pdf-lite 1.7.3 → 1.7.4-alpha.1

package/dist/crypto/key-derivation/key-derivation-aes256.js

@@ -1,3 +1,4 @@
+import { PdfInvalidPasswordError } from '../../errors.js';
 import { aes128CbcNoPaddingEncrypt, aes256CbcNoPaddingDecrypt, sha256, sha384, sha512, } from '../../utils/algos.js';
 import { assert } from '../../utils/assert.js';
 /**
@@ -162,7 +163,7 @@ export async function getFileKey(userPassword, ownerPassword, u, ue, o, oe) {
             return key;
         }
         catch (e) {
-            throw new Error('Invalid password');
+            throw new PdfInvalidPasswordError();
         }
     }
 }

package/dist/errors.d.ts

@@ -20,3 +20,17 @@ export declare class UnexpectedTokenError extends Error {
  */
 export declare class FoundCompressedObjectError extends Error {
 }
+/**
+ * Error thrown when a PDF is encrypted and the blank password
+ * does not grant access. Callers should catch this and prompt
+ * the user for a password, then retry with the `password` option.
+ */
+export declare class PdfPasswordProtectedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when a provided password is invalid for decrypting a PDF.
+ */
+export declare class PdfInvalidPasswordError extends Error {
+    constructor(message?: string);
+}

package/dist/errors.js

