@yourrealm/sdk 0.0.0-alpha.1378.ce03c8dc

package/src/worker-protocol/app-dirs.ts

@@ -0,0 +1,94 @@
+// Wire constants for an app's *own* directories — where a relative `volumes`
+// hostPath lands, and the group that makes it writable.
+//
+// The Silo answer to "several apps share one tree" is a group per Silo
+// (silo-paths.ts). This is the smaller sibling question: one app, one
+// directory, and an image that doesn't run as root. Docker creates a missing
+// bind source as root-owned 0755, so a container running as a baked-in uid gets
+// EACCES on its own config directory and dies at boot, and the image can't fix
+// that from inside: it has no root phase to chown from.
+//
+// So the worker prepares the directory the same way it prepares a Silo's —
+// group ownership, setgid, group rwx — and the renderer puts the container in
+// that group. Nothing reaches the author: a relative volume is an app's private
+// storage with no permission and no operator decision, and it stays that way.
+//
+// Pure constants and string math, no runtime imports, so this stays QuickJS-safe
+// like its siblings.
+
+/**
+ * Group owning every directory Realm creates for an app's own relative volumes.
+ *
+ * One number for every app rather than one per app, because the isolation is
+ * already carried by the *path*: bind sources are scoped per app by
+ * `scopeBindSource`, an app only ever mounts its own, and the enclosing
+ * `apps/<id>/` tree is root-owned 0700 so nothing on the host box can walk in.
+ * A per-app gid would buy nothing over that and cost an allocator, a wire
+ * field, and a row to keep in sync.
+ *
+ * Sits directly below the Silo range (`home_state.next_gid` counts up from
+ * 1_000_000), so the two allocations can never meet.
+ */
+export const REALM_APP_DIR_GID = 999_999;
+
+/**
+ * Whether this volume mounts a directory Realm prepares for the app itself -
+ * the one question both halves of the mechanism must answer identically. The
+ * worker prepares exactly what this returns true for; the renderer grants
+ * membership for exactly the same set. Split into two implementations they
+ * drift, and each direction is its own bug: a prepared directory nothing
+ * mounts, or a mount whose container was never put in the group.
+ *
+ * Four things are *not* an app's own directory:
+ *
+ *   - a volume carrying a `gid` - that's a Silo's, prepared by prepareSiloDirs
+ *     against a path that may be the operator's own;
+ *   - an exempt path (`allowedAbsoluteHostPaths`) - a peer's directory reached
+ *     through a grant. It's relative and it looks just like private storage,
+ *     which is exactly why this check has to live in one place: preparing it
+ *     would build a hollow mirror of the peer's layout under the wrong app;
+ *   - an absolute path - a Silo's or the operator's;
+ *   - the app's own root (`./` and friends), which the worker keeps at 0700
+ *     for the compose file and secrets it writes there. Claiming it would be
+ *     undone later in the same reconcile.
+ */
+export function isPreparedAppDir(
+  appId: string,
+  volume: { readonly hostPath: string; readonly gid?: number | undefined },
+  exemptHostPaths: ReadonlySet<string>,
+): boolean {
+  if (volume.gid !== undefined) return false;
+  if (exemptHostPaths.has(volume.hostPath)) return false;
+  if (!volume.hostPath.startsWith("./")) return false;
+  return scopeBindSource(volume.hostPath, appId) !== `./apps/${appId}`;
+}
+
+/**
+ * Resolve a bind source against the app's own subtree.
+ *
+ * Relative paths (`./data`) are private storage and land under
+ * `apps/<appId>/`; absolute ones belong to a Silo or the operator and pass
+ * through untouched. Shared by the renderer (which writes the compose source)
+ * and the worker (which prepares the directory), because a preparation that
+ * lands on a different inode than the mount is worse than no preparation at
+ * all - it looks done and shares nothing.
+ *
+ * Home's input validator rejects `..` segments before the wire is built, but
+ * this re-checks: a buggy Home commit must not let a path escape the per-app
+ * subtree.
+ */
+export function scopeBindSource(source: string, appId: string): string {
+  if (!source.startsWith("./")) return source;
+  const scoped = `./apps/${appId}/${source.slice(2)}`;
+  const segments = scoped.split("/");
+  const resolved: string[] = [];
+  for (const seg of segments) {
+    if (seg === "..") resolved.pop();
+    else if (seg !== "." && seg !== "") resolved.push(seg);
+  }
+  const normalized = "./" + resolved.join("/");
+  if (!normalized.startsWith(`./apps/${appId}/`) && normalized !== `./apps/${appId}`) {
+    throw new Error(`bind source escapes app directory: ${source}`);
+  }
+  return normalized;
+}

