@learncard/lca-api-service 1.4.0 → 1.5.0

package/src/accesslayer/signing-authority/index.ts

@@ -7,4 +7,7 @@ export const getSigningAuthoritiesCollection = () => {
 
 export const SigningAuthorities = getSigningAuthoritiesCollection();
 
-SigningAuthorities.createIndex({ ownerDid: 1, name: 1 }, { unique: true });
+// Fire-and-forget at module load; see accesslayer/notifications for why it must not reject.
+SigningAuthorities.createIndex({ ownerDid: 1, name: 1 }, { unique: true }).catch(error => {
+    console.error('Signing authority unique index creation failed:', error);
+});

package/src/app.ts

@@ -12,6 +12,7 @@ import { preferencesRouter } from '@routes/preferences';
 import { keysRouter } from '@routes/keys';
 import { escrowRouter } from '@routes/escrow';
 import { qrLoginRouter } from '@routes/qr-login';
+import { authRouter } from '@routes/auth';
 import { testRouter, type TestRouter } from '@routes/test';
 import { environment } from '@environment';
 
@@ -28,6 +29,7 @@ const routes = {
     keys: keysRouter,
     escrow: escrowRouter,
     qrLogin: qrLoginRouter,
+    auth: authRouter,
 };
 
 export const appRouter = t.router<typeof routes & { test?: TestRouter }>({

package/src/cache/getDel.test.ts

@@ -0,0 +1,34 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import cache from '@cache';
+import { consumeMatchingCode } from './getDel';
+
+vi.mock('@cache', async () => {
+    const { default: Redis } = await import('ioredis-mock');
+    return { default: { node: new Redis() } };
+});
+
+afterEach(async () => {
+    await cache.node.flushall();
+});
+
+describe('consumeMatchingCode', () => {
+    it('preserves a valid code after a wrong guess', async () => {
+        await cache.node.set('login-code:test@example.com', '123456');
+        expect(await consumeMatchingCode('login-code:test@example.com', '000000')).toBe(false);
+        expect(await cache.node.get('login-code:test@example.com')).toBe('123456');
+    });
+
+    it('allows exactly one concurrent redemption and rejects replay', async () => {
+        await cache.node.set('login-code:test@example.com', '123456');
+        const results = await Promise.all([
+            consumeMatchingCode('login-code:test@example.com', '123456'),
+            consumeMatchingCode('login-code:test@example.com', '123456'),
+        ]);
+        expect(results.filter(Boolean)).toHaveLength(1);
+        expect(await consumeMatchingCode('login-code:test@example.com', '123456')).toBe(false);
+    });
+
+    it('rejects missing codes', async () => {
+        expect(await consumeMatchingCode('login-code:missing@example.com', '123456')).toBe(false);
+    });
+});

package/src/cache/getDel.ts

@@ -0,0 +1,32 @@
+import cache from '@cache';
+
+/**
+ * Atomically read-and-delete a key so its value can only ever be consumed once.
+ *
+ * Redis `GETDEL` is a single command, so concurrent redemptions return the value
+ * to exactly one caller — closing the read-then-delete race that `get` + `delete`
+ * would leave open. Used for login codes, login tickets and authorization codes.
+ *
+ * NOTE: `GETDEL` requires Redis >= 6.2. Deployed ElastiCache clusters are on 7.x
+ * (see the `ElasticCacheCluster` note in `serverless.yml`); `ioredis-mock`
+ * implements it for the no-Redis fallback.
+ */
+export const getDel = async (key: string): Promise<string | null> => {
+    const redis = cache.redis ?? cache.node;
+    return redis.getdel(key);
+};
+
+/** Consume a code only when its value matches, atomically preventing replay. */
+export const consumeMatchingCode = async (key: string, code: string): Promise<boolean> => {
+    const redis = cache.redis ?? cache.node;
+    const consumed = await redis.eval(
+        `if redis.call('GET', KEYS[1]) == ARGV[1] then
+            return redis.call('DEL', KEYS[1])
+        end
+        return 0`,
+        1,
+        key,
+        code
+    );
+    return consumed === 1;
+};

package/src/cache/index.ts

@@ -1,6 +1,6 @@
 /// <reference path="../global.d.ts" />
 
-import { environment } from '@environment';
+import { environment } from '@config/cacheEnvironment';
 import Redis, { RedisValue, RedisKey } from 'ioredis';
 import MemoryRedis, { Redis as RedisMockType } from 'ioredis-mock';
 

package/src/cache/login-tickets.ts

@@ -0,0 +1,26 @@
+import { randomBytes } from 'node:crypto';
+import cache from '@cache';
+import { getDel } from '@cache/getDel';
+
+export interface LoginTicketPayload {
+    subject: string;
+    email?: string;
+    emailVerified?: boolean;
+    phoneNumber?: string;
+    phoneNumberVerified?: boolean;
+    name?: string;
+    picture?: string;
+    identityKey: string;
+}
+
+export const issueLoginTicket = async (payload: LoginTicketPayload): Promise<string> => {
+    const ticket = randomBytes(32).toString('base64url');
+    const result = await cache.set(`login-ticket:${ticket}`, JSON.stringify(payload), 60);
+    if (result !== 'OK') throw new Error('Failed to persist login ticket');
+    return ticket;
+};
+
+export const redeemLoginTicket = async (ticket: string): Promise<LoginTicketPayload | null> => {
+    const raw = await getDel(`login-ticket:${ticket}`);
+    return raw ? (JSON.parse(raw) as LoginTicketPayload) : null;
+};

package/src/config/applyDockerStageConfig.ts

@@ -0,0 +1,6 @@
+import { applyLcaApiStageConfig } from './stageConfig';
+
+// Side-effect import: runs before @environment is evaluated so Docker/local processes
+// pick up checked-in per-stage config. Keyed on CONFIG_STAGE (Lambda uses LAMBDA_STAGE);
+// explicit non-empty env values from the developer's .env still win.
+applyLcaApiStageConfig(process.env.CONFIG_STAGE);

package/src/config/cacheEnvironment.ts

@@ -0,0 +1,34 @@
+import 'dotenv/config';
+
+import { z } from 'zod';
+import {
+    optionalEnvironmentPort,
+    optionalEnvironmentString,
+    parseEnvironment,
+} from '@learncard/helpers';
+
+/**
+ * Focused environment contract for the Redis-backed cache so `src/cache/index.ts`
+ * can boot without the full schema's required SEED/MONGO. The cache reads only
+ * REDIS_HOST/REDIS_PORT, mirroring the parsers used by the full schema.
+ */
+export const cacheEnvironmentShape = {
+    REDIS_HOST: optionalEnvironmentString,
+    REDIS_PORT: optionalEnvironmentPort,
+} satisfies z.ZodRawShape;
+
+export const cacheEnvironmentSchema = z.object(cacheEnvironmentShape);
+
+export type CacheEnvironment = z.output<typeof cacheEnvironmentSchema>;
+
+export const parseCacheEnvironment = (
+    raw: Record<string, unknown>,
+    source = 'process environment'
+): CacheEnvironment =>
+    parseEnvironment(cacheEnvironmentSchema, raw, {
+        project: 'lca-api (cache)',
+        source,
+        examplePath: 'services/learn-card-network/lca-api/.env.example',
+    });
+
+export const environment = parseCacheEnvironment(process.env);

package/src/config/environment.test.ts

@@ -1,5 +1,18 @@
-import { describe, expect, it } from 'vitest';
-import { parseLcaApiEnvironment } from './environment';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { isEscrowReleaseKillSwitchEnabled, parseLcaApiEnvironment } from './environment';
+
+afterEach(() => vi.unstubAllEnvs());
+
+describe('live escrow release kill switch', () => {
+    it.each(['1', 'true'])('blocks releases for %s', value => {
+        vi.stubEnv('ESCROW_RELEASE_KILL_SWITCH', value);
+        expect(isEscrowReleaseKillSwitchEnabled()).toBe(true);
+    });
+    it.each(['0', 'false', ''])('allows releases for %s', value => {
+        vi.stubEnv('ESCROW_RELEASE_KILL_SWITCH', value);
+        expect(isEscrowReleaseKillSwitchEnabled()).toBe(false);
+    });
+});
 
 const production = {
     NODE_ENV: 'production',
@@ -114,3 +127,33 @@ describe('signing-authority seed environment', () => {
         ).not.toThrow();
     });
 });
+
+describe('Keycloak startup configuration', () => {
+    it.each([undefined, '', '   ', ' , , '])('rejects missing audiences: %s', audiences => {
+        expect(() =>
+            parseLcaApiEnvironment({
+                NODE_ENV: 'test',
+                IS_OFFLINE: 'true',
+                KEYCLOAK_ISSUERS: 'https://identity.example/realms/learncard',
+                KEYCLOAK_AUDIENCES: audiences,
+            })
+        ).toThrow(/KEYCLOAK_AUDIENCES/);
+    });
+    it('allows disabled Keycloak and valid issuer/audience configuration', () => {
+        expect(() =>
+            parseLcaApiEnvironment({
+                NODE_ENV: 'test',
+                IS_OFFLINE: 'true',
+                KEYCLOAK_ISSUERS: ' , ',
+            })
+        ).not.toThrow();
+        expect(() =>
+            parseLcaApiEnvironment({
+                NODE_ENV: 'test',
+                IS_OFFLINE: 'true',
+                KEYCLOAK_ISSUERS: 'https://identity.example/realms/learncard',
+                KEYCLOAK_AUDIENCES: ' , learncard-app, ',
+            })
+        ).not.toThrow();
+    });
+});

package/src/config/environment.ts

@@ -13,6 +13,9 @@ 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,
@@ -30,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,
@@ -42,6 +56,16 @@ export const lcaApiEnvironmentShape = {
     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)),
@@ -74,29 +98,15 @@ export const lcaApiEnvironmentSchema = z
         };
     })
     .superRefine((environment, context) => {
-        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',
-                });
-            }
+        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 (
@@ -133,6 +143,56 @@ export const lcaApiEnvironmentSchema = z
                 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 &&
@@ -185,6 +245,13 @@ 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 {

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);