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

package/dist/security/handlers/v5.js

@@ -0,0 +1,210 @@
+import { aes256 } from '../../crypto/ciphers/aes256';
+import { getFileKey } from '../../crypto/key-derivation/key-derivation-aes256';
+import { generateOandOe, generateUandUe, } from '../../crypto/key-gen/key-gen-aes256';
+import { aes256ecbEncrypt, getRandomBytes } from '../../utils/algos';
+import { assert } from '../../utils/assert';
+import { PdfV4SecurityHandler } from './v4';
+import { AesV3CryptFilter } from '../crypt-filters/aesv3';
+import { PdfHexadecimal } from '../../core/objects/pdf-hexadecimal';
+import { PdfString } from '../../core/objects/pdf-string';
+/**
+ * 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 class PdfV5SecurityHandler extends PdfV4SecurityHandler {
+    /** User encrypted file key (UE value). */
+    userEncryptedFileKey;
+    /** Owner encrypted file key (OE value). */
+    ownerEncryptedFileKey;
+    /** Permissions entry (Perms value). */
+    perms;
+    /** Promise resolving to the file encryption key. */
+    fileKey;
+    /**
+     * Creates a new V5 security handler with AES-256 encryption.
+     *
+     * @param options - Configuration options including optional pre-computed keys.
+     */
+    constructor(options) {
+        super(options);
+        this.userEncryptedFileKey = options.userEncryptedFileKey;
+        this.ownerEncryptedFileKey = options.ownerEncryptedFileKey;
+        this.setCryptFilter('StdCF', new AesV3CryptFilter({
+            authEvent: 'DocOpen',
+        }));
+        this.setCryptFilterForType('stream', 'StdCF');
+        this.setCryptFilterForType('string', 'StdCF');
+    }
+    /**
+     * Checks if the handler is ready (has user encrypted file key).
+     *
+     * @returns True if the handler has the required keys.
+     */
+    isReady() {
+        return !!this.userEncryptedFileKey;
+    }
+    /**
+     * Initializes encryption keys, either deriving from existing values or generating new ones.
+     */
+    async initKeys() {
+        this.fileKey ||= (async () => {
+            if (this.userEncryptedFileKey &&
+                this.ownerEncryptedFileKey &&
+                this.userKey &&
+                this.ownerKey &&
+                this.perms) {
+                const derivedFileKey = await getFileKey(this.password, this.ownerPassword ?? this.password, this.userKey, this.userEncryptedFileKey, this.ownerKey, this.ownerEncryptedFileKey);
+                return derivedFileKey;
+            }
+            const fileKey = getRandomBytes(32);
+            const { U, UE } = await generateUandUe(this.password, fileKey);
+            this.userKey = U;
+            this.userEncryptedFileKey = UE;
+            const { O, OE } = await generateOandOe(this.ownerPassword ?? this.password, U, fileKey);
+            this.ownerKey = O;
+            this.ownerEncryptedFileKey = OE;
+            this.perms = await this.buildPermsEntry(this.permissions ?? 0, this.encryptMetadata, fileKey);
+            return fileKey;
+        })();
+        await this.fileKey;
+    }
+    /**
+     * Computes the master encryption key.
+     *
+     * @returns The file encryption key.
+     * @throws Error if file key is not initialized.
+     */
+    async computeMasterKey() {
+        await this.initKeys();
+        if (!this.fileKey) {
+            throw new Error('File key not initialized');
+        }
+        return this.fileKey;
+    }
+    /**
+     * 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.
+     */
+    async buildPermsEntry(flags, encryptMetadata, fileKey) {
+        const block = new Uint8Array(16);
+        // a + b) permissions + 0xFFFFFFFF (little-endian)
+        const view = new DataView(block.buffer);
+        view.setUint32(0, flags, true); // little-endian
+        view.setUint32(4, 0xffffffff, true); // upper 32 bits
+        // c) "T" or "F"
+        block[8] = encryptMetadata ? 'T'.charCodeAt(0) : 'F'.charCodeAt(0);
+        // d) "adb"
+        block[9] = 'a'.charCodeAt(0);
+        block[10] = 'd'.charCodeAt(0);
+        block[11] = 'b'.charCodeAt(0);
+        // e) random 4 bytes
+        const randomBytes = getRandomBytes(4);
+        block.set(randomBytes, 12);
+        return await aes256ecbEncrypt(fileKey, block);
+    }
+    /**
+     * Gets the encryption key length in bits.
+     *
+     * @returns 256 for V5 encryption.
+     */
+    getKeyBits() {
+        return 256;
+    }
+    /**
+     * Gets an AES-256 cipher.
+     *
+     * @returns An AES-256 cipher instance.
+     */
+    async getCipher() {
+        this.masterKey ||= await this.computeMasterKey();
+        return aes256(this.masterKey);
+    }
+    /**
+     * Gets the encryption version number.
+     *
+     * @returns 5 for AES-256 encryption.
+     */
+    getVersion() {
+        return 5;
+    }
+    /**
+     * Gets the encryption revision number.
+     *
+     * @returns 6 for V5 encryption.
+     */
+    getRevision() {
+        return 6;
+    }
+    /**
+     * Writes the encryption dictionary including V5-specific entries.
+     *
+     * @throws Error if required keys are not computed.
+     */
+    async write() {
+        await super.write();
+        const dict = this.dict;
+        assert(this.userEncryptedFileKey, 'User Encrypted File Key not set');
+        assert(this.ownerEncryptedFileKey, 'Owner Encrypted File Key not set');
+        assert(this.perms, 'Permissions entry not set');
+        dict.set('UE', new PdfString(this.userEncryptedFileKey));
+        dict.set('OE', new PdfString(this.ownerEncryptedFileKey));
+        dict.set('Perms', new PdfString(this.perms));
+    }
+    /**
+     * 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) {
+        super.readEncryptionDictionary(encryptionDictionary);
+        const { values } = encryptionDictionary;
+        assert(values['UE'] instanceof PdfHexadecimal ||
+            values['UE'] instanceof PdfString, 'Invalid or missing /UE entry');
+        assert(values['OE'] instanceof PdfHexadecimal ||
+            values['OE'] instanceof PdfString, 'Invalid or missing /OE entry');
+        assert(values['Perms'] instanceof PdfString ||
+            values['Perms'] instanceof PdfHexadecimal, 'Invalid or missing /Perms entry');
+        this.userEncryptedFileKey =
+            values['UE'] instanceof PdfHexadecimal
+                ? values['UE'].bytes
+                : values['UE'].raw;
+        this.ownerEncryptedFileKey =
+            values['OE'] instanceof PdfHexadecimal
+                ? values['OE'].bytes
+                : values['OE'].raw;
+        this.perms =
+            values['Perms'] instanceof PdfHexadecimal
+                ? values['Perms'].bytes
+                : values['Perms'].raw;
+    }
+    /**
+     * Computes the object encryption key (same as master key for V5).
+     *
+     * @returns The master encryption key.
+     */
+    async computeObjectKey() {
+        return await this.computeMasterKey();
+    }
+    /**
+     * 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.
+     */
+    async recoverUserPassword(ownerPassword) {
+        throw new Error('Recovering user password from owner password is not supported for AES-256');
+    }
+}

