@learncard/lca-api-service 1.3.2 → 1.5.0

package/.env.example

@@ -1,9 +1,27 @@
 # 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
+# writes and set a key from `openssl rand -hex 32`; retain it for the database lifetime.
+SA_SEED_LOCAL_KEK=
+SA_SEED_KMS_KEY_ARN=
+SA_SEED_ENCRYPT_WRITES=false
+SA_SEED_ALLOW_LEGACY_READ=true
 MONGO_URI=mongodb://localhost:27017
 MONGO_DB_NAME=learncard
 DOMAIN_NAME=
@@ -12,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=
@@ -25,6 +90,38 @@ POSTMARK_ENDORSEMENT_REQUEST_TEMPLATE_ALIAS=
 POSTMARK_RECOVERY_EMAIL_CODE_TEMPLATE_ALIAS=
 POSTMARK_RECOVERY_KEY_TEMPLATE_ALIAS=
 
+ESCROW_RELAY_URL=
+ESCROW_RELAY_AUTH_TOKEN=
+
+# Automatic (escrow) recovery. Unset disables all /keys/escrow routes.
+# Local dev: set ESCROW_ENCLAVE_MODE=software with the disposable fixture below, which
+# pairs with the public key in apps/learn-card-app/environments/learncard/config.local.json.
+# The fixture is NOT a secret and must never be used outside local development.
+# See docs/how-to-guides/deploy-infrastructure/sss-key-management-config.md.
+ESCROW_ENCLAVE_MODE=
+ESCROW_ENCLAVE_ACTIVE_KEY_ID=
+ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON=
+# ESCROW_ENCLAVE_MODE=software
+# ESCROW_ENCLAVE_ACTIVE_KEY_ID=local-dev
+# 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=
@@ -34,8 +131,8 @@ TROOP_DASHBOARD_ID=
 
 SENTRY_DSN=
 SENTRY_ENV=development
-IS_OFFLINE=false
+IS_OFFLINE=true
 IS_CI=false
 IS_E2E_TEST=false
 SKIP_DIDKIT_NAPI=false
-CI=false
+CI=false

package/AGENTS.md

@@ -4,22 +4,80 @@ The LearnCard Application API (`lca-api`) is the tRPC service backing client-sid
 
 ## Build & Development Commands
 
--   Build: `bun run build`
--   Dev: `bun run dev` — watches and rebuilds
--   Start: `bun run start` — local server (default port from env, typically 5100)
--   Test: `bun run test`
--   Run tests once (non-watch): `bun run test -- run` (equivalent to `vitest run`)
--   Run single test: `bun run test test/credentials.spec.ts`
--   Typecheck: `bunx tsc --noEmit`
+### 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)
+- Test: `bun run test`
+- Run tests once (non-watch): `bun run test -- run` (equivalent to `vitest run`)
+- Run single test: `bun run test test/credentials.spec.ts`
+- Typecheck: `bunx tsc --noEmit`
 
 ## Code Style Guidelines
 
--   **TypeScript**: Strict typing, interfaces in dedicated files under `src/types/`
--   **Imports**: Path aliases (`@helpers/*`, `@routes/*`, `@cache/*`)
--   **Routes**: tRPC routers under `src/routes/` — one router per resource
--   **Error handling**: `TRPCError` with specific codes (`BAD_REQUEST`, `UNAUTHORIZED`, `INTERNAL_SERVER_ERROR`, `NOT_FOUND`)
--   **Named exports only** — no one-line default exports
--   **Explicit return types** on all exported functions
+- **TypeScript**: Strict typing, interfaces in dedicated files under `src/types/`
+- **Imports**: Path aliases (`@helpers/*`, `@routes/*`, `@cache/*`)
+- **Routes**: tRPC routers under `src/routes/` — one router per resource
+- **Error handling**: `TRPCError` with specific codes (`BAD_REQUEST`, `UNAUTHORIZED`, `INTERNAL_SERVER_ERROR`, `NOT_FOUND`)
+- **Named exports only** — no one-line default exports
+- **Explicit return types** on all exported functions
 
 ## Request Lifecycle & Context
 
