@learncard/types 5.21.0 → 5.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/types",
-    "version": "5.21.0",
+    "version": "5.23.0",
     "description": "Shared types for learn card",
     "type": "module",
     "main": "./dist/index.cjs",
@@ -25,6 +25,7 @@
     "scripts": {
         "build": "node ./scripts/build.mjs && shx cp ./scripts/mixedEntypoint.js ./dist/index.cjs && tsc --p tsconfig.json && shx cp ./dist/index.d.ts ./dist/index.d.cts",
         "typecheck": "tsc --noEmit -p tsconfig.json",
+        "test": "vitest run",
         "start": "aqu watch"
     },
     "author": "Learning Economy Foundation (www.learningeconomy.io)",

package/src/__tests__/unsupportedSignInOperation.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+import { UnsupportedSignInOperationError } from '../auth';
+
+describe('UnsupportedSignInOperationError', () => {
+    it('preserves the operation and provider for callers', () => {
+        const error = new UnsupportedSignInOperationError('sendPhoneOtp', 'keycloak');
+        expect(error).toBeInstanceOf(Error);
+        expect(error.name).toBe('UnsupportedSignInOperationError');
+        expect(error.operation).toBe('sendPhoneOtp');
+        expect(error.providerType).toBe('keycloak');
+        expect(error.message).toContain('sendPhoneOtp');
+    });
+});

package/src/auth.ts

@@ -6,6 +6,8 @@
  * coupling consumers to any specific implementation.
  */
 
+import { z } from 'zod';
+
 // ---------------------------------------------------------------------------
 // Auth Session Error
 // ---------------------------------------------------------------------------
