@markii/lua 0.1.0 → 0.3.0

package/dist/capabilities.d.ts

@@ -53,6 +53,25 @@ export interface CapabilityConfig {
     maxFetchBytes?: number;
 }
 export declare const DEFAULT_MAX_FETCH_BYTES = 2000000;
+/** One genuine capability denial, as recorded by `buildCapabilities`' `denials` handle — see its doc comment. */
+export interface CapabilityDenial {
+    reason: 'denied' | 'tier-blocked';
+    message: string;
+}
+/**
+ * Non-spoofable, out-of-band record of the LAST genuine capability denial
+ * that happened during one `buildCapabilities` call's lifetime (i.e. one
+ * `runScript` call — see `./sandbox`). This is a plain JS closure: no Lua
+ * value, no metatable, nothing a script running in the sandbox can ever
+ * read or write, mirroring the discipline `./limits`' breach flag already
+ * uses for resource-limit kills. `sandbox.ts`'s `classifyRuntimeError`
+ * consults `last()` — never any error message string that crossed the Lua
+ * boundary — to decide whether a failed run was genuinely a `'capability'`
+ * kind, and if so which `capability` flavor (`'denied'` vs `'tier-blocked'`).
+ */
+export interface CapabilityDenials {
+    last(): CapabilityDenial | undefined;
+}
 /**
  * `Uint8Array` <-> Lua string, byte-for-byte via one JS UTF-16 code unit
  * per byte (Latin-1-style). Lua strings are themselves 8-bit-clean byte
@@ -76,7 +95,7 @@ export declare function luaStringToBytes(s: string): Uint8Array;
 /**
  * Builds the raw, host-facing async functions to inject as flat globals,
  * and the trusted Lua prelude that wraps them into the ergonomic `net` /
- * `cache` / `bundle` tables the DESIGN.md host API documents (`net.fetch_json(url)`,
+ * `cache` / `bundle` tables the docs/spec.md host API documents (`net.fetch_json(url)`,
  * `cache.get(key, ttl, fn)`, `bundle.read/write/exists(path)`).
  *
  * ## Why "raw flat globals + a Lua prelude" instead of `global.set('net', {...})`
@@ -107,7 +126,7 @@ export declare function luaStringToBytes(s: string): Uint8Array;
  * `js_promise` userdata with `:await()`/`:next()`/`:catch()` methods; the
  * CALLER must explicitly invoke `:await()` to get the resolved value
  * (verified empirically: without it, a script sees the raw promise
- * userdata, not the awaited result). Since `DESIGN.md`'s example script
+ * userdata, not the awaited result). Since `docs/spec.md`'s example script
  * (`local repo = net.fetch_json(url)`) is written as if this were
  * synchronous, the awaiting is done for the author, once, HERE — inside
  * the prelude's Lua wrapper — never exposed to the untrusted script.
@@ -121,4 +140,5 @@ export declare function luaStringToBytes(s: string): Uint8Array;
 export declare function buildCapabilities(config: CapabilityConfig): {
     rawGlobals: Record<string, (...args: never[]) => Promise<unknown>>;
     preludeLua: string;
+    denials: CapabilityDenials;
 };

package/dist/capabilities.js

@@ -50,7 +50,7 @@ export function luaStringToBytes(s) {
 /**
  * Builds the raw, host-facing async functions to inject as flat globals,
  * and the trusted Lua prelude that wraps them into the ergonomic `net` /
- * `cache` / `bundle` tables the DESIGN.md host API documents (`net.fetch_json(url)`,
+ * `cache` / `bundle` tables the docs/spec.md host API documents (`net.fetch_json(url)`,
  * `cache.get(key, ttl, fn)`, `bundle.read/write/exists(path)`).
  *
  * ## Why "raw flat globals + a Lua prelude" instead of `global.set('net', {...})`
@@ -81,7 +81,7 @@ export function luaStringToBytes(s) {
  * `js_promise` userdata with `:await()`/`:next()`/`:catch()` methods; the
  * CALLER must explicitly invoke `:await()` to get the resolved value
  * (verified empirically: without it, a script sees the raw promise
- * userdata, not the awaited result). Since `DESIGN.md`'s example script
+ * userdata, not the awaited result). Since `docs/spec.md`'s example script
  * (`local repo = net.fetch_json(url)`) is written as if this were
  * synchronous, the awaiting is done for the author, once, HERE — inside
  * the prelude's Lua wrapper — never exposed to the untrusted script.
@@ -96,6 +96,15 @@ export function buildCapabilities(config) {
     const maxFetchBytes = config.maxFetchBytes ?? DEFAULT_MAX_FETCH_BYTES;
     const rawGlobals = {};
     const preludeParts = [];
+    // Out-of-band denial record — see `CapabilityDenials`'s doc comment. Every
+    // site below that throws a `capabilityError` records here FIRST, so
+    // `sandbox.ts` can classify the failure by this JS-only signal instead of
+    // by re-reading the (script-forgeable) error message.
+    let lastDenial;
+    function recordDenial(reason, message) {
+        lastDenial = { reason, message };
+    }
+    const denials = { last: () => lastDenial };
     // --- net --------------------------------------------------------------
     // `fetch_json` and `post`/`patch` are gated INDEPENDENTLY of each other
     // (a manifest can grant POST to a host without granting it GET, or vice
@@ -104,9 +113,12 @@ export function buildCapabilities(config) {
     // this function nested POST/PATCH wiring inside "if GET is granted",
     // which silently produced no `net.post` at all for a POST-only grant.
     const netGrants = config.netGrants ?? { get: [], post: [] };
+    // NOTE: no longer conditioned on `config.tier === 'manual'` for the POST
+    // half — under 'auto' with POST hosts granted, `net.post`/`net.patch` are
+    // now wired to TIER-BLOCKED STUBS below (not left undefined), so the
+    // `net` table itself must exist for those stubs to attach to.
     const netTableNeeded = config.net !== undefined &&
-        (netGrants.get.length > 0 ||
-            (config.tier === 'manual' && netGrants.post.length > 0));
+        (netGrants.get.length > 0 || netGrants.post.length > 0);
     if (netTableNeeded) {
         preludeParts.push('net = net or {}\n');
     }
@@ -114,18 +126,24 @@ export function buildCapabilities(config) {
         rawGlobals.__smd_net_get_raw = (async (url) => {
             const host = hostnameOf(url);
             if (!host || !netGrants.get.includes(host)) {
-                throw capabilityError(`net access to host "${host ?? url}" not granted for GET`);
+                const message = `net access to host "${host ?? url}" not granted for GET`;
+                recordDenial('denied', message);
+                throw capabilityError(message);
             }
             const res = await config.net.get(url);
             if (res.body.length > maxFetchBytes) {
-                throw capabilityError(`fetch response for "${url}" exceeds the ${maxFetchBytes}-byte cap`);
+                const message = `fetch response for "${url}" exceeds the ${maxFetchBytes}-byte cap`;
+                recordDenial('denied', message);
+                throw capabilityError(message);
             }
             let parsed;
             try {
                 parsed = JSON.parse(res.body);
             }
             catch {
-                throw capabilityError(`fetch response for "${url}" was not valid JSON`);
+                const message = `fetch response for "${url}" was not valid JSON`;
+                recordDenial('denied', message);
+                throw capabilityError(message);
             }
             return parsed;
         });
@@ -135,10 +153,14 @@ __smd_net_get_raw = nil
 net.fetch_json = function(url) return __smd_net_get(url):await() end
 `);
     }
-    // POST/PATCH are effectful — only wired at all under the 'manual' tier,
-    // and only for hosts the effective grant set allows for POST. Under
-    // 'auto' these are simply never defined: calling `net.post` fails as
-    // "attempt to call a nil value", a clean typed failure (spec §8: "An
+    // POST/PATCH are effectful. Under the 'manual' tier, wired to the real
+    // provider for hosts the effective grant set allows for POST. Under
+    // 'auto', even when POST hosts ARE granted, they are wired to STUBS
+    // that record a 'tier-blocked' denial and throw WITHOUT EVER reaching
+    // `config.net.post`/`.patch` — this grants nothing new (the provider is
+    // never called), it only makes "granted but tier-forbidden" a
+    // classifiable, non-spoofable outcome instead of collapsing into an
+    // ordinary "attempt to call a nil value" runtime error (spec §8: "An
     // effectful call under an auto trigger fails cleanly").
     if (config.tier === 'manual' &&
         config.net?.post &&
@@ -146,7 +168,9 @@ net.fetch_json = function(url) return __smd_net_get(url):await() end
         rawGlobals.__smd_net_post_raw = (async (url, body) => {
             const host = hostnameOf(url);
             if (!host || !netGrants.post.includes(host)) {
-                throw capabilityError(`net access to host "${host ?? url}" not granted for POST`);
+                const message = `net access to host "${host ?? url}" not granted for POST`;
+                recordDenial('denied', message);
+                throw capabilityError(message);
             }
             return config.net.post(url, body);
         });
@@ -154,6 +178,29 @@ net.fetch_json = function(url) return __smd_net_get(url):await() end
 local __smd_net_post = __smd_net_post_raw
 __smd_net_post_raw = nil
 net.post = function(url, body) return __smd_net_post(url, body):await() end
+`);
+    }
+    else if (
+    // Mirrors the 'manual' condition above EXACTLY except for the tier, so
+    // the read-only tier never exposes a wider method surface than the
+    // full-grant tier would: a stub appears only where a real `net.post`
+    // would have appeared under 'manual'. Without the `config.net?.post`
+    // half, a host whose provider implements no POST at all would still
+    // show `net.post` under 'auto' (as a tier-block stub) while showing
+    // nothing under 'manual' — an inconsistency a feature-detecting script
+    // (`if net.post then`) would read exactly backwards.
+    config.tier === 'auto' &&
+        config.net?.post &&
+        netGrants.post.length > 0) {
+        rawGlobals.__smd_net_post_tier_blocked_raw = (async () => {
+            const message = 'net.post is granted but not permitted under the read-only auto tier (requires a manual run)';
+            recordDenial('tier-blocked', message);
+            throw capabilityError(message);
+        });
+        preludeParts.push(`
+local __smd_net_post_blocked = __smd_net_post_tier_blocked_raw
+__smd_net_post_tier_blocked_raw = nil
+net.post = function(url, body) return __smd_net_post_blocked(url, body):await() end
 `);
     }
     if (config.tier === 'manual' &&
@@ -162,7 +209,9 @@ net.post = function(url, body) return __smd_net_post(url, body):await() end
         rawGlobals.__smd_net_patch_raw = (async (url, body) => {
             const host = hostnameOf(url);
             if (!host || !netGrants.post.includes(host)) {
-                throw capabilityError(`net access to host "${host ?? url}" not granted for PATCH`);
+                const message = `net access to host "${host ?? url}" not granted for PATCH`;
+                recordDenial('denied', message);
+                throw capabilityError(message);
             }
             return config.net.patch(url, body);
         });
@@ -170,6 +219,22 @@ net.post = function(url, body) return __smd_net_post(url, body):await() end
 local __smd_net_patch = __smd_net_patch_raw
 __smd_net_patch_raw = nil
 net.patch = function(url, body) return __smd_net_patch(url, body):await() end
+`);
+    }
+    else if (
+    // Same mirroring as the POST stub above — see its comment.
+    config.tier === 'auto' &&
+        config.net?.patch &&
+        netGrants.post.length > 0) {
+        rawGlobals.__smd_net_patch_tier_blocked_raw = (async () => {
+            const message = 'net.patch is granted but not permitted under the read-only auto tier (requires a manual run)';
+            recordDenial('tier-blocked', message);
+            throw capabilityError(message);
+        });
+        preludeParts.push(`
+local __smd_net_patch_blocked = __smd_net_patch_tier_blocked_raw
+__smd_net_patch_tier_blocked_raw = nil
+net.patch = function(url, body) return __smd_net_patch_blocked(url, body):await() end
 `);
     }
     // --- cache --------------------------------------------------------------
@@ -220,24 +285,27 @@ end
     // Delegates entirely to the injected `ScriptView` (`@markii/bundle`), which
     // already enforces the path-jail and the read/write:cache/ split (spec
     // §11). This module adds nothing on top except the tier gate for
-    // `bundle.write` (absent entirely under 'auto' — read-only tier) and the
-    // byte<->Lua-string conversion.
+    // `bundle.write` (a tier-blocked stub under 'auto' — read-only tier) and
+    // the byte<->Lua-string conversion.
     if (config.bundle) {
         const view = config.bundle;
         // `ScriptView` (@markii/bundle) throws its own `ScriptCapabilityError` /
         // `BundlePathError` for a denied or path-jail-violating call — those
-        // are re-tagged here with `CAPABILITY_ERROR_TAG` so `sandbox.ts`'s
-        // message-based classification (see `./errors`'s doc comment on why
-        // that's necessary) reports them as `kind: 'capability'` uniformly,
-        // the same as a net host-allowlist denial, rather than falling
-        // through to the generic `'runtime'` bucket.
+        // are re-tagged here with `CAPABILITY_ERROR_TAG` (a cosmetic prefix
+        // only, see `./errors`'s doc comment) AND recorded on the `denials`
+        // handle as reason `'denied'`, so `sandbox.ts` reports them as
+        // `kind: 'capability', capability: 'denied'` uniformly, the same as a
+        // net host-allowlist denial, rather than falling through to the
+        // generic `'runtime'` bucket.
         rawGlobals.__smd_bundle_read_raw = (async (path) => {
             let data;
             try {
                 data = await view.read(path);
             }
             catch (err) {
-                throw capabilityError(describeThrown(err));
+                const message = describeThrown(err);
+                recordDenial('denied', message);
+                throw capabilityError(message);
             }
             return data === undefined ? null : bytesToLuaString(data);
         });
@@ -246,7 +314,9 @@ end
                 return await view.exists(path);
             }
             catch (err) {
-                throw capabilityError(describeThrown(err));
+                const message = describeThrown(err);
+                recordDenial('denied', message);
+                throw capabilityError(message);
             }
         });
         preludeParts.push(`
@@ -264,7 +334,9 @@ bundle.exists = function(path) return __smd_bundle_exists(path):await() end
                     await view.write(path, luaStringToBytes(data));
                 }
                 catch (err) {
-                    throw capabilityError(describeThrown(err));
+                    const message = describeThrown(err);
+                    recordDenial('denied', message);
+                    throw capabilityError(message);
                 }
                 return true;
             });
@@ -274,8 +346,25 @@ __smd_bundle_write_raw = nil
 bundle.write = function(path, data) return __smd_bundle_write(path, data):await() end
 `);
         }
-        // Under 'auto', `bundle.write` is simply never defined — spec §8's
-        // read-only tier table: "bundle/cache reads, cache writes only".
+        else {
+            // Under 'auto': `bundle.write` is wired to a TIER-BLOCKED STUB that
+            // records a 'tier-blocked' denial and throws WITHOUT EVER reaching
+            // `view.write` — the bundle view's own write path is never touched,
+            // so this grants nothing new; it only makes "write is available but
+            // this tier forbids it" classifiable instead of collapsing into an
+            // ordinary "attempt to call a nil value" runtime error (spec §8:
+            // "bundle/cache reads, cache writes only" under the read-only tier).
+            rawGlobals.__smd_bundle_write_tier_blocked_raw = (async () => {
+                const message = 'bundle.write is not permitted under the read-only auto tier (requires a manual run)';
+                recordDenial('tier-blocked', message);
+                throw capabilityError(message);
+            });
+            preludeParts.push(`
+local __smd_bundle_write_blocked = __smd_bundle_write_tier_blocked_raw
+__smd_bundle_write_tier_blocked_raw = nil
+bundle.write = function(path, data) return __smd_bundle_write_blocked(path, data):await() end
+`);
+        }
     }
-    return { rawGlobals, preludeLua: preludeParts.join('\n') };
+    return { rawGlobals, preludeLua: preludeParts.join('\n'), denials };
 }

package/dist/errors.d.ts

@@ -13,33 +13,61 @@
  * checks on the far side are useless (verified empirically against
  * wasmoon 1.16.0: `new MyError('x')` thrown inside an injected async
  * function round-trips as `Error: MyError: x`, not `MyError`). So
- * classification of capability/marshal failures raised *from inside Lua
- * execution* is done by tagging the error message with one of the
- * `*_ERROR_TAG` prefixes below and pattern-matching on it in `sandbox.ts`
- * after the run fails. Resource-limit breaches are NOT classified this way
- * — they're tracked out-of-band via a plain JS closure flag set inside the
- * instruction hook (see `./limits`), which Lua code can never see or touch,
- * so that classification is exact regardless of what any error message says.
+ * classification of marshal failures raised *from inside Lua execution* is
+ * done by tagging the error message with `MARSHAL_ERROR_TAG` and
+ * pattern-matching on it in `sandbox.ts` after the run fails (a forged
+ * marshal tag only relabels one script-error-class failure as another —
+ * see `classifyRuntimeError`'s doc comment).
+ *
+ * Capability failures are classified DIFFERENTLY, and NOT by message
+ * matching (this used to be message-tag-based too — `error("MARK_CAPABILITY:
+ * ...")` from a script would forge a `kind: 'capability'` result, which is
+ * exactly the bug this taxonomy closes). See `./capabilities`'s
+ * `CapabilityDenials` handle: every genuine denial is recorded on a plain JS
+ * closure BEFORE the corresponding throw, entirely out of Lua's reach, and
+ * `sandbox.ts` consults that handle — never the message that came back out
+ * of the VM — to decide `kind: 'capability'`. This mirrors the discipline
+ * already used for resource-limit breaches: they're tracked out-of-band via
+ * a plain JS closure flag set inside the instruction hook (see `./limits`)
+ * and the raw `LuaReturn.ErrorMem` C-API status code (see
+ * `captureAssertOkStatus` in `./sandbox`), neither of which Lua code can see
+ * or touch, so classification is exact regardless of what any error message
+ * says.
+ */
+/**
+ * Prefix tag applied to the `Error` message thrown into Lua for a capability
+ * (permission) denial. PURELY COSMETIC as of the capability-denial JS-closure
+ * rework (see the module doc comment above): it makes a message readable to
+ * a human/log, and nothing else. It is NOT, and must never again become, a
+ * classification signal — `sandbox.ts`'s `classifyRuntimeError` does not
+ * (and must not) inspect it; a script forging `error("MARK_CAPABILITY:
+ * ...")` produces a message containing this tag but classifies as an
+ * ordinary `'runtime'`/`'script-error'` failure, exactly like any other
+ * `error()` call, because no genuine denial was ever recorded on the
+ * `CapabilityDenials` handle for that run.
  */
