@aotter/mantle 0.2.0-alpha.9 → 0.2.1-alpha.1

package/README.md

@@ -1,8 +1,14 @@
 # Mantle
 
-Generate native SQL for Bun SQLite/PostgreSQL and Cloudflare D1/PostgreSQL.
-The build-time compiler uses the closed v2 grammar and canonical SQL policy.
-Applications import contract primitives and official drivers.
+Mantle is an agent-native application SDK and backend compiler. Declare Schemas, Views, Procedures and Triggers in
+YAML manifests; `mantle generate` compiles them at build time into native SQL and typed TypeScript for SQLite (Bun or
+Cloudflare D1) and PostgreSQL (Bun or Cloudflare Workers). The compiler adds row policy to every query, and the closed v2
+grammar reports actionable diagnostics. Your app keeps its own entry, routes and auth; Mantle adds only the surfaces
+you select: REST, MCP, a web module, Better Auth sign-in and the native Admin.
+
+**Start here:** `npx mantle help` prints the installed docs one topic at a time. `mantle init <directory>` writes a
+complete app shell once (email OTP, `admin` + `user`, Admin, MCP, REST); [examples](./docs/examples/README.md) show
+how to combine stock, own-records, approvals, callbacks, public pages and email into it.
 
 Three packages: `@aotter/mantle` is the SDK with bin `mantle`; `@aotter/mantle-ui` is pure UI without an SDK dependency; `@aotter/mantle-admin` is the optional product with the SDK as a peer. Use matching installed versions and their own docs.
 
@@ -153,8 +159,12 @@ Writes are lazy thenables: await `collection.insert/update/delete(...)` to execu
 or pass unused Writes from the same Store to `store.batch([...])` for atomic results in input order;
 a stale lock, excluded row or unique clash rolls back the whole batch with `CONFLICT`.
 A batch step cannot use a previous step's result. D1 supports only batch.
-On bun:sqlite and PostgreSQL, `store.transaction(async tx => { ... })` binds `collection`, `views`
-and `procedures` to one transaction: resolve commits, throw rolls back; nested transactions and `tx.batch` are refused.
+On bun:sqlite and PostgreSQL, `store.transaction(async tx => { ... })` binds `collection`, `batch`, `views`
+and `procedures` to one transaction: resolve commits, throw rolls back; nested transactions are refused.
+`tx.batch` and a ref handler's `ctx.store.batch` join that same transaction, without a savepoint or another BEGIN.
+A rejected batch makes the whole outer transaction rollback-only: even if the callback catches the error and returns,
+its transaction rejects with the first batch failure and rolls back every write. This includes batch validation errors.
+Ref handlers can use `ctx.store.batch` on every target, including D1, without creating another Store.
 PostgreSQL defaults to serializable; `{ isolation: "read committed" }` selects another level. There is no automatic retry.
 SQLite uses BEGIN IMMEDIATE and queues all Store/generated driver calls on the same Database until COMMIT/ROLLBACK;
 Inside a transaction callback the outer Store or handle passed to a Mantle driver throws `INPUT_VALIDATION_FAILED`; use `tx`.

package/dist/auth/adapter.js

@@ -1,10 +1,3 @@
-/**
- * Better Auth `database` adapters on the same native handle as the data layer: a Cloudflare D1 binding, or PostgreSQL through Bun.SQL or postgres.js.
- * No Kysely. Rules (where semantics, joins, field/model mapping, value transforms) come from Better Auth's own
- * `createAdapterFactory`; this file only turns its already-normalised calls into parameterised SQL.
- * `consumeOne` and `incrementOne` are single statements: D1 has no transactions, and they guard OTP consumption and
- * attempt counting.
- */
 import { createAdapterFactory } from "@better-auth/core/db/adapter";
 import { APIError } from "@better-auth/core/error";
 import { getAuthTables } from "@better-auth/core/db";
@@ -16,8 +9,6 @@ import * as sqlite from "../kernel/dialect/sqlite.js";
 import * as bunSql from "../kernel/driver/postgres.js";
 import { condition as spell } from "../kernel/where.js";
 const nativeReaders = new WeakMap();