package/{packages/pdf-lite/src/security/types.ts → dist/security/types.d.ts}

@@ -1,81 +1,73 @@
-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 { PdfString } from '../core/objects/pdf-string'
-import { ByteArray } from '../types'
-
+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 { PdfString } from '../core/objects/pdf-string';
+import { ByteArray } from '../types';
 /**
  * Represents the PDF document ID array containing two hexadecimal identifiers.
  * The first element is the permanent ID assigned when the document is created,
  * and the second is updated when the document is modified.
  */
-export type PdfId = PdfArray<PdfHexadecimal>
-
+export type PdfId = PdfArray<PdfHexadecimal>;
 /**
  * Dictionary defining a crypt filter for PDF encryption.
  * Specifies the encryption method and authentication event trigger.
  */
 export type PdfCryptFilterDictionary = PdfDictionary<{
-    AuthEvent: PdfName<'DocOpen' | 'EFOpen'>
-    CFM: PdfName<'None' | 'V2' | 'AESV2' | 'AESV3'>
-    Length?: PdfNumber
-}>
-
+    AuthEvent: PdfName<'DocOpen' | 'EFOpen'>;
+    CFM: PdfName<'None' | 'V2' | 'AESV2' | 'AESV3'>;
+    Length?: PdfNumber;
+}>;
 /**
  * The encryption dictionary stored in the PDF trailer.
  * Contains all encryption parameters including filter type, version, revision,
  * owner/user keys, permissions, and crypt filter configurations.
  */
 export type PdfEncryptionDictionary = PdfDictionary<{
-    Filter: PdfName<'Standard' | 'Adobe.PubSec'>
-    SubFilter?: PdfName<'adbe.pkcs7.s3' | 'adbe.pkcs7.s4' | 'adbe.pkcs7.s5'>
-    V: PdfNumber
-    R: PdfNumber
-    O: PdfString | PdfHexadecimal
-    OE?: PdfString | PdfHexadecimal
-    U: PdfString | PdfHexadecimal
-    UE?: PdfString | PdfHexadecimal
-    P: PdfNumber
-    Perms?: PdfString | PdfHexadecimal
-    Length: PdfNumber
+    Filter: PdfName<'Standard' | 'Adobe.PubSec'>;
+    SubFilter?: PdfName<'adbe.pkcs7.s3' | 'adbe.pkcs7.s4' | 'adbe.pkcs7.s5'>;
+    V: PdfNumber;
+    R: PdfNumber;
+    O: PdfString | PdfHexadecimal;
+    OE?: PdfString | PdfHexadecimal;
+    U: PdfString | PdfHexadecimal;
+    UE?: PdfString | PdfHexadecimal;
+    P: PdfNumber;
+    Perms?: PdfString | PdfHexadecimal;
+    Length: PdfNumber;
     CF?: PdfDictionary<{
-        [key: string]: PdfCryptFilterDictionary
-    }>
-    StmF?: PdfName
-    StrF?: PdfName
-    EFF?: PdfName
-    EncryptMetadata?: PdfBoolean
-    ID?: PdfArray<PdfHexadecimal>
-    Recipients?: PdfArray<PdfHexadecimal>
-}>
-
+        [key: string]: PdfCryptFilterDictionary;
+    }>;
+    StmF?: PdfName;
+    StrF?: PdfName;
+    EFF?: PdfName;
+    EncryptMetadata?: PdfBoolean;
+    ID?: PdfArray<PdfHexadecimal>;
+    Recipients?: PdfArray<PdfHexadecimal>;
+}>;
 /**
  * An indirect object containing the encryption dictionary.
  */
