@verbeth/sdk 0.1.4 → 0.1.5

package/README.md

@@ -1,191 +1,40 @@
 # @verbeth/sdk
 
-Verbeth enables secure, E2EE messaging using Ethereum event logs as the only transport layer. No servers, no relays—just the blockchain.
-
-## Features
-
-- **End-to-end encryption** using NaCl Box (X25519 + XSalsa20-Poly1305)
-- **Forward secrecy** with ephemeral keys per message
-- **Handshake protocol** for secure key exchange
-- **Privacy-focused** with minimal metadata via `recipientHash`
-- **EOA & Smart Account support** (ERC-1271/6492 compatible)
-- **Fully on-chain** - no centralized infrastructure
-
-## Installation
+End-to-end encrypted messaging over public EVM blockchains.
 
+### Install
 ```bash
-npm install @verbeth/sdk ethers tweetnacl
+npm install @verbeth/sdk
 ```
 
-## Quick Start
+### Quickstart
+```ts
+import { createVerbethClient, deriveIdentityKeyPairWithProof, ExecutorFactory } from '@verbeth/sdk';
+import { ethers } from 'ethers';
 
-### 1. Initialize with VerbethClient (Recommended)
+const LOGCHAIN = '0x62720f39d5Ec6501508bDe4D152c1E13Fd2F6707';
 
-```typescript
-import { VerbethClient, ExecutorFactory, deriveIdentityKeyPairWithProof } from '@verbeth/sdk';
-import { Contract, BrowserProvider } from 'ethers';
-import { LogChainV1__factory } from '@verbeth/contracts/typechain-types';
-
-// Setup
-const provider = new BrowserProvider(window.ethereum);
+const provider = new ethers.BrowserProvider(window.ethereum);
 const signer = await provider.getSigner();
 const address = await signer.getAddress();
 
-// Create contract instance
-const contract = LogChainV1__factory.connect(LOGCHAIN_ADDRESS, signer);
-
-// Derive identity keys (done once, then stored)
-const { identityKeyPair, identityProof } = await deriveIdentityKeyPairWithProof(signer);
+const { identityKeyPair, identityProof } = await deriveIdentityKeyPairWithProof(signer, address);
 
