superdoc-macros 0.7.0 → 0.8.0

package/README.md

@@ -9,10 +9,11 @@ Three capabilities, in the spirit of Word macros:
 | **Scripted macros** | User-written JavaScript macros that run in a real sandbox (an isolated iframe) against a small, safe document API |
 | **Macro recorder** | "Record → work normally → stop → replay" — records commands and typing, like Word's recorder |
 | **Snippets (AutoText)** | Templates with variables (`{{date}}`, `{{selection}}`…), keyboard shortcuts, and auto-expansion while typing (type a trigger word + space) |
+| **VBA import (read-only)** | Reads the macros already inside a `.docm` and shows the user their real source, so they can port it. Nothing is executed |
 
 Plus: persistence (localStorage or custom storage), JSON import/export, keyboard shortcut binding, and localizable runtime messages (English by default, Hebrew locale included).
 
-> **A note on VBA:** the toolkit does not execute VBA macros from `.docm` files — there is no VBA engine in the browser. It provides a parallel, JavaScript-based macro system suited to a browser-hosted editor.
+> **A note on VBA:** the toolkit does not *execute* VBA — there is no VBA engine in the browser, and running document-supplied code is not something it will grow into. What it does instead is two things: it lets a user **see** the macros a `.docm` already contains (section 4), and it provides a parallel, JavaScript-based macro system to rewrite them in.
 
 ## Installation
 
@@ -87,7 +88,9 @@ If you must waive isolation (e.g. a CSP that blocks `srcdoc`), switch to the dir
 ## 2. Macro recorder
 
 ```ts
-kit.startRecording();
+if (!kit.startRecording()) {
+  throw new Error('A macro is running or an unsaved recording is pending');
+}
 // the user works normally: typing, formatting, lists...
 const recording = kit.stopRecording('Standard intro', 'Ctrl+Alt+1');
 
@@ -97,6 +100,8 @@ await kit.replayRecording(recording.id);
 
 The recorder captures **commands and typing**, not caret positions — exactly like Word's recorder: replay applies wherever the caret stands. Consecutive keystrokes coalesce into one step, `undo`/`redo` are not recorded (configurable via `RecorderOptions`), and recordings persist as clean JSON that can be exported and shared. `updateRecording({id, name?, shortcut?})` renames a recording or edits its shortcut.
 
+Finalization is loss-aware. A command payload that cannot be stored faithfully is reported instead of silently omitted; `stopRecording()` keeps the stopped capture pending until it is saved or explicitly cancelled. A mixed capture requires `{ allowIncomplete: true }` after the host has obtained user consent, while a capture containing no replayable step is rejected as `recording-uncapturable`. Storage, capacity, and validation failures are retryable: fix the problem and call `stopRecording()` again. Starting a new recording while one is pending is rejected, preventing accidental loss.
+
 ## 3. Snippets and auto-text
 
 ```ts
@@ -114,6 +119,93 @@ await kit.expandSnippet(id);   // or expand explicitly / via the shortcut
 
 Built-in variables: `{{date}}`, `{{time}}`, `{{datetime}}` (formatted with the browser locale, or an explicit `locale` option), `{{selection}}`. Any other name resolves from the `variables` passed to `expandSnippet`; a variable with no value stays visible in the text.
 
