@learncard/lca-api-service 1.6.0 → 1.6.2

package/dist/routes/escrow.d.ts

@@ -113,6 +113,10 @@ export declare const escrowRouter: import("@trpc/server").TRPCBuiltRouter<{
                 iv: string;
                 ciphertext: string;
             } | null | undefined;
+            expectedPinCharges?: {
+                attemptsRemaining: number;
+                wrongAttempts: number;
+            } | undefined;
         };
         output: {
             success: true;

package/dist/routes/keys.d.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
+import { type Context } from '@routes';
 import { AuthProviderType } from '@helpers/auth.helpers';
+import { type RecoverySessionRecord } from '@cache/recoverySessions';
 import { type ContactMethod, type AuthProviderMapping, type MongoUserKeyType } from '@models';
 export declare const AuthProviderTypeValidator: z.ZodEnum<{
     firebase: "firebase";
@@ -32,9 +34,16 @@ export declare function verifyAndGetContactMethod(input: {
 }>;
 export declare const requireUserKey: (authProvider: AuthProviderMapping, message?: string) => Promise<MongoUserKeyType>;
 export declare const assertDidOwner: (userKey: MongoUserKeyType, authenticatedDid: string) => void;
+export declare const requireRecoverySessionRecord: (token: string, scope: "recover" | "rebind") => Promise<RecoverySessionRecord & {
+    authProvider: AuthProviderMapping;
+}>;
 export declare const requireRecoverySession: (token: string, scope: "recover" | "rebind") => Promise<AuthProviderMapping>;
+export declare const getRecoverySessionEpoch: (session: Pick<RecoverySessionRecord, "securityEpoch">) => number;
+export declare const STALE_RECOVERY_SESSION_MESSAGE = "Your account security changed during recovery. Start again.";
+export declare const assertRecoverySessionEpoch: (session: Pick<RecoverySessionRecord, "securityEpoch">, userKey: MongoUserKeyType) => void;
+export declare const ACCOUNT_SECURED_NOTICE_TIMEOUT_MS = 3000;
 export declare const keysRouter: import("@trpc/server").TRPCBuiltRouter<{
-    ctx: import("@routes").Context;
+    ctx: Context;
     meta: import("trpc-to-openapi").OpenApiMeta;
     errorShape: import("@trpc/server").TRPCDefaultErrorShape;
     transformer: false;
@@ -65,6 +74,7 @@ export declare const keysRouter: import("@trpc/server").TRPCBuiltRouter<{
                 state: "enabled" | "none" | "locked" | "stale";
                 enabled: boolean;
                 attemptsRemaining: number;
+                wrongAttempts?: number | undefined;
                 salt?: string | undefined;
             };
             primaryDid: string | null;
@@ -113,6 +123,39 @@ export declare const keysRouter: import("@trpc/server").TRPCBuiltRouter<{
         };
         meta: import("trpc-to-openapi").OpenApiMeta;
     }>;
+    completePinSignIn: import("@trpc/server").TRPCMutationProcedure<{
+        input: {
+            recoverySessionToken: string;
+            providerType: "firebase" | "supertokens" | "keycloak" | "oidc";
+            primaryDid: string;
+            newAuthToken?: string | undefined;
+        };
+        output: {
+            success: true;
+            shareVersion: number;
+            linked: boolean;
+        };
+        meta: import("trpc-to-openapi").OpenApiMeta;
+    }>;
+    revokeOtherDevices: import("@trpc/server").TRPCMutationProcedure<{
+        input: {
+            providerType: "firebase" | "supertokens" | "keycloak" | "oidc";
+            primaryDid: string;
+            authShare: {
+                encryptedData: string;
+                encryptedDek: string;
+                iv: string;
+            };
+            expectedShareVersion: number;
+            authToken?: string | undefined;
+        };
+        output: {
+            success: true;
+            shareVersion: number;
+            recoveryMethodsRequireConfirmation: ("email" | "passkey" | "backup" | "phrase" | "escrow")[];
+        };
+        meta: import("trpc-to-openapi").OpenApiMeta;
+    }>;
     issueDidChallenge: import("@trpc/server").TRPCMutationProcedure<{
         input: {
             did: string;
@@ -151,11 +194,14 @@ export declare const keysRouter: import("@trpc/server").TRPCBuiltRouter<{
                 state: "enabled" | "none" | "locked" | "stale";
                 enabled: boolean;
                 attemptsRemaining: number;
+                wrongAttempts?: number | undefined;
                 salt?: string | undefined;
             };
             priorEscrowEnrollment: boolean;
             sssActivationState: "active" | "provisional";
             escrowStale?: "mode-mismatch" | "key-rotated" | undefined;
+            escrowBlobIdentity?: string | undefined;
+            escrowUpdating?: boolean | undefined;
         } | null;
         meta: import("trpc-to-openapi").OpenApiMeta;
     }>;

package/dist/services/escrow-enclave/enrollmentLease.d.ts

@@ -0,0 +1,8 @@
+import { type AuthProviderMapping, type EscrowEnrollmentLease } from '@models';
+import type { AuthorityMutationResult, AuthorityStateResponse } from './authorityContract';
+export declare const isDefiniteAuthorityRefusal: (error: unknown) => boolean;
+export declare const isLeaseCommitted: (lease: EscrowEnrollmentLease, { state }: AuthorityStateResponse, received?: AuthorityMutationResult) => boolean;
+export declare const settleEscrowEnrollmentLease: (authProvider: AuthProviderMapping, primaryDid: string, lease: EscrowEnrollmentLease, { received, releaseIfUncommitted, }: {
+    received?: AuthorityMutationResult;
+    releaseIfUncommitted: boolean;
+}) => Promise<"adopted" | "released" | "kept">;

package/dist/services/escrow-enclave/notifications.d.ts

@@ -1,7 +1,7 @@
 import type { ResolvedTenant } from '@learncard/email-templates';
 import type { EscrowHold, MongoUserKeyType } from '@models';
 import { type DeliveryService } from '../delivery';
-export type EscrowHoldEventKind = 'started' | 'reminder' | 'completed' | 'cancelled' | 'pin-locked';
+export type EscrowHoldEventKind = 'started' | 'reminder' | 'completed' | 'cancelled' | 'pin-locked' | 'pin-sign-in';
 export interface EscrowHoldEvent {
     kind: EscrowHoldEventKind;
     hold: EscrowHold;

package/package.json

@@ -1,11 +1,11 @@
 {
     "name": "@learncard/lca-api-service",
-    "version": "1.6.0",
+    "version": "1.6.2",
     "description": "",
     "engines": {
         "node": ">=24.12 <25"
     },
-    "packageManager": "bun@1.4.2",
+    "packageManager": "bun@1.4.4",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "scripts": {
@@ -66,15 +66,15 @@
         "@fastify/formbody": "^8.0.2",
         "@fastify/rate-limit": "^10.2.0",
         "@fastify/static": "^10.1.1",
-        "@learncard/core": "9.4.41",
-        "@learncard/did-web-plugin": "1.1.41",
-        "@learncard/didkit-plugin": "1.10.6",
-        "@learncard/didkit-plugin-node": "0.3.6",
-        "@learncard/email-templates": "1.2.1",
-        "@learncard/helpers": "1.7.1",
-        "@learncard/init": "2.5.6",
-        "@learncard/types": "5.24.0",
-        "@learncard/sss-key-manager": "0.2.4",
+        "@learncard/core": "9.4.42",
+        "@learncard/did-web-plugin": "1.1.42",
+        "@learncard/didkit-plugin": "1.10.8",
+        "@learncard/didkit-plugin-node": "0.3.8",
+        "@learncard/email-templates": "1.2.2",
+        "@learncard/helpers": "1.7.2",
+        "@learncard/init": "2.5.8",
+        "@learncard/types": "5.24.1",
+        "@learncard/sss-key-manager": "0.2.6",
         "@sentry/serverless": "^7.61.0",
         "@trpc/server": "11.8.0",
         "@types/jsonwebtoken": "^9.0.8",

package/project.json

@@ -59,7 +59,7 @@
         },
         "test": {
             "executor": "nx:run-script",
-            "inputs": ["source", "tests"],
+            "inputs": ["source", "tests", "ciTestConfig"],
             "options": {
                 "script": "test"
             }

package/src/cache/recoverySessions.ts

@@ -13,6 +13,22 @@ export type RecoverySessionScope = 'recover' | 'rebind';
 export interface RecoverySessionRecord {
     scope: RecoverySessionScope;
     authProvider: { type: AuthProviderType; id: string };
+    /**
+     * Set only by `/keys/escrow/complete` after a successful PIN release. Keep-mode
+     * PIN sign-in (`/keys/recovery-session/pin-sign-in`) requires it, so tokens from
+     * the waiting-period hold or from `useRecoverySession` can never skip the rotation.
+     */
+    origin?: 'pin-release';
+    /** Account DID and share version the PIN release unlocked (server-side, never client input). */
+    primaryDid?: string;
+    shareVersion?: number;
+    /**
+     * The account's security epoch when the token (or the recovery session it came
+     * from) was minted. `/rebind` and `/pin-sign-in` only write while the account is
+     * still at this epoch, so a revoke or wiping rebind retires every older token.
+     * Read as 0 when absent (tokens minted before the field existed).
+     */
+    securityEpoch?: number;
 }
 
 export interface RecoveryOtpRecord {
@@ -56,6 +72,28 @@ export const createRecoverySession = async (
     return token;
 };
 
+/**
+ * Read a recovery token without consuming it, so a route can reject a token meant for
+ * another route without burning it. Always follow with `consumeRecoverySession`.
+ */
+export const peekRecoverySession = async (
+    token: string,
+    expectedScope: RecoverySessionScope
+): Promise<RecoverySessionRecord | null> => {
+    const redis = cache.redis ?? cache.node;
+    const raw = await redis.get(getRecoverySessionCacheKey(token));
+
+    if (!raw) return null;
+
+    try {
+        const record = JSON.parse(raw) as RecoverySessionRecord;
+
+        return record.scope === expectedScope ? record : null;
+    } catch {
+        return null;
+    }
+};
+
 /** Atomically consume a recovery token. Every token authorizes exactly one route call. */
 export const consumeRecoverySession = async (
     token: string,

package/src/helpers/accountSecureLink.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+
+import { buildAccountSecureUrl } from './accountSecureLink';
+
+describe('buildAccountSecureUrl', () => {
+    it('builds the secure-account path on the tenant app URL', () => {
+        expect(buildAccountSecureUrl({ baseUrl: 'https://learncard.app' })).toBe(
+            'https://learncard.app/account/secure'
+        );
+        expect(buildAccountSecureUrl({ baseUrl: 'https://vetpass.app' })).toBe(
+            'https://vetpass.app/account/secure'
+        );
+    });
+
+    it('never doubles the slash when baseUrl has a trailing slash', () => {
+        expect(buildAccountSecureUrl({ baseUrl: 'https://learncard.app/' })).toBe(
+            'https://learncard.app/account/secure'
+        );
+    });
+
+    it('carries no query string (no token in the link)', () => {
+        expect(new URL(buildAccountSecureUrl({ baseUrl: 'https://learncard.app' })).search).toBe(
+            ''
+        );
+    });
+});

package/src/helpers/accountSecureLink.ts

@@ -0,0 +1,16 @@
+/**
+ * "Secure my account" deep-link builder for the PIN sign-in notice.
+ *
+ * Same tenant-branded base URL as the escrow cancel link (`escrowCancelLink.ts`):
+ * the resolved `TenantBranding.appUrl`, falling back to LearnCard. The link
+ * carries no token. Under PIN sign-in the owner's other devices stay signed in,
+ * and the secure action itself needs a signed-in wallet (DID auth + fresh
+ * challenge), so the URL only has to open the right screen.
+ */
+
+/** Path the app routes to its "Secure my account" flow. */
+export const ACCOUNT_SECURE_PATH = '/account/secure';
+
+/** `URL` rather than concatenation so a trailing slash on `baseUrl` never doubles. */
+export const buildAccountSecureUrl = ({ baseUrl }: { baseUrl: string }): string =>
+    new URL(ACCOUNT_SECURE_PATH, baseUrl).toString();

package/src/jobs/escrowBlobRewrap.ts

@@ -1,7 +1,13 @@
 import {
+    claimEscrowEnrollmentLease,
+    commitEscrowEnrollmentLease,
     findPendingEscrowHoldByAuthProvider,
+    findUserKeyByAuthProvider,
     findUserKeysWithEscrowBlobKeyId,
+    releaseEscrowEnrollmentLease,
     rewrapEscrowBlobByAuthProvider,
+    ESCROW_ENROLLMENT_LEASE_TTL_MS,
+    type EscrowEnrollmentLease,
 } from '@models';
 import {
     getEnclaveAttestationIdentity,
@@ -9,8 +15,13 @@ import {
     isEscrowEnabled,
     isEscrowRemoteMode,
 } from '../services/escrow-enclave';
-import { randomBytes } from 'crypto';
+import { randomBytes, randomUUID } from 'crypto';
 import { EscrowUnavailableError } from '../services/escrow-enclave/types';
+import type { AuthorityMutationResult } from '../services/escrow-enclave/authorityContract';
+import {
+    isDefiniteAuthorityRefusal,
+    settleEscrowEnrollmentLease,
+} from '../services/escrow-enclave/enrollmentLease';
 
 const DEFAULT_REWRAP_BATCH_LIMIT = 200;
 
@@ -82,8 +93,9 @@ export const runEscrowBlobRewrap = async (
     let skippedPendingHold = 0;
     let failed = 0;
 
-    for (const userKey of candidates) {
-        const blob = userKey.escrowBlob;
+    for (const candidate of candidates) {
+        let userKey = candidate;
+        let blob = userKey.escrowBlob;
         const authProvider = userKey.authProviders[0];
         // Already migrated (by this loop's own attestation refresh landing
         // mid-batch, or a concurrent run) since the candidate query ran.
@@ -95,6 +107,27 @@ export const runEscrowBlobRewrap = async (
             }
             const enclave = getEscrowEnclave();
             if (isEscrowRemoteMode()) {
+                // A PIN operation (or an earlier run) left a lease behind: settle it
+                // against the authority first, then work from the converged copy.
+                const stuck = userKey.escrowEnrollmentLease;
+                if (stuck && stuck.expiresAt <= new Date()) {
+                    await settleEscrowEnrollmentLease(authProvider, userKey.primaryDid, stuck, {
+                        releaseIfUncommitted: true,
+                    });
+                    const settled = await findUserKeyByAuthProvider(
+                        authProvider.type,
+                        authProvider.id
+                    );
+                    if (
+                        !settled?.escrowBlob ||
+                        settled.escrowBlob.enclaveKeyId === attestation.keyId
+                    )
+                        continue;
+                    userKey = settled;
+                    blob = settled.escrowBlob;
+                }
+                // A live lease: its operation replaces this blob. Re-tried on a later run.
+                if (userKey.escrowEnrollmentLease) continue;
                 if (!enclave.getEnrollmentState || !blob.authorityGeneration)
                     throw new EscrowUnavailableError();
                 const snapshot = await enclave.getEnrollmentState({
@@ -131,6 +164,65 @@ export const runEscrowBlobRewrap = async (
                     if (stored) rewrapped += 1;
                     continue;
                 }
+                // The authority call itself runs under the account's PIN-operation
+                // lease, like an owner's intent: otherwise a lease claimed between this
+                // commit and its Mongo write would leave the authority re-sealed and
+                // Mongo on the old copy.
+                const lease: EscrowEnrollmentLease = {
+                    id: randomUUID(),
+                    expiresAt: new Date(Date.now() + ESCROW_ENROLLMENT_LEASE_TTL_MS),
+                    action: 'rewrap',
+                    pinAction: 'keep',
+                    pin: 'keep',
+                    shareVersion: blob.shareVersion,
+                    authorityGeneration: current.authorityGeneration,
+                    expectedEnrollmentVersion: current.enrollmentVersion,
+                    expectedPinGeneration: current.pinGeneration,
+                    enrollmentEpoch: blob.enrollmentEpoch,
+                    sourceBlobHash: blob.blobHash,
+                    measurements: attestation.measurements,
+                };
+                const claimed = await claimEscrowEnrollmentLease(authProvider, {
+                    lease,
+                    expectedBlob: blob,
+                    expectedPin: userKey.escrowPin,
+                    requireOptedIn: true,
+                });
+                // Changed since read, a compare in flight, or another lease: next run.
+                if (!claimed) continue;
+                let authority: AuthorityMutationResult | undefined;
+                try {
+                    ({ authority } = await enclave.rewrapEscrowBlob({
+                        envelope: blob.envelope,
+                        expectedDid: userKey.primaryDid,
+                        expectedShareVersion: blob.shareVersion,
+                        sourceEnrollmentEpoch: blob.enrollmentEpoch,
+                    }));
+                    if (!authority?.envelope) throw new EscrowUnavailableError('invalid_response');
+                } catch (error) {
+                    if (isDefiniteAuthorityRefusal(error))
+                        await releaseEscrowEnrollmentLease(authProvider, lease.id);
+                    else
+                        await settleEscrowEnrollmentLease(authProvider, userKey.primaryDid, lease, {
+                            releaseIfUncommitted: false,
+                        }).catch(() => undefined);
+                    throw error;
+                }
+                const committed = await commitEscrowEnrollmentLease(authProvider, lease, {
+                    envelope: authority.envelope,
+                    authorityGeneration: authority.authorityGeneration,
+                    enrollmentVersion: authority.enrollmentVersion,
+                    enrollmentEpoch: authority.enrollmentEpoch,
+                    receipt: authority.receipt,
+                }).catch(() => null);
+                const settled = committed
+                    ? 'adopted'
+                    : await settleEscrowEnrollmentLease(authProvider, userKey.primaryDid, lease, {
+                          received: authority,
+                          releaseIfUncommitted: false,
+                      });
+                if (settled === 'adopted') rewrapped += 1;
+                continue;
             }
             const { envelope, authority } = await enclave.rewrapEscrowBlob({
                 envelope: blob.envelope,

package/src/models/EscrowHold.ts

@@ -123,7 +123,14 @@ export const EscrowHoldValidator = z.object({
     notifications: z
         .array(
             z.object({
-                kind: z.enum(['started', 'reminder', 'completed', 'cancelled', 'pin-locked']),
+                kind: z.enum([
+                    'started',
+                    'reminder',
+                    'completed',
+                    'cancelled',
+                    'pin-locked',
+                    'pin-sign-in',
+                ]),
                 sentAt: z.date(),
             })
         )
@@ -282,7 +289,8 @@ export const findEscrowHoldsPendingEnclaveCancellation = async (
             enclaveCancelPendingAt: { $exists: true },
             enclaveCancelConfirmedAt: { $exists: false },
         })
-        .sort({ enclaveCancelAttempts: 1, releaseAfter: 1 })
+        // Mongo sorts are unstable on ties; the unique ID makes bounded batches repeatable.
+        .sort({ enclaveCancelAttempts: 1, releaseAfter: 1, _id: 1 })
         .limit(limit)
         .toArray();
 
@@ -427,10 +435,16 @@ export const completeEscrowHold = async (id: string): Promise<EscrowHold | null>
         { returnDocument: 'after' }
     );
 };
-/** Whether escrow material at this share version has already been released. */
+/**
+ * Whether escrow material at this share version has already been released.
+ * `completedAfter` ignores releases at or before that time: a PIN re-set at the
+ * same version after a PIN sign-in (keep mode) is a fresh PIN, so the release
+ * that preceded it must not retire it at the next rotation.
+ */
 export const hasCompletedEscrowHoldForVersion = async (
     authProvider: AuthProviderMapping,
-    shareVersion: number
+    shareVersion: number,
+    options: { completedAfter?: Date } = {}
 ): Promise<boolean> =>
     (await getEscrowHoldsCollection().countDocuments(
         {
@@ -438,6 +452,7 @@ export const hasCompletedEscrowHoldForVersion = async (
             'authProvider.id': authProvider.id,
             shareVersion,
             status: 'completed',
+            ...(options.completedAfter ? { completedAt: { $gt: options.completedAfter } } : {}),
         },
         { limit: 1 }
     )) > 0;
@@ -499,7 +514,8 @@ export const findEscrowHoldsPendingStartNotification = async (
 ): Promise<EscrowHold[]> =>
     getEscrowHoldsCollection()
         .find({ status: 'pending', startedNotificationPending: true })
-        .sort({ startedNotificationAttemptedAt: 1, requestedAt: 1 })
+        // Keep tied start-notification batches deterministic before the limit.
+        .sort({ startedNotificationAttemptedAt: 1, requestedAt: 1, _id: 1 })
         .limit(limit)
         .toArray();
 
@@ -563,7 +579,8 @@ export const findEscrowHoldsDueForReminder = async (
             releaseAfter: { $lte: new Date(now.getTime() + ESCROW_HOLD_REMINDER_WINDOW_MS) },
             'notifications.kind': { $ne: 'reminder' },
         })
-        .sort({ reminderAttemptedAt: 1, releaseAfter: 1 })
+        // Keep tied reminder batches deterministic before the limit.
+        .sort({ reminderAttemptedAt: 1, releaseAfter: 1, _id: 1 })
         .limit(limit)
         .toArray();
 

package/src/models/UserKey.escrowPin.test.ts

@@ -28,6 +28,7 @@ describe('getEscrowPinStatus', () => {
             state,
             enabled: false,
             attemptsRemaining: 10,
+            wrongAttempts: 0,
         });
     });
 
@@ -43,7 +44,27 @@ describe('getEscrowPinStatus', () => {
                 enabled: true,
                 attemptsRemaining: Math.max(0, 10 - failedAttempts),
                 salt: 'salt',
+                // Charged budget alone never proves a wrong entry (legacy records).
+                ...(failedAttempts === 0 ? { wrongAttempts: 0 } : {}),
             });
         }
     );
+
+    it('reports verified wrong entries, not the charged budget', () => {
+        const userKey = {
+            shareVersion: 1,
+            escrowPin: {
+                salt: 'salt',
+                shareVersion: 1,
+                // 3 verified mismatches + 1 successful release + 1 open reservation.
+                failedAttempts: 5,
+                verifiedFailedAttempts: 3,
+                enabledAt: new Date(),
+            },
+        } as MongoUserKeyType;
+        expect(getEscrowPinStatus(userKey)).toMatchObject({
+            attemptsRemaining: 5,
+            wrongAttempts: 3,
+        });
+    });
 });