@dxheroes/local-mcp-backend 0.9.2 → 0.10.0

package/src/__tests__/integration/proxy-auth.test.ts

@@ -1,12 +1,12 @@
 /**
  * Integration Tests: Proxy controller auth
  *
- * Verifies that:
- * - Proxy routes are @Public() (no session cookie required)
- * - Bearer token validation via resolveUser flow
+ * Verifies:
+ * - McpOAuthGuard always enforces Bearer token
+ * - WWW-Authenticate header with resource_metadata_uri on 401
+ * - Valid tokens resolve user and pass through
  * - Org-scoped profile lookup through the proxy service
- * - Unauthenticated access uses __unauthenticated__ sentinel
- * - Gateway endpoint still works with handleGatewayRequest
+ * - Gateway endpoint uses default profile with user scoping
  */
 
 import { NotFoundException, UnauthorizedException } from '@nestjs/common';
@@ -17,6 +17,7 @@ import type { McpRequest, McpResponse, ProxyService } from '../../modules/proxy/
 import type { SettingsService } from '../../modules/settings/settings.service.js';
 
 // Dynamic import to handle ESM
+const { McpOAuthGuard } = await import('../../modules/auth/mcp-oauth.guard.js');
 const { ProxyController } = await import('../../modules/proxy/proxy.controller.js');
 
 // ────────────────────────────────────────────────
@@ -33,6 +34,17 @@ function createMockAuthService() {
   };
 }
 
