@nopeek/chat 0.2.2 → 0.2.4

package/dist/index.js

@@ -33,6 +33,9 @@ const defaultStore = () => {
  * trickle so the visible text eases in smoothly instead of arriving in big jumps.
  */
 const STREAM_THROTTLE_MS = 120;
+/** SDK version, exported so apps can run once-per-upgrade maintenance (e.g. a
+ *  forced backup re-upload) without depending on package.json at runtime. */
+export const SDK_VERSION = "0.2.4";
 class Emitter {
     listeners = new Map();
     on(event, fn) {
@@ -60,7 +63,20 @@ export class NoPeek extends Emitter {
     ws = null;
     reqCounter = 0;
     pending = new Map();
-    channelKeys = new Map(); // channelId -> AES key
+    channelKeys = new Map(); // channelId -> AES key (the SEND key)
+    /** channelId -> (rawKeyB64 -> key): decrypt-only HISTORY keys. When a channel
+     *  key is superseded (newer welcome, divergence heal, backup merge) the old
+     *  key moves here instead of being dropped, so every message ever sent stays
+     *  decryptable on every device. Persisted and carried in encrypted backups. */
+    channelKeyRings = new Map();
+    /** deviceId -> keypair for PREVIOUS device identities of this user, recovered
+     *  from encrypted backups. A fresh login adopts ONE identity (the newest
+     *  backup's), but the account may have older lineages — e.g. a web login that
+     *  once registered its own device instead of adopting. Welcomes addressed to
+     *  those old deviceIds are still unwrappable with these keys, so channel keys
+     *  that only ever reached a legacy device remain recoverable. Persisted, and
+     *  carried inside backup envelopes (`legacyDevices`). */
+    legacyIdentities = new Map();
     mlsGroupToChannel = new Map();
     /** Latest known presence per user, updated on every presence frame (incl. the
      *  connect-time snapshot that may arrive before app listeners attach). */
@@ -189,8 +205,26 @@ export class NoPeek extends Emitter {
                     this.channelKeys.set(chId, await importChannelKey(raw));
                 }
             }
+            const savedRings = await this.store.get(`nopeek:${this.userId}:channelKeyRings`);
+            if (savedRings) {
+                for (const [chId, raws] of Object.entries(JSON.parse(savedRings))) {
+                    const ring = new Map();
+                    for (const raw of raws) {
+                        try {
+                            ring.set(raw, await importChannelKey(raw));
+                        }
+                        catch {
+                            /* skip a corrupt entry */
+                        }
+                    }
+                    if (ring.size)
+                        this.channelKeyRings.set(chId, ring);
+                }
+            }
+            await this.loadLegacyIdentities();
             return;
         }
+        await this.loadLegacyIdentities();
         this.keys = await generateDeviceKeys();
         // Deferred: the caller decides whether to restore() the real identity from a
         // backup or registerDevice() a genuinely new one. Registering here would
@@ -239,11 +273,89 @@ export class NoPeek extends Emitter {
     async persistDevice() {
         await this.store.set(`nopeek:${this.userId}:device`, JSON.stringify({ deviceId: this.deviceId, keys: this.keys }));
     }
+    // ------------------------------------------------- legacy identities ----
+    async loadLegacyIdentities() {
+        try {
+            const saved = await this.store.get(`nopeek:${this.userId}:legacyDevices`);
+            if (!saved)
+                return;
+            for (const [devId, keys] of Object.entries(JSON.parse(saved))) {
+                if (devId !== this.deviceId)
+                    this.legacyIdentities.set(devId, keys);
+            }
+        }
+        catch {
+            /* corrupt entry — legacy identities are a recovery aid, never fatal */
+        }
+    }
+    async persistLegacyIdentities() {
+        const out = {};
+        for (const [devId, keys] of this.legacyIdentities)
+            out[devId] = keys;
+        await this.store.set(`nopeek:${this.userId}:legacyDevices`, JSON.stringify(out));
+    }
+    /** Remember a previous device identity of this user (from a backup envelope)
+     *  so welcomes addressed to it can still be unwrapped. Returns whether new. */
+    async registerLegacyIdentity(device) {
+        if (!device?.deviceId || !device.keys?.privateKeyJwk)
+            return false;
+        if (device.deviceId === this.deviceId || this.legacyIdentities.has(device.deviceId))
+            return false;
+        this.legacyIdentities.set(device.deviceId, device.keys);
+        await this.persistLegacyIdentities();
+        return true;
+    }
+    /** Every deviceId this client can unwrap welcomes for: the live identity plus
+     *  any legacy identities recovered from backups. */
+    welcomeIds() {
+        const ids = new Set();
+        if (this.deviceId)
+            ids.add(this.deviceId);
+        for (const id of this.legacyIdentities.keys())
+            ids.add(id);
+        return ids;
+    }
+    /** Find the wrap in a welcome addressed to us (live identity first, then
+     *  legacy) and the private key that opens it. */
+    findMyWrap(wrapped) {
+        const own = wrapped.find((w) => w.deviceId === this.deviceId);
+        if (own && this.keys)
+            return { wrap: own, privateKeyJwk: this.keys.privateKeyJwk };
+        for (const [devId, keys] of this.legacyIdentities) {
+            const w = wrapped.find((x) => x.deviceId === devId);
+            if (w)
+                return { wrap: w, privateKeyJwk: keys.privateKeyJwk };
+        }
+        return null;
+    }
     async persistChannelKeys() {
         const out = {};
         for (const [chId, key] of this.channelKeys)
             out[chId] = await exportChannelKey(key);
         await this.store.set(`nopeek:${this.userId}:channelKeys`, JSON.stringify(out));
+        const rings = {};
+        for (const [chId, ring] of this.channelKeyRings)
+            if (ring.size)
+                rings[chId] = [...ring.keys()];
+        await this.store.set(`nopeek:${this.userId}:channelKeyRings`, JSON.stringify(rings));
+    }
+    /** Add a decrypt-only history key to a channel's ring (deduped by raw bytes;
+     *  the current send key is never ringed). Returns whether the ring grew.
+     *  Callers persist — this only mutates in-memory state. */
+    async ringAdd(channelId, key, rawB64) {
+        const raw = rawB64 ?? (await exportChannelKey(key));
+        const primary = this.channelKeys.get(channelId);
+        if (primary && (await exportChannelKey(primary)) === raw)
+            return false;
+        let ring = this.channelKeyRings.get(channelId);
+        if (!ring) {
+            ring = new Map();
+            this.channelKeyRings.set(channelId, ring);
+        }
+        if (ring.has(raw))
+            return false;
+        ring.set(raw, key);
+        return true;
     }
     async ensureKeyPackages() {
         const { available } = await this.api("GET", `/v1/apps/${this.appId}/users/${this.userId}/devices/${this.deviceId}/key-packages`);
@@ -479,12 +591,25 @@ export class NoPeek extends Emitter {
     async handleWelcome(hs) {
         try {
             const welcome = JSON.parse(new TextDecoder().decode(b64.dec(hs.payload)));
-            const mine = welcome.wrapped.find((w) => w.deviceId === this.deviceId);
+            const mine = this.findMyWrap(welcome.wrapped ?? []);
             if (!mine)
                 return;
-            const key = await unwrapChannelKey(mine, this.keys.privateKeyJwk);
-            this.channelKeys.set(welcome.channelId, key);
+            const key = await unwrapChannelKey(mine.wrap, mine.privateKeyJwk);
+            const raw = await exportChannelKey(key);
             this.mlsGroupToChannel.set(hs.mlsGroupId, welcome.channelId);
+            const prev = this.channelKeys.get(welcome.channelId);
+            const prevRaw = prev ? await exportChannelKey(prev) : null;
+            if (prevRaw === raw)
+                return; // already the key we hold
+            // A newer welcome SUPERSEDES the held key for sending — that's how every
+            // member device converges after a rotation or a divergence heal. The
+            // displaced key is NEVER dropped: it moves to the history ring (AFTER the
+            // swap, so the ring's dedupe-against-primary guard can't reject it) and
+            // all messages sent under it keep decrypting.
+            this.channelKeys.set(welcome.channelId, key);
+            this.channelKeyRings.get(welcome.channelId)?.delete(raw); // re-promoted: no longer history
+            if (prev && prevRaw)
+                await this.ringAdd(welcome.channelId, prev, prevRaw);
             await this.persistChannelKeys();
             this.emit("channelKeyReceived", { channelId: welcome.channelId });
         }
@@ -492,66 +617,183 @@ export class NoPeek extends Emitter {
             /* not a dev-suite welcome or not for us */
         }
     }
-    /** Fetch any welcomes we missed while offline. */
+    /** Fetch any welcomes we missed while offline. Folds EVERY welcome addressed
+     *  to this device, oldest → newest: the newest becomes the send key and the
+     *  earlier ones land in the history ring, so a device that missed a rotation
+     *  still reads the whole backlog. */
     async syncChannelKey(channelId, mlsGroupId) {
         if (this.channelKeys.has(channelId))
             return true;
         const { handshakes } = await this.api("GET", `/v1/apps/${this.appId}/mls/groups/${mlsGroupId}/handshakes?sinceEpoch=0`);
-        for (const hs of handshakes.reverse()) {
-            if (hs.kind === "welcome" && hs.recipientDeviceIds?.includes(this.deviceId)) {
+        const mine = this.welcomeIds();
+        for (const hs of handshakes) {
+            if (hs.kind === "welcome" && hs.recipientDeviceIds?.some((id) => mine.has(id))) {
                 await this.handleWelcome({ mlsGroupId, payload: hs.payload });
-                if (this.channelKeys.has(channelId))
-                    return true;
             }
         }
-        return false;
+        return this.channelKeys.has(channelId);
     }
-    /** Channels already checked for a self-addressed welcome this session. */
-    selfWelcomeChecked = new Set();
+    /** Channels already reconciled against the group's welcome history this session. */
+    keyReconChecked = new Set();
     /**
-     * Self-heal for channels created before establishKeys wrapped the welcome to
-     * the creator's OWN device: if this device HOLDS the channel key but no
-     * welcome in the group addresses this deviceId, post one (wrapped to
-     * ourselves). A future device that restores this identity from the encrypted
-     * backup — or an already-restored device sharing this deviceId — can then
-     * pull the key via syncChannelKey even when the backup's channel-key map is
-     * stale. Runs at most once per channel per device (persisted mark);
-     * best-effort and safe to fire-and-forget.
+     * Group-key reconciliation — runs once per channel per device per SDK
+     * version (persisted mark) BEFORE the first send, so a device can never
+     * encrypt into the void with a key the rest of the group doesn't hold.
+     *
+     * v2 (0.2.4). v1 reconciled a device only against welcomes addressed to
+     * ITSELF: a device holding an orphan key (minted by a stale pre-0.2.3
+     * bundle) saw no addressed welcome, posted a SELF-welcome legitimizing the
+     * orphan, and marked itself done — while the group's real key lived in a
+     * welcome addressed to a different device lineage. Two lineages with
+     * disjoint welcome sets never converged. v2:
+     *  - unwraps every welcome addressed to this device OR a legacy identity
+     *    restored from a backup, adopting the newest as the send key (displaced
+     *    keys go to the history ring, nothing is lost);
+     *  - computes COVERAGE: which member devices provably received a welcome
+     *    carrying our current send key. If any device observed in the group's
+     *    handshake history lacks it — or nothing addresses us at all — publish
+     *    the send key AND the history ring to every member device, so all
+     *    lineages (bots included) converge on one send key and can decrypt the
+     *    full backlog;
+     *  - v1 marks are deliberately ignored: every device re-runs one pass after
+     *    upgrading, because v1 could have marked a diverged channel as done.
+     * Best-effort; retried on failure.
      */
-    async ensureSelfWelcome(channelId, mlsGroupId) {
+    async reconcileChannelKey(channelId, mlsGroupId) {
         if (!mlsGroupId || this.deriveChannelKey || !this.deviceId)
             return; // preshared mode has no welcomes
-        const key = this.channelKeys.get(channelId);
-        if (!key)
+        const local = this.channelKeys.get(channelId);
+        if (!local)
             return;
-        if (this.selfWelcomeChecked.has(channelId))
+        if (this.keyReconChecked.has(channelId))
             return;
-        this.selfWelcomeChecked.add(channelId);
-        const mark = `nopeek:${this.userId}:selfWelcomed:${channelId}`;
+        this.keyReconChecked.add(channelId);
+        const mark = `nopeek:${this.userId}:keyRecon2:${channelId}`;
         try {
             if (await this.store.get(mark))
                 return;
             const { handshakes } = await this.api("GET", `/v1/apps/${this.appId}/mls/groups/${mlsGroupId}/handshakes?sinceEpoch=0`);
-            const covered = handshakes.some((h) => h.kind === "welcome" && h.recipientDeviceIds?.includes(this.deviceId));
-            if (!covered) {
-                const wrapped = await wrapChannelKey(key, [{ deviceId: this.deviceId, publicKeyJwk: this.keys.publicKeyJwk }]);
-                const welcome = { suite: "npdev-1", channelId, wrapped };
-                // Only `commit` handshakes are epoch-guarded server-side; welcomes
-                // append at the steady-state epoch (same as the member-add flow).
-                await this.api("POST", `/v1/apps/${this.appId}/mls/groups/${mlsGroupId}/handshakes`, {
-                    epoch: 1,
-                    kind: "welcome",
-                    senderDeviceId: this.deviceId,
-                    recipientDeviceIds: [this.deviceId],
-                    payload: b64.enc(new TextEncoder().encode(JSON.stringify(welcome))),
-                });
+            const mine = this.welcomeIds();
+            // Every deviceId that has EVER appeared in this group's handshakes — the
+            // observable universe of member devices (senders and welcome recipients).
+            const observed = new Set();
+            for (const h of handshakes) {
+                if (h.senderDeviceId)
+                    observed.add(h.senderDeviceId);
+                for (const r of h.recipientDeviceIds ?? [])
+                    observed.add(r);
+            }
+            // Unwrap every welcome addressed to us (live or legacy identity), oldest
+            // → newest: adopt each in turn (newest wins as send key, displaced keys
+            // ring), and record which recipients each carried key reached.
+            const coverage = new Map(); // rawKeyB64 -> recipient deviceIds
+            let addressedCount = 0;
+            for (const hs of handshakes) {
+                if (hs.kind !== "welcome")
+                    continue;
+                try {
+                    const welcome = JSON.parse(new TextDecoder().decode(b64.dec(hs.payload)));
+                    if (welcome.channelId !== channelId)
+                        continue;
+                    const my = this.findMyWrap(welcome.wrapped ?? []);
+                    if (!my)
+                        continue;
+                    addressedCount++;
+                    const key = await unwrapChannelKey(my.wrap, my.privateKeyJwk);
+                    const raw = await exportChannelKey(key);
+                    let cov = coverage.get(raw);
+                    if (!cov)
+                        coverage.set(raw, (cov = new Set()));
+                    for (const r of hs.recipientDeviceIds ?? welcome.wrapped.map((w) => w.deviceId))
+                        cov.add(r);
+                    // adopt: newest processed welcome becomes the send key
+                    const prev = this.channelKeys.get(channelId);
+                    const prevRaw = prev ? await exportChannelKey(prev) : null;
+                    if (prevRaw !== raw) {
+                        this.channelKeys.set(channelId, key);
+                        this.channelKeyRings.get(channelId)?.delete(raw); // re-promoted: no longer history
+                        if (prev && prevRaw)
+                            await this.ringAdd(channelId, prev, prevRaw);
+                    }
+                }
+                catch {
+                    /* not a dev-suite welcome / stale wrap — skip */
+                }
+            }
+            const localRaw = await exportChannelKey(local);
+            const current = this.channelKeys.get(channelId) ?? local;
+            const currentRaw = await exportChannelKey(current);
+            if (currentRaw !== localRaw) {
+                await this.persistChannelKeys();
+                this.emit("channelKeyReceived", { channelId });
+            }
+            // Coverage gap: some observed member device (not one of our own
+            // identities) provably lacks our send key, or a ring key of ours never
+            // appeared in ANY welcome (it would die with this device's local store),
+            // or nothing addresses us at all. Publish send key + ring to everyone.
+            const ringRaws = [...(this.channelKeyRings.get(channelId)?.keys() ?? [])];
+            const uncoveredKey = [currentRaw, ...ringRaws].some((raw) => {
+                const cov = coverage.get(raw) ?? new Set();
+                return [...observed].some((d) => !cov.has(d) && !mine.has(d)) || cov.size === 0;
+            });
+            if (addressedCount === 0 || uncoveredKey) {
+                await this.publishKeysToMembers(channelId, mlsGroupId);
             }
             await this.store.set(mark, "1");
         }
         catch {
-            this.selfWelcomeChecked.delete(channelId); // retry on a later ensureKey
+            this.keyReconChecked.delete(channelId); // retry on a later ensureKey
         }
     }
+    /** Back-compat alias: the 0.2.2 self-welcome heal is now part of reconcileChannelKey. */
+    async ensureSelfWelcome(channelId, mlsGroupId) {
+        return this.reconcileChannelKey(channelId, mlsGroupId);
+    }
+    /** Append a welcome carrying `wrapped` at the steady-state epoch. Only
+     *  `commit` handshakes are epoch-guarded server-side; welcomes append freely
+     *  (same as the member-add flow). */
+    async postWelcome(mlsGroupId, channelId, wrapped) {
+        const welcome = { suite: "npdev-1", channelId, wrapped };
+        await this.api("POST", `/v1/apps/${this.appId}/mls/groups/${mlsGroupId}/handshakes`, {
+            epoch: 1,
+            kind: "welcome",
+            senderDeviceId: this.deviceId,
+            recipientDeviceIds: wrapped.map((w) => w.deviceId),
+            payload: b64.enc(new TextEncoder().encode(JSON.stringify(welcome))),
+        });
+    }
+    /** Wrap this channel's HISTORY RING keys and then its SEND key to every
+     *  member device (claiming key packages) plus this device, posting each as a
+     *  welcome — the convergence carrier. The send key goes LAST so recipients
+     *  (which adopt the newest welcome) all land on the same send key with the
+     *  ring keys as decrypt-only history. Members whose packages can't be
+     *  claimed heal later via sync/backup. */
+    async publishKeysToMembers(channelId, mlsGroupId) {
+        const recipients = [];
+        const { members } = await this.api("GET", `/v1/apps/${this.appId}/channels/${channelId}/members`);
+        for (const m of members) {
+            try {
+                const { keyPackages } = await this.api("POST", `/v1/apps/${this.appId}/users/${m.userId}/key-packages/claim`);
+                for (const kp of keyPackages) {
+                    if (kp.deviceId === this.deviceId)
+                        continue; // self added below with the known local key
+                    const parsed = JSON.parse(new TextDecoder().decode(b64.dec(kp.data)));
+                    recipients.push({ deviceId: kp.deviceId, publicKeyJwk: parsed.pub });
+                }
+            }
+            catch {
+                /* a member with no claimable packages converges via sync/backup later */
+            }
+        }
+        recipients.push({ deviceId: this.deviceId, publicKeyJwk: this.keys.publicKeyJwk });
+        // ring first (bounded), send key last — recipients adopt the last welcome
+        const ring = [...(this.channelKeyRings.get(channelId)?.values() ?? [])].slice(0, 8);
+        for (const rk of ring)
+            await this.postWelcome(mlsGroupId, channelId, await wrapChannelKey(rk, recipients));
+        const send = this.channelKeys.get(channelId);
+        if (send)
+            await this.postWelcome(mlsGroupId, channelId, await wrapChannelKey(send, recipients));
+    }
     /** In-flight key recoveries, deduped per channel so a burst of undecryptable
      *  frames triggers a single welcome sync rather than one fetch per message. */
     keyRecovery = new Map();
@@ -634,7 +876,7 @@ export class NoPeek extends Emitter {
         let rawDK = await exportRawKeyB64(dataKey);
         let reusedDK = false;
         const carried = {};
-        let remoteChannelKeys = null;
+        let remotePayload = null;
         try {
             const { backups } = await this.api("GET", `/v1/apps/${this.appId}/users/${this.userId}/history-backups`);
             const newest = backups[0];
@@ -680,8 +922,7 @@ export class NoPeek extends Emitter {
                         const res = await fetch(newest.downloadUrl);
                         if (res.ok) {
                             const ct = b64.enc(new Uint8Array(await res.arrayBuffer()));
-                            const payload = await decryptPayload(await importRawKeyB64(candidate), ct);
-                            remoteChannelKeys = payload.channelKeys ?? null;
+                            remotePayload = await decryptPayload(await importRawKeyB64(candidate), ct);
                             oldDK = candidate; // decrypt success ⇒ the cached dk is the live one
                         }
                     }
@@ -715,26 +956,25 @@ export class NoPeek extends Emitter {
         }
         // Merge: keys from the existing backup that this device lacks stay in the
         // new payload (and heal this device's local key store while we're at it).
-        if (remoteChannelKeys) {
-            let healed = false;
-            for (const [chId, raw] of Object.entries(remoteChannelKeys)) {
-                if (this.channelKeys.has(chId))
-                    continue;
-                try {
-                    this.channelKeys.set(chId, await importChannelKey(raw));
-                    healed = true;
-                }
-                catch {
-                    /* skip a corrupt entry */
-                }
-            }
-            if (healed)
+        // A remote key that DIFFERS from ours goes to the history ring — a refresh
+        // must never erase a key some other device is still decrypting with. The
+        // remote envelope's device identity (another lineage's) and its legacy
+        // identities are preserved as OUR legacy identities for the same reason.
+        if (remotePayload) {
+            await this.registerLegacyIdentity(remotePayload.device);
+            const healed = await this.foldBackupKeys(remotePayload);
+            if (healed.length)
                 await this.persistChannelKeys();
         }
         const channelKeys = {};
         for (const [chId, k] of this.channelKeys)
             channelKeys[chId] = await exportChannelKey(k);
-        const ciphertext = await encryptPayload(dataKey, { v: 2, device: { deviceId: this.deviceId, keys: this.keys }, channelKeys });
+        const channelKeyRings = {};
+        for (const [chId, ring] of this.channelKeyRings)
+            if (ring.size)
+                channelKeyRings[chId] = [...ring.keys()];
+        const legacyDevices = [...this.legacyIdentities].map(([deviceId, keys]) => ({ deviceId, keys }));
+        const ciphertext = await encryptPayload(dataKey, { v: 2, device: { deviceId: this.deviceId, keys: this.keys }, legacyDevices, channelKeys, channelKeyRings });
         const iterations = 210_000;
         const wraps = { ...carried };
         for (const [kind, secret] of [["password", s.password], ["recovery", s.recoveryCode]]) {
@@ -778,6 +1018,43 @@ export class NoPeek extends Emitter {
         }
         return rec.backupId;
     }
+    /** Fold a decrypted backup payload's keys into this device's key store:
+     *  channels we have NO key for adopt the backup's key; a key that differs
+     *  from what we hold (either direction) lands in the history ring — nothing
+     *  is ever overwritten-and-lost. Legacy device identities carried in the
+     *  payload are registered too (welcome unwrap for old lineages). Returns the
+     *  channels that gained a key. Callers persist channel keys. */
+    async foldBackupKeys(payload) {
+        for (const d of payload.legacyDevices ?? [])
+            await this.registerLegacyIdentity(d);
+        const touched = new Set();
+        for (const [chId, raw] of Object.entries(payload.channelKeys ?? {})) {
+            try {
+                if (!this.channelKeys.has(chId)) {
+                    this.channelKeys.set(chId, await importChannelKey(raw));
+                    touched.add(chId);
+                }
+                else if (await this.ringAdd(chId, await importChannelKey(raw), raw)) {
+                    touched.add(chId);
+                }
+            }
+            catch {
+                /* skip a corrupt entry */
+            }
+        }
+        for (const [chId, raws] of Object.entries(payload.channelKeyRings ?? {})) {
+            for (const raw of raws) {
+                try {
+                    if (await this.ringAdd(chId, await importChannelKey(raw), raw))
+                        touched.add(chId);
+                }
+                catch {
+                    /* skip a corrupt entry */
+                }
+            }
+        }
+        return [...touched];
+    }
     /** Where the current backup envelope's raw data key is cached on this device.
      *  Sensitivity-equivalent to the channel keys (`nopeek:<user>:channelKeys`)
      *  already persisted in the same store — it decrypts a payload containing
@@ -816,18 +1093,7 @@ export class NoPeek extends Emitter {
         const ct = b64.enc(new Uint8Array(await res.arrayBuffer()));
         // Throws if the envelope was re-keyed by another device (stale cached dk).
         const payload = await decryptPayload(await importRawKeyB64(rawDK), ct);
-        const added = [];
-        for (const [chId, raw] of Object.entries(payload.channelKeys ?? {})) {
-            if (this.channelKeys.has(chId))
-                continue;
-            try {
-                this.channelKeys.set(chId, await importChannelKey(raw));
-                added.push(chId);
-            }
-            catch {
-                /* skip a corrupt entry */
-            }
-        }
+        const added = await this.foldBackupKeys(payload);
         if (added.length) {
             await this.persistChannelKeys();
             for (const chId of added)
@@ -835,27 +1101,14 @@ export class NoPeek extends Emitter {
         }
         return added.length;
     }
-    /**
-     * Restore chats on a NEW device from the latest encrypted backup. Pass the
-     * account password (preferred) and/or the recovery code — whichever unlocks
-     * the backup is used. Rehydrates channel keys so server-stored history
-     * decrypts. Returns the number of channels restored.
-     */
-    async restore(secrets) {
-        const s = typeof secrets === "string" ? { recoveryCode: secrets } : secrets;
-        const { backups } = await this.api("GET", `/v1/apps/${this.appId}/users/${this.userId}/history-backups`);
-        if (!backups.length)
-            throw new Error("No backup found for this user.");
-        const b = backups[0]; // newest first
+    /** Unlock ONE backup record with the given secrets; throws if none open it. */
+    async unlockBackup(b, s) {
         const kd = b.keyDerivation || {};
         const res = await fetch(b.downloadUrl);
         if (!res.ok)
             throw new Error(`backup download failed: HTTP ${res.status}`);
         const ct = b64.enc(new Uint8Array(await res.arrayBuffer()));
-        let payload;
         if (kd.scheme === "wrapped-v2") {
-            let dataKey = null;
-            let rawDK = null;
             for (const [kind, secret] of [["password", s.password], ["recovery", s.recoveryCode]]) {
                 const w = secret && kd.wraps?.[kind];
                 if (!w)
@@ -863,47 +1116,75 @@ export class NoPeek extends Emitter {
                 try {
                     const kek = await deriveBackupKey(secret, w.salt, w.iterations);
                     const { dk } = await decryptPayload(kek, w.wrapped);
-                    dataKey = await importRawKeyB64(dk);
-                    rawDK = dk;
-                    break;
+                    return { payload: await decryptPayload(await importRawKeyB64(dk), ct), rawDK: dk };
                 }
                 catch {
                     /* wrong secret for this wrap — try the next */
                 }
             }
-            if (!dataKey)
-                throw new Error("Couldn't unlock the backup with the provided password or recovery code.");
-            payload = await decryptPayload(dataKey, ct);
-            // Cache the data key: this restored device can then refresh the backup and
-            // pull later-added keys (refreshKeysFromBackup) with no secret in memory.
-            if (rawDK) {
-                try {
-                    await this.store.set(this.backupDkStoreKey(), rawDK);
-                }
-                catch {
-                    /* store hiccup — restore itself succeeded */
-                }
+            throw new Error("Couldn't unlock the backup with the provided password or recovery code.");
+        }
+        // legacy single-layer backup: payload keyed directly off the recovery code
+        const code = s.recoveryCode ?? s.password;
+        if (!code)
+            throw new Error("This backup requires a recovery code.");
+        const key = await deriveBackupKey(code, kd.salt, kd.iterations);
+        try {
+            return { payload: await decryptPayload(key, ct), rawDK: null };
+        }
+        catch {
+            throw new Error("Recovery code is incorrect — could not decrypt the backup.");
+        }
+    }
+    /**
+     * Restore chats on a NEW device from the user's encrypted backups. Pass the
+     * account password (preferred) and/or the recovery code — whichever unlocks
+     * a backup is used. Tries the secrets against EVERY listed backup (newest →
+     * oldest), not just the newest: an account can have several device lineages
+     * (e.g. an old phone's envelope plus a later web login's), and a key that
+     * only ever reached one lineage's envelope must still be recoverable. The
+     * newest unlockable envelope's device identity is adopted; every OTHER
+     * embedded identity is kept as a legacy identity so welcomes addressed to it
+     * still unwrap. Returns the number of channels restored from the newest
+     * envelope (legacy-envelope keys fold in on top).
+     */
+    async restore(secrets) {
+        const s = typeof secrets === "string" ? { recoveryCode: secrets } : secrets;
+        const { backups } = await this.api("GET", `/v1/apps/${this.appId}/users/${this.userId}/history-backups`);
+        if (!backups.length)
+            throw new Error("No backup found for this user.");
+        const unlocked = [];
+        let newestErr = null;
+        for (const b of backups) {
+            try {
+                unlocked.push(await this.unlockBackup(b, s));
+            }
+            catch (e) {
+                if (newestErr === null)
+                    newestErr = e; // newest-first: keep its error semantics
             }
         }
-        else {
-            // legacy single-layer backup: payload keyed directly off the recovery code
-            const code = s.recoveryCode ?? s.password;
-            if (!code)
-                throw new Error("This backup requires a recovery code.");
-            const key = await deriveBackupKey(code, kd.salt, kd.iterations);
+        if (!unlocked.length)
+            throw newestErr ?? new Error("Couldn't unlock the backup with the provided password or recovery code.");
+        const newest = unlocked[0];
+        // Cache the newest envelope's data key: this restored device can then
+        // refresh the backup and pull later-added keys (refreshKeysFromBackup)
+        // with no secret in memory.
+        if (newest.rawDK) {
             try {
-                payload = await decryptPayload(key, ct);
+                await this.store.set(this.backupDkStoreKey(), newest.rawDK);
             }
             catch {
-                throw new Error("Recovery code is incorrect — could not decrypt the backup.");
+                /* store hiccup — restore itself succeeded */
             }
         }
-        await this.adoptBackedUpDevice(payload.device);
-        for (const [chId, raw] of Object.entries(payload.channelKeys)) {
-            this.channelKeys.set(chId, await importChannelKey(raw));
+        await this.adoptBackedUpDevice(newest.payload.device);
+        for (const u of unlocked) {
+            await this.registerLegacyIdentity(u.payload.device); // no-op for the adopted identity
+            await this.foldBackupKeys(u.payload); // also folds the payload's legacyDevices
         }
         await this.persistChannelKeys();
-        return Object.keys(payload.channelKeys).length;
+        return Object.keys(newest.payload.channelKeys ?? {}).length;
     }
     // ------------------------------------------------- server-side escrow ----
     /** Cached escrow availability for THIS caller ({enabled, escrowPublicKey}). */
@@ -961,11 +1242,10 @@ export class NoPeek extends Emitter {
             /* store hiccup — restore itself succeeded */
         }
         await this.adoptBackedUpDevice(payload.device);
-        for (const [chId, raw] of Object.entries(payload.channelKeys)) {
-            this.channelKeys.set(chId, await importChannelKey(raw));
-        }
+        await this.registerLegacyIdentity(payload.device); // no-op when adopted
+        await this.foldBackupKeys(payload);
         await this.persistChannelKeys();
-        return Object.keys(payload.channelKeys).length;
+        return Object.keys(payload.channelKeys ?? {}).length;
     }
     /**
      * Adopt the device identity stored in a backup so a returning user on a fresh
@@ -1140,17 +1420,20 @@ export class NoPeek extends Emitter {
         if (env.ciphertext) {
             if (!this.channelKeys.has(channelId))
                 await this.deriveAndSet(channelId);
-            const key = this.channelKeys.get(channelId);
-            if (!key) {
-                base.decryptionFailed = true;
-                return base;
-            }
-            try {
-                base.body = await decryptPayload(key, String(env.ciphertext));
-            }
-            catch {
-                base.decryptionFailed = true;
+            // Send key first, then the history ring — messages encrypted under a
+            // superseded key (rotation, divergence heal) stay readable forever.
+            const primary = this.channelKeys.get(channelId);
+            const candidates = [...(primary ? [primary] : []), ...(this.channelKeyRings.get(channelId)?.values() ?? [])];
+            for (const key of candidates) {
+                try {
+                    base.body = await decryptPayload(key, String(env.ciphertext));
+                    return base;
+                }
+                catch {
+                    /* wrong key for this message — try the next candidate */
+                }
             }
+            base.decryptionFailed = true;
         }
         return base;
     }
@@ -1201,7 +1484,10 @@ export class Channel {
     /** E2EE key ceremony (creator side). */
     async establishKeys(memberIds) {
         const key = await generateChannelKey();
-        this.np.setChannelKey(this.channelId, key);
+        // NOTE: the minted key is NOT adopted yet — only the winner of the epoch
+        // 0→1 commit below may use it. Adopting first was the root cause of the
+        // "restored device sends with a key nobody else holds" bug: a device that
+        // LOST the race kept the orphan key locally and encrypted into the void.
         // Wrap for EVERY member device — peers, the creator's OTHER devices, and
         // (crucially) this device itself. The self-wrap makes the welcome a durable
         // second carrier of the key: a future device that restores this identity
@@ -1229,13 +1515,15 @@ export class Channel {
             }
         }
         recipients.push({ deviceId: this.np.deviceId, publicKeyJwk: this.np.devicePublicKeyJwk });
-        // advance epoch 0 -> 1 (server-enforced single writer)
+        // advance epoch 0 -> 1 (server-enforced single writer). Losing this race
+        // throws STALE_EPOCH — and the minted key is discarded with the throw.
         await this.np.api("POST", `/v1/apps/${this.np.appId}/mls/groups/${this.record.mlsGroupId}/handshakes`, {
             epoch: 0,
             kind: "commit",
             senderDeviceId: this.np.deviceId,
             payload: b64.enc(new TextEncoder().encode(JSON.stringify({ suite: "npdev-1", op: "init" }))),
         });
+        this.np.setChannelKey(this.channelId, key); // commit won — the key is canonical
         if (recipients.length) {
             const wrapped = await wrapChannelKey(key, recipients);
             const welcome = { suite: "npdev-1", channelId: this.channelId, wrapped };
@@ -1253,9 +1541,11 @@ export class Channel {
         if (!this.e2ee)
             return true;
         if (this.np.getChannelKey(this.channelId)) {
-            // We hold the key — make sure a welcome addressed to THIS device exists in
-            // the group so a backup-restored successor of this identity can pull it.
-            void this.np.ensureSelfWelcome(this.channelId, this.record.mlsGroupId);
+            // We hold a key — reconcile it against the group's welcome history ONCE
+            // (posting the missing self-welcome, or ADOPTING the group's newer key if
+            // this device had diverged) BEFORE it is ever used to send. Awaited so a
+            // diverged device can never fire off even one message under a dead key.
+            await this.np.reconcileChannelKey(this.channelId, this.record.mlsGroupId);
             return true;
         }
         if (await this.np.deriveAndSet(this.channelId))
@@ -1264,10 +1554,25 @@ export class Channel {
             return false;
         if (await this.np.syncChannelKey(this.channelId, this.record.mlsGroupId))
             return true;
+        // Still keyless — a key-holding device may have refreshed the backup since
+        // we restored. Recovering the EXISTING key always beats minting a new one.
+        try {
+            if (await this.np.hasCachedBackupKey()) {
+                await this.np.refreshKeysFromBackup();
+                if (this.np.getChannelKey(this.channelId))
+                    return true;
+            }
+        }
+        catch {
+            /* stale cached dk or no backup — fall through */
+        }
         // No key and no welcome yet — e.g. the channel was created server-side, or the
         // original creator's key was lost. Bootstrap the ceremony as the originator:
         // the server enforces a single epoch-0→1 writer, so if a peer races us we lose
-        // the commit and fall back to pulling their welcome.
+        // the commit (STALE_EPOCH) and fall back to pulling their welcome — and since
+        // establishKeys only adopts its key AFTER winning, losing leaves no orphan
+        // key behind. If no key is reachable at all, sending fails closed rather
+        // than encrypting under a key no other device could ever obtain.
         try {
             const { members } = await this.np.api("GET", `/v1/apps/${this.np.appId}/channels/${this.channelId}/members`);
             await this.establishKeys(members.map((m) => m.userId));