pdf-lite 1.0.0

package/packages/pdf-lite/src/core/tokens/xref-table-section-start-token.ts

@@ -0,0 +1,31 @@
+import { ByteArray } from '../../types'
+import { stringToBytes } from '../../utils/stringToBytes'
+import { PdfNumberToken } from './number-token'
+import { PdfToken } from './token'
+
+export class PdfXRefTableSectionStartToken extends PdfToken {
+    start: PdfNumberToken
+    count: PdfNumberToken
+
+    constructor(
+        start: number | PdfNumberToken,
+        count: number | PdfNumberToken,
+    ) {
+        super(PdfXRefTableSectionStartToken.toBytes(start, count))
+        this.start =
+            start instanceof PdfNumberToken
+                ? start
+                : new PdfNumberToken({ value: start })
+        this.count =
+            count instanceof PdfNumberToken
+                ? count
+                : new PdfNumberToken({ value: count })
+    }
+
+    private static toBytes(
+        start: PdfNumberToken | number,
+        count: PdfNumberToken | number,
+    ): ByteArray {
+        return stringToBytes(`${start.toString()} ${count.toString()}`)
+    }
+}

package/packages/pdf-lite/src/core/tokens/xref-table-start-token.ts

@@ -0,0 +1,13 @@
+import { stringToBytes } from '../../utils/stringToBytes'
+import { PdfToken } from './token'
+
+const XREF = stringToBytes('xref')
+
+export class PdfXRefTableStartToken extends PdfToken {
+    byteOffset?: number
+
+    constructor(byteOffset?: number) {
+        super(XREF)
+        this.byteOffset = byteOffset
+    }
+}

package/packages/pdf-lite/src/crypto/ciphers/aes128.ts

@@ -0,0 +1,63 @@
+import { ByteArray } from '../../types.js'
+import { aes128cbcDecrypt, aes128cbcEncrypt } from '../../utils/algos.js'
+import { Cipher } from '../types.js'
+
+/**
+ * Creates an AES-128-CBC cipher for PDF encryption.
+ * The cipher prepends a zero IV to encrypted data during encryption
+ * and extracts the IV from the first 16 bytes during decryption.
+ *
+ * @param key - The 16-byte encryption key.
+ * @returns A Cipher object with encrypt and decrypt methods.
+ * @throws Error if the key is not exactly 16 bytes.
+ *
+ * @example
+ * ```typescript
+ * const cipher = aes128(key)
+ * const encrypted = await cipher.encrypt(plaintext)
+ * const decrypted = await cipher.decrypt(encrypted)
+ * ```
+ */
+export function aes128(key: ByteArray): Cipher {
+    if (key.length !== 16)
+        throw new Error(
+            `AES-128 key must be exactly 16 bytes, got ${key.length}`,
+        )
+
+    const iv = new Uint8Array(16) // Zero IV, as per PDF spec
+
+    return {
+        /**
+         * Encrypts data using AES-128-CBC.
+         * Prepends the IV to the ciphertext.
+         *
+         * @param data - The data to encrypt.
+         * @returns A promise that resolves to IV followed by ciphertext.
+         * @throws Error if the IV is not exactly 16 bytes.
+         */
+        encrypt: async (data: ByteArray): Promise<ByteArray> => {
+            if (iv.length !== 16) throw new Error('IV must be exactly 16 bytes')
+
+            const encrypted = await aes128cbcEncrypt(key, data)
+            const result = new Uint8Array(iv.length + encrypted.length)
+
+            result.set(iv, 0)
+            result.set(encrypted, iv.length)
+
+            return result
+        },
+        /**
+         * Decrypts data using AES-128-CBC.
+         * Extracts the IV from the first 16 bytes of the input.
+         *
+         * @param data - The data to decrypt (IV + ciphertext).
+         * @returns A promise that resolves to the decrypted plaintext.
+         */
+        decrypt: async (data: ByteArray): Promise<ByteArray> => {
+            const iv = data.slice(0, 16)
+            const ciphertext = data.slice(16)
+
+            return await aes128cbcDecrypt(key, ciphertext, iv)
+        },
+    }
+}

