Refactoring OAuthErrors

This makes it possible to parse them from JSON, using OAUTH_ERRORS

Invalidating credentials & retrying when server OAuth errors occur

Updated existing tests

Added some initial test coverage

refactored to avoid recursion as recommended

Author: geelen

src/client/auth.test.ts

@@ -5,6 +5,7 @@ import {
   refreshAuthorization,
   registerClient,
 } from "./auth.js";
+import {ServerError} from "../server/auth/errors.js";
 
 // Mock fetch globally
 const mockFetch = jest.fn();
@@ -112,25 +113,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")
@@ -321,10 +320,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", {
@@ -403,10 +404,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", {
@@ -491,10 +494,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,7 +1,26 @@
 import pkceChallenge from "pkce-challenge";
-import { LATEST_PROTOCOL_VERSION } from "../types.js";
-import type { OAuthClientMetadata, OAuthClientInformation, OAuthTokens, OAuthMetadata, OAuthClientInformationFull } from "../shared/auth.js";
-import { OAuthClientInformationFullSchema, OAuthMetadataSchema, OAuthTokensSchema } from "../shared/auth.js";
+import {LATEST_PROTOCOL_VERSION} from "../types.js";
+import type {
+  OAuthClientInformation,
+  OAuthClientInformationFull,
+  OAuthClientMetadata,
+  OAuthMetadata,
+  OAuthTokens
+} from "../shared/auth.js";
+import {
+  OAuthClientInformationFullSchema,
+  OAuthErrorResponseSchema,
+  OAuthMetadataSchema,
+  OAuthTokensSchema
+} from "../shared/auth.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.
@@ -66,6 +85,13 @@ export interface OAuthClientProvider {
    * the authorization result.
    */
   codeVerifier(): string | Promise<string>;
+
+  /**
+   * 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";
@@ -76,6 +102,33 @@ export class UnauthorizedError extends Error {
   }
 }
 
+/**
+ * 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.
  * 
@@ -84,7 +137,30 @@ export class UnauthorizedError extends Error {
  */
 export async function auth(
   provider: OAuthClientProvider,
-  { serverUrl, authorizationCode }: { serverUrl: string | URL, authorizationCode?: string }): Promise<AuthResult> {
+  options: { serverUrl: string | URL, authorizationCode?: string },
+): 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,
+  options: { serverUrl: string | URL, authorizationCode?: string },
+): Promise<AuthResult> {
+  const { serverUrl, authorizationCode } = options;
   const metadata = await discoverOAuthMetadata(serverUrl);
 
   // Handle client registration if needed
@@ -119,7 +195,7 @@ export async function auth(
     });
 
     await provider.saveTokens(tokens);
-    return "AUTHORIZED";
+    return "AUTHORIZED"
   }
 
   const tokens = await provider.tokens();
@@ -135,14 +211,20 @@ export async function auth(
       });
 
       await provider.saveTokens(newTokens);
-      return "AUTHORIZED";
+      return "AUTHORIZED"
     } catch (error) {
-      console.error("Could not refresh OAuth tokens:", 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) {
+        console.error("Could not refresh OAuth tokens:", error);
+      } else {
+        console.warn(`OAuth token refresh failed: ${JSON.stringify(error.toResponseObject())}`);
+        throw error;
+      }
     }
   }
 
   // Start new authorization flow
-  const { authorizationUrl, codeVerifier } = await startAuthorization(serverUrl, {
+  const {authorizationUrl, codeVerifier} = await startAuthorization(serverUrl, {
     metadata,
     clientInformation,
     redirectUrl: provider.redirectUrl,
@@ -151,7 +233,7 @@ export async function auth(
 
   await provider.saveCodeVerifier(codeVerifier);
   await provider.redirectToAuthorization(authorizationUrl);
-  return "REDIRECT";
+  return "REDIRECT"
 }
 
 /**
@@ -316,7 +398,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());
@@ -375,7 +457,7 @@ export async function refreshAuthorization(
   });
 
   if (!response.ok) {
-    throw new Error(`Token refresh failed: HTTP ${response.status}`);
+    throw await parseErrorResponse(response);
   }
 
   return OAuthTokensSchema.parse(await response.json());
@@ -415,7 +497,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());