@intentius/chant 0.4.0 → 0.6.0

package/src/audit/fetch.test.ts

@@ -0,0 +1,182 @@
+import { describe, test, expect } from "vitest";
+import { fetchCiFiles, parseRepoUrl, resolveActionSha, resolveImageDigest, parseImageRef, FetchError } from "./fetch";
+
+const b64 = (s: string) => Buffer.from(s, "utf-8").toString("base64");
+const CI_YAML = "name: CI\non:\n  push:\npermissions: write-all\njobs:\n  build:\n    runs-on: ubuntu-latest\n";
+
+interface Route {
+  match: string;
+  make: () => Response;
+}
+
+function fakeFetch(routes: Route[]) {
+  const calls: Array<{ url: string; init?: RequestInit }> = [];
+  const impl = (async (url: string | URL | Request, init?: RequestInit) => {
+    calls.push({ url: String(url), init });
+    for (const r of routes) {
+      if (String(url).includes(r.match)) return r.make();
+    }
+    return new Response("not found", { status: 404 });
+  }) as unknown as typeof fetch;
+  return { impl, calls };
+}
+
+const githubRoutes = (size = 100): Route[] => [
+  {
+    match: "/contents/.github/workflows/ci.yml",
+    make: () => new Response(JSON.stringify({ name: "ci.yml", path: ".github/workflows/ci.yml", type: "file", content: b64(CI_YAML), encoding: "base64" }), { status: 200 }),
+  },
+  {
+    match: "/contents/.github/workflows",
+    make: () => new Response(JSON.stringify([{ name: "ci.yml", path: ".github/workflows/ci.yml", type: "file", size }]), { status: 200 }),
+  },
+];
+
+describe("parseRepoUrl", () => {
+  test("rejects non-https", () => {
+    expect(() => parseRepoUrl("http://github.com/o/r")).toThrow(FetchError);
+  });
+  test("rejects non-allowlisted host", () => {
+    expect(() => parseRepoUrl("https://evil.example.com/o/r")).toThrow(/Host not allowed/);
+  });
+  test("parses owner/repo and strips .git", () => {
+    const p = parseRepoUrl("https://github.com/acme/widgets.git");
+    expect(p.owner).toBe("acme");
+    expect(p.repo).toBe("widgets");
+    expect(p.host.kind).toBe("github");
+  });
+});
+
+describe("fetchCiFiles", () => {
+  test("fetches and decodes github workflow files", async () => {
+    const { impl } = fakeFetch(githubRoutes());
+    const files = await fetchCiFiles("https://github.com/acme/widgets", { fetchImpl: impl });
+    expect(files).toHaveLength(1);
+    expect(files[0].path).toBe(".github/workflows/ci.yml");
+    expect(files[0].lexicon).toBe("github");
+    expect(files[0].content).toContain("permissions: write-all");
+  });
+
+  test("sends an auth token when provided", async () => {
+    const { impl, calls } = fakeFetch(githubRoutes());
+    await fetchCiFiles("https://github.com/acme/widgets", { fetchImpl: impl, token: "secret" });
+    const auth = calls.map((c) => (c.init?.headers as Record<string, string>)?.Authorization);
+    expect(auth).toContain("Bearer secret");
+  });
+
+  test("skips a file over the per-file size cap", async () => {
+    const { impl } = fakeFetch(githubRoutes(10_000_000));
+    const files = await fetchCiFiles("https://github.com/acme/widgets", { fetchImpl: impl, maxBytesPerFile: 1024 });
+    expect(files).toHaveLength(0);
+  });
+
+  test("refuses to follow a redirect", async () => {
+    const { impl } = fakeFetch([{ match: "/contents/", make: () => new Response(null, { status: 302 }) }]);
+    await expect(fetchCiFiles("https://github.com/acme/widgets", { fetchImpl: impl })).rejects.toThrow(/redirect/i);
+  });
+
+  test("throws on a non-allowlisted host before any fetch", async () => {
+    await expect(fetchCiFiles("https://evil.example.com/o/r")).rejects.toThrow(/Host not allowed/);
+  });
+
+  test("returns the gitlab pipeline file", async () => {
+    const { impl } = fakeFetch([
+      { match: "/repository/files/", make: () => new Response("stages:\n  - build\n", { status: 200 }) },
+    ]);
+    const files = await fetchCiFiles("https://gitlab.com/acme/widgets", { fetchImpl: impl });
+    expect(files).toHaveLength(1);
+    expect(files[0].path).toBe(".gitlab-ci.yml");
+    expect(files[0].lexicon).toBe("gitlab");
+  });
+
+  test("forgejo (codeberg) reads .forgejo/workflows", async () => {
+    const { impl } = fakeFetch([
+      {
+        match: "/contents/.forgejo/workflows/ci.yml",
+        make: () => new Response(JSON.stringify({ name: "ci.yml", path: ".forgejo/workflows/ci.yml", type: "file", content: b64(CI_YAML), encoding: "base64" }), { status: 200 }),
+      },
+      {
+        match: "/contents/.forgejo/workflows",
+        make: () => new Response(JSON.stringify([{ name: "ci.yml", path: ".forgejo/workflows/ci.yml", type: "file", size: 100 }]), { status: 200 }),
+      },
+    ]);
+    const files = await fetchCiFiles("https://codeberg.org/acme/widgets", { fetchImpl: impl });
+    expect(files).toHaveLength(1);
+    expect(files[0].lexicon).toBe("forgejo");
+    expect(files[0].path).toBe(".forgejo/workflows/ci.yml");
+  });
+
+  test("a repo with no CI files returns []", async () => {
+    const { impl } = fakeFetch([]); // everything 404s
+    const files = await fetchCiFiles("https://github.com/acme/empty", { fetchImpl: impl });
+    expect(files).toEqual([]);
+  });
+});
+
+describe("resolveActionSha", () => {
+  const SHA = "11bd71901bbe5b1630ceea73d27597364c9af683";
+
+  test("resolves an action ref to a commit SHA via the GitHub API", async () => {
+    const { impl, calls } = fakeFetch([
+      { match: "/repos/actions/checkout/commits/v4", make: () => new Response(JSON.stringify({ sha: SHA }), { status: 200 }) },
+    ]);
+    const sha = await resolveActionSha("actions/checkout", "v4", { fetchImpl: impl });
+    expect(sha).toBe(SHA);
+    expect(calls[0].url).toContain("api.github.com/repos/actions/checkout/commits/v4");
+  });
+
+  test("returns undefined on a failed lookup", async () => {
+    const { impl } = fakeFetch([]); // 404
+    expect(await resolveActionSha("acme/missing", "v1", { fetchImpl: impl })).toBeUndefined();
+  });
+
+  test("rejects a non-SHA response", async () => {
+    const { impl } = fakeFetch([{ match: "/commits/", make: () => new Response(JSON.stringify({ sha: "not-a-sha" }), { status: 200 }) }]);
+    expect(await resolveActionSha("acme/action", "v1", { fetchImpl: impl })).toBeUndefined();
+  });
+});
+
+describe("parseImageRef", () => {
+  test("bare Docker Hub official image", () => {
+    expect(parseImageRef("node:20")).toEqual({ registry: "registry-1.docker.io", repository: "library/node", tag: "20" });
+  });
+  test("Docker Hub org image, default tag", () => {
+    expect(parseImageRef("acme/app")).toEqual({ registry: "registry-1.docker.io", repository: "acme/app", tag: "latest" });
+  });
+  test("ghcr image with registry host", () => {
+    expect(parseImageRef("ghcr.io/owner/img:1.2")).toEqual({ registry: "ghcr.io", repository: "owner/img", tag: "1.2" });
+  });
+  test("already-digested ref returns undefined", () => {
+    expect(parseImageRef("node@sha256:" + "a".repeat(64))).toBeUndefined();
+  });
+});
+
+describe("resolveImageDigest", () => {
+  const DIGEST = "sha256:" + "c".repeat(64);
+
+  test("resolves via the registry v2 bearer-token challenge", async () => {
+    const challenge = 'Bearer realm="https://auth.docker.io/token",service="registry.docker.io",scope="repository:library/node:pull"';
+    const impl = (async (url: string | URL | Request, init?: RequestInit) => {
+      const u = String(url);
+      if (u.includes("auth.docker.io/token")) return new Response(JSON.stringify({ token: "t" }), { status: 200 });
+      if (u.includes("/v2/library/node/manifests/20")) {
+        const hasAuth = Boolean((init?.headers as Record<string, string>)?.Authorization);
+        return hasAuth
+          ? new Response(null, { status: 200, headers: { "docker-content-digest": DIGEST } })
+          : new Response(null, { status: 401, headers: { "www-authenticate": challenge } });
+      }
+      return new Response("nf", { status: 404 });
+    }) as unknown as typeof fetch;
+    expect(await resolveImageDigest("node:20", { fetchImpl: impl })).toBe(DIGEST);
+  });
+
+  test("skips a non-allowlisted registry (SSRF guard)", async () => {
+    let called = false;
+    const impl = (async () => {
+      called = true;
+      return new Response(null, { status: 200 });
+    }) as unknown as typeof fetch;
+    expect(await resolveImageDigest("evil.internal/x:1", { fetchImpl: impl })).toBeUndefined();
+    expect(called).toBe(false);
+  });
+});

