@better-auth/mcp 1.7.22 → 1.7.23

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { OAuthOptions, Scope, oauthProvider } from "@better-auth/oauth-provider";
 import { DpopReplayReservations, DpopReplayStore } from "better-auth/oauth2";
-import { Awaitable } from "@better-auth/core";
+import { AuthContext, Awaitable } from "@better-auth/core";
 import { JWTPayload, JWTVerifyOptions } from "jose";
 import { BetterAuthOptions } from "better-auth/types";
 interface McpProtectedRequestHandlerOptions {
@@ -36,9 +36,21 @@ interface McpProtectedRequestHandlerOptions {
   dpop?: {
     proofMaxAgeSeconds?: number;
     signingAlgorithms?: readonly string[];
+    /**
+     * Store that rejects a DPoP proof that was already used.
+     *
+     * Unlike `requireMcpAuth`, this handler has no auth instance to store
+     * proofs in, so it defaults to a process-local in-memory store. That is
+     * safe only for a single long-lived instance. For multiple instances or
+     * serverless, pass a shared store, such as
+     * `createDpopReplayStore((await auth.$context).internalAdapter)` from
+     * `better-auth/oauth2`. With secondary storage, that store also needs
+     * `verification.storeInDatabase: true`, or every DPoP request fails.
+     */
     replayStore?: DpopReplayStore;
   };
 }
+type McpRequestHandler = (request: Request, accessTokenClaims: JWTPayload) => Awaitable<Response>;
 /**
  * A request middleware handler that verifies an MCP access token and responds
  * with an RFC 9728 `WWW-Authenticate` header for unauthenticated requests.
@@ -47,7 +59,7 @@ interface McpProtectedRequestHandlerOptions {
  *
  * @external
  */
-export declare const createMcpProtectedRequestHandler: (options: McpProtectedRequestHandlerOptions, handler: (request: Request, accessTokenClaims: JWTPayload) => Awaitable<Response>) => (request: Request) => Promise<Response>;
+export declare const createMcpProtectedRequestHandler: (options: McpProtectedRequestHandlerOptions, handler: McpRequestHandler) => (request: Request) => Promise<Response>;
 /**
  * Options for the {@link mcp} plugin: the full OAuth provider configuration plus
  * the MCP resource identifier.
@@ -134,8 +146,9 @@ interface RequireMcpAuthOptions {
    */
   issuer?: string;
   /**
-   * URL of the authorization server's JWKS. Defaults to `/jwks` under the
-   * server's resolved base URL.
+   * URL of the authorization server's JWKS. When unset, the signing keys are
+   * read from the auth instance in-process, without an HTTP request, or
+   * fetched from the JWT plugin's `jwks.remoteUrl` when it sets one.
    */
   jwksUrl?: string;
   /**
@@ -184,8 +197,7 @@ interface RequireMcpAuthOptions {
  */
 export declare const requireMcpAuth: <Auth extends {
   options: BetterAuthOptions;
-  $context: Promise<{
-    baseURL: string;
+  $context: Promise<Pick<AuthContext, "baseURL" | "getPlugin"> & {
     internalAdapter: DpopReplayReservations;
   }>;
 }>(auth: Auth, handler: (request: Request, accessTokenClaims: JWTPayload) => Awaitable<Response>, opts?: RequireMcpAuthOptions) => (req: Request) => Promise<Response>;

package/dist/index.mjs

@@ -46,7 +46,14 @@ function toChallengeResponse(error, resource, opts) {
 *
 * @external
 */
-const createMcpProtectedRequestHandler = (options, handler) => {
+const createMcpProtectedRequestHandler = (options, handler) => createProtectedRequestHandler(options, handler);
+/**
+* {@link createMcpProtectedRequestHandler} that can also read the
+* authorization server's keys in-process.
+*
+* @internal
+*/
+const createProtectedRequestHandler = (options, handler) => {
 	const resource = validateMcpResource(options.audience);
 	const resolvedChallengeOptions = {
 		challengeScopes: options.challengeScopes ?? options.requiredScopes,
@@ -59,6 +66,8 @@ const createMcpProtectedRequestHandler = (options, handler) => {
 			audience: options.audience
 		},
 		jwksUrl: options.jwksUrl,
+		jwksFetch: options.jwksFetch,
+		jwksCacheKey: options.jwksCacheKey,
 		remoteVerify: options.remoteVerify,
 		requiredScopes: options.requiredScopes,
 		isScopeSatisfied: options.isScopeSatisfied,
@@ -77,7 +86,10 @@ const createMcpProtectedRequestHandler = (options, handler) => {
 		try {
 			return await handler(request, accessTokenClaims);
 		} catch (error) {
-			if (isInsufficientScopeError(error)) return toChallengeResponse(error, resource, resolvedChallengeOptions);
+			if (isInsufficientScopeError(error)) return toChallengeResponse(error, resource, {
+				...resolvedChallengeOptions,
+				request
+			});
 			throw error;
 		}
 	};
@@ -223,12 +235,19 @@ const mcp = (options) => {
 const requireMcpAuth = (auth, handler, opts) => {
 	if (opts?.resource !== void 0) validateMcpResource(opts.resource);
 	return async (req) => {
-		const { baseURL, internalAdapter } = await auth.$context;
+		const authContext = await auth.$context;
+		const { baseURL, internalAdapter } = authContext;
 		if (!baseURL) throw new Error("requireMcpAuth requires a resolvable base URL. For dynamic base URLs use `createMcpProtectedRequestHandler` with explicit verification options.");
 		const issuer = opts?.issuer ?? baseURL;
 		const resource = opts?.resource ?? baseURL;
-		const jwksUrl = opts?.jwksUrl ?? `${baseURL}/jwks`;
-		return createMcpProtectedRequestHandler({
+		const jwtPlugin = authContext.getPlugin("jwt");
+		const localJwks = !opts?.jwksUrl && jwtPlugin && !jwtPlugin.options?.jwks?.remoteUrl ? {
+			jwksFetch: async () => jwtPlugin.endpoints.getJwks({ context: authContext }),
+			jwksCacheKey: authContext
+		} : void 0;
+		const jwksUrl = opts?.jwksUrl ?? jwtPlugin?.options?.jwks?.remoteUrl ?? `${baseURL}/jwks`;
+		return createProtectedRequestHandler({
+			...localJwks,
 			issuer,
 			audience: resource,
 			jwtVerifyOptions: { requiredClaims: ["azp"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/mcp",
-  "version": "1.7.22",
+  "version": "1.7.23",
   "description": "Model Context Protocol (MCP) plugin for Better Auth",
   "type": "module",
   "license": "MIT",
@@ -46,20 +46,20 @@
     }
   },
   "dependencies": {
-    "@better-auth/oauth-provider": "^1.7.22",
+    "@better-auth/oauth-provider": "^1.7.23",
     "jose": "^6.1.3"
   },
   "devDependencies": {
-    "@better-auth/core": "1.7.22",
+    "@better-auth/core": "1.7.23",
     "@modelcontextprotocol/client": "2.3.1",
     "@modelcontextprotocol/server": "2.3.1",
-    "better-auth": "1.7.22",
+    "better-auth": "1.7.23",
     "better-call": "1.4.5",
     "tsdown": "0.23.1"
   },
   "peerDependencies": {
-    "@better-auth/core": "^1.7.22",
-    "better-auth": "^1.7.22",
+    "@better-auth/core": "^1.7.23",
+    "better-auth": "^1.7.23",
     "better-call": "1.4.5"
   },
   "scripts": {