pdf-lite 1.0.1-alpha.2 → 1.0.1-alpha.3

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

@@ -0,0 +1,304 @@
+import { PdfIndirectObject } from '../../core/objects/pdf-indirect-object';
+import { Cipher } from '../../crypto/types';
+import { ByteArray, PdfPermissions } from '../../types';
+import { PdfEncryptionAlgorithmType, PdfEncryptionDictionary, PdfId } from '../types';
+/**
+ * Base options for creating a security handler.
+ */
+export type PdfSecurityHandlerOptions = {
+    /** Document permissions configuration. */
+    permissions?: number | PdfPermissions;
+    /** Whether to encrypt document metadata. */
+    encryptMetadata?: boolean;
+};
+/**
+ * Abstract base class for PDF security handlers.
+ * Security handlers manage encryption, decryption, and access permissions for PDF documents.
+ *
+ * @example
+ * ```typescript
+ * const handler = new PdfV5SecurityHandler({ password: 'secret' })
+ * await handler.write()
+ * const encryptedData = await handler.encrypt('stream', data, objectNumber, generationNumber)
+ * ```
+ */
+export declare abstract class PdfSecurityHandler {
+    /** The encryption dictionary containing all encryption parameters. */
+    dict: PdfEncryptionDictionary;
+    /** Numeric permission flags. */
+    permissions: number;
+    /** Whether to encrypt document metadata. */
+    encryptMetadata: boolean;
+    /**
+     * Creates a new security handler.
+     *
+     * @param options - Configuration options for the security handler.
+     */
+    constructor(options?: PdfSecurityHandlerOptions);
+    /**
+     * Decodes the numeric permission flags into a PdfPermissions object.
+     *
+     * @returns An object with boolean flags for each permission.
+     */
+    decodePermissions(): PdfPermissions;
+    /**
+     * Checks if the security handler is ready for encryption/decryption.
+     *
+     * @returns True if ready, false otherwise.
+     */
+    abstract isReady(): boolean;
+    /**
+     * Gets the security handler filter name.
+     *
+     * @returns The filter name (e.g., 'Standard').
+     */
+    abstract getName(): string;
+    /**
+     * Gets the encryption version number.
+     *
+     * @returns The version number (1-5).
+     */
+    abstract getVersion(): number;
+    /**
+     * Gets the encryption revision number.
+     *
+     * @returns The revision number.
+     */
+    abstract getRevision(): number;
+    /**
+     * Reads and applies encryption parameters from a dictionary.
+     *
+     * @param dictionary - The encryption dictionary from the PDF trailer.
+     */
+    abstract readEncryptionDictionary(dictionary: PdfEncryptionDictionary): void;
+    /**
+     * Decrypts data of a specific type.
+     *
+     * @param type - The type of content being decrypted.
+     * @param data - The encrypted data.
+     * @param objectNumber - The PDF object number.
+     * @param generationNumber - The PDF generation number.
+     * @returns The decrypted data.
+     */
+    abstract decrypt(type: 'string' | 'stream' | 'file', data: ByteArray, objectNumber?: number, generationNumber?: number): Promise<ByteArray>;
+    /**
+     * Encrypts data of a specific type.
+     *
+     * @param type - The type of content being encrypted.
+     * @param data - The data to encrypt.
+     * @param objectNumber - The PDF object number.
+     * @param generationNumber - The PDF generation number.
+     * @returns The encrypted data.
+     */
+    abstract encrypt(type: 'string' | 'stream' | 'file', data: ByteArray, objectNumber?: number, generationNumber?: number): Promise<ByteArray>;
+    /**
+     * Computes the object-specific encryption key.
+     *
+     * @param objectNumber - The PDF object number.
+     * @param generationNumber - The PDF generation number.
+     * @param algorithm - Optional algorithm type for key derivation.
+     * @returns The computed object key.
+     */
+    abstract computeObjectKey(objectNumber?: number, generationNumber?: number, algorithm?: PdfEncryptionAlgorithmType): Promise<ByteArray>;
+    /**
+     * Gets the document ID array.
+     *
+     * @returns The document ID, or undefined if not set.
+     */
+    abstract getDocumentId(): PdfId | undefined;
+    /**
+     * Sets the document ID array.
+     *
+     * @param id - The document ID to set.
+     */
+    abstract setDocumentId(id: PdfId): void;
+    /**
+     * Writes the encryption dictionary with computed keys.
+     */
+    abstract write(): Promise<void>;
+    /**
+     * Builds the numeric permission flags from a PdfPermissions object.
+     *
+     * @param perm - The permissions to encode.
+     * @returns The numeric permission flags.
+     */
+    protected buildPermissions(perm: PdfPermissions): number;
+    /**
+     * Recursively decrypts all strings and streams within an indirect object.
+     *
+     * @param object - The indirect object to decrypt.
+     */
+    decryptObject(object: PdfIndirectObject): Promise<void>;
+    /**
+     * Recursively encrypts all strings and streams within an indirect object.
+     *
+     * @param object - The indirect object to encrypt.
+     */
+    encryptObject(object: PdfIndirectObject): Promise<void>;
+}
+/**
+ * Options for creating a standard security handler with password-based encryption.
+ */
+export type PdfStandardSecurityHandlerOptions = PdfSecurityHandlerOptions & {
+    /** User password for opening the document. */
+    password?: string | ByteArray;
+    /** Owner password for full document access. */
+    ownerPassword?: string | ByteArray;
+    /** Document identifier for key derivation. */
+    documentId?: PdfId | string | ByteArray;
+    /** Pre-computed user key. */
+    userKey?: ByteArray;
+    /** Pre-computed owner key. */
+    ownerKey?: ByteArray;
+};
+/**
+ * Abstract base class for standard PDF security handlers.
+ * Implements password-based encryption as defined in the PDF specification.
+ *
+ * @example
+ * ```typescript
+ * const handler = new PdfV5SecurityHandler({
+ *     password: 'user123',
+ *     ownerPassword: 'admin456',
+ *     permissions: { print: true, copy: false }
+ * })
+ * ```
+ */
+export declare abstract class PdfStandardSecurityHandler extends PdfSecurityHandler {
+    /** Document identifier for key derivation. */
+    protected documentId?: PdfId;
+    /** Computed owner key (O value). */
+    protected ownerKey?: ByteArray;
+    /** Computed user key (U value). */
+    protected userKey?: ByteArray;
+    /** User password for authentication. */
+    protected password: ByteArray;
+    /** Owner password for full access. */
+    protected ownerPassword?: ByteArray;
+    /** Derived master encryption key. */
+    protected masterKey?: ByteArray;
+    /**
+     * Creates a new standard security handler.
+     *
+     * @param options - Configuration options including passwords and document ID.
+     */
+    constructor(options: PdfStandardSecurityHandlerOptions);
+    /**
+     * Gets the encryption key length in bits.
+     *
+     * @returns The key length in bits.
+     */
+    abstract getKeyBits(): number;
+    /**
+     * Gets the security handler filter name.
+     *
+     * @returns 'Standard' for password-based encryption.
+     */
+    getName(): string;
+    /**
+     * Checks if the handler is ready (has document ID).
+     *
+     * @returns True if document ID is set.
+     */
+    isReady(): boolean;
+    /**
+     * Sets the document ID for key derivation.
+     *
+     * @param id - The document ID array.
+     */
+    setDocumentId(id: PdfId): void;
+    /**
+     * Gets the document ID.
+     *
+     * @returns The document ID, or undefined if not set.
+     */
+    getDocumentId(): PdfId | undefined;
+    /**
+     * Sets the user password.
+     *
+     * @param password - The user password string or bytes.
+     */
+    setPassword(password: string | ByteArray): void;
+    /**
+     * Sets the owner password.
+     *
+     * @param ownerPassword - The owner password string or bytes.
+     */
+    setOwnerPassword(ownerPassword: string | ByteArray): void;
+    /**
+     * Checks if metadata encryption is enabled.
+     *
+     * @returns True if metadata should be encrypted.
+     */
+    canEncryptMetadata(): boolean;
+    /**
+     * Reads encryption parameters from the encryption dictionary.
+     *
+     * @param encryptionDictionary - The encryption dictionary from the PDF.
+     */
+    readEncryptionDictionary(encryptionDictionary: PdfEncryptionDictionary): void;
+    /**
+     * Computes the user key (U value) for the encryption dictionary.
+     *
+     * @returns The computed user key.
+     */
+    protected abstract computeUserKey(): Promise<ByteArray>;
+    /**
+     * Computes the owner key (O value) for the encryption dictionary.
+     *
+     * @returns The computed owner key.
+     */
+    protected abstract computeOwnerKey(): Promise<ByteArray>;
+    /**
+     * Initializes the user and owner keys if not already set.
+     */
+    protected initKeys(): Promise<void>;
+    /**
+     * Writes the encryption dictionary with all computed keys and parameters.
+     *
+     * @throws Error if required keys are not computed.
+     */
+    write(): Promise<void>;
+    /**
+     * Gets a cipher for the specified object.
+     *
+     * @param objectNumber - The PDF object number.
+     * @param generationNumber - The PDF generation number.
+     * @returns A cipher instance, or null if no encryption needed.
+     */
+    protected abstract getCipher(objectNumber?: number, generationNumber?: number): Promise<Cipher | null>;
+    /**
+     * Encrypts data using the appropriate cipher.
+     *
+     * @param type - The type of content being encrypted.
+     * @param data - The data to encrypt.
+     * @param objectNumber - The PDF object number.
+     * @param generationNumber - The PDF generation number.
+     * @returns The encrypted data.
+     */
+    encrypt(type: 'string' | 'stream' | 'file', data: ByteArray, objectNumber?: number, generationNumber?: number): Promise<ByteArray>;
+    /**
+     * Decrypts data using the appropriate cipher.
+     *
+     * @param type - The type of content being decrypted.
+     * @param data - The encrypted data.
+     * @param objectNumber - The PDF object number.
+     * @param generationNumber - The PDF generation number.
+     * @returns The decrypted data.
+     */
+    decrypt(type: 'string' | 'stream' | 'file', data: ByteArray, objectNumber?: number, generationNumber?: number): Promise<ByteArray>;
+    /**
+     * Sets the master encryption key directly.
+     *
+     * @param masterKey - The master key to use.
+     */
+    setMasterKey(masterKey: ByteArray): void;
+    /**
+     * Recovers the user password from the owner password.
+     *
+     * @param ownerPassword - The owner password.
+     * @returns The recovered user password.
+     * @throws Error if recovery is not supported.
+     */
+    abstract recoverUserPassword(ownerPassword?: ByteArray | string): Promise<string>;
+}

