@claxedo/sandbox-manager 0.6.0 → 0.9.0

package/README.md

@@ -11,7 +11,7 @@ The package owns the generic pieces:
 - `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`.
+It deliberately does not own Claxedo product auth, billing, app storage schema, routes, or relay tokens. Applications provide those through adapters and call `createSandboxManager`.
 
 ## Install
 
@@ -59,8 +59,8 @@ Swap `createDockerSandboxDriver` for `createDaytonaSandboxDriver`,
 `@claxedo/sandbox-manager/drivers/*`) to place on a hosted provider instead —
 see [`docs/architecture.md`](docs/architecture.md) for the full driver
 comparison and each provider's required options. Swap `createMemoryLeaseStore`
-for a persisted `SandboxLeaseStore` implementation (e.g. backed by SQLite or
-Convex) to survive process restarts.
+for a persisted `SandboxLeaseStore` implementation (e.g. backed by SQLite) to
+survive process restarts.
 
 ## Credentials & secrets
 
@@ -99,26 +99,71 @@ 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`). |
+| Vercel | `native` | Firewall header-transform (`updateNetworkPolicy`): the value is spliced onto egress to the allowlisted hosts as `header`, so the sandbox makes an unauthenticated request ([docs](https://vercel.com/docs/sandbox/concepts/firewall)). `updateNetworkPolicy` replaces the whole policy, so the driver sends the **union** of the create-time allow-list and the brokered hosts — attaching a credential must not revoke egress the caller was already granted (a mid-run `npm install` would start failing), nor widen it to a brokered host the create-time policy never approved. |
+| Cloudflare | `native` | The driver sends named registrations to the API-token-gated Worker. KV holds the values outside the container; native HTTPS outbound handlers replace named placeholders in registered headers. Each request reads KV, so there is no expiring container JWT. KV propagation delay still applies to rotation and withdrawal. |
 | 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:
+readable env. Only `native` keeps the value out of the sandbox and provisions
+normally; 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.
+> Native brokering keeps the original upstream URL. Cloudflare accepts its
+> named placeholder as the complete credential header, or with a Bearer prefix
+> for Authorization API-key clients. Modal remains `none`: its encrypted store
+> exposes credentials as readable environment variables inside the sandbox.
+
+## Egress containment
+
+`SandboxManagerInput.net` restricts what the sandbox can reach on the network.
+It is a *separate* control from brokered secrets, with a **different** posture,
+and the difference matters:
+
+- **Brokered secrets fail closed.** A driver that cannot broker refuses to
+  provision (`error: "secret_brokering_unsupported"`).
+- **Egress does not.** Only `daytona` (names + CIDRs) and `vercel` (names) can
+  enforce an allowlist. Every other driver declares
+  `metadata.egressControl: "none"`, and for those the manager **withholds** the
+  policy and provisions anyway — the sandbox runs with unrestricted egress.
+
+Withholding rather than passing is deliberate: `exe`, `docker`, `modal` and
+`box` throw when handed a restricted policy, and `cloudflare` and the fetch
+bridge accept one and silently ignore it. Withholding at the manager means the
+throwing drivers never see a policy (their throws stay as their own last line of
+defence) and the silently-dropping ones stop pretending.
+
+The gap is never silent. `createSandboxManager` warns at composition, and again
+each time a policy is withheld:
+
+```text
+[sandbox-manager] SANDBOX EGRESS IS UNRESTRICTED: driver "cloudflare" declares
+egressControl: "none", so workspace ws_1 can reach ANY host on the internet …
+```
+
+Pass `onEgressUnenforced` to route that into telemetry instead of `console.warn`
+— it receives a structured `SandboxEgressUnenforcedEvent`. Overriding the sink
+replaces the console warning, so only do it if the replacement is as visible.
+
+**Reuse and resume reapply the policy.** A restricted policy only reaches a
+provider as *creation* parameters, so a sandbox handed back rather than created
+— reuse in `ensureHost`, resume in `resumeHost` — would otherwise run on the
+policy in force when it was first created, possibly a wider one from an earlier
+caller. Daytona's allow-list is mutable post-create
+(`Sandbox.updateNetworkSettings`), so `daytona` reapplies the requested policy
+on both paths. A client too old to expose that call makes the driver **refuse
+the reuse**: a policy reported as applied but not in force is worse than no
+sandbox. Requesting no containment leaves the existing policy alone rather than
+clearing it — "not requested" is not "please unrestrict".
+
+`driver.metadata.egressControl` is the machine-readable source of truth, and
+`sandboxEgressDisposition(control, net)` is the pure predicate the manager uses,
+so you can ask the same question before composing. One exception stays fail
+closed: a hosts-only driver handed an address-only policy is refused
+(`sandbox_egress_policy_unenforceable`) rather than degraded, because that
+driver *does* enforce egress — it just cannot express that encoding.
 
 > SDK conformance: the Daytona secret API and Vercel network-policy transform
 > shapes follow the providers' official docs and are validated structurally

package/dist/checkpoint-manager.d.ts

@@ -0,0 +1,47 @@
+import type { SandboxCheckpointReference, SandboxEnsureResult, SandboxLease, SandboxLeaseStore, SandboxManagerInput, SandboxSnapshotManagerResult, SandboxTargetResult } from ".";
+export type SandboxCheckpointRuntime = {
+    freeze: (policy: "drain" | "interrupt") => Promise<void>;
+    flush: () => Promise<void>;
+    scrub: () => Promise<void>;
+    resume: () => Promise<void>;
+    reconcile: (input: {
+        epoch: number;
+        checkpointId: string;
+    }) => Promise<void>;
+};
+export type SandboxCheckpointCaptureInput = {
+    runtime: SandboxCheckpointRuntime;
+    policy?: "drain" | "interrupt";
+    retentionExpiresAt?: number;
+};
+export type SandboxCheckpointRestoreInput = {
+    runtime: SandboxCheckpointRuntime;
+    checkpointId?: string;
+    ensure?: Omit<SandboxManagerInput, "homeRegion">;
+};
+export type SandboxCheckpointResult = {
+    status: "ready";
+    lease: SandboxLease;
+    checkpoint: SandboxCheckpointReference;
+} | {
+    status: "provisioning";
+    lease: SandboxLease;
+    checkpoint: SandboxCheckpointReference;
+    retryAfterMs: number;
+};
+export declare function captureSandboxCheckpoint(input: {
+    workspaceId: string;
+    request: SandboxCheckpointCaptureInput;
+    leaseStore: SandboxLeaseStore;
+    target: (workspaceId: string) => Promise<SandboxTargetResult>;
+    snapshot: (workspaceId: string) => Promise<SandboxSnapshotManagerResult>;
+    now?: () => number;
+    checkpointId?: () => string;
+}): Promise<SandboxCheckpointResult>;
+export declare function restoreSandboxCheckpoint(input: {
+    workspaceId: string;
+    request: SandboxCheckpointRestoreInput;
+    leaseStore: SandboxLeaseStore;
+    ensure: (workspaceId: string, input: SandboxManagerInput) => Promise<SandboxEnsureResult>;
+    now?: () => number;
+}): Promise<SandboxCheckpointResult>;

package/dist/checkpoint-manager.mjs

@@ -0,0 +1,116 @@
+// src/checkpoint-manager.ts
+async function captureSandboxCheckpoint(input) {
+  const lease = await requireLease(input.leaseStore, input.workspaceId);
+  if (lease.status !== "ready") throw new Error("workspace_checkpoint_lease_not_ready");
+  const persistence = lease.persistence;
+  if (!persistence || persistence.capture === "none") throw new Error("workspace_checkpoint_unsupported");
+  const target = await input.target(input.workspaceId);
+  if (target.status !== "ready") throw new Error(target.reason);
+  await input.request.runtime.freeze(input.request.policy ?? "drain");
+  let capturedSource = false;
+  try {
+    await input.request.runtime.flush();
+    await input.request.runtime.scrub();
+    const captured = persistence.capture === "same-resource" ? { ok: true, snapshotId: target.driverResourceId ?? target.sandboxId } : await input.snapshot(input.workspaceId);
+    if (!captured.ok) throw new Error(captured.reason);
+    capturedSource = true;
+    const capturedAt = (input.now ?? Date.now)();
+    const checkpoint = {
+      id: input.checkpointId?.() ?? `cp_${lease.epoch}_${crypto.randomUUID()}`,
+      providerReference: captured.snapshotId,
+      sourceEpoch: lease.epoch,
+      capturedAt,
+      metadata: {
+        scope: persistence.capture,
+        sourceBehavior: requireCaptureSource(persistence.captureSource),
+        ...input.request.retentionExpiresAt === void 0 ? {} : { retentionExpiresAt: input.request.retentionExpiresAt },
+        restoreMount: requireRestoreMount(persistence.restoreMount)
+      }
+    };
+    const updated = await input.leaseStore.update(input.workspaceId, lease.epoch, {
+      checkpoint,
+      restore: null,
+      ...persistence.captureSource === "stopped" || persistence.captureSource === "deleted" ? { status: "stopped" } : {}
+    });
+    if (!updated) throw new Error("workspace_checkpoint_epoch_fenced");
+    return { status: "ready", lease: updated, checkpoint };
+  } finally {
+    if (!capturedSource || persistence.captureSource === "preserved") {
+      await input.request.runtime.resume();
+    }
+  }
+}
+async function restoreSandboxCheckpoint(input) {
+  const lease = await requireLease(input.leaseStore, input.workspaceId);
+  const checkpoint = lease.checkpoint;
+  if (!checkpoint || input.request.checkpointId && checkpoint.id !== input.request.checkpointId) {
+    throw new Error("workspace_checkpoint_not_found");
+  }
+  if (lease.restore?.state === "ready" && lease.restore.checkpointId === checkpoint.id) {
+    return { status: "ready", lease, checkpoint };
+  }
+  const requestedAt = lease.restore?.checkpointId === checkpoint.id ? lease.restore.requestedAt : (input.now ?? Date.now)();
+  const restoring = lease.restore?.checkpointId === checkpoint.id && lease.restore.state !== "pending" ? lease.restore : {
+    checkpointId: checkpoint.id,
+    sourceEpoch: checkpoint.sourceEpoch,
+    state: "restoring",
+    requestedAt,
+    startedAt: (input.now ?? Date.now)()
+  };
+  const staged = lease.status === "ready" && lease.epoch === checkpoint.sourceEpoch ? await input.leaseStore.update(input.workspaceId, lease.epoch, { status: "stopped", restore: restoring }) : await input.leaseStore.update(input.workspaceId, lease.epoch, { restore: restoring });
+  if (!staged) throw new Error("workspace_restore_epoch_fenced");
+  const result = await input.ensure(input.workspaceId, {
+    homeRegion: staged.homeRegion,
+    ...input.request.ensure,
+    bootSource: checkpoint.metadata.restoreMount === "same-resource" ? { kind: "default" } : { kind: "driver-snapshot", snapshotId: checkpoint.providerReference }
+  });
+  const current = await requireLease(input.leaseStore, input.workspaceId);
+  if (result.status === "provisioning") {
+    return { status: "provisioning", lease: current, checkpoint, retryAfterMs: result.retryAfterMs };
+  }
+  if (result.status !== "ready") {
+    const failedAt = (input.now ?? Date.now)();
+    await input.leaseStore.update(input.workspaceId, current.epoch, {
+      restore: {
+        checkpointId: checkpoint.id,
+        sourceEpoch: checkpoint.sourceEpoch,
+        state: "failed",
+        requestedAt,
+        startedAt: "startedAt" in restoring ? restoring.startedAt : void 0,
+        failedAt,
+        error: result.error ?? "workspace_restore_unavailable"
+      }
+    });
+    throw new Error(result.error ?? "workspace_restore_unavailable");
+  }
+  await input.request.runtime.reconcile({ epoch: result.epoch, checkpointId: checkpoint.id });
+  const ready = await input.leaseStore.update(input.workspaceId, result.epoch, {
+    restore: {
+      checkpointId: checkpoint.id,
+      sourceEpoch: checkpoint.sourceEpoch,
+      state: "ready",
+      requestedAt,
+      startedAt: "startedAt" in restoring && restoring.startedAt !== void 0 ? restoring.startedAt : (input.now ?? Date.now)(),
+      completedAt: (input.now ?? Date.now)()
+    }
+  });
+  if (!ready) throw new Error("workspace_restore_epoch_fenced");
+  return { status: "ready", lease: ready, checkpoint };
+}
+async function requireLease(store, workspaceId) {
+  const lease = await store.get(workspaceId);
+  if (!lease) throw new Error("workspace_checkpoint_lease_missing");
+  return lease;
+}
+function requireCaptureSource(value) {
+  if (value === "preserved" || value === "stopped" || value === "deleted") return value;
+  throw new Error("workspace_checkpoint_capabilities_invalid");
+}
+function requireRestoreMount(value) {
+  if (value === "same-resource" || value === "copy-on-write" || value === "new-resource") return value;
+  throw new Error("workspace_checkpoint_capabilities_invalid");
+}
+export {
+  captureSandboxCheckpoint,
+  restoreSandboxCheckpoint
+};

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

@@ -3,3 +3,14 @@
  * Daytona currently accepts at most 10 entries.
  */
 export declare function formatDaytonaAllowList(cidrs: string[]): string;
+/**
+ * Format hostnames for Daytona SDK `domainAllowList` parameter.
+ *
+ * Deliberately does NOT truncate, unlike the CIDR formatter above. Silently
+ * dropping entries from an egress allowlist is the worst of both worlds: the
+ * sandbox stays contained, but it loses reachability the caller believed it
+ * granted and nothing anywhere says so. Daytona documents no cap on
+ * `domainAllowList`; if one exists, an over-long list fails the create call
+ * loudly, which is the outcome we want.
+ */
+export declare function formatDaytonaDomainAllowList(hosts: string[]): string;

package/dist/daytona-allow-list.mjs

@@ -2,6 +2,10 @@
 function formatDaytonaAllowList(cidrs) {
   return cidrs.slice(0, 10).join(",");
 }
+function formatDaytonaDomainAllowList(hosts) {
+  return [...new Set(hosts)].join(",");
+}
 export {
-  formatDaytonaAllowList
+  formatDaytonaAllowList,
+  formatDaytonaDomainAllowList
 };

package/dist/driver-catalog.d.ts

@@ -1,65 +1,18 @@
-import type { SandboxDriverMetadata } from "./index";
-export declare const sandboxDriverIds: readonly ["daytona", "modal", "vercel", "cloudflare", "box", "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;
-    };
-    box?: {
-        api_key?: string;
-    };
-    docker?: {
-        image?: string;
-    };
-};
-export type SandboxDriverConfig = {
-    default_driver?: SandboxDriverID;
-    auth?: SandboxDriverAuth;
-};
+import { validateSandboxPersistenceCapabilities, type SandboxDriverMetadata } from "./index";
+import { defaultSandboxDriverID, listSandboxDrivers, sandboxDriverId, type SandboxDriverAuth, type SandboxDriverConfig, type SandboxDriverEnv, type SandboxDriverID } from "@claxedo/sandbox-contract";
+export { defaultSandboxDriverID, listSandboxDrivers, sandboxDriverId };
 export type SandboxDriverCatalogEntry = {
     id: SandboxDriverID;
     label: string;
     metadata: SandboxDriverMetadata;
-    credentialFields: Array<{
+    credentialFields: ReadonlyArray<{
         key: string;
         label: string;
         secret?: boolean;
     }>;
 };
+export { validateSandboxPersistenceCapabilities };
 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): "box" | "cloudflare" | "daytona" | "docker" | "modal" | "vercel" | 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: "box" | "cloudflare" | "daytona" | "docker" | "modal" | "vercel";
-    drivers: {
-        id: "box" | "cloudflare" | "daytona" | "docker" | "modal" | "vercel";
-        label: string;
-        fields: {
-            key: string;
-            label: string;
-            secret?: boolean;
-        }[];
-        configured: boolean;
-        source: "config" | "managed" | "none";
-        default: boolean;
-    }[];
-};
-type SandboxDriverEnv = Record<string, string | undefined>;
-export {};