@awacloud/pdf 0.0.0-stage → 1.0.0

package/src/sig/certChain.js

@@ -0,0 +1,247 @@
+// Copyright (c) 2026 AwaCloud SAS
+// Author: Matthieu Bouilloux
+// SPDX-License-Identifier: AGPL-3.0-only
+// Dual-licensed; see the NOTICE file for licensing and any additional terms.
+
+/**
+ * @fileoverview X.509 certificate chain extraction from a PKCS#7
+ * SignedData blob.
+ *
+ * - `extractCertsFromCms(blob, asn1)` → typed records for each cert in
+ *   the SignedData `certificates [0]` field.
+ * - `extractCertFromPem(pem, pemMod, asn1)` → typed record from a PEM
+ *   block.
+ * - `findIssuer(cert, candidates)` / `validateChainOrder(chain)` →
+ *   structural chain checks (subject = next.issuer), no signature
+ *   verification at this layer.
+ *
+ * @module pdf/sig/certChain
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfSigOids } from './oids.js';
+import { asn1 } from '@awacloud/fw/crypto/utils/asn1.js';
+import { pem } from '@awacloud/fw/crypto/utils/pem.js';
+
+export const pdfCertChain = {
+    name: 'pdfCertChain',
+    dependencies: ['pdfErrors', 'pdfSigOids', 'asn1', 'pem'],
+    deps: [pdfErrors, pdfSigOids, asn1, pem],
+    factory(errors, sigOids, asn1, pem) {
+        const { EncryptionError, ParseError } = errors;
+        const {
+            KEY_ALG_OIDS,
+            SIG_ALG_OIDS_VERBOSE: SIG_ALG_OIDS,
+            shortOid: _shortOid
+        } = sigOids;
+
+        function _parseUtcOrGeneralizedTime(node) {
+            if (!node) return null;
+            const s = String.fromCharCode.apply(null, Array.from(node.value));
+            let yr, mo, da, hr, mi, se;
+            if (node.tag === 0x17) {        // UTCTime: YYMMDDhhmmssZ
+                const m = /^(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})/.exec(s);
+                if (!m) return null;
+                yr = +m[1]; yr += yr < 50 ? 2000 : 1900;
+                mo = +m[2] - 1; da = +m[3]; hr = +m[4]; mi = +m[5]; se = +m[6];
+            } else if (node.tag === 0x18) { // GeneralizedTime: YYYYMMDDhhmmssZ
+                const m = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})/.exec(s);
+                if (!m) return null;
+                yr = +m[1]; mo = +m[2] - 1; da = +m[3];
+                hr = +m[4]; mi = +m[5]; se = +m[6];
+            } else { return null; }
+            return new Date(Date.UTC(yr, mo, da, hr, mi, se));
+        }
+
+        function _renderName(seqValue, asn1Mod) {
+            const rdns = asn1Mod.parseChildren(seqValue);
+            if (!rdns) return '';
+            const parts = [];
+            for (let i = 0; i < rdns.length; i++) {
+                const set = asn1Mod.parseChildren(rdns[i].value);
+                if (!set) continue;
+                for (let j = 0; j < set.length; j++) {
+                    const tv = asn1Mod.parseChildren(set[j].value);
+                    if (!tv || tv.length < 2) continue;
+                    const oid = asn1Mod.readOid(tv[0]);
+                    const valBytes = tv[1].value;
+                    const val = String.fromCharCode.apply(null, Array.from(valBytes));
+                    parts.push(_shortOid(oid) + '=' + val);
+                }
+            }
+            return parts.join(',');
+        }
+
+        function _reconstructDer(node, parentBuf) {
+            const len = node.length;
+            let lenLen;
+            if (len < 0x80) lenLen = 1;
+            else if (len < 0x100) lenLen = 2;
+            else if (len < 0x10000) lenLen = 3;
+            else if (len < 0x1000000) lenLen = 4;
+            else lenLen = 5;
+            return parentBuf.subarray(node.valueOff - 1 - lenLen, node.next);
+        }
+
+        function parseCertificate(der, asn1Mod) {
+            const a1 = asn1Mod || asn1;
+            const top = a1.parseOne(der, 0);
+            if (!top) {
+                throw new ParseError('pdf/cert/malformed',
+                    'Certificate top-level SEQUENCE parse failed');
+            }
+            const cert = a1.parseChildren(top.value);
+            if (!cert || cert.length < 3) {
+                throw new ParseError('pdf/cert/short',
+                    'Certificate has fewer than 3 children');
+            }
+            const tbs = a1.parseChildren(cert[0].value);
+            if (!tbs) {
+                throw new ParseError('pdf/cert/bad-tbs',
+                    'tbsCertificate parse failed');
+            }
+            let idx = 0;
+            let version = 1;
+            if (tbs[idx] && tbs[idx].tag === 0xA0) {  // [0] EXPLICIT version
+                const v = a1.parseOne(tbs[idx].value, 0);
+                if (v && v.value && v.value.length) version = v.value[0] + 1;
+                idx++;
+            }
+            const serialNode = tbs[idx++];
+            idx++;
+            const issuerNode = tbs[idx++];
+            const validityNode = tbs[idx++];
+            const subjectNode = tbs[idx++];
+            const spkiNode = tbs[idx];
+            const validity = a1.parseChildren(validityNode.value);
+            const sigAlgChildren = a1.parseChildren(cert[1].value);
+            const sigAlgOid = sigAlgChildren && sigAlgChildren[0]
+                ? a1.readOid(sigAlgChildren[0]) : null;
+            const spki = a1.parseChildren(spkiNode.value);
+            const keyAlgChildren = spki && spki[0]
+                ? a1.parseChildren(spki[0].value) : null;
+            const keyAlgOid = keyAlgChildren && keyAlgChildren[0]
+                ? a1.readOid(keyAlgChildren[0]) : null;
+            return {
+                version,
+                serialNumber: serialNode ? serialNode.value : null,
+                issuer:  _renderName(issuerNode.value, a1),
+                subject: _renderName(subjectNode.value, a1),
+                notBefore: validity ? _parseUtcOrGeneralizedTime(validity[0]) : null,
+                notAfter:  validity ? _parseUtcOrGeneralizedTime(validity[1]) : null,
+                publicKey: spki && spki[1] ? spki[1].value : null,
+                keyAlgorithm: KEY_ALG_OIDS[keyAlgOid] || keyAlgOid,
+                sigAlgorithm: SIG_ALG_OIDS[sigAlgOid] || sigAlgOid,
+                raw: der
+            };
+        }
+
+        function extractCertsFromCms(blob, asn1Mod, opts) {
+            const a1 = asn1Mod || asn1;
+            if (!(blob instanceof Uint8Array)) {
+                throw new ParseError('pdf/cert/bad-input',
+                    'extractCertsFromCms expects a Uint8Array');
+            }
+            if (!a1 || typeof a1.parseOne !== 'function') {
+                throw new EncryptionError('pdf/cert/missing-fw',
+                    'extractCertsFromCms requires the fw asn1 module');
+            }
+            const warnings = opts && Array.isArray(opts.warnings) ? opts.warnings : null;
+            const ci = a1.parseOne(blob, 0);
+            if (!ci) return [];
+            const ciKids = a1.parseChildren(ci.value);
+            if (!ciKids || ciKids.length < 2) return [];
+            const sdNode = a1.parseOne(ciKids[1].value, 0);
+            if (!sdNode) return [];
+            const sd = a1.parseChildren(sdNode.value);
+            if (!sd) return [];
+            let certsField = null;
+            for (let i = 0; i < sd.length; i++) {
+                if (sd[i].tag === 0xA0) { certsField = sd[i]; break; }
+            }
+            if (!certsField) return [];
+            const certs = a1.parseChildren(certsField.value);
+            if (!certs) return [];
+            const out = [];
+            for (let i = 0; i < certs.length; i++) {
+                if (certs[i].tag !== 0x30) continue;
+                const der = _reconstructDer(certs[i], certsField.value);
+                try {
+                    out.push(parseCertificate(der, a1));
+                } catch (e) {
+                    if (warnings) {
+                        warnings.push({
+                            code: e && e.code ? e.code : 'pdf/cert/malformed',
+                            message: 'skipped malformed cert at index ' + i
+                                + ': ' + (e && e.message),
+                            context: { index: i }
+                        });
+                    }
+                }
+            }
+            return out;
+        }
+
+        function extractCertFromPem(pemString, pemMod, asn1Mod) {
+            const pm = pemMod || pem;
+            const a1 = asn1Mod || asn1;
+            if (typeof pemString !== 'string') {
+                throw new ParseError('pdf/cert/bad-pem-input',
+                    'extractCertFromPem expects a string');
+            }
+            if (!pm || typeof pm.decode !== 'function') {
+                throw new EncryptionError('pdf/cert/missing-pem',
+                    'extractCertFromPem requires the fw pem module');
+            }
+            const dec = pm.decode(pemString);
+            if (!dec || !dec.bytes) {
+                throw new ParseError('pdf/cert/pem-decode-failed',
+                    'PEM decode failed');
+            }
+            return parseCertificate(dec.bytes, a1);
+        }
+
+        function findIssuer(cert, candidates) {
+            if (!cert || !Array.isArray(candidates)) return null;
+            for (let i = 0; i < candidates.length; i++) {
+                if (candidates[i] === cert) continue;
+                if (candidates[i].subject === cert.issuer) return candidates[i];
+            }
+            return null;
+        }
+
+        function validateChainOrder(chain) {
+            const errs = [];
+            if (!Array.isArray(chain) || chain.length === 0) {
+                errs.push({ code: 'pdf/cert/empty-chain',
+                            message: 'chain must be a non-empty array' });
+                return { valid: false, errors: errs };
+            }
+            for (let i = 0; i < chain.length - 1; i++) {
+                if (chain[i].issuer !== chain[i + 1].subject) {
+                    errs.push({
+                        code: 'pdf/cert/chain-break',
+                        message: 'cert[' + i + '].issuer != cert['
+                            + (i + 1) + '].subject',
+                        context: {
+                            issuer: chain[i].issuer,
+                            subject: chain[i + 1].subject
+                        }
+                    });
+                }
+            }
+            return { valid: errs.length === 0, errors: errs };
+        }
+
+        return {
+            extractCertsFromCms,
+            extractCertFromPem,
+            parseCertificate,
+            findIssuer,
+            validateChainOrder
+        };
+    }
+};

package/src/sig/dss.js

@@ -0,0 +1,317 @@
+// Copyright (c) 2026 AwaCloud SAS
+// Author: Matthieu Bouilloux
+// SPDX-License-Identifier: AGPL-3.0-only
+// Dual-licensed; see the NOTICE file for licensing and any additional terms.
+
+/**
+ * @fileoverview PAdES-LT Document Security Store builder — produces
+ * the indirect objects (certs / OCSPs / CRLs / DSS dict / VRI dict)
+ * that a level-LT signer appends via the incremental writer to the
+ * already-signed (level B/T) PDF bytes.
+ *
+ * Spec : ETSI EN 319 142-1 V1.1.1 §5.4, ISO 32000-2:2020 §12.8.4.3.
+ *
+ *   DSS ::= <<
+ *     /Type /DSS
+ *     /Certs [N₁ 0 R N₂ 0 R …]    -- optional
+ *     /OCSPs [Nk 0 R …]           -- optional
+ *     /CRLs  [Nj 0 R …]           -- optional
+ *     /VRI   << /<sigHashHex> << /Cert [...] /OCSP [...] /CRL [...]
+ *                                 /TU? (M:...) /TS? Nₜ 0 R >> … >>
+ *   >>
+ *
+ * Each referenced cert/OCSP/CRL is an indirect *stream* whose body is
+ * the raw DER bytes and whose dict carries the `/Type /CertVal`,
+ * `/OCSPVal` or `/CRLVal` marker (Adobe extension, widely deployed).
+ *
+ * The factory does NOT touch the byte buffer. It produces a list of
+ * `{ num, gen, value }` updates compatible with
+ * `pdfIncrementalWriter.appendIncremental`, plus the DSS object number
+ * so the caller can also append an updated Catalog carrying
+ * `/DSS dssNum 0 R`.
+ *
+ * @module pdf/sig/dss
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfSha1 } from './sha1.js';
+import { bitArray } from '@awacloud/fw/crypto/utils/bitArray.js';
+
+export const pdfDssBuilder = {
+    name: 'pdfDssBuilder',
+    dependencies: ['pdfErrors', 'pdfSha1', 'bitArray'],
+    deps: [pdfErrors, pdfSha1, bitArray],
+    factory(errors, sha1Mod, bitArray) {
+        const { ContractError } = errors;
+
+        // ── SHA-1 hoisted to fw (FIPS 180-4 §6.1) ────────────────────
+        // Used solely for VRI key derivation per ISO 32000-2 §12.8.4.3
+        // (the VRI dict keys are the uppercase hex SHA-1 of each
+        // signature value bytes). SHA-1 is deprecated for general
+        // cryptographic use but PDF VRI keys still mandate it.
+        function _sha1(bytes) {
+            const digestBa = sha1Mod.hash(bitArray.ui8_to_ba(bytes));
+            return bitArray.ba_to_ui8(digestBa);
+        }
+        // PDF date string per ISO 32000-2:2020 §7.9.4 :
+        //   (D:YYYYMMDDHHmmSS+HH'mm') — used here for VRI `TU` entries
+        //   (ISO 32000-2 §12.8.4.3 : the time at which validation data
+        //   was obtained). Always emitted in UTC (`+00'00'`) so the
+        //   value is stable across runs and machine timezones.
+        function _pdfDate(date) {
+            const d = date instanceof Date ? date : new Date();
+            function p2(n) { return (n < 10 ? '0' : '') + n; }
+            return '(D:'
+                + d.getUTCFullYear()
+                + p2(d.getUTCMonth() + 1)
+                + p2(d.getUTCDate())
+                + p2(d.getUTCHours())
+                + p2(d.getUTCMinutes())
+                + p2(d.getUTCSeconds())
+                + "+00'00')";
+        }
+        function _toHexUpper(bytes) {
+            let s = '';
+            for (let i = 0; i < bytes.length; i++) {
+                const b = bytes[i];
+                s += (b < 16 ? '0' : '') + b.toString(16).toUpperCase();
+            }
+            return s;
+        }
+        function _scanSignatureContentsHex(bytes) {
+            // Find every `/Type /Sig` (incl. /DocTimeStamp) and extract
+            // the `/Contents <…hex…>` literal. Returns an array of
+            // uppercase hex strings (the raw hex from /Contents).
+            let s = '';
+            const CHUNK = 0x8000;
+            for (let i = 0; i < bytes.length; i += CHUNK) {
+                s += String.fromCharCode.apply(null,
+                    bytes.subarray(i, Math.min(i + CHUNK, bytes.length)));
+            }
+            const out = [];
+            const re = /(\d+)\s+(\d+)\s+obj\s*<<([\s\S]*?)>>\s*endobj/g;
+            let m;
+            while ((m = re.exec(s)) !== null) {
+                const body = m[3];
+                if (!/\/Type\s*\/(?:Sig|DocTimeStamp)\b/.test(body)) continue;
+                const cm = body.match(/\/Contents\s*<([0-9A-Fa-f]*)>/);
+                if (!cm) continue;
+                out.push(cm[1]);
+            }
+            return out;
+        }
+
+
+        function _refObj(num, gen) {
+            return { type: 'ref', num: num | 0, gen: gen | 0 };
+        }
+        function _intObj(v) { return { type: 'int', value: v | 0 }; }
+        function _nameObj(v) { return { type: 'name', value: String(v) }; }
+        function _strHexObj(s) {
+            // s is an ASCII hex string (e.g. SHA-1 of signature value).
+            // Emit it as a regular PDF string ; PDF VRI keys are NAMES
+            // composed of the hex characters per ISO 32000-2 §12.8.4.3.
+            return { type: 'name', value: String(s) };
+        }
+        function _arrayObj(items) { return { type: 'array', items }; }
+        function _dictObj(entries) { return { type: 'dict', entries }; }
+        function _streamObj(rawBytes, typeName) {
+            // Stream dict carries /Type — the writer auto-adds /Length.
+            return {
+                type: 'stream',
+                dict: _dictObj({
+                    Type: _nameObj(typeName)
+                }),
+                raw: rawBytes
+            };
+        }
+
+        /**
+         * Build DSS + supporting streams for an incremental append.
+         *
+         * @param {Object} args
+         * @param {Uint8Array[]} [args.certs] Cert DER bytes — required for
+         *   a useful DSS (at least one signer cert + chain).
+         * @param {Uint8Array[]} [args.ocsps] OCSP response DER bytes.
+         * @param {Uint8Array[]} [args.crls]  CRL DER bytes.
+         * @param {Object<string, Object>} [args.vri] Map of signature-hash
+         *   hex → { certs?, ocsps?, crls?, tu?, ts? } (each list is an
+         *   array of *indices* into the parent certs/ocsps/crls lists, or
+         *   raw DER bytes; ts? is a TimeStampToken DER as a stream).
+         * @param {number} args.startNum First free object number to
+         *   allocate (subsequent objects are sequential).
+         * @returns {{ updates: Array, dssNum: number, lastNum: number,
+         *             certNums: number[], ocspNums: number[],
+         *             crlNums: number[] }}
+         */
+        function buildDss(args) {
+            args = args || {};
+            const startNum = args.startNum | 0;
+            if (!Number.isFinite(startNum) || startNum < 2) {
+                throw new ContractError('pdf/dss/bad-startNum',
+                    'buildDss requires opts.startNum >= 2',
+                    { context: { startNum } });
+            }
+            const certs = Array.isArray(args.certs) ? args.certs : [];
+            const ocsps = Array.isArray(args.ocsps) ? args.ocsps : [];
+            const crls  = Array.isArray(args.crls)  ? args.crls  : [];
+
+            for (const c of certs) {
+                if (!(c instanceof Uint8Array)) {
+                    throw new ContractError('pdf/dss/bad-cert',
+                        'each cert must be a Uint8Array (DER)');
+                }
+            }
+            for (const o of ocsps) {
+                if (!(o instanceof Uint8Array)) {
+                    throw new ContractError('pdf/dss/bad-ocsp',
+                        'each ocsp must be a Uint8Array (DER)');
+                }
+            }
+            for (const c of crls) {
+                if (!(c instanceof Uint8Array)) {
+                    throw new ContractError('pdf/dss/bad-crl',
+                        'each crl must be a Uint8Array (DER)');
+                }
+            }
+
+            const updates = [];
+            let n = startNum;
+
+            const certNums = [];
+            for (const der of certs) {
+                certNums.push(n);
+                updates.push({ num: n, gen: 0, value: _streamObj(der, 'CertVal') });
+                n++;
+            }
+            const ocspNums = [];
+            for (const der of ocsps) {
+                ocspNums.push(n);
+                updates.push({ num: n, gen: 0, value: _streamObj(der, 'OCSPVal') });
+                n++;
+            }
+            const crlNums = [];
+            for (const der of crls) {
+                crlNums.push(n);
+                updates.push({ num: n, gen: 0, value: _streamObj(der, 'CRLVal') });
+                n++;
+            }
+
+            // Optional VRI auto-population : scan parent PDF bytes for
+            // every signature, derive the SHA-1(/Contents hex) key, and
+            // synthesise a VRI entry referencing all certs/ocsps/crls.
+            let vriArg = args.vri;
+            if (args.autoVri && args.parentBytes instanceof Uint8Array) {
+                const sigContents = _scanSignatureContentsHex(args.parentBytes);
+                const auto = vriArg && typeof vriArg === 'object'
+                    ? Object.assign({}, vriArg) : {};
+                const allCertIdx = certs.map((_, i) => i);
+                const allOcspIdx = ocsps.map((_, i) => i);
+                const allCrlIdx  = crls.map((_, i) => i);
+                // VRI `TU` = time at which validation data was obtained
+                // (ISO 32000-2 §12.8.4.3). PDF date string per §7.9.4.
+                // `args.vriTime` overrides the default of `new Date()` so
+                // tests can pin a deterministic value.
+                const tuDate = args.vriTime instanceof Date
+                    ? args.vriTime : new Date();
+                const tuPdfStr = _pdfDate(tuDate);
+                for (const hex of sigContents) {
+                    // SHA-1 of the *raw signature value bytes* (the binary
+                    // decoded from the /Contents hex literal), uppercase hex.
+                    const sigBytes = new Uint8Array(hex.length >>> 1);
+                    for (let i = 0; i < sigBytes.length; i++) {
+                        sigBytes[i] = parseInt(hex.substr(i * 2, 2), 16);
+                    }
+                    const key = _toHexUpper(_sha1(sigBytes));
+                    if (auto[key]) continue;
+                    const entry = { tu: tuPdfStr };
+                    if (allCertIdx.length) entry.certs = allCertIdx;
+                    if (allOcspIdx.length) entry.ocsps = allOcspIdx;
+                    if (allCrlIdx.length)  entry.crls  = allCrlIdx;
+                    auto[key] = entry;
+                }
+                vriArg = auto;
+            }
+            let vriEntries = null;
+            if (vriArg && typeof vriArg === 'object') {
+                vriEntries = {};
+                for (const k of Object.keys(vriArg)) {
+                    const v = vriArg[k] || {};
+                    const e = {};
+                    function _refsFrom(spec, parentNums) {
+                        if (!Array.isArray(spec)) return null;
+                        const refs = [];
+                        for (const it of spec) {
+                            if (typeof it === 'number') {
+                                if (it < 0 || it >= parentNums.length) {
+                                    throw new ContractError('pdf/dss/vri-bad-index',
+                                        'VRI index out of bounds',
+                                        { context: { index: it } });
+                                }
+                                refs.push(_refObj(parentNums[it], 0));
+                            } else if (it instanceof Uint8Array) {
+                                // Promote raw DER to a new stream.
+                                const newNum = n++;
+                                updates.push({ num: newNum, gen: 0,
+                                    value: _streamObj(it, 'CertVal') });
+                                refs.push(_refObj(newNum, 0));
+                            }
+                        }
+                        return _arrayObj(refs);
+                    }
+                    const c = _refsFrom(v.certs, certNums);
+                    const o = _refsFrom(v.ocsps, ocspNums);
+                    const r = _refsFrom(v.crls, crlNums);
+                    if (c) e.Cert = c;
+                    if (o) e.OCSP = o;
+                    if (r) e.CRL  = r;
+                    if (typeof v.tu === 'string') {
+                        e.TU = { type: 'string',
+                                 value: new TextEncoder().encode(v.tu) };
+                    }
+                    if (v.ts instanceof Uint8Array) {
+                        const newNum = n++;
+                        updates.push({ num: newNum, gen: 0,
+                            value: _streamObj(v.ts, 'TS') });
+                        e.TS = _refObj(newNum, 0);
+                    }
+                    vriEntries[k] = _dictObj(e);
+                }
+            }
+
+            const dssEntries = { Type: _nameObj('DSS') };
+            if (certNums.length) {
+                dssEntries.Certs = _arrayObj(certNums.map(num => _refObj(num, 0)));
+            }
+            if (ocspNums.length) {
+                dssEntries.OCSPs = _arrayObj(ocspNums.map(num => _refObj(num, 0)));
+            }
+            if (crlNums.length) {
+                dssEntries.CRLs = _arrayObj(crlNums.map(num => _refObj(num, 0)));
+            }
+            if (vriEntries) {
+                dssEntries.VRI = _dictObj(vriEntries);
+            }
+            const dssNum = n++;
+            updates.push({ num: dssNum, gen: 0, value: _dictObj(dssEntries) });
+
+            return {
+                updates,
+                dssNum,
+                lastNum: n - 1,
+                certNums, ocspNums, crlNums
+            };
+        }
+
+        return {
+            buildDss,
+            // Exposed for test wiring + helpers.
+            _refObj, _intObj, _nameObj, _strHexObj,
+            _arrayObj, _dictObj, _streamObj,
+            _sha1, _toHexUpper, _scanSignatureContentsHex, _pdfDate
+        };
+    }
+};