-/** Prefix tag for a capability (permission) denial raised into Lua from a host-provided function. */
 export declare const CAPABILITY_ERROR_TAG = "MARK_CAPABILITY";
 /** Prefix tag for a marshal-time rejection raised from the in-Lua marshal walk (see `./marshal`). */
 export declare const MARSHAL_ERROR_TAG = "MARK_MARSHAL";
 /** The limits a run can breach; see `./limits`. */
 export type ScriptLimitKind = 'instructions' | 'timeout' | 'memory';
 /** Why a return value was rejected by the marshaller; see `./marshal`. */
-export type ScriptMarshalReason = 'depth' | 'nodes' | 'cycle' | 'type' | 'key-type' | 'non-finite-number';
+export type ScriptMarshalReason = 'depth' | 'nodes' | 'cycle' | 'type' | 'key-type' | 'non-finite-number' | 'nul-byte';
 /**
  * The full discriminated failure shape `runScript` returns. `kind`:
  * - `'limit'` — a resource limit was breached (instruction count, wall
  *   clock, or memory). `limit` says which.
  * - `'capability'` — the script attempted something its granted
  *   capabilities don't allow (ungranted host, effectful op under an
- *   auto-run tier, disallowed bundle path/write).
+ *   auto-run tier, disallowed bundle path/write). `capability` says which
+ *   flavor — see below.
  * - `'marshal'` — the script's return value could not be safely converted
  *   to a JSON-serializable JS value (function/userdata/thread, a cycle,
- *   too deep, too many nodes, a non-string table key, or a non-finite
- *   number). `reason` says which.
+ *   too deep, too many nodes, a non-string table key, a non-finite
+ *   number, or a string containing an embedded NUL byte — wasmoon silently
+ *   truncates a Lua string at its first NUL when converting to JS, so this
+ *   is rejected on the Lua side before that truncation can happen).
+ *   `reason` says which.
  * - `'runtime'` — an ordinary Lua error (syntax error, `error()` call,
  *   type error, stack overflow, etc.) not covered by the above.
  */
