@jasy/pdf 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/edit/acroform-reader.js

@@ -1,5 +1,5 @@
 import { PdfEncryptedError } from "./document.js";
-import { get, isDict, isRef, nameOf, numberOf, textOf } from "./objects.js";
+import { get, isDict, isRef, nameOf, numberOf, textStringOf } from "./objects.js";
 const FIELD_TYPES = new Set(["Tx", "Btn", "Ch", "Sig"]);
 /** Join a parent's qualified name with a child's partial name. */
 const joinName = (parent, part) => part === undefined || part === "" ? parent : parent === "" ? part : `${parent}.${part}`;
@@ -10,10 +10,10 @@ function readOptions(doc, raw) {
     return raw.map((entry) => {
         const e = doc.resolve(entry);
         if (Array.isArray(e)) {
-            const value = textOf(doc.resolve(e[0])) ?? "";
-            return { value, label: textOf(doc.resolve(e[1])) ?? value };
+            const value = textStringOf(doc.resolve(e[0])) ?? "";
+            return { value, label: textStringOf(doc.resolve(e[1])) ?? value };
         }
-        const value = textOf(e) ?? "";
+        const value = textStringOf(e) ?? "";
         return { value, label: value };
     });
 }
@@ -21,10 +21,10 @@ function readOptions(doc, raw) {
 function readValue(doc, raw) {
     const v = doc.resolve(raw);
     if (Array.isArray(v)) {
-        const values = v.map((x) => textOf(doc.resolve(x)) ?? nameOf(doc.resolve(x)) ?? "");
+        const values = v.map((x) => textStringOf(doc.resolve(x)) ?? nameOf(doc.resolve(x)) ?? "");
         return { value: values[0], values };
     }
-    const single = textOf(v) ?? nameOf(v);
+    const single = textStringOf(v) ?? nameOf(v);
     return { value: single, values: undefined };
 }
 /** The export names a button widget can show, read from the keys of its `/AP /N` state dictionary. */
@@ -72,7 +72,7 @@ function walk(doc, ref, parentName, parent, out, depth) {
     const node = doc.resolve(ref);
     if (node === undefined || !isDict(node))
         return;
-    const name = joinName(parentName, textOf(doc.lookup(node, "T")));
+    const name = joinName(parentName, textStringOf(doc.lookup(node, "T")));
     const type = nameOf(doc.lookup(node, "FT")) ?? parent.type;
     const flags = numberOf(doc.lookup(node, "Ff")) ?? parent.flags;
     const maxLen = numberOf(doc.lookup(node, "MaxLen")) ?? parent.maxLen;

package/dist/edit/appearance.js

@@ -1,5 +1,5 @@
 import { PDFObjectManager, FontStyle } from "../utils/pdf-object-manager.js";
-import { checkboxOff, checkboxOn, fieldDrawSize, listBoxFace, radioOff, radioOn, textFieldFace, wrapFieldValue, } from "../forms/appearance.js";
+import { HELV, checkboxOff, checkboxOn, fieldDrawSize, listBoxFace, radioOff, radioOn, textFieldFace, wrapFieldValue, } from "../forms/appearance.js";
 import { Color } from "../common/color.js";
 import { get, isDict, isString, numberOf } from "./objects.js";
 import { latin1FromBytes } from "../utils/bytes.js";
@@ -130,7 +130,7 @@ export function bakeAppearance(look, field, value, values, metrics) {
             ...measure(o.label),
             selected: chosen.has(o.value),
         }));
-        content = listBoxFace(look.width, look.height, look.style, rows, capHeight, size, "Helv");
+        content = listBoxFace(look.width, look.height, look.style, rows, capHeight, size, HELV);
     }
     else {
         // A choice stores an EXPORT value but shows its label - "DE" in /V, "Germany" on screen.
@@ -139,7 +139,7 @@ export function bakeAppearance(look, field, value, values, metrics) {
         const lines = shown
             ? wrapFieldValue(shown, "Helvetica", size, FontStyle.Normal, innerWidth, om, look.multiline).map(measure)
             : [];
-        content = textFieldFace(look.width, look.height, look.style, lines, capHeight, size, "Helv", look.multiline, look.align);
+        content = textFieldFace(look.width, look.height, look.style, lines, capHeight, size, HELV, look.multiline, look.align);
     }
     return { content, bbox: [0, 0, look.width, look.height] };
 }

