@learncard/sss-key-manager 0.1.14 → 0.1.16

package/src/key-manager.ts

@@ -0,0 +1,323 @@
+/**
+ * SSS Key Manager - Main class
+ */
+
+import type {
+    SSSKeyManagerConfig,
+    SSSKeyDerivationProvider,
+    RecoveryMethod,
+    RecoveryMethodInfo,
+    SecurityLevel,
+    BackupFile,
+    AuthProvider,
+} from './types';
+
+import { SSSApiClient } from './api-client';
+import { splitPrivateKey, reconstructPrivateKey } from './sss';
+import {
+    storeDeviceShare,
+    getDeviceShare,
+    hasDeviceShare,
+    deleteDeviceShare,
+    clearAllShares,
+} from './storage';
+import {
+    encryptWithPassword,
+    decryptWithPassword,
+    generateEd25519PrivateKey,
+} from './crypto';
+
+import {
+    createPasskeyCredential,
+    encryptShareWithPasskey,
+    decryptShareWithPasskey,
+} from './passkey';
+
+import {
+    shareToRecoveryPhrase,
+    recoveryPhraseToShare,
+} from './recovery-phrase';
+
+export class SSSKeyManager implements SSSKeyDerivationProvider {
+    readonly name = 'sss';
+
+    private config: SSSKeyManagerConfig;
+    private apiClient: SSSApiClient;
+    private initialized = false;
+    private currentPrivateKey: string | null = null;
+
+    constructor(config: SSSKeyManagerConfig) {
+        this.config = config;
+        this.apiClient = new SSSApiClient({
+            serverUrl: config.serverUrl,
+            authProvider: config.authProvider,
+        });
+    }
+
+    isInitialized(): boolean {
+        return this.initialized;
+    }
+
+    async hasLocalKey(): Promise<boolean> {
+        return hasDeviceShare(this.config.deviceStorageKey);
+    }
+
+    async connect(): Promise<string> {
+        const deviceShare = await getDeviceShare(this.config.deviceStorageKey);
+
+        if (!deviceShare) {
+            throw new Error('No device share found. User needs to set up SSS or recover.');
+        }
+
+        const serverResponse = await this.apiClient.getAuthShare();
+
+        if (!serverResponse || !serverResponse.authShare) {
+            throw new Error('No auth share found on server. User may need to recover.');
+        }
+
+        if (serverResponse.keyProvider !== 'sss') {
+            throw new Error('User has not migrated to SSS yet.');
+        }
+
+        const privateKey = await reconstructPrivateKey(
+            deviceShare,
+            serverResponse.authShare.encryptedData
+        );
+
+        this.currentPrivateKey = privateKey;
+        this.initialized = true;
+
+        return privateKey;
+    }
+
+    async disconnect(): Promise<void> {
+        this.currentPrivateKey = null;
+        this.initialized = false;
+    }
+
+    async setupNewKey(): Promise<string> {
+        const privateKey = await generateEd25519PrivateKey();
+        await this.setupWithKey(privateKey);
+        return privateKey;
+    }
+
+    async setupWithKey(privateKey: string, primaryDid?: string): Promise<void> {
+        const shares = await splitPrivateKey(privateKey);
+
+        await storeDeviceShare(shares.deviceShare, this.config.deviceStorageKey);
+
+        const did = primaryDid || `did:key:placeholder-${Date.now()}`;
+
+        await this.apiClient.storeAuthShare({
+            authShare: {
+                encryptedData: shares.authShare,
+                encryptedDek: '',
+                iv: '',
+            },
+            primaryDid: did,
+            securityLevel: 'basic',
+        });
+
+        this.currentPrivateKey = privateKey;
+        this.initialized = true;
+    }
+
+    async migrate(privateKey: string): Promise<void> {
+        await this.setupWithKey(privateKey);
+        await this.apiClient.markMigrated();
+    }
+
+    async canMigrate(): Promise<boolean> {
+        const serverResponse = await this.apiClient.getAuthShare();
+        return serverResponse?.keyProvider === 'web3auth';
+    }
+
+    async addRecoveryMethod(method: RecoveryMethod): Promise<void> {
+        if (!this.currentPrivateKey) {
+            throw new Error('No active key. Connect first.');
+        }
+
+        const shares = await splitPrivateKey(this.currentPrivateKey);
+        const recoveryShare = shares.recoveryShare;
+
+        if (method.type === 'passkey') {
+            const user = await this.config.authProvider.getCurrentUser();
+            if (!user) {
+                throw new Error('No authenticated user');
+            }
+
+            const credential = await createPasskeyCredential(
+                user.id,
+                user.email || user.phone || user.id
+            );
+
+            const encryptedShare = await encryptShareWithPasskey(
+                recoveryShare,
+                credential.credentialId
+            );
+
+            await this.apiClient.addRecoveryMethod({
+                type: 'passkey',
+                encryptedShare: {
+                    encryptedData: encryptedShare.encryptedData,
+                    iv: encryptedShare.iv,
+                },
+                credentialId: credential.credentialId,
+            });
+        } else if (method.type === 'backup') {
+            throw new Error('Use exportBackup() instead');
+        }
+    }
+
+    async generateRecoveryPhrase(): Promise<string> {
+        if (!this.currentPrivateKey) {
+            throw new Error('No active key. Connect first.');
+        }
+
+        const shares = await splitPrivateKey(this.currentPrivateKey);
+        const phrase = await shareToRecoveryPhrase(shares.recoveryShare);
+
+        return phrase;
+    }
+
+    async getRecoveryMethods(): Promise<RecoveryMethodInfo[]> {
+        const serverResponse = await this.apiClient.getAuthShare();
+        return serverResponse?.recoveryMethods || [];
+    }
+
+    async recover(method: RecoveryMethod): Promise<string> {
+        if (method.type === 'backup') {
+            const backup: BackupFile = JSON.parse(method.fileContents);
+
+            if (backup.version !== 1) {
+                throw new Error('Unsupported backup file version');
+            }
+
+            const recoveryShare = await decryptWithPassword(
+                backup.encryptedShare.ciphertext,
+                backup.encryptedShare.iv,
+                backup.encryptedShare.salt,
+                method.password,
+                backup.encryptedShare.kdfParams
+            );
+
+            const serverResponse = await this.apiClient.getAuthShare();
+
+            if (!serverResponse || !serverResponse.authShare) {
+                throw new Error('No auth share found on server');
+            }
+
+            const privateKey = await reconstructPrivateKey(
+                recoveryShare,
+                serverResponse.authShare.encryptedData
+            );
+
+            const newShares = await splitPrivateKey(privateKey);
+            await storeDeviceShare(newShares.deviceShare, this.config.deviceStorageKey);
+
+            this.currentPrivateKey = privateKey;
+            this.initialized = true;
+
+            return privateKey;
+        } else if (method.type === 'passkey') {
+            const result = await this.apiClient.getRecoveryShare('passkey', method.credentialId);
+
+            if (!result?.encryptedShare) {
+                throw new Error('No passkey recovery share found');
+            }
+
+            const recoveryShare = await decryptShareWithPasskey({
+                encryptedData: result.encryptedShare.encryptedData,
+                iv: result.encryptedShare.iv,
+                credentialId: method.credentialId || '',
+            });
+
+            const serverResponse = await this.apiClient.getAuthShare();
+
+            if (!serverResponse || !serverResponse.authShare) {
+                throw new Error('No auth share found on server');
+            }
+
+            const privateKey = await reconstructPrivateKey(
+                recoveryShare,
+                serverResponse.authShare.encryptedData
+            );
+
+            const newShares = await splitPrivateKey(privateKey);
+            await storeDeviceShare(newShares.deviceShare, this.config.deviceStorageKey);
+
+            this.currentPrivateKey = privateKey;
+            this.initialized = true;
+
+            return privateKey;
+        } else if (method.type === 'phrase') {
+            const recoveryShare = await recoveryPhraseToShare(method.phrase);
+
+            const serverResponse = await this.apiClient.getAuthShare();
+
+            if (!serverResponse || !serverResponse.authShare) {
+                throw new Error('No auth share found on server');
+            }
+
+            const privateKey = await reconstructPrivateKey(
+                recoveryShare,
+                serverResponse.authShare.encryptedData
+            );
+
+            const newShares = await splitPrivateKey(privateKey);
+            await storeDeviceShare(newShares.deviceShare, this.config.deviceStorageKey);
+
+            this.currentPrivateKey = privateKey;
+            this.initialized = true;
+
+            return privateKey;
+        }
+
+        throw new Error('Unknown recovery method');
+    }
+
+    async getSecurityLevel(): Promise<SecurityLevel> {
+        const serverResponse = await this.apiClient.getAuthShare();
+        return serverResponse?.securityLevel || 'basic';
+    }
+
+    async exportBackup(password: string): Promise<BackupFile> {
+        if (!this.currentPrivateKey) {
+            throw new Error('No active key. Connect first.');
+        }
+
+        const shares = await splitPrivateKey(this.currentPrivateKey);
+        const encrypted = await encryptWithPassword(shares.recoveryShare, password);
+
+        const serverResponse = await this.apiClient.getAuthShare();
+
+        return {
+            version: 1,
+            createdAt: new Date().toISOString(),
+            primaryDid: serverResponse?.primaryDid || 'unknown',
+            encryptedShare: {
+                ciphertext: encrypted.ciphertext,
+                iv: encrypted.iv,
+                salt: encrypted.salt,
+                kdfParams: encrypted.kdfParams,
+            },
+        };
+    }
+
+    async clearLocalData(): Promise<void> {
+        await deleteDeviceShare(this.config.deviceStorageKey);
+        this.currentPrivateKey = null;
+        this.initialized = false;
+    }
+
+    async deleteAccount(): Promise<void> {
+        await this.apiClient.deleteUserKey();
+        await clearAllShares();
+        this.currentPrivateKey = null;
+        this.initialized = false;
+    }
+}
+
+export function createSSSKeyManager(config: SSSKeyManagerConfig): SSSKeyManager {
+    return new SSSKeyManager(config);
+}

