xls-codec 4.5.0 → 4.7.0

package/dist/workbook/encryption.cjs

@@ -0,0 +1,78 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_biff_record_types = require("../biff/record-types.cjs");
+const require_biff_records = require("../biff/records.cjs");
+const require_biff_cursor = require("../biff/cursor.cjs");
+let archive_codec = require("archive-codec");
+//#region src/workbook/encryption.ts
+/** [MS-XLS] 2.4.117's own wEncryptionType: RC4 encryption, as opposed to 0x0000 (XOR obfuscation, out of scope). */
+const ENCRYPTION_TYPE_RC4 = 1;
+/** [MS-OFFCRYPTO] 2.3.6.1's own EncryptionVersionInfo: vMajor/vMinor MUST both be 1 for the "RC4 encryption header" this module reads. vMajor 2/3/4 with vMinor 2 names the RC4 CryptoAPI encryption header instead (2.3.5.1), a different, unimplemented header shape. */
+const RC4_HEADER_VERSION_MAJOR = 1;
+const RC4_HEADER_VERSION_MINOR = 1;
+/** The first four bytes of a BoundSheet8 record's own data ([MS-XLS] 2.4.28): lbPlyPos, the one field [MS-XLS] 2.2.10 names as never encrypted even though the rest of the record is. */
+const BOUNDSHEET8_LBPLYPOS_SIZE = 4;
+/** [MS-XLS] 2.2.10's own list of records that "MUST NOT be obfuscated or encrypted" wherever they occur in the workbook stream -- BOF and FilePass are checked ahead of this set by their callers, since both matter beyond encryption too. */
+const NEVER_ENCRYPTED_RECORD_TYPES = /* @__PURE__ */ new Set([
+	require_biff_record_types.RECORD_BOF,
+	47,
+	404,
+	405,
+	225,
+	406,
+	312
+]);
+/** Reads FilePass's own fields, rejecting the two encryption schemes this module does not implement with a specific message rather than a generic parse failure. */
+function readFilePassRc4Header(filePassRecord) {
+	const cursor = new require_biff_cursor.BlockCursor([filePassRecord.data]);
+	const encryptionType = cursor.u16();
+	if (encryptionType !== ENCRYPTION_TYPE_RC4) throw new require_biff_records.BiffFormatError(`workbook uses FilePass wEncryptionType 0x${encryptionType.toString(16).padStart(4, "0")} (XOR obfuscation), which this reader does not decrypt`);
+	const versionMajor = cursor.u16();
+	const versionMinor = cursor.u16();
+	if (versionMajor !== RC4_HEADER_VERSION_MAJOR || versionMinor !== RC4_HEADER_VERSION_MINOR) throw new require_biff_records.BiffFormatError(`workbook uses RC4 CryptoAPI encryption (EncryptionVersionInfo ${versionMajor}.${versionMinor}), which this reader does not decrypt`);
+	return {
+		salt: cursor.take(archive_codec.OFFICE_RC4_VERIFIER_LENGTH),
+		encryptedVerifier: cursor.take(archive_codec.OFFICE_RC4_VERIFIER_LENGTH),
+		encryptedVerifierHash: cursor.take(archive_codec.OFFICE_RC4_VERIFIER_LENGTH)
+	};
+}
+/** [MS-OFFCRYPTO] 2.3.6.4's own password verification: block 0's key decrypts EncryptedVerifier, and MD5 of the result must equal the same block's decryption of EncryptedVerifierHash. Both verifier fields sit in one continuous keystream starting at position 0, not two independently-reset ones -- though decryptOfficeRc4 regenerates its keystream fresh from block start on every call regardless, so decrypting them as two separate 16-byte calls at offsets 0 and 16 is equivalent to one 32-byte call, not merely close to it. */
+function verifyOfficeRc4Password(baseHash, header) {
+	const decryptedVerifier = (0, archive_codec.decryptOfficeRc4)(baseHash, 0, header.encryptedVerifier);
+	const decryptedVerifierHash = (0, archive_codec.decryptOfficeRc4)(baseHash, archive_codec.OFFICE_RC4_VERIFIER_LENGTH, header.encryptedVerifierHash);
+	const computedHash = (0, archive_codec.md5)(decryptedVerifier);
+	if (!(computedHash.length === decryptedVerifierHash.length && computedHash.every((byte, index) => byte === decryptedVerifierHash[index]))) throw new require_biff_records.BiffFormatError("incorrect password for RC4-encrypted workbook");
+}
+/** Decrypts one record's own data in place against the derived base hash, honouring every [MS-XLS] 2.2.10 exclusion: a never-encrypted record's data is returned unchanged, BoundSheet8's own lbPlyPos prefix is preserved while the rest of its data is decrypted, and everything else is decrypted whole. `record.offset` is the record's own header start, so its data begins `HEADER_SIZE` bytes further into the stream -- the position [MS-OFFCRYPTO]'s block-keyed keystream is defined against. */
+function decryptRecord(record, baseHash) {
+	if (NEVER_ENCRYPTED_RECORD_TYPES.has(record.type)) return record;
+	const dataOffset = record.offset + 4;
+	if (record.type === 133) {
+		const lbPlyPos = record.data.subarray(0, BOUNDSHEET8_LBPLYPOS_SIZE);
+		const decryptedRest = (0, archive_codec.decryptOfficeRc4)(baseHash, dataOffset + BOUNDSHEET8_LBPLYPOS_SIZE, record.data.subarray(BOUNDSHEET8_LBPLYPOS_SIZE));
+		const data = new Uint8Array(record.data.length);
+		data.set(lbPlyPos, 0);
+		data.set(decryptedRest, BOUNDSHEET8_LBPLYPOS_SIZE);
+		return {
+			...record,
+			data
+		};
+	}
+	return {
+		...record,
+		data: (0, archive_codec.decryptOfficeRc4)(baseHash, dataOffset, record.data)
+	};
+}
+/**
+* Decrypts every record of a workbook stream protected by [MS-OFFCRYPTO] 2.3.6.1's RC4 encryption header, given the `FilePass` record already located within `records` and the password to decrypt it with.
+*
+* Throws `BiffFormatError` for a missing password, an incorrect one, or an encryption scheme this module does not implement (RC4 CryptoAPI, XOR obfuscation) -- there is no partial or best-effort result to return in any of those cases.
+*/
+function decryptWorkbookRecords(records, filePassRecord, password) {
+	const header = readFilePassRc4Header(filePassRecord);
+	if (password === void 0) throw new require_biff_records.BiffFormatError("workbook is RC4-encrypted (FilePass record); call readXlsContent with a password to decrypt it");
+	const baseHash = (0, archive_codec.deriveOfficeRc4BaseHash)(password, header.salt);
+	verifyOfficeRc4Password(baseHash, header);
+	return records.map((record) => decryptRecord(record, baseHash));
+}
+//#endregion
+exports.decryptWorkbookRecords = decryptWorkbookRecords;

