infraweaver 0.1.0

package/src/utils/github.ts

@@ -0,0 +1,676 @@
+import { createSign } from "node:crypto";
+import { rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import * as core from "@actions/core";
+import { throttling } from "@octokit/plugin-throttling";
+import { Octokit } from "@octokit/rest";
+import { DOCS_URL, PRODUCT_NAME, PRODUCT_SLUG } from "#app/brand";
+import { apiFetch } from "#app/utils/apiFetch";
+import { cloudOidcAudience } from "#app/utils/apiUrl";
+import { retry } from "#app/utils/retry";
+
+function isObject(value: unknown) {
+  return typeof value === "object" && value !== null;
+}
+
+// we don't get access to the actual class from @octokit/rest
+// it's reachable from @octokit/request-error but we'd have to add a dependency on it
+// and it would pose a risk of accidentally pulling a different version of that class (node_modules dep graphs ❤️)
+// so it's safer to ducktype this
+interface OctokitResponseShim {
+  headers: Record<string, string | number | undefined>;
+}
+
+export interface InstallationToken {
+  token: string;
+  expires_at: string;
+  installation_id: number;
+  repository: string;
+  ref: string;
+  runner_environment: string;
+  owner?: string;
+}
+
+interface GitHubAppConfig {
+  appId: string;
+  privateKey: string;
+  repoOwner: string;
+  repoName: string;
+}
+
+interface Installation {
+  id: number;
+  account: {
+    login: string;
+    type: string;
+  };
+}
+
+interface Repository {
+  owner: {
+    login: string;
+  };
+  name: string;
+}
+
+interface InstallationTokenResponse {
+  token: string;
+  expires_at: string;
+}
+
+interface RepositoriesResponse {
+  repositories: Repository[];
+}
+
+function isOIDCAvailable(): boolean {
+  // OIDC requires both env vars to be set (only in real GitHub Actions with id-token permission)
+  return Boolean(
+    process.env.ACTIONS_ID_TOKEN_REQUEST_URL &&
+    process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN,
+  );
+}
+
+/**
+ * Snapshot the GHA OIDC request creds from the env. Returns undefined off-CI or
+ * once they have been scrubbed. Call this BEFORE main.ts's restricted-mode env
+ * scrub so a mid-run token re-mint can still fetch a fresh OIDC JWT afterwards.
+ */
+export function readOidcCreds(): OidcCreds | undefined {
+  const requestUrl = process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
+  const requestToken = process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
+  return requestUrl && requestToken ? { requestUrl, requestToken } : undefined;
+}
+
+/**
+ * Fetch a fresh OIDC JWT from the GHA token service using stashed creds — the
+ * env-independent equivalent of `core.getIDToken(audience)` (same
+ * `${url}&audience=` shape + bearer request token). Lets a re-mint succeed after
+ * the ACTIONS_ID_TOKEN_REQUEST_* env vars `core.getIDToken` reads are scrubbed.
+ */
+export async function fetchOidcIdToken(
+  creds: OidcCreds,
+  audience: string,
+): Promise<string> {
+  const res = await fetch(
+    `${creds.requestUrl}&audience=${encodeURIComponent(audience)}`,
+    {
+      headers: {
+        Authorization: `Bearer ${creds.requestToken}`,
+        Accept: "application/json",
+      },
+      signal: AbortSignal.timeout(10_000),
+    },
+  );
+  if (!res.ok) {
+    throw new Error(
+      `OIDC token request failed: ${res.status} ${res.statusText}`,
+    );
+  }
+  const body = (await res.json()) as { value?: unknown };
+  if (typeof body.value !== "string" || !body.value) {
+    throw new Error("OIDC token response missing 'value'");
+  }
+  return body.value;
+}
+
+type ReadWrite = "read" | "write";
+type WriteOnly = "write";
+
+/**
+ * GitHub App installation access token permissions.
+ * passed to `POST /app/installations/{id}/access_tokens` to scope the token.
+ * fields and allowed values come from the `app-permissions` OpenAPI schema.
+ * @see https://docs.github.com/en/rest/apps/installations#create-an-installation-access-token-for-an-app
+ * @see https://github.com/github/rest-api-description — components.schemas.app-permissions
+ */
+type GitHubAppPermissions = {
+  actions?: ReadWrite;
+  artifact_metadata?: ReadWrite;
+  attestations?: ReadWrite;
+  checks?: ReadWrite;
+  contents?: ReadWrite;
+  deployments?: ReadWrite;
+  discussions?: ReadWrite;
+  issues?: ReadWrite;
+  packages?: ReadWrite;
+  pages?: ReadWrite;
+  pull_requests?: ReadWrite;
+  security_events?: ReadWrite;
+  statuses?: ReadWrite;
+  workflows?: WriteOnly;
+};
+
+/**
+ * Stashed GitHub Actions OIDC request credentials (`ACTIONS_ID_TOKEN_REQUEST_URL`
+ * + `_TOKEN`). Captured by {@link readOidcCreds} while the env vars are still
+ * present so a mid-run token re-mint can fetch a fresh OIDC JWT even after main.ts
+ * scrubs those vars from the env (which it does in every shell mode).
+ */
+export type OidcCreds = { requestUrl: string; requestToken: string };
+
+type AcquireTokenOptions = {
+  repos?: string[];
+  permissions?: GitHubAppPermissions;
+  /** when set, mint via OIDC using these stashed creds instead of reading the
+   *  (possibly already-scrubbed) ACTIONS_ID_TOKEN_REQUEST_* env vars. */
+  oidc?: OidcCreds;
+};
+
+/**
+ * Thrown when our token-exchange endpoint returns a non-2xx response.
+ * The retry policy in `acquireNewToken` looks for this concrete type to
+ * skip retries — 4xx is terminal user state (not-installed, not-authorized)
+ * and 5xx is rare enough that re-running the workflow is the right escape
+ * hatch. Genuine network failures throw plain `Error` and stay retryable.
+ */
+class TokenExchangeError extends Error {
+  readonly status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = "TokenExchangeError";
+    this.status = status;
+  }
+}
+
+async function acquireTokenViaOIDC(
+  opts?: AcquireTokenOptions,
+): Promise<string> {
+  const oidcToken = opts?.oidc
+    ? await fetchOidcIdToken(opts.oidc, cloudOidcAudience())
+    : await core.getIDToken(cloudOidcAudience());
+
+  const repos = [...(opts?.repos ?? [])];
+  const targetRepo = process.env.GITHUB_REPOSITORY?.split("/")[1];
+  if (targetRepo) {
+    repos.push(targetRepo);
+  }
+  const reposParam = repos.length ? `?repos=${repos.join(",")}` : "";
+
+  const timeoutMs = 30000;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const tokenResponse = await apiFetch({
+      path: `/api/github/installation-token${reposParam}`,
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${oidcToken}`,
+        "Content-Type": "application/json",
+      },
+      body: opts?.permissions
+        ? JSON.stringify({ permissions: opts.permissions })
+        : undefined,
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!tokenResponse.ok) {
+      // prefer the server-side `error` field — it's the single source of
+      // truth for the install URL (uses GITHUB_APP_INSTALL_URL, or the
+      // slug from NEXT_PUBLIC_GITHUB_APP_SLUG, which vary per env). fall back
+      // to a generic message if the body isn't JSON or has no `error` field.
+      let serverMessage: string | undefined;
+      try {
+        const body = (await tokenResponse.json()) as { error?: unknown };
+        if (typeof body.error === "string") serverMessage = body.error;
+      } catch {
+        // body wasn't JSON — fall through to the generic message
+      }
+      throw new TokenExchangeError(
+        tokenResponse.status,
+        serverMessage ??
+          `Token exchange failed: ${tokenResponse.status} ${tokenResponse.statusText}`,
+      );
+    }
+
+    const tokenData = (await tokenResponse.json()) as InstallationToken;
+    return tokenData.token;
+  } catch (error) {
+    clearTimeout(timeoutId);
+
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new Error(`Token exchange timed out after ${timeoutMs}ms`);
+    }
+    throw error;
+  }
+}
+
+const base64UrlEncode = (str: string): string => {
+  return Buffer.from(str)
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=/g, "");
+};
+
+const generateJWT = (appId: string, privateKey: string): string => {
+  const now = Math.floor(Date.now() / 1000);
+  const payload = {
+    iat: now - 60,
+    exp: now + 5 * 60,
+    iss: appId,
+  };
+
+  const header = {
+    alg: "RS256",
+    typ: "JWT",
+  };
+
+  const encodedHeader = base64UrlEncode(JSON.stringify(header));
+  const encodedPayload = base64UrlEncode(JSON.stringify(payload));
+  const signaturePart = `${encodedHeader}.${encodedPayload}`;
+
+  const signature = createSign("RSA-SHA256")
+    .update(signaturePart)
+    .sign(privateKey, "base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=/g, "");
+
+  return `${signaturePart}.${signature}`;
+};
+
+const githubRequest = async <T>(
+  path: string,
+  options: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+  } = {},
+): Promise<T> => {
+  const { method = "GET", headers = {}, body } = options;
+
+  const url = `https://api.github.com${path}`;
+  const requestHeaders = {
+    Accept: "application/vnd.github.v3+json",
+    "User-Agent": `${PRODUCT_NAME}-Installation-Token-Generator/1.0`,
+    ...headers,
+  };
+
+  const response = await fetch(url, {
+    method,
+    headers: requestHeaders,
+    ...(body && { body }),
+    signal: AbortSignal.timeout(30_000),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(
+      `GitHub API request failed: ${response.status} ${response.statusText}\n${errorText}`,
+    );
+  }
+
+  return response.json() as T;
+};
+
+const checkRepositoryAccess = async (
+  token: string,
+  repoOwner: string,
+  repoName: string,
+): Promise<boolean> => {
+  try {
+    const response = await githubRequest<RepositoriesResponse>(
+      "/installation/repositories",
+      {
+        headers: { Authorization: `token ${token}` },
+      },
+    );
+
+    const ownerLower = repoOwner.toLowerCase();
+    const nameLower = repoName.toLowerCase();
+    return response.repositories.some(
+      (repo) =>
+        repo.owner.login.toLowerCase() === ownerLower &&
+        repo.name.toLowerCase() === nameLower,
+    );
+  } catch {
+    return false;
+  }
+};
+
+const createInstallationToken = async (
+  jwt: string,
+  installationId: number,
+  permissions?: GitHubAppPermissions,
+): Promise<string> => {
+  const requestOpts: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+  } = {
+    method: "POST",
+    headers: { Authorization: `Bearer ${jwt}` },
+  };
+  if (permissions) {
+    requestOpts.body = JSON.stringify({ permissions });
+  }
+  const response = await githubRequest<InstallationTokenResponse>(
+    `/app/installations/${installationId}/access_tokens`,
+    requestOpts,
+  );
+
+  return response.token;
+};
+
+const findInstallationId = async (
+  jwt: string,
+  repoOwner: string,
+  repoName: string,
+): Promise<number> => {
+  const installations = await githubRequest<Installation[]>(
+    "/app/installations",
+    {
+      headers: { Authorization: `Bearer ${jwt}` },
+    },
+  );
+
+  // Probing each installation is best-effort — one that legitimately can't mint a
+  // token (suspended, revoked) must not abort the search. But swallowing the error
+  // entirely made a systemic failure (a malformed App private key, a clock skew
+  // rejecting every JWT) surface as the misleading "no installation found", which
+  // sends the reader to reinstall an App that is in fact installed correctly. Keep
+  // the last error and surface it alongside the diagnosis.
+  let lastError: unknown;
+  for (const installation of installations) {
+    try {
+      const tempToken = await createInstallationToken(jwt, installation.id);
+      const hasAccess = await checkRepositoryAccess(
+        tempToken,
+        repoOwner,
+        repoName,
+      );
+
+      if (hasAccess) {
+        return installation.id;
+      }
+    } catch (error) {
+      lastError = error;
+    }
+  }
+
+  const detail =
+    lastError === undefined
+      ? ""
+      : ` Last error while probing ${installations.length} installation(s): ${
+          lastError instanceof Error ? lastError.message : String(lastError)
+        }`;
+  throw new Error(
+    `No installation found with access to ${repoOwner}/${repoName}. ` +
+      `Ensure the GitHub App is installed on the target repository.${detail}`,
+  );
+};
+
+// for local development only
+async function acquireTokenViaGitHubApp(
+  opts?: AcquireTokenOptions,
+): Promise<string> {
+  if (!process.env.GITHUB_APP_ID || !process.env.GITHUB_PRIVATE_KEY) {
+    throw new Error(
+      "cannot acquire token via GitHub App: GITHUB_APP_ID and GITHUB_PRIVATE_KEY must be set",
+    );
+  }
+
+  const repoContext = parseRepoContext();
+
+  const config: GitHubAppConfig = {
+    appId: process.env.GITHUB_APP_ID,
+    privateKey: process.env.GITHUB_PRIVATE_KEY.replace(/\\n/g, "\n"),
+    repoOwner: repoContext.owner,
+    repoName: repoContext.name,
+  };
+
+  const jwt = generateJWT(config.appId, config.privateKey);
+  const installationId = await findInstallationId(
+    jwt,
+    config.repoOwner,
+    config.repoName,
+  );
+  return await createInstallationToken(jwt, installationId, opts?.permissions);
+}
+
+/**
+ * ensure a GitHub token is available in the environment.
+ *
+ * when OIDC is available (CI), always mints a fresh token scoped to
+ * GITHUB_REPOSITORY — overriding any inherited GITHUB_TOKEN that may
+ * be scoped to the wrong repo.
+ *
+ * otherwise falls back to GitHub App credentials for local development.
+ *
+ * only called from dev-run.ts (test/dev path) — the live action calls
+ * main() directly and never calls this.
+ */
+export async function ensureGitHubToken(): Promise<void> {
+  // when OIDC is available, always mint a fresh token scoped to
+  // GITHUB_REPOSITORY. the inherited GITHUB_TOKEN may be scoped to a
+  // different repo (e.g., runner token for infraweaver/app when tests
+  // target infraweaver/test-repo).
+  if (isOIDCAvailable()) {
+    const token = await acquireNewToken();
+    process.env.GITHUB_TOKEN = token;
+    return;
+  }
+
+  if (!process.env.GITHUB_TOKEN && !process.env.GH_TOKEN) {
+    const token = await acquireNewToken();
+    process.env.GITHUB_TOKEN = token;
+  }
+}
+
+export async function acquireNewToken(
+  opts?: AcquireTokenOptions,
+): Promise<string> {
+  // stashed OIDC creds (opts.oidc) take the OIDC path even after the
+  // ACTIONS_ID_TOKEN_REQUEST_* env vars are scrubbed — that's what lets a
+  // mid-run re-mint work after the scrub. otherwise fall back to the env check.
+  if (opts?.oidc || isOIDCAvailable()) {
+    return await retry(() => acquireTokenViaOIDC(opts), {
+      label: "token exchange",
+      shouldRetry: (error) => {
+        // 4xx is terminal user state (app not installed, permissions wrong) —
+        // retrying just triples our log noise and the user's CI bill (see
+        // #693). 5xx/429 are transient (vercel cold start, github outage,
+        // rate limit) and should ride the existing backoff.
+        if (error instanceof TokenExchangeError)
+          return error.status >= 500 || error.status === 429;
+        return (
+          error instanceof Error &&
+          (error.message.includes("timed out") ||
+            error.message.includes("fetch failed") ||
+            error.message.includes("ECONNRESET") ||
+            error.message.includes("ETIMEDOUT"))
+        );
+      },
+    });
+  }
+  // running inside GitHub Actions but the OIDC env vars are absent — the
+  // workflow is missing `permissions: id-token: write`. surface an
+  // actionable, customer-facing message; the GitHub-App branch below is
+  // local-dev only. see #739.
+  if (process.env.GITHUB_ACTIONS === "true") {
+    throw new Error(
+      `missing \`permissions: id-token: write\` on the ${PRODUCT_NAME} workflow job.\n` +
+        "\n" +
+        `${PRODUCT_NAME} mints short-lived GitHub App installation tokens via OIDC and\n` +
+        "requires `id-token: write` to be granted at the job level. add the\n" +
+        "following to your workflow yaml:\n" +
+        "\n" +
+        "  jobs:\n" +
+        `    ${PRODUCT_SLUG}:\n` +
+        "      permissions:\n" +
+        `        id-token: write   # mint ${PRODUCT_NAME} installation tokens via OIDC\n` +
+        "        contents: read    # for actions/checkout\n" +
+        "\n" +
+        `see ${DOCS_URL}/headless-action#required-permissions for the full template.`,
+    );
+  }
+  // local development via GitHub App
+  return await acquireTokenViaGitHubApp(opts);
+}
+
+export interface RepoContext {
+  owner: string;
+  name: string;
+}
+
+/**
+ * Parse repository context from GITHUB_REPOSITORY environment variable.
+ */
+export function parseRepoContext(): RepoContext {
+  const githubRepo = process.env.GITHUB_REPOSITORY;
+  if (!githubRepo) {
+    throw new Error("GITHUB_REPOSITORY environment variable is required");
+  }
+
+  const [owner, name] = githubRepo.split("/");
+  if (!owner || !name) {
+    throw new Error(
+      `Invalid GITHUB_REPOSITORY format: ${githubRepo}. Expected 'owner/repo'`,
+    );
+  }
+
+  return { owner, name };
+}
+
+export type OctokitWithPlugins = InstanceType<
+  ReturnType<typeof Octokit.plugin<typeof Octokit, [typeof throttling]>>
+>;
+
+export interface ResourceUsage {
+  requestCount: number;
+  rateLimitRemaining: number | null;
+  rateLimitResetMs: number | null;
+}
+
+function emptyResourceUsage(): ResourceUsage {
+  return {
+    requestCount: 0,
+    rateLimitRemaining: null,
+    rateLimitResetMs: null,
+  };
+}
+
+// `core` and `graphql` are always seeded below, so they're declared as required
+// (the index signature still admits other resources, which are added on demand).
+const usageByResource: Record<string, ResourceUsage> & {
+  core: ResourceUsage;
+  graphql: ResourceUsage;
+} = {
+  core: emptyResourceUsage(),
+  graphql: emptyResourceUsage(),
+};
+
+export interface UsageSummary {
+  version: 1;
+  github: {
+    core: ResourceUsage;
+    graphql: ResourceUsage;
+  };
+}
+
+function getGitHubUsageSummary(): UsageSummary {
+  return {
+    version: 1,
+    github: {
+      core: usageByResource.core,
+      graphql: usageByResource.graphql,
+    },
+  };
+}
+
+export async function writeGitHubUsageSummaryToFile(
+  path: string,
+): Promise<void> {
+  const summary = getGitHubUsageSummary();
+  const tmpPath = join(dirname(path), `.usage-summary-${process.pid}.tmp`);
+  await writeFile(tmpPath, JSON.stringify(summary));
+  await rename(tmpPath, path);
+}
+
+export function createOctokit(
+  token: string,
+  refreshAuth?: (stale: string) => Promise<string>,
+): OctokitWithPlugins {
+  // `OctokitWithPlugins` initialization based on https://github.com/actions/toolkit/blob/2506e78e82fbd2f9e94d63e75f5309118c8de1b1/packages/github/src/github.ts#L15-L22
+  // we can't use it directly because it's stuck on `@octokit/core@v5` and we use the hottest `@octokit/core@v7`
+  //
+  // Auth is applied in the request hook below rather than via the constructor
+  // `auth` option: a 401 can swap in a re-minted installation token mid-run
+  // (GitHub can reject a freshly-minted token while it replicates; pullfrog #891
+  // re-acquires one), and the hook owning the Authorization header end-to-end
+  // means no auth strategy clobbers the refreshed token on the replayed request.
+  let currentToken = token;
+  const OctokitWithPlugins = Octokit.plugin(throttling);
+  const octokit = new OctokitWithPlugins({
+    throttle: {
+      onRateLimit: (_retryAfter, _options, _octokit, retryCount) => {
+        return retryCount <= 2;
+      },
+      onSecondaryRateLimit: (_retryAfter, _options, _octokit, retryCount) => {
+        return retryCount <= 2;
+      },
+    },
+  });
+
+  const onResponse = (response: OctokitResponseShim) => {
+    const resource = response.headers["x-ratelimit-resource"];
+    if (!resource) {
+      return response;
+    }
+    usageByResource[resource] ??= emptyResourceUsage();
+    const usage = usageByResource[resource];
+    usage.requestCount++;
+    const remaining = response.headers["x-ratelimit-remaining"];
+    const reset = response.headers["x-ratelimit-reset"];
+    if (remaining !== undefined) {
+      usage.rateLimitRemaining = Number(remaining);
+    }
+    if (reset !== undefined) {
+      usage.rateLimitResetMs = Number(reset) * 1000;
+    }
+    return response;
+  };
+
+  octokit.hook.wrap("request", async (request, options) => {
+    // snapshot the token we're about to use; refreshAuth single-flights on it so
+    // concurrent requests that all sent the same stale token coalesce to one mint.
+    const sentToken = currentToken;
+    options.headers.authorization = `token ${sentToken}`;
+    try {
+      const response = await request(options);
+      onResponse(response);
+      return response;
+    } catch (error) {
+      if (
+        isObject(error) &&
+        "response" in error &&
+        isObject(error.response) &&
+        "headers" in error.response &&
+        isObject(error.response.headers)
+      ) {
+        onResponse(error.response as OctokitResponseShim);
+      }
+      // GitHub rejected the installation token with 401 — re-acquire a fresh one
+      // and replay the request once. covers the post-mint replication window
+      // where a just-minted token is briefly unrecognised. see pullfrog #891.
+      if (
+        refreshAuth &&
+        isObject(error) &&
+        "status" in error &&
+        error.status === 401
+      ) {
+        currentToken = await refreshAuth(sentToken);
+        options.headers.authorization = `token ${currentToken}`;
+        const response = await request(options);
+        onResponse(response);
+        return response;
+      }
+      throw error;
+    }
+  });
+
+  return octokit;
+}

package/src/utils/globals.ts

@@ -0,0 +1,9 @@
+import { existsSync } from "node:fs";
+
+export const isCloudflareSandbox =
+  !!process.env.CLOUDFLARE_APPLICATION_ID && !!process.env.SANDBOX_VERSION;
+
+export const isGitHubActions = !!process.env.GITHUB_ACTIONS;
+
+// detect if running inside Docker container (CI tests run in Docker with host env vars)
+export const isInsideDocker = existsSync("/.dockerenv");