poe-code 14.0.5 → 14.0.6

package/packages/safe-js/dist/interp/host-capabilities.js

@@ -0,0 +1,123 @@
+import { readDataRecord } from "../extensions.js";
+const hostObjects = new WeakMap();
+const guestObjects = new WeakMap();
+const guestCallbacks = new WeakMap();
+export function createLiveHostObject(definition, controller) {
+    const input = readDataRecord(definition, "Host object definition");
+    if (Object.keys(input).some((key) => key !== "properties" && key !== "methods"))
+        throw new TypeError("Unknown host object definition field.");
+    const properties = new Map();
+    for (const [name, inputProperty] of Object.entries(readDataRecord(input.properties ?? {}, "Host properties"))) {
+        const property = readDataRecord(inputProperty, `Host property '${name}'`);
+        if (Object.keys(property).some((key) => key !== "get" && key !== "set"))
+            throw new TypeError("Unknown host property field.");
+        if ((property.get !== undefined && typeof property.get !== "function") ||
+            (property.set !== undefined && typeof property.set !== "function"))
+            throw new TypeError("Host property operations must be functions.");
+        properties.set(name, property);
+    }
+    const operations = readDataRecord(input.methods ?? {}, "Host methods");
+    for (const [name, operation] of Object.entries(operations)) {
+        if (typeof operation !== "function")
+            throw new TypeError("Host methods must be functions.");
+        if (properties.has(name))
+            throw new TypeError(`Conflicting host member '${name}'.`);
+    }
+    for (const name of [...properties.keys(), ...Object.keys(operations)]) {
+        if (["constructor", "prototype", "__proto__"].includes(name))
+            throw new TypeError(`Reserved host member '${name}'.`);
+    }
+    controller.assertActive();
+    controller.chargeWork(properties.size + Object.keys(operations).length + 1);
+    const host = Object.freeze(Object.create(null));
+    const guest = Object.freeze(Object.create(null));
+    const methods = new Map(Object.entries(operations).map(([name, operation]) => [
+        name,
+        controller.method(operation)
+    ]));
+    const state = { host, guest, controller, properties, methods };
+    hostObjects.set(host, state);
+    guestObjects.set(guest, state);
+    return host;
+}
+export function isGuestHostObject(value) {
+    return typeof value === "object" && value !== null && guestObjects.has(value);
+}
+export function isLiveCapability(value) {
+    return (((typeof value === "object" && value !== null) || typeof value === "function") &&
+        (hostObjects.has(value) || guestObjects.has(value) || guestCallbacks.has(value)));
+}
+export function importHostCapability(value, owner) {
+    const object = hostObjects.get(value);
+    if (object !== undefined) {
+        if (object.controller.owner !== owner)
+            throw new TypeError("Foreign realm host capability.");
+        object.controller.assertActive();
+        return object.guest;
+    }
+    const callback = guestCallbacks.get(value);
+    if (callback !== undefined) {
+        if (callback.owner !== owner)
+            throw new TypeError("Foreign realm guest callback.");
+        callback.assertActive();
+        if (callback.closure === undefined)
+            throw new TypeError("Guest callback is revoked.");
+        return callback.closure;
+    }
+    throw new TypeError("Unsupported live capability conversion.");
+}
+export function exportHostCapability(value, owner) {
+    const state = guestObjects.get(value);
+    if (state === undefined || state.controller.owner !== owner)
+        throw new TypeError("Foreign realm host capability.");
+    state.controller.assertActive();
+    return state.host;
+}
+export function registerGuestCallback(callback, state) {
+    guestCallbacks.set(callback, state);
+}
+export function readGuestCallback(callback, owner) {
+    const state = typeof callback === "function" ? guestCallbacks.get(callback) : undefined;
+    if (state === undefined || state.owner !== owner)
+        throw new TypeError("Foreign or invalid guest callback.");
+    state.assertActive();
+    if (state.closure === undefined)
+        throw new TypeError("Guest callback is revoked.");
+    return state.closure;
+}
+export function revokeGuestCallback(callback, owner) {
+    const state = guestCallbacks.get(callback);
+    if (state === undefined || state.owner !== owner)
+        throw new TypeError("Foreign guest callback.");
+    state.closure = undefined;
+}
+export function revokeHostObject(value, owner) {
+    const state = hostObjects.get(value);
+    if (state === undefined || state.controller.owner !== owner)
+        throw new TypeError("Foreign host object.");
+    state.properties.clear();
+    state.methods.clear();
+}
+export function getHostObjectMember(value, key) {
+    const state = guestObjects.get(value);
+    state.controller.assertActive();
+    state.controller.chargeWork();
+    const property = state.properties.get(key);
+    if (property !== undefined)
+        return property.get === undefined ? undefined : state.controller.read(property.get);
+    return state.methods.get(key);
+}
+export function setHostObjectMember(value, key, entry) {
+    const state = guestObjects.get(value);
+    state.controller.assertActive();
+    state.controller.chargeWork();
+    const property = state.properties.get(key);
+    if (property?.set === undefined)
+        throw new TypeError(`Host property '${key}' is not writable.`);
+    state.controller.write(property.set, entry);
+}
+export function getHostObjectKeys(value) {
+    const state = guestObjects.get(value);
+    state.controller.assertActive();
+    return [...state.properties.keys(), ...state.methods.keys()];
+}

