@learncard/learn-cloud-service 2.5.35 → 2.5.36

package/lambdaApp.ts

@@ -0,0 +1,163 @@
+import serverlessHttp from 'serverless-http';
+import type { Context, APIGatewayProxyResultV2, APIGatewayProxyEventV2 } from 'aws-lambda';
+import { awsLambdaRequestHandler } from '@trpc/server/adapters/aws-lambda';
+import * as Sentry from '@sentry/serverless';
+import Fastify, { type FastifyInstance } from 'fastify';
+
+import app from './src/openapi';
+import { appRouter, createContext } from './src/app';
+import { createOpenApiAwsLambdaHandler } from './src/helpers/shim';
+import {
+    handleTrpcError,
+    sentryBeforeSend,
+    getTracesSampleRate,
+} from './src/helpers/sentry.helpers';
+import { environment } from './src/config/environment';
+import { toServerlessApplication } from './src/helpers/serverlessApplication';
+import {
+    assertShareContentEnvironmentConfiguration,
+    createShareContentRuntimeFromEnvironment,
+    registerShareContentRoutes,
+} from './src/share-content';
+
+Sentry.AWSLambda.init({
+    dsn: environment.SENTRY_DSN,
+    environment: environment.SENTRY_ENV,
+    enabled: Boolean(environment.SENTRY_DSN),
+    tracesSampleRate: getTracesSampleRate(),
+    beforeSend: sentryBeforeSend,
+    integrations: [
+        new Sentry.Integrations.Console(),
+        new Sentry.Integrations.Http({ tracing: true }),
+        new Sentry.Integrations.ContextLines(),
+        new Sentry.Integrations.Mongo(),
+    ],
+});
+
+// Fail the cold start on an enabled-but-invalid LC-2187 share-content
+// configuration; a disabled configuration is a no-op.
+assertShareContentEnvironmentConfiguration();
+
+let shareContentProxyPromise: Promise<ReturnType<typeof serverlessHttp> | null> | null = null;
+
+/**
+ * Lazy per-container boot for the LC-2187 service routes. Resolving the runtime
+ * awaits repository index initialization and opens Redis only when enabled, so a
+ * disabled deployment installs nothing and returns 404 for every internal path.
+ */
+const getShareContentProxy = async (): Promise<ReturnType<typeof serverlessHttp> | null> => {
+    if (!shareContentProxyPromise) {
+        shareContentProxyPromise = (async () => {
+            const runtime = await createShareContentRuntimeFromEnvironment();
+
+            if (!runtime.enabled) return null;
+
+            const shareContentApp: FastifyInstance = Fastify({ maxParamLength: 5000 });
+            await registerShareContentRoutes(shareContentApp, runtime);
+            await shareContentApp.ready();
+
+            return serverlessHttp(toServerlessApplication(shareContentApp.server));
+        })();
+    }
+
+    return shareContentProxyPromise;
+};
+
+export const shareContentHandler = async (
+    event: APIGatewayProxyEventV2,
+    context: Context
+): Promise<APIGatewayProxyResultV2> => {
+    let proxy: ReturnType<typeof serverlessHttp> | null;
+
+    try {
+        proxy = await getShareContentProxy();
+    } catch {
+        // Never return a raw boot error. Allow a later invocation to retry.
+        shareContentProxyPromise = null;
+
+        return {
+            statusCode: 503,
+            headers: { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' },
+            body: JSON.stringify({ ok: false, error: 'UNAVAILABLE' }),
+        };
+    }
+
+    if (!proxy) {
+        return { statusCode: 404, headers: { 'Cache-Control': 'no-store' }, body: '' };
+    }
+
+    return proxy(event, context);
+};
+
+export const swaggerUiHandler = serverlessHttp(toServerlessApplication(app), {
+    basePath: '/docs',
+});
+
+export const _openApiHandler = createOpenApiAwsLambdaHandler({
+    router: appRouter,
+    responseMeta: () => {
+        return {
+            headers: {
+                'Access-Control-Allow-Origin': '*',
+                'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+                'Access-Control-Allow-Headers': 'Authorization, Content-Type',
+            },
+        };
+    },
+    createContext,
+    onError: handleTrpcError,
+});
+
+export const _trpcHandler = awsLambdaRequestHandler({
+    allowMethodOverride: true,
+    router: appRouter,
+    createContext,
+    onError: handleTrpcError,
+    responseMeta: () => {
+        return {
+            headers: {
+                'Access-Control-Allow-Origin': '*',
+                'Access-Control-Allow-Methods': '*',
+                'Access-Control-Allow-Headers': 'authorization',
+            },
+        };
+    },
+});
+
+export const openApiHandler = Sentry.AWSLambda.wrapHandler(
+    async (event: APIGatewayProxyEventV2, context: Context): Promise<APIGatewayProxyResultV2> => {
+        if (event.requestContext.http.method === 'OPTIONS') {
+            return {
+                statusCode: 200,
+                headers: {
+                    'Access-Control-Allow-Origin': '*',
+                    'Access-Control-Allow-Headers': '*',
+                    'Access-Control-Allow-Methods': '*',
+                },
+            };
+        }
+
+        context.callbackWaitsForEmptyEventLoop = false;
+
+        return _openApiHandler(event, context);
+    }
+);
+
+export const trpcHandler = Sentry.AWSLambda.wrapHandler(
+    async (event: APIGatewayProxyEventV2, context: Context): Promise<APIGatewayProxyResultV2> => {
+        if (event.requestContext.http.method === 'OPTIONS') {
+            return {
+                statusCode: 200,
+                headers: {
+                    'Access-Control-Allow-Origin': '*',
+                    'Access-Control-Allow-Headers': '*',
+                    'Access-Control-Allow-Methods': '*',
+                },
+            };
+        }
+
+        context.callbackWaitsForEmptyEventLoop = false;
+
+        return _trpcHandler(event, context);
+    }
+);

package/oidcLambda.test.ts

@@ -0,0 +1,41 @@
+import type { APIGatewayProxyEventV2, Context } from 'aws-lambda';
+import { beforeEach, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({ bootstrap: vi.fn(), getApp: vi.fn(), handler: vi.fn() }));
+
+vi.mock('@learncard/service-config', () => ({ bootstrapLambda: mocks.bootstrap }));
+vi.mock('./src/config/stageConfig', () => ({ base: {}, stages: { dev: {}, production: {} } }));
+vi.mock('./oidcLambdaApp', () => ({ oidcHandler: mocks.handler }));
+
+beforeEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    mocks.bootstrap.mockReturnValue(mocks.getApp);
+    mocks.getApp.mockResolvedValue({ oidcHandler: mocks.handler });
+    mocks.handler.mockResolvedValue({ statusCode: 200 });
+});
+
+it('bootstraps the oidc app with checked-in stage config and the deploy stage', async () => {
+    vi.stubEnv('AWS_LAMBDA_FUNCTION_NAME', 'learn-cloud-service-dev-oidc');
+    vi.stubEnv('LAMBDA_STAGE', 'dev');
+    await import('./oidcLambda');
+    expect(mocks.bootstrap).toHaveBeenCalledTimes(1);
+    expect(mocks.bootstrap).toHaveBeenCalledWith({
+        base: {},
+        stages: { dev: {}, production: {} },
+        stage: 'dev',
+        importApp: expect.any(Function),
+    });
+    vi.unstubAllEnvs();
+});
+
+it('resolves the app once per cold start and forwards every argument', async () => {
+    const { oidcHandler } = await import('./oidcLambda');
+    const event = {} as APIGatewayProxyEventV2;
+    const context = {} as Context;
+    const callback = vi.fn();
+    await oidcHandler(event, context, callback);
+    await oidcHandler(event, context, callback);
+    expect(mocks.getApp).toHaveBeenCalledTimes(2);
+    expect(mocks.handler).toHaveBeenLastCalledWith(event, context, callback);
+});

