@intentius/chant-lexicon-terraform 0.124.54 → 0.124.56

package/src/registry/targets/nexus.test.ts

@@ -0,0 +1,220 @@
+// chant#4605: the Nexus module target against the in-memory Nexus fake. No request leaves the
+// process, no CLI config file is written, and no credential appears in a log line or an error.
+import { describe, expect, it } from "vitest";
+import { PublishTargetError } from "@intentius/chant/lifecycle/release-publish";
+import { createRedactor } from "@intentius/chant/lifecycle/publish-credentials";
+import {
+  archiveContent,
+  moduleZip,
+  nexusHostBlock,
+  nexusHostLabel,
+  nexusModuleTarget,
+  nexusUploadUrl,
+  readModuleZipComment,
+  readZip,
+  registryVersions,
+  type ModuleVersionContext,
+} from "../index";
+import { createFakeNexus, type FakeNexusOptions } from "./fake-nexus";
+import { moduleTarball } from "./fake-http";
+
+const HOST = "nexus.example.com";
+const URL_ = `https://${HOST}`;
+const USER = "tf-publisher";
+const TOKEN = "nexus-pass-0123456789abcdef";
+const ENV = { NEXUS_USER: USER, NEXUS_TOKEN: TOKEN };
+const BASIC = `Basic ${Buffer.from(`${USER}:${TOKEN}`).toString("base64")}`;
+
+const fake = (over: Partial<FakeNexusOptions> = {}) => createFakeNexus({ host: HOST, repos: ["terraform-hosted"], users: { [USER]: TOKEN }, ...over });
+
+const clock = () => {
+  let t = 0;
+  const sleeps: number[] = [];
+  return { now: () => t, sleep: async (ms: number) => void (sleeps.push(ms), (t += ms)), sleeps };
+};
+
+const archiveOf = (text: string) => moduleTarball({ "main.tf": `# ${text}\n`, "outputs.tf": "" });
+
+function context(env: NodeJS.ProcessEnv, over: Partial<ModuleVersionContext> = {}): ModuleVersionContext & { lines: string[] } {
+  const archive = over.archive ?? archiveOf("vpc 1.2.0");
+  const redactor = createRedactor(env, ["NEXUS_TOKEN"]);
+  const lines: string[] = [];
+  return {
+    cwd: "/nowhere",
+    env,
+    redactor,
+    log: (line) => lines.push(redactor.redact(line)),
+    provenance: { oidc: false, ci: null, reason: "not in CI" },
+    tag: null,
+    address: { namespace: "acme", name: "vpc", system: "aws" },
+    version: "1.2.0",
+    revision: "3f2a9c1d0b7e3f2a9c1d0b7e3f2a9c1d0b7e3f2a",
+    content: archiveContent(archive),
+    archive,
+    ...over,
+    lines,
+  };
+}
+
+const target = (nx: ReturnType<typeof fake>, opts = {}, c = clock()) =>
+  nexusModuleTarget({ url: URL_, repo: "terraform-hosted", ...opts }, { fetch: nx.fetch, registryFetch: nx.fetch, sleep: c.sleep, now: c.now });
+
+const errorOf = async (p: Promise<unknown>): Promise<PublishTargetError> => {
+  const e = await p.then(
+    () => undefined,
+    (err: unknown) => err,
+  );
+  expect(e).toBeInstanceOf(PublishTargetError);
+  return e as PublishTargetError;
+};
+
+const noSecret = (text: string) => {
+  expect(text).not.toContain(TOKEN);
+  expect(text).not.toContain(BASIC.slice(6));
+  expect(text).not.toMatch(/TerraformBearerToken\.fake/);
+};
+
+describe("Nexus module target (chant#4605)", () => {
+  it("uploads the zip of the attested archive with one PUT, basic credentials and application/zip", async () => {
+    const nx = fake();
+    const ctx = context(ENV);
+    const t = target(nx);
+    expect(await t.plan(ctx)).toEqual([{ name: "acme/vpc/aws 1.2.0", destination: "terraform-hosted/acme/vpc/aws", digest: ctx.content }]);
+    const staged = await t.stage(ctx);
+    const puts = nx.requests.filter((r) => r.method === "PUT");
+    expect(puts).toHaveLength(1);
+    expect(puts[0]!.url).toBe(`${URL_}/repository/terraform-hosted/v1/modules/acme/vpc/aws/1.2.0/vpc-1.2.0.zip`);
+    expect(puts[0]!.headers.authorization).toBe(BASIC);
+    expect(puts[0]!.headers["content-type"]).toBe("application/zip");
+    expect(Buffer.compare(Buffer.from(puts[0]!.body!), moduleZip(ctx.archive, ctx.content, ctx.revision))).toBe(0);
+    expect(readModuleZipComment(readZip(puts[0]!.body!).comment)?.content).toBe(ctx.content);
+    noSecret(JSON.stringify(staged));
+
+    const published = await t.reveal(ctx, staged);
+    expect(published.destination).toBe("terraform-hosted/acme/vpc/aws");
+    expect(await t.held(ctx.address, "1.2.0", ctx)).toEqual({ content: ctx.content, revision: ctx.revision });
+  });
+
+  it("reads back through the registry protocol with an in-memory host block, never discovery", async () => {
+    const nx = fake();
+    const ctx = context(ENV);
+    const t = target(nx);
+    await t.reveal(ctx, await t.stage(ctx));
+    const paths = nx.requests.map((r) => new URL(r.url).pathname);
+    expect(paths).not.toContain("/.well-known/terraform.json");
+    expect(paths).toContain("/repository/terraform-hosted/v1/modules/acme/vpc/aws/versions");
+    expect(paths).toContain("/repository/terraform-hosted/v1/modules/acme/vpc/aws/1.2.0/download");
+  });
+
+  it("reads with the 3.95 bearer token issued for the basic credentials", async () => {
+    const nx = fake();
+    const ctx = context(ENV);
+    const t = target(nx);
+    await t.reveal(ctx, await t.stage(ctx));
+    expect(nx.issued.size).toBe(1);
+    const read = nx.requests.find((r) => r.url.endsWith("/versions"))!;
+    expect(read.headers.authorization).toBe(`Bearer ${[...nx.issued][0]}`);
+    noSecret(ctx.lines.join("\n"));
+  });
+
+  it("reads with the basic credentials on a Nexus without the token call", async () => {
+    const nx = fake({ bearer: false });
+    const ctx = context(ENV);
+    const t = target(nx);
+    await t.reveal(ctx, await t.stage(ctx));
+    const read = nx.requests.find((r) => r.url.endsWith("/versions"))!;
+    expect(read.headers.authorization).toBe(BASIC);
+  });
+
+  it("reads with TF_TOKEN_<nexus host> when it is set", async () => {
+    const nx = fake({ bearer: false });
+    const ctx = context({ ...ENV, TF_TOKEN_nexus_example_com: "cli-token-1234567890" });
+    const t = target(nx);
+    const read = await errorOf(t.versions(ctx.address, ctx));
+    // The fake does not know the CLI token: the read is refused, and the token is never printed.
+    expect(read.code).toBe("publish-read-failed");
+    expect(read.message).not.toContain("cli-token-1234567890");
+    expect(nx.requests.at(-1)!.headers.authorization).toBe("Bearer cli-token-1234567890");
+  });
+
+  it("waits out a cached not-found after the upload", async () => {
+    const nx = fake({ cacheNotFound: 2 });
+    const c = clock();
+    const ctx = context(ENV);
+    const t = target(nx, { pollMs: 500 }, c);
+    await t.reveal(ctx, await t.stage(ctx));
+    expect(c.sleeps).toEqual([500, 500]);
+  });
+
+  it("stops after the wait when the version is never listed", async () => {
+    const nx = fake({ cacheNotFound: 100 });
+    const ctx = context(ENV);
+    const t = target(nx, { waitMs: 1000, pollMs: 500 });
+    const e = await errorOf(t.reveal(ctx, await t.stage(ctx)));
+    expect(e.code).toBe("publish-reveal-missing");
+    expect(e.fix).toContain("3.95.0");
+  });
+
+  it("sends nothing for a version already uploaded with the same content", async () => {
+    const nx = fake();
+    const ctx = context(ENV);
+    nx.seed("terraform-hosted", "acme", "vpc", "aws", "1.2.0", "vpc-1.2.0.zip", moduleZip(ctx.archive, ctx.content));
+    const staged = await target(nx).stage(ctx);
+    expect(staged.items[0]!.present).toBe(true);
+    expect(nx.requests.filter((r) => r.method === "PUT")).toHaveLength(0);
+  });
+
+  it("refuses a version already uploaded with other content", async () => {
+    const nx = fake();
+    const ctx = context(ENV);
+    const other = archiveOf("other");
+    nx.seed("terraform-hosted", "acme", "vpc", "aws", "1.2.0", "vpc-1.2.0.zip", moduleZip(other, archiveContent(other)));
+    expect((await errorOf(target(nx).stage(ctx))).code).toBe("publish-version-held");
+  });
+
+  it("refuses a 401 naming the variables, never their values", async () => {
+    const nx = fake();
+    const ctx = context({ NEXUS_USER: USER, NEXUS_TOKEN: "nexus-wrong-pass-0000" });
+    const e = await errorOf(target(nx).stage(ctx));
+    expect(e.code).toBe("publish-credentials-refused");
+    expect(`${e.message} ${e.fix}`).not.toContain("nexus-wrong-pass-0000");
+  });
+
+  it("refuses to plan without a user or a token", async () => {
+    const nx = fake();
+    const e = await errorOf(target(nx).plan(context({ NEXUS_TOKEN: TOKEN })));
+    expect(e.code).toBe("publish-credentials-missing");
+    expect(e.message).toContain("NEXUS_USER");
+  });
+
+  it("names the hosted floor on an upload Nexus refuses", async () => {
+    const nx = fake();
+    const ctx = context(ENV);
+    const failing: typeof nx.fetch = async (url, init) => (init?.method === "PUT" ? new Response("{}", { status: 500 }) : nx.fetch(url, init));
+    const e = await errorOf(nexusModuleTarget({ url: URL_, repo: "terraform-hosted" }, { fetch: failing, registryFetch: failing }).stage(ctx));
+    expect(e.code).toBe("publish-upload-failed");
+    expect(e.fix).toContain("3.89.0");
+  });
+
+  it("gives the CLI host block consumers add, and refuses a label a host block cannot carry", () => {
+    expect(nexusHostBlock({ url: URL_, repo: "terraform-hosted" })).toBe(
+      `host "terraform-hosted" {\n  services = {\n    "modules.v1" = "${URL_}/repository/terraform-hosted/v1/modules/"\n  }\n}\n`,
+    );
+    expect(() => nexusHostLabel({ repo: "terraform_hosted" })).toThrow(PublishTargetError);
+    expect(nexusHostLabel({ repo: "terraform_hosted", host: "tf-hosted" })).toBe("tf-hosted");
+    expect(nexusUploadUrl(URL_, "r", { namespace: "n", name: "m", system: "aws" }, "1.0.0")).toBe(`${URL_}/repository/r/v1/modules/n/m/aws/1.0.0/m-1.0.0.zip`);
+  });
+
+  it("lets the registry reader take a bare host from its services map", async () => {
+    const nx = fake();
+    const ctx = context(ENV);
+    await target(nx).stage(ctx);
+    const versions = await registryVersions("terraform-hosted/acme/vpc/aws", {
+      services: { "terraform-hosted": `${URL_}/repository/terraform-hosted/v1/modules/` },
+      authorization: BASIC,
+      token: false,
+      fetch: nx.fetch,
+    });
+    expect(versions).toEqual(["1.2.0"]);
+  });
+});

