@cj-tech-master/excelts 9.1.0 → 9.2.0

package/dist/browser/modules/pdf/builder/resource-merger.d.ts

@@ -0,0 +1,41 @@
+/**
+ * PDF resource dictionary merger — structured merging at the parsed object level.
+ *
+ * Instead of manipulating serialized PDF dict strings directly, this module
+ * parses resource dicts into a structured `PdfResourceDict` (nested Maps),
+ * merges them, and serializes back to PDF dict strings.
+ */
+/**
+ * Structured representation of a PDF resource dictionary.
+ *
+ * Outer key: category name (e.g. `Font`, `XObject`, `ExtGState`, `ColorSpace`,
+ * `Pattern`, `Shading`, `Properties`).
+ * Inner key: resource name (e.g. `F1`, `Im1`, `GS0`).
+ * Value: serialized ref or value string (e.g. `3 0 R`, `/DeviceRGB`).
+ *
+ * Categories whose value is not a sub-dict (e.g. `/ProcSet [/PDF /Text]`)
+ * are stored with an empty inner key `""` mapping to the raw value string.
+ */
+export type PdfResourceDict = Map<string, Map<string, string>>;
+/**
+ * Merge two parsed resource dicts. For sub-dict categories, entries are
+ * combined; overlay entries win on name collision. For non-sub-dict categories,
+ * the overlay value replaces the original.
+ */
+export declare function mergeResourceDicts(original: PdfResourceDict, overlay: PdfResourceDict): PdfResourceDict;
+/**
+ * Parse a serialized PDF resource dict string into a structured `PdfResourceDict`.
+ *
+ * Handles top-level entries like:
+ * ```
+ * << /Font << /F1 3 0 R /F2 5 0 R >> /XObject << /Im1 7 0 R >> /ProcSet [/PDF /Text] >>
+ * ```
+ *
+ * Sub-dict categories (`Font`, `XObject`, etc.) are parsed into inner name→value maps.
+ * Other categories are stored with a single entry keyed by `""`.
+ */
+export declare function parseResourceDict(dictStr: string): PdfResourceDict;
+/**
+ * Serialize a structured `PdfResourceDict` back to a PDF dict string.
+ */
+export declare function serializeResourceDict(dict: PdfResourceDict): string;

package/dist/browser/modules/pdf/builder/resource-merger.js

