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

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

@@ -0,0 +1,121 @@
+import { Cipher } from '../../crypto/types';
+import { ByteArray } from '../../types';
+import { PdfCryptFilter } from '../crypt-filters/base';
+import { CryptFilterType, PdfEncryptionAlgorithmType, PdfEncryptionDictionary } from '../types';
+import { PdfStandardSecurityHandlerOptions } from './base';
+import { PdfV2SecurityHandler } from './v2';
+/**
+ * V4 security handler implementing AES-128-CBC encryption with crypt filters.
+ * Supports different encryption methods for strings, streams, and embedded files (PDF 1.5).
+ *
+ * @example
+ * ```typescript
+ * const handler = new PdfV4SecurityHandler({
+ *     password: 'user123',
+ *     ownerPassword: 'admin456'
+ * })
+ * handler.setCryptFilter('StmFilter', new AesV2CryptFilter({ authEvent: 'DocOpen' }))
+ * ```
+ */
+export declare class PdfV4SecurityHandler extends PdfV2SecurityHandler {
+    /** Map of named crypt filters. */
+    protected cryptFilters: Map<string, PdfCryptFilter>;
+    /** Mapping of content types to crypt filter names. */
+    protected cryptFiltersByType: {
+        [key in CryptFilterType]?: string;
+    };
+    /**
+     * Creates a new V4 security handler with AES-128 encryption.
+     *
+     * @param options - Configuration options for the handler.
+     */
+    constructor(options: PdfStandardSecurityHandlerOptions);
+    /**
+     * Gets a crypt filter by name.
+     *
+     * @param name - The crypt filter name.
+     * @returns The crypt filter, or undefined if not found.
+     */
+    getCryptFilter(name: string): PdfCryptFilter | undefined;
+    /**
+     * Gets the crypt filter assigned to a content type.
+     *
+     * @param type - The content type ('string', 'stream', or 'file').
+     * @returns The assigned crypt filter, or null if none.
+     */
+    getCryptFilterByType(type: CryptFilterType): PdfCryptFilter | null;
+    /**
+     * Assigns a crypt filter to a content type.
+     *
+     * @param type - The content type.
+     * @param name - The crypt filter name.
+     */
+    setCryptFilterForType(type: CryptFilterType, name: string): void;
+    /**
+     * Registers a named crypt filter.
+     *
+     * @param name - The filter name.
+     * @param filter - The crypt filter instance.
+     */
+    setCryptFilter(name: string, filter: PdfCryptFilter): void;
+    /**
+     * Gets the encryption revision number.
+     *
+     * @returns 4 for V4 encryption.
+     */
+    getRevision(): number;
+    /**
+     * Gets the encryption version number.
+     *
+     * @returns 4 for crypt filter-based encryption.
+     */
+    getVersion(): number;
+    /**
+     * 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.
+     * @throws Error if object or generation number is invalid.
+     */
+    computeObjectKey(objectNumber?: number, generationNumber?: number, algorithm?: PdfEncryptionAlgorithmType): Promise<ByteArray>;
+    /**
+     * Gets an AES-128 cipher for the specified object.
+     *
+     * @param objectNumber - The PDF object number.
+     * @param generationNumber - The PDF generation number.
+     * @returns An AES-128 cipher instance.
+     */
+    protected getCipher(objectNumber?: number, generationNumber?: number): Promise<Cipher>;
+    /**
+     * Reads encryption parameters and crypt filter definitions from the dictionary.
+     *
+     * @param encryptionDictionary - The encryption dictionary from the PDF.
+     */
+    readEncryptionDictionary(encryptionDictionary: PdfEncryptionDictionary): void;
+    /**
+     * Writes the encryption dictionary including crypt filter definitions.
+     */
+    write(): Promise<void>;
+    /**
+     * Encrypts data using the appropriate crypt filter for the content 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.
+     */
+    encrypt(type: 'string' | 'stream' | 'file', data: ByteArray, objectNumber?: number, generationNumber?: number): Promise<ByteArray>;
+    /**
+     * Decrypts data using the appropriate crypt filter for the content 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.
+     */
+    decrypt(type: 'string' | 'stream' | 'file', data: ByteArray, objectNumber?: number, generationNumber?: number): Promise<ByteArray>;
+}

package/dist/security/handlers/v4.js

