@learncard/lca-api-service 1.3.1 → 1.4.0

package/src/routes/firebase.test.ts

@@ -0,0 +1,94 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+    environment: { IS_OFFLINE: true, IS_E2E_TEST: false },
+    verifyIdToken: vi.fn(),
+    getDidAuthVp: vi.fn(),
+}));
+
+vi.mock('@environment', () => ({ environment: mocks.environment }));
+vi.mock('@firebase', () => ({ default: undefined }));
+vi.mock('firebase-admin', () => ({
+    default: { auth: () => ({ verifyIdToken: mocks.verifyIdToken }) },
+}));
+vi.mock('@routes', async () => {
+    const { initTRPC } = await import('@trpc/server');
+    const t = initTRPC.create();
+    return { t, openRoute: t.procedure, authorizedDidRoute: t.procedure };
+});
+vi.mock('@helpers/learnCard.helpers', () => ({
+    getDidWebLearnCard: async () => ({ invoke: { getDidAuthVp: mocks.getDidAuthVp } }),
+    getEmptyLearnCard: vi.fn(),
+}));
+vi.mock('@cache', () => ({ default: {} }));
+vi.mock('../services/delivery', () => ({ getDeliveryService: vi.fn(), getFrom: vi.fn() }));
+vi.mock('../helpers/locale.helpers', () => ({ resolveLocaleByEmail: vi.fn() }));
+vi.mock('@helpers/dids.helpers', () => ({ isAuthorizedDID: vi.fn() }));
+
+import { firebaseRouter } from './firebase';
+
+const tokenFor = (claims: Record<string, string>): string =>
+    `e30.${Buffer.from(JSON.stringify({ sub: 'local-user', ...claims })).toString('base64url')}.test`;
+const caller = firebaseRouter.createCaller({} as never);
+
+describe('getProofOfLoginVp', () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+        vi.clearAllMocks();
+        mocks.environment.IS_OFFLINE = true;
+        mocks.environment.IS_E2E_TEST = false;
+        mocks.getDidAuthVp.mockResolvedValue('signed-proof');
+        vi.spyOn(console, 'error').mockImplementation(() => {});
+    });
+
+    it('includes the login email without Firebase Admin credentials in local dev', async () => {
+        await expect(
+            caller.getProofOfLoginVp({ token: tokenFor({ email: 'billy@example.com' }) })
+        ).resolves.toEqual({ success: true, vp: 'signed-proof' });
+        expect(mocks.getDidAuthVp).toHaveBeenCalledWith({
+            proofFormat: 'jwt',
+            challenge: 'proof-of-login:email:billy@example.com',
+        });
+        expect(mocks.verifyIdToken).not.toHaveBeenCalled();
+    });
+
+    it('supports the e2e token path and Firebase phone_number claim', async () => {
+        mocks.environment.IS_OFFLINE = false;
+        mocks.environment.IS_E2E_TEST = true;
+        await caller.getProofOfLoginVp({ token: tokenFor({ phone_number: '+15555550123' }) });
+        expect(mocks.getDidAuthVp).toHaveBeenCalledWith({
+            proofFormat: 'jwt',
+            challenge: 'proof-of-login:phone:+15555550123',
+        });
+    });
+
+    it('does not sign a proof when the token has no contact method', async () => {
+        expect(await caller.getProofOfLoginVp({ token: tokenFor({}) })).toMatchObject({
+            success: false,
+        });
+        expect(mocks.getDidAuthVp).not.toHaveBeenCalled();
+    });
+
+    it('requires Firebase verification outside local and e2e environments', async () => {
+        mocks.environment.IS_OFFLINE = false;
+        mocks.verifyIdToken.mockRejectedValueOnce(new Error('Invalid signature'));
+        expect(
+            await caller.getProofOfLoginVp({ token: tokenFor({ email: 'forged@example.com' }) })
+        ).toMatchObject({ success: false });
+        expect(mocks.verifyIdToken).toHaveBeenCalledOnce();
+        expect(mocks.getDidAuthVp).not.toHaveBeenCalled();
+    });
+
+    it('uses verified claims in production', async () => {
+        mocks.environment.IS_OFFLINE = false;
+        mocks.verifyIdToken.mockResolvedValueOnce({
+            uid: 'real-user',
+            email: 'verified@example.com',
+        });
+        await caller.getProofOfLoginVp({ token: 'firebase-token' });
+        expect(mocks.getDidAuthVp).toHaveBeenCalledWith({
+            proofFormat: 'jwt',
+            challenge: 'proof-of-login:email:verified@example.com',
+        });
+    });
+});

