@stvor/sdk 2.2.1 → 2.2.2

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/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;

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 {};