@learncard/sss-key-manager 0.1.20 → 0.1.22

package/README.md

@@ -8,14 +8,14 @@ This package provides a secure, self-hosted alternative to Web3Auth Single Facto
 
 ## Features
 
--   **Key Splitting**: Split ed25519 private keys into 3 shares with 2-of-3 threshold
--   **Device Storage**: Encrypted local storage using AES-GCM with IndexedDB
--   **Server Storage**: Encrypted auth share stored on server with envelope encryption
--   **Recovery Methods**:
-    -   Password-based (Argon2id KDF)
-    -   Passkey/WebAuthn PRF (coming soon)
-    -   Backup file export/import
--   **Migration**: Seamless migration from Web3Auth SFA
+- **Key Splitting**: Split ed25519 private keys into 3 shares with 2-of-3 threshold
+- **Device Storage**: Encrypted local storage using AES-GCM with IndexedDB
+- **Server Storage**: Encrypted auth share stored on server with envelope encryption
+- **Recovery Methods**:
+    - Password-based (Argon2id KDF)
+    - Passkey/WebAuthn PRF (coming soon)
+    - Backup file export/import
+- **Migration**: Seamless migration from Web3Auth SFA
 
 ## Installation
 
@@ -115,19 +115,19 @@ const privateKey = await keyManager.recover({
 
 ## Security Model
 
--   **Device Share**: Encrypted with non-extractable AES-GCM key stored in IndexedDB
--   **Auth Share**: Server-side envelope encryption (DEK + KMS-encrypted DEK)
--   **Recovery Share**: Password-based uses Argon2id KDF with secure parameters
--   **Threshold**: Any 2 of 3 shares can reconstruct the key
+- **Device Share**: Encrypted with non-extractable AES-GCM key stored in IndexedDB
+- **Auth Share**: Server-side envelope encryption (DEK + KMS-encrypted DEK)
+- **Recovery Share**: Password-based uses Argon2id KDF with secure parameters
+- **Threshold**: Any 2 of 3 shares can reconstruct the key
 
 ## Auth Provider Support
 
 The package is designed to work with any authentication provider:
 
--   Firebase Authentication (default for production)
--   SuperTokens (recommended for self-hosting/local dev)
--   Keycloak (enterprise SSO)
--   Any OIDC-compliant provider
+- Firebase Authentication (default for production)
+- SuperTokens (recommended for self-hosting/local dev)
+- Keycloak (enterprise SSO)
+- Any OIDC-compliant provider
 
 ## API Reference
 
@@ -167,6 +167,147 @@ Exports an encrypted backup file.
 
 Returns the current security level based on configured recovery methods.
 
+## Four shares
+
+`SSS_TOTAL_SHARES = 4` and `SSS_THRESHOLD = 2`: any two shares reconstruct the private key, while one share alone reveals nothing about it.
+
+| Share          | Where it lives                                                                     | Purpose                            |
+| -------------- | ---------------------------------------------------------------------------------- | ---------------------------------- |
+| Device share   | Local IndexedDB                                                                    | Same-device sign-in                |
+| Auth share     | LearnCard API server, encrypted at rest                                            | Authenticated sign-in and recovery |
+| Recovery share | Passkey-protected server record, offline phrase, or password-encrypted backup file | User-controlled recovery           |
+| Email share    | Recovery email backup, encrypted before delivery                                   | Optional additional recovery path  |
+
+Passkeys protect the recovery share using a key derived from WebAuthn PRF output. A recovery phrase encodes the share as a mnemonic; a backup file encrypts it using Argon2id password derivation and AES-GCM, with its salt and KDF parameters stored in the file.
+
+### Server-side encryption
+
+The `lca-api` service derives an AES-256-GCM key from its server `SEED` using HKDF-SHA256, with salt `lca-auth-share-encryption` and info `v1`. Each auth-share encryption uses a fresh 12-byte IV; the stored ciphertext includes the 16-byte authentication tag.
+
+This implementation encrypts the share directly with the derived key. It does **not** generate a per-share Data Encryption Key (DEK) wrapped by a separate Key Encryption Key (KEK): the `encryptedDek` field holds the format marker `server-v1`, not a wrapped DEK. Password backup encryption and server auth-share encryption are separate mechanisms.
+
+## Key Types
+
+### ContactMethod
+
+Identifies a user by their primary contact method:
+
+```typescript
+type ContactMethodType = 'email' | 'phone';
+
+interface ContactMethod {
+    type: ContactMethodType;
+    value: string;
+}
+```
+
+### SecurityLevel
+
+Describes how well-protected a user's key is:
+
+```typescript
+type SecurityLevel = 'basic' | 'enhanced' | 'advanced';
+```
+
+- **basic** — device + server share only (no recovery method)
+- **enhanced** — at least one recovery method configured
+- **advanced** — multiple recovery methods configured
+
+### RecoveryInput
+
+What the user provides to recover their key:
+
+```typescript
+type RecoveryInput =
+    | { method: 'passkey'; credentialId: string }
+    | { method: 'phrase'; phrase: string }
+    | { method: 'backup'; fileContents: string; password: string }
+    | { method: 'email'; emailShare: string };
+```
+
+### RecoverySetupInput
+
+What the user provides to set up a new recovery method:
+
+```typescript
+type RecoverySetupInput =
+    | { method: 'passkey' }
+    | { method: 'phrase' }
+    | { method: 'backup'; password: string; did: string }
+    | { method: 'email' };
+```
+
+### BackupFile
+
+The JSON structure of a downloadable backup file:
+
+```typescript
+interface BackupFile {
+    version: 1;
+    createdAt: string;
+    primaryDid: string;
+    shareVersion?: number;
+    encryptedShare: {
+        ciphertext: string;
+        iv: string;
+        salt: string;
+        kdfParams: {
+            algorithm: 'argon2id';
+            timeCost: number;
+            memoryCost: number;
+            parallelism: number;
+        };
+    };
+}
+```
+
+## SSSStrategy
+
+The main class that implements `KeyDerivationStrategy`. It is typically instantiated by the AuthCoordinator, not directly by application code.
+
+### Configuration
+
+```typescript
+interface SSSStrategyConfig {
+    serverUrl: string;
+    enableEmailBackupShare?: boolean;
+}
+```
+
+| Option                   | Default | Description                                                            |
+| ------------------------ | ------- | ---------------------------------------------------------------------- |
+| `serverUrl`              | —       | Base URL of the lca-api server (e.g., `https://api.example.com/api`)   |
+| `enableEmailBackupShare` | `false` | Automatically send a backup share to the user's email during key setup |
+
+### Key Methods
+
+| Method                                             | Purpose                                                               |
+| -------------------------------------------------- | --------------------------------------------------------------------- |
+| `fetchServerKeyStatus(token, providerType)`        | Check if a key record exists on the server for the authenticated user |
+| `setupNewKey(token, providerType, signVp)`         | Generate a new key, split it, store shares on device and server       |
+| `reconstructKey(token, providerType)`              | Reconstruct the key from device share + auth share                    |
+| `recoverKey(token, providerType, input)`           | Recover the key using a recovery method + auth share                  |
+| `hasLocalKey()`                                    | Check if a device share exists in IndexedDB                           |
+| `clearLocalKey()`                                  | Remove the device share from IndexedDB                                |
+| `setupRecoveryMethod(params)`                      | Set up a new recovery method (passkey, phrase, backup, email)         |
+| `getAvailableRecoveryMethods(token, providerType)` | List the user's configured recovery methods                           |
+
+## API Client
+
+The `api-client.ts` module provides a typed fetch wrapper for all lca-api `/keys/*` and `/qr-login/*` routes. It is used internally by the SSS strategy but can also be used directly:
+
+```typescript
+import { createApiClient } from '@learncard/sss-key-manager';
+
+const client = createApiClient({ serverUrl: 'https://api.example.com/api' });
+
+const status = await client.getAuthShare({
+    authToken: token,
+    providerType: 'firebase',
+    contactMethod: { type: 'email', value: 'user@example.com' },
+});
+```
+
 ## License
 
 MIT

package/dist/api-client.d.ts

@@ -0,0 +1,49 @@
+/**
+ * API client for SSS Key Manager server routes
+ */
+import type { AuthProvider, ServerEncryptedShare, RecoveryMethodInfo, EncryptedShare, SecurityLevel } from './types';
+export interface GetAuthShareResponse {
+    authShare: ServerEncryptedShare | null;
+    primaryDid: string | null;
+    securityLevel: SecurityLevel;
+    recoveryMethods: RecoveryMethodInfo[];
+    keyProvider: 'web3auth' | 'sss';
+    maskedRecoveryEmail?: string | null;
+}
+export interface StoreAuthShareInput {
+    authShare: ServerEncryptedShare;
+    primaryDid: string;
+    securityLevel?: SecurityLevel;
+}
+export interface StoreRecoveryShareInput {
+    type: 'passkey' | 'backup' | 'phrase' | 'email';
+    encryptedShare?: EncryptedShare;
+    credentialId?: string;
+    shareVersion?: number;
+}
+export interface ApiClientConfig {
+    serverUrl: string;
+    authProvider: AuthProvider;
+}
+export declare class SSSApiClient {
+    private serverUrl;
+    private authProvider;
+    constructor(config: ApiClientConfig);
+    private getAuthHeaders;
+    private getContactMethodFromUser;
+    getAuthShare(): Promise<GetAuthShareResponse | null>;
+    storeAuthShare(input: StoreAuthShareInput): Promise<void>;
+    addRecoveryMethod(input: StoreRecoveryShareInput): Promise<void>;
+    getRecoveryShare(type: 'passkey' | 'backup' | 'phrase' | 'email', credentialId?: string): Promise<{
+        encryptedShare?: EncryptedShare;
+        shareVersion?: number;
+    } | null>;
+    markMigrated(): Promise<void>;
+    sendEmailBackupShare(emailShare: string, overrideEmail?: string): Promise<void>;
+    addRecoveryEmail(email: string): Promise<void>;
+    verifyRecoveryEmail(code: string): Promise<{
+        maskedEmail: string;
+    }>;
+    deleteUserKey(): Promise<void>;
+}
+//# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACR,YAAY,EAGZ,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,aAAa,EAChB,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,oBAAoB;IACjC,SAAS,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACvC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,aAAa,EAAE,aAAa,CAAC;IAC7B,eAAe,EAAE,kBAAkB,EAAE,CAAC;IACtC,WAAW,EAAE,UAAU,GAAG,KAAK,CAAC;IAChC,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,mBAAmB;IAChC,SAAS,EAAE,oBAAoB,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,aAAa,CAAC;CACjC;AAED,MAAM,WAAW,uBAAuB;IACpC,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;IAChD,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,YAAY,CAAC;CAC9B;AAED,qBAAa,YAAY;IACrB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,YAAY,CAAe;gBAEvB,MAAM,EAAE,eAAe;YAKrB,cAAc;YAQd,wBAAwB;IAahC,YAAY,IAAI,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAoBpD,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBzD,iBAAiB,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBhE,gBAAgB,CAClB,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,EAC/C,YAAY,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC;QAAE,cAAc,CAAC,EAAE,cAAc,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IA+BvE,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAe7B,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgC/E,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB9C,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAkBnE,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;CAcvC"}

package/dist/atomic-operations.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 { 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 declare class ShareVerificationError extends Error {
+    readonly combination: string;
+    readonly expected: string;
+    readonly got: string;
+    constructor(message: string, combination: string, expected: string, got: string);
+}
+export declare class AtomicUpdateError extends Error {
+    readonly phase: 'split' | 'verify' | 'store_device' | 'store_auth' | 'verify_stored';
+    readonly rolledBack: boolean;
+    readonly cause?: Error | undefined;
+    constructor(message: string, phase: 'split' | 'verify' | 'store_device' | 'store_auth' | 'verify_stored', rolledBack: boolean, cause?: Error | undefined);
+}
+/**
+ * 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 declare function splitAndVerify(privateKey: string): Promise<AtomicSplitResult>;
+/**
+ * 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 declare function atomicShareUpdate(privateKey: string, storage: StorageOperations, options?: AtomicUpdateOptions): Promise<SSSShares>;
+/**
+ * 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 declare 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;
+}>;
+/**
+ * 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 declare function atomicRecovery(recoveryShare: string, authShareData: string, storage: StorageOperations, options?: AtomicUpdateOptions): Promise<{
+    privateKey: string;
+    newShares: SSSShares;
+}>;
+//# sourceMappingURL=atomic-operations.d.ts.map

package/dist/atomic-operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-operations.d.ts","sourceRoot":"","sources":["../src/atomic-operations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAA0C,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAE/E,MAAM,WAAW,iBAAiB;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,SAAS,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAChC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,iBAAiB;IAC9B,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1C;AAED,qBAAa,sBAAuB,SAAQ,KAAK;aAGzB,WAAW,EAAE,MAAM;aACnB,QAAQ,EAAE,MAAM;aAChB,GAAG,EAAE,MAAM;gBAH3B,OAAO,EAAE,MAAM,EACC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM;CAKlC;AAED,qBAAa,iBAAkB,SAAQ,KAAK;aAGpB,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,cAAc,GAAG,YAAY,GAAG,eAAe;aAC3E,UAAU,EAAE,OAAO;aACnB,KAAK,CAAC,EAAE,KAAK;gBAH7B,OAAO,EAAE,MAAM,EACC,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,cAAc,GAAG,YAAY,GAAG,eAAe,EAC3E,UAAU,EAAE,OAAO,EACnB,KAAK,CAAC,EAAE,KAAK,YAAA;CAKpC;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+BnF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,iBAAiB,CACnC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,mBAAwB,GAClC,OAAO,CAAC,SAAS,CAAC,CAuDpB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACpC,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,WAAW,GAAG,SAAS,CAAC,EACzD,WAAW,EAAE,MAAM,EACnB,iBAAiB,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAC3D,OAAO,CAAC;IACP,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,OAAO,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC,CA6CD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAChC,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,mBAAwB,GAClC,OAAO,CAAC;IACP,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,SAAS,CAAC;CACxB,CAAC,CAWD"}

package/dist/auth-coordinator.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @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';
+ * ```
+ */
+//# sourceMappingURL=auth-coordinator.d.ts.map

package/dist/auth-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-coordinator.d.ts","sourceRoot":"","sources":["../src/auth-coordinator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/crypto.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Cryptographic utilities for SSS Key Manager
+ */
+export interface KdfParams {
+    algorithm: 'argon2id';
+    timeCost: number;
+    memoryCost: number;
+    parallelism: number;
+}
+export declare const DEFAULT_KDF_PARAMS: KdfParams;
+export declare function bufferToBase64(buf: ArrayBuffer): string;
+export declare function base64ToBuffer(b64: string): Uint8Array<ArrayBuffer>;
+export declare function hexToBytes(hex: string): Uint8Array<ArrayBuffer>;
+export declare function bytesToHex(bytes: Uint8Array): string;
+export declare function deriveKeyFromPassword(password: string, salt: Uint8Array, params?: KdfParams): Promise<Uint8Array<ArrayBuffer>>;
+export declare function encryptWithPassword(plaintext: string, password: string): Promise<{
+    ciphertext: string;
+    iv: string;
+    salt: string;
+    kdfParams: KdfParams;
+}>;
+export declare function decryptWithPassword(ciphertext: string, iv: string, salt: string, password: string, params?: KdfParams): Promise<string>;
+export declare function encryptShare(share: string, key: CryptoKey, aad?: string): Promise<{
+    encryptedData: string;
+    iv: string;
+}>;
+export declare function decryptShare(encryptedData: string, iv: string, key: CryptoKey, aad?: string): Promise<string>;
+export declare function generateAesKey(): Promise<CryptoKey>;
+export declare function generateRandomBytes(length: number): Uint8Array;
+export declare function generateEd25519PrivateKey(): Promise<string>;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,MAAM,WAAW,SAAS;IACtB,SAAS,EAAE,UAAU,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,kBAAkB,EAAE,SAKhC,CAAC;AAEF,wBAAgB,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAOvD;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,CAOnE;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,CAM/D;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAIpD;AAED,wBAAsB,qBAAqB,CACvC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,UAAU,EAChB,MAAM,GAAE,SAA8B,GACvC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAWlC;AAED,wBAAsB,mBAAmB,CACrC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,CAAC,CA2BjF;AAED,wBAAsB,mBAAmB,CACrC,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,GAAE,SAA8B,GACvC,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAED,wBAAsB,YAAY,CAC9B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,SAAS,EACd,GAAG,CAAC,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAehD;AAED,wBAAsB,YAAY,CAC9B,aAAa,EAAE,MAAM,EACrB,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,SAAS,EACd,GAAG,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAkBjB;AAED,wBAAsB,cAAc,IAAI,OAAO,CAAC,SAAS,CAAC,CAKzD;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAE9D;AAED,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,MAAM,CAAC,CAGjE"}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @learncard/sss-key-manager
+ *
+ * Shamir Secret Sharing key manager for LearnCard - replaces Web3Auth SFA
+ */
+export { SSSKeyManager, createSSSKeyManager } from './key-manager';
+export { SSSApiClient } from './api-client';
+export { splitPrivateKey, reconstructPrivateKey, reconstructFromShares, SSS_TOTAL_SHARES, SSS_THRESHOLD, } from './sss';
+export { storeDeviceShare, getDeviceShare, hasDeviceShare, deleteDeviceShare, clearAllShares, listAllDeviceShares, storeShareVersion, getShareVersion, isPublicComputerMode, setPublicComputerMode, createAdaptiveStorage, } from './storage';
+export type { DeviceShareEntry } from './storage';
+export { encryptWithPassword, decryptWithPassword, deriveKeyFromPassword, generateEd25519PrivateKey, hexToBytes, bytesToHex, bufferToBase64, base64ToBuffer, DEFAULT_KDF_PARAMS, } from './crypto';
+export { createPasskeyCredential, deriveKeyFromPasskey, encryptShareWithPasskey, decryptShareWithPasskey, isWebAuthnSupported, isPRFSupported, } from './passkey';
+export type { PasskeyCredential, PasskeyEncryptedShare } from './passkey';
+export { shareToRecoveryPhrase, recoveryPhraseToShare, generateRecoveryPhrase, validateRecoveryPhrase, countWords, } from './recovery-phrase';
+export type { RecoveryPhraseData } from './recovery-phrase';
+export { splitAndVerify, atomicShareUpdate, verifyStoredShares, atomicRecovery, ShareVerificationError, AtomicUpdateError, } from './atomic-operations';
+export type { AtomicSplitResult, AtomicUpdateOptions, StorageOperations, } from './atomic-operations';
+export { createSSSStrategy } from './sss-strategy';
+export type { SSSStorageFunctions, SSSStrategyConfig } from './sss-strategy';
+export { generateEphemeralKeypair, encryptShareForTransfer, decryptShareFromTransfer, } from './qr-crypto';
+export type { EphemeralKeypair, EncryptedSharePayload } from './qr-crypto';
+export { createQrLoginSession, pollQrLoginSession, pollUntilApproved, getQrLoginSessionInfo, approveQrLoginSession, notifyDevicesForQrSession, } from './qr-login';
+export type { QrLoginSession, QrLoginSessionInfo, QrLoginClientConfig, QrPayload, PollResult, NotifyDevicesResult, } from './qr-login';
+export { AuthSessionError } from './types';
+export type { SSSKeyManagerConfig, SSSKeyDerivationProvider, KeyDerivationProvider, KeyDerivationStrategy, SSSKeyDerivationStrategy, ServerKeyStatus, AuthProvider, AuthUser, AuthProviderType, ContactMethod, ContactMethodType, RecoveryMethod, RecoveryMethodType, RecoveryMethodInfo, RecoveryInput, RecoveryResult, RecoverySetupInput, RecoverySetupResult, PasskeyRecoveryMethod, BackupFileRecoveryMethod, RecoveryPhraseRecoveryMethod, SecurityLevel, BackupFile, EncryptedShare, ServerEncryptedShare, UserKeyRecord, AuthProviderMapping, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,EACH,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,aAAa,GAChB,MAAM,OAAO,CAAC;AAEf,OAAO,EACH,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,GACxB,MAAM,WAAW,CAAC;AAEnB,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD,OAAO,EACH,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,EACzB,UAAU,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,kBAAkB,GACrB,MAAM,UAAU,CAAC;AAElB,OAAO,EACH,uBAAuB,EACvB,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,EACvB,mBAAmB,EACnB,cAAc,GACjB,MAAM,WAAW,CAAC;AAEnB,YAAY,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAE1E,OAAO,EACH,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,UAAU,GACb,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,OAAO,EACH,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,sBAAsB,EACtB,iBAAiB,GACpB,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EACR,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,GACpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,YAAY,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAE7E,OAAO,EACH,wBAAwB,EACxB,uBAAuB,EACvB,wBAAwB,GAC3B,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE3E,OAAO,EACH,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,GAC5B,MAAM,YAAY,CAAC;AAEpB,YAAY,EACR,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,SAAS,EACT,UAAU,EACV,mBAAmB,GACtB,MAAM,YAAY,CAAC;AAMpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3C,YAAY,EACR,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,EACrB,qBAAqB,EACrB,wBAAwB,EACxB,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,wBAAwB,EACxB,4BAA4B,EAC5B,aAAa,EACb,UAAU,EACV,cAAc,EACd,oBAAoB,EACpB,aAAa,EACb,mBAAmB,GACtB,MAAM,SAAS,CAAC"}

package/dist/key-manager.d.ts

@@ -0,0 +1,30 @@
+/**
+ * SSS Key Manager - Main class
+ */
+import type { SSSKeyManagerConfig, SSSKeyDerivationProvider, RecoveryMethod, RecoveryMethodInfo, SecurityLevel, BackupFile } from './types';
+export declare class SSSKeyManager implements SSSKeyDerivationProvider {
+    readonly name = "sss";
+    private config;
+    private apiClient;
+    private initialized;
+    private currentPrivateKey;
+    constructor(config: SSSKeyManagerConfig);
+    isInitialized(): boolean;
+    hasLocalKey(): Promise<boolean>;
+    connect(): Promise<string>;
+    disconnect(): Promise<void>;
+    setupNewKey(): Promise<string>;
+    setupWithKey(privateKey: string, primaryDid?: string): Promise<void>;
+    migrate(privateKey: string): Promise<void>;
+    canMigrate(): Promise<boolean>;
+    addRecoveryMethod(method: RecoveryMethod): Promise<void>;
+    generateRecoveryPhrase(): Promise<string>;
+    getRecoveryMethods(): Promise<RecoveryMethodInfo[]>;
+    recover(method: RecoveryMethod): Promise<string>;
+    getSecurityLevel(): Promise<SecurityLevel>;
+    exportBackup(password: string): Promise<BackupFile>;
+    clearLocalData(): Promise<void>;
+    deleteAccount(): Promise<void>;
+}
+export declare function createSSSKeyManager(config: SSSKeyManagerConfig): SSSKeyManager;
+//# sourceMappingURL=key-manager.d.ts.map

package/dist/key-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-manager.d.ts","sourceRoot":"","sources":["../src/key-manager.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACR,mBAAmB,EACnB,wBAAwB,EACxB,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,UAAU,EAEb,MAAM,SAAS,CAAC;AA4BjB,qBAAa,aAAc,YAAW,wBAAwB;IAC1D,QAAQ,CAAC,IAAI,SAAS;IAEtB,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,SAAS,CAAe;IAChC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,iBAAiB,CAAuB;gBAEpC,MAAM,EAAE,mBAAmB;IAQvC,aAAa,IAAI,OAAO;IAIlB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAI/B,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IA4B1B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IAM9B,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBpE,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK1C,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAK9B,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAqCxD,sBAAsB,IAAI,OAAO,CAAC,MAAM,CAAC;IAWzC,kBAAkB,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAKnD,OAAO,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IA2FhD,gBAAgB,IAAI,OAAO,CAAC,aAAa,CAAC;IAK1C,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAuBnD,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAM/B,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;CAMvC;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,aAAa,CAE9E"}

package/dist/passkey.d.ts

@@ -0,0 +1,23 @@
+/**
+ * WebAuthn Passkey utilities for SSS recovery
+ * Uses the PRF (Pseudo-Random Function) extension to derive encryption keys
+ */
+export interface PasskeyCredential {
+    credentialId: string;
+    publicKey: string;
+    transports?: AuthenticatorTransport[];
+}
+export interface PasskeyEncryptedShare {
+    encryptedData: string;
+    iv: string;
+    credentialId: string;
+}
+declare function isWebAuthnSupported(): boolean;
+declare function isPRFSupported(): Promise<boolean>;
+export declare function createPasskeyCredential(userId: string, userName: string): Promise<PasskeyCredential>;
+export declare function deriveKeyFromPasskey(credentialId: string): Promise<CryptoKey>;
+export declare function encryptShareWithPasskey(share: string, credentialId: string): Promise<PasskeyEncryptedShare>;
+export declare function decryptShareWithPasskey(encryptedShare: PasskeyEncryptedShare): Promise<string>;
+export declare function listStoredPasskeys(): Promise<PasskeyCredential[]>;
+export { isWebAuthnSupported, isPRFSupported };
+//# sourceMappingURL=passkey.d.ts.map

package/dist/passkey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"passkey.d.ts","sourceRoot":"","sources":["../src/passkey.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,WAAW,iBAAiB;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,sBAAsB,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,qBAAqB;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;CACxB;AAOD,iBAAS,mBAAmB,IAAI,OAAO,CAItC;AAED,iBAAe,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC,CAShD;AAED,wBAAsB,uBAAuB,CACzC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACjB,OAAO,CAAC,iBAAiB,CAAC,CAgE5B;AAED,wBAAsB,oBAAoB,CACtC,YAAY,EAAE,MAAM,GACrB,OAAO,CAAC,SAAS,CAAC,CAkDpB;AAED,wBAAsB,uBAAuB,CACzC,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,GACrB,OAAO,CAAC,qBAAqB,CAAC,CAiBhC;AAED,wBAAsB,uBAAuB,CACzC,cAAc,EAAE,qBAAqB,GACtC,OAAO,CAAC,MAAM,CAAC,CAcjB;AAED,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAevE;AAED,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,CAAC"}

package/dist/qr-crypto.d.ts

@@ -0,0 +1,56 @@
+/**
+ * QR Login Crypto Helpers
+ *
+ * X25519 ECDH key exchange + AES-256-GCM encryption for cross-device
+ * share transfer. Uses the Web Crypto API exclusively — no external deps.
+ *
+ * Flow:
+ *   Device B generates an ephemeral X25519 keypair, shares the public key.
+ *   Device A derives a shared secret via ECDH, encrypts the device share
+ *   with AES-256-GCM, and sends the ciphertext.
+ *   Device B decrypts with the same derived shared secret.
+ */
+export interface EphemeralKeypair {
+    /** Base64-encoded X25519 public key (sent to server / encoded in QR) */
+    publicKey: string;
+    /** Raw CryptoKey — kept in memory on Device B, never leaves the device */
+    privateKey: CryptoKey;
+}
+export interface EncryptedSharePayload {
+    /** Base64-encoded AES-256-GCM ciphertext */
+    ciphertext: string;
+    /** Base64-encoded 12-byte IV */
+    iv: string;
+    /** Base64-encoded ephemeral public key of the *sender* (Device A) */
+    senderPublicKey: string;
+}
+/**
+ * Generate an ephemeral X25519 keypair for the new device (Device B).
+ * The public key is shared via QR / short code; the private key stays in memory.
+ */
+export declare const generateEphemeralKeypair: () => Promise<EphemeralKeypair>;
+/**
+ * Encrypt a device share for transfer to Device B.
+ *
+ * Called by Device A (the logged-in device):
+ *   1. Generates its own ephemeral X25519 keypair
+ *   2. Derives a shared secret from its private key + Device B's public key
+ *   3. Encrypts the share with AES-256-GCM
+ *   4. Returns the ciphertext + IV + Device A's ephemeral public key
+ *
+ * @param deviceShare - Plaintext device share to encrypt
+ * @param recipientPublicKey - Base64-encoded X25519 public key from Device B
+ */
+export declare const encryptShareForTransfer: (deviceShare: string, recipientPublicKey: string) => Promise<EncryptedSharePayload>;
+/**
+ * Decrypt a device share received from Device A.
+ *
+ * Called by Device B (the new device):
+ *   1. Derives the shared secret from its private key + Device A's public key
+ *   2. Decrypts the ciphertext with AES-256-GCM
+ *
+ * @param payload - The encrypted payload from Device A
+ * @param recipientPrivateKey - Device B's ephemeral private CryptoKey
+ */
+export declare const decryptShareFromTransfer: (payload: EncryptedSharePayload, recipientPrivateKey: CryptoKey) => Promise<string>;
+//# sourceMappingURL=qr-crypto.d.ts.map

package/dist/qr-crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qr-crypto.d.ts","sourceRoot":"","sources":["../src/qr-crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,MAAM,WAAW,gBAAgB;IAC7B,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAElB,0EAA0E;IAC1E,UAAU,EAAE,SAAS,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IAClC,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IAEnB,gCAAgC;IAChC,EAAE,EAAE,MAAM,CAAC;IAEX,qEAAqE;IACrE,eAAe,EAAE,MAAM,CAAC;CAC3B;AAMD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,QAAa,OAAO,CAAC,gBAAgB,CAoBzE,CAAC;AAsEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,GAChC,aAAa,MAAM,EACnB,oBAAoB,MAAM,KAC3B,OAAO,CAAC,qBAAqB,CAsB/B,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,GACjC,SAAS,qBAAqB,EAC9B,qBAAqB,SAAS,KAC/B,OAAO,CAAC,MAAM,CAiBhB,CAAC"}