@stvor/sdk 2.4.0 → 3.0.0

package/dist/facade/index.js

@@ -1,5 +1,25 @@
-export * from './app.js';
-export * from './errors.js';
-export * from './types.js';
+/**
+ * STVOR DX Facade SDK
+ * High-level developer experience layer for STVOR E2E encryption
+ *
+ * Design goals:
+ * - Minimal API surface
+ * - Zero crypto knowledge required
+ * - Secure by default
+ * - Opinionated (no configuration)
+ */
 export { StvorError } from './errors.js';
+// Re-export classes and functions
 export { StvorApp, StvorFacadeClient, Stvor, init, createApp } from './app.js';
+export { ErrorCode as STVOR_ERRORS } from './errors.js';
+// Re-export metrics verification for Dashboard
+export { verifyMetricsSignature, MetricsEngine } from './metrics-engine.js';
+// Re-export crypto session management
+export { CryptoSessionManager } from './crypto-session.js';
+export { LocalStorageIdentityStore, LocalStorageSessionStore } from './local-storage-identity-store.js';
+// Re-export replay protection
+export { isReplay, validateMessage, validateMessageWithNonce, getCacheStats, cleanupExpiredNonces, initializeReplayProtection, startAutoCleanup, stopAutoCleanup, } from './replay-manager.js';
+// Re-export Redis replay cache for production
+export { RedisReplayCache } from './redis-replay-cache.js';
+// Re-export TOFU management
+export { generateFingerprint, storeFingerprint, verifyFingerprint, isFingerprintTrusted, getFingerprint, revokeTrust, trustNewFingerprint, listTrustedFingerprints, getFingerprintInfo, initializeTofu, } from './tofu-manager.js';

package/dist/facade/local-storage-identity-store.cjs

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

@@ -0,0 +1,50 @@
+/**
+ * LocalStorage-based Identity Store for browser environments
+ * Implements IIdentityStore for persistent identity key storage
+ */
+import { IIdentityStore } from './crypto-session.js';
+/**
+ * Browser-based identity storage using localStorage
+ * CRITICAL: Keys are stored in base64url — in production, use encrypted storage
+ */
+export declare class LocalStorageIdentityStore implements IIdentityStore {
+    private storageKey;
+    constructor(userId: string, storageKeyPrefix?: string);
+    saveIdentityKeys(userId: string, keys: {
+        identityKeyPair: {
+            publicKey: string;
+            privateKey: string;
+        };
+        signedPreKeyPair: {
+            publicKey: string;
+            privateKey: string;
+        };
+        signedPreKeySignature: string;
+    }): Promise<void>;
+    loadIdentityKeys(userId: string): Promise<{
+        identityKeyPair: {
+            publicKey: string;
+            privateKey: string;
+        };
+        signedPreKeyPair: {
+            publicKey: string;
+            privateKey: string;
+        };
+        signedPreKeySignature: string;
+    } | null>;
+    /** Delete stored keys (for logout / account reset) */
+    deleteIdentityKeys(userId: string): Promise<void>;
+}
+/**
+ * Session storage implementation for browser environments
+ */
+export declare class LocalStorageSessionStore {
+    private storageKey;
+    constructor(userId: string, storageKeyPrefix?: string);
+    saveSession(userId: string, peerId: string, _session: unknown): Promise<void>;
+    loadSession(userId: string, peerId: string): Promise<unknown | null>;
+    deleteSession(userId: string, peerId: string): Promise<void>;
+    listSessions(userId: string): Promise<string[]>;
+    private getAllSessions;
+}
+export default LocalStorageIdentityStore;

package/dist/facade/local-storage-identity-store.js

