@learncard/sss-key-manager 0.1.23 → 0.2.0

package/dist/sss-strategy.d.ts

@@ -12,28 +12,42 @@
  * - Recovery method execution and setup
  * - Storage cleanup knowledge
  */
-import type { SSSKeyDerivationStrategy } from './types';
+import type { SSSKeyDerivationStrategy, EscrowAttestationPolicy } from './types';
+import type { EmailRelayBranding } from './email-relay-crypto';
 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>;
+    deleteDeviceShare: (id?: string) => Promise<void>;
     storeShareVersion: (version: number, id?: string) => Promise<void>;
     getShareVersion: (id?: string) => Promise<number | null>;
 }
 export interface SSSStrategyConfig {
+    /** Enable automatic enrollment under an explicit enclave trust policy. */
+    escrow?: {
+        enabled: boolean;
+        attestation: EscrowAttestationPolicy;
+    };
+    /** Report enrollment failures without logging recovery material. */
+    onEscrowError?: (err: unknown) => void;
     /** 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.
+     * Whether email recovery enrollment is enabled. Delivery is synchronous
+     * and must be confirmed with the code included in the recovery email.
      *
      * Defaults to false. Controlled by VITE_ENABLE_EMAIL_BACKUP_SHARE env var.
      */
     enableEmailBackupShare?: boolean;
+    /** Base64 DER/SPKI P-256 public key pinned for the isolated email relay. */
+    escrowRelayPublicKey?: string;
+    /** Identifier selecting the matching relay private key during rotation. */
+    escrowRelayKeyId?: string;
+    /** Tenant branding encrypted into the relay payload with the recovery key. */
+    emailBranding?: EmailRelayBranding;
     /**
      * Tenant identifier forwarded as `X-Tenant-Id` on every server request.
      * The lca-api uses this to brand recovery / OTP emails for the active
@@ -41,6 +55,22 @@ export interface SSSStrategyConfig {
      */
     tenantId?: string;
 }
