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

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

@@ -1,7 +1,8 @@
-import { SecureDeviceModel } from "../contract";
+import { SecureDeviceModel } from "../contract/index.js";
 /** Options for {@link useSecureDevice}. */
 export interface UseSecureDeviceOptions {
-    /** Stable, persisted client device id. Generated if omitted (persist it in the platform layer). */
+    /** Stable, persisted client device id. Generated (and persisted) if omitted. A previously
+     *  persisted device's id takes precedence over this value when one exists on mount. */
     deviceId?: string;
     /** MLS ciphersuite to register under. Defaults to the crypto implementation's preferred suite. */
     ciphersuite?: number;
@@ -14,13 +15,15 @@ export interface UseSecureDeviceOptions {
 export interface UseSecureDeviceValues {
     /** The registered device row (its `.id` is the uuid used as targetDeviceId everywhere). */
     device: SecureDeviceModel | null;
+    /** True until the initial persisted-device load settles. */
+    loading: boolean;
     /** True while {@link UseSecureDeviceValues.register} is in flight. */
     registering: boolean;
-    /** The last error thrown by registration or replenishment, or `null`. */
+    /** The last error thrown by load, registration, or replenishment, or `null`. */
     error: unknown;
     /** Last known count of unconsumed KeyPackages, or `null` until refreshed. */
     keyPackagesAvailable: number | null;
-    /** Generate identity + register (idempotent server-side on (userId, deviceId)). */
+    /** Generate identity + register (idempotent server-side on (userId, deviceId)) and persist it. */
     register: () => Promise<SecureDeviceModel>;
     /** Generate + publish `count` fresh KeyPackages (default = keyPackageTarget). */
     publishKeyPackages: (count?: number) => Promise<number>;
@@ -28,20 +31,18 @@ export interface UseSecureDeviceValues {
     refreshKeyPackageCount: () => Promise<number>;
 }
 /**
- * Register this client as an MLS device (one device = one leaf) and keep its KeyPackages stocked.
+ * Register this client as an MLS device, persist its identity, and keep KeyPackages stocked.
  *
- * On {@link UseSecureDeviceValues.register} it generates a device identity, POSTs it to `/devices`,
- * and (when `autoReplenish` is on) republishes KeyPackages whenever the server emits
- * `secure:key-packages-low` for this device. The device's private key material must be persisted by
- * the platform layer — this hook only handles registration and relay.
+ * On mount it loads any persisted device and re-hydrates the crypto identity (stable id, no
+ * re-register). When none exists, await {@link UseSecureDeviceValues.register}.
  *
- * @param options - {@link UseSecureDeviceOptions} — device id, ciphersuite, and replenishment tuning.
- * @returns {@link UseSecureDeviceValues} — the device row, status flags, and register/publish actions.
+ * @param options - {@link UseSecureDeviceOptions}.
+ * @returns {@link UseSecureDeviceValues}.
  *
  * @example
  * ```tsx
- * const { device, register } = useSecureDevice({ keyPackageTarget: 20 });
- * useEffect(() => { register(); }, []);
+ * const { device, loading, register } = useSecureDevice();
+ * useEffect(() => { if (!loading && !device) register(); }, [loading, device, register]);
  * ```
  */
 export declare function useSecureDevice(options?: UseSecureDeviceOptions): UseSecureDeviceValues;

package/dist/esm/hooks/useSecureDevice.js

@@ -1,17 +1,15 @@
-// useSecureDevice — register this client as an MLS device (leaf) and keep its KeyPackages topped up.
+// useSecureDevice — register this client as an MLS device (leaf), persist its identity, and keep its
+// KeyPackages topped up.
 //
-// Flow (server spec §14): generateDeviceIdentity → POST /devices → publish a batch of KeyPackages;
-// replenish on the `secure:key-packages-low` realtime signal or via the count endpoint.
-//
-// NOTE: the device's PRIVATE state (`privateState` from generateDeviceIdentity, and MLS group
-// state) must be persisted by the platform layer (IndexedDB on web, keystore on native — Phase 2/3).
-// Core only performs registration + relay; it does not persist secrets.
+// 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.
 import { useCallback, useEffect, useRef, useState } from "react";
-import { toBase64 } from "../util/base64";
-import { useSecureChat } from "../context/secure-chat-context";
+import { toBase64 } from "../util/base64.js";
+import { useSecureChat } from "../context/secure-chat-context.js";
 /**
  * Mint a device id when the caller doesn't supply one — `crypto.randomUUID()` when available, else a
- * non-cryptographic timestamp+random fallback. The platform layer should supply a persisted id.
+ * non-cryptographic timestamp+random fallback.
  *
  * @returns A fresh device id string.
  */
@@ -19,34 +17,64 @@ function newDeviceId() {
     const g = globalThis.crypto;
     if (g?.randomUUID)
         return g.randomUUID();
-    // Platform layer should supply a persisted, stable device id; this is a non-crypto fallback.
     return `dev-${Date.now().toString(36)}-${Math.floor(Math.random() * 1e9).toString(36)}`;
 }
 /**
- * Register this client as an MLS device (one device = one leaf) and keep its KeyPackages stocked.
+ * Register this client as an MLS device, persist its identity, and keep KeyPackages stocked.
  *
- * On {@link UseSecureDeviceValues.register} it generates a device identity, POSTs it to `/devices`,
- * and (when `autoReplenish` is on) republishes KeyPackages whenever the server emits
- * `secure:key-packages-low` for this device. The device's private key material must be persisted by
- * the platform layer — this hook only handles registration and relay.
+ * On mount it loads any persisted device and re-hydrates the crypto identity (stable id, no
+ * re-register). When none exists, await {@link UseSecureDeviceValues.register}.
  *
- * @param options - {@link UseSecureDeviceOptions} — device id, ciphersuite, and replenishment tuning.
- * @returns {@link UseSecureDeviceValues} — the device row, status flags, and register/publish actions.
+ * @param options - {@link UseSecureDeviceOptions}.
+ * @returns {@link UseSecureDeviceValues}.
  *
  * @example
  * ```tsx
- * const { device, register } = useSecureDevice({ keyPackageTarget: 20 });
- * useEffect(() => { register(); }, []);
+ * const { device, loading, register } = useSecureDevice();
+ * useEffect(() => { if (!loading && !device) register(); }, [loading, device, register]);
  * ```
  */
 export function useSecureDevice(options = {}) {
-    const { crypto, rest, socket } = useSecureChat();
+    const { crypto, rest, socket, repo } = useSecureChat();
     const { ciphersuite, keyPackageTarget = 20, autoReplenish = true } = options;
     const [device, setDevice] = useState(null);
+    const [loading, setLoading] = useState(true);
     const [registering, setRegistering] = useState(false);
     const [error, setError] = useState(null);
     const [keyPackagesAvailable, setKeyPackagesAvailable] = useState(null);
     const deviceIdRef = useRef(options.deviceId ?? newDeviceId());
+    const registerStartedRef = useRef(false);
+    // On mount: re-hydrate a persisted device (stable id + private state). No persisted device ⇒
+    // first-run; the app calls register().
+    useEffect(() => {
+        let alive = true;
+        (async () => {
+            const persisted = await repo.loadDevice();
+            if (!alive || registerStartedRef.current) {
+                setLoading(false);
+                return;
+            }
+            if (persisted) {
+                await crypto.importDeviceState(persisted.deviceState);
+                // register() may have started during the await — don't overwrite its identity.
+                if (!alive || registerStartedRef.current) {
+                    setLoading(false);
+                    return;
+                }
+                deviceIdRef.current = persisted.deviceId;
+                setDevice(persisted.device);
+            }
+            setLoading(false);
+        })().catch((err) => {
+            if (!alive)
+                return;
+            setError(err);
+            setLoading(false);
+        });
+        return () => {
+            alive = false;
+        };
+    }, [repo, crypto]);
     const publishKeyPackages = useCallback(async (count = keyPackageTarget) => {
         if (!device)
             throw new Error("Register the device before publishing KeyPackages.");
@@ -69,6 +97,7 @@ export function useSecureDevice(options = {}) {
         return available;
     }, [rest, device]);
     const register = useCallback(async () => {
+        registerStartedRef.current = true;
         setRegistering(true);
         setError(null);
         try {
@@ -82,6 +111,9 @@ export function useSecureDevice(options = {}) {
                 credential: toBase64(identity.credential),
                 ciphersuite: identity.ciphersuite,
             });
+            const deviceState = await crypto.exportDeviceState();
+            await repo.saveDevice({ deviceId: identity.deviceId, deviceState, device: registered });
+            deviceIdRef.current = identity.deviceId;
             setDevice(registered);
             return registered;
         }
@@ -92,7 +124,7 @@ export function useSecureDevice(options = {}) {
         finally {
             setRegistering(false);
         }
-    }, [crypto, rest, ciphersuite]);
+    }, [crypto, rest, repo, ciphersuite]);
     // Auto-replenish on the server's low-water signal for this device.
     useEffect(() => {
         if (!autoReplenish || !device)
@@ -106,6 +138,7 @@ export function useSecureDevice(options = {}) {
     }, [autoReplenish, device, socket, publishKeyPackages]);
     return {
         device,
+        loading,
         registering,
         error,
         keyPackagesAvailable,

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

@@ -1 +1 @@
-{"version":3,"file":"useSecureDevice.js","sourceRoot":"","sources":["../../../src/hooks/useSecureDevice.tsx"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,EAAE;AACF,mGAAmG;AACnG,wFAAwF;AACxF,EAAE;AACF,8FAA8F;AAC9F,qGAAqG;AACrG,wEAAwE;AAExE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEjE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAE/D;;;;;GAKG;AACH,SAAS,WAAW;IAClB,MAAM,CAAC,GAAI,UAAyD,CAAC,MAAM,CAAC;IAC5E,IAAI,CAAC,EAAE,UAAU;QAAE,OAAO,CAAC,CAAC,UAAU,EAAE,CAAC;IACzC,6FAA6F;IAC7F,OAAO,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;AAC1F,CAAC;AAgCD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkC,EAAE;IAClE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,EAAE,CAAC;IACjD,MAAM,EAAE,WAAW,EAAE,gBAAgB,GAAG,EAAE,EAAE,aAAa,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAE7E,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAA2B,IAAI,CAAC,CAAC;IACrE,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IACtD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAU,IAAI,CAAC,CAAC;IAClD,MAAM,CAAC,oBAAoB,EAAE,uBAAuB,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAC;IAEtF,MAAM,WAAW,GAAG,MAAM,CAAS,OAAO,CAAC,QAAQ,IAAI,WAAW,EAAE,CAAC,CAAC;IAEtE,MAAM,kBAAkB,GAAG,WAAW,CACpC,KAAK,EAAE,QAAgB,gBAAgB,EAAmB,EAAE;QAC1D,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACnF,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;QACxD,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,EAAE;YACzD,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC/B,aAAa,EAAE,CAAC,CAAC,aAAa;gBAC9B,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC;gBAClC,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,SAAS,EAAE,CAAC,CAAC,SAAS;aACvB,CAAC,CAAC;SACJ,CAAC,CAAC;QACH,OAAO,SAAS,CAAC;IACnB,CAAC,EACD,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,gBAAgB,CAAC,CACzC,CAAC;IAEF,MAAM,sBAAsB,GAAG,WAAW,CAAC,KAAK,IAAqB,EAAE;QACrE,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QACtF,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACxD,uBAAuB,CAAC,SAAS,CAAC,CAAC;QACnC,OAAO,SAAS,CAAC;IACnB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAEnB,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,IAAgC,EAAE;QAClE,cAAc,CAAC,IAAI,CAAC,CAAC;QACrB,QAAQ,CAAC,IAAI,CAAC,CAAC;QACf,IAAI,CAAC;YACH,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC;gBACvD,QAAQ,EAAE,WAAW,CAAC,OAAO;gBAC7B,WAAW;aACZ,CAAC,CAAC;YACH,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC;gBAC3C,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBAC3B,kBAAkB,EAAE,QAAQ,CAAC,QAAQ,CAAC,kBAAkB,CAAC;gBACzD,UAAU,EAAE,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC;gBACzC,WAAW,EAAE,QAAQ,CAAC,WAAW;aAClC,CAAC,CAAC;YACH,SAAS,CAAC,UAAU,CAAC,CAAC;YACtB,OAAO,UAAU,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,GAAG,CAAC,CAAC;YACd,MAAM,GAAG,CAAC;QACZ,CAAC;gBAAS,CAAC;YACT,cAAc,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;IACH,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC;IAEhC,mEAAmE;IACnE,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,aAAa,IAAI,CAAC,MAAM;YAAE,OAAO;QACtC,MAAM,GAAG,GAAG,MAAM,CAAC,EAAE,CAAC,yBAAyB,EAAE,CAAC,MAAM,EAAE,EAAE;YAC1D,IAAI,MAAM,CAAC,QAAQ,KAAK,MAAM,CAAC,EAAE;gBAAE,OAAO;YAC1C,kBAAkB,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;QACH,OAAO,GAAG,CAAC;IACb,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAExD,OAAO;QACL,MAAM;QACN,WAAW;QACX,KAAK;QACL,oBAAoB;QACpB,QAAQ;QACR,kBAAkB;QAClB,sBAAsB;KACvB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"useSecureDevice.js","sourceRoot":"","sources":["../../../src/hooks/useSecureDevice.tsx"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,yBAAyB;AACzB,EAAE;AACF,kFAAkF;AAClF,sGAAsG;AACtG,6FAA6F;AAE7F,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEjE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAElE;;;;;GAKG;AACH,SAAS,WAAW;IAClB,MAAM,CAAC,GAAI,UAAyD,CAAC,MAAM,CAAC;IAC5E,IAAI,CAAC,EAAE,UAAU;QAAE,OAAO,CAAC,CAAC,UAAU,EAAE,CAAC;IACzC,OAAO,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;AAC1F,CAAC;AAmCD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkC,EAAE;IAClE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,aAAa,EAAE,CAAC;IACvD,MAAM,EAAE,WAAW,EAAE,gBAAgB,GAAG,EAAE,EAAE,aAAa,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAE7E,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAA2B,IAAI,CAAC,CAAC;IACrE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IACtD,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAU,IAAI,CAAC,CAAC;IAClD,MAAM,CAAC,oBAAoB,EAAE,uBAAuB,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAC;IAEtF,MAAM,WAAW,GAAG,MAAM,CAAS,OAAO,CAAC,QAAQ,IAAI,WAAW,EAAE,CAAC,CAAC;IACtE,MAAM,kBAAkB,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAEzC,6FAA6F;IAC7F,uCAAuC;IACvC,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,KAAK,GAAG,IAAI,CAAC;QACjB,CAAC,KAAK,IAAI,EAAE;YACV,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;YAC1C,IAAI,CAAC,KAAK,IAAI,kBAAkB,CAAC,OAAO,EAAE,CAAC;gBACzC,UAAU,CAAC,KAAK,CAAC,CAAC;gBAClB,OAAO;YACT,CAAC;YACD,IAAI,SAAS,EAAE,CAAC;gBACd,MAAM,MAAM,CAAC,iBAAiB,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;gBACtD,+EAA+E;gBAC/E,IAAI,CAAC,KAAK,IAAI,kBAAkB,CAAC,OAAO,EAAE,CAAC;oBACzC,UAAU,CAAC,KAAK,CAAC,CAAC;oBAClB,OAAO;gBACT,CAAC;gBACD,WAAW,CAAC,OAAO,GAAG,SAAS,CAAC,QAAQ,CAAC;gBACzC,SAAS,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YAC9B,CAAC;YACD,UAAU,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;YACjB,IAAI,CAAC,KAAK;gBAAE,OAAO;YACnB,QAAQ,CAAC,GAAG,CAAC,CAAC;YACd,UAAU,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC,CAAC,CAAC;QACH,OAAO,GAAG,EAAE;YACV,KAAK,GAAG,KAAK,CAAC;QAChB,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAEnB,MAAM,kBAAkB,GAAG,WAAW,CACpC,KAAK,EAAE,QAAgB,gBAAgB,EAAmB,EAAE;QAC1D,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACnF,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;QACxD,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,EAAE;YACzD,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC/B,aAAa,EAAE,CAAC,CAAC,aAAa;gBAC9B,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC;gBAClC,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,SAAS,EAAE,CAAC,CAAC,SAAS;aACvB,CAAC,CAAC;SACJ,CAAC,CAAC;QACH,OAAO,SAAS,CAAC;IACnB,CAAC,EACD,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,gBAAgB,CAAC,CACzC,CAAC;IAEF,MAAM,sBAAsB,GAAG,WAAW,CAAC,KAAK,IAAqB,EAAE;QACrE,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QACtF,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACxD,uBAAuB,CAAC,SAAS,CAAC,CAAC;QACnC,OAAO,SAAS,CAAC;IACnB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAEnB,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,IAAgC,EAAE;QAClE,kBAAkB,CAAC,OAAO,GAAG,IAAI,CAAC;QAClC,cAAc,CAAC,IAAI,CAAC,CAAC;QACrB,QAAQ,CAAC,IAAI,CAAC,CAAC;QACf,IAAI,CAAC;YACH,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC;gBACvD,QAAQ,EAAE,WAAW,CAAC,OAAO;gBAC7B,WAAW;aACZ,CAAC,CAAC;YACH,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC;gBAC3C,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBAC3B,kBAAkB,EAAE,QAAQ,CAAC,QAAQ,CAAC,kBAAkB,CAAC;gBACzD,UAAU,EAAE,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC;gBACzC,WAAW,EAAE,QAAQ,CAAC,WAAW;aAClC,CAAC,CAAC;YACH,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,iBAAiB,EAAE,CAAC;YACrD,MAAM,IAAI,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;YACxF,WAAW,CAAC,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC;YACxC,SAAS,CAAC,UAAU,CAAC,CAAC;YACtB,OAAO,UAAU,CAAC;QACpB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,GAAG,CAAC,CAAC;YACd,MAAM,GAAG,CAAC;QACZ,CAAC;gBAAS,CAAC;YACT,cAAc,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;IACH,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC;IAEtC,mEAAmE;IACnE,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,aAAa,IAAI,CAAC,MAAM;YAAE,OAAO;QACtC,MAAM,GAAG,GAAG,MAAM,CAAC,EAAE,CAAC,yBAAyB,EAAE,CAAC,MAAM,EAAE,EAAE;YAC1D,IAAI,MAAM,CAAC,QAAQ,KAAK,MAAM,CAAC,EAAE;gBAAE,OAAO;YAC1C,kBAAkB,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;QACH,OAAO,GAAG,CAAC;IACb,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAExD,OAAO;QACL,MAAM;QACN,OAAO;QACP,WAAW;QACX,KAAK;QACL,oBAAoB;QACpB,QAAQ;QACR,kBAAkB;QAClB,sBAAsB;KACvB,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,64 @@
+import { SecureHandshakeModel } from "../contract/index.js";
+/** Options for {@link useSecureHandshakes}. */
+export interface UseSecureHandshakesOptions {
+    /**
+     * The device row id whose inbox to drain. Defaults to the persisted device's `.id`. Pass the id
+     * from `useSecureDevice` so processing starts the moment the device registers (a persisted device
+     * is picked up automatically on reload even without this).
+     */
+    deviceId?: string;
+    /** Disable processing (e.g. before sign-in). Default true. */
+    enabled?: boolean;
+    /** Page size for the catch-up fetch loop. Default 100. */
+    pageSize?: number;
+    /** Called per handshake-processing error; the inbox skips the bad row and continues. */
+    onError?: (err: unknown, handshake?: SecureHandshakeModel) => void;
+}
+/** The state and actions returned by {@link useSecureHandshakes}. */
+export interface UseSecureHandshakesValues {
+    /** True until the initial catch-up loop settles. */
+    catchingUp: boolean;
+    /** True once catch-up completed and live subscriptions are active. */
+    ready: boolean;
+    /** The last processed delivery cursor (`seq`), or `null`. */
+    cursor: string | null;
+    /** Count of handshakes applied this session. */
+    processedCount: number;
+    /** The last error surfaced (also delivered via `onError`), or `null`. */
+    error: unknown;
+    /**
+     * Re-run the catch-up loop from the persisted cursor. The reusable primitive a future 409
+     * epoch-conflict rebase (on a membership Commit) calls before rebuilding + retrying its Commit.
+     */
+    resync: () => Promise<void>;
+}
+/**
+ * Process this device's MLS handshake inbox so the recipient side of secure chat works.
+ *
+ * On mount (once a device id is available) it catches up via `fetchHandshakes(since=cursor)`, re-joins
+ * the socket rooms for groups it already holds, then processes live `secure:welcome` /
+ * `secure:handshake` events — all serialized in `seq` order, deduped, and cursor-persisted. Mount it
+ * exactly once near `useSecureDevice`.
+ *
+ * @param options - {@link UseSecureHandshakesOptions}.
+ * @returns {@link UseSecureHandshakesValues}.
+ *
+ * @remarks
+ * Single-device only (Phase 3 adds own-device fan-out + MLS generation-counter gap detection). A
+ * Commit for a group whose Welcome hasn't been seen is skipped — `seq` ordering puts the Welcome
+ * first, so an unknown group means this device is genuinely not a member.
+ *
+ * Mount it exactly once. Processing is serialized *within* a mount, and the cursor is re-read from
+ * storage at the start of each run, so a serialized re-mount (or `deviceId` change) resumes without
+ * reprocessing. It does NOT serialize across a *concurrent* re-mount whose prior catch-up is still
+ * in flight; that case relies on `processWelcome` / `processCommit` being idempotent for a replayed
+ * blob. The mock is idempotent (so dev StrictMode double-invoke is harmless); harden this when the
+ * real MLS core lands (Task 1) if its handshake processing is not replay-safe.
+ *
+ * @example
+ * ```tsx
+ * const { device } = useSecureDevice();
+ * useSecureHandshakes({ deviceId: device?.id });
+ * ```
+ */
+export declare function useSecureHandshakes(options?: UseSecureHandshakesOptions): UseSecureHandshakesValues;

package/dist/esm/hooks/useSecureHandshakes.js

@@ -0,0 +1,212 @@
+// useSecureHandshakes — drain and process this device's MLS handshake inbox (the recipient side).
+//
+// The blind DS delivers each device a stream of handshakes (Welcomes targeted at it, plus broadcast
+// Commits/Proposals for its groups), ordered by a monotonic `seq`. This hook is what makes a
+// RECIPIENT actually join and stay current: on connect it pulls `GET .../handshakes?since=<cursor>`
+// to the end, then processes live `secure:welcome` / `secure:handshake` events — all funneled through
+// ONE serialized, seq-ordered, idempotent path, persisting the cursor as it goes. A processed Welcome
+// joins a group (rememberGroup); a processed Commit advances its epoch. Mount it once, near
+// useSecureDevice.
+//
+// Ordering invariant: live events that arrive WHILE catching up are buffered and replayed in `seq`
+// order AFTER catch-up — otherwise a high-seq live event would advance the cursor past not-yet-fetched
+// rows and the dedupe check would drop them (data loss).
+import { useCallback, useEffect, useRef, useState } from "react";
+import { fromBase64 } from "../util/base64.js";
+import { useSecureChat } from "../context/secure-chat-context.js";
+/** Compare two decimal-string `seq` cursors numerically (string compare is wrong across digit widths). */
+function compareSeq(a, b) {
+    const d = BigInt(a) - BigInt(b);
+    return d > 0n ? 1 : d < 0n ? -1 : 0;
+}
+/**
+ * Process this device's MLS handshake inbox so the recipient side of secure chat works.
+ *
+ * On mount (once a device id is available) it catches up via `fetchHandshakes(since=cursor)`, re-joins
+ * the socket rooms for groups it already holds, then processes live `secure:welcome` /
+ * `secure:handshake` events — all serialized in `seq` order, deduped, and cursor-persisted. Mount it
+ * exactly once near `useSecureDevice`.
+ *
+ * @param options - {@link UseSecureHandshakesOptions}.
+ * @returns {@link UseSecureHandshakesValues}.
+ *
+ * @remarks
+ * Single-device only (Phase 3 adds own-device fan-out + MLS generation-counter gap detection). A
+ * Commit for a group whose Welcome hasn't been seen is skipped — `seq` ordering puts the Welcome
+ * first, so an unknown group means this device is genuinely not a member.
+ *
+ * Mount it exactly once. Processing is serialized *within* a mount, and the cursor is re-read from
+ * storage at the start of each run, so a serialized re-mount (or `deviceId` change) resumes without
+ * reprocessing. It does NOT serialize across a *concurrent* re-mount whose prior catch-up is still
+ * in flight; that case relies on `processWelcome` / `processCommit` being idempotent for a replayed
+ * blob. The mock is idempotent (so dev StrictMode double-invoke is harmless); harden this when the
+ * real MLS core lands (Task 1) if its handshake processing is not replay-safe.
+ *
+ * @example
+ * ```tsx
+ * const { device } = useSecureDevice();
+ * useSecureHandshakes({ deviceId: device?.id });
+ * ```
+ */
+export function useSecureHandshakes(options = {}) {
+    const { rest, crypto, socket, repo, resolveGroup, rememberGroup } = useSecureChat();
+    const { deviceId: deviceIdOption, pageSize = 100 } = options;
+    const enabled = options.enabled ?? true;
+    const [catchingUp, setCatchingUp] = useState(true);
+    const [ready, setReady] = useState(false);
+    const [cursor, setCursor] = useState(null);
+    const [processedCount, setProcessedCount] = useState(0);
+    const [error, setError] = useState(null);
+    // onError read through a ref so passing an inline callback doesn't re-run the effect.
+    const onErrorRef = useRef(options.onError);
+    onErrorRef.current = options.onError;
+    // The catch-up routine, published from the effect so `resync()` (stable) can invoke it.
+    const runCatchUpRef = useRef(null);
+    const resync = useCallback(async () => {
+        await runCatchUpRef.current?.();
+    }, []);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        let alive = true;
+        const offFns = [];
+        // Async state shared across the catch-up loop, live handlers, and the serial apply queue.
+        const cursorRef = { current: null };
+        const catchingUpRef = { current: true };
+        const liveBuffer = [];
+        let queue = Promise.resolve();
+        let deviceId;
+        const report = (err, h) => {
+            if (alive)
+                setError(err);
+            onErrorRef.current?.(err, h);
+        };
+        const dispatchByKind = async (h) => {
+            const payload = fromBase64(h.payload);
+            if (h.kind === "welcome") {
+                // Targeted at us → join the group, then join its room for future broadcast Commits.
+                if (h.targetDeviceId && h.targetDeviceId !== deviceId)
+                    return;
+                const handle = await crypto.processWelcome(payload);
+                await rememberGroup(h.conversationId, handle);
+                socket.joinConversation(h.conversationId);
+            }
+            else if (h.kind === "commit") {
+                const group = await resolveGroup(h.conversationId);
+                if (!group) {
+                    // Unknown group at a Commit: with seq ordering the Welcome precedes it, so we're not a
+                    // member of this conversation. Skip (the cursor still advances so we don't re-fetch it).
+                    report(new Error(`secure-chat: commit for unknown group ${h.conversationId}`), h);
+                    return;
+                }
+                const advanced = await crypto.processCommit(group, payload);
+                await rememberGroup(h.conversationId, advanced);
+            }
+            else if (h.kind === "proposal") {
+                const group = await resolveGroup(h.conversationId);
+                if (group)
+                    await crypto.processProposal(group, payload);
+            }
+        };
+        // The ONE place that mutates the cursor + crypto state. Dedupes by seq; advances the cursor even
+        // when a row is skipped or its dispatch throws, so a poison blob can never wedge the inbox. A hard
+        // crash mid-dispatch leaves the cursor unsaved, so the row replays on restart (no loss).
+        const applyOrdered = async (h) => {
+            if (cursorRef.current !== null && compareSeq(h.seq, cursorRef.current) <= 0)
+                return;
+            try {
+                await dispatchByKind(h);
+            }
+            catch (err) {
+                report(err, h);
+            }
+            cursorRef.current = h.seq;
+            await repo.saveHandshakeCursor(h.seq);
+            if (alive) {
+                setCursor(h.seq);
+                setProcessedCount((n) => n + 1);
+            }
+        };
+        const schedule = (h) => {
+            queue = queue.then(() => applyOrdered(h));
+            return queue;
+        };
+        const enqueueLive = (h) => {
+            // Buffer while catching up so a high-seq live event can't advance the cursor past rows the
+            // catch-up loop hasn't fetched yet (which the dedupe check would then drop).
+            if (catchingUpRef.current)
+                liveBuffer.push(h);
+            else
+                schedule(h);
+        };
+        // Coalesce overlapping invocations: a `resync()` fired while a catch-up is still draining returns
+        // the in-flight promise instead of starting a second drain (two drains would race the
+        // `catchingUpRef` gate + `liveBuffer` and could break seq ordering).
+        let catchUpInFlight = null;
+        const runCatchUp = () => {
+            if (catchUpInFlight)
+                return catchUpInFlight;
+            catchUpInFlight = (async () => {
+                catchingUpRef.current = true;
+                try {
+                    for (;;) {
+                        const page = await rest.fetchHandshakes(deviceId, {
+                            since: cursorRef.current ?? undefined,
+                            limit: pageSize,
+                        });
+                        for (const h of page.handshakes)
+                            await schedule(h);
+                        if (!page.hasMore)
+                            break;
+                    }
+                }
+                finally {
+                    catchingUpRef.current = false;
+                    // Replay anything that landed live during catch-up, in seq order, through the same queue.
+                    const buffered = liveBuffer.splice(0).sort((a, b) => compareSeq(a.seq, b.seq));
+                    for (const h of buffered)
+                        schedule(h);
+                }
+            })().finally(() => {
+                catchUpInFlight = null;
+            });
+            return catchUpInFlight;
+        };
+        (async () => {
+            // Resolve the device row id (option wins; else the persisted device). Without one, there is no
+            // inbox to drain yet — the effect re-runs when `deviceId` is later supplied.
+            deviceId = deviceIdOption ?? (await repo.loadDevice())?.device?.id;
+            if (!alive || !deviceId)
+                return;
+            cursorRef.current = await repo.loadHandshakeCursor();
+            if (alive)
+                setCursor(cursorRef.current);
+            // Subscribe to live events BEFORE catch-up (buffered until catch-up completes).
+            offFns.push(socket.on("secure:welcome", enqueueLive));
+            offFns.push(socket.on("secure:handshake", enqueueLive));
+            runCatchUpRef.current = runCatchUp;
+            await runCatchUp();
+            // After a reload we hold group state but haven't joined the socket rooms, so broadcast Commits
+            // wouldn't arrive — re-join every known conversation.
+            try {
+                const convIds = await repo.listGroupConversationIds();
+                for (const c of convIds)
+                    socket.joinConversation(c);
+            }
+            catch (err) {
+                report(err);
+            }
+            if (alive) {
+                setCatchingUp(false);
+                setReady(true);
+            }
+        })().catch((err) => report(err));
+        return () => {
+            alive = false;
+            offFns.forEach((off) => off());
+            runCatchUpRef.current = null;
+        };
+    }, [enabled, deviceIdOption, pageSize, rest, socket, repo, crypto, resolveGroup, rememberGroup]);
+    return { catchingUp, ready, cursor, processedCount, error, resync };
+}
+//# sourceMappingURL=useSecureHandshakes.js.map

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

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

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

@@ -1,4 +1,4 @@
-import { SecureMessageModel } from "../contract";
+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). */
 export interface DecryptedSecureMessage {
@@ -9,9 +9,9 @@ export interface DecryptedSecureMessage {
 }
 /** Options for {@link useSecureMessages}. */
 export interface UseSecureMessagesOptions {
-    /** The MLS group handle for this conversation (from the platform persistence layer). */
+    /** Override the MLS group handle. Defaults to the persisted handle via `resolveGroup`. */
     group?: GroupHandle;
-    /** The caller's device row id — required to send (the server verifies it belongs to the caller). */
+    /** Override the sender device row id. Defaults to the persisted device's `.id`. */
     senderDeviceId?: string;
 }
 /** The state and actions returned by {@link useSecureMessages}. */
@@ -28,24 +28,23 @@ export interface UseSecureMessagesValues {
     loadMore: () => Promise<void>;
     /** Reload from the newest message, replacing the current list. */
     refresh: () => Promise<void>;
-    /** Encrypt + send a text message. Requires `group` + `senderDeviceId`. */
+    /** Encrypt + send a text message. Requires a resolvable group + sender device. */
     sendMessage: (text: string) => Promise<void>;
 }
 /**
  * Load, decrypt, send, and live-receive messages in one secure conversation.
  *
- * Decryption runs through the injected `SecureChatCrypto` against the conversation's MLS
- * `GroupHandle`. Without a `group` in `options`, ciphertext is still listed and received (as
- * `plaintext: null`) and sending is disabled — letting the transport work ahead of the crypto
- * wiring. Joins the conversation's socket room to receive `secure:message` events live.
+ * Auto-resolves the MLS group handle (via `resolveGroup`) and the sender device id (from the
+ * persisted device) unless overridden in `options`. Joins the conversation socket room for live
+ * `secure:message` events.
  *
  * @param conversationId - The conversation to read and send within.
- * @param options - {@link UseSecureMessagesOptions} — the MLS `group` handle and `senderDeviceId`.
- * @returns {@link UseSecureMessagesValues} — the message list, paging state, and `sendMessage`.
+ * @param options - {@link UseSecureMessagesOptions}.
+ * @returns {@link UseSecureMessagesValues}.
  *
  * @example
  * ```tsx
- * const { messages, sendMessage } = useSecureMessages(conversationId, { group, senderDeviceId });
+ * const { messages, sendMessage } = useSecureMessages(conversationId);
  * await sendMessage("hello 💜");
  * ```
  */