@claxedo/sandbox-manager 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { DEFAULT_WORKSPACE_RUNTIME_PORT } from "./constants";
-import type { SandboxDriverID } from "./driver-catalog";
+import type { SandboxDriverID, SandboxSecretBrokering } from "@claxedo/sandbox-contract";
+export type { SandboxSecretBrokering } from "@claxedo/sandbox-contract";
 import { type SandboxCheckpointCaptureInput, type SandboxCheckpointRestoreInput, type SandboxCheckpointResult } from "./checkpoint-manager";
 export { DEFAULT_WORKSPACE_RUNTIME_PORT };
 export * from "./checkpoint-manager";
@@ -72,25 +73,16 @@ export type SandboxDriverMetadata = {
      * How the driver can honor a `SandboxBrokeredSecret` — a credential the
      * sandbox may USE for outbound requests but must NEVER be able to READ.
      *
-     * - `"native"` — the provider brokers it automatically on egress to the
-     *   allowlisted hosts, with no extra infrastructure: Daytona secret
-     *   placeholders + egress proxy; Vercel firewall header transforms. The
-     *   driver injects it during `ensureHost`.
-     * - `"proxy"` — brokering is achievable but only via a host-operated egress
-     *   proxy the driver routes through (Cloudflare's official Worker-proxy
-     *   pattern: the sandbox gets a short-lived JWT, egress hits the Worker,
-     *   the Worker injects the real credential — the raw value never enters the
-     *   sandbox). Not automatic; requires the host's proxy to be wired.
+     * - `"native"` — the provider brokers it on egress to the allowlisted hosts
+     *   with no extra infrastructure of ours: Daytona secret placeholders,
+     *   Vercel firewall header transforms, Cloudflare outbound handlers reading
+     *   the value from KV. The driver installs it during `ensureHost`.
      * - `"none"` — no way to keep the value out of sandbox processes. The
      *   provider may still have an encrypted secret STORE (e.g. Modal secrets),
-     *   but those are exposed as readable env vars, so they cannot satisfy the
+     *   but it is exposed as a readable env var, which cannot satisfy the
      *   never-readable contract.
-     *
-     * The manager fails closed unless the driver actually injects brokered
-     * secrets (today: `"native"` only). `"proxy"` records an achievable ceiling
-     * that is not yet wired and therefore also fails closed.
      */
-    secretBrokering: "native" | "proxy" | "none";
+    secretBrokering: SandboxSecretBrokering;
     /**
      * How the driver can enforce a RESTRICTED `SandboxNetworkPolicy` — i.e.
      * whether the sandbox's outbound network can actually be contained.
@@ -196,7 +188,7 @@ export type SandboxEgressUnenforcedEvent = {
  *
  * Guarantees enforced by the manager: brokered secrets are never written to
  * labels, never logged, and never captured in a driver snapshot. A driver
- * whose `metadata.secretBrokering !== "native"` cannot honor them and the
+ * whose `metadata.secretBrokering` is not `"native"` cannot honor them and the
  * manager refuses to provision (fail-closed).
  */
 export type SandboxBrokeredSecret = {
@@ -213,7 +205,49 @@ export type SandboxBrokeredSecret = {
      * the sandbox to attach itself (Daytona).
      */
     header?: string;
+    /**
+     * The authentication scheme `header` carries, when it has one (`Bearer`).
+     *
+     * A driver that WRITES the whole header composes `"<scheme> <value>"`; one
+     * that SUBSTITUTES a placeholder the sandbox already wrote after the scheme
+     * ignores it, because the scheme is in the request before the value is.
+     */
+    scheme?: string;
+    /**
+     * The methods and path prefixes the credential may be attached to, on top of
+     * `hosts`. A vendor host serves far more than the routes a turn needs —
+     * api.anthropic.com also answers the organization-admin API — and everything
+     * sharing the sandbox reaches the same host.
+     *
+     * Optional so a producer that has not been taught to state a policy still
+     * type-checks, and fails closed instead: a driver that can express them
+     * attaches the credential only within them, so an absent or empty policy
+     * names a host and nothing else, and nothing is spendable at a host alone. A
+     * driver whose provider cannot express them documents that it drops them,
+     * and the host allowlist is all the containment there is.
+     */
+    methods?: readonly string[];
+    pathPrefixes?: readonly string[];
 };
+/**
+ * What the sandbox presents so a header-injecting driver recognizes the request
+ * as one asking for that secret.
+ *
+ * Carries no authority: the value is attached at the edge, keyed by the host
+ * and this string, and the string itself is never accepted by a vendor. The
+ * Cloudflare sandbox Worker is deployed on its own and cannot depend on this
+ * package, so it matches on its own copy of the prefix; a driver minting
+ * anything else sends every brokered request upstream bare, which is what
+ * `brokered-placeholder.test.ts` exists to catch.
+ */
+export declare function brokeredSecretPlaceholder(name: string): string;
+/**
+ * The environment a header-injecting driver must add so the sandbox can present
+ * each secret. Daytona is absent from this: its own mount fills the same
+ * variables with the placeholder it substitutes, and an env entry would shadow
+ * it with a string Daytona does not know.
+ */
+export declare function brokeredPlaceholderEnv(secrets: readonly SandboxBrokeredSecret[] | undefined): Record<string, string>;
 export type SandboxExposure = {
     kind: "loopback";
 } | {
@@ -290,6 +324,8 @@ export type SandboxNetworkPolicy = {
     hosts?: string[];
     cidrs?: string[];
 };
+/** Brokered destinations are the minimum egress needed to use the credential. */
+export declare function sandboxNetworkPolicyWithBrokeredHosts(policy: SandboxNetworkPolicy, secrets: readonly SandboxBrokeredSecret[] | undefined): SandboxNetworkPolicy;
 export type SandboxBootSource = {
     kind: "image";
     image: string;
@@ -431,6 +467,14 @@ export type SandboxRegisterInput = {
     now?: number;
 };
 export type SandboxHeartbeatInput = SandboxRegisterInput;
+/**
+ * What a provisioning cycle is actually doing, for honest progress UI.
+ * `restore` = booting a replacement restored from the workspace's snapshot
+ * (files come back), `resume` = restarting the same paused resource,
+ * `cold-start` = a fresh sandbox with no prior state to bring back (first
+ * boot, or nothing snapshot-able survived).
+ */
+export type SandboxBootMode = "restore" | "resume" | "cold-start";
 export type SandboxEnsureResult = ({
     status: "ready";
 } & SandboxTarget & {
@@ -441,6 +485,7 @@ export type SandboxEnsureResult = ({
     retryAfterMs: number;
     epoch: number;
     homeRegion: SandboxRegion;
+    bootMode?: SandboxBootMode;
 } | {
     status: "unavailable";
     retryAfterMs?: number;

package/dist/index.mjs

@@ -141,16 +141,16 @@ var SANDBOX_BASELINE_EGRESS_HOSTS = [
 ];
 function hostOf(value) {
   const raw = value?.trim();
-  if (!raw) return;
+  if (!raw) return void 0;
   try {
     const host = new URL(raw).hostname.trim().toLowerCase();
     return host ? host : void 0;
   } catch {
-    return;
+    return void 0;
   }
 }
 function sandboxSourceHost(source) {
-  if (!source || source.kind !== "git") return;
+  if (!source || source.kind !== "git") return void 0;
   return hostOf(source.repoUrl);
 }
 function hostedSandboxNetworkPolicy(input) {
@@ -206,6 +206,12 @@ var compositionEgressWarnings = /* @__PURE__ */ new Set();
 function defaultEgressUnenforcedSink(event) {
   console.warn(event.message);
 }
+function brokeredSecretPlaceholder(name) {
+  return `claxedo-broker:${name}`;
+}
+function brokeredPlaceholderEnv(secrets) {
+  return Object.fromEntries((secrets ?? []).map((secret) => [secret.name, brokeredSecretPlaceholder(secret.name)]));
+}
 function applySandboxLeasePatch(current, patch, updatedAt) {
   return {
     ...current,
@@ -226,6 +232,17 @@ function applySandboxLeasePatch(current, patch, updatedAt) {
     updatedAt
   };
 }
+function sandboxNetworkPolicyWithBrokeredHosts(policy, secrets) {
+  if (policy.mode !== "restricted" || !secrets?.length) return policy;
+  const hosts = [.../* @__PURE__ */ new Set([
+    ...policy.hosts ?? [],
+    ...secrets.flatMap((secret) => secret.hosts)
+  ])].toSorted();
+  return {
+    ...policy,
+    ...hosts.length ? { hosts } : {}
+  };
+}
 function isSandboxListingUnsupported(err) {
   return !!err && typeof err === "object" && err.listingUnsupported === true;
 }
@@ -254,14 +271,17 @@ function ensureHostInput(input) {
     workspaceRuntimePort: input.managerInput?.workspaceRuntimePort ?? DEFAULT_WORKSPACE_RUNTIME_PORT,
     env: input.managerInput?.env ?? {},
     // Brokered secrets ride their own channel — NEVER merged into labels or env.
-    ...input.managerInput?.secrets?.length ? { secrets: input.managerInput.secrets } : {},
+    // Presence of the key, not its length, is the signal: `[]` is the caller
+    // withdrawing every brokered secret, and dropping it would reach the driver
+    // as "preserve what you have".
+    ...input.managerInput?.secrets ? { secrets: input.managerInput.secrets } : {},
     source: input.managerInput?.source,
     exposure: input.managerInput?.exposure ?? (input.driver.metadata.targetAccess === "loopback" ? { kind: "loopback" } : { kind: "relay" }),
     // 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 } : {},
+    ...egress.action === "enforce" && input.managerInput?.net ? { net: sandboxNetworkPolicyWithBrokeredHosts(input.managerInput.net, input.managerInput.secrets) } : {},
     snapshot: input.managerInput?.snapshot
   };
 }
@@ -306,17 +326,27 @@ function createSandboxManager(options) {
       });
     }
   }
-  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 });
+  function lifecycleQueue(current) {
+    return current?.promise.catch(() => void 0) ?? Promise.resolve();
+  }
+  function lifecycleSettle(workspaceId, entry, operation) {
+    lifecycleOperations.set(workspaceId, entry);
     return operation.finally(() => {
-      if (lifecycleOperations.get(workspaceId)?.promise === operation) {
-        lifecycleOperations.delete(workspaceId);
-      }
+      if (lifecycleOperations.get(workspaceId) === entry) lifecycleOperations.delete(workspaceId);
     });
   }
+  function checkpointLifecycle(workspaceId, kind, run) {
+    const current = lifecycleOperations.get(workspaceId);
+    if (current?.kind === kind) return current.promise;
+    const operation = lifecycleQueue(current).then(run);
+    return lifecycleSettle(workspaceId, { kind, promise: operation }, operation);
+  }
+  function mutationLifecycle(workspaceId, kind, run) {
+    const current = lifecycleOperations.get(workspaceId);
+    if (current?.kind === kind) return current.promise;
+    const operation = lifecycleQueue(current).then(run);
+    return lifecycleSettle(workspaceId, { kind, promise: operation }, operation);
+  }
   async function leaseTarget(lease) {
     if (lease.status !== "ready" || !lease.sandboxId || !lease.url || !lease.hostId) {
       return { status: "unavailable", reason: "runtime_lease_not_ready" };
@@ -337,6 +367,12 @@ function createSandboxManager(options) {
       homeRegion: lease.homeRegion
     };
   }
+  function leaseBootMode(lease) {
+    const restoring = Boolean(lease.checkpoint) && lease.status !== "ready" && options.driver.metadata.persistence.resume === "replacement-restore";
+    if (restoring) return "restore";
+    if (lease.sandboxId && options.driver.resumeHost) return "resume";
+    return "cold-start";
+  }
   async function provision(workspaceId, lease, homeRegion, managerInput) {
     try {
       const ensure = ensureHostInput({
@@ -355,7 +391,8 @@ function createSandboxManager(options) {
           homeRegion
         };
       }
-      const target = lease.sandboxId && ensure.bootSource?.kind === "default" && options.driver.resumeHost ? await options.driver.resumeHost({ lease, ensure }) : await options.driver.ensureHost(ensure);
+      const resuming = Boolean(lease.sandboxId && ensure.bootSource?.kind === "default" && options.driver.resumeHost);
+      const target = resuming ? await options.driver.resumeHost({ lease, ensure }) : await options.driver.ensureHost(ensure);
       if ("provisioning" in target) {
         await options.leaseStore.update(workspaceId, lease.epoch, {
           status: "acquiring",
@@ -365,7 +402,11 @@ function createSandboxManager(options) {
           status: "provisioning",
           retryAfterMs: target.retryAfterMs,
           epoch: lease.epoch,
-          homeRegion
+          homeRegion,
+          // Honest progress for the connect UI: which of the three boot paths
+          // this cycle is on. Derived from the same inputs that CHOSE the path
+          // above, so it cannot drift from what actually ran.
+          bootMode: resuming ? "resume" : ensure.bootSource?.kind === "driver-snapshot" ? "restore" : "cold-start"
         };
       }
       const updated = await options.leaseStore.update(workspaceId, lease.epoch, {
@@ -428,7 +469,8 @@ function createSandboxManager(options) {
             status: "provisioning",
             retryAfterMs: existing.nextRetryAt - now(),
             epoch: existing.epoch,
-            homeRegion: existing.homeRegion
+            homeRegion: existing.homeRegion,
+            bootMode: leaseBootMode(existing)
           };
         }
         return {
@@ -464,7 +506,8 @@ function createSandboxManager(options) {
           status: "provisioning",
           retryAfterMs: acquired.retryAfterMs,
           epoch: acquired.lease.epoch,
-          homeRegion: acquired.lease.homeRegion
+          homeRegion: acquired.lease.homeRegion,
+          bootMode: leaseBootMode(acquired.lease)
         };
       }
       return provision(workspaceId, acquired.lease, input.homeRegion, input);
@@ -493,7 +536,7 @@ function createSandboxManager(options) {
       return { ok: true, ...await options.driver.snapshot(target) };
     },
     async checkpoint(workspaceId, input) {
-      return await lifecycle(workspaceId, "checkpoint", () => captureSandboxCheckpoint({
+      return await checkpointLifecycle(workspaceId, "checkpoint", () => captureSandboxCheckpoint({
         workspaceId,
         request: input,
         leaseStore: options.leaseStore,
@@ -503,7 +546,7 @@ function createSandboxManager(options) {
       }));
     },
     async restore(workspaceId, input) {
-      return await lifecycle(workspaceId, "restore", () => restoreSandboxCheckpoint({
+      return await checkpointLifecycle(workspaceId, "restore", () => restoreSandboxCheckpoint({
         workspaceId,
         request: input,
         leaseStore: options.leaseStore,
@@ -512,7 +555,7 @@ function createSandboxManager(options) {
       }));
     },
     async stop(workspaceId) {
-      return await lifecycle(workspaceId, "stop", async () => {
+      return await mutationLifecycle(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);
@@ -527,7 +570,7 @@ function createSandboxManager(options) {
       });
     },
     async destroy(workspaceId) {
-      return await lifecycle(workspaceId, "destroy", async () => {
+      return await mutationLifecycle(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);
@@ -617,7 +660,7 @@ function createSandboxManager(options) {
     const expectedEpoch = input.epoch ?? current.epoch;
     if (current.epoch !== expectedEpoch) return { ok: false, reason: "runtime_lease_epoch_mismatch" };
     const timestamp = input.now ?? now();
-    const status = input.status === "unhealthy" || input.ok === false ? "unavailable" : input.ok ? "ready" : current.status;
+    const status = input.status === "unhealthy" || !input.ok ? "unavailable" : input.ok ? "ready" : current.status;
     const updated = await options.leaseStore.update(workspaceId, expectedEpoch, {
       status,
       ...input.sandboxId ? { sandboxId: input.sandboxId } : {},
@@ -638,12 +681,15 @@ export {
   SANDBOX_MODEL_PROVIDER_HOSTS,
   SANDBOX_PACKAGE_REGISTRY_HOSTS,
   applySandboxLeasePatch,
+  brokeredPlaceholderEnv,
+  brokeredSecretPlaceholder,
   captureSandboxCheckpoint,
   createSandboxManager,
   hostedSandboxNetworkPolicy,
   isSandboxListingUnsupported,
   restoreSandboxCheckpoint,
   sandboxEgressDisposition,
+  sandboxNetworkPolicyWithBrokeredHosts,
   sandboxSourceHost,
   validateSandboxPersistenceCapabilities
 };

package/dist/json.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Reading untrusted JSON: driver API responses, CLI output, stored records.
+ *
+ * Drivers all face the same problem — a provider hands back `any`, and the code
+ * needs a few named fields out of it. Narrowing through these keeps the check
+ * and the type in the same place, instead of each site asserting a shape it
+ * never verified. The object check is `@claxedo/helpers/guards`, re-exported
+ * under the names the drivers use.
+ */
+export { asRecord as record, isRecord } from "@claxedo/helpers/guards";
+/** A non-empty string, or undefined — the shape almost every provider field wants. */
+export declare function text(input: unknown): string | undefined;
+export declare function num(input: unknown): number | undefined;

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 "@claxedo/sandbox-contract";
 export type SandboxDecision = {
     action: "skip";
     reason: string;
@@ -44,5 +44,9 @@ export type SandboxDriverPlacement = {
 export declare const DEFAULT_WORKSPACE_HOST_DECISION_CONFIG: SandboxDecisionConfig;
 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;
+/**
+ * Health-failure policy is placement-independent: retry budget and backoff are
+ * the same question for every driver, so this deliberately takes no placement.
+ */
+export declare function decideSandboxHealthFailure(lease: SandboxLeaseRow, now: number, config?: SandboxDecisionConfig): SandboxDecision;
 export declare function nextSandboxRetryAt(retryCount: number, now: number, config?: SandboxDecisionConfig): number | null;

package/dist/lease-policy.mjs

@@ -24,12 +24,42 @@ var SANDBOX_BASELINE_EGRESS_HOSTS = [
   ...SANDBOX_PACKAGE_REGISTRY_HOSTS
 ];
 
+// ../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",
@@ -49,17 +79,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",
@@ -73,20 +101,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",
@@ -100,20 +123,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",
@@ -127,23 +145,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",
@@ -157,8 +167,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",
@@ -178,8 +188,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",
@@ -236,7 +246,7 @@ function decideSandboxStart(lease, placement, now, config = DEFAULT_WORKSPACE_HO
   }
   return decideStartMethod(lease, placement);
 }
-function decideSandboxHealthFailure(lease, _placement, now, config = DEFAULT_WORKSPACE_HOST_DECISION_CONFIG) {
+function decideSandboxHealthFailure(lease, now, config = DEFAULT_WORKSPACE_HOST_DECISION_CONFIG) {
   if (lease.status !== "ready" && lease.status !== "unhealthy") {
     return { action: "skip", reason: `status is ${lease.status}, health check not applicable` };
   }

package/dist/lease-types.d.ts

@@ -1,4 +1,3 @@
-import type { SandboxDriverID } from "./driver-catalog";
 import type { SandboxCheckpointReference, SandboxPersistenceCapabilities, SandboxRestoreStatus } from "./index";
 export type SandboxLeaseRowStatus = "pending" | "acquiring" | "starting" | "ready" | "unhealthy" | "backoff" | "stopping" | "stopped" | "destroyed" | "failed";
 export type SandboxComputeClass = "small" | "medium" | "large" | "gpu";
@@ -8,7 +7,17 @@ export type SandboxLeaseRow = {
     home_region?: string;
     epoch: number;
     status: SandboxLeaseRowStatus;
-    driver: SandboxDriverID;
+    /**
+     * The id the driver was registered with, which is any string: the manager
+     * dispatches on whatever a composition registers (`stores/d1.test.ts`
+     * provisions one called `"test-provider"`), and every other type this value
+     * flows between — `SandboxLease["driver"]`, `SandboxLeaseAcquireInput["driver"]`,
+     * `SandboxTarget["driver"]["id"]` — is already `string`. Typing the row as the
+     * closed `SandboxDriverID` made it the odd one out and forced every store to
+     * assert into it. Narrow with `isSandboxDriverID` where a CATALOG entry is
+     * needed, which is the only place the closed set is the right question.
+     */
+    driver: string;
     driver_resource_id: string | null;
     driver_snapshot_id: string | null;
     sandbox_id: string | null;

package/dist/runtime-env.d.ts

@@ -1,4 +1,15 @@
-import type { SandboxDriverID } from "./driver-catalog";
+import type { SandboxDriverID } from "@claxedo/sandbox-contract";
+export type WorkspaceRuntimeControlEnv = {
+    relayJwksUrl?: string;
+    relayVerifyPem?: string;
+    managementJwksUrl?: string;
+    sessionAuthorityUrl?: string;
+};
+export declare function workspaceRuntimeBootEnv(input: Parameters<typeof workspaceRuntimeTargetEnv>[0] & Parameters<typeof workspaceRuntimeSourceEnv>[0] & {
+    env?: Record<string, string>;
+    runner?: string;
+    controlEnv?: WorkspaceRuntimeControlEnv;
+}): Record<string, string>;
 export declare function workspaceRuntimeTargetEnv(input: {
     workspaceId: string;
     hostId?: string;

package/dist/runtime-env.mjs

@@ -1,4 +1,17 @@
 // 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,
@@ -27,6 +40,7 @@ function workspaceRuntimeServiceExposureEnv(input) {
   };
 }
 export {
+  workspaceRuntimeBootEnv,
   workspaceRuntimeServiceExposureEnv,
   workspaceRuntimeSourceEnv,
   workspaceRuntimeTargetEnv

package/dist/service-url-exposure.d.ts

@@ -1,4 +1,4 @@
-import type { SandboxDriverID } from "./driver-catalog";
+import type { SandboxDriverID } from "@claxedo/sandbox-contract";
 export type SandboxServiceUrlExposure = {
     source: "driver-service-url";
     access: "private" | "public" | "driver-authenticated" | "unknown";
@@ -7,4 +7,3 @@ export type SandboxServiceUrlExposure = {
     note?: string;
 };
 export declare function sandboxServiceUrlExposure(driver: SandboxDriverID): SandboxServiceUrlExposure;
-export declare function sandboxServiceUrlExposureEnv(driver: SandboxDriverID): Record<string, string>;

package/dist/service-url-exposure.mjs

@@ -1,15 +1,3 @@
-// src/runtime-env.ts
-function workspaceRuntimeServiceExposureEnv(input) {
-  return {
-    ...input.driver === "docker" ? { WORKSPACE_RUNTIME_HOST: "0.0.0.0" } : {},
-    WORKSPACE_RUNTIME_SERVICE_EXPOSURE_SOURCE: input.source,
-    WORKSPACE_RUNTIME_SERVICE_EXPOSURE_ACCESS: input.access,
-    WORKSPACE_RUNTIME_SERVICE_EXPOSURE_DRIVER: input.driver,
-    ...input.fallbackAccess ? { WORKSPACE_RUNTIME_SERVICE_EXPOSURE_FALLBACK_ACCESS: input.fallbackAccess } : {},
-    ...input.note ? { WORKSPACE_RUNTIME_SERVICE_EXPOSURE_NOTE: input.note } : {}
-  };
-}
-
 // src/service-url-exposure.ts
 function sandboxServiceUrlExposure(driver) {
   if (driver === "docker") {
@@ -35,10 +23,6 @@ function sandboxServiceUrlExposure(driver) {
     driver
   };
 }
-function sandboxServiceUrlExposureEnv(driver) {
-  return workspaceRuntimeServiceExposureEnv(sandboxServiceUrlExposure(driver));
-}
 export {
-  sandboxServiceUrlExposure,
-  sandboxServiceUrlExposureEnv
+  sandboxServiceUrlExposure
 };