@terreno/mcp 56.0.0-beta.0 → 56.0.0-beta.2

package/src/docs/versioned/next/implementationPlans/password-reset-and-email-verification.md

@@ -0,0 +1,147 @@
+# Implementation Plan: Password reset and email verification
+
+**Status:** Draft
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1023
+**Priority:** High
+**Effort:** Big batch
+**Owner:** unassigned
+**Created:** 2026-08-09
+**Program:** [B2B platform](b2b-platform-program.md)
+**Depends on:** [comms-abstraction](comms-abstraction.md), [comms-adapter-sendgrid](comms-adapter-sendgrid.md)
+**RTK deprecation flag:** None — the RTK client's existing `resetPassword` endpoint gets a
+backend at last; new client work is a thin screen pair noted in UI
+
+## Goal
+
+The JWT auth path has no way to recover an account or verify an email address: the
+`@terreno/rtk` client ships a `resetPassword` mutation with **no backend route**, and
+nothing sets or checks email verification. This IP adds forgot/reset password and email
+verification flows to `@terreno/api`'s JWT auth, wires the Better Auth equivalents to the
+same mail templates, and sends everything through `@terreno/comms`.
+
+## Non-Goals
+
+- MFA / step-up auth (`mfa-step-up-auth` item).
+- Magic-link login.
+- SMS-based recovery (possible later via the Twilio Verify adapter).
+- Account lockout / brute-force throttling beyond token single-use + expiry
+  (`rate-limiting` item hardens the endpoints).
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Token design | 32-byte crypto-random token, stored **hashed** (sha256) with expiry (`1h` reset / `24h` verify) and single-use consumption; separate `AuthToken` collection rather than fields on User |
+| Enumeration safety | `POST /auth/forgotPassword` always returns 202 regardless of whether the email exists |
+| Password set mechanism | `passport-local-mongoose`'s `setPassword` on the user document, then invalidate all refresh tokens |
+| RTK client compatibility | The existing RTK `resetPassword` endpoint's path/shape is the contract — verify at implementation time and alias if it differs from `/auth/resetPassword` |
+| Verification gating | Opt-in `requireEmailVerification` auth option: unverified users get 403 with code `email-not-verified` on login; default off (non-breaking) |
+| Better Auth path | Enable Better Auth's built-in reset/verification, providing `sendResetPassword` / `sendVerificationEmail` hooks that call the same comms templates so both auth paths send identical mail |
+| Link targets | Deep-link/URL base from a new `authOptions.publicAppUrl`; web route examples in example-frontend |
+
+## Architecture
+
+```
+api/src/authTokens.ts      # AuthToken model + issue/consume helpers
+api/src/authRecovery.ts    # forgot/reset/verify routes + options
+                           # registered by addAuthRoutes when comms is available
+comms templates            # resetPassword + verifyEmail templates (subject/text/html)
+```
+
+Flow (reset): `POST /auth/forgotPassword {email}` → 202 always; if user exists, issue
+token, send mail with `${publicAppUrl}/resetPassword?token=...` → `POST
+/auth/resetPassword {token, password}` → validate + consume token, `setPassword`,
+invalidate refresh tokens, 200.
+
+Flow (verify): token issued on signup (and via `POST /auth/sendVerification` for
+re-sends, authenticated); `POST /auth/verifyEmail {token}` sets `user.emailVerified =
+true`.
+
+## Models
+
+**AuthToken** — `userId` (ref User, required, indexed), `tokenHash` (string, unique),
+`type` ("passwordReset" | "emailVerification"), `expiresAt` (date, TTL-indexed),
+`consumedAt` (date, optional). Statics: `issueFor(user, type)`, `consume(token, type)`
+(atomic findOneAndUpdate guarding single-use).
+
+**User** — adds `emailVerified` (boolean, default false) via a small
+`emailVerificationPlugin` so existing user schemas opt in without breaking.
+
+## APIs
+
+| Method | Path | Permissions | Notes |
+|---|---|---|---|
+| POST | `/auth/forgotPassword` | anonymous | `{email}` → always 202 |
+| POST | `/auth/resetPassword` | anonymous | `{token, password}`; path/shape matched to the RTK client contract |
+| POST | `/auth/sendVerification` | IsAuthenticated | Re-send verification mail |
+| POST | `/auth/verifyEmail` | anonymous | `{token}` |
+
+All registered by `addAuthRoutes` when a mail-capable `CommsApp` is present; without one,
+routes 501 in production and console-send in development (inherited comms behavior).
+
+## Notifications
+
+Two mail templates (`resetPassword`, `verifyEmail`) shipped in `@terreno/comms` templates
+with app-override hooks.
+
+## UI
+
+example-frontend: `/resetPassword` (token from URL, new-password form using the existing
+RTK `resetPassword` mutation) and a "verify your email" banner + re-send button on the
+profile screen. `LoginScreen` gains an optional `onForgotPassword` link prop in
+`@terreno/ui`.
+
+## Phases
+
+1. **Token infrastructure:** AuthToken model, issue/consume, `emailVerificationPlugin`,
+   unit tests.
+2. **JWT routes + mail:** four routes, templates, refresh-token invalidation,
+   enumeration-safety + single-use/expiry test suite.
+3. **Better Auth parity:** wire `sendResetPassword`/`sendVerificationEmail` hooks to the
+   same templates; parity tests.
+4. **Client + docs:** example-frontend screens, `@terreno/ui` login link prop, SDK regen,
+   `docs/how-to/password-reset.md`, env/reference docs.
+
+## Feature Flags & Migrations
+
+`requireEmailVerification` defaults off; enabling it for an existing app is documented
+(backfill `emailVerified: true` for existing users or accept re-verification). No schema
+migration otherwise.
+
+## Activity Log & User Updates
+
+Token issue/consume and verification events logged via `logger` and `CommsMessage`
+rows; no user-facing activity feed.
+
+## Not Included / Future Work
+
+- Password strength policy hooks (exists via `PasswordRequirements` UI; server policy is
+  future work).
+- Admin-triggered forced resets (admin panel action — future).
+- Endpoint rate limiting (`rate-limiting` item).
+
+## Files to Create / Modify
+
+- `api/src/authTokens.ts`, `api/src/authRecovery.ts` (new), `api/src/auth.ts`,
+  `api/src/plugins.ts` (emailVerificationPlugin), `api/src/index.ts`
+- `comms/src/templates.ts` — two templates
+- `example-frontend/app/resetPassword.tsx`, profile banner, SDK regen
+- `ui/src/login/LoginScreen.tsx` — `onForgotPassword` prop
+- `docs/how-to/password-reset.md`, `docs/reference/environment-variables.md`
+
+## Task List
+
+See [docs/tasks/password-reset-and-email-verification.md](../tasks/password-reset-and-email-verification.md).
+
+## Acceptance Criteria
+
+- [ ] `POST /auth/forgotPassword` returns 202 for existing and non-existing emails alike,
+      sending mail only for existing ones.
+- [ ] A reset token works exactly once, fails after expiry, and a successful reset
+      invalidates outstanding refresh tokens.
+- [ ] The unmodified RTK client `resetPassword` mutation completes the flow end to end.
+- [ ] With `requireEmailVerification` on, an unverified user gets 403 code
+      `email-not-verified` on login and can complete verification to proceed.
+- [ ] Better Auth mode sends the same two templates through comms.
+- [ ] example-frontend can complete forgot → email link (console adapter output in dev) →
+      reset → login with the new password; UI verification evidence attached to the PR.

