@learncard/types 5.22.0 → 5.23.1

package/dist/vc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vc.d.ts","sourceRoot":"","sources":["../src/vc.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"vc.d.ts","sourceRoot":"","sources":["../src/vc.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/types",
-    "version": "5.22.0",
+    "version": "5.23.1",
     "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

@@ -32,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.
@@ -260,6 +271,8 @@ export interface RecoveryResult {
 export interface IdentityRecoverySession {
     recoverySessionToken: string;
     recoveryMethods: RecoveryMethodInfo[];
+    /** The verified account's DID (same source as `ServerKeyStatus.primaryDid`). */
+    primaryDid: string | null;
 }
 
 // ---------------------------------------------------------------------------
@@ -269,7 +282,15 @@ export interface IdentityRecoverySession {
 export type SssActivationState = 'provisional' | 'active';
 
 /** Optional PIN enrollment requires rotating the existing escrow share. */
-export type EscrowEnrollmentOptions = { pin?: string };
+export type EscrowEnrollmentOptions = {
+    pin?: string;
+    /** P9.1 (attack C): required by the enclave for nitro/authority-mode
+     *  enroll/replace; bound into the sealed blob + signed intent, never read
+     *  or changed by lca-api. The authenticated account's email + the app's
+     *  current locale (one of the compiled template languages). */
+    recoveryEmail?: string;
+    recoveryLanguage?: string;
+};
 
 /** Stable error-message contract shared by PIN recovery clients and servers. */
 export const ESCROW_PIN_LOCKED_MESSAGE =
@@ -288,10 +309,21 @@ export const EscrowPinStatusValidator = z.object({
 });
 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';
+    state: 'enrolled' | 'not-enrolled' | 'opted-out' | 'disabled' | 'stale';
     escrowPin?: EscrowPinStatus;
+    /** Present only when `state === 'stale'`. */
+    staleReason?: EscrowBlobStaleReason;
 }
 
 /**
@@ -309,6 +341,7 @@ export interface ServerKeyStatus {
     maskedRecoveryEmail?: string | null;
     escrowOptedOut?: boolean;
     escrowPin?: EscrowPinStatus;
+    escrowStale?: EscrowBlobStaleReason;
     sssActivationState?: SssActivationState | null;
 }
 
@@ -362,6 +395,20 @@ export interface KeyDerivationCapabilities {
 // Key Derivation Strategy (generic)
 // ---------------------------------------------------------------------------
 
+/** Initiating-client bindings. Persist with the recovery secrets and never replace
+ * these with fields from a status response. Missing bindings require a new start. */
+export interface EscrowRecoveryExpectations {
+    tenant: string;
+    did: string;
+    holdId: string;
+    clientEphemeralPublicKey: string;
+    blobHash: string;
+    authorityGeneration: string;
+    holdDigest: string;
+    ledgerPublicKey: string;
+    keyId: string;
+}
+
 /**
  * Key Derivation Strategy
  *
@@ -527,18 +574,27 @@ export interface KeyDerivationStrategy<
         privateKey: string;
         signDidAuthVp: DidAuthVpSigner;
         pin: string;
+        /** P9.1: only `recoveryEmail`/`recoveryLanguage` apply here; `options.pin`
+         *  is ignored in favor of the required top-level `pin`. */
+        options?: EscrowEnrollmentOptions;
     }): Promise<void>;
 
-    /** Remove a PIN by rotating escrow material with an owner proof. */
+    /** Remove a PIN by rotating escrow material with an owner proof. In
+     * nitro/authority mode this is a `replace` enrollment action, which
+     * requires `options.recoveryEmail`/`recoveryLanguage`, same as
+     * `setEscrowPin`. */
     clearEscrowPin?(params: {
         token: string;
         providerType: AuthProviderType;
         privateKey: string;
         signDidAuthVp: DidAuthVpSigner;
+        options?: EscrowEnrollmentOptions;
     }): Promise<void>;
 
     /** Start an escrow hold. Securely persist the returned secrets; null means an existing hold. */
     startEscrowRecovery?(params: {
+        /** Account selected by the initiating client, required for Nitro recovery. */
+        expectedDid?: string;
         token?: string;
         providerType?: AuthProviderType;
         recoverySessionToken?: string;
@@ -553,15 +609,19 @@ export interface KeyDerivationStrategy<
         completedAt?: string;
         resumeToken: string | null;
         clientEphemeralPrivateKey: string;
+        /** Persist alongside the private key; pass unchanged on status, confirm and restore. */
+        expectations?: EscrowRecoveryExpectations;
         pinSalt?: string;
         /** Absent on legacy hold-only strategies. */
         releasePolicy?: 'hold' | 'pin';
+        /** Present only for an authority-mode hold-policy hold; see confirmEscrowRecovery. */
+        requiresConfirmation?: boolean;
     }>;
 
     /** Read a hold using its resume proof or the active device's provider session. */
     getEscrowRecoveryStatus?(
         params:
-            | { holdId: string; resumeToken: string }
+            | { holdId: string; resumeToken: string; expectations?: EscrowRecoveryExpectations }
             | { token: string; providerType: AuthProviderType }
     ): Promise<{
         holdId: string;
@@ -572,6 +632,9 @@ export interface KeyDerivationStrategy<
         releasePolicy?: 'hold' | 'pin';
         cancelledAt?: string;
         completedAt?: string;
+        /** Only present for an authority-mode hold-policy hold; `confirmed` only appears alongside it. */
+        requiresConfirmation?: boolean;
+        confirmed?: boolean;
     } | null>;
 
     /** Cancel a pending hold with a fresh, owner-signed DID challenge. */
@@ -582,6 +645,28 @@ export interface KeyDerivationStrategy<
         signDidAuthVp: DidAuthVpSigner;
     }): Promise<{ cancelled: boolean }>;
 
+    /**
+     * Submit the confirmation code the enclave emailed to the account's
+     * recovery address. Only meaningful when startEscrowRecovery returned
+     * `requiresConfirmation: true`; the resume proof (no DID session exists
+     * yet at this point in the flow) is the only credential.
+     */
+    confirmEscrowRecovery?(params: {
+        /** Retained initiating-client bindings, required in Nitro mode, including after reload. */
+        expectations?: EscrowRecoveryExpectations;
+        holdId: string;
+        resumeToken: string;
+        code: string;
+        tenantId?: string;
+    }): Promise<{ success: true }>;
+
+    /** Request a fresh confirmation code for a hold awaiting confirmation. */
+    resendEscrowRecoveryCode?(params: {
+        holdId: string;
+        resumeToken: string;
+        tenantId?: string;
+    }): Promise<{ success: true }>;
+
     /** Execute a recovery flow and return the recovered private key + DID */
     executeRecovery(params: {
         token: string;

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(),