package/src/routes/firebase.ts

@@ -14,12 +14,14 @@ import {
     FirebaseCustomAuthResponseSchema,
 } from '@helpers/firebase.helpers';
 import cache from '@cache';
+import { checkRateLimit, clearRateLimit, decrementRateLimit } from '@helpers/rateLimit.helpers';
 import { TRPCError } from '@trpc/server';
 import { getDeliveryService, getFrom } from '../services/delivery';
 import { resolveLocaleByEmail } from '../helpers/locale.helpers';
 import jwtDecode from 'jwt-decode';
 import { getDidWebLearnCard, getEmptyLearnCard } from '@helpers/learnCard.helpers';
 import { isAuthorizedDID } from '@helpers/dids.helpers';
+import { verifyFirebaseToken, getContactMethodFromUser } from '@helpers/auth.helpers';
 
 const LOGIN_VERIFICATION_CODE_TEMPLATE_ALIAS =
     environment.POSTMARK_LOGIN_CODE_TEMPLATE_ALIAS || 'login-verification-code';
@@ -66,6 +68,11 @@ const CODE_TTL_SECONDS = 5 * 60; // 5 minutes
 const MAX_ATTEMPTS = 6;
 const ATTEMPT_TTL_SECONDS = 5 * 60; // 5 minutes
 