package/src/worker-protocol/home-proxy-paths.ts

@@ -0,0 +1,76 @@
+// Wire constants for the worker's app→Home proxy brokers (per-app
+// `home-proxy/<appId>/home-proxy.sock`). An app container mounts its own
+// per-app DIRECTORY and calls `callHome` over the socket inside it; the worker
+// turns that into one `apiAccess` call on its uplink, which Home dispatches to
+// `/api-access/*`. An app container holds no uplink — only the worker does —
+// so this socket is the only path an app has to reach the control plane.
+//
+// One socket per granted app, not a single shared one: the worker attaches
+// `X-Realm-App-Id` based on *which* socket a request arrived on, so the app
+// never asserts — or can spoof — its own id. Each app's socket lives ALONE in
+// its own per-app directory: the app mounts the directory (a file bind-mount of
+// a unix socket doesn't wire across containers on macOS Docker), and because
+// the socket is alone in it, mounting the dir never exposes a sibling's socket.
+//
+// Pure constants + string-join builders, no runtime imports (the
+// `WorkerHostPath` import is type-only and erases), so the QuickJS-safe
+// `callHome` helper can pull the container path without dragging Deno deps.
+// Mirrors `spawn-paths.ts`.
+
+import type { WorkerHostPath } from "./logs-socket-path.ts";
+import type { WorkerMount } from "./worker-mount.ts";
+
+/**
+ * Host directory the worker keeps every app's per-app proxy socket dir under.
+ * Lives beneath `/opt/realm/worker/` — the one directory the worker container
+ * already shares with the host (mirrors `REALM_SPAWN_DIR`). The worker mkdirs
+ * this once; each per-app subdir under it lives as long as its app is on the
+ * wire, because a running container holds it by inode.
+ */
+export const REALM_HOME_PROXY_DIR = "/opt/realm/worker/home-proxy";
+
+/**
+ * Host directory holding one app's proxy socket
+ * (`/opt/realm/worker/home-proxy/<appId>`). The socket sits alone inside it, so
+ * this is the path the app bind-mounts. `home.apiAccess`'s resolver builds its
+ * `{ socket }` from this per-app dir at eval time, and `collectAllowed` exempts
+ * it from the absolute-mount gate.
+ */
+export function homeProxyAppDir(appId: string): WorkerHostPath {
+  return `${REALM_HOME_PROXY_DIR}/${appId}` as WorkerHostPath;
+}
+
+/**
+ * Host path of one app's proxy socket, inside {@link homeProxyAppDir}. The
+ * worker binds this in `reconcileHomeProxySockets` and carries it on the wire;
+ * the app connects to it inside the mounted per-app dir.
+ */
+export function homeProxySocketPath(appId: string): string {
+  return `${homeProxyAppDir(appId)}/home-proxy.sock`;
+}
+
+/**
+ * Mount target inside the app container — the DIRECTORY the grant bind-mounts
+ * the per-app proxy dir at. Under `/run` so it doesn't collide with an app's
+ * own filesystem.
+ */
+const REALM_HOME_PROXY_CONTAINER_DIR = "/run/realm/home-proxy";
+
+/**
+ * In-container path `callHome` connects to by default — the socket inside the
+ * mounted `REALM_HOME_PROXY_CONTAINER_DIR`.
+ */
+export const REALM_HOME_PROXY_CONTAINER_PATH = `${REALM_HOME_PROXY_CONTAINER_DIR}/home-proxy.sock`;
+
+/**
+ * The mount `home.apiAccess` resolves `{ socket }` to for one app. Read-only:
+ * `callHome` connects to the socket inside this directory and never writes to
+ * the directory itself.
+ */
+export function homeProxyMount(appId: string): WorkerMount {
+  return {
+    hostPath: homeProxyAppDir(appId),
+    containerPath: REALM_HOME_PROXY_CONTAINER_DIR,
+    readOnly: true,
+  };
+}

