@learncard/lca-api-service 1.6.0 → 1.6.2

package/src/routes/keys.ts

@@ -10,9 +10,10 @@ import admin from 'firebase-admin';
 import { createHmac, randomBytes, randomInt, timingSafeEqual } from 'crypto';
 import type { TenantBranding } from '@learncard/email-templates';
 
-import { t, openRoute, didRoute, didAndChallengeRoute } from '@routes';
+import { t, openRoute, didRoute, didAndChallengeRoute, type Context } from '@routes';
 import { getDeliveryService, getFrom } from '../services/delivery';
-import { getEscrowBlobStaleReason } from '../services/escrow-enclave';
+import { getEscrowBlobStaleReason, notifyEscrowHoldEvent } from '../services/escrow-enclave';
+import { cancelHoldInEnclave } from '../services/escrow-enclave/cancellation';
 import { verifyAuthToken, getContactMethodFromUser, AuthProviderType } from '@helpers/auth.helpers';
 import { encryptAuthShare, decryptAuthShare } from '@helpers/shareEncryption.helpers';
 import { maskEmail } from '@helpers/maskEmail';
@@ -24,8 +25,10 @@ import {
     claimRecoveryOtpSendWindow,
     consumeRecoverySession,
     createRecoverySession,
+    peekRecoverySession,
     storeRecoveryOtp,
     verifyRecoveryOtp,
+    type RecoverySessionRecord,
 } from '@cache/recoverySessions';
 import {
     findUserKeyByAuthProvider,
@@ -46,6 +49,11 @@ import {
     upgradeContactMethodByAuthProvider,
     deleteUserKeyByAuthProvider,
     completeIdentityRebind,
+    getSecurityEpoch,
+    linkAuthProviderKeepingShares,
+    revokeOtherDeviceShares,
+    findPendingEscrowHoldByAuthProvider,
+    cancelEscrowHold,
     ServerEncryptedShareValidator,
     EscrowPinStatusValidator,
     getEscrowPinStatus,
@@ -231,10 +239,11 @@ const serializeConfirmedRecoveryMethods = (userKey: MongoUserKeyType) =>
             ...(method.shareVersion != null ? { shareVersion: method.shareVersion } : {}),
         }));
 
-export const requireRecoverySession = async (
+/** Consume a recovery token and return its whole record (origin, released version). */
+export const requireRecoverySessionRecord = async (
     token: string,
     scope: 'recover' | 'rebind'
-): Promise<AuthProviderMapping> => {
+): Promise<RecoverySessionRecord & { authProvider: AuthProviderMapping }> => {
     const session = await consumeRecoverySession(token, scope);
 
     if (!session || !AuthProviderTypeValidator.safeParse(session.authProvider.type).success) {
@@ -244,7 +253,33 @@ export const requireRecoverySession = async (
         });
     }
 
-    return session.authProvider as AuthProviderMapping;
+    return session as RecoverySessionRecord & { authProvider: AuthProviderMapping };
+};
+
+export const requireRecoverySession = async (
+    token: string,
+    scope: 'recover' | 'rebind'
+): Promise<AuthProviderMapping> => (await requireRecoverySessionRecord(token, scope)).authProvider;
+
+/** The security epoch a recovery token was minted at (0 for tokens minted before the field). */
+export const getRecoverySessionEpoch = (session: Pick<RecoverySessionRecord, 'securityEpoch'>) =>
+    session.securityEpoch ?? 0;
+
+export const STALE_RECOVERY_SESSION_MESSAGE =
+    'Your account security changed during recovery. Start again.';
+
+/**
+ * Reject a recovery token minted before the account's last revoke or wiping rebind.
+ * A read-side check for routes that only release material; the routes that write
+ * (`/rebind`, `/pin-sign-in`) also enforce the epoch inside the update filter.
+ */
+export const assertRecoverySessionEpoch = (
+    session: Pick<RecoverySessionRecord, 'securityEpoch'>,
+    userKey: MongoUserKeyType
+): void => {
+    if (getRecoverySessionEpoch(session) !== getSecurityEpoch(userKey)) {
+        throw new TRPCError({ code: 'CONFLICT', message: STALE_RECOVERY_SESSION_MESSAGE });
+    }
 };
 
 const notifyIdentityRebind = async (
@@ -280,6 +315,106 @@ const notifyIdentityRebind = async (
     });
 };
 
