@jasy/pdf 1.0.0-alpha.1 → 1.0.0-alpha.10

package/dist/edit/lexer.js

@@ -0,0 +1,285 @@
+const EMPTY = new Uint8Array(0);
+/**
+ * The PDF object parser: bytes in, `PdfObject` out.
+ *
+ * It works on a `Uint8Array` with an explicit cursor rather than on a decoded string, because a PDF is
+ * binary - a literal string may hold any byte, and a stream certainly does. Decoding to text first
+ * would corrupt exactly the data we came for.
+ *
+ * Scope: enough of the grammar to walk a document to its `/AcroForm`. No content-stream operators, no
+ * function/shading evaluation - those are a renderer's job, not a form reader's.
+ */
+// PDF whitespace (7.2.2): null, tab, LF, FF, CR, space.
+const isSpace = (c) => c === 0 || c === 9 || c === 10 || c === 12 || c === 13 || c === 32;
+// Delimiters (7.2.2) - they end a token even without whitespace.
+const isDelim = (c) => c === 0x28 ||
+    c === 0x29 ||
+    c === 0x3c ||
+    c === 0x3e ||
+    c === 0x5b ||
+    c === 0x5d ||
+    c === 0x7b ||
+    c === 0x7d ||
+    c === 0x2f ||
+    c === 0x25;
+const isRegular = (c) => !isSpace(c) && !isDelim(c);
+const isDigit = (c) => c >= 0x30 && c <= 0x39;
+const hexVal = (c) => c >= 0x30 && c <= 0x39
+    ? c - 0x30
+    : c >= 0x41 && c <= 0x46
+        ? c - 55
+        : c >= 0x61 && c <= 0x66
+            ? c - 87
+            : -1;
+export class Lexer {
+    constructor(bytes, pos = 0) {
+        this.bytes = bytes;
+        this.pos = pos;
+    }
+    /** Skip whitespace and comments (`%` to end of line). */
+    skip() {
+        for (;;) {
+            while (this.pos < this.bytes.length && isSpace(this.bytes[this.pos]))
+                this.pos++;
+            if (this.bytes[this.pos] !== 0x25)
+                return; // '%'
+            while (this.pos < this.bytes.length &&
+                this.bytes[this.pos] !== 10 &&
+                this.bytes[this.pos] !== 13)
+                this.pos++;
+        }
+    }
+    /** The next bare token (a keyword like `obj`, `R`, `endstream`), without consuming delimiters. */
+    word() {
+        const start = this.pos;
+        while (this.pos < this.bytes.length && isRegular(this.bytes[this.pos]))
+            this.pos++;
+        return new TextDecoder("latin1").decode(this.bytes.subarray(start, this.pos));
+    }
+    /** True when the bytes at the cursor spell `word` (after whitespace). Does not consume. */
+    peekWord(word) {
+        const save = this.pos;
+        this.skip();
+        const w = this.word();
+        this.pos = save;
+        return w === word;
+    }
+    /** Consume `word` if present; report whether it was. */
+    eatWord(word) {
+        const save = this.pos;
+        this.skip();
+        if (this.word() === word)
+            return true;
+        this.pos = save;
+        return false;
+    }
+    /**
+     * Parse one object at the cursor. Returns `undefined` at end of input or on a token this reader does
+     * not model - the caller treats that as "not something I can work with" rather than crashing.
+     */
+    parse() {
+        this.skip();
+        if (this.pos >= this.bytes.length)
+            return undefined;
+        const c = this.bytes[this.pos];
+        if (c === 0x2f)
+            return this.name();
+        if (c === 0x28)
+            return this.literalString();
+        if (c === 0x5b)
+            return this.array();
+        if (c === 0x3c) {
+            return this.bytes[this.pos + 1] === 0x3c ? this.dictOrStream() : this.hexString();
+        }
+        if (isDigit(c) || c === 0x2b || c === 0x2d || c === 0x2e)
+            return this.numberOrRef();
+        const w = this.word();
+        if (w === "true")
+            return true;
+        if (w === "false")
+            return false;
+        if (w === "null")
+            return null;
+        return undefined; // an unmodelled keyword; the caller decides
+    }
+    /** `/Name`, with `#XX` escapes decoded (a font or field name may hold `#20` for a space). */
+    name() {
+        this.pos++; // '/'
+        let out = "";
+        while (this.pos < this.bytes.length && isRegular(this.bytes[this.pos])) {
+            const b = this.bytes[this.pos++];
+            if (b === 0x23 && this.pos + 1 < this.bytes.length) {
+                const hi = hexVal(this.bytes[this.pos]);
+                const lo = hexVal(this.bytes[this.pos + 1]);
+                if (hi >= 0 && lo >= 0) {
+                    out += String.fromCharCode((hi << 4) | lo);
+                    this.pos += 2;
+                    continue;
+                }
+            }
+            out += String.fromCharCode(b);
+        }
+        return { kind: "name", name: out };
+    }
+    /** `(text)`: balanced nested parens, backslash escapes, and the line continuation. */
+    literalString() {
+        this.pos++; // '('
+        const out = [];
+        let depth = 1;
+        while (this.pos < this.bytes.length) {
+            const b = this.bytes[this.pos++];
+            if (b === 0x5c) {
+                // backslash
+                if (this.pos >= this.bytes.length)
+                    break; // truncated file: nothing follows the escape
+                const e = this.bytes[this.pos++];
+                const simple = { 0x6e: 10, 0x72: 13, 0x74: 9, 0x62: 8, 0x66: 12 };
+                if (e in simple)
+                    out.push(simple[e]);
+                else if (e >= 0x30 && e <= 0x37) {
+                    // up to three octal digits
+                    let v = e - 0x30;
+                    for (let i = 0; i < 2 && this.bytes[this.pos] >= 0x30 && this.bytes[this.pos] <= 0x37; i++)
+                        v = v * 8 + (this.bytes[this.pos++] - 0x30);
+                    out.push(v & 0xff);
+                }
+                else if (e === 10) {
+                    /* line continuation: the newline is dropped */
+                }
+                else if (e === 13) {
+                    if (this.bytes[this.pos] === 10)
+                        this.pos++;
+                }
+                else
+                    out.push(e);
+                continue;
+            }
+            // An UNESCAPED end-of-line inside a literal is a line break, not data: CR, LF and CRLF all mean
+            // one LF (7.3.4.2). Passing a CR through verbatim would quietly change the value of any field
+            // written across two lines.
+            if (b === 13) {
+                if (this.bytes[this.pos] === 10)
+                    this.pos++;
+                out.push(10);
+                continue;
+            }
+            if (b === 0x28)
+                depth++;
+            if (b === 0x29 && --depth === 0)
+                break;
+            out.push(b);
+        }
+        return { kind: "string", bytes: new Uint8Array(out), hex: false };
+    }
+    /** `<48656C6C6F>`: hex digits, whitespace ignored, an odd final digit padded with 0. */
+    hexString() {
+        this.pos++; // '<'
+        const out = [];
+        let hi = -1;
+        while (this.pos < this.bytes.length) {
+            const b = this.bytes[this.pos++];
+            if (b === 0x3e)
+                break; // '>'
+            const v = hexVal(b);
+            if (v < 0)
+                continue; // whitespace or junk inside a hex string is ignored
+            if (hi < 0)
+                hi = v;
+            else {
+                out.push((hi << 4) | v);
+                hi = -1;
+            }
+        }
+        if (hi >= 0)
+            out.push(hi << 4);
+        return { kind: "string", bytes: new Uint8Array(out), hex: true };
+    }
+    array() {
+        this.pos++; // '['
+        const out = [];
+        for (;;) {
+            this.skip();
+            if (this.pos >= this.bytes.length)
+                break;
+            if (this.bytes[this.pos] === 0x5d) {
+                this.pos++;
+                break;
+            }
+            const before = this.pos;
+            const v = this.parse();
+            if (v === undefined) {
+                // An unmodelled token inside an array: step past it so we cannot spin forever.
+                if (this.pos === before)
+                    this.pos++;
+                continue;
+            }
+            out.push(v);
+        }
+        return out;
+    }
+    /** `<< … >>`, followed by `stream` when it is a stream object. */
+    dictOrStream() {
+        this.pos += 2; // '<<'
+        const map = new Map();
+        for (;;) {
+            this.skip();
+            if (this.pos >= this.bytes.length)
+                break;
+            if (this.bytes[this.pos] === 0x3e && this.bytes[this.pos + 1] === 0x3e) {
+                this.pos += 2;
+                break;
+            }
+            if (this.bytes[this.pos] !== 0x2f) {
+                // Not a key where one belongs - skip a token rather than loop.
+                const before = this.pos;
+                if (this.parse() === undefined && this.pos === before)
+                    this.pos++;
+                continue;
+            }
+            const key = this.name();
+            const value = this.parse();
+            if (value !== undefined)
+                map.set(key.name, value);
+        }
+        const dict = { kind: "dict", map };
+        // A stream follows its dictionary. Its length is in /Length, which is allowed to be an indirect
+        // reference - resolving that needs the whole document, so we only record where the data starts and
+        // let the document layer slice it.
+        const save = this.pos;
+        if (this.eatWord("stream")) {
+            if (this.bytes[this.pos] === 13)
+                this.pos++;
+            if (this.bytes[this.pos] === 10)
+                this.pos++;
+            return { kind: "stream", dict, start: this.pos, raw: EMPTY };
+        }
+        this.pos = save;
+        return dict;
+    }
+    /** A number, or an indirect reference when the shape is `int int R`. */
+    numberOrRef() {
+        const start = this.pos;
+        if (this.bytes[this.pos] === 0x2b || this.bytes[this.pos] === 0x2d)
+            this.pos++;
+        while (this.pos < this.bytes.length &&
+            (isDigit(this.bytes[this.pos]) || this.bytes[this.pos] === 0x2e))
+            this.pos++;
+        const text = new TextDecoder("latin1").decode(this.bytes.subarray(start, this.pos));
+        const value = Number(text);
+        // Look ahead for `<gen> R`; restore the cursor when it is not there.
+        if (Number.isInteger(value) && value >= 0 && !text.includes(".")) {
+            const save = this.pos;
+            this.skip();
+            const genStart = this.pos;
+            while (this.pos < this.bytes.length && isDigit(this.bytes[this.pos]))
+                this.pos++;
+            if (this.pos > genStart) {
+                const gen = Number(new TextDecoder("latin1").decode(this.bytes.subarray(genStart, this.pos)));
+                if (this.eatWord("R"))
+                    return { kind: "ref", num: value, gen };
+            }
+            this.pos = save;
+        }
+        return value;
+    }
+}

