@protobase/server 0.33.4 → 0.34.0

package/dist/better-auth/create-auth.js

@@ -3,7 +3,6 @@ import { appNameOver, defaultAppName } from "../app-name.js";
 import { goTrueIssuer, goTrueKeyPair } from "../gotrue/keys.js";
 import { defaultSignInPolicy } from "./sign-in-policy.js";
 import { roleDefinitions } from "./organizations/role-definitions.js";
-import { narrowClaims } from "./roles/active-role.js";
 import { signInPolicyPlugin } from "./policy-plugin.js";
 import { goTrueSessionsPlugin } from "../gotrue/sessions-plugin.js";
 import { authBasePath } from "./auth-base-path.js";
@@ -11,12 +10,15 @@ import { platformMailer } from "../mail/platform-mailer.js";
 import { readOperatorSettings, resolveOperator } from "./operator-provider.js";
 import { defaultInvitationUrl } from "./invitations/invitation-link-hook.js";
 import { lastAdminGuardPlugin } from "./last-admin-guard.js";
-import { lastOrganizationField, organizationClaims, sessionOrganizationHooks } from "./organizations/session-organization.js";
+import { revokeMcpGrants } from "./mcp/revoke-grants.js";
+import { coreNames, pluginNames } from "./snake-case-names.js";
+import { lastOrganizationField, sessionOrganizationHooks } from "./organizations/session-organization.js";
+import { tokenClaims } from "./token-claims.js";
+import { mcpAuthPlugins, mcpUnusedPaths, resolveMcp } from "./mcp/mcp-plugins.js";
 import { organizationPlugin } from "./organizations/organization-plugin.js";
 import { protobaseOrganizationPlugin } from "./organizations/protobase-plugin.js";
 import { resolveOrganizations } from "./organizations/options.js";
 import { passkeyHosts, readPasskeyDomain, resolvePasskeyDomain } from "./passkey-domain.js";
-import { coreNames, pluginNames } from "./snake-case-names.js";
 import { passkeyPlugin } from "./passkey-plugin.js";
 import { passwordResetOptions } from "./password-reset.js";
 import { rolesPlugin } from "./roles/roles-plugin.js";
