mirror of
https://github.com/documenso/documenso.git
synced 2026-07-25 01:15:49 +10:00
Merge branch 'main' into fix/update-stripe-team-member-billing
This commit is contained in:
David Nguyen
@@ -16,6 +16,8 @@
|
||||
"@aws-sdk/client-sesv2": "^3.998.0",
|
||||
"@documenso/lib": "*",
|
||||
"@documenso/prisma": "*",
|
||||
"arctic": "^3.7.0",
|
||||
"hono": "^4.12.14",
|
||||
"luxon": "^3.7.2",
|
||||
"react": "^18",
|
||||
"ts-pattern": "^5.9.0",
|
||||
|
||||
@@ -0,0 +1,347 @@
|
||||
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,
|
||||
};
|
||||
};
|
||||
@@ -0,0 +1,122 @@
|
||||
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
|
||||
/**
|
||||
* Length-prefixed X.509 chain for `CscCredential.certCache`. Schema column is
|
||||
* `Bytes`; this gives a self-describing binary that round-trips without
|
||||
* base64 inflation. Format: u32 BE cert count, then per-cert u32 BE byte
|
||||
* length + raw DER bytes.
|
||||
*
|
||||
* Encoding inputs come from `cscCredentialsInfo.cert.certificates`, which the
|
||||
* CSC §11.5 spec defines as an array of base64-encoded DER X.509 certificates
|
||||
* (leaf-first). The encoder decodes each base64 entry once at persistence
|
||||
* time; the decoder is the symmetric inverse used at sign time.
|
||||
*
|
||||
* Pure functions, no I/O.
|
||||
*/
|
||||
|
||||
const BASE64_REGEX = /^[A-Za-z0-9+/]+={0,2}$/;
|
||||
|
||||
/**
|
||||
* Encode a leaf-first chain of base64-encoded DER certs into the
|
||||
* length-prefixed binary form persisted on `CscCredential.certCache`.
|
||||
*
|
||||
* Throws `INVALID_REQUEST` when the input is empty or any entry is not valid
|
||||
* base64.
|
||||
*/
|
||||
export const encodeCscCertChain = (certs: string[]): Uint8Array => {
|
||||
if (certs.length === 0) {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: 'CSC certificate chain encoding requires at least one certificate.',
|
||||
});
|
||||
}
|
||||
|
||||
const derBuffers: Uint8Array[] = [];
|
||||
let totalDerBytes = 0;
|
||||
|
||||
for (const entry of certs) {
|
||||
if (entry.length === 0 || !BASE64_REGEX.test(entry)) {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: 'CSC certificate chain entry is not valid base64.',
|
||||
});
|
||||
}
|
||||
|
||||
const der = Buffer.from(entry, 'base64');
|
||||
|
||||
if (der.length === 0) {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: 'CSC certificate chain entry decoded to zero bytes.',
|
||||
});
|
||||
}
|
||||
|
||||
derBuffers.push(der);
|
||||
totalDerBytes += der.length;
|
||||
}
|
||||
|
||||
// 4 bytes for the count + 4 bytes per-cert length prefix + raw DER bytes.
|
||||
const totalLength = 4 + derBuffers.length * 4 + totalDerBytes;
|
||||
const out = new Uint8Array(totalLength);
|
||||
const view = new DataView(out.buffer, out.byteOffset, out.byteLength);
|
||||
|
||||
view.setUint32(0, derBuffers.length, false);
|
||||
|
||||
let offset = 4;
|
||||
|
||||
for (const der of derBuffers) {
|
||||
view.setUint32(offset, der.length, false);
|
||||
offset += 4;
|
||||
out.set(der, offset);
|
||||
offset += der.length;
|
||||
}
|
||||
|
||||
return out;
|
||||
};
|
||||
|
||||
/**
|
||||
* Decode a length-prefixed cert chain back into an array of DER cert byte
|
||||
* arrays. Inverse of {@link encodeCscCertChain}.
|
||||
*
|
||||
* Throws `INVALID_REQUEST` when the buffer is truncated or any per-cert
|
||||
* length prefix runs off the end of the buffer.
|
||||
*/
|
||||
export const decodeCscCertChain = (bytes: Uint8Array): Uint8Array[] => {
|
||||
if (bytes.byteLength < 4) {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: 'CSC certificate chain buffer is too short to contain a count prefix.',
|
||||
});
|
||||
}
|
||||
|
||||
const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
|
||||
const count = view.getUint32(0, false);
|
||||
|
||||
const result: Uint8Array[] = [];
|
||||
let offset = 4;
|
||||
|
||||
for (let i = 0; i < count; i++) {
|
||||
if (offset + 4 > bytes.byteLength) {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: 'CSC certificate chain buffer truncated at length prefix.',
|
||||
});
|
||||
}
|
||||
|
||||
const length = view.getUint32(offset, false);
|
||||
offset += 4;
|
||||
|
||||
if (length === 0 || offset + length > bytes.byteLength) {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: 'CSC certificate chain buffer truncated within certificate body.',
|
||||
});
|
||||
}
|
||||
|
||||
// Slice copies the underlying bytes so callers can't mutate the source.
|
||||
result.push(bytes.slice(offset, offset + length));
|
||||
offset += length;
|
||||
}
|
||||
|
||||
if (offset !== bytes.byteLength) {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: 'CSC certificate chain buffer has trailing bytes after declared chain end.',
|
||||
});
|
||||
}
|
||||
|
||||
return result;
|
||||
};
|
||||
@@ -0,0 +1,51 @@
|
||||
import { symmetricDecrypt, symmetricEncrypt } from '@documenso/lib/universal/crypto';
|
||||
import { requireEnv } from '@documenso/lib/utils/env';
|
||||
import { bytesToHex, hexToBytes } from '@noble/ciphers/utils';
|
||||
|
||||
/**
|
||||
* Bytes-based wrappers around {@link symmetricEncrypt} / {@link symmetricDecrypt}
|
||||
* for the two CSC secrets stored on Prisma `Bytes` columns:
|
||||
*
|
||||
* - `CscCredential.serviceTokenCiphertext` — service-scope OAuth access token.
|
||||
* - `CscSession.encryptedSad` — credential-scope SAD.
|
||||
*
|
||||
* Both use the primary `DOCUMENSO_ENCRYPTION_KEY` (same key family as 2FA
|
||||
* secrets, OIDC client secrets, DKIM private keys). The underlying cipher
|
||||
* returns hex; we round-trip through `bytesToHex` / `hexToBytes` so the
|
||||
* persisted bytes are the raw XChaCha20-Poly1305 ciphertext (nonce + tag +
|
||||
* payload), not a hex-string-as-bytes inflation.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Encrypt a CSC plaintext secret (service token or SAD) for persistence.
|
||||
* Throws `MISSING_ENV_VAR` on missing encryption key — encryption can't
|
||||
* otherwise fail.
|
||||
*/
|
||||
export const encryptCscToken = (plaintext: string): Uint8Array => {
|
||||
const key = requireEnv('NEXT_PRIVATE_ENCRYPTION_KEY');
|
||||
|
||||
const hex = symmetricEncrypt({ key, data: plaintext });
|
||||
|
||||
return hexToBytes(hex);
|
||||
};
|
||||
|
||||
/**
|
||||
* Decrypt a CSC ciphertext back to its UTF-8 plaintext. Returns `null` on
|
||||
* any cipher-level failure (key rotation, payload tamper, row corruption)
|
||||
* so the caller can map to a domain-appropriate AppError — typically
|
||||
* re-auth for service tokens, `CSC_SAD_EXPIRED_PRE_SIGN` for SADs.
|
||||
*
|
||||
* A missing key throws (config error, must surface loudly) and is *not*
|
||||
* folded into the null return.
|
||||
*/
|
||||
export const decryptCscToken = (ciphertext: Uint8Array): string | null => {
|
||||
const key = requireEnv('NEXT_PRIVATE_ENCRYPTION_KEY');
|
||||
|
||||
try {
|
||||
const buf = symmetricDecrypt({ key, data: bytesToHex(ciphertext) });
|
||||
|
||||
return Buffer.from(buf).toString('utf-8');
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
};
|
||||
@@ -0,0 +1,122 @@
|
||||
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
|
||||
import { cscJsonPost, joinCscUrl } from './http';
|
||||
import {
|
||||
type TCscCredentialsInfoRequest,
|
||||
type TCscCredentialsInfoResponse,
|
||||
type TCscCredentialsListRequest,
|
||||
type TCscCredentialsListResponse,
|
||||
ZCscCredentialsInfoResponseSchema,
|
||||
ZCscCredentialsListResponseSchema,
|
||||
} from './types';
|
||||
|
||||
type CscCredentialsListOptions = TCscCredentialsListRequest & {
|
||||
baseUrl: string;
|
||||
/** Service-scope bearer token (CSC §11.4 + §11.9). */
|
||||
accessToken: string;
|
||||
signal?: AbortSignal;
|
||||
};
|
||||
|
||||
/**
|
||||
* `credentials/list` (§11.4) — list the credentialIDs the bearer token's user
|
||||
* owns at the TSP.
|
||||
*
|
||||
* Throws `CSC_CREDENTIAL_LIST_EMPTY` when the TSP returns a successful
|
||||
* response with zero credentials — the recipient needs to enrol with the TSP
|
||||
* before they can sign. Other failures throw `CSC_REQUEST_FAILED`.
|
||||
*
|
||||
* `userID` MUST be omitted when the service authorization is user-specific
|
||||
* (true for OAuth `service` scope, which is V1's only flow). The spec rejects
|
||||
* the call with `invalid_request` if both are present.
|
||||
*/
|
||||
export const cscCredentialsList = async (opts: CscCredentialsListOptions): Promise<TCscCredentialsListResponse> => {
|
||||
const { baseUrl, accessToken, signal, userID, maxResults, pageToken, clientData } = opts;
|
||||
|
||||
const body: Record<string, unknown> = {};
|
||||
|
||||
if (userID !== undefined) {
|
||||
body.userID = userID;
|
||||
}
|
||||
|
||||
if (maxResults !== undefined) {
|
||||
body.maxResults = maxResults;
|
||||
}
|
||||
|
||||
if (pageToken !== undefined) {
|
||||
body.pageToken = pageToken;
|
||||
}
|
||||
|
||||
if (clientData !== undefined) {
|
||||
body.clientData = clientData;
|
||||
}
|
||||
|
||||
const response = await cscJsonPost(
|
||||
{
|
||||
url: joinCscUrl({ baseUrl, path: 'credentials/list' }),
|
||||
body,
|
||||
accessToken,
|
||||
signal,
|
||||
},
|
||||
ZCscCredentialsListResponseSchema,
|
||||
);
|
||||
|
||||
if (response.credentialIDs.length === 0) {
|
||||
throw new AppError(AppErrorCode.CSC_CREDENTIAL_LIST_EMPTY, {
|
||||
message:
|
||||
'CSC provider returned no credentials for the authenticated user. Recipient must enrol with the TSP before signing.',
|
||||
});
|
||||
}
|
||||
|
||||
return response;
|
||||
};
|
||||
|
||||
type CscCredentialsInfoOptions = TCscCredentialsInfoRequest & {
|
||||
baseUrl: string;
|
||||
/** Service-scope bearer token. */
|
||||
accessToken: string;
|
||||
signal?: AbortSignal;
|
||||
};
|
||||
|
||||
/**
|
||||
* `credentials/info` (§11.5) — fetch credential metadata: key algorithm tuple,
|
||||
* X.509 certificate chain, authorization mode, multisign capacity.
|
||||
*
|
||||
* Returns the parsed response verbatim. Cert validity, algorithm policy, and
|
||||
* SCAL semantics are enforced by `csc/algorithm-resolver.ts` — that lives
|
||||
* outside the client because it's domain logic, not transport.
|
||||
*/
|
||||
export const cscCredentialsInfo = async (opts: CscCredentialsInfoOptions): Promise<TCscCredentialsInfoResponse> => {
|
||||
const { baseUrl, accessToken, signal, credentialID, certificates, certInfo, authInfo, lang, clientData } = opts;
|
||||
|
||||
const body: Record<string, unknown> = { credentialID };
|
||||
|
||||
if (certificates !== undefined) {
|
||||
body.certificates = certificates;
|
||||
}
|
||||
|
||||
if (certInfo !== undefined) {
|
||||
body.certInfo = certInfo;
|
||||
}
|
||||
|
||||
if (authInfo !== undefined) {
|
||||
body.authInfo = authInfo;
|
||||
}
|
||||
|
||||
if (lang !== undefined) {
|
||||
body.lang = lang;
|
||||
}
|
||||
|
||||
if (clientData !== undefined) {
|
||||
body.clientData = clientData;
|
||||
}
|
||||
|
||||
return await cscJsonPost(
|
||||
{
|
||||
url: joinCscUrl({ baseUrl, path: 'credentials/info' }),
|
||||
body,
|
||||
accessToken,
|
||||
signal,
|
||||
},
|
||||
ZCscCredentialsInfoResponseSchema,
|
||||
);
|
||||
};
|
||||
@@ -0,0 +1,170 @@
|
||||
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
import type { z } from 'zod';
|
||||
|
||||
import { ZCscErrorResponseSchema } from './types';
|
||||
|
||||
const LEADING_SLASHES_REGEX = /^\/+/;
|
||||
const TRAILING_SLASHES_REGEX = /\/+$/;
|
||||
|
||||
/**
|
||||
* Low-level fetch wrapper for the JSON-bodied CSC API methods (§7.1 mandates
|
||||
* `Content-Type: application/json` for all API requests).
|
||||
*
|
||||
* OAuth 2.0 endpoints (`oauth2/token`, `oauth2/revoke`) use
|
||||
* `application/x-www-form-urlencoded` per RFC 6749 and are handled by the
|
||||
* `arctic` library — see `oauth.ts` in this directory.
|
||||
*
|
||||
* Normalises CSC error responses (§10.1: `{ error, error_description }`)
|
||||
* into {@link AppError}s carrying the upstream HTTP status in
|
||||
* {@link AppError.statusCode}, so callers can discriminate without
|
||||
* re-parsing the body.
|
||||
*/
|
||||
|
||||
type JoinUrlInput = {
|
||||
baseUrl: string;
|
||||
path: string;
|
||||
};
|
||||
|
||||
/**
|
||||
* Join a CSC base URL with a path segment. Strips trailing/leading slashes so
|
||||
* `joinCscUrl({ baseUrl: 'https://x/csc/v1/', path: '/credentials/list' })`
|
||||
* yields `https://x/csc/v1/credentials/list`.
|
||||
*/
|
||||
export const joinCscUrl = ({ baseUrl, path }: JoinUrlInput): string => {
|
||||
const cleanBaseUrl = baseUrl.replace(TRAILING_SLASHES_REGEX, ''); // Strip trailing slashes from base URL.
|
||||
const cleanPath = path.replace(LEADING_SLASHES_REGEX, ''); // Strip leading slashes from path.
|
||||
|
||||
const url = new URL(cleanPath, `${cleanBaseUrl}/`);
|
||||
|
||||
return url.toString();
|
||||
};
|
||||
|
||||
type CscRequestErrorOptions = {
|
||||
url: string;
|
||||
status: number;
|
||||
cscError?: { error: string; error_description?: string };
|
||||
cause?: unknown;
|
||||
errorCode?: string;
|
||||
};
|
||||
|
||||
const buildCscRequestError = ({
|
||||
url,
|
||||
status,
|
||||
cscError,
|
||||
cause,
|
||||
errorCode = AppErrorCode.CSC_REQUEST_FAILED,
|
||||
}: CscRequestErrorOptions): AppError => {
|
||||
const causeMessage = cause instanceof Error ? cause.message : undefined;
|
||||
|
||||
const parts: string[] = [`CSC request to ${url} failed (HTTP ${status})`];
|
||||
|
||||
if (cscError) {
|
||||
parts.push(cscError.error_description ? `${cscError.error}: ${cscError.error_description}` : cscError.error);
|
||||
}
|
||||
|
||||
if (causeMessage) {
|
||||
parts.push(causeMessage);
|
||||
}
|
||||
|
||||
return new AppError(errorCode, {
|
||||
message: parts.join(' — '),
|
||||
statusCode: status,
|
||||
});
|
||||
};
|
||||
|
||||
/**
|
||||
* Best-effort parse of a CSC error body. Returns `undefined` on non-JSON or
|
||||
* schema mismatch so the caller still surfaces the HTTP status without
|
||||
* masking it.
|
||||
*/
|
||||
const readCscErrorBody = async (
|
||||
response: Response,
|
||||
): Promise<{ error: string; error_description?: string } | undefined> => {
|
||||
try {
|
||||
const json = await response.json();
|
||||
const parsed = ZCscErrorResponseSchema.safeParse(json);
|
||||
|
||||
return parsed.success ? parsed.data : undefined;
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
};
|
||||
|
||||
type CscJsonPostOptions = {
|
||||
/** Fully-qualified endpoint URL (use {@link joinCscUrl} to build it). */
|
||||
url: string;
|
||||
/** Decoded JSON body; serialised via `JSON.stringify`. */
|
||||
body: Record<string, unknown>;
|
||||
/** Bearer access token. Omit for unauthenticated calls (e.g. `info`). */
|
||||
accessToken?: string;
|
||||
/** Override the AppError code thrown on failure. Defaults to `CSC_REQUEST_FAILED`. */
|
||||
errorCode?: string;
|
||||
/**
|
||||
* Optional `AbortSignal` so callers can enforce their own deadlines
|
||||
* (e.g. the 15s sign-time sync timeout).
|
||||
*/
|
||||
signal?: AbortSignal;
|
||||
};
|
||||
|
||||
/**
|
||||
* POST a JSON body to a CSC API endpoint and parse the response against the
|
||||
* supplied Zod schema.
|
||||
*
|
||||
* Throws {@link AppError} on:
|
||||
* - network/transport error (fetch threw)
|
||||
* - non-2xx HTTP response (with CSC error body folded into the message)
|
||||
* - malformed JSON response
|
||||
* - schema validation failure
|
||||
*/
|
||||
export const cscJsonPost = async <T>(opts: CscJsonPostOptions, responseSchema: z.ZodSchema<T>): Promise<T> => {
|
||||
const { url, body, accessToken, errorCode, signal } = opts;
|
||||
|
||||
let response: Response;
|
||||
|
||||
try {
|
||||
response = await fetch(url, {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
Accept: 'application/json',
|
||||
...(accessToken ? { Authorization: `Bearer ${accessToken}` } : {}),
|
||||
},
|
||||
body: JSON.stringify(body),
|
||||
signal,
|
||||
});
|
||||
} catch (cause) {
|
||||
throw buildCscRequestError({ url, status: 0, cause, errorCode });
|
||||
}
|
||||
|
||||
if (!response.ok) {
|
||||
const cscError = await readCscErrorBody(response);
|
||||
|
||||
throw buildCscRequestError({
|
||||
url,
|
||||
status: response.status,
|
||||
cscError,
|
||||
errorCode,
|
||||
});
|
||||
}
|
||||
|
||||
let json: unknown;
|
||||
|
||||
try {
|
||||
json = await response.json();
|
||||
} catch (cause) {
|
||||
throw buildCscRequestError({ url, status: response.status, cause, errorCode });
|
||||
}
|
||||
|
||||
const parsed = responseSchema.safeParse(json);
|
||||
|
||||
if (!parsed.success) {
|
||||
throw buildCscRequestError({
|
||||
url,
|
||||
status: response.status,
|
||||
cause: parsed.error,
|
||||
errorCode,
|
||||
});
|
||||
}
|
||||
|
||||
return parsed.data;
|
||||
};
|
||||
@@ -0,0 +1,32 @@
|
||||
/**
|
||||
* CSC v1.0.4.0 HTTP client. Stateless function wrappers — one per endpoint,
|
||||
* grouped by spec section. Bring your own base URL(s) and bearer token.
|
||||
*
|
||||
* Endpoint coverage (V1 scope):
|
||||
* - §11.1 info → {@link cscInfo}
|
||||
* - §11.4 credentials/list → {@link cscCredentialsList}
|
||||
* - §11.5 credentials/info → {@link cscCredentialsInfo}
|
||||
* - §11.9 signatures/signHash → {@link cscSignHash}
|
||||
* - §11.10 signatures/timestamp → {@link cscTimestamp}
|
||||
* - §8.3.2 oauth2/authorize → {@link buildCscServiceScopeAuthorizeUrl},
|
||||
* {@link buildCscCredentialScopeAuthorizeUrl}
|
||||
* - §8.3.3 oauth2/token → {@link exchangeCscAuthorizationCode},
|
||||
* {@link refreshCscServiceToken}
|
||||
* - §8.3.4 oauth2/revoke → {@link revokeCscToken}
|
||||
*
|
||||
* Out of scope for V1 (intentionally excluded; we use OAuth + single-sig):
|
||||
* - §11.2 auth/login (HTTP Basic)
|
||||
* - §11.3 auth/revoke (HTTP Basic)
|
||||
* - §11.6 credentials/authorize (alternative to OAuth credential scope)
|
||||
* - §11.7 credentials/extendTransaction
|
||||
* - §11.8 credentials/sendOTP
|
||||
*
|
||||
* OAuth is delegated to `arctic` (same library `packages/auth/` uses).
|
||||
*/
|
||||
|
||||
export * from './credentials';
|
||||
export * from './http';
|
||||
export * from './info';
|
||||
export * from './oauth';
|
||||
export * from './signatures';
|
||||
export * from './types';
|
||||
@@ -0,0 +1,42 @@
|
||||
import { AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
|
||||
import { cscJsonPost, joinCscUrl } from './http';
|
||||
import { type TCscInfoRequest, type TCscInfoResponse, ZCscInfoResponseSchema } from './types';
|
||||
|
||||
type CscInfoOptions = TCscInfoRequest & {
|
||||
/**
|
||||
* Base URI of the CSC service (e.g. `https://service.example.org/csc/v1`).
|
||||
* Per §7.2, `info` is mounted relative to the service base URI; the OAuth
|
||||
* base URI returned in `oauth2` is discovered from this call.
|
||||
*/
|
||||
baseUrl: string;
|
||||
signal?: AbortSignal;
|
||||
};
|
||||
|
||||
/**
|
||||
* `info` (§11.1) — discovery method every CSC-conformant TSP MUST implement.
|
||||
*
|
||||
* Used at startup to:
|
||||
*
|
||||
* 1. Learn the OAuth 2.0 base URI (`oauth2`) for subsequent token / revoke
|
||||
* calls. Per §11.1, this MAY differ from the API base URI.
|
||||
* 2. Enumerate supported methods (`methods`) so the caller can fail fast
|
||||
* when a required endpoint is absent.
|
||||
* 3. Surface `signatures/timestamp` capability for the B-LTA seal step.
|
||||
*
|
||||
* Unauthenticated — `info` requires no bearer token. Failures throw
|
||||
* `CSC_PROVIDER_INFO_FAILED` per the spec's startup-discovery error code.
|
||||
*/
|
||||
export const cscInfo = async (opts: CscInfoOptions): Promise<TCscInfoResponse> => {
|
||||
const { baseUrl, lang, signal } = opts;
|
||||
|
||||
return await cscJsonPost(
|
||||
{
|
||||
url: joinCscUrl({ baseUrl, path: 'info' }),
|
||||
body: lang ? { lang } : {},
|
||||
errorCode: AppErrorCode.CSC_PROVIDER_INFO_FAILED,
|
||||
signal,
|
||||
},
|
||||
ZCscInfoResponseSchema,
|
||||
);
|
||||
};
|
||||
@@ -0,0 +1,321 @@
|
||||
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
import {
|
||||
ArcticFetchError,
|
||||
CodeChallengeMethod,
|
||||
generateCodeVerifier,
|
||||
generateState,
|
||||
OAuth2Client,
|
||||
OAuth2RequestError,
|
||||
type OAuth2Tokens,
|
||||
UnexpectedErrorResponseBodyError,
|
||||
UnexpectedResponseError,
|
||||
} from 'arctic';
|
||||
|
||||
import { joinCscUrl } from './http';
|
||||
|
||||
/**
|
||||
* OAuth 2.0 surface for the CSC v1.0.4.0 protocol (§8.3.2 authorize,
|
||||
* §8.3.3 token, §8.3.4 revoke).
|
||||
*
|
||||
* Backed by `arctic` — the same library `packages/auth/` uses for sign-in
|
||||
* OAuth — so PKCE + state generation, token parsing, and revocation share a
|
||||
* proven implementation. CSC-specific extension parameters (`credentialID`,
|
||||
* `numSignatures`, `hash`, `description`, `account_token`, `clientData`,
|
||||
* `lang` — §8.3.2) layer on top of the returned `URL` via
|
||||
* `searchParams.set()`.
|
||||
*
|
||||
* Non-standard CSC bits arctic doesn't model directly:
|
||||
* - `token_type === 'SAD'` for credential-scope responses (§8.3.3). Read from
|
||||
* `tokens.tokenType()` which sources from raw `data`.
|
||||
* - SAD is single-use and short-lived per spec; no refresh_token is issued
|
||||
* for the credential scope. Callers SHOULD NOT call `refreshAccessToken`
|
||||
* with a SAD.
|
||||
*
|
||||
* Re-exports `generateState` and `generateCodeVerifier` for callers that
|
||||
* persist these in the OAuth-flow cookie.
|
||||
*/
|
||||
|
||||
export { generateCodeVerifier, generateState };
|
||||
|
||||
// ─── Client construction ─────────────────────────────────────────────────────
|
||||
|
||||
type CreateCscOAuthClientOptions = {
|
||||
clientId: string;
|
||||
clientSecret: string;
|
||||
redirectUri: string;
|
||||
};
|
||||
|
||||
/**
|
||||
* Construct an `OAuth2Client` bound to the CSC TSP's OAuth registration. The
|
||||
* three values come from the env (`NEXT_PRIVATE_SIGNING_CSC_OAUTH_*`).
|
||||
* Stateless — instantiate per request or cache at the transport singleton
|
||||
* level; arctic's client carries no per-call state.
|
||||
*/
|
||||
export const createCscOAuthClient = ({
|
||||
clientId,
|
||||
clientSecret,
|
||||
redirectUri,
|
||||
}: CreateCscOAuthClientOptions): OAuth2Client => {
|
||||
return new OAuth2Client(clientId, clientSecret, redirectUri);
|
||||
};
|
||||
|
||||
// ─── Authorize URL builders (§8.3.2) ─────────────────────────────────────────
|
||||
|
||||
type AuthorizeUrlBaseOptions = {
|
||||
client: OAuth2Client;
|
||||
/**
|
||||
* The TSP's OAuth base URI as returned by `info.oauth2` (§11.1). The
|
||||
* `oauth2/authorize` path is joined on; per §8.3.2 NOTE 1 this can live on
|
||||
* a different host from the API base URI.
|
||||
*/
|
||||
oauthBaseUrl: string;
|
||||
/** Opaque CSRF token; see {@link generateState}. Caller persists it. */
|
||||
state: string;
|
||||
/** PKCE verifier; see {@link generateCodeVerifier}. Caller persists it. */
|
||||
codeVerifier: string;
|
||||
/** Preferred response language (§11.1 `lang` parameter). */
|
||||
lang?: string;
|
||||
/**
|
||||
* Arbitrary application-defined string echoed back at callback. WARNING per
|
||||
* §8.3.2: this is forwarded verbatim to the TSP; never put secrets here.
|
||||
*/
|
||||
clientData?: string;
|
||||
};
|
||||
|
||||
const applyCscAuthorizeExtras = (url: URL, opts: { lang?: string; clientData?: string }): URL => {
|
||||
if (opts.lang) {
|
||||
url.searchParams.set('lang', opts.lang);
|
||||
}
|
||||
|
||||
if (opts.clientData) {
|
||||
url.searchParams.set('clientData', opts.clientData);
|
||||
}
|
||||
|
||||
return url;
|
||||
};
|
||||
|
||||
/**
|
||||
* Build the `oauth2/authorize` URL for the **service** scope. Recipient
|
||||
* follows this URL to authenticate at the TSP and grant access to list
|
||||
* credentials + fetch credential info.
|
||||
*/
|
||||
export const buildCscServiceScopeAuthorizeUrl = (opts: AuthorizeUrlBaseOptions): URL => {
|
||||
const { client, oauthBaseUrl, state, codeVerifier, lang, clientData } = opts;
|
||||
|
||||
const url = client.createAuthorizationURLWithPKCE(
|
||||
joinCscUrl({ baseUrl: oauthBaseUrl, path: 'oauth2/authorize' }),
|
||||
state,
|
||||
CodeChallengeMethod.S256,
|
||||
codeVerifier,
|
||||
['service'],
|
||||
);
|
||||
|
||||
return applyCscAuthorizeExtras(url, { lang, clientData });
|
||||
};
|
||||
|
||||
type CredentialScopeAuthorizeOptions = AuthorizeUrlBaseOptions & {
|
||||
/** Target credential (§8.3.2 — REQUIRED for credential scope). */
|
||||
credentialId: string;
|
||||
/** Number of signatures this SAD will authorise (§8.3.2 — REQUIRED). */
|
||||
numSignatures: number;
|
||||
/**
|
||||
* Standard-base64-encoded hash values the SAD will be bound to. REQUIRED for
|
||||
* SCAL2 credentials (§8.3.2). The builder converts each value to base64url
|
||||
* before joining with `,` per the spec — §8.3.2 mandates base64url for the
|
||||
* `hash` URL parameter, but the rest of the codebase (and the
|
||||
* `signatures/signHash` JSON body per §11.9) uses standard base64. Callers
|
||||
* pass what `Buffer.from(...).toString('base64')` produces.
|
||||
*/
|
||||
hashes: string[];
|
||||
/** Human-readable transaction description shown on the TSP's SCA page. */
|
||||
description?: string;
|
||||
/** Optional restricted-access token (JWT) some TSPs require (§8.3.2). */
|
||||
accountToken?: string;
|
||||
};
|
||||
|
||||
/**
|
||||
* Convert a standard-base64 string to base64url (RFC 4648 §5). The CSC §8.3.2
|
||||
* `hash` URL parameter requires base64url; TSPs reject standard base64 even
|
||||
* after percent-decoding because `+`, `/`, and `=` are invalid base64url
|
||||
* characters. JSON-body fields (§11.9 `signatures/signHash`) keep standard
|
||||
* base64.
|
||||
*/
|
||||
const toBase64Url = (standardBase64: string): string =>
|
||||
standardBase64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
|
||||
|
||||
/**
|
||||
* Build the `oauth2/authorize` URL for the **credential** scope. The TSP
|
||||
* binds the issued SAD to `hashes` so it can only sign those exact digests.
|
||||
*
|
||||
* Hash ordering in the SAD is independent of the order passed to
|
||||
* `signatures/signHash` (§8.3.2) — the TSP matches by hash value, not
|
||||
* position.
|
||||
*/
|
||||
export const buildCscCredentialScopeAuthorizeUrl = (opts: CredentialScopeAuthorizeOptions): URL => {
|
||||
const {
|
||||
client,
|
||||
oauthBaseUrl,
|
||||
state,
|
||||
codeVerifier,
|
||||
credentialId,
|
||||
numSignatures,
|
||||
hashes,
|
||||
description,
|
||||
accountToken,
|
||||
lang,
|
||||
clientData,
|
||||
} = opts;
|
||||
|
||||
const url = client.createAuthorizationURLWithPKCE(
|
||||
joinCscUrl({ baseUrl: oauthBaseUrl, path: 'oauth2/authorize' }),
|
||||
state,
|
||||
CodeChallengeMethod.S256,
|
||||
codeVerifier,
|
||||
['credential'],
|
||||
);
|
||||
|
||||
url.searchParams.set('credentialID', credentialId);
|
||||
url.searchParams.set('numSignatures', String(numSignatures));
|
||||
url.searchParams.set('hash', hashes.map(toBase64Url).join(','));
|
||||
|
||||
if (description) {
|
||||
url.searchParams.set('description', description);
|
||||
}
|
||||
|
||||
if (accountToken) {
|
||||
url.searchParams.set('account_token', accountToken);
|
||||
}
|
||||
|
||||
return applyCscAuthorizeExtras(url, { lang, clientData });
|
||||
};
|
||||
|
||||
// ─── Token exchange (§8.3.3) ─────────────────────────────────────────────────
|
||||
|
||||
type ExchangeCodeOptions = {
|
||||
client: OAuth2Client;
|
||||
/** OAuth base URI from `info.oauth2`. `oauth2/token` is joined on. */
|
||||
oauthBaseUrl: string;
|
||||
/** Authorization code from the callback's `code` query param. */
|
||||
code: string;
|
||||
/** Same PKCE verifier passed to the authorize URL builder. */
|
||||
codeVerifier: string;
|
||||
signal?: AbortSignal;
|
||||
};
|
||||
|
||||
/**
|
||||
* Exchange an authorization code for an access token. Used for both scopes;
|
||||
* the response shape differs only in `token_type`:
|
||||
*
|
||||
* - service scope: `token_type === 'Bearer'`, optional `refresh_token`.
|
||||
* - credential scope: `token_type === 'SAD'`, single-use, no refresh_token.
|
||||
*
|
||||
* Inspect `tokens.tokenType()` (or `tokens.data` for raw access) to
|
||||
* discriminate.
|
||||
*/
|
||||
export const exchangeCscAuthorizationCode = async (opts: ExchangeCodeOptions): Promise<OAuth2Tokens> => {
|
||||
const { client, oauthBaseUrl, code, codeVerifier } = opts;
|
||||
|
||||
try {
|
||||
return await client.validateAuthorizationCode(
|
||||
joinCscUrl({ baseUrl: oauthBaseUrl, path: 'oauth2/token' }),
|
||||
code,
|
||||
codeVerifier,
|
||||
);
|
||||
} catch (err) {
|
||||
throw mapArcticError(err, 'oauth2/token');
|
||||
}
|
||||
};
|
||||
|
||||
type RefreshServiceTokenOptions = {
|
||||
client: OAuth2Client;
|
||||
oauthBaseUrl: string;
|
||||
/** Service-scope refresh token from a prior token exchange. */
|
||||
refreshToken: string;
|
||||
signal?: AbortSignal;
|
||||
};
|
||||
|
||||
/**
|
||||
* Refresh a service-scope access token. Credential-scope SADs are NOT
|
||||
* refreshable per §8.3.3 — only service scope issues refresh tokens.
|
||||
*
|
||||
* Scopes passed as `['service']` to keep the refresh narrow; the TSP may
|
||||
* ignore the scope parameter on refresh per RFC 6749 §6.
|
||||
*/
|
||||
export const refreshCscServiceToken = async (opts: RefreshServiceTokenOptions): Promise<OAuth2Tokens> => {
|
||||
const { client, oauthBaseUrl, refreshToken } = opts;
|
||||
|
||||
try {
|
||||
return await client.refreshAccessToken(joinCscUrl({ baseUrl: oauthBaseUrl, path: 'oauth2/token' }), refreshToken, [
|
||||
'service',
|
||||
]);
|
||||
} catch (err) {
|
||||
throw mapArcticError(err, 'oauth2/token');
|
||||
}
|
||||
};
|
||||
|
||||
// ─── Revoke (§8.3.4) ─────────────────────────────────────────────────────────
|
||||
|
||||
type RevokeTokenOptions = {
|
||||
client: OAuth2Client;
|
||||
oauthBaseUrl: string;
|
||||
/** Access token or refresh token to revoke. */
|
||||
token: string;
|
||||
signal?: AbortSignal;
|
||||
};
|
||||
|
||||
/**
|
||||
* Revoke a CSC OAuth token. Per §8.3.4, revoking a refresh token also
|
||||
* invalidates every access token derived from the same grant; revoking an
|
||||
* access token only invalidates that access token.
|
||||
*
|
||||
* `204 No Content` on success; arctic resolves the promise. Failures
|
||||
* surface as `CSC_REQUEST_FAILED` via {@link mapArcticError}.
|
||||
*/
|
||||
export const revokeCscToken = async (opts: RevokeTokenOptions): Promise<void> => {
|
||||
const { client, oauthBaseUrl, token } = opts;
|
||||
|
||||
try {
|
||||
await client.revokeToken(joinCscUrl({ baseUrl: oauthBaseUrl, path: 'oauth2/revoke' }), token);
|
||||
} catch (err) {
|
||||
throw mapArcticError(err, 'oauth2/revoke');
|
||||
}
|
||||
};
|
||||
|
||||
// ─── Error normalisation ────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* Translate arctic's typed exception hierarchy into AppErrors consistent with
|
||||
* the rest of the CSC client (see http.ts). Preserves the HTTP status when
|
||||
* arctic surfaces it.
|
||||
*/
|
||||
const mapArcticError = (err: unknown, endpoint: string): AppError => {
|
||||
if (err instanceof OAuth2RequestError) {
|
||||
return new AppError(AppErrorCode.CSC_REQUEST_FAILED, {
|
||||
message: `CSC ${endpoint} rejected: ${err.code}${err.description ? ` — ${err.description}` : ''}`,
|
||||
});
|
||||
}
|
||||
|
||||
if (err instanceof ArcticFetchError) {
|
||||
return new AppError(AppErrorCode.CSC_REQUEST_FAILED, {
|
||||
message: `CSC ${endpoint} fetch failed: ${err.message}`,
|
||||
});
|
||||
}
|
||||
|
||||
if (err instanceof UnexpectedResponseError) {
|
||||
return new AppError(AppErrorCode.CSC_REQUEST_FAILED, {
|
||||
message: `CSC ${endpoint} returned unexpected HTTP ${err.status}`,
|
||||
statusCode: err.status,
|
||||
});
|
||||
}
|
||||
|
||||
if (err instanceof UnexpectedErrorResponseBodyError) {
|
||||
return new AppError(AppErrorCode.CSC_REQUEST_FAILED, {
|
||||
message: `CSC ${endpoint} returned HTTP ${err.status} with unparseable body`,
|
||||
statusCode: err.status,
|
||||
});
|
||||
}
|
||||
|
||||
return new AppError(AppErrorCode.CSC_REQUEST_FAILED, {
|
||||
message: `CSC ${endpoint} failed: ${err instanceof Error ? err.message : String(err)}`,
|
||||
});
|
||||
};
|
||||
@@ -0,0 +1,111 @@
|
||||
import { cscJsonPost, joinCscUrl } from './http';
|
||||
import {
|
||||
type TCscSignHashRequest,
|
||||
type TCscSignHashResponse,
|
||||
type TCscTimestampRequest,
|
||||
type TCscTimestampResponse,
|
||||
ZCscSignHashResponseSchema,
|
||||
ZCscTimestampResponseSchema,
|
||||
} from './types';
|
||||
|
||||
type CscSignHashOptions = TCscSignHashRequest & {
|
||||
baseUrl: string;
|
||||
/** Service-scope bearer token. The SAD (in the body) is the credential-scope grant. */
|
||||
accessToken: string;
|
||||
signal?: AbortSignal;
|
||||
};
|
||||
|
||||
/**
|
||||
* `signatures/signHash` (§11.9) — submit one or more pre-computed hashes for
|
||||
* the TSP to sign with the credential identified by `credentialID`.
|
||||
*
|
||||
* Authorisation is two-layered:
|
||||
* - The service-scope bearer token authenticates the API call itself.
|
||||
* - The credential-scope SAD (in the JSON body) authorises the specific
|
||||
* hashes — the TSP rejects with `invalid_request` ("Hash is not authorized
|
||||
* by the SAD") if any hash in the array wasn't bound at SAD issuance.
|
||||
*
|
||||
* The returned `signatures` array is position-ordered with `hash` per §11.9.
|
||||
* Callers SHALL preserve order when mapping responses back to PDF embed
|
||||
* slots (the fifoSigner relies on this).
|
||||
*/
|
||||
export const cscSignHash = async (opts: CscSignHashOptions): Promise<TCscSignHashResponse> => {
|
||||
const { baseUrl, accessToken, signal, credentialID, SAD, hash, hashAlgo, signAlgo, signAlgoParams, clientData } =
|
||||
opts;
|
||||
|
||||
const body: Record<string, unknown> = {
|
||||
credentialID,
|
||||
SAD,
|
||||
hash,
|
||||
signAlgo,
|
||||
};
|
||||
|
||||
if (hashAlgo !== undefined) {
|
||||
body.hashAlgo = hashAlgo;
|
||||
}
|
||||
|
||||
if (signAlgoParams !== undefined) {
|
||||
body.signAlgoParams = signAlgoParams;
|
||||
}
|
||||
|
||||
if (clientData !== undefined) {
|
||||
body.clientData = clientData;
|
||||
}
|
||||
|
||||
return await cscJsonPost(
|
||||
{
|
||||
url: joinCscUrl({ baseUrl, path: 'signatures/signHash' }),
|
||||
body,
|
||||
accessToken,
|
||||
signal,
|
||||
},
|
||||
ZCscSignHashResponseSchema,
|
||||
);
|
||||
};
|
||||
|
||||
type CscTimestampOptions = TCscTimestampRequest & {
|
||||
baseUrl: string;
|
||||
/**
|
||||
* Service-scope bearer token. Per §11.10 the timestamp endpoint may or may
|
||||
* not require auth depending on TSP policy; the spec is silent. We send the
|
||||
* token unconditionally because all known TSPs gate this endpoint.
|
||||
*/
|
||||
accessToken: string;
|
||||
signal?: AbortSignal;
|
||||
};
|
||||
|
||||
/**
|
||||
* `signatures/timestamp` (§11.10) — request an RFC 3161 / RFC 5816 time-stamp
|
||||
* token for a pre-computed hash. Driven by {@link CscTspTimestampAuthority}
|
||||
* at sign time, when {@link resolveCscSignTimeTsa} selects the TSP source
|
||||
* (TSP advertises `signatures/timestamp` in `info.methods`). The bearer is
|
||||
* the current recipient's own service-scope token. Seal-time archival
|
||||
* timestamps do not go through this endpoint — they use the env-configured
|
||||
* RFC 3161 TSA directly.
|
||||
*
|
||||
* If `nonce` is supplied, the TSP MUST round-trip it in the token — we leave
|
||||
* verification to LibPDF / our TSA helper, not this client.
|
||||
*/
|
||||
export const cscTimestamp = async (opts: CscTimestampOptions): Promise<TCscTimestampResponse> => {
|
||||
const { baseUrl, accessToken, signal, hash, hashAlgo, nonce, clientData } = opts;
|
||||
|
||||
const body: Record<string, unknown> = { hash, hashAlgo };
|
||||
|
||||
if (nonce !== undefined) {
|
||||
body.nonce = nonce;
|
||||
}
|
||||
|
||||
if (clientData !== undefined) {
|
||||
body.clientData = clientData;
|
||||
}
|
||||
|
||||
return await cscJsonPost(
|
||||
{
|
||||
url: joinCscUrl({ baseUrl, path: 'signatures/timestamp' }),
|
||||
body,
|
||||
accessToken,
|
||||
signal,
|
||||
},
|
||||
ZCscTimestampResponseSchema,
|
||||
);
|
||||
};
|
||||
@@ -0,0 +1,179 @@
|
||||
import { z } from 'zod';
|
||||
|
||||
/**
|
||||
* Zod schemas + types for every CSC v1.0.4.0 request/response shape the V1
|
||||
* client touches. Field names mirror the spec exactly. Unknown fields are
|
||||
* silently dropped (Zod default `.strip()`); we don't `.passthrough()` to
|
||||
* keep parsed objects narrow.
|
||||
*
|
||||
* Out-of-scope endpoints (`auth/login`, `auth/revoke`, `credentials/authorize`,
|
||||
* `credentials/extendTransaction`, `credentials/sendOTP`) intentionally have
|
||||
* no schemas here — V1 uses OAuth + sequential single-signature flows only.
|
||||
*/
|
||||
|
||||
// ─── §10.1 common error envelope ─────────────────────────────────────────────
|
||||
|
||||
export const ZCscErrorResponseSchema = z.object({
|
||||
error: z.string(),
|
||||
error_description: z.string().optional(),
|
||||
});
|
||||
|
||||
export type TCscErrorResponse = z.infer<typeof ZCscErrorResponseSchema>;
|
||||
|
||||
// ─── §11.1 info ──────────────────────────────────────────────────────────────
|
||||
|
||||
export const ZCscInfoRequestSchema = z.object({
|
||||
lang: z.string().optional(),
|
||||
});
|
||||
|
||||
export type TCscInfoRequest = z.infer<typeof ZCscInfoRequestSchema>;
|
||||
|
||||
export const ZCscInfoResponseSchema = z.object({
|
||||
specs: z.string(),
|
||||
name: z.string(),
|
||||
logo: z.string(),
|
||||
region: z.string(),
|
||||
lang: z.string(),
|
||||
description: z.string(),
|
||||
authType: z.array(z.string()),
|
||||
// REQUIRED Conditional — present when authType includes `oauth2code` /
|
||||
// `oauth2client`, or when any credential supports `oauth2code` authMode.
|
||||
// We always need it for V1, but keeping the schema permissive matches the
|
||||
// spec; absence is detected at the call site.
|
||||
oauth2: z.string().optional(),
|
||||
methods: z.array(z.string()),
|
||||
});
|
||||
|
||||
export type TCscInfoResponse = z.infer<typeof ZCscInfoResponseSchema>;
|
||||
|
||||
// ─── §11.4 credentials/list ──────────────────────────────────────────────────
|
||||
|
||||
export const ZCscCredentialsListRequestSchema = z.object({
|
||||
// OAuth2 user-specific service auth → userID MUST be omitted (§11.4 NOTE 1).
|
||||
userID: z.string().optional(),
|
||||
maxResults: z.number().int().positive().optional(),
|
||||
pageToken: z.string().optional(),
|
||||
clientData: z.string().optional(),
|
||||
});
|
||||
|
||||
export type TCscCredentialsListRequest = z.infer<typeof ZCscCredentialsListRequestSchema>;
|
||||
|
||||
export const ZCscCredentialsListResponseSchema = z.object({
|
||||
credentialIDs: z.array(z.string()),
|
||||
nextPageToken: z.string().optional(),
|
||||
});
|
||||
|
||||
export type TCscCredentialsListResponse = z.infer<typeof ZCscCredentialsListResponseSchema>;
|
||||
|
||||
// ─── §11.5 credentials/info ──────────────────────────────────────────────────
|
||||
|
||||
export const ZCscCredentialsInfoRequestSchema = z.object({
|
||||
credentialID: z.string(),
|
||||
certificates: z.enum(['none', 'single', 'chain']).optional(),
|
||||
certInfo: z.boolean().optional(),
|
||||
authInfo: z.boolean().optional(),
|
||||
lang: z.string().optional(),
|
||||
clientData: z.string().optional(),
|
||||
});
|
||||
|
||||
export type TCscCredentialsInfoRequest = z.infer<typeof ZCscCredentialsInfoRequestSchema>;
|
||||
|
||||
export const ZCscCredentialsInfoKeySchema = z.object({
|
||||
status: z.enum(['enabled', 'disabled']),
|
||||
algo: z.array(z.string()),
|
||||
// REQUIRED per §11.5 but kept optional here so the algorithm-resolver can
|
||||
// surface absence as a typed `CSC_ALGORITHM_REFUSED` (matching the spec's
|
||||
// policy table) instead of a generic transport schema failure.
|
||||
len: z.number().int().positive().optional(),
|
||||
// REQUIRED Conditional for ECDSA per §11.5; absence handled by the resolver.
|
||||
curve: z.string().optional(),
|
||||
});
|
||||
|
||||
export const ZCscCredentialsInfoCertSchema = z.object({
|
||||
status: z.enum(['valid', 'expired', 'revoked', 'suspended']).optional(),
|
||||
certificates: z.array(z.string()).optional(),
|
||||
issuerDN: z.string().optional(),
|
||||
serialNumber: z.string().optional(),
|
||||
subjectDN: z.string().optional(),
|
||||
validFrom: z.string().optional(),
|
||||
validTo: z.string().optional(),
|
||||
});
|
||||
|
||||
export const ZCscCredentialsInfoPinSchema = z.object({
|
||||
presence: z.enum(['true', 'false', 'optional']),
|
||||
format: z.enum(['A', 'N']).optional(),
|
||||
label: z.string().optional(),
|
||||
description: z.string().optional(),
|
||||
});
|
||||
|
||||
export const ZCscCredentialsInfoOtpSchema = z.object({
|
||||
presence: z.enum(['true', 'false', 'optional']),
|
||||
type: z.enum(['offline', 'online']).optional(),
|
||||
format: z.enum(['A', 'N']).optional(),
|
||||
label: z.string().optional(),
|
||||
description: z.string().optional(),
|
||||
ID: z.string().optional(),
|
||||
provider: z.string().optional(),
|
||||
});
|
||||
|
||||
export const ZCscCredentialsInfoResponseSchema = z.object({
|
||||
description: z.string().optional(),
|
||||
key: ZCscCredentialsInfoKeySchema,
|
||||
cert: ZCscCredentialsInfoCertSchema,
|
||||
authMode: z.enum(['implicit', 'explicit', 'oauth2code']),
|
||||
SCAL: z.enum(['1', '2']).optional(),
|
||||
PIN: ZCscCredentialsInfoPinSchema.optional(),
|
||||
OTP: ZCscCredentialsInfoOtpSchema.optional(),
|
||||
multisign: z.number().int().min(1),
|
||||
lang: z.string().optional(),
|
||||
});
|
||||
|
||||
export type TCscCredentialsInfoResponse = z.infer<typeof ZCscCredentialsInfoResponseSchema>;
|
||||
|
||||
// ─── §11.9 signatures/signHash ───────────────────────────────────────────────
|
||||
|
||||
export const ZCscSignHashRequestSchema = z.object({
|
||||
credentialID: z.string(),
|
||||
SAD: z.string(),
|
||||
// Base64-encoded raw message digests.
|
||||
hash: z.array(z.string()).nonempty(),
|
||||
// REQUIRED Conditional — OID of the hash algorithm. Omit only when implied
|
||||
// by signAlgo (per §11.9). The caller decides.
|
||||
hashAlgo: z.string().optional(),
|
||||
signAlgo: z.string(),
|
||||
// REQUIRED Conditional for algorithms like RSASSA-PSS.
|
||||
signAlgoParams: z.string().optional(),
|
||||
clientData: z.string().optional(),
|
||||
});
|
||||
|
||||
export type TCscSignHashRequest = z.infer<typeof ZCscSignHashRequestSchema>;
|
||||
|
||||
export const ZCscSignHashResponseSchema = z.object({
|
||||
// Position-ordered Base64-encoded signed hashes matching the input order.
|
||||
signatures: z.array(z.string()).nonempty(),
|
||||
});
|
||||
|
||||
export type TCscSignHashResponse = z.infer<typeof ZCscSignHashResponseSchema>;
|
||||
|
||||
// ─── §11.10 signatures/timestamp ─────────────────────────────────────────────
|
||||
|
||||
export const ZCscTimestampRequestSchema = z.object({
|
||||
hash: z.string(),
|
||||
hashAlgo: z.string(),
|
||||
// Hex-encoded random; SHALL round-trip in the timestamp token when supplied.
|
||||
nonce: z.string().optional(),
|
||||
clientData: z.string().optional(),
|
||||
});
|
||||
|
||||
export type TCscTimestampRequest = z.infer<typeof ZCscTimestampRequestSchema>;
|
||||
|
||||
export const ZCscTimestampResponseSchema = z.object({
|
||||
// Base64-encoded RFC 3161 (with RFC 5816 update) time-stamp token.
|
||||
timestamp: z.string(),
|
||||
});
|
||||
|
||||
export type TCscTimestampResponse = z.infer<typeof ZCscTimestampResponseSchema>;
|
||||
|
||||
// OAuth 2.0 token + revoke shapes are handled by the `arctic` library — see
|
||||
// `oauth.ts` in this directory. Arctic exposes `OAuth2Tokens` (with `.data`
|
||||
// available for non-standard CSC fields like `token_type === 'SAD'`).
|
||||
@@ -0,0 +1,120 @@
|
||||
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
import type { Context } from 'hono';
|
||||
import { deleteCookie, getSignedCookie, setSignedCookie } from 'hono/cookie';
|
||||
import { parseSigned, serialize } from 'hono/utils/cookie';
|
||||
import { z } from 'zod';
|
||||
|
||||
import { CSC_BLOCKING_ERROR_COOKIE_NAME, cscCookieBaseOptions, getCscCookieSecret } from './shared';
|
||||
|
||||
/**
|
||||
* `csc_blocking_error` — one-shot surface for service-scope OAuth callback
|
||||
* failures the recipient can't self-resolve (empty credential list, invalid
|
||||
* cert, refused algorithm, etc.). The `/sign/{token}` loader reads + clears
|
||||
* it on next visit so no error state rides on URL query params.
|
||||
*/
|
||||
|
||||
const CSC_BLOCKING_ERROR_MAX_AGE_SECONDS = 60 * 10; // 10 minutes — matches the other short-lived CSC cookies.
|
||||
|
||||
export const ZCscBlockingErrorPayloadSchema = z.object({
|
||||
/** `AppErrorCode` value, e.g. `'CSC_CREDENTIAL_LIST_EMPTY'`. */
|
||||
code: z.string().min(1),
|
||||
/** Recipient token from `/sign/{token}`; loader scopes the error to its recipient. */
|
||||
recipientToken: z.string().min(1),
|
||||
});
|
||||
|
||||
export type TCscBlockingErrorPayload = z.infer<typeof ZCscBlockingErrorPayloadSchema>;
|
||||
|
||||
type SetCscBlockingErrorCookieOptions = {
|
||||
c: Context;
|
||||
payload: TCscBlockingErrorPayload;
|
||||
};
|
||||
|
||||
export const setCscBlockingErrorCookie = async (options: SetCscBlockingErrorCookieOptions): Promise<void> => {
|
||||
const { c, payload } = options;
|
||||
|
||||
await setSignedCookie(c, CSC_BLOCKING_ERROR_COOKIE_NAME, JSON.stringify(payload), getCscCookieSecret(), {
|
||||
...cscCookieBaseOptions,
|
||||
maxAge: CSC_BLOCKING_ERROR_MAX_AGE_SECONDS,
|
||||
});
|
||||
};
|
||||
|
||||
/**
|
||||
* Read + validate the blocking-error cookie. Returns `null` when absent or
|
||||
* signature-invalid; throws `INVALID_REQUEST` when signed-but-malformed
|
||||
* (tamper-shaped, mirroring `oauth-flow-cookie.ts`).
|
||||
*/
|
||||
export const getCscBlockingErrorCookie = async (c: Context): Promise<TCscBlockingErrorPayload | null> => {
|
||||
const raw = await getSignedCookie(c, getCscCookieSecret(), CSC_BLOCKING_ERROR_COOKIE_NAME);
|
||||
|
||||
if (!raw) {
|
||||
return null;
|
||||
}
|
||||
|
||||
let parsedJson: unknown;
|
||||
|
||||
try {
|
||||
parsedJson = JSON.parse(raw);
|
||||
} catch {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: 'CSC blocking error cookie payload is not valid JSON.',
|
||||
});
|
||||
}
|
||||
|
||||
const result = ZCscBlockingErrorPayloadSchema.safeParse(parsedJson);
|
||||
|
||||
if (!result.success) {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: 'CSC blocking error cookie payload failed schema validation.',
|
||||
});
|
||||
}
|
||||
|
||||
return result.data;
|
||||
};
|
||||
|
||||
export const clearCscBlockingErrorCookie = (c: Context): void => {
|
||||
deleteCookie(c, CSC_BLOCKING_ERROR_COOKIE_NAME, cscCookieBaseOptions);
|
||||
};
|
||||
|
||||
/**
|
||||
* Remix-compatible reader: parses + HMAC-verifies the blocking-error cookie
|
||||
* from a raw `Cookie` header on a standard `Request`. Returns `null` when
|
||||
* absent, signature-invalid, or payload-malformed (no throw — the loader
|
||||
* only uses the cookie advisorily, so a bad cookie shouldn't break the page).
|
||||
*/
|
||||
export const readCscBlockingErrorFromRequest = async (request: Request): Promise<TCscBlockingErrorPayload | null> => {
|
||||
const cookieHeader = request.headers.get('cookie');
|
||||
|
||||
if (!cookieHeader) {
|
||||
return null;
|
||||
}
|
||||
|
||||
const parsed = await parseSigned(cookieHeader, getCscCookieSecret(), CSC_BLOCKING_ERROR_COOKIE_NAME);
|
||||
|
||||
const value = parsed[CSC_BLOCKING_ERROR_COOKIE_NAME];
|
||||
|
||||
if (typeof value !== 'string') {
|
||||
return null;
|
||||
}
|
||||
|
||||
try {
|
||||
const json = JSON.parse(value);
|
||||
|
||||
const result = ZCscBlockingErrorPayloadSchema.safeParse(json);
|
||||
|
||||
return result.success ? result.data : null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* Serialised `Set-Cookie` header value that expires the cookie immediately.
|
||||
* Use in a Remix loader's response headers to clear the cookie after the
|
||||
* loader reads it once.
|
||||
*/
|
||||
export const buildClearCscBlockingErrorCookieHeader = (): string => {
|
||||
return serialize(CSC_BLOCKING_ERROR_COOKIE_NAME, '', {
|
||||
...cscCookieBaseOptions,
|
||||
maxAge: 0,
|
||||
});
|
||||
};
|
||||
@@ -0,0 +1,85 @@
|
||||
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
import type { Context } from 'hono';
|
||||
import { deleteCookie, getSignedCookie, setSignedCookie } from 'hono/cookie';
|
||||
import { z } from 'zod';
|
||||
|
||||
import { CSC_OAUTH_FLOW_COOKIE_NAME, cscCookieBaseOptions, getCscCookieSecret } from './shared';
|
||||
|
||||
/**
|
||||
* `csc_oauth_flow` — single-round-trip carrier across `/api/csc/oauth/authorize`
|
||||
* → TSP → `/api/csc/oauth/callback`. Holds the PKCE verifier + state plus the
|
||||
* Documenso-side context (`recipientToken`, optional `sessionId`) the
|
||||
* callback needs to resume the right signing flow.
|
||||
*
|
||||
* JSON-encoded inside a single signed cookie; structurally validated on read
|
||||
* so a tampered or stale shape can't smuggle bad state into the callback.
|
||||
*/
|
||||
|
||||
const CSC_OAUTH_FLOW_MAX_AGE_SECONDS = 60 * 10; // 10 minutes — matches /api/auth/oauth/* convention.
|
||||
|
||||
export const ZCscOAuthFlowPayloadSchema = z.object({
|
||||
/** `'service'` for the first round-trip, `'credential'` for the SAD round-trip. */
|
||||
scope: z.enum(['service', 'credential']),
|
||||
/** Arctic-generated CSRF token; re-validated against `?state` at callback. */
|
||||
state: z.string().min(1),
|
||||
/** Arctic-generated PKCE verifier (RFC 7636); paired with the URL's `code_challenge`. */
|
||||
codeVerifier: z.string().min(1),
|
||||
/** Recipient signing token from `/sign/{token}`; threads recipient identity through the round-trip. */
|
||||
recipientToken: z.string().min(1),
|
||||
/** CSC session id — present only on `credential`-scope flows (set at prep). */
|
||||
sessionId: z.string().min(1).optional(),
|
||||
});
|
||||
|
||||
export type TCscOAuthFlowPayload = z.infer<typeof ZCscOAuthFlowPayloadSchema>;
|
||||
|
||||
type SetCscOAuthFlowCookieOptions = {
|
||||
c: Context;
|
||||
payload: TCscOAuthFlowPayload;
|
||||
};
|
||||
|
||||
export const setCscOAuthFlowCookie = async (options: SetCscOAuthFlowCookieOptions): Promise<void> => {
|
||||
const { c, payload } = options;
|
||||
|
||||
await setSignedCookie(c, CSC_OAUTH_FLOW_COOKIE_NAME, JSON.stringify(payload), getCscCookieSecret(), {
|
||||
...cscCookieBaseOptions,
|
||||
maxAge: CSC_OAUTH_FLOW_MAX_AGE_SECONDS,
|
||||
});
|
||||
};
|
||||
|
||||
/**
|
||||
* Read + validate the OAuth-flow cookie. Returns `null` when the cookie is
|
||||
* absent or the signature is invalid; throws `INVALID_REQUEST` when the
|
||||
* payload is structurally bad (signed but malformed JSON / schema mismatch),
|
||||
* since that's tamper-shaped, not a normal missing-cookie case.
|
||||
*/
|
||||
export const getCscOAuthFlowCookie = async (c: Context): Promise<TCscOAuthFlowPayload | null> => {
|
||||
const raw = await getSignedCookie(c, getCscCookieSecret(), CSC_OAUTH_FLOW_COOKIE_NAME);
|
||||
|
||||
if (!raw) {
|
||||
return null;
|
||||
}
|
||||
|
||||
let parsedJson: unknown;
|
||||
|
||||
try {
|
||||
parsedJson = JSON.parse(raw);
|
||||
} catch {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: 'CSC OAuth flow cookie payload is not valid JSON.',
|
||||
});
|
||||
}
|
||||
|
||||
const result = ZCscOAuthFlowPayloadSchema.safeParse(parsedJson);
|
||||
|
||||
if (!result.success) {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: 'CSC OAuth flow cookie payload failed schema validation.',
|
||||
});
|
||||
}
|
||||
|
||||
return result.data;
|
||||
};
|
||||
|
||||
export const clearCscOAuthFlowCookie = (c: Context): void => {
|
||||
deleteCookie(c, CSC_OAUTH_FLOW_COOKIE_NAME, cscCookieBaseOptions);
|
||||
};
|
||||
@@ -0,0 +1,61 @@
|
||||
import type { Context } from 'hono';
|
||||
import { deleteCookie, getSignedCookie, setSignedCookie } from 'hono/cookie';
|
||||
import { parseSigned } from 'hono/utils/cookie';
|
||||
|
||||
import { CSC_SAD_SESSION_COOKIE_NAME, cscCookieBaseOptions, getCscCookieSecret } from './shared';
|
||||
|
||||
/**
|
||||
* `csc_sad_session` — HMAC-signed `CscSession` cuid. Set after the
|
||||
* credential-scope OAuth callback exchanges code → SAD; pointed at the
|
||||
* server-side session row that owns the SAD + the prep-time item hashes.
|
||||
*
|
||||
* Lifetime mirrors the TSP-asserted SAD expiry (`sadExpiresAt`) so the cookie
|
||||
* cannot outlive its server-side authorisation. Cleared by the sync sign
|
||||
* mutation on success; otherwise decays naturally with the browser TTL.
|
||||
*/
|
||||
|
||||
type SetCscSadSessionCookieOptions = {
|
||||
c: Context;
|
||||
sessionId: string;
|
||||
/** Mirror of `CscSession.sadExpiresAt`; cookie expires no later than the SAD. */
|
||||
expiresAt: Date;
|
||||
};
|
||||
|
||||
export const setCscSadSessionCookie = async (options: SetCscSadSessionCookieOptions): Promise<void> => {
|
||||
const { c, sessionId, expiresAt } = options;
|
||||
|
||||
await setSignedCookie(c, CSC_SAD_SESSION_COOKIE_NAME, sessionId, getCscCookieSecret(), {
|
||||
...cscCookieBaseOptions,
|
||||
expires: expiresAt,
|
||||
});
|
||||
};
|
||||
|
||||
export const getCscSadSessionCookie = async (c: Context): Promise<string | null> => {
|
||||
const value = await getSignedCookie(c, getCscCookieSecret(), CSC_SAD_SESSION_COOKIE_NAME);
|
||||
|
||||
// `getSignedCookie` returns `false` on signature mismatch, `undefined` when
|
||||
// the cookie is absent. Both collapse to `null` for the caller's sake.
|
||||
return value ? value : null;
|
||||
};
|
||||
|
||||
export const clearCscSadSessionCookie = (c: Context): void => {
|
||||
deleteCookie(c, CSC_SAD_SESSION_COOKIE_NAME, cscCookieBaseOptions);
|
||||
};
|
||||
|
||||
/**
|
||||
* Remix-compatible reader: parses + HMAC-verifies the SAD-session cookie
|
||||
* from a raw `Cookie` header on a standard `Request`. Mirrors
|
||||
* `getCscSadSessionCookie` but works outside Hono's `Context`.
|
||||
*/
|
||||
export const readCscSadSessionFromRequest = async (request: Request): Promise<string | null> => {
|
||||
const cookieHeader = request.headers.get('cookie');
|
||||
|
||||
if (!cookieHeader) {
|
||||
return null;
|
||||
}
|
||||
|
||||
const parsed = await parseSigned(cookieHeader, getCscCookieSecret(), CSC_SAD_SESSION_COOKIE_NAME);
|
||||
const value = parsed[CSC_SAD_SESSION_COOKIE_NAME];
|
||||
|
||||
return typeof value === 'string' ? value : null;
|
||||
};
|
||||
@@ -0,0 +1,65 @@
|
||||
import type { Context } from 'hono';
|
||||
import { deleteCookie, getSignedCookie, setSignedCookie } from 'hono/cookie';
|
||||
import { parseSigned } from 'hono/utils/cookie';
|
||||
|
||||
import { CSC_SERVICE_SESSION_COOKIE_NAME, cscCookieBaseOptions, getCscCookieSecret } from './shared';
|
||||
|
||||
/**
|
||||
* `csc_service_session` — recipient-scoped attestation that this browser just
|
||||
* completed a service-scope OAuth round-trip for `<recipientToken>`. The
|
||||
* `/sign/{token}` loader compares the cookie value against the path token; on
|
||||
* match it skips re-auth, breaking the redirect loop that would otherwise
|
||||
* occur when the TSP silently re-grants from its cached SCA session.
|
||||
*
|
||||
* Covers the long-lived T1→T3 window (recipient on the signing page filling
|
||||
* fields, before clicking Sign). `csc_sad_session` covers the much shorter
|
||||
* T4→T5 window (active signing transaction); the two are complementary, not
|
||||
* substitutes.
|
||||
*
|
||||
* TTL = TSP-asserted service-scope `expires_in` so the trust window can never
|
||||
* outlive the underlying access token.
|
||||
*/
|
||||
|
||||
type SetCscServiceSessionCookieOptions = {
|
||||
c: Context;
|
||||
recipientToken: string;
|
||||
/** TSP service-scope `expires_in` in seconds. Mirrored as the cookie max-age. */
|
||||
ttlSeconds: number;
|
||||
};
|
||||
|
||||
export const setCscServiceSessionCookie = async (options: SetCscServiceSessionCookieOptions): Promise<void> => {
|
||||
const { c, recipientToken, ttlSeconds } = options;
|
||||
|
||||
await setSignedCookie(c, CSC_SERVICE_SESSION_COOKIE_NAME, recipientToken, getCscCookieSecret(), {
|
||||
...cscCookieBaseOptions,
|
||||
maxAge: ttlSeconds,
|
||||
});
|
||||
};
|
||||
|
||||
export const getCscServiceSessionCookie = async (c: Context): Promise<string | null> => {
|
||||
const value = await getSignedCookie(c, getCscCookieSecret(), CSC_SERVICE_SESSION_COOKIE_NAME);
|
||||
|
||||
return value ? value : null;
|
||||
};
|
||||
|
||||
export const clearCscServiceSessionCookie = (c: Context): void => {
|
||||
deleteCookie(c, CSC_SERVICE_SESSION_COOKIE_NAME, cscCookieBaseOptions);
|
||||
};
|
||||
|
||||
/**
|
||||
* Remix-compatible reader: parses + HMAC-verifies the service-session cookie
|
||||
* from a raw `Cookie` header on a standard `Request`. Mirrors
|
||||
* `getCscServiceSessionCookie` but works outside Hono's `Context`.
|
||||
*/
|
||||
export const readCscServiceSessionFromRequest = async (request: Request): Promise<string | null> => {
|
||||
const cookieHeader = request.headers.get('cookie');
|
||||
|
||||
if (!cookieHeader) {
|
||||
return null;
|
||||
}
|
||||
|
||||
const parsed = await parseSigned(cookieHeader, getCscCookieSecret(), CSC_SERVICE_SESSION_COOKIE_NAME);
|
||||
const value = parsed[CSC_SERVICE_SESSION_COOKIE_NAME];
|
||||
|
||||
return typeof value === 'string' ? value : null;
|
||||
};
|
||||
@@ -0,0 +1,46 @@
|
||||
import { formatSecureCookieName, getCookieDomain, useSecureCookies } from '@documenso/lib/constants/auth';
|
||||
import { requireEnv } from '@documenso/lib/utils/env';
|
||||
|
||||
/**
|
||||
* Shared HMAC secret + base attribute set for the CSC cookies.
|
||||
*
|
||||
* `NEXTAUTH_SECRET` is reused so signed-cookie verification stays uniform
|
||||
* across the auth + CSC surfaces. The `sameSite` conditional matches
|
||||
* `sessionCookieOptions` in `@documenso/auth` so a future embedding flow
|
||||
* (CSC inside an `<iframe>` on a partner host) works without a separate
|
||||
* cookie-attribute regime.
|
||||
*/
|
||||
|
||||
/** HMAC secret for hono `setSignedCookie` / `getSignedCookie`. */
|
||||
export const getCscCookieSecret = (): string => requireEnv('NEXTAUTH_SECRET');
|
||||
|
||||
/**
|
||||
* CSC cookie names; prefixed with `__Secure-` in production over HTTPS.
|
||||
*
|
||||
* Naming maps 1:1 to the CSC OAuth scope each cookie attests:
|
||||
* - `csc_service_session` — service-scope grant (long-lived per-browser SCA
|
||||
* attestation; lifetime = TSP `expires_in`).
|
||||
* - `csc_sad_session` — credential-scope grant in progress (in-flight signing
|
||||
* transaction; lifetime = SAD lifetime).
|
||||
* - `csc_oauth_flow` — single-round-trip carrier across authorize → callback
|
||||
* (scope-agnostic; both flows reuse it).
|
||||
* - `csc_blocking_error` — callback failure surface; carries an unresolvable
|
||||
* service-scope error (e.g. empty credential list, refused algorithm) to
|
||||
* the next `/sign/{token}` loader, read-once.
|
||||
*/
|
||||
export const CSC_SERVICE_SESSION_COOKIE_NAME = formatSecureCookieName('csc_service_session');
|
||||
export const CSC_SAD_SESSION_COOKIE_NAME = formatSecureCookieName('csc_sad_session');
|
||||
export const CSC_OAUTH_FLOW_COOKIE_NAME = formatSecureCookieName('csc_oauth_flow');
|
||||
export const CSC_BLOCKING_ERROR_COOKIE_NAME = formatSecureCookieName('csc_blocking_error');
|
||||
|
||||
/**
|
||||
* Base options spread into every CSC cookie. Callers add per-cookie expiry
|
||||
* (`maxAge` or `expires`) on top.
|
||||
*/
|
||||
export const cscCookieBaseOptions = {
|
||||
httpOnly: true,
|
||||
path: '/',
|
||||
sameSite: useSecureCookies ? 'none' : 'lax',
|
||||
secure: useSecureCookies,
|
||||
domain: getCookieDomain(),
|
||||
} as const;
|
||||
@@ -0,0 +1,184 @@
|
||||
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
import { prisma } from '@documenso/prisma';
|
||||
import { Prisma } from '@prisma/client';
|
||||
|
||||
/**
|
||||
* DB helpers for `CscCredential` — the per-recipient row that holds the
|
||||
* TSP-validated certificate chain, the resolved algorithm policy, and the
|
||||
* encrypted service-scope access token.
|
||||
*
|
||||
* Lifecycle mirrors {@link sign-session.ts} but with a longer-lived row:
|
||||
*
|
||||
* - {@link upsertCscCredential} — service-scope OAuth callback writes the
|
||||
* full credential after `credentials/info` + algorithm validation succeed.
|
||||
* Re-runs replace prior bytes (cert / token rotates as the TSP refreshes).
|
||||
* - {@link loadCscCredential} — sign-time fetches by `recipientId` to recover
|
||||
* the persisted algorithm + encrypted service token; returns `null` when
|
||||
* the recipient never completed service-scope OAuth.
|
||||
*
|
||||
* Encryption is the caller's job — both byte columns hold raw ciphertext
|
||||
* produced by {@link encryptCscToken} so the helpers stay cipher-agnostic.
|
||||
* Cascade cleanup on `Recipient` delete removes the row transitively.
|
||||
*/
|
||||
|
||||
export type CscCredentialRow = {
|
||||
id: string;
|
||||
recipientId: number;
|
||||
providerId: string;
|
||||
credentialId: string;
|
||||
certCache: Uint8Array | null;
|
||||
signatureAlgorithm: string;
|
||||
keyType: string;
|
||||
digestAlgorithm: string;
|
||||
keyLenBits: number | null;
|
||||
signAlgoParams: string | null;
|
||||
serviceTokenCiphertext: Uint8Array | null;
|
||||
serviceTokenExpiresAt: Date | null;
|
||||
createdAt: Date;
|
||||
updatedAt: Date;
|
||||
};
|
||||
|
||||
type UpsertCscCredentialInput = {
|
||||
recipientId: number;
|
||||
providerId: string;
|
||||
credentialId: string;
|
||||
/** Length-prefixed X.509 chain — produced from `cscCredentialsInfo.cert.certificates`. */
|
||||
certCache: Uint8Array;
|
||||
/** OID persisted from {@link CscAlgorithmPolicy.signAlgoOid}. */
|
||||
signatureAlgorithm: string;
|
||||
/** `'RSA'` or `'ECDSA'` from the resolved policy. */
|
||||
keyType: string;
|
||||
/** `'SHA-256'` / `'SHA-384'` / `'SHA-512'` from the resolved policy. */
|
||||
digestAlgorithm: string;
|
||||
keyLenBits: number;
|
||||
/** RSASSA-PSS only; omit otherwise. */
|
||||
signAlgoParams?: string;
|
||||
/** Output of {@link encryptCscToken}. */
|
||||
serviceTokenCiphertext: Uint8Array;
|
||||
/** Mirrors the TSP's `expires_in` projected onto wall-clock. */
|
||||
serviceTokenExpiresAt: Date;
|
||||
};
|
||||
|
||||
/**
|
||||
* Create or refresh the per-recipient credential row at service-scope OAuth
|
||||
* callback success. Replaces every prior byte payload — a re-auth always
|
||||
* supersedes the prior cert + token (TSPs may have rotated either).
|
||||
*/
|
||||
export const upsertCscCredential = async (input: UpsertCscCredentialInput): Promise<CscCredentialRow> => {
|
||||
const {
|
||||
recipientId,
|
||||
providerId,
|
||||
credentialId,
|
||||
certCache,
|
||||
signatureAlgorithm,
|
||||
keyType,
|
||||
digestAlgorithm,
|
||||
keyLenBits,
|
||||
signAlgoParams,
|
||||
serviceTokenCiphertext,
|
||||
serviceTokenExpiresAt,
|
||||
} = input;
|
||||
|
||||
const row = await prisma.cscCredential.upsert({
|
||||
where: { recipientId },
|
||||
create: {
|
||||
recipientId,
|
||||
providerId,
|
||||
credentialId,
|
||||
certCache,
|
||||
signatureAlgorithm,
|
||||
keyType,
|
||||
digestAlgorithm,
|
||||
keyLenBits,
|
||||
signAlgoParams: signAlgoParams ?? null,
|
||||
serviceTokenCiphertext,
|
||||
serviceTokenExpiresAt,
|
||||
},
|
||||
update: {
|
||||
providerId,
|
||||
credentialId,
|
||||
certCache,
|
||||
signatureAlgorithm,
|
||||
keyType,
|
||||
digestAlgorithm,
|
||||
keyLenBits,
|
||||
signAlgoParams: signAlgoParams ?? null,
|
||||
serviceTokenCiphertext,
|
||||
serviceTokenExpiresAt,
|
||||
},
|
||||
});
|
||||
|
||||
return toCscCredentialRow(row);
|
||||
};
|
||||
|
||||
/**
|
||||
* Fetch the credential row for a recipient. Returns `null` when absent — the
|
||||
* recipient hasn't completed service-scope OAuth yet (loader path) or the
|
||||
* recipient cascade fired (cleanup path). Both are normal terminal outcomes.
|
||||
*/
|
||||
export const loadCscCredential = async (recipientId: number): Promise<CscCredentialRow | null> => {
|
||||
const row = await prisma.cscCredential.findUnique({
|
||||
where: { recipientId },
|
||||
});
|
||||
|
||||
return row ? toCscCredentialRow(row) : null;
|
||||
};
|
||||
|
||||
/**
|
||||
* Explicit delete by recipient id. Recipient-cascade handles routine cleanup;
|
||||
* this helper is for operator-triggered re-auth flows (force the next visit
|
||||
* to re-do service-scope OAuth even within the trust window).
|
||||
*
|
||||
* Throws `NOT_FOUND` when the row is already gone — semantically distinct
|
||||
* from {@link loadCscCredential}'s nullable return because explicit delete
|
||||
* is a deliberate operation and silent no-op would mask flow-state bugs.
|
||||
*/
|
||||
export const deleteCscCredential = async (recipientId: number): Promise<CscCredentialRow> => {
|
||||
try {
|
||||
const row = await prisma.cscCredential.delete({
|
||||
where: { recipientId },
|
||||
});
|
||||
|
||||
return toCscCredentialRow(row);
|
||||
} catch (err) {
|
||||
if (err instanceof Prisma.PrismaClientKnownRequestError && err.code === 'P2025') {
|
||||
throw new AppError(AppErrorCode.NOT_FOUND, {
|
||||
message: `CSC credential for recipient ${recipientId} not found.`,
|
||||
});
|
||||
}
|
||||
|
||||
throw err;
|
||||
}
|
||||
};
|
||||
|
||||
const toCscCredentialRow = (row: {
|
||||
id: string;
|
||||
recipientId: number;
|
||||
providerId: string;
|
||||
credentialId: string;
|
||||
certCache: Uint8Array | null;
|
||||
signatureAlgorithm: string;
|
||||
keyType: string;
|
||||
digestAlgorithm: string;
|
||||
keyLenBits: number | null;
|
||||
signAlgoParams: string | null;
|
||||
serviceTokenCiphertext: Uint8Array | null;
|
||||
serviceTokenExpiresAt: Date | null;
|
||||
createdAt: Date;
|
||||
updatedAt: Date;
|
||||
}): CscCredentialRow => ({
|
||||
id: row.id,
|
||||
recipientId: row.recipientId,
|
||||
providerId: row.providerId,
|
||||
credentialId: row.credentialId,
|
||||
certCache: row.certCache,
|
||||
signatureAlgorithm: row.signatureAlgorithm,
|
||||
keyType: row.keyType,
|
||||
digestAlgorithm: row.digestAlgorithm,
|
||||
keyLenBits: row.keyLenBits,
|
||||
signAlgoParams: row.signAlgoParams,
|
||||
serviceTokenCiphertext: row.serviceTokenCiphertext,
|
||||
serviceTokenExpiresAt: row.serviceTokenExpiresAt,
|
||||
createdAt: row.createdAt,
|
||||
updatedAt: row.updatedAt,
|
||||
});
|
||||
@@ -0,0 +1,548 @@
|
||||
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
import { jobs } from '@documenso/lib/jobs/client';
|
||||
import { getRecipientByToken } from '@documenso/lib/server-only/recipient/get-recipient-by-token';
|
||||
import { triggerWebhook } from '@documenso/lib/server-only/webhooks/trigger/trigger-webhook';
|
||||
import { DOCUMENT_AUDIT_LOG_TYPE } from '@documenso/lib/types/document-audit-logs';
|
||||
import { mapEnvelopeToWebhookDocumentPayload, ZWebhookDocumentSchema } from '@documenso/lib/types/webhook-payload';
|
||||
import type { RequestMetadata } from '@documenso/lib/universal/extract-request-metadata';
|
||||
import { getFileServerSide } from '@documenso/lib/universal/upload/get-file.server';
|
||||
import { putPdfFileServerSide } from '@documenso/lib/universal/upload/put-file.server';
|
||||
import { createDocumentAuditLogData } from '@documenso/lib/utils/document-audit-logs';
|
||||
import { extractDocumentAuthMethods } from '@documenso/lib/utils/document-auth';
|
||||
import { mapSecondaryIdToDocumentId } from '@documenso/lib/utils/envelope';
|
||||
import { prisma } from '@documenso/prisma';
|
||||
import { PDF } from '@libpdf/core';
|
||||
import {
|
||||
type DocumentDataType,
|
||||
EnvelopeType,
|
||||
RecipientRole,
|
||||
SendStatus,
|
||||
SigningStatus,
|
||||
WebhookTriggerEvents,
|
||||
} from '@prisma/client';
|
||||
|
||||
import { type CscDigest, hashOidForDigest, policyToLibpdfSignerAlgo } from './algorithm-resolver';
|
||||
import { decodeCscCertChain } from './cert-chain';
|
||||
import { decryptCscToken } from './ciphers';
|
||||
import { cscSignHash } from './client/signatures';
|
||||
import { loadCscCredential } from './credential';
|
||||
import { buildTspAnchorName } from './pdf-names';
|
||||
import { consumeCscSession, loadCscSession } from './sign-session';
|
||||
import { CscCaptureSigner } from './signers/capture-signer';
|
||||
import { CscFifoSigner } from './signers/fifo-signer';
|
||||
import { getCscTransport } from './transport';
|
||||
import { resolveCscSignTimeTsa } from './tsa-resolver';
|
||||
|
||||
/**
|
||||
* CSC TSP sign-time orchestrator.
|
||||
*
|
||||
* Two-pass run, both passes operating on the same prep-time-persisted PDF
|
||||
* bytes (`CscSession.items[i].documentDataId` pins an immutable rendered
|
||||
* orphan row — see `prepare-recipient-signing.ts`):
|
||||
*
|
||||
* 1. Capture re-derives each item's `signedAttrs` digest under the
|
||||
* session-pinned `signingTime` and asserts it matches the prep-time hash
|
||||
* bit-for-bit. Defense in depth — the bytes are identical so a mismatch
|
||||
* means libpdf changed between prep and sign or the row was tampered
|
||||
* with. Throws `CSC_BASE_DOCUMENT_MUTATED` on divergence.
|
||||
* 2. A single batched `signatures/signHash` (§11.9) returns position-ordered
|
||||
* signatures that the embed pass writes back into the same anchors via
|
||||
* `CscFifoSigner`.
|
||||
*
|
||||
* Output bytes are in-place-copied onto `envelopeItem.documentData` (the
|
||||
* row id stays stable; only `type` + `data` change) — same pattern as
|
||||
* `materializeTspAnchorsForEnvelope`. The uploaded rows from
|
||||
* `putPdfFileServerSide` orbit as orphans.
|
||||
*
|
||||
* Persistence is bundled into one outer transaction so document-content
|
||||
* updates, recipient signing-status, audit log, and session consume commit
|
||||
* atomically. Post-tx side effects (webhooks, emails) run after.
|
||||
*/
|
||||
|
||||
export type ExecuteTspSignOptions = {
|
||||
sessionId: string;
|
||||
recipientToken: string;
|
||||
requestMetadata?: RequestMetadata;
|
||||
};
|
||||
|
||||
export type ExecuteTspSignResult = { outcome: 'signed' } | { outcome: 'already_signed' };
|
||||
|
||||
type CapturedItem = {
|
||||
envelopeItemId: string;
|
||||
recapturedDigestB64: string;
|
||||
anchorName: string;
|
||||
pdfBytes: Uint8Array;
|
||||
};
|
||||
|
||||
type SignedItemDataUpdate = {
|
||||
/** Existing `envelopeItem.documentDataId` — receives the in-place data update. */
|
||||
envelopeItemDataId: string;
|
||||
/** Payload to copy onto the existing row. */
|
||||
uploadedType: DocumentDataType;
|
||||
uploadedData: string;
|
||||
};
|
||||
|
||||
export const executeTspSign = async (opts: ExecuteTspSignOptions): Promise<ExecuteTspSignResult> => {
|
||||
const { sessionId, recipientToken, requestMetadata } = opts;
|
||||
|
||||
const session = await loadCscSession(sessionId);
|
||||
|
||||
if (!session) {
|
||||
throw new AppError(AppErrorCode.NOT_FOUND, {
|
||||
message: `CSC session "${sessionId}" not found.`,
|
||||
});
|
||||
}
|
||||
|
||||
const recipient = await getRecipientByToken({ token: recipientToken }).catch(() => null);
|
||||
|
||||
if (!recipient) {
|
||||
throw new AppError(AppErrorCode.NOT_FOUND, {
|
||||
message: `Recipient with token "${recipientToken}" not found.`,
|
||||
});
|
||||
}
|
||||
|
||||
if (recipient.id !== session.recipientId) {
|
||||
throw new AppError(AppErrorCode.UNAUTHORIZED, {
|
||||
message: 'CSC session does not belong to the recipient identified by token.',
|
||||
});
|
||||
}
|
||||
|
||||
// Idempotency: a 15s tRPC timeout that races with a successful sign can
|
||||
// leave the client retrying after the recipient row already flipped to
|
||||
// SIGNED. Return success rather than re-running.
|
||||
if (recipient.signingStatus === SigningStatus.SIGNED) {
|
||||
return { outcome: 'already_signed' };
|
||||
}
|
||||
|
||||
if (!session.encryptedSad || !session.sadExpiresAt) {
|
||||
throw new AppError(AppErrorCode.CSC_SAD_EXPIRED_PRE_SIGN, {
|
||||
message: 'CSC session has no attached SAD — credential-scope OAuth must complete first.',
|
||||
});
|
||||
}
|
||||
|
||||
if (session.sadExpiresAt.getTime() <= Date.now()) {
|
||||
throw new AppError(AppErrorCode.CSC_SAD_EXPIRED_PRE_SIGN, {
|
||||
message: 'CSC SAD expired before sign-time execution.',
|
||||
});
|
||||
}
|
||||
|
||||
const sad = decryptCscToken(session.encryptedSad);
|
||||
|
||||
if (!sad) {
|
||||
throw new AppError(AppErrorCode.CSC_SAD_EXPIRED_PRE_SIGN, {
|
||||
message: 'CSC SAD decrypt failed — key rotation or row corruption.',
|
||||
});
|
||||
}
|
||||
|
||||
const credential = await loadCscCredential(recipient.id);
|
||||
|
||||
if (!credential) {
|
||||
throw new AppError(AppErrorCode.NOT_FOUND, {
|
||||
message: 'CSC credential missing at sign time.',
|
||||
});
|
||||
}
|
||||
|
||||
if (!credential.certCache) {
|
||||
throw new AppError(AppErrorCode.CSC_CERT_INVALID, {
|
||||
message: 'CSC credential has no persisted certificate chain.',
|
||||
});
|
||||
}
|
||||
|
||||
if (credential.keyLenBits === null) {
|
||||
throw new AppError(AppErrorCode.CSC_ALGORITHM_REFUSED, {
|
||||
message: 'CSC credential omits persisted keyLenBits — service-scope OAuth must re-run.',
|
||||
});
|
||||
}
|
||||
|
||||
if (!credential.serviceTokenCiphertext || !credential.serviceTokenExpiresAt) {
|
||||
throw new AppError(AppErrorCode.CSC_REQUEST_FAILED, {
|
||||
message: 'CSC credential has no persisted service token — recipient must re-auth.',
|
||||
});
|
||||
}
|
||||
|
||||
if (credential.serviceTokenExpiresAt.getTime() <= Date.now()) {
|
||||
throw new AppError(AppErrorCode.CSC_REQUEST_FAILED, {
|
||||
message: 'CSC service token expired — recipient must re-auth via service-scope OAuth.',
|
||||
});
|
||||
}
|
||||
|
||||
const serviceToken = decryptCscToken(credential.serviceTokenCiphertext);
|
||||
|
||||
if (!serviceToken) {
|
||||
throw new AppError(AppErrorCode.CSC_REQUEST_FAILED, {
|
||||
message: 'CSC service token decrypt failed — operator re-auth required.',
|
||||
});
|
||||
}
|
||||
|
||||
const chain = decodeCscCertChain(credential.certCache);
|
||||
|
||||
const algo = policyToLibpdfSignerAlgo({
|
||||
keyType: credential.keyType as 'RSA' | 'ECDSA',
|
||||
digestAlgorithm: credential.digestAlgorithm as CscDigest,
|
||||
signAlgoOid: credential.signatureAlgorithm,
|
||||
keyLenBits: credential.keyLenBits,
|
||||
hashAlgoOid: '',
|
||||
});
|
||||
|
||||
const envelope = await prisma.envelope.findUniqueOrThrow({
|
||||
where: { id: session.envelopeId },
|
||||
include: {
|
||||
envelopeItems: { include: { documentData: true } },
|
||||
recipients: true,
|
||||
documentMeta: true,
|
||||
},
|
||||
});
|
||||
|
||||
// Capture pass: iterate session.items in order so the resulting hash array
|
||||
// is position-bound to session.items[*].ordinal.
|
||||
const capturedItems: CapturedItem[] = [];
|
||||
|
||||
for (let i = 0; i < session.items.length; i++) {
|
||||
const sessionItem = session.items[i];
|
||||
|
||||
const envelopeItem = envelope.envelopeItems.find((item) => item.id === sessionItem.envelopeItemId);
|
||||
|
||||
if (!envelopeItem) {
|
||||
throw new AppError(AppErrorCode.CSC_BASE_DOCUMENT_MUTATED, {
|
||||
message: `Session references envelope item "${sessionItem.envelopeItemId}" not on envelope.`,
|
||||
});
|
||||
}
|
||||
|
||||
const pinnedDocumentData = await prisma.documentData.findUniqueOrThrow({
|
||||
where: { id: sessionItem.documentDataId },
|
||||
});
|
||||
|
||||
const bytes = await getFileServerSide(pinnedDocumentData);
|
||||
const pdfDoc = await PDF.load(bytes);
|
||||
|
||||
const captureSigner = new CscCaptureSigner({
|
||||
certificate: chain[0],
|
||||
certificateChain: chain.slice(1),
|
||||
algo,
|
||||
});
|
||||
|
||||
const anchorName = buildTspAnchorName(recipient.id, envelopeItem.id);
|
||||
|
||||
// Capture pass stays at B-B even though the embed pass below is B-T:
|
||||
// libpdf's B-T signature timestamp is added as a CMS *unsigned*
|
||||
// attribute *after* `signer.sign()` runs over the signed-attrs digest.
|
||||
// The signed-attrs builder (see CAdESDetachedBuilder.create in
|
||||
// @libpdf/core) takes only (signer, documentHash, digestAlgorithm,
|
||||
// signingTime) — no level-conditional attributes — so B-B and B-T
|
||||
// produce byte-identical signed-attrs for the same inputs. Capturing
|
||||
// at B-B avoids dragging the TSA into the dry-run.
|
||||
await pdfDoc.sign({
|
||||
signer: captureSigner,
|
||||
fieldName: anchorName,
|
||||
signingTime: session.signingTime,
|
||||
level: 'B-B',
|
||||
digestAlgorithm: algo.digestAlgorithm,
|
||||
});
|
||||
|
||||
if (captureSigner.capturedDigest === null) {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: 'CscCaptureSigner was not invoked by pdf.sign during sign-time capture.',
|
||||
});
|
||||
}
|
||||
|
||||
const recapturedDigestB64 = Buffer.from(captureSigner.capturedDigest).toString('base64');
|
||||
|
||||
if (recapturedDigestB64 !== sessionItem.hashB64) {
|
||||
throw new AppError(AppErrorCode.CSC_BASE_DOCUMENT_MUTATED, {
|
||||
message: `Re-derived signedAttrs digest at sign time diverged from prep-time hash for envelope item "${envelopeItem.id}".`,
|
||||
});
|
||||
}
|
||||
|
||||
capturedItems.push({
|
||||
envelopeItemId: envelopeItem.id,
|
||||
recapturedDigestB64,
|
||||
anchorName,
|
||||
pdfBytes: bytes,
|
||||
});
|
||||
}
|
||||
|
||||
// Defensive: session-item / captured-item position binding must hold.
|
||||
for (let i = 0; i < capturedItems.length; i++) {
|
||||
if (capturedItems[i].envelopeItemId !== session.items[i].envelopeItemId) {
|
||||
throw new AppError(AppErrorCode.CSC_EMBED_FAILED, {
|
||||
message: 'Capture-pass item ordering diverged from session-pinned ordering.',
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
if (capturedItems.length === 0) {
|
||||
throw new AppError(AppErrorCode.CSC_EMBED_FAILED, {
|
||||
message: 'CSC session contains no items — nothing to sign.',
|
||||
});
|
||||
}
|
||||
|
||||
const hashes = capturedItems.map((c) => c.recapturedDigestB64);
|
||||
// The cscSignHash request schema requires a non-empty tuple; the explicit
|
||||
// check above narrows the array literal for the type system.
|
||||
const [firstHash, ...restHashes] = hashes;
|
||||
|
||||
const transport = await getCscTransport();
|
||||
|
||||
const signHashResp = await cscSignHash({
|
||||
baseUrl: transport.serviceBaseUrl,
|
||||
accessToken: serviceToken,
|
||||
credentialID: credential.credentialId,
|
||||
SAD: sad,
|
||||
hash: [firstHash, ...restHashes],
|
||||
signAlgo: credential.signatureAlgorithm,
|
||||
hashAlgo: hashOidForDigest(algo.digestAlgorithm),
|
||||
});
|
||||
|
||||
if (signHashResp.signatures.length !== capturedItems.length) {
|
||||
throw new AppError(AppErrorCode.CSC_EMBED_FAILED, {
|
||||
message: `CSC signHash returned ${signHashResp.signatures.length} signatures for ${capturedItems.length} hashes.`,
|
||||
});
|
||||
}
|
||||
|
||||
// Embed pass: per-item, reload the same prep-persisted PDF bytes and sign
|
||||
// with a single-signature FIFO signer. No re-render — bytes are exactly
|
||||
// the ones whose digest the TSP just authorised. Level is B-T: each
|
||||
// recipient's CMS gets a TSA-attested signature timestamp embedded as an
|
||||
// unsigned attribute, binding proven time to the signature itself (the
|
||||
// actual eIDAS AES/QES requirement). The TSA is resolved per-recipient
|
||||
// via the sign-time resolver — TSP if advertised (authorised with this
|
||||
// recipient's service-scope bearer), env otherwise.
|
||||
const timestampAuthority = resolveCscSignTimeTsa(transport, serviceToken);
|
||||
|
||||
const signedItemDataUpdates: SignedItemDataUpdate[] = [];
|
||||
|
||||
for (let i = 0; i < capturedItems.length; i++) {
|
||||
const captured = capturedItems[i];
|
||||
const sigBytes = Buffer.from(signHashResp.signatures[i], 'base64');
|
||||
|
||||
const pdfDoc = await PDF.load(captured.pdfBytes);
|
||||
|
||||
const fifoSigner = new CscFifoSigner({
|
||||
certificate: chain[0],
|
||||
certificateChain: chain.slice(1),
|
||||
algo,
|
||||
signatures: [sigBytes],
|
||||
});
|
||||
|
||||
const signResult = await pdfDoc.sign({
|
||||
signer: fifoSigner,
|
||||
fieldName: captured.anchorName,
|
||||
signingTime: session.signingTime,
|
||||
level: 'B-T',
|
||||
timestampAuthority,
|
||||
digestAlgorithm: algo.digestAlgorithm,
|
||||
});
|
||||
|
||||
const envelopeItem = envelope.envelopeItems.find((item) => item.id === captured.envelopeItemId);
|
||||
|
||||
if (!envelopeItem) {
|
||||
throw new AppError(AppErrorCode.CSC_EMBED_FAILED, {
|
||||
message: `Envelope item "${captured.envelopeItemId}" missing during embed pass.`,
|
||||
});
|
||||
}
|
||||
|
||||
const fileName = envelope.title.endsWith('.pdf') ? envelope.title : `${envelope.title || 'envelope'}.pdf`;
|
||||
|
||||
const uploaded = await putPdfFileServerSide(
|
||||
{
|
||||
name: fileName,
|
||||
type: 'application/pdf',
|
||||
arrayBuffer: async () => Promise.resolve(signResult.bytes),
|
||||
},
|
||||
envelopeItem.documentData.initialData ?? undefined,
|
||||
);
|
||||
|
||||
// In-place data update target: the existing envelopeItem.documentDataId
|
||||
// row. `uploaded.documentData` is the freshly-created row whose payload
|
||||
// we'll copy on; that row stays orphan after the copy. Mirrors the
|
||||
// `materializeTspAnchorsForEnvelope` pattern.
|
||||
signedItemDataUpdates.push({
|
||||
envelopeItemDataId: envelopeItem.documentDataId,
|
||||
uploadedType: uploaded.documentData.type,
|
||||
uploadedData: uploaded.documentData.data,
|
||||
});
|
||||
}
|
||||
|
||||
const legacyDocumentId = mapSecondaryIdToDocumentId(envelope.secondaryId);
|
||||
|
||||
// Single tx: per-item in-place data updates + recipient flip + audit log +
|
||||
// session consume. Atomic across items — if any write fails, the recipient
|
||||
// stays unsigned and the session row stays attached. `envelopeItem.
|
||||
// documentDataId` is preserved across the run; only `documentData.{type,
|
||||
// data}` changes. Mirrors `materializeTspAnchorsForEnvelope`.
|
||||
await prisma.$transaction(async (tx) => {
|
||||
for (const { envelopeItemDataId, uploadedType, uploadedData } of signedItemDataUpdates) {
|
||||
await tx.documentData.update({
|
||||
where: { id: envelopeItemDataId },
|
||||
data: { type: uploadedType, data: uploadedData },
|
||||
});
|
||||
}
|
||||
|
||||
await tx.recipient.update({
|
||||
where: { id: recipient.id },
|
||||
data: {
|
||||
signingStatus: SigningStatus.SIGNED,
|
||||
signedAt: new Date(),
|
||||
},
|
||||
});
|
||||
|
||||
const authOptions = extractDocumentAuthMethods({
|
||||
documentAuth: envelope.authOptions,
|
||||
recipientAuth: recipient.authOptions,
|
||||
});
|
||||
|
||||
await tx.documentAuditLog.create({
|
||||
data: createDocumentAuditLogData({
|
||||
type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_COMPLETED,
|
||||
envelopeId: envelope.id,
|
||||
user: {
|
||||
name: recipient.name,
|
||||
email: recipient.email,
|
||||
},
|
||||
requestMetadata,
|
||||
data: {
|
||||
recipientEmail: recipient.email,
|
||||
recipientName: recipient.name,
|
||||
recipientId: recipient.id,
|
||||
recipientRole: recipient.role,
|
||||
actionAuth: authOptions.derivedRecipientActionAuth,
|
||||
},
|
||||
}),
|
||||
});
|
||||
|
||||
await tx.documentAuditLog.create({
|
||||
data: createDocumentAuditLogData({
|
||||
type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_CSC_SIGNED,
|
||||
envelopeId: envelope.id,
|
||||
user: { name: recipient.name, email: recipient.email },
|
||||
requestMetadata,
|
||||
data: {
|
||||
recipientEmail: recipient.email,
|
||||
recipientName: recipient.name,
|
||||
recipientId: recipient.id,
|
||||
recipientRole: recipient.role,
|
||||
providerId: credential.providerId,
|
||||
credentialId: credential.credentialId,
|
||||
sessionId,
|
||||
numItemsSigned: signedItemDataUpdates.length,
|
||||
signatureAlgorithm: credential.signatureAlgorithm,
|
||||
digestAlgorithm: credential.digestAlgorithm,
|
||||
},
|
||||
}),
|
||||
});
|
||||
|
||||
await consumeCscSession(sessionId, tx);
|
||||
});
|
||||
|
||||
// Post-tx side effects (webhooks, emails, next-signer advancement, seal
|
||||
// job dispatch). Inlined rather than shared with the SES completion path —
|
||||
// the in-tx shape diverges enough (TSP swaps documentDataIds + consumes
|
||||
// the CSC session; SES doesn't) that a shared helper would obscure both.
|
||||
const envelopeWithRelations = await prisma.envelope.findUniqueOrThrow({
|
||||
where: { id: envelope.id },
|
||||
include: { documentMeta: true, recipients: true },
|
||||
});
|
||||
|
||||
await triggerWebhook({
|
||||
event: WebhookTriggerEvents.DOCUMENT_RECIPIENT_COMPLETED,
|
||||
data: ZWebhookDocumentSchema.parse(mapEnvelopeToWebhookDocumentPayload(envelopeWithRelations)),
|
||||
userId: envelope.userId,
|
||||
teamId: envelope.teamId,
|
||||
});
|
||||
|
||||
await jobs.triggerJob({
|
||||
name: 'send.recipient.signed.email',
|
||||
payload: {
|
||||
documentId: legacyDocumentId,
|
||||
recipientId: recipient.id,
|
||||
},
|
||||
});
|
||||
|
||||
const pendingRecipients = await prisma.recipient.findMany({
|
||||
select: {
|
||||
id: true,
|
||||
signingOrder: true,
|
||||
role: true,
|
||||
},
|
||||
where: {
|
||||
envelopeId: envelope.id,
|
||||
signingStatus: { not: SigningStatus.SIGNED },
|
||||
role: { not: RecipientRole.CC },
|
||||
},
|
||||
orderBy: [{ signingOrder: { sort: 'asc', nulls: 'last' } }, { id: 'asc' }],
|
||||
});
|
||||
|
||||
if (pendingRecipients.length > 0) {
|
||||
await jobs.triggerJob({
|
||||
name: 'send.document.pending.email',
|
||||
payload: {
|
||||
envelopeId: envelope.id,
|
||||
recipientId: recipient.id,
|
||||
},
|
||||
});
|
||||
|
||||
// TSP envelopes are forced SEQUENTIAL at send-time; this branch always
|
||||
// fires when pending recipients exist. No `nextSigner` dictation path
|
||||
// — `prepareCscRecipientSigning` doesn't accept one.
|
||||
const [nextRecipient] = pendingRecipients;
|
||||
|
||||
await prisma.recipient.update({
|
||||
where: { id: nextRecipient.id },
|
||||
data: {
|
||||
sendStatus: SendStatus.SENT,
|
||||
sentAt: new Date(),
|
||||
},
|
||||
});
|
||||
|
||||
await jobs.triggerJob({
|
||||
name: 'send.signing.requested.email',
|
||||
payload: {
|
||||
userId: envelope.userId,
|
||||
documentId: legacyDocumentId,
|
||||
recipientId: nextRecipient.id,
|
||||
requestMetadata,
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
const haveAllRecipientsSigned = await prisma.envelope.findFirst({
|
||||
where: {
|
||||
id: envelope.id,
|
||||
recipients: {
|
||||
every: {
|
||||
OR: [{ signingStatus: SigningStatus.SIGNED }, { role: RecipientRole.CC }],
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
if (haveAllRecipientsSigned) {
|
||||
await jobs.triggerJob({
|
||||
name: 'internal.seal-document',
|
||||
payload: {
|
||||
documentId: legacyDocumentId,
|
||||
requestMetadata,
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
const updatedDocument = await prisma.envelope.findFirstOrThrow({
|
||||
where: {
|
||||
id: envelope.id,
|
||||
type: EnvelopeType.DOCUMENT,
|
||||
},
|
||||
include: {
|
||||
documentMeta: true,
|
||||
recipients: true,
|
||||
},
|
||||
});
|
||||
|
||||
await triggerWebhook({
|
||||
event: WebhookTriggerEvents.DOCUMENT_SIGNED,
|
||||
data: ZWebhookDocumentSchema.parse(mapEnvelopeToWebhookDocumentPayload(updatedDocument)),
|
||||
userId: updatedDocument.userId,
|
||||
teamId: updatedDocument.teamId ?? undefined,
|
||||
});
|
||||
|
||||
return { outcome: 'signed' };
|
||||
};
|
||||
@@ -0,0 +1,130 @@
|
||||
import type { RequestMetadata } from '@documenso/lib/universal/extract-request-metadata';
|
||||
import { getFileServerSide } from '@documenso/lib/universal/upload/get-file.server';
|
||||
import { putPdfFileServerSide } from '@documenso/lib/universal/upload/put-file.server';
|
||||
import type { CreateDocumentAuditLogDataResponse } from '@documenso/lib/utils/document-audit-logs';
|
||||
import { prisma } from '@documenso/prisma';
|
||||
import { HttpTimestampAuthority, PDF, type TimestampAuthority } from '@libpdf/core';
|
||||
import type { DocumentData, DocumentMeta, Envelope, EnvelopeItem, Recipient, User } from '@prisma/client';
|
||||
import { DocumentStatus } from '@prisma/client';
|
||||
|
||||
import { resolveCscSealTimeTsa } from './tsa-resolver';
|
||||
|
||||
/**
|
||||
* TSP envelope finalisation step run from the `seal-document` job.
|
||||
*
|
||||
* Replaces the SES "decorate + p12 sign" pass: recipient bytes are already
|
||||
* PAdES-signed by each recipient's CSC TSP, so the seal step is reduced to
|
||||
* a per-item PAdES B-LTA upgrade — libpdf's `pdf.addArchivalData()` runs
|
||||
* the full archive sequence (DSS for every existing signature + archival
|
||||
* `/DocTimeStamp` + DSS for the timestamp's own chain), and the resulting
|
||||
* bytes are copied in-place onto each `envelopeItem.documentData` row.
|
||||
* `envelopeItem.documentDataId` stays stable across the whole envelope
|
||||
* lifecycle (materialise → per-recipient signs → finalise) — mirrors the
|
||||
* pattern used by `materializeTspAnchorsForEnvelope` and `executeTspSign`.
|
||||
*
|
||||
* Certificate / audit-log sidecar PDFs are intentionally NOT merged into
|
||||
* the signed bytes here — they're rendered on-demand at download time so
|
||||
* the signed PDF stays byte-identical to what each recipient's SAD
|
||||
* authorised. Rejection and resealing are unsupported in V1 and rejected
|
||||
* by the caller before this runs.
|
||||
*/
|
||||
|
||||
export type FinalizeTspEnvelopeCompletionOptions = {
|
||||
envelope: Envelope & {
|
||||
documentMeta: DocumentMeta | null;
|
||||
recipients: Recipient[];
|
||||
envelopeItems: Array<EnvelopeItem & { documentData: DocumentData }>;
|
||||
user: Pick<User, 'name' | 'email'>;
|
||||
};
|
||||
envelopeCompletedAuditLog: CreateDocumentAuditLogDataResponse;
|
||||
requestMetadata?: RequestMetadata;
|
||||
};
|
||||
|
||||
type ArchivedItem = {
|
||||
/** Existing `envelopeItem.documentDataId` — target of the in-place update. */
|
||||
envelopeItemDataId: string;
|
||||
uploadedType: DocumentData['type'];
|
||||
uploadedData: string;
|
||||
};
|
||||
|
||||
export const finalizeTspEnvelopeCompletion = async (opts: FinalizeTspEnvelopeCompletionOptions): Promise<void> => {
|
||||
const { envelope, envelopeCompletedAuditLog } = opts;
|
||||
|
||||
// Resolve the TSA up-front — fail fast if the instance is mis-configured
|
||||
// before we start round-tripping PDF bytes through storage.
|
||||
const tsa = resolveCscSealTimeTsa();
|
||||
const timestampAuthority = buildLibpdfTsa(tsa);
|
||||
|
||||
const archivedItems: ArchivedItem[] = [];
|
||||
|
||||
for (const envelopeItem of envelope.envelopeItems) {
|
||||
const pdfBytes = await getFileServerSide(envelopeItem.documentData);
|
||||
const pdfDoc = await PDF.load(pdfBytes);
|
||||
|
||||
// PAdES B-LTA in one call. Internally:
|
||||
// 1. Gather LTV (certs/OCSP/CRL) for every existing signed field and
|
||||
// write a single DSS incremental update.
|
||||
// 2. Add an archival `/DocTimeStamp` over the result.
|
||||
// 3. Gather LTV for the new timestamp's own certificate chain.
|
||||
// All three are append-only incremental updates — every prior recipient
|
||||
// signature's `/ByteRange` stays valid.
|
||||
const archived = await pdfDoc.addArchivalData({ timestampAuthority });
|
||||
|
||||
const { documentData: uploaded } = await putPdfFileServerSide(
|
||||
{
|
||||
name: envelopeItem.title.endsWith('.pdf') ? envelopeItem.title : `${envelopeItem.title}.pdf`,
|
||||
type: 'application/pdf',
|
||||
arrayBuffer: async () => Promise.resolve(archived.bytes),
|
||||
},
|
||||
envelopeItem.documentData.initialData,
|
||||
);
|
||||
|
||||
archivedItems.push({
|
||||
envelopeItemDataId: envelopeItem.documentData.id,
|
||||
uploadedType: uploaded.type,
|
||||
uploadedData: uploaded.data,
|
||||
});
|
||||
}
|
||||
|
||||
// Single tx: per-item in-place data updates + envelope status flip +
|
||||
// completion audit log. `envelopeItem.documentDataId` is preserved; the
|
||||
// freshly-uploaded `DocumentData` rows orbit as orphans.
|
||||
await prisma.$transaction(async (tx) => {
|
||||
for (const { envelopeItemDataId, uploadedType, uploadedData } of archivedItems) {
|
||||
await tx.documentData.update({
|
||||
where: { id: envelopeItemDataId },
|
||||
data: { type: uploadedType, data: uploadedData },
|
||||
});
|
||||
}
|
||||
|
||||
await tx.envelope.update({
|
||||
where: { id: envelope.id },
|
||||
data: {
|
||||
status: DocumentStatus.COMPLETED,
|
||||
completedAt: new Date(),
|
||||
},
|
||||
});
|
||||
|
||||
await tx.documentAuditLog.create({
|
||||
data: envelopeCompletedAuditLog,
|
||||
});
|
||||
});
|
||||
};
|
||||
|
||||
/**
|
||||
* Wrap a resolved seal-time TSA config into a libpdf `TimestampAuthority`.
|
||||
*
|
||||
* Env only at seal time — the archival `/DocTimeStamp` is the operator's
|
||||
* long-term trust anchor and SHOULD point at a dedicated qualified archival
|
||||
* TSA (e.g. DigiCert) that's independent of the per-recipient TSP. We
|
||||
* deliberately don't fall back to the TSP here: doing so would couple the
|
||||
* archive's longevity to a TSP that may revoke or rotate without notice,
|
||||
* and would require keeping a live service-scope bearer around at the
|
||||
* seal-document job which has no recipient context anyway.
|
||||
*
|
||||
* First URL only — multi-URL fallback can layer on later via a composite
|
||||
* wrapper if operators need it.
|
||||
*/
|
||||
const buildLibpdfTsa = (tsa: { urls: string[] }): TimestampAuthority => {
|
||||
return new HttpTimestampAuthority(tsa.urls[0]);
|
||||
};
|
||||
@@ -0,0 +1,16 @@
|
||||
import type { logger } from '@documenso/lib/utils/logger';
|
||||
|
||||
/**
|
||||
* CSC subapp Hono context. Mirrors the subset of `apps/remix/server/router.ts`
|
||||
* `HonoEnv` that CSC handlers actually read. Duplicated (rather than imported
|
||||
* from `apps/remix/`) to keep the `packages/ee` → `apps/remix` dep direction
|
||||
* unidirectional.
|
||||
*
|
||||
* Runtime contract: the remix host's middleware sets `logger` on every request
|
||||
* before the CSC subapp runs; the CSC subapp does not set it itself.
|
||||
*/
|
||||
export type HonoCscEnv = {
|
||||
Variables: {
|
||||
logger: typeof logger;
|
||||
};
|
||||
};
|
||||
@@ -0,0 +1,63 @@
|
||||
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
import { Hono } from 'hono';
|
||||
import { HTTPException } from 'hono/http-exception';
|
||||
import type { ContentfulStatusCode } from 'hono/utils/http-status';
|
||||
|
||||
import type { HonoCscEnv } from './context';
|
||||
import { cscOAuthAuthorizeRoute } from './oauth-authorize';
|
||||
import { cscOAuthCallbackRoute } from './oauth-callback';
|
||||
|
||||
/**
|
||||
* `@documenso/ee` CSC subapp. Mount under `/api/csc` in the remix host (see
|
||||
* `apps/remix/server/router.ts`). All CSC endpoints — OAuth authorize +
|
||||
* callback — are composed here so the host only has to wire one route.
|
||||
*
|
||||
* Routes throw `AppError` freely; the `.onError` handler below normalises
|
||||
* them into REST responses (mirrors `@documenso/auth/server`'s pattern).
|
||||
*/
|
||||
export const csc = new Hono<HonoCscEnv>()
|
||||
.route('/oauth/authorize', cscOAuthAuthorizeRoute)
|
||||
.route('/oauth/callback', cscOAuthCallbackRoute);
|
||||
|
||||
csc.onError((err, c) => {
|
||||
const logger = c.get('logger');
|
||||
|
||||
if (err instanceof HTTPException) {
|
||||
return c.json(
|
||||
{
|
||||
code: AppErrorCode.UNKNOWN_ERROR,
|
||||
message: err.message,
|
||||
statusCode: err.status,
|
||||
},
|
||||
err.status,
|
||||
);
|
||||
}
|
||||
|
||||
if (err instanceof AppError) {
|
||||
const { status, body } = AppError.toRestAPIError(err);
|
||||
|
||||
logger.error({
|
||||
event: 'csc.error',
|
||||
code: err.code,
|
||||
message: err.message,
|
||||
});
|
||||
|
||||
return c.json(body, status as ContentfulStatusCode);
|
||||
}
|
||||
|
||||
logger.error({
|
||||
event: 'csc.unknown_error',
|
||||
error: err,
|
||||
});
|
||||
|
||||
return c.json(
|
||||
{
|
||||
code: AppErrorCode.UNKNOWN_ERROR,
|
||||
message: 'Internal Server Error',
|
||||
statusCode: 500,
|
||||
},
|
||||
500,
|
||||
);
|
||||
});
|
||||
|
||||
export type CscAppType = typeof csc;
|
||||
@@ -0,0 +1,154 @@
|
||||
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
import { getRecipientByToken } from '@documenso/lib/server-only/recipient/get-recipient-by-token';
|
||||
import { prisma } from '@documenso/prisma';
|
||||
import { sValidator } from '@hono/standard-validator';
|
||||
import { Hono } from 'hono';
|
||||
import { z } from 'zod';
|
||||
|
||||
import {
|
||||
buildCscCredentialScopeAuthorizeUrl,
|
||||
buildCscServiceScopeAuthorizeUrl,
|
||||
generateCodeVerifier,
|
||||
generateState,
|
||||
} from '../client/oauth';
|
||||
import { setCscOAuthFlowCookie } from '../cookies/oauth-flow-cookie';
|
||||
import { loadCscCredential } from '../credential';
|
||||
import { loadCscSession } from '../sign-session';
|
||||
import { getCscTransport } from '../transport';
|
||||
import type { HonoCscEnv } from './context';
|
||||
|
||||
/**
|
||||
* `GET /api/csc/oauth/authorize` — initiates the CSC OAuth round-trip and
|
||||
* 302-redirects to the TSP's authorize URL with a signed `csc_oauth_flow`
|
||||
* cookie carrying the state, PKCE verifier, and recipient context the
|
||||
* callback needs to resume the flow.
|
||||
*
|
||||
* Branches on `?scope=service|credential`:
|
||||
* - `service`: authorised by recipient token; precedes credentials/list.
|
||||
* - `credential`: authorised by an active `CscSession`; binds the issued SAD
|
||||
* to the per-item hashes captured at prep.
|
||||
*
|
||||
* Errors bubble to the parent app's `.onError` handler (see `./index.ts`).
|
||||
*/
|
||||
|
||||
const ZAuthorizeQuerySchema = z.discriminatedUnion('scope', [
|
||||
z.object({
|
||||
scope: z.literal('service'),
|
||||
token: z.string().min(1),
|
||||
}),
|
||||
z.object({
|
||||
scope: z.literal('credential'),
|
||||
session: z.string().min(1),
|
||||
}),
|
||||
]);
|
||||
|
||||
export const cscOAuthAuthorizeRoute = new Hono<HonoCscEnv>().get(
|
||||
'/',
|
||||
sValidator('query', ZAuthorizeQuerySchema),
|
||||
async (c) => {
|
||||
const logger = c.get('logger');
|
||||
|
||||
const query = c.req.valid('query');
|
||||
|
||||
const transport = await getCscTransport();
|
||||
|
||||
if (query.scope === 'service') {
|
||||
const recipient = await getRecipientByToken({ token: query.token }).catch(() => null);
|
||||
|
||||
if (!recipient) {
|
||||
throw new AppError(AppErrorCode.NOT_FOUND, {
|
||||
message: 'Recipient not found for the provided token.',
|
||||
});
|
||||
}
|
||||
|
||||
logger.info({
|
||||
event: 'csc.oauth.authorize.start',
|
||||
scope: 'service',
|
||||
recipientId: recipient.id,
|
||||
});
|
||||
|
||||
const state = generateState();
|
||||
const codeVerifier = generateCodeVerifier();
|
||||
|
||||
const authorizeUrl = buildCscServiceScopeAuthorizeUrl({
|
||||
client: transport.oauthClient,
|
||||
oauthBaseUrl: transport.oauthBaseUrl,
|
||||
state,
|
||||
codeVerifier,
|
||||
});
|
||||
|
||||
await setCscOAuthFlowCookie({
|
||||
c,
|
||||
payload: {
|
||||
scope: 'service',
|
||||
state,
|
||||
codeVerifier,
|
||||
recipientToken: query.token,
|
||||
},
|
||||
});
|
||||
|
||||
return c.redirect(authorizeUrl.toString(), 302);
|
||||
}
|
||||
|
||||
const session = await loadCscSession(query.session);
|
||||
|
||||
if (!session) {
|
||||
throw new AppError(AppErrorCode.NOT_FOUND, {
|
||||
message: 'CSC session not found or already consumed.',
|
||||
});
|
||||
}
|
||||
|
||||
const credential = await loadCscCredential(session.recipientId);
|
||||
|
||||
if (!credential) {
|
||||
throw new AppError(AppErrorCode.NOT_FOUND, {
|
||||
message: 'CSC credential missing — service-scope OAuth must complete first.',
|
||||
});
|
||||
}
|
||||
|
||||
const recipient = await prisma.recipient.findUnique({
|
||||
where: { id: session.recipientId },
|
||||
select: { token: true },
|
||||
});
|
||||
|
||||
if (!recipient) {
|
||||
throw new AppError(AppErrorCode.NOT_FOUND, {
|
||||
message: 'Recipient not found for the CSC session.',
|
||||
});
|
||||
}
|
||||
|
||||
logger.info({
|
||||
event: 'csc.oauth.authorize.start',
|
||||
scope: 'credential',
|
||||
recipientId: session.recipientId,
|
||||
sessionId: session.id,
|
||||
numSignatures: session.items.length,
|
||||
});
|
||||
|
||||
const state = generateState();
|
||||
const codeVerifier = generateCodeVerifier();
|
||||
|
||||
const authorizeUrl = buildCscCredentialScopeAuthorizeUrl({
|
||||
client: transport.oauthClient,
|
||||
oauthBaseUrl: transport.oauthBaseUrl,
|
||||
state,
|
||||
codeVerifier,
|
||||
credentialId: credential.credentialId,
|
||||
numSignatures: session.items.length,
|
||||
hashes: session.items.map((item) => item.hashB64),
|
||||
});
|
||||
|
||||
await setCscOAuthFlowCookie({
|
||||
c,
|
||||
payload: {
|
||||
scope: 'credential',
|
||||
state,
|
||||
codeVerifier,
|
||||
recipientToken: recipient.token,
|
||||
sessionId: session.id,
|
||||
},
|
||||
});
|
||||
|
||||
return c.redirect(authorizeUrl.toString(), 302);
|
||||
},
|
||||
);
|
||||
@@ -0,0 +1,303 @@
|
||||
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
import { getRecipientByToken } from '@documenso/lib/server-only/recipient/get-recipient-by-token';
|
||||
import { DOCUMENT_AUDIT_LOG_TYPE } from '@documenso/lib/types/document-audit-logs';
|
||||
import { extractRequestMetadata } from '@documenso/lib/universal/extract-request-metadata';
|
||||
import { createDocumentAuditLogData } from '@documenso/lib/utils/document-audit-logs';
|
||||
import { formatSigningLink } from '@documenso/lib/utils/recipients';
|
||||
import { prisma } from '@documenso/prisma';
|
||||
import { sValidator } from '@hono/standard-validator';
|
||||
import { Hono } from 'hono';
|
||||
import { z } from 'zod';
|
||||
|
||||
import { resolveCscAlgorithmPolicy } from '../algorithm-resolver';
|
||||
import { encodeCscCertChain } from '../cert-chain';
|
||||
import { encryptCscToken } from '../ciphers';
|
||||
import { cscCredentialsInfo, cscCredentialsList } from '../client/credentials';
|
||||
import { exchangeCscAuthorizationCode } from '../client/oauth';
|
||||
import { setCscBlockingErrorCookie } from '../cookies/blocking-error-cookie';
|
||||
import { clearCscOAuthFlowCookie, getCscOAuthFlowCookie } from '../cookies/oauth-flow-cookie';
|
||||
import { setCscSadSessionCookie } from '../cookies/sad-session-cookie';
|
||||
import { setCscServiceSessionCookie } from '../cookies/service-session-cookie';
|
||||
import { loadCscCredential, upsertCscCredential } from '../credential';
|
||||
import { updateCscSessionWithSad } from '../sign-session';
|
||||
import { getCscTransport } from '../transport';
|
||||
import type { HonoCscEnv } from './context';
|
||||
|
||||
/**
|
||||
* `GET /api/csc/oauth/callback` — landing point for the recipient's return
|
||||
* from the TSP after the round-trip initiated by `oauth-authorize`. Reads
|
||||
* the `csc_oauth_flow` cookie, verifies CSRF, exchanges the code, and
|
||||
* branches on the cookie's `scope`:
|
||||
*
|
||||
* - `service`: pulls `credentials/list` + `credentials/info`, validates the
|
||||
* cert + algorithm policy, persists the `CscCredential` row + service
|
||||
* token, sets the `csc_service_session` cookie, and redirects to
|
||||
* `/sign/{token}`. Blocking validation errors (empty list, bad cert,
|
||||
* refused algorithm) round-trip via the `csc_blocking_error` cookie so the
|
||||
* signing-page loader can render a stable error UI.
|
||||
* - `credential`: exchanges code → SAD, stamps it onto the existing
|
||||
* `CscSession`, sets the `csc_sad_session` cookie, and redirects to
|
||||
* `/sign/{token}`. Credential-scope failures bubble to `.onError` — the
|
||||
* recipient simply re-clicks Sign.
|
||||
*
|
||||
* Non-blocking errors bubble to the parent app's `.onError` (see
|
||||
* `./index.ts`) — mirrors `oauth-authorize.ts`.
|
||||
*/
|
||||
|
||||
const ZCallbackQuerySchema = z.object({
|
||||
state: z.string().min(1),
|
||||
code: z.string().min(1).optional(),
|
||||
error: z.string().min(1).optional(),
|
||||
error_description: z.string().optional(),
|
||||
});
|
||||
|
||||
const BLOCKING_SERVICE_ERROR_CODES = new Set<string>([
|
||||
AppErrorCode.CSC_CREDENTIAL_LIST_EMPTY,
|
||||
AppErrorCode.CSC_CERT_INVALID,
|
||||
AppErrorCode.CSC_ALGORITHM_REFUSED,
|
||||
]);
|
||||
|
||||
const isBlockingServiceError = (code: string): boolean => BLOCKING_SERVICE_ERROR_CODES.has(code);
|
||||
|
||||
export const cscOAuthCallbackRoute = new Hono<HonoCscEnv>().get(
|
||||
'/',
|
||||
sValidator('query', ZCallbackQuerySchema),
|
||||
async (c) => {
|
||||
const logger = c.get('logger');
|
||||
|
||||
const query = c.req.valid('query');
|
||||
|
||||
const cookie = await getCscOAuthFlowCookie(c);
|
||||
|
||||
if (!cookie) {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: 'CSC OAuth flow cookie missing or expired.',
|
||||
});
|
||||
}
|
||||
|
||||
if (query.state !== cookie.state) {
|
||||
throw new AppError(AppErrorCode.UNAUTHORIZED, {
|
||||
message: 'CSC OAuth callback state mismatch — possible CSRF.',
|
||||
});
|
||||
}
|
||||
|
||||
// The single-round-trip carrier is spent regardless of subsequent
|
||||
// outcome; clear it now so a retry restarts from `/api/csc/oauth/authorize`.
|
||||
clearCscOAuthFlowCookie(c);
|
||||
|
||||
if (query.error) {
|
||||
throw new AppError(AppErrorCode.CSC_REQUEST_FAILED, {
|
||||
message: `CSC TSP returned OAuth error: ${query.error}${query.error_description ? ' — ' + query.error_description : ''}`,
|
||||
});
|
||||
}
|
||||
|
||||
if (!query.code) {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: 'CSC OAuth callback missing code parameter.',
|
||||
});
|
||||
}
|
||||
|
||||
const transport = await getCscTransport();
|
||||
|
||||
const recipient = await getRecipientByToken({ token: cookie.recipientToken }).catch(() => null);
|
||||
|
||||
if (!recipient) {
|
||||
throw new AppError(AppErrorCode.NOT_FOUND, {
|
||||
message: 'Recipient not found for CSC OAuth flow cookie.',
|
||||
});
|
||||
}
|
||||
|
||||
if (cookie.scope === 'service') {
|
||||
const tokens = await exchangeCscAuthorizationCode({
|
||||
client: transport.oauthClient,
|
||||
oauthBaseUrl: transport.oauthBaseUrl,
|
||||
code: query.code,
|
||||
codeVerifier: cookie.codeVerifier,
|
||||
});
|
||||
|
||||
try {
|
||||
const listResp = await cscCredentialsList({
|
||||
baseUrl: transport.serviceBaseUrl,
|
||||
accessToken: tokens.accessToken(),
|
||||
});
|
||||
|
||||
// V1 picks the first credential per spec section "Out of scope for
|
||||
// V1": multi-credential selection UI lands in a later iteration.
|
||||
const credentialId = listResp.credentialIDs[0];
|
||||
|
||||
const infoResp = await cscCredentialsInfo({
|
||||
baseUrl: transport.serviceBaseUrl,
|
||||
accessToken: tokens.accessToken(),
|
||||
credentialID: credentialId,
|
||||
certificates: 'chain',
|
||||
certInfo: true,
|
||||
});
|
||||
|
||||
const policy = resolveCscAlgorithmPolicy(infoResp);
|
||||
|
||||
if (!infoResp.cert.certificates || infoResp.cert.certificates.length === 0) {
|
||||
throw new AppError(AppErrorCode.CSC_CERT_INVALID, {
|
||||
message: 'CSC credential info response omitted required certificate chain.',
|
||||
});
|
||||
}
|
||||
|
||||
const certCache = encodeCscCertChain(infoResp.cert.certificates);
|
||||
const serviceTokenCiphertext = encryptCscToken(tokens.accessToken());
|
||||
const serviceTokenExpiresAt = tokens.accessTokenExpiresAt();
|
||||
|
||||
await upsertCscCredential({
|
||||
recipientId: recipient.id,
|
||||
providerId: transport.serviceBaseUrl,
|
||||
credentialId,
|
||||
certCache,
|
||||
signatureAlgorithm: policy.signAlgoOid,
|
||||
keyType: policy.keyType,
|
||||
digestAlgorithm: policy.digestAlgorithm,
|
||||
keyLenBits: policy.keyLenBits,
|
||||
serviceTokenCiphertext,
|
||||
serviceTokenExpiresAt,
|
||||
});
|
||||
|
||||
await setCscServiceSessionCookie({
|
||||
c,
|
||||
recipientToken: cookie.recipientToken,
|
||||
ttlSeconds: tokens.accessTokenExpiresInSeconds(),
|
||||
});
|
||||
|
||||
await prisma.documentAuditLog.create({
|
||||
data: createDocumentAuditLogData({
|
||||
type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_CSC_AUTHENTICATED,
|
||||
envelopeId: recipient.envelopeId,
|
||||
user: { name: recipient.name, email: recipient.email },
|
||||
requestMetadata: extractRequestMetadata(c.req.raw),
|
||||
data: {
|
||||
recipientEmail: recipient.email,
|
||||
recipientName: recipient.name,
|
||||
recipientId: recipient.id,
|
||||
recipientRole: recipient.role,
|
||||
providerId: transport.serviceBaseUrl,
|
||||
credentialId,
|
||||
signatureAlgorithm: policy.signAlgoOid,
|
||||
digestAlgorithm: policy.digestAlgorithm,
|
||||
},
|
||||
}),
|
||||
});
|
||||
|
||||
logger.info({
|
||||
event: 'csc.oauth.callback.service.complete',
|
||||
recipientId: recipient.id,
|
||||
});
|
||||
|
||||
return c.redirect(formatSigningLink(cookie.recipientToken), 302);
|
||||
} catch (err) {
|
||||
if (err instanceof AppError && isBlockingServiceError(err.code)) {
|
||||
await setCscBlockingErrorCookie({
|
||||
c,
|
||||
payload: { code: err.code, recipientToken: cookie.recipientToken },
|
||||
});
|
||||
|
||||
await prisma.documentAuditLog.create({
|
||||
data: createDocumentAuditLogData({
|
||||
type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_CSC_AUTHENTICATION_FAILED,
|
||||
envelopeId: recipient.envelopeId,
|
||||
user: { name: recipient.name, email: recipient.email },
|
||||
requestMetadata: extractRequestMetadata(c.req.raw),
|
||||
data: {
|
||||
recipientEmail: recipient.email,
|
||||
recipientName: recipient.name,
|
||||
recipientId: recipient.id,
|
||||
recipientRole: recipient.role,
|
||||
providerId: transport.serviceBaseUrl,
|
||||
reason: err.code,
|
||||
},
|
||||
}),
|
||||
});
|
||||
|
||||
logger.warn({
|
||||
event: 'csc.oauth.callback.service.blocking',
|
||||
recipientId: recipient.id,
|
||||
code: err.code,
|
||||
});
|
||||
|
||||
return c.redirect(formatSigningLink(cookie.recipientToken), 302);
|
||||
}
|
||||
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
|
||||
if (!cookie.sessionId) {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: 'CSC credential-scope OAuth callback missing sessionId in cookie.',
|
||||
});
|
||||
}
|
||||
|
||||
const tokens = await exchangeCscAuthorizationCode({
|
||||
client: transport.oauthClient,
|
||||
oauthBaseUrl: transport.oauthBaseUrl,
|
||||
code: query.code,
|
||||
codeVerifier: cookie.codeVerifier,
|
||||
});
|
||||
|
||||
// CSC §8.3.3 says credential-scope returns `token_type === 'SAD'`. We
|
||||
// don't hard-fail on a divergent label — the binding is by scope + hash,
|
||||
// not by `token_type` — but we log so operator metrics can spot loose
|
||||
// TSPs.
|
||||
if (tokens.tokenType() !== 'SAD') {
|
||||
logger.warn({
|
||||
event: 'csc.oauth.callback.credential.unexpected_token_type',
|
||||
actual: tokens.tokenType(),
|
||||
});
|
||||
}
|
||||
|
||||
const sadCiphertext = encryptCscToken(tokens.accessToken());
|
||||
const sadExpiresAt = tokens.accessTokenExpiresAt();
|
||||
|
||||
await updateCscSessionWithSad({
|
||||
sessionId: cookie.sessionId,
|
||||
encryptedSad: sadCiphertext,
|
||||
sadExpiresAt,
|
||||
});
|
||||
|
||||
await setCscSadSessionCookie({
|
||||
c,
|
||||
sessionId: cookie.sessionId,
|
||||
expiresAt: sadExpiresAt,
|
||||
});
|
||||
|
||||
const credential = await loadCscCredential(recipient.id);
|
||||
|
||||
if (!credential) {
|
||||
throw new AppError(AppErrorCode.NOT_FOUND, {
|
||||
message: 'CSC credential missing at credential-scope callback.',
|
||||
});
|
||||
}
|
||||
|
||||
await prisma.documentAuditLog.create({
|
||||
data: createDocumentAuditLogData({
|
||||
type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_CSC_AUTHORIZED,
|
||||
envelopeId: recipient.envelopeId,
|
||||
user: { name: recipient.name, email: recipient.email },
|
||||
requestMetadata: extractRequestMetadata(c.req.raw),
|
||||
data: {
|
||||
recipientEmail: recipient.email,
|
||||
recipientName: recipient.name,
|
||||
recipientId: recipient.id,
|
||||
recipientRole: recipient.role,
|
||||
providerId: credential.providerId,
|
||||
credentialId: credential.credentialId,
|
||||
sessionId: cookie.sessionId,
|
||||
sadExpiresAt,
|
||||
},
|
||||
}),
|
||||
});
|
||||
|
||||
logger.info({
|
||||
event: 'csc.oauth.callback.credential.complete',
|
||||
recipientId: recipient.id,
|
||||
sessionId: cookie.sessionId,
|
||||
});
|
||||
|
||||
return c.redirect(formatSigningLink(cookie.recipientToken), 302);
|
||||
},
|
||||
);
|
||||
@@ -0,0 +1,230 @@
|
||||
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
import { isTspEnvelope } from '@documenso/lib/types/signature-level';
|
||||
import { getFileServerSide } from '@documenso/lib/universal/upload/get-file.server';
|
||||
import { putPdfFileServerSide } from '@documenso/lib/universal/upload/put-file.server';
|
||||
import { prisma } from '@documenso/prisma';
|
||||
import { PDF } from '@libpdf/core';
|
||||
|
||||
import { buildTspAnchorName, buildTspStampName } from './pdf-names';
|
||||
|
||||
export type MaterializeTspAnchorsForEnvelopeOptions = {
|
||||
envelopeId: string;
|
||||
};
|
||||
|
||||
/**
|
||||
* Pre-allocate per-recipient AcroForm signature anchors and per-page `/Stamp`
|
||||
* overlay annotations on every envelope item of a TSP (AES/QES) envelope.
|
||||
*
|
||||
* Mutates the existing `DocumentData` row in place — the `envelopeItem.
|
||||
* documentDataId` pointer is preserved across materialisation. Materialise
|
||||
* is distribution housekeeping (pre-allocate fixed anchor slots before any
|
||||
* recipient signs), not a content version bump, so a pointer swap +
|
||||
* audit-log entry would mis-attribute the change. The new uploaded row
|
||||
* created by `putPdfFileServerSide` is kept as an orphan rather than
|
||||
* deleted — it preserves the standard upload mechanics (S3 PUT or BYTES_64
|
||||
* encode) without a separate "copy then drop" dance.
|
||||
*
|
||||
* Idempotent: re-runs are no-ops when every expected anchor/stamp is
|
||||
* already present. No-op for SES envelopes.
|
||||
*/
|
||||
export const materializeTspAnchorsForEnvelope = async ({
|
||||
envelopeId,
|
||||
}: MaterializeTspAnchorsForEnvelopeOptions): Promise<void> => {
|
||||
const envelope = await prisma.envelope.findUnique({
|
||||
where: {
|
||||
id: envelopeId,
|
||||
},
|
||||
include: {
|
||||
recipients: true,
|
||||
envelopeItems: {
|
||||
include: {
|
||||
documentData: true,
|
||||
},
|
||||
},
|
||||
fields: {
|
||||
select: {
|
||||
recipientId: true,
|
||||
envelopeItemId: true,
|
||||
page: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
if (!envelope) {
|
||||
throw new AppError(AppErrorCode.NOT_FOUND, {
|
||||
message: `Envelope ${envelopeId} not found`,
|
||||
});
|
||||
}
|
||||
|
||||
if (!isTspEnvelope(envelope)) {
|
||||
return;
|
||||
}
|
||||
|
||||
if (envelope.recipients.length === 0) {
|
||||
return;
|
||||
}
|
||||
|
||||
for (const envelopeItem of envelope.envelopeItems) {
|
||||
const expectedAnchorNames = envelope.recipients.map((recipient) =>
|
||||
buildTspAnchorName(recipient.id, envelopeItem.id),
|
||||
);
|
||||
|
||||
const expectedStampNames: string[] = [];
|
||||
|
||||
for (const recipient of envelope.recipients) {
|
||||
const pagesWithFields = new Set<number>();
|
||||
|
||||
for (const field of envelope.fields) {
|
||||
if (field.recipientId === recipient.id && field.envelopeItemId === envelopeItem.id) {
|
||||
pagesWithFields.add(field.page);
|
||||
}
|
||||
}
|
||||
|
||||
for (const page of pagesWithFields) {
|
||||
expectedStampNames.push(buildTspStampName(recipient.id, envelopeItem.id, page));
|
||||
}
|
||||
}
|
||||
|
||||
const bytes = await getFileServerSide(envelopeItem.documentData);
|
||||
const pdfDoc = await PDF.load(bytes);
|
||||
|
||||
if (isAlreadyMaterialised(pdfDoc, expectedAnchorNames, expectedStampNames)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
// Bake operator AcroForm, annotations and OCG layers into static graphics
|
||||
// so the materialised PDF is a deterministic surface. `skipSignatures`
|
||||
// preserves any operator-placed signature widgets and (on re-materialise)
|
||||
// the TSP anchors created previously.
|
||||
pdfDoc.flattenAll({
|
||||
form: {
|
||||
skipSignatures: true,
|
||||
},
|
||||
});
|
||||
|
||||
const form = pdfDoc.getOrCreateForm();
|
||||
|
||||
if (pdfDoc.getPageCount() === 0) {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: `Envelope item ${envelopeItem.id} PDF has no pages`,
|
||||
});
|
||||
}
|
||||
|
||||
// Anchors are AcroForm signature fields with no pre-attached widget.
|
||||
// libpdf forbids `drawField` for signature fields — at sign time
|
||||
// `pdf.sign({ fieldName })` promotes the existing field dict in place
|
||||
// to a merged field/widget (Type=Annot, Subtype=Widget, P=page0,
|
||||
// Rect=[0,0,0,0]) without modifying the page object. That preserves the
|
||||
// per-recipient `/ByteRange` invariant across sequential signatures.
|
||||
for (const anchorName of expectedAnchorNames) {
|
||||
if (form.getSignatureField(anchorName)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
form.createSignatureField(anchorName);
|
||||
}
|
||||
|
||||
for (const recipient of envelope.recipients) {
|
||||
const pagesWithFields = new Set<number>();
|
||||
|
||||
for (const field of envelope.fields) {
|
||||
if (field.recipientId === recipient.id && field.envelopeItemId === envelopeItem.id) {
|
||||
pagesWithFields.add(field.page);
|
||||
}
|
||||
}
|
||||
|
||||
for (const pageNumber of pagesWithFields) {
|
||||
const stampName = buildTspStampName(recipient.id, envelopeItem.id, pageNumber);
|
||||
const page = pdfDoc.getPage(pageNumber - 1);
|
||||
|
||||
if (!page) {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: `Envelope item ${envelopeItem.id} missing page ${pageNumber} referenced by field`,
|
||||
});
|
||||
}
|
||||
|
||||
const existing = page.getStampAnnotations().some((stamp) => stamp.stampName === stampName);
|
||||
|
||||
if (existing) {
|
||||
continue;
|
||||
}
|
||||
|
||||
page.addStampAnnotation({
|
||||
name: stampName,
|
||||
rect: {
|
||||
x: 0,
|
||||
y: 0,
|
||||
width: page.width,
|
||||
height: page.height,
|
||||
},
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
const newBytes = await pdfDoc.save({ useXRefStream: true });
|
||||
|
||||
// CRITICAL: persist via `putPdfFileServerSide` (raw). The normalised path
|
||||
// would call `form.flatten()` without `skipSignatures` and wipe anchors.
|
||||
const fileName = envelope.title.endsWith('.pdf') ? envelope.title : `${envelope.title || 'envelope'}.pdf`;
|
||||
|
||||
const uploaded = await putPdfFileServerSide(
|
||||
{
|
||||
name: fileName,
|
||||
type: 'application/pdf',
|
||||
arrayBuffer: async () => Promise.resolve(newBytes),
|
||||
},
|
||||
envelopeItem.documentData.initialData ?? undefined,
|
||||
);
|
||||
|
||||
// Copy the persisted bytes reference (S3 key or BYTES_64 payload) onto the
|
||||
// existing DocumentData row in place. `envelopeItem.documentDataId` stays
|
||||
// put — see file-level docblock for the rationale.
|
||||
await prisma.documentData.update({
|
||||
where: { id: envelopeItem.documentDataId },
|
||||
data: {
|
||||
type: uploaded.documentData.type,
|
||||
data: uploaded.documentData.data,
|
||||
},
|
||||
});
|
||||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* Whole-item idempotency probe: returns true only when every expected anchor
|
||||
* and stamp name is already present on the loaded PDF. Partial state is
|
||||
* treated as not-materialised — the whole item is rebuilt.
|
||||
*/
|
||||
const isAlreadyMaterialised = (pdfDoc: PDF, expectedAnchorNames: string[], expectedStampNames: string[]): boolean => {
|
||||
const form = pdfDoc.getForm();
|
||||
|
||||
if (!form) {
|
||||
return expectedAnchorNames.length === 0 && expectedStampNames.length === 0;
|
||||
}
|
||||
|
||||
for (const anchorName of expectedAnchorNames) {
|
||||
if (!form.getSignatureField(anchorName)) {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
if (expectedStampNames.length === 0) {
|
||||
return true;
|
||||
}
|
||||
|
||||
const presentStampNames = new Set<string>();
|
||||
|
||||
for (let i = 0; i < pdfDoc.getPageCount(); i++) {
|
||||
const page = pdfDoc.getPage(i);
|
||||
|
||||
if (!page) {
|
||||
continue;
|
||||
}
|
||||
|
||||
for (const stamp of page.getStampAnnotations()) {
|
||||
presentStampNames.add(stamp.stampName);
|
||||
}
|
||||
}
|
||||
|
||||
return expectedStampNames.every((name) => presentStampNames.has(name));
|
||||
};
|
||||
@@ -0,0 +1,23 @@
|
||||
import { bytesToHex, utf8ToBytes } from '@noble/ciphers/utils';
|
||||
import { sha1 } from '@noble/hashes/legacy';
|
||||
|
||||
/**
|
||||
* Deterministic PDF object names for CSC TSP signing.
|
||||
*
|
||||
* Materialise-time and sign-time both derive these from the same
|
||||
* `(recipient, item [, page])` tuple — they MUST agree byte-for-byte.
|
||||
*
|
||||
* Output is opaque: SHA-1(label) hex-encoded uppercase (40 chars). The PDF
|
||||
* persists only the hex serial so recipient / envelope-item IDs never leak
|
||||
* into the document.
|
||||
*/
|
||||
|
||||
const hashToOpaqueSerial = (label: string): string => bytesToHex(sha1(utf8ToBytes(label))).toUpperCase();
|
||||
|
||||
/** AcroForm signature-field name (TSP anchor) for a recipient + envelope item. */
|
||||
export const buildTspAnchorName = (recipientId: number, envelopeItemId: string): string =>
|
||||
hashToOpaqueSerial(`recipient:${recipientId}|item:${envelopeItemId}`);
|
||||
|
||||
/** `/Stamp` annotation name for a recipient + envelope item on a specific page. */
|
||||
export const buildTspStampName = (recipientId: number, envelopeItemId: string, pageNumber: number): string =>
|
||||
hashToOpaqueSerial(`recipient:${recipientId}|item:${envelopeItemId}|page:${pageNumber}`);
|
||||
@@ -0,0 +1,248 @@
|
||||
import { NEXT_PUBLIC_WEBAPP_URL } from '@documenso/lib/constants/app';
|
||||
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
import type { TCscSessionItems } from '@documenso/lib/types/csc-session';
|
||||
import { DOCUMENT_AUDIT_LOG_TYPE } from '@documenso/lib/types/document-audit-logs';
|
||||
import { isTspEnvelope } from '@documenso/lib/types/signature-level';
|
||||
import type { RequestMetadata } from '@documenso/lib/universal/extract-request-metadata';
|
||||
import { getFileServerSide } from '@documenso/lib/universal/upload/get-file.server';
|
||||
import { putPdfFileServerSide } from '@documenso/lib/universal/upload/put-file.server';
|
||||
import { createDocumentAuditLogData } from '@documenso/lib/utils/document-audit-logs';
|
||||
import { prisma } from '@documenso/prisma';
|
||||
import type { FieldWithSignature } from '@documenso/prisma/types/field-with-signature';
|
||||
import { PDF } from '@libpdf/core';
|
||||
|
||||
import { type CscDigest, policyToLibpdfSignerAlgo } from './algorithm-resolver';
|
||||
import { decodeCscCertChain } from './cert-chain';
|
||||
import { loadCscCredential } from './credential';
|
||||
import { buildTspAnchorName, buildTspStampName } from './pdf-names';
|
||||
import { renderRecipientOverlay } from './render-overlay';
|
||||
import { upsertCscSession } from './sign-session';
|
||||
import { CscCaptureSigner } from './signers/capture-signer';
|
||||
|
||||
/**
|
||||
* CSC TSP prep-phase orchestrator.
|
||||
*
|
||||
* Per envelope item:
|
||||
*
|
||||
* 1. Render the recipient's overlay into the materialised PDF in memory.
|
||||
* 2. Persist the rendered bytes as a fresh `DocumentData` row — this is the
|
||||
* immutable byte-source the sign pass will load. Pinning the rendered PDF
|
||||
* (rather than re-rendering at sign time) eliminates the determinism risk
|
||||
* of running Konva twice across the OAuth round-trip.
|
||||
* 3. Reload `pdfDoc` from the persisted bytes and dry-run `pdf.sign` with
|
||||
* `CscCaptureSigner` to derive the `signedAttrs` digest — captured over
|
||||
* the same bytes the sign pass will load.
|
||||
*
|
||||
* The resulting `{ envelopeItemId, documentDataId, hashB64, ordinal }` tuples
|
||||
* are stored on `CscSession.itemsJson`. `documentDataId` pins the orphan
|
||||
* rendered row, not `envelopeItem.documentDataId` — the latter stays stable
|
||||
* (in-place data updates only, mirroring the materialise pattern).
|
||||
*
|
||||
* Sequential per item — PDF parse + libpdf sign is CPU-heavy and per-recipient
|
||||
* concurrency is wasted on a single Node event loop.
|
||||
*/
|
||||
|
||||
export type PrepareCscRecipientSigningOptions = {
|
||||
/** Recipient token from `/sign/{token}` URL. */
|
||||
recipientToken: string;
|
||||
/** Forwarded for audit log attribution. */
|
||||
requestMetadata?: RequestMetadata;
|
||||
};
|
||||
|
||||
export type PrepareCscRecipientSigningResult = {
|
||||
status: 'REDIRECT';
|
||||
redirectUrl: string;
|
||||
};
|
||||
|
||||
export const prepareCscRecipientSigning = async (
|
||||
opts: PrepareCscRecipientSigningOptions,
|
||||
): Promise<PrepareCscRecipientSigningResult> => {
|
||||
const { recipientToken, requestMetadata } = opts;
|
||||
|
||||
const recipient = await prisma.recipient
|
||||
.findFirst({
|
||||
where: { token: recipientToken },
|
||||
// `signature` must be eager-loaded — `renderRecipientOverlay` runs the
|
||||
// field renderer in `export` mode, which throws `MISSING_SIGNATURE` for
|
||||
// any inserted SIGNATURE field without signature data. Mirrors the
|
||||
// include pattern in `seal-document.handler.ts`.
|
||||
include: { fields: { include: { signature: true } } },
|
||||
})
|
||||
.catch(() => null);
|
||||
|
||||
if (!recipient) {
|
||||
throw new AppError(AppErrorCode.NOT_FOUND, {
|
||||
message: `Recipient with token "${recipientToken}" not found.`,
|
||||
});
|
||||
}
|
||||
|
||||
const envelope = await prisma.envelope.findUniqueOrThrow({
|
||||
where: { id: recipient.envelopeId },
|
||||
include: {
|
||||
envelopeItems: {
|
||||
include: {
|
||||
documentData: true,
|
||||
},
|
||||
},
|
||||
recipients: true,
|
||||
},
|
||||
});
|
||||
|
||||
if (!isTspEnvelope(envelope)) {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: 'prepareCscRecipientSigning called for a non-TSP envelope.',
|
||||
});
|
||||
}
|
||||
|
||||
const credential = await loadCscCredential(recipient.id);
|
||||
|
||||
if (!credential) {
|
||||
throw new AppError(AppErrorCode.NOT_FOUND, {
|
||||
message: 'CSC credential missing — service-scope OAuth must complete first.',
|
||||
});
|
||||
}
|
||||
|
||||
if (!credential.certCache) {
|
||||
throw new AppError(AppErrorCode.CSC_CERT_INVALID, {
|
||||
message: 'CSC credential has no persisted certificate chain.',
|
||||
});
|
||||
}
|
||||
|
||||
if (credential.keyLenBits === null) {
|
||||
throw new AppError(AppErrorCode.CSC_ALGORITHM_REFUSED, {
|
||||
message: 'CSC credential omits persisted keyLenBits — service-scope OAuth must re-run.',
|
||||
});
|
||||
}
|
||||
|
||||
const chain = decodeCscCertChain(credential.certCache);
|
||||
|
||||
const algo = policyToLibpdfSignerAlgo({
|
||||
keyType: credential.keyType as 'RSA' | 'ECDSA',
|
||||
digestAlgorithm: credential.digestAlgorithm as CscDigest,
|
||||
signAlgoOid: credential.signatureAlgorithm,
|
||||
keyLenBits: credential.keyLenBits,
|
||||
// `policyToLibpdfSignerAlgo` does not read `hashAlgoOid`; passing empty
|
||||
// string keeps the synthetic policy type-correct without re-derivation.
|
||||
hashAlgoOid: '',
|
||||
});
|
||||
|
||||
// Pin a single signingTime for every per-item capture so the embed pass
|
||||
// re-derives byte-identical signedAttrs digests.
|
||||
const signingTime = new Date();
|
||||
|
||||
const items: TCscSessionItems = [];
|
||||
|
||||
for (const envelopeItem of envelope.envelopeItems) {
|
||||
const recipientFieldsOnItem = recipient.fields.filter((field) => field.envelopeItemId === envelopeItem.id);
|
||||
|
||||
const pagesWithFields = new Set<number>();
|
||||
|
||||
for (const field of recipientFieldsOnItem) {
|
||||
pagesWithFields.add(field.page);
|
||||
}
|
||||
|
||||
const bytes = await getFileServerSide(envelopeItem.documentData);
|
||||
const pdfDoc = await PDF.load(bytes);
|
||||
|
||||
for (const pageNumber of pagesWithFields) {
|
||||
const fieldsOnPage: FieldWithSignature[] = recipientFieldsOnItem.filter((field) => field.page === pageNumber);
|
||||
|
||||
await renderRecipientOverlay({
|
||||
pdfDoc,
|
||||
stampName: buildTspStampName(recipient.id, envelopeItem.id, pageNumber),
|
||||
pageNumber,
|
||||
fields: fieldsOnPage,
|
||||
});
|
||||
}
|
||||
|
||||
// Persist the rendered PDF as an orphan `DocumentData` row before the
|
||||
// capture pass so sign-time can load byte-identical input — eliminates
|
||||
// the determinism risk of running Konva again after the OAuth round-trip.
|
||||
const renderedBytes = await pdfDoc.save({ incremental: true });
|
||||
|
||||
const fileName = envelope.title.endsWith('.pdf') ? envelope.title : `${envelope.title || 'envelope'}.pdf`;
|
||||
|
||||
const renderedUpload = await putPdfFileServerSide(
|
||||
{
|
||||
name: fileName,
|
||||
type: 'application/pdf',
|
||||
arrayBuffer: async () => Promise.resolve(renderedBytes),
|
||||
},
|
||||
envelopeItem.documentData.initialData ?? undefined,
|
||||
);
|
||||
|
||||
// Reload from the persisted bytes so the capture pass operates on the
|
||||
// exact same bytes the sign pass will fetch from storage. Skipping the
|
||||
// reload would compute the digest over an in-memory incremental update
|
||||
// that diverges from what `PDF.load(renderedBytes)` produces.
|
||||
const capturePdfDoc = await PDF.load(renderedBytes);
|
||||
|
||||
const captureSigner = new CscCaptureSigner({
|
||||
certificate: chain[0],
|
||||
certificateChain: chain.slice(1),
|
||||
algo,
|
||||
});
|
||||
|
||||
const anchorName = buildTspAnchorName(recipient.id, envelopeItem.id);
|
||||
|
||||
// Capture at B-B even though the eventual embed pass is B-T. The B-T
|
||||
// signature timestamp is a CMS *unsigned* attribute, added by libpdf
|
||||
// after `signer.sign()` runs over the signed-attrs digest — so B-B and
|
||||
// B-T produce byte-identical signed-attrs for the same `(signer,
|
||||
// documentHash, digestAlgorithm, signingTime)` tuple. See the matching
|
||||
// note in `execute-tsp-sign.ts`.
|
||||
await capturePdfDoc.sign({
|
||||
signer: captureSigner,
|
||||
fieldName: anchorName,
|
||||
signingTime,
|
||||
level: 'B-B',
|
||||
digestAlgorithm: algo.digestAlgorithm,
|
||||
});
|
||||
|
||||
if (captureSigner.capturedDigest === null) {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: 'CscCaptureSigner was not invoked by pdf.sign during prep.',
|
||||
});
|
||||
}
|
||||
|
||||
items.push({
|
||||
envelopeItemId: envelopeItem.id,
|
||||
documentDataId: renderedUpload.documentData.id,
|
||||
hashB64: Buffer.from(captureSigner.capturedDigest).toString('base64'),
|
||||
ordinal: items.length,
|
||||
});
|
||||
}
|
||||
|
||||
const session = await upsertCscSession({
|
||||
recipientId: recipient.id,
|
||||
envelopeId: envelope.id,
|
||||
signingTime,
|
||||
items,
|
||||
});
|
||||
|
||||
await prisma.documentAuditLog.create({
|
||||
data: createDocumentAuditLogData({
|
||||
type: DOCUMENT_AUDIT_LOG_TYPE.DOCUMENT_RECIPIENT_CSC_SIGN_REQUESTED,
|
||||
envelopeId: envelope.id,
|
||||
user: { name: recipient.name, email: recipient.email },
|
||||
requestMetadata,
|
||||
data: {
|
||||
recipientEmail: recipient.email,
|
||||
recipientName: recipient.name,
|
||||
recipientId: recipient.id,
|
||||
recipientRole: recipient.role,
|
||||
providerId: credential.providerId,
|
||||
credentialId: credential.credentialId,
|
||||
sessionId: session.id,
|
||||
numSignatures: items.length,
|
||||
},
|
||||
}),
|
||||
});
|
||||
|
||||
const redirectUrl = `${NEXT_PUBLIC_WEBAPP_URL()}/api/csc/oauth/authorize?scope=credential&session=${session.id}`;
|
||||
|
||||
return {
|
||||
status: 'REDIRECT',
|
||||
redirectUrl,
|
||||
};
|
||||
};
|
||||
@@ -0,0 +1,162 @@
|
||||
import { AnnotationFlags, ops, PDF, PdfArray, PdfDict, PdfName, PdfNumber } from '@libpdf/core';
|
||||
|
||||
// `Operator` is declared in `@libpdf/core` but not exported. Derive it from
|
||||
// `ops.pushGraphicsState`'s return type instead of importing.
|
||||
type LibpdfOperator = ReturnType<typeof ops.pushGraphicsState>;
|
||||
|
||||
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
import { insertFieldInPDFV2 } from '@documenso/lib/server-only/pdf/insert-field-in-pdf-v2';
|
||||
import type { FieldWithSignature } from '@documenso/prisma/types/field-with-signature';
|
||||
|
||||
/**
|
||||
* CSC TSP recipient overlay renderer.
|
||||
*
|
||||
* Writes a recipient's per-page field values into the pre-allocated
|
||||
* `/Stamp` annotation's normal appearance (`/AP /N`), reusing the Konva
|
||||
* overlay generator that powers the SES path.
|
||||
*
|
||||
* SES uses `page.drawPage(embeddedPage)` to paint directly onto the page
|
||||
* content stream. For TSP that would create a new page object in the
|
||||
* incremental update and invalidate prior recipients' `/ByteRange`. Routing
|
||||
* the same embedded FormXObject through a stamp's appearance keeps the page
|
||||
* dict untouched while reusing the embed pipeline `drawPage` does.
|
||||
*
|
||||
* The appearance stream mirrors `drawPage`'s `x=0, y=0, scale=1, no-rotate`
|
||||
* branch: a single `concatMatrix(1, 0, 0, 1, -box.x, -box.y)` compensates
|
||||
* for any non-origin MediaBox on the overlay PDF before `paintXObject`. The
|
||||
* stamp's `/Rect` and the appearance `/BBox` both span `[0, 0, page.width,
|
||||
* page.height]`, so the PDF reader maps content 1:1 and page rotation
|
||||
* applies at the page level (not inside the appearance).
|
||||
*/
|
||||
|
||||
export type RenderRecipientOverlayOptions = {
|
||||
/** The loaded PDF the stamp lives on. */
|
||||
pdfDoc: PDF;
|
||||
/** Stamp name from `buildTspStampName(recipientId, envelopeItemId, pageNumber)`. */
|
||||
stampName: string;
|
||||
/** 1-based page number. */
|
||||
pageNumber: number;
|
||||
/** Recipient's fields for THIS page only. */
|
||||
fields: FieldWithSignature[];
|
||||
};
|
||||
|
||||
/**
|
||||
* Render `fields` into the pre-allocated `/Stamp` annotation named `stampName`
|
||||
* on `pageNumber`. Mutates `pdfDoc` in place.
|
||||
*
|
||||
* Throws when the named stamp can't be located — every call site must have
|
||||
* materialised the stamp first via `materializeTspAnchorsForEnvelope`.
|
||||
*/
|
||||
export const renderRecipientOverlay = async ({
|
||||
pdfDoc,
|
||||
stampName,
|
||||
pageNumber,
|
||||
fields,
|
||||
}: RenderRecipientOverlayOptions): Promise<void> => {
|
||||
const page = pdfDoc.getPage(pageNumber - 1);
|
||||
|
||||
if (!page) {
|
||||
throw new AppError(AppErrorCode.NOT_FOUND, {
|
||||
message: `Page ${pageNumber} not found on PDF.`,
|
||||
});
|
||||
}
|
||||
|
||||
const stamp = page.getStampAnnotations().find((annotation) => annotation.stampName === stampName);
|
||||
|
||||
if (!stamp) {
|
||||
throw new AppError(AppErrorCode.NOT_FOUND, {
|
||||
message: `TSP stamp ${stampName} not found on page ${pageNumber}.`,
|
||||
});
|
||||
}
|
||||
|
||||
const overlayBytes = await insertFieldInPDFV2({
|
||||
pageWidth: page.width,
|
||||
pageHeight: page.height,
|
||||
fields,
|
||||
});
|
||||
|
||||
const overlayDoc = await PDF.load(overlayBytes);
|
||||
const embedded = await pdfDoc.embedPage(overlayDoc, 0);
|
||||
|
||||
// Bind the embedded page under a local XObject name in the appearance's
|
||||
// own /Resources. Appearance streams are scoped — they can't see the
|
||||
// parent page's resource dict.
|
||||
const xobjectName = 'X0';
|
||||
|
||||
// Mirror `PDFPage.drawPage`'s no-rotation, no-scale branch:
|
||||
// translateX = x - embedded.box.x * scaleX (x = 0, scaleX = 1)
|
||||
// translateY = y - embedded.box.y * scaleY (y = 0, scaleY = 1)
|
||||
// concatMatrix(scaleX, 0, 0, scaleY, translateX, translateY)
|
||||
// Identity matrix when the overlay PDF has an origin-aligned MediaBox;
|
||||
// a translate-only shift otherwise. No-op cost is negligible.
|
||||
const operators: LibpdfOperator[] = [
|
||||
ops.pushGraphicsState(),
|
||||
ops.concatMatrix(1, 0, 0, 1, -embedded.box.x, -embedded.box.y),
|
||||
ops.paintXObject(xobjectName),
|
||||
ops.popGraphicsState(),
|
||||
];
|
||||
|
||||
const contentBytes = serializeOperators(operators);
|
||||
|
||||
const appearanceRef = pdfDoc.createStream(
|
||||
{
|
||||
Type: PdfName.of('XObject'),
|
||||
Subtype: PdfName.of('Form'),
|
||||
FormType: PdfNumber.of(1),
|
||||
BBox: new PdfArray([PdfNumber.of(0), PdfNumber.of(0), PdfNumber.of(page.width), PdfNumber.of(page.height)]),
|
||||
Resources: PdfDict.of({
|
||||
XObject: PdfDict.of({
|
||||
[xobjectName]: embedded.ref,
|
||||
}),
|
||||
}),
|
||||
},
|
||||
contentBytes,
|
||||
);
|
||||
|
||||
// Direct dict write — bypasses `PDFAnnotation.setNormalAppearance`, which
|
||||
// (a) re-registers the stream and (b) has a no-op branch when `/AP` is
|
||||
// absent on the annotation. See `node_modules/@libpdf/core/dist/index.mjs:
|
||||
// 4347-4357`. The PDF reader and libpdf's `getAppearance` (index.mjs:4337)
|
||||
// both follow refs transparently, so `/AP -> { N: <ref> }` is valid.
|
||||
stamp.dict.set('AP', PdfDict.of({ N: appearanceRef }));
|
||||
|
||||
stamp.setFlag(AnnotationFlags.Print, true);
|
||||
stamp.setFlag(AnnotationFlags.ReadOnly, true);
|
||||
stamp.setFlag(AnnotationFlags.Locked, true);
|
||||
stamp.setFlag(AnnotationFlags.LockedContents, true);
|
||||
};
|
||||
|
||||
/**
|
||||
* Serialize a content-stream operator sequence into a single byte buffer,
|
||||
* newline-separated. Mirrors libpdf's internal `serializeOperators` (not
|
||||
* exported from `@libpdf/core`); each `Operator.toBytes()` returns one
|
||||
* operator's `operand1 operand2 ... op` slice.
|
||||
*/
|
||||
const serializeOperators = (operators: LibpdfOperator[]): Uint8Array => {
|
||||
if (operators.length === 0) {
|
||||
return new Uint8Array(0);
|
||||
}
|
||||
|
||||
const chunks = operators.map((operator) => operator.toBytes());
|
||||
|
||||
let totalLength = 0;
|
||||
|
||||
for (const chunk of chunks) {
|
||||
totalLength += chunk.length + 1; // +1 for trailing newline
|
||||
}
|
||||
|
||||
const out = new Uint8Array(totalLength);
|
||||
let offset = 0;
|
||||
|
||||
for (const chunk of chunks) {
|
||||
out.set(chunk, offset);
|
||||
|
||||
offset += chunk.length;
|
||||
|
||||
out[offset] = 0x0a;
|
||||
|
||||
offset += 1;
|
||||
}
|
||||
|
||||
return out;
|
||||
};
|
||||
@@ -0,0 +1,181 @@
|
||||
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
import { type TCscSessionItems, ZCscSessionItemsSchema } from '@documenso/lib/types/csc-session';
|
||||
import { prisma } from '@documenso/prisma';
|
||||
import { Prisma } from '@prisma/client';
|
||||
|
||||
/**
|
||||
* DB helpers for `CscSession` — the per-recipient transient row that bridges
|
||||
* prep, the credential-scope OAuth round-trip, and the sync sign mutation.
|
||||
*
|
||||
* Four operations cover the spec's lifecycle:
|
||||
*
|
||||
* - {@link upsertCscSession} — prep time; clears any prior SAD by writing
|
||||
* `encryptedSad = null` so a re-clicked Sign starts fresh.
|
||||
* - {@link updateCscSessionWithSad} — credential-scope callback; sets the
|
||||
* SAD + its TSP-asserted expiry.
|
||||
* - {@link loadCscSession} — authorize route, signing-page loader, sync
|
||||
* mutation. Returns null on missing (cookie referenced a deleted session).
|
||||
* - {@link consumeCscSession} — sync mutation success path; single-use delete
|
||||
* returning the consumed row so the caller can use its data post-deletion.
|
||||
*
|
||||
* `itemsJson` is parsed through `ZCscSessionItemsSchema` on every read so the
|
||||
* caller works with typed {@link TCscSessionItems}.
|
||||
*/
|
||||
|
||||
export type CscSessionRow = {
|
||||
id: string;
|
||||
recipientId: number;
|
||||
envelopeId: string;
|
||||
signingTime: Date;
|
||||
items: TCscSessionItems;
|
||||
encryptedSad: Uint8Array | null;
|
||||
sadExpiresAt: Date | null;
|
||||
createdAt: Date;
|
||||
};
|
||||
|
||||
type UpsertCscSessionInput = {
|
||||
recipientId: number;
|
||||
envelopeId: string;
|
||||
signingTime: Date;
|
||||
items: TCscSessionItems;
|
||||
};
|
||||
|
||||
/**
|
||||
* Create or refresh the per-recipient session row at prep time. The recipient
|
||||
* has at most one in-flight session (`@@unique([recipientId])`); re-clicking
|
||||
* Sign overwrites prior `itemsJson` + clears `encryptedSad` / `sadExpiresAt`
|
||||
* so the next credential-scope callback starts from a clean SAD slot.
|
||||
*/
|
||||
export const upsertCscSession = async (input: UpsertCscSessionInput): Promise<CscSessionRow> => {
|
||||
const { recipientId, envelopeId, signingTime, items } = input;
|
||||
|
||||
const row = await prisma.cscSession.upsert({
|
||||
where: { recipientId },
|
||||
create: {
|
||||
recipientId,
|
||||
envelopeId,
|
||||
signingTime,
|
||||
itemsJson: items,
|
||||
encryptedSad: null,
|
||||
sadExpiresAt: null,
|
||||
},
|
||||
update: {
|
||||
envelopeId,
|
||||
signingTime,
|
||||
itemsJson: items,
|
||||
encryptedSad: null,
|
||||
sadExpiresAt: null,
|
||||
},
|
||||
});
|
||||
|
||||
return toCscSessionRow(row);
|
||||
};
|
||||
|
||||
type UpdateCscSessionWithSadInput = {
|
||||
sessionId: string;
|
||||
encryptedSad: Uint8Array;
|
||||
sadExpiresAt: Date;
|
||||
};
|
||||
|
||||
/**
|
||||
* Stamp the credential-scope SAD onto an existing session at the OAuth
|
||||
* callback. Throws when the session id was already consumed or never existed
|
||||
* — that's a flow-state bug the caller must surface, not silently skip.
|
||||
*/
|
||||
export const updateCscSessionWithSad = async (input: UpdateCscSessionWithSadInput): Promise<CscSessionRow> => {
|
||||
const { sessionId, encryptedSad, sadExpiresAt } = input;
|
||||
|
||||
try {
|
||||
const row = await prisma.cscSession.update({
|
||||
where: {
|
||||
id: sessionId,
|
||||
},
|
||||
data: {
|
||||
encryptedSad: Buffer.from(encryptedSad),
|
||||
sadExpiresAt,
|
||||
},
|
||||
});
|
||||
|
||||
return toCscSessionRow(row);
|
||||
} catch (err) {
|
||||
if (err instanceof Prisma.PrismaClientKnownRequestError && err.code === 'P2025') {
|
||||
throw new AppError(AppErrorCode.NOT_FOUND, {
|
||||
message: `CSC session "${sessionId}" not found at SAD attach time.`,
|
||||
});
|
||||
}
|
||||
|
||||
throw err;
|
||||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* Fetch a session by id. Returns `null` when the row is absent — callers MUST
|
||||
* handle the missing case (cookie outliving the row is a normal terminal
|
||||
* outcome, not an error).
|
||||
*/
|
||||
export const loadCscSession = async (sessionId: string): Promise<CscSessionRow | null> => {
|
||||
const row = await prisma.cscSession.findUnique({
|
||||
where: { id: sessionId },
|
||||
});
|
||||
|
||||
return row ? toCscSessionRow(row) : null;
|
||||
};
|
||||
|
||||
/**
|
||||
* Atomically delete the session row and return its parsed contents. Used by
|
||||
* the sync mutation's success path so the caller still has the session data
|
||||
* for post-sign side effects (audit log, webhook payloads).
|
||||
*
|
||||
* Throws `NOT_FOUND` when the row is already gone — semantically distinct
|
||||
* from {@link loadCscSession}'s nullable return because consume is the
|
||||
* success-path single-use closer; a missing row at that point means another
|
||||
* branch raced to consume and the caller should not double-count.
|
||||
*/
|
||||
export const consumeCscSession = async (sessionId: string, tx?: Prisma.TransactionClient): Promise<CscSessionRow> => {
|
||||
const client = tx ?? prisma;
|
||||
|
||||
try {
|
||||
const row = await client.cscSession.delete({
|
||||
where: { id: sessionId },
|
||||
});
|
||||
|
||||
return toCscSessionRow(row);
|
||||
} catch (err) {
|
||||
if (err instanceof Prisma.PrismaClientKnownRequestError && err.code === 'P2025') {
|
||||
throw new AppError(AppErrorCode.NOT_FOUND, {
|
||||
message: `CSC session "${sessionId}" already consumed or never existed.`,
|
||||
});
|
||||
}
|
||||
|
||||
throw err;
|
||||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* Project a raw Prisma `CscSession` into the helper's parsed shape. Throws
|
||||
* on `itemsJson` parse failure — that's a data-integrity issue, not a
|
||||
* recoverable runtime case.
|
||||
*/
|
||||
const toCscSessionRow = (row: {
|
||||
id: string;
|
||||
recipientId: number;
|
||||
envelopeId: string;
|
||||
signingTime: Date;
|
||||
itemsJson: Prisma.JsonValue;
|
||||
encryptedSad: Uint8Array | null;
|
||||
sadExpiresAt: Date | null;
|
||||
createdAt: Date;
|
||||
}): CscSessionRow => {
|
||||
const items = ZCscSessionItemsSchema.parse(row.itemsJson);
|
||||
|
||||
return {
|
||||
id: row.id,
|
||||
recipientId: row.recipientId,
|
||||
envelopeId: row.envelopeId,
|
||||
signingTime: row.signingTime,
|
||||
items,
|
||||
encryptedSad: row.encryptedSad,
|
||||
sadExpiresAt: row.sadExpiresAt,
|
||||
createdAt: row.createdAt,
|
||||
};
|
||||
};
|
||||
@@ -0,0 +1,123 @@
|
||||
/**
|
||||
* CSC dry-run capture signer.
|
||||
*
|
||||
* Libpdf's signing flow expects an inline signer that hashes the
|
||||
* `signedAttrs` bytes and returns a CMS signature. For the CSC §11.9
|
||||
* `signatures/signHash` contract the actual signature is produced
|
||||
* remotely by the TSP, so a single libpdf sign cycle has to be split
|
||||
* into two passes:
|
||||
*
|
||||
* 1. Dry-run — drive `pdf.sign()` with this capture signer to derive
|
||||
* the `signedAttrs` digest libpdf would otherwise sign. The
|
||||
* resulting PDF is discarded; only `capturedDigest` matters.
|
||||
* 2. Embed pass — the `CscFifoSigner` re-runs `pdf.sign()` and feeds
|
||||
* the TSP-produced signature bytes back into the same byte slots.
|
||||
*
|
||||
* The placeholder bytes returned from `sign()` are sized to the
|
||||
* chosen algorithm so libpdf's downstream CMS construction is not
|
||||
* surprised by an unexpectedly short signature.
|
||||
*/
|
||||
|
||||
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
import type { Signer } from '@libpdf/core';
|
||||
import { sha256, sha384, sha512 } from '@noble/hashes/sha2';
|
||||
|
||||
import type { LibpdfSignerAlgo } from '../algorithm-resolver';
|
||||
|
||||
type DigestAlgorithm = 'SHA-256' | 'SHA-384' | 'SHA-512';
|
||||
|
||||
type KeyType = 'RSA' | 'EC';
|
||||
|
||||
type SignatureAlgorithm = 'RSASSA-PKCS1-v1_5' | 'RSA-PSS' | 'ECDSA';
|
||||
|
||||
export type CscCaptureSignerOptions = {
|
||||
certificate: Uint8Array;
|
||||
certificateChain?: Uint8Array[];
|
||||
algo: LibpdfSignerAlgo;
|
||||
};
|
||||
|
||||
export class CscCaptureSigner implements Signer {
|
||||
readonly certificate: Uint8Array;
|
||||
readonly certificateChain?: Uint8Array[];
|
||||
readonly keyType: KeyType;
|
||||
readonly signatureAlgorithm: SignatureAlgorithm;
|
||||
private readonly algo: LibpdfSignerAlgo;
|
||||
|
||||
/** Populated by `sign()`. `null` until libpdf calls into the signer. */
|
||||
capturedDigest: Uint8Array | null = null;
|
||||
|
||||
constructor(options: CscCaptureSignerOptions) {
|
||||
this.certificate = options.certificate;
|
||||
this.certificateChain = options.certificateChain;
|
||||
this.keyType = options.algo.keyType;
|
||||
this.signatureAlgorithm = options.algo.signatureAlgorithm;
|
||||
this.algo = options.algo;
|
||||
}
|
||||
|
||||
/**
|
||||
* Hash `data` with `algorithm` to derive the `signedAttrs` digest libpdf
|
||||
* would normally sign, stash it on `capturedDigest`, then return a
|
||||
* placeholder buffer sized to the chosen key so libpdf's CMS scaffolding
|
||||
* accepts it. The placeholder bytes are never inspected — the resulting
|
||||
* PDF is discarded after the digest is read.
|
||||
*/
|
||||
|
||||
// biome-ignore lint/suspicious/useAwait: intentional
|
||||
async sign(data: Uint8Array, algorithm: DigestAlgorithm): Promise<Uint8Array> {
|
||||
if (this.capturedDigest !== null) {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: 'CscCaptureSigner.sign() called more than once — capture signers are single-use.',
|
||||
});
|
||||
}
|
||||
|
||||
this.capturedDigest = hashData(data, algorithm);
|
||||
|
||||
return new Uint8Array(placeholderSize(this.algo));
|
||||
}
|
||||
}
|
||||
|
||||
const hashData = (data: Uint8Array, algorithm: DigestAlgorithm): Uint8Array => {
|
||||
if (algorithm === 'SHA-256') {
|
||||
return sha256(data);
|
||||
}
|
||||
|
||||
if (algorithm === 'SHA-384') {
|
||||
return sha384(data);
|
||||
}
|
||||
|
||||
if (algorithm === 'SHA-512') {
|
||||
return sha512(data);
|
||||
}
|
||||
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: `CscCaptureSigner.sign() called with unsupported digest algorithm '${String(algorithm)}'.`,
|
||||
});
|
||||
};
|
||||
|
||||
const placeholderSize = (algo: LibpdfSignerAlgo): number => {
|
||||
if (algo.keyType === 'RSA') {
|
||||
// RSA signature length === modulus length in bytes.
|
||||
if (algo.keyLenBits >= 4096) {
|
||||
return 512;
|
||||
}
|
||||
|
||||
if (algo.keyLenBits >= 3072) {
|
||||
return 384;
|
||||
}
|
||||
|
||||
return 256;
|
||||
}
|
||||
|
||||
// ECDSA DER-encoded SEQUENCE { INTEGER r, INTEGER s }. Upper bounds:
|
||||
// P-256 ≈ 72 bytes, P-384 ≈ 104, P-521 ≈ 139. The dry-run PDF is
|
||||
// discarded — exact size is informational, not load-bearing.
|
||||
if (algo.keyLenBits >= 512) {
|
||||
return 139;
|
||||
}
|
||||
|
||||
if (algo.keyLenBits >= 384) {
|
||||
return 104;
|
||||
}
|
||||
|
||||
return 72;
|
||||
};
|
||||
@@ -0,0 +1,57 @@
|
||||
/**
|
||||
* CSC embed-pass FIFO signer.
|
||||
*
|
||||
* `signatures/signHash` (CSC §11.9) returns one signature per submitted
|
||||
* hash, in the same position-bound order as the request `hash[]` array.
|
||||
* The embed pass re-runs `pdf.sign()` once per anchor in that same order,
|
||||
* so a FIFO queue of signature bytes — popped on each `sign()` call —
|
||||
* is sufficient to feed libpdf without any per-anchor binding metadata.
|
||||
*/
|
||||
|
||||
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
import type { Signer } from '@libpdf/core';
|
||||
|
||||
import type { LibpdfSignerAlgo } from '../algorithm-resolver';
|
||||
|
||||
type DigestAlgorithm = 'SHA-256' | 'SHA-384' | 'SHA-512';
|
||||
|
||||
type KeyType = 'RSA' | 'EC';
|
||||
|
||||
type SignatureAlgorithm = 'RSASSA-PKCS1-v1_5' | 'RSA-PSS' | 'ECDSA';
|
||||
|
||||
export type CscFifoSignerOptions = {
|
||||
certificate: Uint8Array;
|
||||
certificateChain?: Uint8Array[];
|
||||
algo: LibpdfSignerAlgo;
|
||||
/** Base64-decoded raw signature bytes in the order produced by `signatures/signHash`. */
|
||||
signatures: Uint8Array[];
|
||||
};
|
||||
|
||||
export class CscFifoSigner implements Signer {
|
||||
readonly certificate: Uint8Array;
|
||||
readonly certificateChain?: Uint8Array[];
|
||||
readonly keyType: KeyType;
|
||||
readonly signatureAlgorithm: SignatureAlgorithm;
|
||||
private readonly queue: Uint8Array[];
|
||||
|
||||
constructor(options: CscFifoSignerOptions) {
|
||||
this.certificate = options.certificate;
|
||||
this.certificateChain = options.certificateChain;
|
||||
this.keyType = options.algo.keyType;
|
||||
this.signatureAlgorithm = options.algo.signatureAlgorithm;
|
||||
this.queue = [...options.signatures];
|
||||
}
|
||||
|
||||
// biome-ignore lint/suspicious/useAwait: intentional
|
||||
async sign(_data: Uint8Array, _algorithm: DigestAlgorithm): Promise<Uint8Array> {
|
||||
const next = this.queue.shift();
|
||||
|
||||
if (next === undefined) {
|
||||
throw new AppError(AppErrorCode.INVALID_REQUEST, {
|
||||
message: 'CSC FIFO signer exhausted — more sign() calls than queued signatures.',
|
||||
});
|
||||
}
|
||||
|
||||
return next;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,153 @@
|
||||
import { IS_INSTANCE_CSC_MODE, NEXT_PUBLIC_WEBAPP_URL } from '@documenso/lib/constants/app';
|
||||
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
import { assertLicensedFor } from '@documenso/lib/server-only/license/assert-licensed-for';
|
||||
import { requireEnv } from '@documenso/lib/utils/env';
|
||||
import type { OAuth2Client } from 'arctic';
|
||||
|
||||
import { cscInfo } from './client/info';
|
||||
import { createCscOAuthClient } from './client/oauth';
|
||||
import type { TCscInfoResponse } from './client/types';
|
||||
import { isEnvTsaConfigured } from './tsa-resolver';
|
||||
|
||||
/**
|
||||
* Lazily-built, globally-cached CSC transport.
|
||||
*
|
||||
* Boot-discovers `cscInfo` (§11.1) once, caches the OAuth base URL +
|
||||
* `signatures/timestamp` capability, and exposes a configured arctic
|
||||
* `OAuth2Client`. License + env + discovery are gated at construction so a
|
||||
* misconfigured instance fails at the first call site, not at sign time.
|
||||
*
|
||||
* Cached on `globalThis` so Hono routes and Remix loaders share one instance
|
||||
* across bundles (mirrors {@link LicenseClient}'s strategy).
|
||||
*
|
||||
* A failed build is **not** cached — the next caller retries. This keeps a
|
||||
* transient discovery hiccup from permanently breaking the transport while
|
||||
* still amortising the success path to one round-trip per process.
|
||||
*/
|
||||
|
||||
const DISCOVERY_TIMEOUT_MS = 10_000;
|
||||
|
||||
const CSC_TIMESTAMP_METHOD = 'signatures/timestamp';
|
||||
|
||||
export type CscTransport = {
|
||||
/** Service base URI from `NEXT_PRIVATE_SIGNING_CSC_PROVIDER_BASE_URL`. */
|
||||
serviceBaseUrl: string;
|
||||
/** OAuth base URI from `info.oauth2` (§11.1). MAY differ from `serviceBaseUrl`. */
|
||||
oauthBaseUrl: string;
|
||||
/** Pre-configured arctic client bound to the TSP's OAuth registration. */
|
||||
oauthClient: OAuth2Client;
|
||||
/**
|
||||
* Documenso's callback URL registered with the TSP. Derived from
|
||||
* `NEXT_PUBLIC_WEBAPP_URL` and the fixed `/api/csc/oauth/callback` mount —
|
||||
* mirrors `packages/auth/server/config.ts` for the sign-in OAuth providers.
|
||||
* Operators must register this exact URL with the TSP.
|
||||
*/
|
||||
oauthRedirectUri: string;
|
||||
/** True when the TSP advertises `signatures/timestamp` in `info.methods`. */
|
||||
supportsTimestamp: boolean;
|
||||
/** Raw discovery response, exposed for callers needing other fields (`name`, `region`, `lang`). */
|
||||
info: TCscInfoResponse;
|
||||
};
|
||||
|
||||
declare global {
|
||||
// eslint-disable-next-line no-var
|
||||
var __documenso_csc_transport__: CscTransport | undefined;
|
||||
// eslint-disable-next-line no-var
|
||||
var __documenso_csc_transport_promise__: Promise<CscTransport> | undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get the current CSC transport, building + caching it on first call.
|
||||
*
|
||||
* Throws:
|
||||
* - `NOT_SETUP` — instance is not in CSC mode, or a required env var is unset.
|
||||
* - `CSC_UNLICENSED` — `instanceCscSigning` license flag missing.
|
||||
* - `CSC_PROVIDER_INFO_FAILED` — `info` discovery failed or response omits
|
||||
* the REQUIRED `oauth2` base URL.
|
||||
*
|
||||
* Safe to call concurrently — a second call during in-flight discovery
|
||||
* awaits the same promise instead of starting a duplicate request.
|
||||
*/
|
||||
export const getCscTransport = async (): Promise<CscTransport> => {
|
||||
if (globalThis.__documenso_csc_transport__) {
|
||||
return globalThis.__documenso_csc_transport__;
|
||||
}
|
||||
|
||||
if (!globalThis.__documenso_csc_transport_promise__) {
|
||||
globalThis.__documenso_csc_transport_promise__ = buildCscTransport()
|
||||
.then((transport) => {
|
||||
globalThis.__documenso_csc_transport__ = transport;
|
||||
return transport;
|
||||
})
|
||||
.finally(() => {
|
||||
globalThis.__documenso_csc_transport_promise__ = undefined;
|
||||
});
|
||||
}
|
||||
|
||||
return await globalThis.__documenso_csc_transport_promise__;
|
||||
};
|
||||
|
||||
/**
|
||||
* Drop the cached transport. Intended for tests / operator-triggered reload
|
||||
* after a license-key swap. Next {@link getCscTransport} call re-runs the
|
||||
* full build pipeline (license + env + discovery).
|
||||
*/
|
||||
export const resetCscTransport = (): void => {
|
||||
globalThis.__documenso_csc_transport__ = undefined;
|
||||
globalThis.__documenso_csc_transport_promise__ = undefined;
|
||||
};
|
||||
|
||||
const buildCscTransport = async (): Promise<CscTransport> => {
|
||||
if (!IS_INSTANCE_CSC_MODE()) {
|
||||
throw new AppError(AppErrorCode.NOT_SETUP, {
|
||||
message: 'CSC transport requested but NEXT_PRIVATE_SIGNING_TRANSPORT is not "csc".',
|
||||
});
|
||||
}
|
||||
|
||||
await assertLicensedFor('instanceCscSigning', { errorCode: AppErrorCode.CSC_UNLICENSED });
|
||||
|
||||
const serviceBaseUrl = requireEnv('NEXT_PRIVATE_SIGNING_CSC_PROVIDER_BASE_URL');
|
||||
const clientId = requireEnv('NEXT_PRIVATE_SIGNING_CSC_OAUTH_CLIENT_ID');
|
||||
const clientSecret = requireEnv('NEXT_PRIVATE_SIGNING_CSC_OAUTH_CLIENT_SECRET');
|
||||
const oauthRedirectUri = `${NEXT_PUBLIC_WEBAPP_URL()}/api/csc/oauth/callback`;
|
||||
|
||||
const oauthClient = createCscOAuthClient({ clientId, clientSecret, redirectUri: oauthRedirectUri });
|
||||
|
||||
const info = await cscInfo({
|
||||
baseUrl: serviceBaseUrl,
|
||||
signal: AbortSignal.timeout(DISCOVERY_TIMEOUT_MS),
|
||||
});
|
||||
|
||||
if (!info.oauth2) {
|
||||
throw new AppError(AppErrorCode.CSC_PROVIDER_INFO_FAILED, {
|
||||
message:
|
||||
'CSC TSP info response omits the required `oauth2` base URL. CSC QES V1 only supports OAuth-based authorization (§8.3) — non-OAuth TSPs are not compatible.',
|
||||
});
|
||||
}
|
||||
|
||||
const supportsTimestamp = info.methods.includes(CSC_TIMESTAMP_METHOD);
|
||||
|
||||
// Boot-time TSA invariant: `NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY` is
|
||||
// required unconditionally in CSC mode. Sign-time B-T can use the TSP's
|
||||
// own `signatures/timestamp` endpoint when advertised, but seal-time
|
||||
// B-LTA archival is env-only by design (operators should pin a dedicated
|
||||
// qualified archival TSA — see `resolveCscSealTimeTsa`). Without env, an
|
||||
// envelope would sign successfully and then hang in
|
||||
// WAITING_FOR_SIGNATURE_COMPLETION when the seal job throws. Catch the
|
||||
// misconfiguration at boot instead so the instance refuses to start.
|
||||
if (!isEnvTsaConfigured()) {
|
||||
throw new AppError(AppErrorCode.CSC_PROVIDER_NO_TSA, {
|
||||
message:
|
||||
'NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY is unset. AES/QES envelopes require a TSA for B-LTA archival at seal time regardless of whether the CSC TSP advertises signatures/timestamp for B-T sign-time. Configure NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY.',
|
||||
});
|
||||
}
|
||||
|
||||
return {
|
||||
serviceBaseUrl,
|
||||
oauthBaseUrl: info.oauth2,
|
||||
oauthClient,
|
||||
oauthRedirectUri,
|
||||
supportsTimestamp,
|
||||
info,
|
||||
};
|
||||
};
|
||||
@@ -0,0 +1,105 @@
|
||||
import { NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY } from '@documenso/lib/constants/app';
|
||||
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
import { HttpTimestampAuthority, type TimestampAuthority } from '@libpdf/core';
|
||||
|
||||
import type { CscTransport } from './transport';
|
||||
import { CscTspTimestampAuthority } from './tsp-timestamp-authority';
|
||||
|
||||
/**
|
||||
* Two-phase TSA resolution for the CSC transport.
|
||||
*
|
||||
* Phase 1 — sign time (PAdES B-T, per recipient signature).
|
||||
* Each recipient's CMS gets a signature timestamp embedded as an unsigned
|
||||
* attribute. {@link resolveCscSignTimeTsa} returns a libpdf-shaped
|
||||
* `TimestampAuthority` bound to either the TSP's `signatures/timestamp`
|
||||
* endpoint (authorised with the recipient's own service-scope bearer) or
|
||||
* the operator's env-configured RFC 3161 TSA, whichever is configured.
|
||||
* TSP wins precedence so a TSP-supplied TSA is the default when the TSP
|
||||
* advertises the method.
|
||||
*
|
||||
* Phase 2 — seal time (PAdES B-LTA archival timestamp).
|
||||
* The seal-document job emits one `/DocTimeStamp` over the fully-signed
|
||||
* envelope. {@link resolveCscSealTimeTsa} returns the env-configured TSA
|
||||
* only — the archival anchor SHOULD be a dedicated qualified archival
|
||||
* TSA, independent of the per-recipient TSP. Using the TSP here would
|
||||
* couple archive longevity to a TSP that may rotate or revoke, and seal
|
||||
* time has no recipient context to carry a service-scope bearer anyway.
|
||||
*
|
||||
* Boot-time guard: {@link buildCscTransport} asserts
|
||||
* `NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY` is set unconditionally — seal
|
||||
* time always needs it, so making it env-or-fail at boot also satisfies
|
||||
* the sign-time fallback. The defensive throws inside the resolvers below
|
||||
* should be unreachable in practice.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Build a libpdf `TimestampAuthority` for a recipient's B-T sign-time
|
||||
* signature timestamp.
|
||||
*
|
||||
* Precedence: TSP first, env fallback. Selection is made up-front based on
|
||||
* the boot-discovered transport capability — we don't try TSP then fall
|
||||
* through to env on a runtime error. If the chosen source fails at call
|
||||
* time, the recipient's sign attempt fails (operator's recourse is to
|
||||
* configure env, which then wins on the next sign).
|
||||
*
|
||||
* `serviceToken` is the decrypted, non-expired service-scope bearer for
|
||||
* the current recipient — used only when the TSP source is selected.
|
||||
*/
|
||||
export const resolveCscSignTimeTsa = (transport: CscTransport, serviceToken: string): TimestampAuthority => {
|
||||
if (transport.supportsTimestamp) {
|
||||
return new CscTspTimestampAuthority({ transport, serviceToken });
|
||||
}
|
||||
|
||||
const envUrls = parseTsaEnv(NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY());
|
||||
|
||||
if (envUrls.length > 0) {
|
||||
return new HttpTimestampAuthority(envUrls[0]);
|
||||
}
|
||||
|
||||
// Boot-time guard in `buildCscTransport` should have rejected this
|
||||
// configuration before any recipient hit this code path.
|
||||
throw new AppError(AppErrorCode.CSC_PROVIDER_NO_TSA, {
|
||||
message:
|
||||
'CSC sign-time TSA unresolved: TSP does not advertise signatures/timestamp and NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY is unset. This should have been caught by the boot-time guard in buildCscTransport.',
|
||||
});
|
||||
};
|
||||
|
||||
/**
|
||||
* Resolve the seal-time archival TSA URLs (env only).
|
||||
*
|
||||
* Returns the parsed env list; the caller picks how to consume it (today
|
||||
* `finalize-tsp-completion.ts` uses the first URL).
|
||||
*/
|
||||
export const resolveCscSealTimeTsa = (): { urls: string[] } => {
|
||||
const envUrls = parseTsaEnv(NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY());
|
||||
|
||||
if (envUrls.length === 0) {
|
||||
throw new AppError(AppErrorCode.CSC_PROVIDER_NO_TSA, {
|
||||
message:
|
||||
'CSC seal-time archival timestamps require NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY. This should have been caught by the boot-time guard in buildCscTransport — the env var is required at seal time even when the TSP advertises signatures/timestamp.',
|
||||
});
|
||||
}
|
||||
|
||||
return { urls: envUrls };
|
||||
};
|
||||
|
||||
/**
|
||||
* Cheap boot-time predicate — used by `buildCscTransport` to decide
|
||||
* whether the env TSA satisfies the "at least one source must be
|
||||
* configured" invariant. Keeping the env parsing in one place avoids
|
||||
* drift between the guard and the resolvers.
|
||||
*/
|
||||
export const isEnvTsaConfigured = (): boolean => {
|
||||
return parseTsaEnv(NEXT_PRIVATE_SIGNING_TIMESTAMP_AUTHORITY()).length > 0;
|
||||
};
|
||||
|
||||
const parseTsaEnv = (raw: string | undefined): string[] => {
|
||||
if (!raw) {
|
||||
return [];
|
||||
}
|
||||
|
||||
return raw
|
||||
.split(',')
|
||||
.map((url) => url.trim())
|
||||
.filter(Boolean);
|
||||
};
|
||||
@@ -0,0 +1,82 @@
|
||||
import { AppError, AppErrorCode } from '@documenso/lib/errors/app-error';
|
||||
import type { DigestAlgorithm, TimestampAuthority } from '@libpdf/core';
|
||||
|
||||
import { hashOidForDigest } from './algorithm-resolver';
|
||||
import { cscTimestamp } from './client/signatures';
|
||||
import type { CscTransport } from './transport';
|
||||
|
||||
/**
|
||||
* libpdf {@link TimestampAuthority} backed by the CSC TSP's
|
||||
* `signatures/timestamp` endpoint (§11.10).
|
||||
*
|
||||
* Used only at sign time, per recipient, when {@link resolveCscSignTimeTsa}
|
||||
* selects the TSP source — that is, when the TSP advertises
|
||||
* `signatures/timestamp` in `info.methods`. The token wired in is the
|
||||
* current recipient's own service-scope bearer (the same one authorising
|
||||
* the `signatures/signHash` call alongside it), so the timestamp gets
|
||||
* attributed to the same identity that just authorised the signature.
|
||||
*
|
||||
* Seal-time archival timestamps do not use this class — they go through
|
||||
* the env-only path in `finalize-tsp-completion.ts`.
|
||||
*
|
||||
* Failure semantics: a single `signatures/timestamp` call. On any error
|
||||
* (HTTP, schema, expired token) we surface `CSC_PROVIDER_NO_TSA` with the
|
||||
* upstream message folded in. There's no try-in-order — at sign time the
|
||||
* recipient is fixed, so there's no other token to fall through to.
|
||||
*/
|
||||
|
||||
type CscTspTimestampAuthorityOptions = {
|
||||
transport: CscTransport;
|
||||
/** Decrypted service-scope access token for the current recipient. */
|
||||
serviceToken: string;
|
||||
/** Optional deadline for the `signatures/timestamp` call. */
|
||||
signal?: AbortSignal;
|
||||
};
|
||||
|
||||
export class CscTspTimestampAuthority implements TimestampAuthority {
|
||||
private readonly transport: CscTransport;
|
||||
|
||||
private readonly serviceToken: string;
|
||||
|
||||
private readonly signal?: AbortSignal;
|
||||
|
||||
constructor(opts: CscTspTimestampAuthorityOptions) {
|
||||
this.transport = opts.transport;
|
||||
this.serviceToken = opts.serviceToken;
|
||||
this.signal = opts.signal;
|
||||
}
|
||||
|
||||
/**
|
||||
* Request a CSC §11.10 timestamp for the supplied digest, authorised with
|
||||
* the recipient's service-scope bearer. Returns the decoded TimeStampToken
|
||||
* bytes. Throws `CSC_PROVIDER_NO_TSA` carrying the upstream error message
|
||||
* on failure.
|
||||
*
|
||||
* `algorithm` is libpdf's `DigestAlgorithm` (`SHA-256` / `SHA-384` /
|
||||
* `SHA-512`), translated to the matching `hashAlgo` OID via the existing
|
||||
* {@link hashOidForDigest} mapping so the spec's OID-typed payload stays
|
||||
* in one place.
|
||||
*/
|
||||
async timestamp(digest: Uint8Array, algorithm: DigestAlgorithm): Promise<Uint8Array> {
|
||||
const hash = Buffer.from(digest).toString('base64');
|
||||
const hashAlgo = hashOidForDigest(algorithm);
|
||||
|
||||
try {
|
||||
const response = await cscTimestamp({
|
||||
baseUrl: this.transport.serviceBaseUrl,
|
||||
accessToken: this.serviceToken,
|
||||
hash,
|
||||
hashAlgo,
|
||||
signal: this.signal,
|
||||
});
|
||||
|
||||
return Buffer.from(response.timestamp, 'base64');
|
||||
} catch (err) {
|
||||
const message = err instanceof Error ? err.message : String(err);
|
||||
|
||||
throw new AppError(AppErrorCode.CSC_PROVIDER_NO_TSA, {
|
||||
message: `CSC TSP timestamp endpoint refused the recipient's service token: ${message}.`,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user