@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/src/registry/targets/artifactory.ts

@@ -0,0 +1,257 @@
+/**
+ * A JFrog Artifactory Terraform module repository as a module target
+ * (chant#4605), from the research on terragucci#1299 and its ruling.
+ *
+ * The repository is a local Terraform repository (Module/Provider registry
+ * type, layout `terraform-module-default`). The one write is the documented
+ * deploy (docs.jfrog.com, Terraform repositories):
+ *
+ *   PUT <url>/<repo>/<namespace>/<name>/<system>/<version>.zip
+ *
+ * with basic `user:token` credentials, as the docs show them (ruling B), and
+ * the zip of the attested archive as the body (ruling A, ./zip.ts). The user
+ * is `JFROG_USER` (or the declaration's `user` or `userEnv`) and the token
+ * `JFROG_ACCESS_TOKEN` (or `tokenEnv`). `<url>` is the Artifactory base,
+ * `https://<host>/artifactory`; a URL with no path gets `/artifactory`.
+ *
+ * Consumers write `<host>/<repo>__<namespace>/<name>/<system>`: the
+ * repository key and the namespace joined by a double underscore. `versions`
+ * and `reveal` read that source through the lexicon's registry reader
+ * (discovery, versions, download) with `TF_TOKEN_<host>` (chant#4563), else
+ * the access token as a bearer token. Artifactory indexes a deploy after
+ * the PUT answers, so `reveal` waits for the version to be listed, through
+ * the contract's `sleep` and `now`, up to `waitMs` (default 30s), then
+ * downloads it from the location the registry gives and checks it is the
+ * zip of the attested archive.
+ *
+ * `held` GETs the zip at its deploy path. A chant zip names the attested
+ * content in its archive comment; a version deployed some other way is
+ * judged by its own bytes, so it never passes for the release's. A version
+ * already there with the same content comes back `present` with nothing
+ * sent; with other content it is refused. A 403 or 409 to the PUT (a
+ * repository whose deploy policy refuses a redeploy) is judged the same way
+ * by reading the version again.
+ *
+ * Not confirmed by the docs (terragucci#1299): which editions carry
+ * Terraform repositories, the PUT's `Content-Type` (this sends
+ * `application/zip`), whether a deploy takes a bearer access token in place
+ * of basic credentials, and the overwrite rule. Artifactory's Terraform
+ * docs show no call to deprecate a module version, so Artifactory shows no
+ * deprecation and the bucket catalog carries it.
+ */
+import { PublishTargetError, type PublishContextBase, type PublishItem, type StagedTarget } from "@intentius/chant/lifecycle/release-publish";
+import { terraformCredential } from "@intentius/chant/terraform/credentials";
+import { createHash } from "node:crypto";
+import { RegistryError, registryLocation, registryVersions, type RegistryReadOptions } from "../reader";
+import {
+  answerError,
+  checkModuleVersion,
+  contentDigest,
+  defaultPublishFetch,
+  versionHeldError,
+  type HeldVersion,
+  type ModuleAddress,
+  type ModulePublishTarget,
+  type ModuleTargetDeps,
+  type ModuleVersionContext,
+} from "./module-target";
+import {
+  HOSTED_LIST_WAIT_MS,
+  HOSTED_POLL_MS,
+  defaultRegistryFetch,
+  getBytes,
+  locationContent,
+  needBasicCredential,
+  readBasicCredential,
+  revealMismatch,
+  waitListed,
+  writeRefused,
+  type BasicCredentialEnv,
+} from "./hosted";
+import { heldContentOf, moduleZip } from "./zip";
+
+/** How an Artifactory module target is declared. */
+export interface ArtifactoryModuleTargetOptions {
+  /** The Artifactory base, such as `https://acme.jfrog.io/artifactory`. A URL with no path gets `/artifactory`. */
+  url: string;
+  /** The local Terraform repository's key, such as `terraform-local`. */
+  repo: string;
+  /** The variable the access token is read from. Default `JFROG_ACCESS_TOKEN`. */
+  tokenEnv?: string;
+  /** The variable the user name is read from. Default `JFROG_USER`. */
+  userEnv?: string;
+  /** The user name, in place of `userEnv`. */
+  user?: string;
+  /** How long `reveal` waits for Artifactory to list the version. Default 30s. */
+  waitMs?: number;
+  /** How often it asks while it waits. Default 2s. */
+  pollMs?: number;
+}
+
+export const ARTIFACTORY_TOKEN_ENV = "JFROG_ACCESS_TOKEN";
+export const ARTIFACTORY_USER_ENV = "JFROG_USER";
+
+/** The Artifactory base a target deploys under, without a trailing slash. */
+export function artifactoryBase(url: string): string {
+  let u: URL;
+  try {
+    u = new URL(url);
+  } catch {
+    throw new PublishTargetError("publish-config-invalid", `${url} is not a URL`, "Set url to the Artifactory base, such as https://acme.jfrog.io/artifactory.");
+  }
+  const path = u.pathname.replace(/\/+$/, "");
+  return `${u.origin}${path || "/artifactory"}`;
+}
+
+/** The source consumers write for a module in the repository: `<host>/<repo>__<namespace>/<name>/<system>`. */
+export const artifactorySource = (host: string, repo: string, a: ModuleAddress): string => `${host}/${repo}__${a.namespace}/${a.name}/${a.system}`;
+
+/** The deploy path of one version's zip. */
+export function artifactoryDeployUrl(base: string, repo: string, a: ModuleAddress, version: string): string {
+  const seg = [repo, a.namespace, a.name, a.system].map(encodeURIComponent).join("/");
+  return `${base}/${seg}/${encodeURIComponent(version)}.zip`;
+}
+
+const REPO_KEY = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export function artifactoryModuleTarget(options: ArtifactoryModuleTargetOptions, deps: ModuleTargetDeps = {}): ModulePublishTarget<"artifactory"> {
+  const put = deps.fetch ?? defaultPublishFetch;
+  const get = deps.registryFetch ?? defaultRegistryFetch;
+  const names: BasicCredentialEnv = { tokenEnv: options.tokenEnv ?? ARTIFACTORY_TOKEN_ENV, userEnv: options.userEnv ?? ARTIFACTORY_USER_ENV, ...(options.user ? { user: options.user } : {}) };
+  const wait = {
+    waitMs: options.waitMs ?? HOSTED_LIST_WAIT_MS,
+    pollMs: options.pollMs ?? HOSTED_POLL_MS,
+    sleep: deps.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms))),
+    now: deps.now ?? Date.now,
+  };
+  const key = `artifactory:${createHash("sha256")
+    .update(JSON.stringify({ url: options.url, repo: options.repo, tokenEnv: names.tokenEnv, userEnv: names.userEnv, user: options.user ?? null }))
+    .digest("hex")
+    .slice(0, 16)}`;
+
+  const where = () => {
+    if (!REPO_KEY.test(options.repo)) throw new PublishTargetError("publish-config-invalid", `${JSON.stringify(options.repo)} is not an Artifactory repository key`);
+    const base = artifactoryBase(options.url);
+    const u = new URL(base);
+    return { base, host: u.host.toLowerCase(), scheme: (u.protocol === "http:" ? "http" : "https") as "http" | "https" };
+  };
+  const fix = `Use an identity token or API key with Deploy permission on the repository ${options.repo}, with the user it belongs to.`;
+  const needCredential = (ctx: Pick<PublishContextBase, "env" | "redactor">) => needBasicCredential(ctx, names, "Artifactory", fix);
+
+  /** The reader's options: the CLIs' token for the host, else the access token as a bearer token. */
+  const readOptions = (ctx: Pick<PublishContextBase, "env" | "redactor">): RegistryReadOptions & { host: string } => {
+    const { host, scheme } = where();
+    const cli = terraformCredential(host, { env: ctx.env });
+    const token = cli?.token ?? ctx.env[names.tokenEnv] ?? undefined;
+    ctx.redactor.add(token);
+    return { host, scheme, token: token || false, fetch: get };
+  };
+  const read = async <T>(ctx: Pick<PublishContextBase, "redactor">, run: () => Promise<T>): Promise<T> => {
+    try {
+      return await run();
+    } catch (e) {
+      if (e instanceof RegistryError) throw answerError(ctx, "publish-read-failed", e.message);
+      throw e;
+    }
+  };
+
+  const versions = async (address: ModuleAddress, ctx: Pick<PublishContextBase, "env" | "redactor">): Promise<string[]> => {
+    const o = readOptions(ctx);
+    return read(ctx, () => registryVersions(artifactorySource(o.host, options.repo, address), o));
+  };
+
+  const held = async (address: ModuleAddress, version: string, ctx: Pick<PublishContextBase, "env" | "redactor">): Promise<HeldVersion | undefined> => {
+    const { base } = where();
+    const url = artifactoryDeployUrl(base, options.repo, address, version);
+    const basic = readBasicCredential(ctx, names);
+    const bearer = readOptions(ctx).token;
+    const { status, bytes } = await getBytes(ctx, get, url, basic?.header ?? (bearer ? `Bearer ${bearer}` : undefined));
+    if (status === 404) return undefined;
+    if (status === 401 || status === 403) {
+      throw answerError(ctx, "publish-credentials-refused", `Artifactory answered ${status} to a read of ${url}`, `Set ${names.userEnv} and ${names.tokenEnv} to a user with Read permission on ${options.repo}.`);
+    }
+    if (status < 200 || status > 299) throw answerError(ctx, "publish-read-failed", `Artifactory answered ${status} to a read of ${url}`);
+    return heldContentOf(bytes, contentDigest);
+  };
+
+  const item = (ctx: ModuleVersionContext, present?: boolean): PublishItem => {
+    const { host } = where();
+    return {
+      name: `${options.repo}__${ctx.address.namespace}/${ctx.address.name}/${ctx.address.system} ${ctx.version}`,
+      destination: artifactorySource(host, options.repo, ctx.address),
+      digest: ctx.content,
+      ...(present ? { present: true } : {}),
+    };
+  };
+
+  return {
+    kind: "artifactory",
+    name: "Artifactory Terraform repository",
+    destination: `${options.url} ${options.repo}`,
+    credentialEnv: [names.tokenEnv, ...(options.user ? [] : [names.userEnv])],
+    key,
+    versions,
+    held,
+
+    async plan(ctx) {
+      checkModuleVersion(ctx);
+      where();
+      needCredential(ctx);
+      return [item(ctx)];
+    },
+
+    async stage(ctx): Promise<StagedTarget> {
+      checkModuleVersion(ctx);
+      const credential = needCredential(ctx);
+      const { base, host } = where();
+      const source = artifactorySource(host, options.repo, ctx.address);
+      const staged = (present: boolean): StagedTarget => ({ target: "artifactory", destination: source, items: [item(ctx, present)], state: { repo: options.repo, host, version: ctx.version } });
+
+      const before = await held(ctx.address, ctx.version, ctx);
+      if (before) {
+        if (before.content !== ctx.content) throw versionHeldError(source, ctx, before);
+        ctx.log(`${source} ${ctx.version} is already in ${options.repo} with this content; nothing sent`);
+        return staged(true);
+      }
+
+      const zip = moduleZip(ctx.archive, ctx.content, ctx.revision);
+      const url = artifactoryDeployUrl(base, options.repo, ctx.address, ctx.version);
+      let res: Awaited<ReturnType<typeof put>>;
+      try {
+        res = await put(url, { method: "PUT", headers: { authorization: credential.header, "content-type": "application/zip" }, body: zip });
+      } catch (e) {
+        throw answerError(ctx, "publish-upload-failed", `PUT ${url}: ${(e as Error).message}`);
+      }
+      const text = await res.text().catch(() => "");
+      if (res.ok) {
+        ctx.log(`deployed ${source} ${ctx.version} to ${options.repo}`);
+        return staged(false);
+      }
+      if (res.status === 403 || res.status === 409) {
+        // A deploy policy that refuses a redeploy, or another run deploying first: judge what the repository holds.
+        const now = await held(ctx.address, ctx.version, ctx).catch(() => undefined);
+        if (now && now.content === ctx.content) return staged(true);
+        if (now) throw versionHeldError(source, ctx, now);
+      }
+      if (res.status === 401 || res.status === 403) throw writeRefused(ctx, "Artifactory", res.status, `${source} ${ctx.version}`, credential, names, fix);
+      throw answerError(ctx, "publish-upload-failed", `Artifactory answered ${res.status} to the deploy of ${source} ${ctx.version}: ${text.slice(0, 300)}`);
+    },
+
+    async reveal(ctx, staged) {
+      const listed = await waitListed(() => versions(ctx.address, ctx), ctx.version, wait);
+      if (!listed) {
+        throw answerError(
+          ctx,
+          "publish-reveal-missing",
+          `${staged.destination} lists no ${ctx.version} ${Math.round(wait.waitMs / 1000)}s after the deploy`,
+          `Artifactory may not have indexed the deploy yet: an admin can run Recalculate Index on ${options.repo}, then run the publish again.`,
+        );
+      }
+      const o = readOptions(ctx);
+      const location = await read(ctx, () => registryLocation(staged.destination, ctx.version, o));
+      const got = await locationContent(ctx, get, location, o.host, o.token ? `Bearer ${o.token}` : undefined);
+      if (got.content !== ctx.content) throw revealMismatch(ctx, staged.destination, ctx.version, got.content, ctx.content);
+      return { target: staged.target, destination: staged.destination, items: staged.items };
+    },
+  };
+}

