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

package/docs/examples/recipes/src/routes.ts

@@ -0,0 +1,71 @@
+import type { Caller } from "@aotter/mantle/contracts";
+import { store } from "../generated/generated.js";
+import { translationLocales } from "../generated/translations.js";
+import recipePage from "../generated/paged/views/published_recipes.js";
+import translationPage from "../generated/paged/views/published_translations.js";
+import { DEFAULT_LOCALE, LOCALES, type Locale, type Recipe, listHtml, llmsTxt, recipeHtml, recipeMarkdown, robotsTxt, sitemapXml } from "./pages.js";
+
+// Visitor pages always read as anonymous, even for a signed-in admin, so drafts never reach public HTML.
+const visitor: Caller = { kind: "anonymous" };
+const page = /^\/(zh-TW|en)\/(?:recipes\/([a-z0-9-]+?)(\.md)?)?$/;
+
+/**
+ * Visitor pages, tried before Admin, MCP and REST. Only these paths are matched; everything else falls through.
+ *   /                          -> redirect to /zh-TW/
+ *   /{locale}/                 list (HTML)
+ *   /{locale}/recipes/{slug}   detail (HTML: SEO meta, hreflang, JSON-LD Recipe, short answer)
+ *   /{locale}/recipes/{slug}.md  Markdown alternate
+ *   /llms.txt                  published recipes for AI agents
+ *   /sitemap.xml, /robots.txt  every published URL in every locale; robots keeps crawlers out of /admin/
+ */
+export async function appRoutes(request: Request, env: Env, _context: { caller: () => Promise<Caller>; waitUntil: (task: Promise<unknown>) => void }): Promise<Response | undefined> {
+  const url = new URL(request.url), match = page.exec(url.pathname);
+  if (!["/", "/llms.txt", "/sitemap.xml", "/robots.txt"].includes(url.pathname) && !match) return undefined;
+  if (request.method !== "GET" && request.method !== "HEAD") return new Response(null, { status: 405, headers: { allow: "GET, HEAD" } });
+  // Absolute links use the configured origin, not the request Host.
+  const origin = env.PUBLIC_ORIGIN;
+  if (url.pathname === "/") return Response.redirect(`${origin}/${DEFAULT_LOCALE}/`, 302);
+
+  if (url.pathname === "/robots.txt") return send(request, robotsTxt(origin), "text/plain; charset=utf-8");
+  if (url.pathname === "/llms.txt" || url.pathname === "/sitemap.xml") {
+    const lists = await Promise.all(LOCALES.map(async locale => [locale, await list(env, locale)] as const));
+    return url.pathname === "/llms.txt"
+      ? send(request, llmsTxt(origin, lists), "text/plain; charset=utf-8")
+      : send(request, sitemapXml(origin, lists), "application/xml; charset=utf-8");
+  }
+
+  const locale = match![1] as Locale, slug = match![2], markdown = !!match![3];
+  if (!slug) return send(request, listHtml(origin, locale, await list(env, locale)), "text/html; charset=utf-8");
+  const found = await read(env, slug, locale);
+  if (!found) return new Response("Not found", { status: 404, headers: { "cache-control": "no-store" } });
+  return markdown
+    ? send(request, recipeMarkdown(found.recipe), "text/markdown; charset=utf-8", { link: `<${origin}/${locale}/recipes/${slug}>; rel="canonical"` })
+    : send(request, recipeHtml(origin, locale, found.recipe, found.locales), "text/html; charset=utf-8");
+}
+
+/** First page of published recipes in one locale. AGENT: page with `nextCursor` once a locale has more than 100 recipes. */
+async function list(env: Env, locale: Locale) {
+  const result = locale === DEFAULT_LOCALE
+    ? await recipePage(env.DB, visitor, {}, { limit: 100 })
+    : await translationPage(env.DB, visitor, { locale }, { limit: 100 });
+  return result.rows.map(row => ({ slug: String(row.slug), title: String(row.title), summary: String(row.summary) }));
+}
+
+/** One published recipe in `locale` plus the locales it is published in (for hreflang). */
+async function read(env: Env, slug: string, locale: Locale): Promise<{ recipe: Recipe; locales: Locale[] } | undefined> {
+  const recipes = store(env.DB, visitor);
+  const parent = await recipes.collection("recipes").first({ where: { slug } });
+  if (!parent) return undefined;
+  const translated = (await translationLocales(env.DB, visitor, "recipes", [parent]))[parent.id] ?? [];
+  const locales = LOCALES.filter(l => l === DEFAULT_LOCALE || translated.includes(l));
+  if (!locales.includes(locale)) return undefined;
+  // A translation read merges the parent's fields (total_minutes, servings, cover_url, ...); the child's own fields win.
+  const row = locale === DEFAULT_LOCALE ? parent : await recipes.collection("recipe_translations").first({ where: { slug, locale } });
+  if (!row) return undefined;
+  return { recipe: { ...row, slug, locale } as Recipe, locales };
+}
+
+function send(request: Request, body: string, type: string, headers: Record<string, string> = {}) {
+  // AGENT: choose a cache policy (and purge on publish) once pages sit behind a CDN.
+  return new Response(request.method === "HEAD" ? null : body, { headers: { "content-type": type, "cache-control": "no-store", ...headers } });
+}

