@claxedo/sandbox-manager 0.5.2 → 0.7.0

package/dist/index.mjs

@@ -1,7 +1,211 @@
 // src/constants.ts
 var DEFAULT_WORKSPACE_RUNTIME_PORT = 2593;
 
+// 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");
+}
+
+// src/hosted-network-policy.ts
+var SANDBOX_MODEL_PROVIDER_HOSTS = [
+  "api.anthropic.com",
+  "api.openai.com",
+  "generativelanguage.googleapis.com",
+  "openrouter.ai",
+  // Model catalog + engine config, fetched on runner startup.
+  "models.dev",
+  "opencode.ai"
+];
+var SANDBOX_PACKAGE_REGISTRY_HOSTS = [
+  "registry.npmjs.org",
+  "nodejs.org",
+  "pypi.org",
+  "files.pythonhosted.org",
+  "crates.io",
+  "static.crates.io",
+  "index.crates.io",
+  "proxy.golang.org",
+  "sum.golang.org"
+];
+var SANDBOX_BASELINE_EGRESS_HOSTS = [
+  ...SANDBOX_MODEL_PROVIDER_HOSTS,
+  ...SANDBOX_PACKAGE_REGISTRY_HOSTS
+];
+function hostOf(value) {
+  const raw = value?.trim();
+  if (!raw) return;
+  try {
+    const host = new URL(raw).hostname.trim().toLowerCase();
+    return host ? host : void 0;
+  } catch {
+    return;
+  }
+}
+function sandboxSourceHost(source) {
+  if (!source || source.kind !== "git") return;
+  return hostOf(source.repoUrl);
+}
+function hostedSandboxNetworkPolicy(input) {
+  const hosts = /* @__PURE__ */ new Set();
+  for (const entry of input.controlPlane) {
+    const host = hostOf(entry) ?? entry?.trim().toLowerCase();
+    if (host) hosts.add(host);
+  }
+  const sourceHost = sandboxSourceHost(input.source);
+  if (sourceHost) hosts.add(sourceHost);
+  for (const host of SANDBOX_BASELINE_EGRESS_HOSTS) hosts.add(host);
+  for (const host of input.extraHosts ?? []) {
+    const trimmed = host.trim().toLowerCase();
+    if (trimmed) hosts.add(trimmed);
+  }
+  return { mode: "restricted", hosts: [...hosts] };
+}
+
 // src/index.ts