package/src/registry/targets/fake-artifactory.ts

@@ -0,0 +1,158 @@
+/**
+ * An in-memory stand-in for a JFrog Artifactory Terraform module repository
+ * (chant#4605), for the Artifactory module target's tests here and in
+ * terragucci#1302. It is a fetch function: nothing listens on a port and
+ * nothing leaves the process.
+ *
+ * It answers the calls terragucci#1299's research found in JFrog's docs:
+ *
+ *   GET  /.well-known/terraform.json        {"modules.v1": "/artifactory/api/terraform/v1/modules/"}
+ *   PUT  /artifactory/<repo>/<ns>/<name>/<system>/<version>.zip
+ *   GET  /artifactory/<repo>/<ns>/<name>/<system>/<version>.zip
+ *   GET  /artifactory/api/terraform/v1/modules/<repo>__<ns>/<name>/<system>/versions
+ *   GET  /artifactory/api/terraform/v1/modules/<repo>__<ns>/<name>/<system>/<version>/download   204, X-Terraform-Get
+ *
+ * The deploy takes basic `user:token` credentials only; the reads take those
+ * or a bearer token the fake knows. An unknown credential gets 401, and a
+ * user without deploy rights on the repository 403. A deploy body that is
+ * not a zip holding a `.tf` file gets 400. A redeploy of a version is
+ * refused with 409 unless `redeploy` is set. `indexAfter` keeps a new
+ * version out of the versions list for that many reads, as Artifactory's
+ * index recalculation does. `failNext` answers the next requests with a
+ * status (401, 403, 409, 5xx). Every request is kept, headers and body
+ * included.
+ */
+import { readZip } from "./zip";
+import { basicOf, bearerOf, bodyOf, headersOf, jsonAnswer, type FakeFetch, type FakeRequest } from "./fake-http";
+
+export interface FakeArtifactoryOptions {
+  /** The host, such as `acme.jfrog.io`. */
+  host: string;
+  /** The local Terraform repositories' keys. */
+  repos: string[];
+  /** Users and their access tokens. */
+  users: Record<string, string>;
+  /** The users who may deploy, per repository. Default: every user on every repository. */
+  deployers?: Record<string, string[]>;
+  /** Whether reads go without a credential (Artifactory's anonymous access). Default false. */
+  anonymousReads?: boolean;
+  /** Whether a deploy over an existing version is taken. Default false: 409. */
+  redeploy?: boolean;
+  /** How many versions reads a new version stays unlisted for. Default 0. */
+  indexAfter?: number;
+}
+
+export interface FakeArtifactory {
+  fetch: FakeFetch;
+  requests: FakeRequest[];
+  /** What the repositories hold, keyed `<repo>/<ns>/<name>/<system>/<version>`. */
+  modules: Map<string, Uint8Array>;
+  /** Put a version in directly, as a deploy by hand would. */
+  seed(repo: string, ns: string, name: string, system: string, version: string, bytes: Uint8Array): void;
+  /** Answer the next `count` requests with `status`. */
+  failNext(status: number, count?: number): void;
+}
+
+export const FAKE_ARTIFACTORY_MODULES_V1 = "/artifactory/api/terraform/v1/modules/";
+
+export function createFakeArtifactory(o: FakeArtifactoryOptions): FakeArtifactory {
+  const requests: FakeRequest[] = [];
+  const modules = new Map<string, Uint8Array>();
+  const unlisted = new Map<string, number>();
+  let failures: { status: number; count: number } | undefined;
+  const tokens = new Set(Object.values(o.users));
+
+  const userOf = (headers: Record<string, string>): string | undefined => {
+    const b = basicOf(headers.authorization);
+    return b && o.users[b.user] === b.password ? b.user : undefined;
+  };
+  const mayRead = (headers: Record<string, string>): boolean => {
+    if (o.anonymousReads) return true;
+    if (userOf(headers)) return true;
+    const bearer = bearerOf(headers.authorization);
+    return bearer !== undefined && tokens.has(bearer);
+  };
+  const mayDeploy = (user: string, repo: string) => !o.deployers || (o.deployers[repo] ?? []).includes(user);
+
+  const seed: FakeArtifactory["seed"] = (repo, ns, name, system, version, bytes) => void modules.set(`${repo}/${ns}/${name}/${system}/${version}`, bytes);
+
+  const fetch: FakeFetch = async (url, init = {}) => {
+    const method = (init.method ?? "GET").toUpperCase();
+    const headers = headersOf(init.headers);
+    const body = bodyOf(init.body);
+    requests.push({ method, url, headers, ...(body ? { body } : {}) });
+    const u = new URL(url);
+    if (u.host !== o.host) throw new TypeError(`fetch failed: the fake answers only ${o.host}, not ${u.host}`);
+    if (failures && failures.count > 0) {
+      failures.count--;
+      return jsonAnswer(failures.status, { errors: [{ status: failures.status, message: "set by failNext" }] });
+    }
+    const path = decodeURIComponent(u.pathname);
+
+    if (method === "GET" && path === "/.well-known/terraform.json") return jsonAnswer(200, { "modules.v1": FAKE_ARTIFACTORY_MODULES_V1 });
+
+    if (path.startsWith(FAKE_ARTIFACTORY_MODULES_V1)) {
+      if (method !== "GET") return jsonAnswer(405, { errors: [{ status: 405 }] });
+      if (!mayRead(headers)) return jsonAnswer(401, { errors: [{ status: 401, message: "Unauthorized" }] });
+      const rest = path.slice(FAKE_ARTIFACTORY_MODULES_V1.length).split("/");
+      const joined = /^(.+?)__(.+)$/.exec(rest[0] ?? "");
+      if (!joined || !o.repos.includes(joined[1]!)) return jsonAnswer(404, { errors: [{ status: 404 }] });
+      const prefix = `${joined[1]}/${joined[2]}/${rest[1]}/${rest[2]}/`;
+      if (rest.length === 4 && rest[3] === "versions") {
+        const listed = [...modules.keys()]
+          .filter((k) => k.startsWith(prefix))
+          .filter((k) => {
+            const left = unlisted.get(k) ?? 0;
+            if (left > 0) unlisted.set(k, left - 1);
+            return left === 0;
+          })
+          .map((k) => k.slice(prefix.length));
+        if (listed.length === 0) return jsonAnswer(404, { errors: [{ status: 404 }] });
+        return jsonAnswer(200, { modules: [{ versions: listed.map((version) => ({ version })) }] });
+      }
+      if (rest.length === 5 && rest[4] === "download") {
+        if (!modules.has(`${prefix}${rest[3]}`)) return jsonAnswer(404, { errors: [{ status: 404 }] });
+        return new Response(null, { status: 204, headers: { "X-Terraform-Get": `/artifactory/${prefix}${rest[3]}.zip` } });
+      }
+      return jsonAnswer(404, { errors: [{ status: 404 }] });
+    }
+
+    const deploy = /^\/artifactory\/([^/]+)\/([^/]+)\/([^/]+)\/([^/]+)\/([^/]+)\.zip$/.exec(path);
+    if (deploy) {
+      const [repo, ns, name, system, version] = deploy.slice(1) as [string, string, string, string, string];
+      const k = `${repo}/${ns}/${name}/${system}/${version}`;
+      if (method === "GET") {
+        if (!mayRead(headers)) return jsonAnswer(401, { errors: [{ status: 401, message: "Unauthorized" }] });
+        const stored = modules.get(k);
+        if (!stored || !o.repos.includes(repo)) return jsonAnswer(404, { errors: [{ status: 404, message: "Not Found" }] });
+        return new Response(new Uint8Array(stored), { status: 200, headers: { "content-type": "application/zip" } });
+      }
+      if (method !== "PUT") return jsonAnswer(405, { errors: [{ status: 405 }] });
+      const user = userOf(headers);
+      if (!user) return jsonAnswer(401, { errors: [{ status: 401, message: "Bad credentials" }] });
+      if (!o.repos.includes(repo)) return jsonAnswer(404, { errors: [{ status: 404, message: `repository ${repo} not found` }] });
+      if (!mayDeploy(user, repo)) return jsonAnswer(403, { errors: [{ status: 403, message: "Not enough permissions to deploy" }] });
+      if (!body || body.length === 0) return jsonAnswer(400, { errors: [{ status: 400, message: "empty body" }] });
+      try {
+        if (!readZip(body).entries.some((e) => !e.dir && e.path.endsWith(".tf"))) return jsonAnswer(400, { errors: [{ status: 400, message: "the zip holds no .tf file" }] });
+      } catch {
+        return jsonAnswer(400, { errors: [{ status: 400, message: "not a zip archive" }] });
+      }
+      if (modules.has(k) && !o.redeploy) return jsonAnswer(409, { errors: [{ status: 409, message: "Redeploy is not allowed" }] });
+      modules.set(k, body);
+      if (o.indexAfter) unlisted.set(k, o.indexAfter);
+      return jsonAnswer(201, { repo, path: `/${ns}/${name}/${system}/${version}.zip` });
+    }
+    return jsonAnswer(404, { errors: [{ status: 404 }] });
+  };
+
+  return {
+    fetch,
+    requests,
+    modules,
+    seed,
+    failNext(status, count = 1) {
+      failures = { status, count };
+    },
+  };
+}