@@ -48,6 +76,20 @@ export interface ScriptFailure {
     message: string;
     limit?: ScriptLimitKind;
     reason?: ScriptMarshalReason;
+    /**
+     * Set only when `kind === 'capability'`, discriminating WHICH flavor of
+     * capability failure this was — derived exclusively from `./capabilities`'
+     * `CapabilityDenials` handle (a plain JS closure, never from any message
+     * text; see the module doc comment):
+     * - `'denied'`      — the grant was absent, or the host actively refused
+     *   (an ungranted net host, a bundle path-jail rejection, a fetch-size
+     *   cap). A manual run with the SAME grants would fail identically.
+     * - `'tier-blocked'` — the capability genuinely exists in the granted set,
+     *   but the current execution tier (`'auto'`) forbids exercising it. A
+     *   manual run of the exact same script, with the exact same grants,
+     *   would succeed.
+     */
+    capability?: 'denied' | 'tier-blocked';
 }
 /**
  * Thrown by the instruction-count/wall-clock hook installed in `./limits`

package/dist/errors.js

@@ -13,15 +13,39 @@
  * checks on the far side are useless (verified empirically against
  * wasmoon 1.16.0: `new MyError('x')` thrown inside an injected async
  * function round-trips as `Error: MyError: x`, not `MyError`). So
- * classification of capability/marshal failures raised *from inside Lua
- * execution* is done by tagging the error message with one of the
- * `*_ERROR_TAG` prefixes below and pattern-matching on it in `sandbox.ts`
- * after the run fails. Resource-limit breaches are NOT classified this way
- * — they're tracked out-of-band via a plain JS closure flag set inside the
- * instruction hook (see `./limits`), which Lua code can never see or touch,
- * so that classification is exact regardless of what any error message says.
+ * classification of marshal failures raised *from inside Lua execution* is
+ * done by tagging the error message with `MARSHAL_ERROR_TAG` and
+ * pattern-matching on it in `sandbox.ts` after the run fails (a forged
+ * marshal tag only relabels one script-error-class failure as another —
+ * see `classifyRuntimeError`'s doc comment).
+ *
+ * Capability failures are classified DIFFERENTLY, and NOT by message
+ * matching (this used to be message-tag-based too — `error("MARK_CAPABILITY:
+ * ...")` from a script would forge a `kind: 'capability'` result, which is
+ * exactly the bug this taxonomy closes). See `./capabilities`'s
+ * `CapabilityDenials` handle: every genuine denial is recorded on a plain JS
+ * closure BEFORE the corresponding throw, entirely out of Lua's reach, and
+ * `sandbox.ts` consults that handle — never the message that came back out
+ * of the VM — to decide `kind: 'capability'`. This mirrors the discipline
+ * already used for resource-limit breaches: they're tracked out-of-band via
+ * a plain JS closure flag set inside the instruction hook (see `./limits`)
+ * and the raw `LuaReturn.ErrorMem` C-API status code (see
+ * `captureAssertOkStatus` in `./sandbox`), neither of which Lua code can see
+ * or touch, so classification is exact regardless of what any error message
+ * says.
+ */
+/**
+ * Prefix tag applied to the `Error` message thrown into Lua for a capability
+ * (permission) denial. PURELY COSMETIC as of the capability-denial JS-closure
+ * rework (see the module doc comment above): it makes a message readable to
+ * a human/log, and nothing else. It is NOT, and must never again become, a
+ * classification signal — `sandbox.ts`'s `classifyRuntimeError` does not
+ * (and must not) inspect it; a script forging `error("MARK_CAPABILITY:
+ * ...")` produces a message containing this tag but classifies as an
+ * ordinary `'runtime'`/`'script-error'` failure, exactly like any other
+ * `error()` call, because no genuine denial was ever recorded on the
+ * `CapabilityDenials` handle for that run.
  */