package/packages/safe-js/dist/interp/interpreter.d.ts

@@ -1,3 +1,4 @@
+import { SandboxJobQueue } from "./jobs.js";
 import type { ParseResult, SourceSpan } from "../parse.js";
 import { type AsyncEvaluationContext, type AsyncEvaluationResult, type InterpreterYieldPoint } from "./async.js";
 import type { GeneratorCompletion } from "./generator.js";
@@ -43,6 +44,9 @@ export type InterpreterResult = {
     stats: InterpreterStats;
 };
 export type InterpretOptions = {
+    assertActive?: () => void;
+    jobs?: SandboxJobQueue;
+    nested?: boolean;
     compilation?: CompileScope;
     compileOwner?: CompileOwner;
     captureReplayState?: () => unknown;

package/packages/safe-js/dist/interp/interpreter.js

@@ -1,6 +1,7 @@
 import { promiseReplayContext } from "./promise-replay.js";
+import { getHostObjectKeys, getHostObjectMember, isGuestHostObject, setHostObjectMember } from "./host-capabilities.js";
 import { assertPromiseExecutionAllowed } from "./promise-tracker.js";
-import { SandboxJobQueue, suspendJob } from "./jobs.js";
+import { SandboxJobQueue, runAsyncPrefix, suspendJob } from "./jobs.js";
 import { withCancellationSignal } from "./cancel.js";
 import { attachErrorSpan, formatErrorStack, readErrorSpan, replaceErrorStack } from "../error/shape.js";
 import { evaluateArrowFunctionExpression, evaluateFunctionExpression, evaluateAwaitExpression, emitResumeBreakpoint, createInterpretedClosure, normalizeClosureResult } from "./async.js";
@@ -98,9 +99,10 @@ export async function interpret(node, options = {}) {
             peakDataSize: { enumerable: false, value: 0, writable: true }
         });
         const activeLoopIterations = new Map();