+export declare const SERVER_REQUEST_TIMEOUT_MS = 30000;
+/** HTTP failure metadata without potentially sensitive server response text. */
+export declare class EscrowRequestError extends Error {
+    readonly status: number;
+    constructor(status: number);
+}
+/**
+ * Signals that an identity-recovery attempt failed after the one-shot server
+ * session was submitted and must be restarted with a new verification code.
+ */
+export declare class IdentityRecoverySessionConsumedError extends Error {
+    constructor(message: string);
+}
+/** Two tap-to-confirm questions with six choices each: a 1-in-36 guess. */
+export declare const RECOVERY_PHRASE_CHALLENGE_COUNT = 2;
+export declare const selectRecoveryPhraseChallengeIndices: (wordCount: number, challengeCount?: number) => number[];
 /**
  * Format an email share with a 4-character hex version prefix.
  *
@@ -61,6 +91,46 @@ export declare const parseVersionedEmailShare: (input: string) => {
     share: string;
     version: number | undefined;
 };
+/**
+ * Serialize every share rotation (device + server write pair). Two rotations
+ * interleaving would leave the device share and the server auth share on
+ * different polynomials, which locks the account out on the next reconstruct.
+ */
+export declare const withRotationLock: <T>(operation: () => Promise<T>) => Promise<T>;
+/** DID_CHALLENGE_TTL_SECS (5 minutes) plus a processing margin for auth-share PUTs. */
+export declare const PENDING_WRITE_EXPIRY_MS: number;
+export interface PendingShareCandidate {
+    share: string;
+    createdAt: number;
+}
+/**
+ * Read device-only candidates from independent splits; never persist an auth,
+ * recovery, or email share here (two shares from one split reveal the key).
+ * Legacy raw shares have unknown age, but must still be checked before expiry.
+ * Mutating helpers must run under the account's share-update lock.
+ */
+export declare const readPendingShareCandidates: (storage: SSSStorageFunctions, storageId?: string) => Promise<PendingShareCandidate[]>;
+/** Clear only an empty/resolved queue or when explicitly forgetting this device. */
+export declare const clearPendingShareCandidates: (storage: SSSStorageFunctions, storageId?: string) => Promise<void>;
+/** Persist the versioned device-only queue without storing another share of any split. */
+export declare const writePendingShareCandidates: (storage: SSSStorageFunctions, candidates: PendingShareCandidate[], storageId?: string) => Promise<void>;
+/** Append a candidate; never evict a live write to make room for another one. */
+export declare const addPendingShareCandidate: (storage: SSSStorageFunctions, candidate: PendingShareCandidate, storageId?: string) => Promise<void>;
+/** Roll back only the definitively rejected operation, preserving earlier in-flight writes. */
+export declare const removePendingShareCandidate: (storage: SSSStorageFunctions, share: string, storageId?: string) => Promise<void>;
+interface CurrentShareSnapshot {
+    currentVersion: number | null;
+    authShare: string | null;
+}
+/**
+ * Check current and retained history before expiry: an expired nonce does not
+ * prove a write never committed. Keep unrelated live writes even after promotion,
+ * since older servers may still commit them after this read.
+ */
+export declare const resolvePendingShareCandidates: (storage: SSSStorageFunctions, storageId: string | undefined, fetchCurrent: () => Promise<CurrentShareSnapshot>, expectedDid: string, didFromPrivateKey: (key: string) => Promise<string>, assertActiveUser?: () => void, onPromoted?: (snapshot: CurrentShareSnapshot) => void, fetchHistorical?: (version: number) => Promise<string | null>) => Promise<{
+    snapshot: CurrentShareSnapshot;
+    privateKey: string | null;
+}>;
 /**
  * Create an SSS key derivation strategy.
  *

package/dist/sss-strategy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sss-strategy.d.ts","sourceRoot":"","sources":["../src/sss-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACR,wBAAwB,EAU3B,MAAM,SAAS,CAAC;AA4BjB,MAAM,WAAW,mBAAmB;IAChC,gBAAgB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,cAAc,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAClD,cAAc,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,iBAAiB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,eAAe,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,iBAAiB;IAC9B,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAElB,uDAAuD;IACvD,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAE9B;;;;;;OAMG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IAEjC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAmID;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC,eAAO,MAAM,yBAAyB,GAAI,YAAY,MAAM,EAAE,cAAc,MAAM,KAAG,MACT,CAAC;AAE7E;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GACjC,OAAO,MAAM,KACd;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;CAY9C,CAAC;AAqGF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,wBAAwB,CA8uBrF;AAED,YAAY,EAAE,wBAAwB,EAAE,CAAC"}
+{"version":3,"file":"sss-strategy.d.ts","sourceRoot":"","sources":["../src/sss-strategy.ts"],"names":[],"mappings":"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"}

package/dist/storage.d.ts

@@ -39,6 +39,7 @@ export declare function createAdaptiveStorage(): {
     getDeviceShare: (id?: string) => Promise<string | null>;
     hasDeviceShare: (id?: string) => Promise<boolean>;
     clearAllShares: (id?: string) => Promise<void>;
+    deleteDeviceShare: (id?: string) => Promise<void>;
     storeShareVersion: (version: number, id?: string) => Promise<void>;
     getShareVersion: (id?: string) => Promise<number | null>;
 };

package/dist/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAgJH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAE,MAAgC,GAAG,OAAO,CAAC,IAAI,CAAC,CASzG;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,GAAE,MAAgC,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ5G;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,EAAE,GAAE,MAAgC,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYlG;AAED,wBAAsB,cAAc,CAAC,EAAE,GAAE,MAAgC,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAqCjG;AAED,wBAAsB,cAAc,CAAC,EAAE,GAAE,MAAgC,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3F;AAED,wBAAsB,iBAAiB,CAAC,EAAE,GAAE,MAAgC,GAAG,OAAO,CAAC,IAAI,CAAC,CAU3F;AAED,MAAM,WAAW,gBAAgB;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAoDvE;AAYD,wBAAgB,oBAAoB,IAAI,OAAO,CAO9C;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAU5D;AAiDD;;;;GAIG;AACH,wBAAgB,qBAAqB;8BAEH,MAAM,OAAO,MAAM;0BAKvB,MAAM;0BAKN,MAAM;0BAKN,MAAM;iCAKC,MAAM,OAAO,MAAM;2BAKzB,MAAM;EAKpC;AAED,wBAAsB,cAAc,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsC/D"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA+IH,wBAAsB,gBAAgB,CAClC,KAAK,EAAE,MAAM,EACb,EAAE,GAAE,MAAgC,GACrC,OAAO,CAAC,IAAI,CAAC,CASf;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACnC,OAAO,EAAE,MAAM,EACf,EAAE,GAAE,MAAgC,GACrC,OAAO,CAAC,IAAI,CAAC,CAQf;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACjC,EAAE,GAAE,MAAgC,GACrC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYxB;AAED,wBAAsB,cAAc,CAAC,EAAE,GAAE,MAAgC,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAmCjG;AAED,wBAAsB,cAAc,CAAC,EAAE,GAAE,MAAgC,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3F;AAED,wBAAsB,iBAAiB,CAAC,EAAE,GAAE,MAAgC,GAAG,OAAO,CAAC,IAAI,CAAC,CAU3F;AAED,MAAM,WAAW,gBAAgB;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAsDvE;AAYD,wBAAgB,oBAAoB,IAAI,OAAO,CAS9C;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAU5D;AAyDD;;;;GAIG;AACH,wBAAgB,qBAAqB;8BAEH,MAAM,OAAO,MAAM;0BAKvB,MAAM;0BAGN,MAAM;0BAGN,MAAM;6BAGH,MAAM;iCAGF,MAAM,OAAO,MAAM;2BAKzB,MAAM;EAGpC;AAED,wBAAsB,cAAc,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsC/D"}

package/dist/types.d.ts

@@ -4,8 +4,8 @@
  * Re-exports provider-agnostic interfaces from @learncard/types
  * and defines SSS-specific types (recovery shapes, backup files, etc.).
  */
