@learncard/lca-api-service 1.3.2 → 1.5.0

package/src/config/environment.ts

@@ -13,8 +13,16 @@ import {
 
 export const lcaApiEnvironmentShape = {
     NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
+    LAMBDA_STAGE: optionalEnvironmentString,
+    CONFIG_STAGE: optionalEnvironmentString,
+    RUNTIME_SECRETS_ID: optionalEnvironmentString,
     PORT: environmentPort.default(3000),
     SEED: requiredEnvironmentString,
+    SA_SEED_KMS_KEY_ARN: optionalEnvironmentString,
+    SA_SEED_LOCAL_KEK: optionalEnvironmentString,
+    // Defaults depend on offline/test mode and are resolved below.
+    SA_SEED_ENCRYPT_WRITES: optionalEnvironmentBoolean,
+    SA_SEED_ALLOW_LEGACY_READ: optionalEnvironmentBoolean,
     MONGO_URI: requiredEnvironmentString,
     MONGO_DB_NAME: requiredEnvironmentString,
     DOMAIN_NAME: optionalEnvironmentString,
@@ -25,6 +33,17 @@ export const lcaApiEnvironmentShape = {
     OPENAI_API_KEY: optionalEnvironmentString,
     METABASE_SECRET_KEY: optionalEnvironmentString,
     SCOUTS_SSO_CLIENT_SECRET: optionalEnvironmentString,
+    KEYCLOAK_ISSUERS: optionalEnvironmentString,
+    KEYCLOAK_AUDIENCES: optionalEnvironmentString,
+    KEYCLOAK_JWKS_URL_OVERRIDES: optionalEnvironmentString,
+    OIDC_ISSUER: optionalEnvironmentString,
+    OIDC_SIGNING_KEY_JWK: optionalEnvironmentString,
+    OIDC_SIGNING_KEY_SECRET_ID: optionalEnvironmentString,
+    OIDC_CLIENT_ID: optionalEnvironmentString,
+    OIDC_CLIENT_SECRET: optionalEnvironmentString,
+    OIDC_REDIRECT_URIS: optionalEnvironmentString,
+    GOOGLE_OAUTH_CLIENT_IDS: optionalEnvironmentString,
+    APPLE_OAUTH_CLIENT_IDS: optionalEnvironmentString,
     POSTMARK_SERVER_TOKEN: optionalEnvironmentString,
     POSTMARK_FROM_EMAIL: optionalEnvironmentString,
     POSTMARK_BRAND_NAME: optionalEnvironmentString,
@@ -32,6 +51,27 @@ export const lcaApiEnvironmentShape = {
     POSTMARK_ENDORSEMENT_REQUEST_TEMPLATE_ALIAS: optionalEnvironmentString,
     POSTMARK_RECOVERY_EMAIL_CODE_TEMPLATE_ALIAS: optionalEnvironmentString,
     POSTMARK_RECOVERY_KEY_TEMPLATE_ALIAS: optionalEnvironmentString,
+    ESCROW_RELAY_URL: optionalEnvironmentUrl,
+    ESCROW_RELAY_AUTH_TOKEN: optionalEnvironmentString,
+    ESCROW_ENCLAVE_MODE: optionalEnvironmentString.pipe(z.enum(['software', 'remote']).optional()),
+    ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON: optionalEnvironmentString,
+    ESCROW_ENCLAVE_ACTIVE_KEY_ID: optionalEnvironmentString,
+    ESCROW_ENCLAVE_REMOTE_URL: optionalEnvironmentUrl,
+    ESCROW_ENCLAVE_REMOTE_TOKEN: optionalEnvironmentString,
+    /** Operator-flipped, manual-only kill switch (P7.1). When true, startRecovery/completeRecovery
+     *  refuse with a friendly message; hold cancellation and notifications keep working. Never
+     *  auto-flipped by the escrow-ledger-monitor — a compromised monitor must not be able to
+     *  silently DoS recovery. See services/escrow-ledger-monitor/README.md. */
+    ESCROW_RELEASE_KILL_SWITCH: optionalEnvironmentBoolean,
+    ESCROW_ENCLAVE_REMOTE_TIMEOUT_MS: optionalEnvironmentString
+        .transform(value => (value === undefined ? 10_000 : Number(value)))
+        .pipe(z.number().int().positive().max(30_000)),
+    ESCROW_HOLD_DURATION_MS: optionalEnvironmentString
+        .transform(value => (value === undefined ? 604_800_000 : Number(value)))
+        .pipe(z.number().int().positive().max(Number.MAX_SAFE_INTEGER)),
+    ESCROW_HOLD_RESTART_MIN_AGE_MS: optionalEnvironmentString
+        .transform(value => (value === undefined ? 86_400_000 : Number(value)))
+        .pipe(z.number().int().positive().max(Number.MAX_SAFE_INTEGER)),
     ANDROID_PUSH_ICON: optionalEnvironmentString,
     REDIS_HOST: optionalEnvironmentString,
     REDIS_PORT: optionalEnvironmentPort,
@@ -49,7 +89,110 @@ export const lcaApiEnvironmentShape = {
 
 export const lcaApiEnvironmentSchema = z
     .object(lcaApiEnvironmentShape)
+    .transform(environment => {
+        const legacyLocalDefaults = environment.IS_OFFLINE && environment.NODE_ENV !== 'test';
+        return {
+            ...environment,
+            SA_SEED_ENCRYPT_WRITES: environment.SA_SEED_ENCRYPT_WRITES ?? !legacyLocalDefaults,
+            SA_SEED_ALLOW_LEGACY_READ: environment.SA_SEED_ALLOW_LEGACY_READ ?? legacyLocalDefaults,
+        };
+    })
     .superRefine((environment, context) => {
+        if (
+            environment.KEYCLOAK_ISSUERS?.split(',').some(value => value.trim()) &&
+            !environment.KEYCLOAK_AUDIENCES?.split(',').some(value => value.trim())
+        ) {
+            context.addIssue({
+                code: 'custom',
+                path: ['KEYCLOAK_AUDIENCES'],
+                message: 'Required when KEYCLOAK_ISSUERS is configured',
+            });
+        }
+        if (environment.SA_SEED_KMS_KEY_ARN) {
+            if (
+                !/^arn:aws[a-z-]*:kms:[a-z0-9-]+:\d{12}:key\/[a-zA-Z0-9-]+$/.test(
+                    environment.SA_SEED_KMS_KEY_ARN
+                )
+            ) {
+                context.addIssue({
+                    code: 'custom',
+                    path: ['SA_SEED_KMS_KEY_ARN'],
+                    message: 'Must be a KMS key ARN (not an alias)',
+                });
+            }
+        } else if (!environment.IS_OFFLINE && environment.NODE_ENV !== 'test') {
+            context.addIssue({
+                code: 'custom',
+                path: ['SA_SEED_KMS_KEY_ARN'],
+                message: 'Required outside offline/test environments',
+            });
+        } else if (
+            (environment.SA_SEED_ENCRYPT_WRITES || environment.SA_SEED_LOCAL_KEK !== undefined) &&
+            !/^[a-fA-F0-9]{64}$/.test(environment.SA_SEED_LOCAL_KEK ?? '')
+        ) {
+            context.addIssue({
+                code: 'custom',
+                path: ['SA_SEED_LOCAL_KEK'],
+                message: 'A 32-byte hex key is required for local seed encryption',
+            });
+        }
+        if (!environment.SA_SEED_ENCRYPT_WRITES && !environment.SA_SEED_ALLOW_LEGACY_READ) {
+            context.addIssue({
+                code: 'custom',
+                path: ['SA_SEED_ENCRYPT_WRITES'],
+                message: 'Plaintext writes require the compatibility reader',
+            });
+        }
+
+        if (environment.ESCROW_ENCLAVE_MODE === 'software') {
+            try {
+                const keys = parseEscrowPrivateKeys(
+                    environment.ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON ?? ''
+                );
+                if (
+                    !environment.ESCROW_ENCLAVE_ACTIVE_KEY_ID ||
+                    !Object.hasOwn(keys, environment.ESCROW_ENCLAVE_ACTIVE_KEY_ID)
+                ) {
+                    context.addIssue({
+                        code: 'custom',
+                        path: ['ESCROW_ENCLAVE_ACTIVE_KEY_ID'],
+                        message: 'Software escrow requires an active key ID present in the key map',
+                    });
+                }
+            } catch {
+                context.addIssue({
+                    code: 'custom',
+                    path: ['ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON'],
+                    message:
+                        'Software escrow requires a valid nonempty key ID to private key JSON map',
+                });
+            }
+        }
+        // Format-only: absence at 'remote' mode is intentionally NOT a parse-time
+        // failure. getEscrowEnclave() fails closed per-request instead, so a
+        // misconfigured remote backend degrades that one feature rather than
+        // crashing the whole service at boot (see escrow-enclave/index.ts).
+        if (environment.ESCROW_ENCLAVE_REMOTE_URL) {
+            const { protocol, hostname } = new URL(environment.ESCROW_ENCLAVE_REMOTE_URL);
+            const isLocalhost = ['localhost', '127.0.0.1', '::1'].includes(hostname);
+            if (protocol !== 'https:' && environment.NODE_ENV !== 'test' && !isLocalhost) {
+                context.addIssue({
+                    code: 'custom',
+                    path: ['ESCROW_ENCLAVE_REMOTE_URL'],
+                    message: 'Must use https:// outside tests or localhost',
+                });
+            }
+        }
+        if (
+            environment.ESCROW_ENCLAVE_REMOTE_TOKEN &&
+            environment.ESCROW_ENCLAVE_REMOTE_TOKEN.length < 32
+        ) {
+            context.addIssue({
+                code: 'custom',
+                path: ['ESCROW_ENCLAVE_REMOTE_TOKEN'],
+                message: 'Must be at least 32 characters',
+            });
+        }
         if (
             environment.NODE_ENV === 'production' &&
             !environment.IS_OFFLINE &&
@@ -85,6 +228,7 @@ export const parseLcaApiEnvironment = (
         raw.NODE_ENV === 'test'
             ? {
                   SEED: 'a'.repeat(64),
+                  SA_SEED_LOCAL_KEK: 'f'.repeat(64),
                   MONGO_URI: 'mongodb://localhost:27017',
                   MONGO_DB_NAME: 'lca-api-test',
               }
@@ -101,4 +245,24 @@ export const parseLcaApiEnvironment = (
     );
 };
 
+// Read live from process.env (not the frozen `environment` snapshot below) so an
+// operator's flip takes effect on the next request without a full restart, and so
+// tests can toggle it per-case. The escrow-ledger-monitor must never set this itself
+// — see services/escrow-ledger-monitor/README.md.
+export const isEscrowReleaseKillSwitchEnabled = (): boolean =>
+    optionalEnvironmentBoolean.parse(process.env.ESCROW_RELEASE_KILL_SWITCH) ?? false;
+
+/** Parse configuration without exposing secret values in validation errors. */
+export const parseEscrowPrivateKeys = (serialized: string): Record<string, string> => {
+    try {
+        const parsed: unknown = JSON.parse(serialized);
+        return z
+            .record(z.string().regex(/^[A-Za-z0-9._-]{1,128}$/), z.string().trim().min(1))
+            .refine(keys => Object.keys(keys).length > 0)
+            .parse(parsed);
+    } catch {
+        throw new Error('Invalid escrow private key configuration');
+    }
+};
+
 export const environment = parseLcaApiEnvironment(process.env);

package/src/config/escrowBundleMode.test.ts

@@ -0,0 +1,52 @@
+import { createRequire } from 'node:module';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { mergeRuntimeSecrets, resolveStageDefaults } from '@learncard/service-config';
+
+import { parseLcaApiEnvironment } from './environment';
+import { base, stages } from './stageConfig';
+
+const require = createRequire(import.meta.url);
+const functions: {
+    api: () => Record<string, string>;
+    provider: (context?: { options: { stage: string } }) => Record<string, unknown>;
+} = require('../../serverless.function-env.cjs');
+
+// Deployed precedence for an api function in bundle mode: real Lambda env > bundle > stage file.
+const deployedEnvironment = (
+    bundle: Record<string, string>
+): Record<string, string | undefined> => {
+    const lambdaEnv = Object.fromEntries(
+        Object.entries({ ...functions.provider({ options: { stage: 'dev' } }), ...functions.api() })
+            // CloudFormation intrinsics (KMS ARN, Redis endpoint) resolve only at deploy time.
+            .filter((entry): entry is [string, string] => typeof entry[1] === 'string')
+    );
+    const stageDefaults = resolveStageDefaults({ base, stages, stage: 'dev', env: lambdaEnv });
+    const resolvedIntrinsics = {
+        SA_SEED_KMS_KEY_ARN: 'arn:aws:kms:us-east-1:000000000000:key/test',
+    };
+    return mergeRuntimeSecrets({ ...stageDefaults, ...lambdaEnv, ...resolvedIntrinsics }, bundle);
+};
+
+afterEach(() => vi.unstubAllEnvs());
+
+describe('escrow in runtime-secrets bundle mode', () => {
+    it('keeps software escrow enabled with keys supplied only by the bundle', () => {
+        vi.stubEnv('RUNTIME_SECRETS_ID', 'lca-api/dev/runtime-secrets');
+        vi.stubEnv('ESCROW_ENCLAVE_MODE', 'software');
+        vi.stubEnv('SEED', '');
+
+        const activeKeyId = stages.dev.ESCROW_ENCLAVE_ACTIVE_KEY_ID;
+        const env = parseLcaApiEnvironment(
+            deployedEnvironment({
+                SEED: 'a'.repeat(64),
+                MONGO_URI: 'mongodb://localhost:27017',
+                MONGO_DB_NAME: 'test',
+                POSTMARK_SERVER_TOKEN: 'postmark',
+                ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON: JSON.stringify({ [activeKeyId]: 'k' }),
+            })
+        );
+
+        expect(env.ESCROW_ENCLAVE_MODE).toBe('software');
+        expect(env.ESCROW_ENCLAVE_ACTIVE_KEY_ID).toBe(activeKeyId);
+    });
+});

package/src/config/escrowDeployment.test.ts

@@ -0,0 +1,114 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { lcaApiEnvironmentShape } from './environment';
+import { stages } from './stageConfig';
+
+const require = createRequire(import.meta.url);
+const serverlessRequire = createRequire(require.resolve('serverless/package.json'));
+const yaml: { load: (source: string) => unknown } = serverlessRequire('js-yaml');
+
+const functionEnvironment = require('../../serverless.function-env.cjs') as Record<
+    'api' | 'escrow',
+    () => Record<string, string>
+>;
+
+// Every schema ESCROW_* setting has exactly one source under the config model.
+const SOURCES = {
+    // Credentials and the endpoints bound to them: runtime bundle, GitHub fallback.
+    bundle: [
+        'ESCROW_RELAY_URL',
+        'ESCROW_RELAY_AUTH_TOKEN',
+        'ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON',
+        'ESCROW_ENCLAVE_REMOTE_URL',
+        'ESCROW_ENCLAVE_REMOTE_TOKEN',
+    ],
+    // Operator toggles: GitHub vars forwarded in every mode.
+    toggle: ['ESCROW_ENCLAVE_MODE', 'ESCROW_RELEASE_KILL_SWITCH'],
+    // Non-secret tuning: checked-in config.<stage>.json (or schema default).
+    stage: [
+        'ESCROW_ENCLAVE_ACTIVE_KEY_ID',
+        'ESCROW_HOLD_DURATION_MS',
+        'ESCROW_HOLD_RESTART_MIN_AGE_MS',
+        'ESCROW_ENCLAVE_REMOTE_TIMEOUT_MS',
+    ],
+};
+const SECRETS = new Set([
+    'ESCROW_RELAY_AUTH_TOKEN',
+    'ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON',
+    'ESCROW_ENCLAVE_REMOTE_TOKEN',
+]);
+// serverless.yml PrivateLink inputs; read at deploy time, never by the Lambda runtime.
+const DEPLOY_TIME = ['ESCROW_ENCLAVE_ENDPOINT_SERVICE_NAME', 'ESCROW_ENCLAVE_HOSTNAME'];
+
+const settings = Object.keys(lcaApiEnvironmentShape).filter(name => name.startsWith('ESCROW_'));
+
+afterEach(() => vi.unstubAllEnvs());
+
+describe('escrow deployment wiring', () => {
+    it('classifies every schema ESCROW_* setting exactly once', () => {
+        const classified = Object.values(SOURCES).flat();
+        expect([...classified].sort()).toEqual([...settings].sort());
+        expect(new Set(classified).size).toBe(classified.length);
+    });
+
+    it('passes only bundle fallbacks, toggles and deploy-time inputs through GitHub', () => {
+        const workflow = yaml.load(
+            readFileSync(
+                new URL('../../../../../.github/workflows/deploy.yml', import.meta.url),
+                'utf8'
+            )
+        ) as {
+            jobs: Record<string, { steps: { name: string; env?: Record<string, string> }[] }>;
+        };
+        const env = workflow.jobs['deploy-lca-api']!.steps.find(
+            step => step.name === 'Deploy LCA API Service Lambda'
+        )!.env!;
+
+        for (const name of [...SOURCES.bundle, ...SOURCES.toggle, ...DEPLOY_TIME]) {
+            expect(env[name], name).toBe(
+                `\${{ ${SECRETS.has(name) ? 'secrets' : 'vars'}.${name} }}`
+            );
+        }
+        for (const name of SOURCES.stage) expect(env[name], name).toBeUndefined();
+    });
+
+    it('runs the scheduled escrow jobs with the API environment (bundle + toggles)', () => {
+        const serverless = yaml.load(
+            readFileSync(new URL('../../serverless.yml', import.meta.url), 'utf8')
+        ) as { functions: Record<string, { environment?: string; role?: string }> };
+        for (const name of ['escrowHoldReminders', 'escrowBlobRewrap']) {
+            expect(serverless.functions[name]?.environment, name).toBe(
+                '${file(./serverless.function-env.cjs):escrow}'
+            );
+        }
+        expect(functionEnvironment.escrow).toBe(functionEnvironment.api);
+    });
+
+    it('keeps escrow toggles and drops credential fallbacks in bundle mode', () => {
+        for (const name of [...SOURCES.bundle, ...SOURCES.toggle]) vi.stubEnv(name, name);
+        vi.stubEnv('RUNTIME_SECRETS_ID', 'lca-api/dev/runtime-secrets');
+        expect(functionEnvironment.escrow()).toEqual({
+            RUNTIME_SECRETS_ID: 'lca-api/dev/runtime-secrets',
+            ESCROW_ENCLAVE_MODE: 'ESCROW_ENCLAVE_MODE',
+            ESCROW_RELEASE_KILL_SWITCH: 'ESCROW_RELEASE_KILL_SWITCH',
+        });
+
+        vi.stubEnv('RUNTIME_SECRETS_ID', '');
+        expect(Object.keys(functionEnvironment.escrow()).sort()).toEqual(
+            [...SOURCES.bundle, ...SOURCES.toggle].sort()
+        );
+    });
+
+    it('never checks in escrow credentials', () => {
+        for (const [stage, config] of Object.entries(stages)) {
+            for (const name of [...SOURCES.bundle, ...SOURCES.toggle]) {
+                expect(
+                    (config as Record<string, string>)[name],
+                    `${stage}/${name}`
+                ).toBeUndefined();
+            }
+        }
+    });
+});

package/src/config/oidcEnvironment.ts

@@ -0,0 +1,59 @@
+import 'dotenv/config';
+
+import { z } from 'zod';
+import {
+    optionalEnvironmentBoolean,
+    optionalEnvironmentString,
+    parseEnvironment,
+} from '@learncard/helpers';
+
+/**
+ * Focused environment contract for the OIDC provider surface so the OIDC Lambda
+ * can boot without SEED/MONGO/Postmark/Firebase/bundle. Validates ONLY the
+ * fields read by src/oidc.ts and src/helpers/oidc.helpers.ts, reproducing the
+ * full schema's parsers and its KEYCLOAK_ISSUERS->KEYCLOAK_AUDIENCES superRefine
+ * verbatim so no constraint is weakened.
+ */
+export const oidcEnvironmentShape = {
+    NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
+    LAMBDA_STAGE: optionalEnvironmentString,
+    IS_OFFLINE: optionalEnvironmentBoolean.default(false),
+    IS_E2E_TEST: optionalEnvironmentBoolean.default(false),
+    KEYCLOAK_ISSUERS: optionalEnvironmentString,
+    KEYCLOAK_AUDIENCES: optionalEnvironmentString,
+    OIDC_ISSUER: optionalEnvironmentString,
+    OIDC_SIGNING_KEY_JWK: optionalEnvironmentString,
+    OIDC_SIGNING_KEY_SECRET_ID: optionalEnvironmentString,
+    OIDC_CLIENT_ID: optionalEnvironmentString,
+    OIDC_CLIENT_SECRET: optionalEnvironmentString,
+    OIDC_REDIRECT_URIS: optionalEnvironmentString,
+} satisfies z.ZodRawShape;
+
+export const oidcEnvironmentSchema = z
+    .object(oidcEnvironmentShape)
+    .superRefine((environment, context) => {
+        if (
+            environment.KEYCLOAK_ISSUERS?.split(',').some(value => value.trim()) &&
+            !environment.KEYCLOAK_AUDIENCES?.split(',').some(value => value.trim())
+        ) {
+            context.addIssue({
+                code: 'custom',
+                path: ['KEYCLOAK_AUDIENCES'],
+                message: 'Required when KEYCLOAK_ISSUERS is configured',
+            });
+        }
+    });
+
+export type OidcEnvironment = z.output<typeof oidcEnvironmentSchema>;
+
+export const parseOidcEnvironment = (
+    raw: Record<string, unknown>,
+    source = 'process environment'
+): OidcEnvironment =>
+    parseEnvironment(oidcEnvironmentSchema, raw, {
+        project: 'lca-api (oidc)',
+        source,
+        examplePath: 'services/learn-card-network/lca-api/.env.example',
+    });
+
+export const environment = parseOidcEnvironment(process.env);

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';
 
@@ -9,6 +11,9 @@ import { fastifyTRPCOpenApiPlugin, CreateOpenApiFastifyPluginOptions } from 'trp
 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 });
 
@@ -50,6 +55,7 @@ server.register(fastifyCors, {
         'Authorization',
         'X-Tenant-Id',
         'X-Guardian-Approval',
+        'X-Auth-Token',
         'baggage',
         'sentry-trace',
     ],
@@ -100,10 +106,17 @@ 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();
         await server.listen({ host: '0.0.0.0', port: Number(environment.PORT || 3000) });
     } catch (err) {
         console.error(err);