@aotter/mantle 0.2.0-alpha.6 → 0.2.0-alpha.8

package/docs/examples/recipes/wrangler.jsonc

@@ -0,0 +1,74 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "mantle-app",
+  "main": "dist/worker/index.js",
+  "compatibility_date": "2026-09-01",
+  "compatibility_flags": [
+    "nodejs_compat",
+    "global_fetch_strictly_public"
+  ],
+  "secrets": {
+    "required": [
+      "BETTER_AUTH_SECRET",
+      "PUBLIC_ORIGIN",
+      "ADMIN_EMAIL"
+    ]
+  },
+  "observability": {
+    "enabled": true,
+    "logs": {
+      "enabled": true,
+      "head_sampling_rate": 1
+    },
+    "traces": {
+      "enabled": true,
+      "head_sampling_rate": 0.01
+    }
+  },
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "mantle-app"
+    }
+  ],
+  // Recipe cover images (docs/handbook/cloudflare/media-r2.md). AGENT: create the bucket, serve its `committed/` prefix
+  // on a public domain, and set MEDIA_PUBLIC_BASE / MEDIA_S3_ENDPOINT below to that domain and the bucket's S3 endpoint.
+  "r2_buckets": [
+    {
+      "binding": "MEDIA",
+      "bucket_name": "mantle-app-media"
+    }
+  ],
+  "vars": {
+    "MEDIA_PUBLIC_BASE": "https://media.example.com",
+    "MEDIA_S3_ENDPOINT": "https://mantle-app-media.ACCOUNT_ID.r2.cloudflarestorage.com"
+  },
+  "assets": {
+    "directory": "dist/client",
+    "binding": "ASSETS",
+    "run_worker_first": true,
+    "html_handling": "none"
+  },
+  "triggers": {
+    "crons": []
+  },
+  "no_bundle": true,
+  "find_additional_modules": true,
+  "base_dir": "dist/worker",
+  "build": {
+    "command": "mantle bundle src/index.ts dist",
+    "watch_dir": [
+      "src",
+      "generated"
+    ]
+  },
+  "rules": [
+    {
+      "type": "ESModule",
+      "globs": [
+        "**/*.js"
+      ],
+      "fallthrough": true
+    }
+  ]
+}

package/docs/handbook/cloudflare/authentication.md

@@ -1,246 +1,196 @@
----
-description: Sign-in for a Mantle 0.2.0 service — the three identity choices, createMantleAuth with email OTP, social and OAuth methods, the first owner, roles, production senders, and a custom CallerResolver.
----
-# 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`
+
+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:
 
-Mantle never owns your users. Choose once, in `mantle.config.json`:
+- 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.
 
-| `identity` | Callers come from | Auth tables |
-|---|---|---|
-| `mantle` | `@aotter/mantle/auth`: Better Auth sign-in, staff roles, an OAuth server for MCP | Better Auth's, migrated by Better Auth |
-| `custom` | your `src/identity.ts`, a `CallerResolver` over your own sessions or tokens | none |
-| `none` | nobody: every caller is anonymous | none |
+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.
 
-A rerun of `mantle generate` cannot switch identity. Admin needs `mantle` or
-`custom`.
+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.
 
-## Identity `mantle`
+`@aotter/mantle/auth/hardening` supplies optional helpers:
 