-export { AuthSessionError, type AuthProviderType, type AuthUser, type AuthProvider, type RecoveryMethodInfo, type RecoveryResult, type ServerKeyStatus, type KeyDerivationStrategy, } from '@learncard/types';
-import type { AuthProvider, AuthProviderType, KeyDerivationStrategy, RecoveryMethodInfo } from '@learncard/types';
+export { AuthSessionError, type AuthProviderType, type AuthUser, 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, SssActivationState } from '@learncard/types';
 export type ContactMethodType = 'email' | 'phone';
 export interface ContactMethod {
     type: ContactMethodType;
@@ -21,7 +21,56 @@ export declare const SecurityLevels: readonly SecurityLevel[];
  * 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 declare class EscrowPinUnavailableError extends Error {
+    constructor();
+}
+/** A failed PIN attempt consumes its hold; another attempt must start a fresh hold. */
+export declare class EscrowPinMismatchError extends Error {
+    readonly attemptsRemaining: number;
+    constructor(attemptsRemaining: number);
+}
+/** Temporary throttle: retry after cooldown with a fresh hold, never retry /complete. */
+export declare class EscrowPinThrottledError extends Error {
+    constructor();
+}
+/** A pending waiting-period request is too recent to restart. */
+export declare class EscrowHoldRestartThrottledError extends Error {
+    readonly retryAfter?: string | undefined;
+    constructor(retryAfter?: string | undefined);
+}
+/** PIN recovery is exhausted; delayed escrow recovery remains available. */
+export declare class EscrowPinLockedError extends Error {
+    constructor();
+}
 export interface PasskeyRecoveryMethod {
     type: 'passkey';
     credentialId?: string;
@@ -41,6 +90,14 @@ export type RecoveryMethod = PasskeyRecoveryMethod | BackupFileRecoveryMethod |
  * 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;
 } | {
@@ -58,6 +115,9 @@ 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';
@@ -67,22 +127,41 @@ export type RecoverySetupInput = {
     did: string;
 } | {
     method: 'email';
+    email: string;
 };
 /**
  * SSS-specific recovery setup result.
  */
 export type RecoverySetupResult = {
+    method: 'escrow';
+    shareVersion: number;
+} | {
     method: 'passkey';
     credentialId: 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;
+};
 export interface EncryptedShare {
     encryptedData: string;
     iv: string;
@@ -104,6 +183,8 @@ export interface UserKeyRecord {
     recoveryMethods: RecoveryMethodInfo[];
     migratedFromWeb3Auth: boolean;
     migratedAt?: Date;
+    sssActivationState?: SssActivationState;
+    provisionalCreatedAt?: Date;
     createdAt: Date;
     updatedAt: Date;
 }
@@ -112,6 +193,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;
@@ -133,7 +216,7 @@ 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>;
 /** @deprecated Use KeyDerivationStrategy instead. Kept for legacy SSSKeyManager class. */
 export interface KeyDerivationProvider {
     readonly name: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EACH,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,eAAe,GACvB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EACR,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EACrB,MAAM,kBAAkB,CAAC;AAM1B,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,OAAO,CAAC;AAElD,MAAM,WAAW,aAAa;IAC1B,IAAI,EAAE,iBAAiB,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAChC,IAAI,EAAE,gBAAgB,CAAC;IACvB,EAAE,EAAE,MAAM,CAAC;CACd;AAMD,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,CAAC;AAE9D,eAAO,MAAM,cAAc,EAAE,SAAS,aAAa,EAA+C,CAAC;AAMnG;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEtF,oEAAoE;AACpE,MAAM,MAAM,uBAAuB,GAC7B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,gBAAgB,EAAE,MAAM,EAAE,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,kBAAkB,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpG,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,GAAG,KAAK,CAAC;IAC9B,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,CAAC;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,4FAA4F;AAC5F,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,GAAG;IACjD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,yBAAyB,EAAE,MAAM,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,uDAAuD;AACvD,qBAAa,yBAA0B,SAAQ,KAAK;;CAKnD;AAED,uFAAuF;AACvF,qBAAa,sBAAuB,SAAQ,KAAK;aACjB,iBAAiB,EAAE,MAAM;gBAAzB,iBAAiB,EAAE,MAAM;CAIxD;AAED,yFAAyF;AACzF,qBAAa,uBAAwB,SAAQ,KAAK;;CAKjD;AAED,iEAAiE;AACjE,qBAAa,+BAAgC,SAAQ,KAAK;aAC1B,UAAU,CAAC,EAAE,MAAM;gBAAnB,UAAU,CAAC,EAAE,MAAM,YAAA;CAIlD;AAED,4EAA4E;AAC5E,qBAAa,oBAAqB,SAAQ,KAAK;;CAK9C;AAED,MAAM,WAAW,qBAAqB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,wBAAwB;IACrC,IAAI,EAAE,QAAQ,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,4BAA4B;IACzC,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,kFAAkF;AAClF,MAAM,MAAM,cAAc,GACtB,qBAAqB,GAAG,wBAAwB,GAAG,4BAA4B,CAAC;AAEpF;;GAEG;AACH,MAAM,MAAM,aAAa,GACnB;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,yBAAyB,EAAE,MAAM,CAAA;CAAE,GAC5F;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C;;GAEG;AACH,MAAM,MAAM,kBAAkB,GACxB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GACpB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC;;GAEG;AACH,MAAM,MAAM,mBAAmB,GACzB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC3C;IACI,MAAM,EAAE,QAAQ,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,uFAAuF;IACvF,oBAAoB,EAAE,MAAM,EAAE,EAAE,CAAC;CACpC,GACD;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,GAC5C;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1B,uEAAuE;AACvE,MAAM,MAAM,yBAAyB,GAC/B;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,cAAc,EAAE,MAAM,EAAE,CAAA;CAAE,GAC9C;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAMxC,MAAM,WAAW,cAAc;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;CACd;AAMD,MAAM,WAAW,aAAa;IAC1B,aAAa,EAAE,aAAa,CAAC;IAC7B,aAAa,EAAE,mBAAmB,EAAE,CAAC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,EAAE,UAAU,GAAG,KAAK,CAAC;IAChC,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,aAAa,EAAE,aAAa,CAAC;IAC7B,eAAe,EAAE,kBAAkB,EAAE,CAAC;IACtC,oBAAoB,EAAE,OAAO,CAAC;IAC9B,UAAU,CAAC,EAAE,IAAI,CAAC;IAClB,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,oBAAoB,CAAC,EAAE,IAAI,CAAC;IAC5B,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACvB,OAAO,EAAE,CAAC,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE;QACZ,UAAU,EAAE,MAAM,CAAC;QACnB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE;YACP,SAAS,EAAE,UAAU,CAAC;YACtB,QAAQ,EAAE,MAAM,CAAC;YACjB,UAAU,EAAE,MAAM,CAAC;YACnB,WAAW,EAAE,MAAM,CAAC;SACvB,CAAC;KACL,CAAC;CACL;AAMD,MAAM,WAAW,mBAAmB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,YAAY,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAMD;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,qBAAqB,CACxD,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,CAC5B,CAAC;AAMF,0FAA0F;AAC1F,MAAM,WAAW,qBAAqB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,aAAa,IAAI,OAAO,CAAC;IACzB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,UAAU,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,OAAO,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/C;AAED,0FAA0F;AAC1F,MAAM,WAAW,wBAAyB,SAAQ,qBAAqB;IACnE,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,kBAAkB,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACpD,OAAO,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjD,gBAAgB,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;IAC3C,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACvD"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/sss-key-manager",
-    "version": "0.1.23",
+    "version": "0.2.0",
     "description": "Shamir Secret Sharing key manager for LearnCard - replaces Web3Auth SFA",
     "main": "./dist/index.js",
     "module": "./dist/sss-key-manager.esm.js",
@@ -38,7 +38,7 @@
         "vitest": "4.1.11"
     },
     "dependencies": {
-        "@learncard/types": "5.20.0",
+        "@learncard/types": "5.22.0",
         "@noble/ed25519": "^2.0.0",
         "@scure/bip39": "^1.2.1",
         "hash-wasm": "^4.11.0",

package/src/api-client.test.ts

@@ -0,0 +1,122 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { SSSApiClient } from './api-client';
+
+import type { AuthProvider } from './types';
+
+const SENTINEL_TOKEN = 'SENTINEL_TOKEN_XYZ';
+const DID_CHALLENGE_ERROR = 'This operation requires the DID-challenge flow; use createSSSStrategy';
+
+const createMockAuthProvider = (): AuthProvider => ({
+    getIdToken: vi.fn().mockResolvedValue(SENTINEL_TOKEN),
+    getCurrentUser: vi.fn().mockResolvedValue({
+        id: 'user-123',
+        email: 'sentinel-user@example.com',
+        providerType: 'firebase' as const,
+    }),
+    getProviderType: vi.fn().mockReturnValue('firebase' as const),
+    signOut: vi.fn().mockResolvedValue(undefined),
+});
+
+describe('SSSApiClient', () => {
+    let client: SSSApiClient;
+    let calls: { url: string; init?: RequestInit }[];
+
+    beforeEach(() => {
+        calls = [];
+
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+            calls.push({ url: url.toString(), init });
+            return new Response(
+                JSON.stringify({
+                    authShare: null,
+                    primaryDid: null,
+                    securityLevel: 'basic',
+                    recoveryMethods: [],
+                    keyProvider: 'sss',
+                    shareVersion: 1,
+                    sssActivationState: 'active',
+                    recoverySessionToken: 'recovery-session-token',
+                    rebindSessionToken: 'rebind-session-token',
+                    recoveryMethodsRequireConfirmation: [],
+                }),
+                { status: 200 }
+            );
+        });
+
+        client = new SSSApiClient({
+            serverUrl: 'http://test-server:5100/api',
+            authProvider: createMockAuthProvider(),
+        });
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it('uses X-Auth-Token rather than Authorization for provider-authenticated reads', async () => {
+        await client.getAuthShare();
+
+        const headers = calls[0]!.init?.headers as Record<string, string>;
+        expect(headers['X-Auth-Token']).toBe(SENTINEL_TOKEN);
+        expect(headers.Authorization).toBeUndefined();
+        expect(calls[0]!.url).not.toContain(SENTINEL_TOKEN);
+    });
+
+    it('keeps recovery read credentials out of the URL', async () => {
+        await client.getRecoveryShare('passkey', 'credential-1');
+
+        const headers = calls[0]!.init?.headers as Record<string, string>;
+        expect(headers['X-Auth-Token']).toBe(SENTINEL_TOKEN);
+        expect(calls[0]!.url).not.toContain(SENTINEL_TOKEN);
+        expect(calls[0]!.url).not.toMatch(/[?&](token|share)=/i);
+    });
+
+    it('retains the valid unauthenticated identity-recovery helpers', async () => {
+        await client.startIdentityRecovery('recovery@example.com');
+        await client.verifyIdentityRecovery('recovery@example.com', '123456');
+        await client.useIdentityRecoverySession('recovery-session-token', 'phrase');
+
+        expect(calls.map(call => call.url)).toEqual([
+            'http://test-server:5100/api/keys/recovery-session/start',
+            'http://test-server:5100/api/keys/recovery-session/verify',
+            'http://test-server:5100/api/keys/recovery-session/recover',
+        ]);
+    });
+
+    it('retains identity rebind because it supplies both DID proof and the auth token', async () => {
+        await client.completeIdentityRecoveryRebind({
+            recoverySessionToken: 'rebind-session-token',
+            newAuthToken: SENTINEL_TOKEN,
+            providerType: 'firebase',
+            primaryDid: 'did:key:zTest',
+            authShare: { encryptedData: 'encrypted-share', encryptedDek: '', iv: '' },
+            didAuthVp: 'did-auth-vp',
+        });
+
+        const headers = calls[0]!.init?.headers as Record<string, string>;
+        expect(headers.Authorization).toBe('Bearer did-auth-vp');
+        expect(headers['X-Auth-Token']).toBe(SENTINEL_TOKEN);
+    });
+
+    it.each([
+        [
+            'storeAuthShare',
+            () =>
+                client.storeAuthShare({
+                    authShare: { encryptedData: 'share', encryptedDek: '', iv: '' },
+                    primaryDid: 'did:key:zTest',
+                }),
+        ],
+        ['addRecoveryMethod', () => client.addRecoveryMethod({ type: 'phrase' })],
+        ['markMigrated', () => client.markMigrated()],
+        ['activate', () => client.activate()],
+        ['sendEmailBackupShare', () => client.sendEmailBackupShare('email-share')],
+        ['addRecoveryEmail', () => client.addRecoveryEmail('recovery@example.com')],
+        ['verifyRecoveryEmail', () => client.verifyRecoveryEmail('123456')],
+        ['deleteUserKey', () => client.deleteUserKey()],
+    ])('%s fails closed instead of calling a route without DID proof', async (_name, call) => {
+        await expect(call()).rejects.toThrow(DID_CHALLENGE_ERROR);
+        expect(calls).toHaveLength(0);
+    });
+});