@markii/bundle 0.12.0 → 0.13.0

package/dist/fs.js

@@ -15,8 +15,8 @@ function isEnoent(err) {
 }
 /**
  * `ENOTDIR` shows up when an *earlier* path component turns out to be a
- * plain file instead of a directory (e.g. writing `cache/data.json/sub`
- * when `cache/data.json` already exists as a file) — treated the same as
+ * plain file instead of a directory (e.g. writing `.cache/data.json/sub`
+ * when `.cache/data.json` already exists as a file) — treated the same as
  * "doesn't exist yet" by the lstat walk below, deferring the actual clear
  * error to the subsequent `mkdir`/`writeFile`/`open` call.
  */
@@ -31,7 +31,7 @@ function isEnoentLike(err) {
  * in `./paths` only reasons about the *logical* path string, but the actual
  * filesystem write/read *follows symlinks*, so a symlink planted anywhere
  * inside the bundle (even one that resolves to somewhere still nominally
- * "inside the bundle root", like `cache/pwn -> ../manifest.json`) can
+ * "inside the bundle root", like `.cache/pwn -> ../manifest.json`) can
  * silently retarget an otherwise-innocuous-looking write.
  *
  * Two layers, in order:
@@ -41,10 +41,10 @@ function isEnoentLike(err) {
  *    `stat`, which would itself follow a symlink). The moment any
  *    *existing* component is a symlink — file or directory, leaf or
  *    ancestor, whether or not it resolves inside or outside the root — the
