@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

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

@@ -0,0 +1,122 @@
+// The security crux. `buildSpawnSpec` *constructs* the `ode.createContainer`
+// body from the tiny allowlist of caller params (`image`, `argv`, `env`,
+// the resolved context path). The caller supplies no `HostConfig` — the
+// broker imposes the entire hardened envelope here.
+//
+// This is to `spawn.sock` what `checkAppGrants` + `HARDENING` + the SDK
+// authoring surface are to the compose path: every security-relevant
+// field is forced, and everything in the `docker.sock` deny-list
+// (privileged, host namespaces, arbitrary mounts/networks, the socket
+// itself) is simply not expressible — it is never read from the caller.
+
+import { KINDS, LABELS } from "@local/docker";
+import { HARDENING } from "../compose/default-hardening.ts";
+import { UNTRUSTED_NET } from "../../../worker-protocol/networks.ts";
+import type { SpawnRequest } from "./protocol.ts";
+
+/** Where the validated build context is bind-mounted, read-only, in the box. */
+export const CONTEXT_MOUNT = "/workspace";
+
+/**
+ * Where the broker's per-box output dir is bind-mounted, read-write, in the
+ * box. Mounted ONLY when `output` is requested; the box writes its build
+ * artifacts (e.g. a kaniko `--tar-path` image) here and the caller reads them
+ * back off the per-app artifacts dir. The dir is broker-owned and
+ * broker-created (the caller never names it), so this RW bind is as
+ * trusted as the RO context bind. The broker itself never reads anything
+ * out of this dir — it only reports the dir's basename via `outputKey`.
+ */
+export const OUTPUT_MOUNT = "/output";
+
+export interface SpawnLimits {
+  /** Hard memory ceiling, bytes. */
+  memoryBytes: number;
+  /** CPU quota in nano-CPUs (1e9 = one home). */
+  nanoCpus: number;
+}
+
+export function buildSpawnSpec(
+  req: SpawnRequest,
+  opts: {
+    scratchHostPath: string;
+    outputHostPath?: string;
+    limits: SpawnLimits;
+    spawnedBy: string;
+  },
+): Record<string, unknown> {
+  const env = req.env ? Object.entries(req.env).map(([k, v]) => `${k}=${v}`) : undefined;
+  return {
+    Image: req.image,
+    ...(req.argv ? { Cmd: req.argv } : {}),
+    ...(env ? { Env: env } : {}),
+    Labels: {
+      // realm.kind=spawn-box drives the reconcile / teardown / GC loops (boot
+      // gcStaleBoxes reaps orphans by it); it's broker-owned, not a wire
+      // service. realm.spawned-by records which granted app drove this build,
+      // as provenance for `docker ps` and forensics.
+      //
+      // Deliberately NOT realm.managed: the logs server tails every managed
+      // container, and a build's (attacker-controlled) stdout must not land in
+      // the logger — the build app (e.g. Forge) collects it over the spawn
+      // socket relay. spawned-by is its OWN key, distinct from realm.app
+      // (which would re-trigger logger attribution), so it's pure metadata:
+      // nothing taps or buckets by it.
+      [LABELS.KIND]: KINDS.SPAWN_BOX,
+      [LABELS.SPAWNED_BY]: opts.spawnedBy,
+    },
+    HostConfig: {
+      // Full HARDENING, plus the file-extraction caps a builder needs. A
+      // builder unpacks arbitrary base rootfs as uid 0, and real bases ship
+      // files owned by other uids (node:22-alpine's /home/node): chmod/utimes
+      // on a non-owned file needs FOWNER, writing through restrictive mode
+      // bits needs DAC_OVERRIDE, security.capability xattrs (setcap'd
+      // binaries in the tar) need SETFCAP, and FSETID keeps setgid bits
+      // intact — without it, chmod of a foreign-group file (Debian's 2775
+      // root:staff /usr/local, sgid crontab/wall) silently strips the bit
+      // and the built image drifts from its base. All four act only on file
+      // metadata inside the box; the escape-relevant fences — default
+      // seccomp (blocks unshare(CLONE_NEWUSER)) and no-new-privileges —
+      // stay exactly as HARDENING sets them.
+      CapDrop: [...HARDENING.cap_drop],
+      // DAC_OVERRIDE arrives via HARDENING.cap_add; listing it here too would
+      // just duplicate the entry.
+      CapAdd: [...HARDENING.cap_add, "FOWNER", "SETFCAP", "FSETID"],
+      SecurityOpt: [...HARDENING.security_opt],
+      PidsLimit: HARDENING.pids_limit,
+      Ulimits: [
+        { Name: "nofile", Soft: HARDENING.ulimits.nofile, Hard: HARDENING.ulimits.nofile },
+        { Name: "nproc", Soft: HARDENING.ulimits.nproc, Hard: HARDENING.ulimits.nproc },
+      ],
+      LogConfig: {
+        Type: HARDENING.logging.driver,
+        Config: { ...HARDENING.logging.options },
+      },
+      // One-shot: a failed build must NOT loop. The single documented
+      // deviation from HARDENING.restart (on-failure) — lifecycle, not
+      // security; the broker tears the box down on exit.
+      RestartPolicy: { Name: "no" },
+      // Resource caps beyond HARDENING — bound a single box.
+      Memory: opts.limits.memoryBytes,
+      NanoCpus: opts.limits.nanoCpus,
+      // Every bind is broker-constructed. The context dir is read-only —
+      // RO is load-bearing, the scratch root is shared host fs, so RW
+      // would let a build tamper with the caller's clone or plant data
+      // another build reads. The ONLY RW bind is the broker's own per-box
+      // output dir, and only when `output` is requested: the box writes its
+      // build artifacts there for the caller to read back off the per-app
+      // artifacts dir. The caller never names that dir (same trust property as
+      // the context dir).
+      Binds: [
+        `${opts.scratchHostPath}:${CONTEXT_MOUNT}:ro`,
+        ...(opts.outputHostPath ? [`${opts.outputHostPath}:${OUTPUT_MOUNT}:rw`] : []),
+      ],
+    },
+    // Attach at create time to untrusted-net ONLY — never the default
+    // bridge. Docker's DOCKER-ISOLATION-STAGE-2 DROPs FORWARD between
+    // user bridges, so the box physically cannot route to management-net
+    // or a peer realm_<app>. Segmentation by topology, not by caps.
+    NetworkingConfig: {
+      EndpointsConfig: { [UNTRUSTED_NET]: {} },
+    },
+  };
+}

