@poe-platform/safe-js 0.1.0

package/dist/safe-js/interp/budget.d.ts

@@ -0,0 +1,95 @@
+export type BudgetName = "steps" | "deadline" | "callDepth" | "stringLength" | "arrayLength" | "dataSize" | "dataDepth";
+export type BudgetOptions = {
+    maxSteps?: number;
+    deadline?: number | Date;
+    maxCallDepth?: number;
+    stringLength?: number;
+    arrayLength?: number;
+    dataSize?: number;
+};
+export declare const REGEX_STEP_LIMIT = 2000;
+export declare const REGEX_COMPILE_LIMITS: Readonly<{
+    sourceLength: 4096;
+    flagsLength: 8;
+    depth: 64;
+    allocations: 16384;
+}>;
+export declare class SandboxError extends Error {
+    readonly code: "aborted" | "budgetExceeded" | "reentry";
+    readonly budget?: BudgetName;
+    readonly current?: number;
+    readonly limit?: number;
+    constructor(input: "aborted");
+    constructor(input: "reentry");
+    constructor(input: {
+        budget: BudgetName;
+        current: number;
+        limit: number;
+    });
+}
+type BudgetLimits = {
+    maxSteps?: number;
+    maxCallDepth?: number;
+    stringLength?: number;
+    arrayLength?: number;
+    dataSize?: number;
+};
+export type CompileOwner = {
+    readonly budget: Budget;
+    readonly generation: number;
+};
+export type CompileTicket = {
+    readonly owner: CompileOwner;
+};
+export declare class Budget {
+    readonly deadline?: number;
+    readonly limits: Readonly<BudgetLimits>;
+    stepsUsed: number;
+    peakCallDepth: number;
+    currentDataSize: number;
+    peakDataSize: number;
+    currentCallDepth: number;
+    private allChecksSuspended;
+    private deadlineChecksSuspended;
+    private visitsUntilDeadlineCheck;
+    private retainedDataSize;
+    private readonly retainedData;
+    private readonly retainedValueSources;
+    private compileGeneration;
+    private activeCompileOwner?;
+    private compileUses;
+    private provisionalScopes;
+    private readonly compileTickets;
+    private readonly completedCompileTickets;
+    constructor(options?: BudgetOptions);
+    visitNode(): void;
+    allocateString(value: string): string;
+    allocateArrayLength(length: number): void;
+    allocateCollectionEntries(count: number): void;
+    reconcileDataUsage(usage: number): void;
+    setRetainedDataUsage(owner: object, usage: number): void;
+    setRetainedValues(owner: object, values: (() => Iterable<unknown>) | undefined): void;
+    retainedValues(): Iterable<unknown>;
+    acquireCompileOwner(reset?: boolean, owner?: CompileOwner): {
+        owner: CompileOwner;
+        release: () => void;
+    };
+    createCompileTicket(owner: CompileOwner): CompileTicket;
+    compileTicketUsage(ticket: CompileTicket): number;
+    resizeCompileTicket(ticket: CompileTicket, usage: number): void;
+    discardCompileTicket(ticket: CompileTicket): void;
+    reconcileCompileData(usage: number, included: ReadonlySet<CompileTicket>, transferred?: ReadonlySet<CompileTicket>, retainedOwner?: object, complete?: boolean): ReadonlySet<CompileTicket>;
+    chargeDataUsage(usage: number): void;
+    provisionDataUsage(usage: number): () => void;
+    enterCall(): () => void;
+    enterAwait(): () => void;
+    reset(): void;
+    suspendChecks(): () => void;
+    suspendDeadlineChecks(): () => void;
+    private checkDeadline;
+    private checkDataUsage;
+    private checkSampledDeadline;
+    private enterDepth;
+}
+export declare function allocateRegexSteps(steps: number): void;
+export {};

package/dist/safe-js/interp/exceptions.d.ts

