replica-bridge 0.3.19 → 0.3.22

package/src/bridge/service.js

@@ -5,19 +5,28 @@
 // the app-server says, so a phone that drops off the network resumes where it left off.
                                                        
 import crypto from "node:crypto";
+import fs from "node:fs";
 import os from "node:os";
 import { Duplex } from "node:stream";
 import { WebSocket } from "ws";
                                   
 import {
-  CloseCode, FrameCipher, ChunkAssembler, MAX_FRAME_BYTES, REASSEMBLED_MAX_BYTES, RELAY_REPLY_LIMIT, StreamBuffer, encodeLine, b64url, fromB64url, generateKeyPair, hostSessionKeys,
+  CloseCode, FrameCipher, ChunkAssembler, MAX_FRAME_BYTES, REASSEMBLED_MAX_BYTES, RELAY_REPLY_LIMIT, RING_ENTRIES_PER_FRAME, StreamBuffer, encodeLine, b64url, fromB64url,
+  RingState, generateKeyPair, hostSessionKeys, ringB64,
 } from "../protocol.js";
-                                                                            
+             
+                                                                                                  
+                        
 import { relaySocketURL } from "../http.js";
 import { BoardReader } from "./board.js";
 import { readWork, workDirectories } from "./work.js";
 import { killCommand, spawnCommand } from "./command.js";
-import { hostKeyPair, loadState } from "./state.js";
+import {
+  LogGrowth, PENDING_LOG_MAX_BYTES, RING_LOG_MAX_ENTRIES, RelayRingStore, RingCache, acceptAnchor, admit, anchorPrompt, checkAnchor, isKey32, noteRingDevice, recordPending, rejectAnchor,
+  replayAll, storeLog, wireEntries,
+} from "./ring.js";
+                                                        
+import { hostKeyPair, loadState, statePathForWatch, updateState } from "./state.js";
 import { annotateWriterError } from "./writer.js";
                                           
                                               
@@ -60,6 +69,13 @@ import { annotateWriterError } from "./writer.js";
                             
                                                                                               
                              
+     
+                                                                                                                    
+                                                                                                         
+     
+                                                   
+                                                                                                                 
+                           
  
 
                   
@@ -79,6 +95,8 @@ import { annotateWriterError } from "./writer.js";
                          
                                                                                                                             
                               
+                                                                                           
+                     
  
 
                 
@@ -90,6 +108,22 @@ import { annotateWriterError } from "./writer.js";
                        
                                                    
                                         