package/src/runtime/docker/stats-server/disks.ts

@@ -0,0 +1,161 @@
+// One entry per real filesystem mounted on the host.
+//
+// The worker sees the host's root at /host (a read-only recursive bind — see
+// install-script.ts). So the mount table it reads through its own
+// /proc/self/mounts lists every host filesystem twice over: once at its real
+// path, once under /host. The /host copies are the ones we can actually
+// statfs, and stripping the prefix back off is what makes `path` read as the
+// operator's real path rather than a container detail.
+
+// `statfsSync` is a deliberate exception to the Deno-native rule in CLAUDE.md:
+// there is no Deno equivalent (`Deno.statfs` does not exist), so the node
+// compat path is the only way to read a filesystem's size. Needs
+// --allow-sys=statfs plus --allow-read on the path.
+import { statfsSync } from "node:fs";
+import type { DiskSample } from "../../stats-sample.ts";
+
+const HOST_ROOT = "/host";
+
+/**
+ * Our own mount table, reached through the host bind rather than at
+ * `/proc/self/mounts` directly. Deno refuses ANY path under `/proc` unless the
+ * process holds blanket `--allow-read` — `--allow-read=/proc` is not enough
+ * (`/proc/self/mem` would hand over process memory, so the whole tree is
+ * all-or-nothing). Reading the identical file via `/host/proc/...` is covered
+ * by the scoped `--allow-read=/host` the worker already needs for statfs, so
+ * the stats broker costs no permission widening.
+ *
+ * Same bytes either way: the host's procfs resolves `self` by the reading
+ * task's host-side pid, and `mounts` is a property of that task's mount
+ * namespace — ours.
+ */
+const MOUNTS = `${HOST_ROOT}/proc/self/mounts`;
+
+/**
+ * Filesystems the kernel synthesizes rather than stores bytes on. Reporting a
+ * `total`/`available` for these is meaningless — tmpfs reports RAM, cgroup and
+ * proc report zero — so they're dropped by fstype rather than by path. The
+ * host's /proc, /sys and /dev all come along with the recursive bind, so
+ * without this the "disks" list would be mostly kernel interfaces.
+ */
+const PSEUDO_FSTYPES = new Set([
+  "autofs",
+  "binfmt_misc",
+  "bpf",
+  "configfs",
+  "debugfs",
+  "devpts",
+  "devtmpfs",
+  "efivarfs",
+  "fusectl",
+  "hugetlbfs",
+  "mqueue",
+  "nsfs",
+  "overlay",
+  "proc",
+  "pstore",
+  "ramfs",
+  "rpc_pipefs",
+  "securityfs",
+  "selinuxfs",
+  "squashfs",
+  "sysfs",
+  "tmpfs",
+  "tracefs",
+]);
+
+const isPseudo = (fstype: string): boolean =>
+  PSEUDO_FSTYPES.has(fstype) || fstype.startsWith("cgroup") || fstype.startsWith("fuse.lxcfs");
+
+/**
+ * Mounts under `/run` are volatile runtime state, never a data disk (FHS), so
+ * the subtree is dropped by path — the one spot the fstype rule can't cover.
+ * Most `/run` submounts are already pseudo (tmpfs, nsfs), but a VM host exposes
+ * binary-emulation shares here that aren't: OrbStack / Docker Desktop's Rosetta
+ * mount (`/run/rosetta.orig`) has a non-pseudo fstype and its own anonymous
+ * st_dev, so neither the type filter nor the st_dev dedupe folds it, and statfs
+ * on it reports the whole VM host filesystem — a phantom multi-TiB "drive".
+ */
+const isUnderRun = (path: string): boolean => path.startsWith(`${HOST_ROOT}/run/`);
+
+/**
+ * `overlay` is in the pseudo list because every running container's rootfs is
+ * an overlay mount with its own anonymous st_dev — the dedupe below can't
+ * collapse them, so without the drop a busy host reports one phantom disk per
+ * container. But the host's own root is a real filesystem whatever its fstype,
+ * and on overlay-root systems (the Docker Desktop / OrbStack VM, appliance
+ * images) that root IS an overlay. Judge the root by position, not fstype: a
+ * container rootfs is never mounted at HOST_ROOT exactly.
+ */
+const isHostRoot = (path: string): boolean => path === HOST_ROOT;
+
+export async function readDisks(): Promise<DiskSample[]> {
+  let raw: string;
+  try {
+    raw = await Deno.readTextFile(MOUNTS);
+  } catch {
+    // No procfs under /host: a macOS dev host, or the host bind isn't wired.
+    // Report no disks rather than failing the whole sample.
+    return [];
+  }
+
+  const disks: DiskSample[] = [];
+  // Dedupe by filesystem identity, not by path. statfs returns no fsid, so
+  // st_dev is the only key available. This is what collapses docker's own
+  // /etc/resolv.conf, /etc/hostname and /etc/hosts file-binds: each is a
+  // separate mount entry whose statfs reports its *containing* filesystem, so
+  // without this they'd each surface as a phantom disk the size of the root
+  // volume. Bind-mounted subtrees of one disk collapse the same way.
+  const seen = new Set<number>();
+
+  for (const line of raw.split("\n")) {
+    const mount = parseMountLine(line);
+    if (!mount) continue;
+    if (!isHostRoot(mount.path) && !mount.path.startsWith(HOST_ROOT + "/")) continue;
+    if (isPseudo(mount.fstype) && !isHostRoot(mount.path)) continue;
+    if (isUnderRun(mount.path)) continue;
+
+    try {
+      const dev = Deno.statSync(mount.path).dev;
+      if (seen.has(dev)) continue;
+      seen.add(dev);
+
+      const fs = statfsSync(mount.path);
+      const total = fs.blocks * fs.bsize;
+      // A zero-capacity filesystem carries no signal — drop it rather than
+      // render an empty "0 B / 0 B" bar (some VM shim mounts report this).
+      if (total <= 0) continue;
+      disks.push({
+        path: stripHostPrefix(mount.path),
+        total,
+        available: fs.bavail * fs.bsize,
+      });
+    } catch {
+      // Raced an unmount, or the mount point isn't readable. Skip it.
+    }
+  }
+
+  return disks;
+}
+
+interface Mount {
+  path: string;
+  fstype: string;
+}
+
+// /proc/self/mounts: `device mountpoint fstype options dump pass`, with
+// whitespace inside a field escaped octally.
+function parseMountLine(line: string): Mount | null {
+  const fields = line.split(" ");
+  if (fields.length < 3) return null;
+  const path = unescapeOctal(fields[1]!);
+  const fstype = fields[2]!;
+  if (!path || !fstype) return null;
+  return { path, fstype };
+}
+
+const unescapeOctal = (s: string): string =>
+  s.replace(/\\([0-7]{3})/g, (_, oct: string) => String.fromCharCode(parseInt(oct, 8)));
+
+const stripHostPrefix = (path: string): string =>
+  path === HOST_ROOT ? "/" : path.slice(HOST_ROOT.length);

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