@@ -22,3 +22,21 @@ export class UnexpectedTokenError extends Error {
  */
 export class FoundCompressedObjectError extends Error {
 }
+/**
+ * Error thrown when a PDF is encrypted and the blank password
+ * does not grant access. Callers should catch this and prompt
+ * the user for a password, then retry with the `password` option.
+ */
+export class PdfPasswordProtectedError extends Error {
+    constructor(message) {
+        super(message ?? 'PDF is password protected');
+    }
+}
+/**
+ * Error thrown when a provided password is invalid for decrypting a PDF.
+ */
+export class PdfInvalidPasswordError extends Error {
+    constructor(message) {
+        super(message ?? 'Invalid password');
+    }
+}

package/dist/pdf/pdf-document.d.ts

@@ -47,6 +47,8 @@ export declare class PdfDocument extends PdfObject implements IPdfObjectResolver
     private _updating;
     private _finalized;
     private _signed;
+    /** @internal */
+    _batching: boolean;
     /**
      * Creates a new PDF document instance.
      *
@@ -71,14 +73,48 @@ export declare class PdfDocument extends PdfObject implements IPdfObjectResolver
     get pages(): PdfPages;
     get header(): PdfComment | undefined;
     set header(comment: PdfComment | undefined);
+    /**
+     * Loads PDF objects into the document, organizing them into revisions.
+     * Parses objects into revisions based on EOF comments.
+     *
+     * @param objects - Array of PDF objects to load into the document
+     * @param options - Optional security and mode configuration
+     * @param options.password - User password for encrypted documents
+     * @param options.ownerPassword - Owner password for encrypted documents
+     * @param options.incremental - Whether to use incremental mode
+     */
+    loadObjects(objects: PdfObject[], options?: {
+        password?: string;
+        ownerPassword?: string;
+        incremental?: boolean;
+    }): Promise<this>;
+    /**
+     * Loads a PDF document from a byte stream, parsing it into objects and revisions.
+     * @param input - Async or sync iterable of byte arrays representing the PDF file
+     * @param options - Optional security and mode configuration
+     * @returns A promise that resolves to the loaded PdfDocument instance
+     */
+    load(input: AsyncIterable<ByteArray> | Iterable<ByteArray>, options?: {
+        password?: string;
+        ownerPassword?: string;
+        incremental?: boolean;
+    }): Promise<this>;
     /**
      * Creates a PdfDocument from an array of PDF objects.
      * Parses objects into revisions based on EOF comments.
      *
      * @param objects - Array of PDF objects to construct the document from
-     * @returns A new PdfDocument instance
+     * @param options - Optional security and mode configuration
+     * @param options.password - User password for encrypted documents
+     * @param options.ownerPassword - Owner password for encrypted documents
+     * @param options.incremental - Whether to use incremental mode
+     * @returns A promise that resolves to the new PdfDocument instance
      */
-    static fromObjects(objects: PdfObject[]): PdfDocument;
+    static fromObjects(objects: PdfObject[], options?: {
+        password?: string;
+        ownerPassword?: string;
+        incremental?: boolean;
+    }): Promise<PdfDocument>;
     /**
      * Starts a new revision for incremental updates.
      * Creates a new revision linked to the previous one.
@@ -94,6 +130,31 @@ export declare class PdfDocument extends PdfObject implements IPdfObjectResolver
      * @param objects - PDF objects to add to the document
      */
     add(...objects: PdfObject[]): void;
+    /**
+     * Recursively collects and adds all missing referenced objects in batches.
+     * More efficient than recursive add() calls since it collects all missing
+     * objects before processing them.
+     * @private
+     */
+    private addAllMissingReferences;
+    /**
+     * Creates a batch for adding multiple objects with a single update pass.
+     * This is significantly faster than calling `add()` multiple times when
+     * adding objects with many sub-references (e.g. fonts with descriptors,
+     * CIDToGIDMap streams, ToUnicode CMaps).
+     *
+     * @example
+     * ```typescript
+     * const batch = document.batch()
+     * batch.add(font1)
+     * batch.add(font2)
+     * batch.add(imageStream)
+     * batch.commit()
+     * ```
+     *
+     * @returns A PdfDocumentBatch instance
+     */
+    batch(): PdfDocumentBatch;
     /**
      * Packs non-stream indirect objects into compressed ObjStm containers.
      * Objects that already have an object number are left unchanged.
@@ -289,8 +350,9 @@ export declare class PdfDocument extends PdfObject implements IPdfObjectResolver
     private updateRevisions;
     /**
      * Performs a full update cycle to ensure all revisions are consistent and offsets are correct.
+     * @internal
      */
-    private update;
+    update(): void;
     /**
      * Walks all objects in the document and registers any newly created
      * PdfIndirectObjects that are referenced but not yet part of the document
@@ -318,6 +380,20 @@ export declare class PdfDocument extends PdfObject implements IPdfObjectResolver
             objects: object[];
         }[];
     };
+    /**
+     * Creates a new PdfDocument instance.
+     *
+     * @param options - Configuration options for the document
+     * @returns A new PdfDocument instance
+     */
+    static newDocument(options?: {
+        revisions?: PdfRevision[];
+        version?: string | PdfComment;
+        password?: string;
+        ownerPassword?: string;
+        securityHandler?: PdfSecurityHandler;
+        signer?: PdfSigner;
+    }): PdfDocument;
     /**
      * Creates a PdfDocument from a byte stream.
      *
@@ -337,3 +413,29 @@ export declare class PdfDocument extends PdfObject implements IPdfObjectResolver
      */
     verifySignatures(): Promise<PdfDocumentVerificationResult>;
 }
+/**
+ * Batches multiple `add()` calls into a single update pass.
+ * Created via {@link PdfDocument.batch}.
+ */
+export declare class PdfDocumentBatch {
+    private _document;
+    private _completed;
+    private _addedObjects;
+    /** @internal */
+    constructor(document: PdfDocument);
+    /**
+     * Adds one or more objects to the document without triggering an update.
+     *
+     * @param objects - PDF objects to add
+     */
+    add(...objects: PdfObject[]): this;
+    /**
+     * Commits the batch, running a single update pass for all added objects.
+     */
+    commit(): void;
+    /**
+     * Rolls back the batch, removing all objects that were added and
+     * restoring the document to its state before the batch was created.
+     */
+    rollback(): void;
+}

package/dist/pdf/pdf-document.js

