@claxedo/sandbox-manager 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Claxedo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @claxedo/sandbox-manager
+
+Open-sourceable sandbox placement and lease management for running `@claxedo/workspace-runtime` inside provider sandboxes.
+
+The package owns the generic pieces:
+
+- `SandboxManager`
+- `SandboxLease`
+- `SandboxTarget`
+- `SandboxLeaseStore`
+- `SandboxDriver`
+- provider drivers for Cloudflare, Daytona, Docker, fetch bridge, Modal, and Vercel
+
+It deliberately does not own Claxedo product auth, billing, Convex schema, SQLite app storage, routes, or relay tokens. Applications provide those through adapters and call `createSandboxManager`.
+
+## Credentials & secrets
+
+There are two distinct channels for getting values into a sandbox, chosen by
+whether the code inside the sandbox is trusted with the raw value.
+
+### `env` — readable, for trusted credentials
+
+`SandboxManagerInput.env` (and the driver-level `env`) sets ordinary
+environment variables, readable inside the sandbox via `process.env`. Reserve
+this for credentials the agent is *meant* to hold — e.g. the user's own model
+subscription/API key, which the agent needs to call the model directly.
+
+### `secrets` — brokered, never readable inside the sandbox
+
+`SandboxManagerInput.secrets: SandboxBrokeredSecret[]` is for credentials the
+sandbox must be able to *use* on outbound requests but must never be able to
+*read* or exfiltrate (connection tokens, deploy tokens). The raw value never
+enters the sandbox: the provider injects it on egress to an allowlist of
+`hosts` only.
+
+```ts
+await manager.ensure(workspaceId, {
+  homeRegion: "us-east",
+  secrets: [{
+    name: "NOTION_TOKEN",
+    value: notionToken,          // never enters the sandbox in plaintext
+    hosts: ["api.notion.com"],   // substituted/injected only for these hosts
+    header: "Authorization",     // required for Vercel; optional for Daytona
+  }],
+})
+```
+
+Per-provider mechanism (from each provider's official docs):
+
+| Driver | `secretBrokering` | Mechanism |
+| --- | --- | --- |
+| Daytona | `native` | `daytona.secret.create({name, value, hosts})`; the sandbox env holds an opaque `dtn_secret_…` placeholder and an egress proxy substitutes the real value only for allowlisted hosts ([docs](https://www.daytona.io/docs/en/secrets/)). |
+| Vercel | `native` | Firewall header-transform (`updateNetworkPolicy`): the value is spliced onto egress to the allowlisted hosts as `header`; the sandbox makes an unauthenticated request, egress restricted to brokered hosts ([docs](https://vercel.com/docs/sandbox/concepts/firewall)). |
+| Cloudflare | `proxy` | Implemented via the official [Worker-proxy pattern](https://developers.cloudflare.com/sandbox/guides/proxy-requests/): the driver sends the value to the sandbox Worker (API-token-gated, never into the container); the Worker stores it in KV, mints a short-lived per-sandbox JWT, and sets `CLAXEDO_EGRESS_PROXY_URL`/`CLAXEDO_EGRESS_TOKEN`/`CLAXEDO_EGRESS_HOSTS` in the container. The sandbox routes brokered-host egress through the Worker, which validates the JWT and injects the credential as `header` — the raw value never enters the sandbox. The reusable core is `@claxedo/sandbox-manager/drivers/cloudflare-egress` (mint/verify + `handleEgressRequest`). |
+| Modal | `none` | Modal [Secrets](https://modal.com/docs/guide/secrets) are an encrypted by-reference store, but exposed as **readable env vars** inside the sandbox — they cannot satisfy the never-readable contract. |
+| Docker, fetch | `none` | Plaintext env only. |
+
+**Fail-closed contract.** A brokered secret is never silently downgraded to
+readable env. `native` (transparent egress) and `proxy` (Cloudflare Worker
+egress proxy) both keep the value out of the sandbox and provision normally;
+only a `none` driver makes the manager refuse to provision (`status:
+"unavailable", error: "secret_brokering_unsupported"`) rather than expose or
+drop the credential. Brokered secret values are also never written to labels,
+never logged, and never captured in a driver snapshot.
+
+> Consumption note: `native` brokering is transparent (existing code reaches
+> the real host and the platform injects). Cloudflare `proxy` is NOT
+> transparent — the sandbox must route brokered-host requests through
+> `CLAXEDO_EGRESS_PROXY_URL` (with the `CLAXEDO_EGRESS_TOKEN` bearer and the
+> `x-claxedo-egress-target` header). Modal stays `none`; its secret store
+> improves storage hygiene for *readable* credentials but does not hide them
+> from the sandbox.
+
+> SDK conformance: the Daytona secret API and Vercel network-policy transform
+> shapes follow the providers' official docs and are validated structurally
+> against the pinned SDK types; like all provider calls in this package they
+> are exercised against mocks in unit tests, with live-SDK integration
+> verified at deploy time.

package/dist/command.d.ts

@@ -0,0 +1,3 @@
+export declare function shell(input: string): string;
+export declare function file(...parts: string[]): string;
+export declare function env(input: Record<string, string>): string;

package/dist/command.mjs

@@ -0,0 +1,18 @@
+import { createRequire as __createRequire } from 'module';var require = __createRequire(import.meta.url);
+
+// src/command.ts
+import path from "path";
+function shell(input) {
+  return `'${input.replace(/'/g, `'"'"'`)}'`;
+}
+function file(...parts) {
+  return shell(path.posix.join(...parts));
+}
+function env(input) {
+  return Object.entries(input).map(([k, v]) => `export ${k}=${shell(v)}`).join(" && ");
+}
+export {
+  env,
+  file,
+  shell
+};

package/dist/constants.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_WORKSPACE_RUNTIME_PORT = 2593;

package/dist/constants.mjs

@@ -0,0 +1,7 @@
+import { createRequire as __createRequire } from 'module';var require = __createRequire(import.meta.url);
+
+// src/constants.ts
+var DEFAULT_WORKSPACE_RUNTIME_PORT = 2593;
+export {
+  DEFAULT_WORKSPACE_RUNTIME_PORT
+};

package/dist/daytona-allow-list.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Format CIDRs for Daytona SDK `networkAllowList` parameter.
+ * Daytona currently accepts at most 10 entries.
+ */
+export declare function formatDaytonaAllowList(cidrs: string[]): string;

package/dist/daytona-allow-list.mjs

@@ -0,0 +1,9 @@
+import { createRequire as __createRequire } from 'module';var require = __createRequire(import.meta.url);
+
+// src/daytona-allow-list.ts
+function formatDaytonaAllowList(cidrs) {
+  return cidrs.slice(0, 10).join(",");
+}
+export {
+  formatDaytonaAllowList
+};

package/dist/defaults.d.ts

@@ -0,0 +1,3 @@
+export declare const WORKSPACE_RUNTIME_PORT = 2593;
+export declare const WORKSPACE_DIR = "/workspace";
+export declare const RUNTIME_DIR = "/opt/workspace-runtime";

package/dist/defaults.mjs

@@ -0,0 +1,14 @@
+import { createRequire as __createRequire } from 'module';var require = __createRequire(import.meta.url);
+
+// src/constants.ts
+var DEFAULT_WORKSPACE_RUNTIME_PORT = 2593;
+
+// src/defaults.ts
+var WORKSPACE_RUNTIME_PORT = DEFAULT_WORKSPACE_RUNTIME_PORT;
+var WORKSPACE_DIR = "/workspace";
+var RUNTIME_DIR = "/opt/workspace-runtime";
+export {
+  RUNTIME_DIR,
+  WORKSPACE_DIR,
+  WORKSPACE_RUNTIME_PORT
+};

package/dist/driver-catalog.d.ts

@@ -0,0 +1,62 @@
+import type { SandboxDriverMetadata } from "./index";
+export declare const sandboxDriverIds: readonly ["daytona", "modal", "vercel", "cloudflare", "docker"];
+export type SandboxDriverID = (typeof sandboxDriverIds)[number];
+export type SandboxDriverAuth = {
+    daytona?: {
+        api_key?: string;
+    };
+    modal?: {
+        token_id?: string;
+        token_secret?: string;
+    };
+    vercel?: {
+        access_token?: string;
+        team_id?: string;
+        project_id?: string;
+    };
+    cloudflare?: {
+        api_token?: string;
+        worker_url?: string;
+    };
+    docker?: {
+        image?: string;
+    };
+};
+export type SandboxDriverConfig = {
+    default_driver?: SandboxDriverID;
+    auth?: SandboxDriverAuth;
+};
+export type SandboxDriverCatalogEntry = {
+    id: SandboxDriverID;
+    label: string;
+    metadata: SandboxDriverMetadata;
+    credentialFields: Array<{
+        key: string;
+        label: string;
+        secret?: boolean;
+    }>;
+};
+export declare const sandboxDriverCatalog: Record<SandboxDriverID, SandboxDriverCatalogEntry>;
+export declare function isSandboxDriverID(input: string | undefined): input is SandboxDriverID;
+export declare function sandboxDriverId(input: string | undefined, cfg?: SandboxDriverConfig, env?: SandboxDriverEnv): "daytona" | "modal" | "vercel" | "cloudflare" | "docker" | undefined;
+export declare function defaultSandboxDriverID(cfg?: SandboxDriverConfig, env?: SandboxDriverEnv): SandboxDriverID;
+export declare function sandboxDriverAuth<T extends SandboxDriverID>(cfg: SandboxDriverConfig | undefined, id: T, env?: SandboxDriverEnv): SandboxDriverAuth[T] | undefined;
+export declare function hasSandboxDriverAuth(cfg: SandboxDriverConfig | undefined, id: SandboxDriverID, env?: SandboxDriverEnv): boolean;
+export declare function dockerSandboxDriverEnabled(env?: SandboxDriverEnv): boolean;
+export declare function listSandboxDrivers(cfg?: SandboxDriverConfig, env?: SandboxDriverEnv, managedDriverIds?: ReadonlySet<string>): {
+    default_driver: "daytona" | "modal" | "vercel" | "cloudflare" | "docker";
+    drivers: {
+        id: "daytona" | "modal" | "vercel" | "cloudflare" | "docker";
+        label: string;
+        fields: {
+            key: string;
+            label: string;
+            secret?: boolean;
+        }[];
+        configured: boolean;
+        source: "none" | "config" | "managed";
+        default: boolean;
+    }[];
+};
+type SandboxDriverEnv = Record<string, string | undefined>;
+export {};

package/dist/driver-catalog.mjs

@@ -0,0 +1,206 @@
+import { createRequire as __createRequire } from 'module';var require = __createRequire(import.meta.url);
+
+// src/runtime-version.ts
+import { createRequire } from "module";
+var require2 = createRequire(import.meta.url);
+var versionCache;
+function workspaceRuntimeVersion() {
+  if (versionCache) return versionCache;
+  const envVersion = process.env.WORKSPACE_RUNTIME_VERSION;
+  if (envVersion) {
+    versionCache = envVersion;
+    return versionCache;
+  }
+  try {
+    versionCache = require2("@claxedo/workspace-runtime/package.json").version;
+    return versionCache;
+  } catch {
+  }
+  versionCache = "0.0.0";
+  return versionCache;
+}
+
+// src/image-name.ts
+var SNAPSHOT_SCHEMA_VERSION = 8;
+var DEFAULT_SANDBOX_IMAGE_REPOSITORY = "ghcr.io/kyashrathore/claxedo-sandbox";
+function snapshotVersion(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+function sandboxImageRepository(env = process.env) {
+  const repository = env.CLAXEDO_SANDBOX_IMAGE_REPOSITORY?.trim();
+  return repository ? repository : DEFAULT_SANDBOX_IMAGE_REPOSITORY;
+}
+function buildIdSuffix(buildId, env) {
+  const id = (buildId ?? env.CLAXEDO_SANDBOX_BUILD_ID)?.trim();
+  return id ? `-${snapshotVersion(id)}` : "";
+}
+function defaultSandboxImage(version = workspaceRuntimeVersion(), buildId, env = process.env) {
+  return `${sandboxImageRepository(env)}:workspace-runtime-${snapshotVersion(version)}${buildIdSuffix(buildId, env)}-v${SNAPSHOT_SCHEMA_VERSION}`;
+}
+
+// src/driver-catalog.ts
+var sandboxDriverIds = ["daytona", "modal", "vercel", "cloudflare", "docker"];
+var sandboxDriverCatalog = {
+  daytona: {
+    id: "daytona",
+    label: "Daytona",
+    credentialFields: [{ key: "api_key", label: "API Key", secret: true }],
+    metadata: {
+      driverRunsIn: ["worker", "node"],
+      hostStopBehavior: "suspends-host",
+      hostResumeBehavior: "same-host",
+      targetAccess: "relay",
+      secretBrokering: "native"
+    }
+  },
+  modal: {
+    id: "modal",
+    label: "Modal",
+    credentialFields: [
+      { key: "token_id", label: "Token ID", secret: true },
+      { key: "token_secret", label: "Token Secret", secret: true }
+    ],
+    metadata: {
+      driverRunsIn: ["node"],
+      hostStopBehavior: "terminates-host",
+      hostResumeBehavior: "replacement-host",
+      targetAccess: "relay",
+      secretBrokering: "none"
+    }
+  },
+  vercel: {
+    id: "vercel",
+    label: "Vercel",
+    credentialFields: [
+      { key: "access_token", label: "Access Token", secret: true },
+      { key: "team_id", label: "Team ID" },
+      { key: "project_id", label: "Project ID" }
+    ],
+    metadata: {
+      driverRunsIn: ["node"],
+      hostStopBehavior: "terminates-host",
+      hostResumeBehavior: "replacement-host",
+      targetAccess: "relay",
+      secretBrokering: "native"
+    }
+  },
+  cloudflare: {
+    id: "cloudflare",
+    label: "Cloudflare",
+    credentialFields: [
+      { key: "api_token", label: "API Token", secret: true },
+      { key: "worker_url", label: "Worker URL" }
+    ],
+    metadata: {
+      driverRunsIn: ["worker"],
+      hostStopBehavior: "not-supported",
+      hostResumeBehavior: "same-host",
+      targetAccess: "relay",
+      secretBrokering: "proxy"
+    }
+  },
+  docker: {
+    id: "docker",
+    label: "Docker",
+    credentialFields: [{ key: "image", label: "Image" }],
+    metadata: {
+      driverRunsIn: ["local"],
+      hostStopBehavior: "terminates-host",
+      hostResumeBehavior: "same-host",
+      targetAccess: "loopback",
+      secretBrokering: "none"
+    }
+  }
+};
+function isSandboxDriverID(input) {
+  return !!input && sandboxDriverIds.includes(input);
+}
+function sandboxDriverId(input, cfg, env = process.env) {
+  if (!isSandboxDriverID(input)) return;
+  if (input === "docker" && !sandboxDriverAuth(cfg, input, env)) return;
+  return input;
+}
+function defaultSandboxDriverID(cfg, env = process.env) {
+  return sandboxDriverId(cfg?.default_driver, cfg, env) ?? (dockerSandboxDefault(env) && sandboxDriverAuth(cfg, "docker", env) ? "docker" : "daytona");
+}
+function sandboxDriverAuth(cfg, id, env = process.env) {
+  if (id === "daytona") return authDaytona(cfg);
+  if (id === "modal") return authModal(cfg, env);
+  if (id === "vercel") return authVercel(cfg, env);
+  if (id === "cloudflare") return authCloudflare(cfg, env);
+  return authDocker(cfg, env);
+}
+function hasSandboxDriverAuth(cfg, id, env = process.env) {
+  return !!sandboxDriverAuth(cfg, id, env);
+}
+function dockerSandboxDriverEnabled(env = process.env) {
+  return dockerSandboxEnabled(env);
+}
+function listSandboxDrivers(cfg, env = process.env, managedDriverIds = /* @__PURE__ */ new Set()) {
+  const def = defaultSandboxDriverID(cfg, env);
+  return {
+    default_driver: def,
+    drivers: sandboxDriverIds.filter((id) => id !== "docker" || !!sandboxDriverAuth(cfg, "docker", env)).map((id) => {
+      const configuredFromConfigOrEnv = !!sandboxDriverAuth(cfg, id, env);
+      const configured = id === "docker" ? configuredFromConfigOrEnv : configuredFromConfigOrEnv || managedDriverIds.has(id);
+      return {
+        id,
+        label: sandboxDriverCatalog[id].label,
+        fields: sandboxDriverCatalog[id].credentialFields,
+        configured,
+        source: configuredFromConfigOrEnv ? "config" : configured ? "managed" : "none",
+        default: id === def
+      };
+    })
+  };
+}
+function clean(input) {
+  const txt = input?.trim();
+  return txt ? txt : void 0;
+}
+function enabled(input) {
+  return ["1", "true", "yes", "on"].includes(input?.trim().toLowerCase() ?? "");
+}
+function dockerSandboxEnabled(env) {
+  return enabled(env.CLAXEDO_ENABLE_DOCKER_SANDBOX) || enabled(env.CLAXEDO_DEV_DOCKER_SANDBOX);
+}
+function dockerSandboxDefault(env) {
+  return enabled(env.CLAXEDO_DOCKER_SANDBOX_DEFAULT);
+}
+function authDaytona(cfg) {
+  const api_key = clean(cfg?.auth?.daytona?.api_key);
+  return api_key ? { api_key } : void 0;
+}
+function authModal(cfg, env) {
+  const token_id = clean(cfg?.auth?.modal?.token_id) ?? clean(env.MODAL_TOKEN_ID);
+  const token_secret = clean(cfg?.auth?.modal?.token_secret) ?? clean(env.MODAL_TOKEN_SECRET);
+  return token_id && token_secret ? { token_id, token_secret } : void 0;
+}
+function authVercel(cfg, env) {
+  const access_token = clean(cfg?.auth?.vercel?.access_token) ?? clean(env.VERCEL_TOKEN);
+  const team_id = clean(cfg?.auth?.vercel?.team_id) ?? clean(env.VERCEL_TEAM_ID);
+  const project_id = clean(cfg?.auth?.vercel?.project_id) ?? clean(env.VERCEL_PROJECT_ID);
+  return access_token && team_id && project_id ? { access_token, team_id, project_id } : void 0;
+}
+function authCloudflare(cfg, env) {
+  const api_token = clean(cfg?.auth?.cloudflare?.api_token) ?? clean(env.CLOUDFLARE_API_TOKEN);
+  const worker_url = clean(cfg?.auth?.cloudflare?.worker_url) ?? clean(env.CLOUDFLARE_SANDBOX_WORKER_URL);
+  return api_token && worker_url ? { api_token, worker_url } : void 0;
+}
+function authDocker(cfg, env) {
+  if (!dockerSandboxEnabled(env)) return;
+  return {
+    image: clean(cfg?.auth?.docker?.image) ?? clean(env.CLAXEDO_DOCKER_SANDBOX_IMAGE) ?? clean(env.CLAXEDO_SANDBOX_IMAGE) ?? defaultSandboxImage(workspaceRuntimeVersion(), void 0, env)
+  };
+}
+export {
+  defaultSandboxDriverID,
+  dockerSandboxDriverEnabled,
+  hasSandboxDriverAuth,
+  isSandboxDriverID,
+  listSandboxDrivers,
+  sandboxDriverAuth,
+  sandboxDriverCatalog,
+  sandboxDriverId,
+  sandboxDriverIds
+};

package/dist/drivers/cloudflare-egress.d.ts

@@ -0,0 +1,40 @@
+export type EgressTokenClaims = {
+    /** Sandbox the token is bound to. */
+    sub: string;
+    /** Hosts the sandbox may reach through the broker. */
+    hosts: string[];
+    /** Expiry (epoch seconds). */
+    exp: number;
+};
+/** Mint a short-lived HS256 token binding a sandbox to its brokered hosts. Carries NO secret values. */
+export declare function mintEgressToken(input: {
+    sandboxId: string;
+    hosts: string[];
+    signingSecret: string;
+    ttlSeconds?: number;
+    now?: () => number;
+}): Promise<string>;
+/** Verify a token and return its claims, or null if invalid/expired. */
+export declare function verifyEgressToken(token: string, signingSecret: string, now?: () => number): Promise<EgressTokenClaims | null>;
+/** How the sandbox names its egress target: header carries the absolute upstream URL. */
+export declare const EGRESS_TARGET_HEADER = "x-claxedo-egress-target";
+/** Resolves the brokered credential for a (sandbox, host) pair — Worker-side only, never the sandbox. */
+export type EgressSecretResolver = (sandboxId: string, host: string) => Promise<{
+    header: string;
+    value: string;
+} | undefined> | {
+    header: string;
+    value: string;
+} | undefined;
+/**
+ * Handle one egress-proxy request from a sandbox: validate the JWT, confirm
+ * the target host is allowed, inject the brokered credential as its header,
+ * and forward. The credential is read from `resolveSecret` (Worker store) and
+ * never round-trips through the sandbox.
+ */
+export declare function handleEgressRequest(request: Request, options: {
+    signingSecret: string;
+    resolveSecret: EgressSecretResolver;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}): Promise<Response>;

package/dist/drivers/cloudflare-egress.mjs

@@ -0,0 +1,115 @@
+import { createRequire as __createRequire } from 'module';var require = __createRequire(import.meta.url);
+
+// src/drivers/cloudflare-egress.ts
+function b64urlEncode(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function b64urlDecode(input) {
+  const padded = input.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - input.length % 4) % 4);
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+function encodeJson(value) {
+  return b64urlEncode(new TextEncoder().encode(JSON.stringify(value)));
+}
+async function hmacKey(secret) {
+  return crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign", "verify"]
+  );
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+async function mintEgressToken(input) {
+  const now = input.now ?? Date.now;
+  const header = encodeJson({ alg: "HS256", typ: "JWT" });
+  const payload = encodeJson({
+    sub: input.sandboxId,
+    hosts: input.hosts,
+    exp: Math.floor(now() / 1e3) + (input.ttlSeconds ?? 15 * 60)
+  });
+  const key = await hmacKey(input.signingSecret);
+  const sig = new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${header}.${payload}`)));
+  return `${header}.${payload}.${b64urlEncode(sig)}`;
+}
+async function verifyEgressToken(token, signingSecret, now = Date.now) {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  const [header, payload, sig] = parts;
+  const key = await hmacKey(signingSecret);
+  const expected = b64urlEncode(
+    new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(`${header}.${payload}`)))
+  );
+  if (!timingSafeEqual(sig, expected)) return null;
+  let claims;
+  try {
+    claims = JSON.parse(new TextDecoder().decode(b64urlDecode(payload)));
+  } catch {
+    return null;
+  }
+  if (typeof claims.sub !== "string" || !Array.isArray(claims.hosts) || typeof claims.exp !== "number") return null;
+  if (claims.exp <= Math.floor(now() / 1e3)) return null;
+  return claims;
+}
+var EGRESS_TARGET_HEADER = "x-claxedo-egress-target";
+async function handleEgressRequest(request, options) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const auth = request.headers.get("authorization");
+  const token = auth?.toLowerCase().startsWith("bearer ") ? auth.slice(7) : void 0;
+  if (!token) return egressError(401, "missing egress token");
+  const claims = await verifyEgressToken(token, options.signingSecret, options.now);
+  if (!claims) return egressError(401, "invalid or expired egress token");
+  const targetRaw = request.headers.get(EGRESS_TARGET_HEADER);
+  if (!targetRaw) return egressError(400, "missing egress target");
+  let target;
+  try {
+    target = new URL(targetRaw);
+  } catch {
+    return egressError(400, "malformed egress target");
+  }
+  if (target.protocol !== "https:") return egressError(400, "egress target must be https");
+  if (!claims.hosts.includes(target.host)) return egressError(403, "host not permitted for this sandbox");
+  const secret = await options.resolveSecret(claims.sub, target.host);
+  if (!secret) return egressError(403, "no brokered credential for host");
+  const headers = new Headers(request.headers);
+  headers.delete("authorization");
+  headers.delete(EGRESS_TARGET_HEADER);
+  headers.set(secret.header, secret.value);
+  headers.set("host", target.host);
+  try {
+    const upstream = await fetchImpl(target.toString(), {
+      method: request.method,
+      headers,
+      body: request.method === "GET" || request.method === "HEAD" ? void 0 : request.body,
+      redirect: "manual"
+    });
+    const outHeaders = new Headers(upstream.headers);
+    outHeaders.delete(secret.header);
+    return new Response(upstream.body, { status: upstream.status, statusText: upstream.statusText, headers: outHeaders });
+  } catch {
+    return egressError(502, "upstream request failed");
+  }
+}
+function egressError(status, message) {
+  return new Response(JSON.stringify({ error: message }), {
+    status,
+    headers: { "content-type": "application/json" }
+  });
+}
+export {
+  EGRESS_TARGET_HEADER,
+  handleEgressRequest,
+  mintEgressToken,
+  verifyEgressToken
+};

package/dist/drivers/cloudflare.d.ts

@@ -0,0 +1,37 @@
+import type { SandboxDriver, SandboxDriverEnsureInput } from "..";
+export type CloudflareSandboxDriverOptions = {
+    /** Base URL of the deployed Cloudflare Sandbox Worker (e.g. https://sbx.example.com). */
+    workerUrl: string;
+    /** Bearer token the Worker validates (its `API_TOKEN` secret). */
+    apiToken: string;
+    /** Port the workspace-runtime listens on inside the sandbox (exposed publicly). */
+    runtimePort?: number;
+    /** Command that launches the workspace-runtime inside the image. */
+    runtimeCommand?: string;
+    /** Workspace directory inside the sandbox. */
+    workspaceDir?: string;
+    /**
+     * Static control-plane config injected into every sandbox so the runtime can
+     * verify relay-proxied requests. Never carries per-workspace secrets — those
+     * (if any) belong to the future egress broker.
+   *   relayJwksUrl     → WORKSPACE_RUNTIME_RELAY_JWKS_URL (relay public key for RAT verify)
+   *   relayVerifyPem   → WORKSPACE_RUNTIME_RELAY_HOST_VERIFY_PEM (fallback to JWKS)
+   *   managementJwksUrl → WORKSPACE_RUNTIME_MANAGEMENT_JWKS_URL (config apply)
+     */
+    controlEnv?: {
+        relayJwksUrl?: string;
+        relayVerifyPem?: string;
+        managementJwksUrl?: string;
+    };
+    /** Default runner injected as WORKSPACE_RUNTIME_RUNNER, e.g. "opencode" | "claude-acp" | "codex-acp". */
+    runner?: string;
+    /** Dynamic runtime env that needs the sandbox id or current lease. */
+    env?: (input: SandboxDriverEnsureInput, sandbox: {
+        id: string;
+    }) => Record<string, string> | Promise<Record<string, string>>;
+    /** Injected for tests. */
+    fetch?: typeof fetch;
+    /** ensure-runtime/HTTP timeout. */
+    timeoutMs?: number;
+};
+export declare function createCloudflareSandboxDriver(options: CloudflareSandboxDriverOptions): SandboxDriver;