@learncard/lca-api-service 1.4.0 → 1.5.0

package/src/config/serverlessFunctionEnv.test.ts

@@ -0,0 +1,98 @@
+import { createRequire } from 'node:module';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const require = createRequire(import.meta.url);
+const functions: {
+    api: () => Record<string, string>;
+    oidc: () => Record<string, string>;
+    provider: (context?: {
+        options: { stage: string; httpPort?: string };
+    }) => Record<string, unknown>;
+} = require('../../serverless.function-env.cjs');
+
+beforeEach(() => {
+    vi.stubEnv('RUNTIME_SECRETS_ID', '');
+    vi.stubEnv('SEED', 'seed');
+    vi.stubEnv('GOOGLE_APPLICATION_CREDENTIAL', 'credential');
+    vi.stubEnv('OIDC_CLIENT_SECRET', 'broker-secret');
+    vi.stubEnv('OIDC_REDIRECT_URIS', 'https://example.com/callback');
+});
+afterEach(() => vi.unstubAllEnvs());
+
+describe('lca-api serverless function environments', () => {
+    it('omits all fallback credentials in bundle mode', () => {
+        vi.stubEnv('RUNTIME_SECRETS_ID', 'lca-api/dev/runtime-secrets');
+        expect(functions.api()).toEqual({ RUNTIME_SECRETS_ID: 'lca-api/dev/runtime-secrets' });
+        expect(Object.keys(functions.provider()).sort()).toEqual([
+            'CONFIG_TENANT',
+            'LAMBDA_STAGE',
+            'PORT',
+            'REDIS_HOST',
+            'REDIS_PORT',
+            'SA_SEED_KMS_KEY_ARN',
+        ]);
+    });
+
+    it('keeps the non-secret escrow toggle in bundle mode', () => {
+        vi.stubEnv('RUNTIME_SECRETS_ID', 'lca-api/dev/runtime-secrets');
+        vi.stubEnv('ESCROW_ENCLAVE_MODE', 'software');
+        vi.stubEnv('ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON', '{"k":"secret"}');
+        expect(functions.api()).toEqual({
+            RUNTIME_SECRETS_ID: 'lca-api/dev/runtime-secrets',
+            ESCROW_ENCLAVE_MODE: 'software',
+        });
+    });
+
+    it('bakes the tenant selector into every function, defaulting to learncard', () => {
+        expect(functions.provider().CONFIG_TENANT).toBe('learncard');
+        vi.stubEnv('CONFIG_TENANT', 'scouts');
+        expect(functions.provider().CONFIG_TENANT).toBe('scouts');
+    });
+
+    it('retains the existing provider and API credentials only in fallback mode', () => {
+        expect(functions.provider().SEED).toBe('seed');
+        expect(functions.api().GOOGLE_APPLICATION_CREDENTIAL).toBe('credential');
+        expect(functions.api().RUNTIME_SECRETS_ID).toBeUndefined();
+    });
+
+    it('keeps the OIDC exception scoped to its separate role', () => {
+        vi.stubEnv('RUNTIME_SECRETS_ID', 'bundle');
+        expect(functions.oidc()).toEqual({
+            OIDC_CLIENT_SECRET: 'broker-secret',
+            OIDC_REDIRECT_URIS: 'https://example.com/callback',
+        });
+        expect(functions.provider().OIDC_CLIENT_SECRET).toBeUndefined();
+        expect(functions.api().OIDC_CLIENT_SECRET).toBeUndefined();
+    });
+
+    it.each(['', 'bundle'])(
+        'resolves the full provider environment through Serverless v3 (%s)',
+        async bundle => {
+            const source = require('serverless/lib/configuration/variables/sources/file');
+            vi.stubEnv('RUNTIME_SECRETS_ID', bundle);
+            const options = { stage: 'production', httpPort: '5100' };
+            for (const name of ['provider', 'api', 'oidc'] as const) {
+                const result = await source.resolve({
+                    serviceDir: new URL('../../', import.meta.url).pathname,
+                    params: [
+                        new URL('../../serverless.function-env.cjs', import.meta.url).pathname,
+                    ],
+                    address: name,
+                    options,
+                    resolveConfigurationProperty: vi.fn(),
+                    resolveVariable: vi.fn(),
+                });
+                const expected =
+                    name === 'provider' ? functions.provider({ options }) : functions[name]();
+                expect(result.value).toEqual(expected);
+                if (name === 'provider') {
+                    expect(result.value.LAMBDA_STAGE).toBe('production');
+                    expect(result.value.PORT).toBe('5100');
+                    expect(result.value.SA_SEED_KMS_KEY_ARN).toEqual({
+                        'Fn::GetAtt': ['SigningAuthoritySeedKey', 'Arn'],
+                    });
+                }
+            }
+        }
+    );
+});

