@learncard/sss-key-manager 0.1.24 → 0.2.1

package/src/atomic-operations.test.ts

@@ -1,6 +1,6 @@
 /**
  * Atomic Operations Tests
- * 
+ *
  * Tests for split verification, atomic updates, and rollback behavior.
  */
 
@@ -13,13 +13,15 @@ import {
     atomicRecovery,
     ShareVerificationError,
     AtomicUpdateError,
+    ShareWriteRejectedError,
     type StorageOperations,
 } from './atomic-operations';
 import { generateEd25519PrivateKey } from './crypto';
 import { splitPrivateKey, reconstructFromShares } from './sss';
 
-describe('splitAndVerify', () => {
+type MockShareState = { deviceShare: string | null; authShare: string | null };
 
+describe('splitAndVerify', () => {
     it('should return verified shares that reconstruct the key', async () => {
         const privateKey = await generateEd25519PrivateKey();
 
@@ -56,6 +58,33 @@ describe('splitAndVerify', () => {
 });
 
 describe('atomicShareUpdate', () => {
+    it.each([false, true])(
+        'preserves the new share after a lost reply (existing=%s)',
+        async existing => {
+            const privateKey = await generateEd25519PrivateKey();
+            const previous = existing ? (await splitPrivateKey(privateKey)).deviceShare : undefined;
+            const storage = createMockStorage();
+            storage.deviceShare = previous ?? null;
+            storage.clearDevice = vi.fn(async () => {
+                storage.deviceShare = null;
+            });
+            storage.storeAuth = vi.fn(async share => {
+                storage.authShare = share;
+                throw new TypeError('Connection closed after commit');
+            });
+
+            await expect(
+                atomicShareUpdate(privateKey, storage, {
+                    previousDeviceShare: previous,
+                })
+            ).rejects.toMatchObject({ phase: 'store_auth', rolledBack: false });
+
+            expect(storage.clearDevice).not.toHaveBeenCalled();
+            expect(await reconstructFromShares([storage.deviceShare!, storage.authShare!])).toBe(
+                privateKey
+            );
+        }
+    );
 
     const createMockStorage = (): StorageOperations & {
         deviceShare: string | null;
@@ -64,19 +93,19 @@ describe('atomicShareUpdate', () => {
         deviceShare: null,
         authShare: null,
 
-        storeDevice: vi.fn(async function(this: any, share: string) {
+        storeDevice: vi.fn(async function (this: MockShareState, share: string) {
             this.deviceShare = share;
         }),
 
-        storeAuth: vi.fn(async function(this: any, share: string) {
+        storeAuth: vi.fn(async function (this: MockShareState, share: string) {
             this.authShare = share;
         }),
 
-        getDevice: vi.fn(async function(this: any) {
+        getDevice: vi.fn(async function (this: MockShareState) {
             return this.deviceShare;
         }),
 
-        getAuth: vi.fn(async function(this: any) {
+        getAuth: vi.fn(async function (this: MockShareState) {
             return this.authShare;
         }),
     });
@@ -101,7 +130,7 @@ describe('atomicShareUpdate', () => {
         storage.deviceShare = previousDeviceShare;
 
         // Make auth storage fail
-        storage.storeAuth = vi.fn().mockRejectedValue(new Error('Network error'));
+        storage.storeAuth = vi.fn().mockRejectedValue(new ShareWriteRejectedError('Rejected'));
 
         const onRollback = vi.fn();
 
@@ -117,6 +146,20 @@ describe('atomicShareUpdate', () => {
         expect(onRollback).toHaveBeenCalled();
     });
 
+    it('removes a fresh device share after an explicit rejection', async () => {
+        const storage = createMockStorage();
+        storage.clearDevice = vi.fn(async () => {
+            storage.deviceShare = null;
+        });
+        storage.storeAuth = vi.fn().mockRejectedValue(new ShareWriteRejectedError('Rejected'));
+
+        await expect(
+            atomicShareUpdate(await generateEd25519PrivateKey(), storage)
+        ).rejects.toMatchObject({ phase: 'store_auth', rolledBack: true });
+        expect(storage.deviceShare).toBeNull();
+        expect(storage.clearDevice).toHaveBeenCalledOnce();
+    });
+
     it('should throw AtomicUpdateError with correct phase on device storage failure', async () => {
         const privateKey = await generateEd25519PrivateKey();
         const storage = createMockStorage();
@@ -138,7 +181,9 @@ describe('atomicShareUpdate', () => {
         const privateKey = await generateEd25519PrivateKey();
         const storage = createMockStorage();
 
-        storage.storeAuth = vi.fn().mockRejectedValue(new Error('Server error'));
+        storage.storeAuth = vi
+            .fn()
+            .mockRejectedValue(new ShareWriteRejectedError('Server rejection'));
 
         try {
             await atomicShareUpdate(privateKey, storage, {
@@ -160,16 +205,12 @@ describe('atomicShareUpdate', () => {
         const shares = await atomicShareUpdate(privateKey, storage);
 
         // Verify the returned shares can reconstruct the key
-        const reconstructed = await reconstructFromShares([
-            shares.deviceShare,
-            shares.authShare,
-        ]);
+        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);
@@ -266,7 +307,6 @@ describe('verifyStoredShares', () => {
 });
 
 describe('atomicRecovery', () => {
-
     it('should reconstruct key and generate new shares', async () => {
         const privateKey = await generateEd25519PrivateKey();
         const originalShares = await splitPrivateKey(privateKey);
@@ -275,11 +315,11 @@ describe('atomicRecovery', () => {
             deviceShare: null as string | null,
             authShare: null as string | null,
 
-            storeDevice: vi.fn(async function(this: any, share: string) {
+            storeDevice: vi.fn(async function (this: MockShareState, share: string) {
                 this.deviceShare = share;
             }),
 
-            storeAuth: vi.fn(async function(this: any, share: string) {
+            storeAuth: vi.fn(async function (this: MockShareState, share: string) {
                 this.authShare = share;
             }),
         };

package/src/atomic-operations.ts

@@ -1,6 +1,6 @@
 /**
  * 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.
  */
@@ -22,6 +22,7 @@ export interface AtomicUpdateOptions {
 export interface StorageOperations {
     storeDevice: (share: string) => Promise<void>;
     storeAuth: (share: string) => Promise<void>;
+    clearDevice?: () => Promise<void>;
     getDevice?: () => Promise<string | null>;
     getAuth?: () => Promise<string | null>;
 }
@@ -50,12 +51,20 @@ export class AtomicUpdateError extends Error {
     }
 }
 
+/** A write was explicitly rejected, rather than its outcome being unknown. */
+export class ShareWriteRejectedError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'ShareWriteRejectedError';
+    }
+}
+
 /**
  * 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
@@ -95,17 +104,20 @@ export async function splitAndVerify(privateKey: string): Promise<AtomicSplitRes
 
 /**
  * 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)
- * 
+ * 2. A rejected write restores the previous state (rollback), OR
+ * 3. An indeterminate write preserves the new device share for reconciliation
+ *
  * 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
- * 
+ * 4. Roll back only if step 3 throws ShareWriteRejectedError. Network failures
+ *    may happen after commit and must never destroy the new device share.
+ *    Callers can stage storeDevice in a separate entry to retain both versions.
+ *
  * @param privateKey - The private key to split
  * @param storage - Storage operations for device and auth shares
  * @param options - Options including previous shares for rollback
@@ -150,22 +162,46 @@ export async function atomicShareUpdate(
         // 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) {
+        if (!(e instanceof ShareWriteRejectedError)) {
+            throw new AtomicUpdateError(
+                'Auth share write outcome unknown; device share preserved for reconciliation',
+                'store_auth',
+                false,
+                e instanceof Error ? e : undefined
+            );
+        }
+
+        let rolledBack = false;
+
+        // ROLLBACK: restore the previous share, or remove the newly-written
+        // share when this was an initial setup with no previous local state.
+        if (deviceStored) {
             try {
-                await storage.storeDevice(options.previousDeviceShare);
-                options.onRollback?.('Server storage failed, restored previous device share');
+                if (options.previousDeviceShare !== undefined) {
+                    await storage.storeDevice(options.previousDeviceShare);
+                    options.onRollback?.('Server storage failed, restored previous device share');
+                    rolledBack = true;
+                } else if (storage.clearDevice) {
+                    await storage.clearDevice();
+                    options.onRollback?.('Server storage failed, removed new device share');
+                    rolledBack = true;
+                }
             } 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);
+                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',
+            rolledBack
+                ? 'Failed to store auth share on server, rolled back device share'
+                : 'Failed to store auth share on server; rollback did not complete',
             'store_auth',
-            !!options.previousDeviceShare,
+            rolledBack,
             e instanceof Error ? e : undefined
         );
     }
@@ -175,10 +211,10 @@ export async function atomicShareUpdate(
 
 /**
  * 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
@@ -243,10 +279,10 @@ export async function verifyStoredShares(
 
 /**
  * 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

package/src/critical-paths.test.ts

@@ -9,7 +9,9 @@
  * Run these tests before any release that touches SSS code.
  */
 
-import { describe, it, expect } from 'vitest';
+import 'fake-indexeddb/auto';
+import { describe, it, expect, vi } from 'vitest';
+import { createSSSStrategy } from './sss-strategy';
 
 import { splitPrivateKey, reconstructFromShares, SSS_THRESHOLD } from './sss';
 import { generateEd25519PrivateKey, encryptWithPassword, decryptWithPassword } from './crypto';
@@ -20,6 +22,54 @@ import {
 } from './recovery-phrase';
 
 describe('Critical: Key must NEVER be lost', () => {
+    it('recovers a fresh account from encrypted IndexedDB after the auth-share reply is lost', async () => {
+        const config = { serverUrl: 'https://test.invalid/api' };
+        const strategy = createSSSStrategy(config);
+        strategy.setActiveUser!('indexeddb-lost-response');
+        const privateKey = await generateEd25519PrivateKey();
+        const expectedDid = 'did:key:test-owner';
+        let authShare = '';
+        const fetchMock = vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+            if (init?.method === 'PUT') {
+                authShare = JSON.parse(String(init.body)).authShare.encryptedData;
+                throw new TypeError('Lost reply');
+            }
+            return new Response(
+                JSON.stringify({ authShare, shareVersion: 1, primaryDid: expectedDid })
+            );
+        });
+
+        try {
+            await expect(
+                strategy.atomicUpdateShares!({
+                    token: 'token',
+                    providerType: 'firebase',
+                    privateKey,
+                    did: expectedDid,
+                })
+            ).rejects.toMatchObject({ rolledBack: false });
+
+            const reloaded = createSSSStrategy(config);
+            reloaded.setActiveUser!('indexeddb-lost-response');
+            expect(await reloaded.hasLocalKey()).toBe(true);
+            const result = await reloaded.reconcileShares!({
+                token: 'token',
+                providerType: 'firebase',
+                expectedDid,
+                didFromPrivateKey: async key =>
+                    key === privateKey ? expectedDid : 'did:key:wrong',
+            });
+            expect(result).toEqual({ privateKey, did: expectedDid });
+            expect(await reloaded.getLocalShareVersion!()).toBe(1);
+            expect(await reconstructFromShares([(await reloaded.getLocalKey())!, authShare])).toBe(
+                privateKey
+            );
+        } finally {
+            fetchMock.mockRestore();
+            await strategy.clearLocalKeys();
+        }
+    });
+
     describe('Share split verification (fuzz test)', () => {
         it('should verify all 6 share combinations reconstruct the key (100 iterations)', async () => {
             for (let i = 0; i < 100; i++) {

package/src/email-relay-crypto.test.ts

@@ -0,0 +1,87 @@
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import { bufferToBase64 } from './crypto';
+import {
+    decryptEmailRelayPayload,
+    encryptEmailRelayPayload,
+    generateEmailRelayConfirmationCode,
+} from './email-relay-crypto';
+
+describe('email relay encryption', () => {
+    let publicKeyBase64 = '';
+    let privateKeyBase64 = '';
+
+    beforeAll(async () => {
+        const keyPair = await crypto.subtle.generateKey(
+            { name: 'ECDH', namedCurve: 'P-256' },
+            true,
+            ['deriveBits']
+        );
+        const [publicKey, privateKey] = await Promise.all([
+            crypto.subtle.exportKey('spki', keyPair.publicKey),
+            crypto.subtle.exportKey('pkcs8', keyPair.privateKey),
+        ]);
+
+        publicKeyBase64 = bufferToBase64(publicKey);
+        privateKeyBase64 = bufferToBase64(privateKey);
+    });
+
+    it('sends no raw recovery key and round-trips with the relay private key', async () => {
+        const recoveryKey = `0001${'ab'.repeat(48)}`;
+        const confirmationCode = '483920';
+        const envelope = await encryptEmailRelayPayload(
+            {
+                targetEmail: 'Recovery@Example.com',
+                recoveryKey,
+                confirmationCode,
+                branding: { brandName: 'Test Tenant', fromDomain: 'example.com' },
+            },
+            publicKeyBase64,
+            'test-key-1'
+        );
+
+        expect(JSON.stringify(envelope)).not.toContain(recoveryKey);
+        expect(JSON.stringify(envelope)).not.toContain(confirmationCode);
+        await expect(decryptEmailRelayPayload(envelope, privateKeyBase64)).resolves.toEqual({
+            version: 1,
+            targetEmail: 'recovery@example.com',
+            recoveryKey,
+            confirmationCode,
+            branding: { brandName: 'Test Tenant', fromDomain: 'example.com' },
+        });
+    });
+
+    it('authenticates envelope metadata and ciphertext', async () => {
+        const envelope = await encryptEmailRelayPayload(
+            {
+                targetEmail: 'recovery@example.com',
+                recoveryKey: `0002${'cd'.repeat(48)}`,
+                confirmationCode: '123456',
+            },
+            publicKeyBase64,
+            'test-key-1'
+        );
+
+        await expect(
+            decryptEmailRelayPayload({ ...envelope, keyId: 'other-key' }, privateKeyBase64)
+        ).rejects.toThrow();
+
+        const lastCharacter = envelope.ciphertext.at(-1);
+        const tamperedCiphertext = `${envelope.ciphertext.slice(0, -1)}${
+            lastCharacter === 'A' ? 'B' : 'A'
+        }`;
+
+        await expect(
+            decryptEmailRelayPayload(
+                { ...envelope, ciphertext: tamperedCiphertext },
+                privateKeyBase64
+            )
+        ).rejects.toThrow();
+    });
+
+    it('generates exactly six decimal digits', () => {
+        const codes = Array.from({ length: 100 }, generateEmailRelayConfirmationCode);
+
+        expect(codes.every(code => /^\d{6}$/.test(code))).toBe(true);
+    });
+});