package/src/passkey.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect, vi } from 'vitest';
+import {
+    isWebAuthnSupported,
+    isPRFSupported,
+} from './passkey';
+
+describe('Passkey utilities', () => {
+    describe('isWebAuthnSupported', () => {
+        it('should return false when window is undefined', () => {
+            const originalWindow = global.window;
+            // @ts-expect-error - Testing undefined window
+            delete global.window;
+
+            expect(isWebAuthnSupported()).toBe(false);
+
+            global.window = originalWindow;
+        });
+
+        it('should return false when PublicKeyCredential is undefined', () => {
+            const originalPKC = global.window?.PublicKeyCredential;
+            if (global.window) {
+                // @ts-expect-error - Testing undefined PublicKeyCredential
+                delete global.window.PublicKeyCredential;
+            }
+
+            expect(isWebAuthnSupported()).toBe(false);
+
+            if (global.window && originalPKC) {
+                global.window.PublicKeyCredential = originalPKC;
+            }
+        });
+    });
+
+    describe('isPRFSupported', () => {
+        it('should return false when WebAuthn is not supported', async () => {
+            const originalWindow = global.window;
+            // @ts-expect-error - Testing undefined window
+            delete global.window;
+
+            const result = await isPRFSupported();
+            expect(result).toBe(false);
+
+            global.window = originalWindow;
+        });
+    });
+
+    describe('Module exports', () => {
+        it('should export all required functions', async () => {
+            const passkey = await import('./passkey');
+
+            expect(typeof passkey.isWebAuthnSupported).toBe('function');
+            expect(typeof passkey.isPRFSupported).toBe('function');
+            expect(typeof passkey.createPasskeyCredential).toBe('function');
+            expect(typeof passkey.deriveKeyFromPasskey).toBe('function');
+            expect(typeof passkey.encryptShareWithPasskey).toBe('function');
+            expect(typeof passkey.decryptShareWithPasskey).toBe('function');
+        });
+    });
+});

