replica-bridge 0.0.0-stage → 0.2.0

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,319 @@
+// 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 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 { killCommand, spawnCommand } from "./command.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) => {
+      if (ws !== this.relay) return; // a socket this bridge already replaced itself
+      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 for this computer connected to the relay, which keeps only the newest; stopping this one");
+        this.stop();
+        this.options.onReplaced?.();
+        return;
+      }
+      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               = spawnCommand(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"); killCommand(child); 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", () => killCommand(child));
+        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 = spawnCommand(command, args, { stdio: "ignore" });
+      const timer = setTimeout(() => { killCommand(child); 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. Windows has no login shell
+    // (a SHELL from Git Bash is a POSIX path Node cannot run), so Codex is asked directly there.
+    const shell = process.platform === "win32" ? null : 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();
+}