@intentius/chant 0.124.28 → 0.124.30

package/src/lifecycle/publish-npm.ts

@@ -0,0 +1,259 @@
+/**
+ * The npm publish target (#4047): `npm publish` for each package the
+ * declaration lists, in the order it lists them, so a set of packages that
+ * depend on each other goes out dependencies first.
+ *
+ * Each package is a directory with a `package.json` or a `.tgz` that
+ * `npm pack` wrote, relative to the member.
+ *
+ * A publish is two steps (#4048), as chant's own releases are (#3903):
+ *
+ * - stage: for each package, `npm view <name>@<version> version` asks the
+ *   registry whether it already holds the version, and when it does not,
+ *
+ *       npm publish <package> --tag next [--registry <url>] [--access <access>] [--provenance]
+ *
+ *   puts it out under the `next` dist-tag, where nothing that resolves
+ *   `latest` or a range finds it. A version already there is not published
+ *   again, so a stage run after a failure publishes only the rest.
+ * - reveal: `npm dist-tag add <name>@<version> latest` for each package in
+ *   the declared order. The first package is the set's core: it moves first,
+ *   so a consumer never resolves a new package whose new core is not `latest`
+ *   yet. Order the list core first, then the packages that depend on it.
+ *   `ctx.tag` names another tag to move in place of `latest`.
+ *
+ * `--provenance` is passed when the run has an OIDC token (`detectProvenance`
+ * in ./release-publish.ts), so a CI publish gets npm provenance, and npm's
+ * trusted publishing exchanges that token for its own. With that token, the
+ * reveal then checks what it published (#4049): in an empty directory it
+ * installs every package at its version with `npm install --ignore-scripts`
+ * and runs `npm audit signatures`, which fails on a package whose registry
+ * signature or provenance attestation does not verify. From a workstation
+ * there is no npm provenance, and the release's signature, which
+ * `chant release verify` checks, is the only provenance.
+ *
+ * Each package carries its SBOM (#4049): npm keeps no file beside a package,
+ * so the SBOM is a file at the package's root, the one `sbom` names or the
+ * first of `sbom.spdx.json`, `sbom.cdx.json`, `sbom.cyclonedx.json` it holds,
+ * such as `npm sbom` writes. A package with none is refused
+ * (`publish-sbom-missing`) unless the declaration says `sbom: false`. Moving a dist-tag over
+ * OIDC needs "Allow npm dist-tag" on the package's trusted-publisher record.
+ * npm makes the first version of a new package `latest` whatever tag it is
+ * published under, so a package's first release is visible when it stages.
+ *
+ * Credentials are npm's own. chant reads no npm token and writes no `.npmrc`:
+ * npm authenticates with the registry's `_authToken` in the user's or the
+ * CI's npm config (`actions/setup-node` writes one that reads
+ * `NODE_AUTH_TOKEN`), or by trusted publishing. npm runs with the run's
+ * environment, and everything it prints is redacted before chant prints it.
+ */
+
+import { execFileSync, spawn } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { packageSbom } from "./publish-attachments";
+import type { NpmPublishDeclaration } from "./publish-declaration";
+import { checkReleaseDigest, fileDigest, isDir, memberFile, publishTargetKey } from "./publish-targets";
+import { NPM_STAGE_TAG, PublishTargetError, type PublishContext, type PublishDeps, type PublishItem, type PublishTarget } from "./release-publish";
+
+interface NpmPackage {
+  path: string;
+  abs: string;
+  name: string;
+  version: string;
+  digest?: string;
+  /** The SBOM file at its root, or undefined under `sbom: false`. */
+  sbom?: string;
+}
+
+/** Read a package's name and version, from its directory or its packed `.tgz`, and find the SBOM it carries. */
+function readPackage(ctx: PublishContext, path: string, sbom: NpmPublishDeclaration["sbom"]): NpmPackage {
+  const abs = memberFile(ctx.cwd, path);
+  let text: string;
+  let digest: string | undefined;
+  const directory = isDir(abs);
+  if (directory) {
+    try {
+      text = readFileSync(join(abs, "package.json"), "utf-8");
+    } catch {
+      throw new PublishTargetError("publish-npm-not-a-package", `${path} has no package.json`);
+    }
+  } else {
+    digest = fileDigest(abs);
+    checkReleaseDigest(ctx.release, "asset", ctx.cwd, path, [digest]);
+    try {
+      text = execFileSync("tar", ["-xzOf", abs, "package/package.json"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
+    } catch {
+      throw new PublishTargetError("publish-npm-not-a-package", `${path} is not a package tarball with package/package.json`);
+    }
+  }
+  let pkg: { name?: unknown; version?: unknown; private?: unknown };
+  try {
+    pkg = JSON.parse(text);
+  } catch {
+    throw new PublishTargetError("publish-npm-not-a-package", `${path}'s package.json is not JSON`);
+  }
+  if (typeof pkg.name !== "string" || typeof pkg.version !== "string") {
+    throw new PublishTargetError("publish-npm-not-a-package", `${path}'s package.json has no name and version`);
+  }
+  if (pkg.private === true) {
+    throw new PublishTargetError("publish-npm-private", `${pkg.name} (${path}) is private, and npm refuses to publish it`, "Remove it from release.publish, or remove private: true.");
+  }
+  const carried = packageSbom(abs, directory, path, pkg.name, sbom);
+  return { path, abs, name: pkg.name, version: pkg.version, ...(digest ? { digest } : {}), ...(carried ? { sbom: carried.file } : {}) };
+}
+
+/** The arguments of one `npm publish`, which stages under `tag`. */
+export function npmPublishArgs(decl: Pick<NpmPublishDeclaration, "registry" | "access">, abs: string, ctx: Pick<PublishContext, "provenance">, tag: string = NPM_STAGE_TAG): string[] {
+  return [
+    "publish",
+    abs,
+    "--tag",
+    tag,
+    ...(decl.registry ? ["--registry", decl.registry] : []),
+    ...(decl.access ? ["--access", decl.access] : []),
+    ...(ctx.provenance.oidc ? ["--provenance"] : []),
+  ];
+}
+
+/** The arguments of the `npm dist-tag add` that reveals a staged version under `tag`. */
+export function npmDistTagArgs(decl: Pick<NpmPublishDeclaration, "registry">, name: string, version: string, tag: string): string[] {
+  return ["dist-tag", "add", `${name}@${version}`, tag, ...(decl.registry ? ["--registry", decl.registry] : [])];
+}
+
+/** The arguments of the `npm install` that fetches the published packages into an empty directory for `npm audit signatures`. */
+export function npmAuditInstallArgs(decl: Pick<NpmPublishDeclaration, "registry">): string[] {
+  return ["install", "--ignore-scripts", "--no-audit", "--no-fund", ...(decl.registry ? ["--registry", decl.registry] : [])];
+}
+
+/** The arguments of `npm audit signatures`. */
+export function npmAuditSignaturesArgs(decl: Pick<NpmPublishDeclaration, "registry">): string[] {
+  return ["audit", "signatures", ...(decl.registry ? ["--registry", decl.registry] : [])];
+}
+
+function run(bin: string, args: string[], ctx: PublishContext, cwd: string = ctx.cwd): Promise<{ code: number; output: string[] }> {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(bin, args, { cwd, env: ctx.env, stdio: ["ignore", "pipe", "pipe"] });
+    const output: string[] = [];
+    let partial = { out: "", err: "" };
+    const take = (key: "out" | "err") => (chunk: Buffer) => {
+      const text = partial[key] + chunk.toString("utf-8");
+      const lines = text.split("\n");
+      partial = { ...partial, [key]: lines.pop() ?? "" };
+      for (const l of lines) if (l.trim() !== "") output.push(ctx.redactor.redact(l));
+    };
+    child.stdout.on("data", take("out"));
+    child.stderr.on("data", take("err"));
+    child.on("error", reject);
+    child.on("close", (code) => {
+      for (const l of [partial.out, partial.err]) if (l.trim() !== "") output.push(ctx.redactor.redact(l));
+      resolvePromise({ code: code ?? 1, output });
+    });
+  });
+}
+
+export function npmTarget(decl: NpmPublishDeclaration, deps: PublishDeps): PublishTarget {
+  const bin = deps.npm ?? "npm";
+  const registry = decl.registry ?? "the registry npm's config names";
+  const shown = (tag: string) => `${registry}, dist-tag ${tag}`;
+  const revealTag = (ctx: PublishContext) => ctx.tag ?? "latest";
+  const npm = async (ctx: PublishContext, args: string[], cwd?: string): Promise<{ code: number; output: string[] }> => {
+    try {
+      return await run(bin, args, ctx, cwd);
+    } catch (err) {
+      throw new PublishTargetError("publish-npm-failed", ctx.redactor.redact(`npm could not be run: ${err instanceof Error ? err.message : String(err)}`), "Install npm, or put it on PATH.");
+    }
+  };
+  /** Whether the registry already holds the version. A failed lookup reads as no, and the publish that follows says why. */
+  const onRegistry = async (ctx: PublishContext, pkg: NpmPackage): Promise<boolean> => {
+    const r = await npm(ctx, ["view", `${pkg.name}@${pkg.version}`, "version", ...(decl.registry ? ["--registry", decl.registry] : [])]);
+    return r.code === 0 && r.output.some((l) => l.trim() === pkg.version || l.trim() === JSON.stringify(pkg.version));
+  };
+  const read = (ctx: PublishContext) => decl.packages.map((p) => readPackage(ctx, p, decl.sbom));
+  const extra = (pkg: NpmPackage) => ({ ...(pkg.digest ? { digest: pkg.digest } : {}), ...(pkg.sbom ? { sbom: pkg.sbom } : {}) });
+  const plan = async (ctx: PublishContext): Promise<PublishItem[]> =>
+    read(ctx).map((pkg) => ({ name: `${pkg.name}@${pkg.version}`, destination: `${shown(NPM_STAGE_TAG)}, then ${revealTag(ctx)}`, ...extra(pkg) }));
+  /**
+   * In CI, install what was published into an empty directory and run
+   * `npm audit signatures` there (#4049), which checks each package's
+   * registry signature and provenance attestation.
+   */
+  const audit = async (ctx: PublishContext, pkgs: NpmPackage[]): Promise<void> => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-npm-audit-"));
+    try {
+      const dependencies = Object.fromEntries(pkgs.map((p) => [p.name, p.version]));
+      writeFileSync(join(dir, "package.json"), `${JSON.stringify({ name: "chant-publish-audit", version: "0.0.0", private: true, dependencies }, null, 2)}\n`);
+      for (const args of [npmAuditInstallArgs(decl), npmAuditSignaturesArgs(decl)]) {
+        ctx.log(`npm ${args.join(" ")}`);
+        const result = await npm(ctx, args, dir);
+        for (const line of result.output) ctx.log(`  ${line}`);
+        if (result.code !== 0) {
+          throw new PublishTargetError(
+            "publish-npm-audit-failed",
+            `npm ${args.slice(0, 2).join(" ")} exited ${result.code} for ${pkgs.map((p) => `${p.name}@${p.version}`).join(", ")}, after latest moved: ${result.output.at(-1) ?? "npm printed nothing"}`,
+            "Each package was published; check its signature and provenance on the registry. Running the publish again moves no tag that moved and audits again.",
+          );
+        }
+      }
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  };
+  return {
+    kind: "npm",
+    name: `npm (${decl.packages.length} package${decl.packages.length === 1 ? "" : "s"})`,
+    destination: `npm ${registry}`,
+    credentialEnv: [],
+    key: publishTargetKey(decl),
+    plan,
+    async stage(ctx) {
+      const pkgs = read(ctx);
+      const items: PublishItem[] = [];
+      for (const pkg of pkgs) {
+        const item: PublishItem = { name: `${pkg.name}@${pkg.version}`, destination: shown(NPM_STAGE_TAG), ...extra(pkg) };
+        if (await onRegistry(ctx, pkg)) {
+          ctx.log(`${item.name} is already on the registry; not published again`);
+          items.push({ ...item, present: true });
+          continue;
+        }
+        const args = npmPublishArgs(decl, pkg.abs, ctx);
+        ctx.log(`npm publish ${pkg.path} ${args.slice(2).join(" ")}`);
+        const result = await npm(ctx, args);
+        for (const line of result.output) ctx.log(`  ${line}`);
+        if (result.code !== 0) {
+          const done = items.map((i) => i.name);
+          throw new PublishTargetError(
+            "publish-npm-failed",
+            `npm publish of ${item.name} exited ${result.code}${done.length > 0 ? `, after ${done.join(", ")} were staged under ${NPM_STAGE_TAG}` : ", before any package was staged"}: ${result.output.at(-1) ?? "npm printed nothing"}`,
+          );
+        }
+        items.push(item);
+      }
+      return { target: this.name, destination: this.destination, items, state: {} };
+    },
+    async reveal(ctx) {
+      const tag = revealTag(ctx);
+      const pkgs = read(ctx);
+      const items: PublishItem[] = [];
+      // The declared order: the first package is the set's core, and its tag moves first.
+      for (const pkg of pkgs) {
+        const args = npmDistTagArgs(decl, pkg.name, pkg.version, tag);
+        ctx.log(`npm ${args.join(" ")}`);
+        const result = await npm(ctx, args);
+        for (const line of result.output) ctx.log(`  ${line}`);
+        if (result.code !== 0) {
+          const moved = items.map((i) => i.name);
+          throw new PublishTargetError(
+            "publish-npm-tag-failed",
+            `npm dist-tag add ${pkg.name}@${pkg.version} ${tag} exited ${result.code}${moved.length > 0 ? `, after ${tag} moved for ${moved.join(", ")}` : `, before ${tag} moved for any package`}: ${result.output.at(-1) ?? "npm printed nothing"}`,
+            `Moving a dist-tag needs npm credentials that may change dist-tags; over OIDC that is "Allow npm dist-tag" on the package's trusted-publisher record.`,
+          );
+        }
+        items.push({ name: `${pkg.name}@${pkg.version}`, destination: shown(tag), ...extra(pkg) });
+      }
+      if (ctx.provenance.oidc) await audit(ctx, pkgs);
+      return { target: this.name, destination: this.destination, items };
+    },
+  };
+}

