@shipfox/api-integration-github 2.0.0

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

@@ -0,0 +1,241 @@
+import type {GetIntegrationConnectionByIdFn} from '@shipfox/api-integration-core-dto';
+import {GithubIntegrationProviderError} from '#core/errors.js';
+import {githubInstallationFactory} from '#test/index.js';
+import {encodeInstallationTokenEnvelope} from './installation-token-envelope.js';
+import {createGithubInstallationTokenProvider} from './installation-token-provider.js';
+
+const {appOptions, createInstallationAccessTokenMock, RequestErrorMock} = vi.hoisted(() => ({
+  appOptions: [] as unknown[],
+  createInstallationAccessTokenMock: vi.fn(),
+  RequestErrorMock: class RequestError extends Error {
+    constructor(
+      message: string,
+      public readonly status: number,
+    ) {
+      super(message);
+    }
+  },
+}));
+
+vi.mock('octokit', () => ({
+  App: class App {
+    octokit = {
+      rest: {apps: {createInstallationAccessToken: createInstallationAccessTokenMock}},
+    };
+
+    constructor(options: unknown) {
+      appOptions.push(options);
+    }
+  },
+  Octokit: {
+    defaults(options: unknown) {
+      return {defaults: options};
+    },
+  },
+  RequestError: RequestErrorMock,
+}));
+
+describe('GithubInstallationTokenProvider', () => {
+  beforeEach(() => {
+    appOptions.length = 0;
+    createInstallationAccessTokenMock.mockReset();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  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'},
+    });
+    const provider = createGithubInstallationTokenProvider();
+
+    const result = await provider.getInstallationAccessToken(1);
+
+    expect(result).toEqual({
+      token: 'ghs_installationtoken',
+      expiresAt: new Date('2026-06-10T12:00:00.000Z'),
+    });
+    expect(createInstallationAccessTokenMock).toHaveBeenCalledWith({
+      installation_id: 1,
+    });
+  });
+
+  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'},
+    });
+    const provider = createGithubInstallationTokenProvider();
+
+    const first = await provider.getInstallationAccessToken(1);
+    const second = await provider.getInstallationAccessToken(1);
+
+    expect(first).toEqual(second);
+    expect(createInstallationAccessTokenMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('mints a fresh token inside the expiry refresh margin', async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-06-10T12:00:00.000Z'));
+    createInstallationAccessTokenMock
+      .mockResolvedValueOnce({
+        data: {token: 'ghs_first', expires_at: '2026-06-10T12:10:00.000Z'},
+      })
+      .mockResolvedValueOnce({
+        data: {token: 'ghs_second', expires_at: '2026-06-10T13:00:00.000Z'},
+      });
+    const provider = createGithubInstallationTokenProvider();
+
+    const first = await provider.getInstallationAccessToken(1);
+    vi.setSystemTime(new Date('2026-06-10T12:06:00.000Z'));
+    const second = await provider.getInstallationAccessToken(1);
+
+    expect(first.token).toBe('ghs_first');
+    expect(second.token).toBe('ghs_second');
+    expect(createInstallationAccessTokenMock).toHaveBeenCalledTimes(2);
+  });
+
+  it('dedupes concurrent cold-cache mints for one installation', async () => {
+    let resolveMint: (
+      value: Awaited<ReturnType<typeof createInstallationAccessTokenMock>>,
+    ) => void = (_value) => {
+      throw new Error('Mint promise was not initialized');
+    };
+    createInstallationAccessTokenMock.mockReturnValue(
+      new Promise((resolve) => {
+        resolveMint = resolve;
+      }),
+    );
+    const provider = createGithubInstallationTokenProvider();
+
+    const first = provider.getInstallationAccessToken(1);
+    const second = provider.getInstallationAccessToken(1);
+    resolveMint({
+      data: {token: 'ghs_installationtoken', expires_at: '2026-06-10T12:00:00.000Z'},
+    });
+    const results = await Promise.all([first, second]);
+
+    expect(results).toEqual([
+      {token: 'ghs_installationtoken', expiresAt: new Date('2026-06-10T12:00:00.000Z')},
+      {token: 'ghs_installationtoken', expiresAt: new Date('2026-06-10T12:00:00.000Z')},
+    ]);
+    expect(createInstallationAccessTokenMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('composes the RAM tier over the shared token cache', async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(new Date('2026-06-10T11:00:00.000Z'));
+    const installationId = Math.floor(Math.random() * 1_000_000_000);
+    const connectionId = crypto.randomUUID();
+    const workspaceId = crypto.randomUUID();
+    await githubInstallationFactory.create({installationId: String(installationId), connectionId});
+    const values = new Map<string, string>();
+    let lockCalls = 0;
+    function withLock<T>(_installationId: number, fn: () => Promise<T>) {
+      lockCalls += 1;
+      return fn().then((value) => ({acquired: true as const, value}));
+    }
+    const getIntegrationConnectionById: GetIntegrationConnectionByIdFn = () =>
+      Promise.resolve({
+        id: connectionId,
+        workspaceId,
+        provider: 'github',
+        externalAccountId: String(installationId),
+        slug: 'github_shipfox',
+        displayName: 'GitHub shipfox',
+        lifecycleStatus: 'active',
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      });
+    createInstallationAccessTokenMock.mockResolvedValue({
+      data: {token: 'ghs_installationtoken', expires_at: '2026-06-10T12:00:00.000Z'},
+    });
+    const provider = createGithubInstallationTokenProvider({
+      getIntegrationConnectionById,
+      secretStore: {
+        read: (readWorkspaceId, readInstallationId) =>
+          Promise.resolve(values.get(`${readWorkspaceId}:${readInstallationId}`) ?? null),
+        write: (writeWorkspaceId, writeInstallationId, envelope) => {
+          values.set(
+            `${writeWorkspaceId}:${writeInstallationId}`,
+            encodeInstallationTokenEnvelope(envelope),
+          );
+          return Promise.resolve();
+        },
+      },
+      withLock,
+      now: () => new Date(),
+    });
+
+    const first = await provider.getInstallationAccessToken(installationId);
+    const second = await provider.getInstallationAccessToken(installationId);
+
+    expect(first).toEqual(second);
+    expect(lockCalls).toBe(1);
+    expect(createInstallationAccessTokenMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('configures throttle retry handlers on the mint octokit', async () => {
+    createInstallationAccessTokenMock.mockResolvedValue({
+      data: {token: 'ghs_installationtoken', expires_at: '2026-06-10T12:00:00.000Z'},
+    });
+    const provider = createGithubInstallationTokenProvider();
+
+    await provider.getInstallationAccessToken(1);
+
+    expect(appOptions).toEqual([
+      expect.objectContaining({
+        Octokit: {
+          defaults: {
+            baseUrl: 'https://api.github.com',
+            throttle: {
+              onRateLimit: expect.any(Function),
+              onSecondaryRateLimit: expect.any(Function),
+            },
+          },
+        },
+      }),
+    ]);
+  });
+
+  it('maps missing installations to an installation-not-found provider error', async () => {
+    createInstallationAccessTokenMock.mockRejectedValue(new RequestErrorMock('Not Found', 404));
+    const provider = createGithubInstallationTokenProvider();
+
+    const result = provider.getInstallationAccessToken(1);
+
+    await expect(result).rejects.toMatchObject({
+      reason: 'installation-not-found',
+    });
+  });
+
+  it('rejects a response without a token', async () => {
+    createInstallationAccessTokenMock.mockResolvedValue({
+      data: {expires_at: '2026-06-10T12:00:00.000Z'},
+    });
+    const provider = createGithubInstallationTokenProvider();
+
+    const result = provider.getInstallationAccessToken(1);
+
+    await expect(result).rejects.toMatchObject({
+      reason: 'malformed-provider-response',
+    });
+    await expect(result).rejects.toBeInstanceOf(GithubIntegrationProviderError);
+  });
+
+  it('rejects a response with a missing or unparseable expiry', async () => {
+    createInstallationAccessTokenMock.mockResolvedValue({
+      data: {token: 'ghs_installationtoken'},
+    });
+    const provider = createGithubInstallationTokenProvider();
+
+    const result = provider.getInstallationAccessToken(1);
+
+    await expect(result).rejects.toMatchObject({
+      reason: 'malformed-provider-response',
+    });
+  });
+});

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

@@ -0,0 +1,224 @@
+import type {GetIntegrationConnectionByIdFn} from '@shipfox/api-integration-core-dto';
+import {App, Octokit} from 'octokit';
+import {config, normalizedGithubApiBaseUrl, normalizedGithubPrivateKey} from '#config.js';
+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 {type GithubInstallationAccessToken, mapGithubError} from './client.js';
+import {
+  githubInstallationTokenNamespace,
+  TOKEN_REFRESH_MARGIN_MS,
+} from './installation-token-envelope.js';
+import {
+  type InstallationTokenCache,
+  type InstallationTokenSecretStore,
+  SharedInstallationTokenCache,
+  type SharedInstallationTokenCacheOptions,
+} from './shared-installation-token-cache.js';
+
+export interface GithubInstallationTokenProvider {
+  getInstallationAccessToken(installationId: number): Promise<GithubInstallationAccessToken>;
+}
+
+export interface GithubInstallationTokenProviderOptions {
+  cache?: InstallationTokenCache | undefined;
+  getIntegrationConnectionById?: GetIntegrationConnectionByIdFn | undefined;
+  secretStore?: InstallationTokenSecretStore | undefined;
+  withLock?: SharedInstallationTokenCacheOptions['withLock'] | undefined;
+  now?: (() => Date) | undefined;
+}
+
+export function createGithubInstallationTokenProvider(
+  options: GithubInstallationTokenProviderOptions = {},
+): GithubInstallationTokenProvider {
+  return new OctokitGithubInstallationTokenProvider(createInstallationTokenCache(options));
+}
+
+class OctokitGithubInstallationTokenProvider implements GithubInstallationTokenProvider {
+  private app: App | undefined;
+
+  constructor(
+    private readonly cache: InstallationTokenCache = new InMemoryInstallationTokenCache(),
+  ) {}
+
+  getInstallationAccessToken(installationId: number): Promise<GithubInstallationAccessToken> {
+    return this.cache.getOrMint(installationId, () =>
+      this.mintInstallationAccessToken(installationId),
+    );
+  }
+
+  private async mintInstallationAccessToken(
+    installationId: number,
+  ): Promise<GithubInstallationAccessToken> {
+    const response = await mapGithubError(
+      () =>
+        this.getApp().octokit.rest.apps.createInstallationAccessToken({
+          installation_id: installationId,
+        }),
+      'installation-not-found',
+    );
+
+    if (typeof response.data.token !== 'string') {
+      throw new GithubIntegrationProviderError(
+        'malformed-provider-response',
+        'GitHub installation access token response did not include a token',
+      );
+    }
+
+    const expiresAt = new Date(response.data.expires_at);
+    if (Number.isNaN(expiresAt.getTime())) {
+      throw new GithubIntegrationProviderError(
+        'malformed-provider-response',
+        'GitHub installation access token response did not include a valid expiry',
+      );
+    }
+
+    return {
+      token: response.data.token,
+      expiresAt,
+      ...(response.data.permissions === undefined ? {} : {permissions: response.data.permissions}),
+    };
+  }
+
+  private getApp(): App {
+    if (!this.app) {
+      this.app = new App({
+        appId: config.GITHUB_APP_ID,
+        privateKey: normalizedGithubPrivateKey(),
+        Octokit: Octokit.defaults({
+          baseUrl: normalizedGithubApiBaseUrl(),
+          throttle: {
+            onRateLimit: (
+              _retryAfter: number,
+              _options: unknown,
+              _octokit: unknown,
+              retryCount: number,
+            ) => retryCount === 0,
+            onSecondaryRateLimit: (
+              _retryAfter: number,
+              _options: unknown,
+              _octokit: unknown,
+              retryCount: number,
+            ) => retryCount === 0,
+          },
+        }),
+      });
+    }
+    return this.app;
+  }
+}
+
+class InMemoryInstallationTokenCache implements InstallationTokenCache {
+  private readonly tokens = new Map<number, GithubInstallationAccessToken>();
+  private readonly inFlightMints = new Map<number, Promise<GithubInstallationAccessToken>>();
+
+  constructor(
+    private readonly options: {
+      refreshMarginMs: number;
+      now: () => Date;
+    } = {
+      refreshMarginMs: TOKEN_REFRESH_MARGIN_MS,
+      now: () => new Date(),
+    },
+  ) {}
+
+  getOrMint(
+    installationId: number,
+    mint: () => Promise<GithubInstallationAccessToken>,
+  ): Promise<GithubInstallationAccessToken> {
+    const cached = this.tokens.get(installationId);
+    if (cached && !this.isInsideRefreshMargin(cached.expiresAt)) {
+      recordInstallationTokenLookup('ram-hit');
+      return Promise.resolve(cached);
+    }
+
+    const inFlightMint = this.inFlightMints.get(installationId);
+    if (inFlightMint) return inFlightMint;
+
+    const freshToken = mint()
+      .then((token) => {
+        this.tokens.set(installationId, token);
+        return token;
+      })
+      .finally(() => {
+        this.inFlightMints.delete(installationId);
+      });
+    this.inFlightMints.set(installationId, freshToken);
+    return freshToken;
+  }
+
+  private isInsideRefreshMargin(expiresAt: Date): boolean {
+    return expiresAt.getTime() <= this.options.now().getTime() + this.options.refreshMarginMs;
+  }
+}
+
+class TieredInstallationTokenCache implements InstallationTokenCache {
+  constructor(
+    private readonly ram: InstallationTokenCache,
+    private readonly shared: InstallationTokenCache,
+  ) {}
+
+  getOrMint(
+    installationId: number,
+    mint: () => Promise<GithubInstallationAccessToken>,
+  ): Promise<GithubInstallationAccessToken> {
+    return this.ram.getOrMint(installationId, () => this.shared.getOrMint(installationId, mint));
+  }
+}
+
+function createInstallationTokenCache(
+  options: GithubInstallationTokenProviderOptions,
+): InstallationTokenCache {
+  if (options.cache) return options.cache;
+
+  const ram = new InMemoryInstallationTokenCache({
+    refreshMarginMs: TOKEN_REFRESH_MARGIN_MS,
+    now: options.now ?? (() => new Date()),
+  });
+  if (!options.getIntegrationConnectionById || !options.secretStore) return ram;
+
+  const shared = new SharedInstallationTokenCache({
+    secretStore: options.secretStore,
+    withLock: options.withLock ?? withInstallationTokenLock,
+    resolveWorkspaceId: createGithubInstallationWorkspaceResolver(
+      options.getIntegrationConnectionById,
+    ),
+    now: options.now,
+  });
+  return new TieredInstallationTokenCache(ram, shared);
+}
+
+function createGithubInstallationWorkspaceResolver(
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn,
+) {
+  return async (installationId: number): Promise<string> => {
+    const installation = await getGithubInstallationByInstallationId(String(installationId));
+    if (!installation) {
+      throw new GithubIntegrationProviderError(
+        'installation-not-found',
+        `GitHub installation not found: ${installationId}`,
+      );
+    }
+
+    const connection = await getIntegrationConnectionById(installation.connectionId);
+    if (!connection) {
+      throw new GithubIntegrationProviderError(
+        'installation-not-found',
+        `GitHub installation connection not found: ${installation.connectionId}`,
+      );
+    }
+    return connection.workspaceId;
+  };
+}
+
+export function deleteGithubInstallationTokenSecret(params: {
+  workspaceId: string;
+  installationId: number;
+  deleteSecrets: (params: {workspaceId: string; namespace: string}) => Promise<number>;
+}): Promise<number> {
+  return params.deleteSecrets({
+    workspaceId: params.workspaceId,
+    namespace: githubInstallationTokenNamespace(params.installationId),
+  });
+}