@learncard/lca-api-service 1.6.0 → 1.6.2

package/src/services/escrow-enclave/enrollmentLease.ts

@@ -0,0 +1,124 @@
+import { randomBytes } from 'crypto';
+import {
+    commitEscrowEnrollmentLease,
+    findUserKeyByAuthProvider,
+    releaseEscrowEnrollmentLease,
+    type AuthProviderMapping,
+    type EscrowEnrollmentLease,
+} from '@models';
+import { getEscrowEnclave, isEscrowRemoteMode } from './index';
+import {
+    EscrowBlobError,
+    EscrowCodeError,
+    EscrowPolicyError,
+    EscrowUnavailableError,
+} from './types';
+import { escrowBlobIdentity } from './blobIdentity';
+import type { AuthorityMutationResult, AuthorityStateResponse } from './authorityContract';
+
+/**
+ * A definite authority refusal: the operation never committed, so its lease can be
+ * released at once. Anything else (timeout, lost or malformed response) may have.
+ */
+export const isDefiniteAuthorityRefusal = (error: unknown): boolean =>
+    error instanceof EscrowPolicyError ||
+    error instanceof EscrowBlobError ||
+    error instanceof EscrowCodeError;
+
+/**
+ * True when the authority's current state is exactly the commit `lease` was claimed
+ * for: one enrollment version past the read, the signed epoch and share version, the
+ * PIN generation the intent's action implies and, when the caller holds the returned
+ * mutation, the same envelope identity.
+ */
+export const isLeaseCommitted = (
+    lease: EscrowEnrollmentLease,
+    { state }: AuthorityStateResponse,
+    received?: AuthorityMutationResult
+): boolean => {
+    const pinChanged = lease.pinAction !== 'keep';
+    if (
+        state.authorityGeneration !== lease.authorityGeneration ||
+        state.enrollmentVersion !== lease.expectedEnrollmentVersion + 1 ||
+        state.enrollmentEpoch !== lease.enrollmentEpoch ||
+        (lease.expectedPinGeneration !== undefined &&
+            state.pinGeneration !== lease.expectedPinGeneration + (pinChanged ? 1 : 0)) ||
+        (pinChanged && state.hasPin !== (lease.pinAction !== 'clear'))
+    )
+        return false;
+    if (received && received.enrollmentVersion !== state.enrollmentVersion) return false;
+    if (lease.action === 'disable') return state.status === 'disabled' && !state.envelope;
+    return (
+        state.status === 'active' &&
+        !!state.envelope &&
+        state.shareVersion === lease.shareVersion &&
+        (!received?.envelope ||
+            escrowBlobIdentity(received.envelope) === escrowBlobIdentity(state.envelope))
+    );
+};
+
+/**
+ * Converge Mongo to the authority after a PIN-operation lease did not complete
+ * normally (lost response, crash, or the lease's own write missed). Reads the
+ * authority's state: if it is the lease's commit, persists the authority's envelope,
+ * epoch and version with the PIN record the lease recorded (`adopted`, also when
+ * another request already persisted that same commit); otherwise drops the lease
+ * when `releaseIfUncommitted` (only safe once no call under it can still land: an
+ * expired lease, or a definite refusal), else leaves it to expire (`kept`).
+ * Idempotent: the adopt write is conditioned on the lease id (or, with the returned
+ * mutation in hand, on the lease being gone) and on the blob it replaced.
+ */
+export const settleEscrowEnrollmentLease = async (
+    authProvider: AuthProviderMapping,
+    primaryDid: string,
+    lease: EscrowEnrollmentLease,
+    {
+        received,
+        releaseIfUncommitted,
+    }: { received?: AuthorityMutationResult; releaseIfUncommitted: boolean }
+): Promise<'adopted' | 'released' | 'kept'> => {
+    const enclave = getEscrowEnclave();
+    if (!isEscrowRemoteMode() || !enclave.getEnrollmentState) {
+        await releaseEscrowEnrollmentLease(authProvider, lease.id);
+        return 'released';
+    }
+    const current = await enclave.getEnrollmentState({
+        expectedDid: primaryDid,
+        nonce: randomBytes(32).toString('hex'),
+    });
+    if (current.state.did !== primaryDid) throw new EscrowUnavailableError('invalid_response');
+    if (isLeaseCommitted(lease, current, received)) {
+        const adopted = await commitEscrowEnrollmentLease(
+            authProvider,
+            lease,
+            {
+                envelope: current.state.envelope,
+                authorityGeneration: current.state.authorityGeneration,
+                enrollmentVersion: current.state.enrollmentVersion,
+                enrollmentEpoch: current.state.enrollmentEpoch,
+                ...(received ? { receipt: received.receipt } : {}),
+                stateProof: current.proof,
+            },
+            { adoptWithoutLease: received !== undefined }
+        );
+        if (adopted) return 'adopted';
+        // Another request (an expired-lease settle) may already have persisted this
+        // exact commit: Mongo then serves the authority's copy, nothing is left to do.
+        // Only on the lease's own split: a security rotation also drops the lease and
+        // the blob, but never wrote this commit (or a disable's opt-out) into Mongo.
+        const stored = await findUserKeyByAuthProvider(authProvider.type, authProvider.id);
+        const persisted =
+            stored !== null &&
+            stored.shareVersion === lease.shareVersion &&
+            stored.escrowEnrollmentLease?.id !== lease.id &&
+            (current.state.envelope
+                ? stored.escrowBlob?.blobHash === escrowBlobIdentity(current.state.envelope)
+                : !stored.escrowBlob && (!lease.optOut || stored.escrowOptedOutAt !== undefined));
+        await releaseEscrowEnrollmentLease(authProvider, lease.id);
+        // Otherwise Mongo moved past the blob this lease replaced (a rotation).
+        return persisted ? 'adopted' : 'released';
+    }
+    if (!releaseIfUncommitted) return 'kept';
+    await releaseEscrowEnrollmentLease(authProvider, lease.id);
+    return 'released';
+};

