pdf-lite 1.0.0

package/packages/pdf-lite/src/utils/algos.ts

@@ -0,0 +1,446 @@
+import { deflate, Inflate } from 'pako'
+import { bytesToHex } from './bytesToHex.js'
+import { AlgorithmIdentifier } from 'pki-lite/algorithms/AlgorithmIdentifier'
+import 'pki-lite-crypto-extended'
+import { ByteArray } from '../types.js'
+
+/**
+ * Computes the SHA-1 hash of the input data.
+ *
+ * @param input - The data to hash.
+ * @returns A promise that resolves to the SHA-1 hash as a byte array.
+ *
+ * @example
+ * ```typescript
+ * const hash = await sha1(new Uint8Array([1, 2, 3]))
+ * ```
+ */
+export async function sha1(input: ByteArray): Promise<ByteArray> {
+    return AlgorithmIdentifier.digestAlgorithm('SHA-1').digest(input)
+}
+
+/**
+ * Computes the SHA-256 hash of the input data.
+ *
+ * @param input - The data to hash.
+ * @returns A promise that resolves to the SHA-256 hash as a byte array.
+ *
+ * @example
+ * ```typescript
+ * const hash = await sha256(new Uint8Array([1, 2, 3]))
+ * ```
+ */
+export async function sha256(input: ByteArray): Promise<ByteArray> {
+    return AlgorithmIdentifier.digestAlgorithm('SHA-256').digest(input)
+}
+
+/**
+ * Computes the SHA-384 hash of the input data.
+ *
+ * @param input - The data to hash.
+ * @returns A promise that resolves to the SHA-384 hash as a byte array.
+ *
+ * @example
+ * ```typescript
+ * const hash = await sha384(new Uint8Array([1, 2, 3]))
+ * ```
+ */
+export async function sha384(input: ByteArray): Promise<ByteArray> {
+    return AlgorithmIdentifier.digestAlgorithm('SHA-384').digest(input)
+}
+
+/**
+ * Computes the SHA-512 hash of the input data.
+ *
+ * @param input - The data to hash.
+ * @returns A promise that resolves to the SHA-512 hash as a byte array.
+ *
+ * @example
+ * ```typescript
+ * const hash = await sha512(new Uint8Array([1, 2, 3]))
+ * ```
+ */
+export async function sha512(input: ByteArray): Promise<ByteArray> {
+    return AlgorithmIdentifier.digestAlgorithm('SHA-512').digest(input)
+}
+
+/**
+ * Computes the MD5 hash of the input data.
+ *
+ * @param input - The data to hash.
+ * @returns A promise that resolves to the MD5 hash as a byte array.
+ *
+ * @example
+ * ```typescript
+ * const hash = await md5(new Uint8Array([1, 2, 3]))
+ * ```
+ */
+export async function md5(input: ByteArray): Promise<ByteArray> {
+    return AlgorithmIdentifier.digestAlgorithm('MD5').digest(input)
+}
+
+/**
+ * Computes a cryptographic hash of the input data using the specified algorithm.
+ *
+ * @param input - The data to hash.
+ * @param algorithm - The hash algorithm to use. Defaults to 'SHA-256'.
+ * @returns A promise that resolves to the hash as a byte array.
+ * @throws Error if an unsupported hash algorithm is specified.
+ *
+ * @example
+ * ```typescript
+ * const hash = await hash(data, 'SHA-256')
+ * ```
+ */
+export async function hash(
+    input: ByteArray,
+    algorithm: 'SHA-256' | 'SHA-384' | 'SHA-512' | 'MD5' | 'SHA-1' = 'SHA-256',
+): Promise<ByteArray> {
+    switch (algorithm) {
+        case 'SHA-256':
+            return sha256(input)
+        case 'SHA-384':
+            return sha384(input)
+        case 'SHA-512':
+            return sha512(input)
+        case 'MD5':
+            return md5(input)
+        case 'SHA-1':
+            return sha1(input)
+        default:
+            throw new Error(`Unsupported hash algorithm: ${algorithm}`)
+    }
+}
+
+/**
+ * Generates cryptographically secure random bytes.
+ *
+ * @param length - The number of random bytes to generate.
+ * @returns A byte array containing random bytes.
+ * @throws Error if length is not a positive integer.
+ *
+ * @example
+ * ```typescript
+ * const randomBytes = getRandomBytes(16) // 16 random bytes
+ * ```
+ */
+export function getRandomBytes(length: number): ByteArray {
+    if (length <= 0) throw new Error('Length must be a positive integer')
+    return AlgorithmIdentifier.randomBytes(length)
+}
+
+/**
+ * Encrypts data using AES-128-CBC mode.
+ *
+ * @param key - The 16-byte encryption key.
+ * @param data - The data to encrypt.
+ * @param iv - The 16-byte initialization vector. Defaults to zero IV.
+ * @returns A promise that resolves to the encrypted data.
+ * @throws Error if the key is not exactly 16 bytes.
+ *
+ * @example
+ * ```typescript
+ * const encrypted = await aes128cbcEncrypt(key, plaintext, iv)
+ * ```
+ */
+export async function aes128cbcEncrypt(
+    key: ByteArray,
+    data: ByteArray,
+    iv: ByteArray = new Uint8Array(16), // Zero IV, as per PDF spec
+): Promise<ByteArray> {
+    if (key.length !== 16) {
+        throw new Error(
+            `AES-128 key must be exactly 16 bytes, got ${key.length}`,
+        )
+    }
+
+    return AlgorithmIdentifier.contentEncryptionAlgorithm({
+        type: 'AES_128_CBC',
+        params: {
+            nonce: iv,
+        },
+    }).encrypt(data, key)
+}
+
+/**
+ * Decrypts data using AES-128-CBC mode.
+ *
+ * @param key - The 16-byte decryption key.
+ * @param encrypted - The encrypted data to decrypt.
+ * @param iv - The 16-byte initialization vector. Defaults to zero IV.
+ * @returns A promise that resolves to the decrypted data.
+ * @throws Error if the key is not exactly 16 bytes or encrypted data is too short.
+ *
+ * @example
+ * ```typescript
+ * const decrypted = await aes128cbcDecrypt(key, ciphertext, iv)
+ * ```
+ */
+export async function aes128cbcDecrypt(
+    key: ByteArray,
+    encrypted: ByteArray,
+    iv: ByteArray = new Uint8Array(16), // Zero IV, as per PDF spec
+): Promise<ByteArray> {
+    if (key.length !== 16) {
+        throw new Error(
+            `AES-128 key must be exactly 16 bytes, got ${key.length}`,
+        )
+    }
+    if (encrypted.length < 16) {
+        throw new Error('Encrypted stream too short — no IV found')
+    }
+
+    return AlgorithmIdentifier.contentEncryptionAlgorithm({
+        type: 'AES_128_CBC',
+        params: {
+            nonce: iv,
+        },
+    }).decrypt(encrypted, key)
+}
+
+/**
+ * Encrypts data using AES-256-CBC mode.
+ *
+ * @param fileKey - The 32-byte encryption key.
+ * @param block - The data to encrypt.
+ * @param iv - The 16-byte initialization vector. Defaults to zero IV.
+ * @returns A promise that resolves to the encrypted data.
+ *
+ * @example
+ * ```typescript
+ * const encrypted = await aes256cbcEncrypt(key, plaintext, iv)
+ * ```
+ */
+export async function aes256cbcEncrypt(
+    fileKey: ByteArray,
+    block: ByteArray,
+    iv: ByteArray = new Uint8Array(16), // Zero IV, as per PDF spec
+): Promise<ByteArray> {
+    return AlgorithmIdentifier.contentEncryptionAlgorithm({
+        type: 'AES_256_CBC',
+        params: {
+            nonce: iv,
+        },
+    }).encrypt(block, fileKey)
+}
+
+/**
+ * Decrypts data using AES-256-CBC mode.
+ *
+ * @param fileKey - The 32-byte decryption key.
+ * @param ciphertext - The encrypted data to decrypt.
+ * @param iv - The 16-byte initialization vector. Defaults to zero IV.
+ * @returns A promise that resolves to the decrypted data.
+ *
+ * @example
+ * ```typescript
+ * const decrypted = await aes256cbcDecrypt(key, ciphertext, iv)
+ * ```
+ */
+export async function aes256cbcDecrypt(
+    fileKey: ByteArray,
+    ciphertext: ByteArray,
+    iv: ByteArray = new Uint8Array(16), // Zero IV, as per PDF spec
+): Promise<ByteArray> {
+    return AlgorithmIdentifier.contentEncryptionAlgorithm({
+        type: 'AES_256_CBC',
+        params: {
+            nonce: iv,
+        },
+    }).decrypt(ciphertext, fileKey)
+}
+
+/**
+ * Encrypts data using AES-256-ECB mode.
+ *
+ * @param fileKey - The 32-byte encryption key.
+ * @param data - The data to encrypt.
+ * @returns A promise that resolves to the encrypted data.
+ * @throws Error if the key is not exactly 32 bytes.
+ *
+ * @example
+ * ```typescript
+ * const encrypted = await aes256ecbEncrypt(key, plaintext)
+ * ```
+ */
+export async function aes256ecbEncrypt(
+    fileKey: ByteArray,
+    data: ByteArray,
+): Promise<ByteArray> {
+    if (fileKey.length !== 32) {
+        throw new Error(
+            `AES-256 key must be exactly 32 bytes, got ${fileKey.length}`,
+        )
+    }
+
+    return AlgorithmIdentifier.contentEncryptionAlgorithm({
+        type: 'AES_256_ECB',
+        params: {},
+    }).encrypt(data, fileKey)
+}
+
+/**
+ * Decrypts data using AES-256-ECB mode.
+ *
+ * @param fileKey - The 32-byte decryption key.
+ * @param encrypted - The encrypted data to decrypt.
+ * @returns A promise that resolves to the decrypted data.
+ * @throws Error if the key is not exactly 32 bytes.
+ *
+ * @example
+ * ```typescript
+ * const decrypted = await aes256ecbDecrypt(key, ciphertext)
+ * ```
+ */
+export async function aes256ecbDecrypt(
+    fileKey: ByteArray,
+    encrypted: ByteArray,
+): Promise<ByteArray> {
+    if (fileKey.length !== 32) {
+        throw new Error(
+            `AES-256 key must be exactly 32 bytes, got ${fileKey.length}`,
+        )
+    }
+
+    return AlgorithmIdentifier.contentEncryptionAlgorithm({
+        type: 'AES_256_ECB',
+        params: {},
+    }).decrypt(encrypted, fileKey)
+}
+
+/**
+ * Encrypts data using AES-128-CBC mode without PKCS#7 padding.
+ *
+ * @param key - The 16-byte encryption key.
+ * @param data - The data to encrypt. Must be a multiple of 16 bytes.
+ * @param iv - The 16-byte initialization vector.
+ * @returns A promise that resolves to the encrypted data.
+ *
+ * @example
+ * ```typescript
+ * const encrypted = await aes128CbcNoPaddingEncrypt(key, data, iv)
+ * ```
+ */
+export async function aes128CbcNoPaddingEncrypt(
+    key: ByteArray,
+    data: ByteArray,
+    iv: ByteArray,
+): Promise<ByteArray> {
+    return AlgorithmIdentifier.contentEncryptionAlgorithm({
+        type: 'AES_128_CBC',
+        params: {
+            nonce: iv,
+            disablePadding: true,
+        },
+    }).encrypt(data, key)
+}
+
+/**
+ * Encrypts data using AES-256-CBC mode without PKCS#7 padding.
+ *
+ * @param key - The 32-byte encryption key.
+ * @param data - The data to encrypt. Must be a multiple of 16 bytes.
+ * @param iv - The 16-byte initialization vector.
+ * @returns A promise that resolves to the encrypted data.
+ *
+ * @example
+ * ```typescript
+ * const encrypted = await aes256CbcNoPaddingEncrypt(key, data, iv)
+ * ```
+ */
+export async function aes256CbcNoPaddingEncrypt(
+    key: ByteArray,
+    data: ByteArray,
+    iv: ByteArray,
+): Promise<ByteArray> {
+    return AlgorithmIdentifier.contentEncryptionAlgorithm({
+        type: 'AES_256_CBC',
+        params: {
+            nonce: iv,
+            disablePadding: true,
+        },
+    }).encrypt(data, key)
+}
+
+/**
+ * Decrypts data using AES-256-CBC mode without PKCS#7 padding.
+ *
+ * @param key - The 32-byte decryption key.
+ * @param ciphertext - The encrypted data to decrypt.
+ * @param iv - The 16-byte initialization vector. Defaults to zero IV.
+ * @returns A promise that resolves to the decrypted data.
+ *
+ * @example
+ * ```typescript
+ * const decrypted = await aes256CbcNoPaddingDecrypt(key, ciphertext, iv)
+ * ```
+ */
+export async function aes256CbcNoPaddingDecrypt(
+    key: ByteArray,
+    ciphertext: ByteArray,
+    iv: ByteArray = new Uint8Array(16),
+): Promise<ByteArray> {
+    return AlgorithmIdentifier.contentEncryptionAlgorithm({
+        type: 'AES_256_CBC',
+        params: {
+            nonce: iv,
+            disablePadding: true,
+        },
+    }).decrypt(ciphertext, key)
+}
+
+/**
+ * Compresses data using the DEFLATE algorithm.
+ *
+ * @param data - The data to compress.
+ * @returns The compressed data as a byte array.
+ *
+ * @example
+ * ```typescript
+ * const compressed = deflateData(rawData)
+ * ```
+ */
+export function deflateData(data: ByteArray): ByteArray {
+    const output = deflate(data)
+    if (!output) {
+        return new Uint8Array(0)
+    }
+    return output
+}
+
+/**
+ * Decompresses data using the INFLATE algorithm (reverses DEFLATE).
+ *
+ * @param data - The compressed data to decompress.
+ * @returns The decompressed data as a byte array.
+ * @throws Error if inflation fails due to invalid or corrupted data.
+ *
+ * @example
+ * ```typescript
+ * const decompressed = inflateData(compressedData)
+ * ```
+ */
+export function inflateData(data: ByteArray): ByteArray {
+    if (data.length === 0) {
+        return new Uint8Array(0) // Return empty array for empty input
+    }
+
+    const isWhitespace = (byte: number): boolean => {
+        return byte === 0x20 || byte === 0x09 || byte === 0x0a || byte === 0x0d
+    }
+
+    const inflate = new Inflate()
+    inflate.push(data, true)
+
+    if (inflate.err || !inflate.result) {
+        if (isWhitespace(data[data.length - 1])) {
+            data = data.slice(0, -1) // Remove trailing whitespace]
+            return inflateData(data) // Retry inflation after removing whitespace
+        }
+        throw new Error(
+            `Inflate error: ${inflate.err} - ${inflate.msg}. Data hex: ${bytesToHex(data)}`,
+        ) // Log the hex representation of the data for debugging
+    }
+
+    return inflate.result as ByteArray
+}

