@bevel-software/platform-core-backend 0.21.0 → 0.22.0

package/src/modules/github-app/github-app.client.ts

@@ -0,0 +1,268 @@
+import { createSign } from 'node:crypto';
+
+/** A GitHub App's identity and keys, as GitHub issued them. */
+export interface GitHubAppCredentials {
+  appId: string;
+  slug: string;
+  /** PEM. */
+  privateKey: string;
+  clientId: string;
+  clientSecret: string;
+}
+
+/** What GitHub hands back when an app is created from a manifest. */
+export interface RegisteredApp extends GitHubAppCredentials {
+  /** The account that owns the app. */
+  owner: string;
+  htmlUrl: string;
+}
+
+export interface Installation {
+  id: string;
+  /** The user or organisation it is installed on. */
+  account: string;
+  /** `all`, or `selected` when the admin chose repositories. */
+  repositorySelection: string;
+}
+
+export interface InstallationToken {
+  token: string;
+  /** Epoch milliseconds. */
+  expiresAt: number;
+}
+
+export interface InstallationRepository {
+  /** `owner/name`. */
+  fullName: string;
+  private: boolean;
+  defaultBranch: string;
+  /** Whether the installation may push to it. */
+  writable: boolean;
+}
+
+export type GitHubFailureKind = 'unreachable' | 'refused' | 'not-found' | 'unexpected';
+
+/** A call to GitHub that did not give what was asked. The message never carries a credential. */
+export class GitHubAppError extends Error {
+  constructor(
+    readonly kind: GitHubFailureKind,
+    message: string,
+    readonly status = 0,
+  ) {
+    super(message);
+    this.name = 'GitHubAppError';
+  }
+}
+
+const API = 'https://api.github.com';
+const WEB = 'https://github.com';
+const API_VERSION = '2022-11-28';
+/** Generous for an API that answers in a fraction of a second, short for something git is waiting on. */
+const REQUEST_TIMEOUT_MS = 10_000;
+/** Repositories listed per installation before the list is said to be cut short. */
+const MAX_REPOSITORIES = 500;
+
+/**
+ * A private key as an operator is likely to have supplied it: the PEM
+ * itself, the PEM with its line breaks written as `\n` (the only way most
+ * environment files can hold it), or the PEM in base64.
+ */
+export function normalizePrivateKey(raw: string): string {
+  const value = raw.trim();
+  if (value.includes('-----BEGIN')) return value.replace(/\\n/g, '\n');
+  try {
+    const decoded = Buffer.from(value, 'base64').toString('utf8');
+    if (decoded.includes('-----BEGIN')) return decoded.trim();
+  } catch {
+    // Not base64: handed on as it is, and the signing says what is wrong with it.
+  }
+  return value;
+}
+
+/**
+ * The JWT an app presents to GitHub as itself: RS256 over its id, good for
+ * a few minutes. Issued a minute in the past, as GitHub advises, so a clock
+ * that runs slightly ahead of theirs is not refused.
+ */
+export function appJwt(credentials: Pick<GitHubAppCredentials, 'appId' | 'privateKey'>, now: number = Date.now()): string {
+  const seconds = Math.floor(now / 1000);
+  const part = (value: unknown) => Buffer.from(JSON.stringify(value), 'utf8').toString('base64url');
+  const body = `${part({ alg: 'RS256', typ: 'JWT' })}.${part({ iat: seconds - 60, exp: seconds + 9 * 60, iss: credentials.appId })}`;
+  let signature: string;
+  try {
+    signature = createSign('RSA-SHA256').update(body).end().sign(normalizePrivateKey(credentials.privateKey), 'base64url');
+  } catch {
+    // What the key was is never quoted.
+    throw new GitHubAppError('refused', 'The GitHub App private key could not be read. It must be the PEM GitHub issued.');
+  }
+  return `${body}.${signature}`;
+}
+
+/**
+ * What the deployment asks of GitHub, as a GitHub App: every call it makes,
+ * and nothing that decides anything. Injected with `fetch` so suites answer
+ * for GitHub.
+ */
+export class GitHubAppClient {
+  constructor(
+    private readonly fetchImpl: typeof fetch = fetch,
+    private readonly now: () => number = Date.now,
+    /** How long one request to GitHub may take. */
+    private readonly timeoutMs: number = REQUEST_TIMEOUT_MS,
+  ) {}
+
+  /** The app GitHub created from a manifest, for the code it sent the browser back with. Good once, for an hour. */
+  async convertManifest(code: string): Promise<RegisteredApp> {
+    const body = await this.call<Record<string, unknown>>(`${API}/app-manifests/${encodeURIComponent(code)}/conversions`, {
+      method: 'POST',
+    });
+    const owner = (body.owner as { login?: unknown } | undefined)?.login;
+    const app: RegisteredApp = {
+      appId: String(body.id ?? ''),
+      slug: String(body.slug ?? ''),
+      privateKey: String(body.pem ?? ''),
+      clientId: String(body.client_id ?? ''),
+      clientSecret: String(body.client_secret ?? ''),
+      owner: typeof owner === 'string' ? owner : '',
+      htmlUrl: String(body.html_url ?? ''),
+    };
+    if (!app.appId || !app.slug || !app.privateKey || !app.clientId || !app.clientSecret) {
+      throw new GitHubAppError('unexpected', 'GitHub created the app but did not return its keys.');
+    }
+    return app;
+  }
+
+  /**
+   * A token for the PERSON who has just come back from GitHub, in exchange
+   * for the code they came back with. Used for one question (see
+   * {@link installationsOf}) and then dropped.
+   */
+  async exchangeUserCode(credentials: Pick<GitHubAppCredentials, 'clientId' | 'clientSecret'>, code: string): Promise<string> {
+    const body = await this.call<Record<string, unknown>>(`${WEB}/login/oauth/access_token`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ client_id: credentials.clientId, client_secret: credentials.clientSecret, code }),
+    });
+    // GitHub answers a refused exchange with 200 and an `error` field.
+    if (typeof body.access_token !== 'string' || !body.access_token) {
+      throw new GitHubAppError('refused', 'GitHub did not accept the sign-in that came back with the installation.');
+    }
+    return body.access_token;
+  }
+
+  /** The installations of this app that the person holding `userToken` can reach. */
+  async installationsOf(userToken: string): Promise<Installation[]> {
+    const found: Installation[] = [];
+    for (let page = 1; page <= 10; page += 1) {
+      const body = await this.call<{ installations?: unknown[] }>(`${API}/user/installations?per_page=100&page=${page}`, {
+        headers: { Authorization: `Bearer ${userToken}` },
+      });
+      const batch = Array.isArray(body.installations) ? body.installations : [];
+      for (const item of batch) found.push(installationOf(item));
+      if (batch.length < 100) break;
+    }
+    return found;
+  }
+
+  /** One installation, asked for as the app. */
+  async installation(credentials: GitHubAppCredentials, id: string): Promise<Installation> {
+    const body = await this.call<unknown>(`${API}/app/installations/${encodeURIComponent(id)}`, {
+      headers: { Authorization: `Bearer ${appJwt(credentials, this.now())}` },
+    });
+    return installationOf(body);
+  }
+
+  /** A token for the installation: what git presents. Good for an hour. */
+  async installationToken(credentials: GitHubAppCredentials, id: string): Promise<InstallationToken> {
+    const body = await this.call<Record<string, unknown>>(`${API}/app/installations/${encodeURIComponent(id)}/access_tokens`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${appJwt(credentials, this.now())}` },
+    });
+    const expiresAt = Date.parse(String(body.expires_at ?? ''));
+    if (typeof body.token !== 'string' || !body.token || Number.isNaN(expiresAt)) {
+      throw new GitHubAppError('unexpected', 'GitHub did not return a token for the installation.');
+    }
+    return { token: body.token, expiresAt };
+  }
+
+  /** The repositories the installation reaches, and whether the list was cut short. */
+  repositories(installationToken: string): Promise<{ repositories: InstallationRepository[]; more: boolean }> {
+    return this.listRepositories(`${API}/installation/repositories`, installationToken);
+  }
+
+  /**
+   * The repositories of an installation that THE PERSON holding `userToken`
+   * reaches, each with that person's own permissions: `writable` is whether
+   * they may push to it, which is another question from whether the
+   * installation may. An installation the person does not reach at all is
+   * GitHub's to refuse.
+   */
+  repositoriesOf(userToken: string, installationId: string): Promise<{ repositories: InstallationRepository[]; more: boolean }> {
+    return this.listRepositories(`${API}/user/installations/${encodeURIComponent(installationId)}/repositories`, userToken);
+  }
+
+  private async listRepositories(url: string, token: string): Promise<{ repositories: InstallationRepository[]; more: boolean }> {
+    const repositories: InstallationRepository[] = [];
+    let total = 0;
+    for (let page = 1; repositories.length < MAX_REPOSITORIES; page += 1) {
+      const body = await this.call<{ total_count?: unknown; repositories?: unknown[] }>(
+        `${url}?per_page=100&page=${page}`,
+        { headers: { Authorization: `Bearer ${token}` } },
+      );
+      total = typeof body.total_count === 'number' ? body.total_count : total;
+      const batch = Array.isArray(body.repositories) ? body.repositories : [];
+      for (const item of batch) {
+        const repo = item as Record<string, unknown>;
+        if (typeof repo.full_name !== 'string') continue;
+        repositories.push({
+          fullName: repo.full_name,
+          private: repo.private === true,
+          defaultBranch: typeof repo.default_branch === 'string' ? repo.default_branch : '',
+          writable: (repo.permissions as { push?: unknown } | undefined)?.push === true,
+        });
+      }
+      if (batch.length < 100) break;
+    }
+    repositories.sort((a, b) => a.fullName.localeCompare(b.fullName));
+    return { repositories, more: total > repositories.length };
+  }
+
+  private async call<T>(url: string, init: RequestInit): Promise<T> {
+    let res: Response;
+    try {
+      res = await this.fetchImpl(url, {
+        ...init,
+        // A deadline of ours: left to the platform, a host that accepts
+        // the connection and says nothing is waited on for minutes, by
+        // whatever was waiting on this call.
+        signal: AbortSignal.timeout(this.timeoutMs),
+        headers: {
+          Accept: 'application/vnd.github+json',
+          'X-GitHub-Api-Version': API_VERSION,
+          'User-Agent': 'hexis',
+          ...(init.headers as Record<string, string> | undefined),
+        },
+      });
+    } catch (err) {
+      throw new GitHubAppError('unreachable', `GitHub could not be reached: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!res.ok) {
+      // GitHub's own words name the cause (a permission, a suspended app) and carry no credential of ours.
+      const said = ((await res.json().catch(() => ({}))) as { message?: unknown }).message;
+      const detail = typeof said === 'string' && said ? `: ${said.slice(0, 200)}` : '';
+      const kind: GitHubFailureKind = res.status === 404 ? 'not-found' : res.status === 401 || res.status === 403 ? 'refused' : 'unexpected';
+      throw new GitHubAppError(kind, `GitHub answered ${res.status}${detail}`, res.status);
+    }
+    return (await res.json().catch(() => ({}))) as T;
+  }
+}
+
+function installationOf(raw: unknown): Installation {
+  const item = (raw ?? {}) as Record<string, unknown>;
+  const account = (item.account as { login?: unknown } | undefined)?.login;
+  return {
+    id: String(item.id ?? ''),
+    account: typeof account === 'string' ? account : '',
+    repositorySelection: typeof item.repository_selection === 'string' ? item.repository_selection : '',
+  };
+}

