@learncard/lca-api-service 1.3.2 → 1.5.0

package/scripts/provision-keycloak-users.ts

@@ -0,0 +1,419 @@
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { z } from 'zod';
+import { ObjectId, type Collection } from 'mongodb';
+import { client } from '../src/mongo';
+import { getUserKeysCollection, type MongoUserKeyType } from '../src/models/UserKey';
+import { getAuthSubjectsCollection, getOrCreateAuthSubject } from '../src/models/AuthSubject';
+import { maskEmail } from '../src/helpers/maskEmail';
+import { createKeycloakAdmin } from './keycloak-admin';
+import { setTimeout } from 'node:timers/promises';
+import {
+    fetchFirebaseUsers,
+    findProviderLinkConflicts,
+    linkFirebaseProviders,
+    type FirebaseReader,
+    type FirebaseUser,
+    type ProviderLinkSummary,
+} from './keycloak-provider-links';
+
+export interface ProvisionOptions {
+    apply?: boolean;
+    email?: string;
+    limit?: number;
+    after?: string;
+    linkProviders?: boolean;
+}
+export interface ProvisionSummary extends ProviderLinkSummary {
+    processed: number;
+    skipped: number;
+    refused: number;
+    mapped: number;
+    missingMappings: number;
+}
+const log = (message: string): void => {
+    process.stdout.write(`${message}\n`);
+};
+const escapeRegex = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+type ProvisionKey = Omit<MongoUserKeyType, '_id'> & { _id: ObjectId };
+
+const loadProvisioningBatch = async (
+    source: AsyncIterator<ProvisionKey>,
+    firebase?: FirebaseReader
+): Promise<{ batch: ProvisionKey[]; firebaseUsers?: Map<string, FirebaseUser> }> => {
+    const batch: ProvisionKey[] = [];
+    for (let index = 0; index < (firebase ? 100 : 1); index++) {
+        const item = await source.next();
+        if (item.done) break;
+        batch.push(item.value);
+    }
+    const firebaseUsers =
+        firebase && batch.length
+            ? await fetchFirebaseUsers(
+                  batch.flatMap(key =>
+                      key.authProviders
+                          .filter(provider => provider.type === 'firebase')
+                          .map(provider => provider.id)
+                  ),
+                  firebase
+              )
+            : undefined;
+    return { batch, firebaseUsers };
+};
+
+const getFirebaseReader = async (): Promise<FirebaseReader> => {
+    const { environment } = await import('../src/config/environment');
+    // Validate before importing the legacy initializer, which logs raw JSON parse errors.
+    try {
+        z.object({})
+            .passthrough()
+            .parse(JSON.parse(environment.GOOGLE_APPLICATION_CREDENTIAL ?? ''));
+    } catch {
+        throw new Error('Valid existing Firebase Admin credential JSON is required');
+    }
+    const { default: app } = await import('../src/firebase');
+    if (!app)
+        throw new Error('Existing Firebase Admin credentials are required for provider linking');
+    return app.auth();
+};
+
+/** Offline operator migration, never a runtime email-based identity fallback. */
+export const provisionKeycloakUsers = async (
+    options: ProvisionOptions = {},
+    dependencies: {
+        firebase?: FirebaseReader;
+        admin?: Awaited<ReturnType<typeof createKeycloakAdmin>>;
+    } = {}
+): Promise<ProvisionSummary> => {
+    const email =
+        options.email === undefined
+            ? undefined
+            : z.email().parse(options.email.trim().toLowerCase());
+    const limit =
+        options.limit === undefined ? undefined : z.number().int().positive().parse(options.limit);
+    const after =
+        options.after === undefined
+            ? undefined
+            : new ObjectId(
+                  z
+                      .string()
+                      .regex(/^[0-9a-fA-F]{24}$/)
+                      .parse(options.after)
+              );
+    let lastProcessedId = after?.toHexString();
+    const summary: ProvisionSummary = {
+        processed: 0,
+        skipped: 0,
+        refused: 0,
+        mapped: 0,
+        missingMappings: 0,
+        linked: 0,
+        alreadyLinked: 0,
+        conflicts: 0,
+        noSocialProvider: 0,
+        wouldLink: 0,
+    };
+    try {
+        const linkProviders = options.linkProviders ?? true;
+        const firebase = linkProviders
+            ? (dependencies.firebase ?? (await getFirebaseReader()))
+            : undefined;
+        const admin = dependencies.admin ?? (await createKeycloakAdmin());
+        // Mongo assigns ObjectIds on insert; the model's optional string _id describes serialized data.
+        const keys = getUserKeysCollection() as unknown as Collection<
+            Omit<MongoUserKeyType, '_id'>
+        >;
+        const subjects = getAuthSubjectsCollection();
+        const cursor = keys
+            .find({
+                'authProviders.type': 'firebase',
+                ...(after ? { _id: { $gt: after } } : {}),
+                ...(email
+                    ? {
+                          'contactMethod.type': 'email',
+                          'contactMethod.value': {
+                              $regex: `^${escapeRegex(email)}$`,
+                              $options: 'i',
+                          },
+                      }
+                    : {}),
+            })
+            .sort({ _id: 1 });
+        if (limit) cursor.limit(limit);
+        log(`Mode: ${options.apply ? 'APPLY' : 'DRY RUN (no resource writes)'}\nContact\tResult`);
+        const iterator = cursor[Symbol.asyncIterator]();
+        try {
+            while (true) {
+                const { batch, firebaseUsers } = await loadProvisioningBatch(iterator, firebase);
+                if (!batch.length) break;
+                for (const key of batch) {
+                    let failed = false;
+                    try {
+                        summary.processed++;
+                        if (key.contactMethod.type !== 'email') {
+                            summary.skipped++;
+                            log('[phone-only]\tSKIP: phone OTP deferred');
+                            continue;
+                        }
+                        const normalized = key.contactMethod.value.trim().toLowerCase();
+                        const label = maskEmail(normalized);
+                        const refuse = (reason: string): void => {
+                            summary.refused++;
+                            log(`${label}\tREFUSED: ${reason}`);
+                        };
+                        if (!z.email().safeParse(normalized).success) {
+                            refuse('invalid email');
+                            continue;
+                        }
+                        const firebaseIds = key.authProviders
+                            .filter(provider => provider.type === 'firebase')
+                            .map(provider => provider.id);
+                        const firebaseRecords = firebaseIds.map(id => firebaseUsers?.get(id));
+                        if (
+                            linkProviders &&
+                            (!firebaseIds.length ||
+                                firebaseRecords.some(
+                                    record =>
+                                        !record ||
+                                        record.disabled ||
+                                        !record.emailVerified ||
+                                        record.email?.trim().toLowerCase() !== normalized
+                                ))
+                        ) {
+                            refuse(
+                                'Firebase UID missing, disabled, unverified, or email ownership differs'
+                            );
+                            continue;
+                        }
+                        const linkSocial = async (userId?: string): Promise<void> => {
+                            if (!linkProviders) return;
+                            await linkFirebaseProviders({
+                                userId,
+                                providers: firebaseRecords.flatMap(
+                                    record => record?.providerData ?? []
+                                ),
+                                apply: options.apply ?? false,
+                                admin,
+                                log: message => log(`${label}\t${message}`),
+                                summary,
+                            });
+                        };
+                        // Contact indexes are deliberately nonunique; recycled/ambiguous addresses need manual review.
+                        const peers = await keys.countDocuments({
+                            'contactMethod.type': 'email',
+                            'contactMethod.value': {
+                                $regex: `^\\s*${escapeRegex(normalized)}\\s*$`,
+                                $options: 'i',
+                            },
+                        });
+                        if (peers !== 1) {
+                            refuse('ambiguous UserKey email; manual identity review required');
+                            continue;
+                        }
+                        const identityKey = `email:${normalized}`;
+                        let subject = await subjects.findOne({ identityKey });
+                        const matches = await admin.findUsers(normalized);
+                        if (matches.length > 1) {
+                            refuse('ambiguous Keycloak email');
+                            continue;
+                        }
+                        let user = matches[0];
+                        if (
+                            user &&
+                            (user.email?.toLowerCase() !== normalized ||
+                                !user.enabled ||
+                                !user.emailVerified)
+                        ) {
+                            refuse('existing Keycloak user is disabled or email is not verified');
+                            continue;
+                        }
+                        const links = user ? await admin.links(user.id) : [];
+                        if (linkProviders) {
+                            const conflicts = findProviderLinkConflicts(
+                                firebaseRecords.flatMap(record => record?.providerData ?? []),
+                                links
+                            );
+                            if (conflicts.length) {
+                                summary.conflicts += conflicts.length;
+                                refuse(
+                                    `${conflicts.join(', ')} identity differs; manual review required`
+                                );
+                                continue;
+                            }
+                        }
+                        const link = links.find(item => item.identityProvider === 'lca-api');
+                        if (link && link.userId !== subject?.subject) {
+                            refuse('existing lca-api link differs');
+                            continue;
+                        }
+                        const mappings = key.authProviders.filter(
+                            provider => provider.type === 'keycloak'
+                        );
+                        if (mappings.some(mapping => mapping.id !== user?.id)) {
+                            refuse('existing keycloak mapping differs');
+                            continue;
+                        }
+                        if (
+                            user &&
+                            (await keys.findOne({
+                                _id: { $ne: key._id },
+                                authProviders: { $elemMatch: { type: 'keycloak', id: user.id } },
+                            }))
+                        ) {
+                            refuse('Keycloak identity already belongs to another UserKey');
+                            continue;
+                        }
+                        const actions = [
+                            !subject && 'create subject',
+                            !user && 'create user',
+                            !link && 'link lca-api',
+                            !mappings.length && 'append mapping',
+                        ].filter(Boolean);
+                        if (!options.apply) {
+                            log(
+                                `${label}\t${actions.length ? `PLAN: ${actions.join(', ')}` : 'unchanged'}`
+                            );
+                            await linkSocial(user?.id);
+                            continue;
+                        }
+                        // Do not call getOrCreate for an existing subject: it updates lastLoginAt.
+                        subject ??= await getOrCreateAuthSubject(identityKey, {
+                            email: normalized,
+                            emailVerified: true,
+                        });
+                        if (!user) {
+                            const phone = z
+                                .object({
+                                    phone: z.string().optional(),
+                                    phoneNumber: z.string().optional(),
+                                })
+                                .parse(key);
+                            const number = phone.phone ?? phone.phoneNumber;
+                            await admin.request('/users', {
+                                method: 'POST',
+                                body: JSON.stringify({
+                                    username: normalized,
+                                    email: normalized,
+                                    emailVerified: true,
+                                    enabled: true,
+                                    ...(number
+                                        ? {
+                                              attributes: {
+                                                  phone_number: [number],
+                                                  // UserKey has no canonical secondary-phone verification proof.
+                                                  // Never promote a legacy string into a verified identity claim.
+                                                  phone_number_verified: ['false'],
+                                              },
+                                          }
+                                        : {}),
+                                }),
+                            });
+                            const created = await admin.findUsers(normalized);
+                            if (created.length !== 1)
+                                throw new Error('Cannot resolve newly provisioned user');
+                            user = created[0]!;
+                        }
+                        if (!link)
+                            await admin.request(
+                                `/users/${encodeURIComponent(user.id)}/federated-identity/lca-api`,
+                                {
+                                    method: 'POST',
+                                    body: JSON.stringify({
+                                        identityProvider: 'lca-api',
+                                        userId: subject.subject,
+                                        userName: subject.subject,
+                                    }),
+                                }
+                            );
+                        if (!mappings.length) {
+                            const result = await keys.updateOne(
+                                {
+                                    _id: key._id,
+                                    authProviders: { $not: { $elemMatch: { type: 'keycloak' } } },
+                                },
+                                {
+                                    $addToSet: { authProviders: { type: 'keycloak', id: user.id } },
+                                }
+                            );
+                            if (result.modifiedCount !== 1)
+                                throw new Error('Concurrent mapping change; rerun after review');
+                            summary.mapped++;
+                        }
+                        await linkSocial(user.id);
+                        log(`${label}\t${actions.length ? actions.join(', ') : 'unchanged'}`);
+                    } catch (error) {
+                        failed = true;
+                        throw error;
+                    } finally {
+                        if (!failed) {
+                            lastProcessedId = key._id.toHexString();
+                            if (summary.processed % 100 === 0)
+                                log(`Last processed id: ${lastProcessedId}`);
+                        }
+                    }
+                }
+                if (firebase && batch.length === 100) await setTimeout(1000);
+            }
+        } finally {
+            await iterator.return?.();
+        }
+        summary.missingMappings = await keys.countDocuments({
+            'contactMethod.type': 'email',
+            'authProviders.type': { $ne: 'keycloak' },
+        });
+        log(
+            `Mapping-presence assertion: ${summary.missingMappings === 0 && summary.refused === 0 ? 'PASS' : 'FAIL'} — ${summary.missingMappings} email UserKeys lack a keycloak mapping (global, not limited by --email/--limit).`
+        );
+        log(
+            'Cutover approval: NOT EVALUATED. Presence is necessary, not sufficient; validate all existing mappings and authoritative Firebase UID ownership before cutover.'
+        );
+        return summary;
+    } finally {
+        log(`Summary: ${JSON.stringify(summary)}`);
+        log(
+            `Last processed id: ${lastProcessedId ?? '(none)'}${lastProcessedId ? `; resume with --after ${lastProcessedId}` : ''}`
+        );
+    }
+};
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    try {
+        const { values } = parseArgs({
+            args: process.argv.slice(2).filter(arg => arg !== '--'),
+            options: {
+                apply: { type: 'boolean', default: false },
+                email: { type: 'string' },
+                limit: { type: 'string' },
+                after: { type: 'string' },
+                'link-providers': { type: 'boolean', default: true },
+            },
+            allowNegative: true,
+            strict: true,
+        });
+        const summary = await provisionKeycloakUsers({
+            apply: values.apply,
+            email: values.email,
+            after: values.after,
+            linkProviders: values['link-providers'],
+            limit: values.limit === undefined ? undefined : Number(values.limit),
+        });
+        if (summary.refused || summary.conflicts) process.exitCode = 1;
+    } catch (error) {
+        // Argument errors are safe to echo; driver/HTTP errors can embed connection
+        // strings or credentials, so only their type is shown.
+        const code = (error as { code?: unknown }).code;
+        const detail =
+            typeof code === 'string' && code.startsWith('ERR_PARSE_ARGS') && error instanceof Error
+                ? error.message
+                : `${error instanceof Error ? error.name : typeof error}${
+                      typeof code === 'string' ? ` (${code})` : ''
+                  }`;
+        process.stderr.write(
+            `Provisioning failed: ${detail}\nCheck arguments, service connectivity and admin permissions; rerun the dry-run before applying.\n`
+        );
+        process.exitCode = 1;
+    } finally {
+        await client.close();
+    }
+}