package/dist/edit/attachments.d.ts

@@ -0,0 +1,52 @@
+import type { PdfDocument } from "./document.js";
+/**
+ * The files embedded in a PDF - every one of them, with everything the file says about it, and its
+ * exact bytes on demand.
+ *
+ * Attachments live in three places, and real files use all three: the document's `/EmbeddedFiles` name
+ * tree (a tree - large ones split into `/Kids`), the `/AF` arrays of PDF/A-3 (the catalog's, and a page's),
+ * and `FileAttachment` annotations on pages. One file spec reached from two places is ONE attachment;
+ * two different file specs with the same name are TWO - telling those apart is the caller's business,
+ * so nothing is merged by name.
+ */
+/** Thrown when an attachment's data cannot be handed back exactly as it was embedded. */
+export declare class AttachmentError extends Error {
+    constructor(message: string);
+}
+/** Where an attachment hangs: the document, or a page (0-based), through an annotation or its `/AF`. */
+export type AttachmentLocation = {
+    kind: "document";
+} | {
+    kind: "page";
+    page: number;
+};
+export interface Attachment {
+    /** The file's name: `/UF`, else `/F`, else its key in the name tree. */
+    name: string;
+    /** Its key in the `/EmbeddedFiles` name tree, when it is listed there. */
+    key?: string;
+    description?: string;
+    /** The media type the file declares (`/Subtype` of the embedded stream), e.g. `application/xml`. */
+    mimeType?: string;
+    /** `/AFRelationship` - `Source`, `Data`, `Alternative`, `Supplement`, `Unspecified`, ... */
+    relationship?: string;
+    /** The size the file DECLARES (`/Params /Size`). Informative only: `bytes()` is bounded by what it decodes to. */
+    declaredSize?: number;
+    created?: Date;
+    modified?: Date;
+    /** The MD5 the file declares (`/Params /CheckSum`); `bytes()` checks the data against it. */
+    checksum?: Uint8Array;
+    /** Every place it hangs - one file spec may be listed for the document AND annotated on a page. */
+    locations: AttachmentLocation[];
+    /** The file specification's object, when it is one - stable identity within this document. */
+    ref?: {
+        num: number;
+        gen: number;
+    };
+    /** The file's exact bytes: deciphered, every filter decoded, checked against its checksum. */
+    bytes(): Uint8Array;
+    /** The bytes as UTF-8 text, a byte-order mark dropped. */
+    text(): string;
+}
+/** Every attachment in the document, in the order: name tree, catalog `/AF`, then page by page. */
+export declare function readAttachments(doc: PdfDocument): Attachment[];

package/dist/edit/attachments.js