@@ -0,0 +1,258 @@
+/**
+ * PDF resource dictionary merger — structured merging at the parsed object level.
+ *
+ * Instead of manipulating serialized PDF dict strings directly, this module
+ * parses resource dicts into a structured `PdfResourceDict` (nested Maps),
+ * merges them, and serializes back to PDF dict strings.
+ */
+// Known resource categories that contain sub-dicts
+const SUB_DICT_CATEGORIES = new Set([
+    "Font",
+    "XObject",
+    "ExtGState",
+    "ColorSpace",
+    "Pattern",
+    "Shading",
+    "Properties"
+]);
+// =============================================================================
+// Merge
+// =============================================================================
+/**
+ * Merge two parsed resource dicts. For sub-dict categories, entries are
+ * combined; overlay entries win on name collision. For non-sub-dict categories,
+ * the overlay value replaces the original.
+ */
+export function mergeResourceDicts(original, overlay) {
+    const merged = new Map();
+    // Copy all original entries (deep-copy inner maps)
+    for (const [category, innerMap] of original) {
+        merged.set(category, new Map(innerMap));
+    }
+    // Merge overlay entries
+    for (const [category, overlayInner] of overlay) {
+        const existing = merged.get(category);
+        if (existing && SUB_DICT_CATEGORIES.has(category)) {
+            // Both have this sub-dict category — merge inner entries (overlay wins)
+            for (const [name, value] of overlayInner) {
+                existing.set(name, value);
+            }
+        }
+        else if (existing && !SUB_DICT_CATEGORIES.has(category)) {
+            // Non-sub-dict category — overlay replaces
+            merged.set(category, new Map(overlayInner));
+        }
+        else {
+            // Category only in overlay — copy it
+            merged.set(category, new Map(overlayInner));
+        }
+    }
+    return merged;
+}
+// =============================================================================
+// Parse
+// =============================================================================
+/**
+ * Parse a serialized PDF resource dict string into a structured `PdfResourceDict`.
+ *
+ * Handles top-level entries like:
+ * ```
+ * << /Font << /F1 3 0 R /F2 5 0 R >> /XObject << /Im1 7 0 R >> /ProcSet [/PDF /Text] >>
+ * ```
+ *
+ * Sub-dict categories (`Font`, `XObject`, etc.) are parsed into inner name→value maps.
+ * Other categories are stored with a single entry keyed by `""`.
+ */
+export function parseResourceDict(dictStr) {
+    const result = new Map();
+    const trimmed = dictStr.trim();
+    if (!trimmed.startsWith("<<") || !trimmed.endsWith(">>")) {
+        return result;
+    }
+    // Strip the outer << >>
+    const inner = trimmed.slice(2, -2).trim();
+    if (!inner) {
+        return result;
+    }
+    // Parse top-level entries
+    const entries = parseDictEntries(inner);
+    for (const [key, value] of entries) {
+        const valueTrimmed = value.trim();
+        if (SUB_DICT_CATEGORIES.has(key) && valueTrimmed.startsWith("<<")) {
+            // Parse the sub-dict into name→value pairs
+            const subInner = valueTrimmed.slice(2, -2).trim();
+            const subEntries = parseDictEntries(subInner);
+            const innerMap = new Map();
+            for (const [subKey, subValue] of subEntries) {
+                innerMap.set(subKey, subValue.trim());
+            }
+            result.set(key, innerMap);
+        }
+        else {
+            // Non-sub-dict category — store with empty key
+            const innerMap = new Map();
+            innerMap.set("", valueTrimmed);
+            result.set(key, innerMap);
+        }
+    }
+    return result;
+}
+// =============================================================================
+// Serialize
+// =============================================================================
+/**
+ * Serialize a structured `PdfResourceDict` back to a PDF dict string.
+ */
+export function serializeResourceDict(dict) {
+    if (dict.size === 0) {
+        return "<< >>";
+    }
+    const parts = ["<<"];
+    for (const [category, innerMap] of dict) {
+        if (SUB_DICT_CATEGORIES.has(category) && !(innerMap.size === 1 && innerMap.has(""))) {
+            // Sub-dict category — serialize as << /Name value ... >>
+            const subParts = ["<<"];
+            for (const [name, value] of innerMap) {
+                subParts.push(`/${name} ${value}`);
+            }
+            subParts.push(">>");
+            parts.push(`/${category} ${subParts.join(" ")}`);
+        }
+        else {
+            // Non-sub-dict or single-value category
+            const value = innerMap.get("") ?? "";
+            if (value) {
+                parts.push(`/${category} ${value}`);
+            }
+        }
+    }
+    parts.push(">>");
+    return parts.join(" ");
+}
+// =============================================================================
+// Internal: Dict Entry Parser
+// =============================================================================
+/**
+ * Parse the inner content of a `<< ... >>` dict (with outer delimiters already
+ * stripped) into key→value pairs. Handles nested `<< >>` and `[ ]` by depth
+ * counting.
+ */
+function parseDictEntries(inner) {
+    const entries = new Map();
+    let i = 0;
+    while (i < inner.length) {
+        // Skip whitespace
+        while (i < inner.length && isWhitespace(inner[i])) {
+            i++;
+        }
+        if (i >= inner.length) {
+            break;
+        }
+        // Expect a name: /KeyName
+        if (inner[i] !== "/") {
+            break; // malformed — bail
+        }
+        i++; // skip '/'
+        const nameStart = i;
+        while (i < inner.length && !isDelimiterOrWhitespace(inner[i])) {
+            i++;
+        }
+        const key = inner.slice(nameStart, i);
+        // Skip whitespace
+        while (i < inner.length && isWhitespace(inner[i])) {
+            i++;
+        }
+        // Read the value
+        const valueStart = i;
+        if (i < inner.length && inner[i] === "<" && i + 1 < inner.length && inner[i + 1] === "<") {
+            // Sub-dict: count nested << >>
+            i = skipNestedDict(inner, i);
+        }
+        else if (i < inner.length && inner[i] === "[") {
+            // Array: find matching ]
+            i = skipNestedArray(inner, i);
+        }
+        else {
+            // Token(s) — read until next top-level '/' or end
+            i = skipTokenValue(inner, i, valueStart);
+        }
+        const value = inner.slice(valueStart, i).trim();
+        if (key && value) {
+            entries.set(key, value);
+        }
+    }
+    return entries;
+}
+function isWhitespace(ch) {
+    return ch === " " || ch === "\t" || ch === "\n" || ch === "\r" || ch === "\f";
+}
+function isDelimiterOrWhitespace(ch) {
+    return (isWhitespace(ch) ||
+        ch === "/" ||
+        ch === "<" ||
+        ch === ">" ||
+        ch === "[" ||
+        ch === "]" ||
+        ch === "(" ||
+        ch === ")");
+}
+/** Skip over a `<< ... >>` block, handling nesting. Returns position after `>>`. */
+function skipNestedDict(str, start) {
+    let i = start;
+    let depth = 0;
+    while (i < str.length) {
+        if (str[i] === "<" && i + 1 < str.length && str[i + 1] === "<") {
+            depth++;
+            i += 2;
+        }
+        else if (str[i] === ">" && i + 1 < str.length && str[i + 1] === ">") {
+            depth--;
+            i += 2;
+            if (depth === 0) {
+                return i;
+            }
+        }
+        else {
+            i++;
+        }
+    }
+    return i;
+}
+/** Skip over a `[ ... ]` block, handling nesting. Returns position after `]`. */
+function skipNestedArray(str, start) {
+    let i = start;
+    let depth = 0;
+    while (i < str.length) {
+        if (str[i] === "[") {
+            depth++;
+        }
+        else if (str[i] === "]") {
+            depth--;
+            if (depth === 0) {
+                i++;
+                return i;
+            }
+        }
+        i++;
+    }
+    return i;
+}
+/**
+ * Skip a token value (ref, name, number, etc.) that is not a dict or array.
+ * Stops at the next top-level `/` preceded by whitespace, or at a `<<` pair.
+ */
+function skipTokenValue(str, i, valueStart) {
+    while (i < str.length) {
+        if (str[i] === "/" && i > valueStart) {
+            // Check if this '/' starts a new key (preceded by whitespace)
+            if (isWhitespace(str[i - 1])) {
+                break;
+            }
+        }
+        if (str[i] === "<" && i + 1 < str.length && str[i + 1] === "<") {
+            break; // shouldn't happen at this level, but be safe
+        }
+        i++;
+    }
+    return i;
+}