package/src/registry/targets/fake-gitlab.ts

@@ -0,0 +1,161 @@
+/**
+ * An in-memory stand-in for GitLab's Terraform module registry (chant#4603),
+ * for the GitLab module target's tests. It is a fetch function, so nothing
+ * listens on a port and nothing leaves the process: the target's upload and
+ * the registry reader's reads both go through it.
+ *
+ * It answers the calls GitLab documents (docs.gitlab.com/api/packages/terraform-modules/):
+ *
+ *   GET  /.well-known/terraform.json                                  {"modules.v1": "/api/v4/packages/terraform/modules/v1/"}
+ *   PUT  /api/v4/projects/:id/packages/terraform/modules/:name/:system/:version/file
+ *   GET  /api/v4/packages/terraform/modules/v1/:ns/:name/:system/versions
+ *   GET  /api/v4/packages/terraform/modules/v1/:ns/:name/:system/:version/download   204, X-Terraform-Get
+ *   GET  /api/v4/packages/terraform/modules/v1/:ns/:name/:system/:version/file?token=...
+ *
+ * The upload takes `PRIVATE-TOKEN` or `JOB-TOKEN`; the reads take
+ * `Authorization: Bearer`. A token the fake does not know gets 401, and a
+ * known token without write access to the project gets 403. Uploading a
+ * version the project already holds gets 403 "Package already exists", as
+ * GitLab answers a duplicate package. Every request is kept, headers and
+ * body included, so a test can check them.
+ */
+import { gunzipSync } from "node:zlib";
+
+/** One request the fake was sent. */
+export interface FakeGitlabRequest {
+  method: string;
+  url: string;
+  /** Header names lower-cased. */
+  headers: Record<string, string>;
+  body?: Uint8Array;
+}
+
+export interface FakeGitlabOptions {
+  /** The host, such as `gitlab.example.com`. */
+  host: string;
+  /** Projects by id, each with its full path, whose top-level group is the namespace. */
+  projects: Record<string, string>;
+  /** Tokens the fake knows, each with the project ids it may upload to. */
+  tokens: Record<string, string[]>;
+  /** Whether reads need a bearer token. Default true, as for a private project. */
+  privateReads?: boolean;
+}
+
+interface Stored {
+  archive: Uint8Array;
+  project: string;
+}
+
+/** The fetch both the target and the reader are given. */
+export type FakeGitlabFetch = (url: string, init?: { method?: string; headers?: unknown; body?: unknown }) => Promise<Response>;
+
+export interface FakeGitlab {
+  fetch: FakeGitlabFetch;
+  requests: FakeGitlabRequest[];
+  /** What the registry holds, keyed `<ns>/<name>/<system>/<version>`. */
+  modules: Map<string, Stored>;
+  /** Put a version in directly, as an upload by hand would. */
+  seed(project: string, name: string, system: string, version: string, archive: Uint8Array): void;
+}
+
+const API = "/api/v4";
+const MODULES_V1 = `${API}/packages/terraform/modules/v1/`;
+const DOWNLOAD_TOKEN = "fake-download-grant";
+
+function headersOf(h: unknown): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!h) return out;
+  if (typeof (h as Headers).forEach === "function" && typeof (h as Headers).get === "function") {
+    (h as Headers).forEach((v, k) => (out[k.toLowerCase()] = v));
+    return out;
+  }
+  for (const [k, v] of Object.entries(h as Record<string, string>)) out[k.toLowerCase()] = String(v);
+  return out;
+}
+
+function bodyOf(b: unknown): Uint8Array | undefined {
+  if (b === undefined || b === null) return undefined;
+  if (typeof b === "string") return new TextEncoder().encode(b);
+  if (b instanceof Uint8Array) return b;
+  if (b instanceof ArrayBuffer) return new Uint8Array(b);
+  throw new Error("the fake takes a string or bytes as a body");
+}
+
+const json = (status: number, doc: unknown) => new Response(JSON.stringify(doc), { status, headers: { "content-type": "application/json" } });
+
+export function createFakeGitlab(o: FakeGitlabOptions): FakeGitlab {
+  const requests: FakeGitlabRequest[] = [];
+  const modules = new Map<string, Stored>();
+  const namespaceOf = (project: string) => o.projects[project]!.split("/")[0]!;
+  const projectId = (raw: string): string | undefined => {
+    const id = decodeURIComponent(raw);
+    if (o.projects[id]) return id;
+    return Object.entries(o.projects).find(([, path]) => path === id)?.[0];
+  };
+  const seed = (project: string, name: string, system: string, version: string, archive: Uint8Array) => {
+    modules.set(`${namespaceOf(project)}/${name}/${system}/${version}`, { archive, project });
+  };
+
+  const fetch: FakeGitlabFetch = async (url, init = {}) => {
+    const method = (init.method ?? "GET").toUpperCase();
+    const headers = headersOf(init.headers);
+    const body = bodyOf(init.body);
+    requests.push({ method, url, headers, ...(body ? { body } : {}) });
+    const u = new URL(url);
+    if (u.host !== o.host) throw new TypeError(`fetch failed: the fake answers only ${o.host}, not ${u.host}`);
+    const path = u.pathname;
+
+    if (method === "GET" && path === "/.well-known/terraform.json") return json(200, { "modules.v1": MODULES_V1 });
+
+    const upload = /^\/api\/v4\/projects\/([^/]+)\/packages\/terraform\/modules\/([^/]+)\/([^/]+)\/([^/]+)\/file$/.exec(path);
+    if (upload) {
+      if (method !== "PUT") return json(405, { message: "405 Method Not Allowed" });
+      const token = headers["private-token"] ?? headers["job-token"];
+      if (!token || !o.tokens[token]) return json(401, { message: "401 Unauthorized" });
+      const project = projectId(upload[1]!);
+      if (!project) return json(404, { message: "404 Project Not Found" });
+      if (!o.tokens[token]!.includes(project)) return json(403, { message: "403 Forbidden" });
+      if (!body || body.length === 0) return json(400, { message: "400 Bad request - file is missing" });
+      try {
+        gunzipSync(body);
+      } catch {
+        return json(400, { message: "400 Bad request - not a gzip archive" });
+      }
+      const [name, system, version] = [upload[2]!, upload[3]!, upload[4]!].map(decodeURIComponent) as [string, string, string];
+      const key = `${namespaceOf(project)}/${name}/${system}/${version}`;
+      if (modules.has(key)) return json(403, { message: "403 Forbidden - Package already exists" });
+      modules.set(key, { archive: body, project });
+      return json(201, { message: "201 Created" });
+    }
+
+    if (method === "GET" && path.startsWith(MODULES_V1)) {
+      const rest = path.slice(MODULES_V1.length).split("/").map(decodeURIComponent);
+      const isFile = rest.length === 5 && rest[4] === "file";
+      if (isFile) {
+        if (u.searchParams.get("token") !== DOWNLOAD_TOKEN) return json(401, { message: "401 Unauthorized" });
+      } else if (o.privateReads !== false) {
+        const bearer = /^Bearer (.+)$/i.exec(headers.authorization ?? "")?.[1];
+        if (!bearer || !o.tokens[bearer]) return json(401, { message: "401 Unauthorized" });
+      }
+      const [ns, name, system] = rest;
+      const prefix = `${ns}/${name}/${system}/`;
+      if (rest.length === 4 && rest[3] === "versions") {
+        const versions = [...modules.keys()].filter((k) => k.startsWith(prefix)).map((k) => k.slice(prefix.length));
+        if (versions.length === 0) return json(404, { message: "404 Not Found" });
+        return json(200, { modules: [{ versions: versions.map((version) => ({ version, submodules: [], root: { dependencies: [], providers: [] } })), source: `${o.host}/${ns}/${name}/${system}` }] });
+      }
+      if (rest.length === 5 && rest[4] === "download") {
+        if (!modules.has(`${prefix}${rest[3]}`)) return json(404, { message: "404 Not Found" });
+        return new Response(null, { status: 204, headers: { "X-Terraform-Get": `${MODULES_V1}${prefix}${rest[3]}/file?token=${DOWNLOAD_TOKEN}&archive=tgz` } });
+      }
+      if (isFile) {
+        const stored = modules.get(`${prefix}${rest[3]}`);
+        if (!stored) return json(404, { message: "404 Not Found" });
+        return new Response(new Uint8Array(stored.archive), { status: 200, headers: { "content-type": "application/octet-stream" } });
+      }
+    }
+    return json(404, { message: "404 Not Found" });
+  };
+
+  return { fetch, requests, modules, seed };
+}