package/src/config/stageConfig.test.ts

@@ -0,0 +1,26 @@
+import { afterEach, expect, it, vi } from 'vitest';
+
+// Model a non-empty .env value arriving before the stage defaults are applied.
+vi.mock('dotenv/config', () => {
+    vi.stubEnv('SENTRY_ENV', 'self-hosted');
+    return {};
+});
+
+afterEach(() => vi.unstubAllEnvs());
+
+it('loads local env before applying statically imported stage defaults', async () => {
+    const { applyLcaApiStageConfig, stages } = await import('./stageConfig');
+    for (const key of Object.keys(stages.dev)) {
+        if (key !== 'SENTRY_ENV') vi.stubEnv(key, '');
+    }
+    applyLcaApiStageConfig('dev');
+    expect(process.env.SENTRY_ENV).toBe('self-hosted');
+    expect(process.env.DOMAIN_NAME).toBe(stages.dev.DOMAIN_NAME);
+});
+
+it('does not select a deployed stage for an unknown local stage', async () => {
+    const { applyLcaApiStageConfig } = await import('./stageConfig');
+    vi.stubEnv('DOMAIN_NAME', '');
+    applyLcaApiStageConfig('unregistered-self-hosted-stage');
+    expect(process.env.DOMAIN_NAME).toBe('');
+});

package/src/config/stageConfig.ts

@@ -0,0 +1,24 @@
+import 'dotenv/config';
+import { applyStageConfig } from '@learncard/service-config';
+
+import baseConfig from '../../config/config.json';
+import devConfig from '../../config/config.dev.json';
+import productionConfig from '../../config/config.production.json';
+import scoutsDevConfig from '../../config/config.scouts.dev.json';
+import scoutsProductionConfig from '../../config/config.scouts.production.json';
+
+export const base: Record<string, string> = baseConfig;
+
+export const stages = {
+    dev: devConfig,
+    production: productionConfig,
+    // ScoutPass deploys the same services and stage names; CONFIG_TENANT=scouts selects these.
+    'scouts.dev': scoutsDevConfig,
+    'scouts.production': scoutsProductionConfig,
+} satisfies Record<string, Record<string, string>>;
+
+// Must run before any module that reads configuration on import (e.g. @environment):
+// merges base + the selected stage into process.env; explicit non-empty env still wins.
+export const applyLcaApiStageConfig = (stage: string | undefined): void => {
+    applyStageConfig({ base, stages, stage });
+};

package/src/docker-entry.ts

@@ -1,3 +1,5 @@
+import './config/applyDockerStageConfig';
+
 import { environment } from '@environment';
 import path from 'path';
 
@@ -10,6 +12,8 @@ import { appRouter, type AppRouter, createContext } from './app';
 import { openApiDocument } from './openapi';
 import { didFastifyPlugin } from './dids';
 import { ensureUserKeysIndexes, createEscrowHoldsIndexes } from './models';
+import { oidcFastifyPlugin } from './oidc';
+import { ensureAuthSubjectIndexes } from './models/AuthSubject';
 
 const server = Fastify({ maxParamLength: 5000 });
 