@@ -0,0 +1,100 @@
+/**
+ * LocalStorage-based Identity Store for browser environments
+ * Implements IIdentityStore for persistent identity key storage
+ */
+/**
+ * Browser-based identity storage using localStorage
+ * CRITICAL: Keys are stored in base64url — in production, use encrypted storage
+ */
+export class LocalStorageIdentityStore {
+    constructor(userId, storageKeyPrefix = 'stvor_identity_') {
+        this.storageKey = `${storageKeyPrefix}${userId}`;
+    }
+    async saveIdentityKeys(userId, keys) {
+        try {
+            const data = {
+                identityKeyPair: keys.identityKeyPair,
+                signedPreKeyPair: keys.signedPreKeyPair,
+                signedPreKeySignature: keys.signedPreKeySignature,
+            };
+            localStorage.setItem(this.storageKey, JSON.stringify(data));
+            console.log(`[LocalStorageIdentityStore] Keys saved for user: ${userId}`);
+        }
+        catch (error) {
+            console.error('[LocalStorageIdentityStore] Failed to save keys:', error);
+            throw new Error('Failed to save identity keys to localStorage');
+        }
+    }
+    async loadIdentityKeys(userId) {
+        try {
+            const data = localStorage.getItem(this.storageKey);
+            if (!data) {
+                console.log(`[LocalStorageIdentityStore] No keys found for user: ${userId}`);
+                return null;
+            }
+            const parsed = JSON.parse(data);
+            console.log(`[LocalStorageIdentityStore] Keys loaded for user: ${userId}`);
+            return {
+                identityKeyPair: parsed.identityKeyPair,
+                signedPreKeyPair: parsed.signedPreKeyPair,
+                signedPreKeySignature: parsed.signedPreKeySignature,
+            };
+        }
+        catch (error) {
+            console.error('[LocalStorageIdentityStore] Failed to load keys:', error);
+            return null;
+        }
+    }
+    /** Delete stored keys (for logout / account reset) */
+    async deleteIdentityKeys(userId) {
+        localStorage.removeItem(this.storageKey);
+        console.log(`[LocalStorageIdentityStore] Keys deleted for user: ${userId}`);
+    }
+}
+/**
+ * Session storage implementation for browser environments
+ */
+export class LocalStorageSessionStore {
+    constructor(userId, storageKeyPrefix = 'stvor_session_') {
+        this.storageKey = `${storageKeyPrefix}${userId}`;
+    }
+    async saveSession(userId, peerId, _session) {
+        try {
+            const allSessions = this.getAllSessions();
+            allSessions[peerId] = { savedAt: Date.now() };
+            localStorage.setItem(this.storageKey, JSON.stringify(allSessions));
+        }
+        catch (error) {
+            console.error('[LocalStorageSessionStore] Failed to save session:', error);
+        }
+    }
+    async loadSession(userId, peerId) {
+        try {
+            const allSessions = this.getAllSessions();
+            return allSessions[peerId] || null;
+        }
+        catch (error) {
+            console.error('[LocalStorageSessionStore] Failed to load session:', error);
+            return null;
+        }
+    }
+    async deleteSession(userId, peerId) {
+        try {
+            const allSessions = this.getAllSessions();
+            delete allSessions[peerId];
+            localStorage.setItem(this.storageKey, JSON.stringify(allSessions));
+        }
+        catch (error) {
+            console.error('[LocalStorageSessionStore] Failed to delete session:', error);
+        }
+    }
+    async listSessions(userId) {
+        const allSessions = this.getAllSessions();
+        return Object.keys(allSessions);
+    }
+    getAllSessions() {
+        const data = localStorage.getItem(this.storageKey);
+        return data ? JSON.parse(data) : {};
+    }
+}
+export default LocalStorageIdentityStore;

package/dist/facade/metrics-attestation.cjs

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

