@intentius/chant 0.124.27 → 0.124.29

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();
+      }
+    },
+  };
+}

package/src/lifecycle/publish-record.ts

@@ -0,0 +1,113 @@
+/**
+ * The publish record (#4048): what `chant release publish` has staged and
+ * revealed for a release, so a publish that failed part way resumes without
+ * publishing again what already went out.
+ *
+ * One line per target per step in `_releases/publishes.jsonl` on
+ * `chant/lifecycle`, under the member's prefix like `cuts.jsonl` beside it,
+ * append-only. A target that staged gets a `staged` line with its items and
+ * the state its reveal needs (a draft release's id); one that revealed gets
+ * a `revealed` line. Each line is pushed as soon as it is written, so a CI
+ * job that resumes on a fresh checkout reads it after `fetchLifecycle`.
+ *
+ * Why a record and not only the registries: a registry says whether a version
+ * or a digest is there, which each target's stage asks so that it never sends
+ * an item twice, but not whether a draft release, a version under `next` or
+ * a pushed digest belongs to this release's publish, nor whether every
+ * target of the set has staged, which is when the reveals may start. A
+ * record that was not written or not pushed costs only speed: the stage runs
+ * again, asks the registry, and sends nothing that is there.
+ *
+ * A line holds names, destinations, digests and draft ids. It never holds a
+ * credential, and every line is redacted before it is written.
+ */
+
+import { sortedJsonReplacer } from "../utils";
+import { appendLedgerLine, readBlobFromPath, type LedgerLocation } from "./git";
+import { RELEASES_DIR } from "./release-store";
+import type { PublishedTarget, PublishItem, PublishTarget, StagedTarget } from "./release-publish";
+import type { Redactor } from "./publish-credentials";
+
+/** The file the record is appended to, under `_releases/`. */
+export const PUBLISHES_FILE = "publishes.jsonl";
+
+/** One line of `_releases/publishes.jsonl`. Version 1, written by chant 0.124.29 and newer. */
+export interface PublishRecord {
+  version: 1;
+  releaseDigest: string;
+  label: string | null;
+  /** The target's key ({@link PublishTarget.key}). */
+  target: string;
+  kind: PublishTarget["kind"];
+  /** The target's name, for a reader. */
+  name: string;
+  step: "staged" | "revealed";
+  items: PublishItem[];
+  /** What the reveal needs, on a `staged` line; `{}` on a `revealed` one. */
+  state: Record<string, string>;
+  runId: string;
+  timestamp: string;
+}
+
+/** Parse the lines of `publishes.jsonl`. A line that is not a record is counted and skipped. */
+export function parsePublishRecords(text: string | null): { records: PublishRecord[]; malformed: number } {
+  const records: PublishRecord[] = [];
+  let malformed = 0;
+  for (const line of (text ?? "").split("\n").map((l) => l.trim()).filter(Boolean)) {
+    try {
+      const r = JSON.parse(line) as Partial<PublishRecord>;
+      const ok =
+        r &&
+        r.version === 1 &&
+        typeof r.releaseDigest === "string" &&
+        typeof r.target === "string" &&
+        (r.step === "staged" || r.step === "revealed") &&
+        Array.isArray(r.items) &&
+        typeof r.timestamp === "string";
+      if (!ok) {
+        malformed++;
+        continue;
+      }
+      records.push({ ...(r as PublishRecord), state: r.state && typeof r.state === "object" ? r.state : {} });
+    } catch {
+      malformed++;
+    }
+  }
+  return { records, malformed };
+}
+
+/** Every publish record of `releaseDigest`, oldest first. */
+export async function readPublishRecords(releaseDigest: string, opts?: LedgerLocation): Promise<PublishRecord[]> {
+  const text = await readBlobFromPath(RELEASES_DIR, PUBLISHES_FILE, opts);
+  return parsePublishRecords(text).records.filter((r) => r.releaseDigest === releaseDigest);
+}
+
+/** Where each target of a release stands, by key: what it staged, and what it revealed. */
+export interface PublishProgress {
+  staged: Map<string, StagedTarget>;
+  revealed: Map<string, PublishedTarget>;
+}
+
+/** The progress `records` show. A later line for a target replaces an earlier one of the same step. */
+export function publishProgress(records: readonly PublishRecord[]): PublishProgress {
+  const staged = new Map<string, StagedTarget>();
+  const revealed = new Map<string, PublishedTarget>();
+  for (const r of records) {
+    if (r.step === "staged") staged.set(r.target, { target: r.name, destination: "", items: r.items, state: r.state });
+    else revealed.set(r.target, { target: r.name, destination: "", items: r.items });
+  }
+  return { staged, revealed };
+}
+
+/** Where `target` stands in `progress`: `revealed`, `staged`, or `none`. */
+export function progressOf(progress: PublishProgress, target: Pick<PublishTarget, "key">): "revealed" | "staged" | "none" {
+  if (progress.revealed.has(target.key)) return "revealed";
+  if (progress.staged.has(target.key)) return "staged";
+  return "none";
+}
+
+/** Append one record, redacted. Does not push. */
+export async function appendPublishRecord(record: PublishRecord, redactor: Redactor, opts?: { cwd?: string }): Promise<void> {
+  const line = redactor.redact(JSON.stringify(record, sortedJsonReplacer));
+  await appendLedgerLine(RELEASES_DIR, PUBLISHES_FILE, line, "Release publish", opts);
+}