@shipfox/api-integration-github 2.0.0

package/src/api/client.ts

@@ -0,0 +1,525 @@
+import {Buffer} from 'node:buffer';
+import {MAX_REPOSITORY_FILE_BYTES} from '@shipfox/api-integration-core-dto';
+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';
+
+const NEXT_PAGE_RE = /[?&]page=(\d+)/;
+const TRAILING_SLASHES_RE = /\/+$/;
+const MAX_TREE_WALK_DEPTH = 10;
+
+export interface GithubAccount {
+  login: string;
+  type: string;
+}
+
+export interface GithubInstallationDetails {
+  id: number;
+  account: GithubAccount;
+  repositorySelection: string;
+  suspendedAt: Date | null;
+  htmlUrl: string;
+  raw: Record<string, unknown>;
+}
+
+export interface GithubRepository {
+  id: number;
+  ownerLogin: string;
+  name: string;
+  fullName: string;
+  defaultBranch: string;
+  private: boolean;
+  visibility?: string | undefined;
+  cloneUrl: string;
+  htmlUrl: string;
+}
+
+export interface GithubRepositoryPage {
+  repositories: GithubRepository[];
+  nextCursor: string | null;
+}
+
+export interface GithubFileEntry {
+  path: string;
+  size: number | null;
+}
+
+export interface GithubFilePage {
+  files: GithubFileEntry[];
+  nextCursor: string | null;
+}
+
+export interface GithubFileContent {
+  path: string;
+  content: string;
+  size: number;
+}
+
+export interface GithubUserInstallationPage {
+  installationIds: number[];
+  nextCursor: string | null;
+}
+
+export interface GithubApiClient {
+  exchangeOAuthCode(code: string): Promise<string>;
+  listUserInstallations(input: {
+    userAccessToken: string;
+    cursor?: string | undefined;
+  }): Promise<GithubUserInstallationPage>;
+  getInstallation(installationId: number): Promise<GithubInstallationDetails>;
+  listInstallationRepositories(input: {
+    installationId: number;
+    limit: number;
+    cursor?: string | undefined;
+  }): Promise<GithubRepositoryPage>;
+  getRepository(input: {installationId: number; repositoryId: number}): Promise<GithubRepository>;
+  listRepositoryFiles(input: {
+    installationId: number;
+    repositoryId: number;
+    ref: string;
+    prefix: string;
+    limit: number;
+    cursor?: string | undefined;
+  }): Promise<GithubFilePage>;
+  fetchRepositoryFile(input: {
+    installationId: number;
+    repositoryId: number;
+    ref: string;
+    path: string;
+  }): Promise<GithubFileContent>;
+  createInstallationAccessToken(input: {
+    installationId: number;
+    repositoryId: number;
+    permissions?: {contents: 'read' | 'write'} | undefined;
+  }): Promise<GithubInstallationAccessToken>;
+}
+
+export interface GithubInstallationAccessToken {
+  token: string;
+  expiresAt: Date;
+  permissions?: Record<string, 'read' | 'write' | 'admin'> | undefined;
+}
+
+export function createGithubApiClient(): GithubApiClient {
+  return new OctokitGithubApiClient();
+}
+
+class OctokitGithubApiClient implements GithubApiClient {
+  private app: App | undefined;
+
+  async exchangeOAuthCode(code: string): Promise<string> {
+    const body = await mapGithubOAuthError(() =>
+      ky
+        .post('https://github.com/login/oauth/access_token', {
+          headers: {accept: 'application/json'},
+          json: {
+            client_id: config.GITHUB_APP_CLIENT_ID,
+            client_secret: config.GITHUB_APP_CLIENT_SECRET,
+            code,
+          },
+        })
+        .json<{access_token?: unknown}>(),
+    );
+
+    if (typeof body.access_token !== 'string') {
+      throw new GithubIntegrationProviderError(
+        'malformed-provider-response',
+        'GitHub OAuth response did not include an access token',
+      );
+    }
+    return body.access_token;
+  }
+
+  async listUserInstallations(input: {
+    userAccessToken: string;
+    cursor?: string | undefined;
+  }): Promise<GithubUserInstallationPage> {
+    const octokit = new Octokit({
+      auth: input.userAccessToken,
+      baseUrl: normalizedGithubApiBaseUrl(),
+    });
+    const page = cursorToPage(input.cursor);
+    const response = await mapGithubError(() =>
+      octokit.request('GET /user/installations', {
+        per_page: 100,
+        page,
+      }),
+    );
+
+    const installations = response.data.installations ?? [];
+    return {
+      installationIds: installations.map((installation) => installation.id),
+      nextCursor: nextCursorFromLink(response.headers.link),
+    };
+  }
+
+  async getInstallation(installationId: number): Promise<GithubInstallationDetails> {
+    const response = await mapGithubError(() =>
+      this.getApp().octokit.rest.apps.getInstallation({installation_id: installationId}),
+    );
+    const data = response.data;
+    const account = data.account;
+    if (!account) {
+      throw new GithubIntegrationProviderError(
+        'malformed-provider-response',
+        'GitHub installation response did not include an account',
+      );
+    }
+
+    const login = 'login' in account ? account.login : account.slug;
+    return {
+      id: data.id,
+      account: {
+        login,
+        type: 'type' in account ? account.type : 'Enterprise',
+      },
+      repositorySelection: data.repository_selection,
+      suspendedAt: data.suspended_at ? new Date(data.suspended_at) : null,
+      htmlUrl: data.html_url,
+      raw: data as unknown as Record<string, unknown>,
+    };
+  }
+
+  async listInstallationRepositories(input: {
+    installationId: number;
+    limit: number;
+    cursor?: string | undefined;
+  }): Promise<GithubRepositoryPage> {
+    const octokit = await this.getApp().getInstallationOctokit(input.installationId);
+    const page = cursorToPage(input.cursor);
+    const response = await mapGithubError(() =>
+      octokit.rest.apps.listReposAccessibleToInstallation({
+        per_page: input.limit,
+        page,
+      }),
+    );
+
+    return {
+      repositories: response.data.repositories.map(toGithubRepository),
+      nextCursor: nextCursorFromLink(response.headers.link),
+    };
+  }
+
+  async getRepository(input: {
+    installationId: number;
+    repositoryId: number;
+  }): Promise<GithubRepository> {
+    const octokit = await this.getApp().getInstallationOctokit(input.installationId);
+    const response = await mapGithubError(() =>
+      octokit.request('GET /repositories/{repository_id}', {
+        repository_id: input.repositoryId,
+      }),
+    );
+
+    return toGithubRepository(response.data);
+  }
+
+  async listRepositoryFiles(input: {
+    installationId: number;
+    repositoryId: number;
+    ref: string;
+    prefix: string;
+    limit: number;
+    cursor?: string | undefined;
+  }): Promise<GithubFilePage> {
+    const octokit = await this.getApp().getInstallationOctokit(input.installationId);
+    const repository = await this.getRepository({
+      installationId: input.installationId,
+      repositoryId: input.repositoryId,
+    });
+    const owner = repository.ownerLogin;
+    const repo = repository.name;
+    const startPath = input.prefix.replace(TRAILING_SLASHES_RE, '');
+    const offset = input.cursor ? Number.parseInt(input.cursor, 10) : 0;
+    const start = Number.isNaN(offset) || offset < 0 ? 0 : offset;
+    const collected: GithubFileEntry[] = [];
+    const overflowLimit = start + input.limit + 1;
+
+    type GetContentData = Awaited<ReturnType<typeof octokit.rest.repos.getContent>>['data'];
+
+    const walk = async (path: string, depth: number): Promise<void> => {
+      if (collected.length >= overflowLimit) return;
+      if (depth > MAX_TREE_WALK_DEPTH) return;
+
+      let data: GetContentData;
+      try {
+        const response = await mapGithubError(
+          () =>
+            octokit.rest.repos.getContent({
+              owner,
+              repo,
+              path,
+              ref: input.ref,
+            }),
+          'file-not-found',
+        );
+        data = response.data;
+      } catch (error) {
+        if (error instanceof GithubIntegrationProviderError && error.reason === 'file-not-found') {
+          return;
+        }
+        throw error;
+      }
+
+      if (!Array.isArray(data)) {
+        if (data.type === 'file' && data.path) {
+          collected.push({path: data.path, size: typeof data.size === 'number' ? data.size : null});
+        }
+        return;
+      }
+
+      const entries = [...data].sort((a, b) => (a.path ?? '').localeCompare(b.path ?? ''));
+      for (const entry of entries) {
+        if (collected.length >= overflowLimit) return;
+        if (!entry.path) continue;
+        if (entry.type === 'file') {
+          collected.push({
+            path: entry.path,
+            size: typeof entry.size === 'number' ? entry.size : null,
+          });
+        } else if (entry.type === 'dir') {
+          await walk(entry.path, depth + 1);
+        }
+      }
+    };
+
+    await walk(startPath, 0);
+
+    const sorted = collected.sort((a, b) => a.path.localeCompare(b.path));
+    const page = sorted.slice(start, start + input.limit);
+    const consumed = start + page.length;
+    const hasMore = consumed < sorted.length;
+
+    return {
+      files: page,
+      nextCursor: hasMore ? String(consumed) : null,
+    };
+  }
+
+  async fetchRepositoryFile(input: {
+    installationId: number;
+    repositoryId: number;
+    ref: string;
+    path: string;
+  }): Promise<GithubFileContent> {
+    const octokit = await this.getApp().getInstallationOctokit(input.installationId);
+    const repository = await this.getRepository({
+      installationId: input.installationId,
+      repositoryId: input.repositoryId,
+    });
+    const response = await mapGithubError(
+      () =>
+        octokit.rest.repos.getContent({
+          owner: repository.ownerLogin,
+          repo: repository.name,
+          path: input.path,
+          ref: input.ref,
+        }),
+      'file-not-found',
+    );
+    const data = response.data;
+
+    if (Array.isArray(data) || data.type !== 'file') {
+      throw new GithubIntegrationProviderError('file-not-found', 'GitHub path is not a file');
+    }
+    if (data.size > MAX_REPOSITORY_FILE_BYTES) {
+      throw new GithubIntegrationProviderError(
+        'content-too-large',
+        'GitHub file content is larger than the supported limit',
+      );
+    }
+    if (typeof data.content !== 'string' || data.encoding !== 'base64') {
+      throw new GithubIntegrationProviderError(
+        'malformed-provider-response',
+        'GitHub file response did not include base64 content',
+      );
+    }
+
+    return {
+      path: data.path,
+      size: data.size,
+      content: Buffer.from(data.content, 'base64').toString('utf8'),
+    };
+  }
+
+  async createInstallationAccessToken(input: {
+    installationId: number;
+    repositoryId: number;
+    permissions?: {contents: 'read' | 'write'} | undefined;
+  }): Promise<GithubInstallationAccessToken> {
+    const response = await mapGithubError(() =>
+      this.getApp().octokit.rest.apps.createInstallationAccessToken({
+        installation_id: input.installationId,
+        repository_ids: [input.repositoryId],
+        permissions: input.permissions ?? {contents: 'read'},
+      }),
+    );
+
+    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()}),
+      });
+    }
+    return this.app;
+  }
+}
+
+async function mapGithubOAuthError<T>(operation: () => Promise<T>): Promise<T> {
+  try {
+    return await operation();
+  } catch (error) {
+    if (error instanceof HTTPError) {
+      if (error.response.status === 429) {
+        throw new GithubIntegrationProviderError(
+          'rate-limited',
+          'GitHub OAuth code exchange failed',
+          retryAfterSecondsFromHeaders(error.response.headers),
+        );
+      }
+      if (error.response.status >= 500) {
+        throw new GithubIntegrationProviderError(
+          'provider-unavailable',
+          'GitHub OAuth code exchange failed',
+        );
+      }
+      throw new GithubIntegrationProviderError(
+        'access-denied',
+        'GitHub OAuth code exchange failed',
+      );
+    }
+    if (error instanceof TimeoutError) {
+      throw new GithubIntegrationProviderError('timeout', 'GitHub OAuth request timed out');
+    }
+    throw error;
+  }
+}
+
+export async function mapGithubError<T>(
+  operation: () => Promise<T>,
+  notFoundReason:
+    | 'repository-not-found'
+    | 'installation-not-found'
+    | 'file-not-found' = 'repository-not-found',
+): Promise<T> {
+  try {
+    return await operation();
+  } catch (error) {
+    if (error instanceof GithubIntegrationProviderError) throw error;
+    if (error instanceof RequestError) {
+      if (error.status === 404) {
+        throw new GithubIntegrationProviderError(notFoundReason, error.message);
+      }
+      if (error.status === 429 || isGithubRateLimitError(error)) {
+        throw new GithubIntegrationProviderError(
+          'rate-limited',
+          error.message,
+          retryAfterSeconds(error),
+        );
+      }
+      if (error.status === 401 || error.status === 403) {
+        throw new GithubIntegrationProviderError(
+          'access-denied',
+          error.message,
+          retryAfterSeconds(error),
+        );
+      }
+      if (error.status >= 500) {
+        throw new GithubIntegrationProviderError('provider-unavailable', error.message);
+      }
+    }
+    if (error instanceof Error && error.name === 'AbortError') {
+      throw new GithubIntegrationProviderError('timeout', 'GitHub request timed out');
+    }
+    throw error;
+  }
+}
+
+function isGithubRateLimitError(error: RequestError): boolean {
+  return error.status === 403 && error.response?.headers['x-ratelimit-remaining'] === '0';
+}
+
+function retryAfterSeconds(error: RequestError): number | undefined {
+  return parseRetryAfterSeconds(error.response?.headers['retry-after']);
+}
+
+function retryAfterSecondsFromHeaders(headers: Headers): number | undefined {
+  return parseRetryAfterSeconds(headers.get('retry-after'));
+}
+
+function parseRetryAfterSeconds(
+  retryAfter: string | number | null | undefined,
+): number | undefined {
+  if (!retryAfter) return undefined;
+  const parsed = Number.parseInt(String(retryAfter), 10);
+  return Number.isNaN(parsed) ? undefined : parsed;
+}
+
+function cursorToPage(cursor: string | undefined): number {
+  if (!cursor) return 1;
+  const page = Number.parseInt(cursor, 10);
+  return Number.isNaN(page) || page < 1 ? 1 : page;
+}
+
+function nextCursorFromLink(link: string | undefined): string | null {
+  if (!link) return null;
+  const next = link.split(',').find((part) => part.includes('rel="next"'));
+  if (!next) return null;
+  const match = next.match(NEXT_PAGE_RE);
+  return match?.[1] ?? null;
+}
+
+function toGithubRepository(repository: {
+  id: number;
+  owner: {login: string};
+  name: string;
+  full_name: string;
+  default_branch?: string | null | undefined;
+  private: boolean;
+  visibility?: string | undefined;
+  clone_url?: string | null | undefined;
+  html_url?: string | null | undefined;
+}): GithubRepository {
+  if (!repository.default_branch || !repository.clone_url || !repository.html_url) {
+    throw new GithubIntegrationProviderError(
+      'malformed-provider-response',
+      'GitHub repository response is missing required fields',
+    );
+  }
+  return {
+    id: repository.id,
+    ownerLogin: repository.owner.login,
+    name: repository.name,
+    fullName: repository.full_name,
+    defaultBranch: repository.default_branch,
+    private: repository.private,
+    visibility: repository.visibility,
+    cloneUrl: repository.clone_url,
+    htmlUrl: repository.html_url,
+  };
+}

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

