@agora-sdk/secure-chat-core 0.3.0 → 0.5.0

package/dist/esm/hooks/useSecureBackup.d.ts

@@ -0,0 +1,67 @@
+import { type PassphraseStrength } from "../backup/passphrase-strength.js";
+/** State + actions returned by {@link useSecureBackup}. */
+export interface UseSecureBackupValues {
+    /**
+     * Seal all local key material under `passphrase` and upload it to the blind server.
+     * @throws {Error} If export or upload fails.
+     */
+    backup: (passphrase: string) => Promise<void>;
+    /**
+     * Restore local key material on a fresh client from the server's backup, rehydrating the device and
+     * every conversation's group state.
+     * @throws {Error} If no backup exists, the passphrase is wrong, or the backup is corrupt.
+     */
+    restore: (passphrase: string) => Promise<void>;
+    /** True while {@link UseSecureBackupValues.backup} is in flight. */
+    backingUp: boolean;
+    /** True while {@link UseSecureBackupValues.restore} is in flight. */
+    restoring: boolean;
+    /** The last error thrown by backup or restore, or `null`. */
+    error: unknown;
+    /** Server `updatedAt` of the most recent successful upload this session, or `null`. */
+    lastBackupAt: string | null;
+    /** True once a group has advanced since the last backup (membership/epoch change) — prompt a re-backup. */
+    needsBackup: boolean;
+    /**
+     * True when there is NO local key material but a backup exists on the server — i.e. this client was
+     * evicted (Safari ITP / "clear browsing data") or is a fresh browser, and recovery is possible. The
+     * app should route to a passphrase prompt → {@link UseSecureBackupValues.restore} instead of
+     * registering a new device. Indistinguishable cases (evicted vs cleared vs new browser) all resolve
+     * the same way. Cleared after a successful restore.
+     */
+    needsRestore: boolean;
+    /** True while the mount-time eviction check (or {@link UseSecureBackupValues.recheckRestore}) is in flight. */
+    checkingRestore: boolean;
+    /**
+     * Re-run the eviction check on demand (e.g. after catching a storage error mid-session, or after
+     * sign-in). Skips the server entirely when local key material is present.
+     * @returns The new {@link UseSecureBackupValues.needsRestore} value.
+     */
+    recheckRestore: () => Promise<boolean>;
+    /** Coarse client-side passphrase-strength estimate for a meter (see {@link estimatePassphraseStrength}). */
+    estimateStrength: (passphrase: string) => PassphraseStrength;
+}
+/**
+ * Manage passphrase backup + restore of the client's secure-chat key material.
+ *
+ * Backups are explicit (call {@link UseSecureBackupValues.backup}); `needsBackup` flips true when a
+ * group advances so the app can prompt. On mount it also detects an evicted/fresh client
+ * (`needsRestore`) so the app restores rather than registering a fresh, history-less identity.
+ *
+ * @returns Backup/restore actions, the evicted-client `needsRestore` signal, in-flight + error state, a
+ *   stale-backup signal, and a passphrase-strength helper.
+ * @throws {Error} When used outside a `<SecureChatProvider>`.
+ *
+ * @example
+ * ```tsx
+ * const { needsRestore, restore, backup } = useSecureBackup();
+ * const { device, register } = useSecureDevice();
+ * // Route an evicted / fresh client to restore; a true first-run to register.
+ * if (needsRestore) await restore(passphrase);      // prompt for the passphrase first
+ * else if (!device) await register();
+ * await backup(passphrase);                          // later, after a device/chat exists
+ * ```
+ * Restore should complete before the app relies on `useSecureDevice` (which read `device: null` on its
+ * own mount) — gate the chat subtree on a post-restore flag or remount it after restore.
+ */
+export declare function useSecureBackup(): UseSecureBackupValues;

package/dist/esm/hooks/useSecureBackup.js

