@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/runtime/docker/spawn-server/context-key.ts

@@ -0,0 +1,82 @@
+// The broker's mount defense, split into the two halves the back-room seal
+// runs at two different times:
+//
+//   1. validateContextKeyShape(key) — string-only. Runs FIRST, before any fs
+//      touch, on the caller-supplied key. Rejects every traversal / absolute /
+//      blocklist shape so the only thing we ever `rename` is a clean single
+//      segment under the scratch root.
+//   2. assertSealedDir(dir, root) — real-filesystem. Runs AFTER the broker has
+//      renamed that segment into its per-box back room, on the MOVED inode.
+//      Rejects a symlink and confirms the real path stays inside the back room.
+//
+// The split is what makes the seal sound: a string check can't stop a symlink
+// planted in the shared scratch root (Docker follows symlinks in a bind source
+// at mount time, so `spawn/evil -> /var/run/docker.sock` would escape), and a
+// real-fs check done *before* the rename is a TOCTOU (the caller can swap the
+// validated dir for a symlink in the validate→mount window). Renaming the
+// segment into a dir the caller can't reach, then re-validating the moved
+// inode, closes that window — `rename(2)` never follows symlinks on either
+// path and is atomic w.r.t. concurrent fs ops.
+
+import { isValidHostDirectoryPath } from "../../../schema/host.ts";
+
+/**
+ * Shape-check a caller-supplied context key as text only — no filesystem
+ * access. `key` must be a single, clean path segment: non-empty, not `.` or
+ * `..`, no separators, no `..` substring. As defense in depth it must also
+ * clear the same dangerous-root blocklist operator-set Silo paths use
+ * (so a segment named `etc`, `proc`, … is refused even though joining it under
+ * the scratch root would be harmless). Those segment checks ARE the logical
+ * confinement: a key with no separator and no `..` cannot escape whatever root
+ * it's joined under. Throws on any violation; the broker turns the throw into a
+ * terminal error line. Runs before the rename, so a bad key never moves a file.
+ */
+export function validateContextKeyShape(key: string): void {
+  if (!key || key === "." || key === "..") {
+    throw new Error(`invalid context key: ${JSON.stringify(key)}`);
+  }
+  if (key.includes("/") || key.includes("\\")) {
+    throw new Error(`context key must be a single path segment: ${JSON.stringify(key)}`);
+  }
+  if (key.includes("..")) {
+    throw new Error(`context key must not contain "..": ${JSON.stringify(key)}`);
+  }
+  // Mirror the host-path blocklist: a key that maps onto a dangerous root
+  // (e.g. `etc` → `/etc`) is refused even though joining it under the scratch
+  // root would be harmless.
+  if (!isValidHostDirectoryPath(`/${key}`)) {
+    throw new Error(`context key resolves to a blocked root: ${JSON.stringify(key)}`);
+  }
+}
+
+/**
+ * Real-filesystem check on a directory the broker has just renamed into its
+ * per-box back room, confirming it's safe to hand to Docker as a bind source.
+ * `dir` must exist, must NOT be a symlink, and its canonical real path must
+ * stay inside the canonical `root` (the back-room box dir). Throws otherwise.
+ *
+ * This is the post-rename half of the seal. If the caller planted a symlink at
+ * `scratch/<key>`, the broker's `rename` moved the *symlink object* in, so the
+ * `lstat` here catches it. A swap racing the rename either landed before it
+ * (caught here) or after (on a path no longer in scratch — this inode is
+ * already sealed). Docker follows symlinks in a bind source at mount time, so
+ * an un-caught symlink (`-> /` or `-> /var/run/docker.sock`) would be a full
+ * host escape; rejecting it here, on a path the caller has no mount into, is
+ * what closes the window between validation and mount.
+ */
+export async function assertSealedDir(dir: string, root: string): Promise<void> {
+  const realRoot = await Deno.realPath(root);
+  let info: Deno.FileInfo;
+  try {
+    info = await Deno.lstat(dir);
+  } catch {
+    throw new Error(`sealed context not found: ${JSON.stringify(dir)}`);
+  }
+  if (info.isSymlink) {
+    throw new Error(`sealed context must not be a symlink: ${JSON.stringify(dir)}`);
+  }
+  const real = await Deno.realPath(dir);
+  if (real !== realRoot && !real.startsWith(`${realRoot}/`)) {
+    throw new Error(`sealed context escapes the box dir: ${JSON.stringify(dir)}`);
+  }
+}

