@learncard/lca-api-service 1.4.0 → 1.5.0

package/.env.example

@@ -1,7 +1,19 @@
 # LCA API environment
 # Copy to .env. Validation runs before database/client initialization.
+#
+# Config resolves lowest→highest: schema defaults < config/config.json <
+# config/config.<stage>.json < runtime AWS secrets bundle (Lambda only) < real env.
+# Empty values are unset. The config/config*.json stage files are PUBLIC BY DESIGN:
+# put only non-secret config there. Secrets (credentials, AUTHORIZED_DIDS allowlist,
+# internal endpoints, signing keys) stay in the runtime bundle or this local .env.
+# Stage = LAMBDA_STAGE on Lambda, else CONFIG_STAGE; unknown stage uses config.json only.
+# Self-hosting: copy config/config.example.json to a stage file, or just use this .env.
+# Keep the entries you need locally even once a stage uses the runtime bundle.
 
 NODE_ENV=development
+# Lambda sets LAMBDA_STAGE; elsewhere CONFIG_STAGE selects the config.<stage>.json file.
+LAMBDA_STAGE=
+CONFIG_STAGE=
 PORT=3000
 SEED=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
 # Local development keeps plaintext behavior by default. To opt in, enable encrypted
@@ -18,10 +30,57 @@ AUTHORIZED_DIDS=
 LEARN_CLOUD_URL=
 NETWORK_BRAIN_SERVICE_URL=
 GOOGLE_APPLICATION_CREDENTIAL=
+# Lambda deploys may instead set RUNTIME_SECRETS_ID=lca-api/<stage>/runtime-secrets.
+# This secret bundle holds secrets only; non-secret per-stage config lives in the
+# checked-in config/config.<stage>.json files, not here and not in the bundle.
+# SecretString: flat env-name -> string JSON (including the Firebase JSON as a string).
+# Loaded before validation; non-empty explicit env wins. Leave unset for local/Docker/CI.
+# Keep all GitHub runtime secret fallbacks until each stage has a complete bundle.
+RUNTIME_SECRETS_ID=
 OPENAI_API_KEY=
 METABASE_SECRET_KEY=
 SCOUTS_SSO_CLIENT_SECRET=
 
+# Comma-separated exact Keycloak issuers (e.g. http://localhost:8081/realms/learncard).
+KEYCLOAK_ISSUERS=
+# Comma-separated allowed client IDs (e.g. learncard-app); matches aud or azp.
+KEYCLOAK_AUDIENCES=
+# Optional issuer=url pairs for internal JWKS endpoints, separated by commas.
+# Example: http://localhost:8081/realms/learncard=http://keycloak:8080/realms/learncard/protocol/openid-connect/certs
+KEYCLOAK_JWKS_URL_OVERRIDES=
+
+# Minimal self-issued OIDC provider (AD-2). Keycloak trusts lca-api as an
+# upstream Identity Provider: the app proves ownership in-app, exchanges the
+# proof for a single-use login ticket, and Keycloak redeems it via the
+# authorization-code flow (/oidc/authorize -> /oidc/token).
+# OIDC_ISSUER: REQUIRED issuer identifier baked into discovery/tokens (no
+#   default; unset = 503).
+# OIDC_SIGNING_KEY_JWK: local/Docker/CI override, JSON RSA private JWK with d, kid
+#   and alg RS256, SEPARATE from SEED. Takes precedence over the secret id.
+# OIDC_SIGNING_KEY_SECRET_ID: deployed Lambda secret name or ARN, convention
+#   lca-api/<stage>/oidc-signing-jwk in the Lambda account/region. SecretString
+#   must be a plain string containing the same JWK JSON (no wrapper).
+#   Fetched and cached per process; failed loads retry and readiness returns 503.
+#   Redeploy after rotation. Neither source set: prod = 503; dev/CI = ephemeral key.
+# OIDC_CLIENT_ID / OIDC_CLIENT_SECRET: credentials of the confidential Keycloak
+#   broker client that calls /oidc/token (default id 'keycloak-broker').
+#   OIDC_CLIENT_SECRET stays a GitHub-environment secret on the OIDC function and
+#   is NEVER placed in the runtime bundle; its signing key uses a separate AWS secret.
+# OIDC_REDIRECT_URIS: optional redirect-uri allowlist override (defaults to
+#   each KEYCLOAK_ISSUERS entry plus /broker/lca-api/endpoint). Exact match only;
+#   when neither list is set every redirect is rejected.
+OIDC_ISSUER=
+OIDC_SIGNING_KEY_JWK=
+OIDC_SIGNING_KEY_SECRET_ID=
+OIDC_CLIENT_ID=
+OIDC_CLIENT_SECRET=
+OIDC_REDIRECT_URIS=
+
+# Native Google/Apple social login: comma-separated allowed client ids.
+# Issuers and JWKS are fixed to the respective provider.
+GOOGLE_OAUTH_CLIENT_IDS=
+APPLE_OAUTH_CLIENT_IDS=
+
 # Configure both Postmark credentials or leave both empty for log delivery.
 POSTMARK_SERVER_TOKEN=
 POSTMARK_FROM_EMAIL=
@@ -47,8 +106,22 @@ ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON=
 # ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON={"local-dev":"MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgv1vJWrZWg8ydq4ibGe6/IqEw/BEIcgI+Y3c6hnoeF2ehRANCAAQ08rGhw2reTThF/ecfafLzjphjmqvySHJZwqKfqSn8YPK/1GMWODPWounlJ2MZb/iS/D69K0k9durGsGjaSb0I"}
 # Waiting period in ms (default 7 days). Local QA only: shorten to one minute.
 ESCROW_HOLD_DURATION_MS=
