@learncard/types 5.23.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.23.0",
+    "version": "5.23.1",
     "description": "Shared types for learn card",
     "type": "module",
     "main": "./dist/index.cjs",

package/src/auth.ts

@@ -271,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;
 }
 
 // ---------------------------------------------------------------------------
@@ -280,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 =
@@ -385,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
  *
@@ -550,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;
@@ -576,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;
@@ -595,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. */
@@ -605,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/vc.test.ts

@@ -1,17 +1,24 @@
 import { expect, test } from 'vitest';
 import { ProofValidator } from './vc';
 
-test('only final ecdsa-rdfc-2019 DataIntegrityProofs may omit created', () => {
+test.each([
+    'ecdsa-rdfc-2019',
+    'ecdsa-jcs-2019',
+    'ecdsa-sd-2023',
+    'eddsa-rdfc-2022',
+    'eddsa-jcs-2022',
+    'bbs-2023',
+])('final %s DataIntegrityProofs may omit created', cryptosuite => {
     const proof = {
         type: 'DataIntegrityProof',
-        cryptosuite: 'ecdsa-rdfc-2019',
+        cryptosuite,
         proofPurpose: 'authentication',
         verificationMethod: 'did:example:holder#key',
         proofValue: 'zSignature',
     };
 
     expect(ProofValidator.parse(proof)).toEqual(proof);
-    const legacy = { ...proof, cryptosuite: 'eddsa-rdfc-2022' };
+    const legacy = { ...proof, cryptosuite: 'unknown-suite' };
     expect(ProofValidator.safeParse(legacy).success).toBe(false);
     expect(ProofValidator.safeParse({ ...legacy, created: '2026-01-01T00:00:00Z' }).success).toBe(
         true

package/src/vc.ts

@@ -200,7 +200,19 @@ export const ProofValidator = z
     .superRefine((proof, ctx) => {
         if (
             proof.created === undefined &&
-            (proof.type !== 'DataIntegrityProof' || proof.cryptosuite !== 'ecdsa-rdfc-2019')
+            // These standardized Data Integrity suites make created optional.
+            // Keep the prior requirement for legacy and unknown proof suites.
+            // https://www.w3.org/TR/vc-di-eddsa/#proof-configuration-eddsa-jcs-2022
+            // https://www.w3.org/TR/vc-di-bbs/#proof-configuration
+            (proof.type !== 'DataIntegrityProof' ||
+                ![
+                    'ecdsa-rdfc-2019',
+                    'ecdsa-jcs-2019',
+                    'ecdsa-sd-2023',
+                    'eddsa-rdfc-2022',
+                    'eddsa-jcs-2022',
+                    'bbs-2023',
+                ].includes(proof.cryptosuite as string))
         ) {
             ctx.addIssue({
                 code: 'custom',