@@ -15,12 +15,13 @@ import { PdfByteOffsetToken } from '../core/tokens/byte-offset-token.js';
 import { PdfNumberToken } from '../core/tokens/number-token.js';
 import { PdfXRefTableEntryToken } from '../core/tokens/xref-table-entry-token.js';
 import { PdfStartXRef } from '../core/objects/pdf-start-xref.js';
-import { FoundCompressedObjectError } from '../errors.js';
+import { FoundCompressedObjectError, PdfPasswordProtectedError, } from '../errors.js';
 import { PdfReader } from './pdf-reader.js';
 import { PdfSigner } from '../signing/signer.js';
 import { concatUint8Arrays } from '../utils/concatUint8Arrays.js';
 import { PdfAcroForm } from '../acroform/pdf-acro-form.js';
 import { PdfPages } from './pdf-pages.js';
+import { PdfObjectStream } from '../index.js';
 /**
  * Represents a PDF document with support for reading, writing, and modifying PDF files.
  * Handles document structure, revisions, encryption, and digital signatures.
@@ -55,6 +56,8 @@ export class PdfDocument extends PdfObject {
     _updating = false;
     _finalized = false;
     _signed = false;
+    /** @internal */
+    _batching = false;
     /**
      * Creates a new PDF document instance.
      *
@@ -75,18 +78,18 @@ export class PdfDocument extends PdfObject {
         else {
             this.setVersion(options?.version ?? '2.0');
         }
-        if (options?.password) {
-            this.setPassword(options.password);
-        }
-        if (options?.ownerPassword) {
-            this.setOwnerPassword(options.ownerPassword);
-        }
         this.signer = options?.signer ?? new PdfSigner({ document: this });
         this.linkRevisions();
         this.wireResolvers(...this.objects.filter((x) => x instanceof PdfIndirectObject), ...this.revisions.map((rev) => rev.xref.trailerDict));
         this.calculateOffsets();
         this.originalSecurityHandler = options?.securityHandler;
         this.resetSecurityHandler();
+        if (options?.password) {
+            this.setPassword(options.password);
+        }
+        if (options?.ownerPassword) {
+            this.setOwnerPassword(options.ownerPassword);
+        }
     }
     resolve(objectNumber, generationNumber) {
         const cacheKey = `${objectNumber} ${generationNumber}`;
@@ -132,13 +135,16 @@ export class PdfDocument extends PdfObject {
             this.revisions[0].header = comment;
     }
     /**
-     * Creates a PdfDocument from an array of PDF objects.
+     * Loads PDF objects into the document, organizing them into revisions.
      * Parses objects into revisions based on EOF comments.
      *
-     * @param objects - Array of PDF objects to construct the document from
-     * @returns A new PdfDocument instance
+     * @param objects - Array of PDF objects to load into the document
+     * @param options - Optional security and mode configuration
+     * @param options.password - User password for encrypted documents
+     * @param options.ownerPassword - Owner password for encrypted documents
+     * @param options.incremental - Whether to use incremental mode
      */