-export type PdfEncryptionDictionaryObject =
-    PdfIndirectObject<PdfEncryptionDictionary>
-
+export type PdfEncryptionDictionaryObject = PdfIndirectObject<PdfEncryptionDictionary>;
 /**
  * Specifies the type of content being encrypted.
  * - 'string': PDF string objects
  * - 'stream': PDF stream objects
  * - 'file': Embedded file streams
  */
-export type CryptFilterType = 'string' | 'stream' | 'file'
-
+export type CryptFilterType = 'string' | 'stream' | 'file';
 /**
  * Recipient information for public key encryption.
  * Contains the certificate for encryption and optional private key for decryption.
  */
 export type PdfEncryptionRecipient = {
-    certificate?: ByteArray
-    privateKey?: ByteArray
-}
-
+    certificate?: ByteArray;
+    privateKey?: ByteArray;
+};
 /**
  * Supported encryption algorithm types.
  * - 'RC4-40': 40-bit RC4 encryption (weak, legacy)
@@ -84,75 +76,61 @@ export type PdfEncryptionRecipient = {
  * - 'AES-256-CBC': 256-bit AES in CBC mode (recommended)
  * - 'none': No encryption (identity filter)
  */
-export type PdfEncryptionAlgorithmType =
-    | 'RC4-40'
-    | 'RC4-128'
-    | 'AES-128-CBC'
-    | 'AES-256-CBC'
-    | 'none'
-
+export type PdfEncryptionAlgorithmType = 'RC4-40' | 'RC4-128' | 'AES-128-CBC' | 'AES-256-CBC' | 'none';
 /**
  * RC4-40 encryption configuration.
  */
 type Rc40 = {
-    default: 'RC4-40'
-}
-
+    default: 'RC4-40';
+};
 /**
  * RC4-128 encryption configuration.
  */
 type Rc128 = {
-    default: 'RC4-128'
-}
-
+    default: 'RC4-128';
+};
 /**
  * AES-128 encryption configuration with optional per-type crypt filters.
  */
 type Aes128WithCryptFilters = {
-    default: 'AES-128-CBC'
-    streams?: 'AES-128-CBC' | 'RC4-128' | 'RC4-40' | 'none'
-    strings?: 'AES-128-CBC' | 'RC4-128' | 'RC4-40' | 'none'
-}
-
+    default: 'AES-128-CBC';
+    streams?: 'AES-128-CBC' | 'RC4-128' | 'RC4-40' | 'none';
+    strings?: 'AES-128-CBC' | 'RC4-128' | 'RC4-40' | 'none';
+};
 /**
  * AES-256 encryption configuration with optional per-type crypt filters.
  */
 type Aes256 = {
-    default: 'AES-256-CBC' | 'none'
-    streams?: 'AES-256-CBC' | 'AES-128-CBC' | 'RC4-128' | 'none'
-    files?: 'AES-256-CBC' | 'AES-128-CBC' | 'RC4-128' | 'none'
-    strings?: 'AES-256-CBC' | 'AES-128-CBC' | 'RC4-128' | 'none'
-}
-
+    default: 'AES-256-CBC' | 'none';
+    streams?: 'AES-256-CBC' | 'AES-128-CBC' | 'RC4-128' | 'none';
+    files?: 'AES-256-CBC' | 'AES-128-CBC' | 'RC4-128' | 'none';
+    strings?: 'AES-256-CBC' | 'AES-128-CBC' | 'RC4-128' | 'none';
+};
 /**
  * Union of all encryption algorithm configuration options.
  */
