@markii/lua 0.12.1 → 0.13.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

@@ -422,7 +422,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 +438,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 +557,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.13.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.13.0",
+    "@markii/runtime": "^0.13.0",
     "wasmoon": "^1.16.0"
   }
 }