-    static fromObjects(objects) {
+    async loadObjects(objects, options) {
         let header;
         const revisions = [];
         let currentObjects = [];
@@ -156,7 +162,111 @@ export class PdfDocument extends PdfObject {
         if (currentObjects.length > 0) {
             revisions.push(new PdfRevision({ objects: currentObjects }));
         }
-        return new PdfDocument({ revisions, version: header });
+        this.revisions = revisions;
+        if (header) {
+            this.header = header;
+        }
+        this.linkRevisions();
+        this.wireResolvers(...this.objects.filter((x) => x instanceof PdfIndirectObject), ...this.revisions.map((rev) => rev.xref.trailerDict));
+        this.calculateOffsets();
+        // Reset security handler to detect and initialize encryption from the PDF
+        // Preserve any passwords that were set before load() was called
+        let presetPassword = options?.password;
+        let presetOwnerPassword = options?.ownerPassword;
+        if (this.securityHandler instanceof PdfStandardSecurityHandler) {
+            const pw = this.securityHandler.getPassword();
+            const opw = this.securityHandler.getOwnerPassword();
+            if (!presetPassword && pw.length > 0) {
+                presetPassword = new TextDecoder().decode(pw);
+            }
+            if (!presetOwnerPassword && opw) {
+                presetOwnerPassword = new TextDecoder().decode(opw);
+            }
+        }
+        this.resetSecurityHandler();
+        // Apply passwords
+        if (presetPassword) {
+            this.setPassword(presetPassword);
+        }
+        if (presetOwnerPassword) {
+            this.setOwnerPassword(presetOwnerPassword);
+        }
+        // Handle encryption/decryption
+        let shouldDecrypt = Boolean(this.encryptionDictionary);
+        const hasExplicitPassword = !!presetPassword || !!presetOwnerPassword;
+        // If encrypted, verify the password is valid before attempting decryption
+        if (shouldDecrypt &&
+            this.securityHandler instanceof PdfStandardSecurityHandler) {
+            const valid = await this.securityHandler.testPassword();
+            if (!valid) {
+                if (!hasExplicitPassword) {
+                    throw new PdfPasswordProtectedError();
+                }
+                this.resetSecurityHandler();
+                shouldDecrypt = false;
+            }
+        }
+        if (options?.incremental) {
+            // Lock revisions first to preserve the original bytes
+            // (including encrypted data) via cached tokens.
+            this.setIncremental(true);
+            // Then decrypt the live object data so built-in operations
+            // (AcroForm, fonts, etc.) can read it. The cached tokens
+            // still produce the original encrypted bytes on serialization.
+            if (shouldDecrypt) {
+                try {
+                    await this.decryptObjects();
+                }
+                catch (e) {
+                    if (!hasExplicitPassword) {
+                        throw new PdfPasswordProtectedError();
+                    }
+                    this.resetSecurityHandler();
+                }
+            }
+        }
+        else if (shouldDecrypt) {
+            try {
+                await this.decryptObjects();
+            }
+            catch (e) {
+                if (!hasExplicitPassword) {
+                    throw new PdfPasswordProtectedError();
+                }
+                this.resetSecurityHandler();
+            }
+        }
+        return this;
+    }
+    /**
+     * Loads a PDF document from a byte stream, parsing it into objects and revisions.
+     * @param input - Async or sync iterable of byte arrays representing the PDF file
+     * @param options - Optional security and mode configuration
+     * @returns A promise that resolves to the loaded PdfDocument instance
+     */
+    async load(input, options) {
+        const objectStream = new PdfObjectStream(input);
+        const objects = [];
+        for await (const obj of objectStream) {
+            objects.push(obj);
+        }
+        return await this.loadObjects(objects, options);
+    }
+    /**
+     * Creates a PdfDocument from an array of PDF objects.
+     * Parses objects into revisions based on EOF comments.
+     *
+     * @param objects - Array of PDF objects to construct the document from
+     * @param options - Optional security and mode configuration
+     * @param options.password - User password for encrypted documents
+     * @param options.ownerPassword - Owner password for encrypted documents
+     * @param options.incremental - Whether to use incremental mode
+     * @returns A promise that resolves to the new PdfDocument instance
+     */
+    static async fromObjects(objects, options) {
+        const document = new PdfDocument();
+        await document.loadObjects(objects, options);
+        return document;
     }
     /**
      * Starts a new revision for incremental updates.
@@ -193,16 +303,54 @@ export class PdfDocument extends PdfObject {
             }
             this.latestRevision.addObject(obj);
         }
-        // Auto-add any referenced-but-missing objects
-        const missing = this.collectMissingReferences(...objects);
-        if (missing.length > 0) {
-            this.add(...missing);
+        // Auto-add any referenced-but-missing objects recursively in one pass
+        this.addAllMissingReferences(objects);
+        if (!this._batching) {
+            this.update();
         }
-        this.update();
         for (const obj of objects) {
             obj.setModified(false);
         }
     }
+    /**
+     * Recursively collects and adds all missing referenced objects in batches.
+     * More efficient than recursive add() calls since it collects all missing
+     * objects before processing them.
+     * @private
+     */
+    addAllMissingReferences(objects) {
+        let batch = this.collectMissingReferences(...objects);
+        while (batch.length > 0) {
+            for (const obj of batch) {
+                this.wireResolvers(obj);
+                if (!this.hasObjectInLatestRevision(obj)) {
+                    this.latestRevision.addObject(obj);
+                }
+            }
+            // Check if these newly added objects reference more missing objects
+            batch = this.collectMissingReferences(...batch);
+        }
+    }
+    /**
+     * Creates a batch for adding multiple objects with a single update pass.
+     * This is significantly faster than calling `add()` multiple times when
+     * adding objects with many sub-references (e.g. fonts with descriptors,
+     * CIDToGIDMap streams, ToUnicode CMaps).
+     *
+     * @example
+     * ```typescript
+     * const batch = document.batch()
+     * batch.add(font1)
+     * batch.add(font2)
+     * batch.add(imageStream)
+     * batch.commit()
+     * ```
+     *
+     * @returns A PdfDocumentBatch instance
+     */
+    batch() {
+        return new PdfDocumentBatch(this);
+    }
     /**
      * Packs non-stream indirect objects into compressed ObjStm containers.
      * Objects that already have an object number are left unchanged.
@@ -826,9 +974,9 @@ export class PdfDocument extends PdfObject {
             }
         }
     }
-    linkOffsets() {
+    linkOffsets(tokens) {
         const refMap = new Map();
-        const tokens = this.toTokens();
+        tokens = tokens ?? this.toTokens();
         for (let i = 0; i < tokens.length; i++) {
             const token = tokens[i];
             let main;
@@ -862,11 +1010,13 @@ export class PdfDocument extends PdfObject {
             }
         }
     }
-    calculateOffsets() {
+    calculateOffsets(cachedTokens) {
         const serializer = new PdfTokenSerializer();
-        serializer.feedMany(this.toTokens());
+        const tokens = cachedTokens ?? this.toTokens();
+        this.linkOffsets(tokens);
+        serializer.feedMany(tokens);
         serializer.calculateOffsets();
-        this.linkOffsets();
+        return tokens;
     }
     updateRevisions() {
         let modified = false;
@@ -890,6 +1040,7 @@ export class PdfDocument extends PdfObject {
     }
     /**
      * Performs a full update cycle to ensure all revisions are consistent and offsets are correct.
+     * @internal
      */
     update() {
         if (this._updating)
@@ -899,17 +1050,17 @@ export class PdfDocument extends PdfObject {
             this.commitIncrementalUpdates();
             this.flushResolvedCache();
             this.registerNewReferences();
+            // First pass: generate tokens and calculate offsets
             this.calculateOffsets();
             this.updateRevisions();
             // Second pass: xref binary may have changed size (e.g. FlateDecode removed
-            // from xref stream), shifting objects that follow it. Recalculate so entry
-            // byteOffset refs hold the new positions, then rebuild the xref binary once
-            // more so the baked bytes match those positions.
-            this.calculateOffsets();
+            // from xref stream), shifting objects that follow it. Regenerate tokens
+            // to capture xref changes, then recalculate offsets.
+            const tokens = this.calculateOffsets();
             this.updateRevisions();
-            // Third pass: confirm positions are stable (xref binary size should not
-            // change again because W widths and entry count are the same).
-            this.calculateOffsets();
+            // Third pass: reuse tokens from second pass since xref should now be stable
+            // (xref binary size should not change because W widths and entry count are same).
+            this.calculateOffsets(tokens);
         }
         finally {
             this._updating = false;
@@ -921,7 +1072,7 @@ export class PdfDocument extends PdfObject {
      * (e.g. appearance streams created by generateAppearance).
      */
     registerNewReferences() {
-        const missing = this.collectMissingReferences(...this.latestRevision.objects);
+        const missing = this.collectMissingReferences(...this.objects);
         if (missing.length > 0) {
             this.add(...missing);
         }
@@ -961,11 +1112,13 @@ export class PdfDocument extends PdfObject {
      */
     cloneImpl() {
         const clonedRevisions = this.revisions.map((rev) => rev.clone());
-        return new PdfDocument({
+        const cloned = new PdfDocument({
             revisions: clonedRevisions,
             version: this.header?.clone(),
-            securityHandler: this.securityHandler,
+            securityHandler: this.securityHandler?.clone(),
         });
+        cloned.hasEncryptionDictionary = this.hasEncryptionDictionary;
+        return cloned;
     }
     toJSON() {
         return {
@@ -973,6 +1126,15 @@ export class PdfDocument extends PdfObject {
             revisions: this.revisions.map((rev) => rev.toJSON()),
         };
     }
+    /**
+     * Creates a new PdfDocument instance.
+     *
+     * @param options - Configuration options for the document
+     * @returns A new PdfDocument instance
+     */
+    static newDocument(options) {
+        return new PdfDocument(options);
+    }
     /**
      * Creates a PdfDocument from a byte stream.
      *
@@ -994,3 +1156,56 @@ export class PdfDocument extends PdfObject {
         return await this.signer.verify();
     }
 }
+/**
+ * Batches multiple `add()` calls into a single update pass.
+ * Created via {@link PdfDocument.batch}.
+ */
+export class PdfDocumentBatch {
+    _document;
+    _completed = false;
+    _addedObjects = [];
+    /** @internal */
+    constructor(document) {
+        this._document = document;
+        this._document._batching = true;
+    }
+    /**
+     * Adds one or more objects to the document without triggering an update.
+     *
+     * @param objects - PDF objects to add
+     */
+    add(...objects) {
+        if (this._completed) {
+            throw new Error('Batch already completed (committed or rolled back)');
+        }
+        this._addedObjects.push(...objects);
+        this._document.add(...objects);
+        return this;
+    }
+    /**
+     * Commits the batch, running a single update pass for all added objects.
+     */
+    commit() {
+        if (this._completed) {
+            throw new Error('Batch already completed (committed or rolled back)');
+        }
+        this._completed = true;
+        this._document._batching = false;
+        this._document.update();
+    }
+    /**
+     * Rolls back the batch, removing all objects that were added and
+     * restoring the document to its state before the batch was created.
+     */
+    rollback() {
+        if (this._completed) {
+            throw new Error('Batch already completed (committed or rolled back)');
+        }
+        this._completed = true;
+        this._document._batching = false;
+        // Remove all objects that were added during this batch
+        for (const obj of this._addedObjects) {
+            this._document.deleteObject(obj);
+        }
+    }
+}

package/dist/pdf/pdf-reader.js

@@ -1,4 +1,3 @@
-import { PdfObjectStream } from '../core/streams/object-stream.js';
 import { PdfDocument } from './pdf-document.js';
 /**
  * A reader for parsing PDF data into PdfDocument instances.
@@ -31,7 +30,7 @@ export class PdfReader {
         for await (const obj of this.objectStream) {
             objects.push(obj);
         }
-        return PdfDocument.fromObjects(objects);
+        return await PdfDocument.fromObjects(objects);
     }
     /**
      * Creates a PdfDocument directly from a byte stream.
@@ -41,41 +40,8 @@ export class PdfReader {
      * @returns A promise that resolves to the parsed PdfDocument
      */
     static async fromBytes(input, options) {
-        const reader = new PdfReader(new PdfObjectStream(input));
-        const document = await reader.read();
-        let shouldDecrypt = Boolean(document.encryptionDictionary);
-        if (typeof options?.password === 'string') {
-            document.setPassword(options.password);
-            shouldDecrypt = true;
-        }
-        if (typeof options?.ownerPassword === 'string') {
-            document.setOwnerPassword(options.ownerPassword);
-            shouldDecrypt = true;
-        }
-        if (options?.incremental) {
-            // Lock revisions first to preserve the original bytes
-            // (including encrypted data) via cached tokens.
-            document.setIncremental(true);
-            // Then decrypt the live object data so built-in operations
-            // (AcroForm, fonts, etc.) can read it. The cached tokens
-            // still produce the original encrypted bytes on serialization.
-            if (shouldDecrypt) {
-                try {
-                    await document.decryptObjects();
-                }
-                catch (e) {
-                    document.resetSecurityHandler();
-                }
-            }
-        }
-        else if (shouldDecrypt) {
-            try {
-                await document.decryptObjects();
-            }
-            catch (e) {
-                document.resetSecurityHandler();
-            }
-        }
+        const document = new PdfDocument();
+        await document.load(input, options);
         return document;
     }
 }

package/dist/security/handlers/base.d.ts

@@ -116,6 +116,11 @@ export declare abstract class PdfSecurityHandler {
      * Writes the encryption dictionary with computed keys.
      */
     abstract write(): Promise<void>;
+    /**
+     * Tests whether the current password can decrypt this document.
+     * Returns true if the password is valid, false otherwise.
+     */
+    abstract testPassword(): Promise<boolean>;
     /**
      * Builds the numeric permission flags from a PdfPermissions object.
      *
@@ -123,6 +128,12 @@ export declare abstract class PdfSecurityHandler {
      * @returns The numeric permission flags.
      */
     protected buildPermissions(perm: PdfPermissions): number;
+    /**
+     * Creates a shallow clone of this security handler with an independent
+     * encryption dictionary, so that mutating the clone (e.g. during
+     * finalize/encrypt) does not affect the original.
+     */
+    clone(): this;
     /**
      * Recursively decrypts all strings and streams within an indirect object.
      *
@@ -213,6 +224,11 @@ export declare abstract class PdfStandardSecurityHandler extends PdfSecurityHand
      * @returns The document ID, or undefined if not set.
      */
     getDocumentId(): PdfId | undefined;
+    /**
+     * Tests whether the current password can decrypt this document.
+     * Attempts to compute the master key and returns true if successful.
+     */
+    testPassword(): Promise<boolean>;
     /**
      * Sets the user password.
      *
@@ -225,6 +241,18 @@ export declare abstract class PdfStandardSecurityHandler extends PdfSecurityHand
      * @param ownerPassword - The owner password string or bytes.
      */
     setOwnerPassword(ownerPassword: string | ByteArray): void;
+    /**
+     * Gets the user password.
+     *
+     * @returns The user password as bytes.
+     */
+    getPassword(): ByteArray;
+    /**
+     * Gets the owner password.
+     *
+     * @returns The owner password as bytes, or undefined if not set.
+     */
+    getOwnerPassword(): ByteArray | undefined;
     /**
      * Checks if metadata encryption is enabled.
      *
@@ -243,6 +271,13 @@ export declare abstract class PdfStandardSecurityHandler extends PdfSecurityHand
      * @returns The computed user key.
      */
     protected abstract computeUserKey(): Promise<ByteArray>;
+    /**
+     * Computes the master encryption key from the password.
+     *
+     * @returns The computed master key.
+     * @throws Error if the password is incorrect or required parameters are missing.
+     */
+    protected abstract computeMasterKey(): Promise<ByteArray>;
     /**
      * Computes the owner key (O value) for the encryption dictionary.
      *

package/dist/security/handlers/base.js

@@ -69,6 +69,17 @@ export class PdfSecurityHandler {
         }
         return flags | 0xfffff000; // ensure unused high bits are set
     }
+    /**
+     * Creates a shallow clone of this security handler with an independent
+     * encryption dictionary, so that mutating the clone (e.g. during
+     * finalize/encrypt) does not affect the original.
+     */
+    clone() {
+        const cloned = Object.create(Object.getPrototypeOf(this));
+        Object.assign(cloned, this);
+        cloned.dict = this.dict.clone();
+        return cloned;
+    }
     /**
      * Recursively decrypts all strings and streams within an indirect object.
      *
@@ -241,6 +252,19 @@ export class PdfStandardSecurityHandler extends PdfSecurityHandler {
     getDocumentId() {
         return this.documentId;
     }
+    /**
+     * Tests whether the current password can decrypt this document.
+     * Attempts to compute the master key and returns true if successful.
+     */
+    async testPassword() {
+        try {
+            await this.computeMasterKey();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Sets the user password.
      *
@@ -261,6 +285,22 @@ export class PdfStandardSecurityHandler extends PdfSecurityHandler {
                 ? stringToBytes(ownerPassword)
                 : ownerPassword;
     }
+    /**
+     * Gets the user password.
+     *
+     * @returns The user password as bytes.
+     */
+    getPassword() {
+        return this.password;
+    }
+    /**
+     * Gets the owner password.
+     *
+     * @returns The owner password as bytes, or undefined if not set.
+     */
+    getOwnerPassword() {
+        return this.ownerPassword;
+    }
     /**
      * Checks if metadata encryption is enabled.
      *

package/dist/security/handlers/pubSec.d.ts

@@ -36,6 +36,7 @@ export declare class PdfPublicKeySecurityHandler extends PdfSecurityHandler {
         permissions?: PdfPermissions | number;
         encryptMetadata?: boolean;
     });
+    clone(): this;
     /**
      * Gets the security handler filter name.
      *
@@ -66,6 +67,7 @@ export declare class PdfPublicKeySecurityHandler extends PdfSecurityHandler {
      * @returns True if the underlying handler is ready.
      */
     isReady(): boolean;
+    testPassword(): Promise<boolean>;
     /**
      * Gets the encryption version number.
      *

package/dist/security/handlers/pubSec.js

@@ -50,6 +50,11 @@ export class PdfPublicKeySecurityHandler extends PdfSecurityHandler {
         pkcs7Input[23] = this.permissions & 0xff;
         this.recipientsCms = this.getRecipientsPkcs7(pkcs7Input);
     }
+    clone() {
+        const cloned = super.clone();
+        cloned.standardSecurityHandler = this.standardSecurityHandler.clone();
+        return cloned;
+    }
     /**
      * Gets the security handler filter name.
      *
@@ -90,6 +95,9 @@ export class PdfPublicKeySecurityHandler extends PdfSecurityHandler {
     isReady() {
         return this.standardSecurityHandler.isReady();
     }
+    async testPassword() {
+        return this.standardSecurityHandler.testPassword();
+    }
     /**
      * Gets the encryption version number.
      *

package/dist/security/handlers/v4.d.ts

@@ -58,6 +58,7 @@ export declare class PdfV4SecurityHandler extends PdfV2SecurityHandler {
      * @param filter - The crypt filter instance.
      */
     setCryptFilter(name: string, filter: PdfCryptFilter): void;
+    clone(): this;
     /**
      * Gets the encryption revision number.
      *

package/dist/security/handlers/v4.js

@@ -84,6 +84,16 @@ export class PdfV4SecurityHandler extends PdfV2SecurityHandler {
         filter.setSecurityHandler(this);
         this.cryptFilters.set(name, filter);
     }
+    clone() {
+        const cloned = super.clone();
+        cloned.cryptFilters = new Map();
+        cloned.cryptFiltersByType = { ...this.cryptFiltersByType };
+        for (const [name, filter] of this.cryptFilters) {
+            cloned.cryptFilters.set(name, filter);
+            filter.setSecurityHandler(cloned);
+        }
+        return cloned;
+    }
     /**
      * Gets the encryption revision number.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pdf-lite",
-  "version": "1.7.3",
+  "version": "1.7.4-alpha.1",
   "main": "dist/index.js",
   "type": "module",
   "exports": {
@@ -35,7 +35,7 @@
     "@vitest/browser-playwright": "^4.0.14",
     "@vitest/coverage-v8": "^4.0.14",
     "playwright": "^1.56.1",
-    "typescript": "6.0.2",
+    "typescript": "6.0.3",
     "vitest": "^4.0.14"
   },
   "repository": {