@aotter/mantle 0.2.0-alpha.1 → 0.2.0-alpha.11

package/dist/auth/identity.js

@@ -0,0 +1,192 @@
+import { adminOptionsOf, isBanned } from "./caller.js";
+import { authNames } from "./adapter.js";
+import { APIError } from "@better-auth/core/error";
+import { ContractError } from "../kernel/contracts.js";
+import { adminLayerOf, rolesFrom } from "../kernel/user-caller.js";
+import * as sqlite from "../kernel/dialect/sqlite.js";
+import * as postgres from "../kernel/dialect/postgres.js";
+import { read as d1Read } from "../kernel/driver/d1.js";
+import { read as pgRead, transaction } from "../kernel/driver/postgres.js";
+const invalid = (message) => new ContractError("INPUT_VALIDATION_FAILED", message, "identity");
+const project = ({ id, email, name, role, githubLogin, emailVerified, createdAt }) => ({ id, email, name, role: role ?? null, githubLogin: githubLogin ?? null, emailVerified: Boolean(emailVerified), createdAt: new Date(createdAt) });
+const literal = (value) => "'" + value.replaceAll("'", "''") + "'";
+const adminSql = (d, auth) => {
+    const { column } = authNames(auth.options), { adminRoles, adminUserIds } = adminOptionsOf(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 ') + ')';
+};
+async function api(run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (error instanceof APIError)
+            throw new ContractError(error.body?.code ?? "AUTH_DENIED", error.message, "identity", { status: error.statusCode, cause: error });
+        throw error;
+    }
+}
+function directory(auth, _caller, headers, d, read) {
+    const options = adminOptionsOf(auth), roles = options.adminRoles, privileged = adminSql(d, auth);
+    const { table, column, has } = authNames(auth.options), col = (field) => column("user", field);
+    const createdAt = d === sqlite.dialect ? col("createdAt") : postgres.wireTimestamp(col("createdAt")).join("");
+    const grantRole = (role = roles[0]) => { if (!role || !roles.includes(role))
+        throw invalid("Role must be configured in Better Auth adminRoles."); return role; };
+    const allowed = async (action) => {
+        if (!(await api(() => auth.api.userHasPermission({ headers, body: { permissions: { user: [action] } } }))).success)
+            throw new ContractError("AUTH_DENIED", `Requires Better Auth user:${action}.`, "identity");
+    };
+    const context = async () => await auth.$context;
+    const find = async (id) => (await context()).adapter.findOne({ model: "user", where: [{ field: "id", value: id }] });
+    const set = async (id, role) => {
+        try {
+            await api(() => auth.api.setRole({ headers, body: { userId: id, role: [...(role.length ? role : rolesFrom(options.defaultRole))] } }));
+            return true;
+        }
+        catch (error) {
+            if (error instanceof ContractError && error.code === "USER_NOT_FOUND")
+                return false;
+            throw error;
+        }
+    };
+    const remove = async (id) => {
+        try {
+            const found = await find(id);
+            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 } }));
+            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;
+        }
+        catch (error) {
+            if (error instanceof ContractError && error.code === "USER_NOT_FOUND")
+                return false;
+            throw error;
+        }
+    };
+    return {
+        adminRoles: roles,
+        async listUsers() {
+            const query = { sortBy: "createdAt", sortDirection: "asc" };
+            let { users, total } = await api(() => auth.api.listUsers({ headers, query }));
+            if (users.length < total)
+                ({ users } = await api(() => auth.api.listUsers({ headers, query: { ...query, limit: total } })));
+            return users.filter(user => adminLayerOf(user, options)).map(project);
+        },
+        async listMembers({ search = "", limit = 50, cursor, cursorDirection = "forward" } = {}) {
+            await allowed("list");
+            if (!Number.isInteger(limit) || limit < 1 || limit > 100 || search.length > 200 || !["forward", "backward"].includes(cursorDirection))
+                throw invalid("Invalid member page options.");
+            const term = search.trim().toLowerCase(), scope = JSON.stringify(["members", term]);
+            let key;
+            if (cursor) {
+                try {
+                    const v = JSON.parse(decodeURIComponent(cursor.slice(2)));
+                    if (!cursor.startsWith("m:") || !Array.isArray(v) || v.length !== 3 || v[0] !== scope || typeof v[1] !== "string" || !Number.isFinite(Date.parse(v[1])) || typeof v[2] !== "string" || !v[2])
+                        throw 0;
+                    key = [v[1], v[2]];
+                }
+                catch {
+                    throw invalid("Invalid member cursor for this search.");
+                }
+            }
+            const values = [], bind = (v) => (values.push(v), d.param(values.length));
+            const conditions = [`NOT ${privileged}`];
+            if (term) {
+                const like = bind(`%${d.escapeLike(term)}%`);
+                conditions.push(`(${[`CAST(${col("id")} AS text)`, col("name"), col("email")].map(c => `${c} ${d.like(true)} ${like}${d.likeEscape}`).join(" OR ")})`);
+            }
+            const backward = cursorDirection === "backward", order = backward ? "DESC" : "ASC", op = backward ? "<" : ">";
+            if (key) {
+                const time = d.cast(bind(key[0]), "timestamptz"), id = bind(key[1]);
+                conditions.push(`(${col("createdAt")} ${op} ${time} OR (${col("createdAt")} = ${time} AND ${col("id")} ${op} ${id}))`);
+            }
+            const rows = await read(`SELECT ${["id", "email", "name", "role", "githubLogin", "emailVerified"].map(field => `${has("user", field) ? col(field) : "NULL"} AS "${field}"`).join(",")},${createdAt} AS "createdAt" FROM ${table("user")} WHERE ${conditions.join(" AND ")} ORDER BY ${col("createdAt")} ${order},${col("id")} ${order} LIMIT ${limit + 1}`, values);
+            const page = rows.slice(0, limit);
+            if (backward)
+                page.reverse();
+            const encode = (row) => `m:${encodeURIComponent(JSON.stringify([scope, typeof row.createdAt === "string" ? row.createdAt : row.createdAt.toISOString(), row.id]))}`;
+            return { items: page.map(project), previousCursor: (backward ? rows.length > limit : !!key) && page[0] ? encode(page[0]) : null, nextCursor: (backward ? !!key : rows.length > limit) && page.at(-1) ? encode(page.at(-1)) : null };
+        },
+        async setUserRole(id, role) {
+            const user = await find(id), current = rolesFrom(user?.role);
+            return set(id, role === null ? current.filter(name => !roles.includes(name)) : typeof role === "string" ? [...new Set([...current, grantRole(role)])] : role);
+        },
+        async inviteUser(email, role) {
+            const adminRole = grantRole(role), normalized = email.trim().toLowerCase();
+            if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(normalized))
+                throw invalid("Invalid invitation email.");
+            try {
+                const { user } = await api(() => auth.api.createUser({ headers, body: { email: normalized, name: normalized.split("@")[0], role: [adminRole] } }));
+                return { kind: "created", id: user.id };
+            }
+            catch (error) {
+                if (!(error instanceof ContractError) || error.code !== "USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL")
+                    throw error;
+                const { users: [found] } = await api(() => auth.api.listUsers({ headers, query: { filterField: "email", filterValue: normalized, limit: 1 } }));
+                if (!found)
+                    throw error;
+                if (!found.emailVerified)
+                    throw new ContractError("AUTH_DENIED", "The existing account must verify its email before receiving admin access.", "identity:invitation");
+                await set(found.id, [...new Set([...rolesFrom(found.role), adminRole])]);
+                return { kind: "exists", id: found.id };
+            }
+        },
+        async revokeInvite(id) {
+            await allowed("delete");
+            const user = await find(id);
+            if (!user || !adminLayerOf(user, options) || user.emailVerified || await (await context()).adapter.findOne({ model: "account", where: [{ field: "userId", value: id }] }))
+                return false;
+            return remove(id);
+        },
+        deleteUser: remove,
+    };
+}
+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));
+export function readIdentity(auth) {
+    const options = adminOptionsOf(auth), context = async () => await auth.$context;
+    const active = (user) => user && !isBanned(user) ? project(user) : null;
+    return {
+        user: async (id) => active(await (await context()).internalAdapter.findUserById(id)),
+        admins: async () => {
+            const { adapter } = await context();
+            const found = new Map();
+            for (const role of options.adminRoles)
+                for (const user of await adapter.findMany({ model: "user", where: [{ field: "role", operator: "contains", value: role }], limit: 10_000 }))
+                    found.set(user.id, user);
+            if (options.adminUserIds.length)
+                for (const user of await adapter.findMany({ model: "user", where: [{ field: "id", operator: "in", value: [...options.adminUserIds] }], limit: 10_000 }))
+                    found.set(user.id, user);
+            return [...found.values()].filter(user => adminLayerOf(user, options)).map(active).filter((user) => !!user);
+        },
+    };
+}
+const matches = (rule, user) => (rule.match === "email" ? user.emailVerified === true ? user.email : null : user.githubLogin)?.trim().toLowerCase() === rule.value.trim().toLowerCase();
+const promote = (d, param, source) => {
+    const auth = typeof source === "function" ? source() : source, { adminRoles: roles } = adminOptionsOf(auth);
+    if (!roles[0])
+        throw new ContractError("AUTH_CONFIGURATION_ERROR", "Bootstrap requires Better Auth adminRoles.", "identity");
+    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}`;
+};
+function bootstrap(rule, update) {
+    if (!rule.value.trim())
+        throw invalid("Bootstrap target cannot be empty.");
+    return async (user) => {
+        if (!matches(rule, user))
+            return;
+        if (!(await update(user.id)).length)
+            console.warn("[mantle bootstrap] promotion blocked: admin already exists.");
+    };
+}
+export function d1BootstrapAdmin(db, rule, auth) {
+    return bootstrap(rule, id => d1Read(db, promote(sqlite.dialect, "?", auth), [id]));
+}
+export function postgresBootstrapAdmin(db, rule, source) {
+    return bootstrap(rule, id => transaction(db, async (tx) => {
+        const auth = typeof source === "function" ? source() : source;
+        await tx.unsafe("SELECT pg_advisory_xact_lock(hashtext($1))", [authNames(auth.options).table("user")]);
+        return tx.unsafe(promote(postgres.dialect, "$1", auth), [id]);
+    }, { isolation: "read committed" }, "identity/bootstrap"));
+}

package/dist/auth/oauth.d.ts

@@ -0,0 +1,63 @@
+import type { oauthProvider } from "@better-auth/oauth-provider";
+import type { AuthInstance } from "./caller.js";
+/**
+ * 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 declare function assertActiveUserGrant(auth: AuthInstance, claims: Record<string, unknown>, audience: string | readonly string[]): Promise<{
+    id: string;
+}>;
+/** Add first to oauthProvider/mcp extensions; Better Auth retains ownership of referenceId. */
+export declare const oauthGrantExtension: NonNullable<Parameters<typeof oauthProvider>[0]["extensions"]>[number];
+export declare const OAUTH_GRANT_REVOCATION = "mantle-oauth-grant-revocation";
+/**
+ * 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 declare function oauthGrantRevocation(): {
+    id: "mantle-oauth-grant-revocation";
+    hooks: {
+        before: ({
+            matcher: (ctx: import("better-auth").HookEndpointContext) => boolean;
+            handler: import("better-auth").Middleware<import("better-auth").MiddlewareOptions, (inputContext: import("better-auth").MiddlewareInputContext<import("better-auth").MiddlewareOptions>) => Promise<{
+                context: {
+                    mantleResetPasswordUser: string;
+                };
+            } | undefined>>;
+        } | {
+            matcher: (ctx: import("better-auth").HookEndpointContext) => boolean;
+            handler: import("better-auth").Middleware<import("better-auth").MiddlewareOptions, (inputContext: import("better-auth").MiddlewareInputContext<import("better-auth").MiddlewareOptions>) => Promise<void>>;
+        })[];
+        after: {
+            matcher: (ctx: import("better-auth").HookEndpointContext) => boolean;
+            handler: import("better-auth").Middleware<import("better-auth").MiddlewareOptions, (inputContext: import("better-auth").MiddlewareInputContext<import("better-auth").MiddlewareOptions>) => Promise<void>>;
+        }[];
+    };
+};
+export interface OAuthConsentRequest {
+    readonly clientName: string;
+    readonly redirectUri: string;
+    readonly scopes: readonly string[];
+    readonly oauthQuery: string;
+}
+export interface OAuthConsentInfo {
+    readonly id: string;
+    readonly clientId: string;
+    readonly clientName: string;
+    readonly scopes: readonly string[];
+}
+/** Signed-query and consent APIs over the same application-owned instance and adapter (including renamed tables). */
+export declare function oauthConsents(auth: AuthInstance & {
+    handler(request: Request): Promise<Response>;
+}): {
+    getOAuthConsentRequest: (request: Request) => Promise<OAuthConsentRequest | null>;
+    completeOAuthConsent: (request: Request, accept: boolean) => Promise<string>;
+    listOAuthConsents: (userId: string) => Promise<OAuthConsentInfo[]>;
+    revokeOAuthConsent: (userId: string, consentId: string) => Promise<boolean>;
+};
+/** Optional scheduled storage hygiene, not boot work or an authorization rule. Owned/CIMD clients survive. */
+export declare function pruneLegacyOAuthClients(auth: AuthInstance): Promise<number>;

package/dist/auth/oauth.js

@@ -0,0 +1,185 @@
+import { createAuthMiddleware } from "@better-auth/core/api";
+import { nativeAuthRead } from "./adapter.js";
+import { ContractError } from "../kernel/contracts.js";
+const pair = (field, value) => ({ field, value });
+const array = (value) => {
+    try {
+        const parsed = typeof value === "string" ? JSON.parse(value) : value;
+        return Array.isArray(parsed) && parsed.every(x => typeof x === "string") ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+};
+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);
+    const offline = !!tokenScopes?.includes("offline_access");
+    if (![sub, azp].every(x => typeof x === "string" && x.length) || !(offline && sid == null || typeof sid === "string" && sid.length) || !(skip === true && id === null || typeof id === "string" && id.length))
+        throw new ContractError("UNAUTHENTICATED", "OAuth token is not bound to a user session.");
+    const { exec, param, now, table, column } = nativeAuthRead(auth.options);
+    const at = now(Date.now());
+    const c = (field) => `c.${column("oauthConsent", field)}`, s = (field) => `s.${column("session", field)}`, client = (field) => `client.${column("oauthClient", field)}`, r = (field) => column("oauthRefreshToken", field);
+    const { rows } = await exec(`SELECT ${s("id")} AS session, ${c("id")} AS "consentId", ${c("referenceId")} AS reference, ${c("resources")} AS resources, ${c("scopes")} AS scopes,
+      ${client("skipConsent")} AS "skipConsent", ${client("disabled")} AS disabled, ${client("scopes")} AS "clientScopes"
+    FROM ${table("oauthClient")} client LEFT JOIN ${table("session")} s ON ${s("id")} = ${param(1)} AND ${s("userId")} = ${param(2)} AND ${s("expiresAt")} > ${param(3)}
+    LEFT JOIN ${table("oauthConsent")} c ON ${c("id")} = ${param(4)} AND ${c("userId")} = ${param(2)} AND ${c("clientId")} = ${client("clientId")}
+    WHERE ${client("clientId")} = ${param(5)}`, [sid ?? null, sub, at, id, azp]);
+    const grant = rows[0];
+    const live = !!grant?.session || offline && !!grant && (await exec(`SELECT ${r("scopes")} AS scopes FROM ${table("oauthRefreshToken")}
+    WHERE ${r("userId")} = ${param(1)} AND ${r("clientId")} = ${param(2)} AND ${r("revoked")} IS NULL AND ${r("expiresAt")} > ${param(3)}`, [sub, azp, at])).rows.some(row => array(row.scopes)?.includes("offline_access"));
+    const provider = auth.options.plugins?.find(plugin => plugin.id === "oauth-provider");
+    const firstParty = skip === true && id === null && !!grant?.skipConsent;
+    const resources = firstParty ? (typeof claims.aud === "string" ? [claims.aud] : array(claims.aud)) : array(grant?.resources);
+    const scopes = firstParty ? array(grant?.clientScopes) ?? provider?.options?.scopes : array(grant?.scopes);
+    const requested = typeof audience === "string" ? [audience] : audience;
+    const tokenAudiences = typeof claims.aud === "string" ? [claims.aud] : array(claims.aud) ?? [];
+    if (!grant || !live || grant.disabled || !firstParty && (!grant.consentId || (grant.reference ?? null) !== reference) || !resources || !scopes || !tokenScopes || !requested.some(x => resources.includes(x) && tokenAudiences.includes(x)) || !tokenScopes.every(x => scopes.includes(x)))
+        throw new ContractError("UNAUTHENTICATED", "OAuth authorization grant is no longer active.");
+    return { id: sub };
+}
+export const oauthGrantExtension = {
+    claims: { accessToken: async ({ ctx, user, client, referenceId, grantType, scopes, sessionId }) => {
+            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())
+                    throw ctx.error("BAD_REQUEST", { error: "invalid_grant", error_description: "The browser session for this grant has ended; keep offline_access or sign in again." });
+            }
+            if (client.skipConsent)
+                return { mantle_consent_id: null, mantle_skip_consent: true };
+            const consent = user && await ctx.context.adapter.findOne({ model: "oauthConsent", where: [pair("userId", user.id), pair("clientId", client.clientId), { field: "referenceId", value: referenceId ?? null }] });
+            return { mantle_consent_id: consent?.id ?? null, mantle_consent_reference: referenceId ?? null };
+        } },
+};
+export const OAUTH_GRANT_REVOCATION = "mantle-oauth-grant-revocation";
+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";
+const PROVING = ["/sign-in/email-otp", "/magic-link/verify"];
+export function oauthGrantRevocation() {
+    return {
+        id: OAUTH_GRANT_REVOCATION,
+        hooks: {
+            before: [{ matcher: ctx => ctx.path === "/reset-password", handler: createAuthMiddleware(async (ctx) => {
+                        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) => {
+                        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: [{ 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)
+                            return;
+                        const body = ctx.body;
+                        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
+                                    : 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;
+                        if (RESETS.includes(path))
+                            await ctx.context.internalAdapter.deleteUserSessions(userId);
+                        await endGrants(ctx.context.adapter, userId);
+                    }) }],
+        },
+    };
+}
+async function magicLinkEmail(context, token) {
+    if (typeof token !== "string" || !token)
+        return;
+    const store = context.options.plugins?.find(plugin => plugin.id === "magic-link")?.options?.storeToken ?? "plain";
+    const hash = typeof store === "object" && store && "hash" in store && typeof store.hash === "function" ? store.hash : undefined;
+    const stored = store === "plain" ? token : hash ? await hash(token)
+        : store === "hashed" ? btoa(String.fromCharCode(...new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(token))))).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "") : undefined;
+    const value = stored === undefined ? null : await context.internalAdapter.findVerificationValue(`magic-link:${stored}`);
+    try {
+        return value ? JSON.parse(value.value).email : undefined;
+    }
+    catch {
+        return;
+    }
+}
+async function endGrants(db, userId, clientId) {
+    const where = [pair("userId", userId), ...clientId ? [pair("clientId", clientId)] : []];
+    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() } });
+    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;;) {
+        const page = await db.findMany({ model: "verification", where: codes, limit: 100, offset, sortBy: { field: "id", direction: "asc" } });
+        const ids = page.filter(v => code(v.value)).map(v => v.id);
+        if (ids.length)
+            await db.deleteMany({ model: "verification", where: [{ field: "id", operator: "in", value: ids }] });
+        if (page.length < 100)
+            break;
+        offset += page.length - ids.length;
+    }
+}
+function authCode(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return;
+    }
+    return value?.type === "authorization_code" && typeof value.userId === "string" && typeof value.query?.client_id === "string" ? value : undefined;
+}
+export function oauthConsents(auth) {
+    const adapter = async () => (await auth.$context).adapter;
+    return {
+        getOAuthConsentRequest: async (request) => {
+            const url = new URL(request.url), clientId = url.searchParams.get("client_id");
+            if (!clientId || !url.search)
+                return null;
+            const api = auth.api;
+            const oauthQuery = url.search.slice(1);
+            const client = await api.getOAuthClientPublicPrelogin({ headers: request.headers, body: { client_id: clientId, oauth_query: oauthQuery } });
+            return { clientName: client.client_name ?? clientId, redirectUri: url.searchParams.get("redirect_uri") ?? client.redirect_uris?.[0] ?? "", scopes: (url.searchParams.get("scope") ?? "").split(/\s+/).filter(Boolean), oauthQuery };
+        },
+        completeOAuthConsent: async (request, accept) => {
+            const oauth_query = (await request.formData()).get("oauth_query");
+            if (typeof oauth_query !== "string" || !oauth_query)
+                throw new ContractError("INPUT_VALIDATION_FAILED", "Missing signed authorization request.");
+            const headers = new Headers(request.headers);
+            headers.set("content-type", "application/json");
+            headers.delete("content-length");
+            const response = await auth.handler(new Request(new URL(`${auth.options.basePath ?? "/api/auth"}/oauth2/consent`, request.url).href, { method: "POST", headers, body: JSON.stringify({ accept, oauth_query }) }));
+            const body = await response.json();
+            if (!response.ok || typeof body.url !== "string")
+                throw new ContractError("INPUT_VALIDATION_FAILED", "Invalid authorization request.");
+            return body.url;
+        },
+        listOAuthConsents: async (userId) => {
+            const { exec, param, table, column } = nativeAuthRead(auth.options);
+            const c = (field) => `c.${column("oauthConsent", field)}`, client = (field) => `client.${column("oauthClient", field)}`;
+            const { rows } = await exec(`SELECT ${c("id")} AS id, ${c("clientId")} AS "clientId", COALESCE(${client("name")}, ${c("clientId")}) AS "clientName", ${c("scopes")} AS scopes
+        FROM ${table("oauthConsent")} c LEFT JOIN ${table("oauthClient")} client ON ${client("clientId")} = ${c("clientId")}
+        WHERE ${c("userId")} = ${param(1)} ORDER BY ${c("updatedAt")} DESC, ${c("id")} ASC`, [userId]);
+            return rows.map(row => ({ id: row.id, clientId: row.clientId, clientName: row.clientName, scopes: array(row.scopes) ?? [] }));
+        },
+        revokeOAuthConsent: async (userId, consentId) => {
+            const db = await adapter();
+            const consent = await db.findOne({ model: "oauthConsent", where: [pair("id", consentId), pair("userId", userId)] });
+            if (!consent)
+                return false;
+            await endGrants(db, userId, consent.clientId);
+            return true;
+        },
+    };
+}
+export async function pruneLegacyOAuthClients(auth) {
+    const { adapter } = await auth.$context;
+    return adapter.deleteMany({ model: "oauthClient", where: [
+            { field: "clientDiscoveryId", value: null }, { field: "userId", value: null }, { field: "referenceId", value: null },
+            { field: "createdAt", operator: "lt", value: new Date(Date.now() - 90 * 86400_000) },
+        ] });
+}

package/dist/auth/resource-seeds.js

@@ -0,0 +1,8 @@
+const seeds = new WeakMap();
+export function resourceSeeds(options) {
+    const inputs = (seeds.get(options) ?? options.resources ?? []);
+    if (!seeds.has(options))
+        seeds.set(options, [...inputs]);
+    options.resources = [];
+    return inputs;
+}

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();
+    }
+}

package/dist/auth/routes.d.ts

@@ -0,0 +1,32 @@
+/** Optional app-mounted auth routes; consent and raw admin routes resolve fresh authority. Better Auth owns tokens. */
+import { type Caller } from "../kernel/contracts.js";
+import { type AuthInstance, type AuthLoader } from "./caller.js";
+export interface AuthRoutesOptions {
+    /** Same basePath as app-owned betterAuth options. */
+    readonly basePath?: string;
+    readonly resolver?: (request: Request) => Caller | Promise<Caller>;
+    readonly methods: readonly ({
+        readonly kind: "social";
+        readonly provider: string;
+    } | {
+        readonly kind: "oauth";
+        readonly providerId: string;
+        readonly displayName?: string;
+    } | {
+        readonly kind: "email-otp" | "magic-link";
+    })[];
+    readonly connectedAppsPage?: string;
+}
+/** The service's auth entry: a Response for a path it owns, `null` for any other. */
+export declare function authRoutes(loader: AuthLoader<AuthInstance & {
+    handler(request: Request): Promise<Response>;
+}>, options: AuthRoutesOptions): (request: Request) => Promise<Response | null>;
+/**
+ * A dynamic registration whose every redirect URI is http on a loopback host and that names no application_type is a
+ * native app (RFC 8252 7.3): local MCP clients register this way. Better Auth reads the missing type as `web`, which
+ * needs https on a non-loopback host, so it would refuse them all. Mark it native, as the client could itself; a
+ * registration naming a type, mixing hosts or using any other redirect is passed through unchanged.
+ */
+export declare function loopbackClientsAreNative(request: Request): Promise<Request>;
+/** Better Auth and host fetch implementations may merge several Set-Cookie values into one header. */
+export declare function normalizeAuthResponseCookies(response: Response): Promise<Response>;

package/dist/auth/routes.js

@@ -0,0 +1,80 @@
+import { ContractError } from "../kernel/contracts.js";
+import { checkOrigin, surfaceFailure } from "../kernel/surface-failure.js";
+import { draining } from "../kernel/drain.js";
+import { guardAuthAdminRequest } from "./admin.js";
+import { CONSENT, MAX_BODY, json, readBody, text } from "./route-http.js";
+import { resolveCaller } from "./caller.js";
+const basePathOf = (options) => (options.basePath ?? "/api/auth").replace(/\/+$/, "");
+const WELL_KNOWN = /^\/\.well-known\/(oauth-authorization-server|oauth-protected-resource)(\/|$)/;
+export function authRoutes(loader, options) {
+    const base = basePathOf(options);
+    if (options.connectedAppsPage && (!options.connectedAppsPage.startsWith("/") || options.connectedAppsPage.startsWith("//") || /[\\\r\n]/.test(options.connectedAppsPage)))
+        throw new Error("connectedAppsPage must be a same-origin absolute path.");
+    const resolve = options.resolver ?? ((request) => resolveCaller(request, loader));
+    return draining(async (request) => {
+        const { pathname } = new URL(request.url);
+        const route = `${request.method} ${pathname}`;
+        if (pathname === `${base}/methods` && request.method === "GET")
+            return json({ methods: options.methods });
+        if (pathname.startsWith(`${base}/`) || WELL_KNOWN.test(pathname)) {
+            const auth = await loader.get();
+            if (basePathOf(auth.options) !== base)
+                throw new Error("authRoutes basePath differs from betterAuth options.");
+            try {
+                const bounded = request.body ? new Request(request, { body: await readBody(request) }) : request;
+                await guardAuthAdminRequest(bounded, () => resolve(bounded), base);
+                const registration = bounded.method === "POST" && pathname === `${base}/oauth2/register` ? await loopbackClientsAreNative(bounded) : bounded;
+                return await normalizeAuthResponseCookies(await auth.handler(registration));
+            }
+            catch (error) {
+                return surfaceFailure(error, undefined, `auth ${route}`);
+            }
+        }
+        if (!CONSENT.has(route))
+            return null;
+        try {
+            const caller = await resolve(request);
+            checkOrigin(request, caller);
+            if (request.method === "POST" && Number(request.headers.get("content-length")) > MAX_BODY)
+                return text("request body too large", 413);
+            const [{ oauthConsents }, { consentSurface }] = await Promise.all([import("./oauth.js"), import("./consent.js")]);
+            return await consentSurface(oauthConsents(await loader.get()), options)(request, caller, route);
+        }
+        catch (error) {
+            return surfaceFailure(error, undefined, `auth ${route}`);
+        }
+    });
+}
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+export async function loopbackClientsAreNative(request) {
+    const body = await readBody(request.clone()).then(JSON.parse).catch(error => { if (error instanceof ContractError)
+        throw error; return null; });
+    const uris = body?.redirect_uris;
+    if (!body || typeof body !== "object" || Array.isArray(body) || body.application_type !== undefined || !Array.isArray(uris) || !uris.length)
+        return request;
+    const loopback = uris.every((uri) => {
+        if (typeof uri !== "string" || !URL.canParse(uri))
+            return false;
+        const url = new URL(uri);
+        return url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+    });
+    if (!loopback)
+        return request;
+    const headers = new Headers(request.headers);
+    headers.delete("content-length");
+    return new Request(request.url, { method: "POST", headers, body: JSON.stringify({ ...body, application_type: "native" }) });
+}
+export async function normalizeAuthResponseCookies(response) {
+    if (!response.headers.has("set-cookie"))
+        return response;
+    const { splitSetCookieHeader } = await import("better-auth/cookies");
+    const values = response.headers.getSetCookie?.() ?? [response.headers.get("set-cookie")];
+    const cookies = values.flatMap(splitSetCookieHeader);
+    if (cookies.length < 2)
+        return response;
+    const headers = new Headers(response.headers);
+    headers.delete("set-cookie");
+    for (const cookie of cookies)
+        headers.append("set-cookie", cookie);
+    return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+}