@dxheroes/local-mcp-backend 0.9.2 → 0.11.0

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
@@ -34,6 +40,10 @@ async function bootstrap() {
 
   // Security
   app.use(helmet());
+  app.use((_req: Request, res: Response, next: NextFunction) => {
+    res.setHeader('X-Robots-Tag', 'noindex, nofollow');
+    next();
+  });
   app.use(compression());
 
   // CORS
@@ -72,12 +82,56 @@ async function bootstrap() {
   const authService = app.get(AuthService);
   const expressApp = app.getHttpAdapter().getInstance();
 
-  const lazyAuthHandler = (req: any, res: any, next: any) => {
+  const lazyAuthHandler = async (req: Request, res: Response, next: NextFunction) => {
     const auth = authService.getAuth();
     if (!auth) return next();
-    toNodeHandler(auth)(req, res);
+    try {
+      await toNodeHandler(auth)(req, res);
+    } catch (error: unknown) {
+      const isPrismaNotFound =
+        error instanceof Error &&
+        'code' in error &&
+        (error as { code: string }).code === 'P2025';
+      if (isPrismaNotFound) {
+        // Stale session cookie — clear it and return 401
+        res.clearCookie('better-auth.session_token');
+        res.clearCookie('better-auth.session_token.sig');
+        if (!res.headersSent) {
+          res.status(401).json({ error: 'Session expired' });
+        }
+        return;
+      }
+      if (!res.headersSent) {
+        res.status(500).json({ error: 'Internal server error' });
+      }
+    }
   };
 
+  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

@@ -1,16 +1,19 @@
 /**
  * Better Auth Configuration
  *
- * Configures Better Auth with Prisma adapter, email+password (always),
- * optional Google OAuth, Organization plugin, and MCP OAuth plugin.
+ * Configures Better Auth with Prisma adapter, email+password (toggleable via
+ * AUTH_EMAIL_PASSWORD env var), optional Google OAuth, Organization plugin,
+ * and MCP OAuth plugin.
  * Auto-creates a default organization on user signup.
  */
 
 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 +40,8 @@ function toSlug(name: string): string {
 
 export function createAuth(prisma: PrismaClient): AuthInstance {
   const hasGoogle = !!process.env.GOOGLE_CLIENT_ID && !!process.env.GOOGLE_CLIENT_SECRET;
+  const emailPasswordEnabled = process.env.AUTH_EMAIL_PASSWORD !== 'false';
+  const configService = new ConfigService();
 
   const auth = betterAuth({
     basePath: '/api/auth',
@@ -47,7 +52,7 @@ export function createAuth(prisma: PrismaClient): AuthInstance {
       'http://localhost:3000',
     ]),
     database: prismaAdapter(prisma, { provider: 'postgresql' }),
-    emailAndPassword: { enabled: true },
+    emailAndPassword: { enabled: emailPasswordEnabled },
     ...(hasGoogle && {
       socialProviders: {
         google: {
@@ -106,7 +111,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,102 @@
+/**
+ * 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 { type AuthUser, 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);
+
+    // 1. Try Bearer token (MCP clients like Claude Desktop, Cursor, etc.)
+    if (token) {
+      const user = await this.authService.validateMcpToken(token);
+      if (user) {
+        request.user = user;
+        return true;
+      }
+      throw this.createUnauthorizedError('Invalid or expired MCP OAuth token');
+    }
+
+    // 2. Try session cookie (browser UI calling /info endpoints)
+    const session = await this.validateSessionCookie(request);
+    if (session) {
+      request.user = session;
+      return true;
+    }
+
+    // 3. Neither worked — require Bearer token (for MCP client discovery)
+    throw this.createUnauthorizedError('Bearer token required');
+  }
+
+  /**
+   * Attempt to validate session cookie from the request.
+   * Returns the user if a valid session exists, null otherwise.
+   */
+  private async validateSessionCookie(request: Request): Promise<AuthUser | null> {
+    try {
+      const headers = new Headers();
+      for (const [key, value] of Object.entries(request.headers)) {
+        if (value) {
+          headers.set(key, Array.isArray(value) ? value.join(', ') : value);
+        }
+      }
+      const result = await this.authService.getSession(headers);
+      return result?.user ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * 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;
+  }
+}

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

@@ -0,0 +1,80 @@
+import type { ConfigService } from '@nestjs/config';
+
+const DEFAULT_BACKEND_PORT = '3001';
+const DEFAULT_FRONTEND_PORT = '3000';
+
+function trimTrailingSlash(value: string): string {
+  return value.replace(/\/+$/, '');
+}
+
+function swapPort(origin: string, fromPort: string, toPort: string): string {
+  const url = new URL(origin);
+  if (url.port === fromPort) {
+    url.port = toPort;
+  }
+  return trimTrailingSlash(url.origin);
+}
+
+export function resolvePublicBackendOrigin(configService: ConfigService): string {
+  const configuredUrl = configService.get<string>('BETTER_AUTH_URL');
+  if (configuredUrl) {
+    return trimTrailingSlash(new URL(configuredUrl).origin);
+  }
+
+  const port = configService.get<number>('app.port') || Number(DEFAULT_BACKEND_PORT);
+  return `http://localhost:${port}`;
+}
+
+export function resolvePublicAuthBaseUrl(configService: ConfigService): string {
+  return `${resolvePublicBackendOrigin(configService)}/api/auth`;
+}
+
+export function resolveFrontendOrigin(configService: ConfigService): string {
+  const configuredUrl = configService.get<string>('FRONTEND_URL');
+  if (configuredUrl) {
+    return trimTrailingSlash(new URL(configuredUrl).origin);
+  }
+
+  const backendOrigin = resolvePublicBackendOrigin(configService);
+  const backendUrl = new URL(backendOrigin);
+
+  if (backendUrl.port === '9631') {
+    return swapPort(backendOrigin, '9631', '9630');
+  }
+
+  if (backendUrl.port === DEFAULT_BACKEND_PORT) {
+    return swapPort(backendOrigin, DEFAULT_BACKEND_PORT, DEFAULT_FRONTEND_PORT);
+  }
+
+  return trimTrailingSlash(backendUrl.origin);
+}
+
+export function resolveMcpLoginPageUrl(configService: ConfigService): string {
+  return `${resolveFrontendOrigin(configService)}/sign-in`;
+}
+
+export function createMcpProtectedResourceMetadata(configService: ConfigService) {
+  const backendOrigin = resolvePublicBackendOrigin(configService);
+  const authBaseUrl = resolvePublicAuthBaseUrl(configService);
+
+  return {
+    resource: `${backendOrigin}/api/mcp`,
+    authorization_servers: [backendOrigin],
+    bearer_methods_supported: ['header'],
+    scopes_supported: ['openid', 'profile', 'email', 'offline_access'],
+    jwks_uri: `${authBaseUrl}/mcp/jwks`,
+    resource_signing_alg_values_supported: ['RS256', 'none'],
+  };
+}
+
+export function createMcpWwwAuthenticateHeader(configService: ConfigService): string {
+  const resourceMetadataUrl = `${resolvePublicBackendOrigin(
+    configService
+  )}/.well-known/oauth-protected-resource`;
+
+  return [
+    'Bearer',
+    `resource_metadata="${resourceMetadataUrl}"`,
+    `resource_metadata_uri="${resourceMetadataUrl}"`,
+  ].join(' ');
+}

package/src/modules/health/health.controller.ts

@@ -31,7 +31,7 @@ export class HealthController {
   @Get('auth-config')
   getAuthConfig() {
     return {
-      emailAndPassword: true,
+      emailAndPassword: process.env.AUTH_EMAIL_PASSWORD !== 'false',
       google: !!process.env.GOOGLE_CLIENT_ID && !!process.env.GOOGLE_CLIENT_SECRET,
     };
   }

package/src/modules/mcp/mcp.service.ts

@@ -254,11 +254,11 @@ export class McpService {
 
     // For remote_http servers, connect and fetch tools
     if (server.type === 'remote_http') {
-      const config = this.parseConfig(server.config) as { url: string };
+      const config = this.parseConfig(server.config) as { url: string; headers?: Record<string, string> };
       const apiKeyConfig = server.apiKeyConfig ? JSON.parse(server.apiKeyConfig as string) : null;
 
       const remoteServer = new RemoteHttpMcpServer(
-        { url: config.url, transport: 'http' },
+        { url: config.url, transport: 'http', headers: config.headers },
         null,
         apiKeyConfig
       );
@@ -269,11 +269,11 @@ export class McpService {
 
     // For remote_sse servers, connect and fetch tools
     if (server.type === 'remote_sse') {
-      const config = this.parseConfig(server.config) as { url: string };
+      const config = this.parseConfig(server.config) as { url: string; headers?: Record<string, string> };
       const apiKeyConfig = server.apiKeyConfig ? JSON.parse(server.apiKeyConfig as string) : null;
 
       const remoteServer = new RemoteSseMcpServer(
-        { url: config.url, transport: 'sse' },
+        { url: config.url, transport: 'sse', headers: config.headers },
         null,
         apiKeyConfig
       );
@@ -410,14 +410,30 @@ export class McpService {
     }
 
     // For remote_http servers, validate by connecting
+    let oauthRequired = false;
     if (server.type === 'remote_http' && status === 'unknown') {
-      const config = this.parseConfig(server.config) as { url: string };
+      const config = this.parseConfig(server.config) as { url: string; headers?: Record<string, string> };
       const apiKeyConfig = server.apiKeyConfig ? JSON.parse(server.apiKeyConfig as string) : null;
 
+      // Get OAuth token if available, mapping Prisma types to core OAuthToken
+      const oauthToken = server.oauthToken
+        ? {
+            id: server.oauthToken.id,
+            mcpServerId: server.oauthToken.mcpServerId,
+            accessToken: server.oauthToken.accessToken,
+            tokenType: server.oauthToken.tokenType,
+            refreshToken: server.oauthToken.refreshToken ?? undefined,
+            scope: server.oauthToken.scope ?? undefined,
+            expiresAt: server.oauthToken.expiresAt?.getTime(),
+            createdAt: server.oauthToken.createdAt.getTime(),
+            updatedAt: server.oauthToken.updatedAt.getTime(),
+          }
+        : null;
+
       try {
         const remoteServer = new RemoteHttpMcpServer(
-          { url: config.url, transport: 'http' },
-          null,
+          { url: config.url, transport: 'http', headers: config.headers },
+          oauthToken,
           apiKeyConfig
         );
         await remoteServer.initialize();
@@ -427,19 +443,39 @@ export class McpService {
       } catch (error) {
         status = 'error';
         validationError = error instanceof Error ? error.message : 'Unknown error';
-        validationDetails = `Connection failed: ${validationError}`;
+        if (validationError.includes('OAUTH_REQUIRED')) {
+          oauthRequired = true;
+          validationDetails = 'OAuth authentication required. Click "Login with OAuth" to authorize.';
+        } else {
+          validationDetails = `Connection failed: ${validationError}`;
+        }
       }
     }
 
     // For remote_sse servers, validate by connecting
     if (server.type === 'remote_sse' && status === 'unknown') {
-      const config = this.parseConfig(server.config) as { url: string };
+      const config = this.parseConfig(server.config) as { url: string; headers?: Record<string, string> };
       const apiKeyConfig = server.apiKeyConfig ? JSON.parse(server.apiKeyConfig as string) : null;
 
+      // Get OAuth token if available, mapping Prisma types to core OAuthToken
+      const oauthToken = server.oauthToken
+        ? {
+            id: server.oauthToken.id,
+            mcpServerId: server.oauthToken.mcpServerId,
+            accessToken: server.oauthToken.accessToken,
+            tokenType: server.oauthToken.tokenType,
+            refreshToken: server.oauthToken.refreshToken ?? undefined,
+            scope: server.oauthToken.scope ?? undefined,
+            expiresAt: server.oauthToken.expiresAt?.getTime(),
+            createdAt: server.oauthToken.createdAt.getTime(),
+            updatedAt: server.oauthToken.updatedAt.getTime(),
+          }
+        : null;
+
       try {
         const remoteServer = new RemoteSseMcpServer(
-          { url: config.url, transport: 'sse' },
-          null,
+          { url: config.url, transport: 'sse', headers: config.headers },
+          oauthToken,
           apiKeyConfig
         );
         await remoteServer.initialize();
@@ -449,7 +485,12 @@ export class McpService {
       } catch (error) {
         status = 'error';
         validationError = error instanceof Error ? error.message : 'Unknown error';
-        validationDetails = `Connection failed: ${validationError}`;
+        if (validationError.includes('OAUTH_REQUIRED')) {
+          oauthRequired = true;
+          validationDetails = 'OAuth authentication required. Click "Login with OAuth" to authorize.';
+        } else {
+          validationDetails = `Connection failed: ${validationError}`;
+        }
       }
     }
 
@@ -493,6 +534,7 @@ export class McpService {
       hasOAuth,
       requiresApiKey,
       requiresOAuth,
+      oauthRequired,
       isReady,
       status,
       error: validationError,

package/src/modules/oauth/oauth.controller.ts

@@ -4,7 +4,21 @@
  * REST API endpoints for OAuth token management.
  */
 
-import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, Post } from '@nestjs/common';
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpCode,
+  HttpStatus,
+  Logger,
+  Param,
+  Post,
+  Query,
+  Req,
+  Res,
+} from '@nestjs/common';
+import type { Request, Response } from 'express';
 import { SkipOrgCheck } from '../auth/decorators/skip-org-check.decorator.js';
 import { OAuthService } from './oauth.service.js';
 
@@ -36,8 +50,77 @@ interface StoreTokenDto {
 @SkipOrgCheck()
 @Controller('oauth')
 export class OAuthController {
+  private readonly logger = new Logger(OAuthController.name);
+
   constructor(private readonly oauthService: OAuthService) {}
 
+  /**
+   * Start OAuth auto-discovery flow for an MCP server.
+   * Discovers OAuth endpoints via RFC 9728/8414, performs DCR if needed,
+   * and redirects the browser to the authorization server.
+   */
+  @Get('authorize/:serverId')
+  async authorize(
+    @Param('serverId') serverId: string,
+    @Req() req: Request,
+    @Res() res: Response
+  ) {
+    try {
+      const callbackUrl = `${req.protocol}://${req.get('host')}/api/oauth/callback`;
+      const authorizationUrl = await this.oauthService.discoverAndAuthorize(serverId, callbackUrl);
+      res.redirect(authorizationUrl);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      this.logger.error(`OAuth authorize failed for ${serverId}: ${message}`);
+      res.status(400).send(this.renderCallbackPage(false, message));
+    }
+  }
+
+  /**
+   * OAuth callback endpoint. Receives authorization code, exchanges for tokens,
+   * and returns an HTML page that notifies the opener window.
+   */
+  @Get('callback')
+  async callback(
+    @Query('code') code: string,
+    @Query('state') state: string,
+    @Req() req: Request,
+    @Res() res: Response
+  ) {
+    if (!code || !state) {
+      res.status(400).send(this.renderCallbackPage(false, 'Missing code or state parameter'));
+      return;
+    }
+
+    const serverId = state;
+    const callbackUrl = `${req.protocol}://${req.get('host')}/api/oauth/callback`;
+
+    const result = await this.oauthService.handleCallback(serverId, code, callbackUrl);
+    res.status(200).send(this.renderCallbackPage(result.success, result.error));
+  }
+
+  /**
+   * Render an HTML page that posts a message to the opener window and closes itself.
+   */
+  private renderCallbackPage(success: boolean, error?: string): string {
+    const message = JSON.stringify({
+      type: 'oauth-callback',
+      success,
+      error: error || null,
+    });
+    return `<!DOCTYPE html>
+<html><head><title>OAuth ${success ? 'Success' : 'Error'}</title></head>
+<body>
+<p>${success ? 'Authorization successful! This window will close.' : `Error: ${error}`}</p>
+<script>
+  if (window.opener) {
+    window.opener.postMessage(${message}, '*');
+  }
+  setTimeout(function() { window.close(); }, 2000);
+</script>
+</body></html>`;
+  }
+
   /**
    * Start OAuth flow for an MCP server
    */