replica-bridge 0.3.19 → 0.3.22

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; }
+}