package/src/lifecycle/publish-oci.ts

@@ -0,0 +1,396 @@
+/**
+ * The OCI publish target (#4047): an image pushed to an OCI registry, such
+ * as GHCR or Docker Hub, by digest, then tagged.
+ *
+ * The image is an OCI image layout (`index.json` and `blobs/`), as a
+ * directory or a tar file such as `docker save` writes. Its `index.json`
+ * names one manifest: an image manifest, or an index of them. The target
+ * speaks the registry HTTP API (the OCI distribution spec) through an
+ * injectable `fetch`, so it needs no docker, crane or oras, and the tests
+ * run it against a registry fake on 127.0.0.1. A publish is two steps
+ * (#4048). The stage pushes by digest only: for each image manifest it
+ * uploads the config and layers the registry does not hold yet, then puts
+ * the manifest by its digest, then the index when there is one. A registry
+ * that already holds the top manifest's digest is sent nothing. Every blob
+ * is checked against its digest before it is sent. Nothing a consumer pulls
+ * by tag changes until the reveal, which points each tag at that digest.
+ *
+ * The stage also pushes, by digest, two referrers of the image (#4049): its
+ * SBOM and the release's provenance statement (./publish-attachments.ts),
+ * each an OCI artifact manifest whose `subject` is the image, so a registry
+ * with the referrers API lists them under the image's digest and `oras
+ * discover` or `cosign tree` finds them. A referrer the registry already
+ * holds is not pushed again.
+ *
+ * Credentials come from `usernameEnv` and `passwordEnv` (default
+ * `OCI_USERNAME`, `OCI_PASSWORD`), or else from the `auths` entry for the
+ * registry in the docker config file (`$DOCKER_CONFIG/config.json` or
+ * `~/.docker/config.json`), which `docker login` writes; a credential helper
+ * (`credsStore`) is not read. With none, the push is anonymous. The registry
+ * decides how they are used: a `Basic` challenge takes them as they are, and
+ * a `Bearer` challenge (GHCR, Docker Hub) exchanges them for a token at the
+ * realm it names. The password and the token are masked in all output.
+ *
+ * A host of `localhost`, `127.0.0.1` or `[::1]` is spoken to over http, as
+ * docker does; any other over https. `docker.io` is `registry-1.docker.io`,
+ * and a one-part Docker Hub name is under `library/`.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { memberSbom, releaseProvenance, type Attachment } from "./publish-attachments";
+import { readCredential, type Credential } from "./publish-credentials";
+import type { OciPublishDeclaration } from "./publish-declaration";
+import { bytesDigest, checkReleaseDigest, fileDigest, isDir, memberFile, publishTargetKey } from "./publish-targets";
+import { PublishTargetError, type PublishContext, type PublishDeps, type PublishFetch, type PublishItem, type PublishTarget } from "./release-publish";
+
+const INDEX_TYPES = new Set(["application/vnd.oci.image.index.v1+json", "application/vnd.docker.distribution.manifest.list.v2+json"]);
+
+/** A repository reference split into where the registry is and the name in it. */
+export interface OciRepository {
+  /** The host as written, used to find docker config credentials. */
+  host: string;
+  /** `http(s)://<host>` the API is under. */
+  base: string;
+  /** The repository's name in the registry. */
+  name: string;
+}
+
+export function parseRepository(repository: string): OciRepository {
+  const parts = repository.split("/");
+  const first = parts[0]!;
+  const isHost = parts.length > 1 && (first.includes(".") || first.includes(":") || first === "localhost");
+  let host = isHost ? first : "docker.io";
+  let path = isHost ? parts.slice(1) : parts;
+  if (host === "docker.io" || host === "index.docker.io") {
+    host = "docker.io";
+    if (path.length === 1) path = ["library", ...path];
+  }
+  const apiHost = host === "docker.io" ? "registry-1.docker.io" : host;
+  const local = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/.test(apiHost);
+  return { host, base: `${local ? "http" : "https"}://${apiHost}`, name: path.join("/") };
+}
+
+interface Descriptor {
+  mediaType: string;
+  digest: string;
+  size?: number;
+}
+
+/** What a layout holds, in the order it is pushed. */
+interface LayoutImage {
+  top: Descriptor & { bytes: Uint8Array };
+  /** The image manifests: one, or an index's children. */
+  manifests: Array<Descriptor & { bytes: Uint8Array; blobs: Descriptor[] }>;
+  configDigests: string[];
+  readBlob(digest: string): Uint8Array;
+  cleanup(): void;
+}
+
+function readLayout(abs: string): LayoutImage {
+  let dir = abs;
+  let tmp: string | null = null;
+  if (!isDir(abs)) {
+    tmp = mkdtempSync(join(tmpdir(), "chant-oci-"));
+    try {
+      execFileSync("tar", ["-xf", abs, "-C", tmp], { stdio: "ignore" });
+    } catch {
+      rmSync(tmp, { recursive: true, force: true });
+      throw new PublishTargetError("publish-oci-not-a-layout", `${abs} is neither an OCI image layout directory nor a tar file of one`);
+    }
+    dir = tmp;
+  }
+  const cleanup = () => {
+    if (tmp) rmSync(tmp, { recursive: true, force: true });
+  };
+  try {
+    const readBlob = (digest: string): Uint8Array => {
+      const [alg, hex] = digest.split(":");
+      const file = join(dir, "blobs", alg ?? "", hex ?? "");
+      if (!alg || !hex || !existsSync(file)) throw new PublishTargetError("publish-oci-not-a-layout", `the layout has no blob ${digest}`);
+      const bytes = readFileSync(file);
+      if (bytesDigest(bytes) !== digest) throw new PublishTargetError("publish-oci-blob-corrupt", `blob ${digest} in the layout does not match its digest`);
+      return bytes;
+    };
+    const indexFile = join(dir, "index.json");
+    if (!existsSync(indexFile)) throw new PublishTargetError("publish-oci-not-a-layout", `${abs} has no index.json, so it is not an OCI image layout`);
+    const index = JSON.parse(readFileSync(indexFile, "utf-8")) as { manifests?: Descriptor[] };
+    const tops = index.manifests ?? [];
+    if (tops.length !== 1) {
+      throw new PublishTargetError("publish-oci-not-one-image", `${abs} names ${tops.length} manifests in its index.json, and a target pushes one image`, "Save one image per layout.");
+    }
+    const topDesc = tops[0]!;
+    const topBytes = readBlob(topDesc.digest);
+    const manifests: LayoutImage["manifests"] = [];
+    const configDigests: string[] = [];
+    const image = (d: Descriptor, bytes: Uint8Array) => {
+      const m = JSON.parse(Buffer.from(bytes).toString("utf-8")) as { config?: Descriptor; layers?: Descriptor[]; mediaType?: string };
+      if (!m.config) throw new PublishTargetError("publish-oci-not-a-layout", `manifest ${d.digest} has no config`);
+      configDigests.push(m.config.digest);
+      manifests.push({ ...d, mediaType: d.mediaType ?? m.mediaType, bytes, blobs: [m.config, ...(m.layers ?? [])] });
+    };
+    const topParsed = JSON.parse(Buffer.from(topBytes).toString("utf-8")) as { mediaType?: string; manifests?: Descriptor[] };
+    const topType = topDesc.mediaType ?? topParsed.mediaType ?? "application/vnd.oci.image.manifest.v1+json";
+    if (INDEX_TYPES.has(topType)) {
+      for (const child of topParsed.manifests ?? []) image(child, readBlob(child.digest));
+    } else {
+      image({ ...topDesc, mediaType: topType }, topBytes);
+    }
+    return { top: { ...topDesc, mediaType: topType, bytes: topBytes }, manifests, configDigests, readBlob, cleanup };
+  } catch (err) {
+    cleanup();
+    if (err instanceof SyntaxError) throw new PublishTargetError("publish-oci-not-a-layout", `${abs} holds a manifest or index.json that is not JSON`);
+    throw err;
+  }
+}
+
+/** The credential for `repo`: the declared variables, else the docker config's `auths` entry. */
+function ociCredential(decl: OciPublishDeclaration, repo: OciRepository, ctx: PublishContext): { username: string; password: Credential } | null {
+  const password = readCredential(ctx.env, [decl.passwordEnv ?? "OCI_PASSWORD"], ctx.redactor);
+  if (password) {
+    const user = ctx.env[decl.usernameEnv ?? "OCI_USERNAME"];
+    return { username: user && user !== "" ? user : "oauth2", password };
+  }
+  const dir = ctx.env.DOCKER_CONFIG ?? (ctx.env.HOME ? join(ctx.env.HOME, ".docker") : null);
+  if (!dir || !existsSync(join(dir, "config.json"))) return null;
+  try {
+    const conf = JSON.parse(readFileSync(join(dir, "config.json"), "utf-8")) as { auths?: Record<string, { auth?: string }> };
+    const keys = repo.host === "docker.io" ? ["https://index.docker.io/v1/", "docker.io", "index.docker.io"] : [repo.host, `https://${repo.host}`];
+    for (const k of keys) {
+      const auth = conf.auths?.[k]?.auth;
+      if (!auth) continue;
+      ctx.redactor.add(auth);
+      const decoded = Buffer.from(auth, "base64").toString("utf-8");
+      const at = decoded.indexOf(":");
+      if (at < 0) continue;
+      const value = decoded.slice(at + 1);
+      ctx.redactor.add(value);
+      return { username: decoded.slice(0, at), password: { value, from: "docker config" } };
+    }
+  } catch {
+    // An unreadable docker config gives no credential.
+  }
+  return null;
+}
+
+/** A registry client that answers the registry's auth challenge once and keeps the token. */
+class Registry {
+  private auth: string | null = null;
+  constructor(
+    private readonly repo: OciRepository,
+    private readonly fetch: PublishFetch,
+    private readonly cred: { username: string; password: Credential } | null,
+    private readonly ctx: PublishContext,
+  ) {}
+
+  private fail(what: string, status: number, body: string): never {
+    throw new PublishTargetError("publish-oci-failed", this.ctx.redactor.redact(`${what} at ${this.repo.base} answered ${status}${body ? `: ${body.slice(0, 300)}` : ""}`));
+  }
+
+  async request(method: string, path: string, headers: Record<string, string> = {}, body?: Uint8Array): Promise<Awaited<ReturnType<PublishFetch>>> {
+    const url = /^https?:\/\//.test(path) ? path : `${this.repo.base}${path}`;
+    const send = () => this.fetch(url, { method, headers: { ...headers, ...(this.auth ? { authorization: this.auth } : {}) }, ...(body ? { body } : {}) });
+    let res = await send();
+    if (res.status === 401 && this.auth === null) {
+      await this.answerChallenge(res.headers.get("www-authenticate") ?? "");
+      res = await send();
+    }
+    return res;
+  }
+
+  private async answerChallenge(header: string): Promise<void> {
+    const basic = this.cred ? `Basic ${Buffer.from(`${this.cred.username}:${this.cred.password.value}`).toString("base64")}` : null;
+    if (basic) this.ctx.redactor.add(basic.slice(6));
+    if (/^basic/i.test(header)) {
+      if (!basic) throw new PublishTargetError("publish-credentials-missing", `${this.repo.base} asks for credentials, and none are set`, "Set OCI_USERNAME and OCI_PASSWORD, or the variables usernameEnv and passwordEnv name, or docker login.");
+      this.auth = basic;
+      return;
+    }
+    if (!/^bearer/i.test(header)) this.fail("the registry", 401, "with no challenge chant can answer");
+    const params = Object.fromEntries([...header.matchAll(/(\w+)="([^"]*)"/g)].map((m) => [m[1]!.toLowerCase(), m[2]!]));
+    if (!params.realm) this.fail("the registry", 401, "with a Bearer challenge that names no realm");
+    const u = new URL(params.realm);
+    if (params.service) u.searchParams.set("service", params.service);
+    u.searchParams.set("scope", `repository:${this.repo.name}:pull,push`);
+    const res = await this.fetch(u.toString(), { method: "GET", headers: basic ? { authorization: basic } : {} });
+    const text = await res.text();
+    if (!res.ok) this.fail("the token service", res.status, text);
+    const json = JSON.parse(text) as { token?: string; access_token?: string };
+    const token = json.token ?? json.access_token;
+    if (!token) this.fail("the token service", res.status, "with no token");
+    this.ctx.redactor.add(token);
+    this.auth = `Bearer ${token}`;
+  }
+
+  /** Upload a blob unless the registry holds it. True when it was uploaded. */
+  async pushBlob(digest: string, bytes: () => Uint8Array): Promise<boolean> {
+    const head = await this.request("HEAD", `/v2/${this.repo.name}/blobs/${digest}`);
+    if (head.status === 200) return false;
+    const start = await this.request("POST", `/v2/${this.repo.name}/blobs/uploads/`, { "content-length": "0" });
+    if (start.status !== 202) this.fail(`starting an upload of ${digest}`, start.status, await start.text());
+    const location = start.headers.get("location");
+    if (!location) this.fail(`starting an upload of ${digest}`, start.status, "with no Location");
+    const abs = /^https?:\/\//.test(location) ? location : `${this.repo.base}${location.startsWith("/") ? "" : "/"}${location}`;
+    const put = `${abs}${abs.includes("?") ? "&" : "?"}digest=${encodeURIComponent(digest)}`;
+    const data = bytes();
+    const done = await this.request("PUT", put, { "content-type": "application/octet-stream", "content-length": String(data.byteLength) }, data);
+    if (done.status !== 201) this.fail(`uploading ${digest}`, done.status, await done.text());
+    return true;
+  }
+
+  /** Whether the registry holds the manifest `digest`. */
+  async hasManifest(digest: string, mediaType: string): Promise<boolean> {
+    const res = await this.request("HEAD", `/v2/${this.repo.name}/manifests/${digest}`, { accept: mediaType });
+    return res.status === 200;
+  }
+
+  async putManifest(ref: string, mediaType: string, bytes: Uint8Array): Promise<void> {
+    const res = await this.request("PUT", `/v2/${this.repo.name}/manifests/${ref}`, { "content-type": mediaType }, bytes);
+    if (res.status !== 201) this.fail(`putting manifest ${ref}`, res.status, await res.text());
+  }
+}
+
+/** The media type of the empty config an artifact manifest names. */
+const EMPTY_CONFIG = { mediaType: "application/vnd.oci.empty.v1+json", bytes: new Uint8Array(Buffer.from("{}")) };
+const IMAGE_MANIFEST = "application/vnd.oci.image.manifest.v1+json";
+
+/** One referrer of the image: an attached file and the artifact manifest that names the image as its subject. */
+interface Referrer {
+  attachment: Attachment;
+  manifest: Uint8Array;
+  digest: string;
+}
+
+/**
+ * The artifact manifest that attaches `a` to the image `subject` (OCI image
+ * spec 1.1): `artifactType` is the file's media type, the config is the empty
+ * descriptor, the one layer is the file, and `subject` is the image.
+ */
+export function referrerManifest(a: Attachment, subject: { mediaType: string; digest: string; size: number }): Uint8Array {
+  const manifest = {
+    schemaVersion: 2,
+    mediaType: IMAGE_MANIFEST,
+    artifactType: a.mediaType,
+    config: { mediaType: EMPTY_CONFIG.mediaType, digest: bytesDigest(EMPTY_CONFIG.bytes), size: EMPTY_CONFIG.bytes.byteLength },
+    layers: [{ mediaType: a.mediaType, digest: a.digest, size: a.bytes.byteLength, annotations: { "org.opencontainers.image.title": a.name } }],
+    subject,
+    annotations: { "org.opencontainers.image.title": a.name },
+  };
+  return new Uint8Array(Buffer.from(JSON.stringify(manifest)));
+}
+
+/** The tags to point at the digest: the context's tag when set, else the declared ones with `{label}` filled in. */
+export function ociTags(decl: OciPublishDeclaration, ctx: Pick<PublishContext, "tag" | "label">): string[] {
+  if (ctx.tag) return [ctx.tag];
+  const declared = decl.tags ?? (ctx.label ? ["{label}"] : []);
+  return declared.filter((t) => ctx.label !== null || !t.includes("{label}")).map((t) => t.split("{label}").join(ctx.label ?? ""));
+}
+
+export function ociTarget(decl: OciPublishDeclaration, deps: PublishDeps): PublishTarget {
+  const repo = parseRepository(decl.repository);
+  const fetchImpl: PublishFetch = deps.fetch ?? ((url, init) => fetch(url, init as RequestInit));
+  const inspect = (ctx: PublishContext) => {
+    const abs = memberFile(ctx.cwd, decl.image);
+    const layout = readLayout(abs);
+    try {
+      const identities = [layout.top.digest, ...layout.configDigests, ...(isDir(abs) ? [] : [fileDigest(abs)])];
+      checkReleaseDigest(ctx.release, "image", ctx.cwd, decl.image, identities);
+    } catch (err) {
+      layout.cleanup();
+      throw err;
+    }
+    return layout;
+  };
+  const item = (ctx: PublishContext, digest: string): PublishItem => {
+    const tags = ociTags(decl, ctx);
+    return {
+      name: `${decl.image}${tags.length > 0 ? ` (tag${tags.length === 1 ? "" : "s"} ${tags.join(", ")})` : ""}`,
+      destination: `${decl.repository}@${digest}`,
+      digest,
+    };
+  };
+  /** The SBOM and the provenance statement, each with the artifact manifest that refers to the image. */
+  const referrers = (ctx: PublishContext, layout: LayoutImage): Referrer[] => {
+    const subject = { mediaType: layout.top.mediaType, digest: layout.top.digest, size: layout.top.bytes.byteLength };
+    const files = [
+      memberSbom(ctx, decl.sbom, `${decl.repository}@${layout.top.digest}`, `oci ${decl.repository}`),
+      releaseProvenance(ctx, [{ name: `${decl.repository}@${layout.top.digest}`, digest: layout.top.digest }]),
+    ].filter((a): a is Attachment => a !== null);
+    return files.map((attachment) => {
+      const manifest = referrerManifest(attachment, subject);
+      return { attachment, manifest, digest: bytesDigest(manifest) };
+    });
+  };
+  const referrerItem = (r: Referrer): PublishItem => ({ name: r.attachment.name, destination: `${decl.repository}@${r.digest}, a referrer of the image`, digest: r.digest, attachment: r.attachment.kind });
+  const connect = (ctx: PublishContext) => {
+    const cred = ociCredential(decl, repo, ctx);
+    return { cred, registry: new Registry(repo, fetchImpl, cred, ctx) };
+  };
+  return {
+    kind: "oci",
+    name: `oci ${decl.repository}`,
+    destination: decl.repository,
+    credentialEnv: [decl.passwordEnv ?? "OCI_PASSWORD"],
+    key: publishTargetKey(decl),
+    async plan(ctx) {
+      const layout = inspect(ctx);
+      try {
+        return [item(ctx, layout.top.digest), ...referrers(ctx, layout).map(referrerItem)];
+      } finally {
+        layout.cleanup();
+      }
+    },
+    async stage(ctx) {
+      const layout = inspect(ctx);
+      try {
+        const attached = referrers(ctx, layout);
+        const { cred, registry } = connect(ctx);
+        const staged: PublishItem = { ...item(ctx, layout.top.digest), name: decl.image };
+        const items: PublishItem[] = [];
+        if (await registry.hasManifest(layout.top.digest, layout.top.mediaType)) {
+          ctx.log(`${decl.repository} already holds ${layout.top.digest}; the image is not pushed again`);
+          items.push({ ...staged, present: true });
+        } else {
+          ctx.log(`pushing ${decl.image} to ${decl.repository} by digest ${layout.top.digest}, ${cred ? `with credentials from ${cred.password.from}` : "anonymously"}; no tag moves yet`);
+          let uploaded = 0;
+          for (const m of layout.manifests) {
+            for (const b of m.blobs) if (await registry.pushBlob(b.digest, () => layout.readBlob(b.digest))) uploaded++;
+            await registry.putManifest(m.digest, m.mediaType, m.bytes);
+          }
+          if (INDEX_TYPES.has(layout.top.mediaType)) await registry.putManifest(layout.top.digest, layout.top.mediaType, layout.top.bytes);
+          ctx.log(`  ${uploaded} blob(s) uploaded`);
+          items.push(staged);
+        }
+        // #4049: the SBOM and the provenance statement, as referrers of the image, by digest.
+        for (const r of attached) {
+          if (await registry.hasManifest(r.digest, IMAGE_MANIFEST)) {
+            items.push({ ...referrerItem(r), present: true });
+            continue;
+          }
+          ctx.log(`attaching ${r.attachment.name} to ${layout.top.digest} as referrer ${r.digest}`);
+          await registry.pushBlob(bytesDigest(EMPTY_CONFIG.bytes), () => EMPTY_CONFIG.bytes);
+          await registry.pushBlob(r.attachment.digest, () => r.attachment.bytes);
+          await registry.putManifest(r.digest, IMAGE_MANIFEST, r.manifest);
+          items.push(referrerItem(r));
+        }
+        return { target: this.name, destination: this.destination, items, state: {} };
+      } finally {
+        layout.cleanup();
+      }
+    },
+    async reveal(ctx) {
+      const layout = inspect(ctx);
+      try {
+        const { registry } = connect(ctx);
+        const tags = ociTags(decl, ctx);
+        for (const t of tags) await registry.putManifest(t, layout.top.mediaType, layout.top.bytes);
+        ctx.log(tags.length > 0 ? `tagged ${layout.top.digest} ${tags.join(", ")}` : `no tag to point at ${layout.top.digest}`);
+        return { target: this.name, destination: this.destination, items: [item(ctx, layout.top.digest), ...referrers(ctx, layout).map(referrerItem)] };
+      } finally {
+        layout.cleanup();
+      }
+    },
+  };
+}