-The generated `src/service.ts` builds the auth from `env`:
+- `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.
 
-```ts
-createMantleAuth({
-  database: env.DB, driver: d1Driver(env.DB), baseURL: origin, secret: env.BETTER_AUTH_SECRET,
-  methods: [{ kind: "email-otp", sender: new ConsoleEmailSender() }],
-  bootstrapOwner: { match: "email", value: env.ADMIN_EMAIL },
-  ipAddressHeaders: ["cf-connecting-ip"],
-  oauthProvider: { loginPage: "/admin/sign-in", consentPage: "/admin/oauth/consent", scopes: ["mcp"], mcpResource: `${origin}/mcp` },
-});
-```
+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).
 
-`consentPage` is Admin's consent page when the service mounts Admin (the
-preset does); without Admin it is `/oauth/consent`, the plain page
-`createAuthRoutes` serves. Both post the decision to `/oauth/consent`.
-
-then `createCallerResolver(auth, { jwtBearer: { audience: `${origin}/mcp`, scopes: ["mcp"] } })`,
-`createAuthRoutes(auth, { resolver })` and an `AdminIdentity` over the auth's
-own methods. With dialect `postgres` the preset passes `database:
-pgPool(connect), driver: pgDatabaseDriver(connect)` on both hosts (Hyperdrive on
-`cloudflare`, a `pg.Pool` on `bun`); host `bun` over SQLite passes the bun:sqlite
-`Database` and `bunSqliteDriver(db)`, with `ipAddressHeaders:
-["x-mantle-client-ip"]`, which its entry sets from the socket.
-
-### Local sign-in
-
-Install auth and MCP dependencies at the versions declared in the installed
-Core package's `peerDependencies`; the generator prints a versioned install
-command and refuses incompatible installed peers before writing generated files.
-The preset owns convergence; a normal fresh local database needs no manual auth
-migration. `auth.ready` initializes Better Auth's context; auth tables are prepared
-lazily before authenticated operations. Mantle runs Better Auth's explicit schema
-validation after that preparation, including when the schema ledger is current;
-an incompatible existing schema still rejects authentication.
-
-#### Upgrading an existing 1.7.0–1.7.2 auth database
-
-Those Better Auth versions created a required `account.issuer` column that
-1.7.7 no longer writes. Automatic additive convergence preserves that column;
-it cannot make a required unused column safe for future inserts. Before starting
-the upgraded service, the database owner must migrate this legacy constraint.
-Fresh databases need no such step.
-
-For PostgreSQL, first inspect the service's own database/schema and back it up:
-
-```sql
-SELECT table_schema, is_nullable, column_default
-FROM information_schema.columns
-WHERE table_name = 'account' AND column_name = 'issuer';
-```
+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.
 
-If the legacy column is required and has no default, apply this in the service's
-auth schema (the example assumes it is selected by `search_path`):
-
-```sql
-BEGIN;
-ALTER TABLE "account" ALTER COLUMN "issuer" DROP NOT NULL;
-COMMIT;
-```
+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.
 
-This retains every row and existing issuer value. It changes only the obsolete
-constraint; new accounts may leave that column null. Restart the service after
-the migration so Better Auth checks the repaired schema in a fresh context.
-Verify existing users, roles, sessions and content rows, then sign in again.
-Do not drop auth tables or disable schema validation. This applies to native Bun
-PostgreSQL and Cloudflare/Hyperdrive PostgreSQL alike.
-
-For D1/SQLite, `ALTER COLUMN` is unavailable. Use a database-owner-reviewed table
-rebuild that retains every column/value, index and foreign-key relationship while
-making the legacy issuer nullable; do not run the PostgreSQL statement there.
-See Better Auth's [1.7 upgrade guide](https://www.better-auth.com/docs/guides/1-7-upgrade-guide).
-Mantle's portable auth facade does not silently perform engine-specific table
-rebuilds or remove historical fields.
-
-```sh
-cp .dev.vars.example .dev.vars   # ADMIN_EMAIL, a random BETTER_AUTH_SECRET, PUBLIC_ORIGIN=http://127.0.0.1:8787
-pnpm exec wrangler dev --local
-curl -X POST http://127.0.0.1:8787/api/auth/email-otp/send-verification-otp \
-  -H 'content-type: application/json' -H 'origin: http://127.0.0.1:8787' \
-  -d '{"email":"you@example.com","type":"sign-in"}'
-```
+## Identity helpers
 
-`ConsoleEmailSender` prints the code to the wrangler log; post it to
-`/api/auth/sign-in/email-otp` with `{ email, otp }` to get a session cookie.
-The preset prints codes only when `PUBLIC_ORIGIN` is set to a loopback `http:`
-origin and both secrets exist. Otherwise it uses
-`createSetupIncompleteAuth`, which refuses sign-in with a message, so a
-deployed service never prints codes to its log.
+`@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.
 
-On Bun, copy `.env.example` to `.env`, set `PUBLIC_ORIGIN=http://127.0.0.1:3000`
-and run `bun src/index.ts`; send the same HTTP requests to port 3000. Codes print
-to the Bun console. Normalize test email addresses to lowercase when matching
-that output. Treat codes and session cookies as secrets in test logs.
+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.
 
