@bitkyc08/opencodex 2.87.0 → 2.89.0

package/src/messaging/remote-enrollment.ts

@@ -0,0 +1,244 @@
+import { mkdtempSync, rmSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildExecArgv, buildFingerprintArgv, buildProbeArgv, remoteOcxArgv, isSshAlias } from "../link/ssh-argv";
+import { parseFingerprintLine } from "../link/fingerprint";
+import { MessageBudget } from "./budget";
+import { capability, exactRecord, RemoteCapacity, REMOTE_PROTOCOL, remoteError, validAlias,
+  validCapability, validMachine, validPort, REMOTE_LIMITS, type RemoteState } from "./remote-contract";
+import { readRemoteFile, removeRemoteFile, withRemoteLock, writeRemoteFile } from "./remote-files";
+import { parseEnrollmentJournal } from "./remote-enrollment-recovery";
+import { runRemoteHelper } from "./remote-process";
+import { RemoteMessageStore } from "./remote-store";
+import { isThreadId } from "./types";
+
+export type RemoteControlRunner = (argv: readonly string[], budget: MessageBudget, capacity: RemoteCapacity,
+  stdin?: string) => Promise<string>;
+
+/** Forget only the revoked transaction, while the state mutation lock is still owned. */
+function forgetPendingTransaction(store: RemoteMessageStore, transaction: string, removeJournal = unlinkSync): void {
+  const path = join(store.directory, "enrollment.json");
+  const text = readRemoteFile(path);
+  if (text === null) return;
+  let pendingTransaction: unknown;
+  try {
+    const saved = exactRecord(JSON.parse(text), ["alias", "ssh", "fingerprint", "generation", "request"]);
+    const request = exactRecord(saved.request, ["protocol", "action", "params"]);
+    pendingTransaction = exactRecord(request.params, ["machine", "transaction", "returnCapability", "port"]).transaction;
+  } catch {
+    // Uninterpretable text cannot match a valid in-flight saved journal.
+    return;
+  }
+  if (pendingTransaction === transaction) removeRemoteFile(path, removeJournal);
+}
+/** Offer one host fingerprint without enrollment or persistent state; clean only this probe's scratch directory. */
+export async function probeRemoteHost(ssh: string, budget: MessageBudget, capacity: RemoteCapacity,
+  runner: RemoteControlRunner = runRemoteHelper) {
+  if (!isSshAlias(ssh)) throw remoteError("invalid_ssh_alias", "Choose a valid SSH destination.");
+  const root = mkdtempSync(join(tmpdir(), "ocx-message-probe-"));
+  const path = join(root, "known_hosts");
+  try {
+    writeRemoteFile(path, "");
+    await runner(buildProbeArgv({ alias: ssh, tempKnownHostsFile: path }), budget, capacity);
+    const fingerprint = parseFingerprintLine((await runner(buildFingerprintArgv(path), budget, capacity)).trim()).fingerprint;
+    const hostKey = readRemoteFile(path);
+    if (!hostKey || hostKey.length > 8192 || hostKey.trim().split("\n").length !== 1
+      || !hostKey.startsWith(`${ssh} `)) {
+      throw remoteError("invalid_host_key", "SSH probe did not return one bounded alias-bound host key.");
+    }
+    return { fingerprint, hostKey };
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+/** Versioned private stdio control: invoked over confirmed SSH, never the network messaging gateway. */
+export function handleEnrollmentControl(store: RemoteMessageStore, input: unknown, removeJournal = unlinkSync): unknown {
+  const raw = exactRecord(input, ["protocol", "action", "params"]);
+  if (raw.protocol !== REMOTE_PROTOCOL) throw remoteError("remote_incompatible", "Remote messaging protocol versions differ.");
+  const state = store.requireEnabled();
+  if (raw.action === "enroll") {
+    const params = exactRecord(raw.params, ["machine", "transaction", "returnCapability", "port"]);
+    if (!validMachine(params.machine) || params.machine.id === state.machine.id || !isThreadId(params.transaction)
+      || !validCapability(params.returnCapability) || !validPort(params.port)) {
+      throw remoteError("invalid_enrollment", "Invalid messaging enrollment contract.");
+    }
+    const machine = params.machine, transaction = params.transaction, returnCapability = params.returnCapability, port = params.port;
+    let incoming = "", full = false;
+    const committed = store.mutate(current => {
+      const existing = current.peers.find(peer => peer.machine.id === machine.id || peer.transaction === transaction);
+      if (existing) {
+        if (existing.transaction !== transaction || existing.machine.id !== machine.id || existing.outgoing !== returnCapability
+          || existing.port !== port) {
+          throw remoteError("enrollment_conflict", "An existing enrollment cannot be silently replaced.");
+        }
+        incoming = existing.incoming;
+        return;
+      }
+      if (current.peers.length >= REMOTE_LIMITS.peers) {
+        full = true;
+        return;
+      }
+      incoming = capability();
+      current.peers.push({ alias: `peer-${machine.id}`, machine, transaction, incoming, outgoing: returnCapability,
+        port, ssh: null, hostKey: null, fingerprint: null, allowInbound: true });
+    });
+    if (full) return { protocol: REMOTE_PROTOCOL, transaction, rejected: "peer_capacity" };
+    return { protocol: REMOTE_PROTOCOL, transaction, machine: committed.machine, port: committed.port, capability: incoming };
+  }
+  if (raw.action === "remove") {
+    const params = exactRecord(raw.params, ["machineId", "transaction"]);
+    if (!isThreadId(params.machineId) || !isThreadId(params.transaction)) {
+      throw new Error();
+    }
+    store.mutate(current => {
+      // Invalidate recovery before publishing absence, including an enrollment not yet locally published.
+      forgetPendingTransaction(store, params.transaction as string, removeJournal);
+      current.peers = current.peers.filter(peer => peer.machine.id !== params.machineId || peer.transaction !== params.transaction);
+    });
+    return { protocol: REMOTE_PROTOCOL, removed: true };
+  }
+  throw remoteError("invalid_control", "Unsupported messaging enrollment control operation.");
+}
+/** Grant outbound delivery and correlated return replies, never arbitrary inbound delivery on the initiator. */
+export async function enrollRemoteHost(store: RemoteMessageStore, alias: string, ssh: string, fingerprint: string,
+  budget: MessageBudget, capacity: RemoteCapacity, runner: RemoteControlRunner = runRemoteHelper) {
+  const state = store.requireEnabled();
+  if (!validAlias(alias) || !isSshAlias(ssh) || !/^SHA256:[A-Za-z0-9+/=]{1,64}$/.test(fingerprint)) {
+    throw remoteError("invalid_enrollment", "Alias, SSH destination and confirmed fingerprint are required.");
+  }
+  const offered = await probeRemoteHost(ssh, budget, capacity, runner);
+  if (offered.fingerprint !== fingerprint) throw remoteError("host_key_changed", "The offered SSH key differs from the explicitly confirmed fingerprint.");
+  const pendingPath = join(store.directory, "enrollment.json");
+  const pending = withRemoteLock(store.directory, () => {
+    const existing = readRemoteFile(pendingPath);
+    if (existing !== null) {
+      const saved = parseEnrollmentJournal(existing);
+      if (saved.alias !== alias || saved.ssh !== ssh || saved.fingerprint !== fingerprint) {
+        throw remoteError("enrollment_pending", "Reconcile the existing messaging enrollment before starting another.");
+      }
+      return saved;
+    }
+    const current = store.requireEnabled();
+    if (current.generation !== state.generation) throw remoteError("enrollment_pending", "Local configuration changed during the probe; repeat explicitly.");
+    if (current.peers.some(peer => peer.alias === alias)) throw remoteError("enrollment_conflict", "This messaging alias is already enrolled.");
+    if (current.peers.length >= REMOTE_LIMITS.peers) throw remoteError("peer_capacity", "Remove an enrolled peer before adding another.");
+    const saved = { alias, ssh, fingerprint, generation: current.generation, request: { protocol: REMOTE_PROTOCOL, action: "enroll",
+      params: { machine: state.machine, transaction: crypto.randomUUID(), returnCapability: capability(), port: state.port } } };
+    budget.throwIfEnded();
+    writeRemoteFile(pendingPath, JSON.stringify(saved));
+    return saved;
+  });
+  const request = pending.request, params = request.params;
+  if (pending.generation !== state.generation || request.protocol !== REMOTE_PROTOCOL || request.action !== "enroll" || !validMachine(params.machine)
+    || params.machine.id !== state.machine.id || !isThreadId(params.transaction) || !validCapability(params.returnCapability)
+    || params.port !== state.port) {
+    throw remoteError("enrollment_pending", "Pending enrollment no longer matches this node; reconcile it explicitly.");
+  }
+  const hostsPath = join(store.directory, `enrollment_known_hosts-${params.transaction}-${crypto.randomUUID()}`);
+  try {
+    withRemoteLock(store.directory, () => {
+      if (readRemoteFile(pendingPath) !== JSON.stringify(pending)) {
+        throw remoteError("enrollment_pending", "Pending enrollment changed before SSH preparation.");
+      }
+      writeRemoteFile(hostsPath, offered.hostKey);
+    });
+    let reply: Record<string, unknown>;
+    try {
+      const value = JSON.parse(await runner(buildExecArgv({ alias: ssh, knownHostsFile: hostsPath,
+        argv: remoteOcxArgv(["message", "_control"]) }), budget, capacity, JSON.stringify(request)));
+      reply = exactRecord(value, value?.rejected !== undefined ? ["protocol", "transaction", "rejected"]
+        : ["protocol", "transaction", "machine", "port", "capability"]);
+      if (reply.protocol !== REMOTE_PROTOCOL || reply.transaction !== params.transaction) {
+        throw new Error("Enrollment reply does not match this protocol/transaction.");
+      }
+      if (reply.rejected !== undefined) {
+        if (reply.rejected !== "peer_capacity") throw new Error("Unknown enrollment rejection.");
+      } else if (!validMachine(reply.machine) || reply.machine.id === state.machine.id
+        || !validPort(reply.port) || !validCapability(reply.capability)) {
+        throw new Error("Invalid enrollment reply identity, port or capability.");
+      }
+    } catch {
+      throw remoteError("enrollment_unknown", "Remote enrollment may have committed. Reconcile the retained transaction, if present; do not create a replacement automatically.");
+    }
+    if (reply.rejected === "peer_capacity") {
+      throw remoteError("peer_capacity", "The remote node has no free messaging peer slot. Retry the same transaction after freeing a slot, or explicitly abandon it.");
+    }
+    const machine = reply.machine as RemoteState["machine"];
+    let inbound = "responses-only";
+    try {
+      budget.throwIfEnded();
+      const savedText = JSON.stringify(pending);
+      let ownsJournal = false;
+      store.mutate(current => {
+        if (current.generation !== state.generation) {
+          throw remoteError("enrollment_unknown", "Local configuration changed during enrollment; the remote transaction is retained.");
+        }
+        ownsJournal = readRemoteFile(pendingPath) === savedText;
+        const existing = current.peers.find(peer => peer.alias === alias || peer.machine.id === machine.id);
+        if (existing) {
+          if (existing.alias !== alias || existing.machine.id !== machine.id || existing.transaction !== params.transaction
+            || existing.incoming !== params.returnCapability || existing.outgoing !== reply.capability
+            || existing.port !== reply.port || existing.ssh !== ssh || existing.fingerprint !== fingerprint
+            || existing.hostKey !== offered.hostKey) {
+            throw remoteError("enrollment_conflict", "The remote identity is already enrolled differently.");
+          }
+          inbound = existing.allowInbound === true ? "messages" : "responses-only";
+          return;
+        }
+        if (!ownsJournal) throw remoteError("enrollment_unknown", "This enrollment no longer owns the saved transaction.");
+        current.peers.push({ alias, machine, transaction: params.transaction as string, incoming: params.returnCapability as string,
+          outgoing: reply.capability as string, port: reply.port as number, ssh, hostKey: offered.hostKey, fingerprint, allowInbound: false });
+      }, () => {
+        if (ownsJournal) forgetPendingTransaction(store, params.transaction as string);
+      });
+    } catch {
+      throw remoteError("enrollment_unknown", "Remote enrollment committed, but local completion is uncertain. Inspect current enrollment and any retained transaction before an explicit retry.");
+    }
+    return { protocol: REMOTE_PROTOCOL, alias, machine, enrolled: true, outbound: "messages", inbound,
+      inboundOptInCommand: `ocx message hosts allow-inbound ${machine.id} --json` };
+  } finally {
+    // The unique attempt owns this path, not the shared journal; a busy mutation must not prevent cleanup.
+    try {
+      if (readRemoteFile(hostsPath) !== null) removeRemoteFile(hostsPath);
+    } catch {
+      throw remoteError("remote_storage_unknown", "Enrollment scratch cleanup could not be confirmed. Inspect local state before recovery; the remote enrollment may have committed.");
+    }
+  }
+}
+/** Revoke locally first, then attempt exact remote revocation; unknown cleanup never restores local admission. */
+export async function removeRemoteHost(store: RemoteMessageStore, selector: string, budget: MessageBudget,
+  capacity: RemoteCapacity, runner: RemoteControlRunner = runRemoteHelper, removeJournal = unlinkSync,
+  expectedTransaction?: string) {
+  let peer!: RemoteState["peers"][number];
+  const state = store.mutate(current => {
+    const matches = current.peers.filter(item => item.alias === selector || item.machine.id === selector);
+    if (matches.length !== 1) throw remoteError("unknown_peer", "No unique enrolled messaging peer matches this exact host.");
+    peer = matches[0]!;
+    if (expectedTransaction !== undefined && (!isThreadId(expectedTransaction) || peer.transaction !== expectedTransaction)) {
+      throw remoteError("enrollment_conflict", "The peer no longer matches the cleanup transaction; no peer was removed.");
+    }
+    forgetPendingTransaction(store, peer.transaction, removeJournal);
+    current.peers = current.peers.filter(item => item.transaction !== peer.transaction);
+  });
+  let remote: "removed" | "unconfirmed" = "unconfirmed";
+  if (peer.ssh) {
+    const path = join(store.directory, `revocation_known_hosts-${peer.transaction}-${crypto.randomUUID()}`);
+    try {
+      writeRemoteFile(path, peer.hostKey!);
+      const reply = exactRecord(JSON.parse(await runner(buildExecArgv({ alias: peer.ssh, knownHostsFile: path,
+        argv: remoteOcxArgv(["message", "_control"]) }), budget, capacity, JSON.stringify({ protocol: REMOTE_PROTOCOL,
+        action: "remove", params: { machineId: state.machine.id, transaction: peer.transaction } }))), ["protocol", "removed"]);
+      if (reply.protocol === REMOTE_PROTOCOL && reply.removed === true) remote = "removed";
+    } catch {
+      // Receipt explicitly preserves unconfirmed remote cleanup.
+    } finally {
+      try {
+        removeRemoteFile(path);
+      } catch {
+        // Scratch cleanup is best-effort and cannot undo local revocation.
+      }
+    }
+  }
+  return { protocol: REMOTE_PROTOCOL, machine: peer.machine, locallyRemoved: true, remote,
+    ...(remote === "unconfirmed" ? { remoteCleanupCommand: `ocx message hosts remove ${state.machine.id} --transaction ${peer.transaction} --json` } : {}) };
+}

package/src/messaging/remote-envelope.ts

@@ -0,0 +1,40 @@
+import { messageEnvelope } from "./envelope";
+import { isRecord } from "./types";
+import { remoteError, type RemotePeer } from "./remote-contract";
+
+/** Accept only the canonical wrapper bound to this authenticated enrollment and queue UUID. */
+export function receiveRemoteEnvelope(text: string, messageId: string, peer: RemotePeer) {
+  const prefix = "[opencodex-message ";
+  const end = text.indexOf("]\n\n");
+  const marker = "\n\nPeer-provided message body follows:\n\n";
+  const bodyStart = text.indexOf(marker, end);
+  try {
+    if (!text.startsWith(prefix) || end < prefix.length || bodyStart < end) {
+      throw new Error("Invalid message envelope framing.");
+    }
+    const header: unknown = JSON.parse(text.slice(prefix.length, end));
+    if (!isRecord(header) || header.messageId !== messageId) {
+      throw new Error("Message envelope header does not match the queue UUID.");
+    }
+    if (header.threadId !== null && typeof header.threadId !== "string") {
+      throw new Error("Invalid message envelope sender thread.");
+    }
+    if (header.name !== null && (typeof header.name !== "string" || header.name.length > 4096)) {
+      throw new Error("Invalid message envelope sender name.");
+    }
+    const sender = header.threadId === null ? null : {
+      id: header.threadId as string, name: header.name as string | null, status: "idle" as const,
+    };
+    const envelope = messageEnvelope(messageId, {
+      kind: header.kind as "request" | "response" | "notification",
+      ...(header.inReplyTo === null ? {} : { inReplyTo: header.inReplyTo as string }),
+    }, text.slice(bodyStart + marker.length), sender, peer.machine);
+    // This also rejects forged reply commands/hosts, missing guidance, duplicate JSON keys and extra fields.
+    if (envelope.text !== text) {
+      throw new Error("Message envelope is not canonical for the authenticated peer.");
+    }
+    return envelope;
+  } catch {
+    throw remoteError("invalid_remote_envelope", "Remote message attribution or guidance does not match the authenticated peer.");
+  }
+}

package/src/messaging/remote-files.ts

@@ -0,0 +1,117 @@
+import { constants, closeSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync,
+  realpathSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
+import { remoteError, REMOTE_LIMITS } from "./remote-contract";
+
+/** Check the entire path ancestry before using the private messaging subtree. */
+export function checkRemoteDirectory(path: string): void {
+  checkDirectory(path, true);
+}
+/** The configuration home needs trusted ancestry; only messaging's own leaf must be private. */
+function checkDirectory(path: string, privateLeaf: boolean): void {
+  if (!["linux", "darwin"].includes(process.platform) || !isAbsolute(path)) {
+    throw remoteError("unsupported_platform", "Remote messaging requires a private Linux or macOS configuration home.");
+  }
+  try {
+    const final = lstatSync(path);
+    if (!final.isDirectory() || final.isSymbolicLink()
+      || (privateLeaf && (final.uid !== process.getuid!() || (final.mode & 0o077)))) throw new Error();
+    // Root-controlled OS aliases (/tmp and /var on macOS) are not user-controlled redirects.
+    for (let entry = path; ; entry = dirname(entry)) {
+      const stat = lstatSync(entry);
+      if (stat.isSymbolicLink()) { if (stat.uid !== 0) throw new Error(); }
+      else if (!stat.isDirectory() || (stat.uid !== process.getuid!() && stat.uid !== 0)
+        || ((stat.mode & 0o022) !== 0 && !(stat.uid === 0 && (stat.mode & 0o1000) !== 0))
+        || (privateLeaf && entry === path && (stat.uid !== process.getuid!() || (stat.mode & 0o077) !== 0))) throw new Error();
+      if (entry === "/") break;
+    }
+    for (let entry = realpathSync(path); ; entry = dirname(entry)) {
+      const stat = lstatSync(entry);
+      if (!stat.isDirectory() || (stat.uid !== process.getuid!() && stat.uid !== 0)
+        || ((stat.mode & 0o022) && !(stat.uid === 0 && (stat.mode & 0o1000)))) throw new Error();
+      if (entry === "/") break;
+    }
+  } catch { throw remoteError("unsafe_remote_storage", "Messaging storage requires private owned directories and trusted ancestors."); }
+}
+/** ENOENT alone means absent; permission failures and redirects are not empty state. */
+export function remotePathExists(path: string): boolean {
+  try { lstatSync(path); return true; }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return false; throw error; }
+}
+/** A published directory entry must reach storage before dependent remote work starts. */
+function syncRemoteDirectory(path: string, sync = fsyncSync): void {
+  let fd: number | undefined;
+  try {
+    fd = openSync(realpathSync(path), constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    sync(fd);
+  } catch { throw remoteError("remote_storage_unknown", "Messaging storage changed, but its crash durability could not be confirmed; inspect state before explicit recovery."); }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+/** Remove a validated private file durably; shared journals require the caller's mutation lock. */
+export function removeRemoteFile(path: string, remove = unlinkSync, sync = fsyncSync): void {
+  assertNotRealHomeUnderTest(path); readRemoteFile(path);
+  remove(path); syncRemoteDirectory(dirname(path), sync);
+}
+/** Create only explicitly requested state, refusing an unsafe existing configuration home. */
+export function createRemoteDirectory(path: string): void {
+  assertNotRealHomeUnderTest(path);
+  const parent = dirname(path);
+  if (!remotePathExists(parent)) {
+    if (!remotePathExists(dirname(parent))) throw remoteError("unsafe_remote_storage", "Messaging configuration parent must already exist.");
+    checkDirectory(dirname(parent), false);
+    mkdirSync(parent, { mode: 0o700 });
+    syncRemoteDirectory(dirname(parent));
+  }
+  checkDirectory(parent, false);
+  if (!remotePathExists(path)) { mkdirSync(path, { mode: 0o700 }); syncRemoteDirectory(parent); }
+  checkRemoteDirectory(path);
+}
+/** Bounded, fatal-UTF-8, no-follow regular file reads never open SQLite or create absent state. */
+export function readRemoteFile(path: string): string | null {
+  if (!remotePathExists(dirname(path))) return null;
+  checkRemoteDirectory(dirname(path));
+  let fd: number;
+  try { fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw remoteError("unsafe_remote_storage", "Cannot safely read messaging state.");
+  }
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.nlink !== 1 || stat.uid !== process.getuid!() || (stat.mode & 0o077)
+      || stat.size > REMOTE_LIMITS.storeBytes) throw new Error();
+    const bytes = Buffer.alloc(REMOTE_LIMITS.storeBytes + 1);
+    let size = 0;
+    while (size < bytes.length) { const count = readSync(fd, bytes, size, bytes.length - size, size); if (!count) break; size += count; }
+    if (size > REMOTE_LIMITS.storeBytes) throw new Error();
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, size));
+  } catch { throw remoteError("unsafe_remote_storage", "Messaging state is unsafe, oversized or malformed."); }
+  finally { closeSync(fd); }
+}
+/** Publish a private file atomically; this primitive is called while its store lock is owned. */
+export function writeRemoteFile(path: string, text: string, sync = fsyncSync): void {
+  assertNotRealHomeUnderTest(path);
+  checkRemoteDirectory(dirname(path));
+  if (Buffer.byteLength(text) > REMOTE_LIMITS.storeBytes) throw remoteError("remote_capacity", "Messaging state exceeds its byte limit.");
+  readRemoteFile(path);
+  const temporary = join(dirname(path), `.write-${crypto.randomUUID()}`);
+  const fd = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+  try {
+    try { writeFileSync(fd, text, "utf8"); sync(fd); } finally { closeSync(fd); }
+    renameSync(temporary, path);
+    syncRemoteDirectory(dirname(path), sync);
+  } finally { if (remotePathExists(temporary)) unlinkSync(temporary); }
+}
+/** Serialize cooperating mutations. Crash residue fails closed; it is never reaped by age. */
+export function withRemoteLock<T>(directory: string, action: () => T): T {
+  const lock = join(directory, "mutation.lock");
+  try { mkdirSync(lock, { mode: 0o700 }); }
+  catch { throw remoteError("remote_state_busy", "Messaging state is locked; finish or recover its owning mutation first."); }
+  const identity = lstatSync(lock);
+  try { return action(); }
+  finally {
+    const current = lstatSync(lock);
+    if (current.dev === identity.dev && current.ino === identity.ino) rmdirSync(lock);
+  }
+}