@@ -0,0 +1,45 @@
+import type { BreakStatement, ContinueStatement, ParseResult, ThrowStatement, TryStatement } from "../parse.js";
+import { type SandboxErrorName, type ErrorSourceSpan } from "../error/shape.js";
+import { type Budget } from "./budget.js";
+import type { Scope } from "./scope.js";
+import { type SandboxObject, type SandboxValue } from "./values.js";
+declare const capturedExceptionBrand: unique symbol;
+export type { SandboxErrorName } from "../error/shape.js";
+export type CompletionKind = "normal" | "return" | "throw" | "break" | "continue";
+export type CompletionResult = {
+    kind: CompletionKind;
+    hasValue: boolean;
+    span?: ErrorSourceSpan;
+    stackFrames?: readonly string[];
+    value: SandboxValue;
+    label?: string;
+    node?: BreakStatement | ContinueStatement;
+};
+export type EvaluationResult<TError> = CompletionResult | {
+    kind: "error";
+    error: TError;
+};
+type CapturedException = {
+    readonly reason: unknown;
+    readonly sandbox: boolean;
+    readonly stackFrames: readonly string[];
+    readonly [capturedExceptionBrand]: true;
+};
+type ExceptionContext = {
+    budget: Budget;
+    callStack: readonly string[];
+    scope: Scope;
+};
+type EvaluateExceptionNode<TContext, TError> = (node: ParseResult, context: TContext) => Promise<EvaluationResult<TError>>;
+export declare function evaluateThrowStatement<TContext extends ExceptionContext, TError>(node: ThrowStatement, context: TContext, evaluateNode: EvaluateExceptionNode<TContext, TError>): Promise<EvaluationResult<TError>>;
+export declare function evaluateTryStatement<TContext extends ExceptionContext, TError>(node: TryStatement, context: TContext, evaluateNode: EvaluateExceptionNode<TContext, TError>): Promise<EvaluationResult<TError>>;
+export declare function createCapturedException(reason: unknown, stackFrames: readonly string[], sandbox?: boolean): CapturedException;
+export declare function isCapturedException(value: unknown): value is CapturedException;
+export declare function coerceThrownValue(reason: unknown, budget: Budget, stackFrames: readonly string[], span?: ErrorSourceSpan, sandbox?: boolean): SandboxValue;
+export declare function surfaceThrownValue(reason: unknown, budget: Budget, stackFrames?: readonly string[], span?: ErrorSourceSpan): SandboxObject;
+export declare function createSubsetErrorValue(name: string, message: SandboxValue, stackFrames: readonly string[], budget: Budget, options?: {
+    cause?: unknown;
+    chargeBudget?: boolean;
+    span?: ErrorSourceSpan;
+}): SandboxObject;
+export declare function isSandboxErrorConstructorInstance(value: SandboxValue, name: SandboxErrorName): boolean;

package/dist/safe-js/interp/generator.d.ts

@@ -0,0 +1,16 @@
+export type GeneratorCompletion = {
+    type: "normal" | "return" | "throw";
+    value: unknown;
+};
+export type GeneratorChannel = {
+    next(value?: unknown): Promise<IteratorResult<unknown>>;
+    return(value?: unknown): Promise<IteratorResult<unknown>>;
+    throw(error?: unknown): Promise<IteratorResult<unknown>>;
+    snapshot(): GeneratorChannelSnapshot;
+};
+export type GeneratorChannelSnapshot = {
+    yieldNodeId?: number;
+    sent: GeneratorCompletion[];
+};
+export declare function createGeneratorChannel(body: (yieldValue: (value?: unknown, yieldNodeId?: number) => Promise<GeneratorCompletion>) => Promise<unknown>): GeneratorChannel;
+export declare function restoreGeneratorChannel(body: Parameters<typeof createGeneratorChannel>[0], snapshot: GeneratorChannelSnapshot): GeneratorChannel;

package/dist/safe-js/interp/globals/console-json.d.ts

@@ -0,0 +1,14 @@
+import type { Budget, CompileOwner } from "../budget.js";
+import type { HostCallJournal } from "../host-call.js";
+import { type SandboxObject } from "../values.js";
+export type ConsoleSink = {
+    error: (...args: unknown[]) => void;
+    log: (...args: unknown[]) => void;
+};
+export type ConsoleJsonGlobalsOptions = {
+    budget: Budget;
+    compileOwner?: CompileOwner;
+    sink?: ConsoleSink;
+    hostCalls?: HostCallJournal;
+};
+export declare function createConsoleJsonGlobals(options: ConsoleJsonGlobalsOptions): Record<"JSON" | "console", SandboxObject>;

package/dist/safe-js/interp/host-bridge.d.ts

