@better-auth/mcp 1.5.0-beta.9 → 1.7.0-beta.6

package/README.md

@@ -0,0 +1,21 @@
+# @better-auth/mcp
+
+Model Context Protocol (MCP) plugin for [Better Auth](https://www.better-auth.com).
+
+`mcp()` turns your Better Auth app into an OAuth 2.1 authorization server for MCP
+clients, built on [`@better-auth/oauth-provider`](https://www.better-auth.com/docs/plugins/oauth-provider).
+It serves the RFC 9728 protected resource metadata so MCP clients can discover it.
+To protect an MCP route, wrap its handler with `requireMcpAuth` (or `mcpHandler`),
+which verifies bearer tokens against the published JWKS.
+
+```ts
+import { betterAuth } from "better-auth";
+import { jwt } from "better-auth/plugins";
+import { mcp } from "@better-auth/mcp";
+
+export const auth = betterAuth({
+  plugins: [jwt(), mcp({ loginPage: "/login", consentPage: "/consent" })],
+});
+```
+
+See the [MCP plugin documentation](https://www.better-auth.com/docs/plugins/mcp).

package/dist/client/adapters.d.mts

@@ -0,0 +1,56 @@
+import { McpResourceClient, McpResourceClientOptions, McpSession } from "./index.mjs";
+
+//#region src/client/adapters.d.ts
+interface HonoContext {
+  req: {
+    header: (name: string) => string | undefined;
+    raw: Request;
+  };
+  set: (key: string, value: unknown) => void;
+  json: (data: unknown, status?: number, headers?: Record<string, string>) => Response;
+  header: (name: string, value: string) => void;
+}
+type HonoNext = () => Promise<void>;
+type HonoMiddleware = (c: HonoContext, next: HonoNext) => Promise<Response | void>;
+interface HonoApp {
+  get: (path: string, handler: (c: HonoContext) => Promise<Response>) => void;
+}
+declare function mcpAuthHono(options: McpResourceClientOptions): {
+  client: McpResourceClient;
+  middleware: HonoMiddleware;
+  discoveryRoutes: (app: HonoApp, serverURL: string) => void;
+};
+declare function mcpAuthOfficial(options: McpResourceClientOptions): {
+  client: McpResourceClient;
+  handler: McpResourceClient["handler"];
+  verifyToken: McpResourceClient["verifyToken"];
+};
+type OAuthMode = "direct" | "proxy";
+interface McpUseUserInfo {
+  userId: string;
+  roles?: string[];
+  permissions?: string[];
+  scopes?: string;
+  clientId?: string;
+  [key: string]: unknown;
+}
+interface OAuthProvider {
+  verifyToken(token: string): Promise<{
+    payload: Record<string, unknown>;
+  }>;
+  getUserInfo(payload: Record<string, unknown>): McpUseUserInfo;
+  getIssuer(): string;
+  getAuthEndpoint(): string;
+  getTokenEndpoint(): string;
+  getScopesSupported(): string[];
+  getGrantTypesSupported(): string[];
+  getMode(): OAuthMode;
+  getRegistrationEndpoint?(): string;
+}
+interface McpUseBetterAuthConfig {
+  authURL: string;
+  getUserInfo?: (payload: Record<string, unknown>) => McpUseUserInfo;
+}
+declare function mcpAuthMcpUse(config: McpUseBetterAuthConfig): OAuthProvider;
+//#endregion
+export { type McpResourceClient, type McpResourceClientOptions, type McpSession, McpUseBetterAuthConfig, mcpAuthHono, mcpAuthMcpUse, mcpAuthOfficial };

package/dist/client/adapters.mjs

@@ -0,0 +1,126 @@
+import { createMcpResourceClient, makeDpopWWWAuthenticate } from "./index.mjs";
+import { DPOP_SIGNING_ALGORITHMS, isDpopBindingError, parseAccessTokenAuthorization } from "better-auth/oauth2";
+//#region src/client/adapters.ts
+const PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource";
+function getProtectedResourceMetadataPath(resource) {
+	const resourceUrl = new URL(resource);
+	if (resourceUrl.origin === "null") return PROTECTED_RESOURCE_METADATA_PATH;
+	return `${PROTECTED_RESOURCE_METADATA_PATH}${resourceUrl.pathname === "/" ? "" : resourceUrl.pathname.replace(/\/$/, "")}`;
+}
+function getProtectedResourceMetadataURL(resource) {
+	const resourceUrl = new URL(resource);
+	if (resourceUrl.origin === "null") throw new Error("MCP resource_metadata requires an origin-based resource URL");
+	return `${resourceUrl.origin}${getProtectedResourceMetadataPath(resource)}${resourceUrl.search}`;
+}
+function mcpAuthHono(options) {
+	const client = createMcpResourceClient(options);
+	const resourceMetadata = getProtectedResourceMetadataURL(options.resource ?? client.authURL);
+	const dpopChallenge = makeDpopWWWAuthenticate(options.dpop?.signingAlgorithms ?? DPOP_SIGNING_ALGORITHMS);
+	const unauthorized = (c, challenge, message) => {
+		c.header("WWW-Authenticate", challenge);
+		return c.json({
+			jsonrpc: "2.0",
+			error: {
+				code: -32e3,
+				message
+			},
+			id: null
+		}, 401);
+	};
+	const middleware = async (c, next) => {
+		const authHeader = c.req.header("Authorization");
+		let session;
+		try {
+			session = await client.verifyRequest(c.req.raw);
+		} catch (error) {
+			if (isDpopBindingError(error)) return unauthorized(c, dpopChallenge, "Invalid or expired token");
+			throw error;
+		}
+		if (!session) return unauthorized(c, parseAccessTokenAuthorization(authHeader)?.scheme === "DPoP" || !!c.req.header("DPoP") ? dpopChallenge : `Bearer resource_metadata="${resourceMetadata}"`, authHeader ? "Invalid or expired token" : "Unauthorized: Authentication required");
+		c.set("mcpSession", session);
+		await next();
+	};
+	const discoveryRoutes = (app, serverURL) => {
+		const discoveryFn = client.discoveryHandler();
+		const protectedResourceFn = client.protectedResourceHandler(serverURL);
+		const protectedResourcePaths = new Set([PROTECTED_RESOURCE_METADATA_PATH, getProtectedResourceMetadataPath(options.resource ?? client.authURL)]);
+		app.get("/.well-known/oauth-authorization-server", async (c) => {
+			const response = await discoveryFn(c.req.raw);
+			const data = await response.json().catch(() => ({ error: "Invalid response from auth server" }));
+			return c.json(data, response.status);
+		});
+		for (const path of protectedResourcePaths) app.get(path, async (c) => {
+			const response = await protectedResourceFn(c.req.raw);
+			const data = await response.json().catch(() => ({ error: "Invalid response from auth server" }));
+			return c.json(data, response.status);
+		});
+	};
+	return {
+		client,
+		middleware,
+		discoveryRoutes
+	};
+}
+function mcpAuthOfficial(options) {
+	const client = createMcpResourceClient(options);
+	return {
+		client,
+		handler: client.handler,
+		verifyToken: client.verifyToken
+	};
+}
+function mcpAuthMcpUse(config) {
+	const authURL = normalizeURL(config.authURL);
+	if (!authURL) throw new Error("Better Auth authURL is required. Pass authURL in config, e.g.: mcpAuthMcpUse({ authURL: 'http://localhost:3000/api/auth' })");
+	const client = createMcpResourceClient({ authURL });
+	return {
+		async verifyToken(token) {
+			const session = await client.verifyToken(token);
+			if (!session) throw new Error("Invalid or expired token");
+			return { payload: session };
+		},
+		getUserInfo(payload) {
+			if (config.getUserInfo) return config.getUserInfo(payload);
+			const scopes = typeof payload.scope === "string" ? payload.scope.split(" ") : [];
+			return {
+				userId: payload.sub,
+				roles: [],
+				permissions: scopes,
+				scopes: payload.scope,
+				clientId: payload.azp ?? payload.client_id
+			};
+		},
+		getIssuer() {
+			return authURL;
+		},
+		getAuthEndpoint() {
+			return `${authURL}/oauth2/authorize`;
+		},
+		getTokenEndpoint() {
+			return `${authURL}/oauth2/token`;
+		},
+		getScopesSupported() {
+			return [
+				"openid",
+				"profile",
+				"email",
+				"offline_access"
+			];
+		},
+		getGrantTypesSupported() {
+			return ["authorization_code", "refresh_token"];
+		},
+		getMode() {
+			return "direct";
+		},
+		getRegistrationEndpoint() {
+			return `${authURL}/oauth2/register`;
+		}
+	};
+}
+function normalizeURL(url) {
+	if (!url || url.trim() === "") return void 0;
+	return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+//#endregion
+export { mcpAuthHono, mcpAuthMcpUse, mcpAuthOfficial };

package/dist/client/index.d.mts

@@ -0,0 +1,52 @@
+import { VerifyAccessTokenRequestOptions } from "better-auth/oauth2";
+import { JWTPayload } from "jose";
+
+//#region src/client/index.d.ts
+interface McpResourceClientOptions {
+  authURL: string;
+  resource?: string;
+  allowedOrigin?: string;
+  fetch?: typeof globalThis.fetch;
+  dpop?: VerifyAccessTokenRequestOptions["dpop"];
+}
+interface McpSession extends JWTPayload {
+  sub?: string;
+  scope?: string;
+  client_id?: string;
+}
+interface NodeLikeRequest {
+  headers: Record<string, string | string[] | undefined> & {
+    get?: (name: string) => string | undefined;
+    authorization?: string;
+    host?: string;
+    "x-forwarded-proto"?: string;
+  };
+  get?: (name: string) => string | undefined;
+  method?: string;
+  originalUrl?: string;
+  protocol?: string;
+  url?: string;
+  mcpSession?: McpSession;
+}
+interface NodeLikeResponse {
+  set?: (name: string, value: string) => void;
+  setHeader?: (name: string, value: string) => void;
+  status?: (code: number) => {
+    json: (body: unknown) => void;
+  };
+  writeHead?: (code: number, headers: Record<string, string>) => void;
+  end?: (body: string) => void;
+}
+interface McpResourceClient {
+  verifyToken: (token: string) => Promise<McpSession | null>;
+  verifyRequest: (req: Request) => Promise<McpSession | null>;
+  handler: (fn: (req: Request, session: McpSession) => Response | Promise<Response>) => (req: Request) => Promise<Response>;
+  discoveryHandler: () => (req: Request) => Promise<Response>;
+  protectedResourceHandler: (serverURL: string) => (req: Request) => Promise<Response>;
+  middleware: () => (req: NodeLikeRequest, res: NodeLikeResponse, next: () => void) => Promise<void>;
+  authURL: string;
+}
+declare function makeDpopWWWAuthenticate(algorithms: readonly string[]): string;
+declare function createMcpResourceClient(options: McpResourceClientOptions): McpResourceClient;
+//#endregion
+export { McpResourceClient, McpResourceClientOptions, McpSession, createMcpResourceClient, makeDpopWWWAuthenticate };

package/dist/client/index.mjs

@@ -0,0 +1,244 @@
+import { DPOP_SIGNING_ALGORITHMS, createInMemoryDpopReplayStore, enforceDpopBinding, getDpopJktFromPayload, isDpopBindingError, parseAccessTokenAuthorization } from "better-auth/oauth2";
+import { createRemoteJWKSet, jwtVerify } from "jose";
+//#region src/client/index.ts
+const PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource";
+function buildCorsHeaders(authURL, allowedOrigin) {
+	let origin;
+	if (allowedOrigin) origin = allowedOrigin;
+	else try {
+		origin = new URL(authURL).origin;
+	} catch {
+		origin = authURL;
+	}
+	return {
+		"Access-Control-Allow-Origin": origin,
+		"Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+		"Access-Control-Allow-Headers": "Content-Type, Authorization, DPoP",
+		"Access-Control-Expose-Headers": "WWW-Authenticate",
+		"Access-Control-Max-Age": "86400"
+	};
+}
+function getProtectedResourceMetadataURL(resource) {
+	const resourceUrl = new URL(resource);
+	if (resourceUrl.origin === "null") throw new Error("MCP resource_metadata requires an origin-based resource URL");
+	const resourcePath = resourceUrl.pathname === "/" ? "" : resourceUrl.pathname.replace(/\/$/, "");
+	return `${resourceUrl.origin}${PROTECTED_RESOURCE_METADATA_PATH}${resourcePath}${resourceUrl.search}`;
+}
+function makeWWWAuthenticate(authURL, resource) {
+	return `Bearer resource_metadata="${getProtectedResourceMetadataURL(resource ?? authURL)}"`;
+}
+function makeDpopWWWAuthenticate(algorithms) {
+	return `DPoP algs="${algorithms.map((alg) => alg.replace(/[\r\n"\\]/g, "")).join(" ")}"`;
+}
+function make401Response(wwwAuth) {
+	return Response.json({
+		jsonrpc: "2.0",
+		error: {
+			code: -32e3,
+			message: "Unauthorized: Authentication required",
+			"www-authenticate": wwwAuth
+		},
+		id: null
+	}, {
+		status: 401,
+		headers: { "WWW-Authenticate": wwwAuth }
+	});
+}
+function send401Node(res, wwwAuth, message) {
+	const body = JSON.stringify({
+		jsonrpc: "2.0",
+		error: {
+			code: -32e3,
+			message
+		},
+		id: null
+	});
+	if (typeof res.set === "function") {
+		res.set("WWW-Authenticate", wwwAuth);
+		res.status?.(401).json(JSON.parse(body));
+	} else if (typeof res.writeHead === "function") {
+		res.writeHead(401, {
+			"Content-Type": "application/json",
+			"WWW-Authenticate": wwwAuth
+		});
+		res.end?.(body);
+	}
+}
+function createMcpResourceClient(options) {
+	const authURL = options.authURL.endsWith("/") ? options.authURL.slice(0, -1) : options.authURL;
+	const fetchFn = options.fetch ?? globalThis.fetch;
+	const corsHeaders = buildCorsHeaders(authURL, options.allowedOrigin);
+	const expectedAudience = options.resource ?? authURL;
+	const dpopReplayStore = options.dpop?.replayStore ?? createInMemoryDpopReplayStore();
+	const dpopSigningAlgorithms = options.dpop?.signingAlgorithms ?? DPOP_SIGNING_ALGORITHMS;
+	const selectChallenge = (authHeader, dpopHeaderPresent) => {
+		return parseAccessTokenAuthorization(authHeader)?.scheme === "DPoP" || dpopHeaderPresent ? makeDpopWWWAuthenticate(dpopSigningAlgorithms) : makeWWWAuthenticate(authURL, options.resource);
+	};
+	let discovery = null;
+	let jwks = null;
+	const loadVerifier = async () => {
+		if (discovery && jwks) return {
+			discovery,
+			jwks
+		};
+		const response = await fetchFn(`${authURL}/.well-known/oauth-authorization-server`);
+		if (!response.ok) throw new Error("Failed to fetch discovery metadata");
+		const metadata = await response.json();
+		if (!metadata.jwks_uri || !metadata.issuer) throw new Error("Discovery metadata missing jwks_uri or issuer");
+		discovery = {
+			issuer: metadata.issuer,
+			jwks_uri: metadata.jwks_uri
+		};
+		jwks = createRemoteJWKSet(new URL(metadata.jwks_uri));
+		return {
+			discovery,
+			jwks
+		};
+	};
+	const verifyJwtToken = async (token) => {
+		try {
+			const { discovery: meta, jwks: keySet } = await loadVerifier();
+			const { payload } = await jwtVerify(token, keySet, {
+				issuer: meta.issuer,
+				audience: expectedAudience
+			});
+			return payload;
+		} catch {
+			return null;
+		}
+	};
+	const verifyToken = async (token) => {
+		const session = await verifyJwtToken(token);
+		if (!session || getDpopJktFromPayload(session)) return null;
+		return session;
+	};
+	/**
+	* Verifies a request's access token and, when the token is DPoP-bound, its
+	* RFC 9449 sender-constraint. Returns `null` when there is no usable token
+	* or the JWT itself is invalid. Throws a `DpopBindingError` when a
+	* DPoP-bound token fails the binding check, so the caller can answer with a
+	* `WWW-Authenticate: DPoP` challenge rather than a bearer one.
+	*/
+	const verifyRequest = async (req) => {
+		const authorization = parseAccessTokenAuthorization(req.headers.get("Authorization"));
+		if (!authorization?.token || authorization.scheme === "Unknown") return null;
+		const session = await verifyJwtToken(authorization.token);
+		if (!session) return null;
+		await enforceDpopBinding({
+			payload: session,
+			authorization,
+			proofJwt: req.headers.get("DPoP"),
+			method: req.method,
+			url: req.url,
+			proofMaxAgeSeconds: options.dpop?.proofMaxAgeSeconds,
+			signingAlgorithms: dpopSigningAlgorithms,
+			replayStore: dpopReplayStore
+		});
+		return session;
+	};
+	const getHeader = (req, name) => {
+		const lower = name.toLowerCase();
+		const value = req.headers?.[lower] ?? req.headers?.[name] ?? req.headers?.get?.(name) ?? req.get?.(name);
+		if (Array.isArray(value)) return value[0];
+		return value;
+	};
+	const getNodeRequestUrl = (req) => {
+		const rawUrl = req.originalUrl ?? req.url ?? "/";
+		if (URL.canParse(rawUrl)) return rawUrl;
+		const fallbackUrl = new URL(authURL);
+		const host = getHeader(req, "host") ?? fallbackUrl.host;
+		return `${getHeader(req, "x-forwarded-proto")?.split(",")[0]?.trim() ?? req.protocol ?? fallbackUrl.protocol.replace(":", "")}://${host}${rawUrl.startsWith("/") ? rawUrl : `/${rawUrl}`}`;
+	};
+	const handler = (fn) => {
+		return async (req) => {
+			if (req.method === "OPTIONS") return new Response(null, {
+				status: 204,
+				headers: corsHeaders
+			});
+			let session;
+			try {
+				session = await verifyRequest(req);
+			} catch (error) {
+				if (isDpopBindingError(error)) return make401Response(makeDpopWWWAuthenticate(dpopSigningAlgorithms));
+				throw error;
+			}
+			if (!session) return make401Response(selectChallenge(req.headers.get("Authorization"), req.headers.has("DPoP")));
+			return fn(req, session);
+		};
+	};
+	const discoveryHandler = () => {
+		let cachedMetadata = null;
+		let cacheTime = 0;
+		const CACHE_TTL = 6e4;
+		return async (_req) => {
+			const now = Date.now();
+			if (cachedMetadata && now - cacheTime < CACHE_TTL) return Response.json(cachedMetadata, { headers: corsHeaders });
+			try {
+				const response = await fetchFn(`${authURL}/.well-known/oauth-authorization-server`);
+				if (!response.ok) return Response.json({ error: "Failed to fetch discovery metadata" }, {
+					status: 502,
+					headers: corsHeaders
+				});
+				cachedMetadata = await response.json();
+				cacheTime = now;
+				return Response.json(cachedMetadata, { headers: corsHeaders });
+			} catch {
+				return Response.json({ error: "Better Auth server unreachable" }, {
+					status: 502,
+					headers: corsHeaders
+				});
+			}
+		};
+	};
+	const protectedResourceHandler = (serverURL) => {
+		const metadata = {
+			resource: options.resource ?? new URL(serverURL).origin,
+			authorization_servers: [authURL],
+			bearer_methods_supported: ["header"],
+			dpop_signing_alg_values_supported: [...dpopSigningAlgorithms]
+		};
+		return async (_req) => {
+			return Response.json(metadata, { headers: corsHeaders });
+		};
+	};
+	const middleware = () => {
+		return async (req, res, next) => {
+			const authHeader = getHeader(req, "authorization");
+			const requestHeaders = new Headers();
+			if (authHeader) requestHeaders.set("Authorization", authHeader);
+			const dpop = getHeader(req, "dpop");
+			if (dpop) requestHeaders.set("DPoP", dpop);
+			const request = new Request(getNodeRequestUrl(req), {
+				method: req.method ?? "GET",
+				headers: requestHeaders
+			});
+			let session;
+			try {
+				session = await verifyRequest(request);
+			} catch (error) {
+				if (isDpopBindingError(error)) {
+					send401Node(res, makeDpopWWWAuthenticate(dpopSigningAlgorithms), "Invalid or expired token");
+					return;
+				}
+				throw error;
+			}
+			if (!session) {
+				send401Node(res, selectChallenge(authHeader, !!getHeader(req, "dpop")), authHeader ? "Invalid or expired token" : "Unauthorized: Authentication required");
+				return;
+			}
+			req.mcpSession = session;
+			next();
+		};
+	};
+	return {
+		verifyToken,
+		verifyRequest,
+		handler,
+		discoveryHandler,
+		protectedResourceHandler,
+		middleware,
+		authURL
+	};
+}
+//#endregion
+export { createMcpResourceClient, makeDpopWWWAuthenticate };

package/dist/index.d.mts

@@ -1 +1,123 @@
-export { };
+import { OAuthOptions, Scope, oauthProvider } from "@better-auth/oauth-provider";
+import { DpopReplayReservations, DpopReplayStore, verifyAccessTokenRequest } from "better-auth/oauth2";
+import { JWTPayload } from "jose";
+import { Awaitable } from "@better-auth/core";
+import { BetterAuthOptions } from "better-auth/types";
+
+//#region src/handler.d.ts
+/**
+ * A request middleware handler that verifies an MCP access token and responds
+ * with an RFC 9728 `WWW-Authenticate` header for unauthenticated requests.
+ *
+ * @external
+ */
+declare const mcpHandler: (/** Verifier options. `audience` must match the protected resource identifier. */
+
+verifyOptions: Parameters<typeof verifyAccessTokenRequest>[1], handler: (req: Request, jwt: JWTPayload) => Awaitable<Response>, opts?: {
+  /** Maps non-url (ie urn, client) resources to resource_metadata */resourceMetadataMappings: Record<string, string>;
+}) => (req: Request) => Promise<Response>;
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * Options for the {@link mcp} plugin: the full OAuth provider configuration plus
+ * the MCP resource identifier.
+ */
+interface McpOptions extends OAuthOptions<Scope[]> {
+  /**
+   * The protected resource identifier (RFC 8707 / RFC 9728) that access tokens
+   * are bound to. Published as `resource` in the protected resource metadata,
+   * added to `resources`, and used as the expected token audience.
+   */
+  resource: string;
+}
+/**
+ * Model Context Protocol authorization server.
+ *
+ * `mcp()` is the OAuth 2.1 / OIDC provider ({@link oauthProvider}) configured for
+ * MCP: it enables dynamic client registration, binds issued tokens to the MCP
+ * `resource`, and, as the resource server, serves the RFC 9728 protected resource
+ * metadata so MCP clients discover and use it through standard OAuth discovery.
+ * Because it is the OAuth provider, it cannot be combined with a separate
+ * {@link oauthProvider}.
+ *
+ * @example
+ * ```ts
+ * import { betterAuth } from "better-auth";
+ * import { jwt } from "better-auth/plugins";
+ * import { mcp } from "@better-auth/mcp";
+ *
+ * export const auth = betterAuth({
+ *   plugins: [
+ *     jwt(),
+ *     mcp({
+ *       loginPage: "/login",
+ *       consentPage: "/consent",
+ *       resource: "https://api.example.com/mcp",
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare const mcp: (options: McpOptions) => ReturnType<typeof oauthProvider>;
+//#endregion
+//#region src/require-mcp-auth.d.ts
+interface RequireMcpAuthOptions {
+  /**
+   * The protected resource identifier the access token must be bound to.
+   * Defaults to the server's resolved base URL.
+   */
+  resource?: string;
+  /**
+   * Expected token issuer. Defaults to the server's resolved base URL. Override
+   * when the JWT plugin is configured with a custom `jwt.issuer`.
+   */
+  issuer?: string;
+  /**
+   * URL of the authorization server's JWKS. Defaults to `/jwks` under the
+   * server's resolved base URL.
+   */
+  jwksUrl?: string;
+  /**
+   * Space-delimited scopes to advertise in the `WWW-Authenticate` challenge
+   * (RFC 6750), hinting which scopes the client should request.
+   */
+  scope?: string;
+  /**
+   * Maps a non-URL `resource` (an RFC 8707 `urn:` identifier or a client id) to
+   * the URL of its protected resource metadata. Required when `resource` is not
+   * an origin-based URL, so the `WWW-Authenticate` challenge can point at it.
+   */
+  resourceMetadataMappings?: Record<string, string>;
+  /**
+   * DPoP proof validation settings. By default the replay store is backed by
+   * the auth instance's database adapter, so anti-replay holds across multiple
+   * server instances. Override `replayStore` only to point at a different store.
+   */
+  dpop?: {
+    proofMaxAgeSeconds?: number;
+    signingAlgorithms?: readonly string[];
+    replayStore?: DpopReplayStore;
+  };
+}
+/**
+ * Protects an MCP server route handler. Verifies the bearer access token
+ * against the authorization server's JWKS (checking signature, issuer,
+ * audience, and expiry) and forwards the verified JWT payload to the handler.
+ * Unauthenticated requests receive a JSON-RPC 401 with the RFC 9728
+ * `WWW-Authenticate` header so MCP clients can start the authorization flow.
+ *
+ * For a resource server that runs separately from the authorization server, or
+ * a server using a dynamic `baseURL`, use {@link mcpHandler} with explicit
+ * verification options instead.
+ *
+ * @external
+ */
+declare const requireMcpAuth: <Auth extends {
+  options: BetterAuthOptions;
+  $context: Promise<{
+    baseURL: string;
+    internalAdapter: DpopReplayReservations;
+  }>;
+}>(auth: Auth, handler: (req: Request, jwt: JWTPayload) => Awaitable<Response>, opts?: RequireMcpAuthOptions) => (req: Request) => Promise<Response>;
+//#endregion
+export { type McpOptions, mcp, mcpHandler, requireMcpAuth };