@@ -0,0 +1,178 @@
+import { md5 } from "../utils/md5.js";
+import { get, isDict, isRef, isStream, isString, nameOf, numberOf, textStringOf, } from "./objects.js";
+/**
+ * The files embedded in a PDF - every one of them, with everything the file says about it, and its
+ * exact bytes on demand.
+ *
+ * Attachments live in three places, and real files use all three: the document's `/EmbeddedFiles` name
+ * tree (a tree - large ones split into `/Kids`), the `/AF` arrays of PDF/A-3 (the catalog's, and a page's),
+ * and `FileAttachment` annotations on pages. One file spec reached from two places is ONE attachment;
+ * two different file specs with the same name are TWO - telling those apart is the caller's business,
+ * so nothing is merged by name.
+ */
+/** Thrown when an attachment's data cannot be handed back exactly as it was embedded. */
+export class AttachmentError extends Error {
+    constructor(message) {
+        super(`@jasy/pdf: ${message}`);
+    }
+}
+/** Every attachment in the document, in the order: name tree, catalog `/AF`, then page by page. */
+export function readAttachments(doc) {
+    const out = [];
+    const byRef = new Map();
+    const add = (spec, where, key) => {
+        const known = isRef(spec) ? byRef.get(spec.num) : undefined;
+        if (known) {
+            const same = known.locations.some((l) => l.kind === where.kind &&
+                (l.kind === "document" || l.page === where.page));
+            if (!same)
+                known.locations.push(where);
+            if (key !== undefined)
+                known.key ?? (known.key = key);
+            return;
+        }
+        const attachment = toAttachment(doc, spec, where, key);
+        if (!attachment)
+            return;
+        out.push(attachment);
+        if (isRef(spec))
+            byRef.set(spec.num, attachment);
+    };
+    const catalog = doc.catalog;
+    const tree = doc.lookup(doc.lookup(catalog, "Names"), "EmbeddedFiles");
+    walkNameTree(doc, tree, (key, spec) => add(spec, { kind: "document" }, key));
+    for (const spec of arrayOf(doc, doc.lookup(catalog, "AF")))
+        add(spec, { kind: "document" });
+    pagesOf(doc).forEach((page, index) => {
+        const where = { kind: "page", page: index };
+        for (const spec of arrayOf(doc, doc.lookup(page, "AF")))
+            add(spec, where);
+        for (const annot of arrayOf(doc, doc.lookup(page, "Annots"))) {
+            const dict = doc.resolve(annot);
+            if (nameOf(get(dict, "Subtype")) === "FileAttachment")
+                add(get(dict, "FS"), where);
+        }
+    });
+    return out;
+}
+/** One file specification as an attachment, or nothing when it embeds no file (a mere reference). */
+function toAttachment(doc, specRef, where, key) {
+    const spec = doc.resolve(specRef);
+    if (spec === undefined || !isDict(spec))
+        return undefined;
+    const ef = doc.resolve(get(spec, "EF"));
+    const fileRef = get(ef, "F") ?? get(ef, "UF");
+    const file = doc.resolve(fileRef);
+    if (file === undefined || !isStream(file))
+        return undefined;
+    const params = doc.resolve(get(file, "Params"));
+    const name = textStringOf(doc.resolve(get(spec, "UF"))) ??
+        textStringOf(doc.resolve(get(spec, "F"))) ??
+        key ??
+        "";
+    const checksum = doc.resolve(get(params, "CheckSum"));
+    const declared = isString(checksum) ? checksum.bytes : undefined;
+    let decoded;
+    const bytes = () => {
+        if (decoded)
+            return decoded;
+        let data;
+        try {
+            data = doc.streamData(file, true);
+        }
+        catch (e) {
+            throw new AttachmentError(`the attachment "${name}" cannot be read: ${String(e?.message ?? e).replace(/^@jasy\/pdf: /, "")}`);
+        }
+        if (declared && declared.length === 16 && !sameBytes(md5(data), declared)) {
+            throw new AttachmentError(`the attachment "${name}" does not match its own checksum - it was changed or damaged after ` +
+                `it was embedded`);
+        }
+        return (decoded = data);
+    };
+    return {
+        name,
+        key,
+        description: textStringOf(doc.resolve(get(spec, "Desc"))),
+        mimeType: nameOf(get(file, "Subtype")),
+        relationship: nameOf(get(spec, "AFRelationship")),
+        declaredSize: numberOf(doc.resolve(get(params, "Size"))),
+        created: dateOf(doc.resolve(get(params, "CreationDate"))),
+        modified: dateOf(doc.resolve(get(params, "ModDate"))),
+        checksum: declared,
+        locations: [where],
+        ref: isRef(specRef) ? { num: specRef.num, gen: specRef.gen } : undefined,
+        bytes,
+        text: () => {
+            const b = bytes();
+            const bom = b.length >= 3 && b[0] === 0xef && b[1] === 0xbb && b[2] === 0xbf;
+            return new TextDecoder().decode(bom ? b.subarray(3) : b);
+        },
+    };
+}
+/** A name tree's leaves in key order, through `/Kids` - bounded, and a node reached twice is read once. */
+function walkNameTree(doc, root, visit) {
+    const seen = new Set();
+    const node = (n, depth) => {
+        if (depth > 64)
+            return;
+        if (isRef(n)) {
+            if (seen.has(n.num))
+                return;
+            seen.add(n.num);
+        }
+        const dict = doc.resolve(n);
+        if (dict === undefined || !isDict(dict))
+            return;
+        const names = doc.resolve(get(dict, "Names"));
+        if (Array.isArray(names)) {
+            for (let i = 0; i + 1 < names.length; i += 2) {
+                visit(textStringOf(doc.resolve(names[i])) ?? "", names[i + 1]);
+            }
+        }
+        for (const kid of arrayOf(doc, get(dict, "Kids")))
+            node(kid, depth + 1);
+    };
+    node(root, 0);
+}
+/** The page dictionaries in document order - bounded, a page tree node reached twice is read once. */
+function pagesOf(doc) {
+    const out = [];
+    const seen = new Set();
+    const node = (n, depth) => {
+        if (depth > 64)
+            return;
+        if (isRef(n)) {
+            if (seen.has(n.num))
+                return;
+            seen.add(n.num);
+        }
+        const dict = doc.resolve(n);
+        if (dict === undefined || !isDict(dict))
+            return;
+        const kids = doc.lookup(dict, "Kids");
+        if (Array.isArray(kids))
+            for (const kid of kids)
+                node(kid, depth + 1);
+        else
+            out.push(dict);
+    };
+    node(get(doc.catalog, "Pages"), 0);
+    return out;
+}
+const arrayOf = (doc, o) => {
+    const a = doc.resolve(o);
+    return Array.isArray(a) ? a : [];
+};
+const sameBytes = (a, b) => a.length === b.length && a.every((v, i) => v === b[i]);
+/** A PDF date, `D:YYYYMMDDHHmmSSOHH'mm`, everything after the year optional. */
+function dateOf(o) {
+    const s = textStringOf(o);
+    const m = s &&
+        /^(?:D:)?(\d{4})(\d{2})?(\d{2})?(\d{2})?(\d{2})?(\d{2})?([Zz+-])?(\d{2})?'?(\d{2})?'?/.exec(s.trim());
+    if (!m)
+        return undefined;
+    const [, y, mo = "01", d = "01", h = "00", mi = "00", sec = "00", sign, oh = "00", om = "00"] = m;
+    const utc = Date.UTC(+y, +mo - 1, +d, +h, +mi, +sec);
+    const offset = sign === "+" || sign === "-" ? (sign === "+" ? 1 : -1) * (+oh * 60 + +om) : 0;
+    return new Date(utc - offset * 60000);
+}

