replica-bridge 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,8 @@
-# Temporary Holding Version
+# replica-bridge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lets the ChatReplica iPhone app use Codex on this computer. Needs Codex installed and signed in (`codex login`).
+
+    npx replica-bridge
+
+The first run sets this computer up with the relay, shows a QR code to scan in the app (远程 › 添加连接 › 配对新设备),
+and keeps running: paired phones can use Codex here while it does. `npx replica-bridge --help` lists the other commands.

package/package.json

@@ -1,6 +1,17 @@
 {
   "name": "replica-bridge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Lets the ChatReplica iPhone app use Codex on this computer through a relay, end-to-end encrypted.",
+  "type": "module",
+  "bin": {
+    "replica-bridge": "src/bridge/main.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "qrcode": "1.5.4",
+    "ws": "8.18.3"
+  },
+  "license": "UNLICENSED"
+}

package/src/bridge/enroll.js

@@ -0,0 +1,39 @@
+// First run: make this computer's key pair and enroll it, anonymously, with a relay.
+import fs from "node:fs";
+import os from "node:os";
+import { b64url, generateKeyPair } from "../protocol.js";
+import { relayRequest } from "../http.js";
+import { defaultEnvPath, loadRelayConfig } from "../relay/config.js";
+import { loadState, saveState } from "./state.js";
+                                              
+
+/** The project's public relay, which the app also signs in to by default (Sources/Core/RelayPairing.swift). */
+export const PUBLIC_RELAY = "https://agens.office-cli.onl";
+
+/** With no --relay: REPLICA_RELAY, else the relay on this machine over loopback, else the public relay. */
+export function defaultRelayURL()         {
+  if (process.env.REPLICA_RELAY) return process.env.REPLICA_RELAY;
+  return fs.existsSync(defaultEnvPath()) ? `http://127.0.0.1:${loadRelayConfig().port}` : PUBLIC_RELAY;
+}
+
+export async function enroll(relay        , options                                          = {})                       {
+  const keys = generateKeyPair();
+  const hostName = options.name ?? os.hostname();
+  const { hostId, hostToken } = await relayRequest                                       (relay, "POST", "/v1/hosts/enroll", { body: { publicKey: b64url(keys.publicKey), name: hostName } });
+  const state              = { relay, publicRelay: options.publicRelay, hostId, hostToken, hostName, hostPrivateKey: b64url(keys.privateKey), hostPublicKey: b64url(keys.publicKey), devices: [] };
+  saveState(state);
+  return state;
+}
+
+/** The saved state, enrolling first if this computer never has. */
+export async function ensureEnrolled(relay                    , say                        , name         )                       {
+  try {
+    return loadState();
+  } catch (error) {
+    if (!/not set up yet/.test((error         ).message)) throw error;
+  }
+  const url = relay ?? defaultRelayURL();
+  const state = await enroll(url, { name });
+  say(`Set up ${state.hostName} with ${url} (${state.hostId}).`);
+  return state;
+}