-/** Prefix tag for a capability (permission) denial raised into Lua from a host-provided function. */
 export const CAPABILITY_ERROR_TAG = 'MARK_CAPABILITY';
 /** Prefix tag for a marshal-time rejection raised from the in-Lua marshal walk (see `./marshal`). */
 export const MARSHAL_ERROR_TAG = 'MARK_MARSHAL';

package/dist/executor.d.ts

@@ -1,7 +1,7 @@
 import type { ScriptExecutor } from '@markii/runtime';
 import { type RunScriptOptions } from './sandbox.js';
 /**
- * Slice 2 of the scripting-usability layer (DESIGN.md §8): the reusable
+ * Slice 2 of the scripting-usability layer (docs/scripting.md): the reusable
  * adapter from this package's `runScript` to `@markii/runtime`'s
  * language-agnostic `ScriptExecutor` shape, so `runDocumentScripts` can run
  * a document's script blocks through the real Lua sandbox without
@@ -31,9 +31,10 @@ export type LuaExecutorConfig = Omit<RunScriptOptions, 'code' | 'tier'>;
  * signature. `runScript` never throws (see `./sandbox`'s doc comment), so
  * this adapter doesn't need its own try/catch — it only reshapes the
  * result: `ok: true` passes `value` through untouched; `ok: false` maps
- * `runScript`'s `ScriptFailure` (`{ kind, message, ... }`) down to the
- * narrower `{ kind: string; message: string }` `ExecuteFailure` shape
- * `@markii/runtime` expects, dropping the Lua-specific `limit`/`reason`
- * fields (still visible in `message` for anyone reading the stored error).
+ * `runScript`'s `ScriptFailure` (`{ kind, message, ... }`) down to
+ * `@markii/runtime`'s closed `ExecuteFailure` shape via
+ * `toRuntimeFailureKind`, dropping the Lua-specific `limit`/`reason`/
+ * `capability` sub-fields (still visible in `message` for anyone reading
+ * the stored error).
  */
 export declare function createLuaExecutor(config?: LuaExecutorConfig): ScriptExecutor;