@@ -0,0 +1,204 @@
+// useSecureBackup — passphrase backup + restore of all local key material.
+//
+// Backup: crypto.exportBackup(passphrase) seals the device identity + every group's state under a
+// real argon2id KDF + AEAD; we base64 the blob/nonce at the wire boundary and PUT it to the blind
+// server, which stores the ciphertext verbatim (it never sees the passphrase or plaintext).
+//
+// Restore (fresh browser): GET the blob → crypto.importBackup re-derives the identity + groups in
+// memory → re-assert the device server-side (idempotent) to recover its row → persist the device →
+// rebind each conversation's group state by conversationId from the server's conversation list (the
+// server is the source of truth for membership; the backup itself is conversationId-agnostic). The
+// handshake cursor is intentionally left unset so useSecureHandshakes re-pulls from since=0 and
+// dedupes — no cursor needs to live in the backup.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { toBase64, fromBase64 } from "../util/base64.js";
+import { useSecureChat } from "../context/secure-chat-context.js";
+import { estimatePassphraseStrength, } from "../backup/passphrase-strength.js";
+/**
+ * Manage passphrase backup + restore of the client's secure-chat key material.
+ *
+ * Backups are explicit (call {@link UseSecureBackupValues.backup}); `needsBackup` flips true when a
+ * group advances so the app can prompt. On mount it also detects an evicted/fresh client
+ * (`needsRestore`) so the app restores rather than registering a fresh, history-less identity.
+ *
+ * @returns Backup/restore actions, the evicted-client `needsRestore` signal, in-flight + error state, a
+ *   stale-backup signal, and a passphrase-strength helper.
+ * @throws {Error} When used outside a `<SecureChatProvider>`.
+ *
+ * @example
+ * ```tsx
+ * const { needsRestore, restore, backup } = useSecureBackup();
+ * const { device, register } = useSecureDevice();
+ * // Route an evicted / fresh client to restore; a true first-run to register.
+ * if (needsRestore) await restore(passphrase);      // prompt for the passphrase first
+ * else if (!device) await register();
+ * await backup(passphrase);                          // later, after a device/chat exists
+ * ```
+ * Restore should complete before the app relies on `useSecureDevice` (which read `device: null` on its
+ * own mount) — gate the chat subtree on a post-restore flag or remount it after restore.
+ */
+export function useSecureBackup() {
+    const { crypto, rest, repo, rememberGroup, subscribeGroupChange } = useSecureChat();
+    const [backingUp, setBackingUp] = useState(false);
+    const [restoring, setRestoring] = useState(false);
+    const [error, setError] = useState(null);
+    const [lastBackupAt, setLastBackupAt] = useState(null);
+    const [needsBackup, setNeedsBackup] = useState(false);
+    const [needsRestore, setNeedsRestore] = useState(false);
+    const [checkingRestore, setCheckingRestore] = useState(false);
+    // A group advancing (a join or a processed Commit) means the on-server backup is now stale.
+    // Guard the very first synchronous fire so mount doesn't immediately flag a backup as needed.
+    const armed = useRef(false);
+    useEffect(() => {
+        armed.current = true;
+        return subscribeGroupChange(() => {
+            if (armed.current)
+                setNeedsBackup(true);
+        });
+    }, [subscribeGroupChange]);
+    // Eviction / fresh-client detection: local key material gone but a server backup exists ⇒ restore is
+    // possible (and preferable to registering a new, history-less identity). Evicted, "cleared browsing
+    // data", and a brand-new browser are indistinguishable here and resolve the same way. We only hit the
+    // server when there's no local device, so the common (healthy) path stays a single IndexedDB read.
+    const recheckRestore = useCallback(async () => {
+        setCheckingRestore(true);
+        try {
+            const persisted = await repo.loadDevice();
+            if (persisted) {
+                setNeedsRestore(false);
+                return false;
+            }
+            const model = await rest.getKeyBackup();
+            const possible = model !== null;
+            setNeedsRestore(possible);
+            return possible;
+        }
+        catch (err) {
+            // Fail soft: a network blip must not strand the user as "needs restore". Surface the error only.
+            setError(err);
+            setNeedsRestore(false);
+            return false;
+        }
+        finally {
+            setCheckingRestore(false);
+        }
+    }, [repo, rest]);
+    useEffect(() => {
+        let alive = true;
+        repo
+            .loadDevice()
+            .then(async (persisted) => {
+            if (!alive || persisted)
+                return; // have local state → not evicted; skip the server call
+            const model = await rest.getKeyBackup();
+            if (alive)
+                setNeedsRestore(model !== null);
+        })
+            .catch((err) => {
+            if (alive)
+                setError(err); // fail soft
+        });
+        return () => {
+            alive = false;
+        };
+    }, [repo, rest]);
+    const backup = useCallback(async (passphrase) => {
+        setBackingUp(true);
+        setError(null);
+        try {
+            const b = await crypto.exportBackup(passphrase);
+            const { updatedAt } = await rest.uploadKeyBackup({
+                // base64 at the wire boundary; KDF params (incl. the hex salt) are non-secret metadata.
+                blob: toBase64(b.blob),
+                nonce: toBase64(b.nonce),
+                kdf: b.kdf,
+                kdfParams: b.kdfParams,
+                cipher: b.cipher,
+                version: b.version,
+            });
+            setLastBackupAt(updatedAt);
+            setNeedsBackup(false);
+        }
+        catch (err) {
+            setError(err);
+            throw err;
+        }
+        finally {
+            setBackingUp(false);
+        }
+    }, [crypto, rest]);
+    const restore = useCallback(async (passphrase) => {
+        setRestoring(true);
+        setError(null);
+        try {
+            const model = await rest.getKeyBackup();
+            if (!model)
+                throw new Error("No key backup found on the server to restore.");
+            // Decrypt + repopulate crypto memory (identity + groups). Returns the restored identity.
+            const id = await crypto.importBackup(passphrase, {
+                blob: fromBase64(model.blob),
+                nonce: fromBase64(model.nonce),
+                kdf: model.kdf,
+                kdfParams: model.kdfParams,
+                cipher: model.cipher,
+                version: model.version,
+            });
+            // Re-assert the (already-registered) device to recover its server row — idempotent on
+            // (userId, deviceId). The row's id is the senderDeviceId messages need.
+            const device = await rest.registerDevice({
+                deviceId: id.deviceId,
+                signaturePublicKey: toBase64(id.signaturePublicKey),
+                credential: toBase64(id.credential),
+                ciphersuite: id.ciphersuite,
+            });
+            await repo.saveDevice({
+                deviceId: id.deviceId,
+                deviceState: await crypto.exportDeviceState(),
+                device,
+            });
+            // Rebind conversationId → restored group state from the server's conversation list.
+            let cursor;
+            for (;;) {
+                const page = await rest.listConversations(cursor ? { cursor } : undefined);
+                for (const c of page.conversations) {
+                    try {
+                        await rememberGroup(c.id, {
+                            mlsGroupId: fromBase64(c.mlsGroupId),
+                            epoch: BigInt(c.currentEpoch),
+                        });
+                    }
+                    catch {
+                        // The group isn't in this backup (created after it, or we're not a member) — skip it.
+                    }
+                }
+                if (!page.hasMore || page.conversations.length === 0)
+                    break;
+                const last = page.conversations[page.conversations.length - 1];
+                cursor = last.lastMessageAt ?? last.createdAt;
+            }
+            setNeedsBackup(false);
+            setNeedsRestore(false); // we now hold local key material again
+        }
+        catch (err) {
+            setError(err);
+            throw err;
+        }
+        finally {
+            setRestoring(false);
+        }
+    }, [crypto, rest, repo, rememberGroup]);
+    return {
+        backup,
+        restore,
+        backingUp,
+        restoring,
+        error,
+        lastBackupAt,
+        needsBackup,
+        needsRestore,
+        checkingRestore,
+        recheckRestore,
+        estimateStrength: estimatePassphraseStrength,
+    };
+}
+//# sourceMappingURL=useSecureBackup.js.map