package/src/bridge/main.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// replica-bridge: runs on the computer that has Codex. See docs/RELAY.md.
+// The first pair or start sets the computer up by itself (anonymous enrollment); init does it explicitly.
+//   (no command) [--relay <url>] [--name <name>] [--pair] [--codex <path>]
+//       what `npx replica-bridge` runs: set up if needed, keep the bridge running, and show a QR code while no
+//       phone is paired yet (or with --pair)
+//   init [--relay <url>] [--public-url <url>] [--name <name>]
+//   config [--public-url <url>]
+//   pair [--relay <url>] [--confirm] [--yes] [--png <file>] [--timeout <seconds>]
+//   start [--codex <path>] [--stream-ttl <seconds>] [--no-login-shell]
+//   devices
+//   revoke <deviceId>
+import { spawnSync } from "node:child_process";
+import { parseArgs } from "node:util";
+import { relayRequest } from "../http.js";
+import { defaultRelayURL, enroll, ensureEnrolled } from "./enroll.js";
+import { pair, publicRelayURL } from "./pair.js";
+import { BridgeService } from "./service.js";
+import { loadState, saveState } from "./state.js";
+
+// A leading option means no command: `replica-bridge --pair` is the default command with --pair.
+const argv = process.argv.slice(2);
+const [command, ...rest] = argv[0]?.startsWith("-") ? [undefined, ...argv] : argv;
+const { values, positionals } = parseArgs({
+  args: rest,
+  allowPositionals: true,
+  options: {
+    relay: { type: "string" },
+    "public-url": { type: "string" },
+    name: { type: "string" },
+    confirm: { type: "boolean", default: false },
+    yes: { type: "boolean", default: false },
+    png: { type: "string" },
+    timeout: { type: "string", default: "600" },
+    pair: { type: "boolean", default: false },
+    help: { type: "boolean", short: "h", default: false },
+    codex: { type: "string" },
+    "stream-ttl": { type: "string", default: "1800" },
+    "no-login-shell": { type: "boolean", default: false },
+  },
+});
+
+const usage = `usage: replica-bridge [command] (docs/RELAY.md)
+  (none)          set up, keep running, and show a QR code until a phone is paired (--pair shows one anyway)
+  pair            show a QR code for another phone
+  start           keep running without showing a QR code
+  init            set up only (--relay <url>, --name <name>)
+  config          show the relay, this computer and its owner
+  devices         list paired phones
+  revoke <id>     remove a phone
+The relay is ${defaultRelayURL()} unless --relay or REPLICA_RELAY says otherwise.`;
+
+function startService() {
+  const service = new BridgeService({ codexPath: values.codex, loginShell: !values["no-login-shell"], streamTTLSeconds: Number(values["stream-ttl"]) });
+  service.start();
+  for (const signal of ["SIGINT", "SIGTERM"]         ) process.on(signal, () => { service.stop(); process.exit(0); });
+}
+
+/** Warns, without stopping, when Codex does not answer the way the bridge will run it (through the login shell). */
+function checkCodex() {
+  const codex = values.codex ?? "codex";
+  const loginShell = !values["no-login-shell"] && process.env.SHELL;
+  const result = loginShell
+    ? spawnSync(process.env.SHELL , ["-lic", `"$0" --version`, codex], { encoding: "utf8", timeout: 15_000 })
+    : spawnSync(codex, ["--version"], { encoding: "utf8", timeout: 15_000 });
+  if (result.status === 0) return;
+  console.warn(`Codex did not answer "${codex} --version". Install it (npm install -g @openai/codex) and sign in (codex login); the phone cannot use this computer until then.`);
+}
+
+async function main() {
+  if (values.help || command === "help") { console.log(usage); return; }
+  switch (command) {
+    case undefined:
+    case "up": {
+      checkCodex();
+      const state = await ensureEnrolled(values.relay, console.log, values.name);
+      startService();
+      if (values.pair || !state.devices.length) {
+        try {
+          await pair({ confirm: values.confirm, yes: values.yes, timeoutSeconds: Number(values.timeout), pngPath: values.png });
+        } catch (error) {
+          console.error(`replica-bridge: ${(error         ).message}. Pair later with "replica-bridge pair".`);
+        }
+      }
+      console.log(`Running: paired phones can use Codex on ${state.hostName} while this keeps running (Ctrl-C stops it).`);
+      break;
+    }
+    case "init": {
+      const relay = values.relay ?? defaultRelayURL();
+      const state = await enroll(relay, { name: values.name, publicRelay: values["public-url"] });
+      console.log(`Set up ${state.hostName} as ${state.hostId}. Next: "replica-bridge start" (keep it running), then "replica-bridge pair".`);
+      console.log("Nobody owns it yet: the first phone that scans its QR code and is approved here claims it.");
+      break;
+    }
+    case "config": {
+      const state = loadState();
+      if (values["public-url"] !== undefined) state.publicRelay = values["public-url"] || undefined;
+      saveState(state);
+      console.log(`relay ${state.relay}\npublic URL in QR codes ${publicRelayURL(state)}${state.publicRelay ? "" : " (from the relay's env file)"}\nhost ${state.hostName} (${state.hostId})\nowner ${state.owner ? `${state.owner.login} (${state.owner.provider})` : "none yet: pair a phone to claim it"}`);
+      break;
+    }
+    case "pair":
+      await ensureEnrolled(values.relay, console.log, values.name);
+      await pair({ confirm: values.confirm, yes: values.yes, timeoutSeconds: Number(values.timeout), pngPath: values.png });
+      break;
+    case "start":
+      await ensureEnrolled(values.relay, console.log, values.name);
+      startService();
+      break;
+    case "devices": {
+      const state = loadState();
+      const { owner, devices } = await relayRequest                                                                                                                                                                                   (state.relay, "GET", "/v1/host/devices", { token: state.hostToken });
+      console.log(owner ? `Owner: ${owner.login} (${owner.provider})` : "No owner yet.");
+      if (!devices.length) console.log("No paired phones.");
+      for (const d of devices) console.log(`${d.deviceId}  ${d.name} (${d.login})  paired ${new Date(d.createdAt).toLocaleString()}  ${d.revokedAt ? "removed" : d.online ? "online" : "offline"}`);
+      break;
+    }
+    case "revoke": {
+      const deviceId = positionals[0];
+      if (!deviceId) throw new Error("usage: replica-bridge revoke <deviceId>");
+      const state = loadState();
+      await relayRequest(state.relay, "DELETE", `/v1/host/devices/${encodeURIComponent(deviceId)}`, { token: state.hostToken });
+      state.devices = state.devices.filter((d) => d.deviceId !== deviceId);
+      saveState(state);
+      console.log(`Removed ${deviceId} from this computer.`);
+      break;
+    }
+    default:
+      console.log(usage);
+      process.exitCode = 1;
+  }
+}
+
+main().catch((error) => {
+  console.error(`replica-bridge: ${(error         ).message}`);
+  process.exit(1);
+});

package/src/bridge/pair.js