package/dist/executor.js

@@ -1,4 +1,32 @@
 import { runScript } from './sandbox.js';
+/**
+ * Maps this package's own `ScriptFailure.kind` (`'limit' | 'capability' |
+ * 'marshal' | 'runtime'`, further discriminated by `ScriptFailure.
+ * capability` for the `'capability'` case) down to `@markii/runtime`'s
+ * closed, shared `FailureKind` union (`'script-error' | 'capability-denied'
+ * | 'tier-blocked' | 'limit'`):
+ * - `'limit'`                                 -> `'limit'`
+ * - `'capability'` with `capability === 'tier-blocked'` -> `'tier-blocked'`
+ * - `'capability'` otherwise (i.e. `'denied'`, or — defensively — absent)
+ *                                              -> `'capability-denied'`
+ * - `'marshal'` / `'runtime'`                 -> `'script-error'`
+ *
+ * This is the one place the Lua-specific taxonomy and the runtime-shared
+ * one meet; every other module in this package only knows `ScriptFailure`.
+ */
+function toRuntimeFailureKind(failure) {
+    switch (failure.kind) {
+        case 'limit':
+            return 'limit';
+        case 'capability':
+            return failure.capability === 'tier-blocked'
+                ? 'tier-blocked'
+                : 'capability-denied';
+        case 'marshal':
+        case 'runtime':
+            return 'script-error';
+    }
+}
 /**
  * Builds a `ScriptExecutor` (`@markii/runtime`) backed by this package's
  * `runScript`. `config` is captured once and reused for every script the
@@ -7,10 +35,11 @@ import { runScript } from './sandbox.js';
  * signature. `runScript` never throws (see `./sandbox`'s doc comment), so
  * this adapter doesn't need its own try/catch — it only reshapes the
  * result: `ok: true` passes `value` through untouched; `ok: false` maps
- * `runScript`'s `ScriptFailure` (`{ kind, message, ... }`) down to the
- * narrower `{ kind: string; message: string }` `ExecuteFailure` shape
- * `@markii/runtime` expects, dropping the Lua-specific `limit`/`reason`
- * fields (still visible in `message` for anyone reading the stored error).
+ * `runScript`'s `ScriptFailure` (`{ kind, message, ... }`) down to
+ * `@markii/runtime`'s closed `ExecuteFailure` shape via
+ * `toRuntimeFailureKind`, dropping the Lua-specific `limit`/`reason`/
+ * `capability` sub-fields (still visible in `message` for anyone reading
+ * the stored error).
  */
 export function createLuaExecutor(config = {}) {
     return async ({ code, tier }) => {
@@ -20,7 +49,10 @@ export function createLuaExecutor(config = {}) {
         }
         return {
             ok: false,
-            error: { kind: result.error.kind, message: result.error.message },
+            error: {
+                kind: toRuntimeFailureKind(result.error),
+                message: result.error.message,
+            },
         };
     };
 }

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export type { CreateEmptyLuaEngineOptions } from './globals.js';
 export { ALLOWED_GLOBALS, DENIED_GLOBALS, createEmptyLuaEngine, } from './globals.js';
 export type { LimitHandle, ScriptLimits } from './limits.js';
 export { DEFAULT_LIMITS, installLimits } from './limits.js';