@@ -0,0 +1,257 @@
+import { PdfDictionary } from '../../core/objects/pdf-dictionary';
+import { PdfName } from '../../core/objects/pdf-name';
+import { PdfNumber } from '../../core/objects/pdf-number';
+import { aes128 } from '../../crypto/ciphers/aes128';
+import { deriveObjectKey } from '../../crypto/key-derivation/key-derivation';
+import { assert, assertIfDefined } from '../../utils/assert';
+import { AesV2CryptFilter } from '../crypt-filters/aesv2';
+import { AesV3CryptFilter } from '../crypt-filters/aesv3';
+import { IdentityCryptFilter } from '../crypt-filters/identity';
+import { V2CryptFilter } from '../crypt-filters/v2';
+import { PdfV2SecurityHandler } from './v2';
+const IDENTITY_CRYPT_FILTER = new IdentityCryptFilter({ authEvent: 'DocOpen' });
+/**
+ * V4 security handler implementing AES-128-CBC encryption with crypt filters.
+ * Supports different encryption methods for strings, streams, and embedded files (PDF 1.5).
+ *
+ * @example
+ * ```typescript
+ * const handler = new PdfV4SecurityHandler({
+ *     password: 'user123',
+ *     ownerPassword: 'admin456'
+ * })
+ * handler.setCryptFilter('StmFilter', new AesV2CryptFilter({ authEvent: 'DocOpen' }))
+ * ```
+ */
+export class PdfV4SecurityHandler extends PdfV2SecurityHandler {
+    /** Map of named crypt filters. */
+    cryptFilters = new Map([
+        ['Identity', IDENTITY_CRYPT_FILTER],
+    ]);
+    /** Mapping of content types to crypt filter names. */
+    cryptFiltersByType = {};
+    /**
+     * Creates a new V4 security handler with AES-128 encryption.
+     *
+     * @param options - Configuration options for the handler.
+     */
+    constructor(options) {
+        super(options);
+        this.setCryptFilter('StdCF', new AesV2CryptFilter({
+            authEvent: 'DocOpen',
+        }));
+        this.setCryptFilterForType('stream', 'StdCF');
+        this.setCryptFilterForType('string', 'StdCF');
+    }
+    /**
+     * Gets a crypt filter by name.
+     *
+     * @param name - The crypt filter name.
+     * @returns The crypt filter, or undefined if not found.
+     */
+    getCryptFilter(name) {
+        return this.cryptFilters.get(name);
+    }
+    /**
+     * Gets the crypt filter assigned to a content type.
+     *
+     * @param type - The content type ('string', 'stream', or 'file').
+     * @returns The assigned crypt filter, or null if none.
+     */
+    getCryptFilterByType(type) {
+        const name = this.cryptFiltersByType[type];
+        if (name) {
+            return this.cryptFilters.get(name) || null;
+        }
+        return null;
+    }
+    /**
+     * Assigns a crypt filter to a content type.
+     *
+     * @param type - The content type.
+     * @param name - The crypt filter name.
+     */
+    setCryptFilterForType(type, name) {
+        this.cryptFiltersByType[type] = name;
+    }
+    /**
+     * Registers a named crypt filter.
+     *
+     * @param name - The filter name.
+     * @param filter - The crypt filter instance.
+     */
+    setCryptFilter(name, filter) {
+        filter.setSecurityHandler(this);
+        this.cryptFilters.set(name, filter);
+    }
+    /**
+     * Gets the encryption revision number.
+     *
+     * @returns 4 for V4 encryption.
+     */
+    getRevision() {
+        return 4;
+    }
+    /**
+     * Gets the encryption version number.
+     *
+     * @returns 4 for crypt filter-based encryption.
+     */
+    getVersion() {
+        return 4;
+    }
+    /**
+     * 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.
+     * @throws Error if object or generation number is invalid.
+     */
+    async computeObjectKey(objectNumber, generationNumber, algorithm) {
+        assert(objectNumber !== undefined, 'Object number is required to derive the key');
+        assert(generationNumber !== undefined, 'Generation number is required to derive the key');
+        assert(objectNumber > 0, 'Object number cannot be zero or negative');
+        assert(generationNumber >= 0, 'Generation number cannot be negative');
+        this.masterKey ||= await this.computeMasterKey();
+        const key = await deriveObjectKey(this.masterKey, objectNumber, generationNumber, algorithm === 'AES-128-CBC');
+        return key;
+    }
+    /**
+     * Gets an AES-128 cipher for the specified object.
+     *
+     * @param objectNumber - The PDF object number.
+     * @param generationNumber - The PDF generation number.
+     * @returns An AES-128 cipher instance.
+     */
+    async getCipher(objectNumber, generationNumber) {
+        const key = await this.computeObjectKey(objectNumber, generationNumber);
+        return aes128(key);
+    }
+    /**
+     * Reads encryption parameters and crypt filter definitions from the dictionary.
+     *
+     * @param encryptionDictionary - The encryption dictionary from the PDF.
+     */
+    readEncryptionDictionary(encryptionDictionary) {
+        super.readEncryptionDictionary(encryptionDictionary);
+        if (encryptionDictionary.get('CF')) {
+            const cfDict = encryptionDictionary.get('CF');
+            assert(cfDict instanceof PdfDictionary, 'CF must be a dictionary');
+            const cfEntries = cfDict.values;
+            for (const [key, cf] of Object.entries(cfEntries)) {
+                assert(cf instanceof PdfDictionary, 'Crypt filter must be a dictionary');
+                const cfm = cf.get('CFM');
+                const authEvent = cf.get('AuthEvent');
+                const length = cf.get('Length');
+                assertIfDefined(cfm, cfm instanceof PdfName, 'CFM must be a name');
+                assertIfDefined(authEvent, authEvent instanceof PdfName, 'AuthEvent must be a name');
+                assertIfDefined(length, length instanceof PdfNumber, 'Length must be a number');
+                assert(cfm, 'CFM is required in crypt filter dictionary');
+                assert(authEvent, 'AuthEvent is required in crypt filter dictionary');
+                if (cfm.value === 'None') {
+                    this.setCryptFilter(key, new IdentityCryptFilter({
+                        authEvent: authEvent.value,
+                    }));
+                }
+                else if (cfm.value === 'V2') {
+                    this.setCryptFilter(key, new V2CryptFilter({
+                        authEvent: authEvent.value,
+                        length: length.value,
+                    }));
+                }
+                else if (cfm.value === 'AESV2') {
+                    this.setCryptFilter(key, new AesV2CryptFilter({
+                        authEvent: authEvent.value,
+                    }));
+                }
+                else if (cfm.value === 'AESV3') {
+                    this.setCryptFilter(key, new AesV3CryptFilter({
+                        authEvent: authEvent.value,
+                    }));
+                }
+                else {
+                    throw new Error(`Unsupported CFM value: ${cfm.value}`);
+                }
+            }
+        }
+        if (encryptionDictionary.values['StmF']) {
+            const stmF = encryptionDictionary.values['StmF'];
+            assert(stmF instanceof PdfName, 'StmF must be a name');
+            assert(this.cryptFilters.has(stmF.value), `StmF references unknown crypt filter: ${stmF.value}`);
+            this.setCryptFilterForType('stream', stmF.value);
+        }
+        if (encryptionDictionary.values['StrF']) {
+            const strF = encryptionDictionary.values['StrF'];
+            assert(strF instanceof PdfName, 'StrF must be a name');
+            assert(this.cryptFilters.has(strF.value), `StrF references unknown crypt filter: ${strF.value}`);
+            this.setCryptFilterForType('string', strF.value);
+        }
+        if (encryptionDictionary.values['EFF']) {
+            const eff = encryptionDictionary.values['EFF'];
+            assert(eff instanceof PdfName, 'EFF must be a name');
+            assert(this.cryptFilters.has(eff.value), `EFF references unknown crypt filter: ${eff.value}`);
+            this.setCryptFilterForType('file', eff.value);
+        }
+    }
+    /**
+     * Writes the encryption dictionary including crypt filter definitions.
+     */
+    async write() {
+        await super.write();
+        const dict = this.dict;
+        const cfs = {};
+        this.cryptFilters.forEach((cf, name) => {
+            if (cf instanceof IdentityCryptFilter) {
+                // The Identity crypt filter is implicit and should not be included
+                return;
+            }
+            cfs[name] = cf.toDictionary();
+        });
+        if (Object.keys(cfs).length > 0) {
+            dict.set('CF', new PdfDictionary(cfs));
+        }
+        if (this.cryptFiltersByType.stream) {
+            dict.set('StmF', new PdfName(this.cryptFiltersByType.stream));
+        }
+        if (this.cryptFiltersByType.string) {
+            dict.set('StrF', new PdfName(this.cryptFiltersByType.string));
+        }
+        if (this.cryptFiltersByType.file) {
+            dict.set('EFF', new PdfName(this.cryptFiltersByType.file));
+        }
+    }
+    /**
+     * Encrypts data using the appropriate crypt filter for the content 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.
+     */
+    encrypt(type, data, objectNumber, generationNumber) {
+        const cryptFilter = this.getCryptFilterByType(type);
+        if (cryptFilter) {
+            return cryptFilter.encrypt(data, objectNumber, generationNumber);
+        }
+        return super.encrypt(type, data, objectNumber, generationNumber);
+    }
+    /**
+     * Decrypts data using the appropriate crypt filter for the content 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.
+     */
+    decrypt(type, data, objectNumber, generationNumber) {
+        const cryptFilter = this.getCryptFilterByType(type);
+        if (cryptFilter) {
+            return cryptFilter.decrypt(data, objectNumber, generationNumber);
+        }
+        return super.decrypt(type, data, objectNumber, generationNumber);
+    }
+}

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