-Local clients share the loopback socket IP and therefore share sign-in limits.
-Multi-user smoke tests must respect the retry window (HTTP 429) rather than
-spoofing forwarding headers or disabling production limits. `rateLimit: {
-window: 60, max: 100 }` changes the general quota, but plugin-specific OTP limits
-still apply; changing it is not a way to bypass those limits.
+`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.
+Helpers run no boot queries or DDL.
 
-### MCP clients for members
+## Worker entry
 
-`/admin/sign-in` suits staff. When members connect an MCP client to the public
-`/mcp`, set `loginPage` to the service's own sign-in page. That page must
-continue the authorization: Better Auth sends the browser there with the
-request signed, and the sign-in carries it back as `oauth_query`, then follows
-the `url` it answers (consent) instead of the page's own destination:
+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.
 
-```ts
-import { signedOAuthQuery } from "@aotter/mantle-ui/kit";
+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.
 
-const oauthQuery = signedOAuthQuery(window.location.search);
-const res = await fetch("/api/auth/sign-in/email-otp", { method: "POST", credentials: "include",
-  headers: { "content-type": "application/json" }, body: JSON.stringify({ email, otp, ...(oauthQuery ? { oauth_query: oauthQuery } : {}) }) });
-const { url } = await res.json();
-location.assign(url ?? "/account");
-```
+## Build: keep Better Auth out of startup
 
-The generated preset does not enable dynamic client registration (DCR).
-An `access_denied` response from `/api/auth/oauth2/register` does not mean
-member OAuth is broken. An owner can register a known local client through
-the public `MantleAuth` API, without opening DCR:
+Use the [Workers build instructions](../../../README.md#workers-build).
+The metafile startup guard rejects static Better Auth imports; keep auth behind
+`authLoader(() => import(...))`.
 
-```ts
-const client = await auth.registerOAuthClient({
-  requestHeaders: ownerRequest.headers,
-  clientName: "Local MCP client",
-  redirectUris: ["http://127.0.0.1:3456/callback"],
-  applicationType: "native",
-  tokenEndpointAuthMethod: "none",
-  grantTypes: ["authorization_code", "refresh_token"],
-  responseTypes: ["code"],
-  scope: ["mcp"],
-  requirePKCE: true,
-});
-```
+## Schema
 
-Use a real owner session, keep persisted user consent, and configure the MCP
-client with the returned `clientId`. This belongs in an owner-controlled
-management path, not an anonymous registration handler. Choose DCR separately
-according to the host's registration policy.
+`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).
 
-When DCR is enabled, registration takes a client that names no `application_type`
-and registers only `http` loopback redirects (`localhost`, `127.0.0.1`,
-`[::1]`) as `native` (RFC 8252), which is how local MCP clients register; any
-other registration is checked as Better Auth checks it (`web` needs `https` on a
-non-loopback host).
+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.
+
+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.
 
-### Production
+### Explicit read-only cookie snapshots
 
-Replace the local choices in `src/service.ts`:
-
-- **A real sender.** Implement `EmailSender` (`send({ to, subject, text, html?, locale, category? })`)
-  over your provider, and pass it to the email method. Drop the loopback check
-  once the sender is real.
-- **Secrets.** `wrangler secret put BETTER_AUTH_SECRET` (32+ random bytes) and
-  `wrangler secret put ADMIN_EMAIL`; set `PUBLIC_ORIGIN` to the deployed origin
-  in `vars`.
-- **Methods.** `methods` takes any mix:
+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: "email-otp", sender },
-  { kind: "magic-link", sender },
-  { kind: "social", provider: "google", options: { clientId: env.GOOGLE_CLIENT_ID, clientSecret: env.GOOGLE_CLIENT_SECRET } },
-  { kind: "oauth", displayName: "Company SSO", options: { providerId: "sso", discoveryUrl: …, clientId: …, clientSecret: … } },
-]
+session: {
+  cookieCache: { enabled: true, maxAge: 60, refreshCache: false, version: "read-60-v1" },
+}
 ```
 
-`options` is Better Auth's own configuration for that method, passed through.
-`appleClientSecret` builds Apple's signed client secret. `GET /api/auth/methods`
-lists what the service offers, for your sign-in page.
-
-Other options: `rateLimit`, `trustedOrigins`, `cookiePrefix`,
-`crossSubDomainCookies` (first-party apps under one parent domain),
-`accountLinking` (passed to Better Auth; by default a social sign-in links to
-an existing row only when the provider verified the email and the local row is
-verified), `staffInvitationSender`, `sessionCache`, and raw Better Auth
-`plugins`.
-
-### The first owner and roles
-
-`bootstrapOwner: { match: "email", value }` (or `{ match: "github-login", value }`)
-makes the first matching sign-in the `owner`. Staff roles are `owner`,
-`editor` and `contributor`; a user without one is a member. Owners manage staff
-through Admin's API (`/admin/api/staff`, `/staff/invitations`), which calls
-Better Auth's admin API with the owner's own request. The resolver reads the
-role on every request, so a revoked role takes effect at once.
-
-### Account deletion
+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.
 
-`auth.deleteUser(userId)` deletes a user through Better Auth, sessions
-included, and the email codes still pending for its address. Never delete auth
-rows with SQL. To require a recent sign-in first, compare
-`(await auth.getSession(request)).session.createdAt` with the current time.
+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.
 
-## Identity `custom`
-
-`src/identity.ts` exports `resolveCaller: CallerResolver`. It throws until you
-implement it, so a request fails loudly instead of running as anonymous.
+Generated REST, MCP and web boundaries pass `{ readOnly }` as the third argument
+to the application's caller callback. Forward it to `resolveCaller`:
 
 ```ts