package/src/worker-protocol/index.ts

@@ -0,0 +1,55 @@
+// @yourrealm/sdk/worker-protocol — Home ↔ Worker wire contracts.
+//
+// Schemas + types both live here so Home and Worker validate against the
+// same source. Adding a new wire surface (log-tap, etc.) means a new
+// file next to worker-state.ts with a Zod schema + an inferred type.
+
+export {
+  dependsOnEdgeSchema,
+  wireServiceSchema,
+  workerAppSchema,
+  workerStateSchema,
+} from "./worker-state.ts";
+export type { DependsOnEdge, WireService, WorkerApp, WorkerState } from "./worker-state.ts";
+export { ingressInputSchema, PLATFORM_INGRESS_PORTS } from "./ingress.ts";
+export type { IngressInput } from "./ingress.ts";
+export { nodeVersionSchema, readNodeVersion, shortNodeVersion } from "./node-version.ts";
+export type { NodeVersion } from "./node-version.ts";
+export { readUpdateFiles } from "./update-files.ts";
+export type { UpdateFiles } from "./update-files.ts";
+export { REALM_LOGS_DIR, REALM_LOGS_MOUNT, REALM_LOGS_SOCKET } from "./logs-socket-path.ts";
+export { REALM_STATS_DIR, REALM_STATS_MOUNT, REALM_STATS_SOCKET } from "./stats-socket-path.ts";
+export type { WorkerMount } from "./worker-mount.ts";
+export {
+  MANAGEMENT_NET,
+  SILO_NET_PREFIX,
+  UNTRUSTED_NET,
+  isSiloNetwork,
+  siloNetwork,
+} from "./networks.ts";
+export { REALM_APP_DIR_GID, isPreparedAppDir, scopeBindSource } from "./app-dirs.ts";
+export {
+  REALM_SILO_DIR,
+  isManagedSiloPath,
+  managedSiloPath,
+  siloReclaimCommand,
+  siloSetupCommand,
+  siloWidenCommand,
+} from "./silo-paths.ts";
+export type { SiloOrphan } from "./silo-paths.ts";
+export {
+  REALM_SPAWN_DIR,
+  spawnMounts,
+  spawnSocketDir,
+  spawnSocketPath,
+  spawnScratchPath,
+  spawnArtifactsPath,
+} from "./spawn-paths.ts";
+export type { SpawnValue } from "./spawn-paths.ts";
+export {
+  REALM_HOME_PROXY_CONTAINER_PATH,
+  REALM_HOME_PROXY_DIR,
+  homeProxyAppDir,
+  homeProxyMount,
+  homeProxySocketPath,
+} from "./home-proxy-paths.ts";

package/src/worker-protocol/ingress.ts