+                                                                                                          
+                            
+                                  
+                            
+                                                                                                 
+                    
+                                                                                                                     
+                                                                                                    
+                                                            
+                                                      
+                                                                                                     
+                            
+                       
+                                                                 
+                          
+                  
  
 
 export class BridgeService {
@@ -103,6 +137,16 @@ export class BridgeService {
 
                    options                ;
                    board             ;
+                   ringCache = new RingCache();
+                   relayRing = new RelayRingStore(() => loadState());
+  /** What connected ring peers last heard from this bridge, so a change is told once. */
+          ringTold = "";
+  /** The ring this bridge last saw itself anchored to, to catch up once a new anchor is confirmed. */
+          anchoredId                           ;
+  /** The newest relay push not handled yet, and whether one is being handled: pushes never pile up. */
+          nextPush                       = null;
+          pushRunning = false;
+          watching                = null;
 
   constructor(options                 = {}) {
     this.options = options;
@@ -111,11 +155,16 @@ export class BridgeService {
   }
 
   start() {
+    try { this.anchoredId = loadState().ring?.id ?? null; } catch { this.anchoredId = null; /* not set up: connectRelay says so */ }
     this.connectRelay();
+    // `replica-bridge ring accept`, `ring reset` and `revoke` run as other processes and change state.json.
+    this.watching = statePathForWatch();
+    fs.watchFile(this.watching, { interval: 1000 }, () => this.ringChanged());
   }
 
   stop() {
     this.stopped = true;
+    if (this.watching) { fs.unwatchFile(this.watching); this.watching = null; }
     if (this.retryTimer) clearTimeout(this.retryTimer);
     this.relay?.close();
     this.board.stop();
@@ -157,7 +206,8 @@ export class BridgeService {
 
           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 });
+    // ring=1: this bridge reads `key` in `open` and the relay's ring pushes; a relay without the ring ignores it.
+    const ws = new WebSocket(relaySocketURL(state.relay, "/v1/host?ring=1"), { headers: { authorization: `Bearer ${state.hostToken}` }, maxPayload: MAX_FRAME_BYTES + 4096, perMessageDeflate: false });
     this.relay = ws;
     let refused = false;
     // A laptop that sleeps or changes networks keeps a socket the relay dropped long ago, and nothing here would
@@ -178,6 +228,8 @@ export class BridgeService {
       this.log(`connected to relay ${state.relay} as ${state.hostId}`);
       this.options.onRelayConnected?.(true);
       this.relayChanged();
+      this.relayRing.forget();
+      void this.catchUpFromRelay();
     });
     ws.on("message", (data         ) => {
       let envelope              ;
@@ -243,55 +295,98 @@ export class BridgeService {
     this.conns.delete(conn.id);
   }
 
-          onEnvelope(envelope              ) {
+          onEnvelope(envelope                              ) {
     if (envelope.type === "open") {
-      this.conns.set(envelope.conn, { id: envelope.conn, deviceId: envelope.device, cipher: null, stream: null, queue: Promise.resolve(), boardUnsubscribe: null });
+      const offered = envelope.key;
+      this.conns.set(envelope.conn, {
+        id: envelope.conn, deviceId: envelope.device, cipher: null, stream: null, queue: Promise.resolve(), boardUnsubscribe: null,
+        offeredKey: isKey32(offered) ? fromB64url(offered) : null, admitted: null, ringPeer: false, held: null, ringWaiter: null, nextHead: null, headRunning: false, peerRing: null, peerSeq: -1,
+      });
     } 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");
-      });
+      this.enqueue(conn, () => this.onFrame(conn, envelope.frame));
+    } else if (envelope.type === "ring") {
+      void this.onRingPush(envelope);
     }
   }
 
-  /** 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        )                                                            {
+  /** Runs work in this connection's order; a failure is a protocol error that ends the connection. */
+          enqueue(conn      , work                     ) {
+    conn.queue = conn.queue.then(work).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");
+    });
+  }
+
+  /**
+   * Who this device is: paired here by QR code, or an active signer of the anchored ring (ring.ts admit). A device
+   * paired a moment ago may not be saved yet, so look again briefly; one the ring revoked is refused at once.
+   */
+          async admitDevice(conn      )                                                                            {
+    let refused = "";
     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) };
+      const ring = this.ringCache.get(state.ring, this.log);
+      // Every handshake looks at the log again, so a revocation another process stored ends live connections too.
+      this.enforceRing(state, ring);
+      const result = admit(state, ring, hostKeyPair(state).publicKey, conn.deviceId, conn.offeredKey);
+      if (!("refused" in result)) return { state, admitted: result };
+      refused = result.refused;
+      // Only an unknown device may be one paired a moment ago; the ring's refusals are final.
+      if (state.devices.some((d) => d.deviceId === conn.deviceId) || !refused.startsWith("not paired")) break;
       await new Promise((resolve) => setTimeout(resolve, 500));
     }
-    return null;
+    return { refused };
   }
 
           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" });
+      const found = await this.admitDevice(conn);
+      if ("refused" in found) {
+        this.log(`refused ${conn.deviceId}: ${found.refused}`);
+        this.sendFrame(conn, { type: "error", code: "unknown_device", message: found.refused === "not paired with this computer" ? "this phone is not paired with this computer" : `this device may not connect: ${found.refused}` });
         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);
+      const keys = hostSessionKeys(hostKeyPair(found.state), ephemeral, found.admitted.key, deviceEphemeral);
       conn.cipher = new FrameCipher(keys.hostToDevice, keys.deviceToHost, keys.transcript);
+      conn.admitted = found.admitted;
+      if (found.admitted.via === "ring") {
+        this.log(`${conn.deviceId} connects as ${found.admitted.name}, a signer of this computer's device ring`);
+        // Kept so `replica-bridge revoke <deviceId>` can refuse this key here, though it was never paired by QR code.
+        const { deviceId } = conn, { key, name } = found.admitted;
+        if (noteRingDevice(loadState(), deviceId, key, name)) updateState((state) => { noteRingDevice(state, deviceId, key, name); });
+      }
       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 === "ring/head" || message.t === "ring/get" || message.t === "ring/entries") return this.onRingMessage(conn, message);
