@agora-sdk/secure-chat-core 0.1.0

package/dist/esm/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/esm/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/esm/index.js

@@ -0,0 +1,17 @@
+// @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.
+// ── context / provider ──────────────────────────────────────────────────────
+export { SecureChatProvider, useSecureChat } from "./context/secure-chat-context";
+// ── hooks ────────────────────────────────────────────────────────────────────
+export { useSecureDevice } from "./hooks/useSecureDevice";
+export { useSecureConversations } from "./hooks/useSecureConversations";
+export { useSecureMessages } from "./hooks/useSecureMessages";
+// ── transport (for advanced / non-React use) ─────────────────────────────────
+export { SecureChatRestClient } from "./transport/rest";
+export { SecureChatSocketClient } from "./transport/socket";
+// ── utils ────────────────────────────────────────────────────────────────────
+export { toBase64, fromBase64, utf8ToBytes, bytesToUtf8 } from "./util/base64";
+//# sourceMappingURL=index.js.map

package/dist/esm/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,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAMlF,gFAAgF;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAExE,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAO9D,gFAAgF;AAChF,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAsB5D,gFAAgF;AAChF,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/esm/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>;
+}

package/dist/esm/transport/rest.js

@@ -0,0 +1,201 @@
+// Typed REST client for the secure-chat blind Delivery Service.
+//
+// Covers every endpoint in agora-server `docs/SECURE_CHAT.md` §9. Base URL and access token are
+// resolved **lazily per request** (matching the @agora-sdk/core base-URL runtime), so a token
+// refresh or a late-set baseUrl always wins. All binary is base64 on the wire; this client never
+// inspects payloads.
+import axios from "axios";
+/**
+ * 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 class SecureChatRestClient {
+    constructor(config) {
+        this.config = config;
+        this.http = axios.create();
+        this.http.interceptors.request.use((req) => {
+            const base = config.getBaseUrl().replace(/\/$/, "");
+            req.baseURL = `${base}/${config.projectId}/secure-chat`;
+            const token = config.getAccessToken();
+            if (token)
+                req.headers.set("Authorization", `Bearer ${token}`);
+            return req;
+        });
+    }
+    // ── Devices ────────────────────────────────────────────────────────────────
+    /**
+     * 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.
+     */
+    async registerDevice(body) {
+        const { data } = await this.http.post("/devices", body);
+        return data;
+    }
+    /** Public device records (signature key + credential) so peers can build a group. */
+    async listDevices(userId) {
+        const { data } = await this.http.get("/devices", {
+            params: { userId },
+        });
+        return data.data;
+    }
+    /** Revoke the caller's own device. */
+    async revokeDevice(deviceId) {
+        await this.http.delete(`/devices/${encodeURIComponent(deviceId)}`);
+    }
+    // ── KeyPackages ──────────────────────────────────────────────────────────────
+    /**
+     * 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.
+     */
+    async publishKeyPackages(deviceId, body) {
+        const { data } = await this.http.post(`/devices/${encodeURIComponent(deviceId)}/key-packages`, body);
+        return data.published;
+    }
+    /** Unconsumed + unexpired KeyPackage count for the caller's device (replenishment signal). */
+    async keyPackageCount(deviceId) {
+        const { data } = await this.http.get(`/devices/${encodeURIComponent(deviceId)}/key-packages/count`);
+        return data.available;
+    }
+    /**
+     * 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".
+     */
+    async claimKeyPackage(targetDeviceId) {
+        const { data } = await this.http.post(`/devices/${encodeURIComponent(targetDeviceId)}/key-packages/claim`);
+        return data;
+    }
+    // ── Conversations ────────────────────────────────────────────────────────────
+    /**
+     * 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.
+     */
+    async createConversation(body) {
+        const { data } = await this.http.post("/conversations", body);
+        return data;
+    }
+    /**
+     * 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.
+     */
+    async listConversations(params) {
+        const { data } = await this.http.get("/conversations", { params });
+        return data;
+    }
+    /**
+     * Fetch a single conversation by id (including the caller's membership + unread metadata).
+     *
+     * @param conversationId - The conversation's id.
+     * @returns The conversation row.
+     */
+    async getConversation(conversationId) {
+        const { data } = await this.http.get(`/conversations/${encodeURIComponent(conversationId)}`);
+        return data;
+    }
+    /** Mark the conversation read up to now (sets the member's `last_read_at`). */
+    async markRead(conversationId) {
+        await this.http.post(`/conversations/${encodeURIComponent(conversationId)}/read`);
+    }
+    // ── Membership (client supplies the MLS Commit + Welcomes; the DS linearizes) ──
+    /**
+     * 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.
+     */
+    async addMember(conversationId, body) {
+        const { data } = await this.http.post(`/conversations/${encodeURIComponent(conversationId)}/members`, body);
+        return data;
+    }
+    /** Admin remove, or self-leave. Returns the new epoch. Throws on `409 epoch-conflict` (rebase). */
+    async removeMember(conversationId, userId, body) {
+        const { data } = await this.http.delete(`/conversations/${encodeURIComponent(conversationId)}/members/${encodeURIComponent(userId)}`, { data: body });
+        return { epoch: data.epoch };
+    }
+    // ── Messages ──────────────────────────────────────────────────────────────────
+    /**
+     * 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.
+     */
+    async sendMessage(conversationId, body) {
+        const { data } = await this.http.post(`/conversations/${encodeURIComponent(conversationId)}/messages`, body);
+        return data;
+    }
+    /**
+     * 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.
+     */
+    async listMessages(conversationId, params) {
+        const { data } = await this.http.get(`/conversations/${encodeURIComponent(conversationId)}/messages`, { params });
+        return data;
+    }
+    // ── Handshake inbox + key backup ───────────────────────────────────────────────
+    /**
+     * 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.
+     */
+    async fetchHandshakes(deviceId, params) {
+        const { data } = await this.http.get(`/devices/${encodeURIComponent(deviceId)}/handshakes`, { params });
+        return data;
+    }
+    /**
+     * 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.
+     */
+    async uploadKeyBackup(body) {
+        const { data } = await this.http.put("/key-backup", body);
+        return { updatedAt: data.updatedAt };
+    }
+    /** Returns the caller's passphrase-encrypted backup blob, or null on 404. */
+    async getKeyBackup(deviceId) {
+        try {
+            const { data } = await this.http.get("/key-backup", {
+                params: deviceId ? { deviceId } : undefined,
+            });
+            return data;
+        }
+        catch (err) {
+            if (axios.isAxiosError(err) && err.response?.status === 404)
+                return null;
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=rest.js.map

package/dist/esm/transport/rest.js.map

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

package/dist/esm/transport/socket.d.ts

@@ -0,0 +1,79 @@
+import { Socket } from "socket.io-client";
+import { SecureHandshakeModel, SecureMessageModel } from "../contract";
+/** Server → client events on the `/secure` namespace (§10). */
+export interface SecureServerEvents {
+    "secure:message": (message: SecureMessageModel) => void;
+    "secure:handshake": (handshake: SecureHandshakeModel) => void;
+    "secure:welcome": (welcome: SecureHandshakeModel) => void;
+    "secure:member:joined": (signal: {
+        conversationId: string;
+        userId: string;
+    }) => void;
+    "secure:member:left": (signal: {
+        conversationId: string;
+        userId: string;
+    }) => void;
+    "secure:key-packages-low": (signal: {
+        deviceId: string;
+        available: number;
+    }) => void;
+    "secure:typing:start": (signal: {
+        conversationId: string;
+        userId: string;
+    }) => void;
+    "secure:typing:stop": (signal: {
+        conversationId: string;
+        userId: string;
+    }) => void;
+}
+/** Client → server events. */
+export interface SecureClientEvents {
+    "join:secure-conversation": (conversationId: string) => void;
+    "join:secure-device": (deviceId: string) => void;
+}
+/** A socket.io `Socket` typed with the secure-chat event maps in both directions. */
+export type SecureSocket = Socket<SecureServerEvents, SecureClientEvents>;
+/**
+ * Configuration for {@link SecureChatSocketClient}. The origin and token are read through resolvers
+ * (not captured once) so a refreshed token is used on the next (re)connect.
+ */
+export interface SecureChatSocketConfig {
+    /** Resolve the socket origin (e.g. `getSocketUrl()` from @agora-sdk/core). */
+    getSocketUrl: () => string;
+    /** Resolve the current access token (sent in the socket `auth` handshake). */
+    getAccessToken: () => string | undefined;
+    /** The Agora project id, sent as a connection query param. */
+    projectId: string;
+}
+/**
+ * Thin wrapper around the `/secure` namespace connection. Devices the user owns are auto-joined to
+ * their `secure:device:{id}` rooms on connect (server-side), so targeted Welcomes arrive without an
+ * explicit join; conversation rooms are membership-gated and joined on demand.
+ */
+export declare class SecureChatSocketClient {
+    private readonly config;
+    private socket;
+    constructor(config: SecureChatSocketConfig);
+    /**
+     * Lazily open (or reuse) the `/secure` namespace connection.
+     *
+     * @returns The live socket; idempotent while already connected.
+     */
+    connect(): SecureSocket;
+    /** Tear down the connection and drop the cached socket (e.g. on provider unmount or sign-out). */
+    disconnect(): void;
+    /** The underlying socket if one exists, else `null` — escape hatch for advanced socket.io use. */
+    get raw(): SecureSocket | null;
+    /** Join a conversation room (membership-gated server-side) to receive its broadcasts. */
+    joinConversation(conversationId: string): void;
+    /** Explicitly join a device room (ownership-verified). Owned devices auto-join on connect. */
+    joinDevice(deviceId: string): void;
+    /**
+     * Subscribe to a server → client event, auto-connecting if needed.
+     *
+     * @param event - The `secure:*` event name to listen for.
+     * @param handler - The typed handler for that event's payload.
+     * @returns An unsubscribe function that removes this handler.
+     */
+    on<E extends keyof SecureServerEvents>(event: E, handler: SecureServerEvents[E]): () => void;
+}

package/dist/esm/transport/socket.js

@@ -0,0 +1,66 @@
+// Client for the `/secure` socket.io namespace — realtime notification layer for secure chat.
+//
+// A SEPARATE namespace from the plaintext chat socket (defense-in-depth: ciphertext events never
+// mix with plaintext handlers). Realtime is an OPTIMIZATION — the REST `fetchHandshakes(since)` +
+// `listMessages` endpoints remain the durable source of truth for offline catch-up. All event
+// payloads carry ciphertext only.
+import { io } from "socket.io-client";
+/**
+ * Thin wrapper around the `/secure` namespace connection. Devices the user owns are auto-joined to
+ * their `secure:device:{id}` rooms on connect (server-side), so targeted Welcomes arrive without an
+ * explicit join; conversation rooms are membership-gated and joined on demand.
+ */
+export class SecureChatSocketClient {
+    constructor(config) {
+        this.config = config;
+        this.socket = null;
+    }
+    /**
+     * Lazily open (or reuse) the `/secure` namespace connection.
+     *
+     * @returns The live socket; idempotent while already connected.
+     */
+    connect() {
+        if (this.socket?.connected)
+            return this.socket;
+        const origin = this.config.getSocketUrl().replace(/\/$/, "");
+        this.socket = io(`${origin}/secure`, {
+            auth: { token: this.config.getAccessToken() },
+            query: { projectId: this.config.projectId },
+            transports: ["websocket"],
+            autoConnect: true,
+        });
+        return this.socket;
+    }
+    /** Tear down the connection and drop the cached socket (e.g. on provider unmount or sign-out). */
+    disconnect() {
+        this.socket?.disconnect();
+        this.socket = null;
+    }
+    /** The underlying socket if one exists, else `null` — escape hatch for advanced socket.io use. */
+    get raw() {
+        return this.socket;
+    }
+    /** Join a conversation room (membership-gated server-side) to receive its broadcasts. */
+    joinConversation(conversationId) {
+        this.connect().emit("join:secure-conversation", conversationId);
+    }
+    /** Explicitly join a device room (ownership-verified). Owned devices auto-join on connect. */
+    joinDevice(deviceId) {
+        this.connect().emit("join:secure-device", deviceId);
+    }
+    /**
+     * Subscribe to a server → client event, auto-connecting if needed.
+     *
+     * @param event - The `secure:*` event name to listen for.
+     * @param handler - The typed handler for that event's payload.
+     * @returns An unsubscribe function that removes this handler.
+     */
+    on(event, handler) {
+        const s = this.connect();
+        // socket.io typings accept the event/handler pair; the cast keeps our strict map ergonomic.
+        s.on(event, handler);
+        return () => s.off(event, handler);
+    }
+}
+//# sourceMappingURL=socket.js.map

package/dist/esm/transport/socket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket.js","sourceRoot":"","sources":["../../../src/transport/socket.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,EAAE;AACF,iGAAiG;AACjG,kGAAkG;AAClG,8FAA8F;AAC9F,kCAAkC;AAElC,OAAO,EAAE,EAAE,EAAU,MAAM,kBAAkB,CAAC;AAqC9C;;;;GAIG;AACH,MAAM,OAAO,sBAAsB;IAGjC,YAA6B,MAA8B;QAA9B,WAAM,GAAN,MAAM,CAAwB;QAFnD,WAAM,GAAwB,IAAI,CAAC;IAEmB,CAAC;IAE/D;;;;OAIG;IACH,OAAO;QACL,IAAI,IAAI,CAAC,MAAM,EAAE,SAAS;YAAE,OAAO,IAAI,CAAC,MAAM,CAAC;QAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC7D,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,MAAM,SAAS,EAAE;YACnC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,EAAE;YAC7C,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE;YAC3C,UAAU,EAAE,CAAC,WAAW,CAAC;YACzB,WAAW,EAAE,IAAI;SAClB,CAAC,CAAC;QACH,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,kGAAkG;IAClG,UAAU;QACR,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,kGAAkG;IAClG,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,yFAAyF;IACzF,gBAAgB,CAAC,cAAsB;QACrC,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,0BAA0B,EAAE,cAAc,CAAC,CAAC;IAClE,CAAC;IAED,8FAA8F;IAC9F,UAAU,CAAC,QAAgB;QACzB,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAC,CAAC;IACtD,CAAC;IAED;;;;;;OAMG;IACH,EAAE,CAAqC,KAAQ,EAAE,OAA8B;QAC7E,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QACzB,4FAA4F;QAC5F,CAAC,CAAC,EAAE,CAAC,KAAc,EAAE,OAAgB,CAAC,CAAC;QACvC,OAAO,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,KAAc,EAAE,OAAgB,CAAC,CAAC;IACvD,CAAC;CACF"}

package/dist/esm/util/base64.d.ts

@@ -0,0 +1,8 @@
+/** Encode bytes to a standard (padded) base64 string. */
+export declare function toBase64(bytes: Uint8Array): string;
+/** Decode a standard base64 string to bytes. Ignores ASCII whitespace; throws on bad chars. */
+export declare function fromBase64(b64: string): Uint8Array;
+/** UTF-8 text → bytes (for encrypting message plaintext). */
+export declare function utf8ToBytes(text: string): Uint8Array;
+/** Bytes → UTF-8 text (for decrypted message plaintext). */
+export declare function bytesToUtf8(bytes: Uint8Array): string;

package/dist/esm/util/base64.js

@@ -0,0 +1,63 @@
+// Base64 ⇄ Uint8Array at the wire boundary.
+//
+// The `SecureChatCrypto` seam works in `Uint8Array`; the server contract is base64. These helpers
+// are the only place that conversion happens. Pure (no Buffer / atob / btoa) so the same code runs
+// on web, React Native, and Node without a polyfill.
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const LOOKUP = (() => {
+    const table = new Array(256).fill(-1);
+    for (let i = 0; i < ALPHABET.length; i++)
+        table[ALPHABET.charCodeAt(i)] = i;
+    table["=".charCodeAt(0)] = 0;
+    return table;
+})();
+/** Encode bytes to a standard (padded) base64 string. */
+export function toBase64(bytes) {
+    let out = "";
+    let i = 0;
+    for (; i + 2 < bytes.length; i += 3) {
+        const n = (bytes[i] << 16) | (bytes[i + 1] << 8) | bytes[i + 2];
+        out += ALPHABET[(n >> 18) & 63] + ALPHABET[(n >> 12) & 63] + ALPHABET[(n >> 6) & 63] + ALPHABET[n & 63];
+    }
+    const rem = bytes.length - i;
+    if (rem === 1) {
+        const n = bytes[i] << 16;
+        out += ALPHABET[(n >> 18) & 63] + ALPHABET[(n >> 12) & 63] + "==";
+    }
+    else if (rem === 2) {
+        const n = (bytes[i] << 16) | (bytes[i + 1] << 8);
+        out += ALPHABET[(n >> 18) & 63] + ALPHABET[(n >> 12) & 63] + ALPHABET[(n >> 6) & 63] + "=";
+    }
+    return out;
+}
+/** Decode a standard base64 string to bytes. Ignores ASCII whitespace; throws on bad chars. */
+export function fromBase64(b64) {
+    const clean = b64.replace(/[\r\n\t ]/g, "");
+    const padless = clean.replace(/=+$/, "");
+    const outLen = (padless.length * 3) >> 2;
+    const out = new Uint8Array(outLen);
+    let o = 0;
+    let buffer = 0;
+    let bits = 0;
+    for (let i = 0; i < padless.length; i++) {
+        const v = LOOKUP[padless.charCodeAt(i)];
+        if (v === -1)
+            throw new Error("invalid base64 character");
+        buffer = (buffer << 6) | v;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out[o++] = (buffer >> bits) & 0xff;
+        }
+    }
+    return out;
+}
+/** UTF-8 text → bytes (for encrypting message plaintext). */
+export function utf8ToBytes(text) {
+    return new TextEncoder().encode(text);
+}
+/** Bytes → UTF-8 text (for decrypted message plaintext). */
+export function bytesToUtf8(bytes) {
+    return new TextDecoder().decode(bytes);
+}
+//# sourceMappingURL=base64.js.map

package/dist/esm/util/base64.js.map

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