@@ -0,0 +1,166 @@
+// The ingress half of the Home → Worker wire contract.
+//
+// `WorkerState.ingress` says *where traffic goes*, the way `WorkerState.apps`
+// says *what runs*. Both are runtime-neutral: an implementation picks a
+// renderer for each and satisfies them however it likes. The Docker worker
+// pairs `apps` with `convertToDockerCompose` and `ingress` with
+// `buildCaddyConfig` (`runtime/docker/ingress/`); a Fargate worker would emit
+// ECS task definitions and ALB listener rules from these same two fields. So
+// the schema lives here, in the protocol, while the renderer that consumes it
+// lives under `runtime/docker/` - that split is what lets a second worker
+// implementation read the same field.
+//
+// Two things are deliberately NOT here:
+//   - Caddy's config document. Shipping the rendered blob would lock the wire
+//     to one proxy and validate nothing (`workerStateSchema.parse` cannot see
+//     into an opaque string).
+//   - Docker network names. The routed entries carry no `network`: it is
+//     always `realm_${appId}`, and the Docker renderer derives it.
+//
+// Install-time fields (`baseDomain`, `homeSlug`, the acme-dns credentials) ride
+// along even though the installer could seed them on the box: they carry
+// secrets, so they need the per-worker encrypted channel rather than a plain
+// file, and one delivery path beats two that can disagree.
+
+import { z } from "zod";
+
+/**
+ * One ACME DNS-01 credential set: the acme-dns shim's base URL plus the label
+ * this caller owns under it.
+ *
+ * `ca` is an ACME directory URL override (staging / a test CA); empty means
+ * the renderer's default endpoint. `caRootPem` is the PEM to trust for that
+ * endpoint - the BYTES, not a path. A path would have to be agreed between
+ * whoever writes the file and whoever references it, which are two different
+ * modules; with the bytes on the wire the renderer owns both ends and the two
+ * cannot disagree.
+ */
+const acmeIssuerSchema = z.object({
+  serverUrl: z.string(),
+  username: z.string(),
+  apiKey: z.string(),
+  ca: z.string(),
+  caRootPem: z.string(),
+});
+
+/**
+ * A routed service's router, projected down to what a renderer reads.
+ *
+ * NOT a copy of `RoutedRouter` (`schema/peer.ts`): that type also carries
+ * `name`, `icon` and `tile`, which are Home's dashboard presentation
+ * and have no business on a worker's wire. Home enumerates the fields below
+ * explicitly when it derives this, so a router field added later stays off the
+ * wire until someone puts it here on purpose.
+ */
+const ingressRouterSchema = z.object({
+  containerPort: z.number().int().min(1).max(65535),
+  /** Operator-granted hostnames for the additional ungated public route. */
+  publicDomain: z.union([z.string(), z.array(z.string())]).optional(),
+  /** With several granted hosts: serve them all, or serve one and 301 the rest. */
+  domainMode: z.enum(["redirect", "all"]),
+  pathPrefix: z
+    .string()
+    .regex(/^\/[a-zA-Z0-9/_-]*$/, "pathPrefix must start with / and contain only [a-zA-Z0-9/_-]")
+    .optional(),
+  compress: z.boolean(),
+  maxRequestSizeMb: z.number().nullable(),
+  rateLimit: z
+    .union([
+      z.number(),
+      z.object({
+        requests: z.number(),
+        window: z.string().regex(/^\d+(ms|s|m|h)$/, "window must be a duration like 10s, 1m, 1h"),
+      }),
+    ])
+    .nullable(),
+  /** Response-header overrides; `null` deletes the renderer's default. */
+  headers: z.record(z.string(), z.string().nullable()).optional(),
+});
+
+const ingressRoutedAppSchema = z.object({
+  appId: z.string(),
+  services: z.array(z.object({ serviceId: z.string(), router: ingressRouterSchema })),
+  /**
+   * Header-brokering names the app declared via `getTrustedHeaders`. The
+   * renderer injects these on the authenticated route (lifted off the
+   * forward-auth response) and strips them everywhere else, so identity can't
+   * be spoofed.
+   */
+  trustedHeaderKeys: z.array(z.string()).optional(),
+});
+
+export const ingressInputSchema = z.object({
+  /** Every routed service on this worker, ordered canonically by `appId`. */
+  routedApps: z.array(ingressRoutedAppSchema),
+  /**
+   * The Home dashboard's own host, `{homeSlug}.{workerId}.{baseDomain}` - one
+   * label under the worker wildcard, which a renderer has to match ahead of
+   * that wildcard so the not-routed holding page never shadows it.
+   *
+   * Null on a box that does not run Home. The name resolves realm-wide (it
+   * sits under the realm's wildcard), so emitting the route on a worker-only
+   * box would answer a hit there with a page claiming the control plane is
+   * down - and, under BYO public providers, cost a real per-host certificate
+   * on every worker. Home knows which box is which from `home_state
+   * .home_worker_id`.
+   */
+  dashboardHost: z.string().nullable(),
+  /**
+   * This worker's short slug: the `{workerId}` level of every app subdomain,
+   * and the label it owns under acme-dns.
+   */
+  workerId: z.string(),
+  /**
+   * The realm's domain base (`{slug}.yourrealm.me`, or the operator's own).
+   * With `workerId` it forms every structured authenticated subdomain. Empty
+   * on the placeholder identity, before an install is configured.
+   */
+  baseDomain: z.string(),
+  /** DNS-01 inputs for the worker wildcard, or null (dev / e2e / first boot). */
+  acmeDns: acmeIssuerSchema.extend({ baseDomain: z.string() }).nullable(),
+  /**
+   * BYO public-DNS providers, in issue order. `apiToken` is a plain string:
+   * a `Ref` cannot ride the wire, and by this point Home has resolved it.
+   */
+  publicProviders: z.array(
+    z.object({ name: z.enum(["cloudflare", "hetzner"]), apiToken: z.string() }),
+  ),
+  /**
+   * CDNs in front of this realm, whose edge addresses ingress trusts when
+   * resolving the real client IP. The addresses themselves are not here - the
+   * renderer's runtime fetches and refreshes them.
+   */
+  cdnProviders: z.array(z.string()),
+  /**
+   * The signing-certificate fingerprints in the Digital Asset Links statement
+   * the ingress serves on every host - the statement's
+   * `sha256_cert_fingerprints`, which Chrome matches the companion APK's own
+   * signature against before it drops the Trusted Web Activity's toolbar.
+   *
+   * Operator-set rather than a constant, because which certificate signs the
+   * installed APK is a property of how that operator got it: Play App Signing
+   * re-signs with Google's key, direct distribution keeps the release
+   * keystore's, and a locally built debug APK carries a third.
+   *
+   * The shape is pinned here because the renderer inlines these strings into a
+   * JSON body Caddy's `ReplaceKnown` walks: uppercase hex bytes and colons can
+   * never form a `{placeholder}`, so a value that parses cannot reach into the
+   * replacer.
+   */
+  companionFingerprints: z.array(
+    z
+      .string()
+      .regex(/^[0-9A-F]{2}(:[0-9A-F]{2}){31}$/, "expected 32 colon-separated uppercase hex bytes"),
+  ),
+});
+
+export type IngressInput = z.infer<typeof ingressInputSchema>;
+
+/**
+ * The ports the box ingress binds, for the life of the box.
+ *
+ * Constants rather than grants: the ingress is placed by the installer as a
+ * platform compose project, so no app declares them and no operator can refuse
+ * them - a realm whose 443 is closed is a realm nobody can reach.
+ */
+export const PLATFORM_INGRESS_PORTS = [80, 443] as const;