package/packages/pdf-lite/src/crypto/ciphers/aes256.ts

@@ -0,0 +1,50 @@
+import { ByteArray } from '../../types.js'
+import { aes256cbcDecrypt, aes256cbcEncrypt } from '../../utils/algos.js'
+import { Cipher } from '../types.js'
+
+/**
+ * Creates an AES-256-CBC cipher for PDF encryption.
+ * The cipher prepends a zero IV to encrypted data during encryption
+ * and extracts the IV from the first 16 bytes during decryption.
+ *
+ * @param key - The 32-byte encryption key.
+ * @returns A Cipher object with encrypt and decrypt methods.
+ *
+ * @example
+ * ```typescript
+ * const cipher = aes256(key)
+ * const encrypted = await cipher.encrypt(plaintext)
+ * const decrypted = await cipher.decrypt(encrypted)
+ * ```
+ */
+export function aes256(key: ByteArray): Cipher {
+    const iv = new Uint8Array(16) // Zero IV, as per PDF spec
+    return {
+        /**
+         * Encrypts data using AES-256-CBC.
+         * Prepends the IV to the ciphertext.
+         *
+         * @param data - The data to encrypt.
+         * @returns A promise that resolves to IV followed by ciphertext.
+         */
+        encrypt: async (data: ByteArray): Promise<ByteArray> => {
+            const encrypted = await aes256cbcEncrypt(key, data, iv)
+            const result = new Uint8Array(iv.length + encrypted.length)
+            result.set(iv, 0)
+            result.set(encrypted, iv.length)
+            return result
+        },
+        /**
+         * Decrypts data using AES-256-CBC.
+         * Extracts the IV from the first 16 bytes of the input.
+         *
+         * @param data - The data to decrypt (IV + ciphertext).
+         * @returns A promise that resolves to the decrypted plaintext.
+         */
+        decrypt: async (data: ByteArray): Promise<ByteArray> => {
+            const iv = data.slice(0, 16)
+            const ciphertext = data.slice(16)
+            return await aes256cbcDecrypt(key, ciphertext, iv)
+        },
+    }
+}

package/packages/pdf-lite/src/crypto/ciphers/rc4.ts

@@ -0,0 +1,82 @@
+import { ByteArray } from '../../types.js'
+import { Cipher } from '../types.js'
+
+/**
+ * Creates an RC4 cipher for PDF encryption.
+ * RC4 is a symmetric stream cipher where encryption and decryption
+ * use the same operation (XOR with the key stream).
+ *
+ * @param key - The encryption key (variable length).
+ * @returns A Cipher object with encrypt and decrypt methods.
+ *
+ * @example
+ * ```typescript
+ * const cipher = rc4(key)
+ * const encrypted = await cipher.encrypt(plaintext)
+ * const decrypted = await cipher.decrypt(encrypted)
+ * ```
+ */
+export function rc4(key: ByteArray): Cipher {
+    /**
+     * RC4 Key Scheduling Algorithm (KSA).
+     * Initializes the permutation in the S array based on the key.
+     *
+     * @param key - The encryption key.
+     * @returns The initialized S array (256 bytes).
+     */
+    function ksa(key: ByteArray) {
+        const S = new Uint8Array(256)
+        for (let i = 0; i < 256; i++) S[i] = i
+        let j = 0
+        for (let i = 0; i < 256; i++) {
+            j = (j + S[i] + key[i % key.length]) & 0xff
+            ;[S[i], S[j]] = [S[j], S[i]]
+        }
+        return S
+    }
+
+    /**
+     * RC4 Pseudo-Random Generation Algorithm (PRGA).
+     * Generates the key stream and XORs it with the data.
+     *
+     * @param data - The data to encrypt or decrypt.
+     * @param S - The initialized S array from KSA.
+     * @returns The encrypted or decrypted data.
+     */
+    function rc4(data: ByteArray, S: ByteArray): ByteArray {
+        const out = new Uint8Array(data.length)
+        let i = 0,
+            j = 0
+        const s = S.slice() // Copy S for each operation
+        for (let k = 0; k < data.length; k++) {
+            i = (i + 1) & 0xff
+            j = (j + s[i]) & 0xff
+            ;[s[i], s[j]] = [s[j], s[i]]
+            const rnd = s[(s[i] + s[j]) & 0xff]
+            out[k] = data[k] ^ rnd
+        }
+        return out
+    }
+
+    const S = ksa(key)
+    return {
+        /**
+         * Encrypts data using RC4.
+         *
+         * @param data - The data to encrypt.
+         * @returns A promise that resolves to the encrypted data.
+         */
+        encrypt: async (data: ByteArray): Promise<ByteArray> => {
+            return rc4(data, S)
+        },
+        /**
+         * Decrypts data using RC4.
+         *
+         * @param data - The data to decrypt.
+         * @returns A promise that resolves to the decrypted data.
+         */
+        decrypt: async (data: ByteArray): Promise<ByteArray> => {
+            return rc4(data, S)
+        },
+    }
+}