package/src/docs/versioned/next/implementationPlans/positioning-django-rails-universal.md

@@ -1,6 +1,7 @@
 # Implementation Plan: Positioning — "Django/Rails for TypeScript, with Universal Apps"
 
 **Status:** Draft — blocking questions open
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1008
 **Priority:** High
 **Effort:** Small batch
 **Owner:** unassigned

package/src/docs/versioned/next/implementationPlans/public-roadmap-github.md

@@ -1,6 +1,7 @@
 # Implementation Plan: Public Roadmap on GitHub
 
 **Status:** Approved — decisions recorded (2026-07-29)
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1004
 **Priority:** High
 **Effort:** Small batch
 **Owner:** unassigned

package/src/docs/versioned/next/implementationPlans/upgrade-guides-and-skill.md

@@ -1,6 +1,7 @@
 # Implementation Plan: Upgrade Guides and the `upgrading-terreno` Skill
 
 **Status:** Draft — blocked on PR #869
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1013
 **Priority:** High
 **Effort:** Big batch
 **Owner:** unassigned

package/src/docs/versioned/next/implementationPlans/web-ssr-and-admin-spa.md

@@ -1,6 +1,7 @@
 # Implementation Plan: Server-Side Rendering for Universal Web (and Admin SPA)
 
 **Status:** Draft — blocking questions open
