@terreno/mcp 57.16.1 → 57.17.0

package/dist/docs/versioned/next/how-to/add-github-oauth.md

@@ -68,7 +68,8 @@ setupServer({
     clientSecret: process.env.GITHUB_CLIENT_SECRET!,
     callbackURL: process.env.GITHUB_CALLBACK_URL || "http://localhost:4000/auth/github/callback",
     scope: ["user:email"], // Optional, defaults to ["user:email"]
-    allowAccountLinking: true, // Optional, defaults to true
+    allowAccountLinking: true, // Optional
+    allowedReturnTo: ["https://app.yourapp.com", "yourapp://auth"], // Optional, needed for returnTo
   },
 });
 ``````
@@ -81,7 +82,8 @@ setupServer({
 | `clientSecret` | string | Yes | GitHub OAuth Client Secret |
 | `callbackURL` | string | Yes | OAuth callback URL (must match GitHub app settings) |
 | `scope` | string[] | No | OAuth scopes (default: `["user:email"]`) |
-| `allowAccountLinking` | boolean | No | Allow linking GitHub to existing accounts (default: `true`) |
+| `allowAccountLinking` | boolean | No | `true` lets `GET /auth/github/link` attach GitHub to the signed-in user. When omitted, the link route is mounted but linking returns 400, and a GitHub login whose email matches an existing account links to it. `false` turns off both. |
+| `allowedReturnTo` | string[] | No | Exact http(s) origins (`https://app.yourapp.com`) or custom-scheme authorities (`yourapp://auth`) that `returnTo` may point to. Unset means `returnTo` is ignored. |
 | `findOrCreateUser` | function | No | Custom user creation/lookup handler |
 
 ## Step 4: Set Environment Variables
@@ -106,8 +108,20 @@ The following routes are automatically added when `githubAuth` is configured:
 GET /auth/github
 ``````
 
-Redirects users to GitHub for authentication. Optional query parameter:
-- `returnTo` — URL to redirect after successful authentication (tokens will be appended as query params)
+Redirects users to GitHub for authentication. The redirect carries an OAuth `state` value, and
+the response sets a short-lived (10 minute), signed, HttpOnly, `SameSite=Lax` cookie named
+`terreno_github_oauth_state` that holds the same value. The callback accepts the GitHub response
+only from the browser that holds that cookie, and each cookie works once. The cookie is signed
+with `SESSION_SECRET` (or `TOKEN_SECRET` when `SESSION_SECRET` is unset).
+
+Optional query parameter:
+- `returnTo` — URL to redirect to after successful authentication. Its origin (or custom-scheme
+  authority) must be listed in `allowedReturnTo`; any other value returns 400. When
+  `allowedReturnTo` is unset, `returnTo` is ignored and the callback returns JSON. Tokens are
+  delivered in the URL fragment (`#token=...&refreshToken=...&userId=...`), never the query
+  string. `returnTo` is kept in `req.session` between the two requests, so it needs a
+  persistent session middleware (for example `express-session`) mounted through
+  `beforeJsonSetup` or `addMiddleware`; TerrenoApp ships none.
 
 ### OAuth Callback
 
@@ -115,7 +129,7 @@ Redirects users to GitHub for authentication. Optional query parameter:
 GET /auth/github/callback
 ``````
 
-Handles the GitHub OAuth callback. Returns JSON with tokens:
+Handles the GitHub OAuth callback. Without an allowlisted `returnTo`, returns JSON with tokens:
 
 ``````json
 {
@@ -134,7 +148,12 @@ GET /auth/github/link
 Authorization: Bearer <jwt-token>
 ``````
 
-Links GitHub to the authenticated user's existing account. Redirects to GitHub, then back to callback.
+Links GitHub to the authenticated user's existing account. Redirects to GitHub, then back to
+the callback. The user ID from the bearer token is recorded in the signed state cookie, and the
+callback links GitHub only to that user. A session cookie or token that happens to be on the
+callback request is never used as the link target. Open this route in the same browser that will
+return to the callback, so the state cookie is present there. Requires
+`allowAccountLinking: true`.
 
 ### Unlink GitHub Account (Requires Auth)
 
@@ -164,7 +183,7 @@ Removes GitHub authentication from the user's account. Returns:
 3. User authorizes on GitHub
 4. Backend receives callback, creates new user with GitHub profile data
 5. Backend generates JWT tokens
-6. Backend redirects to `returnTo` URL with tokens in query params
+6. Backend checks `returnTo` against `allowedReturnTo` again and redirects there with tokens in the URL fragment
 7. Frontend stores tokens and logs user in
 
 ### Existing User Login
@@ -195,7 +214,8 @@ setupServer({
       // - profile: GitHub profile data
       // - accessToken: GitHub access token
       // - refreshToken: GitHub refresh token (if available)
-      // - existingUser: If user is authenticated, their user document
+      // - existingUser: The user who started GET /auth/github/link (from the verified
+      //   OAuth state), otherwise undefined
       
       if (existingUser) {
         // Link GitHub to existing user
@@ -243,6 +263,7 @@ const handleGitHubLogin = async () => {
   });
   
   if (result.type === "success") {
+    // Tokens arrive in the fragment; expo-auth-session merges fragment values into params
     const {token, refreshToken, userId} = result.params;
     // Store tokens and log in user
   }
@@ -258,12 +279,13 @@ const handleGitHubLogin = () => {
   window.location.href = `https://api.yourapp.com/auth/github?returnTo=${window.location.origin}/auth/callback`;
 };
 
-// On callback page (/auth/callback)
-const urlParams = new URLSearchParams(window.location.search);
-const token = urlParams.get("token");
-const refreshToken = urlParams.get("refreshToken");
-const userId = urlParams.get("userId");
-// Store tokens and redirect to app
+// On callback page (/auth/callback). Tokens are in the fragment, not the query string.
+const fragment = new URLSearchParams(window.location.hash.slice(1));
+const token = fragment.get("token");
+const refreshToken = fragment.get("refreshToken");
+const userId = fragment.get("userId");
+// Clear the fragment, store tokens, and redirect to app
+window.history.replaceState(null, "", window.location.pathname);
 ``````
 
 ## Creating a GitHub OAuth App
@@ -284,8 +306,9 @@ const userId = urlParams.get("userId");
 ## Security Considerations
 
 - **Never expose client secrets** — They should only exist on the backend
+- **State is enforced** — The callback rejects a response without a valid, unexpired state cookie from the same browser (redirect to `/auth/github/failure`), which blocks login CSRF and cross-site account linking
 - **Use HTTPS in production** — GitHub OAuth requires HTTPS for production callbacks
-- **Validate redirect URLs** — Only allow trusted domains in `returnTo` parameters
+- **Redirect allowlist** — List only your own app origins in `allowedReturnTo`. Matching is exact on origin (or custom-scheme authority); subdomains and other ports are not included
 - **Scope minimization** — Only request GitHub scopes your app actually needs
 - **Token storage** — Store tokens securely on the frontend (SecureStore on mobile, httpOnly cookies on web)
 
@@ -301,13 +324,23 @@ const userId = urlParams.get("userId");
 
 A different user has already linked this GitHub account. Users must unlink it first or use a different GitHub account.
 
+### Callback redirects to `/auth/github/failure` right away
+
+The OAuth state did not verify. The flow must start (`/auth/github` or `/auth/github/link`) and
+finish (`/auth/github/callback`) in the same browser within 10 minutes, and the API host that
+serves `callbackURL` must be the host that set the cookie. Check that `SESSION_SECRET` is the
+same on every instance.
+
 ### "Account linking is disabled"
 
 Set `allowAccountLinking: true` in `githubAuth` configuration.
 
 ### Tokens not included in callback
 
-If using `returnTo`, tokens are appended as query parameters. Check that your frontend is reading them correctly.
+Tokens are in the URL fragment (`window.location.hash`), not the query string. If the callback
+returns JSON instead of redirecting, check that `allowedReturnTo` lists the `returnTo` origin and
+that a session middleware keeps `req.session` between `/auth/github` and the callback. A 400
+"returnTo is not an allowed redirect target" means the origin is not listed.
 
 ## Learn More
 

package/dist/docs/versioned/next/how-to/admin-add-model.md

@@ -49,4 +49,7 @@ Common fields:
   sentinel is consumed before Mongo receives the query.
 - `fieldsets`: grouped form sections.
 - `readonlyFields` / `hiddenFields`: display-only or omitted form fields.
-- `adminPermissions`: optional admin-specific permission methods.
+- `adminPermissions`: optional per-action (`list`, `read`, `create`, `update`, `delete`)
+  permission methods. They run in addition to the admin check (`admin:access` plus the model's
+  RBAC action, or `IsAdmin`), so they can only restrict access. An empty array disables that
+  action, including `list` and `read`.

package/dist/docs/versioned/next/how-to/ai-feature-development.md

@@ -108,6 +108,11 @@ await aiService.generateText({
 
 Missing `production` fails the request (400). Do not fall back to a hardcoded string.
 
+3. Bound cost before users reach the AI routes. `@terreno/ai` has no per-user token or spend
+   limit, and a chat reply keeps running after the client disconnects. Enable `TerrenoApp`
+   `rateLimit` and set a provider budget or quota alert; see
+   [Cost and abuse limits](../reference/ai.md#cost-and-abuse-limits).
+
 ## 7. Production tracing and feedback
 
 Do this in parallel with steps 1–6 once the feature is reachable.

package/dist/docs/versioned/next/how-to/background-jobs.md

@@ -46,7 +46,10 @@ entrypoint.
 When `JobsApp` is registered **before** `AdminApp`, `POST {adminBase}/scripts/:name/run`
 enqueues job `admin/script` (`maxAttempts: 1`) and still returns `{taskId}` for the existing
 Scripts poll UI (`BackgroundTask`). Progress, logs, dry/wet, and cancel stay on that row.
-Cancel also cancels the job so `ctx.signal` aborts.
+Cancel also cancels the job so `ctx.signal` aborts. The job handler starts the script only
+when it moves the task from `pending` to `running`; a delivery for a task that already
+started fails with 409 and the script is not run again. Start a new run instead of retrying
+a dead `admin/script` job.
 
 Apps without `JobsApp` keep the previous in-process `void` runner. The CLI
 (`runScriptCli` / `bun run script`) stays process-local.
@@ -114,8 +117,17 @@ On shutdown, call `jobsApp.stopWorker()` so in-flight handlers receive `ctx.sign
 
 ## Mongo runner: restart, retry, idempotency, schedules
 
-**Restart:** Jobs are Mongo documents. A crashed worker leaves `running` rows; after
-`lockTtlMs` (default 15 minutes) another worker reclaims them via `lockedAt` expiry.
+**Lease:** A claimed job holds a lease on its row (`lockedAt` / `lockedBy`). While the
+handler runs, the worker renews `lockedAt` every `lockTtlMs / 3`, so a long handler keeps its
+claim and no other worker or execute dispatch runs it at the same time. If a renewal finds
+that another consumer owns the row, the worker aborts `ctx.signal` and discards its own
+result. A finalize failure on one job is logged and does not stop the poll loop.
+
+**Restart:** Jobs are Mongo documents. A crashed worker leaves `running` rows; once their
+lease is older than `lockTtlMs` (default 15 minutes) another worker reclaims them. A reclaim
+counts as an attempt (`attemptCount++`, `attempts[]` entry with `errorClass: "LeaseExpired"`).
+When that exhausts `maxAttempts`, the job goes to `status: "dead"` instead of running again,
+so a `maxAttempts: 1` job never runs twice.
 
 **Retry:** Handler throws → `attemptCount++`, `attempts[]` entry, exponential backoff with
 equal jitter, `status: "pending"` and future `runAt`. At `maxAttempts` (default 5) →
@@ -130,8 +142,9 @@ tick when a child for that schedule is still `pending` / `running` / `scheduled`
 
 ## At-least-once handlers
 
-Delivery is **at-least-once**: lock expiry, Cloud Task retries, or Vercel queue redelivery
-can run a handler more than once.
+Delivery is **at-least-once**: a reclaim after a worker crash (within `maxAttempts`),
+Cloud Task retries, or Vercel queue redelivery can run a handler more than once. A live
+handler is never run concurrently by a second consumer while its lease renews.
 
 - Make handlers idempotent (stable keys, upserts, “already processed” checks).
 - Use `idempotencyKey` on enqueue to prevent duplicate **rows**, not duplicate execution after admin retry/requeue.

package/dist/docs/versioned/next/how-to/circleci.md

@@ -239,7 +239,8 @@ restrict `terreno-release` and `terreno-npm` to tag/manual release pipelines.
 | `terreno-e2e` | `E2E_TOKEN_SECRET`, `E2E_REFRESH_TOKEN_SECRET`, `E2E_SESSION_SECRET` | `e2e`, `admin-spa-integration`, `maestro-e2e` |
 | `terreno-release` | `REPO_ADMIN_TOKEN`, `ZOOM_WEBHOOK_URL`, `ZOOM_WEBHOOK_TOKEN` | stable version bump + release notification |
 | `terreno-agentic` | `CURSOR_API_KEY`, optional `CURSOR_MODEL` | `architectural-pr-review` |
-| `terreno-github-api` | PAT (`pull-requests`, `contents`, …) | `dco`, `architectural-pr-review` |
+| `terreno-github-api` | PAT (`pull-requests`, `contents`, …) | `dco`, `architectural-pr-review`, `approve` |
+| `terreno-approve` | `TERRENO_APP_ID`, `TERRENO_APP_PRIVATE_KEY` (the terreno-approval-agent GitHub App), `ANTHROPIC_API_KEY` | `approve` |
 | `terreno-github-deployments` | `GITHUB_DEPLOYMENTS_TOKEN`: fine-grained PAT on `TerrenoLabs/terreno` with **Deployments: read/write** and **Pull requests: read** only | GitHub Deployment records + preview PR lookup in every Netlify/GCP deploy job |
 
 Until contexts exist, e2e jobs may use **project env vars for `E2E_*` secrets only**
@@ -247,8 +248,9 @@ Until contexts exist, e2e jobs may use **project env vars for `E2E_*` secrets on
 GitHub PAT) in project env vars — those are injected into every job, including
 `bun` scripts from the PR. `terreno-github-api` must hold the PAT as
 `GITHUB_TOKEN`; restrict it to this project and leave fork-PR secret passing off.
-The `always` workflow attaches it **only** to `dco` and `architectural-pr-review`
-(the latter also gets `terreno-agentic`). DCO skips if `GITHUB_TOKEN` is unset.
+The `always` workflow attaches it **only** to `dco`, `architectural-pr-review`
+(which also gets `terreno-agentic`), and `approve` (which also gets `terreno-approve`).
+DCO skips if `GITHUB_TOKEN` is unset.
 `architectural-pr-review` also skips if `GITHUB_TOKEN` or `CURSOR_API_KEY` is
 unset, and it skips fork PRs. The job checks out `origin/master` before running
 the review script so a PR cannot rewrite the reviewer.
@@ -293,6 +295,7 @@ the same commands through the parameterized `packages-ci` job, gated by
 | Repository policies (barrels, source rules, explicit any, licenses, changelog, parity, lifecycle, static analysis) | `repo-policies` |
 | Verify rules are in sync | `rulesync-check` |
 | `dco` | `dco` |
+| (none) | `approve` |
 | Run all tests (API CI) | `api-ci` |
 | Admin backend lint, compile, coverage | `packages-ci` (`admin-backend`) |
 | Admin frontend lint, compile, coverage | `packages-ci` (`admin-frontend`) |
@@ -339,6 +342,39 @@ CD replacement map:
 | Publish on tag (`publish-on-tag.yml`) | `publish-release` |
 | Appium Android / iOS | Not ported (Maestro web is `maestro-e2e`) |
 
+## Approval agent
+
+`approve` runs `brewery approve` from
+[joshgachnang/brewery](https://github.com/joshgachnang/brewery) on every same-repo PR
+pipeline and posts one review as the **terreno-approval-agent** GitHub App plus a
+`terreno/approve` check run. Policy lives in `.brewery.json` (`approve` block: levels
+the App may approve, path rules that floor, cap, or forbid approval; when a file matches
+both a floor and a lower ceiling, the floor wins) and
+`docs/approval-rubric.md` (what the model scores). Both are read from `origin/master`,
+so a PR cannot change the rules it is judged by, and a PR that edits either file is
+never approved. The job resets its working tree to `origin/master` right after
+checkout, so the PR-number script, `bunfig.toml`, and the agent's working directory all
+come from master and nothing from the PR tree runs while the App key is in the
+environment; brewery reads the head through `git show <sha>:`. Brewery itself is
+pinned to a commit (`BREWERY_REF`) and cloned into `$HOME`; the model runs read-only
+with an allowlisted environment that holds no GitHub or App credential. The job waits
+(`--wait-checks`, up to 45 minutes) for every other check on the head before judging,
+ignoring its own `ci/circleci: approve` check (`selfChecks` in `.brewery.json`), and
+skips a red or still-pending head without spending a model, so it runs once per push,
+last.
+
+To teach the agent from what reviewers actually say, run
+`brewery calibrate TerrenoLabs/terreno` (optionally `--reviewer <login>` or `--notes
+<file>` of pasted comments): it opens one PR editing `docs/approval-rubric.md` and the
+path rules from the review comments since the last pass.
+
+Rollout: `approveLevels` is `[]`, so every PR gets a `COMMENT` review that says the
+risk level and why, and nothing approves. After a dozen PRs, compare the levels with
+how humans reviewed them, tune the path rules and rubric, then set
+`"approveLevels": ["low"]` in a one-line PR. The prompts and answers behind each
+verdict are stored as the `brewery-approve` job artifact. Full reference:
+[brewery `docs/approve.md`](https://github.com/joshgachnang/brewery/blob/master/docs/approve.md).
+
 ## Manual pipelines
 
 Trigger a pipeline from the CircleCI UI/API on the ref containing the code to

package/dist/docs/versioned/next/how-to/configure-better-auth.md

@@ -97,7 +97,10 @@ email-verification mail match the JWT recovery templates. The hooks throw 501 an
 `publicAppUrl` is missing. JWT `POST /auth/resetPassword` updates the Better Auth password and
 deletes Better Auth sessions when this plugin is registered. Better Auth password reset updates
 the JWT password and `tokenEpoch` for the matching app User so dual-enrolled accounts cannot keep
-the old passport hash.
+the old passport hash. Better Auth `change-password` does the same for an app User that already
+has a JWT password, and bumps `tokenEpoch` for every app User. `revoke-sessions` and
+`revoke-other-sessions` bump `tokenEpoch`, so JWT refresh tokens issued before them stop working.
+An account with only a Better Auth password does not gain a JWT password.
 
 ```typescript
 import {getCommsService, renderAuthMail} from "@terreno/comms";
@@ -117,6 +120,51 @@ Throwaway in-process seed apps (CLI / container smoke tests that call Better Aut
 sign-up many times) should set `disableRateLimit: true` on that instance only.
 Better Auth enables its limiter in production, which 429s the fourth seeded user.
 
+#### Pass other Better Auth options and plugins
+
+`BetterAuthConfig` covers the settings Terreno manages. For anything else, use `options` and
+`plugins` instead of replacing `BetterAuthApp`:
+
+- `options` takes any Better Auth option except `basePath` and `plugins`, with nested fields
+  optional. It is deep-merged over the options Terreno builds. Arrays (such as `trustedOrigins`)
+  replace Terreno's instead of merging. An explicit value wins; an `undefined` value is ignored,
+  so it cannot clear a default.
+- `plugins` are appended after Terreno's `bearer()` plugin. Their endpoints mount under
+  `basePath`, like the built-in ones.
+
+``````typescript
+const config: BetterAuthConfig = {
+  enabled: true,
+  options: {
+    emailAndPassword: {
+      requireEmailVerification: true,
+      // Carry over legacy password hashes during a migration
+      password: {hash: hashPassword, verify: verifyPassword},
+    },
+    databaseHooks: {user: {create: {after: async (user) => onUserCreated(user)}}},
+  },
+  plugins: [myBetterAuthPlugin()],
+};
+``````
+
+| Terreno default | Set from | What overriding it drops |
+| --- | --- | --- |
+| `database` | MongoDB adapter on the app's connection, in the connection's database (the `dbName` passed to `mongoose.connect`, else the URI's database) | Users and sessions in the app's database |
+| `emailAndPassword.enabled` | `true` | Email/password sign-in |
+| `emailAndPassword.revokeSessionsOnPasswordReset` | `true` | Signing out other sessions after a password reset |
+| `emailAndPassword.sendResetPassword` | `sendMail` | Terreno's reset email |
+| `emailAndPassword.onPasswordReset` | `userModel` | Syncing the new password to JWT credentials |
+| `terreno-credential-sync` plugin (always registered with `userModel`) | `userModel` | Not overridable; syncs change-password and session revocation to JWT credentials |
+| `emailVerification.sendOnSignUp`, `emailVerification.sendVerificationEmail` | `sendMail` | Terreno's verification email on sign-up |
+| `session.cookieCache` | `{enabled: true, maxAge: 300}` | The 5-minute session cookie cache |
+| `advanced.defaultCookieAttributes` | `crossDomainCookies` | `SameSite=None; Secure` cookies for cross-site frontends |
+| `rateLimit` | `disableRateLimit` | Turning Better Auth's limiter off |
+| `socialProviders` | `googleOAuth`, `githubOAuth`, `appleOAuth` | The configured social providers (`options` adds to them per provider) |
+| `trustedOrigins` | `trustedOrigins` | The origins listed in the config |
+
+Endpoints added by `plugins` are not part of the `auth.api` type. Call them over HTTP, or cast
+`auth.api` where you call them on the server.
+
 ### 3. Register BetterAuthApp Plugin
 
 Use the TerrenoApp plugin system:
@@ -143,10 +191,16 @@ if (betterAuthConfig) {
 const server = app.start();
 ``````
 
+`RealtimeApp` (registered directly or through `TerrenoApp({realtime})`) uses this plugin's Better Auth instance for socket sessions. Do not build a second instance with `createBetterAuth` for sockets.
+
+`BetterAuthApp` keeps Better Auth's `user`, `account`, `session`, and `verification` collections in the mongoose connection's database, so a `dbName` passed to `mongoose.connect` (the example backend's `MONGO_DB_NAME`) isolates them along with your models. Earlier releases wrote them to the connection string's default database instead. If your app connects with a `dbName` that differs from the URI's database, copy those four collections into the `dbName` database when you upgrade, or users must sign up and sign in again.
+
 ### 4. Update User Model
 
 `syncBetterAuthUser` creates the app `User` on the first authenticated request after Better Auth sign-up. Declare `betterAuthId` on that schema. Declare `oauthProvider` only if the app uses social OAuth.
 
+To lock an account out, set `disabled: true` on its app `User` (for example with `isDisabledPlugin`). That user's Better Auth sessions stop authenticating: `req.user` is not set, so protected routes answer 401. Sign-out still works.
+
 Email/password sync does **not** write `oauthProvider`. A `strict: "throw"` schema that omits the field stays valid. Social login still passes a provider string and requires the field.
 
 ``````typescript
@@ -169,27 +223,46 @@ const userSchema = new mongoose.Schema(
 ``````typescript
 import {createBetterAuthClient} from "@terreno/rtk";
 
+// `scheme` is the app's deep-link scheme (required).
 export const authClient = createBetterAuthClient({
   baseURL: process.env.EXPO_PUBLIC_API_URL || "http://localhost:4000",
+  scheme: "yourapp",
 });
 ``````
 
+On web the client authenticates with Better Auth's session cookie. When the web frontend and
+the API are on different sites, use [bearer mode](#frontend-and-api-on-different-sites).
+
+A cookie-authenticated `POST`, `PUT`, `PATCH`, or `DELETE` to any Terreno route is
+authenticated only when its `Origin` (or, without one, its `Referer`) is in `trustedOrigins` or
+is the API's own origin. Otherwise `req.user` stays unset and protected routes answer 401, so
+another site cannot submit a form that writes as the signed-in user. Add every web origin that
+uses cookie mode to `trustedOrigins`. Requests with an `Authorization: Bearer` session token,
+safe methods, and clients that send no `Origin`, `Referer`, or cross-site `Sec-Fetch-Site`
+(native apps, server scripts) are not affected. Better Auth's `advanced.disableCSRFCheck` turns
+the check off. A `trustedOrigins` function is not consulted; list the origins.
+
 ### 2. Add Session Redux Slice
 
 ``````typescript
 import {generateBetterAuthSlice} from "@terreno/rtk";
 import {configureStore} from "@reduxjs/toolkit";
 import {authClient} from "./authClient";
+import {api} from "./sdk"; // the app's generated RTK Query API
 
-const {sessionReducer, sessionMiddleware} = generateBetterAuthSlice(authClient);
+// Purge the SDK's cached responses on logout or user switch.
+const betterAuth = generateBetterAuthSlice({apisToReset: [api], authClient});
 
 export const store = configureStore({
   reducer: {
-    session: sessionReducer,
+    betterAuth: betterAuth.reducer, // selectors read `state.betterAuth`
     // ... other reducers
   },
-  middleware: (getDefault) => getDefault().concat(sessionMiddleware),
+  middleware: (getDefault) => getDefault().concat(...betterAuth.middleware),
 });
+
+// Call after sign-in, sign-out, and at app startup to copy the session into Redux
+void betterAuth.syncSession(store.dispatch);
 ``````
 
 ### 3. Add Social Login UI
@@ -237,6 +310,201 @@ const LoginScreen = () => {
 };
 ``````
 
+## Frontend and API on different sites
+
+By default the web client relies on Better Auth's HttpOnly session cookie. When the web app
+and the API are on different sites (for example `app.example.com` and `api.example.net`, or
+two hosting providers' domains), that cookie is a third-party cookie, and browsers such as
+Safari block it. The user signs in and is signed out on the next request.
+
+Use bearer mode in that case. Keep cookie mode when the frontend and API share a site.
+
+``````typescript
+import {createBetterAuthClient} from "@terreno/rtk";
+
+export const authClient = createBetterAuthClient({
+  baseURL: process.env.EXPO_PUBLIC_API_URL || "http://localhost:4000",
+  scheme: "yourapp",
+  webAuth: "bearer",
+});
+``````
+
+With `webAuth: "bearer"`, on web only:
+
+- The client stores the `set-auth-token` response header from sign-in under
+  `${storagePrefix}_bearer_token` (default `terreno_bearer_token`) in `localStorage`.
+- Every Better Auth client call, `getSession` included, sends `Authorization: Bearer <token>`
+  and no cookies (`credentials: "omit"`).
+- `signOut()` forgets the token before its request is sent, so a failed sign-out never leaves
+  a usable token on the device.
+- A successful `getSession` that returns no session clears the token, unless a newer token was
+  stored while that request was in flight. A failed or 5xx `getSession` keeps it.
+
+Native apps ignore `webAuth`: the Expo plugin already keeps the session without browser cookies.
+
+Bearer mode covers email and password sign-in directly. Social and generic OAuth sign-in end
+with a redirect, so the page never sees `set-auth-token`. They need the
+[one-time-token handoff](#social-sign-in-in-bearer-mode) below.
+
+Apps that handle PHI should pass `bearerStorage: window.sessionStorage` and serve a strict
+Content-Security-Policy. `localStorage` is readable by any XSS on the frontend's origin and
+outlives the tab, so a stolen or forgotten token stays usable after the person closes it.
+
+Read the stored token outside the client, without a network call, with
+`getBetterAuthBearerToken({storagePrefix?, bearerStorage?})`. Pass the same options the client
+was created with.
+
+example-frontend shows the whole setup. `EXPO_PUBLIC_BETTER_AUTH_WEB_BEARER=true` turns on
+bearer mode in `lib/betterAuth.ts`. `store/syncdb.ts` passes the stored token to
+`betterAuthAdapter` as `getBearerToken`, and `store/index.ts` registers that adapter with
+`setTokenSource` before it creates the store, so RTK Query, the socket and MCP tools send the
+same token. `e2e/crossSiteBearer.spec.ts` signs in from `localhost:8082` to an API on
+`127.0.0.1:4000` with every `set-cookie` header stripped, then reloads.
+
+### Server requirements
+
+- The web app's origin must be in `trustedOrigins`. A cookie-less sign-in sends an `Origin`
+  header, and Better Auth rejects an unlisted origin with 403 `INVALID_ORIGIN`:
+
+  ``````typescript
+  const config: BetterAuthConfig = {
+    enabled: true,
+    trustedOrigins: ["https://app.example.com", "yourapp://", "exp://"],
+  };
+  ``````
+
+  Better Auth skips this check when `NODE_ENV=test`, so test it against a non-test build.
+- No CORS change is needed. Bearer mode sends no cookies, so the default `corsOrigin` (`"*"`)
+  works, and so does an explicit list that includes the web origin.
+- No header change is needed. Better Auth's bearer plugin, which `BetterAuthApp` enables, lists
+  `set-auth-token` in `Access-Control-Expose-Headers` itself, so the page can read it.
+
+### Social sign-in in bearer mode
+
+The server adds a single-use, three-minute token to the OAuth callback's redirect, in the URL
+fragment, and the web app exchanges it for the bearer. rtk binds each exchange to a random
+nonce the tab stored when it started the sign-in, so a token planted in a link is never sent.
+
+1. On the server, list the web app's origin and the one page that reads the token. The origin
+   must also be in `trustedOrigins`:
+
+   ``````typescript
+   const config: BetterAuthConfig = {
+     enabled: true,
+     oauthHandoff: {
+       callbackPaths: ["/"], // the default; list only the page that runs the steps below
+       webOrigins: ["https://app.example.com"],
+     },
+     trustedOrigins: ["https://app.example.com", "yourapp://", "exp://"],
+   };
+   ``````
+
+   `webOrigins` takes exact `http(s)` origins. `callbackPaths` takes exact paths in normal form
+   (no trailing-slash or case variants). The query is free. Any other return page is refused.
+
+2. Start the sign-in from the buttons with `signInSocialWithHandoff`. It stores the nonce in
+   `sessionStorage` and navigates the page to `GET {basePath}/oauth-handoff/start`, which keeps
+   Better Auth's OAuth state cookie first-party on the API's origin. The start endpoint answers
+   400 when a request's `Sec-Fetch-Dest` is set and is not `document`, so open it as a page
+   navigation, never with `fetch`, an `<img>`, or an `<iframe>`:
+
+   ``````typescript
+   import {signInSocialWithHandoff} from "@terreno/rtk";
+
+   <SocialLoginButton
+     provider="google"
+     onPress={() =>
+       signInSocialWithHandoff({
+         callbackURL: "/", // must be one of callbackPaths; defaults to "/" on this origin
+         client: authClient,
+         errorCallbackURL: "/login", // optional; defaults to callbackURL
+         provider: "google",
+       })
+     }
+   />
+   ``````
+
+   It throws on native, in cookie mode, and when `sessionStorage` is blocked. Keep
+   `authClient.signIn.social` on native and in cookie mode.
+
+3. On the return page, await `completeBetterAuthOAuthHandoff` at startup, before anything
+   reads the session, before any code acts on other query parameters (such as `next=`), and
+   before Sentry, analytics, or other third-party scripts start:
+
+   ``````typescript
+   import {completeBetterAuthOAuthHandoff} from "@terreno/rtk";
+
+   await completeBetterAuthOAuthHandoff({client: authClient});
+   await betterAuth.syncSession(store.dispatch);
+   initSentry();
+   ``````
+
+   When the URL has `#ott=<token>` and a `handoff=` equal to the stored nonce, it removes
+   `ott`, `handoff` and the stored nonce with `history.replaceState`, then posts the token to
+   `{basePath}/one-time-token/verify`. Bearer mode stores the `set-auth-token` that comes back.
+   It resolves `true` only when a token was stored, and it never rejects. Other query and
+   fragment parts stay. A token without a matching nonce, or an `ott` in the query instead of the
+   fragment, is removed from the URL and never sent.
+   Calls made while one is running share its result, so React strict mode verifies once.
+
+4. Show sign-in errors from the query. A failed start or callback comes back with
+   `?error=provider_not_found`, `?error=sign_in_failed`, or one of Better Auth's own `error=`
+   codes. The function resolves `false` and leaves `error` in the URL.
+
+The return page must not redirect, on the server or in the browser, before the function has
+run. A browser carries the fragment through a redirect that has none of its own, so a redirect
+would hand the token to the next page. For the same reason, keep `callbackPaths` to that page.
+
+example-frontend uses `/login` as the return page. With `BETTER_AUTH_OAUTH_HANDOFF=true`,
+example-backend sets `oauthHandoff` to its web origins and `callbackPaths: ["/login"]`. With
+`NODE_ENV=production` it drops loopback origins (`localhost`, `127.0.0.1`, `[::1]`, any port) from
+the handoff only, so a token never goes to a page on the visitor's own machine, and it refuses to
+start when no other origin is left in `CORS_ORIGINS`. CORS and `trustedOrigins` keep them. In bearer mode `lib/betterAuth.ts` starts the social buttons with
+`signInSocialWithHandoff`. `app/_layout.tsx` syncs the session only after the exchange resolves.
+
+In an Expo Router app, run the exchange from the entry file, not from a layout. Expo Router
+copies the URL, fragment included, as soon as it is imported, and writes that copy back into
+the address bar when it routes, which would put `ott` and `handoff` back. Importing
+`@terreno/rtk` imports Expo Router too (through `@terreno/ui`). example-frontend's `index.js`
+first imports `lib/oauthHandoffUrl.ts`, which has no imports and hides `handoff` and `ott` from
+the URL, then `lib/oauthHandoff.ts`, which puts the URL back and calls
+`completeBetterAuthOAuthHandoff` in the same synchronous step, then `expo-router/entry`.
+
+The login screen shows `?error=` in `login-screen-error`. `e2e/crossSiteOAuth.spec.ts` signs in
+cross-site through a local mock OIDC provider (`e2e/helpers/mockOidcProvider.ts`), which
+example-backend registers as the `mock-oidc` generic OAuth provider only when `MOCK_OIDC_ISSUER`
+is set. example-backend refuses to start when `MOCK_OIDC_ISSUER` is set with
+`NODE_ENV=production` or names a host other than `127.0.0.1`, `localhost` or `[::1]`.
+
+### Trade-offs
+
+A bearer token in web storage is readable by any script on the frontend's origin, so an XSS
+can steal it. An HttpOnly cookie cannot be read that way, which is why cookie mode stays the
+default. `localStorage` also outlives browser restarts, so on a shared device, such as a family
+computer, the next person to open the app is still signed in.
+
+On shared devices, keep the token in `sessionStorage` so it ends when the browser session does.
+Reading `window.sessionStorage` throws when the browser blocks site storage, so guard it:
+
+``````typescript
+const sessionStorageOrDefault = (): Storage | undefined => {
+  try {
+    return typeof window === "undefined" ? undefined : window.sessionStorage;
+  } catch {
+    return undefined; // falls back to localStorage, or to no storage when that is blocked too
+  }
+};
+
+export const authClient = createBetterAuthClient({
+  baseURL: process.env.EXPO_PUBLIC_API_URL || "http://localhost:4000",
+  bearerStorage: sessionStorageOrDefault(),
+  scheme: "yourapp",
+  webAuth: "bearer",
+});
+``````
+
+`bearerStorage` takes any synchronous `{getItem, setItem, removeItem}` store.
+
 ## OAuth Provider Setup
 
 ### Google OAuth
@@ -318,9 +586,19 @@ Better Auth runs **in parallel** with JWT auth. You don't need to migrate existi
 4. Existing users continue using JWT tokens
 5. Optionally add migration logic to link accounts
 
+An existing JWT user who signs up through Better Auth with the same email is linked to their app
+`User` only once Better Auth has verified that email. Until then their session does not
+authenticate. Configure `sendMail` so verification mail goes out, and consider
+`options.emailAndPassword.requireEmailVerification: true`. Social sign-in with a provider that
+verifies email links on first contact. If the app `User` never verified its email
+(`emailVerified` is not `true`), linking removes its legacy password and bumps `tokenEpoch`, so
+the user signs in through Better Auth or resets the password from then on. A row that already has
+a different `betterAuthId` is never relinked. Set `SIGNUP_DISABLED=true` once Better Auth is the
+only sign-up path, so new accounts cannot be created through the legacy `/auth/signup`.
+
 ## Learn More
 
 - [Authentication Architecture](../explanation/authentication.md)
 - [@terreno/api Reference](../reference/api.md#better-auth)
-- [@terreno/rtk Reference (legacy)](../reference/legacy/rtk.md#better-auth)
+- [@terreno/rtk Reference (legacy)](../reference/legacy/rtk.md#better-auth-integration)
 - [Better Auth Documentation](https://better-auth.com/)

package/dist/docs/versioned/next/how-to/connect-mcp-service-token.md

@@ -2,7 +2,7 @@
 
 Mint a personal `mcp_…` Bearer key, then paste the MCP URL and key into Perplexity, Cursor, VS Code, or Claude Code.
 
-This is the **static-key** path for the consumer app's `POST /mcp`. It is not the hosted `@terreno/mcp` codegen server. For exposing tools, see [Expose MCP tools](expose-mcp-tools.md). Interactive OAuth for remote clients is a separate plan ([app MCP server](../implementationPlans/app-mcp-server.md)); do not send these keys in a query string.
+This is the **static-key** path for the consumer app's `POST /mcp`. It is not the hosted `@terreno/mcp` codegen server. For exposing tools, see [Expose MCP tools](expose-mcp-tools.md). Interactive OAuth for remote clients such as Claude.ai and ChatGPT is [Enable MCP OAuth for a JWT app](enable-mcp-oauth.md); do not send these keys in a query string.
 
 ## 1. Enable the flag
 
@@ -108,3 +108,5 @@ The token acts as the owning user on **MCP only**. It cannot mint or list tokens
 - **Admin:** Admin → MCP service tokens (`/admin/mcp-service-tokens`). Create and update are off. Delete sets `revokedAt`; it does not hard-delete the row.
 
 Revoked and expired keys fail `tools/call` immediately. Disabled user accounts are refused the same way as over HTTP.
+
+A password reset, Better Auth password change, or "sign out everywhere" (`revoke-sessions` / `revoke-other-sessions`) bumps the user's `tokenEpoch` and ends every key minted before it. The keys show as revoked in the list; mint a new one for each client you still use.