package/dist/security/handlers/base.js

@@ -0,0 +1,359 @@
+import { PdfArray } from '../../core/objects/pdf-array';
+import { PdfBoolean } from '../../core/objects/pdf-boolean';
+import { PdfDictionary } from '../../core/objects/pdf-dictionary';
+import { PdfHexadecimal } from '../../core/objects/pdf-hexadecimal';
+import { PdfIndirectObject } from '../../core/objects/pdf-indirect-object';
+import { PdfName } from '../../core/objects/pdf-name';
+import { PdfNumber } from '../../core/objects/pdf-number';
+import { PdfStream } from '../../core/objects/pdf-stream';
+import { PdfString } from '../../core/objects/pdf-string';
+import { PERMISSION_FLAGS } from '../../types';
+import { assert, assertIfDefined } from '../../utils/assert';
+import { stringToBytes } from '../../utils/stringToBytes';
+/**
+ * Abstract base class for PDF security handlers.
+ * Security handlers manage encryption, decryption, and access permissions for PDF documents.
+ *
+ * @example
+ * ```typescript
+ * const handler = new PdfV5SecurityHandler({ password: 'secret' })
+ * await handler.write()
+ * const encryptedData = await handler.encrypt('stream', data, objectNumber, generationNumber)
+ * ```
+ */
+export class PdfSecurityHandler {
+    /** The encryption dictionary containing all encryption parameters. */
+    dict;
+    /** Numeric permission flags. */
+    permissions;
+    /** Whether to encrypt document metadata. */
+    encryptMetadata;
+    /**
+     * Creates a new security handler.
+     *
+     * @param options - Configuration options for the security handler.
+     */
+    constructor(options) {
+        this.dict = new PdfDictionary();
+        this.encryptMetadata = options?.encryptMetadata ?? true;
+        this.permissions =
+            typeof options?.permissions === 'number'
+                ? options.permissions
+                : this.buildPermissions(options?.permissions ?? DEFAULT_PERMISSIONS);
+    }
+    /**
+     * Decodes the numeric permission flags into a PdfPermissions object.
+     *
+     * @returns An object with boolean flags for each permission.
+     */
+    decodePermissions() {
+        const perm = {};
+        for (const [key, bit] of Object.entries(PERMISSION_FLAGS)) {
+            perm[key] = (this.permissions & bit) !== 0;
+        }
+        return perm;
+    }
+    /**
+     * Builds the numeric permission flags from a PdfPermissions object.
+     *
+     * @param perm - The permissions to encode.
+     * @returns The numeric permission flags.
+     */
+    buildPermissions(perm) {
+        let flags = 0xfffffffc; // All bits set to 1 except bits 0–1, which must be 0
+        for (const [key, bit] of Object.entries(PERMISSION_FLAGS)) {
+            if (perm[key] === false) {
+                // Remove this permission
+                flags &= ~bit;
+            }
+        }
+        return flags | 0xfffff000; // ensure unused high bits are set
+    }
+    /**
+     * Recursively decrypts all strings and streams within an indirect object.
+     *
+     * @param object - The indirect object to decrypt.
+     */
+    async decryptObject(object) {
+        const objectNumber = object.objectNumber;
+        const generationNumber = object.generationNumber;
+        const decryptObject = async (obj) => {
+            if (obj instanceof PdfIndirectObject) {
+                return decryptObject(obj.content);
+            }
+            else if (obj instanceof PdfString) {
+                const decryptedData = await this.decrypt('string', obj.raw, objectNumber, generationNumber);
+                obj.raw = decryptedData;
+            }
+            else if (obj instanceof PdfStream) {
+                const decryptedData = await this.decrypt('stream', obj.raw, objectNumber, generationNumber);
+                obj.raw = decryptedData;
+                await decryptObject(obj.header);
+            }
+            else if (obj instanceof PdfDictionary) {
+                for (const [key, value] of Object.entries(obj)) {
+                    await decryptObject(value);
+                }
+            }
+            else if (obj instanceof PdfArray) {
+                for (const item of obj.items) {
+                    await decryptObject(item);
+                }
+            }
+        };
+        await decryptObject(object.content);
+    }
+    /**
+     * Recursively encrypts all strings and streams within an indirect object.
+     *
+     * @param object - The indirect object to encrypt.
+     */
+    async encryptObject(object) {
+        const objectNumber = object.objectNumber;
+        const generationNumber = object.generationNumber;
+        const encryptObject = async (obj) => {
+            if (obj instanceof PdfIndirectObject) {
+                return encryptObject(obj.content);
+            }
+            else if (obj instanceof PdfString) {
+                const encryptedData = await this.encrypt('string', obj.raw, objectNumber, generationNumber);
+                obj.raw = encryptedData;
+            }
+            else if (obj instanceof PdfStream) {
+                const encryptedData = await this.encrypt('stream', obj.raw, objectNumber, generationNumber);
+                obj.raw = encryptedData;
+                await encryptObject(obj.header);
+            }
+            else if (obj instanceof PdfDictionary) {
+                const values = obj.values;
+                for (const key in values) {
+                    await encryptObject(values[key]);
+                }
+            }
+            else if (obj instanceof PdfArray) {
+                for (const item of obj.items) {
+                    await encryptObject(item);
+                }
+            }
+        };
+        return await encryptObject(object.content);
+    }
+}
+const DEFAULT_PERMISSIONS = {
+    print: true,
+    modify: true,
+    copy: true,
+    annotate: true,
+    fill: true,
+    extract: true,
+    assemble: true,
+    printHighQuality: true,
+};
+/**
+ * Abstract base class for standard PDF security handlers.
+ * Implements password-based encryption as defined in the PDF specification.
+ *
+ * @example
+ * ```typescript
+ * const handler = new PdfV5SecurityHandler({
+ *     password: 'user123',
+ *     ownerPassword: 'admin456',
+ *     permissions: { print: true, copy: false }
+ * })
+ * ```
+ */
+export class PdfStandardSecurityHandler extends PdfSecurityHandler {
+    /** Document identifier for key derivation. */
+    documentId;
+    /** Computed owner key (O value). */
+    ownerKey;
+    /** Computed user key (U value). */
+    userKey;
+    /** User password for authentication. */
+    password;
+    /** Owner password for full access. */
+    ownerPassword;
+    /** Derived master encryption key. */
+    masterKey;
+    /**
+     * Creates a new standard security handler.
+     *
+     * @param options - Configuration options including passwords and document ID.
+     */
+    constructor(options) {
+        super(options);
+        this.dict.set('Filter', new PdfName('Standard'));
+        this.password =
+            typeof options.password === 'string'
+                ? stringToBytes(options.password)
+                : (options.password ?? new Uint8Array());
+        this.ownerPassword =
+            typeof options.ownerPassword === 'string'
+                ? stringToBytes(options.ownerPassword)
+                : options.ownerPassword;
+        this.documentId =
+            typeof options.documentId === 'string' ||
+                options.documentId instanceof Uint8Array
+                ? new PdfArray([
+                    PdfHexadecimal.toHexadecimal(options.documentId),
+                    PdfHexadecimal.toHexadecimal(options.documentId),
+                ])
+                : options.documentId;
+    }
+    /**
+     * Gets the security handler filter name.
+     *
+     * @returns 'Standard' for password-based encryption.
+     */
+    getName() {
+        return 'Standard';
+    }
+    /**
+     * Checks if the handler is ready (has document ID).
+     *
+     * @returns True if document ID is set.
+     */
+    isReady() {
+        return !!this.documentId;
+    }
+    /**
+     * Sets the document ID for key derivation.
+     *
+     * @param id - The document ID array.
+     */
+    setDocumentId(id) {
+        this.documentId = id;
+    }
+    /**
+     * Gets the document ID.
+     *
+     * @returns The document ID, or undefined if not set.
+     */
+    getDocumentId() {
+        return this.documentId;
+    }
+    /**
+     * Sets the user password.
+     *
+     * @param password - The user password string or bytes.
+     */
+    setPassword(password) {
+        this.password =
+            typeof password === 'string' ? stringToBytes(password) : password;
+    }
+    /**
+     * Sets the owner password.
+     *
+     * @param ownerPassword - The owner password string or bytes.
+     */
+    setOwnerPassword(ownerPassword) {
+        this.ownerPassword =
+            typeof ownerPassword === 'string'
+                ? stringToBytes(ownerPassword)
+                : ownerPassword;
+    }
+    /**
+     * Checks if metadata encryption is enabled.
+     *
+     * @returns True if metadata should be encrypted.
+     */
+    canEncryptMetadata() {
+        return this.encryptMetadata;
+    }
+    /**
+     * Reads encryption parameters from the encryption dictionary.
+     *
+     * @param encryptionDictionary - The encryption dictionary from the PDF.
+     */
+    readEncryptionDictionary(encryptionDictionary) {
+        this.dict.copyFrom(encryptionDictionary);
+        const o = encryptionDictionary.get('O');
+        const u = encryptionDictionary.get('U');
+        const p = encryptionDictionary.get('P');
+        const ID = encryptionDictionary.get('ID');
+        const encryptMetadata = encryptionDictionary.get('EncryptMetadata');
+        assertIfDefined(u, u instanceof PdfHexadecimal || u instanceof PdfString, 'U must be a hexadecimal or a string');
+        assertIfDefined(o, o instanceof PdfHexadecimal || o instanceof PdfString, 'O must be a hexadecimal or a string');
+        assert(p instanceof PdfNumber, 'P must be a number');
+        assertIfDefined(ID, ID instanceof PdfArray, 'ID must be an array');
+        assertIfDefined(encryptMetadata, encryptMetadata instanceof PdfBoolean, 'EncryptMetadata must be a boolean');
+        this.ownerKey = o instanceof PdfHexadecimal ? o.bytes : o.raw;
+        this.userKey = u instanceof PdfHexadecimal ? u.bytes : u.raw;
+        this.permissions = p.value;
+        this.encryptMetadata = encryptMetadata?.value ?? true;
+        if (ID)
+            this.documentId = ID;
+    }
+    /**
+     * Initializes the user and owner keys if not already set.
+     */
+    async initKeys() {
+        this.ownerKey ||= await this.computeOwnerKey();
+        this.userKey ||= await this.computeUserKey();
+    }
+    /**
+     * Writes the encryption dictionary with all computed keys and parameters.
+     *
+     * @throws Error if required keys are not computed.
+     */
+    async write() {
+        // Initialise the keys
+        await this.initKeys();
+        if (!this.ownerKey) {
+            throw new Error('Missing ownerKey');
+        }
+        if (!this.userKey) {
+            throw new Error('Missing userKey');
+        }
+        this.dict.set('O', new PdfString(this.ownerKey));
+        this.dict.set('U', new PdfString(this.userKey));
+        this.dict.set('P', new PdfNumber(this.permissions));
+        this.dict.set('V', new PdfNumber(this.getVersion()));
+        this.dict.set('R', new PdfNumber(this.getRevision()));
+        this.dict.set('Length', new PdfNumber(this.getKeyBits()));
+        if (this.documentId) {
+            this.dict.set('ID', this.documentId);
+        }
+        this.dict.set('EncryptMetadata', new PdfBoolean(this.encryptMetadata));
+    }
+    /**
+     * Encrypts data using the appropriate cipher.
+     *
+     * @param type - The type of content being encrypted.
+     * @param data - The data to encrypt.
+     * @param objectNumber - The PDF object number.
+     * @param generationNumber - The PDF generation number.
+     * @returns The encrypted data.
+     */
+    async encrypt(type, data, objectNumber, generationNumber) {
+        const cipher = await this.getCipher(objectNumber, generationNumber);
+        if (!cipher) {
+            return data;
+        }
+        return await cipher.encrypt(data);
+    }
+    /**
+     * Decrypts data using the appropriate cipher.
+     *
+     * @param type - The type of content being decrypted.
+     * @param data - The encrypted data.
+     * @param objectNumber - The PDF object number.
+     * @param generationNumber - The PDF generation number.
+     * @returns The decrypted data.
+     */
+    async decrypt(type, data, objectNumber, generationNumber) {
+        const cipher = await this.getCipher(objectNumber, generationNumber);
+        if (!cipher) {
+            return data;
+        }
+        return await cipher.decrypt(data);
+    }
+    /**
+     * Sets the master encryption key directly.
+     *
+     * @param masterKey - The master key to use.
+     */
+    setMasterKey(masterKey) {
+        this.masterKey = masterKey;
+    }
+}