@learncard/sss-key-manager 0.1.24 → 0.2.0

package/src/storage.test.ts

@@ -13,7 +13,7 @@
  */
 
 import 'fake-indexeddb/auto';
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 
 import {
     storeDeviceShare,
@@ -25,6 +25,11 @@ import {
     storeShareVersion,
     getShareVersion,
 } from './storage';
+import {
+    createSSSStrategy,
+    readPendingShareCandidates,
+    writePendingShareCandidates,
+} from './sss-strategy';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -249,7 +254,7 @@ describe('SSS Storage', () => {
             expect(await getShareVersion(id)).toBeNull();
         });
 
-        it('deleting one user does not affect another user\'s version', async () => {
+        it("deleting one user does not affect another user's version", async () => {
             const idA = 'sss-device-share:user-a';
             const idB = 'sss-device-share:user-b';
 
@@ -380,7 +385,10 @@ describe('SSS Storage', () => {
                 const t = db.transaction('shares', 'readwrite');
                 const s = t.objectStore('shares');
                 // Store garbage data that will fail AES-GCM decryption
-                const req = s.put({ version: 1, iv: 'bad', cipher: 'bad', keyVersion: 1 }, orphanId);
+                const req = s.put(
+                    { version: 1, iv: 'bad', cipher: 'bad', keyVersion: 1 },
+                    orphanId
+                );
                 req.onsuccess = () => resolve();
                 req.onerror = () => reject(req.error);
             });
@@ -427,11 +435,7 @@ describe('SSS Storage', () => {
 // Session-only storage (public computer mode)
 // ---------------------------------------------------------------------------
 
-import {
-    isPublicComputerMode,
-    setPublicComputerMode,
-    createAdaptiveStorage,
-} from './storage';
+import { isPublicComputerMode, setPublicComputerMode, createAdaptiveStorage } from './storage';
 
 describe('Session-only storage (public computer mode)', () => {
     beforeEach(() => {
@@ -528,3 +532,57 @@ describe('Session-only storage (public computer mode)', () => {
         });
     });
 });
+
+describe.each([false, true])(
+    'SSS automatic cleanup with adaptive storage (public mode=%s)',
+    publicMode => {
+        beforeEach(async () => {
+            sessionStorage.clear();
+            await clearAllShares();
+            setPublicComputerMode(publicMode);
+        });
+
+        afterEach(async () => {
+            sessionStorage.clear();
+            await clearAllShares();
+        });
+
+        it('preserves scoped and unscoped pending writes while clearing stale main shares', async () => {
+            const storage = createAdaptiveStorage();
+            const scoped = createSSSStrategy({ serverUrl: 'https://unused.test', storage });
+            const accountId = 'sss-device-share:account-a';
+            const otherId = 'sss-device-share:account-b';
+            const scopedPending = [{ share: 'pending-a', createdAt: Date.now() }];
+            const legacyPending = [{ share: 'pending-legacy', createdAt: Date.now() }];
+            const otherPending = [{ share: 'pending-b', createdAt: Date.now() }];
+
+            scoped.setActiveUser!('account-a');
+            await scoped.storeLocalKey('stale-a');
+            await scoped.storeLocalShareVersion!(3);
+            await writePendingShareCandidates(storage, scopedPending, accountId);
+            await storage.storeDeviceShare('share-b', otherId);
+            await storage.storeShareVersion(7, otherId);
+            await writePendingShareCandidates(storage, otherPending, otherId);
+
+            await scoped.clearLocalKeys({ preservePending: true });
+            expect(await storage.getDeviceShare(accountId)).toBeNull();
+            expect(await storage.getShareVersion(accountId)).toBeNull();
+            expect(await readPendingShareCandidates(storage, accountId)).toEqual(scopedPending);
+            expect(await scoped.getLocalKey()).toBe('pending-a');
+
+            const legacy = createSSSStrategy({ serverUrl: 'https://unused.test', storage });
+            await legacy.storeLocalKey('stale-legacy');
+            await legacy.storeLocalShareVersion!(2);
+            await writePendingShareCandidates(storage, legacyPending);
+            await legacy.clearLocalKeys({ preservePending: true });
+            expect(await storage.getDeviceShare()).toBeNull();
+            expect(await storage.getShareVersion()).toBeNull();
+            expect(await readPendingShareCandidates(storage)).toEqual(legacyPending);
+            expect(await legacy.getLocalKey()).toBe('pending-legacy');
+
+            expect(await storage.getDeviceShare(otherId)).toBe('share-b');
+            expect(await storage.getShareVersion(otherId)).toBe(7);
+            expect(await readPendingShareCandidates(storage, otherId)).toEqual(otherPending);
+        });
+    }
+);

package/src/storage.ts

@@ -70,11 +70,10 @@ async function getOrCreateMasterKey(): Promise<CryptoKey> {
 
             if (existing) return existing;
 
-            const key = await crypto.subtle.generateKey(
-                { name: 'AES-GCM', length: 256 },
-                false,
-                ['encrypt', 'decrypt']
-            );
+            const key = await crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, false, [
+                'encrypt',
+                'decrypt',
+            ]);
 
             await tx(db, KEYS_STORE, 'readwrite', s => s.put(key, 'master-key'));
 
@@ -145,7 +144,10 @@ async function decryptShare(payload: EncryptedPayload, id: string): Promise<stri
     return new TextDecoder().decode(plainBuffer);
 }
 
-export async function storeDeviceShare(share: string, id: string = DEFAULT_DEVICE_SHARE_ID): Promise<void> {
+export async function storeDeviceShare(
+    share: string,
+    id: string = DEFAULT_DEVICE_SHARE_ID
+): Promise<void> {
     const db = await openDB();
 
     try {
@@ -160,7 +162,10 @@ export async function storeDeviceShare(share: string, id: string = DEFAULT_DEVIC
  * Store the share version alongside a device share.
  * Stored as a separate key `{id}:version` to avoid changing the encryption format.
  */
-export async function storeShareVersion(version: number, id: string = DEFAULT_DEVICE_SHARE_ID): Promise<void> {
+export async function storeShareVersion(
+    version: number,
+    id: string = DEFAULT_DEVICE_SHARE_ID
+): Promise<void> {
     const db = await openDB();
 
     try {
@@ -174,7 +179,9 @@ export async function storeShareVersion(version: number, id: string = DEFAULT_DE
  * Retrieve the share version for a device share.
  * Returns null if no version is stored (legacy shares).
  */
-export async function getShareVersion(id: string = DEFAULT_DEVICE_SHARE_ID): Promise<number | null> {
+export async function getShareVersion(
+    id: string = DEFAULT_DEVICE_SHARE_ID
+): Promise<number | null> {
     const db = await openDB();
 
     try {
@@ -192,9 +199,7 @@ export async function getDeviceShare(id: string = DEFAULT_DEVICE_SHARE_ID): Prom
     const db = await openDB();
 
     try {
-        const raw = await tx<unknown>(db, SHARES_STORE, 'readonly', s =>
-            s.get(id)
-        );
+        const raw = await tx<unknown>(db, SHARES_STORE, 'readonly', s => s.get(id));
 
         if (raw == null) {
             return null;
@@ -288,7 +293,9 @@ export async function listAllDeviceShares(): Promise<DeviceShareEntry[]> {
                     // Orphaned entry — value exists but can't be decrypted.
                     // Auto-clean it (and its companion :version key) to prevent
                     // phantom "(decrypt failed)" entries from accumulating.
-                    console.warn(`SSS Storage: removing orphaned entry that failed to decrypt: ${id}`);
+                    console.warn(
+                        `SSS Storage: removing orphaned entry that failed to decrypt: ${id}`
+                    );
                     await deleteDeviceShare(id);
                     continue;
                 }
@@ -321,8 +328,10 @@ const SESSION_PREFIX = 'sss:';
 
 export function isPublicComputerMode(): boolean {
     try {
-        return typeof sessionStorage !== 'undefined' &&
-            sessionStorage.getItem('lc-session-mode') === 'public';
+        return (
+            typeof sessionStorage !== 'undefined' &&
+            sessionStorage.getItem('lc-session-mode') === 'public'
+        );
     } catch {
         return false;
     }
@@ -340,7 +349,10 @@ export function setPublicComputerMode(enabled: boolean): void {
     }
 }
 
-async function sessionStoreDeviceShare(share: string, id: string = DEFAULT_DEVICE_SHARE_ID): Promise<void> {
+async function sessionStoreDeviceShare(
+    share: string,
+    id: string = DEFAULT_DEVICE_SHARE_ID
+): Promise<void> {
     sessionStorage.setItem(`${SESSION_PREFIX}${id}`, share);
 }
 
@@ -357,11 +369,16 @@ async function sessionDeleteDeviceShare(id: string = DEFAULT_DEVICE_SHARE_ID): P
     sessionStorage.removeItem(`${SESSION_PREFIX}${id}:version`);
 }
 
-async function sessionStoreShareVersion(version: number, id: string = DEFAULT_DEVICE_SHARE_ID): Promise<void> {
+async function sessionStoreShareVersion(
+    version: number,
+    id: string = DEFAULT_DEVICE_SHARE_ID
+): Promise<void> {
     sessionStorage.setItem(`${SESSION_PREFIX}${id}:version`, String(version));
 }
 
-async function sessionGetShareVersion(id: string = DEFAULT_DEVICE_SHARE_ID): Promise<number | null> {
+async function sessionGetShareVersion(
+    id: string = DEFAULT_DEVICE_SHARE_ID
+): Promise<number | null> {
     const raw = sessionStorage.getItem(`${SESSION_PREFIX}${id}:version`);
 
     return raw !== null ? Number(raw) : null;
@@ -400,19 +417,16 @@ export function createAdaptiveStorage() {
                 : storeDeviceShare(share, id),
 
         getDeviceShare: (id?: string) =>
-            isPublicComputerMode()
-                ? sessionGetDeviceShare(id)
-                : getDeviceShare(id),
+            isPublicComputerMode() ? sessionGetDeviceShare(id) : getDeviceShare(id),
 
         hasDeviceShare: (id?: string) =>
-            isPublicComputerMode()
-                ? sessionHasDeviceShare(id)
-                : hasDeviceShare(id),
+            isPublicComputerMode() ? sessionHasDeviceShare(id) : hasDeviceShare(id),
 
         clearAllShares: (id?: string) =>
-            isPublicComputerMode()
-                ? sessionClearAllShares(id)
-                : clearAllShares(id),
+            isPublicComputerMode() ? sessionClearAllShares(id) : clearAllShares(id),
+
+        deleteDeviceShare: (id?: string) =>
+            isPublicComputerMode() ? sessionDeleteDeviceShare(id) : deleteDeviceShare(id),
 
         storeShareVersion: (version: number, id?: string) =>
             isPublicComputerMode()
@@ -420,9 +434,7 @@ export function createAdaptiveStorage() {
                 : storeShareVersion(version, id),
 
         getShareVersion: (id?: string) =>
-            isPublicComputerMode()
-                ? sessionGetShareVersion(id)
-                : getShareVersion(id),
+            isPublicComputerMode() ? sessionGetShareVersion(id) : getShareVersion(id),
     };
 }
 

package/src/types.ts

@@ -16,11 +16,23 @@ export {
     type AuthProvider,
     type RecoveryMethodInfo,
     type RecoveryResult,
+    type IdentityRecoverySession,
     type ServerKeyStatus,
+    type SssActivationState,
     type KeyDerivationStrategy,
+    type DidAuthVpSigner,
+    type EscrowEnrollmentOptions,
+    type EscrowEnrollmentState,
+    type EscrowPinStatus,
 } from '@learncard/types';
 
-import type { AuthProvider, AuthProviderType, KeyDerivationStrategy, RecoveryMethodInfo } from '@learncard/types';
+import type {
+    AuthProvider,
+    AuthProviderType,
+    KeyDerivationStrategy,
+    RecoveryMethodInfo,
+    SssActivationState,
+} from '@learncard/types';
 
 // ---------------------------------------------------------------------------
 // SSS-specific: Contact & auth provider mapping
@@ -54,7 +66,70 @@ export const SecurityLevels: readonly SecurityLevel[] = ['basic', 'enhanced', 'a
  * SSS recovery method type identifiers.
  * These are the specific recovery methods supported by the SSS strategy.
  */
-export type RecoveryMethodType = 'passkey' | 'backup' | 'phrase' | 'email';
+export type RecoveryMethodType = 'passkey' | 'backup' | 'phrase' | 'email' | 'escrow';
+
+/** Trust policy for the enclave that receives recovery material. */
+export type EscrowAttestationPolicy =
+    | { mode: 'software'; pinnedPublicKeys: string[] }
+    | { mode: 'nitro'; pinnedMeasurements: { imageSha384: string }[]; rootCertificatePem?: string };
+
+/** Public status of an escrow recovery waiting period. */
+export interface EscrowHoldStatus {
+    holdId: string;
+    releasePolicy: 'hold' | 'pin';
+    status: 'pending' | 'cancelled' | 'completed' | 'expired';
+    requestedAt: string;
+    releaseAfter: string;
+    cancelledAt?: string;
+    completedAt?: string;
+}
+
+/** Persist these secrets securely until completion; a null token means an existing hold. */
+export type EscrowRecoveryStart = EscrowHoldStatus & {
+    resumeToken: string | null;
+    clientEphemeralPrivateKey: string;
+    pinSalt?: string;
+};
+
+/** The account has no available PIN release policy. */
+export class EscrowPinUnavailableError extends Error {
+    constructor() {
+        super('PIN recovery is not available for this account.');
+        this.name = 'EscrowPinUnavailableError';
+    }
+}
+
+/** A failed PIN attempt consumes its hold; another attempt must start a fresh hold. */
+export class EscrowPinMismatchError extends Error {
+    constructor(public readonly attemptsRemaining: number) {
+        super('Incorrect PIN.');
+        this.name = 'EscrowPinMismatchError';
+    }
+}
+
+/** Temporary throttle: retry after cooldown with a fresh hold, never retry /complete. */
+export class EscrowPinThrottledError extends Error {
+    constructor() {
+        super('Too many tries right now. Wait a minute and try again.');
+        this.name = 'EscrowPinThrottledError';
+    }
+}
+
+/** A pending waiting-period request is too recent to restart. */
+export class EscrowHoldRestartThrottledError extends Error {
+    constructor(public readonly retryAfter?: string) {
+        super('A recovery request was started recently. Please wait before restarting.');
+        this.name = 'EscrowHoldRestartThrottledError';
+    }
+}
+
+/** PIN recovery is exhausted; delayed escrow recovery remains available. */
+export class EscrowPinLockedError extends Error {
+    constructor() {
+        super('Too many incorrect PIN attempts. You can still recover by waiting.');
+        this.name = 'EscrowPinLockedError';
+    }
+}
 
 export interface PasskeyRecoveryMethod {
     type: 'passkey';
@@ -73,12 +148,15 @@ export interface RecoveryPhraseRecoveryMethod {
 }
 
 /** @deprecated Use RecoveryInput instead. Kept for legacy SSSKeyManager class. */
-export type RecoveryMethod = PasskeyRecoveryMethod | BackupFileRecoveryMethod | RecoveryPhraseRecoveryMethod;
+export type RecoveryMethod =
+    PasskeyRecoveryMethod | BackupFileRecoveryMethod | RecoveryPhraseRecoveryMethod;
 
 /**
  * SSS-specific recovery input — what the user provides to recover their key.
  */
 export type RecoveryInput =
+    | { method: 'escrow-pin'; pin: string }
+    | { method: 'escrow'; holdId: string; resumeToken: string; clientEphemeralPrivateKey: string }
     | { method: 'passkey'; credentialId: string }
     | { method: 'phrase'; phrase: string }
     | { method: 'backup'; fileContents: string; password: string }
@@ -88,20 +166,34 @@ export type RecoveryInput =
  * SSS-specific recovery setup input — what the user provides to set up a method.
  */
 export type RecoverySetupInput =
+    | { method: 'escrow'; pin?: string }
     | { method: 'passkey' }
     | { method: 'phrase' }
     | { method: 'backup'; password: string; did: string }
-    | { method: 'email' };
+    | { method: 'email'; email: string };
 
 /**
  * SSS-specific recovery setup result.
  */
 export type RecoverySetupResult =
+    | { method: 'escrow'; shareVersion: number }
     | { method: 'passkey'; credentialId: string }
-    | { method: 'phrase'; phrase: string }
+    | {
+          method: 'phrase';
+          phrase: string;
+          challengeWordIndices: number[];
+          /** Shuffled choices per challenged word (the answer plus decoys not in the phrase). */
+          challengeWordOptions: string[][];
+      }
     | { method: 'backup'; backupFile: BackupFile }
     | { method: 'email' };
 
+/** Proof supplied after a pending recovery method has been created. */
+export type RecoveryConfirmationInput =
+    | { method: 'phrase'; challengeWords: string[] }
+    | { method: 'backup'; fileContents: string; password: string }
+    | { method: 'email'; code: string };
+
 // ---------------------------------------------------------------------------
 // SSS-specific: Share & encryption types
 // ---------------------------------------------------------------------------
@@ -133,6 +225,8 @@ export interface UserKeyRecord {
     recoveryMethods: RecoveryMethodInfo[];
     migratedFromWeb3Auth: boolean;
     migratedAt?: Date;
+    sssActivationState?: SssActivationState;
+    provisionalCreatedAt?: Date;
     createdAt: Date;
     updatedAt: Date;
 }
@@ -142,6 +236,8 @@ export interface BackupFile {
     createdAt: string;
     primaryDid: string;
     shareVersion?: number;
+    /** SHA-256 checksum of the decrypted share, used to verify a just-written file. */
+    shareChecksum?: string;
     encryptedShare: {
         ciphertext: string;
         iv: string;
@@ -173,7 +269,12 @@ export interface SSSKeyManagerConfig {
  * The SSS key derivation strategy — a KeyDerivationStrategy narrowed
  * with SSS-specific recovery input/output types.
  */
-export type SSSKeyDerivationStrategy = KeyDerivationStrategy<RecoveryInput, RecoverySetupInput, RecoverySetupResult>;
+export type SSSKeyDerivationStrategy = KeyDerivationStrategy<
+    RecoveryInput,
+    RecoverySetupInput,
+    RecoverySetupResult,
+    RecoveryConfirmationInput
+>;
 
 // ---------------------------------------------------------------------------
 // Legacy types (deprecated)