+function validateSandboxPersistenceCapabilities(input) {
+  if (input.resume === "replacement-restore" && input.capture === "none") {
+    return { valid: false, reason: "replacement restore requires a capture source" };
+  }
+  if (input.capture === "none" && input.captureSource !== "not-applicable") {
+    return { valid: false, reason: "capture source behavior requires capture support" };
+  }
+  if (input.capture !== "none" && input.captureSource === "not-applicable") {
+    return { valid: false, reason: "capture support requires source behavior" };
+  }
+  if (input.capture === "same-resource" && input.restoreMount !== "same-resource") {
+    return { valid: false, reason: "same-resource capture requires same-resource restore" };
+  }
+  if (input.restoreMount === "copy-on-write" && input.capture !== "directories") {
+    return { valid: false, reason: "copy-on-write restore requires directory capture" };
+  }
+  return { valid: true };
+}
+function sandboxEgressDisposition(control, net) {
+  if (!net || net.mode === "allow-all") return { action: "enforce" };
+  if (control === "none") return { action: "withhold", reason: "sandbox_egress_uncontained" };
+  const hosts = net.hosts?.length ?? 0;
+  const cidrs = net.cidrs?.length ?? 0;
+  if (hosts === 0 && cidrs === 0) return { action: "enforce" };
+  if (hosts > 0) return { action: "enforce" };
+  return control === "hosts-and-cidrs" ? { action: "enforce" } : { action: "refuse", reason: "sandbox_egress_policy_unenforceable" };
+}
+function egressUnenforcedMessage(input) {
+  const scope = input.workspaceId ? `workspace ${input.workspaceId}` : "every sandbox it provisions";
+  const withheld = input.requested ? ` The requested allowlist (${(input.requested.hosts ?? []).length} host(s), ${(input.requested.cidrs ?? []).length} cidr(s)) was withheld, not applied.` : "";
+  return `[sandbox-manager] SANDBOX EGRESS IS UNRESTRICTED: driver "${input.driver}" declares egressControl: "none", so ${scope} can reach ANY host on the internet, including attacker-controlled buckets \u2014 agent-authored code inside the sandbox has an unmonitored exfiltration path.${withheld} Select a driver that can enforce egress (daytona, vercel) to close it. See public-docs/sandbox-egress.md.`;
+}
+var compositionEgressWarnings = /* @__PURE__ */ new Set();
+function defaultEgressUnenforcedSink(event) {
+  console.warn(event.message);
+}
 function applySandboxLeasePatch(current, patch, updatedAt) {
   return {
     ...current,
@@ -16,14 +220,21 @@ function applySandboxLeasePatch(current, patch, updatedAt) {
     ...patch.labels === void 0 ? {} : { labels: patch.labels },
     ...patch.nextRetryAt === void 0 ? {} : { nextRetryAt: patch.nextRetryAt ?? void 0 },
     ...patch.lastError === void 0 ? {} : { lastError: patch.lastError ?? void 0 },
+    ...patch.checkpoint === void 0 ? {} : { checkpoint: patch.checkpoint ?? void 0 },
+    ...patch.persistence === void 0 ? {} : { persistence: patch.persistence ?? void 0 },
+    ...patch.restore === void 0 ? {} : { restore: patch.restore ?? void 0 },
     updatedAt
   };
 }
+function isSandboxListingUnsupported(err) {
+  return !!err && typeof err === "object" && err.listingUnsupported === true;
+}
 var DEFAULT_APP_LABEL = "claxedo";
 function sandboxId(driver, workspaceId) {
   return `${driver}-${workspaceId}`;
 }
 function ensureHostInput(input) {
+  const egress = sandboxEgressDisposition(input.driver.metadata.egressControl, input.managerInput?.net);
   const labels = {
     app: input.appLabel,
     workspaceId: input.workspaceId,
@@ -37,7 +248,7 @@ function ensureHostInput(input) {
     homeRegion: input.homeRegion,
     epoch: input.lease.epoch,
     labels,
-    bootSource: input.managerInput?.bootSource ?? { kind: "default" },
+    bootSource: input.managerInput?.bootSource ?? (input.lease.checkpoint && input.lease.status !== "ready" && input.driver.metadata.persistence.resume === "replacement-restore" ? { kind: "driver-snapshot", snapshotId: input.lease.checkpoint.providerReference } : { kind: "default" }),
     workspaceRoot: input.managerInput?.workspaceRoot ?? "/workspace",
     runtimeCwd: input.managerInput?.runtimeCwd,
     workspaceRuntimePort: input.managerInput?.workspaceRuntimePort ?? DEFAULT_WORKSPACE_RUNTIME_PORT,
@@ -46,17 +257,66 @@ function ensureHostInput(input) {
     ...input.managerInput?.secrets?.length ? { secrets: input.managerInput.secrets } : {},
     source: input.managerInput?.source,
     exposure: input.managerInput?.exposure ?? (input.driver.metadata.targetAccess === "loopback" ? { kind: "loopback" } : { kind: "relay" }),
-    net: input.managerInput?.net,
+    // Withheld, never downgraded: `undefined` here is the same shape a caller
+    // that asked for no containment produces, so the throwing drivers take
+    // their allow-all path and their throws stay intact for anyone who hands
+    // them a policy directly.
+    ...egress.action === "enforce" && input.managerInput?.net ? { net: input.managerInput.net } : {},
     snapshot: input.managerInput?.snapshot
   };
 }
 function createSandboxManager(options) {
+  const persistence = validateSandboxPersistenceCapabilities(options.driver.metadata.persistence);
+  if (!persistence.valid) throw new Error(`Invalid sandbox persistence capabilities: ${persistence.reason}`);
   const staleAfterMs = options.staleAfterMs ?? 6e4;
   const retryAfterMs = options.retryAfterMs ?? 2e3;
   const now = options.now ?? Date.now;
   const retryDelayMs = options.retryDelayMs ?? ((retryCount) => Math.min(6e4, 1e3 * 2 ** Math.max(0, retryCount - 1)));
   const maxRetryCount = options.maxRetryCount ?? Number.POSITIVE_INFINITY;
   const retryCapCooldownMs = options.retryCapCooldownMs ?? 10 * 6e4;
+  const egressControl = options.driver.metadata.egressControl;
+  const onEgressUnenforced = options.onEgressUnenforced ?? defaultEgressUnenforcedSink;
+  const lifecycleOperations = /* @__PURE__ */ new Map();
+  function reportEgressUnenforced(input) {
+    onEgressUnenforced({
+      phase: "ensure",
+      reason: "sandbox_egress_uncontained",
+      driver: options.driver.id,
+      egressControl,
+      message: egressUnenforcedMessage({
+        phase: "ensure",
+        driver: options.driver.id,
+        workspaceId: input.workspaceId,
+        requested: input.requested
+      }),
+      workspaceId: input.workspaceId,
+      requested: input.requested
+    });
+  }
+  if (egressControl === "none") {
+    const key = `${options.driver.id}|${egressControl}`;
+    if (!compositionEgressWarnings.has(key)) {
+      compositionEgressWarnings.add(key);
+      onEgressUnenforced({
+        phase: "composition",
+        reason: "sandbox_egress_uncontained",
+        driver: options.driver.id,
+        egressControl,
+        message: egressUnenforcedMessage({ phase: "composition", driver: options.driver.id })
+      });
+    }
+  }
+  function lifecycle(workspaceId, kind, run) {
+    const current = lifecycleOperations.get(workspaceId);
+    if (current?.kind === kind) return current.promise;
+    const operation = (current?.promise.catch(() => void 0) ?? Promise.resolve()).then(run);
+    lifecycleOperations.set(workspaceId, { kind, promise: operation });
+    return operation.finally(() => {
+      if (lifecycleOperations.get(workspaceId)?.promise === operation) {
+        lifecycleOperations.delete(workspaceId);
+      }
+    });
+  }
   async function leaseTarget(lease) {
     if (lease.status !== "ready" || !lease.sandboxId || !lease.url || !lease.hostId) {
       return { status: "unavailable", reason: "runtime_lease_not_ready" };
@@ -117,7 +377,8 @@ function createSandboxManager(options) {
         retryCount: 0,
         nextRetryAt: null,
         lastError: null,
-        labels: target.labels ?? ensure.labels
+        labels: target.labels ?? ensure.labels,
+        persistence: options.driver.metadata.persistence
       });
       const resolved = await leaseTarget(updated ?? lease);
       if (resolved.status === "ready") return resolved;
@@ -153,6 +414,13 @@ function createSandboxManager(options) {
   }
   return {
     async ensure(workspaceId, input) {
+      const egress = sandboxEgressDisposition(options.driver.metadata.egressControl, input.net);
+      if (egress.action === "withhold" && input.net) {
+        reportEgressUnenforced({ workspaceId, requested: input.net });
+      }
+      if (egress.action === "refuse") {
+        return { status: "unavailable", error: egress.reason, homeRegion: input.homeRegion };
+      }
       const existing = await options.leaseStore.get(workspaceId);
       if (existing?.nextRetryAt && existing.nextRetryAt > now()) {
         if (existing.status === "acquiring") {
@@ -224,23 +492,50 @@ function createSandboxManager(options) {
       if (!options.driver.snapshot) return { ok: false, reason: "snapshot_unsupported" };
       return { ok: true, ...await options.driver.snapshot(target) };
     },
+    async checkpoint(workspaceId, input) {
+      return await lifecycle(workspaceId, "checkpoint", () => captureSandboxCheckpoint({
+        workspaceId,
+        request: input,
+        leaseStore: options.leaseStore,
+        target: (id) => this.target(id),
+        snapshot: (id) => this.snapshot(id),
+        now
+      }));
+    },
+    async restore(workspaceId, input) {
+      return await lifecycle(workspaceId, "restore", () => restoreSandboxCheckpoint({
+        workspaceId,
+        request: input,
+        leaseStore: options.leaseStore,
+        ensure: (id, next) => this.ensure(id, next),
+        now
+      }));
+    },
     async stop(workspaceId) {
-      const target = await this.target(workspaceId);
-      if (target.status !== "ready") return { ok: false, reason: target.reason };
-      if (options.driver.metadata.hostStopBehavior !== "not-supported") {
-        await (options.driver.suspend ?? options.driver.stop)?.(target);
-      } else {
-        await options.driver.stop?.(target);
-      }
-      await options.leaseStore.update(workspaceId, target.epoch, { status: "stopped" });
-      return { ok: true, status: "stopped" };
+      return await lifecycle(workspaceId, "stop", async () => {
+        const lease = await options.leaseStore.get(workspaceId);
+        if (lease?.status === "stopped") return { ok: true, status: "stopped" };
+        const target = await this.target(workspaceId);
+        if (target.status !== "ready") return { ok: false, reason: target.reason };
+        if (options.driver.metadata.hostStopBehavior !== "not-supported") {
+          await (options.driver.suspend ?? options.driver.stop)?.(target);
+        } else {
+          await options.driver.stop?.(target);
+        }
+        await options.leaseStore.update(workspaceId, target.epoch, { status: "stopped" });
+        return { ok: true, status: "stopped" };
+      });
     },
     async destroy(workspaceId) {
-      const target = await this.target(workspaceId);
-      if (target.status !== "ready") return { ok: false, reason: target.reason };
-      await options.driver.destroy?.(target);
-      await options.leaseStore.update(workspaceId, target.epoch, { status: "destroyed" });
-      return { ok: true, status: "destroyed" };
+      return await lifecycle(workspaceId, "destroy", async () => {
+        const lease = await options.leaseStore.get(workspaceId);
+        if (lease?.status === "destroyed") return { ok: true, status: "destroyed" };
+        const target = await this.target(workspaceId);
+        if (target.status !== "ready") return { ok: false, reason: target.reason };
+        await options.driver.destroy?.(target);
+        await options.leaseStore.update(workspaceId, target.epoch, { status: "destroyed" });
+        return { ok: true, status: "destroyed" };
+      });
     },
     async release(workspaceId) {
       const lease = await options.leaseStore.get(workspaceId);
@@ -254,7 +549,23 @@ function createSandboxManager(options) {
           destroyed: [],
           kept: [],
           skipped: [],
-          failed: []
+          failed: [],
+          listingUnsupported: true,
+          driver: options.driver.id
+        };
+      }
+      let listed;
+      try {
+        listed = await options.driver.list();
+      } catch (err) {
+        if (!isSandboxListingUnsupported(err)) throw err;
+        return {
+          destroyed: [],
+          kept: [],
+          skipped: [],
+          failed: [],
+          listingUnsupported: true,
+          driver: options.driver.id
         };
       }
       const leases = new Map((await options.leaseStore.list()).map((lease) => [lease.workspaceId, lease]));
@@ -265,7 +576,7 @@ function createSandboxManager(options) {
         failed: []
       };
       const appLabel = options.appLabel ?? DEFAULT_APP_LABEL;
-      for (const target of await options.driver.list()) {
+      for (const target of listed) {
         if (target.labels?.app !== appLabel) {
           result.skipped.push({ target, reason: "unmanaged_app_label" });
           continue;
@@ -323,6 +634,16 @@ function createSandboxManager(options) {
 }
 export {
   DEFAULT_WORKSPACE_RUNTIME_PORT,
+  SANDBOX_BASELINE_EGRESS_HOSTS,
+  SANDBOX_MODEL_PROVIDER_HOSTS,
+  SANDBOX_PACKAGE_REGISTRY_HOSTS,
   applySandboxLeasePatch,
-  createSandboxManager
+  captureSandboxCheckpoint,
+  createSandboxManager,
+  hostedSandboxNetworkPolicy,
+  isSandboxListingUnsupported,
+  restoreSandboxCheckpoint,
+  sandboxEgressDisposition,
+  sandboxSourceHost,
+  validateSandboxPersistenceCapabilities
 };

package/dist/lease-policy.d.ts

@@ -1,5 +1,5 @@
 import type { SandboxLeaseRow } from "./lease-types";
-import type { SandboxDriverID } from "./driver-catalog";
+import { type SandboxDriverID } from "./driver-catalog";
 export type SandboxDecision = {
     action: "skip";
     reason: string;
@@ -45,5 +45,4 @@ export declare const DEFAULT_WORKSPACE_HOST_DECISION_CONFIG: SandboxDecisionConf
 export declare function sandboxDriverPlacement(driver: SandboxDriverID): SandboxDriverPlacement;
 export declare function decideSandboxStart(lease: SandboxLeaseRow, placement: SandboxDriverPlacement, now: number, config?: SandboxDecisionConfig): SandboxDecision;
 export declare function decideSandboxHealthFailure(lease: SandboxLeaseRow, _placement: SandboxDriverPlacement, now: number, config?: SandboxDecisionConfig): SandboxDecision;
-export declare function decideSandboxIdle(lease: SandboxLeaseRow, activeHoldCount: number, now: number, config?: SandboxDecisionConfig): SandboxDecision;
 export declare function nextSandboxRetryAt(retryCount: number, now: number, config?: SandboxDecisionConfig): number | null;