@questpie/sandbox 3.16.0 → 3.17.0

package/dist/adapter-http-DDeL-Ym3.d.mts

@@ -0,0 +1,259 @@
+import { a as SandboxCustomToolsRunOptions } from "./custom-tools-CgfgyVNv.mjs";
+import { ExecutorAdapter, ExecutorRunOptions, ExecutorRunResult } from "questpie/executor";
+
+//#region src/workload-admission.d.ts
+interface SandboxWorkloadAdmissionClaims {
+  readonly kind: "sandbox_workload_admission";
+  readonly version: 1;
+  readonly admissionId: string;
+  readonly supervisorInstanceId: string;
+  readonly expiresAt: string;
+  readonly requestSha256: string;
+}
+interface SandboxWorkloadAdmissionKey {
+  readonly keyId: string;
+  readonly secret: Uint8Array;
+  /** Unique per supervisor process; rotate on every restart. */
+  readonly instanceId: string;
+}
+type SandboxWorkloadAdmissionDenialReason = "invalid" | "wrong_instance" | "expired" | "body_mismatch";
+type SandboxWorkloadAdmissionVerification = {
+  readonly ok: true;
+  readonly claims: SandboxWorkloadAdmissionClaims;
+} | {
+  readonly ok: false;
+  readonly reason: SandboxWorkloadAdmissionDenialReason;
+  readonly claims?: SandboxWorkloadAdmissionClaims;
+};
+//#endregion
+//#region src/types.d.ts
+/**
+ * Wire contract between the `executor` adapter (Bun/Node, main app) and the
+ * standalone Deno sandbox server. Kept intentionally minimal: the main app
+ * never imports Deno; it only speaks this JSON over HTTP.
+ */
+/**
+ * Per-request guest capabilities. `net` and `import` are INDEPENDENT axes
+ * (Deno enforces them separately — `--allow-net` gates `fetch`, `--allow-import`
+ * gates module imports). The richer app-binding capabilities (`data`, `services`,
+ * etc.) live on the core `ExecutorCapabilities` type and are NOT enforced by the
+ * sandbox server — they are the later bindings-broker's job.
+ */
+interface SandboxCapabilities {
+  /** Runtime `fetch()` allowlist as `host[:port]`. Empty = no network. */
+  net: string[];
+  /** Module import allowlist as `host[:port]` (e.g. `esm.sh:443`). Empty = no remote imports. */
+  import: string[];
+  /** Hard wall-clock timeout; the subprocess is force-killed on exceed. */
+  timeoutMs: number;
+  /** Hard per-guest memory bound (`--v8-flags=--max-old-space-size`). */
+  memoryMb: number;
+}
+/**
+ * App-bindings wiring for the UNTRUSTED path. When present, the supervisor
+ * exposes a capability-scoped `globalThis.questpie` proxy to the guest whose
+ * methods RPC (over STDIO, never the network) to the host broker at {@link url},
+ * authenticated by the per-run scoped {@link token}.
+ *
+ * The token is OPAQUE and is held by the SUPERVISOR only — it is never written
+ * into the guest subprocess, so guest code cannot read or forge it to widen
+ * scope. The guest only ever sees the typed proxy.
+ *
+ * Critically, the broker is reached SERVER-TO-SERVER (supervisor → app), NOT by
+ * the guest's `fetch`: the guest's egress allowlist rejects loopback/private IPs
+ * (the SSRF defense), so a localhost broker is unreachable from guest code by
+ * design — we do not poke a hole in that.
+ */
+interface SandboxBindings {
+  /** Absolute URL of the host broker endpoint (e.g. `https://app/sandbox/rpc`). */
+  url: string;
+  /** Per-run opaque scoped token. Supervisor-only; never exposed to the guest. */
+  token: string;
+}
+/** POST /run request body. */
+interface SandboxRunRequest {
+  /** Explicit transport admission. The supervisor rejects omitted/unknown modes. */
+  mode: "workload" | "host";
+  /** Guest TypeScript source. Must `export default` a `function(input)`. */
+  source: string;
+  /** Payload passed to the guest entry function. */
+  input: unknown;
+  capabilities: SandboxCapabilities;
+  /**
+   * Secrets injected into the guest (NOT in source). Surfaced to the guest as
+   * `globalThis.__secrets`. The sandbox never persists these.
+   */
+  secrets?: Record<string, string>;
+  /**
+   * App-bindings broker wiring. When omitted, the guest gets no `questpie`
+   * proxy (the legacy compute-only path). When present, the supervisor brokers
+   * the guest's binding RPCs to the host. See {@link SandboxBindings}.
+   */
+  bindings?: SandboxBindings;
+}
+/** POST /run response body — also the `ExecutorAdapter.run` result shape. */
+type SandboxRunResult = {
+  ok: true;
+  output?: unknown;
+  logs: string[];
+  error?: never;
+  timedOut?: never;
+  /** Wall-clock duration in ms (server-measured). */
+  ms?: number;
+} | {
+  ok: false;
+  error: string;
+  logs: string[];
+  output?: never;
+  timedOut?: never;
+  /** Wall-clock duration in ms (server-measured). */
+  ms?: number;
+} | {
+  ok: false;
+  error: string;
+  logs: string[];
+  output?: never;
+  /** True when the run was killed by the wall-clock timeout. */
+  timedOut: true;
+  /** Wall-clock duration in ms (server-measured). */
+  ms?: number;
+};
+/** Line prefix marking a framed protocol message on guest stdout. */
+declare const FRAME_MARKER = "__QP_SANDBOX_MSG__";
+/**
+ * Header carrying the per-run scoped token on the supervisor → broker request.
+ * Mirrors `questpie`'s `BINDINGS_TOKEN_HEADER`. Supervisor-only; never set by or
+ * exposed to guest code.
+ */
+declare const BINDINGS_TOKEN_HEADER$1 = "x-questpie-sandbox-token";
+/** Host-issued admission binding an authorized workload to one exact request. */
+declare const WORKLOAD_ADMISSION_HEADER = "x-questpie-workload-admission";
+/** Trusted service identity for the structurally separate direct-host path. */
+declare const HOST_ADMISSION_HEADER = "x-questpie-sandbox-host-admission";
+/** Structured error returned by the broker (mirrors `questpie` `BindingError`). */
+interface SandboxBindingError {
+  code: string;
+  message: string;
+  correlationId?: string;
+}
+/** Guest → supervisor: a binding RPC awaiting a brokered result. */
+interface GuestRpcMessage {
+  type: "rpc";
+  id: number;
+  method: string;
+  args: unknown;
+}
+/** Guest → supervisor: the run's final result. */
+interface GuestResultMessage {
+  type: "result";
+  ok: boolean;
+  output?: unknown;
+  error?: string;
+  logs: string[];
+}
+/** Any message the guest emits on stdout (framed). */
+type GuestMessage = GuestRpcMessage | GuestResultMessage;
+/** Supervisor → guest: the brokered outcome of a prior {@link GuestRpcMessage}. */
+interface HostRpcResultMessage {
+  type: "rpc-result";
+  id: number;
+  ok: boolean;
+  value?: unknown;
+  error?: SandboxBindingError;
+}
+//#endregion
+//#region src/workload.d.ts
+declare const SANDBOX_WORKLOAD_DENIAL_MESSAGE = "The workload is not authorized for this sandbox operation.";
+declare class SandboxWorkloadDeniedError extends Error {
+  readonly code: "sandbox_authority_denied";
+  constructor();
+}
+interface SandboxWorkloadPolicy {
+  readonly source: string;
+  readonly input?: unknown;
+  readonly capabilities: SandboxCapabilities;
+  readonly secrets?: Readonly<Record<string, string>>;
+  readonly bindings?: SandboxBindings;
+  /** Host-only custom-tool authority. Never serialized to the supervisor. */
+  readonly sandboxTools?: SandboxCustomToolsRunOptions;
+  /** Optional consumer deadline; transport admission is additionally capped at 5s. */
+  readonly validUntil?: string;
+}
+type SandboxWorkloadAuthorizationPhase = "prepare" | "dispatch";
+interface SandboxWorkloadAuthorizationContext {
+  readonly phase: SandboxWorkloadAuthorizationPhase;
+  readonly signal: AbortSignal;
+}
+type SandboxWorkloadAuthorizer = (envelope: unknown, context: SandboxWorkloadAuthorizationContext) => SandboxWorkloadPolicy | null | Promise<SandboxWorkloadPolicy | null>;
+interface SandboxWorkloadAuditEvent {
+  readonly boundary: "sandbox.workload";
+  readonly phase: SandboxWorkloadAuthorizationPhase | "transport";
+  readonly decision: "allowed" | "denied";
+  readonly reason: "authorization_failed" | "authorization_timed_out" | "cancelled" | "egress_denied" | "policy_changed" | "policy_invalid" | "authorization_succeeded" | "transport_completed" | "transport_denied" | "transport_cancelled" | "transport_timed_out" | "transport_invalid_response" | "transport_failed";
+}
+interface SandboxWorkloadAuditContext {
+  readonly signal: AbortSignal;
+}
+interface SandboxWorkloadRunOptions {
+  /** Consumer-owned opaque value. QUESTPIE never parses or persists it. */
+  readonly envelope: unknown;
+  readonly signal?: AbortSignal;
+}
+//#endregion
+//#region src/adapter-http.d.ts
+interface WorkloadHttpSandboxOptions {
+  readonly authorize: SandboxWorkloadAuthorizer;
+  readonly admission: SandboxWorkloadAdmissionKey;
+  /** Hard bound around each consumer authorization read. Default 2s, max 5s. */
+  readonly authorizationTimeoutMs?: number;
+  /** Redacted audit seam. Allowed decisions fail closed when it cannot settle. */
+  readonly audit?: (event: SandboxWorkloadAuditEvent, context: SandboxWorkloadAuditContext) => void | Promise<void>;
+  /** Hard bound around the audit callback. Default 250ms, max 1s. */
+  readonly auditTimeoutMs?: number;
+}
+interface HttpSandboxAdapterOptions {
+  /**
+   * Base URL of the standalone Deno sandbox service (`sandbox-server.ts`).
+   * Defaults to `process.env.SANDBOX_URL`. Throws on `run` if neither is set.
+   */
+  url?: string;
+  /**
+   * Per-request HTTP fetch timeout (ms). A safety margin above the guest
+   * wall-timeout so the server's own kill fires first; if the server is
+   * unreachable this bounds the client wait. Default: guest timeout + 10s.
+   */
+  fetchTimeoutMs?: number;
+  /** Optional custom `fetch` (e.g. for auth headers / mTLS). */
+  fetch?: typeof fetch;
+  /**
+   * Validate net/import hosts against the private-IP policy BEFORE sending to
+   * the sandbox (defense-in-depth; the server validates too). Default: true.
+   */
+  validateEgress?: boolean;
+  /** Consumer-owned fail-closed admission for opaque remote workloads. */
+  workload?: WorkloadHttpSandboxOptions;
+  /** Trusted host credential for the direct framework `run()` path. */
+  hostAdmissionSecret?: string;
+}
+/**
+ * Production sandboxed `ExecutorAdapter` — POSTs the run to the standalone Deno
+ * sandbox service over HTTP. The main app (Bun/Node) holds NO Deno; it only
+ * speaks this JSON contract.
+ *
+ * Use as the `sandboxed` adapter in the executor config:
+ *   executor: { sandboxed: httpSandboxAdapter({ url: process.env.SANDBOX_URL }) }
+ */
+declare class HttpSandboxAdapter implements ExecutorAdapter {
+  private readonly options;
+  private readonly fetchImpl;
+  private readonly validateEgress;
+  constructor(options?: HttpSandboxAdapterOptions);
+  private resolveUrl;
+  private postRun;
+  run(options: ExecutorRunOptions): Promise<ExecutorRunResult>;
+  runWorkload(options: SandboxWorkloadRunOptions): Promise<ExecutorRunResult>;
+}
+/** Factory for the production sandboxed adapter. */
+declare function httpSandboxAdapter(options?: HttpSandboxAdapterOptions): HttpSandboxAdapter;
+//#endregion
+export { SandboxWorkloadAdmissionVerification as A, SandboxCapabilities as C, SandboxWorkloadAdmissionClaims as D, WORKLOAD_ADMISSION_HEADER as E, SandboxWorkloadAdmissionDenialReason as O, SandboxBindings as S, SandboxRunResult as T, GuestResultMessage as _, SANDBOX_WORKLOAD_DENIAL_MESSAGE as a, HostRpcResultMessage as b, SandboxWorkloadAuthorizationContext as c, SandboxWorkloadDeniedError as d, SandboxWorkloadPolicy as f, GuestMessage as g, FRAME_MARKER as h, httpSandboxAdapter as i, SandboxWorkloadAdmissionKey as k, SandboxWorkloadAuthorizationPhase as l, BINDINGS_TOKEN_HEADER$1 as m, HttpSandboxAdapterOptions as n, SandboxWorkloadAuditContext as o, SandboxWorkloadRunOptions as p, WorkloadHttpSandboxOptions as r, SandboxWorkloadAuditEvent as s, HttpSandboxAdapter as t, SandboxWorkloadAuthorizer as u, GuestRpcMessage as v, SandboxRunRequest as w, SandboxBindingError as x, HOST_ADMISSION_HEADER as y };