@@ -32,33 +90,86 @@ Every request goes through `createContext` in `src/routes/index.ts`, which:
 
 ### Route Procedures
 
--   `openRoute` — unauthenticated, tenant + Sentry tracing attached
--   `didRoute` — requires `ctx.user.did` (DID-auth VP verified, challenge may be stale)
--   `didAndChallengeRoute` — requires `didRoute` + live challenge
--   `authorizedDidRoute` — requires `didRoute` + DID in `AUTHORIZED_DIDS` env allowlist
+- `openRoute` — unauthenticated, tenant + Sentry tracing attached
+- `didRoute` — requires `ctx.user.did` (DID-auth VP verified, challenge may be stale)
+- `didAndChallengeRoute` — requires `didRoute` + live challenge
+- `authorizedDidRoute` — requires `didRoute` + DID in `AUTHORIZED_DIDS` env allowlist
 
 ## SSS Key Management Routes (`src/routes/keys.ts`)
 
 The `keysRouter` implements the server side of Shamir Secret Sharing key management used by `@learncard/sss-key-manager`:
 
-| Route                               | Purpose                                                                                                                                             |
-| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `POST /keys/auth-share`             | Fetch the encrypted auth share for a user by contact method + provider                                                                              |
-| `PUT /keys/auth-share`              | Store / rotate the auth share; manages `shareVersion` for historical lookup                                                                         |
-| `GET /keys/recovery`                | Fetch an encrypted recovery share (passkey / phrase / backup)                                                                                       |
-| `POST /keys/recovery`               | Register a recovery method (passkey / phrase / backup / email)                                                                                      |
-| `POST /keys/recovery-email`         | Start recovery email verification (sends 6-digit OTP)                                                                                               |
-| `POST /keys/recovery-email/verify`  | Verify the OTP and persist the recovery email on the UserKey                                                                                        |
-| `POST /keys/email-backup`           | Relay the emailed recovery share to the user's primary or recovery email. **Share is never persisted** — in-memory for the duration of the request. |
-| `POST /keys/upgrade-contact-method` | Upgrade phone-only users to email + phone                                                                                                           |
-| `POST /keys/migrate`                | Mark a UserKey as migrated from the legacy Web3Auth pathway                                                                                         |
+| Route                               | Purpose                                                                                                         |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `POST /keys/auth-share`             | Fetch the encrypted auth share for a user by contact method + provider                                          |
+| `PUT /keys/auth-share`              | Store / rotate the auth share; manages `shareVersion` for historical lookup                                     |
+| `GET /keys/recovery`                | Fetch an encrypted recovery share (passkey / phrase / backup)                                                   |
+| `POST /keys/recovery`               | Register a recovery method (passkey / phrase / backup / email)                                                  |
+| `POST /keys/recovery-email`         | Start recovery email verification (sends 6-digit OTP)                                                           |
+| `POST /keys/recovery-email/verify`  | Verify the OTP and persist the recovery email on the UserKey                                                    |
+| `POST /keys/email-backup`           | Proxy a client-encrypted recovery payload to the isolated email relay. The share is never visible to `lca-api`. |
+| `POST /keys/upgrade-contact-method` | Upgrade phone-only users to email + phone                                                                       |
+| `POST /keys/migrate`                | Mark a UserKey as migrated from the legacy Web3Auth pathway                                                     |
+
+### Escrow recovery routes
+
+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/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
 
