The Open Source DocuSign Alternative.
TypeScript digital-signaturedocument-signingdocusign-alternativee-signatureesignesignaturenext-authnextjsopen-sourcepades-standardpdfpdf-signpdf-signaturepostgresqlprismaself-hostedsigningtypescript
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
import type { TCscCredentialsInfoResponse } from './client/types';
/**
* CSC QES V1 algorithm policy.
*
* Single OID-to-algorithm map + single helper that:
* - validates cert state (status, validity window) → `CSC_CERT_INVALID`,
* - validates the credential's key + algorithm against the spec's policy
* table (RSA ≥2048, ECDSA P-256/384/521, SHA-256/384/512) →
* `CSC_ALGORITHM_REFUSED`,
* - resolves a concrete `(signAlgo, hashAlgo)` OID pair for §11.9.
*
* Called at the service-scope OAuth callback (validation boundary) and
* re-called at sign time as a defence-in-depth pre-check. Persisted fields
* (`keyType` / `keyLenBits` / `digestAlgorithm` / `signAlgoOid`) round-trip
* through `CscCredential`.
*/
export type CscKeyType = 'RSA' | 'ECDSA';
export type CscDigest = 'SHA-256' | 'SHA-384' | 'SHA-512';
export type CscEcdsaCurve = 'P-256' | 'P-384' | 'P-521';
export type CscAlgorithmPolicy = {
keyType: CscKeyType;
keyLenBits: number;
digestAlgorithm: CscDigest;
/** OID for `signatures/signHash.signAlgo` + persisted on `CscCredential`. */
signAlgoOid: string;
/** OID for `signatures/signHash.hashAlgo`. */
hashAlgoOid: string;
/** ECDSA named curve (informational; not separately persisted). */
ecdsaCurve?: CscEcdsaCurve;
};
/**
* Default RSA digest when the TSP advertises only hash-agnostic RSA OIDs
* (plain `rsaEncryption` / RSASSA-PSS). SHA-256 matches the CSC §11.9
* sample and is universally TSP-supported.
*/
const DEFAULT_RSA_DIGEST: CscDigest = 'SHA-256';
const HASH_OID_FOR_DIGEST: Record<CscDigest, string> = {
'SHA-256': '2.16.840.1.101.3.4.2.1',
'SHA-384': '2.16.840.1.101.3.4.2.2',
'SHA-512': '2.16.840.1.101.3.4.2.3',
};
/**
* Exposed lookup for the `signatures/signHash.hashAlgo` OID corresponding to a
* resolved {@link CscDigest}. Useful at sign time when the policy's
* `hashAlgoOid` field is not in scope (e.g. when reconstructing a
* `LibpdfSignerAlgo` from a persisted `CscCredential` row).
*/
export const hashOidForDigest = (digest: CscDigest): string => HASH_OID_FOR_DIGEST[digest];
const DIGEST_STRENGTH: Record<CscDigest, number> = {
'SHA-256': 256,
'SHA-384': 384,
'SHA-512': 512,
};
const STRONG_DIGEST_SET = new Set<string>(['SHA-256', 'SHA-384', 'SHA-512']);
type AlgoOidInfo = { family: 'RSA' | 'ECDSA'; boundDigest: CscDigest | 'SHA-1' | 'MD5' | null } | { family: 'DSA' };
/**
* Source-of-truth registry for `key.algo` entries (§11.5). Anything not
* listed is treated as unknown and skipped at policy evaluation.
*/
const KEY_ALGO_OID_REGISTRY: Record<string, AlgoOidInfo> = {
// Hash-agnostic RSA — caller picks the hash via `hashAlgo`.
'1.2.840.113549.1.1.1': { family: 'RSA', boundDigest: null }, // rsaEncryption
'1.2.840.113549.1.1.10': { family: 'RSA', boundDigest: null }, // RSASSA-PSS
// Hash-bound legacy RSA combos.
'1.2.840.113549.1.1.4': { family: 'RSA', boundDigest: 'MD5' }, // md5WithRSAEncryption
'1.2.840.113549.1.1.5': { family: 'RSA', boundDigest: 'SHA-1' }, // sha1WithRSAEncryption
'1.2.840.113549.1.1.11': { family: 'RSA', boundDigest: 'SHA-256' }, // sha256WithRSAEncryption
'1.2.840.113549.1.1.12': { family: 'RSA', boundDigest: 'SHA-384' }, // sha384WithRSAEncryption
'1.2.840.113549.1.1.13': { family: 'RSA', boundDigest: 'SHA-512' }, // sha512WithRSAEncryption
// ECDSA with SHA-x (hash is always bound).
'1.2.840.10045.4.1': { family: 'ECDSA', boundDigest: 'SHA-1' }, // ecdsa-with-SHA1
'1.2.840.10045.4.3.2': { family: 'ECDSA', boundDigest: 'SHA-256' },
'1.2.840.10045.4.3.3': { family: 'ECDSA', boundDigest: 'SHA-384' },
'1.2.840.10045.4.3.4': { family: 'ECDSA', boundDigest: 'SHA-512' },
// DSA — refused outright.
'1.2.840.10040.4.1': { family: 'DSA' },
'1.2.840.10040.4.3': { family: 'DSA' }, // dsa-with-SHA1
};
/**
* ECDSA named-curve OID registry. Policy verdict (allow/refuse) is decided
* by the resolver from the resolved curve name, not encoded here.
*/
const CURVE_OID_REGISTRY: Record<string, CscEcdsaCurve | 'P-192' | 'P-224'> = {
'1.2.840.10045.3.1.7': 'P-256', // secp256r1
'1.3.132.0.34': 'P-384', // secp384r1
'1.3.132.0.35': 'P-521', // secp521r1
'1.2.840.10045.3.1.1': 'P-192', // secp192r1
'1.3.132.0.33': 'P-224', // secp224r1
};
/**
* Validate a CSC credential's cert + key/algorithm against V1 policy and
* resolve the `(signAlgo, hashAlgo)` OID pair used by `signatures/signHash`.
*
* Caller MUST fetch the credential with `certInfo: true` so `cert.validFrom`
* / `cert.validTo` are present.
*
* Throws:
* - `CSC_CERT_INVALID` for cert-state issues (status not `valid`, missing or
* malformed validity dates, current time outside the validity window).
* - `CSC_ALGORITHM_REFUSED` for key/algorithm policy failures (disabled key,
* missing `key.len`, RSA `< 2048`, ECDSA without an allowed curve, DSA, no
* acceptable digest advertised in `key.algo`).
*/
export const resolveCscAlgorithmPolicy = (credentialInfo: TCscCredentialsInfoResponse): CscAlgorithmPolicy => {
assertCertValid(credentialInfo.cert);
if (credentialInfo.key.status !== 'enabled') {
throw new AppError(AppErrorCode.CSC_ALGORITHM_REFUSED, {
message: `CSC credential key status is '${credentialInfo.key.status}'.`,
});
}
if (credentialInfo.key.len === undefined) {
throw new AppError(AppErrorCode.CSC_ALGORITHM_REFUSED, {
message: 'CSC credential omits required key.len (REQUIRED per §11.5).',
});
}
const choice = pickAlgorithmChoice(credentialInfo.key.algo);
if (choice.family === 'RSA') {
if (credentialInfo.key.len < 2048) {
throw new AppError(AppErrorCode.CSC_ALGORITHM_REFUSED, {
message: `CSC RSA credential keyLen ${credentialInfo.key.len} < 2048.`,
});
}
return {
keyType: 'RSA',
keyLenBits: credentialInfo.key.len,
digestAlgorithm: choice.digest,
signAlgoOid: choice.signAlgoOid,
hashAlgoOid: HASH_OID_FOR_DIGEST[choice.digest],
};
}
const curve = resolveEcdsaCurve(credentialInfo.key.curve);
return {
keyType: 'ECDSA',
keyLenBits: credentialInfo.key.len,
digestAlgorithm: choice.digest,
signAlgoOid: choice.signAlgoOid,
hashAlgoOid: HASH_OID_FOR_DIGEST[choice.digest],
ecdsaCurve: curve,
};
};
type AlgorithmChoice = {
family: 'RSA' | 'ECDSA';
signAlgoOid: string;
digest: CscDigest;
};
/**
* Iterate the TSP's advertised `key.algo` OIDs, drop the policy-refused
* entries, and pick the strongest survivor.
*
* Precedence: ECDSA before RSA (smaller signatures, modern); within each
* family, strongest advertised digest first. Hash-agnostic RSA OIDs pair
* with {@link DEFAULT_RSA_DIGEST}.
*/
const pickAlgorithmChoice = (algoOids: readonly string[]): AlgorithmChoice => {
const candidates: AlgorithmChoice[] = [];
for (const oid of algoOids) {
const info = KEY_ALGO_OID_REGISTRY[oid];
if (info === undefined) {
// Unknown OID — another entry in `key.algo` may still be acceptable.
continue;
}
if (info.family === 'DSA') {
continue;
}
if (info.boundDigest === null) {
candidates.push({
family: info.family,
signAlgoOid: oid,
digest: DEFAULT_RSA_DIGEST,
});
continue;
}
if (STRONG_DIGEST_SET.has(info.boundDigest)) {
candidates.push({
family: info.family,
signAlgoOid: oid,
digest: info.boundDigest as CscDigest,
});
}
}
if (candidates.length === 0) {
throw new AppError(AppErrorCode.CSC_ALGORITHM_REFUSED, {
message: `CSC credential advertises no policy-compliant key.algo OIDs (got: ${algoOids.join(', ') || '<empty>'}).`,
});
}
candidates.sort((a, b) => {
if (a.family !== b.family) {
return a.family === 'ECDSA' ? -1 : 1;
}
return DIGEST_STRENGTH[b.digest] - DIGEST_STRENGTH[a.digest];
});
return candidates[0];
};
const resolveEcdsaCurve = (curveOid: string | undefined): CscEcdsaCurve => {
if (curveOid === undefined || curveOid === '') {
throw new AppError(AppErrorCode.CSC_ALGORITHM_REFUSED, {
message: 'CSC ECDSA credential omits required key.curve.',
});
}
const named = CURVE_OID_REGISTRY[curveOid];
if (named === 'P-256' || named === 'P-384' || named === 'P-521') {
return named;
}
const detail = named ? `, named=${named}` : '';
throw new AppError(AppErrorCode.CSC_ALGORITHM_REFUSED, {
message: `CSC ECDSA credential uses refused curve (oid=${curveOid}${detail}).`,
});
};
const assertCertValid = (cert: TCscCredentialsInfoResponse['cert']): void => {
if (cert.status !== undefined && cert.status !== 'valid') {
throw new AppError(AppErrorCode.CSC_CERT_INVALID, {
message: `CSC credential certificate status is '${cert.status}'.`,
});
}
if (!cert.validFrom || !cert.validTo) {
throw new AppError(AppErrorCode.CSC_CERT_INVALID, {
message: 'CSC credential certificate omits validFrom/validTo (malformed).',
});
}
const validFromMs = parseGeneralizedTime(cert.validFrom);
const validToMs = parseGeneralizedTime(cert.validTo);
if (validFromMs === null || validToMs === null) {
throw new AppError(AppErrorCode.CSC_CERT_INVALID, {
message: `CSC credential certificate validity dates are malformed (validFrom=${cert.validFrom}, validTo=${cert.validTo}).`,
});
}
const now = Date.now();
if (now < validFromMs) {
throw new AppError(AppErrorCode.CSC_CERT_INVALID, {
message: `CSC credential certificate is not yet valid (validFrom=${cert.validFrom}).`,
});
}
if (now > validToMs) {
throw new AppError(AppErrorCode.CSC_CERT_INVALID, {
message: `CSC credential certificate has expired (validTo=${cert.validTo}).`,
});
}
};
/**
* Parse an X.509 GeneralizedTime string (`YYYYMMDDHHMMSSZ`) into epoch ms.
* Strict — returns null on any deviation from the §11.5 example format.
*/
const parseGeneralizedTime = (value: string): number | null => {
const matched = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})Z$/.exec(value);
if (matched === null) {
return null;
}
const [, y, mo, d, h, mi, s] = matched;
const ms = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s));
return Number.isNaN(ms) ? null : ms;
};
/**
* Subset of libpdf's `Signer` interface fields derived from a `CscAlgorithmPolicy`.
* Used by `CscCaptureSigner` / `CscFifoSigner` to satisfy libpdf's signer
* contract without re-deriving the mapping at each call site. `keyLenBits`
* is carried through so the capture-signer can size its placeholder output
* appropriately for the chosen key.
*/
export type LibpdfSignerAlgo = {
keyType: 'RSA' | 'EC';
signatureAlgorithm: 'RSASSA-PKCS1-v1_5' | 'RSA-PSS' | 'ECDSA';
digestAlgorithm: CscDigest;
keyLenBits: number;
};
/**
* Translate a `CscAlgorithmPolicy` (CSC §11.5 OIDs) into libpdf's `Signer`
* algorithm tuple. RSASSA-PSS is detected by the `signAlgoOid`; everything
* else maps directly from `keyType` + `digestAlgorithm`.
*/
export const policyToLibpdfSignerAlgo = (policy: CscAlgorithmPolicy): LibpdfSignerAlgo => {
if (policy.keyType === 'ECDSA') {
return {
keyType: 'EC',
signatureAlgorithm: 'ECDSA',
digestAlgorithm: policy.digestAlgorithm,
keyLenBits: policy.keyLenBits,
};
}
// RSA — distinguish PKCS1-v1.5 from PSS by the resolved sign-algo OID.
// RSASSA-PSS OID: '1.2.840.113549.1.1.10'.
const signatureAlgorithm: 'RSASSA-PKCS1-v1_5' | 'RSA-PSS' =
policy.signAlgoOid === '1.2.840.113549.1.1.10' ? 'RSA-PSS' : 'RSASSA-PKCS1-v1_5';
return {
keyType: 'RSA',
signatureAlgorithm,
digestAlgorithm: policy.digestAlgorithm,
keyLenBits: policy.keyLenBits,
};
};