package/src/worker-protocol/logs-socket-path.ts

@@ -0,0 +1,50 @@
+import type { WorkerMount } from "./worker-mount.ts";
+
+/**
+ * Branded host-absolute path supplied by the worker (e.g. the host.logs
+ * broker socket dir). Mirrors `PeerHostPath`: lets a worker-managed path
+ * flow into `volumes.hostPath` without widening the literal-path type
+ * to allow arbitrary `string` host paths.
+ */
+export type WorkerHostPath = string & { readonly __workerHostPath: unique symbol };
+
+/**
+ * Host directory the worker keeps the shared logs socket inside. This is the
+ * path an app mounts (the DIRECTORY, not the socket file): a file bind-mount
+ * of a unix socket does NOT wire to the live listener across containers on
+ * macOS Docker (connect succeeds, no bytes flow), so every broker socket lives
+ * alone in its own directory and the app mounts that directory. The value
+ * `r.host.logs()` resolves to (and the path the resolver exempts from the
+ * absolute-mount gate).
+ *
+ * Lives under `/opt/realm/worker/` because that directory is the one volume
+ * the worker container already shares with the host (see `install-script.ts`'s
+ * `-v /opt/realm/worker:/opt/realm/worker`), so the socket the worker writes
+ * is the same inode an app container can bind-mount through the host docker
+ * daemon.
+ *
+ * Lives in worker-protocol because it's a Home↔Worker contract: Home encodes
+ * the path into WorkerState via `host.logs.toValue`; Worker binds the socket
+ * inside it on startup. Pure constants, no runtime imports, so `schema/host.ts`
+ * (loaded in QuickJS) and any realm.ts consumer can pull it without dragging
+ * Deno deps.
+ */
+export const REALM_LOGS_DIR = "/opt/realm/worker/logs" as WorkerHostPath;
+
+/**
+ * Host path of the logs socket, inside {@link REALM_LOGS_DIR}. The worker's
+ * logs-server binds this; a consumer mounts {@link REALM_LOGS_DIR} and connects
+ * to the socket at the corresponding path inside the mounted directory.
+ */
+export const REALM_LOGS_SOCKET = `${REALM_LOGS_DIR}/logs.sock`;
+
+/**
+ * What `r.host.logs()` resolves to: the mount, not the bare path. Read-only
+ * because {@link REALM_LOGS_DIR} is shared by every app holding the grant -
+ * see {@link WorkerMount}.
+ */
+export const REALM_LOGS_MOUNT: WorkerMount = {
+  hostPath: REALM_LOGS_DIR,
+  containerPath: "/run/realm/logs",
+  readOnly: true,
+};

