@intentius/chant 0.124.27 → 0.124.29

package/src/lifecycle/mixed-environment.ts

@@ -0,0 +1,204 @@
+/**
+ * Whether an environment runs a mix of releases, and the lines that settle
+ * it (#4035). Derived when read, from the environment's release ledger and
+ * its deploy outcomes (./deploy-outcome.ts); nothing here is written.
+ *
+ * Two things make an environment mixed:
+ *
+ * - a component is unsettled: the newest promote, rollback or redeploy that
+ *   named it left it `failed` or `gated`, and the release ledger has no
+ *   record of it newer than that run, so what it runs is not known;
+ * - the latest records of its components name more than one release, a
+ *   record of no release counting as one value, and at least one names a
+ *   release.
+ *
+ * The ledger already says per component what deployed, and with which
+ * release, so the second needs no record of its own. Only the first needs
+ * the outcome: a failed deploy writes no release record, by design, so the
+ * ledger alone can't tell a component that failed partway from one that was
+ * never touched.
+ */
+
+import type { ReleaseRecord } from "./release-ledger";
+import type { DeployOutcome } from "./deploy-outcome";
+
+/** One component of a mixed environment. */
+export interface MixedComponent {
+  component: string;
+  /** The digest the release ledger records the component running, or null when it has no record in the environment. */
+  digest: string | null;
+  /** The release that record names, or null. */
+  releaseDigest: string | null;
+  releaseLabel: string | null;
+  /** `settled` when the ledger's record is what it runs; `failed` or `gated` when the newest run that named it left it so. */
+  state: "settled" | "failed" | "gated";
+  /** For an unsettled component, the run that left it so and what that run was deploying. Null when settled. */
+  attempt: {
+    verb: DeployOutcome["verb"];
+    runId: string;
+    timestamp: string;
+    digest: string;
+    releaseDigest: string | null;
+    releaseLabel: string | null;
+  } | null;
+}
+
+export interface MixedEnvironment {
+  /** Every component the ledger records or a run left unsettled, sorted by name. */
+  components: MixedComponent[];
+  /** `chant components redeploy <env> --component <c>` for each unsettled component the ledger records, which puts its recorded release back. */
+  redeploy: string[];
+  /** `chant components rollback <env> --release <label|digest>`, naming the release to go back to, or null when there is none to name. */
+  rollback: string | null;
+}
+
+/** What a reader knows about a release a rollback could go back to. */
+export interface ReleaseCheck {
+  /** Its release file can still be read, so its templates can be deployed. */
+  kept: boolean;
+  /** Its commit is revoked (#4033), so it is refused. */
+  revoked: boolean;
+}
+
+function latest(records: readonly ReleaseRecord[]): Map<string, ReleaseRecord> {
+  const out = new Map<string, ReleaseRecord>();
+  for (const r of records) {
+    const current = out.get(r.component);
+    if (!current || r.timestamp >= current.timestamp) out.set(r.component, r);
+  }
+  return out;
+}
+
+/**
+ * The components a run left unsettled: for each, the newest outcome naming it
+ * `failed` or `gated` that no release record of it is newer than.
+ */
+export function unsettledComponents(
+  records: readonly ReleaseRecord[],
+  outcomes: readonly DeployOutcome[],
+): Map<string, { outcome: DeployOutcome; state: "failed" | "gated"; digest: string; releaseDigest: string | null }> {
+  const newest = new Map<string, { outcome: DeployOutcome; state: "failed" | "gated"; digest: string; releaseDigest: string | null }>();
+  for (const outcome of outcomes) {
+    for (const c of outcome.components) {
+      if (c.outcome !== "failed" && c.outcome !== "gated") continue;
+      const seen = newest.get(c.component);
+      if (!seen || outcome.timestamp >= seen.outcome.timestamp) {
+        newest.set(c.component, { outcome, state: c.outcome, digest: c.digest, releaseDigest: c.releaseDigest });
+      }
+    }
+  }
+  const recorded = latest(records);
+  for (const [component, u] of newest) {
+    const r = recorded.get(component);
+    if (r && r.timestamp > u.outcome.timestamp) newest.delete(component);
+  }
+  return newest;
+}
+
+/**
+ * The newest release the environment's ledger names that a rollback can go
+ * back to: not in `exclude`, still kept, and not revoked. With `before`, only
+ * records older than that time count. Null when there is none.
+ */
+export async function rollbackTarget(input: {
+  records: readonly ReleaseRecord[];
+  exclude: ReadonlySet<string>;
+  before?: string;
+  check: (releaseDigest: string) => Promise<ReleaseCheck>;
+}): Promise<string | null> {
+  const ordered = input.records
+    .map((r, i) => ({ r, i }))
+    .filter(({ r }) => r.releaseDigest !== undefined && (input.before === undefined || r.timestamp < input.before))
+    .sort((a, b) => (a.r.timestamp === b.r.timestamp ? b.i - a.i : a.r.timestamp < b.r.timestamp ? 1 : -1));
+  const seen = new Set<string>();
+  for (const { r } of ordered) {
+    const digest = r.releaseDigest!;
+    if (seen.has(digest) || input.exclude.has(digest)) continue;
+    seen.add(digest);
+    const check = await input.check(digest);
+    if (check.kept && !check.revoked) return digest;
+  }
+  return null;
+}
+
+/** The line that rolls `env` back to a release, by its label when it has one. */
+export function releaseRollbackLine(env: string, releaseDigest: string, label: string | null | undefined): string {
+  return `chant components rollback ${env} --release ${label ?? releaseDigest}`;
+}
+
+/** The line that redeploys one component's recorded release in `env`. */
+export function redeployLine(env: string, component: string): string {
+  return `chant components redeploy ${env} --component ${component}`;
+}
+
+/**
+ * The environment's mixed state, or null when it runs one release (or no
+ * release at all) and no component is unsettled.
+ */
+export async function mixedEnvironment(input: {
+  env: string;
+  records: readonly ReleaseRecord[];
+  outcomes: readonly DeployOutcome[];
+  /** A release's label, or undefined. */
+  label: (releaseDigest: string) => Promise<string | undefined>;
+  check: (releaseDigest: string) => Promise<ReleaseCheck>;
+}): Promise<MixedEnvironment | null> {
+  const { env, records } = input;
+  const recorded = latest(records);
+  const unsettled = unsettledComponents(records, input.outcomes);
+  const releases = new Set([...recorded.values()].map((r) => r.releaseDigest ?? null));
+  const divergent = releases.size > 1 && [...releases].some((d) => d !== null);
+  if (unsettled.size === 0 && !divergent) return null;
+
+  const labelOf = async (digest: string | null | undefined): Promise<string | null> => (digest ? ((await input.label(digest)) ?? null) : null);
+  const names = [...new Set([...recorded.keys(), ...unsettled.keys()])].sort();
+  const components: MixedComponent[] = [];
+  for (const component of names) {
+    const r = recorded.get(component);
+    const u = unsettled.get(component);
+    components.push({
+      component,
+      digest: r?.digest ?? null,
+      releaseDigest: r?.releaseDigest ?? null,
+      releaseLabel: await labelOf(r?.releaseDigest),
+      state: u ? u.state : "settled",
+      attempt: u
+        ? {
+            verb: u.outcome.verb,
+            runId: u.outcome.runId,
+            timestamp: u.outcome.timestamp,
+            digest: u.digest,
+            releaseDigest: u.releaseDigest,
+            releaseLabel: await labelOf(u.releaseDigest),
+          }
+        : null,
+    });
+  }
+
+  // The release the environment was moving to is not one to go back to: the
+  // one a run left components unsettled on, else, of the releases its
+  // components run, the one that reached the environment last.
+  const exclude = new Set<string>();
+  if (unsettled.size > 0) {
+    for (const u of unsettled.values()) if (u.releaseDigest) exclude.add(u.releaseDigest);
+  } else {
+    const firstSeen = new Map<string, string>();
+    for (const r of records) {
+      if (r.releaseDigest === undefined) continue;
+      const seen = firstSeen.get(r.releaseDigest);
+      if (seen === undefined || r.timestamp < seen) firstSeen.set(r.releaseDigest, r.timestamp);
+    }
+    let arrived: string | undefined;
+    for (const d of releases) {
+      if (d === null) continue;
+      if (arrived === undefined || firstSeen.get(d)! > firstSeen.get(arrived)!) arrived = d;
+    }
+    if (arrived !== undefined) exclude.add(arrived);
+  }
+  const target = await rollbackTarget({ records, exclude, check: input.check });
+  return {
+    components,
+    redeploy: components.filter((c) => c.state !== "settled" && c.digest !== null).map((c) => redeployLine(env, c.component)),
+    rollback: target ? releaseRollbackLine(env, target, await labelOf(target)) : null,
+  };
+}