+**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1017
 **Priority:** Medium
 **Effort:** Epic
 **Owner:** unassigned

package/src/docs/versioned/next/reference/README.md

@@ -8,10 +8,15 @@ Technical reference for Terreno packages and APIs. Information-oriented, precise
 - [@terreno/ui](ui.md) — Components, theming, layout
 - [@terreno/rtk](rtk.md) — Auth slice, SDK codegen, token handling
 - [@terreno/syncdb](syncdb.md) — Local-first data layer (reads, writes, offline sync)
+- [@terreno/ai](ai.md) — AI service, GPT routes, Langfuse integration
 - [@terreno/admin-backend](admin-backend.md) — Auto-generated admin CRUD endpoints
 - [@terreno/admin-frontend](admin-frontend.md) — Admin panel UI components
+- [@terreno/admin-spa](admin-spa.md) — Standalone admin SPA + Express serve plugin
+- [@terreno/api-health](api-health.md) — Health check TerrenoPlugin
+- [@terreno/comms](comms.md) — Pluggable mail, SMS, push, and verification providers
 - [@terreno/feature-flags](feature-flags.md) — Feature flags and A/B testing plugin
 - [@terreno/mcp](mcp-server.md) — AI coding assistant integration (MCP)
+- [@terreno/test](test.md) — Bun test helpers and in-memory MongoDB
 
 ## Configuration
 

package/src/docs/versioned/next/reference/admin-spa.md