package/dist/edit/objects.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The PDF object model, as READ from an existing file - the counterpart of the writer's string
+ * building. Deliberately small: this reader exists to find and change an `/AcroForm`, not to model
+ * every corner of the format.
+ *
+ * Values stay close to the bytes on purpose. A PDF string is kept as RAW BYTES rather than a JS string,
+ * because its encoding is not known until you look at it (a literal may be PDFDocEncoded, a hex string
+ * is often UTF-16BE with a BOM - pdf-lib writes every field name that way). Decoding early would lose
+ * the distinction and mangle names.
+ */
+export interface PdfName {
+    kind: "name";
+    /** The name WITHOUT the leading slash, `#XX` already decoded. */
+    name: string;
+}
+export interface PdfString {
+    kind: "string";
+    bytes: Uint8Array;
+    /** True when it was written as `<hex>` rather than `(literal)`. Kept for faithful round-tripping. */
+    hex: boolean;
+}
+/** An indirect reference, `12 0 R`. Resolved against the document, never followed by the parser itself. */
+export interface PdfRef {
+    kind: "ref";
+    num: number;
+    gen: number;
+}
+export interface PdfDict {
+    kind: "dict";
+    map: Map<string, PdfObject>;
+}
+/**
+ * A stream: its dictionary plus the RAW (still encoded) bytes between `stream` and `endstream`.
+ *
+ * The parser records only where the data STARTS, because the length lives in `/Length`, which is itself
+ * allowed to be an indirect reference - resolving it needs the whole document. The document layer fills
+ * `raw` once it can.
+ */
+export interface PdfStream {
+    kind: "stream";
+    dict: PdfDict;
+    /** Byte offset of the first data byte (just past the EOL after the `stream` keyword). */
+    start: number;
+    /** The still-encoded bytes; empty until the document resolves `/Length`. */
+    raw: Uint8Array;
+}
+export type PdfObject = number | boolean | null | PdfName | PdfString | PdfRef | PdfDict | PdfStream | PdfObject[];
+export declare const isName: (o: PdfObject | undefined) => o is PdfName;
+export declare const isString: (o: PdfObject | undefined) => o is PdfString;
+export declare const isRef: (o: PdfObject | undefined) => o is PdfRef;
+export declare const isDict: (o: PdfObject | undefined) => o is PdfDict;
+export declare const isStream: (o: PdfObject | undefined) => o is PdfStream;
+/** A dictionary entry, by key without the slash. Reads through a stream to its dictionary, since the
+ *  two are asked the same questions (`/Type`, `/Length`, …). */
+export declare function get(o: PdfObject | undefined, key: string): PdfObject | undefined;
+export declare const nameOf: (o: PdfObject | undefined) => string | undefined;
+export declare const numberOf: (o: PdfObject | undefined) => number | undefined;
+/**
+ * A PDF text string as JS text. Two encodings live side by side in the wild: UTF-16BE, marked by a
+ * `FE FF` byte-order mark (what pdf-lib writes for every field name), and otherwise PDFDocEncoding,
+ * which agrees with Latin-1 for everything a field name realistically holds.
+ */
+export declare function textOf(o: PdfObject | undefined): string | undefined;
+/**
+ * Every string inside an object, however deep. Both sides of the crypto seam use it: strings are
+ * deciphered on open and must be enciphered again before an object is written back.
+ */
+export declare function stringsIn(o: PdfObject | undefined, out?: PdfString[], depth?: number): PdfString[];