package/src/passkey.ts

@@ -0,0 +1,222 @@
+/**
+ * WebAuthn Passkey utilities for SSS recovery
+ * Uses the PRF (Pseudo-Random Function) extension to derive encryption keys
+ */
+
+import { bufferToBase64, base64ToBuffer, bytesToHex, hexToBytes } from './crypto';
+
+export interface PasskeyCredential {
+    credentialId: string;
+    publicKey: string;
+    transports?: AuthenticatorTransport[];
+}
+
+export interface PasskeyEncryptedShare {
+    encryptedData: string;
+    iv: string;
+    credentialId: string;
+}
+
+const RP_NAME = 'LearnCard';
+const RP_ID = typeof window !== 'undefined' ? window.location.hostname : 'localhost';
+
+const PRF_SALT = new TextEncoder().encode('learncard-sss-recovery-v1');
+
+function isWebAuthnSupported(): boolean {
+    return typeof window !== 'undefined' &&
+        typeof window.PublicKeyCredential !== 'undefined' &&
+        typeof window.PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable === 'function';
+}
+
+async function isPRFSupported(): Promise<boolean> {
+    if (!isWebAuthnSupported()) return false;
+
+    try {
+        const available = await PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable();
+        return available;
+    } catch {
+        return false;
+    }
+}
+
+export async function createPasskeyCredential(
+    userId: string,
+    userName: string
+): Promise<PasskeyCredential> {
+    if (!isWebAuthnSupported()) {
+        throw new Error('WebAuthn is not supported in this browser');
+    }
+
+    const userIdBytes = new TextEncoder().encode(userId);
+
+    const createOptions: PublicKeyCredentialCreationOptions = {
+        challenge: crypto.getRandomValues(new Uint8Array(32)),
+        rp: {
+            name: RP_NAME,
+            id: RP_ID,
+        },
+        user: {
+            id: userIdBytes,
+            name: userName,
+            displayName: userName,
+        },
+        pubKeyCredParams: [
+            { alg: -7, type: 'public-key' },   // ES256
+            { alg: -257, type: 'public-key' }, // RS256
+        ],
+        authenticatorSelection: {
+            authenticatorAttachment: 'platform',
+            userVerification: 'required',
+            residentKey: 'required',
+        },
+        timeout: 60000,
+        attestation: 'none',
+        extensions: {
+            prf: {
+                eval: {
+                    first: PRF_SALT,
+                },
+            },
+        } as AuthenticationExtensionsClientInputs,
+    };
+
+    const credential = await navigator.credentials.create({
+        publicKey: createOptions,
+    }) as PublicKeyCredential;
+
+    if (!credential) {
+        throw new Error('Failed to create passkey credential');
+    }
+
+    const response = credential.response as AuthenticatorAttestationResponse;
+
+    const extensionResults = credential.getClientExtensionResults() as {
+        prf?: { enabled?: boolean; results?: { first?: ArrayBuffer } };
+    };
+
+    if (!extensionResults.prf?.enabled && !extensionResults.prf?.results?.first) {
+        throw new Error(
+            'PRF extension not available. Your browser or device does not support ' +
+            'the encryption required for passkey recovery. Please use a different recovery method.'
+        );
+    }
+
+    return {
+        credentialId: bufferToBase64(credential.rawId),
+        publicKey: bufferToBase64(response.getPublicKey() as ArrayBuffer),
+        transports: response.getTransports?.() as AuthenticatorTransport[],
+    };
+}
+
+export async function deriveKeyFromPasskey(
+    credentialId: string
+): Promise<CryptoKey> {
+    if (!isWebAuthnSupported()) {
+        throw new Error('WebAuthn is not supported in this browser');
+    }
+
+    const getOptions: PublicKeyCredentialRequestOptions = {
+        challenge: crypto.getRandomValues(new Uint8Array(32)),
+        rpId: RP_ID,
+        allowCredentials: [{
+            id: base64ToBuffer(credentialId),
+            type: 'public-key',
+        }],
+        userVerification: 'required',
+        timeout: 60000,
+        extensions: {
+            prf: {
+                eval: {
+                    first: PRF_SALT,
+                },
+            },
+        } as AuthenticationExtensionsClientInputs,
+    };
+
+    const assertion = await navigator.credentials.get({
+        publicKey: getOptions,
+    }) as PublicKeyCredential;
+
+    if (!assertion) {
+        throw new Error('Failed to get passkey assertion');
+    }
+
+    const extensionResults = assertion.getClientExtensionResults() as {
+        prf?: { results?: { first?: ArrayBuffer } };
+    };
+
+    if (!extensionResults.prf?.results?.first) {
+        throw new Error('PRF extension not available or failed. This passkey cannot be used for encryption.');
+    }
+
+    const prfOutput = new Uint8Array(extensionResults.prf.results.first);
+
+    const cryptoKey = await crypto.subtle.importKey(
+        'raw',
+        prfOutput,
+        { name: 'AES-GCM' },
+        false,
+        ['encrypt', 'decrypt']
+    );
+
+    return cryptoKey;
+}
+
+export async function encryptShareWithPasskey(
+    share: string,
+    credentialId: string
+): Promise<PasskeyEncryptedShare> {
+    const key = await deriveKeyFromPasskey(credentialId);
+
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const encoder = new TextEncoder();
+
+    const ciphertext = await crypto.subtle.encrypt(
+        { name: 'AES-GCM', iv },
+        key,
+        encoder.encode(share)
+    );
+
+    return {
+        encryptedData: bufferToBase64(ciphertext),
+        iv: bufferToBase64(iv.buffer),
+        credentialId,
+    };
+}
+
+export async function decryptShareWithPasskey(
+    encryptedShare: PasskeyEncryptedShare
+): Promise<string> {
+    const key = await deriveKeyFromPasskey(encryptedShare.credentialId);
+
+    const iv = base64ToBuffer(encryptedShare.iv);
+    const ciphertext = base64ToBuffer(encryptedShare.encryptedData);
+
+    const plaintext = await crypto.subtle.decrypt(
+        { name: 'AES-GCM', iv: iv.buffer },
+        key,
+        ciphertext.buffer
+    );
+
+    const decoder = new TextDecoder();
+    return decoder.decode(plaintext);
+}
+
+export async function listStoredPasskeys(): Promise<PasskeyCredential[]> {
+    if (!isWebAuthnSupported()) {
+        return [];
+    }
+
+    if (typeof PublicKeyCredential.isConditionalMediationAvailable !== 'function') {
+        return [];
+    }
+
+    const available = await PublicKeyCredential.isConditionalMediationAvailable();
+    if (!available) {
+        return [];
+    }
+
+    return [];
+}
+
+export { isWebAuthnSupported, isPRFSupported };