@dxheroes/local-mcp-backend 0.9.2 → 0.11.0

package/src/__tests__/integration/oauth-authorize-callback.test.ts

@@ -0,0 +1,155 @@
+import { createServer } from 'node:http';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OAuthController } from '../../modules/oauth/oauth.controller.js';
+import { OAuthService } from '../../modules/oauth/oauth.service.js';
+
+function createOAuthServiceMock() {
+  return {
+    discoverAndAuthorize: vi.fn(),
+    handleCallback: vi.fn(),
+  };
+}
+
+describe('OAuth authorize and callback HTTP contract', () => {
+  let close: (() => Promise<void>) | undefined;
+  let oauthService: ReturnType<typeof createOAuthServiceMock>;
+  let baseUrl: string;
+
+  beforeEach(async () => {
+    oauthService = createOAuthServiceMock();
+    const controller = new OAuthController(oauthService as unknown as OAuthService);
+
+    const server = await new Promise<import('node:http').Server>((resolve) => {
+      const listeningServer = createServer(async (req, res) => {
+        const url = new URL(req.url ?? '/', `http://${req.headers.host ?? '127.0.0.1'}`);
+        const request = {
+          protocol: 'http',
+          query: Object.fromEntries(url.searchParams.entries()),
+          get: (headerName: string) => {
+            if (headerName.toLowerCase() === 'host') {
+              return req.headers.host ?? '';
+            }
+            return undefined;
+          },
+        };
+        const response = {
+          redirect(location: string) {
+            res.statusCode = 302;
+            res.setHeader('location', location);
+            res.end();
+          },
+          status(statusCode: number) {
+            res.statusCode = statusCode;
+            return response;
+          },
+          send(body: string) {
+            res.setHeader('content-type', 'text/html; charset=utf-8');
+            res.end(body);
+          },
+        };
+
+        if (req.method === 'GET' && url.pathname.startsWith('/api/oauth/authorize/')) {
+          const serverId = url.pathname.split('/').pop() ?? '';
+          await controller.authorize(serverId, request as never, response as never);
+          return;
+        }
+
+        if (req.method === 'GET' && url.pathname === '/api/oauth/callback') {
+          await controller.callback(
+            typeof request.query.code === 'string' ? request.query.code : '',
+            typeof request.query.state === 'string' ? request.query.state : '',
+            request as never,
+            response as never
+          );
+          return;
+        }
+
+        res.statusCode = 404;
+        res.end();
+      }).listen(0, () => resolve(listeningServer));
+    });
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+      throw new Error('Failed to resolve test server address');
+    }
+
+    close = () =>
+      new Promise<void>((resolve, reject) => {
+        server.close((error) => {
+          if (error) {
+            reject(error);
+            return;
+          }
+          resolve();
+        });
+      });
+    baseUrl = `http://127.0.0.1:${address.port}`;
+  });
+
+  afterEach(async () => {
+    if (close) {
+      await close();
+    }
+  });
+
+  it('redirects authorize requests to the discovered authorization URL', async () => {
+    oauthService.discoverAndAuthorize.mockResolvedValue('https://auth.example.com/authorize?client_id=abc');
+
+    const response = await fetch(`${baseUrl}/api/oauth/authorize/server-1`, {
+      redirect: 'manual',
+    });
+
+    expect(response.status).toBe(302);
+    expect(response.headers.get('location')).toBe('https://auth.example.com/authorize?client_id=abc');
+    expect(oauthService.discoverAndAuthorize).toHaveBeenCalledWith(
+      'server-1',
+      `${baseUrl}/api/oauth/callback`
+    );
+  });
+
+  it('renders an error page when authorize discovery fails', async () => {
+    oauthService.discoverAndAuthorize.mockRejectedValue(new Error('Metadata discovery failed'));
+
+    const response = await fetch(`${baseUrl}/api/oauth/authorize/server-1`);
+    const html = await response.text();
+
+    expect(response.status).toBe(400);
+    expect(html).toContain('Error: Metadata discovery failed');
+  });
+
+  it('rejects callbacks without code or state', async () => {
+    const response = await fetch(`${baseUrl}/api/oauth/callback`);
+    const html = await response.text();
+
+    expect(response.status).toBe(400);
+    expect(html).toContain('Missing code or state parameter');
+  });
+
+  it('renders a success page for valid callbacks', async () => {
+    oauthService.handleCallback.mockResolvedValue({ success: true });
+
+    const response = await fetch(`${baseUrl}/api/oauth/callback?code=auth-code&state=server-1`);
+    const html = await response.text();
+
+    expect(response.status).toBe(200);
+    expect(html).toContain('Authorization successful! This window will close.');
+    expect(oauthService.handleCallback).toHaveBeenCalledWith(
+      'server-1',
+      'auth-code',
+      `${baseUrl}/api/oauth/callback`
+    );
+  });
+
+  it('renders a failure page when callback token exchange fails', async () => {
+    oauthService.handleCallback.mockResolvedValue({
+      success: false,
+      error: 'Token exchange failed',
+    });
+
+    const response = await fetch(`${baseUrl}/api/oauth/callback?code=auth-code&state=server-1`);
+    const html = await response.text();
+
+    expect(response.status).toBe(200);
+    expect(html).toContain('Error: Token exchange failed');
+  });
+});

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,177 @@ 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
-      );
-    });
+  it('accepts session cookie when no Bearer token is present', async () => {
+    const user: AuthUser = { id: 'session-user', name: 'Session', email: 'session@example.com' };
+    authService.getSession.mockResolvedValue({ user, session: { id: 's1', userId: user.id } });
+    const req = createMockRequest({ cookie: 'better-auth.session_token=abc123' });
+    const ctx = createMockExecutionContext(req);
 
-    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',
-      };
+    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(authService.validateMcpToken).toHaveBeenCalledWith('valid-mcp-token');
-      expect(proxyService.handleRequestByOrgSlug).toHaveBeenCalledWith(
-        'my-profile',
-        'my-org',
-        mcpRequest,
-        'user-1'
-      );
-    });
+  it('rejects when neither Bearer token nor session cookie is valid', async () => {
+    authService.getSession.mockResolvedValue(null);
+    const req = createMockRequest({ cookie: 'better-auth.session_token=expired' });
+    const ctx = createMockExecutionContext(req);
 
-    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);
-    });
+    await expect(guard.canActivate(ctx)).rejects.toThrow(UnauthorizedException);
+  });
+
+  it('does not fall through to session cookie when Bearer token is invalid', async () => {
+    const user: AuthUser = { id: 'session-user', name: 'Session', email: 'session@example.com' };
+    authService.validateMcpToken.mockResolvedValue(null);
+    authService.getSession.mockResolvedValue({ user, session: { id: 's1', userId: user.id } });
+    const req = createMockRequest({ authorization: 'Bearer bad-token' });
+    const ctx = createMockExecutionContext(req);
 
-    it('no Authorization header falls back to __unauthenticated__', async () => {
-      const req = createMockRequest();
-      const mcpRequest: McpRequest = {
-        jsonrpc: '2.0',
-        id: 1,
-        method: 'tools/list',
-      };
+    await expect(guard.canActivate(ctx)).rejects.toThrow(UnauthorizedException);
+    expect(authService.getSession).not.toHaveBeenCalled();
+  });
+});
+
+// ────────────────────────────────────────────────
+// Proxy controller auth tests
+// ────────────────────────────────────────────────
+
+describe('Proxy controller auth', () => {
+  let controller: InstanceType<typeof ProxyController>;
+  let proxyService: ReturnType<typeof createMockProxyService>;
+  let settingsService: ReturnType<typeof createMockSettingsService>;
+  let eventEmitter: ReturnType<typeof createMockEventEmitter>;
+
+  beforeEach(() => {
+    proxyService = createMockProxyService();
+    settingsService = createMockSettingsService();
+    eventEmitter = createMockEventEmitter();
+
+    controller = new ProxyController(
+      proxyService as unknown as ProxyService,
+      settingsService as unknown as SettingsService,
+      eventEmitter as unknown as EventEmitter2
+    );
+  });
+
+  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;
+
+      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 +269,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 +297,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 +309,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);
   }
 }