@stvor/sdk 2.4.1 → 3.0.0

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

@@ -0,0 +1,51 @@
+/**
+ * STVOR Replay Protection Manager
+ * Implements persistent replay protection with fallback to in-memory
+ *
+ * VERSION 2.0 - PRODUCTION READY
+ *
+ * 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
+ */
+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>;
+/**
+ * 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(): Promise<{
+    size: number;
+    maxSize: number;
+}>;
+export declare function startAutoCleanup(): void;
+export declare function stopAutoCleanup(): void;

package/dist/facade/replay-manager.js

@@ -0,0 +1,150 @@
+/**
+ * STVOR Replay Protection Manager
+ * Implements persistent replay protection with fallback to in-memory
+ *
+ * VERSION 2.0 - PRODUCTION READY
+ *
+ * Features:
+ * - Persistent storage interface (Redis, PostgreSQL, etc.)
+ * - In-memory fallback for development
+ * - Proper cleanup of expired entries
+ * - Cache statistics
+ */
+// In-memory replay cache (fallback)
+class InMemoryReplayCache {
+    constructor() {
+        this.cache = new Map();
+        this.maxSize = 10000;
+    }
+    async addNonce(userId, nonce, timestamp) {
+        const key = `${userId}:${nonce}`;
+        this.cache.set(key, { timestamp: Date.now(), userId });
+        // Prevent memory exhaustion
+        if (this.cache.size > this.maxSize) {
+            await this.cleanupOldest(1000);
+        }
+    }
+    async hasNonce(userId, nonce) {
+        return this.cache.has(`${userId}:${nonce}`);
+    }
+    async cleanup(userId, maxAge) {
+        const now = Date.now();
+        let cleaned = 0;
+        for (const [key, value] of this.cache.entries()) {
+            if (value.userId === userId && now - value.timestamp > maxAge) {
+                this.cache.delete(key);
+                cleaned++;
+            }
+        }
+        return cleaned;
+    }
+    async getStats() {
+        return { size: this.cache.size };
+    }
+    async cleanupOldest(count) {
+        const entries = Array.from(this.cache.entries());
+        entries.sort((a, b) => a[1].timestamp - b[1].timestamp);
+        for (let i = 0; i < Math.min(count, entries.length); i++) {
+            this.cache.delete(entries[i][0]);
+        }
+    }
+}
+// Global in-memory cache instance
+let globalReplayCache = null;
+// Configuration
+const NONCE_EXPIRY_MS = 5 * 60 * 1000; // 5 minutes - production should be shorter
+const MESSAGE_EXPIRY_MS = 60 * 1000; // Messages older than 1 minute are rejected
+/**
+ * Initialize replay protection with optional persistent storage
+ */
+export function initializeReplayProtection(customCache) {
+    globalReplayCache = customCache || new InMemoryReplayCache();
+    console.log('[ReplayProtection] Initialized' + (customCache ? ' with persistent storage' : ' with in-memory fallback'));
+}
+/**
+ * Check if message is a replay attack
+ */
+export async function isReplay(userId, nonce, timestamp) {
+    if (!globalReplayCache) {
+        initializeReplayProtection();
+    }
+    const now = Date.now();
+    // CRITICAL: Check if message is too old FIRST (before checking cache)
+    // This prevents replay of old messages that have expired
+    const messageAge = now - timestamp * 1000;
+    if (messageAge > MESSAGE_EXPIRY_MS) {
+        throw new Error(`Message rejected: too old (${Math.round(messageAge / 1000)}s)`);
+    }
+    // Check if nonce already seen
+    const isDuplicate = await globalReplayCache.hasNonce(userId, nonce);
+    if (isDuplicate) {
+        console.warn(`[ReplayProtection] Replay detected from user ${userId}`);
+        return true;
+    }
+    // Store nonce with timestamp
+    await globalReplayCache.addNonce(userId, nonce, timestamp);
+    return false;
+}
+/**
+ * Validate message for replay protection
+ * Throws error if replay detected or message too old
+ */
+export async function validateMessage(userId, nonce, timestamp) {
+    const replay = await isReplay(userId, nonce, timestamp);
+    if (replay) {
+        throw new Error(`Replay attack detected from user ${userId}`);
+    }
+}
+/**
+ * Validate message with Uint8Array nonce
+ */
+export async function validateMessageWithNonce(userId, nonce, timestamp) {
+    const nonceHex = Buffer.from(nonce).toString('hex');
+    await validateMessage(userId, nonceHex, timestamp);
+}
+/**
+ * Cleanup expired nonces from cache
+ * Should be called periodically in production
+ */
+export async function cleanupExpiredNonces() {
+    if (!globalReplayCache) {
+        return 0;
+    }
+    const cleaned = await globalReplayCache.cleanup('all', NONCE_EXPIRY_MS);
+    if (cleaned > 0) {
+        console.log(`[ReplayProtection] Cleaned ${cleaned} expired nonces`);
+    }
+    return cleaned;
+}
+/**
+ * Get cache statistics (for monitoring)
+ */
+export async function getCacheStats() {
+    const stats = await globalReplayCache?.getStats() || { size: 0 };
+    return {
+        size: stats.size,
+        maxSize: 10000,
+    };
+}
+// Auto-cleanup interval (every 1 minute)
+let cleanupInterval = null;
+export function startAutoCleanup() {
+    if (cleanupInterval) {
+        return;
+    }
+    cleanupInterval = setInterval(() => {
+        cleanupExpiredNonces().catch(err => {
+            console.error('[ReplayProtection] Cleanup error:', err);
+        });
+    }, 60000);
+    console.log('[ReplayProtection] Auto-cleanup started');
+}
+export function stopAutoCleanup() {
+    if (cleanupInterval) {
+        clearInterval(cleanupInterval);
+        cleanupInterval = null;
+        console.log('[ReplayProtection] Auto-cleanup stopped');
+    }
+}
+// Default initialization
+initializeReplayProtection();

