agent-dag 3.15.0 → 3.17.0

package/src/server/lan-engine.mjs

@@ -29,8 +29,8 @@
 // anything.
 import { accountKey, manifestFor, open, plan, seal, stillListed, transferChallenge } from "./lan-sync.mjs";
 import { connectToPeer, createBeacon, createSyncServer, sendFrame } from "./lan-socket.mjs";
-import { fingerprint, groupKey } from "./lan-sync.mjs";
-import { generateKeyPairSync, randomBytes } from "node:crypto";
+import { addTrusted, dropTrusted, identityFrom, mintInvite, pairable, readInvite, trustedPeer } from "./lan-sync.mjs";
+import { randomBytes } from "node:crypto";
 import { hostname, networkInterfaces } from "node:os";
 
 /** How often a deck asks its peers what they have. A minute is far more often
@@ -44,32 +44,6 @@ export const SYNC_MS = 60_000;
 export const ROUND_MS = 10_000;
 
 
-/**
- * The name everybody knows this deck by.
- *
- * PERSISTED, and the first version was not. It regenerated on every start, on
- * the argument that a stored key is one more secret to protect — and that
- * argument was about the wrong thing, because this is not a key. Nothing is
- * signed with it and nothing is decrypted with it; the group passphrase is what
- * authenticates, and this is only an identifier, broadcast in the clear in
- * every beacon. There is nothing here to steal.
- *
- * What regenerating it cost was measured rather than guessed: on a machine
- * where decks had been restarted a few times, every peer's list held a row per
- * restart — dozens of them, each reporting ECONNREFUSED every minute against a
- * port nothing has listened on for an hour. Remembered forever and never
- * recognised again is the worst of both, and a stable id is the whole fix.
- */
-export function newIdentity(stored) {
-  if (typeof stored === "string" && /^[0-9a-f]{12}$/.test(stored)) {
-    return { fp: stored.replace(/(.{3})(?=.)/g, "$1-"), id: stored };
-  }
-  const { publicKey } = generateKeyPairSync("x25519");
-  const raw = publicKey.export({ type: "spki", format: "der" });
-  const fp = fingerprint(raw);
-  return { fp, id: fp.replace(/-/g, "") };
-}
-
 /** What this machine calls itself when the user has not said. The hostname,
  *  because that is the word they already use for this machine everywhere else. */
 export function defaultName() {
@@ -115,17 +89,78 @@ export function localAddresses(faces = networkInterfaces()) {
  */
 export function createEngine({
   readAccounts, exportAccount, importAccount,
-  onChange, onError, onIdentity, now = Date.now,
+  onChange, onError, onIdentity, onPort, onTrust, onDial, now = Date.now,
+  /**
+   * The UDP socket the beacon shouts through, injectable for the same reason
+   * lan-socket exposes it — and for one more that only showed up in use.
+   *
+   * The suite runs whole engines over real sockets, which is right: a handshake
+   * between two of them is the thing being tested and a mock would only check
+   * that the mock agrees with the code it was written from. But `createBeacon`
+   * defaulted to a real dgram socket, so `npm test` BROADCAST on whatever
+   * network the machine was on — and the fake decks it announces turned up in
+   * a real panel, on a real screen, in a list of decks somebody could pair
+   * with. Nothing secret leaves, and it is still a test shouting at an office.
+   */
+  createSocket,
 } = {}) {
-  let cfg = { enabled: false, name: defaultName(), passphrase: "", shared: [], deckId: "" };
+  let cfg = { enabled: false, name: defaultName(), secret: "", shared: [], trusted: [], port: 0 };
   let identity = null;
   let beacon = null;
   let server = null;
   let timer = null;
-  let key = null;
+  /**
+   * Decks that finished a handshake and that nobody here has accepted yet, and
+   * decks merely heard shouting on the network. Two lists because they are two
+   * different claims: a pending deck proved it holds the key it announced, a
+   * heard one only said so. Both are rows with an accept on them; only the
+   * first is evidence.
+   *
+   * In memory rather than on disk. A request that is a day old is not a request
+   * any more, and a list of them that survives restarts is a list nobody reads.
+   */
+  const pending = new Map();
+  const strangers = new Map();
+  /**
+   * Decks somebody here said no to.
+   *
+   * WITHOUT THIS, DECLINING DID NOTHING THAT LASTED. A deck that asks is a deck
+   * that keeps asking — it dials on its own timer, and every dial that finds no
+   * pin here becomes a fresh request. So `dismiss` took a row off a list that
+   * the next minute put back, and on the other machine the refusal was
+   * indistinguishable from a deck that had not been answered yet: both are the
+   * same `pending` refusal on the wire, and both drew "waiting for the other
+   * deck to accept this one" forever.
+   *
+   * A name kept here is therefore two answers at once. This deck stops asking
+   * its owner, and the deck that asked is TOLD — see refuse("declined") in
+   * lan-socket.mjs, which is the only way the far end can ever learn that the
+   * answer was no rather than not yet.
+   *
+   * In memory, like the two lists above, and reversible: `allow` takes a name
+   * out and the requests come back. Nothing about it is written down, because a
+   * refusal that outlives the process is a decision nobody can find to undo.
+   */
+  const declined = new Map();
+  /** The invite this deck is offering, or null. One at a time: a deck showing
+   *  two tokens is a deck whose owner cannot say which one they sent. */
+  let invite = null;
   /** What the last round did, for the panel. Not a log: one line per peer, most
    *  recent only, because "what happened" is a question about now. */
   const lastRound = new Map();
+  /**
+   * Why this deck is not listening, when it is switched on and is not.
+   *
+   * A second deck on one machine takes the first one's port and the bind fails;
+   * the switch stays on, the beacon never starts, and the panel drew
+   * `starting…` for as long as the process lived. A state that cannot resolve
+   * and does not say why is the worst thing an instrument can show — the reader
+   * waits, and waiting is the one thing that never fixes it.
+   *
+   * Only the failures that stop the service reach this. A round that could not
+   * reach one peer is that peer's row, not the deck's.
+   */
+  let stalled = null;
 
   /** This deck's accounts in the shape the rules want. Read through the same
    *  function the panel uses, so a row can never be alive here and dead there. */
@@ -139,8 +174,10 @@ export function createEngine({
     }));
   };
 
-  /** Frames from a peer that has proved the passphrase. Nothing reaches this
-   *  before that, which is the whole point of where the check sits. */
+  /** Frames from a deck that finished the handshake AND that somebody here has
+   *  accepted. Nothing reaches this before both, which is the whole point of
+   *  where the two checks sit. `ctx.key` is this connection's key and no other
+   *  connection's — see sessionKey. */
   const serve = async (msg, ctx) => {
     try {
       if (msg.t === "manifest") {
@@ -152,7 +189,7 @@ export function createEngine({
         // session says who connected; this says they are asking for this
         // account, now. A long-lived connection authenticated an hour ago is
         // not a statement about now.
-        const want = transferChallenge(key, {
+        const want = transferChallenge(ctx.key, {
           nonce: msg.nonce, accountKey: msg.key, fromFp: ctx.peerFp, toFp: identity.fp,
         });
         if (typeof msg.proof !== "string" || msg.proof !== want) {
@@ -168,7 +205,7 @@ export function createEngine({
         const blob = await exportAccount(mine.num);
         if (!blob) return ctx.send({ t: "no", why: "export failed" });
         const aad = `${identity.fp}->${ctx.peerFp}|${msg.key}`;
-        return ctx.send({ t: "have", key: msg.key, sealed: seal(key, blob, aad) });
+        return ctx.send({ t: "have", key: msg.key, sealed: seal(ctx.key, blob, aad) });
       }
     } catch (err) {
       onError?.("serve", err);
@@ -180,7 +217,16 @@ export function createEngine({
   const roundWith = async peer => {
     let conn = null;
     try {
-      conn = await connectToPeer({ host: peer.addr, port: peer.port, fp: identity.fp, key, timeoutMs: ROUND_MS });
+      conn = await connectToPeer({
+        host: peer.addr, port: peer.port, timeoutMs: ROUND_MS,
+        fp: identity.fp, pub: identity.pub, secret: identity.secret, name: cfg.name,
+        // Where this deck listens, so the far side can reach back after it
+        // accepts rather than only being reachable.
+        myPort: server?.port() ?? null,
+        // The key pinned when this deck was accepted, so a second machine
+        // answering at that address is refused rather than talked to.
+        expectPub: trustedPeer(cfg.trusted, peer.fp)?.pub ?? null,
+      });
       const ask = frame => new Promise((resolve, reject) => {
         const bell = setTimeout(() => reject(new Error("peer went quiet")), ROUND_MS);
         bell.unref?.();
@@ -197,6 +243,30 @@ export function createEngine({
         sendFrame(conn.sock, frame);
       });
 
+      // TRUST ON FIRST USE, AND ONLY FOR AN ADDRESS SOMEBODY TYPED. Reaching a
+      // deck we have no pin for means the person at this keyboard put its
+      // address in the field, which is the same decision the accept button is
+      // on the other side. Pinning it here is what makes the two lists agree —
+      // without it this deck would dial a peer every minute and still show it
+      // as nobody, and its own listener would refuse the same deck calling
+      // back.
+      //
+      // A deck we DO have a pin for was checked before this line: connectToPeer
+      // was given expectPub and refuses a different key at that address.
+      // WHO IS ACTUALLY THERE. A typed address is a row that says `192.168.1.5:54340`
+      // and nothing else until somebody answers it — and once one has, the deck
+      // on the other end has told us what it calls itself. The row says that
+      // from then on, because "Constantin-PC" is what the person who typed the
+      // address was trying to reach.
+      learned.set(`${peer.addr}:${peer.port}`, { fp: conn.peerFp, name: conn.peerName || "" });
+
+      if (!trustedPeer(cfg.trusted, conn.peerFp)) {
+        const { list, added } = addTrusted(cfg.trusted, {
+          fp: conn.peerFp, pub: conn.peerPub, name: conn.peerName,
+        });
+        if (added) { cfg = { ...cfg, trusted: list }; onTrust?.(list); }
+      }
+
       const theirs = await ask({ t: "manifest" });
       if (theirs?.t !== "manifest" || !Array.isArray(theirs.accounts)) throw new Error("no manifest");
       const mine = await localAccounts();
@@ -205,10 +275,10 @@ export function createEngine({
       // A HEAL NEEDS MY TICK; AN ADD DOES NOT, and the asymmetry is deliberate.
       // Healing replaces a slot I already have, so it is only reasonable for an
       // account I said I share. Adding is the case the owner asked for by name:
-      // an account that appears in the group appears everywhere in it, which is
-      // the whole of "I do not want to paste blobs any more". The group is
-      // passphrase-gated, so what can reach this is what somebody I trusted
-      // with that passphrase chose to offer.
+      // an account that appears among the decks I paired with appears on all of
+      // them, which is the whole of "I do not want to paste blobs any more".
+      // What can reach this is what a deck somebody here pressed accept on
+      // chose to offer.
       const wanted = plan(mine, theirs.accounts)
         .filter(step => step.action === "add" || cfg.shared.includes(step.key));
       const done = [];
@@ -216,12 +286,12 @@ export function createEngine({
         const nonce = randomBytes(12).toString("hex");
         const reply = await ask({
           t: "want", key: step.key, nonce,
-          proof: transferChallenge(key, {
+          proof: transferChallenge(conn.key, {
             nonce, accountKey: step.key, fromFp: identity.fp, toFp: conn.peerFp,
           }),
         });
         if (reply?.t !== "have" || !reply.sealed) { done.push({ ...step, ok: false, why: reply?.why ?? "refused" }); continue; }
-        const blob = open(key, reply.sealed, `${conn.peerFp}->${identity.fp}|${step.key}`);
+        const blob = open(conn.key, reply.sealed, `${conn.peerFp}->${identity.fp}|${step.key}`);
         if (!blob) { done.push({ ...step, ok: false, why: "could not open" }); continue; }
         const ok = await importAccount(blob);
         done.push({ ...step, ok: !!ok, why: ok ? null : "import failed" });
@@ -241,13 +311,19 @@ export function createEngine({
    *
    *  Broadcast dies at the first router and is dropped by a switch that
    *  filters it, so a deck across a VPN or on another subnet is unreachable by
-   *  discovery and perfectly reachable by address. The passphrase remains the
-   *  only gate, so an address is not a way in — it is a way to be dialled.
+   *  discovery and perfectly reachable by address. Typing one is a decision to
+   *  trust whatever answers there the first time, and to pin it: an address is
+   *  a way to reach a deck, and the accept on the other machine is what lets
+   *  anything move.
    *
    *  Keyed by `host:port` rather than by fingerprint, because a fingerprint is
    *  what a deck says about itself after the handshake and this list has to
    *  exist before there has been one. */
   const manual = new Map();
+  /** What answered at a typed address, once something has. Keyed the same way
+   *  `manual` is, because until a connection succeeds an address is all there
+   *  is to key on. */
+  const learned = new Map();
 
   const round = async () => {
     if (!beacon) return [];
@@ -274,36 +350,271 @@ export function createEngine({
       const was = cfg;
       cfg = { ...cfg, ...next };
       const restart = !was.enabled !== !cfg.enabled
-        || was.passphrase !== cfg.passphrase
-        || was.name !== cfg.name
-        || was.deckId !== cfg.deckId;
+        || was.secret !== cfg.secret
+        || was.name !== cfg.name;
       if (!restart) return;
       this.stop();
-      if (!cfg.enabled || !cfg.passphrase) return;
-      key = groupKey(cfg.passphrase);
-      identity = newIdentity(cfg.deckId);
-      // Hand the caller an id to keep when there was none, so the next start is
-      // the same deck rather than a new row in everybody's list.
-      if (identity.id !== cfg.deckId) onIdentity?.(identity.id);
-      server = createSyncServer({ fp: identity.fp, name: cfg.name, key, handlers: serve, onError });
-      const port = await server.start();
+      if (!cfg.enabled) return;
+      identity = identityFrom(cfg.secret);
+      // Hand the caller a key to keep when there was none, so the next start is
+      // the same deck rather than a stranger to everybody who paired with it.
+      if (identity.secret !== cfg.secret) {
+        cfg = { ...cfg, secret: identity.secret };
+        onIdentity?.(identity.secret);
+      }
+      // The port last used, so an address somebody typed on the other machine
+      // still works after this deck restarts. createSyncServer falls through to
+      // an OS-chosen one when it is taken, and the caller stores whatever came
+      // back — so the pin drifts to a free port rather than failing.
+      server = createSyncServer({
+        fp: identity.fp, pub: identity.pub, secret: identity.secret,
+        name: cfg.name, handlers: serve, onError, prefer: cfg.port,
+        trusted: () => cfg.trusted,
+        invite: () => (invite && invite.expiresAt > now() ? invite : null),
+        // Somebody used the token. They are pinned, and the token is retired —
+        // one that pairs twice is one worth stealing twice.
+        onInviteUsed: entry => {
+          const { list } = addTrusted(cfg.trusted, { fp: entry.fp, pub: entry.pub, name: entry.name });
+          cfg = { ...cfg, trusted: list };
+          invite = null;
+          // AND DIAL IT BACK, KEPT. Accepting made it welcome and left this
+          // deck with no way to reach it: an inbound connection puts nothing in
+          // the dial list. Without this the pairing is mutual in the trusted
+          // list and one-way in fact — and `addPeer` alone lives in memory, so
+          // it would be one-way again after the next restart.
+          if (entry.addr && entry.port) {
+            this.addPeer(entry.addr, entry.port);
+            onDial?.(`${entry.addr}:${entry.port}`);
+            // AND SAY WHO IS THERE, NOW. `learned` is what joins a dialled row
+            // to a heard one, and it was only ever filled by a round that
+            // succeeded — so between accepting a deck and the next round, one
+            // machine appeared as two rows. We already know the answer here:
+            // the handshake that just finished said so.
+            learned.set(`${entry.addr}:${entry.port}`, { fp: entry.fp, name: entry.name || "" });
+          }
+          onTrust?.(list);
+          onChange?.();
+        },
+        // Asked before the request is drawn, so a deck that was told no is
+        // told no again rather than becoming a row somebody has to answer
+        // twice. The socket sends the reason; this only knows the name.
+        declined: fp => declined.has(fp),
+        onPending: entry => {
+          const had = pending.get(entry.fp);
+          pending.set(entry.fp, { ...entry, at: had?.at ?? now(), lastAt: now() });
+          if (!had) onChange?.();
+        },
+      });
+      let port;
+      try {
+        port = await server.start();
+      } catch (err) {
+        // Kept, so the panel can say it. Rethrown, because the caller's own
+        // catch is what leaves the engine stopped rather than half-started.
+        stalled = err?.message ?? String(err);
+        throw err;
+      }
+      stalled = null;
+      if (port !== cfg.port) onPort?.(port);
       beacon = createBeacon({
-        port, name: cfg.name, fp: identity.fp, key,
+        port, name: cfg.name, fp: identity.fp,
+        trusted: () => cfg.trusted,
         onPeer: () => onChange?.(),
-        // Take a new name and keep it. Two decks with one id are invisible to
-        // each other forever otherwise, and the second one to notice moving is
-        // enough — whichever notices first, moves.
+        onStranger: entry => {
+          const had = strangers.get(entry.fp);
+          strangers.set(entry.fp, entry);
+          // Only a deck that is new to us is news. A beacon every thirty
+          // seconds from one already on the list is not a reason to redraw.
+          if (!had) onChange?.();
+        },
+        // Take a new key and keep it. Two decks with one identity are invisible
+        // to each other forever otherwise, and the second one to notice moving
+        // is enough — whichever notices first, moves.
         onIdClash: () => {
-          const fresh = newIdentity();
-          onIdentity?.(fresh.id);
-          onError?.("id-clash", new Error("another deck was using this one's id; taking a new one"));
+          const fresh = identityFrom("");
+          onIdentity?.(fresh.secret);
+          onError?.("id-clash", new Error("another deck was using this one's key; taking a new one"));
         },
         onError, now,
+        ...(createSocket ? { createSocket } : {}),
       });
       await beacon.start();
       timer = setInterval(() => { void round(); }, SYNC_MS);
       timer.unref?.();
     },
+    /**
+     * Make an invite: every address this deck has, its port, its name, and a
+     * code, in one piece of text somebody sends however they already talk.
+     *
+     * EVERY ADDRESS, and that is the whole reason this exists. A person cannot
+     * know which of their machine's addresses the other machine can route to —
+     * a VPN, a second card, another subnet, all real and all at once — and
+     * neither can this deck. The one machine that can find out is the one doing
+     * the reaching, so it gets the list and tries it.
+     */
+    invite() {
+      if (!server || !beacon) return null;
+      const port = server.port();
+      if (port == null) return null;
+      const addrs = localAddresses().map(a => `${a}:${port}`);
+      const made = mintInvite({ addrs, name: cfg.name, now: now() });
+      if (!made) return null;
+      invite = made;
+      onChange?.();
+      return { token: made.token, expiresAt: made.expiresAt, addrs };
+    },
+
+    /** What this deck is offering right now, for the panel to draw. Null once
+     *  it has run out, so a token nobody can use is not shown as if they could. */
+    offering() {
+      if (!invite || invite.expiresAt <= now()) return null;
+      return { token: invite.token, expiresAt: invite.expiresAt };
+    },
+
+    /** Put it away without using it. */
+    withdraw() {
+      const had = !!invite;
+      invite = null;
+      if (had) onChange?.();
+      return had;
+    },
+
+    /**
+     * Join on somebody else's invite: try every address it carries until one
+     * answers, and pair with whatever does.
+     *
+     * IN ORDER, AND STOPPING AT THE FIRST, because the addresses are the same
+     * deck seen from different networks — reaching it twice would pair one deck
+     * as two. The failures are collected rather than thrown away: when none of
+     * them worked, which ones were tried and what each said is the only thing
+     * the reader can act on.
+     */
+    async join(token) {
+      const inv = readInvite(token, now());
+      if (!inv) return { ok: false, reason: "not_an_invite" };
+      if (inv.expired) return { ok: false, reason: "expired" };
+      if (!identity || !server) return { ok: false, reason: "not_running" };
+      const tried = [];
+      for (const at of inv.addrs) {
+        let conn = null;
+        try {
+          conn = await connectToPeer({
+            host: at.addr, port: at.port, timeoutMs: ROUND_MS,
+            fp: identity.fp, pub: identity.pub, secret: identity.secret,
+            name: cfg.name, myPort: server.port(), code: inv.code,
+          });
+          const { list } = addTrusted(cfg.trusted, {
+            fp: conn.peerFp, pub: conn.peerPub, name: conn.peerName || inv.name,
+          });
+          cfg = { ...cfg, trusted: list };
+          this.addPeer(at.addr, at.port);
+          onDial?.(`${at.addr}:${at.port}`);
+          learned.set(`${at.addr}:${at.port}`, { fp: conn.peerFp, name: conn.peerName || inv.name });
+          onTrust?.(list);
+          onChange?.();
+          return {
+            ok: true,
+            peer: { fp: conn.peerFp, name: conn.peerName || inv.name, addr: at.addr, port: at.port },
+            tried,
+          };
+        } catch (err) {
+          tried.push({ addr: `${at.addr}:${at.port}`, why: err.message });
+        } finally {
+          conn?.sock?.destroy();
+        }
+      }
+      return { ok: false, reason: "unreachable", tried };
+    },
+
+    /**
+     * Accept a deck, which is the only thing that lets anything move.
+     *
+     * It takes the fingerprint AND the key that was seen with it, from the
+     * pending or heard list — never from whatever is at an address now, because
+     * the point of pinning is that the thing answering later has to be the same
+     * thing. A fingerprint nobody has actually met is refused rather than
+     * trusted on a name somebody typed.
+     */
+    accept(fp) {
+      const asked = pending.get(fp) ?? null;
+      const heard = strangers.get(fp) ?? null;
+      const seen = asked ?? heard;
+      if (!seen) return null;
+      // TWO KINDS OF ROW, AND THEY ARE NOT THE SAME CLAIM.
+      //
+      // A deck that ASKED finished a handshake, so it held the private half of
+      // the key it announced and that key can be pinned right here. A deck we
+      // merely HEARD has only shouted: a beacon carries a fingerprint and no
+      // key, and pinning a fingerprint with no key to check it against later is
+      // worse than not pinning at all — it looks like a pairing and is not one.
+      //
+      // So accepting a heard deck starts a conversation rather than ending one:
+      // its address goes on the dial list, the next round reaches it and pins
+      // whatever answers, and its owner gets the same request to accept. Which
+      // is the same two presses, in the other order.
+      if (!seen.pub) {
+        if (!seen.addr || !seen.port) return null;
+        this.addPeer(seen.addr, seen.port);
+        strangers.delete(fp);
+        onChange?.();
+        return { fp, name: seen.name, addr: seen.addr, port: seen.port, dialled: true };
+      }
+      const { list, added } = addTrusted(cfg.trusted, { fp, pub: seen.pub, name: seen.name });
+      cfg = { ...cfg, trusted: list };
+      pending.delete(fp);
+      strangers.delete(fp);
+      onTrust?.(list);
+      onChange?.();
+      // AND DIAL IT BACK. Accepting a deck that called us made it welcome and
+      // left this one with no way to reach it: the peer list is what this deck
+      // dials, and an inbound connection puts nothing in it. So the pairing was
+      // mutual in the trusted list and one-way in fact — if the other machine
+      // stopped calling, nothing here would ever call it. The hello carries the
+      // port it listens on for exactly this.
+      const back = seen.addr && seen.port && this.addPeer(seen.addr, seen.port)
+        ? (learned.set(`${seen.addr}:${seen.port}`, { fp, name: seen.name || "" }),
+           { addr: seen.addr, port: seen.port })
+        : null;
+      return added ? { fp, name: seen.name, addr: seen.addr, port: seen.port ?? null, dialBack: back } : null;
+    },
+    /** Say no, and stop being asked. The deck is dropped from both lists; if it
+     *  connects again it is a new request, because refusing is not a block. */
+    dismiss(fp) {
+      // Whatever the row said, kept — the panel draws a declined deck by name
+      // and address, and after the delete below there is nowhere else to read
+      // them from.
+      const was = pending.get(fp) ?? strangers.get(fp) ?? null;
+      const had = pending.delete(fp) || strangers.delete(fp);
+      if (had) {
+        declined.set(fp, {
+          fp,
+          name: was?.name ?? fp,
+          addr: was?.addr ?? "",
+          port: was?.port ?? 0,
+          at: now(),
+        });
+        onChange?.();
+      }
+      return had;
+    },
+    /** Change your mind. The name comes off the declined list and the next time
+     *  that deck dials, it is a request again — which it will, on its own, so
+     *  there is nothing else to press. */
+    allow(fp) {
+      const had = declined.delete(fp);
+      if (had) onChange?.();
+      return had;
+    },
+    /** Unpair. It stops what has not happened yet and takes back nothing that
+     *  has — the same sentence the panel says about a shared login. */
+    unpair(fp) {
+      const list = dropTrusted(cfg.trusted, fp);
+      if (list.length === cfg.trusted.length) return false;
+      cfg = { ...cfg, trusted: list };
+      onTrust?.(list);
+      onChange?.();
+      return true;
+    },
     round,
     /** Dial this address on every round from now on. Returns false for an
      *  address that is not one, rather than storing a row that can never
@@ -332,6 +643,9 @@ export function createEngine({
       return {
         enabled: !!cfg.enabled,
         running: !!beacon,
+        // Said only while it is true, and it is only ever true of a deck that
+        // is switched on and has no listener.
+        stalled: cfg.enabled && !beacon ? stalled : null,
         name: cfg.name,
         fp: identity?.fp ?? null,
         // The address and port a person on another subnet types into the other
@@ -340,20 +654,94 @@ export function createEngine({
         port: server?.port() ?? null,
         addrs: beacon ? localAddresses() : [],
         shared: [...cfg.shared],
-        // The rule is stillListed's, in lan-sync.mjs, where it can be tested.
-        peers: beacon ? [...beacon.peers.values(), ...manual.values()]
-          .filter(p => stillListed(p, now()))
-          .map(p => ({ ...p, last: lastRound.get(p.fp) ?? null })) : [],
+        // The token this deck is offering, if any. Drawn as the one thing to do
+        // when nobody is paired yet, and put away once somebody is.
+        invite: invite && invite.expiresAt > now()
+          ? { token: invite.token, expiresAt: invite.expiresAt }
+          : null,
+        // Decks somebody accepted, decks that asked and have not been answered,
+        // and decks merely heard. Three lists because they are three different
+        // things a person does something different about.
+        trusted: cfg.trusted.map(t => ({ fp: t.fp, name: t.name })),
+        pending: [...pending.values()].map(p => ({ fp: p.fp, name: p.name, addr: p.addr, at: p.at })),
+        // Only the ones somebody could actually pair with right now, one row
+        // per machine, newest first — see pairable, which is where the rule
+        // that keeps this from becoming a wall of ghosts lives.
+        strangers: (() => {
+          // A deck that was told no is not somebody to offer pairing with. It
+          // has its own row, with the one control that undoes the decision.
+          const heard = [...strangers.values()].filter(p => !declined.has(p.fp));
+          const { shown, more } = pairable(heard, now(), { mine: localAddresses() });
+          return shown.map(p => ({ fp: p.fp, name: p.name, addr: p.addr, port: p.port, at: p.at, more }));
+        })(),
+        // Said no to, by somebody at this keyboard. Listed rather than merely
+        // silenced, because a refusal nobody can see is a refusal nobody can
+        // take back.
+        declined: [...declined.values()].map(p => ({ fp: p.fp, name: p.name, addr: p.addr, at: p.at })),
+        peers: beacon ? (() => {
+          // ONE DECK, ONE ROW, and it takes work because a deck can arrive here
+          // twice by two different routes: heard on the network, and dialled at
+          // an address somebody typed or that an invite carried. Both are the
+          // same machine and neither knows it — the beacon row is keyed by the
+          // fingerprint it announced, the typed row by `host:port`, and until a
+          // connection succeeds nothing joins them.
+          //
+          // What joins them is `learned`: the fingerprint that actually
+          // answered at that address. So every row is given the identity it is
+          // really about, and rows that turn out to share one are merged — the
+          // heard half brings liveness, the dialled half brings the last round.
+          const rows = [];
+          const byId = new Map();
+          const put = row => {
+            const had = byId.get(row.id);
+            if (!had) { byId.set(row.id, row); rows.push(row); return; }
+            // Keep what each half is the authority on.
+            had.lastSeen = had.lastSeen ?? row.lastSeen;
+            had.last = had.last ?? row.last;
+            had.manual = had.manual || row.manual;
+            had.met = had.met || row.met;
+            if (row.name && !had.name) had.name = row.name;
+          };
+          for (const p of [...beacon.peers.values(), ...manual.values()]) {
+            if (!stillListed(p, now())) continue;
+            const met = p.manual ? learned.get(`${p.addr}:${p.port}`) : null;
+            const id = met?.fp ?? p.fp;
+            put({
+              ...p,
+              id,
+              // The fingerprint an unpair has to name. A typed row's own `fp` is
+              // a placeholder built from its address and matches nothing.
+              peerFp: p.manual ? met?.fp ?? null : p.fp,
+              name: met?.name || p.name,
+              met: !!met,
+              paired: !!trustedPeer(cfg.trusted, id),
+              last: lastRound.get(p.fp) ?? null,
+            });
+          }
+          // A DECK WE ARE PAIRED WITH AND DO NOT DIAL. It called us, we accepted
+          // it, and nothing here has its address — which used to mean the panel
+          // listed failing addresses under "paired decks" and left out the one
+          // deck that actually was.
+          for (const t of cfg.trusted) {
+            if (byId.has(t.fp)) continue;
+            put({
+              id: t.fp, fp: t.fp, peerFp: t.fp, name: t.name || t.fp, addr: "", port: 0,
+              paired: true, waiting: true, last: lastRound.get(t.fp) ?? null,
+            });
+          }
+          return rows;
+        })() : [],
       };
     },
     stop() {
       if (timer) clearInterval(timer);
+      // A deliberate stop is not a fault, and the next start says its own.
+      if (!cfg.enabled) stalled = null;
       timer = null;
       beacon?.stop();
       server?.stop();
       beacon = null;
       server = null;
-      key = null;
     },
   };
 }