package/src/messaging/remote-owner.ts

@@ -0,0 +1,169 @@
+import { MessageBudget } from "./budget";
+import { authenticatedRemoteSocket, peerEndpoint, remoteControl, type RemoteEndpoint } from "./remote-auth";
+import { startRemoteBridge } from "./remote-bridge";
+import { exactRecord, RemoteCapacity, REMOTE_LIMITS, remoteError, validPort, type RemotePeer, type RemoteState } from "./remote-contract";
+import { remotePortIsLoopback } from "./remote-ports";
+import { LocalMessageRpc } from "./rpc";
+import type { RemoteMessageStore } from "./remote-store";
+import { startRemoteTunnels, type RemoteTunnelPair, type RemoteTunnelDeps } from "./remote-tunnels";
+import { isThreadId, LocalMessagingError } from "./types";
+
+interface Route { peer: RemotePeer; port: number; generation: string; expiry: number; ready: boolean; tunnels?: RemoteTunnelPair }
+export interface RemoteOwnerDeps extends RemoteTunnelDeps { now?: () => number }
+/** Local owner-control capability never leaves this configuration home or enters remote enrollment. */
+export function ownerEndpoint(state: RemoteState): RemoteEndpoint {
+  return { port: state.port, machineId: state.machine.id, transaction: state.generation, key: state.controlKey };
+}
+/** Discover a route from the live authenticated owner, never a cached loopback port or implicit startup. */
+export async function resolveRemoteRoute(store: RemoteMessageStore, selector: string, budget: MessageBudget) {
+  const state = store.requireEnabled(), peer = store.peer(selector);
+  const result = exactRecord(await remoteControl(state, ownerEndpoint(state), "message/routes", {}, budget), ["routes"]);
+  if (!Array.isArray(result.routes) || result.routes.length > REMOTE_LIMITS.peers) throw remoteError("invalid_remote_route", "Messaging owner returned invalid routes.");
+  const matches = result.routes.filter(route => route && typeof route === "object" && route.machineId === peer.machine.id);
+  if (matches.length !== 1) throw remoteError("route_unavailable", "No live messaging route exists for this enrolled peer; run the explicit foreground owner.");
+  const route = exactRecord(matches[0], ["machineId", "transaction", "port", "kind"]);
+  if (route.transaction !== peer.transaction || !validPort(route.port) || !["initiated", "leased"].includes(String(route.kind))) throw remoteError("invalid_remote_route", "Messaging route does not match the current enrollment.");
+  store.requireCurrentPeer(state, peer);
+  return { state, peer, endpoint: peerEndpoint(peer, route.port) };
+}
+
+/** Explicit foreground lifetime: one listener, aggregate reservations and bounded owned tunnel teardown. */
+export async function startRemoteOwner(store: RemoteMessageStore, home: string, selectors: readonly string[], parent?: AbortSignal,
+  tunnelDeps: RemoteOwnerDeps = {}) {
+  const state = store.requireEnabled(), generation = crypto.randomUUID(), controller = new AbortController();
+  const now = tunnelDeps.now ?? (() => performance.now());
+  const capacity = new RemoteCapacity(), routes = new Map<string, Route>(), operations = new Set<Promise<unknown>>();
+  // Availability may retire before cleanup settles; retain every published pair's join and failure.
+  const ownedTunnels = new Set<RemoteTunnelPair>();
+  let finish!: () => void, finishError!: (error: Error) => void;
+  const finished = new Promise<void>((resolve, reject) => { finish = resolve; finishError = reject; });
+  void finished.catch(() => {});
+  let stopping = false, closing: Promise<void> | undefined, timer: ReturnType<typeof setInterval> | undefined;
+  const check = () => {
+    const current = store.requireEnabled();
+    if (stopping || current.generation !== state.generation) throw remoteError("owner_retired", "Messaging owner configuration changed; restart this foreground owner explicitly.");
+    return current;
+  };
+  const probe = async (peer: RemotePeer, port: number, budget: MessageBudget) => {
+    const release = capacity.reserve("connections"); let rpc: LocalMessageRpc | undefined;
+    try { rpc = await LocalMessageRpc.attach(await authenticatedRemoteSocket(check(), peerEndpoint(peer, port), budget), budget); }
+    finally { rpc?.close(); release(); }
+  };
+  const bridge = startRemoteBridge(store, home, capacity, controller.signal, {
+    async control(peer, method, params, budget) {
+      check();
+      if (method === "message/routes" && !peer) {
+        exactRecord(params, []);
+        const current = check();
+        return { routes: [...routes.values()].filter(route => route.ready && current.peers.some(p => p.transaction === route.peer.transaction)
+          && (route.tunnels ? route.tunnels.alive : route.expiry > now())).map(route => ({
+          machineId: route.peer.machine.id, transaction: route.peer.transaction, port: route.port, kind: route.tunnels ? "initiated" : "leased" })) };
+      }
+      if (method !== "message/lease" || !peer) throw new Error();
+      const lease = exactRecord(params, ["port", "generation"]);
+      if (!validPort(lease.port) || !isThreadId(lease.generation)) throw new Error();
+      if (!await remotePortIsLoopback(lease.port, budget, capacity)) throw new Error();
+      await probe(peer, lease.port, budget);
+      check(); budget.throwIfEnded(); store.requireCurrentPeer(state, peer);
+      const existing = routes.get(peer.machine.id);
+      if (existing?.tunnels) throw new Error();
+      if (existing && existing.generation !== lease.generation && existing.expiry > now()) {
+        if (existing.port === lease.port) throw new Error();
+        // A live generation keeps its lease. Native availability is not owner identity evidence.
+        const release = capacity.reserve("connections"); let oldBudget: MessageBudget | undefined;
+        let authenticated = false;
+        try {
+          oldBudget = new MessageBudget(budget.remainingMs(1000), budget.signal);
+          try {
+            const socket = await authenticatedRemoteSocket(check(), peerEndpoint(existing.peer, existing.port), oldBudget);
+            socket.terminate(); authenticated = true;
+          } catch (error) {
+            if (!(error instanceof LocalMessagingError) || !["remote_auth_failed", "operation_timeout"].includes(error.code)) throw error;
+          }
+        } finally { oldBudget?.dispose(); release(); }
+        check(); budget.throwIfEnded(); store.requireCurrentPeer(state, peer);
+        if (authenticated || routes.get(peer.machine.id) !== existing) throw new Error();
+      }
+      routes.set(peer.machine.id, { peer, port: lease.port, generation: lease.generation, ready: true, expiry: now() + REMOTE_LIMITS.leaseMs });
+      return { leased: true, generation: lease.generation };
+    },
+  });
+  const register = async (route: Route, budget: MessageBudget) => {
+    const free = capacity.reserve("connections");
+    try {
+      const result = exactRecord(await remoteControl(check(), peerEndpoint(route.peer, route.port), "message/lease",
+        { port: route.tunnels!.returnPort, generation }, budget), ["leased", "generation"]);
+      check(); budget.throwIfEnded(); store.requireCurrentPeer(state, route.peer);
+      if (routes.get(route.peer.machine.id) !== route) throw new Error();
+      if (result.leased !== true || result.generation !== generation || !route.tunnels!.alive) throw new Error();
+    } finally { free(); }
+  };
+  const renew = async (budget: MessageBudget) => {
+    const results = await Promise.allSettled([...routes.values()].filter(route => route.tunnels).map(route => register(route, budget)));
+    const failure = results.find(result => result.status === "rejected");
+    if (failure?.status === "rejected") throw failure.reason;
+    check(); budget.throwIfEnded();
+  };
+  const close = (): Promise<void> => closing ??= (async () => {
+    stopping = true; clearInterval(timer); parent?.removeEventListener("abort", abort); controller.abort();
+    const results = await Promise.allSettled([bridge.close(), ...[...ownedTunnels].map(tunnels => tunnels.close()), ...operations]);
+    routes.clear(); ownedTunnels.clear();
+    if (results.some(result => result.status === "rejected")) {
+      const error = remoteError("cleanup_incomplete", "Messaging owner cleanup did not complete cleanly.");
+      finishError(error); throw error;
+    }
+    finish();
+  })();
+  const abort = () => { void close().catch(() => {}); };
+  parent?.addEventListener("abort", abort, { once: true });
+  if (parent?.aborted) abort();
+  const setup = new MessageBudget(30000, controller.signal);
+  try {
+    const unique = new Set(selectors.map(selector => store.peer(selector).machine.id));
+    if (unique.size !== selectors.length) throw remoteError("duplicate_peer", "Do not initiate the same peer more than once.");
+    for (const selector of selectors) {
+      check(); const peer = store.peer(selector);
+      const tunnels = await startRemoteTunnels(store, peer, setup, capacity, controller.signal, tunnelDeps);
+      const route: Route = { peer, port: tunnels.localPort, generation, expiry: Infinity, ready: false, tunnels };
+      try {
+        check(); setup.throwIfEnded(); ownedTunnels.add(tunnels); routes.set(peer.machine.id, route);
+      } catch (error) {
+        // Before publication this local scope, not the routes map, owns the join.
+        await tunnels.close(); throw error;
+      }
+      void tunnels.exited.then(() => {
+        if (!stopping && routes.get(peer.machine.id) === route) { routes.delete(peer.machine.id); abort(); }
+      });
+      // The data connection proves both the peer and native initialization before ready publication.
+      await probe(peer, route.port, setup); await register(route, setup);
+      check(); setup.throwIfEnded();
+    }
+    // Earlier peers may have spent their lease lifetime waiting for later setup.
+    const renewal = new MessageBudget(setup.remainingMs(5000), setup.signal);
+    try { await renew(renewal); for (const route of routes.values()) route.ready = true; }
+    finally { renewal.dispose(); }
+  } catch (error) { await close(); throw error; }
+  finally { setup.dispose(); }
+  if (stopping) { await close(); throw remoteError("owner_retired", "Messaging owner stopped during setup."); }
+  let refreshing = false;
+  timer = setInterval(() => {
+    if (refreshing || stopping) return;
+    refreshing = true;
+    const task = (async () => {
+      const budget = new MessageBudget(5000, controller.signal);
+      try {
+        check();
+        for (const route of [...routes.values()]) {
+          if (!store.read()?.peers.some(peer => peer.transaction === route.peer.transaction)) {
+            routes.delete(route.peer.machine.id); await route.tunnels?.close();
+          } else if (!route.tunnels && route.expiry <= now()) routes.delete(route.peer.machine.id);
+        }
+        await renew(budget);
+      } catch { abort(); }
+      finally { budget.dispose(); refreshing = false; }
+    })();
+    operations.add(task);
+    void task.finally(() => operations.delete(task));
+  }, 10000);
+  return { port: bridge.port, capacity, close, finished };
+}

