@intentius/chant-lexicon-terraform 0.124.52 → 0.124.55

package/dist/registry/targets/hosted.js

@@ -0,0 +1,74 @@
+/**
+ * What the Artifactory and Nexus module targets share (chant#4605): basic
+ * `user:token` write credentials (terragucci#1299 ruling B), a binary GET of
+ * an uploaded archive, and the wait for a version to be listed after its
+ * upload, since both hosts index an upload after the PUT answers.
+ */
+import { readCredential } from "@intentius/chant/lifecycle/publish-credentials";
+import { answerError, contentDigest } from "./module-target.js";
+import { heldContentOf } from "./zip.js";
+/** The basic credential the environment holds, added to the redactor, or null when either half is missing. */
+export function readBasicCredential(ctx, names) {
+    const token = readCredential(ctx.env, [names.tokenEnv], ctx.redactor);
+    const user = names.user ?? ctx.env[names.userEnv];
+    if (!token || !user)
+        return null;
+    const encoded = Buffer.from(`${user}:${token.value}`, "utf-8").toString("base64");
+    ctx.redactor.add(encoded);
+    return { user, token, header: `Basic ${encoded}` };
+}
+/** The basic credential, or the refusal naming both variables. */
+export function needBasicCredential(ctx, names, host, fix) {
+    const c = readBasicCredential(ctx, names);
+    if (c)
+        return c;
+    const missing = [...(ctx.env[names.tokenEnv] ? [] : [names.tokenEnv]), ...(names.user || ctx.env[names.userEnv] ? [] : [names.userEnv])];
+    throw answerError(ctx, "publish-credentials-missing", `no ${host} credentials: set ${missing.join(" and ")}`, fix);
+}
+/** The global fetch, in the reader's shape. */
+export const defaultRegistryFetch = (url, init) => fetch(url, init);
+/** A GET of bytes, with its status. A network failure is a `publish-read-failed`. */
+export async function getBytes(ctx, fetchFn, url, authorization) {
+    let res;
+    try {
+        res = await fetchFn(url, { method: "GET", redirect: "follow", ...(authorization ? { headers: { Authorization: authorization } } : {}) });
+    }
+    catch (e) {
+        throw answerError(ctx, "publish-read-failed", `GET ${url}: ${e.message}`);
+    }
+    return { status: res.status, bytes: new Uint8Array(await res.arrayBuffer()) };
+}
+export const HOSTED_LIST_WAIT_MS = 30000;
+export const HOSTED_POLL_MS = 2000;
+/** Reads `list` until it holds `version` or the wait is over; true when it was listed. */
+export async function waitListed(list, version, wait) {
+    const start = wait.now();
+    for (;;) {
+        if ((await list()).includes(version))
+            return true;
+        if (wait.now() - start >= wait.waitMs)
+            return false;
+        await wait.sleep(wait.pollMs);
+    }
+}
+/** The refusal for a 401 or 403 on an upload, naming the variables, never their values. */
+export function writeRefused(ctx, host, status, what, credential, names, fix) {
+    const userFrom = names.user ? "the declaration's user" : names.userEnv;
+    return answerError(ctx, "publish-credentials-refused", `${host} answered ${status} to the upload of ${what}: it refused the user in ${userFrom} with the token in ${credential.token.from}`, fix);
+}
+/**
+ * The content of the archive a download location holds, as the CLIs would
+ * fetch it: the registry's credential goes along only to the registry's own
+ * host and only when the location has no query (a signed URL carries its own
+ * grant). Refuses a location that answers other than 2xx.
+ */
+export async function locationContent(ctx, fetchFn, location, registryHost, authorization) {
+    const u = new URL(location);
+    const auth = !u.search && u.host.toLowerCase() === registryHost.toLowerCase() ? authorization : undefined;
+    const { status, bytes } = await getBytes(ctx, fetchFn, location, auth);
+    if (status < 200 || status > 299)
+        throw answerError(ctx, "publish-read-failed", `${location.split("?")[0]} answered ${status} to the download a consumer would make`);
+    return heldContentOf(bytes, contentDigest);
+}
+/** The refusal for a download that holds other content than the version staged. */
+export const revealMismatch = (ctx, where, version, got, want) => answerError(ctx, "publish-reveal-mismatch", `${where} ${version} downloads as ${got}, and this publish staged ${want}`, "Check which archive the repository holds for the version; a published version never changes.");

