@learncard/lca-api-service 1.3.1 → 1.4.0

package/lambda.ts

@@ -15,8 +15,13 @@ import {
 } from './src/helpers/sentry.helpers';
 import { environment } from './src/config/environment';
 import { toServerlessApplication } from './src/helpers/serverlessApplication';
+import { ensureUserKeysIndexes, createEscrowHoldsIndexes } from './src/models';
 
-const promise = getEmptyLearnCard(); // Load WASM in for better cold starts
+const startupPromise = Promise.all([
+    getEmptyLearnCard(), // Load WASM in for better cold starts
+    ensureUserKeysIndexes(),
+    createEscrowHoldsIndexes(),
+]);
 
 const isWarmupEvent = (event: APIGatewayProxyEventV2): boolean =>
     'source' in event && event.source === 'serverless-plugin-warmup';
@@ -72,7 +77,7 @@ export const _trpcHandler = awsLambdaRequestHandler({
 
 export const openApiHandler = Sentry.AWSLambda.wrapHandler(
     async (event: APIGatewayProxyEventV2, context: Context): Promise<APIGatewayProxyResultV2> => {
-        await promise;
+        await startupPromise;
 
         if (isWarmupEvent(event)) {
             console.log('[Warmup] Initializing LearnCard...');
@@ -98,7 +103,7 @@ export const openApiHandler = Sentry.AWSLambda.wrapHandler(
 
 export const trpcHandler = Sentry.AWSLambda.wrapHandler(
     async (event: APIGatewayProxyEventV2, context: Context): Promise<APIGatewayProxyResultV2> => {
-        await promise;
+        await startupPromise;
 
         if (isWarmupEvent(event)) {
             console.log('[Warmup] Initializing LearnCard...');

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/lca-api-service",
-    "version": "1.3.1",
+    "version": "1.4.0",
     "description": "",
     "engines": {
         "node": ">=24.12 <25"
@@ -9,6 +9,10 @@
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "scripts": {
+        "migrate:sa-seeds:local": "bash scripts/migrate-signing-authority-seeds-local.sh",
+        "migrate:sa-seeds": "node scripts/migrate-signing-authority-seeds.mjs",
+        "check:sa-infra": "node scripts/check-seed-encryption-infrastructure.mjs",
+        "check:sa-redis": "node scripts/check-signing-authority-redis.mjs",
         "test": "vitest run --config vitest.config.ts",
         "test:watch": "vitest --config vitest.config.ts",
         "test:coverage": "vitest run --coverage --config vitest.config.ts",
@@ -22,7 +26,7 @@
         "start-p-5000": "PORT=5000 serverless offline --httpPort 5000 --websocketPort 5001 --lambdaPort 5002 --albPort 5003 --config serverless-local.yml",
         "dev": "bun --conditions=development --watch src/docker-entry.ts",
         "start:docker": "bun --conditions=development src/docker-entry.ts",
-        "serverless-deploy": "node ../../../scripts/prepare-didkit-native-layer.cjs && serverless deploy",
+        "serverless-deploy": "node scripts/check-seed-encryption-infrastructure.mjs && node ../../../scripts/prepare-didkit-native-layer.cjs && serverless deploy",
         "serverless-deploy-scouts": "serverless deploy --config serverless-scouts.yml"
     },
     "keywords": [],
@@ -48,25 +52,27 @@
         "shx": "^0.3.4"
     },
     "dependencies": {
+        "@aws-sdk/client-kms": "^3.1139.0",
         "@fastify/cors": "^11.2.0",
         "@fastify/static": "^10.1.1",
-        "@learncard/core": "9.4.35",
-        "@learncard/email-templates": "1.0.6",
-        "@learncard/did-web-plugin": "1.1.35",
-        "@learncard/didkit-plugin": "1.10.0",
-        "@learncard/didkit-plugin-node": "0.3.0",
-        "@learncard/init": "2.4.16",
-        "@learncard/helpers": "1.5.1",
-        "@learncard/types": "5.20.0",
+        "@learncard/core": "9.4.37",
+        "@learncard/did-web-plugin": "1.1.37",
+        "@learncard/didkit-plugin": "1.10.2",
+        "@learncard/didkit-plugin-node": "0.3.2",
+        "@learncard/email-templates": "1.2.0",
+        "@learncard/helpers": "1.6.1",
+        "@learncard/init": "2.5.1",
+        "@learncard/types": "5.22.0",
+        "@learncard/sss-key-manager": "0.2.0",
         "@sentry/serverless": "^7.61.0",
         "@trpc/server": "11.8.0",
         "@types/jsonwebtoken": "^9.0.8",
         "@types/lodash": "^4.14.191",
         "@types/node-forge": "^1.3.11",
         "axios": "^0.33.0",
-        "dotenv": "^16.0.3",
         "dag-jose-utils": "2.0.0",
         "did-jwt": "5.9.0",
+        "dotenv": "^16.0.3",
         "express": "^4.18.2",
         "fastify": "^5.8.5",
         "filestack-js": "^3.24.0",

package/scripts/check-seed-encryption-infrastructure.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+// Use Serverless's own YAML parser. An optional argument validates its packaged JSON template.
+const require = createRequire(import.meta.url);
+const serverlessRequire = createRequire(require.resolve('serverless/package.json'));
+const config = serverlessRequire('js-yaml').load(
+    readFileSync(fileURLToPath(new URL('../serverless.yml', import.meta.url)), 'utf8')
+);
+const packaged = process.argv[2] ? JSON.parse(readFileSync(process.argv[2], 'utf8')) : undefined;
+const resources = packaged?.Resources ?? config.resources.Resources;
+const key = resources.SigningAuthoritySeedKey;
+assert.equal(key.Type, 'AWS::KMS::Key');
+assert.equal(key.DeletionPolicy, 'Retain');
+assert.equal(key.UpdateReplacePolicy, 'Retain');
+assert.equal(key.Properties.KeySpec, 'SYMMETRIC_DEFAULT');
+assert.equal(key.Properties.KeyUsage, 'ENCRYPT_DECRYPT');
+assert.equal(key.Properties.EnableKeyRotation, true);
+
+const roleArn = { 'Fn::GetAtt': ['SigningAuthorityExecutionRole', 'Arn'] };
+const keyArn = { 'Fn::GetAtt': ['SigningAuthoritySeedKey', 'Arn'] };
+const purpose = { StringEquals: { 'kms:EncryptionContext:purpose': 'lca-signing-authority-seed' } };
+const statements = key.Properties.KeyPolicy.Statement;
+const use = statements.find(statement => statement.Sid === 'LcaApiSeedEncryption');
+assert.deepEqual(use.Principal, { AWS: roleArn });
+assert.deepEqual(use.Action, ['kms:GenerateDataKey', 'kms:Decrypt']);
+assert.deepEqual(use.Condition, purpose);
+const deny = statements.find(statement => statement.Sid === 'DenyOtherCryptographicPrincipals');
+assert.equal(deny.Effect, 'Deny');
+assert.equal(deny.Principal, '*');
+assert.deepEqual(deny.Condition, { ArnNotEquals: { 'aws:PrincipalArn': roleArn } });
+assert(deny.Action.includes('kms:Decrypt'));
+assert(deny.Action.includes('kms:ReEncrypt*'));
+const admin = statements.find(statement => statement.Sid === 'AccountKeyAdministration');
+assert(admin.Action.includes('kms:DeleteAlias'));
+assert(admin.Action.includes('kms:GetKeyPolicy'));
+assert(
+    !admin.Action.some(action =>
+        ['kms:*', 'kms:Decrypt', 'kms:CreateGrant', 'kms:ReEncrypt*'].includes(action)
+    )
+);
+const iam = resources.SigningAuthoritySeedKeyPolicy.Properties;
+assert.deepEqual(iam.Roles, [{ Ref: 'SigningAuthorityExecutionRole' }]);
+assert.deepEqual(iam.PolicyDocument.Statement, [
+    {
+        Effect: 'Allow',
+        Action: ['kms:GenerateDataKey', 'kms:Decrypt'],
+        Resource: keyArn,
+        Condition: purpose,
+    },
+]);
+
+const worker = config.functions.seedMigration;
+assert.equal(worker.timeout, 900);
+assert.equal(worker.reservedConcurrency, 1);
+assert.equal(worker.events, undefined);
+assert.equal(worker.url, undefined);
+assert.deepEqual(worker.vpc, config.functions.api.vpc);
+for (const name of ['api', 'trpc', 'seedMigration']) {
+    assert(config.functions[name].dependsOn.includes('SigningAuthoritySeedKeyPolicy'));
+    assert.equal(config.functions[name].role, 'SigningAuthorityExecutionRole');
+}
+for (const name of ['swagger', 'didWeb']) {
+    assert.equal(config.functions[name].role, undefined);
+}
+assert.equal(resources.SigningAuthorityExecutionRole.Type, 'AWS::IAM::Role');
+assert.deepEqual(config.provider.environment.SA_SEED_KMS_KEY_ARN, keyArn);
+assert.equal(config.provider.environment.SA_SEED_LOCAL_KEK, undefined);
+if (packaged) {
+    const lambda = resources.SeedMigrationLambdaFunction;
+    assert.equal(lambda.Properties.Timeout, 900);
+    assert.equal(lambda.Properties.ReservedConcurrentExecutions, 1);
+    assert.deepEqual(lambda.Properties.Role, roleArn);
+    assert.deepEqual(lambda.Properties.Environment.Variables.SA_SEED_KMS_KEY_ARN, keyArn);
+    for (const name of ['Api', 'Trpc']) {
+        assert.deepEqual(resources[`${name}LambdaFunction`].Properties.Role, roleArn);
+    }
+    for (const name of ['Swagger', 'DidWeb']) {
+        assert.deepEqual(resources[`${name}LambdaFunction`].Properties.Role, {
+            'Fn::GetAtt': ['IamRoleLambdaExecution', 'Arn'],
+        });
+    }
+    for (const resource of Object.values(resources)) {
+        if (resource.Type === 'AWS::Lambda::Permission' || resource.Type === 'AWS::Lambda::Url') {
+            assert(!JSON.stringify(resource).includes('SeedMigrationLambdaFunction'));
+        }
+    }
+}
+
+// Validate the entire dependency graph, including generated role/function resources when packaged.
+const references = value => {
+    const found = new Set();
+    const visit = node => {
+        if (!node || typeof node !== 'object') return;
+        if (typeof node.Ref === 'string') found.add(node.Ref);
+        const attribute = node['Fn::GetAtt'];
+        if (attribute) found.add(Array.isArray(attribute) ? attribute[0] : attribute.split('.')[0]);
+        const sub = node['Fn::Sub'];
+        const source = Array.isArray(sub) ? sub[0] : sub;
+        if (typeof source === 'string') {
+            for (const match of source.matchAll(/\$\{([^}.]+)(?:\.[^}]+)?\}/g)) found.add(match[1]);
+        }
+        for (const child of Object.values(node)) visit(child);
+    };
+    visit(value);
+    for (const name of [].concat(value.DependsOn ?? [])) found.add(name);
+    return [...found].filter(name => name in resources);
+};
+const finished = new Set();
+const visit = (name, active = new Set()) => {
+    assert(!active.has(name), `Circular CloudFormation dependency at ${name}`);
+    if (finished.has(name)) return;
+    const next = new Set(active).add(name);
+    for (const dependency of references(resources[name])) visit(dependency, next);
+    finished.add(name);
+};
+for (const name of Object.keys(resources)) visit(name);
+console.log(
+    `Seed encryption infrastructure checks passed (${packaged ? 'packaged template' : 'source config'}, ${finished.size} resources).`
+);

package/scripts/check-signing-authority-redis.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Redis from 'ioredis';
+
+const LEGACY_SEED_PATTERN = 'sa|*';
+
+/** Read key names only. SCAN can repeat keys, so only a zero count proves absence. */
+export const countLegacySigningAuthorityKeys = async redis => {
+    let cursor = '0';
+    let matches = 0;
+    const deadline = Date.now() + 60_000;
+    do {
+        if (Date.now() >= deadline) throw new Error('Redis audit timed out.');
+        const [nextCursor, keys] = await redis.scan(
+            cursor,
+            'MATCH',
+            LEGACY_SEED_PATTERN,
+            'COUNT',
+            500
+        );
+        matches += keys.length;
+        cursor = nextCursor;
+    } while (cursor !== '0');
+    return matches;
+};
+
+/** Require an explicit real endpoint; never fall back to an empty in-memory cache. */
+export const getAuditRedisOptions = (env = process.env) => {
+    const port = Number(env.REDIS_PORT);
+    const db = Number(env.REDIS_DB ?? '0');
+    if (
+        !env.REDIS_HOST?.trim() ||
+        !Number.isInteger(port) ||
+        port < 1 ||
+        port > 65535 ||
+        !Number.isInteger(db) ||
+        db < 0 ||
+        (env.REDIS_TLS !== undefined && !['true', 'false'].includes(env.REDIS_TLS))
+    ) {
+        throw new Error(
+            'Set REDIS_HOST and REDIS_PORT; REDIS_DB defaults to 0 and REDIS_TLS accepts true or false.'
+        );
+    }
+    return {
+        host: env.REDIS_HOST,
+        port,
+        db,
+        username: env.REDIS_USERNAME,
+        password: env.REDIS_PASSWORD,
+        ...(env.REDIS_TLS === 'true' ? { tls: {} } : {}),
+        lazyConnect: true,
+        connectTimeout: 2_000,
+        commandTimeout: 5_000,
+        maxRetriesPerRequest: 0,
+        retryStrategy: () => null,
+    };
+};
+
+const main = async () => {
+    let redis;
+    try {
+        const options = getAuditRedisOptions();
+        redis = new Redis(options);
+        // Driver errors can include endpoint/auth details; report only the sanitized failure below.
+        redis.on('error', () => undefined);
+        await redis.connect();
+        const legacyKeyMatches = await countLegacySigningAuthorityKeys(redis);
+        console.log(
+            JSON.stringify({
+                database: options.db,
+                pattern: LEGACY_SEED_PATTERN,
+                legacyKeyMatches,
+                auditedAt: new Date().toISOString(),
+            })
+        );
+        if (legacyKeyMatches > 0) {
+            console.error(
+                'Legacy signing-authority cache keys remain. Follow the seed-encryption runbook before completing rollout.'
+            );
+            process.exitCode = 1;
+        }
+    } catch {
+        console.error(
+            'Redis audit failed. Check REDIS_HOST, REDIS_PORT, optional REDIS_DB/TLS/auth settings, and private network access. No clean result was established.'
+        );
+        process.exitCode = 1;
+    } finally {
+        redis?.disconnect();
+    }
+};
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();

package/scripts/migrate-signing-authority-seeds-local.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Run one local migration phase using the API container's database and keys.
+set -euo pipefail
+
+usage() {
+    echo 'Usage: bun run migrate:sa-seeds:local --dry-run|--prepare|--verify|--purge'
+    echo 'Defaults to read-only dry-run. Runs one phase to completion and streams logs.'
+}
+
+if [[ "$#" -gt 1 ]]; then
+    usage >&2
+    exit 1
+fi
+
+case "${1:---dry-run}" in
+    --dry-run|--prepare|--verify|--purge) SA_PHASE="${1:---dry-run}"; SA_PHASE="${SA_PHASE#--}" ;;
+    --help|-h) usage; exit 0 ;;
+    *) usage >&2; exit 1 ;;
+esac
+
+SA_REPO_ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../../../.." && pwd)"
+cd "$SA_REPO_ROOT"
+printf 'Running local signing-authority migration: %s\n' "$SA_PHASE"
+
+docker compose -f apps/learn-card-app/compose-local.yaml exec -T \
+  -e "SA_MIGRATION_PHASE=$SA_PHASE" \
+  -w /app/services/learn-card-network/lca-api api bun --conditions=development -e '
+import { environment } from "./src/config/environment";
+import { client, mongodb } from "./src/mongo";
+import { runSeedMigrationBatch, SeedMigrationError } from "./src/migrations/signingAuthoritySeeds";
+
+try {
+    let result;
+    do {
+        result = await runSeedMigrationBatch(
+            mongodb,
+            { phase: process.env.SA_MIGRATION_PHASE, batchSize: 50 },
+            { encryptedWritesEnabled: environment.SA_SEED_ENCRYPT_WRITES }
+        );
+        console.log(JSON.stringify(result, null, 2));
+        if (!result.done && result.processed === 0 && !result.rescanRequired) {
+            throw new Error("No progress");
+        }
+    } while (!result.done);
+} catch (error) {
+    console.error(error instanceof SeedMigrationError ? error.category : "operation_failed");
+    process.exitCode = 1;
+} finally {
+    await client.close();
+}
+'

package/scripts/migrate-signing-authority-seeds.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+
+const { values } = parseArgs({
+    options: {
+        'function-name': { type: 'string' },
+        region: { type: 'string' },
+        phase: { type: 'string', default: 'dry-run' },
+        'batch-size': { type: 'string', default: '50' },
+        'one-batch': { type: 'boolean', default: false },
+        help: { type: 'boolean', default: false },
+    },
+});
+
+if (values.help) {
+    console.log(
+        'Usage: node scripts/migrate-signing-authority-seeds.mjs --function-name NAME --region REGION --phase dry-run|prepare|verify|purge [--batch-size 1..100] [--one-batch]'
+    );
+    process.exit(0);
+}
+const batchSize = Number(values['batch-size']);
+if (
+    !values['function-name'] ||
+    !values.region ||
+    !['dry-run', 'prepare', 'verify', 'purge'].includes(values.phase) ||
+    !Number.isInteger(batchSize) ||
+    batchSize < 1 ||
+    batchSize > 100
+) {
+    console.error('Provide --function-name, --region, a valid --phase, and --batch-size 1..100.');
+    process.exit(1);
+}
+
+// No database credentials or key material on the operator host. AWS CLI uses its normal credential chain.
+const directory = mkdtempSync(join(tmpdir(), 'lca-sa-migration-'));
+const payloadFile = join(directory, 'request.json');
+const outputFile = join(directory, 'response.json');
+writeFileSync(payloadFile, JSON.stringify({ phase: values.phase, batchSize }), { mode: 0o600 });
+try {
+    let done = false;
+    do {
+        const invocation = JSON.parse(
+            execFileSync(
+                'aws',
+                [
+                    'lambda',
+                    'invoke',
+                    '--function-name',
+                    values['function-name'],
+                    '--region',
+                    values.region,
+                    '--invocation-type',
+                    'RequestResponse',
+                    '--payload',
+                    `fileb://${payloadFile}`,
+                    '--cli-read-timeout',
+                    '910',
+                    '--cli-connect-timeout',
+                    '10',
+                    '--output',
+                    'json',
+                    outputFile,
+                ],
+                {
+                    encoding: 'utf8',
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                    env: { ...process.env, AWS_PAGER: '' },
+                }
+            )
+        );
+        const result = JSON.parse(readFileSync(outputFile, 'utf8'));
+        if (invocation.FunctionError || invocation.StatusCode !== 200) {
+            // The Lambda boundary emits only sanitized migration errors.
+            console.error(
+                result.errorMessage ?? 'Migration invocation failed. Inspect the function logs.'
+            );
+            process.exitCode = 1;
+            break;
+        }
+        console.log(JSON.stringify(result));
+        done = result.done === true;
+        if (!done && result.processed === 0 && !result.rescanRequired) {
+            console.error('No progress in this batch. Inspect the function logs before retrying.');
+            process.exitCode = 1;
+            break;
+        }
+    } while (!done && !values['one-batch']);
+} catch (error) {
+    // CLI diagnostics describe invocation/auth/transport failures. Never print the whole
+    // exec error: stdout and the Lambda response are handled separately above.
+    if (typeof error.stderr === 'string' || Buffer.isBuffer(error.stderr)) {
+        const diagnostic = error.stderr.toString().trim();
+        if (diagnostic) console.error(diagnostic);
+    }
+    console.error(
+        'AWS invocation failed. Check your credentials, region, and function name; rerun to resume.'
+    );
+    process.exitCode = 1;
+} finally {
+    rmSync(directory, { recursive: true, force: true });
+}

package/seedMigrationLambda.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 './seedMigrationLambda';
+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/seedMigrationLambda.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;
+};