package/dist/adapter.d.mts

@@ -1,2 +1,3 @@
-import { n as HttpSandboxAdapterOptions, r as httpSandboxAdapter, t as HttpSandboxAdapter } from "./adapter-http-7ypWHBck.mjs";
-export { HttpSandboxAdapter, type HttpSandboxAdapterOptions, httpSandboxAdapter };
+import { f as SandboxWorkloadPolicy, i as httpSandboxAdapter, n as HttpSandboxAdapterOptions, o as SandboxWorkloadAuditContext, p as SandboxWorkloadRunOptions, r as WorkloadHttpSandboxOptions, s as SandboxWorkloadAuditEvent, t as HttpSandboxAdapter, u as SandboxWorkloadAuthorizer } from "./adapter-http-DDeL-Ym3.mjs";
+import { a as SandboxCustomToolsRunOptions, i as SandboxCustomToolsLimits, n as SandboxCustomToolEvidenceEvent, o as sandboxCustomTools, r as SandboxCustomToolsConfig, t as SandboxCustomToolEvidenceContext } from "./custom-tools-CgfgyVNv.mjs";
+export { HttpSandboxAdapter, type HttpSandboxAdapterOptions, type SandboxCustomToolEvidenceContext, type SandboxCustomToolEvidenceEvent, type SandboxCustomToolsConfig, type SandboxCustomToolsLimits, type SandboxCustomToolsRunOptions, type SandboxWorkloadAuditContext, type SandboxWorkloadAuditEvent, type SandboxWorkloadAuthorizer, type SandboxWorkloadPolicy, type SandboxWorkloadRunOptions, type WorkloadHttpSandboxOptions, httpSandboxAdapter, sandboxCustomTools };

