replica-bridge 0.3.20 → 0.3.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replica-bridge",
-  "version": "0.3.20",
+  "version": "0.3.22",
   "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

@@ -22,8 +22,11 @@ const CHANGES_PAGE = 100;
 const CATCH_UP_PAGES = 1000;
 /** More changed tasks than this in one event, and the phone reads the whole board instead. */
 export const CHANGED_ITEMS_MAX = 200;
-/** What this bridge can do beyond reading, for board/state (PROTOCOL.md "看板"). */
-export const BOARD_CAPS = ["post", "delta", "items", "tasks"]         ;
+/**
+ * What this bridge can do beyond reading, for board/state (PROTOCOL.md "看板"). `ring`: this connection takes the
+ * ring/* frames (PROTOCOL.md "设备环：电脑一侧"), since a board connection has no resume to say it in.
+ */
+export const BOARD_CAPS = ["post", "delta", "items", "tasks", "ring"]         ;
 /** Up to this many changed tasks in one event come with their contents (`task`); past it the phone reads them itself. */
 export const CARRIED_TASKS_MAX = 50;
 /** A task bigger than this is left for the phone to read. */

package/src/bridge/main.js

@@ -11,6 +11,9 @@
 //   config [--public-url <url>]
 //   devices
 //   revoke <deviceId>
+//   ring [status]                       the device ring this computer is anchored to, and anchors waiting
+//   ring accept|reject [<n|fingerprint>] confirm or refuse a waiting anchor (lists them without an argument)
+//   ring reset [--yes]                  leave the ring, so a different one can be anchored
 import fs from "node:fs";
 import os from "node:os";
 import readline from "node:readline/promises";
@@ -20,8 +23,10 @@ import { spawnCommandSync } from "./command.js";
 import { defaultRelayURL, enroll, ensureEnrolled, ensureRelay } from "./enroll.js";
 import { PACKAGE_VERSION, clearPid, installService, logPath, pauseService, readServiceInfo, runningPid, servicePaused, servicePlan, uninstallService, writePid } from "./install.js";
 import { pair, publicRelayURL } from "./pair.js";
+import { acceptAnchor, anchorPrompt, describeAnchor, findPending, rejectAnchor, removeDevice, resetRing, ringSummary } from "./ring.js";
+                                              
 import { BridgeService } from "./service.js";
-import { loadState, saveState } from "./state.js";
+import { hostKeyPair, loadState, saveState, updateState } from "./state.js";
 
 // A leading option means no command: `replica-bridge --pair` is the default command with --pair.
 const argv = process.argv.slice(2);
@@ -53,7 +58,8 @@ const usage = `replica-bridge ${PACKAGE_VERSION}: lets the ChatReplica app use C
                                   in the background; run again for the status
   npx replica-bridge pair         pair another phone
   npx replica-bridge uninstall    stop and remove the background service
-Others: status, install, start (in this terminal), init, config, devices, revoke <id>.
+  npx replica-bridge ring accept  confirm a device ring asking to include this computer (ring reject, ring reset)
+Others: status, install, start (in this terminal), init, config, devices, revoke <id>, ring.
 The relay is ${defaultRelayURL()} unless --relay or REPLICA_RELAY says otherwise.`;
 
 // The Windows service has no terminal to write to: its output goes to the log file it names.
@@ -78,11 +84,115 @@ function startBridge()                {
     if (process.env.REPLICA_BRIDGE_SERVICE === "1" && process.platform === "win32") pauseService();
     process.exit(0);
   };
-  const service = new BridgeService({ codexPath: values.codex, loginShell: !values["no-login-shell"], streamTTLSeconds: Number(values["stream-ttl"]), onReplaced });
+  const service                = new BridgeService({
+    codexPath: values.codex, loginShell: !values["no-login-shell"], streamTTLSeconds: Number(values["stream-ttl"]), onReplaced,
+    onAnchorRequest: (prompt) => askAnchor(service, prompt),
+  });
   service.start();
   return service;
 }
 
