@terreno/mcp 57.19.2 → 57.20.0

package/src/docs/versioned/next/reference/api.md

@@ -14,6 +14,7 @@ REST API framework built on Express and Mongoose. Provides modelRouter (CRUD end
 - [Middleware](#middleware)
 - [Logging & Tracing](#logging--tracing)
 - [Extensibility](#extensibility)
+- [Consent forms (ConsentApp)](#consent-forms-consentapp)
 - [In-app notifications](#in-app-notifications)
 - [Webhooks & Notifications](#webhooks--notifications)
 - [HTTP Client](#http-client)
@@ -165,6 +166,7 @@ new TerrenoApp({userModel: User})
 | `modelRouter` | `audit: true` or `{redact?: string[]}` after successful HTTP create/update/delete and array push/update/remove |
 | `AdminApp` | Auto when `AuditApp` is registered (`source: "admin"`). `onAdminAudit` is extra |
 | RBAC | `createAccess({auditSink: persistRbacAuditToAuditEvent})` (`source: "rbac"`) |
+| `AccountSecurityApp` | Each recovery action that changes something (`source: "security"`). See [Account security](account-security.md) |
 
 HTTP is list+read only: `GET /audit-events` with `Permissions.IsAdmin`. Empty create/update/delete permission arrays mean POST/PATCH/DELETE return **405**, including `/admin/audit-events` (`admin.adminPermissions`). Non-admin list is also **405** (`permissionMiddleware`). There is no `isDeletedPlugin`; rows are not soft-deleted.
 
@@ -328,8 +330,10 @@ updating, and removing array items:
 
 Each operation runs like a `PATCH` that replaces the whole field. The transform, `preUpdate`,
 and RBAC write checks see `{[field]: newArray}`, and only the body they return is saved. A
-`PATCH` of a subdocument merges into a copy of the item, so a hook (or admin `readonlyFields`)
-that drops the field leaves the stored item unchanged.
+`PATCH` of a subdocument merges into a plain-data copy of the item, so a hook (or admin
+`readonlyFields`) that drops the field leaves the stored item unchanged. It deliberately does not
+use `Subdocument.$clone()`: that clone has no parent, and assigning a nested document array to it
+causes Mongoose setters to fail.
 
 `:id` must be an ObjectId. Any other id leaves this router so a later route on the same
 prefix can handle it. `POST /ai/observability/evaluators` is not an array push on a model
@@ -415,23 +419,23 @@ new TerrenoApp({
 | `authorizationRequestTtlSeconds` | 600 | How long a request waits for a consent decision |
 | `authorizationCodeTtlSeconds` | 60 | How long a code can be exchanged |
 
-Misconfiguration (an issuer with a path, a non-URL `consentUrl`, registration on with no redirect hosts) throws at boot. With registration off, create clients yourself as `McpOAuthClient` documents (`clientId`, `clientName`, `redirectUris`, `grantTypes: ["authorization_code", "refresh_token"]`, `responseTypes: ["code"]`); `/oauth/register` is then 404 and the metadata has no `registration_endpoint`.
+Misconfiguration (an issuer with a path, a non-URL `consentUrl`, registration on with no redirect hosts) throws at boot. With registration off, create public clients yourself as `McpOAuthClient` documents (`clientId`, `clientName`, `redirectUris`, `grantTypes: ["authorization_code", "refresh_token"]`, `responseTypes: ["code"]`). Create a headless client with `McpOAuthClient.issueConfidential({clientName, tokenEndpointAuthMethod, userId})`, which returns `{client, clientSecret}` once. `/oauth/register` is 404 while registration is off, and the metadata has no `registration_endpoint`.
 
 | Method | Path | Auth | Purpose |
 | --- | --- | --- | --- |
 | GET | `/.well-known/oauth-protected-resource` and `/.well-known/oauth-protected-resource/mcp` | none | RFC 9728 metadata: `resource`, `authorization_servers`, `bearer_methods_supported`, `scopes_supported` |
-| GET | `/.well-known/oauth-authorization-server` | none | RFC 8414 metadata: `issuer`, endpoints, `response_types_supported: ["code"]`, `grant_types_supported`, `code_challenge_methods_supported: ["S256"]`, `token_endpoint_auth_methods_supported: ["none"]` |
+| GET | `/.well-known/oauth-authorization-server` | none | RFC 8414 metadata: `issuer`, endpoints, `response_types_supported: ["code"]`, `grant_types_supported` (`authorization_code`, `refresh_token`, `client_credentials`), `code_challenge_methods_supported: ["S256"]`, `token_endpoint_auth_methods_supported` (`none`, `client_secret_basic`, `client_secret_post`) |
 | POST | `/oauth/register` | none | Only with `dynamicClientRegistration`. RFC 7591 dynamic client registration. Public clients only. 201 with `client_id`; `invalid_redirect_uri` for a redirect outside `allowedRedirectHosts`, non-https (except loopback), or with a fragment |
-| GET | `/oauth/authorize` | none | Validates `client_id`, `redirect_uri`, `response_type=code`, PKCE (`S256` only), `scope`, and `resource`, stores a pending request, and redirects to `consentUrl?request=<id>`. An unknown client or unregistered redirect is a 400 in place; other errors redirect with `error` and `state` |
-| GET | `/oauth/authorize/:request` | JWT or session | What the consent screen shows: `{data: {clientId, clientName, redirectUri, redirectHost, scope, resource, expiresAt}}` |
-| POST | `/oauth/authorize/:request/approve` | JWT or session | `{data: {redirectUrl}}` carrying `code`, `state`, and `iss` |
-| POST | `/oauth/authorize/:request/deny` | JWT or session | `{data: {redirectUrl}}` carrying `error=access_denied` and `state` |
-| POST | `/oauth/token` | `client_id` | `authorization_code` (with `code`, `redirect_uri`, `code_verifier`) or `refresh_token`. Returns `{access_token, token_type: "Bearer", expires_in, refresh_token, scope}` with `Cache-Control: no-store` |
+| GET | `/oauth/authorize` | none | Validates `client_id`, `redirect_uri`, `response_type=code`, PKCE (`S256` only), `scope`, and `resource`, stores a pending request, and redirects to `consentUrl?request=<id>`. An unknown or revoked client, or an unregistered redirect, is a 400 in place; other errors redirect with `error` and `state`. A loopback redirect (`localhost`, `127.0.0.1`, `[::1]`) matches a registered URI with the same scheme, host, path, and query on any port (RFC 8252 §7.3). PKCE `S256` is what stops another process on that host from exchanging a code delivered to a different port. The pending request stores the redirect the client sent, so the code returns to that port. Those three hosts do not match each other. Every other redirect must match the registered string exactly |
+| GET | `/oauth/authorize/:request` | JWT, session, or `req.user` already set | What the consent screen shows: `{data: {clientId, clientName, redirectUri, redirectHost, scope, resource, expiresAt}}` |
+| POST | `/oauth/authorize/:request/approve` | JWT, session, or `req.user` already set | `{data: {redirectUrl}}` carrying `code`, `state`, and `iss`. The grant is issued to `req.user._id` |
+| POST | `/oauth/authorize/:request/deny` | JWT, session, or `req.user` already set | `{data: {redirectUrl}}` carrying `error=access_denied` and `state` |
+| POST | `/oauth/token` | public: `client_id` in the body. confidential: `client_secret_basic` or `client_secret_post`, matching the client | `authorization_code` (with `code`, `redirect_uri`, `code_verifier`), `refresh_token`, or `client_credentials`. Authorization-code and refresh responses are `{access_token, token_type: "Bearer", expires_in, refresh_token, scope}`. `client_credentials` returns the same without `refresh_token`, and the access token acts as the client's bound user. `Cache-Control: no-store` |
 | POST | `/oauth/revoke` | `client_id` | RFC 7009. Always 200. Revoking a refresh token revokes its whole chain |
 
-The consent endpoints are in OpenAPI (`getMcpOAuthRequest`, `approveMcpOAuthRequest`, `denyMcpOAuthRequest`) and refuse `mcp_` and `mcpat_` bearers, so an agent cannot approve its own grants. A pending request that expired is 400 `Authorization request expired`; one already decided is 409. Protocol endpoints answer `{error, error_description}` per RFC 6749 and never carry the `requestId` member TerrenoApp adds to other JSON bodies. `/oauth/register`, `/oauth/authorize`, `/oauth/token`, and `/oauth/revoke` count against the `auth` rate-limit bucket.
+The consent endpoints are in OpenAPI (`getMcpOAuthRequest`, `approveMcpOAuthRequest`, `denyMcpOAuthRequest`) and refuse `mcp_` and `mcpat_` bearers, so an agent cannot approve its own grants. `authenticateMiddleware()` calls `next()` when `req.user` is already set, so an app with no Terreno JWT sets that user in `addMiddleware` (before these routes), from a session the app has already verified, and calls the consent routes with no bearer. The user object needs `_id`. See [Enable MCP OAuth](../how-to/enable-mcp-oauth.md#apps-without-a-terreno-jwt). A pending request that expired is 400 `Authorization request expired`; one already decided is 409. Protocol endpoints answer `{error, error_description}` per RFC 6749 and never carry the `requestId` member TerrenoApp adds to other JSON bodies. `/oauth/register`, `/oauth/authorize`, `/oauth/token`, and `/oauth/revoke` count against the `auth` rate-limit bucket.
 
-Tokens are opaque (`mcpat_` access, `mcprt_` refresh) and stored only as SHA-256 hashes in `McpOAuthToken`. Each refresh rotates the pair; reusing a rotated refresh token revokes every pair issued from that authorization (its family). Codes are single-use: a failed exchange burns the code, and replaying a used code revokes the tokens it issued. The code exchange fixes the family id when it consumes the code, so a replay can revoke the family before its tokens exist.
+Tokens are opaque (`mcpat_` access, `mcprt_` refresh) and stored only as SHA-256 hashes in `McpOAuthToken`. Each refresh rotates the pair; reusing a rotated refresh token revokes every pair issued from that authorization (its family). Codes are single-use: a failed exchange burns the code, and replaying a used code revokes the tokens it issued. The code exchange fixes the family id when it consumes the code, so a replay can revoke the family before its tokens exist. A `client_credentials` token has no refresh token. Its document still stores a unique hash of a discarded secret so the `refreshTokenHash` unique index is unchanged, and `hasRefreshToken: false` rejects that hash if it is ever presented. `McpOAuthClient.revoke(clientId)` revokes every family issued to that client. An authorization-code exchange, a refresh, or a client_credentials grant that loses a race with that revoke is discarded instead of returned. `deleteOne`, `findOneAndDelete`, and `deleteMany` revoke those families too. A query `deleteOne` or `findOneAndDelete` whose filter matches several clients deletes one of them and revokes that client's tokens. `bulkWrite` bypasses the hooks.
 
 `McpOAuthToken.revokeFamily(familyId)` first writes an `McpOAuthRevokedFamily` tombstone, then revokes every pair in the family. `McpOAuthToken.issue` refuses a tombstoned family with `McpOAuthFamilyRevokedError` (the token endpoint answers `invalid_grant`), and checks again after creating the pair, revoking it if a revoke landed meanwhile. A request that won a rotation or code exchange before a concurrent revoke therefore cannot leave a live pair behind. Tombstones expire after the family's last refresh expiry, and at least one hour after the revoke.
 
@@ -465,8 +469,12 @@ setupServer({
 - `POST /auth/signup` — Create user account
 - `POST /auth/login` — Authenticate with email/password
 - `POST /auth/refresh_token` — Refresh access token
-- `POST /auth/forgotPassword` — Always 202; mails a reset link only when the email exists
-- `POST /auth/resetPassword` — `{token, password}`; also aliased at `POST /resetPassword` for the RTK client
+- `POST /auth/forgotPassword` — Always 202; mails a reset link only when the email exists (with
+  `BetterAuthApp` registered, only when that user already has a JWT password)
+- `POST /auth/resetPassword` — `{token, password}`; also aliased at `POST /resetPassword` for the
+  RTK client. With `BetterAuthApp` registered, a token for a user without a JWT password gets 400
+  `legacy-password-reset-unavailable` and sets no password (`POST /auth/login` has no second
+  factor); that user resets through Better Auth
 - `POST /auth/sendVerification` — Authenticated; 202 only after delivery succeeds; mails a verification link when `emailVerified` is not true
 - `POST /auth/verifyEmail` — `{token}` sets `emailVerified` true
 - `GET /auth/me` — Get current user profile
@@ -539,7 +547,9 @@ Request logs redact credential values at any depth in request bodies and in URL
 any key whose name contains `password`, `passwd`, `passphrase`, `passcode`, `token`, `secret`,
 `verifier`, `signature`, `apikey`, `authorization`, `credential`, or `privatekey` (case and `_`/`-`
 ignored, so `currentPassword`, `refresh_token`, `client_secret`, and `idToken.token` all match), or
-that has `code`, `otp`, or `pin` as a word (`code`, `zipCode`, `otp_code`). Changing the mailbox through `PATCH /auth/me`
+that has `code`, `otp`, `pin`, `note`, or `reason` as a word (`code`, `zipCode`, `otp_code`,
+`provisionalNote`). `note` and `reason` are free text that can hold PHI, such as a provisional
+consent signer's note. Changing the mailbox through `PATCH /auth/me`
 invalidates unused `passwordReset` AuthTokens for that user even when the schema has no
 `emailVerified` field. When the schema uses `emailVerificationPlugin`, mailbox change also
 sets `emailVerified` to false and invalidates unused `emailVerification` tokens; changing letter
@@ -562,8 +572,8 @@ case instead of 202. Email lookup is case-insensitive. Successful reset calls `s
 `tokenEpoch` so outstanding **refresh** tokens and MCP credentials (`mcp_` service tokens and
 `mcpat_`/`mcprt_` OAuth grants) fail, and returns new JWT tokens. When
 `BetterAuthApp` is registered, JWT reset also updates that user's Better Auth password
-and deletes Better Auth sessions. Better Auth password reset updates the JWT password
-and `tokenEpoch` for the matching app User. Access
+and deletes Better Auth sessions. Better Auth password reset updates the JWT password of the
+matching app User when it already has one, and bumps its `tokenEpoch`. Access
 tokens stay valid until expiry (default 15m). `POST /resetPassword`
 matches the `@terreno/rtk` `resetPassword` mutation path (`password` or `newPassword`).
 
@@ -663,9 +673,11 @@ Set `publicAppUrl`, `sendMail`, and `renderAuthMail` (from `@terreno/comms`) so
 Those hooks throw 501 and do not send when `publicAppUrl` is missing, so links are never
 relative. Password reset also sets `revokeSessionsOnPasswordReset`, so existing Better Auth sessions
 are deleted when that reset path succeeds. JWT `POST /auth/resetPassword` updates the
-Better Auth password and deletes those sessions when `BetterAuthApp` is registered.
+Better Auth password and deletes those sessions when `BetterAuthApp` is registered; it only
+serves app `User`s that already have a JWT password then (others get 400
+`legacy-password-reset-unavailable`, and `POST /auth/forgotPassword` mails them nothing).
 With a user model, Better Auth `reset-password` sets the same password as the app `User`'s JWT
-password and bumps `tokenEpoch`. `change-password` sets the new JWT password only on an app
+password when that `User` already has one, and bumps `tokenEpoch` either way. `change-password` sets the new JWT password only on an app
 `User` that already has one. `change-password`, `revoke-sessions`, and `revoke-other-sessions`
 bump `tokenEpoch` for the linked app `User`, so JWT refresh tokens and MCP credentials issued
 before the change stop working.
@@ -690,9 +702,10 @@ trusted origin (`trustedOrigins` plus the API's own origin), or that has neither
 browser headers are unchanged; `advanced.disableCSRFCheck` disables the check.
 
 On first contact, `syncBetterAuthUser` finds the app `User` by `betterAuthId` and creates it
-when missing. It links an existing app `User` that has the same email only when Better Auth has
-verified that email and the row has no other `betterAuthId`. Otherwise the session does not set
-`req.user` and the socket handshake is refused, until the address is verified. When a verified
+when missing. It links an existing app `User` that has the same email only when the row has no
+other `betterAuthId` and Better Auth has verified that email or the request's password matches the
+row's passport hash (see the plugin rules below). Otherwise the session does not set `req.user`
+and the socket handshake is refused. When a verified
 email links a row whose own `emailVerified` is not `true`, its legacy passport password is removed
 and `tokenEpoch` is bumped, because whoever set that password never proved the mailbox. Seeds
 that create the Better Auth account themselves pass `{trustEmail: true}` as the fourth argument
@@ -705,6 +718,43 @@ registered `BetterAuthApp` instance for socket sessions. With a user model (its
 The legacy JWT socket handshake loads the same user model and refuses a token whose user is
 disabled or missing (`createSocketAuthMiddleware({tokenSecret, userModel})`).
 
+With a user model, the `terreno-app-user-sync` plugin guards Better Auth user creation and syncs
+the app `User` as each Better Auth session is created
+(`syncBetterAuthUser(userModel, betterAuthUser, oauthProvider?, {password?, trustEmail?})`):
+
+- An app `User` with the same email that no Better Auth user has claimed is claimed only when the
+  email is verified, or when the request's plaintext password (`/sign-up/email`,
+  `/sign-in/email`) verifies against that `User`'s passport-local-mongoose hash. The hash check
+  runs on a detached copy, so passport's `limitAttempts` counters never change.
+- Before a Better Auth user is created, the same rule runs on the provider-reported
+  `emailVerified` and the sign-up password. A refusal answers 409 with
+  `code: "VERIFY_EMAIL_TO_USE_ACCOUNT"` (an OAuth callback redirects with that `error`) and
+  creates nothing: no Better Auth user, account, or verification email. A `User` already bound to
+  another Better Auth account is refused the same way with `code: "ACCOUNT_ALREADY_EXISTS"`.
+- At session creation the rule runs again; `syncBetterAuthUser` throws `APIError` 409
+  `VERIFY_EMAIL_TO_USE_ACCOUNT` ("Verify your email to use this account") and the sign-in answers
+  the same 409. No second `User` is inserted.
+- The provider id of a social or generic OAuth sign-in fills `oauthProvider` on create and link.
+- Emails match ignoring case (the address is matched literally, not as a pattern).
+- `BetterAuthApp` without its own `userModel` adopts `TerrenoApp`'s before it creates Better Auth
+  (`adoptUserModel`), so the plugin is installed whenever a user model is in play. Adopting after
+  the instance exists throws at boot. Callers of `createBetterAuth` must pass `userModel`
+  themselves.
+- A password-proven link that fails to save fails the sign-in with 500 `APP_USER_LINK_FAILED`.
+  Other sync failures are logged and the session proceeds; the session middleware retries.
+
+With a user model, Terreno's `onPasswordReset` sets the same password on the app `User`'s
+passport hash when it already has one, and bumps `tokenEpoch` either way. A `User` without a JWT
+password (a social-only account) does not gain one, since `POST /auth/login` has no second
+factor. It reads the new password (`newPassword`, or `password` for
+the email-OTP and phone-number resets) from the parsed body of the Better Auth endpoint being
+served, through Better Auth's endpoint context. Better Auth reads an HTTP body before the hook
+runs, so the request it passes cannot be read again. HTTP requests and direct `auth.api` calls
+both work.
+
+`accountLinking: {mode: "never"}` refuses `POST {basePath}/link-social` with 403
+`LINKING_DISABLED`. See [Account linking](../explanation/account-linking.md).
+
 **Social sign-in for a web app on another site (`oauthHandoff`):**
 
 `oauthHandoff: {webOrigins, callbackPaths?}` lets a bearer-mode web client on another site
@@ -729,14 +779,119 @@ Endpoints it adds, under `basePath` (default `/api/auth`):
   `callbackPaths` on one of `webOrigins`, `errorCallbackURL` (optional) is on one of
   `webOrigins`, and `trustedOrigins` allows both. It also answers 400 when `Sec-Fetch-Dest` is
   set and is not `document`. The OAuth callback then redirects to `callbackURL` with
-  `#ott=<token>`, a single-use token that expires in three minutes.
+  `#ott=<token>`, a single-use token that expires in three minutes. With `oauthProxy` on a
+  preview, the session is created on the preview's `GET {basePath}/callback/:id/oauth-proxy`
+  (or the deprecated `GET {basePath}/oauth-proxy-callback`) after the production server
+  receives the provider's return, and that redirect carries the `#ott` instead.
 - `POST {basePath}/one-time-token/verify` — Body `{token}`. Exchanges the token once for the
   session and the `set-auth-token` header, and sets no cookie. `GET
   {basePath}/one-time-token/generate` is refused.
+- `POST {basePath}/oauth-handoff/link-intent` — Bearer- or cookie-authenticated. Body
+  `{provider, callbackURL, errorCallbackURL?}`. Both URLs must be absolute and on one of
+  `webOrigins` that `trustedOrigins` allows; `callbackPaths` do not apply, since no token travels
+  on a link's return (400; Better Auth's origin check answers 403 first for a URL outside
+  `trustedOrigins`). Answers
+  `{token, startURL}`: a single-use link token that expires in three minutes, stored hashed in
+  Better Auth's verification table (`terreno-link-intent:<hash>`) and bound to the caller's
+  session. Answers 401 without a session and 403 `LINKING_DISABLED` when account linking is off.
+- `POST {basePath}/oauth-handoff/link-start` — Form body `token=<token>`, submitted as a page
+  navigation (`application/x-www-form-urlencoded` only). Answers 400 when `Sec-Fetch-Dest` is set
+  and is not `document`, and 403 when `Origin` is missing, `null`, or not one of `webOrigins`,
+  without using the token. Web origins must not serve `Referrer-Policy: no-referrer` or
+  `same-origin`, which make the form's `Origin` `null`. Otherwise it uses the token up (400, no redirect, when unknown, used, or
+  expired), runs Better Auth's link flow as the token's session, sets only the OAuth state
+  cookie, and redirects to the provider. A link that cannot start redirects to
+  `errorCallbackURL` (or `callbackURL`) with `error=session_expired`, `error=provider_not_found`,
+  or `error=link_failed`. The provider callback links the account and redirects to `callbackURL`
+  with no `#ott`, since no session is created. rtk's `linkSocialWithHandoff` drives both steps;
+  see [Linking a provider in bearer mode](../how-to/configure-better-auth.md#linking-a-provider-in-bearer-mode).
+
+With the opt-in `rateLimit`, every path above is in the auth bucket. Better Auth's own limiter
+allows three starts, three link intents, and three link starts per ten seconds per IP.
+
+**Sign-in methods discovery (`GET {basePath}/terreno/methods`):**
+
+Every Better Auth server answers `GET {basePath}/terreno/methods` (default
+`/api/auth/terreno/methods`) with the sign-in methods it has enabled, so a login screen renders
+only those. It needs no session. Read it from a frontend with `useAuthMethods(authClient)` from
+`@terreno/rtk`.
+
+``````json
+{
+  "accountLinking": {"mode": "verified-email"},
+  "emailPassword": true,
+  "multiSession": false,
+  "passkey": false,
+  "providers": ["github", "google", "mock-oidc"],
+  "signUp": true,
+  "twoFactor": false
+}
+``````
 
-With the opt-in `rateLimit`, both paths are in the auth bucket.
+- `providers` — Sorted ids of every OAuth provider that can start a sign-in: the configured
+  `googleOAuth`, `githubOAuth`, and `appleOAuth` providers, plus every `genericOAuth` provider id
+  from `plugins`. The endpoint is public, so every configured provider id is published, including
+  generic providers meant only for integrations or internal staff. A generic provider whose
+  discovery failed at startup is left out.
+- `emailPassword` — Better Auth's `emailAndPassword.enabled` (on unless `options` turns it off).
+- `signUp` — `true` when email and password is on and `emailAndPassword.disableSignUp` is not set
+  (`signUp: {mode: "closed"}` sets it).
+- `accountLinking.mode` — From Better Auth's `account.accountLinking`: `"never"` when
+  `enabled: false`, `"explicit"` when `disableImplicitLinking: true`, otherwise
+  `"verified-email"` (Better Auth's default: a same-email sign-in links when the provider reports
+  a verified email).
+- `passkey`, `twoFactor`, `multiSession` — `true` when the `passkey`, `two-factor`, or
+  `multi-session` plugin is in the final plugin list: set by the `passkey`, `twoFactor`, and
+  `multiSession` config fields, or added through `plugins`. See
+  [Auth features](../how-to/configure-better-auth.md#auth-features).
+
+The values come from Better Auth's final context on each request, so `options` overrides and
+plugin-registered providers are reflected.
+
+**Set a first password (`POST {basePath}/terreno/set-password`):**
+
+Every Better Auth server serves `POST {basePath}/terreno/set-password` (default
+`/api/auth/terreno/set-password`) so a signed-in user who has no password, such as one who signed
+up with a provider, can add one. Better Auth's own `setPassword` is server-only. rtk's
+`useAccountSecurity` calls it from the password card's "Set a password" form.
+
+| Request | Response |
+| --- | --- |
+| Body `{newPassword}` with a bearer or session cookie, and no password yet | `200 {status: true}` with `cache-control: no-store`; the user can now sign in with email and password |
+| The user already has a password | `409` `PASSWORD_ALREADY_SET` (change it with `/change-password`). Of two concurrent sets, one succeeds and the other gets this 409; one credential row remains |
+| No session, or a revoked one (the session is read from the database, not the cookie cache) | `401` |
+| The session signed in longer ago than Better Auth's `session.freshAge` (a day by default) | `403` `SESSION_NOT_FRESH`: sign in again first, so a stolen old session cannot add a lasting password |
+| Shorter than `emailAndPassword.minPasswordLength` (8) or longer than `maxPasswordLength` (128) | `400` `PASSWORD_TOO_SHORT` / `PASSWORD_TOO_LONG` |
+| Email and password sign-in is off | `400` `EMAIL_PASSWORD_DISABLED` |
+
+With a `userModel`, the new password is also set on the app User's passport-local-mongoose hash
+(when the model has one), so `POST /auth/login` accepts it on dual-enrolled apps, and the request
+records a `password-set` security event. The app User is the one whose `betterAuthId` matches, or
+else the one with the same email, but only when the Better Auth email is verified and that User is
+not linked to another Better Auth user. A successful `POST {basePath}/change-password` syncs the
+same way and also bumps the app User's `tokenEpoch`, so the old password stops working at
+`POST /auth/login` (which has no second factor) and outstanding JWT refresh tokens stop
+refreshing (see
+[Self-service events](account-security.md#self-service-events)). With the opt-in `rateLimit`, the
+path is in the auth bucket.
+
+**Challenge header (`X-Terreno-Auth-Challenge`):**
+
+With `twoFactor` or `passkey` configured, a request that sends `X-Terreno-Auth-Challenge` (`-`
+when empty) gets back the challenge cookies its response sets (`two_factor`, `trust_device`, the
+passkey challenge, and `dont_remember` when it comes with a two-factor challenge) in the same
+header, as URL-search-params `name=value` pairs with the signed cookie values; an empty value
+means the cookie expired. Only values the response sets are carried. Such a sign-in that
+answers with a two-factor challenge has no `set-auth-token`. The header is listed in
+`Access-Control-Expose-Headers`. On `{basePath}/two-factor/*`, `/passkey/*`, and `/sign-in/*`,
+the header's challenge cookies are merged into the request's cookies unless a real cookie of
+the same name is present; other names, including session cookies, are ignored. rtk's bearer mode
+uses it; see
+[Challenges without cookies](../explanation/authentication.md#challenges-without-cookies).
 
 **Endpoints (when enabled):**
+- `GET /api/auth/terreno/methods` — Enabled sign-in methods (public)
+- `POST /api/auth/terreno/set-password` — Add a first password for the signed-in user
 - `POST /api/auth/signup/email` — Email/password signup
 - `POST /api/auth/signin/email` — Email/password signin
 - `GET /api/auth/signin/{provider}` — Initiate OAuth (google, github, apple)
@@ -1251,6 +1406,14 @@ source's deny posture for the user. Under every policy:
   role mappings, membership lookups). Their cold failure then drops only their grants and local
   roles apply. The built-in organization membership source (`createAccess({organizations: true})`)
   sets it.
+- Dropped grants make a user look less privileged, which is safe for the user being authorized
+  but not for the target of "may this actor act on that user?". Pass
+  `access.getPermissions({user, requireComplete: true})` for such a target: when a failed source's
+  grants were dropped (not served from a `"use-stale"` cache), it throws 503
+  `Permission source unavailable` instead of returning the partial set. The account-security
+  reach check, the RBAC user-write guard, and the RoleManager target-privilege rule
+  (`access.roles.assign`, `unassign`, `previewAssignment`, and `assertCanModifyUser`, so also
+  `PUT /rbac/users/:id/roles` and admin user writes) resolve their target this way.
 
 ## Request Validation
 
@@ -1474,6 +1637,27 @@ See [Schema metadata explanation](../explanation/schema-metadata.md).
 
 ## Middleware
 
+### Error middleware
+
+`TerrenoApp` ends the app with `apiUnauthorizedMiddleware`, `apiErrorMiddleware`,
+and `apiFallthroughErrorMiddleware`, in that order. `apiErrorMiddleware` answers with a JSONAPI
+error body for these errors:
+
+| Error | Status | Title |
+|-------|--------|-------|
+| `APIError` (or a subclass) | its `status` | its `title` |
+| Mongoose `ValidationError` or `CastError` | 400 | `Validation failed`, with `meta.fields` |
+| Malformed JSON or urlencoded body (`entity.parse.failed`) | 400 | `Malformed request body` |
+| Body over the parser `limit` (`entity.too.large`, `parameters.too.many`) | 413 | `Request body too large` |
+| Unsupported body charset or encoding | 415 | `Unsupported request body encoding` |
+| Aborted or truncated body (`request.aborted`, `request.size.invalid`) | 400 | `Request body incomplete` |
+
+Body-parser errors keep the parser's message in `detail`, are logged at `warn`, and skip Sentry.
+`bodyParserErrorToAPIError(err)` and `mongooseErrorToAPIError(err)` are exported for custom error
+handlers; each returns `null` for errors it does not handle. Anything else reaches
+`apiFallthroughErrorMiddleware`, which logs `Fallthrough error: <error>` with the stack at `error`
+level and answers `500 {"status":500,"title":"Internal server error"}`.
+
 ### openApiEtagMiddleware
 
 Adds ETag support to the `/openapi.json` endpoint for efficient caching.
@@ -1520,7 +1704,8 @@ background job can be followed across many log lines, both in plain-text console
 transports (Google Cloud Logging, Sentry).
 
 > Never use `console.log` for permanent server logs — use `logger` or a scoped logger. Request
-> logging already redacts password, token, secret, and code fields in bodies and query strings;
+> logging already redacts password, token, secret, code, note, and reason fields in bodies and
+> query strings;
 > never log secrets, full auth tokens, or raw passwords.
 
 ### Quick reference
@@ -1756,19 +1941,98 @@ To correlate with Cloud Trace, ensure clients or load balancers send `x-cloud-tr
 
 ### Development browser-log ingestion
 
-`TerrenoApp` mounts `POST /__terreno/browser-logs` only when `NODE_ENV=development`, or when
-`TERRENO_BROWSER_LOGS=true` in another non-production environment. Production always returns 404;
-set `TERRENO_BROWSER_LOGS=false` to disable the route in development.
+`POST /__terreno/browser-logs` lets a running client write its console errors and warnings to a
+file on the backend, where the local MCP `read_logs` and `last_error` tools can read them. The
+Terreno dev console logger (`installTerrenoDevConsoleLogger`) is the client that sends them. The
+route lives in `api/src/browserLogsRoute.ts`.
+
+**When the route exists.** `TerrenoApp` calls `addTerrenoDevBrowserLogsRoute(app)` while it builds
+the app. `setupServer` does not register the route. An app built on `setupServer` can call the
+exported `addTerrenoDevBrowserLogsRoute(app)` itself. The check runs once, when the route is added:
+
+| `NODE_ENV` | `TERRENO_BROWSER_LOGS` | Route |
+|------------|------------------------|-------|
+| `production` | any value, including `true` | Not registered |
+| anything else, or unset | `false` or `0` | Not registered |
+| anything else, or unset | `true` or `1` | Registered |
+| `development` | unset or any other value | Registered |
+| not `development`, or unset | unset or any other value | Not registered |
+
+An unregistered route falls through to the app's normal not-found handling, so the request gets a
+404. Production always returns 404. `TERRENO_BROWSER_LOGS=true` cannot turn the route on there.
+`NODE_ENV` unset counts as "not `development`", so the route is off unless
+`TERRENO_BROWSER_LOGS=true` is set.
+
+**Who may post.** The route accepts a request when `req.user` is set or when the socket's remote
+address is loopback (`127.0.0.1`, `::1`, or `::ffff:127.0.0.1`). Any other request gets 403. The
+check reads the socket address, not `X-Forwarded-For`. `TerrenoApp` mounts the route after JWT
+decoding, the Better Auth session middleware, and the optional rate limiter. Remote clients can
+authenticate the usual way, and configured API limits apply to ingestion too.
+
+**Request body.**
+
+``````json
+{"entries": [{"level": "error", "message": "Cannot read properties of undefined", "stack": "TypeError: ...", "timestamp": "2026-10-12T00:29:20.067+00:00"}]}
+``````
+
+| Field | Type | Handling |
+|-------|------|----------|
+| `entries` | array | Required and non-empty. At most 100 items. |
+| `entries[].level` | string | Defaults to `info`. Truncated to 32 characters. |
+| `entries[].message` | any | A string is kept as is. Any other value is JSON-stringified. Truncated to 8,000 characters. |
+| `entries[].stack` | string | Optional. Truncated to 16,000 characters. Left out of the line when it is not a string. |
+| `entries[].timestamp` | string | Kept as sent. When missing or empty, the server uses Luxon `DateTime.now().toISO()`. |
+
+Items that are not objects are skipped, and the request still succeeds.
+
+**Responses.**
+
+| Status | When |
+|--------|------|
+| `204` | The batch was accepted and written. |
+| `400` | The body has no `entries` array, or the array is empty: `{"error": "Expected { entries: [...] }"}`. |
+| `403` | The client is neither loopback nor authenticated. |
+| `413` | The parsed body is over 256 kB, or `entries` has more than 100 items. |
+| `404` | The route is not registered (see the table above). |
+
+The route has its own `express.json({limit: "256kb"})` parser. Under `TerrenoApp`, the app-wide
+JSON parser runs first with a larger limit, so the route measures the parsed body itself and
+answers 413.
 
-The route accepts loopback requests for local browser development. Non-loopback clients must
-authenticate through the app's normal JWT or Better Auth middleware. `TerrenoApp` mounts the route
-after its optional rate limiter, so configured API limits also apply to ingestion.
+**Output file.** Each accepted item becomes one JSON line in
+`<process.cwd()>/.terreno/logs/browser.log`. The directory is created if needed, and the file is
+created with mode `0600`. The path follows the backend's working directory. In this monorepo,
+`bun run backend:dev` runs in `example-backend/`, so the file is
+`example-backend/.terreno/logs/browser.log`. A line looks like this:
 
-The request body is `{entries: Array<{level?, message?, stack?, timestamp?}>}`. Batches are capped
-at 100 entries and 256 kB. Accepted rows are truncated to bounded field lengths and appended as
-mode-`0600` JSONL under `<backend cwd>/.terreno/logs/browser.log`. The file restarts with the latest
-batch before it would exceed 5 MB. The local MCP `read_logs` / `last_error` tools and
-`terreno logs --sources browser` consume that file.
+``````json
+{"level":"warn","message":"TASK-1.2 direct POST probe","source":"browser","timestamp":"2026-10-12T00:29:20.067+00:00"}
+``````
+
+Each line has `level`, `message`, `source` (always `"browser"`), `stack` (only when present), and
+`timestamp`, in that order. There is no rotation and no backup file. If a batch would push the file
+past 5 MB, the file is overwritten with that batch and all earlier lines are lost.
+
+**Who reads it.** The local MCP `read_logs` tool (source `browser`), the `last_error` tool, and
+`terreno logs --sources browser` / `terreno logs last-error` read `browser.log` from each of these
+directories that exists under the project root: `backend/.terreno/logs`,
+`example-backend/.terreno/logs`, and `.terreno/logs`. Backend logs go to `app.log` in the same
+directory. That file comes from the Winston JSONL transport, which `TERRENO_LOG_FILE` switches on
+or off (see [Environment variables](environment-variables.md#observability)).
+
+**Client behavior.** The Terreno dev console logger runs only in development builds (`__DEV__`). It
+captures `console.error`, `console.warn`, uncaught errors, and unhandled rejections. It sends them
+in batches of up to 100, about 400 ms after the first one is queued. If a post fails, it retries
+once and then drops the batch without reporting anything. A missing route (404) or a 403 therefore
+shows up only as an empty `browser.log`. Uncaught errors and unhandled rejections whose value is
+an `Error` carry a `stack`. `console.error` and `console.warn` entries do not. An error passed to
+React Native's `ErrorUtils` handler is logged only after the previous handler returns. On web the
+default handler rethrows, so the logger skips that error: its caller may still catch it, as Expo's
+web `import()` does while it loads a split bundle. If nothing catches it, the window `error` or
+`unhandledrejection` listener logs it.
+
+On the client, `installTerrenoDevConsoleLogger({baseUrl})` from `@terreno/syncdb` posts to this
+route in `__DEV__` builds. The `@terreno/rtk` export of the same name is a deprecated re-export.
 
 ### Message style
 
@@ -1871,6 +2135,168 @@ setupServer({
 - Optional/configurable functionality
 - Clean separation of concerns
 
+## Consent forms (ConsentApp)
+
+Versioned consent forms, user responses, and the consent gate. Concepts:
+[Consent forms](../explanation/consent-forms.md).
+
+```typescript
+import {ConsentApp, TerrenoApp} from "@terreno/api";
+
+new TerrenoApp({userModel: User})
+  .register(new ConsentApp({accessControl: access, auditTrail: true}))
+  .start();
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `accessControl` | — | RBAC access control. When set, roles granting `consentResponse:signOnBehalf` may sign provisionally for other users. When unset, only `user.admin` may, and register logs a warning |
+| `auditTrail` | `false` | Store IP address, user agent, and content snapshots on responses, and mount `GET /consents/audit/:userId` |
+| `resolveConsentForms` | — | `(user, forms) => forms` narrows the active forms that apply to a user |
+| `supportedLocales` | — | Accepted for app configuration; `ConsentApp` does not read it |
+| `aiConfig` | — | `{generateContent, translateContent}` enables `POST /consent-forms/generate` and `/translate` |
+
+### Endpoints
+
+| Method + path | Who | Description |
+| --- | --- | --- |
+| `GET/POST/PATCH/DELETE /consent-forms` | admin | Form CRUD |
+| `POST /consent-forms/:id/publish` | admin | Copy the form to `version + 1`, activate it, deactivate other versions |
+| `GET /consent-responses`, `GET /consent-responses/:id` | admin | Read responses, populated with form and user |
+| `POST /consent-responses/provisional` | sign-on-behalf | Record a provisional signature for another user |
+| `GET /consent-responses/status?userId=` | sign-on-behalf | Consent status of each form that applies to a user |
+| `POST /consent-responses/:id/void` | sign-on-behalf | Void a provisional signature made in error |
+| `GET /consents/pending` | user | Active forms the user has not answered themselves at the current version |
+| `POST /consents/respond` | user | `{consentFormId, agreed, locale, checkboxValues?, signature?}` |
+| `GET /consents/my` | user | The user's own responses with form data |
+| `GET /consents/audit/:userId` | admin | Full audit history (only with `auditTrail`) |
+
+"sign-on-behalf" means an authenticated user with `consentResponse:signOnBehalf` when
+`accessControl` is set, otherwise `user.admin`. Others get 405.
+
+### `POST /consent-responses/provisional`
+
+Body: `{userId, consentFormId, note, locale?}`. `note` is required, trimmed, and at most 2000
+characters. `locale` defaults to the form's `defaultLocale`.
+
+Creates a `ConsentResponse` for `userId` with `provisional: true`, `agreed: true`,
+`agreedAt` (server time), `provisionalSignedBy` (the caller), `provisionalNote`, and
+`formVersionSnapshot`. With `auditTrail`, it also stores `contentSnapshot`,
+`provisionalSignerIp`, and `provisionalSignerUserAgent`. `ipAddress`, `userAgent`,
+`signature`, and `signedAt` stay unset: they describe the user's own device and signature.
+
+Returns `{data: ConsentResponse}` with `provisionalSignedBy` populated as `{_id, name, email}`.
+The form stays in the target user's `/consents/pending` until they respond themselves.
+
+| Status | When |
+| --- | --- |
+| 400 | Missing or invalid ids, blank or too-long note, `userId` is the caller, inactive form, or the form is filtered out for the target user by `resolveConsentForms` |
+| 404 | Unknown user or form |
+| 405 | The caller may not sign on behalf of others |
+
+With `AuditApp` registered, each provisional signature writes an `AuditEvent`
+(`modelName: "ConsentResponse"`, `operation: "create"`, `after: {action: "signOnBehalf",
+userId, consentFormId}`, `actorId`: the signer).
+
+`/consent-responses` and its actions are in OpenAPI, so `bun run sdk` generates
+`useConsentresponsesProvisionalMutation`, `useConsentresponsesStatusQuery`, and
+`useConsentresponsesVoidMutation`. The other
+ConsentApp routes are not in OpenAPI.
+
+### `POST /consent-responses/:id/void`
+
+Body: `{reason}` (required, trimmed, at most 2000 characters). Sets `voidedAt`, `voidedBy`
+(the caller), and `voidReason` on a provisional response and returns
+`{data: ConsentResponse}` with `provisionalSignedBy` and `voidedBy` populated. The record is
+never deleted. A voided signature no longer counts: `getConsentStatuses` ignores it, and
+`/consents/pending` drops its `provisionalSignature`.
+
+| Status | When |
+| --- | --- |
+| 400 | Blank or too-long reason, the response is not provisional, or it is already voided |
+| 404 | Unknown response |
+| 405 | The caller may not sign on behalf of others |
+
+With `AuditApp` registered, each void writes an `AuditEvent` (`operation: "update"`,
+`verb: "updated"`, `after: {action: "voidProvisional", userId, consentFormId}`).
+
+### `GET /consent-responses/status` and `getConsentStatuses`
+
+`GET /consent-responses/status?userId=<id>` returns `{data: ConsentStatusRow[]}`, one row per
+active form that applies to the user (after `resolveConsentForms`), in form order. 400 when
+`userId` is missing or malformed, 404 for an unknown user, 405 for callers who may not sign
+on behalf of others. With `AuditApp` registered, each read writes an `AuditEvent`
+(`operation: "read"`, `verb: "viewed"`, `after: {action: "viewStatus", userId}`).
+
+The same rows come from the exported helper, for server code that needs the "considered
+signed" answer:
+
+```typescript
+import {getConsentStatuses} from "@terreno/api";
+
+const rows = await getConsentStatuses({userId, resolveConsentForms});
+const allConsented = rows.every((row) => row.isConsented);
+```
+
+```typescript
+interface ConsentStatusRow {
+  form: ConsentStatusForm; // the form as clients receive it: string ids, content as an object
+  status: "pending" | "provisional" | "signed" | "declined";
+  isConsented: boolean; // true for "signed" and "provisional"
+  respondedAt?: Date; // agreedAt of the response that decided the status
+  provisional?: {
+    responseId: string;
+    signedAt: Date;
+    signedBy: {id: string; name?: string; email?: string} | null;
+    note?: string;
+  };
+}
+```
+
+Only non-voided responses to each form's current version count:
+
+1. The user's own latest response decides: `agreed` → `signed`, declined → `declined`.
+2. Otherwise a provisional response → `provisional`.
+3. Otherwise → `pending`.
+
+`provisional` is set whenever a provisional response exists for the current version, even
+when the user's own answer decides the status. The helper throws `APIError` 400 for a
+malformed `userId` and 404 for an unknown user.
+
+### Admin columns
+
+The "Consent Responses" admin model lists `provisional`, offers a "Provisional" boolean
+filter, and populates `provisionalSignedBy` (`name`, `email`).
+
+### Provisional data on user-facing payloads
+
+The user sees who signed on their behalf and when. They never see the signer's note or the
+signer's request metadata.
+
+| Endpoint | Adds |
+| --- | --- |
+| `GET /consents/pending` | `provisionalSignature?: {signedAt, signedByName}` on each form, from the latest non-voided provisional response for the form's current version. Absent when there is none. Provisional responses never remove a form from this list |
+| `GET /consents/my` | `provisional: boolean`, `provisionalSignedBy: {name} \| null`, and `voidedAt` on each entry. No note, IP, or user agent of the signer, and no void reason |
+| `GET /consents/audit/:userId` | `provisional`, `provisionalSignedBy: {_id, name, email} \| null`, `provisionalNote`, `provisionalSignerIp`, `provisionalSignerUserAgent`, `voidedAt`, `voidedBy: {_id, name, email} \| null`, `voidReason` |
+
+`signedByName` falls back to the signer's email, then `"Staff"`.
+
+### RBAC
+
+`terrenoStatements.consentResponse` is `["list", "read", "signOnBehalf"]`. The built-in
+`admin` role grants `consentResponse: ["signOnBehalf"]`. Seeding adds it to existing unsealed
+`admin` roles without removing other grants. `superadmin` has every action.
+
+### Response fields
+
+| Field | Notes |
+| --- | --- |
+| `provisional` | `false` by default; `true` only on responses from `/consent-responses/provisional` |
+| `provisionalSignedBy` | User ref; required when `provisional` |
+| `provisionalNote` | Required when `provisional`; max 2000 characters |
+| `provisionalSignerIp`, `provisionalSignerUserAgent` | Signer's request metadata, with `auditTrail` |
+| `voidedAt`, `voidedBy`, `voidReason` | Set only by the void action |
+
 ## In-app notifications
 
 Owner-scoped inbox and channel preferences via `NotificationsApp` (`ConsentApp` pattern).