package/dist/adapter.mjs

@@ -1,3 +1,4 @@
-import { n as httpSandboxAdapter, t as HttpSandboxAdapter } from "./adapter-http-w7SjAfcC.mjs";
+import { r as sandboxCustomTools } from "./custom-tools-DxI7JvUn.mjs";
+import { n as httpSandboxAdapter, t as HttpSandboxAdapter } from "./adapter-http-Coy4jqsj.mjs";
 
-export { HttpSandboxAdapter, httpSandboxAdapter };
+export { HttpSandboxAdapter, httpSandboxAdapter, sandboxCustomTools };

package/dist/custom-tools-CgfgyVNv.d.mts

@@ -0,0 +1,55 @@
+import { McpWorkloadAuditEvent, McpWorkloadAuthorizer, McpWorkloadContextBinder, McpWorkloadHandoff } from "@questpie/mcp";
+import "questpie";
+import "questpie/executor";
+
+//#region src/custom-tools.d.ts
+interface SandboxCustomToolsLimits {
+  readonly maxTools?: number;
+  readonly maxListBytes?: number;
+  readonly maxArgumentBytes?: number;
+  readonly maxResultBytes?: number;
+  /** Total `tools.list` plus `tools.call` operations allowed in one run. */
+  readonly maxCalls?: number;
+  readonly timeoutMs?: number;
+  readonly concurrency?: number;
+}
+interface SandboxCustomToolEvidenceEvent {
+  readonly boundary: "sandbox.tool";
+  readonly phase: "discovery" | "call";
+  readonly toolName?: string;
+  readonly result: "succeeded" | "denied" | "failed";
+  readonly reason: "completed" | "authorization_or_tool_denied" | "invalid_request" | "limit_exceeded" | "timed_out" | "execution_failed";
+  readonly durationMs: number;
+}
+interface SandboxCustomToolEvidenceContext {
+  readonly signal: AbortSignal;
+}
+interface SandboxCustomToolsConfig {
+  readonly authorizer: McpWorkloadAuthorizer;
+  readonly contextBinder: McpWorkloadContextBinder;
+  /** Existing MCP authorization audit seam; receives no input or result bodies. */
+  readonly authorizationAudit?: (event: McpWorkloadAuditEvent) => void | Promise<void>;
+  readonly handoff?: McpWorkloadHandoff;
+  /** Product-neutral terminal evidence. Arguments/results/envelopes are omitted. */
+  readonly evidence?: (event: SandboxCustomToolEvidenceEvent, context: SandboxCustomToolEvidenceContext) => void | Promise<void>;
+  readonly evidenceTimeoutMs?: number;
+  readonly limits?: SandboxCustomToolsLimits;
+}
+interface SandboxCustomToolsRunOptions {
+  /** Consumer-owned opaque authorization input. Never sent to the guest. */
+  readonly envelope: unknown;
+}
+declare module "questpie" {
+  interface RuntimeConfigExtensions {
+    sandboxCustomTools?: SandboxCustomToolsConfig;
+  }
+}
+declare module "questpie/executor" {
+  interface ExecutorRunOptions {
+    /** Host-only custom-tool authority for this sandbox run. */
+    sandboxTools?: SandboxCustomToolsRunOptions;
+  }
+}
+declare function sandboxCustomTools(config: SandboxCustomToolsConfig): SandboxCustomToolsConfig;
+//#endregion
+export { SandboxCustomToolsRunOptions as a, SandboxCustomToolsLimits as i, SandboxCustomToolEvidenceEvent as n, sandboxCustomTools as o, SandboxCustomToolsConfig as r, SandboxCustomToolEvidenceContext as t };