@twinsearth/w2m-dsh-plugin 0.5.9 → 0.6.2

package/src/agent/crypto.mjs

@@ -119,6 +119,15 @@ export const SESSION_KEY_LABEL = 'w2m-p2p-crypto v1 session';
 /** `k0 = HKDF(ECDH(s_i,s_r))` of §4: proves possession of the static key. */
 export const STATIC_KEY_LABEL = 'w2m-p2p-crypto v1 static';
 
+/**
+ * Domain separator of a `REFUSE`'s optional MAC — a *different* label from every handshake MAC, and a
+ * different *input*: `ECDH(e_i, s_r)` rather than `ECDH(s_i, s_r)` (see the note above `REFUSE`).
+ *
+ * Without the label, a refusal MAC and `mac'` of §4 would both be `sealMac(·, …)` over 32-byte hashes
+ * a hostile peer could try to make collide. One extra hash input makes the two families disjoint.
+ */
+export const REFUSE_MAC_LABEL = 'w2m-p2p-crypto v1 refuse';
+
 /** The literal string §4's `hash(prologue ——` starts with. */
 export const PROLOGUE = 'w2m-p2p-crypto v1 prologue';
 
@@ -200,6 +209,43 @@ export const CRYPTO_REASON = Object.freeze({
   MALFORMED: 'P2P_CRYPTO_MALFORMED',
   /** The peer never learned a key (an older build), so a direct channel with it is plaintext. */
   PLAINTEXT_PEER: 'P2P_CRYPTO_PLAINTEXT_PEER',
+  /**
+   * The relay is not serving peer keys, so no handshake can be armed by anyone (v0.6.2).
+   *
+   * Distinct from {@link PLAINTEXT_PEER} on purpose, and the distinction is the whole reason this code
+   * exists. A relay older than v0.6.0 has never heard of `static_key`: it accepts an announcement,
+   * silently drops the field, and serves an entry without it. Every peer then looks exactly like a
+   * machine that has no key — which is how a stale *relay* came to be reported for hours as "the peer
+   * is an older build", pointing the investigation at the one component that was up to date.
+   *
+   * Detected from this node's own announcement: we POST a key, so the entry the relay echoes back says
+   * whether it kept it. No relay cooperation and no version negotiation required, which is what makes
+   * it work against the relay that is actually deployed.
+   */
+  RELAY_NO_KEYS: 'P2P_CRYPTO_RELAY_NO_KEYS',
+  /**
+   * A `REFUSE` datagram was **dropped**, not honoured: it named a session this punch did not agree.
+   *
+   * The four `REFUSE_*` codes below name an *ignored datagram* rather than a failed punch, which is
+   * deliberate and is the whole of the v0.6.0 hardening: an unauthenticated refusal that cannot be
+   * tied to this punch must not be able to change its outcome, and it must not be able to fail it
+   * either — an attacker who could turn "the peer never answered" into "the peer refused" would have
+   * been handed a denial of service in exchange for closing a downgrade.
+   */
+  REFUSE_SESSION_MISMATCH: 'P2P_CRYPTO_REFUSE_SESSION_MISMATCH',
+  /** A `REFUSE` datagram was dropped: it came from an address this punch never dialled. */
+  REFUSE_UNPUNCHED_SOURCE: 'P2P_CRYPTO_REFUSE_UNPUNCHED_SOURCE',
+  /** A `REFUSE` datagram was dropped: it carried a `k0` MAC that did not verify. */
+  REFUSE_BAD_MAC: 'P2P_CRYPTO_REFUSE_BAD_MAC',
+  /**
+   * A downgrade-inducing `REFUSE` was dropped: it did not come from the peer that answered the punch.
+   *
+   * `NO_KEY`/`NO_PEER_KEY` say "I cannot take part, use the plaintext channel" — the one refusal that
+   * changes the outcome into something weaker than a failure. Requiring it to come from the address
+   * that actually answered the punch is what stops a datagram from a third address from choosing a
+   * plaintext channel on the peer's behalf.
+   */
+  REFUSE_UNCORROBORATED: 'P2P_CRYPTO_REFUSE_UNCORROBORATED',
 });
 
 /* -------------------------------------------------------------------------- */