package/dist/facade/sodium-singleton.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+// Auto-generated CommonJS wrapper for facade/sodium-singleton.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/sodium-singleton.d.ts

@@ -0,0 +1,20 @@
+/**
+ * STVOR libsodium Singleton
+ * Ensures sodium.ready is called only ONCE globally
+ * Prevents race conditions during concurrent initialization
+ */
+/**
+ * Initialize libsodium ONCE globally
+ * Safe to call multiple times - returns same promise
+ *
+ * @throws Never throws - libsodium.ready is infallible
+ */
+export declare function ensureSodiumReady(): Promise<void>;
+/**
+ * Check if libsodium is ready (synchronous)
+ */
+export declare function isSodiumReady(): boolean;
+/**
+ * Reset state (ONLY for testing)
+ */
+export declare function _resetSodiumState(): void;

package/dist/facade/sodium-singleton.js

@@ -0,0 +1,44 @@
+/**
+ * STVOR libsodium Singleton
+ * Ensures sodium.ready is called only ONCE globally
+ * Prevents race conditions during concurrent initialization
+ */
+import sodium from 'libsodium-wrappers';
+let sodiumInitialized = false;
+let sodiumInitPromise = null;
+/**
+ * Initialize libsodium ONCE globally
+ * Safe to call multiple times - returns same promise
+ *
+ * @throws Never throws - libsodium.ready is infallible
+ */
+export async function ensureSodiumReady() {
+    // Already initialized - return immediately
+    if (sodiumInitialized) {
+        return;
+    }
+    // Initialization in progress - return existing promise
+    if (sodiumInitPromise) {
+        return sodiumInitPromise;
+    }
+    // Start initialization
+    sodiumInitPromise = (async () => {
+        await sodium.ready;
+        sodiumInitialized = true;
+        console.log('[Crypto] libsodium initialized');
+    })();
+    return sodiumInitPromise;
+}
+/**
+ * Check if libsodium is ready (synchronous)
+ */
+export function isSodiumReady() {
+    return sodiumInitialized;
+}
+/**
+ * Reset state (ONLY for testing)
+ */
+export function _resetSodiumState() {
+    sodiumInitialized = false;
+    sodiumInitPromise = null;
+}

