@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/browser/modules/word/{digital-signatures.js → security/digital-signatures.js}

@@ -13,14 +13,17 @@
  * - Detection and extraction of signature metadata
  * - Preservation of signatures through round-trip (via opaqueParts)
  *
- * Note: Creating new signatures requires X.509 certificate handling and
- * is outside the scope of this module. Consider using a dedicated signing
- * tool for the actual signing step.
+ * Note: This module does NOT validate signature integrity (would require
+ * full XMLDSig + Canonical XML implementation). Signatures are preserved
+ * verbatim but become invalid if the package contents change.
  *
  * References:
- *   - OPC: Open Packaging Conventions (ECMA-376 Part 2)
+ *   - MS-OFFCRYPTO §3.2.6 Digital Signatures
  *   - XMLDSig: https://www.w3.org/TR/xmldsig-core/
  */
+import { xmlDecode } from "../../xml/encode.js";
+import { utf8Decoder } from "../core/internal-utils.js";
+import { getFileName } from "../core/opc-paths.js";
 /**
  * Check if a document has digital signatures.
  *
@@ -40,33 +43,34 @@ export function hasDigitalSignatures(opaquePaths) {
 export function parseSignatureXml(xmlStr, fileName) {
     const info = {
         rawXml: xmlStr,
-        fileName
+        fileName,
+        cryptographicStatus: "not-verified"
     };
     // Extract Office-specific metadata from <SignatureInfoV1>
     const sigTextMatch = /<SignatureText[^>]*>([^<]*)<\/SignatureText>/.exec(xmlStr);
     if (sigTextMatch) {
-        info.signer = decodeEntities(sigTextMatch[1]);
+        info.signer = xmlDecode(sigTextMatch[1]);
     }
     const sigCommentsMatch = /<SignatureComments[^>]*>([^<]*)<\/SignatureComments>/.exec(xmlStr);
     if (sigCommentsMatch) {
-        info.signatureComments = decodeEntities(sigCommentsMatch[1]);
+        info.signatureComments = xmlDecode(sigCommentsMatch[1]);
     }
     const purposeMatch = /<SignaturePurpose[^>]*>([^<]*)<\/SignaturePurpose>/.exec(xmlStr);
     if (purposeMatch) {
-        info.purpose = decodeEntities(purposeMatch[1]);
+        info.purpose = xmlDecode(purposeMatch[1]);
     }
     const dateMatch = /<SignatureDate[^>]*>([^<]*)<\/SignatureDate>/.exec(xmlStr);
     if (dateMatch) {
-        info.signDate = dateMatch[1];
+        info.signDate = xmlDecode(dateMatch[1]);
     }
     const providerMatch = /<SignatureProviderUrl[^>]*>([^<]*)<\/SignatureProviderUrl>/.exec(xmlStr);
     if (providerMatch) {
-        info.providerUrl = decodeEntities(providerMatch[1]);
+        info.providerUrl = xmlDecode(providerMatch[1]);
     }
     // Commitment type
     const commitMatch = /<CommitmentType[^>]*>\s*<CommitmentTypeIndication[^>]*>\s*<CommitmentTypeId>([^<]*)<\/CommitmentTypeId>/.exec(xmlStr);
     if (commitMatch) {
-        info.commitmentType = commitMatch[1];
+        info.commitmentType = xmlDecode(commitMatch[1]);
     }
     // Extract signature value (base64)
     const sigValMatch = /<SignatureValue[^>]*>([^]*?)<\/SignatureValue>/.exec(xmlStr);
@@ -76,15 +80,15 @@ export function parseSignatureXml(xmlStr, fileName) {
     // Certificate details from <X509Data>
     const certSubjectMatch = /<X509SubjectName[^>]*>([^<]*)<\/X509SubjectName>/.exec(xmlStr);
     if (certSubjectMatch) {
-        info.certificateSubject = decodeEntities(certSubjectMatch[1]);
+        info.certificateSubject = xmlDecode(certSubjectMatch[1]);
     }
     const certIssuerMatch = /<X509IssuerName[^>]*>([^<]*)<\/X509IssuerName>/.exec(xmlStr);
     if (certIssuerMatch) {
-        info.certificateIssuer = decodeEntities(certIssuerMatch[1]);
+        info.certificateIssuer = xmlDecode(certIssuerMatch[1]);
     }
     const certSerialMatch = /<X509SerialNumber[^>]*>([^<]*)<\/X509SerialNumber>/.exec(xmlStr);
     if (certSerialMatch) {
-        info.certificateSerialNumber = certSerialMatch[1];
+        info.certificateSerialNumber = xmlDecode(certSerialMatch[1]);
     }
     return info;
 }
@@ -99,36 +103,32 @@ export function extractSignatures(opaqueParts) {
         return [];
     }
     const signatures = [];
-    const decoder = new TextDecoder("utf-8");
     for (const part of opaqueParts) {
         if (part.path.startsWith("_xmlsignatures/sig") && part.path.endsWith(".xml")) {
-            const xmlStr = decoder.decode(part.data);
-            const fileName = part.path.split("/").pop() ?? "";
+            const xmlStr = utf8Decoder.decode(part.data);
+            const fileName = getFileName(part.path);
             signatures.push(parseSignatureXml(xmlStr, fileName));
         }
     }
     return signatures;
 }
 /**
- * Verify that a digital signature's structural integrity is intact.
+ * Check that a parsed signature has the structural elements XMLDSig
+ * requires (`Signature`, `SignedInfo`, `SignatureValue`, `KeyInfo`).
  *
- * Note: This does NOT verify the cryptographic signature — that requires
- * access to the signer's public key and a full XMLDSig implementation.
- * Use a dedicated XMLDSig library for cryptographic verification.
+ * This is **not** a cryptographic check — see `cryptographicStatus`. It is
+ * also tolerant of namespace prefixes (`<ds:Signature>` etc.) which the
+ * previous implementation missed.
  *
- * @returns True if the signature structure is well-formed.
+ * @returns True if the signature XML carries the required elements.
  */
 export function isWellFormedSignature(info) {
-    return (info.rawXml.includes("<Signature ") &&
-        info.rawXml.includes("<SignedInfo") &&
-        info.rawXml.includes("<SignatureValue") &&
-        info.rawXml.includes("<KeyInfo"));
-}
-function decodeEntities(s) {
-    return s
-        .replace(/&lt;/g, "<")
-        .replace(/&gt;/g, ">")
-        .replace(/&quot;/g, '"')
-        .replace(/&apos;/g, "'")
-        .replace(/&amp;/g, "&");
+    // Allow optional namespace prefix and either an attribute-bearing or
+    // self-closing form — XMLDSig signatures in real DOCX files commonly
+    // use `<ds:Signature ...>` rather than the default-namespace form.
+    const hasElement = (local) => new RegExp(`<(?:[\\w-]+:)?${local}(?:\\s|>|/>)`).test(info.rawXml);
+    return (hasElement("Signature") &&
+        hasElement("SignedInfo") &&
+        hasElement("SignatureValue") &&
+        hasElement("KeyInfo"));
 }