package/docs/examples/recipes/src/site-config.ts

@@ -0,0 +1,12 @@
+import type { SiteDefaults } from "@aotter/mantle/site";
+
+/**
+ * Site defaults for `mantle generate ... --site src/site-config.ts`, which adds the media library tables and
+ * `generated/site.ts`. The shell does not pass `--site`; see README "Cover images" for the two lines to add.
+ */
+export const siteDefaults = {
+  title: "Recipes",
+  description: "Home recipes in Traditional Chinese and English.",
+  locales: ["zh-TW", "en"],
+  media: { purposes: [{ name: "cover", required: ["image/jpeg,image/png,image/webp"], maxBytes: { "image/jpeg": 5_000_000, "image/png": 5_000_000, "image/webp": 5_000_000 } }] },
+} satisfies SiteDefaults;

package/docs/examples/recipes/wrangler.jsonc

@@ -0,0 +1,73 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "mantle-app",
+  "main": "dist/index.js",
+  "compatibility_date": "2026-09-01",
+  "compatibility_flags": [
+    "nodejs_compat"
+  ],
+  "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": "node_modules/@aotter/mantle-admin/dist/admin",
+    "binding": "ASSETS",
+    "run_worker_first": true,
+    "html_handling": "none"
+  },
+  "triggers": {
+    "crons": []
+  },
+  "no_bundle": true,
+  "find_additional_modules": true,
+  "base_dir": "dist",
+  "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,176 @@
----
-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
 
-Mantle never owns your users. Choose once, in `mantle.config.json`:
+Your application configures `betterAuth()` and its official plugins in `auth.ts`.
+Mantle supplies the database adapter, schema generation and caller resolution:
 
-| `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 |
+| 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. |
 
-A rerun of `mantle generate` cannot switch identity. Admin needs `mantle` or
-`custom`.
+## `auth.ts`
 
-## Identity `mantle`
+Copy `src/auth.ts` from the [app shell](../../examples/app-shell/README.md), which CI runs from the packed packages.
+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.
 
-The generated `src/service.ts` builds the auth from `env`:
+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.
 
-```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` },
-});
-```
+`@aotter/mantle/auth/hardening` supplies optional helpers:
 
-`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';
-```
+- `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.
 
-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`):
+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).
 
-```sql
-BEGIN;
-ALTER TABLE "account" ALTER COLUMN "issuer" DROP NOT NULL;
-COMMIT;
-```
+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.
 
-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"}'
-```
+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.
 
-`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.
+## Identity helpers
 
-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.
+`@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.
 
-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.
+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.
 
-### MCP clients for members
+`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.
 
-`/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:
+## Worker entry
 
-```ts
-import { signedOAuthQuery } from "@aotter/mantle-ui/kit";
+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.
 
-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");
-```
+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.
 
-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:
+## Build: keep Better Auth out of startup
 
-```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,
-});
-```
+Use the [Workers build instructions](../../../README.md#workers-build).
+The metafile startup guard rejects static Better Auth imports; keep auth behind
+`authLoader(() => import(...))`.
 
-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.
+## Schema
 
-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).
+`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).
 
-### Production
+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.
 
-Replace the local choices in `src/service.ts`:
+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.
 
-- **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:
+### Explicit read-only cookie snapshots
+
+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.
+
+`ctx.admin` role names are open and must match `^[a-z][a-zA-Z0-9_]{0,62}$`. Bare `ctx.admin` admits any admin; a list admits admins holding one of its roles. Better Auth’s `adminRoles` decides who is an admin. Member role names alone grant no privilege.
+
+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`.