package/dist/edit/objects.js

@@ -0,0 +1,83 @@
+/**
+ * The PDF object model, as READ from an existing file - the counterpart of the writer's string
+ * building. Deliberately small: this reader exists to find and change an `/AcroForm`, not to model
+ * every corner of the format.
+ *
+ * Values stay close to the bytes on purpose. A PDF string is kept as RAW BYTES rather than a JS string,
+ * because its encoding is not known until you look at it (a literal may be PDFDocEncoded, a hex string
+ * is often UTF-16BE with a BOM - pdf-lib writes every field name that way). Decoding early would lose
+ * the distinction and mangle names.
+ */
+import { latin1FromBytes } from "../utils/bytes.js";
+// ---------------------------------------------------------------------------------------------
+// Narrowing helpers. Reading a foreign PDF means every lookup can legitimately come back missing or
+// of the wrong type, so these all answer `undefined` rather than throwing - the caller decides what
+// is fatal.
+// ---------------------------------------------------------------------------------------------
+// The guards take an OPTIONAL object on purpose: they are nearly always applied to the result of a
+// lookup that may find nothing (`isRef(get(o, "AP"))`), and a missing entry simply is not of the type.
+export const isName = (o) => typeof o === "object" && o !== null && !Array.isArray(o) && o.kind === "name";
+export const isString = (o) => typeof o === "object" && o !== null && !Array.isArray(o) && o.kind === "string";
+export const isRef = (o) => typeof o === "object" && o !== null && !Array.isArray(o) && o.kind === "ref";
+export const isDict = (o) => typeof o === "object" && o !== null && !Array.isArray(o) && o.kind === "dict";
+export const isStream = (o) => typeof o === "object" && o !== null && !Array.isArray(o) && o.kind === "stream";
+/** A dictionary entry, by key without the slash. Reads through a stream to its dictionary, since the
+ *  two are asked the same questions (`/Type`, `/Length`, …). */
+export function get(o, key) {
+    if (o === undefined)
+        return undefined;
+    if (isStream(o))
+        return o.dict.map.get(key);
+    if (isDict(o))
+        return o.map.get(key);
+    return undefined;
+}
+export const nameOf = (o) => o !== undefined && isName(o) ? o.name : undefined;
+export const numberOf = (o) => typeof o === "number" ? o : undefined;
+/**
+ * A PDF text string as JS text. Two encodings live side by side in the wild: UTF-16BE, marked by a
+ * `FE FF` byte-order mark (what pdf-lib writes for every field name), and otherwise PDFDocEncoding,
+ * which agrees with Latin-1 for everything a field name realistically holds.
+ */
+export function textOf(o) {
+    if (o === undefined || !isString(o))
+        return undefined;
+    const b = o.bytes;
+    if (b.length >= 2 && b[0] === 0xfe && b[1] === 0xff) {
+        let s = "";
+        for (let i = 2; i + 1 < b.length; i += 2)
+            s += String.fromCharCode((b[i] << 8) | b[i + 1]);
+        return s;
+    }
+    // latin1FromBytes, NOT TextDecoder("latin1"): the latter is a WHATWG alias for windows-1252, which
+    // remaps 0x80-0x9F (byte 0x95 becomes a bullet). Mapping each byte to the same code point keeps the
+    // value round-trippable, which is what a reader that may write the string back needs.
+    return latin1FromBytes(b);
+}
+/**
+ * Every string inside an object, however deep. Both sides of the crypto seam use it: strings are
+ * deciphered on open and must be enciphered again before an object is written back.
+ */
+export function stringsIn(o, out = [], depth = 0) {
+    if (o === undefined || o === null)
+        return out;
+    // Throws rather than returning a short list: a missed string is one written back in the clear.
+    // Bounded at all only because the walk does not follow references, just inline containers.
+    if (depth > MAX_NESTING) {
+        throw new Error(`@jasy/pdf: this PDF nests objects more than ${MAX_NESTING} deep, which no legitimate producer ` +
+            `does; refusing to walk it`);
+    }
+    if (isString(o))
+        out.push(o);
+    else if (Array.isArray(o))
+        for (const e of o)
+            stringsIn(e, out, depth + 1);
+    // The dictionary only - a stream's DATA is covered by the stream's own encryption.
+    else if (isStream(o))
+        stringsIn(o.dict, out, depth + 1);
+    else if (isDict(o))
+        for (const v of o.map.values())
+            stringsIn(v, out, depth + 1);
+    return out;
+}
+const MAX_NESTING = 64;

