@stvor/sdk 2.4.0 → 3.0.0

package/dist/facade/redis-replay-cache.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Redis-based Replay Protection Cache for SDK
+ * Production-ready replay protection for clustered client deployments
+ *
+ * Use case: When running multiple instances of the same app (e.g., web app with
+ * multiple tabs, mobile app with background sync, or server-side SDK usage)
+ */
+import { IReplayCache } from './replay-manager.js';
+/**
+ * Redis client interface (compatible with ioredis, node-redis, etc.)
+ */
+export interface RedisClient {
+    setEx(key: string, ttl: number, value: string): Promise<void>;
+    exists(key: string): Promise<number>;
+    keys(pattern: string): Promise<string[]>;
+    ping(): Promise<string>;
+    quit(): Promise<void>;
+}
+/**
+ * Configuration for Redis replay cache
+ */
+export interface RedisReplayCacheConfig {
+    /** Redis client instance (ioredis, node-redis, etc.) */
+    client: RedisClient;
+    /** Prefix for all keys (default: 'stvor:replay:') */
+    keyPrefix?: string;
+    /** TTL in seconds (default: 300 = 5 minutes) */
+    ttlSeconds?: number;
+}
+/**
+ * Redis-based replay cache implementation
+ * Works with any Redis client (ioris, node-redis, etc.)
+ */
+export declare class RedisReplayCache implements IReplayCache {
+    private client;
+    private keyPrefix;
+    private ttlSeconds;
+    constructor(config: RedisReplayCacheConfig);
+    /**
+     * Build Redis key for nonce
+     */
+    private buildKey;
+    /**
+     * Add nonce to cache
+     */
+    addNonce(userId: string, nonce: string, timestamp: number): Promise<void>;
+    /**
+     * Check if nonce exists in cache
+     */
+    hasNonce(userId: string, nonce: string): Promise<boolean>;
+    /**
+     * Cleanup expired nonces
+     * Note: With Redis SETEX, keys auto-expire, so this is a no-op
+     */
+    cleanup(userId: string, maxAge: number): Promise<number>;
+    /**
+     * Get cache statistics
+     */
+    getStats(): Promise<{
+        size: number;
+    }>;
+}
+/**
+ * Example: Create Redis cache using ioredis
+ *
+ * ```typescript
+ * import Redis from 'ioredis';
+ * import { initializeReplayProtection, RedisReplayCache } from '@stvor/sdk';
+ *
+ * const redis = new Redis(process.env.REDIS_URL!);
+ * const cache = new RedisReplayCache({ client: redis });
+ * initializeReplayProtection(cache);
+ * ```
+ */
+/**
+ * Example: Create Redis cache using node-redis
+ *
+ * ```typescript
+ * import { createClient } from 'redis';
+ * import { initializeReplayProtection, RedisReplayCache } from '@stvor/sdk';
+ *
+ * const redis = createClient({ url: process.env.REDIS_URL });
+ * await redis.connect();
+ * const cache = new RedisReplayCache({ client: redis });
+ * initializeReplayProtection(cache);
+ * ```
+ */
+export type { IReplayCache } from './replay-manager.js';

package/dist/facade/redis-replay-cache.js

@@ -0,0 +1,60 @@
+/**
+ * Redis-based Replay Protection Cache for SDK
+ * Production-ready replay protection for clustered client deployments
+ *
+ * Use case: When running multiple instances of the same app (e.g., web app with
+ * multiple tabs, mobile app with background sync, or server-side SDK usage)
+ */
+/**
+ * Redis-based replay cache implementation
+ * Works with any Redis client (ioris, node-redis, etc.)
+ */
+export class RedisReplayCache {
+    constructor(config) {
+        this.client = config.client;
+        this.keyPrefix = config.keyPrefix || 'stvor:replay:';
+        this.ttlSeconds = config.ttlSeconds || 300;
+    }
+    /**
+     * Build Redis key for nonce
+     */
+    buildKey(userId, nonce) {
+        return `${this.keyPrefix}${userId}:${nonce}`;
+    }
+    /**
+     * Add nonce to cache
+     */
+    async addNonce(userId, nonce, timestamp) {
+        const key = this.buildKey(userId, nonce);
+        await this.client.setEx(key, this.ttlSeconds, String(timestamp));
+    }
+    /**
+     * Check if nonce exists in cache
+     */
+    async hasNonce(userId, nonce) {
+        const key = this.buildKey(userId, nonce);
+        const result = await this.client.exists(key);
+        return result === 1;
+    }
+    /**
+     * Cleanup expired nonces
+     * Note: With Redis SETEX, keys auto-expire, so this is a no-op
+     */
+    async cleanup(userId, maxAge) {
+        // Redis handles TTL automatically via SETEX
+        // This is kept for interface compatibility but returns 0
+        return 0;
+    }
+    /**
+     * Get cache statistics
+     */
+    async getStats() {
+        try {
+            const keys = await this.client.keys(`${this.keyPrefix}*`);
+            return { size: keys.length };
+        }
+        catch {
+            return { size: 0 };
+        }
+    }
+}

