@shipfox/api-integration-github 2.0.0

package/src/core/source-control.ts

@@ -0,0 +1,223 @@
+import {Buffer} from 'node:buffer';
+import {
+  buildProviderRepositoryId,
+  type CheckoutSpec,
+  type CreateCheckoutSpecInput,
+  type FetchFileInput,
+  type FilePage,
+  type FileSnapshot,
+  type IntegrationConnection,
+  type ListFilesInput,
+  type ListRepositoriesInput,
+  MAX_REPOSITORY_FILE_BYTES,
+  parseProviderRepositoryId,
+  type RepositoryPage,
+  type RepositorySnapshot,
+  type RepositoryVisibility,
+  type ResolveRepositoryInput,
+  type SourceControlProvider,
+} from '@shipfox/api-integration-core-dto';
+import type {GithubApiClient, GithubRepository} from '#api/client.js';
+import {config} from '#config.js';
+import {getGithubInstallationByConnectionId} from '#db/installations.js';
+import {GithubIntegrationProviderError} from './errors.js';
+
+type GithubIntegrationConnection = IntegrationConnection<'github'>;
+
+const GITHUB_PROVIDER = 'github';
+const GITHUB_APP_BOT_SUFFIX = '[bot]';
+const SEARCH_PAGE_SIZE = 100;
+const SEARCH_MAX_PAGES_PER_REQUEST = 5;
+
+export class GithubSourceControlProvider
+  implements SourceControlProvider<GithubIntegrationConnection>
+{
+  constructor(private readonly github: GithubApiClient) {}
+
+  async listRepositories(
+    input: ListRepositoriesInput<GithubIntegrationConnection>,
+  ): Promise<RepositoryPage> {
+    const installation = await getGithubInstallationByConnectionId(input.connection.id);
+    if (!installation) {
+      throw new GithubIntegrationProviderError(
+        'access-denied',
+        'GitHub installation details were not found for the connection',
+      );
+    }
+
+    const installationId = Number.parseInt(installation.installationId, 10);
+    const needle = input.search?.trim().toLowerCase();
+
+    if (!needle) {
+      const page = await this.github.listInstallationRepositories({
+        installationId,
+        limit: input.limit,
+        cursor: input.cursor,
+      });
+      return {
+        repositories: page.repositories.map(toRepositorySnapshot),
+        nextCursor: page.nextCursor,
+      };
+    }
+
+    const matches: RepositorySnapshot[] = [];
+    let cursor = input.cursor;
+    let pagesScanned = 0;
+    while (matches.length < input.limit && pagesScanned < SEARCH_MAX_PAGES_PER_REQUEST) {
+      const page = await this.github.listInstallationRepositories({
+        installationId,
+        limit: SEARCH_PAGE_SIZE,
+        cursor,
+      });
+      pagesScanned += 1;
+      for (const repo of page.repositories) {
+        if (repo.fullName.toLowerCase().includes(needle)) {
+          matches.push(toRepositorySnapshot(repo));
+        }
+      }
+      cursor = page.nextCursor ?? undefined;
+      if (!cursor) break;
+    }
+
+    return {
+      repositories: matches.slice(0, input.limit),
+      nextCursor: cursor ?? null,
+    };
+  }
+
+  async resolveRepository(
+    input: ResolveRepositoryInput<GithubIntegrationConnection>,
+  ): Promise<RepositorySnapshot> {
+    const installationId = await this.installationId(input.connection.id);
+    const {repositoryId} = parseGithubRepositoryLocator(input.externalRepositoryId);
+    const repository = await this.github.getRepository({
+      installationId,
+      repositoryId,
+    });
+
+    return toRepositorySnapshot(repository);
+  }
+
+  async listFiles(input: ListFilesInput<GithubIntegrationConnection>): Promise<FilePage> {
+    const installationId = await this.installationId(input.connection.id);
+    const {repositoryId} = parseGithubRepositoryLocator(input.externalRepositoryId);
+    const page = await this.github.listRepositoryFiles({
+      installationId,
+      repositoryId,
+      ref: input.ref,
+      prefix: input.prefix,
+      limit: input.limit,
+      cursor: input.cursor,
+    });
+
+    return {
+      files: page.files.map((file) => ({path: file.path, type: 'file', size: file.size})),
+      nextCursor: page.nextCursor,
+    };
+  }
+
+  async fetchFile(input: FetchFileInput<GithubIntegrationConnection>): Promise<FileSnapshot> {
+    const installationId = await this.installationId(input.connection.id);
+    const {repositoryId} = parseGithubRepositoryLocator(input.externalRepositoryId);
+    const file = await this.github.fetchRepositoryFile({
+      installationId,
+      repositoryId,
+      ref: input.ref,
+      path: input.path,
+    });
+
+    if (
+      file.size > MAX_REPOSITORY_FILE_BYTES ||
+      Buffer.byteLength(file.content, 'utf8') > MAX_REPOSITORY_FILE_BYTES
+    ) {
+      throw new GithubIntegrationProviderError(
+        'content-too-large',
+        'GitHub file content is larger than the supported limit',
+      );
+    }
+
+    return {
+      path: file.path,
+      ref: input.ref,
+      content: file.content,
+    };
+  }
+
+  async createCheckoutSpec(
+    input: CreateCheckoutSpecInput<GithubIntegrationConnection>,
+  ): Promise<CheckoutSpec> {
+    const installationId = await this.installationId(input.connection.id);
+    const {repositoryId} = parseGithubRepositoryLocator(input.externalRepositoryId);
+    const repository = await this.github.getRepository({installationId, repositoryId});
+    const ref = input.ref?.trim() || repository.defaultBranch;
+    const {token, expiresAt} = await this.github.createInstallationAccessToken({
+      installationId,
+      repositoryId,
+      permissions: input.permissions,
+    });
+    const gitAuthor = githubAppGitAuthor();
+
+    return {
+      repositoryUrl: repository.cloneUrl,
+      ref,
+      credentials: {username: 'x-access-token', token, expiresAt},
+      ...(gitAuthor ? {gitAuthor} : {}),
+    };
+  }
+
+  private async installationId(connectionId: string): Promise<number> {
+    const installation = await getGithubInstallationByConnectionId(connectionId);
+    if (!installation) {
+      throw new GithubIntegrationProviderError(
+        'access-denied',
+        'GitHub installation details were not found for the connection',
+      );
+    }
+
+    return Number.parseInt(installation.installationId, 10);
+  }
+}
+
+function githubAppGitAuthor(): CheckoutSpec['gitAuthor'] {
+  const appUsername = config.GITHUB_APP_USERNAME?.trim();
+  if (!appUsername) return undefined;
+  const name = appUsername.endsWith(GITHUB_APP_BOT_SUFFIX)
+    ? appUsername
+    : `${appUsername}${GITHUB_APP_BOT_SUFFIX}`;
+  return {name, email: `${config.GITHUB_APP_ID}+${name}@users.noreply.github.com`};
+}
+
+function toRepositorySnapshot(repository: GithubRepository): RepositorySnapshot {
+  return {
+    externalRepositoryId: buildProviderRepositoryId(GITHUB_PROVIDER, String(repository.id)),
+    owner: repository.ownerLogin,
+    name: repository.name,
+    fullName: repository.fullName,
+    defaultBranch: repository.defaultBranch,
+    visibility: toRepositoryVisibility(repository),
+    cloneUrl: repository.cloneUrl,
+    htmlUrl: repository.htmlUrl,
+  };
+}
+
+function parseGithubRepositoryLocator(externalRepositoryId: string): {
+  repositoryId: number;
+} {
+  const value = parseProviderRepositoryId(externalRepositoryId, GITHUB_PROVIDER);
+  const repositoryId = Number.parseInt(value, 10);
+  if (!Number.isInteger(repositoryId) || repositoryId <= 0 || String(repositoryId) !== value) {
+    throw new GithubIntegrationProviderError(
+      'repository-not-found',
+      `GitHub repository id ${externalRepositoryId} must follow the form ${GITHUB_PROVIDER}:<numeric-id>`,
+    );
+  }
+
+  return {repositoryId};
+}
+
+function toRepositoryVisibility(repository: GithubRepository): RepositoryVisibility {
+  if (repository.visibility === 'public') return 'public';
+  if (repository.visibility === 'private') return 'private';
+  if (repository.visibility === 'internal') return 'internal';
+  return repository.private ? 'private' : 'public';
+}