package/src/worker-protocol/networks.ts

@@ -0,0 +1,39 @@
+// Worker-owned external networks - shared Docker bridges created out of band
+// (`management-net` by the installer, `untrusted-net` by the spawn broker) and
+// joined via `host.*` permissions. Both surface in `build-wire`'s
+// `externalNetworks` and land on each service's `joinNetworks` post-up. Branded
+// `Network` so a raw name can't stand in for a `joinNetworks` entry.
+//
+// Co-located because they're the same kind of thing: `host.management`
+// (schema/host.ts) reads `MANAGEMENT_NET`, the spawn broker reads
+// `UNTRUSTED_NET`, and `build-wire` matches both. Pure constants, type-only
+// import, so the QuickJS-loaded `schema/host.ts` can pull them.
+
+import type { Network } from "../identifiers.ts";
+
+/**
+ * The Home's management bridge: dashboard URL plumbing + Home identity,
+ * joined by system-app proxies/sidecars via `host.management()`.
+ */
+export const MANAGEMENT_NET = "management-net" as Network;
+
+/**
+ * The untrusted-zone ("DMZ") bridge a spawned box attaches to at create time.
+ * The broker creates it and joins the box; no app service does.
+ */
+export const UNTRUSTED_NET = "untrusted-net" as Network;
+
+/**
+ * Prefix of every Silo bridge. App ids never contain `_`, so
+ * `realm_silo_<siloId>` can't collide with an app's own `realm_<appId>`.
+ */
+export const SILO_NET_PREFIX = "realm_silo_";
+
+/** The shared bridge of one Silo, created `Internal: true` by the worker pre-up. */
+export function siloNetwork(siloId: string): Network {
+  return `${SILO_NET_PREFIX}${siloId}` as Network;
+}
+
+export function isSiloNetwork(name: string): boolean {
+  return name.startsWith(SILO_NET_PREFIX);
+}

package/src/worker-protocol/node-version.ts

