@markii/lua 0.1.0

package/dist/globals.js

@@ -0,0 +1,284 @@
+import { LuaFactory, LuaLibraries } from 'wasmoon';
+/**
+ * Builds the *empty* Lua environment (spec §10: "Scripts run in an empty
+ * Lua environment: no `os`, no `io`, no `require`, no globals except the
+ * capability functions the host injects").
+ *
+ * Strategy: `openStandardLibs: false` means wasmoon never calls
+ * `luaL_openlibs` at all — `os`, `io`, `package`, `debug`, and `coroutine`
+ * are never linked into this Lua state's globals table in the first place.
+ * This is strictly stronger than "load everything, then delete the bad
+ * parts": there is nothing to delete because the C library that would have
+ * installed them was never invoked, so there is no back door (metatable,
+ * `_ENV`, or otherwise) that recovers them — recovering a name that was
+ * never assigned into the (single, shared) globals table is not possible in
+ * Lua regardless of what handle a script obtains on that table.
+ *
+ * We then hand-load exactly four libraries via `Global.loadLibrary` (the
+ * per-library `luaopen_*` wasmoon exposes) and immediately run a trusted
+ * "scrub" prelude that nils out the specific names, within those four
+ * libraries, that are still dangerous. Every inclusion/exclusion below is
+ * commented with why.
+ */
+/**
+ * Libraries linked into the sandbox, and why:
+ * - Base (`_G`)  — required: this is where `pcall`/`xpcall`/`error`/
+ *   `assert`/`type`/`tostring`/`tonumber`/`pairs`/`ipairs`/`next`/`select`
+ *   live in stock Lua 5.4. There's no way to get these without opening
+ *   Base, so Base is opened and then aggressively pruned (see below) —
+ *   everything Base brings that ISN'T on the whitelist gets nil'd out by
+ *   the scrub prelude.
+ * - String  — string manipulation is core to "fetch JSON, format a label"
+ *   scripts; pruned of `string.dump` only (see SCRUB_PRELUDE).
+ * - Table   — `table.insert/remove/concat/sort/pack/unpack/move`: no
+ *   member of this library reads/writes anything outside the table passed
+ *   to it, so the whole library is safe as-is; nothing pruned.
+ * - Math    — pure numeric functions (including `math.random`/
+ *   `math.randomseed` — a script influencing its own PRNG seed cannot
+ *   reach anything outside its own arithmetic); nothing pruned.
+ *
+ * NOT linked, and why (spec §10 threat model: the script is hostile):
+ * - Coroutine — `coroutine.*` would let a script create additional Lua
+ *   threads it controls directly. We already run the whole script on a
+ *   dedicated child thread and drive `resume`/`yield` ourselves (for the
+ *   capability await bridge, `./capabilities`, and the instruction-count
+ *   hook, `./limits`); handing the script its own `coroutine.create` is
+ *   unnecessary for the documented host API and only adds surface area
+ *   (e.g. spawning coroutines to dodge the hook's per-thread installation
+ *   — see the `./limits` doc comment on why hooks are per-thread).
+ * - IO, OS   — filesystem/process/env/clock access. The bundle-scoped
+ *   filesystem (§11) is the ONLY filesystem a script gets, via the
+ *   injected `bundle.*` capability table (`./capabilities`), never real
+ *   `io`.
+ * - Package  — `package.loadlib`/`package.cpath` is exactly "load a native
+ *   C module", meaningless (and dangerous, if it somehow resolved) in a
+ *   WASM sandbox with no real filesystem; `require` itself is intentionally
+ *   not wired to it either (see `./require`).
+ * - Debug    — `debug.getmetatable`/`debug.getupvalue`/`debug.sethook`
+ *   are a complete metatable/upvalue/hook bypass of every other
+ *   restriction in this file. Never loaded.
+ * - UTF8     — not on the documented host API surface; omitted by default
+ *   deny (a script working with byte strings and `string.*` covers the
+ *   documented use cases). Add it if a real need shows up — it carries no
+ *   special risk (pure string library), it just wasn't asked for.
+ */
+const LIBRARIES = [
+    LuaLibraries.Base,
+    LuaLibraries.String,
+    LuaLibraries.Table,
+    LuaLibraries.Math,
+];
+/**
+ * Runs once per fresh engine, before any capability table or user code is
+ * injected. Mutates the real `string` table object in place (`string.dump
+ * = nil`) rather than replacing the `string` global — the metatable that
+ * makes `("x"):upper()` work points at this same table object, so deleting
+ * the field this way removes both `string.dump(...)` AND `("x"):dump()` in
+ * one move, and can't be un-done by anything a script can reach (no
+ * `getmetatable` is exposed — see below — so a script cannot even inspect,
+ * let alone rewrite, that metatable).
+ *
+ * Base-library names removed, each independently a documented sandbox
+ * escape or ambient-authority primitive:
+ * - `load`, `loadstring`, `loadfile`, `dofile` — compile/run arbitrary
+ *   source or bytecode text at runtime; the entire point of §10 is that
+ *   the ONLY code that ever runs is the one chunk the host handed in.
+ *   `lua_load` also accepts precompiled bytecode with no source-text
+ *   validation — bytecode is not sandboxed the way source is (it can
+ *   encode out-of-range opcodes that crash or exploit the VM), which is
+ *   also why `string.dump` (bytecode *production*) is removed below.
+ * - `collectgarbage` — its `"count"` argument is a harmless memory query
+ *   but other arguments (`"stop"`, `"generational"`, `"incremental"`) let
+ *   a script retune the collector as a denial-of-service knob against the
+ *   memory cap installed in `./sandbox`; removed wholesale rather than
+ *   allow-listing a sub-mode we don't need.
+ * - `rawget`, `rawset`, `rawequal`, `rawlen` — bypass `__index`/
+ *   `__newindex`/`__eq`/`__len` metamethods. Nothing in this sandbox
+ *   currently relies on metamethod interception for security (we don't
+ *   proxy the capability tables — see `./capabilities`), but keeping raw
+ *   accessors off by default costs the sandbox nothing and closes off
+ *   that category of future bug entirely: default-deny.
+ * - `getmetatable`, `setmetatable` — `getmetatable("")` is the standard
+ *   way to reach the shared string metatable and, with `setmetatable`,
+ *   rewrite it — potentially restoring a removed method or corrupting
+ *   `__index` for every string literal for the rest of the run. Removing
+ *   both closes this off completely (there is then no Lua-reachable way
+ *   to obtain any metatable at all, since `debug.getmetatable` is also
+ *   unavailable — `debug` is never loaded).
+ * - `print`, `warn` — write to the process's real stdout/stderr. Not a
+ *   sandbox-escape by itself, but not on the documented host API surface
+ *   (scripts communicate by *returning a value*, per spec §8 — "Scripts
+ *   return values; they never write into the document body") and a
+ *   console/stderr channel is an unnecessary side channel; default-deny.
+ * - `_G`, `_VERSION` — `_G` is merely the *name* Base binds to the real
+ *   globals table for convenience; removing the name does not remove the
+ *   table (every chunk's `_ENV` upvalue still refers to it — that's
+ *   unavoidable in Lua and is exactly why every prune in this file is done
+ *   by MUTATING the real table/globals rather than rebinding a name to
+ *   something else). What matters is that the *table itself* never had
+ *   `os`/`io`/`debug`/`package`/`load`/etc. as members to begin with, so
+ *   reaching it via `_ENV` recovers nothing. `_VERSION` is a harmless
+ *   info leak with no use on the documented API; removed for
+ *   default-deny consistency.
+ *
+ * Explicitly KEPT from Base (each is on the DoD-mandated whitelist):
+ * `tonumber`, `tostring`, `type`, `ipairs`, `pairs`, `next`, `select`,
+ * `error`, `assert`, `pcall`, `xpcall`. NOTE: `xpcall` is kept in name only —
+ * the C-level `xpcall` Base actually provides is REPLACED by a pure-Lua
+ * reimplementation (`XPCALL_REIMPLEMENTATION` below, run as part of this
+ * prelude) that closes a host-deadlock the C version has under this
+ * sandbox's limits hook; see that constant's doc comment for the full
+ * mechanism and empirical evidence.
+ *
+ * `unpack`/`table.unpack`: Lua 5.4 (this build, no 5.1-compat flag) never
+ * defines a *global* `unpack` — only `table.unpack` exists in stock 5.4,
+ * confirmed empirically (a fresh engine with Base+Table loaded has no
+ * global `unpack`). We do not synthesize one; `table.unpack` is exposed as
+ * part of the (fully kept) Table library and is the documented spelling.
+ */
+/**
+ * Replaces the C-level \`xpcall\` with a pure-Lua reimplementation built on
+ * \`pcall\`.
+ *
+ * ## Why: the C \`xpcall\` deadlocks the host under the limits hook
+ *
+ * \`./limits\`' instruction/wall-clock interrupt works by having the JS
+ * count-hook call \`thread.lua.lua_error(...)\` — a longjmp — from inside the
+ * hook. That is an ordinary Lua error, so \`pcall\` and \`xpcall\` both catch
+ * it (this is exactly what makes the "script's own pcall can't swallow the
+ * interrupt" guarantee in \`./limits\` need the out-of-band JS flag in the
+ * first place). With \`pcall\` that is harmless: no user code runs in
+ * response, the call just returns \`false, err\` and the JS-side breach flag
+ * still forces the run to a hard failure. But the C \`xpcall\` INVOKES THE
+ * USER'S MESSAGE HANDLER as part of unwinding, while the VM is still inside
+ * the C-level xpcall error-handling frame. If that handler also runs long
+ * enough for the hook to fire again (trivially true once the hook has
+ * already tightened to \`count = 1\` after the first breach — see
+ * \`./limits\`), the second \`lua_error\` longjmps AGAIN, nested inside the
+ * xpcall error-handler's setjmp/Asyncify state, and wasmoon deadlocks:
+ * \`thread.run()\` never resolves or rejects, the JS event loop is fully
+ * blocked (not spinning — an idle wait), and nothing external, including an
+ * unrelated \`setTimeout\`, ever fires again. Verified empirically against
+ * wasmoon 1.16.0 in a disposable child-process harness (own OS-level SIGKILL
+ * watchdog, run outside this repo's test suite so a still-hanging case could
+ * never block CI): \`return xpcall(f, f)\` and three structural variants
+ * (looping in a \`while\` around the xpcall call, wrapping the xpcall call in
+ * an outer \`pcall\`, and a looping message handler with a non-looping body)
+ * all hang the host process indefinitely under the stock C \`xpcall\`, while
+ * \`pcall\`-only equivalents (including the pcall-wrapped-retry-loop "worst
+ * case" documented in \`./limits\`) correctly terminate as limit failures.
+ *
+ * ## The fix
+ *
+ * Reimplementing \`xpcall\` in Lua on top of \`pcall\` means the message
+ * handler runs at ORDINARY Lua call depth (an ordinary function call from
+ * inside this prelude's own \`xpcall\`, itself invoked through \`pcall\`),
+ * never inside the C xpcall error-unwind frame — so a hook-triggered
+ * longjmp during the handler propagates exactly like it does for the
+ * already-safe \`pcall\` cases, instead of deadlocking. Verified empirically
+ * in the same disposable harness: with this reimplementation installed, all
+ * four former-hang cases now terminate (well under a second) as
+ * \`{ok:false, error:{kind:'limit', limit:'instructions'}}\`, and legitimate
+ * \`xpcall(f, handler)\` usage (handler receiving the error object on
+ * failure; all return values passed through unchanged on success) is
+ * unaffected — see \`limits.deadlock.test.ts\`.
+ *
+ * ## Accepted semantics change (safe in this sandbox)
+ *
+ * The handler now runs AFTER the stack has unwound (an ordinary \`pcall\`
+ * return), not WHILE it is still live, so it cannot walk a live traceback
+ * the way \`debug.traceback\` would from inside a real C \`xpcall\` handler.
+ * This loses nothing real here: \`debug\` is never loaded in this sandbox
+ * (see the library table below), so no script could have used that
+ * capability anyway. \`table.pack\`/\`table.unpack\` preserve variadic
+ * arguments to \`f\` and every return value on the success path, matching
+ * stock \`xpcall\`'s multi-return contract.
+ */
+const XPCALL_REIMPLEMENTATION = `
+do
+  local _pcall = pcall
+  xpcall = function(f, msgh, ...)
+    local r = table.pack(_pcall(f, ...))
+    if r[1] then return table.unpack(r, 1, r.n) end
+    return false, msgh(r[2])
+  end
+end
+`;
+const SCRUB_PRELUDE = `
+load = nil
+loadstring = nil
+loadfile = nil
+dofile = nil
+collectgarbage = nil
+rawget = nil
+rawset = nil
+rawequal = nil
+rawlen = nil
+getmetatable = nil
+setmetatable = nil
+print = nil
+warn = nil
+_G = nil
+_VERSION = nil
+string.dump = nil
+${XPCALL_REIMPLEMENTATION}
+`;
+/** The Base-library names this sandbox intentionally keeps reachable. */
+export const ALLOWED_GLOBALS = [
+    'tonumber',
+    'tostring',
+    'type',
+    'ipairs',
+    'pairs',
+    'next',
+    'select',
+    'error',
+    'assert',
+    'pcall',
+    'xpcall',
+    'string',
+    'table',
+    'math',
+];
+/** Names this sandbox verifies are absent after scrubbing (see the adversarial test suite). */
+export const DENIED_GLOBALS = [
+    'os',
+    'io',
+    'require',
+    'dofile',
+    'loadfile',
+    'load',
+    'loadstring',
+    'debug',
+    'package',
+    'coroutine',
+    'collectgarbage',
+    'rawget',
+    'rawset',
+    'rawequal',
+    'rawlen',
+    'getmetatable',
+    'setmetatable',
+    'print',
+    'warn',
+    '_G',
+    '_VERSION',
+];
+/**
+ * Creates a fresh wasmoon engine with the curated, empty environment
+ * described above. `traceAllocations: true` is required for the memory cap
+ * (`./limits` / `./sandbox` call `engine.global.setMemoryMax`) — without it
+ * wasmoon uses the plain, uncapped allocator.
+ */
+export async function createEmptyLuaEngine(options) {
+    const factory = new LuaFactory(options?.wasmUri);
+    const engine = await factory.createEngine({
+        openStandardLibs: false,
+        traceAllocations: true,
+    });
+    for (const library of LIBRARIES) {
+        engine.global.loadLibrary(library);
+    }
+    await engine.doString(SCRUB_PRELUDE);
+    return engine;
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export type { ScriptFailure, ScriptLimitKind, ScriptMarshalReason, } from './errors.js';
+export { CAPABILITY_ERROR_TAG, MARSHAL_ERROR_TAG, ScriptLimitError, } from './errors.js';
+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 { 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';
+export { NOT_YET_SUPPORTED_MESSAGE, buildRequireStub } from './require.js';
+export type { RunScriptOptions, RunScriptResult } from './sandbox.js';
+export { runScript } from './sandbox.js';
+export type { LuaExecutorConfig } from './executor.js';
+export { createLuaExecutor } from './executor.js';

package/dist/index.js

@@ -0,0 +1,13 @@
+// @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
+// 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';
+export { ALLOWED_GLOBALS, DENIED_GLOBALS, createEmptyLuaEngine, } from './globals.js';
+export { DEFAULT_LIMITS, installLimits } from './limits.js';
+export { DEFAULT_MAX_FETCH_BYTES, bytesToLuaString, buildCapabilities, luaStringToBytes, } from './capabilities.js';
+export { DEFAULT_MARSHAL_LIMITS, buildMarshalPrelude, finalizeMarshaledValue, wrapUserCode, } from './marshal.js';
+export { NOT_YET_SUPPORTED_MESSAGE, buildRequireStub } from './require.js';
+export { runScript } from './sandbox.js';
+export { createLuaExecutor } from './executor.js';

package/dist/limits.d.ts

@@ -0,0 +1,146 @@
+import { type LuaThread } from 'wasmoon';
+import type { ScriptLimitKind } from './errors.js';
+/** Resource limits for one `runScript` call. All configurable; defaults are conservative. */
+export interface ScriptLimits {
+    /** Lua VM instructions before the run is killed. Default 100,000,000. */
+    maxInstructions: number;
+    /** Wall-clock milliseconds before the run is killed. Default 5,000. */
+    wallClockMs: number;
+    /** Bytes the Lua allocator may hand out before allocations start failing. Default 32 MiB. */
+    maxMemoryBytes: number;
+    /**
+     * VM instructions between hook firings (the `count` argument to
+     * `lua_sethook`'s `LUA_MASKCOUNT`). Smaller = finer-grained wall-clock
+     * checks and lower overshoot past `maxInstructions`, at the cost of more
+     * hook-call overhead per instruction executed. Default 10,000.
+     */
+    hookIntervalInstructions: number;
+}
+export declare const DEFAULT_LIMITS: ScriptLimits;
+export interface LimitHandle {
+    /** True once the instruction/wall-clock hook has fired at least once. Authoritative: check this after every run, regardless of the run's apparent outcome (see the module doc comment). */
+    isBreached(): boolean;
+    breachKind(): ScriptLimitKind | undefined;
+    /** Removes the WASM function pointer and clears the hook. Must be called exactly once, in the run's `finally`. */
+    dispose(): void;
+}
+/**
+ * Installs the instruction-count + wall-clock interrupt on `thread` (a
+ * dedicated child thread from `engine.global.newThread()` — see the "hooks
+ * are per-thread" note below) and returns a handle to read/tear it down.
+ *
+ * ## Why this exists instead of wasmoon's own `Thread.setTimeout`/`run({
+ * timeout })`
+ *
+ * wasmoon ships a built-in mechanism (`Thread.setTimeout`, used internally
+ * by `run({ timeout })`): it installs a `lua_sethook` count hook that, once
+ * `Date.now() > deadline`, pushes a `LuaTimeoutError` and calls
+ * `lua_error`. That is a completely ordinary Lua error from the VM's point
+ * of view — indistinguishable from a script calling `error("x")` itself —
+ * which means it is fully catchable by `pcall`:
+ *
+ * ```lua
+ * pcall(function() while true do end end)  -- catches the timeout, keeps going
+ * ```
+ *
+ * This is exactly the case the task calls out as "the crucial one": the
+ * interrupt must abort the WHOLE RUN, not be swallowed by the script's own
+ * `pcall`. Verified empirically against wasmoon 1.16.0 — a script that
+ * `pcall`s an infinite loop and then keeps running afterward completes
+ * "successfully" under wasmoon's own `setTimeout`/`run({timeout})`
+ * mechanism; the timeout is silently absorbed.
+ *
+ * ## The fix: an out-of-band JS flag, plus shrinking the hook interval to 1
+ *
+ * This hook does two things wasmoon's built-in one doesn't:
+ *
+ * 1. It sets a plain JS closure variable (`breached`) the instant the limit
+ *    is first exceeded. This flag lives entirely on the JS side — no Lua
+ *    value, no metatable, no `pcall` can ever see or clear it. `sandbox.ts`
+ *    checks this flag UNCONDITIONALLY after every run and overrides the
+ *    result to a hard `ScriptLimitError` if it's set, regardless of what
+ *    the Lua-level call returned or whether a `pcall` inside the script
+ *    reported "success". This is the actual enforcement point — not the
+ *    Lua-level error the hook also raises (see next point).
+ * 2. On the FIRST breach, it re-installs the hook with `count = 1` (fires
+ *    on literally every subsequent VM instruction, not just every
+ *    `hookIntervalInstructions`). Combined with the hook continuing to
+ *    call `lua_error` every time it fires, this makes forward progress
+ *    after a breach exceedingly hard: even a script that wraps the
+ *    offending loop in its own `pcall` and immediately retries in an outer
+ *    loop gets re-interrupted after (usually) a single VM instruction, so
+ *    the error re-escalates and reaches the top of the call stack (a
+ *    frame with no enclosing `pcall`) almost immediately. Verified
+ *    empirically: `local n=0; while true do pcall(function() while true do
+ *    end end); n=n+1 end` — the worst case in the adversarial suite,
+ *    combining an inner `pcall`-wrapped infinite loop with an outer
+ *    infinite retry loop — still terminates (as a hard failure, `n` never
+ *    returned) in under 100ms with `maxInstructions = 5,000,000`.
+ *
+ * Point 2 is a strong practical deterrent but is NOT a formal proof of
+ * "zero possible forward progress after breach" — a script could in
+ * principle structure code so that literally every single VM instruction
+ * after the breach happens inside its own fresh `pcall` frame (each
+ * `pcall` call itself is several instructions, some of which execute
+ * outside any protection while the closure/call frame is being set up).
+ * Point 1 is what actually closes the loophole: even in that
+ * (implausible, and in practice never observed) worst case, the run's
+ * *reported outcome* is still forced to a limit failure by the JS-side
+ * flag, which the script has no way to reach or clear. **Solid** claim:
+ * the reported result of a breached run is always a limit failure, never
+ * a script-controlled "success" — but this was verified against `pcall`
+ * specifically, and does NOT generalize to every Lua construct that can
+ * catch an error. It was FALSE, for one such construct, until a separate
+ * fix landed: the stock C `xpcall` invokes its message handler WHILE still
+ * inside the C-level xpcall error-unwind frame, and a hook-triggered
+ * longjmp firing again during that handler (trivial once the hook has
+ * tightened to `count = 1` after the first breach) re-enters that same
+ * setjmp/Asyncify state and deadlocks wasmoon's `thread.run()` outright —
+ * not a script-controlled "success", but a hung HOST, which is worse. That
+ * specific hole is closed by replacing `xpcall` with a pure-Lua
+ * reimplementation built on `pcall` (see `./globals`'s
+ * `XPCALL_REIMPLEMENTATION`), so the message handler runs at ordinary Lua
+ * call depth instead of inside the C xpcall frame, where a re-firing hook
+ * behaves exactly like the already-safe `pcall` case. **Best-effort, not
+ * airtight** claim, even with that fix: the breached script's own further
+ * CPU consumption is curtailed almost immediately, not provably instantly,
+ * and this in-VM hook is fundamentally a cooperative, best-effort
+ * mechanism — it only runs BETWEEN Lua VM instructions and cannot preempt
+ * a single WASM-synchronous hang (whether from an as-yet-undiscovered catch
+ * construct with the same nested-frame shape as the old `xpcall`, or from
+ * something outside the VM's own instruction stream entirely). The
+ * 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
+ * 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
+ * case; it is not, and cannot be, a substitute for the external watchdog.
+ *
+ * ## Why hooks are per-thread, and why that matters here
+ *
+ * `lua_sethook` sets the hook on the specific `lua_State` passed to it.
+ * `engine.doString()` internally creates a NEW child thread via
+ * `engine.global.newThread()` and runs the script there — a hook installed
+ * on `engine.global.address` would never fire for code run through
+ * `doString`. `sandbox.ts` therefore does NOT use `engine.doString()` for
+ * the untrusted script; it creates the child thread itself (mirroring what
+ * `doString` does internally) so it can install this hook on that exact
+ * thread before loading/running the script.
+ *
+ * ## Wall-clock accuracy
+ *
+ * The wall-clock check only runs when the hook fires — i.e. every
+ * `hookIntervalInstructions` VM instructions. This is not a true
+ * OS-level preemption (nothing in wasmoon offers that inside a single JS
+ * thread); it bounds overshoot to "however long `hookIntervalInstructions`
+ * takes to execute", which for the default of 10,000 is sub-millisecond on
+ * ordinary hardware. It does NOT protect against a single hung *host*
+ * operation (e.g. a capability call that never resolves its promise) —
+ * that's a separate concern handled by the `Promise.race` wall-clock guard
+ * in `sandbox.ts`, since Lua isn't executing any instructions while
+ * suspended on an `await`, so this hook simply never fires during that
+ * window.
+ */
+export declare function installLimits(thread: LuaThread, limits: Pick<ScriptLimits, 'maxInstructions' | 'wallClockMs' | 'hookIntervalInstructions'>): LimitHandle;

package/dist/limits.js

@@ -0,0 +1,172 @@
+import { LuaEventMasks } from 'wasmoon';
+export const DEFAULT_LIMITS = {
+    maxInstructions: 100_000_000,
+    wallClockMs: 5_000,
+    maxMemoryBytes: 32 * 1024 * 1024,
+    hookIntervalInstructions: 10_000,
+};
+/**
+ * Installs the instruction-count + wall-clock interrupt on `thread` (a
+ * dedicated child thread from `engine.global.newThread()` — see the "hooks
+ * are per-thread" note below) and returns a handle to read/tear it down.
+ *
+ * ## Why this exists instead of wasmoon's own `Thread.setTimeout`/`run({
+ * timeout })`
+ *
+ * wasmoon ships a built-in mechanism (`Thread.setTimeout`, used internally
+ * by `run({ timeout })`): it installs a `lua_sethook` count hook that, once
+ * `Date.now() > deadline`, pushes a `LuaTimeoutError` and calls
+ * `lua_error`. That is a completely ordinary Lua error from the VM's point
+ * of view — indistinguishable from a script calling `error("x")` itself —
+ * which means it is fully catchable by `pcall`:
+ *
+ * ```lua
+ * pcall(function() while true do end end)  -- catches the timeout, keeps going
+ * ```
+ *
+ * This is exactly the case the task calls out as "the crucial one": the
+ * interrupt must abort the WHOLE RUN, not be swallowed by the script's own
+ * `pcall`. Verified empirically against wasmoon 1.16.0 — a script that
+ * `pcall`s an infinite loop and then keeps running afterward completes
+ * "successfully" under wasmoon's own `setTimeout`/`run({timeout})`
+ * mechanism; the timeout is silently absorbed.
+ *
+ * ## The fix: an out-of-band JS flag, plus shrinking the hook interval to 1
+ *
+ * This hook does two things wasmoon's built-in one doesn't:
+ *
+ * 1. It sets a plain JS closure variable (`breached`) the instant the limit
+ *    is first exceeded. This flag lives entirely on the JS side — no Lua
+ *    value, no metatable, no `pcall` can ever see or clear it. `sandbox.ts`
+ *    checks this flag UNCONDITIONALLY after every run and overrides the
+ *    result to a hard `ScriptLimitError` if it's set, regardless of what
+ *    the Lua-level call returned or whether a `pcall` inside the script
+ *    reported "success". This is the actual enforcement point — not the
+ *    Lua-level error the hook also raises (see next point).
+ * 2. On the FIRST breach, it re-installs the hook with `count = 1` (fires
+ *    on literally every subsequent VM instruction, not just every
+ *    `hookIntervalInstructions`). Combined with the hook continuing to
+ *    call `lua_error` every time it fires, this makes forward progress
+ *    after a breach exceedingly hard: even a script that wraps the
+ *    offending loop in its own `pcall` and immediately retries in an outer
+ *    loop gets re-interrupted after (usually) a single VM instruction, so
+ *    the error re-escalates and reaches the top of the call stack (a
+ *    frame with no enclosing `pcall`) almost immediately. Verified
+ *    empirically: `local n=0; while true do pcall(function() while true do
+ *    end end); n=n+1 end` — the worst case in the adversarial suite,
+ *    combining an inner `pcall`-wrapped infinite loop with an outer
+ *    infinite retry loop — still terminates (as a hard failure, `n` never
+ *    returned) in under 100ms with `maxInstructions = 5,000,000`.
+ *
+ * Point 2 is a strong practical deterrent but is NOT a formal proof of
+ * "zero possible forward progress after breach" — a script could in
+ * principle structure code so that literally every single VM instruction
+ * after the breach happens inside its own fresh `pcall` frame (each
+ * `pcall` call itself is several instructions, some of which execute
+ * outside any protection while the closure/call frame is being set up).
+ * Point 1 is what actually closes the loophole: even in that
+ * (implausible, and in practice never observed) worst case, the run's
+ * *reported outcome* is still forced to a limit failure by the JS-side
+ * flag, which the script has no way to reach or clear. **Solid** claim:
+ * the reported result of a breached run is always a limit failure, never
+ * a script-controlled "success" — but this was verified against `pcall`
+ * specifically, and does NOT generalize to every Lua construct that can
+ * catch an error. It was FALSE, for one such construct, until a separate
+ * fix landed: the stock C `xpcall` invokes its message handler WHILE still
+ * inside the C-level xpcall error-unwind frame, and a hook-triggered
+ * longjmp firing again during that handler (trivial once the hook has
+ * tightened to `count = 1` after the first breach) re-enters that same
+ * setjmp/Asyncify state and deadlocks wasmoon's `thread.run()` outright —
+ * not a script-controlled "success", but a hung HOST, which is worse. That
+ * specific hole is closed by replacing `xpcall` with a pure-Lua
+ * reimplementation built on `pcall` (see `./globals`'s
+ * `XPCALL_REIMPLEMENTATION`), so the message handler runs at ordinary Lua
+ * call depth instead of inside the C xpcall frame, where a re-firing hook
+ * behaves exactly like the already-safe `pcall` case. **Best-effort, not
+ * airtight** claim, even with that fix: the breached script's own further
+ * CPU consumption is curtailed almost immediately, not provably instantly,
+ * and this in-VM hook is fundamentally a cooperative, best-effort
+ * mechanism — it only runs BETWEEN Lua VM instructions and cannot preempt
+ * a single WASM-synchronous hang (whether from an as-yet-undiscovered catch
+ * construct with the same nested-frame shape as the old `xpcall`, or from
+ * something outside the VM's own instruction stream entirely). The
+ * 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
+ * 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
+ * case; it is not, and cannot be, a substitute for the external watchdog.
+ *
+ * ## Why hooks are per-thread, and why that matters here
+ *
+ * `lua_sethook` sets the hook on the specific `lua_State` passed to it.
+ * `engine.doString()` internally creates a NEW child thread via
+ * `engine.global.newThread()` and runs the script there — a hook installed
+ * on `engine.global.address` would never fire for code run through
+ * `doString`. `sandbox.ts` therefore does NOT use `engine.doString()` for
+ * the untrusted script; it creates the child thread itself (mirroring what
+ * `doString` does internally) so it can install this hook on that exact
+ * thread before loading/running the script.
+ *
+ * ## Wall-clock accuracy
+ *
+ * The wall-clock check only runs when the hook fires — i.e. every
+ * `hookIntervalInstructions` VM instructions. This is not a true
+ * OS-level preemption (nothing in wasmoon offers that inside a single JS
+ * thread); it bounds overshoot to "however long `hookIntervalInstructions`
+ * takes to execute", which for the default of 10,000 is sub-millisecond on
+ * ordinary hardware. It does NOT protect against a single hung *host*
+ * operation (e.g. a capability call that never resolves its promise) —
+ * that's a separate concern handled by the `Promise.race` wall-clock guard
+ * in `sandbox.ts`, since Lua isn't executing any instructions while
+ * suspended on an `await`, so this hook simply never fires during that
+ * window.
+ */
+export function installLimits(thread, limits) {
+    let breached = false;
+    let kind;
+    let instructionsSeen = 0;
+    let hookInterval = limits.hookIntervalInstructions;
+    const deadline = Date.now() + limits.wallClockMs;
+    const hookPointer = thread.lua.module.addFunction(() => {
+        instructionsSeen += hookInterval;
+        if (!breached) {
+            if (instructionsSeen >= limits.maxInstructions) {
+                breached = true;
+                kind = 'instructions';
+            }
+            else if (Date.now() >= deadline) {
+                breached = true;
+                kind = 'timeout';
+            }
+            if (breached) {
+                // Tighten the hook so every subsequent instruction re-triggers —
+                // see the module doc comment ("point 2").
+                hookInterval = 1;
+                thread.lua.lua_sethook(thread.address, hookPointer, LuaEventMasks.Count, 1);
+            }
+        }
+        if (breached) {
+            thread.pushValue(`MARK_LIMIT: ${kind ?? 'instructions'} limit exceeded`);
+            thread.lua.lua_error(thread.address);
+        }
+        // Unreachable in practice: lua_error longjmps and never returns here.
+    }, 'vii');
+    thread.lua.lua_sethook(thread.address, hookPointer, LuaEventMasks.Count, limits.hookIntervalInstructions);
+    let disposed = false;
+    return {
+        isBreached: () => breached,
+        breachKind: () => kind,
+        dispose: () => {
+            if (disposed)
+                return;
+            disposed = true;
+            if (!thread.isClosed()) {
+                thread.lua.lua_sethook(thread.address, null, 0, 0);
+            }
+            thread.lua.module.removeFunction(hookPointer);
+        },
+    };
+}