w3pk 0.9.2 → 0.10.0

package/README.md

@@ -52,6 +52,7 @@ const endpoints = await w3pk.getEndpoints(1)
 - EIP-1193 provider for ethers, viem, wagmi, RainbowKit (`getEIP1193Provider`)
 - ERC-5564 stealth addresses (opt-in)
 - ZK primitives (zero-knowledge proof generation and verification)
+- Post-quantum encryption (ML-KEM-1024/Kyber NIST FIPS 203)
 - Chainlist support (2390+ networks)
 - EIP-7702 network detection (329+ networks)
 - External wallet integration (delegate MetaMask/Ledger to w3pk via EIP-7702)
@@ -337,6 +338,15 @@ if (result.isForUser) {
 const myPayments = await w3pk.stealth?.scanAnnouncements(announcements)
 ```
 
+### ML-KEM encryption
+
+```typescript
+// Encrypt with post-quantum security (NIST FIPS 203)
+const pubKey = await w3pk.deriveMLKemPublicKey()
+const encrypted = await w3pk.mlkemEncrypt('secret', [pubKey])
+const plaintext = await w3pk.mlkemDecrypt(encrypted)
+```
+
 ### Backup & Recovery
 
 ```typescript
@@ -355,8 +365,13 @@ console.log('Security Score:', status.securityScore.total) // 0-100
 // Create encrypted backup file
 const { blob, filename } = await w3pk.createBackupFile('password', password)
 
-// Setup social recovery (M-of-N guardians)
-await w3pk.setupSocialRecovery(
+// Setup social recovery (M-of-N guardians) - guardians store backup file fragments
+import { SocialRecoveryManager } from 'w3pk'
+const backupFileJson = await blob.text()
+const socialRecovery = new SocialRecoveryManager()
+const guardians = await socialRecovery.setupSocialRecovery(
+  backupFileJson,
+  w3pk.user.ethereumAddress,
   [
     { name: 'Alice', email: 'alice@example.com' },
     { name: 'Bob', phone: '+1234567890' },
@@ -366,10 +381,11 @@ await w3pk.setupSocialRecovery(
 )
 
 // Generate guardian invite
-const invite = await w3pk.generateGuardianInvite(guardianShare)
+const invite = await socialRecovery.generateGuardianInvite(guardians[0])
 
-// Recover from guardian shares
-const { mnemonic } = await w3pk.recoverFromGuardians([share1, share2])
+// Recover from guardian shares - reconstructs encrypted backup file
+const { backupFileJson } = await socialRecovery.recoverFromGuardians([share1, share2])
+await w3pk.registerWithBackupFile(backupFileJson, password, 'username')
 
 // Restore from backup file
 await w3pk.restoreFromBackupFile(encryptedData, password)

package/dist/index.d.mts

@@ -1016,6 +1016,111 @@ declare class Web3Passkey {
      * @param hours - Duration in hours
      */
     setSessionDuration(hours: number): void;
+    /**
+     * Derive ML-KEM-1024 public key from the current wallet
+     *
+     * Returns the public key that can be shared with others for encryption.
+     * The keypair is derived deterministically from the wallet's private key.
+     *
+     * @param options - Optional configuration
+     * @param options.context - Context string for domain separation (default: 'mlkem-v1')
+     * @param options.mode - Security mode (default: 'YOLO' to access private key)
+     * @param options.tag - Tag for address derivation (default: 'MAIN')
+     * @param options.origin - Origin for derivation (default: current origin)
+     * @param options.requireAuth - Force WebAuthn re-authentication
+     * @returns Base64-encoded ML-KEM public key (1568 bytes)
+     *
+     * @example
+     * ```typescript
+     * const w3pk = createWeb3Passkey();
+     * await w3pk.login();
+     *
+     * const publicKey = await w3pk.deriveMLKemPublicKey();
+     * // Share publicKey with others so they can encrypt data for you
+     * ```
+     */
+    deriveMLKemPublicKey(options?: {
+        context?: string;
+        mode?: SecurityMode;
+        tag?: string;
+        origin?: string;
+        requireAuth?: boolean;
+    }): Promise<string>;
+    /**
+     * Encrypt data using ML-KEM-1024 for self + additional recipients
+     *
+     * Encrypts data such that you (the sender) and specified recipients can decrypt.
+     * Your ML-KEM keypair is derived from your wallet, so you can always decrypt later.
+     *
+     * @param plaintext - The data to encrypt
+     * @param recipientPublicKeys - Array of recipient ML-KEM public keys (base64 strings or Uint8Arrays)
+     * @param options - Optional configuration
+     * @param options.context - Context string for key derivation (default: 'mlkem-v1')
+     * @param options.mode - Security mode (default: 'YOLO' to access private key)
+     * @param options.tag - Tag for address derivation (default: 'MAIN')
+     * @param options.origin - Origin for derivation (default: current origin)
+     * @param options.requireAuth - Force WebAuthn re-authentication
+     * @returns Encrypted payload that can be decrypted by sender or recipients
+     *
+     * @example
+     * ```typescript
+     * const w3pk = createWeb3Passkey();
+     * await w3pk.login();
+     *
+     * // Get server's public key
+     * const serverPubKey = await fetch('/api/mlkem-public-key').then(r => r.text());
+     *
+     * // Encrypt for yourself + server
+     * const encrypted = await w3pk.mlkemEncrypt(
+     *   'my secret data',
+     *   [serverPubKey]
+     * );
+     *
+     * // Later: decrypt with the same wallet
+     * const decrypted = await w3pk.mlkemDecrypt(encrypted);
+     * ```
+     */
+    mlkemEncrypt(plaintext: string, recipientPublicKeys: Array<string | Uint8Array>, options?: {
+        context?: string;
+        mode?: SecurityMode;
+        tag?: string;
+        origin?: string;
+        requireAuth?: boolean;
+    }): Promise<any>;
+    /**
+     * Decrypt ML-KEM encrypted data using current wallet
+     *
+     * Decrypts data that was encrypted for this wallet.
+     * The ML-KEM keypair is derived from your wallet's private key.
+     *
+     * @param payload - The encrypted payload (from mlkemEncrypt)
+     * @param options - Optional configuration
+     * @param options.context - Context string for key derivation (default: 'mlkem-v1', must match encryption)
+     * @param options.mode - Security mode (default: 'YOLO' to access private key)
+     * @param options.tag - Tag for address derivation (default: 'MAIN')
+     * @param options.origin - Origin for derivation (default: current origin)
+     * @param options.requireAuth - Force WebAuthn re-authentication
+     * @returns Decrypted plaintext
+     *
+     * @example
+     * ```typescript
+     * const w3pk = createWeb3Passkey();
+     * await w3pk.login();
+     *
+     * // Retrieve encrypted data
+     * const encrypted = await fetch('/api/my-data').then(r => r.json());
+     *
+     * // Decrypt locally (server never sees plaintext!)
+     * const plaintext = await w3pk.mlkemDecrypt(encrypted);
+     * ```
+     */
+    mlkemDecrypt(payload: any, options?: {
+        context?: string;
+        mode?: SecurityMode;
+        tag?: string;
+        origin?: string;
+        requireAuth?: boolean;
+    }): Promise<string>;
 }
 
 /**
@@ -1209,6 +1314,14 @@ interface AuthenticationCredential {
         signature: ArrayBuffer;
         userHandle?: ArrayBuffer;
     };
+    getClientExtensionResults(): {
+        prf?: {
+            results?: {
+                first?: ArrayBuffer;
+                second?: ArrayBuffer;
+            };
+        };
+    };
 }
 
 /**
@@ -1753,6 +1866,93 @@ interface RecoveryProgress {
     canRecover: boolean;
 }
 
+/**
+ * Social Recovery Manager
+ * Manages guardian-based wallet recovery using Shamir Secret Sharing
+ */
+
+declare class SocialRecoveryManager {
+    private storageKey;
+    /**
+     * Get storage (localStorage or in-memory fallback)
+     */
+    private getItem;
+    /**
+     * Set storage (localStorage or in-memory fallback)
+     */
+    private setItem;
+    /**
+     * Set up social recovery
+     * Splits encrypted backup file into M-of-N shares and distributes to guardians
+     *
+     * @param backupFileJson - The complete backup file JSON string (password-encrypted)
+     * @param ethereumAddress - The Ethereum address for verification
+     * @param guardians - Array of guardian information
+     * @param threshold - Minimum number of guardians needed for recovery
+     */
+    setupSocialRecovery(backupFileJson: string, ethereumAddress: string, guardians: {
+        name: string;
+        email?: string;
+        phone?: string;
+    }[], threshold: number): Promise<Guardian[]>;
+    /**
+     * Get current social recovery configuration
+     */
+    getSocialRecoveryConfig(): SocialRecoveryConfig | null;
+    /**
+     * Generate guardian invitation
+     * Creates QR code and educational materials for guardian
+     */
+    generateGuardianInvite(guardian: Guardian): Promise<GuardianInvite>;
+    /**
+     * Generate QR code from share data
+     * Uses 'qrcode' library if available, falls back to canvas text
+     */
+    private generateQRCode;
+    /**
+     * Create fallback QR representation
+     */
+    private createPlaceholderQR;
+    /**
+     * Wrap text for display
+     */
+    private wrapText;
+    /**
+     * Get guardian explainer text
+     */
+    private getGuardianExplainer;
+    /**
+     * Recover backup file from guardian shares
+     * Returns the reconstructed backup file JSON that can be used with restoreFromBackupFile()
+     */
+    recoverFromGuardians(shareData: string[]): Promise<{
+        backupFileJson: string;
+        ethereumAddress: string;
+    }>;
+    /**
+     * Get recovery progress
+     */
+    getRecoveryProgress(collectedShares: string[]): RecoveryProgress;
+    /**
+     * Mark guardian as verified
+     * Note: This updates guardian status but does NOT automatically refresh security score.
+     * The security score will be updated on the next call to BackupManager.getBackupStatus()
+     */
+    markGuardianVerified(guardianId: string): void;
+    /**
+     * Revoke a guardian
+     */
+    revokeGuardian(guardianId: string): void;
+    /**
+     * Add new guardian (requires re-sharing with new backup file)
+     */
+    addGuardian(backupFileJson: string, newGuardian: {
+        name: string;
+        email?: string;
+        phone?: string;
+    }): Promise<Guardian>;
+}
+
 /**
  * Cross-Device Sync Type Definitions
  */
@@ -1980,6 +2180,105 @@ declare function inspect(options?: BrowserInspectOptions): Promise<BrowserInspec
  */
 declare function inspectNow(options?: BrowserInspectOptions): Promise<void>;
 
+interface MLKemKeypair {
+    publicKey: Uint8Array;
+    privateKey: Uint8Array;
+}
+interface EncryptedPayload {
+    recipients: Array<{
+        publicKey: string;
+        ciphertext: string;
+    }>;
+    encryptedData: string;
+    iv: string;
+    authTag: string;
+}
+/**
+ * Derive deterministic ML-KEM-1024 keypair from any private key material
+ *
+ * Uses HKDF-SHA256 to derive a 64-byte seed from the input key material,
+ * then generates a reproducible ML-KEM-1024 keypair.
+ *
+ * @param privateKey - Private key material (hex string with optional 0x prefix, or Uint8Array)
+ * @param context - Context string for domain separation (default: 'mlkem-v1')
+ * @returns ML-KEM-1024 keypair (publicKey: 1568 bytes, privateKey: 3168 bytes)
+ *
+ * @example
+ * ```typescript
+ * // Derive from Ethereum private key
+ * const ethPrivateKey = '0x1234...';
+ * const keypair = await deriveMLKemKeypair(ethPrivateKey, 'my-app');
+ *
+ * // Derive from any 32-byte key
+ * const randomKey = crypto.getRandomValues(new Uint8Array(32));
+ * const keypair2 = await deriveMLKemKeypair(randomKey);
+ * ```
+ */
+declare function deriveMLKemKeypair(privateKey: string | Uint8Array, context?: string): Promise<MLKemKeypair>;
+/**
+ * Encrypt data using ML-KEM-1024 + AES-256-GCM for multiple recipients
+ *
+ * @param plaintext - The data to encrypt
+ * @param publicKeys - Array of ML-KEM-1024 public keys (base64 strings or Uint8Arrays, 1568 bytes each)
+ * @returns Encrypted payload with per-recipient ciphertexts and shared encrypted data
+ */
+declare function mlkemEncrypt(plaintext: string, publicKeys: (string | Uint8Array) | Array<string | Uint8Array>): Promise<EncryptedPayload>;
+/**
+ * Decrypt data encrypted with mlkemEncrypt()
+ *
+ * @param payload - The encrypted payload
+ * @param privateKey - ML-KEM-1024 private key (base64 string or Uint8Array, 3168 bytes)
+ * @param publicKey - Optional: Your public key to find the correct recipient entry (base64 string or Uint8Array, 1568 bytes)
+ * @returns Decrypted plaintext
+ */
+declare function mlkemDecrypt(payload: EncryptedPayload, privateKey: string | Uint8Array, publicKey?: string | Uint8Array): Promise<string>;
+/**
+ * Encrypt data with ML-KEM using derived keypairs from private keys
+ *
+ * This is a convenience function that derives ML-KEM keypairs from private key material,
+ * then encrypts the data for all recipients. The sender's keypair is derived and used
+ * as one of the recipients.
+ *
+ * @param plaintext - The data to encrypt
+ * @param senderPrivateKey - Sender's private key (hex string or Uint8Array)
+ * @param recipientPublicKeys - Array of recipient ML-KEM public keys (from deriveMLKemKeypair)
+ * @param senderContext - Context for sender's key derivation (default: 'mlkem-v1')
+ * @returns Encrypted payload with sender + recipients
+ *
+ * @example
+ * ```typescript
+ * // Encrypt for yourself + server
+ * const serverKeypair = await deriveMLKemKeypair(serverPrivateKey, 'server');
+ * const encrypted = await mlkemEncryptWithKey(
+ *   'secret data',
+ *   myEthPrivateKey,
+ *   [serverKeypair.publicKey]
+ * );
+ * ```
+ */
+declare function mlkemEncryptWithKey(plaintext: string, senderPrivateKey: string | Uint8Array, recipientPublicKeys: Array<string | Uint8Array>, senderContext?: string): Promise<EncryptedPayload>;
+/**
+ * Decrypt data with ML-KEM using a derived keypair from private key
+ *
+ * This is a convenience function that derives an ML-KEM keypair from private key material,
+ * then decrypts the payload.
+ *
+ * @param payload - The encrypted payload
+ * @param privateKey - Private key material (hex string or Uint8Array)
+ * @param context - Context for key derivation (default: 'mlkem-v1')
+ * @returns Decrypted plaintext
+ *
+ * @example
+ * ```typescript
+ * // Decrypt with your Ethereum private key
+ * const plaintext = await mlkemDecryptWithKey(
+ *   encryptedPayload,
+ *   myEthPrivateKey
+ * );
+ * ```
+ */
+declare function mlkemDecryptWithKey(payload: EncryptedPayload, privateKey: string | Uint8Array, context?: string): Promise<string>;
+
 declare function createWeb3Passkey(config?: Web3PasskeyConfig): Web3Passkey;
 
-export { ApiError, AuthenticationError, type BackupStatus, type BrowserInspectOptions, type BrowserInspectResult, CryptoError, DEFAULT_MODE, DEFAULT_TAG, type DeviceInfo, type EIP1193Provider, type EIP7702Authorization, type EncryptedBackupInfo, type Guardian, type GuardianInvite, type PasskeySelectionResult, type QRBackupOptions, type RecoveryProgress, type RecoveryScenario, type RecoveryShare, RecoverySimulator, RegistrationError, type SecurityScore, type SignAuthorizationParams, type SimulationResult, type SiweMessage, type SocialRecoveryConfig, type StealthAddressConfig, StealthAddressModule, type StealthAddressResult, type StealthKeys, StorageError, type SyncCapabilities, type SyncStatus, type SyncVault, type UserInfo, WalletError, type WalletInfo, Web3Passkey, type Web3PasskeyConfig, Web3PasskeyError, arrayBufferToBase64Url, assertEthereumAddress, assertMnemonic, assertUsername, authenticateWithPasskey, base64ToArrayBuffer, base64UrlDecode, base64UrlToArrayBuffer, canControlStealthAddress, checkStealthAddress, clearCache, computeStealthPrivateKey, createSiweMessage, createWalletFromMnemonic, createWeb3Passkey, createWeb3Passkey as default, deriveAddressFromP256PublicKey, deriveIndexFromOriginModeAndTag, deriveStealthKeys, deriveWalletFromMnemonic, detectWalletProvider, encodeEIP7702AuthorizationMessage, extractRS, generateBIP39Wallet, generateSiweNonce, generateStealthAddress, getAllChains, getAllTopics, getChainById, getCurrentBuildHash, getCurrentOrigin, getDefaultProvider, getEndpoints, getExplainer, getOriginSpecificAddress, getPackageVersion, getW3pkBuildHash, hashEIP7702AuthorizationMessage, inspect, inspectNow, isStrongPassword, normalizeOrigin, parseSiweMessage, promptPasskeySelection, requestExternalWalletAuthorization, safeAtob, safeBtoa, searchExplainers, supportsEIP7702Authorization, validateEthereumAddress, validateMnemonic, validateSiweMessage, validateUsername, verifyBuildHash, verifyEIP7702Authorization, verifySiweSignature };
+export { ApiError, AuthenticationError, type BackupStatus, type BrowserInspectOptions, type BrowserInspectResult, CryptoError, DEFAULT_MODE, DEFAULT_TAG, type DeviceInfo, type EIP1193Provider, type EIP7702Authorization, type EncryptedBackupInfo, type EncryptedPayload, type Guardian, type GuardianInvite, type MLKemKeypair, type PasskeySelectionResult, type QRBackupOptions, type RecoveryProgress, type RecoveryScenario, type RecoveryShare, RecoverySimulator, RegistrationError, type SecurityScore, type SignAuthorizationParams, type SimulationResult, type SiweMessage, type SocialRecoveryConfig, SocialRecoveryManager, type StealthAddressConfig, StealthAddressModule, type StealthAddressResult, type StealthKeys, StorageError, type SyncCapabilities, type SyncStatus, type SyncVault, type UserInfo, WalletError, type WalletInfo, Web3Passkey, type Web3PasskeyConfig, Web3PasskeyError, arrayBufferToBase64Url, assertEthereumAddress, assertMnemonic, assertUsername, authenticateWithPasskey, base64ToArrayBuffer, base64UrlDecode, base64UrlToArrayBuffer, canControlStealthAddress, checkStealthAddress, clearCache, computeStealthPrivateKey, createSiweMessage, createWalletFromMnemonic, createWeb3Passkey, createWeb3Passkey as default, deriveAddressFromP256PublicKey, deriveIndexFromOriginModeAndTag, deriveMLKemKeypair, deriveStealthKeys, deriveWalletFromMnemonic, detectWalletProvider, encodeEIP7702AuthorizationMessage, extractRS, generateBIP39Wallet, generateSiweNonce, generateStealthAddress, getAllChains, getAllTopics, getChainById, getCurrentBuildHash, getCurrentOrigin, getDefaultProvider, getEndpoints, getExplainer, getOriginSpecificAddress, getPackageVersion, getW3pkBuildHash, hashEIP7702AuthorizationMessage, inspect, inspectNow, isStrongPassword, mlkemDecrypt, mlkemDecryptWithKey, mlkemEncrypt, mlkemEncryptWithKey, normalizeOrigin, parseSiweMessage, promptPasskeySelection, requestExternalWalletAuthorization, safeAtob, safeBtoa, searchExplainers, supportsEIP7702Authorization, validateEthereumAddress, validateMnemonic, validateSiweMessage, validateUsername, verifyBuildHash, verifyEIP7702Authorization, verifySiweSignature };