@schemavaults/sandbox-management-sdk 0.0.0-stage → 0.1.1

package/LICENSE

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

package/README.md

@@ -1,3 +1,296 @@
-# Temporary Holding Version
+# @schemavaults/sandbox-management-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A TypeScript SDK for running sandboxes on any backend through one API. You can create, set up, start, stop, resume, list and destroy sandboxes on Docker or [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox), and the sandbox state lives in your app's own database.
+
+- **One lifecycle everywhere.** `create` clones an optional git repo, runs `setup` once and launches `start` as the long-running main process. `stop` keeps the filesystem. Touching a stopped sandbox wakes it and runs `resume`.
+- **State in your database.** Records go through a `SandboxStore`. The SDK ships an in-memory store, a Kysely / [`@schemavaults/dbh`](https://github.com/schemavaults/dbh) Postgres store with a migration, and a Web Storage store (`localStorage` / `sessionStorage`) for browsers. Every status change is a compare-and-set, so many server processes can share sandboxes safely.
+- **Runtimes.** Runs on Node.js ≥ 24 and Bun, and the core, Vercel adapter and dbh store also run in serverless functions. The core and the Web Storage store also run in browsers.
+
+```
+bun add @schemavaults/sandbox-management-sdk
+# plus whichever backends you use (all optional peer dependencies):
+bun add dockerode              # Docker provider
+bun add @vercel/sandbox        # Vercel provider
+bun add @schemavaults/dbh      # Postgres store (or any Kysely instance)
+```
+
+| Entry point | Contents |
+| --- | --- |
+| `@schemavaults/sandbox-management-sdk` | `SandboxManager`, `InMemorySandboxStore`, types, errors, helpers for writing providers |
+| `…/docker` | `DockerSandboxProvider` |
+| `…/vercel` | `VercelSandboxProvider` |
+| `…/dbh` | `DbhSandboxStore`, `createSandboxesMigration`, `up` / `down` |
+| `…/dbh/migration` | `up` / `down` only, to re-export from a migrations directory |
+| `…/web-storage` | `WebStorageSandboxStore` (browser `localStorage` / `sessionStorage`) |
+| `…/testing` | `MockSandboxProvider`, `InMemorySandboxStore` |
+
+## Quick start
+
+```ts
+import { SandboxManager } from "@schemavaults/sandbox-management-sdk";
+import { DockerSandboxProvider } from "@schemavaults/sandbox-management-sdk/docker";
+import { VercelSandboxProvider } from "@schemavaults/sandbox-management-sdk/vercel";
+import { DbhSandboxStore } from "@schemavaults/sandbox-management-sdk/dbh";
+import createDbh from "@schemavaults/dbh";
+
+const dbh = await createDbh("postgres", { environment: "production" });
+
+const sandboxes = new SandboxManager({
+  providers: [
+    new DockerSandboxProvider({ defaultImage: "node:24-bookworm" }),
+    new VercelSandboxProvider(), // uses VERCEL_OIDC_TOKEN, or pass { credentials }
+  ],
+  defaultProvider: "vercel",
+  store: new DbhSandboxStore({ db: dbh }),
+});
+
+const sandbox = await sandboxes.create({
+  ownerId: user.id,
+  labels: { project: "acme" },
+  spec: {
+    git: { url: "https://github.com/acme/app.git", revision: "main", depth: 1 },
+    setup: ["npm ci", "npm run build"],
+    start: "npm run dev -- --port 3000",
+    resume: "npm run dev -- --port 3000", // defaults to `start`
+    ports: [3000],
+    env: { NODE_ENV: "development" },
+    timeoutMs: 30 * 60_000,
+    resources: { vcpus: 2 },
+  },
+  onStdout: (chunk) => process.stdout.write(chunk), // setup output
+});
+
+await sandboxes.getUrl(sandbox.id, 3000);           // https://….vercel.run
+await sandboxes.exec(sandbox.id, "npm test");        // { exitCode, stdout, stderr }
+await sandboxes.stop(sandbox.id);                    // filesystem is kept
+await sandboxes.exec(sandbox.id, "ls");              // auto-resumes first
+await sandboxes.list({ ownerId: user.id, labels: { project: "acme" } });
+await sandboxes.destroy(sandbox.id);
+```
+
+## Concepts
+
+### The spec
+
+The `SandboxSpec` is stored with the sandbox, so any process can later resume it by ID alone. Any of these fields can be left out:
+
+| Field | Meaning |
+| --- | --- |
+| `workdir` | Absolute directory commands run in. Default: `/workspace` (Docker), `/vercel/sandbox` (Vercel). |
+| `env` | Environment variables for every command. |
+| `git` | `{ url, revision?, depth?, auth? }`, cloned into `workdir` before setup. `revision` may be a branch, tag or commit SHA. `auth` is sent as a one-off HTTP header and never written to `.git/config`. The image needs `git`. |
+| `setup` | One command or a list of them, run once after creation. Stops at the first non-zero exit. |
+| `start` | The main process, launched detached after setup. |
+| `resume` | Launched detached as the new main process whenever a stopped sandbox is woken. Defaults to `start`. |
+| `ports` | Ports reachable through `getUrl`. |
+| `timeoutMs` | Maximum run time. Vercel enforces it itself. For Docker, call `stopExpired()` periodically. |
+| `resources` | `{ vcpus?, memoryMb? }`. Vercel only supports `vcpus` (2 GB of memory per vCPU). |
+| `network` | Outbound access: `"allow-all"` (default), `"deny-all"`, or an allowlist `{ allowDomains?, allowCidrs?, denyCidrs? }`. See [Network access](#network-access). |
+| `providerOptions` | Provider-specific settings: `{ docker: { image, user, network, pullPolicy, labels } }` or `{ vercel: { image \| runtime, region, networkPolicy, tags } }`. |
+
+A command is either a string, run with `sh -c`, or `{ cmd, args?, cwd?, env? }`, run as an exact argv with no shell. A relative `cwd` resolves against `workdir`.
+
+> `spec.env` and `git.auth` are stored in your store as-is. Treat the table as sensitive, or pass short-lived credentials.
+
+### Network access
+
+`spec.network` limits where a sandbox can connect, for example so that an agent can only reach the platforms it works with:
+
+```ts
+await sandboxes.create({
+  spec: {
+    git: { url: "https://github.com/acme/agent.git" },
+    setup: "npm ci",
+    start: "node agent.js",
+    network: {
+      allowDomains: ["github.com", "*.github.com", "registry.npmjs.org", "api.acme.dev"],
+      allowCidrs: ["203.0.113.10", "198.51.100.0/24"], // IP addresses or CIDR ranges
+      denyCidrs: ["169.254.169.254"],                  // always blocked, even for allowed domains
+    },
+  },
+});
+```
+
+- Everything not on the allowlist is blocked. `"deny-all"` blocks everything, and `"allow-all"` (the default) blocks nothing.
+- A host name is allowed if it is on `allowDomains` or resolves to an address in `allowCidrs`. A leading `*.` matches subdomains only, so list `example.com` as well as `*.example.com` if you need both. An IP address is allowed if it is in `allowCidrs`. `denyCidrs` wins over both.
+- The policy applies from creation, so `git` and `setup` run under it too. Allow your git host and package registries, or those steps fail.
+- A provider only gets sandboxes whose policy it can enforce. Otherwise `create` throws before anything is created or stored, so a policy is never silently ignored.
+
+| Provider | `"deny-all"` | Allowlist |
+| --- | --- | --- |
+| Vercel | Yes | Yes, as the native network policy |
+| Docker | Yes: `--network none`, or behind an egress proxy when the sandbox has `ports` | Yes, behind an egress proxy (HTTP and HTTPS only, see [Docker](#docker)) |
+
+### Lifecycle
+
+```
+create ─► provisioning ─► setting_up ─► starting ─► running ◄──► stopping ─► stopped
+                                                        ▲                       │
+                                                        └──────── resuming ◄────┘
+any ─► destroying ─► destroyed          failures ─► failed
+```
+
+- **Auto-resume.** `exec`, `getUrl`, `readFile`, `writeFiles`, `logs` and the other operations on a stopped sandbox first wake it and launch `resume`. This also covers a sandbox the provider stopped by itself (for example a Vercel timeout). Turn it off with `autoResume: false`, and call `resume(id)` yourself.
+- **Concurrency.** Status changes are compare-and-set on a version column. If several requests hit a stopped sandbox at once, exactly one resumes it and the others wait for it (up to `transitionTimeoutMs`, default 10 minutes).
+- **Failures.** A failing setup step (`SandboxCommandError`) or provider error marks the sandbox `failed` and keeps the provider sandbox so you can inspect it. Call `destroy` to remove it. `resume` also retries a failed sandbox (without re-running setup).
+- **Destroyed records are kept**, but `list` hides them unless you pass `includeDestroyed: true`.
+- **`reconcile(ids?)`** syncs records with what the providers report: sandboxes stopped behind the SDK's back become `stopped`, vanished ones become `failed`, and transitions abandoned by a crashed process are settled.
+
+### Main process and logs
+
+`start` and `resume` run detached. Their stdout and stderr are appended to `/tmp/sandbox-sdk/main.log` inside the sandbox, which survives restarts:
+
+```ts
+await sandboxes.getMainProcess(id); // { pid, running, exitCode }
+await sandboxes.readLogs(id);       // everything so far
+for await (const chunk of sandboxes.logs(id, { follow: true, signal })) {
+  process.stdout.write(chunk);
+}
+```
+
+Only the first log read auto-resumes a stopped sandbox. A `follow` stream ends when the sandbox stops or `signal` aborts.
+
+### Files
+
+```ts
+await sandboxes.writeFiles(id, [{ path: "prompt.md", content: "…" }, { path: "/usr/local/bin/x", content: bytes, mode: 0o755 }]);
+await sandboxes.readTextFile(id, "out/result.json"); // null if missing
+```
+
+## Providers
+
+### Docker
+
+```ts
+new DockerSandboxProvider({
+  docker: new Docker({ socketPath: "/var/run/docker.sock" }), // default: new Docker() (honors DOCKER_HOST)
+  defaultImage: "node:24-bookworm",
+  pullPolicy: "if-not-present",   // or "always" / "never"
+  portBindingHost: "127.0.0.1",   // where published ports bind
+  urlHost: "localhost",           // host used in getUrl() URLs
+  egressProxyImage: DOCKER_EGRESS_PROXY_IMAGE, // the default: enforces spec.network allowlists
+});
+```
+
+- Each sandbox is a long-lived container named `sandbox-<id>` and labeled `dev.schemavaults.sandbox.id=<id>`. It runs an idle PID 1 (the entrypoint is overridden; the image needs `/bin/sh`) with `--init`.
+- `stop` and `wake` map to `docker stop` and `docker start`, so the container filesystem persists. Published ports get random host ports again on every start, and `getUrl` looks them up.
+- Docker has no native timeout. Run `sandboxes.stopExpired()` from a cron job.
+- If a command passed to `exec` with `timeoutMs` or `signal` is abandoned, the process inside the container keeps running.
+- `spec.network: "deny-all"` without `ports` runs the container with `--network none`.
+
+#### Network allowlists
+
+A sandbox with a `spec.network` allowlist (or `"deny-all"` and `ports`) runs behind an egress proxy:
+
+```
+ sandbox-<id>  ──(internal network, no route out)──  sandbox-<id>-egress  ──►  allowed hosts
+                                                       ▲ published ports
+```
+
+- The sandbox container is attached only to an internal Docker network of its own (`sandbox-<id>-net`), so it has no route out and cannot resolve outside names.
+- Its only way out is the proxy container `sandbox-<id>-egress`, which joins that network and `providerOptions.docker.network` (default `"bridge"`). The proxy enforces the allowlist and forwards the sandbox's `ports`, which it publishes on the host in the sandbox's place. Both carry the label `dev.schemavaults.sandbox.egress-proxy=<id>`.
+- The sandbox gets `HTTP_PROXY`, `HTTPS_PROXY` (and lowercase), `NO_PROXY` and `NODE_USE_ENV_PROXY=1`, which curl, wget, git over HTTPS, npm, pip, Bun and Node.js honor. HTTPS is tunneled with `CONNECT`, so TLS stays end to end and needs no extra CA. Set any of these in `spec.env` to override them.
+- **Only HTTP and HTTPS get out.** Tools that ignore the proxy variables, git over SSH, other TCP protocols, UDP and DNS lookups all fail, because there is no route out.
+- The proxy only resolves names that could be allowed, so it cannot be used to leak data through DNS lookups. It refuses clients outside the sandbox's network and never connects to its own loopback.
+- HTTPS is checked by the host name in the `CONNECT` request, not inside the encrypted tunnel. A client could still reach another site served from the same address as an allowed host (domain fronting), where that host's CDN permits it.
+- `stop` and `wake` stop and start the proxy with the sandbox, and `destroy` removes the proxy and the network. `status` and `reconcile` report the sandbox as stopped if its proxy is not running, and the next access restarts it. `docker logs sandbox-<id>-egress` shows every allowed and refused connection.
+- The proxy image is `DOCKER_EGRESS_PROXY_IMAGE` (`ghcr.io/schemavaults/sandbox-egress-proxy:<sdk version>`), built from [`images/egress-proxy`](images/egress-proxy/Dockerfile) and published with each release. To use your own build, run `docker build -f images/egress-proxy/Dockerfile -t my-proxy .` and pass `egressProxyImage: "my-proxy"`. The provider waits for the image's `HEALTHCHECK` before starting the sandbox.
+- Each allowlisted sandbox uses one Docker network, stopped or running. Docker's default address pools hold about 30 networks; raise `default-address-pools` in `daemon.json` (for example `{ "base": "10.200.0.0/16", "size": 24 }`) to run more.
+
+### Vercel Sandbox
+
+```ts
+new VercelSandboxProvider({
+  credentials: { token, teamId, projectId }, // omit to use VERCEL_OIDC_TOKEN
+  defaultImage: "vercel/sandbox/universal",
+});
+```
+
+- Sandboxes are created `persistent` and named after the SDK ID. `stop` snapshots the filesystem and `wake` restores it.
+- `timeoutMs` becomes the native sandbox timeout, and `extendTimeout(id, ms)` extends it. The SDK detects when Vercel has stopped a sandbox and resumes it through its own `resume` flow, instead of letting `@vercel/sandbox` resume it silently without relaunching your main process.
+- `spec.network` becomes the sandbox's native network policy. For rules `spec.network` cannot express, such as injecting an API key header into requests to one domain, pass a `@vercel/sandbox` `NetworkPolicy` as `providerOptions.vercel.networkPolicy` instead (`toVercelNetworkPolicy(network)` gives you a starting point). The two cannot be combined.
+
+### Writing a provider
+
+Implement `SandboxProvider` (see `src/provider.ts`). For backends that can only "run a command", the exported `shellStartMainProcess`, `shellGetMainProcess` and `shellReadMainLog` implement the main-process and log bookkeeping on top of `exec`.
+
+If your backend can restrict network access, list what it enforces in `networkPolicies` (`"deny-all"`, `"allowlist"`) and apply `spec.network` in `create`. A provider without `networkPolicies` is only given sandboxes with unrestricted access. `networkPolicyKind` and `normalizeCidr` help with the mapping.
+
+## Stores
+
+### Postgres via `@schemavaults/dbh` / Kysely
+
+Add the migration to your dbh migrations directory:
+
+```ts
+// src/db/migrations/00012-create-sandboxes.ts
+export { up, down } from "@schemavaults/sandbox-management-sdk/dbh/migration";
+```
+
+For a different table name, use `createSandboxesMigration("my_sandboxes")` and `new DbhSandboxStore({ db, tableName: "my_sandboxes" })`. The store takes a dbh handler or any Kysely instance using the Postgres dialect. It never opens or closes connections itself, so the `postgres-neon-proxy` adapter works unchanged.
+
+### Browser storage (`localStorage` / `sessionStorage`)
+
+For an app with no database, such as a demo or a local-first tool, keep records in the browser. The core has no Node.js dependencies, so `SandboxManager` runs in the page too:
+
+```ts
+import { WebStorageSandboxStore } from "@schemavaults/sandbox-management-sdk/web-storage";
+
+const store = new WebStorageSandboxStore();                          // localStorage
+const perTab = new WebStorageSandboxStore({ storage: sessionStorage, prefix: "my-app:sandboxes:" });
+```
+
+Each record is one JSON entry under `prefix + id` (default prefix `sandbox-sdk:sandboxes:`), with dates as ISO strings, so you can inspect it in the browser's dev tools. `update` reads and writes synchronously, which makes it an atomic compare-and-set within one page. Browsers do not guarantee that across tabs sharing `localStorage`, so give tabs that write the same records their own `prefix` or `ownerId`, or use `sessionStorage`. The store also accepts any object with the Web Storage API (`length`, `key`, `getItem`, `setItem`, `removeItem`). Storage quotas are around 5 MB per origin.
+
+### Your own store
+
+Implement `SandboxStore` (`insert`, `get`, `list`, `update`, `delete`). `update` must be an atomic compare-and-set on `version`. Run the shared contract suite in `tests/contracts/store-contract.ts` against your store to check it.
+
+## Testing your app
+
+```ts
+import { MockSandboxProvider, InMemorySandboxStore } from "@schemavaults/sandbox-management-sdk/testing";
+
+const provider = new MockSandboxProvider({
+  execHandler: ({ command }) => (command.args.includes("npm test") ? { exitCode: 1, stderr: "1 failing" } : undefined),
+});
+const sandboxes = new SandboxManager({ providers: [provider], store: new InMemorySandboxStore() });
+
+// …exercise your code, then assert on what happened:
+provider.callsFor(id, "exec");
+provider.simulateExternalStop(id); // e.g. a provider-side timeout
+provider.appendMainLog(id, "server listening\n");
+```
+
+The mock executes nothing. It records every call, keeps files in memory, and simulates stop, wake and external stops. It accepts every `spec.network` policy; pass `networkPolicies` to simulate a provider that enforces fewer.
+
+## Development
+
+```bash
+bun install
+bun run lint && bun run typecheck && bun run build
+bun run test:unit                                  # no external services needed
+
+bun run test:e2e:fixture-image && bun run test:e2e:egress-proxy-image && bun run test:e2e:docker    # needs a Docker daemon
+bun run test:e2e:dbh                                         # needs Postgres (POSTGRES_* env vars)
+node ./tests/smoke/node-smoke.mjs                            # built package under Node (after build)
+```
+
+CI (`.github/workflows/ci.yml`) runs lint, typecheck, build, the unit tests and a Node 24 smoke test. It also builds the egress proxy image and runs the Docker e2e suite against the runner's Docker daemon, including allowlists enforced end to end, and the store suite against a Postgres service container. The Vercel adapter is tested against a fake `@vercel/sandbox` client, with no live API calls.
+
+### Website
+
+The landing page in `website/` is a static Next.js export built with [`@schemavaults/ui`](https://github.com/schemavaults/ui), with its own `package.json` and lockfile. Its hero runs an agent demo on the SDK's own build, so build the SDK first:
+
+```bash
+bun install && bun run build                       # the SDK, into dist/
+cd website && bun install
+bun run dev                                        # http://localhost:3000
+bun run build                                      # static export in website/out
+```
+
+`.github/workflows/pages.yml` builds it on pull requests that touch it and deploys it to GitHub Pages on every push to `main` (set **Settings → Pages → Source** to **GitHub Actions** once). Its code samples live in `website/src/content/snippets.ts`; keep them in step with this README. See [`website/README.md`](website/README.md) for details.
+
+### Releasing
+
+Bump `version` in `package.json` and the tag in `DOCKER_EGRESS_PROXY_IMAGE` (`src/docker/egress.ts`; a unit test checks they match), then merge to `main`. On every push to `main`, `.github/workflows/publish.yml` checks whether that version is on npm, and stops there if it is. If it isn't, it pushes the egress proxy image to `ghcr.io/<owner>/sandbox-egress-proxy:<version>` for amd64 and arm64, publishes to npm with [trusted publishing](https://docs.npmjs.com/trusted-publishers) (OIDC, no token), then tags the commit `v<version>` and creates a GitHub release with generated notes. If a run fails partway, re-run its failed jobs; it skips an image that is already pushed and a GitHub release that already exists. The first time, make the GHCR package public (**Package settings → Change visibility**) so Docker hosts can pull it.

package/dist/commands.d.ts

@@ -0,0 +1,16 @@
+import type { CommandInput, GitSource, NormalizedCommand, SandboxSpec } from "./types.js";
+/** Resolve `path` against `workdir` unless it is already absolute. */
+export declare function resolveSandboxPath(workdir: string, path: string): string;
+export declare function normalizeCommand(input: CommandInput, workdir: string): NormalizedCommand;
+/** Quote a string for POSIX `sh`. */
+export declare function shellQuote(value: string): string;
+/** Render a normalized command as a single `sh` command line (cd + env + argv). */
+export declare function toShellCommandLine(command: NormalizedCommand): string;
+/** Throws a `SandboxError` describing the first problem found in `spec`. */
+export declare function validateSpec(spec: SandboxSpec): void;
+/**
+ * The command that clones `git` into `workdir`. Credentials travel as a
+ * one-off `http.extraHeader` via `GIT_CONFIG_*` env vars, so they are never
+ * written to `.git/config`.
+ */
+export declare function gitCloneCommand(git: GitSource, workdir: string): NormalizedCommand;

package/dist/commands.js

@@ -0,0 +1,99 @@
+import { SandboxError } from "./errors.js";
+import { encodeBase64 } from "./internal/base64.js";
+import * as posix from "./internal/posix-path.js";
+import { validateNetworkPolicy } from "./network.js";
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Resolve `path` against `workdir` unless it is already absolute. */
+export function resolveSandboxPath(workdir, path) {
+    return posix.isAbsolute(path) ? posix.normalize(path) : posix.join(workdir, path);
+}
+export function normalizeCommand(input, workdir) {
+    if (typeof input === "string") {
+        return { cmd: "sh", args: ["-c", input], cwd: workdir, env: {} };
+    }
+    return {
+        cmd: input.cmd,
+        args: input.args ?? [],
+        cwd: input.cwd ? resolveSandboxPath(workdir, input.cwd) : workdir,
+        env: input.env ?? {},
+    };
+}
+/** Quote a string for POSIX `sh`. */
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+/** Render a normalized command as a single `sh` command line (cd + env + argv). */
+export function toShellCommandLine(command) {
+    const env = Object.entries(command.env).map(([key, value]) => {
+        assertEnvName(key);
+        return `${key}=${shellQuote(value)}`;
+    });
+    const argv = [command.cmd, ...command.args].map(shellQuote);
+    const run = env.length > 0 ? ["env", ...env, ...argv] : argv;
+    return `cd ${shellQuote(command.cwd)} && ${run.join(" ")}`;
+}
+function assertEnvName(name) {
+    if (!ENV_NAME.test(name)) {
+        throw new SandboxError(`Invalid environment variable name "${name}"`);
+    }
+}
+/** Throws a `SandboxError` describing the first problem found in `spec`. */
+export function validateSpec(spec) {
+    for (const key of Object.keys(spec.env ?? {}))
+        assertEnvName(key);
+    for (const port of spec.ports ?? []) {
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            throw new SandboxError(`Invalid port ${port}`);
+        }
+    }
+    if (spec.timeoutMs !== undefined && !(spec.timeoutMs > 0)) {
+        throw new SandboxError(`timeoutMs must be a positive number`);
+    }
+    if (spec.workdir !== undefined && !posix.isAbsolute(spec.workdir)) {
+        throw new SandboxError(`workdir must be an absolute path`);
+    }
+    if (spec.git) {
+        if (!spec.git.url)
+            throw new SandboxError(`git.url is required`);
+        if (spec.git.depth !== undefined && !(Number.isInteger(spec.git.depth) && spec.git.depth > 0)) {
+            throw new SandboxError(`git.depth must be a positive integer`);
+        }
+    }
+    validateNetworkPolicy(spec.network);
+}
+const GIT_CLONE_SCRIPT = `set -e
+mkdir -p "$SANDBOX_GIT_DIR"
+cd "$SANDBOX_GIT_DIR"
+if [ -z "$SANDBOX_GIT_REVISION" ]; then
+  git clone $SANDBOX_GIT_DEPTH -- "$SANDBOX_GIT_URL" .
+elif git clone $SANDBOX_GIT_DEPTH --branch "$SANDBOX_GIT_REVISION" -- "$SANDBOX_GIT_URL" . 2>/dev/null; then
+  :
+else
+  # Not a branch or tag: fetch the revision (e.g. a commit SHA) directly.
+  rm -rf .git
+  git init -q
+  git remote add origin "$SANDBOX_GIT_URL"
+  git fetch -q $SANDBOX_GIT_DEPTH origin "$SANDBOX_GIT_REVISION"
+  git checkout -q FETCH_HEAD
+fi`;
+/**
+ * The command that clones `git` into `workdir`. Credentials travel as a
+ * one-off `http.extraHeader` via `GIT_CONFIG_*` env vars, so they are never
+ * written to `.git/config`.
+ */
+export function gitCloneCommand(git, workdir) {
+    const env = {
+        GIT_TERMINAL_PROMPT: "0",
+        SANDBOX_GIT_DIR: workdir,
+        SANDBOX_GIT_URL: git.url,
+        SANDBOX_GIT_REVISION: git.revision ?? "",
+        SANDBOX_GIT_DEPTH: git.depth ? `--depth=${git.depth}` : "",
+    };
+    if (git.auth) {
+        const basic = encodeBase64(new TextEncoder().encode(`${git.auth.username}:${git.auth.password}`));
+        env.GIT_CONFIG_COUNT = "1";
+        env.GIT_CONFIG_KEY_0 = "http.extraHeader";
+        env.GIT_CONFIG_VALUE_0 = `Authorization: Basic ${basic}`;
+    }
+    return { cmd: "sh", args: ["-c", GIT_CLONE_SCRIPT], cwd: "/", env };
+}

package/dist/dbh/index.d.ts

@@ -0,0 +1,4 @@
+export { DbhSandboxStore } from "./store.js";
+export type { DbhSandboxStoreOptions, SandboxRow } from "./store.js";
+export { DEFAULT_SANDBOXES_TABLE, createSandboxesMigration, down, up } from "./migration.js";
+export type { SandboxesMigration } from "./migration.js";

package/dist/dbh/index.js

@@ -0,0 +1,2 @@
+export { DbhSandboxStore } from "./store.js";
+export { DEFAULT_SANDBOXES_TABLE, createSandboxesMigration, down, up } from "./migration.js";

package/dist/dbh/migration.d.ts

@@ -0,0 +1,18 @@
+import type { Kysely } from "kysely";
+export declare const DEFAULT_SANDBOXES_TABLE = "sandboxes";
+export interface SandboxesMigration {
+    up(db: Kysely<any>): Promise<void>;
+    down(db: Kysely<any>): Promise<void>;
+}
+/** Kysely migration creating the sandboxes table (Postgres) under `tableName`. */
+export declare function createSandboxesMigration(tableName?: string): SandboxesMigration;
+/**
+ * Re-export from a file in your dbh migrations directory:
+ *
+ * ```ts
+ * // src/db/migrations/00012-create-sandboxes.ts
+ * export { up, down } from "@schemavaults/sandbox-management-sdk/dbh/migration";
+ * ```
+ */
+export declare const up: (db: Kysely<any>) => Promise<void>;
+export declare const down: (db: Kysely<any>) => Promise<void>;

package/dist/dbh/migration.js

@@ -0,0 +1,41 @@
+export const DEFAULT_SANDBOXES_TABLE = "sandboxes";
+/** Kysely migration creating the sandboxes table (Postgres) under `tableName`. */
+export function createSandboxesMigration(tableName = DEFAULT_SANDBOXES_TABLE) {
+    return {
+        async up(db) {
+            await db.schema
+                .createTable(tableName)
+                .addColumn("id", "text", (col) => col.primaryKey())
+                .addColumn("provider", "text", (col) => col.notNull())
+                .addColumn("provider_ref", "text")
+                .addColumn("status", "text", (col) => col.notNull())
+                .addColumn("spec", "jsonb", (col) => col.notNull())
+                .addColumn("owner_id", "text")
+                .addColumn("labels", "jsonb", (col) => col.notNull().defaultTo("{}"))
+                .addColumn("metadata", "jsonb", (col) => col.notNull().defaultTo("{}"))
+                .addColumn("error", "text")
+                .addColumn("version", "integer", (col) => col.notNull().defaultTo(0))
+                .addColumn("created_at", "timestamptz", (col) => col.notNull())
+                .addColumn("updated_at", "timestamptz", (col) => col.notNull())
+                .addColumn("expires_at", "timestamptz")
+                .execute();
+            await db.schema.createIndex(`${tableName}_owner_id_idx`).on(tableName).column("owner_id").execute();
+            await db.schema.createIndex(`${tableName}_status_idx`).on(tableName).column("status").execute();
+            await db.schema.createIndex(`${tableName}_labels_idx`).on(tableName).using("gin").column("labels").execute();
+        },
+        async down(db) {
+            await db.schema.dropTable(tableName).ifExists().execute();
+        },
+    };
+}
+const migration = createSandboxesMigration();
+/**
+ * Re-export from a file in your dbh migrations directory:
+ *
+ * ```ts
+ * // src/db/migrations/00012-create-sandboxes.ts
+ * export { up, down } from "@schemavaults/sandbox-management-sdk/dbh/migration";
+ * ```
+ */
+export const up = migration.up;
+export const down = migration.down;

package/dist/dbh/store.d.ts

@@ -0,0 +1,42 @@
+import type { Kysely } from "kysely";
+import type { SandboxListFilter, SandboxRecordPatch, SandboxStore } from "../store.js";
+import type { SandboxRecord } from "../types.js";
+/** Row shape of the sandboxes table. */
+export interface SandboxRow {
+    id: string;
+    provider: string;
+    provider_ref: string | null;
+    status: string;
+    spec: unknown;
+    owner_id: string | null;
+    labels: unknown;
+    metadata: unknown;
+    error: string | null;
+    version: number;
+    created_at: Date | string;
+    updated_at: Date | string;
+    expires_at: Date | string | null;
+}
+export interface DbhSandboxStoreOptions {
+    /**
+     * Your app's Kysely instance (Postgres dialect), or a `@schemavaults/dbh`
+     * handler (anything with a `db` Kysely property). The store never opens or
+     * closes connections itself.
+     */
+    db: Kysely<any> | {
+        db: Kysely<any>;
+    };
+    /** Default `"sandboxes"`; must match the table name given to the migration. */
+    tableName?: string;
+}
+/** `SandboxStore` backed by a Postgres table, via Kysely / `@schemavaults/dbh`. */
+export declare class DbhSandboxStore implements SandboxStore {
+    private readonly db;
+    private readonly table;
+    constructor(options: DbhSandboxStoreOptions);
+    insert(record: SandboxRecord): Promise<void>;
+    get(id: string): Promise<SandboxRecord | null>;
+    list(filter?: SandboxListFilter): Promise<SandboxRecord[]>;
+    update(id: string, expectedVersion: number, patch: SandboxRecordPatch): Promise<SandboxRecord | null>;
+    delete(id: string): Promise<boolean>;
+}

package/dist/dbh/store.js

@@ -0,0 +1,105 @@
+import { DEFAULT_SANDBOXES_TABLE } from "./migration.js";
+/** `SandboxStore` backed by a Postgres table, via Kysely / `@schemavaults/dbh`. */
+export class DbhSandboxStore {
+    db;
+    table;
+    constructor(options) {
+        const db = "selectFrom" in options.db ? options.db : options.db.db;
+        this.db = db;
+        this.table = options.tableName ?? DEFAULT_SANDBOXES_TABLE;
+    }
+    async insert(record) {
+        await this.db
+            .insertInto(this.table)
+            .values({
+            id: record.id,
+            provider: record.provider,
+            provider_ref: record.providerRef,
+            status: record.status,
+            spec: JSON.stringify(record.spec),
+            owner_id: record.ownerId,
+            labels: JSON.stringify(record.labels),
+            metadata: JSON.stringify(record.metadata),
+            error: record.error,
+            version: record.version,
+            created_at: record.createdAt,
+            updated_at: record.updatedAt,
+            expires_at: record.expiresAt,
+        })
+            .execute();
+    }
+    async get(id) {
+        const row = await this.db.selectFrom(this.table).selectAll().where("id", "=", id).executeTakeFirst();
+        return row ? fromRow(row) : null;
+    }
+    async list(filter = {}) {
+        let query = this.db.selectFrom(this.table).selectAll();
+        if (filter.ownerId !== undefined)
+            query = query.where("owner_id", "=", filter.ownerId);
+        if (filter.provider !== undefined)
+            query = query.where("provider", "=", filter.provider);
+        if (filter.status !== undefined) {
+            const statuses = [].concat(filter.status);
+            if (statuses.length === 0)
+                return [];
+            query = query.where("status", "in", statuses);
+        }
+        else if (!filter.includeDestroyed) {
+            query = query.where("status", "!=", "destroyed");
+        }
+        if (filter.labels && Object.keys(filter.labels).length > 0) {
+            query = query.where("labels", "@>", JSON.stringify(filter.labels));
+        }
+        query = query.orderBy("created_at", "desc").orderBy("id", "desc");
+        if (filter.limit !== undefined)
+            query = query.limit(filter.limit);
+        if (filter.offset !== undefined)
+            query = query.offset(filter.offset);
+        const rows = await query.execute();
+        return rows.map(fromRow);
+    }
+    async update(id, expectedVersion, patch) {
+        const row = await this.db
+            .updateTable(this.table)
+            .set({
+            ...(patch.status !== undefined && { status: patch.status }),
+            ...(patch.providerRef !== undefined && { provider_ref: patch.providerRef }),
+            ...(patch.error !== undefined && { error: patch.error }),
+            ...(patch.expiresAt !== undefined && { expires_at: patch.expiresAt }),
+            ...(patch.labels !== undefined && { labels: JSON.stringify(patch.labels) }),
+            ...(patch.metadata !== undefined && { metadata: JSON.stringify(patch.metadata) }),
+            version: expectedVersion + 1,
+            updated_at: new Date(),
+        })
+            .where("id", "=", id)
+            .where("version", "=", expectedVersion)
+            .returningAll()
+            .executeTakeFirst();
+        return row ? fromRow(row) : null;
+    }
+    async delete(id) {
+        const result = await this.db.deleteFrom(this.table).where("id", "=", id).executeTakeFirst();
+        return Number(result.numDeletedRows) > 0;
+    }
+}
+function fromRow(row) {
+    return {
+        id: row.id,
+        provider: row.provider,
+        providerRef: row.provider_ref,
+        status: row.status,
+        spec: parseJson(row.spec),
+        ownerId: row.owner_id,
+        labels: parseJson(row.labels),
+        metadata: parseJson(row.metadata),
+        error: row.error,
+        version: Number(row.version),
+        createdAt: new Date(row.created_at),
+        updatedAt: new Date(row.updated_at),
+        expiresAt: row.expires_at === null ? null : new Date(row.expires_at),
+    };
+}
+/** jsonb comes back parsed from `pg`, but as text from some drivers. */
+function parseJson(value) {
+    return typeof value === "string" ? JSON.parse(value) : value;
+}