-// Create executor (handles transaction submission)
-const executor = ExecutorFactory.createEOA(contract);
-
-// Initialize client
-const client = new VerbethClient({
-  executor,
-  identityKeyPair,
-  identityProof,
+const contract = new ethers.Contract(LOGCHAIN, LogChainABI, signer);
+const client = createVerbethClient({
+  address,
   signer,
-  address
-});
-
-// Send a handshake to start chatting
-const { tx, ephemeralKeyPair } = await client.sendHandshake(
-  '0xRecipientAddress...',
-  'Hello! Want to chat?'
-);
-
-// Store ephemeralKeyPair. you'll just need it to decrypt the handshake response!
-
-// Accept a handshake
-const { tx, duplexTopics } = await client.acceptHandshake(
-  handshakeEvent.ephemeralPubKey,
-  handshakeEvent.identityPubKey,
-  'Sure, lets chat!'
-);
-
-// Send encrypted messages
-await client.sendMessage(
-  duplexTopics.topicOut,
-  recipientIdentityPubKey,
-  'This message is encrypted!'
-);
-
-// Decrypt received messages
-const decrypted = await client.decryptMessage(
-  messageEvent.ciphertext,
-  senderIdentityPubKey
-);
-```
-
-### 2. Low-level API
-
-For more control, use the low-level functions:
-
-```typescript
-import {
-  initiateHandshake,
-  respondToHandshake,
-  sendEncryptedMessage,
-  decryptMessage,
-  deriveIdentityKeyPairWithProof
-} from '@verbeth/sdk';
-
-// Generate identity keys
-const { identityKeyPair, identityProof } = await deriveIdentityKeyPairWithProof(signer);
-
-// Initiate handshake
-const ephemeralKeyPair = nacl.box.keyPair();
-const tx = await initiateHandshake({
-  executor,
-  recipientAddress: '0xBob...',
-  ephemeralPubKey: ephemeralKeyPair.publicKey,
   identityKeyPair,
   identityProof,
-  plaintextPayload: 'Hi Bob!'
-});
-
-// Send encrypted message
-await sendEncryptedMessage({
-  executor,
-  topic: derivedTopic,
-  message: 'Secret message',
-  recipientPubKey: bobsIdentityKey,
-  senderAddress: myAddress,
-  senderSignKeyPair: identityKeyPair,
-  timestamp: Date.now()
+  executor: ExecutorFactory.createEOA(contract),
 });
 
-// Decrypt message
-const plaintext = decryptMessage(
-  ciphertext,
-  senderIdentityPubKey,
-  myIdentityKeyPair.secretKey
-);
+await client.sendMessage(conversationId, 'Hello, encrypted world!');
 ```
 
-## Smart Account Support
-
-Verbeth works with ERC-4337 smart accounts:
-
-```typescript
-import { ExecutorFactory } from '@verbeth/sdk';
-
-// For UserOp-based execution
-const executor = ExecutorFactory.createUserOp(
-  contract,
-  bundler,
-  smartAccount,
-  signer
-);
-
-// For direct EntryPoint execution
-const executor = ExecutorFactory.createDirectEntryPoint(
-  contract,
-  entryPoint,
-  smartAccountAddress,
-  signer
-);
-```
-
-## Contract Addresses
-
-**LogChainV1 Singleton:** `0x41a3eaC0d858028E9228d1E2092e6178fc81c4f0`
-
-**ERC1967Proxy:** `0x62720f39d5Ec6501508bDe4D152c1E13Fd2F6707`
-
-## How It Works
-
-1. **Identity Keys**: Each account derives long-term X25519 (encryption) + Ed25519 (signing) keys bound to their address via signature
-2. **Handshake**: Alice sends her ephemeral key + identity proof to Bob via a `Handshake` event
-3. **Response**: Bob verifies Alice's identity and responds with his keys + duplex topics
-4. **Messaging**: Both parties derive shared topics and exchange encrypted messages via `MessageSent` events
-5. **Decryption**: Recipients monitor their inbound topic and decrypt with their identity key
-
-
-## Security Considerations
-
-- **Forward Secrecy**: Fresh ephemeral keys per message provide sender-side forward secrecy
-- **Identity Binding**: Addresses are cryptographically bound to long-term keys via signature
-- **Non-Repudiation**: Optional Ed25519 signatures prove message origin
-- **Privacy**: RecipientHash hides recipient identity; duplex topics separate communication channels
-
-⚠️ **Note**: Current design provides sender-side forward secrecy. Recipient-side FS requires ephemeral↔ephemeral or session ratcheting (e.g., Double Ratchet).
-
-## Built With
-
-- [TweetNaCl](https://tweetnacl.js.org/) - Encryption primitives
-- [Ethers v6](https://docs.ethers.org/v6/) - Ethereum interactions
-- [Viem](https://viem.sh/) - EIP-1271/6492 verification
-- [Noble Curves](https://github.com/paulmillr/noble-curves) - Elliptic curve operations
-
-## Examples
-
-Check out the [demo application](https://github.com/okrame/verbeth-sdk/tree/main/apps/demo) for a complete implementation.
-
 ## Documentation
 
-For detailed protocol documentation, security analysis, and improvement proposals, see the [main repository](https://github.com/okrame/verbeth-sdk).
+For detailed protocol documentation, see [docs.verbeth.xyz](https://docs.verbeth.xyz).
 
 ## License
 

package/dist/esm/src/client/HsrTagIndex.d.ts

@@ -0,0 +1,77 @@
+export interface PendingContactEntry {
+    address: string;
+    handshakeEphemeralSecret: Uint8Array;
+    kemSecretKey: Uint8Array;
+}
+/**
+ * Index for efficient HSR tag matching.
+ *
+ * When an HSR arrives, we need to find which pending contact it belongs to.
+ * This requires computing tag = computeTagFromInitiator(secret, R) for each
+ * pending contact until we find a match.
+ *
+ * This class caches the computed tags per (contact, R) pair, making
+ * subsequent lookups O(1) after the first computation.
+ *
+ * @example
+ * ```typescript
+ * const hsrIndex = new HsrTagIndex();
+ *
+ * // When pending contacts change
+ * hsrIndex.rebuild(pendingContacts.map(c => ({
+ *   address: c.address,
+ *   handshakeEphemeralSecret: c.handshakeEphemeralSecret
+ * })));
+ *
+ * // Matching O(1) after first computation for each R
+ * const matchedAddress = hsrIndex.matchByTag(inResponseToTag, R);
+ * ```
+ */
+export declare class HsrTagIndex {
+    private entries;
+    private tagToAddress;
+    /**
+     * Rebuild the index with a new set of pending contacts.
+     *
+     * Preserves cached tag computations for contacts that remain.
+     * Clears entries for contacts no longer in the list.
+     *
+     * @param contacts - Current pending contacts
+     */
+    rebuild(contacts: PendingContactEntry[]): void;
+    /**
+     * Add a single pending contact without full rebuild.
+     *
+     * @param contact - Contact to add
+     */
+    addContact(contact: PendingContactEntry): void;
+    /**
+     * Remove a contact from the index.
+     *
+     * @param address - Address of contact to remove
+     */
+    removeContact(address: string): void;
+    clear(): void;
+    /**
+     * Match an HSR by its tag using hybrid (PQ-secure) computation.
+     *
+     * Decrypts the payload internally to extract kemCiphertext, then
+     * decapsulates and computes the hybrid tag for matching.
+     *
+     * @param inResponseToTag - The tag from the HSR event
+     * @param R - Responder's ephemeral public key (from HSR event)
+     * @param encryptedPayload - JSON string of the encrypted HSR payload
+     * @returns Address of matching contact, or null if no match
+     */
+    matchByTag(inResponseToTag: `0x${string}`, R: Uint8Array, encryptedPayload: string): string | null;
+    /**
+     * Get the number of indexed contacts.
+     */
+    get size(): number;
+    /**
+     * Check if a contact is in the index.
+     */
+    hasContact(address: string): boolean;
+    private secretsEqual;
+}
+//# sourceMappingURL=HsrTagIndex.d.ts.map

package/dist/esm/src/client/HsrTagIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HsrTagIndex.d.ts","sourceRoot":"","sources":["../../../../src/client/HsrTagIndex.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,wBAAwB,EAAE,UAAU,CAAC;IACrC,YAAY,EAAE,UAAU,CAAC;CAC1B;AAQD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAsC;IACrD,OAAO,CAAC,YAAY,CAAkC;IAEtD;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,EAAE,mBAAmB,EAAE,GAAG,IAAI;IAuB9C;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI;IAc9C;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAcpC,KAAK,IAAI,IAAI;IAKb;;;;;;;;;;OAUG;IACH,UAAU,CACR,eAAe,EAAE,KAAK,MAAM,EAAE,EAC9B,CAAC,EAAE,UAAU,EACb,gBAAgB,EAAE,MAAM,GACvB,MAAM,GAAG,IAAI;IAyBhB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIpC,OAAO,CAAC,YAAY;CAOrB"}

package/dist/esm/src/client/HsrTagIndex.js

@@ -0,0 +1,157 @@
+// packages/sdk/src/client/HsrTagIndex.ts
+/**
+ * Index for O(1) HSR (Handshake Response) matching.
+ *
+ * Caches computed tags for pending contacts to avoid O(n) loops
+ * when matching incoming handshake responses.
+ */
+import { computeHybridTagFromInitiator, decryptHandshakeResponse } from '../crypto.js';
+import { kem } from '../pq/kem.js';
+/**
+ * Index for efficient HSR tag matching.
+ *
+ * When an HSR arrives, we need to find which pending contact it belongs to.
+ * This requires computing tag = computeTagFromInitiator(secret, R) for each
+ * pending contact until we find a match.
+ *
+ * This class caches the computed tags per (contact, R) pair, making
+ * subsequent lookups O(1) after the first computation.
+ *
+ * @example
+ * ```typescript
+ * const hsrIndex = new HsrTagIndex();
+ *
+ * // When pending contacts change
+ * hsrIndex.rebuild(pendingContacts.map(c => ({
+ *   address: c.address,
+ *   handshakeEphemeralSecret: c.handshakeEphemeralSecret
+ * })));
+ *
+ * // Matching O(1) after first computation for each R
+ * const matchedAddress = hsrIndex.matchByTag(inResponseToTag, R);
+ * ```
+ */
+export class HsrTagIndex {
+    constructor() {
+        this.entries = new Map();
+        this.tagToAddress = new Map();
+    }
+    /**
+     * Rebuild the index with a new set of pending contacts.
+     *
+     * Preserves cached tag computations for contacts that remain.
+     * Clears entries for contacts no longer in the list.
+     *
+     * @param contacts - Current pending contacts
+     */
+    rebuild(contacts) {
+        const newEntries = new Map();
+        for (const contact of contacts) {
+            const existing = this.entries.get(contact.address);
+            if (existing &&
+                this.secretsEqual(existing.secret, contact.handshakeEphemeralSecret) &&
+                this.secretsEqual(existing.kemSecretKey, contact.kemSecretKey)) {
+                newEntries.set(contact.address, existing);
+            }
+            else {
+                newEntries.set(contact.address, {
+                    address: contact.address,
+                    secret: contact.handshakeEphemeralSecret,
+                    kemSecretKey: contact.kemSecretKey,
+                });
+            }
+        }
+        // Keep tagToAddress cache - it's still valid for already computed tags
+        this.entries = newEntries;
+    }
+    /**
+     * Add a single pending contact without full rebuild.
+     *
+     * @param contact - Contact to add
+     */
+    addContact(contact) {
+        const existing = this.entries.get(contact.address);
+        if (!existing ||
+            !this.secretsEqual(existing.secret, contact.handshakeEphemeralSecret) ||
+            !this.secretsEqual(existing.kemSecretKey, contact.kemSecretKey)) {
+            this.entries.set(contact.address, {
+                address: contact.address,
+                secret: contact.handshakeEphemeralSecret,
+                kemSecretKey: contact.kemSecretKey,
+            });
+        }
+    }
+    /**
+     * Remove a contact from the index.
+     *
+     * @param address - Address of contact to remove
+     */
+    removeContact(address) {
+        const entry = this.entries.get(address);
+        if (entry) {
+            // Remove any cached tags for this address
+            for (const [tag, addr] of this.tagToAddress) {
+                if (addr === address) {
+                    this.tagToAddress.delete(tag);
+                }
+            }
+            this.entries.delete(address);
+        }
+    }
+    clear() {
+        this.entries.clear();
+        this.tagToAddress.clear();
+    }
+    /**
+     * Match an HSR by its tag using hybrid (PQ-secure) computation.
+     *
+     * Decrypts the payload internally to extract kemCiphertext, then
+     * decapsulates and computes the hybrid tag for matching.
+     *
+     * @param inResponseToTag - The tag from the HSR event
+     * @param R - Responder's ephemeral public key (from HSR event)
+     * @param encryptedPayload - JSON string of the encrypted HSR payload
+     * @returns Address of matching contact, or null if no match
+     */
+    matchByTag(inResponseToTag, R, encryptedPayload) {
+        // Cache check
+        const cachedAddress = this.tagToAddress.get(inResponseToTag);
+        if (cachedAddress) {
+            return cachedAddress;
+        }
+        // For each contact: decrypt → extract kemCiphertext → decapsulate → compute hybrid tag
+        for (const [address, entry] of this.entries) {
+            const decrypted = decryptHandshakeResponse(encryptedPayload, entry.secret);
+            if (!decrypted || !decrypted.kemCiphertext)
+                continue;
+            const kemSecret = kem.decapsulate(decrypted.kemCiphertext, entry.kemSecretKey);
+            const tag = computeHybridTagFromInitiator(entry.secret, R, kemSecret);
+            this.tagToAddress.set(tag, address);
+            if (tag === inResponseToTag) {
+                return address;
+            }
+        }
+        return null;
+    }
+    /**
+     * Get the number of indexed contacts.
+     */
+    get size() {
+        return this.entries.size;
+    }
+    /**
+     * Check if a contact is in the index.
+     */
+    hasContact(address) {
+        return this.entries.has(address);
+    }
+    secretsEqual(a, b) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            if (a[i] !== b[i])
+                return false;
+        }
+        return true;
+    }
+}

package/dist/esm/src/client/PendingManager.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Internal Pending Message Coordinator.
+ *
+ * Manages the lifecycle of outbound messages:
+ * - Creating pending records before tx submission
+ * - Updating status on submission
+ * - Matching confirmations by txHash
+ * - Cleaning up after confirmation or failure
+ */
+import { PendingStore, PendingMessage } from './types.js';
+export interface CreatePendingParams {
+    id: string;
+    conversationId: string;
+    topic: string;
+    payloadHex: string;
+    plaintext: string;
+    sessionStateBefore: string;
+    sessionStateAfter: string;
+    createdAt: number;
+}
+export declare class PendingManager {
+    private store;
+    constructor(store: PendingStore);
+    /**
+     * Create and save a pending message record.
+     * Called right before submitting a transaction.
+     */
+    create(params: CreatePendingParams): Promise<PendingMessage>;
+    /**
+     * Mark as submitted with transaction hash.
+     * Called immediately after tx is broadcast.
+     */
+    markSubmitted(id: string, txHash: string): Promise<void>;
+    /**
+     * Mark as failed.
+     * Called when tx submission fails.
+     * Note: Ratchet slot is already burned (session was committed).
+     */
+    markFailed(id: string): Promise<void>;
+    get(id: string): Promise<PendingMessage | null>;
+    getByTxHash(txHash: string): Promise<PendingMessage | null>;
+    getByConversation(conversationId: string): Promise<PendingMessage[]>;
+    /**
+     * Finalize and delete.
+     * Called when we see our MessageSent event on-chain.
+     *
+     * @returns The finalized pending message, or null if not found
+     */
+    finalize(id: string): Promise<PendingMessage | null>;
+    /**
+     * Delete a pending message without finalizing.
+     * Used for cleanup on failure or cancellation.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Clean up stale pending messages.
+     * Called periodically to remove old failed/stuck records.
+     *
+     * @param conversationId - Conversation to clean up
+     * @param maxAgeMs - Maximum age in milliseconds (default: 24 hours)
+     * @returns Number of records cleaned up
+     */
+    cleanupStale(conversationId: string, maxAgeMs?: number): Promise<number>;
+}
+//# sourceMappingURL=PendingManager.d.ts.map

package/dist/esm/src/client/PendingManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PendingManager.d.ts","sourceRoot":"","sources":["../../../../src/client/PendingManager.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,cAAc,EAAiB,MAAM,YAAY,CAAC;AAEzE,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,cAAc;IACb,OAAO,CAAC,KAAK;gBAAL,KAAK,EAAE,YAAY;IAEvC;;;OAGG;IACG,MAAM,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;IAUlE;;;OAGG;IACG,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9D;;;;OAIG;IACG,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAK/C,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAI3D,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAK1E;;;;;OAKG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAU1D;;;OAGG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC;;;;;;;OAOG;IACG,YAAY,CAChB,cAAc,EAAE,MAAM,EACtB,QAAQ,GAAE,MAA4B,GACrC,OAAO,CAAC,MAAM,CAAC;CAcnB"}

package/dist/esm/src/client/PendingManager.js

@@ -0,0 +1,84 @@
+// packages/sdk/src/client/PendingManager.ts
+export class PendingManager {
+    constructor(store) {
+        this.store = store;
+    }
+    /**
+     * Create and save a pending message record.
+     * Called right before submitting a transaction.
+     */
+    async create(params) {
+        const pending = {
+            ...params,
+            txHash: null,
+            status: 'preparing',
+        };
+        await this.store.save(pending);
+        return pending;
+    }
+    /**
+     * Mark as submitted with transaction hash.
+     * Called immediately after tx is broadcast.
+     */
+    async markSubmitted(id, txHash) {
+        await this.store.updateStatus(id, 'submitted', txHash);
+    }
+    /**
+     * Mark as failed.
+     * Called when tx submission fails.
+     * Note: Ratchet slot is already burned (session was committed).
+     */
+    async markFailed(id) {
+        await this.store.updateStatus(id, 'failed');
+    }
+    async get(id) {
+        return this.store.get(id);
+    }
+    async getByTxHash(txHash) {
+        return this.store.getByTxHash(txHash);
+    }
+    async getByConversation(conversationId) {
+        return this.store.getByConversation(conversationId);
+    }
+    /**
+     * Finalize and delete.
+     * Called when we see our MessageSent event on-chain.
+     *
+     * @returns The finalized pending message, or null if not found
+     */
+    async finalize(id) {
+        const pending = await this.store.get(id);
+        if (!pending) {
+            return null;
+        }
+        await this.store.delete(id);
+        return pending;
+    }
+    /**
+     * Delete a pending message without finalizing.
+     * Used for cleanup on failure or cancellation.
+     */
+    async delete(id) {
+        await this.store.delete(id);
+    }
+    /**
+     * Clean up stale pending messages.
+     * Called periodically to remove old failed/stuck records.
+     *
+     * @param conversationId - Conversation to clean up
+     * @param maxAgeMs - Maximum age in milliseconds (default: 24 hours)
+     * @returns Number of records cleaned up
+     */
+    async cleanupStale(conversationId, maxAgeMs = 24 * 60 * 60 * 1000) {
+        const pending = await this.store.getByConversation(conversationId);
+        const cutoff = Date.now() - maxAgeMs;
+        let cleaned = 0;
+        for (const p of pending) {
+            if (p.createdAt < cutoff) {
+                await this.store.delete(p.id);
+                cleaned++;
+            }
+        }
+        return cleaned;
+    }
+}

package/dist/esm/src/client/SessionManager.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Internal Session Coordinator.
+ *
+ * Handles:
+ * - Session caching for performance
+ * - Topic matching (current, next, previous)
+ * - Automatic topic promotion when next topic is used
+ * - Cache invalidation
+ */
+import { RatchetSession } from '../ratchet/types.js';
+import { SessionStore } from './types.js';
+export interface TopicLookupResult {
+    session: RatchetSession;
+    topicMatch: 'current' | 'next' | 'previous';
+}
+/**
+ * Internal session manager that wraps a SessionStore with caching
+ * and topic promotion logic.
+ */
+export declare class SessionManager {
+    private store;
+    private cache;
+    constructor(store: SessionStore);
+    /**
+     * Get session by conversation ID, checking cache first.
+     */
+    getByConversationId(conversationId: string): Promise<RatchetSession | null>;
+    /**
+     * Find session by inbound topic with automatic topic promotion.
+     *
+     * Checks topics in order:
+     * 1. currentTopicInbound - standard case
+     * 2. nextTopicInbound - DH ratchet advanced, promotes topics
+     * 3. previousTopicInbound - grace period for late messages
+     *
+     * @param topic - The topic to look up
+     * @returns Session and match type, or null if not found
+     */
+    getByInboundTopic(topic: string): Promise<TopicLookupResult | null>;
+    /**
+     * Update session in cache and persist to store.
+     */
+    save(session: RatchetSession): Promise<void>;
+    /**
+     * Update cache without persisting (for batch operations).
+     */
+    updateCache(session: RatchetSession): void;
+    /**
+     * Persist all cached sessions to store.
+     */
+    flushCache(): Promise<void>;
+    /**
+     * Invalidate cache entry (e.g., on session reset).
+     */
+    invalidate(conversationId: string): void;
+    clearCache(): void;
+    getCacheSize(): number;
+    isCached(conversationId: string): boolean;
+    /**
+     * Promote next topics to current (internal helper).
+     * Called when a message arrives on nextTopicInbound.
+     */
+    private promoteTopics;
+}
+//# sourceMappingURL=SessionManager.d.ts.map

package/dist/esm/src/client/SessionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionManager.d.ts","sourceRoot":"","sources":["../../../../src/client/SessionManager.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,EAAE,cAAc,EAA8B,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,cAAc,CAAC;IACxB,UAAU,EAAE,SAAS,GAAG,MAAM,GAAG,UAAU,CAAC;CAC7C;AAED;;;GAGG;AACH,qBAAa,cAAc;IAGb,OAAO,CAAC,KAAK;IAFzB,OAAO,CAAC,KAAK,CAAqC;gBAE9B,KAAK,EAAE,YAAY;IAMvC;;OAEG;IACG,mBAAmB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAajF;;;;;;;;;;OAUG;IACG,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IA6CzE;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlD;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAI1C;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IASjC;;OAEG;IACH,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI;IAIxC,UAAU,IAAI,IAAI;IAIlB,YAAY,IAAI,MAAM;IAItB,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAIzC;;;OAGG;IACH,OAAO,CAAC,aAAa;CAqBtB"}