@stvor/sdk 2.2.1 → 2.3.0

package/dist/facade/app.d.ts

@@ -1,23 +1,96 @@
 import type { StvorAppConfig, UserId, MessageContent } from './types.js';
 import { RelayClient } from './relay-client.js';
 type MessageHandler = (from: UserId, msg: string | Uint8Array) => void;
+type UserAvailableHandler = (userId: UserId) => void;
 export declare class StvorFacadeClient {
     readonly userId: UserId;
     private readonly relay;
+    private readonly defaultTimeout;
     private crypto;
     private handlers;
+    private userAvailableHandlers;
     private knownPubKeys;
-    constructor(userId: UserId, relay: RelayClient);
+    private pendingKeyResolvers;
+    constructor(userId: UserId, relay: RelayClient, defaultTimeout?: number);
     private handleRelayMessage;
     internalInitialize(): Promise<void>;
-    send(recipientId: UserId, content: MessageContent): Promise<void>;
+    /**
+     * Check if a user's public key is available locally
+     */
+    isUserAvailable(userId: UserId): boolean;
+    /**
+     * Get list of all known users (whose public keys we have)
+     */
+    getAvailableUsers(): UserId[];
+    /**
+     * Wait until a specific user's public key becomes available.
+     * This is the recommended way to ensure you can send messages.
+     *
+     * @param userId - The user to wait for
+     * @param timeoutMs - Maximum time to wait (default: 10000ms)
+     * @throws StvorError with RECIPIENT_TIMEOUT if timeout expires
+     *
+     * @example
+     * ```typescript
+     * await alice.waitForUser('bob@example.com');
+     * await alice.send('bob@example.com', 'Hello!');
+     * ```
+     */
+    waitForUser(userId: UserId, timeoutMs?: number): Promise<void>;
+    /**
+     * Send an encrypted message to a recipient.
+     *
+     * If the recipient's public key is not yet available, this method will
+     * automatically wait up to `timeoutMs` for the key to arrive via the relay.
+     *
+     * @param recipientId - The recipient's user ID
+     * @param content - Message content (string or Uint8Array)
+     * @param options - Optional: { timeout: number, waitForRecipient: boolean }
+     * @throws StvorError with RECIPIENT_TIMEOUT if recipient key doesn't arrive in time
+     *
+     * @example
+     * ```typescript
+     * // Auto-waits for recipient (recommended)
+     * await alice.send('bob@example.com', 'Hello!');
+     *
+     * // Skip waiting (throws immediately if not available)
+     * await alice.send('bob@example.com', 'Hello!', { waitForRecipient: false });
+     * ```
+     */
+    send(recipientId: UserId, content: MessageContent, options?: {
+        timeout?: number;
+        waitForRecipient?: boolean;
+    }): Promise<void>;
+    /**
+     * Register a handler for incoming messages
+     */
     onMessage(handler: MessageHandler): () => void;
+    /**
+     * Register a handler that fires when a new user becomes available.
+     * This is triggered when we receive a user's public key announcement.
+     *
+     * @example
+     * ```typescript
+     * client.onUserAvailable((userId) => {
+     *   console.log(`${userId} is now available for messaging`);
+     * });
+     * ```
+     */
+    onUserAvailable(handler: UserAvailableHandler): () => void;
 }
 export declare class StvorApp {
     private readonly config;
     private clients;
     constructor(config: StvorAppConfig);
     connect(userId: UserId): Promise<StvorFacadeClient>;
+    /**
+     * Get a connected client by user ID
+     */
+    getClient(userId: UserId): StvorFacadeClient | undefined;
+    /**
+     * Check if a user is connected locally
+     */
+    isConnected(userId: UserId): boolean;
     disconnect(userId?: UserId): Promise<void>;
 }
 export declare function init(config: StvorAppConfig): Promise<StvorApp>;

package/dist/facade/app.js

