@terreno/mcp 58.0.0-beta.1 → 58.0.0-beta.3

package/src/docs/versioned/57.21.0/implementationPlans/rtk-token-source-web-bearer.md

@@ -0,0 +1,246 @@
+# One token source for @terreno/rtk, and a web bearer scheme for Better Auth
+
+Better Auth is the default for new Terreno apps, but most of `@terreno/rtk` still reads the
+legacy JWT from storage. The RTK base query, the socket hook, the chat hook, the MCP tools
+hook and offline replay all call the JWT `getAuthToken`. A Better Auth app either forks the
+base query (example-frontend and every generated app do) or gets logged out on its first
+RTK call (#1217). On web, Better Auth also needs cookies, so an app whose frontend and API
+are on different sites depends on third-party cookies that Safari blocks. Lede is
+migrating to Better Auth on two Vercel hosts and carries shims until this ships. After
+this change, an app registers one token source at startup and every rtk consumer uses it,
+and a cross-site web app can sign in, with email and password or a social provider, and
+stay signed in without any cookie.
+
+Source: #1579. Also fixes #1217.
+
+## The idea
+
+rtk gets a registered token source: `setTokenSource(source)`, typed as syncdb's
+`AuthProvider` (`getToken`, `getUserId`, `onAuthChange`, `refresh?`). rtk imports that
+type from `@terreno/syncdb`, so the object an app already builds for syncdb with
+`betterAuthAdapter(betterAuthClient)` is the same one rtk uses. Until an app registers one,
+rtk uses a built-in JWT source that wraps today's `getAuthToken` and `refreshAuthToken`, so
+JWT apps change nothing. Each consumer also takes an optional `tokenSource` override.
+
+`createBetterAuthClient` gets an opt-in `webAuth: "bearer"` mode. On web it captures the
+`set-auth-token` header that Better Auth's bearer plugin returns, stores it in
+localStorage (or a `bearerStorage` the app passes), sends `Authorization: Bearer` on every
+Better Auth client call including `getSession`, and sends no cookies
+(`credentials: "omit"`). rtk exports `getBetterAuthBearerToken()` to read that stored
+token, and syncdb's `betterAuthAdapter` takes it as an explicit `getBearerToken` option so
+it reads the token locally instead of calling `getSession()` per read. Social sign-in is a redirect, so the client never sees
+`set-auth-token`. Instead, rtk starts the sign-in with a random nonce, the server appends a
+single-use, three-minute one-time token to the callback redirect's URL fragment (only for
+configured web origins), and rtk exchanges it for the bearer on return, but only when the
+nonce matches the sign-in it started. Native is unchanged: the expo plugin already keeps the
+session without browser cookies.
+
+Rejected: passing the token source to every consumer with no global default. Hooks deep in
+the tree, like `useMCPTools`, would need it threaded through props, and it is the same
+object everywhere.
+
+## The plan
+
+| # | Task | Depends on | Lands in | Proves it |
+| --- | --- | --- | --- | --- |
+| T1 | Registered token source, used by the RTK base query | none | rtk | base query sends the registered source's token and never logs out a Better Auth user for a missing JWT (#1217) |
+| T2 | Web bearer scheme for `createBetterAuthClient` | T3 | rtk | sign-in token is stored and sent, cookies are not; sign-out clears it, a failed read does not |
+| T3 | Server accepts cookie-less bearer from another origin | none | api | cross-origin sign-in exposes the token; bearer alone reaches `/auth/me`, a model route and `/mcp` |
+| T4 | `betterAuthAdapter` takes a `getBearerToken` option | none | syncdb | with the option, `getToken` makes no `getSession` call |
+| T5 | Socket hook reads the token source | T1 | rtk | handshake re-reads the token per attempt, refreshes once per failure, reconnects on auth change |
+| T6 | Chat hook reads the token source | T1 | rtk | chat requests carry the source's token |
+| T7 | MCP tools hook reads the token source | T1 | rtk | MCP transport carries the source's current token |
+| T8 | Offline queue and replay read the token source | T1 | rtk | a Better Auth user's mutations queue and replay with the source's token |
+| T9 | Document the consumer `tokenSource` options | T5, T6, T7, T8 | docs | reference and how-to pages match the new signatures |
+| T10 | example-frontend drops its forks; bearer on web behind a flag | T1, T2, T4, T5, T7 | example-frontend | Playwright, cross-site with no cookies: email sign-in, reload, profile, socket and MCP tools work |
+| T11 | Generated apps use the token source | T1 | create-terreno-app | generated store registers `betterAuthAdapter` and drops the base-query fork |
+| T12 | Server hands a one-time token to the OAuth callback | none | api | the callback redirect to a configured web origin carries `#ott`, which verifies once into a bearer; nothing else mints one |
+| T13 | rtk exchanges the OAuth one-time token for the bearer | T2, T12 | rtk | a nonce-matched return stores the bearer; an unsolicited `#ott` is ignored |
+| T14 | Cross-site social sign-in in example-frontend | T10, T13 | example-frontend | Playwright drives a mock OIDC sign-in cross-site with no cookies and lands signed in |
+| T15 | Deployed example-frontend runs in bearer mode | T10 | CI deploy | Netlify builds set the flag; a smoke run against the PR preview signs in with no cookie |
+
+Tracer: T1, the registered source through the RTK base query.
+Out of scope: moving rtk's hooks out of rtk, admin-frontend's header getter, the missing `/api/chat` route (see Expansions).
+Open risks: the one-time token travels in a URL fragment, which servers, access logs and `Referer` never see, but browser history and client-side scripts loaded before the strip could; it is single-use, expires in three minutes, is checked by the web app against a `handoff=` nonce it stored (which stops a planted token, not a stolen one), and goes only to an exactly listed path (`oauthHandoff.callbackPaths`, default `/`) on a configured web origin. Because a browser carries the fragment through a redirect that has none, that page must strip the fragment first and never redirect; an open redirect elsewhere on the origin cannot receive the token. A localStorage token can be read by an XSS on the frontend and outlives browser restarts, which matters on shared family devices. Bearer mode is opt-in, `bearerStorage` accepts sessionStorage, and the docs say when to use which.
+
+## Tasks
+
+- [x] **T1** — Register a token source and use it in the RTK base query
+  - Depends on: none
+  - Files: rtk/package.json, rtk/src/tokenSource.ts, rtk/src/tokenSource.test.ts, rtk/src/authEvents.ts, rtk/src/authSlice.ts, rtk/src/emptyApi.ts, rtk/src/isolated/emptyApi.staggered.isolated.ts, rtk/src/index.ts, docs/reference/legacy/rtk.md, plugins/terreno-planning/skills/terreno-data-fetching/references/auth-and-tokens.md, skills/terreno-data-fetching/references/auth-and-tokens.md, plugins/terreno-claude/skills/terreno-data-fetching/references/auth-and-tokens.md, changelog/unreleased/rtk-token-source.md
+  - Behavior: `setTokenSource(source)` and `getTokenSource()` are exported from `@terreno/rtk`; `AuthProvider` is imported as a type from `@terreno/syncdb`, added as a `workspace:*` dependency. Seams, chosen so rtk stays cycle-free: `tokenSource.ts` is a leaf that holds the registered source (`undefined` until an app registers one) and imports nothing from rtk. `authEvents.ts` is a leaf emitter that the `authSlice.ts` login and logout listeners and `refreshAuthToken` call. `emptyApi.ts` exports `jwtTokenSource` (`getToken` is `getAuthToken`, `refresh` is `refreshAuthToken` resolving `true` on success, `getUserId` reads the JWT `sub`, `onAuthChange` subscribes to `authEvents`) for apps that want to register it explicitly. Every consumer treats "no source registered" or `jwtTokenSource` as today's JWT path, so JWT apps run the same code. `staggeredBaseQuery` keeps its exact JWT behavior on that path. With any other source it sends that source's token, sends the request with no `authorization` header when the token is null, and never dispatches `auth/logout` for a missing token. On a 401 it calls `refresh()` once and retries, and dispatches `auth/logout` only when the retry is also 401.
+  - Acceptance:
+    - With a fake `AuthProvider` registered and no JWT in storage, a query sends `authorization: Bearer <fake token>` and dispatches no `auth/logout`. Verification: new case in `rtk/src/isolated/emptyApi.staggered.isolated.ts`; fails on master (logout dispatched), passes on the branch.
+    - With a fake source, a 401 then a 200 calls `refresh` once and returns the 200; two 401s dispatch `auth/logout`. Verification: `rtk/src/isolated/emptyApi.staggered.isolated.ts`.
+    - Existing JWT base-query tests pass unchanged, and the default source's `getToken` and `refresh` delegate to `getAuthToken` and `refreshAuthToken`. Verification: `cd rtk && bun test ./src/isolated/emptyApi.isolated.ts && bun test ./src/isolated/emptyApi.staggered.isolated.ts && bun test src/tokenSource.test.ts` (each file its own process; `tokenSource.test.ts` uses no module mocks, otherwise it moves under `isolated/`).
+    - rtk coverage stays at or above its 95% threshold. Verification: `cd rtk && bun run test:coverage`.
+    - Generated skill copies match, and dependency-cruiser finds no new cycle. Verification: `bun run skills:sync && bun run skills:check && bun run analyze:full`.
+  - Docs: `docs/reference/legacy/rtk.md` gets a token-source section. Its Better Auth slice snippet and the skill's `auth-and-tokens.md` contradict the code (`{sessionReducer, sessionMiddleware}` and a nonexistent `basePath`); fix them here because the new section sits next to them.
+  - Skills: terreno-data-fetching, update-docs.
+- [x] **T2** — Add a web bearer scheme to createBetterAuthClient
+  - Depends on: T3
+  - Files: rtk/src/betterAuthClient.ts, rtk/src/betterAuthTypes.ts, rtk/src/betterAuthClient.test.ts, docs/how-to/configure-better-auth.md, docs/explanation/authentication.md, docs/how-to/migrate-rtk-to-syncdb.md, changelog/unreleased/better-auth-web-bearer.md
+  - Behavior: `BetterAuthClientConfig` gains `webAuth?: "cookie" | "bearer"` (default `"cookie"`) and `bearerStorage?: {getItem, setItem, removeItem}` (default `window.localStorage`, key `${storagePrefix}_bearer_token`). With `"bearer"` on web, the client passes `fetchOptions` with: `credentials: "omit"`; `onSuccess` that stores a `set-auth-token` response header, and clears the stored token after a successful `get-session` response whose body has no session, but only when the token that request sent equals the token stored now; `auth: {type: "Bearer", token: () => stored token}`. A failed or errored `get-session` leaves the token in place. Calling `signOut` clears the stored token locally before the request, whatever the response, so a failed sign-out never leaves a usable token on the device. rtk exports `getBetterAuthBearerToken({storagePrefix?, bearerStorage?}): string | null`, which reads the same key. Nothing is added to the client object: `createAuthClient` returns a route proxy, so an added property would be unreadable and `client.getBearerToken` already resolves to a `/get-bearer-token` request. On native, or with `"cookie"`, the options passed to `createAuthClient` are unchanged.
+  - Acceptance:
+    - On web with `webAuth: "bearer"`, `onSuccess` with a `set-auth-token: t1` response stores `t1`; `fetchOptions.auth.token()` and `getBetterAuthBearerToken()` return `t1`; `fetchOptions.credentials` is `"omit"`. Verification: `rtk/src/betterAuthClient.test.ts` against the captured `createAuthClient` options.
+    - A sign-out clears the token even when its request fails or returns 5xx. A successful `get-session` with a null session clears it, unless a newer token was stored while that request was in flight. A `get-session` that errors or returns 5xx keeps it. Verification: `rtk/src/betterAuthClient.test.ts`.
+    - A custom `bearerStorage` is used instead of localStorage. Verification: `rtk/src/betterAuthClient.test.ts`.
+    - On native, or without `webAuth`, the captured options equal today's. Verification: existing `createBetterAuthClient` tests pass unchanged.
+  - Docs: `configure-better-auth.md` gets "Frontend and API on different sites": when to use bearer, that it sends no cookies so the server's `corsOrigin` default works and the bearer plugin exposes `set-auth-token` itself (both proved by T3), the XSS and shared-device trade-off, and `sessionStorage` for shared devices. Its slice snippet and the missing required `scheme` contradict the code; fix them in this section's neighbourhood. `authentication.md:39` and `:311` describe bearer on web as the cross-site option. `migrate-rtk-to-syncdb.md:336` stops saying web tokens live in AsyncStorage.
+  - Skills: update-docs.
+- [x] **T3** — Accept a cookie-less bearer from another origin on the server
+  - Depends on: none
+  - Files: api/src/betterAuthApp.test.ts
+  - Behavior: with `TerrenoApp` and `BetterAuthApp`, both with the default `corsOrigin` (`"*"`) and with an explicit one, a cross-origin `POST /api/auth/sign-in/email` sent without credentials returns `set-auth-token` and lists it in `access-control-expose-headers`. A later request carrying only `Authorization: Bearer <that token>` and no cookie reaches `GET /auth/me` as the user, an authenticated `modelRouter` list route returns 200, and `POST /mcp` `initialize` succeeds. If any of these fails, the task fixes the server (for example `exposedHeaders` in `api/src/terrenoApp.ts`) and adds that file.
+  - Acceptance: the cases pass. Verification: `cd api && bun test src/betterAuthApp.test.ts`.
+  - Skills: terreno-backend-api.
+- [x] **T4** — Take a getBearerToken option in betterAuthAdapter
+  - Depends on: none
+  - Files: syncdb/src/auth/betterAuthAdapter.ts, syncdb/src/auth/betterAuthAdapter.test.ts, docs/reference/syncdb.md, changelog/unreleased/syncdb-adapter-bearer-token.md
+  - Behavior: `BetterAuthAdapterOptions` gains `getBearerToken?: () => string | null`. When it is passed and returns a token, `getToken` returns that token without calling `getSession()`. Otherwise `getToken` behaves as today. `getUserId`, `onAuthChange` and `refresh` are unchanged. The option is explicit, never detected on the client, so the bridged client from `bridgeBetterAuthReactClient` needs no change.
+  - Acceptance: with `getBearerToken` returning `t1`, `getToken()` resolves `t1` and the fake client's `getSession` is not called; without the option, or with it returning null, `getSession` is read as today. Verification: `cd syncdb && bun test src/auth/betterAuthAdapter.test.ts`.
+  - Docs: `docs/reference/syncdb.md` adapter section.
+- [x] **T5** — Read the token source in useSocketConnection
+  - Depends on: T1
+  - Files: rtk/src/socket.ts, rtk/src/isolated/socket.web.isolated.ts, changelog/unreleased/rtk-socket-token-source.md
+  - Behavior: `getAuthToken` becomes optional. Without it, the hook reads the token source (the `tokenSource` option, else the registered one). The socket's `auth` is a callback that reads the token on every connect and reconnect. On an auth `connect_error` it calls `refresh()` once per failure episode and reconnects; a second auth failure before a successful connect stops reconnecting and calls `onConnectError`. A successful connect resets the episode. It reconnects when `onAuthChange` fires. The JWT expiry check stays as it is while the JWT source is registered.
+  - Acceptance:
+    - With a registered fake source and no `getAuthToken`, the handshake sends `Bearer <token>`; after the token changes and `onAuthChange` fires, the next handshake sends the new token. Verification: `rtk/src/isolated/socket.web.isolated.ts`.
+    - When `refresh` resolves true but the server keeps rejecting the token, the hook refreshes once and stops. Verification: same file.
+    - Passing `getAuthToken` keeps today's behavior, and existing socket tests pass. Verification: `cd rtk && bun test ./src/isolated/socket.isolated.ts && bun test ./src/isolated/socket.web.isolated.ts && bun test src/socket.test.ts`.
+  - Docs: JSDoc on the new options (feeds the generated reference); prose in T9.
+- [x] **T6** — Read the token source in useTerrenoChat
+  - Depends on: T1
+  - Files: rtk/src/useTerrenoChat.ts, rtk/src/isolated/useTerrenoChat.isolated.ts, changelog/unreleased/rtk-chat-token-source.md
+  - Behavior: the transport `headers` callback reads the token source (`tokenSource` option, else the registered one) per request, and omits `Authorization` when there is no token.
+  - Acceptance: with a registered fake source, the headers callback returns `Authorization: Bearer <token>`; with a null token it returns none. Verification: `cd rtk && bun test ./src/isolated/useTerrenoChat.isolated.ts`.
+  - Docs: JSDoc on the new option; prose in T9.
+- [x] **T7** — Read the token source in useMCPTools
+  - Depends on: T1
+  - Files: rtk/src/useMCPTools.ts, rtk/src/isolated/useMCPTools.isolated.ts, changelog/unreleased/rtk-mcp-token-source.md
+  - Behavior: the MCP transport's `authProvider.token` reads the token source (`tokenSource` option, else the registered one) on each call instead of capturing one token per fetch.
+  - Acceptance: with a registered fake source, `authProvider.token()` resolves to the source's current token, including after it changes. Verification: `cd rtk && bun test ./src/isolated/useMCPTools.isolated.ts`.
+  - Docs: JSDoc on the new option; prose in T9.
+- [x] **T8** — Read the token source in the offline queue and replay
+  - Depends on: T1
+  - Files: rtk/src/offlineMiddleware.ts, rtk/src/isolated/offlineMiddleware.isolated.ts, changelog/unreleased/rtk-offline-token-source.md
+  - Behavior: with a non-JWT source (`OfflineMiddlewareConfig.tokenSource`, else the registered one), the middleware tags and filters queued mutations by the source's `getUserId()` instead of `state.auth.userId` (`offlineMiddleware.ts:142-152, 541, 641`), and `replayMutation` sends the source's token, omitting `authorization` when there is none. On the JWT path it behaves as today.
+  - Acceptance: with a registered fake Better Auth source and no `state.auth` slice, a mutation made offline is queued under the source's user id and, on reconnect, replayed with `authorization: Bearer <token>`. Verification: `cd rtk && bun test ./src/isolated/offlineMiddleware.isolated.ts`; existing offline tests pass.
+  - Docs: JSDoc on the new option; prose in T9.
+- [x] **T9** — Document the token-source options on rtk's consumers
+  - Depends on: T5, T6, T7, T8
+  - Files: docs/reference/legacy/rtk.md, docs/how-to/websocket-integration.md
+  - Behavior: `legacy/rtk.md` stops calling `getAuthToken` required and JWT-only (`:165`), and documents `tokenSource` on the socket, chat, MCP and offline APIs. `websocket-integration.md:146-165` describes the registered source. The generated rtk reference is built from JSDoc at docs-site build time, so it needs no edit.
+  - Acceptance: every option named on the pages exists in the exported signatures, and the docs site builds with the generated rtk reference. Verification: `cd website && bun run build` succeeds, and the docs-audit skill reports no rtk drift.
+  - Skills: update-docs, docs-audit.
+- [x] **T10** — Use the token source in example-frontend, with web bearer behind a flag
+  - Depends on: T1, T2, T4, T5, T7
+  - Files: example-frontend/lib/betterAuth.ts, example-frontend/store/adminAuthHeaders.ts (renamed from store/betterAuthApi.ts), example-frontend/store/index.ts, example-frontend/store/syncdb.ts, example-frontend/openapi-config.ts, example-frontend/store/openApiSdk.ts, example-frontend/app/_layout.tsx, example-frontend/app/admin/_layout.tsx, example-frontend/e2e/crossSiteBearer.spec.ts, example-frontend/e2e/helpers/syncdbSuite.ts, example-frontend/playwright.config.ts, example-frontend/.env.example
+  - Behavior: the app registers the `authProvider` it already builds in `store/syncdb.ts` (`betterAuthAdapter(bridgeBetterAuthReactClient(betterAuthClient), ...)`, now with `getBearerToken: getBetterAuthBearerToken`) with `setTokenSource` at startup. It turns on `webAuth: "bearer"` on web when `EXPO_PUBLIC_BETTER_AUTH_WEB_BEARER=true`; T15 sets the flag in the Netlify builds (D6). The generated SDK points back at rtk's `emptySplitApi`, and the old `store/betterAuthApi.ts` becomes `store/adminAuthHeaders.ts`, holding only `getAdminAuthHeaders`, which reads the token source. `_layout.tsx` stops passing its own `getAuthToken` to `useSocketConnection`.
+  - Acceptance:
+    - A Playwright project runs the web app at `localhost:8082` against the API at `127.0.0.1:4000` (different sites) with the flag on. The test strips `set-cookie` from API responses, signs in through the UI, asserts `context.cookies()` holds no Better Auth session cookie, reloads, and sees the profile screen load (`useGetMeQuery`), the socket connect, and the AI tab's MCP tools load. Verification: `cd example-frontend && bunx playwright test e2e/crossSiteBearer.spec.ts`; it fails on master.
+    - The `useMCPTools error` console allowance is removed and the existing Better Auth suites pass: login, signup, profile, realtime, ai-chat. Verification: `bun run check:e2e-affected` then the affected shards.
+    - Screenshots of the signed-in profile and AI tab after the reload are saved to `/opt/cursor/artifacts/` and attached to the PR. Verification: verify-ui-changes skill.
+  - Skills: generate-sdk, verify-ui-changes, terreno-data-fetching.
+- [x] **T11** — Generate apps that register the token source
+  - Depends on: T1
+  - Files: create-terreno-app/src/generate.ts, create-terreno-app/src/__tests__/generate.test.ts, changelog/unreleased/cta-token-source.md
+  - Behavior: the generated store registers its existing bridged `authProvider` (`generate.ts:2544-2564`) with `setTokenSource`, the generated codegen config points at rtk's `emptySplitApi`, and `store/betterAuthApi.ts` (with its `readSessionToken` fork) is no longer generated. The generated client keeps cookie mode.
+  - Acceptance:
+    - Generator tests assert the registration and the codegen target, and that no `betterAuthApi.ts` is emitted. Verification: `cd create-terreno-app && bun test src/`.
+    - A generated app type-checks against the workspace packages. Verification: generate into a temp dir, link `node_modules`, run `tsc -p frontend/tsconfig.json`.
+
+- [x] **T12** — Hand a one-time token to the OAuth callback on the server
+  - Depends on: none
+  - Files: api/src/betterAuth.ts, api/src/betterAuthSetup.ts, api/src/betterAuthOAuthHandoff.ts, api/src/betterAuthOAuthHandoff.test.ts, api/src/rateLimit/policies.ts, api/src/rateLimit/rateLimit.test.ts, docs/how-to/rate-limiting.md, changelog/unreleased/better-auth-oauth-handoff.md
+  - Behavior: `BetterAuthConfig` gains `oauthHandoff?: {webOrigins: string[]}` (unset by default). When set, `createBetterAuth` adds Better Auth's `oneTimeToken` plugin with `expiresIn: 3`, `storeToken: "hashed"`, `disableClientRequest: true` and `setOttHeaderOnNewSession` off, then a Terreno plugin whose after-hook matches only `ctx.path?.startsWith("/callback/")` (social and generic OAuth share `/callback/:id` in 1.7.4). When the callback created a session (`ctx.context.newSession`), the hook reads the redirect `Location`, which must be an absolute http(s) URL already in the URL parser's normal form (relative locations are refused, not resolved). If its origin exactly equals an http(s) origin in `webOrigins` and its `pathname` exactly equals one of `oauthHandoff.callbackPaths` (default `["/"]`; the query is free, so `handoff=` works; entries must be absolute, normalized paths, checked at startup), it mints a token with `auth.api.generateOneTimeToken` (server-side, headers `authorization: Bearer <new session token>`) and appends `ott=<token>` to the `Location` fragment. App schemes (`exp://`, `terreno://`), relative paths and the API's own origin never get a token. `POST /api/auth/one-time-token/verify` returns the session with `set-auth-token`, once. Because Better Auth's OAuth state check needs a cookie that a cross-site `POST /sign-in/social` fetch cannot keep, the plugin also serves `GET /api/auth/oauth-handoff/start?provider&callbackURL[&errorCallbackURL]`: a top-level navigation that checks each URL against `webOrigins` and `trustedOrigins` (400, no redirect, otherwise), starts the flow through `signInSocial` server-side, sets the state cookie first-party on the API origin, and redirects to the provider (decided by the parent after review, attempt 2). The start endpoint applies the same exact-path rule to `callbackURL`; `errorCallbackURL` is checked by origin only, since an error redirect never carries a token. The handed-off callback redirect drops the session cookies it set on the API origin (and the `set-auth-token` header), and verify drops its Set-Cookie while keeping `set-auth-token` (attempt 3).
+  - Acceptance:
+    - With `oauthHandoff.webOrigins` set and a local mock OIDC provider registered through `plugins` (`genericOAuth`), completing the flow with a `callbackURL` on a listed web origin redirects with `#ott=` in `Location`. Verifying it returns `set-auth-token`; a second verify fails. Verification: `cd api && bun test src/betterAuthOAuthHandoff.test.ts`.
+    - A `callbackURL` that passes Better Auth's origin check but is not a listed web origin (an `exp://` scheme in `trustedOrigins`, a relative path, the API origin) gets no `ott`. Verification: same file.
+    - The client route `GET /one-time-token/generate` is refused; email sign-in and verify responses carry no `set-ott` header; with `oauthHandoff` unset, no `/one-time-token/*` route exists. Verification: same file.
+  - Docs: in T13 (the same page).
+  - Skills: terreno-backend-api.
+- [x] **T13** — Exchange the OAuth one-time token for the bearer in rtk
+  - Depends on: T2, T12
+  - Files: rtk/src/betterAuthClient.ts, rtk/src/betterAuthClient.test.ts, rtk/src/isolated/betterAuthClient.native.isolated.ts, docs/how-to/configure-better-auth.md, docs/reference/legacy/rtk.md, changelog/unreleased/better-auth-web-bearer-oauth.md
+  - Behavior: rtk exports `signInSocialWithHandoff({client, provider, callbackURL?, errorCallbackURL?})`, which stores a random nonce in sessionStorage and navigates the page top-level (`window.location.assign`) to T12's `GET <baseURL><basePath>/oauth-handoff/start?provider=…&callbackURL=…&errorCallbackURL=…`, with a `callbackURL` on one of the server's `callbackPaths` (default `/`) that carries `handoff=<nonce>` in its query (D7). A top-level start keeps Better Auth's OAuth state cookie first-party on the API origin. It also exports `completeBetterAuthOAuthHandoff({client}): Promise<boolean>`. On web in bearer mode, when the URL fragment has `ott` and the `handoff` query equals the stored nonce, it removes `ott`, `handoff` and the stored nonce first (`history.replaceState`), then POSTs the token to `/one-time-token/verify`; T2's `onSuccess` stores the bearer. A missing or mismatched nonce drops `ott` from the URL and makes no request. It resolves `true` only when a token was stored. Apps await it before anything reads the session, before any code acts on other query parameters, and before Sentry or analytics start. A return with `?error=provider_not_found|sign_in_failed` resolves `false` and leaves the error for the app to show.
+  - Acceptance:
+    - After `signInSocialWithHandoff`, a URL with the matching `handoff` and `#ott=abc` makes the function strip both before the request, call verify with `abc`, and leave `t2` stored from a `set-auth-token: t2` response. Verification: `rtk/src/betterAuthClient.test.ts`.
+    - An unsolicited `#ott` (no stored nonce, or a different one) makes no request and stores nothing. Without `ott`, on native, or in cookie mode, no request is made. A failed verify resolves `false`. Verification: same file.
+    - A null-session `get-session` that was sent before verify finished does not clear the token verify stored. Verification: same file, with the two responses resolved in that order.
+    - `ott` is removed from the URL before verify is sent and before the function returns, even when the callback URL carries other query parameters such as `next=`. Verification: same file.
+    - `signInSocialWithHandoff` navigates to the start endpoint with an encoded `callbackURL` carrying the nonce. Verification: same file.
+  - Docs: `configure-better-auth.md` "Frontend and API on different sites" covers social sign-in: `oauthHandoff: {webOrigins}` on the server, `signInSocialWithHandoff` for the buttons, and awaiting `completeBetterAuthOAuthHandoff` at startup before session reads and Sentry.
+  - Skills: update-docs.
+- [x] **T14** — Run cross-site social sign-in in example-frontend
+  - Depends on: T10, T13
+  - Files: example-frontend/lib/betterAuth.ts, example-frontend/lib/oauthHandoff.ts, example-frontend/lib/oauthHandoffUrl.ts, example-frontend/lib/oauthErrorMessage.ts, example-frontend/index.js, example-frontend/app/_layout.tsx, example-frontend/app/login.tsx, example-frontend/app/signup.tsx, example-frontend/e2e/crossSiteOAuth.spec.ts, example-frontend/e2e/helpers/mockOidcProvider.ts, example-frontend/e2e/helpers/crossSiteApi.ts, example-frontend/playwright.config.ts, example-backend/src/utils/betterAuthConfig.ts
+  - Behavior: with the bearer flag on, the social buttons use `signInSocialWithHandoff`, and the app's entry (`index.js`) runs `completeBetterAuthOAuthHandoff` before Expo Router loads, since Expo Router copies the URL when imported and writes it back (built: `lib/oauthHandoffUrl.ts` hides the handoff, `lib/oauthHandoff.ts` restores and exchanges it in one synchronous step); `_layout.tsx` syncs the session only after it resolves, and nothing starts Sentry in this app. example-backend sets `oauthHandoff.webOrigins` from `getWebOrigins()` (and `callbackPaths` for the app's return page) when `BETTER_AUTH_OAUTH_HANDOFF=true`, and registers a `genericOAuth` provider only when `MOCK_OIDC_ISSUER` is set (never in production). Playwright starts the mock OIDC provider as a web server.
+  - Acceptance:
+    - Cross-site (`localhost:8082` to `127.0.0.1:4000`), with `set-cookie` stripped from API responses, clicking the mock provider's button completes the redirect and lands signed in. `ott` is gone from the URL and `context.cookies()` holds no Better Auth session cookie. Verification: `cd example-frontend && bunx playwright test e2e/crossSiteOAuth.spec.ts`.
+    - Opening the app with a made-up `#ott=` does not sign in. Verification: same file.
+    - A screenshot of the signed-in page after the return is saved to `/opt/cursor/artifacts/` and attached to the PR. Verification: verify-ui-changes skill.
+  - Skills: verify-ui-changes.
+
+- [x] **T15** — Deploy example-frontend in bearer mode
+  - Depends on: T10
+  - Files: scripts/ci/netlify-deploy.sh, scripts/ci/netlify-deploy.test.ts, .circleci/continue-config.yml, example-frontend/e2e/deployedBearer.smoke.ts, example-frontend/playwright.smoke.config.ts, example-frontend/package.json, docs/how-to/run-tests-locally.md
+  - Behavior: `netlify-deploy.sh frontend` exports `EXPO_PUBLIC_BETTER_AUTH_WEB_BEARER=true` before `bun run export`, for production and previews. The backends keep `CROSS_DOMAIN_AUTH_COOKIES=true`, so a browser still holding an old cookie build keeps working until it reloads. `deploy-frontend-preview` then runs `bun run smoke:deployed` with `SMOKE_BASE_URL=https://pr-<n>--terreno-frontend.netlify.app`: a Playwright config with no web servers and one spec that signs up a fresh `smoke-<run id>@example.com` user on the PR's isolated preview backend through the UI, reloads, sees the profile screen load, and asserts `context.cookies()` for the API origin holds no Better Auth session cookie. Production deploys only build with the flag: the smoke never creates users on the prod backend.
+  - Acceptance:
+    - The frontend build step exports the flag before `bun run export`, for both modes. Verification: a `scripts/ci/netlify-deploy.test.ts` case that runs the script with `bun run export` stubbed and asserts the stub saw `EXPO_PUBLIC_BETTER_AUTH_WEB_BEARER=true`.
+    - The smoke spec passes against a local cross-site stack (`SMOKE_BASE_URL=http://localhost:8082`, API at `127.0.0.1:4000`). Verification: `cd example-frontend && SMOKE_BASE_URL=http://localhost:8082 bun run smoke:deployed`.
+    - On the PR, the `deploy-frontend-preview` CircleCI job runs the smoke after the deploy and it passes. Verification: the job's log on the PR head.
+  - Docs: `run-tests-locally.md` maps the new CircleCI step to its local command.
+  - Skills: verify-ui-changes.
+
+## Assumptions
+
+- `@terreno/syncdb` has no `@terreno/*` dependencies, so `rtk → syncdb` adds no cycle. Both are lockstep-versioned.
+- No Redux shape changes for auth: the JWT `onAuthChange` comes from the `authEvents.ts` emitter, not from state. T8 adds optional fields to the offline slice (`lastUserId`, and `userIdConfirmed` on queued mutations) so mutations made after an offline launch keep their user; they are additive.
+- The registered source is module-global, like rtk's existing `baseUrl`. One app, one source.
+- Changelog fragments are `Added` or `Fixed`, except `cta-token-source.md` (`Changed`: generated apps now log out after a 401 survives one refresh, and drop `store/betterAuthApi.ts`). Its migration steps feed the next release's upgrade note, which `bun run check:upgrade-docs` requires.
+- T1 also orders `syncdb` before `rtk` in the CI compile lists (`.circleci/*.yml`, `.github/workflows/admin-spa-ci.yml`) and maps `syncdb/src` changes to `run-rtk`, because rtk's types now import syncdb's.
+- The cross-site Playwright specs (T10, T14) run locally only (`cross-site-bearer` shard, `blocksPullRequest: false`): CircleCI builds one cookie-mode web export for all shards. In CI, bearer mode is covered by T15's deployed-preview smoke.
+- The bearer plugin exposes `set-auth-token` itself on responses that set a session (`node_modules/better-auth/dist/plugins/bearer/index.mjs:62-65`); T3 proves it from another origin.
+- The OAuth handoff hook mints its own token through `auth.api.generateOneTimeToken`; `setOttHeaderOnNewSession` stays off because it fires on every new session, including email sign-in and verify (`node_modules/better-auth/dist/plugins/one-time-token/index.mjs:89-100`). After-hooks run on the callback's thrown redirect, and a hook can rewrite `Location`, as `oauthPopup` does.
+- T9 is a docs join: the prose pages are shared by T5–T8, so one task writes them after all four land. Each of T5–T8 ships its own JSDoc and changelog fragment.
+
+## Open questions (recommendation assumed)
+
+| ID | Question | Recommendation | Why | If answered differently | Tasks affected |
+| --- | --- | --- | --- | --- | --- |
+| Q1 | Is the web bearer scheme opt-in, or on by default on web? | Opt-in with `webAuth: "bearer"` | The issue asks for opt-in; same-site apps keep HttpOnly cookies, which an XSS cannot read | Default flips to `"bearer"` on web: T2's default and tests change, and the change becomes `Changed` with an upgrade note | T2, T10 |
+| Q2 | Does this plan also close #1217? | Yes | #1579 names the base query as a consumer, and T1's test is #1217's repro | T1 drops the base-query change and only adds the registry; #1217 stays open | T1, T10, T11 |
+| Q3 | With a non-JWT source, what does the base query do when the token is null? | Send the request without auth and let the server answer; log out only after a 401 survives one refresh | The #1217 bug is exactly the client deciding "logged out" on its own | Dispatch `auth/logout` on a null token, as JWT does: T1's first acceptance case inverts | T1 |
+
+## Expansions (follow up later)
+
+| ID | Idea | Why it came up | Rough size | Depends on |
+| --- | --- | --- | --- | --- |
+| X1 | Move the token source and hooks out of rtk before the next major | `versioning-policy.md:21`: rtk does not ship in the next major | M | T1–T8 |
+| X2 | admin-frontend's `AdminGetAuthHeaders` reads the token source by default | It is another hand-rolled token getter | S | T1 |
+| X3 | `useTerrenoChat`'s default `/api/chat` route does not exist on any backend | Found while tracing chat auth; T6 proves the header, not a live chat | S | T6 |
+| X4 | `createSessionApi` uses `credentials: "same-origin"`, so it cannot work cross-site | Found while tracing cookies | S | none |
+| X5 | Move the deployed example-frontend and API onto same-site custom domains (first-party `SameSite=Lax` cookies) | Q4 trade-offs: neither cross-site cookies nor bearer is the production best practice | S (about half a day, DNS plus deploy config) | none |
+| X6 | syncdb's `betterAuthAdapter` marks its first-load emission so rtk's offline queue can tell it from a sign-in | T8 drops unconfirmed offline-launch writes on any `onAuthChange`, including the adapter's first successful load | S | T8 |
+| X7 | rtk's base-query response handler null-checks a JSON `null` body before reading `more` | The removed example-frontend and generated forks did; no endpoint returns `null` today | S | T10, T11 |
+| X8 | A CircleCI job (nightly or path-gated) that runs the cross-site specs with a bearer-mode export | The handoff browser flow (hide before Expo Router, nonce, strip, verify) only runs locally | S | T10, T14 |
+| X9 | When create-terreno-app gains a bearer option, emit the pre–Expo Router `ott` guard (as example-frontend `index.js` does) or ship one rtk startup helper | Expo Router copies the URL fragment on import, so bearer social sign-in needs an entry-file step today | S | T11, T14 |
+
+## Decisions
+
+| ID | Question asked | Answer | What it changes |
+| --- | --- | --- | --- |
+| D1 | Where does the token-source API live? | Import syncdb's `AuthProvider` type into rtk | rtk depends on `@terreno/syncdb`; syncdb's `betterAuthAdapter` is the Better Auth source, so rtk writes no Better Auth source of its own |
+| D2 | Where does the web bearer scheme store the token? | localStorage by default, with a `bearerStorage` option | T2's default storage; docs state the XSS and shared-device trade-off |
+| D3 | How do apps give rtk the token source? | Register once with `setTokenSource`, JWT by default, optional per-consumer override | Every consumer task reads the registry first |
+| D4 | Q5: Should bearer mode cover social OAuth sign-in in this plan? | Yes, add the handoff (recommendation was to document the limit) | Adds T12 (server one-time token on the callback, web origins only), T13 (nonce-bound rtk exchange) and T14 (cross-site mock-OIDC Playwright run) |
+| D5 | Approve the plan? | Approved 2026-10-20, with D4 | Status: approved after cut checked the D4 tasks |
+| D6 | Q4: Should the deployed example-frontend switch to bearer mode? | Yes, deploy bearer (recommendation was flag-only) | Adds T15: Netlify builds set the flag, and the PR preview runs a cookie-less sign-in smoke |
+| D7 | Build-time: a cross-site `POST /sign-in/social` loses Better Auth's OAuth state cookie (third-party), so the callback fails with `state_mismatch` | Start the flow with a top-level `GET /oauth-handoff/start` instead of skipping the state check; the ott goes only to exact `callbackPaths` on listed web origins | T12 adds the start endpoint and `callbackPaths`; T13 navigates to it; T14 configures `callbackPaths` |
+| D8 | Build-time: the bearer build's social buttons go to `/oauth-handoff/start`, which 404s unless the deployed backend enables the handoff | Enable `BETTER_AUTH_OAUTH_HANDOFF=true` on the deployed example-backend (prod and previews), with loopback origins excluded from the handoff in production; follows from D4 + D6 | T15 also edits `scripts/ci/gcp-deploy.sh` and example-backend config; the smoke checks the start link redirects |
+
+## Sign-off
+
+Status: approved 2026-10-20
+Cut: 3 rounds (the third on the D4 tasks), 28 findings: 26 fixed, 1 moved to questions then decided (social OAuth → Q5 → D4), 1 rebutted in part (round 1 F11: the slice-snippet fixes stay, because distill must resolve docs that contradict the code in the affected area)