@@ -0,0 +1,29 @@
+import { type Budget, type CompileOwner } from "./budget.js";
+import { type PendingHostCallPolicyMode } from "../snapshot/policy.js";
+import { type HostCallJournal, type HostCallOutcome } from "./host-call.js";
+import { type SandboxClosure, type SandboxValue } from "./values.js";
+import type { RunLifecycle } from "../snapshot/dump.js";
+type CallerInjectedFunction = {
+    bivarianceHack(...args: readonly unknown[]): unknown;
+}["bivarianceHack"];
+type HostBridgeOptions = {
+    registerCapabilities?: boolean;
+    capabilityPath?: readonly string[];
+    budget: Budget;
+    compileOwner?: CompileOwner;
+    hostCalls?: HostCallJournal;
+    moduleId?: string;
+    operation?: string;
+    signal?: AbortSignal;
+    lifecycle?: RunLifecycle;
+    proofFunctions?: WeakMap<object, SandboxClosure>;
+};
+export type CallerInjectedBinding = SandboxValue | CallerInjectedFunction | readonly CallerInjectedBinding[] | {
+    readonly [key: string]: CallerInjectedBinding;
+};
+export declare function declareHostOperation<TFunction extends CallerInjectedFunction>(operation: TFunction, policy: PendingHostCallPolicyMode, options?: {
+    onReplay?: (args: readonly unknown[], outcome: HostCallOutcome) => void;
+}): TFunction;
+export declare function readHostOperationPolicy(operation: CallerInjectedFunction): PendingHostCallPolicyMode | undefined;
+export declare function wrapCallerInjectedBindings(bindings: Record<string, CallerInjectedBinding>, options: HostBridgeOptions): Record<string, SandboxValue>;
+export {};

package/dist/safe-js/interp/host-call.d.ts

