fix(web): always request offline_access for MCP refresh_token grant

Atlassian (and other providers) only honour the `refresh_token` grant when
`offline_access` is included in the authorization scope. The client was
already declaring `refresh_token` in `clientMetadata.grant_types` but never
injecting `offline_access` into `requestedOAuthScopes`, so the /authorize
request was incomplete and Atlassian rejected it.

- `PrismaOAuthClientProvider` now appends `OFFLINE_ACCESS_SCOPE` before
  normalization so it appears in both `clientMetadata.scope` and the
  /authorize request. Injection is unconditional (matching the existing
  behaviour of always declaring `refresh_token`); a comment explains the
  tradeoff vs checking `oauthScopesSupported`.
- `buildMcpOAuthScopeEntries` defaults `offline_access` to enabled when
  present in available scopes so the admin UI reflects what will be sent.
- New `oauthScopeUtils.test.ts` covers the default-enabled behaviour and
  general normalization/filtering helpers.
- Updated `prismaOAuthClientProvider.test.ts` to assert `offline_access` is
  always present and that it is not duplicated when already supplied.
- Added a note to the connectors doc explaining why `offline_access` is
  pre-ticked in the OAuth scopes UI.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: fatmcgav

docs/docs/features/ask/connectors.mdx

@@ -80,6 +80,10 @@ Owners can change connector scopes at any time from **Settings → Workspace →
 Changing connector scopes requires all users to re-authenticate with that connector.
 </Warning>
 
+<Note>
+`offline_access` is enabled by default when offered by the connector. It is required for token refresh, so Sourcebot includes it regardless of whether an admin ticks the box.
+</Note>
+
 ## Tool Permissions
 
 Owners can configure how Ask Sourcebot may use each tool exposed by a connector. Changes take effect immediately and do not require users to re-authenticate.

packages/web/src/ee/features/chat/mcp/oauthScopeUtils.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, test } from 'vitest';
+import {
+    buildMcpOAuthScopeEntries,
+    normalizeMcpRequestedOAuthScopes,
+    getEnabledMcpOAuthScopeNames,
+} from './oauthScopeUtils';
+
+describe('normalizeMcpRequestedOAuthScopes', () => {
+    test('deduplicates, trims, and sorts scopes', () => {
+        expect(normalizeMcpRequestedOAuthScopes([' repo ', 'read:user', 'repo'])).toEqual([
+            'read:user',
+            'repo',
+        ]);
+    });
+
+    test('returns an empty array for empty input', () => {
+        expect(normalizeMcpRequestedOAuthScopes([])).toEqual([]);
+    });
+
+    test('filters blank strings', () => {
+        expect(normalizeMcpRequestedOAuthScopes(['', '  ', 'read'])).toEqual(['read']);
+    });
+});
+
+describe('buildMcpOAuthScopeEntries', () => {
+    test('enables scopes that are in requestedOAuthScopes', () => {
+        const entries = buildMcpOAuthScopeEntries({
+            availableOAuthScopes: ['read', 'write'],
+            requestedOAuthScopes: ['read'],
+        });
+
+        expect(entries).toEqual([
+            { scope: 'read', enabled: true },
+            { scope: 'write', enabled: false },
+        ]);
+    });
+
+    test('enables offline_access by default when present in available scopes', () => {
+        const entries = buildMcpOAuthScopeEntries({
+            availableOAuthScopes: ['offline_access', 'read'],
+            requestedOAuthScopes: ['read'],
+        });
+
+        expect(entries).toEqual([
+            { scope: 'offline_access', enabled: true },
+            { scope: 'read', enabled: true },
+        ]);
+    });
+
+    test('enables offline_access by default even when not in requestedOAuthScopes', () => {
+        const entries = buildMcpOAuthScopeEntries({
+            availableOAuthScopes: ['offline_access', 'read', 'write'],
+            requestedOAuthScopes: [],
+        });
+
+        expect(entries).toEqual([
+            { scope: 'offline_access', enabled: true },
+            { scope: 'read', enabled: false },
+            { scope: 'write', enabled: false },
+        ]);
+    });
+
+    test('does not add offline_access when it is absent from available scopes', () => {
+        const entries = buildMcpOAuthScopeEntries({
+            availableOAuthScopes: ['read', 'write'],
+            requestedOAuthScopes: [],
+        });
+
+        expect(entries.find((e) => e.scope === 'offline_access')).toBeUndefined();
+    });
+
+    test('merges requested scopes not in available scopes into the output', () => {
+        const entries = buildMcpOAuthScopeEntries({
+            availableOAuthScopes: ['read'],
+            requestedOAuthScopes: ['write'],
+        });
+
+        expect(entries).toEqual([
+            { scope: 'read', enabled: false },
+            { scope: 'write', enabled: true },
+        ]);
+    });
+
+    test('returns sorted, deduplicated entries', () => {
+        const entries = buildMcpOAuthScopeEntries({
+            availableOAuthScopes: ['write', 'read', 'write'],
+            requestedOAuthScopes: ['write', 'write'],
+        });
+
+        expect(entries).toEqual([
+            { scope: 'read', enabled: false },
+            { scope: 'write', enabled: true },
+        ]);
+    });
+});
+
+describe('getEnabledMcpOAuthScopeNames', () => {
+    test('returns only enabled scopes, sorted and deduplicated', () => {
+        const scopes = getEnabledMcpOAuthScopeNames([
+            { scope: 'write', enabled: false },
+            { scope: 'read', enabled: true },
+            { scope: 'offline_access', enabled: true },
+        ]);
+
+        expect(scopes).toEqual(['offline_access', 'read']);
+    });
+
+    test('returns an empty array when no scopes are enabled', () => {
+        const scopes = getEnabledMcpOAuthScopeNames([
+            { scope: 'read', enabled: false },
+        ]);
+
+        expect(scopes).toEqual([]);
+    });
+});