+/** Delivery budget for the "Secure my account" notice, so a slow provider never stalls the route. */
+export const ACCOUNT_SECURED_NOTICE_TIMEOUT_MS = 3_000;
+
+/**
+ * The account's established contact address and its verified recovery email,
+ * deduped case-insensitively. Read from the record as it was before the revoke: the
+ * revoke never changes either, and the owner's login may be the one just unlinked.
+ */
+const getAccountSecuredRecipients = (userKey: MongoUserKeyType): string[] => {
+    const candidates = [
+        userKey.contactMethod.type === 'email' ? userKey.contactMethod.value : undefined,
+        userKey.recoveryEmail && userKey.recoveryEmailVerifiedAt
+            ? userKey.recoveryEmail
+            : undefined,
+    ];
+    const recipients = new Set<string>();
+
+    for (const candidate of candidates) {
+        const normalized = candidate?.trim().toLowerCase();
+        if (normalized) recipients.add(normalized);
+    }
+
+    return [...recipients];
+};
+
+/**
+ * Tell the owner that "Secure my account" ran. If someone with the owner's login and
+ * PIN ran it first, the owner's own login was just unlinked, so this notice is their
+ * only signal (the PIN sign-in notice's secure link no longer helps them). Awaited
+ * within a bounded budget so it is not lost when the request ends; fail-open, never
+ * throws, and never logs addresses.
+ */
+const notifyAccountSecured = async (
+    userKey: MongoUserKeyType,
+    branding: Partial<TenantBranding> | undefined,
+    securedAt: Date
+): Promise<void> => {
+    const recipients = getAccountSecuredRecipients(userKey);
+    if (recipients.length === 0) return;
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const send = Promise.allSettled(
+        recipients.map(to =>
+            getDeliveryService().send({
+                to,
+                templateAlias: 'account-secured',
+                templateModel: { securedAt: securedAt.toISOString() },
+                branding,
+                from: getFrom({ mailbox: 'recovery', branding }),
+            })
+        )
+    ).then(results => {
+        const failed = results.filter(result => result.status === 'rejected').length;
+        if (failed > 0) {
+            console.error('[revokeOtherDevices] Account-secured notice failed', {
+                failed,
+                total: results.length,
+            });
+        }
+    });
+
+    try {
+        await Promise.race([
+            send,
+            new Promise<void>(resolve => {
+                timer = setTimeout(() => {
+                    console.error('[revokeOtherDevices] Account-secured notice timed out');
+                    resolve();
+                }, ACCOUNT_SECURED_NOTICE_TIMEOUT_MS);
+            }),
+        ]);
+    } catch {
+        console.error('[revokeOtherDevices] Account-secured notice failed');
+    } finally {
+        clearTimeout(timer);
+    }
+};
+
+/** Cancel every pending escrow hold on the account (any linked login, either policy). */
+const cancelPendingEscrowHolds = async (
+    userKey: MongoUserKeyType,
+    tenant: Context['tenant']
+): Promise<void> => {
+    for (const authProvider of userKey.authProviders ?? []) {
+        for (const policy of ['hold', 'pin'] as const) {
+            const pending = await findPendingEscrowHoldByAuthProvider(authProvider, policy);
+            const cancelled = pending && (await cancelEscrowHold(pending._id, 'did'));
+            if (cancelled) {
+                await cancelHoldInEnclave(cancelled, userKey);
+                await notifyEscrowHoldEvent({
+                    kind: 'cancelled',
+                    hold: cancelled,
+                    userKey,
+                    tenant,
+                });
+            }
+        }
+    }
+};
+
 export const keysRouter = t.router({
     startRecoverySession: openRoute
         .meta({
@@ -405,6 +540,7 @@ export const keysRouter = t.router({
             const recoverySessionToken = await createRecoverySession({
                 scope: 'recover',
                 authProvider: verification.record.authProvider,
+                securityEpoch: getSecurityEpoch(userKey),
             });
 
             return {
@@ -441,10 +577,11 @@ export const keysRouter = t.router({
             })
         )
         .mutation(async ({ input }) => {
-            const authProvider = await requireRecoverySession(
+            const recoverSession = await requireRecoverySessionRecord(
                 input.recoverySessionToken,
                 'recover'
             );
+            const { authProvider } = recoverSession;
             if (input.type === 'escrow') {
                 throw new TRPCError({
                     code: 'BAD_REQUEST',
@@ -452,6 +589,7 @@ export const keysRouter = t.router({
                 });
             }
             const userKey = await requireUserKey(authProvider, 'Recovery account not found.');
+            assertRecoverySessionEpoch(recoverSession, userKey);
             const recoveryMethod = (userKey.recoveryMethods ?? []).find(method => {
                 if (method.type !== input.type || !isRecoveryMethodConfirmed(userKey, method)) {
                     return false;
@@ -481,6 +619,9 @@ export const keysRouter = t.router({
             const rebindSessionToken = await createRecoverySession({
                 scope: 'rebind',
                 authProvider,
+                // Inherit the recovery session's epoch, so a revoke at any point after
+                // the OTP still invalidates the whole chain at `/rebind`.
+                securityEpoch: getRecoverySessionEpoch(recoverSession),
             });
 
             return {
@@ -518,10 +659,11 @@ export const keysRouter = t.router({
             })
         )
         .mutation(async ({ input, ctx }) => {
-            const oldAuthProvider = await requireRecoverySession(
+            const session = await requireRecoverySessionRecord(
                 input.recoverySessionToken,
                 'rebind'
             );
+            const oldAuthProvider = session.authProvider;
             const oldUserKey = await requireUserKey(oldAuthProvider, 'Recovery account not found.');
 
             assertDidOwner(oldUserKey, ctx.user.did);
@@ -559,6 +701,17 @@ export const keysRouter = t.router({
                 newContactMethod,
                 primaryDid: input.primaryDid,
                 authShare: encryptAuthShare(input.authShare, seed),
+                // A PIN-release token is no longer used up by the PIN sign-in itself (keep
+                // mode never calls this route), so it may still be live here. Pin it to the
+                // version the PIN released: once "Secure my account" (or any rotation)
+                // moves the account on, the token can no longer wipe and rebind.
+                ...(session.origin === 'pin-release'
+                    ? { expectedShareVersion: session.shareVersion ?? -1 }
+                    : {}),
+                // Every token origin (phrase, passkey, backup, waiting-period hold, PIN)
+                // is bound to the epoch it was minted at, enforced in the update filter:
+                // after a revoke or another wiping rebind, no older token can rebind.
+                expectedSecurityEpoch: getRecoverySessionEpoch(session),
             });
 
             if (!result) {
@@ -582,6 +735,246 @@ export const keysRouter = t.router({
             };
         }),
 
+    /**
+     * PIN sign-in with a different login (keep mode). Links the new login to the
+     * account WITHOUT rotating: shares, history, recovery methods and escrow stay as
+     * they are, so other devices and the user's other recovery methods keep working.
+     * Only tokens minted by a successful PIN release are accepted; the waiting-period
+     * hold and `useRecoverySession` tokens must still use the wiping rebind. The
+     * owner was already emailed at the PIN release (`escrow-pin-sign-in`).
+     */
+    completePinSignIn: didAndChallengeRoute
+        .meta({
+            openapi: {
+                method: 'POST',
+                path: '/keys/recovery-session/pin-sign-in',
+                tags: ['Keys'],
+                summary: 'Link a new login after a PIN release without rotating shares',
+            },
+        })
+        .input(
+            z.object({
+                recoverySessionToken: RecoverySessionTokenValidator,
+                newAuthToken: z.string().min(1).optional(),
+                providerType: AuthProviderTypeValidator,
+                primaryDid: z.string(),
+            })
+        )
+        .output(
+            z.object({
+                success: z.literal(true),
+                shareVersion: z.number(),
+                linked: z.boolean(),
+            })
+        )
+        .mutation(async ({ input, ctx }) => {
+            // Validate before consuming: a waiting-period or phrase token sent here by
+            // mistake must stay usable at `/rebind`, and a DID mismatch must not burn
+            // the owner's token. Whatever is consumed is re-checked below.
+            const isPinSession = (
+                record: RecoverySessionRecord | null
+            ): record is RecoverySessionRecord & { primaryDid: string; shareVersion: number } =>
+                !!record &&
+                record.origin === 'pin-release' &&
+                !!record.primaryDid &&
+                record.shareVersion !== undefined;
+            const peeked = await peekRecoverySession(input.recoverySessionToken, 'rebind');
+
+            if (peeked && !isPinSession(peeked)) {
+                throw new TRPCError({
+                    code: 'FORBIDDEN',
+                    message: 'This recovery session cannot sign in without a reset.',
+                });
+            }
+            if (
+                peeked &&
+                (input.primaryDid !== ctx.user.did || input.primaryDid !== peeked.primaryDid)
+            ) {
+                throw new TRPCError({
+                    code: 'FORBIDDEN',
+                    message: 'Recovered DID does not match.',
+                });
+            }
+
+            const session = await requireRecoverySessionRecord(
+                input.recoverySessionToken,
+                'rebind'
+            );
+
+            if (!isPinSession(session)) {
+                throw new TRPCError({
+                    code: 'FORBIDDEN',
+                    message: 'This recovery session cannot sign in without a reset.',
+                });
+            }
+
+            const oldAuthProvider = session.authProvider;
+            const userKey = await requireUserKey(oldAuthProvider, 'Recovery account not found.');
+
+            assertDidOwner(userKey, ctx.user.did);
+            if (input.primaryDid !== ctx.user.did || input.primaryDid !== session.primaryDid) {
+                throw new TRPCError({
+                    code: 'FORBIDDEN',
+                    message: 'Recovered DID does not match.',
+                });
+            }
+
+            const newUser = await verifyAuthToken(
+                input.newAuthToken || ctx.providerToken || '',
+                input.providerType
+            );
+            const newContactMethod = getContactMethodFromUser(newUser);
+
+            if (!newContactMethod) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'New sign-in needs an email or phone.',
+                });
+            }
+
+            const newAuthProvider: AuthProviderMapping = {
+                type: input.providerType,
+                id: newUser.id,
+            };
+            const alreadyLinked = (userKey.authProviders ?? []).some(
+                provider =>
+                    provider.type === newAuthProvider.type && provider.id === newAuthProvider.id
+            );
+
+            if (alreadyLinked) {
+                if (
+                    (userKey.shareVersion ?? 1) !== session.shareVersion ||
+                    getSecurityEpoch(userKey) !== getRecoverySessionEpoch(session)
+                ) {
+                    throw new TRPCError({
+                        code: 'CONFLICT',
+                        message: 'Your account changed while signing in. Try again.',
+                    });
+                }
+
+                return {
+                    success: true as const,
+                    shareVersion: session.shareVersion,
+                    linked: false,
+                };
+            }
+
+            const result = await linkAuthProviderKeepingShares({
+                oldAuthProvider,
+                newAuthProvider,
+                primaryDid: input.primaryDid,
+                shareVersion: session.shareVersion,
+                securityEpoch: getRecoverySessionEpoch(session),
+            });
+
+            if (!result) {
+                throw new TRPCError({
+                    code: 'CONFLICT',
+                    message:
+                        'The sign-in is already linked elsewhere or your account changed. Try again.',
+                });
+            }
+
+            // Notification is intentionally fail-open after the link commits.
+            void notifyIdentityRebind(userKey, newContactMethod, ctx.tenant?.emailBranding).catch(
+                error => console.error('[completePinSignIn] Notification failed:', error)
+            );
+
+            return { success: true as const, shareVersion: result.shareVersion, linked: true };
+        }),
+
+    /**
+     * "Secure my account" / "Sign out of all other devices". The signed-in owner
+     * commits a fresh split: every older auth share is purged (other devices and the
+     * old phrase, backup file, passkey and email key stop working), recovery methods
+     * go back to pending, escrow is cleared for the client to re-enroll, and every
+     * login except the caller's is unlinked. One atomic CAS on `expectedShareVersion`;
+     * a concurrent rotation gets CONFLICT. The private key is unchanged, so a device
+     * that already holds it is not evicted (SECURITY.md D19). The security epoch
+     * advances, so every recovery token minted before the revoke is dead. After the
+     * commit the contact and verified recovery addresses get the `account-secured`
+     * notice (fail-open): the caller may not be the owner.
+     */
+    revokeOtherDevices: didAndChallengeRoute
+        .meta({
+            openapi: {
+                method: 'POST',
+                path: '/keys/revoke-other-devices',
+                tags: ['Keys'],
+                summary: 'Rotate shares, purge older versions and unlink other logins',
+            },
+        })
+        .input(
+            z.object({
+                /** Login token; falls back to the `X-Auth-Token` header like the rebind route. */
+                authToken: z.string().min(1).optional(),
+                providerType: AuthProviderTypeValidator,
+                primaryDid: z.string(),
+                authShare: ServerEncryptedShareValidator,
+                expectedShareVersion: z.number().int().positive(),
+            })
+        )
+        .output(
+            z.object({
+                success: z.literal(true),
+                shareVersion: z.number(),
+                recoveryMethodsRequireConfirmation: z.array(RecoveryMethodTypeValidator),
+            })
+        )
+        .mutation(async ({ input, ctx }) => {
+            const user = await verifyAuthToken(
+                input.authToken || ctx.providerToken || '',
+                input.providerType
+            );
+            const authProvider: AuthProviderMapping = { type: input.providerType, id: user.id };
+            const userKey = await requireUserKey(authProvider);
+
+            assertDidOwner(userKey, ctx.user.did);
+            if (input.primaryDid !== ctx.user.did) {
+                throw new TRPCError({
+                    code: 'FORBIDDEN',
+                    message: 'The authenticated DID does not match primaryDid.',
+                });
+            }
+
+            const seed = environment.SEED;
+            if (!seed) {
+                throw new TRPCError({
+                    code: 'INTERNAL_SERVER_ERROR',
+                    message: 'Server configuration error.',
+                });
+            }
+
+            const result = await revokeOtherDeviceShares({
+                authProvider,
+                primaryDid: input.primaryDid,
+                expectedShareVersion: input.expectedShareVersion,
+                authShare: encryptAuthShare(input.authShare, seed),
+            });
+
+            if (!result) {
+                throw new TRPCError({
+                    code: 'CONFLICT',
+                    message: `Key material changed; please retry (current version ${userKey.shareVersion ?? 1}).`,
+                });
+            }
+
+            // Clean-up only: pending holds already cannot release once the commit lands
+            // (`/complete` needs a confirmed escrow at the hold's version, and escrow is
+            // cleared). Best-effort, so a failure never reports the committed revoke as failed.
+            await cancelPendingEscrowHolds(userKey, ctx.tenant).catch(() =>
+                console.error('[revokeOtherDevices] Pending escrow hold clean-up failed')
+            );
+            // Fail-open after the commit: the owner may not be the one who ran this.
+            await notifyAccountSecured(userKey, ctx.tenant?.emailBranding, new Date());
+
+            return {
+                success: true as const,
+                shareVersion: result.shareVersion,
+                recoveryMethodsRequireConfirmation: result.methodsRequiringConfirmation,
+            };
+        }),
+
     issueDidChallenge: didRoute
         .meta({
             openapi: {
@@ -643,6 +1036,20 @@ export const keysRouter = t.router({
                     escrowOptedOut: z.boolean(),
                     escrowPin: EscrowPinStatusValidator,
                     escrowStale: z.enum(['mode-mismatch', 'key-rotated']).optional(),
+                    /**
+                     * Identity (blob hash) of the escrow copy lca-api holds. Authority-mode
+                     * clients compare it with the authority's envelope and repair a
+                     * mismatch instead of trusting a stale copy.
+                     */
+                    escrowBlobIdentity: z
+                        .string()
+                        .regex(/^[0-9a-f]{64}$/)
+                        .optional(),
+                    /**
+                     * A PIN operation holds the account's lease: lca-api's copy may trail
+                     * the authority until it settles, so a mismatch is not yet stale.
+                     */
+                    escrowUpdating: z.boolean().optional(),
                     /**
                      * The account has an escrow recovery method (any confirmation state)
                      * but none confirmed at the current share version, e.g. `pending`
@@ -731,6 +1138,8 @@ export const keysRouter = t.router({
                 escrowStale: userKey.escrowBlob
                     ? await getEscrowBlobStaleReason(userKey.escrowBlob)
                     : undefined,
+                ...(userKey.escrowBlob ? { escrowBlobIdentity: userKey.escrowBlob.blobHash } : {}),
+                ...(userKey.escrowEnrollmentLease ? { escrowUpdating: true } : {}),
                 priorEscrowEnrollment:
                     escrowMethods.length > 0 &&
                     !escrowMethods.some(

package/src/services/delivery/adapters/postmark.adapter.ts

@@ -44,6 +44,8 @@ const LOCAL_TEMPLATE_ALIASES: Record<string, TemplateId> = {
     'escrow-hold-released': 'escrow-hold-released',
     'escrow-hold-cancelled': 'escrow-hold-cancelled',
     'escrow-pin-locked': 'escrow-pin-locked',
+    'escrow-pin-sign-in': 'escrow-pin-sign-in',
+    'account-secured': 'account-secured',
 };
 
 /** Whether the given alias is a sentinel we registered (vs. a real Postmark alias). */
@@ -248,6 +250,15 @@ export class PostmarkAdapter implements DeliveryService {
                     cancelUrl: model.cancelUrl as string | undefined,
                 };
 
+            case 'escrow-pin-sign-in':
+                return {
+                    signedInAt: (model.signedInAt as string) ?? '',
+                    secureUrl: (model.secureUrl as string) ?? '',
+                };
+
+            case 'account-secured':
+                return { securedAt: (model.securedAt as string) ?? '' };
+
             default:
                 return model as TemplateDataMap[TemplateId];
         }

package/src/services/escrow-enclave/README.md

@@ -14,9 +14,14 @@ existing host-trusted model, but does not protect against a malicious host eithe
 The API atomically reserves one of ten lifetime attempts before claiming the hold
 and calling the enclave. Failed releases burn the single-use hold. Exhaustion
 disables PIN recovery and cancels pending PIN holds; delayed recovery remains
-available. Successful PIN recovery does not replenish the lifetime budget; authenticated
-enrollment with a new PIN starts a fresh counter. Setting or changing a PIN requires
-client share rotation. Inbox compromise plus a correct PIN guess can recover the
+available. Successful PIN recovery does not replenish the lifetime budget by itself;
+authenticated enrollment of a PIN starts a fresh counter. A PIN sign-in (keep mode,
+pending security approval; see `services/escrow-enclave-app/SECURITY.md` D19) re-enrolls
+the same PIN at the same share version straight after the release, which starts a fresh
+counter without a rotation, but only when the PIN status records no wrong attempt for the
+current PIN; otherwise the client keeps the reduced budget and asks the user for a different
+PIN. Otherwise, setting or changing a PIN requires client share
+rotation. Inbox compromise plus a correct PIN guess can recover the
 account (at most 10/1,000,000 for a uniformly random six-digit PIN).
 
 Software hold records contain a non-cryptographic signature placeholder and no