@markii/lua 0.12.1 → 0.14.0

package/dist/capabilities.d.ts

@@ -24,7 +24,7 @@ export interface CacheEntry {
 }
 /**
  * Host-provided cache primitive backing `cache.get(key, ttl, fn)`. Real
- * persistence (bundle `cache/`, IndexedDB, whatever the host uses) is the
+ * persistence (bundle `.cache/`, IndexedDB, whatever the host uses) is the
  * host's concern; this package only defines the read-if-fresh-else-run-fn
  * contract.
  */

package/dist/capabilities.js

@@ -198,63 +198,72 @@ export function buildCapabilities(config) {
     // rather than behind one combined condition — an earlier version of
     // this function nested POST/PATCH wiring inside "if GET is granted",
     // which silently produced no `net.post` at all for a POST-only grant.
+    //
+    // The `net` table itself, and every one of its three methods, is now
+    // ALWAYS wired, regardless of grants, provider wiring, or tier (GitHub
+    // capability-stub finding, batch 7 #47). Before this, an ungranted
+    // script saw a missing global (`net` itself omitted when nothing was
+    // granted, or a missing method when a specific host/verb wasn't) and
+    // failed with an ordinary Lua "attempt to index/call a nil value" —
+    // indistinguishable, from inside the script and from a host reading
+    // `runScript`'s outcome, from a plain typo. A denied capability and a
+    // typo must never look the same (see `./errors`'s module doc comment).
+    // Each method below performs its own grant/tier check and records a
+    // denial through `recordDenial` (the non-spoofable `CapabilityDenials`
+    // handle `sandbox.ts` reads) before throwing — never a typed error
+    // string, and never anything a script's own `error()` call could forge;
+    // see `./errors.ts`'s `CAPABILITY_ERROR_TAG` doc comment for why the
+    // message text itself must never become a classification signal. One
+    // side effect, expected and documented in CHANGELOG: a script that does
+    // `if net then ... end` to feature-detect now always sees a table.
     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 || netGrants.post.length > 0);
