@learncard/lca-api-service 1.3.2 → 1.5.0

package/serverless-local.yml

@@ -36,8 +36,12 @@ 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'}
+        SA_SEED_ALLOW_LEGACY_READ: ${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}
@@ -51,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:
@@ -98,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:
@@ -223,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

@@ -129,32 +129,17 @@ provider:
     timeout: 29
     stage: ${opt:stage, "dev"}
     region: ${opt:region, "us-east-1"}
-    environment:
-        LAMBDA_STAGE: ${opt:stage, "dev"}
-        SEED: ${env:SEED, ''}
-        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
@@ -167,6 +152,9 @@ provider:
 functions:
     trpc:
         handler: lambda.trpcHandler
+        role: SigningAuthorityExecutionRole
+        dependsOn: [SigningAuthoritySeedKeyPolicy]
+        environment: ${file(./serverless.function-env.cjs):api}
         vpc:
             securityGroupIds:
                 - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
@@ -177,6 +165,9 @@ functions:
 
     api:
         handler: lambda.openApiHandler
+        role: SigningAuthorityExecutionRole
+        dependsOn: [SigningAuthoritySeedKeyPolicy]
+        environment: ${file(./serverless.function-env.cjs):api}
         vpc:
             securityGroupIds:
                 - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
@@ -187,6 +178,7 @@ functions:
 
     didWeb:
         handler: lambda.didWebHandler
+        environment: ${file(./serverless.function-env.cjs):api}
         vpc:
             securityGroupIds:
                 - 'Fn::GetAtt': [ServerlessSecurityGroup, GroupId]
