@stvor/sdk 2.2.1 → 2.3.0

package/dist/ratchet/index.js

@@ -0,0 +1,318 @@
+import sodium from 'libsodium-wrappers';
+import { ensureSodiumReady } from '../facade/sodium-singleton.js';
+// Initialize libsodium (safe to call multiple times)
+export async function initializeCrypto() {
+    await ensureSodiumReady();
+}
+/**
+ * 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 function establishSession(identityKeyPair, signedPreKeyPair, oneTimePreKey, recipientIdentityKey, recipientSignedPreKey, recipientOneTimePreKey, recipientSPKSignature, protocolVersion, cipherSuite) {
+    // Validate protocol version and cipher suite
+    validateProtocolVersion(protocolVersion);
+    validateCipherSuite(cipherSuite);
+    // Verify SPK signature
+    verifySPKSignature(recipientSignedPreKey, recipientSPKSignature, recipientIdentityKey);
+    // Derive shared secret with cryptographic binding
+    const sharedSecret = deriveSharedSecret(identityKeyPair.publicKey, recipientSignedPreKey, recipientOneTimePreKey, protocolVersion, cipherSuite);
+    if (!sharedSecret) {
+        throw new Error('Failed to derive shared secret');
+    }
+    // Derive root key
+    const rootKey = deriveKey(sharedSecret, 'x3dh-root-key', sodium.from_string(protocolVersion));
+    return {
+        identityKey: identityKeyPair.publicKey,
+        signedPreKey: signedPreKeyPair.publicKey,
+        oneTimePreKey,
+        rootKey,
+        sendingChainKey: rootKey,
+        receivingChainKey: rootKey,
+        skippedMessageKeys: new Map(),
+        isPostCompromise: false,
+    };
+}
+/**
+ * Double Ratchet Encryption
+ * @param plaintext - The message to encrypt
+ * @param session - The current session state
+ * @returns { ciphertext: Uint8Array; header: { publicKey: Uint8Array; nonce: Uint8Array } }
+ */
+export function encryptMessage(plaintext, session) {
+    // Generate a new ratchet key pair
+    const ratchetKeyPair = sodium.crypto_kx_keypair();
+    // Perform a Diffie-Hellman exchange with the recipient's public key
+    const sharedSecret = sodium.crypto_kx_client_session_keys(ratchetKeyPair.publicKey, ratchetKeyPair.privateKey, session.identityKey);
+    // Update root key and derive new sending chain key
+    const newRootKey = sodium.crypto_generichash(32, new Uint8Array([...session.rootKey, ...sharedSecret.sharedTx]));
+    const newSendingChainKey = sodium.crypto_generichash(32, newRootKey);
+    // Derive a message key
+    const messageKey = sodium.crypto_generichash(32, newSendingChainKey);
+    // Encrypt the message
+    const nonce = sodium.randombytes_buf(sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
+    const ciphertext = sodium.crypto_aead_xchacha20poly1305_ietf_encrypt(sodium.from_string(plaintext), null, // No additional data
+    null, nonce, messageKey);
+    // Update session state
+    session.rootKey = newRootKey;
+    session.sendingChainKey = newSendingChainKey;
+    return {
+        ciphertext,
+        header: {
+            publicKey: ratchetKeyPair.publicKey,
+            nonce,
+        },
+    };
+}
+/**
+ * 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 function decryptMessage(ciphertext, header, session) {
+    // Check for skipped message keys
+    const skippedKey = session.skippedMessageKeys.get(header.nonce.toString());
+    if (skippedKey) {
+        session.skippedMessageKeys.delete(header.nonce.toString());
+        const plaintext = sodium.crypto_aead_xchacha20poly1305_ietf_decrypt(null, ciphertext, null, // No additional data
+        header.nonce, skippedKey);
+        return sodium.to_string(plaintext);
+    }
+    // Perform a Diffie-Hellman exchange with the sender's public key
+    const sharedSecret = sodium.crypto_kx_client_session_keys(session.identityKey, session.signedPreKey, header.publicKey);
+    // Update root key and derive new receiving chain key
+    const newRootKey = sodium.crypto_generichash(32, new Uint8Array([...session.rootKey, ...sharedSecret.sharedTx]));
+    const newReceivingChainKey = sodium.crypto_generichash(32, newRootKey);
+    // Derive the message key
+    const messageKey = sodium.crypto_generichash(32, newReceivingChainKey);
+    // Decrypt the message
+    const plaintext = sodium.crypto_aead_xchacha20poly1305_ietf_decrypt(null, ciphertext, null, // No additional data
+    header.nonce, messageKey);
+    // Update session state
+    session.rootKey = newRootKey;
+    session.receivingChainKey = newReceivingChainKey;
+    return sodium.to_string(plaintext);
+}
+// Enhanced KDF with explicit domain separation and transcript binding
+function deriveKey(inputKey, context, transcript) {
+    const label = sodium.from_string(context);
+    return sodium.crypto_generichash(32, new Uint8Array([...label, ...inputKey, ...transcript]));
+}
+function hkdfExtract(salt, inputKeyMaterial) {
+    return sodium.crypto_generichash(32, new Uint8Array([...salt, ...inputKeyMaterial]));
+}
+function hkdfExpand(prk, info, length) {
+    const infoBytes = sodium.from_string(info);
+    return sodium.crypto_generichash(length, new Uint8Array([...prk, ...infoBytes]));
+}
+function deriveRootKey(oldRootKey, dhOutput, transcript) {
+    const salt = deriveKey(oldRootKey, 'DR:dh', transcript);
+    const prk = hkdfExtract(salt, dhOutput);
+    return hkdfExpand(prk, 'DR:root', 32);
+}
+function deriveChainKey(rootKey, transcript) {
+    const prk = hkdfExtract(rootKey, sodium.from_string('DR:chain'));
+    return hkdfExpand(prk, 'DR:chain', 32);
+}
+function deriveMessageKey(chainKey, transcript) {
+    const prk = hkdfExtract(chainKey, sodium.from_string('DR:message'));
+    return hkdfExpand(prk, 'DR:message', 32);
+}
+// Updated skipped keys handling with bounds
+const MAX_SKIPPED_KEYS = 50; // Limit to prevent DoS
+// Enhanced skipped keys handling with state exhaustion protection
+const MAX_TOTAL_SKIPPED_KEYS = 500; // Global limit across sessions
+let totalSkippedKeys = 0;
+export function addSkippedKey(session, header, messageKey) {
+    const keyId = `${header.publicKey.toString()}:${header.nonce.toString()}`;
+    if (session.skippedMessageKeys.size >= MAX_SKIPPED_KEYS) {
+        throw new Error('Skipped keys limit exceeded for session');
+    }
+    if (totalSkippedKeys >= MAX_TOTAL_SKIPPED_KEYS) {
+        throw new Error('Global skipped keys limit exceeded');
+    }
+    session.skippedMessageKeys.set(keyId, messageKey);
+    totalSkippedKeys++;
+}
+export function removeSkippedKey(session, header) {
+    const keyId = `${header.publicKey.toString()}:${header.nonce.toString()}`;
+    if (session.skippedMessageKeys.delete(keyId)) {
+        totalSkippedKeys--;
+    }
+}
+// Improved skipped keys eviction policy
+function cleanUpSkippedKeys(session) {
+    const currentTime = Date.now();
+    session.skippedMessageKeys.forEach((_, keyId) => {
+        const [timestamp] = keyId.split(':');
+        if (currentTime - parseInt(timestamp, 10) > 300000) { // Evict keys older than 5 minutes
+            session.skippedMessageKeys.delete(keyId);
+            totalSkippedKeys--;
+        }
+    });
+}
+export function processSkippedKeys(session) {
+    cleanUpSkippedKeys(session);
+}
+// Updated simultaneous send handling
+export function handleSimultaneousSend(session, isInitiator) {
+    if (isInitiator) {
+        // Initiator ratchets forward
+        session.sendingChainKey = deriveChainKey(session.sendingChainKey, sodium.from_string('initiator'));
+    }
+    else {
+        // Responder ratchets forward
+        session.receivingChainKey = deriveChainKey(session.receivingChainKey, sodium.from_string('responder'));
+    }
+}
+// Updated SPK signature verification with downgrade protection
+function verifySPKSignature(spk, spkSignature, identityKey) {
+    const isValid = sodium.crypto_sign_verify_detached(spkSignature, spk, identityKey);
+    if (!isValid) {
+        throw new Error('Invalid SPK signature');
+    }
+}
+// Updated OPK exhaustion handling
+const OPK_POOL_SIZE = 100; // Example pool size
+let opkPool = [];
+export function generateOPKPool() {
+    opkPool = Array.from({ length: OPK_POOL_SIZE }, () => sodium.crypto_kx_keypair().publicKey);
+}
+// Improved X3DH race safety and OPK handling
+const OPK_LOCK = new Map(); // Lock for atomic OPK consumption
+export function consumeOPKAtomically(userId) {
+    if (OPK_LOCK.get(userId)) {
+        throw new Error('OPK consumption in progress');
+    }
+    OPK_LOCK.set(userId, true);
+    try {
+        const opk = consumeOPK();
+        return opk;
+    }
+    finally {
+        OPK_LOCK.delete(userId);
+    }
+}
+// Enhanced X3DH with cryptographic binding and explicit abort semantics
+function deriveSharedSecret(ik, spk, opk, protocolVersion, cipherSuite) {
+    const context = sodium.from_string(`${protocolVersion}:${cipherSuite}`);
+    return sodium.crypto_generichash(32, new Uint8Array([...ik, ...spk, ...opk, ...context]));
+}
+// Final improvements for X3DH
+function validateProtocolVersion(version) {
+    const supportedVersions = ['1.0'];
+    if (!supportedVersions.includes(version)) {
+        throw new Error(`Unsupported protocol version: ${version}`);
+    }
+}
+function validateCipherSuite(cipherSuite) {
+    const supportedSuites = ['AES-GCM'];
+    if (!supportedSuites.includes(cipherSuite)) {
+        throw new Error(`Unsupported cipher suite: ${cipherSuite}`);
+    }
+}
+/**
+ * Policy for forced DH rotation.
+ * Triggers a DH ratchet step based on:
+ * - Number of messages sent.
+ * - Time elapsed since the last ratchet.
+ * - Explicit compromise flag.
+ */
+const DH_RATCHET_POLICY = {
+    maxMessages: 50, // Trigger after 50 messages
+    maxTime: 10 * 60 * 1000, // Trigger after 10 minutes
+};
+let lastRatchetTime = Date.now();
+let messageCounter = 0;
+export function enforceDHRatchetPolicy(session, remotePublicKey, suspectedCompromise = false) {
+    const currentTime = Date.now();
+    // Check if policy conditions are met
+    if (messageCounter >= DH_RATCHET_POLICY.maxMessages ||
+        currentTime - lastRatchetTime >= DH_RATCHET_POLICY.maxTime ||
+        suspectedCompromise) {
+        forceDHRatchet(session, remotePublicKey);
+        // Reset counters
+        lastRatchetTime = currentTime;
+        messageCounter = 0;
+    }
+}
+/**
+ * Increment message counter and enforce policy.
+ */
+export function incrementMessageCounter(session, remotePublicKey) {
+    messageCounter++;
+    enforceDHRatchetPolicy(session, remotePublicKey);
+}
+/**
+ * Force a DH ratchet step to enable PCS.
+ * @param session - The current session state.
+ * @param remotePublicKey - The remote party's ephemeral public key.
+ */
+export function forceDHRatchet(session, remotePublicKey) {
+    // Generate a new ephemeral key pair
+    const ephemeralKeyPair = sodium.crypto_kx_keypair();
+    // Perform a Diffie-Hellman exchange
+    const dhOutput = sodium.crypto_kx_client_session_keys(ephemeralKeyPair.publicKey, ephemeralKeyPair.privateKey, remotePublicKey);
+    // Update the root key
+    const newRootKey = deriveRootKey(session.rootKey, dhOutput.sharedTx, sodium.from_string('dh-ratchet-recovery'));
+    // Clear compromised keys
+    session.sendingChainKey = newRootKey;
+    session.receivingChainKey = newRootKey;
+    session.skippedMessageKeys.clear();
+    // Update session state
+    session.rootKey = newRootKey;
+}
+/**
+ * Ensure rootKey updates only occur through DH ratchet.
+ * @param session - The current session state.
+ * @param dhOutput - The DH output used to update the root key.
+ */
+function enforceDHRatchetOnly(session, dhOutput) {
+    if (!dhOutput) {
+        throw new Error('Root key updates must occur through DH ratchet');
+    }
+    // Update the root key
+    const newRootKey = deriveRootKey(session.rootKey, dhOutput, sodium.from_string('dh-ratchet-only'));
+    session.rootKey = newRootKey;
+}
+/**
+ * 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 function receiveNewDHPublicKey(session, remotePublicKey) {
+    // Generate a new ephemeral key pair
+    const ephemeralKeyPair = sodium.crypto_kx_keypair();
+    // Perform a Diffie-Hellman exchange
+    const dhOutput = sodium.crypto_kx_client_session_keys(ephemeralKeyPair.publicKey, ephemeralKeyPair.privateKey, remotePublicKey);
+    // Update the root key
+    const newRootKey = deriveRootKey(session.rootKey, dhOutput, sodium.from_string('dh-ratchet-recovery'));
+    // Clear compromised keys
+    session.sendingChainKey = newRootKey;
+    session.receivingChainKey = newRootKey;
+    session.skippedMessageKeys.clear();
+    // Update session state
+    session.rootKey = newRootKey;
+}
+/**
+ * Define and enforce state transitions between epochs.
+ * @param session - The current session state.
+ */
+function transitionToPostCompromiseEpoch(session) {
+    // Clear all pre-compromise state
+    session.sendingChainKey = null;
+    session.receivingChainKey = null;
+    session.skippedMessageKeys.clear();
+    // Mark the session as post-compromise
+    session.isPostCompromise = true;
+}

package/dist/ratchet/key-recovery.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 declare function generateRecoveryShares(secret: Uint8Array): Uint8Array[];
+/**
+ * Combine recovery key shares to reconstruct the secret.
+ * @param shares - An array of shares.
+ * @returns The reconstructed secret.
+ */
+export declare function combineRecoveryShares(shares: Uint8Array[]): Uint8Array;
+/**
+ * Store recovery shares securely.
+ * @param userId - The user ID.
+ * @param shares - The recovery shares.
+ */
+export declare function storeRecoveryShares(userId: string, shares: Uint8Array[]): void;
+/**
+ * Retrieve recovery shares for a user.
+ * @param userId - The user ID.
+ * @returns The recovery shares.
+ */
+export declare function retrieveRecoveryShares(userId: string): Uint8Array[];
+/**
+ * Revoke recovery shares for a user.
+ * @param userId - The user ID.
+ */
+export declare function revokeRecoveryShares(userId: string): void;
+export declare function verifyShareIntegrity(share: Uint8Array, expectedHash: string): boolean;
+/**
+ * Formal Policy for Recovery Shares
+ */
+declare const recoveryPolicy: {
+    minAdmins: number;
+    tamperEvidence: boolean;
+};
+export declare function getRecoveryPolicy(): typeof recoveryPolicy;
+/**
+ * Example Admin Authentication Model
+ */
+export declare function authenticateAdmin(adminToken: string): boolean;
+export declare function approveRecovery(userId: string, adminId: string): void;
+export declare function revokeRecovery(userId: string, adminId: string): void;
+export {};

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