pdf-lite 1.0.0

package/packages/pdf-lite/src/security/crypt-filters/base.ts

@@ -0,0 +1,140 @@
+import { PdfDictionary } from '../../core/objects/pdf-dictionary'
+import { PdfName } from '../../core/objects/pdf-name'
+import { PdfNumber } from '../../core/objects/pdf-number'
+import { Cipher } from '../../crypto/types'
+import { ByteArray } from '../../types'
+import { PdfSecurityHandler } from '../handlers/base'
+import { PdfCryptFilterDictionary } from '../types'
+
+/**
+ * Configuration options for creating a crypt filter.
+ */
+export type CryptFilterOptions = {
+    /** Security handler for key derivation and encryption operations. */
+    securityHandler?: PdfSecurityHandler
+    /** Crypt filter method: 'None' (identity), 'V2' (RC4), 'AESV2' (AES-128), or 'AESV3' (AES-256). */
+    cfm: 'None' | 'V2' | 'AESV2' | 'AESV3'
+    /** Event that triggers authentication: 'DocOpen' or 'EFOpen' (embedded file open). */
+    authEvent: 'DocOpen' | 'EFOpen'
+    /** Key length in bits. */
+    length?: number
+}
+
+/**
+ * Abstract base class for PDF crypt filters.
+ * Crypt filters define how specific types of data (strings, streams, files) are encrypted.
+ *
+ * @example
+ * ```typescript
+ * const filter = new AesV2CryptFilter({ authEvent: 'DocOpen' })
+ * filter.setSecurityHandler(securityHandler)
+ * const encrypted = await filter.encrypt(data, objectNumber, generationNumber)
+ * ```
+ */
+export abstract class PdfCryptFilter {
+    /** Crypt filter method identifier. */
+    cfm: 'None' | 'V2' | 'AESV2' | 'AESV3'
+    /** Authentication event trigger. */
+    authEvent: 'DocOpen' | 'EFOpen'
+    /** Key length in bits. */
+    length: number
+    /** Security handler for cryptographic operations. */
+    protected securityHandler?: PdfSecurityHandler
+
+    /**
+     * Creates a new crypt filter with the specified options.
+     *
+     * @param options - Configuration options for the crypt filter.
+     */
+    constructor(options: CryptFilterOptions) {
+        const { cfm, authEvent, length, securityHandler } = options
+
+        this.securityHandler = securityHandler
+        this.cfm = cfm
+        this.authEvent = authEvent
+        this.length = length ?? 0
+    }
+
+    /**
+     * Sets the security handler for this crypt filter.
+     *
+     * @param handler - The security handler to use for key derivation.
+     */
+    setSecurityHandler(handler: PdfSecurityHandler) {
+        this.securityHandler = handler
+    }
+
+    /**
+     * Gets the current security handler.
+     *
+     * @returns The security handler, or undefined if not set.
+     */
+    getSecurityHandler(): PdfSecurityHandler | undefined {
+        return this.securityHandler
+    }
+
+    /**
+     * Gets a cipher instance for encrypting/decrypting data.
+     *
+     * @param objectNumber - The PDF object number for key derivation.
+     * @param generationNumber - The PDF generation number for key derivation.
+     * @returns A cipher instance for encryption/decryption operations.
+     */
+    abstract getCipher(
+        objectNumber?: number,
+        generationNumber?: number,
+    ): Promise<Cipher>
+
+    /**
+     * Encrypts data using this crypt filter.
+     *
+     * @param data - The data to encrypt.
+     * @param objectNumber - The PDF object number for key derivation.
+     * @param generationNumber - The PDF generation number for key derivation.
+     * @returns The encrypted data.
+     */
+    async encrypt(
+        data: ByteArray,
+        objectNumber?: number,
+        generationNumber?: number,
+    ): Promise<ByteArray> {
+        const cipher = await this.getCipher(objectNumber, generationNumber)
+        return cipher.encrypt(data)
+    }
+
+    /**
+     * Decrypts data using this crypt filter.
+     *
+     * @param data - The data to decrypt.
+     * @param objectNumber - The PDF object number for key derivation.
+     * @param generationNumber - The PDF generation number for key derivation.
+     * @returns The decrypted data.
+     */
+    async decrypt(
+        data: ByteArray,
+        objectNumber?: number,
+        generationNumber?: number,
+    ): Promise<ByteArray> {
+        const cipher = await this.getCipher(objectNumber, generationNumber)
+        return cipher.decrypt(data)
+    }
+
+    /**
+     * Converts this crypt filter to a PDF dictionary representation.
+     *
+     * @returns The crypt filter dictionary.
+     */
+    toDictionary(): PdfCryptFilterDictionary {
+        const dict: PdfCryptFilterDictionary = new PdfDictionary({
+            AuthEvent: new PdfName(this.authEvent),
+            CFM: new PdfName(this.cfm),
+            ...(this.length
+                ? {
+                      Length: new PdfNumber(this.length),
+                  }
+                : {}),
+        })
+
+        return dict
+    }
+}

