@stvor/sdk 2.2.0 → 2.2.2

package/dist/ratchet/key-recovery.js

@@ -0,0 +1,148 @@
+import { randomBytes } from 'crypto';
+import { split, combine } from 'shamirs-secret-sharing';
+import { createHash } from 'crypto';
+import { writeFileSync, readFileSync, existsSync } from 'fs';
+import { createSign, createVerify } from 'crypto';
+/**
+ * Generate recovery key shares using Shamir's Secret Sharing.
+ * @param secret - The secret to split (e.g., a recovery key).
+ * @returns An array of two shares.
+ */
+export function generateRecoveryShares(secret) {
+    return split(secret, { shares: 2, threshold: 2 });
+}
+/**
+ * Combine recovery key shares to reconstruct the secret.
+ * @param shares - An array of shares.
+ * @returns The reconstructed secret.
+ */
+export function combineRecoveryShares(shares) {
+    return combine(shares);
+}
+/**
+ * Lifecycle Management for Recovery Shares
+ */
+const recoveryShares = new Map(); // Simulated storage
+/**
+ * Store recovery shares securely.
+ * @param userId - The user ID.
+ * @param shares - The recovery shares.
+ */
+export function storeRecoveryShares(userId, shares) {
+    recoveryShares.set(userId, shares);
+}
+/**
+ * Retrieve recovery shares for a user.
+ * @param userId - The user ID.
+ * @returns The recovery shares.
+ */
+export function retrieveRecoveryShares(userId) {
+    const shares = recoveryShares.get(userId);
+    if (!shares) {
+        throw new Error('No recovery shares found for user');
+    }
+    return shares;
+}
+/**
+ * Revoke recovery shares for a user.
+ * @param userId - The user ID.
+ */
+export function revokeRecoveryShares(userId) {
+    recoveryShares.delete(userId);
+}
+/**
+ * Tamper-Evidence for Recovery Shares
+ */
+function generateShareHash(share) {
+    return createHash('sha256').update(share).digest('hex');
+}
+export function verifyShareIntegrity(share, expectedHash) {
+    return generateShareHash(share) === expectedHash;
+}
+/**
+ * Honest 2-Man Rule Limitations
+ *
+ * 1. This is NOT enterprise-grade recovery.
+ * 2. No HSM or hardware-backed tamper resistance.
+ * 3. Software-based signatures are vulnerable to compromise.
+ */
+// Append-only log with software-based signing
+const PRIVATE_KEY = process.env.RECOVERY_SIGNING_KEY || '';
+const PUBLIC_KEY = process.env.RECOVERY_VERIFICATION_KEY || '';
+function signRecoveryAction(action) {
+    const sign = createSign('SHA256');
+    sign.update(action);
+    sign.end();
+    return sign.sign(PRIVATE_KEY, 'hex');
+}
+function verifyRecoveryAction(action, signature) {
+    const verify = createVerify('SHA256');
+    verify.update(action);
+    verify.end();
+    return verify.verify(PUBLIC_KEY, signature, 'hex');
+}
+/**
+ * Formal Policy for Recovery Shares
+ */
+const recoveryPolicy = {
+    minAdmins: 2,
+    tamperEvidence: true,
+};
+export function getRecoveryPolicy() {
+    return recoveryPolicy;
+}
+/**
+ * Example Admin Authentication Model
+ */
+export function authenticateAdmin(adminToken) {
+    const validToken = process.env.ADMIN_TOKEN; // Ensure ADMIN_TOKEN is set in the environment
+    return adminToken === validToken;
+}
+/**
+ * Enhanced 2-Man Rule with audit trail and approval flow
+ */
+const AUDIT_LOG_PATH = './audit-log.json';
+function logRecoveryAction(action, userId, adminId) {
+    const logEntry = {
+        timestamp: new Date().toISOString(),
+        action,
+        userId,
+        adminId,
+    };
+    const auditLog = existsSync(AUDIT_LOG_PATH)
+        ? JSON.parse(readFileSync(AUDIT_LOG_PATH, 'utf-8'))
+        : [];
+    auditLog.push(logEntry);
+    writeFileSync(AUDIT_LOG_PATH, JSON.stringify(auditLog, null, 2));
+}
+export function approveRecovery(userId, adminId) {
+    logRecoveryAction('APPROVE_RECOVERY', userId, adminId);
+}
+export function revokeRecovery(userId, adminId) {
+    logRecoveryAction('REVOKE_RECOVERY', userId, adminId);
+}
+/**
+ * Recommendations for enterprise-grade 2-Man Rule
+ *
+ * 1. Use HSM (Hardware Security Modules) for secure key storage.
+ * 2. Implement threshold cryptography for distributed key recovery.
+ * 3. Ensure tamper-proof audit logs with cryptographic integrity checks.
+ * 4. Define a formal compliance process for recovery actions.
+ */
+/**
+ * Example usage:
+ */
+(async () => {
+    // Generate a random recovery key
+    const recoveryKey = randomBytes(32);
+    console.log('Original Recovery Key:', recoveryKey.toString('hex'));
+    // Split the recovery key into two shares
+    const shares = generateRecoveryShares(recoveryKey);
+    console.log('Share 1:', shares[0].toString('hex'));
+    console.log('Share 2:', shares[1].toString('hex'));
+    // Store the shares securely
+    storeRecoveryShares('user1', shares);
+    // Combine the shares to reconstruct the recovery key
+    const reconstructedKey = combineRecoveryShares(shares);
+    console.log('Reconstructed Recovery Key:', reconstructedKey.toString('hex'));
+})();

