@terreno/mcp 57.20.0 → 57.21.0

package/src/docs/versioned/57.20.0/implementationPlans/fix-better-auth-sessions-and-config.md

@@ -0,0 +1,80 @@
+# Fix Better Auth: disabled users, socket sessions, and config passthrough
+
+Three Better Auth gaps that apps migrating from JWT hit right away. Disabling an account
+does not lock out its live Better Auth sessions on REST or sockets. Sockets only accept
+Better Auth sessions when each app wires the instance in by hand, and they refuse a user
+who has not made an HTTP request yet. `BetterAuthConfig` cannot pass any Better Auth
+option or plugin Terreno does not set itself.
+
+Selected: "the better-auth issues from the last day", resolved 2026-10-18T10:52:18Z
+(window 2026-10-17T10:52:18Z to 2026-10-18T10:52:18Z), GitHub TerrenoLabs/terreno.
+
+## Issues
+
+| Issue | Title | Disposition | Root cause | Task |
+| --- | --- | --- | --- | --- |
+| #1577 | Better Auth session middleware does not reject disabled users | fix | `api/src/betterAuthSetup.ts:410` sets `req.user` without checking `disabled` | T1 |
+| #1576 | Better Auth: wire RealtimeApp automatically and lazily sync users at socket handshake | fix | `api/src/realtime/socketAuth.ts:161` refuses unsynced users and skips `disabled`; `api/src/realtime/realtimeApp.ts:398` reads only `config.betterAuth` | T2, T3 |
+| #1578 | BetterAuthConfig: pass through Better Auth options and plugins | fix | `api/src/betterAuthSetup.ts:189` builds options only from fixed fields; `plugins: [bearer()]` is hard-coded | T4 |
+
+## Tasks
+
+- [x] **T1** — Reject disabled users' Better Auth sessions on REST (#1577)
+  - Depends on: none
+  - Files: api/src/betterAuthSetup.ts, api/src/betterAuthSetup.test.ts, docs/explanation/authentication.md, docs/how-to/configure-better-auth.md
+  - Root cause: `createBetterAuthSessionMiddleware` assigns the app user without the `disabled` check JWT (`auth.ts:565`) and MCP (`mcp/auth.ts:21`) make.
+  - Fix: add an exported `resolveBetterAuthAppUser({userModel, betterAuthUser})` that finds the user by `betterAuthId`, falls back to `syncBetterAuthUser`, and reports disabled users. The middleware leaves `req.user` unset for a disabled user, as MCP's `rejectIfDisabled` does, so protected routes answer 401 and Better Auth's own routes (sign-out) stay reachable.
+  - Proof: `api/src/betterAuthSetup.test.ts` tests for a disabled user and a user disabled while the session is live fail on the base (`req.user` is set) and pass on the branch.
+  - Closes: #1577
+- [x] **T2** — Sync and check disabled users at the Better Auth socket handshake (#1576)
+  - Depends on: T1
+  - Files: api/src/realtime/socketAuth.ts, api/src/realtime/socketAuth.test.ts
+  - Root cause: the Better Auth socket check looks up the app user by `betterAuthId` and throws when none exists; it never checks `disabled`.
+  - Fix: use `resolveBetterAuthAppUser` from T1, so a fresh user is created at handshake and a disabled one is refused.
+  - Proof: `api/src/realtime/socketAuth.test.ts` tests "creates the app user" and "rejects a disabled user" fail on the base and pass on the branch.
+  - Closes: #1576 (with T3)
+- [x] **T3** — Find the Better Auth instance for RealtimeApp from the registered plugins (#1576)
+  - Depends on: T2
+  - Files: api/src/realtime/realtimeApp.ts, api/src/realtime/types.ts, api/src/realtime/realtimeAppSetup.test.ts, example-backend/src/server.ts, docs/how-to/configure-better-auth.md, docs/how-to/migrate-rtk-to-syncdb.md, docs/reference/syncdb.md, docs/explanation/authentication.md
+  - Root cause: `RealtimeApp` reads only `config.betterAuth` at startup, in the handshake middleware, and in the revalidation sweep, and ignores the `terrenoApp` passed to `register`.
+  - Fix: store `terrenoApp` in `register`; in `onServerCreated`, resolve `config.betterAuth ?? {auth: ensureAuth(), userModel}` from the registered Better Auth plugin and use it in all three places. Explicit `config.betterAuth` still wins.
+  - Proof: `api/src/realtime/realtimeAppSetup.test.ts` tests with `BetterAuthApp` registered and no `betterAuth` option — handshake with a Better Auth bearer authenticates, and the sweep reports `disabled` rather than `invalid-session` — fail on the base and pass on the branch.
+  - Closes: #1576 (with T2)
+- [x] **T4** — Pass Better Auth options and plugins through BetterAuthConfig (#1578)
+  - Depends on: T3
+  - Files: api/src/betterAuth.ts, api/src/betterAuthSetup.ts, api/src/betterAuthSetup.test.ts, api/src/betterAuthApp.test.ts, docs/how-to/configure-better-auth.md
+  - Root cause: `createBetterAuth` builds a fixed options literal and hard-codes `plugins: [bearer()]`.
+  - Fix: add `options?: Omit<Partial<BetterAuthOptions>, "plugins" | "basePath">` and `plugins?: BetterAuthPlugin[]`; deep-merge `options` over Terreno's defaults with arrays replaced, and append `plugins` after `bearer()`.
+  - Proof: `api/src/betterAuthSetup.test.ts` "requireEmailVerification blocks sign-in" and "plugin endpoints mount under the base path" fail on the base and pass on the branch; existing defaults tests stay green.
+  - Closes: #1578
+- [x] **T5** — Resolve a Better Auth user created concurrently on first contact (#1576)
+  - Depends on: T4
+  - Files: api/src/betterAuthSetup.ts, api/src/betterAuthSetup.test.ts
+  - Root cause: found in branch review. The socket handshake (T2) and the first REST calls race to create a new user; the loser's insert hits the unique `_id` index, and the socket reports it as Unauthorized.
+  - Fix: `resolveBetterAuthAppUser` looks the user up again after a duplicate-key error.
+  - Proof: `api/src/betterAuthSetup.test.ts` describe "resolveBetterAuthAppUser" fails on T4's head (8 of 13 runs for the concurrent test, 5 of 5 for the stub test) and passes on the branch.
+  - Closes: #1576 (with T2 and T3)
+
+T2 depends on T1 for the helper. T3 and T4 depend on the previous task only because they edit the same docs page.
+
+## Assumptions
+
+- A disabled user's session falls through as anonymous instead of answering 401 directly, because `TerrenoApp` mounts the session middleware before Better Auth's routes and a direct 401 blocked sign-out (Roast T1 attempt 1).
+- Auto-wiring has no opt-out: it only adds one more accepted credential, after the JWT check.
+- `options` overrides win, including over the adapter and security defaults, as #1578 says; docs list what an override drops.
+- Plugin endpoints added through `plugins` are not typed on `auth.api`; docs say so.
+
+## Open questions (recommendation assumed)
+
+None.
+
+## Not fixed in this run
+
+| Issue | Disposition | Next action |
+| --- | --- | --- |
+| #1579 | decide | New rtk public API with four design choices (token-source shape, #1217 composition, web storage, bearer default), about three PRs. Run `/brewery:distill #1579`. |
+| #1574 | skipped | Open PR #1581 already covers it. |
+
+## Sign-off
+
+Status: approved 2026-10-18 (tap: #1576, #1577, #1578)

package/src/docs/versioned/57.20.0/implementationPlans/framework-audit-log.md

@@ -0,0 +1,247 @@
+# Implementation Plan: Framework-level audit log
+
+**Status:** Complete — shipped in #1301  
+**Branch:** `cursor/framework-audit-log-grow-0d6c`  
+**Owner:** —  
+**Created:** 2026-09-10  
+**Roadmap issue:** https://github.com/TerrenoLabs/terreno/issues/1186 (implementation PRs use `Fixes #1186`)  
+**Task list:** [framework-audit-log.md](../tasks/framework-audit-log.md)  
+**Program:** [B2B platform](b2b-platform-program.md)  
+**Depends on:** — (soft: `organizationId` now; org-admin list filter waits on [org-management-ui](org-management-ui.md))  
+**RTK deprecation flag:** None — admin viewer uses generated OpenAPI / `useAdminApi`, not syncdb  
+
+## Goal
+
+Opt-in `AuditApp` in `@terreno/api` persists append-only `AuditEvent` rows for successful mutations: who changed which record, with changed-field before/after diffs. The existing admin Platform **Audit Log** lists them. Default retention is forever. This is the B2B compliance log; it generalizes example `AdminAuditLog` without replacing consent `ConsentResponse` rows.
+
+## Non-Goals
+
+- Waiting on `org-management-ui` to start (no `OrgsApp` in tree today).
+- Default-on `modelRouter` product CRUD.
+- Consent signing history (`ConsentResponse` + `GET /consents/audit/:userId` stay).
+- Login, failed auth, permission denials (except existing `RbacAudit` `denied: true` fanned through `auditSink`).
+- Sync mutate / outbox / socket writes (`@terreno/syncdb`). HTTP `modelRouter` only.
+- Admin hard-delete of events; SIEM export; legal hold.
+- Full-document snapshots.
+- Per-org-admin filtered lists (store `organizationId` now; filter when org context ships).
+
+## Decisions
+
+| ID | Question | Choice |
+| --- | --- | --- |
+| Q1 | Org dependency | Ship now. Optional `organizationId` from the mutated document or `req.organization` when present. |
+| Q2 | Default on | Off. `AuditApp` plugin + per-router `audit: true`. **AdminApp writes `AuditEvent` automatically when `AuditApp` is registered.** |
+| Q3 | Events | Successful create/update/delete and array mutations on audited routers; AdminApp → same collection; RBAC via existing `auditSink`; consent stays domain-specific. |
+| Q4 | Mutability / retention | HTTP list+read only. Create only via framework writers. No PATCH/DELETE. **Default retain forever.** Optional `retentionDays > 0` Mongo TTL. |
+| Q5 | Diffs | Changed fields only. Auto-redact `password`, `hash`, `salt`, `token`, `secret`, `refreshToken` (case-insensitive last path segment) plus per-router `redact`. Never log full request bodies. |
+
+**Recorded assumptions (not grilled):** No default-connection singleton (same as `RbacAudit`: `createAuditEventModel(connection)`). Example-backend **replaces** `AdminAuditLog` with `AuditEvent`. `onAdminAudit` remains an extra sink. Writes are best-effort (`logger.error`, mutation still succeeds). Persist is fire-and-forget on the request path. Optional Cloud Tasks enqueue (`GCP_TASKS_AUDIT_QUEUE` + `AUDIT_TASKS_URL`) writes Mongo on a worker via `POST /internal/audit-events`. `AuditEvent` is never audited. `audit: true` without `AuditApp` skips the write and logs an error once per process. Array mutations use `verb: "updated"` and `operation` `arrayPush` / `arrayUpdate` / `arrayRemove`. `organizationId` is stored as string. Admin list uses `Permissions.IsAdmin` until org RBAC lands.
+
+## Architecture
+
+```
+AuditApp({retentionDays?})
+  → createAuditEventModel(connection)
+  → set process recorder
+  → modelRouter("/audit-events", AuditEvent, {create/update/delete: [], list/read: IsAdmin})
+  → adminContribution() for Platform Audit Log
+
+modelRouter(..., {audit: true | {redact?: string[]}})
+  → after successful create/update/delete/array *
+  → recordAuditEvent({actorId, modelName, recordId, recordLabel?, organizationId?, verb, operation, before, after, source: "modelRouter"})
+
+AdminApp
+  → after successful admin CRUD, if recorder present
+  → recordAuditEvent({..., source: "admin"})
+  → then onAdminAudit? (unchanged extra sink)
+
+createAccess({auditSink: persistRbacAuditToAuditEvent})
+  → source: "rbac"; before/after from permissionDelta when present
+```
+
+`AuditApp` implements `TerrenoPlugin` (+ `adminContribution` like FeatureFlags). Importing `@terreno/api` does **not** register `AuditEvent` on `mongoose.connection`.
+
+### Config shape
+
+```typescript
+interface AuditAppOptions {
+  enqueue?: (write: AuditEventWrite) => Promise<void>;
+  processQueuePath?: string;
+  processQueueSecret?: string;
+  /** Mongo TTL in days. Omit or 0 = forever (no TTL index). */
+  retentionDays?: number;
+}
+
+interface ModelRouterAuditOptions {
+  redact?: string[]; // extra field names; merged with defaults
+}
+
+// modelRouter options:
+audit?: boolean | ModelRouterAuditOptions;
+```
+
+`audit: true` equals `{redact: []}`.
+
+### Writer contract
+
+```typescript
+interface AuditEventWrite {
+  actorId?: string;
+  after?: Record<string, unknown>;
+  before?: Record<string, unknown>;
+  modelName: string;
+  operation: "create" | "update" | "delete" | "arrayPush" | "arrayUpdate" | "arrayRemove";
+  organizationId?: string;
+  recordId?: string;
+  recordLabel?: string;
+  source: "admin" | "modelRouter" | "rbac";
+  verb: "created" | "deleted" | "updated";
+}
+```
+
+Diff helper: shallow (plus one-level nested objects) comparison of previous JSON vs next JSON after redaction. Unchanged keys omitted. Create: `before` omitted, `after` is redacted new fields. Delete: `after` omitted, `before` is redacted last state.
+
+`organizationId` resolution order: `req.organization?.id` / `_id`, else string of `doc.organizationId` when present.
+
+## Models
+
+`AuditEvent` (collection `auditevents`):
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `actorId` | ObjectId, ref User, indexed | Optional (system / missing user) |
+| `modelName` | string, required, indexed | |
+| `recordId` | string, indexed | |
+| `recordLabel` | string | Short label (admin list fields / `title` / `name` / `email`) |
+| `organizationId` | string, indexed | Optional |
+| `verb` | `created` \| `updated` \| `deleted`, indexed | Widget-compatible |
+| `operation` | string, required | Fine-grained verb |
+| `source` | `admin` \| `modelRouter` \| `rbac`, indexed | |
+| `before` / `after` | Mixed | Changed fields only, redacted |
+| `created` / `updated` | dates | `createdUpdatedPlugin`; no `isDeletedPlugin` (append-only) |
+
+Indexes: `{created: -1}`, `{modelName: 1, recordId: 1, created: -1}`. Optional TTL on `created` when `retentionDays > 0`. Every field has `description`. Five-type pattern co-located with the schema. `strict: "throw"`.
+
+HTTP: `create`/`update`/`delete` empty permission arrays. No public POST/PATCH/DELETE even for admins. Denied list/create (including non-admin GET list) returns **405**, matching `permissionMiddleware`; instance-level denials after a loaded document remain **403**.
+
+## APIs
+
+| Method | Path | Who | Behavior |
+| --- | --- | --- | --- |
+| GET | `/audit-events` | IsAdmin | Paginated list, default sort `-created`, `queryFields`: `modelName`, `recordId`, `actorId`, `verb`, `source`, `organizationId` |
+| GET | `/audit-events/:id` | IsAdmin | Read one |
+| POST/PATCH/DELETE | `/audit-events` | — | Disabled |
+
+Admin mounts the same model via `adminContribution` (or example registers it once — do **not** double-mount). Route path includes `audit-log` **or** model name `AuditEvent` so `AdminShell.isAuditLogModel` lifts it into Platform.
+
+RBAC helper `persistRbacAuditToAuditEvent(model)` returns an `RbacAuditSink`. Built-in `RbacAudit` collection unchanged.
+
+## Notifications
+
+None.
+
+## UI
+
+Reuse Platform Audit Log + `RecentActivityWidget`. Update `isAuditLogModel` to match `AuditEvent` (keep `AdminAuditLog` and `audit-log` path for leftover apps). List columns: `created`, `verb`, `modelName`, `recordLabel`, `actorId`. Detail form is read-only; show `before`/`after` as JSON (existing object field rendering is enough). No new custom screen.
+
+example-backend: register `AuditApp`, enable `audit: true` on `Todo`, drop `AdminAuditLog` model and `onAdminAudit` persistence (optional `onAdminAudit` may remain no-op or be removed). Point home `recentActivity` at `AuditEvent`. RBAC `auditSink` uses the helper. Scripts that count/wipe `AdminAuditLog` switch to `AuditEvent` (wipe only in test/dev scripts — production HTTP still cannot delete).
+
+## Docs in this slice
+
+| Page | Change |
+| --- | --- |
+| `docs/how-to/audit-log.md` | **New.** Enable `AuditApp`, per-router `audit`, AdminApp auto-write, redaction, TTL, append-only, org field. |
+| `docs/reference/api.md` | `AuditApp`, `audit` option, `persistRbacAuditToAuditEvent`, no default-connection model. |
+| `docs/explanation/admin-interface.md` | Platform Audit Log is `AuditEvent` when `AuditApp` is registered. |
+| `docs/reference/admin-backend.md` | `onAdminAudit` is extra; framework write when `AuditApp` present. |
+| `docs/explanation/roadmap-seed-issues.md` | IP + task URLs; soft org depend. |
+| `docs/implementationPlans/b2b-platform-program.md` | Row for this IP. |
+| `.rulesync/rules/api/00-api.mdc` | AuditApp + `audit` option. |
+| `CHANGELOG.md` | Added opt-in framework audit log. |
+
+## Testing
+
+Tracer: `TerrenoApp` + `AuditApp` + test model with `audit: true` → authenticated PATCH changes `title` → `GET /audit-events` as admin returns one row with `verb: "updated"`, `before.title` / `after.title`, no `password` if present.
+
+Cases:
+
+- Plugin omitted: `audit: true` does not throw on CRUD; no collection on default connection; error logged once.
+- Create/update/delete each write one event; actorId matches `req.user`.
+- Unchanged fields absent from `before`/`after`.
+- Default redact list strips secrets even if not in `redact`.
+- Per-router `redact: ["ssn"]` strips `ssn`.
+- Array push writes `operation: "arrayPush"`, `verb: "updated"`.
+- Admin POST writes `source: "admin"` without `onAdminAudit`.
+- `onAdminAudit` still fires when both configured; mutation 201 if either sink throws.
+- AuditEvent HTTP POST is 404/not registered; PATCH/DELETE disabled.
+- `organizationId` copied from document; from `req.organization` when set.
+- `retentionDays` omitted: no TTL index. `retentionDays: 1`: TTL index present (assert index spec; do not sleep a day).
+- Example RBAC role change fans into `AuditEvent` with `source: "rbac"`.
+- Existing `onAdminAudit` tests stay green (best-effort extra sink).
+- Admin frontend: `isAuditLogModel` true for `AuditEvent`; Recent Activity still skips when no audit model.
+
+Skills: `terreno-backend-api`, `mongoose-schema-safety`, `backend-test-env` (if tests touch env), `building-admin-interfaces`, `verify-ui-changes` (example `/admin` audit log after Todo/admin mutation), `update-docs`, `generate-sdk` if example OpenAPI admin SDK lists the new route.
+
+## Risks
+
+| Risk | Mitigation |
+| --- | --- |
+| Write volume / PII | Opt-in per router; redaction; append-only HTTP. |
+| Missing plugin | No-op + once-per-process error; docs. |
+| Example `AdminAuditLog` break | Replace in the same slice; shell still matches old name. |
+| TTL index change later | How-to: drop old TTL index when changing `retentionDays`. |
+| Sync bypass | Documented non-goal; follow-up IP. |
+| Org filter incomplete | Field stored; list filter is `org-management-ui`. |
+
+## Phases
+
+1. Tracer: model + `AuditApp` + `audit: true` create/update/delete + list/read API + redaction.
+2. Array mutations + `organizationId`.
+3. AdminApp auto-write + example migration + shell matcher + RBAC helper.
+4. Optional TTL.
+5. Docs, changelog, rulesync, seed, B2B table.
+
+## Feature Flags & Migrations
+
+No feature flag. New collection. example-backend drops `AdminAuditLog` (example-only; no published schema). Apps that copied `AdminAuditLog` keep it until they register `AuditApp`.
+
+## Activity Log & User Updates
+
+This IP **is** the activity log. No `UserUpdate` spam.
+
+## Not Included / Future Work
+
+- Org-admin scoped list (`org-management-ui`).
+- Sync-path audit.
+- Auth / login events.
+- SIEM export, legal hold, immutable object storage.
+- Custom diff UI beyond JSON fields.
+
+## Files to Create / Modify
+
+| File | Role |
+| --- | --- |
+| `api/src/audit/*` | Model, recorder, diff/redact, `AuditApp`, tests |
+| `api/src/api.ts` | `audit` option + post hooks |
+| `api/src/index.ts` | Exports |
+| `admin-backend/src/adminApp.ts` | Auto-write when recorder present |
+| `admin-frontend/src/AdminShell.tsx`, `AdminHome.tsx` | `isAuditLogModel` |
+| `example-backend/src/server.ts`, `access.ts`, models, scripts | `AuditApp`; drop `AdminAuditLog` |
+| Docs listed above | Same slice |
+
+## Task List
+
+[docs/tasks/framework-audit-log.md](../tasks/framework-audit-log.md)
+
+## Acceptance Criteria
+
+- [ ] `AuditApp` omitted: no `AuditEvent` on the default connection; product CRUD unchanged.
+- [ ] `audit: true` + `AuditApp`: create/update/delete persist one event with actor, model, record, changed-field diff, redacted secrets.
+- [ ] HTTP `/audit-events` is list+read for admin only; create/update/delete disabled.
+- [ ] Admin mutations write `AuditEvent` when the plugin is registered, without requiring `onAdminAudit`.
+- [ ] `onAdminAudit` still runs as an extra best-effort sink.
+- [ ] example-backend Platform Audit Log and Recent Activity read `AuditEvent`; `AdminAuditLog` removed.
+- [ ] RBAC `auditSink` helper writes `source: "rbac"` without dropping `RbacAudit`.
+- [ ] Default: no TTL. `retentionDays > 0` adds TTL on `created`.
+- [ ] How-to + api reference + admin explanation match the shipped design.
+- [ ] Merging the implementation PR closes https://github.com/TerrenoLabs/terreno/issues/1186 (`Fixes #1186`).

package/src/docs/versioned/57.20.0/implementationPlans/gpt-chat-mascot.md

@@ -0,0 +1,41 @@
+# GPTChat optional mascot
+
+**Status:** Complete  
+**Roadmap:** Area=`ui`, Target=`Released`, Impact=`Feature`  
+**Branch:** `cursor/gpt-chat-mascot-d39f`  
+**Owner:** cloud agent  
+**Created:** 2026-09-15
+
+## Goal
+
+Let consuming apps brand the GPT screen with their own mascot. Terreno does not ship a default character.
+
+## Non-Goals
+
+- Bundling artwork, Lottie files, or a Terreno fox in `@terreno/ui`
+- Animating the mascot from `isStreaming` inside GPTChat (consumers wrap their own node)
+- Showing the mascot beside assistant bubbles
+
+## Decisions
+
+| Question | Decision |
+|----------|----------|
+| Who owns the asset? | Consumer. `mascot?: React.ReactNode` |
+| When is it visible? | Only while `currentMessages.length === 0` |
+| Default? | Omitted — existing empty chat unchanged |
+
+## UI
+
+`GPTChat` empty-state hero: optional mascot slot, then existing suggested prompts.
+
+## Task List
+
+[docs/tasks/gpt-chat-mascot.md](../tasks/gpt-chat-mascot.md)
+
+## Acceptance Criteria
+
+- [ ] Omitting `mascot` leaves the empty chat unchanged
+- [ ] Passing `mascot` shows it on an empty chat, including with suggested prompts
+- [ ] Messages hide the mascot
+- [ ] Demo story and example app show a consumer node
+- [ ] Docs describe the optional slot