@shipfox/api-integration-github 12.7.0 → 13.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-github",
   "license": "MIT",
-  "version": "12.7.0",
+  "version": "13.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",

package/src/api/client.test.ts

@@ -7,37 +7,211 @@ import {createGithubApiClient, mapGithubError} from './client.js';
 
 const GITHUB_INSTALLATION_TOKEN_PATTERN = /^ghs_[A-Za-z0-9._-]{36,}$/u;
 
-const {createInstallationAccessTokenMock, RequestErrorMock} = vi.hoisted(() => {
-  class RequestErrorMock extends Error {
-    constructor(
-      message: string,
-      public readonly status: number,
-    ) {
-      super(message);
-      this.name = 'HttpError';
+const {createInstallationAccessTokenMock, getByUsernameMock, octokitOptionsMock, RequestErrorMock} =
+  vi.hoisted(() => {
+    class RequestErrorMock extends Error {
+      constructor(
+        message: string,
+        public readonly status: number,
+      ) {
+        super(message);
+        this.name = 'HttpError';
+      }
     }
-  }
 
-  return {createInstallationAccessTokenMock: vi.fn(), RequestErrorMock};
-});
+    return {
+      createInstallationAccessTokenMock: vi.fn(),
+      getByUsernameMock: vi.fn(),
+      octokitOptionsMock: vi.fn(),
+      RequestErrorMock,
+    };
+  });
 
 vi.mock('octokit', () => ({
   App: class App {
     octokit = {
-      rest: {apps: {createInstallationAccessToken: createInstallationAccessTokenMock}},
+      rest: {
+        apps: {createInstallationAccessToken: createInstallationAccessTokenMock},
+        users: {getByUsername: getByUsernameMock},
+      },
     };
   },
-  Octokit: {
-    plugin() {
-      return this;
-    },
-    defaults(options: unknown) {
+  Octokit: class Octokit {
+    rest = {users: {getByUsername: getByUsernameMock}};
+
+    constructor(options: unknown) {
+      octokitOptionsMock(options);
+    }
+
+    static plugin() {
+      return Octokit;
+    }
+
+    static defaults(options: unknown) {
       return {defaults: options};
-    },
+    }
   },
   RequestError: RequestErrorMock,
 }));
 
+describe('OctokitGithubApiClient.getBotUser', () => {
+  beforeEach(() => {
+    getByUsernameMock.mockReset();
+    octokitOptionsMock.mockReset();
+  });
+
+  it('shares one lookup for concurrent requests with the same token and caches the bot', async () => {
+    getByUsernameMock.mockResolvedValue({
+      data: {id: 307_629_549, login: 'shipfox-ai[bot]', type: 'Bot'},
+    });
+    const client = createGithubApiClient();
+
+    const firstLookup = client.getBotUser({
+      username: 'shipfox-ai[bot]',
+      installationAccessToken: 'ghs_first',
+    });
+    const secondLookup = client.getBotUser({
+      username: 'SHIPFOX-AI[BOT]',
+      installationAccessToken: 'ghs_first',
+    });
+    const [first, second] = await Promise.all([firstLookup, secondLookup]);
+    const cached = await client.getBotUser({
+      username: 'shipfox-ai[bot]',
+      installationAccessToken: 'ghs_third',
+    });
+
+    expect(first).toEqual({id: 307_629_549, login: 'shipfox-ai[bot]'});
+    expect(second).toEqual(first);
+    expect(cached).toEqual(first);
+    expect(getByUsernameMock).toHaveBeenCalledTimes(1);
+    expect(getByUsernameMock).toHaveBeenCalledWith({
+      username: 'shipfox-ai[bot]',
+      request: {signal: expect.any(AbortSignal)},
+    });
+    expect(octokitOptionsMock).toHaveBeenCalledWith({
+      auth: 'ghs_first',
+      baseUrl: 'https://api.github.com',
+    });
+  });
+
+  it('does not share an in-flight lookup across installation tokens', async () => {
+    getByUsernameMock.mockResolvedValue({
+      data: {id: 307_629_549, login: 'shipfox-ai[bot]', type: 'Bot'},
+    });
+    const client = createGithubApiClient();
+
+    const firstLookup = client.getBotUser({
+      username: 'shipfox-ai[bot]',
+      installationAccessToken: 'ghs_first',
+    });
+    const secondLookup = client.getBotUser({
+      username: 'shipfox-ai[bot]',
+      installationAccessToken: 'ghs_second',
+    });
+
+    await expect(Promise.all([firstLookup, secondLookup])).resolves.toEqual([
+      {id: 307_629_549, login: 'shipfox-ai[bot]'},
+      {id: 307_629_549, login: 'shipfox-ai[bot]'},
+    ]);
+    expect(getByUsernameMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('evicts a failed lookup so a later request can retry', async () => {
+    getByUsernameMock
+      .mockRejectedValueOnce(new RequestErrorMock('GitHub unavailable', 503))
+      .mockResolvedValueOnce({
+        data: {id: 307_629_549, login: 'shipfox-ai[bot]', type: 'Bot'},
+      });
+    const client = createGithubApiClient();
+
+    const failed = client.getBotUser({
+      username: 'shipfox-ai[bot]',
+      installationAccessToken: 'ghs_first',
+    });
+    await expect(failed).rejects.toMatchObject({reason: 'provider-unavailable'});
+    const retried = await client.getBotUser({
+      username: 'shipfox-ai[bot]',
+      installationAccessToken: 'ghs_second',
+    });
+
+    expect(retried).toEqual({id: 307_629_549, login: 'shipfox-ai[bot]'});
+    expect(getByUsernameMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('maps a missing configured bot and retries after the username becomes available', async () => {
+    getByUsernameMock
+      .mockRejectedValueOnce(new RequestErrorMock('Not Found', 404))
+      .mockResolvedValueOnce({
+        data: {id: 307_629_549, login: 'shipfox-ai[bot]', type: 'Bot'},
+      });
+    const client = createGithubApiClient();
+
+    const missing = client.getBotUser({
+      username: 'shipfox-ai[bot]',
+      installationAccessToken: 'ghs_installationtoken',
+    });
+    await expect(missing).rejects.toMatchObject({
+      reason: 'provider-rejected',
+      message: 'Configured GitHub bot user shipfox-ai[bot] was not found',
+      status: 404,
+    });
+    const corrected = client.getBotUser({
+      username: 'shipfox-ai[bot]',
+      installationAccessToken: 'ghs_installationtoken',
+    });
+
+    await expect(corrected).resolves.toEqual({
+      id: 307_629_549,
+      login: 'shipfox-ai[bot]',
+    });
+    expect(getByUsernameMock).toHaveBeenCalledTimes(2);
+  });
+
+  it.each([
+    ['a null body', null, 'GitHub bot user response is missing required fields'],
+    [
+      'an empty login',
+      {id: 307_629_549, login: '', type: 'Bot'},
+      'GitHub bot user response is missing required fields',
+    ],
+    [
+      'a zero id',
+      {id: 0, login: 'shipfox-ai[bot]', type: 'Bot'},
+      'GitHub bot user response is missing required fields',
+    ],
+    [
+      'a negative id',
+      {id: -1, login: 'shipfox-ai[bot]', type: 'Bot'},
+      'GitHub bot user response is missing required fields',
+    ],
+    [
+      'a fractional id',
+      {id: 1.5, login: 'shipfox-ai[bot]', type: 'Bot'},
+      'GitHub bot user response is missing required fields',
+    ],
+    [
+      'a non-bot account',
+      {id: 307_629_549, login: 'shipfox-ai[bot]', type: 'User'},
+      'Configured GitHub username is not a bot account',
+    ],
+    [
+      'a different bot account',
+      {id: 307_629_549, login: 'another-app[bot]', type: 'Bot'},
+      'GitHub bot user response did not match the configured username',
+    ],
+  ])('rejects %s', async (_label, data, message) => {
+    getByUsernameMock.mockResolvedValue({data});
+    const client = createGithubApiClient();
+
+    const result = client.getBotUser({
+      username: 'shipfox-ai[bot]',
+      installationAccessToken: 'ghs_installationtoken',
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'malformed-provider-response', message});
+  });
+});
+
 describe('mapGithubError', () => {
   it.each([400, 409, 422])('maps HTTP %i to a terminal provider rejection', async (status) => {
     const error = new RequestErrorMock(`GitHub rejected request with HTTP ${status}`, status);
@@ -62,6 +236,20 @@ describe('mapGithubError', () => {
       status: 503,
     });
   });
+
+  it('maps a request timeout cause to timeout', async () => {
+    const timeout = new Error('The operation was aborted due to timeout');
+    timeout.name = 'TimeoutError';
+    const error = new RequestErrorMock('fetch failed', 500);
+    error.cause = timeout;
+
+    const result = mapGithubError(() => Promise.reject(error));
+
+    await expect(result).rejects.toMatchObject({
+      reason: 'timeout',
+      message: 'GitHub request timed out',
+    });
+  });
 });
 
 describe('OctokitGithubApiClient.createInstallationAccessToken', () => {

package/src/api/client.ts

@@ -1,5 +1,6 @@
 import {Buffer} from 'node:buffer';
-import {MAX_REPOSITORY_FILE_BYTES} from '@shipfox/api-integration-spi';
+import {isRecord, MAX_REPOSITORY_FILE_BYTES} from '@shipfox/api-integration-spi';
+import {logger} from '@shipfox/node-opentelemetry';
 import ky, {HTTPError, TimeoutError} from 'ky';
 import {App, Octokit, RequestError} from 'octokit';
 import {config, normalizedGithubApiBaseUrl, normalizedGithubPrivateKey} from '#config.js';
@@ -13,6 +14,7 @@ import {
 const NEXT_PAGE_RE = /[?&]page=(\d+)/;
 const TRAILING_SLASHES_RE = /\/+$/;
 const MAX_TREE_WALK_DEPTH = 10;
+const GITHUB_API_TIMEOUT_MS = 10_000;
 
 export interface GithubAccount {
   login: string;
@@ -66,7 +68,16 @@ export interface GithubUserInstallationPage {
   nextCursor: string | null;
 }
 
-export interface GithubApiClient {
+export interface GithubBotUser {
+  id: number;
+  login: string;
+}
+
+export interface GithubBotUserClient {
+  getBotUser(input: {username: string; installationAccessToken: string}): Promise<GithubBotUser>;
+}
+
+export interface GithubApiClient extends Partial<GithubBotUserClient> {
   exchangeOAuthCode(code: string): Promise<string>;
   listUserInstallations(input: {
     userAccessToken: string;
@@ -106,12 +117,17 @@ export interface GithubInstallationAccessToken {
   permissions?: Record<string, 'read' | 'write' | 'admin'> | undefined;
 }
 
-export function createGithubApiClient(): GithubApiClient {
+export function createGithubApiClient(): GithubApiClient & GithubBotUserClient {
   return new OctokitGithubApiClient();
 }
 
-class OctokitGithubApiClient implements GithubApiClient {
+class OctokitGithubApiClient implements GithubApiClient, GithubBotUserClient {
   private app: App | undefined;
+  private readonly botUsers = new Map<string, GithubBotUser>();
+  private readonly botUserLookups = new Map<
+    string,
+    {installationAccessToken: string; promise: Promise<GithubBotUser>}
+  >();
 
   async exchangeOAuthCode(code: string): Promise<string> {
     const body = await mapGithubOAuthError(() =>
@@ -136,6 +152,39 @@ class OctokitGithubApiClient implements GithubApiClient {
     return body.access_token;
   }
 
+  getBotUser(input: {username: string; installationAccessToken: string}): Promise<GithubBotUser> {
+    const cacheKey = input.username.trim().toLowerCase();
+    const cached = this.botUsers.get(cacheKey);
+    if (cached) return Promise.resolve(cached);
+
+    const pending = this.botUserLookups.get(cacheKey);
+    if (pending?.installationAccessToken === input.installationAccessToken) {
+      return pending.promise;
+    }
+
+    const lookup = this.fetchBotUser(input).then((botUser) => {
+      const resolved = this.botUsers.get(cacheKey);
+      if (resolved) return resolved;
+
+      this.botUsers.set(cacheKey, botUser);
+      logger().info(
+        {githubAppBotLogin: botUser.login, githubAppBotUserId: botUser.id},
+        'Resolved GitHub App bot identity',
+      );
+      return botUser;
+    });
+    const trackedLookup = lookup.finally(() => {
+      if (this.botUserLookups.get(cacheKey)?.promise === trackedLookup) {
+        this.botUserLookups.delete(cacheKey);
+      }
+    });
+    this.botUserLookups.set(cacheKey, {
+      installationAccessToken: input.installationAccessToken,
+      promise: trackedLookup,
+    });
+    return trackedLookup;
+  }
+
   async listUserInstallations(input: {
     userAccessToken: string;
     cursor?: string | undefined;
@@ -405,6 +454,72 @@ class OctokitGithubApiClient implements GithubApiClient {
     }
     return this.app;
   }
+
+  private async fetchBotUser(input: {
+    username: string;
+    installationAccessToken: string;
+  }): Promise<GithubBotUser> {
+    const octokit = new Octokit({
+      auth: input.installationAccessToken,
+      baseUrl: normalizedGithubApiBaseUrl(),
+    });
+    let response: Awaited<ReturnType<typeof octokit.rest.users.getByUsername>>;
+    try {
+      response = await mapGithubError(
+        () =>
+          octokit.rest.users.getByUsername({
+            username: input.username,
+            request: {signal: AbortSignal.timeout(GITHUB_API_TIMEOUT_MS)},
+          }),
+        'provider-rejected',
+      );
+    } catch (error) {
+      if (error instanceof GithubIntegrationProviderError && error.status === 404) {
+        throw new GithubIntegrationProviderError(
+          'provider-rejected',
+          `Configured GitHub bot user ${input.username} was not found`,
+          undefined,
+          error.status,
+        );
+      }
+      throw error;
+    }
+
+    const data: unknown = response.data;
+    if (!isRecord(data)) {
+      throw new GithubIntegrationProviderError(
+        'malformed-provider-response',
+        'GitHub bot user response is missing required fields',
+      );
+    }
+    const {id, login, type} = data;
+    if (
+      typeof id !== 'number' ||
+      !Number.isSafeInteger(id) ||
+      id <= 0 ||
+      typeof login !== 'string' ||
+      login.trim().length === 0
+    ) {
+      throw new GithubIntegrationProviderError(
+        'malformed-provider-response',
+        'GitHub bot user response is missing required fields',
+      );
+    }
+    if (type !== 'Bot') {
+      throw new GithubIntegrationProviderError(
+        'malformed-provider-response',
+        'Configured GitHub username is not a bot account',
+      );
+    }
+    const canonicalLogin = login.trim();
+    if (canonicalLogin.toLowerCase() !== input.username.trim().toLowerCase()) {
+      throw new GithubIntegrationProviderError(
+        'malformed-provider-response',
+        'GitHub bot user response did not match the configured username',
+      );
+    }
+    return {id, login: canonicalLogin};
+  }
 }
 
 async function mapGithubOAuthError<T>(operation: () => Promise<T>): Promise<T> {
@@ -442,12 +557,16 @@ export async function mapGithubError<T>(
   notFoundReason:
     | 'repository-not-found'
     | 'installation-not-found'
-    | 'file-not-found' = 'repository-not-found',
+    | 'file-not-found'
+    | 'provider-rejected' = 'repository-not-found',
 ): Promise<T> {
   try {
     return await operation();
   } catch (error) {
     if (error instanceof GithubIntegrationProviderError) throw error;
+    if (isGithubTimeoutError(error)) {
+      throw new GithubIntegrationProviderError('timeout', 'GitHub request timed out');
+    }
     if (error instanceof RequestError) {
       if (error.status === 404) {
         throw new GithubIntegrationProviderError(
@@ -490,13 +609,16 @@ export async function mapGithubError<T>(
         );
       }
     }
-    if (error instanceof Error && error.name === 'AbortError') {
-      throw new GithubIntegrationProviderError('timeout', 'GitHub request timed out');
-    }
     throw error;
   }
 }
 
+function isGithubTimeoutError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  if (error.name === 'AbortError' || error.name === 'TimeoutError') return true;
+  return error.cause instanceof Error && isGithubTimeoutError(error.cause);
+}
+
 function isGithubRateLimitError(error: RequestError): boolean {
   return error.status === 403 && error.response?.headers['x-ratelimit-remaining'] === '0';
 }

package/src/core/agent-tools.ts

@@ -13,8 +13,9 @@ import {
   createGithubInstallationTokenProvider,
   type GithubInstallationTokenProvider,
 } from '#api/installation-token-provider.js';
-import {config, normalizedGithubApiBaseUrl} from '#config.js';
+import {normalizedGithubApiBaseUrl} from '#config.js';
 import type {GithubInstallation} from '#db/installations.js';
+import {githubAppBotLogin} from './bot-identity.js';
 import {GithubIntegrationProviderError} from './errors.js';
 import {
   type GithubAgentToolCatalogEntry,
@@ -59,7 +60,6 @@ const GITHUB_GRAPHQL_ROUTE = 'POST /graphql';
 const GITHUB_ARTIFACT_ARCHIVE_FORMAT = 'zip';
 const GITHUB_ARTIFACT_DOWNLOAD_ROUTE = `GET /repos/{owner}/{repo}/actions/artifacts/{resource_id}/${GITHUB_ARTIFACT_ARCHIVE_FORMAT}`;
 const GITHUB_ARTIFACT_DOWNLOAD_TIMEOUT_MS = 30_000;
-const GITHUB_APP_BOT_SUFFIX = '[bot]';
 const PENDING_REVIEW_PAGE_SIZE = 100;
 const PENDING_REVIEW_MAX_PAGE_REQUESTS = 5;
 const PENDING_REVIEW_LOOKUP_TIMEOUT_MS = 15_000;
@@ -725,13 +725,6 @@ function latestPendingReviewOnPage(
   return {malformed};
 }
 
-function githubAppBotLogin(): string {
-  const configuredUsername = config.GITHUB_APP_USERNAME?.trim() || config.GITHUB_APP_SLUG.trim();
-  return configuredUsername.toLowerCase().endsWith(GITHUB_APP_BOT_SUFFIX)
-    ? configuredUsername
-    : `${configuredUsername}${GITHUB_APP_BOT_SUFFIX}`;
-}
-
 function githubToolResult(
   toolId: GithubAgentToolId,
   data: unknown,

package/src/core/bot-identity.test.ts

@@ -0,0 +1,19 @@
+import {configuredGithubAppBotLogin, githubAppBotLogin, githubBotLogin} from './bot-identity.js';
+
+describe('GitHub App bot identity', () => {
+  it.each([
+    ['shipfox-ai', 'shipfox-ai[bot]'],
+    ['shipfox-ai[bot]', 'shipfox-ai[bot]'],
+    ['Shipfox-AI[Bot]', 'Shipfox-AI[Bot]'],
+  ])('normalizes %s to %s', (username, expected) => {
+    expect(githubBotLogin(username)).toBe(expected);
+  });
+
+  it('uses the configured username for commit attribution', () => {
+    expect(configuredGithubAppBotLogin()).toBe('shipfox-test[bot]');
+  });
+
+  it('uses the configured username for App review identity', () => {
+    expect(githubAppBotLogin()).toBe('shipfox-test[bot]');
+  });
+});

package/src/core/bot-identity.ts

@@ -0,0 +1,19 @@
+import {config} from '#config.js';
+
+const GITHUB_APP_BOT_SUFFIX = '[bot]';
+
+export function githubBotLogin(username: string): string {
+  const normalized = username.trim();
+  return normalized.toLowerCase().endsWith(GITHUB_APP_BOT_SUFFIX)
+    ? normalized
+    : `${normalized}${GITHUB_APP_BOT_SUFFIX}`;
+}
+
+export function configuredGithubAppBotLogin(): string | undefined {
+  const configuredUsername = config.GITHUB_APP_USERNAME?.trim();
+  return configuredUsername ? githubBotLogin(configuredUsername) : undefined;
+}
+
+export function githubAppBotLogin(): string {
+  return configuredGithubAppBotLogin() ?? githubBotLogin(config.GITHUB_APP_SLUG);
+}

package/src/core/source-control.test.ts

@@ -8,6 +8,7 @@ const VALID_COMMIT = 'a'.repeat(40);
 function githubClient(overrides: Partial<GithubApiClient> = {}): GithubApiClient {
   return {
     exchangeOAuthCode: vi.fn(() => Promise.resolve('token')),
+    getBotUser: vi.fn(() => Promise.resolve({id: 12_345, login: 'shipfox-test[bot]'})),
     listUserInstallations: vi.fn(() => Promise.resolve({installationIds: [], nextCursor: null})),
     getInstallation: vi.fn(() => {
       throw new Error('not used');
@@ -349,7 +350,7 @@ describe('GithubSourceControlProvider', () => {
       },
       gitAuthor: {
         name: 'shipfox-test[bot]',
-        email: '1+shipfox-test[bot]@users.noreply.github.com',
+        email: '12345+shipfox-test[bot]@users.noreply.github.com',
       },
     });
     expect(result.repositoryUrl).not.toContain('ghs_installationtoken');
@@ -358,6 +359,91 @@ describe('GithubSourceControlProvider', () => {
       repositoryId: 42,
       permissions: {contents: 'write'},
     });
+    expect(github.getBotUser).toHaveBeenCalledWith({
+      username: 'shipfox-test[bot]',
+      installationAccessToken: 'ghs_installationtoken',
+    });
+  });
+
+  it('propagates bot identity resolution failures for write checkouts', async () => {
+    await createInstallation();
+    const github = githubClient({
+      getBotUser: vi.fn(() =>
+        Promise.reject(
+          new GithubIntegrationProviderError('provider-rejected', 'bot user not found'),
+        ),
+      ),
+    });
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = provider.createCheckoutSpec({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      permissions: {contents: 'write'},
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'provider-rejected'});
+  });
+
+  it('propagates unexpected bot lookup errors', async () => {
+    await createInstallation();
+    const github = githubClient({
+      getBotUser: vi.fn(() => Promise.reject(new Error('unexpected lookup failure'))),
+    });
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = provider.createCheckoutSpec({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      permissions: {contents: 'write'},
+    });
+
+    await expect(result).rejects.toThrow('unexpected lookup failure');
+  });
+
+  it('rejects write checkout when the bot identity resolver is unavailable', async () => {
+    await createInstallation();
+    const github = githubClient();
+    delete github.getBotUser;
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = provider.createCheckoutSpec({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      permissions: {contents: 'write'},
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'provider-unavailable'});
+  });
+
+  it('omits the author and bot lookup for read-only checkouts', async () => {
+    await createInstallation();
+    const github = githubClient();
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = await provider.createCheckoutSpec({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      permissions: {contents: 'read'},
+    });
+
+    expect(result.gitAuthor).toBeUndefined();
+    expect(github.getBotUser).not.toHaveBeenCalled();
+  });
+
+  it('omits the author and bot lookup when the App username is unset', async () => {
+    await createInstallation();
+    const github = githubClient();
+    const provider = new GithubSourceControlProvider(github, () => undefined);
+
+    const result = await provider.createCheckoutSpec({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      permissions: {contents: 'write'},
+    });
+
+    expect(result.gitAuthor).toBeUndefined();
+    expect(github.getBotUser).not.toHaveBeenCalled();
   });
 
   it('defaults the checkout ref to the repository default branch', async () => {