-export type PdfEncryptionAlgorithmOptions =
-    | Rc40
-    | Rc128
-    | Aes128WithCryptFilters
-    | Aes256
-
+export type PdfEncryptionAlgorithmOptions = Rc40 | Rc128 | Aes128WithCryptFilters | Aes256;
 /**
  * Options for configuring PDF encryption.
  * Includes encryption method, passwords, document ID, and permission settings.
  */
 export type PdfEncryptionOptions = {
-    method?: PdfEncryptionAlgorithmOptions
-    password?: ByteArray | string
-    ownerPassword?: ByteArray | string
-    documentId?: PdfId | ByteArray | string
-    encryptMetadata?: boolean
-    recipients?: PdfEncryptionRecipient[]
+    method?: PdfEncryptionAlgorithmOptions;
+    password?: ByteArray | string;
+    ownerPassword?: ByteArray | string;
+    documentId?: PdfId | ByteArray | string;
+    encryptMetadata?: boolean;
+    recipients?: PdfEncryptionRecipient[];
     permissions?: {
-        print?: boolean
-        modify?: boolean
-        copy?: boolean
-        annotate?: boolean
-        fill?: boolean
-        extract?: boolean
-        assemble?: boolean
-        printHighQuality?: boolean
-        all?: boolean
-    }
-}
+        print?: boolean;
+        modify?: boolean;
+        copy?: boolean;
+        annotate?: boolean;
+        fill?: boolean;
+        extract?: boolean;
+        assemble?: boolean;
+        printHighQuality?: boolean;
+        all?: boolean;
+    };
+};
+export {};

package/dist/security/types.js

@@ -0,0 +1 @@
+export {};

package/dist/signing/document-security-store.d.ts