package/dist/facade/relay-client.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+// Auto-generated CommonJS wrapper for facade/relay-client.js
+// This allows `require('@stvor/sdk')` to work alongside ESM `import`.
+
+const mod = require('module');
+const url = require('url');
+
+// Use dynamic import to load the ESM module
+let _cached;
+async function _load() {
+  if (!_cached) {
+    _cached = await import(url.pathToFileURL(__filename.replace(/\.cjs$/, '.js')).href);
+  }
+  return _cached;
+}
+
+// For simple CJS usage, expose a promise-based loader
+module.exports = new Proxy({ load: _load }, {
+  get(target, prop) {
+    if (prop === '__esModule') return true;
+    if (prop === 'then') return undefined; // prevent treating as thenable
+    if (prop === 'load') return _load;
+    if (prop === 'default') {
+      return _load().then(m => m.default);
+    }
+    return _load().then(m => m[prop]);
+  }
+});

package/dist/facade/relay-client.d.ts

@@ -1,36 +1,35 @@
 /**
  * STVOR DX Facade - Relay Client
  */
-type JSONable = Record<string, any>;
-export type RelayHandler = (msg: JSONable) => void;
+import type { SerializedPublicKeys } from './crypto-session';
+interface OutgoingMessage {
+    to: string;
+    from: string;
+    ciphertext: string;
+    header: string;
+}
+interface IncomingMessage {
+    id?: string;
+    from: string;
+    ciphertext: string;
+    header: string;
+    timestamp: string;
+}
 export declare class RelayClient {
     private relayUrl;
     private timeout;
     private appToken;
-    private ws?;
     private connected;
-    private handshakeComplete;
-    private backoff;
-    private queue;
-    private handlers;
-    private reconnecting;
-    private connectPromise?;
-    private connectResolve?;
-    private connectReject?;
-    private authFailed;
     constructor(relayUrl: string, appToken: string, timeout?: number);
-    /**
-     * Initialize the connection and wait for handshake.
-     * Throws StvorError if API key is rejected.
-     */
-    init(): Promise<void>;
+    getAppToken(): string;
+    getBaseUrl(): string;
     private getAuthHeaders;
-    private connect;
-    private scheduleReconnect;
-    private doSend;
-    send(obj: JSONable): void;
-    onMessage(h: RelayHandler): void;
+    healthCheck(): Promise<void>;
     isConnected(): boolean;
-    isAuthenticated(): boolean;
+    register(userId: string, publicKeys: SerializedPublicKeys): Promise<void>;
+    getPublicKeys(userId: string): Promise<SerializedPublicKeys | null>;
+    send(message: OutgoingMessage): Promise<void>;
+    fetchMessages(userId: string): Promise<IncomingMessage[]>;
+    disconnect(): void;
 }
 export {};

package/dist/facade/relay-client.js

@@ -1,154 +1,133 @@
 /**
  * STVOR DX Facade - Relay Client
  */