package/src/audit/fetch.ts

@@ -0,0 +1,371 @@
+/**
+ * Remote fetch — pull a repo's CI files from a git host so the auditor can run
+ * on a URL, not just a local path. This is the ONLY audit module that touches
+ * the network; the core stays pure.
+ *
+ * SSRF posture: only an allowlisted set of hosts is accepted; request URLs are
+ * built from the parsed owner/repo (never a user-controlled host); redirects
+ * are refused; and file count / size / total bytes / time are all capped.
+ */
+
+import type { AuditInput, AuditLexicon } from "./core";
+
+export interface FetchOptions {
+  /** Branch/tag/sha; defaults to the repo's default branch. */
+  ref?: string;
+  /** Server-side token (lifts rate limits). Never surfaced to callers. */
+  token?: string;
+  /** Max number of CI files to fetch (default 50). */
+  maxFiles?: number;
+  /** Max bytes for a single file; larger files are skipped (default 256 KiB). */
+  maxBytesPerFile?: number;
+  /** Max total bytes across all files; exceeding throws (default 2 MiB). */
+  maxTotalBytes?: number;
+  /** Per-request timeout in ms (default 10000). */
+  timeoutMs?: number;
+  /** Injectable fetch for testing. Defaults to the global fetch. */
+  fetchImpl?: typeof fetch;
+}
+
+const DEFAULTS = {
+  maxFiles: 50,
+  maxBytesPerFile: 256 * 1024,
+  maxTotalBytes: 2 * 1024 * 1024,
+  timeoutMs: 10_000,
+};
+
+type HostKind = "github" | "forgejo" | "gitlab";
+
+interface HostConfig {
+  kind: HostKind;
+  api: string;
+  lexicon: AuditLexicon;
+}
+
+const ALLOWED_HOSTS: Record<string, HostConfig> = {
+  "github.com": { kind: "github", api: "https://api.github.com", lexicon: "github" },
+  "codeberg.org": { kind: "forgejo", api: "https://codeberg.org/api/v1", lexicon: "forgejo" },
+  "gitlab.com": { kind: "gitlab", api: "https://gitlab.com/api/v4", lexicon: "gitlab" },
+};
+
+export class FetchError extends Error {}
+
+interface ParsedRepo {
+  host: HostConfig;
+  owner: string;
+  repo: string;
+}
+
+/** Parse and validate a repo URL against the host allowlist (SSRF guard). */
+export function parseRepoUrl(url: string): ParsedRepo {
+  let u: URL;
+  try {
+    u = new URL(url);
+  } catch {
+    throw new FetchError(`Invalid URL: ${url}`);
+  }
+  if (u.protocol !== "https:") {
+    throw new FetchError(`Only https:// URLs are allowed (got ${u.protocol}).`);
+  }
+  const host = ALLOWED_HOSTS[u.hostname];
+  if (!host) {
+    throw new FetchError(
+      `Host not allowed: ${u.hostname}. Allowed: ${Object.keys(ALLOWED_HOSTS).join(", ")}.`,
+    );
+  }
+  const parts = u.pathname.replace(/^\/+/, "").split("/");
+  if (parts.length < 2 || !parts[0] || !parts[1]) {
+    throw new FetchError(`URL must be https://${u.hostname}/<owner>/<repo>.`);
+  }
+  return { host, owner: parts[0], repo: parts[1].replace(/\.git$/, "") };
+}
+
+function authHeaders(kind: HostKind, token?: string): Record<string, string> {
+  if (!token) return {};
+  if (kind === "github") return { Authorization: `Bearer ${token}` };
+  if (kind === "forgejo") return { Authorization: `token ${token}` };
+  return { "PRIVATE-TOKEN": token };
+}
+
+function isYaml(name: string): boolean {
+  return name.endsWith(".yml") || name.endsWith(".yaml");
+}
+
+function timeoutSignal(ms: number): AbortSignal | undefined {
+  return typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function"
+    ? AbortSignal.timeout(ms)
+    : undefined;
+}
+
+/** Gitea/GitHub contents-API entry (directory listing or single file). */
+interface ContentsEntry {
+  name: string;
+  path: string;
+  type: string;
+  size?: number;
+  content?: string;
+  encoding?: string;
+}
+
+export async function fetchCiFiles(url: string, opts: FetchOptions = {}): Promise<AuditInput[]> {
+  const { host, owner, repo } = parseRepoUrl(url);
+  const doFetch = opts.fetchImpl ?? fetch;
+  const cfg = {
+    maxFiles: opts.maxFiles ?? DEFAULTS.maxFiles,
+    maxBytesPerFile: opts.maxBytesPerFile ?? DEFAULTS.maxBytesPerFile,
+    maxTotalBytes: opts.maxTotalBytes ?? DEFAULTS.maxTotalBytes,
+    timeoutMs: opts.timeoutMs ?? DEFAULTS.timeoutMs,
+  };
+  const headers = authHeaders(host.kind, opts.token);
+
+  async function getJson(apiUrl: string): Promise<{ status: number; body: unknown }> {
+    let res: Response;
+    try {
+      res = await doFetch(apiUrl, { headers, redirect: "error", signal: timeoutSignal(cfg.timeoutMs) });
+    } catch (err) {
+      throw new FetchError(`Request failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (res.status >= 300 && res.status < 400) {
+      throw new FetchError(`Refusing to follow redirect from ${apiUrl}`);
+    }
+    if (res.status === 404) return { status: 404, body: null };
+    if (!res.ok) throw new FetchError(`${apiUrl} returned ${res.status}`);
+    return { status: res.status, body: await res.json() };
+  }
+
+  if (host.kind === "gitlab") {
+    return fetchGitlab(host, owner, repo, opts.ref, cfg, doFetch, headers);
+  }
+
+  // GitHub / Forgejo share the Gitea-style contents API.
+  const dirs = host.kind === "forgejo" ? [".forgejo/workflows", ".github/workflows"] : [".github/workflows"];
+  const ref = opts.ref ? `?ref=${encodeURIComponent(opts.ref)}` : "";
+
+  const candidates: ContentsEntry[] = [];
+  const seen = new Set<string>();
+  for (const dir of dirs) {
+    const { body } = await getJson(`${host.api}/repos/${owner}/${repo}/contents/${dir}${ref}`);
+    if (!Array.isArray(body)) continue;
+    for (const entry of body as ContentsEntry[]) {
+      if (entry.type === "file" && isYaml(entry.name) && !seen.has(entry.path)) {
+        seen.add(entry.path);
+        candidates.push(entry);
+      }
+    }
+  }
+
+  const inputs: AuditInput[] = [];
+  let total = 0;
+  for (const entry of candidates) {
+    if (inputs.length >= cfg.maxFiles) break;
+    if ((entry.size ?? 0) > cfg.maxBytesPerFile) continue; // skip oversize
+    const { body } = await getJson(`${host.api}/repos/${owner}/${repo}/contents/${entry.path}${ref}`);
+    const file = body as ContentsEntry | null;
+    if (!file?.content) continue;
+    const content = Buffer.from(file.content, (file.encoding as BufferEncoding) ?? "base64").toString("utf-8");
+    if (content.length > cfg.maxBytesPerFile) continue;
+    total += content.length;
+    if (total > cfg.maxTotalBytes) throw new FetchError("Repository CI files exceed the total size cap.");
+    inputs.push({ path: entry.path, content, lexicon: host.lexicon });
+  }
+  return inputs;
+}
+
+const SHA40 = /^[0-9a-f]{40}$/;
+
+/**
+ * Resolve an action ref (e.g. action="actions/checkout", ref="v4") to its
+ * commit SHA via the GitHub API. Returns undefined on any failure — pinning
+ * degrades gracefully to guidance. Actions are GitHub-hosted slugs, so this
+ * queries api.github.com regardless of the audited repo's host.
+ */
+export async function resolveActionSha(
+  action: string,
+  ref: string,
+  opts: { token?: string; fetchImpl?: typeof fetch; timeoutMs?: number } = {},
+): Promise<string | undefined> {
+  const parts = action.split("/");
+  if (parts.length < 2 || !parts[0] || !parts[1]) return undefined;
+  const [owner, repo] = parts;
+  const doFetch = opts.fetchImpl ?? fetch;
+  const url = `https://api.github.com/repos/${owner}/${repo}/commits/${encodeURIComponent(ref)}`;
+  try {
+    const res = await doFetch(url, {
+      headers: {
+        Accept: "application/vnd.github+json",
+        ...(opts.token ? { Authorization: `Bearer ${opts.token}` } : {}),
+      },
+      redirect: "error",
+      signal: timeoutSignal(opts.timeoutMs ?? DEFAULTS.timeoutMs),
+    });
+    if (!res.ok) return undefined;
+    const body = (await res.json()) as { sha?: string };
+    return body.sha && SHA40.test(body.sha) ? body.sha : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+const DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
+
+/** Public registries we'll talk to. The image ref is untrusted (SSRF guard). */
+const ALLOWED_REGISTRIES = new Set([
+  "registry-1.docker.io",
+  "ghcr.io",
+  "quay.io",
+  "gcr.io",
+  "public.ecr.aws",
+  "mcr.microsoft.com",
+  "registry.gitlab.com",
+]);
+
+interface ImageRef {
+  registry: string;
+  repository: string;
+  tag: string;
+}
+
+/** Parse a Docker/OCI image reference. Returns undefined if already digested. */
+export function parseImageRef(ref: string): ImageRef | undefined {
+  if (ref.includes("@")) return undefined; // already digest-pinned
+  let registry = "registry-1.docker.io";
+  let rest = ref;
+  let repoPrefix = "";
+  const firstSlash = ref.indexOf("/");
+  const firstPart = firstSlash === -1 ? "" : ref.slice(0, firstSlash);
+  if (firstPart && (firstPart.includes(".") || firstPart.includes(":") || firstPart === "localhost")) {
+    registry = firstPart;
+    rest = ref.slice(firstSlash + 1);
+  } else if (firstSlash === -1) {
+    repoPrefix = "library/"; // bare Docker Hub official image
+  }
+  let tag = "latest";
+  const lastColon = rest.lastIndexOf(":");
+  const lastSlash = rest.lastIndexOf("/");
+  if (lastColon > lastSlash) {
+    tag = rest.slice(lastColon + 1);
+    rest = rest.slice(0, lastColon);
+  }
+  if (!rest) return undefined;
+  return { registry, repository: repoPrefix + rest, tag };
+}
+
+/** Parse a `Bearer realm=...,service=...,scope=...` challenge into a token URL. */
+function tokenUrlFromChallenge(header: string): string | undefined {
+  const m = /Bearer\s+(.*)/i.exec(header);
+  if (!m) return undefined;
+  const params: Record<string, string> = {};
+  for (const part of m[1].split(",")) {
+    const kv = /(\w+)="([^"]*)"/.exec(part.trim());
+    if (kv) params[kv[1]] = kv[2];
+  }
+  if (!params.realm) return undefined;
+  const url = new URL(params.realm);
+  if (params.service) url.searchParams.set("service", params.service);
+  if (params.scope) url.searchParams.set("scope", params.scope);
+  return url.toString();
+}
+
+/**
+ * Resolve a container image `name:tag` to its `sha256:...` digest via the OCI
+ * registry v2 API (anonymous bearer-token challenge). Returns undefined on any
+ * failure or for a non-allowlisted registry. The image ref is untrusted, so we
+ * only ever contact allowlisted public registries (SSRF guard).
+ */
+export async function resolveImageDigest(
+  image: string,
+  opts: { fetchImpl?: typeof fetch; timeoutMs?: number } = {},
+): Promise<string | undefined> {
+  const parsed = parseImageRef(image);
+  if (!parsed || !ALLOWED_REGISTRIES.has(parsed.registry)) return undefined;
+  const doFetch = opts.fetchImpl ?? fetch;
+  const ms = opts.timeoutMs ?? DEFAULTS.timeoutMs;
+  const accept = [
+    "application/vnd.oci.image.index.v1+json",
+    "application/vnd.oci.image.manifest.v1+json",
+    "application/vnd.docker.distribution.manifest.list.v2+json",
+    "application/vnd.docker.distribution.manifest.v2+json",
+  ].join(", ");
+  const manifestUrl = `https://${parsed.registry}/v2/${parsed.repository}/manifests/${encodeURIComponent(parsed.tag)}`;
+
+  try {
+    let res = await doFetch(manifestUrl, { headers: { Accept: accept }, redirect: "error", signal: timeoutSignal(ms) });
+    if (res.status === 401) {
+      const tokenUrl = tokenUrlFromChallenge(res.headers.get("www-authenticate") ?? "");
+      if (!tokenUrl) return undefined;
+      const tokRes = await doFetch(tokenUrl, { redirect: "error", signal: timeoutSignal(ms) });
+      if (!tokRes.ok) return undefined;
+      const tok = (await tokRes.json()) as { token?: string; access_token?: string };
+      const bearer = tok.token ?? tok.access_token;
+      if (!bearer) return undefined;
+      res = await doFetch(manifestUrl, { headers: { Accept: accept, Authorization: `Bearer ${bearer}` }, redirect: "error", signal: timeoutSignal(ms) });
+    }
+    if (!res.ok) return undefined;
+    const digest = res.headers.get("docker-content-digest");
+    return digest && DIGEST_RE.test(digest) ? digest : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve the audited repo's current commit SHA (best-effort) for the report
+ * snapshot, so findings are anchored to an exact commit. Returns undefined on
+ * any failure.
+ */
+export async function resolveRepoCommit(
+  url: string,
+  opts: { token?: string; fetchImpl?: typeof fetch; timeoutMs?: number } = {},
+): Promise<string | undefined> {
+  let parsed: ParsedRepo;
+  try {
+    parsed = parseRepoUrl(url);
+  } catch {
+    return undefined;
+  }
+  const { host, owner, repo } = parsed;
+  const doFetch = opts.fetchImpl ?? fetch;
+  const headers = authHeaders(host.kind, opts.token);
+  const apiUrl =
+    host.kind === "gitlab"
+      ? `${host.api}/projects/${encodeURIComponent(`${owner}/${repo}`)}/repository/commits?per_page=1`
+      : `${host.api}/repos/${owner}/${repo}/commits?per_page=1&limit=1`;
+  try {
+    const res = await doFetch(apiUrl, { headers, redirect: "error", signal: timeoutSignal(opts.timeoutMs ?? DEFAULTS.timeoutMs) });
+    if (!res.ok) return undefined;
+    const body = (await res.json()) as Array<{ sha?: string; id?: string }>;
+    if (!Array.isArray(body) || body.length === 0) return undefined;
+    const sha = body[0].sha ?? body[0].id;
+    return typeof sha === "string" ? sha : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function fetchGitlab(
+  host: HostConfig,
+  owner: string,
+  repo: string,
+  ref: string | undefined,
+  cfg: { maxBytesPerFile: number; maxTotalBytes: number; timeoutMs: number },
+  doFetch: typeof fetch,
+  headers: Record<string, string>,
+): Promise<AuditInput[]> {
+  const projectId = encodeURIComponent(`${owner}/${repo}`);
+  const refQ = `?ref=${encodeURIComponent(ref ?? "HEAD")}`;
+  const apiUrl = `${host.api}/projects/${projectId}/repository/files/${encodeURIComponent(".gitlab-ci.yml")}/raw${refQ}`;
+  let res: Response;
+  try {
+    res = await doFetch(apiUrl, { headers, redirect: "error", signal: timeoutSignal(cfg.timeoutMs) });
+  } catch (err) {
+    throw new FetchError(`Request failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (res.status >= 300 && res.status < 400) throw new FetchError(`Refusing to follow redirect from ${apiUrl}`);
+  if (res.status === 404) return [];
+  if (!res.ok) throw new FetchError(`${apiUrl} returned ${res.status}`);
+  const content = await res.text();
+  if (content.length > cfg.maxBytesPerFile || content.length > cfg.maxTotalBytes) {
+    throw new FetchError("Pipeline file exceeds the size cap.");
+  }
+  return [{ path: ".gitlab-ci.yml", content, lexicon: "gitlab" }];
+}