+/** True only for y or yes: anchoring is the one question here whose default is no. */
+async function confirm(question        )                   {
+  const prompt = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try { return /^y(es)?$/i.test((await prompt.question(question)).trim()); } finally { prompt.close(); }
+}
+
+/** Anchor questions in this terminal, one at a time, once nothing else here is asking (askAnchorsHere). */
+let anchorQuestions                = Promise.resolve();
+let askAnchorsHere = false;
+
+function askAnchor(bridge               , prompt              ) {
+  if (!askAnchorsHere) {
+    console.log(`A device asks to anchor this computer to its device ring (fingerprint ${prompt.fingerprint}): run "npx replica-bridge ring accept" to confirm.`);
+    return;
+  }
+  anchorQuestions = anchorQuestions.then(async () => {
+    // Answered meanwhile with `ring accept` or `ring reject` in another terminal.
+    if (!bridge.pendingAnchors().some((p) => p.ring === prompt.ring)) return;
+    console.log(`\n${describeAnchor(prompt)}`);
+    const yes = await confirm("Anchor this computer to this ring? [y/N] ");
+    try {
+      const { removed } = bridge.answerAnchor(prompt.ring, yes);
+      console.log(yes ? `Anchored. The ring's signers can use this computer now.${removed.length ? ` Removed ${removed.join(", ")}, revoked in the ring.` : ""}` : "Rejected. The device can ask again.");
+    } catch (error) {
+      console.error(`replica-bridge: ${(error         ).message}`);
+    }
+  });
+}
+
+/** From here on this terminal asks about anchor requests, starting with any already waiting. */
+function askAnchorsInTerminal(bridge               ) {
+  if (!process.stdin.isTTY || process.env.REPLICA_BRIDGE_SERVICE === "1") return;
+  askAnchorsHere = true;
+  for (const prompt of bridge.pendingAnchors()) askAnchor(bridge, prompt);
+}
+
+/** With the background service serving the computer: ask here about the anchors it recorded (it notices the answer). */
+async function answerPendingHere() {
+  if (!process.stdin.isTTY) return;
+  for (const pending of loadState().ringPending ?? []) {
+    console.log(`\n${describeAnchor(anchorPrompt(pending))}`);
+    const yes = await confirm("Anchor this computer to this ring? [y/N] ");
+    if (yes) acceptAnchor(pending.ring, hostKeyPair(loadState()).publicKey);
+    else rejectAnchor(pending.ring);
+    console.log(yes ? "Anchored." : "Rejected.");
+    if (yes) break;
+  }
+}
+
+async function ringCommand() {
+  const sub = positionals[0] ?? "status";
+  const state = loadState();
+  if (sub === "status") {
+    for (const line of ringSummary(state)) console.log(line);
+    if (state.ringPending?.length) console.log('Confirm with "npx replica-bridge ring accept", refuse with "npx replica-bridge ring reject".');
+    return;
+  }
+  if (sub === "accept" || sub === "reject") {
+    const pending = state.ringPending ?? [];
+    if (!pending.length) { console.log("No device ring is waiting for confirmation."); return; }
+    let which = positionals[1];
+    if (!which) {
+      pending.forEach((p, i) => console.log(`\n${i + 1}. ${describeAnchor(anchorPrompt(p))}`));
+      if (!process.stdin.isTTY) throw new Error(`say which: replica-bridge ring ${sub} <number or fingerprint>`);
+      if (pending.length === 1) {
+        if (!(await confirm(`\n${sub === "accept" ? "Anchor this computer to this ring" : "Reject this request"}? [y/N] `))) return;
+        which = "1";
+      } else {
+        const prompt = readline.createInterface({ input: process.stdin, output: process.stdout });
+        try { which = (await prompt.question(`\nWhich one (1-${pending.length}, empty to stop)? `)).trim(); } finally { prompt.close(); }
+        if (!which) return;
+      }
+    } else {
+      console.log(describeAnchor(anchorPrompt(findPending(state, which))));
+    }
+    // The ring id of what was shown, so a list that changed meanwhile cannot put another ring under the same number.
+    const shown = findPending(state, which).ring;
+    if (sub === "reject") {
+      rejectAnchor(shown);
+      console.log("Rejected. Nothing changed; the device can ask again.");
+      return;
+    }
+    const { ring, removed } = acceptAnchor(shown, hostKeyPair(state).publicKey);
+    console.log(`Anchored to ring ${ring.id}. Its signers can use this computer now; "npx replica-bridge ring reset" leaves it.`);
+    if (removed.length) console.log(`Removed ${removed.join(", ")} from the paired devices: the ring revoked them.`);
+    return;
+  }
+  if (sub === "reset") {
+    if (!state.ring && !state.ringPending?.length) { console.log("Not anchored to a device ring."); return; }
+    for (const line of ringSummary(state)) console.log(line);
+    if (!values.yes) {
+      if (!process.stdin.isTTY) throw new Error("add --yes to leave the ring without a terminal to ask in");
+      if (!(await confirm("Leave this ring? Its signers can no longer use this computer unless paired here. [y/N] "))) return;
+    }
+    resetRing();
+    console.log("Left the device ring. Phones paired here by QR code still connect; a device can ask to anchor again.");
+    return;
+  }
+  throw new Error("usage: replica-bridge ring [status | accept [<n>] | reject [<n>] | reset [--yes]]");
+}
+
 /**
  * Warns, without stopping, when Codex does not answer the way the bridge will run it (through the login shell).
  * The shell is interactive (-i) so it reads the rc file where people put Codex on PATH, and an interactive shell that
@@ -197,6 +307,7 @@ function status() {
   console.log(`Owner: ${state.owner ? `${state.owner.login} (${state.owner.provider})` : "none yet"}; paired phones: ${state.devices.map((d) => d.name).join(", ") || "none"}`);
   if (info) console.log(`Background service ${info.version}: ${pid ? `running (pid ${pid})` : "installed, not running right now"}. Log: ${logPath()}`);
   else console.log(pid ? `Running (pid ${pid}).` : `Not running: "npx replica-bridge" sets up the background service.`);
+  if (state.ring || state.ringPending?.length) for (const line of ringSummary(state)) console.log(line);
 }
 
 async function main() {
@@ -215,6 +326,7 @@ async function main() {
         if (moved || values.install || installed.version !== PACKAGE_VERSION) await install();
         if (moved || values.pair || !state.devices.length) await pairOrExplain();
         else status();
+        await answerPendingHere();
         break;
       }
       if (runningPid()) throw new Error(`a bridge already runs for this computer (pid ${runningPid()}); stop it first`);
@@ -234,6 +346,7 @@ async function main() {
       }
       for (const signal of ["SIGINT", "SIGTERM"]         ) process.on(signal, () => { bridge.stop(); process.exit(0); });
       console.log(`Running in this terminal: paired phones can use Codex on ${state.hostName} until it closes (Ctrl-C stops it).`);
+      askAnchorsInTerminal(bridge);
       if (!(await bridge.waitForRelay(RELAY_WAIT_MS))) console.warn(`Still not connected to the relay${bridge.relayProblem ? ` (${bridge.relayProblem})` : ""}: the phone shows ${state.hostName} offline until it is.`);
       break;
     }
@@ -282,6 +395,7 @@ async function main() {
       if (runningPid()) throw new Error(`a bridge already runs for this computer (pid ${runningPid()})${asService ? "" : '; "npx replica-bridge uninstall" stops the background one'}`);
       const bridge = startBridge();
       if (asService) { writePid(); process.on("exit", clearPid); }
+      askAnchorsInTerminal(bridge);
       for (const signal of ["SIGINT", "SIGTERM"]         ) process.on(signal, () => { bridge.stop(); process.exit(0); });
       break;
     }
@@ -298,11 +412,18 @@ async function main() {
       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);
+      // Read again after the request: the running bridge may have stored ring entries meanwhile.
+      let name                = null;
+      const after = updateState((latest) => { name = removeDevice(latest, deviceId); });
       console.log(`Removed ${deviceId} from this computer.`);
+      if (name && after.ring) {
+        console.log(`It stays refused here even while this computer's device ring lists it as a signer. To remove "${name}" from your other computers too, remove it from the ring in the app.`);
+      }
       break;
     }
+    case "ring":
+      await ringCommand();
+      break;
     default:
       console.log(usage);
       process.exitCode = 1;

package/src/bridge/pair.js

@@ -136,6 +136,8 @@ export async function pair(options             )
     ...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() }],
+    // Scanning it again here is a person saying yes to this key: it is no longer refused (ring.ts removeDevice).
+    ...(s.denied ? { denied: s.denied.filter((d) => d.key !== b64url(devicePublicKey)) } : {}),
   });
   saveState(withDevice(loadState()));
   try {

package/src/bridge/ring.js

@@ -0,0 +1,427 @@
+// The device ring on the computer's side (PROTOCOL.md "设备环：电脑一侧"). A bridge is a member, never a signer: it
+// only keeps the log, checks every entry with RingState, and lets the ring's active signers connect once a person on
+// this computer has confirmed which ring it belongs to (anchoring). Everything is kept in state.json.
+import { RelayHTTPError } from "../http.js";
+import { RING_ENTRIES_PER_FRAME, RingError, RingState, b64url, fromB64url, ringB64, ringFingerprint } from "../protocol.js";
+                                                                
+import { loadState, updateState } from "./state.js";
+                                                                           
+
+/** Longest log the bridge keeps; far more than a person's devices ever write. */
+export const RING_LOG_MAX_ENTRIES = 10_000;
+/** Most bytes (base64url of entries and signatures) the anchored log may take in state.json: some 6,000 typical entries. */
+export const RING_LOG_MAX_BYTES = 2 * 1024 * 1024;
+/** Most bytes a pending anchor's log may take; it lands in state.json before anyone has confirmed anything. */
+export const PENDING_LOG_MAX_BYTES = 1024 * 1024;
+/** Different rings waiting for confirmation at once; a newer request for one of them replaces its log. */
+export const PENDING_ANCHORS_MAX = 4;
+/** Largest relay answer the bridge reads for one page of the log. */
+export const RELAY_PAGE_MAX_BYTES = 8 * 1024 * 1024;
+
+/** base64url lengths: the longest an entry can be (RING_ENTRY_MAX_BYTES), and a 64-byte signature. */
+const ENTRY_B64_MAX = Math.ceil((16 * 1024 * 4) / 3);
+const SIGNATURE_B64 = 86;
+
+export const logBytes = (entries                 )         => entries.reduce((sum, entry) => sum + entry.e.length + entry.s.length, 0);
+
+/**
+ * Entries being added to a log, checked one at a time as they arrive: the first that does not apply ends it, and so
+ * does reaching `until` or the size limits. Nothing is kept unverified, whatever a peer or the relay sends.
+ */
+export class LogGrowth {
+           added                  = [];
+  /** Why it stopped short of `until`: an entry that did not apply, or the size limit (`full`). */
+  stopped                = null;
+  full = false;
+          bytes        ;
+          count        ;
+           state           ;
+           until        ;
+                   maxBytes        ;
+
+  constructor(state           , base                 , until        , maxBytes = RING_LOG_MAX_BYTES) {
+    this.state = state; this.until = until; this.maxBytes = maxBytes;
+    this.bytes = logBytes(base); this.count = base.length;
+  }
+
+  get done() { return this.state.seq >= this.until || this.stopped !== null; }
+
+  /**
+   * Applies a page; false once nothing more should be asked for. Only an entry that verifies can make the log full:
+   * an oversized one that does not would otherwise let anyone stop the ring with one bogus entry.
+   */
+  take(page                 , from        )          {
+    for (const entry of page) {
+      if (this.done) return false;
+      const size = entry.e.length + entry.s.length;
+      const bad = (why        ) => { this.stopped = `${from} sent an entry for seq ${this.state.seq + 1} that does not apply (${why})`; return false; };
+      // Longer than any entry can be: refused before any work (RingState would say too_large or bad_encoding).
+      if (entry.e.length > ENTRY_B64_MAX || entry.s.length !== SIGNATURE_B64) return bad("too_large: longer than any entry");
+      const seq = this.state.seq;
+      try { this.state.apply(entry); } catch (error) { return bad((error         ).message); }
+      if (this.count + 1 > RING_LOG_MAX_ENTRIES || this.bytes + size > this.maxBytes) {
+        // Verified but past the limit: not kept (storeLog replays only `added`), and the log counts as full.
+        this.full = true;
+        this.stopped = `the log reached this bridge's limit at seq ${seq}`;
+        return false;
+      }
+      this.added.push(entry);
+      this.bytes += size;
+      this.count++;
+    }
+    return !this.done;
+  }
+}
+
+/** Replays a log as far as it is valid: the state of that prefix, and why it stopped (null when it did not). */
+export function replayPrefix(entries                 , from                       )                                                             {
+  const state = from?.state ?? new RingState();
+  let applied = 0;
+  for (const entry of entries) {
+    try { state.apply(entry); } catch (error) { return { state, applied, error: error          }; }
+    applied++;
+  }
+  return { state, applied, error: null };
+}
+
+/** A copy of a state by replaying its log again; RingState has no clone and the logs are small. */
+export function replayAll(entries                 )            {
+  const { state, error } = replayPrefix(entries);
+  if (error) throw error;
+  return state;
+}
+
+/**
+ * The anchored ring's state, replayed from state.json whenever the stored log differs from what was last replayed.
+ * A stored log that stops replaying (edited by hand) counts up to its last valid entry; one whose genesis is not the
+ * anchored ring counts as no ring at all, so it grants nothing.
+ */
+export class RingCache {
+          key = "";
+          state                   = null;
+
+  get(ring                          , log                            = () => {})                   {
+    if (!ring) { this.key = ""; this.state = null; return null; }
+    const key = `${ring.id}|${ring.entries.length}|${ring.entries.at(-1)?.e ?? ""}`;
+    if (key === this.key) return this.state;
+    const { state, error } = replayPrefix(ring.entries);
+    if (error) log(`device ring: the stored log stops at seq ${state.seq}: ${error.message}`);
+    this.key = key;
+    this.state = state.ringId && b64url(state.ringId) === ring.id ? state : null;
+    if (!this.state) log("device ring: the stored log does not start with the anchored ring's genesis; the ring grants nothing");
+    return this.state;
+  }
+}
+
+                           
+                                                                                                           
+                     
+              
+               
+ 
+
+/**
+ * Who may connect: the devices paired here by QR code, minus any key revoked in the anchored ring, plus the anchored
+ * ring's active signers. Members never connect to other members. A computer revoked from its own ring takes nobody in
+ * through the ring, though its paired devices still connect.
+ */
+export function admit(state             , ring                  , hostKey        , deviceId        , offeredKey               )                                 {
+  const paired = state.devices.find((d) => d.deviceId === deviceId);
+  // Removed here: a local no that the ring cannot overrule.
+  const denied = (key        ) => state.denied?.some((d) => d.key === b64url(key));
+  if (offeredKey && !paired && denied(offeredKey)) return { refused: "removed from this computer" };
+  if (paired) {
+    const key = fromB64url(paired.publicKey);
+    if (denied(key)) return { refused: "removed from this computer" };
+    if (ring?.isRevokedKey("x25519", key)) return { refused: "removed from the device ring" };
+    return { via: "qr", key, name: paired.name };
+  }
+  if (!ring || !offeredKey) return { refused: "not paired with this computer" };
+  if (!ring.activeMemberWithKey("x25519", hostKey)) return { refused: "this computer is no longer in its device ring" };
+  // A log that stopped growing at the size limit may be missing revocations: the ring lets nobody in until a reset.
+  if (state.ring?.stalled) return { refused: "this computer's copy of its device ring is full" };
+  const signer = ring.signers.find((m) => m.key.equals(offeredKey));
+  if (signer) return { via: "ring", key: offeredKey, name: signer.name };
+  if (ring.activeMemberWithKey("x25519", offeredKey)) return { refused: "only the ring's signers connect to its members" };
+  return { refused: "not paired with this computer and not a signer of its device ring" };
+}
+
+/**
+ * The three conditions for anchoring (docs/design/DEVICE-RING.md): the requester is paired here by QR code, it is an
+ * active signer of the ring with the transport key of this very connection and the signing key it named, and this
+ * computer's own key is an active member. The log must replay from genesis to the head the requester claimed.
+ */
+export function checkAnchor(state             , hostKey        , request                                                                                               )                                                                {
+  const paired = state.devices.find((d) => d.deviceId === request.deviceId);
+  if (!paired || !fromB64url(paired.publicKey).equals(request.key)) return { refused: "only a device paired here by QR code can ask" };
+  if (request.entries.length > RING_LOG_MAX_ENTRIES || logBytes(request.entries) > PENDING_LOG_MAX_BYTES) return { refused: "the log is too long" };
+  const { state: ring, error } = replayPrefix(request.entries);
+  if (error) return { refused: `the log does not verify: ${error.message}` };
+  if (!ring.ringId || b64url(ring.ringId) !== request.ring) return { refused: "the log is not this ring's" };
+  const signer = ring.signers.find((m) => m.key.equals(request.key) && m.signingKey .equals(request.signingKey));
+  if (!signer) return { refused: "the device is not an active signer of the ring with this key" };
+  if (ring.isRevokedKey("x25519", hostKey) || !ring.activeMemberWithKey("x25519", hostKey)) return { refused: "this computer is not an active member of the ring" };
+  return { ring, signer };
+}
+
+/** What a person on this computer is asked to confirm. */
+                               
+               
+                      
+                                                                                                   
+                    
+                    
+                  
+                      
+ 
+
+export function anchorPrompt(pending               )               {
+  const ring = replayAll(pending.entries);
+  const key = fromB64url(pending.requester.key);
+  const inRing = ring.signers.find((m) => m.key.equals(key))?.name ?? pending.requester.name;
+  return {
+    ring: pending.ring, fingerprint: ringFingerprint(fromB64url(pending.ring)),
+    // Always both: the name it was paired under here is the one a stranger's ring cannot choose; the six digits
+    // alone can be matched by trying about a million genesis nonces.
+    requester: `${inRing} (paired here as "${pending.requester.name}")`,
+    signers: ring.signers.map((m) => m.name), members: ring.active.length, requestedAt: pending.requestedAt,
+  };
+}
+
+/** The question, as the terminal and `ring accept` print it. */
+export function describeAnchor(prompt              )         {
+  return [
+    "A device asks to anchor this computer to its device ring.",
+    `  Asked by:     ${prompt.requester}`,
+    `  Signers:      ${prompt.signers.join(", ")} (${prompt.members} devices in the ring)`,
+    `  Fingerprint:  ${prompt.fingerprint}  (the app shows the same six digits)`,
+    "Once confirmed, every signer of this ring can use this computer, and the ring can only change with",
+    '"npx replica-bridge ring reset". Confirm only if this is your ring and the digits match.',
+  ].join("\n");
+}
+
+/**
+ * Records (or refreshes) a pending anchor once checkAnchor passed. Nothing else changes until a person confirms.
+ * Returns false when this computer is already anchored or too many other rings are waiting.
+ */
+export function recordPending(request               )          {
+  let recorded = false;
+  updateState((state) => {
+    if (state.ring) return;
+    const pending = state.ringPending ?? [];
+    const index = pending.findIndex((p) => p.ring === request.ring);
+    if (index >= 0) {
+      pending[index] = { ...request, requestedAt: pending[index].requestedAt };
+    } else {
+      if (pending.length >= PENDING_ANCHORS_MAX) return;
+      pending.push(request);
+    }
+    state.ringPending = pending;
+    recorded = true;
+  });
+  return recorded;
+}
+
+/** A pending anchor by its number in the list (1-based), its fingerprint, or the start of its ring id. */
+export function findPending(state             , which        )                {
+  const pending = state.ringPending ?? [];
+  if (!pending.length) throw new Error("no device ring is waiting for confirmation");
+  const byNumber = /^\d{1,2}$/.test(which) ? pending[Number(which) - 1] : undefined;
+  const found = byNumber ?? pending.filter((p) => ringFingerprint(fromB64url(p.ring)) === which || (which.length >= 6 && p.ring.startsWith(which)));
+  if (!Array.isArray(found)) return found;
+  if (found.length !== 1) throw new Error(found.length ? `"${which}" matches more than one pending ring` : `no pending ring matches "${which}"`);
+  return found[0];
+}
+
+/**
+ * Removes a paired device on this computer and remembers its key as refused, so a ring that still lists it as a
+ * signer cannot bring it back; pairing it here by QR code again lifts that. Returns its name, or null when unknown.
+ */
+export function removeDevice(state             , deviceId        )                {
+  // Paired here by QR code, or only ever let in through the ring: either way its key is on file.
+  const device = state.devices.find((d) => d.deviceId === deviceId) ?? state.ringDevices?.find((d) => d.deviceId === deviceId);
+  state.devices = state.devices.filter((d) => d.deviceId !== deviceId);
+  if (state.ringDevices) state.ringDevices = state.ringDevices.filter((d) => d.deviceId !== deviceId);
+  if (!device) return null;
+  const publicKey = "publicKey" in device ? device.publicKey : device.key;
+  state.denied = [...(state.denied ?? []).filter((d) => d.key !== publicKey), { key: publicKey, name: device.name, at: new Date().toISOString() }];
+  return device.name;
+}
+
+/** Most ring-only devices remembered for `revoke`; a person has far fewer. */
+export const RING_DEVICES_MAX = 64;
+
+/** Remembers a device let in through the ring under its relay device id (for `revoke`); false when nothing changed. */
+export function noteRingDevice(state             , deviceId        , key        , name        )          {
+  const known = state.ringDevices?.find((d) => d.deviceId === deviceId);
+  if (known && known.key === b64url(key) && known.name === name) return false;
+  const others = (state.ringDevices ?? []).filter((d) => d.deviceId !== deviceId);
+  state.ringDevices = [...others, { deviceId, key: b64url(key), name, seenAt: new Date().toISOString() }].slice(-RING_DEVICES_MAX);
+  return true;
+}
+
+
+/** Drops paired devices whose key was revoked in the ring, for good: a reset does not bring them back. */
+export function pruneRevoked(state             , ring           )           {
+  const removed = state.devices.filter((d) => ring.isRevokedKey("x25519", fromB64url(d.publicKey)));
+  state.devices = state.devices.filter((d) => !removed.includes(d));
+  return removed.map((d) => d.name);
+}
+
+/**
+ * Confirms a pending anchor: checks the three conditions again against the paired devices as they are now, then
+ * anchors for good and forgets every other pending ring.
+ */
+export function acceptAnchor(which        , hostKey        )                                            {
+  let result                                                   = null;
+  updateState((state) => {
+    if (state.ring) throw new Error(`this computer is already anchored to ring ${state.ring.id}; "replica-bridge ring reset" first`);
+    const pending = findPending(state, which);
+    const checked = checkAnchor(state, hostKey, {
+      deviceId: pending.requester.deviceId, key: fromB64url(pending.requester.key), signingKey: fromB64url(pending.requester.signingKey), ring: pending.ring, entries: pending.entries,
+    });
+    if ("refused" in checked) throw new Error(`cannot anchor to this ring any more: ${checked.refused}`);
+    const ring               = { id: pending.ring, entries: pending.entries, anchoredAt: new Date().toISOString(), anchoredBy: { deviceId: pending.requester.deviceId, name: pending.requester.name } };
+    state.ring = ring;
+    delete state.ringPending;
+    result = { ring, removed: pruneRevoked(state, checked.ring) };
+  });
+  return result ;
+}
+
+export function rejectAnchor(which        )                {
+  let rejected                       = null;
+  updateState((state) => {
+    rejected = findPending(state, which);
+    state.ringPending = state.ringPending .filter((p) => p !== rejected);
+    if (!state.ringPending.length) delete state.ringPending;
+  });
+  return rejected ;
+}
+
+/** Leaves the ring: its signers can no longer connect unless paired here. Devices it revoked stay removed. */
+export function resetRing()                           {
+  let was                          ;
+  updateState((state) => {
+    was = state.ring;
+    delete state.ring;
+    delete state.ringPending;
+  });
+  return was;
+}
+
+/**
+ * Adds verified entries to the anchored log. `added` extends `base` (the log as it was when the caller started
+ * fetching); when the stored log grew meanwhile, only the entries past it are applied again on top. All in one
+ * synchronous step, so this process never interleaves two writers and the stored log only ever grows.
+ */
+export function storeLog(ringId        , base                 , added                 , stalled               )                                            {
+  let result                                            = null;
+  updateState((state) => {
+    if (state.ring?.id !== ringId) return;
+    const stored = state.ring.entries;
+    if (stored.length < base.length || stored[base.length - 1]?.e !== base.at(-1)?.e) return;
+    const growth = new LogGrowth(replayAll(stored), stored, Number.MAX_SAFE_INTEGER);
+    growth.take(added.slice(stored.length - base.length), "a peer");
+    if (stalled && !state.ring.stalled) state.ring.stalled = stalled;
+    if (!growth.added.length && !stalled) return;
+    state.ring.entries = [...stored, ...growth.added];
+    result = { seq: growth.state.seq, removed: pruneRevoked(state, growth.state) };
+  });
+  return result;
+}
+
+/** The anchored ring's summary, for `replica-bridge ring` and status. */
+export function ringSummary(state              = loadState())           {
+  const lines           = [];
+  if (state.ring) {
+    const { state: ring } = replayPrefix(state.ring.entries);
+    lines.push(`Device ring ${state.ring.id} (fingerprint ${ringFingerprint(fromB64url(state.ring.id))}), anchored ${state.ring.anchoredAt} at the request of ${state.ring.anchoredBy.name}`);
+    if (state.ring.stalled) lines.push(`  Stopped growing (${state.ring.stalled}): the ring lets nobody in until "replica-bridge ring reset".`);
+    lines.push(`  ${ring.seq + 1} entries; signers: ${ring.signers.map((m) => m.name).join(", ") || "none"}; members: ${ring.active.filter((m) => m.role === "member").map((m) => m.name).join(", ") || "none"}`);
+  } else lines.push("Not anchored to a device ring.");
+  for (const d of state.ringDevices ?? []) lines.push(`  through the ring: ${d.name} (${d.deviceId}), last ${d.seenAt}; "replica-bridge revoke ${d.deviceId}" refuses it here`);
+  (state.ringPending ?? []).forEach((pending, i) => {
+    const prompt = anchorPrompt(pending);
+    lines.push(`  waiting ${i + 1}: ring ${prompt.ring.slice(0, 12)}…, fingerprint ${prompt.fingerprint}, asked by ${prompt.requester} at ${prompt.requestedAt}`);
+  });
+  return lines;
+}
+
+/** Checks the shape of a ring frame's entries, so nothing below sees anything but {e, s} strings. */
+export function wireEntries(value         )                         {
+  if (!Array.isArray(value) || value.length > RING_ENTRIES_PER_FRAME) return null;
+  for (const item of value) if (typeof item?.e !== "string" || typeof item?.s !== "string") return null;
+  return value.map((item) => ({ e: item.e, s: item.s }));
+}
+
+const withTimeout =    (promise            , ms        )             => Promise.race([
+  promise, new Promise   ((_, reject) => setTimeout(() => reject(new Error(`no answer in ${ms / 1000} s`)), ms).unref()),
+]);
+
+/**
+ * The relay's copy of the log (docs/design/DEVICE-RING.md "中转服务器：存储和推送"), used only after it says
+ * `ring-v1` at /v1/ring/capabilities; an older relay answers 404 and the bridge stays with what the peers gave it.
+ * The relay cannot forge entries, so whatever it returns is checked like a peer's.
+ */
+export class RelayRingStore {
+          known                                            = null;
+                   relay                                            ;
+  constructor(relay                                            ) { this.relay = relay; }
+
+  /** Asks again next time: the relay socket reopened, perhaps onto a newer (or older) relay. */
+  forget() { this.known = null; }
+
+  async supported()                   {
+    if (this.known && Date.now() - this.known.at < 5 * 60_000) return this.known.supported;
+    const { relay } = this.relay();
+    let supported = false;
+    try {
+      const answer = await withTimeout(readJSON(new URL("v1/ring/capabilities", relay.endsWith("/") ? relay : `${relay}/`)), 10_000)                      ;
+      supported = answer.ring === "ring-v1";
+    } catch (error) {
+      // A relay that is down says nothing about what it supports; ask again next time.
+      if (!(error instanceof RelayHTTPError)) return false;
+    }
+    this.known = { supported, at: Date.now() };
+    return supported;
+  }
+
+  /** Pages of the log after the growth's head into `growth`, each checked as it arrives, until it is done. */
+  async fetchInto(ringId        , growth           )                {
+    if (!(await this.supported())) throw new Error("the relay has no ring endpoints");
+    const { relay, hostToken } = this.relay();
+    while (!growth.done) {
+      const after = growth.state.seq;
+      const url = new URL(`v1/ring/${encodeURIComponent(ringId)}${after >= 0 ? `?after=${after}` : ""}`, relay.endsWith("/") ? relay : `${relay}/`);
+      const page = await withTimeout(readJSON(url, hostToken), 15_000)                                                         ;
+      if (page.ring !== undefined && page.ring !== ringId) throw new Error("the relay answered for another ring");
+      const entries = Array.isArray(page.entries) ? page.entries.filter((e) => typeof e?.e === "string" && typeof e?.s === "string").map((e) => ({ e: e.e          , s: e.s           })) : [];
+      if (!growth.take(entries, "the relay") || !page.more || !entries.length) return;
+    }
+  }
+}
+
+/** A GET (with the computer's token when given) whose answer may be at most RELAY_PAGE_MAX_BYTES: a relay cannot run the bridge out of memory. */
+async function readJSON(url     , token         )                   {
+  const response = await fetch(url, { headers: token ? { authorization: `Bearer ${token}` } : {} });
+  const reader = response.body?.getReader();
+  const chunks               = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = reader ? await reader.read() : { done: true, value: undefined };
+    if (done) break;
+    size += value.length;
+    if (size > RELAY_PAGE_MAX_BYTES) { await reader .cancel(); throw new Error("the relay's answer is too large"); }
+    chunks.push(value);
+  }
+  const text = Buffer.concat(chunks).toString("utf8");
+  if (!response.ok) throw new RelayHTTPError(response.status, String(response.status), text.slice(0, 200));
+  return JSON.parse(text);
+}
+
+/** True when a string is canonical base64url of 32 bytes (a ring id, an entry id, a key). */
+export function isKey32(text         )                 {
+  if (typeof text !== "string") return false;
+  try { return ringB64(text).length === 32; } catch (error) { if (error instanceof RingError) return false; throw error; }
+}