package/src/lifecycle/publish-attachments.ts

@@ -0,0 +1,196 @@
+/**
+ * What a publish attaches to what it publishes (#4049): an SBOM and the
+ * release's provenance statement.
+ *
+ * The provenance statement is an in-toto Statement v1 whose predicate
+ * (`https://intentius.io/chant/release/v1`) names the release, its commit,
+ * and the cut that signed it, with the cut's ssh signature in the
+ * `chant-release` namespace. Anyone holding the repository checks that
+ * signature offline with `chant release verify`, against
+ * `.chant/allowed_signers` at the release's commit. The predicate also says
+ * whether the run had an OIDC token: in CI, the provenance a registry records
+ * (npm's `--provenance`) is signed with it, and from a workstation the
+ * release's signature is the only provenance there is.
+ *
+ * The SBOM is an SPDX or CycloneDX JSON document. A target attaches the file
+ * its declaration's `sbom` names; with none named, the OCI and forge targets
+ * write one from the member's `package-lock.json` or `pom.xml` with the
+ * hermetic writer `generate-sbom` uses (../components/verbs/bom-writer.ts),
+ * dated with the cut's time, so a publish run again writes the same bytes.
+ * `sbom: false` publishes without one. The npm target carries its SBOM in
+ * each package instead, since a registry keeps no file beside a package
+ * (./publish-npm.ts).
+ *
+ * Both are written as sorted JSON, so the same release attaches the same
+ * bytes on every run, and a resumed stage finds what an earlier run sent.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { sortedJsonReplacer } from "../utils";
+import { writeBom } from "../components/verbs/bom-writer";
+import { parseNpmPackageLock, parsePomXml } from "../components/verbs/lockfile-sbom-generator";
+import { SBOM_MEDIA_TYPES } from "../components/verbs/sbom-generator";
+import { bytesDigest, checkReleaseDigest, memberFile } from "./publish-targets";
+import { PublishTargetError, type PublishContext } from "./release-publish";
+import { RELEASE_SEAL_NAMESPACE } from "../workspace/identity-gate-rule";
+
+/** The in-toto statement type the provenance statement is. */
+export const IN_TOTO_STATEMENT_TYPE = "https://in-toto.io/Statement/v1";
+/** The predicate type of chant's release provenance. */
+export const RELEASE_PREDICATE_TYPE = "https://intentius.io/chant/release/v1";
+/** The media type an in-toto statement is attached under. */
+export const IN_TOTO_MEDIA_TYPE = "application/vnd.in-toto+json";
+/** The file name the provenance statement is attached under. */
+export const PROVENANCE_FILE = "release.intoto.json";
+/** The file name of an SBOM chant writes from a lockfile. */
+export const GENERATED_SBOM_FILE = "sbom.spdx.json";
+/** The names an npm package's own SBOM is looked for under, at its root, when the declaration names none. */
+export const PACKAGE_SBOM_FILES = ["sbom.spdx.json", "sbom.cdx.json", "sbom.cyclonedx.json"] as const;
+
+/** One file attached to what a target publishes. */
+export interface Attachment {
+  kind: "sbom" | "provenance";
+  /** The file name it is attached under. */
+  name: string;
+  mediaType: string;
+  bytes: Uint8Array;
+  digest: string;
+}
+
+const json = (value: unknown): Uint8Array => new Uint8Array(Buffer.from(`${JSON.stringify(value, sortedJsonReplacer, 2)}\n`, "utf-8"));
+
+const attachment = (kind: Attachment["kind"], name: string, mediaType: string, bytes: Uint8Array): Attachment => ({ kind, name, mediaType, bytes, digest: bytesDigest(bytes) });
+
+/**
+ * The provenance statement for `subjects`, the digests of what the target
+ * publishes. Every value in it comes from the release, its cut and the run's
+ * OIDC check, never from the clock, so it is the same bytes on every run.
+ */
+export function releaseProvenance(ctx: PublishContext, subjects: ReadonlyArray<{ name: string; digest: string }>): Attachment {
+  const cut = ctx.cut ?? null;
+  const statement = {
+    _type: IN_TOTO_STATEMENT_TYPE,
+    subject: subjects.map((s) => ({ name: s.name, digest: { [s.digest.split(":")[0] ?? "sha256"]: s.digest.split(":")[1] ?? s.digest } })),
+    predicateType: RELEASE_PREDICATE_TYPE,
+    predicate: {
+      releaseDigest: ctx.release.releaseDigest,
+      label: ctx.label,
+      member: ctx.release.member,
+      commit: ctx.release.commit,
+      cut: cut ? { actor: cut.actor, label: cut.label, timestamp: cut.timestamp, runId: cut.runId, signature: cut.signature, namespace: RELEASE_SEAL_NAMESPACE } : null,
+      provenance: ctx.provenance.oidc ? { kind: "oidc", ci: ctx.provenance.ci } : { kind: "signature", ci: ctx.provenance.ci },
+    },
+  };
+  return attachment("provenance", PROVENANCE_FILE, IN_TOTO_MEDIA_TYPE, json(statement));
+}
+
+/** The media type of an SBOM document, or null when `bytes` is neither SPDX nor CycloneDX JSON. */
+export function sbomMediaType(bytes: Uint8Array): string | null {
+  let doc: { spdxVersion?: unknown; bomFormat?: unknown };
+  try {
+    doc = JSON.parse(Buffer.from(bytes).toString("utf-8")) as typeof doc;
+  } catch {
+    return null;
+  }
+  if (!doc || typeof doc !== "object") return null;
+  if (typeof doc.spdxVersion === "string") return SBOM_MEDIA_TYPES.spdx;
+  if (doc.bomFormat === "CycloneDX") return SBOM_MEDIA_TYPES.cyclonedx;
+  return null;
+}
+
+function invalid(where: string): PublishTargetError {
+  return new PublishTargetError("publish-sbom-invalid", `${where} is not an SPDX or CycloneDX JSON document`, "Point sbom at the SPDX or CycloneDX JSON the build writes.");
+}
+
+/** The lockfile nearest the member: `package-lock.json` or `pom.xml` in `cwd` or a directory above it inside its repository (only `cwd` outside one). */
+function nearestLockfile(cwd: string): { kind: "npm" | "maven"; path: string } | null {
+  let top: string | null = null;
+  try {
+    top = realpathSync(execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim());
+  } catch {
+    top = null;
+  }
+  let dir = realpathSync(cwd);
+  for (;;) {
+    for (const [kind, file] of [["npm", "package-lock.json"], ["maven", "pom.xml"]] as const) {
+      if (existsSync(join(dir, file))) return { kind, path: join(dir, file) };
+    }
+    const up = dirname(dir);
+    if (top === null || dir === top || up === dir || !up.startsWith(top)) return null;
+    dir = up;
+  }
+}
+
+/**
+ * The SBOM a target attaches, for an OCI image or a forge release: the file
+ * `declared` names (relative to the member, checked against the release's
+ * digest when the release records it), else one written from the member's
+ * lockfile for `subject`. Null when `declared` is `false`. Throws
+ * `publish-sbom-missing` when there is neither.
+ */
+export function memberSbom(ctx: PublishContext, declared: string | false | undefined, subject: string, target: string): Attachment | null {
+  if (declared === false) return null;
+  if (declared !== undefined) {
+    const abs = memberFile(ctx.cwd, declared);
+    const bytes = new Uint8Array(readFileSync(abs));
+    checkReleaseDigest(ctx.release, "asset", ctx.cwd, declared, [bytesDigest(bytes)]);
+    const mediaType = sbomMediaType(bytes);
+    if (!mediaType) throw invalid(declared);
+    return attachment("sbom", declared.split("/").pop() ?? declared, mediaType, bytes);
+  }
+  const lock = nearestLockfile(ctx.cwd);
+  if (!lock) {
+    throw new PublishTargetError(
+      "publish-sbom-missing",
+      `${target} attaches an SBOM to what it publishes, and its declaration names none and there is no package-lock.json or pom.xml in ${ctx.cwd} or above it to write one from`,
+      "Set sbom in the declaration to the SPDX or CycloneDX file the build writes, or sbom: false to publish without one.",
+    );
+  }
+  const content = readFileSync(lock.path, "utf-8");
+  const packages = lock.kind === "npm" ? parseNpmPackageLock(content) : parsePomXml(content);
+  const at = new Date(ctx.cut?.timestamp ?? 0);
+  const doc = writeBom(
+    "spdx",
+    { subjectName: subject, subjectId: ctx.release.releaseDigest, packages, generator: `chant-lockfile-sbom/${lock.kind === "npm" ? "package-lock.json" : "pom.xml"}` },
+    () => (Number.isNaN(at.getTime()) ? new Date(0) : at),
+  );
+  return attachment("sbom", GENERATED_SBOM_FILE, doc.mediaType, new Uint8Array(Buffer.from(doc.bytes, "utf-8")));
+}
+
+/**
+ * The SBOM an npm package carries at its root: the file `declared` names, else
+ * the first of {@link PACKAGE_SBOM_FILES} it holds, in a package directory or
+ * under `package/` in a packed `.tgz`. Null when `declared` is `false`.
+ * Throws `publish-sbom-missing` when the package has none, and
+ * `publish-sbom-invalid` when it is not SPDX or CycloneDX JSON.
+ */
+export function packageSbom(abs: string, isDirectory: boolean, path: string, name: string, declared: string | false | undefined): { file: string; digest: string } | null {
+  if (declared === false) return null;
+  const candidates = declared !== undefined ? [declared] : [...PACKAGE_SBOM_FILES];
+  let listed: Set<string> | null = null;
+  if (!isDirectory) {
+    try {
+      listed = new Set(execFileSync("tar", ["-tzf", abs], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).split("\n").map((l) => l.trim()));
+    } catch {
+      listed = new Set();
+    }
+  }
+  for (const file of candidates) {
+    let bytes: Uint8Array | null = null;
+    if (isDirectory) {
+      if (existsSync(join(abs, file))) bytes = new Uint8Array(readFileSync(join(abs, file)));
+    } else if (listed!.has(`package/${file}`)) {
+      bytes = new Uint8Array(execFileSync("tar", ["-xzOf", abs, `package/${file}`], { stdio: ["ignore", "pipe", "ignore"] }));
+    }
+    if (bytes === null) continue;
+    if (!sbomMediaType(bytes)) throw invalid(`${file} in ${path}`);
+    return { file, digest: bytesDigest(bytes) };
+  }
+  throw new PublishTargetError(
+    "publish-sbom-missing",
+    `${name} (${path}) carries no SBOM: npm keeps no file beside a package, so its SBOM goes in it, and ${declared !== undefined ? declared : `none of ${PACKAGE_SBOM_FILES.join(", ")}`} is at its root`,
+    `Write one into the package before it is packed, such as npm sbom --sbom-format spdx > ${path}/sbom.spdx.json, and keep it in the package's files; or set sbom: false to publish without one.`,
+  );
+}

