@learncard/sss-key-manager 0.1.24 → 0.2.0

package/src/api-client.ts

@@ -5,12 +5,21 @@
 import type {
     AuthProvider,
     AuthProviderType,
-    ContactMethod,
     ServerEncryptedShare,
     RecoveryMethodInfo,
     EncryptedShare,
     SecurityLevel,
+    SssActivationState,
+    IdentityRecoverySession,
 } from './types';
+import type { EmailRelayBranding } from './email-relay-crypto';
+
+const DID_CHALLENGE_REQUIRED_ERROR =
+    'This operation requires the DID-challenge flow; use createSSSStrategy';
+
+const throwDidChallengeRequired = (): never => {
+    throw new Error(DID_CHALLENGE_REQUIRED_ERROR);
+};
 
 export interface GetAuthShareResponse {
     authShare: ServerEncryptedShare | null;
@@ -18,13 +27,16 @@ export interface GetAuthShareResponse {
     securityLevel: SecurityLevel;
     recoveryMethods: RecoveryMethodInfo[];
     keyProvider: 'web3auth' | 'sss';
+    shareVersion: number;
     maskedRecoveryEmail?: string | null;
+    sssActivationState: SssActivationState;
 }
 
 export interface StoreAuthShareInput {
     authShare: ServerEncryptedShare;
     primaryDid: string;
     securityLevel?: SecurityLevel;
+    sssActivationState?: 'provisional';
 }
 
 export interface StoreRecoveryShareInput {
@@ -34,11 +46,23 @@ export interface StoreRecoveryShareInput {
     shareVersion?: number;
 }
 
+export interface RecoverySessionMaterial {
+    authShare: ServerEncryptedShare;
+    encryptedShare?: EncryptedShare;
+    primaryDid: string;
+    shareVersion: number;
+    rebindSessionToken: string;
+}
+
 export interface ApiClientConfig {
     serverUrl: string;
     authProvider: AuthProvider;
+    escrowRelayPublicKey?: string;
+    escrowRelayKeyId?: string;
+    emailBranding?: EmailRelayBranding;
 }
 
+/** @deprecated Use `createSSSStrategy`, which implements the hardened DID-challenge flow. */
 export class SSSApiClient {
     private serverUrl: string;
     private authProvider: AuthProvider;
@@ -52,23 +76,10 @@ export class SSSApiClient {
         const token = await this.authProvider.getIdToken();
         return {
             'Content-Type': 'application/json',
-            Authorization: `Bearer ${token}`,
+            'X-Auth-Token': token,
         };
     }
 
-    private async getContactMethodFromUser(): Promise<ContactMethod | null> {
-        const user = await this.authProvider.getCurrentUser();
-        if (!user) return null;
-
-        if (user.email) {
-            return { type: 'email' as const, value: user.email.toLowerCase() };
-        }
-        if (user.phone) {
-            return { type: 'phone' as const, value: user.phone };
-        }
-        return null;
-    }
-
     async getAuthShare(): Promise<GetAuthShareResponse | null> {
         const headers = await this.getAuthHeaders();
         const providerType = this.authProvider.getProviderType();
@@ -89,54 +100,28 @@ export class SSSApiClient {
         return response.json();
     }
 
-    async storeAuthShare(input: StoreAuthShareInput): Promise<void> {
-        const headers = await this.getAuthHeaders();
-        const providerType = this.authProvider.getProviderType();
-
-        const response = await fetch(`${this.serverUrl}/keys/auth-share`, {
-            method: 'PUT',
-            headers,
-            body: JSON.stringify({
-                ...input,
-                providerType,
-            }),
-        });
-
-        if (!response.ok) {
-            throw new Error(`Failed to store auth share: ${response.statusText}`);
-        }
+    /** @deprecated Requires DID-challenge authorization. Use `createSSSStrategy`. */
+    async storeAuthShare(_input: StoreAuthShareInput): Promise<void> {
+        throwDidChallengeRequired();
     }
 
-    async addRecoveryMethod(input: StoreRecoveryShareInput): Promise<void> {
-        const headers = await this.getAuthHeaders();
-        const providerType = this.authProvider.getProviderType();
-
-        const response = await fetch(`${this.serverUrl}/keys/recovery`, {
-            method: 'POST',
-            headers,
-            body: JSON.stringify({
-                ...input,
-                providerType,
-            }),
-        });
-
-        if (!response.ok) {
-            throw new Error(`Failed to add recovery method: ${response.statusText}`);
-        }
+    /** @deprecated Requires DID-challenge authorization. Use `createSSSStrategy`. */
+    async addRecoveryMethod(_input: StoreRecoveryShareInput): Promise<void> {
+        throwDidChallengeRequired();
     }
 
     async getRecoveryShare(
         type: 'passkey' | 'backup' | 'phrase' | 'email',
         credentialId?: string
     ): Promise<{ encryptedShare?: EncryptedShare; shareVersion?: number } | null> {
+        // P0-4: authToken travels via the X-Auth-Token header — never as a
+        // query param, which would land in proxy/ALB access logs. A
+        // dedicated header (not Authorization) avoids colliding with
+        // clients that send a DID-Auth VP as Authorization for this route.
         const token = await this.authProvider.getIdToken();
         const providerType = this.authProvider.getProviderType();
 
-        const params = new URLSearchParams({
-            type,
-            providerType,
-            authToken: token,
-        });
+        const params = new URLSearchParams({ type, providerType });
 
         if (credentialId) {
             params.append('credentialId', credentialId);
@@ -144,9 +129,7 @@ export class SSSApiClient {
 
         const response = await fetch(`${this.serverUrl}/keys/recovery?${params}`, {
             method: 'GET',
-            headers: {
-                'Content-Type': 'application/json',
-            },
+            headers: { 'Content-Type': 'application/json', 'X-Auth-Token': token },
         });
 
         if (!response.ok) {
@@ -159,99 +142,107 @@ export class SSSApiClient {
         return response.json();
     }
 
-    async markMigrated(): Promise<void> {
-        const headers = await this.getAuthHeaders();
-        const providerType = this.authProvider.getProviderType();
-
-        const response = await fetch(`${this.serverUrl}/keys/migrate`, {
+    async startIdentityRecovery(email: string): Promise<void> {
+        const response = await fetch(`${this.serverUrl}/keys/recovery-session/start`, {
             method: 'POST',
-            headers,
-            body: JSON.stringify({ providerType }),
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ email }),
         });
 
         if (!response.ok) {
-            throw new Error(`Failed to mark as migrated: ${response.statusText}`);
+            throw new Error(`Failed to send recovery code: ${response.statusText}`);
         }
     }
 
-    async sendEmailBackupShare(emailShare: string, overrideEmail?: string): Promise<void> {
-        const headers = await this.getAuthHeaders();
-        const providerType = this.authProvider.getProviderType();
-
-        let email = overrideEmail;
-
-        if (!email) {
-            const user = await this.authProvider.getCurrentUser();
-            email = user?.email;
-        }
-
-        if (!email) {
-            console.warn('Cannot send email backup share: no email address available');
-            return;
-        }
-
-        const response = await fetch(`${this.serverUrl}/keys/email-backup`, {
+    async verifyIdentityRecovery(email: string, code: string): Promise<IdentityRecoverySession> {
+        const response = await fetch(`${this.serverUrl}/keys/recovery-session/verify`, {
             method: 'POST',
-            headers,
-            body: JSON.stringify({
-                providerType,
-                emailShare,
-                email,
-            }),
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ email, code }),
         });
 
         if (!response.ok) {
-            // Non-fatal: log but don't throw — the user can still use the app
-            console.warn(`Failed to send email backup share: ${response.statusText}`);
+            throw new Error(`Failed to verify recovery code: ${response.statusText}`);
         }
-    }
 
-    async addRecoveryEmail(email: string): Promise<void> {
-        const token = await this.authProvider.getIdToken();
-        const providerType = this.authProvider.getProviderType();
+        return response.json();
+    }
 
-        const response = await fetch(`${this.serverUrl}/keys/recovery-email/add`, {
+    async useIdentityRecoverySession(
+        recoverySessionToken: string,
+        type: StoreRecoveryShareInput['type'],
+        credentialId?: string
+    ): Promise<RecoverySessionMaterial> {
+        const response = await fetch(`${this.serverUrl}/keys/recovery-session/recover`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ authToken: token, providerType, email }),
+            body: JSON.stringify({ recoverySessionToken, type, credentialId }),
         });
 
         if (!response.ok) {
-            const data = await response.json().catch(() => ({}));
-            throw new Error(data?.message || `Failed to add recovery email: ${response.statusText}`);
+            throw new Error(`Failed to retrieve recovery data: ${response.statusText}`);
         }
-    }
 
-    async verifyRecoveryEmail(code: string): Promise<{ maskedEmail: string }> {
-        const token = await this.authProvider.getIdToken();
-        const providerType = this.authProvider.getProviderType();
+        return response.json();
+    }
 
-        const response = await fetch(`${this.serverUrl}/keys/recovery-email/verify`, {
+    async completeIdentityRecoveryRebind(input: {
+        recoverySessionToken: string;
+        newAuthToken: string;
+        providerType: AuthProviderType;
+        primaryDid: string;
+        authShare: ServerEncryptedShare;
+        didAuthVp: string;
+    }): Promise<{ shareVersion: number; recoveryMethodsRequireConfirmation: string[] }> {
+        const response = await fetch(`${this.serverUrl}/keys/recovery-session/rebind`, {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ authToken: token, providerType, code }),
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${input.didAuthVp}`,
+                'X-Auth-Token': input.newAuthToken,
+            },
+            body: JSON.stringify({
+                recoverySessionToken: input.recoverySessionToken,
+                providerType: input.providerType,
+                primaryDid: input.primaryDid,
+                authShare: input.authShare,
+            }),
         });
 
         if (!response.ok) {
-            const data = await response.json().catch(() => ({}));
-            throw new Error(data?.message || `Failed to verify recovery email: ${response.statusText}`);
+            throw new Error(`Failed to bind the new sign-in: ${response.statusText}`);
         }
 
         return response.json();
     }
 
-    async deleteUserKey(): Promise<void> {
-        const headers = await this.getAuthHeaders();
-        const providerType = this.authProvider.getProviderType();
+    /** @deprecated Requires DID-challenge authorization. Use `createSSSStrategy`. */
+    async markMigrated(): Promise<void> {
+        throwDidChallengeRequired();
+    }
 
-        const response = await fetch(`${this.serverUrl}/keys`, {
-            method: 'DELETE',
-            headers,
-            body: JSON.stringify({ providerType }),
-        });
+    /** @deprecated Requires DID-challenge authorization. Use `createSSSStrategy`. */
+    async activate(): Promise<void> {
+        throwDidChallengeRequired();
+    }
 
-        if (!response.ok) {
-            throw new Error(`Failed to delete user key: ${response.statusText}`);
-        }
+    /** @deprecated Requires DID-challenge authorization. Use `createSSSStrategy`. */
+    async sendEmailBackupShare(_emailShare: string, _overrideEmail?: string): Promise<void> {
+        throwDidChallengeRequired();
+    }
+
+    /** @deprecated Requires DID-challenge authorization. Use `createSSSStrategy`. */
+    async addRecoveryEmail(_email: string): Promise<void> {
+        throwDidChallengeRequired();
+    }
+
+    /** @deprecated Requires DID-challenge authorization. Use `createSSSStrategy`. */
+    async verifyRecoveryEmail(_code: string): Promise<{ maskedEmail: string }> {
+        return throwDidChallengeRequired();
+    }
+
+    /** @deprecated Requires DID-challenge authorization. Use `createSSSStrategy`. */
+    async deleteUserKey(): Promise<void> {
+        throwDidChallengeRequired();
     }
 }

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