--   **Auth shares are encrypted at rest** with a KEK derived from `SEED`. Losing `SEED` means every stored auth share is permanently unrecoverable.
--   **Recovery shares are encrypted client-side** (except the phrase method, which stores only shareVersion metadata).
--   **Email share is never written to the DB.** The `sendEmailBackup` route holds it in memory only for the duration of the request; Postmark receives it but never stores it.
--   **`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.
+- **Auth shares are encrypted at rest** with a KEK derived from `SEED`. Losing `SEED` means every stored auth share is permanently unrecoverable.
+- **Recovery shares are encrypted client-side** (except the phrase method, which stores only shareVersion metadata).
+- **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
 
@@ -90,10 +201,10 @@ The adapter additionally re-throws when local rendering fails for a **sentinel a
 
 ### Rules for Route Authors
 
--   **Always pass `branding: ctx.tenant?.emailBranding`** to `getDeliveryService().send()`. Calls without branding render with LearnCard defaults regardless of the caller's tenant.
--   **Use `getFrom({ mailbox, branding: ctx.tenant?.emailBranding })`** for the `from` field so the domain matches the tenant (e.g. `recovery@vetpass.app`).
--   **Use the local template ID as the `templateAlias`** — e.g. `'recovery-key'`, `'recovery-email-code'`, `'login-verification-code'`, `'endorsement-request'`. These are pre-registered as sentinels in `LOCAL_TEMPLATE_ALIASES`. Env-var overrides (`POSTMARK_*_TEMPLATE_ALIAS`) are optional; `templateAlias: RECOVERY_KEY_TEMPLATE_ALIAS || 'recovery-key'` is the canonical pattern.
--   **Do not write plain-text fallbacks.** The adapter renders the React Email template regardless; plain-text branches are dead code and should be deleted on sight.
+- **Always pass `branding: ctx.tenant?.emailBranding`** to `getDeliveryService().send()`. Calls without branding render with LearnCard defaults regardless of the caller's tenant.
+- **Use `getFrom({ mailbox, branding: ctx.tenant?.emailBranding })`** for the `from` field so the domain matches the tenant (e.g. `recovery@vetpass.app`).
+- **Use the local template ID as the `templateAlias`** — e.g. `'recovery-key'`, `'recovery-email-code'`, `'login-verification-code'`, `'endorsement-request'`. These are pre-registered as sentinels in `LOCAL_TEMPLATE_ALIASES`. Env-var overrides (`POSTMARK_*_TEMPLATE_ALIAS`) are optional; `templateAlias: RECOVERY_KEY_TEMPLATE_ALIAS || 'recovery-key'` is the canonical pattern.
+- **Do not write plain-text fallbacks.** The adapter renders the React Email template regardless; plain-text branches are dead code and should be deleted on sight.
 
 ### Env Vars
 
@@ -108,14 +219,14 @@ See [`docs/how-to-guides/deploy-infrastructure/sss-key-management-config.md`](..
 
 ## Testing Notes
 
--   Test files in `test/` spin up a Fastify server via `getClient()` and exercise routes with `fetch`.
--   `IS_E2E_TEST=true` disables Firebase Admin SDK calls and switches email delivery to the log adapter.
--   For tenant-aware tests, set `X-Tenant-Id` on the request; `createContext` will pick it up and `ctx.tenant.emailBranding` will be populated from the registry in `@learncard/email-templates`.
+- Test files using `getClient()` exercise tRPC procedures via `appRouter.createCaller()`, not an HTTP server. Header-context tests inject `providerToken`; they do not verify HTTP header extraction or CORS.
+- `IS_E2E_TEST=true` disables Firebase Admin SDK calls and switches email delivery to the log adapter.
+- For tenant-aware tests, set `X-Tenant-Id` on the request; `createContext` will pick it up and `ctx.tenant.emailBranding` will be populated from the registry in `@learncard/email-templates`.
 
 ## Cross-References
 
--   [Tenant-Branded Emails (architecture)](../../../docs/core-concepts/tenant-branded-emails.md) — end-to-end email flow
--   [Configure Tenant-Branded Emails](../../../docs/how-to-guides/configure-tenant-branded-emails.md) — operator-facing setup
--   [SSS Key Management Config](../../../docs/how-to-guides/deploy-infrastructure/sss-key-management-config.md) — env var reference for deployers
--   [`@learncard/email-templates` README](../../../packages/email-templates/README.md) — template catalog, tenant registry, preview server
--   [`@learncard/sss-key-manager`](../../../packages/sss-key-manager/README.md) — client side of SSS key management
+- [Tenant-Branded Emails (architecture)](../../../docs/core-concepts/tenant-branded-emails.md) — end-to-end email flow
+- [Configure Tenant-Branded Emails](../../../docs/how-to-guides/configure-tenant-branded-emails.md) — operator-facing setup
+- [SSS Key Management Config](../../../docs/how-to-guides/deploy-infrastructure/sss-key-management-config.md) — env var reference for deployers
+- [`@learncard/email-templates` README](../../../packages/email-templates/README.md) — template catalog, tenant registry, preview server
+- [`@learncard/sss-key-manager`](../../../packages/sss-key-manager/README.md) — client side of SSS key management

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # @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
+
+- [#1565](https://github.com/learningeconomy/LearnCard/pull/1565) [`4b83aa9ee802f0d7a54adc5f053a7376fa103cdd`](https://github.com/learningeconomy/LearnCard/commit/4b83aa9ee802f0d7a54adc5f053a7376fa103cdd) Thanks [@Custard7](https://github.com/Custard7)! - Escrow PIN fast release: an optional PIN release policy on the existing escrow-recovery substrate.
+
+    - The escrow recovery share now supports a second release policy alongside the 7-day hold: `pin`. A user who sets an optional 6-12 digit PIN can recover immediately by presenting it, instead of waiting for the hold. Custodianship is unchanged — this adds a release policy on the already-sealed blob, not a second custodial share.
+    - PIN verifier lives inside the enclave-sealed envelope (`EscrowBlobPlaintext.pinVerifier`); a leaked DB alone yields nothing to brute force. Client derives the proof with Argon2id and the enclave constant-time compares.
+    - 10 lifetime failed attempts locks the PIN (`EscrowPinLockedError`); the 7-day hold path is always available as a fallback. Setting/changing a PIN rotates the escrow share.
+    - Carry the sealed PIN verifier across share rotations while preserving its salt and attempt counters; explicit removal and unavailable carry still enroll without a PIN.
+    - New app UI: recovery PIN setup overlay after first setup (skippable), a Recovery PIN row in recovery settings (set/change/remove), and a PIN-first step in the recovery flow with fallback to the existing hold.
+
+- [#1529](https://github.com/learningeconomy/LearnCard/pull/1529) [`0e262737aafb8248e88e05039c83a3f30be6750f`](https://github.com/learningeconomy/LearnCard/commit/0e262737aafb8248e88e05039c83a3f30be6750f) Thanks [@Custard7](https://github.com/Custard7)! - SSS prod hardening: confirmed recovery enrollment, lost-login identity rebind, and an isolated email relay.
+
+    - Recovery methods now carry `confirmedAt` and must be proven before they count (email confirmation code, phrase challenge words, backup re-decrypt, passkey round trip). New SSS accounts are `active` immediately; web3auth migrations stay `provisional` until a method is confirmed.
+    - New recovery-session flow lets a user whose sign-in identity is gone recover via a verified personal email and bind a new sign-in.
+    - Email recovery shares are encrypted on the client to an isolated relay's public key; `lca-api` never sees plaintext. Provider tokens move from query strings to the `X-Auth-Token` header.
+    - Sensitive key routes require a single-use DID challenge; key records are keyed by immutable provider ID.
+    - `recovery-key` email template now requires `confirmationCode`.
+    - Auth-share initialization requires the provider uniqueness index before inserting, preventing competing first writes from creating duplicate accounts. Existing records with missing or BSON-null auth material retain atomic update protection.
+    - Automatic stale-key cleanup preserves unresolved pending shares for delayed commits; explicit device forgetting still removes them. Custom SSS storage adapters now implement `deleteDeviceShare(id?)` to remove only the selected share and its version.
+
+### Patch Changes
+
+- [#1601](https://github.com/learningeconomy/LearnCard/pull/1601) [`3850da277fe17d421bc055cef3cac65616b7626d`](https://github.com/learningeconomy/LearnCard/commit/3850da277fe17d421bc055cef3cac65616b7626d) Thanks [@rhen92](https://github.com/rhen92)! - fix: [LC-2207] Limit wrong code attempts on email login verification
+
+- [#1636](https://github.com/learningeconomy/LearnCard/pull/1636) [`dab95a1313b10f0339a4284cb5dcdc2f459dcdd5`](https://github.com/learningeconomy/LearnCard/commit/dab95a1313b10f0339a4284cb5dcdc2f459dcdd5) Thanks [@Custard7](https://github.com/Custard7)! - Fix lca-api deploys failing on Lambda's 4KB environment limit: escrow variables are now attached only to the trpc/api functions, omitted when unset, and enclave settings are gated on `ESCROW_ENCLAVE_MODE`. SSS client errors now include the HTTP status code (HTTP/2 responses have an empty `statusText`).
+
+- [#1619](https://github.com/learningeconomy/LearnCard/pull/1619) [`5639d80a9d111f8156469e6692c37ffb354d2ec7`](https://github.com/learningeconomy/LearnCard/commit/5639d80a9d111f8156469e6692c37ffb354d2ec7) Thanks [@gerardopar](https://github.com/gerardopar)! - feat: [LC-2161] - Encrypt hosted signing-authority seeds with AWS KMS
+
+- Updated dependencies [[`4b83aa9ee802f0d7a54adc5f053a7376fa103cdd`](https://github.com/learningeconomy/LearnCard/commit/4b83aa9ee802f0d7a54adc5f053a7376fa103cdd), [`f7b54c45cf495e14cc7b2824653c8f0a63b61660`](https://github.com/learningeconomy/LearnCard/commit/f7b54c45cf495e14cc7b2824653c8f0a63b61660), [`dab95a1313b10f0339a4284cb5dcdc2f459dcdd5`](https://github.com/learningeconomy/LearnCard/commit/dab95a1313b10f0339a4284cb5dcdc2f459dcdd5), [`b184f5552abf37a11468d435e5cea07fc35e1993`](https://github.com/learningeconomy/LearnCard/commit/b184f5552abf37a11468d435e5cea07fc35e1993), [`0e262737aafb8248e88e05039c83a3f30be6750f`](https://github.com/learningeconomy/LearnCard/commit/0e262737aafb8248e88e05039c83a3f30be6750f), [`d436c39e00994e6d8c77e7b94985a51fe1f42adb`](https://github.com/learningeconomy/LearnCard/commit/d436c39e00994e6d8c77e7b94985a51fe1f42adb)]:
+    - @learncard/sss-key-manager@0.2.0
+    - @learncard/types@5.22.0
+    - @learncard/email-templates@1.2.0
+    - @learncard/helpers@1.6.1
+    - @learncard/core@9.4.37
+    - @learncard/init@2.5.1
+    - @learncard/did-web-plugin@1.1.37
+    - @learncard/didkit-plugin@1.10.2
+    - @learncard/didkit-plugin-node@0.3.2
+
 ## 1.3.2
 
 ### Patch 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/compose.env

@@ -0,0 +1,5 @@
+# Local Docker defaults only; encryption is opt-in and requires an explicit KEK.
+# Load before optional .env files so existing custom keys and rollout settings win.
+# For persistent data, configure a unique KEK before the first encrypted write and retain it.
+SA_SEED_ENCRYPT_WRITES=false
+SA_SEED_ALLOW_LEGACY_READ=true

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 @@
+{}