package/packages/pdf-lite/src/security/crypt-filters/identity.ts

@@ -0,0 +1,40 @@
+import { Cipher } from '../../crypto/types'
+import { ByteArray } from '../../types'
+import { PdfCryptFilter, CryptFilterOptions } from './base'
+
+/**
+ * Identity crypt filter that passes data through without encryption.
+ * Used when no encryption is needed for specific content types.
+ *
+ * @example
+ * ```typescript
+ * const filter = new IdentityCryptFilter({ authEvent: 'DocOpen' })
+ * const output = await filter.encrypt(data) // Returns data unchanged
+ * ```
+ */
+export class IdentityCryptFilter extends PdfCryptFilter {
+    /**
+     * Creates a new identity crypt filter.
+     *
+     * @param options - Configuration options with authentication event.
+     */
+    constructor(options: { authEvent: CryptFilterOptions['authEvent'] }) {
+        super({ ...options, cfm: 'None' })
+    }
+
+    /**
+     * Gets a passthrough cipher that returns data unchanged.
+     *
+     * @returns A cipher that performs no encryption or decryption.
+     */
+    async getCipher(): Promise<Cipher> {
+        return {
+            encrypt: async (data: ByteArray) => {
+                return data
+            },
+            decrypt: async (data: ByteArray) => {
+                return data
+            },
+        }
+    }
+}

package/packages/pdf-lite/src/security/crypt-filters/v2.ts

@@ -0,0 +1,59 @@
+import { rc4 } from '../../crypto/ciphers/rc4.js'
+import { Cipher } from '../../crypto/types.js'
+import { PdfCryptFilter, CryptFilterOptions } from './base'
+
+/**
+ * V2 crypt filter using RC4 encryption.
+ * Implements the legacy RC4 stream cipher for PDF encryption.
+ *
+ * @example
+ * ```typescript
+ * const filter = new V2CryptFilter({
+ *     authEvent: 'DocOpen',
+ *     securityHandler,
+ *     length: 128
+ * })
+ * const encrypted = await filter.encrypt(data, objectNumber, generationNumber)
+ * ```
+ */
+export class V2CryptFilter extends PdfCryptFilter {
+    /**
+     * Creates a new V2 crypt filter with RC4 encryption.
+     *
+     * @param options - Configuration options including key length.
+     */
+    constructor(options: {
+        authEvent: CryptFilterOptions['authEvent']
+        securityHandler?: CryptFilterOptions['securityHandler']
+        length?: number
+    }) {
+        super({ ...options, cfm: 'V2', length: options.length || 40 })
+    }
+
+    /**
+     * Gets an RC4 cipher for encryption/decryption.
+     *
+     * @param objectNumber - The PDF object number for key derivation.
+     * @param generationNumber - The PDF generation number for key derivation.
+     * @returns An RC4 cipher instance.
+     * @throws Error if security handler is not set.
+     */
+    async getCipher(
+        objectNumber?: number,
+        generationNumber?: number,
+    ): Promise<Cipher> {
+        const securityHandler = this.securityHandler
+        if (!securityHandler) {
+            throw new Error('Missing security handler for V2 crypt filter')
+        }
+
+        const objectKey = await securityHandler.computeObjectKey(
+            objectNumber,
+            generationNumber,
+        )
+
+        return rc4(
+            objectKey.slice(0, this.length / 8), // V2 needs a key of specified length in bits
+        )
+    }
+}