@@ -0,0 +1,108 @@
+import { PdfArray } from '../core/objects/pdf-array';
+import { PdfDate } from '../core/objects/pdf-date';
+import { PdfDictionary } from '../core/objects/pdf-dictionary';
+import { PdfIndirectObject } from '../core/objects/pdf-indirect-object';
+import { PdfName } from '../core/objects/pdf-name';
+import { PdfObjectReference } from '../core/objects/pdf-object-reference';
+import { PdfStream } from '../core/objects/pdf-stream';
+import { PdfString } from '../core/objects/pdf-string';
+import { PdfDocument } from '../pdf/pdf-document';
+import { ByteArray } from '../types';
+import { RevocationInfo } from './types';
+/**
+ * Indirect object containing a certificate stream.
+ */
+export declare class PdfCertObject extends PdfIndirectObject<PdfStream> {
+}
+/**
+ * Indirect object containing a CRL stream.
+ */
+export declare class PdfCrlObject extends PdfIndirectObject<PdfStream> {
+}
+/**
+ * Indirect object containing an OCSP response stream.
+ */
+export declare class PdfOcspObject extends PdfIndirectObject<PdfStream> {
+}
+/**
+ * Validation Related Information (VRI) dictionary.
+ * Associates revocation data with specific certificate hashes.
+ */
+export type PdfVriObject = PdfIndirectObject<PdfDictionary<{
+    [CertHash: string]: PdfDictionary<{
+        Type?: PdfName<'VRI'>;
+        Cert?: PdfObjectReference;
+        OCSP?: PdfObjectReference;
+        CRL?: PdfObjectReference;
+        TU?: PdfDate;
+        TS?: PdfString;
+    }>;
+}>>;
+/**
+ * Dictionary for the Document Security Store (DSS).
+ * Contains arrays of certificates, CRLs, OCSPs, and VRI entries.
+ */
+export declare class PdfDocumentSecurityStoreDictionary extends PdfDictionary<{
+    Type?: PdfName<'DSS'>;
+    VRI?: PdfObjectReference;
+    OCSPs?: PdfArray<PdfObjectReference>;
+    CRLs?: PdfArray<PdfObjectReference>;
+    Certs?: PdfArray<PdfObjectReference>;
+}> {
+}
+/**
+ * Document Security Store (DSS) object for PAdES LTV signatures.
+ * Stores validation data (certificates, CRLs, OCSPs) for long-term validation.
+ *
+ * @example
+ * ```typescript
+ * const dss = new PdfDocumentSecurityStoreObject(document)
+ * await dss.addCert(certificateBytes)
+ * await dss.addCrl(crlBytes)
+ * await dss.addOcsp(ocspBytes)
+ * ```
+ */
+export declare class PdfDocumentSecurityStoreObject extends PdfIndirectObject<PdfDocumentSecurityStoreDictionary> {
+    /** Reference to the parent document. */
+    private document;
+    /**
+     * Creates a new DSS object.
+     *
+     * @param document - The parent PDF document.
+     * @param content - Optional pre-existing DSS dictionary.
+     */
+    constructor(document: PdfDocument, content?: PdfDocumentSecurityStoreDictionary);
+    /**
+     * Adds an OCSP response to the DSS, avoiding duplicates.
+     *
+     * @param ocsp - The DER-encoded OCSP response.
+     * @returns The created or existing OCSP object.
+     */
+    addOcsp(ocsp: ByteArray): Promise<PdfOcspObject>;
+    /**
+     * Adds a CRL to the DSS, avoiding duplicates.
+     *
+     * @param crl - The DER-encoded CRL.
+     * @returns The created or existing CRL object.
+     */
+    addCrl(crl: ByteArray): Promise<PdfCrlObject>;
+    /**
+     * Adds a certificate to the DSS, avoiding duplicates.
+     *
+     * @param cert - The DER-encoded certificate.
+     * @returns The created or existing certificate object.
+     */
+    addCert(cert: ByteArray): Promise<PdfCertObject>;
+    /**
+     * Adds revocation information (CRLs and OCSPs) to the DSS.
+     *
+     * @param revocationInfo - The revocation information to add.
+     */
+    addRevocationInfo(revocationInfo: RevocationInfo): Promise<void>;
+    /**
+     * Checks if the DSS is empty (contains no certificates, CRLs, or OCSPs).
+     *
+     * @returns True if the DSS has no stored data.
+     */
+    isEmpty(): boolean;
+}