@shipfox/api-integration-github 12.5.0 → 12.6.0

package/package.json

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

package/src/api/client.test.ts

@@ -1,6 +1,12 @@
 import {GithubIntegrationProviderError} from '#core/errors.js';
+import {
+  GITHUB_STATEFUL_INSTALLATION_TOKEN,
+  GITHUB_STATELESS_INSTALLATION_TOKEN,
+} from '#test/index.js';
 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(
@@ -22,6 +28,9 @@ vi.mock('octokit', () => ({
     };
   },
   Octokit: {
+    plugin() {
+      return this;
+    },
     defaults(options: unknown) {
       return {defaults: options};
     },
@@ -62,7 +71,10 @@ describe('OctokitGithubApiClient.createInstallationAccessToken', () => {
 
   it('mints a repository-scoped, read-only installation token', async () => {
     createInstallationAccessTokenMock.mockResolvedValue({
-      data: {token: 'ghs_installationtoken', expires_at: '2026-06-10T12:00:00.000Z'},
+      data: {
+        token: GITHUB_STATELESS_INSTALLATION_TOKEN,
+        expires_at: '2026-06-10T12:00:00.000Z',
+      },
     });
     const client = createGithubApiClient();
 
@@ -72,9 +84,11 @@ describe('OctokitGithubApiClient.createInstallationAccessToken', () => {
     });
 
     expect(result).toEqual({
-      token: 'ghs_installationtoken',
+      token: GITHUB_STATELESS_INSTALLATION_TOKEN,
       expiresAt: new Date('2026-06-10T12:00:00.000Z'),
     });
+    expect(GITHUB_STATELESS_INSTALLATION_TOKEN).toMatch(GITHUB_INSTALLATION_TOKEN_PATTERN);
+    expect(GITHUB_STATELESS_INSTALLATION_TOKEN.slice(4).split('.')).toHaveLength(3);
     expect(createInstallationAccessTokenMock).toHaveBeenCalledWith({
       installation_id: 1,
       repository_ids: [42],
@@ -82,18 +96,24 @@ describe('OctokitGithubApiClient.createInstallationAccessToken', () => {
     });
   });
 
-  it('mints a repository-scoped write installation token when requested', async () => {
+  it('passes through a stateful repository-scoped write token', async () => {
     createInstallationAccessTokenMock.mockResolvedValue({
-      data: {token: 'ghs_installationtoken', expires_at: '2026-06-10T12:00:00.000Z'},
+      data: {
+        token: GITHUB_STATEFUL_INSTALLATION_TOKEN,
+        expires_at: '2026-06-10T12:00:00.000Z',
+      },
     });
     const client = createGithubApiClient();
 
-    await client.createInstallationAccessToken({
+    const result = await client.createInstallationAccessToken({
       installationId: 1,
       repositoryId: 42,
       permissions: {contents: 'write'},
     });
 
+    expect(result.token).toBe(GITHUB_STATEFUL_INSTALLATION_TOKEN);
+    expect(GITHUB_STATEFUL_INSTALLATION_TOKEN).toMatch(GITHUB_INSTALLATION_TOKEN_PATTERN);
+    expect(GITHUB_STATEFUL_INSTALLATION_TOKEN).not.toContain('.');
     expect(createInstallationAccessTokenMock).toHaveBeenCalledWith({
       installation_id: 1,
       repository_ids: [42],

package/src/api/client.ts

@@ -4,6 +4,11 @@ import ky, {HTTPError, TimeoutError} from 'ky';
 import {App, Octokit, RequestError} from 'octokit';
 import {config, normalizedGithubApiBaseUrl, normalizedGithubPrivateKey} from '#config.js';
 import {GithubIntegrationProviderError} from '#core/errors.js';
+import {recordInstallationTokenFormat} from '#metrics/index.js';
+import {
+  getGithubInstallationOctokit,
+  githubInstallationTokenFormatPlugin,
+} from './github-octokit.js';
 
 const NEXT_PAGE_RE = /[?&]page=(\d+)/;
 const TRAILING_SLASHES_RE = /\/+$/;
@@ -186,7 +191,9 @@ class OctokitGithubApiClient implements GithubApiClient {
     limit: number;
     cursor?: string | undefined;
   }): Promise<GithubRepositoryPage> {
-    const octokit = await this.getApp().getInstallationOctokit(input.installationId);
+    const octokit = await mapGithubError(() =>
+      getGithubInstallationOctokit(this.getApp(), input.installationId),
+    );
     const page = cursorToPage(input.cursor);
     const response = await mapGithubError(() =>
       octokit.rest.apps.listReposAccessibleToInstallation({
@@ -205,7 +212,9 @@ class OctokitGithubApiClient implements GithubApiClient {
     installationId: number;
     repositoryId: number;
   }): Promise<GithubRepository> {
-    const octokit = await this.getApp().getInstallationOctokit(input.installationId);
+    const octokit = await mapGithubError(() =>
+      getGithubInstallationOctokit(this.getApp(), input.installationId),
+    );
     const response = await mapGithubError(() =>
       octokit.request('GET /repositories/{repository_id}', {
         repository_id: input.repositoryId,
@@ -223,7 +232,9 @@ class OctokitGithubApiClient implements GithubApiClient {
     limit: number;
     cursor?: string | undefined;
   }): Promise<GithubFilePage> {
-    const octokit = await this.getApp().getInstallationOctokit(input.installationId);
+    const octokit = await mapGithubError(() =>
+      getGithubInstallationOctokit(this.getApp(), input.installationId),
+    );
     const repository = await this.getRepository({
       installationId: input.installationId,
       repositoryId: input.repositoryId,
@@ -303,7 +314,9 @@ class OctokitGithubApiClient implements GithubApiClient {
     ref: string;
     path: string;
   }): Promise<GithubFileContent> {
-    const octokit = await this.getApp().getInstallationOctokit(input.installationId);
+    const octokit = await mapGithubError(() =>
+      getGithubInstallationOctokit(this.getApp(), input.installationId),
+    );
     const repository = await this.getRepository({
       installationId: input.installationId,
       repositoryId: input.repositoryId,
@@ -363,6 +376,8 @@ class OctokitGithubApiClient implements GithubApiClient {
       );
     }
 
+    recordInstallationTokenFormat(response.data.token);
+
     const expiresAt = new Date(response.data.expires_at);
     if (Number.isNaN(expiresAt.getTime())) {
       throw new GithubIntegrationProviderError(
@@ -383,7 +398,9 @@ class OctokitGithubApiClient implements GithubApiClient {
       this.app = new App({
         appId: config.GITHUB_APP_ID,
         privateKey: normalizedGithubPrivateKey(),
-        Octokit: Octokit.defaults({baseUrl: normalizedGithubApiBaseUrl()}),
+        Octokit: Octokit.plugin(githubInstallationTokenFormatPlugin).defaults({
+          baseUrl: normalizedGithubApiBaseUrl(),
+        }),
       });
     }
     return this.app;

package/src/api/github-octokit.test.ts

@@ -0,0 +1,115 @@
+import {generateKeyPairSync} from 'node:crypto';
+import {once} from 'node:events';
+import {createServer} from 'node:http';
+import {App, Octokit} from 'octokit';
+import {
+  GITHUB_STATEFUL_INSTALLATION_TOKEN,
+  GITHUB_STATELESS_INSTALLATION_TOKEN,
+} from '#test/index.js';
+import {
+  createGithubInstallationTokenFormatPlugin,
+  getGithubInstallationOctokit,
+} from './github-octokit.js';
+
+const {privateKey} = generateKeyPairSync('rsa', {
+  modulusLength: 2048,
+  publicKeyEncoding: {type: 'spki', format: 'pem'},
+  privateKeyEncoding: {type: 'pkcs8', format: 'pem'},
+});
+const BEARER_AUTHORIZATION = /^bearer /iu;
+
+describe('GitHub installation Octokit', () => {
+  it.each([
+    {
+      format: 'stateless',
+      token: GITHUB_STATELESS_INSTALLATION_TOKEN,
+      override: 'enabled' as const,
+      authorization: `bearer ${GITHUB_STATELESS_INSTALLATION_TOKEN}`,
+    },
+    {
+      format: 'stateful',
+      token: GITHUB_STATEFUL_INSTALLATION_TOKEN,
+      override: 'disabled' as const,
+      authorization: `token ${GITHUB_STATEFUL_INSTALLATION_TOKEN}`,
+    },
+    {
+      format: 'stateful without an override',
+      token: GITHUB_STATEFUL_INSTALLATION_TOKEN,
+      override: undefined,
+      authorization: `token ${GITHUB_STATEFUL_INSTALLATION_TOKEN}`,
+    },
+  ])('requests and authenticates with a $format token', async ({
+    token,
+    override,
+    authorization,
+  }) => {
+    const calls: Array<{
+      method: string | undefined;
+      path: string | undefined;
+      authorization: string | undefined;
+      tokenFormatOverride: string | undefined;
+    }> = [];
+    const server = createServer((request, response) => {
+      calls.push({
+        method: request.method,
+        path: request.url,
+        authorization: request.headers.authorization,
+        tokenFormatOverride: request.headers['x-github-stateless-s2s-token'] as string | undefined,
+      });
+
+      if (request.method === 'POST' && request.url === '/app/installations/123/access_tokens') {
+        response.writeHead(201, {'content-type': 'application/json'}).end(
+          JSON.stringify({
+            token,
+            expires_at: '2099-01-01T00:00:00.000Z',
+            permissions: {metadata: 'read'},
+            repository_selection: 'all',
+          }),
+        );
+        return;
+      }
+
+      if (request.method === 'GET' && request.url === '/installation/repositories') {
+        response
+          .writeHead(200, {'content-type': 'application/json'})
+          .end(JSON.stringify({total_count: 0, repositories: []}));
+        return;
+      }
+
+      response.writeHead(404, {'content-type': 'application/json'}).end('{"message":"Not Found"}');
+    });
+    server.listen({host: '127.0.0.1', port: 0});
+    await once(server, 'listening');
+    const address = server.address();
+    if (!address || typeof address === 'string') throw new Error('Expected TCP server address.');
+    const baseUrl = `http://127.0.0.1:${address.port}`;
+
+    try {
+      const InstallationTokenOctokit = Octokit.plugin(
+        createGithubInstallationTokenFormatPlugin(override),
+      ).defaults({baseUrl});
+      const app = new App({appId: 1, privateKey, Octokit: InstallationTokenOctokit});
+      const octokit = await getGithubInstallationOctokit(app, 123, baseUrl);
+
+      await octokit.rest.apps.listReposAccessibleToInstallation();
+
+      expect(calls).toEqual([
+        {
+          method: 'POST',
+          path: '/app/installations/123/access_tokens',
+          authorization: expect.stringMatching(BEARER_AUTHORIZATION),
+          tokenFormatOverride: override,
+        },
+        {
+          method: 'GET',
+          path: '/installation/repositories',
+          authorization,
+          tokenFormatOverride: undefined,
+        },
+      ]);
+    } finally {
+      server.close();
+      await once(server, 'close');
+    }
+  });
+});

package/src/api/github-octokit.ts

@@ -0,0 +1,49 @@
+import {type App, Octokit} from 'octokit';
+import {config, normalizedGithubApiBaseUrl} from '#config.js';
+import {GithubIntegrationProviderError} from '#core/errors.js';
+import {recordInstallationTokenFormat} from '#metrics/index.js';
+
+const INSTALLATION_TOKEN_REQUEST_PATH = /\/app\/installations\/[^/]+\/access_tokens(?:\?|$)/u;
+type GithubInstallationTokenFormatOverride = 'enabled' | 'disabled' | undefined;
+
+export function createGithubInstallationTokenFormatPlugin(
+  override: GithubInstallationTokenFormatOverride,
+): Parameters<typeof Octokit.plugin>[0] {
+  return (octokit) => {
+    octokit.hook.before('request', (options) => {
+      if (
+        !override ||
+        options.method !== 'POST' ||
+        !INSTALLATION_TOKEN_REQUEST_PATH.test(options.url)
+      ) {
+        return;
+      }
+
+      options.headers['x-github-stateless-s2s-token'] = override;
+    });
+  };
+}
+
+export const githubInstallationTokenFormatPlugin: Parameters<typeof Octokit.plugin>[0] =
+  createGithubInstallationTokenFormatPlugin(config.GITHUB_INSTALLATION_TOKEN_FORMAT_OVERRIDE);
+
+export async function getGithubInstallationOctokit(
+  app: App,
+  installationId: number,
+  baseUrl = normalizedGithubApiBaseUrl(),
+): Promise<Octokit> {
+  const authentication = (await app.octokit.auth({
+    type: 'installation',
+    installationId,
+  })) as {token?: unknown};
+
+  if (typeof authentication.token !== 'string') {
+    throw new GithubIntegrationProviderError(
+      'malformed-provider-response',
+      'GitHub installation authentication did not include a token',
+    );
+  }
+
+  recordInstallationTokenFormat(authentication.token);
+  return new Octokit({auth: authentication.token, baseUrl});
+}

package/src/api/installation-token-provider.test.ts

@@ -1,9 +1,15 @@
 import type {GetIntegrationConnectionByIdFn} from '@shipfox/api-integration-spi';
 import {GithubIntegrationProviderError} from '#core/errors.js';
-import {githubInstallationFactory} from '#test/index.js';
+import {
+  GITHUB_STATEFUL_INSTALLATION_TOKEN,
+  GITHUB_STATELESS_INSTALLATION_TOKEN,
+  githubInstallationFactory,
+} from '#test/index.js';
 import {encodeInstallationTokenEnvelope} from './installation-token-envelope.js';
 import {createGithubInstallationTokenProvider} from './installation-token-provider.js';
 
+const GITHUB_INSTALLATION_TOKEN_PATTERN = /^ghs_[A-Za-z0-9._-]{36,}$/u;
+
 const {appOptions, createInstallationAccessTokenMock, RequestErrorMock} = vi.hoisted(() => ({
   appOptions: [] as unknown[],
   createInstallationAccessTokenMock: vi.fn(),
@@ -28,6 +34,9 @@ vi.mock('octokit', () => ({
     }
   },
   Octokit: {
+    plugin() {
+      return this;
+    },
     defaults(options: unknown) {
       return {defaults: options};
     },
@@ -47,26 +56,49 @@ describe('GithubInstallationTokenProvider', () => {
 
   it('mints a broad installation token on a cache miss', async () => {
     createInstallationAccessTokenMock.mockResolvedValue({
-      data: {token: 'ghs_installationtoken', expires_at: '2026-06-10T12:00:00.000Z'},
+      data: {
+        token: GITHUB_STATELESS_INSTALLATION_TOKEN,
+        expires_at: '2026-06-10T12:00:00.000Z',
+      },
     });
     const provider = createGithubInstallationTokenProvider();
 
     const result = await provider.getInstallationAccessToken(1);
 
     expect(result).toEqual({
-      token: 'ghs_installationtoken',
+      token: GITHUB_STATELESS_INSTALLATION_TOKEN,
       expiresAt: new Date('2026-06-10T12:00:00.000Z'),
     });
+    expect(GITHUB_STATELESS_INSTALLATION_TOKEN).toMatch(GITHUB_INSTALLATION_TOKEN_PATTERN);
+    expect(GITHUB_STATELESS_INSTALLATION_TOKEN.slice(4).split('.')).toHaveLength(3);
     expect(createInstallationAccessTokenMock).toHaveBeenCalledWith({
       installation_id: 1,
     });
   });
 
+  it('passes through a stateful broad installation token', async () => {
+    createInstallationAccessTokenMock.mockResolvedValue({
+      data: {
+        token: GITHUB_STATEFUL_INSTALLATION_TOKEN,
+        expires_at: '2026-06-10T12:00:00.000Z',
+      },
+    });
+    const provider = createGithubInstallationTokenProvider();
+
+    const result = await provider.getInstallationAccessToken(1);
+
+    expect(result.token).toBe(GITHUB_STATEFUL_INSTALLATION_TOKEN);
+    expect(GITHUB_STATEFUL_INSTALLATION_TOKEN).not.toContain('.');
+  });
+
   it('returns a cached token without a second mint', async () => {
     vi.useFakeTimers();
     vi.setSystemTime(new Date('2026-06-10T11:00:00.000Z'));
     createInstallationAccessTokenMock.mockResolvedValue({
-      data: {token: 'ghs_installationtoken', expires_at: '2026-06-10T12:00:00.000Z'},
+      data: {
+        token: GITHUB_STATELESS_INSTALLATION_TOKEN,
+        expires_at: '2026-06-10T12:00:00.000Z',
+      },
     });
     const provider = createGithubInstallationTokenProvider();
 
@@ -151,7 +183,10 @@ describe('GithubInstallationTokenProvider', () => {
         updatedAt: new Date(),
       });
     createInstallationAccessTokenMock.mockResolvedValue({
-      data: {token: 'ghs_installationtoken', expires_at: '2026-06-10T12:00:00.000Z'},
+      data: {
+        token: GITHUB_STATELESS_INSTALLATION_TOKEN,
+        expires_at: '2026-06-10T12:00:00.000Z',
+      },
     });
     const provider = createGithubInstallationTokenProvider({
       getIntegrationConnectionById,
@@ -174,6 +209,10 @@ describe('GithubInstallationTokenProvider', () => {
     const second = await provider.getInstallationAccessToken(installationId);
 
     expect(first).toEqual(second);
+    expect(first.token).toBe(GITHUB_STATELESS_INSTALLATION_TOKEN);
+    expect(values.get(`${workspaceId}:${installationId}`)).toContain(
+      GITHUB_STATELESS_INSTALLATION_TOKEN,
+    );
     expect(lockCalls).toBe(1);
     expect(createInstallationAccessTokenMock).toHaveBeenCalledTimes(1);
   });

package/src/api/installation-token-provider.ts

@@ -4,8 +4,9 @@ import {config, normalizedGithubApiBaseUrl, normalizedGithubPrivateKey} from '#c
 import {GithubIntegrationProviderError} from '#core/errors.js';
 import {withInstallationTokenLock} from '#db/installation-token-lock.js';
 import {getGithubInstallationByInstallationId} from '#db/installations.js';
-import {recordInstallationTokenLookup} from '#metrics/index.js';
+import {recordInstallationTokenFormat, recordInstallationTokenLookup} from '#metrics/index.js';
 import {type GithubInstallationAccessToken, mapGithubError} from './client.js';
+import {githubInstallationTokenFormatPlugin} from './github-octokit.js';
 import {
   githubInstallationTokenNamespace,
   TOKEN_REFRESH_MARGIN_MS,
@@ -66,6 +67,8 @@ class OctokitGithubInstallationTokenProvider implements GithubInstallationTokenP
       );
     }
 
+    recordInstallationTokenFormat(response.data.token);
+
     const expiresAt = new Date(response.data.expires_at);
     if (Number.isNaN(expiresAt.getTime())) {
       throw new GithubIntegrationProviderError(
@@ -86,7 +89,7 @@ class OctokitGithubInstallationTokenProvider implements GithubInstallationTokenP
       this.app = new App({
         appId: config.GITHUB_APP_ID,
         privateKey: normalizedGithubPrivateKey(),
-        Octokit: Octokit.defaults({
+        Octokit: Octokit.plugin(githubInstallationTokenFormatPlugin).defaults({
           baseUrl: normalizedGithubApiBaseUrl(),
           throttle: {
             onRateLimit: (

package/src/config.ts

@@ -29,6 +29,11 @@ export const config = createConfig({
     desc: 'Base URL used for GitHub REST API requests. Set this only for GitHub Enterprise Server or a compatible test server.',
     default: 'https://api.github.com',
   }),
+  GITHUB_INSTALLATION_TOKEN_FORMAT_OVERRIDE: str({
+    desc: 'Temporary GitHub installation token format override. Set this to enabled to request stateless tokens, disabled to request stateful tokens, or leave it unset to follow the GitHub rollout.',
+    choices: ['enabled', 'disabled'] as const,
+    default: undefined,
+  }),
   GITHUB_INSTALL_STATE_SECRET: str({
     desc: 'Secret used to sign the state token that protects the GitHub App install flow. Required.',
   }),