feat: scope access tokens by repository ID

Author: brendan-kellam

docs/api-reference/sourcebot-public.openapi.json

@@ -1114,11 +1114,12 @@
             "type": "string",
             "format": "date-time"
           },
-          "repos": {
+          "repoIds": {
             "type": "array",
             "items": {
-              "type": "string",
-              "minLength": 1
+              "type": "integer",
+              "minimum": 0,
+              "exclusiveMinimum": true
             },
             "minItems": 1
           }
@@ -1128,24 +1129,25 @@
           "token",
           "createdAt",
           "expiresAt",
-          "repos"
+          "repoIds"
         ]
       },
       "PublicCreateScopedAccessTokenRequest": {
         "type": "object",
         "properties": {
-          "repos": {
+          "repoIds": {
             "type": "array",
             "items": {
-              "type": "string",
-              "minLength": 1
+              "type": "integer",
+              "minimum": 0,
+              "exclusiveMinimum": true
             },
             "minItems": 1,
-            "description": "Repository names to bind to the token. Every name must identify exactly one repository accessible to the API-key owner."
+            "description": "Repository IDs to bind to the token. Every ID must identify a repository accessible to the API-key owner."
           }
         },
         "required": [
-          "repos"
+          "repoIds"
         ],
         "additionalProperties": false
       },
@@ -2332,7 +2334,7 @@
           "Scoped Access Tokens"
         ],
         "summary": "Create a scoped access token",