package/dist/esm/hooks/useSecureBackup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSecureBackup.js","sourceRoot":"","sources":["../../../src/hooks/useSecureBackup.tsx"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,EAAE;AACF,kGAAkG;AAClG,kGAAkG;AAClG,4FAA4F;AAC5F,EAAE;AACF,kGAAkG;AAClG,mGAAmG;AACnG,oGAAoG;AACpG,mGAAmG;AACnG,gGAAgG;AAChG,mDAAmD;AAEnD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACjE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAClE,OAAO,EACL,0BAA0B,GAE3B,MAAM,kCAAkC,CAAC;AA6C1C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,oBAAoB,EAAE,GAAG,aAAa,EAAE,CAAC;IAEpF,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClD,MAAM,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAClD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAU,IAAI,CAAC,CAAC;IAClD,MAAM,CAAC,YAAY,EAAE,eAAe,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAC;IACtE,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IACtD,MAAM,CAAC,YAAY,EAAE,eAAe,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IACxD,MAAM,CAAC,eAAe,EAAE,kBAAkB,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAE9D,4FAA4F;IAC5F,8FAA8F;IAC9F,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,SAAS,CAAC,GAAG,EAAE;QACb,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC;QACrB,OAAO,oBAAoB,CAAC,GAAG,EAAE;YAC/B,IAAI,KAAK,CAAC,OAAO;gBAAE,cAAc,CAAC,IAAI,CAAC,CAAC;QAC1C,CAAC,CAAC,CAAC;IACL,CAAC,EAAE,CAAC,oBAAoB,CAAC,CAAC,CAAC;IAE3B,qGAAqG;IACrG,oGAAoG;IACpG,sGAAsG;IACtG,mGAAmG;IACnG,MAAM,cAAc,GAAG,WAAW,CAAC,KAAK,IAAsB,EAAE;QAC9D,kBAAkB,CAAC,IAAI,CAAC,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;YAC1C,IAAI,SAAS,EAAE,CAAC;gBACd,eAAe,CAAC,KAAK,CAAC,CAAC;gBACvB,OAAO,KAAK,CAAC;YACf,CAAC;YACD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;YACxC,MAAM,QAAQ,GAAG,KAAK,KAAK,IAAI,CAAC;YAChC,eAAe,CAAC,QAAQ,CAAC,CAAC;YAC1B,OAAO,QAAQ,CAAC;QAClB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,iGAAiG;YACjG,QAAQ,CAAC,GAAG,CAAC,CAAC;YACd,eAAe,CAAC,KAAK,CAAC,CAAC;YACvB,OAAO,KAAK,CAAC;QACf,CAAC;gBAAS,CAAC;YACT,kBAAkB,CAAC,KAAK,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;IAEjB,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,KAAK,GAAG,IAAI,CAAC;QACjB,IAAI;aACD,UAAU,EAAE;aACZ,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE;YACxB,IAAI,CAAC,KAAK,IAAI,SAAS;gBAAE,OAAO,CAAC,uDAAuD;YACxF,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;YACxC,IAAI,KAAK;gBAAE,eAAe,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC;QAC7C,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;YACb,IAAI,KAAK;gBAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY;QACxC,CAAC,CAAC,CAAC;QACL,OAAO,GAAG,EAAE;YACV,KAAK,GAAG,KAAK,CAAC;QAChB,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;IAEjB,MAAM,MAAM,GAAG,WAAW,CACxB,KAAK,EAAE,UAAkB,EAAiB,EAAE;QAC1C,YAAY,CAAC,IAAI,CAAC,CAAC;QACnB,QAAQ,CAAC,IAAI,CAAC,CAAC;QACf,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;YAChD,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC;gBAC/C,wFAAwF;gBACxF,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;gBACtB,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC;gBACxB,GAAG,EAAE,CAAC,CAAC,GAA4B;gBACnC,SAAS,EAAE,CAAC,CAAC,SAAS;gBACtB,MAAM,EAAE,CAAC,CAAC,MAA6C;gBACvD,OAAO,EAAE,CAAC,CAAC,OAAO;aACnB,CAAC,CAAC;YACH,eAAe,CAAC,SAAS,CAAC,CAAC;YAC3B,cAAc,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,GAAG,CAAC,CAAC;YACd,MAAM,GAAG,CAAC;QACZ,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC,EACD,CAAC,MAAM,EAAE,IAAI,CAAC,CACf,CAAC;IAEF,MAAM,OAAO,GAAG,WAAW,CACzB,KAAK,EAAE,UAAkB,EAAiB,EAAE;QAC1C,YAAY,CAAC,IAAI,CAAC,CAAC;QACnB,QAAQ,CAAC,IAAI,CAAC,CAAC;QACf,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;YACxC,IAAI,CAAC,KAAK;gBAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;YAE7E,yFAAyF;YACzF,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,UAAU,EAAE;gBAC/C,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;gBAC5B,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC;gBAC9B,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,OAAO,EAAE,KAAK,CAAC,OAAO;aACvB,CAAC,CAAC;YAEH,sFAAsF;YACtF,wEAAwE;YACxE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC;gBACvC,QAAQ,EAAE,EAAE,CAAC,QAAQ;gBACrB,kBAAkB,EAAE,QAAQ,CAAC,EAAE,CAAC,kBAAkB,CAAC;gBACnD,UAAU,EAAE,QAAQ,CAAC,EAAE,CAAC,UAAU,CAAC;gBACnC,WAAW,EAAE,EAAE,CAAC,WAAW;aAC5B,CAAC,CAAC;YACH,MAAM,IAAI,CAAC,UAAU,CAAC;gBACpB,QAAQ,EAAE,EAAE,CAAC,QAAQ;gBACrB,WAAW,EAAE,MAAM,MAAM,CAAC,iBAAiB,EAAE;gBAC7C,MAAM;aACP,CAAC,CAAC;YAEH,oFAAoF;YACpF,IAAI,MAA0B,CAAC;YAC/B,SAAS,CAAC;gBACR,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;gBAC3E,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;oBACnC,IAAI,CAAC;wBACH,MAAM,aAAa,CAAC,CAAC,CAAC,EAAE,EAAE;4BACxB,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC;4BACpC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC;yBAC9B,CAAC,CAAC;oBACL,CAAC;oBAAC,MAAM,CAAC;wBACP,sFAAsF;oBACxF,CAAC;gBACH,CAAC;gBACD,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,aAAa,CAAC,MAAM,KAAK,CAAC;oBAAE,MAAM;gBAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;gBAChE,MAAM,GAAG,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,SAAS,CAAC;YAChD,CAAC;YAED,cAAc,CAAC,KAAK,CAAC,CAAC;YACtB,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,uCAAuC;QACjE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,GAAG,CAAC,CAAC;YACd,MAAM,GAAG,CAAC;QACZ,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC,EACD,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,CAAC,CACpC,CAAC;IAEF,OAAO;QACL,MAAM;QACN,OAAO;QACP,SAAS;QACT,SAAS;QACT,KAAK;QACL,YAAY;QACZ,WAAW;QACX,YAAY;QACZ,eAAe;QACf,cAAc;QACd,gBAAgB,EAAE,0BAA0B;KAC7C,CAAC;AACJ,CAAC"}

