@learncard/lca-api-service 1.4.0 → 1.5.0

package/seedMigrationLambda.test.ts

@@ -1,145 +1,40 @@
 import type { Context } from 'aws-lambda';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import type { SeedMigrationResult } from './src/types/seed-migration';
+import { beforeEach, expect, it, vi } from 'vitest';
 
-const mocks = vi.hoisted(() => ({
-    connect: vi.fn(),
-    close: vi.fn(),
-    runBatch: vi.fn(),
-    mongodb: {},
-}));
+const mocks = vi.hoisted(() => ({ bootstrap: vi.fn(), getApp: vi.fn(), handler: vi.fn() }));
 
-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(),
-});
+vi.mock('@learncard/service-config', () => ({ bootstrapLambda: mocks.bootstrap }));
+vi.mock('./src/config/stageConfig', () => ({ base: {}, stages: { dev: {}, production: {} } }));
+vi.mock('./seedMigrationApp', () => ({ handler: mocks.handler }));
 
 beforeEach(() => {
-    mocks.connect.mockReset().mockResolvedValue(undefined);
-    mocks.close.mockReset().mockResolvedValue(undefined);
-    mocks.runBatch.mockReset().mockResolvedValue(result);
-    vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    vi.resetModules();
+    vi.clearAllMocks();
+    mocks.bootstrap.mockReturnValue(mocks.getApp);
+    mocks.getApp.mockResolvedValue({ handler: mocks.handler });
+    mocks.handler.mockResolvedValue({ phase: 'prepare', done: true });
 });
 
-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('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('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();
-    });
+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

@@ -1,50 +1,19 @@
 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 { bootstrapLambda } from '@learncard/service-config';
+
+import { base, stages } from './src/config/stageConfig';
 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();
+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'),
+});
 
