@terreno/mcp 57.16.1 → 57.17.0

package/src/docs/versioned/next/how-to/deploy-backend-to-cloud-run.md

@@ -56,7 +56,7 @@ echo -n 'mongodb+srv://user:pass@cluster.example/terreno?retryWrites=true&w=majo
 
 Repeat for `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, and `SESSION_SECRET`.
 
-For Better Auth, also create `better-auth-secret` and set `AUTH_PROVIDER=better-auth` plus `BETTER_AUTH_URL` at deploy time. See [Configure Better Auth](configure-better-auth.md).
+For Better Auth, also create `better-auth-secret` and set `AUTH_PROVIDER=better-auth` plus `BETTER_AUTH_URL` at deploy time. See [Configure Better Auth](configure-better-auth.md). The example backend uses Better Auth when `AUTH_PROVIDER` is unset, and with `NODE_ENV=production` it refuses to start unless `BETTER_AUTH_SECRET` is set to a value other than its published development secret.
 
 ## 4. Runtime service account
 

package/src/docs/versioned/next/how-to/enable-mcp-oauth.md

@@ -0,0 +1,134 @@
+# Enable MCP OAuth for a JWT app
+
+Let Claude.ai custom connectors, ChatGPT apps, and other remote MCP clients connect to your app's `POST /mcp` through OAuth 2.1, when your app signs users in with Terreno JWTs. Terreno runs the authorization server; your app hosts one consent screen.
+
+Use [a service token](connect-mcp-service-token.md) instead for clients that take a static Bearer key (Perplexity, Cursor, Claude Code).
+
+## Prerequisites
+
+- A `TerrenoApp` backend with at least one MCP tool ([Expose MCP tools](expose-mcp-tools.md))
+- A public https origin for the API, for example `https://api.example.com`
+- A signed-in page in your app that can call the API with the user's JWT
+
+## 1. Turn on `mcpOAuth`
+
+MCP OAuth is off until you set `enabled: true`. Without it the app has no `/oauth/*` routes, no `.well-known/oauth-*` documents, and no OAuth challenge on `/mcp`.
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  mcpOAuth: {
+    consentUrl: "https://app.example.com/oauth/consent",
+    enabled: true,
+    issuer: "https://api.example.com",
+  },
+});
+```
+
+- `issuer` is the API's public origin, with no path. Every discovery URL and endpoint is built from it, so it must be the origin clients reach.
+- `consentUrl` is the page from step 2.
+
+### Choose how clients get a `client_id`
+
+Dynamic client registration (`POST /oauth/register`) is a separate opt-in and stays off by default. The endpoint is unauthenticated: anyone who can reach your API can create a client with any name and a redirect on an allowed host. The consent screen is then the only thing between that client and a user's grant, so a convincing name is enough to phish an approval.
+
+- **Registration off (default).** Create each client yourself and give its `client_id` to the client (Claude.ai custom connectors accept one under advanced settings). `/oauth/register` returns 404 and the metadata has no `registration_endpoint`.
+
+  ```typescript
+  import {McpOAuthClient} from "@terreno/api";
+
+  await McpOAuthClient.create({
+    clientId: "claude-connector",
+    clientName: "Claude",
+    grantTypes: ["authorization_code", "refresh_token"],
+    redirectUris: ["https://claude.ai/api/mcp/auth_callback"],
+    responseTypes: ["code"],
+  });
+  ```
+
+- **Registration on.** Turn it on only when clients you cannot pre-register must connect. Set `dynamicClientRegistration: true` and list `allowedRedirectHosts`, which limits where a registered client may send codes. Claude.ai redirects to `claude.ai`, ChatGPT to `chatgpt.com`. Use `*.example.com` for subdomains, and add `localhost` only if you want local clients with loopback `http://` redirects. Keep rate limiting on.
+
+  ```typescript
+  mcpOAuth: {
+    allowedRedirectHosts: ["claude.ai", "chatgpt.com"],
+    consentUrl: "https://app.example.com/oauth/consent",
+    dynamicClientRegistration: true,
+    enabled: true,
+    issuer: "https://api.example.com",
+  },
+  ```
+
+Booting with an issuer that has a path, a consent URL that is not a URL, or registration on with no redirect hosts throws. Full option list: [API reference → MCP OAuth](../reference/api.md#mcp-oauth).
+
+## 2. Host the consent screen
+
+The client sends the user's browser to `/oauth/authorize`. Terreno checks the client, redirect URI, and PKCE, stores a pending request, and redirects to `consentUrl?request=<id>`. Your page:
+
+1. Makes sure the user is signed in (send them through login and back if not, keeping `request`).
+2. Loads the request to show who is asking:
+
+   ```http
+   GET /oauth/authorize/<request>
+   Authorization: Bearer <user JWT>
+   ```
+
+   Response: `{data: {clientName, redirectHost, scope, expiresAt, …}}`. Show the client name and redirect host so the user can spot a client they did not start.
+
+3. Posts the decision with the same JWT, then sends the browser to the returned URL:
+
+   ```http
+   POST /oauth/authorize/<request>/approve   # or /deny
+   Authorization: Bearer <user JWT>
+   ```
+
+   ```typescript
+   const {data} = await approve(requestId);
+   window.location.assign(data.redirectUrl);
+   ```
+
+The three endpoints are in OpenAPI (`getMcpOAuthRequest`, `approveMcpOAuthRequest`, `denyMcpOAuthRequest`), so `bun run sdk` generates hooks for them. A request expires after 10 minutes (400 `Authorization request expired`), and a decided request cannot be decided again (409). The endpoints refuse `mcp_` and OAuth bearers, so an agent cannot approve itself.
+
+## 3. Connect a client
+
+Give the client the MCP URL, `https://api.example.com/mcp`. It discovers the rest:
+
+1. `POST /mcp` without credentials returns `401` with `WWW-Authenticate: Bearer resource_metadata="https://api.example.com/.well-known/oauth-protected-resource/mcp"`.
+2. The client reads that document, then `/.well-known/oauth-authorization-server`.
+3. It uses the `client_id` you gave it, or registers itself at `/oauth/register` when `dynamicClientRegistration` is on, then runs the browser flow through your consent screen, and exchanges the code at `/oauth/token` for an access token (`mcpat_…`, one hour) and a refresh token (`mcprt_…`, 30 days).
+
+For Claude.ai: **Settings → Connectors → Add custom connector**, paste the MCP URL, and connect. For ChatGPT: create a connector with the MCP URL and choose OAuth.
+
+## 4. Check it
+
+```bash
+curl -i -X POST https://api.example.com/mcp \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+# HTTP/1.1 401 … WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource/mcp"
+
+curl https://api.example.com/.well-known/oauth-authorization-server
+```
+
+## What changes on `/mcp`
+
+- Every request that cannot be authenticated, including `initialize` and `tools/list`, gets the 401 challenge. A rejected credential adds `error="invalid_token"` so clients refresh.
+- JWTs, Better Auth sessions, and `mcp_` service tokens keep working.
+- Tools see the approving user. `getCurrentRequestContext()?.credential` is `"oauth"`, so permission code can treat an agent's token differently from the user's own session (for example, no admin bypass). See [Request credential](../reference/api.md#request-credential).
+- Scopes are not enforced for you. A token can call every tool its user can, whatever scope it was granted. If `scopesSupported` lists scopes with different meanings (for example `["read", "write"]`), add `requireOAuthScope("write")` to the permissions of the methods and actions that need it. The granted scopes are in `getCurrentRequestContext()?.oauthScopes`.
+
+## Revoking access
+
+- The client revokes with `POST /oauth/revoke`. Revoking a refresh token ends the whole chain.
+- Disabling the user stops their tokens at the next call.
+- A password reset, Better Auth password change, or session revocation (anything that bumps `tokenEpoch`) ends every grant approved before it: the next `/mcp` call, refresh, or code exchange fails and the chain is revoked. The user reconnects the client.
+- Server-side, revoke everything a user granted with `McpOAuthToken.updateMany({userId, revokedAt: {$exists: false}}, {$set: {revokedAt: DateTime.now().toJSDate()}})`.
+
+Refresh tokens rotate on every use. If an old refresh token comes back, Terreno assumes it leaked and revokes every token issued from that approval; the user reconnects the client. The revoke is final: Terreno records the revoked approval, so a refresh or code exchange that was already in flight cannot issue a new token for it.
+
+## Security notes
+
+- Only public clients with PKCE `S256` are supported. `plain` PKCE and client secrets are rejected.
+- Tokens, codes, and refresh tokens are stored as SHA-256 hashes.
+- Registration, authorize, token, and revoke count against the `auth` [rate-limit](rate-limiting.md) bucket. Turn rate limiting on in production, since registration is unauthenticated.
+- If a browser-based client (such as the MCP Inspector) runs discovery from another origin, allow that origin in `corsOrigin`.

package/src/docs/versioned/next/how-to/expose-mcp-tools.md

@@ -51,12 +51,15 @@ to work while clients migrate.
 Point any MCP client at `POST /mcp`. Auth order on the Bearer header is:
 
 1. `mcp_…` service token, when `mcpServiceTokens` is enabled
-2. Better Auth session
-3. JWT
+2. `mcpat_…` OAuth access token, when `mcpOAuth` is enabled
+3. Better Auth session
+4. JWT
+
+The credential type that won is recorded as `getCurrentRequestContext()?.credential` (`"mcp-service-token"`, `"oauth"`, `"better-auth-session"`, or `"jwt"`), so a permission function can refuse delegated agent tokens where it would trust the user's own session. Remote clients that need OAuth (Claude.ai connectors, ChatGPT apps) are covered in [Enable MCP OAuth for a JWT app](enable-mcp-oauth.md).
 
 The resolved user is what permission checks run against, so an LLM never sees more than that user could see over REST. Mint and paste a static key with [Connect an MCP client with a service token](connect-mcp-service-token.md).
 
-`initialize` and `tools/list` are the unauthenticated catalog. Identity is enforced on `tools/call`. GET `/mcp` is Streamable HTTP **405** (`Method not allowed.`) — there is no GET SSE stream; Perplexity still uses that 405 as a successful probe.
+`initialize` and `tools/list` are the unauthenticated catalog (unless `mcpOAuth` is enabled, which makes every unauthenticated `/mcp` request a 401 challenge). Identity is enforced on `tools/call`. GET `/mcp` is Streamable HTTP **405** (`Method not allowed.`) — there is no GET SSE stream; Perplexity still uses that 405 as a successful probe.
 
 Authentication is required by default, matching REST. A tool call with no resolvable user is refused before any permission check unless the model router sets `allowAnonymous: true` — the same flag REST passes to `authenticateMiddleware`. That matters for read-only helpers like `IsAuthenticatedOrReadOnly`, which would otherwise pass for an anonymous `list`. Disabled accounts are refused too, as they are over HTTP. Service tokens are MCP-only: they are rejected on `/mcp/service-tokens` and are not accepted on REST, sync, or admin.
 
@@ -116,6 +119,8 @@ populatePaths: [{fields: ["name", "email"], path: "ownerId"}],
 - A bare name (`"hash"`) is removed at **every depth**, including inside arrays and populated refs, so a redacted name cannot leak through a nested document.
 - A dot path (`"metadata.secretKey"`) removes exactly that location, following arrays of subdocuments element-wise.
 
+The list tool's `sort` argument accepts only the router's sortable fields (`queryFields`, fields in the router's `sort`, and `sortFields`) minus `excludeFields`. Sorting on any other field returns an error that lists the allowed fields, because result order would reveal the hidden values.
+
 ## Customizing responses
 
 `mcpResponseHandler` shapes MCP responses independently of the REST `responseHandler`, which is useful for returning compact summaries to an LLM:
@@ -174,9 +179,43 @@ Unexpected exceptions and caught internal causes are also captured with
 receives the stable MCP error text — internal exceptions and stack traces stay
 server-side. Tool arguments are not logged.
 
+## Actions as tools
+
+A verb that is not CRUD belongs in a [modelRouter action](../explanation/model-router-actions.md). Add `mcp` to the action to expose the same implementation as a tool, instead of writing it twice:
+
+```typescript
+export const todoRouter = modelRouter("/todos", Todo, {
+  collectionActions: {
+    bulkComplete: {
+      body: z.object({ids: z.array(z.string()).min(1)}).strict(),
+      handler: async ({body, user}) => completeTodos(body.ids, user),
+      mcp: {description: "Mark several todos complete", name: "todos_bulk_complete"},
+      method: "POST",
+      permissions: [Permissions.IsAuthenticated],
+    },
+  },
+  instanceActions: {
+    markComplete: {
+      handler: async ({doc}) => markComplete(doc),
+      mcp: {name: "todos_mark_complete"},
+      method: "POST",
+      permissions: [Permissions.IsOwner],
+    },
+  },
+  permissions: { /* CRUD */ },
+});
+```
+
+- `todos_mark_complete` takes `{id}`; an instance action's tool input is `{id, ...body}` (or `{id, ...query}` for GET). `todos_bulk_complete` takes `{ids}`.
+- The tool runs the action's own `permissions` and RBAC `access`, before and after loading the document, exactly as REST does. It does not need `mcp` on the router, and the router's CRUD permissions do not apply.
+- The handler sees `req.isMCPRequest === true`. Its return value is the tool's JSON text. Touching `res` fails the call, so return values instead of writing to `res`.
+- `body` / `query` must be a `z.object()`, and instance actions cannot define `id` in it. Tool names must be unique; a duplicate fails at boot.
+
+Audit log lines for action tools carry `mcpTool`, `mcpModel`, and `mcpAction` labels.
+
 ## Custom tools
 
-CRUD tools cover one model at a time. For a query that spans models, register a custom tool with `registerMCPTool`. It shows up on `POST /mcp` and in `getMCPTools` next to the generated CRUD tools:
+CRUD tools cover one model at a time, and actions cover one model's verbs. For a query that spans models, register a custom tool with `registerMCPTool`. It shows up on `POST /mcp` and in `getMCPTools` next to the generated CRUD tools:
 
 ```typescript
 import {registerMCPTool} from "@terreno/api";

package/src/docs/versioned/next/how-to/install-agent-skills.md

@@ -68,7 +68,7 @@ scan stages come from
 | Lifecycle | `terreno-1-grow` … `terreno-5-taste`, `terreno-pick-roast-loop`, `terreno-planning-loop`, `terreno-taste-sweep` |
 | Terreno apps | backend, UI, admin interfaces, data, schema, SDK, prompts, upgrades, deployment |
 | Docs | `update-docs`, `update-agent-docs`, architecture skills |
-| GitHub | issues, review, UI verification, release, dependency updates |
+| GitHub | issues, review, UI verification, PR screenshots (`attach-pr-media`), release, dependency updates |
 | Code scans | `terreno-scan-1-aim` … `terreno-scan-5-track`, `terreno-scan-campaign`, `terreno-scan-loop` |
 | Expo and native | `track-upstream-expo`, `upgrading-expo`, `store-assets`, deployment / EAS skills |
 | Plugin agents | `pre-commit`, `ui-verifier` |
@@ -101,6 +101,13 @@ bun run check:lifecycle-skills
 
 Do not hand-edit `skills/`.
 
+A `.rulesync/skills/` skill that links a lifecycle reference as
+`references/<name>.md` (for example `references/push-ownership.md`) gets its own copy of
+`plugins/terreno-planning/references/<name>.md`, so the link still resolves once the skill
+is installed elsewhere. `skills:sync` rewrites those copies and `skills:check` fails when
+one drifts. Edit the plugin reference, never the copy, then run `bun run skills:sync` and
+`bun run rules`.
+
 ## Keep native hooks in sync
 
 Repository-level hooks are canonical in `.rulesync/hooks.json`; shared commands live in

package/src/docs/versioned/next/how-to/migrate-rtk-to-syncdb.md

@@ -335,8 +335,9 @@ export const syncDb = createSyncDb({authProvider, baseUrl, collections: ["todos"
 
 Better Auth session tokens live in the Better Auth client (`@terreno/rtk` `createBetterAuthClient`):
 
-- **Native:** `expo-secure-store`
-- **Web:** `@react-native-async-storage/async-storage`
+- **Native:** the Expo plugin's cookie jar in `expo-secure-store`
+- **Web (default):** Better Auth's HttpOnly session cookie, managed by the browser. No token is in app storage
+- **Web with `webAuth: "bearer"`:** the `set-auth-token` bearer in `localStorage` (or the `bearerStorage` you pass), readable with `getBetterAuthBearerToken()`. See [Frontend and API on different sites](configure-better-auth.md#frontend-and-api-on-different-sites)
 
 Syncdb does not store tokens itself — it calls `authProvider` on every transport/HTTP request.
 
@@ -346,12 +347,14 @@ On connect, the socket transport sends the bearer token from `getToken()`. When
 
 ### Backend
 
+Register `BetterAuthApp` and `RealtimeApp` on the same `TerrenoApp`. `RealtimeApp` picks up the
+Better Auth instance by itself, so no extra option is needed. Legacy JWT sockets keep working
+alongside it. Only a `RealtimeApp` mounted without `TerrenoApp` needs the instance passed in:
+
 ```typescript
 new RealtimeApp({betterAuth: {auth, userModel: User}})
 ```
 
-Required for Better Auth socket sessions. Legacy JWT sockets continue to work without it.
-
 ## 8. Codegen
 
 Synced collections use `bun run sync-sdk`, which runs `terreno-syncdb-codegen` from

package/src/docs/versioned/next/how-to/password-reset.md

@@ -29,6 +29,8 @@ authOptions: {
 }
 ```
 
+Pass the `message` through unchanged. Recovery mail carries `sensitive: true`, and `@terreno/comms` stores no payload for a sensitive message, so the reset or verify link never reaches the `CommsMessage` log or the admin Comms Dashboard. If you send through another transport, do not log or store the content of a message with `sensitive: true`.
+
 | Action | Path | Body |
 | --- | --- | --- |
 | Forgot | `POST /auth/forgotPassword` | `{email}` → 202 |
@@ -71,6 +73,10 @@ On `BetterAuthConfig` set the same `publicAppUrl`, `sendMail`, and `renderAuthMa
 4. Show a profile banner when `emailVerified` is false, with Resend calling `POST /auth/sendVerification`.
 5. Add `/verifyEmail` that reads `token` from the query string. JWT apps call `POST /auth/verifyEmail`. Better Auth apps try `GET /verify-email?token=...` first, then the JWT route so either token type can complete.
 
-A new `issueFor` for the same user and type invalidates earlier unused tokens of that type. Changing the mailbox through `PATCH /auth/me` invalidates unused `passwordReset` tokens even when the User schema has no `emailVerified` field. When `emailVerificationPlugin` is applied, mailbox change also sets `emailVerified` to false and invalidates unused `emailVerification` tokens. Letter casing alone does not count as a mailbox change. `emailVerified` and `tokenEpoch` are privileged user fields: signup and `PATCH /auth/me` drop them.
+A new `issueFor` for the same user and type invalidates earlier unused tokens of that type. Changing the mailbox through `PATCH /auth/me` invalidates unused `passwordReset` tokens even when the User schema has no `emailVerified` field. When `emailVerificationPlugin` is applied, mailbox change also sets `emailVerified` to false and invalidates unused `emailVerification` tokens. Letter casing alone does not count as a mailbox change. `emailVerified` and `tokenEpoch` are privileged user fields: signup and `PATCH /auth/me` drop them, along with the password fields `hash` and `salt`.
+
+To set a password from your own server code (for example an admin action), call `changeUserPassword(user, password, {adminId, app: req.app})` from `@terreno/api` so the change revokes sessions the same way a reset does. The example backend's `POST /users/:id/password` uses it.
+
+Either reset path also ends the user's MCP credentials: `mcp_` service tokens and MCP OAuth grants issued before the reset stop working, because they are bound to `tokenEpoch`. With `CommsApp` registered, push also stops going to devices the user registered before the reset until each device registers again.
 
-Better Auth password reset revokes that user's Better Auth sessions (`revokeSessionsOnPasswordReset`) and, when an app User exists, updates the JWT password and `tokenEpoch` so `POST /auth/login` cannot keep the old passport hash. JWT `POST /auth/resetPassword` does the reverse for Better Auth when `BetterAuthApp` is registered: it updates the Better Auth password and deletes Better Auth sessions. Console mail in development prints length only; check `CommsMessage` / console adapter logs for delivery, not the raw token in logger output. Request logs redact `password`, `newPassword`, `oldPassword`, `token`, and `refreshToken` in bodies and in URL query strings.
+Better Auth password reset revokes that user's Better Auth sessions (`revokeSessionsOnPasswordReset`) and, when an app User exists, updates the JWT password and `tokenEpoch` so `POST /auth/login` cannot keep the old passport hash. JWT `POST /auth/resetPassword` does the reverse for Better Auth when `BetterAuthApp` is registered: it updates the Better Auth password and deletes Better Auth sessions. Console mail in development prints length only; check `CommsMessage` / console adapter logs for delivery, not the raw token in logger output. Request logs redact password, token, secret, and code fields (any key name, any depth) in bodies and in URL query strings.

package/src/docs/versioned/next/how-to/product-announcements.md

@@ -131,7 +131,7 @@ Interrupt frequency is enforced **client-side** in `AnnouncementNavigator` befor
 </AnnouncementNavigator>
 ```
 
-`maxInterruptionsPerSession` defaults to `1` when omitted. The example app sets `skipFirstLaunch: false` so seeded interrupts still appear on first launch.
+`maxInterruptionsPerSession` defaults to `1` when omitted. The example app sets `skipFirstLaunch: false` so an announcement an admin publishes appears on the next launch.
 
 | Prop | Default | Behavior |
 |------|---------|----------|
@@ -150,9 +150,11 @@ Paste YouTube or Loom URLs in the announcement `body` using markdown links or im
 
 ## Example app
 
-`example-backend` registers `AnnouncementsApp` with `isStaff: (user) => user.admin === true` and an optional `matchAudience` org filter. `bun run backend:seed` idempotently seeds:
+`example-backend` registers `AnnouncementsApp` with `isStaff: (user) => user.admin === true` and an optional `matchAudience` org filter. `bun run backend:seed` idempotently seeds two **drafts**:
 
 - **Staff modal (required)** — `audienceType: "staff"`, `displayMode: "modal"`, `acknowledgementPolicy: "required"` (`Example staff operations bulletin`)
 - **Patient banner (dismiss-only)** — `audienceType: "patient"`, `displayMode: "banner"`, `acknowledgementPolicy: "dismiss-only"` (`Example patient care tip`)
 
-The staff launch example is rich markdown with a YouTube embed, overview/editor screenshots, and a tracked docs CTA. Re-running the seed updates that example in place. An existing legacy welcome row (`Welcome to Terreno announcements`) is archived idempotently so it no longer blocks the patient banner. `example-frontend` wraps authenticated users with `AnnouncementNavigator` (`skipFirstLaunch: false`, `userId` from the profile); non-staff users therefore see only the patient banner interrupt under the default session cap of `1`.
+The seed keeps them as drafts so a fresh database (local dev or a PR preview) does not interrupt sign-in. Publish one from **Admin → Announcements** to see it. Re-running the seed updates both examples in place and sets them back to draft. The staff example is rich markdown with a YouTube embed, overview/editor screenshots, and a tracked docs CTA. An existing legacy welcome row (`Welcome to Terreno announcements`) is archived idempotently. `example-frontend` wraps authenticated users with `AnnouncementNavigator` (`skipFirstLaunch: false`, `userId` from the profile).
+
+Release notes in the example app use [`WhatsNewBanner`](./whats-new-banner.md) instead of announcements.

package/src/docs/versioned/next/how-to/rate-limiting.md

@@ -77,13 +77,13 @@ const uploadLimit = createRouteRateLimitMiddleware({
 | `POST /auth/forgotPassword`, `/auth/resetPassword`, `/resetPassword` | auth |
 | `POST /auth/sendVerification`, `/auth/verifyEmail` | auth |
 | `GET /auth/github`, `/auth/github/callback` | auth |
-| `{betterAuthBasePath}/sign-in/*`, `sign-up/*`, `forget-password`, `request-password-reset`, `reset-password`, `send-verification-email`, `verify-email`, `callback/*` | auth |
+| `{betterAuthBasePath}/sign-in/*`, `sign-up/*`, `forget-password`, `request-password-reset`, `reset-password`, `send-verification-email`, `verify-email`, `callback/*`, `oauth-handoff/*`, `one-time-token/*` | auth |
 | Trailing slash on those paths (`/auth/login/`) | same bucket as the unsuffixed path |
 | `GET`/`PATCH /auth/me` | api (600 / 15 min) |
 | modelRouter, admin, AI HTTP, `POST /mcp`, `POST /sync/mutate` | api |
 | `GET /health`, `/healthz`, `/openapi.json`, `/swagger` | skip |
 
-`rateLimit.skip` adds extra skips. Health/openapi/swagger always skip. Paths use Express `req.path` (not the raw request-target), without a trailing slash.
+`rateLimit.skip` adds extra skips. Health/openapi/swagger always skip. Paths use Express `req.path` (not the raw request-target), without a trailing slash. Classification also resolves `.` and `..` segments, including `%2e` forms, the way Better Auth's router does: a request is charged to the auth bucket when either the path as sent or its resolved form is a credential route (so `/api/auth/%2e/sign-in/email` counts as sign-in), and a path that contains dot segments never gets the health/openapi/swagger skip.
 
 JWT login/signup/refresh and password-reset paths skip access-token verification so a stale `Authorization` header cannot block credential exchange. Other routes still 401 on an expired JWT. Path matching uses Express `req.path` and ignores trailing slashes and letter case.
 

package/src/docs/versioned/next/how-to/run-tests-locally.md

@@ -89,6 +89,56 @@ Full local suite: `bun run frontend:e2e`. Nightly load (`e2e-load` / `syncdb-loa
 not PR-blocking; run `bunx playwright test e2e/syncdb-loadlab.spec.ts` only when that job
 failed.
 
+`e2e/crossSiteBearer.spec.ts` and `e2e/crossSiteOAuth.spec.ts` have no CircleCI job: they need
+a web server built with `EXPO_PUBLIC_API_URL=http://127.0.0.1:4000`,
+`EXPO_PUBLIC_BETTER_AUTH_WEB_BEARER=true` and `EXPO_PUBLIC_MOCK_OIDC_SIGN_IN=true`, a backend
+with `BETTER_AUTH_URL=http://127.0.0.1:4000`, `BETTER_AUTH_OAUTH_HANDOFF=true` and
+`MOCK_OIDC_ISSUER`, and the mock OIDC provider on `127.0.0.1:4555`. Naming either spec file (or
+setting `E2E_CROSS_SITE_BEARER=true`) makes `playwright.config.ts` start all three and run only
+the cross-site specs, so stop any other backend on 4000 and web server on 8082 first:
+`cd example-frontend && bunx playwright test e2e/crossSiteBearer.spec.ts e2e/crossSiteOAuth.spec.ts`.
+
+### Deployed bearer smoke (`deploy-frontend-preview`)
+
+`netlify-deploy.sh frontend` builds the web app with `EXPO_PUBLIC_BETTER_AUTH_WEB_BEARER=true`
+for production and previews. After the preview deploy, the `deploy-frontend-preview` job's
+"Smoke the deployed preview in web bearer mode" step runs `bun run smoke:deployed`
+(`playwright.smoke.config.ts`, `e2e/deployedBearer.smoke.ts`) against
+`https://pr-<n>--terreno-frontend.netlify.app`. It signs up a new `smoke-*@example.com` user on
+the PR's own backend, agrees to the consent forms, reloads, opens the profile, and fails if the
+API's origin holds a Better Auth session cookie. It also checks that the Google button's OAuth
+handoff start link redirects (to the provider, or back to `/login?error=provider_not_found`)
+instead of returning 404; `gcp-deploy.sh` sets `BETTER_AUTH_OAUTH_HANDOFF=true` on both backends.
+Production deploys never run it. To re-run it:
+
+1. Against the PR preview, which takes about 1 minute:
+
+   ```bash
+   cd example-frontend
+   SMOKE_BASE_URL=https://pr-<n>--terreno-frontend.netlify.app \
+     SMOKE_API_URL=https://pr-<n>---terreno-backend-example-7knxlrnpqq-uc.a.run.app \
+     bun run smoke:deployed
+   ```
+
+2. Against a local cross-site stack, which takes about 5 minutes because of the web export.
+   Start the backend with Better Auth on `127.0.0.1:4000`, then build and serve the web app
+   with the flag on `localhost:8082` (a different site):
+
+   ```bash
+   # Terminal 1, from example-backend/ (the replica-set mongod from step 2 above)
+   AUTH_PROVIDER=better-auth BETTER_AUTH_URL=http://127.0.0.1:4000 PORT=4000 \
+     BETTER_AUTH_OAUTH_HANDOFF=true \
+     MONGO_URI="mongodb://127.0.0.1:27017/terreno-smoke?replicaSet=rs0" \
+     TOKEN_SECRET=dev TOKEN_ISSUER=dev REFRESH_TOKEN_SECRET=dev SESSION_SECRET=dev \
+     bun run src/index.ts
+   # Terminal 2, from example-frontend/. --clear: Metro's cache can keep an earlier
+   # build's EXPO_PUBLIC_* values.
+   EXPO_PUBLIC_API_URL=http://127.0.0.1:4000 EXPO_PUBLIC_BETTER_AUTH_WEB_BEARER=true \
+     bun run export --clear && bunx serve dist -s -l 8082
+   # Terminal 3, from example-frontend/
+   SMOKE_BASE_URL=http://localhost:8082 bun run smoke:deployed
+   ```
+
 CircleCI skips a shard no changed file can reach. Ask for the same verdict before
 pushing with `bun run check:e2e-affected` (see
 [the affected gate](circleci.md#e2e-affected-gate)).

package/src/docs/versioned/next/how-to/use-syncdb-correctly.md

@@ -96,7 +96,7 @@ In tests, clean up with `Model.collection.deleteMany(...)`, which bypasses Mongo
 
 ### Deltas don't apply `queryFilter`
 
-Snapshots and `/sync/entities` apply the router's `queryFilter`. Live deltas check only `permissions.read` (or RBAC) per recipient. A router that restricts visibility only through `queryFilter` leaks rows over the socket. Every synced router's `read` permission must enforce the same restriction itself.
+Snapshots and `/sync/entities` apply the router's `queryFilter`. Live deltas check only `permissions.read` per recipient (on an RBAC router: the role, `access.scope`, and `access.also.read`, the same checks REST read applies; subscriptions also apply `access.also.list`). A router that restricts visibility only through `queryFilter` leaks rows over the socket. Every synced router's `read` permission must enforce the same restriction itself.
 
 ### Membership grants arrive late
 

package/src/docs/versioned/next/how-to/websocket-integration.md

@@ -137,24 +137,56 @@ Add to your `app.json` or environment:
 }
 ``````
 
-### 2. Set Up Connection Hook
+### 2. Register the token source
 
-Create a custom hook to manage the connection:
+The hook reads its handshake token from the token source the app registers once at startup
+with `setTokenSource`. A JWT app registers nothing: the default source reads the JWT in
+storage. A Better Auth app registers the adapter it builds for syncdb:
+
+``````typescript
+// store/tokenSource.ts: import once from the app entry, before the store is created
+import {setTokenSource} from "@terreno/rtk";
+import {betterAuthAdapter, bridgeBetterAuthReactClient} from "@terreno/syncdb";
+import {authClient} from "@/lib/betterAuth";
+
+setTokenSource(betterAuthAdapter(bridgeBetterAuthReactClient(authClient)));
+``````
+
+With `webAuth: "bearer"`, also pass the adapter `getBearerToken`
+([syncdb adapter](../reference/syncdb.md#createsyncdb-configuration)).
+
+With a token source, the hook:
+
+- reads `getToken()` on every connect and reconnect;
+- calls `refresh()` once when the server rejects the token, then reconnects, and stops after a
+  second rejection (`onConnectError` fires). With no `refresh`, or a failed one, it stops at
+  once;
+- reconnects with the new token when `onAuthChange` fires, and disconnects when there is no
+  token.
+
+To use a different source for one socket, pass it as `tokenSource`. Passing the legacy
+`getAuthToken` getter instead turns the token source off for that hook. See
+[Token source](../reference/legacy/rtk.md#token-source).
+
+### 3. Set Up Connection Hook
+
+Create a custom hook to manage the connection. A Better Auth app gates `shouldConnect` on
+`selectBetterAuthUserId` instead of the JWT user id:
 
 ``````typescript
 // hooks/useWebSocket.ts
-import {useSocketConnection, getAuthToken, baseWebsocketsUrl} from "@terreno/rtk";
-import {useSelectCurrentUserId} from "@/store";
+import {useSocketConnection, baseWebsocketsUrl} from "@terreno/rtk";
+import {selectBetterAuthUserId} from "@terreno/rtk";
+import {useSelector} from "react-redux";
 import {useCallback} from "react";
 import * as Sentry from "@sentry/react-native";
 
 export const useWebSocket = () => {
-  const userId = useSelectCurrentUserId();
+  const userId = useSelector(selectBetterAuthUserId); // JWT apps: useSelectCurrentUserId()
   
   const {socket, isSocketConnected} = useSocketConnection({
     baseUrl: baseWebsocketsUrl,
     shouldConnect: !!userId,
-    getAuthToken,
     onConnect: () => {
       console.info("[WebSocket] Connected");
     },
@@ -176,7 +208,7 @@ export const useWebSocket = () => {
 };
 ``````
 
-### 3. Subscribe to Events in Components
+### 4. Subscribe to Events in Components
 
 ``````typescript
 // screens/TodoList.tsx
@@ -226,7 +258,7 @@ export const TodoListScreen = () => {
 };
 ``````
 
-### 4. Show Connection Status (Optional)
+### 5. Show Connection Status (Optional)
 
 ``````typescript
 import {useWebSocket} from "@/hooks/useWebSocket";
@@ -361,7 +393,8 @@ This logs:
 **Cause:** Token not provided or invalid.
 
 **Solution:**
-1. Ensure `getAuthToken()` returns a valid JWT
+1. Ensure the token source returns a valid token: `await getTokenSource()?.getToken()` (or
+   `getAuthToken()` on a JWT app with no source registered)
 2. Check backend token verification logic
 3. Enable `WEBSOCKETS_DEBUG` to see token status
 

package/src/docs/versioned/next/how-to/whats-new-banner.md

@@ -0,0 +1,55 @@
+# Show release notes with WhatsNewBanner
+
+Use `WhatsNewBanner` from `@terreno/ui` to tell people about a new release without blocking
+them. The banner reads "What's new in 57.16.2" until the viewer opens or dismisses it, then
+stays hidden until a newer release is listed. Use it instead of a required announcement modal
+for routine release notes.
+
+## Add the banner
+
+1. Build a list of releases, newest first. Each entry has a `version`, Markdown `body`, and
+   an optional `date`:
+
+   ```typescript
+   import type {WhatsNewRelease} from "@terreno/ui";
+
+   export const RELEASES: WhatsNewRelease[] = [
+     {body: "### Fixed\n\n- Exports finish on slow networks.", date: "2026-10-13", version: "2.4.1"},
+     {body: "### Added\n\n- Bulk-complete todos.", date: "2026-10-01", version: "2.4.0"},
+   ];
+   ```
+
+2. Render it near the top of a screen people see after signing in:
+
+   ```tsx
+   import {WhatsNewBanner} from "@terreno/ui";
+
+   <WhatsNewBanner releases={RELEASES} testID="home-whats-new-banner" />
+   ```
+
+3. Open the app. The banner shows the latest version and how many earlier releases the viewer
+   has not seen. **See what's new** opens a modal with the notes for every unseen release.
+
+The last seen version is stored on the device under `@TerrenoUI:whatsNew:lastSeenVersion`.
+Pass `storageKey` to keep separate histories, for example one per product.
+
+## Generate releases from CHANGELOG.md
+
+The example app builds its list from the repository changelog, so every release appears in the
+banner without hand edits:
+
+- `bun run whats-new:generate` writes the 10 most recent `CHANGELOG.md` releases to
+  `example-frontend/constants/whatsNew.generated.json`. Repo-relative links and `(#123)` pull
+  request numbers become GitHub URLs.
+- `bun run changelog:assemble <version>` regenerates that file when it cuts a release.
+- `bun run check:whats-new` fails when the file does not match `CHANGELOG.md`. CircleCI runs it
+  in the lint job, next to `check:changelog`.
+
+`example-frontend/constants/whatsNew.ts` types the JSON as `WhatsNewRelease[]`, and
+`SyncTodosScreen` renders the banner above the todo list.
+
+## When to use announcements instead
+
+`WhatsNewBanner` is static and per device. Use [product announcements](./product-announcements.md)
+when you need audience targeting, required acknowledgement, scheduling, or analytics. Props are
+listed in the [UI reference](../reference/ui.md#whatsnewbanner).

package/src/docs/versioned/next/implementationPlans/agent-ui-asks.md

@@ -115,6 +115,8 @@ How asks and blocks divide the work:
 | D25 | Compact surface mode | `surface: "compact"` on `/gpt/prompt` or `turn` offers only `ask_confirm` and a narrowed `ask_choice` (`select: one`, 2–3 options, labels ≤ 20), and appends one prompt line: keep replies to two short sentences and ask only yes/no or up to three short options. | assumed |
 | D26 | Button order and safety | Primary answer first, Cancel last. A `destructive` confirm marks its approve button `destructive`, so Apple Watch Double Tap, which triggers the first non-destructive action, can never approve it. | assumed |
 
+D27 note: Markdown images in `text` blocks and plain replies bypass `imageHosts`; this is documented as a known gap in `docs/explanation/agent-ui-asks.md`.
+
 ## Architecture
 
 ```

package/src/docs/versioned/next/implementationPlans/app-mcp-server.md

@@ -65,7 +65,7 @@ When this is done, an operator can:
 | Q2 | Primitive shape | **Factories:** `defineMCPTool` / `defineMCPPrompt` / `defineMCPResource` wrapping `registerMCP*`. |
 | Q3 | Default endpoint | **Keep `/mcp`.** Additive capabilities. No rename. |
 | Q4 | Multiple servers | **Yes, v1.** Named mounts with explicit include lists. Default `/mcp` remains the union of CRUD + globally registered primitives. Extra servers are opt-in and do not auto-include every model tool. |
-| Q5 | Auth | **Bearer (JWT + Better Auth session) plus OAuth 2.1 for MCP** via Better Auth (`@better-auth/mcp` + `@better-auth/oauth-provider`). Same User as REST after token exchange. JWT-only apps keep bearer-only; OAuth metadata mounts only when Better Auth is enabled. |
+| Q5 | Auth | **Bearer (JWT + Better Auth session) plus OAuth 2.1 for MCP** via Better Auth (`@better-auth/mcp` + `@better-auth/oauth-provider`). Same User as REST after token exchange. JWT-only apps get the Terreno-native `mcpOAuth` authorization server instead (#1573); with `mcpOAuth` off they keep bearer-only and mount no OAuth metadata. |
 | Q6 | Tool metadata | **MCP spec hints:** `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`, plus optional `outputSchema` + `structuredContent`. |
 | Q7 | Conditional register | **`shouldRegister(user)`** (and optional `shouldRegister: false`). Filter list methods and reject call/get/read if hidden. |
 | Q8 | Response helper | **`mcpResult.text` / `.json` / `.error`.** Images/audio out. |
@@ -161,7 +161,7 @@ Remote MCP clients (Claude connectors, ChatGPT, Cursor HTTP) expect **OAuth 2.1*
 5. Extend `extractUserFromHeaders` to accept an OAuth access token on `Authorization: Bearer`, resolve it through Better Auth, then load the app `User` by `betterAuthId` — same mapping as session cookies today.
 6. Keep JWT verification as a fallback so Inspector, tests, and `useMCPTools` keep working with session/JWT bearer.
 
-**When Better Auth is off (JWT-only):** do not mount OAuth metadata. Bearer JWT behavior is unchanged. Docs state that ChatGPT-class connectors need Better Auth.
+**When Better Auth is off (JWT-only):** set `mcpOAuth: {enabled: true, …}` to mount the Terreno-native OAuth 2.1 authorization server ([Enable MCP OAuth](../how-to/enable-mcp-oauth.md)). It serves the RFC 9728 and RFC 8414 documents, authorize/consent, token, and revoke, and `/mcp` answers unauthenticated requests with the 401 challenge. Dynamic client registration is a second opt-in (`dynamicClientRegistration: true`), off by default because the endpoint is unauthenticated and lets anyone create a client; without it the app creates `McpOAuthClient` documents itself. Revoking a token family writes a tombstone that `McpOAuthToken.issue` honors, so in-flight exchanges cannot revive it. The app hosts the consent screen. Bearer JWT keeps working. With `mcpOAuth` off, no OAuth metadata mounts and bearer behavior is unchanged.
 
 **Not in this IP:** social login providers (already documented); infra-mcp’s RBAC/elicitation; replacing Passport JWT for REST.
 
@@ -250,7 +250,7 @@ Tracer: example-backend custom tool already exists (`users_todo_statuses`). Add
 - Wire plugin in Better Auth setup used by `BetterAuthApp`.
 - RFC 9728 + 401 `WWW-Authenticate` on `/mcp`.
 - `extractUserFromHeaders` accepts OAuth access tokens.
-- JWT-only apps unchanged.
+- JWT-only apps unchanged by this phase: they use the Terreno-native `mcpOAuth` server (#1573, [Enable MCP OAuth](../how-to/enable-mcp-oauth.md)). Reuse its well-known builders (`buildProtectedResourceMetadata`, `buildAuthorizationServerMetadata`) and `/mcp` challenge (`sendMcpOAuthChallenge`) from `api/src/mcp/oauthMetadata.ts`, which does not depend on the JWT authorization-server routes, so both stacks share one code path.
 - How-to `docs/how-to/secure-app-mcp.md`; reference well-known paths.
 - Tests with Better Auth test instance: no token → 401 challenge; valid access token → `tools/list` as that user.
 
@@ -311,7 +311,10 @@ None. Additive APIs. `registerMCPTool` signature may gain optional fields only.
 - [ ] `invokeMCPTool` can assert a successful custom tool in Bun tests
 - [ ] `MCPService` can list tools over Streamable HTTP against `mountMCPServer`
 - [ ] Better Auth on: unauthenticated `/mcp` returns 401 with resource metadata; a valid OAuth access token runs tools as that user
-- [ ] JWT-only: existing bearer behavior unchanged; no OAuth well-known required
+- [ ] JWT-only with `mcpOAuth` off: existing bearer behavior unchanged; no OAuth well-known mounted
+- [ ] JWT-only with `mcpOAuth` on: RFC 9728/8414 documents mount, unauthenticated `/mcp` returns the 401 challenge, and bearer JWT still works
+- [ ] `mcpOAuth` on without `dynamicClientRegistration`: `/oauth/register` is 404, metadata has no `registration_endpoint`, and an app-created client completes the flow
+- [ ] A revoked token family stays revoked when a concurrent refresh or code exchange issues after the revoke
 - [ ] Hosted `terreno_generate_mcp_tool|prompt|resource` return TypeScript matching the factories
 - [ ] Docs: two MCP layers; prompts/resources; Inspector; OAuth vs bearer; generator tools
 - [ ] `registerMCPTool` without new fields still typechecks and runs