@awacloud/pdf 0.0.0-stage → 1.0.0

package/src/extra/form-actions-extended.js

@@ -0,0 +1,196 @@
+// 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: extended action subtypes per
+ * ISO 32000-2:2020 §12.6.4 — GoTo3DView (§12.6.4.15),
+ * SetOCGState (§12.6.4.12), Trans (§12.6.4.13), Rendition (§12.6.4.14),
+ * Hide (§12.6.4.10), SubmitForm (§12.6.4.4), ResetForm (§12.6.4.5),
+ * ImportData (§12.6.4.6), JavaScript (§12.6.4.7, sandboxed flag only).
+ *
+ * Each typer returns a typed record ; unknowns are preserved in
+ * `_extras`. The orchestrator returns `{ kind, ...typed, raw, _extras }`.
+ *
+ * @module pdf/extra/form-actions-extended
+ */
+
+/**
+ * Module factory.
+ */
+import { pdfErrors } from '../errors.js';
+import { pdfParserObj } from '../syntax/parser-obj.js';
+
+export const pdfFormActionsExtended = {
+    name: 'pdfFormActionsExtended',
+    dependencies: ['pdfErrors', 'pdfParserObj'],
+    deps: [pdfErrors, pdfParserObj],
+    factory(errors, parserObj) {
+        const { ParseError } = errors;
+        const { isType } = parserObj;
+
+        const EXTENDED_ACTION_SUBTYPES = new Set([
+            'GoTo3DView', 'SetOCGState', 'Trans', 'Rendition', 'Hide',
+            'SubmitForm', 'ResetForm', 'ImportData', 'JavaScript'
+        ]);
+
+        const KNOWN = {
+            GoTo3DView:  new Set(['Type', 'S', 'Next', 'TA', 'V']),
+            SetOCGState: new Set(['Type', 'S', 'Next', 'State', 'PreserveRB']),
+            Trans:       new Set(['Type', 'S', 'Next', 'Trans']),
+            Rendition:   new Set(['Type', 'S', 'Next', 'R', 'AN', 'OP', 'JS']),
+            Hide:        new Set(['Type', 'S', 'Next', 'T', 'H']),
+            SubmitForm:  new Set(['Type', 'S', 'Next', 'F', 'Fields', 'Flags', 'CharSet']),
+            ResetForm:   new Set(['Type', 'S', 'Next', 'Fields', 'Flags']),
+            ImportData:  new Set(['Type', 'S', 'Next', 'F']),
+            JavaScript:  new Set(['Type', 'S', 'Next', 'JS'])
+        };
+
+        function knownFor(s) { return KNOWN[s] || new Set(['Type', 'S', 'Next']); }
+
+        function typeExtendedAction(dict) {
+            if (!isType(dict, 'dict')) {
+                throw new ParseError('pdf/extra/action-ext/not-dict',
+                    'action must be a dictionary',
+                    { context: { type: dict && dict.type } });
+            }
+            const e = dict.entries;
+            if (e.Type && (e.Type.type !== 'name' || e.Type.value !== 'Action')) {
+                throw new ParseError('pdf/extra/action-ext/bad-type',
+                    '/Type entry must be /Action',
+                    { context: { actual: e.Type.value } });
+            }
+            if (!isType(e.S, 'name') || !EXTENDED_ACTION_SUBTYPES.has(e.S.value)) {
+                throw new ParseError('pdf/extra/action-ext/unsupported',
+                    'unsupported extended action subtype',
+                    { context: { subtype: e.S && e.S.value } });
+            }
+            let rec;
+            switch (e.S.value) {
+                case 'GoTo3DView':  rec = readGoTo3DView(e); break;
+                case 'SetOCGState': rec = readSetOCGState(e); break;
+                case 'Trans':       rec = readTrans(e); break;
+                case 'Rendition':   rec = readRendition(e); break;
+                case 'Hide':        rec = readHide(e); break;
+                case 'SubmitForm':  rec = readSubmitForm(e); break;
+                case 'ResetForm':   rec = readResetForm(e); break;
+                case 'ImportData':  rec = readImportData(e); break;
+                case 'JavaScript':  rec = readJavaScript(e); break;
+            }
+            rec.kind = e.S.value;
+            rec.raw = dict;
+            rec._extras = collectExtras(e, knownFor(e.S.value));
+            return rec;
+        }
+
+        function readGoTo3DView(e) {
+            return { ta: e.TA || null, v:  e.V  || null };
+        }
+
+        function readSetOCGState(e) {
+            if (!isType(e.State, 'array')) {
+                throw new ParseError('pdf/extra/action-ext/bad-state',
+                    '/State must be an array',
+                    { context: { type: e.State && e.State.type } });
+            }
+            return {
+                state:      e.State.items,
+                preserveRB: isType(e.PreserveRB, 'bool') ? e.PreserveRB.value : true
+            };
+        }
+
+        function readTrans(e) {
+            if (!isType(e.Trans, 'dict')) {
+                throw new ParseError('pdf/extra/action-ext/bad-trans',
+                    '/Trans must be a dict',
+                    { context: { type: e.Trans && e.Trans.type } });
+            }
+            return { trans: e.Trans };
+        }
+
+        function readRendition(e) {
+            const op = (e.OP && (e.OP.type === 'int' || e.OP.type === 'real'))
+                ? (e.OP.value | 0) : null;
+            const hasJs = isType(e.JS, 'string') || isType(e.JS, 'stream');
+            return {
+                r:  e.R  || null,
+                an: e.AN || null,
+                op,
+                js: isType(e.JS, 'string') ? e.JS.value : (isType(e.JS, 'stream') ? e.JS : null),
+                sandboxed: hasJs ? true : undefined
+            };
+        }
+
+        function readHide(e) {
+            if (!e.T) {
+                throw new ParseError('pdf/extra/action-ext/missing-t',
+                    'Hide action requires /T');
+            }
+            let targets;
+            if (isType(e.T, 'string') || e.T.type === 'ref') targets = [e.T];
+            else if (isType(e.T, 'array')) targets = e.T.items;
+            else {
+                throw new ParseError('pdf/extra/action-ext/bad-t',
+                    '/T must be string, ref, or array',
+                    { context: { type: e.T.type } });
+            }
+            return { targets, h: isType(e.H, 'bool') ? e.H.value : true };
+        }
+
+        function readSubmitForm(e) {
+            if (!e.F) {
+                throw new ParseError('pdf/extra/action-ext/missing-f',
+                    'SubmitForm requires /F (URL)');
+            }
+            return {
+                url:     e.F,
+                fields:  isType(e.Fields, 'array') ? e.Fields.items : null,
+                flags:   (e.Flags && (e.Flags.type === 'int' || e.Flags.type === 'real'))
+                            ? (e.Flags.value | 0) : 0,
+                charSet: isType(e.CharSet, 'string') ? e.CharSet.value : null,
+                sandboxed: true
+            };
+        }
+
+        function readResetForm(e) {
+            return {
+                fields: isType(e.Fields, 'array') ? e.Fields.items : null,
+                flags:  (e.Flags && (e.Flags.type === 'int' || e.Flags.type === 'real'))
+                            ? (e.Flags.value | 0) : 0
+            };
+        }
+
+        function readImportData(e) {
+            if (!e.F) {
+                throw new ParseError('pdf/extra/action-ext/missing-f',
+                    'ImportData requires /F (file spec)');
+            }
+            return { file: e.F, sandboxed: true };
+        }
+
+        function readJavaScript(e) {
+            if (!e.JS) {
+                throw new ParseError('pdf/extra/action-ext/missing-js',
+                    'JavaScript action requires /JS');
+            }
+            if (!isType(e.JS, 'string') && !isType(e.JS, 'stream')) {
+                throw new ParseError('pdf/extra/action-ext/bad-js',
+                    '/JS must be string or stream',
+                    { context: { type: e.JS.type } });
+            }
+            return { js: e.JS, sandboxed: true };
+        }
+
+        function collectExtras(entries, known) {
+            const out = {};
+            for (const k of Object.keys(entries)) {
+                if (!known.has(k)) out[k] = entries[k];
+            }
+            return out;
+        }
+
+        return { typeExtendedAction, EXTENDED_ACTION_SUBTYPES };
+    }
+};
+

