ooxml-core 0.9.0 → 0.10.0

package/dist/crypto/key-derivation.d.ts

@@ -0,0 +1,73 @@
+/**
+ * OOXML encryption key derivation ([MS-OFFCRYPTO] 2.3.4.7 and 2.3.4.11).
+ *
+ * The password spin (100,000 rounds for agile, 50,000 for Standard) runs on the synchronous
+ * digests of the shared `digest` area when the hash is one it computes, so a key is derived
+ * without awaiting Web Crypto once per round; other hashes fall back to Web Crypto.
+ *
+ * Moved from `src/pptx/core/utils/ooxml-crypto-key-derivation.ts` (see PROVENANCE.md).
+ */
+/** Well-known block keys for agile encryption as defined in [MS-OFFCRYPTO]. */
+export declare const BLOCK_KEYS: {
+    readonly verifierHashInput: Uint8Array<ArrayBuffer>;
+    readonly verifierHashValue: Uint8Array<ArrayBuffer>;
+    readonly encryptedKeyValue: Uint8Array<ArrayBuffer>;
+    readonly dataIntegrityHmacKey: Uint8Array<ArrayBuffer>;
+    readonly dataIntegrityHmacValue: Uint8Array<ArrayBuffer>;
+};
+/** The largest spin count honoured; Office writes 100,000, far more is a hostile file. */
+export declare const MAX_SPIN_COUNT = 10000000;
+/**
+ * The spun password hash for agile key derivation (the expensive part). Derive several block
+ * keys from one base with {@link deriveAgileKeyFromBase} instead of spinning again for each.
+ */
+export declare function computeAgileKeyBase(password: string, salt: Uint8Array, spinCount: number, hashAlgorithm: string): Promise<Uint8Array>;
+/** Finishes agile key derivation for one block key: Hfinal = H(base + blockKey), sized. */
+export declare function deriveAgileKeyFromBase(base: Uint8Array, hashAlgorithm: string, blockKey: Uint8Array, keyBits: number, hashSize: number): Promise<Uint8Array>;
+/**
+ * Derive an encryption key from a password using the OOXML agile encryption key derivation
+ * algorithm.
+ *
+ * @param password - User's password.
+ * @param salt - Salt from EncryptionInfo.
+ * @param spinCount - Number of hash iterations.
+ * @param hashAlgorithm - Hash algorithm name (e.g. "SHA-512").
+ * @param blockKey - Block key for deriving specific sub-keys.
+ * @param keyBits - Desired key length in bits.
+ * @param hashSize - Hash output size in bytes.
+ * @returns Derived key of keyBits/8 bytes.
+ */
+export declare function deriveAgileKey(password: string, salt: Uint8Array, spinCount: number, hashAlgorithm: string, blockKey: Uint8Array, keyBits: number, hashSize: number): Promise<Uint8Array>;
+/**
+ * Compute the expensive, password/salt-dependent part of Standard Encryption key derivation:
+ * `H50000`, the result of hashing salt+password and then iterating 50,000 times.
+ *
+ * Only OOXML Standard Encryption spins. The legacy `.ppt` "RC4 CryptoAPI" scheme has no spin
+ * rounds and lives in the pptx area (`ppt/rc4-cryptoapi-key.ts`).
+ */
+export declare function computeStandardKeyBase(password: string, salt: Uint8Array): Promise<Uint8Array>;
+/**
+ * Finish Standard Encryption key derivation for one block, given the expensive base from
+ * {@link computeStandardKeyBase}: `Hfinal = H(H50000 + blockKey)`, then always the X1/X2/X3
+ * extension, of which the key is the first `keySize` bits ([MS-OFFCRYPTO] 2.3.4.7). Unlike the
+ * binary-document RC4 CryptoAPI derivation (2.3.5.2), a 128-bit key is not a plain truncation of
+ * Hfinal.
+ */
+export declare function deriveStandardKeyFromBase(base: Uint8Array, keySize: number, blockNumber?: number): Promise<Uint8Array>;
+/**
+ * Derive the encryption key for OOXML Standard Encryption (Office 2007), [MS-OFFCRYPTO]
+ * 2.3.4.7 (50,000 spin rounds).
+ *
+ * @param password - User's password.
+ * @param salt - Salt from the verifier.
+ * @param keySize - Key size in bits (e.g. 128).
+ * @param _algIdHash - Algorithm ID for hashing (always SHA-1 in practice).
+ * @param blockNumber - Block number (0 for Standard Encryption).
+ */
+export declare function deriveStandardKey(password: string, salt: Uint8Array, keySize: number, _algIdHash: number, blockNumber?: number): Promise<Uint8Array>;
+/**
+ * Generate an IV for agile encryption: H(salt + blockKey), truncated to `blockSize` or padded
+ * with 0x36.
+ */
+export declare function generateIV(hashAlgorithm: string, salt: Uint8Array, blockKey: Uint8Array, blockSize: number): Promise<Uint8Array>;
+//# sourceMappingURL=key-derivation.d.ts.map

