ccdeck 3.22.15 → 3.23.1

package/src/server/lan-socket.mjs

@@ -25,6 +25,20 @@ import dgram from "node:dgram";
 import { networkInterfaces } from "node:os";
 
 /** An IPv4 dotted quad as four numbers, or null for anything that is not one. */
+/**
+ * What each refusal reason means, in a sentence the LAN panel can print.
+ *
+ * At module scope so it is one object rather than one per frame, and named so
+ * the `Object.hasOwn` guard below reads as the rule it is rather than as
+ * punctuation. The keys are the protocol's, not a user's.
+ */
+const REFUSALS = Object.freeze({
+  pending: "waiting for the other deck to accept this one",
+  declined: "that deck said no",
+  impostor: "that deck has this one pinned under a different key",
+  "bad proof": "the other deck refused this one's proof",
+});
+
 function quad(text) {
   const parts = String(text ?? "").split(".");
   if (parts.length !== 4) return null;
@@ -76,8 +90,9 @@ export function broadcastTargets(ifaces) {
 import net from "node:net";
 import { randomBytes } from "node:crypto";
 import {
-  beaconPayload, beaconVerdict, handshakeTranscript, hostId, notePeer, proof, proofOk,
-  inviteProof, readBeacon, readPub, sessionKey, trustedPeer,
+  beaconPayload, beaconVerdict, challengeFor, cleanName, ephemeralPair, frameChannel, handshakeTranscript,
+  hostId, mixesEphemeral, notePeer, proof, proofOk, inviteProof, inviteProofBack, readBeacon, readChallenge,
+  readEphemeral, readPub, sealsFrames, sessionKey, trustedPeer,
   ANNOUNCE_MS, MAX_BEACON_BYTES, MAX_MANIFEST_BYTES,
 } from "./lan-sync.mjs";
 
@@ -107,10 +122,56 @@ export const MAX_FRAME_BYTES = MAX_MANIFEST_BYTES;
  *  in a peer or somebody holding sockets open to see what happens. */
 export const MAX_SOCKETS = 16;
 
+/**
+ * And the most any ONE host may take of that, because a budget nobody
+ * apportions belongs to whoever grabs it first.
+ *
+ * The cap above is deliberate and documented and it was not shared out, so a
+ * host that did nothing at all could hold the whole of it. Measured against a
+ * real listener with a paired caller:
+ *
+ *     baseline handshake:                OK
+ *     with 16 silent sockets held:       REFUSED: peer closed the connection
+ *     with 16 idle authed sockets held:  REFUSED, and still refused 11s later
+ *
+ * No key, no trust, not one byte sent — sixteen TCP connections and silence.
+ * Every further connection is destroyed on arrival, a paired deck's included,
+ * and re-dialling on a cycle shorter than HANDSHAKE_MS holds it there. Outbound
+ * still works, so the shape of it is "this deck becomes unreachable" rather
+ * than "sync stops" — but a deck nobody can reach is a deck that has stopped
+ * healing logins for everyone pointed at it.
+ *
+ * FOUR RATHER THAN THE OBVIOUS TWO. One round plus one dial-back is two, and
+ * two decks on ONE machine is a supported setup — it is how this gets tested,
+ * and `reuseAddr` exists for it — so the honest ceiling from one address is
+ * twice that. It still means no single host can take more than a quarter of the
+ * table, which is the property that matters.
+ */
+export const MAX_SOCKETS_PER_HOST = 4;
+
+/**
+ * How long a socket may say nothing before it is dropped, at any point.
+ *
+ * HANDSHAKE_MS covers the part before `authed` and stops there: it is cleared
+ * the moment a peer authenticates, and after that a socket had no deadline of
+ * any kind — `live` shrank only on close or error. So a paired deck that
+ * completed four handshakes and then went quiet held its whole share of the
+ * table for as long as its process lived, which makes the budget a permanent
+ * lease rather than a rate limit.
+ *
+ * A round is a request and a response. The caller's own per-frame bell is
+ * ROUND_MS (10s) in lan-engine, and a `want` puts a claude-swap subprocess on
+ * the far side between the two, so a legitimate gap can approach that. Thirty
+ * seconds is three times the longest honest silence and half the gap between
+ * rounds, and a round gets a fresh socket anyway — lan-engine destroys it in
+ * its own `finally`.
+ */
+export const IDLE_MS = 30_000;
+
 /** The shortest gap between two "I am here too" replies to a stranger. Long
  *  enough that a burst of decks starting together cannot make a storm, short
  *  enough that starting two decks by hand feels instant. */
-export const REPLY_COOLDOWN_MS = 2_000;
+const REPLY_COOLDOWN_MS = 2_000;
 
 /**
  * The shouting half.
@@ -312,7 +373,15 @@ export function frameReader(onFrame, onRefuse, max = MAX_FRAME_BYTES) {
       if (!msg || typeof msg !== "object" || Array.isArray(msg)) {
         dead = true; buf = ""; onRefuse("not an object"); return;
       }
-      onFrame(msg);
+      // A HANDLER THAT THROWS ENDS ITS CONNECTION, NOT THE PROCESS. This runs
+      // inside the socket's `data` event, where nothing above catches, so a
+      // throw from a frame handler took the whole deck down — and every frame
+      // read here has come off the network before anybody is trusted. The
+      // handlers are meant never to throw; this is what holds when one does.
+      // The error goes on with the refusal, so the next one that hides here is
+      // logged with its stack rather than as two words.
+      try { onFrame(msg); }
+      catch (err) { dead = true; buf = ""; onRefuse("bad frame", err); return; }
       if (dead) return;
     }
   };
@@ -335,7 +404,9 @@ export function sendFrame(sock, obj) {
  * lesson has.
  *
  * `handlers` is called only with authenticated frames, and it never sees the
- * handshake at all.
+ * handshake at all. On a sealed connection it is handed each frame already
+ * opened, and `ctx.send` seals whatever it is given — see frameChannel.
+ * `ctx.sealed` says which kind of connection it is on.
  */
 export function createSyncServer({
   fp, pub, name, secret, handlers, onError, host = "0.0.0.0", prefer = 0,
@@ -358,15 +429,60 @@ export function createSyncServer({
   /** One was used. The caller stores the pairing and retires the invite: a
    *  token that pairs twice is a token worth stealing twice. */
   onInviteUsed,
+  /** How long a socket may say nothing before it is dropped — see IDLE_MS,
+   *  which is what the deck runs on. A parameter only so the suite can drive
+   *  the reclaim in a few hundred milliseconds rather than half a minute; a
+   *  case that slept for the real value would be thirty seconds of CI per run
+   *  and would still only be checking a timer. */
+  idleMs = IDLE_MS,
+  /** Whether this deck seals every frame after the handshake with a peer that
+   *  says it does too — see frameChannel. On in every real deck. False makes
+   *  this listener announce nothing and seal nothing, which is the wire every
+   *  deck before #810 speaks, and is how the suite plays one. */
+  sealFrames = true,
+  /** Whether this deck mixes a key pair made for each connection into its key,
+   *  with a peer that says it does too — see sessionKey. On in every real
+   *  deck. False makes this listener's challenge say only that it seals, which
+   *  is the wire of a deck of #810's version, and is how the suite plays one.
+   *  It rides on `sealFrames`, as it does on the wire. */
+  ephemeral = true,
 } = {}) {
   let server = null;
   const live = new Set();
 
+  /** Which host a socket came from, in one spelling. Node reports an IPv4 peer
+   *  on a dual-stack listener as `::ffff:127.0.0.1`, and two spellings of one
+   *  address would be two budgets. Empty for a socket already going away, which
+   *  is why the count below only ever matches non-empty ones. */
+  const from = sock => sock.remoteAddress?.replace(/^::ffff:/, "") ?? "";
+
   const onConnection = sock => {
     if (!secret || live.size >= MAX_SOCKETS) { sock.destroy(); return; }
+    // AND NOT ALL OF IT TO ONE CALLER. The table is small on purpose; what was
+    // missing is that it was not shared out, so the cheapest thing on the
+    // network — connect, say nothing — took the whole of it. See
+    // MAX_SOCKETS_PER_HOST.
+    //
+    // An address we cannot read is counted by the total alone rather than
+    // lumped together with every other unreadable one: an accepted TCP socket
+    // always has a peer, so an empty answer here is a socket already on its way
+    // out, and treating those as one host would let a closing connection refuse
+    // a real one.
+    const here = from(sock);
+    if (here) {
+      let mine = 0;
+      for (const s of live) if (from(s) === here) mine++;
+      if (mine >= MAX_SOCKETS_PER_HOST) { sock.destroy(); return; }
+    }
     live.add(sock);
     sock.setEncoding("utf8");
     sock.setNoDelay(true);
+    // ARMED HERE RATHER THAN AT `authed`, and that is the point of it: the
+    // handshake deadline below is cleared the moment a peer authenticates, and
+    // this is the one that is not. It is longer than HANDSHAKE_MS, so it never
+    // decides the outcome of a handshake — it is what ends a socket that has
+    // gone quiet afterwards, which nothing used to.
+    sock.setTimeout(idleMs, () => sock.destroy());
 
     let authed = false;
     let peerFp = null;
@@ -374,8 +490,30 @@ export function createSyncServer({
     let peerName = "";
     let peerPort = null;
     let key = null;
-    const myChallenge = randomBytes(16).toString("hex");
+    // Carrying this deck's marks — that it seals, and that it mixes a key pair
+    // of its own into the key — inside the one field the handshake already
+    // binds. See "THE ANNOUNCEMENT RIDES INSIDE THE CHALLENGE" and EPHEMERAL
+    // in lan-sync.mjs.
+    const myChallenge = challengeFor({ seals: sealFrames, ephemeral });
     let theirChallenge = null;
+    /** What the key was derived over, kept so the invite proofs below are made
+     *  over the same string rather than rebuilt from its parts — which, once
+     *  the ephemeral keys are in it, only the `hello` branch holds all of. */
+    let transcript = null;
+    /** The sealed channel, once the handshake is done and both challenges said
+     *  so; null for a peer that did not, which is answered in the clear exactly
+     *  as before. Set once and never changed. */
+    let chan = null;
+    /** Set by `refuse`, and read first by every frame after it. A refusal is the
+     *  end of this socket, and nothing the peer sent in the same write may be
+     *  read against whatever state the refusal left half-set. */
+    let refused = false;
+    /** Called at the moment `authed` turns true, so the first frame after `ok`
+     *  in either direction is already the sealed kind. Both challenges are
+     *  known by then, and the caller's proof has just said it saw the same two
+     *  this end did. */
+    const sealedChannel = () =>
+      (sealsFrames(myChallenge) && sealsFrames(theirChallenge) ? frameChannel(key, "listener") : null);
 
     // Armed before the first byte is read, and cleared only by a completed
     // handshake. A socket that connects and says nothing is the cheapest
@@ -407,15 +545,28 @@ export function createSyncServer({
      * that is the whole point. The timer is the backstop for a peer whose
      * receive window is full and whose callback therefore never comes.
      */
-    const refuse = why => {
-      onError?.("frame", new Error(why));
+    const refuse = (why, cause) => {
+      refused = true;
+      // The thrown error itself when frameReader caught one, so the terminal
+      // shows what threw and where rather than only "bad frame".
+      onError?.("frame", cause ?? new Error(why));
       const bye = () => { try { sock.destroy(); } catch { /* already gone */ } };
+      // SEALED, A REFUSAL IS A CLOSE. Once both ends seal nothing leaves this
+      // socket in the clear, not even a word about why — and a peer whose frame
+      // would not open has nothing it could do with the word anyway.
+      if (chan) { bye(); return; }
       try { sock.write(`${JSON.stringify({ t: "no", why })}\n`, bye); }
       catch { bye(); return; }
       setTimeout(bye, 250).unref?.();
     };
 
     sock.on("data", frameReader(msg => {
+      // NOTHING AFTER A REFUSAL. The reader hands over every frame in a chunk,
+      // and `refuse` destroys the socket without stopping it. So a `hello`
+      // refused after its challenge was stored and before a key existed could
+      // be followed, in the same write, by an `auth` that reached `proof` with
+      // no key: a throw in this handler, and the end of the process.
+      if (refused) return;
       if (!authed) {
         // FOUR MESSAGES, and the order is chosen so that a stranger who merely
         // connects receives nothing derived from a key.
@@ -430,8 +581,18 @@ export function createSyncServer({
         // value. What the exchange establishes is that whoever is on the other
         // end holds the private half of the key they claimed — which is the
         // only thing a pin can later be checked against.
+        //
+        // AND, FROM #1120, ONE KEY PAIR MORE AT EACH END, made for this
+        // connection alone: the caller's public half rides in `hello` as
+        // `epk`, ours in `challenge`. Public too, and in the clear too. What
+        // they buy is a connection key that is gone once both ends have let go
+        // of the private halves, whoever takes either long-term key later —
+        // see sessionKey.
         if (msg.t === "hello") {
-          if (theirChallenge || typeof msg.challenge !== "string") return refuse("bad hello");
+          // A string of letters, digits, `.`, `_` and `-` — a `|` inside it
+          // would let the transcript come out the same on both ends while each
+          // read a different challenge. See readChallenge.
+          if (theirChallenge || !readChallenge(msg.challenge)) return refuse("bad hello");
           const them = readPub(msg.pub);
           // The fingerprint is a hash of the key, so a hello whose two halves
           // disagree is not a deck with a stale field, it is somebody trying to
@@ -440,13 +601,60 @@ export function createSyncServer({
           theirChallenge = msg.challenge;
           peerFp = them.fp;
           peerPub = them.pub;
-          peerName = typeof msg.name === "string" ? msg.name : "";
+          // THROUGH cleanName, like the beacon and the invite. This path — the
+          // handshake — was the one that skipped it, and it is the one that
+          // feeds the pairing prompt and cfg.trusted, which index.mjs writes to
+          // prefs.json. So the only bound on the name an operator reads before
+          // pressing Accept was the 128 KB frame cap.
+          //
+          // cleanName caps at MAX_NAME (40) and collapses \s+, which includes
+          // U+00A0 — and 200 non-breaking spaces neither collapse in HTML nor
+          // offer a break opportunity, so a name of "Alice's laptop at
+          // 192.168.1.10 wants to pair" + padding pushed the REAL address out
+          // of a fixed 288px column and left a complete, plausible sentence.
+          peerName = cleanName(msg.name, "");
           peerPort = Number.isInteger(msg.port) && msg.port > 0 && msg.port < 65_536 ? msg.port : null;
-          key = sessionKey(secret, peerPub, handshakeTranscript(peerFp, fp, theirChallenge, myChallenge));
-          sendFrame(sock, { t: "challenge", fp, pub, name, challenge: myChallenge });
+          // MIXED WHEN BOTH CHALLENGES SAY SO, and only then: the two strings
+          // the proofs bind decide it, never whether a field turned up. Once
+          // both say so, a hello with no usable key is refused rather than
+          // answered the old way, because answering the old way is the
+          // downgrade. See EPHEMERAL in lan-sync.mjs.
+          //
+          // A KEY OFFERED IS A KEY ANSWERED, whatever the challenges say, so
+          // what this end sends depends only on what it was sent. When the two
+          // do not mix, ours goes out and is never used. That happens only
+          // between two decks of this version whose challenges somebody edited
+          // on the way, and there it takes the dialler on to a proof this end
+          // refuses by name — `bad proof`, as for every other edit to a
+          // challenge — rather than stopping it one message short. Made here
+          // and not when the socket opened, so a connection that never says
+          // hello costs what it always did.
+          const theirEphemeral = readEphemeral(msg.epk);
+          const mixing = mixesEphemeral(myChallenge) && mixesEphemeral(theirChallenge);
+          if (mixing && !theirEphemeral) return refuse("bad hello");
+          let mine = theirEphemeral && mixesEphemeral(myChallenge) ? ephemeralPair() : null;
+          const epk = mine?.pub;
+          transcript = mixing
+            ? handshakeTranscript(peerFp, fp, theirChallenge, myChallenge, theirEphemeral, epk)
+            : handshakeTranscript(peerFp, fp, theirChallenge, myChallenge);
+          // A key X25519 cannot use throws in here, and nothing above this
+          // handler catches it — see readPub for what that throw used to do.
+          try {
+            key = sessionKey(secret, peerPub, transcript,
+              mixing ? { role: "listener", priv: mine.priv, peer: theirEphemeral } : null);
+          } catch {
+            return refuse("bad hello");
+          } finally {
+            // The private half, let go before a byte of the reply is written.
+            mine = null;
+          }
+          sendFrame(sock, { t: "challenge", fp, pub, name, challenge: myChallenge, ...(epk ? { epk } : {}) });
           return;
         }
-        if (msg.t !== "auth" || !theirChallenge) return refuse("expected auth");
+        // A key, too: a challenge on record says a `hello` arrived, not that one
+        // was accepted. Unreachable after the guard at the top of this handler,
+        // and stated anyway, because it is the rule `proof` below depends on.
+        if (msg.t !== "auth" || !theirChallenge || !key) return refuse("expected auth");
         const want = proof(key, {
           challenge: theirChallenge, peerChallenge: myChallenge,
           fromFp: peerFp, toFp: fp, direction: "hello",
@@ -465,32 +673,51 @@ export function createSyncServer({
           // name — refused loudly rather than quietly re-pinned.
           return refuse("impostor");
         }
+        // AN INVITE THIS DECK HANDED OUT, PRESENTED BACK. Whoever is calling
+        // holds a token the owner of this machine copied and sent, which is the
+        // same decision the accept button is — made earlier, and made once.
+        //
+        // The proof is over the transcript, so it is worth nothing to somebody
+        // who recorded an earlier exchange, and the code itself never travels.
+        //
+        // ASKED BEFORE "DO I KNOW THIS DECK", because the two questions are
+        // independent and the answer to this one is owed to the caller either
+        // way. A caller that sent a code is waiting to be shown one back, and a
+        // deck it has ALREADY paired with is not exempt from that — somebody
+        // pasting a token into a deck that happens to be paired already would
+        // otherwise be told the minter does not hold its own invite.
+        // `offer` rather than `live`, which is what this used to be called: the
+        // socket table one scope out is also `live`, and widening this block
+        // widened the shadow with it.
+        const offer = invite();
+        // Over the transcript the key came from — the ephemeral keys in it
+        // when the two mix — which is the string the dialler proved over too.
+        const heldInvite = !!offer && typeof msg.invite === "string"
+          && proofOk(inviteProof(offer.code, transcript), msg.invite);
+        // AND THE CODE, BACK. The session proof says "I hold the private half
+        // of the key I just showed you", which anything with a socket can say.
+        // This says "I am the deck whose owner minted that token", which only
+        // the minter can — and a caller joining on an invite has no pin to
+        // check against, so it is the only thing standing between an invite
+        // address and whoever else is reachable there.
+        const back = heldInvite ? { inviteProof: inviteProofBack(offer.code, transcript) } : {};
         if (!known) {
-          // AN INVITE THIS DECK HANDED OUT, PRESENTED BACK. Whoever is calling
-          // holds a token the owner of this machine copied and sent, which is
-          // the same decision the accept button is — made earlier, and made
-          // once. So there is nothing to press: the deck is pinned here.
-          //
-          // The proof is over the transcript, so it is worth nothing to
-          // somebody who recorded an earlier exchange, and the code itself
-          // never travels.
-          const live = invite();
-          if (live && typeof msg.invite === "string") {
-            const want = inviteProof(live.code, handshakeTranscript(peerFp, fp, theirChallenge, myChallenge));
-            if (proofOk(want, msg.invite)) {
-              onInviteUsed?.({ fp: peerFp, pub: peerPub, name: peerName, port: peerPort,
-                addr: sock.remoteAddress?.replace(/^::ffff:/, "") ?? "" });
-              authed = true;
-              clearTimeout(deadline);
-              sendFrame(sock, {
-                t: "ok", fp, name,
-                proof: proof(key, {
-                  challenge: myChallenge, peerChallenge: theirChallenge,
-                  fromFp: fp, toFp: peerFp, direction: "reply",
-                }),
-              });
-              return;
-            }
+          if (heldInvite) {
+            // So there is nothing to press: the deck is pinned here.
+            onInviteUsed?.({ fp: peerFp, pub: peerPub, name: peerName, port: peerPort,
+              addr: sock.remoteAddress?.replace(/^::ffff:/, "") ?? "" });
+            authed = true;
+            chan = sealedChannel();
+            clearTimeout(deadline);
+            sendFrame(sock, {
+              t: "ok", fp, name,
+              proof: proof(key, {
+                challenge: myChallenge, peerChallenge: theirChallenge,
+                fromFp: fp, toFp: peerFp, direction: "reply",
+              }),
+              ...back,
+            });
+            return;
           }
           // A DECK THIS ONE'S OWNER ALREADY ANSWERED, and the answer was no.
           // It is not asked again here, and — the half a held refusal cannot
@@ -513,19 +740,34 @@ export function createSyncServer({
         }
 
         authed = true;
+        chan = sealedChannel();
         clearTimeout(deadline);
         // And ours, so the caller knows it reached the deck it pinned rather
-        // than something standing in the way of one.
+        // than something standing in the way of one. Plus the invite, when one
+        // was presented and held: a deck already on this list is not a reason
+        // to leave a caller's question unanswered. Nothing is retired on this
+        // path — nobody was paired, because they already were.
         sendFrame(sock, {
           t: "ok", fp, name,
           proof: proof(key, {
             challenge: myChallenge, peerChallenge: theirChallenge,
             fromFp: fp, toFp: peerFp, direction: "reply",
           }),
+          ...back,
         });
         return;
       }
-      handlers?.(msg, { sock, peerFp, key, send: obj => sendFrame(sock, obj) });
+      // SEALED FROM HERE WHEN BOTH ENDS SAID SO, AND ONLY SEALED. A frame that
+      // does not open is refused and the socket goes with it — see
+      // frameChannel for what "does not open" covers: altered, replayed,
+      // reordered, dropped, sent back, or simply plain. There is no reading it
+      // as it stands instead; that fallback would be the downgrade.
+      const frame = chan ? chan.unwrap(msg) : msg;
+      if (!frame) return refuse("a sealed frame did not open");
+      handlers?.(frame, {
+        sock, peerFp, key, sealed: !!chan,
+        send: obj => sendFrame(sock, chan ? chan.wrap(obj) : obj),
+      });
     }, refuse));
   };
 
@@ -589,15 +831,34 @@ export function connectToPeer({
   /** The public key we pinned for this deck the first time, or null for a deck
    *  we are meeting — an address somebody typed. */
   expectPub = null,
+  /** Whether the deck that minted `code` said it will prove it holds one too.
+   *  From the token's own `pb`, which is the only way to tell a deck that will
+   *  not from a deck that cannot — see mintInvite. False leaves this path
+   *  exactly as it shipped, for a token minted by an older deck. */
+  inviteProvesBack = false,
+  /** Whether this deck seals every frame after the handshake with a deck that
+   *  says it does too — see frameChannel. False announces nothing and seals
+   *  nothing, exactly as every deck before #810 dials; only the suite asks. */
+  sealFrames = true,
+  /** Whether this deck mixes a key pair made for the connection into its key,
+   *  with a deck that says it does too — see sessionKey. False dials exactly
+   *  as a deck of #810's version does; only the suite asks. */
+  ephemeral = true,
 }) {
   return new Promise((resolve, reject) => {
-    const myChallenge = randomBytes(16).toString("hex");
+    const myChallenge = challengeFor({ seals: sealFrames, ephemeral });
+    // Made before the other deck is heard from, because the public half goes
+    // in the hello. Let go of once the key is derived — unused, when the deck
+    // that answers turns out not to mix — and on every way out below.
+    let mine = mixesEphemeral(myChallenge) ? ephemeralPair() : null;
+    const myEpk = mine?.pub;
     const sock = net.createConnection({ host, port });
     sock.setEncoding("utf8");
     let settled = false;
     const fail = err => {
       if (settled) return;
       settled = true;
+      mine = null;
       sock.destroy();
       reject(err instanceof Error ? err : new Error(String(err)));
     };
@@ -614,28 +875,41 @@ export function connectToPeer({
       // — that one is ephemeral and useless to dial. Without it a deck can
       // accept an incoming request and still have no way to reach back, so the
       // pairing is mutual on paper and one-way in fact.
-      sendFrame(sock, { t: "hello", fp, pub, name, port: myPort, challenge: myChallenge });
+      // `epk` is this connection's key pair, offered: a deck from before #1120
+      // reads past a field it does not know, and one of this version answers.
+      sendFrame(sock, {
+        t: "hello", fp, pub, name, port: myPort, challenge: myChallenge, ...(myEpk ? { epk: myEpk } : {}),
+      });
     });
 
     let theirChallenge = null;
     let theirFp = null;
     let theirPub = null;
     let key = null;
+    /** What the key was derived over; the invite proofs are made over it too. */
+    let transcript = null;
     sock.on("data", frameReader(msg => {
       if (settled) return;
       // A deck that heard us and said no. Each reason is a different problem
       // with a different fix, and until this frame existed they were all one
-      // silent close that read as a firewall.
+      // silent close that read as a firewall. See REFUSALS.
       if (msg.t === "no") {
-        return fail(new Error({
-          pending: "waiting for the other deck to accept this one",
-          declined: "that deck said no",
-          impostor: "that deck has this one pinned under a different key",
-          "bad proof": "the other deck refused this one's proof",
-        }[msg.why] ?? "the other deck refused this handshake"));
+        // `Object.hasOwn`, and here more than anywhere: `msg.why` is a field in
+        // a frame written by the OTHER MACHINE, which is the case admin-failure
+        // states the rule for (#474). Every member of Object.prototype answers
+        // a plain bracket read with an inherited value that is neither nullish
+        // nor falsy, so `?? "the other deck refused this handshake"` never
+        // fired for one — `{...}["constructor"]` is the Object function itself,
+        // and `new Error(Object).message` is the string "function Object() {
+        // [native code] }". lan-engine files that as `lastRound.error` and the
+        // LAN panel prints it verbatim, so a peer chose what appeared in the
+        // user's interface. Asking whether the map has a ROW is the question
+        // this read was always trying to ask; no real reason moves.
+        return fail(new Error(Object.hasOwn(REFUSALS, msg.why) ? REFUSALS[msg.why]
+          : "the other deck refused this handshake"));
       }
       if (msg.t === "challenge") {
-        if (theirFp || typeof msg.challenge !== "string") return fail(new Error("bad challenge"));
+        if (theirFp || !readChallenge(msg.challenge)) return fail(new Error("bad challenge"));
         const them = readPub(msg.pub);
         if (!them || them.fp !== msg.fp) return fail(new Error("bad challenge"));
         // THE PIN, CHECKED BEFORE ANYTHING ELSE. A deck we have paired with is
@@ -647,7 +921,25 @@ export function connectToPeer({
         theirChallenge = msg.challenge;
         theirFp = them.fp;
         theirPub = them.pub;
-        key = sessionKey(secret, theirPub, handshakeTranscript(fp, theirFp, myChallenge, theirChallenge));
+        // Mixed when both challenges say so, as at the listener, and then the
+        // listener's key is required: a deck of this version that says it
+        // mixes and sends no key is not an older deck, it is a deck whose key
+        // was taken out on the way. Refused, and never read the old way.
+        const mixing = mixesEphemeral(myChallenge) && mixesEphemeral(theirChallenge);
+        const theirEphemeral = mixing ? readEphemeral(msg.epk) : null;
+        if (mixing && !theirEphemeral) return fail(new Error("bad challenge"));
+        transcript = mixing
+          ? handshakeTranscript(fp, theirFp, myChallenge, theirChallenge, myEpk, theirEphemeral)
+          : handshakeTranscript(fp, theirFp, myChallenge, theirChallenge);
+        try {
+          key = sessionKey(secret, theirPub, transcript,
+            mixing ? { role: "caller", priv: mine.priv, peer: theirEphemeral } : null);
+        } catch {
+          return fail(new Error("bad challenge"));
+        } finally {
+          // Used or not, the private half goes now.
+          mine = null;
+        }
         sendFrame(sock, {
           t: "auth",
           proof: proof(key, {
@@ -657,26 +949,61 @@ export function connectToPeer({
           // Only when joining on an invite. Sent in the same frame as the
           // session proof so a deck that holds a token is paired in one round
           // trip rather than being queued behind somebody else's press.
-          ...(code ? { invite: inviteProof(code, handshakeTranscript(fp, theirFp, myChallenge, theirChallenge)) } : {}),
+          ...(code ? { invite: inviteProof(code, transcript) } : {}),
         });
         return;
       }
       // The same deck that gave us the challenge, or nothing: a reply naming a
       // different fingerprint is a second party in the middle of this.
-      if (msg.t !== "ok" || msg.fp !== theirFp) return fail(new Error("expected ok"));
+      //
+      // AND A CHALLENGE FIRST. `theirFp` is null until one is accepted, so an
+      // `ok` sent as the very first frame with `fp: null` matched it — null is
+      // null — and walked into `proof` with no key, which throws. Before #1146
+      // that throw ended the deck, and this end dials whatever address a beacon
+      // announces; since #1146 the reader catches it as "bad frame". Neither is
+      // the answer: an `ok` before a challenge is out of order, and says so.
+      if (msg.t !== "ok" || !theirFp || !key || msg.fp !== theirFp) return fail(new Error("expected ok"));
       const want = proof(key, {
         challenge: theirChallenge, peerChallenge: myChallenge,
         fromFp: theirFp, toFp: fp, direction: "reply",
       });
       if (!proofOk(want, msg.proof)) return fail(new Error("that deck could not prove its own key"));
+      // AND THAT IT IS THE DECK THE INVITE NAMED. The proof above is about a
+      // key the responder chose a moment ago; this one is about a code it had
+      // to have been given. `join` has no pin to pass, so `expectPub` above is
+      // null on this path and this is the only check that distinguishes the
+      // deck whose owner minted the token from whatever else is reachable at
+      // one of the ten addresses the token happens to carry.
+      //
+      // The caller giving up here is not the end of the attempt: `join` walks
+      // the rest of the list, so a deck answering at a stale or borrowed
+      // address costs one failed address instead of winning the whole token.
+      if (code && inviteProvesBack) {
+        const back = inviteProofBack(code, transcript);
+        if (!proofOk(back, msg.inviteProof)) {
+          return fail(new Error("that deck does not hold the invite"));
+        }
+      }
+      // Sealed from here when both challenges said so. The listener decided
+      // the same at the same moment from the same two strings, and the proof
+      // just checked is what says it saw the same two. See frameChannel.
+      const chan = sealsFrames(myChallenge) && sealsFrames(theirChallenge) ? frameChannel(key, "caller") : null;
       settled = true;
       clearTimeout(timer);
       sock.removeAllListeners("close");
       resolve({
-        sock, key,
-        peerFp: theirFp, peerPub: theirPub, peerName: msg.name,
-        send: obj => sendFrame(sock, obj),
+        sock, key, sealed: !!chan,
+        peerFp: theirFp, peerPub: theirPub, peerName: cleanName(msg.name, ""),
+        send: obj => sendFrame(sock, chan ? chan.wrap(obj) : obj),
+        /** What a frame from the other end says — or null on a sealed
+         *  connection when it does not open, which ends the connection: every
+         *  frame after it would fail too. On a connection to a deck from before
+         *  #810, a plain frame passes through as it arrived. */
+        read: frame => (chan ? chan.unwrap(frame) : frame),
       });
-    }, fail));
+    // A refusal from the reader, with the thrown error as its cause when there
+    // was one: the message is the one it always was, and whatever logs the
+    // rejection can reach what actually threw.
+    }, (why, cause) => fail(cause ? new Error(why, { cause }) : new Error(why))));
   });
 }