-/** 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;
-};
+export const handler = async (event: unknown, context: Context): Promise<SeedMigrationResult> =>
+    (await getApplication()).handler(event, context);

package/serverless-local.yml

@@ -36,7 +36,8 @@ provider:
     stage: ${opt:stage, "dev"}
     region: ${opt:region, "us-east-1"}
     environment:
-        LAMBDA_STAGE: ${opt:stage, "dev"}
+        # serverless-offline sets AWS_LAMBDA_FUNCTION_NAME; stage config stays opt-in locally.
+        LAMBDA_STAGE: ${env:CONFIG_STAGE, ''}
         SEED: ${env:SEED}
         SA_SEED_LOCAL_KEK: ${env:SA_SEED_LOCAL_KEK, ''}
         SA_SEED_ENCRYPT_WRITES: ${env:SA_SEED_ENCRYPT_WRITES, 'false'}
@@ -54,6 +55,16 @@ provider:
         MONGO_DB_NAME: ${env:MONGO_DB_NAME}
         AUTHORIZED_DIDS: ${env:AUTHORIZED_DIDS}
         GOOGLE_APPLICATION_CREDENTIAL: ${env:GOOGLE_APPLICATION_CREDENTIAL, ""}
+        KEYCLOAK_ISSUERS: ${env:KEYCLOAK_ISSUERS, ""}
+        KEYCLOAK_AUDIENCES: ${env:KEYCLOAK_AUDIENCES, ""}
+        KEYCLOAK_JWKS_URL_OVERRIDES: ${env:KEYCLOAK_JWKS_URL_OVERRIDES, ""}
+        OIDC_ISSUER: ${env:OIDC_ISSUER, ""}
+        OIDC_SIGNING_KEY_JWK: ${env:OIDC_SIGNING_KEY_JWK, ""}
+        OIDC_CLIENT_ID: ${env:OIDC_CLIENT_ID, ""}
+        OIDC_CLIENT_SECRET: ${env:OIDC_CLIENT_SECRET, ""}
+        OIDC_REDIRECT_URIS: ${env:OIDC_REDIRECT_URIS, ""}
+        GOOGLE_OAUTH_CLIENT_IDS: ${env:GOOGLE_OAUTH_CLIENT_IDS, ""}
+        APPLE_OAUTH_CLIENT_IDS: ${env:APPLE_OAUTH_CLIENT_IDS, ""}
         REDIS_HOST:
             'Fn::GetAtt': [ElasticCacheCluster, RedisEndpoint.Address]
         REDIS_PORT:
@@ -101,6 +112,17 @@ functions:
         url:
             cors: true
 
+    oidc:
+        handler: lambda.oidcHandler
+        vpc:
+            securityGroupIds:
+                - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
+            subnetIds:
+                - Ref: PrivateSubnetA
+        events:
+            - httpApi: GET /.well-known/openid-configuration
+            - httpApi: ANY /oidc/{proxy+}
+
     swagger:
         handler: lambda.swaggerUiHandler
         package:
@@ -226,6 +248,8 @@ resources:
             Properties:
                 AutoMinorVersionUpgrade: true
                 Engine: redis
+                # GETDEL (login codes/tickets/auth codes) needs Redis >= 6.2
+                EngineVersion: '7.0'
                 CacheNodeType: ${self:custom.config.CACHE_INSTANCE_SIZE}
                 NumCacheNodes: 1
                 VpcSecurityGroupIds:

package/serverless.function-env.cjs

@@ -0,0 +1,58 @@
+const { functionEnvironment, pickNonEmpty } = require('@learncard/service-config/function-env.cjs');
+
+const PROVIDER_SECRETS = [
+    'SEED',
+    'MONGO_URI',
+    'MONGO_DB_NAME',
+    'AUTHORIZED_DIDS',
+    'METABASE_SECRET_KEY',
+    'OPENAI_API_KEY',
+    'POSTMARK_SERVER_TOKEN',
+    'SCOUTS_SSO_CLIENT_SECRET',
+    'SENTRY_DSN',
+    'LEARN_CLOUD_URL',
+];
+
+const API_SECRETS = [
+    'GOOGLE_APPLICATION_CREDENTIAL',
+    'POSTHOG_API_KEY',
+    'ESCROW_RELAY_URL',
+    'ESCROW_RELAY_AUTH_TOKEN',
+    'ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON',
+    'ESCROW_ENCLAVE_REMOTE_URL',
+    'ESCROW_ENCLAVE_REMOTE_TOKEN',
+    'KEYCLOAK_JWKS_URL_OVERRIDES',
+];
+
+// Non-secret operator toggles forwarded in bundle mode too, so enabling RUNTIME_SECRETS_ID
+// can never silently change them: escrow stays off unless ESCROW_ENCLAVE_MODE is set, and
+// ESCROW_RELEASE_KILL_SWITCH must be flippable without editing the bundle.
+const API_TOGGLES = ['ESCROW_ENCLAVE_MODE', 'ESCROW_RELEASE_KILL_SWITCH'];
+
+// Serverless v3 supplies CLI options to file functions and preserves CF intrinsics.
+// No stage-file values are forwarded from the deployment environment.
+exports.provider = ({ options = {} } = {}) => ({
+    LAMBDA_STAGE: options.stage || 'dev',
+    // Non-secret product selector for the shared stage files (config.<tenant>.<stage>.json).
+    CONFIG_TENANT: process.env.CONFIG_TENANT || 'learncard',
+    PORT: String(options.httpPort || '3000'),
+    SA_SEED_KMS_KEY_ARN: { 'Fn::GetAtt': ['SigningAuthoritySeedKey', 'Arn'] },
+    REDIS_HOST: { 'Fn::GetAtt': ['ElasticCacheCluster', 'RedisEndpoint.Address'] },
+    REDIS_PORT: { 'Fn::GetAtt': ['ElasticCacheCluster', 'RedisEndpoint.Port'] },
+    ...functionEnvironment({ always: [], fallback: PROVIDER_SECRETS }),
+});
+
+// API/migration and the default-role didWeb/swagger functions get the bundle pointer.
+// Reading the bundle does not grant the default role signing-authority KMS access.
+exports.api = () =>
+    functionEnvironment({
+        always: ['RUNTIME_SECRETS_ID', ...API_TOGGLES],
+        fallback: API_SECRETS,
+    });
+
+// Scheduled escrow jobs load the full app (Mongo, Postmark, seed) through lambda.ts, so they
+// need the same bundle pointer and escrow settings as the API functions.
+exports.escrow = exports.api;
+
+// OIDC has its own signing-key secret and cannot read the runtime bundle.
+exports.oidc = () => pickNonEmpty(['OIDC_CLIENT_SECRET', 'OIDC_REDIRECT_URIS']);

package/serverless.yml

@@ -18,10 +18,6 @@ custom:
         number: 3
     config:
         CACHE_INSTANCE_SIZE: cache.t2.micro
-    # Lambda caps each function's environment at 4KB. Escrow config is only read
-    # by the trpc/api handlers, so it is attached per-function (not provider-wide)
-    # and unset keys are omitted entirely.
-    escrowEnvironment: ${file(./serverless.escrow-env.cjs)}
     esbuild:
         # serverless-esbuild does not support Bun as a Lambda artifact packager.
         # Bun remains the repo installer/runner; pnpm is used only for packaging externals.
@@ -133,37 +129,17 @@ provider:
     timeout: 29
     stage: ${opt:stage, "dev"}
     region: ${opt:region, "us-east-1"}
-    environment:
-        LAMBDA_STAGE: ${opt:stage, "dev"}
-        SEED: ${env:SEED, ''}
-        SA_SEED_KMS_KEY_ARN:
-            Fn::GetAtt: [SigningAuthoritySeedKey, Arn]
-        # First deployment upgrades readers only. Enable writes after every reader is compatible.
-        SA_SEED_ENCRYPT_WRITES: ${param:saSeedEncryptWrites, env:SA_SEED_ENCRYPT_WRITES, 'false'}
-        SA_SEED_ALLOW_LEGACY_READ: ${param:saSeedAllowLegacyRead, env:SA_SEED_ALLOW_LEGACY_READ, 'true'}
-        DOMAIN_NAME: ${env:DOMAIN_NAME, ''}
-        OPENAI_API_KEY: ${env:OPENAI_API_KEY, ''}
-        METABASE_SECRET_KEY: ${env:METABASE_SECRET_KEY, ''}
-        POSTMARK_SERVER_TOKEN: ${env:POSTMARK_SERVER_TOKEN, ''}
-        POSTMARK_LOGIN_CODE_TEMPLATE_ALIAS: ${env:POSTMARK_LOGIN_CODE_TEMPLATE_ALIAS, ''}
-        POSTMARK_ENDORSEMENT_REQUEST_TEMPLATE_ALIAS: ${env:POSTMARK_ENDORSEMENT_REQUEST_TEMPLATE_ALIAS, ''}
-        POSTMARK_RECOVERY_EMAIL_CODE_TEMPLATE_ALIAS: ${env:POSTMARK_RECOVERY_EMAIL_CODE_TEMPLATE_ALIAS, ''}
-        POSTMARK_RECOVERY_KEY_TEMPLATE_ALIAS: ${env:POSTMARK_RECOVERY_KEY_TEMPLATE_ALIAS, ''}
-        POSTMARK_FROM_EMAIL: ${env:POSTMARK_FROM_EMAIL, ''}
-        POSTMARK_BRAND_NAME: ${env:POSTMARK_BRAND_NAME, ''}
-        PORT: ${opt:httpPort, "3000"}
-        MONGO_URI: ${env:MONGO_URI, ''}
-        MONGO_DB_NAME: ${env:MONGO_DB_NAME, ''}
-        AUTHORIZED_DIDS: ${env:AUTHORIZED_DIDS, ''}
-        GOOGLE_APPLICATION_CREDENTIAL: ${env:GOOGLE_APPLICATION_CREDENTIAL, ''}
-        SCOUTS_SSO_CLIENT_SECRET: ${env:SCOUTS_SSO_CLIENT_SECRET, ''}
-        LEARN_CLOUD_URL: ${env:LEARN_CLOUD_URL, ''}
-        SENTRY_DSN: ${env:SENTRY_DSN, ''}
-        SENTRY_ENV: ${env:SENTRY_ENV, ''}
-        REDIS_HOST:
-            'Fn::GetAtt': [ElasticCacheCluster, RedisEndpoint.Address]
-        REDIS_PORT:
-            'Fn::GetAtt': [ElasticCacheCluster, RedisEndpoint.Port]
+    # Bundle mode emits only infra; fallback mode retains the existing GitHub secrets.
+    environment: ${file(./serverless.function-env.cjs):provider}
+    # Only didWeb/swagger use this generated role. Explicit function roles do not inherit it.
+    # Bundle access must not grant cryptographic use of the hosted signing-authority KMS key.
+    iam:
+        role:
+            statements:
+                - Effect: Allow
+                  Action: secretsmanager:GetSecretValue
+                  Resource:
+                      Fn::Sub: arn:${AWS::Partition}:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:lca-api/${sls:stage}/runtime-secrets-*
     tracing:
         apiGateway: true
         lambda: true
@@ -178,7 +154,7 @@ functions:
         handler: lambda.trpcHandler
         role: SigningAuthorityExecutionRole
         dependsOn: [SigningAuthoritySeedKeyPolicy]
-        environment: ${self:custom.escrowEnvironment}
+        environment: ${file(./serverless.function-env.cjs):api}
         vpc:
             securityGroupIds:
                 - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
@@ -191,7 +167,7 @@ functions:
         handler: lambda.openApiHandler
         role: SigningAuthorityExecutionRole
         dependsOn: [SigningAuthoritySeedKeyPolicy]
-        environment: ${self:custom.escrowEnvironment}
+        environment: ${file(./serverless.function-env.cjs):api}
         vpc:
             securityGroupIds:
                 - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
@@ -202,6 +178,7 @@ functions:
 
     didWeb:
         handler: lambda.didWebHandler
+        environment: ${file(./serverless.function-env.cjs):api}
         vpc:
             securityGroupIds:
                 - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
@@ -213,12 +190,29 @@ functions:
         url:
             cors: true
 
+    oidc:
+        handler: oidcLambda.handler
+        # Only this function may read the private signing key (see OidcExecutionRole).
+        role: OidcExecutionRole
+        environment: ${file(./serverless.function-env.cjs):oidc}
+        vpc:
+            securityGroupIds:
+                - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
+            subnetIds:
+                - Ref: PrivateSubnetA
+        events:
+            - httpApi: GET /.well-known/openid-configuration
+            - httpApi: ANY /oidc/{proxy+}
+
     seedMigration:
         handler: seedMigrationLambda.handler
         role: SigningAuthorityExecutionRole
         timeout: 900
         reservedConcurrency: 1
         dependsOn: [SigningAuthoritySeedKeyPolicy]
+        # Shares the SigningAuthority role, so it reads the runtime bundle when present and
+        # falls back to the same credentials as trpc/api otherwise (it needs SEED + Mongo).
+        environment: ${file(./serverless.function-env.cjs):api}
         # IAM invoke only: intentionally no events, schedule, or function URL.
         vpc:
             securityGroupIds:
@@ -228,6 +222,12 @@ functions:
 
     swagger:
         handler: lambda.swaggerUiHandler
+        environment: ${file(./serverless.function-env.cjs):api}
+        vpc:
+            securityGroupIds:
+                - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
+            subnetIds:
+                - Ref: PrivateSubnetA
         package:
             patterns:
                 - src/swagger-ui/**
@@ -235,7 +235,44 @@ functions:
             - httpApi: GET /docs
             - httpApi: GET /docs/{trpc+}
 
+    # Always deployed (no per-stage conditional: `schedule.enabled` needs a
+    # literal boolean, not an interpolated ESCROW_ENCLAVE_MODE env string);
+    # the handler itself no-ops when escrow is disabled for this stage/tenant.
+    escrowHoldReminders:
+        handler: lambda.escrowHoldRemindersHandler
+        timeout: 120
+        environment: ${file(./serverless.function-env.cjs):escrow}
+        vpc:
+            securityGroupIds:
+                - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
+            subnetIds:
+                - Ref: PrivateSubnetA
+        events:
+            - schedule: rate(1 hour)
+
+    # Same always-deployed/no-op-when-disabled shape as escrowHoldReminders
+    # above; a bounded batch each run, so an hourly rate is generous relative
+    # to how quickly a key rotation's previous-key backlog should drain.
+    escrowBlobRewrap:
+        handler: lambda.escrowBlobRewrapHandler
+        timeout: 120
+        environment: ${file(./serverless.function-env.cjs):escrow}
+        vpc:
+            securityGroupIds:
+                - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
+            subnetIds:
+                - Ref: PrivateSubnetA
+        events:
+            - schedule: rate(1 hour)
+
 resources:
+    # Escrow enclave over PrivateLink: created only when the stage sets
+    # ESCROW_ENCLAVE_ENDPOINT_SERVICE_NAME (the enclave account's endpoint
+    # service). TLS trust for the hostname is pinned in enclaveTrustAnchors.ts.
+    Conditions:
+        EscrowEnclavePrivateLink:
+            Fn::Not:
+                - Fn::Equals: ['${env:ESCROW_ENCLAVE_ENDPOINT_SERVICE_NAME, ""}', '']
     Outputs:
         SigningAuthoritySeedKeyArn:
             Value:
@@ -259,6 +296,39 @@ resources:
                 ManagedPolicyArns:
                     - Fn::Sub: arn:${AWS::Partition}:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole
                     - Fn::Sub: arn:${AWS::Partition}:iam::aws:policy/AWSXRayDaemonWriteAccess
+                Policies:
+                    - PolicyName: runtime-secrets
+                      PolicyDocument:
+                          Version: '2012-10-17'
+                          Statement:
+                              # seedMigration shares this role; bundle access is acceptable for now.
+                              - Effect: Allow
+                                Action: secretsmanager:GetSecretValue
+                                Resource:
+                                    Fn::Sub: arn:${AWS::Partition}:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:lca-api/${sls:stage}/runtime-secrets-*
+        OidcExecutionRole:
+            Type: AWS::IAM::Role
+            Properties:
+                AssumeRolePolicyDocument:
+                    Version: '2012-10-17'
+                    Statement:
+                        - Effect: Allow
+                          Principal:
+                              Service: lambda.amazonaws.com
+                          Action: sts:AssumeRole
+                ManagedPolicyArns:
+                    - Fn::Sub: arn:${AWS::Partition}:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole
+                    - Fn::Sub: arn:${AWS::Partition}:iam::aws:policy/AWSXRayDaemonWriteAccess
+                Policies:
+                    - PolicyName: oidc-signing-key
+                      PolicyDocument:
+                          Version: '2012-10-17'
+                          Statement:
+                              # SecretString is the private JWK JSON; only its id belongs in Lambda env.
+                              - Effect: Allow
+                                Action: secretsmanager:GetSecretValue
+                                Resource:
+                                    Fn::Sub: arn:${AWS::Partition}:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:lca-api/${sls:stage}/oidc-signing-jwk-*
         SigningAuthoritySeedKey:
             Type: AWS::KMS::Key
             DeletionPolicy: Retain
@@ -346,6 +416,67 @@ resources:
             Type: AWS::EC2::VPC
             Properties:
                 CidrBlock: '10.0.0.0/16'
+                # A private hosted zone needs DNS hostnames; left at the default elsewhere.
+                EnableDnsHostnames:
+                    Fn::If: [EscrowEnclavePrivateLink, true, Ref: AWS::NoValue]
+        EscrowEnclaveEndpointSecurityGroup:
+            Type: AWS::EC2::SecurityGroup
+            Condition: EscrowEnclavePrivateLink
+            Properties:
+                GroupDescription: Escrow enclave PrivateLink endpoint, 8443 from lca-api only
+                VpcId:
+                    Ref: VPC
+                SecurityGroupIngress:
+                    - IpProtocol: tcp
+                      FromPort: 8443
+                      ToPort: 8443
+                      SourceSecurityGroupId:
+                          Ref: ServerlessSecurityGroup
+        EscrowEnclaveEndpoint:
+            Type: AWS::EC2::VPCEndpoint
+            Condition: EscrowEnclavePrivateLink
+            Properties:
+                VpcEndpointType: Interface
+                ServiceName: ${env:ESCROW_ENCLAVE_ENDPOINT_SERVICE_NAME, ''}
+                VpcId:
+                    Ref: VPC
+                SubnetIds:
+                    - Ref: PrivateSubnetA
+                SecurityGroupIds:
+                    - Ref: EscrowEnclaveEndpointSecurityGroup
+                PrivateDnsEnabled: false
+        EscrowEnclaveHostedZone:
+            Type: AWS::Route53::HostedZone
+            Condition: EscrowEnclavePrivateLink
+            Properties:
+                Name: ${env:ESCROW_ENCLAVE_HOSTNAME, ''}
+                VPCs:
+                    - VPCId:
+                          Ref: VPC
+                      VPCRegion: ${self:provider.region}
+        EscrowEnclaveDnsRecord:
+            Type: AWS::Route53::RecordSet
+            Condition: EscrowEnclavePrivateLink
+            Properties:
+                HostedZoneId:
+                    Ref: EscrowEnclaveHostedZone
+                Name: ${env:ESCROW_ENCLAVE_HOSTNAME, ''}
+                Type: A
+                # DnsEntries[0] is "<hosted zone id>:<regional endpoint DNS name>".
+                AliasTarget:
+                    HostedZoneId:
+                        Fn::Select:
+                            - 0
+                            - Fn::Split:
+                                  - ':'
+                                  - Fn::Select: [0, Fn::GetAtt: [EscrowEnclaveEndpoint, DnsEntries]]
+                    DNSName:
+                        Fn::Select:
+                            - 1
+                            - Fn::Split:
+                                  - ':'
+                                  - Fn::Select: [0, Fn::GetAtt: [EscrowEnclaveEndpoint, DnsEntries]]
+                    EvaluateTargetHealth: false
         IP:
             Type: AWS::EC2::EIP
             Properties:
@@ -456,6 +587,10 @@ resources:
             Properties:
                 AutoMinorVersionUpgrade: true
                 Engine: redis
+                # GETDEL (login codes/tickets/auth codes) needs Redis >= 6.2. The
+                # version is deliberately NOT pinned here: existing clusters are
+                # already on 7.x, and a pin below the running version is rejected
+                # by CloudFormation as a downgrade (failing the whole deploy).
                 CacheNodeType: ${self:custom.config.CACHE_INSTANCE_SIZE}
                 NumCacheNodes: 1
                 VpcSecurityGroupIds:

package/src/accesslayer/notifications/index.ts

@@ -12,12 +12,19 @@ export const getNotificationsCollection = () => {
 
 export const Notifications = getNotificationsCollection();
 
-Notifications.createIndex({ 'to.did': 1, read: 1, sent: -1, _id: 1 });
+// Fire-and-forget at module load: every Lambda imports this, so an uncaught
+// rejection (e.g. a Mongo connect that outlives a frozen invocation) would
+// crash whichever function thaws next.
+const logIndexFailure = (error: unknown): void => {
+    console.error('Notifications index creation failed:', error);
+};
+
+Notifications.createIndex({ 'to.did': 1, read: 1, sent: -1, _id: 1 }).catch(logIndexFailure);
 Notifications.createIndex({
     'to.did': 1,
     type: 1,
     'data.metadata.connectionPrompt.promptId': 1,
-});
+}).catch(logIndexFailure);
 
 const LEGACY_CREDENTIAL_REFRESH_INDEX = 'to.did_1_type_1_data.metadata.deliveryKey_1';
 const MANAGED_CREDENTIAL_REFRESH_INDEX = 'managed_credential_refresh_delivery_key_unique';