@caelo-cms/provisioning 0.10.47 → 0.10.49

package/src/release-contract.ts

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Release-contract constants that every signed release manifest carries
+ * (epic #696). The infrastructure contract number itself lives in
+ * infra-contract.ts (shared with the upgrade split's `needsConverge`);
+ * this module says which files can change it and the min-from version. They tell an upgrader, without running any code from the
+ * new release, whether the release can be installed as an app-roll or
+ * needs the operator's own identity.
+ *
+ * The admin's upgrader job (Phase 2) only rolls images: it holds no IAM
+ * write, no secret create, no resource create. Anything a release needs
+ * beyond "new image digests + expand-only migrations" must therefore be
+ * declared here, so the upgrader refuses it and sends the Owner to the
+ * "Run in Cloud Shell" path instead of half-applying it.
+ */
+
+/**
+ * Oldest installed version a release can be applied to directly. An
+ * install below it has to step through an intermediate release first.
+ *
+ * Raise it when a release depends on a migration or runtime change that
+ * an older install has not been through (the expand/contract rule only
+ * guarantees N-1 → N).
+ */
+export const RELEASE_MIN_FROM_VERSION = "0.10.0";
+
+/**
+ * Repo-relative paths (a trailing `/` means "everything below") whose
+ * changes can alter the infrastructure contract. Tests and READMEs under
+ * them are ignored — see {@link isInfraContractPath}.
+ */
+export const INFRA_CONTRACT_PATHS: readonly string[] = [
+  "packages/provisioning/stacks/",
+  "packages/provisioning/src/stack-contract.ts",
+  "packages/provisioning/src/stack-converge.ts",
+  "packages/provisioning/src/runtime-secrets.ts",
+  "packages/provisioning/src/operator-access.ts",
+  "packages/provisioning/src/gcp-names.ts",
+  // Upgrade-time mutators outside stack-converge: the converge half of the
+  // upgrade (it decides which ensure* steps run), the MCP IAP service
+  // account + bindings, the default firewall policy.
+  "packages/provisioning/src/upgrade/converge.ts",
+  "packages/provisioning/src/mcp-iap.ts",
+  "packages/provisioning/src/default-firewall.ts",
+];
+
+/**
+ * Whether a changed repo-relative path can alter the infrastructure
+ * contract.
+ *
+ * @param path - a path as `git diff --name-only` prints it.
+ */
+export function isInfraContractPath(path: string): boolean {
+  if (/\.test\.ts$/.test(path) || /(^|\/)README\.md$/.test(path)) return false;
+  return INFRA_CONTRACT_PATHS.some((p) => (p.endsWith("/") ? path.startsWith(p) : path === p));
+}

package/src/release-manifest.test.ts

@@ -0,0 +1,300 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { INFRA_CONTRACT_VERSION } from "./infra-contract.js";
+import { isInfraContractPath } from "./release-contract.js";
+import {
+  assessAutoInstall,
+  channelForVersion,
+  compareImageDigests,
+  compareSemver,
+  fetchVerifiedReleaseManifest,
+  RELEASE_MANIFEST_ARTIFACT_TYPE,
+  RELEASE_MANIFEST_MEDIA_TYPE,
+  RELEASE_OIDC_ISSUER,
+  type ReleaseManifest,
+  type ReleaseManifestDeps,
+  ReleaseManifestSchema,
+  releaseManifestSignerIdentity,
+  SIGSTORE_BUNDLE_MEDIA_TYPE,
+} from "./release-manifest.js";
+
+const d = (c: string) => `sha256:${c.repeat(64)}`;
+
+const MANIFEST: ReleaseManifest = {
+  manifestVersion: 1,
+  version: "0.11.0",
+  channel: "stable",
+  digests: { admin: d("a"), gateway: d("b"), ops: d("c") },
+  minFromVersion: "0.10.0",
+  infraContractVersion: 1,
+  migrations: {
+    contract: false,
+    head: "0262_tool_approval_branch",
+    lastContractVersion: "0.10.42",
+  },
+  security: false,
+  advisories: [],
+};
+
+const sha = (b: Uint8Array) => `sha256:${createHash("sha256").update(b).digest("hex")}`;
+const enc = (s: string) => new TextEncoder().encode(s);
+
+interface Fixture {
+  manifestBody?: string;
+  bundleBody?: string;
+  artifactType?: string;
+  /** Serve this instead of the real manifest blob (digest stays the original). */
+  tamperManifestBlob?: string;
+  manifestStatus?: number;
+  cosignExit?: number;
+  dropBundleLayer?: boolean;
+}
+
+/** An in-memory OCI registry + cosign stub. Records every cosign call. */
+function fixture(f: Fixture = {}) {
+  const manifestBytes = enc(f.manifestBody ?? JSON.stringify(MANIFEST));
+  const bundleBytes = enc(
+    f.bundleBody ?? '{"mediaType":"application/vnd.dev.sigstore.bundle.v0.3+json"}',
+  );
+  const layers = [
+    { mediaType: RELEASE_MANIFEST_MEDIA_TYPE, digest: sha(manifestBytes) },
+    ...(f.dropBundleLayer
+      ? []
+      : [{ mediaType: SIGSTORE_BUNDLE_MEDIA_TYPE, digest: sha(bundleBytes) }]),
+  ];
+  const blobs = new Map<string, Uint8Array>([
+    [sha(manifestBytes), f.tamperManifestBlob ? enc(f.tamperManifestBlob) : manifestBytes],
+    [sha(bundleBytes), bundleBytes],
+  ]);
+  const urls: string[] = [];
+  const cosignCalls: (readonly string[])[] = [];
+  const deps: ReleaseManifestDeps = {
+    registry: "registry.test",
+    repository: "caelo/release-manifest",
+    fetch: async (url) => {
+      urls.push(url);
+      const m = /\/v2\/caelo\/release-manifest\/(manifests|blobs)\/(.+)$/.exec(url);
+      if (!m) return new Response("", { status: 404 });
+      if (m[1] === "manifests") {
+        if (f.manifestStatus) return new Response("", { status: f.manifestStatus });
+        return Response.json({
+          schemaVersion: 2,
+          mediaType: "application/vnd.oci.image.manifest.v1+json",
+          artifactType: f.artifactType ?? RELEASE_MANIFEST_ARTIFACT_TYPE,
+          layers,
+        });
+      }
+      const blob = blobs.get(m[2] ?? "");
+      return blob ? new Response(blob) : new Response("", { status: 404 });
+    },
+    cosign: async (args) => {
+      cosignCalls.push(args);
+      return { exitCode: f.cosignExit ?? 0, stderr: f.cosignExit ? "no matching signatures" : "" };
+    },
+  };
+  return { deps, urls, cosignCalls };
+}
+
+describe("fetchVerifiedReleaseManifest", () => {
+  it("returns the manifest when signature, schema and version check out", async () => {
+    const { deps, urls } = fixture();
+    const r = await fetchVerifiedReleaseManifest("0.11.0", deps);
+    expect(r).toEqual({ ok: true, manifest: MANIFEST });
+    expect(urls[0]).toBe("https://registry.test/v2/caelo/release-manifest/manifests/0.11.0");
+  });
+
+  it("pins cosign to release.yml on the exact tag", async () => {
+    const { deps, cosignCalls } = fixture();
+    await fetchVerifiedReleaseManifest("0.11.0", deps);
+    expect(cosignCalls).toHaveLength(1);
+    const args = cosignCalls[0] ?? [];
+    expect(args[0]).toBe("verify-blob");
+    expect(args).toContain("--bundle");
+    const id = args[args.indexOf("--certificate-identity") + 1];
+    expect(id).toBe(
+      "https://github.com/caelo-cms/caelo-cms/.github/workflows/release.yml@refs/tags/v0.11.0",
+    );
+    expect(args[args.indexOf("--certificate-oidc-issuer") + 1]).toBe(RELEASE_OIDC_ISSUER);
+    // An identity regexp would accept other refs; only the exact flag is used.
+    expect(args).not.toContain("--certificate-identity-regexp");
+  });
+
+  it("refuses when cosign rejects the signature", async () => {
+    const { deps } = fixture({ cosignExit: 1 });
+    const r = await fetchVerifiedReleaseManifest("0.11.0", deps);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error.code).toBe("signature");
+      expect(r.error.message).toContain(releaseManifestSignerIdentity("0.11.0"));
+    }
+  });
+
+  it("refuses a blob whose bytes do not match its digest, before calling cosign", async () => {
+    const tampered = JSON.stringify({ ...MANIFEST, security: true, advisories: [] });
+    const { deps, cosignCalls } = fixture({ tamperManifestBlob: tampered });
+    const r = await fetchVerifiedReleaseManifest("0.11.0", deps);
+    expect(r.ok ? null : r.error.code).toBe("blob-digest");
+    expect(cosignCalls).toHaveLength(0);
+  });
+
+  it("refuses a signed manifest that describes another version (replay)", async () => {
+    const { deps } = fixture({ manifestBody: JSON.stringify({ ...MANIFEST, version: "0.9.0" }) });
+    const r = await fetchVerifiedReleaseManifest("0.11.0", deps);
+    expect(r.ok ? null : r.error.code).toBe("version-mismatch");
+  });
+
+  it("refuses a manifest that fails the schema", async () => {
+    const bad = { ...MANIFEST, digests: { admin: "sha256:nope", gateway: d("b"), ops: d("c") } };
+    const { deps } = fixture({ manifestBody: JSON.stringify(bad) });
+    const r = await fetchVerifiedReleaseManifest("0.11.0", deps);
+    expect(r.ok ? null : r.error.code).toBe("schema");
+  });
+
+  it("refuses an artifact of the wrong type or without the bundle layer", async () => {
+    const wrongType = await fetchVerifiedReleaseManifest(
+      "0.11.0",
+      fixture({ artifactType: "application/vnd.oci.image.config.v1+json" }).deps,
+    );
+    expect(wrongType.ok ? null : wrongType.error.code).toBe("artifact-shape");
+    const noBundle = await fetchVerifiedReleaseManifest(
+      "0.11.0",
+      fixture({ dropBundleLayer: true }).deps,
+    );
+    expect(noBundle.ok ? null : noBundle.error.code).toBe("artifact-shape");
+  });
+
+  it("reports a missing manifest as a registry error with a next step", async () => {
+    const r = await fetchVerifiedReleaseManifest("0.11.0", fixture({ manifestStatus: 404 }).deps);
+    expect(r.ok ? null : r.error.code).toBe("registry");
+    expect(r.ok ? "" : r.error.message).toContain("HTTP 404");
+  });
+
+  it("rejects a non-SemVer version without touching the network", async () => {
+    const { deps, urls } = fixture();
+    const r = await fetchVerifiedReleaseManifest("v0.11.0", deps);
+    expect(r.ok ? null : r.error.code).toBe("schema");
+    expect(urls).toHaveLength(0);
+  });
+});
+
+describe("ReleaseManifestSchema", () => {
+  it("accepts the canonical fixture and rejects a non-GHSA advisory", () => {
+    expect(ReleaseManifestSchema.safeParse(MANIFEST).success).toBe(true);
+    const cve = { ...MANIFEST, security: true, advisories: ["CVE-2026-1234"] };
+    expect(ReleaseManifestSchema.safeParse(cve).success).toBe(false);
+    const ghsa = { ...MANIFEST, security: true, advisories: ["GHSA-2c2m-4x8q-wx9f"] };
+    expect(ReleaseManifestSchema.safeParse(ghsa).success).toBe(true);
+  });
+});
+
+describe("compareImageDigests", () => {
+  it("is empty when every resolved digest matches", () => {
+    expect(compareImageDigests(MANIFEST, { admin: d("a"), gateway: d("b"), ops: d("c") })).toEqual(
+      [],
+    );
+  });
+
+  it("names each mismatching or unresolved image, ignores absent ones", () => {
+    expect(compareImageDigests(MANIFEST, { admin: d("f"), gateway: null })).toEqual([
+      { image: "admin", expected: d("a"), actual: d("f") },
+      { image: "gateway", expected: d("b"), actual: null },
+    ]);
+  });
+});
+
+describe("assessAutoInstall", () => {
+  const installed = { version: "0.10.43", infraContractVersion: 1 };
+
+  it("auto-installs an expand-only release with the same infra contract", () => {
+    expect(assessAutoInstall(MANIFEST, installed)).toEqual({
+      mode: "auto",
+      kind: "normal",
+      reasons: [],
+    });
+    const advisories = ["GHSA-abcd-efgh-jkmp"];
+    expect(assessAutoInstall({ ...MANIFEST, security: true, advisories }, installed).kind).toBe(
+      "security",
+    );
+  });
+
+  it("counts security only with a published advisory behind it (#696 decision 2)", () => {
+    expect(assessAutoInstall({ ...MANIFEST, security: true }, installed).kind).toBe("normal");
+  });
+
+  it("downgrades a security release with contract migrations to manual", () => {
+    const m = {
+      ...MANIFEST,
+      security: true,
+      migrations: { contract: true, head: "x", lastContractVersion: "0.11.0" },
+    };
+    const a = assessAutoInstall(m, installed);
+    expect(a.mode).toBe("manual");
+    expect(a.kind).toBe("normal");
+  });
+
+  it("makes skipping a contract release manual, but not upgrading past it from after it", () => {
+    const m = {
+      ...MANIFEST,
+      migrations: { ...MANIFEST.migrations, lastContractVersion: "0.10.50" },
+    };
+    const skipped = assessAutoInstall(m, installed);
+    expect(skipped.mode).toBe("manual");
+    expect(skipped.reasons[0]).toContain("skips v0.10.50");
+    expect(assessAutoInstall(m, { ...installed, version: "0.10.50" }).mode).toBe("auto");
+  });
+
+  it("downgrades an infra contract bump to manual, also when skipped releases carried it", () => {
+    const a = assessAutoInstall(
+      { ...MANIFEST, security: true, infraContractVersion: 3 },
+      installed,
+    );
+    expect(a.mode).toBe("manual");
+    expect(a.reasons[0]).toContain("1 → 3");
+  });
+
+  it("refuses downgrades, re-installs and versions below minFromVersion", () => {
+    expect(assessAutoInstall(MANIFEST, { ...installed, version: "0.11.0" }).mode).toBe("refused");
+    expect(assessAutoInstall(MANIFEST, { ...installed, version: "0.12.0" }).mode).toBe("refused");
+    expect(assessAutoInstall(MANIFEST, { ...installed, version: "0.9.9" }).mode).toBe("refused");
+  });
+});
+
+describe("compareSemver / channelForVersion", () => {
+  it("orders releases and pre-releases per SemVer", () => {
+    expect(compareSemver("0.10.43", "0.10.9")).toBeGreaterThan(0);
+    expect(compareSemver("0.11.0-rc.1", "0.11.0")).toBeLessThan(0);
+    expect(compareSemver("0.11.0-rc.2", "0.11.0-rc.10")).toBeLessThan(0);
+    expect(compareSemver("0.11.0-beta.1", "0.11.0-rc.1")).toBeLessThan(0);
+    expect(compareSemver("1.0.0", "1.0.0")).toBe(0);
+    expect(() => compareSemver("v1.0.0", "1.0.0")).toThrow();
+  });
+
+  it("maps versions to channels", () => {
+    expect(channelForVersion("0.11.0")).toBe("stable");
+    expect(channelForVersion("0.11.0-rc.1")).toBe("rc");
+    expect(channelForVersion("0.11.0-nightly.1")).toBeNull();
+  });
+});
+
+describe("release-contract", () => {
+  it("watches the stacks and converge sources, not their tests", () => {
+    expect(isInfraContractPath("packages/provisioning/stacks/gcp/index.ts")).toBe(true);
+    expect(isInfraContractPath("packages/provisioning/src/stack-converge.ts")).toBe(true);
+    expect(isInfraContractPath("packages/provisioning/src/upgrade/converge.ts")).toBe(true);
+    expect(isInfraContractPath("packages/provisioning/src/stack-converge.test.ts")).toBe(false);
+    expect(isInfraContractPath("packages/provisioning/stacks/gcp/README.md")).toBe(false);
+    expect(isInfraContractPath("packages/provisioning/src/cli.ts")).toBe(false);
+  });
+
+  it("keeps INFRA_CONTRACT_VERSION a literal the release scripts can read from a past tag", () => {
+    // scripts/release-manifest.ts reads the previous tag's value with a
+    // regex over `git show <tag>:<file>`, so it must stay a plain literal.
+    const src = readFileSync(new URL("./infra-contract.ts", import.meta.url), "utf8");
+    expect(src).toMatch(
+      new RegExp(`export const INFRA_CONTRACT_VERSION = ${INFRA_CONTRACT_VERSION};`),
+    );
+  });
+});