@@ -0,0 +1,112 @@
+import { ByteArray } from '../../types';
+import { PdfEncryptionDictionary } from '../types';
+import { PdfV4SecurityHandler } from './v4';
+import { PdfStandardSecurityHandlerOptions } from './base';
+import { Cipher } from '../../crypto/types';
+/**
+ * V5 security handler implementing AES-256-CBC encryption.
+ * This is the most secure encryption method (PDF 2.0).
+ *
+ * @example
+ * ```typescript
+ * const handler = new PdfV5SecurityHandler({
+ *     password: 'strongPassword123',
+ *     ownerPassword: 'adminPassword456'
+ * })
+ * ```
+ */
+export declare class PdfV5SecurityHandler extends PdfV4SecurityHandler {
+    /** User encrypted file key (UE value). */
+    protected userEncryptedFileKey?: ByteArray;
+    /** Owner encrypted file key (OE value). */
+    protected ownerEncryptedFileKey?: ByteArray;
+    /** Permissions entry (Perms value). */
+    protected perms?: ByteArray;
+    /** Promise resolving to the file encryption key. */
+    protected fileKey?: Promise<ByteArray>;
+    /**
+     * Creates a new V5 security handler with AES-256 encryption.
+     *
+     * @param options - Configuration options including optional pre-computed keys.
+     */
+    constructor(options: PdfStandardSecurityHandlerOptions & {
+        userEncryptedFileKey?: ByteArray;
+        ownerEncryptedFileKey?: ByteArray;
+    });
+    /**
+     * Checks if the handler is ready (has user encrypted file key).
+     *
+     * @returns True if the handler has the required keys.
+     */
+    isReady(): boolean;
+    /**
+     * Initializes encryption keys, either deriving from existing values or generating new ones.
+     */
+    protected initKeys(): Promise<void>;
+    /**
+     * Computes the master encryption key.
+     *
+     * @returns The file encryption key.
+     * @throws Error if file key is not initialized.
+     */
+    protected computeMasterKey(): Promise<ByteArray>;
+    /**
+     * Builds the Perms entry for the encryption dictionary.
+     *
+     * @param flags - The permission flags.
+     * @param encryptMetadata - Whether metadata is encrypted.
+     * @param fileKey - The file encryption key.
+     * @returns The encrypted permissions entry.
+     */
+    private buildPermsEntry;
+    /**
+     * Gets the encryption key length in bits.
+     *
+     * @returns 256 for V5 encryption.
+     */
+    getKeyBits(): number;
+    /**
+     * Gets an AES-256 cipher.
+     *
+     * @returns An AES-256 cipher instance.
+     */
+    protected getCipher(): Promise<Cipher>;
+    /**
+     * Gets the encryption version number.
+     *
+     * @returns 5 for AES-256 encryption.
+     */
+    getVersion(): number;
+    /**
+     * Gets the encryption revision number.
+     *
+     * @returns 6 for V5 encryption.
+     */
+    getRevision(): number;
+    /**
+     * Writes the encryption dictionary including V5-specific entries.
+     *
+     * @throws Error if required keys are not computed.
+     */
+    write(): Promise<void>;
+    /**
+     * Reads V5-specific encryption parameters from the dictionary.
+     *
+     * @param encryptionDictionary - The encryption dictionary from the PDF.
+     * @throws Error if required entries are missing or invalid.
+     */
+    readEncryptionDictionary(encryptionDictionary: PdfEncryptionDictionary): void;
+    /**
+     * Computes the object encryption key (same as master key for V5).
+     *
+     * @returns The master encryption key.
+     */
+    computeObjectKey(): Promise<ByteArray>;
+    /**
+     * Recovers the user password from the owner password.
+     * Not supported for AES-256 encryption.
+     *
+     * @throws Error always, as this operation is not supported for V5.
+     */
+    recoverUserPassword(ownerPassword?: ByteArray | string): Promise<string>;
+}