package/src/registry/targets/nexus.ts

@@ -0,0 +1,314 @@
+/**
+ * A Sonatype Nexus Repository hosted Terraform repository as a module target
+ * (chant#4605), from the research on terragucci#1299 and its ruling.
+ *
+ * Nexus has a Terraform format from 3.88 and hosted Terraform repositories
+ * from 3.89, which is this target's floor. The one write is the documented
+ * module upload (help.sonatype.com, CLI usage and options):
+ *
+ *   PUT <url>/repository/<repo>/v1/modules/<namespace>/<name>/<system>/<version>/<name>-<version>.zip
+ *
+ * with `Content-Type: application/zip`, basic `user:token` credentials
+ * (ruling B) and the zip of the attested archive as the body (ruling A,
+ * ./zip.ts). The user is `NEXUS_USER` (or the declaration's `user` or
+ * `userEnv`) and the token `NEXUS_TOKEN` (or `tokenEnv`), a user token's
+ * pass code or the user's password.
+ *
+ * Nexus has no single registry host to discover from: a consumer declares a
+ * CLI `host "<name>"` block mapping `modules.v1` to the repository's
+ * `<url>/repository/<repo>/v1/modules/`, and writes
+ * `<name>/<namespace>/<name>/<system>`. `nexusHostBlock` gives that block.
+ * `versions` and `reveal` read the module the same way, with the block held
+ * in memory as the reader's `services` map (ruling C), so no CLI config file
+ * is written. The reads send `TF_TOKEN_<nexus host>` when it is set, else the
+ * bearer token Nexus 3.95 and later issue at `<repo>/v1/api/token` for the
+ * basic credentials, else the basic credentials themselves, which Nexus
+ * takes as header authentication before 3.95. Nexus before 3.95 kept a "not
+ * found" answer in its cache, so `reveal` waits for the version to be
+ * listed, up to `waitMs` (default 30s).
+ *
+ * `held` GETs the uploaded zip at its path. A chant zip names the attested
+ * content in its archive comment, so the same content comes back `present`
+ * with nothing sent and other content is refused.
+ *
+ * Not confirmed by the docs (terragucci#1299): Sonatype's page on creating a
+ * Terraform repository says GPG signing is mandatory for hosted repositories
+ * and also that it is optional for modules, so what a module upload does on
+ * a repository with no signing key is unknown; whether a second upload of a
+ * version is refused; whether a hosted repository serves
+ * `/.well-known/terraform.json` (this target never asks for it); and the
+ * answer shape of the 3.95 token call (this reads a JSON `token` field, else
+ * the body as text). Nexus shows no deprecation for a module version, so 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 BasicCredential,
+  type BasicCredentialEnv,
+} from "./hosted";
+import { heldContentOf, moduleZip } from "./zip";
+
+/** How a Nexus module target is declared. */
+export interface NexusModuleTargetOptions {
+  /** The Nexus base, such as `https://nexus.example.com`. */
+  url: string;
+  /** The hosted Terraform repository's name. */
+  repo: string;
+  /**
+   * The label of the consumers' CLI `host` block, which their sources start
+   * with. Default: the repository's name, lower-cased. It must be a valid host name.
+   */
+  host?: string;
+  /** The variable the token (a user token's pass code, or the password) is read from. Default `NEXUS_TOKEN`. */
+  tokenEnv?: string;
+  /** The variable the user name (a user token's name code, or the user) is read from. Default `NEXUS_USER`. */
+  userEnv?: string;
+  /** The user name, in place of `userEnv`. */
+  user?: string;
+  /** How long `reveal` waits for Nexus to list the version. Default 30s. */
+  waitMs?: number;
+  /** How often it asks while it waits. Default 2s. */
+  pollMs?: number;
+}
+
+export const NEXUS_TOKEN_ENV = "NEXUS_TOKEN";
+export const NEXUS_USER_ENV = "NEXUS_USER";
+/** The first Nexus release with hosted Terraform repositories. */
+export const NEXUS_HOSTED_FLOOR = "3.89.0";
+/** The first Nexus release with the bearer token call and the archive and cache fixes the research names. */
+export const NEXUS_BEARER_FLOOR = "3.95.0";
+
+const HOST_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$/;
+
+/** The Nexus base, without a trailing slash. */
+export function nexusBase(url: string): string {
+  try {
+    const u = new URL(url);
+    return `${u.origin}${u.pathname.replace(/\/+$/, "")}`;
+  } catch {
+    throw new PublishTargetError("publish-config-invalid", `${url} is not a URL`, "Set url to the Nexus base, such as https://nexus.example.com.");
+  }
+}
+
+/** The repository's modules.v1 URL, ending in `/`. */
+export const nexusModulesUrl = (base: string, repo: string): string => `${base}/repository/${encodeURIComponent(repo)}/v1/modules/`;
+
+/** The upload path of one version's zip. */
+export function nexusUploadUrl(base: string, repo: string, a: ModuleAddress, version: string): string {
+  const seg = [a.namespace, a.name, a.system, version].map(encodeURIComponent).join("/");
+  return `${nexusModulesUrl(base, repo)}${seg}/${encodeURIComponent(`${a.name}-${version}.zip`)}`;
+}
+
+/** The label of the consumers' `host` block. */
+export function nexusHostLabel(o: Pick<NexusModuleTargetOptions, "repo" | "host">): string {
+  const label = (o.host ?? o.repo).toLowerCase();
+  if (!HOST_LABEL.test(label)) {
+    throw new PublishTargetError("publish-config-invalid", `${JSON.stringify(label)} is not a host name a CLI host block can carry`, "Set the declaration's host to a name of letters, digits and -, such as the repository's name without _.");
+  }
+  return label;
+}
+
+/** The source consumers write for a module in the repository: `<host label>/<namespace>/<name>/<system>`. */
+export const nexusSource = (label: string, a: ModuleAddress): string => `${label}/${a.namespace}/${a.name}/${a.system}`;
+
+/** The CLI configuration block a consumer adds so its sources reach the repository. */
+export function nexusHostBlock(o: Pick<NexusModuleTargetOptions, "url" | "repo" | "host">): string {
+  return `host "${nexusHostLabel(o)}" {\n  services = {\n    "modules.v1" = "${nexusModulesUrl(nexusBase(o.url), o.repo)}"\n  }\n}\n`;
+}
+
+export function nexusModuleTarget(options: NexusModuleTargetOptions, deps: ModuleTargetDeps = {}): ModulePublishTarget<"nexus"> {
+  const put = deps.fetch ?? defaultPublishFetch;
+  const get = deps.registryFetch ?? defaultRegistryFetch;
+  const names: BasicCredentialEnv = { tokenEnv: options.tokenEnv ?? NEXUS_TOKEN_ENV, userEnv: options.userEnv ?? NEXUS_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 = `nexus:${createHash("sha256")
+    .update(JSON.stringify({ url: options.url, repo: options.repo, host: options.host ?? null, tokenEnv: names.tokenEnv, userEnv: names.userEnv, user: options.user ?? null }))
+    .digest("hex")
+    .slice(0, 16)}`;
+
+  const where = () => {
+    const base = nexusBase(options.url);
+    const label = nexusHostLabel(options);
+    return { base, label, nexusHost: new URL(base).host.toLowerCase(), modules: nexusModulesUrl(base, options.repo) };
+  };
+  const fix = `Use a user token, or a user, that may add and edit components in the repository ${options.repo}.`;
+  const needCredential = (ctx: Pick<PublishContextBase, "env" | "redactor">) => needBasicCredential(ctx, names, "Nexus", fix);
+
+  /** The bearer token from Nexus 3.95's token call, per credential; null when the call is not there. */
+  const issued = new Map<string, string | null>();
+  const issuedToken = async (ctx: Pick<PublishContextBase, "redactor">, basic: BasicCredential): Promise<string | null> => {
+    if (issued.has(basic.header)) return issued.get(basic.header)!;
+    const { base } = where();
+    const url = `${base}/repository/${encodeURIComponent(options.repo)}/v1/api/token`;
+    const { status, bytes } = await getBytes(ctx, get, url, basic.header);
+    let token: string | null = null;
+    if (status >= 200 && status <= 299) {
+      const text = Buffer.from(bytes).toString("utf-8").trim();
+      try {
+        const doc = JSON.parse(text) as { token?: unknown };
+        token = typeof doc.token === "string" && doc.token ? doc.token : null;
+      } catch {
+        token = text || null;
+      }
+    }
+    ctx.redactor.add(token);
+    issued.set(basic.header, token);
+    return token;
+  };
+
+  /** How the reads authenticate: the CLIs' token for the Nexus host, else the issued bearer token, else basic. */
+  const readAuth = async (ctx: Pick<PublishContextBase, "env" | "redactor">): Promise<string | undefined> => {
+    const { nexusHost } = where();
+    const cli = terraformCredential(nexusHost, { env: ctx.env })?.token;
+    if (cli) {
+      ctx.redactor.add(cli);
+      return `Bearer ${cli}`;
+    }
+    const basic = readBasicCredential(ctx, names);
+    if (!basic) return undefined;
+    const bearer = await issuedToken(ctx, basic);
+    return bearer ? `Bearer ${bearer}` : basic.header;
+  };
+  const readOptions = async (ctx: Pick<PublishContextBase, "env" | "redactor">): Promise<RegistryReadOptions> => {
+    const { label, modules } = where();
+    const authorization = await readAuth(ctx);
+    return { services: { [label]: modules }, token: false, fetch: get, ...(authorization ? { authorization } : {}) };
+  };
+  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 = await readOptions(ctx);
+    return read(ctx, () => registryVersions(nexusSource(where().label, address), o));
+  };
+
+  const held = async (address: ModuleAddress, version: string, ctx: Pick<PublishContextBase, "env" | "redactor">): Promise<HeldVersion | undefined> => {
+    const { base } = where();
+    const url = nexusUploadUrl(base, options.repo, address, version);
+    const { status, bytes } = await getBytes(ctx, get, url, await readAuth(ctx));
+    if (status === 404) return undefined;
+    if (status === 401 || status === 403) {
+      throw answerError(ctx, "publish-credentials-refused", `Nexus answered ${status} to a read of ${url}`, `Set ${names.userEnv} and ${names.tokenEnv} to a user with read access to ${options.repo}.`);
+    }
+    if (status < 200 || status > 299) throw answerError(ctx, "publish-read-failed", `Nexus answered ${status} to a read of ${url}`);
+    return heldContentOf(bytes, contentDigest);
+  };
+
+  const item = (ctx: ModuleVersionContext, present?: boolean): PublishItem => {
+    const { label } = where();
+    const a = ctx.address;
+    return { name: `${a.namespace}/${a.name}/${a.system} ${ctx.version}`, destination: nexusSource(label, a), digest: ctx.content, ...(present ? { present: true } : {}) };
+  };
+
+  return {
+    kind: "nexus",
+    name: "Nexus 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, label } = where();
+      const source = nexusSource(label, ctx.address);
+      const staged = (present: boolean): StagedTarget => ({ target: "nexus", destination: source, items: [item(ctx, present)], state: { repo: options.repo, url: base, 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 = nexusUploadUrl(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(`uploaded ${source} ${ctx.version} to ${options.repo}`);
+        return staged(false);
+      }
+      if (res.status === 400 || res.status === 403 || res.status === 409) {
+        // A deployment policy that refuses a redeploy, or another run uploading 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, "Nexus", res.status, `${source} ${ctx.version}`, credential, names, fix);
+      throw answerError(
+        ctx,
+        "publish-upload-failed",
+        `Nexus answered ${res.status} to the upload of ${source} ${ctx.version}: ${text.slice(0, 300)}`,
+        `Hosted Terraform repositories need Nexus ${NEXUS_HOSTED_FLOOR} or later; check that ${options.repo} is a hosted Terraform repository with a signing key.`,
+      );
+    },
+
+    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 upload`,
+          `Nexus before ${NEXUS_BEARER_FLOOR} can keep an earlier "not found" in its cache; run the publish again once it has expired.`,
+        );
+      }
+      const o = await readOptions(ctx);
+      const location = await read(ctx, () => registryLocation(staged.destination, ctx.version, o));
+      const got = await locationContent(ctx, get, location, where().nexusHost, o.authorization);
+      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/zip.test.ts

@@ -0,0 +1,65 @@
+// chant#4605: the zip of an attested module archive keeps every file, path and mode, is the
+// same bytes every time, and names the attested content in its archive comment.
+import { gzipSync } from "node:zlib";
+import { describe, expect, it } from "vitest";
+import { PublishTargetError } from "@intentius/chant/lifecycle/release-publish";
+import { archiveContent, contentDigest, heldContentOf, moduleArchiveEntries, moduleZip, readModuleZipComment, readZip } from "../index";
+import { moduleTarball } from "./fake-http";
+
+const FILES = {
+  "main.tf": 'resource "null_resource" "a" {}\n',
+  "variables.tf": 'variable "cidr" {}\n',
+  "modules/sub/main.tf": "# sub\n",
+  "README.md": "# vpc\n",
+};
+
+describe("module zip (chant#4605)", () => {
+  it("carries every file of the tarball at its path with its bytes", () => {
+    const archive = moduleTarball(FILES);
+    const zip = readZip(moduleZip(archive, archiveContent(archive)));
+    const files = Object.fromEntries(zip.entries.filter((e) => !e.dir).map((e) => [e.path, e.data.toString("utf-8")]));
+    expect(files).toEqual(FILES);
+    expect(zip.entries.filter((e) => e.dir).map((e) => e.path)).toEqual(["modules", "modules/sub"]);
+    expect(zip.entries.find((e) => e.path === "main.tf")!.mode).toBe(0o644);
+  });
+
+  it("gives the same bytes for the same archive", () => {
+    const archive = moduleTarball(FILES);
+    const content = archiveContent(archive);
+    expect(Buffer.compare(moduleZip(archive, content, "abc"), moduleZip(archive, content, "abc"))).toBe(0);
+  });
+
+  it("names the attested content and revision in the archive comment", () => {
+    const archive = moduleTarball(FILES);
+    const content = archiveContent(archive);
+    const zip = moduleZip(archive, content, "3f2a9c1d");
+    expect(readModuleZipComment(readZip(zip).comment)).toEqual({ content, revision: "3f2a9c1d" });
+    expect(heldContentOf(zip, contentDigest)).toEqual({ content, revision: "3f2a9c1d" });
+  });
+
+  it("judges a gzip tarball by its uncompressed bytes and any other bytes by their own digest", () => {
+    const archive = moduleTarball(FILES);
+    expect(heldContentOf(archive, contentDigest).content).toBe(archiveContent(archive));
+    const plain = Buffer.from("not an archive");
+    expect(heldContentOf(plain, contentDigest).content).toBe(contentDigest(plain));
+  });
+
+  it("cuts ./ from paths", () => {
+    const entries = moduleArchiveEntries(moduleTarball({ "./main.tf": "x" }));
+    expect(entries.map((e) => e.path)).toEqual(["main.tf"]);
+  });
+
+  it("refuses bytes that are not a gzip tarball", () => {
+    expect(() => moduleArchiveEntries(Buffer.from("plain"))).toThrow(PublishTargetError);
+  });
+
+  it("refuses a path outside the archive's root", () => {
+    const header = Buffer.alloc(512);
+    header.write("../evil.tf", 0);
+    header.write("0000644\0", 100);
+    header.write("00000000000\0", 124);
+    header.write("0", 156);
+    const tar = gzipSync(Buffer.concat([header, Buffer.alloc(1024)]));
+    expect(() => moduleArchiveEntries(tar)).toThrow(/outside its root/);
+  });
+});