@@ -198,8 +190,44 @@ 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:
+                - Fn::GetAtt: [ServerlessSecurityGroup, GroupId]
+            subnetIds:
+                - Ref: PrivateSubnetA
+
     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/**
@@ -207,12 +235,248 @@ 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:
+                Fn::GetAtt: [SigningAuthoritySeedKey, Arn]
+        SigningAuthoritySeedMigrationFunctionName:
+            Value:
+                Ref: SeedMigrationLambdaFunction
     Resources:
+        # Only the two signing entry points and the migration worker assume this role.
+        # Keep KMS references out of the role itself to avoid a Role -> Key -> Role cycle.
+        SigningAuthorityExecutionRole:
+            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: 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
+            UpdateReplacePolicy: Retain
+            Properties:
+                Description: Envelope encryption for hosted signing-authority seeds
+                KeySpec: SYMMETRIC_DEFAULT
+                KeyUsage: ENCRYPT_DECRYPT
+                EnableKeyRotation: true
+                PendingWindowInDays: 30
+                KeyPolicy:
+                    Version: '2012-10-17'
+                    Statement:
+                        - Sid: AccountKeyAdministration
+                          Effect: Allow
+                          Principal:
+                              AWS:
+                                  Fn::Sub: arn:${AWS::Partition}:iam::${AWS::AccountId}:root
+                          Action:
+                              - kms:DescribeKey
+                              - kms:GetKeyPolicy
+                              - kms:PutKeyPolicy
+                              - kms:ListResourceTags
+                              - kms:TagResource
+                              - kms:UntagResource
+                              - kms:GetKeyRotationStatus
+                              - kms:EnableKeyRotation
+                              - kms:DisableKeyRotation
+                              - kms:UpdateKeyDescription
+                              - kms:EnableKey
+                              - kms:DisableKey
+                              - kms:ScheduleKeyDeletion
+                              - kms:CancelKeyDeletion
+                              - kms:CreateAlias
+                              - kms:UpdateAlias
+                              - kms:DeleteAlias
+                          Resource: '*'
+                        - Sid: LcaApiSeedEncryption
+                          Effect: Allow
+                          Principal:
+                              AWS:
+                                  Fn::GetAtt: [SigningAuthorityExecutionRole, Arn]
+                          Action: [kms:GenerateDataKey, kms:Decrypt]
+                          Resource: '*'
+                          Condition:
+                              StringEquals:
+                                  kms:EncryptionContext:purpose: lca-signing-authority-seed
+                        - Sid: DenyOtherCryptographicPrincipals
+                          Effect: Deny
+                          Principal: '*'
+                          Action:
+                              [kms:Decrypt, 'kms:ReEncrypt*', 'kms:GenerateDataKey*', kms:Encrypt]
+                          Resource: '*'
+                          Condition:
+                              ArnNotEquals:
+                                  aws:PrincipalArn:
+                                      Fn::GetAtt: [SigningAuthorityExecutionRole, Arn]
+        SigningAuthoritySeedKeyAlias:
+            Type: AWS::KMS::Alias
+            Properties:
+                AliasName: alias/${self:service}-${self:provider.stage}-sa-seeds
+                TargetKeyId:
+                    Ref: SigningAuthoritySeedKey
+        # The direct execution-role grant in the KEY policy authorizes cryptographic use.
+        # This matching IAM allow is not required by that grant; it documents the scope and
+        # provides a dependsOn deployment barrier. Keeping it separate avoids a Role -> Key
+        # -> Role CloudFormation dependency cycle. Swagger/didWeb use the generated role.
+        SigningAuthoritySeedKeyPolicy:
+            Type: AWS::IAM::Policy
+            Properties:
+                PolicyName: ${self:service}-${self:provider.stage}-sa-seeds
+                Roles:
+                    - Ref: SigningAuthorityExecutionRole
+                PolicyDocument:
+                    Version: '2012-10-17'
+                    Statement:
+                        - Effect: Allow
+                          Action: [kms:GenerateDataKey, kms:Decrypt]
+                          Resource:
+                              Fn::GetAtt: [SigningAuthoritySeedKey, Arn]
+                          Condition:
+                              StringEquals:
+                                  kms:EncryptionContext:purpose: lca-signing-authority-seed
         VPC:
             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:
@@ -323,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';

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

@@ -3,6 +3,7 @@ import { getEphemeralLearnCard } from '@helpers/learnCard.helpers';
 import { SigningAuthorities } from '.';
 import crypto from 'node:crypto';
 import { v4 as uuidv4 } from 'uuid';
+import { logSeedEncryptionFailure, seedEncryption } from '@helpers/seedEncryption.helpers';
 
 export const createSigningAuthorityForDID = async (
     ownerDid: string,
@@ -10,19 +11,22 @@ export const createSigningAuthorityForDID = async (
 ): Promise<string | false> => {
     const seed =
         environment.NODE_ENV === 'test' ? 'e'.repeat(64) : crypto.randomBytes(32).toString('hex');
-    const did = (await getEphemeralLearnCard(seed)).id.did();
+    const _id = uuidv4();
     try {
+        const did = (await getEphemeralLearnCard(seed)).id.did();
+        const identity = { _id, ownerDid, did, name };
+        // Plaintext writes support the compatibility deployment and offline opt-in defaults.
+        const secret = environment.SA_SEED_ENCRYPT_WRITES
+            ? await seedEncryption.encrypt(seed, identity)
+            : { seed };
         return (
             await SigningAuthorities.insertOne({
-                _id: uuidv4(),
-                ownerDid,
-                did,
-                name,
-                seed,
+                ...identity,
+                ...secret,
             })
         ).insertedId;
     } catch (e) {
-        console.error(e);
+        logSeedEncryptionFailure(e, 'create', { _id });
         return false;
     }
 };

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

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

package/src/app.ts

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

package/src/cache/challenges.ts

@@ -4,6 +4,7 @@ export const getChallengeCacheKey = (did: string, challenge: string): string =>
     `challenge|${did}|${challenge}`;
 
 export const VALID = 'valid';
+export const DID_CHALLENGE_TTL_SECS = 5 * 60;
 
 export const isChallengeValidForDid = async (
     did: string,
@@ -14,8 +15,17 @@ export const isChallengeValidForDid = async (
     return result === VALID ? result : undefined;
 };
 
+/** Atomically validate and consume a challenge so concurrent replays cannot both succeed. */
+export const consumeChallengeForDid = async (did: string, challenge: string): Promise<boolean> => {
+    const key = getChallengeCacheKey(did, challenge);
+    const redis = cache.redis ?? cache.node;
+    const value = await redis.getdel(key);
+
+    return value === VALID;
+};
+
 export const setValidChallengeForDid = async (did: string, challenge: string) => {
-    return cache.set(getChallengeCacheKey(did, challenge), VALID);
+    return cache.set(getChallengeCacheKey(did, challenge), VALID, DID_CHALLENGE_TTL_SECS);
 };
 
 export const setValidChallengesForDid = async (did: string, challenges: string[]) => {
@@ -25,7 +35,7 @@ export const setValidChallengesForDid = async (did: string, challenges: string[]
         return acc;
     }, {});
 
-    return cache.mset(values);
+    return cache.mset(values, DID_CHALLENGE_TTL_SECS);
 };
 
 export const invalidateChallengeForDid = async (did: string, challenge: string) => {

package/src/cache/getDel.test.ts

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