package/packages/pdf-lite/src/utils/assert.ts

@@ -0,0 +1,42 @@
+/**
+ * Asserts that a value is truthy, throwing an error if it is not.
+ *
+ * @param value - The value to check.
+ * @param message - Optional error message to throw if the assertion fails.
+ * @throws Error if the value is falsy.
+ *
+ * @example
+ * ```typescript
+ * assert(user !== null, 'User must be defined')
+ * ```
+ */
+export function assert(value: unknown, message?: string): asserts value {
+    if (!value) {
+        throw new Error(message)
+    }
+}
+
+/**
+ * Conditionally asserts a condition only when a value is defined.
+ * Does nothing if the value is undefined or null.
+ *
+ * @param value - The value to check for definedness.
+ * @param condition - The condition to assert if value is defined.
+ * @param message - Optional error message to throw if the assertion fails.
+ * @throws Error if value is defined and condition is falsy.
+ *
+ * @example
+ * ```typescript
+ * assertIfDefined(user, user?.age >= 18, 'User must be an adult')
+ * ```
+ */
+export function assertIfDefined(
+    value: unknown,
+    condition: unknown,
+    message?: string,
+): asserts condition {
+    if (value === undefined || value === null) {
+        return
+    }
+    assert(condition, message)
+}

package/packages/pdf-lite/src/utils/bytesToHex.ts

