fix(web): reject repository-scoped access tokens in skill tools

Scoped tokens are documented to grant access to selected repositories only,
so the skill tools now reject that principal inside each handler and the MCP
server skips registering them for scoped sessions. The handler check is the
real gate: MCP sessions are keyed by owner, not principal, so a session
created with a full credential can later be driven by a scoped token.

Author: jsourcebot

docs/docs/features/mcp-server.mdx

@@ -457,7 +457,7 @@ Parameters:
 
 Creates a new agent skill: a reusable, named instruction set the user can invoke in Ask Sourcebot as a `/<slug>` slash command or have loaded automatically when a request matches its description. The skill is personal to the authenticated user and enabled immediately. The result includes a link to the skill in **Settings → Skills**.
 
-Requires an authenticated user (API key or OAuth) and the Ask Sourcebot feature. Anonymous sessions do not see this tool.
+Requires an authenticated user (API key or OAuth) and the Ask Sourcebot feature. Anonymous sessions and repository-scoped access tokens cannot use this tool.
 
 Parameters:
 | Name | Required | Description |
@@ -471,7 +471,7 @@ Parameters:
 
 Updates an existing agent skill in place. Omitted content fields keep their current values. Personal skills are editable by their owner. Shared skills are editable only by the user who created them, and only while enabled. Skills synced from a repository file are rejected and must be edited in **Settings → Skills**. This tool never enables/disables a skill and never moves it between the personal and shared catalogs.
 
-Requires an authenticated user (API key or OAuth) and the Ask Sourcebot feature. Anonymous sessions do not see this tool.
+Requires an authenticated user (API key or OAuth) and the Ask Sourcebot feature. Anonymous sessions and repository-scoped access tokens cannot use this tool.
 
 Parameters:
 | Name | Required | Description |
@@ -487,7 +487,7 @@ Parameters:
 
 Lists the agent skills visible to the authenticated user: their personal skills plus the organization's shared skill catalog. Each row includes `slug` and `scope` (the identifier pair `update_skill` needs), `enabled`, `isSynced` (linked to a repository file), `canEdit` (whether `update_skill` can edit it), and, on shared rows, `adopted`. Skill instructions are never included.
 
-Requires an authenticated user (API key or OAuth) and the Ask Sourcebot feature. Anonymous sessions do not see this tool.
+Requires an authenticated user (API key or OAuth) and the Ask Sourcebot feature. Anonymous sessions and repository-scoped access tokens cannot use this tool.
 
 Parameters:
 | Name | Required | Description |

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