package/oidcLambda.ts

@@ -1,23 +1,17 @@
-import serverlessHttp from 'serverless-http';
-import * as Sentry from '@sentry/serverless';
+import { bootstrapLambda } from '@learncard/service-config';
 
-import oidcApp from './src/oidc';
-import { environment } from './src/config/environment';
-import { toServerlessApplication } from './src/helpers/serverlessApplication';
+import { base, stages } from './src/config/stageConfig';
 
-Sentry.AWSLambda.init({
-    dsn: environment.SENTRY_DSN,
-    environment: environment.SENTRY_ENV,
-    enabled: Boolean(environment.SENTRY_DSN),
-    tracesSampleRate: 1.0,
-    integrations: [
-        new Sentry.Integrations.Console(),
-        new Sentry.Integrations.Http(),
-        new Sentry.Integrations.ContextLines(),
-        new Sentry.Integrations.Mongo(),
-    ],
+type OidcApp = typeof import('./oidcLambdaApp');
+
+const getApplication = bootstrapLambda<OidcApp>({
+    base,
+    stages,
+    stage: process.env.AWS_LAMBDA_FUNCTION_NAME
+        ? process.env.LAMBDA_STAGE
+        : process.env.CONFIG_STAGE,
+    importApp: () => import('./oidcLambdaApp'),
 });
 
-export const oidcHandler = Sentry.AWSLambda.wrapHandler(
-    serverlessHttp(toServerlessApplication(oidcApp))
-);
+export const oidcHandler = async (...args: Parameters<OidcApp['oidcHandler']>) =>
+    (await getApplication()).oidcHandler(...args);

package/oidcLambdaApp.ts

@@ -0,0 +1,23 @@
+import serverlessHttp from 'serverless-http';
+import * as Sentry from '@sentry/serverless';
+
+import oidcApp from './src/oidc';
+import { environment } from './src/config/environment';
+import { toServerlessApplication } from './src/helpers/serverlessApplication';
+
+Sentry.AWSLambda.init({
+    dsn: environment.SENTRY_DSN,
+    environment: environment.SENTRY_ENV,
+    enabled: Boolean(environment.SENTRY_DSN),
+    tracesSampleRate: 1.0,
+    integrations: [
+        new Sentry.Integrations.Console(),
+        new Sentry.Integrations.Http(),
+        new Sentry.Integrations.ContextLines(),
+        new Sentry.Integrations.Mongo(),
+    ],
+});
+
+export const oidcHandler = Sentry.AWSLambda.wrapHandler(
+    serverlessHttp(toServerlessApplication(oidcApp))
+);

package/package.json

@@ -1,11 +1,11 @@
 {
     "name": "@learncard/learn-cloud-service",
-    "version": "2.5.35",
+    "version": "2.5.36",
     "description": "",
     "engines": {
         "node": ">=24.12 <25"
     },
-    "packageManager": "bun@1.3.14",
+    "packageManager": "bun@1.4.2",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "scripts": {
@@ -61,27 +61,28 @@
         "serverless-offline": "^12.0.4",
         "serverless-prune-plugin": "^2.1.0",
         "shx": "^0.3.4",
-        "swagger-ui-dist": "^5.18.2",
         "testcontainers": "^9.1.1"
     },
     "dependencies": {
         "@fastify/cors": "^11.2.0",
         "@fastify/rate-limit": "^10.2.0",
         "@fastify/static": "^10.1.1",
-        "@learncard/core": "9.4.37",
-        "@learncard/crypto-plugin": "1.1.37",
-        "@learncard/did-web-plugin": "1.1.37",
-        "@learncard/didkey-plugin": "1.1.37",
-        "@learncard/didkit-plugin": "^1.10.2",
-        "@learncard/didkit-plugin-node": "0.3.2",
-        "@learncard/encryption-plugin": "1.1.37",
-        "@learncard/expiration-plugin": "1.2.37",
-        "@learncard/helpers": "1.6.1",
-        "@learncard/learn-card-plugin": "1.2.37",
-        "@learncard/types": "5.22.0",
-        "@learncard/vc-plugin": "1.6.3",
-        "@learncard/vc-templates-plugin": "1.1.37",
+        "@learncard/core": "9.4.38",
+        "@learncard/crypto-plugin": "1.1.38",
+        "@learncard/did-web-plugin": "1.1.38",
+        "@learncard/didkey-plugin": "1.1.38",
+        "@learncard/didkit-plugin": "^1.10.3",
+        "@learncard/didkit-plugin-node": "0.3.3",
+        "@learncard/encryption-plugin": "1.1.38",
+        "@learncard/expiration-plugin": "1.2.38",
+        "@learncard/helpers": "1.6.2",
+        "@learncard/learn-card-plugin": "1.2.38",
+        "@learncard/service-config": "0.1.1",
+        "@learncard/types": "5.23.0",
+        "@learncard/vc-plugin": "1.6.4",
+        "@learncard/vc-templates-plugin": "1.1.38",
         "@sentry/serverless": "7.61.0",
+        "@traversable/zod": "^0.0.57",
         "@trpc/server": "11.8.0",
         "@types/lodash": "^4.14.191",
         "@xapi/xapi": "^3.0.0",
@@ -103,6 +104,7 @@
         "neo4j-driver": "^4.3.0",
         "neogma": "^1.11.1",
         "simple-redis-mutex": "^1.3.1",
+        "swagger-ui-dist": "^5.18.2",
         "trpc-to-openapi": "^3.1.0",
         "tsc-alias": "^1.8.10",
         "zod-openapi": "^5.0.1",

package/serverless-local.yml

@@ -40,9 +40,11 @@ provider:
     timeout: 20
     stage: ${opt:stage, "dev"}
     region: ${opt:region, "us-east-1"}
+    # serverless-offline sets AWS_LAMBDA_FUNCTION_NAME; stage config stays opt-in locally.
     environment:
         PORT: ${env:PORT, 3000}
-        LAMBDA_STAGE: ${opt:stage, "dev"}
+        LAMBDA_STAGE: ${env:CONFIG_STAGE, ''}
+        CONFIG_STAGE: ${env:CONFIG_STAGE, ''}
         LEARN_CLOUD_SEED: ${env:LEARN_CLOUD_SEED}
         LEARN_CLOUD_MONGO_URI: ${env:LEARN_CLOUD_MONGO_URI}
         LEARN_CLOUD_MONGO_DB_NAME: ${env:LEARN_CLOUD_MONGO_DB_NAME}

package/serverless.function-env.cjs

@@ -0,0 +1,31 @@
+const { functionEnvironment } = require('@learncard/service-config/function-env.cjs');
+
+const PROVIDER_SECRETS = [
+    'LEARN_CLOUD_SEED',
+    'LEARN_CLOUD_MONGO_URI',
+    'LEARN_CLOUD_MONGO_DB_NAME',
+    'RSA_PRIVATE_KEY',
+    'RSA_PUBLIC_KEY',
+    'JWT_SIGNING_KEY',
+    'XAPI_ENDPOINT',
+    'XAPI_USERNAME',
+    'XAPI_PASSWORD',
+    'SENTRY_DSN',
+];
+
+// Serverless v3 supplies CLI options to file functions and preserves CF intrinsics.
+// Every function shares the one generated execution role, so the bundle pointer and the
+// credential fallbacks sit together on the provider. Bundle mode emits only infra plus the
+// pointer; fallback mode retains the per-value GitHub secrets. XAPI_ENDPOINT is a
+// user-classified bundle secret (fallback env only), not infra, so it rides the fallback
+// list and is dropped once a bundle is configured. Non-secret per-stage values are applied
+// from checked-in stage config at cold start, never forwarded here.
+exports.provider = ({ options = {}, env = process.env } = {}) => ({
+    LAMBDA_STAGE: options.stage || 'dev',
+    // Non-secret product selector for the shared stage files (config.<tenant>.<stage>.json).
+    CONFIG_TENANT: env.CONFIG_TENANT || 'learncard',
+    PORT: String(options.httpPort || '3000'),
+    REDIS_HOST: { 'Fn::GetAtt': ['ElasticCacheCluster', 'RedisEndpoint.Address'] },
+    REDIS_PORT: { 'Fn::GetAtt': ['ElasticCacheCluster', 'RedisEndpoint.Port'] },
+    ...functionEnvironment({ always: ['RUNTIME_SECRETS_ID'], fallback: PROVIDER_SECRETS, env }),
+});

package/serverless.yml

@@ -118,35 +118,19 @@ provider:
     timeout: 29
     stage: ${opt:stage, "dev"}
     region: ${opt:region, "us-east-1"}
-    environment:
-        PORT: ${env:PORT, 3000}
-        LAMBDA_STAGE: ${opt:stage, "dev"}
-        LEARN_CLOUD_SEED: ${env:LEARN_CLOUD_SEED}
-        LEARN_CLOUD_MONGO_URI: ${env:LEARN_CLOUD_MONGO_URI}
-        LEARN_CLOUD_MONGO_DB_NAME: ${env:LEARN_CLOUD_MONGO_DB_NAME}
-        XAPI_ENDPOINT: ${env:XAPI_ENDPOINT, "false"}
-        XAPI_USERNAME: ${env:XAPI_USERNAME, "false"}
-        XAPI_PASSWORD: ${env:XAPI_PASSWORD, "false"}
-        RSA_PRIVATE_KEY: ${env:RSA_PRIVATE_KEY, "false"}
-        RSA_PUBLIC_KEY: ${env:RSA_PUBLIC_KEY, "false"}
-        SERVER_URL: ${env:SERVER_URL, "https://cloud.learncard.com"}
-        JWT_SIGNING_KEY: ${env:JWT_SIGNING_KEY, ""}
-        SENTRY_DSN: ${env:SENTRY_DSN}
-        SENTRY_ENV: ${env:SENTRY_ENV}
-        SENTRY_AUTH_TOKEN: ${env:SENTRY_AUTH_TOKEN}
-        SENTRY_ORG: ${env:SENTRY_ORG}
-        SENTRY_PROJECT: ${env:SENTRY_PROJECT}
-        REDIS_HOST:
-            'Fn::GetAtt': [ElasticCacheCluster, RedisEndpoint.Address]
-        REDIS_PORT:
-            'Fn::GetAtt': [ElasticCacheCluster, RedisEndpoint.Port]
-        # LC-2187 service-only share-content routes. Require an explicit
-        # audience, service DID/key-method allowlists and
-        # per-service namespace bindings. No secret material is passed here.
-        SHARE_CONTENT_AUDIENCE: ${env:SHARE_CONTENT_AUDIENCE, ''}
-        SHARE_CONTENT_SERVICE_DIDS: ${env:SHARE_CONTENT_SERVICE_DIDS, ''}
-        SHARE_CONTENT_VERIFICATION_METHODS: ${env:SHARE_CONTENT_VERIFICATION_METHODS, ''}
-        SHARE_CONTENT_NAMESPACE_BINDINGS: ${env:SHARE_CONTENT_NAMESPACE_BINDINGS, ''}
+    # Infra values and the CF intrinsics live in the helper alongside the bundle pointer.
+    # Bundle mode emits only infra + RUNTIME_SECRETS_ID; fallback mode retains the GitHub
+    # secrets. Non-secret per-stage values (SENTRY_ENV, SERVER_URL, SHARE_CONTENT_*) are
+    # applied from checked-in stage config at cold start, not passed here.
+    environment: ${file(./serverless.function-env.cjs):provider}
+    # Only this generated role runs every function; grant it read of the runtime bundle.
+    iam:
+        role:
+            statements:
+                - Effect: Allow
+                  Action: secretsmanager:GetSecretValue
+                  Resource:
+                      Fn::Sub: arn:${AWS::Partition}:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:learn-cloud-service/${sls:stage}/runtime-secrets-*
     tracing:
         apiGateway: true
         lambda: true

package/src/config/applyDockerStageConfig.ts

@@ -0,0 +1,6 @@
+import { applyLearnCloudStageConfig } 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.
+applyLearnCloudStageConfig(process.env.CONFIG_STAGE);

package/src/config/serverlessFunctionEnv.test.ts

@@ -0,0 +1,81 @@
+import { createRequire } from 'node:module';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const require = createRequire(import.meta.url);
+const functions: {
+    provider: (context?: {
+        options: { stage: string; httpPort?: string };
+    }) => Record<string, unknown>;
+} = require('../../serverless.function-env.cjs');
+
+beforeEach(() => {
+    vi.stubEnv('RUNTIME_SECRETS_ID', '');
+    vi.stubEnv('LEARN_CLOUD_SEED', 'seed');
+    vi.stubEnv('LEARN_CLOUD_MONGO_URI', 'mongodb://localhost:27017');
+    // XAPI_ENDPOINT is a user-classified bundle secret, so populate a stale fallback value
+    // to prove it never leaks onto the provider once a runtime bundle is configured.
+    vi.stubEnv('XAPI_ENDPOINT', 'https://stale.xapi.example.com');
+});
+afterEach(() => vi.unstubAllEnvs());
+
+describe('learn-cloud-service serverless function environments', () => {
+    it('omits all credential fallbacks in bundle mode', () => {
+        vi.stubEnv('RUNTIME_SECRETS_ID', 'learn-cloud-service/dev/runtime-secrets');
+        expect(Object.keys(functions.provider()).sort()).toEqual([
+            'CONFIG_TENANT',
+            'LAMBDA_STAGE',
+            'PORT',
+            'REDIS_HOST',
+            'REDIS_PORT',
+            'RUNTIME_SECRETS_ID',
+        ]);
+    });
+
+    it('drops the XAPI_ENDPOINT bundle secret in bundle mode even when a stale fallback is set', () => {
+        vi.stubEnv('RUNTIME_SECRETS_ID', 'learn-cloud-service/dev/runtime-secrets');
+        expect(functions.provider()).not.toHaveProperty('XAPI_ENDPOINT');
+    });
+
+    it('retains the existing provider credentials only in fallback mode', () => {
+        const provider = functions.provider();
+        expect(provider.LEARN_CLOUD_SEED).toBe('seed');
+        expect(provider.LEARN_CLOUD_MONGO_URI).toBe('mongodb://localhost:27017');
+        expect(provider.XAPI_ENDPOINT).toBe('https://stale.xapi.example.com');
+        expect(provider.RUNTIME_SECRETS_ID).toBeUndefined();
+    });
+
+    it('preserves the CloudFormation Redis intrinsics and CLI options', () => {
+        const provider = functions.provider({ options: { stage: 'production', httpPort: '5100' } });
+        expect(provider.LAMBDA_STAGE).toBe('production');
+        expect(provider.PORT).toBe('5100');
+        expect(provider.REDIS_HOST).toEqual({
+            'Fn::GetAtt': ['ElasticCacheCluster', 'RedisEndpoint.Address'],
+        });
+        expect(provider.REDIS_PORT).toEqual({
+            'Fn::GetAtt': ['ElasticCacheCluster', 'RedisEndpoint.Port'],
+        });
+    });
+
+    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' };
+            const result = await source.resolve({
+                serviceDir: new URL('../../', import.meta.url).pathname,
+                params: [new URL('../../serverless.function-env.cjs', import.meta.url).pathname],
+                address: 'provider',
+                options,
+                resolveConfigurationProperty: vi.fn(),
+                resolveVariable: vi.fn(),
+            });
+            expect(result.value).toEqual(functions.provider({ options }));
+            expect(result.value.LAMBDA_STAGE).toBe('production');
+            expect(result.value.PORT).toBe('5100');
+            expect(result.value.REDIS_HOST).toEqual({
+                'Fn::GetAtt': ['ElasticCacheCluster', 'RedisEndpoint.Address'],
+            });
+        }
+    );
+});

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 { applyLearnCloudStageConfig, stages } = await import('./stageConfig');
+    for (const key of Object.keys(stages.dev)) {
+        if (key !== 'SENTRY_ENV') vi.stubEnv(key, '');
+    }
+    applyLearnCloudStageConfig('dev');
+    expect(process.env.SENTRY_ENV).toBe('self-hosted');
+    expect(process.env.SERVER_URL).toBe(stages.dev.SERVER_URL);
+});
+
+it('does not select a deployed stage for an unknown local stage', async () => {
+    const { applyLearnCloudStageConfig } = await import('./stageConfig');
+    vi.stubEnv('SERVER_URL', '');
+    applyLearnCloudStageConfig('unregistered-self-hosted-stage');
+    expect(process.env.SERVER_URL).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 applyLearnCloudStageConfig = (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';
 

package/vitest.config.ts

@@ -7,6 +7,9 @@ export default createVitestConfig(nodePreset, {
             'test/query.helpers.spec.ts',
             'test/xapi.helpers.spec.ts',
             'test/share-content-auth.spec.ts',
+            'src/config/stageConfig.test.ts',
+            'src/config/serverlessFunctionEnv.test.ts',
+            '*Lambda.test.ts',
         ],
     },
 });

package/xApiLambda.test.ts

@@ -0,0 +1,41 @@
+import type { APIGatewayProxyEventV2, Context } from 'aws-lambda';
+import { beforeEach, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({ bootstrap: vi.fn(), getApp: vi.fn(), handler: vi.fn() }));
+
+vi.mock('@learncard/service-config', () => ({ bootstrapLambda: mocks.bootstrap }));
+vi.mock('./src/config/stageConfig', () => ({ base: {}, stages: { dev: {}, production: {} } }));
+vi.mock('./xApiLambdaApp', () => ({ xApiHandler: mocks.handler }));
+
+beforeEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    mocks.bootstrap.mockReturnValue(mocks.getApp);
+    mocks.getApp.mockResolvedValue({ xApiHandler: mocks.handler });
+    mocks.handler.mockResolvedValue({ statusCode: 200 });
+});
+
+it('bootstraps the xApi app with checked-in stage config and the deploy stage', async () => {
+    vi.stubEnv('AWS_LAMBDA_FUNCTION_NAME', 'learn-cloud-service-dev-xapi');
+    vi.stubEnv('LAMBDA_STAGE', 'dev');
+    await import('./xApiLambda');
+    expect(mocks.bootstrap).toHaveBeenCalledTimes(1);
+    expect(mocks.bootstrap).toHaveBeenCalledWith({
+        base: {},
+        stages: { dev: {}, production: {} },
+        stage: 'dev',
+        importApp: expect.any(Function),
+    });
+    vi.unstubAllEnvs();
+});
+
+it('resolves the app once per cold start and forwards every argument', async () => {
+    const { xApiHandler } = await import('./xApiLambda');
+    const event = {} as APIGatewayProxyEventV2;
+    const context = {} as Context;
+    const callback = vi.fn();
+    await xApiHandler(event, context, callback);
+    await xApiHandler(event, context, callback);
+    expect(mocks.getApp).toHaveBeenCalledTimes(2);
+    expect(mocks.handler).toHaveBeenLastCalledWith(event, context, callback);
+});