chore(web): Validate OAuth scopes for MCP access

CHANGELOG.md

@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - [EE] Fixed Ask Sourcebot mermaid diagrams overflowing their container by contain-fitting them to both width and height, and made revealing a diagram from the answer jump it into view instantly to avoid over/undershooting. [#1373](https://github.com/sourcebot-dev/sourcebot/pull/1373)
 - Verified GitHub review webhook deliveries before processing them. [#1378](https://github.com/sourcebot-dev/sourcebot/pull/1378)
 - Passed Zoekt index parameters via argv to preserve revision names with punctuation. [#1376](https://github.com/sourcebot-dev/sourcebot/pull/1376)
+- [EE] Validated OAuth bearer token scopes before allowing access to the Sourcebot MCP resource server. [#1396](https://github.com/sourcebot-dev/sourcebot/pull/1396)
 
 ## [5.0.4] - 2026-06-18
 

packages/db/prisma/migrations/20260630005335_add_oauth_scope_to_authorization_code/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "OAuthAuthorizationCode" ADD COLUMN     "scope" TEXT NOT NULL DEFAULT '';

packages/db/prisma/schema.prisma

@@ -732,6 +732,7 @@ model OAuthAuthorizationCode {
   user          User        @relation(fields: [userId], references: [id], onDelete: Cascade)
   redirectUri   String
   codeChallenge String // BASE64URL(SHA-256(codeVerifier))
+  scope         String      @default("")
   resource      String? // RFC 8707: canonical URI of the target resource server
   dpopJkt       String? // RFC 9449: DPoP JWK SHA-256 thumbprint binding
   expiresAt     DateTime

packages/web/package.json

@@ -11,7 +11,8 @@
     "openapi:generate": "tsx tools/generateOpenApi.ts",
     "generate:protos": "proto-loader-gen-types --includeComments --longs=Number --enums=String --defaults --oneofs --grpcLib=@grpc/grpc-js --keepCase --includeDirs=../../vendor/zoekt/grpc/protos --outDir=src/proto zoekt/webserver/v1/webserver.proto zoekt/webserver/v1/query.proto",
     "dev:emails": "email dev --dir ./src/emails",
-    "tool:decrypt-jwe": "tsx tools/decryptJWE.ts"
+    "tool:decrypt-jwe": "tsx tools/decryptJWE.ts",
+    "tool:oauth-flow": "tsx tools/oauthFlow.ts"
   },
   "dependencies": {
     "@ai-sdk/amazon-bedrock": "^4.0.94",

packages/web/src/__mocks__/prisma.ts

@@ -17,7 +17,6 @@ export const MOCK_ORG: Org = {
     updatedAt: new Date(),
     isOnboarded: true,
     imageUrl: null,
-    metadata: null,
     memberApprovalRequired: false,
     isCredentialsLoginEnabled: true,
     isEmailCodeLoginEnabled: false,

packages/web/src/app/api/(server)/ee/.well-known/oauth-authorization-server/route.ts

@@ -1,6 +1,6 @@
 import { oauthApiHandler } from '@/ee/features/oauth/apiHandler';
 import { env } from '@sourcebot/shared';
-import { OAUTH_NOT_SUPPORTED_ERROR_MESSAGE } from '@/ee/features/oauth/constants';
+import { OAUTH_NOT_SUPPORTED_ERROR_MESSAGE, SOURCEBOT_OAUTH_SCOPES } from '@/ee/features/oauth/constants';
 import { hasEntitlement } from '@/lib/entitlements';
 import { SUPPORTED_DPOP_SIGNING_ALGS } from '@/ee/features/oauth/dpop';
 
@@ -25,6 +25,7 @@ export const GET = oauthApiHandler(async () => {
         revocation_endpoint: `${issuer}/api/ee/oauth/revoke`,
         response_types_supported: ['code'],
         grant_types_supported: ['authorization_code', 'refresh_token'],
+        scopes_supported: SOURCEBOT_OAUTH_SCOPES,
         code_challenge_methods_supported: ['S256'],
         token_endpoint_auth_methods_supported: ['none'],
         dpop_signing_alg_values_supported: SUPPORTED_DPOP_SIGNING_ALGS,

packages/web/src/app/api/(server)/ee/.well-known/oauth-protected-resource/[...path]/route.ts

@@ -1,7 +1,7 @@
 import { env } from '@sourcebot/shared';
 import { hasEntitlement } from '@/lib/entitlements';
 import { NextRequest } from 'next/server';
-import { OAUTH_NOT_SUPPORTED_ERROR_MESSAGE } from '@/ee/features/oauth/constants';
+import { OAUTH_NOT_SUPPORTED_ERROR_MESSAGE, SOURCEBOT_OAUTH_SCOPES } from '@/ee/features/oauth/constants';
 import { oauthApiHandler } from '@/ee/features/oauth/apiHandler';
 
 // RFC 9728: OAuth 2.0 Protected Resource Metadata (path-specific form)
@@ -37,6 +37,7 @@ export const GET = oauthApiHandler(async (_request: NextRequest, { params }: { p
         authorization_servers: [
             issuer
         ],
+        scopes_supported: SOURCEBOT_OAUTH_SCOPES,
         bearer_methods_supported: ['header'],
     });
 });

packages/web/src/app/api/(server)/ee/mcp/route.ts

@@ -12,6 +12,7 @@ import { sew } from "@/middleware/sew";
 import { apiHandler } from '@/lib/apiHandler';
 import { env } from '@sourcebot/shared';
 import { hasEntitlement } from '@/lib/entitlements';
+import { SOURCEBOT_OAUTH_SCOPES } from '@/ee/features/oauth/constants';
 
 // On 401, tell MCP clients where to find the OAuth protected resource metadata (RFC 9728)
 // so they can discover the authorization server and initiate the authorization code flow.
@@ -20,20 +21,35 @@ import { hasEntitlement } from '@/lib/entitlements';
 // @see: https://datatracker.ietf.org/doc/html/rfc9728
 async function mcpErrorResponse(error: ServiceError): Promise<Response> {
     const response = serviceErrorResponse(error);
-    if (error.statusCode === StatusCodes.UNAUTHORIZED && await hasEntitlement('oauth')) {
-        const issuer = env.AUTH_URL.replace(/\/$/, '');
-        response.headers.append(
-            'WWW-Authenticate',
-            `Bearer realm="Sourcebot", resource_metadata_uri="${issuer}/.well-known/oauth-protected-resource/api/mcp"`
-        );
-        response.headers.append(
-            'WWW-Authenticate',
-            `DPoP realm="Sourcebot", resource_metadata_uri="${issuer}/.well-known/oauth-protected-resource/api/mcp"`
-        );
+    if (
+        (error.statusCode === StatusCodes.UNAUTHORIZED || error.errorCode === ErrorCode.OAUTH_INSUFFICIENT_SCOPE) &&
+        await hasEntitlement('oauth')
+    ) {
+        response.headers.append('WWW-Authenticate', mcpOAuthChallenge('Bearer', error));
+        response.headers.append('WWW-Authenticate', mcpOAuthChallenge('DPoP', error));
     }
     return response;
 }
 
+function mcpOAuthChallenge(scheme: 'Bearer' | 'DPoP', error: ServiceError): string {
+    const issuer = env.AUTH_URL.replace(/\/$/, '');
+    const params = [
+        'realm="Sourcebot"',
+        `resource_metadata_uri="${issuer}/.well-known/oauth-protected-resource/api/mcp"`,
+    ];
+    const scope = SOURCEBOT_OAUTH_SCOPES.join(' ');
+    if (scope) {
+        params.push(`scope="${scope}"`);
+    }
+
+    if (error.errorCode === ErrorCode.OAUTH_INSUFFICIENT_SCOPE) {
+        params.push('error="insufficient_scope"');
+        params.push(`error_description="${error.message}"`);
+    }
+
+    return `${scheme} ${params.join(', ')}`;
+}
+
 // @see: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management
 interface McpSession {
     server: McpServer;

packages/web/src/app/api/(server)/ee/oauth/token/route.ts

@@ -1,6 +1,5 @@
 import { verifyAndExchangeCode, verifyAndRotateRefreshToken } from '@/ee/features/oauth/server';
 import { oauthApiHandler } from '@/ee/features/oauth/apiHandler';
-import { env } from '@sourcebot/shared';
 import { NextRequest } from 'next/server';
 import { OAUTH_NOT_SUPPORTED_ERROR_MESSAGE } from '@/ee/features/oauth/constants';
 import { hasEntitlement } from '@/lib/entitlements';
@@ -77,8 +76,8 @@ export const POST = oauthApiHandler(async (request: NextRequest) => {
             access_token: result.token,
             refresh_token: result.refreshToken,
             token_type: result.dpopJkt ? DPOP_TOKEN_TYPE : 'Bearer',
-            expires_in: env.OAUTH_ACCESS_TOKEN_TTL_SECONDS,
-            scope: '',
+            expires_in: result.expiresIn,
+            scope: result.scope,
         });
     }
 
@@ -110,8 +109,8 @@ export const POST = oauthApiHandler(async (request: NextRequest) => {
             access_token: result.token,
             refresh_token: result.refreshToken,
             token_type: result.dpopJkt ? DPOP_TOKEN_TYPE : 'Bearer',
-            expires_in: env.OAUTH_ACCESS_TOKEN_TTL_SECONDS,
-            scope: '',
+            expires_in: result.expiresIn,
+            scope: result.scope,
         });
     }
 

packages/web/src/app/oauth/authorize/components/consentScreen.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { approveAuthorization, denyAuthorization } from '@/ee/features/oauth/actions';
-import { isPermittedRedirectUrl } from '@/ee/features/oauth/constants';
+import { isPermittedRedirectUrl } from '@/ee/features/oauth/utils';
 import { LoadingButton } from '@/components/ui/loading-button';
 import { isServiceError } from '@/lib/utils';
 import { ClientIcon } from './clientIcon';
@@ -17,6 +17,7 @@ interface ConsentScreenProps {
     clientLogoUri: string | null;
     redirectUri: string;
     codeChallenge: string;
+    requestedScope: string | undefined;
     resource: string | null;
     dpopJkt: string | null;
     state: string | undefined;
@@ -29,6 +30,7 @@ export function ConsentScreen({
     clientLogoUri,
     redirectUri,
     codeChallenge,
+    requestedScope,
     resource,
     dpopJkt,
     state,
@@ -45,7 +47,7 @@ export function ConsentScreen({
     const onApprove = async () => {
         captureEvent('wa_oauth_authorization_approved', { clientId, clientName });
         setPending('approve');
-        const result = await approveAuthorization({ clientId, redirectUri, codeChallenge, resource, dpopJkt, state });
+        const result = await approveAuthorization({ clientId, redirectUri, codeChallenge, requestedScope, resource, dpopJkt, state });
         if (!isServiceError(result)) {
             if (!isPermittedRedirectUrl(result)) {
                 toast({ description: `❌ Redirect URL is not permitted.` });

packages/web/src/app/oauth/authorize/page.tsx

@@ -4,6 +4,7 @@ import { ConsentScreen } from './components/consentScreen';
 import { __unsafePrisma } from '@/prisma';
 import { hasEntitlement } from '@/lib/entitlements';
 import { redirect } from 'next/navigation';
+import { resolveGrantedOAuthScopes } from '@/ee/features/oauth/utils';
 import { isValidDpopJkt } from '@/ee/features/oauth/dpop';
 
 export const dynamic = 'force-dynamic';
@@ -16,6 +17,7 @@ interface AuthorizePageProps {
         code_challenge_method?: string;
         response_type?: string;
         state?: string;
+        scope?: string;
         resource?: string | string[];
         dpop_jkt?: string | string[];
     }>;
@@ -27,7 +29,7 @@ export default async function AuthorizePage({ searchParams }: AuthorizePageProps
     }
 
     const params = await searchParams;
-    const { client_id, redirect_uri, code_challenge, code_challenge_method, response_type, state, resource: _resource, dpop_jkt: _dpopJkt } = params;
+    const { client_id, redirect_uri, code_challenge, code_challenge_method, response_type, state, scope, resource: _resource, dpop_jkt: _dpopJkt } = params;
 
     // RFC 8707 allows multiple resource parameters to indicate a token intended for multiple resources.
     // Sourcebot only supports a single resource (the MCP endpoint), so we take the first value.
@@ -50,6 +52,11 @@ export default async function AuthorizePage({ searchParams }: AuthorizePageProps
         return <ErrorPage message={`Unsupported code_challenge_method: ${code_challenge_method}. Only "S256" is supported.`} />;
     }
 
+    const grantedScopes = resolveGrantedOAuthScopes(scope);
+    if ('error' in grantedScopes) {
+        return <ErrorPage message={grantedScopes.errorDescription} />;
+    }
+
     if (dpopJkt && !isValidDpopJkt(dpopJkt)) {
         return <ErrorPage message="Invalid dpop_jkt parameter." />;
     }
@@ -80,6 +87,7 @@ export default async function AuthorizePage({ searchParams }: AuthorizePageProps
                 clientLogoUri={client.logoUri}
                 redirectUri={redirect_uri!}
                 codeChallenge={code_challenge!}
+                requestedScope={scope}
                 resource={resource ?? null}
                 dpopJkt={dpopJkt ?? null}
                 state={state}

packages/web/src/ee/features/oauth/actions.ts

@@ -4,8 +4,10 @@ import { sew } from "@/middleware/sew";
 import { generateAndStoreAuthCode } from '@/ee/features/oauth/server';
 import { withAuth } from '@/middleware/withAuth';
 import { UNPERMITTED_SCHEMES } from '@/ee/features/oauth/constants';
+import { formatOAuthScopeString, resolveGrantedOAuthScopes } from '@/ee/features/oauth/utils';
 import { isValidDpopJkt } from '@/ee/features/oauth/dpop';
 import { ErrorCode } from '@/lib/errorCodes';
+import type { ServiceError } from '@/lib/serviceError';
 import { StatusCodes } from 'http-status-codes';
 
 export interface ConnectedOauthClient {
@@ -40,31 +42,43 @@ export const approveAuthorization = async ({
     clientId,
     redirectUri,
     codeChallenge,
+    requestedScope,
     resource,
     dpopJkt,
     state,
 }: {
     clientId: string;
     redirectUri: string;
     codeChallenge: string;
+    requestedScope: string | undefined;
     resource: string | null;
     dpopJkt: string | null;
     state: string | undefined;
 }) => sew(() =>
     withAuth(async ({ user }) => {
+        const grantedScopes = resolveGrantedOAuthScopes(requestedScope);
+        if ('error' in grantedScopes) {
+            return {
+                statusCode: StatusCodes.BAD_REQUEST,
+                errorCode: ErrorCode.INVALID_REQUEST_BODY,
+                message: grantedScopes.errorDescription,
+            } satisfies ServiceError;
+        }
+
         if (dpopJkt !== null && !isValidDpopJkt(dpopJkt)) {
             return {
                 statusCode: StatusCodes.BAD_REQUEST,
                 errorCode: ErrorCode.INVALID_QUERY_PARAMS,
                 message: 'Invalid dpop_jkt parameter.',
-            };
+            } satisfies ServiceError;
         }
 
         const rawCode = await generateAndStoreAuthCode({
             clientId,
             userId: user.id,
             redirectUri,
             codeChallenge,
+            scope: formatOAuthScopeString(grantedScopes.scopes),
             resource,
             dpopJkt,
         });

packages/web/src/ee/features/oauth/constants.ts

@@ -3,20 +3,5 @@ export const OAUTH_NOT_SUPPORTED_ERROR_MESSAGE = 'OAuth is not supported on this
 
 export const UNPERMITTED_SCHEMES = /^(javascript|data|vbscript):/i;
 
-/**
- * Returns true if the URL is permitted for use as a redirect target.
- * Allows relative paths starting with /oauth/complete and http(s) URLs.
- * Returns false for dangerous schemes like javascript:, data:, vbscript:.
- */
-export function isPermittedRedirectUrl(url: string): boolean {
-    if (url.startsWith('/oauth/complete')) {
-        return true;
-    }
-
-    try {
-        const parsed = new URL(url);
-        return parsed.protocol === 'http:' || parsed.protocol === 'https:';
-    } catch {
-        return false;
-    }
-}
+export const SOURCEBOT_OAUTH_SCOPES = [] as const;
+export type SourcebotOAuthScope = (typeof SOURCEBOT_OAUTH_SCOPES)[number];