@learncard/sss-key-manager 0.1.13 → 0.1.15

package/src/atomic-operations.test.ts

@@ -0,0 +1,327 @@
+/**
+ * Atomic Operations Tests
+ * 
+ * Tests for split verification, atomic updates, and rollback behavior.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+import {
+    splitAndVerify,
+    atomicShareUpdate,
+    verifyStoredShares,
+    atomicRecovery,
+    ShareVerificationError,
+    AtomicUpdateError,
+    type StorageOperations,
+} from './atomic-operations';
+import { generateEd25519PrivateKey } from './crypto';
+import { splitPrivateKey, reconstructFromShares } from './sss';
+
+describe('splitAndVerify', () => {
+
+    it('should return verified shares that reconstruct the key', async () => {
+        const privateKey = await generateEd25519PrivateKey();
+
+        const result = await splitAndVerify(privateKey);
+
+        expect(result.verified).toBe(true);
+        expect(result.privateKey).toBe(privateKey);
+        expect(result.shares.deviceShare).toBeDefined();
+        expect(result.shares.authShare).toBeDefined();
+        expect(result.shares.recoveryShare).toBeDefined();
+
+        // Verify all combinations work
+        const fromDeviceAuth = await reconstructFromShares([
+            result.shares.deviceShare,
+            result.shares.authShare,
+        ]);
+        expect(fromDeviceAuth).toBe(privateKey);
+    });
+
+    it('should work for 100 random keys', async () => {
+        for (let i = 0; i < 100; i++) {
+            const privateKey = await generateEd25519PrivateKey();
+            const result = await splitAndVerify(privateKey);
+
+            expect(result.verified).toBe(true);
+
+            const reconstructed = await reconstructFromShares([
+                result.shares.deviceShare,
+                result.shares.authShare,
+            ]);
+            expect(reconstructed).toBe(privateKey);
+        }
+    });
+});
+
+describe('atomicShareUpdate', () => {
+
+    const createMockStorage = (): StorageOperations & {
+        deviceShare: string | null;
+        authShare: string | null;
+    } => ({
+        deviceShare: null,
+        authShare: null,
+
+        storeDevice: vi.fn(async function(this: any, share: string) {
+            this.deviceShare = share;
+        }),
+
+        storeAuth: vi.fn(async function(this: any, share: string) {
+            this.authShare = share;
+        }),
+
+        getDevice: vi.fn(async function(this: any) {
+            return this.deviceShare;
+        }),
+
+        getAuth: vi.fn(async function(this: any) {
+            return this.authShare;
+        }),
+    });
+
+    it('should store both device and auth shares on success', async () => {
+        const privateKey = await generateEd25519PrivateKey();
+        const storage = createMockStorage();
+
+        const shares = await atomicShareUpdate(privateKey, storage);
+
+        expect(storage.storeDevice).toHaveBeenCalledWith(shares.deviceShare);
+        expect(storage.storeAuth).toHaveBeenCalledWith(shares.authShare);
+        expect(storage.deviceShare).toBe(shares.deviceShare);
+        expect(storage.authShare).toBe(shares.authShare);
+    });
+
+    it('should rollback device share if auth storage fails', async () => {
+        const privateKey = await generateEd25519PrivateKey();
+        const previousDeviceShare = 'previous-device-share-hex';
+
+        const storage = createMockStorage();
+        storage.deviceShare = previousDeviceShare;
+
+        // Make auth storage fail
+        storage.storeAuth = vi.fn().mockRejectedValue(new Error('Network error'));
+
+        const onRollback = vi.fn();
+
+        await expect(
+            atomicShareUpdate(privateKey, storage, {
+                previousDeviceShare,
+                onRollback,
+            })
+        ).rejects.toThrow(AtomicUpdateError);
+
+        // Device share should be rolled back to previous value
+        expect(storage.deviceShare).toBe(previousDeviceShare);
+        expect(onRollback).toHaveBeenCalled();
+    });
+
+    it('should throw AtomicUpdateError with correct phase on device storage failure', async () => {
+        const privateKey = await generateEd25519PrivateKey();
+        const storage = createMockStorage();
+
+        storage.storeDevice = vi.fn().mockRejectedValue(new Error('IndexedDB error'));
+
+        try {
+            await atomicShareUpdate(privateKey, storage);
+            expect.fail('Should have thrown');
+        } catch (e) {
+            expect(e).toBeInstanceOf(AtomicUpdateError);
+            const error = e as AtomicUpdateError;
+            expect(error.phase).toBe('store_device');
+            expect(error.rolledBack).toBe(false);
+        }
+    });
+
+    it('should throw AtomicUpdateError with correct phase on auth storage failure', async () => {
+        const privateKey = await generateEd25519PrivateKey();
+        const storage = createMockStorage();
+
+        storage.storeAuth = vi.fn().mockRejectedValue(new Error('Server error'));
+
+        try {
+            await atomicShareUpdate(privateKey, storage, {
+                previousDeviceShare: 'previous',
+            });
+            expect.fail('Should have thrown');
+        } catch (e) {
+            expect(e).toBeInstanceOf(AtomicUpdateError);
+            const error = e as AtomicUpdateError;
+            expect(error.phase).toBe('store_auth');
+            expect(error.rolledBack).toBe(true);
+        }
+    });
+
+    it('should return verified shares on success', async () => {
+        const privateKey = await generateEd25519PrivateKey();
+        const storage = createMockStorage();
+
+        const shares = await atomicShareUpdate(privateKey, storage);
+
+        // Verify the returned shares can reconstruct the key
+        const reconstructed = await reconstructFromShares([
+            shares.deviceShare,
+            shares.authShare,
+        ]);
+        expect(reconstructed).toBe(privateKey);
+    });
+});
+
+describe('verifyStoredShares', () => {
+
+    it('should return healthy=true when shares match expected DID', async () => {
+        const privateKey = await generateEd25519PrivateKey();
+        const shares = await splitPrivateKey(privateKey);
+        const expectedDid = `did:key:${privateKey.slice(0, 16)}`;
+
+        const storage = {
+            getDevice: vi.fn().mockResolvedValue(shares.deviceShare),
+            getAuth: vi.fn().mockResolvedValue(shares.authShare),
+        };
+
+        const didFromPrivateKey = vi.fn().mockResolvedValue(expectedDid);
+
+        const result = await verifyStoredShares(storage, expectedDid, didFromPrivateKey);
+
+        expect(result.healthy).toBe(true);
+        expect(result.hasDeviceShare).toBe(true);
+        expect(result.hasAuthShare).toBe(true);
+        expect(result.didMatches).toBe(true);
+        expect(result.error).toBeUndefined();
+    });
+
+    it('should return healthy=false when device share is missing', async () => {
+        const storage = {
+            getDevice: vi.fn().mockResolvedValue(null),
+            getAuth: vi.fn().mockResolvedValue('some-auth-share'),
+        };
+
+        const result = await verifyStoredShares(
+            storage,
+            'did:key:expected',
+            async () => 'did:key:any'
+        );
+
+        expect(result.healthy).toBe(false);
+        expect(result.hasDeviceShare).toBe(false);
+        expect(result.error).toBe('No device share found');
+    });
+
+    it('should return healthy=false when auth share is missing', async () => {
+        const storage = {
+            getDevice: vi.fn().mockResolvedValue('some-device-share'),
+            getAuth: vi.fn().mockResolvedValue(null),
+        };
+
+        const result = await verifyStoredShares(
+            storage,
+            'did:key:expected',
+            async () => 'did:key:any'
+        );
+
+        expect(result.healthy).toBe(false);
+        expect(result.hasDeviceShare).toBe(true);
+        expect(result.hasAuthShare).toBe(false);
+        expect(result.error).toBe('No auth share found');
+    });
+
+    it('should return healthy=false when DID does not match', async () => {
+        const privateKey = await generateEd25519PrivateKey();
+        const shares = await splitPrivateKey(privateKey);
+
+        const storage = {
+            getDevice: vi.fn().mockResolvedValue(shares.deviceShare),
+            getAuth: vi.fn().mockResolvedValue(shares.authShare),
+        };
+
+        const result = await verifyStoredShares(
+            storage,
+            'did:key:expected',
+            async () => 'did:key:different'
+        );
+
+        expect(result.healthy).toBe(false);
+        expect(result.hasDeviceShare).toBe(true);
+        expect(result.hasAuthShare).toBe(true);
+        expect(result.didMatches).toBe(false);
+        expect(result.error).toContain('DID mismatch');
+    });
+
+    it('should handle reconstruction errors gracefully', async () => {
+        const storage = {
+            getDevice: vi.fn().mockResolvedValue('invalid-share'),
+            getAuth: vi.fn().mockResolvedValue('also-invalid'),
+        };
+
+        const result = await verifyStoredShares(
+            storage,
+            'did:key:expected',
+            async () => 'did:key:any'
+        );
+
+        expect(result.healthy).toBe(false);
+        expect(result.error).toBeDefined();
+    });
+});
+
+describe('atomicRecovery', () => {
+
+    it('should reconstruct key and generate new shares', async () => {
+        const privateKey = await generateEd25519PrivateKey();
+        const originalShares = await splitPrivateKey(privateKey);
+
+        const storage = {
+            deviceShare: null as string | null,
+            authShare: null as string | null,
+
+            storeDevice: vi.fn(async function(this: any, share: string) {
+                this.deviceShare = share;
+            }),
+
+            storeAuth: vi.fn(async function(this: any, share: string) {
+                this.authShare = share;
+            }),
+        };
+
+        const result = await atomicRecovery(
+            originalShares.recoveryShare,
+            originalShares.authShare,
+            storage
+        );
+
+        // Should reconstruct the correct private key
+        expect(result.privateKey).toBe(privateKey);
+
+        // Should generate new shares
+        expect(result.newShares.deviceShare).toBeDefined();
+        expect(result.newShares.authShare).toBeDefined();
+        expect(result.newShares.recoveryShare).toBeDefined();
+
+        // New shares should also reconstruct the key
+        const reconstructed = await reconstructFromShares([
+            result.newShares.deviceShare,
+            result.newShares.authShare,
+        ]);
+        expect(reconstructed).toBe(privateKey);
+    });
+
+    it('should store new device and auth shares', async () => {
+        const privateKey = await generateEd25519PrivateKey();
+        const originalShares = await splitPrivateKey(privateKey);
+
+        const storage = {
+            storeDevice: vi.fn(),
+            storeAuth: vi.fn(),
+        };
+
+        const result = await atomicRecovery(
+            originalShares.recoveryShare,
+            originalShares.authShare,
+            storage
+        );
+
+        expect(storage.storeDevice).toHaveBeenCalledWith(result.newShares.deviceShare);
+        expect(storage.storeAuth).toHaveBeenCalledWith(result.newShares.authShare);
+    });
+});

package/src/atomic-operations.ts

@@ -0,0 +1,275 @@
+/**
+ * Atomic Share Operations
+ * 
+ * Provides verified split operations and atomic updates with rollback capability.
+ * These functions ensure that private keys can NEVER be lost due to partial failures.
+ */
+
+import { splitPrivateKey, reconstructFromShares, type SSSShares } from './sss';
+
+export interface AtomicSplitResult {
+    privateKey: string;
+    shares: SSSShares;
+    verified: boolean;
+}
+
+export interface AtomicUpdateOptions {
+    previousDeviceShare?: string;
+    previousAuthShare?: string;
+    onRollback?: (reason: string) => void;
+}
+
+export interface StorageOperations {
+    storeDevice: (share: string) => Promise<void>;
+    storeAuth: (share: string) => Promise<void>;
+    getDevice?: () => Promise<string | null>;
+    getAuth?: () => Promise<string | null>;
+}
+
+export class ShareVerificationError extends Error {
+    constructor(
+        message: string,
+        public readonly combination: string,
+        public readonly expected: string,
+        public readonly got: string
+    ) {
+        super(message);
+        this.name = 'ShareVerificationError';
+    }
+}
+
+export class AtomicUpdateError extends Error {
+    constructor(
+        message: string,
+        public readonly phase: 'split' | 'verify' | 'store_device' | 'store_auth' | 'verify_stored',
+        public readonly rolledBack: boolean,
+        public readonly cause?: Error
+    ) {
+        super(message);
+        this.name = 'AtomicUpdateError';
+    }
+}
+
+/**
+ * Split a private key into shares and verify ALL combinations reconstruct correctly.
+ * 
+ * This function will NOT return until verification passes. If verification fails,
+ * it throws an error - no shares are ever returned that don't reconstruct the key.
+ * 
+ * @param privateKey - The private key to split (hex string)
+ * @returns Verified shares that are guaranteed to reconstruct the key
+ * @throws ShareVerificationError if any share combination fails verification
+ */
+export async function splitAndVerify(privateKey: string): Promise<AtomicSplitResult> {
+    const shares = await splitPrivateKey(privateKey);
+
+    // Verify ALL six combinations (4 shares, threshold 2 → C(4,2) = 6)
+    const combinations: [string, string, string][] = [
+        ['device+auth', shares.deviceShare, shares.authShare],
+        ['device+recovery', shares.deviceShare, shares.recoveryShare],
+        ['device+email', shares.deviceShare, shares.emailShare],
+        ['auth+recovery', shares.authShare, shares.recoveryShare],
+        ['auth+email', shares.authShare, shares.emailShare],
+        ['recovery+email', shares.recoveryShare, shares.emailShare],
+    ];
+
+    for (const [name, share1, share2] of combinations) {
+        const reconstructed = await reconstructFromShares([share1, share2]);
+
+        if (reconstructed !== privateKey) {
+            throw new ShareVerificationError(
+                `Share verification failed for ${name}: reconstruction mismatch`,
+                name,
+                privateKey,
+                reconstructed
+            );
+        }
+    }
+
+    return {
+        privateKey,
+        shares,
+        verified: true,
+    };
+}
+
+/**
+ * Atomically update shares with rollback on failure.
+ * 
+ * This function ensures that either:
+ * 1. Both device and auth shares are updated successfully, OR
+ * 2. The previous state is restored (rollback)
+ * 
+ * The operation flow:
+ * 1. Generate and verify new shares
+ * 2. Store device share locally
+ * 3. Store auth share on server
+ * 4. If step 3 fails, rollback step 2
+ * 
+ * @param privateKey - The private key to split
+ * @param storage - Storage operations for device and auth shares
+ * @param options - Options including previous shares for rollback
+ * @returns The new verified shares
+ * @throws AtomicUpdateError with rollback status
+ */
+export async function atomicShareUpdate(
+    privateKey: string,
+    storage: StorageOperations,
+    options: AtomicUpdateOptions = {}
+): Promise<SSSShares> {
+    let newShares: SSSShares | null = null;
+    let deviceStored = false;
+
+    try {
+        // Phase 1: Split and verify
+        const result = await splitAndVerify(privateKey);
+        newShares = result.shares;
+    } catch (e) {
+        throw new AtomicUpdateError(
+            'Failed to split and verify shares',
+            'split',
+            false,
+            e instanceof Error ? e : undefined
+        );
+    }
+
+    try {
+        // Phase 2: Store device share locally
+        await storage.storeDevice(newShares.deviceShare);
+        deviceStored = true;
+    } catch (e) {
+        throw new AtomicUpdateError(
+            'Failed to store device share locally',
+            'store_device',
+            false,
+            e instanceof Error ? e : undefined
+        );
+    }
+
+    try {
+        // Phase 3: Store auth share on server
+        await storage.storeAuth(newShares.authShare);
+    } catch (e) {
+        // ROLLBACK: Restore previous device share if we have it
+        if (options.previousDeviceShare && deviceStored) {
+            try {
+                await storage.storeDevice(options.previousDeviceShare);
+                options.onRollback?.('Server storage failed, restored previous device share');
+            } catch (rollbackError) {
+                // Rollback failed - this is a critical error
+                // The user may be in an inconsistent state
+                console.error('CRITICAL: Rollback failed after auth share storage failure', rollbackError);
+            }
+        }
+
+        throw new AtomicUpdateError(
+            'Failed to store auth share on server, rolled back device share',
+            'store_auth',
+            !!options.previousDeviceShare,
+            e instanceof Error ? e : undefined
+        );
+    }
+
+    return newShares;
+}
+
+/**
+ * Verify that stored shares can reconstruct the expected private key.
+ * 
+ * This is a health check that should be run after recovery or on login
+ * to ensure the user's shares are in a consistent state.
+ * 
+ * @param storage - Storage operations to retrieve shares
+ * @param expectedDid - The expected DID (used to verify the reconstructed key)
+ * @param didFromPrivateKey - Function to derive DID from private key
+ * @returns Object with health status and details
+ */
+export async function verifyStoredShares(
+    storage: Pick<StorageOperations, 'getDevice' | 'getAuth'>,
+    expectedDid: string,
+    didFromPrivateKey: (privateKey: string) => Promise<string>
+): Promise<{
+    healthy: boolean;
+    hasDeviceShare: boolean;
+    hasAuthShare: boolean;
+    didMatches: boolean;
+    error?: string;
+}> {
+    const result = {
+        healthy: false,
+        hasDeviceShare: false,
+        hasAuthShare: false,
+        didMatches: false,
+        error: undefined as string | undefined,
+    };
+
+    try {
+        // Check device share
+        const deviceShare = await storage.getDevice?.();
+        result.hasDeviceShare = !!deviceShare;
+
+        if (!deviceShare) {
+            result.error = 'No device share found';
+            return result;
+        }
+
+        // Check auth share
+        const authShare = await storage.getAuth?.();
+        result.hasAuthShare = !!authShare;
+
+        if (!authShare) {
+            result.error = 'No auth share found';
+            return result;
+        }
+
+        // Reconstruct and verify DID
+        const privateKey = await reconstructFromShares([deviceShare, authShare]);
+        const derivedDid = await didFromPrivateKey(privateKey);
+
+        result.didMatches = derivedDid === expectedDid;
+
+        if (!result.didMatches) {
+            result.error = `DID mismatch: expected ${expectedDid}, got ${derivedDid}`;
+            return result;
+        }
+
+        result.healthy = true;
+        return result;
+    } catch (e) {
+        result.error = e instanceof Error ? e.message : 'Unknown error during verification';
+        return result;
+    }
+}
+
+/**
+ * Create a recovery operation that atomically updates all shares.
+ * 
+ * This is used during recovery when we reconstruct from recovery+auth shares
+ * and need to generate a new device share.
+ * 
+ * @param recoveryShare - The decrypted recovery share
+ * @param authShareData - The auth share from server
+ * @param storage - Storage operations
+ * @param options - Atomic update options
+ * @returns The reconstructed private key and new shares
+ */
+export async function atomicRecovery(
+    recoveryShare: string,
+    authShareData: string,
+    storage: StorageOperations,
+    options: AtomicUpdateOptions = {}
+): Promise<{
+    privateKey: string;
+    newShares: SSSShares;
+}> {
+    // Reconstruct the private key from recovery + auth
+    const privateKey = await reconstructFromShares([recoveryShare, authShareData]);
+
+    // Generate new shares and store atomically
+    const newShares = await atomicShareUpdate(privateKey, storage, options);
+
+    return {
+        privateKey,
+        newShares,
+    };
+}

package/src/auth-coordinator.test.ts

@@ -0,0 +1,13 @@
+/**
+ * @deprecated AuthCoordinator has moved to learn-card-base/auth-coordinator.
+ * These tests are no longer valid for this package.
+ * See learn-card-base for the canonical AuthCoordinator tests.
+ */
+
+import { describe, it, expect } from 'vitest';
+
+describe('AuthCoordinator (deprecated)', () => {
+    it('has moved to learn-card-base', () => {
+        expect(true).toBe(true);
+    });
+});

package/src/auth-coordinator.ts

@@ -0,0 +1,12 @@
+/**
+ * @deprecated AuthCoordinator has moved to learn-card-base/auth-coordinator.
+ * This file is kept only as a stub during migration.
+ * Import from 'learn-card-base' instead:
+ * 
+ * ```ts
+ * import { AuthCoordinator, createAuthCoordinator } from 'learn-card-base';
+ * ```
+ */
+
+// This file intentionally left empty.
+// The AuthCoordinator class now lives in learn-card-base/src/auth-coordinator/AuthCoordinator.ts