package/dist/workbook/encryption.d.cts

@@ -0,0 +1,10 @@
+import { n as BiffRecord } from "../records-G82UEVq8.cjs";
+//#region src/workbook/encryption.d.ts
+/**
+ * Decrypts every record of a workbook stream protected by [MS-OFFCRYPTO] 2.3.6.1's RC4 encryption header, given the `FilePass` record already located within `records` and the password to decrypt it with.
+ *
+ * Throws `BiffFormatError` for a missing password, an incorrect one, or an encryption scheme this module does not implement (RC4 CryptoAPI, XOR obfuscation) -- there is no partial or best-effort result to return in any of those cases.
+ */
+declare function decryptWorkbookRecords(records: readonly BiffRecord[], filePassRecord: BiffRecord, password: string | undefined): readonly BiffRecord[];
+//#endregion
+export { decryptWorkbookRecords };

package/dist/workbook/encryption.d.ts

@@ -0,0 +1,10 @@
+import { n as BiffRecord } from "../records-G82UEVq8.js";
+//#region src/workbook/encryption.d.ts
+/**
+ * Decrypts every record of a workbook stream protected by [MS-OFFCRYPTO] 2.3.6.1's RC4 encryption header, given the `FilePass` record already located within `records` and the password to decrypt it with.
+ *
+ * Throws `BiffFormatError` for a missing password, an incorrect one, or an encryption scheme this module does not implement (RC4 CryptoAPI, XOR obfuscation) -- there is no partial or best-effort result to return in any of those cases.
+ */
+declare function decryptWorkbookRecords(records: readonly BiffRecord[], filePassRecord: BiffRecord, password: string | undefined): readonly BiffRecord[];
+//#endregion
+export { decryptWorkbookRecords };

package/dist/workbook/encryption.js