@@ -0,0 +1,322 @@
+// Worker-side stats server. Binds a unix socket; consumers connect, send a
+// single line `{"sample":true}\n` (or just `\n`), receive one JSON
+// `StatsSample`, and the connection closes.
+//
+// Request/response, not a stream — the deliberate divergence from
+// logs-server. A log line is an event you can't predict, so the worker must
+// push. A stats sample doesn't exist until someone asks for it, so the worker
+// holds no timer, no history, and no cache: it reads the host on demand and
+// answers. Cadence is entirely the consumer's choice.
+//
+// Everything here reads; nothing mutates. The socket has no verb that changes
+// anything.
+
+import { dirname } from "@std/path";
+import { LABELS, ode } from "@local/docker";
+import { z } from "zod";
+import { REALM_STATS_SOCKET } from "../../../worker-protocol/stats-socket-path.ts";
+import {
+  type ContainerSample,
+  type DiskSample,
+  type HostSample,
+  OTHER_APP,
+  type StatsSample,
+} from "../../stats-sample.ts";
+import { readDisks } from "./disks.ts";
+
+export { REALM_STATS_SOCKET };
+export type { StatsSample };
+
+// Request line a consumer sends before the sample: {"sample":true}. The sample
+// is all-or-nothing, so the value is ignored; the field leaves room for a
+// scoped request.
+const sampleRequestSchema = z.object({ sample: z.boolean().optional() });
+
+// A well-behaved consumer sends its line immediately. This bounds one that
+// connects and then never does, so its read can't park the connection (and its
+// fd) open forever. Only host.stats-granted apps reach the socket, so this
+// guards against a buggy grantee, not an external attacker.
+const REQUEST_READ_TIMEOUT_MS = 5_000;
+
+interface StartOpts {
+  /** Defaults to {@link REALM_STATS_SOCKET}. Override for tests. */
+  socketPath?: string;
+}
+
+interface ServerHandle {
+  /** Stop the server: close the listener and remove the socket file. */
+  stop(): Promise<void>;
+}
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+export async function startStatsServer(opts: StartOpts = {}): Promise<ServerHandle> {
+  const socketPath = opts.socketPath ?? REALM_STATS_SOCKET;
+  // The socket lives alone in its own directory (apps mount the dir, not the
+  // socket file — a file bind-mount of a unix socket doesn't wire across
+  // containers on macOS Docker). Ensure the dir exists before binding.
+  await Deno.mkdir(dirname(socketPath), { recursive: true });
+  await Deno.remove(socketPath).catch(() => {});
+
+  const listener = Deno.listen({ transport: "unix", path: socketPath });
+
+  void acceptLoop(listener);
+
+  return {
+    async stop() {
+      try {
+        listener.close();
+      } catch {}
+      await Deno.remove(socketPath).catch(() => {});
+    },
+  };
+}
+
+async function acceptLoop(listener: Deno.Listener): Promise<void> {
+  try {
+    for await (const conn of listener) {
+      void serve(conn as Deno.UnixConn);
+    }
+  } catch {
+    // Listener was closed via stop().
+  }
+}
+
+async function serve(conn: Deno.UnixConn): Promise<void> {
+  try {
+    await readRequestLine(conn);
+    const sample = await collectSample();
+    await conn.write(encoder.encode(JSON.stringify(sample) + "\n"));
+  } catch (err) {
+    console.error("stats-server sample error:", err);
+  } finally {
+    try {
+      conn.close();
+    } catch {}
+  }
+}
+
+export async function collectSample(): Promise<StatsSample> {
+  // `all: true` and no label filter: every container on the host, running and
+  // exited. Anything without a `realm.app` label lands under OTHER_APP — which
+  // is foreign containers AND Realm's own infrastructure (the worker, and Home
+  // where it's a container), since the installer starts those out-of-band and
+  // only the reconciler labels what it creates.
+  const [info, containers] = await Promise.all([ode.info(), ode.listContainers({ all: true })]);
+
+  const samples = await Promise.all(
+    containers.map((c) =>
+      sampleContainer(c.Id ?? "", c.Labels ?? {}, c.State ?? "", pickName(c.Names ?? [])),
+    ),
+  );
+
+  return {
+    ts: new Date().toISOString(),
+    host: await collectHost(info.KernelVersion ?? ""),
+    docker: {
+      version: info.ServerVersion ?? "",
+      // Counted from the list rather than read off /info: one source, so the
+      // counts can't disagree with the `containers` array beside them.
+      containersRunning: containers.filter((c) => c.State === "running").length,
+      containersTotal: containers.length,
+    },
+    containers: samples.filter((s): s is ContainerSample => s !== null),
+  };
+}
+
+async function collectHost(kernelVersion: string): Promise<HostSample> {
+  const mem = Deno.systemMemoryInfo();
+  const load = Deno.loadavg();
+  return {
+    kernelVersion,
+    cores: navigator.hardwareConcurrency,
+    loadAvg: [load[0] ?? 0, load[1] ?? 0, load[2] ?? 0],
+    memoryTotal: mem.total,
+    memoryAvailable: mem.available,
+    swapTotal: mem.swapTotal,
+    swapUsed: mem.swapTotal - mem.swapFree,
+    uptime: Deno.osUptime(),
+    disks: await readDisks(),
+  };
+}
+
+// Docker reports names as a list with a leading slash ("/nginx"), because a
+// container can carry several via legacy links. The first is the one `docker
+// ps` shows, which is the one an operator would recognize.
+function pickName(names: string[]): string {
+  const first = names[0] ?? "";
+  return first.startsWith("/") ? first.slice(1) : first;
+}
+
+async function sampleContainer(
+  id: string,
+  labels: Record<string, string>,
+  state: string,
+  name: string,
+): Promise<ContainerSample | null> {
+  if (!id) return null;
+  try {
+    const inspect = await ode.inspectContainer(id);
+    const base = {
+      app: labels[LABELS.APP] || OTHER_APP,
+      service: labels[LABELS.SERVICE] ?? "",
+      name,
+      containerId: id,
+      state,
+      health: inspect.State?.Health?.Status ?? undefined,
+      startedAt: inspect.State?.StartedAt ?? "",
+      restartCount: inspect.RestartCount ?? 0,
+    };
+
+    // Docker answers /stats for an exited container with HTTP 200 and
+    // all-zero counters, which is indistinguishable from a counter reset on a
+    // live container. Gate on state so a consumer diffing counters can't read
+    // an exit as "traffic went to zero" — skip the call entirely and report
+    // the zeros explicitly.
+    if (state !== "running") {
+      return {
+        ...base,
+        cpuUsage: 0,
+        netRx: 0,
+        netTx: 0,
+        blockRead: 0,
+        blockWrite: 0,
+        memoryUsage: 0,
+        memoryLimit: 0,
+        pids: 0,
+      };
+    }
+
+    const stats = await ode.containerStats(id, { stream: false, oneShot: true });
+    return { ...base, ...readCounters(stats) };
+  } catch {
+    // Container was removed between the list and the inspect/stats call.
+    return null;
+  }
+}
+
+type Counters = Pick<
+  ContainerSample,
+  | "cpuUsage"
+  | "netRx"
+  | "netTx"
+  | "blockRead"
+  | "blockWrite"
+  | "memoryUsage"
+  | "memoryLimit"
+  | "pids"
+>;
+
+// Docker's counters are uint64, which the generated schema parses as bigint.
+// The wire is JSON, which has no bigint, so everything narrows to number here.
+// Lossless below 2^53: at 100% CPU a `cpuUsage` nanosecond counter needs ~104
+// days to reach that, and a container that runs that long without a restart
+// resets nothing — but neither would docker's own uint64 survive a diff across
+// a restart. Bytes counters are further away still.
+const num = (v: bigint | number | null | undefined): number => Number(v ?? 0);
+
+function readCounters(stats: ode.ContainerStats): Counters {
+  const networks = networksSchema.safeParse(stats.networks);
+  let netRx = 0;
+  let netTx = 0;
+  if (networks.success && networks.data) {
+    // Summed across interfaces: an app's container can sit on several networks
+    // (its own, management, an untrusted DMZ) and the consumer wants one
+    // number for the container.
+    for (const iface of Object.values(networks.data)) {
+      netRx += num(iface.rx_bytes);
+      netTx += num(iface.tx_bytes);
+    }
+  }
+
+  let blockRead = 0;
+  let blockWrite = 0;
+  for (const entry of stats.blkio_stats?.io_service_bytes_recursive ?? []) {
+    // `op` casing varies across docker versions and cgroup drivers ("Read" on
+    // cgroup v1, "read" on v2).
+    const op = entry?.op?.toLowerCase();
+    if (op === "read") blockRead += num(entry?.value);
+    if (op === "write") blockWrite += num(entry?.value);
+  }
+
+  // `usage` counts the page cache, so it reads far above what the process
+  // actually holds. Docker's own CLI subtracts inactive file cache before
+  // showing MEM USAGE; do the same so the number matches what an operator sees
+  // in `docker stats`.
+  //
+  // Order matters and mirrors Docker's algorithm exactly: prefer
+  // `total_inactive_file` (present on cgroup v1) and fall back to
+  // `inactive_file` (cgroup v2, which has no `total_` prefix). On a v1 host a
+  // container with child cgroups reports both keys with DIFFERENT values, so
+  // reading `inactive_file` first would subtract the wrong one and drift from
+  // `docker stats`.
+  const memStats = stats.memory_stats?.stats;
+  const inactiveFile = num(memStats?.total_inactive_file ?? memStats?.inactive_file);
+  const memoryUsage = Math.max(0, num(stats.memory_stats?.usage) - inactiveFile);
+
+  return {
+    cpuUsage: num(stats.cpu_stats?.cpu_usage?.total_usage),
+    netRx,
+    netTx,
+    blockRead,
+    blockWrite,
+    memoryUsage,
+    memoryLimit: num(stats.memory_stats?.limit),
+    pids: num(stats.pids_stats?.current),
+  };
+}
+
+// `networks` is typed `unknown` in the generated schema (docker keys it by
+// interface name, so there's no fixed shape to generate). Parse the two fields
+// we sum.
+const networksSchema = z
+  .record(
+    z.string(),
+    z.object({
+      rx_bytes: z.coerce.bigint().nullish(),
+      tx_bytes: z.coerce.bigint().nullish(),
+    }),
+  )
+  .nullish();
+
+async function readRequestLine(conn: Deno.UnixConn): Promise<void> {
+  // Closing the conn on deadline is what unblocks a parked read: `conn.read`
+  // rejects once the socket is gone, so the loop can't wait past the timeout.
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    try {
+      conn.close();
+    } catch {}
+  }, REQUEST_READ_TIMEOUT_MS);
+  try {
+    const buf = new Uint8Array(1);
+    const collected: number[] = [];
+    while (collected.length < 4096) {
+      const n = await conn.read(buf);
+      if (n === null) break;
+      if (n === 0) continue;
+      if (buf[0] === 0x0a) break;
+      collected.push(buf[0]!);
+    }
+    const raw = decoder.decode(new Uint8Array(collected)).trim();
+    if (!raw) return;
+    try {
+      sampleRequestSchema.parse(JSON.parse(raw));
+    } catch {
+      // The request carries nothing this server acts on; a malformed line
+      // still gets a sample rather than an error.
+    }
+  } catch (err) {
+    // A read rejecting because our own timer closed the conn is the timeout
+    // firing, not a real fault — surface it as one clear message rather than a
+    // bare BadResource. Any other read error propagates as-is.
+    if (timedOut) throw new Error("stats request read timed out");
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export type { DiskSample };

package/src/runtime/home-client/index.ts

@@ -0,0 +1,71 @@
+// Consumer-side helper for the worker's `home-proxy.sock` broker. A
+// granted app mounts the per-app socket DIRECTORY and calls `callHome` to make
+// an authenticated control-plane request over the socket inside it; the worker
+// relays it across the mesh to Home. App containers are NOT on the mesh, so
+// this is the only channel an app has to reach Home.
+//
+// `Deno` is referenced only inside the function body — never at module
+// load — so this stays QuickJS-safe and can be re-exported from the
+// top-level `@yourrealm/sdk` barrel without dragging Deno into eval.
+// Mirrors `spawn-client`/`logs-client` framing: connect, write one request
+// line, read one response line, return.
+
+import { REALM_HOME_PROXY_CONTAINER_PATH } from "../../worker-protocol/home-proxy-paths.ts";
+import {
+  homeProxyResponseSchema,
+  type HomeProxyMethod,
+  type HomeProxyResponse,
+} from "../docker/home-proxy-server/protocol.ts";
+
+export interface CallHomeOpts {
+  /** Defaults to {@link REALM_HOME_PROXY_CONTAINER_PATH}. Override for tests. */
+  socketPath?: string;
+}
+
+/**
+ * Make one control-plane call through the worker's proxy socket. `path` is
+ * a sub-path of Home's `/api-access` surface. Resolves
+ * with Home's `{ status, body }`; rejects if the broker closes without a
+ * response line.
+ */
+export async function callHome(
+  method: HomeProxyMethod,
+  path: string,
+  body?: unknown,
+  opts: CallHomeOpts = {},
+): Promise<HomeProxyResponse> {
+  const socketPath = opts.socketPath ?? REALM_HOME_PROXY_CONTAINER_PATH;
+  const conn = await Deno.connect({ transport: "unix", path: socketPath });
+  // `TextEncoder`/`TextDecoder` are constructed INSIDE the function, never
+  // at module load: this module is re-exported from the top-level barrel,
+  // which loads under QuickJS during realm.ts eval, and QuickJS provides
+  // neither global. Per-instance decoder also lets a multi-byte UTF-8
+  // sequence straddling two reads survive the boundary.
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder("utf-8");
+  try {
+    // Omit `body` from the line entirely when undefined, so a no-body call
+    // writes exactly `{"method":…,"path":…}`.
+    const line = JSON.stringify(body === undefined ? { method, path } : { method, path, body });
+    await conn.write(encoder.encode(line + "\n"));
+
+    const buf = new Uint8Array(8192);
+    let remainder = "";
+    while (true) {
+      const n = await conn.read(buf);
+      if (n === null) break;
+      remainder += decoder.decode(buf.slice(0, n), { stream: true });
+      const nl = remainder.indexOf("\n");
+      if (nl !== -1) {
+        const raw = remainder.slice(0, nl).trim();
+        const parsed = homeProxyResponseSchema.parse(JSON.parse(raw));
+        return { status: parsed.status, body: parsed.body };
+      }
+    }
+    throw new Error("home proxy closed without a response line");
+  } finally {
+    try {
+      conn.close();
+    } catch {}
+  }
+}