package/dist/esm/hooks/useSecureDevice.d.ts

@@ -8,7 +8,20 @@ export interface UseSecureDeviceOptions {
     ciphersuite?: number;
     /** How many KeyPackages to publish on registration and replenish toward. Default 20. */
     keyPackageTarget?: number;
-    /** Auto-replenish when `secure:key-packages-low` fires. Default true. */
+    /**
+     * Low-water mark: when the server's available count drops **below** this, a top-up refills to
+     * {@link UseSecureDeviceOptions.keyPackageTarget}. KeyPackages are single-use, so this guards
+     * against exhaustion (peers unable to add this device). Default `ceil(keyPackageTarget / 2)` (10 for
+     * the default target of 20). Only governs the proactive/manual path — the server's
+     * `secure:key-packages-low` signal always tops up, since the server already judged the stock low.
+     */
+    keyPackageLowWater?: number;
+    /**
+     * Auto-replenish without app involvement. Default true. When true the hook subscribes to
+     * `secure:key-packages-low` and runs a one-shot proactive count check once the device is ready. When
+     * false, both automatic paths are disabled but {@link UseSecureDeviceValues.checkAndReplenish}
+     * still works on demand.
+     */
     autoReplenish?: boolean;
 }
 /** The state and actions returned by {@link useSecureDevice}. */
