@awacloud/pdf 0.0.0-stage → 1.0.0

package/src/prepress/outputIntent.js

@@ -0,0 +1,118 @@
+// 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 Output Intent typing per ISO 32000-2:2020 §14.11.5.
+ *
+ * Each entry in the Catalog's `/OutputIntents` array is a dictionary
+ * `/Type /OutputIntent` describing the colour environment the document
+ * was prepared for. Entries:
+ *   /S                       — subtype: GTS_PDFA1, GTS_PDFX, ISO_PDFE1, …
+ *   /OutputCondition         — human-readable description.
+ *   /OutputConditionIdentifier — registry identifier.
+ *   /RegistryName            — URL of registry.
+ *   /Info                    — additional textual info.
+ *   /DestOutputProfile       — ICC profile stream (ref).
+ *   /DestOutputProfileRef    — PDF 2.0 indirect URI to ICC.
+ *   /MixingHints             — dict (mixing hints).
+ *   /SpectralData            — dict (spectral data).
+ *
+ * @module pdf/prepress/outputIntent
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfOutputIntent = {
+    name: 'pdfOutputIntent',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, parser) {
+        const { ParseError } = errors;
+        const { isType } = parser;
+
+        const KNOWN = new Set([
+            'Type', 'S', 'OutputCondition', 'OutputConditionIdentifier',
+            'RegistryName', 'Info', 'DestOutputProfile', 'DestOutputProfileRef',
+            'MixingHints', 'SpectralData'
+        ]);
+
+        function lower(s) { return s.charAt(0).toLowerCase() + s.slice(1); }
+
+        function typeOutputIntent(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/output-intent/not-dict',
+                    'OutputIntent must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (e.Type && (e.Type.type !== 'name' || e.Type.value !== 'OutputIntent')) {
+                throw new ParseError('pdf/output-intent/bad-type',
+                    '/Type must be /OutputIntent',
+                    { context: { actual: e.Type.value } });
+            }
+            if (!e.S || e.S.type !== 'name') {
+                throw new ParseError('pdf/output-intent/missing-s',
+                    'OutputIntent missing /S subtype name',
+                    { context: { type: e.S && e.S.type } });
+            }
+            const out = { subtype: e.S.value, raw: dict, _extras: {} };
+
+            for (const k of ['OutputCondition', 'OutputConditionIdentifier',
+                             'RegistryName', 'Info']) {
+                if (e[k] !== undefined) {
+                    if (e[k].type !== 'string') {
+                        throw new ParseError('pdf/output-intent/bad-str',
+                            '/' + k + ' must be a string',
+                            { context: { key: k, type: e[k].type } });
+                    }
+                    out[lower(k)] = e[k].value;
+                }
+            }
+            if (e.DestOutputProfile) {
+                if (e.DestOutputProfile.type !== 'ref' && e.DestOutputProfile.type !== 'stream') {
+                    throw new ParseError('pdf/output-intent/bad-profile',
+                        '/DestOutputProfile must be a ref or stream',
+                        { context: { type: e.DestOutputProfile.type } });
+                }
+                out.destOutputProfile = e.DestOutputProfile;
+            }
+            if (e.DestOutputProfileRef) {
+                if (e.DestOutputProfileRef.type !== 'dict' && e.DestOutputProfileRef.type !== 'ref') {
+                    throw new ParseError('pdf/output-intent/bad-profile-ref',
+                        '/DestOutputProfileRef must be a dict or ref',
+                        { context: { type: e.DestOutputProfileRef.type } });
+                }
+                out.destOutputProfileRef = e.DestOutputProfileRef;
+            }
+            if (e.MixingHints) {
+                if (e.MixingHints.type !== 'dict') {
+                    throw new ParseError('pdf/output-intent/bad-mixing',
+                        '/MixingHints must be a dictionary',
+                        { context: { type: e.MixingHints.type } });
+                }
+                out.mixingHints = e.MixingHints;
+            }
+            if (e.SpectralData) {
+                if (e.SpectralData.type !== 'dict') {
+                    throw new ParseError('pdf/output-intent/bad-spectral',
+                        '/SpectralData must be a dictionary',
+                        { context: { type: e.SpectralData.type } });
+                }
+                out.spectralData = e.SpectralData;
+            }
+
+            for (const k of Object.keys(e)) {
+                if (!KNOWN.has(k)) out._extras[k] = e[k];
+            }
+            return out;
+        }
+
+        return { typeOutputIntent };
+    }
+};