package/dist/ratchet/replay-protection.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Check if a message is a replay.
+ * @param userId - The user ID sending the message.
+ * @param nonce - The unique nonce for the message.
+ * @returns True if the message is a replay, false otherwise.
+ */
+export declare function isReplay(userId: string, nonce: string): Promise<boolean>;
+/**
+ * Reject messages older than the allowed timestamp.
+ * @param timestamp - The message timestamp.
+ * @returns True if the message is too old, false otherwise.
+ */
+export declare function isTooOld(timestamp: number): boolean;
+/**
+ * Validate a message for replay protection.
+ * @param userId - The user ID sending the message.
+ * @param nonce - The unique nonce for the message.
+ * @param timestamp - The message timestamp.
+ * @throws Error if the message is a replay or too old.
+ */
+export declare function validateMessage(userId: string, nonce: string, timestamp: number): Promise<void>;

package/dist/ratchet/replay-protection.js

@@ -0,0 +1,50 @@
+import { createClient } from 'redis';
+// Redis client setup
+const redis = createClient({
+    url: process.env.REDIS_URL, // Ensure REDIS_URL is set in the environment
+});
+redis.connect();
+const REPLAY_CACHE_PREFIX = 'replay:';
+const MESSAGE_EXPIRY_SECONDS = 300; // 5 minutes
+/**
+ * Check if a message is a replay.
+ * @param userId - The user ID sending the message.
+ * @param nonce - The unique nonce for the message.
+ * @returns True if the message is a replay, false otherwise.
+ */
+export async function isReplay(userId, nonce) {
+    const key = `${REPLAY_CACHE_PREFIX}${userId}:${nonce}`;
+    const exists = await redis.exists(key);
+    if (exists) {
+        return true; // Replay detected
+    }
+    // Store the nonce with an expiry
+    await redis.set(key, '1', {
+        EX: MESSAGE_EXPIRY_SECONDS,
+    });
+    return false;
+}
+/**
+ * Reject messages older than the allowed timestamp.
+ * @param timestamp - The message timestamp.
+ * @returns True if the message is too old, false otherwise.
+ */
+export function isTooOld(timestamp) {
+    const now = Math.floor(Date.now() / 1000); // Current time in seconds
+    return now - timestamp > MESSAGE_EXPIRY_SECONDS;
+}
+/**
+ * Validate a message for replay protection.
+ * @param userId - The user ID sending the message.
+ * @param nonce - The unique nonce for the message.
+ * @param timestamp - The message timestamp.
+ * @throws Error if the message is a replay or too old.
+ */
+export async function validateMessage(userId, nonce, timestamp) {
+    if (isTooOld(timestamp)) {
+        throw new Error('Message rejected: too old');
+    }
+    if (await isReplay(userId, nonce)) {
+        throw new Error('Message rejected: replay detected');
+    }
+}

package/dist/ratchet/tests/ratchet.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ratchet/tests/ratchet.test.js