package/src/runtime/docker/spawn-server/index.ts

@@ -0,0 +1,492 @@
+// Worker-side `spawn.sock` broker. Binds a unix socket; a granted app
+// connects, sends one request line, and gets back a JSON Lines stream of
+// its box's output plus one terminal line. One connection == one build.
+//
+// The broker is the one path that bypasses Home eval, so it re-imposes
+// every guarantee the compose path gets from Home: it CONSTRUCTS a fixed,
+// fully-hardened container spec (spec.ts) from a tiny allowlist of params
+// and never accepts a HostConfig, an absolute mount, or a network name
+// from the caller. `spawn.sock` is strictly less powerful than
+// `docker.sock`. Treat this as the highest-scrutiny code in the worker.
+
+import { dirname, join } from "@std/path";
+import { KINDS, LABELS, ode } from "@local/docker";
+import {
+  spawnArtifactsPath,
+  spawnPrivatePath,
+  spawnScratchPath,
+} from "../../../worker-protocol/spawn-paths.ts";
+import { UNTRUSTED_NET } from "../../../worker-protocol/networks.ts";
+import { dechunkedReader, streamDockerLogFrames } from "../log-frames.ts";
+import {
+  spawnRequestSchema,
+  type SpawnLogLine,
+  type SpawnRequest,
+  type SpawnTerminal,
+} from "./protocol.ts";
+import { assertSealedDir, validateContextKeyShape } from "./context-key.ts";
+import { buildSpawnSpec, type SpawnLimits } from "./spec.ts";
+
+/**
+ * The slice of the Docker layer the build path uses. Threaded through
+ * {@link BuildConfig} (defaulting to the real `ode`) so a unit test can drive
+ * `runBuild` with a mock and assert the seal's ordering without a live daemon —
+ * a TOCTOU race can't be reliably won against real Docker, so that coverage
+ * lives here, not in e2e.
+ */
+export type SpawnOde = Pick<
+  typeof ode,
+  | "inspectImage"
+  | "pullImage"
+  | "createContainer"
+  | "startContainer"
+  | "followContainerLogs"
+  | "waitContainer"
+  | "removeContainer"
+>;
+
+// Conservative per-box resource caps. Env-overridable so an operator can lift
+// them for a heavy build without a code change.
+const DEFAULT_MEMORY_BYTES = 2 * 1024 * 1024 * 1024; // 2 GiB
+const DEFAULT_NANO_CPUS = 2_000_000_000; // 2 cores
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000; // 30 min wall-clock per build
+// Caps the raw request line so a hostile caller can't exhaust memory
+// before the schema runs.
+const MAX_REQUEST_BYTES = 64 * 1024;
+// A caller must send its (small) request line within this window; bounds
+// a slow-loris that connects and stalls to pin a connection/fd. The
+// build wall-clock starts only after the request is parsed, so it does
+// not cover this phase.
+const REQUEST_READ_TIMEOUT_MS = 30 * 1000;
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+interface StartOpts {
+  /**
+   * App this broker fronts. Identity is the socket the request arrived on,
+   * never the wire — the broker derives this app's scratch dir from the
+   * appId, so a caller can't reach another app's tree. Mirrors
+   * `home-proxy-server`'s `opts.appId`.
+   */
+  appId: string;
+  /**
+   * Host path to bind this app's spawn socket at. The worker passes the
+   * per-app `spawn/sock/<appId>/spawn.sock` path (the socket sits alone in its
+   * own per-app dir; the server mkdirs the dir before binding).
+   */
+  socketPath: string;
+  /** Per-box resource caps. Defaults read from env, then constants. */
+  limits?: SpawnLimits;
+  /** Per-build wall-clock budget, ms. Defaults from env, then constant. */
+  timeoutMs?: number;
+  /** Override the scratch root. Defaults to `spawnScratchPath(appId)`. For tests. */
+  scratchRoot?: string;
+  /** Override the artifacts root. Defaults to `spawnArtifactsPath(appId)`. For tests. */
+  artifactsRoot?: string;
+  /**
+   * Override the broker-private back-room root. Defaults to
+   * `spawnPrivatePath(appId)`. For tests.
+   */
+  privateRoot?: string;
+  /**
+   * Test seam: fired once in the validate→mount window — after the seal renames
+   * the context into the back room, before the box is created. Lets a test
+   * attempt a swap in that window and confirm it hits a path the box never
+   * mounts. Undefined in production.
+   */
+  beforeMount?: () => Promise<void>;
+  /** Injectable Docker layer. Defaults to the real `ode`. For tests. */
+  ode?: SpawnOde;
+}
+
+interface ServerHandle {
+  /** Stop the server: close the listener, drop active conns, remove the socket file. */
+  stop(): Promise<void>;
+}
+
+interface BuildConfig {
+  /** The app this broker fronts — stamped on each box as `realm.spawned-by`. */
+  appId: string;
+  scratchRoot: string;
+  artifactsRoot: string;
+  /** Broker-private back room: per-box subdirs hold the sealed bind sources. */
+  privateRoot: string;
+  limits: SpawnLimits;
+  timeoutMs: number;
+  ode: SpawnOde;
+  beforeMount?: () => Promise<void>;
+}
+
+/**
+ * Bind one app's spawn broker socket. The global infra (the untrusted-net DMZ
+ * + orphaned-box GC) is set up once at boot by {@link bootSpawnInfra}, NOT
+ * here — this runs per granted app on every reconcile, so it must stay free of
+ * host-wide side effects. Mirrors `startHomeProxyServer`.
+ */
+export async function startSpawnServer(opts: StartOpts): Promise<ServerHandle> {
+  const { appId, socketPath } = opts;
+  const scratchRoot = opts.scratchRoot ?? spawnScratchPath(appId);
+  const artifactsRoot = opts.artifactsRoot ?? spawnArtifactsPath(appId);
+  const privateRoot = opts.privateRoot ?? spawnPrivatePath(appId);
+  const odeApi = opts.ode ?? ode;
+  const limits = opts.limits ?? {
+    memoryBytes: envInt("REALM_SPAWN_MEMORY_BYTES", DEFAULT_MEMORY_BYTES),
+    nanoCpus: envInt("REALM_SPAWN_NANO_CPUS", DEFAULT_NANO_CPUS),
+  };
+  const timeoutMs = opts.timeoutMs ?? envInt("REALM_SPAWN_TIMEOUT_MS", DEFAULT_TIMEOUT_MS);
+
+  // Per-app scratch (input) + artifacts (output) + private (the back room)
+  // dirs. Created if missing and otherwise left alone, contents included: the
+  // first two are bind-mount sources a running app holds by inode, so a rebind
+  // across a worker restart must find the same dirs. The worker's reconcile
+  // removes the whole `data/<appId>` subtree once the app is off the wire. All
+  // three are siblings under `data/<appId>/` so the seal's renames stay same-fs.
+  await Deno.mkdir(scratchRoot, { recursive: true }).catch(() => {});
+  await Deno.mkdir(artifactsRoot, { recursive: true }).catch(() => {});
+  await Deno.mkdir(privateRoot, { recursive: true }).catch(() => {});
+
+  // The socket lives alone in its own per-app dir under `spawn/sock/<appId>`
+  // (the app mounts the dir, not the socket file — a file bind-mount of a unix
+  // socket doesn't wire across containers on macOS Docker). Ensure it exists
+  // before binding.
+  await Deno.mkdir(dirname(socketPath), { recursive: true }).catch(() => {});
+  await Deno.remove(socketPath).catch(() => {});
+  const listener = Deno.listen({ transport: "unix", path: socketPath });
+  const conns = new Set<Deno.Conn>();
+
+  void acceptLoop(listener, conns, {
+    appId,
+    scratchRoot,
+    artifactsRoot,
+    privateRoot,
+    limits,
+    timeoutMs,
+    ode: odeApi,
+    beforeMount: opts.beforeMount,
+  });
+
+  return {
+    async stop() {
+      try {
+        listener.close();
+      } catch {}
+      for (const c of conns) {
+        try {
+          c.close();
+        } catch {}
+      }
+      conns.clear();
+      await Deno.remove(socketPath).catch(() => {});
+    },
+  };
+}
+
+/**
+ * Boot-once global spawn infra, independent of any app: ensure the shared
+ * untrusted-net DMZ exists, and force-remove every spawn box orphaned by a
+ * previous worker process (a restart mid-build leaves the box running, and
+ * every spawn-box-kind container is disposable). Split out of the per-app
+ * {@link startSpawnServer} so these host-wide steps run exactly once at boot,
+ * not once per granted app per reconcile. The per-app socket + tree (scratch +
+ * artifacts) is reclaimed worker-side by `reconcileSpawnSockets` once the app
+ * is off the wire.
+ */
+export async function bootSpawnInfra(): Promise<void> {
+  // Idempotent create (mirrors management-net) keeps the broker self-sufficient
+  // regardless of install ordering.
+  await ensureUntrustedNet();
+  await gcStaleBoxes();
+}
+
+async function acceptLoop(
+  listener: Deno.Listener,
+  conns: Set<Deno.Conn>,
+  cfg: BuildConfig,
+): Promise<void> {
+  try {
+    for await (const conn of listener) {
+      conns.add(conn);
+      handleConnection(conn as Deno.UnixConn, cfg).finally(() => {
+        conns.delete(conn);
+        try {
+          conn.close();
+        } catch {}
+      });
+    }
+  } catch {
+    // Listener was closed via stop().
+  }
+}
+
+// One connection == one build. Any caller or build failure is turned
+// into a terminal error line; nothing throws across the accept loop.
+async function handleConnection(conn: Deno.UnixConn, cfg: BuildConfig): Promise<void> {
+  const writer = conn.writable.getWriter();
+  let terminal: SpawnTerminal;
+  try {
+    // Bound the read so a stalled caller can't hold the conn open forever;
+    // on timeout the throw lands in the catch below and the finally closes
+    // the conn, which unblocks the pending read.
+    const req = await withTimeout(
+      readRequest(conn),
+      REQUEST_READ_TIMEOUT_MS,
+      "spawn request read timed out",
+    );
+    terminal = await runBuild(req, cfg, (line) => writeLine(writer, line));
+  } catch (err) {
+    terminal = { exit: -1, error: (err as Error).message ?? String(err) };
+  }
+  await writeLine(writer, terminal).catch(() => {});
+  try {
+    writer.releaseLock();
+  } catch {}
+  try {
+    conn.close();
+  } catch {}
+}
+
+// Read one `\n`-terminated request line, bounded, then hardened-parse +
+// Zod-validate. Mirrors the logs server's readSinceLine.
+async function readRequest(conn: Deno.UnixConn): Promise<SpawnRequest> {
+  const buf = new Uint8Array(1);
+  const collected: number[] = [];
+  while (collected.length < MAX_REQUEST_BYTES) {
+    const n = await conn.read(buf);
+    if (n === null) break;
+    if (n === 0) continue;
+    if (buf[0] === 0x0a) break;
+    collected.push(buf[0]!);
+  }
+  if (collected.length >= MAX_REQUEST_BYTES) throw new Error("spawn request too large");
+  const raw = decoder.decode(new Uint8Array(collected)).trim();
+  if (!raw) throw new Error("empty spawn request");
+  return spawnRequestSchema.parse(JSON.parse(raw));
+}
+
+export async function runBuild(
+  req: SpawnRequest,
+  cfg: BuildConfig,
+  onLog: (line: SpawnLogLine) => Promise<void>,
+): Promise<SpawnTerminal> {
+  // Shape-check the caller's key as text only, before the try — a bad key is a
+  // clean terminal error that created nothing on disk.
+  validateContextKeyShape(req.context);
+
+  // One id per box: names the container (`realm-spawn-${boxId}`), the
+  // broker-private box dir, and (with output) the artifacts subdir, so the
+  // three correlate. A FULL uuid, because these name directories where a
+  // collision would cross two builds.
+  const boxId = crypto.randomUUID();
+  const boxDir = join(cfg.privateRoot, boxId);
+  const ctx = join(boxDir, "ctx");
+  const out = req.output ? join(boxDir, "out") : undefined;
+  // Broker-minted basename the caller reads its output back under (success
+  // only); the box never names it. Build-only requests get none.
+  const outputKey = req.output ? `output-${boxId}` : undefined;
+
+  let id: string | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let timedOut = false;
+
+  try {
+    // From here the finally owns boxDir: it holds `ctx` always, and `out` until
+    // the success rename below moves it into the artifacts tree.
+    await Deno.mkdir(boxDir, { recursive: true });
+
+    // THE SEAL. Move the caller's staged context out of the shared,
+    // caller-writable scratch root into this broker-private box dir — a dir the
+    // calling app has no mount into — then re-validate the MOVED inode. rename(2)
+    // never follows symlinks on either path and is atomic w.r.t. concurrent fs
+    // ops: a symlink the caller planted at scratch/<key> moves as the symlink
+    // OBJECT (caught by assertSealedDir below); a swap racing the rename lands
+    // either before it (caught) or after (on a path no longer in scratch — this
+    // inode is already sealed). Nothing the caller can reach can swap `ctx`
+    // between here and the Docker mount, so there is no validate→mount TOCTOU.
+    try {
+      await Deno.rename(join(cfg.scratchRoot, req.context), ctx);
+    } catch (err) {
+      if (err instanceof Deno.errors.NotFound) {
+        throw new Error(`spawn context not found: ${JSON.stringify(req.context)}`);
+      }
+      // EXDEV: scratch and the back room are on different filesystems. NEVER
+      // fall back to a copy — a copy re-opens the very TOCTOU the rename closes.
+      // Fail loud so the operator co-locates the spawn data tree.
+      if (isCrossDevice(err)) {
+        throw new Error(
+          "spawn private root must be on the same filesystem as scratch — " +
+            "both live under spawn/data/<app>/; do not mount them separately",
+        );
+      }
+      throw err;
+    }
+    await assertSealedDir(ctx, boxDir);
+
+    // The box's writable output dir, also inside the back room (broker-owned,
+    // broker-named — the caller never names it). Created only for an `output`
+    // run; moved into artifacts on success below.
+    if (out) await Deno.mkdir(out);
+
+    // Test seam: fires in the validate→mount window the seal above closes.
+    await cfg.beforeMount?.();
+
+    const spec = buildSpawnSpec(req, {
+      scratchHostPath: ctx,
+      outputHostPath: out,
+      limits: cfg.limits,
+      spawnedBy: cfg.appId,
+    });
+
+    // Bound the pull on its own budget — the build wall-clock below can't cover
+    // it (no container to remove yet), so a tarpit registry behind a
+    // caller-chosen `image:` would otherwise hang here unbounded. A stall here
+    // widens no swap window: ctx/out are already sealed in the back room.
+    await withTimeout(ensureImage(cfg.ode, req.image), cfg.timeoutMs, "spawn image pull timed out");
+
+    const created = await cfg.ode.createContainer(`realm-spawn-${boxId}`, spec);
+    id = created.Id;
+
+    // Wall-clock cap on the whole run. On expiry we force-remove the box, which
+    // unblocks the log relay + wait below (their docker conns drop), so a
+    // hung/forking build can't pin a slot forever.
+    timer = setTimeout(() => {
+      timedOut = true;
+      cfg.ode.removeContainer(id!, { force: true }).catch(() => {});
+    }, cfg.timeoutMs);
+
+    await cfg.ode.startContainer(id);
+    await relayLogs(cfg.ode, id, onLog);
+    const result = await cfg.ode.waitContainer(id);
+    if (timedOut) return { exit: -1, error: "spawn build timed out" };
+    const exit = Number(result.StatusCode);
+
+    // Success: move the box's output OUT of the back room into the app's
+    // artifacts tree under the broker-minted key, then hand the key back. The
+    // box is already torn down (waitContainer resolved on its exit), so no live
+    // writer races this rename. On every failure path nothing reaches artifacts
+    // at all — the finally wipes the whole boxDir, `out` included.
+    if (out && outputKey) await Deno.rename(out, join(cfg.artifactsRoot, outputKey));
+    return { exit, outputKey, error: null };
+  } catch (err) {
+    if (timedOut) return { exit: -1, error: "spawn build timed out" };
+    throw err;
+  } finally {
+    clearTimeout(timer);
+    // Disposable teardown: remove the box (it holds the binds), THEN wipe the
+    // whole back room. boxDir always holds ctx; it holds out too unless the
+    // success rename already moved it into artifacts. Nothing the caller can
+    // reach is touched. The box leaves untrusted-net with it; the DMZ persists.
+    if (id) await cfg.ode.removeContainer(id, { force: true }).catch(() => {});
+    await Deno.remove(boxDir, { recursive: true }).catch(() => {});
+  }
+}
+
+// EXDEV detection. Deno doesn't expose a `CrossDevice` error class in this
+// version, so match the OS error a cross-device rename(2) surfaces ("Invalid
+// cross-device link" / raw os error 18) by message. Used to fail the seal loud
+// rather than silently copy (a copy would reintroduce the TOCTOU).
+function isCrossDevice(err: unknown): boolean {
+  return err instanceof Error && /cross-device|os error 18/i.test(err.message);
+}
+
+async function ensureImage(odeApi: SpawnOde, image: string): Promise<void> {
+  try {
+    await odeApi.inspectImage(image);
+    return; // already present
+  } catch {
+    // Not present — pull it.
+  }
+  await odeApi.pullImage(image);
+}
+
+// Follow the box's logs and relay each line back over the socket. Uses
+// timestamps:true to match the shared frame demux (which strips the
+// leading RFC3339); we keep only message + stream. Returns when the
+// stream ends — i.e. the container exited.
+async function relayLogs(
+  odeApi: SpawnOde,
+  id: string,
+  onLog: (line: SpawnLogLine) => Promise<void>,
+): Promise<void> {
+  let conn: Deno.Conn;
+  try {
+    ({ conn } = await odeApi.followContainerLogs(id, {
+      stdout: true,
+      stderr: true,
+      timestamps: true,
+    }));
+  } catch {
+    return; // can't follow — fall through to waitContainer
+  }
+  try {
+    for await (const frame of streamDockerLogFrames(dechunkedReader(conn))) {
+      await onLog({ log: frame.message, stream: frame.stream });
+    }
+  } catch {
+    // Stream ended or errored — proceed to wait for the exit code.
+  } finally {
+    try {
+      conn.close();
+    } catch {}
+  }
+}
+
+async function writeLine(
+  writer: WritableStreamDefaultWriter<Uint8Array>,
+  obj: SpawnLogLine | SpawnTerminal,
+): Promise<void> {
+  await writer.write(encoder.encode(JSON.stringify(obj) + "\n"));
+}
+
+// Idempotent create of the standing DMZ bridge. "already exists" is the
+// expected steady state.
+async function ensureUntrustedNet(): Promise<void> {
+  try {
+    await ode.createNetwork({ Name: UNTRUSTED_NET });
+  } catch (err) {
+    if (!(err instanceof Error && err.message.toLowerCase().includes("already exists"))) {
+      throw err;
+    }
+  }
+}
+
+async function gcStaleBoxes(): Promise<void> {
+  let boxes: Awaited<ReturnType<typeof ode.listContainers>>;
+  try {
+    boxes = await ode.listContainers({
+      all: true,
+      filters: { label: [`${LABELS.KIND}=${KINDS.SPAWN_BOX}`] },
+    });
+  } catch (err) {
+    console.warn(`spawn boot GC: list failed (${(err as Error).message})`);
+    return;
+  }
+  for (const c of boxes) {
+    if (!c.Id) continue;
+    await ode.removeContainer(c.Id, { force: true }).catch(() => {});
+  }
+}
+
+// Race `p` against a wall-clock budget. The loser keeps running in the
+// background (the ode calls hold their own conns); callers that need the
+// abandoned work torn down do so separately (e.g. force-removing the box).
+async function withTimeout<T>(p: Promise<T>, ms: number, message: string): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      p,
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(new Error(message)), ms);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function envInt(name: string, fallback: number): number {
+  const raw = Deno.env.get(name);
+  if (!raw) return fallback;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}

