@markii/lua 0.6.0 → 0.7.1

package/dist/capabilities.d.ts

@@ -158,4 +158,18 @@ export declare function buildCapabilities(config: CapabilityConfig): {
     rawGlobals: Record<string, (...args: never[]) => Promise<unknown>>;
     preludeLua: string;
     denials: CapabilityDenials;
+    /**
+     * The same recording function `denials` reads from, exposed so a SIBLING
+     * capability builder assembled in the same `runScript` call (currently
+     * only `./require`'s `buildRequire`) can record onto this identical,
+     * per-run `CapabilityDenials` handle instead of maintaining its own —
+     * `sandbox.ts`'s classification logic only ever consults ONE such handle
+     * per run, so a require-triggered denial (an ungranted/absent bundle
+     * capability, a path-jail rejection surfaced through the same `ScriptView`
+     * `bundle.read` uses, a rejected pack-module request) must land on this
+     * one, not a second, unconsulted one. Not part of the public API surface
+     * consumers reason about (`denials.last()` remains read-only) — this is
+     * wiring between this package's own modules.
+     */
+    recordDenial: (reason: CapabilityDenial['reason'], message: string) => void;
 };

package/dist/capabilities.js

@@ -650,5 +650,10 @@ bundle.write = function(path, data) return __smd_bundle_write_blocked(path, data
 `);
         }
     }
-    return { rawGlobals, preludeLua: preludeParts.join('\n'), denials };
+    return {
+        rawGlobals,
+        preludeLua: preludeParts.join('\n'),
+        denials,
+        recordDenial,
+    };
 }

package/dist/globals.d.ts

@@ -28,5 +28,15 @@ export interface CreateEmptyLuaEngineOptions {
  * described above. `traceAllocations: true` is required for the memory cap
  * (`./limits` / `./sandbox` call `engine.global.setMemoryMax`) — without it
  * wasmoon uses the plain, uncapped allocator.
+ *
+ * NOT A COMPLETE SANDBOX ON ITS OWN (issue #3, slice 4). `SCRUB_PRELUDE`
+ * removes every dangerous global, but it also captures the genuine `load`
+ * primitive into the private global `__smd_load_raw` so `./require`'s prelude
+ * can consume it — and leaves that global set. `runScript` closes the window:
+ * it runs `./require`'s prelude (which nils `__smd_load_raw` back out) and
+ * then asserts, fail-closed, that no code-loading primitive remains before
+ * any user code runs. Do NOT run untrusted code on an engine straight from
+ * this function without first running that prelude; use `runScript`, which is
+ * the only supported way to execute a note's script.
  */
 export declare function createEmptyLuaEngine(options?: CreateEmptyLuaEngineOptions): Promise<LuaEngine>;

package/dist/globals.js

@@ -87,6 +87,21 @@ const LIBRARIES = [
  *   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.
+ *   The real `load` function object is captured into a private global,
+ *   `__smd_load_raw`, ONE LINE ABOVE where the public `load` name is
+ *   nil'd out (see `SCRUB_PRELUDE` below) — mirroring the "capture the
+ *   genuine primitive into a local/global at definition time, before a
+ *   later script can rebind or lose it" discipline already used
+ *   throughout this sandbox (e.g. `./marshal`'s `error`/`type`/`pairs`
+ *   capture, `./capabilities`' `__smd_json_decode` capture). `./require`
+ *   consumes `__smd_load_raw` from its own prelude (run later, still
+ *   before any untrusted script code) to compile a fetched module's
+ *   SOURCE TEXT ONLY — always called with Lua's `mode = "t"`, which
+ *   makes `load` itself refuse a binary/bytecode chunk — and then nils
+ *   `__smd_load_raw` back out once captured into its own local, so the
+ *   raw primitive is never reachable as a global either before or after
+ *   `require` claims it. No other code in this sandbox may read
+ *   `__smd_load_raw`; it is not part of the documented host API.
  * - `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
@@ -205,6 +220,7 @@ do
 end
 `;
 const SCRUB_PRELUDE = `
+__smd_load_raw = load
 load = nil
 loadstring = nil
 loadfile = nil
@@ -269,6 +285,16 @@ export const DENIED_GLOBALS = [
  * described above. `traceAllocations: true` is required for the memory cap
  * (`./limits` / `./sandbox` call `engine.global.setMemoryMax`) — without it
  * wasmoon uses the plain, uncapped allocator.
+ *
+ * NOT A COMPLETE SANDBOX ON ITS OWN (issue #3, slice 4). `SCRUB_PRELUDE`
+ * removes every dangerous global, but it also captures the genuine `load`
+ * primitive into the private global `__smd_load_raw` so `./require`'s prelude
+ * can consume it — and leaves that global set. `runScript` closes the window:
+ * it runs `./require`'s prelude (which nils `__smd_load_raw` back out) and
+ * then asserts, fail-closed, that no code-loading primitive remains before
+ * any user code runs. Do NOT run untrusted code on an engine straight from
+ * this function without first running that prelude; use `runScript`, which is
+ * the only supported way to execute a note's script.
  */
 export async function createEmptyLuaEngine(options) {
     const factory = new LuaFactory(options?.wasmUri);

package/dist/index.d.ts

@@ -8,7 +8,8 @@ export type { CacheEntry, CacheProvider, CapabilityConfig, CapabilityDenial, Cap
 export { DEFAULT_MAX_FETCH_BYTES, bytesToLuaString, buildCapabilities, isNetProviderDenial, luaStringToBytes, netProviderDenial, } from './capabilities.js';
 export type { MarshalLimits } from './marshal.js';
 export { DEFAULT_MARSHAL_LIMITS, buildMarshalPrelude, checkJsonWithinLimits, finalizeMarshaledValue, wrapUserCode, } from './marshal.js';
-export { NOT_YET_SUPPORTED_MESSAGE, buildRequireStub } from './require.js';
+export type { PackModuleResolver, RequireConfig } from './require.js';
+export { buildRequire } from './require.js';
 export type { RunScriptOptions, RunScriptResult } from './sandbox.js';
 export { runScript } from './sandbox.js';
 export type { LuaExecutorConfig } from './executor.js';

package/dist/index.js

@@ -8,6 +8,6 @@ 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 { DEFAULT_MARSHAL_LIMITS, buildMarshalPrelude, checkJsonWithinLimits, finalizeMarshaledValue, wrapUserCode, } from './marshal.js';
-export { NOT_YET_SUPPORTED_MESSAGE, buildRequireStub } from './require.js';
+export { buildRequire } from './require.js';
 export { runScript } from './sandbox.js';
 export { createLuaExecutor } from './executor.js';

package/dist/require.d.ts

@@ -1,43 +1,116 @@
+import type { ScriptView } from '@markii/bundle';
 /**
- * Sandboxed `require` (spec §8 "Script placement, long scripts, and
- * modules"): the eventual design is exactly two sources — bundle-local
- * modules (`require "scripts/util"`, same path-jail as `bundle.read`) and
- * pack-namespaced pure-Lua modules (`require "ana/http"`) — pure Lua
- * source only, no C, no bytecode, no network, module cache per run.
+ * Sandboxed `require` (spec §8 "Long scripts and shared code", docs/
+ * scripting.md): exactly two of the spec's three sources are implemented
+ * here — bundle-local modules and the SEAM for pack modules (the pack
+ * loader itself, and the third source, the vault library, are later
+ * phases: packs need the pack-installation machinery from packs.md, and
+ * the vault library needs a host-side namespace-to-folder mapping neither
+ * of which exists yet). Both implemented sources, and the not-yet-wired
+ * one, share ONE property: every require target this module resolves is
+ * PURE LUA SOURCE TEXT, loaded as a fresh PROTECTED CHUNK on the SAME
+ * thread as the rest of the run, so it shares that run's globals,
+ * capabilities, and instruction/wall-clock/memory budget — a module can
+ * never grant itself more than the script that required it already had.
  *
- * DESIGN NOTE / explicit deferral: this phase (the sandbox primitive
- * itself) does not wire that up yet. `bundle.read` (via the injected
- * `ScriptView`, see `./capabilities`) already gives a script everything it
- * needs to fetch a bundle-local module's SOURCE TEXT; what a real
- * `require` adds on top is caching per module name and running the loaded
- * source as a new protected chunk with the same globals/capabilities —
- * both of those depend on the pack/namespace resolution rules (§8) that
- * belong to a later phase (packs, §5/§12), not to this security primitive.
- * Rather than build a real (but pack-less, cache-less) `require` now and
- * having to change its resolution semantics later, `require` is left
- * UNDEFINED — not stubbed as an always-erroring global — in this phase.
+ * ## Two sources, told apart by the first path segment (docs/scripting.md)
  *
- * Concretely: `sandbox.ts` never calls anything from this module, and the
- * curated environment (`./globals`) never sets a `require` global at all.
- * `NOT_YET_SUPPORTED_MESSAGE` and `buildRequireStub` are kept here,
- * disconnected from the sandbox wiring, as the landing point for that
- * later phase — a future change only needs to call `buildRequireStub()`
- * (or replace it with the real resolver) from `sandbox.ts`'s prelude
- * assembly, next to `buildCapabilities`.
+ * - **Bundle-local**: `require "scripts/util"`. The bundle's structural
+ *   directories — `scripts`, `assets`, `.cache` — are reserved: a name
+ *   whose first `/`-separated segment is exactly one of those three
+ *   ALWAYS resolves inside the bundle. The module's source is fetched via
+ *   the SAME `ScriptView` `bundle.read` uses (`./capabilities`), so it is
+ *   subject to the exact same path-jail (`@markii/bundle`'s
+ *   `normalizeBundlePath`, enforced inside `ScriptView`/`BundleStorage` —
+ *   never re-implemented here) and the exact same read-permission check.
+ *   Reading is the ONLY operation `require` ever performs — it never
+ *   writes — so it is automatically read-only under every tier; there is
+ *   no separate tier gate to apply on top of what `bundle.read` already
+ *   enforces.
+ * - **Pack-namespaced**: `require "ana/http"` (first segment anything
+ *   else). This phase implements ONLY the seam: an optional injected
+ *   `PackModuleResolver`. With no resolver configured (packs are not
+ *   wired into any host yet), a pack-namespaced `require` fails cleanly
+ *   as a capability denial — never a crash, never a fallthrough into
+ *   filesystem or network access.
  *
- * Either way — absent entirely (current state) or stubbed to always error
- * (the stub below, for a host that wants a friendlier error message than
- * a bare "attempt to call a nil value") — the guarantee the adversarial
- * suite checks holds: no raw Lua `require` is ever reachable, and no
- * script can load arbitrary source or bytecode through it.
+ * ## Why a real `require` needs `load` back, carefully
+ *
+ * `./globals` removes `load` (and its bytecode-execution siblings) from
+ * every sandbox by never letting a script reach a way to compile new
+ * source at runtime — "the ONLY code that ever runs is the one chunk the
+ * host handed in" (spec §10). A real `require` necessarily breaks that
+ * absolute reading: the host is now explicitly choosing to run a SECOND
+ * chunk, one whose text came from a bundle or a pack, not from the note's
+ * own script block. This module does not reopen `load` as a general
+ * capability — no script can ever call `load` directly, under any name.
+ * Instead, `./globals` captures the genuine `load` primitive into a
+ * private global (`__smd_load_raw`) an instant before scrubbing the
+ * public name, and this module's own prelude is the ONLY consumer: it
+ * captures that global into a local and immediately nils the global back
+ * out, so it is reachable from nowhere else, for the rest of the run,
+ * under any name a script could type. Every call this prelude makes to
+ * it passes `mode = "t"` — Lua's own built-in "text chunks only" gate,
+ * which makes `load` itself refuse anything starting with the Lua
+ * bytecode signature (`\27Lua`) before compiling a single byte of it.
+ * `buildRequire` below ALSO rejects that same signature on the JS side,
+ * before the text ever reaches Lua at all — belt and suspenders, not
+ * because either check alone is known to be insufficient, but because
+ * this codebase's convention throughout (`captureAssertOkStatus`,
+ * `ScriptLimitError`, the `xpcall` reimplementation) is to make a
+ * security property hold for two independent reasons wherever the cost
+ * of the second one is low.
+ *
+ * ## Cache, cycle detection, and protected execution — done entirely in Lua
+ *
+ * The module-name -> source-text lookup is the only part that needs a
+ * host round trip (bundle-local: an async `ScriptView.read`; pack:
+ * synchronous, but still crosses the JS/Lua boundary the same way).
+ * Everything after that — the per-run cache, in-progress-stack cycle
+ * detection, compiling, and running the module body — is plain Lua
+ * control flow inside the prelude this module builds, calling Lua from
+ * Lua, never JS calling into Lua. This deliberately mirrors
+ * `./capabilities`' `cache.get`: a Lua function invoked FROM JS goes
+ * through wasmoon's synchronous, non-yieldable bridge, so if a module
+ * body itself calls `net.fetch_json` (which needs `:await()`), that call
+ * must happen as an ordinary Lua-to-Lua call, never as a host-driven one.
+ * The module body runs via `pcall(chunk)`, not `xpcall` — see
+ * `./globals`' `XPCALL_REIMPLEMENTATION` doc comment for why the STOCK C
+ * `xpcall` (which this sandbox never restores) can deadlock the host
+ * under the limits hook; plain `pcall` has no such hazard, and a limit
+ * breach during a module's execution still wins unconditionally via
+ * `./limits`' out-of-band JS flag regardless of what any Lua-level
+ * `pcall` around it reports.
  */
-export declare const NOT_YET_SUPPORTED_MESSAGE = "modules not yet supported (require \"%s\")";
+/** A pack-namespaced `require "packName/modulePath"` resolver, injected by a host that has actually wired up pack installation. Returns pure Lua SOURCE TEXT, or `undefined` if this pack/module isn't available — never throws for a routine "not found". */
+export type PackModuleResolver = (packName: string, modulePath: string) => string | undefined;
+export interface RequireConfig {
+    /** The SAME `ScriptView` `./capabilities` wires up for `bundle.read`/`bundle.write` — reused, never re-implemented, so bundle-local `require` is subject to the identical path-jail and read-permission check. */
+    bundle?: ScriptView;
+    /** Optional pack-module seam — see the module doc comment. Absent (the current default: no host wires packs yet) means every pack-namespaced `require` fails as a clean capability denial. */
+    packModuleResolver?: PackModuleResolver;
+    /**
+     * Records a genuine denial onto the SAME per-run `CapabilityDenials`
+     * handle `./capabilities`' `buildCapabilities` already returns (its
+     * `recordDenial` field) — so `sandbox.ts` classifies a require-triggered
+     * denial as `kind: 'capability'`, exactly like any other capability
+     * failure, rather than an unclassified `'runtime'` error. Optional only
+     * so this module stays independently testable/usable without the rest
+     * of `./capabilities`' wiring; `sandbox.ts` always supplies it.
+     */
+    recordDenial?: (reason: 'denied' | 'tier-blocked', message: string) => void;
+}
 /**
- * Not wired into `sandbox.ts` in this phase (see module doc comment
- * above) — provided so a host that wants an explicit, friendlier error
- * message instead of Lua's default "attempt to call a nil value (global
- * 'require')" can opt in without this package needing to change shape
- * later. Deliberately does not touch the filesystem, network, or `load` —
- * it only ever raises.
+ * Builds the raw host-facing module resolver and the trusted Lua prelude
+ * that turns it into the real `require` global — see the module doc
+ * comment for the full design. Always defines `require`, regardless of
+ * whether `config.bundle` or `config.packModuleResolver` is present, so a
+ * run with neither configured still gets a real, always-defined function
+ * that fails every request cleanly (a capability denial), matching this
+ * sandbox's "never a bare 'attempt to call a nil value'" posture for
+ * every other documented host API surface.
  */
-export declare function buildRequireStub(): string;
+export declare function buildRequire(config: RequireConfig): {
+    rawGlobals: Record<string, (...args: never[]) => Promise<unknown>>;
+    preludeLua: string;
+};

package/dist/require.js

@@ -1,49 +1,185 @@
+import { bytesToLuaString } from './capabilities.js';
+import { CAPABILITY_ERROR_TAG } from './errors.js';
+/** The bundle's reserved structural directories (docs/scripting.md): a `require` name whose first `/`-segment is exactly one of these always resolves inside the bundle and can never be a pack namespace. */
+const RESERVED_BUNDLE_DIRS = new Set([
+    'scripts',
+    'assets',
+    '.cache',
+]);
+/** First `/`-separated path segment of `name` (the whole string if there is no `/`). */
+function firstSegment(name) {
+    const idx = name.indexOf('/');
+    return idx === -1 ? name : name.slice(0, idx);
+}
+/** True iff `name`'s first segment is one of the bundle's reserved structural directories. */
+function isBundleLocalName(name) {
+    return RESERVED_BUNDLE_DIRS.has(firstSegment(name));
+}
+/**
+ * Maps a bundle-local `require` name to the bundle-relative path its
+ * source is read from. A `.lua` suffix is appended when the name doesn't
+ * already carry one — `require "scripts/util"` and `require
+ * "scripts/util.lua"` both resolve to `scripts/util.lua`. This mapping is
+ * this package's own convention (docs/scripting.md's `require` examples
+ * never show an extension); it does not affect the path-jail, which is
+ * enforced entirely by `ScriptView.read` on the resulting path regardless
+ * of how it was built.
+ */
+function bundleModulePath(name) {
+    return name.endsWith('.lua') ? name : `${name}.lua`;
+}
+/** First byte of Lua's bytecode chunk signature (`"\27Lua..."`, i.e. ESC followed by `Lua`). */
+const LUA_BYTECODE_SIGNATURE_FIRST_BYTE = 0x1b;
 /**
- * Sandboxed `require` (spec §8 "Script placement, long scripts, and
- * modules"): the eventual design is exactly two sources — bundle-local
- * modules (`require "scripts/util"`, same path-jail as `bundle.read`) and
- * pack-namespaced pure-Lua modules (`require "ana/http"`) — pure Lua
- * source only, no C, no bytecode, no network, module cache per run.
- *
- * DESIGN NOTE / explicit deferral: this phase (the sandbox primitive
- * itself) does not wire that up yet. `bundle.read` (via the injected
- * `ScriptView`, see `./capabilities`) already gives a script everything it
- * needs to fetch a bundle-local module's SOURCE TEXT; what a real
- * `require` adds on top is caching per module name and running the loaded
- * source as a new protected chunk with the same globals/capabilities —
- * both of those depend on the pack/namespace resolution rules (§8) that
- * belong to a later phase (packs, §5/§12), not to this security primitive.
- * Rather than build a real (but pack-less, cache-less) `require` now and
- * having to change its resolution semantics later, `require` is left
- * UNDEFINED — not stubbed as an always-erroring global — in this phase.
- *
- * Concretely: `sandbox.ts` never calls anything from this module, and the
- * curated environment (`./globals`) never sets a `require` global at all.
- * `NOT_YET_SUPPORTED_MESSAGE` and `buildRequireStub` are kept here,
- * disconnected from the sandbox wiring, as the landing point for that
- * later phase — a future change only needs to call `buildRequireStub()`
- * (or replace it with the real resolver) from `sandbox.ts`'s prelude
- * assembly, next to `buildCapabilities`.
- *
- * Either way — absent entirely (current state) or stubbed to always error
- * (the stub below, for a host that wants a friendlier error message than
- * a bare "attempt to call a nil value") — the guarantee the adversarial
- * suite checks holds: no raw Lua `require` is ever reachable, and no
- * script can load arbitrary source or bytecode through it.
+ * Defense-in-depth bytecode rejection on the JS side, BEFORE a resolved
+ * module's source ever reaches Lua's own `load(text, name, "t")` call
+ * (which independently refuses the same signature — see the module doc
+ * comment's "belt and suspenders" note). `source` here is always a JS
+ * string built the same one-code-unit-per-byte way `./capabilities`'
+ * `bytesToLuaString` produces, so `charCodeAt(0)` reads the first raw
+ * byte, not a decoded Unicode code point.
  */
-export const NOT_YET_SUPPORTED_MESSAGE = 'modules not yet supported (require "%s")';
+function looksLikeBytecode(source) {
+    return (source.length > 0 &&
+        source.charCodeAt(0) === LUA_BYTECODE_SIGNATURE_FIRST_BYTE);
+}
 /**
- * Not wired into `sandbox.ts` in this phase (see module doc comment
- * above) — provided so a host that wants an explicit, friendlier error
- * message instead of Lua's default "attempt to call a nil value (global
- * 'require')" can opt in without this package needing to change shape
- * later. Deliberately does not touch the filesystem, network, or `load` —
- * it only ever raises.
+ * Builds the raw host-facing module resolver and the trusted Lua prelude
+ * that turns it into the real `require` global — see the module doc
+ * comment for the full design. Always defines `require`, regardless of
+ * whether `config.bundle` or `config.packModuleResolver` is present, so a
+ * run with neither configured still gets a real, always-defined function
+ * that fails every request cleanly (a capability denial), matching this
+ * sandbox's "never a bare 'attempt to call a nil value'" posture for
+ * every other documented host API surface.
  */
-export function buildRequireStub() {
-    return `
+export function buildRequire(config) {
+    const recordDenial = config.recordDenial ?? (() => undefined);
+    function denyAndThrow(message) {
+        recordDenial('denied', message);
+        throw new Error(`${CAPABILITY_ERROR_TAG}: ${message}`);
+    }
+    const rawGlobals = {};
+    rawGlobals.__smd_require_resolve_raw = (async (name) => {
+        if (typeof name !== 'string' || name.length === 0) {
+            throw new Error('require: module name must be a non-empty string');
+        }
+        let source;
+        if (isBundleLocalName(name)) {
+            const view = config.bundle;
+            if (!view) {
+                denyAndThrow(`bundle capability is not available for this run (require "${name}")`);
+            }
+            const path = bundleModulePath(name);
+            let data;
+            try {
+                data = await view.read(path);
+            }
+            catch (err) {
+                denyAndThrow(err instanceof Error ? err.message : String(err));
+            }
+            if (data === undefined) {
+                // A genuine "no such module" — not a permission problem, so NOT
+                // recorded as a denial. Spec: "a require that can't resolve fails
+                // softly" — this propagates as an ordinary, uncaught Lua error
+                // (see the prelude below), the same graceful failure shape any
+                // other script-error already gets.
+                throw new Error(`require: no bundle module at "${path}"`);
+            }
+            source = bytesToLuaString(data);
+        }
+        else {
+            const resolver = config.packModuleResolver;
+            if (!resolver) {
+                denyAndThrow(`pack modules are not supported in this run (require "${name}")`);
+            }
+            const segIdx = name.indexOf('/');
+            const packName = segIdx === -1 ? name : name.slice(0, segIdx);
+            const modulePath = segIdx === -1 ? '' : name.slice(segIdx + 1);
+            const resolved = resolver(packName, modulePath);
+            if (resolved === undefined) {
+                throw new Error(`require: no pack module "${modulePath}" in pack "${packName}"`);
+            }
+            source = resolved;
+        }
+        if (looksLikeBytecode(source)) {
+            denyAndThrow(`require "${name}" resolved to a precompiled/binary chunk, which is never permitted (pure Lua source only)`);
+        }
+        return source;
+    });
+    const preludeLua = `
+-- Captured into locals HERE, at prelude-definition time, and the backing
+-- globals nil'd out immediately after -- same discipline as every other
+-- capability wrapper in ./capabilities (see its "Captured into a local
+-- HERE" comments), and load-bearing for __smd_require_load specifically:
+-- __smd_load_raw is the genuine Lua \`load\` primitive (./globals), and
+-- leaving it reachable under any name for even one later statement would
+-- reopen the exact "compile and run arbitrary text" hole §10 closes.
+local __smd_require_resolve = __smd_require_resolve_raw
+local __smd_require_load = __smd_load_raw
+__smd_require_resolve_raw = nil
+__smd_load_raw = nil
+
+-- Per-run module cache and in-progress stack. Both are plain Lua locals
+-- declared in THIS prelude chunk, which runs exactly once per fresh
+-- engine (one runScript call) -- see the module doc comment. A fresh run
+-- gets a fresh engine (./sandbox tears the whole engine down every call),
+-- so neither table is ever visible to, or seeded by, a prior run.
+local __smd_require_cache = {}
+local __smd_require_stack = {}
+
 require = function(name)
-  error(string.format(${JSON.stringify(NOT_YET_SUPPORTED_MESSAGE)}, tostring(name)))
+  if type(name) ~= "string" then
+    error("require: module name must be a string")
+  end
+  local cached = __smd_require_cache[name]
+  if cached ~= nil then
+    return cached
+  end
+  if __smd_require_stack[name] then
+    error("require: circular require of module '" .. name .. "'")
+  end
+
+  -- Resolution (bundle read or pack lookup) happens BEFORE the
+  -- in-progress stack is touched, so a resolution failure (an ungranted
+  -- bundle, a path-jail rejection, no pack resolver, a genuinely missing
+  -- module) never leaves a stale stack entry behind to clean up.
+  local text = __smd_require_resolve(name):await()
+
+  __smd_require_stack[name] = true
+  -- mode = "t": text chunks only -- Lua itself refuses to compile
+  -- anything starting with the bytecode signature under this mode (see
+  -- the module doc comment's "belt and suspenders" note; buildRequire
+  -- already rejected it once, on the JS side, before this point).
+  local chunk, loadErr = __smd_require_load(text, "=" .. name, "t")
+  if not chunk then
+    __smd_require_stack[name] = nil
+    error("require: module '" .. name .. "' failed to compile: " .. tostring(loadErr))
+  end
+
+  -- Protected chunk: same thread, same globals/capabilities, same
+  -- instruction/wall-clock/memory budget as the rest of this run (see
+  -- ./limits -- the hook is installed on the thread, not per-chunk). A
+  -- limit breach during this call still forces the WHOLE run to a hard
+  -- failure via ./limits' out-of-band JS flag, regardless of what this
+  -- pcall reports -- see the module doc comment on why plain pcall (never
+  -- xpcall) is safe here.
+  local ok, result = pcall(chunk)
+  __smd_require_stack[name] = nil
+  if not ok then
+    error(result)
+  end
+
+  -- Matches stock Lua's own require: a module that returns nothing caches
+  -- (and returns) \`true\` rather than \`nil\`, so a later \`require\` of the
+  -- same name is unambiguously a cache HIT (nil is never a valid cached
+  -- value, so it can never be mistaken for "not yet required").
+  if result == nil then
+    result = true
+  end
+  __smd_require_cache[name] = result
+  return result
 end
 `;
+    return { rawGlobals, preludeLua };
 }

package/dist/sandbox.d.ts

@@ -3,6 +3,7 @@ import { type CacheProvider, type CapabilityTier, type NetGrants, type NetProvid
 import type { ScriptFailure } from './errors.js';
 import { type ScriptLimits } from './limits.js';
 import { type MarshalLimits } from './marshal.js';
+import { type PackModuleResolver } from './require.js';
 export interface RunScriptOptions {
     code: string;
     /** Spec §8's trigger tier: 'manual' unlocks effectful ops, 'auto' is read-only regardless of what's granted. */
@@ -10,8 +11,10 @@ export interface RunScriptOptions {
     net?: NetProvider;
     netGrants?: NetGrants;
     cache?: CacheProvider;
-    /** Bundle-scoped filesystem (spec §11), already capability-restricted — see `@markii/bundle`'s `createScriptView`. */
+    /** Bundle-scoped filesystem (spec §11), already capability-restricted — see `@markii/bundle`'s `createScriptView`. Also backs bundle-local `require "scripts/..."` (`./require`) — the SAME `ScriptView`, so a module require goes through the identical path-jail and read-permission check as `bundle.read`. */
     bundle?: ScriptView;
+    /** Optional pack-module `require` seam (`./require`'s `PackModuleResolver`) — resolves `require "packName/modulePath"`. Omitted (the default: no host wires packs yet), every pack-namespaced `require` fails as a clean capability denial, never a crash. */
+    packModuleResolver?: PackModuleResolver;
     maxFetchBytes?: number;
     limits?: Partial<ScriptLimits>;
     marshalLimits?: Partial<MarshalLimits>;
@@ -47,7 +50,9 @@ export type RunScriptResult = {
  * 2. Memory cap (`engine.global.setMemoryMax`, backed by the
  *    `traceAllocations: true` custom allocator `./globals` requests).
  * 3. `./capabilities` — build the `net`/`cache`/`bundle` Lua tables from
- *    whatever providers/grants/tier this call was given.
+ *    whatever providers/grants/tier this call was given, then `./require` —
+ *    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.
  * 5. A dedicated child thread (NOT `engine.doString`, which creates its

package/dist/sandbox.js

@@ -4,6 +4,7 @@ import { MARSHAL_ERROR_TAG, ScriptLimitError } from './errors.js';
 import { createEmptyLuaEngine } from './globals.js';
 import { DEFAULT_LIMITS, installLimits } from './limits.js';
 import { buildMarshalPrelude, DEFAULT_MARSHAL_LIMITS, finalizeMarshaledValue, wrapUserCode, } from './marshal.js';
+import { buildRequire } from './require.js';
 /**
  * The wall-clock hard-kill in `./limits` only fires between Lua VM
  * instructions — it cannot observe a script suspended on `:await()`-ing a
@@ -173,7 +174,9 @@ function classifyRuntimeError(err) {
  * 2. Memory cap (`engine.global.setMemoryMax`, backed by the
  *    `traceAllocations: true` custom allocator `./globals` requests).
  * 3. `./capabilities` — build the `net`/`cache`/`bundle` Lua tables from
- *    whatever providers/grants/tier this call was given.
+ *    whatever providers/grants/tier this call was given, then `./require` —
+ *    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.
  * 5. A dedicated child thread (NOT `engine.doString`, which creates its
@@ -209,7 +212,7 @@ export async function runScript(options) {
     let limitHandle;
     let guardTimer;
     try {
-        const { rawGlobals, preludeLua, denials } = buildCapabilities({
+        const { rawGlobals, preludeLua, denials, recordDenial } = buildCapabilities({
             tier: options.tier,
             net: options.net,
             netGrants: options.netGrants,
@@ -224,6 +227,38 @@ export async function runScript(options) {
         if (preludeLua.trim().length > 0) {
             await engine.doString(preludeLua);
         }
+        // ./require: always wired, regardless of whether `options.bundle`/
+        // `options.packModuleResolver` are set — see `buildRequire`'s doc
+        // comment for why `require` must always be a real, defined function
+        // (never left absent for the sandbox to leave as a bare "attempt to
+        // call a nil value"), and shares `denials`/`recordDenial` with
+        // `buildCapabilities` above so a require-triggered denial classifies
+        // as `kind: 'capability'` the same way any other one does (see
+        // `classifyRuntimeError`'s doc comment below).
+        const requireBuild = buildRequire({
+            bundle: options.bundle,
+            packModuleResolver: options.packModuleResolver,
+            recordDenial,
+        });
+        for (const [name, fn] of Object.entries(requireBuild.rawGlobals)) {
+            engine.global.set(name, fn);
+        }
+        if (requireBuild.preludeLua.trim().length > 0) {
+            await engine.doString(requireBuild.preludeLua);
+        }
+        // Fail-closed defense in depth (issue #3, slice 4). `./globals`'
+        // SCRUB_PRELUDE captures the genuine `load` primitive into the private
+        // global `__smd_load_raw` so `./require`'s prelude (run just above) can
+        // consume it; that prelude nils the global back out immediately. This
+        // asserts the window is actually closed BEFORE any user code runs: if a
+        // future refactor of either prelude ever left `__smd_load_raw` (or the
+        // public `load`) reachable, this aborts the run rather than executing a
+        // script against an exposed compiler. On the sanctioned path this is
+        // always a no-op; it exists so the path can never silently regress.
+        const loadResidue = await engine.doString('return type(__smd_load_raw) .. "," .. type(load)');
+        if (loadResidue !== 'nil,nil') {
+            throw new Error(`sandbox assembly left a code-loading primitive reachable (${String(loadResidue)}); refusing to run`);
+        }
         await engine.doString(buildMarshalPrelude(marshalLimits));
         thread = engine.global.newThread();
         threadStackIndex = engine.global.getTop();

package/package.json

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