@terreno/mcp 0.31.0 → 56.0.0-beta.0

package/src/docs/versioned/next/implementationPlans/orgs-and-teams.md

@@ -1,158 +0,0 @@
-# Implementation Plan: Organizations, teams, and multi-tenant scoping
-
-**Status:** Draft
-**Roadmap issue:** https://github.com/FlourishHealth/terreno/issues/1024
-**Priority:** High
-**Effort:** Big batch
-**Owner:** unassigned
-**Created:** 2026-08-09
-**Program:** [B2B platform](b2b-platform-program.md)
-**Depends on:** none (soft: [rbac-permissions](rbac-permissions.md) for role vocabulary; this IP ships coarse org roles that RBAC later subsumes)
-**RTK deprecation flag:** None — backend only; frontend surfaces are `org-management-ui`
-
-## Goal
-
-Terreno's entire access story is per-user: `ownerId` fields, `OwnerQueryFilter`,
-`Permissions.IsOwner`. A B2B app needs data owned by an **organization** and accessed by
-its **members**. This IP adds the tenant analog of the owner stack to `@terreno/api`:
-Organization and Membership models, an org-context middleware, an `orgScopedPlugin` for
-schemas, `OrgQueryFilter` and `Permissions.IsOrgMember`/`IsOrgAdmin` for modelRouter, and
-CRUD routes for orgs and memberships — so `modelRouter(Todo, {queryFilter: OrgQueryFilter,
-permissions: {...IsOrgMember}})` is all an app needs for tenant-safe endpoints.
-
-## Non-Goals
-
-- Invitations, seat counting (`invitations-and-seats` item).
-- Fine-grained RBAC (roles beyond `member`/`admin` — [rbac-permissions](rbac-permissions.md)).
-- Org switcher and management screens (`org-management-ui` item).
-- Billing linkage (`billing-stripe` maps customers to orgs later).
-- Cross-org data sharing, nested teams/sub-orgs (future work).
-
-## Decisions
-
-| Question | Decision |
-|----------|----------|
-| **D6 (resolved 2026-08-09):** native Mongoose models vs Better Auth `organization` plugin | **Native models.** The JWT/passport path (still supported and the example default) cannot use a Better-Auth-only construct; native models serve both auth paths, keep modelRouter/query-filter integration first-class, and can sync to Better Auth's plugin later if wanted |
-| Org context transport | `X-Organization-Id` header, resolved by middleware into `req.organization` + `req.membership`; explicit query/body override rejected |
-| One org or many per user? | Many (Membership join collection); apps wanting single-org enforce via option `maxOrgsPerUser: 1` |
-| Coarse roles now | `Membership.role: "admin" \| "member"` — deliberately minimal; RBAC IP replaces this enum with role references, migration documented there |
-| Scoping mechanism | `orgScopedPlugin` adds required indexed `organizationId`; `OrgQueryFilter` filters lists by active memberships; `preCreate` helper injects the context org |
-| Personal orgs? | No auto-created personal org; apps opt in via `createDefaultOrgOnSignup` option |
-
-## Architecture
-
-```
-api/src/orgs/
-  organizationModel.ts   # Organization + Membership schemas/models
-  orgContext.ts          # middleware: header → req.organization/req.membership
-  orgPlugin.ts           # orgScopedPlugin(schema) — organizationId field + index
-  orgPermissions.ts      # IsOrgMember, IsOrgAdmin, OrgQueryFilter
-  orgsApp.ts             # OrgsApp TerrenoPlugin — routes + options
-```
-
-`OrgsApp` options:
-
-```typescript
-new OrgsApp({
-  maxOrgsPerUser?: number;
-  createDefaultOrgOnSignup?: boolean;
-  onOrgCreated?: (org, owner) => Promise<void>;
-})
-```
-
-Request flow: `authenticateMiddleware` → `orgContextMiddleware` (loads org by header,
-verifies an active membership for `req.user`, 403 otherwise) → route. Routes that take
-`Permissions.IsOrgMember`/`IsOrgAdmin` require the context; `OrgQueryFilter` works with or
-without a context (no header → all orgs the user belongs to; header → that org only).
-
-## Models
-
-Both use the five-type pattern, `description` on every field, `createdUpdatedPlugin` +
-`isDeletedPlugin`, `strict: "throw"`.
-
-**Organization** — `name` (string, required), `slug` (string, unique, indexed, generated),
-`ownerId` (ref User, required — the creating user; ownership transferable), `settings`
-(Mixed, app-defined), `disabled` (boolean).
-
-**Membership** — `organizationId` (ref Organization, required, indexed), `userId` (ref
-User, required, indexed), `role` ("admin" | "member", default "member"), `status`
-("active" | "suspended", default "active"), compound unique index on
-`(organizationId, userId)`. Statics: `findActiveForUser`, `isMember`, `isOrgAdmin`.
-
-## APIs
-
-| Method | Path | Permissions | Notes |
-|---|---|---|---|
-| POST | `/orgs` | IsAuthenticated | Creates org + admin membership for creator; respects `maxOrgsPerUser` |
-| GET | `/orgs` | IsAuthenticated | Lists orgs the user belongs to (membership join) |
-| GET | `/orgs/:id` | IsOrgMember | |
-| PATCH | `/orgs/:id` | IsOrgAdmin | name/settings; ownership transfer admin-only |
-| DELETE | `/orgs/:id` | IsOrgAdmin | Soft delete; memberships cascade to suspended |
-| GET | `/orgs/:id/members` | IsOrgMember | Paginated membership list (populated user name/email) |
-| PATCH | `/orgs/:id/members/:memberId` | IsOrgAdmin | Role/status change; cannot demote last admin |
-| DELETE | `/orgs/:id/members/:memberId` | IsOrgAdmin | Remove member; cannot remove last admin |
-
-Member creation is **not** exposed here — members arrive via `invitations-and-seats`
-(or `createDefaultOrgOnSignup`). All routes via modelRouter where shapes fit, custom
-`createOpenApiBuilder` routes for member management.
-
-## Notifications
-
-None in this IP (invitation emails belong to `invitations-and-seats`).
-
-## UI
-
-None in this IP (`org-management-ui`). example-backend gains an org-scoped demo model
-(`Project`) exercising `orgScopedPlugin` + `OrgQueryFilter` end to end.
-
-## Phases
-
-1. **Models + plugin:** Organization, Membership, `orgScopedPlugin`, statics, unit tests.
-2. **Context + permissions:** middleware, `IsOrgMember`/`IsOrgAdmin`, `OrgQueryFilter`,
-   modelRouter integration tests (member of A cannot read B's rows — the critical suite).
-3. **Routes + app:** `OrgsApp`, org/member routes, last-admin guards, OpenAPI, supertest.
-4. **Example + docs:** example-backend `Project` model + routes, seeds, admin panel model
-   registration, `docs/how-to/add-organizations.md`, reference docs, SDK regen.
-
-## Feature Flags & Migrations
-
-No migration for existing apps (new collections; opt-in plugin). Adopting apps that
-backfill `organizationId` onto existing collections get a documented backfill recipe —
-formal tooling arrives with `mongo-migrations`.
-
-## Activity Log & User Updates
-
-Org create/delete and membership role changes fire an `onOrgAudit` hook (mirroring
-`onAdminAudit`) so apps can log them; framework-wide audit persistence is the
-`framework-audit-log` item.
-
-## Not Included / Future Work
-
-- Teams within orgs (the Membership schema reserves a `teamIds` extension point but ships
-  without it — YAGNI until a consumer needs it).
-- Org-level settings UI, domain capture/auto-join (SSO IP touches this).
-- Per-org rate limits, quotas.
-
-## Files to Create / Modify
-
-- `api/src/orgs/*` (new), `api/src/index.ts` exports
-- `api/src/permissions.ts` — export org permissions alongside existing ones
-- `example-backend/src/models/project.ts`, `api/projects.ts`, seeds, `server.ts`
-- `docs/how-to/add-organizations.md`, `docs/reference/api.md`
-- `example-frontend` SDK regen (`bun run sdk`) after backend routes land
-
-## Task List
-
-See [docs/tasks/orgs-and-teams.md](../tasks/orgs-and-teams.md).
-
-## Acceptance Criteria
-
-- [ ] A user can create an org, becoming its admin member; `maxOrgsPerUser` is enforced.
-- [ ] With two orgs seeded, a member of org A listing an org-scoped model with
-      `OrgQueryFilter` never receives org B documents — including via crafted `$or` /
-      query-param attempts.
-- [ ] Requests with an `X-Organization-Id` the user is not an active member of get 403.
-- [ ] The last admin of an org cannot be demoted or removed.
-- [ ] Org routes appear in `/openapi.json`; regenerated SDK compiles; admin panel can
-      browse Organizations and Memberships.
-- [ ] Soft-deleting an org suspends its memberships and hides its scoped data from lists.

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

@@ -1,147 +0,0 @@
-# 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/reference/admin-spa.md

@@ -1,130 +0,0 @@
-# @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`.