@@ -29,6 +42,13 @@ export interface UseSecureDeviceValues {
     publishKeyPackages: (count?: number) => Promise<number>;
     /** Re-query the server for the available KeyPackage count and update `keyPackagesAvailable`. */
     refreshKeyPackageCount: () => Promise<number>;
+    /**
+     * Refresh the server count and, if it's below the low-water mark, top up to `keyPackageTarget`
+     * (publishing only the deficit). Safe to call before {@link UseSecureDeviceValues.register} — it
+     * no-ops to 0 when there's no device and never throws for that case — so an app can wire it to a
+     * window-focus / app-foreground handler.
+     */
+    checkAndReplenish: () => Promise<number>;
 }
 /**
  * Register this client as an MLS device, persist its identity, and keep KeyPackages stocked.

package/dist/esm/hooks/useSecureDevice.js

@@ -3,7 +3,14 @@
 //
 // On mount it re-hydrates a persisted device (stable deviceId + private state via
 // crypto.importDeviceState) so a reload does NOT mint a new identity. register() generates, registers
-// on the server, and persists. Replenishes on the `secure:key-packages-low` realtime signal.
+// on the server, and persists.
+//
+// KeyPackages are single-use (the server consumes one per group-add), so running dry means peers can't
+// add this device. The hook keeps the stock topped up to `keyPackageTarget` from three triggers: the
+// server's `secure:key-packages-low` realtime signal, a one-shot proactive count check once the device
+// is ready (self-heals a client that missed the signal while offline), and an app-callable
+// `checkAndReplenish()` (e.g. on window focus). Each top-up publishes only the DEFICIT to the target
+// (using the actual available count), not a blind full batch.
 import { useCallback, useEffect, useRef, useState } from "react";
 import { toBase64 } from "../util/base64.js";
 import { useSecureChat } from "../context/secure-chat-context.js";
@@ -37,6 +44,7 @@ function newDeviceId() {
 export function useSecureDevice(options = {}) {
     const { crypto, rest, socket, repo } = useSecureChat();
     const { ciphersuite, keyPackageTarget = 20, autoReplenish = true } = options;
+    const keyPackageLowWater = options.keyPackageLowWater ?? Math.ceil(keyPackageTarget / 2);
     const [device, setDevice] = useState(null);
     const [loading, setLoading] = useState(true);
     const [registering, setRegistering] = useState(false);
@@ -44,6 +52,8 @@ export function useSecureDevice(options = {}) {
     const [keyPackagesAvailable, setKeyPackagesAvailable] = useState(null);
     const deviceIdRef = useRef(options.deviceId ?? newDeviceId());
     const registerStartedRef = useRef(false);
+    // Guards the one-shot proactive count check so it runs once per device-ready, not on every render.
+    const proactiveCheckedRef = useRef(false);
     // On mount: re-hydrate a persisted device (stable id + private state). No persisted device ⇒
     // first-run; the app calls register().
     useEffect(() => {
@@ -96,6 +106,25 @@ export function useSecureDevice(options = {}) {
         setKeyPackagesAvailable(available);
         return available;
     }, [rest, device]);
+    // Publish only the shortfall (target − available) to refill to the target; nothing if already
+    // at/above it. Optimistically bumps the local count so the UI reflects the refill without a re-query.
+    // Callers guarantee `device` exists (publishKeyPackages throws otherwise).
+    const replenishToTarget = useCallback(async (available) => {
+        const deficit = keyPackageTarget - available;
+        if (deficit <= 0)
+            return 0;
+        const published = await publishKeyPackages(deficit);
+        setKeyPackagesAvailable(available + published);
+        return published;
+    }, [keyPackageTarget, publishKeyPackages]);
+    const checkAndReplenish = useCallback(async () => {
+        if (!device)
+            return 0; // not registered yet — no-op (app may call this eagerly on focus)
+        const available = await refreshKeyPackageCount();
+        if (available >= keyPackageLowWater)
+            return 0;
+        return replenishToTarget(available);
+    }, [device, refreshKeyPackageCount, keyPackageLowWater, replenishToTarget]);
     const register = useCallback(async () => {
         registerStartedRef.current = true;
         setRegistering(true);
@@ -125,17 +154,28 @@ export function useSecureDevice(options = {}) {
             setRegistering(false);
         }
     }, [crypto, rest, repo, ciphersuite]);
-    // Auto-replenish on the server's low-water signal for this device.
+    // Auto-replenish on the server's low-water signal for this device. We top up to the target using the
+    // count the signal reports (not a blind full batch), and trust the server's "low" verdict — the
+    // client `keyPackageLowWater` only gates the proactive path below.
     useEffect(() => {
         if (!autoReplenish || !device)
             return;
         const off = socket.on("secure:key-packages-low", (signal) => {
             if (signal.deviceId !== device.id)
-                return;
-            publishKeyPackages().catch(setError);
+                return; // device.id is the server ROW id, not the deviceId
+            setKeyPackagesAvailable(signal.available);
+            replenishToTarget(signal.available).catch(setError);
         });
         return off;
-    }, [autoReplenish, device, socket, publishKeyPackages]);
+    }, [autoReplenish, device, socket, replenishToTarget]);
+    // One-shot proactive top-up once the device is ready (covers both register and rehydrate-on-mount),
+    // so a client that missed the realtime signal while offline self-heals on next load.
+    useEffect(() => {
+        if (!autoReplenish || !device || proactiveCheckedRef.current)
+            return;
+        proactiveCheckedRef.current = true;
+        checkAndReplenish().catch(setError);
+    }, [autoReplenish, device, checkAndReplenish]);
     return {
         device,
         loading,
@@ -145,6 +185,7 @@ export function useSecureDevice(options = {}) {
         register,
         publishKeyPackages,
         refreshKeyPackageCount,
+        checkAndReplenish,
     };
 }
 //# sourceMappingURL=useSecureDevice.js.map

package/dist/esm/hooks/useSecureDevice.js.map

@@ -1 +1 @@
-{"version":3,"file":"useSecureDevice.js","sourceRoot":"","sources":["../../../src/hooks/useSecureDevice.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"useSecureDevice.js","sourceRoot":"","sources":["../../../src/hooks/useSecureDevice.tsx"],"names":[],"mappings":"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"}

package/dist/esm/hooks/useSecureMessages.d.ts

@@ -1,11 +1,24 @@
 import { SecureMessageModel } from "../contract/index.js";
-import { GroupHandle } from "@agora-sdk/secure-chat-crypto";
-/** A stored message paired with its decrypted text (when a group handle is available). */
+import { GroupHandle, type SecureDecryptFailureReason } from "@agora-sdk/secure-chat-crypto";
+/**
+ * Decryption outcome for a stored message:
+ * - `ok` — decrypted + authenticated; `plaintext` is set.
+ * - `pending` — not decryptable yet (no group handle, or the message's epoch is ahead of ours); it will
+ *   be retried when the group advances. `plaintext` is null.
+ * - `rejected` — fails closed: the MLS core rejected it (replay, over-window gap, bad auth, malformed,
+ *   too-old epoch). NEVER retried; `plaintext` is null and `rejectedReason` says why.
+ */
+export type SecureMessageStatus = "ok" | "pending" | "rejected";
+/** A stored message paired with its decryption outcome. */
 export interface DecryptedSecureMessage {
     /** The raw message row from the server (still holds the base64 ciphertext). */
     model: SecureMessageModel;
-    /** Decrypted text, or null when no group handle is available or decryption is pending/failed. */
+    /** Decrypted text, or null when {@link DecryptedSecureMessage.status} is `pending` or `rejected`. */
     plaintext: string | null;
+    /** Decryption outcome — drives fail-closed handling and what the UI renders. */
+    status: SecureMessageStatus;
+    /** When `status` is `rejected`, why the MLS core refused the message. */
+    rejectedReason?: SecureDecryptFailureReason;
 }
 /** Options for {@link useSecureMessages}. */
 export interface UseSecureMessagesOptions {

package/dist/esm/hooks/useSecureMessages.js

@@ -5,7 +5,9 @@
 // options for advanced use. Without a resolvable handle, ciphertext is still listed/received
 // (plaintext: null) and sending is disabled.
 import { useCallback, useEffect, useRef, useState } from "react";
+import { SecureChatDecryptError, } from "@agora-sdk/secure-chat-crypto";
 import { toBase64, fromBase64, utf8ToBytes, bytesToUtf8 } from "../util/base64.js";
+import { padPlaintext, unpadPlaintext } from "../util/padding.js";
 import { useSecureChat } from "../context/secure-chat-context.js";
 /**
  * Load, decrypt, send, and live-receive messages in one secure conversation.
@@ -25,7 +27,7 @@ import { useSecureChat } from "../context/secure-chat-context.js";
  * ```
  */
 export function useSecureMessages(conversationId, options = {}) {
-    const { rest, crypto, socket, repo, resolveGroup, getGroupVersion, subscribeGroupChange } = useSecureChat();
+    const { rest, crypto, socket, repo, resolveGroup, getGroupVersion, subscribeGroupChange, padding } = useSecureChat();
     const [messages, setMessages] = useState([]);
     const [before, setBefore] = useState(undefined);
     const [hasMore, setHasMore] = useState(true);
@@ -92,15 +94,34 @@ export function useSecureMessages(conversationId, options = {}) {
         };
     }, [options.senderDeviceId, repo]);
     const decrypt = useCallback(async (model) => {
+        // No handle yet (still resolving) → retryable once it arrives.
         if (!group)
-            return { model, plaintext: null };
+            return { model, plaintext: null, status: "pending" };
+        let plaintext;
         try {
-            const { plaintext } = await crypto.decryptMessage(group, fromBase64(model.ciphertext));
-            return { model, plaintext: bytesToUtf8(plaintext) };
+            ({ plaintext } = await crypto.decryptMessage(group, fromBase64(model.ciphertext)));
+        }
+        catch (err) {
+            // Classify, don't conflate. A message from an epoch we HAVEN'T reached yet is legitimately
+            // buffered (a future Commit will advance us, then this re-decrypts). Anything else that fails
+            // at an epoch we HAVE reached is a terminal rejection — the MLS core refused it (replay,
+            // over-window gap, bad auth, malformed, too-old epoch). Fail closed: never show it as text and
+            // never silently retry it forever (the old behavior masked replays/forgeries as "pending").
+            if (BigInt(model.epoch) > group.epoch) {
+                return { model, plaintext: null, status: "pending" };
+            }
+            const rejectedReason = err instanceof SecureChatDecryptError ? err.reason : "unknown";
+            return { model, plaintext: null, status: "rejected", rejectedReason };
+        }
+        // Decrypt + MLS authentication succeeded, so the bytes are from a real group member. Strip the
+        // size-bucket padding frame (see util/padding). A bad frame here is NOT a decrypt failure — it's a
+        // framing/version mismatch from an authenticated sender — so fail closed as "malformed" rather
+        // than rendering raw padded bytes as text.
+        try {
+            return { model, plaintext: bytesToUtf8(unpadPlaintext(plaintext)), status: "ok" };
         }
         catch {
-            // Buffer/skip: epoch not yet reached, or undecryptable. Surface ciphertext without text.
-            return { model, plaintext: null };
+            return { model, plaintext: null, status: "rejected", rejectedReason: "malformed" };
         }
     }, [crypto, group]);
     const load = useCallback(async (reset) => {
@@ -142,30 +163,32 @@ export function useSecureMessages(conversationId, options = {}) {
             throw new Error("Cannot send: no MLS group handle for this conversation.");
         if (!senderDeviceId)
             throw new Error("Cannot send: senderDeviceId is required.");
-        const { ciphertext, epoch } = await crypto.encryptMessage(group, utf8ToBytes(text));
+        // Pad the plaintext to a size bucket BEFORE encryption so the ciphertext length leaks less
+        // (the receiver strips the frame in `decrypt`). See util/padding for the framing.
+        const { ciphertext, epoch } = await crypto.encryptMessage(group, padPlaintext(utf8ToBytes(text), padding));
         const sent = await rest.sendMessage(conversationId, {
             ciphertext: toBase64(ciphertext),
             epoch: epoch.toString(),
             senderDeviceId,
         });
         // Optimistic: we know our own plaintext without a round-trip through decrypt.
-        setMessages((prev) => [{ model: sent, plaintext: text }, ...prev]);
-    }, [crypto, rest, conversationId, group, senderDeviceId]);
+        setMessages((prev) => [{ model: sent, plaintext: text, status: "ok" }, ...prev]);
+    }, [crypto, rest, conversationId, group, senderDeviceId, padding]);
     useEffect(() => {
         refresh();
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [conversationId]);
-    // Decrypt history that was listed before the group handle resolved. On reload, the first page loads
-    // while resolveGroup is still in flight, so those rows come back `plaintext: null`; once the handle
-    // arrives (decrypt is recreated with it), re-decrypt the still-undecrypted rows in place — no
-    // re-fetch, scroll/pagination preserved.
+    // Re-decrypt buffered rows when the group handle advances. On reload the first page loads while
+    // resolveGroup is still in flight (those rows come back `pending`); a Commit/join also advances the
+    // epoch, letting previously-ahead rows decrypt. Retry ONLY `pending` rows — never `rejected` ones, so
+    // a replay/forgery the core already refused isn't retried on every epoch bump. `ok` rows are kept.
     useEffect(() => {
         if (!group)
             return;
-        if (!messagesRef.current.some((m) => m.plaintext === null))
+        if (!messagesRef.current.some((m) => m.status === "pending"))
             return;
         let alive = true;
-        Promise.all(messagesRef.current.map((m) => (m.plaintext === null ? decrypt(m.model) : Promise.resolve(m)))).then((next) => {
+        Promise.all(messagesRef.current.map((m) => (m.status === "pending" ? decrypt(m.model) : Promise.resolve(m)))).then((next) => {
             if (alive)
                 setMessages(next);
         });

package/dist/esm/hooks/useSecureMessages.js.map

@@ -1 +1 @@
-{"version":3,"file":"useSecureMessages.js","sourceRoot":"","sources":["../../../src/hooks/useSecureMessages.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"useSecureMessages.js","sourceRoot":"","sources":["../../../src/hooks/useSecureMessages.tsx"],"names":[],"mappings":"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"}

package/dist/esm/hooks/useSecureSafetyNumber.d.ts

@@ -0,0 +1,30 @@
+import { type SafetyNumber } from "../util/safety-number.js";
+/** The state and actions returned by {@link useSecureSafetyNumber}. */
+export interface UseSecureSafetyNumberValues {
+    /** The derived safety number, or `null` until ready / when the conversation is not a resolvable DM. */
+    safetyNumber: SafetyNumber | null;
+    /** True while the number is being (re)computed. */
+    loading: boolean;
+    /** The last error from resolving the roster or computing, or `null`. */
+    error: unknown;
+    /** Force a recompute (e.g. after the user re-verifies). */
+    refresh: () => void;
+}
+/**
+ * Compute the out-of-band key-verification safety number for a direct-message conversation.
+ *
+ * Resolves the conversation's MLS group, reads its two members' public signature keys, and derives a
+ * symmetric {@link SafetyNumber}. Recomputes when the conversation's group handle advances (e.g. a
+ * processed Commit changes the roster). Returns `safetyNumber: null` when the group is unresolved or is
+ * not a 2-member DM.
+ *
+ * @param conversationId - The conversation to compute the safety number for.
+ * @returns {@link UseSecureSafetyNumberValues}.
+ *
+ * @example
+ * ```tsx
+ * const { safetyNumber } = useSecureSafetyNumber(conversationId);
+ * // render safetyNumber?.groups for the user to compare with their peer
+ * ```
+ */
+export declare function useSecureSafetyNumber(conversationId: string): UseSecureSafetyNumberValues;