-export type { CacheEntry, CacheProvider, CapabilityConfig, CapabilityTier, NetGrants, NetProvider, NetResponse, } from './capabilities.js';
+export type { CacheEntry, CacheProvider, CapabilityConfig, CapabilityDenial, CapabilityDenials, CapabilityTier, NetGrants, NetProvider, NetResponse, } from './capabilities.js';
 export { DEFAULT_MAX_FETCH_BYTES, bytesToLuaString, buildCapabilities, luaStringToBytes, } from './capabilities.js';
 export type { MarshalLimits } from './marshal.js';
 export { DEFAULT_MARSHAL_LIMITS, buildMarshalPrelude, finalizeMarshaledValue, wrapUserCode, } from './marshal.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 // @markii/lua: the sandboxed Lua 5.4 (wasmoon) execution primitive backing
 // spec §8 (scripting), §10 (capability security), and §11 (bundle-scoped
-// filesystem). No React, no @markii/core, no @markii/react — see CLAUDE.md's
+// filesystem). No React, no @markii/core, no @markii/react — see AGENTS.md's
 // import rule and the ESLint guard in the root config. May depend on
 // @markii/bundle for the `ScriptView` capability type only.
 export { CAPABILITY_ERROR_TAG, MARSHAL_ERROR_TAG, ScriptLimitError, } from './errors.js';

package/dist/limits.d.ts