package/seedMigrationApp.test.ts

@@ -0,0 +1,145 @@
+import type { Context } from 'aws-lambda';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { SeedMigrationResult } from './src/types/seed-migration';
+
+const mocks = vi.hoisted(() => ({
+    connect: vi.fn(),
+    close: vi.fn(),
+    runBatch: vi.fn(),
+    mongodb: {},
+}));
+
+vi.mock('./src/mongo', () => ({
+    client: { connect: mocks.connect, close: mocks.close },
+    mongodb: mocks.mongodb,
+}));
+vi.mock('./src/config/environment', () => ({
+    environment: { SA_SEED_ENCRYPT_WRITES: true },
+}));
+vi.mock('./src/migrations/signingAuthoritySeeds', async importOriginal => ({
+    ...(await importOriginal<typeof import('./src/migrations/signingAuthoritySeeds')>()),
+    runSeedMigrationBatch: mocks.runBatch,
+}));
+
+import { handler } from './seedMigrationApp';
+import { SeedMigrationError } from './src/migrations/signingAuthoritySeeds';
+
+const result: SeedMigrationResult = {
+    phase: 'prepare',
+    done: false,
+    processed: 1,
+    counts: { total: 2, encrypted: 1, legacyOnly: 1, malformed: 0, plaintextRemaining: 2 },
+    countsReconciled: false,
+};
+
+const context = (): Context => ({
+    callbackWaitsForEmptyEventLoop: true,
+    functionName: 'seedMigration',
+    functionVersion: '$LATEST',
+    invokedFunctionArn: 'arn:aws:lambda:us-east-1:123456789012:function:seedMigration',
+    memoryLimitInMB: '1024',
+    awsRequestId: 'test-request',
+    logGroupName: 'test-group',
+    logStreamName: 'test-stream',
+    getRemainingTimeInMillis: () => 60_000,
+    done: vi.fn(),
+    fail: vi.fn(),
+    succeed: vi.fn(),
+});
+
+beforeEach(() => {
+    mocks.connect.mockReset().mockResolvedValue(undefined);
+    mocks.close.mockReset().mockResolvedValue(undefined);
+    mocks.runBatch.mockReset().mockResolvedValue(result);
+    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+});
+
+afterEach(() => vi.restoreAllMocks());
+
+describe('seed migration Lambda connection lifecycle', () => {
+    it('waits for cleanup before returning the batch result', async () => {
+        let finishClose!: () => void;
+        mocks.close.mockReturnValue(new Promise<void>(resolve => (finishClose = resolve)));
+        const resolved = vi.fn();
+        const lambdaContext = context();
+        const invocation = handler({ phase: 'prepare', batchSize: 1 }, lambdaContext).then(
+            resolved
+        );
+
+        await vi.waitFor(() => expect(mocks.close).toHaveBeenCalledOnce());
+        expect(resolved).not.toHaveBeenCalled();
+        expect(mocks.runBatch).toHaveBeenCalledWith(
+            mocks.mongodb,
+            { phase: 'prepare', batchSize: 1 },
+            { encryptedWritesEnabled: true, remainingTime: expect.any(Function) }
+        );
+        expect(lambdaContext.callbackWaitsForEmptyEventLoop).toBe(false);
+
+        finishClose();
+        await invocation;
+        expect(resolved).toHaveBeenCalledWith(result);
+    });
+
+    it('connects and closes for each sequential warm invocation', async () => {
+        await handler({ phase: 'prepare' }, context());
+        await handler({ phase: 'prepare' }, context());
+        expect(mocks.connect).toHaveBeenCalledTimes(2);
+        expect(mocks.runBatch).toHaveBeenCalledTimes(2);
+        expect(mocks.close).toHaveBeenCalledTimes(2);
+    });
+
+    it('closes after a connection failure without returning connection details', async () => {
+        mocks.connect.mockRejectedValue(new Error('mongodb://user:secret@private-host'));
+        await expect(handler({ phase: 'prepare' }, context())).rejects.toMatchObject({
+            category: 'operation_failed',
+            message: 'Signing authority seed migration stopped: operation_failed',
+        });
+        expect(mocks.runBatch).not.toHaveBeenCalled();
+        expect(mocks.close).toHaveBeenCalledOnce();
+    });
+
+    it('closes after an unexpected batch failure without returning query details', async () => {
+        mocks.runBatch.mockRejectedValue(new Error('sensitive seed query'));
+        await expect(handler({ phase: 'prepare' }, context())).rejects.toMatchObject({
+            category: 'operation_failed',
+            message: 'Signing authority seed migration stopped: operation_failed',
+        });
+        expect(mocks.close).toHaveBeenCalledOnce();
+    });
+
+    it('preserves the migration failure when cleanup also fails', async () => {
+        mocks.runBatch.mockRejectedValue(new SeedMigrationError('verification_required'));
+        mocks.close.mockRejectedValue(new Error('sensitive cleanup detail'));
+        await expect(handler({ phase: 'purge' }, context())).rejects.toMatchObject({
+            category: 'verification_required',
+        });
+        expect(mocks.close).toHaveBeenCalledOnce();
+        expect(console.error).toHaveBeenCalledExactlyOnceWith({
+            event: 'signing_authority_seed_migration_failure',
+            operation: 'migration_connection_cleanup',
+            category: 'operation_failed',
+        });
+    });
+
+    it('sanitizes cleanup errors after an otherwise successful batch', async () => {
+        mocks.close.mockRejectedValue(new Error('mongodb://user:secret@private-host'));
+        await expect(handler({ phase: 'prepare' }, context())).rejects.toMatchObject({
+            category: 'operation_failed',
+            message: 'Signing authority seed migration stopped: operation_failed',
+        });
+        expect(console.error).toHaveBeenCalledExactlyOnceWith({
+            event: 'signing_authority_seed_migration_failure',
+            operation: 'migration_connection_cleanup',
+            category: 'operation_failed',
+        });
+    });
+
+    it('rejects invalid requests before touching the database', async () => {
+        await expect(handler({ phase: 'unknown' }, context())).rejects.toMatchObject({
+            category: 'invalid_request',
+        });
+        expect(mocks.connect).not.toHaveBeenCalled();
+        expect(mocks.runBatch).not.toHaveBeenCalled();
+        expect(mocks.close).not.toHaveBeenCalled();
+    });
+});

