replica-bridge 0.3.20 → 0.3.22

package/src/protocol.js

@@ -232,8 +232,8 @@ export class FrameCipher {
 
 /** What is inside a data frame. */
                           
-                                                                
                                                                           
+                                                                                    
               
                 
                              
@@ -245,7 +245,8 @@ export class FrameCipher {
                         
               
                                  
-                                                 
+                                                
+                       
 
 /** Agens Work's main conversation on this computer, or why there is none (PROTOCOL.md "Work", 0.3.19). */
                                                                                                               
@@ -331,7 +332,7 @@ export class ChunkAssembler {
 
 /** Relay ↔ host multiplexing: one host WebSocket carries every phone connection. */
                           
-                                                  
+                                                                
                                                     
                                                       
 
@@ -385,3 +386,703 @@ export class StreamBuffer {
     return true;
   }
 }
+
+// MARK: - Device ring entries (ring-v1, PROTOCOL.md "设备环条目")
+//
+// The owner's devices form one ring: a log of entries, each signed with a signer's Ed25519 key and chained to the one
+// before by its hash. Whoever holds the log replays it with RingState and gets the same members. Only the entry format
+// and its rules are here; how the relay stores the log and how peers exchange it is still a design
+// (docs/design/DEVICE-RING.md), and nothing on the wire uses these yet. The relay-v1 handshake is unchanged.
+
+export const RING_PROTOCOL = "agens-ring-v1";
+/** First field of every entry, so an entry signature can never be mistaken for another message signed with the same key. */
+export const RING_ENTRY_TAG = `${RING_PROTOCOL}/entry`;
+export const RING_ENTRY_MAX_BYTES = 16 * 1024;
+export const RING_NAME_MAX_BYTES = 128;
+export const RING_MACHINE_MEMBERS_MAX = 64;
+const RING_NONCE_BYTES = 16;
+const RING_RECOVERY_MAX_BYTES = 1024;
+const RING_SSH_KEY_MAX_BYTES = 1024;
+const ZERO_HASH = Buffer.alloc(32);
+
+// Ed25519 keys as raw 32-byte values (CryptoKit's Curve25519.Signing rawRepresentation): the private key is the seed.
+const PKCS8_ED25519_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+const SPKI_ED25519_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+
+export function signingKeyPairFromPrivate(privateKey        )          {
+  if (privateKey.length !== 32) throw new Error("Ed25519 private keys are 32 bytes");
+  const key = crypto.createPrivateKey({ key: Buffer.concat([PKCS8_ED25519_PREFIX, privateKey]), format: "der", type: "pkcs8" });
+  const spki = crypto.createPublicKey(key).export({ format: "der", type: "spki" });
+  return { privateKey, publicKey: Buffer.from(spki.subarray(SPKI_ED25519_PREFIX.length)) };
+}
+
+export const generateSigningKeyPair = ()          => signingKeyPairFromPrivate(crypto.randomBytes(32));
+
+/** Ed25519 (RFC 8032, deterministic). CryptoKit's signatures are randomized, so they differ byte for byte but verify the same. */
+export function ed25519Sign(privateKey        , message        )         {
+  return crypto.sign(null, message, crypto.createPrivateKey({ key: Buffer.concat([PKCS8_ED25519_PREFIX, privateKey]), format: "der", type: "pkcs8" }));
+}
+
+/** Ed25519 verification (RFC 8032, strict), for a runtime whose node:crypto lacks it (bridge/embedded.ts). */
+                                                                                                             
+let ed25519Verifier                         = null;
+export function useEd25519Verifier(verifier                        ) { ed25519Verifier = verifier; }
+
+// Strict Ed25519 (PROTOCOL.md "签名的严格规则"): libraries disagree on small-order and non-canonical points and on
+// S >= L (CryptoKit accepts a small-order public key that OpenSSL refuses), and a log that one device accepts and
+// another refuses splits the ring for good. So these are checked here, byte by byte, before any library sees the
+// signature, and the answer never depends on which library or version runs.
+
+/** p = 2^255 - 19 and the group order L, little-endian as they are compared. */
+const ED25519_P = (1n << 255n) - 19n;
+export const ED25519_L = (1n << 252n) + 27742317777372353535851937790883648493n;
+const leInt = (bytes            )         => { let n = 0n; for (let i = bytes.length - 1; i >= 0; i--) n = (n << 8n) | BigInt(bytes[i]); return n; };
+
+/**
+ * The y-coordinates of the eight points of small order (1, 2, 4 and 8), as 255-bit little-endian integers: an
+ * encoding whose low 255 bits are one of these is refused whatever its sign bit (the sign-bit forms of y = 1 and
+ * y = p - 1 are also the non-canonical "-0"). Same list as libsodium's has_small_order, without its y >= p entries,
+ * which the canonical check below refuses.
+ */
+export const ED25519_SMALL_ORDER_Y                    = [
+  0n, // order 4: (±sqrt(-1), 0)
+  1n, // order 1: the identity
+  ED25519_P - 1n, // order 2
+  leInt(Buffer.from("26e8958fc2b227b045c3f489f2ef98f0d5dfac05d3c63339b13802886d53fc05", "hex")), // order 8
+  leInt(Buffer.from("c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac037a", "hex")), // order 8
+];
+
+/** Why a 32-byte point encoding is refused: "non-canonical" (y >= p), "small-order", or null when it is acceptable. */
+export function ed25519PointFault(encoded            )                                         {
+  if (encoded.length !== 32) return "non-canonical";
+  const y = leInt(encoded) & ((1n << 255n) - 1n);
+  if (y >= ED25519_P) return "non-canonical";
+  if (ED25519_SMALL_ORDER_Y.includes(y)) return "small-order";
+  return null;
+}
+
+/** The checks before verification: A and R canonical and not of small order, S < L. Null when they pass. */
+export function ed25519StrictFault(publicKey            , signature            )                {
+  if (publicKey.length !== 32 || signature.length !== 64) return "a public key is 32 bytes and a signature 64";
+  const a = ed25519PointFault(publicKey);
+  if (a) return `the public key is ${a}`;
+  const r = ed25519PointFault(signature.subarray(0, 32));
+  if (r) return `R is ${r}`;
+  if (leInt(signature.subarray(32)) >= ED25519_L) return "S is not below L";
+  return null;
+}
+
+export function ed25519Verify(publicKey        , message        , signature        )          {
+  if (ed25519StrictFault(publicKey, signature)) return false;
+  if (ed25519Verifier) { try { return ed25519Verifier(publicKey, message, signature); } catch { return false; } }
+  try {
+    return crypto.verify(null, message, crypto.createPublicKey({ key: Buffer.concat([SPKI_ED25519_PREFIX, publicKey]), format: "der", type: "spki" }), signature);
+  } catch {
+    return false;
+  }
+}
+
+/** A ring entry's fault, by a code both the Node and the Swift side report (test-vectors/device-ring-v1.json `invalid`). */
+export class RingError extends Error {
+           code        ;
+  constructor(code        , message        ) { super(`${code}: ${message}`); this.code = code; }
+}
+
+// The canonical encoding: every value is a byte string with a 4-byte big-endian length in front, numbers are 8-byte
+// big-endian, and nothing may follow the last field. Entries travel as these bytes, so nobody re-encodes before checking.
+// Every text rule below is defined on bytes or code points (PROTOCOL.md), never through regex anchors or trim, whose
+// meaning differs between JavaScript, Python and Swift.
+
+const u32 = (value        ) => { const out = Buffer.alloc(4); out.writeUInt32BE(value); return out; };
+const u64 = (value        ) => { const out = Buffer.alloc(8); out.writeBigUInt64BE(BigInt(value)); return out; };
+const bstr = (value                 ) => { const bytes = typeof value === "string" ? Buffer.from(value, "utf8") : value; return Buffer.concat([u32(bytes.length), bytes]); };
+
+/**
+ * Canonical base64url without padding, or `bad_encoding`: only [A-Za-z0-9_-], a length that is not 1 modulo 4, and
+ * zero unused bits in the last character (so every byte string has exactly one spelling). Buffer.from(…, "base64url")
+ * alone skips characters it does not know.
+ */
+export function ringB64(text        )         {
+  if (typeof text !== "string" || text.length % 4 === 1) throw new RingError("bad_encoding", "not canonical base64url");
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    const ok = (c >= 0x41 && c <= 0x5a) || (c >= 0x61 && c <= 0x7a) || (c >= 0x30 && c <= 0x39) || c === 0x2d || c === 0x5f;
+    if (!ok) throw new RingError("bad_encoding", "not canonical base64url");
+  }
+  const bytes = Buffer.from(text, "base64url");
+  if (b64url(bytes) !== text) throw new RingError("bad_encoding", "not canonical base64url");
+  return bytes;
+}
+
+/** What an entry says, before it is signed. */
+                                
+                                                            
+              
+                                                                                              
+               
+               
+                                         
+                 
+                                                                                                            
+             
+                                                      
+                   
+ 
+
+/** An entry on the wire and on disk: the exact encoded bytes and the signer's signature over them. */
+                                                       
+
+const isLower = (b        ) => b >= 0x61 && b <= 0x7a;
+const isDigit = (b        ) => b >= 0x30 && b <= 0x39;
+/** `kind`: 1–32 bytes, the first a–z, the rest a–z, 0–9 or `-`. */
+function isKind(bytes        )          {
+  if (bytes.length < 1 || bytes.length > 32 || !isLower(bytes[0])) return false;
+  for (const b of bytes) if (!isLower(b) && !isDigit(b) && b !== 0x2d) return false;
+  return true;
+}
+/** `type`: 1–32 bytes, each a–z, 0–9 or `-`. */
+function isType(bytes        )          {
+  if (bytes.length < 1 || bytes.length > 32) return false;
+  for (const b of bytes) if (!isLower(b) && !isDigit(b) && b !== 0x2d) return false;
+  return true;
+}
+
+export function encodeRingEntry(body               )         {
+  for (const n of [body.seq, body.at]) if (!Number.isSafeInteger(n) || n < 0) throw new RingError("bad_encoding", "seq and at are non-negative integers");
+  return Buffer.concat([
+    bstr(RING_ENTRY_TAG), u64(body.seq), bstr(body.prev), bstr(body.kind), bstr(body.signer), u64(body.at),
+    u32(body.fields.length), ...body.fields.map((field) => bstr(field)),
+  ]);
+}
+
+/** Strict: the size, the tag, every length, no bytes left over, then prev, signer and kind. */
+export function decodeRingEntry(bytes        )                {
+  if (bytes.length > RING_ENTRY_MAX_BYTES) throw new RingError("too_large", `an entry is at most ${RING_ENTRY_MAX_BYTES} bytes`);
+  let offset = 0;
+  const need = (n        ) => { if (offset + n > bytes.length) throw new RingError("bad_encoding", "entry ends early"); };
+  const readU32 = () => { need(4); const v = bytes.readUInt32BE(offset); offset += 4; return v; };
+  const readU64 = () => {
+    need(8); const v = bytes.readBigUInt64BE(offset); offset += 8;
+    if (v > BigInt(Number.MAX_SAFE_INTEGER)) throw new RingError("bad_encoding", "number out of range");
+    return Number(v);
+  };
+  const readBytes = () => { const n = readU32(); need(n); const v = bytes.subarray(offset, offset + n); offset += n; return Buffer.from(v); };
+  if (!readBytes().equals(Buffer.from(RING_ENTRY_TAG))) throw new RingError("bad_encoding", "not a ring-v1 entry");
+  const seq = readU64();
+  const prev = readBytes();
+  const kind = readBytes();
+  const signer = readBytes();
+  const at = readU64();
+  const count = readU32();
+  const fields           = [];
+  for (let i = 0; i < count; i++) fields.push(readBytes());
+  if (offset !== bytes.length) throw new RingError("bad_encoding", "bytes after the last field");
+  if (prev.length !== 32 || signer.length !== 32) throw new RingError("bad_encoding", "prev and signer are 32 bytes");
+  if (!isKind(kind)) throw new RingError("bad_encoding", "kind is 1-32 bytes of a-z, 0-9 and -, starting with a-z");
+  return { seq, prev, kind: kind.toString("latin1"), signer, at, fields };
+}
+
+/** An entry's id: SHA-256 of its encoded bytes. The signature is not part of it, so a re-signed copy keeps its id. */
+export const ringEntryId = (bytes        )         => sha256(bytes);
+
+export function signRingEntry(signing         , body                               )                {
+  const bytes = encodeRingEntry({ ...body, signer: signing.publicKey });
+  return { e: b64url(bytes), s: b64url(ed25519Sign(signing.privateKey, bytes)) };
+}
+
+                                           
+/** `x25519`: a relay-v1 key (Hs or Ds). `ssh`: an SSH server's host key, the OpenSSH public key blob; members only. */
+                                           
+
+/** Who a genesis or add entry brings in. */
+                                 
+                       
+              
+                                                       
+                            
+                 
+               
+                                                                                                                       
+               
+ 
+
+                                                    
+                                                                                                                
+             
+                  
+                           
+ 
+
+                                                                            
+
+const memberFields = (m                )           => [
+  Buffer.from(m.keyType), m.key, m.signingKey ?? Buffer.alloc(0), Buffer.from(m.role), Buffer.from(m.name, "utf8"), Buffer.from(m.type),
+];
+
+/**
+ * Code points a name may not contain anywhere: C0 and C1 controls, DEL, the bidi marks and overrides the relay strips
+ * (server.ts cleanName), the line and paragraph separators, and U+FEFF.
+ */
+function nameForbidden(cp        )          {
+  return cp <= 0x1f || (cp >= 0x7f && cp <= 0x9f) || cp === 0x061c || cp === 0x200e || cp === 0x200f || cp === 0x2028 || cp === 0x2029
+    || (cp >= 0x202a && cp <= 0x202e) || (cp >= 0x2066 && cp <= 0x2069) || cp === 0xfeff;
+}
+/** Spaces a name may not start or end with (the rest of Unicode's Zs; the other whitespace is forbidden anywhere). */
+function nameEdgeSpace(cp        )          {
+  return cp === 0x20 || cp === 0xa0 || cp === 0x1680 || (cp >= 0x2000 && cp <= 0x200a) || cp === 0x202f || cp === 0x205f || cp === 0x3000;
+}
+const strictUTF8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+
+/** The name rules (PROTOCOL.md): 1–128 bytes (0 allowed where noted), strict UTF-8, no forbidden code points, no edge spaces. */
+function checkName(bytes        , allowEmpty = false)         {
+  if (bytes.length > RING_NAME_MAX_BYTES || (!allowEmpty && bytes.length === 0)) throw new RingError("bad_fields", `a name is 1 to ${RING_NAME_MAX_BYTES} bytes`);
+  let name        ;
+  try { name = strictUTF8.decode(bytes); } catch { throw new RingError("bad_fields", "a name is UTF-8"); }
+  const points = Array.from(name, (c) => c.codePointAt(0) );
+  if (points.some(nameForbidden)) throw new RingError("bad_fields", "a name has no control, bidi, separator or U+FEFF characters");
+  if (points.length && (nameEdgeSpace(points[0]) || nameEdgeSpace(points[points.length - 1]))) throw new RingError("bad_fields", "a name does not start or end with a space");
+  return name;
+}
+
+/** Something a person can see: not whitespace, not a default-ignorable or format character, not a lone mark. */
+const VISIBLE = /[^\p{White_Space}\p{Default_Ignorable_Code_Point}\p{Cc}\p{Cf}\p{M}]/u;
+
+/**
+ * Makes a name the rules accept, for a signer about to sign one it did not type (a computer's name from the relay):
+ * drops forbidden code points and lone surrogates, drops edge spaces, and cuts at a code point boundary to fit 128
+ * UTF-8 bytes. A name with nothing visible left becomes `fallback`. The result is exactly what it encodes to (no
+ * U+FFFD stands in for anything), so the bytes signed are the string shown.
+ */
+export function ringName(text        , fallback        )         {
+  let points = Array.from(text).filter((c) => {
+    const cp = c.codePointAt(0) ;
+    return !nameForbidden(cp) && !(cp >= 0xd800 && cp <= 0xdfff);
+  });
+  const trim = () => {
+    while (points.length && nameEdgeSpace(points[0].codePointAt(0) )) points.shift();
+    while (points.length && nameEdgeSpace(points[points.length - 1].codePointAt(0) )) points.pop();
+  };
+  trim();
+  let bytes = 0;
+  const kept           = [];
+  for (const c of points) {
+    bytes += Buffer.byteLength(c, "utf8");
+    if (bytes > RING_NAME_MAX_BYTES) break;
+    kept.push(c);
+  }
+  points = kept;
+  trim();
+  const name = points.join("");
+  return VISIBLE.test(name) ? name : fallback;
+}
+
+const bytesAre = (bytes        , text        ) => bytes.equals(Buffer.from(text, "latin1"));
+
+/** keyType, key, role, the signing key for that role, type, then name; every fault is bad_fields. */
+function parseMemberFields(fields          )                 {
+  const [keyTypeBytes, key, signingKeyBytes, roleBytes, nameBytes, typeBytes] = fields;
+  let keyType             ;
+  if (bytesAre(keyTypeBytes, "x25519")) { keyType = "x25519"; if (key.length !== 32) throw new RingError("bad_fields", "an x25519 key is 32 bytes"); }
+  else if (bytesAre(keyTypeBytes, "ssh")) { keyType = "ssh"; if (key.length < 1 || key.length > RING_SSH_KEY_MAX_BYTES) throw new RingError("bad_fields", "an ssh key is 1 to 1024 bytes"); }
+  else throw new RingError("bad_fields", "keyType is x25519 or ssh");
+  let role          ;
+  if (bytesAre(roleBytes, "signer")) role = "signer";
+  else if (bytesAre(roleBytes, "member")) role = "member";
+  else throw new RingError("bad_fields", "role is signer or member");
+  if (role === "signer" && (signingKeyBytes.length !== 32 || keyType !== "x25519")) throw new RingError("bad_fields", "a signer has a 32-byte signing key and an x25519 key");
+  // A small-order signing key lets anyone sign for it under some libraries and nobody under others: the ring splits.
+  if (role === "signer" && ed25519PointFault(signingKeyBytes)) throw new RingError("bad_fields", `the signing key is ${ed25519PointFault(signingKeyBytes)}`);
+  if (role === "member" && signingKeyBytes.length !== 0) throw new RingError("bad_fields", "a member has no signing key");
+  if (!isType(typeBytes)) throw new RingError("bad_fields", "type is 1-32 bytes of a-z, 0-9 and -");
+  const name = checkName(nameBytes);
+  return { keyType, key, signingKey: role === "signer" ? signingKeyBytes : null, role, name, type: typeBytes.toString("latin1") };
+}
+
+const signingKeyId = (key        ) => `ed25519:${b64url(key)}`;
+
+/**
+ * Checks a member the way an `add` entry with these fields would (bad_fields, RingError), without a ring: what a
+ * relay checks in a join claim, so the signer is never handed a name or key it could not sign into the ring.
+ */
+export function checkRingMember(info                )       {
+  parseMemberFields(memberFields(info));
+}
+
+/**
+ * The members a log describes. `apply` checks one entry against everything before it and changes nothing when the
+ * entry is refused, so the relay, a bridge and a phone that replay the same log end with the same state.
+ */
+export class RingState {
+  /** The genesis entry's id; null until genesis is applied. */
+  ringId                = null;
+  /** The last applied entry's seq and id. */
+  seq = -1;
+  head         = ZERO_HASH;
+           members = new Map                    ();
+           machines = new Map                     ();
+  /** Keys revoked in this ring (`x25519:…`, `ssh:…`, `ed25519:…`); they never come back, the device makes new ones. */
+           retired = new Set        ();
+  /** Entries of a kind this version does not know (controller and controller-revoke included): chained, no effect. */
+  ignored = 0;
+
+  get active()               { return [...this.members.values()].filter((m) => m.revokedAt === null); }
+  get signers()               { return this.active.filter((m) => m.role === "signer"); }
+
+  /** The active signers' X25519 keys (signers always have one). */
+  signerKeys()           { return this.signers.map((m) => m.key); }
+
+  isRevokedKey(keyType             , key        )          { return this.retired.has(`${keyType}:${b64url(key)}`); }
+
+  activeMemberWithKey(keyType             , key        )                         {
+    return this.active.find((m) => m.keyType === keyType && m.key.equals(key));
+  }
+
+  /** An independent copy: applying to it leaves this one as it is (the relay checks a request on a copy). */
+  clone()            {
+    const copy = new RingState();
+    copy.ringId = this.ringId;
+    copy.seq = this.seq;
+    copy.head = this.head;
+    copy.ignored = this.ignored;
+    for (const [id, member] of this.members) copy.members.set(id, { ...member });
+    for (const [id, machine] of this.machines) copy.machines.set(id, { ...machine, members: [...machine.members] });
+    for (const key of this.retired) copy.retired.add(key);
+    return copy;
+  }
+
+  /**
+   * Checks and applies one entry; returns its id. Throws RingError and leaves the state as it was when refused.
+   * `verified`: the caller already checked this exact signature (the relay replaying entries it stored after checking
+   * them); every other rule still runs. Never for an entry that came from anyone else.
+   */
+  apply(entry               , options                         = {})         {
+    const bytes = ringB64(entry.e);
+    const signature = ringB64(entry.s);
+    const body = decodeRingEntry(bytes);
+    const id = ringEntryId(bytes);
+    if (body.seq !== this.seq + 1) throw new RingError("wrong_seq", `expected seq ${this.seq + 1}, got ${body.seq}`);
+    if (!body.prev.equals(this.head)) throw new RingError("wrong_prev", "prev is not the id of the entry before");
+    if (!options.verified && !ed25519Verify(body.signer, bytes, signature)) throw new RingError("bad_signature", "the signature does not verify");
+    if ((this.ringId === null) !== (body.kind === "genesis")) throw new RingError("bad_genesis", "genesis is the first entry and only the first");
+    const effect = this.ringId === null ? this.genesis(body, id) : this.entry(body, id);
+    effect();
+    this.seq = body.seq;
+    this.head = id;
+    return id;
+  }
+
+  /** The member a 32-byte id names, if it is still active. */
+          activeMember(idBytes        )             {
+    if (idBytes.length !== 32) throw new RingError("bad_fields", "a member id is 32 bytes");
+    const member = this.members.get(b64url(idBytes));
+    if (!member || member.revokedAt !== null) throw new RingError("unknown_member", "no active member has this id");
+    return member;
+  }
+
+          checkNewKeys(info                ) {
+    if (this.isRevokedKey(info.keyType, info.key) || (info.signingKey && this.retired.has(signingKeyId(info.signingKey)))) {
+      throw new RingError("retired_key", "a key revoked in this ring cannot come back");
+    }
+    for (const m of this.active) {
+      if ((m.keyType === info.keyType && m.key.equals(info.key)) || (info.signingKey && m.signingKey?.equals(info.signingKey))) {
+        throw new RingError("duplicate_key", "an active member already has this key");
+      }
+    }
+  }
+
+  // Each returns a closure that makes the change, so nothing changes until every check has passed. The checks run in
+  // the order PROTOCOL.md lists, which decides the error code when an entry has several faults.
+
+          genesis(body               , id        )             {
+    if (body.fields.length !== 8) throw new RingError("bad_fields", "genesis has 8 fields");
+    const [nonce, recovery, ...rest] = body.fields;
+    if (nonce.length !== RING_NONCE_BYTES) throw new RingError("bad_fields", "the genesis nonce is 16 bytes");
+    if (recovery.length > RING_RECOVERY_MAX_BYTES) throw new RingError("bad_fields", "the recovery field is at most 1024 bytes");
+    const info = parseMemberFields(rest);
+    if (info.role !== "signer" || !info.signingKey .equals(body.signer)) throw new RingError("bad_genesis", "genesis is signed by the signer it founds");
+    return () => {
+      this.ringId = id;
+      this.members.set(b64url(id), { ...info, id: b64url(id), addedAt: 0, revokedAt: null });
+    };
+  }
+
+          entry(body               , entryId        )             {
+    const by = this.signers.find((m) => m.signingKey .equals(body.signer));
+    if (!by) throw new RingError("not_signer", "the entry is not signed by an active signer");
+    const { fields } = body;
+    switch (body.kind) {
+      case "add": {
+        if (fields.length !== 6) throw new RingError("bad_fields", "add has 6 fields");
+        const info = parseMemberFields(fields);
+        this.checkNewKeys(info);
+        const id = b64url(entryId);
+        return () => { this.members.set(id, { ...info, id, addedAt: body.seq, revokedAt: null }); };
+      }
+      case "revoke": {
+        if (fields.length !== 2) throw new RingError("bad_fields", "revoke has 2 fields");
+        const member = this.activeMember(fields[0]);
+        checkName(fields[1], true);
+        if (member.role === "signer" && this.signers.length === 1) throw new RingError("last_signer", "a ring keeps at least one signer");
+        return () => {
+          member.revokedAt = body.seq;
+          this.retired.add(`${member.keyType}:${b64url(member.key)}`);
+          if (member.signingKey) this.retired.add(signingKeyId(member.signingKey));
+          this.leaveMachines([member.id]);
+        };
+      }
+      case "machine": {
+        if (fields.length < 2 || fields.length > 2 + RING_MACHINE_MEMBERS_MAX) throw new RingError("bad_fields", `machine has 2 to ${2 + RING_MACHINE_MEMBERS_MAX} fields`);
+        const [machineIdBytes, nameBytes, ...memberIds] = fields;
+        if (machineIdBytes.length !== RING_NONCE_BYTES) throw new RingError("bad_fields", "a machine id is 16 bytes");
+        const machineId = b64url(machineIdBytes);
+        const members = memberIds.map((m) => this.activeMember(m).id);
+        if (new Set(members).size !== members.length) throw new RingError("bad_fields", "a machine lists a member once");
+        const name = checkName(nameBytes, members.length === 0);
+        if (members.length === 0 && !this.machines.has(machineId)) throw new RingError("unknown_machine", "only an existing machine can be emptied");
+        return () => {
+          this.machines.delete(machineId);
+          this.leaveMachines(members);
+          if (members.length) this.machines.set(machineId, { id: machineId, name, members });
+        };
+      }
+      default:
+        // Kinds this version does not know, including the reserved controller and controller-revoke: their fields are
+        // whatever a later version defines, so v1 checks none of them and gives them no effect.
+        return () => { this.ignored++; };
+    }
+  }
+
+          leaveMachines(memberIds          ) {
+    for (const machine of [...this.machines.values()]) {
+      machine.members = machine.members.filter((m) => !memberIds.includes(m));
+      if (machine.members.length === 0) this.machines.delete(machine.id);
+    }
+  }
+}
+
+/** Replays a whole log from genesis. */
+export function replayRing(entries                 )            {
+  const state = new RingState();
+  for (const entry of entries) state.apply(entry);
+  return state;
+}
+
+// Builders for the signer's side. Each signs on top of `state` (its seq and head); the caller applies the result.
+
+export function ringGenesis(signing         , founder                                             , options                                )                {
+  const nonce = options.nonce ?? crypto.randomBytes(RING_NONCE_BYTES);
+  const fields = [nonce, Buffer.alloc(0), ...memberFields({ ...founder, signingKey: signing.publicKey, role: "signer" })];
+  return signRingEntry(signing, { seq: 0, prev: ZERO_HASH, kind: "genesis", at: options.at, fields });
+}
+
+function ringNext(signing         , state           , kind        , fields          , at        )                {
+  if (state.ringId === null) throw new Error("the ring has no genesis yet");
+  return signRingEntry(signing, { seq: state.seq + 1, prev: state.head, kind, at, fields });
+}
+
+export const ringAdd = (signing         , state           , member                , at        ) => ringNext(signing, state, "add", memberFields(member), at);
+export const ringRevoke = (signing         , state           , memberId        , reason        , at        ) =>
+  ringNext(signing, state, "revoke", [memberId, Buffer.from(reason, "utf8")], at);
+/** Says these members are one machine (replacing what the machine listed before); no members dissolves it. */
+export const ringMachine = (signing         , state           , machineId        , name        , memberIds          , at        ) =>
+  ringNext(signing, state, "machine", [machineId, Buffer.from(name, "utf8"), ...memberIds], at);
+
+// MARK: - Device ring on the relay (PROTOCOL.md "设备环：中转服务器")
+
+/**
+ * GET /v1/ring/capabilities; an older relay answers 404. `join` is there on a relay with the join endpoints
+ * (PROTOCOL.md "设备环：加入新的签名者"); a relay from before them leaves it out, and the app offers no join.
+ */
+                                                                       
+/** A ring's head as the relay has it: the answer to a create or append, and the start of a read. */
+                                                                       
+/** GET /v1/ring/<ring>?after=&wait=: up to 256 entries after `after`; `more` when there are further ones. */
+                                                                                        
+/**
+ * Relay to a computer connected with /v1/host?ring=1: the ring it is in (or was, when this entry removed it) has this
+ * head now. Also sent once when such a computer connects. Bridges that did not ask never get it.
+ */
+                                                            
+
+// MARK: - Device ring on the session (PROTOCOL.md "设备环：电脑一侧", bridge 0.3.21)
+//
+// A phone that says `ring` in resume, and a bridge that says it in ready, compare their logs right after the
+// handshake and the older one catches up from the other, inside the encrypted session where the relay can neither
+// hold entries back nor change them. A board connection has no resume: the bridge lists `ring` in board/state's caps.
+
+/** Most entries in one ring/entries frame. */
+export const RING_ENTRIES_PER_FRAME = 256;
+
+/**
+ * Where a peer's log is. `ring: null` is no ring (or, from a bridge, not anchored yet); a bridge waiting for its owner
+ * to confirm an anchor names that ring in `pending`. `key` is a signer's Ed25519 key, which only signers send.
+ */
+                                                                                                                          
+/** Asks for the entries after `after`; without it, from genesis. */
+                                                                      
+                                                                                                     
+                                                                  
+
+/**
+ * Six digits a person compares between the computer and the app before a computer anchors to a ring: like the
+ * pairing safety code, SHA-256 under its own label, the first four bytes big-endian modulo 1,000,000.
+ */
+export function ringFingerprint(ringId        )         {
+  const digest = sha256(Buffer.from(`${RING_PROTOCOL}|fingerprint`), ringId);
+  return String(digest.readUInt32BE(0) % 1_000_000).padStart(6, "0");
+}
+
+// MARK: - Joining a new signer (PROTOCOL.md "设备环：加入新的签名者")
+//
+// A signer already in the ring shows chatreplica://ring?…; the new device (a second iPhone, an iPad, agens-desktop)
+// scans it, makes its Ed25519 signing key, and hands the relay its keys with three proofs: `proof` (it saw the QR
+// code, and these are its keys, name and type: an HMAC under the QR's secret, which the relay never has), `pop` (it
+// holds the signing key) and `dhProof` (it holds the X25519 key: a MAC keyed by X25519 between it and the signer).
+// The signer checks all three on its own device and then appends an ordinary `add` with role signer; the relay checks
+// only `pop`, and stores and forwards.
+
+/** First field of the join proof of possession, so it can never be taken for an entry or another message. */
+export const RING_JOIN_TAG = `${RING_PROTOCOL}/join`;
+
+/** The signing tag of `pop`, the tags of `proof` and `dhProof`, and the HKDF label of the `dhProof` key. */
+const RING_JOIN_PROOF_TAG = `${RING_PROTOCOL}/join-proof`;
+const RING_JOIN_DH_TAG = `${RING_PROTOCOL}/join-dh`;
+const RING_JOIN_DH_KEY_INFO = `${RING_PROTOCOL}/join-dh-key`;
+
+                               
+                
+                                                        
+               
+               
+                 
+                                                                                                         
+                    
+                                                               
+                
+ 
+
+/** chatreplica://ring?v=1&r=<relay URL>&g=<ring id>&c=<code>&s=<secret>&k=<signer X25519 key>&n=<signer name> */
+export function buildRingJoinLink(link              )         {
+  const params = new URLSearchParams({ v: "1", r: link.relay, g: b64url(link.ring), c: normalizeCode(link.code), s: b64url(link.secret), k: b64url(link.signerKey) });
+  if (link.name) params.set("n", link.name);
+  return `chatreplica://ring?${params}`;
+}
+
+export function parseRingJoinLink(text        )               {
+  const url = new URL(text.trim());
+  if (url.protocol !== LINK_SCHEME || url.hostname !== "ring") throw new Error("not a chatreplica://ring link");
+  const get = (name        ) => {
+    const value = url.searchParams.get(name);
+    if (!value) throw new Error(`ring link is missing ${name}`);
+    return value;
+  };
+  if (get("v") !== "1") throw new Error("unsupported ring link version");
+  const relay = new URL(get("r"));
+  if (relay.protocol !== "https:" && relay.protocol !== "http:") throw new Error("relay must be an http(s) URL");
+  const ring = ringB64(get("g"));
+  const secret = ringB64(get("s"));
+  const signerKey = ringB64(get("k"));
+  if (ring.length !== 32 || secret.length !== 32 || signerKey.length !== 32) throw new Error("ring link id, secret or key has the wrong length");
+  return { relay: get("r"), ring, code: normalizeCode(get("c")), secret, signerKey, name: url.searchParams.get("n") ?? undefined };
+}
+
+/** What a claim says about the new device, which `proof` and `dhProof` cover. `name` is the exact UTF-8 the add will carry. */
+                                                                                                    
+
+/**
+ * P = bstr("agens-ring-v1/join-proof") ‖ bstr(code) ‖ bstr(X25519 key) ‖ bstr(signing key) ‖ bstr(name) ‖ bstr(type)
+ * proof = HMAC-SHA256(key: secret, P): the device that claims saw the QR code, and these are the keys, name and type it
+ * claims with. The relay never has the secret (not even its hash), so it can neither swap the keys nor relabel the
+ * device; only the signer that showed the code can check it.
+ */
+export function ringJoinProofMessage(code        , claim                     )         {
+  return Buffer.concat([bstr(RING_JOIN_PROOF_TAG), bstr(normalizeCode(code)), bstr(claim.key), bstr(claim.signingKey), bstr(claim.name), bstr(claim.type)]);
+}
+
+export function ringJoinProof(secret        , code        , claim                     )         {
+  return crypto.createHmac("sha256", secret).update(ringJoinProofMessage(code, claim)).digest();
+}
+
+export function verifyRingJoinProof(secret        , code        , claim                     , proof        )          {
+  const expected = ringJoinProof(secret, code, claim);
+  return proof.length === expected.length && crypto.timingSafeEqual(proof, expected);
+}
+
+/**
+ * dhProof: the new device holds the private half of its X25519 key (`pop` only covers the signing key, and the relay
+ * never checks a key's private half when a phone signs in).
+ *   Z = X25519(new device's private key, signer's X25519 key from the QR) = X25519(signer's private key, new device's key)
+ *   K = HKDF-SHA256(ikm: Z, salt: ring id, info: "agens-ring-v1/join-dh-key", 32 bytes)
+ *   T = bstr("agens-ring-v1/join-dh") ‖ bstr(ring id) ‖ bstr(code) ‖ bstr(signer's X25519 key) ‖ bstr(new X25519 key)
+ *       ‖ bstr(signing key) ‖ bstr(name) ‖ bstr(type)
+ *   dhProof = HMAC-SHA256(key: K, T)
+ * Only the two devices can compute Z; the relay cannot. A Z of 32 zero bytes (a small-order key) is refused.
+ */
+export function ringJoinDhMessage(ring        , code        , signerKey        , claim                     )         {
+  return Buffer.concat([
+    bstr(RING_JOIN_DH_TAG), bstr(ring), bstr(normalizeCode(code)), bstr(signerKey), bstr(claim.key), bstr(claim.signingKey), bstr(claim.name), bstr(claim.type),
+  ]);
+}
+
+/** K from Z; throws on an all-zero Z. */
+export function ringJoinDhKey(shared        , ring        )         {
+  if (shared.length !== 32 || shared.every((b) => b === 0)) throw new Error("the X25519 shared secret is all zero");
+  return Buffer.from(crypto.hkdfSync("sha256", shared, ring, Buffer.from(RING_JOIN_DH_KEY_INFO), 32));
+}
+
+/** The new device's side: Z from its own private key and the signer's key in the QR. */
+export function ringJoinDhProof(devicePrivateKey        , ring        , code        , signerKey        , claim                     )         {
+  let shared        ;
+  try { shared = dh(devicePrivateKey, signerKey); } catch { throw new Error("the X25519 shared secret is all zero"); }
+  return crypto.createHmac("sha256", ringJoinDhKey(shared, ring)).update(ringJoinDhMessage(ring, code, signerKey, claim)).digest();
+}
+
+/** The signer's side: Z from its own private key and the claimed key. False on any fault, an all-zero Z included. */
+export function verifyRingJoinDhProof(signer         , ring        , code        , claim                     , mac        )          {
+  let key        ;
+  try { key = ringJoinDhKey(dh(signer.privateKey, claim.key), ring); } catch { return false; }
+  const expected = crypto.createHmac("sha256", key).update(ringJoinDhMessage(ring, code, signer.publicKey, claim)).digest();
+  return mac.length === expected.length && crypto.timingSafeEqual(mac, expected);
+}
+
+/** What `pop` signs: bstr("agens-ring-v1/join") ‖ bstr(ring id) ‖ bstr(code) ‖ bstr(X25519 key). */
+export function ringJoinPopMessage(ring        , code        , key        )         {
+  return Buffer.concat([bstr(RING_JOIN_TAG), bstr(ring), bstr(normalizeCode(code)), bstr(key)]);
+}
+
+/** pop = Ed25519(the new signing key, ringJoinPopMessage): the device holds the signing key it claims with. */
+export const ringJoinPop = (signing         , ring        , code        , key        )         =>
+  ed25519Sign(signing.privateKey, ringJoinPopMessage(ring, code, key));
+
+/** Strict Ed25519 (PROTOCOL.md "签名的严格规则"), as for entries: a small-order or non-canonical signing key never verifies. */
+export const verifyRingJoinPop = (signingKey        , ring        , code        , key        , pop        )          =>
+  ed25519Verify(signingKey, ringJoinPopMessage(ring, code, key), pop);
+
+/** POST /v1/ring/<ring>/join/start {} (no secret, nor its hash, goes to the relay) */
+                                                                    
+/** POST /v1/ring/join/claim; every key and the proofs in base64url. `key` is the claiming phone's own X25519 key. */
+                                       
+                                                                                                                                            
+ 
+/** `code` is the join's code, by which status and approval find it (the QR's code, normalized). */
+                                                                                  
+/** GET /v1/ring/join/claim?code=, for the signer that started the join. The claim's fields are there once claimed. */
+                               
+                                                                   
+               
+                    
+                    
+                     
+               
+                      
+                
+                
+                 
+               
+                   
+                                                
+                                                                                               
+                  
+ 
+/** GET /v1/ring/join/status?code=, for the device that claimed. */
+