@cj-tech-master/excelts 9.5.4 → 9.5.5

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

@@ -0,0 +1,208 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.protectDocument = protectDocument;
+exports.unprotectDocument = unprotectDocument;
+exports.isDocumentProtected = isDocumentProtected;
+exports.getProtectionState = getProtectionState;
+exports.verifyProtectionPassword = verifyProtectionPassword;
+const internal_utils_1 = require("../core/internal-utils");
+// =============================================================================
+// 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"
+ * });
+ * ```
+ */
+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.
+ */
+function unprotectDocument(doc) {
+    if (!doc.settings?.documentProtection) {
+        return doc;
+    }
+    const { documentProtection: _, ...rest } = doc.settings;
+    return {
+        ...doc,
+        settings: rest
+    };
+}
+/**
+ * Check if a document is protected.
+ */
+function isDocumentProtected(doc) {
+    const dp = doc.settings?.documentProtection;
+    return dp !== undefined && dp.enforcement === true;
+}
+/**
+ * Get the protection state of a document.
+ */
+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.
+ */
+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 = (0, internal_utils_1.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 (0, internal_utils_1.bytesToBase64)(hash);
+}
+/** Alias for UTF-16LE encoding (uses unified implementation). */
+const encodeUtf16LE = internal_utils_1.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 (0, internal_utils_1.bytesToBase64)((0, internal_utils_1.randomBytes)(16));
+}