@aotter/mantle 0.1.2-alpha.5 → 0.1.2-alpha.6

package/docs/adr/0011-adapter-port-spec.md

@@ -177,8 +177,10 @@ const auth = createAuth({
     {
       kind: "social",
       provider: "github",
-      clientId: env.GITHUB_CLIENT_ID,
-      clientSecret: env.GITHUB_CLIENT_SECRET,
+      options: {
+        clientId: env.GITHUB_CLIENT_ID,
+        clientSecret: env.GITHUB_CLIENT_SECRET,
+      },
     },
   ],
   bootstrapOwner: env.ADMIN_GITHUB_LOGIN

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

@@ -734,3 +734,24 @@ one-way hashes. This is a fixed security boundary, not adopter configuration;
 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.

package/docs/adr/README.md

@@ -15,7 +15,7 @@ Records of *why* mantle ended up shaped this way. The numbering preserves POC AD
 | [0011](0011-adapter-port-spec.md) | Adapter port spec. Required runtime ports plus optional feature ports. | Accepted (new) |
 | [0012](0012-views-as-public-rest.md) | Views auto-expose matching REST and `query_view_*` MCP reads on their declared `public` or `staff` surface. Schemas never get a public REST endpoint. | Accepted + amended |
 | [0013](0013-agent-provisioned-consumer-projects.md) | Historical agent-provisioned consumer projects path. Superseded for first launch by landing provision bundles. | Superseded |
-| [0014](0014-auth-better-auth-and-multi-tenant-mcp.md) | The Cloudflare adapter owns one curated Better Auth 1.7 identity/OAuth/MCP authority with CIMD discovery. Verified callers are normalized into runtime context; mutable staff role and target authorization are re-evaluated per call. | Accepted + amended |
+| [0014](0014-auth-better-auth-and-multi-tenant-mcp.md) | The Cloudflare adapter owns one Better Auth 1.7 identity/OAuth/MCP authority with native method options and CIMD discovery. Verified callers are normalized into runtime context; mutable staff role and target authorization are re-evaluated per call. | Accepted + amended |
 | [0016](0016-site-semantic-layer.md) | Site semantic layer: `AGENTS.md` (cross-tool entry) + `.mantle/launch-state.json` (deterministic install context). The older `mantle/site.md` letter surface is suspended from first-run scaffolds. | Accepted (slimmed) |
 | [0017](0017-media-multi-variant-agent-side-optimization.md) | Multi-variant media assets with agent-side optimization and asset-id entry references. | Accepted |
 | [0018](0018-core-starters-repository-boundary.md) | Core produces published SDK artifacts; the separate starters repository validates them as an external consumer. Revisit after release-contract simplification. | Superseded by 0021 |

package/docs/auth-hosting-model.md

@@ -23,11 +23,11 @@ A free Mantle site can run every login method the SDK exposes through
 `createAuth()`:
 
 - social OAuth providers supported by Better Auth;
-- generic provider-specific options through the `social.extras` shape;
+- provider-specific options through Better Auth's native `socialProviders` types;
 - email OTP;
 - magic link;
-- passkey or additional Better Auth method support when the SDK adds a
-  curated first-class field for it;
+- passkey or another Better Auth method through the raw `plugins` path when the
+  application owns its callback and UI;
 - first-party same-domain or same-parent-domain SSO when the site owner
   controls every participating subdomain.
 
@@ -143,9 +143,9 @@ the exact public API and four consumer examples.
 
 ## SDK Surface Rule
 
-Mantle should expose Better Auth knobs only as curated first-class
-fields when there is a real Mantle use case. Do not add a generic
-`betterAuthOptions` or `advanced` passthrough.
+Mantle owns only integration fields with a real Mantle use case. Method
+configuration uses Better Auth's official provider/plugin option types; do not
+copy those unions or add a generic `Partial<BetterAuthOptions>` deep merge.
 
 The current first-party SSO use case justifies these optional fields on
 `CreateAuthConfig`:
@@ -154,14 +154,13 @@ The current first-party SSO use case justifies these optional fields on
 - `crossSubDomainCookies`
 - `cookiePrefix`
 
-The cross-site API use case additionally justifies these curated fields and
-facades:
+The cross-site API use case additionally justifies these fields and facades:
 
-- generic OAuth method `resource`
+- native generic OAuth `authorizationUrlParams`, `tokenUrlParams`, and
+  `refreshTokenParams` for RFC 8707 `resource`
 - OAuth provider `resources` and the curated `mcpResource`
 - `Auth.getProviderAccessToken(request, providerId)`
 - `Auth.verifyOAuthAccessToken(tokenOrRequest, { audience, scopes })`
 
-Generic OAuth providers use Better Auth 1.7's standard social sign-in and
-`/api/auth/callback/:id` path. These are not a raw Better Auth options
-passthrough.
+Generic OAuth providers use Better Auth 1.7's official `GenericOAuthConfig`,
+standard social sign-in and `/api/auth/callback/:id` path.

package/docs/handbook/cloudflare/authentication.md

@@ -3,7 +3,7 @@ description: Configure MANTLE_AUTH_MODE, secrets, the first owner and staff role
 ---
 # Authentication
 
-Conventional Auth is chosen by one variable, `MANTLE_AUTH_MODE`, and fails closed when its configuration is incomplete. This page covers the two modes, the secrets each needs, first-owner bootstrap, roles, the routes that require a session, and the curated Better Auth surface.
+Conventional Auth is chosen by one variable, `MANTLE_AUTH_MODE`, and fails closed when its configuration is incomplete. This page covers the two modes, the secrets each needs, first-owner bootstrap, roles, the routes that require a session, and the Better Auth integration surface.
 
 ## Mode matrix
 
@@ -71,9 +71,59 @@ The staff role is re-read from D1 on every protected REST and MCP call; a revoke
 
 MCP tokens are session-bound: signing out of Admin ends MCP access. See [MCP and agents](../concepts/mcp-and-agents.md).
 
-## Curated Better Auth surface
+## Better Auth configuration
 
-`createAuth()` exposes curated fields, not a Better Auth passthrough: `database`, `baseURL`, `secret`, `methods`, `bootstrapOwner`, `oauthProvider`, `rateLimit`, and for first-party SSO `trustedOrigins`, `cookiePrefix` and `crossSubDomainCookies`. There is no `betterAuthOptions` or `advanced` escape hatch; a new Better Auth knob appears only when a Mantle use case justifies a first-class field.
+`createAuth()` owns the Worker lifecycle, Admin metadata, sender integration,
+bootstrap rules, roles and MCP invariants. Method-specific configuration stays
+native to Better Auth under `options`, so provider updates and type inference do
+not need a matching Mantle DSL update. There is deliberately no
+`Partial<BetterAuthOptions>` deep merge.
+
+```ts
+methods: [
+  {
+    kind: "social",
+    provider: "google",
+    options: { clientId: env.GOOGLE_CLIENT_ID, clientSecret: env.GOOGLE_CLIENT_SECRET, accessType: "offline" },
+  },
+  {
+    kind: "social",
+    provider: "apple",
+    options: async () => ({ clientId: env.APPLE_CLIENT_ID, clientSecret: await loadAppleSecret(env) }),
+  },
+  {
+    kind: "email-otp",
+    sender,
+    options: { otpLength: 8 },
+  },
+]
+```
+
+Email OTP and magic-link storage defaults to `hashed`. Explicit official
+overrides remain available, including custom hashing/encryption:
+
+```ts
+{ kind: "email-otp", sender, options: {
+  storeOTP: { encrypt: encryptOtp, decrypt: decryptOtp },
+} }
+{ kind: "magic-link", sender, options: {
+  storeToken: { type: "custom-hasher", hash: hashMagicToken },
+} }
+```
+
+For complete callback ownership, register an official plugin instance directly.
+Raw plugins do not add a button to `Auth.methods`; the application owns that UI.
+Duplicate plugin ids fail at construction rather than silently replacing one:
+
+```ts
+createAuth({
+  database: env.DB,
+  baseURL: env.PUBLIC_ORIGIN,
+  secret: env.BETTER_AUTH_SECRET,
+  methods: [],
+  plugins: [emailOTP({ sendVerificationOTP, storeOTP: "encrypted" })],
+});
+```
 
 When several first-party apps share one parent domain that the same party controls, configure shared cookies explicitly. `cookiePrefix` is required whenever more than one Better Auth app writes cookies under that domain; `trustedOrigins` is the auth-flow trust list, not a CORS policy.
 
@@ -116,11 +166,15 @@ const clientAuth = createAuth({
   // database, baseURL, secret, other methods...
   methods: [{
     kind: "oauth",
-    providerId: "mantle-platform",
-    clientId: env.PLATFORM_CLIENT_ID,
-    discoveryUrl: "https://platform.example.com/api/auth/.well-known/openid-configuration",
-    scopes: ["openid", "offline_access", "accounts:read"],
-    resource: "https://api.example.com",
+    options: {
+      providerId: "mantle-platform",
+      clientId: env.PLATFORM_CLIENT_ID,
+      discoveryUrl: "https://platform.example.com/api/auth/.well-known/openid-configuration",
+      scopes: ["openid", "offline_access", "accounts:read"],
+      authorizationUrlParams: { resource: "https://api.example.com" },
+      tokenUrlParams: { resource: "https://api.example.com" },
+      refreshTokenParams: { resource: "https://api.example.com" },
+    },
   }],
 });
 

package/package.json

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