package/dist/edit/document.d.ts

@@ -13,7 +13,9 @@ export interface OpenOptions extends LoadOptions {
 /** Thrown when a file cannot be opened because of its encryption - always saying which of the reasons it
  *  is: no password, wrong password, or a revision we do not implement. */
 export declare class PdfEncryptedError extends Error {
-    constructor(message: string);
+    readonly needsPassword: boolean;
+    /** `needsPassword`: the password is missing or wrong - as opposed to a file we cannot decrypt at all. */
+    constructor(message: string, needsPassword?: boolean);
 }
 export declare class PdfDocument {
     readonly bytes: Uint8Array;
@@ -23,6 +25,10 @@ export declare class PdfDocument {
     private readonly objStmCache;
     /** Set once an encrypted file has been opened with its password. */
     private security?;
+    /** Which of streams, strings and attached files this file enciphers (all of them, but for `/Identity`). */
+    private enciphered?;
+    /** Attached files encrypted on their own (`/EFF`) and opened without the password: their streams. */
+    private readonly lockedFiles;
     /** Decrypted stream payloads, keyed by the stream's data offset (unique per stream). */
     private readonly plainStreams;
     /** True when the cross-reference index was unusable and had to be rebuilt by scanning. Surfaced so
@@ -46,6 +52,8 @@ export declare class PdfDocument {
      * before the synchronous constructor).
      */
     static open(bytes: Uint8Array, opts?: OpenOptions): Promise<PdfDocument>;
+    /** Which parts the `/Encrypt` dictionary enciphers. Before V4 there are no crypt filters: everything. */
+    private encipheredParts;
     /**
      * Build the handler for this file's `/Encrypt` dictionary, or say precisely why we cannot.
      *
@@ -54,13 +62,15 @@ export declare class PdfDocument {
      */
     private securityHandlerFor;
     /**
-     * Which cipher and key length actually apply to the streams.
+     * Which cipher and key length a legacy (V2-V4) file uses.
      *
-     * For V4 the answer is NOT the top-level `/Length`: the document names a crypt filter in `/StmF` and
-     * that filter carries its own `/CFM` and `/Length` (in BYTES, where the top-level one is in bits).
-     * `/Identity` means the streams are not enciphered at all - decrypting them anyway would destroy them.
+     * For V4 the answer is NOT the top-level `/Length`: the document names crypt filters - `/StmF` for
+     * streams, `/StrF` for strings, `/EFF` for attached files - and each carries its own `/CFM` and
+     * `/Length` (in BYTES, where the top-level one is in bits). `/Identity` means "not enciphered". One
+     * handler serves them all, so the filters that DO encipher must agree; two different ciphers in one
+     * file are refused by name.
      */
-    private streamCipher;
+    private legacyCipher;
     /**
      * Decrypt every string and stream, once, in place.
      *
@@ -70,6 +80,10 @@ export declare class PdfDocument {
      * the clear already.
      */
     private decryptEverything;
+    /** A stream that names the `/Identity` crypt filter in its own `/Filter` is not enciphered. */
+    private identityCrypt;
+    /** The object numbers of every attached file's stream: whatever an /EF dictionary points at. */
+    private embeddedFileStreams;
     /** The byte offset in the `startxref` trailer at the very end of the file. */
     private findStartXref;
     /** Read the index at `startxref`, then walk `/Prev` back through earlier revisions. Entries already
@@ -110,6 +124,8 @@ export declare class PdfDocument {
     /** True once the password has been accepted and the contents decrypted, so what is read is plaintext.
      *  Always true for a document that was never encrypted. */
     get isReadable(): boolean;
+    /** Whether streams or strings are enciphered - not the case when only attached files are. */
+    private get encryptsDocument();
     /**
      * Encipher a value that is about to be written back INTO this document, or `undefined` when the
      * document is not encrypted and the value goes in as it is.
@@ -132,13 +148,27 @@ export declare class PdfDocument {
     get catalog(): PdfObject | undefined;
     /** A stream's bytes as they sit in the file: sliced by `/Length`, still filtered and still encrypted. */
     private rawStream;
-    /** A stream's DECODED bytes: deciphered if the document is encrypted, then run through its filters. */
-    streamData(stream: PdfStream): Uint8Array;
+    /**
+     * A stream's DECODED bytes: deciphered if the document is encrypted, then run through its filters.
+     *
+     * `strict` is for data handed to a caller as it is (an attachment): every filter must decode, or this
+     * throws a `PdfFilterError` - never bytes still encoded or half decoded. The default suits the
+     * structural reads, where a filter that fails is skipped and the rest is read as it stands.
+     */
+    streamData(stream: PdfStream, strict?: boolean): Uint8Array;
+    /**
+     * One filter. Each pass is bounded on what it produces, because /Filter is a list and
+     * [/FlateDecode /FlateDecode] is a legal nested bomb. The image codecs (DCT, JPX, CCITT, JBIG2) decode
+     * to pixels, not to a file: strict refuses them by name, the default leaves them encoded.
+     */
+    private decodeFilter;
     /**
      * Undo a PNG predictor (`/Predictor` 10-15), which xref streams almost always use - the IRS form in
      * our fixtures does. Each row is prefixed with its filter type and is decoded against the row above.
      */
     private undoPredictor;
+    /** TIFF predictor 2: each component is the difference from the one to its left, per row. */
+    private undoTiffPredictor;
     /** Every object number the index knows, ascending - for walking a whole document. */
     objectNumbers(): number[];
 }