@learncard/lca-api-service 1.3.2 → 1.5.0

package/src/routes/keys.ts

@@ -7,55 +7,179 @@ import { environment } from '@environment';
 import { z } from 'zod';
 import { TRPCError } from '@trpc/server';
 import admin from 'firebase-admin';
+import { createHmac, randomBytes, randomInt, timingSafeEqual } from 'crypto';
+import type { TenantBranding } from '@learncard/email-templates';
 
-import { t, openRoute, didRoute } from '@routes';
+import { t, openRoute, didRoute, didAndChallengeRoute } from '@routes';
 import { getDeliveryService, getFrom } from '../services/delivery';
+import { getEscrowBlobStaleReason } from '../services/escrow-enclave';
 import { verifyAuthToken, getContactMethodFromUser, AuthProviderType } from '@helpers/auth.helpers';
 import { encryptAuthShare, decryptAuthShare } from '@helpers/shareEncryption.helpers';
 import { maskEmail } from '@helpers/maskEmail';
 import cache from '@cache';
+import { setValidChallengeForDid } from '@cache/challenges';
+import { checkRateLimit, clearRateLimit } from '@helpers/rateLimit.helpers';
 import {
-    findUserKeyByContactMethod,
+    MAX_RECOVERY_OTP_ATTEMPTS,
+    claimRecoveryOtpSendWindow,
+    consumeRecoverySession,
+    createRecoverySession,
+    storeRecoveryOtp,
+    verifyRecoveryOtp,
+} from '@cache/recoverySessions';
+import {
+    findUserKeyByAuthProvider,
+    findUniqueUserKeyByVerifiedRecoveryEmail,
     findAuthShareByVersion,
-    upsertUserKey,
-    addAuthProviderToUserKey,
-    addRecoveryMethodToUserKey,
-    setRecoveryEmail,
-    markUserKeyMigrated,
-    upgradeContactMethod,
-    deleteUserKey,
+    upsertUserKeyByAuthProvider,
+    addRecoveryMethodToUserKeyByAuthProvider,
+    confirmRecoveryMethodByAuthProvider,
+    incrementRecoveryConfirmationAttemptsByAuthProvider,
+    removeRecoveryMethodFromUserKeyByAuthProvider,
+    setRecoveryEmailByAuthProvider,
+    markUserKeyMigrationProvisionalByAuthProvider,
+    activateUserKeyByAuthProvider,
+    purgeExpiredProvisionalMigrationByAuthProvider,
+    getSssActivationState,
+    hasActivatableRecoveryMethod,
+    isRecoveryMethodConfirmed,
+    upgradeContactMethodByAuthProvider,
+    deleteUserKeyByAuthProvider,
+    completeIdentityRebind,
     ServerEncryptedShareValidator,
+    EscrowPinStatusValidator,
+    getEscrowPinStatus,
     EncryptedShareValidator,
+    UserKeyVersionConflictError,
     type ContactMethod,
+    type AuthProviderMapping,
+    type MongoUserKeyType,
 } from '@models';
 
 const RECOVERY_EMAIL_CODE_TEMPLATE_ALIAS =
     environment.POSTMARK_RECOVERY_EMAIL_CODE_TEMPLATE_ALIAS ?? '';
-const RECOVERY_KEY_TEMPLATE_ALIAS = environment.POSTMARK_RECOVERY_KEY_TEMPLATE_ALIAS ?? '';
 
 const RECOVERY_EMAIL_CODE_PREFIX = 'recovery_email_code:';
 const RECOVERY_EMAIL_CODE_TTL_SECS = 15 * 60; // 15 minutes