@@ -0,0 +1,137 @@
+// replica-bridge pair: shows a QR code and a pairing code, waits for a signed-in phone to claim it, checks the claim
+// and approves it. A QR claim carries an HMAC made with the secret only the QR code holds; a typed-code claim has
+// none, so the person at the computer compares the six-digit safety code. The first claim binds this computer to
+// the phone's account, so it is always confirmed here; later QR claims from the same account go through by themselves.
+import crypto from "node:crypto";
+import readline from "node:readline/promises";
+import QRCode from "qrcode";
+import {
+  b64url, buildPairingLink, formatCode, fromB64url, safetyCode, secretHash, verifyPairingProof,
+} from "../protocol.js";
+import { relayRequest } from "../http.js";
+import { loadState, saveState } from "./state.js";
+                                              
+import { loadRelayConfig } from "../relay/config.js";
+
+/**
+ * The address the phone should use: the bridge's own setting, else (when the bridge reaches the relay on this
+ * machine) RELAY_PUBLIC_ORIGIN from the relay's env file, so a new tunnel address or domain is set in one place.
+ */
+export function publicRelayURL(state             )         {
+  if (state.publicRelay) return state.publicRelay;
+  const host = new URL(state.relay).hostname;
+  if (["127.0.0.1", "localhost", "[::1]"].includes(host)) return loadRelayConfig().publicOrigin ?? state.relay;
+  return state.relay;
+}
+
+/** What the bridge knows about a claim when it asks the person at the computer. */
+                            
+                
+                   
+                     
+                      
+                                                         
+                            
+ 
+
+                              
+                                                                       
+                   
+                                                                                                       
+                
+                         
+                   
+                                                                                     
+                                                
+                                              
+                                                  
+                  
+ 
+
+                     
+                                                                                                                             
+                                                                      
+ 
+
+async function askTerminal(claim           )                   {
+  if (!process.stdin.isTTY) {
+    console.log("No terminal to confirm on; rejecting. Run pair in a terminal, or pass --yes to approve the first claim.");
+    return false;
+  }
+  const who = claim.provider === "github" ? `GitHub user @${claim.login}` : `${claim.login} (${claim.provider})`;
+  const lines = [`${who} wants to use Codex on this computer from "${claim.deviceName}".`];
+  if (claim.firstClaim) lines.push("This makes the computer theirs: from now on only their account can pair with it.");
+  if (claim.safetyCode) lines.push(`They typed the code instead of scanning it. Safety code: ${claim.safetyCode} — it must match the phone.`);
+  console.log(lines.join("\n"));
+  const prompt = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return /^y(es)?$/i.test((await prompt.question("Allow? [y/N] ")).trim());
+  } finally {
+    prompt.close();
+  }
+}
+
+export async function pair(options             )                                                             {
+  const state = loadState();
+  const say = (text        ) => { if (!options.quiet) console.log(text); };
+  const secret = crypto.randomBytes(32);
+  const { code, expiresAt } = await relayRequest                                     (state.relay, "POST", "/v1/pair/start", { token: state.hostToken, body: { secretHash: secretHash(secret) } });
+  const link = buildPairingLink({ relay: publicRelayURL(state), hostId: state.hostId, hostPublicKey: fromB64url(state.hostPublicKey), code, secret, hostName: state.hostName });
+  options.onLink?.(link, code);
+  if (!options.quiet) {
+    console.log(await QRCode.toString(link, { type: "terminal", small: true, errorCorrectionLevel: "M" }));
+    console.log(`Scan with the app (远程 › 添加连接 › 配对新设备) or the iPhone camera, or type the code: ${formatCode(code)}`);
+    console.log(`Link: ${link}`);
+    console.log(`Expires at ${new Date(expiresAt).toLocaleTimeString()}. Waiting for the phone…`);
+  }
+  if (options.pngPath) {
+    await QRCode.toFile(options.pngPath, link, { width: 512, errorCorrectionLevel: "M" });
+    say(`QR code also saved to ${options.pngPath}`);
+  }
+
+  const deadline = Math.min(expiresAt, Date.now() + options.timeoutSeconds * 1000);
+  let claim                   = null;
+  while (Date.now() < deadline) {
+    const view = await relayRequest           (state.relay, "GET", `/v1/pair/claim?code=${code}`, { token: state.hostToken });
+    if (view.status === "claimed") { claim = view; break; }
+    if (view.status !== "open") throw new Error(`pairing ${view.status}`);
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+  }
+  if (!claim?.devicePublicKey || !claim.deviceId || !claim.account) throw new Error("pairing timed out");
+
+  const devicePublicKey = fromB64url(claim.devicePublicKey);
+  const info            = {
+    login: claim.account.login, provider: claim.account.provider, deviceName: claim.deviceName ?? "iPhone",
+    firstClaim: claim.firstClaim === true, safetyCode: claim.proof ? null : safetyCode(fromB64url(state.hostPublicKey), devicePublicKey),
+  };
+  const decide = options.decide ?? askTerminal;
+  let approve         ;
+  if (claim.proof && !verifyPairingProof(secret, code, devicePublicKey, fromB64url(claim.proof))) {
+    say("The claim's proof does not match this QR code; rejecting it.");
+    approve = false;
+  } else if (info.safetyCode || options.confirm || (info.firstClaim && !options.yes)) {
+    approve = await decide(info);
+  } else {
+    approve = true;
+  }
+  if (!approve) {
+    await relayRequest(state.relay, "POST", "/v1/pair/approve", { token: state.hostToken, body: { code, approve: false } });
+    throw new Error("pairing rejected");
+  }
+  // Save the phone's key before approving: the phone may connect the moment the relay says yes.
+  const withDevice = (s             )              => ({
+    ...s,
+    owner: s.owner ?? { login: info.login, provider: info.provider },
+    devices: [...s.devices.filter((d) => d.deviceId !== claim .deviceId), { deviceId: claim .deviceId , publicKey: b64url(devicePublicKey), name: info.deviceName, login: info.login, pairedAt: new Date().toISOString() }],
+  });
+  saveState(withDevice(loadState()));
+  try {
+    await relayRequest(state.relay, "POST", "/v1/pair/approve", { token: state.hostToken, body: { code, approve: true } });
+  } catch (error) {
+    const latest = loadState();
+    saveState({ ...latest, owner: state.owner, devices: latest.devices.filter((d) => d.deviceId !== claim .deviceId) });
+    throw error;
+  }
+  say(`Paired "${info.deviceName}" of ${info.login}.`);
+  return { deviceId: claim.deviceId, name: info.deviceName, login: info.login };
+}

package/src/bridge/service.js