package/src/services/escrow-enclave/notifications.test.ts

@@ -238,6 +238,75 @@ describe('notifyEscrowHoldEvent', () => {
         expect(sent).toHaveLength(0);
     });
 
+    it('pin-sign-in emails a secure-account link (no token) and sends its own push copy', async () => {
+        const userKey = baseUserKey();
+        const completedAt = new Date('2026-03-04T05:06:07.000Z');
+        const hold = baseHold({ releasePolicy: 'pin', status: 'completed', completedAt });
+        const rotateCancelToken = vi.fn(async () => 'e'.repeat(64));
+        const { deps, sent, pushCalls, recorded } = makeDeps({ rotateCancelToken });
+
+        await expect(
+            notifyEscrowHoldEvent({ kind: 'pin-sign-in', hold, userKey }, deps)
+        ).resolves.toBe(true);
+
+        expect(rotateCancelToken).not.toHaveBeenCalled();
+        expect(sent).toHaveLength(1);
+        expect(sent[0]!.templateAlias).toBe('escrow-pin-sign-in');
+        expect(sent[0]!.templateModel).toEqual({
+            signedInAt: completedAt.toISOString(),
+            secureUrl: 'https://learncard.app/account/secure',
+        });
+        expect(pushCalls).toEqual([
+            expect.objectContaining({
+                message: {
+                    title: 'New device signed in with your PIN',
+                    body: 'Not you? Open the app to secure your account.',
+                },
+            }),
+        ]);
+        expect(recorded).toEqual([{ holdId: hold._id, kind: 'pin-sign-in' }]);
+    });
+
+    it('pin-sign-in links to the tenant app and sends tenant branding', async () => {
+        const userKey = baseUserKey();
+        const hold = baseHold({ releasePolicy: 'pin', status: 'completed' });
+        const { deps, sent } = makeDeps();
+        const emailBranding = { brandName: 'VetPass', appUrl: 'https://vetpass.app' };
+
+        await notifyEscrowHoldEvent(
+            {
+                kind: 'pin-sign-in',
+                hold,
+                userKey,
+                tenant: { id: 'vetpass', emailBranding, resolvedVia: 'header' },
+            },
+            deps
+        );
+
+        expect(sent[0]!.templateModel.secureUrl).toBe('https://vetpass.app/account/secure');
+        expect(sent[0]!.branding).toEqual(emailBranding);
+    });
+
+    it('pin-sign-in never throws when delivery fails', async () => {
+        const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+        const userKey = baseUserKey();
+        const hold = baseHold({ releasePolicy: 'pin', status: 'completed' });
+        const { deps } = makeDeps({
+            send: async () => {
+                throw new Error('postmark down owner@example.com');
+            },
+            sendPush: async () => {
+                throw new Error('fcm down');
+            },
+        });
+
+        await expect(
+            notifyEscrowHoldEvent({ kind: 'pin-sign-in', hold, userKey }, deps)
+        ).resolves.toBe(false);
+        expect(JSON.stringify(errorSpy.mock.calls)).not.toContain('owner@example.com');
+        errorSpy.mockRestore();
+    });
+
     it('sends a push notification to the account DID for every kind', async () => {
         const userKey = baseUserKey({ contactMethod: { type: 'phone', value: '+15555550100' } });
         const hold = baseHold();

package/src/services/escrow-enclave/notifications.ts

@@ -10,8 +10,15 @@ import { resolveBranding } from '@learncard/email-templates';
 import type { EscrowHold, MongoUserKeyType } from '@models';
 import { getDeliveryService, getFrom, type DeliveryService } from '../delivery';
 import { buildEscrowCancelUrl } from '@helpers/escrowCancelLink';
+import { buildAccountSecureUrl } from '@helpers/accountSecureLink';
 
-export type EscrowHoldEventKind = 'started' | 'reminder' | 'completed' | 'cancelled' | 'pin-locked';
+/**
+ * `'pin-sign-in'` replaces `'completed'` for PIN releases: a PIN release now
+ * signs a new device in without signing out other devices, so the notice links
+ * to "Secure my account" instead of only confirming a recovery.
+ */
+export type EscrowHoldEventKind =
+    'started' | 'reminder' | 'completed' | 'cancelled' | 'pin-locked' | 'pin-sign-in';
 
 export interface EscrowHoldEvent {
     kind: EscrowHoldEventKind;
@@ -79,6 +86,7 @@ const EMAIL_TEMPLATE_ALIAS: Record<EscrowHoldEventKind, TemplateId> = {
     completed: 'escrow-hold-released',
     cancelled: 'escrow-hold-cancelled',
     'pin-locked': 'escrow-pin-locked',
+    'pin-sign-in': 'escrow-pin-sign-in',
 };
 
 const PUSH_MESSAGES: Record<EscrowHoldEventKind, { title: string; body: string }> = {
@@ -102,6 +110,10 @@ const PUSH_MESSAGES: Record<EscrowHoldEventKind, { title: string; body: string }
         title: 'Recovery PIN locked',
         body: 'Your recovery PIN was locked after too many attempts.',
     },
+    'pin-sign-in': {
+        title: 'New device signed in with your PIN',
+        body: 'Not you? Open the app to secure your account.',
+    },
 };
 
 /**
@@ -207,6 +219,12 @@ const buildEmailTemplateModel = async (
         case 'completed':
             return { completedAt: (hold.completedAt ?? deps.now()).toISOString() };
 
+        case 'pin-sign-in':
+            return {
+                signedInAt: (hold.completedAt ?? deps.now()).toISOString(),
+                secureUrl: buildAccountSecureUrl({ baseUrl }),
+            };
+
         case 'cancelled':
             return {
                 cancelledAt: (hold.cancelledAt ?? deps.now()).toISOString(),

package/test/jobs/escrowHoldReminders.spec.ts

@@ -15,6 +15,13 @@ import {
     hashEscrowResumeToken,
     recordEscrowHoldNotification,
     computeEffectiveReleaseAfter,
+    findEscrowHoldsDueForReminder,
+    findEscrowHoldsPendingStartNotification,
+    findEscrowHoldsPendingEnclaveCancellation,
+    claimEscrowHoldForReminder,
+    releaseEscrowReminderClaim,
+    recordEscrowStartNotificationAttempt,
+    recordEscrowEnclaveCancelAttempt,
     ESCROW_RELEASE_TIME_MARGIN_MS,
     ESCROW_RELEASE_WARNING_GAP_MS,
     type AuthProviderMapping,
@@ -41,7 +48,11 @@ const makeProvider = (): AuthProviderMapping => {
 
 /** Every seed() call gets its own authProvider (see test/models/escrow.spec.ts
  * for why: only one pending hold-policy hold is allowed per authProvider). */
-const seed = async (releaseAfter: Date, releasePolicy: 'hold' | 'pin' = 'hold') => {
+const seed = async (
+    releaseAfter: Date,
+    releasePolicy: 'hold' | 'pin' = 'hold',
+    holdId = randomUUID()
+) => {
     const provider = makeProvider();
     await upsertUserKeyByAuthProvider(
         { type: 'email', value: `${provider.id}@example.com` },
@@ -54,7 +65,7 @@ const seed = async (releaseAfter: Date, releasePolicy: 'hold' | 'pin' = 'hold')
     return createEscrowHold({
         holdRecord: {
             hold: {
-                holdId: randomUUID(),
+                holdId,
                 did: 'did:key:test',
                 shareVersion: 1,
                 blobHash: 'ab'.repeat(32),
@@ -117,6 +128,75 @@ afterAll(async () => {
 });
 
 describe('runEscrowHoldReminders', () => {
+    describe.each(['reminder', 'started', 'cancelled'] as const)('%s queue ordering', queue => {
+        it.each([false, true])(
+            'keeps tied batches stable and rotates retries (previously attempted: %s)',
+            async previouslyAttempted => {
+                const now = new Date();
+                const previousAttempt = new Date(now.getTime() - HOUR);
+                // More than a default delivery batch. Insert backwards so physical
+                // insertion order cannot accidentally satisfy the expected ID order.
+                const ids = Array.from(
+                    { length: 13 },
+                    (_, index) => `00000000-0000-4000-8000-${String(index + 1).padStart(12, '0')}`
+                );
+                for (const id of [...ids].reverse()) {
+                    await seed(new Date(now.getTime() + HOUR), 'hold', id);
+                }
+                await getEscrowHoldsCollection().updateMany(
+                    {},
+                    {
+                        $set: {
+                            requestedAt: previousAttempt,
+                            ...(queue === 'started' ? { startedNotificationPending: true } : {}),
+                            ...(queue === 'cancelled'
+                                ? {
+                                      status: 'cancelled' as const,
+                                      enclaveCancelPendingAt: previousAttempt,
+                                      enclaveCancelAttempts: previouslyAttempted ? 2 : 0,
+                                  }
+                                : previouslyAttempted
+                                  ? queue === 'reminder'
+                                      ? { reminderAttemptedAt: previousAttempt }
+                                      : { startedNotificationAttemptedAt: previousAttempt }
+                                  : {}),
+                        },
+                    }
+                );
+                const readBatch = () =>
+                    queue === 'reminder'
+                        ? findEscrowHoldsDueForReminder(now, 5)
+                        : queue === 'started'
+                          ? findEscrowHoldsPendingStartNotification(5)
+                          : findEscrowHoldsPendingEnclaveCancellation(5);
+
+                for (let repeat = 0; repeat < 3; repeat += 1) {
+                    expect((await readBatch()).map(hold => hold._id)).toEqual(ids.slice(0, 5));
+                }
+                // Failed deliveries remain eligible. Updating their real attempt
+                // markers must put untouched rows first, even with tied timestamps.
+                for (let offset = 0; offset < ids.length; offset += 5) {
+                    const batch = await readBatch();
+                    const remaining = Math.min(5, ids.length - offset);
+                    expect(batch.slice(0, remaining).map(hold => hold._id)).toEqual(
+                        ids.slice(offset, offset + remaining)
+                    );
+                    for (const hold of batch) {
+                        if (queue === 'reminder') {
+                            const claimed = await claimEscrowHoldForReminder(hold._id, now);
+                            expect(claimed).not.toBeNull();
+                            if (claimed) await releaseEscrowReminderClaim(claimed);
+                        } else if (queue === 'started') {
+                            await recordEscrowStartNotificationAttempt(hold._id, now);
+                        } else {
+                            expect(await recordEscrowEnclaveCancelAttempt(hold._id)).toBe(true);
+                        }
+                    }
+                }
+            }
+        );
+    });
+
     it('bounds cancellation retries and gives unattempted cancellations priority', async () => {
         const now = new Date();
         const holds = await Promise.all(
@@ -129,9 +209,13 @@ describe('runEscrowHoldReminders', () => {
         await runEscrowHoldReminders({ now, limit: 200 });
         const firstRun = await Promise.all(holds.map(hold => findEscrowHoldById(hold._id)));
         expect(firstRun.map(hold => hold?.enclaveCancelAttempts).sort()).toEqual([0, 0, 1, 1]);
-        const unattempted = firstRun.find(hold => hold?.enclaveCancelAttempts === 0)!;
+        // UUIDs are ASCII: default string ordering matches Mongo's byte ordering.
+        const unattemptedId = firstRun
+            .filter(hold => hold?.enclaveCancelAttempts === 0)
+            .map(hold => hold!._id)
+            .sort()[0]!;
         await runEscrowHoldReminders({ now, limit: 1 });
-        expect((await findEscrowHoldById(unattempted._id))?.enclaveCancelAttempts).toBe(1);
+        expect((await findEscrowHoldById(unattemptedId))?.enclaveCancelAttempts).toBe(1);
         for (const hold of holds) {
             const stored = await findEscrowHoldById(hold._id);
             expect(stored?.enclaveCancelPendingAt).toBeInstanceOf(Date);

package/test/keys-escrow.spec.ts

@@ -2499,11 +2499,13 @@ describe('escrow PIN release', () => {
             enabled: true,
             attemptsRemaining: 10,
             salt: pinSalt,
+            wrongAttempts: 0,
         });
         await getUserKeysCollection().updateOne(
             { 'authProviders.id': authProvider.id },
             { $set: { 'escrowPin.failedAttempts': 10, 'escrowPin.disabledAt': new Date() } }
         );
+        // Legacy charged history without the verified counter: no wrong-entry count.
         expect((await owner().keys.getAuthShare(auth))?.escrowPin).toEqual({
             state: 'locked',
             enabled: false,
@@ -2518,6 +2520,7 @@ describe('escrow PIN release', () => {
             state: 'stale',
             enabled: false,
             attemptsRemaining: 10,
+            wrongAttempts: 0,
         });
         await expect(startPin()).rejects.toMatchObject({ code: 'FORBIDDEN' });
     });
@@ -2580,6 +2583,7 @@ describe('escrow PIN release', () => {
             enabled: true,
             attemptsRemaining: 10,
             salt: pinSalt,
+            wrongAttempts: 0,
         });
         // Required for a no-provider Nitro escrow start/restart to bind to this account.
         expect(result.primaryDid).toBe(did);

package/test/keys-lifecycle-invariants.spec.ts

@@ -676,6 +676,82 @@ describe('P0-1 provisional SSS activation', () => {
     });
 });
 
+describe('P0-1 provisional purge spares escrow-enrolled migrations', () => {
+    const expiredMigration = (
+        email: string,
+        uid: string,
+        did: string,
+        escrow: { blob: boolean; method?: 'confirmed' | 'pending' }
+    ): MongoUserKeyType => {
+        const key = makeUserKey(email, uid, did, 'migrated-share');
+
+        Object.assign(key, {
+            keyProvider: 'web3auth' as const,
+            sssActivationState: 'provisional' as const,
+            provisionalCreatedAt: new Date(Date.now() - PROVISIONAL_MIGRATION_TTL_MS - 1_000),
+            recoveryMethods: escrow.method
+                ? [
+                      {
+                          type: 'escrow' as const,
+                          createdAt: new Date(),
+                          confirmationStatus: escrow.method,
+                          ...(escrow.method === 'confirmed' ? { confirmedAt: new Date() } : {}),
+                          shareVersion: 1,
+                      },
+                  ]
+                : [],
+            // Only presence matters to the purge filter.
+            ...(escrow.blob
+                ? { escrowBlob: { shareVersion: 1 } as unknown as MongoUserKeyType['escrowBlob'] }
+                : {}),
+        });
+
+        return key;
+    };
+
+    it.each([
+        ['confirmed escrow enrollment', false, { blob: true, method: 'confirmed' as const }],
+        [
+            'escrow blob without a confirmed method',
+            true,
+            { blob: true, method: 'pending' as const },
+        ],
+        ['confirmed method without a blob', true, { blob: false, method: 'confirmed' as const }],
+    ])('%s → purged: %s', async (_name, purged, escrow) => {
+        const suffix = `${Date.now()}-${randomUUID()}`;
+        const email = `escrow-purge-${suffix}@example.com`;
+        const uid = `uid-${suffix}`;
+        const { learnCard } = await getUser('5'.repeat(64));
+        const collection = getUserKeysCollection();
+
+        await collection.insertOne(expiredMigration(email, uid, learnCard.id.did(), escrow));
+
+        try {
+            const result = await getClient().keys.getAuthShare({
+                authToken: makeMockToken(email, uid),
+                providerType: 'firebase',
+            });
+            const stored = await collection.findOne({
+                authProviders: { $elemMatch: { type: 'firebase', id: uid } },
+            });
+
+            if (purged) {
+                expect(result?.authShare).toBeNull();
+                expect(stored?.authShare).toBeUndefined();
+                expect(stored?.escrowBlob).toBeUndefined();
+                expect(stored?.sssActivationState).toBeUndefined();
+            } else {
+                expect(stored?.authShare?.encryptedData).toBe('migrated-share');
+                expect(stored?.escrowBlob).toBeDefined();
+                expect(stored?.sssActivationState).toBe('provisional');
+                expect(stored?.keyProvider).toBe('web3auth');
+            }
+        } finally {
+            await collection.deleteMany({ 'contactMethod.value': email });
+        }
+    });
+});
+
 describe('P0-6 fresh DID authorization', () => {
     it('issues short-lived challenges that can only be consumed once', async () => {
         const did = `did:key:${randomUUID()}`;