-import { Errors, StvorError } from './errors.js';
-import * as WS from 'ws';
+import { Errors } from './errors.js';
 export class RelayClient {
     constructor(relayUrl, appToken, timeout = 10000) {
         this.connected = false;
-        this.handshakeComplete = false;
-        this.backoff = 1000;
-        this.queue = [];
-        this.handlers = [];
-        this.reconnecting = false;
-        this.authFailed = false;
-        this.relayUrl = relayUrl.replace(/^http/, 'ws');
+        this.relayUrl = relayUrl;
         this.appToken = appToken;
         this.timeout = timeout;
     }
-    /**
-     * Initialize the connection and wait for handshake.
-     * Throws StvorError if API key is rejected.
-     */
-    async init() {
-        if (this.authFailed) {
-            throw new StvorError(Errors.INVALID_API_KEY, 'Relay rejected connection: invalid API key');
-        }
-        if (this.handshakeComplete)
-            return;
-        await this.connect();
+    getAppToken() {
+        return this.appToken;
+    }
+    getBaseUrl() {
+        return this.relayUrl;
     }
     getAuthHeaders() {
         return {
-            Authorization: `Bearer ${this.appToken}`,
+            'Authorization': `Bearer ${this.appToken}`,
+            'Content-Type': 'application/json',
         };
     }
-    connect() {
-        if (this.connectPromise)
-            return this.connectPromise;
-        if (this.ws)
-            return Promise.resolve();
-        this.connectPromise = new Promise((resolve, reject) => {
-            this.connectResolve = resolve;
-            this.connectReject = reject;
-            const WSClass = WS.default ?? WS;
-            this.ws = new WSClass(this.relayUrl, { headers: this.getAuthHeaders() });
-            // Timeout for handshake
-            const handshakeTimeout = setTimeout(() => {
-                if (!this.handshakeComplete) {
-                    this.ws?.close();
-                    reject(new StvorError(Errors.RELAY_UNAVAILABLE, 'Relay handshake timeout'));
-                }
-            }, this.timeout);
-            this.ws.on('open', () => {
-                this.connected = true;
-                this.backoff = 1000;
-                // Don't flush queue yet - wait for handshake
+    async healthCheck() {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const res = await fetch(`${this.relayUrl}/health`, {
+                method: 'GET',
+                signal: controller.signal,
             });
-            this.ws.on('message', (data) => {
-                try {
-                    const json = JSON.parse(data.toString());
-                    // Handle handshake response
-                    if (json.type === 'handshake') {
-                        clearTimeout(handshakeTimeout);
-                        if (json.status === 'ok') {
-                            this.handshakeComplete = true;
-                            // Now flush the queue
-                            while (this.queue.length) {
-                                const m = this.queue.shift();
-                                this.doSend(m);
-                            }
-                            this.connectResolve?.();
-                        }
-                        else {
-                            // Handshake rejected
-                            this.authFailed = true;
-                            this.ws?.close();
-                            const err = new StvorError(Errors.INVALID_API_KEY, `Relay rejected connection: ${json.reason || 'invalid API key'}`);
-                            this.connectReject?.(err);
-                        }
-                        return;
-                    }
-                    // Regular message
-                    for (const h of this.handlers)
-                        h(json);
-                }
-                catch (e) {
-                    // ignore parse errors
-                }
-            });
-            this.ws.on('close', (code) => {
-                this.connected = false;
-                this.handshakeComplete = false;
-                this.ws = undefined;
-                this.connectPromise = undefined;
-                // If auth failed, don't reconnect
-                if (this.authFailed) {
-                    return;
-                }
-                // 401/403 close codes mean auth failure
-                if (code === 4001 || code === 4003) {
-                    this.authFailed = true;
-                    this.connectReject?.(new StvorError(Errors.INVALID_API_KEY, 'Relay rejected connection: invalid API key'));
-                    return;
-                }
-                this.scheduleReconnect();
-            });
-            this.ws.on('error', (err) => {
-                this.connected = false;
-                this.handshakeComplete = false;
-                this.ws = undefined;
-                this.connectPromise = undefined;
-                if (this.authFailed) {
-                    return;
-                }
-                this.scheduleReconnect();
-            });
-        });
-        return this.connectPromise;
+            if (!res.ok) {
+                throw Errors.relayUnavailable();
+            }
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
     }
-    scheduleReconnect() {
-        if (this.reconnecting)
-            return;
-        this.reconnecting = true;
-        setTimeout(() => {
-            this.reconnecting = false;
-            this.connect();
-            this.backoff = Math.min(this.backoff * 2, 30000);
-        }, this.backoff);
+    isConnected() {
+        return this.connected;
     }
-    doSend(obj) {
-        const data = JSON.stringify(obj);
-        if (this.connected && this.ws && this.handshakeComplete) {
-            this.ws.send(data);
+    async register(userId, publicKeys) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const res = await fetch(`${this.relayUrl}/register`, {
+                method: 'POST',
+                headers: this.getAuthHeaders(),
+                body: JSON.stringify({ user_id: userId, publicKeys }),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const error = await res.json().catch(() => ({}));
+                if (error.code === 'AUTH_FAILED') {
+                    throw Errors.authFailed();
+                }
+                throw Errors.relayUnavailable();
+            }
+            this.connected = true;
         }
-        else {
-            this.queue.push(obj);
+        finally {
+            clearTimeout(timeoutId);
         }
     }
-    send(obj) {
-        if (this.authFailed) {
-            throw new StvorError(Errors.INVALID_API_KEY, 'Cannot send: relay rejected connection due to invalid API key');
+    async getPublicKeys(userId) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const res = await fetch(`${this.relayUrl}/public-key/${userId}`, {
+                method: 'GET',
+                headers: this.getAuthHeaders(),
+                signal: controller.signal,
+            });
+            if (res.status === 404) {
+                return null;
+            }
+            if (!res.ok) {
+                throw Errors.relayUnavailable();
+            }
+            const data = await res.json();
+            return data.publicKeys;
+        }
+        finally {
+            clearTimeout(timeoutId);
         }
-        this.doSend(obj);
     }
-    onMessage(h) {
-        this.handlers.push(h);
+    async send(message) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const res = await fetch(`${this.relayUrl}/message`, {
+                method: 'POST',
+                headers: this.getAuthHeaders(),
+                body: JSON.stringify({
+                    to: message.to,
+                    from: message.from,
+                    ciphertext: message.ciphertext,
+                    header: message.header,
+                }),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                throw Errors.deliveryFailed(message.to);
+            }
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
     }
-    isConnected() {
-        return this.connected && this.handshakeComplete;
+    async fetchMessages(userId) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const res = await fetch(`${this.relayUrl}/messages/${userId}`, {
+                method: 'GET',
+                headers: this.getAuthHeaders(),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                throw Errors.relayUnavailable();
+            }
+            const data = await res.json();
+            return data.messages || [];
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
     }
-    isAuthenticated() {
-        return this.handshakeComplete && !this.authFailed;
+    disconnect() {
+        this.connected = false;
     }
 }

package/dist/facade/replay-manager.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+// Auto-generated CommonJS wrapper for facade/replay-manager.js
+// This allows `require('@stvor/sdk')` to work alongside ESM `import`.
+
+const mod = require('module');
+const url = require('url');
+
+// Use dynamic import to load the ESM module
+let _cached;
+async function _load() {
+  if (!_cached) {
+    _cached = await import(url.pathToFileURL(__filename.replace(/\.cjs$/, '.js')).href);
+  }
+  return _cached;
+}
+
+// For simple CJS usage, expose a promise-based loader
+module.exports = new Proxy({ load: _load }, {
+  get(target, prop) {
+    if (prop === '__esModule') return true;
+    if (prop === 'then') return undefined; // prevent treating as thenable
+    if (prop === 'load') return _load;
+    if (prop === 'default') {
+      return _load().then(m => m.default);
+    }
+    return _load().then(m => m[prop]);
+  }
+});

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

@@ -1,39 +1,29 @@
 /**
  * STVOR Replay Protection Manager
- * Integrates nonce-based replay protection with in-memory fallback
+ * Implements persistent replay protection with fallback to in-memory
  *
- * ⚠️  CRITICAL LIMITATIONS (v2.1):
+ * VERSION 2.0 - PRODUCTION READY
  *
- * 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
+ * Features:
+ * - Persistent storage interface (Redis, PostgreSQL, etc.)
+ * - In-memory fallback for development
+ * - Proper cleanup of expired entries
+ * - Cache statistics
  */
+export interface IReplayCache {
+    addNonce(userId: string, nonce: string, timestamp: number): Promise<void>;
+    hasNonce(userId: string, nonce: string): Promise<boolean>;
+    cleanup(userId: string, maxAge: number): Promise<number>;
+    getStats(): Promise<{
+        size: number;
+    }>;
+}
+/**
+ * Initialize replay protection with optional persistent storage
+ */
+export declare function initializeReplayProtection(customCache?: IReplayCache): void;
 /**
  * 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>;
 /**
@@ -45,14 +35,17 @@ export declare function validateMessage(userId: string, nonce: string, timestamp
  * Validate message with Uint8Array nonce
  */
 export declare function validateMessageWithNonce(userId: string, nonce: Uint8Array, timestamp: number): Promise<void>;
+/**
+ * Cleanup expired nonces from cache
+ * Should be called periodically in production
+ */
+export declare function cleanupExpiredNonces(): Promise<number>;
 /**
  * Get cache statistics (for monitoring)
  */
-export declare function getCacheStats(): {
+export declare function getCacheStats(): Promise<{
     size: number;
     maxSize: number;
-};
-/**
- * Clear all cached nonces (for testing)
- */
-export declare function clearNonceCache(): void;
+}>;
+export declare function startAutoCleanup(): void;
+export declare function stopAutoCleanup(): void;