realtimeclipboard 0.7.0 → 1.0.0

package/src/core/frames.js

@@ -0,0 +1,117 @@
+/**
+ * Sealing and opening signalling frames.
+ *
+ * The relay is a blind pipe (docs/P2P-FILES.md §4). Signalling in the clear
+ * would hand it every SDP, every ICE candidate — including peer IPs — and, on
+ * the fallback path, every byte of every file. Routing fields stay readable
+ * because the relay must deliver the frame; everything else is sealed with the
+ * session key.
+ *
+ * Its own module rather than a pair of private functions in main.js because
+ * both halves of it are security rules — what may travel unsealed, and what a
+ * payload may not claim — and a rule with no test is a rule until someone
+ * edits it.
+ */
+
+import * as cryptoBox from "./crypto.js";
+import * as state from "./state.js";
+
+/**
+ * Readable to the relay, because it has to route on them. `from` is the one the
+ * relay STAMPS: it is the connection a frame arrived on, and the only field a
+ * client cannot choose.
+ */
+export const ROUTING_FIELDS = new Set([
+  "t", "to", "from", "originId", "id", "seq", "total", "crc",
+]);
+
+/**
+ * Frame types allowed to arrive with no envelope, because they carry nothing
+ * but routing. Set by the composition root from the files layer's own list —
+ * inferring it would mean guessing, and guessing wrong in the permissive
+ * direction is the bug this exists to prevent.
+ */
+let plaintext = new Set();
+
+export function setPlaintextFrames(types) {
+  plaintext = new Set(types ?? []);
+}
+
+/**
+ * The key-taking forms. `encryptFrame`/`decryptFrame` are these with the
+ * session's key filled in, and they exist separately because `cli/session.mjs`
+ * — the half `cli/`, `mcp/`, `vscode/` and `browser/` all share — holds its key
+ * in its own object and never touches `core/state.js`. Without these it would
+ * have to hand-roll the split-seal-strip dance to answer one frame, which is
+ * the reimplementation those surfaces are forbidden.
+ */
+export async function sealWith(aesKey, frame) {
+  if (!aesKey) return frame;
+
+  const routing = {}, secret = {};
+  for (const [k, v] of Object.entries(frame)) {
+    (ROUTING_FIELDS.has(k) ? routing : secret)[k] = v;
+  }
+  if (!Object.keys(secret).length) return frame;
+
+  const { payload, iv } = await cryptoBox.encrypt(aesKey, JSON.stringify(secret));
+  return { ...routing, payload, iv };
+}
+
+export const encryptFrame = (frame) => sealWith(state.get().aesKey, frame);
+
+/**
+ * Open a sealed frame, or refuse it. Two things this must not do, both of which
+ * it used to.
+ *
+ * It must not pass an UNSEALED frame through. A frame arriving with no envelope
+ * was returned as it came, so anything that could reach the relay — the relay
+ * itself included — could inject editor text, fake file announcements with
+ * their thumbnails, and RTC negotiation into a session whose key it does not
+ * hold. Only frames carrying nothing BUT routing may legitimately arrive in the
+ * clear, and they are named rather than inferred.
+ *
+ * And it must not let decrypted content overwrite the routing. The merge ran
+ * secret-last, so a session member could seal `from: someoneElsesPeerId` inside
+ * a payload and displace the relay's stamp — the field file-retraction
+ * ownership is checked against.
+ *
+ * It deliberately does NOT latch state.setVerified(). Opening a frame is proof
+ * the PIN is right for the room the frame came from, and this returns to a
+ * caller that has yet to check whether that is still the room we are in — so
+ * latching here could mark a session verified on the strength of a frame from
+ * the one before it. The caller does it, after that check. See openFrame() in
+ * main.js.
+ */
+export async function openWith(aesKey, frame) {
+  if (!aesKey) return null;                     // no session: nothing is trusted
+
+  if (!frame.payload || !frame.iv) {
+    if (plaintext.has(frame.t)) return frame;
+    console.warn("[realtimeclipboard] dropped an unsealed frame", frame.t);
+    return null;
+  }
+
+  try {
+    const secret = JSON.parse(await cryptoBox.decrypt(aesKey, frame.payload, frame.iv));
+    const { payload, iv, ...routing } = frame;
+
+    // A sealed payload has no business carrying routing: encryptFrame() splits
+    // them out before sealing, so one that arrives inside is a forgery or a bug.
+    for (const field of ROUTING_FIELDS) {
+      if (!(field in secret)) continue;
+      console.warn(`[realtimeclipboard] ignored sealed routing field "${field}"`, frame.t);
+      delete secret[field];
+    }
+
+    // Routing spread LAST as well, so the relay's stamp wins even if the strip
+    // above is ever loosened.
+    return { ...secret, ...routing };
+  } catch {
+    // Should be unreachable — drop rather than hand files a half-frame.
+    console.warn("[realtimeclipboard] undecryptable signalling frame", frame.t);
+    return null;
+  }
+}
+
+export const decryptFrame = (frame) => openWith(state.get().aesKey, frame);