@@ -0,0 +1,18 @@
+import { ByteArray } from '../types'
+import { bytesToHexBytes } from './bytesToHexBytes'
+import { bytesToString } from './bytesToString'
+
+/**
+ * Converts a byte array to a hexadecimal string.
+ *
+ * @param bytes - The byte array to convert.
+ * @returns A hexadecimal string representation of the bytes.
+ *
+ * @example
+ * ```typescript
+ * bytesToHex(new Uint8Array([255, 0, 127])) // Returns 'FF007F'
+ * ```
+ */
+export function bytesToHex(bytes: ByteArray): string {
+    return bytesToString(bytesToHexBytes(bytes))
+}

package/packages/pdf-lite/src/utils/bytesToHexBytes.ts

@@ -0,0 +1,27 @@
+import { ByteArray } from '../types'
+
+const hexChars = '0123456789ABCDEF'
+
+/**
+ * Converts a byte array to a byte array containing hexadecimal character codes.
+ * Each byte becomes two bytes representing its hex digits.
+ *
+ * @param bytes - The byte array to convert.
+ * @returns A byte array with hexadecimal character codes.
+ *
+ * @example
+ * ```typescript
+ * bytesToHexBytes(new Uint8Array([255])) // Returns bytes for 'FF'
+ * ```
+ */
+export function bytesToHexBytes(bytes: ByteArray): ByteArray {
+    const result = new Uint8Array(bytes.length * 2)
+
+    for (let i = 0; i < bytes.length; i++) {
+        const byte = bytes[i]
+        result[i * 2] = hexChars.charCodeAt((byte >> 4) & 0x0f)
+        result[i * 2 + 1] = hexChars.charCodeAt(byte & 0x0f)
+    }
+
+    return result
+}