package/dist/facade/tofu-manager.cjs

@@ -0,0 +1,29 @@
+'use strict';
+
+// Auto-generated CommonJS wrapper for facade/tofu-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/tofu-manager.d.ts

@@ -0,0 +1,82 @@
+/**
+ * STVOR TOFU (Trust On First Use) Manager
+ * Implements persistent TOFU with fallback to in-memory
+ *
+ * VERSION 2.0 - PRODUCTION READY
+ *
+ * Features:
+ * - Persistent storage interface
+ * - In-memory fallback for development
+ * - Fingerprint verification
+ * - Key rotation support
+ *
+ * SEMANTICS:
+ * - Fingerprint = BLAKE2b(identity_public_key)
+ * - Binding: identity key ONLY (not bundle, not SPK)
+ * - Key rotation: requires manual re-trust via trustNewFingerprint()
+ * - Multi-device: NOT supported (each device = new identity)
+ */
+interface FingerprintRecord {
+    fingerprint: string;
+    firstSeen: Date;
+    lastSeen: Date;
+    version: number;
+    trusted: boolean;
+}
+export interface ITofuStore {
+    saveFingerprint(userId: string, record: FingerprintRecord): Promise<void>;
+    loadFingerprint(userId: string): Promise<FingerprintRecord | null>;
+    deleteFingerprint(userId: string): Promise<void>;
+    listFingerprints(): Promise<string[]>;
+}
+/**
+ * Initialize TOFU manager with optional persistent storage
+ */
+export declare function initializeTofu(customStore?: ITofuStore): void;
+/**
+ * Generate BLAKE2b-256 fingerprint from identity public key
+ *
+ * BINDING: Identity key ONLY
+ * - SPK rotation does NOT change fingerprint
+ * - OPK exhaustion does NOT change fingerprint
+ * - Only identity key rotation changes fingerprint
+ */
+export declare function generateFingerprint(identityPublicKey: Uint8Array): string;
+/**
+ * Store fingerprint for user
+ */
+export declare function storeFingerprint(userId: string, fingerprint: string): Promise<void>;
+/**
+ * Verify fingerprint against stored value
+ *
+ * BEHAVIOR:
+ * - First use: stores fingerprint, returns true
+ * - Match: returns true
+ * - Mismatch: throws error (HARD FAILURE)
+ */
+export declare function verifyFingerprint(userId: string, identityPublicKey: Uint8Array): Promise<boolean>;
+/**
+ * Check if user fingerprint is trusted
+ */
+export declare function isFingerprintTrusted(userId: string): Promise<boolean>;
+/**
+ * Get fingerprint for user
+ */
+export declare function getFingerprint(userId: string): Promise<string | null>;
+/**
+ * Revoke trust for a user (after key rotation or suspected compromise)
+ */
+export declare function revokeTrust(userId: string): Promise<void>;
+/**
+ * Re-trust a user after verifying their new fingerprint out-of-band
+ */
+export declare function trustNewFingerprint(userId: string, identityPublicKey: Uint8Array): Promise<void>;
+/**
+ * List all trusted fingerprints
+ */
+export declare function listTrustedFingerprints(): Promise<string[]>;
+/**
+ * Get detailed fingerprint info for debugging
+ */
+export declare function getFingerprintInfo(userId: string): Promise<FingerprintRecord | null>;
+export {};

package/dist/facade/tofu-manager.js