+const RECOVERY_METHOD_CONFIRMATION_TTL_MS = 15 * 60 * 1000;
+const MAX_RECOVERY_METHOD_CONFIRMATION_ATTEMPTS = 5;
+const EMAIL_RELAY_ALGORITHM = 'P-256-HKDF-SHA256-AES-256-GCM' as const;
+const ESCROW_RELAY_TIMEOUT_MS = 15_000;
+
+// Rate limiting for recovery email verification (brute-force protection)
+const RECOVERY_VERIFY_MAX_ATTEMPTS = 5; // max failed attempts per auth provider identity
+
+const generate6DigitCode = (): string => randomInt(100000, 1000000).toString();
+
+const hashRecoveryConfirmationCode = (code: string): string => {
+    const seed = environment.SEED;
+
+    if (!seed) {
+        throw new TRPCError({
+            code: 'INTERNAL_SERVER_ERROR',
+            message: 'Server misconfiguration: SEED is required for recovery confirmation',
+        });
+    }
 
-const generate6DigitCode = (): string => {
-    const array = new Uint32Array(1);
-    crypto.getRandomValues(array);
-    if (!array[0]) throw new Error('Failed to generate random number');
-    return (100000 + (array[0] % 900000)).toString();
+    return createHmac('sha256', seed).update(code).digest('hex');
 };
 
-const AuthProviderTypeValidator = z.enum(['firebase', 'supertokens', 'keycloak', 'oidc']);
+const confirmationCodeMatches = (code: string, expectedHash: string): boolean => {
+    const actual = Buffer.from(hashRecoveryConfirmationCode(code), 'hex');
+    const expected = Buffer.from(expectedHash, 'hex');
 
-const AuthInputValidator = z.object({
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+};
+
+export const AuthProviderTypeValidator = z.enum(['firebase', 'supertokens', 'keycloak', 'oidc']);
+
+export const AuthInputValidator = z.object({
     authToken: z.string(),
     providerType: AuthProviderTypeValidator,
 });
 
-async function verifyAndGetContactMethod(input: {
+const RecoveryMethodTypeValidator = z.enum(['passkey', 'backup', 'phrase', 'email', 'escrow']);
+export const RecoverySessionTokenValidator = z.string().regex(/^[0-9a-f]{64}$/);
+
+const RecoveryMethodResponseValidator = z.object({
+    type: RecoveryMethodTypeValidator,
+    createdAt: z.string(),
+    credentialId: z.string().optional(),
+    shareVersion: z.number().optional(),
+});
+
+const EmailRelayEnvelopeValidator = z
+    .object({
+        version: z.literal(1),
+        algorithm: z.literal(EMAIL_RELAY_ALGORITHM),
+        keyId: z.string().regex(/^[A-Za-z0-9._-]{1,128}$/),
+        ephemeralPublicKey: z.string().min(1).max(256),
+        salt: z.string().min(1).max(128),
+        iv: z.string().min(1).max(64),
+        ciphertext: z.string().min(1).max(16_384),
+    })
+    .strict();
+
+type EmailRelayEnvelope = z.infer<typeof EmailRelayEnvelopeValidator>;
+
+const sendRecoveryKeyToEscrowRelay = async (
+    payload: EmailRelayEnvelope,
+    expectedRecipient: string
+): Promise<void> => {
+    const relayUrl = environment.ESCROW_RELAY_URL?.replace(/\/$/, '');
+    const relayAuthToken = environment.ESCROW_RELAY_AUTH_TOKEN;
+
+    if (!relayUrl || !relayAuthToken) {
+        throw new TRPCError({
+            code: 'INTERNAL_SERVER_ERROR',
+            message: 'Recovery email delivery is not configured.',
+        });
+    }
+
+    let response: Response;
+
+    try {
+        response = await fetch(`${relayUrl}/email-backup`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${relayAuthToken}`,
+            },
+            body: JSON.stringify({ payload, expectedRecipient }),
+            signal: AbortSignal.timeout(ESCROW_RELAY_TIMEOUT_MS),
+        });
+    } catch {
+        throw new TRPCError({
+            code: 'INTERNAL_SERVER_ERROR',
+            message: 'Failed to send the recovery key. Please try again.',
+        });
+    }
+
+    const result: unknown = await response.json().catch(() => null);
+    const accepted =
+        typeof result === 'object' &&
+        result !== null &&
+        'accepted' in result &&
+        result.accepted === true &&
+        'messageId' in result &&
+        typeof result.messageId === 'string' &&
+        result.messageId.length > 0;
+
+    if (!response.ok || !accepted) {
+        throw new TRPCError({
+            code: 'INTERNAL_SERVER_ERROR',
+            message: 'Failed to send the recovery key. Please try again.',
+        });
+    }
+};
+
+export async function verifyAndGetContactMethod(input: {
     authToken: string;
     providerType: AuthProviderType;
 }): Promise<{
     user: { id: string; email?: string; phone?: string; providerType: string };
     contactMethod: ContactMethod;
+    authProvider: AuthProviderMapping;
 }> {
     const user = await verifyAuthToken(input.authToken, input.providerType);
 
@@ -67,10 +191,418 @@ async function verifyAndGetContactMethod(input: {
         });
     }
 
-    return { user, contactMethod };
+    return {
+        user,
+        contactMethod,
+        authProvider: { type: input.providerType, id: user.id },
+    };
 }
 
+export const requireUserKey = async (
+    authProvider: AuthProviderMapping,
+    message = 'User key not found. Set up SSS first.'
+): Promise<MongoUserKeyType> => {
+    const userKey = await findUserKeyByAuthProvider(authProvider.type, authProvider.id);
+
+    if (!userKey) throw new TRPCError({ code: 'NOT_FOUND', message });
+
+    return userKey;
+};
+
+export const assertDidOwner = (userKey: MongoUserKeyType, authenticatedDid: string): void => {
+    if (!userKey.primaryDid || userKey.primaryDid !== authenticatedDid) {
+        throw new TRPCError({
+            code: 'FORBIDDEN',
+            message: 'The authenticated DID does not own this key record.',
+        });
+    }
+};
+
+const serializeConfirmedRecoveryMethods = (userKey: MongoUserKeyType) =>
+    (userKey.recoveryMethods ?? [])
+        .filter(method => isRecoveryMethodConfirmed(userKey, method))
+        .map(method => ({
+            type: method.type,
+            createdAt:
+                method.createdAt instanceof Date
+                    ? method.createdAt.toISOString()
+                    : String(method.createdAt),
+            ...(method.credentialId ? { credentialId: method.credentialId } : {}),
+            ...(method.shareVersion != null ? { shareVersion: method.shareVersion } : {}),
+        }));
+
+export const requireRecoverySession = async (
+    token: string,
+    scope: 'recover' | 'rebind'
+): Promise<AuthProviderMapping> => {
+    const session = await consumeRecoverySession(token, scope);
+
+    if (!session || !AuthProviderTypeValidator.safeParse(session.authProvider.type).success) {
+        throw new TRPCError({
+            code: 'UNAUTHORIZED',
+            message: 'This recovery session is invalid or expired. Start again.',
+        });
+    }
+
+    return session.authProvider as AuthProviderMapping;
+};
+
+const notifyIdentityRebind = async (
+    userKey: MongoUserKeyType,
+    newContactMethod: ContactMethod,
+    branding: Partial<TenantBranding> | undefined
+): Promise<void> => {
+    const recipients = new Set<string>();
+
+    if (userKey.contactMethod.type === 'email') recipients.add(userKey.contactMethod.value);
+    if (userKey.recoveryEmail) recipients.add(userKey.recoveryEmail);
+    if (newContactMethod.type === 'email') recipients.add(newContactMethod.value);
+
+    const results = await Promise.allSettled(
+        [...recipients].map(to =>
+            getDeliveryService().send({
+                to,
+                templateAlias: 'account-sign-in-changed',
+                templateModel: {},
+                branding,
+                from: getFrom({ mailbox: 'recovery', branding }),
+            })
+        )
+    );
+
+    results.forEach(result => {
+        if (result.status === 'rejected') {
+            console.error(
+                '[notifyIdentityRebind] Failed to send security notification:',
+                result.reason
+            );
+        }
+    });
+};
+
 export const keysRouter = t.router({
+    startRecoverySession: openRoute
+        .meta({
+            openapi: {
+                method: 'POST',
+                path: '/keys/recovery-session/start',
+                tags: ['Keys'],
+                summary: 'Send a recovery-session verification code',
+            },
+        })
+        .input(z.object({ email: z.string().email() }))
+        .output(z.object({ success: z.literal(true) }))
+        .mutation(async ({ input, ctx }) => {
+            const email = input.email.trim().toLowerCase();
+            const canSend = await claimRecoveryOtpSendWindow(email);
+
+            if (!canSend) {
+                throw new TRPCError({
+                    code: 'TOO_MANY_REQUESTS',
+                    message: 'Please wait before requesting another code.',
+                });
+            }
+
+            const userKey = await findUniqueUserKeyByVerifiedRecoveryEmail(email);
+            const hasConfirmedMethod = userKey
+                ? serializeConfirmedRecoveryMethods(userKey).length > 0
+                : false;
+
+            // Deliberately return the same response when no account matches.
+            if (!userKey || !hasConfirmedMethod || !userKey.authProviders[0]) {
+                return { success: true as const };
+            }
+
+            const code = generate6DigitCode();
+            await storeRecoveryOtp(email, {
+                codeHash: hashRecoveryConfirmationCode(code),
+                authProvider: userKey.authProviders[0],
+            });
+
+            try {
+                await getDeliveryService().send({
+                    to: email,
+                    templateAlias: RECOVERY_EMAIL_CODE_TEMPLATE_ALIAS || 'recovery-email-code',
+                    templateModel: { verificationCode: code, verificationEmail: email },
+                    branding: ctx.tenant?.emailBranding,
+                    from: getFrom({ mailbox: 'recovery', branding: ctx.tenant?.emailBranding }),
+                });
+            } catch (error) {
+                console.error('[startRecoverySession] Failed to send verification email:', error);
+            }
+
+            return { success: true as const };
+        }),
+
+    verifyRecoverySession: openRoute
+        .meta({
+            openapi: {
+                method: 'POST',
+                path: '/keys/recovery-session/verify',
+                tags: ['Keys'],
+                summary: 'Verify recovery email and issue a one-use recovery token',
+            },
+        })
+        .input(z.object({ email: z.string().email(), code: z.string().regex(/^\d{6}$/) }))
+        .output(
+            z.object({
+                recoverySessionToken: RecoverySessionTokenValidator,
+                recoveryMethods: z.array(RecoveryMethodResponseValidator),
+                escrowPin: EscrowPinStatusValidator,
+            })
+        )
+        .mutation(async ({ input }) => {
+            const email = input.email.trim().toLowerCase();
+            const verification = await verifyRecoveryOtp(
+                email,
+                hashRecoveryConfirmationCode(input.code)
+            );
+
+            if (verification.status === 'locked') {
+                throw new TRPCError({
+                    code: 'TOO_MANY_REQUESTS',
+                    message: 'Too many incorrect attempts. Request a new code later.',
+                });
+            }
+
+            if (verification.status === 'mismatch') {
+                throw new TRPCError({
+                    code:
+                        verification.attempts >= MAX_RECOVERY_OTP_ATTEMPTS
+                            ? 'TOO_MANY_REQUESTS'
+                            : 'BAD_REQUEST',
+                    message:
+                        verification.attempts >= MAX_RECOVERY_OTP_ATTEMPTS
+                            ? 'Too many incorrect attempts. Request a new code later.'
+                            : 'Incorrect or expired code. Please try again.',
+                });
+            }
+
+            if (verification.status === 'none') {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'Incorrect or expired code. Please try again.',
+                });
+            }
+
+            const userKey = await requireUserKey(
+                verification.record.authProvider,
+                'Recovery account not found.'
+            );
+            const recoveryMethods = serializeConfirmedRecoveryMethods(userKey);
+
+            if (recoveryMethods.length === 0) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'No recovery method is available.',
+                });
+            }
+
+            const recoverySessionToken = await createRecoverySession({
+                scope: 'recover',
+                authProvider: verification.record.authProvider,
+            });
+
+            return {
+                recoverySessionToken,
+                recoveryMethods,
+                escrowPin: getEscrowPinStatus(userKey),
+            };
+        }),
+
+    useRecoverySession: openRoute
+        .meta({
+            openapi: {
+                method: 'POST',
+                path: '/keys/recovery-session/recover',
+                tags: ['Keys'],
+                summary: 'Release version-matched recovery material under a recovery session',
+            },
+        })
+        .input(
+            z.object({
+                recoverySessionToken: RecoverySessionTokenValidator,
+                type: RecoveryMethodTypeValidator,
+                credentialId: z.string().optional(),
+            })
+        )
+        .output(
+            z.object({
+                authShare: ServerEncryptedShareValidator,
+                encryptedShare: EncryptedShareValidator.optional(),
+                primaryDid: z.string(),
+                shareVersion: z.number(),
+                rebindSessionToken: RecoverySessionTokenValidator,
+            })
+        )
+        .mutation(async ({ input }) => {
+            const authProvider = await requireRecoverySession(
+                input.recoverySessionToken,
+                'recover'
+            );
+            if (input.type === 'escrow') {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'Use /keys/escrow/recover for automatic recovery.',
+                });
+            }
+            const userKey = await requireUserKey(authProvider, 'Recovery account not found.');
+            const recoveryMethod = (userKey.recoveryMethods ?? []).find(method => {
+                if (method.type !== input.type || !isRecoveryMethodConfirmed(userKey, method)) {
+                    return false;
+                }
+
+                return input.type !== 'passkey' || method.credentialId === input.credentialId;
+            });
+
+            if (!recoveryMethod?.shareVersion) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'Recovery method is unavailable.',
+                });
+            }
+
+            const encryptedAuthShare = findAuthShareByVersion(userKey, recoveryMethod.shareVersion);
+            const seed = environment.SEED;
+
+            if (!encryptedAuthShare || !seed) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'Recovery method is outdated.',
+                });
+            }
+
+            const authShare = decryptAuthShare(encryptedAuthShare, seed);
+            const rebindSessionToken = await createRecoverySession({
+                scope: 'rebind',
+                authProvider,
+            });
+
+            return {
+                authShare,
+                encryptedShare: recoveryMethod.encryptedShare,
+                primaryDid: userKey.primaryDid,
+                shareVersion: recoveryMethod.shareVersion,
+                rebindSessionToken,
+            };
+        }),
+
+    completeRecoveryRebind: didAndChallengeRoute
+        .meta({
+            openapi: {
+                method: 'POST',
+                path: '/keys/recovery-session/rebind',
+                tags: ['Keys'],
+                summary: 'Bind a replacement login and commit recovery rotation',
+            },
+        })
+        .input(
+            z.object({
+                recoverySessionToken: RecoverySessionTokenValidator,
+                newAuthToken: z.string().min(1).optional(),
+                providerType: AuthProviderTypeValidator,
+                primaryDid: z.string(),
+                authShare: ServerEncryptedShareValidator,
+            })
+        )
+        .output(
+            z.object({
+                success: z.literal(true),
+                shareVersion: z.number(),
+                recoveryMethodsRequireConfirmation: z.array(RecoveryMethodTypeValidator),
+            })
+        )
+        .mutation(async ({ input, ctx }) => {
+            const oldAuthProvider = await requireRecoverySession(
+                input.recoverySessionToken,
+                'rebind'
+            );
+            const oldUserKey = await requireUserKey(oldAuthProvider, 'Recovery account not found.');
+
+            assertDidOwner(oldUserKey, ctx.user.did);
+            if (input.primaryDid !== ctx.user.did) {
+                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 seed = environment.SEED;
+            if (!seed) {
+                throw new TRPCError({
+                    code: 'INTERNAL_SERVER_ERROR',
+                    message: 'Server configuration error.',
+                });
+            }
+
+            const result = await completeIdentityRebind({
+                oldAuthProvider,
+                newAuthProvider: { type: input.providerType, id: newUser.id },
+                newContactMethod,
+                primaryDid: input.primaryDid,
+                authShare: encryptAuthShare(input.authShare, seed),
+            });
+
+            if (!result) {
+                throw new TRPCError({
+                    code: 'CONFLICT',
+                    message: 'The new sign-in is already linked or recovery state changed.',
+                });
+            }
+
+            // Notification is intentionally fail-open after the security update commits.
+            void notifyIdentityRebind(
+                oldUserKey,
+                newContactMethod,
+                ctx.tenant?.emailBranding
+            ).catch(error => console.error('[completeRecoveryRebind] Notification failed:', error));
+
+            return {
+                success: true as const,
+                shareVersion: result.shareVersion,
+                recoveryMethodsRequireConfirmation: result.methodsRequiringConfirmation,
+            };
+        }),
+
+    issueDidChallenge: didRoute
+        .meta({
+            openapi: {
+                method: 'POST',
+                path: '/keys/challenge',
+                tags: ['Keys'],
+                summary: 'Issue a short-lived DID challenge for a sensitive key write',
+            },
+        })
+        .input(z.object({ did: z.string() }))
+        .output(z.object({ challenge: z.string() }))
+        .mutation(async ({ ctx, input }) => {
+            if (ctx.user.did !== input.did) {
+                throw new TRPCError({
+                    code: 'FORBIDDEN',
+                    message: 'The authenticated DID does not match the requested challenge.',
+                });
+            }
+
+            const challenge = randomBytes(32).toString('hex');
+
+            await setValidChallengeForDid(ctx.user.did, challenge);
+
+            return { challenge };
+        }),
+
     getAuthShare: openRoute
         .meta({
             openapi: {
@@ -93,32 +625,33 @@ export const keysRouter = t.router({
                     securityLevel: z.enum(['basic', 'enhanced', 'advanced']),
                     recoveryMethods: z.array(
                         z.object({
-                            type: z.enum(['passkey', 'backup', 'phrase', 'email']),
+                            type: RecoveryMethodTypeValidator,
                             createdAt: z.string(),
                             credentialId: z.string().optional(),
                             shareVersion: z.number().optional(),
+                            confirmedAt: z.string().optional(),
                         })
                     ),
                     keyProvider: z.enum(['web3auth', 'sss']),
                     shareVersion: z.number(),
                     maskedRecoveryEmail: z.string().nullable(),
+                    escrowOptedOut: z.boolean(),
+                    escrowPin: EscrowPinStatusValidator,
+                    escrowStale: z.enum(['mode-mismatch', 'key-rotated']).optional(),
+                    sssActivationState: z.enum(['provisional', 'active']),
                 })
                 .nullable()
         )
         .mutation(async ({ input }) => {
-            const { user, contactMethod } = await verifyAndGetContactMethod(input);
+            const { authProvider } = await verifyAndGetContactMethod(input);
+            await purgeExpiredProvisionalMigrationByAuthProvider(authProvider);
 
-            const userKey = await findUserKeyByContactMethod(contactMethod);
+            const userKey = await findUserKeyByAuthProvider(authProvider.type, authProvider.id);
 
             if (!userKey) {
                 return null;
             }
 
-            await addAuthProviderToUserKey(contactMethod, {
-                type: input.providerType,
-                id: user.id,
-            });
-
             // If a specific shareVersion is requested, look it up from history
             const requestedVersion = input.shareVersion;
             const rawAuthShare =
@@ -144,7 +677,9 @@ export const keysRouter = t.router({
             }
 
             const recoveryMethods = (userKey.recoveryMethods ?? [])
-                .filter(rm => rm && rm.type && rm.createdAt)
+                .filter(
+                    rm => rm && rm.type && rm.createdAt && isRecoveryMethodConfirmed(userKey, rm)
+                )
                 .map(rm => ({
                     type: rm.type,
                     createdAt:
@@ -153,6 +688,14 @@ export const keysRouter = t.router({
                             : String(rm.createdAt),
                     ...(rm.credentialId ? { credentialId: rm.credentialId } : {}),
                     ...(rm.shareVersion != null ? { shareVersion: rm.shareVersion } : {}),
+                    ...(rm.confirmedAt
+                        ? {
+                              confirmedAt:
+                                  rm.confirmedAt instanceof Date
+                                      ? rm.confirmedAt.toISOString()
+                                      : String(rm.confirmedAt),
+                          }
+                        : {}),
                 }));
 
             return {
@@ -161,14 +704,21 @@ export const keysRouter = t.router({
                 securityLevel: userKey.securityLevel ?? 'basic',
                 recoveryMethods,
                 keyProvider: userKey.keyProvider ?? 'sss',
-                shareVersion: userKey.shareVersion ?? 1,
+                // No auth material has observable version 0, just like a missing record.
+                shareVersion: userKey.authShare ? (userKey.shareVersion ?? 1) : 0,
                 maskedRecoveryEmail: userKey.recoveryEmail
                     ? maskEmail(userKey.recoveryEmail)
                     : null,
+                sssActivationState: getSssActivationState(userKey),
+                escrowOptedOut: Boolean(userKey.escrowOptedOutAt),
+                escrowPin: getEscrowPinStatus(userKey),
+                escrowStale: userKey.escrowBlob
+                    ? await getEscrowBlobStaleReason(userKey.escrowBlob)
+                    : undefined,
             };
         }),
 
-    storeAuthShare: didRoute
+    storeAuthShare: didAndChallengeRoute
         .meta({
             openapi: {
                 method: 'PUT',
@@ -183,23 +733,50 @@ export const keysRouter = t.router({
                 primaryDid: z.string(),
                 securityLevel: z.enum(['basic', 'enhanced', 'advanced']).optional(),
                 keyProvider: z.enum(['web3auth', 'sss']).optional(),
+                sssActivationState: z.literal('provisional').optional(),
+                expectedShareVersion: z.number().int().min(0).optional(),
+            })
+        )
+        .output(
+            z.object({
+                success: z.boolean(),
+                shareVersion: z.number(),
+                expectedShareVersionChecked: z.boolean(),
             })
         )
-        .output(z.object({ success: z.boolean(), shareVersion: z.number() }))
         .mutation(async ({ ctx, input }) => {
-            // DID-Auth: use the VP-authenticated DID as the authoritative primaryDid.
-            // The VP is already cryptographically verified by didRoute, so ctx.user.did
-            // is the proven owner of the signing key. We prefer it over input.primaryDid
-            // to avoid DID-method format mismatches (e.g. did:key vs did:web).
             const authenticatedDid = ctx.user.did;
 
-            if (input.primaryDid && input.primaryDid !== authenticatedDid) {
-                console.warn(
-                    `[storeAuthShare] DID format mismatch — VP DID: ${authenticatedDid}, body primaryDid: ${input.primaryDid}. Using VP DID.`
-                );
+            if (input.primaryDid !== authenticatedDid) {
+                throw new TRPCError({
+                    code: 'FORBIDDEN',
+                    message: 'The authenticated DID does not match primaryDid.',
+                });
+            }
+
+            const { contactMethod, authProvider } = await verifyAndGetContactMethod(input);
+            const existing = await findUserKeyByAuthProvider(authProvider.type, authProvider.id);
+
+            if (existing) assertDidOwner(existing, authenticatedDid);
+
+            // Match getAuthShare: null (no record) and authShare-less records mean 0.
+            const currentVersion = existing?.authShare ? (existing.shareVersion ?? 1) : 0;
+            if (
+                input.expectedShareVersion !== undefined &&
+                input.expectedShareVersion !== currentVersion
+            ) {
+                throw new TRPCError({
+                    code: 'CONFLICT',
+                    message: 'Key material changed; please retry',
+                });
             }
 
-            const { user, contactMethod } = await verifyAndGetContactMethod(input);
+            const isMigration = existing?.keyProvider === 'web3auth';
+            const shouldRemainProvisional =
+                !existing || isMigration || existing.sssActivationState === 'provisional';
+            const provisionalCreatedAt = shouldRemainProvisional
+                ? (existing?.provisionalCreatedAt ?? new Date())
+                : undefined;
 
             // Encrypt the auth share at rest using the server SEED
             const seed = environment.SEED;
@@ -213,18 +790,42 @@ export const keysRouter = t.router({
 
             const authShareToStore = encryptAuthShare(input.authShare, seed);
 
-            const updatedDoc = await upsertUserKey(contactMethod, {
-                authShare: authShareToStore,
-                primaryDid: authenticatedDid,
-                securityLevel: input.securityLevel ?? 'basic',
-                keyProvider: input.keyProvider ?? 'sss',
-                authProviders: [{ type: input.providerType, id: user.id }],
-            });
+            let updatedDoc: MongoUserKeyType;
 
-            return { success: true, shareVersion: updatedDoc.shareVersion ?? 1 };
+            try {
+                updatedDoc = await upsertUserKeyByAuthProvider(
+                    contactMethod,
+                    authProvider,
+                    {
+                        authShare: authShareToStore,
+                        primaryDid: authenticatedDid,
+                        securityLevel: input.securityLevel ?? 'basic',
+                        keyProvider: isMigration ? 'web3auth' : (existing?.keyProvider ?? 'sss'),
+                        sssActivationState: shouldRemainProvisional ? 'provisional' : 'active',
+                        ...(provisionalCreatedAt ? { provisionalCreatedAt } : {}),
+                    },
+                    // Legacy clients keep server-observed CAS; first inserts stay unconditional.
+                    input.expectedShareVersion ?? (existing ? currentVersion : undefined)
+                );
+            } catch (error) {
+                if (error instanceof UserKeyVersionConflictError) {
+                    throw new TRPCError({
+                        code: 'CONFLICT',
+                        message: 'Key material changed; please retry',
+                    });
+                }
+
+                throw error;
+            }
+
+            return {
+                success: true,
+                shareVersion: updatedDoc.shareVersion ?? 1,
+                expectedShareVersionChecked: input.expectedShareVersion !== undefined,
+            };
         }),
 
-    addRecoveryMethod: didRoute
+    addRecoveryMethod: didAndChallengeRoute
         .meta({
             openapi: {
                 method: 'POST',
@@ -235,7 +836,7 @@ export const keysRouter = t.router({
         })
         .input(
             AuthInputValidator.extend({
-                type: z.enum(['passkey', 'backup', 'phrase', 'email']),
+                type: RecoveryMethodTypeValidator,
                 encryptedShare: EncryptedShareValidator.optional(),
                 credentialId: z.string().optional(),
                 shareVersion: z.number().optional(),
@@ -243,36 +844,198 @@ export const keysRouter = t.router({
         )
         .output(z.object({ success: z.boolean() }))
         .mutation(async ({ ctx, input }) => {
-            const { contactMethod } = await verifyAndGetContactMethod(input);
+            const { authProvider } = await verifyAndGetContactMethod(input);
+            const userKey = await requireUserKey(authProvider);
 
-            const userKey = await findUserKeyByContactMethod(contactMethod);
-            if (!userKey) {
+            assertDidOwner(userKey, ctx.user.did);
+
+            if (input.type === 'escrow') {
                 throw new TRPCError({
-                    code: 'NOT_FOUND',
-                    message: 'User key not found. Set up SSS first.',
+                    code: 'BAD_REQUEST',
+                    message: 'Use the automatic recovery enrollment endpoint.',
                 });
             }
 
-            // DID-Auth: warn on DID format mismatch but proceed — the VP is
-            // already cryptographically verified, and format differences (did:key
-            // vs did:web for the same underlying key) are expected.
-            if (userKey.primaryDid && ctx.user.did !== userKey.primaryDid) {
-                console.warn(
-                    `[addRecoveryMethod] DID format mismatch — VP DID: ${ctx.user.did}, stored primaryDid: ${userKey.primaryDid}. Proceeding (VP is verified).`
-                );
+            // Confirmation only accepts pending methods at the current version.
+            const shareVersion = userKey.shareVersion ?? 1;
+            if (input.shareVersion !== undefined && input.shareVersion !== shareVersion) {
+                throw new TRPCError({
+                    code: 'CONFLICT',
+                    message: 'Key material changed; please retry',
+                });
             }
 
-            await addRecoveryMethodToUserKey(contactMethod, {
+            await addRecoveryMethodToUserKeyByAuthProvider(authProvider, {
                 type: input.type,
                 createdAt: new Date(),
+                confirmationStatus: 'pending',
                 credentialId: input.credentialId,
                 encryptedShare: input.encryptedShare,
-                shareVersion: input.shareVersion,
+                shareVersion,
             });
 
             return { success: true };
         }),
 
+    confirmRecoveryMethod: didAndChallengeRoute
+        .meta({
+            openapi: {
+                method: 'POST',
+                path: '/keys/recovery/confirm',
+                tags: ['Keys'],
+                summary: 'Confirm receipt of a pending recovery method',
+            },
+        })
+        .input(
+            AuthInputValidator.extend({
+                type: RecoveryMethodTypeValidator,
+                credentialId: z.string().optional(),
+                code: z.string().length(6).optional(),
+            })
+        )
+        .output(z.object({ success: z.boolean() }))
+        .mutation(async ({ ctx, input }) => {
+            const { authProvider } = await verifyAndGetContactMethod(input);
+            const userKey = await requireUserKey(authProvider);
+
+            assertDidOwner(userKey, ctx.user.did);
+
+            if (input.type === 'escrow') {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'Use /keys/escrow to manage automatic recovery.',
+                });
+            }
+            const shareVersion = userKey.shareVersion ?? 1;
+            const pendingMethod = (userKey.recoveryMethods ?? []).find(method => {
+                if (
+                    method.type !== input.type ||
+                    method.shareVersion !== shareVersion ||
+                    method.confirmationStatus !== 'pending'
+                ) {
+                    return false;
+                }
+
+                return input.type !== 'passkey' || method.credentialId === input.credentialId;
+            });
+
+            if (!pendingMethod) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'No pending recovery method was found. Please set it up again.',
+                });
+            }
+
+            let confirmedEmail: string | undefined;
+
+            if (input.type === 'email') {
+                if (!input.code || !pendingMethod.confirmationCodeHash) {
+                    throw new TRPCError({
+                        code: 'BAD_REQUEST',
+                        message: 'Enter the confirmation code from your recovery email.',
+                    });
+                }
+
+                const attempts = pendingMethod.confirmationAttempts ?? 0;
+
+                if (attempts >= MAX_RECOVERY_METHOD_CONFIRMATION_ATTEMPTS) {
+                    throw new TRPCError({
+                        code: 'TOO_MANY_REQUESTS',
+                        message:
+                            'Too many incorrect attempts. Send a new recovery key to try again.',
+                    });
+                }
+
+                if (
+                    !pendingMethod.confirmationCodeExpiresAt ||
+                    pendingMethod.confirmationCodeExpiresAt.getTime() <= Date.now()
+                ) {
+                    throw new TRPCError({
+                        code: 'BAD_REQUEST',
+                        message: 'This confirmation code has expired. Send a new recovery key.',
+                    });
+                }
+
+                if (!confirmationCodeMatches(input.code, pendingMethod.confirmationCodeHash)) {
+                    await incrementRecoveryConfirmationAttemptsByAuthProvider(
+                        authProvider,
+                        shareVersion
+                    );
+
+                    if (attempts + 1 >= MAX_RECOVERY_METHOD_CONFIRMATION_ATTEMPTS) {
+                        throw new TRPCError({
+                            code: 'TOO_MANY_REQUESTS',
+                            message:
+                                'Too many incorrect attempts. Send a new recovery key to try again.',
+                        });
+                    }
+
+                    throw new TRPCError({
+                        code: 'BAD_REQUEST',
+                        message: 'Incorrect confirmation code. Please try again.',
+                    });
+                }
+
+                confirmedEmail = pendingMethod.confirmationEmail;
+            }
+
+            const confirmed = await confirmRecoveryMethodByAuthProvider(
+                authProvider,
+                input.type,
+                shareVersion,
+                input.credentialId
+            );
+
+            if (!confirmed) {
+                throw new TRPCError({
+                    code: 'CONFLICT',
+                    message: 'Recovery setup changed before it was confirmed. Please try again.',
+                });
+            }
+
+            if (confirmedEmail) {
+                await setRecoveryEmailByAuthProvider(authProvider, confirmedEmail);
+            }
+
+            return { success: true };
+        }),
+
+    deleteRecoveryMethod: didAndChallengeRoute
+        .meta({
+            openapi: {
+                method: 'DELETE',
+                path: '/keys/recovery',
+                tags: ['Keys'],
+                summary: 'Delete a recovery method for an authenticated user',
+            },
+        })
+        .input(
+            AuthInputValidator.extend({
+                type: RecoveryMethodTypeValidator,
+                credentialId: z.string().optional(),
+            })
+        )
+        .output(z.object({ success: z.boolean() }))
+        .mutation(async ({ ctx, input }) => {
+            const { authProvider } = await verifyAndGetContactMethod(input);
+            const userKey = await requireUserKey(authProvider);
+
+            assertDidOwner(userKey, ctx.user.did);
+            if (input.type === 'escrow') {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'Use /keys/escrow to manage automatic recovery.',
+                });
+            }
+            await removeRecoveryMethodFromUserKeyByAuthProvider(
+                authProvider,
+                input.type,
+                input.credentialId
+            );
+
+            return { success: true };
+        }),
+
     getRecoveryShare: openRoute
         .meta({
             openapi: {
@@ -283,8 +1046,16 @@ export const keysRouter = t.router({
             },
         })
         .input(
-            AuthInputValidator.extend({
-                type: z.enum(['passkey', 'backup', 'phrase', 'email']),
+            // P0-4: authToken is optional here — this GET route's query
+            // string must not carry it (proxy/ALB access logs). Raw-fetch
+            // callers (sss-key-manager) send it as an X-Auth-Token header,
+            // read from ctx.providerToken below; native tRPC callers that
+            // still pass it as input (e.g. lca-api-plugin, whose batch link
+            // always POSTs — never a URL leak) keep working unchanged.
+            z.object({
+                authToken: z.string().optional(),
+                providerType: AuthProviderTypeValidator,
+                type: RecoveryMethodTypeValidator,
                 credentialId: z.string().optional(),
             })
         )
@@ -296,16 +1067,20 @@ export const keysRouter = t.router({
                 })
                 .nullable()
         )
-        .query(async ({ input }) => {
-            const { contactMethod } = await verifyAndGetContactMethod(input);
+        .query(async ({ input, ctx }) => {
+            const { authProvider } = await verifyAndGetContactMethod({
+                authToken: input.authToken || ctx.providerToken || '',
+                providerType: input.providerType,
+            });
 
-            const userKey = await findUserKeyByContactMethod(contactMethod);
+            const userKey = await findUserKeyByAuthProvider(authProvider.type, authProvider.id);
             if (!userKey) {
                 return null;
             }
 
             const recoveryMethod = (userKey.recoveryMethods ?? []).find(rm => {
                 if (rm.type !== input.type) return false;
+                if (!isRecoveryMethodConfirmed(userKey, rm)) return false;
                 if (input.type === 'passkey' && input.credentialId) {
                     return rm.credentialId === input.credentialId;
                 }
@@ -313,6 +1088,7 @@ export const keysRouter = t.router({
             });
 
             if (!recoveryMethod) return null;
+            if (input.type === 'escrow') return { shareVersion: recoveryMethod.shareVersion };
 
             return {
                 encryptedShare: recoveryMethod.encryptedShare ?? undefined,
@@ -320,7 +1096,7 @@ export const keysRouter = t.router({
             };
         }),
 
-    markMigrated: didRoute
+    markMigrated: didAndChallengeRoute
         .meta({
             openapi: {
                 method: 'POST',
@@ -332,24 +1108,83 @@ export const keysRouter = t.router({
         .input(AuthInputValidator)
         .output(z.object({ success: z.boolean() }))
         .mutation(async ({ ctx, input }) => {
-            const { contactMethod } = await verifyAndGetContactMethod(input);
+            const { authProvider } = await verifyAndGetContactMethod(input);
+            const userKey = await requireUserKey(authProvider);
 
-            const userKey = await findUserKeyByContactMethod(contactMethod);
+            assertDidOwner(userKey, ctx.user.did);
 
-            if (userKey?.primaryDid && ctx.user.did !== userKey.primaryDid) {
-                console.warn(
-                    `[markMigrated] DID format mismatch — VP DID: ${ctx.user.did}, stored primaryDid: ${userKey.primaryDid}. Proceeding (VP is verified).`
-                );
+            // storeAuthShare creates a provisional SSS record when a legacy user
+            // has no prior UserKey. Record migration provenance for that case too.
+            if (
+                userKey.keyProvider !== 'web3auth' &&
+                userKey.sssActivationState !== 'provisional'
+            ) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'This key record is not eligible for migration.',
+                });
             }
 
-            await markUserKeyMigrated(contactMethod);
+            const marked = await markUserKeyMigrationProvisionalByAuthProvider(
+                authProvider,
+                userKey.provisionalCreatedAt ?? new Date()
+            );
+            if (!marked) {
+                throw new TRPCError({
+                    code: 'CONFLICT',
+                    message: 'The key record changed before migration. Please try again.',
+                });
+            }
+
+            return { success: true };
+        }),
+
+    activate: didAndChallengeRoute
+        .meta({
+            openapi: {
+                method: 'POST',
+                path: '/keys/activate',
+                tags: ['Keys'],
+                summary: 'Activate provisioned SSS shares after recovery enrollment',
+            },
+        })
+        .input(AuthInputValidator)
+        .output(z.object({ success: z.boolean() }))
+        .mutation(async ({ ctx, input }) => {
+            const { authProvider } = await verifyAndGetContactMethod(input);
+            const userKey = await requireUserKey(authProvider);
+
+            assertDidOwner(userKey, ctx.user.did);
+
+            if (
+                userKey.sssActivationState !== 'provisional' ||
+                !hasActivatableRecoveryMethod(userKey)
+            ) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'A recovery method for the current key version is required.',
+                });
+            }
+
+            const activated = await activateUserKeyByAuthProvider(
+                authProvider,
+                userKey.shareVersion ?? 1,
+                userKey.keyProvider === 'web3auth'
+            );
+
+            if (!activated) {
+                throw new TRPCError({
+                    code: 'CONFLICT',
+                    message: 'The key record changed before activation. Please try again.',
+                });
+            }
 
             return { success: true };
         }),
 
     // ── Recovery email verification ─────────────────────────────
 
-    addRecoveryEmail: didRoute
+    addRecoveryEmail: didAndChallengeRoute
         .meta({
             openapi: {
                 method: 'POST',
@@ -365,15 +1200,10 @@ export const keysRouter = t.router({
         )
         .output(z.object({ success: z.boolean() }))
         .mutation(async ({ input, ctx }) => {
-            const { contactMethod } = await verifyAndGetContactMethod(input);
+            const { authProvider } = await verifyAndGetContactMethod(input);
+            const userKey = await requireUserKey(authProvider);
 
-            const userKey = await findUserKeyByContactMethod(contactMethod);
-            if (!userKey) {
-                throw new TRPCError({
-                    code: 'NOT_FOUND',
-                    message: 'User key not found. Set up SSS first.',
-                });
-            }
+            assertDidOwner(userKey, ctx.user.did);
 
             // Prevent using the primary login email as the recovery email
             if (
@@ -387,7 +1217,7 @@ export const keysRouter = t.router({
             }
 
             const code = generate6DigitCode();
-            const cacheKey = `${RECOVERY_EMAIL_CODE_PREFIX}${contactMethod.type}:${contactMethod.value}`;
+            const cacheKey = `${RECOVERY_EMAIL_CODE_PREFIX}${authProvider.type}:${authProvider.id}`;
 
             // Store: code + target email so verify can confirm both
             await cache.set(
@@ -396,6 +1226,11 @@ export const keysRouter = t.router({
                 RECOVERY_EMAIL_CODE_TTL_SECS
             );
 
+            // Clear the verification attempt counter so user can try the new code
+            await clearRateLimit(
+                `recovery-verify-attempts:${authProvider.type}:${authProvider.id}`
+            );
+
             try {
                 // Always render locally via @learncard/email-templates for
                 // tenant-branded output. Falls back to the 'recovery-email-code'
@@ -422,7 +1257,7 @@ export const keysRouter = t.router({
             return { success: true };
         }),
 
-    verifyRecoveryEmail: didRoute
+    verifyRecoveryEmail: didAndChallengeRoute
         .meta({
             openapi: {
                 method: 'POST',
@@ -437,18 +1272,31 @@ export const keysRouter = t.router({
             })
         )
         .output(z.object({ success: z.boolean(), maskedEmail: z.string() }))
-        .mutation(async ({ input }) => {
-            const { contactMethod } = await verifyAndGetContactMethod(input);
+        .mutation(async ({ input, ctx }) => {
+            const { authProvider } = await verifyAndGetContactMethod(input);
+            const userKey = await requireUserKey(authProvider, 'User key not found.');
 
-            const userKey = await findUserKeyByContactMethod(contactMethod);
-            if (!userKey) {
+            assertDidOwner(userKey, ctx.user.did);
+
+            const cacheKey = `${RECOVERY_EMAIL_CODE_PREFIX}${authProvider.type}:${authProvider.id}`;
+            const attemptKey = `recovery-verify-attempts:${authProvider.type}:${authProvider.id}`;
+
+            // Check rate limit (5 failed attempts per auth provider identity within code TTL)
+            const allowed = await checkRateLimit(
+                attemptKey,
+                RECOVERY_VERIFY_MAX_ATTEMPTS,
+                RECOVERY_EMAIL_CODE_TTL_SECS
+            );
+
+            if (!allowed) {
+                // On exceeding limit, delete the pending recovery code
+                await cache.delete([cacheKey]);
                 throw new TRPCError({
-                    code: 'NOT_FOUND',
-                    message: 'User key not found.',
+                    code: 'TOO_MANY_REQUESTS',
+                    message: 'Too many attempts. Please resend code.',
                 });
             }
 
-            const cacheKey = `${RECOVERY_EMAIL_CODE_PREFIX}${contactMethod.type}:${contactMethod.value}`;
             const raw = await cache.get(cacheKey);
 
             if (!raw) {
@@ -461,6 +1309,7 @@ export const keysRouter = t.router({
             const { code: storedCode, email } = JSON.parse(raw) as { code: string; email: string };
 
             if (input.code !== storedCode) {
+                // Failed attempt — rate limit counter already incremented above
                 throw new TRPCError({
                     code: 'BAD_REQUEST',
                     message: 'Incorrect code. Please try again.',
@@ -469,7 +1318,8 @@ export const keysRouter = t.router({
 
             // Code is valid — consume it and store the verified recovery email
             await cache.delete([cacheKey]);
-            await setRecoveryEmail(contactMethod, email);
+            await clearRateLimit(attemptKey);
+            await setRecoveryEmailByAuthProvider(authProvider, email);
 
             return { success: true, maskedEmail: maskEmail(email) };
         }),
@@ -486,9 +1336,8 @@ export const keysRouter = t.router({
         .input(AuthInputValidator)
         .output(z.object({ recoveryEmail: z.string().nullable() }))
         .query(async ({ input }) => {
-            const { contactMethod } = await verifyAndGetContactMethod(input);
-
-            const userKey = await findUserKeyByContactMethod(contactMethod);
+            const { authProvider } = await verifyAndGetContactMethod(input);
+            const userKey = await findUserKeyByAuthProvider(authProvider.type, authProvider.id);
             if (!userKey) {
                 return { recoveryEmail: null };
             }
@@ -498,79 +1347,80 @@ export const keysRouter = t.router({
             };
         }),
 
-    sendEmailBackup: openRoute
+    sendEmailBackup: didAndChallengeRoute
         .meta({
             openapi: {
                 method: 'POST',
                 path: '/keys/email-backup',
                 tags: ['Keys'],
-                summary:
-                    'Send email backup share to the authenticated user (fire-and-forget relay, share is NEVER persisted)',
+                summary: 'Send a recovery key and confirmation code to a recovery email',
             },
         })
         .input(
             AuthInputValidator.extend({
-                emailShare: z.string().min(1),
-                // Provide either an explicit email OR set useRecoveryEmail to
-                // use the verified recovery email stored on the UserKey.
-                email: z.string().email().optional(),
-                useRecoveryEmail: z.boolean().optional(),
-            })
+                relayPayload: EmailRelayEnvelopeValidator,
+                confirmationCode: z.string().regex(/^\d{6}$/),
+                email: z.string().email(),
+                shareVersion: z.number().int().positive().optional(),
+            }).strict()
         )
         .output(z.object({ success: z.boolean() }))
         .mutation(async ({ input, ctx }) => {
-            // Verify the caller is authenticated
-            const { contactMethod } = await verifyAndGetContactMethod(input);
-
-            let targetEmail = input.email;
-
-            // When useRecoveryEmail is set, look up the stored recovery email
-            if (input.useRecoveryEmail && !targetEmail) {
-                const userKey = await findUserKeyByContactMethod(contactMethod);
+            const { authProvider } = await verifyAndGetContactMethod(input);
+            const userKey = await requireUserKey(authProvider);
 
-                targetEmail = userKey?.recoveryEmail;
+            assertDidOwner(userKey, ctx.user.did);
 
-                if (!targetEmail) {
-                    throw new TRPCError({
-                        code: 'BAD_REQUEST',
-                        message: 'No verified recovery email on file.',
-                    });
-                }
+            if (!userKey.recoveryEmail || !userKey.recoveryEmailVerifiedAt) {
+                throw new TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: 'No verified recovery email on file.',
+                });
             }
 
-            if (!targetEmail) {
+            const targetEmail = input.email.trim().toLowerCase();
+
+            if (
+                userKey.recoveryEmail.toLowerCase() !== targetEmail ||
+                (userKey.contactMethod.type === 'email' &&
+                    userKey.contactMethod.value.toLowerCase() === targetEmail)
+            ) {
                 throw new TRPCError({
                     code: 'BAD_REQUEST',
-                    message: 'An email address or useRecoveryEmail flag is required.',
+                    message: 'Use the verified recovery email for this account.',
                 });
             }
 
-            // IMPORTANT: The emailShare is NEVER written to the database.
-            // It is only held in memory for the duration of this request.
-            const brandName =
-                ctx.tenant?.emailBranding?.brandName ||
-                environment.POSTMARK_BRAND_NAME ||
-                'LearnCard';
+            const now = new Date();
 
-            try {
-                // Always render locally via @learncard/email-templates for
-                // tenant-branded output. Falls back to the 'recovery-key'
-                // sentinel when no Postmark alias is configured.
-                await getDeliveryService().send({
-                    to: targetEmail,
-                    templateAlias: RECOVERY_KEY_TEMPLATE_ALIAS || 'recovery-key',
-                    templateModel: {
-                        brandName,
-                        recoveryKey: input.emailShare,
-                    },
-                    branding: ctx.tenant?.emailBranding,
-                    from: getFrom({ mailbox: 'recovery', branding: ctx.tenant?.emailBranding }),
+            // Older clients omit the version; preserve their current-version fallback.
+            // Even retained historical versions cannot be confirmed for new recovery setup.
+            const shareVersion = userKey.shareVersion ?? 1;
+            if (input.shareVersion !== undefined && input.shareVersion !== shareVersion) {
+                throw new TRPCError({
+                    code: 'CONFLICT',
+                    message: 'Key material changed; please retry',
                 });
-            } catch (emailError) {
-                // Non-fatal: log but still return success so the client doesn't retry
-                console.error('[email-backup] Failed to send backup share email:', emailError);
             }
 
+            // lca-api deliberately cannot decrypt this payload. The isolated
+            // relay verifies that its encrypted recipient matches this
+            // server-verified address before sending.
+            await sendRecoveryKeyToEscrowRelay(input.relayPayload, targetEmail);
+
+            await addRecoveryMethodToUserKeyByAuthProvider(authProvider, {
+                type: 'email',
+                createdAt: now,
+                confirmationStatus: 'pending',
+                shareVersion,
+                confirmationCodeHash: hashRecoveryConfirmationCode(input.confirmationCode),
+                confirmationCodeExpiresAt: new Date(
+                    now.getTime() + RECOVERY_METHOD_CONFIRMATION_TTL_MS
+                ),
+                confirmationAttempts: 0,
+                confirmationEmail: targetEmail,
+            });
+
             return { success: true };
         }),
 
@@ -618,27 +1468,23 @@ export const keysRouter = t.router({
 
             // 2. Verify the old UserKey exists
             const oldContactMethod: ContactMethod = { type: 'phone', value: input.previousPhone };
-            const existingKey = await findUserKeyByContactMethod(oldContactMethod);
+            const authProvider: AuthProviderMapping = {
+                type: input.providerType,
+                id: user.id,
+            };
+            const existingKey = await findUserKeyByAuthProvider(authProvider.type, authProvider.id);
 
-            if (!existingKey) {
+            if (
+                !existingKey ||
+                existingKey.contactMethod.type !== oldContactMethod.type ||
+                existingKey.contactMethod.value !== oldContactMethod.value
+            ) {
                 throw new TRPCError({
                     code: 'NOT_FOUND',
                     message: 'No account found for the provided phone number.',
                 });
             }
 
-            // 3. Verify the authenticated user owns this UserKey
-            const ownsKey = existingKey.authProviders.some(
-                ap => ap.type === input.providerType && ap.id === user.id
-            );
-
-            if (!ownsKey) {
-                throw new TRPCError({
-                    code: 'FORBIDDEN',
-                    message: 'You do not have permission to upgrade this account.',
-                });
-            }
-
             // 4. Link the email to the auth account (passwordless, via Admin SDK)
             //    This invalidates the client's existing session, so we issue a
             //    fresh custom token for the client to re-authenticate with.
@@ -675,7 +1521,11 @@ export const keysRouter = t.router({
 
             // 5. Atomically upgrade the UserKey contact method
             const newContactMethod: ContactMethod = { type: 'email', value: email };
-            const upgraded = await upgradeContactMethod(oldContactMethod, newContactMethod);
+            const upgraded = await upgradeContactMethodByAuthProvider(
+                authProvider,
+                oldContactMethod,
+                newContactMethod
+            );
 
             if (!upgraded) {
                 throw new TRPCError({
@@ -687,7 +1537,7 @@ export const keysRouter = t.router({
             return { success: true, customToken };
         }),
 
-    deleteUserKey: didRoute
+    deleteUserKey: didAndChallengeRoute
         .meta({
             openapi: {
                 method: 'POST',
@@ -696,20 +1546,18 @@ export const keysRouter = t.router({
                 summary: 'Delete user key and all associated data',
             },
         })
-        .input(AuthInputValidator)
+        .input(
+            AuthInputValidator.extend({
+                challenge: z.string().min(1),
+            })
+        )
         .output(z.object({ success: z.boolean() }))
         .mutation(async ({ ctx, input }) => {
-            const { contactMethod } = await verifyAndGetContactMethod(input);
-
-            const userKey = await findUserKeyByContactMethod(contactMethod);
-
-            if (userKey?.primaryDid && ctx.user.did !== userKey.primaryDid) {
-                console.warn(
-                    `[deleteUserKey] DID format mismatch — VP DID: ${ctx.user.did}, stored primaryDid: ${userKey.primaryDid}. Proceeding (VP is verified).`
-                );
-            }
+            const { authProvider } = await verifyAndGetContactMethod(input);
+            const userKey = await requireUserKey(authProvider);
 
-            await deleteUserKey(contactMethod);
+            assertDidOwner(userKey, ctx.user.did);
+            await deleteUserKeyByAuthProvider(authProvider);
 
             return { success: true };
         }),