@learncard/sss-key-manager 0.1.13 → 0.1.15

package/src/qr-login.ts

@@ -0,0 +1,339 @@
+/**
+ * QR Login Client
+ *
+ * High-level orchestrator for cross-device login via QR code or short code.
+ * Coordinates between the relay API and the ECDH crypto layer.
+ *
+ * Two roles:
+ *   - **Requester** (Device B, new device): creates session, renders QR, polls
+ *   - **Approver** (Device A, logged-in device): reads QR/code, encrypts share, approves
+ */
+
+import type { AuthProvider } from './types';
+
+import {
+    generateEphemeralKeypair,
+    encryptShareForTransfer,
+    decryptShareFromTransfer,
+} from './qr-crypto';
+
+import type { EphemeralKeypair, EncryptedSharePayload } from './qr-crypto';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface QrLoginSession {
+    sessionId: string;
+    shortCode: string;
+    expiresInSeconds: number;
+}
+
+export interface QrLoginSessionInfo {
+    sessionId: string;
+    publicKey: string;
+    status: 'pending' | 'approved';
+    encryptedPayload?: string;
+    approverDid?: string;
+}
+
+export interface QrLoginClientConfig {
+    serverUrl: string;
+}
+
+export interface QrPayload {
+    /** Session ID for the relay */
+    sessionId: string;
+
+    /** Base64-encoded ephemeral X25519 public key */
+    publicKey: string;
+
+    /** Server URL for the relay */
+    serverUrl: string;
+}
+
+/** Result of polling — either still waiting or the device share is ready */
+export type PollResult =
+    | { status: 'pending' }
+    | { status: 'approved'; deviceShare: string; approverDid: string; accountHint?: string; shareVersion?: number };
+
+// ---------------------------------------------------------------------------
+// API helpers
+// ---------------------------------------------------------------------------
+
+const buildHeaders = (token?: string): Record<string, string> => {
+    const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+
+    if (token) {
+        headers.Authorization = `Bearer ${token}`;
+    }
+
+    return headers;
+};
+
+// ---------------------------------------------------------------------------
+// Requester (Device B — the new device)
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a QR login session and generate the ephemeral keypair.
+ *
+ * Returns everything Device B needs to display a QR and start polling.
+ * The ephemeral private key is kept in memory — never serialized.
+ */
+export const createQrLoginSession = async (
+    config: QrLoginClientConfig
+): Promise<{
+    session: QrLoginSession;
+    ephemeralKeypair: EphemeralKeypair;
+    qrPayload: QrPayload;
+}> => {
+    const ephemeralKeypair = await generateEphemeralKeypair();
+
+    const response = await fetch(`${config.serverUrl}/qr-login/session`, {
+        method: 'POST',
+        headers: buildHeaders(),
+        body: JSON.stringify({ publicKey: ephemeralKeypair.publicKey }),
+    });
+
+    if (!response.ok) {
+        throw new Error(`Failed to create QR login session: ${response.statusText}`);
+    }
+
+    const session: QrLoginSession = await response.json();
+
+    const qrPayload: QrPayload = {
+        sessionId: session.sessionId,
+        publicKey: ephemeralKeypair.publicKey,
+        serverUrl: config.serverUrl,
+    };
+
+    return { session, ephemeralKeypair, qrPayload };
+};
+
+/**
+ * Poll a QR login session for approval.
+ *
+ * When Device A approves, this returns the decrypted device share.
+ *
+ * @param config - Server config
+ * @param sessionId - The session to poll
+ * @param ephemeralPrivateKey - Device B's ephemeral private key (for decryption)
+ */
+export const pollQrLoginSession = async (
+    config: QrLoginClientConfig,
+    sessionId: string,
+    ephemeralPrivateKey: CryptoKey
+): Promise<PollResult> => {
+    const response = await fetch(`${config.serverUrl}/qr-login/session/${sessionId}`, {
+        method: 'GET',
+        headers: buildHeaders(),
+    });
+
+    if (!response.ok) {
+        throw new Error(`Failed to poll QR login session: ${response.statusText}`);
+    }
+
+    const info: QrLoginSessionInfo = await response.json();
+
+    if (info.status === 'pending') {
+        return { status: 'pending' };
+    }
+
+    if (!info.encryptedPayload || !info.approverDid) {
+        throw new Error('Session approved but missing payload');
+    }
+
+    // Parse the encrypted payload and decrypt
+    const payload: EncryptedSharePayload = JSON.parse(info.encryptedPayload);
+
+    const plaintext = await decryptShareFromTransfer(payload, ephemeralPrivateKey);
+
+    const parsed = JSON.parse(plaintext) as { d: string; h?: string; v?: number };
+
+    return {
+        status: 'approved',
+        deviceShare: parsed.d,
+        approverDid: info.approverDid,
+        accountHint: parsed.h,
+        shareVersion: parsed.v,
+    };
+};
+
+/**
+ * Convenience: poll in a loop until approved or timeout.
+ *
+ * @param config - Server config
+ * @param sessionId - The session to poll
+ * @param ephemeralPrivateKey - Device B's ephemeral private key
+ * @param intervalMs - Polling interval (default 2000ms)
+ * @param timeoutMs - Total timeout (default 120000ms)
+ * @param onPoll - Optional callback on each poll (for UI updates)
+ */
+export const pollUntilApproved = async (
+    config: QrLoginClientConfig,
+    sessionId: string,
+    ephemeralPrivateKey: CryptoKey,
+    options?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+        onPoll?: (attempt: number) => void;
+        signal?: AbortSignal;
+    }
+): Promise<{ deviceShare: string; approverDid: string; accountHint?: string; shareVersion?: number }> => {
+    const intervalMs = options?.intervalMs ?? 2000;
+    const timeoutMs = options?.timeoutMs ?? 120_000;
+
+    const deadline = Date.now() + timeoutMs;
+    let attempt = 0;
+
+    while (Date.now() < deadline) {
+        if (options?.signal?.aborted) {
+            throw new Error('QR login polling aborted');
+        }
+
+        attempt++;
+        options?.onPoll?.(attempt);
+
+        const result = await pollQrLoginSession(config, sessionId, ephemeralPrivateKey);
+
+        if (result.status === 'approved') {
+            return {
+                deviceShare: result.deviceShare,
+                approverDid: result.approverDid,
+                accountHint: result.accountHint,
+                shareVersion: result.shareVersion,
+            };
+        }
+
+        // Wait before next poll
+        await new Promise<void>((resolve, reject) => {
+            const timer = setTimeout(resolve, intervalMs);
+
+            if (options?.signal) {
+                options.signal.addEventListener('abort', () => {
+                    clearTimeout(timer);
+                    reject(new Error('QR login polling aborted'));
+                }, { once: true });
+            }
+        });
+    }
+
+    throw new Error('QR login session timed out');
+};
+
+// ---------------------------------------------------------------------------
+// Approver (Device A — the logged-in device)
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch a QR login session's public key (for Device A to encrypt against).
+ *
+ * @param config - Server config
+ * @param lookup - Session ID or 6-digit short code
+ */
+export const getQrLoginSessionInfo = async (
+    config: QrLoginClientConfig,
+    lookup: string
+): Promise<QrLoginSessionInfo> => {
+    const response = await fetch(`${config.serverUrl}/qr-login/session/${lookup}`, {
+        method: 'GET',
+        headers: buildHeaders(),
+    });
+
+    if (!response.ok) {
+        throw new Error(`Session not found or expired`);
+    }
+
+    return response.json();
+};
+
+/**
+ * Approve a QR login session by encrypting and pushing the device share.
+ *
+ * Called by Device A (the logged-in device).
+ *
+ * @param config - Server config
+ * @param sessionId - The session to approve
+ * @param deviceShare - Plaintext device share from Device A's local storage
+ * @param approverDid - DID of the approving device
+ * @param recipientPublicKey - Base64 X25519 public key from the session
+ * @param accountHint - Optional email or phone of the approver's account (sent to Device B as a login hint)
+ * @param shareVersion - Optional share version so Device B can fetch the matching auth share
+ */
+export const approveQrLoginSession = async (
+    config: QrLoginClientConfig,
+    sessionId: string,
+    deviceShare: string,
+    approverDid: string,
+    recipientPublicKey: string,
+    accountHint?: string,
+    shareVersion?: number
+): Promise<void> => {
+    // Wrap the device share + account hint + version in a JSON envelope
+    const plaintext = JSON.stringify({ d: deviceShare, h: accountHint, v: shareVersion });
+
+    // Encrypt with ECDH
+    const encryptedPayload = await encryptShareForTransfer(plaintext, recipientPublicKey);
+
+    const response = await fetch(`${config.serverUrl}/qr-login/session/${sessionId}/approve`, {
+        method: 'POST',
+        headers: buildHeaders(),
+        body: JSON.stringify({
+            sessionId,
+            encryptedPayload: JSON.stringify(encryptedPayload),
+            approverDid,
+        }),
+    });
+
+    if (!response.ok) {
+        throw new Error(`Failed to approve QR login session: ${response.statusText}`);
+    }
+};
+
+// ---------------------------------------------------------------------------
+// Push notification helper
+// ---------------------------------------------------------------------------
+
+export interface NotifyDevicesResult {
+    sent: boolean;
+    deviceCount: number;
+}
+
+/**
+ * Send a push notification to the authenticated user's other devices,
+ * prompting them to open the approver flow for the given QR session.
+ *
+ * Called by Device B (in needs_recovery) after creating a session.
+ * Requires the user's Firebase (or other auth provider) token.
+ *
+ * This is fire-and-forget — failure does not block the QR login flow.
+ */
+export const notifyDevicesForQrSession = async (
+    config: QrLoginClientConfig,
+    sessionId: string,
+    shortCode: string,
+    authToken: string,
+    providerType: string = 'firebase'
+): Promise<NotifyDevicesResult> => {
+    try {
+        const response = await fetch(`${config.serverUrl}/qr-login/notify`, {
+            method: 'POST',
+            headers: buildHeaders(),
+            body: JSON.stringify({
+                authToken,
+                providerType,
+                sessionId,
+                shortCode,
+            }),
+        });
+
+        if (!response.ok) {
+            return { sent: false, deviceCount: 0 };
+        }
+
+        return (await response.json()) as NotifyDevicesResult;
+    } catch {
+        return { sent: false, deviceCount: 0 };
+    }
+};