-export const resolveCaller: CallerResolver = async (request) => {
-  const token = request.headers.get("authorization")?.replace(/^Bearer /, "");
-  if (!token) return { caller: { kind: "anonymous" } };   // nothing presented
-  const user = await verifyMyToken(token);                // your own auth
-  if (!user) return { invalid: true };                    // presented and bad: 401, never anonymous
-  return { caller: {
-    kind: "user", subject: `myapp:${user.id}`, role: user.isAdmin ? "owner" : null,
-    scopes: user.scopes, credential: "oauth", credentialId: user.tokenId, clientId: null,
-  } };
-};
+const caller = (request: Request, _env: Env, authority = { readOnly: false }) =>
+  resolveCaller(request, loader, { ...authority, responseHeaders });
 ```
 
-- `subject` is stable and unique across every issuer you accept; namespace it
-  when there are several. Never use an email.
-- Map your roles onto `owner`, `editor` and `contributor`, or leave `role`
-  `null` and authorize with scopes and guards.
-- Admin gets no `identity` with `custom`, so it hides user management.
-  Implement `AdminIdentity` (`directory`, `roles`, `deleteUser`, each optional)
-  from `@aotter/mantle/admin` to show it.
-
-[Mantle on ChatGPT Sites](./chatgpt-sites.md) is a worked `custom` identity.
-
-## Further reading
-
-- [Authorization](../concepts/authorization.md)
-- [MCP and agents](../concepts/mcp-and-agents.md): OAuth for MCP clients
+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 table names (`user.modelName`,
+  `session.modelName`, ... and plugin `schema` options). 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.
+- 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,118 +1,9 @@
----
-description: Run a Mantle 0.2.0 service on ChatGPT Sites — the Cloudflare preset with a custom identity over Sites sign-in, D1 schema delivery, R2 media, MCP paths, and what to verify after each publish.
----
 # Mantle on ChatGPT Sites
 
-A ChatGPT Site runs a Cloudflare Worker with D1 and R2 bindings, and Sites owns
-sign-in and deployment. Mantle runs there as the ordinary Cloudflare preset
-with `identity: custom`: Sites authenticates the person, and your
-`src/identity.ts` turns that into a Mantle `Caller`. There is no Sites option in
-`mantle generate` and no Sites code in Core.
+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.
 
-This page is a guide, not a runnable example. Inspect the Site's actual
-hosting configuration and bindings before relying on any detail here, and
-verify every claim on the deployed Site.
+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.
 
-## Generate
+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. Cloud executes migrations at deploy time. Destructive/type changes require explicit data migration; Mantle drops nothing.
 
-```sh
-pnpm exec mantle generate --identity custom --features mcp,admin,web
-```
-
-Keep the application outside the Mantle SDK checkout, pin every
-`@aotter/mantle*` package to one exact version, and publish through Sites; do
-not `wrangler deploy` a Site's Worker yourself.
-
-## Identity: Sites sign-in as a `CallerResolver`
-
-Sites' ingress authenticates the visitor and forwards the identity in
-`oai-authenticated-user-*` headers. Trust them **only** when every request
-reaches the Worker through that ingress, which strips caller-supplied copies;
-never expose the Worker on another route.
-
-Staff roles are the application's: keep them in your own table (here
-`sites_users (id, email, role)`, created by your own migration) and read them
-on every request. A Site viewer is not automatically a Mantle editor.
-
-```ts
-// src/identity.ts
-import type { CallerResolver } from "@aotter/mantle";
-
-export function sitesResolver(db: D1Database, ownerEmail: string | undefined): CallerResolver {
-  return async (request) => {
-    const sub = request.headers.get("oai-authenticated-user-id");
-    const email = request.headers.get("oai-authenticated-user-email")?.trim().toLowerCase();
-    if (!sub) return { caller: { kind: "anonymous" } };
-    if (!email || sub.length > 512) return { invalid: true };
-    const subject = `chatgpt:${sub}`; // namespaced: unique across issuers, never the email
-    await db.prepare("INSERT INTO sites_users (id, email, role) VALUES (?1, ?2, ?3) ON CONFLICT (id) DO NOTHING")
-      .bind(subject, email, email === ownerEmail?.trim().toLowerCase() ? "owner" : null).run();
-    const row = await db.prepare("SELECT role FROM sites_users WHERE id = ?1").bind(subject).first<{ role: "owner" | "editor" | "contributor" | null }>();
-    return { caller: { kind: "user", subject, role: row?.role ?? null, scopes: [], credential: "session", credentialId: null, clientId: null } };
-  };
-}
-```
-
-In `src/service.ts`, use `sitesResolver(env.DB, env.OWNER_EMAIL)` where the
-preset uses `resolveCaller`. The email is used only to recognize the first
-owner. To manage staff from Admin, implement `AdminIdentity`'s `directory` and
-`roles` facets (from `@aotter/mantle/admin`) over `sites_users` and pass it as
-`identity`; without it Admin hides user management.
-
-A Sites session is a browser session. It is not an OAuth bearer token, so it
-does not authenticate a remote MCP client.
-
-## Storage on D1
-
-Boot converges Schema tables to the plan. If the Site applies schema changes
-through migration files instead of letting the Worker run DDL, deliver
-Mantle's SQL that way:
-
-1. Point `mantle generate --check --database <file>` at a local SQLite file
-   in the same state as the Site's database (for example local D1 under
-   `.wrangler/state/v3/d1/`, migrated the same way).
-2. Put the printed SQL into a new migration in the Site's migration directory,
-   together with your own tables (`sites_users`).
-3. Publish; boot then finds the database converged and applies nothing.
-
-Repeat for each plan change. A blocked change is resolved by hand, as in
-[Deploy and operate](./deploy-and-operate.md#resolving-a-blocked-change).
-
-## Media
-
-`r2MediaStorage` presigns uploads with R2's S3 API, which needs an S3
-endpoint and an API key pair. With only an R2 binding, implement the
-`MediaStorage` port yourself (`createUpload`, `commitUpload`, `deleteObject`)
-and add two routes to your service:
-
-- an authenticated, same-origin `PUT` route that checks the pending upload,
-  the declared type and the exact size before `bucket.put`;
-- a public `GET` route that serves only committed variants, with a safe type
-  and `nosniff`.
-
-Pass it as `media` to `createAdminSurface` and declare media purposes in the
-site defaults ([Media uploads with R2](./media-r2.md)).
-
-## MCP paths
-
-Try `/mcp` first. If the Site does not route it to the Worker, mount the
-public surface at another path you own (`createMcpSurface(runtime, { basePath:
-"/agent/mcp", surface: "public" })`) and report the real paths through
-`createAdminSurface`'s `site: { mcpEndpoints }`. Admin and its browser tools
-work with the Sites session. A remote staff MCP client (`/mcp/staff`)
-needs a real OAuth authorization server and bearer verification in your
-resolver; a forwarded identity header is not one.
-
-## Verify after every publish
-
-- Anonymous: a public View, an HTTP Trigger, `/mcp` (or your path)
-  `initialize` and `tools/list` when a public tool may be called anonymously;
-  when every public tool `requires` a caller, they answer 401 with a
-  `WWW-Authenticate` challenge instead.
-- The owner: `GET /admin/api/me` is `owner`; a staff View and an operation.
-- A second account: no Admin access until granted; revoking the role takes
-  effect on the next request.
-- Every binding the service uses, on the deployed Site, not only locally.
-
-Sites lists financial transactions among its unsupported uses; a working
-sandbox flow is not support for live payments.
+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 separate assets and shell security contract. Scheduling and storage provisioning belong to the host.