@@ -0,0 +1,70 @@
+// What a node knows about its own version: the image it was started from
+// and the commit that built it. Home and Worker answer the question the same
+// way, so the contract lives here instead of being written twice.
+//
+// Split by who supplies what. `REALM_GIT_HASH` / `REALM_BUILD_DATE` are baked
+// into the image at build time. `REALM_IMAGE_REF` cannot be - a container has
+// no way to read its own digest - so the install script's compose injects it
+// from the `.env` pin, which makes that pin the single source of truth for both
+// what runs and what gets reported.
+//
+// Every field is nullable rather than defaulted, and the build-args default to
+// empty rather than to a placeholder like "dev". A node can legitimately know
+// only part of this - a hand-built image reports its digest but no commit - and
+// "unknown" must never be mistakable for a real answer, because the
+// self-updater's applied signal compares these strings.
+
+import { z } from "zod";
+
+export const nodeVersionSchema = z.object({
+  // The pinned ref this container runs: `benjick/realm-worker@sha256:…` for a
+  // pulled image, a bare image ID for a locally-loaded one (see the installer's
+  // pin_image). This is the string an `applied` audit entry matches against.
+  imageRef: z.string().nullable(),
+  // The commit the image was built from - a full SHA from the publish workflow,
+  // null for anything built outside it.
+  gitHash: z.string().nullable(),
+  // ISO-8601 build timestamp, read back off the image's OCI `created` label by
+  // the publish workflow so the reported date and the image's own can't drift.
+  buildDate: z.string().nullable(),
+});
+
+export type NodeVersion = z.infer<typeof nodeVersionSchema>;
+
+// An unset build-arg reaches the container as an empty ENV, not an absent one,
+// so empty normalizes to null alongside undefined.
+function readEnv(name: string): string | null {
+  const value = Deno.env.get(name);
+  return value === undefined || value === "" ? null : value;
+}
+
+/**
+ * Read this container's version identity from the environment.
+ *
+ * Reads lazily on purpose. `bundle.ts`'s allowlist is prefix-based
+ * (`ALLOWED_IMPORT_PREFIXES = ["@yourrealm/sdk", ...]`), so an author's
+ * `realm.ts` may legally import this entry and have it bundled into QuickJS,
+ * where `Deno` does not exist. Module scope must stay clean; calling this in
+ * there is the author's own error and fails at the call, not at load.
+ *
+ * Enforced by `quickjs-safe.test.ts` next to this file: hoisting the read to
+ * module scope fails it with `ReferenceError: 'Deno' is not defined`.
+ */
+export function readNodeVersion(): NodeVersion {
+  return {
+    imageRef: readEnv("REALM_IMAGE_REF"),
+    gitHash: readEnv("REALM_GIT_HASH"),
+    buildDate: readEnv("REALM_BUILD_DATE"),
+  };
+}
+
+/**
+ * Short human label for a node's version, for UI and logs. Prefers the commit
+ * (a person can look it up); falls back to the digest's leading hex so a node
+ * built outside CI still reads as something. `null` when neither is known.
+ */
+export function shortNodeVersion(version: NodeVersion): string | null {
+  if (version.gitHash) return version.gitHash.slice(0, 7);
+  const digest = version.imageRef?.split("sha256:")[1];
+  return digest ? digest.slice(0, 12) : null;
+}

package/src/worker-protocol/silo-paths.ts

