@lotics/xlsx 0.1.4 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/xlsx",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

package/src/biff8_reader.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { parseBiff8, isOle2 } from "./biff8_reader";
+import { PasswordProtectedError } from "./types";
+
+// A synthetic BIFF8 (.xls) workbook: 250 data rows of Unicode strings + integer,
+// float and negative numbers. The Unicode strings push the shared-string table
+// past one record boundary, so decoding row 200 exercises the SST CONTINUE +
+// per-continue grbit path. No real data — minted purely to lock the reader.
+const fixture = new Uint8Array(readFileSync(fileURLToPath(new URL("./biff8_fixtures/synthetic.xls", import.meta.url))));
+
+const cell = (sheet: ReturnType<typeof parseBiff8>["sheets"][number], row: number, col: number): unknown =>
+  sheet.rows.find((r) => r.index === row)?.cells.find((c) => c.column === col)?.typedValue;
+
+describe("parseBiff8", () => {
+  it("detects the OLE2 container", () => {
+    expect(isOle2(fixture)).toBe(true);
+    expect(isOle2(new Uint8Array([0x50, 0x4b, 0x03, 0x04]))).toBe(false); // a zip (.xlsx) is not OLE2
+    expect(isOle2(new Uint8Array([0x00]))).toBe(false);
+  });
+
+  it("reads the sheet name and full row count", () => {
+    const s = parseBiff8(fixture).sheets[0];
+    expect(s.name).toBe("GiaoDich");
+    expect(s.totalRowCount).toBe(251); // header + 250 rows
+  });
+
+  it("decodes Unicode text cells", () => {
+    const s = parseBiff8(fixture).sheets[0];
+    expect(cell(s, 0, 0)).toBe("ID");
+    expect(cell(s, 0, 1)).toBe("Tên khách");
+    expect(cell(s, 0, 2)).toBe("Số tiền");
+  });
+
+  it("decodes a string that falls past the SST CONTINUE boundary", () => {
+    const s = parseBiff8(fixture).sheets[0];
+    expect(cell(s, 200, 1)).toBe("Khách 200 — Công ty TNHH số 200");
+    expect(cell(s, 249, 1)).toBe("Khách 249 — Công ty TNHH số 249");
+  });
+
+  it("decodes integer, float and negative numbers to the exact value", () => {
+    const s = parseBiff8(fixture).sheets[0];
+    expect(cell(s, 2, 2)).toBe(2000); // integer (RK int)
+    expect(cell(s, 3, 2)).toBe(3000.5); // float
+    expect(cell(s, 5, 2)).toBe(-500); // negative
+    expect(cell(s, 200, 2)).toBe(-20000);
+    expect(cell(s, 249, 2)).toBe(249000.5);
+  });
+
+  it("honors maxRowsPerSheet and flags truncation", () => {
+    const s = parseBiff8(fixture, { maxRowsPerSheet: 10 }).sheets[0];
+    expect(s.truncated).toBe(true);
+    expect(s.rows.every((r) => r.index < 10)).toBe(true);
+  });
+
+  it("rejects an OLE2 buffer with no Workbook stream", () => {
+    // 8-byte OLE2 magic with no valid directory → not a readable workbook.
+    const bogus = new Uint8Array(512);
+    bogus.set([0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1]);
+    expect(() => parseBiff8(bogus)).toThrow();
+  });
+});
+
+// A date cell is a NUMBER record (Excel serial) whose XF points at a date
+// number-format. The reader must resolve XF → FORMAT so downstream renders a
+// date, not the raw serial — the common case the text-dated reconciliation file
+// never exercised. Fixture: a date, an integer, a decimal, a Unicode string.
+const dateFixture = new Uint8Array(readFileSync(fileURLToPath(new URL("./biff8_fixtures/synthetic_dates.xls", import.meta.url))));
+
+describe("parseBiff8 number formats", () => {
+  const cell = (row: number, col: number) => {
+    const s = parseBiff8(dateFixture).sheets[0];
+    return s.rows.find((r) => r.index === row)?.cells.find((c) => c.column === col);
+  };
+
+  it("reads a date cell as an Excel serial carrying its date number-format", () => {
+    const c = cell(1, 0);
+    expect(c?.typedValue).toBe(45672); // 2025-01-15
+    expect(c?.numFmtCode).toBe("dd/mm/yyyy");
+  });
+
+  it("leaves a plain number with no number-format (General)", () => {
+    expect(cell(1, 1)?.typedValue).toBe(42);
+    expect(cell(1, 1)?.numFmtCode).toBeUndefined();
+    expect(cell(1, 2)?.typedValue).toBe(1234.5);
+  });
+
+  it("decodes a Unicode string cell", () => {
+    expect(cell(1, 3)?.typedValue).toBe("Ábc");
+  });
+});
+
+// PasswordProtectedError is exported and reachable — encrypted .xls (FILEPASS)
+// and encrypted OOXML (EncryptedPackage stream) both route to it.
+describe("parseBiff8 encryption", () => {
+  it("surfaces PasswordProtectedError as the shared error type", () => {
+    expect(new PasswordProtectedError()).toBeInstanceOf(Error);
+  });
+});