+ESCROW_HOLD_RESTART_MIN_AGE_MS=
 # ESCROW_HOLD_DURATION_MS=60000
 
+# ESCROW_ENCLAVE_MODE=remote: HTTP client to the enclave-host parent (P3.3).
+# URL must be https:// unless NODE_ENV=test or the host is localhost. Token
+# is a bearer credential, minimum 32 characters. Timeout defaults to 10000ms
+# (max 30000ms). Missing/invalid config fails escrow closed at request time
+# rather than crashing the whole service at boot.
+ESCROW_ENCLAVE_REMOTE_URL=
+ESCROW_ENCLAVE_REMOTE_TOKEN=
+ESCROW_ENCLAVE_REMOTE_TIMEOUT_MS=
+
+# Emergency stop: true blocks every escrow release (read per request, no restart needed).
+# Deploy toggle, forwarded even in runtime-secrets bundle mode.
+ESCROW_RELEASE_KILL_SWITCH=
+
 ANDROID_PUSH_ICON=
 REDIS_HOST=
 REDIS_PORT=

package/AGENTS.md

@@ -4,6 +4,64 @@ The LearnCard Application API (`lca-api`) is the tRPC service backing client-sid
 
 ## Build & Development Commands
 
+### Backend configuration model
+
+Configuration resolves in layers, lowest to highest precedence:
+
+1. Schema defaults (`src/config/environment.ts` Zod `.default()`s).
+2. Checked-in **non-secret** base config `config/config.json`.
+3. Checked-in **non-secret** per-stage config `config/config.<stage>.json`.
+4. Runtime AWS secrets bundle (Lambda only).
+5. Real environment variables (always win). Empty strings are unset.
+
+The stage is `LAMBDA_STAGE` on Lambda, else `CONFIG_STAGE`; an unknown stage uses
+the base `config/config.json` only (no per-stage file). The config stage files are
+**public by design** — put only non-secret config in them. Credentials,
+authorization allowlists (`AUTHORIZED_DIDS`), and internal service endpoints are
+**secrets** and belong in the runtime bundle or local env, never the stage files.
+
+For Lambda `trpc`/`api`, set the deploy environment variable `RUNTIME_SECRETS_ID` to
+`lca-api/<stage>/runtime-secrets` (or its ARN in the Lambda account/region). Provision
+the secret before enabling the variable. Its SecretString is a flat JSON object of
+UPPER_SNAKE_CASE environment names to string values, including **all** required
+runtime credentials. For example, Firebase is encoded as a string:
+
+```json
+{ "GOOGLE_APPLICATION_CREDENTIAL": "{\"type\":\"service_account\",\"...\":\"...\"}" }
+```
+
+The Firebase JSON is a **string inside the bundle**, not a nested object. No secret
+values belong in checked-in files. `lambda.ts` loads and validates the bundle once
+before importing `lambdaApp.ts` and the environment schema. Non-empty explicit env
+values win; empty strings are unset. Failed secret loads stop startup with a
+sanitized error and can retry; failed application imports remain memoized until
+the process is recycled. Redeploy/recycle functions after rotating the bundle.
+
+When the id is absent, no AWS lookup occurs. Deploys retain the GitHub
+runtime secrets as environment fallbacks; keep those inputs
+until every stage has a bundle. Self-hosters, Docker, local development and CI keep
+using plain environment variables — copy `config/config.example.json` to a stage
+file (register its static import in `src/config/stageConfig.ts` and rebuild) or
+just supply a `.env`. `trpc`, `api`, and `seedMigration` use
+`SigningAuthorityExecutionRole`. `didWeb` and `swagger` use the generated default
+role, with only a scoped runtime-bundle read grant in addition to Serverless's
+execution permissions, not signing-authority KMS access. All five receive the
+bundle id and run in the service VPC. Explicit function roles do not inherit the
+default role's grants. OIDC has an isolated
+`oidcLambda.ts` → `oidcLambdaApp.ts` import path and focused OIDC/cache schemas,
+so it never imports the API schema requiring seed and Mongo credentials. Keep that path free of Mongo, models and DIDKit:
+a Mongo connect left pending when an idle sandbox freezes crashes the next request after thaw. OIDC gets
+its broker settings and keeps its separate signing-key secret and IAM role.
+`OIDC_CLIENT_SECRET` stays a GitHub-environment secret on the OIDC function and is
+**never** placed in the runtime bundle; that function makes no AWS Secrets Manager
+calls for it. Preserve the existing issuer/audience validation.
+
+The Infisical → AWS sync and per-stage cutover are documented in the repo-root
+[environment-variables.md](../../../environment-variables.md#infisical--aws-secrets-sync).
+The shared `@learncard/service-config` package owns parsing, merging, runtime
+loading, stage application and Lambda bootstrap. Brain-service and LearnCloud
+adoption remains a separate task.
+
 - Build: `bun run build`
 - Dev: `bun run dev` — watches and rebuilds
 - Start: `bun run start` — local server (default port from env, typically 5100)
@@ -57,16 +115,17 @@ The `keysRouter` implements the server side of Shamir Secret Sharing key managem
 
 The `escrow` tRPC router is disabled unless `ESCROW_ENCLAVE_MODE` is configured.
 
-| Route                          | Procedure                 | Purpose                                                            |
-| ------------------------------ | ------------------------- | ------------------------------------------------------------------ |
-| `GET /keys/escrow/attestation` | `escrow.getAttestation`   | Enclave public key and hold duration                               |
-| `POST /keys/escrow`            | `escrow.enroll`           | Verify and store automatic recovery material                       |
-| `DELETE /keys/escrow`          | `escrow.remove`           | Remove material and optionally opt out                             |
-| `POST /keys/escrow/opt-in`     | `escrow.optIn`            | Allow enrollment again                                             |
-| `POST /keys/escrow/recover`    | `escrow.startRecovery`    | Start a waiting period without resetting an existing hold          |
-| `GET /keys/escrow/status`      | `escrow.getStatus`        | Check status; active devices send provider auth via `X-Auth-Token` |
-| `POST /keys/escrow/cancel`     | `escrow.cancelRecovery`   | DID owner cancels a pending hold                                   |
-| `POST /keys/escrow/complete`   | `escrow.completeRecovery` | Claim an elapsed hold and release sealed recovery material once    |
+| Route                           | Procedure                     | Purpose                                                                   |
+| ------------------------------- | ----------------------------- | ------------------------------------------------------------------------- |
+| `GET /keys/escrow/attestation`  | `escrow.getAttestation`       | Enclave public key and hold duration                                      |
+| `POST /keys/escrow`             | `escrow.enroll`               | Verify and store automatic recovery material                              |
+| `DELETE /keys/escrow`           | `escrow.remove`               | Remove material and optionally opt out                                    |
+| `POST /keys/escrow/opt-in`      | `escrow.optIn`                | Allow enrollment again                                                    |
+| `POST /keys/escrow/recover`     | `escrow.startRecovery`        | Start a waiting period without resetting an existing hold                 |
+| `GET /keys/escrow/status`       | `escrow.getStatus`            | Check status; active devices send provider auth via `X-Auth-Token`        |
+| `POST /keys/escrow/cancel`      | `escrow.cancelRecovery`       | DID owner cancels a pending hold                                          |
+| `POST /keys/escrow/cancel-link` | `escrow.cancelRecoveryByLink` | Cancels a pending hold via the single-use email cancel link (no DID auth) |
+| `POST /keys/escrow/complete`    | `escrow.completeRecovery`     | Claim an elapsed hold and release sealed recovery material once           |
 
 ### Important Invariants
 
@@ -75,6 +134,43 @@ The `escrow` tRPC router is disabled unless `ESCROW_ENCLAVE_MODE` is configured.
 - **Email share is encrypted before leaving the client.** The `sendEmailBackup` route receives only a relay-key ciphertext envelope and a confirmation code, then waits for isolated relay acceptance before recording pending recovery metadata.
 - **`shareVersion` pairs a device share with a matching auth share.** On rotation, previous versions are kept in `previousAuthShares` so users with stale device shares can still recover.
 
+## OIDC identity provider (AD-2)
+
+`auth.requestLoginTicket` and `auth.requestSocialLoginTicket` prove ownership in-app and issue 60-second single-use tickets. The ticket travels in URLs (`login_hint` on the Keycloak auth URL and again on the `/oidc/authorize` redirect), so it lands in browser history and API Gateway access logs; single-use + the short TTL is what makes that acceptable. Do not lengthen the TTL without revisiting that.
+`src/oidc.ts` serves discovery, JWKS, authorize, token and userinfo in Docker and Lambda; no CORS or duplicate tRPC endpoints.
+Subjects are random permanent UUIDs in `AuthSubject`, keyed by normalized email or Google/Apple subject.
+`requestSocialLoginTicket` is the one exception to "never auto-linked by email": when `verifySocialIdToken`
+returns a verified email (Apple's private-relay addresses count), a brand-new `<provider>:<sub>` identity
+adopts the existing `email:<address>` identity's `subject` via `getOrCreateAuthSubjectLinkedTo`
+(`$setOnInsert`), so a user doesn't hit "Account already exists" switching from email-code to native
+social sign-in. It never runs the other direction, and an already-existing `<provider>:<sub>` record
+keeps its own `subject` — only a first-time native sign-in can be linked this way.
+Require `OIDC_ISSUER`, an exact redirect allowlist, and a token client secret. Deployed Lambdas use `OIDC_SIGNING_KEY_SECRET_ID` (name or ARN of `lca-api/<stage>/oidc-signing-jwk`) pointing to a plain-string Secrets Manager SecretString containing the RSA private JWK JSON (`kty=RSA`, `d`, `kid`, `alg=RS256`). The key is fetched and cached per process; failures return 503 and retry on the next request. Redeploy after rotation. `OIDC_SIGNING_KEY_JWK` remains supported for local/Docker/CI and takes precedence. Any deployed stage (`NODE_ENV=production` or `LAMBDA_STAGE` set) fails closed without a configured key.
+Login codes, tickets and authorization codes are consumed with `getDel` (`src/cache/getDel.ts`, Redis `GETDEL`, requires Redis >= 6.2).
+Rate limiting is two layers, both keyed on `request.ip` (API Gateway `sourceIp` under `serverless-http`; `x-forwarded-for` is attacker-controlled and never trusted). Both fail open if Redis is unreachable. **Layer 1 — failures only** (`src/helpers/rate-limit.helpers.ts`, Redis counters, 10-minute window): the ticket routes use 5 per email plus a 50-per-IP backstop; `/oidc/authorize` (bad client/redirect, invalid ticket) and `/oidc/token` (`invalid_client` only) each use 50 per IP and answer `429 temporarily_unavailable` + `Retry-After` (or an OAuth error redirect once the `redirect_uri` is validated). `invalid_grant` at the token endpoint is deliberately not counted: only the broker (one NAT IP) can reach that branch, and counting the codes it relays would let anyone lock every user out. **Layer 2 — all requests** (`@fastify/rate-limit`, registered in `oidcFastifyPlugin`, Redis-backed when available): 300/min per IP globally so Keycloak's discovery/JWKS polling is never blocked; 60/min per IP on the browser-facing `/oidc/authorize`; a 3000/min sanity ceiling on the server-to-server `/oidc/token` and `/oidc/userinfo` (every legitimate call shares the broker's egress IP, so a tight cap there is a global login ceiling). Layer 2 exists mainly so CodeQL's `js/missing-rate-limiting` recognises the routes; do not remove either layer.
+Unit coverage is in `test/oidc.spec.ts` and `test/auth-tickets.spec.ts`; broker import coverage is gated by `KEYCLOAK_INTEGRATION`.
+Phone OTP remains deferred. The complete live broker round-trip and Firebase-era mapping proof
+are in `test/keycloak-broker-roundtrip.integration.spec.ts` and
+`test/keycloak-migration.integration.spec.ts`, gated on both `KEYCLOAK_INTEGRATION=true`
+and `KEYCLOAK_ROUNDTRIP=true`. With both flags, `vitest.integration.config.ts` selects
+only the live auth suites and aliases Mongo to the explicitly configured API database;
+without them, existing temporary-Mongo integration suites retain their setup.
+See `infra/keycloak/README.md` at the repository root for the local command.
+
+`bun run provision:keycloak` previews the AD-10 mapping migration; `--apply` writes,
+`--email` and `--limit` restrict a batch. Never use this operator-only email join in a
+runtime login route. Dry-run performs no resource writes, including no index creation.
+Existing AuthSubjects are read, not upserted, so repeat apply does not alter lastLoginAt.
+The final global email mapping coverage gate must pass before cutover. Phone-only
+accounts remain a separately reported deferred cohort.
+
+`bun run test:oidc:e2e` also covers the complete email-code broker round-trip in Playwright, with real lca-api and disposable Keycloak/Redis/Mongo. Keep its cleanup contract: exact per-test user/subject deletion, private transient stores, and runner teardown on success/failure/signals. Never point it at shared environments.
+
+### Keycloak broker gotchas
+
+- **Client secret encoding.** Keycloak's broker sends `client_secret_basic` credentials **raw** (not form-url-encoded, contrary to RFC 6749 §2.3.1). `/oidc/token` therefore compares the raw pair first and only falls back to the URL-decoded pair. Secrets containing `+` or `%` are fine.
+- **Phase 2 migration must create the federated identity link.** The realm uses the default `first broker login` flow with `trustEmail: true`. If the migration script pre-creates a Keycloak user by email **without** also creating the `lca-api` federated identity link (`sub` = the `AuthSubject.subject` UUID), the user's first silent hop stops on Keycloak's "Handle Existing Account" web page ("User with email X already exists. How do you want to continue?"), which breaks the no-web-form guarantee. Pre-seed `AuthSubject` and the Keycloak `federatedIdentities` entry together.
+
 ## Email Delivery & Tenant Branding
 
 All transactional emails (login OTP, recovery email OTP, recovery key, endorsement request) are rendered locally via [`@learncard/email-templates`](../../../packages/email-templates/README.md) and delivered as raw HTML through Postmark.

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @welibraryos/lca-api-service
 
+## 1.5.0
+
+### Minor Changes
+
+- [#1589](https://github.com/learningeconomy/LearnCard/pull/1589) [`599f048b082d2ee64775f7a0ef972e171b8c2a8a`](https://github.com/learningeconomy/LearnCard/commit/599f048b082d2ee64775f7a0ef972e171b8c2a8a) Thanks [@Custard7](https://github.com/Custard7)! - Add Keycloak token verification (`verifyKeycloakToken`) using `jose`: exact issuer allowlist, `aud`/`azp` client allowlist, ID/Bearer token-type check, and required `email_verified` / `phone_number_verified` claims. Configured with `KEYCLOAK_ISSUERS`, `KEYCLOAK_AUDIENCES`, and optional `KEYCLOAK_JWKS_URL_OVERRIDES`. Disabled (rejects all tokens) until issuers are configured.
+
+- [#1429](https://github.com/learningeconomy/LearnCard/pull/1429) [`1387cd0a08fa6b0a706c86a5a0376b6c7d706856`](https://github.com/learningeconomy/LearnCard/commit/1387cd0a08fa6b0a706c86a5a0376b6c7d706856) Thanks [@Custard7](https://github.com/Custard7)! - Add a trusted-service `ensureManagedSigningAuthority` route (`POST /signing-authority/managed`) that returns or creates a named signing authority for an owner DID through the standard encrypted-seed path. Brain service now provisions app signing authorities through this route instead of writing plaintext seeds to the LCA API database.
+
+- [#1592](https://github.com/learningeconomy/LearnCard/pull/1592) [`1f1ff54118a5d08c97f57696ca45671f0ee982b8`](https://github.com/learningeconomy/LearnCard/commit/1f1ff54118a5d08c97f57696ca45671f0ee982b8) Thanks [@Custard7](https://github.com/Custard7)! - Add the lca-api OIDC identity provider with RS256 signing, permanent UUID subjects,
+  single-use login tickets, authorization codes and opaque access tokens. The
+  `auth.requestLoginTicket` and `auth.requestSocialLoginTicket` routes verify email
+  codes or native Google/Apple proofs. Keycloak brokers the redirect flow without
+  an additional login form. Includes Docker/Lambda wiring, a development broker
+  fixture and protocol tests. Phone OTP and full live broker round-trip CI remain deferred.
+
+### Patch Changes
+
+- [#1621](https://github.com/learningeconomy/LearnCard/pull/1621) [`d7ca528898d988c65f0dc7084cfdcd41767648c5`](https://github.com/learningeconomy/LearnCard/commit/d7ca528898d988c65f0dc7084cfdcd41767648c5) Thanks [@Custard7](https://github.com/Custard7)! - Add remote enclave backend, hold notifications, cancel links, reminders, and kill switch for escrow recovery.
+
+- [#1679](https://github.com/learningeconomy/LearnCard/pull/1679) [`77e5b0681f5567caa446da57a1746d148ffde27a`](https://github.com/learningeconomy/LearnCard/commit/77e5b0681f5567caa446da57a1746d148ffde27a) Thanks [@Custard7](https://github.com/Custard7)! - Catch module-load index creation failures so a Mongo connect that outlives a frozen Lambda invocation no longer crashes the next request (seen as a 500 on `/oidc/authorize` during Keycloak sign-in).
+
+- [#1670](https://github.com/learningeconomy/LearnCard/pull/1670) [`7656a57d30c6d80b8a25a8bb14bcd3b08b3648c2`](https://github.com/learningeconomy/LearnCard/commit/7656a57d30c6d80b8a25a8bb14bcd3b08b3648c2) Thanks [@Custard7](https://github.com/Custard7)! - Honor CONFIG_STAGE in serverless-offline without implicitly applying a deployed stage's configuration during local startup.
+
+- [#1662](https://github.com/learningeconomy/LearnCard/pull/1662) [`aef0f8cfdef94170104d2179fb04759c8dae7162`](https://github.com/learningeconomy/LearnCard/commit/aef0f8cfdef94170104d2179fb04759c8dae7162) Thanks [@Custard7](https://github.com/Custard7)! - Load deployed OIDC signing keys from Secrets Manager with retryable per-process caching instead of storing private JWKs in Lambda environment variables.
+
+- [#1670](https://github.com/learningeconomy/LearnCard/pull/1670) [`7656a57d30c6d80b8a25a8bb14bcd3b08b3648c2`](https://github.com/learningeconomy/LearnCard/commit/7656a57d30c6d80b8a25a8bb14bcd3b08b3648c2) Thanks [@Custard7](https://github.com/Custard7)! - Document the layered backend configuration model: schema defaults, checked-in non-secret per-stage config files, the Lambda runtime AWS secrets bundle, and real environment variables, plus the Infisical → AWS sync and per-stage cutover.
+
+- [#1670](https://github.com/learningeconomy/LearnCard/pull/1670) [`7656a57d30c6d80b8a25a8bb14bcd3b08b3648c2`](https://github.com/learningeconomy/LearnCard/commit/7656a57d30c6d80b8a25a8bb14bcd3b08b3648c2) Thanks [@Custard7](https://github.com/Custard7)! - Select backend stage files by tenant as well as stage. `CONFIG_TENANT=scouts` loads `config.scouts.<stage>.json` (generated from the live ScoutPass Lambdas), so ScoutPass deployments no longer inherit LearnCard domains, trust settings or seed-encryption flags; a named tenant without a stage file fails closed. `ESCROW_ENCLAVE_MODE` is now forwarded in runtime-secrets bundle mode too.
+
+- [#1664](https://github.com/learningeconomy/LearnCard/pull/1664) [`4a237f41ea4ab0d3bd69f2066039518fdec20984`](https://github.com/learningeconomy/LearnCard/commit/4a237f41ea4ab0d3bd69f2066039518fdec20984) Thanks [@Custard7](https://github.com/Custard7)! - Load optional per-stage runtime secrets before Lambda initialization and scope authentication environment settings by function to avoid Lambda's 4KB limit. Preserve the Firebase environment fallback for stages without a bundle.
+
+- Updated dependencies [[`6209da80c52ac056a7644dab14669192740c9dad`](https://github.com/learningeconomy/LearnCard/commit/6209da80c52ac056a7644dab14669192740c9dad), [`5890451789b18afee45dc5ecbab3fa30aa90f085`](https://github.com/learningeconomy/LearnCard/commit/5890451789b18afee45dc5ecbab3fa30aa90f085), [`1387cd0a08fa6b0a706c86a5a0376b6c7d706856`](https://github.com/learningeconomy/LearnCard/commit/1387cd0a08fa6b0a706c86a5a0376b6c7d706856), [`d7ca528898d988c65f0dc7084cfdcd41767648c5`](https://github.com/learningeconomy/LearnCard/commit/d7ca528898d988c65f0dc7084cfdcd41767648c5), [`d7ca528898d988c65f0dc7084cfdcd41767648c5`](https://github.com/learningeconomy/LearnCard/commit/d7ca528898d988c65f0dc7084cfdcd41767648c5), [`d7ca528898d988c65f0dc7084cfdcd41767648c5`](https://github.com/learningeconomy/LearnCard/commit/d7ca528898d988c65f0dc7084cfdcd41767648c5), [`8f3bc66ab3d3e5e1edb3fbf5f362025875a914ba`](https://github.com/learningeconomy/LearnCard/commit/8f3bc66ab3d3e5e1edb3fbf5f362025875a914ba), [`1387cd0a08fa6b0a706c86a5a0376b6c7d706856`](https://github.com/learningeconomy/LearnCard/commit/1387cd0a08fa6b0a706c86a5a0376b6c7d706856), [`267cf40291b3a63caf178857be0e57feaf5e0948`](https://github.com/learningeconomy/LearnCard/commit/267cf40291b3a63caf178857be0e57feaf5e0948), [`7656a57d30c6d80b8a25a8bb14bcd3b08b3648c2`](https://github.com/learningeconomy/LearnCard/commit/7656a57d30c6d80b8a25a8bb14bcd3b08b3648c2), [`c78c982f9f4911f1ca2973380f19d80db775e012`](https://github.com/learningeconomy/LearnCard/commit/c78c982f9f4911f1ca2973380f19d80db775e012), [`590adf48867d6c6fd504e66a11c9827d5102122d`](https://github.com/learningeconomy/LearnCard/commit/590adf48867d6c6fd504e66a11c9827d5102122d)]:
+    - @learncard/types@5.23.0
+    - @learncard/email-templates@1.2.1
+    - @learncard/sss-key-manager@0.2.1
+    - @learncard/service-config@0.1.1
+    - @learncard/didkit-plugin@1.10.3
+    - @learncard/core@9.4.38
+    - @learncard/helpers@1.6.2
+    - @learncard/init@2.5.2
+    - @learncard/did-web-plugin@1.1.38
+    - @learncard/didkit-plugin-node@0.3.3
+
 ## 1.4.0
 
 ### Minor Changes

package/bootstrapLambda.test.ts

@@ -0,0 +1,76 @@
+import type { APIGatewayProxyEventV2, Context } from 'aws-lambda';
+import { beforeEach, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({ bootstrap: vi.fn(), getApp: vi.fn(), handler: vi.fn() }));
+
+vi.mock('@learncard/service-config', () => ({ bootstrapLambda: mocks.bootstrap }));
+vi.mock('./src/config/stageConfig', () => ({ base: {}, stages: { dev: {}, production: {} } }));
+vi.mock('./oidcLambda', () => ({ handler: mocks.handler }));
+vi.mock('./lambdaApp', () =>
+    Object.fromEntries(
+        ['trpcHandler', 'openApiHandler', 'swaggerUiHandler', 'didWebHandler', 'oidcHandler'].map(
+            name => [name, mocks.handler]
+        )
+    )
+);
+
+beforeEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    mocks.bootstrap.mockReturnValue(mocks.getApp);
+    mocks.handler.mockResolvedValue({ statusCode: 200 });
+});
+
+it('bootstraps the API once with checked-in stage config', async () => {
+    vi.stubEnv('AWS_LAMBDA_FUNCTION_NAME', 'lca-api-dev-api');
+    vi.stubEnv('LAMBDA_STAGE', 'dev');
+    await import('./lambda');
+    expect(mocks.bootstrap).toHaveBeenCalledTimes(1);
+    expect(mocks.bootstrap).toHaveBeenCalledWith({
+        base: {},
+        stages: { dev: {}, production: {} },
+        stage: 'dev',
+        importApp: expect.any(Function),
+    });
+    vi.unstubAllEnvs();
+});
+
+it('uses CONFIG_STAGE outside Lambda rather than LAMBDA_STAGE', async () => {
+    vi.stubEnv('AWS_LAMBDA_FUNCTION_NAME', '');
+    vi.stubEnv('LAMBDA_STAGE', 'production');
+    vi.stubEnv('CONFIG_STAGE', 'dev');
+    await import('./lambda');
+    expect(mocks.bootstrap).toHaveBeenCalledWith(expect.objectContaining({ stage: 'dev' }));
+    vi.unstubAllEnvs();
+});
+
+it('forwards every handler through its bootstrap accessor', async () => {
+    mocks.getApp.mockResolvedValue(
+        Object.fromEntries(
+            [
+                'trpcHandler',
+                'openApiHandler',
+                'swaggerUiHandler',
+                'didWebHandler',
+                'oidcHandler',
+            ].map(name => [name, mocks.handler])
+        )
+    );
+    const lambda = await import('./lambda');
+    const event = {} as APIGatewayProxyEventV2;
+    const context = {} as Context;
+    const callback = vi.fn();
+    const handlers = [
+        lambda.trpcHandler,
+        lambda.openApiHandler,
+        lambda.swaggerUiHandler,
+        lambda.didWebHandler,
+    ];
+    for (const handler of handlers) await handler(event, context, callback);
+    expect(mocks.bootstrap).toHaveBeenCalledTimes(1);
+    expect(mocks.getApp).toHaveBeenCalledTimes(handlers.length);
+    expect(mocks.handler).toHaveBeenCalledTimes(handlers.length);
+    expect(mocks.handler).toHaveBeenCalledWith(event, context, callback);
+    await lambda.oidcHandler(event, context, callback);
+    expect(mocks.getApp).toHaveBeenCalledTimes(handlers.length);
+});

package/config/config.dev.json

@@ -0,0 +1,23 @@
+{
+    "APPLE_OAUTH_CLIENT_IDS": "com.learncard.app,app.learncard.www",
+    "DOMAIN_NAME": "staging.api.learncard.app",
+    "ESCROW_ENCLAVE_ACTIVE_KEY_ID": "escrow-staging-v1",
+    "ESCROW_ENCLAVE_REMOTE_TIMEOUT_MS": "10000",
+    "ESCROW_HOLD_DURATION_MS": "600000",
+    "ESCROW_HOLD_RESTART_MIN_AGE_MS": "300000",
+    "GOOGLE_OAUTH_CLIENT_IDS": "776298253175-74or0s6rg2k2mmdks6d45ro0i4te1bvf.apps.googleusercontent.com,776298253175-kkf562eofl541vu0oedfdvrk40bpkbh7.apps.googleusercontent.com",
+    "KEYCLOAK_AUDIENCES": "learncard-app",
+    "KEYCLOAK_ISSUERS": "https://auth.staging.learncard.app/realms/learncard",
+    "OIDC_CLIENT_ID": "keycloak-broker",
+    "OIDC_ISSUER": "https://staging.api.learncard.app",
+    "OIDC_SIGNING_KEY_SECRET_ID": "lca-api/dev/oidc-signing-jwk",
+    "POSTMARK_BRAND_NAME": "LearnCard",
+    "POSTMARK_ENDORSEMENT_REQUEST_TEMPLATE_ALIAS": "universal-inbox-claim-1",
+    "POSTMARK_FROM_EMAIL": "learncard.com",
+    "POSTMARK_LOGIN_CODE_TEMPLATE_ALIAS": "contact-method-verification-1",
+    "POSTMARK_RECOVERY_EMAIL_CODE_TEMPLATE_ALIAS": "recovery-email-verification",
+    "POSTMARK_RECOVERY_KEY_TEMPLATE_ALIAS": "recovery-key-backup",
+    "SA_SEED_ALLOW_LEGACY_READ": "false",
+    "SA_SEED_ENCRYPT_WRITES": "true",
+    "SENTRY_ENV": "lca-api-staging"
+}

package/config/config.example.json

@@ -0,0 +1,22 @@
+{
+    "APPLE_OAUTH_CLIENT_IDS": "com.example.app,app.example.www",
+    "DOMAIN_NAME": "api.example.com",
+    "ESCROW_ENCLAVE_ACTIVE_KEY_ID": "example-2026-01",
+    "ESCROW_HOLD_DURATION_MS": "604800000",
+    "ESCROW_HOLD_RESTART_MIN_AGE_MS": "86400000",
+    "GOOGLE_OAUTH_CLIENT_IDS": "000000000000-exampleexampleexampleexampleexam.apps.googleusercontent.com",
+    "KEYCLOAK_AUDIENCES": "example-app",
+    "KEYCLOAK_ISSUERS": "https://auth.example.com/realms/example",
+    "OIDC_CLIENT_ID": "keycloak-broker",
+    "OIDC_ISSUER": "https://api.example.com",
+    "OIDC_SIGNING_KEY_SECRET_ID": "lca-api/example/oidc-signing-jwk",
+    "POSTMARK_BRAND_NAME": "Example",
+    "POSTMARK_ENDORSEMENT_REQUEST_TEMPLATE_ALIAS": "universal-inbox-claim-1",
+    "POSTMARK_FROM_EMAIL": "example.com",
+    "POSTMARK_LOGIN_CODE_TEMPLATE_ALIAS": "contact-method-verification-1",
+    "POSTMARK_RECOVERY_EMAIL_CODE_TEMPLATE_ALIAS": "recovery-email-verification",
+    "POSTMARK_RECOVERY_KEY_TEMPLATE_ALIAS": "recovery-key-backup",
+    "SA_SEED_ALLOW_LEGACY_READ": "false",
+    "SA_SEED_ENCRYPT_WRITES": "true",
+    "SENTRY_ENV": "lca-api-example"
+}

package/config/config.json

@@ -0,0 +1 @@
+{}

package/config/config.production.json

@@ -0,0 +1,12 @@
+{
+    "DOMAIN_NAME": "api.learncard.app",
+    "POSTMARK_BRAND_NAME": "LearnCard",
+    "POSTMARK_ENDORSEMENT_REQUEST_TEMPLATE_ALIAS": "universal-inbox-claim-1",
+    "POSTMARK_FROM_EMAIL": "learncard.com",
+    "POSTMARK_LOGIN_CODE_TEMPLATE_ALIAS": "contact-method-verification-1",
+    "POSTMARK_RECOVERY_EMAIL_CODE_TEMPLATE_ALIAS": "recovery-email-verification",
+    "POSTMARK_RECOVERY_KEY_TEMPLATE_ALIAS": "recovery-key-backup",
+    "SA_SEED_ALLOW_LEGACY_READ": "false",
+    "SA_SEED_ENCRYPT_WRITES": "true",
+    "SENTRY_ENV": "lca-api-production"
+}

package/config/config.scouts.dev.json

@@ -0,0 +1,11 @@
+{
+    "DOMAIN_NAME": "staging.api.scoutnetwork.org",
+    "POSTMARK_BRAND_NAME": "ScoutPass",
+    "POSTMARK_FROM_EMAIL": "staging.scoutnetwork.org",
+    "POSTMARK_LOGIN_CODE_TEMPLATE_ALIAS": "sp-login-verification",
+    "POSTMARK_RECOVERY_EMAIL_CODE_TEMPLATE_ALIAS": "sp-recovery-email-verification",
+    "POSTMARK_RECOVERY_KEY_TEMPLATE_ALIAS": "recovery-key-backup",
+    "SA_SEED_ALLOW_LEGACY_READ": "false",
+    "SA_SEED_ENCRYPT_WRITES": "true",
+    "SENTRY_ENV": "scouts-api-staging"
+}

package/config/config.scouts.production.json

@@ -0,0 +1,11 @@
+{
+    "DOMAIN_NAME": "api.scoutnetwork.org",
+    "POSTMARK_BRAND_NAME": "ScoutPass",
+    "POSTMARK_FROM_EMAIL": "scoutnetwork.org",
+    "POSTMARK_LOGIN_CODE_TEMPLATE_ALIAS": "sp-login-verification",
+    "POSTMARK_RECOVERY_EMAIL_CODE_TEMPLATE_ALIAS": "sp-recovery-email-verification",
+    "POSTMARK_RECOVERY_KEY_TEMPLATE_ALIAS": "recovery-key-backup",
+    "SA_SEED_ALLOW_LEGACY_READ": "true",
+    "SA_SEED_ENCRYPT_WRITES": "false",
+    "SENTRY_ENV": "lca-api-production"
+}

package/dist/app.d.ts

@@ -214,6 +214,11 @@ export declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
                             approvedAt: string;
                             contractUpdatedAt: string;
                         } | undefined;
+                        referral?: {
+                            requestId: string;
+                            requestedBy: string;
+                            externalReferenceId?: string | undefined;
+                        } | undefined;
                         uris?: string[] | undefined;
                     } | undefined;
                     inbox?: {
@@ -305,6 +310,20 @@ export declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
             };
             meta: import("trpc-to-openapi").OpenApiMeta;
         }>;
+        ensureManagedSigningAuthority: import("@trpc/server").TRPCMutationProcedure<{
+            input: {
+                name: string;
+                ownerDid: string;
+            };
+            output: {
+                ownerDid: string;
+                name: string;
+                did: string;
+                endpoint: string;
+                _id?: string | undefined;
+            };
+            meta: import("trpc-to-openapi").OpenApiMeta;
+        }>;
         signingAuthorities: import("@trpc/server").TRPCQueryProcedure<{
             input: void;
             output: {
@@ -1108,6 +1127,7 @@ export declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
                     salt?: string | undefined;
                 };
                 sssActivationState: "provisional" | "active";
+                escrowStale?: "mode-mismatch" | "key-rotated" | undefined;
             } | null;
             meta: import("trpc-to-openapi").OpenApiMeta;
         }>;
@@ -1302,7 +1322,9 @@ export declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
         transformer: false;
     }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
         getAttestation: import("@trpc/server").TRPCQueryProcedure<{
-            input: Record<string, never>;
+            input: {
+                nonce?: string | undefined;
+            };
             output: {
                 attestation: {
                     mode: "software" | "nitro";
@@ -1316,6 +1338,7 @@ export declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
                     };
                     document: string;
                     issuedAt: string;
+                    previousKeyIds?: string[] | undefined;
                 };
                 holdDurationMs: number;
             };
@@ -1376,10 +1399,10 @@ export declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
                 recoverySessionToken?: string | undefined;
             };
             output: {
+                holdId: string;
+                releasePolicy: "pin" | "hold";
                 requestedAt: string;
                 releaseAfter: string;
-                releasePolicy: "pin" | "hold";
-                holdId: string;
                 status: "pending";
                 resumeToken: string | null;
                 pinSalt?: string | undefined;
@@ -1417,6 +1440,16 @@ export declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
             };
             meta: import("trpc-to-openapi").OpenApiMeta;
         }>;
+        cancelRecoveryByLink: import("@trpc/server").TRPCMutationProcedure<{
+            input: {
+                holdId: string;
+                token: string;
+            };
+            output: {
+                cancelled: boolean;
+            };
+            meta: import("trpc-to-openapi").OpenApiMeta;
+        }>;
         completeRecovery: import("@trpc/server").TRPCMutationProcedure<{
             input: {
                 holdId: string;
@@ -1500,6 +1533,37 @@ export declare const appRouter: import("@trpc/server").TRPCBuiltRouter<{
             meta: import("trpc-to-openapi").OpenApiMeta;
         }>;
     }>>;
+    auth: import("@trpc/server").TRPCBuiltRouter<{
+        ctx: import("@routes").Context;
+        meta: import("trpc-to-openapi").OpenApiMeta;
+        errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+        transformer: false;
+    }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
+        requestLoginTicket: import("@trpc/server").TRPCMutationProcedure<{
+            input: {
+                email: string;
+                code: string;
+            };
+            output: {
+                success: boolean;
+                ticket?: string | undefined;
+                error?: string | undefined;
+            };
+            meta: import("trpc-to-openapi").OpenApiMeta;
+        }>;
+        requestSocialLoginTicket: import("@trpc/server").TRPCMutationProcedure<{
+            input: {
+                provider: "google" | "apple";
+                idToken: string;
+            };
+            output: {
+                success: boolean;
+                ticket?: string | undefined;
+                error?: string | undefined;
+            };
+            meta: import("trpc-to-openapi").OpenApiMeta;
+        }>;
+    }>>;
 } & {
     test?: TestRouter;
 }>>;

package/dist/cache/getDel.d.ts

@@ -0,0 +1,2 @@
+export declare const getDel: (key: string) => Promise<string | null>;
+export declare const consumeMatchingCode: (key: string, code: string) => Promise<boolean>;

package/dist/cache/getDel.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cache/login-tickets.d.ts

@@ -0,0 +1,12 @@
+export interface LoginTicketPayload {
+    subject: string;
+    email?: string;
+    emailVerified?: boolean;
+    phoneNumber?: string;
+    phoneNumberVerified?: boolean;
+    name?: string;
+    picture?: string;
+    identityKey: string;
+}
+export declare const issueLoginTicket: (payload: LoginTicketPayload) => Promise<string>;
+export declare const redeemLoginTicket: (ticket: string) => Promise<LoginTicketPayload | null>;

package/dist/config/applyDockerStageConfig.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/config/cacheEnvironment.d.ts

@@ -0,0 +1,16 @@
+import 'dotenv/config';
+import { z } from 'zod';
+export declare const cacheEnvironmentShape: {
+    REDIS_HOST: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
+    REDIS_PORT: z.ZodPreprocess<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+};
+export declare const cacheEnvironmentSchema: z.ZodObject<{
+    REDIS_HOST: z.ZodPreprocess<z.ZodOptional<z.ZodString>>;
+    REDIS_PORT: z.ZodPreprocess<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+}, z.core.$strip>;
+export type CacheEnvironment = z.output<typeof cacheEnvironmentSchema>;
+export declare const parseCacheEnvironment: (raw: Record<string, unknown>, source?: string) => CacheEnvironment;
+export declare const environment: {
+    REDIS_HOST?: string | undefined;
+    REDIS_PORT?: number | undefined;
+};