@learncard/types 5.20.0 → 5.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/types",
-    "version": "5.20.0",
+    "version": "5.22.0",
     "description": "Shared types for learn card",
     "type": "module",
     "main": "./dist/index.cjs",

package/src/auth.ts

@@ -6,6 +6,8 @@
  * coupling consumers to any specific implementation.
  */
 
+import { z } from 'zod';
+
 // ---------------------------------------------------------------------------
 // Auth Session Error
 // ---------------------------------------------------------------------------
@@ -101,6 +103,24 @@ export interface PhoneVerificationHandle {
     _internal?: unknown;
 }
 
+/** Sign-in features available to the UI, independent of the provider name. */
+export interface SignInCapabilities {
+    readonly emailLink: boolean;
+    /** Email OTP is verified by the app's server, then exchanged via customToken. */
+    readonly emailOtp: boolean;
+    readonly phoneOtp: boolean;
+    readonly google: boolean;
+    readonly apple: boolean;
+    readonly social: boolean;
+    readonly customToken: boolean;
+    readonly deleteAccount: boolean;
+}
+
+export interface SocialSignInOptions {
+    /** Restore a session using the existing re-authentication interaction. */
+    intent?: 'signIn' | 'reauthenticate';
+}
+
 /**
  * Abstract sign-in adapter interface.
  *
@@ -118,6 +138,7 @@ export interface PhoneVerificationHandle {
  */
 export interface SignInAdapter {
     readonly providerType: AuthProviderType;
+    readonly capabilities: SignInCapabilities;
 
     // --- Auth state ---
 
@@ -140,6 +161,9 @@ export interface SignInAdapter {
 
     isEmailLink(link: string): boolean;
 
+    /** Authoritative provider check; isEmailLink remains a synchronous hint. */
+    validateEmailLink(link: string): Promise<boolean>;
+
     // --- Phone OTP ---
 
     /**
@@ -153,6 +177,17 @@ export interface SignInAdapter {
      */
     confirmPhoneOtp(handle: PhoneVerificationHandle, code: string | number): Promise<AuthUser>;
 
+    /** Preferred API: confirm the most recent request without exposing SDK state. */
+    confirmPhoneOtp(code: string | number): Promise<AuthUser>;
+
+    /** Fires when a code is ready for entry, on either platform. */
+    onPhoneCodeSent(callback: () => void): () => void;
+
+    /** Auto-retrieved code; call confirmPhoneOtp before starting key derivation. */
+    onPhoneVerificationCompleted(callback: (code: string | undefined) => void): () => void;
+
+    onPhoneVerificationFailed(callback: (error: unknown) => void): () => void;
+
     /**
      * Confirm a phone OTP using a native verificationId (Capacitor auto-verify
      * path).  Falls back to `confirmPhoneOtp` when not implemented.
@@ -161,9 +196,9 @@ export interface SignInAdapter {
 
     // --- OAuth ---
 
-    signInWithGoogle(): Promise<AuthUser>;
+    signInWithGoogle(options?: SocialSignInOptions): Promise<AuthUser>;
 
-    signInWithApple(): Promise<AuthUser>;
+    signInWithApple(options?: SocialSignInOptions): Promise<AuthUser>;
 
     /** Check for a pending OAuth redirect result (e.g. Apple on web). */
     checkRedirectResult?(): Promise<AuthUser | null>;
@@ -179,6 +214,15 @@ export interface SignInAdapter {
 
     deleteAccount(): Promise<void>;
 
+    /** Update the signed-in user's display profile, when supported. */
+    updateProfile?(profile: {
+        displayName?: string | null;
+        photoUrl?: string | null;
+    }): Promise<void>;
+
+    /** Limit the auth session to this browser tab on a public computer. */
+    setSessionPersistence?(sessionOnly: boolean): Promise<void>;
+
     signOut(): Promise<void>;
 
     // --- Cleanup ---
@@ -200,6 +244,8 @@ export interface RecoveryMethodInfo {
     type: string;
     createdAt: Date;
     credentialId?: string;
+    shareVersion?: number;
+    confirmedAt?: Date;
 }
 
 /**
@@ -211,10 +257,43 @@ export interface RecoveryResult {
     did: string;
 }
 
+export interface IdentityRecoverySession {
+    recoverySessionToken: string;
+    recoveryMethods: RecoveryMethodInfo[];
+}
+
 // ---------------------------------------------------------------------------
 // Server Key Status
 // ---------------------------------------------------------------------------
 
+export type SssActivationState = 'provisional' | 'active';
+
+/** Optional PIN enrollment requires rotating the existing escrow share. */
+export type EscrowEnrollmentOptions = { pin?: string };
+
+/** Stable error-message contract shared by PIN recovery clients and servers. */
+export const ESCROW_PIN_LOCKED_MESSAGE =
+    'Too many incorrect PIN attempts. You can still recover by waiting.';
+export const ESCROW_PIN_UNAVAILABLE_MESSAGE = 'PIN recovery is not available for this account.';
+export const ESCROW_PIN_MISMATCH_PATTERN = /^Incorrect PIN\. (\d+) attempts left\.$/;
+export const escrowPinMismatchMessage = (attemptsRemaining: number): string =>
+    `Incorrect PIN. ${attemptsRemaining} attempts left.`;
+
+/** Public PIN availability and remaining lifetime attempts; never includes the verifier. */
+export const EscrowPinStatusValidator = z.object({
+    state: z.enum(['none', 'enabled', 'locked', 'stale']),
+    enabled: z.boolean(),
+    attemptsRemaining: z.number().int().nonnegative(),
+    salt: z.string().optional(),
+});
+export type EscrowPinStatus = z.infer<typeof EscrowPinStatusValidator>;
+
+/** Enrollment details for PIN-aware strategies. Legacy strategies may still return a string. */
+export interface EscrowEnrollmentState {
+    state: 'enrolled' | 'not-enrolled' | 'opted-out' | 'disabled';
+    escrowPin?: EscrowPinStatus;
+}
+
 /**
  * Server key status returned by the strategy's fetchServerKeyStatus.
  * The strategy owns the server shape — different strategies may
@@ -228,8 +307,14 @@ export interface ServerKeyStatus {
     authShare: string | null;
     shareVersion: number | null;
     maskedRecoveryEmail?: string | null;
+    escrowOptedOut?: boolean;
+    escrowPin?: EscrowPinStatus;
+    sssActivationState?: SssActivationState | null;
 }
 
+/** Signs a DID-Auth VP. A supplied challenge must be embedded as the VP nonce. */
+export type DidAuthVpSigner = (privateKey: string, challenge?: string) => Promise<string>;
+
 // ---------------------------------------------------------------------------
 // Key Derivation Capabilities
 // ---------------------------------------------------------------------------
@@ -306,6 +391,7 @@ export interface KeyDerivationStrategy<
     TRecoveryInput = unknown,
     TRecoverySetupInput = unknown,
     TRecoverySetupResult = unknown,
+    TRecoveryConfirmationInput = unknown,
 > {
     readonly name: string;
 
@@ -323,8 +409,8 @@ export interface KeyDerivationStrategy<
     /** Store a local key component */
     storeLocalKey(key: string): Promise<void>;
 
-    /** Clear all local key data */
-    clearLocalKeys(): Promise<void>;
+    /** Clear local key data; automatic stale-key cleanup may retain unresolved writes. */
+    clearLocalKeys(options?: { preservePending?: boolean }): Promise<void>;
 
     /** Split a private key into shares/components */
     splitKey(privateKey: string): Promise<{ localKey: string; remoteKey: string }>;
@@ -340,19 +426,162 @@ export interface KeyDerivationStrategy<
         didFromPrivateKey: (pk: string) => Promise<string>
     ): Promise<boolean>;
 
+    /**
+     * Atomically split and persist a private key's local and remote components.
+     * Strategies that implement this use it for initial setup and rotations so
+     * callers never have to coordinate device/server writes themselves.
+     */
+    atomicUpdateShares?(params: {
+        token: string;
+        providerType: AuthProviderType;
+        privateKey: string;
+        did: string;
+        signDidAuthVp?: DidAuthVpSigner;
+    }): Promise<void>;
+
+    /**
+     * Repair local/server share-version skew after an ambiguous write. Returns
+     * the recovered key when reconciliation was needed, otherwise null.
+     */
+    reconcileShares?(params: {
+        token: string;
+        providerType: AuthProviderType;
+        expectedDid: string;
+        didFromPrivateKey: (privateKey: string) => Promise<string>;
+        signDidAuthVp?: DidAuthVpSigner;
+    }): Promise<RecoveryResult | null>;
+
+    /** Obtain a short-lived, single-use challenged DID-Auth VP for a write. */
+    getFreshDidAuthVp?(
+        privateKey: string,
+        did: string,
+        signDidAuthVp: DidAuthVpSigner
+    ): Promise<string>;
+
     // --- Server communication ---
 
     /** 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>;
+    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>;
 
+    /** Commit a provisioned key after the server verifies recovery enrollment. */
+    activate?(token: string, providerType: AuthProviderType, didAuthVp?: string): Promise<void>;
+
     // --- Recovery ---
 
+    /** Read the current automatic recovery enrollment status. */
+    getEscrowEnrollmentState?(params: {
+        token: string;
+        providerType: AuthProviderType;
+    }): Promise<EscrowEnrollmentState['state'] | EscrowEnrollmentState>;
+
+    /** Opt out with an owner proof; requires another confirmed recovery method. */
+    disableEscrowRecovery?(params: {
+        token: string;
+        providerType: AuthProviderType;
+        privateKey: string;
+        signDidAuthVp: DidAuthVpSigner;
+    }): Promise<void>;
+
+    /** Opt back in and enroll automatic recovery material. */
+    enableEscrowRecovery?(params: {
+        token: string;
+        providerType: AuthProviderType;
+        privateKey: string;
+        signDidAuthVp: DidAuthVpSigner;
+        options?: EscrowEnrollmentOptions;
+    }): Promise<
+        | { enrolled: false; reason: 'disabled' | 'opted-out' }
+        | { enrolled: true; changed: false }
+        | { enrolled: true; changed: true; shareVersion: number }
+    >;
+
+    /** Repair escrow enrollment, rotating shares only when no current confirmed enrollment exists. */
+    ensureEscrowEnrollment?(params: {
+        token: string;
+        providerType: AuthProviderType;
+        privateKey: string;
+        signDidAuthVp: DidAuthVpSigner;
+        options?: EscrowEnrollmentOptions;
+    }): Promise<
+        | { enrolled: false; reason: 'disabled' | 'opted-out' }
+        | { enrolled: true; changed: false }
+        | { enrolled: true; changed: true; shareVersion: number }
+    >;
+
+    /** Set or change a PIN by rotating escrow material with an owner proof. */
+    setEscrowPin?(params: {
+        token: string;
+        providerType: AuthProviderType;
+        privateKey: string;
+        signDidAuthVp: DidAuthVpSigner;
+        pin: string;
+    }): Promise<void>;
+
+    /** Remove a PIN by rotating escrow material with an owner proof. */
+    clearEscrowPin?(params: {
+        token: string;
+        providerType: AuthProviderType;
+        privateKey: string;
+        signDidAuthVp: DidAuthVpSigner;
+    }): Promise<void>;
+
+    /** Start an escrow hold. Securely persist the returned secrets; null means an existing hold. */
+    startEscrowRecovery?(params: {
+        token?: string;
+        providerType?: AuthProviderType;
+        recoverySessionToken?: string;
+        tenantId?: string;
+        options?: { releasePolicy?: 'hold' | 'pin'; restart?: boolean };
+    }): Promise<{
+        holdId: string;
+        status: 'pending' | 'cancelled' | 'completed' | 'expired';
+        requestedAt: string;
+        releaseAfter: string;
+        cancelledAt?: string;
+        completedAt?: string;
+        resumeToken: string | null;
+        clientEphemeralPrivateKey: string;
+        pinSalt?: string;
+        /** Absent on legacy hold-only strategies. */
+        releasePolicy?: 'hold' | 'pin';
+    }>;
+
+    /** Read a hold using its resume proof or the active device's provider session. */
+    getEscrowRecoveryStatus?(
+        params:
+            | { holdId: string; resumeToken: string }
+            | { token: string; providerType: AuthProviderType }
+    ): Promise<{
+        holdId: string;
+        status: 'pending' | 'cancelled' | 'completed' | 'expired';
+        requestedAt: string;
+        releaseAfter: string;
+        /** Absent on legacy hold-only strategies. */
+        releasePolicy?: 'hold' | 'pin';
+        cancelledAt?: string;
+        completedAt?: string;
+    } | null>;
+
+    /** Cancel a pending hold with a fresh, owner-signed DID challenge. */
+    cancelEscrowRecovery?(params: {
+        token: string;
+        providerType: AuthProviderType;
+        privateKey: string;
+        signDidAuthVp: DidAuthVpSigner;
+    }): Promise<{ cancelled: boolean }>;
+
     /** Execute a recovery flow and return the recovered private key + DID */
     executeRecovery(params: {
         token: string;
@@ -360,6 +589,8 @@ export interface KeyDerivationStrategy<
         input: TRecoveryInput;
         /** Optional: validate the reconstructed key's DID before rotating shares */
         didFromPrivateKey?: (privateKey: string) => Promise<string>;
+        /** Optional: sign the fresh challenge required to persist rotated shares */
+        signDidAuthVp?: DidAuthVpSigner;
     }): Promise<RecoveryResult>;
 
     /** Set up a new recovery method */
@@ -370,11 +601,51 @@ export interface KeyDerivationStrategy<
         input: TRecoverySetupInput;
         authUser?: AuthUser;
         /** Optional: sign a DID-Auth VP JWT for server write operations */
-        signDidAuthVp?: (privateKey: string) => Promise<string>;
+        signDidAuthVp?: DidAuthVpSigner;
     }): Promise<TRecoverySetupResult>;
 
+    /** Confirm a pending method after the strategy verifies proof of receipt locally. */
+    confirmRecoveryMethod?(params: {
+        token: string;
+        providerType: AuthProviderType;
+        privateKey: string;
+        input: TRecoveryConfirmationInput;
+        signDidAuthVp?: DidAuthVpSigner;
+    }): Promise<void>;
+
     /** Get configured recovery methods for the authenticated user */
-    getAvailableRecoveryMethods?(token: string, providerType: AuthProviderType): Promise<RecoveryMethodInfo[]>;
+    getAvailableRecoveryMethods?(
+        token: string,
+        providerType: AuthProviderType
+    ): Promise<RecoveryMethodInfo[]>;
+
+    // --- Lost login identity recovery ---
+
+    /** Send an OTP to the verified recovery email without requiring provider auth. */
+    startIdentityRecovery?(email: string): Promise<void>;
+
+    /** Verify the OTP and receive a one-use, recovery-scoped session. */
+    verifyIdentityRecovery?(email: string, code: string): Promise<IdentityRecoverySession>;
+
+    /** Reconstruct and hard-validate the key before the replacement login is bound. */
+    prepareIdentityRecovery?(params: {
+        recoverySessionToken: string;
+        input: TRecoveryInput;
+        didFromPrivateKey: (privateKey: string) => Promise<string>;
+    }): Promise<RecoveryResult>;
+
+    /** Whether reconstructed identity recovery is waiting for a replacement login. */
+    hasPendingIdentityRecovery?(): boolean;
+
+    /** Discard any reconstructed identity recovery that has not been rebound. */
+    cancelIdentityRecovery?(): void;
+
+    /** Bind the current provider identity and commit a full share rotation. */
+    completeIdentityRecovery?(params: {
+        token: string;
+        providerType: AuthProviderType;
+        signDidAuthVp?: DidAuthVpSigner;
+    }): Promise<RecoveryResult>;
 
     // --- Contact method management ---
 
@@ -416,7 +687,8 @@ export interface KeyDerivationStrategy<
         token: string,
         providerType: AuthProviderType,
         privateKey: string,
-        email: string
+        email: string,
+        didAuthVp?: string
     ): Promise<void>;
 
     // --- Share versioning ---

