@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

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

@@ -0,0 +1,208 @@
+// chant#4603: the GitLab module target against the in-memory GitLab fake. No request leaves the
+// process, and no token value appears in a log line, an error or a staged record.
+import { gzipSync } from "node:zlib";
+import { describe, expect, it } from "vitest";
+import { PublishTargetError } from "@intentius/chant/lifecycle/release-publish";
+import { createRedactor, REDACTED } from "@intentius/chant/lifecycle/publish-credentials";
+import { archiveContent, gitlabModuleTarget, gitlabUploadUrl, type ModuleVersionContext } from "../index";
+import { createFakeGitlab } from "./fake-gitlab";
+
+const HOST = "gitlab.example.com";
+const API = `https://${HOST}/api/v4`;
+const WRITE_TOKEN = "glpat-write-0123456789";
+const READ_TOKEN = "glpat-read-9876543210";
+const JOB_TOKEN = "job-token-abcdefghij";
+const OTHER_TOKEN = "glpat-other-project-0000";
+
+function fake() {
+  return createFakeGitlab({
+    host: HOST,
+    projects: { "42": "acme/modules", "7": "elsewhere/other" },
+    tokens: { [WRITE_TOKEN]: ["42"], [READ_TOKEN]: [], [JOB_TOKEN]: ["42"], [OTHER_TOKEN]: ["7"] },
+  });
+}
+
+const archiveOf = (text: string) => gzipSync(Buffer.from(`module tar: ${text}`));
+
+function context(env: NodeJS.ProcessEnv, over: Partial<ModuleVersionContext> = {}): ModuleVersionContext & { lines: string[] } {
+  const archive = over.archive ?? archiveOf("vpc 1.2.0");
+  const redactor = createRedactor(env);
+  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 = (gl: ReturnType<typeof fake>, opts = {}) => gitlabModuleTarget({ api: API, project: "42", ...opts }, { fetch: gl.fetch, registryFetch: gl.fetch });
+
+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;
+};
+
+describe("GitLab module target (chant#4603)", () => {
+  it("uploads with one PUT to the project's module file path, with the token header and the archive as the body", async () => {
+    const gl = fake();
+    const ctx = context({ GITLAB_TOKEN: WRITE_TOKEN });
+    const t = target(gl);
+    expect(await t.plan(ctx)).toEqual([{ name: "acme/vpc/aws 1.2.0", destination: `${HOST}/acme/vpc/aws`, digest: ctx.content }]);
+    const staged = await t.stage(ctx);
+    const puts = gl.requests.filter((r) => r.method === "PUT");
+    expect(puts).toHaveLength(1);
+    expect(puts[0]!.url).toBe(`${API}/projects/42/packages/terraform/modules/vpc/aws/1.2.0/file`);
+    expect(puts[0]!.headers["private-token"]).toBe(WRITE_TOKEN);
+    expect(puts[0]!.headers["job-token"]).toBeUndefined();
+    expect(puts[0]!.headers["content-type"]).toBe("application/octet-stream");
+    expect(Buffer.from(puts[0]!.body!)).toEqual(Buffer.from(ctx.archive));
+    expect(staged.items[0]!.present).toBeUndefined();
+    expect(JSON.stringify(staged)).not.toContain(WRITE_TOKEN);
+
+    const published = await t.reveal(ctx, staged);
+    expect(published.destination).toBe(`${HOST}/acme/vpc/aws`);
+    expect(await t.versions(ctx.address, ctx)).toEqual(["1.2.0"]);
+  });
+
+  it("sends a CI job token as JOB-TOKEN, with the project and API root from GitLab CI's variables", async () => {
+    const gl = fake();
+    const ctx = context({ CI_JOB_TOKEN: JOB_TOKEN, CI_PROJECT_ID: "42", CI_API_V4_URL: API });
+    const t = gitlabModuleTarget({}, { fetch: gl.fetch, registryFetch: gl.fetch });
+    await t.stage(ctx);
+    const put = gl.requests.find((r) => r.method === "PUT")!;
+    expect(put.headers["job-token"]).toBe(JOB_TOKEN);
+    expect(put.headers["private-token"]).toBeUndefined();
+    expect(put.url).toBe(gitlabUploadUrl(API, "42", ctx.address, "1.2.0"));
+  });
+
+  it("encodes a project given by its full path", () => {
+    expect(gitlabUploadUrl(API, "acme/modules", { name: "vpc", system: "aws" }, "1.2.0")).toBe(`${API}/projects/acme%2Fmodules/packages/terraform/modules/vpc/aws/1.2.0/file`);
+  });
+
+  it("comes back present and sends nothing when the version is held with the same content", async () => {
+    const gl = fake();
+    const ctx = context({ GITLAB_TOKEN: WRITE_TOKEN });
+    gl.seed("42", "vpc", "aws", "1.2.0", ctx.archive);
+    const t = target(gl);
+    expect(await t.held(ctx.address, "1.2.0", ctx)).toEqual({ content: ctx.content });
+    const staged = await t.stage(ctx);
+    expect(staged.items[0]!.present).toBe(true);
+    expect(gl.requests.filter((r) => r.method === "PUT")).toHaveLength(0);
+    expect(ctx.lines.some((l) => l.includes("nothing sent"))).toBe(true);
+  });
+
+  it("refuses a version held with other content, and sends nothing", async () => {
+    const gl = fake();
+    const ctx = context({ GITLAB_TOKEN: WRITE_TOKEN });
+    gl.seed("42", "vpc", "aws", "1.2.0", archiveOf("something else"));
+    const err = await errorOf(target(gl).stage(ctx));
+    expect(err.code).toBe("publish-version-held");
+    expect(err.message).toContain(archiveContent(archiveOf("something else")));
+    expect(gl.requests.filter((r) => r.method === "PUT")).toHaveLength(0);
+  });
+
+  it("answers held with undefined for a version the host does not list", async () => {
+    const gl = fake();
+    const ctx = context({ GITLAB_TOKEN: WRITE_TOKEN });
+    expect(await target(gl).held(ctx.address, "9.9.9", ctx)).toBeUndefined();
+    expect(await target(gl).versions(ctx.address, ctx)).toEqual([]);
+  });
+
+  it("names the variable on a 401, never its value", async () => {
+    const gl = fake();
+    const ctx = context({ GITLAB_TOKEN: "glpat-unknown-to-the-fake" }, {});
+    gl.seed("42", "other", "aws", "0.1.0", archiveOf("x"));
+    // Reads take TF_TOKEN_<host>, so the upload is the call that meets the unknown token.
+    const env = { ...ctx.env, TF_TOKEN_gitlab_example_com: READ_TOKEN };
+    const c = context(env);
+    const err = await errorOf(target(gl).stage(c));
+    expect(err.code).toBe("publish-credentials-refused");
+    expect(err.message).toContain("401");
+    expect(err.message).toContain("GITLAB_TOKEN");
+    expect(`${err.message} ${err.fix}`).not.toContain("glpat-unknown-to-the-fake");
+  });
+
+  it("names the variable on a 403, never its value", async () => {
+    const gl = fake();
+    const ctx = context({ DEPLOY_TOKEN: OTHER_TOKEN, TF_TOKEN_gitlab_example_com: READ_TOKEN });
+    const err = await errorOf(target(gl, { tokenEnv: "DEPLOY_TOKEN" }).stage(ctx));
+    expect(err.code).toBe("publish-credentials-refused");
+    expect(err.message).toContain("403");
+    expect(err.message).toContain("DEPLOY_TOKEN");
+    expect(`${err.message} ${err.fix}`).not.toContain(OTHER_TOKEN);
+  });
+
+  it("refuses to plan without a token or a project, naming what to set", async () => {
+    const gl = fake();
+    const none = await errorOf(target(gl).plan(context({})));
+    expect(none.code).toBe("publish-credentials-missing");
+    expect(none.message).toContain("GITLAB_TOKEN or CI_JOB_TOKEN");
+    const noProject = await errorOf(gitlabModuleTarget({ api: API }, { fetch: gl.fetch, registryFetch: gl.fetch }).plan(context({ GITLAB_TOKEN: WRITE_TOKEN })));
+    expect(noProject.code).toBe("publish-config-invalid");
+    expect(noProject.fix).toContain("CI_PROJECT_ID");
+  });
+
+  it("refuses an archive whose content is not the one the context names", async () => {
+    const gl = fake();
+    const ctx = context({ GITLAB_TOKEN: WRITE_TOKEN }, { content: "sha256:0000" });
+    expect((await errorOf(target(gl).plan(ctx))).code).toBe("publish-artifact-digest-mismatch");
+  });
+
+  it("reads back with TF_TOKEN_<host> as a bearer token, apart from the upload token", async () => {
+    const gl = fake();
+    const ctx = context({ GITLAB_TOKEN: WRITE_TOKEN, TF_TOKEN_gitlab_example_com: READ_TOKEN });
+    const t = target(gl);
+    await t.reveal(ctx, await t.stage(ctx));
+    const reads = gl.requests.filter((r) => r.method === "GET" && r.url.includes("/packages/terraform/modules/v1/") && !r.url.includes("/file?"));
+    expect(reads.length).toBeGreaterThan(0);
+    for (const r of reads) expect(r.headers.authorization).toBe(`Bearer ${READ_TOKEN}`);
+    const tarball = gl.requests.find((r) => r.url.includes("/file?"));
+    // The download link carries its own grant, so no Authorization header goes with it.
+    if (tarball) expect(tarball.headers.authorization).toBeUndefined();
+  });
+
+  it("a refused read names TF_TOKEN_<host>, never a value", async () => {
+    const gl = fake();
+    const ctx = context({ TF_TOKEN_gitlab_example_com: "not-a-known-token-value" });
+    const err = await errorOf(target(gl).versions(ctx.address, ctx));
+    expect(err.code).toBe("publish-read-failed");
+    expect(err.message).toContain("refused the token");
+    expect(err.message).not.toContain("not-a-known-token-value");
+  });
+
+  it("masks every token in every log line and error", async () => {
+    const gl = fake();
+    const ctx = context({ GITLAB_TOKEN: WRITE_TOKEN, TF_TOKEN_gitlab_example_com: READ_TOKEN });
+    const t = target(gl);
+    await t.reveal(ctx, await t.stage(ctx));
+    // A rerun with other content fails; its error must be clean too.
+    const other = context(ctx.env, { archive: archiveOf("changed"), content: archiveContent(archiveOf("changed")) });
+    const err = await errorOf(t.stage(other));
+    const all = [...ctx.lines, ...other.lines, err.message, err.fix ?? ""].join("\n");
+    for (const secret of [WRITE_TOKEN, READ_TOKEN]) expect(all).not.toContain(secret);
+    expect(ctx.redactor.redact(`PRIVATE-TOKEN: ${WRITE_TOKEN} and ${READ_TOKEN}`)).toBe(`PRIVATE-TOKEN: ${REDACTED} and ${REDACTED}`);
+  });
+
+  it("keeps the download link's grant out of error text", async () => {
+    const gl = fake();
+    const ctx = context({ GITLAB_TOKEN: WRITE_TOKEN, TF_TOKEN_gitlab_example_com: READ_TOKEN });
+    gl.seed("42", "vpc", "aws", "1.2.0", new Uint8Array([1, 2, 3]));
+    const err = await errorOf(target(gl).held(ctx.address, "1.2.0", ctx));
+    expect(err.message).toContain("?[query]");
+    expect(err.message).not.toContain("fake-download-grant");
+  });
+});

