@agora-sdk/secure-chat-core 0.1.0

package/dist/cjs/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/cjs/hooks/useSecureDevice.js

@@ -0,0 +1,120 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSecureDevice = useSecureDevice;
+const react_1 = require("react");
+const base64_1 = require("../util/base64");
+const secure_chat_context_1 = require("../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(); }, []);
+ * ```
+ */
+function useSecureDevice(options = {}) {
+    const { crypto, rest, socket } = (0, secure_chat_context_1.useSecureChat)();
+    const { ciphersuite, keyPackageTarget = 20, autoReplenish = true } = options;
+    const [device, setDevice] = (0, react_1.useState)(null);
+    const [registering, setRegistering] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(null);
+    const [keyPackagesAvailable, setKeyPackagesAvailable] = (0, react_1.useState)(null);
+    const deviceIdRef = (0, react_1.useRef)(options.deviceId ?? newDeviceId());
+    const publishKeyPackages = (0, react_1.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: (0, base64_1.toBase64)(b.keyPackage),
+                ciphersuite: b.ciphersuite,
+                expiresAt: b.expiresAt,
+            })),
+        });
+        return published;
+    }, [crypto, rest, device, keyPackageTarget]);
+    const refreshKeyPackageCount = (0, react_1.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 = (0, react_1.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: (0, base64_1.toBase64)(identity.signaturePublicKey),
+                credential: (0, base64_1.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.
+    (0, react_1.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/cjs/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/cjs/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/cjs/hooks/useSecureMessages.js

@@ -0,0 +1,113 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSecureMessages = useSecureMessages;
+const react_1 = require("react");
+const base64_1 = require("../util/base64");
+const secure_chat_context_1 = require("../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 💜");
+ * ```
+ */
+function useSecureMessages(conversationId, options = {}) {
+    const { rest, crypto, socket } = (0, secure_chat_context_1.useSecureChat)();
+    const { group, senderDeviceId } = options;
+    const [messages, setMessages] = (0, react_1.useState)([]);
+    const [before, setBefore] = (0, react_1.useState)(undefined);
+    const [hasMore, setHasMore] = (0, react_1.useState)(true);
+    const [loading, setLoading] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(null);
+    const decrypt = (0, react_1.useCallback)(async (model) => {
+        if (!group)
+            return { model, plaintext: null };
+        try {
+            const { plaintext } = await crypto.decryptMessage(group, (0, base64_1.fromBase64)(model.ciphertext));
+            return { model, plaintext: (0, base64_1.bytesToUtf8)(plaintext) };
+        }
+        catch {
+            // Buffer/skip: epoch not yet reached, or undecryptable. Surface ciphertext without text.
+            return { model, plaintext: null };
+        }
+    }, [crypto, group]);
+    const load = (0, react_1.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 = (0, react_1.useCallback)(async () => {
+        setBefore(undefined);
+        await load(true);
+    }, [load]);
+    const loadMore = (0, react_1.useCallback)(async () => {
+        if (!hasMore || loading)
+            return;
+        await load(false);
+    }, [hasMore, loading, load]);
+    const sendMessage = (0, react_1.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, (0, base64_1.utf8ToBytes)(text));
+        const sent = await rest.sendMessage(conversationId, {
+            ciphertext: (0, base64_1.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]);
+    (0, react_1.useEffect)(() => {
+        refresh();
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [conversationId]);
+    // Live receive: join the conversation room and decrypt inbound ciphertext.
+    (0, react_1.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

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

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

package/dist/cjs/index.d.ts

@@ -0,0 +1,15 @@
+export { SecureChatProvider, useSecureChat } from "./context/secure-chat-context";
+export type { SecureChatProviderProps, SecureChatContextValue, } from "./context/secure-chat-context";
+export { useSecureDevice } from "./hooks/useSecureDevice";
+export type { UseSecureDeviceOptions, UseSecureDeviceValues } from "./hooks/useSecureDevice";
+export { useSecureConversations } from "./hooks/useSecureConversations";
+export type { UseSecureConversationsValues } from "./hooks/useSecureConversations";
+export { useSecureMessages } from "./hooks/useSecureMessages";
+export type { UseSecureMessagesOptions, UseSecureMessagesValues, DecryptedSecureMessage, } from "./hooks/useSecureMessages";
+export { SecureChatRestClient } from "./transport/rest";
+export type { SecureChatRestConfig } from "./transport/rest";
+export { SecureChatSocketClient } from "./transport/socket";
+export type { SecureSocket, SecureServerEvents, SecureClientEvents, SecureChatSocketConfig, } from "./transport/socket";
+export type { SecureChatCrypto, DeviceIdentity, KeyPackageBundle, GroupHandle, TargetedWelcome, CommitResult, PassphraseBackup, } from "@agora-sdk/secure-chat-crypto";
+export type * from "./contract";
+export { toBase64, fromBase64, utf8ToBytes, bytesToUtf8 } from "./util/base64";

package/dist/cjs/index.js

@@ -0,0 +1,31 @@
+"use strict";
+// @agora-sdk/secure-chat-core — platform-agnostic client for Agora end-to-end-encrypted chat.
+//
+// Transport (REST + /secure socket) + provider/hooks, with MLS crypto supplied by dependency
+// injection of a `SecureChatCrypto`. Platform packages (@agora-sdk/secure-chat-react-js, etc.)
+// re-export this and add the concrete crypto + persistence.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bytesToUtf8 = exports.utf8ToBytes = exports.fromBase64 = exports.toBase64 = exports.SecureChatSocketClient = exports.SecureChatRestClient = exports.useSecureMessages = exports.useSecureConversations = exports.useSecureDevice = exports.useSecureChat = exports.SecureChatProvider = void 0;
+// ── context / provider ──────────────────────────────────────────────────────
+var secure_chat_context_1 = require("./context/secure-chat-context");
+Object.defineProperty(exports, "SecureChatProvider", { enumerable: true, get: function () { return secure_chat_context_1.SecureChatProvider; } });
+Object.defineProperty(exports, "useSecureChat", { enumerable: true, get: function () { return secure_chat_context_1.useSecureChat; } });
+// ── hooks ────────────────────────────────────────────────────────────────────
+var useSecureDevice_1 = require("./hooks/useSecureDevice");
+Object.defineProperty(exports, "useSecureDevice", { enumerable: true, get: function () { return useSecureDevice_1.useSecureDevice; } });
+var useSecureConversations_1 = require("./hooks/useSecureConversations");
+Object.defineProperty(exports, "useSecureConversations", { enumerable: true, get: function () { return useSecureConversations_1.useSecureConversations; } });
+var useSecureMessages_1 = require("./hooks/useSecureMessages");
+Object.defineProperty(exports, "useSecureMessages", { enumerable: true, get: function () { return useSecureMessages_1.useSecureMessages; } });
+// ── transport (for advanced / non-React use) ─────────────────────────────────
+var rest_1 = require("./transport/rest");
+Object.defineProperty(exports, "SecureChatRestClient", { enumerable: true, get: function () { return rest_1.SecureChatRestClient; } });
+var socket_1 = require("./transport/socket");
+Object.defineProperty(exports, "SecureChatSocketClient", { enumerable: true, get: function () { return socket_1.SecureChatSocketClient; } });
+// ── utils ────────────────────────────────────────────────────────────────────
+var base64_1 = require("./util/base64");
+Object.defineProperty(exports, "toBase64", { enumerable: true, get: function () { return base64_1.toBase64; } });
+Object.defineProperty(exports, "fromBase64", { enumerable: true, get: function () { return base64_1.fromBase64; } });
+Object.defineProperty(exports, "utf8ToBytes", { enumerable: true, get: function () { return base64_1.utf8ToBytes; } });
+Object.defineProperty(exports, "bytesToUtf8", { enumerable: true, get: function () { return base64_1.bytesToUtf8; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA,8FAA8F;AAC9F,EAAE;AACF,6FAA6F;AAC7F,+FAA+F;AAC/F,4DAA4D;;;AAE5D,+EAA+E;AAC/E,qEAAkF;AAAzE,yHAAA,kBAAkB,OAAA;AAAE,oHAAA,aAAa,OAAA;AAM1C,gFAAgF;AAChF,2DAA0D;AAAjD,kHAAA,eAAe,OAAA;AAExB,yEAAwE;AAA/D,gIAAA,sBAAsB,OAAA;AAE/B,+DAA8D;AAArD,sHAAA,iBAAiB,OAAA;AAO1B,gFAAgF;AAChF,yCAAwD;AAA/C,4GAAA,oBAAoB,OAAA;AAE7B,6CAA4D;AAAnD,gHAAA,sBAAsB,OAAA;AAsB/B,gFAAgF;AAChF,wCAA+E;AAAtE,kGAAA,QAAQ,OAAA;AAAE,oGAAA,UAAU,OAAA;AAAE,qGAAA,WAAW,OAAA;AAAE,qGAAA,WAAW,OAAA"}

package/dist/cjs/transport/rest.d.ts

@@ -0,0 +1,154 @@
+import { AddSecureMemberBody, CreateSecureConversationBody, PublishKeyPackagesBody, RegisterDeviceBody, RemoveSecureMemberBody, SecureConversationMemberModel, SecureConversationModel, SecureDeviceModel, SecureHandshakeModel, SecureKeyBackupModel, SecureKeyPackageClaim, SecureMessageModel, SendSecureMessageBody, UploadKeyBackupBody } from "../contract";
+/**
+ * Configuration for {@link SecureChatRestClient}. The base URL and access token are read through
+ * resolver callbacks rather than captured once, so a late-set `baseUrl` or a refreshed token take
+ * effect on the next request without rebuilding the client.
+ */
+export interface SecureChatRestConfig {
+    /** Resolve the API base URL (e.g. `getApiBaseUrl()` from @agora-sdk/core → `http://host/v7`). */
+    getBaseUrl: () => string;
+    /** Resolve the current access token, or undefined when signed out. */
+    getAccessToken: () => string | undefined;
+    /** The Agora project id (path-scoped on every endpoint). */
+    projectId: string;
+}
+/**
+ * Typed REST client for the secure-chat blind Delivery Service.
+ *
+ * Wraps every endpoint in agora-server `docs/SECURE_CHAT.md` §9. Each request lazily resolves the
+ * base URL and bearer token via the configured resolvers, scopes the path to
+ * `{baseUrl}/{projectId}/secure-chat`, and passes payloads through untouched — all binary is base64
+ * on the wire and the client never inspects it.
+ *
+ * @remarks
+ * Construct this directly only for advanced / non-React use. Inside React, prefer the
+ * `SecureChatProvider` + hooks, which build and share one client for you.
+ *
+ * @example
+ * ```typescript
+ * const rest = new SecureChatRestClient({
+ *   projectId,
+ *   getBaseUrl: () => getApiBaseUrl(),
+ *   getAccessToken: () => session.accessToken,
+ * });
+ * const device = await rest.registerDevice(body);
+ * ```
+ */
+export declare class SecureChatRestClient {
+    private readonly config;
+    private readonly http;
+    constructor(config: SecureChatRestConfig);
+    /**
+     * Register (or idempotently re-assert) the caller's MLS device — its signature key + credential.
+     *
+     * @param body - The device identity to publish (deviceId, base64 signature key, credential, ciphersuite).
+     * @returns The persisted device row; its `.id` is the uuid used as `targetDeviceId` elsewhere.
+     */
+    registerDevice(body: RegisterDeviceBody): Promise<SecureDeviceModel>;
+    /** Public device records (signature key + credential) so peers can build a group. */
+    listDevices(userId: string): Promise<SecureDeviceModel[]>;
+    /** Revoke the caller's own device. */
+    revokeDevice(deviceId: string): Promise<void>;
+    /**
+     * Publish a batch of fresh, single-use KeyPackages for one of the caller's devices so peers can
+     * add it to groups.
+     *
+     * @param deviceId - The caller's device row id (`SecureDeviceModel.id`).
+     * @param body - The KeyPackage bundles to upload (base64 KeyPackage + ref + ciphersuite).
+     * @returns How many KeyPackages the server accepted and stored.
+     */
+    publishKeyPackages(deviceId: string, body: PublishKeyPackagesBody): Promise<number>;
+    /** Unconsumed + unexpired KeyPackage count for the caller's device (replenishment signal). */
+    keyPackageCount(deviceId: string): Promise<number>;
+    /**
+     * Atomically claim one KeyPackage for a TARGET device (to add it to a group).
+     * Throws on `409 secure-chat/key-packages-exhausted` — caller should surface "device unavailable".
+     */
+    claimKeyPackage(targetDeviceId: string): Promise<SecureKeyPackageClaim>;
+    /**
+     * Register a new secure conversation on the blind DS, relaying the client-built Welcomes.
+     *
+     * @param body - The conversation type, base64 MLS group id, member user ids, and targeted Welcomes.
+     * @returns The created conversation row.
+     */
+    createConversation(body: CreateSecureConversationBody): Promise<SecureConversationModel>;
+    /**
+     * List the caller's secure conversations, newest activity first.
+     *
+     * @param params - Optional `limit` and opaque `cursor` for keyset pagination.
+     * @returns A page of conversations plus a `hasMore` flag for further paging.
+     */
+    listConversations(params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<{
+        conversations: SecureConversationModel[];
+        hasMore: boolean;
+    }>;
+    /**
+     * Fetch a single conversation by id (including the caller's membership + unread metadata).
+     *
+     * @param conversationId - The conversation's id.
+     * @returns The conversation row.
+     */
+    getConversation(conversationId: string): Promise<SecureConversationModel>;
+    /** Mark the conversation read up to now (sets the member's `last_read_at`). */
+    markRead(conversationId: string): Promise<void>;
+    /**
+     * Add a user to a conversation by relaying the caller-built Commit + per-device Welcomes.
+     *
+     * @param conversationId - The conversation to add the member to.
+     * @param body - The new member's user id, the broadcast Commit, and the targeted Welcomes.
+     * @returns The newly created membership row.
+     */
+    addMember(conversationId: string, body: AddSecureMemberBody): Promise<SecureConversationMemberModel>;
+    /** Admin remove, or self-leave. Returns the new epoch. Throws on `409 epoch-conflict` (rebase). */
+    removeMember(conversationId: string, userId: string, body: RemoveSecureMemberBody): Promise<{
+        epoch: string;
+    }>;
+    /**
+     * Send one MLS application message (opaque ciphertext) to a conversation.
+     *
+     * @param conversationId - The target conversation.
+     * @param body - The base64 ciphertext, its epoch, the sending device id, and optional content type.
+     * @returns The stored message row.
+     */
+    sendMessage(conversationId: string, body: SendSecureMessageBody): Promise<SecureMessageModel>;
+    /**
+     * Page through a conversation's messages, newest first (still encrypted — decrypt client-side).
+     *
+     * @param conversationId - The conversation to read.
+     * @param params - Optional `limit` and a `before` cursor (page older than this point).
+     * @returns A page of message rows plus a `hasMore` flag.
+     */
+    listMessages(conversationId: string, params?: {
+        limit?: number;
+        before?: string;
+    }): Promise<{
+        messages: SecureMessageModel[];
+        hasMore: boolean;
+    }>;
+    /**
+     * The durable catch-up path: union of targeted Welcomes + broadcast Commits/Proposals for the
+     * caller's device, ordered by `seq > since`. Page by passing the last `seq` you processed.
+     */
+    fetchHandshakes(deviceId: string, params?: {
+        since?: string;
+        limit?: number;
+    }): Promise<{
+        handshakes: SecureHandshakeModel[];
+        hasMore: boolean;
+    }>;
+    /**
+     * Upload (replace) the caller's passphrase-encrypted key backup blob. The server stores it opaquely
+     * and cannot decrypt it.
+     *
+     * @param body - The encrypted blob, nonce, KDF + cipher descriptors, and version.
+     * @returns The server's `updatedAt` timestamp for the stored backup.
+     */
+    uploadKeyBackup(body: UploadKeyBackupBody): Promise<{
+        updatedAt: string;
+    }>;
+    /** Returns the caller's passphrase-encrypted backup blob, or null on 404. */
+    getKeyBackup(deviceId?: string): Promise<SecureKeyBackupModel | null>;
+}