@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/dist/core/src/plugin/permissions.js

@@ -0,0 +1,152 @@
+// ============================================================================
+// Plugin permissions — the sandbox permission model.
+//
+// Each `PluginPermission` maps to a set of Web Worker globals the sandbox
+// shim keeps (vs. strips) before the plugin's code runs. The host resolves
+// the *granted* permission set = (requested ∩ tier-allowed ∩ game-allowlist),
+// then hands it to the sandbox shim which deletes/overrides disallowed
+// globals.
+//
+// This module is the single source of truth for:
+//   - the per-tier allowed permission sets (mirrored in manifest.ts)
+//   - the permission → global-allowlist mapping
+//   - permission resolution + grant computation
+// ============================================================================
+// ── Per-tier allowed permissions (mirror of manifest.ts rules) ──
+export const TIER_ALLOWED = {
+    data: new Set([]),
+    script: new Set(["events", "state", "tick", "storage", "log"]),
+    native: new Set([
+        "ecs",
+        "sab",
+        "gpu",
+        "events",
+        "state",
+        "tick",
+        "storage",
+        "network",
+        "log",
+        "physics",
+        "assets",
+    ]),
+};
+// ── Permission → worker-global allowlist ──
+//
+// The sandbox shim deletes every global NOT in the granted allowlist. The
+// allowlist is the union of (a) a baseline set always kept (needed for the
+// plugin runtime itself) and (b) per-permission additions.
+//
+// Baseline: the JS runtime essentials + the host-provided `ddPlugin` bridge.
+// These are NEVER stripped — without them the plugin can't run at all.
+export const BASELINE_GLOBALS = [
+    // JS runtime
+    "Object",
+    "Array",
+    "String",
+    "Number",
+    "Boolean",
+    "BigInt",
+    "Symbol",
+    "Math",
+    "JSON",
+    "Date",
+    "Error",
+    "TypeError",
+    "RangeError",
+    "SyntaxError",
+    "ReferenceError",
+    "EvalError",
+    "URIError",
+    "Promise",
+    "Map",
+    "Set",
+    "WeakMap",
+    "WeakSet",
+    "ArrayBuffer",
+    "SharedArrayBuffer",
+    "Int8Array",
+    "Uint8Array",
+    "Uint8ClampedArray",
+    "Int16Array",
+    "Uint16Array",
+    "Int32Array",
+    "Uint32Array",
+    "Float32Array",
+    "Float64Array",
+    "BigInt64Array",
+    "BigUint64Array",
+    "DataView",
+    "TextEncoder",
+    "TextDecoder",
+    "console",
+    "setTimeout",
+    "clearTimeout",
+    "setInterval",
+    "clearInterval",
+    "queueMicrotask",
+    "atob",
+    "btoa",
+    "structuredClone",
+    "performance",
+    "self",
+    "globalThis",
+    // Host bridge (injected by the sandbox shim)
+    "ddPlugin",
+];
+/** Globals kept when a given permission is granted. */
+export const PERMISSION_GLOBALS = {
+    network: ["fetch", "WebSocket", "XMLHttpRequest", "EventSource", "Request", "Response", "Headers", "URL", "URLSearchParams"],
+    storage: ["indexedDB", "caches"],
+    // ecs/sab/gpu/events/state/tick/log don't add raw globals — they're
+    // mediated through the `ddPlugin` host bridge (typed APIs on the context).
+    // Listing them empty keeps the mapping explicit and extensible.
+    ecs: [],
+    sab: [],
+    gpu: [],
+    events: [],
+    state: [],
+    tick: [],
+    log: [],
+    physics: [],
+    assets: [],
+};
+/**
+ * Resolve the granted permission set for a plugin.
+ *
+ * @param requested  Permissions requested in the manifest.
+ * @param tier       The plugin's tier.
+ * @param gameAllow  Optional game-defined allowlist. If provided, only
+ *                   permissions in this set can be granted (game can forbid
+ *                   e.g. `network` even for native-tier plugins). If omitted,
+ *                   the tier set is the only constraint.
+ */
+export function resolvePermissions(requested, tier, gameAllow) {
+    const tierSet = TIER_ALLOWED[tier];
+    const granted = new Set();
+    const denied = [];
+    for (let _i = 0, _it = requested, _n = _it.length; _i < _n; _i++) {
+        const p = _it[_i];
+        if (!tierSet.has(p)) {
+            denied.push({ permission: p, reason: `not allowed for tier "${tier}"` });
+            continue;
+        }
+        if (gameAllow && !gameAllow.has(p)) {
+            denied.push({ permission: p, reason: "denied by game allowlist" });
+            continue;
+        }
+        granted.add(p);
+    }
+    return { granted, denied };
+}
+/**
+ * Compute the full set of worker-global names the sandbox shim should KEEP
+ * for a plugin with the given granted permissions. Everything else on `self`
+ * gets deleted/replaced with a throwing trap.
+ */
+export function computeGlobalAllowlist(granted) {
+    const keep = new Set(BASELINE_GLOBALS);
+    for (const p of granted.values()) {
+        PERMISSION_GLOBALS[p].forEach((g) => { keep.add(g); ; });
+    }
+    return keep;
+}