package/src/lifecycle/publish-credentials.ts

@@ -0,0 +1,84 @@
+/**
+ * Credentials for publish targets (#4047), and the redactor every line a
+ * publish prints goes through.
+ *
+ * A target reads its credential from the environment of the run, by a name
+ * the declaration gives or the target's default, so a workstation sets it in
+ * its shell and CI in the job's secrets. chant never writes a credential to
+ * `chant/lifecycle`, to a file it keeps, or to its output: the value is held
+ * in memory for the requests that need it, and every line a target prints,
+ * and every error it throws, passes through {@link Redactor.redact} first.
+ *
+ * The redactor masks the value of each credential a target read, the values
+ * of the environment variables CI and registries use for tokens
+ * ({@link TOKEN_ENV_VARS}), and the token forms npm and HTTP headers write
+ * (`_authToken=...`, `Authorization: Bearer ...`).
+ */
+
+/** Environment variables that hold a token in CI or for a registry. Their values are masked in all publish output. */
+export const TOKEN_ENV_VARS = [
+  "NODE_AUTH_TOKEN",
+  "NPM_TOKEN",
+  "NPM_ID_TOKEN",
+  "SIGSTORE_ID_TOKEN",
+  "ACTIONS_ID_TOKEN_REQUEST_TOKEN",
+  "ACTIONS_RUNTIME_TOKEN",
+  "GITHUB_TOKEN",
+  "GH_TOKEN",
+  "GITLAB_TOKEN",
+  "CI_JOB_TOKEN",
+  "FORGEJO_TOKEN",
+  "GITEA_TOKEN",
+  "OCI_PASSWORD",
+  "DOCKER_PASSWORD",
+] as const;
+
+/** What a masked value is replaced with. */
+export const REDACTED = "[redacted]";
+
+/** Masks credentials in text a publish prints. */
+export interface Redactor {
+  /** Add a value to mask. Values shorter than 4 characters are not masked, since they would mask ordinary text. */
+  add(value: string | undefined | null): void;
+  redact(text: string): string;
+}
+
+/** A redactor that masks the token variables of `env` and every value added to it later. */
+export function createRedactor(env: NodeJS.ProcessEnv = {}, names: readonly string[] = []): Redactor {
+  const values = new Set<string>();
+  const add = (v: string | undefined | null) => {
+    if (typeof v === "string" && v.trim().length >= 4) values.add(v.trim());
+  };
+  for (const name of [...TOKEN_ENV_VARS, ...names]) add(env[name]);
+  return {
+    add,
+    redact(text: string): string {
+      let out = text;
+      // Longest first, so a value that contains another is masked whole.
+      for (const v of [...values].sort((a, b) => b.length - a.length)) out = out.split(v).join(REDACTED);
+      return out
+        .replace(/(_authToken\s*=\s*)("?)[^\s"]+\2/g, `$1${REDACTED}`)
+        .replace(/(authorization:\s*(?:bearer|basic|token)\s+)[^\s"',]+/gi, `$1${REDACTED}`)
+        .replace(/(private-token:\s*|job-token:\s*)[^\s"',]+/gi, `$1${REDACTED}`);
+    },
+  };
+}
+
+/** A credential a target read, and the variable it came from. The value is never printed. */
+export interface Credential {
+  value: string;
+  /** The environment variable, or `docker config` for one read from the docker config file. */
+  from: string;
+}
+
+/** The first of `names` set in `env`, added to `redactor`, or null. */
+export function readCredential(env: NodeJS.ProcessEnv, names: readonly string[], redactor: Redactor): Credential | null {
+  for (const name of names) {
+    const value = env[name];
+    if (typeof value === "string" && value !== "") {
+      redactor.add(value);
+      return { value, from: name };
+    }
+  }
+  return null;
+}

package/src/lifecycle/publish-declaration.ts

@@ -0,0 +1,95 @@
+/**
+ * Where a member declares its publish targets (#4047): `release.publish` in
+ * its `chant.config.ts`, a list of targets that `chant release publish` runs
+ * in order.
+ *
+ * ```ts
+ * export default {
+ *   release: {
+ *     publish: [
+ *       { type: "npm", packages: ["packages/core", "packages/cli"] },
+ *       { type: "oci", image: "dist/api.oci.tar", repository: "ghcr.io/acme/api", tags: ["{label}"], usernameEnv: "GITHUB_ACTOR", passwordEnv: "GITHUB_TOKEN" },
+ *       { type: "forge", forge: "github", repo: "acme/api", assets: ["dist/api-linux-amd64.tar.gz"] },
+ *     ],
+ *   },
+ * };
+ * ```
+ *
+ * The config is the one at the release's commit: a publish with a target
+ * refuses a checkout whose `HEAD` is another commit. Paths are relative to
+ * the member's directory. A declaration names the environment variables its
+ * credentials are read from, never the credentials.
+ *
+ * This module imports nothing but zod, so ../config.ts can validate the block.
+ */
+
+import { z } from "zod";
+
+const envName = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "an environment variable name");
+
+/** An SBOM file, or `false` to publish without one (#4049). */
+const sbomField = z.union([z.string().min(1), z.literal(false)]);
+
+/** npm: `npm publish` for each package, in the order given. */
+export const NpmPublishSchema = z
+  .object({
+    type: z.literal("npm"),
+    /** Package directories or packed `.tgz` files, relative to the member, published in this order. */
+    packages: z.array(z.string().min(1)).min(1),
+    /** The registry, else the one npm's own config names. */
+    registry: z.string().url().optional(),
+    access: z.enum(["public", "restricted"]).optional(),
+    /**
+     * The SBOM each package carries at its root (#4049), a file name relative
+     * to the package. Default: the first of `sbom.spdx.json`, `sbom.cdx.json`,
+     * `sbom.cyclonedx.json` it holds. `false` publishes without one.
+     */
+    sbom: sbomField.optional(),
+  })
+  .strict();
+
+/** An OCI registry such as GHCR or Docker Hub: the image is pushed by digest, then tagged. */
+export const OciPublishSchema = z
+  .object({
+    type: z.literal("oci"),
+    /** An OCI image layout, as a directory or a tar file such as `docker save` writes, relative to the member. */
+    image: z.string().min(1),
+    /** `<registry host>/<name>`, such as `ghcr.io/acme/api` or `docker.io/acme/api`. */
+    repository: z.string().min(1),
+    /** Tags to point at the pushed digest. `{label}` is the release's label. Default: `["{label}"]`, or none for a release with no label. */
+    tags: z.array(z.string().min(1)).optional(),
+    /** The variable holding the registry user name. Default `OCI_USERNAME`. */
+    usernameEnv: envName.optional(),
+    /** The variable holding the registry password or token. Default `OCI_PASSWORD`. */
+    passwordEnv: envName.optional(),
+    /** The SBOM pushed as a referrer of the image (#4049), relative to the member. Default: one written from the member's lockfile. `false` publishes without one. */
+    sbom: sbomField.optional(),
+  })
+  .strict();
+
+/** Release assets on a GitHub, GitLab or Forgejo release named by the release's tag. */
+export const ForgePublishSchema = z
+  .object({
+    type: z.literal("forge"),
+    forge: z.enum(["github", "gitlab", "forgejo"]),
+    /** `owner/name` on GitHub and Forgejo; the project path or numeric id on GitLab. */
+    repo: z.string().min(1),
+    /** The API root: default `$GITHUB_API_URL` or `https://api.github.com` on GitHub, `$CI_API_V4_URL` or `https://gitlab.com/api/v4` on GitLab, `$GITHUB_API_URL` on Forgejo, which has no default. */
+    api: z.string().url().optional(),
+    /** Files to attach, relative to the member. */
+    assets: z.array(z.string().min(1)).min(1),
+    /** The forge release's tag. Default: the tag the cut made, `release/<label>` or `release/<member>/<label>`. */
+    tag: z.string().min(1).optional(),
+    /** The variable holding the token. Default `GITHUB_TOKEN`, `GITLAB_TOKEN` (then `CI_JOB_TOKEN`), or `FORGEJO_TOKEN`. */
+    tokenEnv: envName.optional(),
+    /** The SBOM attached to the release (#4049), relative to the member. Default: one written from the member's lockfile. `false` publishes without one. */
+    sbom: sbomField.optional(),
+  })
+  .strict();
+
+export const PublishDeclarationSchema = z.discriminatedUnion("type", [NpmPublishSchema, OciPublishSchema, ForgePublishSchema]);
+
+export type NpmPublishDeclaration = z.infer<typeof NpmPublishSchema>;
+export type OciPublishDeclaration = z.infer<typeof OciPublishSchema>;
+export type ForgePublishDeclaration = z.infer<typeof ForgePublishSchema>;
+export type PublishDeclaration = z.infer<typeof PublishDeclarationSchema>;