packages/web/src/ee/features/chat/mcp/oauthScopeUtils.ts

@@ -2,6 +2,10 @@ import type { McpServerOAuthScopeEntry } from './types';
 
 export const OAUTH_SCOPE_TOKEN_REGEX = /^[\x21\x23-\x5B\x5D-\x7E]+$/;
 
+// Required for the refresh_token grant that all clients declare. Providers such as
+// Atlassian only honour that grant when this scope is included in the authorization request.
+export const OFFLINE_ACCESS_SCOPE = 'offline_access';
+
 export function normalizeMcpRequestedOAuthScopes(oauthScopes: string[]): string[] {
     return [...new Set(oauthScopes.map((scope) => scope.trim()).filter(Boolean))]
         .sort();
@@ -50,7 +54,9 @@ export function buildMcpOAuthScopeEntries({
 
     return normalizedAvailableOAuthScopes.map((scope) => ({
         scope,
-        enabled: requestedScopeSet.has(scope),
+        // offline_access is enabled by default because all clients declare the refresh_token
+        // grant; an admin who leaves it unticked would produce a broken authorization request.
+        enabled: scope === OFFLINE_ACCESS_SCOPE || requestedScopeSet.has(scope),
     }));
 }
 

packages/web/src/ee/features/chat/mcp/prismaOAuthClientProvider.test.ts

@@ -79,18 +79,26 @@ describe('PrismaOAuthClientProvider modes', () => {
 });
 
 describe('PrismaOAuthClientProvider client metadata', () => {
-    test('omits scope when no scopes were requested', () => {
+    test('always includes offline_access even when no scopes were requested', () => {
         const provider = createProvider();
 
-        expect(provider.clientMetadata.scope).toBeUndefined();
+        expect(provider.clientMetadata.scope).toBe('offline_access');
     });
 
-    test('includes normalized requested scopes', () => {
+    test('includes offline_access alongside normalized requested scopes', () => {
         const provider = createProvider(createPrismaMock(), {
             requestedOAuthScopes: [' repo ', 'read:user', 'repo'],
         });
 
-        expect(provider.clientMetadata.scope).toBe('read:user repo');
+        expect(provider.clientMetadata.scope).toBe('offline_access read:user repo');
+    });
+
+    test('does not duplicate offline_access when already present in requested scopes', () => {
+        const provider = createProvider(createPrismaMock(), {
+            requestedOAuthScopes: ['offline_access', 'read:user'],
+        });
+
+        expect(provider.clientMetadata.scope).toBe('offline_access read:user');
     });
 });
 

packages/web/src/ee/features/chat/mcp/prismaOAuthClientProvider.ts

@@ -9,7 +9,7 @@ import { McpServerClientInfoSource, type PrismaClient } from '@sourcebot/db';
 import { encryptOAuthToken, decryptOAuthToken, createLogger } from '@sourcebot/shared';
 import { __unsafePrisma } from '@/prisma';
 import { createMcpOAuthState } from './mcpOAuthReturnTo';
-import { normalizeMcpRequestedOAuthScopes } from './oauthScopeUtils';
+import { normalizeMcpRequestedOAuthScopes, OFFLINE_ACCESS_SCOPE } from './oauthScopeUtils';
 
 type McpOAuthPrismaClient = Pick<PrismaClient, 'mcpServer' | 'userMcpServer'>;
 const logger = createLogger('mcp-oauth-client-provider');
@@ -113,7 +113,16 @@ export class PrismaOAuthClientProvider implements OAuthClientProvider {
     this.userId = userId;
     this.callbackUrl = callbackUrl;
     this.callbackReturnTo = callbackReturnTo;
-    this.requestedOAuthScopes = normalizeMcpRequestedOAuthScopes(requestedOAuthScopes);
+    // offline_access is always injected because every client declares the refresh_token grant
+    // and providers such as Atlassian reject /authorize when the grant is declared but
+    // offline_access is absent. We inject unconditionally rather than checking the provider's
+    // advertised scopes because oauthScopesSupported is not plumbed through to this constructor;
+    // the tradeoff (a benign unknown-scope rejection on strict providers) is the same as the
+    // existing behaviour of always declaring refresh_token.
+    this.requestedOAuthScopes = normalizeMcpRequestedOAuthScopes([
+        ...requestedOAuthScopes,
+        OFFLINE_ACCESS_SCOPE,
+    ]);
 
     if (allowClientRegistration) {
       this.saveClientInformation = async (info: OAuthClientInformation) => {