package/dist/core/src/plugin/quickjs-bridge.js

@@ -0,0 +1,219 @@
+// ============================================================================
+// QuickJS bridge — host↔QuickJS value marshaling + interrupt/timeout.
+//
+// QuickJS plugins run in-process on the renderer thread inside a QuickJS WASM
+// VM (via quickjs-emscripten). The VM provides hard isolation by construction:
+// only the host-bridged globals exist. This module:
+//   - creates a QuickJS runtime + context,
+//   - sets an interrupt handler for per-tick instruction-budget enforcement,
+//   - bridges the ScriptPluginContext API into QuickJS functions,
+//   - marshals values between host and VM (primitives + plain objects via JSON),
+//   - evaluates the plugin entry and calls its register().
+// ============================================================================
+import { getQuickJS as _getQuickJS } from "quickjs-emscripten";
+import { getWarningEngine, METRIC_TASK_LATENCY, recordTaskLatency } from "../profiling/worker-prelude.js";
+/** Re-export getQuickJS so consumers don't need a direct dep on quickjs-emscripten. */
+export const getQuickJS = _getQuickJS;
+/** Maximum instructions per eval/tick before the interrupt handler fires. */
+const DEFAULT_INSTRUCTION_BUDGET = 1_000_000;
+/** Marshal a host value into a QuickJS handle. Caller must dispose. */
+function marshalToVm(ctx, value) {
+    if (value === undefined || value === null)
+        return ctx.undefined;
+    if (typeof value === "number")
+        return ctx.newNumber(value);
+    if (typeof value === "string")
+        return ctx.newString(value);
+    if (typeof value === "boolean")
+        return value ? ctx.true : ctx.false;
+    // Objects + arrays → JSON round-trip (simple, safe, no live sharing).
+    if (typeof value === "object") {
+        const result = ctx.evalCode(`JSON.parse(${JSON.stringify(JSON.stringify(value))})`);
+        if (result.error) {
+            result.error.dispose();
+            return ctx.undefined;
+        }
+        // unwrapResult transfers ownership — caller must dispose.
+        return ctx.unwrapResult(result);
+    }
+    return ctx.undefined;
+}
+/** Marshal a QuickJS handle to a host value. Does NOT consume the handle. */
+function marshalFromVm(ctx, handle) {
+    try {
+        return ctx.dump(handle);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Create a QuickJS bridge with a runtime + context, interrupt handler, and
+ * bridged host functions. The `hostApi` object provides the actual
+ * ScriptPluginContext methods; the bridge wraps them as QuickJS functions.
+ */
+export function createQuickjsBridge(module, hostApi, opts) {
+    const runtime = module.newRuntime();
+    const budget = opts.instructionBudget ?? DEFAULT_INSTRUCTION_BUDGET;
+    let instructions = 0;
+    runtime.setInterruptHandler(() => {
+        instructions++;
+        if (instructions > budget) {
+            return true; // interrupt — throws "interrupted" in the VM
+        }
+        return false;
+    });
+    const ctx = runtime.newContext();
+    // Track all persistent handles so we can dispose them before the context.
+    const handles = [];
+    const track = (h) => { handles.push(h); return h; };
+    const unsubFns = [];
+    const disposeCbs = [];
+    // Bridge the host API into the VM global as `ddPlugin`.
+    const ddPlugin = track(ctx.newObject());
+    // ── events ──
+    const events = track(ctx.newObject());
+    ctx.setProp(events, "subscribe", track(ctx.newFunction("subscribe", (eventHandle, handlerHandle) => {
+        const event = ctx.getString(eventHandle);
+        // Dup the handler handle so it stays alive after this callback returns.
+        const handlerDup = handlerHandle.dup();
+        handles.push(handlerDup);
+        const handler = (data) => {
+            try {
+                const dataHandle = marshalToVm(ctx, data);
+                ctx.unwrapResult(ctx.callFunction(handlerDup, ctx.undefined, dataHandle));
+                dataHandle.dispose();
+                runtime.executePendingJobs();
+            }
+            catch { /* swallow */ }
+        };
+        unsubFns.push(hostApi.events.subscribe(event, handler));
+        return ctx.undefined;
+    })));
+    ctx.setProp(events, "publish", track(ctx.newFunction("publish", (eventHandle, dataHandle) => {
+        hostApi.events.publish(ctx.getString(eventHandle), marshalFromVm(ctx, dataHandle));
+        return ctx.undefined;
+    })));
+    ctx.setProp(ddPlugin, "events", events);
+    // ── state ──
+    const state = track(ctx.newObject());
+    ctx.setProp(state, "get", track(ctx.newFunction("get", (keyHandle) => marshalToVm(ctx, hostApi.state.get(ctx.getString(keyHandle))))));
+    ctx.setProp(state, "set", track(ctx.newFunction("set", (keyHandle, valueHandle) => {
+        hostApi.state.set(ctx.getString(keyHandle), marshalFromVm(ctx, valueHandle));
+        return ctx.undefined;
+    })));
+    ctx.setProp(state, "delete", track(ctx.newFunction("delete", (keyHandle) => { hostApi.state.delete(ctx.getString(keyHandle)); return ctx.undefined; })));
+    ctx.setProp(state, "keys", track(ctx.newFunction("keys", () => marshalToVm(ctx, hostApi.state.keys()))));
+    ctx.setProp(ddPlugin, "state", state);
+    // ── tick ──
+    const tick = track(ctx.newObject());
+    ctx.setProp(tick, "onTick", track(ctx.newFunction("onTick", (fnHandle) => {
+        const fnDup = fnHandle.dup();
+        handles.push(fnDup);
+        const cb = (dt, t) => {
+            try {
+                const tickStart = performance.now();
+                ctx.unwrapResult(ctx.callFunction(fnDup, ctx.undefined, ctx.newNumber(dt), ctx.newNumber(t)));
+                runtime.executePendingJobs();
+                const durationUs = (performance.now() - tickStart) * 1000;
+                recordTaskLatency("quickjs", durationUs, "tick");
+                getWarningEngine()?.checkInstant(METRIC_TASK_LATENCY, durationUs);
+            }
+            catch { /* swallow */ }
+        };
+        unsubFns.push(hostApi.tick.onTick(cb));
+        return ctx.undefined;
+    })));
+    ctx.setProp(ddPlugin, "tick", tick);
+    // ── log ──
+    const log = track(ctx.newObject());
+    ctx.setProp(log, "info", track(ctx.newFunction("info", (m) => { hostApi.log.info(ctx.getString(m)); return ctx.undefined; })));
+    ctx.setProp(log, "warn", track(ctx.newFunction("warn", (m) => { hostApi.log.warn(ctx.getString(m)); return ctx.undefined; })));
+    ctx.setProp(log, "error", track(ctx.newFunction("error", (m) => { hostApi.log.error(ctx.getString(m)); return ctx.undefined; })));
+    ctx.setProp(log, "debug", track(ctx.newFunction("debug", (m) => { hostApi.log.debug(ctx.getString(m)); return ctx.undefined; })));
+    ctx.setProp(ddPlugin, "log", log);
+    // ── onDispose ──
+    ctx.setProp(ddPlugin, "onDispose", track(ctx.newFunction("onDispose", (fnHandle) => {
+        const fnDup = fnHandle.dup();
+        handles.push(fnDup);
+        // Register the dispose callback directly — the bridge calls these
+        // in dispose() while the VM is still alive.
+        disposeCbs.push(() => {
+            try {
+                ctx.unwrapResult(ctx.callFunction(fnDup, ctx.undefined));
+                runtime.executePendingJobs();
+            }
+            catch { /* swallow */ }
+        });
+        // Also notify the host API (for external tracking).
+        hostApi.onDispose(() => { });
+        return ctx.undefined;
+    })));
+    // ── id ──
+    ctx.setProp(ddPlugin, "id", track(ctx.newString(hostApi.id)));
+    // Expose ddPlugin as a global.
+    ctx.setProp(ctx.global, "ddPlugin", ddPlugin);
+    return {
+        ctx,
+        eval(code, filename) {
+            instructions = 0;
+            const evalStart = performance.now();
+            const result = ctx.evalCode(code, filename);
+            const durationUs = (performance.now() - evalStart) * 1000;
+            recordTaskLatency("quickjs", durationUs, "eval");
+            getWarningEngine()?.checkInstant(METRIC_TASK_LATENCY, durationUs);
+            if (result.error) {
+                const err = ctx.dump(result.error);
+                result.error.dispose();
+                throw new Error(`QuickJS eval error in "${opts.pluginId}": ${err}`);
+            }
+            const val = marshalFromVm(ctx, result.value);
+            result.value.dispose();
+            return val;
+        },
+        callGlobal(fnName, ...args) {
+            instructions = 0;
+            const fn = ctx.getProp(ctx.global, fnName);
+            if (ctx.typeof(fn) !== "function") {
+                fn.dispose();
+                throw new Error(`QuickJS: global "${fnName}" is not a function`);
+            }
+            const argHandles = args.map((a) => marshalToVm(ctx, a));
+            const callStart = performance.now();
+            const result = ctx.callFunction(fn, ctx.undefined, ...argHandles);
+            const durationUs = (performance.now() - callStart) * 1000;
+            recordTaskLatency("quickjs", durationUs, fnName);
+            getWarningEngine()?.checkInstant(METRIC_TASK_LATENCY, durationUs);
+            fn.dispose();
+            argHandles.forEach((h) => { try {
+                h.dispose?.();
+            }
+            catch { /* */ } });
+            if (result.error) {
+                const err = ctx.dump(result.error);
+                result.error.dispose();
+                throw new Error(`QuickJS call error in "${opts.pluginId}": ${err}`);
+            }
+            const val = marshalFromVm(ctx, result.value);
+            result.value.dispose();
+            return val;
+        },
+        drainJobs() {
+            runtime.executePendingJobs();
+        },
+        dispose() {
+            // Run dispose callbacks while the VM is still alive.
+            disposeCbs.forEach((cb) => { cb(); ; });
+            disposeCbs.length = 0;
+            unsubFns.forEach((unsub) => { unsub(); ; });
+            // Dispose all tracked handles before the context.
+            handles.forEach((h) => { try {
+                h.dispose?.();
+            }
+            catch { /* */ } });
+            handles.length = 0;
+            ctx.dispose();
+            runtime.dispose();
+        },
+    };
+}

package/dist/core/src/plugin/registry.js

@@ -0,0 +1,92 @@
+// ============================================================================
+// Plugin registry — tracks discovered plugins and resolves load order.
+//
+// Mirrors `ModuleRegistry` but operates on `PluginManifest`s and resolves
+// order over BOTH `dependencies` (other plugin ids) and `requires` (stringly-
+// typed plugin resource keys). A plugin that `requires` a key must load
+// after whichever plugin `provides` it.
+// ============================================================================
+export class PluginRegistry {
+    manifests = new Map();
+    loadOrder = [];
+    register(manifest) {
+        if (this.manifests.has(manifest.id)) {
+            throw new Error(`Plugin "${manifest.id}" is already registered`);
+        }
+        this.manifests.set(manifest.id, manifest);
+        this.loadOrder.push(manifest.id);
+    }
+    unregister(id) {
+        this.manifests.delete(id);
+        const idx = this.loadOrder.indexOf(id);
+        if (idx >= 0)
+            this.loadOrder.splice(idx, 1);
+    }
+    get(id) {
+        return this.manifests.get(id);
+    }
+    has(id) {
+        return this.manifests.has(id);
+    }
+    getAll() {
+        return this.loadOrder.map((id) => this.manifests.get(id)).filter(Boolean);
+    }
+    /**
+     * Resolve load order via topological sort over `dependencies` + `requires`.
+     * Plugins with no dependencies/providers come first.
+     *
+     * Throws on:
+     *   - missing dependency (declared dep not registered)
+     *   - missing provider (requires a key nobody provides)
+     *   - cycle
+     */
+    resolveOrder() {
+        // Build provider map: resourceKey → plugin id that provides it.
+        const providers = new Map();
+        for (const m of this.getAll()) {
+            (m.provides ?? []).forEach((key) => {
+                if (providers.has(key)) {
+                    throw new Error(`Plugin resource "${key}" is provided by both "${providers.get(key)}" and "${m.id}".`);
+                }
+                providers.set(key, m.id);
+            });
+        }
+        const visited = new Set();
+        const result = [];
+        const visiting = new Set();
+        const visit = (id) => {
+            if (visited.has(id))
+                return;
+            if (visiting.has(id)) {
+                throw new Error(`Plugin dependency cycle detected at "${id}"`);
+            }
+            const m = this.manifests.get(id);
+            if (!m) {
+                throw new Error(`Plugin "${id}" is not registered (required as a dependency)`);
+            }
+            visiting.add(id);
+            // dependencies (other plugin ids)
+            (m.dependencies ?? []).forEach((dep) => {
+                const depId = dep.split("@")[0];
+                if (!this.manifests.has(depId)) {
+                    throw new Error(`Plugin "${id}" depends on "${depId}" which is not registered`);
+                }
+                visit(depId);
+            });
+            // requires (resource keys → provider plugin id)
+            (m.requires ?? []).forEach((key) => {
+                const providerId = providers.get(key);
+                if (!providerId) {
+                    throw new Error(`Plugin "${id}" requires resource "${key}" which no registered plugin provides`);
+                }
+                if (providerId !== id)
+                    visit(providerId);
+            });
+            visiting.delete(id);
+            visited.add(id);
+            result.push(id);
+        };
+        this.loadOrder.forEach((id) => { visit(id); ; });
+        return result;
+    }
+}

package/dist/core/src/plugin/sandbox-shim.js

@@ -0,0 +1,79 @@
+// ============================================================================
+// Sandbox shim — worker-side global restriction.
+//
+// Runs INSIDE the plugin's sandbox worker (sandbox-worker.ts) BEFORE the
+// plugin's entry module is imported. It deletes/overrides every global on
+// `self` that is NOT in the granted allowlist, then dynamically imports the
+// plugin entry.
+//
+// This is best-effort same-origin isolation. For strong security, remote
+// workshop plugins run from a blob:/data: origin with CSP (Phase 2).
+// ============================================================================
+import { BASELINE_GLOBALS, computeGlobalAllowlist } from "./permissions.js";
+/**
+ * Restrict `self` globals to the allowlist computed from `granted`.
+ * Replaces stripped globals with a throwing trap so a plugin that reaches for
+ * a denied capability gets a clear error rather than `undefined`.
+ */
+export function restrictGlobals(granted) {
+    const keep = computeGlobalAllowlist(granted);
+    const self = globalThis;
+    // Collect own + inherited enumerable keys of self.
+    const allKeys = new Set();
+    for (const k of Object.getOwnPropertyNames(self))
+        allKeys.add(k);
+    // Don't strip the host bridge or baseline runtime globals.
+    BASELINE_GLOBALS.forEach((g) => { keep.add(g); ; });
+    // Snapshot the original descriptors so the globals can be restored later.
+    const originals = new Map();
+    for (const key of allKeys.values()) {
+        if (keep.has(key))
+            continue;
+        // Skip non-configurable / non-writable props silently (can't delete them).
+        const desc = Object.getOwnPropertyDescriptor(self, key);
+        if (desc && !desc.configurable && !desc.writable)
+            continue;
+        if (!originals.has(key))
+            originals.set(key, desc);
+        try {
+            // Replace with a throwing trap so access yields a clear error.
+            Object.defineProperty(self, key, {
+                configurable: true,
+                get() {
+                    throw new Error(`[downdraft:plugin-sandbox] global "${key}" is not available — permission not granted.`);
+                },
+                set() {
+                    throw new Error(`[downdraft:plugin-sandbox] global "${key}" is not available — permission not granted.`);
+                },
+            });
+        }
+        catch {
+            // If defineProperty fails, try a plain delete.
+            try {
+                delete self[key];
+            }
+            catch {
+                /* give up — leave as-is */
+            }
+        }
+    }
+    return {
+        keep,
+        restore() {
+            for (const [key, desc] of originals.entries()) {
+                try {
+                    if (desc) {
+                        Object.defineProperty(self, key, desc);
+                    }
+                    else {
+                        delete self[key];
+                    }
+                }
+                catch {
+                    /* property may be non-configurable — leave as-is */
+                }
+            }
+            originals.clear();
+        },
+    };
+}