feat(server-legacy): add expectedResource to requireBearerAuth (#2952)

Co-authored-by: Felix Weinberger <3823880+felixweinberger@users.noreply.github.com>

Author: claude[bot]

.changeset/server-legacy-expected-resource.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/server-legacy': patch
+---
+
+`requireBearerAuth` in `@modelcontextprotocol/server-legacy` takes the optional `expectedResource` that `@modelcontextprotocol/server` 2.3.0 and `@modelcontextprotocol/sdk` 1.32.0 added: the resource the token must be issued for (its audience), usually the server's URL. When it is set, a token is accepted only if the verifier reports that value in `AuthInfo.resource`; the two are compared as strings, ignoring a fragment and one trailing slash. A token reported for another value, or for none, is answered `401 invalid_token` with the usual `WWW-Authenticate` challenge. When it is not set, nothing changes. The package stays frozen otherwise; this option is added so that its `requireBearerAuth` matches the 1.x middleware it is a copy of.

packages/server-legacy/src/auth/middleware/bearerAuth.ts

@@ -19,8 +19,28 @@ export type BearerAuthMiddlewareOptions = {
      * Optional resource metadata URL to include in WWW-Authenticate header.
      */
     resourceMetadataUrl?: string;
+
+    /**
+     * Optional resource the token must be issued for (its audience), usually the server's URL.
+     * When set, the verifier has to report this value in `AuthInfo.resource` (a fragment and one trailing slash
+     * are ignored); any other token is refused with `401 invalid_token`.
+     */
+    expectedResource?: URL;
 };
 
+// The serialized value without its fragment and without one trailing slash.
+function comparableResource(value: URL): string {
+    const text = String(value);
+    const hash = text.indexOf('#');
+    return (hash === -1 ? text : text.slice(0, hash)).replace(/\/$/, '');
+}
+
+// A reported resource matches when it serializes to the same string as the expected one, fragment and one trailing slash aside.
+function sameResource(reported: URL | undefined, expected: URL): boolean {
+    if (!reported) return false;
+    return comparableResource(reported) === comparableResource(expected);
+}
+
 declare module 'express-serve-static-core' {
     interface Request {
         /**
@@ -38,7 +58,12 @@ declare module 'express-serve-static-core' {
  * If resourceMetadataUrl is provided, it will be included in the WWW-Authenticate header
  * for 401 responses as per the OAuth 2.0 Protected Resource Metadata spec.
  */
-export function requireBearerAuth({ verifier, requiredScopes = [], resourceMetadataUrl }: BearerAuthMiddlewareOptions): RequestHandler {
+export function requireBearerAuth({
+    verifier,
+    requiredScopes = [],
+    resourceMetadataUrl,
+    expectedResource
+}: BearerAuthMiddlewareOptions): RequestHandler {
     const buildWwwAuthHeader = (errorCode: string, message: string): string => {
         let header = `Bearer error="${errorCode}", error_description="${message}"`;
         if (requiredScopes.length > 0) {
@@ -64,6 +89,10 @@ export function requireBearerAuth({ verifier, requiredScopes = [], resourceMetad
 
             const authInfo = await verifier.verifyAccessToken(token);
 
+            if (expectedResource !== undefined && !sameResource(authInfo.resource, expectedResource)) {
+                throw new InvalidTokenError('Token was not issued for this resource');
+            }
+
             if (requiredScopes.length > 0) {
                 const hasAllScopes = requiredScopes.every(scope => authInfo.scopes.includes(scope));
 

packages/server-legacy/test/auth/middleware/bearerAuth.test.ts

@@ -498,4 +498,82 @@ describe('requireBearerAuth middleware', () => {
             expect(nextFunction).not.toHaveBeenCalled();
         });
     });
+
+    describe('with expectedResource', () => {
+        const expectedResource = new URL('https://api.example.com/mcp');
+        const notIssuedForThisResource = { error: 'invalid_token', error_description: 'Token was not issued for this resource' };
+
+        async function handle(reported: string | undefined, options: { expectedResource?: URL; requiredScopes?: string[] } = {}) {
+            const authInfo: AuthInfo = {
+                token: 'valid-token',
+                clientId: 'client-123',
+                scopes: ['read'],
+                expiresAt: Date.now() / 1000 + 3600
+            };
+            if (reported !== undefined) authInfo.resource = new URL(reported);
+            mockVerifyAccessToken.mockResolvedValue(authInfo);
+            const req = { headers: { authorization: 'Bearer valid-token' } } as Request;
+            const res = createExpressResponseMock();
+            const next = vi.fn();
+            await requireBearerAuth({ verifier: mockVerifier, ...options })(req, res, next);
+            return { req, res, next, authInfo };
+        }
+
+        function expectAccepted({ req, res, next, authInfo }: Awaited<ReturnType<typeof handle>>) {
+            expect(req.auth).toEqual(authInfo);
+            expect(next).toHaveBeenCalled();
+            expect(res.status).not.toHaveBeenCalled();
+        }
+
+        function expectUnauthorized({ req, res, next }: Awaited<ReturnType<typeof handle>>) {
+            expect(res.status).toHaveBeenCalledWith(401);
+            expect(res.set).toHaveBeenCalledWith(
+                'WWW-Authenticate',
+                expect.stringMatching(/^Bearer error="invalid_token", error_description="Token was not issued for this resource"/)
+            );
+            expect(res.json).toHaveBeenCalledWith(notIssuedForThisResource);
+            expect(req.auth).toBeUndefined();
+            expect(next).not.toHaveBeenCalled();
+        }
+
+        it('should compare AuthInfo.resource only when expectedResource is set', async () => {
+            expectAccepted(await handle('https://other.example.com/mcp'));
+            expectUnauthorized(await handle('https://other.example.com/mcp', { expectedResource }));
+        });
+
+        it('should reject a token without a reported resource only when expectedResource is set', async () => {
+            expectAccepted(await handle(undefined));
+            expectUnauthorized(await handle(undefined, { expectedResource }));
+        });
+
+        it('should accept a token reported for expectedResource, one trailing slash aside on either value', async () => {
+            expectAccepted(await handle('https://api.example.com/mcp', { expectedResource }));
+            expectAccepted(await handle('https://api.example.com/mcp/', { expectedResource }));
+            expectAccepted(await handle('https://api.example.com/mcp', { expectedResource: new URL('https://api.example.com/mcp/') }));
+            expectAccepted(await handle('HTTPS://API.example.com:443/mcp', { expectedResource }));
+            expectUnauthorized(await handle('https://api.example.com/mcp//', { expectedResource }));
+        });
+
+        it('should ignore a fragment on either value', async () => {
+            expectAccepted(await handle('https://api.example.com/mcp#section', { expectedResource }));
+            expectAccepted(await handle('https://api.example.com/mcp', { expectedResource: new URL(`${expectedResource}#section`) }));
+            expectAccepted(await handle('https://api.example.com/mcp/#section', { expectedResource }));
+            expectUnauthorized(await handle('https://api.example.com/other#section', { expectedResource }));
+        });
+
+        it.each([
+            'https://other.example.com/mcp',
+            'http://api.example.com/mcp',
+            'https://api.example.com:8443/mcp',
+            'https://api.example.com/',
+            'https://api.example.com/mcp/tools',
+            'https://api.example.com/mcp?tenant=a'
+        ])('should return 401 for a token reported for %s', async reported => {
+            expectUnauthorized(await handle(reported, { expectedResource }));
+        });
+
+        it('should return 401 for a token reported for another resource before checking scopes', async () => {
+            expectUnauthorized(await handle('https://other.example.com/mcp', { expectedResource, requiredScopes: ['write'] }));
+        });
+    });
 });