+## 4. Reading the VBA in an existing `.docm`
+
+A user who has relied on a macro-enabled document for years should not be told their macros are simply gone. This reads the macro project out of the package and hands back each module's real source text:
+
+```ts
+import { extractVbaFromDocx } from 'superdoc-macros';
+
+const result = await extractVbaFromDocx(fileBytes);   // Uint8Array of the .docm
+
+if (!result.ok) {
+  // 'no-macros' is the ordinary answer for a document without any.
+  console.log(result.reason, result.message);
+} else {
+  for (const module of result.project.modules) {
+    console.log(module.name, module.kind, module.source);
+  }
+  for (const warning of result.project.warnings) {
+    console.log(warning.code, warning.message);
+  }
+}
+```
+
+Hebrew and other non-Latin sources come back correct: VBA stores text in the project's code page (windows-1255 for Hebrew), and that is honoured rather than assumed to be UTF-8.
+
+When the answer decides something other than what to display — which extension to save under, say — ask the cheap question instead. `findVbaPart` reads only the relationship and content-type parts, decompresses nothing from the project itself, and never throws:
+
+```ts
+import { findVbaPart } from 'superdoc-macros';
+
+const part = await findVbaPart(fileBytes);   // 'word/vbaProject.bin' | null
+```
+
+Use this rather than "did extraction succeed", because the two answer different questions: a project too damaged to read is still a macro project, and a document carrying one must keep its `.docm` extension either way. For the same reason a failed extraction still reports `partName` whenever a macro part was located.
+
+Verified against genuine Office output, not only synthetic files — Word-authored `.docm` documents (including a Cyrillic, code-page-1251 project, and projects carrying `Tools ▸ References` entries) come back with their real module names, kinds and recorded-macro source intact. The test suite pins this with a real macro project as a fixture, alongside synthetic ones covering both container layouts, a Hebrew code page, and the record whose declared length the format itself gets wrong.
+
+### This does not run anything, and it is not wired to anything that does
+
+The security position is deliberate and worth stating plainly, because VBA in a document is code that arrived from outside:
+
+- **Nothing executes.** There is no interpreter, no transpiler, no `eval`. The functions decode bytes into strings.
+- **The extracted `source` is data, not code.** Never pass it to a script runner or to `new Function`: VBA is not JavaScript, so anything that did run would be attacker-chosen text reaching a JavaScript parser.
+- **Extraction is deliberately *not* a `MacroKit` method.** It creates no saved macro, binds no shortcut, and writes nothing to storage. Turning an extracted module into something runnable stays an explicit human decision, and the API shape says so.
+- **Auto-run entry points are reported, never honoured.** Word runs `AutoOpen`, `Document_Open` and friends on its own, which is exactly why they are a long-standing malware vector. They are listed in `project.autoRunProcedures` and raise an `auto-run-macros` warning so a host can tell the user what the original document did. `scanForAutoRunProcedures(source)` is exported for the same check on VBA from anywhere else.
+
+### Failure is a result, not an exception
+
+`extractVbaFromDocx` and `extractVbaProject` never throw — not on a truncated file, not on a hostile one. Every outcome is a result carrying a stable `reason` (`no-macros`, `not-a-package`, `not-a-vba-project`, `too-large`, `unsupported`, `unreadable`).
+
+Partial success is reported honestly rather than silently: a module that cannot be decoded appears in `warnings` with its name instead of vanishing from the list. Each warning carries a stable `code` to switch on (the `message` is English):
+
+| `code` | Meaning |
+| --- | --- |
+| `auto-run-macros` | The document defines macros Word would run on open. Read for review; not executed |
+| `module-unreadable` | A named module could not be decoded and was skipped |
+| `module-truncated` | A module's source was longer than the cap and was cut |
+| `declared-modules-missing` | The project declares modules the directory walk did not produce — the list you have is incomplete, and these are the names |
+| `incomplete-directory` | The macro directory ended unexpectedly; modules may be missing |
+| `no-modules` | The project has no readable modules |
+| `unknown-code-page` | The declared code page is unavailable here; text fell back to windows-1252 and non-Latin characters may be wrong |
+| `module-limit` / `total-size-limit` | A `VBA_LIMITS` cap stopped the read |
+
+The gap-reporting codes exist because a plausible-looking short list is worse than a short list with an explanation. `declared-modules-missing` is the strongest of them: it cross-checks the modules found against the project's own manifest, so a malformed record that desynchronizes the directory walk surfaces as a named gap rather than a module that quietly is not there.
+
+### Bounded against a file built to hurt you
+
+Every reader is bounded (`VBA_LIMITS`, `CFB_LIMITS`, `ZIP_LIMITS`) and every chain walk is loop-guarded, so a container whose allocation table points in a circle terminates, and a part declaring an absurd size is refused.
+
+Counting structural items is not enough on its own, though, and that is the part worth knowing about. A caller's real exposure is in quantities *derived* from the file, which a small input can inflate enormously — so those are metered too:
+
+- **Path length and nesting depth**, not just entry count. Storages nested one inside the next make each path longer than the last, so retained path strings grow with the square of the entry count.
+- **Bytes decompression actually produces**, not the size a header claims. The ZIP reader enforces its cap while inflating, so a part that declares a kilobyte and expands to a gigabyte is abandoned rather than buffered and then rejected.
+- **Warning count**, keyed on modules *considered* rather than modules successfully read — otherwise a project whose every stream fails emits one warning per record.
+- **Regex exposure.** XML is scanned with `indexOf`, not with a `<Tag[^>]*>` pattern, which backtracks quadratically on input containing no `>` at all. On a 260 KB input the difference measured 3 ms against 1.7 s, and it grows with the square.
+
+These are regression-tested, not just asserted: a deterministic corruption sweep over the container header and allocation tables, a deeply nested directory, XML crafted to force backtracking, a declared-size lie over expanding data, and a project declaring more modules than it has streams.
+
+No new dependencies: the OLE container reader, the ZIP reader and the [MS-OVBA] decompressor are part of the package. Inflation is delegated to the platform's own `DecompressionStream` — [Baseline across browsers since 2023](https://web.dev/blog/compressionstreams), and present in Node 18+ — so the decompression itself runs in audited native code rather than a hand-rolled inflater. An environment without it gets `reason: 'unsupported'`, not a crash.
+
+### Macros survive a save
+
+Independently of the above: a macro-enabled document that SuperDoc opens and exports **keeps its macro project intact**. Verified end-to-end against the SuperDoc v2 engine — open a `.docm`, edit the body, export, and `word/vbaProject.bin` comes back byte-identical, with the `macroEnabled` content type and the `vbaProject` relationship preserved, in all three export modes.
+
+Two things are the host's job:
+- **Save with the right extension.** A file carrying a macro project must stay `.docm`/`.dotm`; handing Word a `.docx` with a `vbaProject` part inside makes it complain.
+- **Don't rebuild the package by hand.** If you ever do, copy `word/vbaProject.bin`, `word/vbaData.xml`, the `vbaProject` relationship and the `[Content_Types].xml` override across from the original.
+
 ## Localization
 
 Runtime messages (failures shown to end users) default to English. A host with a localized UI swaps them once at startup:
@@ -156,7 +248,9 @@ The whole toolkit works against a single `MacroHost` interface (commands, text i
 
 ## Known limitations
 
-- No VBA execution. `.docm` files open normally but their macros are not run.
+- No VBA execution. `.docm` files open normally and their macros can be *read* (section 4), but nothing runs them — by design, not for want of trying.
+- VBA import reads code modules. It does not reconstruct UserForm layouts (only a form's code-behind), and it does not read the `vbaData.xml` keyboard-shortcut map — a `.docm`'s macro key bindings are not imported.
+- VBA import does not open ZIP64 or password-protected packages; both are refused with `reason: 'unsupported'` rather than guessed at.
 - The recorder does not capture caret movement or mouse selection (as in Word — replay acts from the current caret).
 - `deleteBackward` and full-document text use the engine's internal view (ProseMirror) — available in the browser, not headless.
 - The `eval` runner's time cap cannot stop an infinite synchronous loop (the iframe runner's can).

package/dist/import/cfb.d.ts

@@ -0,0 +1,44 @@
+export declare const CFB_LIMITS: {
+    /** Whole-container size. A `vbaProject.bin` is normally tens of kilobytes. */
+    readonly maxFileBytes: number;
+    /** Directory entries, i.e. streams plus storages. */
+    readonly maxEntries: 10000;
+    /** Sectors in one chain — the ceiling on any single stream's length. */
+    readonly maxChainSectors: 200000;
+    /** One stream's declared size. */
+    readonly maxStreamBytes: number;
+    /**
+     * Nesting depth of the directory tree, and the length of a resulting path.
+     *
+     * These are not cosmetic. Counting entries alone bounds how many paths
+     * exist but not how long they are, and the two multiply: 10,000 storages
+     * nested one inside the next, with 31-character names, describe paths whose
+     * lengths run 32, 64, 96 … — over a gigabyte of retained strings from a
+     * container that compresses to a few kilobytes. A real VBA project nests
+     * one storage deep.
+     */
+    readonly maxDepth: 32;
+    readonly maxPathLength: 1024;
+};
+export type CfbEntryType = 'root' | 'storage' | 'stream';
+export interface CfbEntry {
+    /** Absolute path inside the container, e.g. `/VBA/dir`. Root is `/`. */
+    readonly path: string;
+    /** The entry's own name, e.g. `dir`. */
+    readonly name: string;
+    readonly type: CfbEntryType;
+    /** Declared length in bytes. `0` for storages. */
+    readonly size: number;
+}
+export interface CfbContainer {
+    /** Every reachable entry, storages included, in directory-tree order. */
+    readonly entries: readonly CfbEntry[];
+    /**
+     * The bytes of one stream, by exact path.
+     *
+     * @throws {VbaParseError} when the path is absent, names a storage, or the
+     * stream's allocation chain is malformed.
+     */
+    readStream(path: string): Uint8Array;
+}
+export declare function readCfb(bytes: Uint8Array): CfbContainer;

package/dist/import/cfb.js

@@ -0,0 +1,378 @@
+/**
+ * A read-only reader for MS-CFB (the OLE "compound file" container).
+ *
+ * `vbaProject.bin` is not XML — it is a small filesystem in a file, with a
+ * sector allocation table, a directory tree, and a second allocation table
+ * for streams under 4096 bytes. VBA sources live in streams inside it, so
+ * reaching them means walking that structure.
+ *
+ * Written by hand rather than pulled from a package, for two reasons. The
+ * toolkit ships with no runtime dependencies, and this is the one place
+ * user-supplied bytes are parsed — a job worth owning outright, kept
+ * read-only (nothing here can write a CFB file) and defensive throughout:
+ *
+ * - Every sector offset is bounds-checked before it is read.
+ * - Every chain walk tracks visited sectors, so a file whose allocation
+ *   table points in a circle terminates instead of hanging.
+ * - Entry counts, chain lengths and stream sizes are capped.
+ *
+ * Deliberately unimplemented: writing, encryption, and CFB v4 files whose
+ * header declares a sector size other than 512 or 4096 bytes.
+ */
+import { VbaParseError } from './errors.js';
+export const CFB_LIMITS = {
+    /** Whole-container size. A `vbaProject.bin` is normally tens of kilobytes. */
+    maxFileBytes: 64 * 1024 * 1024,
+    /** Directory entries, i.e. streams plus storages. */
+    maxEntries: 10_000,
+    /** Sectors in one chain — the ceiling on any single stream's length. */
+    maxChainSectors: 200_000,
+    /** One stream's declared size. */
+    maxStreamBytes: 32 * 1024 * 1024,
+    /**
+     * Nesting depth of the directory tree, and the length of a resulting path.
+     *
+     * These are not cosmetic. Counting entries alone bounds how many paths
+     * exist but not how long they are, and the two multiply: 10,000 storages
+     * nested one inside the next, with 31-character names, describe paths whose
+     * lengths run 32, 64, 96 … — over a gigabyte of retained strings from a
+     * container that compresses to a few kilobytes. A real VBA project nests
+     * one storage deep.
+     */
+    maxDepth: 32,
+    maxPathLength: 1_024,
+};
+const SIGNATURE = [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1];
+const HEADER_BYTES = 512;
+const DIRECTORY_ENTRY_BYTES = 128;
+/** Sector ids above this are sentinels (end-of-chain, free, FAT, DIFAT). */
+const MAX_REGULAR_SECTOR = 0xfffffffa;
+/** DIFAT entries per header. */
+const HEADER_DIFAT_ENTRIES = 109;
+const HEADER_DIFAT_OFFSET = 76;
+export function readCfb(bytes) {
+    if (bytes.length > CFB_LIMITS.maxFileBytes) {
+        throw new VbaParseError('too-large', 'OLE container: file exceeds the size cap');
+    }
+    if (bytes.length < HEADER_BYTES) {
+        throw new VbaParseError('malformed', 'OLE container: file is shorter than its header');
+    }
+    for (let i = 0; i < SIGNATURE.length; i += 1) {
+        if (bytes[i] !== SIGNATURE[i]) {
+            throw new VbaParseError('malformed', 'OLE container: wrong signature');
+        }
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const u32 = (offset) => {
+        if (offset < 0 || offset + 4 > bytes.length) {
+            throw new VbaParseError('malformed', 'OLE container: read past the end of the file');
+        }
+        return view.getUint32(offset, true);
+    };
+    const sectorShift = view.getUint16(30, true);
+    if (sectorShift !== 9 && sectorShift !== 12) {
+        throw new VbaParseError('unsupported', `OLE container: unsupported sector size (2^${sectorShift})`);
+    }
+    const miniSectorShift = view.getUint16(32, true);
+    if (miniSectorShift !== 6) {
+        throw new VbaParseError('unsupported', `OLE container: unsupported mini sector size (2^${miniSectorShift})`);
+    }
+    const sectorSize = 1 << sectorShift;
+    const miniSectorSize = 1 << miniSectorShift;
+    const fatSectorCount = u32(44);
+    const firstDirectorySector = u32(48);
+    const miniStreamCutoff = u32(56);
+    const firstMiniFatSector = u32(60);
+    const miniFatSectorCount = u32(64);
+    const firstDifatSector = u32(68);
+    const difatSectorCount = u32(72);
+    const entriesPerSector = sectorSize / 4;
+    /** Byte offset of a sector. The header occupies the space of sector -1. */
+    const sectorOffset = (sector) => {
+        const offset = (sector + 1) * sectorSize;
+        if (sector < 0 || offset + sectorSize > bytes.length) {
+            throw new VbaParseError('malformed', `OLE container: sector ${sector} lies outside the file`);
+        }
+        return offset;
+    };
+    /* ---------- allocation tables ---------- */
+    // How many sectors the file could possibly hold. Declared counts are just
+    // claims — a crafted header can say the allocation table spans four billion
+    // sectors — so every table is also bounded by what the file physically has
+    // room for. Without this, an attacker sizes our memory use, not us.
+    const sectorsInFile = Math.max(1, Math.ceil(bytes.length / sectorSize));
+    // The allocation table can never usefully describe more sectors than the
+    // file holds, whatever its header claims. Deriving the ceiling first lets
+    // the DIFAT walk below stop collecting as soon as it has enough, instead of
+    // gathering millions of sector numbers it will then discard.
+    const fatLimit = Math.min(Math.max(fatSectorCount, 1) * entriesPerSector, 
+    // One full table sector of slack past the last real sector, so a valid
+    // file is never trimmed while a lying one cannot inflate the table.
+    sectorsInFile + entriesPerSector);
+    const fatSectorLimit = Math.ceil(fatLimit / entriesPerSector) + 1;
+    // The DIFAT is the index *of* the allocation table: the first 109 entries
+    // live in the header, the rest in a chain of their own sectors.
+    const fatSectors = [];
+    for (let i = 0; i < HEADER_DIFAT_ENTRIES && fatSectors.length < fatSectorLimit; i += 1) {
+        fatSectors.push(u32(HEADER_DIFAT_OFFSET + i * 4));
+    }
+    let difatSector = firstDifatSector;
+    const seenDifat = new Set();
+    while (difatSector <= MAX_REGULAR_SECTOR &&
+        fatSectors.length < fatSectorLimit &&
+        seenDifat.size <= Math.min(difatSectorCount, sectorsInFile) + 1) {
+        if (seenDifat.has(difatSector)) {
+            throw new VbaParseError('malformed', 'OLE container: DIFAT chain loops');
+        }
+        seenDifat.add(difatSector);
+        const base = sectorOffset(difatSector);
+        for (let i = 0; i < entriesPerSector - 1 && fatSectors.length < fatSectorLimit; i += 1) {
+            fatSectors.push(u32(base + i * 4));
+        }
+        difatSector = u32(base + (entriesPerSector - 1) * 4);
+    }
+    const fat = [];
+    for (const sector of fatSectors) {
+        if (sector > MAX_REGULAR_SECTOR)
+            continue;
+        if (fat.length >= fatLimit)
+            break;
+        const base = sectorOffset(sector);
+        for (let i = 0; i < entriesPerSector; i += 1)
+            fat.push(u32(base + i * 4));
+    }
+    if (fat.length === 0) {
+        throw new VbaParseError('malformed', 'OLE container: empty allocation table');
+    }
+    /** The sector ids of one chain, in order. */
+    const chain = (start) => {
+        const sectors = [];
+        const seen = new Set();
+        let sector = start;
+        while (sector <= MAX_REGULAR_SECTOR) {
+            if (seen.has(sector)) {
+                throw new VbaParseError('malformed', 'OLE container: sector chain loops');
+            }
+            if (sectors.length >= CFB_LIMITS.maxChainSectors) {
+                throw new VbaParseError('too-large', 'OLE container: sector chain exceeds the length cap');
+            }
+            seen.add(sector);
+            sectors.push(sector);
+            const next = fat[sector];
+            if (next === undefined) {
+                // A chain running off the end of the table is a truncated file. The
+                // sectors gathered so far are still real, so stop rather than fail:
+                // callers slice to the declared size and will notice a short read.
+                break;
+            }
+            sector = next;
+        }
+        return sectors;
+    };
+    const readChain = (start, byteCount) => {
+        if (byteCount > CFB_LIMITS.maxStreamBytes) {
+            throw new VbaParseError('too-large', 'OLE container: stream exceeds the size cap');
+        }
+        if (byteCount === 0)
+            return new Uint8Array(0);
+        // The chain is walked and measured *before* the buffer exists. A declared
+        // size the chain cannot supply is the signature of a truncated file, and
+        // allocating tens of megabytes only to discover that is work an attacker
+        // gets to request for free.
+        const sectors = chain(start);
+        if (sectors.length * sectorSize < byteCount) {
+            throw new VbaParseError('malformed', 'OLE container: stream is shorter than its declared size');
+        }
+        const out = new Uint8Array(byteCount);
+        let written = 0;
+        for (const sector of sectors) {
+            if (written >= byteCount)
+                break;
+            const base = sectorOffset(sector);
+            const take = Math.min(sectorSize, byteCount - written);
+            out.set(bytes.subarray(base, base + take), written);
+            written += take;
+        }
+        return out;
+    };
+    /* ---------- directory ---------- */
+    const directorySectors = chain(firstDirectorySector);
+    const entriesPerDirectorySector = sectorSize / DIRECTORY_ENTRY_BYTES;
+    const raw = [];
+    for (const sector of directorySectors) {
+        const base = sectorOffset(sector);
+        for (let i = 0; i < entriesPerDirectorySector; i += 1) {
+            if (raw.length >= CFB_LIMITS.maxEntries) {
+                throw new VbaParseError('too-large', 'OLE container: too many directory entries');
+            }
+            const at = base + i * DIRECTORY_ENTRY_BYTES;
+            const nameByteLength = view.getUint16(at + 64, true);
+            const objectType = view.getUint8(at + 66);
+            // Names are UTF-16LE with a null terminator counted in the length.
+            const usable = Math.max(0, Math.min(nameByteLength, 64) - 2);
+            let name = '';
+            for (let c = 0; c + 1 < usable; c += 2) {
+                name += String.fromCharCode(view.getUint16(at + c, true));
+            }
+            const low = u32(at + 120);
+            const high = u32(at + 124);
+            // MS-CFB names this case explicitly: older writers left the high half
+            // of a v3 stream size uninitialized, and it "is recommended that
+            // parsers ignore the most significant 32 bits of this field in version
+            // 3 compound files". Honouring the garbage instead turns an otherwise
+            // valid file into an oversized stream and loses the whole project — so
+            // v3 uses the low word, full stop, and only v4 reads both halves.
+            const size = sectorShift === 9 ? low : low + high * 0x1_0000_0000;
+            raw.push({
+                name,
+                type: objectType === 5 ? 'root' : objectType === 1 ? 'storage' : objectType === 2 ? 'stream' : 'unallocated',
+                left: u32(at + 68),
+                right: u32(at + 72),
+                child: u32(at + 76),
+                startSector: u32(at + 116),
+                size,
+            });
+        }
+    }
+    const root = raw[0];
+    if (!root || root.type !== 'root') {
+        throw new VbaParseError('malformed', 'OLE container: missing root directory entry');
+    }
+    // The directory is a red-black tree: `child` descends into a storage,
+    // `left`/`right` are siblings at the same level. Walked with an explicit
+    // stack — a degenerate tree would blow a recursive walk's call stack.
+    const entries = [];
+    const byPath = new Map();
+    const visited = new Set();
+    const pending = [
+        { id: root.child, prefix: '', depth: 1 },
+    ];
+    while (pending.length > 0) {
+        const next = pending.pop();
+        if (!next)
+            break;
+        const { id, prefix, depth } = next;
+        if (id > MAX_REGULAR_SECTOR || visited.has(id))
+            continue;
+        visited.add(id);
+        const entry = raw[id];
+        if (!entry || entry.type === 'unallocated')
+            continue;
+        // Depth and path length are capped together. Entry *count* alone does
+        // not bound the size of the path strings this loop retains: storages
+        // nested one inside the next make each path longer than the last, so the
+        // total is quadratic in the entry count. See `CFB_LIMITS.maxDepth`.
+        if (depth > CFB_LIMITS.maxDepth) {
+            throw new VbaParseError('too-large', 'OLE container: directory nests deeper than the cap');
+        }
+        const path = `${prefix}/${entry.name}`;
+        if (path.length > CFB_LIMITS.maxPathLength) {
+            throw new VbaParseError('too-large', 'OLE container: directory path exceeds the length cap');
+        }
+        if (entry.type === 'storage' || entry.type === 'stream') {
+            entries.push({ path, name: entry.name, type: entry.type, size: entry.type === 'stream' ? entry.size : 0 });
+            // First writer wins: a file with duplicate paths cannot make a later
+            // entry shadow the one already reported.
+            if (!byPath.has(path))
+                byPath.set(path, entry);
+        }
+        if (entry.type === 'storage')
+            pending.push({ id: entry.child, prefix: path, depth: depth + 1 });
+        pending.push({ id: entry.left, prefix, depth });
+        pending.push({ id: entry.right, prefix, depth });
+    }
+    /* ---------- streams ---------- */
+    /**
+     * The mini stream and its allocation table, built once.
+     *
+     * The outcome is cached either way — a *failure* included. Rebuilding it per
+     * call would re-run a multi-megabyte zero-filled allocation for every
+     * stream in a container whose root entry is malformed, turning one bad
+     * header into thousands of repeats of the same doomed work.
+     */
+    let mini = null;
+    const miniContext = () => {
+        if (mini === null) {
+            try {
+                const stream = readChain(root.startSector, Math.min(root.size, CFB_LIMITS.maxStreamBytes));
+                const table = [];
+                // The mini table indexes 64-byte mini sectors inside the mini stream,
+                // *not* full sectors of the file. Bounding it by the file's sector
+                // count — the ceiling that is right for the FAT — is off by the ratio
+                // between the two, and silently truncates the table: on a small
+                // container that caps it at 256 entries, so a project with more than
+                // ~16 KB of small streams loses modules. Almost everything in a real
+                // vbaProject.bin is a mini stream, so this bound has to be the right
+                // dimension.
+                const limit = Math.min(Math.max(miniFatSectorCount, 1) * entriesPerSector, Math.ceil(stream.length / miniSectorSize) + entriesPerSector);
+                for (const sector of chain(firstMiniFatSector)) {
+                    if (table.length >= limit)
+                        break;
+                    const base = sectorOffset(sector);
+                    for (let i = 0; i < entriesPerSector; i += 1)
+                        table.push(u32(base + i * 4));
+                }
+                mini = { ok: true, stream, table };
+            }
+            catch (error) {
+                mini = {
+                    ok: false,
+                    error: error instanceof VbaParseError
+                        ? error
+                        : new VbaParseError('malformed', 'OLE container: unreadable mini stream'),
+                };
+            }
+        }
+        if (!mini.ok)
+            throw mini.error;
+        return { stream: mini.stream, table: mini.table };
+    };
+    const readMini = (start, byteCount) => {
+        const { stream: container, table } = miniContext();
+        const out = new Uint8Array(byteCount);
+        let written = 0;
+        let sector = start;
+        const seen = new Set();
+        while (sector <= MAX_REGULAR_SECTOR && written < byteCount) {
+            if (seen.has(sector)) {
+                throw new VbaParseError('malformed', 'OLE container: mini sector chain loops');
+            }
+            seen.add(sector);
+            const base = sector * miniSectorSize;
+            if (base + miniSectorSize > container.length) {
+                throw new VbaParseError('malformed', 'OLE container: mini sector lies outside the mini stream');
+            }
+            const take = Math.min(miniSectorSize, byteCount - written);
+            out.set(container.subarray(base, base + take), written);
+            written += take;
+            const next = table[sector];
+            if (next === undefined)
+                break;
+            sector = next;
+        }
+        if (written < byteCount) {
+            throw new VbaParseError('malformed', 'OLE container: mini stream is shorter than its declared size');
+        }
+        return out;
+    };
+    return {
+        entries,
+        readStream(path) {
+            const entry = byPath.get(path);
+            if (!entry) {
+                throw new VbaParseError('malformed', `OLE container: no such stream (${path})`);
+            }
+            if (entry.type !== 'stream') {
+                throw new VbaParseError('malformed', `OLE container: ${path} is a storage, not a stream`);
+            }
+            if (entry.size > CFB_LIMITS.maxStreamBytes) {
+                throw new VbaParseError('too-large', `OLE container: ${path} exceeds the stream size cap`);
+            }
+            if (entry.size === 0)
+                return new Uint8Array(0);
+            return entry.size < miniStreamCutoff
+                ? readMini(entry.startSector, entry.size)
+                : readChain(entry.startSector, entry.size);
+        },
+    };
+}

package/dist/import/errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The one error type the binary readers raise.
+ *
+ * The readers parse files that arrive from users — a `.docm` someone was
+ * emailed. Every structural surprise must land as a typed, catchable failure
+ * rather than a `RangeError` from a stray offset, so the public extraction
+ * API can convert it into a message and never throw at its caller.
+ */
+export type VbaParseErrorCode = 
+/** The bytes do not match the format, or a structure points outside the file. */
+'malformed'
+/** Structurally valid but beyond a safety cap — see the `*_LIMITS` objects. */
+ | 'too-large'
+/** A format feature this reader deliberately does not implement. */
+ | 'unsupported';
+export declare class VbaParseError extends Error {
+    readonly code: VbaParseErrorCode;
+    constructor(code: VbaParseErrorCode, message: string);
+}
+/** Whether an unknown thrown value is one of ours. */
+export declare function isVbaParseError(error: unknown): error is VbaParseError;

package/dist/import/errors.js

@@ -0,0 +1,20 @@
+/**
+ * The one error type the binary readers raise.
+ *
+ * The readers parse files that arrive from users — a `.docm` someone was
+ * emailed. Every structural surprise must land as a typed, catchable failure
+ * rather than a `RangeError` from a stray offset, so the public extraction
+ * API can convert it into a message and never throw at its caller.
+ */
+export class VbaParseError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'VbaParseError';
+        this.code = code;
+    }
+}
+/** Whether an unknown thrown value is one of ours. */
+export function isVbaParseError(error) {
+    return error instanceof VbaParseError;
+}

package/dist/import/ms-ovba.d.ts

@@ -0,0 +1,20 @@
+export declare const OVBA_LIMITS: {
+    /**
+     * Cap on the decompressed size of a single stream. Real VBA modules are
+     * kilobytes; megabytes already means something is wrong.
+     */
+    readonly maxDecompressedBytes: 20000000;
+};
+export interface DecompressOvbaOptions {
+    /** Where the CompressedContainer starts. Module streams prefix it with a header. */
+    offset?: number;
+    /** Output cap in bytes. Default: `OVBA_LIMITS.maxDecompressedBytes`. */
+    maxOutput?: number;
+}
+/**
+ * Decompresses one CompressedContainer.
+ *
+ * @throws {VbaParseError} on a malformed container or one whose output would
+ * exceed the cap. Never throws anything else.
+ */
+export declare function decompressOvba(source: Uint8Array, options?: DecompressOvbaOptions): Uint8Array;