package/packages/pdf-lite/src/utils/bytesToString.ts

@@ -0,0 +1,17 @@
+import { ByteArray } from '../types'
+
+/**
+ * Converts a byte array to a string using UTF-8 decoding.
+ *
+ * @param bytes - The byte array to decode.
+ * @returns The decoded string.
+ *
+ * @example
+ * ```typescript
+ * bytesToString(new Uint8Array([72, 101, 108, 108, 111])) // Returns 'Hello'
+ * ```
+ */
+export function bytesToString(bytes: ByteArray): string {
+    const decoder = new TextDecoder()
+    return decoder.decode(bytes)
+}

package/packages/pdf-lite/src/utils/concatUint8Arrays.ts

@@ -0,0 +1,26 @@
+import { ByteArray } from '../types'
+
+/**
+ * Concatenates multiple Uint8Array instances into a single ByteArray.
+ *
+ * @param arrays - The arrays to concatenate.
+ * @returns A new ByteArray containing all input arrays concatenated in order.
+ *
+ * @example
+ * ```typescript
+ * const result = concatUint8Arrays(
+ *   new Uint8Array([1, 2]),
+ *   new Uint8Array([3, 4])
+ * ) // Returns Uint8Array([1, 2, 3, 4])
+ * ```
+ */
+export function concatUint8Arrays(...arrays: Uint8Array[]): ByteArray {
+    const totalLength = arrays.reduce((acc, arr) => acc + arr.length, 0)
+    const result = new Uint8Array(totalLength)
+    let offset = 0
+    for (const arr of arrays) {
+        result.set(arr, offset)
+        offset += arr.length
+    }
+    return result
+}

