feat: implement SEP-985 OAuth 2.0 Protected Resource Metadata fallback

Aligns OAuth 2.0 Protected Resource Metadata handling with RFC 9728 and
SEP-985 by making the WWW-Authenticate header optional and implementing
graceful fallback behavior.

Changes:
- Updated discoverOAuthProtectedResourceMetadata() to return undefined
  instead of throwing on 404, making protected resource metadata optional
- Enhanced JSDoc comments to document SEP-985 fallback behavior
- Updated authInternal() to handle optional metadata with proper null checks
- Added comprehensive test suite for SEP-985 scenarios:
  - WWW-Authenticate header with resource_metadata present
  - WWW-Authenticate header without resource_metadata (fallback to well-known)
  - Missing WWW-Authenticate header (fallback to well-known)
  - 404 on well-known endpoint (graceful degradation)
  - CORS errors on metadata discovery (graceful fallback)
- Updated existing tests to expect undefined instead of errors on 404

Per SEP-985, clients now:
1. Check WWW-Authenticate header for resource_metadata parameter
2. Fallback to /.well-known/oauth-protected-resource if not present
3. Continue gracefully using the MCP server as auth server if metadata unavailable

All 856 tests pass.

Related: #920
Implements: SEP-985 (modelcontextprotocol/modelcontextprotocol#971)

Author: cbcoutinho

src/client/auth.test.ts

@@ -147,15 +147,14 @@ describe('OAuth Authorization', () => {
             expect(mockFetch).toHaveBeenCalledTimes(2);
         });
 
-        it('throws on 404 errors', async () => {
+        it('returns undefined on 404 errors (per SEP-985)', async () => {
             mockFetch.mockResolvedValueOnce({
                 ok: false,
                 status: 404
             });
 
-            await expect(discoverOAuthProtectedResourceMetadata('https://resource.example.com')).rejects.toThrow(
-                'Resource server does not implement OAuth 2.0 Protected Resource Metadata.'
-            );
+            const metadata = await discoverOAuthProtectedResourceMetadata('https://resource.example.com');
+            expect(metadata).toBeUndefined();
         });
 
         it('throws on non-404 errors', async () => {
@@ -248,7 +247,7 @@ describe('OAuth Authorization', () => {
             }
         );
 
-        it('throws error when both path-aware and root discovery return 404', async () => {
+        it('returns undefined when both path-aware and root discovery return 404 (per SEP-985)', async () => {
             // First call (path-aware) returns 404
             mockFetch.mockResolvedValueOnce({
                 ok: false,
@@ -261,9 +260,8 @@ describe('OAuth Authorization', () => {
                 status: 404
             });
 
-            await expect(discoverOAuthProtectedResourceMetadata('https://resource.example.com/path/name')).rejects.toThrow(
-                'Resource server does not implement OAuth 2.0 Protected Resource Metadata.'
-            );
+            const metadata = await discoverOAuthProtectedResourceMetadata('https://resource.example.com/path/name');
+            expect(metadata).toBeUndefined();
 
             const calls = mockFetch.mock.calls;
             expect(calls.length).toBe(2);
@@ -282,16 +280,15 @@ describe('OAuth Authorization', () => {
             expect(calls.length).toBe(1); // Should not attempt fallback
         });
 
-        it('does not fallback when the original URL is already at root path', async () => {
+        it('returns undefined when the original URL is already at root path and returns 404 (per SEP-985)', async () => {
             // First call (path-aware for root) returns 404
             mockFetch.mockResolvedValueOnce({
                 ok: false,
                 status: 404
             });
 
-            await expect(discoverOAuthProtectedResourceMetadata('https://resource.example.com/')).rejects.toThrow(
-                'Resource server does not implement OAuth 2.0 Protected Resource Metadata.'
-            );
+            const metadata = await discoverOAuthProtectedResourceMetadata('https://resource.example.com/');
+            expect(metadata).toBeUndefined();
 
             const calls = mockFetch.mock.calls;
             expect(calls.length).toBe(1); // Should not attempt fallback
@@ -300,16 +297,15 @@ describe('OAuth Authorization', () => {
             expect(url.toString()).toBe('https://resource.example.com/.well-known/oauth-protected-resource');
         });
 
-        it('does not fallback when the original URL has no path', async () => {
+        it('returns undefined when the original URL has no path and returns 404 (per SEP-985)', async () => {
             // First call (path-aware for no path) returns 404
             mockFetch.mockResolvedValueOnce({
                 ok: false,
                 status: 404
             });
 
-            await expect(discoverOAuthProtectedResourceMetadata('https://resource.example.com')).rejects.toThrow(
-                'Resource server does not implement OAuth 2.0 Protected Resource Metadata.'
-            );
+            const metadata = await discoverOAuthProtectedResourceMetadata('https://resource.example.com');
+            expect(metadata).toBeUndefined();
 
             const calls = mockFetch.mock.calls;
             expect(calls.length).toBe(1); // Should not attempt fallback
@@ -349,18 +345,17 @@ describe('OAuth Authorization', () => {
             });
         });
 
-        it('does not fallback when resourceMetadataUrl is provided', async () => {
+        it('returns undefined when resourceMetadataUrl is provided but returns 404 (per SEP-985)', async () => {
             // Call with explicit URL returns 404
             mockFetch.mockResolvedValueOnce({
                 ok: false,
                 status: 404
             });
 
-            await expect(
-                discoverOAuthProtectedResourceMetadata('https://resource.example.com/path', {
-                    resourceMetadataUrl: 'https://custom.example.com/metadata'
-                })
-            ).rejects.toThrow('Resource server does not implement OAuth 2.0 Protected Resource Metadata.');
+            const metadata = await discoverOAuthProtectedResourceMetadata('https://resource.example.com/path', {
+                resourceMetadataUrl: 'https://custom.example.com/metadata'
+            });
+            expect(metadata).toBeUndefined();
 
             const calls = mockFetch.mock.calls;
             expect(calls.length).toBe(1); // Should not attempt fallback when explicit URL is provided
@@ -2180,6 +2175,217 @@ describe('OAuth Authorization', () => {
             // Verify custom fetch was called for AS metadata discovery
             expect(customFetch.mock.calls[1][0].toString()).toBe('https://auth.example.com/.well-known/oauth-authorization-server');
         });
+
+        describe('SEP-985: WWW-Authenticate fallback behavior', () => {
+            it('uses resource_metadata URL from WWW-Authenticate header when provided', async () => {
+                // Mock PRM discovery from explicit URL
+                mockFetch.mockImplementation(url => {
+                    const urlString = url.toString();
+
+                    if (urlString === 'https://resource.example.com/custom/.well-known/oauth-protected-resource') {
+                        return Promise.resolve({
+                            ok: true,
+                            status: 200,
+                            json: async () => ({
+                                resource: 'https://resource.example.com',
+                                authorization_servers: ['https://auth.example.com']
+                            })
+                        });
+                    } else if (urlString.includes('/.well-known/oauth-authorization-server')) {
+                        return Promise.resolve({
+                            ok: true,
+                            status: 200,
+                            json: async () => ({
+                                issuer: 'https://auth.example.com',
+                                authorization_endpoint: 'https://auth.example.com/authorize',
+                                token_endpoint: 'https://auth.example.com/token',
+                                response_types_supported: ['code'],
+                                code_challenge_methods_supported: ['S256']
+                            })
+                        });
+                    }
+
+                    return Promise.resolve({ ok: false, status: 404 });
+                });
+
+                (mockProvider.clientInformation as jest.Mock).mockResolvedValue({
+                    client_id: 'test-client',
+                    client_secret: 'test-secret'
+                });
+                (mockProvider.tokens as jest.Mock).mockResolvedValue(undefined);
+
+                // Pass resourceMetadataUrl extracted from WWW-Authenticate header
+                const result = await auth(mockProvider, {
+                    serverUrl: 'https://resource.example.com',
+                    resourceMetadataUrl: new URL('https://resource.example.com/custom/.well-known/oauth-protected-resource')
+                });
+
+                expect(result).toBe('REDIRECT');
+
+                // Verify that the custom URL was used, not the default well-known path
+                const firstCall = mockFetch.mock.calls[0];
+                expect(firstCall[0].toString()).toBe('https://resource.example.com/custom/.well-known/oauth-protected-resource');
+            });
+
+            it('falls back to well-known when WWW-Authenticate header has no resource_metadata', async () => {
+                // Simulate: WWW-Authenticate present but without resource_metadata parameter
+                // In this case, resourceMetadataUrl would be undefined
+                mockFetch.mockImplementation(url => {
+                    const urlString = url.toString();
+
+                    if (urlString === 'https://resource.example.com/.well-known/oauth-protected-resource') {
+                        return Promise.resolve({
+                            ok: true,
+                            status: 200,
+                            json: async () => ({
+                                resource: 'https://resource.example.com',
+                                authorization_servers: ['https://auth.example.com']
+                            })
+                        });
+                    } else if (urlString.includes('/.well-known/oauth-authorization-server')) {
+                        return Promise.resolve({
+                            ok: true,
+                            status: 200,
+                            json: async () => ({
+                                issuer: 'https://auth.example.com',
+                                authorization_endpoint: 'https://auth.example.com/authorize',
+                                token_endpoint: 'https://auth.example.com/token',
+                                response_types_supported: ['code'],
+                                code_challenge_methods_supported: ['S256']
+                            })
+                        });
+                    }
+
+                    return Promise.resolve({ ok: false, status: 404 });
+                });
+
+                (mockProvider.clientInformation as jest.Mock).mockResolvedValue({
+                    client_id: 'test-client',
+                    client_secret: 'test-secret'
+                });
+                (mockProvider.tokens as jest.Mock).mockResolvedValue(undefined);
+
+                // No resourceMetadataUrl provided (as if WWW-Authenticate had no resource_metadata)
+                const result = await auth(mockProvider, {
+                    serverUrl: 'https://resource.example.com'
+                });
+
+                expect(result).toBe('REDIRECT');
+
+                // Verify fallback to well-known path
+                const firstCall = mockFetch.mock.calls[0];
+                expect(firstCall[0].toString()).toBe('https://resource.example.com/.well-known/oauth-protected-resource');
+            });
+
+            it('continues gracefully when well-known PRM returns 404', async () => {
+                // Per SEP-985, protected resource metadata is optional
+                // Client should fall back to using server as auth server
+                mockFetch.mockImplementation(url => {
+                    const urlString = url.toString();
+
+                    if (urlString === 'https://resource.example.com/.well-known/oauth-protected-resource') {
+                        // PRM not available - return 404
+                        return Promise.resolve({
+                            ok: false,
+                            status: 404
+                        });
+                    } else if (urlString === 'https://resource.example.com/.well-known/oauth-authorization-server') {
+                        // Fall back to server as auth server
+                        return Promise.resolve({
+                            ok: true,
+                            status: 200,
+                            json: async () => ({
+                                issuer: 'https://resource.example.com',
+                                authorization_endpoint: 'https://resource.example.com/authorize',
+                                token_endpoint: 'https://resource.example.com/token',
+                                registration_endpoint: 'https://resource.example.com/register',
+                                response_types_supported: ['code'],
+                                code_challenge_methods_supported: ['S256']
+                            })
+                        });
+                    } else if (urlString === 'https://resource.example.com/register') {
+                        return Promise.resolve({
+                            ok: true,
+                            status: 200,
+                            json: async () => ({
+                                client_id: 'registered-client-id',
+                                client_secret: 'registered-secret',
+                                redirect_uris: ['http://localhost:3000/callback'],
+                                client_name: 'Test Client'
+                            })
+                        });
+                    }
+
+                    return Promise.resolve({ ok: false, status: 404 });
+                });
+
+                (mockProvider.clientInformation as jest.Mock).mockResolvedValue(undefined);
+                (mockProvider.tokens as jest.Mock).mockResolvedValue(undefined);
+                mockProvider.saveClientInformation = jest.fn();
+
+                const result = await auth(mockProvider, {
+                    serverUrl: 'https://resource.example.com'
+                });
+
+                expect(result).toBe('REDIRECT');
+
+                // Verify we tried PRM discovery
+                expect(mockFetch.mock.calls[0][0].toString()).toBe('https://resource.example.com/.well-known/oauth-protected-resource');
+
+                // Verify we fell back to auth server metadata on same server
+                expect(mockFetch.mock.calls[1][0].toString()).toBe('https://resource.example.com/.well-known/oauth-authorization-server');
+
+                // Verify client registration happened
+                expect(mockProvider.saveClientInformation).toHaveBeenCalled();
+            });
+
+            it('handles CORS error on PRM discovery and falls back gracefully', async () => {
+                let callCount = 0;
+
+                mockFetch.mockImplementation(url => {
+                    callCount++;
+                    const urlString = url.toString();
+
+                    if (callCount <= 2 && urlString.includes('oauth-protected-resource')) {
+                        // Simulate CORS error on PRM discovery (both with and without headers)
+                        return Promise.reject(new TypeError('Network request failed'));
+                    } else if (urlString.includes('oauth-authorization-server')) {
+                        // Auth server metadata succeeds
+                        return Promise.resolve({
+                            ok: true,
+                            status: 200,
+                            json: async () => ({
+                                issuer: 'https://resource.example.com',
+                                authorization_endpoint: 'https://resource.example.com/authorize',
+                                token_endpoint: 'https://resource.example.com/token',
+                                response_types_supported: ['code'],
+                                code_challenge_methods_supported: ['S256']
+                            })
+                        });
+                    }
+
+                    return Promise.resolve({ ok: false, status: 404 });
+                });
+
+                (mockProvider.clientInformation as jest.Mock).mockResolvedValue({
+                    client_id: 'test-client',
+                    client_secret: 'test-secret'
+                });
+                (mockProvider.tokens as jest.Mock).mockResolvedValue(undefined);
+
+                const result = await auth(mockProvider, {
+                    serverUrl: 'https://resource.example.com'
+                });
+
+                expect(result).toBe('REDIRECT');
+
+                // Verify we tried PRM discovery (with retry for CORS)
+                expect(mockFetch.mock.calls.filter(call => call[0].toString().includes('oauth-protected-resource')).length).toBeGreaterThan(0);
+
+                // Verify we eventually fell back to auth server metadata
+                expect(mockFetch.mock.calls.some(call => call[0].toString().includes('oauth-authorization-server'))).toBe(true);
+            });
+        });
     });
 
     describe('exchangeAuthorization with multiple client authentication methods', () => {