@jasy/pdf 1.0.0-beta.2 → 1.0.0-beta.4

package/dist/edit/document.js

@@ -3,12 +3,15 @@ import { DEFAULT_MAX_STREAM_SIZE, inflateBounded, PdfStreamTooLargeError, } from
 import { get, isDict, isRef, isStream, isString, nameOf, numberOf, stringsIn, } from "./objects.js";
 import { StandardAes256 } from "../crypto/security-handler.js";
 import { StandardLegacy } from "../crypto/legacy-handler.js";
+import { ascii85Decode, asciiHexDecode, lzwDecode, PdfFilterError, runLengthDecode, } from "./filters.js";
 const EMPTY = new Uint8Array(0);
 /** 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 class PdfEncryptedError extends Error {
-    constructor(message) {
+    /** `needsPassword`: the password is missing or wrong - as opposed to a file we cannot decrypt at all. */
+    constructor(message, needsPassword = false) {
         super(`@jasy/pdf: ${message}`);
+        this.needsPassword = needsPassword;
     }
 }
 /** The raw bytes of a `/Encrypt` entry that must be a string (`/U`, `/UE`). */
@@ -20,6 +23,8 @@ export class PdfDocument {
         this.cache = new Map();
         /** Object streams already unpacked, by their object number. */
         this.objStmCache = new Map();
+        /** Attached files encrypted on their own (`/EFF`) and opened without the password: their streams. */
+        this.lockedFiles = new Set();
         /** Decrypted stream payloads, keyed by the stream's data offset (unique per stream). */
         this.plainStreams = new Map();
         /** True when the cross-reference index was unusable and had to be rebuilt by scanning. Surfaced so
@@ -61,10 +66,37 @@ export class PdfDocument {
         const doc = PdfDocument.load(bytes, opts);
         if (!doc.isEncrypted)
             return doc;
-        doc.security = await doc.securityHandlerFor(opts.password);
+        doc.enciphered = doc.encipheredParts();
+        try {
+            doc.security = await doc.securityHandlerFor(opts.password);
+        }
+        catch (e) {
+            // Only the attached files are encrypted (Acrobat's "encrypt only file attachments"): without a
+            // password the document opens as it is, and an attachment asks for it when it is read. A WRONG
+            // password is still reported as one.
+            const filesOnly = !doc.enciphered.streams && !doc.enciphered.strings;
+            const noPassword = opts.password === undefined;
+            if (!(filesOnly && noPassword && e instanceof PdfEncryptedError && e.needsPassword))
+                throw e;
+        }
         await doc.decryptEverything();
         return doc;
     }
+    /** Which parts the `/Encrypt` dictionary enciphers. Before V4 there are no crypt filters: everything. */
+    encipheredParts() {
+        const enc = this.resolve(this.trailer.map.get("Encrypt"));
+        if ((numberOf(this.lookup(enc, "V")) ?? 0) < 4)
+            return { streams: true, strings: true, files: true };
+        const real = (name) => name !== undefined &&
+            name !== "Identity" &&
+            nameOf(this.lookup(this.lookup(this.lookup(enc, "CF"), name), "CFM")) !== "None";
+        const stmf = nameOf(this.lookup(enc, "StmF")) ?? "Identity";
+        return {
+            streams: real(stmf),
+            strings: real(nameOf(this.lookup(enc, "StrF")) ?? "Identity"),
+            files: real(nameOf(this.lookup(enc, "EFF")) ?? stmf),
+        };
+    }
     /**
      * Build the handler for this file's `/Encrypt` dictionary, or say precisely why we cannot.
      *
@@ -85,8 +117,8 @@ export class PdfDocument {
         const pw = password ?? "";
         const rejected = () => {
             throw password === undefined
-                ? new PdfEncryptedError("this PDF is encrypted; pass its password to open it")
-                : new PdfEncryptedError("wrong password for this PDF");
+                ? new PdfEncryptedError("this PDF is encrypted; pass its password to open it", true)
+                : new PdfEncryptedError("wrong password for this PDF", true);
         };
         // `recoverFileKey` / `StandardLegacy.open` say "wrong password" by name; anything else that comes out
         // of them is structural (a malformed /U, /UE, /O) and must not be reported as a bad password.
@@ -118,10 +150,7 @@ export class PdfDocument {
             const u = stringBytes(this.lookup(enc, "U"));
             if (o === undefined || u === undefined)
                 incomplete("incomplete");
-            const cipher = this.streamCipher(enc, v);
-            if (cipher.kind === "identity") {
-                throw new PdfEncryptedError("this PDF declares encryption but selects the Identity crypt filter, which jasy does not model");
-            }
+            const cipher = this.legacyCipher(enc, v);
             const ids = this.trailer.map.get("ID");
             const firstId = Array.isArray(ids) ? stringBytes(this.resolve(ids[0])) : undefined;
             try {
@@ -145,28 +174,42 @@ export class PdfDocument {
         throw new PdfEncryptedError(`this PDF uses standard security V${v}/R${r}, which jasy does not implement`);
     }
     /**
-     * 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.
      */
-    streamCipher(enc, v) {
+    legacyCipher(enc, v) {
         const topBits = numberOf(this.lookup(enc, "Length")) ?? 40;
         if (v < 4)
             return { kind: "rc4", keyBits: topBits };
         const stmf = nameOf(this.lookup(enc, "StmF")) ?? "Identity";
-        if (stmf === "Identity")
-            return { kind: "identity", keyBits: topBits };
-        const cf = this.lookup(this.lookup(enc, "CF"), stmf);
-        const cfm = nameOf(this.lookup(cf, "CFM"));
-        if (cfm === "None" || cfm === undefined)
-            return { kind: "identity", keyBits: topBits };
-        const cfBytes = numberOf(this.lookup(cf, "Length"));
-        return {
-            kind: cfm === "AESV2" ? "aes" : "rc4",
-            keyBits: cfBytes !== undefined ? cfBytes * 8 : topBits,
-        };
+        const used = [
+            stmf,
+            nameOf(this.lookup(enc, "StrF")) ?? "Identity",
+            nameOf(this.lookup(enc, "EFF")) ?? stmf,
+        ]
+            .filter((name) => name !== "Identity")
+            .map((name) => {
+            const cf = this.lookup(this.lookup(enc, "CF"), name);
+            const cfm = nameOf(this.lookup(cf, "CFM"));
+            const cfBytes = numberOf(this.lookup(cf, "Length"));
+            return cfm === undefined || cfm === "None"
+                ? undefined
+                : {
+                    kind: cfm === "AESV2" ? "aes" : "rc4",
+                    keyBits: cfBytes !== undefined ? cfBytes * 8 : topBits,
+                };
+        })
+            .filter((c) => c !== undefined);
+        const first = used[0] ?? { kind: "rc4", keyBits: topBits };
+        if (used.some((c) => c.kind !== first.kind || c.keyBits !== first.keyBits)) {
+            throw new PdfEncryptedError("this PDF enciphers its streams, strings and attached files with different crypt filters, which jasy does not model");
+        }
+        return first;
     }
     /**
      * Decrypt every string and stream, once, in place.
@@ -178,8 +221,7 @@ export class PdfDocument {
      */
     async decryptEverything() {
         const security = this.security;
-        if (!security)
-            return;
+        const enciphered = this.enciphered ?? { streams: true, strings: true, files: true };
         const encryptNum = isRef(this.trailer.map.get("Encrypt"))
             ? this.trailer.map.get("Encrypt").num
             : undefined;
@@ -199,6 +241,10 @@ export class PdfDocument {
                 continue; // never encrypted - it holds the index itself
             if (type === "Metadata" && metadataInClear)
                 continue;
+            if (type === "EmbeddedFile")
+                continue; // attached files follow /EFF, below
+            if (!security || !enciphered.streams || this.identityCrypt(obj))
+                continue;
             // Keyed by the stream's DATA OFFSET, not its object number: `streamData` receives the stream
             // object and has no number in hand.
             this.plainStreams.set(obj.start, await security.decrypt(this.rawStream(obj), { num, gen: entry.gen }));
@@ -209,7 +255,26 @@ export class PdfDocument {
         // itself stays - it was never encrypted.
         this.cache.clear();
         this.objStmCache.clear();
+        // Attached files follow their own crypt filter (/EFF). They are found by what points at them - an
+        // /EF entry - because a file stream need not say /Type /EmbeddedFile.
+        for (const num of this.embeddedFileStreams()) {
+            const entry = this.xref.get(num);
+            const obj = this.getObject(num);
+            if (entry?.kind !== "offset" || obj === undefined || !isStream(obj))
+                continue;
+            this.plainStreams.delete(obj.start); // a file stream without /Type was taken for a plain stream
+            if (!enciphered.files || this.identityCrypt(obj))
+                continue;
+            if (!security) {
+                this.lockedFiles.add(obj.start);
+                continue;
+            }
+            this.plainStreams.set(obj.start, await security.decrypt(this.rawStream(obj), { num, gen: entry.gen }));
+        }
+        this.cache.clear();
         // Then the strings, in objects that sit directly in the file.
+        if (!security || !enciphered.strings)
+            return;
         for (const [num, entry] of this.xref) {
             if (entry.kind !== "offset" || num === encryptNum)
                 continue;
@@ -221,14 +286,40 @@ export class PdfDocument {
                     s.bytes = await security.decrypt(s.bytes, { num, gen: entry.gen });
                 }
                 catch {
-                    // The password already validated against /U, so the key is right and this string simply is
-                    // not ciphertext - a producer left it in the clear. Say so instead of surfacing an AES error.
-                    throw new PdfEncryptedError(`object ${num} contains a string that is not encrypted, so this file does not follow its own ` +
-                        "/Encrypt declaration and cannot be read safely");
+                    // Only AES can fail here (RC4 has no padding). The password already validated against /U, so
+                    // the key is right: a string that does not decipher was left in the clear by its producer -
+                    // PDFKit does so with name-tree keys, of any length - and is read as it stands (and enciphered
+                    // when written back).
                 }
             }
         }
     }
+    /** A stream that names the `/Identity` crypt filter in its own `/Filter` is not enciphered. */
+    identityCrypt(stream) {
+        const filter = this.resolve(get(stream, "Filter"));
+        const filters = Array.isArray(filter) ? filter : [filter];
+        const i = filters.findIndex((f) => nameOf(this.resolve(f)) === "Crypt");
+        if (i < 0)
+            return false;
+        const parms = this.resolve(get(stream, "DecodeParms"));
+        const own = Array.isArray(parms) ? this.resolve(parms[i]) : parms;
+        return (nameOf(this.lookup(own, "Name")) ?? "Identity") === "Identity";
+    }
+    /** The object numbers of every attached file's stream: whatever an /EF dictionary points at. */
+    embeddedFileStreams() {
+        const out = new Set();
+        for (const num of this.xref.keys()) {
+            const obj = this.getObject(num);
+            if (obj !== undefined && isStream(obj) && nameOf(get(obj, "Type")) === "EmbeddedFile")
+                out.add(num);
+            const ef = isDict(obj) ? this.resolve(get(obj, "EF")) : undefined;
+            if (ef !== undefined && isDict(ef))
+                for (const ref of ef.map.values())
+                    if (isRef(ref))
+                        out.add(ref.num);
+        }
+        return out;
+    }
     // -------------------------------------------------------------------------------------------
     // Cross-reference index
     // -------------------------------------------------------------------------------------------
@@ -504,7 +595,11 @@ export 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() {
-        return !this.isEncrypted || this.security !== undefined;
+        return !this.isEncrypted || this.security !== undefined || !this.encryptsDocument;
+    }
+    /** Whether streams or strings are enciphered - not the case when only attached files are. */
+    get encryptsDocument() {
+        return this.enciphered === undefined || this.enciphered.streams || this.enciphered.strings;
     }
     /**
      * Encipher a value that is about to be written back INTO this document, or `undefined` when the
@@ -525,7 +620,13 @@ export class PdfDocument {
      * a string happening to be present in whatever we rewrite, which is a guarantee by accident.
      */
     get canReEncrypt() {
-        return !this.isEncrypted || (this.security?.canEncrypt ?? false);
+        if (!this.isEncrypted)
+            return true;
+        // A part left as /Identity must stay in the clear when written back - one handler cannot do both.
+        const e = this.enciphered;
+        if (e && !(e.streams && e.strings && e.files))
+            return false;
+        return this.security?.canEncrypt ?? false;
     }
     /** The generation of an object as the file records it. Members of an object stream are always 0. */
     generationOf(num) {
@@ -550,8 +651,17 @@ export class PdfDocument {
         const end = text.indexOf("endstream", stream.start);
         return this.bytes.subarray(stream.start, end < 0 ? this.bytes.length : end);
     }
-    /** A stream's DECODED bytes: deciphered if the document is encrypted, then run through its filters. */
-    streamData(stream) {
+    /**
+     * 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, strict = false) {
+        if (this.lockedFiles.has(stream.start)) {
+            throw new PdfEncryptedError("this attached file is encrypted on its own; open the PDF with its password to read it", true);
+        }
         // A decrypted payload replaces the bytes from the file; filters then run on the plaintext, which is
         // the order the format prescribes - encryption wraps the already-filtered data.
         const raw = this.plainStreams.get(stream.start) ?? this.rawStream(stream);
@@ -563,36 +673,68 @@ export class PdfDocument {
         const parms = Array.isArray(parmsRaw) ? parmsRaw : [parmsRaw];
         let data = raw;
         filters.forEach((filter, i) => {
-            if (filter === "FlateDecode") {
-                try {
-                    // Per pass, because /Filter is a list and [/FlateDecode /FlateDecode] is a legal nested bomb.
-                    data = inflateBounded(data, this.maxStreamSize);
-                }
-                catch (e) {
-                    // A stream that blew the ceiling is an attack, not a stream we failed to decode - swallowing
-                    // it here would hand back silent garbage.
-                    if (e instanceof PdfStreamTooLargeError)
-                        throw e;
-                    return; // not our data to repair; hand back what we have
+            try {
+                data = this.decodeFilter(filter, data, this.resolve(parms[i]), strict);
+            }
+            catch (e) {
+                // A stream that blew the ceiling is an attack, not a stream we failed to decode - swallowing
+                // it here would hand back silent garbage.
+                if (e instanceof PdfStreamTooLargeError)
+                    throw e;
+                if (strict) {
+                    throw e instanceof PdfFilterError
+                        ? e
+                        : new PdfFilterError(`${filter}: ${String(e?.message ?? e)}`);
                 }
-                data = this.undoPredictor(data, this.resolve(parms[i]));
+                // not our data to repair; the rest is read as it stands
             }
-            // Other filters (LZW, DCT, …) are left encoded on purpose: this reader only needs the structural
-            // streams - the index, object streams and appearances - and every one of those is Flate.
         });
         return data;
     }
+    /**
+     * 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.
+     */
+    decodeFilter(filter, data, parms, strict) {
+        switch (filter) {
+            case "FlateDecode":
+            case "Fl":
+                return this.undoPredictor(inflateBounded(data, this.maxStreamSize), parms, strict);
+            case "LZWDecode":
+            case "LZW":
+                return this.undoPredictor(lzwDecode(data, this.maxStreamSize, numberOf(get(parms, "EarlyChange")) ?? 1), parms, strict);
+            case "ASCIIHexDecode":
+            case "AHx":
+                return asciiHexDecode(data);
+            case "ASCII85Decode":
+            case "A85":
+                return ascii85Decode(data, this.maxStreamSize);
+            case "RunLengthDecode":
+            case "RL":
+                return runLengthDecode(data, this.maxStreamSize);
+            case "Crypt":
+                return data; // deciphering happens once, on open
+            default:
+                if (strict) {
+                    throw new PdfFilterError(`/${filter} decodes to image pixels, not to a file - jasy returns no data it cannot decode`);
+                }
+                return data;
+        }
+    }
     /**
      * 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.
      */
-    undoPredictor(data, parms) {
+    undoPredictor(data, parms, strict = false) {
         const predictor = numberOf(get(parms, "Predictor")) ?? 1;
-        if (predictor < 10)
-            return data; // 1 = none; 2 (TIFF) does not occur in the streams we read
         const colors = numberOf(get(parms, "Colors")) ?? 1;
         const bpc = numberOf(get(parms, "BitsPerComponent")) ?? 8;
         const columns = numberOf(get(parms, "Columns")) ?? 1;
+        if (predictor === 2)
+            return this.undoTiffPredictor(data, colors, bpc, columns, strict);
+        if (predictor < 10)
+            return data; // 1 = none
         const bpp = Math.max(1, Math.ceil((colors * bpc) / 8));
         const rowLen = Math.ceil((colors * bpc * columns) / 8);
         const rows = Math.floor(data.length / (rowLen + 1));
@@ -634,6 +776,21 @@ export class PdfDocument {
         }
         return out;
     }
+    /** TIFF predictor 2: each component is the difference from the one to its left, per row. */
+    undoTiffPredictor(data, colors, bpc, columns, strict) {
+        if (bpc !== 8) {
+            if (strict)
+                throw new PdfFilterError(`TIFF predictor with ${bpc} bits per component`);
+            return data;
+        }
+        const out = Uint8Array.from(data);
+        const rowLen = colors * columns;
+        for (let row = 0; row + rowLen <= out.length; row += rowLen) {
+            for (let i = colors; i < rowLen; i++)
+                out[row + i] = (out[row + i] + out[row + i - colors]) & 0xff;
+        }
+        return out;
+    }
     /** Every object number the index knows, ascending - for walking a whole document. */
     objectNumbers() {
         return [...this.xref.keys()].sort((a, b) => a - b);

package/dist/edit/fill.js

@@ -5,6 +5,7 @@ import { bakeAppearance, bakeButtonStates, fontMetrics, readLook } from "./appea
 import { flattenInto } from "./flatten.js";
 import { getArrayBuffer } from "../utils/utf8-to-windows1252-encoder.js";
 import { get, isDict, isRef } from "./objects.js";
+import { encodePdfText } from "../text/pdf-text-string.js";
 /** Field flags we have to honour when filling (see `forms/acroform.ts` for the writer's side). */
 const FF_READ_ONLY = 1 << 0;
 const FF_MULTI_SELECT = 1 << 21;
@@ -12,23 +13,11 @@ const FF_EDIT = 1 << 18;
 const FF_PUSHBUTTON = 1 << 16;
 const FF_RADIO = 1 << 15;
 /**
- * A text value in PDF form. Plain ASCII becomes a `(literal)`; anything else becomes a UTF-16BE `<hex>`
- * string behind a byte-order mark - the encoding every producer uses for unicode, and the only one that
- * carries an umlaut or an emoji unambiguously. Writing UTF-8 into a literal (the obvious mistake) reads
- * back as mojibake, because a literal is PDFDocEncoded.
+ * A text value in PDF form. Plain ASCII becomes a `(literal)`; anything else becomes `<hex>` of the ONE
+ * text-string encoding the writer uses (`encodePdfText`: PDFDocEncoding, else UTF-16BE with its BOM).
+ * Writing UTF-8 into a literal (the obvious mistake) reads back as mojibake.
  */
-const plainBytes = (s) => {
-    if (/^[\x20-\x7e]*$/.test(s))
-        return Uint8Array.from(s, (c) => c.charCodeAt(0));
-    const out = new Uint8Array(2 + s.length * 2);
-    out[0] = 0xfe;
-    out[1] = 0xff;
-    for (let i = 0; i < s.length; i++) {
-        out[2 + i * 2] = s.charCodeAt(i) >> 8;
-        out[3 + i * 2] = s.charCodeAt(i) & 0xff;
-    }
-    return out;
-};
+const isAscii = (s) => /^[\x20-\x7e]*$/.test(s);
 const hex = (b) => `<${Array.from(b, (x) => x.toString(16).padStart(2, "0").toUpperCase()).join("")}>`;
 /** A value in PDF form. `enciphered` holds ciphertext for the strings of an encrypted document; without
  *  it the value is written in the clear, exactly as before. */
@@ -36,14 +25,10 @@ const pdfText = (s, enciphered) => {
     const ready = enciphered?.get(s);
     if (ready !== undefined)
         return ready;
-    const ascii = /^[\x20-\x7e]*$/.test(s);
-    if (ascii) {
+    if (isAscii(s)) {
         return `(${s.replace(/\\/g, "\\\\").replace(/\(/g, "\\(").replace(/\)/g, "\\)")})`;
     }
-    let out = "FEFF";
-    for (let i = 0; i < s.length; i++)
-        out += s.charCodeAt(i).toString(16).padStart(4, "0").toUpperCase();
-    return `<${out}>`;
+    return hex(encodePdfText(s));
 };
 const escName = (s) => Array.from(new TextEncoder().encode(s))
     .map((b) => b >= 0x21 && b <= 0x7e && !"()<>[]{}/%#".includes(String.fromCharCode(b))
@@ -287,7 +272,7 @@ export async function fillForm(bytes, values, options = {}) {
             for (const text of typeof v === "string" ? [v] : Array.isArray(v) ? v : []) {
                 if (enciphered.has(text))
                     continue;
-                const cipher = await doc.encryptForWrite(plainBytes(text));
+                const cipher = await doc.encryptForWrite(encodePdfText(text));
                 if (cipher)
                     enciphered.set(text, hex(cipher));
             }

package/dist/edit/filters.d.ts

@@ -0,0 +1,15 @@
+/** Thrown when a stream's data is not valid for the filter it declares. */
+export declare class PdfFilterError extends Error {
+    constructor(message: string);
+}
+/** `/ASCIIHexDecode`: hex digits, whitespace ignored, `>` ends it; an odd last digit is followed by 0. */
+export declare function asciiHexDecode(data: Uint8Array): Uint8Array;
+/** `/ASCII85Decode`: groups of five in `!`..`u`, `z` for four zero bytes, `~>` ends it. */
+export declare function ascii85Decode(data: Uint8Array, max: number): Uint8Array;
+/** `/RunLengthDecode`: a length byte, then that many literals (0-127) or one byte repeated (129-255). */
+export declare function runLengthDecode(data: Uint8Array, max: number): Uint8Array;
+/**
+ * `/LZWDecode`: 9 to 12 bit codes, 256 clears the table, 257 ends. `earlyChange` 1 (the default) widens
+ * the code one entry early, as PDF's LZW does; 0 is the textbook variant.
+ */
+export declare function lzwDecode(data: Uint8Array, max: number, earlyChange?: number): Uint8Array;

package/dist/edit/filters.js

@@ -0,0 +1,157 @@
+import { PdfStreamTooLargeError } from "../utils/inflate.js";
+// The standard stream filters besides Flate (which `utils/inflate.ts` decodes). Each one is bounded on
+// what it PRODUCES: LZW and RunLength expand, so a small stream can be a bomb just like a Flate one.
+/** Thrown when a stream's data is not valid for the filter it declares. */
+export class PdfFilterError extends Error {
+    constructor(message) {
+        super(`@jasy/pdf: ${message}`);
+    }
+}
+const tooLarge = (max) => new PdfStreamTooLargeError(max, `a stream in this PDF expands past the ${max} byte limit for a single stream; if the file is ` +
+    `genuinely that large, raise it with { maxStreamSize }`);
+/** `/ASCIIHexDecode`: hex digits, whitespace ignored, `>` ends it; an odd last digit is followed by 0. */
+export function asciiHexDecode(data) {
+    const out = [];
+    let high = -1;
+    for (const c of data) {
+        if (c === 0x3e)
+            break; // ">"
+        if (c === 0x20 || (c >= 0x09 && c <= 0x0d) || c === 0x00)
+            continue;
+        const v = c >= 0x30 && c <= 0x39
+            ? c - 0x30
+            : c >= 0x41 && c <= 0x46
+                ? c - 55
+                : c >= 0x61 && c <= 0x66
+                    ? c - 87
+                    : -1;
+        if (v < 0)
+            throw new PdfFilterError(`ASCIIHexDecode: "${String.fromCharCode(c)}" is not a hex digit`);
+        if (high < 0)
+            high = v;
+        else {
+            out.push((high << 4) | v);
+            high = -1;
+        }
+    }
+    if (high >= 0)
+        out.push(high << 4);
+    return Uint8Array.from(out);
+}
+/** `/ASCII85Decode`: groups of five in `!`..`u`, `z` for four zero bytes, `~>` ends it. */
+export function ascii85Decode(data, max) {
+    const out = [];
+    const group = [];
+    const flush = (count) => {
+        let n = 0;
+        for (let i = 0; i < 5; i++)
+            n = n * 85 + (group[i] ?? 84);
+        if (n > 0xffffffff)
+            throw new PdfFilterError("ASCII85Decode: a group decodes past 32 bits");
+        for (let i = 0; i < count - 1; i++)
+            out.push((n >>> (24 - 8 * i)) & 0xff);
+        group.length = 0;
+        if (out.length > max)
+            throw tooLarge(max);
+    };
+    for (let i = 0; i < data.length; i++) {
+        const c = data[i];
+        if (c === 0x7e)
+            break; // "~", the start of "~>"
+        if (c === 0x20 || (c >= 0x09 && c <= 0x0d) || c === 0x00)
+            continue;
+        if (c === 0x7a && group.length === 0) {
+            out.push(0, 0, 0, 0); // "z"
+            if (out.length > max)
+                throw tooLarge(max);
+            continue;
+        }
+        if (c < 0x21 || c > 0x75) {
+            throw new PdfFilterError(`ASCII85Decode: "${String.fromCharCode(c)}" is outside the alphabet`);
+        }
+        group.push(c - 33);
+        if (group.length === 5)
+            flush(5);
+    }
+    if (group.length === 1)
+        throw new PdfFilterError("ASCII85Decode: a final group of one character");
+    if (group.length > 0)
+        flush(group.length);
+    return Uint8Array.from(out);
+}
+/** `/RunLengthDecode`: a length byte, then that many literals (0-127) or one byte repeated (129-255). */
+export function runLengthDecode(data, max) {
+    const out = [];
+    let i = 0;
+    while (i < data.length) {
+        const len = data[i++];
+        if (len === 128)
+            break;
+        if (len < 128) {
+            if (i + len + 1 > data.length)
+                throw new PdfFilterError("RunLengthDecode: data ends inside a run");
+            for (let k = 0; k <= len; k++)
+                out.push(data[i + k]);
+            i += len + 1;
+        }
+        else {
+            if (i >= data.length)
+                throw new PdfFilterError("RunLengthDecode: data ends inside a run");
+            for (let k = 0; k < 257 - len; k++)
+                out.push(data[i]);
+            i += 1;
+        }
+        if (out.length > max)
+            throw tooLarge(max);
+    }
+    return Uint8Array.from(out);
+}
+/**
+ * `/LZWDecode`: 9 to 12 bit codes, 256 clears the table, 257 ends. `earlyChange` 1 (the default) widens
+ * the code one entry early, as PDF's LZW does; 0 is the textbook variant.
+ */
+export function lzwDecode(data, max, earlyChange = 1) {
+    const out = [];
+    let table = [];
+    let width = 9;
+    let prev;
+    const reset = () => {
+        table = Array.from({ length: 258 }, (_, i) => Uint8Array.of(i));
+        width = 9;
+        prev = undefined;
+    };
+    reset();
+    let bitPos = 0;
+    const totalBits = data.length * 8;
+    while (bitPos + width <= totalBits) {
+        let code = 0;
+        for (let b = 0; b < width; b++) {
+            const bit = (data[(bitPos + b) >> 3] >> (7 - ((bitPos + b) & 7))) & 1;
+            code = (code << 1) | bit;
+        }
+        bitPos += width;
+        if (code === 256) {
+            reset();
+            continue;
+        }
+        if (code === 257)
+            break;
+        let entry;
+        if (code < table.length)
+            entry = table[code];
+        else if (code === table.length && prev)
+            entry = Uint8Array.from([...prev, prev[0]]);
+        else
+            throw new PdfFilterError(`LZWDecode: code ${code} is not in the table`);
+        for (const b of entry)
+            out.push(b);
+        if (out.length > max)
+            throw tooLarge(max);
+        if (prev)
+            table.push(Uint8Array.from([...prev, entry[0]]));
+        prev = entry;
+        if (table.length + earlyChange >= 1 << width && width < 12)
+            width++;
+    }
+    return Uint8Array.from(out);
+}

package/dist/edit/index.d.ts

@@ -5,11 +5,14 @@
  * that only generates should not carry it - the same reason jimp is kept out of the text path. Importing
  * `@jasy/pdf` alone pulls in none of this.
  *
- * The scope is deliberately narrow: AcroForm fields, and nothing else. This is not a PDF editor. What we
+ * The scope is deliberately narrow: AcroForm fields and attachments, nothing else. This is not a PDF editor. What we
  * do not understand, we leave untouched, and what we cannot do safely we refuse by name.
  */
 export { readAcroForm } from "./acroform-reader.js";
 export type { ReadField, ReadForm, ReadWidget } from "./acroform-reader.js";
+export { readAttachments, AttachmentError } from "./attachments.js";
+export type { Attachment, AttachmentLocation } from "./attachments.js";
+export { PdfFilterError } from "./filters.js";
 export { fillForm, FillError } from "./fill.js";
 export { flattenForm, FlattenError } from "./flatten.js";
 export type { FlattenOptions, FlattenResult } from "./flatten.js";

package/dist/edit/index.js

@@ -5,10 +5,12 @@
  * that only generates should not carry it - the same reason jimp is kept out of the text path. Importing
  * `@jasy/pdf` alone pulls in none of this.
  *
- * The scope is deliberately narrow: AcroForm fields, and nothing else. This is not a PDF editor. What we
+ * The scope is deliberately narrow: AcroForm fields and attachments, nothing else. This is not a PDF editor. What we
  * do not understand, we leave untouched, and what we cannot do safely we refuse by name.
  */
 export { readAcroForm } from "./acroform-reader.js";
+export { readAttachments, AttachmentError } from "./attachments.js";
+export { PdfFilterError } from "./filters.js";
 export { fillForm, FillError } from "./fill.js";
 export { flattenForm, FlattenError } from "./flatten.js";
 // The document itself, for callers who want to look further than the form.