- *    whole operation is rejected. This alone defeats ESCAPE 1 (`cache/pwn`
+ *    whole operation is rejected. This alone defeats ESCAPE 1 (`.cache/pwn`
  *    symlinked to `../manifest.json`) and its directory variant
- *    (`cache/up` symlinked to `..`, then `cache/up/manifest.json` or even
- *    `cache/up/not-yet-created.txt`): the symlinked component is caught
+ *    (`.cache/up` symlinked to `..`, then `.cache/up/manifest.json` or even
+ *    `.cache/up/not-yet-created.txt`): the symlinked component is caught
  *    before we ever ask whether its target exists.
  * 2. **Defense in depth — resolved-path re-check.** Once the walk finds
  *    the nearest existing ancestor (the leaf itself may not exist yet,
@@ -116,7 +116,7 @@ async function resolveInsideRoot(rootAbs, relPath) {
  * Writes `data` to an already symlink-checked `target` that is known to
  * exist, refusing to write through a hard link (ESCAPE 3: `st_nlink > 1`
  * means some other path — possibly outside the bundle entirely, e.g.
- * `ln b.mkz/../victim.txt b.mkz/cache/hard` — refers to the exact same
+ * `ln b.mkz/../victim.txt b.mkz/.cache/hard` — refers to the exact same
  * inode, so writing here would also silently modify that other path).
  *
  * Opens the file first *without* truncating (`'r+'`), `fstat`s the open

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { CURRENT_SPEC_VERSION, createDefaultManifest, parseManifest, } from './m
 export type { BundleFsGrant, BundleWritePolicy, NormalizePathResult, } from './paths.js';
 export { isWriteAllowed, normalizeBundlePath } from './paths.js';
 export type { BundleStorage } from './storage.js';
-export { normalizeOrThrow } from './storage.js';
+export { createMemoryBundleStorage, normalizeOrThrow } from './storage.js';
 export { BundlePathError, BundleZipError, ScriptCapabilityError, } from './errors.js';
 export type { OpenZipBundleOptions } from './zip.js';
 export { DEFAULT_MAX_ZIP_ENTRY_BYTES, DEFAULT_MAX_ZIP_TOTAL_BYTES, exportZipBundle, openZipBundle, } from './zip.js';

package/dist/index.js

@@ -6,7 +6,7 @@
 // entry never has to reason about Node builtins reachable from it.
 export { CURRENT_SPEC_VERSION, createDefaultManifest, parseManifest, } from './manifest.js';
 export { isWriteAllowed, normalizeBundlePath } from './paths.js';
-export { normalizeOrThrow } from './storage.js';
+export { createMemoryBundleStorage, normalizeOrThrow } from './storage.js';
 export { BundlePathError, BundleZipError, ScriptCapabilityError, } from './errors.js';
 export { DEFAULT_MAX_ZIP_ENTRY_BYTES, DEFAULT_MAX_ZIP_TOTAL_BYTES, exportZipBundle, openZipBundle, } from './zip.js';
 export { createScriptView, grantAllDeclaredPermissions, } from './script-view.js';

package/dist/manifest.js

@@ -7,7 +7,13 @@ const KNOWN_TOP_LEVEL_KEYS = new Set([
     'uses',
     'document',
 ]);
-const KNOWN_FS_GRANTS = new Set(['read', 'write:cache/']);
+const KNOWN_FS_GRANTS = new Set(['read', 'write:.cache/']);
+/**
+ * The retired, undotted spelling of the write grant. Never accepted as an
+ * alias: no released bundle declares it, so a manifest naming it gets a
+ * diagnostic pointing at the correct token instead of a silent rewrite.
+ */
+const RETIRED_WRITE_GRANT = 'write:cache/';
 // Simplified but structurally correct semver: MAJOR.MINOR.PATCH with
 // optional prerelease/build metadata. Good enough for a "shape" check —
 // this package does not need to compare or range-match versions.
@@ -145,8 +151,16 @@ export function parseManifest(json) {
                 else {
                     const badGrants = permsObj.bundle.filter((grant) => !KNOWN_FS_GRANTS.has(grant));
                     if (badGrants.length > 0) {
-                        errors.push(`"permissions.bundle" contains invalid grant(s): ${badGrants.join(', ')} ` +
-                            `(expected "read" or "write:cache/")`);
+                        const retiredGrants = badGrants.filter((grant) => grant === RETIRED_WRITE_GRANT);
+                        const otherGrants = badGrants.filter((grant) => grant !== RETIRED_WRITE_GRANT);
+                        if (retiredGrants.length > 0) {
+                            errors.push(`"permissions.bundle" uses the retired grant "write:cache/"; ` +
+                                `the writable directory is "write:.cache/"`);
+                        }
+                        if (otherGrants.length > 0) {
+                            errors.push(`"permissions.bundle" contains invalid grant(s): ${otherGrants.join(', ')} ` +
+                                `(expected "read" or "write:.cache/")`);
+                        }
                     }
                     else {
                         perms.bundle = permsObj.bundle;

package/dist/paths.d.ts

@@ -13,7 +13,7 @@
  * module exists to prevent.
  */
 /** The two write grants a manifest may declare under `permissions.bundle`. */
-export type BundleFsGrant = 'read' | 'write:cache/';
+export type BundleFsGrant = 'read' | 'write:.cache/';
 export type NormalizePathResult = {
     ok: true;
     path: string;
@@ -48,7 +48,11 @@ export interface BundleWritePolicy {
  * `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/`.
+ * explicitly rules out. Every other path requires the `write:.cache/` grant
+ * and must normalize to a path under `.cache/`. The dot prefix is the one
+ * spelling: `normalizeBundlePath` collapses a bare `.` segment away, so
+ * `.cache/x` normalizes to a first segment of `.cache`, an ordinary
+ * dot-prefixed directory name rather than a traversal segment (only a
+ * literal `..` segment is rejected).
  */
 export declare function isWriteAllowed(path: string, policy: BundleWritePolicy): boolean;

package/dist/paths.js

@@ -67,8 +67,12 @@ export function normalizeBundlePath(path) {
  * `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/`.
+ * explicitly rules out. Every other path requires the `write:.cache/` grant
+ * and must normalize to a path under `.cache/`. The dot prefix is the one
+ * spelling: `normalizeBundlePath` collapses a bare `.` segment away, so
+ * `.cache/x` normalizes to a first segment of `.cache`, an ordinary
+ * dot-prefixed directory name rather than a traversal segment (only a
+ * literal `..` segment is rejected).
  */
 export function isWriteAllowed(path, policy) {
     const normalized = normalizeBundlePath(path);
@@ -78,7 +82,7 @@ export function isWriteAllowed(path, policy) {
     // Unconditional denial: no policy input can override this.
     if (p === 'note.mk.md' || p === 'manifest.json')
         return false;
-    if (!policy.grants.includes('write:cache/'))
+    if (!policy.grants.includes('write:.cache/'))
         return false;
-    return p.startsWith('cache/') && p.length > 'cache/'.length;
+    return p.startsWith('.cache/') && p.length > '.cache/'.length;
 }

package/dist/script-view.d.ts

@@ -48,9 +48,9 @@ export declare function grantAllDeclaredPermissions(manifest: BundleManifest): B
  *
  * - 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
+ * - `'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`).

package/dist/script-view.js

@@ -35,9 +35,9 @@ export function 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
+ * - `'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`).

package/dist/storage.d.ts

@@ -41,3 +41,31 @@ export interface BundleStorage {
  * `BundlePathError` describing why it was rejected.
  */
 export declare function normalizeOrThrow(path: string): string;
+/**
+ * A third `BundleStorage` form, alongside the zip form (`./zip`) and the
+ * Node-only directory form (`./fs`): a plain in-memory bundle, backed by
+ * nothing more than a `Map`. No zip bytes to parse, no real filesystem to
+ * guard against symlinks or hard links — this form exists for a host that
+ * already has a bundle's files as plain values (a browser tab building a
+ * bundle from scratch, a test harness) and wants the same `BundleStorage`
+ * contract without a Node dependency, so it lives on the browser-safe main
+ * entry (`./index`) rather than the `./fs` subpath.
+ *
+ * `files` maps a bundle-relative path to its content, either already as
+ * bytes or as a string encoded here as UTF-8 — the same encoding every
+ * other `BundleStorage` form uses for text. Every key is routed through the
+ * exact same `normalizeOrThrow` choke point every other form uses (never a
+ * reimplemented jail): an individually invalid path throws `BundlePathError`
+ * immediately, and two distinct keys that normalize to the same path (e.g.
+ * `"note.mk.md"` and `"./note.mk.md"`) are rejected the same way `openZipBundle`
+ * rejects colliding zip entries, rather than silently letting one shadow the
+ * other.
+ *
+ * Like the zip and directory forms, this storage enforces only the
+ * structural path-jail — never `isWriteAllowed`. Confining writes to
+ * `.cache/` is `ScriptView`'s job (`./script-view`), which wraps whatever
+ * `BundleStorage` it is given; a caller wanting that policy applied wraps
+ * this storage in `createScriptView` exactly as it would the zip or
+ * directory form.
+ */
+export declare function createMemoryBundleStorage(files?: Readonly<Record<string, string | Uint8Array>>): BundleStorage;

package/dist/storage.js

@@ -1,5 +1,6 @@
 import { BundlePathError } from './errors.js';
 import { normalizeBundlePath } from './paths.js';
+const utf8Encoder = new TextEncoder();
 /**
  * The shared choke point every `BundleStorage` implementation calls before
  * touching an archive or the filesystem: normalizes `path` or throws a
@@ -12,3 +13,59 @@ export function normalizeOrThrow(path) {
     }
     return result.path;
 }
+/**
+ * A third `BundleStorage` form, alongside the zip form (`./zip`) and the
+ * Node-only directory form (`./fs`): a plain in-memory bundle, backed by
+ * nothing more than a `Map`. No zip bytes to parse, no real filesystem to
+ * guard against symlinks or hard links — this form exists for a host that
+ * already has a bundle's files as plain values (a browser tab building a
+ * bundle from scratch, a test harness) and wants the same `BundleStorage`
+ * contract without a Node dependency, so it lives on the browser-safe main
+ * entry (`./index`) rather than the `./fs` subpath.
+ *
+ * `files` maps a bundle-relative path to its content, either already as
+ * bytes or as a string encoded here as UTF-8 — the same encoding every
+ * other `BundleStorage` form uses for text. Every key is routed through the
+ * exact same `normalizeOrThrow` choke point every other form uses (never a
+ * reimplemented jail): an individually invalid path throws `BundlePathError`
+ * immediately, and two distinct keys that normalize to the same path (e.g.
+ * `"note.mk.md"` and `"./note.mk.md"`) are rejected the same way `openZipBundle`
+ * rejects colliding zip entries, rather than silently letting one shadow the
+ * other.
+ *
+ * Like the zip and directory forms, this storage enforces only the
+ * structural path-jail — never `isWriteAllowed`. Confining writes to
+ * `.cache/` is `ScriptView`'s job (`./script-view`), which wraps whatever
+ * `BundleStorage` it is given; a caller wanting that policy applied wraps
+ * this storage in `createScriptView` exactly as it would the zip or
+ * directory form.
+ */
+export function createMemoryBundleStorage(files = {}) {
+    const map = new Map();
+    for (const [rawPath, content] of Object.entries(files)) {
+        const normalized = normalizeOrThrow(rawPath);
+        if (map.has(normalized)) {
+            throw new BundlePathError(rawPath, `collides with another entry after normalization (both resolve to ${JSON.stringify(normalized)})`);
+        }
+        map.set(normalized, typeof content === 'string' ? utf8Encoder.encode(content) : content);
+    }
+    return {
+        read(path) {
+            return Promise.resolve(map.get(normalizeOrThrow(path)));
+        },
+        write(path, data) {
+            map.set(normalizeOrThrow(path), data);
+            return Promise.resolve();
+        },
+        list() {
+            return Promise.resolve(Array.from(map.keys()).sort());
+        },
+        exists(path) {
+            return Promise.resolve(map.has(normalizeOrThrow(path)));
+        },
+        size(path) {
+            const data = map.get(normalizeOrThrow(path));
+            return Promise.resolve(data === undefined ? undefined : data.length);
+        },
+    };
+}

package/dist/zip.d.ts

@@ -37,7 +37,7 @@ export declare const DEFAULT_MAX_ZIP_TOTAL_BYTES: number;
  *
  * 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
+ * `./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".
@@ -64,7 +64,7 @@ export declare function openZipBundle(bytes: Uint8Array, options?: OpenZipBundle
  * `{}` — `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__`
+ * 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.
  *

package/dist/zip.js

@@ -213,7 +213,7 @@ export const DEFAULT_MAX_ZIP_TOTAL_BYTES = 256 * 1024 * 1024;
  *
  * 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
+ * `./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".
@@ -308,7 +308,7 @@ export function openZipBundle(bytes, options = {}) {
  * `{}` — `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__`
+ * 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.
  *
@@ -327,7 +327,7 @@ export async function exportZipBundle(storage) {
     if (topLevelProtoLike.length > 0) {
         throw new BundleZipError(`zip export rejected: bundle path(s) ${topLevelProtoLike.map((p) => JSON.stringify(p)).join(', ')} cannot be represented as a top-level zip entry ` +
             `(fflate's zip writer cannot serialize a top-level entry literally named "__proto__", "constructor", or "prototype"); ` +
-            `nest the file under a directory (e.g. "cache/__proto__") to work around this`, topLevelProtoLike);
+            `nest the file under a directory (e.g. ".cache/__proto__") to work around this`, topLevelProtoLike);
     }
     const files = Object.create(null);
     for (const path of paths) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/bundle",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Bundle (.mkz, formerly .mkbundle) storage and policy layer for Markii: manifest handling, the bundle-relative path-jail, zip (fflate) and Node directory storage forms, and a capability-restricted script view. No React, no parsing.",
   "keywords": [
     "markdown",