package/src/registry/targets/gitlab.ts

@@ -0,0 +1,223 @@
+/**
+ * GitLab's Terraform module registry as a module target (chant#4603).
+ *
+ * The one write is GitLab's documented upload
+ * (docs.gitlab.com/api/packages/terraform-modules/):
+ *
+ *   PUT /projects/:id/packages/terraform/modules/:name/:system/:version/file
+ *
+ * with the archive as the body. The token follows chant's forge target
+ * (core lifecycle/publish-forge.ts `forgeTokenEnv`): the variable the
+ * declaration names, else `GITLAB_TOKEN`, then `CI_JOB_TOKEN`. A job token
+ * goes in `JOB-TOKEN` and any other in `PRIVATE-TOKEN`. The API root is the
+ * declaration's, else `CI_API_V4_URL`, else gitlab.com's; the project is the
+ * declaration's (an id or a full path), else `CI_PROJECT_ID`.
+ *
+ * GitLab lists a version as soon as it is uploaded, so there is no staging
+ * step to hide it: `stage` uploads, and `reveal` reads the version back the
+ * way Terraform and OpenTofu do (discovery, versions, download) with the
+ * lexicon's registry reader, sending `TF_TOKEN_<host>` (chant#4563), else the
+ * upload token, which GitLab also takes as a bearer token on these reads.
+ * `held` downloads the version's archive and compares its content digest, so
+ * a version holding other content is refused and the same content comes back
+ * `present` with nothing sent.
+ *
+ * GitLab's module API has no call to deprecate a version, so a deprecation
+ * stays in the bucket catalog and GitLab shows none. The namespace a GitLab
+ * source names is the project's top-level group (`CI_PROJECT_ROOT_NAMESPACE`
+ * in CI): the declaration's `namespace`, else the context's.
+ */
+import { readCredential, type Credential } from "@intentius/chant/lifecycle/publish-credentials";
+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, fetchTarball, 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";
+
+/** How a GitLab module target is declared. Every field is optional in GitLab CI. */
+export interface GitlabModuleTargetOptions {
+  /** The project the module is uploaded to: its id or its full path. Default `CI_PROJECT_ID`. */
+  project?: string;
+  /** The API root, such as `https://gitlab.example.com/api/v4`. Default `CI_API_V4_URL`, else gitlab.com's. */
+  api?: string;
+  /** The variable the token is read from, in place of `GITLAB_TOKEN` then `CI_JOB_TOKEN`. */
+  tokenEnv?: string;
+  /** The namespace sources name: the project's top-level group. Default: the context's. */
+  namespace?: string;
+}
+
+export const GITLAB_DEFAULT_API = "https://gitlab.com/api/v4";
+
+/** The variables the upload token is read from, in order. */
+export const gitlabTokenEnv = (o: Pick<GitlabModuleTargetOptions, "tokenEnv">): string[] => (o.tokenEnv ? [o.tokenEnv] : ["GITLAB_TOKEN", "CI_JOB_TOKEN"]);
+
+/** The API root a target uploads to, without a trailing slash. */
+export const gitlabApi = (o: Pick<GitlabModuleTargetOptions, "api">, env: NodeJS.ProcessEnv): string => (o.api ?? env.CI_API_V4_URL ?? GITLAB_DEFAULT_API).replace(/\/+$/, "");
+
+/** The headers a GitLab token goes in: `JOB-TOKEN` for a CI job token, `PRIVATE-TOKEN` for any other. */
+export const gitlabAuthHeader = (token: Credential): Record<string, string> => (token.from === "CI_JOB_TOKEN" ? { "job-token": token.value } : { "private-token": token.value });
+
+/** The upload URL for one version. */
+export function gitlabUploadUrl(api: string, project: string, address: Pick<ModuleAddress, "name" | "system">, version: string): string {
+  const id = /^\d+$/.test(project) ? project : encodeURIComponent(project);
+  return `${api}/projects/${id}/packages/terraform/modules/${encodeURIComponent(address.name)}/${encodeURIComponent(address.system)}/${encodeURIComponent(version)}/file`;
+}
+
+/** A signed URL's query (GitLab's download link carries a token in it) cut from a message. */
+const withoutQueries = (text: string): string => text.replace(/(https?:\/\/[^\s?]+)\?[^\s)"']*/g, "$1?[query]");
+
+export function gitlabModuleTarget(options: GitlabModuleTargetOptions = {}, deps: ModuleTargetDeps = {}): ModulePublishTarget<"gitlab"> {
+  const fetch = deps.fetch ?? defaultPublishFetch;
+  const tokenEnv = gitlabTokenEnv(options);
+  const key = `gitlab:${createHash("sha256")
+    .update(JSON.stringify({ project: options.project ?? null, api: options.api ?? null, tokenEnv: options.tokenEnv ?? null, namespace: options.namespace ?? null }))
+    .digest("hex")
+    .slice(0, 16)}`;
+
+  const where = (env: NodeJS.ProcessEnv) => {
+    const api = gitlabApi(options, env);
+    let u: URL;
+    try {
+      u = new URL(api);
+    } catch {
+      throw new PublishTargetError("publish-config-invalid", `${api} is not a URL`, "Set the declaration's api, or CI_API_V4_URL, to the API root, such as https://gitlab.example.com/api/v4.");
+    }
+    return { api, host: u.host.toLowerCase(), scheme: (u.protocol === "http:" ? "http" : "https") as "http" | "https" };
+  };
+  const addressOf = (address: ModuleAddress): ModuleAddress => ({ ...address, namespace: options.namespace ?? address.namespace });
+  const sourceOf = (host: string, a: ModuleAddress) => `${host}/${a.namespace}/${a.name}/${a.system}`;
+
+  const uploadToken = (ctx: Pick<PublishContextBase, "env" | "redactor">): Credential | null => readCredential(ctx.env, tokenEnv, ctx.redactor);
+  const needToken = (ctx: Pick<PublishContextBase, "env" | "redactor">): Credential => {
+    const t = uploadToken(ctx);
+    if (!t) throw answerError(ctx, "publish-credentials-missing", `no GitLab token: set ${tokenEnv.join(" or ")}`, "In GitLab CI the job's CI_JOB_TOKEN can upload to its own project; elsewhere use a token with the api scope.");
+    return t;
+  };
+  const projectOf = (env: NodeJS.ProcessEnv): string => {
+    const p = options.project ?? env.CI_PROJECT_ID;
+    if (!p) throw new PublishTargetError("publish-config-invalid", "no GitLab project to upload to", "Name the project (its id or full path) in the declaration, or run in GitLab CI, which sets CI_PROJECT_ID.");
+    return p;
+  };
+
+  /** The reader's options: the CLIs' token for the host, else the upload token. */
+  const readOptions = (ctx: Pick<PublishContextBase, "env" | "redactor">): RegistryReadOptions & { host: string } => {
+    const { host, scheme } = where(ctx.env);
+    const cli = terraformCredential(host, { env: ctx.env });
+    const token = cli?.token ?? uploadToken(ctx)?.value;
+    ctx.redactor.add(token);
+    return { host, scheme, token: token ?? false, ...(deps.registryFetch ? { fetch: deps.registryFetch } : {}) };
+  };
+  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", withoutQueries(e.message));
+      throw e;
+    }
+  };
+
+  const versions = async (address: ModuleAddress, ctx: Pick<PublishContextBase, "env" | "redactor">): Promise<string[]> => {
+    const o = readOptions(ctx);
+    return read(ctx, () => registryVersions(sourceOf(o.host, addressOf(address)), o));
+  };
+  const held = async (address: ModuleAddress, version: string, ctx: Pick<PublishContextBase, "env" | "redactor">): Promise<HeldVersion | undefined> => {
+    if (!(await versions(address, ctx)).includes(version)) return undefined;
+    const o = readOptions(ctx);
+    const source = sourceOf(o.host, addressOf(address));
+    return read(ctx, async () => {
+      const location = await registryLocation(source, version, o);
+      return { content: contentDigest(await fetchTarball(location, o)) };
+    });
+  };
+
+  const item = (ctx: ModuleVersionContext, present?: boolean): PublishItem => {
+    const { host } = where(ctx.env);
+    const a = addressOf(ctx.address);
+    return { name: `${a.namespace}/${a.name}/${a.system} ${ctx.version}`, destination: sourceOf(host, a), digest: ctx.content, ...(present ? { present: true } : {}) };
+  };
+
+  return {
+    kind: "gitlab",
+    name: "GitLab module registry",
+    destination: gitlabApi(options, process.env),
+    credentialEnv: tokenEnv,
+    key,
+    versions,
+    held,
+
+    async plan(ctx) {
+      checkModuleVersion(ctx);
+      needToken(ctx);
+      projectOf(ctx.env);
+      return [item(ctx)];
+    },
+
+    async stage(ctx): Promise<StagedTarget> {
+      checkModuleVersion(ctx);
+      const token = needToken(ctx);
+      const project = projectOf(ctx.env);
+      const { api, host } = where(ctx.env);
+      const a = addressOf(ctx.address);
+      const source = sourceOf(host, a);
+      const staged = (present: boolean): StagedTarget => ({ target: "gitlab", destination: source, items: [item(ctx, present)], state: { project, 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 on GitLab with this content; nothing sent`);
+        return staged(true);
+      }
+
+      const url = gitlabUploadUrl(api, project, a, ctx.version);
+      let res: Awaited<ReturnType<typeof fetch>>;
+      try {
+        res = await fetch(url, { method: "PUT", headers: { ...gitlabAuthHeader(token), "content-type": "application/octet-stream" }, body: ctx.archive });
+      } 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 project ${project}`);
+        return staged(false);
+      }
+      if (/already exists/i.test(text)) {
+        // Another run uploaded it between the read and the upload: judge what it holds.
+        const now = await held(ctx.address, ctx.version, ctx);
+        if (now && now.content === ctx.content) return staged(true);
+        if (now) throw versionHeldError(source, ctx, now);
+      }
+      if (res.status === 401 || res.status === 403) {
+        throw answerError(
+          ctx,
+          "publish-credentials-refused",
+          `GitLab answered ${res.status} to the upload of ${source} ${ctx.version}: it refused the token in ${token.from}`,
+          token.from === "CI_JOB_TOKEN"
+            ? "A job token uploads only to its own project; name another project's token in the declaration's tokenEnv."
+            : `Give the token in ${token.from} the api scope and at least the Developer role on project ${project}.`,
+        );
+      }
+      throw answerError(ctx, "publish-upload-failed", `GitLab answered ${res.status} to the upload of ${source} ${ctx.version}: ${withoutQueries(text.slice(0, 300))}`);
+    },
+
+    async reveal(ctx, staged) {
+      const listed = await versions(ctx.address, ctx);
+      if (!listed.includes(ctx.version)) {
+        throw answerError(ctx, "publish-reveal-missing", `${staged.destination} lists no ${ctx.version} after the upload`, "Check the project's package registry; run the publish again to upload it.");
+      }
+      const o = readOptions(ctx);
+      await read(ctx, () => registryLocation(staged.destination, ctx.version, o));
+      return { target: staged.target, destination: staged.destination, items: staged.items };
+    },
+  };
+}

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

