@markii/bundle 0.3.1 → 0.5.0

package/README.md

@@ -1,5 +1,7 @@
 # @markii/bundle
 
-Bundle (`.mkbundle`) storage and policy handling for [Mark](https://github.com/sadigaxund/markii): manifest parsing/validation, a bundle-relative path-jail, the zip storage form (via `fflate`), a Node-only directory storage form (`./fs` subpath), and a capability-restricted script view. No React, no markdown parsing.
+Bundle (`.mkz`) storage and policy handling for [Markii](https://github.com/sadigaxund/markii): manifest parsing/validation, a bundle-relative path-jail, the zip storage form (via `fflate`), a Node-only directory storage form (`./fs` subpath), and a capability-restricted script view. No React, no markdown parsing.
+
+The legacy `.mkbundle` extension is still recognized for one more release; new bundles are always written as `.mkz`.
 
 See the [repository](https://github.com/sadigaxund/markii) for the format spec and the reference library as a whole.

package/dist/fs.js

@@ -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.mkbundle/../victim.txt b.mkbundle/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
@@ -212,6 +212,24 @@ export function openDirBundle(rootDir) {
                 throw err;
             }
         },
+        async size(path) {
+            // Routes through the exact same `normalizeOrThrow` + `resolveInsideRoot`
+            // choke point `read`/`exists` use, so this can never be used to stat
+            // outside the bundle root or through a symlink (see `resolveInsideRoot`'s
+            // doc comment) — the whole point of C-1's fix is a size check a caller
+            // can trust as much as it trusts `read` itself.
+            const relPath = normalizeOrThrow(path);
+            const { target } = await resolveInsideRoot(rootAbs, relPath);
+            try {
+                const info = await stat(target);
+                return info.isFile() ? info.size : undefined;
+            }
+            catch (err) {
+                if (isEnoent(err))
+                    return undefined;
+                throw err;
+            }
+        },
     };
 }
 /**

package/dist/manifest.d.ts

@@ -11,6 +11,17 @@ export interface BundleManifest {
     mark: string;
     permissions?: BundlePermissions;
     uses?: string[];
+    /**
+     * Optional bundle-relative path to the document to open, overriding the
+     * conventional `note.mk.md`. `parseManifest` only checks that this is a
+     * string; it does not reject `../` or an absolute path here. Path-jailing
+     * is done once, at use time, by the consumer's `normalizeBundlePath` (see
+     * `./paths.ts`) — matching the parity of every other manifest field, none
+     * of which pre-jail path-shaped values either. Keeping the single jail
+     * point at use time avoids duplicating (and risking drift from) that
+     * logic here.
+     */
+    document?: string;
     [key: string]: unknown;
 }
 export interface BundlePermissions {

package/dist/manifest.js

@@ -1,6 +1,11 @@
 /** The current spec version this package's default manifests declare. */
 export const CURRENT_SPEC_VERSION = '0.1.0';
-const KNOWN_TOP_LEVEL_KEYS = new Set(['mark', 'permissions', 'uses']);
+const KNOWN_TOP_LEVEL_KEYS = new Set([
+    'mark',
+    'permissions',
+    'uses',
+    'document',
+]);
 const KNOWN_FS_GRANTS = new Set(['read', 'write:cache/']);
 // Simplified but structurally correct semver: MAJOR.MINOR.PATCH with
 // optional prerelease/build metadata. Good enough for a "shape" check —
@@ -124,6 +129,22 @@ export function parseManifest(json) {
             uses = obj.uses;
         }
     }
+    // --- document (optional) ---
+    // Only the type is checked here (must be a string). Whether it's a usable
+    // relative path (no `../` escape, not absolute) is left to the consumer's
+    // `normalizeBundlePath` at use time — see the type-level doc comment above
+    // for why: no other manifest field pre-jails a path-shaped value either,
+    // so enforcing it here would be inconsistent and would duplicate the one
+    // real jail point.
+    let document;
+    if (obj.document !== undefined) {
+        if (typeof obj.document !== 'string') {
+            errors.push('"document" must be a string');
+        }
+        else {
+            document = obj.document;
+        }
+    }
     // --- unknown top-level keys: forward-compat warning, not an error ---
     for (const key of Object.keys(obj)) {
         if (!KNOWN_TOP_LEVEL_KEYS.has(key)) {
@@ -138,6 +159,8 @@ export function parseManifest(json) {
         manifest.permissions = permissions;
     if (uses !== undefined)
         manifest.uses = uses;
+    if (document !== undefined)
+        manifest.document = document;
     return { ok: true, manifest, warnings };
 }
 /** A minimal, valid manifest for a freshly promoted bundle: no permissions granted, no packs declared. */

package/dist/script-view.d.ts

@@ -22,8 +22,9 @@ export interface ScriptView {
  * 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.
+ * untrusted `.mkz` bundle (or its legacy `.mkbundle` counterpart) 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;
 /**
@@ -31,7 +32,7 @@ export declare function grantAllDeclaredPermissions(manifest: BundleManifest): B
  *
  * 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`
+ * whatever the (possibly untrusted) `.mkz` bundle *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

package/dist/script-view.js

@@ -7,8 +7,9 @@ import { isWriteAllowed } from './paths.js';
  * 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.
+ * untrusted `.mkz` bundle (or its legacy `.mkbundle` counterpart) 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 ?? {};
@@ -18,7 +19,7 @@ export function grantAllDeclaredPermissions(manifest) {
  *
  * 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`
+ * whatever the (possibly untrusted) `.mkz` bundle *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

package/dist/storage.d.ts

@@ -22,6 +22,18 @@ export interface BundleStorage {
     /** All file paths currently in the bundle, bundle-relative, sorted. */
     list(): Promise<string[]>;
     exists(path: string): Promise<boolean>;
+    /**
+     * Returns the file's byte length, or `undefined` if no such path exists —
+     * WITHOUT reading (let alone inflating) its contents. This is what lets a
+     * caller (e.g. `buildBundleSnapshot` in `apps/vscode`) enforce a size
+     * budget by skipping an over-budget file before it is ever materialized in
+     * memory, rather than reading it whole and only then discovering it was too
+     * big. Must route through the exact same path-jail/symlink-refusal a
+     * `read` of the same path would (see the class doc comment above) — a
+     * caller must never be able to learn the size of, or prove the existence
+     * of, a path `read`/`write` would refuse.
+     */
+    size(path: string): Promise<number | undefined>;
 }
 /**
  * The shared choke point every `BundleStorage` implementation calls before

package/dist/zip.js

@@ -31,6 +31,16 @@ function createMapStorage(map) {
             const normalized = normalizeOrThrow(path);
             return Promise.resolve(map.has(normalized));
         },
+        size(path) {
+            // The map already holds each entry's fully-decompressed bytes (this
+            // archive form eagerly inflates every entry up front, under
+            // `openZipBundle`'s own per-entry/total decompression-bomb caps — see
+            // that function's doc comment), so this is just the stored buffer's
+            // length: no re-inflation, no touching the archive bytes again.
+            const normalized = normalizeOrThrow(path);
+            const data = map.get(normalized);
+            return Promise.resolve(data === undefined ? undefined : data.length);
+        },
     };
 }
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@markii/bundle",
-  "version": "0.3.1",
-  "description": "Bundle (.mkbundle) storage and policy layer for Mark: manifest handling, the bundle-relative path-jail, zip (fflate) and Node directory storage forms, and a capability-restricted script view. No React, no parsing.",
+  "version": "0.5.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",
     "mark",