package/src/prepress/pageBoundary.js

@@ -0,0 +1,108 @@
+// 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 Page boundary helpers per ISO 32000-2:2020 §14.11.2.
+ *
+ * Each Page may declare four optional boundary rectangles —
+ * `/CropBox`, `/TrimBox`, `/BleedBox`, `/ArtBox` — each defaulting to
+ * `/MediaBox` (which is mandatory on every page) when absent. These
+ * helpers resolve the effective rectangle following the spec's
+ * inheritance rules:
+ *   - MediaBox itself is inheritable from ancestor /Pages nodes (already
+ *     handled at L2 by the page-typing layer; we expect callers to pass
+ *     a Page record carrying its effective `/MediaBox`).
+ *   - CropBox defaults to MediaBox; Trim/Bleed/ArtBox default to
+ *     CropBox.
+ *
+ * The input is the *typed* page record returned by the page typer,
+ * carrying `{ mediaBox, cropBox?, trimBox?, bleedBox?, artBox? }` —
+ * each a `[llx, lly, urx, ury]` array of numbers. To stay loosely
+ * coupled we also accept raw dict-shape objects with `entries.MediaBox`
+ * etc.
+ *
+ * @module pdf/prepress/pageBoundary
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParser } from '../syntax/parser.js';
+
+export const pdfPageBoundary = {
+    name: 'pdfPageBoundary',
+    dependencies: ['pdfErrors', 'pdfParser'],
+    deps: [pdfErrors, pdfParser],
+    factory(errors, _p) {
+        const { ParseError } = errors;
+
+        const KEYS = {
+            mediaBox: 'MediaBox',
+            cropBox:  'CropBox',
+            trimBox:  'TrimBox',
+            bleedBox: 'BleedBox',
+            artBox:   'ArtBox'
+        };
+
+        function readBox(page, normKey) {
+            if (!page) return undefined;
+            if (page[normKey] !== undefined) return page[normKey];
+            // Raw dict shape.
+            const k = KEYS[normKey];
+            const dict = page.entries ? page : page.raw;
+            if (dict && dict.entries && dict.entries[k]) {
+                const arr = dict.entries[k];
+                if (arr.type !== 'array' || arr.items.length !== 4) {
+                    throw new ParseError('pdf/page-boundary/bad-box',
+                        '/' + k + ' must be a 4-element array',
+                        { context: { key: k } });
+                }
+                return arr.items.map((x) => {
+                    if (x.type !== 'int' && x.type !== 'real') {
+                        throw new ParseError('pdf/page-boundary/bad-box-element',
+                            '/' + k + ' elements must be numbers',
+                            { context: { key: k, type: x.type } });
+                    }
+                    return x.value;
+                });
+            }
+            return undefined;
+        }
+
+        function effectiveMediaBox(page) {
+            const v = readBox(page, 'mediaBox');
+            if (!v) {
+                throw new ParseError('pdf/page-boundary/no-mediabox',
+                    'page has no /MediaBox');
+            }
+            return v;
+        }
+
+        function effectiveCropBox(page) {
+            return readBox(page, 'cropBox') || effectiveMediaBox(page);
+        }
+
+        function effectiveTrimBox(page) {
+            return readBox(page, 'trimBox') || effectiveCropBox(page);
+        }
+
+        function effectiveBleedBox(page) {
+            return readBox(page, 'bleedBox') || effectiveCropBox(page);
+        }
+
+        function effectiveArtBox(page) {
+            return readBox(page, 'artBox') || effectiveCropBox(page);
+        }
+
+        return {
+            effectiveMediaBox,
+            effectiveCropBox,
+            effectiveTrimBox,
+            effectiveBleedBox,
+            effectiveArtBox
+        };
+    }
+};

package/src/sig/byteRange.js