package/dist/browser/modules/word/security/document-protection.d.ts

@@ -0,0 +1,93 @@
+/**
+ * DOCX Module - Document Protection
+ *
+ * Provides APIs for setting document protection passwords and restrictions.
+ * Supports all protection types defined in OOXML:
+ * - Read-only (no modifications allowed)
+ * - Comments only (only add comments)
+ * - Forms only (only fill form fields)
+ * - Tracked changes (all changes are tracked)
+ * - Sections (specific sections editable)
+ *
+ * Password hashing follows the ECMA-376 specification using
+ * iterative SHA-based hashing with salt.
+ */
+import type { DocxDocument } from "../types.js";
+/** Document protection type (edit restriction). */
+export type ProtectionEditType = "none" | "readOnly" | "comments" | "trackedChanges" | "forms";
+/** Hash algorithm for protection password. */
+export type ProtectionHashAlgorithm = "SHA-1" | "SHA-256" | "SHA-384" | "SHA-512";
+/** Options for setting document protection. */
+export interface DocumentProtectionOptions {
+    /** Type of edit restriction. */
+    readonly edit: ProtectionEditType;
+    /** Password to protect the document (will be hashed). */
+    readonly password?: string;
+    /** Hash algorithm. Default: "SHA-256". */
+    readonly hashAlgorithm?: ProtectionHashAlgorithm;
+    /** Number of hash iterations (spin count). Default: 100000. */
+    readonly spinCount?: number;
+    /** Whether protection is enforced. Default: true. */
+    readonly enforcement?: boolean;
+    /** Formatting restriction (prevent style changes). */
+    readonly formatting?: boolean;
+}
+/** Protection state as stored in settings. */
+export interface ProtectionState {
+    /** Edit restriction type. */
+    readonly edit: ProtectionEditType;
+    /** Whether protection is enforced. */
+    readonly enforcement: boolean;
+    /** Hash algorithm used. */
+    readonly hashAlgorithm?: string;
+    /** Computed hash value (base64). */
+    readonly hashValue?: string;
+    /** Salt (base64). */
+    readonly saltValue?: string;
+    /** Spin count (iterations). */
+    readonly spinCount?: number;
+    /** Formatting restriction. */
+    readonly formatting?: boolean;
+}
+/**
+ * Set document protection on a DocxDocument.
+ * Returns a new document with protection settings applied.
+ *
+ * @param doc - The document to protect.
+ * @param options - Protection options.
+ * @returns A new document with protection settings.
+ *
+ * @example
+ * ```ts
+ * const protected = await protectDocument(doc, {
+ *   edit: "readOnly",
+ *   password: "secret123",
+ *   hashAlgorithm: "SHA-256"
+ * });
+ * ```
+ */
+export declare function protectDocument(doc: DocxDocument, options: DocumentProtectionOptions): Promise<DocxDocument>;
+/**
+ * Remove document protection.
+ *
+ * @param doc - The protected document.
+ * @returns A new document without protection.
+ */
+export declare function unprotectDocument(doc: DocxDocument): DocxDocument;
+/**
+ * Check if a document is protected.
+ */
+export declare function isDocumentProtected(doc: DocxDocument): boolean;
+/**
+ * Get the protection state of a document.
+ */
+export declare function getProtectionState(doc: DocxDocument): ProtectionState | undefined;
+/**
+ * Verify a password against the document's protection hash.
+ * Returns true if the password matches, false otherwise.
+ *
+ * @param doc - The protected document.
+ * @param password - The password to verify.
+ * @returns Whether the password is correct.
+ */
+export declare function verifyProtectionPassword(doc: DocxDocument, password: string): Promise<boolean>;

