@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.10

package/dist/auth/identity.d.ts

@@ -0,0 +1,121 @@
+/** Optional identity operations. Better Auth owns access control, writes and user hooks. */
+import { type AuthInstance } from "./caller.js";
+import { type Caller, type Postgres, type Unsafe } from "../kernel/contracts.js";
+import type { Dialect } from "../kernel/dialect/common.js";
+import { type Reader } from "../kernel/driver/d1.js";
+type User = {
+    id: string;
+    email: string;
+    name: string;
+    role?: string | null;
+    githubLogin?: string | null;
+    emailVerified: boolean | number;
+    createdAt: string | Date;
+};
+type Api = {
+    listUsers(input: {
+        headers: Headers;
+        query: Record<string, unknown>;
+    }): Promise<{
+        users: User[];
+        total: number;
+    }>;
+    setRole(input: {
+        headers: Headers;
+        body: {
+            userId: string;
+            role: never;
+        };
+    }): Promise<unknown>;
+    createUser(input: {
+        headers: Headers;
+        body: {
+            email: string;
+            name: string;
+            role: never;
+        };
+    }): Promise<{
+        user: User;
+    }>;
+    removeUser(input: {
+        headers: Headers;
+        body: {
+            userId: string;
+        };
+    }): Promise<unknown>;
+    userHasPermission(input: {
+        headers: Headers;
+        body: {
+            permissions: {
+                user: ("list" | "delete")[];
+            };
+        };
+    }): Promise<{
+        success: boolean;
+    }>;
+};
+/** Requires Better Auth's official admin plugin. Every API receives the request's headers. */
+export interface IdentityAuth extends AuthInstance {
+    readonly api: AuthInstance["api"] & Api;
+}
+type Read = (sql: string, values: unknown[]) => PromiseLike<any[]>;
+type Member = {
+    id: string;
+    email: string;
+    name: string;
+    role: string | null;
+    githubLogin: string | null;
+    emailVerified: boolean;
+    createdAt: Date;
+};
+declare function directory(auth: IdentityAuth, _caller: Caller, headers: Headers, d: Dialect, read: Read): {
+    adminRoles: string[];
+    listUsers(): Promise<Member[]>;
+    listMembers({ search, limit, cursor, cursorDirection }?: {
+        search?: string;
+        limit?: number;
+        cursor?: string;
+        cursorDirection?: "forward" | "backward";
+    }): Promise<{
+        items: Member[];
+        previousCursor: string | null;
+        nextCursor: string | null;
+    }>;
+    setUserRole(id: string, role: string | readonly string[] | null): Promise<boolean>;
+    inviteUser(email: string, role?: string): Promise<{
+        kind: "created";
+        id: string;
+    } | {
+        kind: "exists";
+        id: string;
+    }>;
+    revokeInvite(id: string): Promise<boolean>;
+    deleteUser: (id: string) => Promise<boolean>;
+};
+export type IdentityDirectory = ReturnType<typeof directory>;
+export declare const d1Identity: (db: Reader, auth: IdentityAuth, caller: Caller, headers: Headers) => IdentityDirectory;
+export declare const postgresIdentity: (db: Unsafe, auth: IdentityAuth, caller: Caller, headers: Headers) => IdentityDirectory;
+/**
+ * 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 declare function readIdentity(auth: AuthInstance): {
+    /** The active user with this id, or null. */
+    user: (id: string) => Promise<Member | null>;
+    /** 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: () => Promise<Member[]>;
+};
+export type BootstrapRule = {
+    match: "email" | "github-login";
+    value: string;
+};
+type BootstrapUser = {
+    id: string;
+    email?: string | null;
+    githubLogin?: string | null;
+    emailVerified?: boolean;
+};
+type BootstrapAuth = Pick<AuthInstance, "options"> | (() => Pick<AuthInstance, "options">);
+export declare function d1BootstrapAdmin(db: Reader, rule: BootstrapRule, auth: BootstrapAuth): (user: BootstrapUser) => Promise<void>;
+export declare function postgresBootstrapAdmin(db: Postgres, rule: BootstrapRule, source: BootstrapAuth): (user: BootstrapUser) => Promise<void>;
+export {};

package/dist/auth/identity.js

@@ -0,0 +1,203 @@
+/** 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";
+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 ') + ')';
+};
+/** Translate Better Auth errors at the selected transport boundary, retaining its status and code. */
+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);
+            // 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;
+        }
+        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));
+/**
+ * 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();
+            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}`;
+};
+/** 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.");
+    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,217 @@
+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;
+    }
+};
+/**
+ * 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);
+    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 };
+}
+/** 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())
+                    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";
+/** 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)
+                            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
+                                    // 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);
+                    }) }],
+        },
+    };
+}
+/** 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;
+    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;
+    }
+}
+/** 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;;) {
+        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;
+    }
+}
+/** A verification value that is an authorization code, with its user and client; else undefined. */
+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;
+}
+/** 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 {
+        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;
+        },
+    };
+}
+/** 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: [
+            { 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,10 @@
+/** 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 ?? []);
+    if (!seeds.has(options))
+        seeds.set(options, [...inputs]);
+    options.resources = [];
+    return inputs;
+}