@@ -102,9 +106,14 @@ server.register(fastifyStatic, {
 });
 
 server.register(didFastifyPlugin);
+server.register(oidcFastifyPlugin);
 
 (async () => {
     try {
+        await ensureAuthSubjectIndexes().catch(error => {
+            // Login requests retry index creation and must succeed before writing subjects.
+            console.error('AuthSubject indexes unavailable at startup; login will retry:', error);
+        });
         console.log('Server starting on port ', environment.PORT || 3000);
         await ensureUserKeysIndexes();
         await createEscrowHoldsIndexes();

package/src/helpers/auth.helpers.ts

@@ -5,6 +5,16 @@
 import { environment } from '@environment';
 import { TRPCError } from '@trpc/server';
 import admin from 'firebase-admin';
+import { z } from 'zod';
+import { getKeycloakVerifyOptionsFromEnv, verifyKeycloakJwt } from './keycloak.helpers';
+
+const offlineFirebaseClaimsSchema = z.object({
+    sub: z.string().optional(),
+    uid: z.string().optional(),
+    user_id: z.string().optional(),
+    email: z.string().nullish(),
+    phone_number: z.string().nullish(),
+});
 
 export interface VerifiedUser {
     id: string;
@@ -15,31 +25,35 @@ export interface VerifiedUser {
 
 export type AuthProviderType = 'firebase' | 'supertokens' | 'keycloak' | 'oidc';
 
+const parseOfflineFirebaseClaims = (
+    token: string
+): z.infer<typeof offlineFirebaseClaimsSchema> | undefined => {
+    const payloadPart = token.split('.')[1];
+    if (!payloadPart) return undefined;
+    try {
+        const decoded: unknown = JSON.parse(Buffer.from(payloadPart, 'base64url').toString());
+        return offlineFirebaseClaimsSchema.parse(decoded);
+    } catch {
+        return undefined;
+    }
+};
+
 export async function verifyFirebaseToken(token: string): Promise<VerifiedUser> {
     // E2E test or offline bypass - parse JWT without Firebase Admin verification
     if (environment.IS_E2E_TEST || environment.IS_OFFLINE) {
-        try {
-            const parts = token.split('.');
-            const payloadPart = parts[1];
-            if (parts.length >= 2 && payloadPart) {
-                // Try base64url first, then regular base64
-                let payload;
-                try {
-                    payload = JSON.parse(Buffer.from(payloadPart, 'base64url').toString());
-                } catch {
-                    payload = JSON.parse(Buffer.from(payloadPart, 'base64').toString());
-                }
-                return {
-                    id: payload.sub || payload.uid || payload.user_id || 'offline-user',
-                    email: payload.email,
-                    phone: payload.phone_number,
-                    providerType: 'firebase',
-                };
-            }
-        } catch (e) {
-            console.warn('Failed to parse JWT in offline mode:', e);
-            // Fall through to normal verification
+        const payload = parseOfflineFirebaseClaims(token);
+        if (payload) {
+            return {
+                id: payload.sub || payload.uid || payload.user_id || 'offline-user',
+                email: payload.email ?? undefined,
+                phone: payload.phone_number ?? undefined,
+                providerType: 'firebase',
+            };
         }
+        throw new TRPCError({
+            code: 'UNAUTHORIZED',
+            message: 'Could not decode Firebase token in offline/E2E mode',
+        });
     }
 
     try {
@@ -52,7 +66,7 @@ export async function verifyFirebaseToken(token: string): Promise<VerifiedUser>
             providerType: 'firebase',
         };
     } catch (error) {
-        console.error('Firebase token verification failed:', error);
+        console.warn('Firebase token verification failed:', error);
         throw new TRPCError({
             code: 'UNAUTHORIZED',
             message: 'Invalid Firebase token',
@@ -70,14 +84,38 @@ export async function verifySuperTokensToken(_token: string): Promise<VerifiedUs
     });
 }
 
-export async function verifyKeycloakToken(_token: string): Promise<VerifiedUser> {
-    // Keycloak verification would go here
-    // This would use the existing verifyKeycloakToken from firebase.helpers.ts
-    // but return a VerifiedUser instead of creating a Firebase user
-    throw new TRPCError({
-        code: 'NOT_IMPLEMENTED',
-        message: 'Keycloak verification not yet implemented for SSS',
-    });
+export async function verifyKeycloakToken(token: string): Promise<VerifiedUser> {
+    const options = getKeycloakVerifyOptionsFromEnv();
+    if (!options) {
+        throw new TRPCError({
+            code: 'UNAUTHORIZED',
+            message: 'Keycloak verification is not configured',
+        });
+    }
+    let claims;
+    try {
+        claims = await verifyKeycloakJwt(token, options);
+    } catch {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Invalid Keycloak token' });
+    }
+    if (claims.email !== undefined && claims.email_verified !== true) {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Email address is not verified' });
+    }
+    if (claims.phone_number !== undefined && claims.phone_number_verified !== true) {
+        throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Phone number is not verified' });
+    }
+    if (!claims.email && !claims.phone_number) {
+        throw new TRPCError({
+            code: 'UNAUTHORIZED',
+            message: 'Token has no verified contact method',
+        });
+    }
+    return {
+        id: claims.sub,
+        email: claims.email,
+        phone: claims.phone_number,
+        providerType: 'keycloak',
+    };
 }
 
 export async function verifyOidcToken(_token: string): Promise<VerifiedUser> {

package/src/helpers/escrowCancelLink.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+
+import { buildEscrowCancelUrl, resolveEscrowAppBaseUrl } from './escrowCancelLink';
+
+describe('buildEscrowCancelUrl', () => {
+    const holdId = '5b1f6e2e-6e2a-4e8a-9e2a-6e2a4e8a9e2a';
+    const token = 'a'.repeat(64);
+
+    it('builds the expected path and query', () => {
+        expect(buildEscrowCancelUrl({ baseUrl: 'https://learncard.app', holdId, token })).toBe(
+            `https://learncard.app/recovery/cancel?holdId=${holdId}&token=${token}`
+        );
+    });
+
+    it('never doubles the slash when baseUrl has a trailing slash', () => {
+        expect(buildEscrowCancelUrl({ baseUrl: 'https://learncard.app/', holdId, token })).toBe(
+            `https://learncard.app/recovery/cancel?holdId=${holdId}&token=${token}`
+        );
+    });
+
+    it('percent-encodes query values that need it', () => {
+        const url = buildEscrowCancelUrl({
+            baseUrl: 'https://learncard.app',
+            holdId: 'weird id/with&chars',
+            token,
+        });
+        expect(url).toBe(
+            `https://learncard.app/recovery/cancel?holdId=weird+id%2Fwith%26chars&token=${token}`
+        );
+        expect(new URL(url).searchParams.get('holdId')).toBe('weird id/with&chars');
+    });
+
+    it('ignores any path segment already present on baseUrl (host + protocol only, matching every tenant appUrl in the registry)', () => {
+        expect(buildEscrowCancelUrl({ baseUrl: 'https://vetpass.app', holdId, token })).toBe(
+            `https://vetpass.app/recovery/cancel?holdId=${holdId}&token=${token}`
+        );
+    });
+});
+
+describe('resolveEscrowAppBaseUrl', () => {
+    it('falls back to the LearnCard default when the tenant has no appUrl override', () => {
+        expect(
+            resolveEscrowAppBaseUrl({
+                tenant: { id: 'learncard', emailBranding: {}, resolvedVia: 'default' },
+            })
+        ).toBe('https://learncard.app');
+    });
+
+    it('prefers the resolved tenant appUrl', () => {
+        expect(
+            resolveEscrowAppBaseUrl({
+                tenant: {
+                    id: 'vetpass',
+                    emailBranding: { appUrl: 'https://vetpass.app' },
+                    resolvedVia: 'origin',
+                },
+            })
+        ).toBe('https://vetpass.app');
+    });
+});

package/src/helpers/escrowCancelLink.ts

@@ -0,0 +1,38 @@
+/**
+ * Escrow recovery cancel-link deep-link builder.
+ *
+ * Mirrors the existing tenant-branded app-link pattern used elsewhere in the
+ * monorepo (brain-service's `generateClaimUrl` / `generateGuardianApprovalUrl`,
+ * `inbox.helpers.ts`'s `new URL('/notifications', appUrl)`): prefer the
+ * resolved tenant's `TenantBranding.appUrl`, which already falls back to the
+ * LearnCard default (`https://learncard.app`) via `resolveBranding()` when a
+ * tenant has no override.
+ */
+
+import { resolveBranding } from '@learncard/email-templates';
+import type { Context } from '@routes';
+
+/** Base app URL (e.g. `https://vetpass.app`) for constructing escrow deep links. */
+export const resolveEscrowAppBaseUrl = (ctx: Pick<Context, 'tenant'>): string =>
+    resolveBranding(ctx.tenant?.emailBranding).appUrl;
+
+/**
+ * Builds the single-use "cancel this recovery" link sent in the hold-started
+ * email. Uses `URL`/`URLSearchParams` rather than string concatenation so
+ * `holdId`/`token` are correctly percent-encoded and a trailing slash on
+ * `baseUrl` never produces a doubled `//recovery/cancel`.
+ */
+export const buildEscrowCancelUrl = ({
+    baseUrl,
+    holdId,
+    token,
+}: {
+    baseUrl: string;
+    holdId: string;
+    token: string;
+}): string => {
+    const url = new URL('/recovery/cancel', baseUrl);
+    url.searchParams.set('holdId', holdId);
+    url.searchParams.set('token', token);
+    return url.toString();
+};

package/src/helpers/escrowCancelToken.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect } from 'vitest';
+
+import {
+    generateEscrowCancelToken,
+    hashEscrowCancelToken,
+    escrowCancelTokenMatches,
+} from './escrowCancelToken';
+
+import type { EscrowHold } from '@models';
+
+const baseHold = (overrides: Partial<EscrowHold> = {}): EscrowHold => {
+    const now = new Date();
+    return {
+        holdRecord: {
+            hold: {
+                holdId: 'hold-id',
+                did: 'did:key:test',
+                shareVersion: 1,
+                blobHash: 'ab'.repeat(32),
+                enrollmentEpoch: 1,
+                releasePolicy: 'hold',
+                clientEphemeralPublicKey: 'public-key',
+                createdLo: 0,
+                createdHi: 0,
+                policyVersion: 1,
+                signature: 'test-signature',
+            },
+            holdDurationMs: 0,
+            ledgerSeq: 0,
+        },
+        _id: 'hold-id',
+        authProvider: { type: 'firebase', id: 'user-1' },
+        primaryDid: 'did:key:test',
+        shareVersion: 1,
+        status: 'pending',
+        identityProofType: 'auth-token',
+        requestedAt: now,
+        releaseAfter: now,
+        releasePolicy: 'hold',
+        clientEphemeralPublicKey: 'public-key',
+        resumeTokenHash: 'a'.repeat(64),
+        notifications: [],
+        createdAt: now,
+        updatedAt: now,
+        ...overrides,
+    };
+};
+
+describe('escrowCancelToken helpers', () => {
+    it('generates unique, high-entropy hex tokens', () => {
+        const token = generateEscrowCancelToken();
+
+        expect(token).toMatch(/^[0-9a-f]{64}$/);
+        expect(generateEscrowCancelToken()).not.toBe(token);
+    });
+
+    it('hashes deterministically without ever equaling the plaintext', () => {
+        const token = generateEscrowCancelToken();
+        const hash = hashEscrowCancelToken(token);
+
+        expect(hash).toMatch(/^[0-9a-f]{64}$/);
+        expect(hash).not.toBe(token);
+        expect(hashEscrowCancelToken(token)).toBe(hash);
+    });
+
+    it('matches the correct token against a pending, unused hold', () => {
+        const token = generateEscrowCancelToken();
+        const hold = baseHold({ cancelTokenHash: hashEscrowCancelToken(token) });
+
+        expect(escrowCancelTokenMatches(hold, token)).toBe(true);
+    });
+
+    it('rejects a wrong token', () => {
+        const token = generateEscrowCancelToken();
+        const hold = baseHold({ cancelTokenHash: hashEscrowCancelToken(token) });
+
+        expect(escrowCancelTokenMatches(hold, generateEscrowCancelToken())).toBe(false);
+    });
+
+    it('rejects an already-used token', () => {
+        const token = generateEscrowCancelToken();
+        const hold = baseHold({
+            cancelTokenHash: hashEscrowCancelToken(token),
+            cancelTokenUsedAt: new Date(),
+        });
+
+        expect(escrowCancelTokenMatches(hold, token)).toBe(false);
+    });
+
+    it('rejects a non-pending hold even with a correct, unused token', () => {
+        const token = generateEscrowCancelToken();
+
+        for (const status of ['cancelled', 'completed', 'expired'] as const) {
+            const hold = baseHold({ status, cancelTokenHash: hashEscrowCancelToken(token) });
+
+            expect(escrowCancelTokenMatches(hold, token)).toBe(false);
+        }
+    });
+
+    it('rejects when no cancel token was ever issued on the hold', () => {
+        const hold = baseHold();
+
+        expect(escrowCancelTokenMatches(hold, generateEscrowCancelToken())).toBe(false);
+    });
+});

package/src/helpers/escrowCancelToken.ts

@@ -0,0 +1,47 @@
+/**
+ * Escrow recovery cancel-link token.
+ *
+ * Mirrors the resume-token primitive in `models/EscrowHold.ts`: a random,
+ * high-entropy token whose SHA-256 hash is stored on the hold so the
+ * plaintext never needs to be persisted. There is no HMAC key involved —
+ * the token's own entropy is the secret, exactly like `resumeTokenHash`.
+ *
+ * The token is single-use (burned via `cancelTokenUsedAt`) and its
+ * effective TTL is the hold's own lifetime: it stops matching the moment
+ * the hold leaves the `pending` status (cancelled, completed, or expired),
+ * so no separate expiry timestamp is needed.
+ *
+ * Never log the plaintext token.
+ */
+
+import { createHash, randomBytes, timingSafeEqual } from 'crypto';
+
+import type { EscrowHold } from '@models';
+
+/** 256 bits of entropy, hex-encoded — same shape as `generateEscrowResumeToken`. */
+export const generateEscrowCancelToken = (): string => randomBytes(32).toString('hex');
+
+/** Plain SHA-256, matching `hashEscrowResumeToken` — the token's own entropy is the secret. */
+export const hashEscrowCancelToken = (token: string): string =>
+    createHash('sha256').update(token).digest('hex');
+
+/**
+ * Timing-safe cancel-token check.
+ *
+ * Returns `false` (never throws) when the hold has no cancel token, the
+ * token was already used, or the hold is no longer `pending` — a cancel
+ * link's effective TTL is the hold's own lifetime, not a separate clock.
+ */
+export const escrowCancelTokenMatches = (hold: EscrowHold, token: string): boolean => {
+    if (hold.status !== 'pending' || hold.cancelTokenUsedAt) return false;
+    const actual = Buffer.from(hashEscrowCancelToken(token), 'hex');
+    const hashes = [
+        ...(hold.cancelTokenHashes ?? []),
+        ...(hold.cancelTokenHash ? [hold.cancelTokenHash] : []),
+    ];
+    // Evaluate every hash, including after a match, rather than short-circuiting.
+    return hashes.reduce((matches, hash) => {
+        const expected = Buffer.from(hash, 'hex');
+        return (actual.length === expected.length && timingSafeEqual(actual, expected)) || matches;
+    }, false);
+};