@stvor/sdk 2.2.1 → 2.3.0

package/dist/facade/replay-manager.js

@@ -0,0 +1,117 @@
+/**
+ * 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
+ */
+import sodium from 'libsodium-wrappers';
+// In-memory nonce cache (fallback when Redis unavailable)
+// ⚠️  LOST ON RESTART - see limitations above
+const nonceCache = new Map();
+const NONCE_EXPIRY_MS = 5 * 60 * 1000; // 5 minutes
+const MAX_CACHE_SIZE = 10000; // Prevent memory exhaustion
+/**
+ * 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 async function isReplay(userId, nonce, timestamp) {
+    const key = `${userId}:${nonce}`;
+    const now = Date.now();
+    // Check if nonce already seen
+    const cached = nonceCache.get(key);
+    if (cached) {
+        // Replay detected
+        return true;
+    }
+    // Check if message is too old
+    const messageAge = now - timestamp * 1000;
+    if (messageAge > NONCE_EXPIRY_MS) {
+        throw new Error('Message rejected: too old');
+    }
+    // Store nonce with timestamp
+    nonceCache.set(key, { timestamp: now });
+    // Cleanup old entries if cache is too large
+    if (nonceCache.size > MAX_CACHE_SIZE) {
+        await cleanupExpiredNonces();
+    }
+    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 = sodium.to_hex(nonce);
+    await validateMessage(userId, nonceHex, timestamp);
+}
+/**
+ * Cleanup expired nonces from cache
+ */
+async function cleanupExpiredNonces() {
+    const now = Date.now();
+    let cleaned = 0;
+    for (const [key, value] of nonceCache.entries()) {
+        if (now - value.timestamp > NONCE_EXPIRY_MS) {
+            nonceCache.delete(key);
+            cleaned++;
+        }
+    }
+    if (cleaned > 0) {
+        console.log(`[ReplayProtection] Cleaned ${cleaned} expired nonces`);
+    }
+}
+/**
+ * Get cache statistics (for monitoring)
+ */
+export function getCacheStats() {
+    return {
+        size: nonceCache.size,
+        maxSize: MAX_CACHE_SIZE,
+    };
+}
+/**
+ * Clear all cached nonces (for testing)
+ */
+export function clearNonceCache() {
+    nonceCache.clear();
+}
+// Periodic cleanup (every 5 minutes)
+if (typeof setInterval !== 'undefined') {
+    setInterval(cleanupExpiredNonces, 5 * 60 * 1000);
+}

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.d.ts

@@ -0,0 +1,80 @@
+/**
+ * STVOR TOFU (Trust On First Use) Manager
+ * Integrates fingerprint verification with in-memory fallback
+ *
+ * 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)
+ * - Reinstall: fingerprint lost (in-memory only)
+ *
+ * LIMITATIONS:
+ * - First-use MITM vulnerability (standard TOFU)
+ * - No persistence (keys lost on restart)
+ * - No out-of-band verification UX
+ *
+ * TODO:
+ * - Add persistent storage (IndexedDB/localStorage)
+ * - Add manual verification UI (compare fingerprints)
+ * - Add key rotation notification system
+ */
+interface FingerprintRecord {
+    fingerprint: string;
+    firstSeen: Date;
+    version: number;
+}
+/**
+ * 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 (in-memory fallback)
+ */
+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)
+ *
+ * KEY ROTATION:
+ * - Automatic rotation NOT supported
+ * - Requires manual trustNewFingerprint() call
+ * - Otherwise connection fails on mismatch
+ *
+ * @throws Error on fingerprint mismatch (possible MITM or key rotation)
+ */
+export declare function verifyFingerprint(userId: string, identityPublicKey: Uint8Array): Promise<boolean>;
+/**
+ * Manually trust a new fingerprint (key rotation)
+ *
+ * USE CASES:
+ * - User reinstalled app and lost keys
+ * - Legitimate key rotation after compromise
+ * - Migration from old device
+ *
+ * SECURITY: Should be called ONLY after out-of-band verification
+ */
+export declare function trustNewFingerprint(userId: string, identityPublicKey: Uint8Array): Promise<void>;
+/**
+ * Get stored fingerprint record for user
+ */
+export declare function getStoredFingerprint(userId: string): FingerprintRecord | undefined;
+/**
+ * Format fingerprint for display (groups of 4 hex chars)
+ * Example: "a3f2 d8c1 5e90 7b4a ..."
+ */
+export declare function formatFingerprint(fingerprint: string): string;
+/**
+ * Clear all stored fingerprints (TESTING ONLY)
+ */
+export declare function clearFingerprints(): void;
+export {};