-        "description": "Creates an opaque bearer token that expires exactly one hour after issuance and is restricted to the requested repositories. Repository names are resolved atomically against the API-key owner's current access; the request fails if any name is missing, inaccessible, or ambiguous.\n\nThis endpoint requires a Sourcebot API key. Scoped access tokens, OAuth tokens, and browser sessions cannot mint another scoped access token. The returned token is independent of the API key after issuance and cannot be refreshed.",
+        "description": "Creates an opaque bearer token that expires exactly one hour after issuance and is restricted to the requested repositories. Repository IDs are validated atomically against the API-key owner's current access; the request fails if any ID is missing or inaccessible. Repository IDs are returned by GET /api/repos.\n\nThis endpoint requires a Sourcebot API key. Scoped access tokens, OAuth tokens, and browser sessions cannot mint another scoped access token. The returned token is independent of the API key after issuance and cannot be refreshed.",
         "security": [
           {
             "bearerToken": []

packages/web/src/ee/features/scopedAccessTokens/api.test.ts

@@ -25,11 +25,11 @@ const {
 const { withAuth } = await import('@/middleware/withAuth');
 
 const NOW = new Date('2026-08-06T04:00:00.000Z');
-const REPO_A = 'github.com/acme/a';
-const REPO_B = 'github.com/acme/b';
+const REPO_A_ID = 11;
+const REPO_B_ID = 22;
 
 function createPrismaMock(
-    repositories: Array<{ id: number; name: string }>,
+    repositories: Array<{ id: number }>,
     deletedTokenCount = 1,
 ) {
     const scopedAccessTokenCreate = vi.fn().mockImplementation(async ({
@@ -68,12 +68,14 @@ afterEach(() => {
 });
 
 describe('createScopedAccessTokenRequestSchema', () => {
-    test('accepts only a non-empty repos array', () => {
-        expect(createScopedAccessTokenRequestSchema.safeParse({ repos: [REPO_A] }).success).toBe(true);
-        expect(createScopedAccessTokenRequestSchema.safeParse({ repos: [] }).success).toBe(false);
-        expect(createScopedAccessTokenRequestSchema.safeParse({ repositories: [REPO_A] }).success).toBe(false);
+    test('accepts only a non-empty repoIds array of positive integers', () => {
+        expect(createScopedAccessTokenRequestSchema.safeParse({ repoIds: [REPO_A_ID] }).success).toBe(true);
+        expect(createScopedAccessTokenRequestSchema.safeParse({ repoIds: [] }).success).toBe(false);
+        expect(createScopedAccessTokenRequestSchema.safeParse({ repos: [REPO_A_ID] }).success).toBe(false);
+        expect(createScopedAccessTokenRequestSchema.safeParse({ repoIds: ['11'] }).success).toBe(false);
+        expect(createScopedAccessTokenRequestSchema.safeParse({ repoIds: [0] }).success).toBe(false);
         expect(createScopedAccessTokenRequestSchema.safeParse({
-            repos: [REPO_A],
+            repoIds: [REPO_A_ID],
             expiresAt: '2026-08-06T05:00:00.000Z',
         }).success).toBe(false);
     });
@@ -82,33 +84,32 @@ describe('createScopedAccessTokenRequestSchema', () => {
 describe('createScopedAccessToken', () => {
     test('creates an API-key-authenticated token with an exact one-hour lifetime', async () => {
         const prisma = createPrismaMock([
-            { id: 22, name: REPO_B },
-            { id: 11, name: REPO_A },
+            { id: REPO_B_ID },
+            { id: REPO_A_ID },
         ]);
         mocks.authContext = {
             org: { id: 1 },
             user: { id: 'user-id' },
             prisma,
         };
 
-        await expect(createScopedAccessToken({ repos: [REPO_A, REPO_B] })).resolves.toEqual({
+        await expect(createScopedAccessToken({ repoIds: [REPO_A_ID, REPO_B_ID] })).resolves.toEqual({
             id: 'token-id',
             token: 'sbst_secret',
             createdAt: '2026-08-06T04:00:00.000Z',
             expiresAt: '2026-08-06T05:00:00.000Z',
-            repos: [REPO_A, REPO_B],
+            repoIds: [REPO_A_ID, REPO_B_ID],
         });
         expect(withAuth).toHaveBeenCalledWith(expect.any(Function), {
             requiredAuthSource: 'api_key',
         });
         expect(prisma.repo.findMany).toHaveBeenCalledWith({
             where: {
                 orgId: 1,
-                name: { in: [REPO_A, REPO_B] },
+                id: { in: [REPO_A_ID, REPO_B_ID] },
             },
             select: {
                 id: true,
-                name: true,
             },
         });
         expect(prisma.scopedAccessToken.create).toHaveBeenCalledWith({
@@ -131,62 +132,43 @@ describe('createScopedAccessToken', () => {
     });
 
     test('rejects the entire request before generating a token when a repo is inaccessible or missing', async () => {
-        const prisma = createPrismaMock([{ id: 11, name: REPO_A }]);
+        const prisma = createPrismaMock([{ id: REPO_A_ID }]);
         mocks.authContext = {
             org: { id: 1 },
             user: { id: 'user-id' },
             prisma,
         };
 
-        await expect(createScopedAccessToken({ repos: [REPO_A, REPO_B] })).resolves.toEqual({
+        await expect(createScopedAccessToken({ repoIds: [REPO_A_ID, REPO_B_ID] })).resolves.toEqual({
             statusCode: 400,
             errorCode: 'INVALID_REPOSITORY_SCOPE',
-            message: 'Each repository name must identify exactly one accessible repository.',
+            message: 'Each repository ID must identify an accessible repository.',
         });
         expect(mocks.generateScopedAccessToken).not.toHaveBeenCalled();
         expect(prisma.scopedAccessToken.create).not.toHaveBeenCalled();
     });
 
-    test('rejects ambiguous repository names before generating a token', async () => {
-        const prisma = createPrismaMock([
-            { id: 11, name: REPO_A },
-            { id: 12, name: REPO_A },
-        ]);
-        mocks.authContext = {
-            org: { id: 1 },
-            user: { id: 'user-id' },
-            prisma,
-        };
-
-        await expect(createScopedAccessToken({ repos: [REPO_A] })).resolves.toMatchObject({
-            statusCode: 400,
-            errorCode: 'INVALID_REPOSITORY_SCOPE',
-        });
-        expect(mocks.generateScopedAccessToken).not.toHaveBeenCalled();
-        expect(prisma.scopedAccessToken.create).not.toHaveBeenCalled();
-    });
-
-    test('normalizes duplicate repository names before lookup and persistence', async () => {
-        const prisma = createPrismaMock([{ id: 11, name: REPO_A }]);
+    test('normalizes duplicate repository IDs before lookup and persistence', async () => {
+        const prisma = createPrismaMock([{ id: REPO_A_ID }]);
         mocks.authContext = {
             org: { id: 1 },
             user: { id: 'user-id' },
             prisma,
         };
 
-        await expect(createScopedAccessToken({ repos: [REPO_A, REPO_A] })).resolves.toMatchObject({
-            repos: [REPO_A],
+        await expect(createScopedAccessToken({ repoIds: [REPO_A_ID, REPO_A_ID] })).resolves.toMatchObject({
+            repoIds: [REPO_A_ID],
         });
         expect(prisma.repo.findMany).toHaveBeenCalledWith(expect.objectContaining({
             where: {
                 orgId: 1,
-                name: { in: [REPO_A] },
+                id: { in: [REPO_A_ID] },
             },
         }));
         expect(prisma.scopedAccessToken.create).toHaveBeenCalledWith(expect.objectContaining({
             data: expect.objectContaining({
                 repos: {
-                    create: [{ repoId: 11 }],
+                    create: [{ repoId: REPO_A_ID }],
                 },
             }),
         }));

packages/web/src/ee/features/scopedAccessTokens/api.ts

@@ -9,7 +9,7 @@ import { z } from 'zod';
 const SCOPED_ACCESS_TOKEN_TTL_MS = 60 * 60 * 1000;
 
 export const createScopedAccessTokenRequestSchema = z.object({
-    repos: z.array(z.string().min(1)).min(1),
+    repoIds: z.array(z.number().int().positive()).min(1),
 }).strict();
 
 export type CreateScopedAccessTokenRequest = z.infer<typeof createScopedAccessTokenRequestSchema>;
@@ -19,7 +19,7 @@ export interface CreateScopedAccessTokenResponse {
     token: string;
     createdAt: string;
     expiresAt: string;
-    repos: string[];
+    repoIds: number[];
 }
 
 export interface RevokeScopedAccessTokenResponse {
@@ -30,37 +30,24 @@ export const createScopedAccessToken = async (
     request: CreateScopedAccessTokenRequest,
 ): Promise<CreateScopedAccessTokenResponse | ServiceError> => sew(() =>
     withAuth(async ({ org, user, prisma }) => {
-        // Treat duplicate names as one scope entry while preserving request order.
-        const repositoryNames = [...new Set(request.repos)];
+        // Treat duplicate IDs as one scope entry while preserving request order.
+        const repositoryIds = [...new Set(request.repoIds)];
         const repositories = await prisma.repo.findMany({
             where: {
                 orgId: org.id,
-                name: { in: repositoryNames },
+                id: { in: repositoryIds },
             },
             select: {
                 id: true,
-                name: true,
             },
         });
 
-        const repositoriesByName = new Map<string, typeof repositories>();
-        for (const repository of repositories) {
-            const matches = repositoriesByName.get(repository.name) ?? [];
-            matches.push(repository);
-            repositoriesByName.set(repository.name, matches);
-        }
-
-        const resolvedRepositories: typeof repositories = [];
-        for (const repositoryName of repositoryNames) {
-            const matches = repositoriesByName.get(repositoryName);
-            if (matches?.length !== 1) {
-                return {
-                    statusCode: StatusCodes.BAD_REQUEST,
-                    errorCode: ErrorCode.INVALID_REPOSITORY_SCOPE,
-                    message: "Each repository name must identify exactly one accessible repository.",
-                } satisfies ServiceError;
-            }
-            resolvedRepositories.push(matches[0]);
+        if (repositories.length !== repositoryIds.length) {
+            return {
+                statusCode: StatusCodes.BAD_REQUEST,
+                errorCode: ErrorCode.INVALID_REPOSITORY_SCOPE,
+                message: 'Each repository ID must identify an accessible repository.',
+            } satisfies ServiceError;
         }
 
         const now = new Date();
@@ -74,7 +61,7 @@ export const createScopedAccessToken = async (
                 createdById: user.id,
                 orgId: org.id,
                 repos: {
-                    create: resolvedRepositories.map(({ id }) => ({ repoId: id })),
+                    create: repositoryIds.map((repoId) => ({ repoId })),
                 },
             },
             select: {
@@ -89,7 +76,7 @@ export const createScopedAccessToken = async (
             token,
             createdAt: createdToken.createdAt.toISOString(),
             expiresAt: createdToken.expiresAt.toISOString(),
-            repos: repositoryNames,
+            repoIds: repositoryIds,
         } satisfies CreateScopedAccessTokenResponse;
     }, { requiredAuthSource: 'api_key' })
 );

packages/web/src/openapi/publicApiDocument.ts

@@ -437,7 +437,7 @@ export function createPublicOpenApiDocument(version: string) {
         tags: [scopedAccessTokensTag.name],
         summary: 'Create a scoped access token',
         description: dedent`
-            Creates an opaque bearer token that expires exactly one hour after issuance and is restricted to the requested repositories. Repository names are resolved atomically against the API-key owner's current access; the request fails if any name is missing, inaccessible, or ambiguous.
+            Creates an opaque bearer token that expires exactly one hour after issuance and is restricted to the requested repositories. Repository IDs are validated atomically against the API-key owner's current access; the request fails if any ID is missing or inaccessible. Repository IDs are returned by GET /api/repos.
 
             This endpoint requires a Sourcebot API key. Scoped access tokens, OAuth tokens, and browser sessions cannot mint another scoped access token. The returned token is independent of the API key after issuance and cannot be refreshed.
         `,

packages/web/src/openapi/publicApiSchemas.ts

@@ -108,8 +108,8 @@ export const publicEeAuditResponseSchema = z.array(publicEeAuditRecordSchema).op
 
 // EE: Scoped Access Tokens
 export const publicCreateScopedAccessTokenRequestSchema = z.object({
-    repos: z.array(z.string().min(1)).min(1)
-        .describe('Repository names to bind to the token. Every name must identify exactly one repository accessible to the API-key owner.'),
+    repoIds: z.array(z.number().int().positive()).min(1)
+        .describe('Repository IDs to bind to the token. Every ID must identify a repository accessible to the API-key owner.'),
 }).strict().openapi('PublicCreateScopedAccessTokenRequest');
 
 export const publicCreateScopedAccessTokenResponseSchema = z.object({
@@ -118,5 +118,5 @@ export const publicCreateScopedAccessTokenResponseSchema = z.object({
         .describe('Opaque bearer token. This value is returned only when the token is created.'),
     createdAt: z.string().datetime(),
     expiresAt: z.string().datetime(),
-    repos: z.array(z.string().min(1)).min(1),
+    repoIds: z.array(z.number().int().positive()).min(1),
 }).openapi('PublicCreateScopedAccessTokenResponse');