-    if (netTableNeeded) {
-        preludeParts.push('net = net or {}\n');
-    }
-    if (config.net && netGrants.get.length > 0) {
-        rawGlobals.__smd_net_get_raw = (async (url) => {
-            const host = hostnameOf(url);
-            if (!host || !netGrants.get.includes(host)) {
-                const message = `net access to host "${host ?? url}" not granted for GET`;
-                recordDenial('denied', message);
-                throw capabilityError(message);
-            }
-            const res = await callNetProvider(() => config.net.get(url));
-            if (res.body.length > maxFetchBytes) {
-                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 {
-                const message = `fetch response for "${url}" was not valid JSON`;
-                recordDenial('denied', message);
-                throw capabilityError(message);
-            }
-            // Depth/node budget, checked HERE on the plain parsed JS value and
-            // BEFORE the raw text is ever handed to Lua — see `./json-decode`'s
-            // doc comment (GitHub issue #6) for why decoding happens entirely in
-            // Lua, and `MarshalLimits`' doc comment above for why this reuses the
-            // same budget the return-value marshal walk already enforces.
-            const budgetCheck = checkJsonWithinLimits(parsed, marshalLimits);
-            if (!budgetCheck.ok) {
-                const message = `fetch response for "${url}" ${budgetCheck.message}`;
-                recordDenial('denied', message);
-                throw capabilityError(message);
-            }
-            // Hand back the RAW JSON TEXT, not the parsed JS value: any object or
-            // array crossing this JS->Lua boundary as-is would arrive in Lua as a
-            // wasmoon `js_proxy` userdata, not a genuine table (see
-            // `./json-decode`'s doc comment for the full mechanism and why that
-            // breaks `type()`/`#`/marshaling a nested return value, and silently
-            // raises on a `null` field read). Strings, unlike objects/arrays, are
-            // scalars and cross the boundary cleanly with no proxy involved; the
-            // prelude below decodes this text into a genuine Lua table entirely
-            // in Lua (`__smd_json_decode`, `./json-decode`).
-            return res.body;
-        });
-        ensureJsonDecodePrelude();
-        preludeParts.push(`
+    preludeParts.push('net = net or {}\n');
+    rawGlobals.__smd_net_get_raw = (async (url) => {
+        const host = hostnameOf(url);
+        if (!config.net || !host || !netGrants.get.includes(host)) {
+            const message = `net access to host "${host ?? url}" not granted for GET`;
+            recordDenial('denied', message);
+            throw capabilityError(message);
+        }
+        const res = await callNetProvider(() => config.net.get(url));
+        if (res.body.length > maxFetchBytes) {
+            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 {
+            const message = `fetch response for "${url}" was not valid JSON`;
+            recordDenial('denied', message);
+            throw capabilityError(message);
+        }
+        // Depth/node budget, checked HERE on the plain parsed JS value and
+        // BEFORE the raw text is ever handed to Lua — see `./json-decode`'s
+        // doc comment (GitHub issue #6) for why decoding happens entirely in
+        // Lua, and `MarshalLimits`' doc comment above for why this reuses the
+        // same budget the return-value marshal walk already enforces.
+        const budgetCheck = checkJsonWithinLimits(parsed, marshalLimits);
+        if (!budgetCheck.ok) {
+            const message = `fetch response for "${url}" ${budgetCheck.message}`;
+            recordDenial('denied', message);
+            throw capabilityError(message);
+        }
+        // Hand back the RAW JSON TEXT, not the parsed JS value: any object or
+        // array crossing this JS->Lua boundary as-is would arrive in Lua as a
+        // wasmoon `js_proxy` userdata, not a genuine table (see
+        // `./json-decode`'s doc comment for the full mechanism and why that
+        // breaks `type()`/`#`/marshaling a nested return value, and silently
+        // raises on a `null` field read). Strings, unlike objects/arrays, are
+        // scalars and cross the boundary cleanly with no proxy involved; the
+        // prelude below decodes this text into a genuine Lua table entirely
+        // in Lua (`__smd_json_decode`, `./json-decode`).
+        return res.body;
+    });
+    ensureJsonDecodePrelude();
+    preludeParts.push(`
 local __smd_net_get = __smd_net_get_raw
 -- Captured into a local HERE, at prelude-definition time (this whole
 -- prelude runs once, before any untrusted script code) -- NOT resolved as
@@ -268,39 +277,43 @@ local __smd_net_get_json_decode = __smd_json_decode
 __smd_net_get_raw = nil
 net.fetch_json = function(url) return __smd_net_get_json_decode(__smd_net_get(url):await()) end
 `);
-    }
-    // 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 &&
-        netGrants.post.length > 0) {
-        rawGlobals.__smd_net_post_raw = (async (url, body) => {
-            const host = hostnameOf(url);
-            if (!host || !netGrants.post.includes(host)) {
-                const message = `net access to host "${host ?? url}" not granted for POST`;
-                recordDenial('denied', message);
-                throw capabilityError(message);
-            }
-            const res = await callNetProvider(() => config.net.post(url, body));
-            // As with `net.fetch_json` above (GitHub issue #6): a plain JS object
-            // (even one this shallow) crosses into Lua as a `js_proxy` userdata,
-            // not a genuine table. `status`/`body` are both scalars, so instead
-            // of proxying the whole response object, resolve with a
-            // `LuaMultiReturn` — `:await()` recognizes that and expands it into
-            // TWO separate Lua return values (see `wasmoon`'s promise
-            // `await`/`MultiReturn` handling) — and let the trusted prelude below
-            // rebuild a real `{status=..., body=...}` table out of ordinary Lua
-            // table-constructor syntax.
-            return LuaMultiReturn.of(res.status, res.body);
-        });
-        preludeParts.push(`
+    // POST/PATCH are effectful. Wired unconditionally like GET above: the
+    // raw handler itself decides, in this order, whether the call is
+    // ungranted (`'denied'`), tier-forbidden (`'tier-blocked'`, only reached
+    // once the host/verb IS granted, under the read-only 'auto' tier — spec
+    // §8: "An effectful call under an auto trigger fails cleanly"), or has
+    // no provider wired for that verb at all (`'denied'`, since the host
+    // never offered it), before ever reaching `config.net.post`/`.patch`.
+    rawGlobals.__smd_net_post_raw = (async (url, body) => {
+        const host = hostnameOf(url);
+        if (!host || !netGrants.post.includes(host)) {
+            const message = `net access to host "${host ?? url}" not granted for POST`;
+            recordDenial('denied', message);
+            throw capabilityError(message);
+        }
+        if (config.tier === 'auto') {
+            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);
+        }
+        if (!config.net?.post) {
+            const message = `net access to host "${host}" not granted for POST`;
+            recordDenial('denied', message);
+            throw capabilityError(message);
+        }
+        const res = await callNetProvider(() => config.net.post(url, body));
+        // As with `net.fetch_json` above (GitHub issue #6): a plain JS object
+        // (even one this shallow) crosses into Lua as a `js_proxy` userdata,
+        // not a genuine table. `status`/`body` are both scalars, so instead
+        // of proxying the whole response object, resolve with a
+        // `LuaMultiReturn` — `:await()` recognizes that and expands it into
+        // TWO separate Lua return values (see `wasmoon`'s promise
+        // `await`/`MultiReturn` handling) — and let the trusted prelude below
+        // rebuild a real `{status=..., body=...}` table out of ordinary Lua
+        // table-constructor syntax.
+        return LuaMultiReturn.of(res.status, res.body);
+    });
+    preludeParts.push(`
 local __smd_net_post = __smd_net_post_raw
 __smd_net_post_raw = nil
 net.post = function(url, body)
@@ -308,46 +321,29 @@ net.post = function(url, body)
   return { status = status, body = respBody }
 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)';
+    rawGlobals.__smd_net_patch_raw = (async (url, body) => {
+        const host = hostnameOf(url);
+        if (!host || !netGrants.post.includes(host)) {
+            const message = `net access to host "${host ?? url}" not granted for PATCH`;
+            recordDenial('denied', message);
+            throw capabilityError(message);
+        }
+        if (config.tier === 'auto') {
+            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_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' &&
-        config.net?.patch &&
-        netGrants.post.length > 0) {
-        rawGlobals.__smd_net_patch_raw = (async (url, body) => {
-            const host = hostnameOf(url);
-            if (!host || !netGrants.post.includes(host)) {
-                const message = `net access to host "${host ?? url}" not granted for PATCH`;
-                recordDenial('denied', message);
-                throw capabilityError(message);
-            }
-            const res = await callNetProvider(() => config.net.patch(url, body));
-            // Same fix as `net.post` above (GitHub issue #6) — see that block's
-            // comment for the full mechanism.
-            return LuaMultiReturn.of(res.status, res.body);
-        });
-        preludeParts.push(`
+        }
+        if (!config.net?.patch) {
+            const message = `net access to host "${host}" not granted for PATCH`;
+            recordDenial('denied', message);
+            throw capabilityError(message);
+        }
+        const res = await callNetProvider(() => config.net.patch(url, body));
+        // Same fix as `net.post` above (GitHub issue #6) — see that block's
+        // comment for the full mechanism.
+        return LuaMultiReturn.of(res.status, res.body);
+    });
+    preludeParts.push(`
 local __smd_net_patch = __smd_net_patch_raw
 __smd_net_patch_raw = nil
 net.patch = function(url, body)
@@ -355,23 +351,6 @@ net.patch = function(url, body)
   return { status = status, body = respBody }
 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 --------------------------------------------------------------
     // cache.get is implemented ENTIRELY IN LUA (see the prelude below),
     // calling the script-provided `fn` as a normal Lua-to-Lua call. This is
@@ -422,7 +401,7 @@ net.patch = function(url, body) return __smd_net_patch_blocked(url, body):await(
     //     JSON-safe result is handed to `config.cache!.set` — so
     //     `CacheEntry.value`'s STORAGE shape is unchanged (still whatever
     //     plain value the host's `CacheProvider` already expects; e.g. a
-    //     bundle's `cache/*.json` file), and a script's own scalar values
+    //     bundle's `.cache/*.json` file), and a script's own scalar values
     //     (numbers, strings, booleans) round-trip exactly as before.
     //   - Either enforcement failing raises the existing, already-classified
     //     `MARSHAL_ERROR_TAG` error (`sandbox.ts` already recognizes it as
@@ -438,7 +417,7 @@ net.patch = function(url, body) return __smd_net_patch_blocked(url, body):await(
             // to text and handed to Lua — mirrors `net.fetch_json`'s own
             // pre-check exactly (adversarial finding B2). A host-stored value is
             // exactly as untrusted as a remote fetch body — a bundle's
-            // `cache/*.json` file, for instance, can be edited by anything with
+            // `.cache/*.json` file, for instance, can be edited by anything with
             // write access to the bundle, not just this sandbox's own WRITE side
             // below — so without this check, a 300k-element cached array reached
             // the script completely uncapped even though the FETCH path was
@@ -557,7 +536,7 @@ end
     }
     // --- bundle -------------------------------------------------------------
     // Delegates entirely to the injected `ScriptView` (`@markii/bundle`), which
-    // already enforces the path-jail and the read/write:cache/ split (spec
+    // 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` (a tier-blocked stub under 'auto' — read-only tier) and
     // the byte<->Lua-string conversion.

package/dist/index.d.ts

@@ -8,6 +8,8 @@ export type { CacheEntry, CacheProvider, CapabilityConfig, CapabilityDenial, Cap
 export { DEFAULT_MAX_FETCH_BYTES, bytesToLuaString, buildCapabilities, isNetProviderDenial, luaStringToBytes, netProviderDenial, } from './capabilities.js';
 export type { DocConfig } from './doc.js';
 export { buildDoc } from './doc.js';
+export type { JsonTableConfig } from './json-table.js';
+export { buildJsonTable } from './json-table.js';
 export type { MarshalLimits } from './marshal.js';
 export { DEFAULT_MARSHAL_LIMITS, buildMarshalPrelude, checkJsonWithinLimits, finalizeMarshaledValue, wrapUserCode, } from './marshal.js';
 export type { PackModuleResolver, RequireConfig } from './require.js';

package/dist/index.js

@@ -8,6 +8,7 @@ export { ALLOWED_GLOBALS, DENIED_GLOBALS, createEmptyLuaEngine, } from './global
 export { DEFAULT_LIMITS, installLimits } from './limits.js';
 export { DEFAULT_MAX_FETCH_BYTES, bytesToLuaString, buildCapabilities, isNetProviderDenial, luaStringToBytes, netProviderDenial, } from './capabilities.js';
 export { buildDoc } from './doc.js';
+export { buildJsonTable } from './json-table.js';
 export { DEFAULT_MARSHAL_LIMITS, buildMarshalPrelude, checkJsonWithinLimits, finalizeMarshaledValue, wrapUserCode, } from './marshal.js';
 export { buildRequire } from './require.js';
 export { runScript } from './sandbox.js';

package/dist/json-table.d.ts

@@ -0,0 +1,88 @@
+import { type MarshalLimits } from './marshal.js';
+export interface JsonTableConfig {
+    /**
+     * Depth/node budget applied to a `json.decode` input and, via
+     * `__smd_marshal_root`, to a `json.encode` value. The SAME `MarshalLimits`
+     * `./sandbox` already uses for the marshal prelude and `./capabilities`
+     * uses for `net.fetch_json` -- never a second, independently-tuned cap.
+     */
+    limits: MarshalLimits;
+    /**
+     * Byte-size cap on the TEXT handed to `json.decode`, checked before the
+     * text is JSON-parsed at all. The SAME cap `net.fetch_json` applies to a
+     * fetched response body (`./capabilities`' `maxFetchBytes`), reused here
+     * rather than forked.
+     */
+    maxFetchBytes: number;
+}
+/**
+ * Builds the raw JS globals and trusted Lua prelude for the `json` table:
+ * `json.decode(text)` and `json.encode(value)` (GitHub issue #40, slice 3a).
+ *
+ * `json` is pure computation with no I/O -- it never touches the network,
+ * the bundle filesystem, or the clock -- so `./sandbox` injects this
+ * unconditionally, for every tier, with no capability grant required. This
+ * mirrors how `./marshal`'s and `./doc`'s preludes are already injected
+ * unconditionally; `json` joins that same "always present" set rather than
+ * being wired through `./capabilities`' tier/grant machinery, which exists
+ * specifically to gate effectful or ambient-authority operations this
+ * table has none of.
+ *
+ * ## `json.decode`: reuses the EXISTING decoder and EXISTING budget
+ *
+ * The actual parse is `./json-decode`'s `__smd_json_decode` -- the same
+ * trusted, in-Lua JSON decoder `net.fetch_json`/`cache.get` already use in
+ * `./capabilities` (see that module's doc comment for why decoding must
+ * happen entirely in Lua rather than trusting wasmoon's own JS-object
+ * conversion). This function never writes a second decoder.
+ *
+ * Before that decoder ever sees the text, a JS-side precheck applies the
+ * exact same two-part budget `net.fetch_json` applies to a fetched body:
+ * the `maxFetchBytes` byte-size cap (an ordinary, untagged `error()`,
+ * `kind: 'runtime'` -- no `ScriptMarshalReason` value fits "too many
+ * bytes"), and `./marshal`'s `checkJsonWithinLimits` (the very function
+ * `./capabilities` calls) against the `JSON.parse`d value, tagged
+ * `MARK_MARSHAL:depth`/`MARK_MARSHAL:nodes` so `./sandbox`'s
+ * `classifyRuntimeError` reports it as `kind: 'marshal'`, `reason: 'depth'
+ * | 'nodes'` -- the same classification a `json.encode` budget violation
+ * gets (see below), so a script sees one consistent failure shape for "too
+ * deep or too wide" regardless of which direction it happened. Text that
+ * fails to `JSON.parse` at all is NOT diagnosed here in JS: it is
+ * handed straight to `__smd_json_decode`, which raises its own "malformed"
+ * error -- duplicating that diagnosis in two places risks the two
+ * disagreeing, and the Lua decoder's message is the one already documented.
+ *
+ * ## `json.encode`: reuses the EXISTING marshal walk
+ *
+ * `json.encode(value)` runs `value` through `__smd_marshal_root`
+ * (`./marshal`'s `buildMarshalPrelude`, already injected once per engine
+ * before this prelude runs) -- the SAME depth/node-capped, cycle-detecting,
+ * type-checking walk a script's own top-level return value already goes
+ * through. No second walk is written. The capped, marker-tagged result then
+ * crosses to JS as a single bounded function argument (safe by construction:
+ * the walk has already capped it, exactly as `./capabilities`' `cache.get`
+ * write path already relies on for the same reason), where
+ * `finalizeMarshaledValue` -- the same JS-side pass `./sandbox` runs on a
+ * script's return value -- strips the array marker and rejects a
+ * non-finite number, before the result is `JSON.stringify`d. A cycle,
+ * excess depth/nodes, a non-string table key, or a function/userdata/thread
+ * all raise the walk's existing `MARK_MARSHAL:<reason>` tag, so `json.encode`
+ * failures classify exactly like a script's own return-value marshal
+ * failures: `kind: 'marshal'`, with `reason` one of `./marshal`'s existing
+ * `ScriptMarshalReason` values.
+ *
+ * ## Rebinding safety
+ *
+ * `json.decode`/`json.encode` themselves close over `type`, `error`,
+ * `__smd_json_decode`, and `__smd_marshal_root` captured into locals AT
+ * PRELUDE-DEFINITION TIME -- before any untrusted script code runs -- so a
+ * later script reassigning any of those globals (or `json` itself) cannot
+ * neuter the type check or reach past the reused decoder/marshal walk. This
+ * is the same discipline `./json-decode` (finding A1) and `./capabilities`
+ * (findings A2/D1) already apply to their own internal calls into these
+ * exact two functions.
+ */
+export declare function buildJsonTable(config: JsonTableConfig): {
+    rawGlobals: Record<string, (...args: never[]) => Promise<unknown>>;
+    preludeLua: string;
+};

package/dist/json-table.js

@@ -0,0 +1,151 @@
+import { MARSHAL_ERROR_TAG } from './errors.js';
+import { buildJsonDecodePrelude } from './json-decode.js';
+import { checkJsonWithinLimits, finalizeMarshaledValue, } from './marshal.js';
+/**
+ * Builds the raw JS globals and trusted Lua prelude for the `json` table:
+ * `json.decode(text)` and `json.encode(value)` (GitHub issue #40, slice 3a).
+ *
+ * `json` is pure computation with no I/O -- it never touches the network,
+ * the bundle filesystem, or the clock -- so `./sandbox` injects this
+ * unconditionally, for every tier, with no capability grant required. This
+ * mirrors how `./marshal`'s and `./doc`'s preludes are already injected
+ * unconditionally; `json` joins that same "always present" set rather than
+ * being wired through `./capabilities`' tier/grant machinery, which exists
+ * specifically to gate effectful or ambient-authority operations this
+ * table has none of.
+ *
+ * ## `json.decode`: reuses the EXISTING decoder and EXISTING budget
+ *
+ * The actual parse is `./json-decode`'s `__smd_json_decode` -- the same
+ * trusted, in-Lua JSON decoder `net.fetch_json`/`cache.get` already use in
+ * `./capabilities` (see that module's doc comment for why decoding must
+ * happen entirely in Lua rather than trusting wasmoon's own JS-object
+ * conversion). This function never writes a second decoder.
+ *
+ * Before that decoder ever sees the text, a JS-side precheck applies the
+ * exact same two-part budget `net.fetch_json` applies to a fetched body:
+ * the `maxFetchBytes` byte-size cap (an ordinary, untagged `error()`,
+ * `kind: 'runtime'` -- no `ScriptMarshalReason` value fits "too many
+ * bytes"), and `./marshal`'s `checkJsonWithinLimits` (the very function
+ * `./capabilities` calls) against the `JSON.parse`d value, tagged
+ * `MARK_MARSHAL:depth`/`MARK_MARSHAL:nodes` so `./sandbox`'s
+ * `classifyRuntimeError` reports it as `kind: 'marshal'`, `reason: 'depth'
+ * | 'nodes'` -- the same classification a `json.encode` budget violation
+ * gets (see below), so a script sees one consistent failure shape for "too
+ * deep or too wide" regardless of which direction it happened. Text that
+ * fails to `JSON.parse` at all is NOT diagnosed here in JS: it is
+ * handed straight to `__smd_json_decode`, which raises its own "malformed"
+ * error -- duplicating that diagnosis in two places risks the two
+ * disagreeing, and the Lua decoder's message is the one already documented.
+ *
+ * ## `json.encode`: reuses the EXISTING marshal walk
+ *
+ * `json.encode(value)` runs `value` through `__smd_marshal_root`
+ * (`./marshal`'s `buildMarshalPrelude`, already injected once per engine
+ * before this prelude runs) -- the SAME depth/node-capped, cycle-detecting,
+ * type-checking walk a script's own top-level return value already goes
+ * through. No second walk is written. The capped, marker-tagged result then
+ * crosses to JS as a single bounded function argument (safe by construction:
+ * the walk has already capped it, exactly as `./capabilities`' `cache.get`
+ * write path already relies on for the same reason), where
+ * `finalizeMarshaledValue` -- the same JS-side pass `./sandbox` runs on a
+ * script's return value -- strips the array marker and rejects a
+ * non-finite number, before the result is `JSON.stringify`d. A cycle,
+ * excess depth/nodes, a non-string table key, or a function/userdata/thread
+ * all raise the walk's existing `MARK_MARSHAL:<reason>` tag, so `json.encode`
+ * failures classify exactly like a script's own return-value marshal
+ * failures: `kind: 'marshal'`, with `reason` one of `./marshal`'s existing
+ * `ScriptMarshalReason` values.
+ *
+ * ## Rebinding safety
+ *
+ * `json.decode`/`json.encode` themselves close over `type`, `error`,
+ * `__smd_json_decode`, and `__smd_marshal_root` captured into locals AT
+ * PRELUDE-DEFINITION TIME -- before any untrusted script code runs -- so a
+ * later script reassigning any of those globals (or `json` itself) cannot
+ * neuter the type check or reach past the reused decoder/marshal walk. This
+ * is the same discipline `./json-decode` (finding A1) and `./capabilities`
+ * (findings A2/D1) already apply to their own internal calls into these
+ * exact two functions.
+ */
+export function buildJsonTable(config) {
+    const { limits, maxFetchBytes } = config;
+    const rawGlobals = {};
+    rawGlobals.__smd_json_decode_precheck_raw = (async (text) => {
+        if (typeof text === 'string' && text.length > maxFetchBytes) {
+            // No `ScriptMarshalReason` value fits "too many bytes" (that taxonomy
+            // is depth/nodes/cycle/type/key-type/non-finite-number/nul-byte, none
+            // of which is a byte-size cap), so this is left untagged: an ordinary
+            // Lua error, classified `kind: 'runtime'` by `./sandbox` like any
+            // other `error()` call. It is still a clean, bounded, descriptive
+            // failure -- never a hang, never a crash -- which is what matters.
+            throw new Error(`json.decode: input exceeds the ${maxFetchBytes}-byte limit`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            // Not valid JSON text: let `__smd_json_decode` (the Lua decoder)
+            // raise its own "malformed" error rather than diagnosing this twice,
+            // in two places, with two possibly-inconsistent messages.
+            return true;
+        }
+        const check = checkJsonWithinLimits(parsed, limits);
+        if (!check.ok) {
+            throw new Error(`${MARSHAL_ERROR_TAG}:${check.reason}: json.decode input ${check.message}`);
+        }
+        return true;
+    });
+    rawGlobals.__smd_json_encode_raw = (async (marshaledValue) => {
+        const finalized = finalizeMarshaledValue(marshaledValue);
+        if (!finalized.ok) {
+            throw new Error(`${MARSHAL_ERROR_TAG}:${finalized.reason}`);
+        }
+        const text = JSON.stringify(finalized.value);
+        // `JSON.stringify` only returns `undefined` for a value it cannot
+        // represent -- already excluded by `finalizeMarshaledValue` above -- so
+        // this is a defensive fallback that is never expected to trigger.
+        return text === undefined ? 'null' : text;
+    });
+    const preludeLua = `
+${buildJsonDecodePrelude(limits)}
+
+-- Captured into locals HERE, at prelude-definition time -- see the module
+-- doc comment's "Rebinding safety" section.
+local __smd_json_type = type
+local __smd_json_error = error
+local __smd_json_decode_precheck = __smd_json_decode_precheck_raw
+local __smd_json_encode_finish = __smd_json_encode_raw
+local __smd_json_decode_fn = __smd_json_decode
+local __smd_json_marshal_root = __smd_marshal_root
+__smd_json_decode_precheck_raw = nil
+__smd_json_encode_raw = nil
+-- \`__smd_json_decode\` (defined by the injected \`./json-decode\` prelude
+-- above) is only ever needed as a GLOBAL long enough for callers to capture
+-- it into their own local -- exactly like \`__smd_net_get_json_decode\` and
+-- \`__smd_cache_json_decode\` already do in \`./capabilities\`. This prelude
+-- runs AFTER any of those (see \`./sandbox\`'s injection order), so every
+-- earlier consumer has already captured its own reference by this point;
+-- nilling the global here keeps \`json\` from being the run that leaves a
+-- private \`__smd_\` name reachable on every single run (it is now injected
+-- UNCONDITIONALLY, unlike \`net\`/\`cache\`, which only define this global
+-- when actually configured) -- see the pass-3 residue probes
+-- (\`require-pass3.probe.test.ts\`, \`doc.probe.test.ts\`), which assert NO
+-- \`__smd_\`-prefixed global survives except \`__smd_marshal_root\`.
+__smd_json_decode = nil
+
+json = json or {}
+json.decode = function(text)
+  if __smd_json_type(text) ~= "string" then
+    __smd_json_error("json.decode expects a string argument")
+  end
+  __smd_json_decode_precheck(text):await()
+  return __smd_json_decode_fn(text)
+end
+json.encode = function(value)
+  return __smd_json_encode_finish(__smd_json_marshal_root(value)):await()
+end
+`;
+    return { rawGlobals, preludeLua };
+}

package/dist/sandbox.d.ts

@@ -63,7 +63,10 @@ export type RunScriptResult = {
  *    the real `require` global, sharing the same `bundle`/denial-recording
  *    wiring (§8's bundle-local and pack-namespaced module sources).
  * 4. `./marshal` — inject the trusted node/depth-capped marshal walk that
- *    the wrapped user code's return value is piped through.
+ *    the wrapped user code's return value is piped through, then
+ *    `./json-table` — the `json.decode`/`json.encode` table, unconditional
+ *    and ungated (pure computation, no capability grant), reusing that
+ *    same marshal walk and `./json-decode`'s existing decoder.
  * 5. A dedicated child thread (NOT `engine.doString`, which creates its
  *    own internal thread we'd have no handle to — see `./limits`'s "hooks
  *    are per-thread" note) gets the instruction/wall-clock hook installed,

package/dist/sandbox.js

@@ -1,8 +1,9 @@
 import { LuaReturn } from 'wasmoon';
-import { buildCapabilities, } from './capabilities.js';
+import { buildCapabilities, DEFAULT_MAX_FETCH_BYTES, } from './capabilities.js';
 import { buildDoc } from './doc.js';
 import { MARSHAL_ERROR_TAG, ScriptLimitError } from './errors.js';
 import { createEmptyLuaEngine } from './globals.js';
+import { buildJsonTable } from './json-table.js';
 import { DEFAULT_LIMITS, installLimits } from './limits.js';
 import { buildMarshalPrelude, DEFAULT_MARSHAL_LIMITS, finalizeMarshaledValue, wrapUserCode, } from './marshal.js';
 import { buildRequire } from './require.js';
@@ -109,6 +110,20 @@ function extractMarshalReason(message) {
             return 'key-type';
         case 'nul-byte':
             return 'nul-byte';
+        case 'non-finite-number':
+            // Unlike the other cases above (all raised from INSIDE the Lua-side
+            // `__smd_marshal` walk itself), a non-finite number is normally
+            // caught by `finalizeMarshaledValue` running directly in JS on a
+            // successful run's already-returned value -- it never crosses back
+            // through Lua as a thrown, tagged error on that path, so this case
+            // was unreached before `./json-table` existed. `json.encode` reuses
+            // `finalizeMarshaledValue` itself (the same JS-side check, the same
+            // reason) but calls it from inside a host function invoked FROM Lua,
+            // so its rejection DOES round-trip through a thrown Lua error and
+            // land here -- this case keeps that reused reason classified
+            // identically to the return-value path, instead of falling through
+            // to the generic 'type' default.
+            return 'non-finite-number';
         case 'type':
             return 'type';
         default:
@@ -179,7 +194,10 @@ function classifyRuntimeError(err) {
  *    the real `require` global, sharing the same `bundle`/denial-recording
  *    wiring (§8's bundle-local and pack-namespaced module sources).
  * 4. `./marshal` — inject the trusted node/depth-capped marshal walk that
- *    the wrapped user code's return value is piped through.
+ *    the wrapped user code's return value is piped through, then
+ *    `./json-table` — the `json.decode`/`json.encode` table, unconditional
+ *    and ungated (pure computation, no capability grant), reusing that
+ *    same marshal walk and `./json-decode`'s existing decoder.
  * 5. A dedicated child thread (NOT `engine.doString`, which creates its
  *    own internal thread we'd have no handle to — see `./limits`'s "hooks
  *    are per-thread" note) gets the instruction/wall-clock hook installed,
@@ -261,6 +279,19 @@ export async function runScript(options) {
             throw new Error(`sandbox assembly left a code-loading primitive reachable (${String(loadResidue)}); refusing to run`);
         }
         await engine.doString(buildMarshalPrelude(marshalLimits));
+        // ./json-table: the `json` table (GitHub issue #40, slice 3a). Pure
+        // computation, no I/O -- injected unconditionally, for every tier, with
+        // no capability grant, same as the marshal/doc preludes below and
+        // above it. Wired AFTER the marshal prelude because `json.encode`
+        // reuses `__smd_marshal_root`, defined by that prelude.
+        const jsonTable = buildJsonTable({
+            limits: marshalLimits,
+            maxFetchBytes: options.maxFetchBytes ?? DEFAULT_MAX_FETCH_BYTES,
+        });
+        for (const [name, fn] of Object.entries(jsonTable.rawGlobals)) {
+            engine.global.set(name, fn);
+        }
+        await engine.doString(jsonTable.preludeLua);
         // ./doc: the note-scoped read-only view (GitHub issue #33). Wired
         // AFTER the marshal prelude and, like `require`, wired unconditionally
         // — with no `options.doc` it is an empty listing, never an absent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markii/lua",
-  "version": "0.12.1",
+  "version": "0.14.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.12.1",
-    "@markii/runtime": "^0.12.1",
+    "@markii/bundle": "^0.14.0",
+    "@markii/runtime": "^0.14.0",
     "wasmoon": "^1.16.0"
   }
 }