package/src/core/state.test.ts

@@ -0,0 +1,43 @@
+import {GithubInstallStateError} from './errors.js';
+import {signGithubInstallState, verifyGithubInstallState} from './state.js';
+
+describe('GitHub install state', () => {
+  it('verifies a signed state payload', () => {
+    const state = signGithubInstallState({
+      workspaceId: crypto.randomUUID(),
+      userId: crypto.randomUUID(),
+      nonce: 'nonce',
+      now: new Date('2026-04-30T00:00:00.000Z'),
+    });
+
+    const result = verifyGithubInstallState(state, new Date('2026-04-30T00:01:00.000Z'));
+
+    expect(result.workspaceId).toBeTypeOf('string');
+    expect(result.userId).toBeTypeOf('string');
+  });
+
+  it('rejects expired state payloads', () => {
+    const state = signGithubInstallState({
+      workspaceId: crypto.randomUUID(),
+      userId: crypto.randomUUID(),
+      nonce: 'nonce',
+      now: new Date('2026-04-30T00:00:00.000Z'),
+    });
+
+    const result = () => verifyGithubInstallState(state, new Date('2026-04-30T00:31:00.000Z'));
+
+    expect(result).toThrow(GithubInstallStateError);
+  });
+
+  it('rejects tampered state payloads', () => {
+    const state = signGithubInstallState({
+      workspaceId: crypto.randomUUID(),
+      userId: crypto.randomUUID(),
+      nonce: 'nonce',
+    });
+
+    const result = () => verifyGithubInstallState(`${state}tampered`);
+
+    expect(result).toThrow(GithubInstallStateError);
+  });
+});

