replica-bridge 0.3.10 → 0.3.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replica-bridge",
-  "version": "0.3.10",
+  "version": "0.3.13",
   "description": "Lets the ChatReplica iPhone app use Codex on this computer through a relay, end-to-end encrypted.",
   "type": "module",
   "bin": {

package/src/bridge/board.js

@@ -0,0 +1,201 @@
+// The optional 任务 board (PROTOCOL.md "看板"): reads AgensWork's agens-backend, which only listens on this computer, for
+// a phone that asked. The bridge does not start the backend or care how it started: it knows a port, and a computer
+// where nothing answers there simply has no board. Reads and writes are short allowlists, and the only background traffic
+// is one poll of /v1/changes while a phone is subscribed, because reading the lists counts as the user having seen them.
+// The bridge stays thin: it checks the shape of a write and leaves what it means to the backend, whose status and body
+// (REC_NOT_FOUND, REC_STATE_CONFLICT, …) go back to the phone unchanged.
+                                                              
+
+/** agens-backend's default port, which its own AGENS_BACKEND_PORT changes. */
+export const DEFAULT_BOARD_PORT = 4753;
+/** agens-backend's own page polls every 10 s. */
+const DEFAULT_POLL_SECONDS = 10;
+/** Past this the backend is treated as gone, so a hung one cannot hold a phone waiting. */
+const READ_TIMEOUT_MS = 5000;
+/** Well under RELAY_REPLY_LIMIT, since the bridge sends board answers in one frame. */
+const BODY_MAX_BYTES = 8 * 1024 * 1024;
+const CHANGES_PAGE = 100;
+/** Stops a catch-up on a change log that never ends; the backend keeps 30 days of it. */
+const CATCH_UP_PAGES = 1000;
+
+/** The backend's own cap on a request body (agens-backend src/http.mjs BODY_MAX). */
+export const POST_BODY_MAX_BYTES = 16 * 1024;
+const REC = "[A-Za-z0-9_.:-]+";
+
+/**
+ * GETs (#367). /session also writes TASK.md in the task's working folder, which is what 开工 asks for; /share and /me
+ * only read. Not /assist, /mcp, /search, /changes (the bridge's own poll) or anything under /ui.
+ */
+const READS = [/^\/v1\/status$/, /^\/v1\/today$/, /^\/v1\/recommendations$/, new RegExp(`^/v1/recommendations/${REC}$`),
+  new RegExp(`^/v1/recommendations/${REC}/(share|session)$`), /^\/v1\/me$/];
+
+/** POSTs (#367): a task's follow-up actions, cancelling its preparation note, and muting a conversation. Nothing else. */
+const WRITES = [new RegExp(`^/v1/recommendations/${REC}/actions$`), new RegExp(`^/v1/recommendations/${REC}/prep/cancel$`), /^\/v1\/me\/muted$/];
+/** agens-backend src/recs.mjs ACTIONS. */
+export const BOARD_ACTIONS = ["accept", "snooze", "delegate", "dismiss", "done", "reopen"]         ;
+
+function localTarget(path         )             {
+  if (typeof path !== "string" || !path.startsWith("/") || path.startsWith("//") || path.includes("\\")) return null;
+  let target     ;
+  try { target = new URL(path, "http://board.invalid"); } catch { return null; }
+  return target.origin === "http://board.invalid" ? target : null;
+}
+
+/** The path and query to read, or null when it is not on the allowlist. */
+export function allowedBoardPath(path         )                {
+  const target = localTarget(path);
+  if (!target || !READS.some((read) => read.test(target.pathname))) return null;
+  return target.pathname + target.search;
+}
+
+/**
+ * The path and body to POST, or why not. The path is one of WRITES with no query; the body is JSON text of an object
+ * within the backend's size cap (absent or empty means `{}`, for prep/cancel), and on /actions names a known action.
+ */
+export function allowedBoardPost(path         , body         )                                                                                       {
+  const target = localTarget(path);
+  if (!target || target.search || !WRITES.some((write) => write.test(target.pathname))) return { error: "not_allowed" };
+  if (body === undefined || body === "") body = "{}";
+  if (typeof body !== "string") return { error: "bad_body" };
+  if (Buffer.byteLength(body, "utf8") > POST_BODY_MAX_BYTES) return { error: "too_large" };
+  let value         ;
+  try { value = JSON.parse(body); } catch { return { error: "bad_body" }; }
+  if (!value || typeof value !== "object" || Array.isArray(value)) return { error: "bad_body" };
+  if (target.pathname.endsWith("/actions")) {
+    const action = (value                        ).action;
+    if (typeof action !== "string" || !(BOARD_ACTIONS                     ).includes(action)) return { error: "not_allowed" };
+  }
+  const sent = JSON.stringify(value);
+  // Rewriting can lengthen it (1e5 becomes 100000), and the backend counts what it receives.
+  if (Buffer.byteLength(sent, "utf8") > POST_BODY_MAX_BYTES) return { error: "too_large" };
+  return { path: target.pathname, body: sent };
+}
+
+/** The port from AGENS_BACKEND_PORT, the backend's own setting, when it names a real one. */
+export function boardPortFrom(env                    = process.env)         {
+  const port = Number(env.AGENS_BACKEND_PORT);
+  return Number.isInteger(port) && port > 0 && port <= 65535 ? port : DEFAULT_BOARD_PORT;
+}
+
+                               
+                
+                       
+ 
+
+export class BoardReader {
+                   port        ;
+                   pollMs        ;
+                   listeners = new Set                             ();
+          timer                        = null;
+          polling = false;
+  /** Where the change log was read to; null until a poll has found its end. */
+          after                = null;
+          up                 = null;
+  /** Bumped when polling stops, so a poll still on its way does not speak for the next round. */
+          round = 0;
+
+  constructor(options               = {}) {
+    this.port = options.port ?? boardPortFrom();
+    this.pollMs = (options.pollSeconds ?? DEFAULT_POLL_SECONDS) * 1000;
+  }
+
+  /** The fetch adds the Host header the backend insists on (127.0.0.1:<port>) and no Origin, as a local caller. */
+          fetch(pathAndQuery        , post         )                    {
+    return fetch(`http://127.0.0.1:${this.port}${pathAndQuery}`, {
+      redirect: "error", signal: AbortSignal.timeout(READ_TIMEOUT_MS),
+      ...(post === undefined ? {} : { method: "POST", headers: { "content-type": "application/json" }, body: post }),
+    });
+  }
+
+  read(path         )                       {
+    const allowed = allowedBoardPath(path);
+    return allowed ? this.answer(allowed) : Promise.resolve({ error: "not_allowed" });
+  }
+
+  /** Sent once and never retried: a write that timed out may still have happened, so the phone reads the task again. */
+  post(path         , body         )                       {
+    const allowed = allowedBoardPost(path, body);
+    return "error" in allowed ? Promise.resolve(allowed) : this.answer(allowed.path, allowed.body);
+  }
+
+  /** The backend's status and body as they are, errors included. */
+          async answer(pathAndQuery        , post         )                       {
+    try {
+      const response = await this.fetch(pathAndQuery, post);
+      const body = await response.text();
+      if (Buffer.byteLength(body, "utf8") > BODY_MAX_BYTES) return { error: "too_large" };
+      return { status: response.status, body };
+    } catch {
+      return { error: "no_board" };
+    }
+  }
+
+  /** Tells `listener` about the board until the returned function is called. Polls only while someone listens. */
+  subscribe(listener                             )             {
+    this.listeners.add(listener);
+    if (this.up !== null) listener({ t: "board/state", up: this.up });
+    if (!this.timer) {
+      this.timer = setInterval(() => void this.poll(), this.pollMs);
+      this.timer.unref();
+      void this.poll();
+    }
+    return () => {
+      this.listeners.delete(listener);
+      if (!this.listeners.size) this.stop();
+    };
+  }
+
+  stop() {
+    this.listeners.clear();
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    this.after = null;
+    this.up = null;
+    this.polling = false;
+    this.round++;
+  }
+
+          emit(event            ) {
+    for (const listener of this.listeners) listener(event);
+  }
+
+          async changes(after        )                                              {
+    const response = await this.fetch(`/v1/changes?after=${after}&limit=${CHANGES_PAGE}`);
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    const page = await response.json()                                       ;
+    if (!Array.isArray(page.items)) throw new Error("not a page of changes");
+    return { items: page.items, next: typeof page.next === "number" ? page.next : after };
+  }
+
+          async poll() {
+    if (this.polling) return;
+    this.polling = true;
+    const round = this.round;
+    let changed = false, up = true, after = this.after;
+    try {
+      // The first poll only finds the end of the log: what happened before someone was listening is not news.
+      if (after === null) {
+        after = 0;
+        for (let page = 0; page < CATCH_UP_PAGES; page++) {
+          const { items, next } = await this.changes(after);
+          after = next;
+          if (items.length < CHANGES_PAGE) break;
+        }
+      } else {
+        const { items, next } = await this.changes(after);
+        after = next;
+        changed = items.length > 0;
+      }
+    } catch {
+      up = false;
+    }
+    if (round !== this.round) return;
+    this.polling = false;
+    if (up) this.after = after;
+    if (up !== this.up) {
+      this.up = up;
+      this.emit({ t: "board/state", up });
+    }
+    if (changed) this.emit({ t: "board/changed" });
+  }
+}

package/src/bridge/install.js

@@ -9,7 +9,11 @@ import path from "node:path";
 import { spawnCommandSync } from "./command.js";
 import { bridgeHome } from "./state.js";
 
-export const PACKAGE_VERSION         = JSON.parse(fs.readFileSync(path.resolve(import.meta.dirname, "../../package.json"), "utf8")).version;
+/** Set by tools/build-embedded-bridge.ts: a single-file bundle has no package.json beside it. */
+                                                          
+export const PACKAGE_VERSION         = typeof EMBEDDED_BRIDGE_VERSION === "string"
+  ? EMBEDDED_BRIDGE_VERSION
+  : JSON.parse(fs.readFileSync(path.resolve(import.meta.dirname, "../../package.json"), "utf8")).version;
 
                                                                                                                                   
 
@@ -212,7 +216,7 @@ WantedBy=default.target
 function serviceEnv()                         {
   const env                         = {};
   for (const [key, value] of Object.entries(process.env)) {
-    if (value !== undefined && (key === "PATH" || key === "Path" || /^(CODEX_|REPLICA_|RELAY_ENV$)/.test(key)) && key !== "REPLICA_BRIDGE_LOG") env[key] = value;
+    if (value !== undefined && (key === "PATH" || key === "Path" || /^(CODEX_|REPLICA_|RELAY_ENV$|AGENS_BACKEND_PORT$)/.test(key)) && key !== "REPLICA_BRIDGE_LOG") env[key] = value;
   }
   for (const key of ["PATH", "Path"]) if (env[key]) env[key] = servicePATH(env[key]);
   env.REPLICA_BRIDGE_SERVICE = "1";

package/src/bridge/pair.js

@@ -46,6 +46,8 @@ export function publicRelayURL(state             )         {
                                               
                                                   
                   
+                                                                                                     
+                       
  
 
                      
@@ -100,6 +102,7 @@ export async function pair(options             )
 
   let claim                   = null;
   while (Date.now() < deadline) {
+    options.signal?.throwIfAborted();
     if (Date.now() >= expiresAt ) { await show(true); continue; }
     const view = await relayRequest           (state.relay, "GET", `/v1/pair/claim?code=${code }`, { token: state.hostToken });
     if (view.status === "claimed") { claim = view; break; }

package/src/bridge/service.js

@@ -14,6 +14,7 @@ import {
 } from "../protocol.js";
                                                                             
 import { relaySocketURL } from "../http.js";
+import { BoardReader } from "./board.js";
 import { killCommand, spawnCommand } from "./command.js";
 import { hostKeyPair, loadState } from "./state.js";
 import { annotateWriterError } from "./writer.js";
@@ -39,6 +40,23 @@ import { annotateWriterError } from "./writer.js";
                                                             
                                                                                                                           
                             
+     
+                                                                                                                 
+                                                                                                                  
+                                                                                       
+     
+                                                                    
+     
+                                                                                                                       
+                                                                                                                     
+     
+                                                         
+                                                                                                                      
+                                                  
+                                                                                                
+                     
+                                                                   
+                            
  
 
                   
@@ -67,6 +85,8 @@ import { annotateWriterError } from "./writer.js";
                         
                                                                                            
                        
+                                                   
+                                        
  
 
 export class BridgeService {
@@ -74,13 +94,16 @@ export class BridgeService {
                    conns = new Map              ();
                    streams = new Map                ();
           stopped = false;
+          retryTimer                        = null;
           retry = 0;
                    log                           ;
 
                    options                ;
+                   board             ;
 
   constructor(options                 = {}) {
     this.options = options;
+    this.board = new BoardReader({ port: options.boardPort, pollSeconds: options.boardPollSeconds });
     this.log = options.log ?? ((message) => console.log(`${new Date().toISOString()} ${message}`));
   }
 
@@ -90,7 +113,9 @@ export class BridgeService {
 
   stop() {
     this.stopped = true;
+    if (this.retryTimer) clearTimeout(this.retryTimer);
     this.relay?.close();
+    this.board.stop();
     for (const stream of this.streams.values()) this.endStream(stream, "bridge stopped");
   }
 
@@ -113,7 +138,7 @@ export class BridgeService {
     }, (this.options.relayPingSeconds ?? 30) * 1000);
     ws.on("pong", () => { answered = true; });
     ws.on("ping", () => { answered = true; });
-    ws.on("open", () => { answered = true; this.retry = 0; this.log(`connected to relay ${state.relay} as ${state.hostId}`); });
+    ws.on("open", () => { answered = true; this.retry = 0; this.log(`connected to relay ${state.relay} as ${state.hostId}`); this.options.onRelayConnected?.(true); });
     ws.on("message", (data         ) => {
       let envelope              ;
       try { envelope = JSON.parse(data.toString()); } catch { return; }
@@ -131,6 +156,7 @@ export class BridgeService {
     ws.on("close", (code) => {
       clearInterval(ping);
       if (ws !== this.relay) return; // a socket this bridge already replaced itself
+      this.options.onRelayConnected?.(false);
       for (const conn of this.conns.values()) this.detach(conn);
       this.conns.clear();
       if (this.stopped) return;
@@ -141,7 +167,7 @@ export class BridgeService {
         return;
       }
       const delay = Math.min(30_000, 1000 * 2 ** this.retry++);
-      setTimeout(() => this.connectRelay(), delay);
+      this.retryTimer = setTimeout(() => this.connectRelay(), delay);
     });
   }
 
@@ -173,7 +199,7 @@ export class BridgeService {
 
           onEnvelope(envelope              ) {
     if (envelope.type === "open") {
-      this.conns.set(envelope.conn, { id: envelope.conn, deviceId: envelope.device, cipher: null, stream: null, queue: Promise.resolve() });
+      this.conns.set(envelope.conn, { id: envelope.conn, deviceId: envelope.device, cipher: null, stream: null, queue: Promise.resolve(), boardUnsubscribe: null });
     } else if (envelope.type === "close") {
       const conn = this.conns.get(envelope.conn);
       if (conn) { this.detach(conn); this.conns.delete(conn.id); }
@@ -240,6 +266,16 @@ export class BridgeService {
       // The phone is done with this stream: stop its proxy now, so the app-server unloads the threads it followed and
       // the computer's other Codex apps can open them, rather than holding them for streamTTL.
       if (conn.stream) this.endStream(conn.stream, "the phone closed the stream");
+    } else if (message.t === "board/get") {
+      // Not awaited: a slow backend should not hold up the frames behind this one.
+      void this.board.read(message.path).then((answer) => this.sendInner(conn, { t: "board/res", id: message.id, ...answer }));
+    } else if (message.t === "board/post") {
+      void this.board.post(message.path, message.body).then((answer) => this.sendInner(conn, { t: "board/res", id: message.id, ...answer }));
+    } else if (message.t === "board/sub") {
+      conn.boardUnsubscribe ??= this.board.subscribe((event) => this.sendInner(conn, event));
+    } else if (message.t === "board/unsub") {
+      conn.boardUnsubscribe?.();
+      conn.boardUnsubscribe = null;
     }
   }
 
@@ -268,6 +304,17 @@ export class BridgeService {
     this.log(`${resumed ? "resumed" : "opened"} stream ${s.id} for ${conn.deviceId}`);
   }
 
+          withheldFromPhone(text        )          {
+    const forwards = this.options.forwardsAppServerRequest;
+    if (!forwards || text.length > MAX_REQUEST_CHARS_TO_INSPECT) return false;
+    try {
+      const { id, method } = JSON.parse(text);
+      return id !== undefined && typeof method === "string" && !forwards(method);
+    } catch {
+      return false;
+    }
+  }
+
           async openStream(deviceId        )                  {
     const { ws: appServer, frameBytes } = await this.connectAppServer();
     const stream         = {
@@ -277,6 +324,7 @@ export class BridgeService {
     this.streams.set(stream.id, stream);
     appServer.on("message", (data         ) => {
       const text = data.toString();
+      if (this.withheldFromPhone(text)) return;
       const segmented = stream.segmented;
       const fitted = fitLine(text, segmented ? REASSEMBLED_MAX_BYTES : RELAY_REPLY_LIMIT);
       if (fitted === null) return this.log(`stream ${stream.id}: dropped a ${text.length}-byte app-server notification too large for the relay`);
@@ -308,6 +356,8 @@ export class BridgeService {
   }
 
           detach(conn      ) {
+    conn.boardUnsubscribe?.();
+    conn.boardUnsubscribe = null;
     const stream = conn.stream;
     conn.stream = null;
     if (!stream || stream.conn !== conn) return;
@@ -357,10 +407,7 @@ export class BridgeService {
       // rather than the oversized message closing the app-server connection.
       const ws = new WebSocket("ws://localhost/", { createConnection: () => pipe         , perMessageDeflate: false, maxPayload: APP_SERVER_MAX_MESSAGE_BYTES });
       let frameBytes = APP_SERVER_FRAME_BYTES;
-      ws.once("upgrade", (res) => {
-        const advertised = Number(res.headers["x-codex-websocket-max-unfragmented-message-bytes"]);
-        if (Number.isInteger(advertised) && advertised >= 64 * 1024) frameBytes = advertised;
-      });
+      ws.once("upgrade", (res) => { frameBytes = advertisedFrameBytes(res.headers); });
       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()}` : ""}`); });
@@ -382,7 +429,21 @@ export class BridgeService {
     });
   }
 
+  /** A direct connection to the host's own app-server. */
+          async openEndpoint(endpoint                                                  )                                                 {
+    const { url, token } = await endpoint();
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(url, { headers: { authorization: `Bearer ${token}` }, perMessageDeflate: false, maxPayload: APP_SERVER_MAX_MESSAGE_BYTES });
+      let frameBytes = APP_SERVER_FRAME_BYTES;
+      ws.once("upgrade", (res) => { frameBytes = advertisedFrameBytes(res.headers); });
+      ws.once("error", (error) => { if (ws.readyState !== WebSocket.OPEN) reject(error); });
+      ws.once("open", () => resolve({ ws, frameBytes }));
+    });
+  }
+
           async connectAppServer()                                                 {
+    const endpoint = this.options.appServerEndpoint;
+    if (endpoint) return this.awaitAppServer(() => this.openEndpoint(endpoint), HOST_APP_SERVER_ATTEMPTS);
     try {
       return await this.openProxy();
     } catch (error) {
@@ -401,15 +462,30 @@ export class BridgeService {
     if (!started && !(await this.run(codex, ["app-server", "daemon", "start"]).catch(() => false))) {
       throw new Error("codex app-server daemon start failed");
     }
+    return this.awaitAppServer(() => this.openProxy(), 40);
+  }
+
+          async awaitAppServer(open                                                      , attempts        )                                                 {
     let last               = null;
-    for (let attempt = 0; attempt < 40; attempt++) {
-      try { return await this.openProxy(); } catch (error) { last = error         ; }
+    for (let attempt = 0; attempt < attempts; attempt++) {
+      try { return await open(); } catch (error) { last = error         ; }
       await new Promise((resolve) => setTimeout(resolve, 250));
     }
     throw new Error(`codex app-server did not come up: ${last?.message}`);
   }
 }
 
+/** Larger than any request the app-server makes of a client; only replies and notifications run this long. */
+const MAX_REQUEST_CHARS_TO_INSPECT = 1024 * 1024;
+
+/** Longest message the app-server takes in one frame, from its handshake. */
+function advertisedFrameBytes(headers                                               )         {
+  const advertised = Number(headers["x-codex-websocket-max-unfragmented-message-bytes"]);
+  return Number.isInteger(advertised) && advertised >= 64 * 1024 ? advertised : APP_SERVER_FRAME_BYTES;
+}
+
+/** A minute: the host may still be starting, or restarting its app-server to apply new settings. */
+const HOST_APP_SERVER_ATTEMPTS = 240;
 /** Largest app-server message the bridge reads before refusing it. */
 const APP_SERVER_MAX_MESSAGE_BYTES = 256 * 1024 * 1024;
 

package/src/protocol.js

@@ -176,7 +176,17 @@ export function frameNonce(counter        )         {
   return nonce;
 }
 
+/** ChaCha20-Poly1305 where the sealed bytes are the ciphertext followed by the 16-byte tag. */
+                            
+                                                                                               
+                                                                                            
+ 
+let frameAEAD                   = null;
+/** Replaces node:crypto for frames, on a runtime that does not have the cipher: Electron's BoringSSL (bridge/embedded.ts). */
+export function useFrameAEAD(aead                  ) { frameAEAD = aead; }
+
 export function seal(key        , counter        , aad        , plaintext        )         {
+  if (frameAEAD) return Buffer.from(frameAEAD.seal(key, frameNonce(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()]);
@@ -184,6 +194,7 @@ export function seal(key        , counter        , aad        , plaintext
 
 export function open(key        , counter        , aad        , sealed        )         {
   if (sealed.length < 16) throw new Error("frame too short");
+  if (frameAEAD) return Buffer.from(frameAEAD.open(key, frameNonce(counter), aad, sealed));
   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));
@@ -226,7 +237,17 @@ export class FrameCipher {
               
                 
                              
-                                    
+                                   
+                                                
+                                                                
+                                                  
+                      
+                        
+               
+
+/** A read or write of the optional board: the backend's status and body, or why there is none (PROTOCOL.md "看板"). */
+                                                                                                                              
+                                                                                    
 
                                                                  
 /** One segment of a long line: `data` is base64 of bytes [segment * chunk size, …) of the payload, `size` its length. */