package/dist/facade/tofu-manager.js

@@ -0,0 +1,134 @@
+/**
+ * STVOR TOFU (Trust On First Use) Manager
+ * Integrates fingerprint verification with in-memory fallback
+ *
+ * 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)
+ * - Reinstall: fingerprint lost (in-memory only)
+ *
+ * LIMITATIONS:
+ * - First-use MITM vulnerability (standard TOFU)
+ * - No persistence (keys lost on restart)
+ * - No out-of-band verification UX
+ *
+ * TODO:
+ * - Add persistent storage (IndexedDB/localStorage)
+ * - Add manual verification UI (compare fingerprints)
+ * - Add key rotation notification system
+ */
+import sodium from 'libsodium-wrappers';
+// In-memory fingerprint cache (fallback when PostgreSQL unavailable)
+const fingerprintCache = new Map();
+const FINGERPRINT_VERSION = 1; // Increment on breaking changes
+/**
+ * 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 = sodium.crypto_generichash(32, identityPublicKey);
+    return sodium.to_hex(hash);
+}
+/**
+ * Store fingerprint for user (in-memory fallback)
+ */
+export async function storeFingerprint(userId, fingerprint) {
+    const record = {
+        fingerprint,
+        firstSeen: new Date(),
+        version: FINGERPRINT_VERSION,
+    };
+    fingerprintCache.set(userId, record);
+    // TODO: Add PostgreSQL persistence when available
+    // try {
+    //   await pool.query(
+    //     'INSERT INTO fingerprints (user_id, fingerprint, first_seen, version) VALUES ($1, $2, $3, $4) ON CONFLICT (user_id) DO UPDATE SET fingerprint = $2',
+    //     [userId, fingerprint, record.firstSeen, record.version]
+    //   );
+    // } catch (error) {
+    //   // Fallback to in-memory storage
+    //   fingerprintCache.set(userId, record);
+    // }
+}
+/**
+ * Verify fingerprint against stored value
+ *
+ * BEHAVIOR:
+ * - First use: stores fingerprint, returns true
+ * - Match: returns true
+ * - Mismatch: throws error (HARD FAILURE)
+ *
+ * KEY ROTATION:
+ * - Automatic rotation NOT supported
+ * - Requires manual trustNewFingerprint() call
+ * - Otherwise connection fails on mismatch
+ *
+ * @throws Error on fingerprint mismatch (possible MITM or key rotation)
+ */
+export async function verifyFingerprint(userId, identityPublicKey) {
+    const fingerprint = generateFingerprint(identityPublicKey);
+    // Check in-memory cache first
+    const storedRecord = fingerprintCache.get(userId);
+    if (!storedRecord) {
+        // First use - store fingerprint
+        await storeFingerprint(userId, fingerprint);
+        console.log(`[TOFU] ✓ First contact: ${userId} (${fingerprint.slice(0, 16)}...)`);
+        return true;
+    }
+    // Verify fingerprint matches
+    if (storedRecord.fingerprint !== fingerprint) {
+        throw new Error(`[TOFU] ✗ SECURITY ALERT: Identity key mismatch for ${userId}\n` +
+            `  Expected: ${storedRecord.fingerprint.slice(0, 16)}...\n` +
+            `  Received: ${fingerprint.slice(0, 16)}...\n` +
+            `  First seen: ${storedRecord.firstSeen.toISOString()}\n\n` +
+            `POSSIBLE CAUSES:\n` +
+            `  1. MITM attack (key substitution)\n` +
+            `  2. User reinstalled app (legitimate key rotation)\n` +
+            `  3. Multi-device not supported (different keys)\n\n` +
+            `ACTION: Verify out-of-band or call trustNewFingerprint()`);
+    }
+    return true;
+}
+/**
+ * Manually trust a new fingerprint (key rotation)
+ *
+ * USE CASES:
+ * - User reinstalled app and lost keys
+ * - Legitimate key rotation after compromise
+ * - Migration from old device
+ *
+ * SECURITY: Should be called ONLY after out-of-band verification
+ */
+export async function trustNewFingerprint(userId, identityPublicKey) {
+    const fingerprint = generateFingerprint(identityPublicKey);
+    const oldRecord = fingerprintCache.get(userId);
+    await storeFingerprint(userId, fingerprint);
+    console.log(`[TOFU] ⚠️  Manually trusted new identity for ${userId}\n` +
+        `  Old: ${oldRecord?.fingerprint.slice(0, 16) || 'none'}...\n` +
+        `  New: ${fingerprint.slice(0, 16)}...`);
+}
+/**
+ * Get stored fingerprint record for user
+ */
+export function getStoredFingerprint(userId) {
+    return fingerprintCache.get(userId);
+}
+/**
+ * Format fingerprint for display (groups of 4 hex chars)
+ * Example: "a3f2 d8c1 5e90 7b4a ..."
+ */
+export function formatFingerprint(fingerprint) {
+    return fingerprint.match(/.{1,4}/g)?.join(' ') || fingerprint;
+}
+/**
+ * Clear all stored fingerprints (TESTING ONLY)
+ */
+export function clearFingerprints() {
+    fingerprintCache.clear();
+}