package/src/messaging/remote-ports.ts

@@ -0,0 +1,56 @@
+import { open } from "node:fs/promises";
+import { MessageBudget } from "./budget";
+import { RemoteCapacity, remoteError, validPort } from "./remote-contract";
+import { runRemoteHelper, type RemoteHelperOptions } from "./remote-process";
+
+type RemoteProcFile = {
+  read(buffer: Buffer, offset: number, length: number, position: null): Promise<{ bytesRead: number }>;
+  close(): Promise<void>;
+};
+
+/** Select a candidate only; actual forwarding and authenticated readiness must still succeed. */
+export function remotePortCandidate(): number {
+  const listener = Bun.listen({ hostname: "127.0.0.1", port: 0, socket: { data(socket) { socket.end(); } } });
+  const port = listener.port; listener.stop(true);
+  if (!validPort(port)) throw remoteError("invalid_port", "Cannot allocate an unprivileged messaging port candidate.");
+  return port;
+}
+/** Refuse GatewayPorts/public binds; neither port existence nor this scan proves endpoint identity. */
+export async function remotePortIsLoopback(port: number, budget: MessageBudget, capacity: RemoteCapacity,
+  inspector: { platform?: NodeJS.Platform; helper?: RemoteHelperOptions;
+    openProc?: (path: string) => Promise<RemoteProcFile> } = {}): Promise<boolean> {
+  if (!validPort(port)) return false;
+  budget.throwIfEnded();
+  const platform = inspector.platform ?? process.platform;
+  if (platform === "linux") {
+    const found: string[] = [], hex = port.toString(16).toUpperCase().padStart(4, "0");
+    for (const path of ["/proc/net/tcp", "/proc/net/tcp6"]) {
+      let fd: RemoteProcFile;
+      try { fd = await (inspector.openProc ?? (path => open(path, "r")))(path); }
+      catch (error) {
+        if (path === "/proc/net/tcp6" && (error as NodeJS.ErrnoException).code === "ENOENT") continue;
+        throw error;
+      }
+      try {
+        const bytes = Buffer.alloc(4 * 1024 * 1024 + 1); let size = 0;
+        while (size < bytes.length) {
+          budget.throwIfEnded(); const next = await fd.read(bytes, size, bytes.length - size, null);
+          if (!next.bytesRead) break; size += next.bytesRead;
+        }
+        if (size >= bytes.length) return false;
+        for (const line of bytes.subarray(0, size).toString("utf8").split("\n").slice(1)) {
+          const fields = line.trim().split(/\s+/), [address, fieldPort] = (fields[1] ?? "").split(":");
+          if (fields[3] === "0A" && fieldPort === hex) found.push(address!);
+        }
+      } finally { await fd.close(); }
+    }
+    return found.length > 0 && found.every(address => address === "0100007F" || address === "00000000000000000000000001000000");
+  }
+  if (platform === "darwin") {
+    const output = await runRemoteHelper(["/usr/sbin/lsof", "-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-Fn"], budget, capacity,
+      undefined, undefined, { ...inspector.helper, successCodes: [0, 1] });
+    const addresses = output.split("\n").filter(line => line.startsWith("n"));
+    return addresses.length > 0 && addresses.every(line => line === `n127.0.0.1:${port}` || line === `n[::1]:${port}`);
+  }
+  return false;
+}