omp-conductor 0.3.25 → 0.4.0

package/src/verbs/socket.ts

@@ -0,0 +1,446 @@
+/**
+ * The authenticated local transport the mutation verbs ride on (#126).
+ *
+ * The permission layout is the whole security argument, and the obvious one
+ * does not work. A socket `chmod 0600` and `chown`ed to a run's principal is
+ * *unreachable* if its parent is the daemon's usual `0700`: connecting needs
+ * **search** (`+x`) on every path component, not read. So:
+ *
+ *  - the parent directory is daemon-owned and mode **`0711`** — searchable by
+ *    run principals, listable by none, and **writable by none but the daemon**;
+ *  - each socket is `0600`, owned by the principal of the run it belongs to, so
+ *    exactly one uid can connect, and the orchestrator's is a third distinct one;
+ *  - the parent being non-writable is what stops a run unlinking a sibling's
+ *    socket or binding an impostor listener in its place. A per-run directory
+ *    owned by the run principal would hand back exactly that power, and is why
+ *    the obvious layout is not used here.
+ *
+ * Two further rules make that layout hold rather than merely describe it:
+ * {@link validateSocketPath} refuses to bind under a path anyone else could
+ * have tampered with, and {@link peerVerdict} compares the connecting uid the
+ * kernel reports against the uid the daemon allocated for that run.
+ *
+ * Every decision in this file is a pure function of `lstat` results or of a
+ * credentials struct, so the adversarial cases are testable without root and
+ * without a second uid.
+ */
+
+import { dlopen, FFIType, ptr, suffix } from "bun:ffi";
+import { randomBytes } from "node:crypto";
+import { chmodSync, chownSync, lstatSync, mkdirSync, rmSync } from "node:fs";
+import type { Stats } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+/** Searchable by run principals, listable by none, writable only by the daemon. */
+export const VERB_DIR_MODE = 0o711;
+
+/** One uid may connect. The parent's `0711` is what makes that reachable. */
+export const VERB_SOCKET_MODE = 0o600;
+
+/**
+ * How long a socket path may be.
+ *
+ * `sun_path` is 104 bytes on darwin and 108 on Linux, *including* the
+ * terminator, and a bind past it fails with a truncation nobody reads as a
+ * path-length problem. Refusing at 100 leaves headroom on both and turns a
+ * confusing `ENAMETOOLONG` into a named dispatch refusal.
+ */
+export const SOCKET_PATH_MAX = 100;
+
+/** The daemon-owned parent every verb socket lives directly inside. */
+export function verbSocketDir(root: string): string {
+  return join(root, "verbs");
+}
+
+/**
+ * Create (or repair the mode of) the socket parent.
+ *
+ * `chmod` on every call rather than only on create: a directory left `0700` by
+ * an older release, or widened by hand, would otherwise stay wrong until
+ * somebody deleted it — and the failure is silent in the safe direction for
+ * `0700` (nothing can connect) and silent in the unsafe direction for `0777`.
+ */
+export function ensureVerbSocketDir(root: string): string {
+  const dir = verbSocketDir(root);
+  mkdirSync(dir, { recursive: true, mode: VERB_DIR_MODE });
+  chmodSync(dir, VERB_DIR_MODE);
+  return dir;
+}
+
+/**
+ * A per-run socket path with an unguessable suffix.
+ *
+ * Unguessable because the parent is unlistable: a run that cannot enumerate the
+ * directory and cannot guess a sibling's filename cannot even name the socket
+ * it is not allowed to open. The suffix is the second lock on a door whose
+ * first lock is `0600` ownership.
+ */
+export function verbSocketPath(dir: string, label: string): string {
+  const slug = label.replace(/[^A-Za-z0-9_-]+/g, "-").slice(0, 24);
+  return join(dir, `${slug}-${randomBytes(8).toString("hex")}.sock`);
+}
+
+export type SocketPathFault =
+  | "not-absolute"
+  | "too-long"
+  | "missing"
+  | "symlink"
+  | "not-directory"
+  | "foreign-owner"
+  | "group-writable"
+  | "other-writable"
+  | "not-searchable";
+
+export interface SocketPathProblem {
+  /** The offending path component, named so the refusal is actionable. */
+  component: string;
+  fault: SocketPathFault;
+  message: string;
+}
+
+/** Every ancestor of `path`, root first, excluding `path` itself. */
+function ancestors(path: string): string[] {
+  const out: string[] = [];
+  let cursor = dirname(resolve(path));
+  for (;;) {
+    out.unshift(cursor);
+    const parent = dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+  return out;
+}
+
+/**
+ * Verify nobody but the daemon could have tampered with where this socket is
+ * about to be bound. A failure **refuses dispatch** — it never degrades to
+ * binding anyway, because a socket under a directory a third party can write is
+ * a socket a third party can replace.
+ *
+ * Ownership is `daemonUid` **or root**. Requiring the daemon to own `/` and
+ * `/Users` is not a check, it is a condition that can never hold, and a check
+ * that always fails gets deleted by the next person who reads it. Root-owned
+ * ancestors are the operating system's, and a host whose `/usr` is hostile has
+ * already lost in ways no socket mode addresses.
+ *
+ * `lstat` rather than `stat`, deliberately: `stat` follows the very symlink
+ * this is looking for.
+ */
+export function validateSocketPath(
+  path: string,
+  daemonUid: number,
+  lstat: (p: string) => Stats = lstatSync,
+): SocketPathProblem | undefined {
+  if (!isAbsolute(path)) {
+    return {
+      component: path,
+      fault: "not-absolute",
+      message: `verb socket path ${path} is not absolute`,
+    };
+  }
+  if (Buffer.byteLength(path) > SOCKET_PATH_MAX) {
+    return {
+      component: path,
+      fault: "too-long",
+      message: `verb socket path ${path} is ${Buffer.byteLength(path)} bytes, over the ${SOCKET_PATH_MAX}-byte limit a unix socket address allows`,
+    };
+  }
+
+  for (const component of ancestors(path)) {
+    let stat: Stats;
+    try {
+      stat = lstat(component);
+    } catch {
+      return {
+        component,
+        fault: "missing",
+        message: `verb socket parent ${component} does not exist or cannot be read`,
+      };
+    }
+    if (stat.isSymbolicLink()) {
+      return {
+        component,
+        fault: "symlink",
+        message: `verb socket parent ${component} is a symlink; a component that can be re-pointed is a socket that can be moved under the daemon`,
+      };
+    }
+    if (!stat.isDirectory()) {
+      return {
+        component,
+        fault: "not-directory",
+        message: `verb socket parent ${component} is not a directory`,
+      };
+    }
+    if (stat.uid !== daemonUid && stat.uid !== 0) {
+      return {
+        component,
+        fault: "foreign-owner",
+        message: `verb socket parent ${component} is owned by uid ${stat.uid}, neither the daemon (${daemonUid}) nor root`,
+      };
+    }
+    if ((stat.mode & 0o020) !== 0) {
+      return {
+        component,
+        fault: "group-writable",
+        message: `verb socket parent ${component} is group-writable (mode ${(stat.mode & 0o7777).toString(8)}); anyone in that group could replace the socket`,
+      };
+    }
+    if ((stat.mode & 0o002) !== 0) {
+      return {
+        component,
+        fault: "other-writable",
+        message: `verb socket parent ${component} is world-writable (mode ${(stat.mode & 0o7777).toString(8)}); anyone on this host could replace the socket`,
+      };
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The first path component a *foreign* uid could not search through, or
+ * `undefined` when the whole chain is traversable.
+ *
+ * Checked rather than assumed, because this is the failure the layout in this
+ * file is most likely to hit in the field and the least likely to be noticed:
+ * connecting to a socket needs `+x` on **every** component, and the daemon's
+ * own state directory is `0700`. A run principal would then be refused at the
+ * state directory rather than at the socket, with an `EACCES` that names a
+ * directory nobody was thinking about.
+ *
+ * Only meaningful when the run has a distinct principal. Under one uid the
+ * daemon is the caller, so `0700` is traversable by definition — which is
+ * exactly why this cannot be left to be discovered on the first fleet that
+ * turns per-run principals on.
+ *
+ * Deliberately reported rather than repaired: the fix is `chmod o+x` on a
+ * directory that may be the operator's home, and a daemon that silently
+ * widened `$HOME` would be trading a legible refusal for a surprise.
+ */
+export function traversalProblem(
+  path: string,
+  lstat: (p: string) => Stats = lstatSync,
+): SocketPathProblem | undefined {
+  for (const component of ancestors(path)) {
+    let stat: Stats;
+    try {
+      stat = lstat(component);
+    } catch {
+      return {
+        component,
+        fault: "missing",
+        message: `verb socket parent ${component} does not exist or cannot be read`,
+      };
+    }
+    if ((stat.mode & 0o001) === 0) {
+      return {
+        component,
+        fault: "not-searchable",
+        message:
+          `verb socket parent ${component} is mode ${(stat.mode & 0o7777).toString(8)}, which a run principal ` +
+          `cannot search through. Connecting needs +x on every component. Run: chmod o+x ${component}`,
+      };
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Remove a stale socket at `path`, and only ever one the daemon itself placed.
+ *
+ * Called after {@link validateSocketPath} has passed, so the parent is known
+ * non-writable by anyone else — which is what makes "unlink and rebind" safe
+ * here and unsafe in `/tmp`. Nothing outside the daemon ever unlinks these.
+ */
+export function unlinkStaleSocket(path: string): void {
+  rmSync(path, { force: true });
+}
+
+/**
+ * Hand a bound socket to its run's principal.
+ *
+ * Returns which guarantee is actually in force, because #126 asks the daemon to
+ * *state* its mechanism at startup rather than guess: with a principal the
+ * socket is one-uid; without one it is one-user, and the parent's `0711` plus
+ * the unguessable suffix are the whole story. Saying which is the difference
+ * between an audited boundary and a hopeful one.
+ */
+export type SocketOwnership = "run-principal" | "daemon-user";
+
+export function secureBoundSocket(
+  path: string,
+  principal: { uid: number; gid: number } | undefined,
+  chmod: (p: string, mode: number) => void = chmodSync,
+  chown: (p: string, uid: number, gid: number) => void = chownSync,
+): SocketOwnership {
+  chmod(path, VERB_SOCKET_MODE);
+  if (principal === undefined) return "daemon-user";
+  chown(path, principal.uid, principal.gid);
+  return "run-principal";
+}
+
+export interface PeerCredentials {
+  uid: number;
+  gid: number;
+}
+
+/**
+ * Read the connecting process's credentials off a connected socket fd, or
+ * `undefined` where the platform (or this runtime's socket object) does not
+ * expose them.
+ *
+ * `getpeereid` on darwin, `SO_PEERCRED` on Linux — both asked of the kernel,
+ * which is the point: the answer cannot be forged by the peer, unlike anything
+ * the peer could put in a payload.
+ */
+export type PeerReader = (fd: number) => PeerCredentials | undefined;
+
+interface LibcSymbols {
+  getpeereid?: (fd: number, uid: unknown, gid: unknown) => number;
+  getsockopt?: (fd: number, level: number, name: number, value: unknown, len: unknown) => number;
+}
+
+/** `SOL_SOCKET` / `SO_PEERCRED` on Linux. Both are ABI constants, not guesses. */
+const SOL_SOCKET_LINUX = 1;
+const SO_PEERCRED_LINUX = 17;
+
+/**
+ * The peer reader for this host, or `undefined` when there is none.
+ *
+ * Resolved once at daemon start so the mechanism can be logged before the
+ * first socket exists, rather than discovered on the first connection. The
+ * `dlopen` is inside the try because it is the part that fails on a host
+ * without a loadable libc — the symbols this asks for are POSIX, but a
+ * hardened or unusual host is entitled to refuse, and "we could not ask" must
+ * never read as "the uid matched".
+ */
+export function peerCredentialReader(): PeerReader | undefined {
+  const declarations: Record<string, { args: FFIType[]; returns: FFIType }> =
+    process.platform === "darwin"
+      ? { getpeereid: { args: [FFIType.i32, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 } }
+      : {
+          getsockopt: {
+            args: [FFIType.i32, FFIType.i32, FFIType.i32, FFIType.ptr, FFIType.ptr],
+            returns: FFIType.i32,
+          },
+        };
+  // `libc.${suffix}` is `libc.so` on Linux, and that is a GNU **linker script**,
+  // not a shared object — `dlopen` refuses it, the reader silently resolves to
+  // undefined, and peer-credential verification is quietly absent on the one
+  // platform the fleet actually runs on. Measured on ubuntu-24.04. So the real
+  // sonames are tried first, and only then the generic name for musl and macOS.
+  const candidates =
+    process.platform === "linux"
+      ? ["libc.so.6", "libc.musl-x86_64.so.1", "libc.musl-aarch64.so.1", `libc.${suffix}`]
+      : [`libc.${suffix}`];
+
+  let symbols: LibcSymbols | undefined;
+  for (const lib of candidates) {
+    try {
+      symbols = dlopen(lib, declarations).symbols as LibcSymbols;
+      break;
+    } catch {
+      // Next candidate. Exhausting them all is a real answer — see the docstring:
+      // "we could not ask" must never read as "the uid matched".
+    }
+  }
+  if (symbols === undefined) return undefined;
+
+  if (process.platform === "darwin") {
+    const getpeereid = symbols.getpeereid;
+    if (getpeereid === undefined) return undefined;
+    return (fd) => {
+      const uid = new Uint32Array(1);
+      const gid = new Uint32Array(1);
+      if (getpeereid(fd, ptr(uid), ptr(gid)) !== 0) return undefined;
+      return { uid: uid[0] ?? -1, gid: gid[0] ?? -1 };
+    };
+  }
+
+  const getsockopt = symbols.getsockopt;
+  if (getsockopt === undefined) return undefined;
+  return (fd) => {
+    // struct ucred { pid_t pid; uid_t uid; gid_t gid; } — three 32-bit fields.
+    const cred = new Uint32Array(3);
+    const len = new Uint32Array([cred.byteLength]);
+    if (getsockopt(fd, SOL_SOCKET_LINUX, SO_PEERCRED_LINUX, ptr(cred), ptr(len)) !== 0) {
+      return undefined;
+    }
+    return { uid: cred[1] ?? -1, gid: cred[2] ?? -1 };
+  };
+}
+
+/**
+ * The file descriptor behind a `node:net` socket, or `undefined`.
+ *
+ * Reached through the handle rather than a public accessor because neither
+ * Node nor Bun exposes one, and narrowed here so exactly one place in this
+ * package knows that. An absent fd is not a failure — it means peer credentials
+ * cannot be read, which {@link peerVerdict} accounts for explicitly.
+ */
+export function socketFd(socket: unknown): number | undefined {
+  const handle = (socket as { _handle?: { fd?: unknown } } | null)?._handle;
+  const fd = handle?.fd;
+  return typeof fd === "number" && fd >= 0 ? fd : undefined;
+}
+
+export type PeerVerdict =
+  | { ok: true; basis: "peer-uid"; uid: number }
+  | { ok: true; basis: "socket-ownership"; why: string }
+  | { ok: false; detail: string; peerUid: number; expectedUid: number };
+
+/**
+ * Compare the kernel-reported peer against the uid the daemon allocated.
+ *
+ * The two `ok` bases are not the same guarantee and are deliberately not
+ * collapsed. `peer-uid` means the kernel vouched for the caller. `socket-
+ * ownership` means nobody could vouch and the whole guarantee is the `0600`
+ * socket under an unlistable, daemon-owned, non-writable parent — which is
+ * real, but it does not distinguish two runs sharing one uid. A caller that
+ * printed "verified" for both would be claiming something it never checked.
+ */
+export function peerVerdict(
+  expected: { uid: number } | undefined,
+  peer: PeerCredentials | undefined,
+): PeerVerdict {
+  if (expected === undefined) {
+    return {
+      ok: true,
+      basis: "socket-ownership",
+      why: "this run has no distinct OS principal, so peer uid cannot tell two runs apart; the 0600 socket under the daemon-owned 0711 parent is the whole boundary",
+    };
+  }
+  if (peer === undefined) {
+    return {
+      ok: true,
+      basis: "socket-ownership",
+      why: "this host exposes no peer credentials, so the 0600 socket owned by the run principal is the whole boundary",
+    };
+  }
+  if (peer.uid !== expected.uid) {
+    return {
+      ok: false,
+      peerUid: peer.uid,
+      expectedUid: expected.uid,
+      detail: `uid ${peer.uid} connected to a socket allocated to uid ${expected.uid}`,
+    };
+  }
+  return { ok: true, basis: "peer-uid", uid: peer.uid };
+}
+
+/** One line naming what the transport can actually enforce on this host. */
+export function transportBanner(
+  dir: string,
+  peerReader: PeerReader | undefined,
+  principals: boolean,
+): string {
+  const peers =
+    peerReader === undefined
+      ? `no peer-credential call on ${process.platform}`
+      : process.platform === "darwin"
+        ? "peer uid asserted with getpeereid"
+        : "peer uid asserted with SO_PEERCRED";
+  const owners = principals
+    ? "each socket 0600 and chowned to its run principal"
+    : "each socket 0600 under the daemon's own uid (no per-run principals on this host)";
+  return `verb sockets in ${dir} (mode ${VERB_DIR_MODE.toString(8)}); ${owners}; ${peers}`;
+}

package/src/worker.ts

@@ -10,9 +10,9 @@
  * sliding into a merge queue.
  */
 
+import type { SessionBoundary } from "./credentials.ts";
 import { createSession, disposeSession } from "./omp.ts";
-import type { ReleaseShape } from "./release-policy.ts";
-import type { Caps, ReleasePolicy, RunState } from "./types.ts";
+import type { Caps, ReleaseShape, ResolvedGrants, RunState } from "./types.ts";
 
 /** Structured evidence fields from the worker's final report. */
 const PR_URL_PATTERN = /^pr:\s*(https:\/\/github\.com\/\S+\/pull\/\d+)\s*$/im;
@@ -46,10 +46,34 @@ export interface WorkerOpts {
    * the harness to pick, which is what an unconfigured project wants.
    */
   model?: string;
-  /** Effective release/deploy gate for this session. */
-  releasePolicy?: ReleasePolicy;
+  /**
+   * Effective per-shape release grants for this session. A worker is refused
+   * every shape whatever they say — see {@link SessionRole} — so this is passed
+   * for the audit trail and the wording of the refusal, not for permission.
+   */
+  releaseGrants?: ResolvedGrants;
   /** Durable audit sink for rejected release/deploy calls. */
   onReleaseBlocked?: (shape: ReleaseShape) => void;
+  /**
+   * The OS principal this run's session executes as (#125). The worker does not
+   * interpret it — it hands it to {@link createSession}, which is where the
+   * launcher lives. Omitted, the session is still a child process but runs as
+   * the daemon's own user: that is A1's shape and carries no security claim.
+   */
+  boundary?: SessionBoundary;
+  /**
+   * Control socket for that child. The daemon puts it inside the run's own
+   * boundary root, because a slot principal has to be able to reach it.
+   */
+  socketPath?: string;
+  /**
+   * The run's conductor verb socket (#126) — its only route to a push, a PR or
+   * any other mutation. Distinct from `socketPath`: that is the daemon's
+   * control channel to the child, this is the child's mediated way back out.
+   */
+  verbSocketPath?: string;
+  /** Where the session child's stdout/stderr go. Defaults to this process's stderr. */
+  onChildLog?: (line: string) => void;
   /**
    * Reads the effective ceiling at each turn boundary. Omitted, the configured
    * startup cap remains fixed for the run.
@@ -177,10 +201,15 @@ export async function runWorker(
     cwd: o.cwd,
     ...(o.sessionDir === undefined ? {} : { sessionDir: o.sessionDir }),
     ...(o.model === undefined ? {} : { model: o.model }),
-    // Prevention half of #24: structured file tools cannot leave this worktree.
-    confineToCwd: true,
-    ...(o.releasePolicy === undefined ? {} : { releasePolicy: o.releasePolicy }),
+    // Prevention half of #24: as a worker, structured file tools cannot leave
+    // this worktree, and no release grant can ever reach this session (#122).
+    role: "worker",
+    ...(o.releaseGrants === undefined ? {} : { releaseGrants: o.releaseGrants }),
     ...(o.onReleaseBlocked === undefined ? {} : { onReleaseBlocked: o.onReleaseBlocked }),
+    ...(o.boundary === undefined ? {} : { boundary: o.boundary }),
+    ...(o.socketPath === undefined ? {} : { socketPath: o.socketPath }),
+    ...(o.verbSocketPath === undefined ? {} : { verbSocketPath: o.verbSocketPath }),
+    ...(o.onChildLog === undefined ? {} : { onChildLog: o.onChildLog }),
   });
 
   // Before the first turn, not after the last: a caller that only learns the