@learncard/lca-api-service 1.6.1 → 1.6.3

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/keys-escrow.spec.ts

@@ -1971,6 +1971,24 @@ describe('escrow PIN release', () => {
         expect((await record())?.escrowPin?.failedAttempts).toBe(2);
     });
 
+    it('never reports "Incorrect PIN." for a mismatch whose wrong entry was not recorded', async () => {
+        // The record changed under the compare (re-enrolled/rotated elsewhere): clients
+        // count every "Incorrect PIN." as their own recorded entry (own-typos rule).
+        await enrollPin();
+        const hold = await startPin();
+        vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+        vi.spyOn(models, 'recordEscrowPinFailure').mockResolvedValueOnce(null);
+        await expect(completePin(hold, wrongProof)).rejects.toMatchObject({
+            code: 'CONFLICT',
+            message: 'Automatic recovery changed; please refresh.',
+        });
+        expect(await findEscrowHoldById(hold.holdId)).toMatchObject({
+            status: 'cancelled',
+            cancelReason: 'pin-mismatch',
+        });
+        expect((await record())?.escrowPin?.verifiedFailedAttempts ?? 0).toBe(0);
+    });
+
     it('locks after ten mismatches and still permits delayed recovery', async () => {
         await enrollPin();
         let lockingHoldId = '';
@@ -2499,11 +2517,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 +2538,7 @@ describe('escrow PIN release', () => {
             state: 'stale',
             enabled: false,
             attemptsRemaining: 10,
+            wrongAttempts: 0,
         });
         await expect(startPin()).rejects.toMatchObject({ code: 'FORBIDDEN' });
     });
@@ -2580,6 +2601,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);