Adding invalidateCredentials() to OAuthClientProvider (modelcontextprotocol#570)

Co-authored-by: Paul Carleton <paulc@anthropic.com>

Author: geelen

src/client/auth.test.ts

@@ -10,6 +10,7 @@ import {
  auth,
  type OAuthClientProvider,
 } from "./auth.js";
+import {ServerError} from "../server/auth/errors.js";
 import { OAuthMetadata } from '../shared/auth.js';
 
 // Mock fetch globally
@@ -596,25 +597,23 @@ describe("OAuth Authorization", () => {
  });
 
  it("throws on non-404 errors", async () => {
- mockFetch.mockResolvedValueOnce({
- ok: false,
- status: 500,
- });
+ mockFetch.mockResolvedValueOnce(new Response(null, { status: 500 }));
 
  await expect(
  discoverOAuthMetadata("https://auth.example.com")
  ).rejects.toThrow("HTTP 500");
  });
 
  it("validates metadata schema", async () => {
- mockFetch.mockResolvedValueOnce({
- ok: true,
- status: 200,
- json: async () => ({
- // Missing required fields
- issuer: "https://auth.example.com",
- }),
- });
+ mockFetch.mockResolvedValueOnce(
+ Response.json(
+ {
+ // Missing required fields
+ issuer: "https://auth.example.com",
+ },
+ { status: 200 }
+ )
+ );
 
  await expect(
  discoverOAuthMetadata("https://auth.example.com")
@@ -902,10 +901,12 @@ describe("OAuth Authorization", () => {
  });
 
  it("throws on error response", async () => {
- mockFetch.mockResolvedValueOnce({
- ok: false,
- status: 400,
- });
+ mockFetch.mockResolvedValueOnce(
+ Response.json(
+ new ServerError("Token exchange failed").toResponseObject(),
+ { status: 400 }
+ )
+ );
 
  await expect(
  exchangeAuthorization("https://auth.example.com", {
@@ -1054,10 +1055,12 @@ describe("OAuth Authorization", () => {
  });
 
  it("throws on error response", async () => {
- mockFetch.mockResolvedValueOnce({
- ok: false,
- status: 400,
- });
+ mockFetch.mockResolvedValueOnce(
+ Response.json(
+ new ServerError("Token refresh failed").toResponseObject(),
+ { status: 400 }
+ )
+ );
 
  await expect(
  refreshAuthorization("https://auth.example.com", {
@@ -1142,10 +1145,12 @@ describe("OAuth Authorization", () => {
  });
 
  it("throws on error response", async () => {
- mockFetch.mockResolvedValueOnce({
- ok: false,
- status: 400,
- });
+ mockFetch.mockResolvedValueOnce(
+ Response.json(
+ new ServerError("Dynamic client registration failed").toResponseObject(),
+ { status: 400 }
+ )
+ );
 
  await expect(
  registerClient("https://auth.example.com", {

src/client/auth.ts

@@ -1,8 +1,24 @@
 import pkceChallenge from "pkce-challenge";
 import { LATEST_PROTOCOL_VERSION } from "../types.js";
-import type { OAuthClientMetadata, OAuthClientInformation, OAuthTokens, OAuthMetadata, OAuthClientInformationFull, OAuthProtectedResourceMetadata } from "../shared/auth.js";
+import {
+ OAuthClientMetadata,
+ OAuthClientInformation,
+ OAuthTokens,
+ OAuthMetadata,
+ OAuthClientInformationFull,
+ OAuthProtectedResourceMetadata,
+ OAuthErrorResponseSchema
+} from "../shared/auth.js";
 import { OAuthClientInformationFullSchema, OAuthMetadataSchema, OAuthProtectedResourceMetadataSchema, OAuthTokensSchema } from "../shared/auth.js";
 import { checkResourceAllowed, resourceUrlFromServerUrl } from "../shared/auth-utils.js";
+import {
+ InvalidClientError,
+ InvalidGrantError,
+ OAUTH_ERRORS,
+ OAuthError,
+ ServerError,
+ UnauthorizedClientError
+} from "../server/auth/errors.js";
 
 /**
  * Implements an end-to-end OAuth client to be used with one MCP server.
@@ -101,6 +117,13 @@ export interface OAuthClientProvider {
  * Implementations must verify the returned resource matches the MCP server.
  */
  validateResourceURL?(serverUrl: string | URL, resource?: string): Promise<URL | undefined>;
+
+ /**
+ * If implemented, provides a way for the client to invalidate (e.g. delete) the specified
+ * credentials, in the case where the server has indicated that they are no longer valid.
+ * This avoids requiring the user to intervene manually.
+ */
+ invalidateCredentials?(scope: 'all' | 'client' | 'tokens' | 'verifier'): void | Promise<void>;
 }
 
 export type AuthResult = "AUTHORIZED" | "REDIRECT";
@@ -219,13 +242,65 @@ function applyPublicAuth(clientId: string, params: URLSearchParams): void {
  params.set("client_id", clientId);
 }
 
+/**
+ * Parses an OAuth error response from a string or Response object.
+ *
+ * If the input is a standard OAuth2.0 error response, it will be parsed according to the spec
+ * and an instance of the appropriate OAuthError subclass will be returned.
+ * If parsing fails, it falls back to a generic ServerError that includes
+ * the response status (if available) and original content.
+ *
+ * @param input - A Response object or string containing the error response
+ * @returns A Promise that resolves to an OAuthError instance
+ */
+export async function parseErrorResponse(input: Response | string): Promise<OAuthError> {
+ const statusCode = input instanceof Response ? input.status : undefined;
+ const body = input instanceof Response ? await input.text() : input;
+
+ try {
+ const result = OAuthErrorResponseSchema.parse(JSON.parse(body));
+ const { error, error_description, error_uri } = result;
+ const errorClass = OAUTH_ERRORS[error] || ServerError;
+ return new errorClass(error_description || '', error_uri);
+ } catch (error) {
+ // Not a valid OAuth error response, but try to inform the user of the raw data anyway
+ const errorMessage = `${statusCode ? `HTTP ${statusCode}: ` : ''}Invalid OAuth error response: ${error}. Raw body: ${body}`;
+ return new ServerError(errorMessage);
+ }
+}
+
 /**
  * Orchestrates the full auth flow with a server.
  *
  * This can be used as a single entry point for all authorization functionality,
  * instead of linking together the other lower-level functions in this module.
  */
 export async function auth(
+ provider: OAuthClientProvider,
+ options: {
+ serverUrl: string | URL;
+ authorizationCode?: string;
+ scope?: string;
+ resourceMetadataUrl?: URL }): Promise<AuthResult> {
+
+ try {
+ return await authInternal(provider, options);
+ } catch (error) {
+ // Handle recoverable error types by invalidating credentials and retrying
+ if (error instanceof InvalidClientError || error instanceof UnauthorizedClientError) {
+ await provider.invalidateCredentials?.('all');
+ return await authInternal(provider, options);
+ } else if (error instanceof InvalidGrantError) {
+ await provider.invalidateCredentials?.('tokens');
+ return await authInternal(provider, options);
+ }
+
+ // Throw otherwise
+ throw error
+ }
+}
+
+async function authInternal(
  provider: OAuthClientProvider,
  { serverUrl,
  authorizationCode,
@@ -289,7 +364,7 @@ export async function auth(
  });
 
  await provider.saveTokens(tokens);
- return "AUTHORIZED";
+ return "AUTHORIZED"
  }
 
  const tokens = await provider.tokens();
@@ -307,9 +382,15 @@ export async function auth(
  });
 
  await provider.saveTokens(newTokens);
- return "AUTHORIZED";
- } catch {
- // Could not refresh OAuth tokens
+ return "AUTHORIZED"
+ } catch (error) {
+ // If this is a ServerError, or an unknown type, log it out and try to continue. Otherwise, escalate so we can fix things and retry.
+ if (!(error instanceof OAuthError) || error instanceof ServerError) {
+ // Could not refresh OAuth tokens
+ } else {
+ // Refresh failed for another reason, re-throw
+ throw error;
+ }
  }
  }
 
@@ -327,7 +408,7 @@ export async function auth(
 
  await provider.saveCodeVerifier(codeVerifier);
  await provider.redirectToAuthorization(authorizationUrl);
- return "REDIRECT";
+ return "REDIRECT"
 }
 
 export async function selectResourceURL(serverUrl: string | URL, provider: OAuthClientProvider, resourceMetadata?: OAuthProtectedResourceMetadata): Promise<URL | undefined> {
@@ -707,7 +788,7 @@ export async function exchangeAuthorization(
  });
 
  if (!response.ok) {
- throw new Error(`Token exchange failed: HTTP ${response.status}`);
+ throw await parseErrorResponse(response);
  }
 
  return OAuthTokensSchema.parse(await response.json());
@@ -788,7 +869,7 @@ export async function refreshAuthorization(
  body: params,
  });
  if (!response.ok) {
- throw new Error(`Token refresh failed: HTTP ${response.status}`);
+ throw await parseErrorResponse(response);
  }
 
  return OAuthTokensSchema.parse({ refresh_token: refreshToken, ...(await response.json()) });
@@ -828,7 +909,7 @@ export async function registerClient(
  });
 
  if (!response.ok) {
- throw new Error(`Dynamic client registration failed: HTTP ${response.status}`);
+ throw await parseErrorResponse(response);
  }
 
  return OAuthClientInformationFullSchema.parse(await response.json());