@@ -0,0 +1,77 @@
+import { RECORD_BOF } from "../biff/record-types.js";
+import { BiffFormatError } from "../biff/records.js";
+import { BlockCursor } from "../biff/cursor.js";
+import { OFFICE_RC4_VERIFIER_LENGTH, decryptOfficeRc4, deriveOfficeRc4BaseHash, md5 } from "archive-codec";
+//#region src/workbook/encryption.ts
+/** [MS-XLS] 2.4.117's own wEncryptionType: RC4 encryption, as opposed to 0x0000 (XOR obfuscation, out of scope). */
+const ENCRYPTION_TYPE_RC4 = 1;
+/** [MS-OFFCRYPTO] 2.3.6.1's own EncryptionVersionInfo: vMajor/vMinor MUST both be 1 for the "RC4 encryption header" this module reads. vMajor 2/3/4 with vMinor 2 names the RC4 CryptoAPI encryption header instead (2.3.5.1), a different, unimplemented header shape. */
+const RC4_HEADER_VERSION_MAJOR = 1;
+const RC4_HEADER_VERSION_MINOR = 1;
+/** The first four bytes of a BoundSheet8 record's own data ([MS-XLS] 2.4.28): lbPlyPos, the one field [MS-XLS] 2.2.10 names as never encrypted even though the rest of the record is. */
+const BOUNDSHEET8_LBPLYPOS_SIZE = 4;
+/** [MS-XLS] 2.2.10's own list of records that "MUST NOT be obfuscated or encrypted" wherever they occur in the workbook stream -- BOF and FilePass are checked ahead of this set by their callers, since both matter beyond encryption too. */
+const NEVER_ENCRYPTED_RECORD_TYPES = /* @__PURE__ */ new Set([
+	RECORD_BOF,
+	47,
+	404,
+	405,
+	225,
+	406,
+	312
+]);
+/** Reads FilePass's own fields, rejecting the two encryption schemes this module does not implement with a specific message rather than a generic parse failure. */
+function readFilePassRc4Header(filePassRecord) {
+	const cursor = new BlockCursor([filePassRecord.data]);
+	const encryptionType = cursor.u16();
+	if (encryptionType !== ENCRYPTION_TYPE_RC4) throw new BiffFormatError(`workbook uses FilePass wEncryptionType 0x${encryptionType.toString(16).padStart(4, "0")} (XOR obfuscation), which this reader does not decrypt`);
+	const versionMajor = cursor.u16();
+	const versionMinor = cursor.u16();
+	if (versionMajor !== RC4_HEADER_VERSION_MAJOR || versionMinor !== RC4_HEADER_VERSION_MINOR) throw new BiffFormatError(`workbook uses RC4 CryptoAPI encryption (EncryptionVersionInfo ${versionMajor}.${versionMinor}), which this reader does not decrypt`);
+	return {
+		salt: cursor.take(OFFICE_RC4_VERIFIER_LENGTH),
+		encryptedVerifier: cursor.take(OFFICE_RC4_VERIFIER_LENGTH),
+		encryptedVerifierHash: cursor.take(OFFICE_RC4_VERIFIER_LENGTH)
+	};
+}
+/** [MS-OFFCRYPTO] 2.3.6.4's own password verification: block 0's key decrypts EncryptedVerifier, and MD5 of the result must equal the same block's decryption of EncryptedVerifierHash. Both verifier fields sit in one continuous keystream starting at position 0, not two independently-reset ones -- though decryptOfficeRc4 regenerates its keystream fresh from block start on every call regardless, so decrypting them as two separate 16-byte calls at offsets 0 and 16 is equivalent to one 32-byte call, not merely close to it. */
+function verifyOfficeRc4Password(baseHash, header) {
+	const decryptedVerifier = decryptOfficeRc4(baseHash, 0, header.encryptedVerifier);
+	const decryptedVerifierHash = decryptOfficeRc4(baseHash, OFFICE_RC4_VERIFIER_LENGTH, header.encryptedVerifierHash);
+	const computedHash = md5(decryptedVerifier);
+	if (!(computedHash.length === decryptedVerifierHash.length && computedHash.every((byte, index) => byte === decryptedVerifierHash[index]))) throw new BiffFormatError("incorrect password for RC4-encrypted workbook");
+}
+/** Decrypts one record's own data in place against the derived base hash, honouring every [MS-XLS] 2.2.10 exclusion: a never-encrypted record's data is returned unchanged, BoundSheet8's own lbPlyPos prefix is preserved while the rest of its data is decrypted, and everything else is decrypted whole. `record.offset` is the record's own header start, so its data begins `HEADER_SIZE` bytes further into the stream -- the position [MS-OFFCRYPTO]'s block-keyed keystream is defined against. */
+function decryptRecord(record, baseHash) {
+	if (NEVER_ENCRYPTED_RECORD_TYPES.has(record.type)) return record;
+	const dataOffset = record.offset + 4;
+	if (record.type === 133) {
+		const lbPlyPos = record.data.subarray(0, BOUNDSHEET8_LBPLYPOS_SIZE);
+		const decryptedRest = decryptOfficeRc4(baseHash, dataOffset + BOUNDSHEET8_LBPLYPOS_SIZE, record.data.subarray(BOUNDSHEET8_LBPLYPOS_SIZE));
+		const data = new Uint8Array(record.data.length);
+		data.set(lbPlyPos, 0);
+		data.set(decryptedRest, BOUNDSHEET8_LBPLYPOS_SIZE);
+		return {
+			...record,
+			data
+		};
+	}
+	return {
+		...record,
+		data: decryptOfficeRc4(baseHash, dataOffset, record.data)
+	};
+}
+/**
+* Decrypts every record of a workbook stream protected by [MS-OFFCRYPTO] 2.3.6.1's RC4 encryption header, given the `FilePass` record already located within `records` and the password to decrypt it with.
+*
+* Throws `BiffFormatError` for a missing password, an incorrect one, or an encryption scheme this module does not implement (RC4 CryptoAPI, XOR obfuscation) -- there is no partial or best-effort result to return in any of those cases.
+*/
+function decryptWorkbookRecords(records, filePassRecord, password) {
+	const header = readFilePassRc4Header(filePassRecord);
+	if (password === void 0) throw new BiffFormatError("workbook is RC4-encrypted (FilePass record); call readXlsContent with a password to decrypt it");
+	const baseHash = deriveOfficeRc4BaseHash(password, header.salt);
+	verifyOfficeRc4Password(baseHash, header);
+	return records.map((record) => decryptRecord(record, baseHash));
+}
+//#endregion
+export { decryptWorkbookRecords };