@@ -112,7 +112,7 @@ export interface LimitHandle {
  * AUTHORITATIVE kill for that class of failure is not this hook at all —
  * it's the host's EXTERNAL, terminatable-isolate watchdog (dedicated Web
  * Worker/`worker_thread` + an outside wall-clock timer calling
- * `terminate()`), now normative in DESIGN.md §10 ("In-process limits are
+ * `terminate()`), now normative in docs/security.md ("In-process limits are
  * best-effort; the terminatable isolate is the real guarantee"). This
  * module's hook reduces how often that external kill is needed and gives
  * fast, precise, in-band error classification for the common compute-bound

package/dist/limits.js

@@ -93,7 +93,7 @@ export const DEFAULT_LIMITS = {
  * AUTHORITATIVE kill for that class of failure is not this hook at all —
  * it's the host's EXTERNAL, terminatable-isolate watchdog (dedicated Web
  * Worker/`worker_thread` + an outside wall-clock timer calling
- * `terminate()`), now normative in DESIGN.md §10 ("In-process limits are
+ * `terminate()`), now normative in docs/security.md ("In-process limits are
  * best-effort; the terminatable isolate is the real guarantee"). This
  * module's hook reduces how often that external kill is needed and gives
  * fast, precise, in-band error classification for the common compute-bound

package/dist/marshal.js

@@ -74,9 +74,21 @@ export const DEFAULT_MARSHAL_LIMITS = {
  */
 export function buildMarshalPrelude(limits) {
     return `
+-- Captured into locals AT PRELUDE-DEFINITION TIME (this chunk is doString'd
+-- once per engine, before any untrusted user code runs), so the walk below
+-- closes over these as upvalues fixed to the genuine primitives -- immune to
+-- a later script doing e.g. \`error = function() end\` in the shared globals
+-- table before this walk runs. See finding F-1 in the sandbox audit: the
+-- walk previously resolved error/type/pairs/math.floor as DYNAMIC GLOBAL
+-- lookups, which a script could rebind to neuter its own caps.
+local error, type, pairs, floor, sfind = error, type, pairs, math.floor, string.find
+
 local function __smd_marshal(value, seen, depth, budget)
   local t = type(value)
   if t == "nil" or t == "boolean" or t == "string" or t == "number" then
+    if t == "string" and sfind(value, "\\0", 1, true) then
+      error("${MARSHAL_ERROR_TAG}:nul-byte")
+    end
     budget.n = budget.n + 1
     if budget.n > budget.maxNodes then error("${MARSHAL_ERROR_TAG}:nodes") end
     return value
@@ -90,7 +102,7 @@ local function __smd_marshal(value, seen, depth, budget)
     local isArray = true
     for k, _ in pairs(value) do
       count = count + 1
-      if type(k) ~= "number" or k < 1 or math.floor(k) ~= k then
+      if type(k) ~= "number" or k < 1 or floor(k) ~= k then
         isArray = false
       end
     end

package/dist/sandbox.d.ts

@@ -58,11 +58,13 @@ export type RunScriptResult = {
  *    UNCONDITIONALLY and, if set, wins over whatever the run otherwise
  *    reported — see `./limits`'s doc comment for why this is the actual
  *    enforcement point for "not swallowed by the script's own `pcall`".
- * 7. Otherwise, a thrown error is classified by three non-spoofable
- *    out-of-band signals, in order, before ever falling back to
+ * 7. Otherwise, a thrown error is classified by non-spoofable out-of-band
+ *    signals, in order, before ever falling back to
  *    `classifyRuntimeError`'s message-based path: the wall-clock guard's
  *    own `ScriptLimitError` sentinel (`instanceof`, Defect 3), then the
- *    raw `LuaReturn.ErrorMem` status code (Defect 2). A successful return
+ *    raw `LuaReturn.ErrorMem` status code (Defect 2), then step 3's
+ *    `CapabilityDenials` handle (`denials.last()` — was ANY genuine
+ *    denial/tier-block recorded during this run?). A successful return
  *    goes through `finalizeMarshaledValue` for the final NaN/Infinity
  *    check and marker cleanup.
  * 8. `finally`: hook removed, thread popped, engine closed — every path,

package/dist/sandbox.js

@@ -1,6 +1,6 @@
 import { LuaReturn } from 'wasmoon';
 import { buildCapabilities, } from './capabilities.js';
-import { CAPABILITY_ERROR_TAG, MARSHAL_ERROR_TAG, ScriptLimitError, } from './errors.js';
+import { MARSHAL_ERROR_TAG, ScriptLimitError } from './errors.js';
 import { createEmptyLuaEngine } from './globals.js';
 import { DEFAULT_LIMITS, installLimits } from './limits.js';
 import { buildMarshalPrelude, DEFAULT_MARSHAL_LIMITS, finalizeMarshaledValue, wrapUserCode, } from './marshal.js';
@@ -105,6 +105,8 @@ function extractMarshalReason(message) {
             return 'cycle';
         case 'key-type':
             return 'key-type';
+        case 'nul-byte':
+            return 'nul-byte';
         case 'type':
             return 'type';
         default:
@@ -113,15 +115,27 @@ function extractMarshalReason(message) {
 }
 /**
  * Classifies an error thrown out of `thread.run()` into the discriminated
- * `ScriptFailure` shape. Message-prefix matching (`CAPABILITY_ERROR_TAG`,
- * `MARSHAL_ERROR_TAG`) is used rather than `instanceof` because wasmoon
- * does not preserve JS `Error` subclass identity across the Lua round trip
- * — see the doc comment on those tags in `./errors` for the empirical
- * evidence. Resource-limit breaches are ALL classified separately, BEFORE
- * this function is ever called, via non-spoofable out-of-band signals —
- * never through this message-based path, since a script can trivially
- * forge any message string (e.g. `error("MARK_LIMIT: ...")` or
- * `error("not enough memory")`) but cannot forge these:
+ * `ScriptFailure` shape, EXCLUDING capability failures — those are decided
+ * separately, BEFORE this function is ever consulted (see `runScript`
+ * below), by the `CapabilityDenials` out-of-band handle (`./capabilities`).
+ * This function only ever returns `'marshal'` or `'runtime'`.
+ *
+ * Message-prefix matching (`MARSHAL_ERROR_TAG`) is used here rather than
+ * `instanceof` because wasmoon does not preserve JS `Error` subclass
+ * identity across the Lua round trip — see the doc comment on that tag in
+ * `./errors` for the empirical evidence. This IS spoofable in principle (a
+ * script could `error("MARK_MARSHAL:type ...")`), but the consequence of
+ * that forgery is bounded and accepted: it only relabels one
+ * `'script-error'`-class failure (`'runtime'`) as another (`'marshal'`) —
+ * neither claims a capability was ever exercised, so there is no security
+ * property being defended here the way there is for `'capability'`/
+ * `'limit'`.
+ *
+ * Resource-limit breaches are ALL classified separately, BEFORE this
+ * function is ever called, via non-spoofable out-of-band signals — never
+ * through a message-based path, since a script can trivially forge any
+ * message string (e.g. `error("MARK_LIMIT: ...")` or `error("not enough
+ * memory")`) but cannot forge these:
  *   - instruction/wall-clock breaches: the JS closure flag from
  *     `./limits`' hook (see `runScript` below);
  *   - the async-hang backstop: `instanceof ScriptLimitError` on the
@@ -129,15 +143,14 @@ function extractMarshalReason(message) {
  *     boundary (see the guard's construction in `runScript`);
  *   - memory-cap breaches: the raw `LuaReturn.ErrorMem` C-API status code
  *     captured by `captureAssertOkStatus` (see its doc comment).
+ * Capability failures are classified the same non-spoofable way, via the
+ * `CapabilityDenials` handle — a script forging `error("MARK_CAPABILITY:
+ * ...")` no longer produces `kind: 'capability'`; with no genuine denial
+ * recorded, it falls through to THIS function and comes back `'runtime'`,
+ * exactly like any other `error()` call with no special meaning.
  */
 function classifyRuntimeError(err) {
     const message = describeError(err);
-    if (message.includes(CAPABILITY_ERROR_TAG)) {
-        return {
-            kind: 'capability',
-            message: message.replace(`${CAPABILITY_ERROR_TAG}: `, ''),
-        };
-    }
     if (message.includes(MARSHAL_ERROR_TAG)) {
         return {
             kind: 'marshal',
@@ -171,11 +184,13 @@ function classifyRuntimeError(err) {
  *    UNCONDITIONALLY and, if set, wins over whatever the run otherwise
  *    reported — see `./limits`'s doc comment for why this is the actual
  *    enforcement point for "not swallowed by the script's own `pcall`".
- * 7. Otherwise, a thrown error is classified by three non-spoofable
- *    out-of-band signals, in order, before ever falling back to
+ * 7. Otherwise, a thrown error is classified by non-spoofable out-of-band
+ *    signals, in order, before ever falling back to
  *    `classifyRuntimeError`'s message-based path: the wall-clock guard's
  *    own `ScriptLimitError` sentinel (`instanceof`, Defect 3), then the
- *    raw `LuaReturn.ErrorMem` status code (Defect 2). A successful return
+ *    raw `LuaReturn.ErrorMem` status code (Defect 2), then step 3's
+ *    `CapabilityDenials` handle (`denials.last()` — was ANY genuine
+ *    denial/tier-block recorded during this run?). A successful return
  *    goes through `finalizeMarshaledValue` for the final NaN/Infinity
  *    check and marker cleanup.
  * 8. `finally`: hook removed, thread popped, engine closed — every path,
@@ -194,7 +209,7 @@ export async function runScript(options) {
     let limitHandle;
     let guardTimer;
     try {
-        const { rawGlobals, preludeLua } = buildCapabilities({
+        const { rawGlobals, preludeLua, denials } = buildCapabilities({
             tier: options.tier,
             net: options.net,
             netGrants: options.netGrants,
@@ -302,6 +317,39 @@ export async function runScript(options) {
                     },
                 };
             }
+            // Capability failures, identified the same non-spoofable way as the
+            // limit breaches above: `denials.last()` is a plain JS closure
+            // (`./capabilities`'s `CapabilityDenials`) that Lua can never see or
+            // touch, recorded BEFORE the corresponding throw at every genuine
+            // denial/tier-block site. If ANY denial was recorded during this run,
+            // it wins over whatever `classifyRuntimeError`'s message-based path
+            // would otherwise conclude — using the RECORDED message, never the
+            // message that came back out of Lua (which the script could have
+            // rewritten via its own `pcall`/`error` games).
+            //
+            // Known, accepted edge case (same precedent as the limit-breach flag
+            // in `./limits` winning unconditionally): a script that triggers a
+            // real denial, swallows it with its own `pcall`, and then throws its
+            // OWN unrelated error is still attributed to that genuine denial —
+            // `denials.last()` has no way to know the denial was "handled" by the
+            // script, and the failure genuinely did happen during this run. It
+            // can never work the other way around: a script can trigger zero
+            // denials and still forge `kind: 'capability'` — that path is now
+            // fully closed. If more than one denial is recorded in a single run
+            // (e.g. a caught GET denial followed by an uncaught POST tier-block),
+            // `last()` reports the LAST one, matching normal "most recent state
+            // wins" semantics for a single mutable JS closure variable.
+            const denial = denials.last();
+            if (denial) {
+                return {
+                    ok: false,
+                    error: {
+                        kind: 'capability',
+                        capability: denial.reason,
+                        message: denial.message,
+                    },
+                };
+            }
             return { ok: false, error: classifyRuntimeError(runResult.err) };
         }
         const finalized = finalizeMarshaledValue(runResult.value);
@@ -317,6 +365,24 @@ export async function runScript(options) {
         }
         return { ok: true, value: finalized.value };
     }
+    catch (err) {
+        // Backstop for the never-throws guarantee: every expected failure mode
+        // above returns before reaching here (limit breaches, capability
+        // denials, marshal rejections, ordinary runtime errors are all
+        // returned, not thrown). This catch exists for anything UNEXPECTED that
+        // throws synchronously inside the try — e.g. `finalizeMarshaledValue`
+        // recursing deep enough to overflow the JS call stack, which today is
+        // safe only INCIDENTALLY because wasmoon's own `getValue` conversion
+        // overflows first on sufficiently deep input (see the sandbox audit's
+        // finding F-1 "also recommended" note) — so that guarantee no longer
+        // depends on that ordering holding forever. Classified the same as any
+        // other unclassified failure: a plain `'runtime'` failure, never a raw
+        // throw out of `runScript`.
+        return {
+            ok: false,
+            error: { kind: 'runtime', message: describeError(err) },
+        };
+    }
     finally {
         limitHandle?.dispose();
         if (thread !== undefined && threadStackIndex !== undefined) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/lua",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Sandboxed Lua 5.4 (wasmoon) execution runtime for Mark's document scripting: an empty-env global whitelist, two-tier capability-gated net/cache/bundle access, instruction-count/wall-clock/memory limits, and depth/size-capped Lua<->JS marshaling.",
   "keywords": [
     "markdown",
@@ -44,8 +44,8 @@
     "lint": "eslint ."
   },
   "dependencies": {
-    "@markii/bundle": "0.1.0",
-    "@markii/runtime": "0.1.0",
+    "@markii/bundle": "0.3.0",
+    "@markii/runtime": "0.3.0",
     "wasmoon": "^1.16.0"
   }
 }