+function createMockConfigService(overrides: Record<string, unknown> = {}) {
+  const defaults: Record<string, unknown> = {
+    'app.port': 3001,
+    BETTER_AUTH_URL: 'http://localhost:3001',
+  };
+  const config = { ...defaults, ...overrides };
+  return {
+    get: vi.fn((key: string) => config[key]),
+  };
+}
+
 function createMockProxyService() {
   return {
     handleRequest: vi.fn().mockResolvedValue({
@@ -73,204 +85,145 @@ function createMockEventEmitter() {
   };
 }
 
-function createMockRequest(headers: Record<string, string> = {}) {
+function createMockRequest(headers: Record<string, string> = {}, query: Record<string, string> = {}) {
   return {
     headers,
+    query,
     on: vi.fn(),
+    user: undefined as any,
   } as unknown as import('express').Request;
 }
 
-describe('Proxy controller auth', () => {
-  let controller: InstanceType<typeof ProxyController>;
+function createMockExecutionContext(req: import('express').Request) {
+  return {
+    switchToHttp: () => ({
+      getRequest: () => req,
+      getResponse: () => ({}),
+    }),
+    getHandler: () => ({}),
+    getClass: () => ({}),
+  } as any;
+}
+
+// ────────────────────────────────────────────────
+// McpOAuthGuard tests
+// ────────────────────────────────────────────────
+
+describe('McpOAuthGuard', () => {
+  let guard: InstanceType<typeof McpOAuthGuard>;
   let authService: ReturnType<typeof createMockAuthService>;
-  let proxyService: ReturnType<typeof createMockProxyService>;
-  let settingsService: ReturnType<typeof createMockSettingsService>;
-  let eventEmitter: ReturnType<typeof createMockEventEmitter>;
 
-  // ────────────────────────────────────────────────
-  // Unauthenticated access (no Bearer token)
-  // ────────────────────────────────────────────────
-
-  describe('unauthenticated access (no Bearer token)', () => {
-    beforeEach(() => {
-      authService = createMockAuthService();
-      proxyService = createMockProxyService();
-      settingsService = createMockSettingsService();
-      eventEmitter = createMockEventEmitter();
-
-      controller = new ProxyController(
-        proxyService as unknown as ProxyService,
-        settingsService as unknown as SettingsService,
-        eventEmitter as unknown as EventEmitter2,
-        authService as unknown as AuthService
-      );
-    });
+  beforeEach(() => {
+    authService = createMockAuthService();
+    const configService = createMockConfigService();
+    guard = new McpOAuthGuard(
+      authService as unknown as AuthService,
+      configService as any
+    );
+  });
 
-    it('org-scoped POST request passes __unauthenticated__ to proxy service', async () => {
-      const req = createMockRequest();
-      const mcpRequest: McpRequest = {
-        jsonrpc: '2.0',
-        id: 1,
-        method: 'tools/list',
-      };
+  it('rejects request without Bearer token with 401', async () => {
+    const req = createMockRequest();
+    const ctx = createMockExecutionContext(req);
 
-      await controller.handleOrgMcpRequest(req, 'my-org', 'my-profile', mcpRequest);
+    await expect(guard.canActivate(ctx)).rejects.toThrow(UnauthorizedException);
+  });
 
-      expect(proxyService.handleRequestByOrgSlug).toHaveBeenCalledWith(
-        'my-profile',
-        'my-org',
-        mcpRequest,
-        '__unauthenticated__'
-      );
-    });
+  it('returns WWW-Authenticate header on missing token', async () => {
+    const req = createMockRequest();
+    const ctx = createMockExecutionContext(req);
+
+    try {
+      await guard.canActivate(ctx);
+    } catch (error: any) {
+      expect(error.wwwAuthenticate).toContain('resource_metadata=');
+      expect(error.wwwAuthenticate).toContain('resource_metadata_uri=');
+      expect(error.wwwAuthenticate).toContain('/.well-known/oauth-protected-resource');
+    }
+  });
 
-    it('gateway POST request passes __unauthenticated__', async () => {
-      const req = createMockRequest();
-      const mcpRequest: McpRequest = {
-        jsonrpc: '2.0',
-        id: 1,
-        method: 'initialize',
-      };
+  it('rejects invalid Bearer token', async () => {
+    authService.validateMcpToken.mockResolvedValue(null);
+    const req = createMockRequest({ authorization: 'Bearer bad-token' });
+    const ctx = createMockExecutionContext(req);
 
-      await controller.handleGatewayRequest(req, mcpRequest);
+    await expect(guard.canActivate(ctx)).rejects.toThrow(UnauthorizedException);
+    expect(authService.validateMcpToken).toHaveBeenCalledWith('bad-token');
+  });
 
-      expect(proxyService.handleRequest).toHaveBeenCalledWith(
-        'default',
-        mcpRequest,
-        '__unauthenticated__'
-      );
-    });
+  it('allows valid Bearer token and attaches user', async () => {
+    const user: AuthUser = { id: 'user-1', name: 'Test', email: 'test@example.com' };
+    authService.validateMcpToken.mockResolvedValue(user);
+    const req = createMockRequest({ authorization: 'Bearer valid-token' });
+    const ctx = createMockExecutionContext(req);
 
-    it('non-Bearer Authorization header falls back to __unauthenticated__', async () => {
-      const req = createMockRequest({
-        authorization: 'Basic dXNlcjpwYXNz',
-      });
-      const mcpRequest: McpRequest = {
-        jsonrpc: '2.0',
-        id: 1,
-        method: 'tools/list',
-      };
+    const result = await guard.canActivate(ctx);
 
-      await controller.handleOrgMcpRequest(req, 'my-org', 'my-profile', mcpRequest);
+    expect(result).toBe(true);
+    expect(req.user).toEqual(user);
+  });
 
-      expect(authService.validateMcpToken).not.toHaveBeenCalled();
-      expect(proxyService.handleRequestByOrgSlug).toHaveBeenCalledWith(
-        'my-profile',
-        'my-org',
-        mcpRequest,
-        '__unauthenticated__'
-      );
-    });
+  it('accepts access_token query param (SSE fallback)', async () => {
+    const user: AuthUser = { id: 'user-1', name: 'Test', email: 'test@example.com' };
+    authService.validateMcpToken.mockResolvedValue(user);
+    const req = createMockRequest({}, { access_token: 'sse-token' });
+    const ctx = createMockExecutionContext(req);
+
+    const result = await guard.canActivate(ctx);
+
+    expect(result).toBe(true);
+    expect(authService.validateMcpToken).toHaveBeenCalledWith('sse-token');
   });
+});
 
-  // ────────────────────────────────────────────────
-  // Authenticated access with Bearer tokens
-  // ────────────────────────────────────────────────
-
-  describe('authenticated access with Bearer tokens', () => {
-    const validUser: AuthUser = {
-      id: 'user-1',
-      name: 'Token User',
-      email: 'token@example.com',
-    };
-
-    beforeEach(() => {
-      authService = createMockAuthService();
-      proxyService = createMockProxyService();
-      settingsService = createMockSettingsService();
-      eventEmitter = createMockEventEmitter();
-
-      controller = new ProxyController(
-        proxyService as unknown as ProxyService,
-        settingsService as unknown as SettingsService,
-        eventEmitter as unknown as EventEmitter2,
-        authService as unknown as AuthService
-      );
-    });
+// ────────────────────────────────────────────────
+// Proxy controller auth tests
+// ────────────────────────────────────────────────
 
-    it('valid Bearer token resolves to authenticated user for org-scoped request', async () => {
-      authService.validateMcpToken.mockResolvedValue(validUser);
-      const req = createMockRequest({
-        authorization: 'Bearer valid-mcp-token',
-      });
-      const mcpRequest: McpRequest = {
-        jsonrpc: '2.0',
-        id: 1,
-        method: 'tools/list',
-      };
+describe('Proxy controller auth', () => {
+  let controller: InstanceType<typeof ProxyController>;
+  let proxyService: ReturnType<typeof createMockProxyService>;
+  let settingsService: ReturnType<typeof createMockSettingsService>;
+  let eventEmitter: ReturnType<typeof createMockEventEmitter>;
 
-      await controller.handleOrgMcpRequest(req, 'my-org', 'my-profile', mcpRequest);
+  beforeEach(() => {
+    proxyService = createMockProxyService();
+    settingsService = createMockSettingsService();
+    eventEmitter = createMockEventEmitter();
 
-      expect(authService.validateMcpToken).toHaveBeenCalledWith('valid-mcp-token');
-      expect(proxyService.handleRequestByOrgSlug).toHaveBeenCalledWith(
-        'my-profile',
-        'my-org',
-        mcpRequest,
-        'user-1'
-      );
-    });
+    controller = new ProxyController(
+      proxyService as unknown as ProxyService,
+      settingsService as unknown as SettingsService,
+      eventEmitter as unknown as EventEmitter2
+    );
+  });
 
-    it('invalid Bearer token throws UnauthorizedException', async () => {
-      authService.validateMcpToken.mockResolvedValue(null);
-      const req = createMockRequest({
-        authorization: 'Bearer invalid-token',
-      });
-      const mcpRequest: McpRequest = {
-        jsonrpc: '2.0',
-        id: 1,
-        method: 'tools/list',
-      };
-
-      await expect(
-        controller.handleOrgMcpRequest(req, 'my-org', 'my-profile', mcpRequest)
-      ).rejects.toThrow(UnauthorizedException);
-    });
+  describe('guard-authenticated user passthrough', () => {
+    it('uses req.user set by McpOAuthGuard', async () => {
+      const guardUser: AuthUser = { id: 'guard-user', name: 'Guard', email: 'g@test.com' };
+      const req = createMockRequest({ authorization: 'Bearer some-token' });
+      (req as any).user = guardUser;
 
-    it('no Authorization header falls back to __unauthenticated__', async () => {
-      const req = createMockRequest();
-      const mcpRequest: McpRequest = {
-        jsonrpc: '2.0',
-        id: 1,
-        method: 'tools/list',
-      };
+      const mcpRequest: McpRequest = { jsonrpc: '2.0', id: 1, method: 'tools/list' };
 
       await controller.handleOrgMcpRequest(req, 'my-org', 'my-profile', mcpRequest);
 
-      expect(authService.validateMcpToken).not.toHaveBeenCalled();
       expect(proxyService.handleRequestByOrgSlug).toHaveBeenCalledWith(
         'my-profile',
         'my-org',
         mcpRequest,
-        '__unauthenticated__'
+        'guard-user'
       );
     });
   });
 
-  // ────────────────────────────────────────────────
-  // Org-scoped profile lookup through proxy
-  // ────────────────────────────────────────────────
-
   describe('org-scoped profile lookup', () => {
     const userA: AuthUser = { id: 'user-a', name: 'User A', email: 'a@test.com' };
     const userB: AuthUser = { id: 'user-b', name: 'User B', email: 'b@test.com' };
 
-    beforeEach(() => {
-      authService = createMockAuthService();
-      proxyService = createMockProxyService();
-      settingsService = createMockSettingsService();
-      eventEmitter = createMockEventEmitter();
-
-      controller = new ProxyController(
-        proxyService as unknown as ProxyService,
-        settingsService as unknown as SettingsService,
-        eventEmitter as unknown as EventEmitter2,
-        authService as unknown as AuthService
-      );
-    });
-
     it('org slug and user are passed through to proxy service', async () => {
-      authService.validateMcpToken.mockResolvedValue(userA);
       const req = createMockRequest({ authorization: 'Bearer token-a' });
+      (req as any).user = userA;
       const mcpRequest: McpRequest = { jsonrpc: '2.0', id: 1, method: 'tools/list' };
 
       await controller.handleOrgMcpRequest(req, 'org-a', 'user-a-profile', mcpRequest);
@@ -284,16 +237,14 @@ describe('Proxy controller auth', () => {
     });
 
     it('different users get different userId passed to proxy', async () => {
-      // First request from User A
-      authService.validateMcpToken.mockResolvedValue(userA);
       const reqA = createMockRequest({ authorization: 'Bearer token-a' });
+      (reqA as any).user = userA;
       const mcpReq: McpRequest = { jsonrpc: '2.0', id: 1, method: 'tools/list' };
 
       await controller.handleOrgMcpRequest(reqA, 'shared-org', 'shared-profile', mcpReq);
 
-      // Second request from User B
-      authService.validateMcpToken.mockResolvedValue(userB);
       const reqB = createMockRequest({ authorization: 'Bearer token-b' });
+      (reqB as any).user = userB;
 
       await controller.handleOrgMcpRequest(reqB, 'shared-org', 'shared-profile', mcpReq);
 
@@ -314,10 +265,10 @@ describe('Proxy controller auth', () => {
     });
 
     it('gateway endpoint uses default profile with user scoping', async () => {
-      authService.validateMcpToken.mockResolvedValue(userA);
       settingsService.getDefaultGatewayProfile.mockResolvedValue('my-default');
 
       const req = createMockRequest({ authorization: 'Bearer token-a' });
+      (req as any).user = userA;
       const mcpRequest: McpRequest = { jsonrpc: '2.0', id: 1, method: 'tools/list' };
 
       await controller.handleGatewayRequest(req, mcpRequest);
@@ -326,13 +277,13 @@ describe('Proxy controller auth', () => {
     });
 
     it('gateway wraps NotFoundException with descriptive message', async () => {
-      authService.validateMcpToken.mockResolvedValue(userA);
       settingsService.getDefaultGatewayProfile.mockResolvedValue('missing-profile');
       proxyService.handleRequest.mockRejectedValue(
         new NotFoundException('Profile "missing-profile" not found')
       );
 
       const req = createMockRequest({ authorization: 'Bearer token-a' });
+      (req as any).user = userA;
       const mcpRequest: McpRequest = { jsonrpc: '2.0', id: 1, method: 'tools/list' };
 
       await expect(controller.handleGatewayRequest(req, mcpRequest)).rejects.toThrow(

package/src/__tests__/unit/auth.guard.test.ts

@@ -2,7 +2,7 @@
  * Tests for AuthGuard
  */
 
-import { ExecutionContext, UnauthorizedException } from '@nestjs/common';
+import { ExecutionContext, ForbiddenException, UnauthorizedException } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { AuthGuard } from '../../modules/auth/auth.guard.js';
@@ -52,7 +52,7 @@ describe('AuthGuard', () => {
 
   it('should attach user and session when valid session exists', async () => {
     const mockUser = { id: 'user-1', name: 'Test', email: 'test@example.com', image: null };
-    const mockSession = { id: 'sess-1', userId: 'user-1', activeOrganizationId: null };
+    const mockSession = { id: 'sess-1', userId: 'user-1', activeOrganizationId: 'org-1' };
     authService.getSession.mockResolvedValue({ user: mockUser, session: mockSession });
 
     const ctx = createMockExecutionContext({ cookie: 'session=abc' });
@@ -63,4 +63,14 @@ describe('AuthGuard', () => {
     expect(request.user).toEqual(mockUser);
     expect(request.sessionData).toEqual(mockSession);
   });
+
+  it('should throw ForbiddenException when session has no active organization', async () => {
+    const mockUser = { id: 'user-1', name: 'Test', email: 'test@example.com', image: null };
+    const mockSession = { id: 'sess-1', userId: 'user-1', activeOrganizationId: null };
+    authService.getSession.mockResolvedValue({ user: mockUser, session: mockSession });
+
+    const ctx = createMockExecutionContext({ cookie: 'session=abc' });
+
+    await expect(guard.canActivate(ctx)).rejects.toThrow(ForbiddenException);
+  });
 });

package/src/common/filters/all-exceptions.filter.ts

@@ -23,6 +23,10 @@ interface ErrorResponse {
   requestId?: string;
 }
 
+type McpHttpException = HttpException & {
+  wwwAuthenticate?: string;
+};
+
 @Catch()
 export class AllExceptionsFilter implements ExceptionFilter {
   private readonly logger = new Logger(AllExceptionsFilter.name);
@@ -72,6 +76,13 @@ export class AllExceptionsFilter implements ExceptionFilter {
       errorResponse.requestId = requestId;
     }
 
+    // Set WWW-Authenticate header for MCP OAuth errors (RFC 9728)
+    const mcpException = exception instanceof HttpException ? (exception as McpHttpException) : null;
+    if (mcpException?.wwwAuthenticate) {
+      response.setHeader('WWW-Authenticate', mcpException.wwwAuthenticate);
+      response.setHeader('Access-Control-Expose-Headers', 'WWW-Authenticate');
+    }
+
     response.status(status).json(errorResponse);
   }
 }

package/src/main.ts

@@ -10,11 +10,17 @@ import { ConfigService } from '@nestjs/config';
 import { NestFactory } from '@nestjs/core';
 import { toNodeHandler } from 'better-auth/node';
 import compression from 'compression';
+import type { NextFunction, Request, Response } from 'express';
 import helmet from 'helmet';
 import { AppModule } from './app.module.js';
 import { AllExceptionsFilter } from './common/filters/all-exceptions.filter.js';
 import { LoggingInterceptor } from './common/interceptors/logging.interceptor.js';
 import { AuthService } from './modules/auth/auth.service.js';
+import {
+  createMcpProtectedResourceMetadata,
+  resolvePublicAuthBaseUrl,
+  resolvePublicBackendOrigin,
+} from './modules/auth/mcp-oauth.utils.js';
 
 async function bootstrap() {
   // Determine log levels from environment
@@ -72,12 +78,37 @@ async function bootstrap() {
   const authService = app.get(AuthService);
   const expressApp = app.getHttpAdapter().getInstance();
 
-  const lazyAuthHandler = (req: any, res: any, next: any) => {
+  const lazyAuthHandler = (req: Request, res: Response, next: NextFunction) => {
     const auth = authService.getAuth();
     if (!auth) return next();
     toNodeHandler(auth)(req, res);
   };
 
+  expressApp.get('/.well-known/oauth-protected-resource', (_req: Request, res: Response) => {
+    res.json(createMcpProtectedResourceMetadata(configService));
+  });
+
+  // RFC 8414 – OAuth 2.0 Authorization Server Metadata
+  // MCP clients fetch this to discover the correct DCR endpoint (/api/auth/mcp/register)
+  // instead of falling back to the root /register which returns 404.
+  expressApp.get('/.well-known/oauth-authorization-server', (_req: Request, res: Response) => {
+    const backendOrigin = resolvePublicBackendOrigin(configService);
+    const authBaseUrl = resolvePublicAuthBaseUrl(configService);
+
+    res.json({
+      issuer: backendOrigin,
+      authorization_endpoint: `${authBaseUrl}/mcp/authorize`,
+      token_endpoint: `${authBaseUrl}/mcp/token`,
+      registration_endpoint: `${authBaseUrl}/mcp/register`,
+      jwks_uri: `${authBaseUrl}/mcp/jwks`,
+      response_types_supported: ['code'],
+      grant_types_supported: ['authorization_code', 'refresh_token'],
+      token_endpoint_auth_methods_supported: ['none'],
+      code_challenge_methods_supported: ['S256'],
+      scopes_supported: ['openid', 'profile', 'email', 'offline_access'],
+    });
+  });
+
   expressApp.all('/api/auth/*splat', lazyAuthHandler);
   expressApp.all('/.well-known/*splat', lazyAuthHandler);
 

package/src/modules/auth/auth.config.ts

@@ -7,10 +7,12 @@
  */
 
 import type { PrismaClient } from '@dxheroes/local-mcp-database/generated/prisma';
+import { ConfigService } from '@nestjs/config';
 import { betterAuth } from 'better-auth';
 import { prismaAdapter } from 'better-auth/adapters/prisma';
 import { mcp } from 'better-auth/plugins';
 import { organization } from 'better-auth/plugins/organization';
+import { resolveMcpLoginPageUrl } from './mcp-oauth.utils.js';
 
 /**
  * Auth wrapper — simplified interface to avoid exporting Better Auth's deep generic types.
@@ -37,6 +39,7 @@ function toSlug(name: string): string {
 
 export function createAuth(prisma: PrismaClient): AuthInstance {
   const hasGoogle = !!process.env.GOOGLE_CLIENT_ID && !!process.env.GOOGLE_CLIENT_SECRET;
+  const configService = new ConfigService();
 
   const auth = betterAuth({
     basePath: '/api/auth',
@@ -106,7 +109,7 @@ export function createAuth(prisma: PrismaClient): AuthInstance {
     plugins: [
       organization(),
       mcp({
-        loginPage: '/sign-in',
+        loginPage: resolveMcpLoginPageUrl(configService),
       }),
     ],
   });

package/src/modules/auth/auth.module.ts

@@ -7,10 +7,11 @@
 import { Global, Module } from '@nestjs/common';
 import { AuthGuard } from './auth.guard.js';
 import { AuthService } from './auth.service.js';
+import { McpOAuthGuard } from './mcp-oauth.guard.js';
 
 @Global()
 @Module({
-  providers: [AuthService, AuthGuard],
-  exports: [AuthService, AuthGuard],
+  providers: [AuthService, AuthGuard, McpOAuthGuard],
+  exports: [AuthService, AuthGuard, McpOAuthGuard],
 })
 export class AuthModule {}

package/src/modules/auth/auth.service.ts

@@ -101,13 +101,13 @@ export class AuthService implements OnModuleInit {
   async validateMcpToken(bearerToken: string): Promise<AuthUser | null> {
     try {
       const tokenRecord = await this.prisma.oauthAccessToken.findFirst({
-        where: { token: bearerToken },
+        where: { accessToken: bearerToken },
       });
 
       if (!tokenRecord || !tokenRecord.userId) return null;
 
       // Check expiration
-      if (tokenRecord.expiresAt && new Date(tokenRecord.expiresAt) < new Date()) {
+      if (new Date(tokenRecord.accessTokenExpiresAt) < new Date()) {
         return null;
       }
 

package/src/modules/auth/mcp-oauth.guard.ts

@@ -0,0 +1,75 @@
+/**
+ * MCP OAuth Guard
+ *
+ * Enforces OAuth 2.1 Bearer token authentication on MCP proxy endpoints.
+ * Validates Bearer tokens and returns RFC 9728-compliant
+ * WWW-Authenticate headers to guide MCP clients through OAuth discovery.
+ */
+
+import {
+  CanActivate,
+  ExecutionContext,
+  Injectable,
+  UnauthorizedException,
+} from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import type { Request } from 'express';
+import { AuthService } from './auth.service.js';
+import { createMcpWwwAuthenticateHeader } from './mcp-oauth.utils.js';
+
+type McpUnauthorizedException = UnauthorizedException & {
+  wwwAuthenticate?: string;
+};
+
+@Injectable()
+export class McpOAuthGuard implements CanActivate {
+  constructor(
+    private readonly authService: AuthService,
+    private readonly configService: ConfigService
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const request = context.switchToHttp().getRequest<Request>();
+    const token = this.extractToken(request);
+
+    if (!token) {
+      throw this.createUnauthorizedError('Bearer token required');
+    }
+
+    const user = await this.authService.validateMcpToken(token);
+    if (!user) {
+      throw this.createUnauthorizedError('Invalid or expired MCP OAuth token');
+    }
+
+    request.user = user;
+    return true;
+  }
+
+  /**
+   * Extract Bearer token from Authorization header or access_token query param (SSE fallback).
+   */
+  private extractToken(request: Request): string | null {
+    const authHeader = request.headers.authorization;
+    if (authHeader?.startsWith('Bearer ')) {
+      return authHeader.slice(7);
+    }
+
+    // SSE connections may pass token as query parameter
+    const queryToken = request.query.access_token;
+    if (typeof queryToken === 'string' && queryToken.length > 0) {
+      return queryToken;
+    }
+
+    return null;
+  }
+
+  /**
+   * Create UnauthorizedException with RFC 9728 WWW-Authenticate header
+   * pointing MCP clients to the protected resource metadata.
+   */
+  private createUnauthorizedError(message: string): UnauthorizedException {
+    const error = new UnauthorizedException(message) as McpUnauthorizedException;
+    error.wwwAuthenticate = createMcpWwwAuthenticateHeader(this.configService);
+    return error;
+  }
+}