@@ -0,0 +1,160 @@
+import { initializeCrypto, establishSession, encryptMessage, decryptMessage } from '../index';
+import { validateMessage } from '../replay-protection';
+import { generateFingerprint, verifyFingerprint } from '../tofu';
+import { randomBytes } from 'crypto';
+describe('Ratchet Tests', () => {
+    beforeAll(async () => {
+        await initializeCrypto();
+    });
+    test('Forward Secrecy: Old keys cannot decrypt', () => {
+        const session = establishSession({ publicKey: randomBytes(32), privateKey: randomBytes(32) }, { publicKey: randomBytes(32), privateKey: randomBytes(32) }, randomBytes(32), randomBytes(32), randomBytes(32), randomBytes(32));
+        const message1 = encryptMessage('Hello, World!', session);
+        const message2 = encryptMessage('Goodbye, World!', session);
+        // Simulate key rotation
+        session.chainKey = randomBytes(32);
+        expect(() => decryptMessage(message1.ciphertext, message1.header, session)).toThrow();
+    });
+    test('Replay Protection: Reject duplicate nonces', async () => {
+        const userId = 'user1';
+        const nonce = 'unique-nonce';
+        const timestamp = Math.floor(Date.now() / 1000);
+        await validateMessage(userId, nonce, timestamp);
+        await expect(validateMessage(userId, nonce, timestamp)).rejects.toThrow('Message rejected: replay detected');
+    });
+    test('MITM Detection: Fingerprint mismatch', async () => {
+        const userId = 'user1';
+        const publicKey1 = randomBytes(32);
+        const publicKey2 = randomBytes(32);
+        const fingerprint1 = generateFingerprint(publicKey1);
+        const fingerprint2 = generateFingerprint(publicKey2);
+        await verifyFingerprint(userId, fingerprint1);
+        const result = await verifyFingerprint(userId, fingerprint2);
+        expect(result).toBe(false);
+    });
+});
+describe('2-Man Rule Tests', () => {
+    test('Recovery shares lifecycle', () => {
+        const userId = 'user1';
+        const recoveryKey = randomBytes(32);
+        const shares = generateRecoveryShares(recoveryKey);
+        storeRecoveryShares(userId, shares);
+        const retrievedShares = retrieveRecoveryShares(userId);
+        expect(retrievedShares.length).toBe(2);
+        expect(combineRecoveryShares(retrievedShares)).toEqual(recoveryKey);
+        revokeRecoveryShares(userId);
+        expect(() => retrieveRecoveryShares(userId)).toThrow('No recovery shares found for user');
+    });
+    test('Admin authentication', () => {
+        process.env.ADMIN_TOKEN = 'secure-token';
+        expect(authenticateAdmin('secure-token')).toBe(true);
+        expect(authenticateAdmin('invalid-token')).toBe(false);
+    });
+});
+describe('Double Ratchet Edge Cases', () => {
+    test('Skipped keys DoS protection', () => {
+        const session = {
+            skippedMessageKeys: new Map(),
+        };
+        for (let i = 0; i < MAX_SKIPPED_KEYS; i++) {
+            addSkippedKey(session, { publicKey: randomBytes(32), nonce: randomBytes(12) }, randomBytes(32));
+        }
+        expect(() => addSkippedKey(session, { publicKey: randomBytes(32), nonce: randomBytes(12) }, randomBytes(32))).toThrow('Skipped keys limit exceeded');
+    });
+    test('Simultaneous send handling', () => {
+        const session = {
+            sendingChainKey: randomBytes(32),
+            receivingChainKey: randomBytes(32),
+        };
+        handleSimultaneousSend(session, true);
+        expect(session.sendingChainKey).not.toEqual(session.receivingChainKey);
+    });
+});
+describe('X3DH Edge Cases', () => {
+    test('OPK exhaustion', () => {
+        generateOPKPool();
+        for (let i = 0; i < OPK_POOL_SIZE; i++) {
+            consumeOPK();
+        }
+        expect(() => consumeOPK()).toThrow('OPK pool exhausted');
+    });
+    test('Partial handshake completion', () => {
+        const identityKeyPair = { publicKey: randomBytes(32), privateKey: randomBytes(32) };
+        const signedPreKeyPair = { publicKey: randomBytes(32), privateKey: randomBytes(32) };
+        const oneTimePreKey = randomBytes(32);
+        const recipientIdentityKey = randomBytes(32);
+        const recipientSignedPreKey = randomBytes(32);
+        const recipientOneTimePreKey = randomBytes(32);
+        const recipientSPKSignature = randomBytes(64);
+        expect(() => {
+            establishSession(identityKeyPair, signedPreKeyPair, oneTimePreKey, recipientIdentityKey, recipientSignedPreKey, recipientOneTimePreKey, recipientSPKSignature, '1.0', 'AES-GCM');
+        }).toThrow('Invalid SPK signature');
+    });
+    test('Abort ordering', () => {
+        const identityKeyPair = { publicKey: randomBytes(32), privateKey: randomBytes(32) };
+        const signedPreKeyPair = { publicKey: randomBytes(32), privateKey: randomBytes(32) };
+        const oneTimePreKey = randomBytes(32);
+        const recipientIdentityKey = randomBytes(32);
+        const recipientSignedPreKey = randomBytes(32);
+        const recipientOneTimePreKey = randomBytes(32);
+        const recipientSPKSignature = randomBytes(64);
+        try {
+            establishSession(identityKeyPair, signedPreKeyPair, oneTimePreKey, recipientIdentityKey, recipientSignedPreKey, recipientOneTimePreKey, recipientSPKSignature, '1.0', 'AES-GCM');
+        }
+        catch (error) {
+            expect(error.message).toBe('Invalid SPK signature');
+        }
+    });
+});
+describe('2-Man Rule Integrity', () => {
+    test('Tamper-evidence for recovery shares', () => {
+        const share = randomBytes(32);
+        const hash = generateShareHash(share);
+        expect(verifyShareIntegrity(share, hash)).toBe(true);
+        expect(verifyShareIntegrity(randomBytes(32), hash)).toBe(false);
+    });
+});
+describe('Post-Compromise Security (PCS)', () => {
+    test('PCS recovery after compromise', () => {
+        const session = establishSession({ publicKey: randomBytes(32), privateKey: randomBytes(32) }, { publicKey: randomBytes(32), privateKey: randomBytes(32) }, randomBytes(32), randomBytes(32), randomBytes(32), randomBytes(32));
+        const remotePublicKey = randomBytes(32);
+        // Simulate compromise
+        session.rootKey = randomBytes(32);
+        session.sendingChainKey = randomBytes(32);
+        session.receivingChainKey = randomBytes(32);
+        // Attacker can decrypt messages before recovery
+        const compromisedMessage = encryptMessage('Compromised!', session);
+        expect(() => decryptMessage(compromisedMessage.ciphertext, compromisedMessage.header, session)).not.toThrow();
+        // Perform forced DH ratchet
+        forceDHRatchet(session, remotePublicKey);
+        // Attacker cannot decrypt new messages
+        const recoveredMessage = encryptMessage('Recovered!', session);
+        expect(() => decryptMessage(compromisedMessage.ciphertext, compromisedMessage.header, session)).toThrow();
+        expect(() => decryptMessage(recoveredMessage.ciphertext, recoveredMessage.header, session)).not.toThrow();
+    });
+    test('PCS policy enforcement', () => {
+        const session = establishSession({ publicKey: randomBytes(32), privateKey: randomBytes(32) }, { publicKey: randomBytes(32), privateKey: randomBytes(32) }, randomBytes(32), randomBytes(32), randomBytes(32), randomBytes(32));
+        const remotePublicKey = randomBytes(32);
+        // Simulate message sending
+        for (let i = 0; i < 50; i++) {
+            incrementMessageCounter(session, remotePublicKey);
+        }
+        // Ensure DH ratchet was triggered
+        expect(messageCounter).toBe(0);
+    });
+});
+describe('PCS Security Proofs', () => {
+    test('rootKeyₜ ≠ rootKeyₜ₊₁ even with full attacker knowledge', () => {
+        const session = establishSession({ publicKey: randomBytes(32), privateKey: randomBytes(32) }, { publicKey: randomBytes(32), privateKey: randomBytes(32) }, randomBytes(32), randomBytes(32), randomBytes(32), randomBytes(32));
+        const remotePublicKey = randomBytes(32);
+        // Simulate attacker knowledge
+        const attackerRootKey = session.rootKey;
+        const attackerChainKey = session.sendingChainKey;
+        const attackerReceivingKey = session.receivingChainKey;
+        // Perform DH ratchet
+        receiveNewDHPublicKey(session, remotePublicKey);
+        // Assert that attacker cannot derive the new root key
+        expect(session.rootKey).not.toEqual(attackerRootKey);
+        expect(session.sendingChainKey).not.toEqual(attackerChainKey);
+        expect(session.receivingChainKey).not.toEqual(attackerReceivingKey);
+    });
+});

