@agora-sdk/secure-chat-core 0.1.0

package/dist/esm/contract/index.d.ts

@@ -0,0 +1,150 @@
+export type SecureConversationType = "dm" | "group" | "channel";
+export type SecureMemberRole = "admin" | "member";
+export type SecureHandshakeKind = "welcome" | "commit" | "proposal";
+/** A Welcome targeted at the ONE device whose claimed KeyPackage was consumed. */
+export interface WelcomeEnvelope {
+    targetDeviceId: string;
+    payload: string;
+    epoch: string;
+}
+/** A Commit/Proposal broadcast to the whole group (no target device). */
+export interface HandshakeBlob {
+    payload: string;
+    epoch: string;
+}
+export interface RegisterDeviceBody {
+    deviceId: string;
+    displayName?: string | null;
+    signaturePublicKey: string;
+    credential: string;
+    ciphersuite: number;
+}
+export interface PublishKeyPackagesBody {
+    keyPackages: {
+        keyPackageRef: string;
+        keyPackage: string;
+        ciphersuite: number;
+        expiresAt?: string | null;
+    }[];
+}
+export interface CreateSecureConversationBody {
+    type: SecureConversationType;
+    mlsGroupId: string;
+    spaceId?: string | null;
+    name?: string | null;
+    memberUserIds?: string[];
+    welcomes?: WelcomeEnvelope[];
+}
+export interface AddSecureMemberBody {
+    userId: string;
+    commit: HandshakeBlob;
+    welcomes: WelcomeEnvelope[];
+}
+export interface RemoveSecureMemberBody {
+    commit: HandshakeBlob;
+}
+export interface SendSecureMessageBody {
+    ciphertext: string;
+    epoch: string;
+    senderDeviceId: string;
+    contentType?: string | null;
+}
+export interface UploadKeyBackupBody {
+    deviceId?: string | null;
+    blob: string;
+    nonce: string;
+    kdf: "argon2id" | "pbkdf2";
+    kdfParams: Record<string, unknown>;
+    cipher: "xchacha20poly1305" | "aes-256-gcm";
+    version: number;
+}
+export interface SecureDeviceModel {
+    id: string;
+    projectId: string;
+    userId: string;
+    deviceId: string;
+    displayName: string | null;
+    signaturePublicKey: string;
+    credential: string;
+    ciphersuite: number;
+    revokedAt: string | null;
+    lastSeenAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface SecureKeyPackageClaim {
+    deviceId: string;
+    keyPackageRef: string;
+    keyPackage: string;
+    ciphersuite: number;
+}
+export interface SecureConversationMemberModel {
+    id: string;
+    projectId: string;
+    conversationId: string;
+    userId: string;
+    role: SecureMemberRole;
+    isActive: boolean;
+    joinedAtEpoch: string | null;
+    lastReadAt: string | null;
+    leftAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface SecureConversationModel {
+    id: string;
+    projectId: string;
+    type: SecureConversationType;
+    mlsGroupId: string;
+    spaceId: string | null;
+    currentEpoch: string;
+    name: string | null;
+    createdById: string | null;
+    lastMessageAt: string | null;
+    memberCount?: number;
+    unreadCount?: number;
+    currentMember?: SecureConversationMemberModel;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface SecureMessageModel {
+    id: string;
+    projectId: string;
+    conversationId: string;
+    senderUserId: string | null;
+    senderDeviceId: string | null;
+    epoch: string;
+    ciphertext: string;
+    contentType: string;
+    createdAt: string;
+}
+export interface SecureHandshakeModel {
+    id: string;
+    seq: string;
+    kind: SecureHandshakeKind;
+    conversationId: string;
+    epoch: string;
+    payload: string;
+    senderDeviceId: string | null;
+    targetDeviceId: string | null;
+}
+export interface SecureKeyBackupModel {
+    id: string;
+    projectId: string;
+    userId: string;
+    deviceId: string | null;
+    blob: string;
+    nonce: string;
+    kdf: string;
+    kdfParams: Record<string, unknown>;
+    cipher: string;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Standard error envelope: `{ error, code, field? }` with `secure-chat/*` codes. */
+export interface SecureChatErrorBody {
+    error: string;
+    code: string;
+    field?: string;
+}

package/dist/esm/contract/index.js

@@ -0,0 +1,15 @@
+// Secure-chat wire contract — stand-in for @agora/contract (the Apache-2.0 server contract).
+//
+// Mirrors the response models + request bodies of agora-server's
+// `packages/contract/src/secure-chat.ts`. That package is the source of truth (zod + TS); the
+// client only needs the TypeScript shapes, so this copy is types-only.
+//
+// ⚠️ Keep this byte-faithful to the server contract. The arrow is SDK → contract: once
+// `@agora/contract` is published, DELETE this file and `import type { ... } from "@agora/contract"`.
+// Do NOT publish a separate `@agora-sdk/secure-chat-contract` (that would invert the dependency —
+// see STATUS.md). Do not let this copy drift in the meantime.
+//
+// Wire conventions: every binary value is **base64** (the server stores/relays opaque blobs and
+// never parses them); MLS epochs are **decimal strings** (u64 exceeds JS safe-int range).
+export {};
+//# sourceMappingURL=index.js.map

package/dist/esm/contract/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/contract/index.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,EAAE;AACF,iEAAiE;AACjE,8FAA8F;AAC9F,uEAAuE;AACvE,EAAE;AACF,uFAAuF;AACvF,qGAAqG;AACrG,kGAAkG;AAClG,8DAA8D;AAC9D,EAAE;AACF,gGAAgG;AAChG,0FAA0F"}

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

@@ -0,0 +1,35 @@
+import { SecureConversationModel } from "../contract";
+/** The state and actions returned by {@link useSecureConversations}. */
+export interface UseSecureConversationsValues {
+    /** The loaded conversations, newest activity first. */
+    conversations: SecureConversationModel[];
+    /** True while a page load or refresh is in flight. */
+    loading: boolean;
+    /** Whether more pages remain to {@link UseSecureConversationsValues.loadMore}. */
+    hasMore: boolean;
+    /** The last error thrown by loading or conversation creation, or `null`. */
+    error: unknown;
+    /** Append the next page of older conversations. No-op when already loading or exhausted. */
+    loadMore: () => Promise<void>;
+    /** Reload from the top, replacing the current list. */
+    refresh: () => Promise<void>;
+    /** Start (or surface) a 1:1 conversation with another user across all their devices. */
+    createDirectConversation: (peerUserId: string) => Promise<SecureConversationModel>;
+}
+/**
+ * List the caller's secure conversations and start new direct messages.
+ *
+ * Refreshes on mount and on `secure:member:joined` / `secure:member:left` signals.
+ * {@link UseSecureConversationsValues.createDirectConversation} claims one KeyPackage per peer
+ * device, builds the MLS group locally, and registers it on the blind DS with targeted Welcomes —
+ * the group secrets never leave the client.
+ *
+ * @returns {@link UseSecureConversationsValues} — the conversation list, paging state, and actions.
+ *
+ * @example
+ * ```tsx
+ * const { conversations, createDirectConversation } = useSecureConversations();
+ * await createDirectConversation(peerUserId);
+ * ```
+ */
+export declare function useSecureConversations(): UseSecureConversationsValues;

package/dist/esm/hooks/useSecureConversations.js

@@ -0,0 +1,106 @@
+// useSecureConversations — list the caller's secure conversations and start new DMs.
+//
+// Starting a DM (server spec §14.3): claim each peer device's KeyPackage → createGroup locally →
+// POST /conversations with the Welcomes targeted to each peer device. The MLS group secrets stay on
+// the client; the server only stores ciphertext metadata.
+import { useCallback, useEffect, useState } from "react";
+import { toBase64, fromBase64 } from "../util/base64";
+import { useSecureChat } from "../context/secure-chat-context";
+/**
+ * List the caller's secure conversations and start new direct messages.
+ *
+ * Refreshes on mount and on `secure:member:joined` / `secure:member:left` signals.
+ * {@link UseSecureConversationsValues.createDirectConversation} claims one KeyPackage per peer
+ * device, builds the MLS group locally, and registers it on the blind DS with targeted Welcomes —
+ * the group secrets never leave the client.
+ *
+ * @returns {@link UseSecureConversationsValues} — the conversation list, paging state, and actions.
+ *
+ * @example
+ * ```tsx
+ * const { conversations, createDirectConversation } = useSecureConversations();
+ * await createDirectConversation(peerUserId);
+ * ```
+ */
+export function useSecureConversations() {
+    const { rest, crypto, socket } = useSecureChat();
+    const [conversations, setConversations] = useState([]);
+    const [cursor, setCursor] = useState(undefined);
+    const [hasMore, setHasMore] = useState(true);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const load = useCallback(async (reset) => {
+        setLoading(true);
+        setError(null);
+        try {
+            const page = await rest.listConversations({
+                cursor: reset ? undefined : cursor,
+                limit: 30,
+            });
+            const last = page.conversations[page.conversations.length - 1];
+            setCursor(last ? last.lastMessageAt ?? last.createdAt : cursor);
+            setHasMore(page.hasMore);
+            setConversations((prev) => (reset ? page.conversations : [...prev, ...page.conversations]));
+        }
+        catch (err) {
+            setError(err);
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [rest, cursor]);
+    const refresh = useCallback(async () => {
+        setCursor(undefined);
+        await load(true);
+    }, [load]);
+    const loadMore = useCallback(async () => {
+        if (!hasMore || loading)
+            return;
+        await load(false);
+    }, [hasMore, loading, load]);
+    const createDirectConversation = useCallback(async (peerUserId) => {
+        // 1. Discover the peer's active devices and claim one KeyPackage per device.
+        const peerDevices = await rest.listDevices(peerUserId);
+        if (peerDevices.length === 0) {
+            throw new Error("Peer has no registered secure-chat devices.");
+        }
+        const initialMembers = await Promise.all(peerDevices.map(async (d) => {
+            const claim = await rest.claimKeyPackage(d.id);
+            return { deviceId: d.id, keyPackage: fromBase64(claim.keyPackage) };
+        }));
+        // 2. Create the MLS group locally; the crypto layer holds the secrets.
+        const { group, welcomes } = await crypto.createGroup({ initialMembers });
+        // 3. Register the conversation on the blind DS, relaying the targeted Welcomes.
+        const conversation = await rest.createConversation({
+            type: "dm",
+            mlsGroupId: toBase64(group.mlsGroupId),
+            memberUserIds: [peerUserId],
+            welcomes: welcomes.map((w) => ({
+                targetDeviceId: w.targetDeviceId,
+                payload: toBase64(w.payload),
+                epoch: group.epoch.toString(),
+            })),
+        });
+        setConversations((prev) => [conversation, ...prev.filter((c) => c.id !== conversation.id)]);
+        return conversation;
+    }, [rest, crypto]);
+    useEffect(() => {
+        refresh();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // Light realtime refresh on membership changes (metadata-only signals).
+    useEffect(() => {
+        const offJoined = socket.on("secure:member:joined", () => {
+            refresh().catch(setError);
+        });
+        const offLeft = socket.on("secure:member:left", () => {
+            refresh().catch(setError);
+        });
+        return () => {
+            offJoined();
+            offLeft();
+        };
+    }, [socket, refresh]);
+    return { conversations, loading, hasMore, error, loadMore, refresh, createDirectConversation };
+}
+//# sourceMappingURL=useSecureConversations.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useSecureConversations.js","sourceRoot":"","sources":["../../../src/hooks/useSecureConversations.tsx"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,EAAE;AACF,iGAAiG;AACjG,oGAAoG;AACpG,0DAA0D;AAE1D,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEzD,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAoB/D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,sBAAsB;IACpC,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,aAAa,EAAE,CAAC;IAEjD,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC,GAAG,QAAQ,CAA4B,EAAE,CAAC,CAAC;IAClF,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAqB,SAAS,CAAC,CAAC;IACpE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC9C,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAAU,IAAI,CAAC,CAAC;IAElD,MAAM,IAAI,GAAG,WAAW,CACtB,KAAK,EAAE,KAAc,EAAE,EAAE;QACvB,UAAU,CAAC,IAAI,CAAC,CAAC;QACjB,QAAQ,CAAC,IAAI,CAAC,CAAC;QACf,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC;gBACxC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM;gBAClC,KAAK,EAAE,EAAE;aACV,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAC/D,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YAChE,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACzB,gBAAgB,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;QAC9F,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,GAAG,CAAC,CAAC;QAChB,CAAC;gBAAS,CAAC;YACT,UAAU,CAAC,KAAK,CAAC,CAAC;QACpB,CAAC;IACH,CAAC,EACD,CAAC,IAAI,EAAE,MAAM,CAAC,CACf,CAAC;IAEF,MAAM,OAAO,GAAG,WAAW,CAAC,KAAK,IAAI,EAAE;QACrC,SAAS,CAAC,SAAS,CAAC,CAAC;QACrB,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAEX,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,IAAI,EAAE;QACtC,IAAI,CAAC,OAAO,IAAI,OAAO;YAAE,OAAO;QAChC,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC;IACpB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;IAE7B,MAAM,wBAAwB,GAAG,WAAW,CAC1C,KAAK,EAAE,UAAkB,EAAoC,EAAE;QAC7D,6EAA6E;QAC7E,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;QACvD,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;QACjE,CAAC;QACD,MAAM,cAAc,GAAG,MAAM,OAAO,CAAC,GAAG,CACtC,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;YAC1B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAC/C,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;QACtE,CAAC,CAAC,CACH,CAAC;QAEF,uEAAuE;QACvE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC;QAEzE,gFAAgF;QAChF,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC;YACjD,IAAI,EAAE,IAAI;YACV,UAAU,EAAE,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC;YACtC,aAAa,EAAE,CAAC,UAAU,CAAC;YAC3B,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC7B,cAAc,EAAE,CAAC,CAAC,cAAc;gBAChC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC;gBAC5B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE;aAC9B,CAAC,CAAC;SACJ,CAAC,CAAC;QAEH,gBAAgB,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC5F,OAAO,YAAY,CAAC;IACtB,CAAC,EACD,CAAC,IAAI,EAAE,MAAM,CAAC,CACf,CAAC;IAEF,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,EAAE,CAAC;QACV,uDAAuD;IACzD,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,wEAAwE;IACxE,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,SAAS,GAAG,MAAM,CAAC,EAAE,CAAC,sBAAsB,EAAE,GAAG,EAAE;YACvD,OAAO,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC5B,CAAC,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,CAAC,EAAE,CAAC,oBAAoB,EAAE,GAAG,EAAE;YACnD,OAAO,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC5B,CAAC,CAAC,CAAC;QACH,OAAO,GAAG,EAAE;YACV,SAAS,EAAE,CAAC;YACZ,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEtB,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,wBAAwB,EAAE,CAAC;AACjG,CAAC"}

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

@@ -0,0 +1,47 @@
+import { SecureDeviceModel } from "../contract";
+/** Options for {@link useSecureDevice}. */
+export interface UseSecureDeviceOptions {
+    /** Stable, persisted client device id. Generated if omitted (persist it in the platform layer). */
+    deviceId?: string;
+    /** MLS ciphersuite to register under. Defaults to the crypto implementation's preferred suite. */
+    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. */
+    autoReplenish?: boolean;
+}
+/** The state and actions returned by {@link useSecureDevice}. */
+export interface UseSecureDeviceValues {
+    /** The registered device row (its `.id` is the uuid used as targetDeviceId everywhere). */
+    device: SecureDeviceModel | null;
+    /** True while {@link UseSecureDeviceValues.register} is in flight. */
+    registering: boolean;
+    /** The last error thrown by 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)). */
+    register: () => Promise<SecureDeviceModel>;
+    /** Generate + publish `count` fresh KeyPackages (default = keyPackageTarget). */
+    publishKeyPackages: (count?: number) => Promise<number>;
+    /** Re-query the server for the available KeyPackage count and update `keyPackagesAvailable`. */
+    refreshKeyPackageCount: () => Promise<number>;
+}
+/**
+ * Register this client as an MLS device (one device = one leaf) and keep its 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.
+ *
+ * @param options - {@link UseSecureDeviceOptions} — device id, ciphersuite, and replenishment tuning.
+ * @returns {@link UseSecureDeviceValues} — the device row, status flags, and register/publish actions.
+ *
+ * @example
+ * ```tsx
+ * const { device, register } = useSecureDevice({ keyPackageTarget: 20 });
+ * useEffect(() => { register(); }, []);
+ * ```
+ */
+export declare function useSecureDevice(options?: UseSecureDeviceOptions): UseSecureDeviceValues;

package/dist/esm/hooks/useSecureDevice.js

@@ -0,0 +1,117 @@
+// useSecureDevice — register this client as an MLS device (leaf) 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.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { toBase64 } from "../util/base64";
+import { useSecureChat } from "../context/secure-chat-context";
+/**
+ * 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.
+ *
+ * @returns A fresh device id string.
+ */
+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.
+ *
+ * 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.
+ *
+ * @param options - {@link UseSecureDeviceOptions} — device id, ciphersuite, and replenishment tuning.
+ * @returns {@link UseSecureDeviceValues} — the device row, status flags, and register/publish actions.
+ *
+ * @example
+ * ```tsx
+ * const { device, register } = useSecureDevice({ keyPackageTarget: 20 });
+ * useEffect(() => { register(); }, []);
+ * ```
+ */
+export function useSecureDevice(options = {}) {
+    const { crypto, rest, socket } = useSecureChat();
+    const { ciphersuite, keyPackageTarget = 20, autoReplenish = true } = options;
+    const [device, setDevice] = useState(null);
+    const [registering, setRegistering] = useState(false);
+    const [error, setError] = useState(null);
+    const [keyPackagesAvailable, setKeyPackagesAvailable] = useState(null);
+    const deviceIdRef = useRef(options.deviceId ?? newDeviceId());
+    const publishKeyPackages = useCallback(async (count = keyPackageTarget) => {
+        if (!device)
+            throw new Error("Register the device before publishing KeyPackages.");
+        const bundles = await crypto.generateKeyPackages(count);
+        const published = await rest.publishKeyPackages(device.id, {
+            keyPackages: bundles.map((b) => ({
+                keyPackageRef: b.keyPackageRef,
+                keyPackage: toBase64(b.keyPackage),
+                ciphersuite: b.ciphersuite,
+                expiresAt: b.expiresAt,
+            })),
+        });
+        return published;
+    }, [crypto, rest, device, keyPackageTarget]);
+    const refreshKeyPackageCount = useCallback(async () => {
+        if (!device)
+            throw new Error("Register the device before checking KeyPackage count.");
+        const available = await rest.keyPackageCount(device.id);
+        setKeyPackagesAvailable(available);
+        return available;
+    }, [rest, device]);
+    const register = useCallback(async () => {
+        setRegistering(true);
+        setError(null);
+        try {
+            const { identity } = await crypto.generateDeviceIdentity({
+                deviceId: deviceIdRef.current,
+                ciphersuite,
+            });
+            const registered = await rest.registerDevice({
+                deviceId: identity.deviceId,
+                signaturePublicKey: toBase64(identity.signaturePublicKey),
+                credential: toBase64(identity.credential),
+                ciphersuite: identity.ciphersuite,
+            });
+            setDevice(registered);
+            return registered;
+        }
+        catch (err) {
+            setError(err);
+            throw err;
+        }
+        finally {
+            setRegistering(false);
+        }
+    }, [crypto, rest, ciphersuite]);
+    // Auto-replenish on the server's low-water signal for this device.
+    useEffect(() => {
+        if (!autoReplenish || !device)
+            return;
+        const off = socket.on("secure:key-packages-low", (signal) => {
+            if (signal.deviceId !== device.id)
+                return;
+            publishKeyPackages().catch(setError);
+        });
+        return off;
+    }, [autoReplenish, device, socket, publishKeyPackages]);
+    return {
+        device,
+        registering,
+        error,
+        keyPackagesAvailable,
+        register,
+        publishKeyPackages,
+        refreshKeyPackageCount,
+    };
+}
+//# sourceMappingURL=useSecureDevice.js.map

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

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

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

@@ -0,0 +1,52 @@
+import { SecureMessageModel } from "../contract";
+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 {
+    /** 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. */
+    plaintext: string | null;
+}
+/** Options for {@link useSecureMessages}. */
+export interface UseSecureMessagesOptions {
+    /** The MLS group handle for this conversation (from the platform persistence layer). */
+    group?: GroupHandle;
+    /** The caller's device row id — required to send (the server verifies it belongs to the caller). */
+    senderDeviceId?: string;
+}
+/** The state and actions returned by {@link useSecureMessages}. */
+export interface UseSecureMessagesValues {
+    /** Loaded messages, newest first, each with decrypted text when possible. */
+    messages: DecryptedSecureMessage[];
+    /** True while a page load or refresh is in flight. */
+    loading: boolean;
+    /** Whether older messages remain to {@link UseSecureMessagesValues.loadMore}. */
+    hasMore: boolean;
+    /** The last error thrown by loading or sending, or `null`. */
+    error: unknown;
+    /** Append the next page of older messages. No-op when already loading or exhausted. */
+    loadMore: () => Promise<void>;
+    /** Reload from the newest message, replacing the current list. */
+    refresh: () => Promise<void>;
+    /** Encrypt + send a text message. Requires `group` + `senderDeviceId`. */
+    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.
+ *
+ * @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`.
+ *
+ * @example
+ * ```tsx
+ * const { messages, sendMessage } = useSecureMessages(conversationId, { group, senderDeviceId });
+ * await sendMessage("hello 💜");
+ * ```
+ */
+export declare function useSecureMessages(conversationId: string, options?: UseSecureMessagesOptions): UseSecureMessagesValues;

package/dist/esm/hooks/useSecureMessages.js

@@ -0,0 +1,110 @@
+// useSecureMessages — load, decrypt, send, and live-receive messages in a secure conversation.
+//
+// Encryption/decryption runs through the injected `SecureChatCrypto` against the conversation's MLS
+// `GroupHandle`. Resolving conversationId → GroupHandle is owned by the platform persistence layer
+// (Phase 2: IndexedDB group state via processWelcome/importGroupState), so the caller passes the
+// handle in. Without it, ciphertext is still listed/received but left undecrypted (`plaintext: null`)
+// and sending is disabled — keeping the transport usable ahead of the crypto wiring.
+import { useCallback, useEffect, useState } from "react";
+import { toBase64, fromBase64, utf8ToBytes, bytesToUtf8 } from "../util/base64";
+import { useSecureChat } from "../context/secure-chat-context";
+/**
+ * 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.
+ *
+ * @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`.
+ *
+ * @example
+ * ```tsx
+ * const { messages, sendMessage } = useSecureMessages(conversationId, { group, senderDeviceId });
+ * await sendMessage("hello 💜");
+ * ```
+ */
+export function useSecureMessages(conversationId, options = {}) {
+    const { rest, crypto, socket } = useSecureChat();
+    const { group, senderDeviceId } = options;
+    const [messages, setMessages] = useState([]);
+    const [before, setBefore] = useState(undefined);
+    const [hasMore, setHasMore] = useState(true);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const decrypt = useCallback(async (model) => {
+        if (!group)
+            return { model, plaintext: null };
+        try {
+            const { plaintext } = await crypto.decryptMessage(group, fromBase64(model.ciphertext));
+            return { model, plaintext: bytesToUtf8(plaintext) };
+        }
+        catch {
+            // Buffer/skip: epoch not yet reached, or undecryptable. Surface ciphertext without text.
+            return { model, plaintext: null };
+        }
+    }, [crypto, group]);
+    const load = useCallback(async (reset) => {
+        setLoading(true);
+        setError(null);
+        try {
+            const page = await rest.listMessages(conversationId, {
+                before: reset ? undefined : before,
+                limit: 40,
+            });
+            const decrypted = await Promise.all(page.messages.map(decrypt));
+            const oldest = page.messages[page.messages.length - 1];
+            setBefore(oldest ? oldest.createdAt : before);
+            setHasMore(page.hasMore);
+            // Server returns created_at DESC; keep newest-first in state.
+            setMessages((prev) => (reset ? decrypted : [...prev, ...decrypted]));
+        }
+        catch (err) {
+            setError(err);
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [rest, conversationId, before, decrypt]);
+    const refresh = useCallback(async () => {
+        setBefore(undefined);
+        await load(true);
+    }, [load]);
+    const loadMore = useCallback(async () => {
+        if (!hasMore || loading)
+            return;
+        await load(false);
+    }, [hasMore, loading, load]);
+    const sendMessage = useCallback(async (text) => {
+        if (!group)
+            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));
+        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]);
+    useEffect(() => {
+        refresh();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [conversationId]);
+    // Live receive: join the conversation room and decrypt inbound ciphertext.
+    useEffect(() => {
+        socket.joinConversation(conversationId);
+        const off = socket.on("secure:message", (model) => {
+            if (model.conversationId !== conversationId)
+                return;
+            decrypt(model).then((m) => setMessages((prev) => prev.some((p) => p.model.id === m.model.id) ? prev : [m, ...prev]));
+        });
+        return off;
+    }, [socket, conversationId, decrypt]);
+    return { messages, loading, hasMore, error, loadMore, refresh, sendMessage };
+}
+//# sourceMappingURL=useSecureMessages.js.map