@@ -0,0 +1,130 @@
+import { type SandboxClosure, type SandboxValue } from "./values.js";
+import type { Budget, CompileOwner } from "./budget.js";
+import { type ReplayData } from "../snapshot/replay-data.js";
+import { type PendingHostCallPolicyMode } from "../snapshot/policy.js";
+export type HostCallLifecycle = "created" | "running" | "settled" | "consumed" | "cancelled";
+export type HostCallOutcome = {
+    status: "fulfilled";
+    value: SandboxValue;
+} | {
+    status: "rejected";
+    reason: SandboxValue;
+};
+export type HostCallRecord = {
+    id: string;
+    runId: string;
+    sourceHash: string;
+    moduleId: string;
+    operation: string;
+    argumentDigest: string;
+    policy: PendingHostCallPolicyMode;
+    lifecycle: HostCallLifecycle;
+    outcome?: HostCallOutcome;
+    asynchronous?: boolean;
+    callbacks?: Array<{
+        id: number;
+        step: number;
+        arguments: ReplayData;
+    }>;
+    functions?: number[];
+};
+export type HostCallReplay = {
+    version: 1;
+    calls: Array<Omit<HostCallRecord, "outcome" | "asynchronous"> & {
+        asynchronous: boolean;
+        outcome?: {
+            status: "fulfilled" | "rejected";
+            data: ReplayData;
+        };
+    }>;
+};
+export type HostCallResumeProof = {
+    callId: string;
+    sourceHash: string;
+    moduleId: string;
+    operation: string;
+    argumentDigest: string;
+    outcome: HostCallOutcome;
+    callbackDisposition?: "joined" | "detached";
+};
+export type HostCallResumeContext = {
+    callbacks: ReadonlyMap<number, (...args: readonly unknown[]) => Promise<unknown>>;
+    replayed: ReadonlyArray<{
+        callbackId: number;
+        result: Promise<unknown>;
+    }>;
+    waitForCallbacks: () => Promise<void>;
+    toSandboxValue: (value: unknown) => SandboxValue;
+};
+export type HostCallResumeRequest = Omit<HostCallRecord, "id" | "outcome"> & {
+    callId: string;
+    requirement: "external-reconciliation";
+};
+export type HostCallResumeProvider = (request: HostCallResumeRequest, context?: HostCallResumeContext) => HostCallResumeProof | Promise<HostCallResumeProof>;
+export declare class HostCallResumabilityError extends Error {
+    #private;
+    readonly action: "reset" | "external-reconciliation";
+    readonly callId: string;
+    readonly lifecycle: HostCallLifecycle;
+    static [Symbol.hasInstance](value: unknown): boolean;
+    constructor(record: HostCallRecord, action: "reset" | "external-reconciliation", message: string);
+}
+export declare class UnresolvedReplayCapabilityError extends TypeError {
+    readonly id: string;
+    constructor(id: string);
+}
+export declare class HostCallJournal {
+    private readonly sourceHash;
+    private readonly resumeProvider?;
+    private budget?;
+    private compileOwner?;
+    readonly runId: string;
+    private nextCall;
+    private readonly records;
+    private readonly restored;
+    private readonly outcomes;
+    private readonly recordedReplay;
+    private retainedSize;
+    private readonly outcomeSizes;
+    private readonly capabilities;
+    private readonly requiredHostCapabilities;
+    private readonly capabilityIds;
+    readonly nativeClosures: WeakMap<object, SandboxClosure>;
+    private readonly hostSources;
+    private readonly encodedOutcomes;
+    private readonly callbackSizes;
+    private readonly completedCallbackOwners;
+    private readonly capabilityWaiters;
+    readonly identifyCapability: (key: SandboxClosure) => string | undefined;
+    readonly resolveCapability: (id: string) => SandboxClosure;
+    constructor(sourceHash: string, records?: readonly HostCallRecord[], resumeProvider?: HostCallResumeProvider | undefined, replay?: unknown, budget?: Budget | undefined, compileOwner?: CompileOwner | undefined);
+    issue(input: {
+        moduleId: string;
+        operation: string;
+        argumentDigest: string;
+        policy: PendingHostCallPolicyMode;
+    }): {
+        record: HostCallRecord;
+        restored: boolean;
+    };
+    private createRecord;
+    start(record: HostCallRecord): void;
+    settle(record: HostCallRecord, outcome: HostCallOutcome): void;
+    consume(record: HostCallRecord): void;
+    cancel(record: HostCallRecord, reason: SandboxValue): void;
+    reconcile(record: HostCallRecord, context?: HostCallResumeContext): Promise<HostCallOutcome>;
+    snapshot(): HostCallRecord[];
+    dispose(): void;
+    registerCallbackFunction(record: HostCallRecord, id: number, closure: SandboxClosure, native: object): void;
+    registerHostCapability(path: string, closure: SandboxClosure, native: object): void;
+    rebindHostCapability(original: SandboxClosure, restored: SandboxClosure): void;
+    validateHostCapabilities(): void;
+    waitForCapability(id: string): Promise<void>;
+    trackCallbackCompletion(record: HostCallRecord, callbacks: readonly Promise<unknown>[]): void;
+    recordCallback(record: HostCallRecord, id: number, args: SandboxValue[], step: number): string;
+    callbackPositions(): ReadonlyMap<string, number>;
+    private retainOutcome;
+    replayOutcome(record: HostCallRecord): HostCallOutcome | undefined;
+    snapshotReplay(): HostCallReplay;
+}
+export declare function digestHostCallArguments(args: readonly unknown[]): string;

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

