@aotter/mantle 0.1.3-alpha.4 → 0.1.3-alpha.5

package/README.md

@@ -16,7 +16,7 @@ npx skills add aotter/mantle --skill install
 ```
 
 To depend on this package in an existing project, pin the exact version
-from `package.json` (currently `0.1.3-alpha.4`):
+from `package.json` (currently `0.1.3-alpha.5`):
 
 ```bash
 npm install @aotter/mantle

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

@@ -3,11 +3,11 @@
 ## Status
 
 Accepted. Amended 2026-05-14, 2026-05-15, 2026-06-30, 2026-07-15,
-2026-08-03, 2026-08-22, 2026-09-18, and 2026-09-21.
+2026-08-03, 2026-08-22, 2026-09-18, 2026-09-21, and 2026-09-22.
 
 ## Date
 
-2026-05-09 (last amended 2026-09-21)
+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
@@ -168,6 +168,8 @@ The internal consumers of `Auth` (post-#193: `mountServerEndpoints`, `createMcpA
 
 **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).
@@ -862,3 +864,36 @@ in a later refactor:
   `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.

package/docs/handbook/cloudflare/authentication.md

@@ -262,6 +262,51 @@ request—DPoP proof binding with database-backed replay protection. It returns
 only `userId`, `clientId`, `credentialId`, and scopes. Opaque tokens are
 rejected; there is no introspection fallback.
 
+## Enterprise-Managed Authorization
+
+MCP's [Enterprise-Managed Authorization](https://modelcontextprotocol.io/extensions/auth/enterprise-managed-authorization)
+extension lets an enterprise IdP decide which employees may reach an MCP
+server. The MCP client exchanges the user's IdP login for an ID-JAG (identity
+assertion authorization grant) and presents it to the server's token endpoint
+as `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer`; no consent page
+is shown. Everything after that is an ordinary access token.
+
+Core does not know any issuer or JWKS. The token grant is a
+`@better-auth/oauth-provider` extension supplied by the adopter through
+`oauthProvider.extensions`, appended after Core's own claims extension:
+
+```ts
+import { identityAssertionAuthorizationGrant } from "@aotterclam/id-jag";
+
+const auth = createAuth({
+  // database, baseURL, secret, methods...
+  oauthProvider: {
+    loginPage: "/admin/sign-in",
+    consentPage: "/oauth/consent",
+    scopes: ["mcp", "offline_access"],
+    mcpResource: env.PUBLIC_ORIGIN + "/mcp",
+    extensions: [
+      identityAssertionAuthorizationGrant({
+        issuer: env.ENTERPRISE_IDP_ISSUER,
+        jwksUrl: env.ENTERPRISE_IDP_JWKS_URL,
+        authorizationServer: env.PUBLIC_ORIGIN,
+        resource: env.PUBLIC_ORIGIN + "/mcp",
+        scopes: ["mcp"],
+        fetchJwks: (input, init) => fetch(input, { ...init, redirect: "manual" }),
+      }),
+    ],
+  },
+});
+```
+
+The extension validates the assertion's signature, issuer, audience and
+lifetime, maps its subject to a user, and issues tokens through the provider's
+shared token path, so `verifyOAuthAccessToken`, DPoP and the MCP challenge
+behave exactly as for interactive grants. `@aotterclam/id-jag` is a reference
+implementation, not a Core dependency; any `OAuthProviderExtension` works.
+Extensions may also add client-authentication strategies, discovery metadata
+and additional claims. The same passthrough applies without `mcpResource`.
+
 ## Source
 - [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
 - [`packages/adapters/cloudflare/src/auth/conventionalAuth.ts`](../../../packages/adapters/cloudflare/src/auth/conventionalAuth.ts)

package/docs/handbook/cloudflare/bindings.md

@@ -40,6 +40,7 @@ export interface Env extends MantleCloudflareEnv {
   readonly R2_ACCESS_KEY_ID?: string;
   readonly R2_SECRET_ACCESS_KEY?: string;
   readonly MEDIA_PUBLIC_URL_BASE?: string;
+  readonly AUDIT?: AnalyticsEngineDataset;                 // optional MCP tools/call audit trail
   readonly MANTLE_INTERNAL_QUEUE?: Queue<DeferredHookEnvelope>;  // optional deferred hooks
   readonly ORDER_EXPIRY_QUEUE?: Queue<{ type: "expire-order"; orderToken: string }>;  // application queue
   readonly INVENTORY_COORDINATOR?: DurableObjectNamespace;  // application-owned
@@ -101,6 +102,63 @@ A deployment-owned namespace that caches the caller-independent MCP catalog proj
 
 Staff media uploads through Staff MCP presigned PUT. The binding alone cannot sign URLs; you also need `R2_ACCOUNT_ID`, `MEDIA_PUBLIC_URL_BASE` and the two S3 credential secrets. See [Media uploads with R2](./media-r2.md).
 
+## Analytics Engine: `AUDIT` (optional)
+
+```jsonc
+"analytics_engine_datasets": [{ "binding": "AUDIT", "dataset": "mantle_mcp_audit" }]
+```
+
+An MCP `tools/call` audit trail: who called which tool on which surface, with
+what outcome and how long it took. The runtime's `McpJsonRpcDispatcher` is the
+single write point; it records nothing unless the composition root passes an
+`AuditSink`, and the write happens through `waitUntil`, off the response path.
+Request and response payloads are never recorded.
+
+```ts
+import { analyticsEngineAuditSink, createMantleWorker } from "@aotter/mantle/cloudflare";
+
+export default createMantleWorker<Env>({
+  plan,
+  audit: (env) => env.AUDIT
+    ? analyticsEngineAuditSink(env.AUDIT, { index: env.PUBLIC_ORIGIN })
+    : undefined,
+});
+```
+
+One dataset may hold many deployments: `index` is the deployment's public
+origin, the only column Analytics Engine filters cheaply. Columns, in order:
+
+| Column | Field |
+|---|---|
+| `index1` | the configured `index` |
+| `blob1` … `blob7` | `surface`, `callerId`, `clientId`, `credential`, `tool`, `outcome`, `operationId` |
+| `double1`, `double2` | `at` (epoch ms), `durationMs` |
+
+`outcome` is `ok`, a runtime Diagnostic code such as `UNAUTHENTICATED` or
+`AUTH_DENIED`, `UNKNOWN_TOOL`, `INVALID_PARAMS`, `INTERNAL`, or a transport gate denial
+(`INVALID_TOKEN`, `INSUFFICIENT_SCOPE`, `INSUFFICIENT_ROLE`, `CROSS_ORIGIN`): a
+`tools/call` refused before it reaches the dispatcher is recorded too, with
+whatever identity the gate established. Its body goes through the same 1 MiB
+bounded reader as an admitted call; a denied request whose body is oversized
+or not JSON is still recorded, with `tool` set to `(unreadable)`, so padding a
+body cannot hide a credential probe. `operationId` is the call's `operationId`
+argument when present, else empty; it correlates retries of one mutation and
+is read the same way on admitted and denied calls. Read it with the
+[SQL API](https://developers.cloudflare.com/analytics/analytics-engine/sql-api/):
+
+```sql
+SELECT timestamp, blob2 AS caller, blob5 AS tool, blob6 AS outcome, double2 AS ms
+FROM mantle_mcp_audit
+WHERE index1 IN ('https://site-a.example', 'https://site-b.example')
+  AND timestamp > NOW() - INTERVAL '7' DAY
+ORDER BY timestamp DESC
+```
+
+Analytics Engine keeps data for a bounded window and samples under very high
+write rates. Longer retention or a tamper-evident trail is an export job on top
+of this dataset. Self-hosted runtimes may implement `AuditSink` over any store;
+the interface is one `record(event)` method.
+
 ## Queues
 
 ```jsonc