package/packages/pdf-lite/src/utils/escapeString.ts

@@ -0,0 +1,49 @@
+import { ByteArray } from '../types'
+import { stringToBytes } from './stringToBytes'
+
+/**
+ * Escapes special characters in a PDF string according to PDF specification.
+ * Escapes parentheses, backslashes, line feeds, and carriage returns.
+ *
+ * @param bytes - The byte array or string to escape.
+ * @returns A new byte array with escaped characters.
+ *
+ * @example
+ * ```typescript
+ * escapeString('Hello (World)') // Escapes the parentheses
+ * ```
+ */
+export function escapeString(bytes: ByteArray | string): ByteArray {
+    if (typeof bytes === 'string') {
+        bytes = stringToBytes(bytes)
+    }
+
+    const result: number[] = []
+    const BACKSLASH = 0x5c
+
+    for (const b of bytes) {
+        switch (b) {
+            case 0x28:
+                result.push(BACKSLASH, 0x28)
+                break // (
+            case 0x29:
+                result.push(BACKSLASH, 0x29)
+                break // )
+            case BACKSLASH:
+                result.push(BACKSLASH, BACKSLASH)
+                break // \
+            case 0x0a:
+                result.push(BACKSLASH, 0x6e)
+                break // LF
+            case 0x0d:
+                result.push(BACKSLASH, 0x72)
+                break // CR
+            default:
+                result.push(b)
+
+                break
+        }
+    }
+
+    return new Uint8Array(result)
+}

