@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.10

package/docs/handbook/cloudflare/authentication.md

@@ -1,355 +1,213 @@
----
-description: Configure MANTLE_AUTH_MODE, secrets, the first owner and staff roles; understand which routes need a session.
----
-# Authentication
+# Auth in Mantle
+
+Your application configures `betterAuth()` and its official plugins in `auth.ts`.
+Mantle supplies the database adapter, schema generation and caller resolution:
+
+| Mantle | What it does |
+| --- | --- |
+| `@aotter/mantle/auth/adapter` | `d1Adapter(env.DB)` / `postgresAdapter(sql)`: Better Auth's `database` on the same native handle as your data, no Kysely. `postgresAdapter` takes the PostgreSQL client the data layer uses, postgres.js (`cloudflare-postgres`, usually through Hyperdrive) or Bun.SQL; on Workers create that client per request, or per isolate with `max: 1`. Both pass Better Auth's official adapter suite (`@better-auth/test-utils/adapter`). |
+| `mantle generate … --auth ./auth.ts` | Adds the tables Better Auth declares for your options (`getSchema`) to `schema.sql`. |
+| `@aotter/mantle/generate/auth` | Programmatic `generateFromSources({ target, sources, auth: authOptions, ... })`; the selected entry types `auth` as Better Auth options. |
+| `@aotter/mantle/auth` | `authLoader` and `resolveCaller(request, loader, { audience })`: the `Caller` that generated queries take. |
+
+## `auth.ts`
 
-Conventional Auth is chosen by one variable, `MANTLE_AUTH_MODE`, and fails closed when its configuration is incomplete. This page covers the two modes, the secrets each needs, first-owner bootstrap, roles, the routes that require a session, and the Better Auth integration surface.
+> **Verification status:** the GitHub social-provider and magic-link recipes have not yet been exercised end to end against real deployed provider flows.
+
+Copy `src/auth.ts` from the [app shell](../../examples/app-shell/README.md), which CI runs from the packed packages;
+installed, it is `node_modules/@aotter/mantle/docs/examples/app-shell/src/auth.ts`. Its essentials:
 