package/dist/workbook/globals-writer.d.cts

@@ -1,5 +1,5 @@
 import { E as XfDecorationFields } from "../xf-colors-mqerVt2O.cjs";
-import { t as PrintNamePlanEntry } from "../print-names-DyYloloV.cjs";
+import { t as PrintNamePlanEntry } from "../print-names-CCwUHAoL.cjs";
 import { Alignment, Color } from "document-schema.js";
 //#region src/workbook/globals-writer.d.ts
 /** [MS-XLS] 2.1.7.20.3's own XFS production requires at least sixteen XF records before any cell can reference one: BUILTIN_STYLES.length built-in cell styles, then at least one cell XF -- the "General, no declared format" one every workbook needs unconditionally, written immediately after them. Derived from BUILTIN_STYLES's own length rather than restated as a literal, so the two can never drift apart. */

package/dist/workbook/globals-writer.d.ts

@@ -1,5 +1,5 @@
 import { E as XfDecorationFields } from "../xf-colors-d3OvRw76.js";
-import { t as PrintNamePlanEntry } from "../print-names-C-PQ2vAy.js";
+import { t as PrintNamePlanEntry } from "../print-names-CxAbgcjB.js";
 import { Alignment, Color } from "document-schema.js";
 //#region src/workbook/globals-writer.d.ts
 /** [MS-XLS] 2.1.7.20.3's own XFS production requires at least sixteen XF records before any cell can reference one: BUILTIN_STYLES.length built-in cell styles, then at least one cell XF -- the "General, no declared format" one every workbook needs unconditionally, written immediately after them. Derived from BUILTIN_STYLES's own length rather than restated as a literal, so the two can never drift apart. */

package/dist/workbook/globals.d.cts

@@ -1,7 +1,7 @@
 import { a as SheetRange, t as ExternalSheetLabel } from "../ptg-CCBbJLZJ.cjs";
-import { t as RecordGroup } from "../substreams-Cpy5Fi3d.cjs";
+import { t as RecordGroup } from "../substreams-CHv3oWmn.cjs";
 import { E as XfDecorationFields, w as XfAlignmentFields } from "../xf-colors-mqerVt2O.cjs";
-import { n as SheetPrintNames } from "../print-names-DyYloloV.cjs";
+import { n as SheetPrintNames } from "../print-names-CCwUHAoL.cjs";
 import { Color } from "document-schema.js";
 //#region src/workbook/globals.d.ts
 /** One sheet, as its BoundSheet8 record describes it ([MS-XLS] 2.4.28). */

package/dist/workbook/globals.d.ts

@@ -1,7 +1,7 @@
 import { a as SheetRange, t as ExternalSheetLabel } from "../ptg-CCBbJLZJ.js";
-import { t as RecordGroup } from "../substreams-CmyZMtuM.js";
+import { t as RecordGroup } from "../substreams-Dp5cZoUo.js";
 import { E as XfDecorationFields, w as XfAlignmentFields } from "../xf-colors-d3OvRw76.js";