package/dist/ratchet/tofu.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Generate a SHA-256 fingerprint for a given public key.
+ * @param publicKey - The public key to fingerprint.
+ * @returns The fingerprint as a hex string.
+ */
+export declare function generateFingerprint(publicKey: Uint8Array): string;
+/**
+ * Store the fingerprint in the database.
+ * @param userId - The user ID associated with the fingerprint.
+ * @param fingerprint - The fingerprint to store.
+ */
+export declare function storeFingerprint(userId: string, fingerprint: string): Promise<void>;
+/**
+ * Verify the fingerprint against the stored value.
+ * @param userId - The user ID associated with the fingerprint.
+ * @param fingerprint - The fingerprint to verify.
+ * @returns True if the fingerprint matches, false otherwise.
+ */
+export declare function verifyFingerprint(userId: string, fingerprint: string): Promise<boolean>;
+/**
+ * Honest TOFU Limitations
+ *
+ * 1. First-session MITM risk: The first connection assumes trust.
+ * 2. Fingerprint mismatches result in hard failure.
+ * 3. No automatic recovery from key substitution attacks.
+ */
+export declare function handleFingerprintMismatch(userId: string): void;

package/dist/ratchet/tofu.js

@@ -0,0 +1,62 @@
+import { createHash } from 'crypto';
+import { Pool } from 'pg';
+// PostgreSQL connection pool
+const pool = new Pool({
+    connectionString: process.env.DATABASE_URL, // Ensure DATABASE_URL is set in the environment
+});
+/**
+ * Generate a SHA-256 fingerprint for a given public key.
+ * @param publicKey - The public key to fingerprint.
+ * @returns The fingerprint as a hex string.
+ */
+export function generateFingerprint(publicKey) {
+    const hash = createHash('sha256');
+    hash.update(publicKey);
+    return hash.digest('hex');
+}
+/**
+ * Store the fingerprint in the database.
+ * @param userId - The user ID associated with the fingerprint.
+ * @param fingerprint - The fingerprint to store.
+ */
+export async function storeFingerprint(userId, fingerprint) {
+    const client = await pool.connect();
+    try {
+        await client.query('INSERT INTO fingerprints (user_id, fingerprint) VALUES ($1, $2) ON CONFLICT (user_id) DO UPDATE SET fingerprint = $2', [userId, fingerprint]);
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Verify the fingerprint against the stored value.
+ * @param userId - The user ID associated with the fingerprint.
+ * @param fingerprint - The fingerprint to verify.
+ * @returns True if the fingerprint matches, false otherwise.
+ */
+export async function verifyFingerprint(userId, fingerprint) {
+    const client = await pool.connect();
+    try {
+        const result = await client.query('SELECT fingerprint FROM fingerprints WHERE user_id = $1', [userId]);
+        if (result.rows.length === 0) {
+            // First use: store the fingerprint
+            await storeFingerprint(userId, fingerprint);
+            return true;
+        }
+        return result.rows[0].fingerprint === fingerprint;
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Honest TOFU Limitations
+ *
+ * 1. First-session MITM risk: The first connection assumes trust.
+ * 2. Fingerprint mismatches result in hard failure.
+ * 3. No automatic recovery from key substitution attacks.
+ */
+export function handleFingerprintMismatch(userId) {
+    console.error(`SECURITY ALERT: Fingerprint mismatch detected for user ${userId}`);
+    throw new Error('Fingerprint mismatch detected. Connection aborted.');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stvor/sdk",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "Stvor DX Facade - Simple E2EE SDK for client-side encryption",
   "type": "module",
   "main": "./dist/index.js",