@@ -0,0 +1,114 @@
+// Wire constants for `host.silo()` — the shared directory a Silo's members
+// mount. Home stores the concrete path on the Silo row (never this template),
+// so changing the root here can't re-point an existing Silo at bytes that
+// didn't move; the builder is what Home calls when it mints a *new* managed
+// Silo, and what the worker's docs point at when explaining where they live.
+//
+// Pure string constants, no runtime imports, so this stays QuickJS-safe like
+// its siblings.
+
+/**
+ * Host directory holding every Realm-managed Silo, one per id.
+ *
+ * Beneath `/opt/realm/worker/` for the same reason the broker sockets are: it's
+ * the one directory the worker container already shares read-write with the
+ * host, so the tree the worker prepares (group, setgid, group rwx) is the same
+ * inode a member bind-mounts through the host docker daemon. A path the worker
+ * can't reach is a path it can't `chgrp`, and an unprepared Silo directory is
+ * just a root-owned folder every member gets EACCES from.
+ *
+ * It sits beside `apps/`, where each app's own `./data` already resolves, so
+ * all of a worker's persistent state stays under one root.
+ */
+export const REALM_SILO_DIR = "/opt/realm/worker/silo";
+
+/** Host path of one Realm-managed Silo's shared directory. */
+export function managedSiloPath(id: string): string {
+  return `${REALM_SILO_DIR}/${id}`;
+}
+
+/**
+ * Whether Realm made this directory, and so may prepare it.
+ *
+ * The worker's guard and Home's "is this Silo adopted" test are the same
+ * question, so they're the same function: a Silo Home believes it adopted but
+ * the worker believes it manages would get its group rewritten on every
+ * reconcile, which is the one thing adoption promises never happens.
+ */
+export function isManagedSiloPath(hostPath: string): boolean {
+  return hostPath.startsWith(`${REALM_SILO_DIR}/`);
+}
+
+/**
+ * Single-quote a path for the shell. Always, never conditionally: a real folder
+ * name can hold a space, an `&`, or brackets, and an unquoted `/mnt/my media`
+ * is two operands - so `chgrp -R` walks one tree the operator didn't name and
+ * `chmod` misses the one they did. `'\''` is the only escape a single-quoted
+ * string needs.
+ */
+function shellQuote(path: string): string {
+  return `'${path.replaceAll("'", "'\\''")}'`;
+}
+
+/**
+ * The command that makes an adopted directory shareable, for the operator to
+ * run on the box that holds it.
+ *
+ * Realm allocates the group and hands over the one command that applies it,
+ * rather than reaching into a directory it didn't create. `chgrp -R` because a
+ * member has to be able to reach what's already in there; `g+rwxs` because
+ * group-write plus setgid is what makes a file *one* member writes editable by
+ * the *others* (setgid is the half no image can supply - it's a property of the
+ * directory).
+ *
+ * The `chmod` is deliberately NOT recursive: `-R` would rewrite the permission
+ * bits of every file the operator already has, and `g+...s` on a regular file is
+ * a setgid binary. Directories that already exist keep their modes, which is
+ * what the operator is told - widening that is their call, not ours.
+ *
+ * One definition, because the Silos page, the install picker and the docs all
+ * show this string and an operator who runs a stale one gets a Silo that looks
+ * ready and shares nothing.
+ */
+export function siloSetupCommand(silo: { hostPath: string; gid: number }): string {
+  const path = shellQuote(silo.hostPath);
+  return `chgrp -R ${silo.gid} ${path}\nchmod g+rwxs ${path}`;
+}
+
+/**
+ * The widening for an adopted directory that already had folders in it: setup
+ * leaves their modes alone, so members can read them and generally can't write
+ * into them. Optional, and the operator's call - which is why it's a second
+ * command they choose to run rather than a third line of the first one.
+ *
+ * Rendered here rather than by whichever surface displays it, for the same
+ * reason as `siloSetupCommand`: it's a path going into a root shell, and the one
+ * place that knows to quote it should be the only place that builds it.
+ */
+export function siloWidenCommand(silo: { hostPath: string }): string {
+  return `find ${shellQuote(silo.hostPath)} -type d -exec chmod g+rwxs {} +`;
+}
+
+/**
+ * A managed directory left on disk after its Silo row was deleted. The worker
+ * reports these (name + last change + size); Home diffs against live ids and
+ * shows the survivors with the reclaim command.
+ */
+export interface SiloOrphan {
+  /** Directory name under REALM_SILO_DIR — the dead Silo's id. */
+  id: string;
+  /** ISO timestamp of the directory's last modification. */
+  mtime: string | null;
+  /** Total bytes inside, or null when the tree was too large to walk in time. */
+  sizeBytes: number | null;
+}
+
+/**
+ * The command that removes an orphaned directory, for the operator to run on
+ * the box that holds it. Deleting a Silo never deletes its bytes and no Realm
+ * code path ever will - reclaiming is the operator's act, so what Realm hands
+ * over is instructions, exactly as adoption hands over the `chgrp`.
+ */
+export function siloReclaimCommand(orphan: { workerIp: string; hostPath: string }): string {
+  return `ssh root@${orphan.workerIp}\nrm -rf ${shellQuote(orphan.hostPath)}`;
+}