-import { n as SheetPrintNames } from "../print-names-C-PQ2vAy.js";
+import { n as SheetPrintNames } from "../print-names-CxAbgcjB.js";
 import { Color } from "document-schema.js";
 //#region src/workbook/globals.d.ts
 /** One sheet, as its BoundSheet8 record describes it ([MS-XLS] 2.4.28). */

package/dist/workbook/print-names.d.cts

@@ -1,2 +1,2 @@
-import { a as writePrintNameRecords, i as readPrintNames, n as SheetPrintNames, r as printNameEntriesFor, t as PrintNamePlanEntry } from "../print-names-DyYloloV.cjs";
+import { a as writePrintNameRecords, i as readPrintNames, n as SheetPrintNames, r as printNameEntriesFor, t as PrintNamePlanEntry } from "../print-names-CCwUHAoL.cjs";
 export { PrintNamePlanEntry, SheetPrintNames, printNameEntriesFor, readPrintNames, writePrintNameRecords };

package/dist/workbook/print-names.d.ts

@@ -1,2 +1,2 @@
-import { a as writePrintNameRecords, i as readPrintNames, n as SheetPrintNames, r as printNameEntriesFor, t as PrintNamePlanEntry } from "../print-names-C-PQ2vAy.js";
+import { a as writePrintNameRecords, i as readPrintNames, n as SheetPrintNames, r as printNameEntriesFor, t as PrintNamePlanEntry } from "../print-names-CxAbgcjB.js";
 export { PrintNamePlanEntry, SheetPrintNames, printNameEntriesFor, readPrintNames, writePrintNameRecords };

package/dist/workbook/sheet.d.cts

@@ -1,9 +1,9 @@
 import { n as SetupFields } from "../print-setup-B_ihDvm5.cjs";
 import { r as FormulaSheetContext } from "../ptg-CCBbJLZJ.cjs";
-import { t as RecordGroup } from "../substreams-Cpy5Fi3d.cjs";
-import { n as RawConditionalFormat } from "../conditional-format-DUQuOrNW.cjs";
-import { i as RawConditionalFormat12 } from "../conditional-format-12-DdEL5DL0.cjs";
-import { t as RawDataValidation } from "../data-validation-DZPzAW-8.cjs";
+import { t as RecordGroup } from "../substreams-CHv3oWmn.cjs";
+import { n as RawConditionalFormat } from "../conditional-format-Czh2oTzQ.cjs";
+import { a as RawConditionalFormat12 } from "../conditional-format-12-DBhe7Zo6.cjs";
+import { t as RawDataValidation } from "../data-validation-DfpjUN-N.cjs";
 //#region src/workbook/sheet.d.ts
 /** A cell's value as its own record carries it, before number-format classification decides whether a number is really a date, a percentage, or an amount of money. */
 type RawCellValue = {

package/dist/workbook/sheet.d.ts

@@ -1,9 +1,9 @@
 import { n as SetupFields } from "../print-setup-B_ihDvm5.js";
 import { r as FormulaSheetContext } from "../ptg-CCBbJLZJ.js";
-import { t as RecordGroup } from "../substreams-CmyZMtuM.js";
-import { n as RawConditionalFormat } from "../conditional-format-BV2313jL.js";
-import { i as RawConditionalFormat12 } from "../conditional-format-12-Dw82ECRh.js";
-import { t as RawDataValidation } from "../data-validation-DsVG0Mms.js";
+import { t as RecordGroup } from "../substreams-Dp5cZoUo.js";
+import { n as RawConditionalFormat } from "../conditional-format-DOdazxWe.js";
+import { a as RawConditionalFormat12 } from "../conditional-format-12-D-X5g_O3.js";
+import { t as RawDataValidation } from "../data-validation-BXvIVU0e.js";
 //#region src/workbook/sheet.d.ts
 /** A cell's value as its own record carries it, before number-format classification decides whether a number is really a date, a percentage, or an amount of money. */
 type RawCellValue = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xls-codec",
-  "version": "4.5.0",
+  "version": "4.7.0",
   "description": "Hand-written reader for the legacy Excel Binary File Format (.xls, BIFF8) as specified by [MS-XLS], mapping a workbook's record stream onto the shared document-schema.js spreadsheet model - the .xls codec for the documents.js family.",
   "type": "module",
   "repository": {
@@ -70,7 +70,7 @@
   },
   "packageManager": "pnpm@11.6.0",
   "dependencies": {
-    "archive-codec": "^1.6.8",
+    "archive-codec": "^1.7.0",
     "document-schema.js": "^7.3.0",
     "excel-number-format": "^1.1.0"
   },