package/src/recovery-phrase.test.ts

@@ -0,0 +1,287 @@
+import { describe, it, expect } from 'vitest';
+import {
+    shareToRecoveryPhrase,
+    recoveryPhraseToShare,
+    validateRecoveryPhrase,
+    countWords,
+} from './recovery-phrase';
+import { splitPrivateKey, reconstructFromShares } from './sss';
+
+describe('Recovery Phrase utilities', () => {
+    const testShareHex = 'abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab';
+
+    describe('shareToRecoveryPhrase', () => {
+        it('should convert a hex share to a recovery phrase', async () => {
+            const phrase = await shareToRecoveryPhrase(testShareHex);
+
+            expect(typeof phrase).toBe('string');
+            expect(phrase.length).toBeGreaterThan(0);
+
+            const words = phrase.split(' ');
+            expect(words.length).toBeGreaterThanOrEqual(12);
+        });
+
+        it('should produce consistent output for same input', async () => {
+            const phrase1 = await shareToRecoveryPhrase(testShareHex);
+            const phrase2 = await shareToRecoveryPhrase(testShareHex);
+
+            expect(phrase1).toBe(phrase2);
+        });
+
+        it('should produce different phrases for different shares', async () => {
+            const share1 = 'a'.repeat(64);
+            const share2 = 'b'.repeat(64);
+
+            const phrase1 = await shareToRecoveryPhrase(share1);
+            const phrase2 = await shareToRecoveryPhrase(share2);
+
+            expect(phrase1).not.toBe(phrase2);
+        });
+
+        it('should only contain valid BIP39 words', async () => {
+            const phrase = await shareToRecoveryPhrase(testShareHex);
+            const words = phrase.split(' ');
+
+            for (const word of words) {
+                expect(word.length).toBeGreaterThan(0);
+                expect(/^[a-z]+$/.test(word)).toBe(true);
+            }
+        });
+    });
+
+    describe('recoveryPhraseToShare', () => {
+        it('should convert a recovery phrase back to the original share', async () => {
+            const phrase = await shareToRecoveryPhrase(testShareHex);
+            const recoveredShare = await recoveryPhraseToShare(phrase);
+
+            expect(recoveredShare).toBe(testShareHex);
+        });
+
+        it('should handle phrases with extra whitespace', async () => {
+            const phrase = await shareToRecoveryPhrase(testShareHex);
+            const paddedPhrase = `  ${phrase.split(' ').join('   ')}  `;
+
+            const recoveredShare = await recoveryPhraseToShare(paddedPhrase);
+
+            expect(recoveredShare).toBe(testShareHex);
+        });
+
+        it('should handle uppercase words', async () => {
+            const phrase = await shareToRecoveryPhrase(testShareHex);
+            const upperPhrase = phrase.toUpperCase();
+
+            const recoveredShare = await recoveryPhraseToShare(upperPhrase);
+
+            expect(recoveredShare).toBe(testShareHex);
+        });
+
+        it('should handle mixed case words', async () => {
+            const phrase = await shareToRecoveryPhrase(testShareHex);
+            const mixedPhrase = phrase.split(' ').map((w, i) => 
+                i % 2 === 0 ? w.toUpperCase() : w
+            ).join(' ');
+
+            const recoveredShare = await recoveryPhraseToShare(mixedPhrase);
+
+            expect(recoveredShare).toBe(testShareHex);
+        });
+
+        it('should reject phrases with too few words', async () => {
+            await expect(
+                recoveryPhraseToShare('abandon ability able')
+            ).rejects.toThrow('must be 12-27 words');
+        });
+
+        it('should reject phrases with invalid words', async () => {
+            const phrase = await shareToRecoveryPhrase(testShareHex);
+            const words = phrase.split(' ');
+            words[0] = 'notavalidword';
+
+            await expect(
+                recoveryPhraseToShare(words.join(' '))
+            ).rejects.toThrow('Invalid word');
+        });
+
+        it('should reject phrases with invalid checksum', async () => {
+            const phrase = await shareToRecoveryPhrase(testShareHex);
+            const words = phrase.split(' ');
+
+            const firstWord = words[0];
+            words[0] = words[1];
+            words[1] = firstWord;
+
+            await expect(
+                recoveryPhraseToShare(words.join(' '))
+            ).rejects.toThrow('checksum');
+        });
+    });
+
+    describe('validateRecoveryPhrase', () => {
+        it('should return true for valid phrase', async () => {
+            const phrase = await shareToRecoveryPhrase(testShareHex);
+            const isValid = await validateRecoveryPhrase(phrase);
+
+            expect(isValid).toBe(true);
+        });
+
+        it('should return false for invalid phrase', async () => {
+            const isValid = await validateRecoveryPhrase('invalid phrase that is not valid');
+
+            expect(isValid).toBe(false);
+        });
+
+        it('should return false for phrase with wrong checksum', async () => {
+            const phrase = await shareToRecoveryPhrase(testShareHex);
+            const words = phrase.split(' ');
+            const temp = words[0];
+            words[0] = words[1];
+            words[1] = temp;
+
+            const isValid = await validateRecoveryPhrase(words.join(' '));
+
+            expect(isValid).toBe(false);
+        });
+
+        it('should return false for empty string', async () => {
+            const isValid = await validateRecoveryPhrase('');
+
+            expect(isValid).toBe(false);
+        });
+
+        it('should return false for phrase with too few words', async () => {
+            const isValid = await validateRecoveryPhrase('abandon ability able about');
+
+            expect(isValid).toBe(false);
+        });
+    });
+
+    describe('countWords', () => {
+        it('should count words correctly', () => {
+            expect(countWords('one two three')).toBe(3);
+            expect(countWords('single')).toBe(1);
+            expect(countWords('')).toBe(0);
+        });
+
+        it('should handle extra whitespace', () => {
+            expect(countWords('  one   two   three  ')).toBe(3);
+            expect(countWords('\tone\ttwo\t')).toBe(2);
+            expect(countWords('\n\n')).toBe(0);
+        });
+
+        it('should handle 12-word phrase', () => {
+            const phrase = 'abandon ability able about above absent absorb abstract absurd abuse access accident';
+            expect(countWords(phrase)).toBe(12);
+        });
+
+        it('should handle 24-word phrase', () => {
+            const phrase = 'abandon ability able about above absent absorb abstract absurd abuse access accident account accuse achieve acid acoustic acquire across act action actor actress actual';
+            expect(countWords(phrase)).toBe(24);
+        });
+    });
+
+    describe('Round-trip conversion', () => {
+        it('should round-trip various share lengths', async () => {
+            const shares = [
+                '00'.repeat(16),
+                'ff'.repeat(16),
+                'abcdef'.repeat(8),
+                '123456789abcdef0'.repeat(4),
+            ];
+
+            for (const share of shares) {
+                const phrase = await shareToRecoveryPhrase(share);
+                const recovered = await recoveryPhraseToShare(phrase);
+                expect(recovered).toBe(share);
+            }
+        });
+
+        it('should handle 32-byte (64 hex char) shares correctly', async () => {
+            const share32bytes = 'a'.repeat(64);
+
+            const phrase = await shareToRecoveryPhrase(share32bytes);
+            const recovered = await recoveryPhraseToShare(phrase);
+
+            expect(recovered).toBe(share32bytes);
+        });
+    });
+});
+
+describe('Full SSS + Recovery Phrase Integration', () => {
+
+    it('should generate phrase from SSS recovery share and reconstruct original key', async () => {
+        // 1. Start with a private key (32 bytes = 64 hex chars)
+        const originalPrivateKey = 'abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab';
+
+        // 2. Split into SSS shares
+        const shares = await splitPrivateKey(originalPrivateKey);
+        console.log('Device share length:', shares.deviceShare.length);
+        console.log('Auth share length:', shares.authShare.length);
+        console.log('Recovery share length:', shares.recoveryShare.length);
+
+        // 3. Convert recovery share to phrase
+        const phrase = await shareToRecoveryPhrase(shares.recoveryShare);
+        const wordCount = phrase.split(' ').length;
+        console.log('Generated phrase word count:', wordCount);
+        console.log('Phrase:', phrase);
+
+        // 4. Validate the phrase
+        const isValid = await validateRecoveryPhrase(phrase);
+        expect(isValid).toBe(true);
+
+        // 5. Convert phrase back to share
+        const recoveredShare = await recoveryPhraseToShare(phrase);
+        expect(recoveredShare).toBe(shares.recoveryShare);
+
+        // 6. Reconstruct private key using recovery share + auth share
+        const reconstructedKey = await reconstructFromShares([
+            recoveredShare,
+            shares.authShare,
+        ]);
+
+        expect(reconstructedKey).toBe(originalPrivateKey);
+    });
+
+    it('should work with randomly generated private keys', async () => {
+        // Generate a few random 32-byte keys
+        for (let i = 0; i < 5; i++) {
+            const randomKey = Array.from({ length: 64 }, () => 
+                Math.floor(Math.random() * 16).toString(16)
+            ).join('');
+
+            const shares = await splitPrivateKey(randomKey);
+            const phrase = await shareToRecoveryPhrase(shares.recoveryShare);
+
+            // Validate
+            const isValid = await validateRecoveryPhrase(phrase);
+            expect(isValid).toBe(true);
+
+            // Round-trip
+            const recoveredShare = await recoveryPhraseToShare(phrase);
+            expect(recoveredShare).toBe(shares.recoveryShare);
+
+            // Reconstruct
+            const reconstructed = await reconstructFromShares([
+                recoveredShare,
+                shares.authShare,
+            ]);
+            expect(reconstructed).toBe(randomKey);
+        }
+    });
+
+    it('should produce consistent word count for SSS shares', async () => {
+        const privateKey = 'abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab';
+        const shares = await splitPrivateKey(privateKey);
+        
+        const phrase = await shareToRecoveryPhrase(shares.recoveryShare);
+        const wordCount = phrase.split(' ').length;
+        
+        // SSS shares from shamir-secret-sharing include an index byte
+        // 33 bytes = 264 bits + 8 checksum = 272 bits / 11 = ~25 words
+        console.log('SSS recovery share hex length:', shares.recoveryShare.length);
+        console.log('SSS recovery share byte length:', shares.recoveryShare.length / 2);
+        console.log('Word count:', wordCount);
+        
+        expect(wordCount).toBeGreaterThanOrEqual(24);
+        expect(wordCount).toBeLessThanOrEqual(27);
+    });
+});