@dtelecom/secure-chat-client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,435 @@
+interface MintTokenResponse {
+    chatToken: string;
+    expiresAt: number;
+    /**
+     * Closest dtelecom node WebSocket URL for this client's IP, computed
+     * server-side via the existing @dtelecom/server-sdk-js node discovery
+     * (Solana registry → /relevants ranking). The SDK uses this for /chat/ws.
+     */
+    chatNodeWsUrl: string;
+}
+interface OneTimeKey {
+    id: string;
+    public: string;
+}
+interface ClaimedDevice {
+    deviceId: string;
+    identityKeyCurve: string;
+    identityKeyEd: string;
+    signedPrekey: string;
+    signedPrekeySig: string;
+    oneTimeKey: OneTimeKey | null;
+    fallbackPrekey: string;
+    fallbackPrekeySig: string;
+    fingerprint: string;
+    lastActiveAt: number;
+}
+
+/** Public material the SDK uploads via POST /api/chat/keys/upload. */
+interface UploadBundle {
+    identityKeyCurve: string;
+    identityKeyEd: string;
+    signedPrekey: string;
+    signedPrekeySig: string;
+    fallbackPrekey: string;
+    fallbackPrekeySig: string;
+    fingerprint: string;
+    oneTimeKeys: {
+        id: string;
+        public: string;
+    }[];
+}
+/** Output of CryptoAdapter.encryptForPeer. */
+interface OutboundEnvelope {
+    /** base64-encoded Olm ciphertext. */
+    ciphertext: string;
+    /**
+     * "prekey" if this is the first message in a fresh outbound session
+     * (consumes one of the recipient's one-time-keys); "normal" once the
+     * session has ratcheted at least once.
+     */
+    msgType: "prekey" | "normal";
+}
+/**
+ * Olm primitives surface. Methods are async because the underlying WASM
+ * library is async-loaded and persistence is async (IndexedDB).
+ *
+ * The adapter owns Olm account + per-(peerUser, peerDevice) session state
+ * and persists across restarts. Callers (sessions.ts, key_bundle.ts) are
+ * stateless wrappers that orchestrate via this interface.
+ */
+interface CryptoAdapter {
+    /** Initialize underlying WASM library. Idempotent. */
+    init(): Promise<void>;
+    /** True if this adapter has a persisted Olm account. */
+    hasAccount(): Promise<boolean>;
+    /**
+     * Generate a new Olm account and return the public bundle to upload.
+     * Persists private state. Throws if an account already exists — call
+     * hasAccount() first.
+     */
+    generateAccount(otkCount: number): Promise<UploadBundle>;
+    /**
+     * Re-emit the current bundle without generating new keys. Used when
+     * the device id is already known but the server doesn't yet have the
+     * bundle (e.g. backend was wiped during testing).
+     */
+    getCurrentBundle(): Promise<UploadBundle>;
+    /** Generate N more one-time keys for top-up. Returns public material. */
+    generateOneTimeKeys(n: number): Promise<{
+        id: string;
+        public: string;
+    }[]>;
+    /**
+     * Locally tracked count of unconsumed one-time keys. The server's count
+     * is authoritative; this is the SDK's view (decrements on every
+     * outbound prekey-message it knows about, but the server may consume
+     * OTKs without notifying the SDK).
+     */
+    unusedOneTimeKeyCount(): Promise<number>;
+    /**
+     * Encrypt for a peer device. Creates an outbound Olm session lazily
+     * from peerBundle if no session exists with (peerUserId, peerDeviceId);
+     * subsequent calls reuse the established session.
+     */
+    encryptForPeer(peerUserId: string, peerDeviceId: string, peerBundle: ClaimedDevice, plaintext: string): Promise<OutboundEnvelope>;
+    /**
+     * Decrypt an inbound ciphertext. If `msgType === "prekey"` and no
+     * session exists yet for (peerUserId, peerDeviceId), creates an
+     * inbound session from the prekey message.
+     */
+    decryptFromPeer(peerUserId: string, peerDeviceId: string, ciphertext: string, msgType: "prekey" | "normal"): Promise<string>;
+    /** Drop the session with a peer device. Used for explicit reset. */
+    forgetSession(peerUserId: string, peerDeviceId: string): Promise<void>;
+    /** Whether a session exists with this peer device. */
+    hasSession(peerUserId: string, peerDeviceId: string): Promise<boolean>;
+}
+
+interface KVStore {
+    getString(key: string): Promise<string | null>;
+    setString(key: string, value: string): Promise<void>;
+    getBytes(key: string): Promise<Uint8Array | null>;
+    setBytes(key: string, value: Uint8Array): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** List keys with the given prefix. Used to enumerate per-peer-device sessions. */
+    listKeys(prefix: string): Promise<string[]>;
+}
+
+/**
+ * Persisted shape of a message. `senderUserId` is the truth — the SDK
+ * sets it to either "self" (when the local user sent it) or to the
+ * peer's user id (on inbound). Edit/delete authorization compares this
+ * field on the stored row to the sender of the inbound mutation event.
+ */
+interface StoredMessage {
+    id: string;
+    peerUserId: string;
+    senderUserId: string;
+    text: string;
+    /** Original clientSentAt of the text event; never mutated by edits. */
+    sentAt: number;
+    /** Set on edit; null otherwise. */
+    editedAt: number | null;
+    /** Set on delete; the message becomes a tombstone. */
+    deletedAt: number | null;
+    replyTo?: string;
+}
+
+type MessageStatus = "pending" | "sent" | "delivered" | "deliveredAll" | "read";
+
+/**
+ * Consumer-supplied callback that mints a chat token via the tenant backend.
+ * Must return the full `POST /api/chat/token` response so the SDK can use the
+ * server-discovered node URL (chatNodeWsUrl) — no Solana code on the client.
+ */
+type FetchChatToken = (deviceId: string) => Promise<MintTokenResponse>;
+
+interface OlmAdapterOptions {
+    store: KVStore;
+}
+declare class OlmCryptoAdapter implements CryptoAdapter {
+    private opts;
+    private account;
+    private sessions;
+    constructor(opts: OlmAdapterOptions);
+    init(): Promise<void>;
+    hasAccount(): Promise<boolean>;
+    generateAccount(otkCount: number): Promise<UploadBundle>;
+    getCurrentBundle(): Promise<UploadBundle>;
+    generateOneTimeKeys(n: number): Promise<{
+        id: string;
+        public: string;
+    }[]>;
+    unusedOneTimeKeyCount(): Promise<number>;
+    encryptForPeer(peerUserId: string, peerDeviceId: string, peerBundle: ClaimedDevice, plaintext: string): Promise<OutboundEnvelope>;
+    decryptFromPeer(peerUserId: string, peerDeviceId: string, ciphertext: string, msgType: "prekey" | "normal"): Promise<string>;
+    forgetSession(peerUserId: string, peerDeviceId: string): Promise<void>;
+    hasSession(peerUserId: string, peerDeviceId: string): Promise<boolean>;
+    private requireAccount;
+    private buildBundle;
+    private persistAccount;
+    private loadSession;
+    private persistSession;
+}
+
+declare class FakeCryptoAdapter implements CryptoAdapter {
+    private account;
+    private sessions;
+    private otkCounter;
+    init(): Promise<void>;
+    hasAccount(): Promise<boolean>;
+    generateAccount(otkCount: number): Promise<UploadBundle>;
+    getCurrentBundle(): Promise<UploadBundle>;
+    generateOneTimeKeys(n: number): Promise<{
+        id: string;
+        public: string;
+    }[]>;
+    unusedOneTimeKeyCount(): Promise<number>;
+    encryptForPeer(peerUserId: string, peerDeviceId: string, _peerBundle: ClaimedDevice, plaintext: string): Promise<OutboundEnvelope>;
+    decryptFromPeer(peerUserId: string, peerDeviceId: string, ciphertext: string, msgType: "prekey" | "normal"): Promise<string>;
+    forgetSession(peerUserId: string, peerDeviceId: string): Promise<void>;
+    hasSession(peerUserId: string, peerDeviceId: string): Promise<boolean>;
+    private snapshot;
+    private makeOtks;
+}
+
+declare class MemoryKVStore implements KVStore {
+    private map;
+    getString(key: string): Promise<string | null>;
+    setString(key: string, value: string): Promise<void>;
+    getBytes(key: string): Promise<Uint8Array | null>;
+    setBytes(key: string, value: Uint8Array): Promise<void>;
+    delete(key: string): Promise<void>;
+    listKeys(prefix: string): Promise<string[]>;
+}
+
+declare class WebKVStore implements KVStore {
+    getString(key: string): Promise<string | null>;
+    setString(key: string, value: string): Promise<void>;
+    getBytes(key: string): Promise<Uint8Array | null>;
+    setBytes(key: string, value: Uint8Array): Promise<void>;
+    delete(key: string): Promise<void>;
+    listKeys(prefix: string): Promise<string[]>;
+}
+
+declare const VERSION = "0.0.0";
+declare const CONTENT_PROTOCOL_VERSION = 1;
+interface ConnectOptions {
+    /** dmeet-backend (or mock) base URL — e.g. https://dmeet.example.com */
+    apiBaseURL: string;
+    /** Function that mints a chat token. The SDK calls this whenever a fresh
+     *  token is needed; the consumer's implementation handles their own
+     *  outer auth (Privy, an internal cookie, etc.). */
+    fetchChatToken: FetchChatToken;
+    /** Optional. Defaults to WebKVStore (IndexedDB) in browsers. Tests pass
+     *  MemoryKVStore to avoid the IDB dependency. */
+    store?: KVStore;
+    /** Optional. Defaults to OlmCryptoAdapter wrapping vodozemac. Tests
+     *  pass FakeCryptoAdapter to avoid bundling WASM in the test runner. */
+    crypto?: CryptoAdapter;
+    /** Optional fetch implementation. Defaults to globalThis.fetch. Tests
+     *  pass a mocked fetch to avoid real network calls. */
+    fetchImpl?: typeof fetch;
+}
+interface MessageReceived {
+    peerUserId: string;
+    peerDeviceId: string;
+    /** The user that authored this message. Equals selfUserId when the
+     *  message arrived via self-echo from another own device. */
+    senderUserId: string;
+    message: {
+        id: string;
+        text: string;
+        replyTo?: string;
+        sentAt: number;
+    };
+}
+interface MessageEdited {
+    peerUserId: string;
+    /** Author of the edit. Equals selfUserId for self-echoed edits. */
+    editorUserId: string;
+    targetId: string;
+    newText: string;
+    editedAt: number;
+}
+interface MessageDeleted {
+    peerUserId: string;
+    /** Author of the delete. Equals selfUserId for self-echoed deletes. */
+    deleterUserId: string;
+    targetId: string;
+    deletedAt: number;
+}
+interface ReadReceiptEvent {
+    peerUserId: string;
+    peerDeviceId: string;
+    upToId: string;
+}
+interface TypingEvt {
+    peerUserId: string;
+    peerDeviceId: string;
+    state: "started" | "stopped";
+}
+interface StatusChangeEvt {
+    peerUserId: string;
+    messageId: string;
+    status: MessageStatus;
+}
+/**
+ * Emitted the first time the SDK observes a previously-unknown peer device,
+ * either via an inbound prekey-message from it OR via a refreshed device
+ * list. Apps render this as the "Bob is using a new device — verify?"
+ * banner per plan §17.
+ */
+interface PeerNewDeviceEvt {
+    peerUserId: string;
+    peerDeviceId: string;
+    fingerprint: string;
+}
+interface EventMap {
+    message: MessageReceived;
+    messageEdited: MessageEdited;
+    messageDeleted: MessageDeleted;
+    readReceipt: ReadReceiptEvent;
+    typing: TypingEvt;
+    statusChange: StatusChangeEvt;
+    peerNewDevice: PeerNewDeviceEvt;
+}
+type EventName = keyof EventMap;
+type Listener<T extends EventName> = (event: EventMap[T]) => void;
+/** Public shape returned by `getKnownPeerDevices()`. */
+interface KnownPeerDevice {
+    deviceId: string;
+    fingerprint: string;
+    lastActiveAt: number;
+    /** True if the local user has explicitly verified this device. */
+    verified: boolean;
+}
+declare class DTelecomSecureChat {
+    private deviceId;
+    private http;
+    private ws;
+    private crypto;
+    private store;
+    private keyBundle;
+    private sessions;
+    private peerDevices;
+    private messages;
+    private status;
+    private outbox;
+    private typingMgr;
+    private listeners;
+    /** Per-peer-device queue of received-event ids awaiting batch send. */
+    private pendingReceived;
+    private receivedFlushTimer;
+    /** Self user id derived from chat-token claims after first mint. */
+    private selfUserId;
+    /** Devices we've already emitted `peerNewDevice` for, to avoid duplicates. */
+    private announcedNewDevices;
+    /** True after we've reuploaded the bundle once for this connection — set
+     *  after a "peer has zero devices" outcome that suggests the backend
+     *  forgot us (registry mismatch / wipe). Don't loop. */
+    private bundleReuploadAttempted;
+    /** Cache of the read-receipts preference (loaded lazily). */
+    private readReceiptsCache;
+    /**
+     * Connect to the dtelecom mesh. Generates an Olm account on first run,
+     * uploads the bundle, opens /chat/ws to the closest discovered node,
+     * and pulls any pending offline envelopes.
+     */
+    static connect(opts: ConnectOptions): Promise<DTelecomSecureChat>;
+    private constructor();
+    /** Stable per-install device id. Useful for app diagnostics. */
+    get currentDeviceId(): string;
+    sendText(peerUserId: string, text: string, opts?: {
+        replyTo?: string;
+    }): Promise<string>;
+    editMessage(peerUserId: string, targetId: string, newText: string): Promise<string>;
+    deleteMessage(peerUserId: string, targetId: string): Promise<string>;
+    /**
+     * Send a read-watermark to `peerUserId`. No-op when read receipts are
+     * disabled by `setReadReceiptsEnabled(false)` — the local user remains
+     * invisible to senders, but inbound `read` events from peers are still
+     * consumed (the sender's preference is their own call).
+     */
+    markRead(peerUserId: string, upToMessageId: string): Promise<void>;
+    setTyping(peerUserId: string, isTyping: boolean): void;
+    /** Enable/disable outbound read receipts. Persisted in the local KV store. */
+    setReadReceiptsEnabled(enabled: boolean): Promise<void>;
+    /** Read the current preference. Default true. */
+    areReadReceiptsEnabled(): Promise<boolean>;
+    /**
+     * Returns the cached peer-device list for `peerUserId`. Refreshes via
+     * `list_devices` if the local cache is empty or stale. Used to render
+     * the "Known Devices" settings panel. Doesn't consume OTKs.
+     */
+    getKnownPeerDevices(peerUserId: string): Promise<KnownPeerDevice[]>;
+    /** Single-device fingerprint accessor. Returns null if unknown. */
+    getPeerDeviceFingerprint(peerUserId: string, peerDeviceId: string): Promise<string | null>;
+    /**
+     * Mark a peer device as verified (or unverified). Local-only — doesn't
+     * change the protocol's behavior, just exposes a flag the UI can render.
+     */
+    markPeerDeviceVerified(peerUserId: string, peerDeviceId: string, verified: boolean): Promise<void>;
+    isPeerDeviceVerified(peerUserId: string, peerDeviceId: string): Promise<boolean>;
+    /**
+     * Read persisted message history with `peerUserId`, oldest→newest within
+     * the page. Use `beforeSentAt` + `limit` to paginate older messages.
+     * Returns include local-sent messages (sender = self), inbound messages
+     * (sender = peer), and tombstoned/edited rows reflecting the latest state.
+     */
+    getHistory(peerUserId: string, opts?: {
+        limit?: number;
+        beforeSentAt?: number;
+    }): Promise<StoredMessage[]>;
+    blockUser(peerUserId: string): Promise<{
+        ok: true;
+    }>;
+    unblockUser(peerUserId: string): Promise<{
+        ok: true;
+    }>;
+    getBlockedUsers(): Promise<string[]>;
+    on<T extends EventName>(event: T, fn: Listener<T>): () => void;
+    disconnect(): Promise<void>;
+    private bootstrap;
+    /**
+     * State-listener for the underlying WsClient. On every transition to
+     * "open" (initial connect AND auto-reconnect), drain any queued
+     * outbound sends and re-pull pending offline envelopes — closes the
+     * gap during disconnect.
+     */
+    private onWsState;
+    /** Set true while drainPending is running to avoid overlapping calls
+     *  (would otherwise hand the same envelope to two concurrent decrypt
+     *  invocations — Olm rejects the second). */
+    private drainingPending;
+    private drainPending;
+    private onFrame;
+    private handleInboundCiphertext;
+    /**
+     * If `peerDeviceId` is not in our local cache for `peerUserId`, refresh
+     * the peer's device list and emit `peerNewDevice` exactly once. Idempotent
+     * across repeated calls — second message from the same new device is a
+     * cheap cache hit. Failures (HTTP error fetching the device list) are
+     * swallowed; we'll re-attempt on the next inbound from this device.
+     */
+    private maybeAnnouncePeerDevice;
+    private dispatchInboundEvent;
+    /**
+     * Multi-device self-echo. Wraps the original event in a `selfEcho`
+     * envelope and ships it to our own user (mesh fanout filters our
+     * own device). Other devices belonging to the same user receive,
+     * unwrap, and persist the event so their local history mirrors this
+     * device's. No-op when:
+     *   - we don't yet know our own user id
+     *   - the original was addressed to ourselves (avoids loops)
+     *   - we have no other devices registered (encryptForPeer returns [])
+     * Best-effort: failures here don't surface to the caller.
+     */
+    private selfEcho;
+    private sendContent;
+    private queueReceivedAck;
+    private flushReceivedBatch;
+    private dispatch;
+}
+
+export { CONTENT_PROTOCOL_VERSION, type ConnectOptions, type CryptoAdapter, DTelecomSecureChat, FakeCryptoAdapter, type KVStore, type KnownPeerDevice, MemoryKVStore, type MessageDeleted, type MessageEdited, type MessageReceived, type MessageStatus, OlmCryptoAdapter, type PeerNewDeviceEvt, type ReadReceiptEvent, type StatusChangeEvt, type StoredMessage, type TypingEvt, VERSION, WebKVStore };