package/src/core/state.ts

@@ -0,0 +1,85 @@
+import {createHmac, randomUUID, timingSafeEqual} from 'node:crypto';
+import {config} from '#config.js';
+import {GithubInstallStateError} from './errors.js';
+
+const STATE_TTL_SECONDS = 30 * 60;
+
+interface GithubInstallStatePayload {
+  workspaceId: string;
+  userId: string;
+  nonce: string;
+  expiresAt: number;
+}
+
+export interface GithubInstallStateClaims {
+  workspaceId: string;
+  userId: string;
+}
+
+export function signGithubInstallState(params: {
+  workspaceId: string;
+  userId: string;
+  nonce?: string | undefined;
+  now?: Date | undefined;
+}): string {
+  const now = params.now ?? new Date();
+  const payload: GithubInstallStatePayload = {
+    workspaceId: params.workspaceId,
+    userId: params.userId,
+    nonce: params.nonce ?? randomUUID(),
+    expiresAt: Math.floor(now.getTime() / 1000) + STATE_TTL_SECONDS,
+  };
+  const encodedPayload = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  return `${encodedPayload}.${sign(encodedPayload)}`;
+}
+
+export function verifyGithubInstallState(
+  state: string,
+  now: Date = new Date(),
+): GithubInstallStateClaims {
+  const [encodedPayload, signature, extra] = state.split('.');
+  if (!encodedPayload || !signature || extra !== undefined) {
+    throw new GithubInstallStateError('Invalid GitHub install state');
+  }
+
+  if (!constantTimeEqual(signature, sign(encodedPayload))) {
+    throw new GithubInstallStateError('Invalid GitHub install state signature');
+  }
+
+  const payload = parsePayload(encodedPayload);
+  if (payload.expiresAt < Math.floor(now.getTime() / 1000)) {
+    throw new GithubInstallStateError('Expired GitHub install state');
+  }
+
+  return {workspaceId: payload.workspaceId, userId: payload.userId};
+}
+
+function sign(encodedPayload: string): string {
+  return createHmac('sha256', config.GITHUB_INSTALL_STATE_SECRET)
+    .update(encodedPayload)
+    .digest('base64url');
+}
+
+function constantTimeEqual(a: string, b: string): boolean {
+  const left = Buffer.from(a);
+  const right = Buffer.from(b);
+  if (left.length !== right.length) return false;
+  return timingSafeEqual(left, right);
+}
+
+function parsePayload(encodedPayload: string): GithubInstallStatePayload {
+  try {
+    const parsed = JSON.parse(Buffer.from(encodedPayload, 'base64url').toString('utf8'));
+    if (
+      typeof parsed.workspaceId !== 'string' ||
+      typeof parsed.userId !== 'string' ||
+      typeof parsed.nonce !== 'string' ||
+      typeof parsed.expiresAt !== 'number'
+    ) {
+      throw new Error('Invalid payload shape');
+    }
+    return parsed;
+  } catch (_error) {
+    throw new GithubInstallStateError('Invalid GitHub install state payload');
+  }
+}