@learncard/sss-key-manager 0.1.20 → 0.1.21

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

@@ -1,898 +0,0 @@
-// Generated by dts-bundle-generator v6.13.0
-
-/**
- * Provider-agnostic interfaces for authentication and key derivation.
- *
- * Both @learncard/sss-key-manager and learn-card-base import from here,
- * ensuring a single canonical source for abstract interfaces without
- * coupling consumers to any specific implementation.
- */
-/**
- * Typed error for auth session issues.
- * Auth providers should throw this (instead of generic Error) when the
- * session is expired, revoked, or missing so the coordinator can
- * distinguish "not logged in" from "unexpected failure".
- */
-export declare class AuthSessionError extends Error {
-	readonly reason: "expired" | "no_session" | "revoked" | "network";
-	constructor(message: string, reason: "expired" | "no_session" | "revoked" | "network");
-}
-/**
- * Auth provider identifier. Known values: 'firebase', 'supertokens', 'keycloak', 'oidc'.
- * Use any string to support custom auth providers without modifying this type.
- */
-export type AuthProviderType = string;
-export interface AuthUser {
-	id: string;
-	email?: string;
-	phone?: string;
-	displayName?: string;
-	photoUrl?: string;
-	providerType: AuthProviderType;
-	/** Account creation timestamp (when available from the auth provider) */
-	createdAt?: Date;
-}
-/**
- * Abstract auth provider interface.
- * Implementations wrap a specific auth SDK (Firebase, Supertokens, etc.)
- * and expose a uniform API to the coordinator.
- */
-export interface AuthProvider {
-	getIdToken(forceRefresh?: boolean): Promise<string>;
-	getCurrentUser(): Promise<AuthUser | null>;
-	getProviderType(): AuthProviderType;
-	signOut(): Promise<void>;
-	/**
-	 * Attempt to silently refresh the auth session (e.g., force-refresh
-	 * the JWT using the underlying refresh token).
-	 *
-	 * Returns `true` if the session was successfully refreshed.
-	 * Returns `false` if a full re-authentication is required.
-	 *
-	 * Optional — providers that don't implement this will require full
-	 * re-auth whenever the session expires.
-	 */
-	refreshSession?(): Promise<boolean>;
-	/**
-	 * Re-authenticate with a server-issued token (e.g., a Firebase custom
-	 * token returned after a server-side account change that invalidates
-	 * the current session).
-	 *
-	 * Returns the refreshed AuthUser read directly from the auth SDK
-	 * (not from the app store, which may be stale).
-	 *
-	 * Optional — only needed by providers whose server-side account
-	 * mutations invalidate the client session.
-	 */
-	reauthenticateWithToken?(token: string): Promise<AuthUser | null>;
-}
-/**
- * Recovery method metadata returned by the server.
- * The `type` is a string so strategies can define their own method types
- * without modifying this interface.
- */
-export interface RecoveryMethodInfo {
-	type: string;
-	createdAt: Date;
-	credentialId?: string;
-}
-/**
- * Generic result of a successful recovery execution.
- * All strategies must produce a private key + DID.
- */
-export interface RecoveryResult {
-	privateKey: string;
-	did: string;
-}
-/**
- * Server key status returned by the strategy's fetchServerKeyStatus.
- * The strategy owns the server shape — different strategies may
- * have fundamentally different server payloads.
- */
-export interface ServerKeyStatus {
-	exists: boolean;
-	needsMigration: boolean;
-	primaryDid: string | null;
-	recoveryMethods: RecoveryMethodInfo[];
-	authShare: string | null;
-	shareVersion: number | null;
-	maskedRecoveryEmail?: string | null;
-}
-/**
- * Declarative capability flags for a key derivation strategy.
- *
- * UI components read these to decide which features to show.
- * Each strategy declares its own capabilities — no strategy-specific
- * checks needed in the UI layer.
- *
- * All flags default to `false` when absent.
- *
- * @example
- * ```ts
- * // SSS declares full capabilities:
- * capabilities: { recovery: true, deviceLinking: true, localKeyPersistence: true }
- *
- * // Web3Auth derives keys on-demand, nothing local to manage:
- * capabilities: { recovery: false, deviceLinking: false, localKeyPersistence: false }
- * ```
- */
-export interface KeyDerivationCapabilities {
-	/** Strategy supports user-facing recovery methods (setup + execution) */
-	recovery: boolean;
-	/** Strategy supports cross-device key transfer (e.g., QR-based device linking) */
-	deviceLinking: boolean;
-	/**
-	 * Strategy persists key material locally (e.g., device share in IndexedDB).
-	 * When true, "public computer" / "forget device" features are relevant.
-	 */
-	localKeyPersistence: boolean;
-	/**
-	 * Strategy supports upgrading the user's contact method (e.g., phone → email).
-	 * When true, the `upgradeContactMethod` method is available and the
-	 * email-linking gate can be shown for phone-only users.
-	 */
-	contactMethodUpgrade: boolean;
-}
-/**
- * Key Derivation Strategy
- *
- * Abstract interface for different key derivation implementations.
- * Used by AuthCoordinator to delegate key operations.
- *
- * The strategy owns:
- * - Local key storage
- * - Key splitting and reconstruction
- * - Server communication for remote key components
- * - Recovery method execution and setup
- * - Storage cleanup knowledge
- *
- * Type parameters allow each strategy to define its own recovery shapes:
- * - TRecoveryInput: what the user provides to recover (e.g., password, passkey)
- * - TRecoverySetupInput: what the user provides to set up a recovery method
- * - TRecoverySetupResult: what setup returns (e.g., generated phrase, credential ID)
- *
- * @example
- * // SSS strategy with specific recovery types:
- * type SSSStrategy = KeyDerivationStrategy<SSSRecoveryInput, SSSRecoverySetupInput, SSSRecoverySetupResult>;
- *
- * // Simple strategy with no recovery:
- * type SimpleStrategy = KeyDerivationStrategy<never, never, never>;
- */
-export interface KeyDerivationStrategy<TRecoveryInput = unknown, TRecoverySetupInput = unknown, TRecoverySetupResult = unknown> {
-	readonly name: string;
-	/** Declarative feature flags — UI reads these to gate features */
-	readonly capabilities: KeyDerivationCapabilities;
-	/** Check if there's a local key component (e.g., device share) */
-	hasLocalKey(): Promise<boolean>;
-	/** Get the local key component */
-	getLocalKey(): Promise<string | null>;
-	/** Store a local key component */
-	storeLocalKey(key: string): Promise<void>;
-	/** Clear all local key data */
-	clearLocalKeys(): Promise<void>;
-	/** Split a private key into shares/components */
-	splitKey(privateKey: string): Promise<{
-		localKey: string;
-		remoteKey: string;
-	}>;
-	/** Reconstruct private key from components */
-	reconstructKey(localKey: string, remoteKey: string): Promise<string>;
-	/** Verify that stored keys can reconstruct the expected DID */
-	verifyKeys?(localKey: string, remoteKey: string, expectedDid: string, didFromPrivateKey: (pk: string) => Promise<string>): Promise<boolean>;
-	/** Fetch the server-side key status for the authenticated user */
-	fetchServerKeyStatus(token: string, providerType: AuthProviderType): Promise<ServerKeyStatus>;
-	/** Store the remote key component on the server */
-	storeAuthShare(token: string, providerType: AuthProviderType, remoteKey: string, did: string, didAuthVp?: string): Promise<void>;
-	/** Mark migration complete on the server (optional — only needed for migration-capable strategies) */
-	markMigrated?(token: string, providerType: AuthProviderType, didAuthVp?: string): Promise<void>;
-	/** Execute a recovery flow and return the recovered private key + DID */
-	executeRecovery(params: {
-		token: string;
-		providerType: AuthProviderType;
-		input: TRecoveryInput;
-		/** Optional: validate the reconstructed key's DID before rotating shares */
-		didFromPrivateKey?: (privateKey: string) => Promise<string>;
-	}): Promise<RecoveryResult>;
-	/** Set up a new recovery method */
-	setupRecoveryMethod?(params: {
-		token: string;
-		providerType: AuthProviderType;
-		privateKey: string;
-		input: TRecoverySetupInput;
-		authUser?: AuthUser;
-		/** Optional: sign a DID-Auth VP JWT for server write operations */
-		signDidAuthVp?: (privateKey: string) => Promise<string>;
-	}): Promise<TRecoverySetupResult>;
-	/** Get configured recovery methods for the authenticated user */
-	getAvailableRecoveryMethods?(token: string, providerType: AuthProviderType): Promise<RecoveryMethodInfo[]>;
-	/**
-	 * Verify email ownership and upgrade the user's contact method on the
-	 * server (e.g., phone → email). The server verifies the OTP code, links
-	 * the email to the auth account (passwordless), and atomically updates
-	 * the UserKey contact method.
-	 *
-	 * Strategies that don't manage server-side contact methods can omit this.
-	 *
-	 * @param token - Auth token for the current session
-	 * @param providerType - Auth provider type
-	 * @param previousPhone - The phone number being replaced
-	 * @param email - The new email address (already OTP-verified client-side)
-	 * @param code - The 6-digit verification code
-	 */
-	upgradeContactMethod?(token: string, providerType: AuthProviderType, previousPhone: string, email: string, code: string): Promise<{
-		customToken?: string;
-	} | void>;
-	/**
-	 * Send a backup share to the user's email for fail-safe recovery.
-	 * Called by the coordinator after key setup or migration.
-	 * Implementation should be fire-and-forget (non-fatal on failure).
-	 *
-	 * @param token - Auth token for server communication
-	 * @param providerType - Auth provider type
-	 * @param privateKey - The private key to derive the email share from
-	 * @param email - Destination email address
-	 */
-	sendEmailBackupShare?(token: string, providerType: AuthProviderType, privateKey: string, email: string): Promise<void>;
-	/**
-	 * Get the share version associated with the local device share.
-	 * Used to request the matching auth share from the server and to
-	 * include in QR cross-device transfers.
-	 *
-	 * Returns null for legacy shares with no stored version.
-	 */
-	getLocalShareVersion?(): Promise<number | null>;
-	/**
-	 * Store the share version for the local device share.
-	 * Called after receiving a device share + version via QR transfer.
-	 */
-	storeLocalShareVersion?(version: number): Promise<void>;
-	/**
-	 * Inform the strategy which user is active so it can scope local storage
-	 * (e.g., device shares) per-user. Called by the coordinator after
-	 * authentication, before any local-key operations.
-	 *
-	 * Strategies that don't need per-user scoping can omit this method.
-	 *
-	 * @param userId - Stable, unique identifier for the authenticated user
-	 *                 (e.g., Firebase UID). Must NOT change across sessions.
-	 */
-	setActiveUser?(userId: string): void;
-	/** Return storage keys (e.g., IndexedDB database names) that should be preserved during logout */
-	getPreservedStorageKeys(): string[];
-	/** Strategy-specific cleanup beyond clearLocalKeys (optional) */
-	cleanup?(): Promise<void>;
-}
-export type ContactMethodType = "email" | "phone";
-export interface ContactMethod {
-	type: ContactMethodType;
-	value: string;
-}
-export interface AuthProviderMapping {
-	type: AuthProviderType;
-	id: string;
-}
-export type SecurityLevel = "basic" | "enhanced" | "advanced";
-/**
- * SSS recovery method type identifiers.
- * These are the specific recovery methods supported by the SSS strategy.
- */
-export type RecoveryMethodType = "passkey" | "backup" | "phrase" | "email";
-export interface PasskeyRecoveryMethod {
-	type: "passkey";
-	credentialId?: string;
-}
-export interface BackupFileRecoveryMethod {
-	type: "backup";
-	fileContents: string;
-	password: string;
-}
-export interface RecoveryPhraseRecoveryMethod {
-	type: "phrase";
-	phrase: string;
-}
-/** @deprecated Use RecoveryInput instead. Kept for legacy SSSKeyManager class. */
-export type RecoveryMethod = PasskeyRecoveryMethod | BackupFileRecoveryMethod | RecoveryPhraseRecoveryMethod;
-/**
- * SSS-specific recovery input — what the user provides to recover their key.
- */
-export type RecoveryInput = {
-	method: "passkey";
-	credentialId: string;
-} | {
-	method: "phrase";
-	phrase: string;
-} | {
-	method: "backup";
-	fileContents: string;
-	password: string;
-} | {
-	method: "email";
-	emailShare: string;
-};
-/**
- * SSS-specific recovery setup input — what the user provides to set up a method.
- */
-export type RecoverySetupInput = {
-	method: "passkey";
-} | {
-	method: "phrase";
-} | {
-	method: "backup";
-	password: string;
-	did: string;
-} | {
-	method: "email";
-};
-/**
- * SSS-specific recovery setup result.
- */
-export type RecoverySetupResult = {
-	method: "passkey";
-	credentialId: string;
-} | {
-	method: "phrase";
-	phrase: string;
-} | {
-	method: "backup";
-	backupFile: BackupFile;
-} | {
-	method: "email";
-};
-export interface EncryptedShare {
-	encryptedData: string;
-	iv: string;
-	salt?: string;
-}
-export interface ServerEncryptedShare {
-	encryptedData: string;
-	encryptedDek: string;
-	iv: string;
-}
-export interface UserKeyRecord {
-	contactMethod: ContactMethod;
-	authProviders: AuthProviderMapping[];
-	primaryDid: string;
-	linkedDids: string[];
-	keyProvider: "web3auth" | "sss";
-	authShare?: ServerEncryptedShare;
-	securityLevel: SecurityLevel;
-	recoveryMethods: RecoveryMethodInfo[];
-	migratedFromWeb3Auth: boolean;
-	migratedAt?: Date;
-	createdAt: Date;
-	updatedAt: Date;
-}
-export 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;
-		};
-	};
-}
-export interface SSSKeyManagerConfig {
-	serverUrl: string;
-	authProvider: AuthProvider;
-	deviceStorageKey?: string;
-}
-/**
- * The SSS key derivation strategy — a KeyDerivationStrategy narrowed
- * with SSS-specific recovery input/output types.
- */
-export type SSSKeyDerivationStrategy = KeyDerivationStrategy<RecoveryInput, RecoverySetupInput, RecoverySetupResult>;
-/** @deprecated Use KeyDerivationStrategy instead. Kept for legacy SSSKeyManager class. */
-export interface KeyDerivationProvider {
-	readonly name: string;
-	connect(): Promise<string>;
-	disconnect(): Promise<void>;
-	isInitialized(): boolean;
-	hasLocalKey(): Promise<boolean>;
-	canMigrate?(): Promise<boolean>;
-	migrate?(privateKey: string): Promise<void>;
-}
-/** @deprecated Use KeyDerivationStrategy instead. Kept for legacy SSSKeyManager class. */
-export interface SSSKeyDerivationProvider extends KeyDerivationProvider {
-	addRecoveryMethod(method: RecoveryMethod): Promise<void>;
-	getRecoveryMethods(): Promise<RecoveryMethodInfo[]>;
-	recover(method: RecoveryMethod): Promise<string>;
-	getSecurityLevel(): Promise<SecurityLevel>;
-	exportBackup(password: string): Promise<BackupFile>;
-}
-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;
-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>;
-}
-/**
- * Shamir Secret Sharing operations
- */
-export declare const SSS_TOTAL_SHARES = 4;
-export declare const SSS_THRESHOLD = 2;
-export interface SSSShares {
-	deviceShare: string;
-	authShare: string;
-	recoveryShare: string;
-	emailShare: string;
-}
-export declare function splitPrivateKey(privateKeyHex: string): Promise<SSSShares>;
-export declare function reconstructPrivateKey(share1Hex: string, share2Hex: string): Promise<string>;
-export declare function reconstructFromShares(shares: string[]): Promise<string>;
-/**
- * Device-side storage for SSS shares
- * Reuses patterns from webSecureStorage but specialized for SSS
- */
-export declare function storeDeviceShare(share: string, id?: string): Promise<void>;
-/**
- * Store the share version alongside a device share.
- * Stored as a separate key `{id}:version` to avoid changing the encryption format.
- */
-export declare function storeShareVersion(version: number, id?: string): Promise<void>;
-/**
- * Retrieve the share version for a device share.
- * Returns null if no version is stored (legacy shares).
- */
-export declare function getShareVersion(id?: string): Promise<number | null>;
-export declare function getDeviceShare(id?: string): Promise<string | null>;
-export declare function hasDeviceShare(id?: string): Promise<boolean>;
-export declare function deleteDeviceShare(id?: string): Promise<void>;
-export interface DeviceShareEntry {
-	id: string;
-	preview: string;
-	shareVersion?: number;
-}
-/**
- * List all device shares stored in IndexedDB.
- * Returns the storage key and a truncated preview for each share.
- * Useful for debugging multi-account storage.
- */
-export declare function listAllDeviceShares(): Promise<DeviceShareEntry[]>;
-export declare function isPublicComputerMode(): boolean;
-export declare function setPublicComputerMode(enabled: boolean): void;
-/**
- * Create storage functions that dynamically route to sessionStorage (public
- * computer mode) or IndexedDB (normal mode) based on the `lc-session-mode`
- * flag in sessionStorage. Checked at call time, not at creation time.
- */
-export declare function createAdaptiveStorage(): {
-	storeDeviceShare: (share: string, id?: string) => Promise<void>;
-	getDeviceShare: (id?: string) => Promise<string | null>;
-	hasDeviceShare: (id?: string) => Promise<boolean>;
-	clearAllShares: (id?: string) => Promise<void>;
-	storeShareVersion: (version: number, id?: string) => Promise<void>;
-	getShareVersion: (id?: string) => Promise<number | null>;
-};
-export declare function clearAllShares(id?: string): Promise<void>;
-/**
- * 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;
-export declare function hexToBytes(hex: string): Uint8Array;
-export declare function bytesToHex(bytes: Uint8Array): string;
-export declare function deriveKeyFromPassword(password: string, salt: Uint8Array, params?: KdfParams): Promise<Uint8Array>;
-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 generateEd25519PrivateKey(): Promise<string>;
-/**
- * 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;
-}
-export declare function isWebAuthnSupported(): boolean;
-export 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>;
-/**
- * BIP39 Recovery Phrase utilities for SSS recovery
- * The recovery phrase directly encodes a share (not encryption)
- */
-export interface RecoveryPhraseData {
-	phrase: string;
-	shareHex: string;
-}
-export declare function shareToRecoveryPhrase(shareHex: string): Promise<string>;
-export declare function recoveryPhraseToShare(phrase: string): Promise<string>;
-export declare function generateRecoveryPhrase(shareHex: string): Promise<RecoveryPhraseData>;
-export declare function validateRecoveryPhrase(phrase: string): Promise<boolean>;
-export declare function countWords(phrase: string): number;
-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;
-}>;
-export interface SSSStorageFunctions {
-	storeDeviceShare: (share: string, id?: string) => Promise<void>;
-	getDeviceShare: (id?: string) => Promise<string | null>;
-	hasDeviceShare: (id?: string) => Promise<boolean>;
-	clearAllShares: (id?: string) => Promise<void>;
-	storeShareVersion: (version: number, id?: string) => Promise<void>;
-	getShareVersion: (id?: string) => Promise<number | null>;
-}
-export interface SSSStrategyConfig {
-	/** Server URL for key share operations */
-	serverUrl: string;
-	/** Custom storage functions (defaults to IndexedDB) */
-	storage?: SSSStorageFunctions;
-	/**
-	 * Whether to automatically send a backup share to the user's email
-	 * during key setup and recovery. The share is relayed through the server
-	 * but never persisted — fire-and-forget.
-	 *
-	 * Defaults to false. Controlled by VITE_ENABLE_EMAIL_BACKUP_SHARE env var.
-	 */
-	enableEmailBackupShare?: boolean;
-	/**
-	 * Tenant identifier forwarded as `X-Tenant-Id` on every server request.
-	 * The lca-api uses this to brand recovery / OTP emails for the active
-	 * tenant. Defaults to the server's fallback tenant (learncard) when unset.
-	 */
-	tenantId?: string;
-}
-/**
- * Create an SSS key derivation strategy.
- *
- * @example
- * ```ts
- * const sssStrategy = createSSSStrategy({
- *     serverUrl: 'https://api.learncard.com',
- * });
- *
- * // Use with AuthCoordinator
- * const coordinator = createAuthCoordinator({
- *     authProvider,
- *     keyDerivation: sssStrategy,
- * });
- * ```
- */
-export declare function createSSSStrategy(config: SSSStrategyConfig): SSSKeyDerivationStrategy;
-/**
- * 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>;
-export interface QrLoginSession {
-	sessionId: string;
-	shortCode: string;
-	expiresInSeconds: number;
-}
-export interface QrLoginSessionInfo {
-	sessionId: string;
-	publicKey: string;
-	status: "pending" | "approved";
-	encryptedPayload?: string;
-	approverDid?: string;
-}
-export interface QrLoginClientConfig {
-	serverUrl: string;
-}
-export interface QrPayload {
-	/** Session ID for the relay */
-	sessionId: string;
-	/** Base64-encoded ephemeral X25519 public key */
-	publicKey: string;
-	/** Server URL for the relay */
-	serverUrl: string;
-}
-/** Result of polling — either still waiting or the device share is ready */
-export type PollResult = {
-	status: "pending";
-} | {
-	status: "approved";
-	deviceShare: string;
-	approverDid: string;
-	accountHint?: string;
-	shareVersion?: number;
-};
-/**
- * Create a QR login session and generate the ephemeral keypair.
- *
- * Returns everything Device B needs to display a QR and start polling.
- * The ephemeral private key is kept in memory — never serialized.
- */
-export declare const createQrLoginSession: (config: QrLoginClientConfig) => Promise<{
-	session: QrLoginSession;
-	ephemeralKeypair: EphemeralKeypair;
-	qrPayload: QrPayload;
-}>;
-/**
- * Poll a QR login session for approval.
- *
- * When Device A approves, this returns the decrypted device share.
- *
- * @param config - Server config
- * @param sessionId - The session to poll
- * @param ephemeralPrivateKey - Device B's ephemeral private key (for decryption)
- */
-export declare const pollQrLoginSession: (config: QrLoginClientConfig, sessionId: string, ephemeralPrivateKey: CryptoKey) => Promise<PollResult>;
-/**
- * Convenience: poll in a loop until approved or timeout.
- *
- * @param config - Server config
- * @param sessionId - The session to poll
- * @param ephemeralPrivateKey - Device B's ephemeral private key
- * @param intervalMs - Polling interval (default 2000ms)
- * @param timeoutMs - Total timeout (default 120000ms)
- * @param onPoll - Optional callback on each poll (for UI updates)
- */
-export declare const pollUntilApproved: (config: QrLoginClientConfig, sessionId: string, ephemeralPrivateKey: CryptoKey, options?: {
-	intervalMs?: number;
-	timeoutMs?: number;
-	onPoll?: (attempt: number) => void;
-	signal?: AbortSignal;
-}) => Promise<{
-	deviceShare: string;
-	approverDid: string;
-	accountHint?: string;
-	shareVersion?: number;
-}>;
-/**
- * Fetch a QR login session's public key (for Device A to encrypt against).
- *
- * @param config - Server config
- * @param lookup - Session ID or 6-digit short code
- */
-export declare const getQrLoginSessionInfo: (config: QrLoginClientConfig, lookup: string) => Promise<QrLoginSessionInfo>;
-/**
- * Approve a QR login session by encrypting and pushing the device share.
- *
- * Called by Device A (the logged-in device).
- *
- * @param config - Server config
- * @param sessionId - The session to approve
- * @param deviceShare - Plaintext device share from Device A's local storage
- * @param approverDid - DID of the approving device
- * @param recipientPublicKey - Base64 X25519 public key from the session
- * @param accountHint - Optional email or phone of the approver's account (sent to Device B as a login hint)
- * @param shareVersion - Optional share version so Device B can fetch the matching auth share
- */
-export declare const approveQrLoginSession: (config: QrLoginClientConfig, sessionId: string, deviceShare: string, approverDid: string, recipientPublicKey: string, accountHint?: string, shareVersion?: number) => Promise<void>;
-export interface NotifyDevicesResult {
-	sent: boolean;
-	deviceCount: number;
-}
-/**
- * Send a push notification to the authenticated user's other devices,
- * prompting them to open the approver flow for the given QR session.
- *
- * Called by Device B (in needs_recovery) after creating a session.
- * Requires the user's Firebase (or other auth provider) token.
- *
- * This is fire-and-forget — failure does not block the QR login flow.
- */
-export declare const notifyDevicesForQrSession: (config: QrLoginClientConfig, sessionId: string, shortCode: string, authToken: string, providerType?: string) => Promise<NotifyDevicesResult>;
-
-export {};