@@ -0,0 +1,166 @@
+/**
+ * STVOR TOFU (Trust On First Use) Manager
+ * Implements persistent TOFU with fallback to in-memory
+ *
+ * VERSION 2.0 - PRODUCTION READY
+ *
+ * Features:
+ * - Persistent storage interface
+ * - In-memory fallback for development
+ * - Fingerprint verification
+ * - Key rotation support
+ *
+ * SEMANTICS:
+ * - Fingerprint = BLAKE2b(identity_public_key)
+ * - Binding: identity key ONLY (not bundle, not SPK)
+ * - Key rotation: requires manual re-trust via trustNewFingerprint()
+ * - Multi-device: NOT supported (each device = new identity)
+ */
+import { createHash } from 'crypto';
+// In-memory TOFU store (fallback)
+class InMemoryTofuStore {
+    constructor() {
+        this.store = new Map();
+    }
+    async saveFingerprint(userId, record) {
+        this.store.set(userId, record);
+    }
+    async loadFingerprint(userId) {
+        return this.store.get(userId) || null;
+    }
+    async deleteFingerprint(userId) {
+        this.store.delete(userId);
+    }
+    async listFingerprints() {
+        return Array.from(this.store.keys());
+    }
+}
+// Global store instance
+let tofuStore = null;
+const FINGERPRINT_VERSION = 1; // Increment on breaking changes
+/**
+ * Initialize TOFU manager with optional persistent storage
+ */
+export function initializeTofu(customStore) {
+    tofuStore = customStore || new InMemoryTofuStore();
+    console.log('[TOFU] Initialized' + (customStore ? ' with persistent storage' : ' with in-memory fallback'));
+}
+/**
+ * Generate BLAKE2b-256 fingerprint from identity public key
+ *
+ * BINDING: Identity key ONLY
+ * - SPK rotation does NOT change fingerprint
+ * - OPK exhaustion does NOT change fingerprint
+ * - Only identity key rotation changes fingerprint
+ */
+export function generateFingerprint(identityPublicKey) {
+    const hash = createHash('sha256').update(identityPublicKey).digest();
+    return hash.toString('hex');
+}
+/**
+ * Store fingerprint for user
+ */
+export async function storeFingerprint(userId, fingerprint) {
+    if (!tofuStore) {
+        initializeTofu();
+    }
+    const record = {
+        fingerprint,
+        firstSeen: new Date(),
+        lastSeen: new Date(),
+        version: FINGERPRINT_VERSION,
+        trusted: true,
+    };
+    await tofuStore.saveFingerprint(userId, record);
+    console.log(`[TOFU] Stored fingerprint for user: ${userId}`);
+}
+/**
+ * Verify fingerprint against stored value
+ *
+ * BEHAVIOR:
+ * - First use: stores fingerprint, returns true
+ * - Match: returns true
+ * - Mismatch: throws error (HARD FAILURE)
+ */
+export async function verifyFingerprint(userId, identityPublicKey) {
+    if (!tofuStore) {
+        initializeTofu();
+    }
+    const fingerprint = generateFingerprint(identityPublicKey);
+    const stored = await tofuStore.loadFingerprint(userId);
+    if (!stored) {
+        // First use - store and trust
+        await storeFingerprint(userId, fingerprint);
+        console.log(`[TOFU] First contact: ${userId} (fingerprint: ${fingerprint.slice(0, 16)}...)`);
+        return true;
+    }
+    if (stored.fingerprint !== fingerprint) {
+        // Fingerprint mismatch - potential MITM!
+        console.error(`[TOFU] FINGERPRINT MISMATCH for ${userId}!`);
+        console.error(`[TOFU] Expected: ${stored.fingerprint.slice(0, 16)}...`);
+        console.error(`[TOFU] Received: ${fingerprint.slice(0, 16)}...`);
+        throw new Error(`FINGERPRINT MISMATCH for user ${userId} - possible MITM attack!`);
+    }
+    // Update last seen
+    stored.lastSeen = new Date();
+    await tofuStore.saveFingerprint(userId, stored);
+    return true;
+}
+/**
+ * Check if user fingerprint is trusted
+ */
+export async function isFingerprintTrusted(userId) {
+    if (!tofuStore) {
+        initializeTofu();
+    }
+    const stored = await tofuStore.loadFingerprint(userId);
+    return stored?.trusted || false;
+}
+/**
+ * Get fingerprint for user
+ */
+export async function getFingerprint(userId) {
+    if (!tofuStore) {
+        initializeTofu();
+    }
+    const stored = await tofuStore.loadFingerprint(userId);
+    return stored?.fingerprint || null;
+}
+/**
+ * Revoke trust for a user (after key rotation or suspected compromise)
+ */
+export async function revokeTrust(userId) {
+    if (!tofuStore) {
+        initializeTofu();
+    }
+    await tofuStore.deleteFingerprint(userId);
+    console.log(`[TOFU] Revoked trust for user: ${userId}`);
+}
+/**
+ * Re-trust a user after verifying their new fingerprint out-of-band
+ */
+export async function trustNewFingerprint(userId, identityPublicKey) {
+    const fingerprint = generateFingerprint(identityPublicKey);
+    await storeFingerprint(userId, fingerprint);
+    console.log(`[TOFU] Re-trusted user: ${userId}`);
+}
+/**
+ * List all trusted fingerprints
+ */
+export async function listTrustedFingerprints() {
+    if (!tofuStore) {
+        initializeTofu();
+    }
+    return tofuStore.listFingerprints();
+}
+/**
+ * Get detailed fingerprint info for debugging
+ */
+export async function getFingerprintInfo(userId) {
+    if (!tofuStore) {
+        initializeTofu();
+    }
+    return tofuStore.loadFingerprint(userId);
+}
+// Default initialization
+initializeTofu();