@@ -1,12 +1,19 @@
 import { Errors, StvorError } from './errors.js';
 import { RelayClient } from './relay-client.js';
 import { CryptoSession } from './crypto.js';
+/** Default timeout for waiting for recipient keys (ms) */
+const DEFAULT_RECIPIENT_TIMEOUT = 10000;
+/** Polling interval for key resolution (ms) */
+const KEY_POLL_INTERVAL = 100;
 export class StvorFacadeClient {
-    constructor(userId, relay) {
+    constructor(userId, relay, defaultTimeout = DEFAULT_RECIPIENT_TIMEOUT) {
         this.userId = userId;
         this.relay = relay;
+        this.defaultTimeout = defaultTimeout;
         this.handlers = [];
+        this.userAvailableHandlers = [];
         this.knownPubKeys = new Map();
+        this.pendingKeyResolvers = new Map();
         this.crypto = new CryptoSession();
         // listen relay messages
         this.relay.onMessage((m) => this.handleRelayMessage(m));
@@ -17,7 +24,23 @@ export class StvorFacadeClient {
         if (!m || typeof m !== 'object')
             return;
         if (m.type === 'announce' && m.user && m.pub) {
+            const wasKnown = this.knownPubKeys.has(m.user);
             this.knownPubKeys.set(m.user, m.pub);
+            // Notify pending resolvers
+            const resolvers = this.pendingKeyResolvers.get(m.user);
+            if (resolvers) {
+                resolvers.forEach(resolve => resolve());
+                this.pendingKeyResolvers.delete(m.user);
+            }
+            // Notify user available handlers (only for new users)
+            if (!wasKnown) {
+                for (const h of this.userAvailableHandlers) {
+                    try {
+                        h(m.user);
+                    }
+                    catch { }
+                }
+            }
             return;
         }
         if (m.type === 'message' && m.to === this.userId && m.payload) {
@@ -37,16 +60,109 @@ export class StvorFacadeClient {
     async internalInitialize() {
         // nothing for now; announce already sent in constructor
     }
-    async send(recipientId, content) {
-        const recipientPub = this.knownPubKeys.get(recipientId);
+    /**
+     * Check if a user's public key is available locally
+     */
+    isUserAvailable(userId) {
+        return this.knownPubKeys.has(userId);
+    }
+    /**
+     * Get list of all known users (whose public keys we have)
+     */
+    getAvailableUsers() {
+        return Array.from(this.knownPubKeys.keys()).filter(id => id !== this.userId);
+    }
+    /**
+     * Wait until a specific user's public key becomes available.
+     * This is the recommended way to ensure you can send messages.
+     *
+     * @param userId - The user to wait for
+     * @param timeoutMs - Maximum time to wait (default: 10000ms)
+     * @throws StvorError with RECIPIENT_TIMEOUT if timeout expires
+     *
+     * @example
+     * ```typescript
+     * await alice.waitForUser('bob@example.com');
+     * await alice.send('bob@example.com', 'Hello!');
+     * ```
+     */
+    async waitForUser(userId, timeoutMs = this.defaultTimeout) {
+        // Already available
+        if (this.knownPubKeys.has(userId)) {
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                // Remove from pending
+                const resolvers = this.pendingKeyResolvers.get(userId);
+                if (resolvers) {
+                    const idx = resolvers.indexOf(resolveHandler);
+                    if (idx >= 0)
+                        resolvers.splice(idx, 1);
+                    if (resolvers.length === 0)
+                        this.pendingKeyResolvers.delete(userId);
+                }
+                reject(new StvorError(Errors.RECIPIENT_TIMEOUT, `Timed out waiting for user "${userId}" after ${timeoutMs}ms. ` +
+                    `The user may not be connected to the relay. ` +
+                    `Ensure both parties are online before sending messages.`, 'Verify the recipient is connected, or increase timeout', true));
+            }, timeoutMs);
+            const resolveHandler = () => {
+                clearTimeout(timeout);
+                resolve();
+            };
+            // Add to pending resolvers
+            if (!this.pendingKeyResolvers.has(userId)) {
+                this.pendingKeyResolvers.set(userId, []);
+            }
+            this.pendingKeyResolvers.get(userId).push(resolveHandler);
+        });
+    }
+    /**
+     * Send an encrypted message to a recipient.
+     *
+     * If the recipient's public key is not yet available, this method will
+     * automatically wait up to `timeoutMs` for the key to arrive via the relay.
+     *
+     * @param recipientId - The recipient's user ID
+     * @param content - Message content (string or Uint8Array)
+     * @param options - Optional: { timeout: number, waitForRecipient: boolean }
+     * @throws StvorError with RECIPIENT_TIMEOUT if recipient key doesn't arrive in time
+     *
+     * @example
+     * ```typescript
+     * // Auto-waits for recipient (recommended)
+     * await alice.send('bob@example.com', 'Hello!');
+     *
+     * // Skip waiting (throws immediately if not available)
+     * await alice.send('bob@example.com', 'Hello!', { waitForRecipient: false });
+     * ```
+     */
+    async send(recipientId, content, options) {
+        const { timeout = this.defaultTimeout, waitForRecipient = true } = options ?? {};
+        // Try to resolve recipient key
+        let recipientPub = this.knownPubKeys.get(recipientId);
         if (!recipientPub) {
-            throw new StvorError(Errors.RECIPIENT_NOT_FOUND, 'Recipient public key unknown');
+            if (!waitForRecipient) {
+                throw new StvorError(Errors.RECIPIENT_NOT_FOUND, `Recipient "${recipientId}" is not available. ` +
+                    `Their public key has not been announced to the relay. ` +
+                    `Use waitForUser() or enable waitForRecipient option.`, 'Call waitForUser(recipientId) before sending, or ensure recipient is connected', false);
+            }
+            // Wait for recipient key with timeout
+            await this.waitForUser(recipientId, timeout);
+            recipientPub = this.knownPubKeys.get(recipientId);
+            if (!recipientPub) {
+                // Should not happen, but safety check
+                throw new StvorError(Errors.RECIPIENT_NOT_FOUND, `Recipient "${recipientId}" key resolution failed unexpectedly.`, 'This is an internal error, please report it', false);
+            }
         }
         const plain = typeof content === 'string' ? new TextEncoder().encode(content) : content;
         const payload = this.crypto.encrypt(plain, recipientPub);
         const msg = { type: 'message', to: recipientId, from: this.userId, payload };
         this.relay.send(msg);
     }
+    /**
+     * Register a handler for incoming messages
+     */
     onMessage(handler) {
         this.handlers.push(handler);
         return () => {
@@ -55,6 +171,25 @@ export class StvorFacadeClient {
                 this.handlers.splice(i, 1);
         };
     }
+    /**
+     * Register a handler that fires when a new user becomes available.
+     * This is triggered when we receive a user's public key announcement.
+     *
+     * @example
+     * ```typescript
+     * client.onUserAvailable((userId) => {
+     *   console.log(`${userId} is now available for messaging`);
+     * });
+     * ```
+     */
+    onUserAvailable(handler) {
+        this.userAvailableHandlers.push(handler);
+        return () => {
+            const i = this.userAvailableHandlers.indexOf(handler);
+            if (i >= 0)
+                this.userAvailableHandlers.splice(i, 1);
+        };
+    }
 }
 export class StvorApp {
     constructor(config) {
@@ -66,11 +201,23 @@ export class StvorApp {
         if (existing)
             return existing;
         const relay = new RelayClient(this.config.relayUrl ?? 'wss://stvor.xyz/relay', this.config.appToken, this.config.timeout ?? 10000);
-        const client = new StvorFacadeClient(userId, relay);
+        const client = new StvorFacadeClient(userId, relay, this.config.timeout ?? 10000);
         await client.internalInitialize();
         this.clients.set(userId, client);
         return client;
     }
+    /**
+     * Get a connected client by user ID
+     */
+    getClient(userId) {
+        return this.clients.get(userId);
+    }
+    /**
+     * Check if a user is connected locally
+     */
+    isConnected(userId) {
+        return this.clients.has(userId);
+    }
     async disconnect(userId) {
         if (userId) {
             this.clients.delete(userId);

package/dist/facade/crypto-session.d.ts

@@ -0,0 +1,76 @@
+/**
+ * STVOR Crypto Session Manager
+ * Integrates X3DH + Double Ratchet from ratchet module
+ *
+ * CRITICAL: Identity keys generated ONCE per userId
+ * Currently in-memory only - keys lost on restart
+ *
+ * TODO: Add persistent storage (IndexedDB/Keychain)
+ */
+export interface IdentityKeys {
+    identityKeyPair: {
+        publicKey: Uint8Array;
+        privateKey: Uint8Array;
+    };
+    signedPreKeyPair: {
+        publicKey: Uint8Array;
+        privateKey: Uint8Array;
+    };
+    oneTimePreKeys: Uint8Array[];
+}
+export interface SerializedPublicKeys {
+    identityKey: string;
+    signedPreKey: string;
+    signedPreKeySignature: string;
+    oneTimePreKey: string;
+}
+/**
+ * Manages cryptographic sessions for all peers
+ */
+export declare class CryptoSessionManager {
+    private userId;
+    private identityKeys;
+    private sessions;
+    private initialized;
+    private initPromise;
+    constructor(userId: string);
+    /**
+     * Initialize libsodium and generate identity keys
+     * RACE CONDITION SAFE: Returns same promise if called concurrently
+     */
+    initialize(): Promise<void>;
+    private _doInitialize;
+    /**
+     * Get serialized public keys for relay registration
+     */
+    getPublicKeys(): SerializedPublicKeys;
+    /**
+     * Establish session with peer (X3DH handshake)
+     */
+    establishSessionWithPeer(peerId: string, peerPublicKeys: SerializedPublicKeys): Promise<void>;
+    /**
+     * Encrypt message for peer using Double Ratchet
+     */
+    encryptForPeer(peerId: string, plaintext: string): Promise<{
+        ciphertext: Uint8Array;
+        header: {
+            publicKey: Uint8Array;
+            nonce: Uint8Array;
+        };
+    }>;
+    /**
+     * Decrypt message from peer using Double Ratchet
+     */
+    decryptFromPeer(peerId: string, ciphertext: Uint8Array, header: {
+        publicKey: Uint8Array;
+        nonce: Uint8Array;
+    }): Promise<string>;
+    /**
+     * Check if session exists with peer
+     */
+    hasSession(peerId: string): boolean;
+    /**
+     * Destroy all sessions (cleanup)
+     */
+    destroy(): void;
+}

package/dist/facade/crypto-session.js

@@ -0,0 +1,175 @@
+/**
+ * STVOR Crypto Session Manager
+ * Integrates X3DH + Double Ratchet from ratchet module
+ *
+ * CRITICAL: Identity keys generated ONCE per userId
+ * Currently in-memory only - keys lost on restart
+ *
+ * TODO: Add persistent storage (IndexedDB/Keychain)
+ */
+import sodium from 'libsodium-wrappers';
+import { ensureSodiumReady } from './sodium-singleton.js';
+import { encryptMessage as ratchetEncrypt, decryptMessage as ratchetDecrypt, incrementMessageCounter, } from '../ratchet/index.js';
+/**
+ * Manages cryptographic sessions for all peers
+ */
+export class CryptoSessionManager {
+    constructor(userId) {
+        this.identityKeys = null;
+        this.sessions = new Map();
+        this.initialized = false;
+        this.initPromise = null;
+        this.userId = userId;
+    }
+    /**
+     * Initialize libsodium and generate identity keys
+     * RACE CONDITION SAFE: Returns same promise if called concurrently
+     */
+    async initialize() {
+        // Already initialized
+        if (this.initialized && this.identityKeys) {
+            return;
+        }
+        // Initialization in progress - return existing promise
+        if (this.initPromise) {
+            return this.initPromise;
+        }
+        // Start initialization
+        this.initPromise = this._doInitialize();
+        return this.initPromise;
+    }
+    async _doInitialize() {
+        // Ensure libsodium ready (singleton - safe to call multiple times)
+        await ensureSodiumReady();
+        // CRITICAL: Check again after await (another call might have completed)
+        if (this.initialized && this.identityKeys) {
+            return;
+        }
+        // Generate long-term identity key pair (Ed25519 for signing)
+        const identityKeyPair = sodium.crypto_sign_keypair();
+        // Generate semi-ephemeral signed pre-key (X25519 for DH)
+        const signedPreKeyPair = sodium.crypto_kx_keypair();
+        // Generate pool of one-time pre-keys
+        const oneTimePreKeys = [];
+        for (let i = 0; i < 10; i++) {
+            const keypair = sodium.crypto_kx_keypair();
+            oneTimePreKeys.push(keypair.publicKey);
+        }
+        this.identityKeys = {
+            identityKeyPair: {
+                publicKey: identityKeyPair.publicKey,
+                privateKey: identityKeyPair.privateKey,
+            },
+            signedPreKeyPair: {
+                publicKey: signedPreKeyPair.publicKey,
+                privateKey: signedPreKeyPair.privateKey,
+            },
+            oneTimePreKeys,
+        };
+        this.initialized = true;
+        this.initPromise = null;
+        console.log(`[Crypto] Identity keys generated for ${this.userId}`);
+    }
+    /**
+     * Get serialized public keys for relay registration
+     */
+    getPublicKeys() {
+        if (!this.identityKeys) {
+            throw new Error('CryptoSessionManager not initialized');
+        }
+        // Sign the pre-key
+        const signedPreKeySignature = sodium.crypto_sign_detached(this.identityKeys.signedPreKeyPair.publicKey, this.identityKeys.identityKeyPair.privateKey);
+        return {
+            identityKey: sodium.to_base64(this.identityKeys.identityKeyPair.publicKey),
+            signedPreKey: sodium.to_base64(this.identityKeys.signedPreKeyPair.publicKey),
+            signedPreKeySignature: sodium.to_base64(signedPreKeySignature),
+            oneTimePreKey: sodium.to_base64(this.identityKeys.oneTimePreKeys[0] || new Uint8Array(32)),
+        };
+    }
+    /**
+     * Establish session with peer (X3DH handshake)
+     */
+    async establishSessionWithPeer(peerId, peerPublicKeys) {
+        if (!this.identityKeys) {
+            throw new Error('CryptoSessionManager not initialized');
+        }
+        // Skip if session already exists
+        if (this.sessions.has(peerId)) {
+            return;
+        }
+        // Deserialize peer's public keys
+        const recipientIdentityKey = sodium.from_base64(peerPublicKeys.identityKey);
+        const recipientSignedPreKey = sodium.from_base64(peerPublicKeys.signedPreKey);
+        const recipientSPKSignature = sodium.from_base64(peerPublicKeys.signedPreKeySignature);
+        const recipientOneTimePreKey = sodium.from_base64(peerPublicKeys.oneTimePreKey);
+        // Verify SPK signature
+        const isValid = sodium.crypto_sign_verify_detached(recipientSPKSignature, recipientSignedPreKey, recipientIdentityKey);
+        if (!isValid) {
+            throw new Error(`Invalid SPK signature for peer ${peerId}`);
+        }
+        // Perform X3DH to derive shared secret
+        const dh1 = sodium.crypto_scalarmult(this.identityKeys.signedPreKeyPair.privateKey, recipientSignedPreKey);
+        const dh2 = sodium.crypto_scalarmult(this.identityKeys.identityKeyPair.privateKey, recipientOneTimePreKey);
+        const dh3 = sodium.crypto_scalarmult(this.identityKeys.signedPreKeyPair.privateKey, recipientOneTimePreKey);
+        // Combine DH outputs
+        const sharedSecret = sodium.crypto_generichash(32, new Uint8Array([...dh1, ...dh2, ...dh3]));
+        // Derive root key
+        const rootKey = sodium.crypto_generichash(32, new Uint8Array([
+            ...sharedSecret,
+            ...sodium.from_string('x3dh-root-key-v1'),
+        ]));
+        // Create initial session state
+        const session = {
+            identityKey: this.identityKeys.identityKeyPair.publicKey,
+            signedPreKey: this.identityKeys.signedPreKeyPair.publicKey,
+            oneTimePreKey: this.identityKeys.oneTimePreKeys[0] || new Uint8Array(32),
+            rootKey,
+            sendingChainKey: rootKey,
+            receivingChainKey: rootKey,
+            skippedMessageKeys: new Map(),
+            isPostCompromise: false,
+        };
+        this.sessions.set(peerId, session);
+    }
+    /**
+     * Encrypt message for peer using Double Ratchet
+     */
+    async encryptForPeer(peerId, plaintext) {
+        const session = this.sessions.get(peerId);
+        if (!session) {
+            throw new Error(`No session with peer ${peerId}`);
+        }
+        // Encrypt using Double Ratchet
+        const result = ratchetEncrypt(plaintext, session);
+        // Enforce DH ratchet policy (Forward Secrecy + PCS)
+        const recipientKey = session.identityKey;
+        incrementMessageCounter(session, recipientKey);
+        return result;
+    }
+    /**
+     * Decrypt message from peer using Double Ratchet
+     */
+    async decryptFromPeer(peerId, ciphertext, header) {
+        const session = this.sessions.get(peerId);
+        if (!session) {
+            throw new Error(`No session with peer ${peerId}`);
+        }
+        // Decrypt using Double Ratchet
+        const plaintext = ratchetDecrypt(ciphertext, header, session);
+        return plaintext;
+    }
+    /**
+     * Check if session exists with peer
+     */
+    hasSession(peerId) {
+        return this.sessions.has(peerId);
+    }
+    /**
+     * Destroy all sessions (cleanup)
+     */
+    destroy() {
+        this.sessions.clear();
+        this.identityKeys = null;
+        this.initialized = false;
+    }
+}

package/dist/facade/errors.d.ts

@@ -3,9 +3,11 @@ export declare const Errors: {
     readonly RELAY_UNAVAILABLE: "RELAY_UNAVAILABLE";
     readonly DELIVERY_FAILED: "DELIVERY_FAILED";
     readonly RECIPIENT_NOT_FOUND: "RECIPIENT_NOT_FOUND";
+    readonly RECIPIENT_TIMEOUT: "RECIPIENT_TIMEOUT";
     readonly MESSAGE_INTEGRITY_FAILED: "MESSAGE_INTEGRITY_FAILED";
     readonly RECEIVE_TIMEOUT: "RECEIVE_TIMEOUT";
     readonly RECEIVE_IN_PROGRESS: "RECEIVE_IN_PROGRESS";
+    readonly NOT_CONNECTED: "NOT_CONNECTED";
 };
 export type ErrorCode = (typeof Errors)[keyof typeof Errors];
 export declare class StvorError extends Error {

package/dist/facade/errors.js

@@ -3,9 +3,11 @@ export const Errors = {
     RELAY_UNAVAILABLE: 'RELAY_UNAVAILABLE',
     DELIVERY_FAILED: 'DELIVERY_FAILED',
     RECIPIENT_NOT_FOUND: 'RECIPIENT_NOT_FOUND',
+    RECIPIENT_TIMEOUT: 'RECIPIENT_TIMEOUT',
     MESSAGE_INTEGRITY_FAILED: 'MESSAGE_INTEGRITY_FAILED',
     RECEIVE_TIMEOUT: 'RECEIVE_TIMEOUT',
     RECEIVE_IN_PROGRESS: 'RECEIVE_IN_PROGRESS',
+    NOT_CONNECTED: 'NOT_CONNECTED',
 };
 export class StvorError extends Error {
     constructor(code, message, action, retryable) {
@@ -13,5 +15,6 @@ export class StvorError extends Error {
         this.code = code;
         this.action = action;
         this.retryable = retryable;
+        this.name = 'StvorError';
     }
 }

package/dist/facade/index.d.ts

@@ -4,5 +4,5 @@ export * from './types.js';
 export type { DecryptedMessage, SealedPayload } from './types.js';
 export type { StvorAppConfig, AppToken, UserId, MessageContent } from './types.js';
 export { StvorError } from './errors.js';
-export { StvorApp, StvorFacadeClient, Stvor, init } from './app.js';
+export { StvorApp, StvorFacadeClient, Stvor, init, createApp } from './app.js';
 export { ErrorCode as STVOR_ERRORS } from './errors.js';

package/dist/facade/index.js

@@ -2,4 +2,4 @@ export * from './app.js';
 export * from './errors.js';
 export * from './types.js';
 export { StvorError } from './errors.js';
-export { StvorApp, StvorFacadeClient, Stvor, init } from './app.js';
+export { StvorApp, StvorFacadeClient, Stvor, init, createApp } from './app.js';

package/dist/facade/replay-manager.d.ts

@@ -0,0 +1,58 @@
+/**
+ * STVOR Replay Protection Manager
+ * Integrates nonce-based replay protection with in-memory fallback
+ *
+ * ⚠️  CRITICAL LIMITATIONS (v2.1):
+ *
+ * 1. IN-MEMORY ONLY - DEMO-LEVEL PROTECTION
+ *    - Process restart → cache cleared → replay window reopens
+ *    - Clustered deployment → each instance has separate cache
+ *    - Mobile background → iOS/Android may kill process
+ *
+ * 2. ATTACK WINDOW: 5 minutes after restart/cache clear
+ *
+ * 3. PRODUCTION REQUIREMENTS:
+ *    - Redis or distributed cache (Memcached, DynamoDB)
+ *    - Persistent storage survives restarts
+ *    - Shared state across instances
+ *
+ * 4. ACCEPTABLE FOR:
+ *    ✓ Single-instance development
+ *    ✓ Proof-of-concept deployments
+ *    ✓ Low-security use cases
+ *
+ * 5. NOT ACCEPTABLE FOR:
+ *    ✗ Multi-instance production
+ *    ✗ High-security environments
+ *    ✗ Mobile apps (background kills)
+ *
+ * STATUS: Transitional implementation - Redis integration planned for v2.2
+ */
+/**
+ * Check if message is a replay attack
+ * @param userId - Sender's user ID
+ * @param nonce - Message nonce (base64 or hex)
+ * @param timestamp - Message timestamp (Unix seconds)
+ * @returns true if replay detected
+ */
+export declare function isReplay(userId: string, nonce: string, timestamp: number): Promise<boolean>;
+/**
+ * Validate message for replay protection
+ * Throws error if replay detected or message too old
+ */
+export declare function validateMessage(userId: string, nonce: string, timestamp: number): Promise<void>;
+/**
+ * Validate message with Uint8Array nonce
+ */
+export declare function validateMessageWithNonce(userId: string, nonce: Uint8Array, timestamp: number): Promise<void>;
+/**
+ * Get cache statistics (for monitoring)
+ */
+export declare function getCacheStats(): {
+    size: number;
+    maxSize: number;
+};
+/**
+ * Clear all cached nonces (for testing)
+ */
+export declare function clearNonceCache(): void;