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

package/packages/pdf-lite/src/security/handlers/base.ts

@@ -1,625 +0,0 @@
-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 { PdfObject } from '../../core/objects/pdf-object'
-import { PdfStream } from '../../core/objects/pdf-stream'
-import { PdfString } from '../../core/objects/pdf-string'
-import { Cipher } from '../../crypto/types'
-import { ByteArray, PdfPermissions, PERMISSION_FLAGS } from '../../types'
-import { assert, assertIfDefined } from '../../utils/assert'
-import { stringToBytes } from '../../utils/stringToBytes'
-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 abstract class PdfSecurityHandler {
-    /** The encryption dictionary containing all encryption parameters. */
-    public dict: PdfEncryptionDictionary
-    /** Numeric permission flags. */
-    public permissions: number
-    /** Whether to encrypt document metadata. */
-    public encryptMetadata: boolean
-
-    /**
-     * Creates a new security handler.
-     *
-     * @param options - Configuration options for the security handler.
-     */
-    constructor(options?: PdfSecurityHandlerOptions) {
-        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(): PdfPermissions {
-        const perm: PdfPermissions = {}
-        for (const [key, bit] of Object.entries(PERMISSION_FLAGS) as [
-            keyof PdfPermissions,
-            number,
-        ][]) {
-            perm[key] = (this.permissions & bit) !== 0
-        }
-        return perm
-    }
-
-    /**
-     * 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 {
-        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) as [
-            keyof PdfPermissions,
-            number,
-        ][]) {
-            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: PdfIndirectObject): Promise<void> {
-        const objectNumber = object.objectNumber
-        const generationNumber = object.generationNumber
-
-        const decryptObject = async (obj: PdfObject): Promise<void> => {
-            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: PdfIndirectObject): Promise<void> {
-        const objectNumber = object.objectNumber
-        const generationNumber = object.generationNumber
-
-        const encryptObject = async (obj: PdfObject): Promise<void> => {
-            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)
-    }
-}
-
-/**
- * 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
-}
-
-const DEFAULT_PERMISSIONS: PdfPermissions = {
-    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 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) {
-        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 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 {
-        return 'Standard'
-    }
-
-    /**
-     * Checks if the handler is ready (has document ID).
-     *
-     * @returns True if document ID is set.
-     */
-    isReady(): boolean {
-        return !!this.documentId
-    }
-
-    /**
-     * Sets the document ID for key derivation.
-     *
-     * @param id - The document ID array.
-     */
-    setDocumentId(id: PdfId): void {
-        this.documentId = id
-    }
-
-    /**
-     * Gets the document ID.
-     *
-     * @returns The document ID, or undefined if not set.
-     */
-    getDocumentId(): PdfId | undefined {
-        return this.documentId
-    }
-
-    /**
-     * Sets the user password.
-     *
-     * @param password - The user password string or bytes.
-     */
-    setPassword(password: string | ByteArray): void {
-        this.password =
-            typeof password === 'string' ? stringToBytes(password) : password
-    }
-
-    /**
-     * Sets the owner password.
-     *
-     * @param ownerPassword - The owner password string or bytes.
-     */
-    setOwnerPassword(ownerPassword: string | ByteArray): void {
-        this.ownerPassword =
-            typeof ownerPassword === 'string'
-                ? stringToBytes(ownerPassword)
-                : ownerPassword
-    }
-
-    /**
-     * Checks if metadata encryption is enabled.
-     *
-     * @returns True if metadata should be encrypted.
-     */
-    canEncryptMetadata(): boolean {
-        return this.encryptMetadata
-    }
-
-    /**
-     * Reads encryption parameters from the encryption dictionary.
-     *
-     * @param encryptionDictionary - The encryption dictionary from the PDF.
-     */
-    readEncryptionDictionary(
-        encryptionDictionary: PdfEncryptionDictionary,
-    ): void {
-        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
-    }
-
-    /**
-     * 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 async initKeys(): Promise<void> {
-        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(): Promise<void> {
-        // 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))
-    }
-
-    /**
-     * 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.
-     */
-    async encrypt(
-        type: 'string' | 'stream' | 'file',
-        data: ByteArray,
-        objectNumber?: number,
-        generationNumber?: number,
-    ): Promise<ByteArray> {
-        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: 'string' | 'stream' | 'file',
-        data: ByteArray,
-        objectNumber?: number,
-        generationNumber?: number,
-    ): Promise<ByteArray> {
-        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: ByteArray): void {
-        this.masterKey = masterKey
-    }
-
-    /**
-     * 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>
-}