@@ -57,7 +59,7 @@ const organizationPaths = ["/organization/set-active", "/organization/accept-inv
 * The options `createAuth` gives Better Auth, with the roles, default role, mailer, operator provider and platform
 * sign-in provider already resolved.
 */
-const betterAuthOptions = (options, { origins = [], passkeyDomain, roles, definitions, defaultRole, appName = defaultAppName, mailer, signUpRole, operator, platformSignIn, saml = [], organizations, context = noContext, signInPolicy = defaultSignInPolicy }) => {
+const betterAuthOptions = (options, { origins = [], passkeyDomain, roles, definitions, defaultRole, appName = defaultAppName, mailer, signUpRole, operator, platformSignIn, saml = [], organizations, mcp, context = noContext, signInPolicy = defaultSignInPolicy }) => {
 	const secure = options.baseURL.startsWith("https://");
 	const signIn = platformSignInFor(platformSignIn, Object.keys(options.socialProviders ?? {}));
 	const hosts = passkeyHosts([options.baseURL, ...origins]);
@@ -88,14 +90,14 @@ const betterAuthOptions = (options, { origins = [], passkeyDomain, roles, defini
 			audience: options.baseURL,
 			definePayload: async ({ user, session }) => {
 				const { activeRole, activeOrganizationId } = session;
-				const claims = {
-					role: user.role,
-					...organizations && await organizationClaims((await context()).adapter, user, activeOrganizationId)
-				};
+				const wanted = [activeRole, user.lastRole];
 				return {
-					email: user.email,
-					sid: session.id,
-					...narrowClaims(claims, [activeRole, user.lastRole], Boolean(organizations))
+					...await tokenClaims(user, {
+						wanted,
+						organizationId: activeOrganizationId,
+						...organizations && { organizations: (await context()).adapter }
+					}),
+					sid: session.id
 				};
 			}
 		},
@@ -122,7 +124,7 @@ const betterAuthOptions = (options, { origins = [], passkeyDomain, roles, defini
 			disableSignUp: true,
 			minPasswordLength: 12,
 			...passwordHashes.length > 0 && { password: { verify: verifyAcceptedHash(passwordHashes) } },
-			...mail && passwordResetOptions(mail)
+			...mail && passwordResetOptions(mail, mcp ? { onPasswordReset: async ({ user }) => revokeMcpGrants((await context()).adapter, user.id) } : {})
 		},
 		...options.socialProviders && { socialProviders: options.socialProviders },
 		user: Object.keys(userFields).length > 0 ? {
@@ -192,13 +194,22 @@ const betterAuthOptions = (options, { origins = [], passkeyDomain, roles, defini
 				invitationSeconds: organizations?.invitationExpiresIn ?? 604800,
 				...organizations && { organizations }
 			}),
-			...passwordHashes.length > 0 ? [rehashPasswordsPlugin(passwordHashes)] : []
+			...passwordHashes.length > 0 ? [rehashPasswordsPlugin(passwordHashes)] : [],
+			...mcp ? mcpAuthPlugins({
+				mcp,
+				organizations: Boolean(organizations),
+				mail: Boolean(mailer),
+				defaultPolicy: signInPolicy,
+				definitions,
+				context
+			}) : []
 		].map((plugin) => withUserColumns(plugin, users)),
 		disabledPaths: [
 			...unusedEmailCodePaths,
 			...adminImpersonationPaths,
 			...organizations ? organizationPaths : [],
-			...saml.length > 0 ? samlDisabledPaths : []
+			...saml.length > 0 ? samlDisabledPaths : [],
+			...mcp ? mcpUnusedPaths : []
 		],
 		databaseHooks: {
 			user: {
@@ -294,6 +305,7 @@ const createAuth = (options) => {
 	const origins = resolveOrigins(options.baseURL, options.origins ?? platformOrigins());
 	const passkeyDomain = resolvePasskeyDomain(options.passkeyDomain ?? platformPasskeyDomain(), [options.baseURL, ...origins]);
 	const organizations = options.organizations && resolveOrganizations(options.organizations, definitions, options.baseURL);
+	const mcp = options.mcp && resolveMcp(options.baseURL, options.mcp);
 	let instance;
 	const context = () => instance?.$context ?? Promise.reject(/* @__PURE__ */ new Error("The auth instance is not made yet"));
 	const auth = betterAuth(betterAuthOptions(options, {
@@ -309,10 +321,9 @@ const createAuth = (options) => {
 		platformSignIn,
 		saml,
 		signInPolicy,
-		...organizations && {
-			organizations,
-			context
-		}
+		...organizations && { organizations },
+		...mcp && { mcp },
+		...(organizations || mcp) && { context }
 	}));
 	instance = auth;
 	return Object.assign(auth, {
@@ -350,7 +361,13 @@ const createAuth = (options) => {
 		samlProviders: saml.map(({ id, name }) => ({
 			id,
 			name
-		}))
+		})),
+		/** The OAuth provider for MCP clients, when on: the endpoint's resource (its URL) and path, and the scope its tokens carry. */
+		mcp: mcp && {
+			resource: mcp.resource,
+			path: mcp.path,
+			scope: "mcp"
+		}
 	});
 };
 //#endregion

package/dist/better-auth/mcp/connected-apps.d.ts

@@ -0,0 +1,13 @@
+import "zod";
+//#region src/better-auth/mcp/connected-apps.d.ts
+/** An app the person allowed: the client, the name it gave itself, when they last allowed it, and as what. */
+export type ConnectedApp = {
+  clientId: string;
+  name?: string;
+  allowedAt: string;
+  access: {
+    role: string;
+    organization?: string;
+  }[];
+};
+//#endregion

package/dist/better-auth/mcp/connected-apps.js

@@ -0,0 +1,86 @@
+import { everyRow } from "../organizations/store.js";
+import { consentModel } from "./consent-check.js";
+import { revokeMcpGrants } from "./revoke-grants.js";
+import { readGrantReference } from "./grant-reference.js";
+import * as z$1 from "zod";
+import { createAuthEndpoint, sessionMiddleware } from "better-auth/api";
+//#region src/better-auth/mcp/connected-apps.ts
+const allowedAt = (consent) => new Date(consent.updatedAt ?? consent.createdAt);
+/**
+* The person's consents as the apps they allowed, newest first: one entry per client, with the role (as its label)
+* and organization (as its name) of each consent it holds. A consent whose client is gone is left out.
+*/
+const connectedApps = (consents, clients, { roleLabel, organizationName }) => {
+	const byClient = /* @__PURE__ */ new Map();
+	for (const consent of consents) byClient.set(consent.clientId, [...byClient.get(consent.clientId) ?? [], consent]);
+	return clients.filter((client) => byClient.has(client.clientId)).map((client) => {
+		const own = byClient.get(client.clientId).toSorted((a, b) => allowedAt(b).getTime() - allowedAt(a).getTime());
+		const access = own.map((consent) => readGrantReference(consent.referenceId)).map(({ role, organization }) => ({
+			role: role ? roleLabel(role) : "",
+			...organization && { organization: organizationName(organization) }
+		}));
+		return {
+			clientId: client.clientId,
+			...client.name && { name: client.name },
+			allowedAt: allowedAt(own[0]).toISOString(),
+			access
+		};
+	}).toSorted((a, b) => b.allowedAt.localeCompare(a.allowedAt));
+};
+const idsIn = (field, values) => [{
+	field,
+	value: values,
+	operator: "in"
+}];
+/**
+* `GET /account/connected-apps`: the apps the signed-in person allowed to act as them (`connectedApps`).
+* `POST /account/connected-apps/disconnect { clientId }`: disconnects one, forgetting its consents and revoking its
+* tokens (`revokeMcpGrants`); one with nothing left is no error. Both act on the session's own person only.
+*/
+const mcpConnectedApps = ({ definitions }) => ({
+	id: "protobase-mcp-connected-apps",
+	endpoints: {
+		listConnectedApps: createAuthEndpoint("/account/connected-apps", {
+			method: "GET",
+			use: [sessionMiddleware]
+		}, async (ctx) => {
+			const { adapter } = ctx.context;
+			const consents = await adapter.findMany({
+				model: consentModel,
+				where: [{
+					field: "userId",
+					value: ctx.context.session.user.id
+				}],
+				limit: everyRow
+			});
+			const clientIds = [...new Set(consents.map((consent) => consent.clientId))];
+			const clients = clientIds.length === 0 ? [] : await adapter.findMany({
+				model: "oauthClient",
+				where: idsIn("clientId", clientIds),
+				limit: everyRow
+			});
+			const organizationIds = [...new Set(consents.map((consent) => readGrantReference(consent.referenceId).organization).filter((id) => id !== void 0))];
+			const organizations = organizationIds.length === 0 ? [] : await adapter.findMany({
+				model: "organization",
+				where: idsIn("id", organizationIds),
+				limit: everyRow
+			});
+			const names = new Map(organizations.map((organization) => [organization.id, organization.name]));
+			const apps = connectedApps(consents, clients, {
+				roleLabel: (role) => definitions.labels[role] ?? role,
+				organizationName: (id) => names.get(id) ?? id
+			});
+			return ctx.json({ apps });
+		}),
+		disconnectApp: createAuthEndpoint("/account/connected-apps/disconnect", {
+			method: "POST",
+			use: [sessionMiddleware],
+			body: z$1.object({ clientId: z$1.string().min(1) })
+		}, async (ctx) => {
+			await revokeMcpGrants(ctx.context.adapter, ctx.context.session.user.id, ctx.body.clientId);
+			return ctx.json({ disconnected: true });
+		})
+	}
+});
+//#endregion
+export { connectedApps, mcpConnectedApps };

package/dist/better-auth/mcp/consent-check.js

@@ -0,0 +1,38 @@
+import { APIError } from "better-auth/api";
+//#region src/better-auth/mcp/consent-check.ts
+/** Better Auth's model of the consents the OAuth provider stores, one per client, user and grant. */
+const consentModel = "oauthConsent";
+const disconnected = () => new APIError("BAD_REQUEST", {
+	error: "invalid_grant",
+	error_description: "You disconnected this client: connect it again."
+});
+/**
+* A provider extension that makes the consent the one source of truth for issuing tokens: every MCP access token, at
+* the code exchange and at each refresh, needs the consent of its client, user and grant (`referenceId`) to still
+* exist. Disconnecting a client deletes its consents, so a code issued just before, or a refresh token left over,
+* gets `invalid_grant`. It runs before the provider writes a new refresh token.
+*/
+const mcpConsentCheck = () => ({ claims: { accessToken: async ({ ctx, client, user, referenceId }) => {
+	if (!user || !referenceId) throw disconnected();
+	const where = [
+		{
+			field: "clientId",
+			value: client.clientId
+		},
+		{
+			field: "userId",
+			value: user.id
+		},
+		{
+			field: "referenceId",
+			value: referenceId
+		}
+	];
+	if (!await ctx.context.adapter.findOne({
+		model: "oauthConsent",
+		where
+	})) throw disconnected();
+	return {};
+} } });
+//#endregion
+export { consentModel, mcpConsentCheck };

package/dist/better-auth/mcp/consent-reference.js

@@ -0,0 +1,16 @@
+import { sessionRoles } from "../roles/session-role.js";
+import { grantReference } from "./grant-reference.js";
+//#region src/better-auth/mcp/consent-reference.ts
+/**
+* The `referenceId` of a consent given from `session`: the role the session acts with, as its next token would carry
+* it, and its active organization. The session's own `activeRole` is not enough: one that never switched role has none.
+*/
+const consentReference = async (context, { user, session }) => grantReference({
+	role: (await sessionRoles(context, {
+		user,
+		session
+	})).active,
+	organization: session.activeOrganizationId ?? void 0
+});
+//#endregion
+export { consentReference };

package/dist/better-auth/mcp/discovery-routes.js

@@ -0,0 +1,19 @@
+import { oauthWellKnownPaths } from "../origins.js";
+import { authBasePath } from "../auth-base-path.js";
+import { cors } from "hono/cors";
+//#region src/better-auth/mcp/discovery-routes.ts
+const openPaths = [
+	...oauthWellKnownPaths.flatMap((path) => [path, `${path}/*`]),
+	`${authBasePath}/oauth2/register`,
+	`${authBasePath}/oauth2/token`
+];
+/**
+* Routes MCP clients find the app's OAuth provider by: the two discovery documents, which Better Auth answers outside
+* its base path, and open CORS on them and on registration and the token endpoint, before the auth route answers.
+*/
+const mcpDiscovery = (app, auth) => {
+	for (const path of openPaths) app.use(path, cors({ origin: "*" }));
+	for (const path of oauthWellKnownPaths) app.get(path, (c) => auth.handler(c.req.raw)).get(`${path}/*`, (c) => auth.handler(c.req.raw));
+};
+//#endregion
+export { mcpDiscovery };

package/dist/better-auth/mcp/grant-reference.js

@@ -0,0 +1,25 @@
+//#region src/better-auth/mcp/grant-reference.ts
+/**
+* The grant written as a consent's `referenceId`: the same text for the same grant, so a consent made with one role
+* is not found for another, and the person is asked again.
+*/
+const grantReference = ({ role, organization }) => {
+	const entries = Object.entries({
+		organization,
+		role
+	}).filter((entry) => typeof entry[1] === "string" && entry[1] !== "");
+	return new URLSearchParams(entries.sort(([a], [b]) => a.localeCompare(b))).toString();
+};
+/** The grant a `referenceId` holds; none for a missing or empty one. */
+const readGrantReference = (reference) => {
+	if (!reference) return {};
+	const params = new URLSearchParams(reference);
+	const role = params.get("role");
+	const organization = params.get("organization");
+	return {
+		...role && { role },
+		...organization && { organization }
+	};
+};
+//#endregion
+export { grantReference, readGrantReference };

package/dist/better-auth/mcp/mcp-plugins.d.ts

@@ -0,0 +1,13 @@
+import "./connected-apps.js";
+import "../organizations/store.js";
+import { ClientMetadataResourceFetch } from "@better-auth/oauth-provider";
+//#region src/better-auth/mcp/mcp-plugins.d.ts
+export type McpAuthOptions = {
+  /** The path of the MCP endpoint on the app's origin, its OAuth resource; default `/api/mcp`. Changing it makes clients connect again. */
+  path?: string;
+  /** The connect page's path on the app's origin, where people sign in and allow a client; default `/-/connect`, for a UI at the root. */
+  connectPage?: string;
+  /** Fetches a client's metadata document (a URL client id); default the CIMD plugin's Node transport, which refuses non-public addresses. */
+  fetchClientMetadata?: ClientMetadataResourceFetch;
+};
+//#endregion

package/dist/better-auth/mcp/mcp-plugins.js

@@ -0,0 +1,107 @@
+import { mcpConsentCheck } from "./consent-check.js";
+import { mcpGrantRevocation } from "./revoke-grants.js";
+import { pluginNames } from "../snake-case-names.js";
+import { mcpConnectedApps } from "./connected-apps.js";
+import { consentReference } from "./consent-reference.js";
+import { mcpTokenClaims } from "./mcp-token-claims.js";
+import { mcpRequestDefaults } from "./request-defaults.js";
+import { mcpSetupGate } from "./setup-gate.js";
+import { mcpSignedQueryGuard } from "./signed-query-guard.js";
+import { connectRoute } from "@protobase/schema";
+import { cimd } from "@better-auth/cimd";
+import { fetchClientMetadataResource } from "@better-auth/cimd/node";
+import { mcp } from "@better-auth/mcp";
+//#region src/better-auth/mcp/mcp-plugins.ts
+/** The path of the app's MCP endpoint, below its origin, unless `mcp.path` names another. */
+const defaultMcpPath = "/api/mcp";
+/** The OAuth resource of the MCP endpoint: the origin of `baseURL` with `path`. */
+const mcpResource = (baseURL, path) => `${new URL(baseURL).origin}${path}`;
+/**
+* The MCP options with their defaults, for an app at `baseURL`. The path must be one below the origin, so the
+* resource is never the issuer, in either of its forms, whose tokens the app's own API takes.
+*/
+const resolveMcp = (baseURL, options) => {
+	const { path = defaultMcpPath, connectPage = connectRoute, fetchClientMetadata = fetchClientMetadataResource } = options === true ? {} : options;
+	if (!path.startsWith("/") || path.length < 2) throw new Error(`mcp.path "${path}" must be a path below the app's origin, such as ${defaultMcpPath}`);
+	if (!connectPage.startsWith("/")) throw new Error(`mcp.connectPage "${connectPage}" must be a path on the app's origin, such as ${connectRoute}`);
+	return {
+		path,
+		connectPage,
+		resource: mcpResource(baseURL, path),
+		fetchClientMetadata
+	};
+};
+/**
+* The OAuth provider's endpoints MCP does not use, closed: managing clients (dynamic registration and client metadata
+* documents are the only ways in), OpenID Connect's userinfo and logout, and the provider's own consent endpoints,
+* whose `delete-consent` would leave the client's tokens working; the account page lists and disconnects clients.
+*/
+const mcpUnusedPaths = [
+	"/oauth2/create-client",
+	"/oauth2/get-client",
+	"/oauth2/get-clients",
+	"/oauth2/update-client",
+	"/oauth2/delete-client",
+	"/oauth2/client/rotate-secret",
+	"/oauth2/client/rotate-keys",
+	"/oauth2/public-client-prelogin",
+	"/oauth2/userinfo",
+	"/oauth2/end-session",
+	"/oauth2/end-session/confirm",
+	"/oauth2/get-consent",
+	"/oauth2/get-consents",
+	"/oauth2/update-consent",
+	"/oauth2/delete-consent"
+];
+/**
+* The Better Auth plugins of an OAuth provider for MCP clients, after the `jwt` plugin, in this order: the guard on
+* signed queries, the request defaults, the setup gate, the provider (`mcp()`), and client metadata documents
+* (`cimd()`), the revocation when the account is secured (`mcpGrantRevocation`), and the person's list of connected
+* apps, where they disconnect one (`mcpConnectedApps`). A client registers itself, the person signs in on the app's own pages and allows it on the connect
+* page, and the client gets 15-minute access tokens for the MCP resource only, with refresh tokens, carrying the role
+* and organization the person worked in when they allowed it.
+*/
+const mcpAuthPlugins = ({ mcp: resolved, organizations, mail, defaultPolicy, definitions, context }) => [
+	mcpSignedQueryGuard(),
+	mcpRequestDefaults(resolved.resource),
+	mcpSetupGate({
+		mail,
+		defaultPolicy,
+		connectPage: resolved.connectPage
+	}),
+	mcp({
+		resource: resolved.resource,
+		loginPage: resolved.connectPage,
+		consentPage: resolved.connectPage,
+		scopes: ["mcp", "offline_access"],
+		clientRegistrationDefaultScopes: ["mcp", "offline_access"],
+		grantTypes: ["authorization_code", "refresh_token"],
+		allowDynamicClientRegistration: true,
+		allowUnauthenticatedClientRegistration: true,
+		clientRegistrationDefaultApplicationType: "infer",
+		postLogin: {
+			page: resolved.connectPage,
+			shouldRedirect: () => false,
+			consentReferenceId: async ({ user, session }) => consentReference(await context(), {
+				user,
+				session
+			})
+		},
+		customAccessTokenClaims: async ({ user, referenceId }) => mcpTokenClaims(await context(), {
+			organizations,
+			mail,
+			defaultPolicy
+		}, user, referenceId),
+		accessTokenExpiresIn: 900,
+		extensions: [mcpConsentCheck()],
+		schema: pluginNames.mcp
+	}),
+	cimd({
+		fetchClientMetadataResource: resolved.fetchClientMetadata,
+		metadataProfile: "mcp-2026-07-28"
+	}),
+	mcpGrantRevocation(),
+	mcpConnectedApps({ definitions })
+];
+//#endregion
+export { defaultMcpPath, mcpAuthPlugins, mcpResource, mcpUnusedPaths, resolveMcp };

package/dist/better-auth/mcp/mcp-token-claims.js

@@ -0,0 +1,39 @@
+import { missingSetup } from "../sign-in-setup.js";
+import { heldRoles } from "../roles/session-role.js";
+import { readGrantReference } from "./grant-reference.js";
+import { mayEnter } from "../organizations/session-organization.js";
+import { tokenClaims } from "../token-claims.js";
+import { APIError } from "better-auth/api";
+//#region src/better-auth/mcp/mcp-token-claims.ts
+const refused = (description) => new APIError("BAD_REQUEST", {
+	error: "invalid_grant",
+	error_description: description
+});
+const isBanned = (user, now) => Boolean(user.banned) && !(user.banExpires && new Date(user.banExpires) < now);
+/**
+* The claims of an MCP access token, issued at the code exchange and at every refresh: the role and organization the
+* grant was made with (its consent's `referenceId`), checked again each time. It refuses (`invalid_grant`) a grant
+* without a user, for a banned user, an address that is not verified, setup the sign-in policy now requires, a grant
+* made with no role, and a role or organization the user no longer holds; so a refresh stops once any of those holds.
+*/
+const mcpTokenClaims = async (context, { organizations, mail, defaultPolicy, now = /* @__PURE__ */ new Date() }, user, referenceId) => {
+	if (!user) throw refused("This grant has no user.");
+	if (isBanned(user, now)) throw refused("This account is blocked.");
+	if (user.emailVerified !== true) throw refused("Confirm your address by signing in with an emailed code, then connect again.");
+	if ((await missingSetup(context, user, {
+		mail,
+		defaultPolicy
+	})).length > 0) throw refused("Set up what this app's sign-in policy requires, then try again.");
+	const { role, organization } = readGrantReference(referenceId);
+	if (!role) throw refused("You had no role in this app when you allowed this client: connect it again.");
+	const held = await heldRoles(context, user, { activeOrganizationId: organization ?? null });
+	const entered = !organizations || !organization || await mayEnter(context.adapter, user, organization);
+	if (!held.includes(role) || !entered) throw refused("Your role or organization changed since you allowed this client: connect it again.");
+	return tokenClaims(user, {
+		wanted: [role],
+		organizationId: organization ?? null,
+		...organizations && { organizations: context.adapter }
+	});
+};
+//#endregion
+export { mcpTokenClaims };

package/dist/better-auth/mcp/request-defaults.js

@@ -0,0 +1,57 @@
+import { APIError, createAuthMiddleware } from "better-auth/api";
+//#region src/better-auth/mcp/request-defaults.ts
+const isParams = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* The authorization parameters with `resource` set to the one this provider protects when none is sent. The provider
+* issues a JWT access token, and so runs the grant's token-time checks (`mcpTokenClaims`, `mcpConsentCheck`), only
+* for a token with an audience; without a resource it would issue an opaque token and a refresh token with no check.
+*/
+const withResource = (params, resource) => params.resource === void 0 ? {
+	...params,
+	resource
+} : params;
+/** `scope` with `offline_access` added, which refresh tokens need; the resource metadata leaves it out of its scopes. */
+const withOfflineAccess = (scope) => {
+	const scopes = scope.split(" ").filter(Boolean);
+	return scopes.includes("offline_access") ? scope : [...scopes, "offline_access"].join(" ");
+};
+const withDefaults = (params, resource) => {
+	const defaulted = withResource(params, resource);
+	return typeof defaulted.scope === "string" ? {
+		...defaulted,
+		scope: withOfflineAccess(defaulted.scope)
+	} : defaulted;
+};
+const refusedRegistrationFields = [
+	"backchannel_logout_uri",
+	"backchannel_logout_session_required",
+	"jwks_uri"
+];
+/** The registration field this server refuses, when `body` has one. */
+const refusedRegistrationField = (body) => isParams(body) ? refusedRegistrationFields.find((field) => body[field] !== void 0) : void 0;
+/**
+* Before hooks that fill in what MCP clients leave out: on `authorize`, the resource and `offline_access` (in the
+* query, or the body of a form POST, wherever the parameters are); on `register`, refusing fields that would make the
+* server call a URL the client chose (`400 invalid_client_metadata`).
+*/
+const mcpRequestDefaults = (resource) => ({
+	id: "protobase-mcp-request-defaults",
+	hooks: { before: [{
+		matcher: (context) => context.path === "/oauth2/authorize",
+		handler: createAuthMiddleware(async (ctx) => {
+			if (isParams(ctx.body) && "client_id" in ctx.body) return { context: { body: withDefaults(ctx.body, resource) } };
+			return { context: { query: withDefaults(isParams(ctx.query) ? ctx.query : {}, resource) } };
+		})
+	}, {
+		matcher: (context) => context.path === "/oauth2/register",
+		handler: createAuthMiddleware(async (ctx) => {
+			const field = refusedRegistrationField(ctx.body);
+			if (field) throw new APIError("BAD_REQUEST", {
+				error: "invalid_client_metadata",
+				error_description: `This server does not take ${field}.`
+			});
+		})
+	}] }
+});
+//#endregion
+export { mcpRequestDefaults, refusedRegistrationField, withOfflineAccess, withResource };

package/dist/better-auth/mcp/revoke-grants.js

@@ -0,0 +1,75 @@
+import { consentModel } from "./consent-check.js";
+import { createAuthMiddleware } from "better-auth/api";
+//#region src/better-auth/mcp/revoke-grants.ts
+/**
+* Disconnects the user's MCP clients, or only `clientId`: deletes their consents, then their access tokens and refresh
+* tokens. Without the consent no code or refresh is exchanged any more (`mcpConsentCheck`), and authorize asks the
+* person again; access tokens already issued work out their 15 minutes. Access tokens go before refresh tokens, as the
+* provider's own revocation does, since an access token's row may name its refresh token.
+*/
+const revokeMcpGrants = async (adapter, userId, clientId) => {
+	const where = [{
+		field: "userId",
+		value: userId
+	}, ...clientId === void 0 ? [] : [{
+		field: "clientId",
+		value: clientId
+	}]];
+	await adapter.deleteMany({
+		model: consentModel,
+		where
+	});
+	await adapter.deleteMany({
+		model: "oauthAccessToken",
+		where
+	});
+	await adapter.deleteMany({
+		model: "oauthRefreshToken",
+		where
+	});
+};
+const ownPaths = ["/revoke-sessions", "/revoke-other-sessions"];
+const adminPaths = [
+	"/admin/revoke-user-sessions",
+	"/admin/ban-user",
+	"/admin/set-user-password"
+];
+const bodyOf = (request) => typeof request.body === "object" && request.body !== null ? request.body : {};
+const securesAccount = (data) => {
+	if (typeof data !== "object" || data === null) return false;
+	const changes = data;
+	return "banned" in changes && changes.banned !== false || "emailVerified" in changes && changes.emailVerified !== true;
+};
+/**
+* The user whose MCP grants a finished request ends, or `undefined`: the person who signed out everywhere, signed out
+* their other devices, or changed their password signing out the other devices; the user an admin ended the sessions
+* of, banned, set the password of, or marked unverified. Nobody when the request failed.
+*/
+const grantOwnerToRevoke = (request) => {
+	const { path, context } = request;
+	if (context.returned instanceof Error || path === void 0) return void 0;
+	const body = bodyOf(request);
+	if (ownPaths.includes(path) || path === "/change-password" && body.revokeOtherSessions === true) return context.session?.user.id;
+	if (adminPaths.includes(path) || path === "/admin/update-user" && securesAccount(body.data)) return body.userId === void 0 ? void 0 : String(body.userId);
+};
+/**
+* Disconnects the user's MCP clients after a request that secures their account (`grantOwnerToRevoke`). A failure to
+* delete is not caught: the request answers 500 after its own work, and can be run again.
+*/
+const mcpGrantRevocation = () => ({
+	id: "protobase-mcp-grant-revocation",
+	hooks: { after: [{
+		matcher: (context) => context.path !== void 0 && [
+			...ownPaths,
+			...adminPaths,
+			"/change-password",
+			"/admin/update-user"
+		].includes(context.path),
+		handler: createAuthMiddleware(async (ctx) => {
+			const userId = grantOwnerToRevoke(ctx);
+			if (userId) await revokeMcpGrants(ctx.context.adapter, userId);
+		})
+	}] }
+});
+//#endregion
+export { grantOwnerToRevoke, mcpGrantRevocation, revokeMcpGrants };

package/dist/better-auth/mcp/setup-gate.js

@@ -0,0 +1,38 @@
+import { addressNotVerified, setupRequired } from "../sign-in-enforcement.js";
+import { missingSetup } from "../sign-in-setup.js";
+import { isStaffSession } from "../staff-checks.js";
+import { APIError, createAuthMiddleware, getSessionFromCtx } from "better-auth/api";
+//#region src/better-auth/mcp/setup-gate.ts
+const gatedPaths = [
+	"/oauth2/authorize",
+	"/oauth2/continue",
+	"/oauth2/consent"
+];
+/**
+* Holds back allowing an MCP client from someone who has not set up what the sign-in policy requires: `authorize`
+* sends them to the connect page, which shows the setup page; `continue` and `consent` answer `403
+* SIGN_IN_SETUP_REQUIRED`. Someone whose address is not verified cannot allow a client either (`403
+* ADDRESS_NOT_VERIFIED`); `authorize` lets them reach the connect page, which says so. Staff sessions are refused by
+* the staff plugin, before this.
+*/
+const mcpSetupGate = ({ mail, defaultPolicy, connectPage }) => ({
+	id: "protobase-mcp-setup-gate",
+	hooks: { before: [{
+		matcher: (context) => context.path !== void 0 && gatedPaths.includes(context.path),
+		handler: createAuthMiddleware(async (ctx) => {
+			const session = await getSessionFromCtx(ctx);
+			if (!session || isStaffSession(session.session)) return;
+			const authorize = ctx.path === "/oauth2/authorize";
+			if ((await missingSetup(ctx.context, session.user, {
+				mail,
+				defaultPolicy
+			})).length > 0) {
+				if (authorize) throw ctx.redirect(connectPage);
+				throw new APIError("FORBIDDEN", setupRequired);
+			}
+			if (session.user.emailVerified !== true && !authorize) throw new APIError("FORBIDDEN", addressNotVerified);
+		})
+	}] }
+});
+//#endregion
+export { mcpSetupGate };