package/packages/pdf-lite/src/crypto/constants.ts

@@ -0,0 +1,10 @@
+/**
+ * Default password padding used in PDF encryption.
+ * This 32-byte constant is defined in the PDF specification and is used
+ * to pad passwords shorter than 32 bytes during encryption key derivation.
+ */
+export const DEFAULT_PADDING = new Uint8Array([
+    0x28, 0xbf, 0x4e, 0x5e, 0x4e, 0x75, 0x8a, 0x41, 0x64, 0x00, 0x4e, 0x56,
+    0xff, 0xfa, 0x01, 0x08, 0x2e, 0x2e, 0x00, 0xb6, 0xd0, 0x68, 0x3e, 0x80,
+    0x2f, 0x0c, 0xa9, 0xfe, 0x64, 0x53, 0x69, 0x7a,
+])

package/packages/pdf-lite/src/crypto/key-derivation/key-derivation-aes256.ts

@@ -0,0 +1,213 @@
+import { ByteArray } from '../../types'
+import {
+    aes128CbcNoPaddingEncrypt,
+    aes256CbcNoPaddingDecrypt,
+    sha256,
+    sha384,
+    sha512,
+} from '../../utils/algos'
+import { assert } from '../../utils/assert'
+
+/**
+ * Converts the first 16 bytes of input to a big-endian bigint.
+ *
+ * @param input - The byte array to convert.
+ * @returns A 128-bit bigint value.
+ */
+function getUint16ByteBigEndian(input: ByteArray): bigint {
+    let value = 0n
+    for (let i = 0; i < 16; i++) {
+        value = (value << 8n) | BigInt(input[i])
+    }
+    return value
+}
+
+/**
+ * Computes the Algorithm 2.B hash for PDF 2.0 AES-256 encryption.
+ * This iterative hash algorithm uses SHA-256, SHA-384, or SHA-512 based on
+ * intermediate results, running for at least 64 rounds.
+ *
+ * @param password - The user or owner password.
+ * @param salt - The 8-byte validation or key salt.
+ * @param userKey - The user key (required for owner password validation). Defaults to empty.
+ * @returns A promise that resolves to a 32-byte hash.
+ *
+ * @example
+ * ```typescript
+ * const hash = await computeAlgorithm2bHash(password, salt)
+ * ```
+ */
+export async function computeAlgorithm2bHash(
+    password: ByteArray,
+    salt: ByteArray,
+    userKey: ByteArray = new Uint8Array(),
+): Promise<ByteArray> {
+    // Step 1: Initial hash
+    let K = new Uint8Array(password.length + salt.length + userKey.length)
+    K.set(password)
+    K.set(salt, password.length)
+    K.set(userKey, password.length + salt.length)
+
+    K = await sha256(K)
+
+    let roundNumber = 0
+    let E: ByteArray = new Uint8Array()
+    while (roundNumber < 64 || E.at(-1)! > roundNumber - 32) {
+        // Step 2: K1 = 64 × (password || K || [userKey])
+        const base = new Uint8Array(password.length + K.length + userKey.length)
+        base.set(password)
+        base.set(K, password.length)
+        base.set(userKey, password.length + K.length)
+
+        const K1 = new Uint8Array(base.length * 64)
+        for (let i = 0; i < 64; i++) {
+            K1.set(base, i * base.length)
+        }
+
+        // Step 3: Encrypt K1 with AES-128-CBC using key/iv from K
+        const key = K.subarray(0, 16)
+        const iv = K.subarray(16, 32)
+        E = await aes128CbcNoPaddingEncrypt(key, K1, iv)
+
+        // Step 4: Choose hash
+        const value = getUint16ByteBigEndian(E)
+        const mod = Number(value % 3n)
+
+        if (mod === 0) {
+            K = await sha256(E)
+        } else if (mod === 1) {
+            K = await sha384(E)
+        } else if (mod === 2) {
+            K = await sha512(E)
+        } else {
+            throw new Error('Invalid mod')
+        }
+
+        roundNumber++
+    }
+
+    return K.subarray(0, 32)
+}
+
+/**
+ * Validates a password against a stored hash using the Algorithm 2.B hash.
+ *
+ * @param password - The password to validate.
+ * @param key - The stored key containing the hash (first 32 bytes) and validation salt (bytes 32-40).
+ * @param extra - Extra data for owner password validation (user key).
+ * @returns A promise that resolves to the computed hash if validation succeeds.
+ * @throws Error if the password is invalid or salt/hash lengths are incorrect.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await validatePasswordHash(password, storedKey)
+ *   console.log('Password is valid')
+ * } catch (e) {
+ *   console.log('Invalid password')
+ * }
+ * ```
+ */
+export async function validatePasswordHash(
+    password: ByteArray,
+    key: ByteArray,
+    extra?: ByteArray,
+): Promise<ByteArray> {
+    const validationSalt = key.slice(32, 40)
+    if (validationSalt.length !== 8) {
+        throw new Error('Invalid salt length')
+    }
+
+    const hash = await computeAlgorithm2bHash(password, validationSalt, extra)
+
+    if (hash.length !== 32) {
+        throw new Error('Invalid hash length')
+    }
+
+    for (let i = 0; i < 32; i++) {
+        if (hash[i] !== key[i]) {
+            throw new Error('Key mismatch')
+        }
+    }
+
+    return hash
+}
+
+/**
+ * Retrieves the file encryption key using user or owner password.
+ * Tries owner password first, then falls back to user password.
+ *
+ * @param userPassword - The user password to try.
+ * @param ownerPassword - The owner password to try.
+ * @param u - The 48-byte /U value from the encryption dictionary.
+ * @param ue - The 32-byte /UE value (encrypted user key).
+ * @param o - The 48-byte /O value from the encryption dictionary.
+ * @param oe - The 32-byte /OE value (encrypted owner key).
+ * @returns A promise that resolves to the 32-byte file encryption key.
+ * @throws Error if both passwords are invalid.
+ *
+ * @example
+ * ```typescript
+ * const fileKey = await getFileKey(userPw, ownerPw, U, UE, O, OE)
+ * ```
+ */
+export async function getFileKey(
+    userPassword: ByteArray,
+    ownerPassword: ByteArray,
+    u: ByteArray,
+    ue: ByteArray,
+    o: ByteArray,
+    oe: ByteArray,
+): Promise<ByteArray> {
+    if (userPassword.length > 128) {
+        userPassword = userPassword.subarray(0, 128)
+    }
+
+    if (ownerPassword.length > 128) {
+        ownerPassword = ownerPassword.subarray(0, 128)
+    }
+
+    assert(oe.length === 32, 'Invalid OE length')
+    assert(ue.length === 32, 'Invalid UE length')
+    assert(u.length === 48, 'Invalid U length')
+    assert(o.length === 48, 'Invalid O length')
+
+    try {
+        // First try owner password
+        await validatePasswordHash(ownerPassword, o, u)
+
+        const hash = await computeAlgorithm2bHash(
+            ownerPassword,
+            o.subarray(40, 48),
+            u,
+        )
+
+        const key = await aes256CbcNoPaddingDecrypt(
+            hash,
+            oe,
+            new Uint8Array(16),
+        )
+
+        return key
+    } catch (e) {
+        try {
+            // Then try user password
+
+            await validatePasswordHash(userPassword, u)
+
+            const hash = await computeAlgorithm2bHash(
+                userPassword,
+                u.subarray(40, 48),
+            )
+            const key = await aes256CbcNoPaddingDecrypt(
+                hash,
+                ue,
+                new Uint8Array(16),
+            )
+
+            return key
+        } catch (e) {
+            throw new Error('Invalid password')
+        }
+    }
+}