package/docs/handbook/cloudflare/conventional-worker.md

@@ -51,7 +51,7 @@ Once per isolate, `createMantleWorker` assembles and memoizes:
 - Conventional bindings: `DB` becomes the D1 driver, `ASSETS` serves the Admin bundle, `MANTLE_KV` (when bound) becomes the MCP catalog projection. See [Bindings](./bindings.md).
 - Conventional Auth chosen by `MANTLE_AUTH_MODE`, or your `auth` factory. See [Authentication](./authentication.md).
 - Runtime endpoints: manifest HTTP Triggers, `GET /api/views` and `GET /api/views/<name>` for public Views.
-- Admin at `/admin` when Admin assets are present, OAuth consent and discovery, and MCP at `/mcp` and `/mcp/staff`.
+- Admin at `/admin` when Admin assets are present, OAuth consent and discovery, and MCP at `/mcp` and `/mcp/staff`. The MCP transport is Streamable HTTP, POST-only: no session header, no server-initiated stream (`GET` answers `405`), and `tools/call` answers `401` with an OAuth challenge so a client can authenticate mid-session and retry. Verified against the official TypeScript client SDK `@modelcontextprotocol/client` 2.0.0 in the adapter's conformance test; that pin is the gate when the SDK is upgraded.
 - A `/favicon.ico` route derived from `siteDefaults.icons`. This is a convention, not a reserved path; an existing host route wins.
 - The final cache policy on every response, and best-effort purge of the deployment-scoped public tag after publishing-content and site-setting writes.
 - A redacted error boundary: an unexpected failure returns `500` with `{ "ok": false, "error": "internal_error" }` and `private, no-store`.