package/src/core/history.js

@@ -31,7 +31,8 @@ export const EVENTS = {
 const STORE_KEY = "realtimeclipboard.history";
 
 let clips = [];
-let roomKey = null;      // share key the current list belongs to; null until first KEY_CHANGED
+let roomId = null;       // ROOM the current list belongs to; null until first KEY_CHANGED
+let sealed = false;      // hydrated from storage, not yet confirmed to be this room
 let started = false;
 let seq = 0;
 
@@ -59,8 +60,8 @@ function removeStore() {
  * is a smaller failure than losing the user's clipboard.
  */
 function persist() {
-  if (!clips.length && roomKey === null) return removeStore();
-  writeStore({ key: roomKey, clips });
+  if (!clips.length && roomId === null) return removeStore();
+  writeStore({ room: roomId, clips });
 }
 
 const nextId = () => `h${Date.now().toString(36)}${(++seq).toString(36)}`;
@@ -73,16 +74,22 @@ function announce(reason) {
   emit(EVENTS.CHANGED, { clips: all(), reason });
 }
 
-/** Newest first. Returns a shallow copy — callers must not mutate the list. */
+/**
+ * Newest first. Returns a shallow copy — callers must not mutate the list.
+ *
+ * Empty while `sealed`: clips restored from storage are not known to belong to
+ * the session being opened until the first KEY_CHANGED says so, and a locked
+ * link sitting on its PIN prompt has not opened one yet.
+ */
 export function all() {
-  return clips.slice();
+  return sealed ? [] : clips.slice();
 }
 
 export function get(id) {
-  return clips.find(c => c.id === id) ?? null;
+  return sealed ? null : clips.find(c => c.id === id) ?? null;
 }
 
-export const size = () => clips.length;
+export const size = () => (sealed ? 0 : clips.length);
 
 /**
  * Record a clip. Returns the new entry, or null if it was ignored — empty text,
@@ -110,19 +117,27 @@ export function add({ text, direction }) {
 export function clear(reason = "clear") {
   const had = clips.length;
   clips = [];
+  sealed = false;
   removeStore();
-  if (roomKey !== null) persist();
+  if (roomId !== null) persist();
   if (had) announce(reason);
   return had;
 }
 
-// The stored key is not known to be the current room yet — the first
-// KEY_CHANGED decides whether to keep or discard this.
+// The stored room is not known to be the current one yet — the first
+// KEY_CHANGED decides whether to keep or discard this, and until it does the
+// clips are `sealed`: in memory, out of every reader.
+//
+// Records written before history was room-scoped are keyed by share key, which
+// cannot be mapped onto a room without the PIN. They are dropped rather than
+// guessed at — the cost is one tab's history, once.
 function hydrate() {
   const saved = readStore();
   if (!saved || !Array.isArray(saved.clips)) return;
+  if (typeof saved.room !== "string" || !saved.room) return removeStore();
 
-  roomKey = saved.key ?? null;
+  roomId = saved.room;
+  sealed = saved.clips.length > 0;
   clips = saved.clips
     .filter(c => c && typeof c.text === "string")
     .slice(0, MAX_CLIPS)
@@ -136,23 +151,35 @@ function hydrate() {
 }
 
 /**
- * A new share key is a new room, new peers, and a new privacy context. The first
- * KEY_CHANGED after boot is not a rotation, though — main.js emits one for the
- * key we already had, and comparing against the key stored alongside the clips
- * is what tells the two apart.
+ * A new ROOM is new peers and a new privacy context. Scoped to the room rather
+ * than the share key because they are not the same boundary: re-PINning a
+ * session keeps the key and moves rooms, and key-scoped history followed the
+ * user across that move — as did a wrong-PIN join, which lands in a different
+ * room under the very same key.
+ *
+ * The first KEY_CHANGED after boot is not a change, though — main.js emits one
+ * for the room we already had, and comparing against the room stored alongside
+ * the clips is what tells the two apart. That comparison is also what unseals
+ * hydrated clips: they are only this session's once it has identified itself.
  */
-function onKeyChanged({ key }) {
-  const next = normKey(key);
+function onKeyChanged({ key, roomHash }) {
+  // roomHash is the real identity; the key is the fallback for surfaces that
+  // set state before a room is derived, and for node tests with neither.
+  const next = roomHash || normKey(key);
   if (!next) return;
 
-  if (roomKey !== null && normKey(roomKey) !== next) {
-    roomKey = next;
+  if (roomId !== null && roomId !== next) {
+    roomId = next;
     clear("key-changed");
     persist();
     return;
   }
 
-  roomKey = next;
+  roomId = next;
+  if (sealed) {
+    sealed = false;
+    if (clips.length) announce("hydrate");
+  }
   persist();
 }
 
@@ -167,5 +194,8 @@ export function init() {
   on(EV.TEXT_RECEIVED, ({ text }) => add({ text, direction: "received" }));
   on(EV.KEY_CHANGED, onKeyChanged);
 
-  if (clips.length) announce("hydrate");
+  // Nothing is announced here on purpose: hydrated clips stay sealed until a
+  // KEY_CHANGED identifies the room they belong to. Announcing them at boot put
+  // the previous session's clips in the pane behind an unanswered PIN prompt.
+  if (!sealed && clips.length) announce("hydrate");
 }

package/src/core/i18n.js

@@ -0,0 +1,92 @@
+/**
+ * App translation, keyed by the English string itself.
+ *
+ * There is no key vocabulary to invent and keep in step: `t("Send")` looks up
+ * "Send" and falls back to "Send". A catalogue that is missing an entry — or a
+ * catalogue that never loaded — renders exactly what the source file already
+ * said, so partial coverage is a normal state rather than a broken one. That is
+ * the same property the translated pages have, and it is what lets this land a
+ * module at a time instead of all at once.
+ *
+ * The cost is that editing an English string orphans its translations. That is
+ * the right way round: the orphan renders English, which is correct but
+ * untranslated, whereas a stale key renders the old wording, which is wrong.
+ * `npm run i18n:app -- --check` reports orphans.
+ *
+ * English pays nothing. `pick()` returns "en" for an English reader and `load()`
+ * resolves without a fetch, so the only reader who waits on a catalogue is one
+ * who is getting a translation out of it.
+ */
+
+const PLACEHOLDER = /\{(\w+)\}/g;
+
+let catalogue = null;
+let current = "en";
+
+/** The language actually in force — "en" until a catalogue has loaded. */
+export const lang = () => current;
+
+/**
+ * Translate `en`, substituting `{name}` placeholders from `vars`.
+ *
+ * Placeholders rather than concatenation because word order moves: Chinese puts
+ * the count after the noun, and Russian inflects around it. A translator needs
+ * the whole sentence, not two halves and a variable.
+ */
+export function t(en, vars) {
+  const s = (catalogue && catalogue[en]) || en;
+  return vars ? s.replace(PLACEHOLDER, (whole, k) => (k in vars ? vars[k] : whole)) : s;
+}
+
+/* Literal specifiers inside thunks. `import(variable)` is opaque to the
+   bundler, and passing a path string is what left two optional panels 404ing
+   in the deploy — see the trap in CLAUDE.md. */
+const LOADERS = {
+  zh: () => import("./lang/zh.js"),
+  pt: () => import("./lang/pt.js"),
+  es: () => import("./lang/es.js"),
+  ru: () => import("./lang/ru.js"),
+};
+
+export const SUPPORTED = Object.keys(LOADERS);
+
+/**
+ * The language to use, given a stored override and the browser's preferences.
+ *
+ * An explicit choice wins outright, including an explicit choice of English —
+ * a reader who picked English wants English, not their browser's guess.
+ */
+export function pick(stored, preferred = []) {
+  if (stored === "en" || SUPPORTED.includes(stored)) return stored;
+  for (const tag of preferred) {
+    const code = String(tag).toLowerCase().split("-")[0];
+    if (SUPPORTED.includes(code)) return code;
+  }
+  return "en";
+}
+
+/**
+ * Load a catalogue. Resolves to the language actually in force.
+ *
+ * Never throws: a catalogue that fails to fetch leaves English in place, which
+ * is a fully working app. The session must not fail to open because a
+ * translation did not arrive.
+ */
+export async function load(code) {
+  const get = LOADERS[code];
+  if (!get) return "en";
+  try {
+    const mod = await get();
+    catalogue = mod.default;
+    current = code;
+  } catch (err) {
+    console.warn("[realtimeclipboard] translation unavailable, staying in English:", err.message);
+  }
+  return current;
+}
+
+/** Test seam: install a catalogue without a fetch. */
+export function useCatalogue(code, entries) {
+  catalogue = entries;
+  current = code;
+}

package/src/core/keys.js

@@ -1,6 +1,6 @@
 /** Share-key generation and normalisation. */
 
-import { KEY, LOCK, SITE } from "./config.js";
+import { KEY, LOCK, SITE, RELAY_URL, RELAY_IS_CUSTOM, safeSearch } from "./config.js";
 import { IS_WEB } from "./native.js";
 import * as state from "./state.js";
 
@@ -158,19 +158,38 @@ export function fromUrl() {
  */
 export function clearUrl() {
   if (typeof history === "undefined" || typeof location === "undefined") return;
-  history.replaceState(null, "", location.pathname + location.search);
+  // The query is rewritten too, not just the fragment: `?org=` is a deployment
+  // credential and it was left in the address bar for the life of the session —
+  // in every screenshot, and readable by the ad tag, which reports the page URL
+  // itself rather than taking pageLocation(). It has been read into storage by
+  // the time this runs.
+  history.replaceState(null, "", location.pathname + safeSearch());
 }
 
 /**
  * A link for the OTHER device to open, which is why it is not always this one's
  * URL. Only a browser can hand out its own address — see SITE in config.js for
  * the hosts that cannot.
+ *
+ * A custom relay travels WITH the link. Dropping it was silent and total: the
+ * recipient resolved to the default relay, both ends reported "connected", and
+ * nothing ever arrived — with no error at either end to say why. `?relay=` is
+ * the mechanism docs/SELF-HOSTING.md tells operators to hand out, and this is
+ * the one place a link is built, so it is the one place that can carry it.
+ *
+ * On a self-hosted app the link is complete: that build's CSP names its own
+ * relay, so following it works. From a native host the base is the public app,
+ * whose CSP names only the public relay — the parameter cannot make that
+ * connection succeed, but it does turn a session that silently syncs nothing
+ * into a connection that visibly refuses, which is the difference between a bug
+ * report and a mystery.
  */
 export function shareLink(key, locked = false) {
   const here = IS_WEB && typeof location !== "undefined"
     ? location.origin + location.pathname
     : SITE.APP_URL;
-  return `${here}#${fragment(key, locked)}`;
+  const relay = RELAY_IS_CUSTOM ? `?relay=${encodeURIComponent(RELAY_URL)}` : "";
+  return `${here}${relay}#${fragment(key, locked)}`;
 }
 
 /**

package/src/core/native.js

@@ -48,7 +48,7 @@ export const IS_CLI     = SURFACE === "cli";
  * key length: an installed surface keeps its session across restarts and is worth
  * the longer key, a visited one is usually typing it to somebody.
  */
-export const IS_INSTALLED = IS_DESKTOP || SURFACE === "vscode";
+export const IS_INSTALLED = IS_DESKTOP || SURFACE === "vscode" || SURFACE === "browser";
 
 let host = null;
 

package/src/core/state.js

@@ -31,6 +31,12 @@ const state = {
   peerId: null,              // assigned by the relay in `welcome.you`
   connection: "idle",        // idle | connecting | connected | reconnecting | offline
   instance: null,            // relay instance id — a change means split-brain (OI-3)
+  /**
+   * Frame types this relay understands, from `welcome.caps`. Empty on a relay
+   * older than the field, which is the point: a client that guesses gets
+   * UNKNOWN_TYPE back and cannot tell it from silence. See core/verify.js.
+   */
+  relayCaps: [],
   peers: 1,
   tier: "T1",                // clipboard capture tier, see clipboard/capture.js
   lastSent: "",              // dedupe guard (FR-2.7)
@@ -56,6 +62,10 @@ const state = {
     // system | light | dark. "system" is not a third colour scheme, it is the
     // absence of a choice — see config.js THEMES and ui/features/theme.js.
     theme: DEFAULT_THEME,
+    // "" is the absence of a choice, and means "follow the browser" — the same
+    // shape as theme's "system". An explicit "en" is a real choice and beats a
+    // browser that asks for Chinese. See core/i18n.js pick().
+    language: "",
   },
 };
 
@@ -141,21 +151,40 @@ function watchSettings() {
   });
 }
 
-export function setKey({ key, roomHash, aesKey, locked = false, authToken = null }) {
+/**
+ * `roomHash` and `aesKey` keep their old value when the property is ABSENT, not
+ * when it is null. `??` could not tell those apart, so the one caller that says
+ * `aesKey: null` to wipe a session — VS Code's leave — kept the key it was
+ * clearing. Omission still means "leave it alone"; an explicit null now clears.
+ */
+export function setKey(next) {
+  const { key, roomHash, aesKey, locked = false, authToken = null } = next;
   state.key = key;
-  state.roomHash = roomHash ?? state.roomHash;
-  state.aesKey = aesKey ?? state.aesKey;
+  state.roomHash = "roomHash" in next ? roomHash : state.roomHash;
+  state.aesKey = "aesKey" in next ? aesKey : state.aesKey;
   state.locked = locked;
   state.authToken = authToken;
   // A new key is a new room, so both of these are re-asked. Left standing, the
   // founder of one session would carry the right to lock into the next.
   state.verified = false;
   state.founder = null;
-  emit(EV.KEY_CHANGED, { key, locked });
+  // roomHash rides along because the ROOM is the privacy boundary, not the
+  // share key: re-PINning keeps the key and changes the room, and a listener
+  // scoping anything to the key alone would carry it across that change.
+  emit(EV.KEY_CHANGED, { key, locked, roomHash: state.roomHash });
   emit(EV.LOCK_STATE, { locked, verified: false });
   emit(EV.FOUNDER, { founder: null });
 }
 
+/**
+ * Wipe every credential this module holds. The teardown paths used to spell
+ * this out field by field and each one forgot a different field — the shape of
+ * "no session" belongs here, with the shape of a session.
+ */
+export function clearKey() {
+  setKey({ key: "", roomHash: "", aesKey: null, locked: false, authToken: null });
+}
+
 /**
  * Fed from `welcome.existing`. Re-answered on every welcome, so a relay restart
  * — which empties every room (OI-13) — hands the title to whoever reconnects
@@ -197,6 +226,10 @@ export function setVerified() {
   emit(EV.LOCK_STATE, { locked: true, verified: true });
 }
 
+export function setRelayCaps(caps) {
+  state.relayCaps = Array.isArray(caps) ? caps : [];
+}
+
 export function setConnection(connection, detail = "") {
   state.connection = connection;
   emit(EV.CONN_STATE, { state: connection, detail });

package/src/core/storage.js

@@ -60,6 +60,20 @@ export function saveRelayUrl(url) {
   return clean;
 }
 
+/**
+ * The organisation token for a relay that demands one. Per DEVICE, not per
+ * session: it admits this machine to a deployment, and it is deliberately kept
+ * out of share links — see ORG_TOKEN in config.js.
+ */
+export const loadOrgToken = () => read("orgToken", null);
+
+export function saveOrgToken(token) {
+  const clean = typeof token === "string" && token.trim() ? token.trim() : null;
+  if (!clean) { remove("orgToken"); return null; }
+  write("orgToken", clean);
+  return clean;
+}
+
 /**
  * The last room, so a relaunch can offer it back (FR-1.7, OI-10). Stores
  * `{key, locked}` and still reads the bare string it used to be, because an

package/src/core/verify.js

@@ -0,0 +1,152 @@
+/**
+ * Proving a locked session, without spending the room's replay slot.
+ *
+ * A wrong PIN is silent by design. The PIN is stretched into the room hash, so
+ * mistyping it does not get you turned away from the right room — it puts you
+ * in a different, empty one, which on screen is indistinguishable from being
+ * the first to arrive. Something in the room has to be readable before the app
+ * can tell those apart.
+ *
+ * That used to be a sentinel clip planted on arrival, and the cost was the
+ * room's single retained clip (FR-3.3): proving the PIN either overwrote the
+ * last thing the user copied, or — once the plant started honouring the sync
+ * rung — was skipped in a way that left correctly-joined devices being warned
+ * their PIN might be wrong. The two guards could not both hold, because the
+ * proof and the user's data were competing for one slot.
+ *
+ * So the proof is its own frame now. It is forwarded and not retained, which
+ * removes the competition rather than arbitrating it.
+ *
+ * Everything here is dependency-injected rather than imported, and not for
+ * purity: `build` is a frame shape (rank 10) and `send` is the transport (also
+ * rank 10), neither of which core/ may reach. It buys the thing that matters
+ * anyway — every rule below is reachable from a test with four fakes, instead
+ * of being four lines in the composition root that only a source-reading check
+ * can see.
+ */
+
+import { LOCK, sharesSession } from "./config.js";
+import * as state from "./state.js";
+
+/**
+ * @param build  proto.verify — the frame shape
+ * @param seal   frames.encryptFrame
+ * @param send   relay.send
+ * @param gen    () => the session generation, so a seal that outlived its room is dropped
+ */
+export function createVerifier({ build, seal, send, gen, now = () => Date.now() }) {
+  /**
+   * "Never asked", which is not the same as "asked at time zero". Spelled 0, it
+   * is a real timestamp that happens to be in 1970, and the first probe of a
+   * session is refused for being too soon after it. Invisible against
+   * Date.now(), and a dead session under any injected clock.
+   */
+  let lastAsk = -Infinity;
+
+  /**
+   * Bumped by cancel(). `gen` covers the same ground in the app — leaveRoom()
+   * moves it — but this module must be able to abandon in-flight work on its
+   * own, or "cancel" would mean "ask the caller nicely".
+   */
+  let epoch = 0;
+
+  /**
+   * The relay has to know the frame type. An older one answers UNKNOWN_TYPE,
+   * which arrives looking exactly like a probe nobody chose to answer — and the
+   * difference between those two is "your PIN is wrong" and "this relay needs
+   * redeploying". Asked rather than guessed, and there is deliberately no
+   * fallback to the old retained beacon: silently spending the replay slot
+   * again is the behaviour being removed, not a degraded mode to keep.
+   */
+  const relaySupports = () => (state.get().relayCaps ?? []).includes("verify");
+
+  /**
+   * Off means nothing leaves. Both directions: a device on Off does not ask,
+   * and does not answer either. Answering is a frame put on the wire for
+   * somebody else's benefit, which is exactly what an Off device has said it
+   * will not do — and a rung that leaks for control traffic is a rung that does
+   * not mean what the UI says.
+   */
+  function eligible() {
+    const s = state.get();
+    return !!s.aesKey
+      && s.locked
+      && sharesSession(s.settings.syncMode)
+      && relaySupports();
+  }
+
+  /**
+   * Checked before sealing and again immediately before sending, because the
+   * seal is an await: a room change, a rung change or a cancel can all land
+   * inside it, and a frame sealed for the room we left is either undecryptable
+   * noise in the room we arrived at or an Off device transmitting after the
+   * fact.
+   */
+  async function transmit(probe) {
+    if (!eligible()) return false;
+    const g = gen(), e = epoch;
+    const frame = await seal(build({ probe, originId: state.get().originId }));
+    if (g !== gen() || e !== epoch) return false;
+    if (!eligible()) return false;
+    send(frame);
+    return true;
+  }
+
+  return {
+    /**
+     * Ask the room to prove itself. Only worth doing unverified and in company:
+     * a probe into an empty room is answered by nobody, and once anything has
+     * decrypted the question is settled for the life of the session.
+     */
+    async request() {
+      const s = state.get();
+      if (s.verified || s.peers <= 1) return false;
+      // Before the interval stamp, so an ineligible attempt does not consume
+      // the window. It is the Off device that most needs the next call to get
+      // through — enabling sharing is a trigger, and swallowing it would strand
+      // the device that just asked to be included.
+      if (!eligible()) return false;
+      if (now() - lastAsk < LOCK.VERIFY_MIN_INTERVAL_MS) return false;
+      lastAsk = now();
+      return transmit(true);
+    },
+
+    /**
+     * Answer one, if it is a question. `probe !== true` is the whole loop guard
+     * and it is one-directional on purpose: an answer can never produce another
+     * frame, so two unverified devices converge in one exchange instead of
+     * trading proof until the rate limiter stops them.
+     *
+     * Answered even when already verified — this is a service to the asker, not
+     * to us — and answered by an unverified device too, which by then has
+     * decrypted the probe and so is about to be verified itself.
+     */
+    async answer(frame) {
+      if (!frame || frame.probe !== true) return false;
+      if (frame.originId && frame.originId === state.get().originId) return false;
+      return transmit(false);
+    },
+
+    /**
+     * Proof nobody asked for, sent when this device becomes able to give it.
+     *
+     * Without it the rung is a one-way trapdoor. A device that was on Off while
+     * a peer probed did not answer — correctly — and the peer has no reason to
+     * ask again: its trigger was the arrival, and nobody new is going to
+     * arrive. So coming off Off has to push, not wait to be pulled.
+     *
+     * Safe to fire unconditionally because an answer is not a probe: it ends
+     * there, however many devices send one at once.
+     */
+    async announce() {
+      if (state.get().peers <= 1) return false;
+      return transmit(false);
+    },
+
+    /** Abandon anything in flight. Called from the session teardown. */
+    cancel() {
+      epoch++;
+      lastAsk = -Infinity;       // a new room may ask at once
+    },
+  };
+}