package/packages/pdf-lite/src/crypto/key-derivation/key-derivation.ts

@@ -0,0 +1,122 @@
+import { DEFAULT_PADDING } from '../constants.js'
+import { md5 } from '../../utils/algos.js'
+import { int32ToLittleEndianBytes } from '../utils.js'
+import { concatUint8Arrays } from '../../utils/concatUint8Arrays.js'
+import { ByteArray } from '../../types.js'
+
+/**
+ * Pads a password to exactly 32 bytes using the PDF standard padding.
+ * If the password is shorter than 32 bytes, it is padded with bytes from DEFAULT_PADDING.
+ * If the password is 32 bytes or longer, only the first 32 bytes are used.
+ *
+ * @param password - The password to pad.
+ * @returns A 32-byte padded password.
+ *
+ * @example
+ * ```typescript
+ * const padded = padPassword(new Uint8Array([1, 2, 3])) // Returns 32-byte array
+ * ```
+ */
+export function padPassword(password: ByteArray): ByteArray {
+    const padded = new Uint8Array(32)
+    if (password.length >= 32) {
+        padded.set(password.subarray(0, 32))
+    } else {
+        padded.set(password)
+        padded.set(
+            DEFAULT_PADDING.subarray(0, 32 - password.length),
+            password.length,
+        )
+    }
+    return padded
+}
+
+/**
+ * Compute the master encryption key for a PDF file.
+ *
+ * @param password User-supplied password (empty if no password)
+ * @param ownerKey Owner key (/O value)
+ * @param permissions /P value
+ * @param id0 First element of /ID array
+ * @param keyLengthBits Usually 40, 128 or 256
+ * @param encryptMetadata Whether /EncryptMetadata is false
+ */
+export async function computeMasterKey(
+    password: ByteArray,
+    ownerKey: ByteArray,
+    permissions: number,
+    id0: ByteArray,
+    keyLengthBits: number,
+    encryptMetadata: boolean,
+    revision: number = 3,
+): Promise<ByteArray> {
+    if (keyLengthBits % 8 !== 0) {
+        throw new Error(
+            `keyLengthBits must be a multiple of 8, got ${keyLengthBits}`,
+        )
+    }
+
+    const keyLengthBytes = keyLengthBits / 8
+
+    const paddedPassword = padPassword(password)
+    const permissionsBytes = int32ToLittleEndianBytes(permissions)
+
+    const hashInputParts = [paddedPassword, ownerKey, permissionsBytes, id0]
+
+    if (keyLengthBits > 40 && !encryptMetadata && revision >= 4) {
+        hashInputParts.push(new Uint8Array([0xff, 0xff, 0xff, 0xff]))
+    }
+
+    // Initial MD5 hash
+    let digest = await md5(concatUint8Arrays(...hashInputParts))
+
+    if (keyLengthBits > 40) {
+        // Perform 50 iterations of MD5 rehash
+        for (let i = 0; i < 50; i++) {
+            digest = await md5(digest.subarray(0, keyLengthBytes))
+        }
+    }
+
+    // Truncate to key length
+    return digest.subarray(0, keyLengthBytes)
+}
+
+/**
+ * Derives an object-specific encryption key from the master key.
+ * Used to encrypt individual PDF objects with unique keys.
+ *
+ * @param mkey - The master encryption key.
+ * @param objNumber - The PDF object number.
+ * @param objGeneration - The PDF object generation number.
+ * @param useAesSalt - Whether to include the AES salt ('sAlT'). Defaults to true.
+ * @returns A promise that resolves to the derived object key.
+ *
+ * @example
+ * ```typescript
+ * const objectKey = await deriveObjectKey(masterKey, 5, 0)
+ * ```
+ */
+export async function deriveObjectKey(
+    mkey: ByteArray,
+    objNumber: number,
+    objGeneration: number,
+    useAesSalt: boolean = true,
+): Promise<ByteArray> {
+    const extra = useAesSalt ? 4 : 0 // 4 extra bytes if AES salt
+    const buffer = new Uint8Array(mkey.length + 5 + extra) // <--- make room for salt if needed
+    buffer.set(mkey, 0)
+    buffer[mkey.length + 0] = objNumber & 0xff
+    buffer[mkey.length + 1] = (objNumber >> 8) & 0xff
+    buffer[mkey.length + 2] = (objNumber >> 16) & 0xff
+    buffer[mkey.length + 3] = objGeneration & 0xff
+    buffer[mkey.length + 4] = (objGeneration >> 8) & 0xff
+
+    if (useAesSalt) {
+        buffer.set([0x73, 0x41, 0x6c, 0x54], mkey.length + 5) // append 'sAlT'
+    }
+
+    const digest = await md5(buffer)
+
+    const keySize = Math.min(mkey.length + 5, 16)
+    return new Uint8Array(digest.subarray(0, keySize))
+}

