@awacloud/pdf 0.0.0-stage → 1.0.0

package/src/extra/sig-aes-gcm.js

@@ -0,0 +1,135 @@
+// 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 Opt-in: AES-GCM crypt filter wrapper for `/Encrypt`
+ * dictionaries — ISO/TS 32003.
+ *
+ * @module pdf/extra/sig-aes-gcm
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfSigAesGcm = {
+    name: 'pdfSigAesGcm',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parser) {
+        const { ParseError, EncryptionError } = errors;
+        const { isType } = parser;
+
+        /** Frozen catalog of known Crypt Filter Methods (CFM names). */
+        const CFM_CATALOG = Object.freeze({
+            None:   { cipher: 'none', keyBits: 0,   notes: 'identity / stream-as-is' },
+            V2:     { cipher: 'rc4',  keyBits: 40,  notes: 'legacy RC4 (deprecated)' },
+            AESV2:  { cipher: 'aes',  keyBits: 128, mode: 'cbc',
+                      notes: 'AES-128 CBC (R4)' },
+            AESV3:  { cipher: 'aes',  keyBits: 256, mode: 'cbc',
+                      notes: 'AES-256 CBC (R6, ISO 32000-2)' },
+            AESV4:  { cipher: 'aes',  keyBits: 256, mode: 'gcm',
+                      notes: 'AES-256 GCM (ISO/TS 32003)' }
+        });
+
+        const ENCRYPT_KNOWN = new Set([
+            'Filter', 'SubFilter', 'V', 'Length', 'CF', 'StmF', 'StrF', 'EFF',
+            'R', 'O', 'U', 'OE', 'UE', 'Perms', 'P', 'EncryptMetadata'
+        ]);
+        const CF_ENTRY_KNOWN = new Set(['Type', 'CFM', 'AuthEvent', 'Length']);
+
+        function typeEncryptForGcm(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/extra/sig-aes-gcm/not-dict',
+                    '/Encrypt must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            const out = {
+                v:        isType(e.V, 'int') ? e.V.value : null,
+                r:        isType(e.R, 'int') ? e.R.value : null,
+                length:   isType(e.Length, 'int') ? e.Length.value : null,
+                stmF:     isType(e.StmF, 'name') ? e.StmF.value : null,
+                strF:     isType(e.StrF, 'name') ? e.StrF.value : null,
+                eff:      isType(e.EFF,  'name') ? e.EFF.value  : null,
+                cf:       {},
+                hasAesGcm: false,
+                raw:      dict,
+                _extras:  {}
+            };
+            if (e.CF !== undefined) {
+                if (!isType(e.CF, 'dict')) {
+                    throw new ParseError('pdf/extra/sig-aes-gcm/bad-cf',
+                        '/CF must be a dictionary',
+                        { context: { type: e.CF.type } });
+                }
+                for (const name of Object.keys(e.CF.entries)) {
+                    const entry = e.CF.entries[name];
+                    if (!isType(entry, 'dict')) {
+                        throw new ParseError('pdf/extra/sig-aes-gcm/bad-cf-entry',
+                            '/CF entry must be a dictionary',
+                            { context: { name } });
+                    }
+                    out.cf[name] = typeCfEntry(entry);
+                    if (out.cf[name].cfm === 'AESV4') out.hasAesGcm = true;
+                }
+            }
+            for (const k of Object.keys(e)) {
+                if (!ENCRYPT_KNOWN.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        function typeCfEntry(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/extra/sig-aes-gcm/cf-entry-not-dict',
+                    'CF entry must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            const cfm = isType(e.CFM, 'name') ? e.CFM.value : null;
+            const out = {
+                cfm,
+                authEvent: isType(e.AuthEvent, 'name') ? e.AuthEvent.value : null,
+                length:    isType(e.Length, 'int') ? e.Length.value : null,
+                catalog:   cfm && CFM_CATALOG[cfm] ? CFM_CATALOG[cfm] : null,
+                raw:       dict,
+                _extras:   {}
+            };
+            for (const k of Object.keys(e)) {
+                if (!CF_ENTRY_KNOWN.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        function validateGcmFraming(framed) {
+            if (!(framed instanceof Uint8Array)) {
+                throw new EncryptionError('pdf/extra/sig-aes-gcm/bad-input',
+                    'framed input must be a Uint8Array',
+                    { context: { type: typeof framed } });
+            }
+            if (framed.length < 12 + 16) {
+                throw new EncryptionError('pdf/extra/sig-aes-gcm/too-short',
+                    'AES-GCM framed blob must be at least 28 bytes (IV+tag)',
+                    { context: { length: framed.length } });
+            }
+            return {
+                iv:         framed.subarray(0, 12),
+                ciphertext: framed.subarray(12, framed.length - 16),
+                tag:        framed.subarray(framed.length - 16)
+            };
+        }
+
+        return {
+            typeEncryptForGcm,
+            typeCfEntry,
+            validateGcmFraming,
+            CFM_CATALOG
+        };
+    }
+};
+

package/src/extra/sig-pades.js

@@ -0,0 +1,242 @@
+// 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 Opt-in: PAdES (ETSI EN 319 142-1) profile detection
+ * for signature dicts, `/Reference` array typing, and DSS (Document
+ * Security Store) dict typing per ISO 32000-2:2020 §12.8.4.3.
+ *
+ * @module pdf/extra/sig-pades
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfSigPades = {
+    name: 'pdfSigPades',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parser) {
+        const { ParseError } = errors;
+        const { isType } = parser;
+
+        /** Frozen catalog of recognized signature SubFilter names. */
+        const SIG_SUBFILTERS = Object.freeze({
+            'adbe.x509.rsa_sha1':    { pades: false, kind: 'legacy' },
+            'adbe.pkcs7.sha1':       { pades: false, kind: 'legacy' },
+            'adbe.pkcs7.detached':   { pades: false, kind: 'pkcs7-detached' },
+            'ETSI.CAdES.detached':   { pades: true,  kind: 'pades-cades' },
+            'ETSI.RFC3161':          { pades: true,  kind: 'doc-timestamp' }
+        });
+
+        function detectPadesProfile(sigDict, ctx) {
+            if (!isType(sigDict, 'dict')) {
+                throw new ParseError('pdf/extra/pades/not-dict',
+                    'signature dict must be a dictionary',
+                    { context: { type: sigDict && sigDict.type } });
+            }
+            const e = sigDict.entries;
+            const sf = isType(e.SubFilter, 'name') ? e.SubFilter.value : null;
+            const info = sf ? SIG_SUBFILTERS[sf] : null;
+            const isPades = !!(info && info.pades);
+            const hasTimestamp = !!(
+                sf === 'ETSI.RFC3161' ||
+                (e.M && isType(e.M, 'string')) ||
+                (ctx && ctx.hasSignatureTimestamp)
+            );
+            let level = null;
+            if (isPades) {
+                const hasDss = !!(ctx && ctx.dss);
+                const ltaTs = !!(ctx && ctx.hasDocTimestampOverDss);
+                if (ltaTs)        level = 'B-LTA';
+                else if (hasDss)  level = 'B-LT';
+                else if (hasTimestamp) level = 'B-T';
+                else              level = 'B-B';
+            }
+            return { subFilter: sf, isPades, level, hasTimestamp };
+        }
+
+        function typeReferenceArray(arr) {
+            if (!isType(arr, 'array')) {
+                throw new ParseError('pdf/extra/pades/bad-reference',
+                    '/Reference must be an array',
+                    { context: { type: arr && arr.type } });
+            }
+            const out = [];
+            for (const it of arr.items) {
+                if (!isType(it, 'dict')) {
+                    throw new ParseError('pdf/extra/pades/bad-reference-item',
+                        '/Reference items must be dicts');
+                }
+                const e = it.entries;
+                if (e.Type && (e.Type.type !== 'name' || e.Type.value !== 'SigRef')) {
+                    throw new ParseError('pdf/extra/pades/bad-reference-type',
+                        '/Type of /Reference item must be /SigRef',
+                        { context: { actual: e.Type.value } });
+                }
+                out.push({
+                    transformMethod: isType(e.TransformMethod, 'name') ? e.TransformMethod.value : null,
+                    transformParams: isType(e.TransformParams, 'dict') ? e.TransformParams : null,
+                    data:            e.Data || null,
+                    digestMethod:    isType(e.DigestMethod, 'name') ? e.DigestMethod.value : null,
+                    raw:             it
+                });
+            }
+            return out;
+        }
+
+        function typeDSS(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/extra/pades/dss-not-dict',
+                    'DSS must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (e.Type && (e.Type.type !== 'name' || e.Type.value !== 'DSS')) {
+                throw new ParseError('pdf/extra/pades/dss-bad-type',
+                    '/Type of DSS dict must be /DSS',
+                    { context: { actual: e.Type.value } });
+            }
+            const out = {
+                certs:   refsArray(e.Certs, 'DSS /Certs'),
+                crls:    refsArray(e.CRLs,  'DSS /CRLs'),
+                ocsps:   refsArray(e.OCSPs, 'DSS /OCSPs'),
+                vri:     isType(e.VRI, 'dict') ? typeVRI(e.VRI) : null,
+                raw:     dict,
+                _extras: {}
+            };
+            const known = new Set(['Type', 'Certs', 'CRLs', 'OCSPs', 'VRI']);
+            for (const k of Object.keys(e)) if (!known.has(k)) out._extras[k] = e[k];
+            return out;
+        }
+
+        function typeVRI(dict) {
+            const out = {};
+            for (const k of Object.keys(dict.entries)) {
+                const v = dict.entries[k];
+                if (!isType(v, 'dict')) continue;
+                const ve = v.entries;
+                out[k] = {
+                    cert:  refsArray(ve.Cert,  'VRI /Cert'),
+                    crl:   refsArray(ve.CRL,   'VRI /CRL'),
+                    ocsp:  refsArray(ve.OCSP,  'VRI /OCSP'),
+                    tu:    isType(ve.TU, 'string') ? ve.TU.value : null,
+                    ts:    ve.TS || null
+                };
+            }
+            return out;
+        }
+
+        function refsArray(v, ctxLabel) {
+            if (!v) return null;
+            if (!isType(v, 'array')) {
+                throw new ParseError('pdf/extra/pades/dss-bad-array',
+                    `${ctxLabel} must be an array`,
+                    { context: { type: v.type } });
+            }
+            return v.items;
+        }
+
+        function validateDocMdp(ref) {
+            const issues = [];
+            if (!ref || ref.transformMethod !== 'DocMDP') {
+                issues.push({
+                    code: 'pdf/extra/pades/mdp/wrong-transform',
+                    message: 'reference is not a DocMDP transform',
+                    context: { transformMethod: ref && ref.transformMethod }
+                });
+                return { valid: false, level: null, issues };
+            }
+            if (!ref.transformParams || !isType(ref.transformParams, 'dict')) {
+                issues.push({
+                    code: 'pdf/extra/pades/mdp/missing-params',
+                    message: 'DocMDP missing /TransformParams dict'
+                });
+                return { valid: false, level: null, issues };
+            }
+            const params = ref.transformParams.entries;
+            let level = null;
+            if (params.P) {
+                if (params.P.type !== 'int') {
+                    issues.push({
+                        code: 'pdf/extra/pades/mdp/bad-p-type',
+                        message: '/P must be an integer',
+                        context: { type: params.P.type }
+                    });
+                } else if (params.P.value < 1 || params.P.value > 3) {
+                    issues.push({
+                        code: 'pdf/extra/pades/mdp/bad-p-value',
+                        message: '/P must be 1, 2 or 3',
+                        context: { value: params.P.value }
+                    });
+                } else {
+                    level = params.P.value;
+                }
+            } else {
+                level = 2;
+            }
+            if (params.V && params.V.type === 'name'
+                && params.V.value !== '1.2'
+                && params.V.value !== '2.2') {
+                issues.push({
+                    code: 'pdf/extra/pades/mdp/bad-version',
+                    message: 'unknown DocMDP /V',
+                    context: { v: params.V.value }
+                });
+            }
+            if (!ref.digestMethod) {
+                issues.push({
+                    code: 'pdf/extra/pades/mdp/missing-digest',
+                    message: 'DocMDP reference missing /DigestMethod'
+                });
+            }
+            return { valid: issues.length === 0, level, issues };
+        }
+
+        function validateBLtaChain(steps) {
+            if (!Array.isArray(steps)) {
+                throw new ParseError('pdf/extra/pades/chain/bad-input',
+                    'validateBLtaChain expects an array of steps',
+                    { context: { type: typeof steps } });
+            }
+            const trace = [];
+            let sawDss = false;
+            let sawDocTsOverDss = false;
+            for (let i = 0; i < steps.length; i++) {
+                const step = steps[i];
+                if (!step || !step.sigDict) {
+                    throw new ParseError('pdf/extra/pades/chain/missing-sig',
+                        'step missing sigDict',
+                        { context: { index: i } });
+                }
+                if (step.hasDss) sawDss = true;
+                if (step.hasDocTimestamp && sawDss) sawDocTsOverDss = true;
+                const ctx = {
+                    dss: sawDss ? {} : undefined,
+                    hasDocTimestampOverDss: sawDocTsOverDss,
+                    hasSignatureTimestamp: !!step.hasSignatureTimestamp
+                };
+                const detected = detectPadesProfile(step.sigDict, ctx);
+                trace.push({ index: i, level: detected.level,
+                             isPades: detected.isPades });
+            }
+            const last = trace[trace.length - 1];
+            return { chainLevel: last ? last.level : null, trace };
+        }
+
+        return {
+            detectPadesProfile,
+            typeReferenceArray,
+            typeDSS,
+            validateDocMdp,
+            validateBLtaChain,
+            SIG_SUBFILTERS
+        };
+    }
+};
+

package/src/extra/tagged-pdf-typed.js

@@ -0,0 +1,203 @@
+// 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 Opt-in: typed StructElem attribute objects per
+ * ISO 32000-2:2020 §14.8.5 (standard structure attribute owners) —
+ * Layout (§14.8.5.4), List (§14.8.5.5), Table (§14.8.5.7),
+ * PrintField (§14.8.5.6), Artifact (§14.8.2.2), UserProperties
+ * (§14.8.5.10).
+ *
+ * Attribute classes appear as dicts with an `/O` (Owner) name. We
+ * dispatch by `/O` and apply a typed reader that returns plain JS
+ * values for the well-defined keys, preserving unknowns in `_extras`.
+ *
+ * @module pdf/extra/tagged-pdf-typed
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParserObj } from '../syntax/parser-obj.js';
+
+export const pdfTaggedPdfTyped = {
+    name: 'pdfTaggedPdfTyped',
+    dependencies: ['pdfErrors', 'pdfParserObj'],
+    deps: [pdfErrors, pdfParserObj],
+    factory(errors, parserObj) {
+        const { ParseError } = errors;
+        const { isType } = parserObj;
+
+        const OWNERS = new Set([
+            'Layout', 'List', 'Table', 'PrintField', 'Artifact', 'UserProperties'
+        ]);
+
+        const KNOWN_BY_OWNER = {
+            Layout: new Set(['O', 'Placement', 'WritingMode', 'BackgroundColor',
+                'BorderColor', 'BorderStyle', 'BorderThickness', 'Color',
+                'Padding', 'SpaceBefore', 'SpaceAfter', 'StartIndent', 'EndIndent',
+                'TextIndent', 'TextAlign', 'BBox', 'Width', 'Height', 'BlockAlign',
+                'InlineAlign', 'TBorderStyle', 'TPadding', 'LineHeight',
+                'BaselineShift', 'TextPosition', 'TextDecorationType',
+                'TextDecorationColor', 'TextDecorationThickness',
+                'RubyAlign', 'RubyPosition', 'GlyphOrientationVertical',
+                'ColumnCount', 'ColumnGap', 'ColumnWidths']),
+            List: new Set(['O', 'ListNumbering', 'ContinuedList', 'ContinuedFrom']),
+            Table: new Set(['O', 'RowSpan', 'ColSpan', 'Headers', 'Scope', 'Summary']),
+            PrintField: new Set(['O', 'Role', 'checked', 'Desc']),
+            Artifact: new Set(['O', 'Type', 'BBox', 'Attached', 'Subtype']),
+            UserProperties: new Set(['O', 'P'])
+        };
+
+        function knownFor(owner) {
+            return KNOWN_BY_OWNER[owner] || new Set(['O']);
+        }
+
+        function typeStructAttribute(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/extra/tagged/not-dict',
+                    'attribute class must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (!isType(e.O, 'name')) {
+                throw new ParseError('pdf/extra/tagged/missing-owner',
+                    'attribute class missing /O owner name',
+                    { context: { type: e.O && e.O.type } });
+            }
+            const owner = e.O.value;
+            let typed;
+            switch (owner) {
+                case 'Layout':         typed = readLayout(e); break;
+                case 'List':           typed = readList(e); break;
+                case 'Table':          typed = readTable(e); break;
+                case 'PrintField':     typed = readPrintField(e); break;
+                case 'Artifact':       typed = readArtifact(e); break;
+                case 'UserProperties': typed = readUserProperties(e); break;
+                default:
+                    typed = { owner, vendor: true };
+            }
+            typed.owner = owner;
+            typed.raw = dict;
+            typed._extras = collectExtras(e, knownFor(owner));
+            return typed;
+        }
+
+        function readLayout(e) {
+            return {
+                placement:               nameVal(e.Placement),
+                writingMode:             nameVal(e.WritingMode),
+                backgroundColor:         numArr(e.BackgroundColor),
+                borderColor:             e.BorderColor || null,
+                borderStyle:             e.BorderStyle || null,
+                borderThickness:         e.BorderThickness || null,
+                color:                   numArr(e.Color),
+                padding:                 e.Padding || null,
+                spaceBefore:             numVal(e.SpaceBefore, null),
+                spaceAfter:              numVal(e.SpaceAfter, null),
+                startIndent:             numVal(e.StartIndent, null),
+                endIndent:               numVal(e.EndIndent, null),
+                textIndent:              numVal(e.TextIndent, null),
+                textAlign:               nameVal(e.TextAlign),
+                bbox:                    numArr(e.BBox),
+                width:                   numVal(e.Width, null),
+                height:                  numVal(e.Height, null),
+                blockAlign:              nameVal(e.BlockAlign),
+                inlineAlign:             nameVal(e.InlineAlign),
+                lineHeight:              numVal(e.LineHeight, null),
+                baselineShift:           numVal(e.BaselineShift, null),
+                textPosition:            nameVal(e.TextPosition),
+                textDecorationType:      nameVal(e.TextDecorationType),
+                textDecorationColor:     numArr(e.TextDecorationColor),
+                textDecorationThickness: numVal(e.TextDecorationThickness, null),
+                columnCount:             numVal(e.ColumnCount, null),
+                columnGap:               e.ColumnGap || null,
+                columnWidths:            e.ColumnWidths || null
+            };
+        }
+
+        function readList(e) {
+            return {
+                listNumbering:  nameVal(e.ListNumbering),
+                continuedList:  isType(e.ContinuedList, 'bool') ? e.ContinuedList.value : null,
+                continuedFrom:  e.ContinuedFrom || null
+            };
+        }
+
+        function readTable(e) {
+            return {
+                rowSpan:    numVal(e.RowSpan, null),
+                colSpan:    numVal(e.ColSpan, null),
+                headers:    e.Headers || null,
+                scope:      nameVal(e.Scope),
+                summary:    isType(e.Summary, 'string') ? e.Summary.value : null
+            };
+        }
+
+        function readPrintField(e) {
+            return {
+                role:    nameVal(e.Role),
+                checked: nameVal(e.checked) || nameVal(e.Checked),
+                desc:    isType(e.Desc, 'string') ? e.Desc.value : null
+            };
+        }
+
+        function readArtifact(e) {
+            return {
+                artifactType:    nameVal(e.Type),
+                bbox:            numArr(e.BBox),
+                attached:        e.Attached || null,
+                artifactSubtype: nameVal(e.Subtype)
+            };
+        }
+
+        function readUserProperties(e) {
+            const out = { properties: [] };
+            if (isType(e.P, 'array')) {
+                for (const it of e.P.items) {
+                    if (!isType(it, 'dict')) {
+                        throw new ParseError('pdf/extra/tagged/bad-user-property',
+                            '/P items must be dicts');
+                    }
+                    const pe = it.entries;
+                    out.properties.push({
+                        name:    isType(pe.N, 'string') ? pe.N.value : null,
+                        value:   pe.V || null,
+                        formatted: isType(pe.F, 'string') ? pe.F.value : null,
+                        hidden:  isType(pe.H, 'bool') ? pe.H.value : false
+                    });
+                }
+            }
+            return out;
+        }
+
+        function nameVal(v) { return isType(v, 'name') ? v.value : null; }
+        function numVal(v, dflt) {
+            if (!v) return dflt;
+            return (v.type === 'int' || v.type === 'real') ? v.value : dflt;
+        }
+        function numArr(v) {
+            if (!isType(v, 'array')) return null;
+            const out = [];
+            for (const it of v.items) {
+                if (!it || (it.type !== 'int' && it.type !== 'real')) return null;
+                out.push(it.value);
+            }
+            return out;
+        }
+
+        function collectExtras(entries, known) {
+            const out = {};
+            for (const k of Object.keys(entries)) {
+                if (!known.has(k)) out[k] = entries[k];
+            }
+            return out;
+        }
+
+        return { typeStructAttribute, ATTRIBUTE_OWNERS: OWNERS };
+    }
+};
+