package/dist/browser/modules/pdf/core/digital-signature.d.ts

@@ -0,0 +1,109 @@
+/**
+ * PDF digital signature — verification and creation.
+ *
+ * Implements:
+ * - ASN.1 DER decode/encode (shared codec)
+ * - PKCS#7 / CMS SignedData parse and build
+ * - X.509 certificate public key extraction
+ * - PDF /ByteRange extraction and hash computation
+ * - Signature verification (RSA PKCS#1 v1.5 + SHA-256)
+ * - Signature creation (with ByteRange placeholder/backfill)
+ *
+ * Uses platform-native RSA via `@utils/crypto` (node:crypto on Node,
+ * Web Crypto API in browsers).
+ *
+ * @see RFC 5652 — CMS (Cryptographic Message Syntax)
+ * @see ITU-T X.690 — ASN.1 DER encoding rules
+ * @see ISO 32000-2:2020 §12.8 — Digital Signatures in PDF
+ */
+/** Parsed ASN.1 node. */
+export interface Asn1Node {
+    tag: number;
+    /** Raw bytes of the value (for primitive types). */
+    bytes: Uint8Array;
+    /** Child nodes (for constructed types). */
+    children: Asn1Node[];
+}
+/**
+ * Parse ASN.1 DER data from the root.
+ */
+export declare function asn1Parse(data: Uint8Array): Asn1Node;
+/** Parsed CMS SignedData info for verification. */
+export interface CmsSignedData {
+    /** The signer's certificate (DER). */
+    certificate: Uint8Array;
+    /** The signature value. */
+    signature: Uint8Array;
+    /** The digest algorithm OID. */
+    digestAlgorithmOid: string;
+    /** The signed attributes (DER-encoded SET for hash computation). */
+    signedAttrsRaw: Uint8Array;
+    /** The message digest from signed attributes. */
+    messageDigest: Uint8Array;
+}
+/**
+ * Parse a PKCS#7 / CMS SignedData structure from DER bytes.
+ * Extracts the first signer's info for verification.
+ */
+export declare function parseCmsSignedData(derBytes: Uint8Array): CmsSignedData;
+/** Options for building a CMS SignedData for PDF signing. */
+export interface SignOptions {
+    /** DER-encoded X.509 certificate. */
+    certificate: Uint8Array;
+    /** DER-encoded PKCS#8 private key. */
+    privateKey: Uint8Array;
+    /** The data to sign (the PDF byte ranges). */
+    data: Uint8Array;
+}
+/**
+ * Build a CMS SignedData (PKCS#7) structure for a PDF signature.
+ *
+ * Uses SHA-256 for digest and RSA PKCS#1 v1.5 for signing.
+ * The signature is created over signed attributes that include
+ * the content-type, message-digest, and signing-time.
+ */
+export declare function buildCmsSignedData(options: SignOptions): Promise<Uint8Array>;
+/** Result of verifying a PDF signature. */
+export interface SignatureVerificationResult {
+    /** Whether the signature is cryptographically valid. */
+    valid: boolean;
+    /** Whether the signed byte ranges cover the entire file (no unsigned gaps). */
+    coversWholeFile: boolean;
+    /** Digest algorithm used. */
+    digestAlgorithm: string;
+    /** Reason for failure, if any. */
+    reason?: string;
+}
+/**
+ * Verify a digital signature in a PDF document.
+ *
+ * @param pdfData - The complete PDF file bytes
+ * @param signatureHex - The hex-encoded PKCS#7 signature from the /Contents field
+ * @param byteRange - The /ByteRange array [offset1, length1, offset2, length2]
+ */
+export declare function verifyPdfSignature(pdfData: Uint8Array, signatureHex: string, byteRange: [number, number, number, number]): Promise<SignatureVerificationResult>;
+/**
+ * Create a PDF signature dictionary string with a placeholder /Contents.
+ * Returns the dict string and the placeholder that will be replaced.
+ *
+ * @param signerName - Optional signer name for /Name field
+ * @param reason - Optional reason for /Reason field
+ */
+export declare function buildSignatureDictPlaceholder(options?: {
+    name?: string;
+    reason?: string;
+    location?: string;
+    contactInfo?: string;
+}): {
+    dictString: string;
+    placeholder: string;
+};
+/**
+ * Patch a PDF with a real signature after the /ByteRange placeholder has been written.
+ *
+ * @param pdfBytes - The PDF bytes with placeholder /Contents and /ByteRange
+ * @param certificate - DER-encoded X.509 certificate
+ * @param privateKey - DER-encoded PKCS#8 private key
+ * @returns The signed PDF bytes
+ */
+export declare function signPdf(pdfBytes: Uint8Array, certificate: Uint8Array, privateKey: Uint8Array): Promise<Uint8Array>;