package/src/modules/github-app/github-app.connection.ts

@@ -0,0 +1,204 @@
+import { logger } from '../../shared/logging.js';
+import type { GitHubAppRepository, SettingReader } from '../settings/repository-source.js';
+import {
+  GitHubAppClient,
+  type GitHubAppCredentials,
+  type InstallationRepository,
+} from './github-app.client.js';
+
+/** Renewed this long before it would expire, so no git call starts on a token with minutes to live. */
+const RENEW_AHEAD_MS = 10 * 60_000;
+/** How long a failed renewal is remembered the first time, and the most it grows to. */
+const FIRST_WAIT_MS = 5_000;
+const LONGEST_WAIT_MS = 5 * 60_000;
+
+/** The repositories a person may connect, as a setting holds them: one `owner/name` a line. */
+export function repositoriesAsSetting(names: string[]): string {
+  return [...new Set(names.map((name) => name.trim()).filter(Boolean))].join('\n');
+}
+
+export interface GitHubAppConnectionOptions {
+  /** The deployment's settings, as they are in effect. */
+  read: SettingReader;
+  /** Where a setting's value comes from: what tells an app the operator supplied from one setup registered. */
+  sourceOf(key: string): 'env' | 'stored' | 'unset';
+  client?: GitHubAppClient;
+  now?: () => number;
+}
+
+/**
+ * The deployment's connection to GitHub through a GitHub App: the app it
+ * acts as, the installation it was given, the repositories it may be
+ * pointed at, and the token that stands for the first two when git runs.
+ *
+ * THE TOKEN EXPIRES. An installation token is good for an hour, which is
+ * the point of it: nothing long-lived is stored that reaches the
+ * repository. It is kept in memory, renewed before it runs out, and never
+ * written anywhere. A deployment that restarts asks for a new one.
+ *
+ * What is stored is what cannot be asked for again: the app's private key,
+ * encrypted like every secret, the number of the installation, and the
+ * repositories the person who connected it could push to.
+ *
+ * WHAT THE INSTALLATION REACHES IS NOT WHAT THE DEPLOYMENT MAY USE. An
+ * installation's token reads and writes every repository the installation
+ * covers. The person who connected it may hold far less: being able to
+ * read ONE of those repositories is enough for GitHub to count the
+ * installation among theirs. So the deployment is limited to what that
+ * person could push to with their own account, recorded when they
+ * connected (see {@link permits}); the installation's reach is what git
+ * works through, never what is offered.
+ */
+export class GitHubAppConnection implements GitHubAppRepository {
+  private readonly client: GitHubAppClient;
+  private readonly now: () => number;
+  private readonly log = () => logger('github-app');
+  /** The token in hand and what it is a token FOR: another app or installation is another token. */
+  private held: { for: string; token: string; expiresAt: number } | null = null;
+  /** One renewal at a time, shared by every git call that arrives during it. */
+  private renewing: Promise<void> | null = null;
+  /** The last renewal failed: how many in a row have, and until when GitHub is not asked again. */
+  private failed: { times: number; until: number } | null = null;
+
+  constructor(private readonly opts: GitHubAppConnectionOptions) {
+    this.client = opts.client ?? new GitHubAppClient();
+    this.now = opts.now ?? Date.now;
+  }
+
+  /** The app the deployment acts as, or null while any part of it is missing. */
+  credentials(read: SettingReader = this.opts.read): GitHubAppCredentials | null {
+    const credentials = {
+      appId: read('githubAppId'),
+      slug: read('githubAppSlug'),
+      privateKey: read('githubAppPrivateKey'),
+      clientId: read('githubAppClientId'),
+      clientSecret: read('githubAppClientSecret'),
+    };
+    return Object.values(credentials).every(Boolean) ? credentials : null;
+  }
+
+  /** Who supplied the app: whoever operates the deployment, or the setup screen. Null: there is none. */
+  registeredBy(): 'environment' | 'setup' | null {
+    if (!this.credentials()) return null;
+    return this.opts.sourceOf('githubAppId') === 'env' ? 'environment' : 'setup';
+  }
+
+  installationId(read: SettingReader = this.opts.read): string {
+    return read('githubInstallationId');
+  }
+
+  url(read: SettingReader = this.opts.read): string {
+    const repository = read('githubRepository');
+    return repository ? `https://github.com/${repository}.git` : '';
+  }
+
+  answered(read: SettingReader = this.opts.read): boolean {
+    return Boolean(this.credentials(read) && this.installationId(read) && read('githubRepository'));
+  }
+
+  /**
+   * Whether the deployment may be pointed at `repository`: it is one the
+   * person who connected the installation could push to.
+   *
+   * An installation the OPERATOR supplied, through the environment, has no
+   * such person. It is the operator's statement about their own
+   * deployment, and everything it reaches is permitted, as everything an
+   * access token reaches is.
+   */
+  permits(repository: string, read: SettingReader = this.opts.read): boolean {
+    if (this.opts.sourceOf('githubInstallationId') === 'env') return true;
+    const wanted = repository.trim().toLowerCase();
+    if (!wanted) return false;
+    // GitHub's names do not tell case apart.
+    return read('githubRepositoriesPermitted')
+      .split('\n')
+      .some((name) => name.trim().toLowerCase() === wanted);
+  }
+
+  token(): string | null {
+    const held = this.held;
+    if (!held || held.for !== this.holder() || held.expiresAt <= this.now()) return null;
+    return held.token;
+  }
+
+  /**
+   * Have a token for the call about to be made, WITHOUT MAKING THE CALL
+   * WAIT ON GITHUB UNLESS IT HAS TO. This runs before every git call the
+   * deployment makes, the ones that never leave the disk included.
+   *
+   *  - A token with time to spare: nothing is asked.
+   *  - A token that is good but close to running out: a renewal is started
+   *    and the call goes ahead with the token in hand.
+   *  - No token that is good: the call waits for one, and gets what GitHub
+   *    says, unless GitHub has just failed to give one. A failure is
+   *    remembered for a short while that grows with each one in a row, and
+   *    inside it nothing is asked: git runs with no token, and a call that
+   *    needed one is told so by the host, at once.
+   *
+   * `asked` is for an admin waiting on the answer itself (the setup screen
+   * listing repositories, proving a connection): GitHub is asked whatever
+   * is remembered, and the failure is thrown.
+   */
+  async prepare(opts: { asked?: boolean } = {}): Promise<void> {
+    const credentials = this.credentials();
+    const installationId = this.installationId();
+    if (!credentials || !installationId) return;
+    const held = this.held?.for === this.holder() ? this.held : null;
+    const good = held !== null && held.expiresAt > this.now();
+    if (good && held.expiresAt - this.now() > RENEW_AHEAD_MS) return;
+    if (!opts.asked && this.failed && this.now() < this.failed.until) return;
+
+    this.renewing ??= this.renew(credentials, installationId).finally(() => {
+      this.renewing = null;
+    });
+    if (good && !opts.asked) {
+      // Not waited on, so not thrown to anyone: the renewal has logged it.
+      this.renewing.catch(() => undefined);
+      return;
+    }
+    await this.renewing;
+  }
+
+  /**
+   * The repositories the deployment may be pointed at: those the
+   * installation reaches AND the person who connected it could push to.
+   * Asked of GitHub each time, so a repository taken out of the
+   * installation since is not offered.
+   */
+  async repositories(): Promise<{ repositories: InstallationRepository[]; more: boolean }> {
+    await this.prepare({ asked: true });
+    const token = this.token();
+    if (!token) return { repositories: [], more: false };
+    const reached = await this.client.repositories(token);
+    return { repositories: reached.repositories.filter((r) => this.permits(r.fullName)), more: reached.more };
+  }
+
+  /** Drop the token in hand: the installation it was for is no longer the deployment's. */
+  forget(): void {
+    this.held = null;
+    this.failed = null;
+  }
+
+  private async renew(credentials: GitHubAppCredentials, installationId: string): Promise<void> {
+    const holder = this.holder();
+    try {
+      const issued = await this.client.installationToken(credentials, installationId);
+      this.held = { for: holder, token: issued.token, expiresAt: issued.expiresAt };
+      this.failed = null;
+    } catch (err) {
+      const times = (this.failed?.times ?? 0) + 1;
+      const wait = Math.min(FIRST_WAIT_MS * 2 ** (times - 1), LONGEST_WAIT_MS);
+      this.failed = { times, until: this.now() + wait };
+      // Once per failure, and a failure is once per wait.
+      this.log().error(`GitHub gave no token for the installation; not asked again for ${Math.round(wait / 1000)} s:`, {
+        detail: err instanceof Error ? err.message : String(err),
+        failuresInARow: times,
+      });
+      throw err;
+    }
+  }
+
+  private holder(): string {
+    return `${this.opts.read('githubAppId')}:${this.installationId()}`;
+  }
+}