package/seedMigrationApp.ts

@@ -0,0 +1,50 @@
+import type { Context } from 'aws-lambda';
+import { z } from 'zod';
+import { environment } from './src/config/environment';
+import { client, mongodb } from './src/mongo';
+import { runSeedMigrationBatch, SeedMigrationError } from './src/migrations/signingAuthoritySeeds';
+import type { SeedMigrationResult } from './src/types/seed-migration';
+
+const requestValidator = z
+    .object({
+        phase: z.enum(['dry-run', 'prepare', 'verify', 'purge']),
+        batchSize: z.number().int().min(1).max(100).optional(),
+    })
+    .strict();
+
+/** IAM invocation only. Never accept seeds, database URLs, key ARNs, or arbitrary queries in events. */
+export const handler = async (event: unknown, context: Context): Promise<SeedMigrationResult> => {
+    const parsed = requestValidator.safeParse(event);
+    if (!parsed.success) throw new SeedMigrationError('invalid_request');
+    context.callbackWaitsForEmptyEventLoop = false;
+    let result: SeedMigrationResult;
+    let cleanupFailed = false;
+    try {
+        await client.connect();
+        result = await runSeedMigrationBatch(mongodb, parsed.data, {
+            encryptedWritesEnabled: environment.SA_SEED_ENCRYPT_WRITES,
+            remainingTime: () => context.getRemainingTimeInMillis(),
+        });
+    } catch (error) {
+        // Mongo connection/lease errors can contain URLs or query values. Never let Lambda serialize them.
+        throw new SeedMigrationError(
+            error instanceof SeedMigrationError ? error.category : 'operation_failed'
+        );
+    } finally {
+        // This private worker releases its pool between batches, including failed connections.
+        // The module-level client reconnects when a warm invocation starts its next batch.
+        try {
+            await client.close();
+        } catch {
+            cleanupFailed = true;
+            console.error({
+                event: 'signing_authority_seed_migration_failure',
+                operation: 'migration_connection_cleanup',
+                category: 'operation_failed',
+            });
+        }
+    }
+    // Reached only after a successful batch; never mask its original failure in finally.
+    if (cleanupFailed) throw new SeedMigrationError('operation_failed');
+    return result;
+};

