@better-auth/mcp 1.7.21 → 1.7.23

package/dist/index.d.mts

@@ -1,9 +1,8 @@
 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";
-//#region src/handler.d.ts
 interface McpProtectedRequestHandlerOptions {
   /** Expected authorization-server issuer for the access token. */
   issuer: string;
@@ -37,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.
@@ -48,9 +59,7 @@ interface McpProtectedRequestHandlerOptions {
  *
  * @external
  */
-export declare const createMcpProtectedRequestHandler: (options: McpProtectedRequestHandlerOptions, handler: (request: Request, accessTokenClaims: JWTPayload) => Awaitable<Response>) => (request: Request) => Promise<Response>;
-//#endregion
-//#region src/plugin.d.ts
+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.
@@ -125,8 +134,6 @@ interface McpOptions extends OAuthOptions<Scope[]> {
  * ```
  */
 export 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.
@@ -139,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;
   /**
@@ -189,10 +197,8 @@ 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>;
-//#endregion
 export type { McpOptions, McpProtectedRequestHandlerOptions, RequireMcpAuthOptions };

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { isLoopbackHost } from "@better-auth/core/utils/host";
 import { createResourceServerChallenge, getIssuer, metadataResponse, oauthProvider } from "@better-auth/oauth-provider";
 import { DPOP_SIGNING_ALGORITHMS, createDpopReplayStore, isInsufficientScopeError, requestToResourceInput, verifyAccessTokenRequest } from "better-auth/oauth2";
-//#region src/handler.ts
+// src/handler.ts
 /**
 * Validates the canonical protected-resource identifier accepted by MCP.
 *
@@ -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,
@@ -69,18 +78,23 @@ const createMcpProtectedRequestHandler = (options, handler) => {
 		try {
 			accessTokenClaims = await verifyAccessTokenRequest(requestToResourceInput(request), accessTokenVerificationOptions);
 		} catch (error) {
-			return toChallengeResponse(error, resource, resolvedChallengeOptions);
+			return toChallengeResponse(error, resource, {
+				...resolvedChallengeOptions,
+				request
+			});
 		}
 		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;
 		}
 	};
 };
-//#endregion
-//#region src/plugin.ts
+// src/plugin.ts
 const PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource";
 const AUTHORIZATION_SERVER_ONLY_SCOPES = /* @__PURE__ */ new Set([
 	"openid",
@@ -199,8 +213,7 @@ const mcp = (options) => {
 		}
 	};
 };
-//#endregion
-//#region src/require-mcp-auth.ts
+// src/require-mcp-auth.ts
 /**
 * Protects an MCP server route handler. Verifies the bearer access token
 * against the authorization server's JWKS (checking signature, issuer,
@@ -222,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"] },
@@ -243,5 +263,4 @@ const requireMcpAuth = (auth, handler, opts) => {
 		}, handler)(req);
 	};
 };
-//#endregion
 export { createMcpProtectedRequestHandler, mcp, requireMcpAuth };

package/package.json

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