package/dist/ratchet/index.d.ts

@@ -0,0 +1,88 @@
+/**
+ * X3DH + Double Ratchet Implementation
+ * This module handles session establishment and message encryption/decryption.
+ */
+export interface SessionState {
+    identityKey: Uint8Array;
+    signedPreKey: Uint8Array;
+    oneTimePreKey: Uint8Array;
+    rootKey: Uint8Array;
+    sendingChainKey: Uint8Array;
+    receivingChainKey: Uint8Array;
+    skippedMessageKeys: Map<string, Uint8Array>;
+    isPostCompromise: boolean;
+}
+export declare function initializeCrypto(): Promise<void>;
+/**
+ * X3DH Session Establishment
+ * @param identityKeyPair - The user's identity key pair
+ * @param signedPreKeyPair - The user's signed pre-key pair
+ * @param oneTimePreKey - A one-time pre-key
+ * @param recipientIdentityKey - The recipient's identity key
+ * @param recipientSignedPreKey - The recipient's signed pre-key
+ * @param recipientOneTimePreKey - The recipient's one-time pre-key
+ * @param recipientSPKSignature - Signature of SPK by recipient's identity key
+ * @param protocolVersion - The protocol version
+ * @param cipherSuite - The cipher suite
+ * @returns SessionState
+ */
+export declare function establishSession(identityKeyPair: {
+    publicKey: Uint8Array;
+    privateKey: Uint8Array;
+}, signedPreKeyPair: {
+    publicKey: Uint8Array;
+    privateKey: Uint8Array;
+}, oneTimePreKey: Uint8Array, recipientIdentityKey: Uint8Array, recipientSignedPreKey: Uint8Array, recipientOneTimePreKey: Uint8Array, recipientSPKSignature: Uint8Array, protocolVersion: string, cipherSuite: string): SessionState;
+/**
+ * Double Ratchet Encryption
+ * @param plaintext - The message to encrypt
+ * @param session - The current session state
+ * @returns { ciphertext: Uint8Array; header: { publicKey: Uint8Array; nonce: Uint8Array } }
+ */
+export declare function encryptMessage(plaintext: string, session: SessionState): {
+    ciphertext: any;
+    header: {
+        publicKey: any;
+        nonce: any;
+    };
+};
+/**
+ * Double Ratchet Decryption
+ * @param ciphertext - The encrypted message
+ * @param header - The message header containing the sender's public key and nonce
+ * @param session - The current session state
+ * @returns The decrypted plaintext
+ */
+export declare function decryptMessage(ciphertext: Uint8Array, header: {
+    publicKey: Uint8Array;
+    nonce: Uint8Array;
+}, session: SessionState): string;
+export declare function addSkippedKey(session: SessionState, header: {
+    publicKey: Uint8Array;
+    nonce: Uint8Array;
+}, messageKey: Uint8Array): void;
+export declare function removeSkippedKey(session: SessionState, header: {
+    publicKey: Uint8Array;
+    nonce: Uint8Array;
+}): void;
+export declare function processSkippedKeys(session: SessionState): void;
+export declare function handleSimultaneousSend(session: SessionState, isInitiator: boolean): void;
+export declare function generateOPKPool(): void;
+export declare function consumeOPKAtomically(userId: string): Uint8Array;
+export declare function enforceDHRatchetPolicy(session: SessionState, remotePublicKey: Uint8Array, suspectedCompromise?: boolean): void;
+/**
+ * Increment message counter and enforce policy.
+ */
+export declare function incrementMessageCounter(session: SessionState, remotePublicKey: Uint8Array): void;
+/**
+ * Force a DH ratchet step to enable PCS.
+ * @param session - The current session state.
+ * @param remotePublicKey - The remote party's ephemeral public key.
+ */
+export declare function forceDHRatchet(session: SessionState, remotePublicKey: Uint8Array): void;
+/**
+ * Trigger PCS recovery only after receiving a new DH public key.
+ * @param session - The current session state.
+ * @param remotePublicKey - The new DH public key from the remote party.
+ */
+export declare function receiveNewDHPublicKey(session: SessionState, remotePublicKey: Uint8Array): void;