package/src/biff8_reader.ts

@@ -0,0 +1,459 @@
+// Read legacy Excel 97–2003 binary workbooks (.xls / BIFF8) into the same
+// ParsedSpreadsheet model as the OOXML (.xlsx) parser, so every consumer —
+// view_files, FilePreview, imports, the CLI, custom apps — reads .xls with no
+// per-caller changes. A .xls is an OLE2 Compound File whose "Workbook" stream
+// is a sequence of BIFF records; we walk the CFB, then the record stream.
+//
+// Scope: the data grid — shared strings (SST, incl. CONTINUE splits), string
+// cells (LABELSST), numbers (NUMBER/RK/MULRK), cached formula results, blanks,
+// and number formats (for date/currency detection). Unknown records are skipped
+// (advance by length), so exotic features degrade gracefully instead of failing.
+// Encrypted files (FILEPASS record, or an OLE2 EncryptedPackage stream) throw
+// PasswordProtectedError. No third-party dependency and no eval/regex on file
+// bytes — the SheetJS path this replaces was removed for prototype-pollution +
+// ReDoS CVEs.
+
+import { emptySheet } from "./ooxml_sheet";
+import type { ParseOptions } from "./excel_parser";
+import { PasswordProtectedError } from "./types";
+import type { ParsedSpreadsheet, ParsedSheet, ParsedRow, ParsedCell } from "./types";
+
+const OLE2_MAGIC = [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1];
+const ENDOFCHAIN = 0xfffffffe;
+const FREESECT = 0xffffffff;
+const DEFAULT_MAX_ROWS = 10_000;
+
+/** True when the bytes begin with the OLE2 Compound File signature (legacy .xls
+ *  or an encrypted OOXML package — both share this container). */
+export function isOle2(bytes: Uint8Array): boolean {
+  return bytes.length >= 8 && OLE2_MAGIC.every((b, i) => bytes[i] === b);
+}
+
+interface CfbStream {
+  name: string;
+  bytes: Uint8Array;
+}
+
+// ─── OLE2 / Compound File Binary container ──────────────────────────────────
+
+function readCfbStreams(bytes: Uint8Array): CfbStream[] {
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const u16 = (o: number) => dv.getUint16(o, true);
+  const u32 = (o: number) => dv.getUint32(o, true);
+
+  const sectorSize = 1 << u16(30);
+  const miniSectorSize = 1 << u16(32);
+  const firstDirSector = u32(48);
+  const miniCutoff = u32(56);
+  const firstMiniFatSector = u32(60);
+  const firstDifatSector = u32(68);
+
+  if (sectorSize < 512 || sectorSize > 1 << 20) {
+    throw new Error("Unsupported .xls: invalid OLE2 sector size");
+  }
+  const sectorOffset = (n: number) => sectorSize * (n + 1);
+
+  // DIFAT: first 109 entries live in the header; the rest chain through sectors.
+  const difat: number[] = [];
+  for (let i = 0; i < 109; i++) {
+    const v = u32(76 + i * 4);
+    if (v !== FREESECT) difat.push(v);
+  }
+  let ds = firstDifatSector;
+  const entriesPerSector = sectorSize / 4;
+  for (let guard = 0; ds !== ENDOFCHAIN && ds !== FREESECT && guard < 1 << 20; guard++) {
+    const base = sectorOffset(ds);
+    for (let i = 0; i < entriesPerSector - 1; i++) {
+      const v = u32(base + i * 4);
+      if (v !== FREESECT) difat.push(v);
+    }
+    ds = u32(base + (entriesPerSector - 1) * 4);
+  }
+
+  // FAT: sector-allocation chains, assembled from the DIFAT-listed FAT sectors.
+  const fat: number[] = [];
+  for (const fatSector of difat) {
+    const base = sectorOffset(fatSector);
+    for (let i = 0; i < entriesPerSector; i++) fat.push(u32(base + i * 4));
+  }
+
+  const readChain = (src: Uint8Array, start: number, size: number | null, ss: number, offOf: (n: number) => number, chain: number[]): Uint8Array => {
+    // A chain can't yield more sectors than the source holds; a longer walk is a
+    // cyclic/corrupt FAT (a crafted .xls DoS) — cap the read at the source size.
+    const maxSectors = Math.floor(src.length / ss) + 2;
+    const parts: Uint8Array[] = [];
+    let s = start;
+    for (let guard = 0; s !== ENDOFCHAIN && s !== FREESECT && s < chain.length && guard < maxSectors; guard++) {
+      const o = offOf(s);
+      parts.push(src.subarray(o, o + ss));
+      s = chain[s];
+    }
+    const merged = concat(parts);
+    return size != null ? merged.subarray(0, size) : merged;
+  };
+  const readBig = (start: number, size: number | null) => readChain(bytes, start, size, sectorSize, sectorOffset, fat);
+
+  // Directory: 128-byte entries in a FAT chain.
+  const dirBytes = readBig(firstDirSector, null);
+  const ddv = new DataView(dirBytes.buffer, dirBytes.byteOffset, dirBytes.byteLength);
+  interface DirEntry { name: string; type: number; start: number; size: number }
+  const dir: DirEntry[] = [];
+  for (let off = 0; off + 128 <= dirBytes.length; off += 128) {
+    const nameLen = ddv.getUint16(off + 64, true);
+    const type = ddv.getUint8(off + 66);
+    if (nameLen < 2 || type === 0) continue;
+    const name = utf16le(dirBytes.subarray(off, off + nameLen - 2));
+    dir.push({ name, type, start: ddv.getUint32(off + 116, true), size: Number(ddv.getBigUint64(off + 120, true)) });
+  }
+
+  // Mini stream (root entry's chain) holds streams below the cutoff, in mini sectors.
+  const root = dir.find((e) => e.type === 5);
+  const miniStream = root ? readBig(root.start, root.size) : new Uint8Array(0);
+  const miniFatBytes = readBig(firstMiniFatSector, null);
+  const miniFat: number[] = [];
+  for (let i = 0; i + 4 <= miniFatBytes.length; i += 4) miniFat.push(miniFatBytes[i] | (miniFatBytes[i + 1] << 8) | (miniFatBytes[i + 2] << 16) | (miniFatBytes[i + 3] << 24));
+  // Mini sectors index into the root mini-stream container, not the raw file.
+  const readMini = (start: number, size: number) => readChain(miniStream, start, size, miniSectorSize, (n) => n * miniSectorSize, miniFat);
+  const readStream = (e: DirEntry) => (e.size >= miniCutoff ? readBig(e.start, e.size) : readMini(e.start, e.size));
+
+  return dir.filter((e) => e.type === 2).map((e) => ({ name: e.name, bytes: readStream(e) }));
+}
+
+// ─── BIFF record stream ─────────────────────────────────────────────────────
+
+const REC = {
+  FORMULA: 0x0006, EOF: 0x000a, CONTINUE: 0x003c, DATEMODE: 0x0022, FILEPASS: 0x002f,
+  BLANK: 0x0201, NUMBER: 0x0203, LABEL: 0x0204, STRING: 0x0207, BOOLERR: 0x0205,
+  BOUNDSHEET: 0x0085, FORMAT: 0x041e, XF: 0x00e0, RK: 0x027e, MULRK: 0x00bd,
+  MULBLANK: 0x00be, LABELSST: 0x00fd, SST: 0x00fc, BOF: 0x0809,
+} as const;
+
+interface Record8 { type: number; body: Uint8Array; offset: number }
+
+function* iterRecords(stream: Uint8Array, from: number, to: number): Generator<Record8> {
+  const dv = new DataView(stream.buffer, stream.byteOffset, stream.byteLength);
+  let p = from;
+  while (p + 4 <= to) {
+    const type = dv.getUint16(p, true);
+    const len = dv.getUint16(p + 2, true);
+    const bodyStart = p + 4;
+    if (bodyStart + len > stream.length) break;
+    yield { type, body: stream.subarray(bodyStart, bodyStart + len), offset: p };
+    p = bodyStart + len;
+  }
+}
+
+interface Globals {
+  sst: string[];
+  date1904: boolean;
+  /** XF index → resolved number-format string. */
+  xfFormats: string[];
+  boundsheets: { name: string; pos: number }[];
+}
+
+function parseGlobals(stream: Uint8Array): Globals {
+  const sstChunks: Uint8Array[] = [];
+  const formats = new Map<number, string>();
+  const xfFormatIds: number[] = [];
+  const boundsheets: { name: string; pos: number }[] = [];
+  let date1904 = false;
+  let sawSst = false;
+  let sstUnique = 0;
+
+  // Globals substream = first BOF … first EOF.
+  let end = stream.length;
+  let started = false;
+  const dv = new DataView(stream.buffer, stream.byteOffset, stream.byteLength);
+  for (const r of iterRecords(stream, 0, stream.length)) {
+    if (r.type === REC.BOF) { if (started) { end = r.offset; break; } started = true; continue; }
+    if (r.type === REC.EOF) { end = r.offset; break; }
+  }
+
+  for (const r of iterRecords(stream, 0, end)) {
+    switch (r.type) {
+      case REC.FILEPASS:
+        throw new PasswordProtectedError();
+      case REC.DATEMODE:
+        date1904 = readU16(r.body, 0) === 1;
+        break;
+      case REC.SST:
+        sawSst = true;
+        sstUnique = readU32(r.body, 4); // cstTotal (0), cstUnique (4)
+        sstChunks.push(r.body.subarray(8)); // strings follow the 8-byte header
+        break;
+      case REC.CONTINUE:
+        if (sawSst) sstChunks.push(r.body);
+        break;
+      case REC.FORMAT: {
+        const id = readU16(r.body, 0);
+        formats.set(id, readUnicodeShort(r.body, 2, 2));
+        break;
+      }
+      case REC.XF: {
+        // ifmt is the number-format index at byte offset 2.
+        xfFormatIds.push(readU16(r.body, 2));
+        break;
+      }
+      case REC.BOUNDSHEET: {
+        const pos = dv.getUint32(r.offset + 4, true);
+        boundsheets.push({ name: readUnicodeShort(r.body, 6, 1), pos });
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  const sst = parseSst(sstChunks, sstUnique);
+  const xfFormats = xfFormatIds.map((id) => formats.get(id) ?? builtinFormat(id));
+  return { sst, date1904, xfFormats, boundsheets };
+}
+
+// ─── Shared string table (handles CONTINUE splits + per-continue grbit) ──────
+
+function parseSst(chunks: Uint8Array[], count: number): string[] {
+  const out: string[] = [];
+  if (chunks.length === 0) return out;
+  let ci = 0;
+  let off = 0;
+  const atEnd = () => ci >= chunks.length;
+  const cur = () => chunks[ci];
+  const advanceChunk = () => { ci++; off = 0; };
+  const rawU8 = (): number => {
+    while (!atEnd() && off >= cur().length) advanceChunk();
+    if (atEnd()) return 0;
+    return cur()[off++];
+  };
+  const rawU16 = () => rawU8() | (rawU8() << 8);
+  const rawU32 = () => rawU8() | (rawU8() << 8) | (rawU8() << 16) | (rawU8() << 24);
+  const skip = (n: number) => { for (let i = 0; i < n; i++) rawU8(); };
+
+  for (let s = 0; s < count && !atEnd(); s++) {
+    const cch = rawU16();
+    const grbit = rawU8();
+    let high = (grbit & 0x01) !== 0;
+    const rich = (grbit & 0x08) !== 0 ? rawU16() : 0;
+    const ext = (grbit & 0x04) !== 0 ? rawU32() : 0;
+
+    let str = "";
+    let read = 0;
+    while (read < cch) {
+      // A string's characters can spill into a CONTINUE record; the first byte
+      // of that record is a fresh grbit whose bit0 re-declares char width.
+      if (off >= cur().length) {
+        advanceChunk();
+        if (atEnd()) break;
+        high = (cur()[off++] & 0x01) !== 0;
+      }
+      if (high) {
+        const code = cur()[off] | (cur()[off + 1] << 8);
+        off += 2;
+        str += String.fromCharCode(code);
+      } else {
+        str += String.fromCharCode(cur()[off++]);
+      }
+      read++;
+    }
+    // Rich-text runs (4 bytes each) and phonetic ext data follow the chars and
+    // are continued without a fresh grbit — a plain byte skip across chunks.
+    skip(rich * 4 + ext);
+    out.push(str);
+  }
+  return out;
+}
+
+// ─── Sheet cells ────────────────────────────────────────────────────────────
+
+function parseSheet(stream: Uint8Array, start: number, name: string, g: Globals, maxRows: number): ParsedSheet {
+  const sheet = emptySheet(name);
+  // Row index → (col index → cell). Sparse; assembled into ParsedRow[] at the end.
+  const grid = new Map<number, Map<number, ParsedCell>>();
+  let maxRow = -1;
+  let truncated = false;
+
+  const put = (row: number, col: number, cell: ParsedCell) => {
+    if (row >= maxRows) { truncated = true; return; }
+    let r = grid.get(row);
+    if (!r) { r = new Map(); grid.set(row, r); }
+    r.set(col, cell);
+    if (row > maxRow) maxRow = row;
+  };
+
+  // The sheet substream runs from its BOF to the next EOF.
+  let end = stream.length;
+  let seenBof = false;
+  for (const r of iterRecords(stream, start, stream.length)) {
+    if (r.type === REC.BOF) { if (seenBof) { end = r.offset; break; } seenBof = true; continue; }
+    if (r.type === REC.EOF) { end = r.offset; break; }
+  }
+
+  for (const r of iterRecords(stream, start, end)) {
+    switch (r.type) {
+      case REC.LABELSST: {
+        const row = readU16(r.body, 0), col = readU16(r.body, 2), isst = readU32(r.body, 6);
+        put(row, col, textCell(col, g.sst[isst] ?? ""));
+        break;
+      }
+      case REC.LABEL: {
+        const row = readU16(r.body, 0), col = readU16(r.body, 2);
+        put(row, col, textCell(col, readUnicodeShort(r.body, 6, 2)));
+        break;
+      }
+      case REC.NUMBER: {
+        const row = readU16(r.body, 0), col = readU16(r.body, 2), xf = readU16(r.body, 4);
+        put(row, col, numberCell(col, readF64(r.body, 6), g.xfFormats[xf]));
+        break;
+      }
+      case REC.RK: {
+        const row = readU16(r.body, 0), col = readU16(r.body, 2), xf = readU16(r.body, 4);
+        put(row, col, numberCell(col, decodeRk(readU32(r.body, 6)), g.xfFormats[xf]));
+        break;
+      }
+      case REC.MULRK: {
+        const row = readU16(r.body, 0), first = readU16(r.body, 2);
+        const n = (r.body.length - 6) / 6;
+        for (let i = 0; i < n; i++) {
+          const xf = readU16(r.body, 4 + i * 6);
+          const rk = readU32(r.body, 6 + i * 6);
+          put(row, first + i, numberCell(first + i, decodeRk(rk), g.xfFormats[xf]));
+        }
+        break;
+      }
+      case REC.FORMULA: {
+        const row = readU16(r.body, 0), col = readU16(r.body, 2), xf = readU16(r.body, 4);
+        const cell = formulaCell(col, r.body, g.xfFormats[xf]);
+        if (cell) put(row, col, cell);
+        break;
+      }
+      // BLANK / MULBLANK / BOOLERR carry no data value we surface — skipped.
+      default:
+        break;
+    }
+  }
+
+  const rows: ParsedRow[] = [];
+  for (let ri = 0; ri <= maxRow; ri++) {
+    const r = grid.get(ri);
+    if (!r) continue;
+    const cells = [...r.values()].sort((a, b) => a.column - b.column);
+    rows.push({ index: ri, height: sheet.defaultRowHeight, cells, hidden: false });
+  }
+  sheet.rows = rows;
+  sheet.totalRowCount = maxRow + 1;
+  sheet.truncated = truncated;
+  return sheet;
+}
+
+// ─── Cell builders ──────────────────────────────────────────────────────────
+
+function textCell(column: number, text: string): ParsedCell {
+  return { column, value: text, typedValue: text, content: { type: "plain", text }, style: {} };
+}
+
+function numberCell(column: number, num: number, numFmt: string | undefined): ParsedCell {
+  const value = Number.isFinite(num) ? String(num) : "";
+  return {
+    column, value, rawValue: num, typedValue: num,
+    numFmtCode: numFmt && numFmt !== "General" ? numFmt : undefined,
+    content: { type: "plain", text: value }, style: {},
+  };
+}
+
+function formulaCell(column: number, body: Uint8Array, numFmt: string | undefined): ParsedCell | null {
+  // Cached result: 8 bytes at offset 6. A trailing 0xFFFF marks a non-numeric
+  // result whose type is byte[6] (0=string in a following STRING rec, 1=bool,
+  // 2=error, 3=empty). Numeric results are an IEEE double.
+  if (readU16(body, 12) === 0xffff) {
+    const kind = body[6];
+    if (kind === 1) {
+      const b = body[8] !== 0;
+      return { column, value: b ? "TRUE" : "FALSE", typedValue: b, content: { type: "plain", text: b ? "TRUE" : "FALSE" }, style: {} };
+    }
+    // string (resolved by a following STRING record — none in scope), error, or
+    // empty: surface nothing rather than a wrong value.
+    return null;
+  }
+  return numberCell(column, readF64(body, 6), numFmt);
+}
+
+// ─── Encodings ──────────────────────────────────────────────────────────────
+
+/** Decode a BIFF RK number: bit0 = ÷100, bit1 = integer (else top 30 bits of a double). */
+function decodeRk(rk: number): number {
+  const div100 = (rk & 0x01) !== 0;
+  const isInt = (rk & 0x02) !== 0;
+  let n: number;
+  if (isInt) {
+    n = rk >> 2; // arithmetic shift keeps the sign
+  } else {
+    const buf = new ArrayBuffer(8);
+    new DataView(buf).setUint32(4, rk & 0xfffffffc, true);
+    n = new DataView(buf).getFloat64(0, true);
+  }
+  return div100 ? n / 100 : n;
+}
+
+function readU16(b: Uint8Array, o: number): number { return b[o] | (b[o + 1] << 8); }
+function readU32(b: Uint8Array, o: number): number { return (b[o] | (b[o + 1] << 8) | (b[o + 2] << 16) | (b[o + 3] << 24)) >>> 0; }
+function readF64(b: Uint8Array, o: number): number { return new DataView(b.buffer, b.byteOffset + o, 8).getFloat64(0, true); }
+
+/** A short (non-CONTINUE) BIFF8 unicode string: `lenBytes`-wide char count, a
+ *  1-byte grbit, then chars (8- or 16-bit). Used for sheet names and formats. */
+function readUnicodeShort(b: Uint8Array, offset: number, lenBytes: 1 | 2): string {
+  const cch = lenBytes === 1 ? b[offset] : readU16(b, offset);
+  const grbit = b[offset + lenBytes];
+  const high = (grbit & 0x01) !== 0;
+  let p = offset + lenBytes + 1;
+  let s = "";
+  for (let i = 0; i < cch; i++) {
+    if (high) { s += String.fromCharCode(b[p] | (b[p + 1] << 8)); p += 2; }
+    else { s += String.fromCharCode(b[p]); p += 1; }
+  }
+  return s;
+}
+
+function utf16le(b: Uint8Array): string {
+  let s = "";
+  for (let i = 0; i + 1 < b.length; i += 2) s += String.fromCharCode(b[i] | (b[i + 1] << 8));
+  return s;
+}
+
+function concat(parts: Uint8Array[]): Uint8Array {
+  let total = 0;
+  for (const p of parts) total += p.length;
+  const out = new Uint8Array(total);
+  let o = 0;
+  for (const p of parts) { out.set(p, o); o += p.length; }
+  return out;
+}
+
+/** Built-in number-format strings we care about (dates → so serials render as
+ *  dates downstream; currency/decimals are otherwise "General"). */
+function builtinFormat(id: number): string {
+  const DATES: Record<number, string> = {
+    14: "m/d/yyyy", 15: "d-mmm-yy", 16: "d-mmm", 17: "mmm-yy",
+    18: "h:mm AM/PM", 19: "h:mm:ss AM/PM", 20: "h:mm", 21: "h:mm:ss",
+    22: "m/d/yyyy h:mm", 45: "mm:ss", 46: "[h]:mm:ss", 47: "mm:ss.0",
+  };
+  return DATES[id] ?? "General";
+}
+
+// ─── Entry point ────────────────────────────────────────────────────────────
+
+/** Parse a legacy .xls (BIFF8) buffer into a ParsedSpreadsheet. Throws
+ *  PasswordProtectedError for encrypted workbooks. */
+export function parseBiff8(bytes: Uint8Array, options?: ParseOptions): ParsedSpreadsheet {
+  const streams = readCfbStreams(bytes);
+  if (streams.some((s) => /^EncryptedPackage$/i.test(s.name))) throw new PasswordProtectedError();
+  const wb = streams.find((s) => /^workbook$/i.test(s.name)) ?? streams.find((s) => /^book$/i.test(s.name));
+  if (!wb) throw new Error("Not a valid .xls: no Workbook stream in the OLE2 container");
+
+  const g = parseGlobals(wb.bytes);
+  const maxRows = options?.maxRowsPerSheet ?? DEFAULT_MAX_ROWS;
+
+  const sheets: ParsedSheet[] = g.boundsheets.length > 0
+    ? g.boundsheets.map((bs) => parseSheet(wb.bytes, bs.pos, bs.name, g, maxRows))
+    : [emptySheet("Sheet1")];
+
+  return { sheets, activeSheetIndex: 0 };
+}

package/src/excel_parser.ts

@@ -16,6 +16,7 @@ import {
   extractWorkbookPivotCaches,
 } from "./ooxml_pivot";
 import { parseVmlDrawing } from "./ooxml_shape";
+import { parseBiff8, isOle2 } from "./biff8_reader";
 import type { ParsedSpreadsheet, ParsedSheet, PrintTitles } from "./types";
 import type { ParsedChart } from "./ooxml_chart_types";
 import type { ParsedPivotCache, ParsedPivotTable } from "./ooxml_pivot_types";
@@ -88,6 +89,11 @@ export function parseExcelBuffer(
   arrayBuffer: ArrayBuffer,
   options?: ParseOptions,
 ): ParsedSpreadsheet {
+  // Legacy .xls (and encrypted OOXML) share the OLE2 container; route it to the
+  // BIFF8 reader, which reads legacy workbooks and throws PasswordProtectedError
+  // for genuinely encrypted files.
+  const bytes = new Uint8Array(arrayBuffer);
+  if (isOle2(bytes)) return parseBiff8(bytes, options);
   const zip = unzipXlsx(arrayBuffer);
   return parseExcelFromZip(zip, options);
 }