package/src/credential-refresh.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod/v4';
 
-import { UnsignedVCValidator, VCValidator } from './vc';
+import { CredentialStatusValidator, UnsignedVCValidator, VCValidator } from './vc';
 import { JWEValidator } from './crypto';
 
 /**
@@ -73,6 +73,40 @@ export type AllocateCredentialRefreshResult = z.infer<
     typeof AllocateCredentialRefreshResultValidator
 >;
 
+// --- Managed issuance receipt (returned to the issuer after a refreshable send) ---
+
+/**
+ * Issuance metadata returned to the authenticated issuer after a refreshable send
+ * (unified send with `refresh: true`, or `sendBoost` with `enableRefresh: true`).
+ *
+ * Populated from the actual signed version 1 credential — never from the template or
+ * allocation alone. This is issuance metadata only: it must not contain credential
+ * claims, subject bodies, plaintext VCs, or JWEs. The issuer retains its own
+ * template/claims alongside this receipt, and preserves the exact `credentialStatus`
+ * descriptor when publishing an update (no new allocation).
+ */
+export const ManagedCredentialRefreshReceiptValidator = z
+    .object({
+        refreshId: z.string().min(1),
+        refreshService: ManagedCredentialRefreshServiceValidator,
+        credentialId: z.string().min(1),
+        issuerDid: z.string().min(1),
+        holderDid: z.string().min(1),
+        credentialStatus: CredentialStatusValidator.or(
+            CredentialStatusValidator.array()
+        ).optional(),
+    })
+    .strip();
+export type ManagedCredentialRefreshReceipt = z.infer<
+    typeof ManagedCredentialRefreshReceiptValidator
+>;
+
+/** Allocation metadata for deferred Inbox issuance. No holder is invented before claim. */
+export const InboxCredentialRefreshReceiptValidator = ManagedCredentialRefreshReceiptValidator.omit(
+    { holderDid: true }
+).extend({ holderDid: z.string().min(1).optional() });
+export type InboxCredentialRefreshReceipt = z.infer<typeof InboxCredentialRefreshReceiptValidator>;
+
 // --- Publication ------------------------------------------------------------
 
 export const CredentialRefreshSigningModeValidator = z.enum(['issuer-signed', 'signing-authority']);

package/src/index.ts

@@ -17,3 +17,4 @@ export * from './auth';
 export * from './bitstring-status-list';
 export * from './inAppMessages';
 export * from './credential-refresh';
+export * from './share-links';