@@ -0,0 +1,171 @@
+import {
+  IntegrationProviderError,
+  type IntegrationProviderErrorReason,
+} from '@shipfox/api-integration-core-dto';
+import {z} from 'zod';
+import {GithubIntegrationProviderError} from '#core/errors.js';
+
+export const TOKEN_REFRESH_MARGIN_MS = 5 * 60 * 1000;
+export const TOKEN_VALIDITY_BUFFER_MS = 60 * 1000;
+export const TRANSIENT_BACKOFF_MIN_MS = 30 * 1000;
+export const TRANSIENT_BACKOFF_MAX_MS = 5 * 60 * 1000;
+export const TERMINAL_BACKOFF_MS = 15 * 60 * 1000;
+
+const providerErrorReasons = [
+  'repository-not-found',
+  'installation-not-found',
+  'file-not-found',
+  'access-denied',
+  'rate-limited',
+  'timeout',
+  'provider-unavailable',
+  'malformed-provider-response',
+  'content-too-large',
+  'too-many-files',
+] as const satisfies readonly IntegrationProviderErrorReason[];
+
+const providerErrorReasonSchema = z.enum(providerErrorReasons);
+const terminalMintErrorReasons = new Set<IntegrationProviderErrorReason>([
+  'access-denied',
+  'installation-not-found',
+  'malformed-provider-response',
+]);
+
+type MissingProviderErrorReason = Exclude<
+  IntegrationProviderErrorReason,
+  (typeof providerErrorReasons)[number]
+>;
+const providerErrorReasonSchemaCoversUnion: Record<MissingProviderErrorReason, never> = {};
+void providerErrorReasonSchemaCoversUnion;
+
+const installationTokenEnvelopeSchema = z.object({
+  token: z.string().min(1).optional(),
+  expiresAt: z.string().datetime().optional(),
+  permissions: z.record(z.string(), z.enum(['read', 'write', 'admin'])).optional(),
+  backoffUntil: z.string().datetime().optional(),
+  backoffReason: providerErrorReasonSchema.optional(),
+});
+
+export interface InstallationTokenEnvelope {
+  token?: string | undefined;
+  expiresAt?: Date | undefined;
+  permissions?: Record<string, 'read' | 'write' | 'admin'> | undefined;
+  backoffUntil?: Date | undefined;
+  backoffReason?: IntegrationProviderErrorReason | undefined;
+}
+
+export type MintErrorClass = 'transient' | 'terminal';
+
+export interface ClassifiedMintError {
+  class: MintErrorClass;
+  reason: IntegrationProviderErrorReason;
+  retryAfterSeconds?: number | undefined;
+}
+
+export function githubInstallationTokenNamespace(installationId: number): string {
+  return `system/github/installation-token/${installationId}`;
+}
+
+export function encodeInstallationTokenEnvelope(envelope: InstallationTokenEnvelope): string {
+  return JSON.stringify({
+    ...(envelope.token !== undefined && {token: envelope.token}),
+    ...(envelope.expiresAt !== undefined && {expiresAt: envelope.expiresAt.toISOString()}),
+    ...(envelope.permissions !== undefined && {permissions: envelope.permissions}),
+    ...(envelope.backoffUntil !== undefined && {
+      backoffUntil: envelope.backoffUntil.toISOString(),
+    }),
+    ...(envelope.backoffReason !== undefined && {backoffReason: envelope.backoffReason}),
+  });
+}
+
+export function parseInstallationTokenEnvelope(raw: string): InstallationTokenEnvelope | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+
+  const result = installationTokenEnvelopeSchema.safeParse(parsed);
+  if (!result.success) return undefined;
+
+  return {
+    token: result.data.token,
+    expiresAt: result.data.expiresAt ? new Date(result.data.expiresAt) : undefined,
+    permissions: result.data.permissions,
+    backoffUntil: result.data.backoffUntil ? new Date(result.data.backoffUntil) : undefined,
+    backoffReason: result.data.backoffReason,
+  };
+}
+
+export function usable(
+  envelope: InstallationTokenEnvelope | undefined,
+  now: Date,
+): envelope is InstallationTokenEnvelope & {token: string; expiresAt: Date} {
+  return (
+    envelope?.token !== undefined &&
+    envelope.expiresAt !== undefined &&
+    !needsRefresh(envelope.expiresAt, now)
+  );
+}
+
+export function needsRefresh(expiresAt: Date, now: Date): boolean {
+  return expiresAt.getTime() <= now.getTime() + TOKEN_REFRESH_MARGIN_MS;
+}
+
+export function stillValid(expiresAt: Date | undefined, now: Date): boolean {
+  return expiresAt !== undefined && expiresAt.getTime() > now.getTime() + TOKEN_VALIDITY_BUFFER_MS;
+}
+
+export function backoffActive(envelope: InstallationTokenEnvelope | undefined, now: Date): boolean {
+  return (
+    envelope?.backoffUntil !== undefined &&
+    envelope.backoffReason !== undefined &&
+    envelope.backoffUntil.getTime() > now.getTime()
+  );
+}
+
+export function classifyMintError(error: unknown): ClassifiedMintError {
+  if (error instanceof IntegrationProviderError) {
+    return {
+      reason: error.reason,
+      retryAfterSeconds: error.retryAfterSeconds,
+      class: mintErrorClassForReason(error.reason),
+    };
+  }
+
+  return {reason: 'provider-unavailable', class: 'transient'};
+}
+
+export function mintErrorClassForReason(reason: IntegrationProviderErrorReason): MintErrorClass {
+  return terminalMintErrorReasons.has(reason) ? 'terminal' : 'transient';
+}
+
+export function backoffMs(classified: ClassifiedMintError): number {
+  if (classified.class === 'terminal') return TERMINAL_BACKOFF_MS;
+
+  const retryAfterMs = (classified.retryAfterSeconds ?? 0) * 1000;
+  return Math.min(TRANSIENT_BACKOFF_MAX_MS, Math.max(TRANSIENT_BACKOFF_MIN_MS, retryAfterMs));
+}
+
+export function providerErrorFromBackoff(
+  reason: IntegrationProviderErrorReason,
+  retryAfterMs: number,
+): GithubIntegrationProviderError {
+  return new GithubIntegrationProviderError(
+    reason,
+    `GitHub installation token mint is backed off after ${reason}`,
+    Math.max(1, Math.ceil(retryAfterMs / 1000)),
+  );
+}
+
+export function toProviderError(error: unknown): GithubIntegrationProviderError {
+  if (error instanceof GithubIntegrationProviderError) return error;
+  if (error instanceof IntegrationProviderError) {
+    return new GithubIntegrationProviderError(error.reason, error.message, error.retryAfterSeconds);
+  }
+  return new GithubIntegrationProviderError(
+    'provider-unavailable',
+    error instanceof Error ? error.message : 'GitHub installation token mint failed',
+  );
+}