ciphermesh 2.12.0 → 2.14.0

package/src/crypto/KeyManager.js

@@ -3,7 +3,18 @@ import sodium from 'sodium-native';
 import { createHash } from 'node:crypto';
 import { KEY_ROTATION_GRACE_MS } from '../shared/constants.js';
 import { generatePQKeyPair } from './PQHybrid.js';
+import { DeviceIdentity, identityFingerprint, newDeviceId } from './DeviceIdentity.js';
 
+// Guarded memory is released with sodium_free, never merely zeroed.
+//
+// sodium_malloc'd pages are mlock'd and the OS caps how much a process may lock
+// (RLIMIT_MEMLOCK — small on Linux, unlimited on macOS, which is why the ceiling
+// is invisible here and fatal in CI). Zeroing leaves the pages locked until the
+// garbage collector runs the buffer's finaliser; sodium_free zeroes *and*
+// releases, so it is strictly stronger than the memzero it replaces. Every
+// caller nulls its reference immediately after, so nothing can reach freed
+// memory. Same reasoning as SenderKey.js, and the same failure it was written
+// for: an allocation that fails lands as a SIGABRT in whatever allocated next.
 export class KeyManager {
   #publicKey;
   #secretKey;
@@ -12,6 +23,26 @@ export class KeyManager {
   #previousSecretKey;
   #graceTimer;
   #pqKeyPair; // ML-KEM-768 — the hybrid half (see crypto/PQHybrid.js)
+  // Multi-device, step 2 (docs/design/multi-device.md). Carried, persisted,
+  // backed up and advertised — and read by nobody. The box key above is still
+  // the identity as far as every fingerprint, SAS and ban is concerned; this
+  // pair exists so that the field is already on the wire when step 3 starts
+  // signing device lists with it, the way the Ed25519 sender key landed before
+  // the send path that needed it.
+  // Ed25519 — signs device lists, never encrypts. **Null on a secondary
+  // device**, which holds only the public half: the identity secret never
+  // leaves the device that provisions. See shared/deviceProvisioning.js.
+  #identity;
+  #identityPk; // the public half, whether or not we hold the secret
+  #grantedList; // a secondary cannot sign, so it publishes what it was given
+  #deviceId; // names *this* device across box-key rotations
+  #deviceCreatedAt; // when this device id was drawn
+  // Version of the device list this device publishes. Persisted, and only ever
+  // increased. A peer keeps the highest counter it has seen, so a list that
+  // came back with a smaller one is a replay and is ignored — which also means
+  // a counter that failed to grow after the descriptor changed would leave
+  // every peer holding a list that no longer describes this device.
+  #listCounter;
 
   constructor() {
     this.#publicKey = Buffer.alloc(sodium.crypto_box_PUBLICKEYBYTES);
@@ -22,10 +53,92 @@ export class KeyManager {
 
     sodium.crypto_box_keypair(this.#publicKey, this.#secretKey);
     this.#pqKeyPair = generatePQKeyPair();
+    this.#identity = new DeviceIdentity();
+    this.#identityPk = this.#identity.publicKeyB64;
+    this.#grantedList = null;
+    this.#deviceId = newDeviceId();
+    this.#deviceCreatedAt = Date.now();
+    this.#listCounter = 1;
 
     this.#fingerprint = KeyManager.computeFingerprint(this.#publicKey);
   }
 
+  /** The signing identity. Survives box-key rotation; that is the point. */
+  get identity() {
+    return this.#identity;
+  }
+
+  get identityPublicKeyB64() {
+    return this.#identityPk;
+  }
+
+  /** True when this device holds the identity secret and can sign for it. */
+  get isPrimaryDevice() {
+    return this.#identity !== null;
+  }
+
+  /** The list a secondary was granted, or null on a primary. */
+  get grantedList() {
+    return this.#grantedList;
+  }
+
+  /**
+   * Adopt an identity we do not hold the secret for.
+   *
+   * The caller has already checked that the list is signed by `identityPk` and
+   * names this device; this only records the outcome. The identity we generated
+   * for ourselves is destroyed rather than kept — two identities on one device
+   * is a state nothing else in the code expects, and keeping a secret nobody
+   * will ever use is the definition of a liability.
+   */
+  adoptIdentity(identityPk, grantedList) {
+    this.#identity?.destroy();
+    this.#identity = null;
+    this.#identityPk = identityPk;
+    this.#grantedList = grantedList;
+  }
+
+  /**
+   * The 128-bit identity fingerprint.
+   *
+   * Not what `/fingerprint` shows and not what a SAS compares — those stay on
+   * the box key until step 4 moves them deliberately, with a migration. Two
+   * fingerprints on screen before then would only teach people to compare the
+   * wrong one.
+   */
+  get identityFingerprint() {
+    return identityFingerprint(this.#identityPk);
+  }
+
+  get deviceId() {
+    return this.#deviceId;
+  }
+
+  get listCounter() {
+    return this.#listCounter;
+  }
+
+  /** The list changed for a reason other than a rotation — adding a device. */
+  bumpListCounter() {
+    this.#listCounter += 1;
+  }
+
+  /**
+   * This device, as a device list names it.
+   *
+   * The label is empty and stays empty until there is a second device to tell
+   * apart. A hostname would be the obvious filler and is exactly the kind of
+   * thing this project does not put on a wire.
+   */
+  deviceDescriptor() {
+    return {
+      deviceId: this.#deviceId,
+      boxPk: this.publicKeyB64,
+      label: '',
+      createdAt: this.#deviceCreatedAt,
+    };
+  }
+
   // The identity fingerprint stays X25519-only on purpose: it is what users
   // already verified out-of-band, and the KEM key adds no authentication.
   get pqPublicKey() {
@@ -65,9 +178,24 @@ export class KeyManager {
   }
 
   /**
-   * Generate a new keypair, keeping the old one for a grace period.
+   * Generate a new box keypair, keeping the old one for a grace period.
+   *
+   * The identity key and the device id are deliberately untouched. Rotating the
+   * box key is a routine hygiene step; rotating an identity is a claim that you
+   * are somebody new, and once device lists exist it would invalidate every one
+   * of them. A device that rotates is the same device.
    */
   rotate() {
+    // A secondary cannot rotate. Its box key is named in a list signed by an
+    // identity whose secret lives somewhere else, so a new key would be a key
+    // nothing vouches for — every peer would see an unproven device under a
+    // known name, which is the alarm this whole arc exists to stop firing
+    // wrongly. Rotating a secondary needs the primary to re-sign for it, and
+    // there is no channel for that yet.
+    if (!this.#identity) {
+      return;
+    }
+
     // Clear any existing grace timer
     if (this.#graceTimer) {
       clearTimeout(this.#graceTimer);
@@ -84,6 +212,10 @@ export class KeyManager {
     sodium.crypto_box_keypair(this.#publicKey, this.#secretKey);
 
     this.#fingerprint = KeyManager.computeFingerprint(this.#publicKey);
+    // The descriptor just changed, so any list already out there describes a
+    // key this device no longer uses. Without this the new list would carry the
+    // old counter and every peer would discard it as not newer.
+    this.#listCounter += 1;
 
     // Auto-destroy previous keys after grace period
     this.#graceTimer = setTimeout(() => {
@@ -94,7 +226,7 @@ export class KeyManager {
 
   destroyPrevious() {
     if (this.#previousSecretKey) {
-      sodium.sodium_memzero(this.#previousSecretKey);
+      sodium.sodium_free(this.#previousSecretKey);
     }
     this.#previousSecretKey = null;
     this.#previousPublicKey = null;
@@ -118,9 +250,11 @@ export class KeyManager {
     if (this.#graceTimer) {
       clearTimeout(this.#graceTimer);
     }
+    this.#identity?.destroy();
+    this.#identity = null;
     this.destroyPrevious();
     if (this.#secretKey) {
-      sodium.sodium_memzero(this.#secretKey);
+      sodium.sodium_free(this.#secretKey);
     }
     this.#secretKey = null;
     this.#publicKey = null;
@@ -133,12 +267,22 @@ export class KeyManager {
       secretKey: this.#secretKey.toString('base64'),
       pqPublicKey: this.#pqKeyPair.publicKey.toString('base64'),
       pqSecretKey: this.#pqKeyPair.secretKey.toString('base64'),
+      identity: this.#identity ? this.#identity.serialize() : null,
+      identityPk: this.#identityPk,
+      grantedList: this.#grantedList,
+      deviceId: this.#deviceId,
+      deviceCreatedAt: this.#deviceCreatedAt,
+      listCounter: this.#listCounter,
     };
   }
 
   static deserialize(data) {
     const km = new KeyManager(); // generates throwaway keys
-    sodium.sodium_memzero(km.#secretKey); // wipe throwaway
+    // sodium_free rather than memzero: the throwaway's pages are mlock'd, and
+    // zeroing leaves them locked until a finaliser happens to run. One page is
+    // harmless, but this is the pattern that aborted CI in 2.12.0 and it costs
+    // nothing to get right.
+    sodium.sodium_free(km.#secretKey);
 
     km.#publicKey = Buffer.from(data.publicKey, 'base64');
     const tempSec = Buffer.from(data.secretKey, 'base64');
@@ -156,6 +300,34 @@ export class KeyManager {
         secretKey: Buffer.from(data.pqSecretKey, 'base64'),
       };
     }
+    // Same shape for the identity: a session or a backup written before this
+    // existed simply keeps the fresh one generated above. Losing an identity
+    // that nothing reads yet costs nothing; refusing to restore the session
+    // would cost the user everything else in it.
+    const identity = DeviceIdentity.deserialize(data.identity);
+    if (identity) {
+      km.#identity.destroy();
+      km.#identity = identity;
+      km.#identityPk = identity.publicKeyB64;
+    } else if (typeof data.identityPk === 'string' && data.grantedList) {
+      // A secondary: an identity it does not hold the secret for, and the list
+      // it was granted. Restored together or not at all — one without the other
+      // is a device that claims an identity it cannot prove it belongs to.
+      km.#identity.destroy();
+      km.#identity = null;
+      km.#identityPk = data.identityPk;
+      km.#grantedList = data.grantedList;
+    }
+    if (typeof data.deviceId === 'string' && /^[0-9a-f]{32}$/.test(data.deviceId)) {
+      km.#deviceId = data.deviceId;
+      // Only meaningful alongside the id they belong to.
+      if (Number.isSafeInteger(data.deviceCreatedAt) && data.deviceCreatedAt >= 0) {
+        km.#deviceCreatedAt = data.deviceCreatedAt;
+      }
+      if (Number.isSafeInteger(data.listCounter) && data.listCounter >= 1) {
+        km.#listCounter = data.listCounter;
+      }
+    }
     return km;
   }
 }

package/src/crypto/TrustStore.js

@@ -9,6 +9,9 @@ const TRUST_FILE = 'trusted-peers.json';
 export const TrustResult = {
   NEW_PEER: 'new_peer',
   TRUSTED: 'trusted',
+  // A key that is not the one on the record, but that the identity bound to
+  // this record has signed as another of its devices. Not a mismatch.
+  KNOWN_DEVICE: 'known_device',
   MISMATCH: 'mismatch',
   VERIFIED_MISMATCH: 'verified_mismatch',
 };
@@ -75,6 +78,18 @@ export class TrustStore {
 
     // Compare the FULL public key (256 bits), not the 64-bit fingerprint.
     // Fall back to the fingerprint only for legacy records without publicKey.
+    // Once a synced device list exists, it is the authority on which keys are
+    // this person — including about the key the record was built on. A revoked
+    // primary that stayed TRUSTED here would make revocation decorative.
+    if (Array.isArray(record.devices)) {
+      if (record.devices.includes(publicKeyB64)) {
+        record.lastSeen = Date.now();
+        this.#save();
+        return record.publicKey === publicKeyB64 ? TrustResult.TRUSTED : TrustResult.KNOWN_DEVICE;
+      }
+      return record.verified ? TrustResult.VERIFIED_MISMATCH : TrustResult.MISMATCH;
+    }
+
     const matches = record.publicKey
       ? record.publicKey === publicKeyB64
       : record.fingerprint === KeyManager.computeFingerprint(Buffer.from(publicKeyB64, 'base64'));
@@ -85,6 +100,18 @@ export class TrustStore {
       return TrustResult.TRUSTED;
     }
 
+    // Another device of the same person is not a key that changed.
+    //
+    // Every key here was put there by a device list signed by the identity
+    // bound to this record — see syncDevices, which is the only writer. So this
+    // is not "a second key we have seen before", it is "a key the identity you
+    // verified says is also them".
+    if (record.devices?.includes(publicKeyB64)) {
+      record.lastSeen = Date.now();
+      this.#save();
+      return TrustResult.KNOWN_DEVICE;
+    }
+
     if (record.verified) {
       return TrustResult.VERIFIED_MISMATCH;
     }
@@ -173,6 +200,132 @@ export class TrustStore {
     return `${digits.slice(0, 4)} ${digits.slice(4, 8)} ${digits.slice(8)}`;
   }
 
+  /**
+   * The same construction over Ed25519 identity keys instead of box keys.
+   *
+   * A separate domain tag, not the same one with different inputs: two
+   * protocols that can produce the same digits from different material are two
+   * protocols one of them can be tricked into accepting. Same width, because
+   * the reason 40 bits replaced 20 has not changed.
+   *
+   * Only ever used when *both* sides will use it — see
+   * ChatController#identitySasReady. A pair where one side compares identity
+   * keys and the other compares box keys would show two different codes to two
+   * people who are doing everything right.
+   */
+  static computeIdentitySAS(myIdentityPk, peerIdentityPk) {
+    const mine = Buffer.isBuffer(myIdentityPk) ? myIdentityPk : Buffer.from(myIdentityPk, 'base64');
+    const theirs = Buffer.isBuffer(peerIdentityPk)
+      ? peerIdentityPk
+      : Buffer.from(peerIdentityPk, 'base64');
+
+    const [first, second] = Buffer.compare(mine, theirs) <= 0 ? [mine, theirs] : [theirs, mine];
+    const context = Buffer.from('CipherMesh-IdentitySAS-v1');
+    const hash = Buffer.alloc(32);
+    sodium.crypto_generichash(hash, Buffer.concat([first, second, context]));
+
+    let num = 0n;
+    for (let i = 0; i < 5; i++) {
+      num = (num << 8n) | BigInt(hash[i]);
+    }
+    const digits = num.toString().padStart(13, '0');
+    return `${digits.slice(0, 4)} ${digits.slice(4, 8)} ${digits.slice(8)}`;
+  }
+
+  /**
+   * Bind an identity key to a peer's record, keeping whatever verification the
+   * record already carries.
+   *
+   * This is the migration, and it is only ever called when the binding is
+   * provable: the identity signed a device list naming the box key this record
+   * was built on, and that list arrived over a channel only the holder of that
+   * box key could have written to. So the identity is vouched for by exactly
+   * the thing the user already verified out of band — the same reasoning
+   * `autoUpdatePeer` uses to carry verification across a key rotation.
+   *
+   * Nothing here can *create* verification. A record that was never verified is
+   * bound and stays unverified.
+   *
+   * @returns {'bound'|'unchanged'|'conflict'|'unknown'}
+   */
+  bindIdentity(nickname, identityPkB64) {
+    const record = this.#store.get(nickname.toLowerCase());
+    if (!record) {
+      return 'unknown';
+    }
+    if (record.identityPk === identityPkB64) {
+      return 'unchanged';
+    }
+    // A second identity claiming a record that already has one. Never silently
+    // overwritten: for a verified record this is the loud case, and it is the
+    // shape a takeover would have.
+    if (record.identityPk) {
+      return 'conflict';
+    }
+    record.identityPk = identityPkB64;
+    record.lastSeen = Date.now();
+    this.#save();
+    return 'bound';
+  }
+
+  /** The identity bound to a peer, or null. */
+  identityFor(nickname) {
+    return this.#store.get(nickname.toLowerCase())?.identityPk ?? null;
+  }
+
+  /**
+   * Set the device keys an identity has signed for to exactly this set.
+   *
+   * A replacement, not an accumulation, and that is the whole of revocation on
+   * the receiving side: a device that has been removed from the list stops
+   * being one of this person's keys here too. Accumulating would leave every
+   * revoked key trusted forever, which is worse than not having revocation at
+   * all, because it would look like it worked.
+   *
+   * The only writer of `record.devices`, and it refuses unless the identity
+   * asking is the one already bound to the record. Without that check any
+   * signed list could write keys onto anybody's record, which is the attack
+   * this prevents rather than enables.
+   *
+   * The record's primary `publicKey` is left alone even when the list no longer
+   * names it: it is the historical fact of what the user compared digits over.
+   * `checkPeer` stops honouring it, which is the part that matters.
+   *
+   * @returns {{added: string[], removed: string[]}}
+   */
+  syncDevices(nickname, identityPkB64, boxKeys) {
+    const record = this.#store.get(nickname.toLowerCase());
+    if (!record || !record.identityPk || record.identityPk !== identityPkB64) {
+      return { added: [], removed: [] };
+    }
+    const before = new Set(record.devices ?? []);
+    const after = new Set(boxKeys);
+
+    const added = [...after].filter((key) => !before.has(key));
+    const removed = [...before].filter((key) => !after.has(key));
+
+    if (added.length > 0 || removed.length > 0 || !record.devices) {
+      record.devices = [...after];
+      record.lastSeen = Date.now();
+      this.#save();
+    }
+    return { added, removed };
+  }
+
+  /**
+   * Every box key this peer is currently known by.
+   *
+   * Once a list has been synced it is the answer on its own; before that, the
+   * verified key is all there is.
+   */
+  devicesFor(nickname) {
+    const record = this.#store.get(nickname.toLowerCase());
+    if (!record) {
+      return [];
+    }
+    return record.devices ? [...record.devices] : [record.publicKey].filter(Boolean);
+  }
+
   markVerified(nickname) {
     const key = nickname.toLowerCase();
     const record = this.#store.get(key);

package/src/p2p/P2PChatController.js

@@ -1,11 +1,11 @@
 import sodium from 'sodium-native';
-import notifier from 'node-notifier';
 import qrcode from 'qrcode-terminal';
 import { writeFileSync, mkdirSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
 import { tmpdir } from 'node:os';
 import { exportBackup } from '../crypto/IdentityBackup.js';
 import { keyArt } from '../shared/keyArt.js';
+import { DesktopNotifier } from '../shared/desktopNotify.js';
 import {
   KEY_ROTATION_INTERVAL_MS,
   EMOJI_MAP,
@@ -47,6 +47,25 @@ import { COMMANDS } from '../client/UI.js';
 const TYPING_SEND_INTERVAL = 2000;
 const TYPING_EXPIRE_TIMEOUT = 3000;
 
+// Commands that exist only on the relay side, and why — so the mesh can say so
+// instead of guessing at a typo.
+//
+// `/device` is the interesting one. Multi-device is not merely unimplemented
+// here: a mesh peer is keyed by *nickname* (`#peers` above is
+// `Map<peerNickname, …>`) and has no session id, so two devices of one person
+// collide on the very thing the peer map is indexed by. Supporting them means
+// re-keying the mesh's whole model of who a peer is, which is a different
+// design from the relay's and deliberately out of scope — see
+// docs/design/multi-device.md.
+const RELAY_ONLY = {
+  '/device':
+    'In the mesh a peer is known by nickname, which is exactly what two of ' +
+    'your devices would share, so it is a different design and not built yet.',
+  '/create': 'Rooms with an owner exist only where there is a relay to hold one.',
+  '/invite': 'There is no address to invite anyone to without a relay.',
+  '/nick': 'Your name here is the one you started with; there is no registry to change it in.',
+};
+
 export class P2PChatController {
   #nickname;
   #connManager;
@@ -93,6 +112,7 @@ export class P2PChatController {
   #roomTopics = new Map(); // room → { text, by, at } (E2EE among peers)
   #historyStore; // encrypted local history (opt-in, needs a passphrase)
   #receiptsEnabled = true; // /receipts — send read confirmations
+  #desktopNotifier; // OS notifications, isolated + rate-limited
   #sentMessageLines = new Map(); // messageId → { lineIndex, baseLine, room }
   #messageReaders = new Map(); // messageId → Set<nickname>
   #pendingReceipts = new Map(); // messageId → Set<nickname> acked before we tracked it
@@ -145,6 +165,9 @@ export class P2PChatController {
       this.#trustStore.importData(restoredState.trust);
     }
     this.#auditLog = new AuditLog();
+    this.#desktopNotifier = new DesktopNotifier({
+      onUnavailable: (reason) => this.#onNotifierUnavailable(reason),
+    });
     this.#historyStore = historyStore;
     this.#ephemeralMode = false;
     this.#ephemeralDurationMs = 0;
@@ -734,7 +757,7 @@ export class P2PChatController {
     }
 
     if (notify && (this.#ui.notifyEnabled || mentioned)) {
-      notifier.notify({
+      this.#desktopNotifier.notify({
         title: mentioned
           ? `🔔 ${fromNickname} mentioned you`
           : data.isDM
@@ -746,6 +769,17 @@ export class P2PChatController {
     }
   }
 
+  // The OS refused a desktop notification (Windows with notifications turned
+  // off for the app is the common case). Say it once, then stay quiet — the
+  // notifier has already stopped trying, so the chat never sees it again.
+  #onNotifierUnavailable(reason) {
+    this.#ui.setNotifyEnabled(false);
+    this.#ui.addInfoMessage(
+      `Desktop notifications unavailable — ${reason}. Muted for this session; ` +
+        'sound alerts still work. Use /notify on to retry.',
+    );
+  }
+
   // ── TOFU: Trust On First Use ───────────────────────────────────
   #checkTrust(nickname, publicKey) {
     const result = this.#trustStore.checkPeer(nickname, publicKey);
@@ -1250,7 +1284,6 @@ export class P2PChatController {
         this.#ui.addQuoteLine(
           this.#lastReceivedNickname,
           (this.#lastReceivedText || '').slice(0, 80),
-          true,
         );
         this.#sendMessageToAll(replyText);
         break;
@@ -1532,14 +1565,17 @@ export class P2PChatController {
         const notifyArg = parts[1]?.toLowerCase();
         if (notifyArg === 'off') {
           this.#ui.setNotifyEnabled(false);
+          this.#desktopNotifier.disable();
           this.#ui.addInfoMessage('Desktop notifications disabled');
         } else if (notifyArg === 'on') {
           this.#ui.setNotifyEnabled(true);
+          this.#desktopNotifier.reset(); // give a previously refusing OS another go
           this.#ui.addInfoMessage('Desktop notifications enabled');
         } else {
           const status = this.#ui.notifyEnabled ? 'enabled' : 'disabled';
+          const blocked = this.#desktopNotifier.available ? '' : ' (blocked by the OS)';
           this.#ui.addInfoMessage(
-            `Desktop notifications: ${status}. Use /notify on or /notify off`,
+            `Desktop notifications: ${status}${blocked}. Use /notify on or /notify off`,
           );
         }
         break;
@@ -1996,6 +2032,7 @@ export class P2PChatController {
 
       case '/room':
         this.#ui.addInfoMessage(`Current room: #${this.#currentRoom}`);
+        this.#ui.addInfoMessage(`Sending: ${this.#describeSendPath()}`);
         break;
 
       case '/tips': {
@@ -2108,6 +2145,14 @@ export class P2PChatController {
             break;
           }
         }
+        // A relay-only command is not a typo, and guessing at one is worse than
+        // saying nothing: `/device` currently suggests `/voice`, which sends
+        // somebody looking in the wrong place entirely.
+        const relayOnly = RELAY_ONLY[cmd];
+        if (relayOnly) {
+          this.#ui.addErrorMessage(`${cmd} needs a relay. ${relayOnly}`);
+          return;
+        }
         const suggestion = suggestCommand(cmd, COMMANDS);
         const hint = suggestion ? ` Did you mean ${suggestion}?` : ' Use /help';
         this.#ui.addErrorMessage(`Unknown command: ${cmd}.${hint}`);
@@ -2375,6 +2420,51 @@ export class P2PChatController {
     this.#broadcastPayload(payload, false, toPeer, room);
   }
 
+  // Which path the next line you type will take, and what is holding it there.
+  //
+  // The mesh half of #481. The saving here is not frames — there is no relay to
+  // fan anything out, so a mesh sends one frame per peer either way — it is
+  // encryptions: one for the room, or one per peer. That is the cost the room
+  // silently pays when something has pushed it back onto the pairwise path, and
+  // until now nothing said so.
+  //
+  // The order matches the decision in #sendMessage, which is the only place
+  // that chooses. Two of the reasons are relay-side concerns that do not exist
+  // here (no hub to be older, no capability negotiation); one is a reason the
+  // relay does not have — constant cover paces messages through pairwise slots
+  // on purpose, because the timing guarantee is what it is for.
+  groupSendStatus() {
+    const inRoom = [...this.#peers.keys()].filter(
+      (nick) => (this.#peerRooms.get(nick) || 'general') === this.#currentRoom,
+    );
+    if (this.#deniableMode) {
+      return { group: false, reason: 'deniable', peers: inRoom.length };
+    }
+    if (this.#coverMode === 'constant') {
+      return { group: false, reason: 'cover', peers: inRoom.length };
+    }
+    if (inRoom.length === 0) {
+      return { group: false, reason: 'alone', peers: 0 };
+    }
+    return { group: true, reason: null, peers: inRoom.length };
+  }
+
+  #describeSendPath() {
+    const status = this.groupSendStatus();
+    if (status.group) {
+      return `one encryption for the room, sent to ${status.peers}`;
+    }
+    const cost = `${status.peers} encryption${status.peers === 1 ? '' : 's'} per message`;
+    switch (status.reason) {
+      case 'deniable':
+        return `${cost} — deniable mode is on, and deniability is pairwise`;
+      case 'cover':
+        return `${cost} — constant cover paces messages through pairwise slots`;
+      default:
+        return 'nothing yet — no one else is in this room';
+    }
+  }
+
   // Encrypt a room message ONCE and send the same ciphertext to every online
   // room peer — real group cryptography (O(1) encryption instead of O(N)).
   #sendRoomGroup(room, payload) {

package/src/protocol/messages.js

@@ -50,7 +50,22 @@ function base(type) {
 // post-quantum handshake. Absent = classical-only peer (pre-2.3 client).
 // caps (optional): what this client can do beyond the baseline protocol. Omitted
 // when empty so the wire is byte-identical to a pre-capability client.
-export function createJoin(nickname, publicKeyB64, pqPublicKeyB64 = null, caps = null) {
+// identityKey: the Ed25519 key a device list will one day be signed with
+// (docs/design/multi-device.md, step 2). Advertised now so the field is already
+// in the field when something reads it, exactly as the capability list was.
+//
+// It is **unauthenticated here** and must stay that way in every reader's mind
+// until step 3: the relay forwards it verbatim, so it can substitute one. What
+// makes an identity key trustworthy is a signed device list checked against it,
+// not its presence in a JOIN.
+export function createJoin(
+  nickname,
+  publicKeyB64,
+  pqPublicKeyB64 = null,
+  caps = null,
+  identityKeyB64 = null,
+  deviceList = null,
+) {
   const msg = { ...base(MSG.JOIN), nickname, publicKey: publicKeyB64 };
   if (pqPublicKeyB64) {
     msg.pqPublicKey = pqPublicKeyB64;
@@ -58,6 +73,15 @@ export function createJoin(nickname, publicKeyB64, pqPublicKeyB64 = null, caps =
   if (Array.isArray(caps) && caps.length > 0) {
     msg.caps = [...caps];
   }
+  if (identityKeyB64) {
+    msg.identityKey = identityKeyB64;
+  }
+  // Only needed when the nickname is already held by another of your devices.
+  // Sent always when there is one, because a client cannot know in advance
+  // whether its other device is already online.
+  if (deviceList) {
+    msg.deviceList = deviceList;
+  }
   return msg;
 }