@@ -0,0 +1,130 @@
+# @terreno/admin-spa
+
+Standalone Expo Router admin web SPA plus an Express plugin (`AdminSpaServeApp`) that serves the pre-built static export from a Terreno backend on the same origin.
+
+## Table of Contents
+
+- [Install](#install)
+- [Commands](#commands)
+- [Architecture](#architecture)
+- [AdminSpaServeApp](#adminspaserveapp)
+- [App config](#app-config)
+- [Serving and caching](#serving-and-caching)
+- [Mount path constraint](#mount-path-constraint)
+- [Standalone SPA vs embedded admin-frontend](#standalone-spa-vs-embedded-admin-frontend)
+
+## Install
+
+```bash
+bun add @terreno/admin-spa @terreno/api
+```
+
+`@terreno/api` is a peer dependency (TerrenoPlugin registration).
+
+## Commands
+
+From the `@terreno/admin-spa` package directory:
+
+```bash
+bun run compile      # Compile the server plugin (src/ -> src/dist)
+bun run build:web    # Expo static export into dist/
+bun run dev          # expo start --web --port 8083
+bun run test:ci      # Serve-plugin unit tests
+bun run smoke        # Smoke test over built dist/
+bun run test:e2e     # Playwright e2e over built dist/
+```
+
+## Architecture
+
+```
+admin-spa/
+  src/
+    serve.ts           # AdminSpaServeApp TerrenoPlugin
+    appConfig.ts       # AdminSpaAppConfig defaults + merge helper
+    index.ts           # Public exports
+  app/                 # Expo Router SPA (Better Auth + admin screens)
+  store/               # Redux + Better Auth client
+  dist/                # Pre-built static export (produced by build:web)
+```
+
+Boot flow in the SPA: `AppConfigGate` fetches `${basePath}/app-config.json` → `StoreProvider` builds Better Auth + Redux → `AdminGate` redirects anonymous users to `/login` and non-admins to `/forbidden`.
+
+## AdminSpaServeApp
+
+`AdminSpaServeApp` implements `TerrenoPlugin`. Register it on `TerrenoApp` alongside `AdminApp` and auth plugins:
+
+```typescript
+import {AdminSpaServeApp} from "@terreno/admin-spa";
+import {AdminApp} from "@terreno/admin-backend";
+import {BetterAuthApp, TerrenoApp} from "@terreno/api";
+
+new TerrenoApp({userModel: User})
+  .register(new BetterAuthApp({config: betterAuthConfig, userModel: User}))
+  .register(new AdminApp({models: [...]}))
+  .register(
+    new AdminSpaServeApp({
+      basePath: "/console",
+      appConfig: {brandName: "Acme Admin", providers: ["email", "google"]},
+      devProxyTarget: process.env.ADMIN_SPA_DEV_PROXY,
+    })
+  )
+  .start();
+```
+
+`example-backend` registers the plugin when `ADMIN_SPA_ENABLED=true`, with optional `ADMIN_SPA_DEV_PROXY` and `ADMIN_SPA_DIST_DIR` overrides.
+
+### AdminSpaServeOptions
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `basePath` | `"/console"` | URL prefix where the SPA is mounted. Admin API stays at `/admin`. |
+| `appConfig` | see [App config](#app-config) | Partial config merged over defaults; served at `${basePath}/app-config.json`. |
+| `distDir` | `<package>/dist` | Directory containing the pre-built static export (tests/custom builds). |
+| `devProxyTarget` | — | When set, proxy all SPA paths to a running `expo start --web` server (e.g. `http://localhost:8083`). `app-config.json` is still served by the plugin. |
+
+### Utility exports
+
+- `rewriteIndexHtml(html, basePath)` — Rewrites absolute `/_expo/` and `/assets/` refs for sub-path mounts.
+- `injectBaseGlobal(html, basePath)` — Injects `window.__ADMIN_SPA_BASE__` before `</head>`.
+- `resolveAppConfig(overrides?)` — Merge partial config with `DEFAULT_APP_CONFIG`.
+- `DEFAULT_APP_CONFIG` — Default `app-config.json` values.
+
+## App config
+
+`AdminSpaAppConfig` fields (from `appConfig.ts`):
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `brandName` | `"Terreno Admin"` | Header brand name |
+| `logoUrl` | — | Optional logo URL (absolute or relative) |
+| `primaryColor` | `"#2563EB"` | Primary brand color (hex) |
+| `providers` | `["email"]` | Login providers: `"email"`, `"google"`, `"github"`, `"apple"` |
+| `authBasePath` | `"/api/auth"` | Better Auth routes on this origin |
+| `adminApiBasePath` | `"/admin"` | Admin API base path on this origin |
+
+## Serving and caching
+
+**Production (no `devProxyTarget`):**
+
+1. `${basePath}/_expo` and `${basePath}/assets` — `express.static` with `maxAge: 365d`, `immutable: true`.
+2. `${basePath}/app-config.json` — `Cache-Control: no-store`.
+3. `${basePath}` and `${basePath}/*splat` — SPA fallback returns rewritten `index.html` with `Cache-Control: no-store`.
+
+`index.html` is read once at startup; asset paths are rewritten to `${basePath}/...` and `window.__ADMIN_SPA_BASE__` is injected for deep-link config fetches.
+
+**Development (`devProxyTarget` set):**
+
+- `${basePath}/app-config.json` served locally (no cache).
+- All other `${basePath}/*` requests proxied to the Expo dev server (WebSocket enabled).
+
+If no bundle exists at `distDir/index.html`, the plugin logs a warning suggesting `bun run --filter '@terreno/admin-spa' build:web` or `devProxyTarget`.
+
+## Mount path constraint
+
+The default web export is built with `experiments.baseUrl: "/console"`, so `basePath` must match. To mount elsewhere, rebuild with a matching base (e.g. `EXPO_BASE_URL=/admin-ui bun run build:web`) and set `basePath` accordingly. Mounting at `/` requires a root-base build and `basePath: "/"`.
+
+## Standalone SPA vs embedded admin-frontend
+
+Use **`@terreno/admin-spa`** when you want a complete admin UI served from the API process (same-origin Better Auth cookies, no separate static deploy). The backend image stays lean until you opt in by registering `AdminSpaServeApp`.
+
+Use **`@terreno/admin-frontend`** when admin screens live inside your main Expo app (e.g. `example-frontend/app/admin/*`). You bring your own routing, auth, and deploy; the package supplies reusable list/table/form components and hooks against `/admin` CRUD routes from `@terreno/admin-backend`.