package/dist/browser/modules/word/security/document-protection.js

@@ -0,0 +1,201 @@
+/**
+ * DOCX Module - Document Protection
+ *
+ * Provides APIs for setting document protection passwords and restrictions.
+ * Supports all protection types defined in OOXML:
+ * - Read-only (no modifications allowed)
+ * - Comments only (only add comments)
+ * - Forms only (only fill form fields)
+ * - Tracked changes (all changes are tracked)
+ * - Sections (specific sections editable)
+ *
+ * Password hashing follows the ECMA-376 specification using
+ * iterative SHA-based hashing with salt.
+ */
+import { bytesToBase64, base64ToBytes, stringToUtf16LE, randomBytes } from "../core/internal-utils.js";
+// =============================================================================
+// Protection API
+// =============================================================================
+/**
+ * Set document protection on a DocxDocument.
+ * Returns a new document with protection settings applied.
+ *
+ * @param doc - The document to protect.
+ * @param options - Protection options.
+ * @returns A new document with protection settings.
+ *
+ * @example
+ * ```ts
+ * const protected = await protectDocument(doc, {
+ *   edit: "readOnly",
+ *   password: "secret123",
+ *   hashAlgorithm: "SHA-256"
+ * });
+ * ```
+ */
+export async function protectDocument(doc, options) {
+    const protection = await buildProtectionSettings(options);
+    const existingSettings = doc.settings ?? {};
+    const newSettings = {
+        ...existingSettings,
+        documentProtection: protection
+    };
+    return {
+        ...doc,
+        settings: newSettings
+    };
+}
+/**
+ * Remove document protection.
+ *
+ * @param doc - The protected document.
+ * @returns A new document without protection.
+ */
+export function unprotectDocument(doc) {
+    if (!doc.settings?.documentProtection) {
+        return doc;
+    }
+    const { documentProtection: _, ...rest } = doc.settings;
+    return {
+        ...doc,
+        settings: rest
+    };
+}
+/**
+ * Check if a document is protected.
+ */
+export function isDocumentProtected(doc) {
+    const dp = doc.settings?.documentProtection;
+    return dp !== undefined && dp.enforcement === true;
+}
+/**
+ * Get the protection state of a document.
+ */
+export function getProtectionState(doc) {
+    const dp = doc.settings?.documentProtection;
+    if (!dp) {
+        return undefined;
+    }
+    return {
+        edit: dp.edit ?? "none",
+        enforcement: dp.enforcement === true,
+        hashAlgorithm: dp.hashAlgorithm,
+        hashValue: dp.hashValue,
+        saltValue: dp.saltValue,
+        spinCount: dp.spinCount,
+        formatting: dp.formatting
+    };
+}
+/**
+ * Verify a password against the document's protection hash.
+ * Returns true if the password matches, false otherwise.
+ *
+ * @param doc - The protected document.
+ * @param password - The password to verify.
+ * @returns Whether the password is correct.
+ */
+export async function verifyProtectionPassword(doc, password) {
+    const dp = doc.settings?.documentProtection;
+    if (!dp || !dp.hashValue || !dp.saltValue || !dp.hashAlgorithm) {
+        return false;
+    }
+    // Cap spinCount: a hostile / malformed document could specify a huge
+    // value to make every verification call freeze the runtime.
+    // documentProtection is editing-restriction metadata, not a serious
+    // security boundary, but we still want a predictable upper bound on
+    // CPU time. Office UI typically writes 100_000.
+    const rawSpin = dp.spinCount ?? 100000;
+    if (!Number.isFinite(rawSpin) || rawSpin < 0 || rawSpin > 10000000) {
+        return false;
+    }
+    const spinCount = rawSpin;
+    const computedHash = await computePasswordHash(password, dp.saltValue, dp.hashAlgorithm, spinCount);
+    // Constant-time string comparison so an attacker cannot recover
+    // hashValue byte-by-byte from timing differences. A short-circuit
+    // `===` would leak the longest common prefix length.
+    return constantTimeEqualString(computedHash, dp.hashValue);
+}
+/**
+ * Length-aware constant-time string comparison.
+ *
+ * Returns false immediately when lengths differ (length itself is not a
+ * useful side-channel — it's already known from the stored hashValue
+ * and an attacker cannot influence it). For equal-length strings it
+ * XORs every char-code into a running accumulator and checks the
+ * accumulator only at the end.
+ */
+function constantTimeEqualString(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return diff === 0;
+}
+// =============================================================================
+// Internal: Password Hashing
+// =============================================================================
+async function buildProtectionSettings(options) {
+    const enforcement = options.enforcement !== false;
+    const result = {
+        edit: options.edit,
+        enforcement
+    };
+    if (options.formatting !== undefined) {
+        result.formatting = options.formatting;
+    }
+    if (options.password) {
+        const algorithm = options.hashAlgorithm ?? "SHA-256";
+        const spinCount = options.spinCount ?? 100000;
+        const salt = generateSalt();
+        const hash = await computePasswordHash(options.password, salt, algorithm, spinCount);
+        result.hashAlgorithm = algorithm;
+        result.saltValue = salt;
+        result.hashValue = hash;
+        result.spinCount = spinCount;
+    }
+    return result;
+}
+async function computePasswordHash(password, saltBase64, algorithm, spinCount) {
+    const algName = algorithmToSubtle(algorithm);
+    const saltBytes = base64ToBytes(saltBase64);
+    // ECMA-376 §14.2.1: password must be encoded as UTF-16LE
+    const passwordBytes = encodeUtf16LE(password);
+    // Initial hash: H0 = Hash(salt + password)
+    const initial = new Uint8Array(saltBytes.length + passwordBytes.length);
+    initial.set(saltBytes, 0);
+    initial.set(passwordBytes, saltBytes.length);
+    let hash = new Uint8Array(await crypto.subtle.digest(algName, initial));
+    // Iterative hashing: Hi = Hash(LE_int32(i) + Hi-1)
+    for (let i = 0; i < spinCount; i++) {
+        const iterBytes = new Uint8Array(4);
+        iterBytes[0] = i & 0xff;
+        iterBytes[1] = (i >> 8) & 0xff;
+        iterBytes[2] = (i >> 16) & 0xff;
+        iterBytes[3] = (i >> 24) & 0xff;
+        const combined = new Uint8Array(4 + hash.length);
+        combined.set(iterBytes, 0);
+        combined.set(hash, 4);
+        hash = new Uint8Array(await crypto.subtle.digest(algName, combined));
+    }
+    return bytesToBase64(hash);
+}
+/** Alias for UTF-16LE encoding (uses unified implementation). */
+const encodeUtf16LE = stringToUtf16LE;
+function algorithmToSubtle(alg) {
+    switch (alg) {
+        case "SHA-1":
+            return "SHA-1";
+        case "SHA-256":
+            return "SHA-256";
+        case "SHA-384":
+            return "SHA-384";
+        case "SHA-512":
+            return "SHA-512";
+    }
+}
+function generateSalt() {
+    return bytesToBase64(randomBytes(16));
+}