@@ -0,0 +1,63 @@
+import type { ParseResult, SourceSpan } from "../parse.js";
+import { type InterpreterYieldPoint } from "./async.js";
+import type { GeneratorCompletion } from "./generator.js";
+import { Budget, type CompileOwner } from "./budget.js";
+import { CompileScope } from "./regex/compile-guard.js";
+import { type SandboxValue } from "./values.js";
+import { Scope } from "./scope.js";
+export type InterpreterValue = SandboxValue;
+export type InterpreterStats = {
+    nodeVisits: number;
+    currentDataSize: number;
+    peakDataSize: number;
+};
+export type InterpreterSnapshot = {
+    bindings: Record<string, InterpreterValue>;
+    loopIterations?: Record<string, LoopIterationSnapshot>;
+    resumeNodeId?: number;
+};
+export type LoopIterationSnapshot = number | {
+    index: number;
+    values: InterpreterValue[];
+};
+export type InterpreterErrorCode = "LABEL_NOT_FOUND" | "UNBOUND_IDENTIFIER" | "UNSUPPORTED_NODE";
+export type InterpreterError = {
+    code: InterpreterErrorCode;
+    message: string;
+    name: string;
+    nodeId?: number;
+    nodeType: ParseResult["type"];
+    span: SourceSpan;
+    stack: string;
+};
+export type InterpreterResult = {
+    ok: true;
+    returnValue?: InterpreterValue;
+    snapshot: InterpreterSnapshot;
+    stats: InterpreterStats;
+} | {
+    ok: false;
+    error: InterpreterError;
+    snapshot: InterpreterSnapshot;
+    stats: InterpreterStats;
+};
+export type InterpretOptions = {
+    compilation?: CompileScope;
+    compileOwner?: CompileOwner;
+    captureReplayState?: () => unknown;
+    bindings?: Record<string, InterpreterValue>;
+    budget?: Budget;
+    onYield?: (yieldPoint: InterpreterYieldPoint) => void;
+    scope?: Scope;
+    signal?: AbortSignal;
+    surfaceUnhandledThrows?: boolean;
+    useScopeDirectly?: boolean;
+    generatorYield?: (value?: SandboxValue, yieldNodeId?: number) => Promise<GeneratorCompletion>;
+    generatorResume?: {
+        sent: GeneratorCompletion[];
+        yieldNodeId: number;
+    };
+    snapshot?: InterpreterSnapshot;
+};
+export declare function interpret(node: ParseResult, options?: InterpretOptions): Promise<InterpreterResult>;
+export { Scope } from "./scope.js";

package/dist/safe-js/interp/promise-replay.d.ts

@@ -0,0 +1,70 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { type Budget } from "./budget.js";
+type ReplayEvent = {
+    kind: "promise";
+    id: number;
+    step: number;
+} | {
+    kind: "callback-start";
+    token: string;
+    step: number;
+    promises: number;
+} | {
+    kind: "callback-end";
+    token: string;
+    step: number;
+};
+export type PromiseReplaySnapshot = {
+    version: 1;
+    steps: number;
+    promises: number;
+    settlements: Array<{
+        id: number;
+        step: number;
+    }>;
+    events?: ReplayEvent[];
+    executionTrace?: {
+        start: number;
+        nodes: number[];
+    };
+};
+export declare class PromiseReplay {
+    private steps;
+    private nextPromise;
+    private position;
+    private readonly replaying;
+    private readonly restored;
+    private readonly restoredEvents;
+    private readonly events;
+    private readonly ready;
+    private readonly callbackTasks;
+    private readonly completedCallbacks;
+    private readonly rejectors;
+    private failure?;
+    private callbackCount;
+    private readonly waiting;
+    private readonly liveWaiters;
+    private budget?;
+    private executionTrace?;
+    constructor(snapshot?: unknown);
+    get currentStep(): number;
+    beforeNode(nodeId?: number): void | Promise<void>;
+    track<TValue>(promise: Promise<TValue>): Promise<TValue>;
+    beginCallback(token: string): void;
+    completeCallback(token: string): void;
+    waitForLiveExecution(): void | Promise<void>;
+    registerCallbacks(callbacks: ReadonlyArray<{
+        token: string;
+        start: () => void;
+    }>): void;
+    private assertHealthy;
+    fail(reason: unknown): void;
+    validateCallbacks(positions: ReadonlyMap<string, number>): void;
+    validateNodes(root: object): void;
+    snapshot(): PromiseReplaySnapshot;
+    attachBudget(budget: Budget): void;
+    dispose(): void;
+    private drain;
+}
+export declare const promiseReplayContext: AsyncLocalStorage<PromiseReplay>;
+export {};

package/dist/safe-js/interp/regex/compile-guard.d.ts