package/docs/spec-only-host-adoption.md

@@ -6,7 +6,7 @@ Runtime. This Spec-only path is allowed by
 [ADR-0019](adr/0019-sealed-manifest-runtime-pipeline.md), not a new adapter,
 manifest grammar, or fork of Core.
 
-This recipe targets `0.1.3-alpha.4`. Pin the package, record the tested version, and
+This recipe targets `0.1.3-alpha.5`. Pin the package, record the tested version, and
 rerun compatibility checks when upgrading.
 
 ## What stays with the host

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.1.3-alpha.4",
+  "version": "0.1.3-alpha.5",
   "description": "Embeddable Mantle Core umbrella with Spec and Runtime; Web, Admin, Auth, Bun, Vercel, Cloudflare, and Admin UI are optional peer packages.",
   "license": "Apache-2.0",
   "homepage": "https://mantle.tools/",
@@ -83,8 +83,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@aotter/mantle-runtime": "0.1.3-alpha.4",
-    "@aotter/mantle-spec": "0.1.3-alpha.4"
+    "@aotter/mantle-runtime": "0.1.3-alpha.5",
+    "@aotter/mantle-spec": "0.1.3-alpha.5"
   },
   "peerDependencies": {
     "aws4fetch": "^1.0.20",
@@ -92,13 +92,13 @@
     "hono": "^4.12.0",
     "@libsql/client": "^0.17.4",
     "zod": "^4.5.0",
-    "@aotter/mantle-admin-ui": "0.1.3-alpha.4",
-    "@aotter/mantle-admin": "0.1.3-alpha.4",
-    "@aotter/mantle-auth": "0.1.3-alpha.4",
-    "@aotter/mantle-bun": "0.1.3-alpha.4",
-    "@aotter/mantle-vercel": "0.1.3-alpha.4",
-    "@aotter/mantle-web": "0.1.3-alpha.4",
-    "@aotter/mantle-cloudflare": "0.1.3-alpha.4"
+    "@aotter/mantle-admin": "0.1.3-alpha.5",
+    "@aotter/mantle-auth": "0.1.3-alpha.5",
+    "@aotter/mantle-bun": "0.1.3-alpha.5",
+    "@aotter/mantle-admin-ui": "0.1.3-alpha.5",
+    "@aotter/mantle-vercel": "0.1.3-alpha.5",
+    "@aotter/mantle-cloudflare": "0.1.3-alpha.5",
+    "@aotter/mantle-web": "0.1.3-alpha.5"
   },
   "peerDependenciesMeta": {
     "@aotter/mantle-admin": {
@@ -144,13 +144,13 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.11",
     "zod": "^4.5.4",
-    "@aotter/mantle-admin": "0.1.3-alpha.4",
-    "@aotter/mantle-admin-ui": "0.1.3-alpha.4",
-    "@aotter/mantle-auth": "0.1.3-alpha.4",
-    "@aotter/mantle-bun": "0.1.3-alpha.4",
-    "@aotter/mantle-vercel": "0.1.3-alpha.4",
-    "@aotter/mantle-cloudflare": "0.1.3-alpha.4",
-    "@aotter/mantle-web": "0.1.3-alpha.4"
+    "@aotter/mantle-admin-ui": "0.1.3-alpha.5",
+    "@aotter/mantle-auth": "0.1.3-alpha.5",
+    "@aotter/mantle-bun": "0.1.3-alpha.5",
+    "@aotter/mantle-admin": "0.1.3-alpha.5",
+    "@aotter/mantle-cloudflare": "0.1.3-alpha.5",
+    "@aotter/mantle-web": "0.1.3-alpha.5",
+    "@aotter/mantle-vercel": "0.1.3-alpha.5"
   },
   "engines": {
     "node": ">=22"