@@ -30,6 +32,17 @@ export class AuthSessionError extends Error {
 // Auth Provider
 // ---------------------------------------------------------------------------
 
+/** An action that the selected sign-in provider does not support. */
+export class UnsupportedSignInOperationError extends Error {
+    constructor(
+        public readonly operation: string,
+        public readonly providerType: string
+    ) {
+        super(`${operation} is not supported by ${providerType}`);
+        this.name = 'UnsupportedSignInOperationError';
+    }
+}
+
 /**
  * Auth provider identifier. Known values: 'firebase', 'supertokens', 'keycloak', 'oidc'.
  * Use any string to support custom auth providers without modifying this type.
@@ -242,6 +255,8 @@ export interface RecoveryMethodInfo {
     type: string;
     createdAt: Date;
     credentialId?: string;
+    shareVersion?: number;
+    confirmedAt?: Date;
 }
 
 /**
@@ -253,10 +268,54 @@ 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>;
+
+/**
+ * Reason a stored escrow blob no longer matches the server's active enclave:
+ * `mode-mismatch` — blob was sealed for `software`/`nitro` but the server now
+ * runs the other backend (e.g. the P6 software→Nitro migration, or a rollback);
+ * `key-rotated` — blob's `enclaveKeyId` no longer matches the active
+ * attestation's key (e.g. a PCR/measurement rotation).
+ */
+export type EscrowBlobStaleReason = 'mode-mismatch' | 'key-rotated';
+
+/** Enrollment details for PIN-aware strategies. Legacy strategies may still return a string. */
+export interface EscrowEnrollmentState {
+    state: 'enrolled' | 'not-enrolled' | 'opted-out' | 'disabled' | 'stale';
+    escrowPin?: EscrowPinStatus;
+    /** Present only when `state === 'stale'`. */
+    staleReason?: EscrowBlobStaleReason;
+}
+
 /**
  * Server key status returned by the strategy's fetchServerKeyStatus.
  * The strategy owns the server shape — different strategies may
@@ -270,8 +329,15 @@ export interface ServerKeyStatus {
     authShare: string | null;
     shareVersion: number | null;
     maskedRecoveryEmail?: string | null;
+    escrowOptedOut?: boolean;
+    escrowPin?: EscrowPinStatus;
+    escrowStale?: EscrowBlobStaleReason;
+    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
 // ---------------------------------------------------------------------------
@@ -348,6 +414,7 @@ export interface KeyDerivationStrategy<
     TRecoveryInput = unknown,
     TRecoverySetupInput = unknown,
     TRecoverySetupResult = unknown,
+    TRecoveryConfirmationInput = unknown,
 > {
     readonly name: string;
 
@@ -365,8 +432,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 }>;
@@ -382,6 +449,38 @@ 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 */
@@ -399,8 +498,113 @@ export interface KeyDerivationStrategy<
     /** 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;
@@ -408,6 +612,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 */
@@ -418,15 +624,52 @@ 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[]>;
 
+    // --- 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 ---
 
     /**
@@ -467,7 +710,8 @@ export interface KeyDerivationStrategy<
         token: string,
         providerType: AuthProviderType,
         privateKey: string,
-        email: string
+        email: string,
+        didAuthVp?: string
     ): Promise<void>;
 
     // --- Share versioning ---

package/src/clr.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+import {
+    AssociationValidator,
+    ClrCredentialValidator,
+    ClrSubjectValidator,
+    UnsignedClrCredentialValidator,
+    type Association,
+} from './clr';
+
+const association = {
+    type: 'Association' as const,
+    associationType: 'isPartOf',
+    sourceId: 'https://example.org/achievements/course',
+    targetId: 'https://example.org/achievements/program',
+};
+
+const supportedTypeNames = [
+    'Association',
+    'https://purl.imsglobal.org/spec/vc/clr/vocab.html#Association',
+    'https://example.org/ExtendedAssociation',
+    'CustomAssociation',
+];
+
+const subject = {
+    id: 'did:example:learner',
+    type: ['ClrSubject'],
+    association: [association],
+};
+
+const unsignedClr = {
+    '@context': [
+        'https://www.w3.org/ns/credentials/v2',
+        'https://purl.imsglobal.org/spec/clr/v2p0/context.json',
+        'https://purl.imsglobal.org/spec/ob/v3p0/context.json',
+    ],
+    id: 'https://example.org/credentials/clr',
+    type: ['VerifiableCredential', 'ClrCredential'],
+    issuer: { id: 'did:example:issuer', type: ['Profile'], name: 'Example University' },
+    validFrom: '2026-01-01T00:00:00Z',
+    credentialSubject: subject,
+};
+
+const proof = {
+    type: 'DataIntegrityProof',
+    cryptosuite: 'eddsa-rdfc-2022',
+    created: '2026-01-01T00:00:00Z',
+    proofPurpose: 'assertionMethod',
+    verificationMethod: 'did:example:issuer#key',
+    proofValue: 'zExampleSignature',
+};
+
+describe('CLR Association.type', () => {
+    it('accepts the canonical scalar without changing it or extension fields', () => {
+        // CLR 2.0 $defs.Association.properties.type requires the scalar "Association".
+        // https://purl.imsglobal.org/spec/clr/v2p0/schema/json/clr_v2p0_clrcredential_schema.json
+        const input = { ...association, 'ext:description': 'Course belongs to program' };
+
+        expect(AssociationValidator.parse(input)).toEqual(input);
+    });
+
+    it.each(supportedTypeNames)(
+        'preserves scalar and singleton-array type values through full CLR parsing: %s',
+        typeName => {
+            for (const type of [typeName, [typeName]]) {
+                const input = { ...association, type };
+                const credential = {
+                    ...unsignedClr,
+                    credentialSubject: { ...subject, association: [input] },
+                };
+
+                // This SDK validator checks structure; the official CLR schema is stricter.
+                expect(AssociationValidator.parse(input)).toEqual(input);
+                expect(UnsignedClrCredentialValidator.parse(credential)).toEqual(credential);
+                expect(ClrCredentialValidator.parse({ ...credential, proof })).toEqual({
+                    ...credential,
+                    proof,
+                });
+            }
+        }
+    );
+
+    it.each(
+        [
+            ['Association'],
+            ['Association', 'https://example.org/ExtendedAssociation'],
+            ['https://example.org/LegacyAssociation'],
+            [''], // Existing arrays accept every string; preserve that contract.
+        ].map(type => ({ type }))
+    )('preserves supported legacy arrays: $type', ({ type }) => {
+        const input = { ...association, type };
+
+        expect(AssociationValidator.parse(input)).toEqual(input);
+    });
+
+    it.each(
+        [undefined, null, false, 42, '', {}, [], ['Association', 42], [['Association']]].map(
+            type => ({ type })
+        )
+    )('rejects invalid values: $type', ({ type }) => {
+        expect(AssociationValidator.safeParse({ ...association, type }).success).toBe(false);
+    });
+
+    it('exposes scalar and legacy array types to callers', () => {
+        expectTypeOf<Association['type']>().toEqualTypeOf<string | string[]>();
+    });
+});
+
+describe('CLR credentials with associations', () => {
+    it('parses a subject containing both canonical and legacy associations', () => {
+        const input = {
+            ...subject,
+            association: [association, { ...association, type: ['Association'] }],
+        };
+
+        expect(ClrSubjectValidator.parse(input)).toEqual(input);
+    });
+
+    it.each([false, true])('parses unsigned and signed CLR subject arrays: %s', subjectArray => {
+        const input = {
+            ...unsignedClr,
+            credentialSubject: subjectArray ? [subject] : subject,
+        };
+
+        expect(UnsignedClrCredentialValidator.parse(input)).toEqual(input);
+        expect(ClrCredentialValidator.parse({ ...input, proof })).toEqual({ ...input, proof });
+    });
+
+    it('preserves nested CLR content and validates its associations when parsed directly', () => {
+        const nested = {
+            ...unsignedClr,
+            id: 'https://example.org/credentials/nested-clr',
+            credentialSubject: {
+                ...subject,
+                association: [{ ...association, type: supportedTypeNames[1] }],
+            },
+            proof,
+        };
+        const input = {
+            ...unsignedClr,
+            credentialSubject: { ...subject, verifiableCredential: [nested] },
+            proof,
+        };
+
+        expect(ClrCredentialValidator.parse(input)).toEqual(input);
+        // Embedded verifiableCredential values are intentionally opaque in ClrSubjectValidator.
+        expect(ClrCredentialValidator.parse(nested)).toEqual(nested);
+    });
+
+    it.each([[], '', ['Association', null]].map(type => ({ type })))(
+        'rejects invalid associations through full CLR parsing: $type',
+        ({ type }) => {
+            const invalidSubject = { ...subject, association: [{ ...association, type }] };
+
+            for (const credentialSubject of [invalidSubject, [invalidSubject]]) {
+                const input = { ...unsignedClr, credentialSubject };
+
+                expect(UnsignedClrCredentialValidator.safeParse(input).success).toBe(false);
+                expect(ClrCredentialValidator.safeParse({ ...input, proof }).success).toBe(false);
+            }
+        }
+    );
+});

package/src/clr.ts

@@ -27,7 +27,8 @@ export type AssociationType = z.infer<typeof AssociationTypeValidator>;
 
 export const AssociationValidator = z
     .object({
-        type: z.string().array().nonempty(),
+        // Accept compacted scalars while retaining the existing permissive array contract.
+        type: z.string().min(1).or(z.string().array().nonempty()),
         associationType: AssociationTypeValidator,
         sourceId: z.string().optional(),
         targetId: z.string(),

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';