@shipfox/api-integration-github 2.0.0

package/src/core/errors.ts

@@ -0,0 +1,23 @@
+import {IntegrationProviderError} from '@shipfox/api-integration-core-dto';
+
+export class GithubIntegrationProviderError extends IntegrationProviderError {}
+
+export class GithubInstallStateError extends Error {}
+
+export class GithubInstallStateActorMismatchError extends Error {
+  constructor() {
+    super('GitHub install state was issued for a different user');
+  }
+}
+
+export class GithubInstallationNotAuthorizedError extends Error {
+  constructor(installationId: number) {
+    super(`GitHub installation is not accessible to the installing user: ${installationId}`);
+  }
+}
+
+export class GithubInstallationAlreadyLinkedError extends Error {
+  constructor(installationId: number | string) {
+    super(`GitHub installation is already linked to another Shipfox workspace: ${installationId}`);
+  }
+}

package/src/core/install.test.ts

@@ -0,0 +1,238 @@
+import type {IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import type {GithubApiClient} from '#api/client.js';
+import {
+  GithubInstallationAlreadyLinkedError,
+  GithubInstallationNotAuthorizedError,
+  GithubInstallStateActorMismatchError,
+} from './errors.js';
+import {handleGithubCallback} from './install.js';
+import {signGithubInstallState} from './state.js';
+
+function githubClient(overrides: Partial<GithubApiClient> = {}): GithubApiClient {
+  return {
+    exchangeOAuthCode: vi.fn(() => Promise.resolve('user-token')),
+    listUserInstallations: vi.fn(({cursor}) =>
+      Promise.resolve({
+        installationIds: cursor ? [123] : [999],
+        nextCursor: cursor ? null : '2',
+      }),
+    ),
+    getInstallation: vi.fn(() =>
+      Promise.resolve({
+        id: 123,
+        account: {login: 'shipfox', type: 'Organization'},
+        repositorySelection: 'all',
+        suspendedAt: null,
+        htmlUrl: 'https://github.com/apps/shipfox/installations/123',
+        raw: {id: 123},
+      }),
+    ),
+    listInstallationRepositories: vi.fn(() =>
+      Promise.resolve({repositories: [], nextCursor: null}),
+    ),
+    getRepository: vi.fn(() => {
+      throw new Error('not used');
+    }),
+    listRepositoryFiles: vi.fn(() => Promise.resolve({files: [], nextCursor: null})),
+    fetchRepositoryFile: vi.fn(() => {
+      throw new Error('not used');
+    }),
+    createInstallationAccessToken: vi.fn(() =>
+      Promise.resolve({
+        token: 'ghs_installationtoken',
+        expiresAt: new Date('2026-06-10T12:00:00.000Z'),
+      }),
+    ),
+    ...overrides,
+  };
+}
+
+function githubConnection(
+  overrides: Partial<IntegrationConnection<'github'>> = {},
+): IntegrationConnection<'github'> {
+  return {
+    id: crypto.randomUUID(),
+    workspaceId: crypto.randomUUID(),
+    provider: 'github',
+    externalAccountId: '123',
+    slug: 'github_shipfox',
+    displayName: 'GitHub shipfox',
+    lifecycleStatus: 'active',
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+describe('handleGithubCallback', () => {
+  it('paginates user installations before creating a connection', async () => {
+    const workspaceId = crypto.randomUUID();
+    const userId = crypto.randomUUID();
+    const github = githubClient();
+    const state = signGithubInstallState({workspaceId, userId});
+    const requireWorkspaceMembership = vi.fn(() => Promise.resolve());
+    const getExistingGithubConnection = vi.fn(() => Promise.resolve(undefined));
+    const connectGithubInstallation = vi.fn(() => Promise.resolve(githubConnection({workspaceId})));
+
+    const result = await handleGithubCallback({
+      github,
+      code: 'code',
+      installationId: 123,
+      state,
+      sessionUserId: userId,
+      sessionMemberships: [],
+      requireWorkspaceMembership,
+      getExistingGithubConnection,
+      connectGithubInstallation,
+    });
+
+    expect(result.externalAccountId).toBe('123');
+    expect(github.listUserInstallations).toHaveBeenCalledTimes(2);
+    expect(requireWorkspaceMembership).toHaveBeenCalledWith({
+      workspaceId,
+      userId,
+      memberships: [],
+    });
+    expect(getExistingGithubConnection).toHaveBeenCalledWith({installationId: '123'});
+    expect(connectGithubInstallation).toHaveBeenCalledWith(
+      expect.objectContaining({
+        workspaceId,
+        installationId: '123',
+        displayName: 'GitHub shipfox',
+        installerUserId: userId,
+        installation: expect.objectContaining({installerUserId: userId}),
+      }),
+    );
+  });
+
+  it('rejects spoofed installation ids', async () => {
+    const userId = crypto.randomUUID();
+    const state = signGithubInstallState({workspaceId: crypto.randomUUID(), userId});
+    const github = githubClient({
+      listUserInstallations: vi.fn(() =>
+        Promise.resolve({installationIds: [999], nextCursor: null}),
+      ),
+    });
+
+    const result = handleGithubCallback({
+      github,
+      code: 'code',
+      installationId: 123,
+      state,
+      sessionUserId: userId,
+      sessionMemberships: [],
+      requireWorkspaceMembership: vi.fn(() => Promise.resolve()),
+      getExistingGithubConnection: vi.fn(() => Promise.resolve(undefined)),
+      connectGithubInstallation: vi.fn(() => {
+        throw new Error('must not connect');
+      }),
+    });
+
+    await expect(result).rejects.toBeInstanceOf(GithubInstallationNotAuthorizedError);
+  });
+
+  it('rejects callbacks completed by a different session user than the one in state', async () => {
+    const stateUserId = crypto.randomUUID();
+    const state = signGithubInstallState({
+      workspaceId: crypto.randomUUID(),
+      userId: stateUserId,
+    });
+    const github = githubClient();
+
+    const result = handleGithubCallback({
+      github,
+      code: 'code',
+      installationId: 123,
+      state,
+      sessionUserId: crypto.randomUUID(),
+      sessionMemberships: [],
+      requireWorkspaceMembership: vi.fn(() => Promise.resolve()),
+      getExistingGithubConnection: vi.fn(() => Promise.resolve(undefined)),
+      connectGithubInstallation: vi.fn(() => {
+        throw new Error('must not connect');
+      }),
+    });
+
+    await expect(result).rejects.toBeInstanceOf(GithubInstallStateActorMismatchError);
+    expect(github.exchangeOAuthCode).not.toHaveBeenCalled();
+  });
+
+  it('returns the existing connection without re-running OAuth on reload', async () => {
+    const workspaceId = crypto.randomUUID();
+    const userId = crypto.randomUUID();
+    const state = signGithubInstallState({workspaceId, userId});
+    const github = githubClient();
+    const existing = githubConnection({workspaceId, lifecycleStatus: 'active'});
+    const connectGithubInstallation = vi.fn(() => {
+      throw new Error('must not reconnect');
+    });
+
+    const result = await handleGithubCallback({
+      github,
+      code: 'code',
+      installationId: 123,
+      state,
+      sessionUserId: userId,
+      sessionMemberships: [],
+      requireWorkspaceMembership: vi.fn(() => Promise.resolve()),
+      getExistingGithubConnection: vi.fn(() => Promise.resolve(existing)),
+      connectGithubInstallation,
+    });
+
+    expect(result).toBe(existing);
+    expect(github.exchangeOAuthCode).not.toHaveBeenCalled();
+    expect(connectGithubInstallation).not.toHaveBeenCalled();
+  });
+
+  it('refuses to claim an installation already linked to another workspace', async () => {
+    const workspaceId = crypto.randomUUID();
+    const userId = crypto.randomUUID();
+    const state = signGithubInstallState({workspaceId, userId});
+    const github = githubClient();
+    const existing = githubConnection({workspaceId: crypto.randomUUID()});
+
+    const result = handleGithubCallback({
+      github,
+      code: 'code',
+      installationId: 123,
+      state,
+      sessionUserId: userId,
+      sessionMemberships: [],
+      requireWorkspaceMembership: vi.fn(() => Promise.resolve()),
+      getExistingGithubConnection: vi.fn(() => Promise.resolve(existing)),
+      connectGithubInstallation: vi.fn(() => {
+        throw new Error('must not connect');
+      }),
+    });
+
+    await expect(result).rejects.toBeInstanceOf(GithubInstallationAlreadyLinkedError);
+    expect(github.exchangeOAuthCode).not.toHaveBeenCalled();
+  });
+
+  it('re-runs the install flow when the existing connection is not active', async () => {
+    const workspaceId = crypto.randomUUID();
+    const userId = crypto.randomUUID();
+    const state = signGithubInstallState({workspaceId, userId});
+    const github = githubClient();
+    const existing = githubConnection({workspaceId, lifecycleStatus: 'disabled'});
+    const connectGithubInstallation = vi.fn(() =>
+      Promise.resolve(githubConnection({workspaceId, lifecycleStatus: 'active'})),
+    );
+
+    const result = await handleGithubCallback({
+      github,
+      code: 'code',
+      installationId: 123,
+      state,
+      sessionUserId: userId,
+      sessionMemberships: [],
+      requireWorkspaceMembership: vi.fn(() => Promise.resolve()),
+      getExistingGithubConnection: vi.fn(() => Promise.resolve(existing)),
+      connectGithubInstallation,
+    });
+
+    expect(result.lifecycleStatus).toBe('active');
+    expect(github.exchangeOAuthCode).toHaveBeenCalled();
+    expect(connectGithubInstallation).toHaveBeenCalled();
+  });
+});

package/src/core/install.ts

@@ -0,0 +1,119 @@
+import type {UserContextMembership} from '@shipfox/api-auth-context';
+import type {IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import type {GithubApiClient, GithubInstallationDetails} from '#api/client.js';
+import {
+  GithubInstallationAlreadyLinkedError,
+  GithubInstallationNotAuthorizedError,
+  GithubInstallStateActorMismatchError,
+} from './errors.js';
+import {verifyGithubInstallState} from './state.js';
+
+export interface ConnectGithubInstallationInput {
+  workspaceId: string;
+  installationId: string;
+  displayName: string;
+  installerUserId: string;
+  installation: {
+    installationId: string;
+    accountLogin: string;
+    accountType: string;
+    repositorySelection: string;
+    suspendedAt: Date | null;
+    deletedAt: Date | null;
+    latestEvent: Record<string, unknown>;
+    installerUserId: string;
+  };
+}
+
+export interface HandleGithubCallbackParams {
+  github: GithubApiClient;
+  code: string;
+  installationId: number;
+  state: string;
+  sessionUserId: string;
+  sessionMemberships: ReadonlyArray<UserContextMembership>;
+  requireWorkspaceMembership: (params: {
+    workspaceId: string;
+    userId: string;
+    memberships: ReadonlyArray<UserContextMembership>;
+  }) => Promise<unknown>;
+  getExistingGithubConnection: (input: {
+    installationId: string;
+  }) => Promise<IntegrationConnection<'github'> | undefined>;
+  connectGithubInstallation: (
+    input: ConnectGithubInstallationInput,
+  ) => Promise<IntegrationConnection<'github'>>;
+}
+
+export async function handleGithubCallback(
+  params: HandleGithubCallbackParams,
+): Promise<IntegrationConnection<'github'>> {
+  const claims = verifyGithubInstallState(params.state);
+  if (claims.userId !== params.sessionUserId) {
+    throw new GithubInstallStateActorMismatchError();
+  }
+  await params.requireWorkspaceMembership({
+    workspaceId: claims.workspaceId,
+    userId: claims.userId,
+    memberships: params.sessionMemberships,
+  });
+
+  const installationIdStr = String(params.installationId);
+  const existing = await params.getExistingGithubConnection({installationId: installationIdStr});
+  if (existing && existing.workspaceId !== claims.workspaceId) {
+    throw new GithubInstallationAlreadyLinkedError(params.installationId);
+  }
+  if (existing && existing.lifecycleStatus === 'active') {
+    return existing;
+  }
+
+  const userAccessToken = await params.github.exchangeOAuthCode(params.code);
+  const accessible = await userCanAccessInstallation({
+    github: params.github,
+    userAccessToken,
+    installationId: params.installationId,
+  });
+  if (!accessible) throw new GithubInstallationNotAuthorizedError(params.installationId);
+
+  const installation = await params.github.getInstallation(params.installationId);
+  return await params.connectGithubInstallation({
+    workspaceId: claims.workspaceId,
+    installationId: installationIdStr,
+    displayName: `GitHub ${installation.account.login}`,
+    installerUserId: claims.userId,
+    installation: toConnectionInstallationInput(installation, claims.userId),
+  });
+}
+
+async function userCanAccessInstallation(params: {
+  github: GithubApiClient;
+  userAccessToken: string;
+  installationId: number;
+}): Promise<boolean> {
+  let cursor: string | undefined;
+  do {
+    const page = await params.github.listUserInstallations({
+      userAccessToken: params.userAccessToken,
+      cursor,
+    });
+    if (page.installationIds.includes(params.installationId)) return true;
+    cursor = page.nextCursor ?? undefined;
+  } while (cursor);
+  return false;
+}
+
+function toConnectionInstallationInput(
+  installation: GithubInstallationDetails,
+  installerUserId: string,
+) {
+  return {
+    installationId: String(installation.id),
+    accountLogin: installation.account.login,
+    accountType: installation.account.type,
+    repositorySelection: installation.repositorySelection,
+    suspendedAt: installation.suspendedAt,
+    deletedAt: null,
+    latestEvent: installation.raw,
+    installerUserId,
+  };
+}

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

@@ -0,0 +1,327 @@
+import type {GithubApiClient} from '#api/client.js';
+import {githubInstallationFactory} from '#test/index.js';
+import {GithubIntegrationProviderError} from './errors.js';
+import {GithubSourceControlProvider} from './source-control.js';
+
+function githubClient(overrides: Partial<GithubApiClient> = {}): GithubApiClient {
+  return {
+    exchangeOAuthCode: vi.fn(() => Promise.resolve('token')),
+    listUserInstallations: vi.fn(() => Promise.resolve({installationIds: [], nextCursor: null})),
+    getInstallation: vi.fn(() => {
+      throw new Error('not used');
+    }),
+    listInstallationRepositories: vi.fn(() =>
+      Promise.resolve({
+        repositories: [
+          {
+            id: 42,
+            ownerLogin: 'shipfox',
+            name: 'platform',
+            fullName: 'shipfox/platform',
+            defaultBranch: 'main',
+            private: true,
+            visibility: 'private',
+            cloneUrl: 'https://github.com/shipfox/platform.git',
+            htmlUrl: 'https://github.com/shipfox/platform',
+          },
+        ],
+        nextCursor: '2',
+      }),
+    ),
+    getRepository: vi.fn(() =>
+      Promise.resolve({
+        id: 42,
+        ownerLogin: 'shipfox',
+        name: 'platform',
+        fullName: 'shipfox/platform',
+        defaultBranch: 'main',
+        private: true,
+        visibility: 'private',
+        cloneUrl: 'https://github.com/shipfox/platform.git',
+        htmlUrl: 'https://github.com/shipfox/platform',
+      }),
+    ),
+    listRepositoryFiles: vi.fn(() =>
+      Promise.resolve({
+        files: [{path: '.shipfox/workflows/ci.yml', size: 64}],
+        nextCursor: null,
+      }),
+    ),
+    fetchRepositoryFile: vi.fn(() =>
+      Promise.resolve({
+        path: '.shipfox/workflows/ci.yml',
+        content: 'name: CI\njobs:\n  build:\n    steps:\n      - run: pnpm test\n',
+        size: 58,
+      }),
+    ),
+    createInstallationAccessToken: vi.fn(() =>
+      Promise.resolve({
+        token: 'ghs_installationtoken',
+        expiresAt: new Date('2026-06-10T12:00:00.000Z'),
+      }),
+    ),
+    ...overrides,
+  };
+}
+
+describe('GithubSourceControlProvider', () => {
+  let connectionId: string;
+  let installationId: number;
+
+  beforeEach(() => {
+    connectionId = crypto.randomUUID();
+    installationId = Math.floor(Math.random() * 1_000_000) + 1;
+  });
+
+  async function createInstallation(): Promise<void> {
+    await githubInstallationFactory.create({
+      connectionId,
+      installationId: String(installationId),
+      latestEvent: {id: 123},
+    });
+  }
+
+  function connection() {
+    return {
+      id: connectionId,
+      workspaceId: crypto.randomUUID(),
+      provider: 'github' as const,
+      externalAccountId: '123',
+      slug: 'github_shipfox',
+      displayName: 'GitHub shipfox',
+      lifecycleStatus: 'active' as const,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+  }
+
+  it('lists repositories using installation auth metadata', async () => {
+    await createInstallation();
+    const github = githubClient();
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = await provider.listRepositories({
+      connection: connection(),
+      limit: 50,
+    });
+
+    expect(result.repositories[0]?.externalRepositoryId).toBe('github:42');
+    expect(result.repositories[0]?.visibility).toBe('private');
+    expect(result.nextCursor).toBe('2');
+    expect(github.listInstallationRepositories).toHaveBeenCalledWith({
+      installationId,
+      limit: 50,
+      cursor: undefined,
+    });
+  });
+
+  it('resolves repositories directly from the provider-owned repository id', async () => {
+    await createInstallation();
+    const github = githubClient();
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = await provider.resolveRepository({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+    });
+
+    expect(result.fullName).toBe('shipfox/platform');
+    expect(github.getRepository).toHaveBeenCalledWith({
+      installationId,
+      repositoryId: 42,
+    });
+    expect(github.listInstallationRepositories).not.toHaveBeenCalled();
+  });
+
+  it('rejects missing installation metadata', async () => {
+    const provider = new GithubSourceControlProvider(githubClient());
+
+    const result = provider.listRepositories({
+      connection: {
+        id: crypto.randomUUID(),
+        workspaceId: crypto.randomUUID(),
+        provider: 'github',
+        externalAccountId: '123',
+        slug: 'github_shipfox',
+        displayName: 'GitHub shipfox',
+        lifecycleStatus: 'active',
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+      limit: 50,
+    });
+
+    await expect(result).rejects.toBeInstanceOf(GithubIntegrationProviderError);
+  });
+
+  it('lists repository files using the provider-owned repository id', async () => {
+    await createInstallation();
+    const github = githubClient();
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = await provider.listFiles({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      ref: 'main',
+      prefix: '.shipfox/workflows/',
+      limit: 100,
+    });
+
+    expect(result.files[0]?.path).toBe('.shipfox/workflows/ci.yml');
+    expect(github.listRepositoryFiles).toHaveBeenCalledWith({
+      installationId,
+      repositoryId: 42,
+      ref: 'main',
+      prefix: '.shipfox/workflows/',
+      limit: 100,
+      cursor: undefined,
+    });
+  });
+
+  it('fetches repository file contents using the provider-owned repository id', async () => {
+    await createInstallation();
+    const github = githubClient();
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = await provider.fetchFile({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      ref: 'main',
+      path: '.shipfox/workflows/ci.yml',
+    });
+
+    expect(result.content).toContain('name: CI');
+    expect(github.fetchRepositoryFile).toHaveBeenCalledWith({
+      installationId,
+      repositoryId: 42,
+      ref: 'main',
+      path: '.shipfox/workflows/ci.yml',
+    });
+  });
+
+  it.each([
+    'shipfox/platform',
+    'github:',
+    'github:foo',
+    'github:foo/bar',
+    'github:42abc',
+    'github:-1',
+    'github:0',
+    'github:42.5',
+    'gitlab:42',
+    '',
+  ])('rejects malformed external repository id %s', async (externalRepositoryId) => {
+    await createInstallation();
+    const github = githubClient();
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = provider.resolveRepository({
+      connection: connection(),
+      externalRepositoryId,
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'repository-not-found'});
+    expect(github.getRepository).not.toHaveBeenCalled();
+  });
+
+  it('rejects oversized repository file contents', async () => {
+    await createInstallation();
+    const github = githubClient({
+      fetchRepositoryFile: vi.fn(() =>
+        Promise.resolve({
+          path: '.shipfox/workflows/huge.yml',
+          content: 'x'.repeat(1_000_001),
+          size: 1_000_001,
+        }),
+      ),
+    });
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = provider.fetchFile({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      ref: 'main',
+      path: '.shipfox/workflows/huge.yml',
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'content-too-large'});
+  });
+
+  it('creates a checkout spec with a clean url and short-lived credentials', async () => {
+    await createInstallation();
+    const github = githubClient();
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = await provider.createCheckoutSpec({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+      ref: 'feature/x',
+      permissions: {contents: 'write'},
+    });
+
+    expect(result).toEqual({
+      repositoryUrl: 'https://github.com/shipfox/platform.git',
+      ref: 'feature/x',
+      credentials: {
+        username: 'x-access-token',
+        token: 'ghs_installationtoken',
+        expiresAt: new Date('2026-06-10T12:00:00.000Z'),
+      },
+      gitAuthor: {
+        name: 'shipfox-test[bot]',
+        email: '1+shipfox-test[bot]@users.noreply.github.com',
+      },
+    });
+    expect(result.repositoryUrl).not.toContain('ghs_installationtoken');
+    expect(github.createInstallationAccessToken).toHaveBeenCalledWith({
+      installationId,
+      repositoryId: 42,
+      permissions: {contents: 'write'},
+    });
+  });
+
+  it('defaults the checkout ref to the repository default branch', async () => {
+    await createInstallation();
+    const github = githubClient();
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = await provider.createCheckoutSpec({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+    });
+
+    expect(result.ref).toBe('main');
+  });
+
+  it('propagates provider errors raised while minting the checkout token', async () => {
+    await createInstallation();
+    const github = githubClient({
+      createInstallationAccessToken: vi.fn(() =>
+        Promise.reject(new GithubIntegrationProviderError('access-denied', 'token denied')),
+      ),
+    });
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = provider.createCheckoutSpec({
+      connection: connection(),
+      externalRepositoryId: 'github:42',
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'access-denied'});
+  });
+
+  it('rejects a malformed external repository id before any api call', async () => {
+    await createInstallation();
+    const github = githubClient();
+    const provider = new GithubSourceControlProvider(github);
+
+    const result = provider.createCheckoutSpec({
+      connection: connection(),
+      externalRepositoryId: 'github:not-a-number',
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'repository-not-found'});
+    expect(github.getRepository).not.toHaveBeenCalled();
+    expect(github.createInstallationAccessToken).not.toHaveBeenCalled();
+  });
+});