package/src/release-manifest.ts

@@ -0,0 +1,310 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The signed release manifest (epic #696): one JSON document per release
+ * that names the exact image digests plus the facts an upgrader needs to
+ * decide whether it may install the release on its own.
+ *
+ * Trust model. `release.yml` generates the manifest on the release tag,
+ * signs it with `cosign sign-blob` (keyless, the workflow's GitHub OIDC
+ * identity) and pushes it as an OCI artifact holding two layers — the
+ * manifest and its Sigstore bundle. Verification pins the signer to
+ * `release.yml` running on the tag `v<version>` of caelo-cms/caelo-cms,
+ * so neither a compromised admin nor a registry mirror can mint, alter or
+ * replay a manifest: changing a digest, flipping `security`, or serving
+ * v0.9's manifest as v0.10's all fail the signature or the version check.
+ * The signature rides inside the artifact (not as an OCI referrer), so
+ * any plain registry copy keeps it — the failure mode that left mirrored
+ * images unsigned (see release-images.yml, "oras copy -r") cannot apply.
+ *
+ * Errors are values: every failure carries a code plus a message that
+ * says what to check next.
+ */
+
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  fetchReleaseArtifact,
+  isSecurityRelease,
+  parseReleaseManifest,
+  RELEASE_CHANNELS,
+  RELEASE_IMAGES,
+  type ReleaseChannel,
+  type ReleaseImage,
+  type ReleaseManifest,
+} from "@caelo-cms/shared";
+import { RELEASE_OIDC_ISSUER, RELEASE_WORKFLOWS_URL } from "./upgrade/release-images.js";
+
+// The manifest's shape and location live in @caelo-cms/shared (the admin's
+// auto-update scheduler reads them too); re-exported so this module stays
+// the CLI's one import for release manifests.
+export {
+  RELEASE_CHANNELS,
+  RELEASE_IMAGES,
+  RELEASE_MANIFEST_ARTIFACT_TYPE,
+  RELEASE_MANIFEST_MEDIA_TYPE,
+  RELEASE_MANIFEST_REGISTRY,
+  RELEASE_MANIFEST_REPOSITORY,
+  type ReleaseChannel,
+  type ReleaseImage,
+  type ReleaseManifest,
+  ReleaseManifestSchema,
+  SIGSTORE_BUNDLE_MEDIA_TYPE,
+} from "@caelo-cms/shared";
+
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/;
+
+// The signer constants are shared with the image verification (one source).
+export { RELEASE_OIDC_ISSUER };
+
+/**
+ * The only identity allowed to sign the manifest of `version`: release.yml
+ * of caelo-cms/caelo-cms running on that exact tag. Exact, not a regex —
+ * a manifest signed on another ref (a branch, another tag) is refused.
+ */
+export function releaseManifestSignerIdentity(version: string): string {
+  return `${RELEASE_WORKFLOWS_URL}/release.yml@refs/tags/v${version}`;
+}
+
+/**
+ * Compare two SemVer strings: negative when `a < b`, 0 when equal,
+ * positive when `a > b`. A pre-release sorts below its release; two
+ * pre-release tags compare by SemVer identifier rules.
+ *
+ * @throws Error when either argument is not SemVer.
+ */
+export function compareSemver(a: string, b: string): number {
+  const ma = SEMVER.exec(a);
+  const mb = SEMVER.exec(b);
+  if (!ma || !mb) throw new Error(`not a SemVer version: ${ma ? b : a}`);
+  for (let i = 1; i <= 3; i++) {
+    const d = Number(ma[i]) - Number(mb[i]);
+    if (d !== 0) return d;
+  }
+  const pa = ma[4];
+  const pb = mb[4];
+  if (pa === undefined || pb === undefined) {
+    return pa === pb ? 0 : pa === undefined ? 1 : -1;
+  }
+  const ia = pa.split(".");
+  const ib = pb.split(".");
+  for (let i = 0; i < Math.max(ia.length, ib.length); i++) {
+    const x = ia[i];
+    const y = ib[i];
+    if (x === undefined) return -1;
+    if (y === undefined) return 1;
+    const xn = /^\d+$/.test(x);
+    const yn = /^\d+$/.test(y);
+    if (xn && yn && Number(x) !== Number(y)) return Number(x) - Number(y);
+    if (xn !== yn) return xn ? -1 : 1;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * The channel a version ships on.
+ *
+ * @returns null for a pre-release whose identifier names no known channel.
+ */
+export function channelForVersion(version: string): ReleaseChannel | null {
+  const m = SEMVER.exec(version);
+  if (!m) return null;
+  if (m[4] === undefined) return "stable";
+  const id = m[4].split(".")[0];
+  return (RELEASE_CHANNELS as readonly string[]).includes(id ?? "") ? (id as ReleaseChannel) : null;
+}
+
+/** Why fetching or verifying a manifest failed. */
+export type ReleaseManifestErrorCode =
+  | "registry"
+  | "artifact-shape"
+  | "blob-digest"
+  | "signature"
+  | "schema"
+  | "version-mismatch";
+
+export interface ReleaseManifestError {
+  readonly code: ReleaseManifestErrorCode;
+  readonly message: string;
+}
+
+export type ReleaseManifestResult =
+  | { readonly ok: true; readonly manifest: ReleaseManifest }
+  | { readonly ok: false; readonly error: ReleaseManifestError };
+
+/** Side effects of {@link fetchVerifiedReleaseManifest}, injectable for tests. */
+export interface ReleaseManifestDeps {
+  readonly fetch: (url: string, init?: RequestInit) => Promise<Response>;
+  /** Runs `cosign` with `args`; resolves with its exit code + stderr. */
+  readonly cosign: (args: readonly string[]) => Promise<{ exitCode: number; stderr: string }>;
+  /** Registry host + repository; defaults to the fixed public mirror. */
+  readonly registry?: string;
+  readonly repository?: string;
+}
+
+/** `cosign` from PATH. Missing binary → exit code 127 with a hint. */
+async function runCosign(args: readonly string[]): Promise<{ exitCode: number; stderr: string }> {
+  try {
+    const proc = Bun.spawn(["cosign", ...args], { stdout: "ignore", stderr: "pipe" });
+    const stderr = await new Response(proc.stderr).text();
+    return { exitCode: await proc.exited, stderr };
+  } catch (e) {
+    return {
+      exitCode: 127,
+      stderr: `cosign could not be started (${e instanceof Error ? e.message : String(e)}) — install cosign (it ships in the caelo-ops image)`,
+    };
+  }
+}
+
+const defaultDeps: ReleaseManifestDeps = {
+  fetch: (url, init) => fetch(url, init),
+  cosign: runCosign,
+};
+
+function fail(code: ReleaseManifestErrorCode, message: string): ReleaseManifestResult {
+  return { ok: false, error: { code, message } };
+}
+
+/**
+ * Fetch the manifest of `version` from the fixed registry, verify its
+ * Sigstore bundle against the release workflow identity for that exact
+ * tag, schema-validate it, and check it describes `version`.
+ *
+ * @param version - SemVer without a leading `v`.
+ * @param deps - injected fetch + cosign runner (tests); defaults to the real ones.
+ */
+export async function fetchVerifiedReleaseManifest(
+  version: string,
+  deps: ReleaseManifestDeps = defaultDeps,
+): Promise<ReleaseManifestResult> {
+  if (!SEMVER.test(version)) return fail("schema", `"${version}" is not a SemVer version`);
+  const artifact = await fetchReleaseArtifact(version, deps);
+  if (!artifact.ok) return { ok: false, error: artifact.error };
+
+  // cosign verifies files, so the exact bytes go to a private temp dir.
+  const dir = await mkdtemp(join(tmpdir(), "caelo-release-manifest-"));
+  try {
+    const manifestPath = join(dir, "release-manifest.json");
+    const bundlePath = join(dir, "release-manifest.json.sigstore.json");
+    await writeFile(manifestPath, artifact.manifestBytes, { mode: 0o600 });
+    await writeFile(bundlePath, artifact.bundleBytes, { mode: 0o600 });
+    const verify = await deps.cosign([
+      "verify-blob",
+      "--bundle",
+      bundlePath,
+      "--certificate-identity",
+      releaseManifestSignerIdentity(version),
+      "--certificate-oidc-issuer",
+      RELEASE_OIDC_ISSUER,
+      manifestPath,
+    ]);
+    if (verify.exitCode !== 0) {
+      return fail(
+        "signature",
+        `the manifest of v${version} is not signed by ${releaseManifestSignerIdentity(version)} — refuse to install. cosign: ${verify.stderr.trim().slice(0, 500)}`,
+      );
+    }
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+
+  const parsed = parseReleaseManifest(artifact.manifestBytes, version);
+  if (!parsed.ok) return fail(parsed.code, `signed manifest: ${parsed.message}`);
+  return { ok: true, manifest: parsed.manifest };
+}
+
+/** One image whose resolved digest differs from the manifest's. */
+export interface DigestMismatch {
+  readonly image: ReleaseImage;
+  readonly expected: string;
+  readonly actual: string | null;
+}
+
+/**
+ * Compare the digests a registry resolved for the release's tags with the
+ * signed manifest. Only images present in `resolved` are compared, except
+ * that an explicitly `null` entry (tag did not resolve) is a mismatch.
+ *
+ * @returns every mismatch; empty means the registry serves the signed images.
+ */
+export function compareImageDigests(
+  manifest: ReleaseManifest,
+  resolved: Partial<Record<ReleaseImage, string | null>>,
+): DigestMismatch[] {
+  const out: DigestMismatch[] = [];
+  for (const image of RELEASE_IMAGES) {
+    if (!(image in resolved)) continue;
+    const actual = resolved[image] ?? null;
+    if (actual !== manifest.digests[image]) {
+      out.push({ image, expected: manifest.digests[image], actual });
+    }
+  }
+  return out;
+}
+
+/** What the installed system looks like, for {@link assessAutoInstall}. */
+export interface InstalledRelease {
+  readonly version: string;
+  readonly infraContractVersion: number;
+}
+
+/**
+ * How an upgrader may treat a release:
+ *  - `auto`    — may install unattended (if the Owner's policy allows the kind).
+ *  - `manual`  — installable only with the operator's own identity
+ *                ("Run in Cloud Shell"); never unattended.
+ *  - `refused` — not installable onto this install at all.
+ */
+export type InstallMode = "auto" | "manual" | "refused";
+
+export interface InstallAssessment {
+  readonly mode: InstallMode;
+  /** `security` only when the manifest says so AND the release is otherwise auto-installable. */
+  readonly kind: "security" | "normal";
+  readonly reasons: readonly string[];
+}
+
+/**
+ * Decide whether `manifest` can be installed on `installed`, and how.
+ *
+ * A security release is NOT exempt: if it carries contract migrations
+ * (or skips a release that did) or raises the infra contract, it is `manual` like any other release — the
+ * manifest still says `security`, but `kind` drops to `normal` so an
+ * "auto-install security fixes" policy never applies it unattended.
+ */
+export function assessAutoInstall(
+  manifest: ReleaseManifest,
+  installed: InstalledRelease,
+): InstallAssessment {
+  const refused: string[] = [];
+  if (compareSemver(manifest.version, installed.version) <= 0) {
+    refused.push(`v${manifest.version} is not newer than the installed v${installed.version}`);
+  }
+  if (compareSemver(installed.version, manifest.minFromVersion) < 0) {
+    refused.push(
+      `v${manifest.version} needs at least v${manifest.minFromVersion} installed first (installed: v${installed.version})`,
+    );
+  }
+  if (refused.length > 0) return { mode: "refused", kind: "normal", reasons: refused };
+
+  const manual: string[] = [];
+  if (manifest.infraContractVersion > installed.infraContractVersion) {
+    manual.push(
+      `the release changes the infrastructure contract (${installed.infraContractVersion} → ${manifest.infraContractVersion}); it must run with the operator's own identity`,
+    );
+  }
+  const lastContract = manifest.migrations.lastContractVersion;
+  if (manifest.migrations.contract) {
+    manual.push("the release carries contract (destructive) migrations");
+  } else if (lastContract !== null && compareSemver(installed.version, lastContract) < 0) {
+    manual.push(
+      `the upgrade skips v${lastContract}, whose contract (destructive) migrations would run while v${installed.version}'s image still serves`,
+    );
+  }
+  if (manual.length > 0) return { mode: "manual", kind: "normal", reasons: manual };
+  // Security counts only with a published advisory behind it (#696
+  // decision 2); the release workflow already refuses the flag without one.
+  return { mode: "auto", kind: isSecurityRelease(manifest) ? "security" : "normal", reasons: [] };
+}