-/** Selected auth queries share this adapter's handle, dialect and Better Auth's physical model/field mapping. */
-/** Better Auth's table and column names for these options (modelName/fieldName mapping); needs no database. */
 export function authNames(options) {
     const schema = getAuthTables(options);
     return {
@@ -45,7 +36,6 @@ function customAdapter(d, exec, seed, insertOnly = false, options) {
             }
             return spell(d, col, operator === "not_in" ? "notIn" : operator, value, bind, fold);
         };
-        /** Builds one statement (its own parameters) and runs it. `where` is `WHERE (and...) AND (or...)`, the Kysely adapter's grouping; empty without conditions. */
         const run = (build, protectAdmin = false) => {
             const values = [];
             const bind = (value) => (values.push(value === undefined ? null : value), d.param(values.length));
@@ -60,11 +50,8 @@ function customAdapter(d, exec, seed, insertOnly = false, options) {
             return exec(build({ bind, where }), values, protectAdmin);
         };
         const idOf = (modelKey) => ident(getFieldName({ model: modelKey, field: "id" }));
-        /** The WHERE plus `<id> IN (SELECT <id> FROM t WHERE ... LIMIT 1)`: the statement touches at most one row. */
         const oneRow = (s, table, modelKey, where) => s.where(modelKey, where, `${idOf(modelKey)} IN (SELECT ${idOf(modelKey)} FROM ${ident(table)}${s.where(modelKey, where)} LIMIT 1)`);
-        /** The one row a `RETURNING *` statement changed, else null. */
         const one = async (build) => ((await run(s => `${build(s)} RETURNING *`)).rows[0] ?? null);
-        /** The columns a write gives (an `undefined` is no value). */
         const cols = (values) => Object.entries(values).filter(([, v]) => v !== undefined);
         const assign = (s, values, increment = {}) => [...cols(values).map(([c, v]) => `${ident(c)} = ${s.bind(v)}`), ...Object.entries(increment).map(([c, n]) => `${ident(c)} = ${ident(c)} + ${s.bind(n)}`)].join(", ");
         const { adminRoles: roles, adminUserIds } = options ? adminOptionsOf({ options }) : { adminRoles: [], adminUserIds: [] };
@@ -90,7 +77,6 @@ function customAdapter(d, exec, seed, insertOnly = false, options) {
             return result;
         };
         const deleteMany = async ({ model, modelKey = model, where }) => (await mutation(model, modelKey, where)).changes;
-        /** Joined rows come back as flat `__j<i>__<column>` aliases; fold them into `row[joinModel]` (object or array). */
         const joinColumns = (join) => Object.entries(join).map(([model, config]) => {
             const fields = schema[config.modelKey ?? getDefaultModelName(model)]?.fields ?? {};
             return [...new Set(["id", ...Object.entries(fields).map(([field, attr]) => attr.fieldName || field)])];
@@ -134,7 +120,6 @@ function customAdapter(d, exec, seed, insertOnly = false, options) {
             const column = (field) => getFieldName({ model: modelKey, field });
             const sortColumn = o.sortBy?.field ? ident(column(o.sortBy.field)) : null;
             const order = (prefix = "") => (sortColumn ? ` ORDER BY ${prefix}${sortColumn} ${o.sortBy.direction === "desc" ? "DESC" : "ASC"}` : "");
-            // With a join the primary subquery also needs the id (rows fold by it), every join key and the sort column; they are dropped again below.
             const wanted = o.select?.length ? o.select.map(column) : null;
             const needed = o.join ? [column("id"), ...Object.values(o.join).map(c => c.on.from), ...(o.sortBy ? [column(o.sortBy.field)] : [])] : [];
             const { rows } = await run(s => {
@@ -145,7 +130,6 @@ function customAdapter(d, exec, seed, insertOnly = false, options) {
                     return primary;
                 const entries = Object.entries(o.join);
                 const names = joinColumns(o.join);
-                // The CTE is MATERIALIZED so an unordered LIMIT picks the same parents in both of its uses. One-to-many: number each parent's joined rows in SQL and keep the first `limit`, so only that many rows ever leave the database.
                 const joinSql = entries.map(([joined, c], i) => {
                     const source = c.relation === "one-to-one" ? ident(joined)
                         : `(SELECT *, ROW_NUMBER() OVER (PARTITION BY ${ident(c.on.to)} ORDER BY ${idOf(c.modelKey ?? getDefaultModelName(joined))}) AS "__rn" FROM ${ident(joined)} WHERE ${ident(c.on.to)} IN (SELECT ${ident(c.on.from)} FROM "primary"))`;
@@ -207,8 +191,7 @@ function build(d, native, adapterId, adapterName, exec, transaction, options) {
     const resources = new Map((options.plugins ?? []).flatMap(plugin => plugin.id === "oauth-provider" ? resourceSeeds(plugin.options).map(input => {
         const resource = typeof input === "string" ? { identifier: input } : input;
         return [resource.identifier, { resource, options: plugin.options }];
-    }) : []).reverse()); // first configured entry wins, as upstream insertOnly does
-    // ponytail: one seed per identifier per isolate (upstream seeds once per init); disable a configured resource rather than deleting it.
+    }) : []).reverse());
     const seeded = new Set();
     let writer;
     const pending = new Map();
@@ -220,7 +203,6 @@ function build(d, native, adapterId, adapterName, exec, transaction, options) {
         if (!work) {
             work = (async () => {
                 const { resource, options: oauth } = configured;
-                // Match upstream identifier validation and seed row defaults.
                 let valid;
                 try {
                     valid = oauth.identifierValidator ? !!(await oauth.identifierValidator(identifier)) : !new URL(identifier).hash;
@@ -238,7 +220,6 @@ function build(d, native, adapterId, adapterName, exec, transaction, options) {
                     dpopBoundAccessTokensRequired: resource.dpopBoundAccessTokensRequired ?? false, disabled: resource.disabled ?? false,
                     policyVersion: 1, createdAt: now, updatedAt: now,
                 };
-                // The factory owns ID generation, field mapping and native date/JSON/boolean encoding, including for seeds.
                 writer ??= createAdapterFactory({ config, adapter: customAdapter(d, exec, async () => false, true) })(options);
                 await writer.create({ model: "oauthResource", data });
                 seeded.add(identifier);
@@ -250,14 +231,11 @@ function build(d, native, adapterId, adapterName, exec, transaction, options) {
     };
     const config = {
         adapterId, adapterName, supportsBooleans: native, supportsDates: native, supportsJSON: native, supportsUUIDs: native, transaction,
-        // Bun.SQL returns int8/numeric as strings; a `number` field must reach Better Auth as a number (the rate limiter adds to `lastRequest`). Ids stay strings.
         customTransformOutput: ({ data, fieldAttributes, field }) => (fieldAttributes.type === "number" && typeof data === "string" && field !== "id" && !fieldAttributes.references ? Number(data) : data),
     };
     const factory = createAdapterFactory({ config, adapter: customAdapter(d, exec, seed, false, options) });
-    // Both native adapters implement joins; Better Auth otherwise emulates each joined read with another statement.
     return (options) => factory({ ...options, advanced: { ...options.advanced, database: { ...options.advanced?.database, joins: options.advanced?.database?.joins ?? true } } });
 }
-/** Cloudflare D1 (SQLite). D1 has no interactive transactions, so `transaction` is off and the atomic operations are single statements. */
 export function d1Adapter(db) {
     const exec = async (text, values) => {
         const { results, meta } = await db.prepare(text).bind(...values).all();
@@ -267,11 +245,6 @@ export function d1Adapter(db) {
     nativeReaders.set(factory, { exec, param: sqlite.param, now: ms => new Date(ms).toISOString() });
     return factory;
 }
-/**
- * PostgreSQL through Bun.SQL or postgres.js (the `Postgres` contract the data layer uses). Transactions use `begin`,
- * which pins every statement to one connection. On Workers, create the postgres.js client per request (or per isolate
- * with `max: 1`), as for the data layer.
- */
 export function postgresAdapter(sql) {
     const executor = (handle) => async (text, values, protectAdmin) => {
         const run = async (tx) => {

package/dist/auth/admin.js

@@ -1,5 +1,5 @@
-import { checkOrigin, isAdmin, deny, ContractError } from "../kernel/contracts.js";
-/** Shared selected-boundary guard. Resolve fresh database authority only for Better Auth's raw admin endpoints. */
+import { isAdmin, deny, ContractError } from "../kernel/contracts.js";
+import { checkOrigin } from "../kernel/surface-failure.js";
 export async function guardAuthAdminRequest(request, resolve, basePath = "/api/auth") {
     let path;
     try {
@@ -12,9 +12,6 @@ export async function guardAuthAdminRequest(request, resolve, basePath = "/api/a
     if (path !== admin && !path.startsWith(`${admin}/`))
         return;
     const caller = await resolve();
-    // Mantle policy: only the admin layer reaches Better Auth admin endpoints (oauth-provider's /admin/oauth2/* admits any
-    // session by default); Better Auth access control then decides each action.
-    // Any signed-in user may ask about their own permissions or end an impersonation.
     const own = path === `${admin}/has-permission` || path === `${admin}/stop-impersonating`;
     deny(caller, caller.kind === "user" && caller.credential === "session" && (own || isAdmin(caller)), "auth:admin");
     checkOrigin(request, caller);

package/dist/auth/caller.js

@@ -2,29 +2,19 @@ import { ContractError } from "../kernel/contracts.js";
 import { userCaller } from "../kernel/user-caller.js";
 const users = new WeakMap();
 const withUser = (caller, user) => (users.set(caller, user), caller);
-/** Display identity from the session this Caller already resolved; never an authority source. */
-/** The Better Auth user record the caller was resolved from (session, OAuth or service credential): name, email, image. */
 export const userOf = (caller) => users.get(caller);
-/** @deprecated Use `userOf`; it covers every credential, not only sessions. */
 export const sessionUserOf = userOf;
-/** The admin plugin's ban, lapsed once `banExpires` has passed (as the plugin reads it at sign-in). */
 export const isBanned = (user) => !!user.banned && (user.banExpires == null || new Date(user.banExpires).getTime() > Date.now());
-/** Better Auth owns the role model; absence of its admin plugin grants no admin layer. */
 export function adminOptionsOf(auth) {
     const plugin = auth.options.plugins?.find(plugin => plugin.id === "admin");
     const configured = plugin?.options?.adminRoles ?? ["admin"];
     return { adminRoles: plugin ? (typeof configured === "string" ? configured.split(",") : [...configured]).map(role => role.trim()) : [], adminUserIds: plugin?.options?.adminUserIds ?? [], defaultRole: plugin?.options?.defaultRole ?? "user" };
 }
-/**
- * `load` should be a dynamic import of the module that builds `betterAuth()`, so the bundler keeps it (and Better Auth)
- * out of the entry module: `authLoader(() => import("./auth.js").then(m => m.auth))`.
- */
 export function authLoader(load, cookiePrefix = "better-auth") {
     let instance;
     return {
         cookiePrefix,
         get: () => instance ??= load().then((auth) => {
-            // Better Auth's getSessionCookie looks the cookie up by prefix only: any other spelling would make every signed-in user anonymous.
             if ((auth.options.advanced?.cookiePrefix ?? "better-auth") !== cookiePrefix)
                 throw new Error(`authLoader cookiePrefix '${cookiePrefix}' differs from the auth options' advanced.cookiePrefix.`);
             if (auth.options.advanced?.cookies?.session_token?.name)
@@ -43,7 +33,6 @@ function checkFieldSources(instance, fields, session = false) {
             throw new ContractError("AUTH_CONFIGURATION_ERROR", `User field '${field}' requires an input: false additional field; customSession-only fields are available only to session credentials.`, "auth:user");
     }
 }
-/** All credentials read current authority from the same Better Auth user record. */
 async function loadSubject(instance, id, fields, sessionUser) {
     checkFieldSources(instance, fields, !!sessionUser);
     const context = await instance.$context;
@@ -57,17 +46,6 @@ async function loadSubject(instance, id, fields, sessionUser) {
         }
     return user;
 }
-/**
- * The Caller for a request that is not public. Public routes must not call it.
- * - `Authorization: Bearer`: an OAuth access token verified by Better Auth's resource client for `audience`; an invalid
- *   token is UNAUTHENTICATED, never anonymous. The user (role, ban) is read from the database on every request.
- * - Otherwise a session cookie, validated by `auth.api.getSession` without the cookie cache, so revocation and role
- *   changes apply on the next request. `readOnly: true` explicitly permits a bounded official cookie snapshot
- *   only with no secondaryStorage and cookieCache {enabled:true,maxAge:1..60,refreshCache:false}.
- *   The application classifies reads; HTTP method alone is not sufficient. No cookie means anonymous without loading Better Auth.
- *   When Better Auth extends the session (`updateAge`) it sets a fresh cookie: pass the outgoing response's headers as
- *   `responseHeaders` and those Set-Cookie lines are appended, so the browser cookie slides with the session.
- */
 export async function resolveCaller(request, auth, options = {}) {
     const lacks = (have) => options.scopes?.some(scope => !have.includes(scope));
     const supplied = await options.resolveCredential?.(request);
@@ -91,7 +69,6 @@ export async function resolveCaller(request, auth, options = {}) {
         const { oauthProviderResourceClient } = await import("@better-auth/oauth-provider/resource-client");
         const { createDpopReplayStore } = await import("better-auth/oauth2");
         const context = await instance.$context;
-        // Issuance uses the normalized auth context URL, not the raw origin-only baseURL option.
         const verifier = oauthProviderResourceClient({ options: { ...instance.options, baseURL: context.baseURL, basePath: "" }, $context: instance.$context }).getActions();
         let claims;
         try {
@@ -113,7 +90,6 @@ export async function resolveCaller(request, auth, options = {}) {
     }
     if (authorization !== null)
         throw new ContractError("UNAUTHENTICATED", "The authorization header is not a supported credential.");
-    // With no Cookie header at all getSessionCookie returns null: skip even loading the helper.
     if (!request.headers.has("cookie"))
         return { kind: "anonymous" };
     const { getSessionCookie, splitSetCookieHeader } = await import("better-auth/cookies");
@@ -123,7 +99,6 @@ export async function resolveCaller(request, auth, options = {}) {
     checkFieldSources(instance, options.fields, true);
     const mirror = !!instance.options.secondaryStorage;
     const cache = instance.options.session?.cookieCache;
-    // Only an application-classified read may use Better Auth's bounded signed snapshot. KV remains primary-guarded.
     const cachedRead = options.readOnly === true && !mirror && cache?.enabled === true && cache.refreshCache === false &&
         typeof cache.maxAge === "number" && cache.maxAge >= 1 && cache.maxAge <= 60;
     const initial = await instance.api.getSession({ headers: request.headers, query: { disableCookieCache: !cachedRead, disableRefresh: mirror || !options.responseHeaders }, returnHeaders: true });
@@ -131,7 +106,6 @@ export async function resolveCaller(request, auth, options = {}) {
     if (!found)
         return { kind: "anonymous" };
     if (mirror) {
-        // disableCookieCache bypasses browser cookies, not KV. Only mirrors need a primary authority re-read.
         if (!instance.options.session?.storeSessionInDatabase)
             throw new ContractError("AUTH_CONFIGURATION_ERROR", "Caller resolution with secondaryStorage requires session.storeSessionInDatabase: true.", "auth:session");
         const context = await instance.$context;
@@ -142,7 +116,6 @@ export async function resolveCaller(request, auth, options = {}) {
     const user = await loadSubject(instance, found.user.id, options.fields, found.user);
     if (!user)
         return { kind: "anonymous" };
-    // Never let a stale secondary snapshot extend an already-expired primary session before the check above.
     if (options.responseHeaders) {
         const refreshed = mirror ? await instance.api.getSession({ headers: request.headers, query: { disableCookieCache: true }, returnHeaders: true }) : initial;
         if (!refreshed.response || refreshed.response.session.id !== found.session.id || refreshed.response.user.id !== user.id)

package/dist/auth/consent.js

@@ -0,0 +1,100 @@
+import { PRIVATE, json, readBody, redirect, text } from "./route-http.js";
+export function consentSurface(auth, options) {
+    const { listOAuthConsents: list, revokeOAuthConsent: revoke } = auth;
+    return async (request, caller, route) => {
+        const person = caller.kind === "user" && caller.credential === "session" ? caller.subject : null;
+        const locale = /zh[-_]tw/i.test(request.headers.get("accept-language") ?? "") ? "zh-TW" : "en";
+        if (route === "GET /oauth/consent/data") {
+            if (!person)
+                return json({ consent: null }, 401);
+            const model = await auth.getOAuthConsentRequest(request).catch(() => null);
+            return json({ consent: model }, model ? 200 : 400);
+        }
+        if (route === "GET /oauth/consent") {
+            const model = await auth.getOAuthConsentRequest(request).catch(() => null);
+            return html(consentHtml(locale, model), model ? 200 : 400);
+        }
+        if (route === "POST /oauth/consent") {
+            if (!person)
+                return text("sign in to answer this request", 401);
+            const body = await readBody(request);
+            const decision = new URLSearchParams(body).get("decision");
+            if (decision !== "approve" && decision !== "deny")
+                return text("invalid consent decision", 400);
+            const location = await auth.completeOAuthConsent(new Request(request, { body }), decision === "approve").catch(() => null);
+            const target = location && URL.canParse(location) ? new URL(location) : null;
+            if (!target || /^(javascript|data|vbscript|blob):$/i.test(target.protocol))
+                return text("invalid authorization request", 400);
+            return redirect(target.href);
+        }
+        if (!list || !revoke)
+            return text("not found", 404);
+        if (route === "GET /oauth/consents") {
+            if (options.connectedAppsPage)
+                return redirect(options.connectedAppsPage);
+            if (!person)
+                return text("sign in to see your connected apps", 401);
+            return html(connectedAppsHtml(locale, await list(person)), 200);
+        }
+        if (route === "GET /oauth/consents/data") {
+            if (!person)
+                return json({ consents: [] }, 401);
+            return json({ consents: await list(person) });
+        }
+        if (route === "POST /oauth/consents/revoke") {
+            if (!person)
+                return text("sign in to revoke a connection", 401);
+            const body = await readBody(request);
+            const id = new URLSearchParams(body).get("consent_id");
+            if (!id)
+                return text("invalid consent id", 400);
+            if (!await revoke(person, id))
+                return text("consent not found", 404);
+            return redirect("/oauth/consents", 303);
+        }
+        return text("not found", 404);
+    };
+}
+function html(body, status) {
+    return new Response(body, {
+        status,
+        headers: {
+            ...PRIVATE, "content-type": "text/html; charset=UTF-8", "referrer-policy": "same-origin", "x-content-type-options": "nosniff", "x-frame-options": "DENY",
+            "content-security-policy": "default-src 'none'; script-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'; base-uri 'none'",
+        },
+    });
+}
+const T = {
+    en: {
+        lang: "en", title: "Authorize", eyebrow: "Connect an MCP client", heading: (c) => `Connect ${c}?`,
+        body: (c) => `${c} will be able to use this site's tools through MCP. What it can view or change is still limited by your account permissions.`,
+        returnsTo: "Returns to", scopes: "Requested access", approve: "Connect", deny: "Cancel", invalid: "Invalid authorization request", invalidBody: "Missing or malformed consent payload. Return to your MCP client and try again.",
+        apps: "MCP connections", appsBody: "These MCP clients can use this site's tools. Every action is still checked against your current account permissions.", empty: "No MCP clients are connected.", revoke: "Disconnect",
+    },
+    "zh-TW": {
+        lang: "zh-Hant-TW", title: "授權", eyebrow: "連結 MCP 客戶端", heading: (c) => `要連結 ${c} 嗎？`,
+        body: (c) => `${c} 將能透過 MCP 使用這個網站提供的工具；它能查看或變更哪些內容，仍會依照你的帳號權限決定。`,
+        returnsTo: "完成後返回", scopes: "要求的權限", approve: "連結", deny: "取消", invalid: "無效的授權請求", invalidBody: "缺少或格式錯誤的授權資訊，請返回 MCP 客戶端重試。",
+        apps: "MCP 連線", appsBody: "這些 MCP 客戶端可以使用網站提供的工具；每次操作仍會依照你當下的帳號權限檢查。", empty: "目前沒有已連結的 MCP 客戶端。", revoke: "中斷連線",
+    },
+};
+const esc = (s) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+const page = (l, title, main) => `<!doctype html><html lang="${T[l].lang}"><head><meta charset="utf-8"/><meta name="viewport" content="width=device-width,initial-scale=1"/><title>${title}</title>` +
+    `<style>:root{color-scheme:light dark;font:1rem/1.5 system-ui,sans-serif}body{margin:0;padding:2rem 1rem}main{max-width:32rem;margin:10vh auto}code{overflow-wrap:anywhere}button{font:inherit;padding:.5rem 1rem;cursor:pointer}</style></head><body><main>${main}</main></body></html>`;
+function consentHtml(l, model) {
+    const t = T[l];
+    if (!model)
+        return page(l, t.title, `<p>${t.eyebrow}</p><h1>${t.invalid}</h1><p>${t.invalidBody}</p>`);
+    const client = esc(model.clientName);
+    const host = URL.canParse(model.redirectUri) ? new URL(model.redirectUri).host || new URL(model.redirectUri).protocol : model.redirectUri;
+    return page(l, t.title, `<p>${t.eyebrow}</p><h1>${t.heading(client)}</h1><p>${t.body(client)}</p>` +
+        `<p>${t.returnsTo} <code>${esc(host)}</code></p><p>${t.scopes}</p><ul>${model.scopes.map((sc) => `<li><code>${esc(sc)}</code></li>`).join("")}</ul><form method="post" action="/oauth/consent">` +
+        `<input type="hidden" name="oauth_query" value="${esc(model.oauthQuery)}"/><button type="submit" name="decision" value="approve">${t.approve}</button> ` +
+        `<button type="submit" name="decision" value="deny">${t.deny}</button></form>`);
+}
+function connectedAppsHtml(l, consents) {
+    const t = T[l];
+    const apps = consents.length === 0 ? `<p>${t.empty}</p>` : consents.map((c) => `<section><h2>${esc(c.clientName)}</h2><code>${esc(c.clientId)}</code><form method="post" action="/oauth/consents/revoke">` +
+        `<input type="hidden" name="consent_id" value="${esc(c.id)}"/><button type="submit">${t.revoke}</button></form></section>`).join("");
+    return page(l, t.apps, `<h1>${t.apps}</h1><p>${t.appsBody}</p>${apps}`);
+}

package/dist/auth/hardening.js

@@ -1,13 +1,10 @@
-/** Optional app-owned Better Auth configuration; no Better Auth runtime import. */
 import { AsyncLocalStorage } from "node:async_hooks";
 const retention = new AsyncLocalStorage();
-/** Wrap the app's auth handler call with the current Worker's ctx.waitUntil.bind(ctx). Concurrent requests stay isolated. */
 export function withAuthTasks(waitUntil, run) { return retention.run(waitUntil, run); }
 export function retainAuthTask(task) {
     const settled = task.catch(() => { console.error("[mantle auth] background task failed"); });
     retention.getStore()?.(settled);
 }
-/** Keyed HMAC prevents enumeration of the six-digit OTP space after a database leak. */
 export async function hashEmailOtp(secret, otp) {
     if (!secret)
         throw new Error("AUTH_SECRET is required for OTP hashing.");
@@ -15,7 +12,6 @@ export async function hashEmailOtp(secret, otp) {
     const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, bytes.encode(otp)));
     return btoa(String.fromCharCode(...mac)).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
 }
-/** Never default to a client-controlled X-Forwarded-For. The host must overwrite the configured headers. */
 export function authHardening({ ipAddressHeaders, baseURL, errorURL = "/" }) {
     const headers = ipAddressHeaders.map(h => h.trim()).filter(Boolean);
     if (!headers.length || headers.some(h => !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(h)))
@@ -24,10 +20,8 @@ export function authHardening({ ipAddressHeaders, baseURL, errorURL = "/" }) {
     if (target.origin !== new URL(baseURL).origin)
         throw new Error("Auth errorURL must be same-origin.");
     return { advanced: { ipAddress: { ipAddressHeaders: headers }, backgroundTasks: { handler: retainAuthTask } },
-        // Shared across isolates; Better Auth's defaults and plugin rules (e.g. 3/min per OTP path) set the limits.
         rateLimit: { enabled: true, storage: "database" }, onAPIError: { errorURL: `${target.pathname}${target.search}` } };
 }
-/** Accept the provider-owned profile only on explicitly trusted callbacks, never sign-up/update JSON. */
 export function guardGithubLogin(user, ctx, trustedProviders = ["github"]) {
     if (!("githubLogin" in user))
         return;
@@ -36,5 +30,4 @@ export function guardGithubLogin(user, ctx, trustedProviders = ["github"]) {
         return;
     return { data: { githubLogin: null } };
 }
-/** First-deploy facade: failed setup never falls back to an anonymous/successful auth response. */
 export const authSetupIncomplete = () => Response.json({ error: { code: "SERVICE_UNAVAILABLE", message: "Authentication setup is incomplete.", path: "auth" } }, { status: 503, headers: { "cache-control": "no-store", "retry-after": "60" } });

package/dist/auth/identity.js

@@ -1,4 +1,3 @@
-/** Optional identity operations. Better Auth owns access control, writes and user hooks. */
 import { adminOptionsOf, isBanned } from "./caller.js";
 import { authNames } from "./adapter.js";
 import { APIError } from "@better-auth/core/error";
@@ -16,7 +15,6 @@ const adminSql = (d, auth) => {
     const col = (field) => column("user", field);
     return '(' + [...adminRoles.map(role => `${d === sqlite.dialect ? "instr" : "strpos"}(',' || COALESCE(${col("role")}, '') || ',', ${literal(',' + role + ',')}) > 0`), ...adminUserIds.map(id => `${col("id")} = ${literal(id)}`), 'FALSE'].join(' OR ') + ')';
 };
-/** Translate Better Auth errors at the selected transport boundary, retaining its status and code. */
 async function api(run) {
     try {
         return await run();
@@ -53,11 +51,9 @@ function directory(auth, _caller, headers, d, read) {
     const remove = async (id) => {
         try {
             const found = await find(id);
-            // Better Auth deletes sessions and accounts before the adapter refuses the last admin row; refuse first.
             if (found && adminLayerOf(found, options) && !(await read(`SELECT 1 FROM ${table("user")} WHERE ${privileged} AND ${col("id")} <> ${literal(id)} AND COALESCE(${col("banned")}, ${d === sqlite.dialect ? "0" : "FALSE"}) = ${d === sqlite.dialect ? "0" : "FALSE"} LIMIT 1`, [])).length)
                 throw new ContractError("CONFLICT", "This is the last admin; promote another admin before removing this one.", "identity", { status: 409 });
             await api(() => auth.api.removeUser({ headers, body: { userId: id } }));
-            // The admin plugin removes accounts and sessions, but email-OTP proofs are keyed by email.
             if (found)
                 await (await context()).adapter.deleteMany({ model: "verification", where: [{ field: "identifier", operator: "in", value: ["sign-in", "email-verification", "forget-password"].map(t => `${t}-otp-${found.email.toLowerCase()}`) }] });
             return true;
@@ -148,17 +144,11 @@ function directory(auth, _caller, headers, d, read) {
 }
 export const d1Identity = (db, auth, caller, headers) => directory(auth, caller, headers, sqlite.dialect, (sql, v) => d1Read(db, sql, v));
 export const postgresIdentity = (db, auth, caller, headers) => directory(auth, caller, headers, postgres.dialect, (sql, v) => pgRead(db, sql, v));
-/**
- * Server-side reads of Better Auth users for code without a session (cron, system callers): no SQL against Better Auth's
- * tables, each instance's own table mapping, banned users excluded. Read-only; writes stay with the caller-bound directory.
- */
 export function readIdentity(auth) {
     const options = adminOptionsOf(auth), context = async () => await auth.$context;
     const active = (user) => user && !isBanned(user) ? project(user) : null;
     return {
-        /** The active user with this id, or null. */
         user: async (id) => active(await (await context()).internalAdapter.findUserById(id)),
-        /** Active users in the admin layer (`adminRoles` and `adminUserIds`). ponytail: reads up to 10,000 per role; page it if an app has more admins. */
         admins: async () => {
             const { adapter } = await context();
             const found = new Map();
@@ -180,7 +170,6 @@ const promote = (d, param, source) => {
     const { table, column } = authNames(auth.options), role = column("user", "role"), id = column("user", "id");
     return `UPDATE ${table("user")} SET ${role}=${literal(roles[0])} || CASE WHEN COALESCE(${role}, '') = '' THEN '' ELSE ',' || ${role} END WHERE ${id}=${param} AND NOT EXISTS (SELECT 1 FROM ${table("user")} WHERE ${adminSql(d, auth)}) RETURNING ${id}`;
 };
-/** First-admin bootstrap has no authorized session for setRole; one conditional write elects a single admin. */
 function bootstrap(rule, update) {
     if (!rule.value.trim())
         throw invalid("Bootstrap target cannot be empty.");

package/dist/auth/oauth.js

@@ -11,10 +11,6 @@ const array = (value) => {
         return null;
     }
 };
-/**
- * Fail closed for unbound tokens; reconsent cannot resurrect an issued JWT. As in Better Auth, an `offline_access` grant outlives
- * the browser session: without a live session it stands on an unrevoked, unexpired offline refresh token for the same user and client.
- */
 export async function assertActiveUserGrant(auth, claims, audience) {
     const { sub, azp, sid, mantle_consent_id: id, mantle_consent_reference: reference, mantle_skip_consent: skip } = claims;
     const tokenScopes = typeof claims.scope === "string" ? claims.scope.split(/\s+/).filter(Boolean) : array(claims.scope);
@@ -42,10 +38,8 @@ export async function assertActiveUserGrant(auth, claims, audience) {
         throw new ContractError("UNAUTHENTICATED", "OAuth authorization grant is no longer active.");
     return { id: sub };
 }
-/** Add first to oauthProvider/mcp extensions; Better Auth retains ownership of referenceId. */
 export const oauthGrantExtension = {
     claims: { accessToken: async ({ ctx, user, client, referenceId, grantType, scopes, sessionId }) => {
-            // Narrowing away offline_access on refresh would mint a session-bound token for a session that has already ended.
             if (grantType === "refresh_token" && !scopes.includes("offline_access")) {
                 const session = sessionId ? await ctx.context.adapter.findOne({ model: "session", where: [pair("id", sessionId)] }) : null;
                 if (!session || new Date(session.expiresAt).getTime() <= Date.now())
@@ -58,42 +52,25 @@ export const oauthGrantExtension = {
         } },
 };
 export const OAUTH_GRANT_REVOCATION = "mantle-oauth-grant-revocation";
-/** Password resets (all channels) and an admin password change: the old credential may be compromised, so every session ends too. */
 const RESETS = ["/reset-password", "/email-otp/reset-password", "/phone-number/reset-password", "/admin/set-user-password"];
 const ENDING = [...RESETS, "/change-password", "/admin/ban-user", "/admin/update-user", "/admin/revoke-user-sessions"];
 const RESET_USER = "mantleResetPasswordUser";
-/** Better Auth's email-proof sign-ins: on an unverified user they delete its accounts and sessions (revokeUnprovenAccountAccess). */
 const PROVING = ["/sign-in/email-otp", "/magic-link/verify"];
-/**
- * Add to the Better Auth plugins with the OAuth provider. An `offline_access` grant outlives sign-out and session expiry
- * (as in Better Auth), but a successful password reset, a password change that signs out other devices, an admin ban
- * (`/admin/ban-user`, or `/admin/update-user` setting `banned: true`), an admin session revocation or an admin password
- * change ends every OAuth grant of that user: tokens, consents and unredeemed codes. So does an email OTP or magic-link
- * sign-in attempt on an unverified user: Better Auth strips what was set up before that proof, possibly by someone else
- * who registered the address first, and Mantle ends that party's grants before the attempt is checked.
- */
 export function oauthGrantRevocation() {
     return {
         id: OAUTH_GRANT_REVOCATION,
         hooks: {
-            // Better Auth consumes the reset token, so its user rides this request's own context to the after hook.
             before: [{ matcher: ctx => ctx.path === "/reset-password", handler: createAuthMiddleware(async (ctx) => {
-                        // Better Auth reads the token from the body or the query, in that order.
                         const token = ctx.body?.token || ctx.query?.token;
                         const value = typeof token === "string" && token ? await ctx.context.internalAdapter.findVerificationValue(`reset-password:${token}`) : null;
                         if (value)
                             return { context: { [RESET_USER]: value.value } };
                     }) }, { matcher: ctx => PROVING.includes(ctx.path ?? ""), handler: createAuthMiddleware(async (ctx) => {
-                        // Before the endpoint, while the user is still unverified and the magic-link token is unconsumed: once Better Auth
-                        // marks the address verified, no later request would tell the pre-registrant's grants apart. A failure here fails
-                        // the request before verification, so a retry ends them. A failed attempt ends them too: an unverified user's grants
-                        // are exactly the pre-hijack risk.
                         const email = ctx.path === "/sign-in/email-otp" ? ctx.body?.email : await magicLinkEmail(ctx.context, ctx.query?.token);
                         const found = typeof email === "string" && email ? await ctx.context.internalAdapter.findUserByEmail(email.toLowerCase()) : null;
                         if (found && !found.user.emailVerified)
                             await endGrants(ctx.context.adapter, found.user.id);
                     }) }],
-            // After the endpoint: its own validation and permission checks have passed and it succeeded.
             after: [{ matcher: ctx => ENDING.includes(ctx.path ?? ""), handler: createAuthMiddleware(async (ctx) => {
                         const returned = ctx.context.returned, path = ctx.path ?? "";
                         if (returned instanceof Error || returned instanceof Response && !returned.ok)
@@ -102,13 +79,11 @@ export function oauthGrantRevocation() {
                         const userId = path === "/reset-password" ? ctx[RESET_USER]
                             : path === "/email-otp/reset-password" ? typeof body?.email === "string" && (await ctx.context.internalAdapter.findUserByEmail(body.email.toLowerCase()))?.user.id
                                 : path === "/phone-number/reset-password" ? typeof body?.phoneNumber === "string" && (await ctx.context.adapter.findOne({ model: "user", where: [pair("phoneNumber", body.phoneNumber)] }))?.id
-                                    // Better Auth itself ends the other sessions and keeps the current one.
                                     : path === "/change-password" ? body?.revokeOtherSessions === true && (ctx.context.session?.user.id ?? returned?.user?.id)
                                         : path === "/admin/update-user" ? body?.data?.banned === true && body.userId
                                             : body?.userId;
                         if (typeof userId !== "string" || !userId)
                             return;
-                        // Sessions first: a live session (perhaps the attacker's) could otherwise authorize a new grant after endGrants.
                         if (RESETS.includes(path))
                             await ctx.context.internalAdapter.deleteUserSessions(userId);
                         await endGrants(ctx.context.adapter, userId);
@@ -116,7 +91,6 @@ export function oauthGrantRevocation() {
         },
     };
 }
-/** The email a magic-link token names, read without consuming it; the token is stored as the magic-link plugin's `storeToken` says. */
 async function magicLinkEmail(context, token) {
     if (typeof token !== "string" || !token)
         return;
@@ -132,14 +106,11 @@ async function magicLinkEmail(context, token) {
         return;
     }
 }
-/** Ends a user's grants (for one client, or all): consents, tokens and unredeemed authorization codes. */
 async function endGrants(db, userId, clientId) {
     const where = [pair("userId", userId), ...clientId ? [pair("clientId", clientId)] : []];
-    // Delete first: even if cleanup fails, every issued JWT fails the live-grant check immediately.
     await db.deleteMany({ model: "oauthConsent", where });
     for (const model of ["oauthRefreshToken", "oauthAccessToken"])
         await db.updateMany({ model, where: [...where, { field: "revoked", value: null }], update: { revoked: new Date() } });
-    // An unredeemed code would mint a new token lineage after reconsent.
     const code = (v) => { const x = authCode(v); return x?.userId === userId && (!clientId || x.query.client_id === clientId); };
     const codes = [userId, clientId].filter(x => x !== undefined).map(x => ({ field: "value", operator: "contains", value: JSON.stringify(x) }));
     for (let offset = 0;;) {
@@ -152,7 +123,6 @@ async function endGrants(db, userId, clientId) {
         offset += page.length - ids.length;
     }
 }
-/** A verification value that is an authorization code, with its user and client; else undefined. */
 function authCode(text) {
     let value;
     try {
@@ -163,7 +133,6 @@ function authCode(text) {
     }
     return value?.type === "authorization_code" && typeof value.userId === "string" && typeof value.query?.client_id === "string" ? value : undefined;
 }
-/** Signed-query and consent APIs over the same application-owned instance and adapter (including renamed tables). */
 export function oauthConsents(auth) {
     const adapter = async () => (await auth.$context).adapter;
     return {
@@ -207,7 +176,6 @@ export function oauthConsents(auth) {
         },
     };
 }
-/** Optional scheduled storage hygiene, not boot work or an authorization rule. Owned/CIMD clients survive. */
 export async function pruneLegacyOAuthClients(auth) {
     const { adapter } = await auth.$context;
     return adapter.deleteMany({ model: "oauthClient", where: [

package/dist/auth/resource-seeds.js

@@ -1,5 +1,3 @@
-/** Keep runtime inputs while disabling the provider's eager and bulk lazy seeding. No schema or database work. */
-// OAuth provider 1.7.7 shares plugin.options with its eager/lazy seed closures; its seedResources/checkIdentifier helpers are not exported.
 const seeds = new WeakMap();
 export function resourceSeeds(options) {
     const inputs = (seeds.get(options) ?? options.resources ?? []);

package/dist/auth/route-http.js

@@ -0,0 +1,33 @@
+import { ContractError } from "../kernel/contracts.js";
+export const PRIVATE = { "cache-control": "private, no-store" };
+export const CONSENT = new Set(["GET /oauth/consent", "GET /oauth/consent/data", "POST /oauth/consent", "GET /oauth/consents", "GET /oauth/consents/data", "POST /oauth/consents/revoke"]);
+export const MAX_BODY = 1_048_576;
+export const text = (body, status) => new Response(body, { status, headers: PRIVATE });
+export const json = (body, status = 200) => Response.json(body, { status, headers: PRIVATE });
+export const redirect = (location, status = 302) => new Response(null, { status, headers: { location, ...PRIVATE } });
+export const tooLarge = () => new ContractError("INPUT_VALIDATION_FAILED", "Request body exceeds 1 MiB.");
+export async function readBody(request) {
+    if (Number(request.headers.get("content-length")) > MAX_BODY)
+        throw tooLarge();
+    const reader = request.body?.getReader();
+    if (!reader)
+        return "";
+    const decoder = new TextDecoder();
+    let size = 0, text = "";
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                return text + decoder.decode();
+            size += value.byteLength;
+            if (size > MAX_BODY) {
+                void reader.cancel();
+                throw tooLarge();
+            }
+            text += decoder.decode(value, { stream: true });
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}