@claxedo/sandbox-manager 0.7.0 → 0.9.0

package/dist/drivers/cloudflare.mjs

@@ -27,12 +27,50 @@ var SANDBOX_BASELINE_EGRESS_HOSTS = [
   ...SANDBOX_PACKAGE_REGISTRY_HOSTS
 ];
 
+// src/index.ts
+function brokeredSecretPlaceholder(name) {
+  return `claxedo-broker:${name}`;
+}
+function brokeredPlaceholderEnv(secrets) {
+  return Object.fromEntries((secrets ?? []).map((secret) => [secret.name, brokeredSecretPlaceholder(secret.name)]));
+}
+
+// ../sandbox-contract/dist/index.mjs
+var sandboxDriverCredentialFields = {
+  exe: [{ key: "api_token", label: "API Token", secret: true }],
+  daytona: [{ key: "api_key", label: "API Key", secret: true }],
+  modal: [
+    { key: "token_id", label: "Token ID", secret: true },
+    { key: "token_secret", label: "Token Secret", secret: true }
+  ],
+  vercel: [
+    { key: "access_token", label: "Access Token", secret: true },
+    { key: "team_id", label: "Team ID" },
+    { key: "project_id", label: "Project ID" }
+  ],
+  cloudflare: [
+    { key: "api_token", label: "API Token", secret: true },
+    { key: "worker_url", label: "Worker URL" }
+  ],
+  box: [{ key: "api_key", label: "API Key", secret: true }],
+  docker: [{ key: "image", label: "Image" }]
+};
+var sandboxDriverLabels = {
+  exe: "exe.dev",
+  daytona: "Daytona",
+  modal: "Modal",
+  vercel: "Vercel",
+  cloudflare: "Cloudflare",
+  box: "Box",
+  docker: "Docker"
+};
+
 // src/driver-catalog.ts
 var sandboxDriverCatalog = {
   exe: {
     id: "exe",
-    label: "exe.dev",
-    credentialFields: [{ key: "api_token", label: "API Token", secret: true }],
+    label: sandboxDriverLabels.exe,
+    credentialFields: sandboxDriverCredentialFields.exe,
     metadata: {
       driverRunsIn: ["worker", "node"],
       hostStopBehavior: "not-supported",
@@ -52,17 +90,15 @@ var sandboxDriverCatalog = {
   },
   daytona: {
     id: "daytona",
-    label: "Daytona",
-    credentialFields: [{ key: "api_key", label: "API Key", secret: true }],
+    label: sandboxDriverLabels.daytona,
+    credentialFields: sandboxDriverCredentialFields.daytona,
     metadata: {
       driverRunsIn: ["worker", "node"],
       hostStopBehavior: "suspends-host",
       hostResumeBehavior: "same-host",
       targetAccess: "relay",
       secretBrokering: "native",
-      // Daytona is the only driver that can filter egress by NAME as well as
-      // by address: `domainAllowList` (names) alongside `networkAllowList`
-      // (CIDRs), with `networkBlockAll` as the deny-all floor.
+      // The driver translates names to domainAllowList, or addresses to networkAllowList.
       egressControl: "hosts-and-cidrs",
       persistence: {
         resume: "same-sandbox",
@@ -76,20 +112,15 @@ var sandboxDriverCatalog = {
   },
   modal: {
     id: "modal",
-    label: "Modal",
-    credentialFields: [
-      { key: "token_id", label: "Token ID", secret: true },
-      { key: "token_secret", label: "Token Secret", secret: true }
-    ],
+    label: sandboxDriverLabels.modal,
+    credentialFields: sandboxDriverCredentialFields.modal,
     metadata: {
       driverRunsIn: ["node"],
       hostStopBehavior: "terminates-host",
       hostResumeBehavior: "replacement-host",
       targetAccess: "relay",
       secretBrokering: "none",
-      // Modal can cut the network entirely (`blockNetwork`) but cannot express
-      // an allowlist, and its driver throws on a host policy. A blackout is
-      // not containment for a workspace that has to clone and reach a model.
+      // The driver does not install Modal's domain allowlist or alpha sidecar.
       egressControl: "none",
       persistence: {
         resume: "replacement-restore",
@@ -103,20 +134,15 @@ var sandboxDriverCatalog = {
   },
   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" }
-    ],
+    label: sandboxDriverLabels.vercel,
+    credentialFields: sandboxDriverCredentialFields.vercel,
     metadata: {
       driverRunsIn: ["node"],
       hostStopBehavior: "terminates-host",
       hostResumeBehavior: "replacement-host",
       targetAccess: "relay",
       secretBrokering: "native",
-      // Vercel's sandbox firewall takes a hostname allow list (or "deny-all"),
-      // never CIDRs.
+      // The driver translates hosts only; the SDK's subnet rules are not wired to net.cidrs.
       egressControl: "hosts",
       persistence: {
         resume: "replacement-restore",
@@ -130,23 +156,15 @@ var sandboxDriverCatalog = {
   },
   cloudflare: {
     id: "cloudflare",
-    label: "Cloudflare",
-    credentialFields: [
-      { key: "api_token", label: "API Token", secret: true },
-      { key: "worker_url", label: "Worker URL" }
-    ],
+    label: sandboxDriverLabels.cloudflare,
+    credentialFields: sandboxDriverCredentialFields.cloudflare,
     metadata: {
       driverRunsIn: ["worker"],
       hostStopBehavior: "not-supported",
       hostResumeBehavior: "same-host",
       targetAccess: "relay",
-      secretBrokering: "proxy",
-      // The Cloudflare Sandbox Worker exposes no egress filter: its broker
-      // (drivers/cloudflare-egress.ts) is an OPT-IN proxy the sandbox chooses
-      // to route brokered-credential requests through, not a boundary. The
-      // driver therefore drops `net` entirely — which is exactly why this
-      // must be declared, so the manager refuses instead of provisioning a
-      // sandbox the caller believes is contained.
+      secretBrokering: "native",
+      // Credential handlers do not restrict unrelated destinations.
       egressControl: "none",
       persistence: {
         resume: "replacement-restore",
@@ -160,8 +178,8 @@ var sandboxDriverCatalog = {
   },
   box: {
     id: "box",
-    label: "Box",
-    credentialFields: [{ key: "api_key", label: "API Key", secret: true }],
+    label: sandboxDriverLabels.box,
+    credentialFields: sandboxDriverCredentialFields.box,
     metadata: {
       driverRunsIn: ["node"],
       hostStopBehavior: "suspends-host",
@@ -181,8 +199,8 @@ var sandboxDriverCatalog = {
   },
   docker: {
     id: "docker",
-    label: "Docker",
-    credentialFields: [{ key: "image", label: "Image" }],
+    label: sandboxDriverLabels.docker,
+    credentialFields: sandboxDriverCredentialFields.docker,
     metadata: {
       driverRunsIn: ["local"],
       hostStopBehavior: "terminates-host",
@@ -202,7 +220,33 @@ var sandboxDriverCatalog = {
   }
 };
 
+// ../claxedo-helpers/dist/guards.mjs
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function asRecord(value) {
+  return isRecord(value) ? value : void 0;
+}
+
+// src/json.ts
+function text(input) {
+  return typeof input === "string" && input.length > 0 ? input : void 0;
+}
+
 // src/runtime-env.ts
+function workspaceRuntimeBootEnv(input) {
+  const env = {
+    ...workspaceRuntimeTargetEnv(input),
+    ...workspaceRuntimeSourceEnv(input),
+    ...input.env
+  };
+  if (input.runner) env.WORKSPACE_RUNTIME_RUNNER = input.runner;
+  if (input.controlEnv?.relayJwksUrl) env.WORKSPACE_RUNTIME_RELAY_JWKS_URL = input.controlEnv.relayJwksUrl;
+  if (input.controlEnv?.relayVerifyPem) env.WORKSPACE_RUNTIME_RELAY_HOST_VERIFY_PEM = input.controlEnv.relayVerifyPem;
+  if (input.controlEnv?.managementJwksUrl) env.WORKSPACE_RUNTIME_MANAGEMENT_JWKS_URL = input.controlEnv.managementJwksUrl;
+  if (input.controlEnv?.sessionAuthorityUrl) env.WORKSPACE_RUNTIME_SESSION_AUTHORITY_URL = input.controlEnv.sessionAuthorityUrl;
+  return env;
+}
 function workspaceRuntimeTargetEnv(input) {
   return {
     WORKSPACE_RUNTIME_WORKSPACE_ID: input.workspaceId,
@@ -222,10 +266,33 @@ function workspaceRuntimeSourceEnv(input) {
 }
 
 // src/drivers/cloudflare.ts
+function registryEntries(input) {
+  if (!Array.isArray(input)) return [];
+  return input.flatMap((item) => {
+    const row = asRecord(item);
+    if (!row) return [];
+    const entries = Object.entries(row).filter((entry) => typeof entry[1] === "string");
+    return [Object.fromEntries(entries)];
+  });
+}
 var DEFAULT_WORKSPACE_DIR = "/workspace";
 var DEFAULT_RUNTIME_COMMAND = "/usr/local/bin/workspace-runtime";
 var DEFAULT_TIMEOUT_MS = 45e3;
+var DEFAULT_ENSURE_TIMEOUT_MS = 3e5;
 var WORKSPACE_DIRECTORY_LABEL = "claxedo.workspaceDirectory";
+function deadlineSignal(timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(new DOMException("The operation timed out", "TimeoutError")),
+    timeoutMs
+  );
+  return {
+    signal: controller.signal,
+    cleanup() {
+      clearTimeout(timer);
+    }
+  };
+}
 var RUNTIME_DATA_DIR = "/var/lib/claxedo";
 function captureDirectories(workspaceDirectory) {
   return [workspaceDirectory, RUNTIME_DATA_DIR];
@@ -249,6 +316,7 @@ function createCloudflareSandboxDriver(options) {
   const runtimeCommand = options.runtimeCommand ?? DEFAULT_RUNTIME_COMMAND;
   const workspaceDir = options.workspaceDir ?? DEFAULT_WORKSPACE_DIR;
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const ensureTimeoutMs = options.timeoutMs ?? DEFAULT_ENSURE_TIMEOUT_MS;
   const base = cleanUrl(options.workerUrl);
   const headers = {
     Authorization: `Bearer ${options.apiToken}`,
@@ -256,51 +324,64 @@ function createCloudflareSandboxDriver(options) {
   };
   async function call(sandboxId, action, body, method = "POST") {
     const url = `${base}/sandbox/${encodeURIComponent(sandboxId)}${action ? `/${action}` : ""}`;
-    const res = await doFetch(url, {
-      method,
-      headers,
-      ...method === "POST" ? { body: JSON.stringify(body) } : {},
-      signal: AbortSignal.timeout(timeoutMs)
-    });
-    const data = await res.json().catch(() => ({}));
-    return { status: res.status, data };
+    const deadline = deadlineSignal(action === "ensure-runtime" ? ensureTimeoutMs : timeoutMs);
+    try {
+      const res = await doFetch(url, {
+        method,
+        headers,
+        ...method === "POST" ? { body: JSON.stringify(body) } : {},
+        signal: deadline.signal
+      });
+      const data = asRecord(await res.json().catch(() => ({}))) ?? {};
+      return { status: res.status, data };
+    } finally {
+      deadline.cleanup();
+    }
   }
   function workspaceDirectory(input) {
     return input.workspaceRoot ?? workspaceDir;
   }
   async function bootEnv(input, hostId) {
-    const env = {
-      ...workspaceRuntimeTargetEnv({
-        workspaceId: input.workspaceId,
-        hostId,
-        directory: workspaceDirectory(input),
-        port: runtimePort,
-        host: "0.0.0.0"
-      }),
-      ...workspaceRuntimeSourceEnv({ source: input.source }),
-      // Must match RUNTIME_DATA_DIR's capture set below — see its comment.
-      CLAXEDO_DATA_DIR: RUNTIME_DATA_DIR,
-      ...input.env,
-      ...await options.env?.(input, { id: hostId })
-    };
-    if (options.runner) env.WORKSPACE_RUNTIME_RUNNER = options.runner;
-    if (options.controlEnv?.relayJwksUrl) env.WORKSPACE_RUNTIME_RELAY_JWKS_URL = options.controlEnv.relayJwksUrl;
-    if (options.controlEnv?.relayVerifyPem) env.WORKSPACE_RUNTIME_RELAY_HOST_VERIFY_PEM = options.controlEnv.relayVerifyPem;
-    if (options.controlEnv?.managementJwksUrl) env.WORKSPACE_RUNTIME_MANAGEMENT_JWKS_URL = options.controlEnv.managementJwksUrl;
-    return env;
+    return workspaceRuntimeBootEnv({
+      workspaceId: input.workspaceId,
+      hostId,
+      directory: workspaceDirectory(input),
+      port: runtimePort,
+      host: "0.0.0.0",
+      source: input.source,
+      env: {
+        // Must match the checkpoint capture set below.
+        CLAXEDO_DATA_DIR: RUNTIME_DATA_DIR,
+        ...input.env,
+        ...await options.env?.(input, { id: hostId }),
+        // Last, so no caller-supplied variable of the same name can stand in
+        // for a placeholder the outbound handler matches on.
+        ...brokeredPlaceholderEnv(input.secrets)
+      },
+      runner: options.runner,
+      controlEnv: options.controlEnv
+    });
   }
   function egressRegistrations(input) {
-    if (!input.secrets?.length) return void 0;
+    if (input.secrets === void 0) return void 0;
     return input.secrets.map((secret) => {
       if (!secret.header) {
         throw new Error(
-          `cloudflare brokered secret "${secret.name}" requires a header \u2014 the egress proxy injects the value as an HTTP header`
+          `cloudflare brokered secret "${secret.name}" requires a header for native outbound injection`
         );
       }
       if (secret.hosts.length === 0) {
         throw new Error(`cloudflare brokered secret "${secret.name}" requires at least one host in its egress allowlist`);
       }
-      return { hosts: secret.hosts, header: secret.header, value: secret.value };
+      const value = secret.scheme ? `${secret.scheme} ${secret.value}` : secret.value;
+      return {
+        name: secret.name,
+        hosts: secret.hosts,
+        header: secret.header,
+        value,
+        methods: [...secret.methods ?? []],
+        pathPrefixes: [...secret.pathPrefixes ?? []]
+      };
     });
   }
   async function ensureHost(input) {
@@ -327,14 +408,17 @@ function createCloudflareSandboxDriver(options) {
     });
     if (!response) return { provisioning: true, retryAfterMs: 2e3 };
     const { status, data } = response;
-    if (status >= 500) return { provisioning: true, retryAfterMs: 2e3 };
-    if (status >= 400 || !data?.url) {
-      throw new Error(`Cloudflare ensure-runtime failed (${status}): ${data?.error ?? "no runtime url"}`);
+    const runtimeUrl = text(data.url);
+    if (status === 503 && data.error === "workspace-runtime did not become ready") {
+      return { provisioning: true, retryAfterMs: 2e3 };
+    }
+    if (status >= 400 || !runtimeUrl) {
+      throw new Error(`Cloudflare ensure-runtime failed (${status}): ${text(data.error) ?? "no runtime url"}`);
     }
     const targetOut = {
       workspaceId: input.workspaceId,
       sandboxId,
-      url: data.url,
+      url: runtimeUrl,
       hostId,
       driverResourceId: sandboxId,
       driver: {
@@ -378,45 +462,50 @@ function createCloudflareSandboxDriver(options) {
     // workstream removes. The manager turns that throw back into
     // `listingUnsupported`, so an un-upgraded Worker is loudly visible.
     async list() {
-      const res = await doFetch(`${base}/sandboxes`, {
-        method: "GET",
-        headers,
-        signal: AbortSignal.timeout(timeoutMs)
-      });
-      const data = await res.json().catch(() => ({}));
-      if (res.status === 404 || res.status === 501 || data?.supported === false) {
-        throw new CloudflareSandboxListingUnsupportedError(
-          data?.error ?? `Cloudflare sandbox Worker cannot enumerate sandboxes (${res.status}) \u2014 deploy a Worker with the /sandboxes registry route and an R2 BACKUP_BUCKET binding`
-        );
-      }
-      if (!res.ok) {
-        throw new Error(`Cloudflare sandbox listing failed (${res.status}): ${data?.error ?? "unknown error"}`);
+      const deadline = deadlineSignal(timeoutMs);
+      try {
+        const res = await doFetch(`${base}/sandboxes`, {
+          method: "GET",
+          headers,
+          signal: deadline.signal
+        });
+        const data = asRecord(await res.json().catch(() => ({}))) ?? {};
+        if (res.status === 404 || res.status === 501 || data.supported === false) {
+          throw new CloudflareSandboxListingUnsupportedError(
+            text(data.error) ?? `Cloudflare sandbox Worker cannot enumerate sandboxes (${res.status}) \u2014 deploy a Worker with the /sandboxes registry route and an R2 BACKUP_BUCKET binding`
+          );
+        }
+        if (!res.ok) {
+          throw new Error(`Cloudflare sandbox listing failed (${res.status}): ${text(data.error) ?? "unknown error"}`);
+        }
+        return registryEntries(data.sandboxes).flatMap((entry) => {
+          const sandboxId = entry.sandboxId;
+          if (!sandboxId) return [];
+          const { sandboxId: _id, ...labels } = entry;
+          const target = {
+            ...labels.workspaceId ? { workspaceId: labels.workspaceId } : {},
+            sandboxId,
+            // Identity, not a reachable address — GC only names what it destroys.
+            url: `${base}/sandbox/${encodeURIComponent(sandboxId)}/proxy`,
+            // Matches `ensureHost`'s `hostId = sandboxId`, so a live sandbox
+            // cannot fail GC's identity check and be destroyed as an orphan.
+            hostId: sandboxId,
+            driverResourceId: sandboxId,
+            labels,
+            driver: { id: "cloudflare", resourceId: sandboxId }
+          };
+          return [target];
+        });
+      } finally {
+        deadline.cleanup();
       }
-      return (data.sandboxes ?? []).flatMap((entry) => {
-        const sandboxId = entry.sandboxId;
-        if (!sandboxId) return [];
-        const { sandboxId: _id, ...labels } = entry;
-        const target = {
-          ...labels.workspaceId ? { workspaceId: labels.workspaceId } : {},
-          sandboxId,
-          // Identity, not a reachable address — GC only names what it destroys.
-          url: `${base}/sandbox/${encodeURIComponent(sandboxId)}/proxy`,
-          // Matches `ensureHost`'s `hostId = sandboxId`, so a live sandbox
-          // cannot fail GC's identity check and be destroyed as an orphan.
-          hostId: sandboxId,
-          driverResourceId: sandboxId,
-          labels,
-          driver: { id: "cloudflare", resourceId: sandboxId }
-        };
-        return [target];
-      });
     },
     metadata: {
       driverRunsIn: ["worker"],
       hostStopBehavior: "not-supported",
       hostResumeBehavior: "same-host",
       targetAccess: "relay",
-      secretBrokering: "proxy",
+      secretBrokering: "native",
       egressControl: "none",
       persistence: sandboxDriverCatalog.cloudflare.metadata.persistence
     },
@@ -440,10 +529,11 @@ function createCloudflareSandboxDriver(options) {
         "backup",
         { directories: captureDirectories(directory) }
       );
-      if (status >= 400 || !data.backupId) {
-        throw new Error(`Cloudflare backup failed (${status}): ${data.error ?? "no backup id"}`);
+      const backupId = text(data.backupId);
+      if (status >= 400 || !backupId) {
+        throw new Error(`Cloudflare backup failed (${status}): ${text(data.error) ?? "no backup id"}`);
       }
-      return { snapshotId: data.backupId };
+      return { snapshotId: backupId };
     }
   };
 }

package/dist/drivers/daytona.d.ts

@@ -1,4 +1,5 @@
 import type { SandboxDriver, SandboxDriverEnsureInput } from "..";
+import { type WorkspaceRuntimeControlEnv } from "../runtime-env";
 export type DaytonaSandboxLike = {
     id: string;
     state?: string;
@@ -18,6 +19,7 @@ export type DaytonaSandboxLike = {
     start: (timeout?: number) => Promise<void>;
     stop: (timeout?: number) => Promise<void>;
     delete: (timeout?: number) => Promise<void>;
+    updateSecrets: (secrets: Record<string, string>) => Promise<void>;
     /**
      * Replace the sandbox's outbound egress policy in place, without stopping it
      * — the Daytona SDK's `Sandbox.updateNetworkSettings`, which drives the same
@@ -75,17 +77,44 @@ export type DaytonaClientLike = {
     }) => Promise<DaytonaSandboxLike>;
     get: (sandboxIdOrName: string) => Promise<DaytonaSandboxLike>;
     /**
-     * Create-or-update an org secret whose value is only substituted by
-     * Daytona's egress proxy for requests to `hosts`
-     * (https://www.daytona.io/docs/en/secrets/). Referenced from `create`'s
-     * `secrets` map; inside the sandbox the env var holds only an opaque
-     * `dtn_secret_…` placeholder, never the value.
+     * The org-secret service, in the SDK's own shape so `createDefaultClient`
+     * hands `sdk.secret` straight through. Upsert and withdrawal POLICY lives in
+     * this driver (`reconcileBrokeredSecrets`) rather than behind a
+     * `upsertSecret` client method: `create` is a conflict on an existing name,
+     * so a client-level "upsert" is a second implementation of the lookup every
+     * embedder would have to get right.
      */
-    upsertSecret?: (params: {
+    secret?: DaytonaSecretServiceLike;
+};
+/** Identity of an org secret. The plaintext value is write-only and never returned. */
+export type DaytonaSecretLike = {
+    id: string;
+    name: string;
+};
+export type DaytonaSecretServiceLike = {
+    /**
+     * `name` is a PARTIAL match, and pages are cursor-based; callers filter the
+     * page themselves and follow `nextCursor` until it is null.
+     */
+    list: (query?: {
+        name?: string;
+        cursor?: string;
+        limit?: number;
+    }) => Promise<{
+        items: DaytonaSecretLike[];
+        nextCursor?: string | null;
+    }>;
+    /** Throws `DaytonaConflictError` when a secret of that name already exists. */
+    create: (params: {
         name: string;
         value: string;
-        hosts: string[];
-    }) => Promise<void>;
+        hosts?: string[];
+    }) => Promise<DaytonaSecretLike>;
+    update: (secretId: string, params: {
+        value?: string;
+        hosts?: string[];
+    }) => Promise<unknown>;
+    delete: (secretId: string) => Promise<void>;
 };
 export type DaytonaSandboxDriverOptions = {
     /** Daytona API base URL. Defaults to the SDK default. */
@@ -107,11 +136,7 @@ export type DaytonaSandboxDriverOptions = {
     /** Default runner injected as WORKSPACE_RUNTIME_RUNNER. */
     runner?: string;
     /** Static control-plane config injected so the runtime verifies relay-proxied requests. */
-    controlEnv?: {
-        relayJwksUrl?: string;
-        relayVerifyPem?: string;
-        managementJwksUrl?: string;
-    };
+    controlEnv?: WorkspaceRuntimeControlEnv;
     /** Dynamic runtime env that needs the acquired sandbox id or current lease. */
     env?: (input: SandboxDriverEnsureInput, sandbox: DaytonaSandboxLike) => Record<string, string> | Promise<Record<string, string>>;
     /** Auto-stop / auto-delete policy, in minutes. */
@@ -123,5 +148,16 @@ export type DaytonaSandboxDriverOptions = {
     operationTimeoutSeconds?: number;
     /** Injected for tests. */
     client?: DaytonaClientLike;
+    /**
+     * Sink for the two operator-visible events this driver has no other way to
+     * report: a restart it had to force on a live sandbox, and an org secret
+     * under this workspace's prefix that it did not mint and therefore emptied
+     * without mounting.
+     *
+     * Defaults to `console.warn`, deliberately unconditional — the same
+     * reasoning as `onEgressUnenforced` in index.ts. Pass your own to route them
+     * into a logger; pass `() => {}` only if you have another way to see them.
+     */
+    warn?: (message: string) => void;
 };
 export declare function createDaytonaSandboxDriver(options: DaytonaSandboxDriverOptions): SandboxDriver;