package/src/extra/info-dict-deprecated.js

@@ -0,0 +1,137 @@
+// 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: /Info dict deprecation lint.
+ *
+ * PDF 2.0 (ISO 32000-2:2020 §14.3.3) deprecates the Document
+ * Information Dictionary in favour of XMP metadata streams. This module
+ * inspects a Catalog + /Info pair and emits structured warnings when
+ * /Info is present on a PDF 2.0 document, including a suggested XMP
+ * mapping per the standard's recommended namespaces.
+ *
+ * @module pdf/extra/info-dict-deprecated
+ */
+
+import { pdfErrors } from '../errors.js';
+
+export const pdfInfoDictDeprecated = {
+    name: 'pdfInfoDictDeprecated',
+    dependencies: ['pdfErrors'],
+    deps: [pdfErrors],
+
+    factory(errors) {
+        const { ParseError } = errors;
+        const INFO_TO_XMP = {
+            Title:        { ns: 'dc',  field: 'title'       },
+            Author:       { ns: 'dc',  field: 'creator'     },
+            Subject:      { ns: 'dc',  field: 'description' },
+            Keywords:     { ns: 'pdf', field: 'Keywords'    },
+            Creator:      { ns: 'xmp', field: 'CreatorTool' },
+            Producer:     { ns: 'pdf', field: 'Producer'    },
+            CreationDate: { ns: 'xmp', field: 'CreateDate'  },
+            ModDate:      { ns: 'xmp', field: 'ModifyDate'  },
+            Trapped:      { ns: 'pdf', field: 'Trapped'     }
+        };
+
+        function isDict(v) { return v && v.type === 'dict'; }
+
+        function parsePdfVersion(v) {
+            if (typeof v === 'string') return v;
+            if (v && v.type === 'name') return v.value;
+            if (v && v.type === 'string') {
+                const b = v.value;
+                if (b instanceof Uint8Array) return new TextDecoder('latin1').decode(b);
+                return String(b);
+            }
+            if (typeof v === 'number') return String(v);
+            throw new ParseError('pdf/info-deprecated/bad-version',
+                'PDF version must be string or PDF name',
+                { context: { type: v && v.type } });
+        }
+
+        function isVersion2OrHigher(versionStr) {
+            const m = /^(\d+)\.(\d+)/.exec(versionStr || '');
+            if (!m) return false;
+            const major = parseInt(m[1], 10);
+            return major >= 2;
+        }
+
+        function suggestionsFor(infoDict) {
+            if (!isDict(infoDict)) return [];
+            const out = [];
+            for (const k of Object.keys(infoDict.entries)) {
+                const map = INFO_TO_XMP[k];
+                if (map) {
+                    out.push({
+                        infoKey: k,
+                        xmpNamespace: map.ns,
+                        xmpField: map.field
+                    });
+                } else {
+                    out.push({
+                        infoKey: k,
+                        xmpNamespace: null,
+                        xmpField: null,
+                        note: 'no standard XMP equivalent'
+                    });
+                }
+            }
+            return out;
+        }
+
+        function lint(opts) {
+            opts = opts || {};
+            const version = parsePdfVersion(opts.version);
+            const info = opts.info;
+            const xmpPresent = !!opts.xmpPresent;
+            const warnings = [];
+
+            if (info != null) {
+                if (!isDict(info)) {
+                    throw new ParseError('pdf/info-deprecated/bad-info',
+                        '/Info must be a dict',
+                        { context: { type: info && info.type } });
+                }
+            }
+
+            const v2 = isVersion2OrHigher(version);
+            if (v2 && info) {
+                warnings.push({
+                    code: 'pdf/info-deprecated',
+                    severity: 'warn',
+                    message: '/Info is deprecated in PDF 2.0 — use the XMP metadata stream instead',
+                    suggestions: suggestionsFor(info)
+                });
+            }
+            if (v2 && info && !xmpPresent) {
+                warnings.push({
+                    code: 'pdf/info-without-xmp',
+                    severity: 'warn',
+                    message: 'PDF 2.0 document carries /Info but no XMP /Metadata stream'
+                });
+            }
+            return {
+                version,
+                isPdf2: v2,
+                hasInfo: info != null,
+                xmpPresent,
+                warnings
+            };
+        }
+
+        function mapInfoKey(name) {
+            return INFO_TO_XMP[name] || null;
+        }
+
+        return {
+            lint,
+            mapInfoKey,
+            suggestionsFor,
+            INFO_TO_XMP,
+            isVersion2OrHigher
+        };
+    }
+};