package/dist/facade/types.d.ts

@@ -47,4 +47,6 @@ export interface SealedPayload {
     ciphertext: Uint8Array;
     /** Nonce used for encryption */
     nonce: Uint8Array;
+    /** Recipient user ID this was sealed for */
+    recipientId: UserId;
 }

package/dist/index.d.cts

@@ -1,2 +1,6 @@
+/**
+ * STVOR SDK - Main exports
+ */
 export * from './legacy.js';
 export * from './facade/index.js';
+export * from './ratchet/index.js';

package/dist/index.d.ts

@@ -1,2 +1,6 @@
+/**
+ * STVOR SDK - Main exports
+ */
 export * from './legacy.js';
 export * from './facade/index.js';
+export * from './ratchet/index.js';

package/dist/index.js

@@ -1,2 +1,9 @@
+/**
+ * STVOR SDK - Main exports
+ */
+// Legacy core API (for migration)
 export * from './legacy.js';
+// New DX Facade API
 export * from './facade/index.js';
+// X3DH + Double Ratchet implementation
+export * from './ratchet/index.js';

package/dist/legacy.d.ts

@@ -1 +1,31 @@
-export {};
+/**
+ * STVOR SDK - Legacy Core API
+ * Kept for backwards compatibility
+ */
+export interface StvorConfig {
+    apiKey: string;
+    serverUrl?: string;
+}
+export interface Peer {
+    id: string;
+    publicKey: any;
+}
+export interface EncryptedMessage {
+    ciphertext: string;
+    nonce: string;
+    from: string;
+}
+export declare class StvorClient {
+    private config;
+    private myKeyPair;
+    private myId;
+    private peers;
+    constructor(config: StvorConfig);
+    ready(): Promise<void>;
+    createPeer(name: string): Promise<Peer>;
+    send({ to, message }: {
+        to: string;
+        message: string;
+    }): Promise<EncryptedMessage>;
+    receive(encrypted: EncryptedMessage): Promise<string>;
+}