@learncard/lca-api-service 1.3.2 → 1.4.0

package/.env.example

@@ -4,6 +4,12 @@
 NODE_ENV=development
 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=
@@ -25,6 +31,24 @@ 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_DURATION_MS=60000
+
 ANDROID_PUSH_ICON=
 REDIS_HOST=
 REDIS_PORT=
@@ -34,8 +58,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,22 @@ 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`
+- 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 +32,48 @@ 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/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.
 
 ## Email Delivery & Tenant Branding
 
@@ -90,10 +105,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 +123,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,46 @@
 # @welibraryos/lca-api-service
 
+## 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/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/dist/accesslayer/signing-authority/index.d.ts

@@ -1,16 +1,22 @@
 export declare const getSigningAuthoritiesCollection: () => import("mongodb").Collection<{
     ownerDid: string;
     name: string;
-    seed: string;
     _id?: string | undefined;
+    seed?: string | undefined;
+    encryptedSeed?: string | undefined;
+    encryptedDek?: string | undefined;
+    keyVersion?: "kms-v1" | "local-v1" | undefined;
     did?: string | undefined;
     endpoint?: string | undefined;
 }>;
 export declare const SigningAuthorities: import("mongodb").Collection<{
     ownerDid: string;
     name: string;
-    seed: string;
     _id?: string | undefined;
+    seed?: string | undefined;
+    encryptedSeed?: string | undefined;
+    encryptedDek?: string | undefined;
+    keyVersion?: "kms-v1" | "local-v1" | undefined;
     did?: string | undefined;
     endpoint?: string | undefined;
 }>;