package/src/docs/versioned/57.21.0/plans/2026-10-23-provisional-consent.md

@@ -0,0 +1,297 @@
+# Provisional consent signing
+
+Terreno's consent system today lets a user sign only for themselves: `ConsentNavigator` blocks
+the app until the user agrees to every pending form, and admins can only read responses. Apps
+such as Flourish need staff to record consent ahead of the user, for example after verbal
+consent from a guardian at intake, so the form counts as signed for compliance while the user
+still sees it and signs it themselves. This plan adds that provisional signature to the
+consent API, ships an exported UI component apps can drop into any screen, and makes consent
+printouts show the provisional signature.
+
+## The idea
+
+A `ConsentResponse` can now be **provisional**: `agreed: true`, `provisional: true`, signed by
+another user (`provisionalSignedBy`), at a time (`agreedAt`), with a required free-text note
+(`provisionalNote`). A new RBAC action, `consentResponse:signOnBehalf`, controls who may
+create one. A provisional response counts as signed in `getConsentStatuses`, a new server helper
+and endpoint. It does **not** clear the form from `/consents/pending`, so the user still
+meets the form in the gate, now with a "Signed on your behalf by <name> on <date>" notice.
+The user's own answer always wins: agreeing makes the status `signed`, and declining makes it
+`declined`. Both records stay for audit. A provisional signature made in error can be voided,
+with the void kept on record.
+
+`@terreno/ui` exports `ProvisionalConsentSigner`: given a target `userId`, it lists that user's
+forms with status and lets the signer read a form, fill in the note box, and sign it
+provisionally. Consent printouts (a new print action, plus the existing PDF downloads)
+include a "Provisional signature" block.
+
+Rejected: a separate `ProvisionalConsent` model. A field on `ConsentResponse` keeps one audit
+trail per user and reuses the existing admin screens, populate paths, and PDF code.
+
+## The plan
+
+| # | Task | Depends on | Lands in | Proves it |
+| --- | --- | --- | --- | --- |
+| T1 | Provisional sign endpoint + RBAC (tracer) | none | api | `bun test api/src/consentApp.test.ts api/src/rbac` |
+| T2 | Provisional notice data on user-facing payloads | T1 | api | `bun test api/src/consentApp.test.ts` |
+| T3 | `getConsentStatuses` helper + status endpoint + admin columns + SDK | T2 | api, example-frontend SDK | `bun test api/src/consentStatus.test.ts api/src/consentApp.test.ts` |
+| T4 | Void a provisional signature | T3 | api | `bun test api/src/consentApp.test.ts` |
+| T5 | Provisional notice in the consent gate | none | ui | `bun test ui/src/ConsentFormScreen.test.tsx` |
+| T6 | `ProvisionalConsentSigner` status list + hook | none | ui | `bun test ui/src/ProvisionalConsentSigner.test.tsx` |
+| T7 | Sign flow with note box in `ProvisionalConsentSigner` | T6 | ui | same |
+| T8 | Print helper + provisional block in PDF template | none | ui | `bun test ui/src/pdfHtmlTemplate.test.ts` |
+| T9 | Provisional block in admin-frontend PDF generators | T8 | admin-frontend | `bun test admin-frontend/src` (PDF + isolated) |
+| T10 | Print buttons + provisional display in admin and user consent views | T9 | admin-frontend | `bun test admin-frontend/src/Consent*.test.tsx` |
+| T11 | Print and void buttons in `ProvisionalConsentSigner` | T7, T8 | ui | `bun test ui/src/ProvisionalConsentSigner.test.tsx` |
+| T12 | Example app routes + backend wiring + E2E (admin and RBAC staff) | T4, T5, T11 | example-backend, example-frontend | `bun run frontend:e2e -- provisionalConsent.spec.ts` + screenshots |
+| T13 | UI, admin, how-to docs + changelog | T10, T12 | docs, changelog | `bun run check:changelog`, `bun run check:knip`, docs-audit skill |
+
+Tracer: `POST /consent-responses/provisional` → `ConsentResponse{provisional: true}` → form still in `/consents/pending`.
+Out of scope: printing blank forms, bulk provisional signing, org or relationship scoping of who can sign for whom (see Expansions).
+Open risks: staff with `signOnBehalf` can list any user's consent statuses. You chose RBAC with no relationship check, so these reads and writes are audited (T1, T3) when `AuditApp` is registered.
+
+## Contracts
+
+### Model: `ConsentResponse` (additive, no migration)
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `provisional` | `Boolean`, default `false` | `true` only on responses created by `/consent-responses/provisional` |
+| `provisionalSignedBy` | `ObjectId` ref `User` | The signer. Required when `provisional` |
+| `provisionalNote` | `String` | Required, trimmed, non-empty, max 2000 chars when `provisional` |
+| `provisionalSignerIp` / `provisionalSignerUserAgent` | `String` | Signer's request metadata, set when `auditTrail` is on |
+| `voidedAt` / `voidedBy` / `voidReason` | `Date` / `ObjectId` ref `User` / `String` | Set only by the void action (T4) |
+
+For provisional responses, `agreed` is always `true` and `agreedAt` is the server time.
+`signature`/`signedAt` stay unset. `ipAddress`/`userAgent` stay unset, because those fields mean
+the **user's** device. `formVersionSnapshot` is always set. `contentSnapshot` is set when
+`auditTrail` is on. Existing documents read as `provisional: false` through the schema default.
+
+### RBAC
+
+`terrenoStatements.consentResponse` becomes `["list", "read", "signOnBehalf"]`, with a
+description in `terrenoStatementDescriptions`. The built-in `admin` role definition gets
+`consentResponse: ["signOnBehalf"]`. The `admin` role upsert in `roleModel.ts` adds
+`consentResponse` to **existing** unsealed admin roles through `mergeMissingResourcePermissions`,
+as it already does for observability resources. Without that, existing databases such as
+Flourish would not get the permission. `superadmin` already has `*`.
+
+`ConsentAppOptions` gains `accessControl?: AnyTerrenoAccess`. The same rule covers sign, status,
+and void:
+
+| `accessControl` passed | Who may act |
+| --- | --- |
+| yes | Any authenticated user whose roles grant `consentResponse:signOnBehalf` |
+| no | `user.admin` only (legacy apps without RBAC); one `logger.warn` at register |
+
+### Status rules (`getConsentStatuses`, T3)
+
+For each active form after `resolveConsentForms(targetUser, forms)`, look only at non-voided
+responses for the form's **current version**:
+
+1. If the user has their own (non-provisional) response, the latest one decides: `agreed` →
+   `signed`, declined → `declined`.
+2. Otherwise, if a provisional response exists → `provisional`. It counts as signed.
+3. Otherwise → `pending`.
+
+`isConsented` is `true` for `signed` and `provisional`. Exported from `@terreno/api`:
+`getConsentStatuses({userId, resolveConsentForms?}) → Promise<ConsentStatusRow[]>`. App code
+uses this as the "considered signed" contract.
+
+### API (modelRouter `collectionActions` / `instanceActions` on `/consent-responses`)
+
+| Method + path | Body / query | Response | Errors |
+| --- | --- | --- | --- |
+| `POST /consent-responses/provisional` | `{userId, consentFormId, note, locale?}` | `{data: ConsentResponse}` (populated `provisionalSignedBy` name/email) | 400: missing ids, blank note, inactive form, form not in target user's resolved set, `userId` = signer. 404: unknown user or form. 403/405: no permission |
+| `GET /consent-responses/status?userId=` | — | `{data: ConsentStatusRow[]}` | 400 missing `userId`; 404 unknown user; 403/405 |
+| `POST /consent-responses/:id/void` | `{reason}` | `{data: ConsentResponse}` | 400: blank reason, not provisional, already voided. 403/405 |
+
+`ConsentStatusRow = {form: ConsentFormPublic, status: "pending" | "provisional" | "signed" | "declined", isConsented, respondedAt?, provisional?: {responseId, signedAt, signedBy: {id, name, email}, note}}`.
+
+User-facing changes (T2). The user never sees the note or the signer's request metadata:
+
+- `GET /consents/pending`: only non-provisional responses remove a form, as today, including
+  declines. Each form carries `provisionalSignature?: {signedAt, signedByName}` from the latest
+  non-voided provisional response for its current version.
+- `GET /consents/my`: entries add `provisional`, `provisionalSignedBy: {name} | null`, `voidedAt`.
+  No note and no signer IP/UA.
+- `GET /consents/audit/:userId` (admin): adds every provisional and void field.
+
+Audit: when `AuditApp` is registered, sign, void, and status reads each call `recordAuditEvent`
+(`api/src/audit/record.ts`) with actor, target user, form id, and action. Writes are best-effort,
+as everywhere else.
+
+### UI exports (`@terreno/ui`)
+
+```tsx
+<ProvisionalConsentSigner
+  api={terrenoApi}        // consumer RTK api, same pattern as ConsentNavigator
+  baseUrl?: string
+  userId="..."            // the user being signed for
+  onSigned?={(response) => void}
+  onError?={(error) => void}
+  variables?: Record<string, string>
+/>
+```
+
+- `useProvisionalConsent(api, baseUrl)` → `{statuses, isLoading, error, refetch, sign, isSigning, voidSignature}`. It injects `getConsentStatus`, `signConsentProvisionally`, and `voidProvisionalConsent`. Mutations invalidate `ConsentStatus` and `PendingConsents`.
+- `printConsentHtml({html})`: native → `expo-print` `printAsync`; web → hidden iframe + `contentWindow.print()`.
+- `PdfTemplateData.provisionalSignature?: {signedAt, signedByName, note?, signerIp?, voidedAt?}` rendered by `buildConsentPdfHtml` as a "Provisional signature" section.
+
+testIDs: `provisional-consent-signer`, `provisional-consent-row-{formId}`, `provisional-consent-status-{formId}`, `provisional-consent-open-{formId}`, `provisional-consent-note-input`, `provisional-consent-submit-button`, `provisional-consent-success`, `provisional-consent-print-{formId}`, `provisional-consent-void-{formId}`, `consent-form-provisional-notice`, `consent-history-print-{entryId}`, `consent-response-print-button`.
+
+## Tasks
+
+- [x] **T1** — Add provisional consent signing endpoint
+  - Depends on: none
+  - Files: api/src/types/consentResponse.ts, api/src/models/consentResponse.ts, api/src/rbac/statements.ts, api/src/rbac/roleModel.ts, api/src/rbac/roleModel.test.ts, api/src/rbac/statements.test.ts, api/src/consentApp.ts, api/src/consentApp.test.ts, docs/explanation/consent-forms.md (new), docs/reference/api.md
+  - Criteria (each a test):
+    - Admin, no `accessControl`: POST returns 200. The stored response has `provisional: true`, `agreed: true`, `provisionalSignedBy` = signer id, `provisionalNote` = trimmed note, `agreedAt` in the test window, `formVersionSnapshot` = form version, and no `ipAddress`/`userAgent`. With `auditTrail`, `provisionalSignerIp` is set.
+    - With `createAccess` and a role granting `consentResponse:signOnBehalf`, a non-admin gets 200. Without it, 403 or 405. A non-admin without `accessControl` gets 403 or 405.
+    - Blank note → 400; `userId` = signer → 400; inactive form → 400; form filtered out by `resolveConsentForms` for the target → 400; unknown user → 404.
+    - After a provisional sign, the target's `/consents/pending` still lists the form. After the target's own `/consents/respond`, it does not.
+    - Role upsert: a fresh database's Admin role includes `consentResponse:signOnBehalf`. An **existing** unsealed admin role without `consentResponse` gains it on the next upsert. A sealed role is untouched.
+    - With `AuditApp` registered, a sign writes one `AuditEvent` naming actor, target user, and form.
+  - Verification: `bun test --only-failures api/src/consentApp.test.ts api/src/rbac`
+  - Docs: create `docs/explanation/consent-forms.md` (forms, responses, versions, the gate, provisional signing, and why it doesn't clear the gate). Add a `ConsentApp` section to `docs/reference/api.md`: the options table with `accessControl`, plus the provisional endpoint.
+  - Skills: terreno:terreno-backend-api, terreno:mongoose-schema-safety, model-router-actions, terreno:backend-test-env
+
+- [x] **T2** — Expose provisional signature notice data on user-facing consent payloads
+  - Depends on: T1
+  - Files: api/src/consentApp.ts, api/src/consentApp.test.ts, docs/reference/api.md
+  - Criteria: after a provisional sign, the `/consents/pending` form has `provisionalSignature.{signedAt, signedByName}` and no `note`. A form without one has no `provisionalSignature`. `/consents/my` entries include `provisional` and `provisionalSignedBy.name`, but no note and no signer IP/UA (asserted absent). `/consents/audit/:userId` includes all provisional fields. Existing pending/my/audit tests still pass.
+  - Verification: `bun test --only-failures api/src/consentApp.test.ts`
+  - Docs: response shapes in `docs/reference/api.md`.
+  - Skills: terreno:terreno-backend-api
+
+- [x] **T3** — Add getConsentStatuses helper, status endpoint, and provisional admin columns
+  - Depends on: T2
+  - Files: api/src/consentStatus.ts (new), api/src/consentStatus.test.ts (new), api/src/index.ts, api/src/consentApp.ts, api/src/consentApp.test.ts, docs/reference/api.md, docs/explanation/consent-forms.md, example-frontend/store/openApiSdk.ts
+  - Criteria: `getConsentStatuses` implements the status rules, with one test each for `pending`, `provisional`, `signed`, `declined`, "user agrees after provisional → `signed`", "user declines after provisional → `declined`", "old-version responses ignored", and "resolver filters forms for the target user". It is exported from `@terreno/api`. `GET /consent-responses/status?userId=` returns its rows, with the same permission matrix as T1, and writes an `AuditEvent` per read when `AuditApp` is registered. The "Consent Responses" admin contribution adds `provisional` to `listFields` plus a boolean filter, and `provisionalSignedBy` to populate paths.
+  - Verification: `bun test --only-failures api/src/consentStatus.test.ts api/src/consentApp.test.ts`; `cd example-frontend && bun run sdk` diff contains the new operations
+  - Docs: helper and endpoint in `docs/reference/api.md`; "considered signed" rules in the explanation page.
+  - Skills: terreno:terreno-backend-api, terreno:generate-sdk
+
+- [x] **T4** — Void a provisional consent signature
+  - Depends on: T3
+  - Files: api/src/types/consentResponse.ts, api/src/models/consentResponse.ts, api/src/consentApp.ts, api/src/consentStatus.ts, api/src/consentApp.test.ts, api/src/consentStatus.test.ts, docs/reference/api.md, example-frontend/store/openApiSdk.ts
+  - Criteria: `POST /consent-responses/:id/void` with a reason sets `voidedAt`/`voidedBy`/`voidReason` and never deletes the record. Voiding a non-provisional response, voiding twice, or a blank reason → 400. Same permission matrix as T1. After a void, `getConsentStatuses` returns `pending`, and `/consents/pending` drops `provisionalSignature`. With `AuditApp`, a void writes an `AuditEvent`.
+  - Verification: `bun test --only-failures api/src/consentApp.test.ts api/src/consentStatus.test.ts`; SDK regenerated
+  - Skills: terreno:terreno-backend-api, terreno:mongoose-schema-safety
+
+- [x] **T5** — Show provisional notice in the consent gate
+  - Depends on: none (contract above)
+  - Files: ui/src/useConsentForms.ts, ui/src/ConsentFormScreen.tsx, ui/src/ConsentFormScreen.test.tsx
+  - Criteria: adds `ConsentFormPublic.provisionalSignature?: {signedAt, signedByName}`. When it is set, `consent-form-provisional-notice` shows "Signed on your behalf by <name> on <date>" (Luxon `DATETIME_MED`) above the content. Agree, decline, the scroll gate, checkboxes, and the signature requirement are unchanged, and existing tests pass. When it is unset, no notice shows.
+  - Verification: `bun test --only-failures ui/src/ConsentFormScreen.test.tsx`
+  - Skills: terreno:terreno-ui, accessibility-testing
+
+- [x] **T6** — Add ProvisionalConsentSigner status list and useProvisionalConsent hook
+  - Depends on: none (contract above)
+  - Files: ui/src/useProvisionalConsent.ts, ui/src/useProvisionalConsent.test.ts, ui/src/ProvisionalConsentSigner.tsx, ui/src/ProvisionalConsentSigner.test.tsx, ui/src/lazyBoundaries/heavyOptionalExports.tsx, ui/src/index.tsx
+  - Criteria: the hook injects `getConsentStatus` (`GET {base}/consent-responses/status?userId=`) once per (api, baseUrl), following the `useConsentForms` cache pattern. The component shows a spinner while loading, an error with Retry on failure, and one row per form with title and status badge: `Pending`, `Signed provisionally by X on date`, `Signed by user on date`, or `Declined by user on date`. It is exported lazily from `@terreno/ui`, like `ConsentNavigator`. `RootImportRegression` passes.
+  - Verification: `bun test --only-failures ui/src/useProvisionalConsent.test.ts ui/src/ProvisionalConsentSigner.test.tsx ui/src/RootImportRegression.test.tsx`
+  - Skills: terreno:terreno-ui, terreno:terreno-data-fetching
+
+- [x] **T7** — Sign on behalf with a note box in ProvisionalConsentSigner
+  - Depends on: T6
+  - Files: ui/src/useProvisionalConsent.ts, ui/src/useProvisionalConsent.test.ts, ui/src/ProvisionalConsentSigner.tsx, ui/src/ProvisionalConsentSigner.test.tsx
+  - Criteria: `pending` and `declined` rows have `provisional-consent-open-{formId}`. Opening one shows the form content read-only (`MarkdownView`, `variables` applied) and a required multiline `provisional-consent-note-input`. Submit stays disabled until the note is non-blank. Submit POSTs `{userId, consentFormId, note, locale}`, then shows `provisional-consent-success` with the signer name and time from the response, and calls `onSigned`. Server errors show inline and call `onError`.
+  - Verification: `bun test --only-failures ui/src/ProvisionalConsentSigner.test.tsx ui/src/useProvisionalConsent.test.ts`
+  - Skills: terreno:terreno-ui, terreno:terreno-data-fetching, accessibility-testing
+
+- [x] **T8** — Add print helper and provisional block to the consent PDF template
+  - Depends on: none
+  - Files: ui/src/pdfHtmlTemplate.ts, ui/src/pdfHtmlTemplate.test.ts
+  - Criteria: `buildConsentPdfHtml` renders a "Provisional signature" section (signer, date, escaped note when given, signer IP when given, "Voided <date>" when voided) when `provisionalSignature` is set, and nothing extra otherwise. `printConsentHtml({html})` calls `expo-print` `printAsync({html})` on native. On web it appends a hidden iframe with the HTML, calls `contentWindow.print()`, and removes the iframe. Unit tests cover both paths with mocks.
+  - Verification: `bun test --only-failures ui/src/pdfHtmlTemplate.test.ts`
+  - Skills: terreno:terreno-ui
+
+- [x] **T9** — Include provisional signatures in admin-frontend consent PDFs
+  - Depends on: T8
+  - Files: admin-frontend/src/generateConsentPdf.ts, admin-frontend/src/generateConsentHistoryPdf.ts, admin-frontend/src/useConsentHistory.ts, admin-frontend/src/isolated/generateConsentPdf.isolated.ts, admin-frontend/src/isolated/generateConsentHistoryPdf.isolated.ts, admin-frontend/src/isolated/generateConsentPdfMobile.isolated.ts, admin-frontend/src/isolated/generateConsentPdfsMobile.isolated.ts, plus their test files
+  - Criteria: response and history types carry the provisional fields. Web jsPDF output for a provisional response contains "Provisional signature", the signer name, and the date. The admin response PDF also has the note and signer IP. The user history PDF has no note. The native path passes `provisionalSignature` to `buildConsentPdfHtml`, and both mobile isolated tests assert it (extend their `@terreno/ui` mocks). Non-provisional output is unchanged. Each generator exports the template-data builder it uses, for T10.
+  - Verification: `bun test --only-failures admin-frontend/src`
+  - Skills: terreno:building-admin-interfaces
+
+- [x] **T10** — Add print buttons and provisional display to admin and user consent views
+  - Depends on: T9
+  - Files: admin-frontend/src/ConsentResponseViewer.tsx, admin-frontend/src/ConsentResponseViewer.test.tsx, admin-frontend/src/ConsentHistory.tsx, admin-frontend/src/ConsentHistory.test.tsx
+  - Criteria: `ConsentResponseViewer` (admin) shows a "Provisional" badge, signer, date, note, and void state. `ConsentHistory` (the user's own) shows the badge, signer, and date, with no note. `consent-response-print-button` and per-entry `consent-history-print-{entryId}` call `printConsentHtml` with HTML containing the provisional block. Tests assert the HTML string. Existing download buttons still work.
+  - Verification: `bun test --only-failures admin-frontend/src/ConsentResponseViewer.test.tsx admin-frontend/src/ConsentHistory.test.tsx`
+  - Skills: terreno:building-admin-interfaces, terreno:terreno-ui
+
+- [x] **T11** — Print and void from ProvisionalConsentSigner
+  - Depends on: T7, T8
+  - Files: ui/src/useProvisionalConsent.ts, ui/src/useProvisionalConsent.test.ts, ui/src/ProvisionalConsentSigner.tsx, ui/src/ProvisionalConsentSigner.test.tsx
+  - Criteria: `provisional`, `signed`, and `declined` rows, plus the success state, show `provisional-consent-print-{formId}`. It calls `printConsentHtml` with HTML from `buildConsentPdfHtml` containing the form content and, for provisional rows, the provisional block with the note. `provisional` rows show `provisional-consent-void-{formId}`, which asks for a reason in a `Modal`, POSTs `/void`, and refetches, so the row returns to `Pending`.
+  - Verification: `bun test --only-failures ui/src/ProvisionalConsentSigner.test.tsx ui/src/useProvisionalConsent.test.ts`
+  - Skills: terreno:terreno-ui
+
+- [x] **T12** — Wire provisional signing into the example apps with E2E coverage
+  - Depends on: T4, T5, T11
+  - Files: example-backend/src/server.ts, example-frontend/app/consent-sign/[userId].tsx (new), example-frontend/app/admin/consent-responses/[id].tsx, example-frontend/e2e/provisionalConsent.spec.ts (new), example-frontend/e2e/helpers/consentForms.ts, example-frontend/e2e/fixtures/testUsers.ts
+  - Criteria: `ConsentApp` gets `accessControl: access`. `/consent-sign/[userId]` (outside `/admin`, so non-admin staff can reach it) renders `ProvisionalConsentSigner`. The admin response detail links to it. E2E cases:
+    1. Admin opens a pending form, fills the note, and submits. The row shows provisional.
+    2. The test user logs in and sees the gate with `consent-form-provisional-notice` and no note text. They agree and reach the app.
+    3. Admin reloads, and the row shows signed.
+    4. Setup creates a role with `consentResponse:["signOnBehalf"]` through the RBAC API and assigns it to a non-admin staff user, who signs provisionally from the same route.
+    5. A non-admin user without the role sees the error state.
+
+    Screenshots of the signer, the notice, and the print HTML go in `/opt/cursor/artifacts/`.
+  - Verification: `bun run frontend:e2e -- provisionalConsent.spec.ts`; terreno:verify-ui-changes evidence
+  - Skills: terreno:verify-ui-changes, accessibility-testing
+
+- [x] **T13** — Document provisional consent signing and printing
+  - Depends on: T10, T12
+  - Files: docs/reference/ui.md, docs/reference/admin-frontend.md, docs/how-to/sign-consent-on-behalf.md (new), docs/how-to/README.md, docs/explanation/README.md, changelog/unreleased/provisional-consent-signing.md (new)
+  - Criteria: `ui.md` documents `ProvisionalConsentSigner`, `useProvisionalConsent`, `printConsentHtml`, and the gate notice. `admin-frontend.md` documents the print buttons and provisional display. The how-to covers granting `consentResponse:signOnBehalf` (including the existing-admin-role merge on upgrade), passing `accessControl` to `ConsentApp`, mounting the component, using `getConsentStatuses`, voiding, and printing. Both README indexes link the new pages. There is an `Added` changelog fragment.
+  - Verification: `bun run check:changelog`; `bun run check:knip`; the docs-audit skill reports no undocumented new exports
+  - Skills: terreno:update-docs, docs-audit
+
+## Assumptions
+
+- Endpoints are `collectionActions`/`instanceActions` on the existing `/consent-responses` modelRouter, not new hand-written `/consents` routes (repo rule: no new `router.post`).
+- Permission lists are ANDed (`checkPermissions`, `api/src/permissions.ts:110`), so the actions build their own list from `accessControl` instead of using `action.access`.
+- `ConsentApp` mounts routers without a path, so `TerrenoApp`'s `accessControl` does not reach them automatically. It is passed as an option.
+- The target user is loaded with `mongoose.model("User")`. `resolveConsentForms` receives that document.
+- The provisional signer does not tick checkboxes or draw a signature. The note is the only box (D3). Required checkboxes stay the user's to tick.
+- `ConsentNavigator` needs no change. It renders whatever `/consents/pending` returns, and T5 adds the notice inside `ConsentFormScreen`.
+- Build notes: `useProvisionalConsent` takes `{api, baseUrl?, userId}` (RORO), not
+  `(api, baseUrl)`. The success state's print button is `provisional-consent-success-print`,
+  so it never shares `provisional-consent-print-{formId}` with the refetched row. The admin
+  PDF template builders live in `admin-frontend/src/consentPdfTemplates.ts`.
+- The user's own decline still clears the gate, as today. A decline after a provisional sign makes the status `declined`, not signed.
+
+## Open questions (recommendation assumed)
+
+| ID | Question | Recommendation | Why | If answered differently | Tasks affected |
+| --- | --- | --- | --- | --- | --- |
+| Q4 | What does "print consent forms" cover? | A user's form with its signatures, from the admin response view, the user's history, and the signer component | Matches "make sure the provisional is included" | Also print blank forms from the form list (X1) | T8–T11 |
+| Q5 | When organizations are on, limit signers to users in their org? | No, RBAC only, as chosen | You picked RBAC with no relationship check; reads and writes are audited | Add an org-membership check to sign, status, and void | T1, T3, T4 |
+
+## Expansions (follow up later)
+
+| ID | Idea | Why it came up | Rough size | Depends on |
+| --- | --- | --- | --- | --- |
+| X1 | Print blank consent forms from the admin form list | "print consent forms" could mean blank forms | S | T8 |
+| X3 | App hook `canSignOnBehalf(signer, target, form)` for relationship checks (guardian, care team) | RBAC has no target-user check | M | T1 |
+| X4 | Bulk provisional sign of all pending forms for a user | Intake usually covers several forms | S | T7 |
+
+## Decisions
+
+| ID | Question asked | Answer | What it changes |
+| --- | --- | --- | --- |
+| D1 | Who may provisionally sign for another user? | RBAC permission | New `consentResponse:signOnBehalf` statement; no app hook or relationship check |
+| D2 | What does the user see after a provisional signature? | Same gate + notice | Provisional responses don't clear `/consents/pending`; `ConsentFormScreen` shows a notice; the user must still agree |
+| D3 | What is the box the provisional signer fills in? | Note only | Required `provisionalNote` text; no drawn signature from the signer |
+| D5 | Can a provisional signature made in error be undone? | 1a: yes, void action that keeps the record | T4, void button in T11 |
+| D6 | Should the user see the signer's note? | 2a: no, name and date only | Note only in admin, audit, printouts (T2, T5, T9, T10) |
+| D7 | Without RBAC, fall back to `user.admin`? | 3a: yes, with a warning log | T1, T3, T4 permission matrix |
+| D8 | Signing on declined forms: hide it, or let a newer provisional signature outrank an older decline? (asked after build: T7 offered sign on declined rows, but the status rules let the user's decline win) | ok → hide | `ProvisionalConsentSigner` offers "Sign on behalf" on pending rows only |
+| D4 | (follow-up message) Printing | "add in the ability to print consent forms and make sure the provisional is included" | T8–T11 |
+
+## Sign-off
+
+Status: approved 2026-10-23
+Cut: 1 round, 12 findings: 11 fixed (F1 status rules + `declined`, F2 existing-admin-role merge, F3 note hidden from user, F4 signer IP/UA in own fields, F5 `getConsentStatuses` export, F6 resolver check on sign, F7 audit events, F9 real verification commands, F10 mobile isolated tests, F11 per-entry testIDs + view naming, F12 RBAC staff E2E), 1 moved to questions (F8 → Q1, built on its recommendation as T4), 0 rebutted