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

package/docs/adr/0014-auth-better-auth-and-multi-tenant-mcp.md

@@ -1,939 +0,0 @@
-# ADR-0014: Adapter-owned identity and MCP authorization
-
-## Status
-
-Accepted. Amended 2026-05-14, 2026-05-15, 2026-06-30, 2026-07-15,
-2026-08-03, 2026-08-22, 2026-09-18, 2026-09-21, and 2026-09-22.
-
-## Date
-
-2026-05-09 (last amended 2026-09-22)
-
-> **Current authority:** the original decision below records the rejected
-> Better-Auth-for-MCP design. The 2026-08-22 Better Auth 1.7 amendment is
-> authoritative where it conflicts with the 2026-05-15 carve-out; the
-> 2026-07-15 normalized authorization boundary still applies. Operational
-> guidance is maintained against the current adapter/runtime.
-
-## Context
-
-The pre-v0.1.0 auth surface is a hand-rolled GitHub-only flow stitched out of two libraries:
-
-- `@cloudflare/workers-oauth-provider` (DCR-compliant authorization server for MCP — `/oauth/{authorize,token,register}`, `.well-known/oauth-authorization-server`, KV-backed token storage)
-- A hand-rolled GitHub upstream OAuth client (`oauth/githubOAuth.ts` ~110 LOC)
-- D1 tables: `users`, `social_logins`, `sessions`, `github_tokens`, `staff` overlay
-- `ensureBootstrapOwner` env-var gated (`ADMIN_GITHUB_LOGIN`)
-- `cms_session` cookie carries the staff session
-- Single `/mcp` route gated to staff bearers only
-
-Pre-launch we promised the `publication` family then `community` and `fan-club` (#58 taxonomy). Both require:
-
-1. **Multi-IDP end-user login** — GitHub, Google, Apple, plus magic link / email OTP for users without OAuth accounts
-2. **End-user MCP access via DCR** — let signed-in end-users grant a Claude / Cursor / Codex agent read access to their own subscriptions, comments, member-only posts
-
-Trying to grow the existing hand-rolled stack into that shape — three IDPs, two paths to magic link, account linking with reauth, scope-based MCP gating, role machinery for both staff and end-user, end-user DCR through `workers-oauth-provider` — accumulates fast (~1500 LOC of auth code by v0.2). Cloudflare itself does not ship a transactional-email-for-app-auth product (Cloudflare Access's "One-time PIN" gates Zero Trust resources, not public-site users), so the email-OTP path needs an external sender regardless.
-
-The "single `/mcp` with config flags" pattern explodes combinatorially when scope, role, surface, and feature flags interact. Each new feature multiplies the matrix.
-
-A 2026 Workers-friendly auth library — [Better Auth](https://better-auth.com) — covers this entire space:
-
-- Identity / sessions / accounts (the obvious thing every auth library does)
-- Multi-IDP via `socialProviders` (GitHub / Google / Apple / 30+ more)
-- Magic link (`magicLink` plugin) and email OTP (`emailOTP` plugin) with pluggable email sender
-- Role machinery (`admin` plugin, `user.role` field on user table)
-- **OAuth 2.1 provider with DCR (`oauthProvider` plugin)** — full RFC 7591 dynamic client registration, RFC 7662 introspection, RFC 7009 revocation, scope-based access control, custom token claims, consent UI redirect customization
-- **MCP plugin (`mcp`)** — purpose-built on top of the OAuth 2.1 provider for MCP DCR; auto-mounts `.well-known/oauth-authorization-server` + `.well-known/oauth-protected-resource`, exposes `auth.api.getMcpSession()` for protected-resource validation
-- Account linking with policies (verified-email match + reauth requirement)
-
-Better Auth depends on a Kysely / Drizzle / Prisma adapter for the database, not on any Cloudflare-specific service. The auth machinery remains platform-agnostic.
-
-## Decision (historical baseline; amended below)
-
-### 1. Better Auth replaces both layers
-
-Adopt Better Auth as the SDK's full auth surface. It owns:
-
-- `user` / `session` / `account` / `verification` D1 tables (replaces our `users` / `social_logins` / `sessions` / `github_tokens`)
-- Cookie session (replaces `cms_session` with `better-auth.session_token`)
-- Upstream OAuth clients for GitHub, Google, Apple via `socialProviders` (replaces `oauth/githubOAuth.ts`)
-- Magic link plugin (replaces the `email_verifications` table we would otherwise hand-roll)
-- Email OTP plugin
-- `admin` plugin for role machinery (replaces the `staff` table — `user.role` carries the role string)
-- **`oauthProvider` (or `mcp`) plugin for DCR-compliant authorization server** (replaces `@cloudflare/workers-oauth-provider`)
-
-`@cloudflare/workers-oauth-provider` is removed entirely. The `OAUTH_KV` binding is no longer required. The whole `packages/adapters/cloudflare/src/oauth/` directory disappears (singleton wiring, hand-rolled GitHub OAuth, consent HTML renderer with locale list — Better Auth's consent flow replaces).
-
-The auth runtime stops being an adapter port. `OAuthVerifier` port + `WorkersOAuthVerifier` adapter are deleted. Validating bearer tokens at `/mcp` and `/staff/mcp` becomes `auth.api.getMcpSession(req.raw)` — a direct Better Auth API call, no port indirection.
-
-This makes the runtime more platform-agnostic, not less: Better Auth runs on Workers (D1 via Kysely), Bun (sqlite), and Node (postgres) without runtime changes.
-
-### 2. `staff` table → `user.role` via Better Auth admin plugin
-
-The `admin` plugin stores a `role` field on the `user` table. Configure:
-
-```ts
-admin({
-  defaultRole: "user",                                 // every end-user
-  adminRoles: ["owner", "editor", "contributor"],      // our existing staff vocabulary
-})
-```
-
-`ensureBootstrapOwner` becomes a `databaseHooks.user.create.after` that promotes the first user matching `ADMIN_GITHUB_LOGIN` to `owner` if no other admin role exists yet. The `staff` D1 table, `D1StaffRepository`, `StaffRepository` port, and `runtime.staff` are deleted.
-
-The manifest grammar predicate `requires.auth.all: [{ "ctx.staff": ["editor"] }]` evaluates against `session.user.role` at runtime. Closed enum membership unchanged.
-
-### 3. Two explicit MCP surfaces
-
-`/mcp` and `/staff/mcp` are mounted side-by-side from boot. `/staff/mcp`
-exposes staff authoring/lifecycle tools and `/mcp` exposes declared public
-Views and Procedures. An MCP Trigger explicitly chooses `surface: public |
-staff`; the target's `requires.auth` still gates every call.
-
-Tool partition rules:
-
-- Per-collection auto-emitted authoring tools (`create_draft_<schema>`, `update_draft_<schema>`) — predicate baked-in to require `ctx.staff: [contributor+]`; route to `/staff/mcp`
-- `list_entries` / `get_entry` / `request_publish` / `archive_entry` / `unpublish_entry` — staff-only (return drafts, mutate state); `/staff/mcp` only
-- `query_view_<name>` follows `View.spec.surface`.
-
-### 4. Scope-aware DCR via Better Auth `oauthProvider`
-
-Better Auth's `oauthProvider` plugin handles DCR. Configure:
-
-```ts
-oauthProvider({
-  scopes: ["mcp:staff", "mcp:read"],
-  clientRegistrationDefaultScopes: ["mcp:read"],
-  clientRegistrationAllowedScopes: ["mcp:staff", "mcp:read"],
-  validAudiences: [
-    "https://<worker>/staff/mcp",
-    "https://<worker>/mcp",
-  ],
-  consentPage: "/auth/consent",
-  customAccessTokenClaims: ({ user, scopes }) => ({
-    role: user.role,
-  }),
-})
-```
-
-Consent UI semantics:
-
-- `mcp:staff` requested — only admin-role users can approve. Non-admin sessions see "you need to be staff to grant this scope."
-- `mcp:read` requested — any signed-in user can approve.
-- Mixed `["mcp:staff", "mcp:read"]` — admin-role users grant both; non-admin users grant only `mcp:read` with a notice.
-
-The consent page (`/auth/consent`) is consumer-rendered; SDK ships a minimal HTML fallback for starters that don't customize.
-
-Each MCP route validates token scope at request time via `auth.api.getMcpSession()`:
-
-- `/staff/mcp` requires `mcp:staff` ∈ session.scopes
-- `/mcp` requires `mcp:read` ∈ session.scopes (`mcp:staff` accepted as superset)
-
-The Better Auth MCP plugin exposes the RFC 9728 protected-resource metadata document at the auth mount (`/api/auth/.well-known/oauth-protected-resource` in the Cloudflare starter). Both `/staff/mcp` and `/mcp` point unauthenticated clients at that metadata document through `WWW-Authenticate`.
-
-### 5. Role checked dynamically, not embedded in token
-
-The token can carry `role` via `customAccessTokenClaims` for caller convenience, but the **MCP route validators always re-read `user.role` fresh** via the session. Cost: ~1ms D1 lookup per request (Better Auth's session cache absorbs most of this). Win: a demoted user is locked out immediately, not at token expiry. Same pattern for the consent UI staff gate.
-
-### 6. Single auth surface, no port indirection
-
-Auth is no longer an adapter port. `mantle-runtime` does NOT define an auth port and `createCmsRuntime()` does not accept auth. Adapter packages construct the Better Auth instance with the right database adapter for their platform and keep it in the adapter-owned HTTP/MCP mount layer.
-
-The adapter uses Better Auth to validate sessions, MCP bearer tokens, scopes, and roles, then passes authenticated user/staff context into runtime dispatchers. Better Auth remains platform-agnostic, but it is not a runtime dependency.
-
-This is a minor amendment to ADR-0011 (adapter port spec): the auth ports disappear and auth becomes adapter-owned mount wiring. The hard invariant ("`mantle-runtime` MUST NOT import `D1Database` / `KVNamespace`") is preserved.
-
-### 7. Auth as contract, Better Auth as default
-
-**Amended 2026-05-14.** The seven auth-cascade PRs (#160 / #161 / #162 / #165 / #167 / #169 / #173) shipped Better Auth-backed config + admin SPA + tests. During that work two architectural lines need to be explicit so future PRs don't drift toward mechanical pass-through:
-
-**The SDK's public auth contract is the `Auth` interface, not Better Auth.**
-
-`packages/adapters/cloudflare/src/auth/createAuth.ts` exports:
-
-```ts
-export interface Auth {
-  readonly handler: (request: Request) => Promise<Response>;
-  readonly getSession: (request: Request) => Promise<{...} | null>;
-  readonly getMcpSession: (request: Request) => Promise<{...} | null>;
-  readonly getUserRole: (userId: string) => Promise<string | null>;
-  readonly methods: ReadonlyArray<AuthMethodInfo>;
-}
-```
-
-The internal consumers of `Auth` (post-#193: `mountServerEndpoints`, `createMcpApiHandler`, `mountAuthorize`, `bootRuntimeOnce`, `cmsConfig`) all import only the `Auth` type — never `betterAuth`, never any plugin internals. Better Auth is imported in exactly one file (`createAuth.ts`).
-
-**`createAuth(config)` is the SDK-shipped, Better Auth-backed *default* implementation.** Adopters who want the curated `methods[]` shape, `bootstrapOwner` promotion, Workers-aware rate-limit, fire-and-forget `backgroundTasks.handler`, `extras` reserved-key validation, and the `Auth.methods` admin-SPA contract — pass a config to `createAuth()` and get an `Auth`.
-
-**Adopters who want a different backend implement `Auth` directly and bypass `createAuth`.** Lucia, Auth.js, a custom hand-roll — all valid. The seam already works today; the `/api/auth/*` URL convention (which Better Auth picks for its mounted endpoints) is a second-tier contract that affects the admin SPA. `auth-views.tsx` hard-codes six paths today (`/api/auth/methods`, `/api/auth/sign-in/social`, `/api/auth/email-otp/send-verification-otp`, `/api/auth/sign-in/email-otp`, `/api/auth/sign-in/magic-link`, `/api/auth/sign-out`); replacing the backend means matching the URL convention OR forking `auth-views.tsx`.
-
-**Anti-pattern to refuse in review: Better Auth-field pass-through.**
-
-> **Narrowed by the 2026-09-22 amendment** for `OAuthProviderConfig.extensions`, Better Auth's declared OAuth-provider composition point. See § "2026-09-22 amendment" below.
-
-If a future PR's only effect is to rename a Better Auth field into our `CreateAuthConfig` and forward it verbatim, refuse it. **Picking a different literal default for an existing Better Auth field does NOT, by itself, justify a new field on `CreateAuthConfig` — that's the same pass-through dressed up.** The SDK adds load-bearing surface area only when the new field exists for at least one of these concrete reasons:
-
-- **Workers-aware behavior** that Better Auth doesn't supply (e.g. `rateLimit` flipped on by default when an email-shaped method registers — Better Auth's per-route limits gate on `process.env.NODE_ENV === "production"` which is unset on Workers; `advanced.backgroundTasks.handler` wired to fire-and-forget — closes the timing-oracle on OTP send).
-- **Cross-adapter port** the runtime needs (e.g. `EmailSender` in `mantle-runtime/domain/port/` — used by both `createAuth`'s OTP / magic-link callbacks AND future use cases like order receipts).
-- **Safety net** Better Auth doesn't provide (e.g. `extras` reserved-key validation refuses to let an adopter shadow `clientSecret` via spread order; bootstrap-method cross-check refuses `match: "github-login"` with no `github` social registered).
-- **New abstraction** that fuses multiple Better Auth surfaces (e.g. `methods[]` unifies `socialProviders` + `emailOTP` + `magicLink` plugins under one config shape with shared per-method discrimination).
-- **DX helper that removes a Workers-hostile dep** (e.g. `appleClientSecret` signs the ES256 JWT via `crypto.subtle` so adopters don't have to install `jose` for the one task Better Auth's docs assume a JWT lib).
-
-A different default value on its own is not on this list. Default tweaks live in adopter code.
-
-> **Retracted by Amendment 2026-05-15.** This section originally pointed at a `CreateAuthConfig.betterAuthOptions?: Partial<BetterAuthOptions>` escape hatch (introduced in PR #175). The 2026-05-15 OAuth carve-out (PR #193) removed it. With the MCP OAuth surface now served by `@cloudflare/workers-oauth-provider`, the un-curated knob set Better Auth still owns (staff sign-in, social, OTP, magic-link, role) is small enough that the curated `methods[]` / `rateLimit` / `bootstrapOwner` fields cover the adopter contract. When a missing Better Auth knob is real and load-bearing, the answer is a curated first-class field — not a passthrough. See § "Amendment 2026-05-15" below.
-
-This makes the implicit explicit. The SDK's auth surface is committee-curated; un-curated knobs require either a justified first-class field or an architectural change to remove the dependency on that knob.
-
-### 8. Path to `@aotter/mantle-better-auth` separate package (deferred)
-
-Each adapter owns its Better Auth wiring. Today the seam is:
-
-- `Auth` interface lives in the adapter (could move to runtime or a separate package without breaking the contract — adapters consume the type, not the implementation).
-- `createAuth.ts` is the only file with `import { betterAuth }` (~290 LOC, no Cloudflare-binding-specific code outside `config.database: D1Database`).
-- `ConsoleEmailSender.ts` is dev-only and platform-agnostic (~25 LOC).
-- `appleClientSecret.ts` uses Web Crypto (`crypto.subtle`) which Workers + Node 18+ + Bun + Deno all share (~150 LOC).
-
-The future split looks like:
-
-```
-@aotter/mantle-runtime           ← ports + use cases (today)
-@aotter/mantle-better-auth       ← createAuth + EmailSender impls + appleClientSecret (new, when needed)
-@aotter/mantle-cloudflare        ← Workers adapter; depends on (or accepts) Auth-shape (today)
-future adapter                   ← same contract, implemented when needed
-```
-
-The pivot point — when to extract — is when a second adapter needs the same wiring. Until then, in-place co-location is cheaper than a new package boundary.
-
-## Consequences
-
-### What gets deleted
-
-- `packages/adapters/cloudflare/src/oauth/` entire directory (`githubOAuth.ts`, `consentHtml.ts`, `oauthSingleton.ts`, `oauthConstants.ts`, `index.ts`)
-- `packages/adapters/cloudflare/src/bindings/D1UserRepository.ts`
-- `packages/adapters/cloudflare/src/bindings/D1SessionRepository.ts`
-- `packages/adapters/cloudflare/src/bindings/D1StaffRepository.ts`
-- `packages/adapters/cloudflare/src/bindings/WorkersOAuthVerifier.ts`
-- `packages/adapters/cloudflare/src/bindings/StubOAuthVerifier.ts`
-- `mantle-runtime/src/domain/port/UserRepository.ts`
-- `mantle-runtime/src/domain/port/SessionRepository.ts`
-- `mantle-runtime/src/domain/port/StaffRepository.ts`
-- `mantle-runtime/src/domain/port/OAuthVerifier.ts`
-- `mantle-runtime/src/runtime.ts` `users` / `sessions` / `staff` / `oauth` ports
-- `mountServerEndpoints.ts` `/admin/auth/github` + callback (Better Auth handles), session cookie read/write code, `ensureBootstrapOwner` inline logic (moves to hook), OAuth consent UI handlers (`/oauth/authorize` GET/POST), OAuth provider passthrough (`/oauth/token`, `/oauth/register`, `.well-known/*`)
-- D1 tables: `users`, `social_logins`, `sessions`, `github_tokens`, `staff`
-- `OAUTH_KV` binding (no longer required in `wrangler.toml`)
-- `@cloudflare/workers-oauth-provider` dependency
-
-### What stays
-
-- `mount/mountMcp.ts` — refactored to mount both `/mcp` + `/staff/mcp`, validates via `auth.api.getMcpSession()`, and enforces route scopes.
-- `infrastructure/mcp/McpJsonRpcDispatcher.ts` — refactored to support staff vs public tool catalogs.
-- All entries / publish / view machinery (zero auth-related changes)
-- Admin SPA — sign-in view rewritten to redirect to Better Auth route; identity / role queries use Better Auth client
-
-### What gets added
-
-- Better Auth library + Kysely + `kysely-d1` packages (or whichever D1 adapter Better Auth recommends current)
-- Better Auth instance at `packages/adapters/cloudflare/src/auth/createAuth.ts` (factory taking env / D1 binding)
-- New `EmailSender` port + `ResendEmailSender` adapter impl (used by Better Auth `magicLink` / `emailOTP` plugins)
-- `databaseHooks.user.create.after` for `ensureBootstrapOwner` semantics
-- Two `/.well-known/oauth-protected-resource/*` metadata endpoints (Better Auth helpers)
-- Public View MCP tools: dispatcher emits `query_view_<name>` on `/mcp`.
-- Skills + docs updates for the dual MCP URL handoff
-
-### Backward compatibility
-
-None. Pre-v0.1.0 has no external consumers. Existing demo deployments tear down + re-bootstrap from the migrated `0.0.x-alpha` release.
-
-### Skills + launch handoff
-
-The Mantle landing launch session and generated repo-local
-`mantle:provision` skill document the dual MCP handoff. Provision's final
-report distinguishes:
-
-```
-Public site:    https://<worker>.workers.dev/
-Staff MCP URL:  https://<worker>.workers.dev/mcp/staff     (give to your owner agent)
-User MCP URL:   https://<worker>.workers.dev/mcp           (give to visitors / their agents)
-```
-
-The publication starter repo's production smoke recipe uses `/mcp/staff`
-for the MCP operator smoke step.
-
-### Platform agnosticism
-
-By removing `@cloudflare/workers-oauth-provider` and routing auth through Better Auth, the SDK no longer depends on any CF-specific auth service. A future adapter can construct Better Auth against its database while the runtime + dispatcher + skills + prompts stay unchanged. ADR-0011 (adapter port spec) is amended: the `OAuthVerifier` port disappears; auth becomes adapter-owned, with platform-agnostic Better Auth as the type.
-
-## Alternatives considered
-
-### Alt-A: Hand-rolled multi-IDP without a library
-
-Continue the existing `oauth/githubOAuth.ts` pattern, write `googleOAuth.ts` and `appleOAuth.ts`, wire account-linking by hand, keep `workers-oauth-provider` for DCR.
-
-**Rejected** — Apple Sign In's JWT-signed client secret rotation (every 6 months) is non-trivial; account-linking with reauth flow has security pitfalls; magic-link / email-OTP adds 200+ LOC of token storage + send + verify per flow. Total scope is ~1500 LOC of auth code for v0.2. Better Auth covers this with config + plugins.
-
-### Alt-B: arctic library for upstream IDPs, keep `workers-oauth-provider` for DCR
-
-Use [arctic](https://arcticjs.dev) for upstream IDP clients, keep our existing `users` / `social_logins` / `sessions` / `staff` schema, hand-roll session management + account linking + magic link, retain `workers-oauth-provider`.
-
-**Rejected** — arctic only solves the OAuth client step (~150 LOC saved). Session management, role machinery, account linking with reauth, magic-link plugin — all still hand-rolled. `workers-oauth-provider` retained means we still glue two systems. Compared to Better Auth (which absorbs all of these into one), arctic forces more glue code AND keeps the platform coupling.
-
-### Alt-C: Better Auth for upstream IDPs, keep `workers-oauth-provider` for DCR
-
-Adopt Better Auth as identity / session / role authority. Keep `workers-oauth-provider` because it's a known-good DCR implementation.
-
-**Rejected as of 2026-05-09** — initial draft of this ADR took this position. Web research showed Better Auth's `oauthProvider` and `mcp` plugins cover the DCR concern with full RFC 7591 / 7662 / 7009 / 9728 compliance. Keeping `workers-oauth-provider` would mean two systems sharing user identity but with different cookie / token / session caches — operationally messier than a single auth surface. The platform-agnosticism win (no CF-specific auth lib) tips the balance.
-
-### Alt-D: Single `/mcp` with role + scope flags
-
-Keep one MCP route. Gate with config flags: `mcpRequiresStaff`, `mcpAllowEndUser`, scope checks per tool.
-
-**Rejected** — flag combinatorics explode as we add subscription tiers + per-collection visibility. Two routes derived from manifest predicate eliminates the flag matrix entirely; the rule is reviewable as a single sentence.
-
-### Alt-E: Two separate Better Auth `oauthProvider` instances
-
-One DCR provider for staff MCP, one for end-user MCP.
-
-**Rejected** — two consent UIs, two token tables, double the configuration burden, no real benefit. Single auth server with scope-based gating achieves the same separation cleanly per the OAuth spec.
-
-### Alt-F: `staff` table preserved alongside Better Auth user table
-
-Keep our `staff` overlay and `D1StaffRepository`. Use Better Auth only for identity / session / account, route role machinery through staff overlay.
-
-**Rejected** — duplicate role data (Better Auth `admin` plugin + our staff overlay) is worse than picking one. Audit trail is the only thing the standalone overlay buys, and v0.1.0 doesn't need it.
-
-## Implementation status (historical snapshot)
-
-Phase 0 (spike, 0.5–1d) — pending:
-
-- Confirm Better Auth + `admin` plugin + `oauthProvider` (or `mcp`) plugin operational on D1 in Workers
-- Confirm Better Auth's auto-mounted `.well-known/oauth-authorization-server` is reachable
-- Confirm two `.well-known/oauth-protected-resource/*` metadata documents serve correctly (helper or hand-roll)
-- Confirm DCR clients (Claude Code, Cursor) follow RFC 9728 path-prefix metadata
-- Confirm `auth.api.getMcpSession()` validates bearer tokens at the protected-resource path
-- Confirm `auth.api.getSession()` works inside consumer routes
-- Bundle size delta on the worker
-
-Phase 1 (migration, ~2d) — pending Phase 0:
-
-- Better Auth integration (publication starter + mantle-cloudflare adapter)
-- Schema cut-over (canonical migrations rewrite, drop legacy auth tables, add Better Auth tables)
-- Drop `oauth/` directory, all auth ports, `WorkersOAuthVerifier`, `StubOAuthVerifier`
-- Drop `@cloudflare/workers-oauth-provider` dep + `OAUTH_KV` binding
-- Mount factories rewrite (`mountServerEndpoints` for admin gate, `mountMcp` for dual-route)
-- Dispatcher refactor (per-tool surface routing from manifest predicate)
-- Tests update (`mcp-smoke` → `staff-mcp-smoke` + new `public-mcp-smoke`)
-- Skills + prompts + starter README updates
-- Admin SPA sign-in view rewrite
-
-Phase 2 (v0.1.x):
-
-- Enable Google + Apple `socialProviders` (config-only — Apple needs Apple Developer cert setup which is consumer-side)
-- Magic-link + email-OTP plugins enabled (need `ResendEmailSender` wired)
-- Account-linking with reauth UI in publication starter
-
-## How to apply
-
-When reviewing or implementing a change that touches auth, MCP routing, or roles:
-
-1. **Identity and local sessions** — depend on the adapter's public `Auth`
-   interface. `createAuth()` is the curated Better Auth-backed Cloudflare
-   default; do not import Better Auth internals outside that implementation or
-   add an un-curated passthrough.
-2. **Mutable staff privilege** — call `auth.getUserRole(userId)` on every
-   protected REST/MCP invocation. Do not trust a role captured in an OAuth
-   grant or long-lived token.
-3. **MCP transport** — export `createOAuthProvider(...)` at the Worker top
-   level. It owns DCR/PKCE/token verification and dispatches `/mcp` and
-   `/mcp/staff`; the consent handler uses the current local `Auth` session.
-4. **MCP surface** — use explicit `View.spec.surface` and
-   `Trigger.source.surface`. The adapter pre-filters each catalog; the shared
-   runtime evaluator then enforces the target's `requires.auth.all` and
-   optional guard on every call.
-5. **Scopes and props** — advertise the compatibility scope `mcp`. Store only
-   immutable grant identity (`userId`, `clientId`, scopes); never store mutable
-   staff role or raw/refresh tokens in runtime context.
-6. **REST credentials** — normalize sessions, OAuth JWTs, and an optional
-   consumer `credentialResolver` into `HandlerContext`. A recognized invalid
-   API key/PAT fails closed and never falls back to a cookie. Standard remote
-   MCP does not promise raw REST key/PAT support.
-7. **Adapter portability** — auth remains adapter-owned. A future adapter
-   verifies its platform's credentials and supplies the same normalized
-   runtime context; `mantle-runtime` does not gain a Better Auth dependency or
-   an auth storage port.
-
-## Sources
-
-- [Better Auth MCP plugin docs](https://better-auth.com/docs/plugins/mcp)
-- [Better Auth OAuth 2.1 Provider plugin docs](https://better-auth.com/docs/plugins/oauth-provider)
-- [Better Auth admin plugin docs](https://better-auth.com/docs/plugins/admin)
-- [Better Auth changelog (1.5+)](https://better-auth.com/blog/1-5)
-- [RFC 7591 — Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591)
-- [RFC 9728 — Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728)
-
-## Amendment — 2026-05-15: MCP carve-out to `@cloudflare/workers-oauth-provider`
-
-Empirical follow-up to the §"Decision" record above. After shipping the Better Auth `mcp()`-plugin path through `0.0.8-beta.5`, Claude Desktop and claude.ai (web) consistently failed at the OAuth handover even though the server-side dance was RFC-correct (DCR + PKCE + AS metadata + PRM all verified via `wrangler tail`). The Anthropic-side error always surfaced as a generic `ofid_*` reference; `/token` returned 200, then the MCP client never made the post-OAuth `/staff/mcp` POST.
-
-We built an isolated POC worker (`the deleted MCP POC worker`, since deleted) that ran `@cloudflare/workers-oauth-provider` at top level with a single dummy `echo` MCP tool. The POC connected to claude.ai cleanly. Migrating the same pattern back to `the legacy MCP test deployment`, three constraints were narrowed:
-
-1. **MCP resource path must start with `/mcp`.** `/staff/mcp` fails (claude.ai drops the session after a server-correct `/token` success). `/mcp/staff` works. Probably an Anthropic-side URL pattern check from an early MCP draft; not currently documented in any spec we found.
-2. **`scopes_supported` must not contain colons.** Advertising `["mcp:read", "mcp:staff"]` causes claude.ai to silently omit `scope=` from `/authorize`, yielding a zero-scope token grant that the client then rejects post-token. Single `["mcp"]` works. Per-surface differentiation moves server-side: staff role is checked in the apiHandler via D1 `getUserRole`, not via OAuth scope.
-3. **OAuth provider must be top-level worker entry.** `export default new OAuthProvider({...})` is required so the lib intercepts `/.well-known/oauth-*` + `/oauth/{authorize,token,register}` + `apiRoute(s)` before forwarding to `defaultHandler` (Hono). Side-mounting from inside Hono left the lib unable to inject `env.OAUTH_PROVIDER` for the consent handler.
-
-### Architectural change
-
-| Concern | Before (ADR-0014 §Decision) | After (this amendment) |
-|---|---|---|
-| Staff sign-in | Better Auth `admin` + social providers | Same — unchanged |
-| Session / user / role | Better Auth D1 tables | Same |
-| MCP OAuth AS surface | Better Auth `mcp()` plugin (opaque tokens, no JWKS) | `@cloudflare/workers-oauth-provider` (KV grants, lib-internal token format) |
-| MCP endpoints | `/staff/mcp` + `/mcp` mounted in Hono with `auth.api.getMcpSession()` | `/mcp/staff` + `/mcp` registered as `apiHandlers` on the top-level OAuthProvider; lib verifies bearer + sets `ctx.props` |
-| Scope | `mcp:staff` + `mcp:read` colon-namespaced | Single `["mcp"]` advertised; staff gating via D1 role lookup |
-| `auth.getMcpSession()` | Part of the SDK `Auth` interface | Removed; the OAuth lib owns token verification |
-| Consent UI | Better Auth's built-in | Adapter-mounted on Hono via `mountAuthorize`; reads `c.env.OAUTH_PROVIDER` helpers the lib injects, gates on `auth.getSession()` |
-| URL conventions | `/api/auth/mcp/*` | `/oauth/*` — namespaced (not bare) to avoid squatting on generic root paths |
-
-### Why Better Auth still wins the auth-side concerns
-
-The split is clean because the two libs answer different questions:
-
-- **Better Auth** answers "who logged into our backstage console?" — sign-in flows, social providers, session cookie, user/role state in D1.
-- **workers-oauth-provider** answers "how do we authorize a third-party OAuth client (MCP) to act on a backstage user's behalf?" — DCR, PKCE, consent, token issue, KV grant store.
-
-Removing Better Auth would force re-implementing all of (a) and gains nothing — Better Auth is uncontested for the staff sign-in surface. Removing workers-oauth-provider would force re-implementing all of (b) and was tried via Better Auth's `mcp()` plugin; the result didn't reach Anthropic-client compatibility within reasonable iterations.
-
-### Auth-as-contract is preserved without the escape hatch
-
-The companion `CreateAuthConfig.betterAuthOptions?: Partial<BetterAuthOptions>` escape hatch from PR #175 is **removed**. Empirically it was a contested anti-pattern: the carved-out MCP surface no longer requires per-adopter Better Auth overrides (the OAuth surface is fully delegated), and the remaining adopter-facing knobs are all curated first-class fields on `CreateAuthConfig` (`methods[]`, `rateLimit`, `bootstrapOwner`). If a Better Auth knob is missing from the SDK contract, the answer is a curated first-class field, not the un-curated escape hatch.
-
-The original ADR-0014 §"Auth as contract, Better Auth as default" framing stays correct; only the §"Implementation status" reference to `betterAuthOptions` is retracted.
-
-### What didn't change
-
-- The auth storage port remains removed; the adapter owns `Auth` and passes
-  verified, normalized caller context into runtime dispatchers.
-- Apple's `trustedOrigins` auto-append (`https://appleid.apple.com`) and `sameSite=none` cookie injection for cross-site `form_post` callback stay.
-- `appleClientSecret()` helper (from PR #173) stays.
-- All non-OAuth admin endpoints (`/api/auth/*`, `/api/auth/methods`, admin SPA mount) stay on Better Auth.
-- The `bootstrapOwner` + email-OTP + magic-link + `methods[]` carve-out stay.
-
-### Compatibility constraints to re-test before changing
-
-- Anthropic clients required the `/mcp` resource-path prefix during the
-  carve-out verification.
-- Colon-shaped advertised scopes broke the same clients; Mantle therefore
-  advertises one `mcp` scope and re-evaluates target authorization server-side.
-
-## Amendment — 2026-06-30: Hosted-auth boundary and first-party cookie fields
-
-Mantle Platform introduces a first-party hosted-auth use case. Platform owns
-site-owner accounts, billing, entitlement, provider credentials, and managed
-email, while Hosted Auth is an OAuth proxy rather than a member directory.
-Each customer site owns its Better Auth users, linked provider accounts,
-sessions, roles, and grants. For Hosted GitHub, the validated proxy profile's
-`github_login` maps to the existing site-local `user.githubLogin`, so hosted
-and self-managed GitHub reuse the same atomic first-owner bootstrap rule. The
-conventional customer-site path uses the proxy's public OAuth client with PKCE
-and `ADMIN_GITHUB_LOGIN`; it does not use Platform Account OIDC, a client
-secret, or an owner email handoff. The local provider id remains `github`.
-The wire contract remains in [Platform #35](https://github.com/aotter/mantle-platform/issues/35),
-and the product boundary is documented in
-[`docs/auth-hosting-model.md`](https://github.com/aotter/mantle/blob/main/docs/auth-hosting-model.md).
-
-This does not change ADR-0014's core rule: Mantle does not expose an
-un-curated `betterAuthOptions` or `advanced` passthrough. Missing Better
-Auth knobs become first-class SDK fields only when a real Mantle use
-case needs them.
-
-The first-party SSO use case needs exactly three Better Auth fields:
-
-- `trustedOrigins` — app-owned origins that Better Auth should trust for
-  auth flows. SDK-managed provider origins, such as Apple, are still
-  injected automatically.
-- `crossSubDomainCookies` — Better Auth's same-parent-domain cookie
-  support for a trusted first-party app family.
-- `cookiePrefix` — required when two Better Auth apps can write cookies
-  under the same parent domain, so Platform cookies do not collide with
-  Landing or generated-site cookies.
-
-These fields are additive. Existing consumers that do not pass them keep
-the previous cookie/session behavior.
-
-The boundary is deliberately narrower than "hosted auth everywhere":
-
-- Free users can still self-host every login method Mantle exposes
-  through `createAuth()`.
-- Same-parent-domain SSO can use `crossSubDomainCookies` when the same
-  party controls all participating subdomains.
-- Customer-owned domains cannot receive `mantle.tools` cookies. Paid
-  hosted auth for `customer.com` must use an OAuth/OIDC broker flow:
-  Platform authenticates and returns identity; the customer site creates
-  its own local session and maps identity into local grants.
-
-## Amendment — 2026-07-15: one adapter-owned authorization pipeline
-
-Epic #467 extends the auth contract without moving auth into
-`mantle-runtime`. The original adapter-ownership rule remains authoritative:
-Better Auth is the curated Cloudflare default for identity/session/OIDC, and
-`@cloudflare/workers-oauth-provider` remains the compatibility transport for
-remote MCP. Both adapters now normalize verified callers into the same
-runtime context before invoking a target.
-
-`HandlerContext` gains an additive optional `auth` member carrying only:
-
-```ts
-{
-  credential: "session" | "oauth" | "api-key" | "personal-token";
-  credentialId: string | null;
-  clientId: string | null;
-  scopes: readonly string[];
-}
-```
-
-Raw keys/tokens and refresh tokens are forbidden in this context. `ctx.user`
-remains the authenticated subject when one exists; `ctx.staff` is a mutable
-privilege overlay and is re-read from D1 for each protected REST/MCP call.
-
-The Cloudflare adapter exposes one `ConsumerCredentialResolver` seam for a
-site to recognize and verify its own API-key or personal-token formats. It
-distinguishes `not-handled`, `invalid`, and `verified`; a recognized invalid
-credential never falls back to a cookie. Core adds no credential repository,
-table, issuance API, or runtime auth port.
-
-The curated Better Auth facade also adds the OAuth resource primitives needed
-by a generated site acting as a client or provider:
-
-- generic OAuth client `resource` is retained across authorization, code
-  exchange, and refresh;
-- OAuth provider `validAudiences` constrains minted JWT audiences;
-- `getProviderAccessToken(request, providerId)` uses the current local session
-  and returns no refresh token/account row;
-- `verifyOAuthAccessToken()` verifies issuer/JWKS, audience, time claims, and
-  scopes, rejects opaque tokens, and preserves the `401`/`403` distinction.
-
-REST and MCP transport verification remain adapter-specific. After
-normalization, both call the same runtime auth evaluator and optional guard
-Procedure. Standard remote MCP continues to use its OAuth bearer and the
-single compatibility `mcp` resource scope; manifest scopes are re-evaluated on
-every `tools/call`. MCP does not promise to accept a raw REST API key/PAT.
-
-Dynamic membership, billing, and entitlement state remains consumer-owned.
-`requires.guard.procedure` orchestrates a site handler on every invocation but
-does not introduce a Policy atom or an entitlement service. See
-[Guarded API access](../examples/guarded-api.md) for the public API
-and end-to-end examples.
-
-## Amendment — 2026-08-22: Better Auth 1.7 MCP and CIMD convergence
-
-Issue #734 revisits the 2026-05-15 compatibility carve-out after Better Auth
-1.7 shipped a dedicated `@better-auth/mcp` package, resource-bound JWT grants,
-and the MCP 2026-07-28 Client ID Metadata Document profile. These are the
-missing capabilities that originally forced Mantle to keep a second OAuth
-authority.
-
-The Cloudflare adapter now uses one Better Auth instance for staff identity,
-OAuth authorization, consent, client registration/discovery, token issuance,
-and MCP resource verification. `@cloudflare/workers-oauth-provider` and Core's
-`OAUTH_KV` requirement are removed. This amendment supersedes only the
-2026-05-15 transport carve-out; adapter ownership, the curated `Auth` facade,
-fresh D1 staff-role checks, the single `mcp` compatibility scope, and normalized
-`HandlerContext.auth` remain unchanged.
-
-### Provider and resource boundary
-
-`createAuth` keeps its general OAuth-provider capability and adds MCP as an
-explicit curated mode, implemented by composing `jwt()` and
-`@better-auth/mcp`. It is not replaced by an MCP-only factory and no Better
-Auth passthrough is exposed. Standard Workers bind one canonical protected
-resource, `${PUBLIC_ORIGIN}/mcp`. Both `/mcp` and `/mcp/staff` accept tokens for
-that resource; `/mcp/staff` remains a stricter server-side role projection, not
-a second OAuth audience.
-
-The adapter continues to verify and normalize credentials before calling the
-portable runtime. Better Auth imports remain confined to the default
-implementation. A host app may still implement the `Auth` facade or mount its
-own low-level routes; the generated convenience path does not make Better Auth
-a runtime dependency.
-
-MCP request verification reuses Better Auth's DPoP binding primitive and its
-database-backed replay store. Bearer JWTs remain valid; a DPoP-bound JWT is
-accepted only with a matching request proof, method, URL, token hash, and
-single-use proof id. Raw-token callers cannot bypass that request boundary.
-
-### CIMD is primary; DCR is bounded compatibility
-
-The MCP mode composes:
-
-```ts
-mcp({ resource, loginPage, consentPage, scopes: ["mcp"], ... })
-cimd({
-  fetchClientMetadataResource,
-  metadataProfile: "mcp-2026-07-28",
-})
-```
-
-Cloudflare's native `fetch` is the metadata transport only when the Worker has
-`global_fetch_strictly_public` enabled. The runtime flag makes the subrequest
-use Cloudflare's public-Internet routing boundary; Better Auth owns URL
-validation, timeout, response limits, redirect refusal, revalidation, and the
-bounded fetch governor. Mantle does not add a DNS resolver, socket HTTP client,
-or generic transport abstraction.
-
-Unauthenticated DCR remains enabled only for older MCP clients. Its lifetime
-stays at the removed provider's 90-day default. Better Auth expires confidential
-registration secrets; Mantle additionally prunes only expired ownerless DCR
-rows (`clientDiscoveryId`, user owner, and reference owner all absent) on
-OAuth traffic. CIMD-owned and operator-managed clients are never cleanup
-candidates. Cleanup is storage hygiene: failures are logged and do not turn a
-valid authorization request into an outage. No cron or second registry is
-introduced.
-
-Better Auth's `oauthClient` row is the connected-client authority. It retains
-the discovery provenance and validated name, URI, redirect URIs, application
-type, and private server metadata. The consent UI reads only the public
-secret-free projection. Remote client metadata is not copied into portable
-`HandlerContext` or deferred event envelopes.
-
-### Breaking migration
-
-All Better Auth packages upgrade together to 1.7. The D1 schema adopts account
-issuer identity, resource/client relationships, resource-bound token and
-consent fields, discovery provenance, and replay storage required by the
-installed plugins. Removed `validAudiences` configuration becomes the one
-explicit MCP resource; generic upstream OAuth adopts the 1.7 social sign-in and
-callback contract.
-
-This is an alpha breaking migration. KV registrations, grants, and opaque
-tokens are not migrated into D1 because their issuer/resource provenance cannot
-be established safely; MCP clients reconnect through CIMD or DCR. Existing
-pre-1.7 alpha auth databases are reset and re-bootstrapped rather than receiving
-a guessed account issuer backfill.
-
-The authorization endpoints consequently move from `/oauth/*` to Better
-Auth's `/api/auth/oauth2/*` discovery-advertised endpoints. No compatibility
-aliases are retained: existing KV client identifiers are invalid after the
-authority change regardless, and standards-compliant clients rediscover the
-new endpoints.
-
-### Downstream ownership
-
-Starters remove their obsolete OAuth package and `OAUTH_KV` binding while
-retaining `global_fetch_strictly_public`. Landing opts its custom `createAuth`
-construction into the same MCP mode. Landing may keep an `OAUTH_KV` binding for
-its own launch/bootstrap state; that storage is unrelated to the removed Core
-OAuth store and is not renamed by this decision.
-
-This amendment adopts the 2026-07-28 CIMD authorization profile only. Updating
-Mantle's JSON-RPC dispatcher to the complete MCP 2026-07-28 transport revision
-is a separate decision.
-
-## 2026-09-07 amendment — shared OAuth surfaces and revocation
-
-OAuth product UI is not owned by a runtime adapter. `@aotter/mantle-admin`
-owns `MantleOAuthAuth`, the consent/connected-app view models, and
-`handleMantleOAuth(Request) -> Response | null`; `mountMantleOAuth` is a thin
-Hono bridge. The Cloudflare adapter implements protocol actions using the
-same Better Auth instance and D1. Future adapters reuse this contract, not
-Cloudflare-specific UI glue. The old `mountAuthorize` export remains an alias.
-
-`@aotter/mantle-admin-ui` owns the React/shadcn sign-in, consent and connected
-apps surfaces, including i18n, theme and submit state. Auth pages initially
-follow the system theme; the light/dark toggle persists an explicit override.
-Connected apps has an Admin page, but managing one's own grants requires only
-a session, never a staff role. The no-assets HTML fallback uses native forms
-without JavaScript or a second implementation of the Admin design system.
-Both mounts retain same-origin mutation checks and private/no-store responses.
-The consent document's CSP permits only the provider-validated callback
-origin for the browser's form redirect; it never trusts an unsigned query.
-
-MCP authorization remains session-bound: the JWT's original Better Auth
-session must still exist and be unexpired. Admin sign-out/session expiration
-therefore also ends that session's MCP access. A refresh token is not an
-independent authorization to bypass this check. Staff roles are still read
-fresh on every protected request.
-
-Disconnect is scoped to the authenticated user and the selected client. It
-revokes refresh/opaque access tokens, removes pending authorization codes and
-consent rows, and prevents existing JWTs from becoming valid when the client
-is connected again. The verification-create hook captures the consent row ID
-in Better Auth's existing authorization `referenceId`; Better Auth carries it
-through the authorization code and every refresh rotation. MCP JWTs copy that
-reference into `mantle_consent_id`, which must match the active consent row.
-Never look up a new consent at token mint time: doing so could revive a refresh
-lineage whose insertion raced the revoke batch. Same-second reconnect and a
-delayed old refresh row are required regression cases, not clock delays.
-
-MCP mode reserves authorization `referenceId` for this grant identity; future
-curated configuration must not also expose Better Auth's `postLogin` reference
-hooks. MCP access requires a persisted user consent, so `skipConsent` and
-`cachedTrustedClients` must not bypass consent for MCP clients.
-
-This alpha hotfix requires existing MCP clients to reconnect once: pre-hotfix
-JWTs without the grant claim are rejected immediately. No account/session reset
-is required. The unshipped watermark migration 0008 is removed; its unused
-table in the phsu development database is harmless and is not queried or
-deleted during deployment.
-
-## 2026-09-08 amendment — request security boundaries
-
-All Admin session mutations use the existing same-origin guard, including
-same-site sibling origins. Admin HTML forbids framing and is private/no-store.
-The SPA also refuses to render in frames, covering direct static-asset URLs
-that bypass the server mount.
-The Admin/auth mounts cap request bodies at 1 MiB using Hono's body limiter;
-HTTP trigger and MCP dispatchers count streamed JSON bytes before parsing and
-return 413 above the same limit. Media bytes continue through direct uploads.
-This intentionally rejects previously accepted larger control-plane payloads.
-
-Cloudflare `createAuth` explicitly enables Better Auth rate limits regardless
-of `NODE_ENV`, including the OAuth provider's anonymous registration limit of
-five requests per minute. Only `CF-Connecting-IP` supplies the client key.
-The upstream memory store limits each isolate; deployments needing a shared
-abuse quota must additionally enforce it at ingress. No D1 migration or new
-runtime platform dependency is introduced.
-
-Workers must retain initialization work through `ExecutionContext.waitUntil`
-even when the initial challenge finishes or its client disconnects. Schema
-boot precedes OAuth handling. The adapter's static AsyncLocalStorage seeding
-is a version-pinned Better Auth 1.7.2 integration, with accessor-identity
-regression coverage; it does not replace Better Auth's request context.
-Failed Auth initialization evicts only the failed Worker assembly so a later
-request can retry. Non-HTTP callers await Auth initialization with runtime boot;
-HTTP requests anchor it without making public responses depend on Auth health.
-
-### 2026-10-05 amendment — Better Auth 1.7.7 schema validation order
-
-Issue #1335 upgrades the complete Better Auth family and the nested MCP provider
-override together to 1.7.7. The AsyncLocalStorage integration above is retested
-against that pin. Better Auth now checks schemas eagerly at construction, before
-Mantle's lazy schema convergence. Mantle disables only that automatic timing and
-executes the public `context.explicitSchemaCheck` after convergence, before auth
-handlers or session reads. It also checks when the auth-schema ledger matches,
-so incompatible schema drift fails closed. Failed preparation clears its promise
-for retry. Static/plan-only requests still do not prepare auth tables. No new
-consumer pass-through, Core port or public grammar is added.
-
-Existing 1.7.0–1.7.2 databases have a required legacy `account.issuer` that 1.7.7
-no longer writes. Additive convergence preserves it and explicit validation
-refuses it. The database owner performs the documented host-specific constraint
-migration before restart: PostgreSQL drops only NOT NULL, retaining issuer values;
-SQLite requires a reviewed data-preserving table rebuild. Portable Auth does not
-guess the engine or drop/rebuild historical tables. The PostgreSQL upgrade is
-verified on populated old-schema accounts and existing sessions/content.
-
-The conventional `/favicon.ico` reflects the configured site icon, but is a
-fallback after consumer routes, not a newly reserved namespace. Existing
-consumer icon routes must continue to work after a package update.
-
-## Amendment — 2026-09-14: Host-only control-plane cookies
-
-`CreateAuthConfig.hostOnlyCookies` is an opt-in, curated auth field for a
-control plane on a parent domain shared with tenants. It uses native `__Host-`
-cookie names, `Secure`, `Path=/` and no `Domain`; HTTPS is required and enabling
-cross-subdomain sharing at the same time is rejected. Existing defaults and
-Apple's `SameSite=None` requirement remain unchanged. Consumers must treat
-switching cookie names as an explicit sign-in migration, not rewrite request
-or response cookies. This keeps cookie semantics in the auth adapter rather
-than requiring each consumer to wrap Admin, member and OAuth routes.
-
-## Amendment — 2026-09-16: deployment KV session reads
-
-Cloudflare deployments may pass their deployment-owned KV namespace as
-`CreateAuthConfig.sessionCacheKv`. Better Auth reads sessions from KV while
-keeping the canonical session row in D1. OTP verification remains D1-backed
-and rate limiting remains isolate-local because Workers KV does not provide
-the atomic consume or increment operations those paths require. Auth keys use
-the `better-auth:<store-instance-id>:` prefix so replacing D1 makes the old
-store's cached sessions unreachable while the namespace can still hold Mantle projections.
-Session revocation and user updates use Better Auth's cache invalidation and
-therefore follow Workers KV's propagation model.
-
-## 2026-09-18 amendment — one-way email verification storage
-
-The curated Cloudflare auth adapter stores email OTPs and magic-link tokens as
-one-way hashes. This is a fixed security boundary, not adopter configuration;
-`createAuth` does not expose Better Auth's plain or encrypted storage options.
-Deploying this change invalidates any unconsumed codes and links created by an
-older deployment. Users request a new code or link; no database migration is
-needed.
-
-## 2026-09-18 amendment — native Better Auth method options
-
-Issue #924 supersedes only the preceding amendment's “not adopter
-configuration” restriction. Hashed OTP and magic-link storage remains the
-Mantle default, while an explicit official Better Auth `storeOTP` or
-`storeToken` option may override it, including custom hashers/encryption.
-
-`createAuth` remains the Worker lifecycle and Mantle integration boundary, but
-does not copy Better Auth's method option unions. Social methods use the
-provider-specific official `SocialProviders` option keyed by `provider`,
-including async factories. Generic OAuth uses `GenericOAuthConfig`; email OTP
-and magic link use their official option types minus the sender callback that
-Mantle owns. GitHub's bootstrap mapper composes with an adopter mapper instead
-of replacing it. Admin method metadata contains only kind, provider id and
-display label, never options or secrets.
-
-Applications that need to own an entire callback may pass official plugin
-instances through `plugins`. Those plugins do not synthesize Admin metadata,
-and duplicate plugin ids fail at construction. There is no
-`Partial<BetterAuthOptions>` deep merge and no silent plugin replacement.
-
-## 2026-09-21 amendment — keyed default email OTP storage
-
-Issue #989 changes only the Mantle default for email OTP storage. Better Auth
-`storeOTP: "hashed"` is unsalted SHA-256 of the OTP. For the default 6-digit
-alphabet that makes a `verification` table dump a sign-in oracle without
-`BETTER_AUTH_SECRET`. The Cloudflare `createAuth` default is now HMAC-SHA-256
-of the OTP keyed by `BETTER_AUTH_SECRET` (unpadded base64url), so D1 alone is
-not enough.
-
-Magic-link tokens remain Better Auth `hashed`; they are high-entropy. Explicit
-official `storeOTP` / `storeToken` overrides, including `plain`, remain adopter
-configuration (2026-09-18 native-options amendment / #925). `createAuth` does
-not hard-reject those overrides.
-
-Deploying this change invalidates unconsumed OTPs created by an older
-deployment. Users request a new code; no database migration is needed.
-
-## Amendment — 2026-09-21: host-neutral `@aotter/mantle-auth`
-
-Identity remains adapter-owned: there is still no Core auth port. The Better
-Auth surface is extracted into `@aotter/mantle-auth` (not
-`mantle-better-auth`) ahead of a second-host adapter, because the
-implementation was already host-neutral except for ingress IP headers and
-D1/KV bindings.
-
-`createMantleAuth` is the portable constructor. Adapters still own host
-wiring. Cloudflare `createAuth` keeps its existing signature, supplies
-`cf-connecting-ip`, constructs `D1DatabaseDriver`, and optionally wraps
-Workers KV as `AuthSessionCache`. Bun and Vercel have no auth adapter in this
-change; when that wiring lands they must supply their own trusted ingress
-header(s) and driver. The portable package never defaults to a Cloudflare
-header or to client-controlled `X-Forwarded-For`. Missing or empty
-`ipAddressHeaders` fails closed.
-
-## 2026-09-21 amendment — instance-level `accountLinking`
-
-Issue #952 adds `accountLinking` to `CreateMantleAuthOptions` in the host-neutral
-`@aotter/mantle-auth` package, forwarded verbatim to Better Auth's
-`account.accountLinking`; the Cloudflare `CreateAuthConfig` and every future
-host wrapper inherit it.
-
-Issue #924 deferred instance-level control to "a separate low-level instance
-adapter". That deferral is kept for *general* control; this is a single named
-passthrough in the shape `trustedOrigins`, `cookiePrefix` and
-`crossSubDomainCookies` already use, not the option-bag merge #924 rejected.
-The distinction that matters is ambiguity, not nesting depth: a named field
-has one owner and one meaning, while a merged `Partial<BetterAuthOptions>`
-would let an adopter silently overwrite session, cookie and rate-limit
-invariants Mantle enforces.
-
-`accountLinking` earned a field ahead of the low-level adapter because it
-decides whether two sign-ins are one person. Mantle cannot pick that default
-on an adopter's behalf — only the adopter knows which providers verify the
-addresses they return — and until now adopters had no way to express it, in
-either direction.
-
-Mantle sets no default. Omitted, no `account` key is constructed at all and
-Better Auth's defaults govern: implicit linking on, `requireLocalEmailVerified`
-on, `trustedProviders` empty. A consequence worth stating, because the
-`inviteUser` contract above implies otherwise: an invitation row is written
-`emailVerified: 0`, so a social sign-in cannot claim it until the invitee
-verifies by email once.
-
-## 2026-09-21 amendment — one caller gate; surface selects the staff rule only
-
-Sections 3 and 5 above describe `/mcp` and `/mcp/staff` as bearer-only routes
-that answer every unauthenticated request with a `401` challenge, while the
-HTTP Trigger and `/api/views/*` routes resolve callers through `resolveCaller`
-(consumer credential, then OAuth bearer, then cookie session, then anonymous)
-and leave enforcement to each target's `requires`. Issue #977 removes that
-split. Both transports now run the same gate (`gateCaller`):
-
-- Identity resolution is `resolveCaller` for every transport. A cookie session
-  may drive `/mcp` same-origin; the cross-origin guard applies only when the
-  credential is a session, as it already did for HTTP mutations.
-- `surface` decides exactly one thing: `staff` requires `ctx.staff`; `public`
-  admits anonymous callers. Each tool's `requires.auth` and guard still run on
-  every `tools/call`, so a public View with no `requires` is reachable
-  anonymously over MCP exactly as it is over REST, and the handbook's
-  "the same View is safe on REST and on public MCP" holds.
-- The OAuth bootstrap is preserved where it matters. Invalid credentials and
-  anonymous callers on the staff surface still receive `401`/`403` with the
-  RFC 9728 `WWW-Authenticate` challenge. On the public surface an anonymous
-  `initialize` or `tools/list` succeeds (the catalog is caller-independent), and
-  the first `tools/call` whose target requires identity answers HTTP `401` with
-  the same challenge instead of an HTTP `200` JSON-RPC error, so a client can
-  authenticate mid-session and retry. `AUTH_DENIED` maps to `403` the same way.
-
-The fresh-role rule (section 5) and the MCP grant check are unchanged: both
-run inside `resolveCaller`'s bearer path. What changed is only where the
-surface rule sits and that it is the *only* rule the surface adds.
-
-Two invariants that the shared gate must keep, stated so they are not lost
-in a later refactor:
-
-- **The `mcp` scope floor applies to every presented credential.** Bearer
-  tokens are checked inside `resolveCaller`; a consumer credential (site PAT,
-  API key) is checked by the MCP handler after the gate, and a PAT minted for
-  a narrow integration is refused with `403 insufficient_scope` even when its
-  owner is staff. A cookie session carries no scopes and is the same browser
-  identity Admin already trusts, so it is exempt. Anonymous callers present
-  nothing to check; each tool's `requires` governs them.
-- **JSON-RPC over HTTP is `application/json` only.** The dispatcher answers
-  `415` to anything else, so an HTML form (whose enctypes cannot produce that
-  header) can never drive a cookie session on `/mcp`; the same-origin guard
-  remains the second layer.
-
-## 2026-09-22 amendment — OAuth provider extensions are an adopter seam
-
-Issue #1016 supersedes the 2026-05-14 "Better Auth-field pass-through"
-prohibition for one field: `OAuthProviderConfig.extensions`, forwarded to
-`@better-auth/oauth-provider`'s `extensions` option. It follows the 2026-09-18
-line that already exposes official Better Auth options and plugin instances
-rather than copying them.
-
-Why this is not the refused pattern: an `OAuthProviderExtension` is Better
-Auth's declared composition point for token grants, client-authentication
-strategies, discovery metadata and additional claims. MCP Enterprise-Managed
-Authorization needs a `jwt-bearer` (ID-JAG) grant whose issuer and JWKS belong
-to one enterprise IdP; that is adopter configuration, not an SDK default, and
-Core has no business knowing the issuer. Curating a first-class
-`enterpriseIdp` field would put an IdP contract inside Core and still forward
-it verbatim underneath. The reference implementation lives outside Core
-(`@aotterclam/id-jag`).
-
-Boundaries that stay:
-
-- Core's own claims extension (`mantle_consent_id`) is always first on the
-  `mcpResource` branch; adopter extensions append after it and cannot replace
-  it. Better Auth's contract makes claims contributors additive, so an
-  extension cannot overwrite identity or AS-owned claims either way.
-- `createMantleAuth` still owns login and consent pages, CIMD/DCR policy,
-  `mcpResource`, scopes and resources. `extensions` adds grants and strategies
-  beside those; it is not a `Partial<OAuthOptions>` merge and cannot change
-  them.
-- Tokens an extension issues go through the provider's shared token path, so
-  `verifyOAuthAccessToken`, DPoP binding and the MCP challenge are unchanged.
-- No other Better Auth field gains a passthrough by this amendment. The
-  2026-05-14 test still applies to the next proposal.
-
-## 2026-10-02 amendment — a surface with no anonymous tool challenges at connect
-
-The 2026-09-21 amendment kept anonymous `initialize` and `tools/list` open on the public surface and moved the `401` to
-the first `tools/call` that needs identity. MCP clients do not all follow that: several decide whether to run OAuth from
-the connect step alone (an anonymous `initialize` that succeeds means "no sign-in"), so a surface whose every tool needs
-identity never showed them a sign-in. Better Auth's `withMcpAuth` and the MCP SDK's `requireBearerAuth` both challenge
-every unauthenticated request for the same reason.
-
-- A surface is **closed** when none of its tools may be called anonymously: every tool's `requires.auth.all` names at least
-  one predicate (each of `ctx.user`, `ctx.auth`, `ctx.staff`, `ctx.auth.scope` needs an identity). The staff surface is
-  always closed; a public surface with no tools is open, since nothing on it needs a sign-in.
-- On a closed surface every anonymous request (`initialize`, `tools/list`, the SSE `GET`) answers `401` with the RFC 9728
-  `WWW-Authenticate` challenge, as the staff surface already did. The challenge names the surface's scope floor
-  (`scope="mcp"` by default), so the first authorization already asks for it.
-- A surface with at least one tool anonymous may call keeps the 2026-09-21 behaviour: discovery stays open and the first
-  `tools/call` that needs identity answers `401`.
-- Nothing is configured: the rule follows from the plan, so a project that adds a public tool reopens discovery by
-  declaring it.