package/packages/pdf-lite/src/utils/hexBytesToBytes.ts

@@ -0,0 +1,22 @@
+import { ByteArray } from '../types'
+
+/**
+ * Converts a byte array containing hexadecimal ASCII characters to raw bytes.
+ * Each pair of hex character bytes is converted to a single byte value.
+ *
+ * @param hex - The byte array containing hex character codes.
+ * @returns A byte array with decoded values.
+ *
+ * @example
+ * ```typescript
+ * // 'FF' as bytes (0x46, 0x46) becomes 0xFF
+ * hexBytesToBytes(new Uint8Array([70, 70])) // Returns Uint8Array([255])
+ * ```
+ */
+export function hexBytesToBytes(hex: ByteArray): ByteArray {
+    const bytes = new Uint8Array(hex.length / 2)
+    for (let i = 0; i < hex.length; i += 2) {
+        bytes[i / 2] = parseInt(String.fromCharCode(hex[i], hex[i + 1]), 16)
+    }
+    return bytes
+}

package/packages/pdf-lite/src/utils/hexBytesToString.ts

@@ -0,0 +1,21 @@
+import { ByteArray } from '../types'
+
+/**
+ * Converts a byte array to a lowercase hexadecimal string.
+ *
+ * @param bytes - The byte array to convert.
+ * @returns A lowercase hexadecimal string representation.
+ *
+ * @example
+ * ```typescript
+ * hexBytesToString(new Uint8Array([255, 0])) // Returns 'ff00'
+ * ```
+ */
+export function hexBytesToString(bytes: ByteArray): string {
+    let hex = ''
+    for (let i = 0; i < bytes.length; i++) {
+        const byte = bytes[i].toString(16)
+        hex += byte.length === 1 ? '0' + byte : byte
+    }
+    return hex
+}

package/packages/pdf-lite/src/utils/hexToBytes.ts

@@ -0,0 +1,18 @@
+import { ByteArray } from '../types'
+import { hexBytesToBytes } from './hexBytesToBytes'
+import { stringToBytes } from './stringToBytes'
+
+/**
+ * Converts a hexadecimal string to a byte array.
+ *
+ * @param hex - The hexadecimal string to convert.
+ * @returns A byte array containing the decoded values.
+ *
+ * @example
+ * ```typescript
+ * hexToBytes('FF00') // Returns Uint8Array([255, 0])
+ * ```
+ */
+export function hexToBytes(hex: string): ByteArray {
+    return hexBytesToBytes(stringToBytes(hex))
+}