package/seedMigrationLambda.test.ts

@@ -0,0 +1,40 @@
+import type { 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('./seedMigrationApp', () => ({ handler: mocks.handler }));
+
+beforeEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    mocks.bootstrap.mockReturnValue(mocks.getApp);
+    mocks.getApp.mockResolvedValue({ handler: mocks.handler });
+    mocks.handler.mockResolvedValue({ phase: 'prepare', done: true });
+});
+
+it('bootstraps the migration app with checked-in stage config and the deploy stage', async () => {
+    vi.stubEnv('AWS_LAMBDA_FUNCTION_NAME', 'lca-api-production-seedMigration');
+    vi.stubEnv('LAMBDA_STAGE', 'production');
+    await import('./seedMigrationLambda');
+    expect(mocks.bootstrap).toHaveBeenCalledTimes(1);
+    expect(mocks.bootstrap).toHaveBeenCalledWith({
+        base: {},
+        stages: { dev: {}, production: {} },
+        stage: 'production',
+        importApp: expect.any(Function),
+    });
+    vi.unstubAllEnvs();
+});
+
+it('resolves the app once per cold start and forwards every argument', async () => {
+    const { handler } = await import('./seedMigrationLambda');
+    const event = { phase: 'prepare' };
+    const context = {} as Context;
+    await expect(handler(event, context)).resolves.toEqual({ phase: 'prepare', done: true });
+    await handler(event, context);
+    expect(mocks.getApp).toHaveBeenCalledTimes(2);
+    expect(mocks.handler).toHaveBeenLastCalledWith(event, context);
+});

package/seedMigrationLambda.ts

@@ -0,0 +1,19 @@
+import type { Context } from 'aws-lambda';
+import { bootstrapLambda } from '@learncard/service-config';
+
+import { base, stages } from './src/config/stageConfig';
+import type { SeedMigrationResult } from './src/types/seed-migration';
+
+type SeedMigrationApp = typeof import('./seedMigrationApp');
+
+const getApplication = bootstrapLambda<SeedMigrationApp>({
+    base,
+    stages,
+    stage: process.env.AWS_LAMBDA_FUNCTION_NAME
+        ? process.env.LAMBDA_STAGE
+        : process.env.CONFIG_STAGE,
+    importApp: () => import('./seedMigrationApp'),
+});
+
+export const handler = async (event: unknown, context: Context): Promise<SeedMigrationResult> =>
+    (await getApplication()).handler(event, context);