+// Rate limiting for login code verification (brute-force protection)
+const LOGIN_VERIFY_MAX_ATTEMPTS_PER_EMAIL = 5; // max failed attempts per email
+const LOGIN_VERIFY_MAX_ATTEMPTS_PER_IP = 30; // max attempts per IP per window
+const LOGIN_VERIFY_IP_WINDOW_SECONDS = 600; // 10 minutes
+
 export const CONTACT_METHOD_SESSION_PREFIX = 'contact_method_session:';
 
 async function createFirebaseToken(keycloakToken: string): Promise<string> {
@@ -87,10 +94,7 @@ async function createFirebaseToken(keycloakToken: string): Promise<string> {
                 firebaseUser = existingUsers?.users?.[0];
 
                 if (firebaseUser?.uid !== uid) {
-                    console.log(
-                        `⚠️ Existing account found for ${email}, linking Keycloak UID: ${uid}`
-                    );
-
+                    // Link existing account to Keycloak UID
                     await admin.auth().updateUser(firebaseUser.uid, {
                         emailVerified,
                         displayName,
@@ -102,8 +106,6 @@ async function createFirebaseToken(keycloakToken: string): Promise<string> {
         }
 
         if (!firebaseUser) {
-            console.log(`🆕 Creating new Firebase user for ${email} (UID: ${uid})`);
-
             firebaseUser = await admin.auth().createUser({
                 uid,
                 email,
@@ -112,7 +114,7 @@ async function createFirebaseToken(keycloakToken: string): Promise<string> {
             });
         }
     } catch (error) {
-        console.error('Error checking or creating Firebase user:', error);
+        console.error('[createFirebaseToken] Firebase user creation or lookup failed:', error);
         throw new Error('Firebase user creation or lookup failed');
     }
 
@@ -166,7 +168,7 @@ export const firebaseRouter = t.router({
 
                 return { userRecord: formattedUserRecord };
             } catch (error) {
-                console.error('Error fetching firebase user data', error);
+                console.error('[getFirebaseUserByEmail] Failed to fetch user:', error);
                 return { userRecord: null };
             }
         }),
@@ -189,7 +191,7 @@ export const firebaseRouter = t.router({
                 const firebaseToken = await createFirebaseToken(keycloakToken);
                 return { firebaseToken };
             } catch (error) {
-                console.error('Error during Keycloak authentication:', error);
+                console.error('[authenticateWithKeycloak] Authentication failed:', error);
                 throw new Error('Authentication failed');
             }
         }),
@@ -231,7 +233,7 @@ export const firebaseRouter = t.router({
 
                 return response.data ?? null;
             } catch (error) {
-                console.log('Unable to authenticate with Scouts SSO', error);
+                console.error('[authenticateWithScoutsSSO] Authentication failed:', error);
                 throw new TRPCError({
                     code: 'INTERNAL_SERVER_ERROR',
                     message: 'Unable to authenticate with Scouts SSO',
@@ -254,31 +256,32 @@ export const firebaseRouter = t.router({
             const { email, locale } = input;
 
             try {
-                // rate limit attempts (max 3 codes per 10 mins)
-                const attemptKey = `login-attempts:${email}`;
-                const attemptCount = Number(await cache.get(attemptKey)) || 0;
-
-                if (attemptCount >= MAX_ATTEMPTS) {
+                // Atomic rate limit for sending codes (max 3 codes per 10 mins)
+                // Uses new key to avoid collision with legacy un-prefixed keys during rolling deploy
+                const sendAllowed = await checkRateLimit(
+                    `login-send:${email}`,
+                    MAX_ATTEMPTS,
+                    ATTEMPT_TTL_SECONDS
+                );
+                if (!sendAllowed) {
                     return {
                         success: false,
                         error: 'Too many login attempts. Try again in a few minutes.',
                     };
                 }
 
-                await cache.set(attemptKey, attemptCount + 1, ATTEMPT_TTL_SECONDS);
-
-                // clear existing codes for this email (enforce 1 active code at a time)
-                const existingCodeKeys = await cache.keys(`login-code:${email}:*`);
-                if (existingCodeKeys?.length) {
-                    await cache.delete(existingCodeKeys);
-                }
-
                 // generate secure random 6-digit code
                 const code = crypto.randomInt(100000, 999999).toString();
-                const redisKey = `login-code:${email}:${code}`;
 
-                // store code in Redis with 5-min TTL
-                await cache.set(redisKey, '1', CODE_TTL_SECONDS);
+                // Store code in Redis with 5-min TTL
+                // Key structure: login-code:${email} → code value
+                // This replaces any existing code (enforces 1 active code at a time)
+                const loginCodeKey = `login-code:${email}`;
+                await cache.set(loginCodeKey, code, CODE_TTL_SECONDS);
+
+                // Clear the per-email verification attempt counter so user can try the new code
+                // Note: IP counter is NOT cleared here to prevent abuse via email rotation
+                await clearRateLimit(`login-verify-attempts:${email}`);
 
                 // Login is pre-auth, so the client only knows its UI language.
                 // Prefer the account's saved locale (resolved by email via
@@ -305,14 +308,14 @@ export const firebaseRouter = t.router({
                         }),
                     });
                 } catch (error) {
-                    console.error('Failed to send verification email:', error);
+                    console.error('[sendLoginVerificationCode] Failed to send email:', error);
                     return { success: false, error: 'Error sending login verification code' };
                 }
 
                 return { success: true };
-            } catch (err: any) {
-                console.error('Error sending login verification code:', err);
-                return { success: false, error: err.message };
+            } catch (err) {
+                console.error('[sendLoginVerificationCode] Unexpected error:', err);
+                return { success: false, error: 'An error occurred. Please try again.' };
             }
         }),
     verifyLoginCode: openRoute
@@ -334,23 +337,63 @@ export const firebaseRouter = t.router({
                 token: z.string().optional(),
             })
         )
-        .mutation(async ({ input }) => {
+        .mutation(async ({ input, ctx }) => {
             const { email, code } = input;
+            const clientIp = ctx.clientIp ?? 'unknown';
 
-            const redisKey = `login-code:${email}:${code}`;
+            // Rate limit keys
+            const emailAttemptKey = `login-verify-attempts:${email}`;
+            const ipAttemptKey = `login-verify-ip:${clientIp}`;
 
             try {
-                // check if code exists
-                const cached = await cache.get(redisKey);
-                if (!cached) {
+                const loginCodeKey = `login-code:${email}`;
+
+                // Atomic increment + check for IP-based rate limit
+                // This prevents TOCTOU races where concurrent requests could bypass the limit
+                const ipAllowed = await checkRateLimit(
+                    ipAttemptKey,
+                    LOGIN_VERIFY_MAX_ATTEMPTS_PER_IP,
+                    LOGIN_VERIFY_IP_WINDOW_SECONDS
+                );
+                if (!ipAllowed) {
+                    return {
+                        success: false,
+                        error: 'Too many attempts. Please resend code.',
+                    };
+                }
+
+                // Atomic increment + check for per-email rate limit
+                const emailAllowed = await checkRateLimit(
+                    emailAttemptKey,
+                    LOGIN_VERIFY_MAX_ATTEMPTS_PER_EMAIL,
+                    CODE_TTL_SECONDS
+                );
+                if (!emailAllowed) {
+                    // Limit exceeded — invalidate the code
+                    await cache.delete([loginCodeKey]);
+                    return {
+                        success: false,
+                        error: 'Too many attempts. Please resend code.',
+                    };
+                }
+
+                // Check if code exists and matches
+                const storedCode = await cache.get(loginCodeKey);
+
+                if (!storedCode || storedCode !== code) {
+                    // Invalid code — counters already incremented above
                     return { success: false, error: 'Invalid or expired code.' };
                 }
 
-                // delete the code to prevent reuse
-                await cache.delete([redisKey]);
+                // Valid code — delete it to prevent reuse
+                await cache.delete([loginCodeKey]);
+
+                // Clear email counter on success; decrement (not clear) IP counter
+                // so legitimate successes don't accumulate but we don't hand attackers a wipe
+                await clearRateLimit(emailAttemptKey);
+                await decrementRateLimit(ipAttemptKey);
 
-                // get or create the Firebase user
-                console.log('Getting or creating Firebase user...', email);
+                // Get or create the Firebase user
                 let user;
                 try {
                     user = await app?.auth().getUserByEmail(email);
@@ -362,13 +405,13 @@ export const firebaseRouter = t.router({
                     return { success: false, error: 'Unable to find or create user.' };
                 }
 
-                // create Firebase custom auth token
+                // Create Firebase custom auth token
                 const token = await app?.auth().createCustomToken(user.uid);
 
                 return { success: true, token };
             } catch (err: any) {
-                console.error('Error verifying login code:', err);
-                return { success: false, error: err.message };
+                console.error('[verifyLoginCode] Unexpected error:', err);
+                return { success: false, error: 'An error occurred. Please try again.' };
             }
         }),
     verifyNetworkHandoffToken: openRoute
@@ -474,9 +517,9 @@ export const firebaseRouter = t.router({
                 const token = await app?.auth().createCustomToken(user.uid);
 
                 return { success: true, token };
-            } catch (err: any) {
-                console.error('Error verifying login code:', err);
-                return { success: false, error: err.message };
+            } catch (err) {
+                console.error('[verifyNetworkHandoffToken] Unexpected error:', err);
+                return { success: false, error: 'An error occurred. Please try again.' };
             }
         }),
     getProofOfLoginVp: openRoute
@@ -501,16 +544,16 @@ export const firebaseRouter = t.router({
             const { token } = input;
 
             try {
-                const decodedToken = await app?.auth().verifyIdToken(token);
+                // Match sign-in's local/e2e token handling while retaining Firebase
+                // verification outside those environments.
+                const user = await verifyFirebaseToken(token);
+                const contactMethod = getContactMethodFromUser(user);
+                if (!contactMethod) {
+                    throw new Error('Login token does not contain an email or phone number');
+                }
 
                 const learnCard = await getDidWebLearnCard();
-
-                let proofOfLoginChallenge = 'proof-of-login:';
-                if (decodedToken?.email) {
-                    proofOfLoginChallenge += 'email:' + decodedToken?.email;
-                } else if (decodedToken?.phoneNumber) {
-                    proofOfLoginChallenge += 'phone:' + decodedToken?.phoneNumber;
-                }
+                const proofOfLoginChallenge = `proof-of-login:${contactMethod.type}:${contactMethod.value}`;
 
                 const result = await learnCard.invoke.getDidAuthVp({
                     proofFormat: 'jwt',
@@ -520,9 +563,9 @@ export const firebaseRouter = t.router({
                 if (typeof result !== 'string') throw new Error('Error getting DID-Auth-JWT!');
 
                 return { success: true, vp: result };
-            } catch (err: any) {
-                console.error('Error verifying login code:', err);
-                return { success: false, error: err.message };
+            } catch (err) {
+                console.error('[getProofOfLoginVp] Unexpected error:', err);
+                return { success: false, error: 'An error occurred. Please try again.' };
             }
         }),
 });

package/src/routes/index.ts

@@ -12,7 +12,8 @@ import type { IncomingMessage, ServerResponse } from 'node:http';
 import { resolveTenantFromRequest, type ResolvedTenant } from '@learncard/email-templates';
 
 import { getEmptyLearnCard } from '@helpers/learnCard.helpers';
-import { invalidateChallengeForDid, isChallengeValidForDid } from '@cache/challenges';
+import { consumeChallengeForDid } from '@cache/challenges';
+import { isEscrowEnabled } from '../services/escrow-enclave';
 
 export type DidAuthVP = {
     iss: string;
@@ -34,6 +35,13 @@ export type Context = {
     tenant: ResolvedTenant;
     debug?: boolean;
     clientIp?: string;
+    // Value of the X-Auth-Token header — a caller's own provider token
+    // (e.g. a Firebase ID token), distinct from the Authorization header
+    // (reserved for the DID-Auth VP). Lets GET routes that verify a
+    // provider token (e.g. keys.getRecoveryShare, P0-4) read it without
+    // putting it in a query string, without colliding with clients that
+    // send a DID-Auth VP as Authorization for the same route.
+    providerToken?: string;
 };
 
 export const t = initTRPC.context<Context>().meta<OpenApiMeta>().create();
@@ -49,6 +57,13 @@ export const createContext = async (
     const domainName = 'requestContext' in event ? event.requestContext.domainName : '';
     const debug = environment.NODE_ENV === 'test';
 
+    // See Context.providerToken — a separate header from Authorization,
+    // which is reserved for the DID-Auth VP handled below.
+    const providerTokenHeader = (event.headers as Record<string, string | undefined>)[
+        'x-auth-token'
+    ];
+    const providerToken = providerTokenHeader || undefined;
+
     const domain =
         !domainName || environment.IS_OFFLINE
             ? `localhost%3A${environment.PORT || 3000}`
@@ -116,10 +131,10 @@ export const createContext = async (
                             tenant,
                             debug,
                             clientIp,
+                            providerToken,
                         };
 
-                    const cacheResponse = await isChallengeValidForDid(did, challenge);
-                    await invalidateChallengeForDid(did, challenge);
+                    const cacheResponse = await consumeChallengeForDid(did, challenge);
 
                     return {
                         user: { did, isChallengeValid: Boolean(cacheResponse), authorizedDid },
@@ -127,6 +142,7 @@ export const createContext = async (
                         tenant,
                         debug,
                         clientIp,
+                        providerToken,
                     };
                 }
             }
@@ -135,15 +151,92 @@ export const createContext = async (
         console.error(e);
     }
 
-    return { domain, tenant, clientIp };
+    return { domain, tenant, clientIp, providerToken };
+};
+
+// ---------------------------------------------------------------------------
+// P0-4: Secret leakage — telemetry
+// ---------------------------------------------------------------------------
+//
+// /keys/* inputs carry Firebase auth tokens, encrypted/plaintext key shares,
+// and recovery artifacts. `attachRpcInput` is disabled below (globally, since
+// this middleware chain is shared by every router — see app.ts) so Sentry
+// never receives raw tRPC input. The event processor further down is
+// defense-in-depth: even if input attachment is ever re-enabled upstream, or
+// another integration attaches a raw payload to an event for a /keys/*
+// request, this strips anything secret-shaped before it can leave the
+// process.
+const SECRET_FIELD_RE =
+    /share|token|seed|recoverykey|blob|envelope|sealed|ephemeral|resumetoken|pinproof|pinverifier/i;
+
+/**
+ * Recursively replaces values whose key matches SECRET_FIELD_RE with
+ * '[Redacted]'. Guards against circular references and caps recursion depth.
+ * Exported for unit testing.
+ */
+export const redactSecretFields = (
+    value: unknown,
+    depth = 0,
+    seen: Set<object> = new Set()
+): unknown => {
+    if (depth > 10 || value === null || value === undefined) return value;
+
+    if (Array.isArray(value)) {
+        if (seen.has(value)) return '[Circular]';
+        seen.add(value);
+        return value.map(item => redactSecretFields(item, depth + 1, seen));
+    }
+
+    if (typeof value === 'object') {
+        if (seen.has(value)) return '[Circular]';
+        seen.add(value);
+        return Object.fromEntries(
+            Object.entries(value as Record<string, unknown>).map(([key, val]) => [
+                key,
+                SECRET_FIELD_RE.test(key) ? '[Redacted]' : redactSecretFields(val, depth + 1, seen),
+            ])
+        );
+    }
+
+    return value;
 };
 
+const sentryTrpcMiddleware = Sentry.Handlers.trpcMiddleware({ attachRpcInput: false });
+
 export const openRoute = t.procedure
-    .use(t.middleware(Sentry.Handlers.trpcMiddleware({ attachRpcInput: true }) as any))
+    .use(
+        t.middleware(({ path, type, next, getRawInput }) =>
+            sentryTrpcMiddleware({ path, type, next, rawInput: getRawInput })
+        )
+    )
     .use(({ ctx, next, path }) => {
         Sentry.configureScope(scope => {
             scope.setTransactionName(`trpc-${path}`);
+
+            if (path.startsWith('keys.') || path.startsWith('escrow.')) {
+                scope.addEventProcessor(event => {
+                    if (event.contexts) {
+                        event.contexts = redactSecretFields(
+                            event.contexts
+                        ) as typeof event.contexts;
+                    }
+                    if (event.extra) {
+                        event.extra = redactSecretFields(event.extra) as typeof event.extra;
+                    }
+                    if (event.request?.data) {
+                        event.request.data = redactSecretFields(event.request.data);
+                    }
+                    return event;
+                });
+            }
         });
+        // Gate escrow before input parsing and DID authorization, including when disabled.
+        if (path.startsWith('escrow.') && !isEscrowEnabled()) {
+            throw new TRPCError({
+                code: 'PRECONDITION_FAILED',
+                message: 'Escrow recovery is not available.',
+            });
+        }
         return next({ ctx });
     });