@@ -0,0 +1,307 @@
+// replica-bridge start: keeps one WebSocket to the relay and, for each phone stream, one `codex app-server proxy`
+// speaking WebSocket to the long-lived app-server, exactly as the app's SSH path does (Sources/Core/CodexSession.swift).
+// The bridge does not run or configure Codex: when no app-server answers it asks Codex to start its own managed
+// one (`codex app-server daemon start`). A stream outlives the phone's connection for `streamTTL`, buffering what
+// the app-server says, so a phone that drops off the network resumes where it left off.
+import { spawn } from "node:child_process";
+                                                       
+import crypto from "node:crypto";
+import os from "node:os";
+import { Duplex } from "node:stream";
+import { WebSocket } from "ws";
+                                  
+import {
+  CloseCode, FrameCipher, MAX_FRAME_BYTES, StreamBuffer, b64url, fromB64url, generateKeyPair, hostSessionKeys,
+} from "../protocol.js";
+                                                                            
+import { relaySocketURL } from "../http.js";
+import { hostKeyPair, loadState } from "./state.js";
+                                              
+
+                                 
+                                                   
+                     
+     
+                                                                                                                    
+                                                                                                                
+     
+                       
+                            
+                                  
+ 
+
+                  
+             
+                   
+                       
+                    
+                   
+                    
+                                
+                                  
+ 
+
+                
+             
+                   
+                             
+                        
+                                                                                           
+                       
+ 
+
+export class BridgeService {
+          relay                   = null;
+                   conns = new Map              ();
+                   streams = new Map                ();
+          stopped = false;
+          retry = 0;
+                   log                           ;
+
+                   options                ;
+
+  constructor(options                 = {}) {
+    this.options = options;
+    this.log = options.log ?? ((message) => console.log(`${new Date().toISOString()} ${message}`));
+  }
+
+  start() {
+    this.connectRelay();
+  }
+
+  stop() {
+    this.stopped = true;
+    this.relay?.close();
+    for (const stream of this.streams.values()) this.endStream(stream, "bridge stopped");
+  }
+
+  get streamCount() { return this.streams.size; }
+
+  // MARK: - Relay connection
+
+          connectRelay() {
+    const state = loadState();
+    const ws = new WebSocket(relaySocketURL(state.relay, "/v1/host"), { headers: { authorization: `Bearer ${state.hostToken}` }, maxPayload: MAX_FRAME_BYTES + 4096, perMessageDeflate: false });
+    this.relay = ws;
+    ws.on("open", () => { this.retry = 0; this.log(`connected to relay ${state.relay} as ${state.hostId}`); });
+    ws.on("message", (data         ) => {
+      let envelope              ;
+      try { envelope = JSON.parse(data.toString()); } catch { return; }
+      this.onEnvelope(envelope);
+    });
+    ws.on("unexpected-response", (_req, res) => this.log(`relay refused the host connection: HTTP ${res.statusCode}`));
+    ws.on("error", (error) => this.log(`relay connection error: ${error.message}`));
+    ws.on("close", (code) => {
+      for (const conn of this.conns.values()) this.detach(conn);
+      this.conns.clear();
+      if (this.stopped) return;
+      if (code === CloseCode.replaced) this.log("another bridge with the same identity connected; reconnecting anyway");
+      const delay = Math.min(30_000, 1000 * 2 ** this.retry++);
+      setTimeout(() => this.connectRelay(), delay);
+    });
+  }
+
+          sendEnvelope(envelope              ) {
+    if (this.relay?.readyState === WebSocket.OPEN) this.relay.send(JSON.stringify(envelope));
+  }
+
+          sendFrame(conn      , frame           ) {
+    this.sendEnvelope({ type: "frame", conn: conn.id, frame });
+  }
+
+          sendInner(conn      , message              ) {
+    if (conn.cipher) this.sendFrame(conn, conn.cipher.sealFrame(message));
+  }
+
+          closeConn(conn      , reason        ) {
+    this.sendEnvelope({ type: "close", conn: conn.id, reason });
+    this.detach(conn);
+    this.conns.delete(conn.id);
+  }
+
+          onEnvelope(envelope              ) {
+    if (envelope.type === "open") {
+      this.conns.set(envelope.conn, { id: envelope.conn, deviceId: envelope.device, cipher: null, stream: null, queue: Promise.resolve() });
+    } else if (envelope.type === "close") {
+      const conn = this.conns.get(envelope.conn);
+      if (conn) { this.detach(conn); this.conns.delete(conn.id); }
+    } else if (envelope.type === "frame") {
+      const conn = this.conns.get(envelope.conn);
+      if (!conn) return;
+      conn.queue = conn.queue.then(() => this.onFrame(conn, envelope.frame)).catch((error) => {
+        this.log(`connection ${conn.id} from ${conn.deviceId}: ${(error         ).message}`);
+        this.sendFrame(conn, { type: "error", code: "protocol", message: "the bridge could not handle a frame" });
+        this.closeConn(conn, "protocol error");
+      });
+    }
+  }
+
+  /** Looks the device up in state.json; a device paired a moment ago may not be saved yet, so look again briefly. */
+          async pairedDevice(deviceId        )                                                            {
+    for (let attempt = 0; attempt < 6; attempt++) {
+      const state = loadState();
+      const device = state.devices.find((d) => d.deviceId === deviceId);
+      if (device) return { state, publicKey: fromB64url(device.publicKey) };
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+    return null;
+  }
+
+          async onFrame(conn      , frame           ) {
+    if (frame.type === "hello") {
+      if (conn.cipher) throw new Error("second hello");
+      const paired = await this.pairedDevice(conn.deviceId);
+      if (!paired) {
+        this.sendFrame(conn, { type: "error", code: "unknown_device", message: "this phone is not paired with this computer" });
+        return this.closeConn(conn, "unknown device");
+      }
+      const deviceEphemeral = fromB64url(frame.e);
+      if (deviceEphemeral.length !== 32) throw new Error("bad ephemeral key");
+      const ephemeral = generateKeyPair();
+      const keys = hostSessionKeys(hostKeyPair(paired.state), ephemeral, paired.publicKey, deviceEphemeral);
+      conn.cipher = new FrameCipher(keys.hostToDevice, keys.deviceToHost, keys.transcript);
+      this.sendFrame(conn, { type: "welcome", v: 1, e: b64url(ephemeral.publicKey) });
+      return;
+    }
+    if (frame.type !== "data" || !conn.cipher) throw new Error(`unexpected ${frame.type} frame`);
+    const message = conn.cipher.openFrame(frame);
+    if (message.t === "resume") {
+      if (conn.stream) throw new Error("second resume");
+      await this.resume(conn, message.stream, message.ack);
+    } else if (message.t === "msg") {
+      const stream = conn.stream;
+      if (!stream) throw new Error("message before resume");
+      if (!stream.in.accept(message.seq)) return;
+      if (stream.appServer.readyState === WebSocket.OPEN) stream.appServer.send(message.line);
+      this.scheduleAck(stream);
+    } else if (message.t === "ack") {
+      conn.stream?.out.ack(message.seq);
+    }
+  }
+
+  // MARK: - Streams
+
+          async resume(conn      , streamId               , peerAck        ) {
+    let stream = streamId ? this.streams.get(streamId) : undefined;
+    const resumed = !!stream && stream.deviceId === conn.deviceId;
+    if (!resumed) {
+      stream = await this.openStream(conn.deviceId);
+    }
+    const s = stream ;
+    if (s.conn && s.conn !== conn) this.closeConn(s.conn, "resumed elsewhere");
+    if (s.expiry) { clearTimeout(s.expiry); s.expiry = null; }
+    s.conn = conn;
+    conn.stream = s;
+    this.sendInner(conn, { t: "ready", stream: s.id, resumed, ack: s.in.received });
+    // A new stream's sequence numbers start over, whatever the phone acknowledged on its old one.
+    const after = resumed ? peerAck : 0;
+    s.out.ack(after);
+    for (const item of s.out.pending(after)) this.sendInner(conn, { t: "msg", seq: item.seq, line: item.line });
+    this.log(`${resumed ? "resumed" : "opened"} stream ${s.id} for ${conn.deviceId}`);
+  }
+
+          async openStream(deviceId        )                  {
+    const appServer = await this.connectAppServer();
+    const stream         = { id: crypto.randomBytes(12).toString("base64url"), deviceId, appServer, out: new StreamBuffer(), in: new StreamBuffer(), conn: null, expiry: null, ackTimer: null };
+    this.streams.set(stream.id, stream);
+    appServer.on("message", (data         ) => {
+      let item;
+      try { item = stream.out.push(data.toString()); } catch { return this.endStream(stream, "the phone stayed away too long and the buffer filled up"); }
+      if (stream.conn) this.sendInner(stream.conn, { t: "msg", seq: item.seq, line: item.line });
+    });
+    appServer.on("close", () => this.endStream(stream, "codex app-server closed the connection"));
+    appServer.on("error", (error) => this.log(`app-server stream ${stream.id}: ${error.message}`));
+    return stream;
+  }
+
+          scheduleAck(stream        ) {
+    if (stream.ackTimer) return;
+    stream.ackTimer = setTimeout(() => {
+      stream.ackTimer = null;
+      if (stream.conn) this.sendInner(stream.conn, { t: "ack", seq: stream.in.received });
+    }, 50);
+  }
+
+          detach(conn      ) {
+    const stream = conn.stream;
+    conn.stream = null;
+    if (!stream || stream.conn !== conn) return;
+    stream.conn = null;
+    const ttl = (this.options.streamTTLSeconds ?? 1800) * 1000;
+    stream.expiry = setTimeout(() => this.endStream(stream, "the phone did not come back in time"), ttl);
+  }
+
+          endStream(stream        , reason        ) {
+    if (!this.streams.delete(stream.id)) return;
+    if (stream.expiry) clearTimeout(stream.expiry);
+    if (stream.ackTimer) clearTimeout(stream.ackTimer);
+    if (stream.conn) {
+      this.sendInner(stream.conn, { t: "closed", reason });
+      this.closeConn(stream.conn, reason);
+    }
+    stream.appServer.close();
+    this.log(`closed stream ${stream.id}: ${reason}`);
+  }
+
+  // MARK: - codex app-server
+
+  /**
+   * One `codex app-server proxy` per stream, with WebSocket over its stdin and stdout. The proxy only relays bytes to
+   * the app-server's control socket, wherever Codex keeps it; it exits at once when no app-server is running.
+   */
+          openProxy()                     {
+    return new Promise((resolve, reject) => {
+      const child               = spawn(this.options.codexPath ?? "codex", ["app-server", "proxy"], { stdio: ["pipe", "pipe", "pipe"] });
+      let stderr = "";
+      child.stderr .on("data", (chunk) => { stderr = (stderr + chunk).slice(-2000); });
+      const pipe = Duplex.from({ readable: child.stdout , writable: child.stdin  })                                    ;
+      // The HTTP client that carries the WebSocket handshake tunes its socket; a pipe has nothing to tune.
+      for (const name of ["setNoDelay", "setKeepAlive", "setTimeout", "ref", "unref"]) pipe[name] = () => pipe;
+      const ws = new WebSocket("ws://localhost/", { createConnection: () => pipe         , perMessageDeflate: false, maxPayload: MAX_FRAME_BYTES });
+      const fail = (why        ) => { ws.removeAllListeners("open"); child.kill(); reject(new Error(why)); };
+      child.once("error", (error) => fail(`could not run codex: ${error.message}`));
+      child.once("exit", (code) => { if (ws.readyState !== WebSocket.OPEN) fail(`codex app-server proxy exited (${code})${stderr ? `: ${stderr.trim()}` : ""}`); });
+      ws.once("error", (error) => { if (ws.readyState !== WebSocket.OPEN) fail(error.message); });
+      ws.once("open", () => {
+        ws.on("close", () => child.kill());
+        resolve(ws);
+      });
+    });
+  }
+
+  /** Runs a command to completion; true when it exits 0 within 30 s. Output is dropped (an rc file may print). */
+          run(command        , args          )                   {
+    return new Promise((resolve, reject) => {
+      const child = spawn(command, args, { stdio: "ignore" });
+      const timer = setTimeout(() => { child.kill(); resolve(false); }, 30_000);
+      child.once("error", (error) => { clearTimeout(timer); reject(error); });
+      child.once("exit", (code) => { clearTimeout(timer); resolve(code === 0); });
+    });
+  }
+
+          async connectAppServer()                     {
+    try {
+      return await this.openProxy();
+    } catch (error) {
+      this.log(`no app-server answered (${(error         ).message}); asking Codex to start its daemon`);
+    }
+    // Codex manages its long-lived app-server itself (start, updates, socket); the bridge only asks for it. However
+    // people configure Codex (config.toml, auth.json, cc-switch, keys exported in their shell rc), the daemon should
+    // see what their terminal sees, so ask through their login shell; fall back to a direct start.
+    const codex = this.options.codexPath ?? "codex";
+    // launchd services may have no SHELL; the account's login shell is the same answer.
+    const shell = process.env.SHELL || os.userInfo().shell;
+    const started = this.options.loginShell !== false && shell
+      ? await this.run(shell, ["-lic", 'exec "$0" app-server daemon start', codex]).catch(() => false)
+      : false;
+    if (!started && !(await this.run(codex, ["app-server", "daemon", "start"]).catch(() => false))) {
+      throw new Error("codex app-server daemon start failed");
+    }
+    let last               = null;
+    for (let attempt = 0; attempt < 40; attempt++) {
+      try { return await this.openProxy(); } catch (error) { last = error         ; }
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    throw new Error(`codex app-server did not come up: ${last?.message}`);
+  }
+}

package/src/bridge/state.js

@@ -0,0 +1,44 @@
+// The bridge's local identity and paired devices, in ~/.config/replica-bridge/state.json (mode 600).
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fromB64url, keyPairFromPrivate } from "../protocol.js";
+                                              
+
+                                                                                                                     
+
+                              
+                                                                                                             
+                
+                                                                       
+                       
+                 
+                    
+                   
+                                                                                   
+                                              
+                         
+                        
+                          
+ 
+
+export const bridgeHome = () => process.env.REPLICA_BRIDGE_HOME ?? path.join(os.homedir(), ".config", "replica-bridge");
+const statePath = () => path.join(bridgeHome(), "state.json");
+
+export function loadState()              {
+  try {
+    return JSON.parse(fs.readFileSync(statePath(), "utf8"))               ;
+  } catch (error) {
+    if ((error                         ).code === "ENOENT") throw new Error(`not set up yet: run "replica-bridge init" first (${statePath()})`);
+    throw error;
+  }
+}
+
+export function saveState(state             ) {
+  fs.mkdirSync(bridgeHome(), { recursive: true, mode: 0o700 });
+  const temporary = `${statePath()}.${process.pid}.part`;
+  fs.writeFileSync(temporary, JSON.stringify(state, null, 2) + "\n", { mode: 0o600 });
+  fs.renameSync(temporary, statePath());
+}
+
+export const hostKeyPair = (state             )          => keyPairFromPrivate(fromB64url(state.hostPrivateKey));

package/src/http.js

@@ -0,0 +1,32 @@
+// Small JSON client for the relay's HTTP endpoints, shared by the bridge and the test phone.
+
+export class RelayHTTPError extends Error {
+           status        ;
+           code        ;
+  constructor(status        , code        , message        ) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export async function relayRequest   (base        , method        , path        , options                                     = {})             {
+  const url = new URL(path.replace(/^\//, ""), base.endsWith("/") ? base : `${base}/`);
+  const response = await fetch(url, {
+    method,
+    headers: { ...(options.body !== undefined ? { "content-type": "application/json" } : {}), ...(options.token ? { authorization: `Bearer ${options.token}` } : {}) },
+    body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+  });
+  const text = await response.text();
+  let value                          = {};
+  try { value = JSON.parse(text); } catch { /* not JSON */ }
+  if (!response.ok) throw new RelayHTTPError(response.status, String(value.error ?? response.status), String(value.message ?? text.slice(0, 200)));
+  return value     ;
+}
+
+/** http(s)://relay/prefix + /v1/host → ws(s)://relay/prefix/v1/host */
+export function relaySocketURL(base        , path        )         {
+  const url = new URL(path.replace(/^\//, ""), base.endsWith("/") ? base : `${base}/`);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  return url.toString();
+}

package/src/protocol.js

@@ -0,0 +1,262 @@
+// Shared protocol for replica-relay, replica-bridge and the test phone (Relay/PROTOCOL.md).
+// Everything here is plain Node: X25519, HKDF-SHA256, ChaCha20-Poly1305 and HMAC-SHA256 match CryptoKit's
+// Curve25519.KeyAgreement, HKDF<SHA256>, ChaChaPoly and HMAC<SHA256>, so the Swift side can follow the same steps.
+import crypto from "node:crypto";
+
+export const PROTOCOL = "chatreplica-relay-v1";
+export const LINK_SCHEME = "chatreplica:";
+/** Pairing codes avoid 0/O, 1/I/L and U so they survive being read aloud or typed. */
+export const CODE_ALPHABET = "23456789ABCDEFGHJKMNPQRSTVWXYZ";
+export const CODE_LENGTH = 8;
+export const MAX_FRAME_BYTES = 16 * 1024 * 1024;
+
+export const b64url = (data            )         => Buffer.from(data).toString("base64url");
+export const fromB64url = (text        )         => Buffer.from(text, "base64url");
+export const sha256 = (...parts              )         => {
+  const hash = crypto.createHash("sha256");
+  for (const part of parts) hash.update(part);
+  return hash.digest();
+};
+export const randomToken = ()         => b64url(crypto.randomBytes(32));
+export const tokenHash = (token        )         => sha256(Buffer.from(token, "utf8")).toString("hex");
+
+export function randomCode()         {
+  let code = "";
+  while (code.length < CODE_LENGTH) {
+    const byte = crypto.randomBytes(1)[0];
+    if (byte < 240) code += CODE_ALPHABET[byte % CODE_ALPHABET.length]; // 240 = 8 * 30, no modulo bias
+  }
+  return code;
+}
+
+/** Uppercases and drops spaces and dashes, so "abcd-2345" and "ABCD 2345" find the same pairing. */
+export const normalizeCode = (code        )         => code.toUpperCase().replace(/[\s-]/g, "");
+export const formatCode = (code        )         => `${code.slice(0, 4)}-${code.slice(4)}`;
+
+// MARK: - X25519 keys as raw 32-byte values (what CryptoKit's rawRepresentation holds)
+
+const PKCS8_X25519_PREFIX = Buffer.from("302e020100300506032b656e04220420", "hex");
+const SPKI_X25519_PREFIX = Buffer.from("302a300506032b656e032100", "hex");
+
+                                                                  
+
+export function generateKeyPair()          {
+  return keyPairFromPrivate(crypto.randomBytes(32));
+}
+
+export function keyPairFromPrivate(privateKey        )          {
+  const key = crypto.createPrivateKey({ key: Buffer.concat([PKCS8_X25519_PREFIX, privateKey]), format: "der", type: "pkcs8" });
+  const spki = crypto.createPublicKey(key).export({ format: "der", type: "spki" });
+  return { privateKey, publicKey: Buffer.from(spki.subarray(SPKI_X25519_PREFIX.length)) };
+}
+
+export function dh(privateKey        , publicKey        )         {
+  if (publicKey.length !== 32) throw new Error("X25519 public keys are 32 bytes");
+  return crypto.diffieHellman({
+    privateKey: crypto.createPrivateKey({ key: Buffer.concat([PKCS8_X25519_PREFIX, privateKey]), format: "der", type: "pkcs8" }),
+    publicKey: crypto.createPublicKey({ key: Buffer.concat([SPKI_X25519_PREFIX, publicKey]), format: "der", type: "spki" }),
+  });
+}
+
+// MARK: - Pairing
+
+                              
+                
+                 
+                        
+               
+                 
+                    
+ 
+
+/** chatreplica://pair?v=1&r=<relay URL>&h=<hostId>&k=<host key>&c=<code>&s=<secret>&n=<host name> */
+export function buildPairingLink(link             )         {
+  const params = new URLSearchParams({ v: "1", r: link.relay, h: link.hostId, k: b64url(link.hostPublicKey), c: link.code, s: b64url(link.secret) });
+  if (link.hostName) params.set("n", link.hostName);
+  return `chatreplica://pair?${params}`;
+}
+
+export function parsePairingLink(text        )              {
+  const url = new URL(text.trim());
+  if (url.protocol !== LINK_SCHEME || url.hostname !== "pair") throw new Error("not a chatreplica://pair link");
+  const get = (name        ) => {
+    const value = url.searchParams.get(name);
+    if (!value) throw new Error(`pairing link is missing ${name}`);
+    return value;
+  };
+  if (get("v") !== "1") throw new Error("unsupported pairing link version");
+  const relay = new URL(get("r"));
+  if (relay.protocol !== "https:" && relay.protocol !== "http:") throw new Error("relay must be an http(s) URL");
+  const hostPublicKey = fromB64url(get("k"));
+  const secret = fromB64url(get("s"));
+  if (hostPublicKey.length !== 32 || secret.length !== 32) throw new Error("pairing link key or secret has the wrong length");
+  return { relay: get("r"), hostId: get("h"), hostPublicKey, code: normalizeCode(get("c")), secret, hostName: url.searchParams.get("n") ?? undefined };
+}
+
+/** What the relay keeps instead of the secret, so it cannot compute the proof itself. */
+export const secretHash = (secret        )         => b64url(sha256(secret));
+
+/** HMAC-SHA256(secret, PROTOCOL "|pair|" code devicePublicKey): proves the phone saw the QR code. */
+export function pairingProof(secret        , code        , devicePublicKey        )         {
+  return crypto.createHmac("sha256", secret).update(`${PROTOCOL}|pair|${normalizeCode(code)}`).update(devicePublicKey).digest();
+}
+
+export function verifyPairingProof(secret        , code        , devicePublicKey        , proof        )          {
+  const expected = pairingProof(secret, code, devicePublicKey);
+  return proof.length === expected.length && crypto.timingSafeEqual(proof, expected);
+}
+
+/** Six digits both screens show when pairing by typed code, where the phone got the host key from the relay. */
+export function safetyCode(hostPublicKey        , devicePublicKey        )         {
+  const digest = sha256(Buffer.from(`${PROTOCOL}|safety`), hostPublicKey, devicePublicKey);
+  return String(digest.readUInt32BE(0) % 1_000_000).padStart(6, "0");
+}
+
+// MARK: - Session handshake and frames
+
+                              
+                                                        
+                     
+                       
+                       
+ 
+
+/**
+ * Both static keys and both ephemeral keys go into the transcript; the shared secret mixes ee, es and se, so only the
+ * paired phone (device static key) talking to the real host (host static key) derives the same keys.
+ */
+export function deriveSessionKeys(args   
+                                                                                           
+                                     
+ )              {
+  const transcript = sha256(Buffer.from(PROTOCOL), args.hostStatic, args.deviceStatic, args.deviceEphemeral, args.hostEphemeral);
+  const okm = Buffer.from(crypto.hkdfSync("sha256", Buffer.concat([args.ee, args.es, args.se]), transcript, Buffer.from(`${PROTOCOL}|keys`), 64));
+  return { transcript, deviceToHost: okm.subarray(0, 32), hostToDevice: okm.subarray(32, 64) };
+}
+
+/** The phone's side: ee = DH(De, He), es = DH(De, Hs), se = DH(Ds, He). */
+export function deviceSessionKeys(device         , deviceEphemeral         , hostStatic        , hostEphemeral        )              {
+  return deriveSessionKeys({
+    hostStatic, deviceStatic: device.publicKey, deviceEphemeral: deviceEphemeral.publicKey, hostEphemeral,
+    ee: dh(deviceEphemeral.privateKey, hostEphemeral), es: dh(deviceEphemeral.privateKey, hostStatic), se: dh(device.privateKey, hostEphemeral),
+  });
+}
+
+/** The host's side of the same three DH values. */
+export function hostSessionKeys(host         , hostEphemeral         , deviceStatic        , deviceEphemeral        )              {
+  return deriveSessionKeys({
+    hostStatic: host.publicKey, deviceStatic, deviceEphemeral, hostEphemeral: hostEphemeral.publicKey,
+    ee: dh(hostEphemeral.privateKey, deviceEphemeral), es: dh(host.privateKey, deviceEphemeral), se: dh(hostEphemeral.privateKey, deviceStatic),
+  });
+}
+
+/** 96-bit nonce: four zero bytes, then the frame counter as a big-endian UInt64. */
+export function frameNonce(counter        )         {
+  const nonce = Buffer.alloc(12);
+  nonce.writeBigUInt64BE(BigInt(counter), 4);
+  return nonce;
+}
+
+export function seal(key        , counter        , aad        , plaintext        )         {
+  const cipher = crypto.createCipheriv("chacha20-poly1305", key, frameNonce(counter), { authTagLength: 16 });
+  cipher.setAAD(aad, { plaintextLength: plaintext.length });
+  return Buffer.concat([cipher.update(plaintext), cipher.final(), cipher.getAuthTag()]);
+}
+
+export function open(key        , counter        , aad        , sealed        )         {
+  if (sealed.length < 16) throw new Error("frame too short");
+  const decipher = crypto.createDecipheriv("chacha20-poly1305", key, frameNonce(counter), { authTagLength: 16 });
+  decipher.setAAD(aad, { plaintextLength: sealed.length - 16 });
+  decipher.setAuthTag(sealed.subarray(sealed.length - 16));
+  return Buffer.concat([decipher.update(sealed.subarray(0, sealed.length - 16)), decipher.final()]);
+}
+
+/** One direction of an established session: counts frames and refuses gaps or replays. */
+export class FrameCipher {
+          sendCounter = 0;
+          receiveCounter = 0;
+                   sendKey        ;
+                   receiveKey        ;
+                   aad        ;
+  constructor(sendKey        , receiveKey        , aad        ) { this.sendKey = sendKey; this.receiveKey = receiveKey; this.aad = aad; }
+
+  sealFrame(message              )            {
+    const n = this.sendCounter++;
+    return { type: "data", n, c: b64url(seal(this.sendKey, n, this.aad, Buffer.from(JSON.stringify(message), "utf8"))) };
+  }
+
+  openFrame(frame                          )               {
+    if (frame.n !== this.receiveCounter) throw new Error(`frame ${frame.n} out of order (expected ${this.receiveCounter})`);
+    const plaintext = open(this.receiveKey, frame.n, this.aad, fromB64url(frame.c));
+    this.receiveCounter++;
+    return JSON.parse(plaintext.toString("utf8"))                ;
+  }
+}
+
+/** What travels between the phone and the host through the relay; the relay only sees these. */
+                       
+                                      
+                                        
+                                          
+                                                     
+
+/** What is inside a data frame. */
+                          
+                                                       
+                                                                 
+                                           
+                             
+                                    
+
+/** Relay ↔ host multiplexing: one host WebSocket carries every phone connection. */
+                          
+                                                  
+                                                    
+                                                      
+
+/** WebSocket close codes the relay and the bridge use. */
+export const CloseCode = {
+  hostOffline: 4404,
+  revoked: 4403,
+  replaced: 4409,
+  protocolError: 4400,
+  streamGone: 4410,
+}         ;
+
+/**
+ * Keeps one direction of a stream's messages until the peer acknowledges them, so a reconnect can resend exactly
+ * what was lost. Sequence numbers start at 1; `received` is the highest contiguous seq taken from the peer.
+ */
+export class StreamBuffer {
+  nextSeq = 1;
+  received = 0;
+          unacked                                                = [];
+          bytes = 0;
+
+                   maxBytes        ;
+  constructor(maxBytes = 32 * 1024 * 1024) { this.maxBytes = maxBytes; }
+
+  push(line        )                                {
+    const item = { seq: this.nextSeq++, line, size: Buffer.byteLength(line) };
+    this.unacked.push(item);
+    this.bytes += item.size;
+    if (this.bytes > this.maxBytes) throw new Error("unacknowledged buffer full");
+    return item;
+  }
+
+  ack(seq        ) {
+    while (this.unacked.length && this.unacked[0].seq <= seq) this.bytes -= this.unacked.shift() .size;
+  }
+
+  pending(after        )                                  {
+    return this.unacked.filter((item) => item.seq > after);
+  }
+
+  /** True when the line is new; duplicates from a resend are dropped. Gaps cannot happen on one ordered socket. */
+  accept(seq        )          {
+    if (seq <= this.received) return false;
+    if (seq !== this.received + 1) throw new Error(`message ${seq} skips ahead of ${this.received}`);
+    this.received = seq;
+    return true;
+  }
+}

package/src/relay/config.js

@@ -0,0 +1,76 @@
+// Reads ~/.config/replica-relay/relay.env (Relay/deploy/relay.env.example). Real environment variables win over
+// the file, so a systemd Environment= line or a one-off `RELAY_PORT=… node …` still works.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** RELAY_ENV points somewhere else (the quick-tunnel script and the tests use it). */
+export const defaultEnvPath = () => process.env.RELAY_ENV ?? path.join(os.homedir(), ".config", "replica-relay", "relay.env");
+
+export function readEnvFile(file        )                         {
+  let text        ;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch (error) {
+    if ((error                         ).code === "ENOENT") return {};
+    throw error;
+  }
+  const values                         = {};
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq < 1) continue;
+    let value = line.slice(eq + 1).trim();
+    if (/^(".*"|'.*')$/.test(value)) value = value.slice(1, -1);
+    values[line.slice(0, eq).trim()] = value;
+  }
+  return values;
+}
+
+                              
+                 
+               
+                              
+                      
+                  
+                                                                          
+                    
+                                
+                                    
+                                   
+                             
+ 
+
+/** "github:583231, 12345, *" → ["583231", "12345", "*"]; anything that is not a numeric id or * is refused. */
+export function parseAllowedIds(text        )           {
+  return text.split(",").map((item) => item.trim()).filter(Boolean).map((item) => {
+    const id = item.replace(/^github:/, "");
+    if (id !== "*" && !/^[0-9]{1,20}$/.test(id)) throw new Error(`GITHUB_ALLOWED_USERS takes numeric GitHub ids (github:123) or *, not "${item}"`);
+    return id;
+  });
+}
+
+const expandHome = (value        ) => (value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value);
+
+export function loadRelayConfig(envPath = defaultEnvPath())              {
+  const file = readEnvFile(envPath);
+  const get = (name        ) => {
+    const value = process.env[name] ?? file[name];
+    return value === undefined || value === "" ? null : value;
+  };
+  const origin = get("RELAY_PUBLIC_ORIGIN");
+  if (origin && !/^https?:\/\/[^/]+\/?$/.test(origin)) throw new Error(`RELAY_PUBLIC_ORIGIN must look like https://host[:port], got ${origin}`);
+  return {
+    listen: get("RELAY_LISTEN") ?? "127.0.0.1",
+    port: Number(get("RELAY_PORT") ?? 8790),
+    publicOrigin: origin?.replace(/\/$/, "") ?? null,
+    trustProxy: get("RELAY_TRUST_PROXY") === "1",
+    dataDir: expandHome(get("RELAY_DATA_DIR") ?? "~/.local/share/replica-relay"),
+    devLogin: get("RELAY_DEV_LOGIN") === "1",
+    githubClientId: get("GITHUB_CLIENT_ID"),
+    githubClientSecret: get("GITHUB_CLIENT_SECRET"),
+    githubCallbackUrl: get("GITHUB_CALLBACK_URL"),
+    githubAllowedIds: parseAllowedIds(get("GITHUB_ALLOWED_USERS") ?? ""),
+  };
+}