@@ -788,12 +834,35 @@ export function bytesEqual(a, b) {
  *
  *     HELLO      magic|version|session u32|e[32]|idLen u8|machineId|mac[48]
  *     HELLO_ACK  magic|version|session u32|e[32]|idLen u8|machineId|mac[48]
- *     REFUSE     magic|version|session u32|code u8|idLen u8|machineId
+ *     REFUSE     magic|version|session u32|code u8|idLen u8|machineId[|mac 48]
+ *
+ * `mac` is 32 bytes of ciphertext plus 16 of tag (§4's AEAD-produced MAC).
+ *
+ * `REFUSE` **may** be unauthenticated, and that is not an oversight: it is sent precisely when we
+ * cannot authenticate the peer (we hold no key for it), so it can carry no proof — and it is what
+ * turns "the handshake did not complete" into a named reason on *both* ends instead of a timeout on
+ * one of them. When the responder received a handshake `HELLO` it holds the initiator's ephemeral
+ * `e_i`, and it *always* holds its own static private key `s_r`, so it can always derive
+ * `k_ref = HKDF(ECDH(e_i, s_r), REFUSE_MAC_LABEL)` — a key the initiator derives just as easily from
+ * `e_i`'s private half and `s_r`'s public key, and that nobody else can derive at all. The trailing 48
+ * bytes of a refusal are then `sealMac(k_ref, hash(REFUSE_MAC_LABEL ‖ the refusal without its MAC))`.
+ *
+ * That is the asymmetry this file relies on, and it is worth stating plainly because the naive
+ * version of it is wrong: `k0 = ECDH(s_i, s_r)` — the handshake MAC's key — is *not* usable here. A
+ * responder that has no key for us (or a stale one) cannot compute it, and those are exactly the two
+ * cases that send a refusal. `k_ref` needs neither end to hold the other's static key: the initiator
+ * sends `e_i` in the clear, and the responder's `s_r` is public. What it proves is what a refusal
+ * needs to prove — *this datagram came from the machine that holds `s_r`* — and it is therefore
+ * available to `BAD_MAC` (our proof did not verify), `NO_PEER_KEY` (we hold no key for you) and
+ * `UNKNOWN_PEER` alike.
  *
- * `mac` is 32 bytes of ciphertext plus 16 of tag (§4's AEAD-produced MAC). `REFUSE` is deliberately
- * unauthenticated: it is sent precisely when we cannot authenticate the peer, so it can carry no
- * proof —and it is what turns "the handshake did not complete" into a named reason on *both* ends
- * instead of a timeout on one of them.
+ * `VERSION` is the one refusal that stays bare, and deliberately: the peer that needs it speaks a
+ * handshake version whose body layout this build cannot rely on, so a trailing field it does not know
+ * about would be worse than useless.
+ *
+ * The unauthenticated form still exists and is still honoured by `p2p.mjs` — a peer running an older
+ * build cannot produce `k_ref` and must not lose its plaintext channel for it. What `p2p.mjs` will not
+ * do is let a datagram it cannot tie to the punch (see `REFUSE_GUARD` there) rewrite a ledger.
  */
 
 /**
@@ -808,6 +877,14 @@ export function bytesEqual(a, b) {
  *     it is not a downgrade: the peer never offered a key to downgrade from.
  *   * `BAD_MAC` — the peer *is* known and its MAC over its static key did not verify. That is either a
  *     stale key or an impersonation attempt, and the initiator treats it as terminal.
+ *
+ * The two known-peer codes (`BAD_MAC`, `REPLAY`) can be sealed with the ephemeral-static key of
+ * {@link refusalMacKey}, and so can the two unknown-peer codes — `k_ref` needs no static key on file.
+ * `VERSION` is the exception and stays bare. What `p2p.mjs` does with that asymmetry (`REFUSE_GUARD`
+ * there) is the rule: a *plaintext-choosing* refusal (`NO_KEY`, `NO_PEER_KEY`) must either verify its
+ * seal or arrive, unsealed, from the endpoint that acknowledged the punch; a terminal refusal is
+ * honoured from a dialled address sealed or not, with `refusal_authenticated` recording whether the
+ * seal was proof. Nothing dropped ever fails a punch.
  */
 export const REFUSE = Object.freeze({
   UNKNOWN_PEER: 1,
@@ -894,32 +971,136 @@ export function decodeHello(body) {
   };
 }
 
-/** @param {number} session @param {number} code @param {string|null} [machineId] @returns {Buffer} */
-export function encodeRefuse(session, code, machineId = null) {
+/**
+ * Build a `REFUSE` body, optionally with the trailing `k0` MAC of {@link sealRefuse}.
+ *
+ * @param {number} session
+ * @param {number} code
+ * @param {string|null} [machineId]
+ * @param {Buffer|null} [mac] 48 bytes, or null for the unauthenticated form.
+ * @returns {Buffer}
+ */
+export function encodeRefuse(session, code, machineId = null, mac = null) {
   const id = (machineId === null ? Buffer.alloc(0) : Buffer.from(machineId, 'utf8')).subarray(
     0,
     MAX_HANDSHAKE_MACHINE_ID,
   );
-  const out = Buffer.alloc(8 + id.length);
+  const trailing = mac === null ? Buffer.alloc(0) : mac;
+  if (trailing.length !== 0 && trailing.length !== MAC_BYTES) {
+    throw new TypeError(`encodeRefuse: a refusal MAC must be ${MAC_BYTES} bytes`);
+  }
+  const out = Buffer.alloc(8 + id.length + trailing.length);
   out.writeUInt8(FRAME_MAGIC, 0);
   out.writeUInt8(CRYPTO_VERSION, 1);
   out.writeUInt32BE(session >>> 0, 2);
   out.writeUInt8(code, 6);
   out.writeUInt8(id.length, 7);
   id.copy(out, 8);
+  trailing.copy(out, 8 + id.length);
   return out;
 }
 
-/** @param {Buffer} body @returns {{session:number, code:number, machineId:string|null}|null} */
+/**
+ * Parse a `REFUSE` body — both the bare form and the `k0`-MAC'd one — or null.
+ *
+ * Strict about the length, in both forms, and that strictness is load-bearing rather than tidy: the
+ * body being parsed here arrives as the body of a **`HELLO_ACK`**, and a handshake body is also
+ * `magic|version|session|…` with a byte that can look like an id length. An earlier version accepted
+ * exactly one length and validated nothing else, so a genuine `HELLO_ACK` could be read as a refusal
+ * — `body[6]` (the first byte of the responder's ephemeral, which is random) became the refusal code
+ * and `body[7]` the id length — roughly one handshake in 256 refusing itself. The machine-id check
+ * below is what makes that collision impossible rather than unlikely: a handshake body's bytes from
+ * offset 8 on are key material, and key material is not a printable machine id.
+ *
+ * @param {Buffer} body
+ * @returns {{session:number, code:number, machineId:string|null, mac:Buffer|null, headerBytes:number,
+ *   bytes:Buffer}|null}
+ */
 export function decodeRefuse(body) {
   if (!Buffer.isBuffer(body) || body.length < 8) return null;
   if (body.readUInt8(0) !== FRAME_MAGIC) return null;
+  if (body.readUInt8(1) !== CRYPTO_VERSION) return null;
   const session = body.readUInt32BE(2);
   const code = body.readUInt8(6);
   const idLength = body.readUInt8(7);
-  if (body.length !== 8 + idLength) return null;
-  const machineId = idLength > 0 ? body.subarray(8, 8 + idLength).toString('utf8') : null;
-  return { session, code, machineId };
+  if (idLength > MAX_HANDSHAKE_MACHINE_ID) return null;
+  const headerBytes = 8 + idLength;
+  if (body.length !== headerBytes && body.length !== headerBytes + MAC_BYTES) return null;
+  let machineId = null;
+  if (idLength > 0) {
+    machineId = body.subarray(8, headerBytes).toString('utf8');
+    // Same rule, and the same reason, as `decodeHello`: no build produces a control byte in a machine
+    // id, and one that arrives would put a delimiter into a log line.
+    // eslint-disable-next-line no-control-regex -- rejecting control bytes is the point
+    if (/[\u0000-\u001f\u007f]/.test(machineId)) return null;
+  }
+  const mac = body.length === headerBytes + MAC_BYTES
+    ? Buffer.from(body.subarray(headerBytes, headerBytes + MAC_BYTES))
+    : null;
+  return { session, code, machineId, mac, headerBytes, bytes: Buffer.from(body) };
+}
+
+/**
+ * The transcript a refusal MAC is taken over: the label, then the refusal exactly as it goes on the
+ * wire *without* its MAC. Recomputed by the receiver from the bytes it holds, never sent separately.
+ *
+ * @param {Buffer} body The refusal body without the trailing MAC.
+ * @returns {Buffer} 32 bytes.
+ */
+export function refuseTranscript(body) {
+  return handshakeHash(REFUSE_MAC_LABEL, body);
+}
+
+/**
+ * A refusal with proof attached, for every responder that received a parseable `HELLO`.
+ *
+ * @param {number} session
+ * @param {number} code
+ * @param {string|null} machineId
+ * @param {Buffer} macKey `k_ref`, from {@link refusalMacKey}.
+ * @returns {Buffer}
+ */
+export function sealRefuse(session, code, machineId, macKey) {
+  const body = encodeRefuse(session, code, machineId);
+  return encodeRefuse(session, code, machineId, sealMac(macKey, refuseTranscript(body)));
+}
+
+/**
+ * The MAC key a refusal is sealed with: `k_ref = HKDF(ECDH(e_i, s_r), REFUSE_MAC_LABEL)`.
+ *
+ * Both ends derive it from material the *other* end published, and neither needs the other's static
+ * public key to be on file: the initiator passes its own ephemeral private key and the responder's
+ * static public key, the responder passes its own static private key and the initiator's ephemeral
+ * public key from the `HELLO`. An attacker who has neither private key cannot derive it, which is
+ * what makes a sealed refusal evidence rather than a claim.
+ *
+ * @param {object} input
+ * @param {import('node:crypto').KeyObject} input.privateKey `e_i`'s private half (initiator) or `s_r`
+ *   (responder).
+ * @param {Buffer} input.peerPublicRaw 32 raw bytes of `s_r` (initiator) or `e_i` (responder).
+ * @returns {Buffer} 32 bytes.
+ */
+export function refusalMacKey({ privateKey, peerPublicRaw }) {
+  if (!Buffer.isBuffer(peerPublicRaw) || peerPublicRaw.length !== KEY_BYTES) {
+    throw new TypeError(`refusalMacKey: the peer public key must be ${KEY_BYTES} raw bytes`);
+  }
+  return derive(diffieHellman({ privateKey, publicKey: publicKeyFromRaw(peerPublicRaw) }), REFUSE_MAC_LABEL);
+}
+
+/**
+ * Verify the optional MAC on a received refusal.
+ *
+ * @param {Buffer|null} macKey `k_ref`, or null when this end has nothing to check with.
+ * @param {Buffer} body The whole refusal body as received.
+ * @returns {boolean|null} `null` when the body carries no MAC (or is not a refusal at all), otherwise
+ *   whether it verifies. `false` is never "unknown" — it is a MAC that was present and wrong.
+ */
+export function verifyRefuseMac(macKey, body) {
+  const decoded = decodeRefuse(body);
+  if (decoded === null || decoded.mac === null) return null;
+  if (macKey === null) return false;
+  const expected = sealMac(macKey, refuseTranscript(body.subarray(0, decoded.headerBytes)));
+  return bytesEqual(expected, decoded.mac);
 }
 
 /* -------------------------------------------------------------------------- */
@@ -1341,7 +1522,9 @@ export function ackTranscript(helloBytes, responderEphemeralRaw) {
  * @param {string} options.peerMachineId The machine being dialled.
  * @param {string} options.peerPublicKey Its static public key, from the offer or from the relay.
  * @param {number} options.session The punch session.
- * @returns {{body: Buffer, ephemeral: string, session: number, peerMachineId: string, finish: Function}}
+ * @returns {{body: Buffer, ephemeral: string, session: number, peerMachineId: string,
+ *   refusalMacKey: Buffer, finish: Function}} `refusalMacKey` is `k_ref` of {@link refusalMacKey}: what
+ *   this end checks a `REFUSE` against, and the reason a refusal can be evidence rather than a claim.
  */
 export function startHandshake({ deviceKey, peerMachineId, peerPublicKey, session }) {
   const peerRaw = decodeKey(peerPublicKey);
@@ -1364,6 +1547,10 @@ export function startHandshake({ deviceKey, peerMachineId, peerPublicKey, sessio
     ephemeral: encodeKey(ephemeralPublic),
     session,
     peerMachineId,
+    // Derived once, here, from the ephemeral this handshake is about to send: `ECDH(e_i, s_r)`. The
+    // responder derives the same value from that very `e_i` and its own static key, which is what lets
+    // it answer a refusal with proof even when it holds no key for us at all.
+    refusalMacKey: refusalMacKey({ privateKey: ephemeral.privateKey, peerPublicRaw: peerRaw }),
     /**
      * Verify `HELLO_ACK` and hand back the transport session.
      *
@@ -1433,7 +1620,42 @@ export function startHandshake({ deviceKey, peerMachineId, peerPublicKey, sessio
 export function respondHandshake({ deviceKey, body, peerKeys, seen = null }) {
   const hello = decodeHello(body);
   if (hello === null) return { ok: false, reason: CRYPTO_REASON.MALFORMED, refuse: null };
+
+  /** This peer's static public key as filed under its claimed machine id, or null. */
+  const keyFor = (machineId) => {
+    if (machineId === null) return null;
+    return peerKeys instanceof PeerKeyStore
+      ? peerKeys.get(machineId)
+      : (peerKeys.get(machineId) ?? null);
+  };
+
+  /**
+   * `k_ref` for this exchange, from the initiator's `e_i` and our own static key.
+   *
+   * Present whenever the `HELLO` parsed at all, which is every refusal below except `MALFORMED` (which
+   * sends nothing). It is deliberately *not* `k0`: a responder with no key for the initiator — the
+   * sender of `NO_PEER_KEY` — cannot compute `k0`, and a responder with a stale key for it (the sender
+   * of `BAD_MAC`) would produce a `k0` the initiator cannot reproduce either. `k_ref` needs neither.
+   */
+  const initiatorEphemeralRaw = decodeKey(hello.ephemeral);
+  const refusalKey = initiatorEphemeralRaw === null
+    ? null
+    : refusalMacKey({ privateKey: deviceKey.privateKey, peerPublicRaw: initiatorEphemeralRaw });
+  /**
+   * A refusal body: sealed when we can prove it, bare when we cannot.
+   *
+   * @param {number} code
+   * @returns {Buffer}
+   */
+  const refuse = (code) => (refusalKey === null
+    ? encodeRefuse(hello.session, code, deviceKey.machineId)
+    : sealRefuse(hello.session, code, deviceKey.machineId, refusalKey));
+
   if (hello.version !== CRYPTO_VERSION) {
+    // The version is decided before any key is looked at — a peer speaking a different handshake
+    // version must be told *that*, not "unknown peer" — and this refusal stays bare on purpose: the
+    // peer receiving it speaks a body layout this build cannot vouch for, so a trailing field it does
+    // not know about would be worse than useless.
     return {
       ok: false,
       reason: CRYPTO_REASON.VERSION_MISMATCH,
@@ -1441,19 +1663,19 @@ export function respondHandshake({ deviceKey, body, peerKeys, seen = null }) {
     };
   }
 
-  const initiatorKey =
-    hello.machineId === null
-      ? null
-      : peerKeys instanceof PeerKeyStore
-        ? peerKeys.get(hello.machineId)
-        : (peerKeys.get(hello.machineId) ?? null);
+  const initiatorKey = keyFor(hello.machineId);
 
   if (initiatorKey === null) {
-    // Nothing this peer says can be verified, and we will not guess. The refusal is named and
-    // unauthenticated — it proves nothing, and it is the only honest answer available. It says
-    // `NO_PEER_KEY` rather than `UNKNOWN_PEER` because that is what the initiator needs to know: a
-    // handshake is impossible here, so it may use the plaintext channel it would have had before this
-    // work rather than waiting out a timeout.
+    // Nothing this peer says can be verified, and we will not guess. The refusal is named — and it is
+    // *sealed*, because `k_ref` is exactly the proof this case can carry: it says "this datagram came
+    // from the machine that holds the static key you dialled", which is precisely what a peer with no
+    // key on file for us can still prove. `p2p.mjs` turns that into the rule that a refusal which
+    // would choose a plaintext channel needs either this proof or the corroboration of the same
+    // endpoint having acknowledged the punch.
+    //
+    // It says `NO_PEER_KEY` rather than `UNKNOWN_PEER` because that is what the initiator needs to
+    // know: a handshake is impossible here, so it may use the plaintext channel it would have had
+    // before this work rather than waiting out a timeout.
     //
     // This branch has a second, ordinary caller: a handshake from *our own* machine id, which is what
     // a task the relay leased back to the dispatching machine produces. We hold no peer key for
@@ -1461,19 +1683,11 @@ export function respondHandshake({ deviceKey, body, peerKeys, seen = null }) {
     // self-dial has always used. That is the right answer rather than an oversight: a self-connection
     // has no path to protect and must not fail, or a machine would lose the task it dispatched to
     // itself.
-    return {
-      ok: false,
-      reason: CRYPTO_REASON.UNKNOWN_PEER,
-      refuse: encodeRefuse(hello.session, REFUSE.NO_PEER_KEY, deviceKey.machineId),
-    };
+    return { ok: false, reason: CRYPTO_REASON.UNKNOWN_PEER, refuse: refuse(REFUSE.NO_PEER_KEY) };
   }
   const initiatorRaw = decodeKey(initiatorKey);
   if (initiatorRaw === null) {
-    return {
-      ok: false,
-      reason: CRYPTO_REASON.UNKNOWN_PEER,
-      refuse: encodeRefuse(hello.session, REFUSE.UNKNOWN_PEER, deviceKey.machineId),
-    };
+    return { ok: false, reason: CRYPTO_REASON.UNKNOWN_PEER, refuse: refuse(REFUSE.UNKNOWN_PEER) };
   }
 
   const k0 = derive(deviceKey.sharedSecret(initiatorRaw), STATIC_KEY_LABEL);
@@ -1484,12 +1698,10 @@ export function respondHandshake({ deviceKey, body, peerKeys, seen = null }) {
   if (!bytesEqual(hello.mac, expectedMac)) {
     // The peer is known, and its mac is wrong: it does not hold the private key we have on file for
     // it. A distinct code from UNKNOWN_PEER because the responses differ —one means "refresh that
-    // machine's key", the other means "somebody is guessing at names".
-    return {
-      ok: false,
-      reason: CRYPTO_REASON.BAD_MAC,
-      refuse: encodeRefuse(hello.session, REFUSE.BAD_MAC, deviceKey.machineId),
-    };
+    // machine's key", the other means "somebody is guessing at names". Sealed with `k_ref` and not
+    // `k0`, because when our record of *its* key is the stale one, `k0` is a value neither end can
+    // agree on — and this is the refusal whose whole content is "our records disagree".
+    return { ok: false, reason: CRYPTO_REASON.BAD_MAC, refuse: refuse(REFUSE.BAD_MAC) };
   }
 
   const nonceKey = `${hello.machineId}#${hello.session}#${hello.ephemeral}`;

package/src/agent/p2p-node.mjs

@@ -509,6 +509,14 @@ export class P2PNode extends EventEmitter {
     this.deviceKey = deviceKey ?? null;
     /** @type {PeerKeyStore} Peer static keys, learned from offers and from the relay. */
     this.peerKeys = peerKeys instanceof PeerKeyStore ? peerKeys : new PeerKeyStore();
+    /**
+     * Does the relay keep the static key this machine announces? `null` until an announcement proves
+     * it either way. See the note in `performAnnounce` — a relay older than v0.6.0 drops the field
+     * silently, and that is otherwise indistinguishable from every peer having no key.
+     *
+     * @type {boolean|null}
+     */
+    this.relayServesKeys = null;
     /** @type {object|null} `CryptoSession` overrides; null means the documented thresholds. */
     this.cryptoTuning = cryptoTuning ?? null;
     /** @type {NonceCache} Replay tracking for inbound handshakes. Outlives one `accept()`. */
@@ -590,6 +598,12 @@ export class P2PNode extends EventEmitter {
     this.announcing = null;
     /** @type {NodeJS.Timeout|null} */
     this.refreshTimer = null;
+    /**
+     * Asked not to hold the process open (see `unref()`). Remembered rather than applied once:
+     * `close()` followed by `start()` binds a *second* socket, and a promise that covered only the
+     * first one would not be a promise.
+     */
+    this.unreferenced = false;
     /** @type {symbol|null} Identifies the current run; a stale loop/announce is ignored. */
     this.runToken = null;
     /** @type {Promise<void>|null} */
@@ -648,6 +662,12 @@ export class P2PNode extends EventEmitter {
         enabled: this.deviceKey !== null,
         public_key: this.deviceKey === null ? null : (this.deviceKey.publicKeyBase64 ?? null),
         peers_known: this.peerKeys.size,
+        /**
+         * `null` until this node's own announcement proves it either way; `false` means the relay
+         * dropped the key we sent, which is the fact that explains an otherwise mysterious
+         * `peers_known: 0` on a fleet whose machines all hold keys (v0.6.2).
+         */
+        relay_serves_keys: this.relayServesKeys,
         handshakes: this.cryptoCounts.handshakes,
         encrypted_channels: this.cryptoCounts.encrypted_channels,
         plaintext_channels: this.cryptoCounts.plaintext_channels,
@@ -690,6 +710,33 @@ export class P2PNode extends EventEmitter {
     if (this.listenerCount('error') > 0) this.emit('error', new Error(message));
   }
 
+  /**
+   * Take the node off the process's liveness budget.
+   *
+   * A running node holds three things that would otherwise keep a Node.js process alive on their
+   * own, and all three are handled here: the bound UDP socket (a referenced handle), the announce
+   * refresh timer, and the accept loop's own wait timeout — a node that is simply waiting for a
+   * punch has that timer pending essentially all of the time. An embedder that has no disposer to
+   * call — a bare context with no `ctx.effect`, or an older host — has no other way to say so, and
+   * the alternative is a process that can never exit.
+   *
+   * The flag is remembered rather than applied once (`unreferenced`), because `close()` followed by
+   * `start()` binds a *second* socket and arms a *second* accept wait; the socket is unref'd as it
+   * binds, and the accept loop reads the flag on every round. A call made *after* `start()` therefore
+   * takes effect on the next round, which is bounded by the accept timeout. `close()` still releases
+   * everything; this only changes whether those handles hold the loop open.
+   *
+   * Idempotent, and safe before `start()` (and on a `relay` node, which never binds at all).
+   *
+   * @returns {this}
+   */
+  unref() {
+    this.unreferenced = true;
+    this.socket?.unref?.();
+    this.refreshTimer?.unref?.();
+    return this;
+  }
+
   /**
    * Bring the node up: bind the socket, start the accept loop, and start announcing.
    *
@@ -771,6 +818,9 @@ export class P2PNode extends EventEmitter {
     });
 
     this.socket = socket;
+    // `unref()` is remembered across binds: a caller that asked not to hold the process open must
+    // not start holding it open again just because this is the second socket the node has owned.
+    if (this.unreferenced) socket.unref?.();
     this.local = local;
     this.started = true;
     this.runToken = Symbol('p2p-run');
@@ -915,6 +965,28 @@ export class P2PNode extends EventEmitter {
     const posted = response?.ok === true;
     if (!posted && postError === null) postError = describeAnnounceFailure(response);
 
+    /**
+     * Does the relay keep the static key we send it? (v0.6.2)
+     *
+     * This is knowable from our own announcement, and only from our own announcement: we POST
+     * `static_key`, and the relay echoes the entry it stored. A relay that predates v0.6.0 has never
+     * heard of the field, drops it silently, and echoes an entry without it — indistinguishable, from
+     * any peer's point of view, from a machine that has no key at all.
+     *
+     * That ambiguity is what turned a stale relay into hours of "the peer is an older build". The
+     * deployed relay in this fleet started 2026-10-10T18:01:40Z; v0.6.0 and v0.6.1 shipped on
+     * 2026-10-11. Every announcement carried a valid key, every stored entry lost it, no dispatcher
+     * could ever arm a handshake, and `PLAINTEXT_PEER` blamed the one component that was up to date.
+     *
+     * Recorded rather than reported here: one announce proves the relay's behaviour, and `dial()`
+     * turns it into a named reason only where it explains something. `null` means "not yet known" —
+     * a machine with no key of its own cannot ask the question at all, and must not conclude "no".
+     */
+    if (posted && this.deviceKey !== null) {
+      const echoed = response?.json?.static_key;
+      this.relayServesKeys = typeof echoed === 'string' && echoed !== '' ? true : false;
+    }
+
     // A POST failure is the headline when there is one: the announcement is not live at
     // all. Otherwise a discovery failure is what makes this announcement incomplete.
     const error = !posted ? postError : discoveryOk ? null : discoveryError;
@@ -1106,6 +1178,9 @@ export class P2PNode extends EventEmitter {
     const fromOffer = Array.isArray(options.candidates) && options.candidates.length > 0;
 
     let announced = [];
+    // v0.6.2: the peer's static key as published in the same record the candidates came from. Lifted
+    // out of the lookup block because `lookup` is scoped to it, and the key is needed further down.
+    let announcedStaticKey = null;
     if (fromOffer) {
       announced = options.candidates;
     } else {
@@ -1130,6 +1205,8 @@ export class P2PNode extends EventEmitter {
         return fail(`P2P_LOOKUP_FAILED: ${describeLookupFailure(lookup)}`);
       }
       announced = Array.isArray(lookup.json?.peer?.candidates) ? lookup.json.peer.candidates : [];
+      const key = lookup.json?.peer?.static_key;
+      if (typeof key === 'string' && key !== '') announcedStaticKey = key;
     }
 
     const remote = [];
@@ -1140,6 +1217,52 @@ export class P2PNode extends EventEmitter {
       remote.push(usable);
       if (remote.length >= this.tuning.maxCandidates) break;
     }
+
+    /**
+     * The peer's static key, learned from its own announcement when this machine does not hold one.
+     *
+     * v0.6.2. This is the other half of the plaintext-downgrade fix, and without it the reason code
+     * alone would have been a better-worded lie: the dispatcher that reported
+     * `P2P_CRYPTO_PLAINTEXT_PEER` against a same-version peer *could* have encrypted, it simply had an
+     * empty key store and never asked. The relay has carried the peer's `static_key` in this very
+     * record since v0.6.0 (`relay/peers.mjs`), the plugin already read it, and the agent's own `dial()`
+     * was fetching the same record for the candidate list and then throwing the key away.
+     *
+     * Adopting it here is what makes the local/remote distinction possible as well as useful: a peer
+     * that publishes no key is genuinely an older build and `PLAINTEXT_PEER` is honest; a peer that
+     * publishes one we had not learned is *our* gap, and after this it is not a gap at all.
+     */
+    let peerKey = this.peerKeys.get(machineId);
+    if (peerKey === null && announcedStaticKey !== null) {
+      this.peerKeys.set(machineId, announcedStaticKey, 'relay');
+      peerKey = announcedStaticKey;
+    }
+
+    /**
+     * Why this dial cannot be encrypted, when it cannot. Named here because this is where the reason
+     * is actually known: `punch()` sees only "no crypto request" and used to guess, blaming the peer
+     * for what is usually a local condition.
+     *
+     * `null` means a handshake will be armed. `PLAINTEXT_PEER` is reserved for the one case that is
+     * about the peer -- it publishes no key, so there is nothing to encrypt with. Everything else is
+     * `NO_KEY`: this machine has no device key of its own, holds no key for that peer, or is dialling
+     * itself (a machine keeps no key for itself, so its own `respondHandshake` would refuse it with
+     * `P2P_CRYPTO_UNKNOWN_PEER`).
+     */
+    const cryptoBlockedReason =
+      this.deviceKey === null
+        ? CRYPTO_REASON.NO_KEY
+        : machineId === this.machineId
+          ? CRYPTO_REASON.NO_KEY
+          : peerKey === null
+            ? this.relayServesKeys === false
+              // The peer announced, we hold a key of our own, and no key came back for it. If this
+              // node has already proved the relay drops keys, the relay is the cause and saying
+              // otherwise sends the operator to the wrong machine.
+              ? CRYPTO_REASON.RELAY_NO_KEYS
+              : CRYPTO_REASON.PLAINTEXT_PEER
+            : null;
+
     if (remote.length === 0) {
       // `peersAnnounced` still counts what was offered, not what survived validation: a caller
       // reading "the punch failed" needs to see that there *was* a list, and that every entry in it
@@ -1174,17 +1297,19 @@ export class P2PNode extends EventEmitter {
         // sends would be refused by its own `respondHandshake` (`P2P_CRYPTO_UNKNOWN_PEER`) and the
         // task it dispatched to itself would be lost. `machineId !== this.machineId` is what makes a
         // self-lease survive a security upgrade, which is the same rule as every other fallback here.
-        ...(this.deviceKey === null ||
-        machineId === this.machineId ||
-        this.peerKeys.get(machineId) === null
-          ? {}
-          : {
+        ...(cryptoBlockedReason === null && peerKey !== null
+          ? {
             crypto: {
               deviceKey: this.deviceKey,
-              peerKey: this.peerKeys.get(machineId),
+              peerKey,
               peerMachineId: machineId,
             },
-          }),
+          }
+          : {}),
+        // v0.6.2: the reason travels with the call instead of being guessed downstream. `punch()`
+        // cannot tell a local "we hold no key" from the peer being an older build, and it used to
+        // report the peer-blaming one for both.
+        cryptoBlockedReason,
         ...(this.cryptoTuning === null ? {} : { cryptoTuning: this.cryptoTuning }),
       });
     } catch (error) {
@@ -1438,6 +1563,10 @@ export class P2PNode extends EventEmitter {
           socket: this.socket,
           timeoutMs: this.tuning.acceptTimeoutMs,
           claimed: this.claimed,
+          // Read on every round, not once: `unref()` can be called after `start()`, and the wait
+          // this loop is about to arm is then the only handle that could still hold the process
+          // open. See `unref()`.
+          unrefWait: this.unreferenced,
           // v0.6.0: handshakes are answered only when this machine holds a key of its own. Without
           // one, `accept()` is byte-for-byte v0.5.x — every HELLO answered plainly — which is what
           // keeps a mixed fleet working rather than half-encrypted and confused.