@stvor/sdk 2.2.1 → 2.2.2

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;

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