+    // A ring peer's messages wait until its ring/head is handled (and any entries it has that this computer lacks).
+    if (conn.held) {
+      conn.held.messages.push(message);
+      conn.held.bytes += frame.c.length;
+      // A peer that keeps sending without ever saying its head is not held without limit.
+      if (conn.held.messages.length >= HELD_MESSAGES_MAX || conn.held.bytes >= HELD_BYTES_MAX) this.releaseHeld(conn);
+      return;
+    }
+    await this.onMessage(conn, message);
+  }
+
+          async onMessage(conn      , message              ) {
     if (message.t === "resume") {
       if (conn.stream) throw new Error("second resume");
       await this.resume(conn, message.stream, message.ack, message.seg === 1);
+      if (message.ring === 1 && conn.stream) this.holdForRing(conn);
     } else if (message.t === "msg") {
       const stream = conn.stream;
       if (!stream) throw new Error("message before resume");
@@ -328,24 +423,298 @@ export class BridgeService {
     }
   }
 
+  // MARK: - Device ring (ring.ts, PROTOCOL.md "设备环：电脑一侧")
+
+          get ringWaitMs() { return (this.options.ringWaitSeconds ?? 10) * 1000; }
+
+  /** The pending anchors, as a person here is asked about them. */
+  pendingAnchors()                 { return (loadState().ringPending ?? []).map(anchorPrompt); }
+
+  /** A person here answered an anchor request (the terminal's y/n, the desktop app's dialog); `ring` is its id. */
+  answerAnchor(ring        , accept         )                        {
+    let removed           = [];
+    if (accept) {
+      removed = acceptAnchor(ring, hostKeyPair(loadState()).publicKey).removed;
+      this.log(`device ring: anchored to ring ${ring}${removed.length ? `; removed ${removed.join(", ")}, revoked in the ring, from the paired devices` : ""}`);
+    } else {
+      rejectAnchor(ring);
+      this.log(`device ring: rejected the request to anchor to ring ${ring}`);
+    }
+    this.ringChanged();
+    return { removed };
+  }
+
+  /** Holds a ring peer's messages until its ring/head is handled, or for at most twice the wait. */
+          holdForRing(conn      ) {
+    conn.ringPeer = true;
+    if (conn.held) return;
+    conn.held = { messages: [], bytes: 0, timer: setTimeout(() => this.releaseHeld(conn), this.ringWaitMs * 2), opening: false };
+  }
+
+  /** Handles the held messages in order, behind whatever this connection already queued. */
+          releaseHeld(conn      ) {
+    const held = conn.held;
+    if (!held || held.opening) return;
+    held.opening = true;
+    clearTimeout(held.timer);
+    this.enqueue(conn, async () => {
+      while (held.messages.length) {
+        if (this.conns.get(conn.id) !== conn) return;
+        await this.onMessage(conn, held.messages.shift() );
+      }
+      if (conn.held === held) conn.held = null;
+    });
+  }
+
+          onRingMessage(conn      , message                    ) {
+    conn.ringPeer = true;
+    if (message.t === "ring/entries") {
+      const waiter = conn.ringWaiter;
+      conn.ringWaiter = null;
+      waiter?.(message);
+    } else if (message.t === "ring/get") {
+      this.answerRingGet(conn, message);
+    } else {
+      // Not awaited: catching up asks the peer for entries, and its answers arrive behind this frame.
+      conn.nextHead = message;
+      if (conn.headRunning) return;
+      conn.headRunning = true;
+      void (async () => {
+        while (conn.nextHead) {
+          const head = conn.nextHead;
+          conn.nextHead = null;
+          try { await this.onPeerHead(conn, head); } catch (error) { this.log(`device ring: ${conn.deviceId}: ${(error         ).message}`); }
+          this.releaseHeld(conn);
+        }
+        conn.headRunning = false;
+      })();
+    }
+  }
+
+          answerRingGet(conn      , message                                  ) {
+    const state = loadState();
+    const ring = this.ringCache.get(state.ring, this.log);
+    const after = message.after ?? -1;
+    if (!state.ring || !ring || message.ring !== state.ring.id || !Number.isSafeInteger(after) || after < -1) {
+      return this.sendInner(conn, { t: "ring/entries", ring: String(message.ring), entries: [] });
+    }
+    const valid = state.ring.entries.slice(0, ring.seq + 1);
+    const entries = valid.slice(after + 1, after + 1 + RING_ENTRIES_PER_FRAME);
+    this.sendInner(conn, { t: "ring/entries", ring: state.ring.id, entries, ...(after + 1 + entries.length < valid.length ? { more: true          } : {}) });
+  }
+
+          ownHead(state             , ring                  , peerRing               )           {
+    if (state.ring && ring) return { t: "ring/head", ring: state.ring.id, seq: ring.seq, id: b64url(ring.head) };
+    const pending = !state.ring && peerRing ? state.ringPending?.find((p) => p.ring === peerRing) : undefined;
+    return { t: "ring/head", ring: null, ...(pending ? { pending: pending.ring } : {}) };
+  }
+
+          async onPeerHead(conn      , head          ) {
+    const peerRing = isKey32(head.ring) ? head.ring : null;
+    const seq = typeof head.seq === "number" && Number.isSafeInteger(head.seq) && head.seq >= 0 ? head.seq : null;
+    conn.peerRing = peerRing;
+    conn.peerSeq = seq ?? -1;
+    const state = loadState();
+    if (state.ring) {
+      // An anchored computer listens to its own ring only.
+      if (peerRing === state.ring.id && seq !== null) await this.catchUp(peerRing, seq, isKey32(head.id) ? head.id : null, conn);
+    } else if (peerRing && seq !== null && isKey32(head.id) && isKey32(head.key) && conn.admitted?.via === "qr") {
+      await this.requestAnchor(conn, peerRing, seq, head.id, head.key);
+    }
+    if (this.conns.get(conn.id) !== conn) return;
+    const now = loadState();
+    this.sendInner(conn, this.ownHead(now, this.ringCache.get(now.ring, this.log), peerRing));
+  }
+
+  /**
+   * Brings the stored log up to `until`: from the peer over the session first, then from the relay when it has the
+   * ring endpoints. Every entry is applied with RingState as it arrives (LogGrowth); the first that does not apply
+   * ends that source (a fork is only logged: fork handling is design only). Fetching holds no lock, so a slow peer
+   * delays nobody else; what was verified is merged into the stored log in one synchronous step (storeLog), and
+   * revocations in it take effect at once.
+   */
+          async catchUp(ringId        , until        , untilId               , conn             ) {
+    const state = loadState();
+    if (state.ring?.id !== ringId || state.ring.stalled) return;
+    const base = state.ring.entries;
+    let working           ;
+    try { working = replayAll(base); } catch (error) { return this.log(`device ring: the stored log does not replay, so it cannot grow: ${(error         ).message}`); }
+    if (until <= working.seq) {
+      if (until === working.seq && untilId && untilId !== b64url(working.head)) this.log(`device ring: ${conn?.deviceId ?? "the relay"} has another entry at seq ${until} (a fork?); keeping this computer's`);
+      return;
+    }
+    const growth = new LogGrowth(working, base, until);
+    if (conn) {
+      try { await this.pullFromPeer(conn, ringId, growth); } catch (error) { this.log(`device ring: ${conn.deviceId}: ${(error         ).message}`); }
+      if (growth.stopped && !growth.full) { this.log(`device ring: ${growth.stopped}`); growth.stopped = null; }
+    }
+    if (!growth.done && await this.relayRing.supported()) {
+      try { await this.relayRing.fetchInto(ringId, growth); } catch (error) { this.log(`device ring: could not catch up from the relay: ${(error         ).message}`); }
+      if (growth.stopped && !growth.full) this.log(`device ring: ${growth.stopped}`);
+    }
+    if (growth.state.seq === until && untilId && untilId !== b64url(growth.state.head)) this.log(`device ring: the head at seq ${until} is not the one ${conn?.deviceId ?? "the relay"} named (a fork?)`);
+    const stalled = growth.full ? growth.stopped : null;
+    if (stalled) this.log(`device ring: ${stalled} while there is more; the ring lets nobody in until "replica-bridge ring reset"`);
+    if (!growth.added.length && !stalled) return;
+    const stored = storeLog(ringId, base, growth.added, stalled);
+    if (stored) this.log(`device ring: caught up to seq ${stored.seq}${stored.removed.length ? `; removed ${stored.removed.join(", ")}, revoked in the ring, from the paired devices` : ""}`);
+    this.ringChanged();
+  }
+
+  /** After the relay socket opens, or a new anchor: entries the relay has that this computer missed. */
+          async catchUpFromRelay() {
+    try {
+      const state = loadState();
+      if (!state.ring || !(await this.relayRing.supported())) return;
+      await this.catchUp(state.ring.id, Number.MAX_SAFE_INTEGER, null, null);
+    } catch (error) {
+      this.log(`device ring: ${(error         ).message}`);
+    }
+  }
+
+  /** Handles the newest push only; pushes that arrive meanwhile replace each other. */
+          async onRingPush(push               ) {
+    if (!Number.isSafeInteger(push.seq) || typeof push.ring !== "string") return;
+    if (!this.nextPush || push.seq > this.nextPush.seq) this.nextPush = push;
+    if (this.pushRunning) return;
+    this.pushRunning = true;
+    try {
+      while (this.nextPush) {
+        const next = this.nextPush;
+        this.nextPush = null;
+        try {
+          const state = loadState();
+          if (state.ring && next.ring === state.ring.id) await this.catchUp(next.ring, next.seq, isKey32(next.id) ? next.id : null, null);
+        } catch (error) {
+          this.log(`device ring: ${(error         ).message}`);
+        }
+      }
+    } finally {
+      this.pushRunning = false;
+    }
+  }
+
+  /** Asks the peer for pages after the growth's head until it is done, the peer has no more, or a page brings nothing. */
+          async pullFromPeer(conn      , ringId        , growth           ) {
+    while (!growth.done) {
+      const after = growth.state.seq;
+      const answer = await this.askPeer(conn, { t: "ring/get", ring: ringId, ...(after >= 0 ? { after } : {}) });
+      const page = answer.ring === ringId ? wireEntries(answer.entries) : null;
+      if (!page) throw new Error("the peer answered ring/get with something else");
+      if (!growth.take(page, conn.deviceId) || !answer.more || !page.length) return;
+    }
+  }
+
+          askPeer(conn      , message              )                       {
+    return new Promise((resolve, reject) => {
+      if (this.conns.get(conn.id) !== conn) return reject(new Error("the peer left"));
+      const timer = setTimeout(() => {
+        if (conn.ringWaiter === done) conn.ringWaiter = null;
+        reject(new Error("the peer did not answer ring/get in time"));
+      }, this.ringWaitMs);
+      const done = (answer             ) => { clearTimeout(timer); resolve(answer); };
+      conn.ringWaiter = done;
+      this.sendInner(conn, message);
+    });
+  }
+
+  /**
+   * A paired signer named its ring and this computer has none yet: fetch the whole log (checked as it arrives, at most
+   * PENDING_LOG_MAX_BYTES), check the anchoring conditions (ring.ts checkAnchor) and record a pending anchor for a
+   * person here to confirm. Nothing else changes.
+   */
+          async requestAnchor(conn      , ringId        , seq        , headId        , signingKey        ) {
+    const admitted = conn.admitted ;
+    if (seq >= RING_LOG_MAX_ENTRIES) return this.log(`device ring: ${admitted.name}'s ring is longer than this bridge takes`);
+    let growth = new LogGrowth(new RingState(), [], seq, PENDING_LOG_MAX_BYTES);
+    try { await this.pullFromPeer(conn, ringId, growth); } catch (error) { this.log(`device ring: ${admitted.name}: ${(error         ).message}`); }
+    if (growth.state.seq < seq && !growth.full && await this.relayRing.supported()) {
+      growth = new LogGrowth(new RingState(), [], seq, PENDING_LOG_MAX_BYTES);
+      try { await this.relayRing.fetchInto(ringId, growth); } catch (error) { this.log(`device ring: could not read ring ${ringId} from the relay: ${(error         ).message}`); }
+    }
+    const entries = growth.added;
+    const state = loadState();
+    const checked = growth.full ? { refused: "the log is too long" } : checkAnchor(state, hostKeyPair(state).publicKey, { deviceId: conn.deviceId, key: admitted.key, signingKey: ringB64(signingKey), ring: ringId, entries });
+    const refused = "refused" in checked ? checked.refused : b64url(checked.ring.head) !== headId ? "the log does not end at the head it named" : null;
+    if (refused) return this.log(`device ring: not asking about ${admitted.name}'s request to anchor to ring ${ringId}: ${refused}`);
+    const fresh = !state.ringPending?.some((p) => p.ring === ringId);
+    const pending = { ring: ringId, entries, requester: { deviceId: conn.deviceId, name: admitted.name, key: b64url(admitted.key), signingKey }, requestedAt: new Date().toISOString() };
+    if (!recordPending(pending)) return this.log(`device ring: not recording ${admitted.name}'s request: this computer is anchored, or too many rings are waiting`);
+    if (!fresh) return;
+    const prompt = anchorPrompt(pending);
+    this.log(`device ring: ${prompt.requester} asks to anchor this computer to its ring (fingerprint ${prompt.fingerprint}); confirm with "npx replica-bridge ring accept"`);
+    this.options.onAnchorRequest?.(prompt);
+  }
+
+  /** Applies what state.json says now: drops whoever the ring no longer lets in, and tells ring peers a new head. */
+          ringChanged() {
+    let state             ;
+    try { state = loadState(); } catch { return; }
+    const ring = this.ringCache.get(state.ring, this.log);
+    this.enforceRing(state, ring);
+    const anchored = state.ring?.id ?? null;
+    if (anchored !== this.anchoredId) {
+      const first = this.anchoredId === undefined;
+      this.anchoredId = anchored;
+      // A new anchor carries the log as the requester sent it, maybe hours ago: revocations since then come first.
+      if (anchored && !first) void this.catchUpAfterAnchor(anchored);
+    }
+    const told = state.ring && ring ? `${state.ring.id}|${b64url(ring.head)}` : `-|${(state.ringPending ?? []).map((p) => p.ring).join(",")}`;
+    if (told === this.ringTold) return;
+    this.ringTold = told;
+    for (const conn of this.conns.values()) if (conn.ringPeer && conn.cipher) this.sendInner(conn, this.ownHead(state, ring, conn.peerRing));
+  }
+
+          async catchUpAfterAnchor(ringId        ) {
+    await this.catchUpFromRelay();
+    for (const conn of [...this.conns.values()]) {
+      if (conn.peerRing === ringId && conn.cipher) {
+        try { await this.catchUp(ringId, conn.peerSeq, null, conn); } catch (error) { this.log(`device ring: ${(error         ).message}`); }
+      }
+    }
+  }
+
+  /** Revocation takes effect at once: connections and kept streams of a device that would be refused now end. */
+          enforceRing(state             , ring                  ) {
+    if (!this.conns.size && !this.streams.size) return;
+    const hostKey = hostKeyPair(state).publicKey;
+    const refusal = (deviceId        , admitted          )                => {
+      const now = admit(state, ring, hostKey, deviceId, admitted.via === "ring" ? admitted.key : null);
+      if ("refused" in now) return now.refused;
+      return now.key.equals(admitted.key) ? null : "its key changed";
+    };
+    for (const conn of [...this.conns.values()]) {
+      const why = conn.admitted && refusal(conn.deviceId, conn.admitted);
+      if (!why) continue;
+      this.log(`dropping ${conn.admitted .name} (${conn.deviceId}): ${why}`);
+      if (conn.stream) this.endStream(conn.stream, why);
+      if (this.conns.has(conn.id)) this.closeConn(conn, why);
+    }
+    for (const stream of [...this.streams.values()]) {
+      const why = refusal(stream.deviceId, stream.admitted);
+      if (why) this.endStream(stream, why);
+    }
+  }
+
   // MARK: - Streams
 
           async resume(conn      , streamId               , peerAck        , segmented         ) {
     let stream = streamId ? this.streams.get(streamId) : undefined;
     const resumed = !!stream && stream.deviceId === conn.deviceId;
     if (!resumed) {
-      stream = await this.openStream(conn.deviceId);
+      stream = await this.openStream(conn.deviceId, conn.admitted );
       // The phone may have left while the app-server came up. It never heard this stream's id, so it cannot come back
       // for it, and detach found no stream to start the timer on: left alone, its proxy stays as long as the bridge.
       if (this.stopped || this.conns.get(conn.id) !== conn) return this.endStream(stream, "the phone left before its stream opened");
     }
     const s = stream ;
+    s.admitted = conn.admitted ;
     if (s.conn && s.conn !== conn) this.closeConn(s.conn, "resumed elsewhere");
     if (s.expiry) { clearTimeout(s.expiry); s.expiry = null; }
     s.conn = conn;
     s.segmented = segmented;
     conn.stream = s;
-    this.sendInner(conn, { t: "ready", stream: s.id, resumed, ack: s.in.received, seg: 1 });
+    this.sendInner(conn, { t: "ready", stream: s.id, resumed, ack: s.in.received, seg: 1, ring: 1 });
     // 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);
@@ -364,11 +733,11 @@ export class BridgeService {
     }
   }
 
-          async openStream(deviceId        )                  {
+          async openStream(deviceId        , admitted          )                  {
     const { ws: appServer, frameBytes } = await this.connectAppServer();
     const stream         = {
       id: crypto.randomBytes(12).toString("base64url"), deviceId, appServer, out: new StreamBuffer(STREAM_BUFFER_BYTES), in: new StreamBuffer(STREAM_BUFFER_BYTES),
-      conn: null, expiry: null, ackTimer: null, relayed: Promise.resolve(), segmented: false, chunks: new ChunkAssembler(), appServerFrameBytes: frameBytes,
+      conn: null, expiry: null, ackTimer: null, relayed: Promise.resolve(), segmented: false, chunks: new ChunkAssembler(), appServerFrameBytes: frameBytes, admitted,
     };
     this.streams.set(stream.id, stream);
     appServer.on("message", (data         ) => {
@@ -405,6 +774,8 @@ export class BridgeService {
   }
 
           detach(conn      ) {
+    if (conn.held) { clearTimeout(conn.held.timer); conn.held = null; }
+    conn.ringWaiter = null;
     conn.boardUnsubscribe?.();
     conn.boardUnsubscribe = null;
     const stream = conn.stream;
@@ -417,12 +788,13 @@ export class BridgeService {
 
           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);
     }
+    // After closing the connection: detach starts the stream's expiry, which an ended stream must not keep.
+    if (stream.expiry) clearTimeout(stream.expiry);
     stream.appServer.close();
     this.log(`closed stream ${stream.id}: ${reason}`);
   }
@@ -525,6 +897,11 @@ export class BridgeService {
   }
 }
 
+/** Messages a ring peer may send before its ring/head is handled; past this they go through anyway. */
+const HELD_MESSAGES_MAX = 1024;
+/** Nor more than this many bytes of them (sealed, as they came). */
+const HELD_BYTES_MAX = 32 * 1024 * 1024;
+
 /** 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;
 

package/src/bridge/state.js

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fromB64url, keyPairFromPrivate } from "../protocol.js";
-                                              
+                                                             
 
                                                                                                                      
 
@@ -20,6 +20,45 @@ import { fromB64url, keyPairFromPrivate } from "../protocol.js";
                          
                         
                           
+     
+                                                                                                             
+                                                                                                                 
+     
+                      
+                                                                                         
+                                
+     
+                                                                                                                   
+                                                                             
+     
+                                                       
+     
+                                                                                                              
+                                                                                              
+     
+                                                                                  
+ 
+
+                               
+             
+                           
+                     
+                                                       
+                                                 
+     
+                                                                                                                    
+                                                                                            
+     
+                   
+ 
+
+                                
+               
+                                                                               
+                           
+                                                                                                                           
+                                                                                 
+                      
  
 
 export const bridgeHome = () => process.env.REPLICA_BRIDGE_HOME ?? path.join(os.homedir(), ".config", "replica-bridge");
@@ -41,4 +80,17 @@ export function saveState(state             ) {
   fs.renameSync(temporary, statePath());
 }
 
+/**
+ * Reads state.json, changes it and writes it back in one synchronous step, so this process never interleaves two
+ * changes; another process (`replica-bridge pair`, `ring accept`) writes the same way and the window between is tiny.
+ */
+export function updateState(change                              )              {
+  const state = loadState();
+  change(state);
+  saveState(state);
+  return state;
+}
+
+export const statePathForWatch = statePath;
+
 export const hostKeyPair = (state             )          => keyPairFromPrivate(fromB64url(state.hostPrivateKey));