package/src/runtime/docker/spawn-server/protocol.ts

@@ -0,0 +1,70 @@
+// The `spawn.sock` wire contract. Newline-delimited JSON over a unix
+// conn, mirroring `logs.sock`: a single request line in, a stream of log
+// lines + one terminal line out.
+//
+// The request carries only the *payload* (image / argv / env) plus a
+// context key and an optional output flag. It carries NO envelope config
+// — the broker constructs the hardened spec itself (see spec.ts). The
+// broker's read buffer caps the raw bytes; these schemas cap the parsed
+// shape.
+
+import { z } from "zod";
+
+const MAX_IMAGE = 1024;
+const MAX_KEY = 255;
+const MAX_ARGV = 1024;
+const MAX_ARG = 16384;
+const MAX_ENV_KEYS = 512;
+
+/**
+ * One build request. `image`/`argv`/`env` are the payload to run inside
+ * the fixed envelope, never envelope config. `context` is a relative,
+ * single-segment key resolved under the worker scratch root (see
+ * context-key.ts). `output` asks the broker for a writable per-box output
+ * dir, bind-mounted RW at OUTPUT_MOUNT: a generic "give me a place to write
+ * artifacts and tell me where it is" flag. The broker stays
+ * image-agnostic — it never parses `argv`, so what the box writes to that
+ * dir (a kaniko `--tar-path` image, say) and what the caller does with it
+ * are entirely the caller's concern. The broker only hands back the dir's
+ * basename via `outputKey`; it never reads a box-authored file.
+ */
+export const spawnRequestSchema = z
+  .object({
+    image: z.string().min(1).max(MAX_IMAGE),
+    context: z.string().min(1).max(MAX_KEY),
+    argv: z.array(z.string().max(MAX_ARG)).max(MAX_ARGV).optional(),
+    env: z
+      .record(z.string().max(MAX_KEY), z.string().max(MAX_ARG))
+      .refine((e) => Object.keys(e).length <= MAX_ENV_KEYS, {
+        message: `too many env keys (max ${MAX_ENV_KEYS})`,
+      })
+      .optional(),
+    output: z.literal(true).optional(),
+  })
+  .strict();
+
+export type SpawnRequest = z.infer<typeof spawnRequestSchema>;
+
+/** One line of the box's output, relayed back over the socket. */
+export const spawnLogLineSchema = z.object({
+  log: z.string(),
+  stream: z.enum(["stdout", "stderr"]),
+});
+
+export type SpawnLogLine = z.infer<typeof spawnLogLineSchema>;
+
+/**
+ * The final line before the broker closes the conn (close == teardown
+ * complete). `outputKey` is the basename of the broker-owned output dir
+ * (`output-<boxId>`) when `output` was requested — the caller reads its
+ * artifacts back from `${artifactsRoot}/${outputKey}`. It is broker-authored
+ * (a basename the broker minted), never a path or value the box wrote.
+ * `error` is set on any failure.
+ */
+export const spawnTerminalSchema = z.object({
+  exit: z.number().int(),
+  outputKey: z.string().optional(),
+  error: z.string().nullable().optional(),
+});
+
+export type SpawnTerminal = z.infer<typeof spawnTerminalSchema>;