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

package/dist/common/color.js

@@ -1,7 +1,4 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Color = void 0;
-class Color {
+export class Color {
     constructor(r, g, b, alpha = 1) {
         this.r = this.clampColorValue(r, "r");
         this.g = this.clampColorValue(g, "g");
@@ -59,4 +56,3 @@ class Color {
         return `${(r / 255).toFixed(3)} ${(g / 255).toFixed(3)} ${(b / 255).toFixed(3)}`;
     }
 }
-exports.Color = Color;

package/dist/constants/page-sizes.js

@@ -1,8 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.pageFormats = exports.PageSize = void 0;
 // Definition of all possible page sizes
-var PageSize;
+export var PageSize;
 (function (PageSize) {
     PageSize["A0"] = "a0";
     PageSize["A1"] = "a1";
@@ -45,9 +42,9 @@ var PageSize;
     PageSize["LEDGER"] = "ledger";
     PageSize["TABLOID"] = "tabloid";
     PageSize["CREDIT_CARD"] = "credit-card";
-})(PageSize || (exports.PageSize = PageSize = {}));
+})(PageSize || (PageSize = {}));
 // Definition of page formats
-exports.pageFormats = {
+export const pageFormats = {
     [PageSize.A0]: [2383.94, 3370.39],
     [PageSize.A1]: [1683.78, 2383.94],
     [PageSize.A2]: [1190.55, 1683.78],

package/dist/constants/pdf-parts.js

@@ -1,7 +1,4 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PDF_PARTS = void 0;
-exports.PDF_PARTS = {
+export const PDF_PARTS = {
     HEADER: "%PDF-1.3",
     TRAILER: (size) => `trailer\n<< /Size ${size} >>\nstartxref\n%%EOF`,
     XREF: "xref", // Placeholder for xref elements

package/dist/crypto/legacy-handler.d.ts

@@ -0,0 +1,43 @@
+import type { SecurityHandler } from "./security-handler.js";
+/** RC4. Not available in WebCrypto - for good reasons - so it is written out here, for reading only. */
+declare function rc4(key: Uint8Array, data: Uint8Array): Uint8Array;
+/** What the `/Encrypt` dictionary tells us, already parsed by the reader. */
+export interface LegacyEncryptInfo {
+    revision: number;
+    /** `/Length` in BITS (default 40). */
+    keyBits: number;
+    o: Uint8Array;
+    u: Uint8Array;
+    /** `/P`, the permission flags, as the signed 32-bit value the algorithm feeds in. */
+    permissions: number;
+    /** The first string of the document `/ID`. */
+    id: Uint8Array;
+    encryptMetadata: boolean;
+    /** True when the crypt filter is AESV2 rather than RC4. */
+    aes: boolean;
+}
+export declare class StandardLegacy implements SecurityHandler {
+    private readonly fileKey;
+    private readonly aes;
+    private constructor();
+    readonly canEncrypt = false;
+    encryptDict(): string;
+    encrypt(): Promise<Uint8Array>;
+    decrypt(data: Uint8Array, ref?: {
+        num: number;
+        gen: number;
+    }): Promise<Uint8Array>;
+    /**
+     * Algorithm 1: every object is enciphered with its own key, derived from the file key plus the
+     * object's number and generation. Miss this and every single object decrypts to noise.
+     */
+    private objectKey;
+    /**
+     * Open a legacy-encrypted document: derive the file key from the password (algorithm 2), then CHECK it
+     * against `/U` (algorithm 6) so a wrong password is rejected rather than silently producing noise.
+     */
+    static open(password: string, info: LegacyEncryptInfo): SecurityHandler;
+    /** Algorithm 6: rebuild what `/U` must look like for this key and compare. */
+    private static passwordMatches;
+}
+export { rc4 };

package/dist/crypto/legacy-handler.js

@@ -0,0 +1,145 @@
+import { aesCbcDecrypt } from "./webcrypto.js";
+import { md5 } from "../utils/md5.js";
+/**
+ * The OLDER standard security handlers, for READING only: R2 and R3 (RC4, 40 and 128 bit) and R4
+ * (RC4 or AES-128).
+ *
+ * Read-only is a deliberate asymmetry, not an omission. RC4 is broken - biased keystream, and R2 uses a
+ * 40-bit key that is brute-forced in minutes - and PDF 2.0 removed it outright. But it is what PDFKit,
+ * react-pdf and Ghostscript still produce BY DEFAULT when you ask them for a password, so refusing to
+ * open such a file means refusing most of the encrypted PDFs anyone actually has. Writing one would be
+ * a different matter: offering a user "protection" we know to be broken helps nobody, so `encrypt`
+ * here throws.
+ *
+ * Two things distinguish these revisions from the modern R6:
+ * - the file key comes from MD5 over the password, `/O`, `/P` and the first `/ID` string (algorithm 2);
+ * - every object gets its OWN key, derived from the file key plus its number and generation
+ *   (algorithm 1). That is why `SecurityHandler.encrypt/decrypt` take a `ref`.
+ */
+/** The padding every legacy revision prepends to a password (algorithm 2, step a). */
+const PAD = new Uint8Array([
+    0x28, 0xbf, 0x4e, 0x5e, 0x4e, 0x75, 0x8a, 0x41, 0x64, 0x00, 0x4e, 0x56, 0xff, 0xfa, 0x01, 0x08,
+    0x2e, 0x2e, 0x00, 0xb6, 0xd0, 0x68, 0x3e, 0x80, 0x2f, 0x0c, 0xa9, 0xfe, 0x64, 0x53, 0x69, 0x7a,
+]);
+/** A password padded (or truncated) to the 32 bytes the algorithm wants. */
+function padPassword(password) {
+    const pw = new Uint8Array(32);
+    // Latin-1: the legacy handlers predate unicode passwords entirely.
+    const raw = Uint8Array.from(password, (c) => c.charCodeAt(0) & 0xff);
+    const take = Math.min(raw.length, 32);
+    pw.set(raw.subarray(0, take), 0);
+    pw.set(PAD.subarray(0, 32 - take), take);
+    return pw;
+}
+/** RC4. Not available in WebCrypto - for good reasons - so it is written out here, for reading only. */
+function rc4(key, data) {
+    const s = new Uint8Array(256);
+    for (let i = 0; i < 256; i++)
+        s[i] = i;
+    for (let i = 0, j = 0; i < 256; i++) {
+        j = (j + s[i] + key[i % key.length]) & 0xff;
+        [s[i], s[j]] = [s[j], s[i]];
+    }
+    const out = new Uint8Array(data.length);
+    for (let k = 0, i = 0, j = 0; k < data.length; k++) {
+        i = (i + 1) & 0xff;
+        j = (j + s[i]) & 0xff;
+        [s[i], s[j]] = [s[j], s[i]];
+        out[k] = data[k] ^ s[(s[i] + s[j]) & 0xff];
+    }
+    return out;
+}
+const concat = (...parts) => {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const p of parts) {
+        out.set(p, at);
+        at += p.length;
+    }
+    return out;
+};
+export class StandardLegacy {
+    constructor(fileKey, aes) {
+        this.fileKey = fileKey;
+        this.aes = aes;
+        this.canEncrypt = false;
+    }
+    encryptDict() {
+        throw new Error("@jasy/pdf: this handler only READS legacy encryption; jasy writes AES-256 (R6) exclusively");
+    }
+    async encrypt() {
+        throw new Error("@jasy/pdf: refusing to write RC4 or AES-128 - they are obsolete; jasy writes AES-256 (R6)");
+    }
+    async decrypt(data, ref) {
+        const key = this.objectKey(ref);
+        if (!this.aes)
+            return rc4(key, data);
+        if (data.length <= 16)
+            return new Uint8Array(0); // an IV and nothing else
+        return aesCbcDecrypt(key, data.subarray(0, 16), data.subarray(16));
+    }
+    /**
+     * Algorithm 1: every object is enciphered with its own key, derived from the file key plus the
+     * object's number and generation. Miss this and every single object decrypts to noise.
+     */
+    objectKey(ref) {
+        const num = ref?.num ?? 0;
+        const gen = ref?.gen ?? 0;
+        const extra = new Uint8Array(this.aes ? 9 : 5);
+        extra[0] = num & 0xff;
+        extra[1] = (num >> 8) & 0xff;
+        extra[2] = (num >> 16) & 0xff;
+        extra[3] = gen & 0xff;
+        extra[4] = (gen >> 8) & 0xff;
+        // AES adds the literal "sAlT" - the spec really does spell it that way.
+        if (this.aes)
+            extra.set([0x73, 0x41, 0x6c, 0x54], 5);
+        const digest = md5(concat(this.fileKey, extra));
+        return digest.subarray(0, Math.min(this.fileKey.length + 5, 16));
+    }
+    /**
+     * Open a legacy-encrypted document: derive the file key from the password (algorithm 2), then CHECK it
+     * against `/U` (algorithm 6) so a wrong password is rejected rather than silently producing noise.
+     */
+    static open(password, info) {
+        const keyLength = info.revision === 2 ? 5 : Math.max(5, Math.floor(info.keyBits / 8));
+        const p = new Uint8Array(4);
+        new DataView(p.buffer).setInt32(0, info.permissions, true); // little-endian, signed
+        let input = concat(padPassword(password), info.o.subarray(0, 32), p, info.id);
+        // R4 with /EncryptMetadata false folds in four 0xFF bytes.
+        if (info.revision >= 4 && !info.encryptMetadata) {
+            input = concat(input, new Uint8Array([0xff, 0xff, 0xff, 0xff]));
+        }
+        let key = md5(input);
+        if (info.revision >= 3) {
+            // 50 further rounds over the first keyLength bytes only.
+            for (let i = 0; i < 50; i++)
+                key = md5(key.subarray(0, keyLength));
+        }
+        key = key.subarray(0, keyLength);
+        if (!StandardLegacy.passwordMatches(key, info)) {
+            throw new Error("@jasy/pdf: wrong password.");
+        }
+        return new StandardLegacy(key, info.aes);
+    }
+    /** Algorithm 6: rebuild what `/U` must look like for this key and compare. */
+    static passwordMatches(key, info) {
+        if (info.revision === 2) {
+            const expect = rc4(key, PAD);
+            return expect.every((b, i) => b === info.u[i]);
+        }
+        // R3+ : MD5 over the padding and the /ID, then 20 rounds of RC4 with the key XORed by the round.
+        let x = md5(concat(PAD, info.id));
+        x = rc4(key, x);
+        for (let round = 1; round <= 19; round++) {
+            const rk = Uint8Array.from(key, (b) => b ^ round);
+            x = rc4(rk, x);
+        }
+        // Only the first 16 bytes are meaningful; the rest of /U is arbitrary padding.
+        for (let i = 0; i < 16; i++)
+            if (x[i] !== info.u[i])
+                return false;
+        return true;
+    }
+}
+export { rc4 };

package/dist/crypto/security-handler.d.ts

@@ -0,0 +1,62 @@
+/** A handler encrypts/decrypts the strings + streams of a document and describes itself as an `/Encrypt` dict. */
+export interface SecurityHandler {
+    /** Whether this scheme may be WRITTEN. False for the legacy revisions: we open them as a service to
+     *  files that already exist, but handing a user protection known to be broken is not one. */
+    readonly canEncrypt: boolean;
+    /** The `/Encrypt` dictionary body (between `<<` and `>>`). Its own strings are never encrypted. */
+    encryptDict(): string;
+    /** Encrypt one string/stream. `ref` is unused for V5/R6 (one file key) but kept for future per-object schemes. */
+    encrypt(data: Uint8Array, ref?: {
+        num: number;
+        gen: number;
+    }): Promise<Uint8Array>;
+    /** Decrypt one string/stream (the groundwork the future "open/edit existing PDF" path reuses). */
+    decrypt(data: Uint8Array, ref?: {
+        num: number;
+        gen: number;
+    }): Promise<Uint8Array>;
+}
+/** What the user grants; everything defaults to allowed. Maps to the `/P` bitfield (ISO 32000-2 Table 22). */
+export interface Permissions {
+    printing?: boolean;
+    copying?: boolean;
+    modifying?: boolean;
+    annotating?: boolean;
+}
+export interface EncryptOptions {
+    /** Only "aes-256" today - the seam for future algorithms. */
+    algorithm?: "aes-256";
+    userPassword: string;
+    /** Full-rights password; defaults to the user password if omitted. */
+    ownerPassword?: string;
+    permissions?: Permissions;
+}
+declare class StandardAes256 implements SecurityHandler {
+    private readonly fileKey;
+    private readonly dict;
+    private constructor();
+    static create(opts: EncryptOptions): Promise<StandardAes256>;
+    readonly canEncrypt = true;
+    encryptDict(): string;
+    encrypt(data: Uint8Array): Promise<Uint8Array>;
+    decrypt(data: Uint8Array): Promise<Uint8Array>;
+    /** Recover the file key from a password as a reader does: validate it against /U FIRST (so a wrong
+     *  password is rejected, not silently turned into a garbage key), then decrypt /UE. The groundwork the
+     *  future "open/edit existing PDF" path reuses. Throws on a wrong password. */
+    static recoverFileKey(userPassword: string, u: Uint8Array, ue: Uint8Array): Promise<Uint8Array>;
+    /**
+     * A handler for READING an existing file: recover its key from the password, then decrypt with it.
+     * The `/Encrypt` dictionary is the file's own, so this handler never has to describe one.
+     *
+     * `revision` 6 is the standard (ISO 32000-2). Revision **5** is Adobe's withdrawn 2008 extension and
+     * differs in ONE respect: the key is a plain SHA-256 of password + salt, without the iterated
+     * procedure of algorithm 2.B. The cipher is the same AES-256, which is why supporting it costs almost
+     * nothing - and it matters, because PDFKit and react-pdf both emit R5 when asked for AES.
+     */
+    static forReading(userPassword: string, u: Uint8Array, ue: Uint8Array, revision?: 5 | 6): Promise<SecurityHandler>;
+    /** Revision 5: validate against /U with a single SHA-256, then unwrap /UE the same way R6 does. */
+    private static recoverFileKeyR5;
+}
+/** The factory = the seam. Today it always returns the AES-256 handler. */
+export declare function createSecurityHandler(opts: EncryptOptions): Promise<SecurityHandler>;
+export { StandardAes256 };

package/dist/crypto/security-handler.js

@@ -0,0 +1,155 @@
+// PDF Standard security handler. The PDFObjectManager talks to the `SecurityHandler` interface, never to a
+// concrete algorithm - so adding another scheme later (a new revision, or per-object RC4/AES-128) is just a
+// second implementation + a factory branch, with the writer untouched. Today we ship exactly one:
+// `StandardAes256` = AES-256, V5/R6 (ISO 32000-2 / PDF 2.0), the newest standard PDF encryption.
+import { aesCbcDecrypt, aesCbcDecryptNoPad, aesCbcEncrypt, aesCbcEncryptNoPad, randomBytes, sha, } from "./webcrypto.js";
+const utf8 = (s) => new TextEncoder().encode(s).subarray(0, 127); // R6 truncates passwords to 127 bytes
+const concat = (...parts) => {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let o = 0;
+    for (const p of parts) {
+        out.set(p, o);
+        o += p.length;
+    }
+    return out;
+};
+const toHex = (a) => [...a].map((b) => b.toString(16).padStart(2, "0")).join("");
+// Constant-time-ish equality for password validation (no early-out on the first differing byte).
+const bytesEqual = (a, b) => {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+};
+// ISO 32000-2 Algorithm 2.B: the hardened password hash. Loops AES-128-CBC + SHA-256/384/512 until the
+// stopping rule. `udata` is the 48-byte /U for the owner computations, empty for the user ones.
+async function hash2B(password, salt, udata) {
+    let k = await sha(256, concat(password, salt, udata));
+    let e = new Uint8Array(0);
+    // At least 64 rounds; then stop once the last byte of E <= round - 32 (ISO 32000-2 Algorithm 2.B).
+    for (let round = 0; round < 64 || e[e.length - 1] > round - 32; round++) {
+        const block = concat(password, k, udata);
+        const k1 = new Uint8Array(block.length * 64);
+        for (let i = 0; i < 64; i++)
+            k1.set(block, i * block.length);
+        e = await aesCbcEncryptNoPad(k.subarray(0, 16), k.subarray(16, 32), k1);
+        let sum = 0;
+        for (let i = 0; i < 16; i++)
+            sum += e[i]; // big-endian 128-bit mod 3 == byte-sum mod 3 (256 ≡ 1 mod 3)
+        k = await sha([256, 384, 512][sum % 3], e);
+    }
+    return k.subarray(0, 32);
+}
+function permissionBits(p = {}) {
+    const { printing = true, copying = true, modifying = true, annotating = true } = p;
+    let bits = 0xfffff000 | 0b11000000; // reserved-1 bits (positions 7-8 and 13-32)
+    if (printing)
+        bits |= 4 | 2048;
+    if (modifying)
+        bits |= 8 | 1024;
+    if (copying)
+        bits |= 16 | 512;
+    if (annotating)
+        bits |= 32 | 256;
+    return bits | 0; // int32
+}
+class StandardAes256 {
+    constructor(fileKey, dict) {
+        this.fileKey = fileKey;
+        this.dict = dict;
+        this.canEncrypt = true;
+    }
+    static async create(opts) {
+        const user = utf8(opts.userPassword);
+        const owner = utf8(opts.ownerPassword ?? opts.userPassword);
+        const fileKey = randomBytes(32);
+        const p = permissionBits(opts.permissions);
+        // Algorithm 8: /U and /UE.
+        const uVS = randomBytes(8);
+        const uKS = randomBytes(8);
+        const empty = new Uint8Array(0);
+        const u = concat(await hash2B(user, uVS, empty), uVS, uKS); // 48 bytes
+        const ue = await aesCbcEncryptNoPad(await hash2B(user, uKS, empty), new Uint8Array(16), fileKey);
+        // Algorithm 9: /O and /OE (these also fold in /U).
+        const oVS = randomBytes(8);
+        const oKS = randomBytes(8);
+        const o = concat(await hash2B(owner, oVS, u), oVS, oKS); // 48 bytes
+        const oe = await aesCbcEncryptNoPad(await hash2B(owner, oKS, u), new Uint8Array(16), fileKey);
+        // Algorithm 10: /Perms (a 16-byte block, ECB == single-block CBC with a zero IV).
+        const perms = new Uint8Array(16);
+        perms[0] = p & 0xff;
+        perms[1] = (p >> 8) & 0xff;
+        perms[2] = (p >> 16) & 0xff;
+        perms[3] = (p >> 24) & 0xff;
+        perms[4] = perms[5] = perms[6] = perms[7] = 0xff;
+        perms[8] = 0x46; // 'F' - metadata (XMP) stays unencrypted (standard; keeps it indexer-readable)
+        perms[9] = 0x61; // 'a'
+        perms[10] = 0x64; // 'd'
+        perms[11] = 0x62; // 'b'
+        perms.set(randomBytes(4), 12);
+        const permsEnc = await aesCbcEncryptNoPad(fileKey, new Uint8Array(16), perms);
+        const dict = `/Filter /Standard /V 5 /R 6 /Length 256 /P ${p} /EncryptMetadata false ` +
+            `/CF << /StdCF << /CFM /AESV3 /AuthEvent /DocOpen /Length 32 >> >> /StmF /StdCF /StrF /StdCF ` +
+            `/U <${toHex(u)}> /UE <${toHex(ue)}> /O <${toHex(o)}> /OE <${toHex(oe)}> /Perms <${toHex(permsEnc)}>`;
+        return new StandardAes256(fileKey, dict);
+    }
+    encryptDict() {
+        return this.dict;
+    }
+    async encrypt(data) {
+        const iv = randomBytes(16);
+        const ct = await aesCbcEncrypt(this.fileKey, iv, data);
+        return concat(iv, ct);
+    }
+    async decrypt(data) {
+        return aesCbcDecrypt(this.fileKey, data.subarray(0, 16), data.subarray(16));
+    }
+    /** Recover the file key from a password as a reader does: validate it against /U FIRST (so a wrong
+     *  password is rejected, not silently turned into a garbage key), then decrypt /UE. The groundwork the
+     *  future "open/edit existing PDF" path reuses. Throws on a wrong password. */
+    static async recoverFileKey(userPassword, u, ue) {
+        const pw = utf8(userPassword);
+        // Algorithm 11: hash(password + validation salt) must equal the first 32 bytes of /U.
+        const check = await hash2B(pw, u.subarray(32, 40), new Uint8Array(0));
+        if (!bytesEqual(check, u.subarray(0, 32))) {
+            throw new Error("@jasy/pdf: wrong password.");
+        }
+        const intermediate = await hash2B(pw, u.subarray(40, 48), new Uint8Array(0));
+        return aesCbcDecryptNoPad(intermediate, new Uint8Array(16), ue);
+    }
+    /**
+     * A handler for READING an existing file: recover its key from the password, then decrypt with it.
+     * The `/Encrypt` dictionary is the file's own, so this handler never has to describe one.
+     *
+     * `revision` 6 is the standard (ISO 32000-2). Revision **5** is Adobe's withdrawn 2008 extension and
+     * differs in ONE respect: the key is a plain SHA-256 of password + salt, without the iterated
+     * procedure of algorithm 2.B. The cipher is the same AES-256, which is why supporting it costs almost
+     * nothing - and it matters, because PDFKit and react-pdf both emit R5 when asked for AES.
+     */
+    static async forReading(userPassword, u, ue, revision = 6) {
+        const key = revision === 6
+            ? await StandardAes256.recoverFileKey(userPassword, u, ue)
+            : await StandardAes256.recoverFileKeyR5(userPassword, u, ue);
+        return new StandardAes256(key, "");
+    }
+    /** Revision 5: validate against /U with a single SHA-256, then unwrap /UE the same way R6 does. */
+    static async recoverFileKeyR5(userPassword, u, ue) {
+        const pw = utf8(userPassword);
+        const check = await sha(256, concat(pw, u.subarray(32, 40)));
+        if (!bytesEqual(check, u.subarray(0, 32))) {
+            throw new Error("@jasy/pdf: wrong password.");
+        }
+        const intermediate = await sha(256, concat(pw, u.subarray(40, 48)));
+        return aesCbcDecryptNoPad(intermediate, new Uint8Array(16), ue);
+    }
+}
+/** The factory = the seam. Today it always returns the AES-256 handler. */
+export async function createSecurityHandler(opts) {
+    if (opts.algorithm && opts.algorithm !== "aes-256") {
+        throw new Error(`@jasy/pdf: unsupported encryption algorithm "${opts.algorithm}" (only "aes-256").`);
+    }
+    return StandardAes256.create(opts);
+}
+export { StandardAes256 };

package/dist/crypto/webcrypto.d.ts

@@ -0,0 +1,11 @@
+export declare function randomBytes(n: number): Uint8Array;
+export declare function sha(bits: 256 | 384 | 512, data: Uint8Array): Promise<Uint8Array>;
+/** AES-CBC with PKCS#7 padding (the AESV3 mode for PDF strings/streams). */
+export declare function aesCbcEncrypt(key: Uint8Array, iv: Uint8Array, data: Uint8Array): Promise<Uint8Array>;
+export declare function aesCbcDecrypt(key: Uint8Array, iv: Uint8Array, data: Uint8Array): Promise<Uint8Array>;
+/** AES-CBC WITHOUT padding (`data.length` must be a multiple of 16). WebCrypto pads unconditionally, so we
+ *  encrypt and drop the extra full pad block - the leading blocks are the true unpadded CBC. */
+export declare function aesCbcEncryptNoPad(key: Uint8Array, iv: Uint8Array, data: Uint8Array): Promise<Uint8Array>;
+/** AES-CBC no-padding DECRYPT (`data` a multiple of 16). We append one cipher block crafted to decrypt to a
+ *  full 0x10 PKCS#7 pad (so WebCrypto accepts and strips it), leaving the original. */
+export declare function aesCbcDecryptNoPad(key: Uint8Array, iv: Uint8Array, data: Uint8Array): Promise<Uint8Array>;

package/dist/crypto/webcrypto.js

@@ -0,0 +1,62 @@
+// Isomorphic crypto via the platform WebCrypto (`globalThis.crypto.subtle`) - native in the browser AND in
+// Node 20+, with zero dependencies. This is the primitive layer the PDF Standard security handler (AES-256,
+// R6) builds on. Everything is async (so is `render()`), so that is no constraint.
+//
+// One wrinkle: WebCrypto's AES-CBC ALWAYS applies PKCS#7 padding and offers no raw/no-pad mode. The PDF R6
+// key derivation (Algorithm 2.B, /UE, /OE, /Perms) needs UNPADDED AES, so we synthesize it from the padded
+// primitive (encrypt: drop the trailing pad block; decrypt: append a block that decrypts to a full pad, then
+// let WebCrypto strip it). Document strings/streams use the padded primitive directly - that IS AESV3.
+const subtle = () => {
+    const c = globalThis.crypto;
+    if (!c?.subtle) {
+        throw new Error("@jasy/pdf: PDF encryption needs WebCrypto (globalThis.crypto.subtle), unavailable here.");
+    }
+    return c.subtle;
+};
+export function randomBytes(n) {
+    const b = new Uint8Array(n);
+    globalThis.crypto.getRandomValues(b);
+    return b;
+}
+// WebCrypto's types want a BufferSource backed by ArrayBuffer; our Uint8Arrays are ArrayBuffer-backed, so
+// this cast at the platform boundary is safe (TS 5.7+ just can't prove it isn't a SharedArrayBuffer).
+const buf = (a) => a;
+export async function sha(bits, data) {
+    return new Uint8Array(await subtle().digest(`SHA-${bits}`, buf(data)));
+}
+async function aesKey(key, usage) {
+    return subtle().importKey("raw", buf(key), { name: "AES-CBC" }, false, [usage]);
+}
+/** AES-CBC with PKCS#7 padding (the AESV3 mode for PDF strings/streams). */
+export async function aesCbcEncrypt(key, iv, data) {
+    return new Uint8Array(await subtle().encrypt({ name: "AES-CBC", iv: buf(iv) }, await aesKey(key, "encrypt"), buf(data)));
+}
+export async function aesCbcDecrypt(key, iv, data) {
+    return new Uint8Array(await subtle().decrypt({ name: "AES-CBC", iv: buf(iv) }, await aesKey(key, "decrypt"), buf(data)));
+}
+/** AES-CBC WITHOUT padding (`data.length` must be a multiple of 16). WebCrypto pads unconditionally, so we
+ *  encrypt and drop the extra full pad block - the leading blocks are the true unpadded CBC. */
+export async function aesCbcEncryptNoPad(key, iv, data) {
+    if (data.length % 16 !== 0)
+        throw new Error("aesCbcEncryptNoPad: data must be a multiple of 16 bytes.");
+    return (await aesCbcEncrypt(key, iv, data)).subarray(0, data.length);
+}
+const xor16 = (a, b) => {
+    const o = new Uint8Array(16);
+    for (let i = 0; i < 16; i++)
+        o[i] = a[i] ^ b[i];
+    return o;
+};
+/** AES-CBC no-padding DECRYPT (`data` a multiple of 16). We append one cipher block crafted to decrypt to a
+ *  full 0x10 PKCS#7 pad (so WebCrypto accepts and strips it), leaving the original. */
+export async function aesCbcDecryptNoPad(key, iv, data) {
+    if (data.length === 0 || data.length % 16 !== 0)
+        throw new Error("aesCbcDecryptNoPad: data must be a non-zero multiple of 16 bytes.");
+    const prev = data.length >= 16 ? data.subarray(data.length - 16) : iv;
+    // ECB(x) == first block of CBC(iv=0, x); we want the appended block to decrypt to 0x10*16 after the CBC xor.
+    const appended = await aesCbcEncryptNoPad(key, new Uint8Array(16), xor16(new Uint8Array(16).fill(16), prev));
+    const withPad = new Uint8Array(data.length + 16);
+    withPad.set(data);
+    withPad.set(appended, data.length);
+    return aesCbcDecrypt(key, iv, withPad);
+}

package/dist/edit/acroform-reader.d.ts

@@ -0,0 +1,70 @@
+import { type PdfDocument } from "./document.js";
+/**
+ * Reads an existing document's `/AcroForm` into a flat list of fields.
+ *
+ * The field tree is the part every producer lays out differently, and where a naive reader goes wrong:
+ *
+ * - **A field and its widget need not be the same object.** pdf-lib splits them (the field carries
+ *   `/T`, `/FT` and `/V`; its `/Kids` are bare widget annotations); PDFKit and our own writer merge
+ *   them into one. Both are legal, so the walk must cope with either.
+ * - **Attributes are inherited.** `/FT`, `/Ff`, `/V` and `/MaxLen` all pass down the tree, so a child may
+ *   state none of them and still have a type, flags and a value (ISO 32000-1 table 220).
+ * - **Names are hierarchical.** The name you address a field by is the `/T` values along the path,
+ *   joined with dots - `address.street`, not `street`.
+ * - **A field may own several widgets** (a radio group, or one field shown on several pages). It is
+ *   still ONE field with one value.
+ */
+/** One field found in an existing document, in the terms a caller thinks in. */
+export interface ReadField {
+    /** The fully qualified name: the `/T` values from the root down, joined with dots. */
+    name: string;
+    /** `Tx` text · `Btn` button (check box, radio, push button) · `Ch` choice · `Sig` signature. */
+    type: "Tx" | "Btn" | "Ch" | "Sig";
+    /** The current value as text, if it has one. A button's value is a name (`Yes`, `Off`). */
+    value?: string;
+    /** A multi-select choice field's values. */
+    values?: string[];
+    /** The `/Ff` field flags, already merged with anything inherited. */
+    flags: number;
+    /** `/MaxLen`: the longest text the field accepts, in characters. Inherited like the type. */
+    maxLen?: number;
+    /** The selectable options of a choice field, as `[export, label]`. */
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** For a check box or radio group: every export name its widgets can take, besides `Off`. */
+    onValues?: string[];
+    /** The object number of the FIELD dictionary - where `/V` lives, and what an update rewrites. */
+    objNum?: number;
+    /** The widgets that display this field. A radio group has one per button, and each knows only its
+     *  OWN export name, which is what its `/AS` has to be set to. */
+    widgets: ReadWidget[];
+    /** True when no widget carries an appearance stream - filling it means generating one. */
+    needsAppearance: boolean;
+}
+/** One widget annotation belonging to a field. */
+export interface ReadWidget {
+    num?: number;
+    /** The export names this particular widget can show (its `/AP /N` keys, minus `Off`). */
+    onValues: string[];
+    hasAppearance: boolean;
+}
+/** What a document says about its form as a whole. */
+export interface ReadForm {
+    fields: ReadField[];
+    /** The form asks viewers to regenerate every appearance. */
+    needAppearances: boolean;
+    /**
+     * The document carries an XFA packet beside the AcroForm (a "hybrid" form). Filling only the AcroForm
+     * side can be ignored by a viewer that prefers XFA, so this is reported rather than glossed over.
+     */
+    hasXfa: boolean;
+    /** True when the cross-reference table had to be rebuilt to read the file at all. */
+    recovered: boolean;
+}
+/**
+ * Read the form of a loaded document. Returns `undefined` when there is no `/AcroForm` at all - that is
+ * a plain PDF, not an error.
+ */
+export declare function readAcroForm(doc: PdfDocument): ReadForm | undefined;