package/src/extra/jbig2-read.js

@@ -0,0 +1,169 @@
+// 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: JBIG2Decode partial reader.
+ *
+ * JBIG2 is the bilevel image codec referenced by /Filter /JBIG2Decode
+ * (ISO 32000-2:2020 §7.4.7). A full decoder is out of scope; this
+ * module parses the segment header chain (ISO/IEC 14492:2001 §7.2) and
+ * returns descriptors so callers can at least enumerate the embedded
+ * data without pulling in a heavyweight decoder.
+ *
+ * Status: PARTIAL — header-only.
+ *
+ * @module pdf/extra/jbig2-read
+ */
+
+import { pdfErrors } from '../errors.js';
+
+export const pdfJbig2Read = {
+    name: 'pdfJbig2Read',
+    dependencies: ['pdfErrors'],
+    deps: [pdfErrors],
+
+    factory(errors) {
+        const { ParseError } = errors;
+        const SEGMENT_TYPES = {
+            0:  'symbolDictionary',
+            4:  'intermediateTextRegion',
+            6:  'immediateTextRegion',
+            7:  'immediateLosslessTextRegion',
+            16: 'patternDictionary',
+            20: 'intermediateHalftoneRegion',
+            22: 'immediateHalftoneRegion',
+            23: 'immediateLosslessHalftoneRegion',
+            36: 'intermediateGenericRegion',
+            38: 'immediateGenericRegion',
+            39: 'immediateLosslessGenericRegion',
+            40: 'intermediateGenericRefinementRegion',
+            42: 'immediateGenericRefinementRegion',
+            43: 'immediateLosslessGenericRefinementRegion',
+            48: 'pageInformation',
+            49: 'endOfPage',
+            50: 'endOfStripe',
+            51: 'endOfFile',
+            52: 'profiles',
+            53: 'tables',
+            62: 'extension'
+        };
+
+        function readUint32BE(b, o) {
+            return (b[o] * 0x1000000) + ((b[o + 1] << 16) | (b[o + 2] << 8) | b[o + 3]);
+        }
+
+        function readReferredSegmentCount(b, o) {
+            // First byte's top 3 bits = count; if = 7 => long form (next 3 bytes hold (count<<5)|reserved).
+            const head = b[o];
+            const small = head >>> 5;
+            if (small !== 7) {
+                return { count: small, fieldBytes: 1 };
+            }
+            // Long form: 4 bytes total, count uses 29 high bits of next 32-bit value.
+            const longVal = readUint32BE(b, o) & 0x1FFFFFFF;
+            return { count: longVal, fieldBytes: 4 };
+        }
+
+        function refSegSize(count) {
+            // Each retention flag bit + alignment to byte, plus references.
+            // We don't need the retention flag bytes' contents; just to skip.
+            return Math.ceil((count + 1) / 8);
+        }
+
+        function refNumberSize(maxSegNum) {
+            if (maxSegNum <= 0xFF)      return 1;
+            if (maxSegNum <= 0xFFFF)    return 2;
+            return 4;
+        }
+
+        function parseSegments(bytes) {
+            if (!(bytes instanceof Uint8Array)) {
+                throw new ParseError('pdf/jbig2/bad-input',
+                    'JBIG2Decode expects Uint8Array');
+            }
+            const out = [];
+            let o = 0;
+            let lastSegNum = 0;
+            while (o + 11 <= bytes.length) {
+                const start = o;
+                const segNum = readUint32BE(bytes, o); o += 4;
+                const flags = bytes[o++];
+                const type = flags & 0x3F;
+                const retainBit = (flags >> 6) & 1;
+                const deferredNonRetainBit = (flags >> 7) & 1;
+
+                const ref = readReferredSegmentCount(bytes, o);
+                o += ref.fieldBytes;
+                // Skip retention flag bytes (count+1 bits rounded up).
+                o += refSegSize(ref.count);
+                // Skip referred segment numbers.
+                const rns = refNumberSize(Math.max(segNum, lastSegNum));
+                o += ref.count * rns;
+                if (o + 4 > bytes.length) {
+                    throw new ParseError('pdf/jbig2/truncated-header',
+                        'JBIG2 segment header truncated',
+                        { context: { segNum, offset: start } });
+                }
+                // Page association — 1 or 4 bytes; we assume 1-byte mode
+                // unless the page-association-size flag in the header
+                // suggests 4 (we have no header — JBIG2 sequential
+                // streams in PDF are headerless, defaulting to 1).
+                o += 1;
+                if (o + 4 > bytes.length) {
+                    throw new ParseError('pdf/jbig2/truncated-data-length',
+                        'JBIG2 segment data length truncated',
+                        { context: { segNum, offset: start } });
+                }
+                const dataLength = readUint32BE(bytes, o); o += 4;
+                const dataStart = o;
+                if (dataLength !== 0xFFFFFFFF) {
+                    if (dataStart + dataLength > bytes.length) {
+                        throw new ParseError('pdf/jbig2/truncated-data',
+                            'JBIG2 segment data truncated',
+                            { context: { segNum, dataLength } });
+                    }
+                    o = dataStart + dataLength;
+                } else {
+                    // Unknown length — caller must scan for EOF.
+                    // We bail and surface the partial descriptor.
+                    o = bytes.length;
+                }
+                out.push({
+                    segmentNumber: segNum,
+                    type,
+                    typeName: SEGMENT_TYPES[type] || 'unknown',
+                    referredCount: ref.count,
+                    retain: !!retainBit,
+                    deferredNonRetain: !!deferredNonRetainBit,
+                    dataOffset: dataStart,
+                    dataLength: dataLength === 0xFFFFFFFF ? null : dataLength,
+                    unknownLength: dataLength === 0xFFFFFFFF
+                });
+                lastSegNum = Math.max(lastSegNum, segNum);
+                if (type === 51) break; // endOfFile
+            }
+            return out;
+        }
+
+        function enumerateGenericRegions(bytes) {
+            const segs = parseSegments(bytes);
+            return segs.filter(s => s.type === 36 || s.type === 38 || s.type === 39);
+        }
+
+        function decode(_bytes) {
+            throw new ParseError('pdf/jbig2/not-implemented',
+                'JBIG2Decode full decode not implemented — header-only',
+                { context: { status: 'partial' } });
+        }
+
+        return {
+            parseSegments,
+            enumerateGenericRegions,
+            decode,
+            SEGMENT_TYPES,
+            STATUS: 'partial — header-only'
+        };
+    }
+};