-        const jobs = new SandboxJobQueue();
+        const jobs = options.jobs ?? new SandboxJobQueue();
         hoistVarDeclarations(node, scope);
         const context = {
+            assertActive: options.assertActive,
             compilation,
             budget,
             callStack: [],
@@ -119,8 +121,9 @@ export async function interpret(node, options = {}) {
             generatorYield: options.generatorYield,
             resumeTarget: { nodeId: options.snapshot?.resumeNodeId }
         };
-        const evaluation = await withCancellationSignal(options.signal, () => jobs.run(() => evaluateNode(node, context)));
-        await jobs.drain();
+        const evaluation = await withCancellationSignal(options.signal, () => options.nested ? runAsyncPrefix(() => evaluateNode(node, context)) : jobs.run(() => evaluateNode(node, context)));
+        if (!options.nested)
+            await jobs.drain();
         const snapshot = scope.snapshot();
         reconcileDataBudget(budget, stats, scope, "hasValue" in evaluation && evaluation.hasValue ? evaluation.value : undefined, compilation, options.compilation);
         if (evaluation.kind === "error") {
@@ -167,6 +170,7 @@ export async function interpret(node, options = {}) {
 }
 export { Scope } from "./scope.js";
 async function evaluateNode(node, context) {
+    context.assertActive?.();
     const replayWait = promiseReplayContext.getStore()?.beforeNode(node.nodeId);
     if (replayWait !== undefined)
         await suspendJob(replayWait);
@@ -1119,6 +1123,8 @@ function forInObject(value) {
     return undefined;
 }
 function forInKeys(object, budget) {
+    if (isGuestHostObject(object))
+        return getHostObjectKeys(object);
     const keys = [];
     const seen = new Set();
     let depth = 0;
@@ -1140,6 +1146,8 @@ function forInKeys(object, budget) {
     return keys;
 }
 function hasForInProperty(object, key, budget) {
+    if (isGuestHostObject(object))
+        return getHostObjectKeys(object).includes(key);
     let depth = 0;
     for (let current = object; current !== null; current = getSandboxPrototype(current)) {
         if (depth > 0)
@@ -1630,6 +1638,8 @@ async function evaluateMemberExpression(node, context) {
     };
 }
 function getPropertyValue(target, property, context) {
+    if (isGuestHostObject(target))
+        return getHostObjectMember(target, String(property));
     if (typeof target === "string")
         return getStringMember(target, property, context.budget);
     if (typeof target === "number")
@@ -2284,6 +2294,8 @@ function isPlainSandboxObject(value) {
         !isSandboxRegex(value));
 }
 function getMemberValue(target, property, context) {
+    if (isGuestHostObject(target))
+        return getHostObjectMember(target, String(property));
     let current = target;
     let depth = 0;
     while (typeof current === "object" && current !== null) {
@@ -2311,6 +2323,10 @@ function getArrayMemberValue(target, property, context) {
     return getArrayMember(target, property, createArrayMethodOptions(context));
 }
 export function setSandboxProperty(target, property, value, budget) {
+    if (isGuestHostObject(target)) {
+        setHostObjectMember(target, String(property), value);
+        return;
+    }
     const prototypeOwner = target;
     if (isGuestClosure(target))
         target = materializeFunctionProperties(target);
@@ -2359,6 +2375,8 @@ export function setSandboxProperty(target, property, value, budget) {
     }
 }
 function deleteSandboxProperty(target, property) {
+    if (isGuestHostObject(target))
+        throw new TypeError("Live host properties cannot be deleted.");
     if (isGuestClosure(target))
         target = materializeFunctionProperties(target);
     if (Array.isArray(target)) {

package/packages/safe-js/dist/interp/object-model.js

@@ -1,4 +1,5 @@
 import { assertSandboxDataDepth } from "../graph-depth.js";
+import { getHostObjectMember, isGuestHostObject, isLiveCapability } from "./host-capabilities.js";
 import { isSandboxClosure, isSandboxGenerator, isSandboxMap, isSandboxPromise, isSandboxRegex, isSandboxSet } from "./values.js";
 const guestClosures = new WeakSet();
 const functionProperties = new WeakMap();
@@ -62,6 +63,8 @@ export function getSandboxDataProperty(value, key, budget) {
     let current = value;
     let depth = 0;
     while (typeof current === "object" && current !== null) {
+        if (isGuestHostObject(current))
+            return getHostObjectMember(current, String(key));
         if (isGuestClosure(current))
             return getGuestFunctionProperty(current, String(key));
         if (isSandboxClosure(current)) {
@@ -108,6 +111,8 @@ export function setSandboxPrototype(value, prototype, budget) {
         prototypes.set(value, prototype);
 }
 function isPrototypeRecord(value) {
+    if (isGuestHostObject(value))
+        return false;
     if (isSandboxClosure(value) ||
         isSandboxGenerator(value) ||
         isSandboxMap(value) ||
@@ -125,6 +130,8 @@ export function hasManagedDescriptors(value) {
     return descriptorObjects.has(value);
 }
 export function hasGuestObjectState(value) {
+    if (isLiveCapability(value))
+        return true;
     if (functionProperties.has(value) || prototypes.has(value))
         return true;
     return (descriptorObjects.has(value) &&

package/packages/safe-js/dist/interp/values.d.ts

@@ -86,6 +86,7 @@ export type SandboxGenerator = {
 };
 type CopyFromSandboxOptions = {
     wrapClosure?: (value: SandboxClosure) => unknown;
+    unwrapHostObject?: (value: SandboxObject) => unknown;
     compilation?: CompileScope;
 };
 export declare function createSandboxClosure(input: {

package/packages/safe-js/dist/interp/values.js

@@ -1,4 +1,5 @@
 import { bindOtelSpan, getBoundOtelSpan } from "../observability/otel.js";
+import { getHostObjectKeys, getHostObjectMember, isGuestHostObject, isLiveCapability } from "./host-capabilities.js";
 import { types as nodeTypes } from "node:util";
 import { CompileScope, RegexCompileGuard, regexCompiledData } from "./regex/compile-guard.js";
 import { copyFloat32Storage, float32DataProperties, float32Storage, isFloat32Array } from "./float32.js";
@@ -70,6 +71,8 @@ export function createSandboxClosure(input) {
     return Object.freeze(closure);
 }
 export function ownEnumerableSandboxEntries(value) {
+    if (isGuestHostObject(value))
+        return getHostObjectKeys(value).map(key => [key, getHostObjectMember(value, key)]);
     if (value === null || value === undefined)
         throw new TypeError("Cannot convert undefined or null to object.");
     if (isGuestClosure(value))
@@ -222,6 +225,11 @@ export function measureSandboxData(values, options = {}) {
         assertSandboxDataDepth(depth);
         seen.add(value);
         usage += 1;
+        if (isGuestHostObject(value)) {
+            for (const key of getHostObjectKeys(value))
+                usage += key.length + 1;
+            return;
+        }
         const prototype = getSandboxPrototype(value);
         if (prototype !== null)
             visit(prototype, depth + 1);
@@ -376,6 +384,8 @@ function copyToSandbox(value, state, path = "<root>", cloneSandboxCollections =
     if (isSandboxPrimitive(value)) {
         return value;
     }
+    if (isLiveCapability(value))
+        throw new TypeError("Live capabilities require their owning realm bridge.");
     if (isSandboxClosure(value) ||
         isSandboxGenerator(value) ||
         isSandboxRegex(value) ||
@@ -508,6 +518,11 @@ function copyFromSandbox(value, state, path = "<root>", options, depth = 0) {
     if (isSandboxPrimitive(value)) {
         return value;
     }
+    if (isGuestHostObject(value)) {
+        if (options.unwrapHostObject === undefined)
+            throw new TypeError("Live capabilities require their owning realm bridge.");
+        return options.unwrapHostObject(value);
+    }
     if (nodeTypes.isProxy(value))
         throw new TypeError("Unsupported proxy sandbox value.");
     if (!isSandboxClosure(value) && hasGuestObjectState(value)) {

package/packages/safe-js/dist/modules/registry.d.ts

@@ -1,6 +1,6 @@
 import type { Budget, CompileOwner } from "../interp/budget.js";
 import type { HostCallJournal } from "../interp/host-call.js";
-import { type CallerInjectedBinding } from "../interp/host-bridge.js";
+import { type RealmBridge, type CallerInjectedBinding } from "../interp/host-bridge.js";
 import type { SandboxValue } from "../interp/values.js";
 import type { Module } from "../parse/parser.js";
 export type ModuleExports = ReadonlyMap<string, CallerInjectedBinding> | Record<string, CallerInjectedBinding>;
@@ -9,6 +9,8 @@ export declare function createUnknownModuleMessage(moduleName: string, moduleNam
 export declare function createUnknownExportMessage(moduleName: string, exportName: string, availableExports: readonly string[]): string;
 export declare function resolveModuleImports(module: Module, modules: ModuleRegistry | undefined, options: {
     budget: Budget;
+    realm?: RealmBridge;
+    wrappedModules?: Map<string, Record<string, SandboxValue>>;
     compileOwner?: CompileOwner;
     hostCalls?: HostCallJournal;
     signal?: AbortSignal;

package/packages/safe-js/dist/modules/registry.js

@@ -17,7 +17,7 @@ export function createUnknownExportMessage(moduleName, exportName, availableExpo
 export function resolveModuleImports(module, modules, options) {
     const registry = normalizeModuleRegistry(modules);
     const bindings = createBindingRecord();
-    const wrappedModules = new Map();
+    const wrappedModules = options.wrappedModules ?? new Map();
     for (const statement of module.body) {
         if (statement.type !== "ImportDeclaration") {
             continue;
@@ -36,6 +36,7 @@ function bindImportDeclaration(declaration, registry, wrappedModules, bindings,
     }
     const wrappedExports = wrappedModules.get(moduleName) ??
         createBindingRecord(wrapCancelableBindings(wrapCallerInjectedBindings(Object.fromEntries(moduleExports), {
+            realm: options.realm,
             budget: options.budget,
             compileOwner: options.compileOwner,
             hostCalls: options.hostCalls,

package/packages/safe-js/dist/realm.d.ts

@@ -0,0 +1,43 @@
+import { Budget } from "./interp/budget.js";
+import { type InterpreterResult } from "./interp/interpreter.js";
+import { type CallerInjectedBinding } from "./interp/host-bridge.js";
+import { type CallbackOptions, type SafeJSExtension } from "./extensions.js";
+import { type ModuleRegistry } from "./modules/registry.js";
+import type { ConsoleSink } from "./interp/globals/console-json.js";
+import type { RunOptions, RunResult } from "./run.js";
+export type RealmLimits = {
+    extensions?: number;
+    hostObjects?: number;
+    callbacks?: number;
+    cleanups?: number;
+    nestedEvaluations?: number;
+};
+export type RealmOptions = {
+    bindings?: Record<string, CallerInjectedBinding>;
+    modules?: ModuleRegistry;
+    extensions?: readonly SafeJSExtension[];
+    grants?: readonly string[];
+    budget?: Budget;
+    signal?: AbortSignal;
+    sink?: ConsoleSink;
+    randomSeed?: number;
+    limits?: RealmLimits;
+};
+export type RealmResult = (Omit<Extract<InterpreterResult, {
+    ok: true;
+}>, "snapshot" | "returnValue"> & {
+    returnValue?: unknown;
+}) | Omit<Extract<InterpreterResult, {
+    ok: false;
+}>, "snapshot">;
+export type SafeJSRealm = {
+    readonly extensions: readonly SafeJSExtension["manifest"][];
+    evaluate(source: string, options?: {
+        filename?: string;
+    }): Promise<RealmResult>;
+    invokeCallback(callback: unknown, options?: CallbackOptions): Promise<unknown>;
+    releaseCallback(callback: unknown): void;
+    close(): Promise<void>;
+};
+export declare function createRealm(options?: RealmOptions): SafeJSRealm;
+export declare function runWithExtensions(source: string, options: RunOptions): Promise<RunResult>;