package/dist/registry/targets/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Module targets: publishing a module version to a hosted registry on chant
+ * core's publish-target contract (chant#4602): GitLab (chant#4603), HCP
+ * Terraform or Terraform Enterprise (chant#4604), and Artifactory and Nexus
+ * (chant#4605), which take the zip of the attested archive (./zip). The
+ * fakes the tests drive them with are at `registry/targets/fake-<host>`,
+ * with `fake-http` holding a module tarball builder, outside this index, so
+ * a product's tests can reach them without shipping them in its own code
+ * paths.
+ */
+export * from "./module-target.js";
+export * from "./gitlab.js";
+export * from "./hcp.js";
+export * from "./zip.js";
+export * from "./hosted.js";
+export * from "./artifactory.js";
+export * from "./nexus.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/registry/targets/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/registry/targets/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,OAAO,CAAC;AACtB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC"}

package/dist/registry/targets/index.js

@@ -0,0 +1,17 @@
+/**
+ * Module targets: publishing a module version to a hosted registry on chant
+ * core's publish-target contract (chant#4602): GitLab (chant#4603), HCP
+ * Terraform or Terraform Enterprise (chant#4604), and Artifactory and Nexus
+ * (chant#4605), which take the zip of the attested archive (./zip). The
+ * fakes the tests drive them with are at `registry/targets/fake-<host>`,
+ * with `fake-http` holding a module tarball builder, outside this index, so
+ * a product's tests can reach them without shipping them in its own code
+ * paths.
+ */
+export * from "./module-target.js";
+export * from "./gitlab.js";
+export * from "./hcp.js";
+export * from "./zip.js";
+export * from "./hosted.js";
+export * from "./artifactory.js";
+export * from "./nexus.js";

package/dist/registry/targets/module-target.d.ts

@@ -0,0 +1,68 @@
+import { PublishTargetError, type PublishContextBase, type PublishDeps, type PublishFetch, type PublishTarget } from "@intentius/chant/lifecycle/release-publish";
+import type { RegistryFetch } from "../reader.js";
+/** A module in a hosted registry, without the host: `<namespace>/<name>/<system>`. */
+export interface ModuleAddress {
+    namespace: string;
+    name: string;
+    system: string;
+}
+/** What a module target is given to plan and to publish: one version of one module. */
+export interface ModuleVersionContext extends PublishContextBase {
+    /** The module. A host that fixes the namespace itself (GitLab's top-level group, HCP's organization) uses its own. */
+    address: ModuleAddress;
+    /** The version, semver without a leading `v`. */
+    version: string;
+    /** The gzip tarball the bucket registry serves and the attestation signs, with the module at its root. */
+    archive: Uint8Array;
+    /** The commit the version was built from. */
+    revision: string;
+    /** The content digest, `sha256:<hex>` of the uncompressed archive, as the bucket registry's release.json keeps it. */
+    content: string;
+}
+/** The content a version a host holds carries. */
+export interface HeldVersion {
+    /** `sha256:<hex>` of its uncompressed archive. */
+    content: string;
+    /** The revision the host keeps for it, when it keeps one. */
+    revision?: string;
+    /**
+     * The host's status for a version it has not finished taking in, such as
+     * HCP's `pending` before its archive is parsed (chant#4604). Absent for a
+     * version consumers can install; `content` is empty while it is set.
+     */
+    status?: string;
+}
+/** The reads a module target answers beside the contract. They read, and change nothing. */
+export interface ModuleTargetReads {
+    /** Every version the host lists for the module, oldest first; none when it has no such module. */
+    versions(address: ModuleAddress, ctx: Pick<PublishContextBase, "env" | "redactor">): Promise<string[]>;
+    /** The content of a version the host holds, or undefined when it holds no such version. */
+    held(address: ModuleAddress, version: string, ctx: Pick<PublishContextBase, "env" | "redactor">): Promise<HeldVersion | undefined>;
+}
+/** A target that publishes a module version: the publish-target contract over {@link ModuleVersionContext}, plus its reads. */
+export type ModulePublishTarget<K extends string = string> = PublishTarget<ModuleVersionContext, K> & ModuleTargetReads;
+/** What a module target's factory is given: core's publish deps, plus the fetch the registry reader uses. */
+export interface ModuleTargetDeps extends PublishDeps {
+    /**
+     * The fetch the registry-protocol reads go through. Default: the global
+     * `fetch`. A test passes its fake for both this and `fetch`.
+     */
+    registryFetch?: RegistryFetch;
+}
+/** `sha256:<hex>` of the bytes. */
+export declare const contentDigest: (bytes: Uint8Array) => string;
+/** The content digest of a gzip archive: the digest of its uncompressed bytes. */
+export declare function archiveContent(archive: Uint8Array): string;
+/**
+ * The checks every module target's `plan` makes before it reads its host: the
+ * address and version are ones a registry can carry, and the archive holds
+ * the content the context names.
+ */
+export declare function checkModuleVersion(ctx: ModuleVersionContext): void;
+/** The refusal for a version a host holds with other content. */
+export declare function versionHeldError(where: string, ctx: ModuleVersionContext, held: HeldVersion): PublishTargetError;
+/** The error message for a host's answer, with every credential masked. */
+export declare const answerError: (ctx: Pick<PublishContextBase, "redactor">, code: string, message: string, fix?: string) => PublishTargetError;
+/** The global fetch, in the contract's shape. */
+export declare const defaultPublishFetch: PublishFetch;
+//# sourceMappingURL=module-target.d.ts.map

package/dist/registry/targets/module-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-target.d.ts","sourceRoot":"","sources":["../../../src/registry/targets/module-target.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,4CAA4C,CAAC;AAGlK,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,sFAAsF;AACtF,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,uFAAuF;AACvF,MAAM,WAAW,oBAAqB,SAAQ,kBAAkB;IAC9D,sHAAsH;IACtH,OAAO,EAAE,aAAa,CAAC;IACvB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,0GAA0G;IAC1G,OAAO,EAAE,UAAU,CAAC;IACpB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,sHAAsH;IACtH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,kDAAkD;AAClD,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IAChC,kGAAkG;IAClG,QAAQ,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,EAAE,IAAI,CAAC,kBAAkB,EAAE,KAAK,GAAG,UAAU,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACvG,2FAA2F;IAC3F,IAAI,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,kBAAkB,EAAE,KAAK,GAAG,UAAU,CAAC,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;CACpI;AAED,+HAA+H;AAC/H,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI,aAAa,CAAC,oBAAoB,EAAE,CAAC,CAAC,GAAG,iBAAiB,CAAC;AAExH,6GAA6G;AAC7G,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD;;;OAGG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,mCAAmC;AACnC,eAAO,MAAM,aAAa,UAAW,UAAU,KAAG,MAAsE,CAAC;AAEzH,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAM1D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,oBAAoB,GAAG,IAAI,CAelE;AAED,iEAAiE;AACjE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,oBAAoB,EAAE,IAAI,EAAE,WAAW,GAAG,kBAAkB,CAMhH;AAED,2EAA2E;AAC3E,eAAO,MAAM,WAAW,QAAS,IAAI,CAAC,kBAAkB,EAAE,UAAU,CAAC,QAAQ,MAAM,WAAW,MAAM,QAAQ,MAAM,KAAG,kBACC,CAAC;AAEvH,iDAAiD;AACjD,eAAO,MAAM,mBAAmB,EAAE,YAA6D,CAAC"}

package/dist/registry/targets/module-target.js

@@ -0,0 +1,63 @@
+/**
+ * Publishing a module version to a hosted module registry (chant#4603,
+ * terragucci#1290 bundle C). A module target is chant core's publish-target
+ * contract (`PublishTarget` in core's lifecycle/release-publish.ts, chant#4047)
+ * over a module-version context in place of a cut release (chant#4602): the
+ * same `plan`, `stage` and `reveal`, the same `PublishTargetError`, the
+ * injected `fetch`, `sleep` and `now`, and core's credential reading and
+ * masking. Two reads sit beside the contract: `versions`, the versions the
+ * host lists, and `held`, the content a version the host holds carries, so a
+ * product's publish can tell a version that is already out from one holding
+ * other content.
+ *
+ * Every target uploads the archive the bucket registry serves and the
+ * attestation signs, unchanged (terragucci#1290 ruling B), so one digest
+ * holds across all of them. A host that renders a README shows the module's
+ * own.
+ *
+ * Products (terragucci's `modules.publish`) make the targets and hold the
+ * words; the protocol and the host calls live here.
+ */
+import { gunzipSync } from "node:zlib";
+import { createHash } from "node:crypto";
+import { PublishTargetError } from "@intentius/chant/lifecycle/release-publish";
+import { REGISTRY_NAME, REGISTRY_SYSTEM } from "../address.js";
+import { parseSemver } from "../semver.js";
+/** `sha256:<hex>` of the bytes. */
+export const contentDigest = (bytes) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+/** The content digest of a gzip archive: the digest of its uncompressed bytes. */
+export function archiveContent(archive) {
+    try {
+        return contentDigest(gunzipSync(archive));
+    }
+    catch {
+        throw new PublishTargetError("publish-archive-invalid", "the module archive is not a gzip tarball", "Publish the .tar.gz the bucket registry serves.");
+    }
+}
+/**
+ * The checks every module target's `plan` makes before it reads its host: the
+ * address and version are ones a registry can carry, and the archive holds
+ * the content the context names.
+ */
+export function checkModuleVersion(ctx) {
+    const { namespace, name, system } = ctx.address;
+    if (!REGISTRY_NAME.test(namespace) || !REGISTRY_NAME.test(name)) {
+        throw new PublishTargetError("publish-config-invalid", `${namespace}/${name}: a registry namespace and module name are letters, digits, - and _`);
+    }
+    if (!REGISTRY_SYSTEM.test(system))
+        throw new PublishTargetError("publish-config-invalid", `${system}: a registry module's system is lower-case letters and digits`);
+    if (!parseSemver(ctx.version))
+        throw new PublishTargetError("publish-config-invalid", `${ctx.version} is not a semver version`);
+    const got = archiveContent(ctx.archive);
+    if (got !== ctx.content) {
+        throw new PublishTargetError("publish-artifact-digest-mismatch", `the archive for ${namespace}/${name}/${system} ${ctx.version} holds ${got}, and the release names ${ctx.content}`, "Publish the archive the release was built with.");
+    }
+}
+/** The refusal for a version a host holds with other content. */
+export function versionHeldError(where, ctx, held) {
+    return new PublishTargetError("publish-version-held", `${where} already holds ${ctx.version} with content ${held.content}, and this publish has ${ctx.content}`, "A published version never changes: raise the version, or check why the module's content moved.");
+}
+/** The error message for a host's answer, with every credential masked. */
+export const answerError = (ctx, code, message, fix) => new PublishTargetError(code, ctx.redactor.redact(message), fix === undefined ? undefined : ctx.redactor.redact(fix));
+/** The global fetch, in the contract's shape. */
+export const defaultPublishFetch = (url, init) => fetch(url, init);

package/dist/registry/targets/nexus.d.ts

@@ -0,0 +1,43 @@
+import { type ModuleAddress, type ModulePublishTarget, type ModuleTargetDeps } from "./module-target.js";
+/** 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 declare const NEXUS_TOKEN_ENV = "NEXUS_TOKEN";
+export declare const NEXUS_USER_ENV = "NEXUS_USER";
+/** The first Nexus release with hosted Terraform repositories. */
+export declare 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 declare const NEXUS_BEARER_FLOOR = "3.95.0";
+/** The Nexus base, without a trailing slash. */
+export declare function nexusBase(url: string): string;
+/** The repository's modules.v1 URL, ending in `/`. */
+export declare const nexusModulesUrl: (base: string, repo: string) => string;
+/** The upload path of one version's zip. */
+export declare function nexusUploadUrl(base: string, repo: string, a: ModuleAddress, version: string): string;
+/** The label of the consumers' `host` block. */
+export declare function nexusHostLabel(o: Pick<NexusModuleTargetOptions, "repo" | "host">): string;
+/** The source consumers write for a module in the repository: `<host label>/<namespace>/<name>/<system>`. */
+export declare const nexusSource: (label: string, a: ModuleAddress) => string;
+/** The CLI configuration block a consumer adds so its sources reach the repository. */
+export declare function nexusHostBlock(o: Pick<NexusModuleTargetOptions, "url" | "repo" | "host">): string;
+export declare function nexusModuleTarget(options: NexusModuleTargetOptions, deps?: ModuleTargetDeps): ModulePublishTarget<"nexus">;
+//# sourceMappingURL=nexus.d.ts.map

package/dist/registry/targets/nexus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nexus.d.ts","sourceRoot":"","sources":["../../../src/registry/targets/nexus.ts"],"names":[],"mappings":"AA+CA,OAAO,EAOL,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EAEtB,MAAM,iBAAiB,CAAC;AAiBzB,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8GAA8G;IAC9G,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6GAA6G;IAC7G,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAC7C,eAAO,MAAM,cAAc,eAAe,CAAC;AAC3C,kEAAkE;AAClE,eAAO,MAAM,kBAAkB,WAAW,CAAC;AAC3C,6GAA6G;AAC7G,eAAO,MAAM,kBAAkB,WAAW,CAAC;AAI3C,gDAAgD;AAChD,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO7C;AAED,sDAAsD;AACtD,eAAO,MAAM,eAAe,SAAU,MAAM,QAAQ,MAAM,KAAG,MAAsE,CAAC;AAEpI,4CAA4C;AAC5C,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGpG;AAED,gDAAgD;AAChD,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,CAAC,wBAAwB,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,CAMzF;AAED,6GAA6G;AAC7G,eAAO,MAAM,WAAW,UAAW,MAAM,KAAK,aAAa,KAAG,MAAyD,CAAC;AAExH,uFAAuF;AACvF,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,CAAC,wBAAwB,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,CAEjG;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,EAAE,IAAI,GAAE,gBAAqB,GAAG,mBAAmB,CAAC,OAAO,CAAC,CA0K9H"}

package/dist/registry/targets/nexus.js

@@ -0,0 +1,250 @@
+/**
+ * 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 } from "@intentius/chant/lifecycle/release-publish";
+import { terraformCredential } from "@intentius/chant/terraform/credentials";
+import { createHash } from "node:crypto";
+import { RegistryError, registryLocation, registryVersions } from "../reader.js";
+import { answerError, checkModuleVersion, contentDigest, defaultPublishFetch, versionHeldError, } from "./module-target.js";
+import { HOSTED_LIST_WAIT_MS, HOSTED_POLL_MS, defaultRegistryFetch, getBytes, locationContent, needBasicCredential, readBasicCredential, revealMismatch, waitListed, writeRefused, } from "./hosted.js";
+import { heldContentOf, moduleZip } from "./zip.js";
+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) {
+    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, repo) => `${base}/repository/${encodeURIComponent(repo)}/v1/modules/`;
+/** The upload path of one version's zip. */
+export function nexusUploadUrl(base, repo, a, version) {
+    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) {
+    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, a) => `${label}/${a.namespace}/${a.name}/${a.system}`;
+/** The CLI configuration block a consumer adds so its sources reach the repository. */
+export function nexusHostBlock(o) {
+    return `host "${nexusHostLabel(o)}" {\n  services = {\n    "modules.v1" = "${nexusModulesUrl(nexusBase(o.url), o.repo)}"\n  }\n}\n`;
+}
+export function nexusModuleTarget(options, deps = {}) {
+    const put = deps.fetch ?? defaultPublishFetch;
+    const get = deps.registryFetch ?? defaultRegistryFetch;
+    const names = { 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) => new Promise((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) => 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();
+    const issuedToken = async (ctx, basic) => {
+        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 = null;
+        if (status >= 200 && status <= 299) {
+            const text = Buffer.from(bytes).toString("utf-8").trim();
+            try {
+                const doc = JSON.parse(text);
+                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) => {
+        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) => {
+        const { label, modules } = where();
+        const authorization = await readAuth(ctx);
+        return { services: { [label]: modules }, token: false, fetch: get, ...(authorization ? { authorization } : {}) };
+    };
+    const read = async (ctx, run) => {
+        try {
+            return await run();
+        }
+        catch (e) {
+            if (e instanceof RegistryError)
+                throw answerError(ctx, "publish-read-failed", e.message);
+            throw e;
+        }
+    };
+    const versions = async (address, ctx) => {
+        const o = await readOptions(ctx);
+        return read(ctx, () => registryVersions(nexusSource(where().label, address), o));
+    };
+    const held = async (address, version, ctx) => {
+        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, present) => {
+        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) {
+            checkModuleVersion(ctx);
+            const credential = needCredential(ctx);
+            const { base, label } = where();
+            const source = nexusSource(label, ctx.address);
+            const staged = (present) => ({ 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;
+            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.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/dist/registry/targets/zip.d.ts

@@ -0,0 +1,55 @@
+/** One entry of a module tarball. */
+export interface ModuleArchiveEntry {
+    path: string;
+    type: "file" | "dir";
+    mode: number;
+    /** Seconds since the epoch. */
+    mtime: number;
+    data: Buffer;
+}
+/**
+ * The entries of a module's gzip tarball (ustar, pax and GNU long names), with
+ * `./` cut from each path. A link or a device in the archive is refused: a
+ * zip of the module could not carry it as the tarball does.
+ */
+export declare function moduleArchiveEntries(archive: Uint8Array): ModuleArchiveEntry[];
+/** The CRC-32 a zip entry carries. */
+export declare function crc32(data: Uint8Array): number;
+/** The archive comment that names the attested archive a zip was made from. */
+export declare const ZIP_COMMENT_PREFIX = "chant-module";
+export declare const moduleZipComment: (content: string, revision?: string) => string;
+/** The content and revision a zip's archive comment names, when it is one {@link moduleZipComment} wrote. */
+export declare function readModuleZipComment(comment: string): {
+    content: string;
+    revision?: string;
+} | undefined;
+/** A zip of the given entries, with `comment` as its archive comment. Files are deflated. */
+export declare function zipOf(entries: readonly ModuleArchiveEntry[], comment?: string): Buffer;
+/**
+ * The zip a hosted target uploads for an attested archive: its entries,
+ * repacked, with the content digest and revision in the archive comment.
+ */
+export declare function moduleZip(archive: Uint8Array, content: string, revision?: string): Buffer;
+/** A zip read back: its archive comment and its entries' paths, modes and bytes. */
+export interface ReadZip {
+    comment: string;
+    entries: {
+        path: string;
+        dir: boolean;
+        mode: number;
+        data: Buffer;
+    }[];
+}
+/** Reads a zip's central directory and entries. Throws on bytes that are not a zip. */
+export declare function readZip(bytes: Uint8Array): ReadZip;
+/**
+ * The content a module archive a host gave back carries, as `held` reports
+ * it: the attested digest a chant zip's comment names; for a gzip tarball,
+ * the digest of its uncompressed bytes, as the bucket registry keeps it; for
+ * any other bytes, their own digest.
+ */
+export declare function heldContentOf(bytes: Uint8Array, digest: (b: Uint8Array) => string): {
+    content: string;
+    revision?: string;
+};
+//# sourceMappingURL=zip.d.ts.map

package/dist/registry/targets/zip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zip.d.ts","sourceRoot":"","sources":["../../../src/registry/targets/zip.ts"],"names":[],"mappings":"AAqBA,qCAAqC;AACrC,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AA2BD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,UAAU,GAAG,kBAAkB,EAAE,CAwC9E;AAYD,sCAAsC;AACtC,wBAAgB,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAI9C;AAWD,+EAA+E;AAC/E,eAAO,MAAM,kBAAkB,iBAAiB,CAAC;AAEjD,eAAO,MAAM,gBAAgB,YAAa,MAAM,aAAa,MAAM,KAAG,MAA8F,CAAC;AAErK,6GAA6G;AAC7G,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAMxG;AAED,6FAA6F;AAC7F,wBAAgB,KAAK,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,EAAE,OAAO,SAAK,GAAG,MAAM,CA+DlF;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzF;AAED,oFAAoF;AACpF,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACvE;AAED,uFAAuF;AACvF,wBAAgB,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAmClD;AAKD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAgB1H"}