@@ -0,0 +1,33 @@
+import { type CompileOwner, type CompileTicket } from "../budget.js";
+import type { RegexPattern } from "./parse.js";
+export declare class CompileScope {
+    readonly owner?: CompileOwner | undefined;
+    readonly parent?: CompileScope | undefined;
+    readonly tickets: Set<CompileTicket>;
+    closed: boolean;
+    constructor(owner?: CompileOwner | undefined, parent?: CompileScope | undefined);
+    forward(tickets: Iterable<CompileTicket>, parent: CompileScope): void;
+    dispose(): void;
+}
+export declare class RegexCompileGuard {
+    private readonly scope?;
+    private allocations;
+    private depth;
+    private readonly ticket?;
+    private retained;
+    constructor(scope?: CompileScope | undefined);
+    checkLength(length: number, flags?: boolean): void;
+    work(units: number): void;
+    allocate(units: number): void;
+    array(length: number): void;
+    enterGroup(): void;
+    leaveGroup(): void;
+    preflight(source: string, flags: string): void;
+    retain(pattern: RegexPattern, valueUnits?: number): void;
+    retainScratch(): void;
+    close(): void;
+}
+export declare function regexCompiledData(pattern: RegexPattern): {
+    units: number;
+    ticket?: CompileTicket;
+};

package/dist/safe-js/interp/regex/parse.d.ts

@@ -0,0 +1,62 @@
+import { type CompileScope } from "./compile-guard.js";
+export type RegexFlags = {
+    global: boolean;
+    ignoreCase: boolean;
+    multiline: boolean;
+    dotAll: boolean;
+};
+export type CharacterKind = "digit" | "word" | "space";
+export type CharacterClassItem = {
+    type: "character";
+    value: string;
+} | {
+    type: "range";
+    from: string;
+    to: string;
+} | {
+    type: "kind";
+    kind: CharacterKind;
+    negated: boolean;
+};
+export type RegexNode = {
+    type: "empty";
+} | {
+    type: "literal";
+    value: string;
+} | {
+    type: "dot";
+} | {
+    type: "anchor";
+    kind: "start" | "end";
+} | {
+    type: "wordBoundary";
+    negated: boolean;
+} | {
+    type: "characterClass";
+    negated: boolean;
+    items: CharacterClassItem[];
+} | {
+    type: "sequence";
+    elements: RegexNode[];
+} | {
+    type: "alternation";
+    alternatives: RegexNode[];
+} | {
+    type: "group";
+    capturing: boolean;
+    index?: number;
+    body: RegexNode;
+} | {
+    type: "quantifier";
+    body: RegexNode;
+    min: number;
+    max?: number;
+    greedy: boolean;
+};
+export type RegexPattern = {
+    source: string;
+    flags: RegexFlags;
+    captureCount: number;
+    body: RegexNode;
+};
+export declare function parseRegex(source: string, flags?: string, compilation?: CompileScope, valueUnits?: number): RegexPattern;

package/dist/safe-js/interp/scope.d.ts

@@ -0,0 +1,43 @@
+import type { VariableDeclarationKind } from "../parse.js";
+import type { InterpreterSnapshot, InterpreterValue } from "./interpreter.js";
+type ScopeLookupResult = {
+    found: true;
+    kind: VariableDeclarationKind;
+    value: InterpreterValue;
+} | {
+    found: false;
+};
+type ScopeOptions = {
+    functionBoundary?: boolean;
+    chargeData?: boolean;
+};
+export declare class Scope {
+    #private;
+    private readonly parent?;
+    private readonly importMeta?;
+    private readonly options;
+    constructor(bindings?: Record<string, InterpreterValue>, parent?: Scope | undefined, importMeta?: InterpreterValue, options?: ScopeOptions, restoredBindings?: Record<string, InterpreterValue>);
+    child(bindings?: Record<string, InterpreterValue>, options?: ScopeOptions): Scope;
+    consumeRestoredBinding(name: string): {
+        found: true;
+        value: InterpreterValue;
+    } | {
+        found: false;
+    };
+    hasOwnBinding(name: string): boolean;
+    getOwnBindingKind(name: string): VariableDeclarationKind | undefined;
+    isFunctionBoundary(): boolean;
+    iterationChild(names: readonly string[]): Scope;
+    lookupImportMeta(): InterpreterValue;
+    retainedValues(): InterpreterValue[];
+    declare(name: string, kind: VariableDeclarationKind, value: InterpreterValue): void;
+    declareVar(name: string): void;
+    predeclare(name: string, kind: VariableDeclarationKind): void;
+    assign(name: string, value: InterpreterValue): void;
+    lookup(name: string): ScopeLookupResult;
+    snapshot(): InterpreterSnapshot;
+    copyInitializedBindingsFrom(source: Scope, names: readonly string[]): void;
+    private resolveScope;
+    private requireInitializedBinding;
+}
+export {};