@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/src/registry/proxies.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Proxy source forms (chant#4606): module and provider sources written
+ * through an Artifactory remote repository or a Nexus proxy host block
+ * compare equal to the plain upstream source, and the registry reader reads
+ * a plain source through a fake proxy. No request leaves the process.
+ */
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import {
+  artifactoryProxy,
+  moduleSourceForms,
+  moduleThroughProxy,
+  nexusProxy,
+  normalizeModuleSource,
+  providerAddress,
+  providerAddressForms,
+  providerThroughProxy,
+  proxyRoute,
+  registryLocation,
+  registryVersions,
+} from "./index";
+import { usedSources } from "../used-sources";
+import { createFakeArtifactory } from "./targets/fake-artifactory";
+import { createFakeNexus } from "./targets/fake-nexus";
+import { moduleTarball } from "./targets/fake-http";
+import { moduleZip } from "./targets/zip";
+import { archiveContent } from "./targets/module-target";
+
+const AF = artifactoryProxy("acme.jfrog.io", "tf-remote");
+const NX = nexusProxy({ url: "https://nexus.example.com", repo: "tf-proxy" });
+const NX_LABEL = nexusProxy({ url: "https://nexus.example.com", repo: "tf-group", host: "nexus-tf" });
+const proxies = [AF, NX_LABEL];
+
+describe("module forms through a proxy", () => {
+  test("an Artifactory remote source stands for the upstream module", () => {
+    const src = "acme.jfrog.io/tf-remote__terraform-aws-modules/vpc/aws?ref=x";
+    expect(moduleThroughProxy(src, proxies)).toEqual({ proxy: AF, upstream: "registry.terraform.io/terraform-aws-modules/vpc/aws" });
+    expect(moduleSourceForms(src, { proxies })).toEqual([
+      "acme.jfrog.io/tf-remote__terraform-aws-modules/vpc/aws",
+      "registry.terraform.io/terraform-aws-modules/vpc/aws",
+      "terraform-aws-modules/vpc/aws",
+      "registry.opentofu.org/terraform-aws-modules/vpc/aws",
+    ]);
+    expect(normalizeModuleSource(src.split("?")[0]!, { proxies })).toBe(normalizeModuleSource("terraform-aws-modules/vpc/aws"));
+  });
+
+  test("keeps a subdirectory and takes the repository key in any case", () => {
+    expect(moduleThroughProxy("ACME.jfrog.io/TF-Remote__acme/vpc/aws//modules/sub", proxies)?.upstream).toBe("registry.terraform.io/acme/vpc/aws//modules/sub");
+  });
+
+  test("a namespace without the repository's prefix, or another repository, is no proxy source", () => {
+    expect(moduleThroughProxy("acme.jfrog.io/terraform-local__acme/vpc/aws", proxies)).toBeUndefined();
+    expect(moduleThroughProxy("acme.jfrog.io/acme/vpc/aws", proxies)).toBeUndefined();
+    expect(moduleSourceForms("acme.jfrog.io/acme/vpc/aws", { proxies })).toEqual(["acme.jfrog.io/acme/vpc/aws"]);
+  });
+
+  test("a Nexus host block label stands for its upstream, and one named for the upstream is the plain source", () => {
+    expect(moduleThroughProxy("nexus-tf/acme/vpc/aws", proxies)?.upstream).toBe("registry.terraform.io/acme/vpc/aws");
+    expect(normalizeModuleSource("nexus-tf/acme/vpc/aws", { proxies })).toBe("registry.terraform.io/acme/vpc/aws");
+    expect(moduleThroughProxy("registry.terraform.io/acme/vpc/aws", [NX])?.upstream).toBe("registry.terraform.io/acme/vpc/aws");
+  });
+
+  test("a proxy for another upstream maps to that upstream", () => {
+    const tofu = artifactoryProxy("acme.jfrog.io", "tofu-remote", "registry.opentofu.org");
+    expect(normalizeModuleSource("acme.jfrog.io/tofu-remote__acme/vpc/aws", { proxies: [tofu] })).toBe("registry.opentofu.org/acme/vpc/aws");
+  });
+
+  test("without proxies nothing changes", () => {
+    expect(moduleSourceForms("acme.jfrog.io/tf-remote__acme/vpc/aws")).toEqual(["acme.jfrog.io/tf-remote__acme/vpc/aws"]);
+  });
+});
+
+describe("provider forms through a proxy", () => {
+  test("an Artifactory remote provider stands for the upstream provider", () => {
+    expect(providerThroughProxy("acme.jfrog.io/tf-remote__hashicorp/aws", proxies)?.upstream).toBe("registry.terraform.io/hashicorp/aws");
+    expect(providerAddress("acme.jfrog.io/tf-remote__hashicorp/AWS", { proxies })).toBe("registry.terraform.io/hashicorp/aws");
+    expect(providerAddress("acme.jfrog.io/tf-remote__hashicorp/aws", { binary: "tofu", proxies })).toBe("registry.terraform.io/hashicorp/aws");
+    expect(providerAddressForms("acme.jfrog.io/tf-remote__hashicorp/aws", { proxies })).toEqual([
+      "acme.jfrog.io/tf-remote__hashicorp/aws",
+      "registry.terraform.io/hashicorp/aws",
+      "hashicorp/aws",
+      "registry.opentofu.org/hashicorp/aws",
+    ]);
+  });
+
+  test("a Nexus label provider stands for the upstream provider", () => {
+    expect(providerAddress("nexus-tf/hashicorp/aws", { proxies })).toBe("registry.terraform.io/hashicorp/aws");
+  });
+
+  test("an address through no proxy is read as before", () => {
+    expect(providerAddress("acme.jfrog.io/acme/thing", { proxies })).toBe("acme.jfrog.io/acme/thing");
+    expect(providerAddress("hashicorp/aws", { proxies })).toBe("registry.terraform.io/hashicorp/aws");
+  });
+});
+
+describe("proxy routes", () => {
+  test("an upstream module goes to the proxy's host and namespace", () => {
+    expect(proxyRoute({ host: "registry.terraform.io", namespace: "acme" }, [AF])).toEqual({ proxy: AF, host: "acme.jfrog.io", namespace: "tf-remote__acme" });
+    expect(proxyRoute({ host: "registry.terraform.io", namespace: "acme" }, [NX])).toEqual({ proxy: NX, host: "registry.terraform.io", namespace: "acme", modules: "https://nexus.example.com/repository/tf-proxy/v1/modules/" });
+    expect(proxyRoute({ host: "registry.acme.dev", namespace: "acme" }, [AF])).toBeUndefined();
+  });
+});
+
+describe("reads through a fake proxy", () => {
+  const archive = moduleTarball({ "main.tf": "# vpc\n" });
+  const zip = moduleZip(archive, archiveContent(archive));
+
+  test("a plain source reads its versions and location through an Artifactory remote repository", async () => {
+    const af = createFakeArtifactory({ host: "acme.jfrog.io", repos: ["tf-remote"], users: { reader: "jfrog-read-0123456789" } });
+    af.seed("tf-remote", "terraform-aws-modules", "vpc", "aws", "5.1.0", zip);
+    const o = { proxies: [AF], fetch: af.fetch, token: "jfrog-read-0123456789" };
+    expect(await registryVersions("terraform-aws-modules/vpc/aws", o)).toEqual(["5.1.0"]);
+    expect(await registryVersions("registry.terraform.io/terraform-aws-modules/vpc/aws", o)).toEqual(["5.1.0"]);
+    expect(await registryLocation("terraform-aws-modules/vpc/aws", "5.1.0", o)).toBe("https://acme.jfrog.io/artifactory/tf-remote/terraform-aws-modules/vpc/aws/5.1.0.zip");
+    const paths = af.requests.map((r) => new URL(r.url).pathname);
+    expect(paths).toContain("/artifactory/api/terraform/v1/modules/tf-remote__terraform-aws-modules/vpc/aws/versions");
+    expect(af.requests.every((r) => new URL(r.url).host === "acme.jfrog.io")).toBe(true);
+  });
+
+  test("a plain source reads through a Nexus proxy repository's host block, with no discovery", async () => {
+    const nx = createFakeNexus({ host: "nexus.example.com", repos: ["tf-proxy"], users: { reader: "nexus-read-0123456789" }, bearer: false });
+    nx.seed("tf-proxy", "terraform-aws-modules", "vpc", "aws", "5.1.0", "vpc-5.1.0.zip", zip);
+    const basic = `Basic ${Buffer.from("reader:nexus-read-0123456789").toString("base64")}`;
+    const o = { proxies: [NX], fetch: nx.fetch, token: false as const, authorization: basic };
+    expect(await registryVersions("terraform-aws-modules/vpc/aws", o)).toEqual(["5.1.0"]);
+    expect(await registryLocation("registry.terraform.io/terraform-aws-modules/vpc/aws", "5.1.0", o)).toBe(
+      "https://nexus.example.com/repository/tf-proxy/v1/modules/terraform-aws-modules/vpc/aws/5.1.0/vpc-5.1.0.zip",
+    );
+    expect(nx.requests.map((r) => new URL(r.url).pathname)).not.toContain("/.well-known/terraform.json");
+  });
+
+  test("a source written through a Nexus label reads through it", async () => {
+    const nx = createFakeNexus({ host: "nexus.example.com", repos: ["tf-group"], users: { reader: "nexus-read-0123456789" }, bearer: false });
+    nx.seed("tf-group", "acme", "vpc", "aws", "1.0.0", "vpc-1.0.0.zip", zip);
+    const basic = `Basic ${Buffer.from("reader:nexus-read-0123456789").toString("base64")}`;
+    expect(await registryVersions("nexus-tf/acme/vpc/aws", { proxies: [NX_LABEL], fetch: nx.fetch, token: false, authorization: basic })).toEqual(["1.0.0"]);
+  });
+
+  test("a hostless source without proxies is refused as before", async () => {
+    await expect(registryVersions("acme/vpc/aws", { fetch: async () => new Response(null, { status: 500 }) })).rejects.toThrow(/not a registry source/);
+  });
+});
+
+describe("usedSources through a proxy", () => {
+  test("a call through an Artifactory remote repository gets the upstream's normal form", async () => {
+    const root = join(import.meta.dirname, "__fixtures__", "proxied-root");
+    const { used } = await usedSources(root, { proxies });
+    const vpc = used.find((u) => u.block === "module.vpc")!;
+    expect(vpc.source).toBe("acme.jfrog.io/tf-remote__terraform-aws-modules/vpc/aws");
+    expect(vpc.normal).toBe("registry.terraform.io/terraform-aws-modules/vpc/aws");
+    expect(used.find((u) => u.block === "required_providers.aws")!.normal).toBe("registry.terraform.io/hashicorp/aws");
+  });
+});

package/src/registry/proxies.ts

@@ -0,0 +1,132 @@
+/**
+ * Registry proxies (chant#4606, terragucci#1290 bundle C): an Artifactory
+ * remote or virtual repository, or a Nexus proxy or group repository,
+ * standing in front of an upstream registry, so a source written through
+ * one and the plain upstream source compare equal, and reads go through the
+ * proxy. The shapes are the ones terragucci#1299's research found:
+ *
+ *   Artifactory   <host>/<repo>__<ns>/<name>/<system>   module, the repository key joined to the namespace by `__`
+ *                 <host>/<repo>__<ns>/<type>            provider, the same joiner
+ *   Nexus         <label>/<ns>/<name>/<system>          behind a CLI `host "<label>"` block whose services
+ *                                                       point at the proxy repository; the label is usually
+ *                                                       the upstream itself (`host "registry.terraform.io"`)
+ *
+ * An entry names the host sources through the proxy write, the Artifactory
+ * repository key when there is one, and the upstream it stands for
+ * (registry.terraform.io unless set). A Nexus entry carries the repository's
+ * modules.v1 URL, which reads use in place of the label's discovery, as the
+ * CLI's host block does. No Node imports, so an edge function can carry it.
+ */
+import { parseRegistrySource } from "./address";
+
+/** The upstream a proxy stands for when an entry names none. */
+export const DEFAULT_PROXY_UPSTREAM = "registry.terraform.io";
+
+/** One registry proxy. */
+export interface RegistryProxy {
+  /** The host sources through the proxy name: Artifactory's host, or the label of a Nexus host block. */
+  host: string;
+  /** Artifactory: the remote or virtual repository's key, joined to the namespace with `__`. Absent for Nexus. */
+  repo?: string;
+  /** The registry host the proxy stands for. Default registry.terraform.io. */
+  upstream?: string;
+  /**
+   * The modules.v1 URL a CLI host block gives the label (a Nexus proxy or
+   * group repository's `<url>/repository/<repo>/v1/modules/`), read in
+   * place of the label's service discovery.
+   */
+  modules?: string;
+  /** The providers.v1 URL of the same host block, when reads of providers go through it. */
+  providers?: string;
+}
+
+/** The `__` an Artifactory source joins its repository key and namespace with. */
+export const ARTIFACTORY_JOINER = "__";
+
+/** A proxy entry for an Artifactory remote or virtual Terraform repository. */
+export const artifactoryProxy = (host: string, repo: string, upstream?: string): RegistryProxy => ({ host: host.toLowerCase(), repo, ...(upstream ? { upstream: upstream.toLowerCase() } : {}) });
+
+/**
+ * A proxy entry for a Nexus proxy or group Terraform repository at `url`.
+ * The label defaults to the upstream, as Sonatype's docs write the host
+ * block (`host "registry.terraform.io"`), so plain sources go through it.
+ */
+export function nexusProxy(o: { url: string; repo: string; upstream?: string; host?: string }): RegistryProxy {
+  const base = o.url.replace(/\/+$/, "");
+  const upstream = (o.upstream ?? DEFAULT_PROXY_UPSTREAM).toLowerCase();
+  const repo = encodeURIComponent(o.repo);
+  return { host: (o.host ?? upstream).toLowerCase(), upstream, modules: `${base}/repository/${repo}/v1/modules/`, providers: `${base}/repository/${repo}/v1/providers/` };
+}
+
+const upstreamOf = (p: RegistryProxy): string => (p.upstream ?? DEFAULT_PROXY_UPSTREAM).toLowerCase();
+const sameHost = (a: string, b: string) => a.toLowerCase() === b.toLowerCase();
+
+/** The bare labels the proxies use as hosts, so a source starting with one parses as a registry source. */
+export const proxyLabels = (proxies: readonly RegistryProxy[] = []): string[] => proxies.map((p) => p.host);
+
+/** A namespace through an Artifactory proxy without its `<repo>__`, or undefined when it does not carry that repository. */
+function unjoin(p: RegistryProxy, namespace: string): string | undefined {
+  if (!p.repo) return namespace;
+  const prefix = `${p.repo}${ARTIFACTORY_JOINER}`;
+  return namespace.toLowerCase().startsWith(prefix.toLowerCase()) && namespace.length > prefix.length ? namespace.slice(prefix.length) : undefined;
+}
+
+/**
+ * The upstream registry source a module source written through a proxy
+ * stands for, `<upstream>/<ns>/<name>/<system>` with any `//subdir` kept and
+ * the query dropped, and the proxy it went through. Undefined for a source
+ * through none of them. A Nexus label that is the upstream itself gives the
+ * source back at the upstream.
+ */
+export function moduleThroughProxy(source: string, proxies: readonly RegistryProxy[] = []): { proxy: RegistryProxy; upstream: string } | undefined {
+  if (proxies.length === 0) return undefined;
+  const written = source.trim().split("?")[0]!;
+  const [base, ...sub] = written.split("//");
+  const s = parseRegistrySource(base!, proxyLabels(proxies));
+  if (!s) return undefined;
+  for (const p of proxies) {
+    if (!sameHost(p.host, s.host)) continue;
+    const ns = unjoin(p, s.namespace);
+    if (ns === undefined) continue;
+    const upstream = [`${upstreamOf(p)}/${ns}/${s.name}/${s.system}`, ...sub].join("//");
+    return { proxy: p, upstream };
+  }
+  return undefined;
+}
+
+/**
+ * The upstream provider address a provider source written through a proxy
+ * stands for, `<upstream>/<ns>/<type>` in lower case. Undefined for a
+ * source through none of them.
+ */
+export function providerThroughProxy(source: string, proxies: readonly RegistryProxy[] = []): { proxy: RegistryProxy; upstream: string } | undefined {
+  const parts = source.trim().toLowerCase().split("/");
+  if (parts.length !== 3) return undefined;
+  const [host, namespace, type] = parts as [string, string, string];
+  for (const p of proxies) {
+    if (!sameHost(p.host, host)) continue;
+    const ns = unjoin(p, namespace);
+    if (ns === undefined || !ns || !type) continue;
+    return { proxy: p, upstream: `${upstreamOf(p)}/${ns}/${type}` };
+  }
+  return undefined;
+}
+
+/**
+ * Where a read of a module at `host/<ns>/<name>/<system>` goes when a proxy
+ * stands for `host`: the host and namespace the proxy names it by, and the
+ * modules.v1 URL to read in place of discovery (a Nexus host block's).
+ * Undefined when no proxy stands for `host`, or the module already names a
+ * proxy's host.
+ */
+export function proxyRoute(
+  s: { host: string; namespace: string },
+  proxies: readonly RegistryProxy[] = [],
+): { proxy: RegistryProxy; host: string; namespace: string; modules?: string } | undefined {
+  // A source written through a proxy already reads from its host; a Nexus label is resolved by its modules URL.
+  const named = proxies.find((p) => sameHost(p.host, s.host));
+  if (named) return named.modules ? { proxy: named, host: named.host, namespace: s.namespace, modules: named.modules } : undefined;
+  const p = proxies.find((q) => sameHost(upstreamOf(q), s.host));
+  if (!p) return undefined;
+  return { proxy: p, host: p.host, namespace: p.repo ? `${p.repo}${ARTIFACTORY_JOINER}${s.namespace}` : s.namespace, ...(p.modules ? { modules: p.modules } : {}) };
+}

package/src/registry/reader.ts

@@ -0,0 +1,225 @@
+/**
+ * Reading a module registry the way the CLIs do: service discovery, the
+ * versions list, a version's download location, and a tarball's bytes.
+ * Lifted from terragucci's `publish/registry.ts` (18f6431595) for chant#4565.
+ *
+ * `registryLocation` reads the download answer in one of three ways:
+ * `terraform` takes only the `X-Terraform-Get` header (200 or 204), `tofu`
+ * takes the JSON body's `location` on a 200 and the header otherwise, and the
+ * default takes either, header first. A test that wants to know whether
+ * Terraform can install from a registry asks with `reads: "terraform"`.
+ *
+ * Every request to the registry's host carries the token the CLIs would send
+ * it (chant#4563): `TF_TOKEN_<host>`, else the CLI config's or
+ * credentials.tfrc.json's `credentials` block, found by core's
+ * `terraform/credentials` reader. The token goes in the `Authorization`
+ * header and nowhere else; an error names the variable to set, never a value.
+ *
+ * A host with no service discovery of its own, such as a Nexus repository
+ * (chant#4605), is read through `services`: the modules.v1 URL per host, as
+ * a CLI's `host` block gives it, held in memory so no CLI config file is
+ * written. Such a host may be a bare name with no dot, as a `host` block's
+ * label may be.
+ *
+ * With `proxies` (chant#4606), a module whose host a proxy stands for is
+ * read through the proxy: an Artifactory remote repository at
+ * `<proxy host>/<repo>__<ns>/<name>/<system>`, a Nexus proxy or group
+ * repository through its host block's modules.v1 URL. A source with no host
+ * is read at registry.terraform.io, so through the proxy that stands for it.
+ */
+import { gunzipSync } from "node:zlib";
+import { credentialsHost, terraformToken, tokenVariable, type CredentialsOptions } from "@intentius/chant/terraform/credentials";
+import { DISCOVERY, parseRegistrySource, type RegistrySource } from "./address";
+import { DEFAULT_PROXY_UPSTREAM, proxyLabels, proxyRoute, type RegistryProxy } from "./proxies";
+import { DOWNLOAD_HEADER, readVersions } from "./writer";
+
+/** The fetch the reader calls: the global fetch's shape. */
+export type RegistryFetch = (url: string, init?: RequestInit) => Promise<Response>;
+
+const globalFetch: RegistryFetch = (url, init) => fetch(url, init);
+
+export class RegistryError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RegistryError";
+  }
+}
+
+/** How a download answer is read. */
+export type DownloadReader = "terraform" | "tofu" | "either";
+
+export interface RegistryReadOptions {
+  fetch?: RegistryFetch;
+  /** The URL scheme service discovery is fetched over. Default https, as both CLIs use. */
+  scheme?: "https" | "http";
+  /**
+   * The bearer token sent to the registry's host. Default: the one the CLIs
+   * would send (`TF_TOKEN_<host>`, then the credentials files). `false` sends none.
+   */
+  token?: string | false;
+  /** Where the default token lookup reads (a test passes its own env and files). */
+  credentials?: CredentialsOptions;
+  /**
+   * The modules.v1 URL per registry host, read in place of the host's
+   * `/.well-known/terraform.json`, as a CLI's `host "<name>" { services = {...} }`
+   * block does. A host named here is taken as a registry host even without a dot.
+   */
+  services?: Record<string, string>;
+  /**
+   * A whole `Authorization` header value sent on every request to the
+   * registry, in place of the bearer token, such as Nexus's basic
+   * credentials before its bearer form (3.95). Never printed.
+   */
+  authorization?: string;
+  /** Registry proxies in front of upstream hosts; a read of a module at an upstream goes through its proxy. */
+  proxies?: readonly RegistryProxy[];
+}
+
+/** The token a read sends to a host, by the options. */
+export const readToken = (host: string, o: RegistryReadOptions): string | undefined => (o.token === false ? undefined : (o.token ?? terraformToken(host, o.credentials)));
+
+const httpGet = async (fetchFn: RegistryFetch, url: string, token?: string, authorization?: string): Promise<Response> => {
+  const auth = authorization ?? (token ? `Bearer ${token}` : undefined);
+  try {
+    return await fetchFn(url, { method: "GET", redirect: "follow", ...(auth ? { headers: { Authorization: auth } } : {}) });
+  } catch (e) {
+    const cause = (e as { cause?: { message?: string } }).cause?.message;
+    throw new RegistryError(`${url}: ${(e as Error).message}${cause ? ` (${cause})` : ""}`);
+  }
+};
+
+/** The error for a status that is not OK, saying where a token goes when the registry refused one. */
+const answered = (url: string, status: number, host: string, token: string | undefined): RegistryError => {
+  if (status !== 401 && status !== 403) return new RegistryError(`${url} answered ${status}`);
+  const variable = tokenVariable(host);
+  const where = variable ? `${variable} or a credentials "${credentialsHost(host)}" block` : `a credentials "${credentialsHost(host) ?? host}" block in credentials.tfrc.json`;
+  return new RegistryError(token ? `${url} answered ${status}: the registry refused the token for ${host}` : `${url} answered ${status}: the registry wants a token; set ${where}`);
+};
+
+const optionsOf = (o: RegistryFetch | RegistryReadOptions | undefined): RegistryReadOptions => (typeof o === "function" ? { fetch: o } : (o ?? {}));
+
+/** The modules.v1 URL `services` names for a host, matched without case. */
+const serviceFor = (host: string, o: RegistryReadOptions): string | undefined => {
+  if (!o.services) return undefined;
+  const h = host.toLowerCase();
+  for (const [k, v] of Object.entries(o.services)) if (k.toLowerCase() === h) return v;
+  return undefined;
+};
+
+/** A source split by the hosts the options know as well as by the usual host shape. */
+const sourceOf = (source: string, o: RegistryReadOptions) => parseRegistrySource(source, [...Object.keys(o.services ?? {}), ...proxyLabels(o.proxies)]);
+
+/**
+ * Where a read of `source` goes: the source as written, or, when a proxy
+ * stands for its host, the proxy's host and namespace, with the options
+ * carrying the proxy's modules.v1 URL when it has one. A source with no host
+ * is taken at registry.terraform.io only when proxies are given, so a read
+ * without them refuses it as before.
+ */
+function readTarget(source: string, o: RegistryReadOptions): { s: RegistrySource; o: RegistryReadOptions } | undefined {
+  let s = sourceOf(source, o);
+  if (!s && o.proxies?.length) {
+    const base = source.split("?")[0]!.split("//")[0]!;
+    const parts = base.split("/");
+    if (parts.length === 3 && parts.every((p) => /^[0-9A-Za-z][0-9A-Za-z_-]*$/.test(p))) s = { host: DEFAULT_PROXY_UPSTREAM, namespace: parts[0]!, name: parts[1]!, system: parts[2]! };
+  }
+  if (!s) return undefined;
+  const r = proxyRoute(s, o.proxies);
+  if (!r) return { s, o };
+  return { s: { ...s, host: r.host, namespace: r.namespace }, o: r.modules ? { ...o, services: { ...o.services, [r.host]: r.modules } } : o };
+}
+
+/** The modules.v1 base a host's service discovery names, ending in `/`. */
+export async function modulesBase(host: string, options?: RegistryFetch | RegistryReadOptions): Promise<string> {
+  const o = optionsOf(options);
+  const mapped = serviceFor(host, o);
+  if (mapped !== undefined) return mapped.endsWith("/") ? mapped : `${mapped}/`;
+  const disco = `${o.scheme ?? "https"}://${host}/${DISCOVERY}`;
+  const token = readToken(host, o);
+  const res = await httpGet(o.fetch ?? globalFetch, disco, token, o.authorization);
+  if (!res.ok) throw answered(disco, res.status, host, token ?? o.authorization);
+  let base: unknown;
+  try {
+    base = ((await res.json()) as Record<string, unknown>)["modules.v1"];
+  } catch {
+    throw new RegistryError(`${disco} is not JSON`);
+  }
+  if (typeof base !== "string") throw new RegistryError(`${disco} names no modules.v1`);
+  const url = new URL(base, disco).toString();
+  return url.endsWith("/") ? url : `${url}/`;
+}
+
+/** Every version a registry lists for a module; none when it has no versions file. */
+export async function registryVersions(source: string, options?: RegistryFetch | RegistryReadOptions): Promise<string[]> {
+  const t = readTarget(source, optionsOf(options));
+  if (!t) throw new RegistryError(`${source} is not a registry source`);
+  const { s, o } = t;
+  const token = readToken(s.host, o);
+  const url = `${await modulesBase(s.host, { ...o, token: token ?? false })}${s.namespace}/${s.name}/${s.system}/versions`;
+  const res = await httpGet(o.fetch ?? globalFetch, url, token, o.authorization);
+  if (res.status === 404) return [];
+  if (!res.ok) throw answered(url, res.status, s.host, token ?? o.authorization);
+  return readVersions(await res.text());
+}
+
+export interface RegistryLocationOptions extends RegistryReadOptions {
+  /** Which CLI's reading to follow. Default `either`. */
+  reads?: DownloadReader;
+}
+
+/** The location a download answer gives, read as `reads` says, or undefined when it gives none that way. */
+export async function locationFromAnswer(res: Response, reads: DownloadReader = "either"): Promise<string | undefined> {
+  const header = res.headers.get(DOWNLOAD_HEADER) || undefined;
+  if (reads === "terraform") return res.status === 200 || res.status === 204 ? header : undefined;
+  let body: string | undefined;
+  if (res.status === 200) {
+    try {
+      const doc = (await res.json()) as { location?: unknown };
+      if (typeof doc.location === "string" && doc.location) body = doc.location;
+    } catch {
+      // OpenTofu fails on a 200 whose body is not JSON, before it looks at the header.
+      if (reads === "tofu") return undefined;
+    }
+  }
+  return reads === "tofu" ? (body ?? header) : (header ?? body);
+}
+
+/** Where a registry says one version is, resolved against the download URL when it is relative. */
+export async function registryLocation(source: string, version: string, options?: RegistryFetch | RegistryLocationOptions): Promise<string> {
+  const t = readTarget(source, optionsOf(options));
+  if (!t) throw new RegistryError(`${source} is not a registry source`);
+  const s = t.s;
+  const o = t.o as RegistryLocationOptions;
+  const token = readToken(s.host, o);
+  const url = `${await modulesBase(s.host, { ...o, token: token ?? false })}${s.namespace}/${s.name}/${s.system}/${version}/download`;
+  const res = await httpGet(o.fetch ?? globalFetch, url, token, o.authorization);
+  if (res.status === 404) throw new RegistryError(`${s.host}/${s.namespace}/${s.name}/${s.system} has no version ${version}`);
+  if (!res.ok) throw answered(url, res.status, s.host, token ?? o.authorization);
+  const reads = o.reads ?? "either";
+  let location = await locationFromAnswer(res, reads);
+  if (!location) {
+    throw new RegistryError(reads === "terraform" ? `${url} sends no ${DOWNLOAD_HEADER} header, and Terraform reads only the header` : `${url} names no location`);
+  }
+  if (/^(\.{0,2}\/)/.test(location)) location = new URL(location, url).toString();
+  return location;
+}
+
+/**
+ * The module archive a tarball location holds, uncompressed: the bytes a
+ * release's digest is of. The host's token goes along only when the location
+ * has no query string; a signed URL carries its own grant, and a bucket
+ * refuses a request that has both a signature and an `Authorization` header.
+ */
+export async function fetchTarball(location: string, options?: RegistryFetch | RegistryReadOptions): Promise<Buffer> {
+  const o = optionsOf(options);
+  const u = new URL(location);
+  const token = u.search || (u.protocol !== "https:" && u.protocol !== "http:") ? undefined : readToken(u.host, o);
+  const res = await httpGet(o.fetch ?? globalFetch, location, token);
+  if (!res.ok) throw answered(location, res.status, u.host, token);
+  const body = Buffer.from(await res.arrayBuffer());
+  try {
+    return gunzipSync(body);
+  } catch {
+    throw new RegistryError(`${location} is not a gzip archive`);
+  }
+}