@@ -0,0 +1,230 @@
+// chant#4604: the HCP Terraform module target against the in-memory HCP fake. No HCP account and no
+// HCP call: every request goes to the fake, the clock is the test's, and no token value appears in a
+// log line, an error or a staged record.
+import { gzipSync } from "node:zlib";
+import { describe, expect, it } from "vitest";
+import { PublishTargetError } from "@intentius/chant/lifecycle/release-publish";
+import { createRedactor } from "@intentius/chant/lifecycle/publish-credentials";
+import { HCP_RATE_RETRIES, archiveContent, hcpModuleTarget, hcpTokenEnv, retryDelay, type HcpModuleTargetOptions, type ModuleVersionContext } from "../index";
+import { ARCHIVIST, createFakeHcp, type FakeHcpOptions } from "./fake-hcp";
+
+const ORG = "acme";
+const TOKEN = "team-token.atlasv1.0123456789abcdef";
+const NO_MANAGE = "team-token.atlasv1.readonly-000000";
+
+const fake = (over: Partial<FakeHcpOptions> = {}) => createFakeHcp({ organization: ORG, tokens: { [TOKEN]: { manageModules: true }, [NO_MANAGE]: { manageModules: false } }, ...over });
+const archiveOf = (text: string) => gzipSync(Buffer.from(`module tar: ${text}`));
+
+function clock() {
+  let t = 1_000_000;
+  const sleeps: number[] = [];
+  return { now: () => t, sleep: async (ms: number) => void (sleeps.push(ms), (t += ms)), sleeps };
+}
+
+function context(env: NodeJS.ProcessEnv, over: Partial<ModuleVersionContext> = {}): ModuleVersionContext & { lines: string[] } {
+  const archive = over.archive ?? archiveOf("vpc 1.2.0");
+  const redactor = createRedactor(env);
+  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: "ignored", name: "vpc", system: "aws" },
+    version: "1.2.0",
+    revision: "3f2a9c1d0b7e3f2a9c1d0b7e3f2a9c1d0b7e3f2a",
+    content: archiveContent(archive),
+    archive,
+    ...over,
+    lines,
+  };
+}
+
+function target(hcp: ReturnType<typeof fake>, c = clock(), opts: Partial<HcpModuleTargetOptions> = {}) {
+  return hcpModuleTarget({ organization: ORG, waitMs: 10_000, pollMs: 1000, ...opts }, { fetch: hcp.fetch, registryFetch: hcp.fetch, sleep: c.sleep, now: c.now });
+}
+
+const writes = (hcp: ReturnType<typeof fake>) => hcp.requests.filter((r) => r.method !== "GET").map((r) => `${r.method} ${r.url}`);
+
+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 API = "https://app.terraform.io/api/v2/organizations/acme/registry-modules";
+
+describe("HCP Terraform module target (chant#4604)", () => {
+  it("makes the three calls in order: create the module, create the version, upload the tarball", async () => {
+    const hcp = fake();
+    const ctx = context({ TFE_TOKEN: TOKEN });
+    const t = target(hcp);
+    expect(await t.plan(ctx)).toEqual([{ name: "acme/vpc/aws 1.2.0", destination: "app.terraform.io/acme/vpc/aws", digest: ctx.content }]);
+    const staged = await t.stage(ctx);
+    expect(writes(hcp)).toEqual([`POST ${API}`, `POST ${API}/private/acme/vpc/aws/versions`, `PUT https://${ARCHIVIST}/v1/object/obj1`]);
+
+    const [createModule, createVersion, upload] = hcp.requests.filter((r) => r.method !== "GET");
+    expect(JSON.parse(new TextDecoder().decode(createModule!.body))).toEqual({ data: { type: "registry-modules", attributes: { name: "vpc", provider: "aws", "registry-name": "private" } } });
+    expect(JSON.parse(new TextDecoder().decode(createVersion!.body))).toEqual({ data: { type: "registry-module-versions", attributes: { version: "1.2.0", "commit-sha": ctx.revision } } });
+    expect(createModule!.headers.authorization).toBe(`Bearer ${TOKEN}`);
+    expect(createModule!.headers["content-type"]).toBe("application/vnd.api+json");
+    expect(upload!.headers["content-type"]).toBe("application/octet-stream");
+    expect(upload!.headers.authorization).toBeUndefined();
+    expect(Buffer.from(upload!.body!)).toEqual(Buffer.from(ctx.archive));
+    // The module was read first, and created only because it was absent.
+    expect(hcp.requests[0]!.method).toBe("GET");
+    expect(hcp.requests[0]!.url).toBe(`${API}/private/acme/vpc/aws`);
+    expect(staged.items[0]!.present).toBeUndefined();
+    expect(JSON.stringify(staged)).not.toContain(TOKEN);
+
+    await t.reveal(ctx, staged);
+    expect(hcp.modules.get("vpc/aws")!.get("1.2.0")!.commitSha).toBe(ctx.revision);
+  });
+
+  it("does not create a module that is already there", async () => {
+    const hcp = fake();
+    hcp.seed("vpc", "aws");
+    await target(hcp).stage(context({ TFE_TOKEN: TOKEN }));
+    expect(writes(hcp)).toEqual([`POST ${API}/private/acme/vpc/aws/versions`, `PUT https://${ARCHIVIST}/v1/object/obj1`]);
+  });
+
+  it("comes back present and sends nothing for a version held with the same content", async () => {
+    const hcp = fake();
+    const ctx = context({ TFE_TOKEN: TOKEN });
+    hcp.seed("vpc", "aws", { version: "1.2.0", archive: ctx.archive });
+    const t = target(hcp);
+    expect(await t.held(ctx.address, "1.2.0", ctx)).toEqual({ content: ctx.content });
+    const staged = await t.stage(ctx);
+    expect(staged.items[0]!.present).toBe(true);
+    expect(writes(hcp)).toEqual([]);
+    expect(await t.versions(ctx.address, ctx)).toEqual(["1.2.0"]);
+  });
+
+  it("refuses a version held with other content, and sends nothing", async () => {
+    const hcp = fake();
+    hcp.seed("vpc", "aws", { version: "1.2.0", archive: archiveOf("other") });
+    const err = await errorOf(target(hcp).stage(context({ TFE_TOKEN: TOKEN })));
+    expect(err.code).toBe("publish-version-held");
+    expect(writes(hcp)).toEqual([]);
+  });
+
+  it("refuses a version an earlier run left pending, naming the fix", async () => {
+    const hcp = fake();
+    hcp.seed("vpc", "aws", { version: "1.2.0", archive: archiveOf("x"), status: "pending" });
+    hcp.modules.get("vpc/aws")!.get("1.2.0")!.archive = undefined;
+    const err = await errorOf(target(hcp).stage(context({ TFE_TOKEN: TOKEN })));
+    expect(err.code).toBe("publish-version-unfinished");
+    expect(err.fix).toContain("delete the version");
+  });
+
+  it("retries a 429 after Retry-After, then succeeds", async () => {
+    const hcp = fake();
+    const c = clock();
+    hcp.throttle(2, "3");
+    const ctx = context({ TFE_TOKEN: TOKEN });
+    await target(hcp, c).stage(ctx);
+    expect(c.sleeps).toEqual([3000, 3000]);
+    expect(writes(hcp)).toContain(`PUT https://${ARCHIVIST}/v1/object/obj1`);
+    expect(ctx.lines.filter((l) => l.includes("429"))).toHaveLength(2);
+  });
+
+  it("backs off, doubling, when a 429 has no Retry-After", async () => {
+    const hcp = fake();
+    const c = clock();
+    hcp.throttle(3);
+    await target(hcp, c).stage(context({ TFE_TOKEN: TOKEN }));
+    expect(c.sleeps).toEqual([1000, 2000, 4000]);
+    expect(retryDelay(null, 0, 0)).toBe(1000);
+    expect(retryDelay(new Date(5000).toUTCString(), 0, 2000)).toBe(3000);
+  });
+
+  it("stops with publish-rate-limited after the retry limit", async () => {
+    const hcp = fake();
+    const c = clock();
+    hcp.throttle(HCP_RATE_RETRIES + 1, "1");
+    const err = await errorOf(target(hcp, c).stage(context({ TFE_TOKEN: TOKEN })));
+    expect(err.code).toBe("publish-rate-limited");
+    expect(c.sleeps).toHaveLength(HCP_RATE_RETRIES);
+    expect(writes(hcp)).toEqual([]);
+  });
+
+  it("names both causes on a 404: the Manage modules permission and the entitlement", async () => {
+    for (const [hcp, env] of [
+      [fake(), { TFE_TOKEN: NO_MANAGE }],
+      [fake({ entitled: false }), { TFE_TOKEN: TOKEN }],
+    ] as const) {
+      const err = await errorOf(target(hcp).stage(context({ ...env })));
+      expect(err.code).toBe("publish-not-found");
+      expect(err.message).toContain("Manage modules");
+      expect(err.message).toContain("entitlement");
+      expect(err.message).not.toContain(env.TFE_TOKEN);
+    }
+  });
+
+  it("names the variable on a refused token, never its value", async () => {
+    const hcp = fake();
+    const err = await errorOf(target(hcp).stage(context({ TFE_TOKEN: "unknown-token-value-1234" })));
+    expect(err.code).toBe("publish-credentials-refused");
+    expect(err.message).toContain("TFE_TOKEN");
+    expect(`${err.message} ${err.fix}`).not.toContain("unknown-token-value-1234");
+  });
+
+  it("takes TF_TOKEN_<host> when TFE_TOKEN is not set, and refuses with neither", async () => {
+    const hcp = fake();
+    await target(hcp).stage(context({ TF_TOKEN_app_terraform_io: TOKEN }));
+    expect(hcp.requests[0]!.headers.authorization).toBe(`Bearer ${TOKEN}`);
+    const none = await errorOf(target(fake()).plan(context({})));
+    expect(none.code).toBe("publish-credentials-missing");
+    expect(none.message).toContain("TFE_TOKEN or TF_TOKEN_app_terraform_io");
+    expect(hcpTokenEnv({ host: "tfe.example.com" })).toEqual(["TFE_TOKEN", "TF_TOKEN_tfe_example_com"]);
+  });
+
+  it("talks to a Terraform Enterprise host when one is given", async () => {
+    const hcp = fake({ host: "tfe.example.com" });
+    await target(hcp, clock(), { host: "tfe.example.com" }).stage(context({ TFE_TOKEN: TOKEN }));
+    expect(hcp.requests[0]!.url).toBe("https://tfe.example.com/api/v2/organizations/acme/registry-modules/private/acme/vpc/aws");
+  });
+
+  it("reveals once polling sees the version's status turn ok", async () => {
+    const hcp = fake({ parseAfterReads: 3 });
+    const c = clock();
+    const ctx = context({ TFE_TOKEN: TOKEN });
+    const t = target(hcp, c);
+    const published = await t.reveal(ctx, await t.stage(ctx));
+    expect(published.destination).toBe("app.terraform.io/acme/vpc/aws");
+    expect(hcp.modules.get("vpc/aws")!.get("1.2.0")!.status).toBe("ok");
+    expect(c.sleeps.every((ms) => ms === 1000)).toBe(true);
+    expect(c.sleeps.length).toBeGreaterThan(0);
+    expect(ctx.lines.some((l) => l.includes("still"))).toBe(false);
+  });
+
+  it("reports a version still parsing past the wait, without failing", async () => {
+    const hcp = fake({ parseAfterReads: Infinity });
+    const c = clock();
+    const ctx = context({ TFE_TOKEN: TOKEN });
+    const t = target(hcp, c);
+    const published = await t.reveal(ctx, await t.stage(ctx));
+    expect(published.items).toHaveLength(1);
+    expect(ctx.lines.some((l) => l.includes("is still pending"))).toBe(true);
+    expect(c.sleeps.reduce((a, b) => a + b, 0)).toBeGreaterThanOrEqual(10_000);
+  });
+
+  it("masks the token in every log line and error", async () => {
+    const hcp = fake({ parseAfterReads: Infinity });
+    const c = clock();
+    hcp.throttle(1, "1");
+    const ctx = context({ TFE_TOKEN: TOKEN });
+    const t = target(hcp, c);
+    await t.reveal(ctx, await t.stage(ctx));
+    const other = context(ctx.env, { version: "1.2.0", archive: archiveOf("changed"), content: archiveContent(archiveOf("changed")) });
+    const err = await errorOf(t.stage(other));
+    const all = [...ctx.lines, ...other.lines, err.message, err.fix ?? ""].join("\n");
+    expect(all).not.toContain(TOKEN);
+    expect(ctx.redactor.redact(`Authorization: Bearer ${TOKEN}`)).not.toContain(TOKEN);
+  });
+});