@@ -0,0 +1,306 @@
+// 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 ByteRange computation around a signature's `/Contents`
+ * hex string.
+ *
+ * ISO 32000-2:2020 §12.8.1 — a signature dictionary's `/ByteRange` is
+ * an array `[a b c d]` of four integers selecting the two byte ranges
+ * `[a, a+b)` and `[c, c+d)` of the document. The gap `[a+b, c)` between
+ * them holds the `/Contents` value, the PKCS#7 / CMS blob; its bytes are
+ * excluded from the signature digest — otherwise the digest would have
+ * to depend on its own value.
+ *
+ * Gap forms. ISO 32000-2 §12.8.3.3.1 requires the `/Contents`
+ * hex string, "with "<" and ">" delimiters", to "fit precisely in the
+ * space between the ranges": the gap is the whole `<…>` token — form
+ * (b), `gapForm: 'token'`, what `pdfSign` emits and what PDFBox and
+ * pyHanko emit and check. Signatures earlier `pdfSign` releases
+ * produced left out the hex digits only — form (a), `gapForm: 'digits'`.
+ * `auditByteRange` accepts exactly these two gaps.
+ *
+ * @module pdf/sig/byteRange
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+
+export const pdfByteRange = {
+    name: 'pdfByteRange',
+    dependencies: ['pdfErrors'],
+    deps: [pdfErrors],
+    factory(errors) {
+        const { ParseError } = errors;
+
+        const CONTENTS_KEY = new Uint8Array([
+            0x2F, 0x43, 0x6F, 0x6E, 0x74, 0x65, 0x6E, 0x74, 0x73   // /Contents
+        ]);
+        const ENDOBJ = new Uint8Array([0x65, 0x6E, 0x64, 0x6F, 0x62, 0x6A]);
+
+        function _indexOfBytes(haystack, needle, from, to) {
+            const n = needle.length;
+            const limit = to - n;
+            outer: for (let i = from; i <= limit; i++) {
+                for (let k = 0; k < n; k++) {
+                    if (haystack[i + k] !== needle[k]) continue outer;
+                }
+                return i;
+            }
+            return -1;
+        }
+
+        function _findEndobj(bytes, from) {
+            const at = _indexOfBytes(bytes, ENDOBJ, from, bytes.length);
+            return at < 0 ? bytes.length : at;
+        }
+
+        function _isWhitespace(b) {
+            return b === 0x00 || b === 0x09 || b === 0x0A || b === 0x0C
+                || b === 0x0D || b === 0x20;
+        }
+
+        /**
+         * `[0, gapStart, gapEnd, total - gapEnd]` around a `/Contents` value.
+         *
+         * Without `opts` the gap is `[contentsOffset, contentsOffset +
+         * contentsLength)` — whatever span the caller passes (historically
+         * the hex digits, form a). With `opts.token` the gap is that token
+         * span instead (form b): it must enclose the digit span by exactly
+         * one byte on each side, and those two bytes must be `<` and `>`.
+         *
+         * @throws {ParseError} `pdf/sig/byterange/bad-input`, `bad-offset`,
+         *   `bad-length`, `overflow`; `bad-token` when `opts.token` is not
+         *   the `<…>` token around the digit span.
+         */
+        function computeByteRange(documentBytes, contentsOffset, contentsLength, opts) {
+            if (!(documentBytes instanceof Uint8Array)) {
+                throw new ParseError('pdf/sig/byterange/bad-input',
+                    'documentBytes must be a Uint8Array');
+            }
+            const total = documentBytes.length;
+            if (!Number.isInteger(contentsOffset) || contentsOffset < 0
+                || contentsOffset > total) {
+                throw new ParseError('pdf/sig/byterange/bad-offset',
+                    'contentsOffset out of range',
+                    { context: { contentsOffset, total } });
+            }
+            if (!Number.isInteger(contentsLength) || contentsLength < 0) {
+                throw new ParseError('pdf/sig/byterange/bad-length',
+                    'contentsLength must be a non-negative integer',
+                    { context: { contentsLength } });
+            }
+            const end = contentsOffset + contentsLength;
+            if (end > total) {
+                throw new ParseError('pdf/sig/byterange/overflow',
+                    '/Contents extends past end of document',
+                    { context: { end, total } });
+            }
+            if (opts && opts.token) {
+                const tOff = opts.token.offset;
+                const tLen = opts.token.length;
+                const tEnd = tOff + tLen;
+                if (!Number.isInteger(tOff) || !Number.isInteger(tLen)
+                    || tOff !== contentsOffset - 1 || tEnd !== end + 1
+                    || tOff < 0 || tEnd > total
+                    || documentBytes[tOff] !== 0x3C             // '<'
+                    || documentBytes[tEnd - 1] !== 0x3E) {      // '>'
+                    throw new ParseError('pdf/sig/byterange/bad-token',
+                        'token span must be the "<…>" token enclosing the '
+                            + '/Contents hex digits',
+                        { context: { token: { offset: tOff, length: tLen },
+                                     contentsOffset, contentsLength } });
+                }
+                return [0, tOff, tEnd, total - tEnd];
+            }
+            return [0, contentsOffset, end, total - end];
+        }
+
+        function extractSignedBytes(documentBytes, byteRange) {
+            if (!(documentBytes instanceof Uint8Array)) {
+                throw new ParseError('pdf/sig/byterange/bad-input',
+                    'documentBytes must be a Uint8Array');
+            }
+            if (!byteRange || byteRange.length !== 4) {
+                throw new ParseError('pdf/sig/byterange/bad-shape',
+                    'byteRange must have 4 entries',
+                    { context: { length: byteRange && byteRange.length } });
+            }
+            const a = byteRange[0] | 0;
+            const b = byteRange[1] | 0;
+            const c = byteRange[2] | 0;
+            const d = byteRange[3] | 0;
+            if (a < 0 || b < 0 || c < 0 || d < 0
+                || a + b > documentBytes.length
+                || c + d > documentBytes.length
+                || c < a + b) {
+                throw new ParseError('pdf/sig/byterange/inconsistent',
+                    'byteRange entries inconsistent with documentBytes',
+                    { context: { a, b, c, d, total: documentBytes.length } });
+            }
+            const out = new Uint8Array(b + d);
+            out.set(documentBytes.subarray(a, a + b), 0);
+            out.set(documentBytes.subarray(c, c + d), b);
+            return out;
+        }
+
+        /**
+         * Non-throwing `/ByteRange` audit.
+         *
+         * With `opts.contents` (the hex-digit span `findContentsField`
+         * returns), the gap must be exactly the `<…>` token (form b) or
+         * exactly the digits (form a); any other gap yields
+         * `gap-start-mismatch` / `gap-end-mismatch`, measured against the
+         * token bounds. `gapForm` names the accepted form: `'token'`,
+         * `'digits'`, or `null` (no `opts.contents`, or neither form).
+         *
+         * @returns {{ok: boolean, issues: Array<{code: string, message: string,
+         *   context: object}>, gapForm: ('token'|'digits'|null)}}
+         * @throws {ParseError} `pdf/sig/byterange/bad-input`, `bad-shape`.
+         */
+        function auditByteRange(documentBytes, byteRange, opts) {
+            if (!(documentBytes instanceof Uint8Array)) {
+                throw new ParseError('pdf/sig/byterange/bad-input',
+                    'documentBytes must be a Uint8Array');
+            }
+            if (!byteRange || byteRange.length !== 4) {
+                throw new ParseError('pdf/sig/byterange/bad-shape',
+                    'byteRange must have 4 entries',
+                    { context: { length: byteRange && byteRange.length } });
+            }
+            const issues = [];
+            const a = byteRange[0] | 0;
+            const b = byteRange[1] | 0;
+            const c = byteRange[2] | 0;
+            const d = byteRange[3] | 0;
+            const total = documentBytes.length;
+            if (a !== 0) {
+                issues.push({
+                    code: 'pdf/sig/byterange/non-zero-start',
+                    message: 'first range does not start at offset 0',
+                    context: { a }
+                });
+            }
+            if (c < a + b) {
+                issues.push({
+                    code: 'pdf/sig/byterange/self-overlap',
+                    message: 'second range starts before first range ends',
+                    context: { firstEnd: a + b, secondStart: c }
+                });
+            }
+            if (a + b > total || c + d > total) {
+                issues.push({
+                    code: 'pdf/sig/byterange/out-of-bounds',
+                    message: 'range extends past document end',
+                    context: { firstEnd: a + b, secondEnd: c + d, total }
+                });
+            }
+            let gapForm = null;
+            if (opts && opts.contents) {
+                const cOff = opts.contents.offset | 0;
+                const cLen = opts.contents.length | 0;
+                // Form (b): the whole `<…>` token. Form (a): the digits.
+                const expectedGapStart = cOff - 1;
+                const expectedGapEnd   = cOff + cLen + 1;
+                if (a + b === expectedGapStart && c === expectedGapEnd) {
+                    gapForm = 'token';
+                } else if (a + b === cOff && c === cOff + cLen) {
+                    gapForm = 'digits';
+                }
+                // Any other gap is refused, measured against form (b).
+                if (gapForm === null && a + b !== expectedGapStart) {
+                    issues.push({
+                        code: 'pdf/sig/byterange/gap-start-mismatch',
+                        message: 'first range end does not align with /Contents '
+                            + 'literal start',
+                        context: { firstEnd: a + b, expected: expectedGapStart }
+                    });
+                }
+                if (gapForm === null && c !== expectedGapEnd) {
+                    issues.push({
+                        code: 'pdf/sig/byterange/gap-end-mismatch',
+                        message: 'second range start does not align with /Contents '
+                            + 'literal end',
+                        context: { secondStart: c, expected: expectedGapEnd }
+                    });
+                }
+            }
+            if (opts && Array.isArray(opts.others)) {
+                for (let i = 0; i < opts.others.length; i++) {
+                    const other = opts.others[i];
+                    if (!other || other.length !== 4) continue;
+                    const r1 = [[a, a + b], [c, c + d]];
+                    const oa = other[0] | 0, ob = other[1] | 0;
+                    const oc = other[2] | 0, od = other[3] | 0;
+                    const r2 = [[oa, oa + ob], [oc, oc + od]];
+                    for (const s of r1) {
+                        for (const t of r2) {
+                            if (s[0] < t[1] && t[0] < s[1]) {
+                                issues.push({
+                                    code: 'pdf/sig/byterange/cross-overlap',
+                                    message: 'byteRange overlaps with another '
+                                        + 'signature ByteRange',
+                                    context: { thisRange: s, otherRange: t,
+                                               otherIndex: i }
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+            if (opts && opts.requireFullCoverage && c + d !== total) {
+                issues.push({
+                    code: 'pdf/sig/byterange/incomplete-coverage',
+                    message: 'byteRange does not cover the document up to its end',
+                    context: { secondEnd: c + d, total }
+                });
+            }
+            return { ok: issues.length === 0, issues, gapForm };
+        }
+
+        function findContentsField(documentBytes, sigObjectOffset) {
+            if (!(documentBytes instanceof Uint8Array)) {
+                throw new ParseError('pdf/sig/byterange/bad-input',
+                    'documentBytes must be a Uint8Array');
+            }
+            if (!Number.isInteger(sigObjectOffset) || sigObjectOffset < 0
+                || sigObjectOffset >= documentBytes.length) {
+                throw new ParseError('pdf/sig/byterange/bad-offset',
+                    'sigObjectOffset out of range');
+            }
+            const stop = _findEndobj(documentBytes, sigObjectOffset);
+            const keyAt = _indexOfBytes(documentBytes, CONTENTS_KEY,
+                sigObjectOffset, stop);
+            if (keyAt < 0) {
+                throw new ParseError('pdf/sig/byterange/no-contents',
+                    '/Contents key not found in signature object',
+                    { context: { sigObjectOffset } });
+            }
+            let p = keyAt + CONTENTS_KEY.length;
+            while (p < stop && _isWhitespace(documentBytes[p])) p++;
+            if (p >= stop || documentBytes[p] !== 0x3C) { // '<'
+                throw new ParseError('pdf/sig/byterange/contents-not-hex',
+                    '/Contents must be a hex literal');
+            }
+            const start = p + 1;
+            let end = start;
+            while (end < stop && documentBytes[end] !== 0x3E) end++;  // '>'
+            if (end >= stop) {
+                throw new ParseError('pdf/sig/byterange/contents-unterminated',
+                    '/Contents hex literal not terminated before endobj');
+            }
+            return { offset: start, length: end - start };
+        }
+
+        return {
+            computeByteRange,
+            extractSignedBytes,
+            findContentsField,
+            auditByteRange
+        };
+    }
+};