-## Local Admin: email OTP
+- Imports: `betterAuth` from `better-auth/minimal`; `admin`, `emailOTP` (and `jwt` for MCP) from `better-auth/plugins`;
+  `createAccessControl` from `better-auth/plugins/access`; `defaultStatements` from `better-auth/plugins/admin/access`;
+  `d1Adapter` from `@aotter/mantle/auth/adapter`; the hardening and bootstrap helpers below. For MCP it also imports `jwt`,
+  `mcp` from `@better-auth/mcp`, `cimd` from `@better-auth/cimd` and `oauthGrantExtension`/`oauthGrantRevocation` from
+  `@aotter/mantle/auth/oauth`; the file marks that block as deletable.
+- `authOptions(env)` returns plain options and is the module's export for `--auth src/auth.ts`. Generation calls it with an
+  empty `env`, so it must not throw: fall back to placeholders for `secret` and origin there.
+- The bootstrap admin: `d1BootstrapAdmin(env.DB, { match: "email", value: env.ADMIN_EMAIL }, () => ({ options: { plugins } }))`
+  is assigned to `databaseHooks.user.create.after` and `.update.after` ([Identity helpers](#identity-helpers)).
+- `createAuth(env)` is the same module's second export: it checks its three variables are set and returns
+  `betterAuth(authOptions(env))`. The Worker's `authLoader(() => import("./auth.js").then(m => m.createAuth(env)))`
+  ([service composition](service-entry.md)) is what calls it.
 
-The generated CF app writes `.dev.vars.example`. Copy it to `.dev.vars` for
-local use, then set `MANTLE_AUTH_MODE=local-otp`, the real `ADMIN_EMAIL`, a
-random `BETTER_AUTH_SECRET`, and the exact loopback `PUBLIC_ORIGIN`. It configures
-its email-OTP auth factory only for a
-loopback origin. If you author the Worker yourself, pass `auth` to
-`createMantleWorker` with `email-otp`, `ConsoleEmailSender`, and
-`bootstrapOwner.match: "email"`; that factory does not read the conventional
-mode matrix. The one-time code is printed in wrangler logs. See
-[Quickstart: local Admin](../start/quickstart-admin.md). `ConsoleEmailSender`
-is for `wrangler dev` only; production needs a real sender. Match
-`PUBLIC_ORIGIN` to wrangler's actual `127.0.0.1:8787` origin or Better Auth
-will reject OTP with `INVALID_ORIGIN`.
+The application owns Better Auth and its optional plugins. Schema generation reads plain options without constructing
+Better Auth; apply `schema.sql` during deployment, never at boot. OAuth resource
+rows are created on first OAuth use from runtime configuration; they require no
+resource deployment step.
 
-For production, the generated Worker's local OTP branch is disabled outside
-loopback. Configure the conventional `self-managed` or `hosted` Auth mode,
-including its required provider credentials and `ADMIN_GITHUB_LOGIN`, instead
-of editing the CLI-owned Worker. An application that needs production email
-delivery should author its own Worker Auth factory and real `EmailSender`.
+OSS uses `admin({adminRoles: ["admin"], ac, roles: {admin: ac.newRole(defaultStatements), user: ac.newRole({user: [], session: []})}})`.
+Mantle reads the official admin plugin’s `adminRoles` when auth loads (default `["admin"]`); it has no role setting of its own. `Caller.role` preserves comma-separated roles and `Caller.admin` carries the layer. A caller holding any configured admin role is an admin; a member’s role names never grant privilege. Publishing, Admin and `/mcp/admin` read this layer. Better Auth still checks permissions for its identity API calls.
 
-With `auth` set, the mode matrix below is not read. Core still owns `/admin` and `/api/auth/*`.
+`@aotter/mantle/auth/hardening` supplies optional helpers:
 
-For production email OTP in a manually authored Worker, keep the custom `createAuth()` factory, replace
-`ConsoleEmailSender` with the application's production `EmailSender`, and keep
-`bootstrapOwner: { match: "email", value: <owner email> }`. Store the sender
-credentials and `BETTER_AUTH_SECRET` as Worker secrets. If the application has
-no transactional-email provider, use self-managed GitHub OAuth instead; never
-deploy console delivery.
+- `hashEmailOtp(secret, otp)` is keyed HMAC-SHA-256. Pass it as emailOTP's `storeOTP.hash`; an unkeyed hash permits enumeration of six-digit codes after a database leak.
+- `authHardening({ipAddressHeaders, baseURL, errorURL})` refuses missing host-trusted ingress headers and cross-origin error redirects, and enables Better Auth's rate limiter with `storage: "database"`, which the Better Auth docs recommend for serverless: counts are shared across isolates, and Better Auth's defaults and plugin rules (for example 3 per minute per email-OTP path) set the limits. The generated schema includes the `rateLimit` table. Never assume client X-Forwarded-For is trusted.
+- `guardGithubLogin(user, context, trustedProviders)` goes in user create/update before-hooks. Only explicitly trusted provider callbacks can populate this field. GitHub maps `githubLogin: profile.login`; generic OAuth ids need trusted profile mappers.
+- `withAuthTasks(ctx.waitUntil.bind(ctx), () => auth.handler(request))` retains background sends/cleanup for the current request, with concurrent requests isolated. `authHardening` installs `retainAuthTask` as Better Auth's background handler. Failure logs are generic and contain no OTPs/credentials.
+- `authSetupIncomplete()` returns 503/no-store while secrets/providers are unconfigured; do not authenticate by fallback.
 
-## Mode matrix
+Better Auth config is app-owned, so restrict who may sign up (an allowlist, an invitation) with a
+`databaseHooks.user.create.before` hook that throws `APIError("FORBIDDEN")` from `better-auth/api` (the app shell calls
+`src/signup.ts` there; returning `false` instead breaks email-OTP sign-in in Better Auth 1.7.7, which does not expect a refused create).
 
-| Mode | Non-secret vars | Worker secrets | Must be absent |
-|---|---|---|---|
-| `self-managed` | `MANTLE_AUTH_MODE=self-managed`, `PUBLIC_ORIGIN`, `GITHUB_CLIENT_ID`, `ADMIN_GITHUB_LOGIN` | `GITHUB_CLIENT_SECRET`, `BETTER_AUTH_SECRET` | `MANTLE_HOSTED_AUTH_ISSUER`, `MANTLE_HOSTED_AUTH_CLIENT_ID` |
-| `hosted` | `MANTLE_AUTH_MODE=hosted`, `PUBLIC_ORIGIN`, `MANTLE_HOSTED_AUTH_ISSUER`, `MANTLE_HOSTED_AUTH_CLIENT_ID`, `ADMIN_GITHUB_LOGIN` | `BETTER_AUTH_SECRET` | `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` |
+Magic links use hashed tokens, 15-minute expiry and the same task retention. Email callbacks pass the first
+Accept-Language tag (fallback `en`) to the app's sender. `authRoutes` (as the app shell mounts it) also guards raw Better Auth `/admin/*` routes with the fresh database-backed Caller and the shared session origin check, so a stale KV role cannot bypass the directory gate. Mount that handler when selecting session KV. Configure ordinary Better Auth social providers;
+Apple needs `https://appleid.apple.com` trusted origin and secure SameSite=None callback cookies. Generic OAuth login
+uses `genericOAuth`, distinct provider ids and discovery or explicit authorization/token URLs. Cookie prefixes,
+account linking and trusted origins remain app-owned. Host-only cookies require HTTPS, secure/path=/, a `__Host-`
+prefix and no Domain/cross-subdomain sharing.
 
-Validation rules:
+For OAuth/MCP add `jwt({disableSettingJwtHeader:true})`, official `mcp` plus `cimd` for client metadata discovery,
+or `oauthProvider` for ordinary OAuth. These are optional app dependencies behind the dynamic auth import.
+Use the live grant/session hooks and route wiring in [OAuth](../guides/oauth.md); merge verification hooks with the app shell's
+user hooks. `genericOAuth` is a login plugin, distinct from the OAuth provider.
 
-- `PUBLIC_ORIGIN` is the site's HTTPS origin without a trailing slash. When unset, the adapter falls back to `http://localhost:8787`. That fallback string is not the preferred local Admin pin. The origin wrangler prints is authoritative; the Admin OTP reference binds `127.0.0.1:8787` and sets `PUBLIC_ORIGIN` to the same origin.
-- Self-managed uses the site's own GitHub OAuth app. Register its callback URL as `<PUBLIC_ORIGIN>/api/auth/callback/github`.
-- Hosted is a public PKCE client with no client secret. `MANTLE_HOSTED_AUTH_ISSUER` must be an HTTPS root origin (no path, query or fragment; `http` only for loopback). `MANTLE_HOSTED_AUTH_CLIENT_ID` must be a URL on that same origin shaped `/clients/<id>`.
-- `ADMIN_GITHUB_LOGIN` must be a valid GitHub login.
+## Identity helpers
 
-Any missing, invalid, partial or mixed-mode configuration produces a setup-incomplete Auth instance instead of a working one.
+`@aotter/mantle/auth/identity` exports `d1Identity(db, auth, caller, request.headers)` and
+`postgresIdentity(sql, auth, caller, request.headers)` (Bun.SQL/postgres.js). Helpers use the template's default
+Better Auth table/field names. Every operation requires a current admin cookie session.
 
-## `503 setup_incomplete`
+Methods: `listUsers()` lists all admin; `listMembers({search,limit,cursor,cursorDirection})` searches id/name/email
+(literal LIKE), pages 1–100 and supports forward/backward opaque cursors bound to normalized search;
+`setUserRole(id, "admin" | null)`, `inviteUser(email)`, `revokeInvite(id)`, `deleteUser(id)`.
+Only identity fields reach outputs, never tokens/internal columns. Self-demotion/deletion is refused. Inviting an existing
+member grants admin only after email verification; an unverified existing account is refused. Revocation deletes only an unverified admin invitation with no linked account. Deletion clears OTP
+records first and delegates user/session/cache cleanup to Better Auth. Invitation email is an optional email-module step
+after success; invitations still work when email is absent.
 
-With incomplete Auth, public routes keep working: public Views, public HTTP Triggers, public pages, `.md` mirrors, `llms.txt` and the sitemap. Auth-owned private routes return:
+`d1BootstrapAdmin(db, {match: "email" | "github-login", value}, () => auth)` / `postgresBootstrapAdmin(sql, rule, () => auth)` return
+`databaseHooks.user.create.after` (and user.update.after for a later email verification). Only the first matching signup wins (case-insensitive); email matching requires emailVerified=true (required for bootstrap).
+D1 uses one conditional UPDATE; PostgreSQL uses a transaction advisory lock before UPDATE, avoiding concurrent winners.
+A blocked promotion logs a warning. A GitHub rule requires a configured trusted GitHub provider/profile mapper.
+The promotion runs after Better Auth creates the user, so the first sign-in response (and a cached session payload) can still show the previous role, while authorization re-reads the role on every request and `/admin/api/me` and later sessions show the admin role.
+Helpers run no boot queries or DDL.
 
-```json
-{ "error": "setup_incomplete", "message": "Self-managed Auth configuration errors: BETTER_AUTH_SECRET is not set; ..." }
-```
-
-with status `503` and `private, no-store`. The affected paths are `/admin` and `/admin/*`, `/api/auth` and `/api/auth/*`, `/oauth` and `/oauth/*`, `/.well-known/oauth*`, `/mcp` and `/mcp/*`. The message lists every failing check.
-
-## Secrets and local values
-
-```sh
-wrangler secret put BETTER_AUTH_SECRET
-wrangler secret put GITHUB_CLIENT_SECRET   # self-managed only
-```
-
-Non-secret vars go in `wrangler.jsonc` under `vars`. For local development put the same names in `.dev.vars`, which the minimal reference ignores in git (`.dev.vars*`). Never commit a secret.
-
-## First owner
+## Worker entry
 
-Every new user receives the default role `user`, which has no staff access. The first sign-in whose GitHub login matches `ADMIN_GITHUB_LOGIN` is promoted to `owner`. Promotion is blocked once any staff user exists, so the variable only bootstraps an empty site.
+Keep auth behind authLoader with a dynamic import of the app-owned auth module. Pass resolveCaller the request, loader, expected MCP audience and outgoing responseHeaders. Preserve returned Set-Cookie headers so sessions can slide. Share a lazy request-local resolver with auth/consent/Admin/MCP/REST; public anonymous routes can avoid auth. See [service composition](service-entry.md) for wiring.
 
-## Roles
+Invalid presented bearer credentials fail rather than becoming anonymous. Fresh session authority comes from Better Auth's primary result; role, ban and revocation checks remain live. Custom cookiePrefix must match the loader; renamed session_token cookie names are refused.
 
-Staff roles are `owner`, `editor` and `contributor`, in descending order. Owners manage them in Admin; the underlying routes are:
+## Build: keep Better Auth out of startup
 
-| Route | Minimum role |
-|---|---|
-| `GET /admin/api/staff`, `PATCH /admin/api/staff/:id/role` (a role or `null` to revoke) | `owner` |
-| `POST /admin/api/staff/invitations`, `DELETE /admin/api/staff/invitations/:id` | `owner` |
-| `GET /admin/api/site-settings`, `PATCH /admin/api/site-settings` | `owner` |
-| `GET /admin/api/members` | `editor` |
-| `POST /admin/api/entries/:id/publish`, `POST /admin/api/entries/:id/unpublish`, `DELETE /admin/api/entries/:id` | `editor` |
+Use the [Workers build instructions](../../../README.md#workers-build).
+The metafile startup guard rejects static Better Auth imports; keep auth behind
+`authLoader(() => import(...))`.
 
-The staff role is re-read from D1 on every protected REST and MCP call; a revoked role takes effect on the next request. Manifest-level rules such as `requires.auth` are covered in [Authorization](../concepts/authorization.md) and the [authorization reference](../reference/authorization.md).
+## Schema
 
-## What needs a session
+`mantle generate <target> <out> <manifest>… --auth ./auth.ts` calls the module's `authOptions` with an empty env
+(the tables depend on plugins and options, not env values; nothing is constructed) and appends Better Auth's tables to `schema.sql`. Nothing runs DDL at runtime; migrations
+are yours (#1463).
+
+For programmatic auth generation, import `generateFromSources` from
+`@aotter/mantle/generate/auth`, not the bare `/generate` entry. Both use the
+same generator; the selected entry preserves Better Auth's option types while
+bare generation requires no optional auth peer in its public declarations.
+Pass plain options rather than constructing Better Auth to obtain the schema.
+The CLI's `--auth` selects this path automatically.
 
-| Surface | Requirement |
-|---|---|
-| `/admin`, `/admin/api/*` | Staff session; role gates per route |
-| `/api/auth/*`, `/oauth/*`, `/.well-known/oauth*` | Auth-owned; public endpoints of the OAuth flow |
-| `/mcp` | Same caller resolution as HTTP routes (bearer, same-origin cookie session, or anonymous); each tool's `requires` gates the call, and a call that needs identity answers `401` with a `WWW-Authenticate` challenge |
-| `/mcp/staff` | Authenticated caller with a staff role |
-| `/<locale>/<segment>/<slug>?preview=1` | Staff session (`401` without a session, `403` without a staff role) |
-| Public Views, public HTTP Triggers, public pages, `.md`, `llms.txt`, sitemap | None, unless the manifest declares `requires` |
+Native adapters enable Better Auth joins by default. Without secondaryStorage, fresh cookie authorization uses Better Auth's primary session/user result with disableCookieCache. Passing responseHeaders permits the same call to slide a due cookie. An explicit advanced.database.joins:false retains separate-read behavior. Authority reflects the primary result at that read; a later concurrent revocation applies on the next request.
 
-MCP tokens are session-bound: signing out of Admin ends MCP access. See [MCP and agents](../concepts/mcp-and-agents.md).
+### Explicit read-only cookie snapshots
 
-## Session cache and database replacement
-
-When optional session caching is enabled, the cache is derived from the
-canonical store, not a second identity authority. Auth prefixes keys with
-`better-auth:<store-instance-id>:`. Preparing a new store gives it a distinct
-identity, so reusing the same KV namespace after replacing D1 cannot resurrect
-the previous store's cached sessions. Ordinary preparation of the same store
-preserves its identity.
-
-Custom low-level Auth composition must prepare the Mantle store before cached
-Auth operations; do not construct cache keys or seed the identity yourself.
-OTP verification remains in the primary database and rate limiting remains
-isolate-local. Revocation/user-update cache invalidation still follows KV
-propagation; the namespace change is isolation across stores, not a promise of
-instant global invalidation. See the [Auth decision](../../adr/0014-auth-better-auth-and-multi-tenant-mcp.md).
-
-## Better Auth configuration
-
-`createAuth()` owns the Worker lifecycle, Admin metadata, sender integration,
-bootstrap rules, roles and MCP invariants. Method-specific configuration stays
-native to Better Auth under `options`, so provider updates and type inference do
-not need a matching Mantle DSL update. There is deliberately no
-`Partial<BetterAuthOptions>` deep merge.
+Authority remains fresh by default. An application may pass `readOnly: true`
+only for a positively classified read. Enable Better Auth's official cache in
+app-owned auth options:
 
 ```ts
-methods: [
-  {
-    kind: "social",
-    provider: "google",
-    options: { clientId: env.GOOGLE_CLIENT_ID, clientSecret: env.GOOGLE_CLIENT_SECRET, accessType: "offline" },
-  },
-  {
-    kind: "social",
-    provider: "apple",
-    options: async () => ({ clientId: env.APPLE_CLIENT_ID, clientSecret: await loadAppleSecret(env) }),
-  },
-  {
-    kind: "email-otp",
-    sender,
-    options: { otpLength: 8 },
-  },
-]
+session: {
+  cookieCache: { enabled: true, maxAge: 60, refreshCache: false, version: "read-60-v1" },
+}
 ```
 
-Email OTP storage defaults to a keyed HMAC-SHA-256 of the code using
-`BETTER_AUTH_SECRET`. Magic-link tokens remain `hashed` (high-entropy).
-Explicit official overrides remain available, including `plain` and custom
-hashing/encryption:
-
-```ts
-{ kind: "email-otp", sender, options: {
-  storeOTP: { encrypt: encryptOtp, decrypt: decryptOtp },
-} }
-{ kind: "magic-link", sender, options: {
-  storeToken: { type: "custom-hasher", hash: hashMagicToken },
-} }
-```
-
-For complete callback ownership, register an official plugin instance directly.
-Raw plugins do not add a button to `Auth.methods`; the application owns that UI.
-Duplicate plugin ids fail at construction rather than silently replacing one:
-
-```ts
-createAuth({
-  database: env.DB,
-  baseURL: env.PUBLIC_ORIGIN,
-  secret: env.BETTER_AUTH_SECRET,
-  methods: [],
-  plugins: [emailOTP({ sendVerificationOTP, storeOTP: "encrypted" })],
-});
-```
-
-When several first-party apps share one parent domain that the same party controls, configure shared cookies explicitly. `cookiePrefix` is required whenever more than one Better Auth app writes cookies under that domain; `trustedOrigins` is the auth-flow trust list, not a CORS policy.
-
-```ts
-const auth = createAuth({
-  database: env.DB,
-  baseURL: "https://platform.example.com",
-  secret: env.BETTER_AUTH_SECRET,
-  methods,
-  trustedOrigins: ["https://example.com", "https://www.example.com"],
-  cookiePrefix: "example-platform",
-  crossSubDomainCookies: { enabled: true, domain: "example.com" },
-});
-```
-
-Shared cookies do not cross registrable domains. A browser never sends an `example.com` cookie to `customer.com`. For a customer-owned domain, use an OAuth/OIDC broker flow: the customer site redirects to the identity provider's authorize endpoint, receives the callback, verifies the response and creates its own local session. The broker returns identity; the customer site remains the authority for its members and grants.
-
-### Account linking across providers
-
-One person signing in with Google, then with GitHub, may land on one user row
-or be refused — Better Auth decides this, and `createAuth()` does not override
-it. Left unconfigured, Better Auth's own defaults apply: implicit linking is
-on, so a social sign-in whose provider reports a verified email attaches to the
-existing row carrying that email. It never creates a second row for the same
-address; when linking is not permitted the sign-in fails with
-`account not linked`.
-
-Two defaults are worth knowing before you change anything. `requireLocalEmailVerified`
-is on, so linking is refused while the *local* row is still unverified — this is
-what stops someone pre-registering an unverified row at your user's address and
-having that user's Google identity attach to it. It is also why a staff invitation
-(`inviteUser` writes `emailVerified: 0`) cannot be claimed by a social sign-in
-until the invitee verifies by email once. Separately, `trustedProviders` is
-empty, so every provider must supply `email_verified` to link at all.
-
-Pass `accountLinking` to scope this. It is forwarded verbatim:
-
-```ts
-const auth = createAuth({
-  database: env.DB,
-  baseURL: env.PUBLIC_ORIGIN,
-  secret: env.BETTER_AUTH_SECRET,
-  methods,
-  accountLinking: {
-    // Accept these providers' word without an `email_verified` claim.
-    trustedProviders: ["google", "github"],
-  },
-});
-```
-
-Listing a provider in `trustedProviders` asserts that it verifies the addresses
-it returns; a provider that does not turns the list into an account-takeover
-path. To go the other way and keep every identity separate, set
-`disableImplicitLinking: true` (users may still link deliberately via
-`linkSocial()` while signed in) or `enabled: false` to refuse linking outright.
-
-## Self-hosted and hosted
-
-A free self-hosted site runs every method `createAuth()` exposes: Better Auth social providers, email OTP, magic link, and parent-domain SSO. The owner supplies provider credentials, email sending and cookie policy. Hosted auth is an operations convenience: the platform holds provider and email configuration and registers the site as a PKCE client, while the site still owns grants, members, content and `ctx.user`/`ctx.staff` mapping. Neither mode changes the runtime's authorization vocabulary.
-
-## Replacing Auth construction
-
-```ts
-createMantleWorker({
-  plan,
-  auth: (env) => createAuth({ /* curated, site-specific methods */ }),
-});
-```
-
-With `auth` set, `MANTLE_AUTH_MODE` and the mode variables are not read. Core still owns the Auth routes: the factory's `basePath` joins the reserved paths, the MCP resource defaults to `auth.mcpResource ?? <PUBLIC_ORIGIN>/mcp`, and a rejected `auth.ready` evicts the isolate's assembly. Keep the D1 `DB` binding; Better Auth tables live there.
-
-## OAuth resource primitives
-
-When one Mantle site is an OAuth client of another, request a stable RFC 8707
-resource and use standard `offline_access` when refresh is needed:
-
-```ts
-const clientAuth = createAuth({
-  // database, baseURL, secret, other methods...
-  methods: [{
-    kind: "oauth",
-    options: {
-      providerId: "mantle-platform",
-      clientId: env.PLATFORM_CLIENT_ID,
-      discoveryUrl: "https://platform.example.com/api/auth/.well-known/openid-configuration",
-      scopes: ["openid", "offline_access", "accounts:read"],
-      authorizationUrlParams: { resource: "https://api.example.com" },
-      tokenUrlParams: { resource: "https://api.example.com" },
-      refreshTokenParams: { resource: "https://api.example.com" },
-    },
-  }],
-});
-
-const { accessToken, accessTokenExpiresAt, scopes } =
-  await clientAuth.getProviderAccessToken(request, "mantle-platform");
-```
-
-The server-side getter is bound to the current local session request and never
-returns a refresh token or account row. On the provider:
-
-```ts
-const providerAuth = createAuth({
-  // database, baseURL, secret, methods...
-  oauthProvider: {
-    loginPage: "/sign-in",
-    consentPage: "/consent",
-    scopes: ["openid", "offline_access", "accounts:read"],
-    resources: ["https://api.example.com"],
-  },
-});
-
-const verification = await providerAuth.verifyOAuthAccessToken(request, {
-  audience: "https://api.example.com",
-  scopes: ["accounts:read"],
-});
-```
-
-The verifier accepts JWT access tokens only and checks the configured issuer,
-JWKS/signature, audience, time claims, required scopes, and—when passed the
-request—DPoP proof binding with database-backed replay protection. It returns
-only `userId`, `clientId`, `credentialId`, and scopes. Opaque tokens are
-rejected; there is no introspection fallback.
-
-## Enterprise-Managed Authorization
+A valid signed cache hit avoids Caller DB reads. Missing, tampered, expired or version-mismatched snapshots fall back to primary authority. The SDK accepts this opt-in only without secondaryStorage, with explicit maxAge from 1 to 60 seconds and refreshCache:false. KV gains no cache-authority guarantee; bearer grant checks remain live.
 
-MCP's [Enterprise-Managed Authorization](https://modelcontextprotocol.io/extensions/auth/enterprise-managed-authorization)
-extension lets an enterprise IdP decide which employees may reach an MCP
-server. The MCP client exchanges the user's IdP login for an ID-JAG (identity
-assertion authorization grant) and presents it to the server's token endpoint
-as `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer`; no consent page
-is shown. Everything after that is an ordinary access token.
+Revocation, bans and role changes reach cached reads within `maxAge` (at most
+60 seconds). Sign-out clears both the session-token and cache cookies. Bearer
+tokens still use their live grant query on every request.
 
-Core does not know any issuer or JWKS. The token grant is a
-`@better-auth/oauth-provider` extension supplied by the adopter through
-`oauthProvider.extensions`, appended after Core's own claims extension:
+Generated REST, MCP and web boundaries pass `{ readOnly }` as the third argument
+to the application's caller callback. Forward it to `resolveCaller`:
 
 ```ts
-import { identityAssertionAuthorizationGrant } from "@aotterclam/id-jag";
-
-const auth = createAuth({
-  // database, baseURL, secret, methods...
-  oauthProvider: {
-    loginPage: "/admin/sign-in",
-    consentPage: "/oauth/consent",
-    scopes: ["mcp", "offline_access"],
-    mcpResource: env.PUBLIC_ORIGIN + "/mcp",
-    extensions: [
-      identityAssertionAuthorizationGrant({
-        issuer: env.ENTERPRISE_IDP_ISSUER,
-        jwksUrl: env.ENTERPRISE_IDP_JWKS_URL,
-        authorizationServer: env.PUBLIC_ORIGIN,
-        resource: env.PUBLIC_ORIGIN + "/mcp",
-        scopes: ["mcp"],
-        fetchJwks: (input, init) => fetch(input, { ...init, redirect: "manual" }),
-      }),
-    ],
-  },
-});
+const caller = (request: Request, _env: Env, authority = { readOnly: false }) =>
+  resolveCaller(request, loader, { ...authority, responseHeaders });
 ```
 
-The extension validates the assertion's signature, issuer, audience and
-lifetime, maps its subject to a user, and issues tokens through the provider's
-shared token path, so `verifyOAuthAccessToken`, DPoP and the MCP challenge
-behave exactly as for interactive grants. `@aotterclam/id-jag` is a reference
-implementation, not a Core dependency; any `OAuthProviderExtension` works.
-Extensions may also add client-authentication strategies, discovery metadata
-and additional claims. The same passthrough applies without `mcpResource`.
-
-## Source
-- [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
-- [`packages/adapters/cloudflare/src/auth/conventionalAuth.ts`](../../../packages/adapters/cloudflare/src/auth/conventionalAuth.ts)
-- [`packages/adapters/cloudflare/src/auth/createAuth.ts`](../../../packages/adapters/cloudflare/src/auth/createAuth.ts)
-- [`packages/adapters/cloudflare/src/worker/createMantleWorker.ts`](../../../packages/adapters/cloudflare/src/worker/createMantleWorker.ts)
-- [`packages/adapters/cloudflare/src/mount/mountPublicRoutes.ts`](../../../packages/adapters/cloudflare/src/mount/mountPublicRoutes.ts)
-- [`packages/adapters/cloudflare/src/mount/mountMcp.ts`](../../../packages/adapters/cloudflare/src/mount/mountMcp.ts)
-- [`packages/mantle-admin/src/mountMantleAdmin.ts`](../../../packages/mantle-admin/src/mountMantleAdmin.ts)
-- [`docs/auth-hosting-model.md`](../../../docs/auth-hosting-model.md)
-- [`docs/adapter-guide.md`](../../../docs/adapter-guide.md)
-- [`docs/examples/host-local-admin-otp/src/index.ts`](../../../docs/examples/host-local-admin-otp/src/index.ts)
-- [`docs/examples/host-local-admin-otp/.dev.vars.example`](../../../docs/examples/host-local-admin-otp/.dev.vars.example)
-- [`docs/examples/host-minimal-worker/.gitignore`](../../../docs/examples/host-minimal-worker/.gitignore)
+REST permits cached authority only on GET/HEAD Views; HEAD returns no body.
+Web permits it only on GET/HEAD page and index reads. For Cookie requests without
+an Authorization header, MCP classifies parsed
+`initialize`, `tools/list`, `resources/list`, `resources/read`, generated View
+tools and generated native Admin media reads before resolving Caller. Generated
+metadata identifies Views versus Procedures; names and `readOnlyHint` annotations
+never make a Procedure eligible. A batch uses cached authority only if every
+message is a known read. Unknown/malformed methods or tools, mutations,
+publishing transitions and Admin writes use fresh authority. Dynamic admin tool
+implementations still load only after the admin gate; their read catalogue is
+generated separately. App-composed tool tables default to fresh authority, including tools with a
+`page` callback or read annotations, unless the
+app supplies equivalent trusted read metadata to `mcp`'s fourth argument.
+
+Auth/admin endpoints (including GET) and consent keep the default fresh resolver.
+Do not infer authority from HTTP method alone or pass `readOnly: true` for a whole
+surface. A caller callback that ignores the third argument retains the default
+primary checks. In request-local memoization, keep cached reads separate from
+fresh authority so a prior read cannot supply authority for a write.
+
+**Bump `cookieCache.version` when enabling this policy or changing its TTL or
+semantics.** A cache minted under an earlier 300-second setting retains its old
+signed expiry; changing `maxAge` alone does not shorten it. Better Auth's version
+check invalidates that snapshot. The SDK cannot infer prior deployment config.
+Sign-out clears the session-token and cache cookies; pass SDK Set-Cookie headers
+through to the browser. A copied pre-sign-out cookie can remain usable for
+read-only snapshots until TTL, while fresh authority rejects revoked sessions.
+
+With secondaryStorage, disableCookieCache does not bypass KV. Caller keeps a primary authority check before any second SDK call refreshes/forwards cookies. Stale snapshots cannot revive deleted/expired primary sessions or retain obsolete role/ban state.
+
+`authRoutes` may be imported statically: its consent/provider integration loads
+only for a matching consent request, after Caller/origin/body guards. Optional
+Better Auth adapter code stays outside the Worker startup graph.
+
+`@aotter/mantle/auth/admin` exports `guardAuthAdminRequest(request, resolveFreshCaller, basePath?)` for selected auth transports. It resolves authority only for raw/encoded admin paths, requires an admin cookie session and checks mutation origin. Both the app-owned template and OAuth routes use this same guard.
+
+Bare `ctx.admin` admits any verified admin layer classified by Better Auth's
+`adminRoles` / `adminUserIds`. Role lists in `requires` are refused; decide
+per-target permissions in `authorize(target, caller)`, using `hasAdminRole`
+when appropriate. Verified role names match `^[a-z][a-zA-Z0-9_-]{0,62}$`.
+Member role names alone grant no privilege. See
+[authorization requirements](../reference/authorization.md).
+
+The generated auth DDL adds a native `(createdAt, id)` member-paging index (respecting schema field/table names). Unfiltered forward/backward paging orders native timestamps through that index; PostgreSQL cursors retain all six fractional digits and bind as text before timestamp casting. Member search (`%term%` over id/name/email, casting UUID ids to text only in the search expression) is a full scan; the index does not accelerate it.
+
+## Several Better Auth instances in one app
+
+The default is one instance with `admin` and `user` roles. An app that keeps two populations apart (for example
+staff and customers) can run one Better Auth instance per population in the same Worker; every Mantle primitive
+takes the instance it works on:
+
+- Give each instance its own `basePath`, `advanced.cookiePrefix`, `secret` and core table names (`user.modelName`,
+  `session.modelName`, `account.modelName`, `verification.modelName`). Keep each instance's options in its own
+  module and pass one `--auth` per module to `mantle generate`; the tables are merged into one migration, and two
+  instances that define the same table differently are refused. The native adapter follows each instance's mapping.
+- Better Auth plugin factories share their schema object, so differing plugin field/model mappings across instances
+  in one Worker override each other. Use one of two supported ways:
+  1. Separate the instances by core table names only and leave every plugin mapping at its default.
+  2. When plugin tables must differ (`jwt`'s `jwks`, `@better-auth/oauth-provider`'s `oauth*` tables), map them
+     explicitly in every instance, the default one included, and give each instance its own copy of the plugin's
+     schema right after constructing it:
+     `const keys = jwt({ schema: { jwks: { modelName: "staff_jwks" } } }); const plugin = { ...keys, schema: structuredClone(keys.schema) };`
+
+  `mantle generate` refuses anything else when two or more `--auth` instances use the same plugin (`jwt`, `admin`,
+  `oauth-provider`, `two-factor`, `phone-number`, `anonymous`, `siwe`, `device-authorization`) and a mapping exists
+  while an instance keeps the shared schema object, or two instances resolve a mapping to the same name (generate
+  cannot tell an identical mapping from an inherited one, so mapped names must differ between instances). Build
+  every instance's plugins in the same order in the Worker as in `--auth`; an instance built earlier than a mapped
+  one can still inherit its mapping, which generate cannot see.
+- One `authLoader(load, cookiePrefix)` per instance; call `resolveCaller(request, loader)` with the instance the
+  route belongs to, and mount `authRoutes(loader, ...)` per instance (it guards that instance's `/admin/*`). The
+  loader takes `cookiePrefix` separately on purpose: it checks the cookie before loading Better Auth, so anonymous
+  requests never pay for it. Read both from one constant.
+- Admin signs in with the instance passed to `adminShell(request, assets, { authBasePath })`; its identity
+  directory is the instance you pass to `d1Identity` / `postgresIdentity`.

package/docs/handbook/cloudflare/chatgpt-sites.md

@@ -1,29 +1,11 @@
----
-description: "Mantle on ChatGPT Sites now has its own integration guide."
----
 # Mantle on ChatGPT Sites
 
-ChatGPT Sites has a dedicated section in the Mantle handbook. Start with
-[Mantle on ChatGPT Sites](../chatgpt-sites/index.md) for installation, supported
-capabilities, and your first published article. This page preserves earlier
-links to the host checklist.
+> **Verification status:** this guide is experimental and has not yet been exercised end to end on a real ChatGPT Site.
 
-## First deployment
+Treat the Site as an existing TypeScript host. Import selected generated Views/Procedures, pass the host's native handle and verified Caller, and compose only the surfaces it supports. Use [partial integration](../../skills/integrate/SKILL.md); Mantle supplies no Sites-specific identity or deployment adapter.
 
-See [the host deployment checklist](../chatgpt-sites/host-reference.md#first-deployment).
+Choose postgres or sqlite according to the host's actual SQL executor. Custom handles are app-owned; a structural match alone does not guarantee driver semantics. [Database boundaries](../concepts/runtime-and-adapters.md) defines the supported drivers.
 
-## Media with only an R2 binding
+The runtime never creates, alters or checks tables. Apply initial `schema.sql` and selected auth/site DDL only to an empty database. For later changes the agent diffs regenerated SQL, writes and rehearses a host-native migration on a copy, and applies it before publishing new code. Destructive/type changes require explicit data migration; Mantle drops nothing.
 
-See [R2 media integration](../chatgpt-sites/host-reference.md#media-with-only-an-r2-binding).
-
-## Remote MCP is a separate gate
-
-See [MCP support and authentication](../chatgpt-sites/host-reference.md#remote-mcp-is-a-separate-gate).
-
-## Capability boundaries
-
-See [host capability boundaries](../chatgpt-sites/host-reference.md#capability-boundaries).
-
-## Source
-
-See [integration sources](../chatgpt-sites/host-reference.md#source).
+Use the Site's native publication workflow. Configure trusted origin and verified identity there; never construct a system/admin Caller from browser input. Serving Admin also requires its app-built assets and shell security contract. Scheduling and storage provisioning belong to the host.