package/packages/pdf-lite/src/crypto/key-gen/key-gen-aes256.ts

@@ -0,0 +1,79 @@
+import { computeAlgorithm2bHash } from '../key-derivation/key-derivation-aes256.js'
+import { getRandomBytes } from '../../utils/algos.js'
+import { aes256CbcNoPaddingEncrypt } from '../../utils/algos.js'
+import { ByteArray } from '../../types.js'
+
+/**
+ * Generates the /U and /UE values for AES-256 PDF encryption.
+ * These values are used to validate the user password and decrypt the file key.
+ *
+ * @param password - The user password.
+ * @param fileKey - The 32-byte file encryption key.
+ * @returns A promise that resolves to an object containing the 48-byte U and 32-byte UE values.
+ *
+ * @example
+ * ```typescript
+ * const { U, UE } = await generateUandUe(password, fileKey)
+ * ```
+ */
+export async function generateUandUe(
+    password: ByteArray,
+    fileKey: ByteArray,
+): Promise<{ U: ByteArray; UE: ByteArray }> {
+    const random = getRandomBytes(16)
+    const userValidationSalt = random.subarray(0, 8)
+    const userKeySalt = random.subarray(8, 16)
+
+    const U = new Uint8Array(48)
+    U.set(await computeAlgorithm2bHash(password, userValidationSalt))
+    U.set(userValidationSalt, 32)
+    U.set(userKeySalt, 40)
+
+    const hash = await computeAlgorithm2bHash(password, userKeySalt)
+    const UE = await aes256CbcNoPaddingEncrypt(
+        hash,
+        fileKey,
+        new Uint8Array(16),
+    )
+
+    return { U, UE }
+}
+
+/**
+ * Generates the /O and /OE values for AES-256 PDF encryption.
+ * These values are used to validate the owner password and decrypt the file key.
+ *
+ * @param password - The owner password.
+ * @param U - The 48-byte /U value (required for owner key derivation).
+ * @param fileKey - The 32-byte file encryption key.
+ * @returns A promise that resolves to an object containing the 48-byte O and 32-byte OE values.
+ *
+ * @example
+ * ```typescript
+ * const { O, OE } = await generateOandOe(ownerPassword, U, fileKey)
+ * ```
+ */
+export async function generateOandOe(
+    password: ByteArray,
+    U: ByteArray,
+    fileKey: ByteArray,
+): Promise<{ O: ByteArray; OE: ByteArray }> {
+    const random = getRandomBytes(16)
+    const ownerValidationSalt = random.subarray(0, 8)
+    const ownerKeySalt = random.subarray(8, 16)
+
+    const O = new Uint8Array(48)
+    O.set(await computeAlgorithm2bHash(password, ownerValidationSalt, U))
+    O.set(ownerValidationSalt, 32)
+    O.set(ownerKeySalt, 40)
+
+    const hash = await computeAlgorithm2bHash(password, ownerKeySalt, U)
+
+    const OE = await aes256CbcNoPaddingEncrypt(
+        hash,
+        fileKey,
+        new Uint8Array(16),
+    )
+
+    return { O, OE }
+}