package/dist/edit/writer.d.ts

@@ -0,0 +1,60 @@
+import type { PdfDocument } from "./document.js";
+import { type PdfObject, type PdfString } from "./objects.js";
+/** Strings already enciphered for write-back, keyed by the very object they replace. */
+export type StringCipher = Map<PdfString, string>;
+/**
+ * Serialise an object back to PDF syntax. Used only for objects we deliberately change - everything we
+ * do not touch stays in the original bytes, untouched and unre-encoded.
+ *
+ * A string keeps the spelling it was read with: a name written as `<FEFF…>` stays hex, because that is
+ * how the producer encodes unicode and rewriting it as a literal would corrupt it.
+ */
+export declare function serialize(o: PdfObject | undefined, cipher?: StringCipher): string;
+/** A stream we are adding: its dictionary entries plus the raw (already encoded) data. */
+export interface NewStream {
+    dict: string;
+    data: Uint8Array;
+}
+export declare class IncrementalWriter {
+    private readonly doc;
+    /** Object number -> its new body, in PDF syntax. */
+    private readonly changed;
+    /** Numbers this writer invented, as opposed to ones it replaces - they have no recorded generation. */
+    private readonly added;
+    private helvNum?;
+    private nextNum;
+    constructor(doc: PdfDocument);
+    /** Replace an existing object. */
+    update(objNum: number, body: string | NewStream): void;
+    /** Append a new object and return its number. */
+    add(body: string | NewStream): number;
+    /** A shared Helvetica for regenerated appearances, added once and only when one is drawn. */
+    helv(): number;
+    /** The generation to write for an object: the file's own for one we replace, 0 for one we add. */
+    private generationOf;
+    get hasChanges(): boolean;
+    /**
+     * Produce the updated file: the original bytes, then every changed object, then a new cross-reference
+     * section chained to the old one.
+     */
+    save(): Uint8Array;
+    /**
+     * The new cross-reference section, as BYTES.
+     *
+     * Bytes, not a string: an xref stream is binary, and running it through a UTF-8 encoder would turn
+     * every value above 127 into two bytes - which is most offsets, so the whole index becomes garbage.
+     *
+     * A classic table is written when the file already had one; an xref-STREAM file gets a stream,
+     * because mixing the two leaves readers that follow only one kind unable to walk the chain back.
+     */
+    private xrefSection;
+    /** The offset the ORIGINAL file's `startxref` pointed at - our `/Prev`. */
+    private previousStartXref;
+}
+/**
+ * Encipher every string the given objects carry, into the cipher map `serialize` consults.
+ *
+ * Not optional on an encrypted document: `serialize` writes any string missing from the map as
+ * PLAINTEXT, so an object rewritten without this pass leaks whatever it holds.
+ */
+export declare function carryStrings(doc: PdfDocument, objects: Array<PdfObject | undefined>, into?: Map<PdfString, string>): Promise<StringCipher>;