package/dist/crypto/key-derivation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-derivation.d.ts","sourceRoot":"","sources":["../../src/crypto/key-derivation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,+EAA+E;AAC/E,eAAO,MAAM,UAAU;;;;;;CAMb,CAAC;AAEX,0FAA0F;AAC1F,eAAO,MAAM,cAAc,WAAa,CAAC;AA+CzC;;;GAGG;AACH,wBAAgB,mBAAmB,CAClC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACnB,OAAO,CAAC,UAAU,CAAC,CAErB;AAED,2FAA2F;AAC3F,wBAAsB,sBAAsB,CAC3C,IAAI,EAAE,UAAU,EAChB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,UAAU,EACpB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACd,OAAO,CAAC,UAAU,CAAC,CAKrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,UAAU,EACpB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACd,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAE9F;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC9C,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,MAAM,EACf,WAAW,SAAI,GACb,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACtC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,WAAW,SAAI,GACb,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAC/B,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,UAAU,EACpB,SAAS,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,CAAC,CAMrB"}

package/dist/crypto/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Type definitions for OOXML package encryption and decryption.
+ *
+ * Moved from `src/pptx/core/utils/ooxml-crypto-types.ts` (see PROVENANCE.md).
+ */
+/** Supported encryption algorithms. */
+export type EncryptionAlgorithm = 'AES128' | 'AES256';
+/**
+ * Which OOXML encryption scheme to write when creating a password-protected
+ * file. Office can write and open either scheme; this library defaults to
+ * 'agile' (Office 2010+), matching Office's own default.
+ */
+export type EncryptionScheme = 'agile' | 'standard';
+/** Parsed encryption info from the EncryptionInfo stream (agile format). */
+export interface EncryptionInfo {
+    /** Encryption version (major.minor). */
+    version: {
+        major: number;
+        minor: number;
+    };
+    /** Whether this is agile encryption. */
+    isAgile: boolean;
+    /** Key encryption data. */
+    keyData: {
+        saltSize: number;
+        blockSize: number;
+        keyBits: number;
+        hashSize: number;
+        cipherAlgorithm: string;
+        cipherChaining: string;
+        hashAlgorithm: string;
+        saltValue: Uint8Array;
+    };
+    /** Data integrity verification. */
+    dataIntegrity?: {
+        encryptedHmacKey: Uint8Array;
+        encryptedHmacValue: Uint8Array;
+    };
+    /** Password verifier encryption data. */
+    passwordKeyEncryptor: {
+        saltSize: number;
+        blockSize: number;
+        keyBits: number;
+        hashSize: number;
+        cipherAlgorithm: string;
+        cipherChaining: string;
+        hashAlgorithm: string;
+        saltValue: Uint8Array;
+        spinCount: number;
+        encryptedVerifierHashInput: Uint8Array;
+        encryptedVerifierHashValue: Uint8Array;
+        encryptedKeyValue: Uint8Array;
+    };
+}
+/**
+ * Standard encryption info (Office 2007 format, versions 2.x/3.x/4.x).
+ */
+export interface StandardEncryptionInfo {
+    /** Encryption version (major.minor). */
+    version: {
+        major: number;
+        minor: number;
+    };
+    /** Always false for standard encryption. */
+    isAgile: false;
+    /** Always true for standard encryption. */
+    isStandard: true;
+    /** Encryption flags. */
+    flags: number;
+    /** Size of the encryption header in bytes. */
+    headerSize: number;
+    /** Encryption header describing algorithm and provider. */
+    header: {
+        flags: number;
+        algId: number;
+        algIdHash: number;
+        keySize: number;
+        providerType: number;
+        cspName: string;
+    };
+    /** Password verifier data. */
+    verifier: {
+        saltSize: number;
+        salt: Uint8Array;
+        encryptedVerifier: Uint8Array;
+        verifierHashSize: number;
+        encryptedVerifierHash: Uint8Array;
+    };
+}
+/** Encryption options for creating encrypted files. */
+export interface EncryptionOptions {
+    /** The encryption algorithm to use (defaults to AES256). */
+    algorithm?: EncryptionAlgorithm;
+    /** Number of hash iterations for key derivation (defaults to 100000). Lower values speed up tests. */
+    spinCount?: number;
+    /**
+     * Which encryption scheme to write (defaults to 'agile'). 'standard'
+     * writes the ECMA-376 Standard scheme (Office 2007-compatible: a single
+     * password-derived AES-CBC key with a zero IV over the whole package),
+     * mirroring the scheme this library already knows how to decrypt.
+     */
+    encryptionScheme?: EncryptionScheme;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/crypto/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/crypto/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,uCAAuC;AACvC,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEtD;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,UAAU,CAAC;AAEpD,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC9B,wCAAwC;IACxC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,2BAA2B;IAC3B,OAAO,EAAE;QACR,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,eAAe,EAAE,MAAM,CAAC;QACxB,cAAc,EAAE,MAAM,CAAC;QACvB,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,UAAU,CAAC;KACtB,CAAC;IACF,mCAAmC;IACnC,aAAa,CAAC,EAAE;QACf,gBAAgB,EAAE,UAAU,CAAC;QAC7B,kBAAkB,EAAE,UAAU,CAAC;KAC/B,CAAC;IACF,yCAAyC;IACzC,oBAAoB,EAAE;QACrB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,eAAe,EAAE,MAAM,CAAC;QACxB,cAAc,EAAE,MAAM,CAAC;QACvB,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,UAAU,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,0BAA0B,EAAE,UAAU,CAAC;QACvC,0BAA0B,EAAE,UAAU,CAAC;QACvC,iBAAiB,EAAE,UAAU,CAAC;KAC9B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,wCAAwC;IACxC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,4CAA4C;IAC5C,OAAO,EAAE,KAAK,CAAC;IACf,2CAA2C;IAC3C,UAAU,EAAE,IAAI,CAAC;IACjB,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,MAAM,EAAE;QACP,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,8BAA8B;IAC9B,QAAQ,EAAE;QACT,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,UAAU,CAAC;QACjB,iBAAiB,EAAE,UAAU,CAAC;QAC9B,gBAAgB,EAAE,MAAM,CAAC;QACzB,qBAAqB,EAAE,UAAU,CAAC;KAClC,CAAC;CACF;AAED,uDAAuD;AACvD,MAAM,WAAW,iBAAiB;IACjC,4DAA4D;IAC5D,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC,sGAAsG;IACtG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACpC"}

package/dist/docx/embedded.cjs

@@ -1071,6 +1071,8 @@ function isSafeHyperlinkHref(href) {
   const scheme = /^([a-z][a-z0-9+.-]*:)/i.exec(href.trim())?.[1];
   return scheme !== void 0 && SAFE_SCHEMES.has(scheme.toLowerCase());
 }
+var OPEN_SCHEMES = /* @__PURE__ */ new Set(["http", "https", "mailto"]);
+/* @__PURE__ */ new Set([...OPEN_SCHEMES, "ftp", "file"]);
 
 // src/docx/zip-parts.ts
 var DOCUMENT_RELS_PATH = "word/_rels/document.xml.rels";

package/dist/docx/embedded.mjs

@@ -1065,6 +1065,8 @@ function isSafeHyperlinkHref(href) {
   const scheme = /^([a-z][a-z0-9+.-]*:)/i.exec(href.trim())?.[1];
   return scheme !== void 0 && SAFE_SCHEMES.has(scheme.toLowerCase());
 }
+var OPEN_SCHEMES = /* @__PURE__ */ new Set(["http", "https", "mailto"]);
+/* @__PURE__ */ new Set([...OPEN_SCHEMES, "ftp", "file"]);
 
 // src/docx/zip-parts.ts
 var DOCUMENT_RELS_PATH = "word/_rels/document.xml.rels";

package/dist/docx/index.cjs

@@ -1708,6 +1708,8 @@ function isSafeHyperlinkHref(href) {
   const scheme = /^([a-z][a-z0-9+.-]*:)/i.exec(href.trim())?.[1];
   return scheme !== void 0 && SAFE_SCHEMES.has(scheme.toLowerCase());
 }
+var OPEN_SCHEMES = /* @__PURE__ */ new Set(["http", "https", "mailto"]);
+/* @__PURE__ */ new Set([...OPEN_SCHEMES, "ftp", "file"]);
 
 // src/docx/zip-parts.ts
 var DOCUMENT_RELS_PATH = "word/_rels/document.xml.rels";

package/dist/docx/index.mjs

@@ -1702,6 +1702,8 @@ function isSafeHyperlinkHref(href) {
   const scheme = /^([a-z][a-z0-9+.-]*:)/i.exec(href.trim())?.[1];
   return scheme !== void 0 && SAFE_SCHEMES.has(scheme.toLowerCase());
 }
+var OPEN_SCHEMES = /* @__PURE__ */ new Set(["http", "https", "mailto"]);
+/* @__PURE__ */ new Set([...OPEN_SCHEMES, "ftp", "file"]);
 
 // src/docx/zip-parts.ts
 var DOCUMENT_RELS_PATH = "word/_rels/document.xml.rels";

package/dist/docx/load/detect.d.ts

@@ -1,6 +1,18 @@
 import type { LoadedDocument } from '../model.js';
-export type DocumentFormat = 'docx' | 'doc';
+/**
+ * A detected document format. `'encrypted'` is a .docx saved with a password to open (a compound
+ * file holding EncryptionInfo and EncryptedPackage), not a Word 97-2003 .doc.
+ */
+export type DocumentFormat = 'docx' | 'doc' | 'encrypted';
 export declare function detectDocumentFormat(input: Uint8Array | ArrayBuffer): DocumentFormat;
+export interface LoadDocumentOptions {
+    /**
+     * The password to open an encrypted (password-protected) .docx. Without it such a file throws
+     * `PasswordRequiredError` (`code: 'password-required'`); a wrong one throws
+     * `IncorrectPasswordError` (`code: 'incorrect-password'`).
+     */
+    password?: string;
+}
 /** Sniff content, never trust a user-supplied filename extension. */
-export declare function loadDocument(input: Uint8Array | ArrayBuffer): Promise<LoadedDocument>;
+export declare function loadDocument(input: Uint8Array | ArrayBuffer, options?: LoadDocumentOptions): Promise<LoadedDocument>;
 //# sourceMappingURL=detect.d.ts.map

package/dist/docx/load/detect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../../src/docx/load/detect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,KAAK,CAAC;AAC5C,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,cAAc,CASpF;AACD,qEAAqE;AACrE,wBAAsB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,OAAO,CAAC,cAAc,CAAC,CAE3F"}
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../../src/docx/load/detect.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,KAAK,GAAG,WAAW,CAAC;AAK1D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,cAAc,CAQpF;AAED,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAKD,qEAAqE;AACrE,wBAAsB,YAAY,CACjC,KAAK,EAAE,UAAU,GAAG,WAAW,EAC/B,OAAO,GAAE,mBAAwB,GAC/B,OAAO,CAAC,cAAc,CAAC,CAczB"}