@@ -0,0 +1,209 @@
+/**
+ * STVOR v2.4.0 - Metrics Attestation Engine
+ *
+ * ⚠️  CRITICAL SECURITY MODEL:
+ *
+ * This module ONLY records real E2EE events and creates attestations.
+ * It does NOT verify attestations (that's backend's job).
+ *
+ * Trust boundary:
+ * ┌─────────────────────────────────────────┐
+ * │ SDK (Trusted) - Record + Sign           │
+ * │ ┌─────────────────────────────────────┐ │
+ * │ │ MetricsAttestationEngine            │ │
+ * │ └─────────────────────────────────────┘ │
+ * └──────────────┬──────────────────────────┘
+ *                │ POST /api/metrics/attest
+ *                ▼
+ * ┌─────────────────────────────────────────┐
+ * │ BACKEND (Trusted) - Verify + Store      │
+ * │ ┌─────────────────────────────────────┐ │
+ * │ │ MetricsVerificationService          │ │
+ * │ │ - Check signature                   │ │
+ * │ │ - Check monotonicity                │ │
+ * │ │ - Check anti-replay                 │ │
+ * │ └─────────────────────────────────────┘ │
+ * └──────────────┬──────────────────────────┘
+ *                │ Verified metrics in DB
+ *                ▼
+ * ┌─────────────────────────────────────────┐
+ * │ Dashboard (Untrusted) - Display Only    │
+ * │ - No crypto verification in browser     │
+ * │ - No calculations                       │
+ * │ - No fallback numbers                   │
+ * │ - Only: fetch from /api/metrics         │
+ * └─────────────────────────────────────────┘
+ */
+/**
+ * Raw metrics from SDK (before attestation)
+ * INVARIANT: Only incremented after crypto success
+ */
+export interface RawMetrics {
+    messagesEncrypted: number;
+    messagesDecrypted: number;
+    messagesRejected: number;
+    replayAttempts: number;
+    authFailures: number;
+}
+/**
+ * Attestation = metrics + proof that can be sent to backend
+ * Backend will verify this, not Dashboard
+ */
+export interface MetricsAttestation {
+    metrics: RawMetrics;
+    attestationId: string;
+    timestamp: number;
+    sessionId: string;
+    sequenceNumber: number;
+    proof: string;
+}
+/**
+ * MetricsAttestationEngine
+ *
+ * RESPONSIBILITY: Record real events + create attestations
+ * NOT RESPONSIBLE: Verify attestations (backend does that)
+ */
+export declare class MetricsAttestationEngine {
+    private metrics;
+    private sessionId;
+    private sequenceNumber;
+    private attestationKey;
+    constructor(appToken: string);
+    /**
+     * Record real event: Successful encryption with AEAD
+     * INVARIANT: Only called after cryptoSession.encryptForPeer() succeeds
+     */
+    recordMessageEncrypted(): void;
+    /**
+     * Record real event: Successful decryption with AAD verification
+     * INVARIANT: Only called after cryptoSession.decryptFromPeer() succeeds
+     */
+    recordMessageDecrypted(): void;
+    /**
+     * Record real event: AAD verification failed (auth failure)
+     * INVARIANT: Only called when AEAD auth tag is invalid
+     */
+    recordMessageRejected(): void;
+    /**
+     * Record real event: Replay attack detected
+     * INVARIANT: Only called when nonce is duplicate
+     */
+    recordReplayAttempt(): void;
+    /**
+     * Record real event: Signature verification failed
+     * INVARIANT: Only called on crypto auth failure
+     */
+    recordAuthFailure(): void;
+    /**
+     * Create attestation that can be sent to backend
+     *
+     * Backend MUST verify:
+     * - Signature is valid
+     * - Metrics are monotonic
+     * - Timestamp is within acceptable window
+     * - sessionId matches
+     * - sequenceNumber hasn't been seen before
+     */
+    createAttestation(): MetricsAttestation;
+    /**
+     * Get current metrics snapshot (immutable)
+     * Used for monitoring/debugging, NOT for Dashboard display
+     */
+    getMetrics(): Readonly<RawMetrics>;
+    /**
+     * Internal: Create proof for attestation
+     *
+     * Format:
+     *   proof = HMAC-SHA256(
+     *     JSON.stringify({metrics, sessionId, sequenceNumber, timestamp}),
+     *     attestationKey
+     *   )
+     *
+     * Backend will recompute this with the appToken sent by SDK.
+     * If proof matches, backend knows:
+     * - Metrics came from this SDK instance
+     * - Metrics haven't been tampered
+     * - This is the correct sequence number
+     */
+    private createProof;
+    /**
+     * Derive attestation key from appToken
+     *
+     * HKDF-SHA256 with:
+     * - IKM: appToken
+     * - salt: 32 zero bytes
+     * - info: "stvor-metrics-attestation-v1"
+     *
+     * Result is deterministic: same appToken → same key
+     *
+     * This key is sent to backend for verification.
+     * Backend computes same key from appToken and verifies proof.
+     */
+    private deriveAttestationKey;
+    /**
+     * Generate unique session ID
+     * Used to distinguish different SDK instances
+     */
+    private generateSessionId;
+    /**
+     * Generate unique attestation ID
+     * Used for anti-replay detection
+     */
+    private generateAttestationId;
+}
+/**
+ * Backend Verification Service (Pseudo-code)
+ *
+ * This runs on BACKEND, not in browser or SDK
+ */
+export declare class MetricsVerificationService {
+    /**
+     * Verify attestation received from SDK
+     *
+     * RETURN: VerificationResult
+     */
+    verifyAttestation(attestation: MetricsAttestation, appToken: string, lastSequenceNumber: number): VerificationResult;
+    /**
+     * Verify proof signature (backend-side)
+     */
+    private verifyProof;
+    private deriveAttestationKey;
+    private constantTimeCompare;
+    private hasSeenAttestationId;
+    private getLastVerifiedMetrics;
+}
+export interface VerificationResult {
+    valid: boolean;
+    reason: string;
+}
+/**
+ * SECURITY INVARIANTS (MUST BE ENFORCED)
+ *
+ * I1: Dashboard NEVER generates metric numbers
+ *     ✓ MetricsAttestationEngine records only on crypto success
+ *     ✓ Dashboard only fetches from /api/metrics
+ *
+ * I2: Metrics without backend verification are discarded
+ *     ✓ Backend verifies proof before storing
+ *     ✓ Only verified metrics go to DB
+ *     ✓ Dashboard reads DB, not SDK
+ *
+ * I3: Metric counters are monotonic
+ *     ✓ SDK: counters only increment (never set)
+ *     ✓ Backend: checks sequenceNumber is sequential
+ *     ✓ Backend: checks metrics don't roll back
+ *
+ * I4: Metrics replay is impossible
+ *     ✓ SDK: each attestation has unique attestationId
+ *     ✓ Backend: stores all seen attestationIds
+ *     ✓ Backend: rejects duplicate attestationIds
+ *
+ * I5: Different SDK instances cannot forge each other
+ *     ✓ Each SDK has unique sessionId
+ *     ✓ Backend checks sessionId matches appToken
+ *
+ * I6: appToken compromise ≠ metrics forgery
+ *     ✓ appToken only derives the signing key
+ *     ✓ Backend verifies timestamp is recent
+ *     ✓ Backend checks monotonicity constraints
+ */