@@ -75,7 +75,7 @@ export const POST = apiHandler(async (request: NextRequest) => {
     }
 
     const response = await sew(() =>
-        withOptionalAuth(async ({ user }) => {
+        withOptionalAuth(async ({ user, principal }) => {
             if (env.EXPERIMENT_ASK_GH_ENABLED === 'true' && !user) {
                 return notAuthenticated();
             }
@@ -111,7 +111,13 @@ export const POST = apiHandler(async (request: NextRequest) => {
                 },
             });
 
-            const mcpServer = await createMcpServer({ isAuthenticated: ownerId !== null });
+            // Repository-scoped access tokens never get the skill management
+            // tools: their documented authorization boundary is the selected
+            // repositories only. The tools also reject scoped principals
+            // per-request, since a session is keyed by owner, not principal.
+            const mcpServer = await createMcpServer({
+                canManageSkills: ownerId !== null && principal?.source !== 'scoped_access_token',
+            });
             await mcpServer.connect(transport);
 
             return transport.handleRequest(request);

packages/web/src/ee/features/mcp/server.ts

@@ -31,7 +31,7 @@ import {
 
 const dedent = _dedent.withOptions({ alignValues: true });
 
-export async function createMcpServer({ isAuthenticated }: { isAuthenticated: boolean }): Promise<McpServer> {
+export async function createMcpServer({ canManageSkills }: { canManageSkills: boolean }): Promise<McpServer> {
     // Defense-in-depth: the MCP server is a paid feature. The /api/ee/mcp route
     // gates on the `mcp` entitlement before calling this; this assertion
     // backstops that contract so the server can't be constructed on a
@@ -64,10 +64,13 @@ export async function createMcpServer({ isAuthenticated }: { isAuthenticated: bo
     registerMcpTool(server, findSymbolReferencesDefinition, toolContext);
 
     // The skill management tools require an authenticated user (skills are
-    // per-user) and the Ask feature. Registration is per session and the
-    // session owner is fixed, so this gate is exact; withAuth inside each
-    // tool's execute remains the real enforcement.
-    if (isAuthenticated && await hasEntitlement('ask')) {
+    // per-user) whose credential is not repository-scoped (scoped access
+    // tokens grant repo access only, never account-level skill management),
+    // plus the Ask feature. Registration is best-effort UX: sessions are keyed
+    // by owner, not principal, so the per-request checks inside each tool's
+    // execute (withAuth + the scoped-token rejection) remain the real
+    // enforcement.
+    if (canManageSkills && await hasEntitlement('ask')) {
         registerMcpTool(server, createSkillDefinition, toolContext);
         registerMcpTool(server, updateSkillDefinition, toolContext);
         registerMcpTool(server, listSkillsDefinition, toolContext);

packages/web/src/features/tools/createSkill.test.ts

@@ -54,6 +54,7 @@ beforeEach(() => {
         org: { id: 1 },
         user: { id: "user-1" },
         prisma: {},
+        principal: { source: "api_key" },
     };
     mocks.withAuth.mockImplementation(async (callback: (context: unknown) => unknown) => callback(mocks.authContext));
     mocks.checkAskEntitlement.mockResolvedValue(null);
@@ -104,6 +105,19 @@ describe("createSkillDefinition", () => {
             .rejects.toThrow("Authentication is required to create skills.");
     });
 
+    test("rejects a repository-scoped access token without creating", async () => {
+        mocks.authContext = {
+            org: { id: 1 },
+            user: { id: "user-1" },
+            prisma: {},
+            principal: { source: "scoped_access_token" },
+        };
+
+        await expect(createSkillDefinition.execute(validInput, { source: "sourcebot-mcp-server" }))
+            .rejects.toThrow("Repository-scoped access tokens cannot manage skills.");
+        expect(mocks.createPersonalAgentSkillForContext).not.toHaveBeenCalled();
+    });
+
     test("throws the entitlement message when Ask is not available", async () => {
         mocks.checkAskEntitlement.mockResolvedValue({
             statusCode: StatusCodes.FORBIDDEN,

packages/web/src/features/tools/createSkill.ts

@@ -7,7 +7,7 @@ import { sew } from "@/middleware/sew";
 import { withAuth } from "@/middleware/withAuth";
 import { ToolDefinition } from "./types";
 import { logger } from "./logger";
-import { skillSettingsUrl, toSkillToolError, toSkillAnalyticsSource } from "./skillToolShared";
+import { scopedTokensCannotManageSkills, skillSettingsUrl, toSkillToolError, toSkillAnalyticsSource } from "./skillToolShared";
 import description from "./createSkill.txt";
 
 // Plain described strings rather than the piped slug schema: the AI SDK
@@ -45,7 +45,11 @@ export const createSkillDefinition: ToolDefinition<"create_skill", typeof create
         }
 
         const result = await sew(() =>
-            withAuth(async ({ org, user, prisma }) => {
+            withAuth(async ({ org, user, prisma, principal }) => {
+                if (principal.source === 'scoped_access_token') {
+                    return scopedTokensCannotManageSkills();
+                }
+
                 const askError = await checkAskEntitlement();
                 if (askError) {
                     return askError;

packages/web/src/features/tools/listSkills.test.ts

@@ -68,6 +68,7 @@ beforeEach(() => {
         org: { id: 1 },
         user: { id: "user-1" },
         prisma,
+        principal: { source: "api_key" },
     };
     mocks.withAuth.mockImplementation(async (callback: (context: unknown) => unknown) => callback(mocks.authContext));
     mocks.checkAskEntitlement.mockResolvedValue(null);
@@ -120,6 +121,19 @@ describe("listSkillsDefinition", () => {
         expect(result.metadata).toEqual({ count: 0 });
     });
 
+    test("rejects a repository-scoped access token without listing", async () => {
+        mocks.authContext = {
+            org: { id: 1 },
+            user: { id: "user-1" },
+            prisma,
+            principal: { source: "scoped_access_token" },
+        };
+
+        await expect(listSkillsDefinition.execute({}, { source: "sourcebot-mcp-server" }))
+            .rejects.toThrow("Repository-scoped access tokens cannot manage skills.");
+        expect(prisma.agentSkill.findMany).not.toHaveBeenCalled();
+    });
+
     test("the scope filter limits the query to one catalog", async () => {
         prisma.agentSkill.findMany.mockResolvedValueOnce([personalRow()]);
 

packages/web/src/features/tools/listSkills.ts

@@ -6,7 +6,7 @@ import { sew } from "@/middleware/sew";
 import { withAuth } from "@/middleware/withAuth";
 import { ToolDefinition } from "./types";
 import { logger } from "./logger";
-import { toSkillToolError } from "./skillToolShared";
+import { scopedTokensCannotManageSkills, toSkillToolError } from "./skillToolShared";
 import description from "./listSkills.txt";
 
 const listSkillsShape = {
@@ -29,7 +29,11 @@ export const listSkillsDefinition: ToolDefinition<"list_skills", typeof listSkil
         logger.debug('list_skills', input);
 
         const result = await sew(() =>
-            withAuth(async ({ org, user, prisma }) => {
+            withAuth(async ({ org, user, prisma, principal }) => {
+                if (principal.source === 'scoped_access_token') {
+                    return scopedTokensCannotManageSkills();
+                }
+
                 const askError = await checkAskEntitlement();
                 if (askError) {
                     return askError;

packages/web/src/features/tools/skillToolShared.ts

@@ -2,6 +2,7 @@ import { env } from "@sourcebot/shared";
 import { ErrorCode } from "@/lib/errorCodes";
 import type { AskSkillAnalyticsSource } from "@/lib/posthogEvents";
 import type { ServiceError } from "@/lib/serviceError";
+import { StatusCodes } from "http-status-codes";
 
 // Helpers shared by the skill management tools (create_skill, update_skill,
 // list_skills).
@@ -11,6 +12,18 @@ export const toSkillAnalyticsSource = (source: string | undefined): AskSkillAnal
         ? source
         : 'sourcebot-ask-agent';
 
+// Repository-scoped access tokens grant access to selected repositories only;
+// account-level skill management is outside their documented authorization
+// boundary. Every skill tool rejects them in its handler regardless of
+// registration-time gating: an MCP session is keyed by its owner, not its
+// principal, so a session created with a full credential can later be driven
+// by a scoped token for the same user.
+export const scopedTokensCannotManageSkills = (): ServiceError => ({
+    statusCode: StatusCodes.FORBIDDEN,
+    errorCode: ErrorCode.INSUFFICIENT_PERMISSIONS,
+    message: "Repository-scoped access tokens cannot manage skills.",
+});
+
 // The settings page supports ?skill= deep links that open the given skill.
 export const skillSettingsUrl = (skillId: string): string =>
     `${env.AUTH_URL.replace(/\/$/, '')}/settings/skills?skill=${encodeURIComponent(skillId)}`;

packages/web/src/features/tools/updateSkill.test.ts

@@ -47,6 +47,7 @@ beforeEach(() => {
         org: { id: 1 },
         user: { id: "user-1" },
         prisma: {},
+        principal: { source: "api_key" },
     };
     mocks.withAuth.mockImplementation(async (callback: (context: unknown) => unknown) => callback(mocks.authContext));
     mocks.checkAskEntitlement.mockResolvedValue(null);
@@ -121,6 +122,21 @@ describe("updateSkillDefinition", () => {
         )).rejects.toThrow("Authentication is required to update skills.");
     });
 
+    test("rejects a repository-scoped access token without updating", async () => {
+        mocks.authContext = {
+            org: { id: 1 },
+            user: { id: "user-1" },
+            prisma: {},
+            principal: { source: "scoped_access_token" },
+        };
+
+        await expect(updateSkillDefinition.execute(
+            { slug: "review-pr", scope: "personal", name: "Renamed" },
+            { source: "sourcebot-mcp-server" },
+        )).rejects.toThrow("Repository-scoped access tokens cannot manage skills.");
+        expect(mocks.updateAgentSkillForContext).not.toHaveBeenCalled();
+    });
+
     test("returns the updated skill as JSON output plus UI metadata with the tool's scope", async () => {
         const result = await updateSkillDefinition.execute(
             { slug: "review-pr", scope: "personal", name: "Review PR" },

packages/web/src/features/tools/updateSkill.ts

@@ -7,7 +7,7 @@ import { sew } from "@/middleware/sew";
 import { withAuth } from "@/middleware/withAuth";
 import { ToolDefinition } from "./types";
 import { logger } from "./logger";
-import { skillSettingsUrl, toSkillToolError, toSkillAnalyticsSource } from "./skillToolShared";
+import { scopedTokensCannotManageSkills, skillSettingsUrl, toSkillToolError, toSkillAnalyticsSource } from "./skillToolShared";
 import description from "./updateSkill.txt";
 
 // Same plain-string style as create_skill: the merged result is validated in
@@ -43,7 +43,11 @@ export const updateSkillDefinition: ToolDefinition<"update_skill", typeof update
         const { slug, scope, name, newSlug, description: newDescription, instructions } = input;
 
         const result = await sew(() =>
-            withAuth(async ({ org, user, prisma }) => {
+            withAuth(async ({ org, user, prisma, principal }) => {
+                if (principal.source === 'scoped_access_token') {
+                    return scopedTokensCannotManageSkills();
+                }
+
                 const askError = await checkAskEntitlement();
                 if (askError) {
                     return askError;