@markii/bundle 0.1.0

package/dist/paths.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The bundle path-jail (spec §11): pure functions, zero dependencies (not
+ * even on Node builtins), so they're trivially unit-testable and reusable
+ * from both the browser-safe zip storage and the Node-only directory
+ * storage without either pulling in the other's runtime.
+ *
+ * IMPORTANT: percent-decoding is deliberately NOT applied anywhere in this
+ * module. A path segment like `..%2F` is treated as a literal filename
+ * (the three characters `.`, `.`, `%2F`... i.e. the six characters
+ * `..%2F`), never decoded into `../`. Bundle paths are opaque strings, not
+ * URLs — decoding them would let a percent-encoded traversal sequence slip
+ * past the `..`-segment check below, which is exactly the class of bug this
+ * module exists to prevent.
+ */
+/** The two write grants a manifest may declare under `permissions.bundle`. */
+export type BundleFsGrant = 'read' | 'write:cache/';
+export type NormalizePathResult = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Normalizes a bundle-relative path and rejects anything that could escape
+ * the bundle root or address the filesystem outside it. This is the single
+ * choke point every `BundleStorage` implementation must route through
+ * before touching disk or an in-memory archive.
+ *
+ * Accepts: relative paths using `/` separators, with `.` segments and
+ * repeated `/` collapsed, and a leading `./` stripped.
+ *
+ * Rejects: empty paths, null bytes, any backslash (so a literal `\` is
+ * never mistaken for a path separator on a platform that treats it as one),
+ * absolute paths (leading `/`), Windows drive-letter paths (`C:...`), and
+ * any `..` segment, wherever it appears (start, middle, or end).
+ */
+export declare function normalizeBundlePath(path: string): NormalizePathResult;
+/** The write-access policy an untrusted script is evaluated against. */
+export interface BundleWritePolicy {
+    /** The `permissions.bundle` grants declared in the note's manifest. */
+    grants: readonly BundleFsGrant[];
+}
+/**
+ * Implements the write half of spec §11's bundle-scoped filesystem.
+ *
+ * `note.mk.md` and `manifest.json` are denied unconditionally, regardless of
+ * `policy` — this is load-bearing, not a default: a script that could edit
+ * the manifest could grant itself further permissions, and a script that
+ * could edit `note.mk.md` would make the document self-modifying, which §8
+ * explicitly rules out. Every other path requires the `write:cache/` grant
+ * and must normalize to a path under `cache/`.
+ */
+export declare function isWriteAllowed(path: string, policy: BundleWritePolicy): boolean;

package/dist/paths.js

@@ -0,0 +1,84 @@
+/**
+ * The bundle path-jail (spec §11): pure functions, zero dependencies (not
+ * even on Node builtins), so they're trivially unit-testable and reusable
+ * from both the browser-safe zip storage and the Node-only directory
+ * storage without either pulling in the other's runtime.
+ *
+ * IMPORTANT: percent-decoding is deliberately NOT applied anywhere in this
+ * module. A path segment like `..%2F` is treated as a literal filename
+ * (the three characters `.`, `.`, `%2F`... i.e. the six characters
+ * `..%2F`), never decoded into `../`. Bundle paths are opaque strings, not
+ * URLs — decoding them would let a percent-encoded traversal sequence slip
+ * past the `..`-segment check below, which is exactly the class of bug this
+ * module exists to prevent.
+ */
+/** Matches a leading Windows drive letter, e.g. `C:` at the start of a path. */
+const DRIVE_LETTER_RE = /^[A-Za-z]:/;
+/**
+ * Normalizes a bundle-relative path and rejects anything that could escape
+ * the bundle root or address the filesystem outside it. This is the single
+ * choke point every `BundleStorage` implementation must route through
+ * before touching disk or an in-memory archive.
+ *
+ * Accepts: relative paths using `/` separators, with `.` segments and
+ * repeated `/` collapsed, and a leading `./` stripped.
+ *
+ * Rejects: empty paths, null bytes, any backslash (so a literal `\` is
+ * never mistaken for a path separator on a platform that treats it as one),
+ * absolute paths (leading `/`), Windows drive-letter paths (`C:...`), and
+ * any `..` segment, wherever it appears (start, middle, or end).
+ */
+export function normalizeBundlePath(path) {
+    if (path.length === 0) {
+        return { ok: false, reason: 'path is empty' };
+    }
+    if (path.includes('\0')) {
+        return { ok: false, reason: 'path contains a null byte' };
+    }
+    if (path.includes('\\')) {
+        return { ok: false, reason: 'backslashes are not allowed in bundle paths' };
+    }
+    if (path.startsWith('/')) {
+        return { ok: false, reason: 'absolute paths are not allowed' };
+    }
+    if (DRIVE_LETTER_RE.test(path)) {
+        return { ok: false, reason: 'drive-letter paths are not allowed' };
+    }
+    const segments = [];
+    for (const segment of path.split('/')) {
+        // Empty segments (repeated `/` or a trailing `/`) and `.` segments
+        // collapse away silently — they carry no traversal meaning.
+        if (segment === '' || segment === '.')
+            continue;
+        if (segment === '..') {
+            return { ok: false, reason: '".." path segments are not allowed' };
+        }
+        segments.push(segment);
+    }
+    if (segments.length === 0) {
+        return { ok: false, reason: 'path has no meaningful segments' };
+    }
+    return { ok: true, path: segments.join('/') };
+}
+/**
+ * Implements the write half of spec §11's bundle-scoped filesystem.
+ *
+ * `note.mk.md` and `manifest.json` are denied unconditionally, regardless of
+ * `policy` — this is load-bearing, not a default: a script that could edit
+ * the manifest could grant itself further permissions, and a script that
+ * could edit `note.mk.md` would make the document self-modifying, which §8
+ * explicitly rules out. Every other path requires the `write:cache/` grant
+ * and must normalize to a path under `cache/`.
+ */
+export function isWriteAllowed(path, policy) {
+    const normalized = normalizeBundlePath(path);
+    if (!normalized.ok)
+        return false;
+    const { path: p } = normalized;
+    // Unconditional denial: no policy input can override this.
+    if (p === 'note.mk.md' || p === 'manifest.json')
+        return false;
+    if (!policy.grants.includes('write:cache/'))
+        return false;
+    return p.startsWith('cache/') && p.length > 'cache/'.length;
+}

package/dist/script-view.d.ts

@@ -0,0 +1,57 @@
+import type { BundleManifest, BundlePermissions } from './manifest.js';
+import type { BundleStorage } from './storage.js';
+/**
+ * The capability-restricted view of a bundle a future Lua runtime (§8, §10,
+ * §11) will actually receive — never the raw `BundleStorage`. Deliberately
+ * exposes only `read` / `write` / `exists`, no `list`: directory
+ * enumeration stays host-side. An untrusted script that can already read
+ * `assets/photo.png` by name doesn't need the ability to *discover* every
+ * other file in the bundle; keeping `list` off the script-facing surface
+ * minimizes what a script can learn about a bundle it wasn't specifically
+ * pointed at (e.g. other cached datasets, other scripts' outputs).
+ */
+export interface ScriptView {
+    read(path: string): Promise<Uint8Array | undefined>;
+    write(path: string, data: Uint8Array): Promise<void>;
+    exists(path: string): Promise<boolean>;
+}
+/**
+ * The fully-trusted convenience case: grants a `ScriptView` exactly what
+ * `manifest.permissions` *declares*, nothing more. This is a legitimate
+ * pattern for a note the user has already explicitly decided to fully
+ * trust (their own note, a dev/test harness) — but it must always be an
+ * explicit, named opt-in at the call site, never `createScriptView`'s
+ * default. See the DEFECT-10 note on `createScriptView` for why: an
+ * untrusted `.mkbundle` opened from elsewhere must never be able to grant
+ * itself capabilities merely by declaring them in its own manifest.
+ */
+export declare function grantAllDeclaredPermissions(manifest: BundleManifest): BundlePermissions;
+/**
+ * Builds a `ScriptView` over `storage`.
+ *
+ * DEFECT 10 / spec §10: "Capabilities are declared in the manifest, granted
+ * by the user" — declaring is not granting. `manifest.permissions` is
+ * whatever the (possibly untrusted) `.mkbundle` *asks for*; `grantedPermissions`
+ * is whatever the user has actually *approved* for this note (e.g. via a
+ * permission-prompt UI, remembered per note and re-prompted if scripts
+ * change — see §10). The capability this view actually exposes is the
+ * INTERSECTION of the two: the manifest can only ever narrow what the user
+ * granted, never expand it, and the user's grant can only ever narrow what
+ * the manifest declared wanting. Neither side alone is authoritative.
+ *
+ * `grantedPermissions` defaults to `{}` (zero grants) — deliberately not to
+ * "everything the manifest asks for". An untrusted note opened from
+ * elsewhere must start with zero grants and still render fully (§10); a
+ * caller that wants the old fully-trusted behavior must opt in explicitly,
+ * e.g. `createScriptView(storage, manifest, grantAllDeclaredPermissions(manifest))`.
+ *
+ * - No effective bundle grants at all: every call throws `ScriptCapabilityError`.
+ * - `'read'` in the intersection: `read`/`exists` work bundle-wide; `write` still fails.
+ * - `'write:cache/'` in the intersection: `write` works, but only for paths
+ *   `isWriteAllowed` accepts — `cache/` only. Critically, this holds even
+ *   if both the manifest and the granted set include `'write:cache/'` and
+ *   the script asks for `manifest.json` or `note.mk.md`: `isWriteAllowed`
+ *   denies those two paths unconditionally, regardless of what's granted
+ *   or declared (see `./paths`).
+ */
+export declare function createScriptView(storage: BundleStorage, manifest: BundleManifest, grantedPermissions?: BundlePermissions): ScriptView;

package/dist/script-view.js

@@ -0,0 +1,71 @@
+import { ScriptCapabilityError } from './errors.js';
+import { isWriteAllowed } from './paths.js';
+/**
+ * The fully-trusted convenience case: grants a `ScriptView` exactly what
+ * `manifest.permissions` *declares*, nothing more. This is a legitimate
+ * pattern for a note the user has already explicitly decided to fully
+ * trust (their own note, a dev/test harness) — but it must always be an
+ * explicit, named opt-in at the call site, never `createScriptView`'s
+ * default. See the DEFECT-10 note on `createScriptView` for why: an
+ * untrusted `.mkbundle` opened from elsewhere must never be able to grant
+ * itself capabilities merely by declaring them in its own manifest.
+ */
+export function grantAllDeclaredPermissions(manifest) {
+    return manifest.permissions ?? {};
+}
+/**
+ * Builds a `ScriptView` over `storage`.
+ *
+ * DEFECT 10 / spec §10: "Capabilities are declared in the manifest, granted
+ * by the user" — declaring is not granting. `manifest.permissions` is
+ * whatever the (possibly untrusted) `.mkbundle` *asks for*; `grantedPermissions`
+ * is whatever the user has actually *approved* for this note (e.g. via a
+ * permission-prompt UI, remembered per note and re-prompted if scripts
+ * change — see §10). The capability this view actually exposes is the
+ * INTERSECTION of the two: the manifest can only ever narrow what the user
+ * granted, never expand it, and the user's grant can only ever narrow what
+ * the manifest declared wanting. Neither side alone is authoritative.
+ *
+ * `grantedPermissions` defaults to `{}` (zero grants) — deliberately not to
+ * "everything the manifest asks for". An untrusted note opened from
+ * elsewhere must start with zero grants and still render fully (§10); a
+ * caller that wants the old fully-trusted behavior must opt in explicitly,
+ * e.g. `createScriptView(storage, manifest, grantAllDeclaredPermissions(manifest))`.
+ *
+ * - No effective bundle grants at all: every call throws `ScriptCapabilityError`.
+ * - `'read'` in the intersection: `read`/`exists` work bundle-wide; `write` still fails.
+ * - `'write:cache/'` in the intersection: `write` works, but only for paths
+ *   `isWriteAllowed` accepts — `cache/` only. Critically, this holds even
+ *   if both the manifest and the granted set include `'write:cache/'` and
+ *   the script asks for `manifest.json` or `note.mk.md`: `isWriteAllowed`
+ *   denies those two paths unconditionally, regardless of what's granted
+ *   or declared (see `./paths`).
+ */
+export function createScriptView(storage, manifest, grantedPermissions = {}) {
+    const declared = new Set(manifest.permissions?.bundle ?? []);
+    const granted = grantedPermissions.bundle ?? [];
+    // Effective capability = declared ∩ granted. See the doc comment above —
+    // this is the load-bearing line for DEFECT 10.
+    const grants = granted.filter((grant) => declared.has(grant));
+    const canRead = grants.includes('read');
+    return {
+        async read(path) {
+            if (!canRead) {
+                throw new ScriptCapabilityError(`script has no "read" bundle permission (requested "${path}")`);
+            }
+            return storage.read(path);
+        },
+        async write(path, data) {
+            if (!isWriteAllowed(path, { grants })) {
+                throw new ScriptCapabilityError(`script may not write "${path}"`);
+            }
+            await storage.write(path, data);
+        },
+        async exists(path) {
+            if (!canRead) {
+                throw new ScriptCapabilityError(`script has no "read" bundle permission (requested "${path}")`);
+            }
+            return storage.exists(path);
+        },
+    };
+}

package/dist/storage.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Common shape both bundle forms (zip, directory) implement. Every method
+ * takes/returns bundle-relative paths and routes through
+ * `normalizeBundlePath` before touching storage — see `normalizeOrThrow`.
+ *
+ * IMPORTANT for implementers: every method MUST route its `path` argument
+ * through `normalizeOrThrow` (or an equivalent check) before touching disk
+ * or an in-memory archive. `ScriptView` (`./script-view`) delegates *all*
+ * path validation to whatever `BundleStorage` it's given — it does not
+ * re-normalize paths itself. A storage implementation that skips this
+ * choke point unjails every `ScriptView` built on top of it, no matter how
+ * carefully `isWriteAllowed`/`normalizeBundlePath` are enforced elsewhere.
+ * The directory form (`./fs`) additionally must not follow symlinks or
+ * hard links when resolving a path to a physical file — see
+ * `resolveInsideRoot` and `writeExistingFileNoHardlink` there for why a
+ * *logical* path-jail alone is not sufficient once real files are involved.
+ */
+export interface BundleStorage {
+    /** Returns the file's bytes, or `undefined` if no such path exists. */
+    read(path: string): Promise<Uint8Array | undefined>;
+    write(path: string, data: Uint8Array): Promise<void>;
+    /** All file paths currently in the bundle, bundle-relative, sorted. */
+    list(): Promise<string[]>;
+    exists(path: string): Promise<boolean>;
+}
+/**
+ * The shared choke point every `BundleStorage` implementation calls before
+ * touching an archive or the filesystem: normalizes `path` or throws a
+ * `BundlePathError` describing why it was rejected.
+ */
+export declare function normalizeOrThrow(path: string): string;

package/dist/storage.js

@@ -0,0 +1,14 @@
+import { BundlePathError } from './errors.js';
+import { normalizeBundlePath } from './paths.js';
+/**
+ * The shared choke point every `BundleStorage` implementation calls before
+ * touching an archive or the filesystem: normalizes `path` or throws a
+ * `BundlePathError` describing why it was rejected.
+ */
+export function normalizeOrThrow(path) {
+    const result = normalizeBundlePath(path);
+    if (!result.ok) {
+        throw new BundlePathError(path, result.reason);
+    }
+    return result.path;
+}

package/dist/zip.d.ts

@@ -0,0 +1,80 @@
+import type { BundleStorage } from './storage.js';
+/** Options for `openZipBundle`'s decompression-bomb guard (DEFECT 4). */
+export interface OpenZipBundleOptions {
+    /**
+     * Reject an entry whose *declared* (header) uncompressed size exceeds
+     * this many bytes, before ever allocating a decompression buffer for it.
+     * Defaults to `DEFAULT_MAX_ZIP_ENTRY_BYTES`.
+     */
+    maxEntryBytes?: number;
+    /**
+     * Reject the archive once the running sum of every processed entry's
+     * declared uncompressed size exceeds this many bytes. Defaults to
+     * `DEFAULT_MAX_ZIP_TOTAL_BYTES`.
+     */
+    maxTotalBytes?: number;
+}
+/** Default per-entry decompressed-size cap: 256MB. */
+export declare const DEFAULT_MAX_ZIP_ENTRY_BYTES: number;
+/** Default total (summed across all entries) decompressed-size cap: 256MB. */
+export declare const DEFAULT_MAX_ZIP_TOTAL_BYTES: number;
+/**
+ * Opens the zip form of a bundle (browser-safe: `fflate` has no Node
+ * dependency; the ZIP container parsing here is our own and is also
+ * dependency-free). Directory entries (names ending in `/`) carry no data
+ * and are skipped — but only *after* the name has passed
+ * `normalizeBundlePath` (DEFECT 8: validating before the directory-entry
+ * skip means a malformed directory entry like `../evil/` is rejected loudly,
+ * the same as its non-directory counterpart `../evil`, instead of being
+ * silently dropped).
+ *
+ * Zip-slip protection: every file entry's name is run through
+ * `normalizeBundlePath`. Any entry that fails (`../`, an absolute path, a
+ * backslash path, a drive-letter path) is collected and, if any exist,
+ * the whole open is rejected with a `BundleZipError` listing every
+ * offending name — a tampered bundle must be loud, not silently pruned
+ * down to "the entries that happened to be safe."
+ *
+ * Collision protection (DEFECT 5): two distinct raw entry names that
+ * *normalize* to the same bundle path (e.g. `manifest.json` and
+ * `./manifest.json`, or `cache/x` and `cache//x`) are rejected outright
+ * rather than silently last-wins — a bundle could otherwise show a benign
+ * file to one reader and a hostile one to another depending on which
+ * implementation's normalization/iteration order "wins".
+ *
+ * Decompression-bomb protection (DEFECT 4): every entry's declared
+ * uncompressed size (read from the central directory, before any inflation
+ * happens) is checked against `options.maxEntryBytes`, and the running
+ * total across all entries against `options.maxTotalBytes`. A crafted
+ * high-ratio archive is rejected before its claimed size is ever allocated.
+ *
+ * CRC-32 verification (DEFECT 6): every entry's decompressed bytes are
+ * checked against the CRC-32 recorded in the central directory; a mismatch
+ * (corrupt archive, flipped bit) throws `BundleZipError` instead of
+ * silently returning wrong data.
+ */
+export declare function openZipBundle(bytes: Uint8Array, options?: OpenZipBundleOptions): BundleStorage;
+/**
+ * Serializes a `BundleStorage` to zip bytes. Zip metadata (unix
+ * permission/symlink bits) is never written — `fflate`'s `zipSync` writes
+ * plain file entries, so re-extracting a bundle produced here can never
+ * materialize a symlink.
+ *
+ * The accumulator is an `Object.create(null)` dict (DEFECT 7), not a plain
+ * `{}` — `fflate`'s `zipSync` flattens its input with a bracket-assignment
+ * loop (`t[key] = ...`) that inherits the same `__proto__` special-case
+ * problem when `key` is nested under a directory prefix; giving it a
+ * null-prototype object here means a bundle path like `cache/__proto__`
+ * (a *nested* `__proto__`, i.e. everything except a bare top-level path)
+ * round-trips correctly instead of silently corrupting our own dict.
+ *
+ * A bundle path that is *exactly* `__proto__` (or `constructor` /
+ * `prototype`) at the top level — no directory prefix — cannot be
+ * represented at all: this is a hard limitation inside `fflate` 0.8.3
+ * itself (its internal flattening step, `fltn`, does `t[name] = [...]` on
+ * its *own* plain `{}` accumulator, which we cannot reach or fix), verified
+ * empirically to throw a raw `TypeError` from deep inside `zipSync` rather
+ * than silently corrupting. We turn that into a clear, typed
+ * `BundleZipError` instead of letting the raw `TypeError` escape.
+ */
+export declare function exportZipBundle(storage: BundleStorage): Promise<Uint8Array>;