package/dist/{types/modules/word → browser/modules/word/security}/encryption.d.ts

@@ -9,9 +9,12 @@
  * - Password-based encryption/decryption of DOCX content
  * - EncryptionInfo XML generation/parsing
  *
- * Note: A full implementation requires a CFB container reader/writer for the
- * outer compound document format. For now, we expose primitives that can be
- * combined with an external CFB library if needed.
+ * All AES and SHA primitives are delegated to `@utils/crypto`, which uses
+ * synchronous `node:crypto` APIs in Node and Web Crypto in the browser.
+ * The KDF inner loop runs ~100,000 hashes per derived key; on Node we go
+ * through the synchronous fast path so a round-trip completes in well
+ * under a second instead of the multi-second microtask churn that the
+ * old `await crypto.subtle.digest()` loop produced.
  *
  * References:
  *   - MS-OFFCRYPTO: Office Document Cryptography Structure
@@ -88,9 +91,13 @@ export declare function verifyPassword(password: string, info: AgileEncryptionIn
  * @param encryptedPackage - The EncryptedPackage stream from CFB.
  * @param info - Agile encryption parameters.
  * @param password - The user password.
+ * @param maxDecryptedSize - Optional upper bound on the decrypted size; if the
+ *   `totalSize` header claims a larger value, throw rather than allocate.
+ *   Defaults to 512 MiB so adversarial files cannot trigger arbitrary-size
+ *   allocations before security policy is applied at the unzip layer.
  * @returns The decrypted (unencrypted) package bytes.
  */
-export declare function decryptPackage(encryptedPackage: Uint8Array, info: AgileEncryptionInfo, password: string): Promise<Uint8Array>;
+export declare function decryptPackage(encryptedPackage: Uint8Array, info: AgileEncryptionInfo, password: string, maxDecryptedSize?: number): Promise<Uint8Array>;
 /**
  * Parse an EncryptionInfo XML stream from a CFB-wrapped encrypted DOCX.
  *
@@ -100,3 +107,43 @@ export declare function decryptPackage(encryptedPackage: Uint8Array, info: Agile
  * @returns Parsed agile encryption info.
  */
 export declare function parseEncryptionInfoXml(xmlStr: string): AgileEncryptionInfo;
+/**
+ * Read an encrypted DOCX file by providing a password.
+ *
+ * Handles the full pipeline:
+ * 1. Parse CFB container
+ * 2. Extract EncryptionInfo and EncryptedPackage streams
+ * 3. Verify password and decrypt
+ * 4. Return the decrypted DOCX ZIP bytes
+ *
+ * @param buffer - The encrypted DOCX file (CFB format).
+ * @param password - The password to decrypt with.
+ * @param maxDecryptedSize - Optional cap on the decrypted size (defaults to 512 MiB).
+ * @returns The decrypted DOCX ZIP bytes (can be passed to readDocx).
+ * @throws Error if the file is not encrypted, password is wrong, or decryption fails.
+ */
+export declare function decryptDocx(buffer: Uint8Array, password: string, maxDecryptedSize?: number): Promise<Uint8Array>;
+/** Options for DOCX encryption. */
+export interface EncryptOptions {
+    /** Key length in bits. Default: 256. */
+    readonly keyBits?: 128 | 192 | 256;
+    /** Hash algorithm. Default: SHA512. */
+    readonly hashAlgorithm?: "SHA1" | "SHA256" | "SHA384" | "SHA512";
+    /** Number of KDF iterations (spin count). Default: 100000. */
+    readonly spinCount?: number;
+}
+/**
+ * Encrypt a DOCX ZIP file with a password using Agile Encryption (MS-OFFCRYPTO).
+ *
+ * Produces a CFB (OLE2 Compound File) containing:
+ *   - EncryptionInfo stream (Agile encryption XML)
+ *   - EncryptedPackage stream (segment-encrypted ZIP data)
+ *
+ * The output can be opened by Microsoft Word with the given password.
+ *
+ * @param zipBytes - The unencrypted DOCX content (ZIP format).
+ * @param password - The password to encrypt with.
+ * @param options - Encryption options (key length, hash algorithm, spin count).
+ * @returns The encrypted DOCX as a CFB-formatted Uint8Array.
+ */
+export declare function encryptDocx(zipBytes: Uint8Array, password: string, options?: EncryptOptions): Promise<Uint8Array>;