@xemahq/repo-build-tooling 0.17.0 → 0.18.0

package/README.md

@@ -30,8 +30,8 @@ pnpm exec xema-scrub-swagger-paths dist
 | `xema-service-bootstrap [--check] [--filter <key>] [--root <dir>]` | Generates `src/generated/*.generated.ts` service and worker descriptors from the repository's `xema-biome.json` manifests; `--check` fails on drift |
 | `xema-scrub-swagger-paths <dist-dir>...` | Rewrites `@nestjs/swagger` plugin output that names a private install path, then fails the build if any leak remains (`--self-test` available) |
 | `xema-composed-image <command>` | Build-time half of a composed-process image: `members`, `filters`, `dirs`, `pins`, `index`, `load`, `stage`, `pnpm-context`, `sync-injected`, `prisma-check`, `migrate`, `coordinate`, `load-image`, `smoke-refusal`, `dockerfile` |
-| `xema-promote-image --service <name> --dev-ref <repo> --release-ref <repo> --tag <tag> --commit <sha> --main-ref <ref> --signer-repository <owner/repo> --develop-workflow <file> --release-workflow <file>... --promotion-predicate-out <path> -- <tag command>` | Publishes the develop image's digest under the release tag instead of rebuilding: `reused` (the release tag is signed by a main workflow, or is the proven develop digest), `copied` (the proven develop digest, digest-preserving; fails closed if the release digest differs) or `miss` (build it). A develop digest is proven only if its SLSA v1 provenance is signed by the develop workflow at `refs/heads/develop`, its revision is an ancestor of the main ref, and the tag command prints the same tag at that revision and at `--commit`; any failed leg is an error, never a miss. On a promotion it writes the `https://xema.dev/attestations/image-promotion/v1` predicate for the caller to attest. Writes `result`, `digest`, `source`, `revision`, `evidence`, `provenance_digest`, `promotion_predicate`, `promotion_predicate_type` to `$GITHUB_OUTPUT`. Needs `docker`, `cosign`, `git` and full history. It does not sign |
 | `xema-arm64-supplement-needed` | Decides whether an arm64 supplement is still owed at `REGISTRY/IMAGE:CONTENT_TAG` (env: `REGISTRY`, `IMAGE`, `CONTENT_TAG`, `REGISTRY_USER`, `REGISTRY_TOKEN`). `needed=false` only when the coordinate serves an index whose linux/arm64 child is proven by its own image config; any other resolvable state is `needed=true`; a 401/403/5xx or an unresolvable child is an error. Writes `needed=true\|false` to `$GITHUB_OUTPUT`. Replaces the generated `arm64-supplement-needed.mjs` copy. |
+| `xema-promote-image --service <name> --dev-ref <repo> --release-ref <repo> --tag <tag> --commit <sha> --main-ref <ref> --signer-repository <owner/repo> --develop-workflow <file> --release-workflow <file>... --promotion-predicate-out <path> -- <tag command>` | Publishes the develop image's digest under the release tag instead of rebuilding: `reused` (the release digest carries an `image-promotion/v1` attestation signed by a `--release-workflow` identity on main, with exactly one verified statement about the digest and a `ghcr.io/<owner>/dev/<name>` source; no dev-ref probe), `copied` (the proven develop digest, digest-preserving; fails closed if the release digest differs) or `miss` (build it; a reuse whose release digest has no `image-promotion/v1` attestation, a legacy image, is a miss with `reason=reuse-no-promotion` on the stdout line; a signature or identity failure, or a source outside `dev/`, is an error; a copy whose dev digest carries no SLSA v1 provenance at all, an image reused on develop from before provenance, is a miss with `reason=copy-no-develop-provenance`, while provenance that is present but fails a leg is an error). A develop digest is proven only if its SLSA v1 provenance is signed by the develop workflow at `refs/heads/develop`, its revision is an ancestor of the main ref, and the tag command prints the same tag at that revision and at `--commit`; any failed leg is an error, never a miss. On every non-miss result it writes the `https://xema.dev/attestations/image-promotion/v1` predicate for the caller to attest: a copy states the facts just proved; a reuse states this run's `release` and `promotedCommit` and carries `source` and `developProvenance` from the earlier promotion. Writes `result`, `digest`, `source`, `revision`, `evidence`, `provenance_digest`, `promotion_predicate`, `promotion_predicate_type` to `$GITHUB_OUTPUT`. Needs `docker`, `cosign` (major v2, the same as the develop attest step and xema-deploy's verify; it runs `cosign version` first and refuses any other major or an unparsable version), `git` and full history. It does not sign |
 | `xema-check-no-vendored-deps` | Fails on a `workspace:` range for a package the repository does not own |
 | `xema-check-workspace-ranges` | Fails on a `workspace:` range the local package does not satisfy |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Dev-time build tooling shared by every Xema repository. Ships as plain ESM, depending only on @xemahq/release-policy for registry access, so the published artifact is the reviewed source.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
@@ -48,6 +48,6 @@
     "test": "node src/scrub-swagger-plugin-paths.mjs --self-test && node --test src/check-workspace-range-matches-local.test.mjs && node --test src/check-no-vendored-deps.test.mjs && node --test src/readiness.test.mjs && node --test src/composed-image.test.mjs && node --test src/composed-image-coordinate-cli.test.mjs && node --test src/declaration-refusal.test.mjs && node --test src/smoke-refusal.test.mjs && node --test src/load-image.test.mjs && node --test src/composed-image-coordinate.test.mjs && node --test src/composed-image-dockerfile.test.mjs && node --test src/service-bootstrap.test.mjs && node --test src/service-bootstrap-protocols.test.mjs && node --test src/composed-image-prebuilt-dockerfile.test.mjs && node --test src/composed-image-in-image-closure.test.mjs && node --test src/composed-image-stage.test.mjs && node --test src/composed-image-pnpm-context.test.mjs && node --test src/composed-image-sync-injected.test.mjs && node --test src/composed-image-prisma-check.test.mjs && node --test src/composed-migrate.test.mjs && node --test src/promote-image.test.mjs && node --test src/arm64-supplement-needed.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:150d82fb857d535b44f1e29686108056532bc9a7827b51260c88bf3270a00eeb"
+    "sourceDigest": "sha256:aba8ae8794d81525b38c0dfcfefae6abb58b1075eebdc18d261e661c0e07b2fd"
   }
 }

package/src/promote-image-predicate.mjs

@@ -3,9 +3,9 @@
 // `xema-promote-image` proved before the copy (promote-image-provenance.mjs).
 
 import { writeFileSync } from 'node:fs';
-import { SLSA_PROVENANCE_V1 } from './promote-image-provenance.mjs';
+import { IMAGE_PROMOTION_PREDICATE_TYPE, SLSA_PROVENANCE_V1 } from './promote-image-provenance.mjs';
 
-export const IMAGE_PROMOTION_PREDICATE_TYPE = 'https://xema.dev/attestations/image-promotion/v1';
+export { IMAGE_PROMOTION_PREDICATE_TYPE };
 
 export function promotionPredicate({ releaseRef, tag, digest, source, revision, commit, provenanceDigest, signerPattern }) {
   return {
@@ -16,7 +16,12 @@ export function promotionPredicate({ releaseRef, tag, digest, source, revision,
   };
 }
 
+/** The predicate of a REUSE: this run's release and commit, with `source` and `developProvenance` carried from main's earlier promotion. */
+export function reusedPromotionPredicate({ releaseRef, tag, digest, commit, source, developProvenance }) {
+  return { release: { repository: releaseRef, tag, digest }, source, promotedCommit: commit, developProvenance };
+}
+
 /** Writes the predicate to a path that must not exist yet, so a stale file is never attested. */
-export function writePromotionPredicate(path, facts) {
-  writeFileSync(path, `${JSON.stringify(promotionPredicate(facts), null, 2)}\n`, { flag: 'wx' });
+export function writePromotionPredicate(path, predicate) {
+  writeFileSync(path, `${JSON.stringify(predicate, null, 2)}\n`, { flag: 'wx' });
 }

package/src/promote-image-provenance.mjs

@@ -1,6 +1,6 @@
 // The trust half of `xema-promote-image`: what must be PROVEN about a develop
-// digest before its bytes may be published under a release tag, and how a
-// release digest is recognised as already released by main.
+// digest before its bytes may be published under a release tag, and how a release digest main
+// already promoted is reused.
 //
 // A develop digest is promotable only on a CONJUNCTION, each leg proven from the
 // develop lane's SIGNED provenance and never from a tag:
@@ -20,7 +20,7 @@ export const GITHUB_OIDC_ISSUER = 'https://token.actions.githubusercontent.com';
 export const SLSA_PROVENANCE_V1 = 'https://slsa.dev/provenance/v1';
 const COSIGN_SLSA_V1_TYPE = 'slsaprovenance1';
 const COMMIT = /^[0-9a-f]{40}$/;
-const UNSIGNED = /no matching signatures|no signatures found/i;
+export const IMAGE_PROMOTION_PREDICATE_TYPE = 'https://xema.dev/attestations/image-promotion/v1';
 
 const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
@@ -30,22 +30,7 @@ export function workflowIdentityPattern(repository, files, branch) {
   return `^${escapeRegExp(`${GITHUB_SERVER}/${repository}/.github/workflows/`)}(?:${alternatives})${escapeRegExp(`@refs/heads/${branch}`)}$`;
 }
 
-/** True when `subject` carries a signature from one of main's release workflows; false when it carries none. */
-export function releaseSignedByMain({ subject, repository, releaseWorkflows }, run = runTool) {
-  const result = run('cosign', [
-    'verify',
-    '--certificate-identity-regexp', workflowIdentityPattern(repository, releaseWorkflows, 'main'),
-    '--certificate-oidc-issuer', GITHUB_OIDC_ISSUER,
-    subject,
-  ]);
-  if (result.error) throw new Error(`could not run cosign to verify ${subject}: ${result.error.message}`);
-  if (result.status === 0) return true;
-  const detail = describeFailure(result);
-  if (UNSIGNED.test(detail)) return false;
-  throw new Error(`verifying main's signature on ${subject} failed (not a "no matching signatures"): ${detail}`);
-}
-
-function readStatements(stdout, subject) {
+function readStatements(stdout, subject, label) {
   const byDigest = new Map();
   for (const line of stdout.split('\n').map((text) => text.trim()).filter(Boolean)) {
     let payload;
@@ -54,41 +39,116 @@ function readStatements(stdout, subject) {
       payload = Buffer.from(JSON.parse(line).payload, 'base64');
       statement = JSON.parse(payload.toString('utf8'));
     } catch (error) {
-      throw new Error(`leg (a) signer: cosign returned an unreadable attestation for ${subject}`, { cause: error });
+      throw new Error(`${label}: cosign returned an unreadable attestation for ${subject}`, { cause: error });
     }
     byDigest.set(`sha256:${createHash('sha256').update(payload).digest('hex')}`, statement);
   }
   return byDigest;
 }
 
-/** Proves legs (a), (b) and (c) for `<devRef>@<digest>`; returns `{ revision, provenanceDigest, signerPattern }`. */
-export function verifyDevelopProvenance(
-  { devRef, digest, repository, developWorkflow, mainRef, commit, tag, tagCommand },
-  run = runTool,
-) {
-  const subject = `${devRef}@${digest}`;
-  const signerPattern = workflowIdentityPattern(repository, [developWorkflow], 'develop');
-
-  // (a) signer
+/**
+ * Runs `cosign verify-attestation` of `type` on `subject` under `pattern` and requires exactly one distinct verified
+ * statement whose subject is the digest. Returns `{ statement, payloadDigest }`.
+ */
+function verifiedStatement({ subject, digest, type, predicateType, what, noun, pattern, label }, run) {
   const verified = run('cosign', [
     'verify-attestation',
-    '--type', COSIGN_SLSA_V1_TYPE,
-    '--certificate-identity-regexp', signerPattern,
+    '--type', type,
+    '--certificate-identity-regexp', pattern,
     '--certificate-oidc-issuer', GITHUB_OIDC_ISSUER,
     subject,
   ]);
-  if (verified.error || verified.status !== 0) {
-    throw new Error(`leg (a) signer: ${subject} has no SLSA v1 provenance signed by ${signerPattern}: ${describeFailure(verified)}`);
+  if (verified.error) throw new Error(`${label}: could not run cosign to verify ${subject}: ${verified.error.message}`);
+  if (verified.status !== 0) {
+    const detail = describeFailure(verified);
+    throw new Error(`${label}: ${subject} has no ${what} signed by ${pattern}: ${detail}`);
   }
-  const statements = readStatements(verified.stdout, subject);
+  const statements = readStatements(verified.stdout, subject, label);
   if (statements.size !== 1) {
-    throw new Error(`leg (a) signer: ${subject} carries ${statements.size} distinct verified provenance statements; exactly one is promotable`);
+    throw new Error(`${label}: ${subject} carries ${statements.size} distinct verified ${noun} statements; exactly one is promotable`);
   }
-  const [[provenanceDigest, statement]] = statements;
+  const [[payloadDigest, statement]] = statements;
   const hex = digest.slice('sha256:'.length);
-  if (statement.predicateType !== SLSA_PROVENANCE_V1 || !statement.subject?.some((entry) => entry?.digest?.sha256 === hex)) {
-    throw new Error(`leg (a) signer: the verified statement is not SLSA v1 provenance about ${subject}`);
+  if (statement.predicateType !== predicateType || !statement.subject?.some((entry) => entry?.digest?.sha256 === hex)) {
+    throw new Error(`${label}: the verified statement is not ${what} about ${subject}`);
+  }
+  return { statement, payloadDigest };
+}
+
+/** The predicate types of every attestation on `subject`, listed without verifying any signature. A registry error is an error. */
+function attestationTypes(subject, label, run) {
+  const listed = run('cosign', ['download', 'attestation', subject]);
+  if (listed.error) throw new Error(`${label}: could not run cosign to list the attestations of ${subject}: ${listed.error.message}`);
+  if (listed.status !== 0) throw new Error(`${label}: listing the attestations of ${subject} failed: ${describeFailure(listed)}`);
+  return listed.stdout.split('\n').map((text) => text.trim()).filter(Boolean).map((line) => {
+    try {
+      return JSON.parse(Buffer.from(JSON.parse(line).payload, 'base64').toString('utf8')).predicateType;
+    } catch (error) {
+      throw new Error(`${label}: cosign listed an unreadable attestation for ${subject}`, { cause: error });
+    }
+  });
+}
+
+/**
+ * Reuse of a release digest main already promoted. Verifies its image-promotion/v1 attestation under one of main's
+ * release workflows (anchored identity, GitHub OIDC issuer) and returns `{ source, developProvenance }` copied from it.
+ * Returns `undefined` when the digest carries no promotion attestation (a legacy image); a registry error, a signature or identity
+ * failure, or a source outside `<registry>/<owner>/dev/`, is an error.
+ */
+export function reuseEarlierPromotion({ releaseRef, tag, digest, repository, releaseWorkflows }, run = runTool) {
+  const subject = `${releaseRef}@${digest}`;
+  const label = 'reuse';
+  // (a) presence, without identity verification: only the predicate types are read
+  if (!attestationTypes(subject, label, run).includes(IMAGE_PROMOTION_PREDICATE_TYPE)) return undefined;
+  // (b) a promotion attestation is present: any verification failure is an error
+  const found = verifiedStatement({
+    subject, digest, type: IMAGE_PROMOTION_PREDICATE_TYPE, predicateType: IMAGE_PROMOTION_PREDICATE_TYPE,
+    what: 'image-promotion/v1 attestation', noun: 'promotion', pattern: workflowIdentityPattern(repository, releaseWorkflows, 'main'),
+    label,
+  }, run);
+  const { source, developProvenance, release } = found.statement.predicate ?? {};
+  for (const [field, expected, stated] of [['digest', digest, release?.digest], ['repository', releaseRef, release?.repository], ['tag', tag, release?.tag]]) {
+    if (stated !== expected) throw new Error(`${label}: the promotion attestation of ${subject} states release ${field} ${stated}, not ${expected}`);
+  }
+  const owner = repository.split('/')[0].toLowerCase();
+  const devSource = new RegExp(`^ghcr\\.io/${escapeRegExp(owner)}/dev/[a-z0-9][a-z0-9._/-]*@${escapeRegExp(digest)}$`);
+  if (typeof source?.reference !== 'string' || !devSource.test(source.reference)) {
+    throw new Error(`${label}: the promotion attestation of ${subject} names source '${source?.reference}', not a ghcr.io/${owner}/dev/<name>@${digest} reference`);
+  }
+  if (typeof source.revision !== 'string' || !COMMIT.test(source.revision)) {
+    throw new Error(`${label}: the promotion attestation of ${subject} names no 40-hex source revision`);
   }
+  const { predicateType, payloadDigest, signerIdentityPattern } = developProvenance ?? {};
+  if (![predicateType, payloadDigest, signerIdentityPattern].every((value) => typeof value === 'string' && value !== '')) {
+    throw new Error(`${label}: the promotion attestation of ${subject} carries no developProvenance`);
+  }
+  return {
+    source: { reference: source.reference, revision: source.revision },
+    developProvenance: { predicateType, payloadDigest, signerIdentityPattern },
+  };
+}
+
+/**
+ * Whether `<devRef>@<digest>` carries any SLSA v1 provenance attestation, listed without verifying a signature. A digest
+ * with none (an image reused on develop from before provenance) is not promotable but not an error; a registry error is.
+ */
+export function hasDevelopProvenance({ devRef, digest }, run = runTool) {
+  return attestationTypes(`${devRef}@${digest}`, 'copy', run).includes(SLSA_PROVENANCE_V1);
+}
+
+/** Proves legs (a), (b) and (c) for `<devRef>@<digest>`; returns `{ revision, provenanceDigest, signerPattern }`. */
+export function verifyDevelopProvenance(
+  { devRef, digest, repository, developWorkflow, mainRef, commit, tag, tagCommand },
+  run = runTool,
+) {
+  const subject = `${devRef}@${digest}`;
+  const signerPattern = workflowIdentityPattern(repository, [developWorkflow], 'develop');
+
+  // (a) signer
+  const { statement, payloadDigest: provenanceDigest } = verifiedStatement(
+    { subject, digest, type: COSIGN_SLSA_V1_TYPE, predicateType: SLSA_PROVENANCE_V1, what: 'SLSA v1 provenance', noun: 'provenance', pattern: signerPattern, label: 'leg (a) signer' },
+    run,
+  );
   const revision = statement.predicate?.runDetails?.metadata?.buildkit_metadata?.vcs?.revision;
   if (typeof revision !== 'string' || !COMMIT.test(revision)) {
     throw new Error(`leg (a) signer: the provenance of ${subject} names no 40-hex vcs.revision`);

package/src/promote-image.mjs

@@ -3,20 +3,24 @@
 // DEVELOP repository already holds for one content-addressed tag, instead of
 // rebuilding them, and only when the develop bytes are PROVEN promotable.
 //
-//   1. `<release-ref>:<tag>` exists:
-//      - signed by one of main's `--release-workflow`s      -> reused (evidence=release-signature)
-//      - else it must be the develop digest, proven below    -> reused (evidence=develop-provenance)
+//   1. `<release-ref>:<tag>` exists: its image-promotion/v1 attestation must verify under one of main's
+//      `--release-workflow` identities (exactly one statement about the digest), and its source must be a
+//      `ghcr.io/<owner>/dev/<name>` reference                  -> reused (evidence=prior-promotion)
+//      - no image-promotion/v1 attestation (a legacy image)    -> miss (reason=reuse-no-promotion): the caller builds
+//      - a signature / identity failure, or a source outside dev/ -> error, never a miss
 //   2. else `<dev-ref>:<tag>` exists: prove it (legs a, b, c in
 //      promote-image-provenance.mjs), copy it by digest (`imagetools create`
 //      from `<dev-ref>@<digest>`, so an index stays whole), re-probe, and refuse
 //      unless the release digest equals the source            -> copied (evidence=develop-provenance)
+//      - no SLSA provenance on the dev digest at all (reused on develop from before the swap) -> miss (reason=copy-no-develop-provenance)
+//      - provenance present but any leg fails                  -> error, never a miss
 //   3. else                                                  -> miss: the caller builds.
 //
-// With evidence=develop-provenance it writes the promotion predicate
-// (`https://xema.dev/attestations/image-promotion/v1`) to
-// `--promotion-predicate-out`, for the caller to `cosign attest` under main's own
-// identity. It signs nothing itself; the develop identity is evidence for the
-// promotion, never a signature the release side trusts.
+// On every non-miss result it writes the promotion predicate
+// (`https://xema.dev/attestations/image-promotion/v1`) to `--promotion-predicate-out`, for the caller to
+// `cosign attest` under main's own identity. A copy states the facts it just proved; a reuse states this run's
+// release and commit and carries `source` and `developProvenance` from main's earlier promotion. It signs
+// nothing itself; the develop identity is evidence for the promotion, never a signature the release side trusts.
 //
 // `--tag` is the caller's content key, and everything after `--` is the command
 // that computes it (e.g. `node tooling/release/compute-image-tag.mjs --service
@@ -30,22 +34,45 @@
 // Outputs: `result`, `digest`, `source`, `revision`, `evidence`,
 // `provenance_digest`, `promotion_predicate` and `promotion_predicate_type` appended to `$GITHUB_OUTPUT`
 // (required; empty values where a fact does not apply), and one stdout line
-// `promote-image result=<r> digest=<d> src=<repository>@<d> revision=<sha> evidence=<e>`.
+// `promote-image result=<r> digest=<d> src=<repository>@<d> revision=<sha> evidence=<e>`, with ` reason=<why>` appended
+// to a miss that has a reason.
 
 import { appendFileSync, existsSync } from 'node:fs';
 import process from 'node:process';
 import { describeErrorChain } from '@xemahq/release-policy/registry';
 import { invokedDirectly } from './readiness.mjs';
-import { IMAGE_PROMOTION_PREDICATE_TYPE, writePromotionPredicate } from './promote-image-predicate.mjs';
-import { releaseSignedByMain, verifyDevelopProvenance } from './promote-image-provenance.mjs';
+import { IMAGE_PROMOTION_PREDICATE_TYPE, promotionPredicate, reusedPromotionPredicate, writePromotionPredicate } from './promote-image-predicate.mjs';
+import { hasDevelopProvenance, reuseEarlierPromotion, verifyDevelopProvenance } from './promote-image-provenance.mjs';
 import { copyByDigest, probeDigest, runTool } from './promote-image-registry.mjs';
 
 export const PromoteResult = Object.freeze({ REUSED: 'reused', COPIED: 'copied', MISS: 'miss' });
 export const PromoteEvidence = Object.freeze({
-  RELEASE_SIGNATURE: 'release-signature',
+  PRIOR_PROMOTION: 'prior-promotion',
   DEVELOP_PROVENANCE: 'develop-provenance',
   NONE: 'none',
 });
+export const PromoteMissReason = Object.freeze({ NO_PROMOTION: 'reuse-no-promotion', NO_DEVELOP_PROVENANCE: 'copy-no-develop-provenance' });
+
+// The one cosign major shared by the develop attest step, this verb and xema-deploy's verify (xema-deploy pins
+// v2.x in scripts/install-cosign.sh and refuses anything else). v2 `attest` stores `.att` tags; v3 stores
+// bundles/referrers, so a mixed pair makes `cosign download attestation` see nothing and every promotion
+// would silently become a build.
+export const COSIGN_MAJOR = 2;
+
+/** Runs `cosign version` once and refuses unless its GitVersion is major `COSIGN_MAJOR`. */
+export function assertCosignMajor(run = runTool) {
+  const result = run('cosign', ['version']);
+  if (result.error) throw new Error(`could not run cosign to read its version: ${result.error.message}`);
+  if (result.status !== 0) throw new Error(`cosign version failed: ${(result.stderr || result.stdout || `exit ${result.status}`).trim()}`);
+  const match = /^GitVersion:\s*v?(\d+)\.\d+\.\d+/m.exec(result.stdout ?? '');
+  if (match === null) throw new Error('cosign version printed no parsable GitVersion; refusing to promote with an unknown cosign');
+  if (Number(match[1]) !== COSIGN_MAJOR) {
+    throw new Error(
+      `cosign major ${match[1]} found, but this verb needs cosign v${COSIGN_MAJOR}.x: v2 and v3 store attestations differently, ` +
+        'so a mismatch with the develop attest step would make every promotion silently a build. Refusing.',
+    );
+  }
+}
 
 const USAGE =
   'usage: xema-promote-image --service <name> --dev-ref <registry/repository> --release-ref <registry/repository> ' +
@@ -115,29 +142,32 @@ export function parsePromoteArguments(argv) {
 
 const MISS = Object.freeze({ result: PromoteResult.MISS, digest: '', source: '', evidence: PromoteEvidence.NONE });
 
-/** Runs the steps. Returns `{ result, digest, source, evidence, proof? }`; `proof` is set for evidence=develop-provenance. */
+/**
+ * Runs the steps. Returns `{ result, digest, source, evidence, predicate?, revision?, provenanceDigest?, reason? }`;
+ * `predicate` is set on every non-miss result, `reason` on a miss that has one.
+ */
 export function promoteImage(options, run = runTool) {
-  const { service, devRef, releaseRef, tag, repository, releaseWorkflows } = options;
+  const { service, devRef, releaseRef, tag, commit, repository, releaseWorkflows } = options;
+  assertCosignMajor(run);
   const releaseTagged = `${releaseRef}:${tag}`;
   const released = probeDigest(releaseTagged, run);
   if (released !== undefined) {
-    const subject = `${releaseRef}@${released}`;
-    if (releaseSignedByMain({ subject, repository, releaseWorkflows }, run)) {
-      return { result: PromoteResult.REUSED, digest: released, source: subject, evidence: PromoteEvidence.RELEASE_SIGNATURE };
-    }
-    const developed = probeDigest(`${devRef}:${tag}`, run);
-    if (developed !== released) {
-      throw new Error(
-        `${service}: ${releaseTagged} (${released}) carries no signature from main and is not the develop digest ` +
-          `(${developed ?? 'no develop tag'}), so nothing proves it promotable. Refusing.`,
-      );
-    }
-    const proof = verifyDevelopProvenance({ ...options, digest: released }, run);
-    return { result: PromoteResult.REUSED, digest: released, source: `${devRef}@${released}`, evidence: PromoteEvidence.DEVELOP_PROVENANCE, proof };
+    const earlier = reuseEarlierPromotion({ releaseRef, tag, digest: released, repository, releaseWorkflows }, run);
+    if (earlier === undefined) return { ...MISS, reason: PromoteMissReason.NO_PROMOTION };
+    return {
+      result: PromoteResult.REUSED,
+      digest: released,
+      source: earlier.source.reference,
+      evidence: PromoteEvidence.PRIOR_PROMOTION,
+      revision: earlier.source.revision,
+      provenanceDigest: earlier.developProvenance.payloadDigest,
+      predicate: reusedPromotionPredicate({ releaseRef, tag, digest: released, commit, ...earlier }),
+    };
   }
   const developed = probeDigest(`${devRef}:${tag}`, run);
   if (developed === undefined) return MISS;
 
+  if (!hasDevelopProvenance({ devRef, digest: developed }, run)) return { ...MISS, reason: PromoteMissReason.NO_DEVELOP_PROVENANCE };
   const proof = verifyDevelopProvenance({ ...options, digest: developed }, run);
   const source = `${devRef}@${developed}`;
   copyByDigest(source, releaseTagged, run);
@@ -148,7 +178,15 @@ export function promoteImage(options, run = runTool) {
         'the copy did not preserve the digest, so the release tag does not name the develop bytes. Refusing.',
     );
   }
-  return { result: PromoteResult.COPIED, digest: developed, source, evidence: PromoteEvidence.DEVELOP_PROVENANCE, proof };
+  return {
+    result: PromoteResult.COPIED,
+    digest: developed,
+    source,
+    evidence: PromoteEvidence.DEVELOP_PROVENANCE,
+    revision: proof.revision,
+    provenanceDigest: proof.provenanceDigest,
+    predicate: promotionPredicate({ releaseRef, tag, digest: developed, source, commit, ...proof }),
+  };
 }
 
 export function main(argv, { githubOutput, run = runTool, write = (text) => process.stdout.write(text) } = {}) {
@@ -157,29 +195,20 @@ export function main(argv, { githubOutput, run = runTool, write = (text) => proc
   if (existsSync(options.predicateOut)) {
     throw new Error(`--promotion-predicate-out ${options.predicateOut} already exists; refusing to leave a stale predicate to attest`);
   }
-  const { result, digest, source, evidence, proof } = promoteImage(options, run);
-  if (proof !== undefined) {
-    writePromotionPredicate(options.predicateOut, {
-      releaseRef: options.releaseRef,
-      tag: options.tag,
-      digest,
-      source,
-      commit: options.commit,
-      ...proof,
-    });
-  }
+  const { result, digest, source, evidence, predicate, revision, provenanceDigest, reason } = promoteImage(options, run);
+  if (predicate !== undefined) writePromotionPredicate(options.predicateOut, predicate);
   const outputs = {
     result,
     digest,
     source,
-    revision: proof?.revision ?? '',
+    revision: revision ?? '',
     evidence,
-    provenance_digest: proof?.provenanceDigest ?? '',
-    promotion_predicate: proof === undefined ? '' : options.predicateOut,
-    promotion_predicate_type: proof === undefined ? '' : IMAGE_PROMOTION_PREDICATE_TYPE,
+    provenance_digest: provenanceDigest ?? '',
+    promotion_predicate: predicate === undefined ? '' : options.predicateOut,
+    promotion_predicate_type: predicate === undefined ? '' : IMAGE_PROMOTION_PREDICATE_TYPE,
   };
   appendFileSync(githubOutput, Object.entries(outputs).map(([key, value]) => `${key}=${value}\n`).join(''));
-  write(`promote-image result=${result} digest=${digest} src=${source} revision=${outputs.revision} evidence=${evidence}\n`);
+  write(`promote-image result=${result} digest=${digest} src=${source} revision=${outputs.revision} evidence=${evidence}${reason === undefined ? '' : ` reason=${reason}`}\n`);
 }
 
 if (invokedDirectly(process.argv[1], import.meta.url)) {

package/src/promote-image.test.mjs

@@ -23,7 +23,8 @@ const PROMOTION_TYPE = 'https://xema.dev/attestations/image-promotion/v1';
 // answering from one JSON state file:
 //   tags / errors / copyDigest   `docker buildx imagetools inspect|create`
 //   signatures[subject]          the identity `cosign verify` finds
-//   attestations[subject]        { identity, statements } `cosign verify-attestation` finds
+//   downloadErrors[subject]      what `cosign download attestation` fails with
+//   attestations[subject]        { identity, statements, type? } (type defaults to slsaprovenance1) `cosign verify-attestation` finds
 //   ancestors                    revisions `git merge-base --is-ancestor` accepts
 //   hashes[commit]               what the tag command prints for `--commit <commit>`
 // Every call is recorded in `calls` as [tool, ...args].
@@ -50,8 +51,21 @@ if (tool === 'docker') {
   if (args[2] === 'create') { state.tags[args[4]] = state.copyDigest ?? args[5].split('@')[1]; save(); process.exit(0); }
   fail('unexpected docker ' + args.join(' '), 2);
 }
+if (tool === 'cosign' && args[0] === 'version') {
+  process.stdout.write(state.cosignVersion ?? 'GitVersion:    v2.6.3\\nGitCommit:     abc\\n');
+  process.exit(0);
+}
 if (tool === 'cosign') {
   const subject = args[args.length - 1];
+  if (args[0] === 'download' && args[1] === 'attestation') {
+    if (state.downloadErrors[subject]) fail(state.downloadErrors[subject]);
+    const listed = state.attestations[subject];
+    if (!listed) fail('Error: no attestations found for ' + subject + '\\n');
+    for (const statement of listed.statements) {
+      process.stdout.write(JSON.stringify({ payloadType: 'application/vnd.in-toto+json', payload: Buffer.from(statement).toString('base64'), signatures: [] }) + '\\n');
+    }
+    process.exit(0);
+  }
   const pattern = new RegExp(flag('--certificate-identity-regexp'));
   if (flag('--certificate-oidc-issuer') !== 'https://token.actions.githubusercontent.com') fail('wrong issuer', 2);
   if (args[0] === 'verify') {
@@ -60,7 +74,10 @@ if (tool === 'cosign') {
   }
   if (args[0] === 'verify-attestation') {
     const found = state.attestations[subject];
-    if (!found || !pattern.test(found.identity) || flag('--type') !== 'slsaprovenance1') fail('Error: no matching attestations: none of the expected identities matched\\n');
+    if (!found || !pattern.test(found.identity)) fail('Error: no matching attestations: none of the expected identities matched\\n');
+    const wanted = flag('--type');
+    const have = found.type ?? 'slsaprovenance1';
+    if (wanted !== have) fail('Error: none of the attestations matched the predicate type: ' + wanted + ', found: ' + have + '\\n');
     for (const statement of found.statements) {
       process.stdout.write(JSON.stringify({ payloadType: 'application/vnd.in-toto+json', payload: Buffer.from(statement).toString('base64'), signatures: [] }) + '\\n');
     }
@@ -108,7 +125,7 @@ function scenario(state) {
   fs.mkdirSync(binDir);
   for (const tool of ['docker', 'cosign', 'git', 'tag-command']) fs.writeFileSync(path.join(binDir, tool), SHIM, { mode: 0o755 });
   const stateFile = path.join(dir, 'state.json');
-  fs.writeFileSync(stateFile, JSON.stringify({ tags: {}, errors: {}, signatures: {}, attestations: {}, ancestors: [], hashes: {}, calls: [], ...state }));
+  fs.writeFileSync(stateFile, JSON.stringify({ tags: {}, errors: {}, downloadErrors: {}, signatures: {}, attestations: {}, ancestors: [], hashes: {}, calls: [], ...state }));
   const output = path.join(dir, 'github-output');
   fs.writeFileSync(output, '');
   const predicate = path.join(dir, 'promotion.json');
@@ -155,24 +172,100 @@ function refused(state, pattern) {
   }
 }
 
-test('a release tag signed by a main workflow is reused, without develop proof or a predicate', () => {
+const sha = (text) => `sha256:${createHash('sha256').update(text).digest('hex')}`;
+const EARLIER_PROVENANCE = {
+  predicateType: 'https://slsa.dev/provenance/v1',
+  payloadDigest: sha('earlier-provenance'),
+  signerIdentityPattern: '^https://github\\.com/acme/svc/\\.github/workflows/(?:develop-images\\.yaml)@refs/heads/develop$',
+};
+const EARLIER_COMMIT = '5'.repeat(40);
+
+// A release digest main already promoted: its image-promotion/v1 attestation, signed by a main workflow.
+function promotedRelease({ source = `${DEV}@${OTHER}`, identity = MAIN_IDENTITY, type = PROMOTION_TYPE, extra = {} } = {}) {
+  const statement = JSON.stringify({
+    _type: 'https://in-toto.io/Statement/v1',
+    subject: [{ name: RELEASE, digest: { sha256: OTHER.slice('sha256:'.length) } }],
+    predicateType: PROMOTION_TYPE,
+    predicate: {
+      release: { repository: RELEASE, tag: TAG, digest: OTHER },
+      source: { reference: source, revision: REVISION },
+      promotedCommit: EARLIER_COMMIT,
+      developProvenance: EARLIER_PROVENANCE,
+      ...extra,
+    },
+  });
+  return {
+    tags: { [`${RELEASE}:${TAG}`]: OTHER },
+    attestations: { [`${RELEASE}@${OTHER}`]: { identity, type, statements: [statement] } },
+  };
+}
+
+test('a release digest main already promoted is reused: source and developProvenance carry over, release and commit are this run', () => {
+  const { run, predicatePath, cleanup } = scenario(promotedRelease());
+  try {
+    const r = run();
+    assert.equal(r.status, 0, r.stderr);
+    assert.equal(r.stdout, `promote-image result=reused digest=${OTHER} src=${DEV}@${OTHER} revision=${REVISION} evidence=prior-promotion\n`);
+    assert.deepEqual(r.outputs, {
+      result: 'reused', digest: OTHER, source: `${DEV}@${OTHER}`, revision: REVISION, evidence: 'prior-promotion',
+      provenance_digest: EARLIER_PROVENANCE.payloadDigest, promotion_predicate: predicatePath, promotion_predicate_type: PROMOTION_TYPE,
+    });
+    assert.deepEqual(r.predicate, {
+      release: { repository: RELEASE, tag: TAG, digest: OTHER },
+      source: { reference: `${DEV}@${OTHER}`, revision: REVISION },
+      promotedCommit: COMMIT,
+      developProvenance: EARLIER_PROVENANCE,
+    });
+    assert.deepEqual(creates(r.state), []);
+    assert.equal(r.state.calls.some((call) => call[0] === 'docker' && call[3] === `${DEV}:${TAG}`), false);
+  } finally {
+    cleanup();
+  }
+});
+
+test('a release digest with only SLSA provenance is a miss with a reason', () => {
   const { run, cleanup } = scenario({
     tags: { [`${RELEASE}:${TAG}`]: OTHER },
-    signatures: { [`${RELEASE}@${OTHER}`]: MAIN_IDENTITY },
+    attestations: { [`${RELEASE}@${OTHER}`]: { identity: MAIN_IDENTITY, statements: [provenance(OTHER)] } },
   });
   try {
     const r = run();
     assert.equal(r.status, 0, r.stderr);
-    assert.equal(r.stdout, `promote-image result=reused digest=${OTHER} src=${RELEASE}@${OTHER} revision= evidence=release-signature\n`);
-    assert.equal(r.outputs.result, 'reused');
-    assert.equal(r.outputs.promotion_predicate, '');
+    assert.equal(r.stdout, 'promote-image result=miss digest= src= revision= evidence=none reason=reuse-no-promotion\n');
+    assert.equal(r.outputs.result, 'miss');
     assert.equal(r.predicate, undefined);
-    assert.deepEqual(creates(r.state), []);
   } finally {
     cleanup();
   }
 });
 
+test('a registry error listing the attestations is an error, not a miss', () => {
+  refused(
+    { tags: { [`${RELEASE}:${TAG}`]: OTHER }, downloadErrors: { [`${RELEASE}@${OTHER}`]: 'Error: dial tcp: lookup ghcr.io: no such host\n' } },
+    /reuse: listing the attestations of .* failed: .*no such host/,
+  );
+});
+
+test('a promotion attestation signed by the wrong identity is refused, not a miss', () => {
+  refused(promotedRelease({ identity: DEVELOP_IDENTITY }), /reuse: .* has no image-promotion\/v1 attestation signed by/);
+});
+
+test('a promotion attestation whose source is outside dev/ is refused', () => {
+  refused(promotedRelease({ source: `ghcr.io/acme/svc@${OTHER}` }), /names source 'ghcr\.io\/acme\/svc@sha256:e+', not a ghcr\.io\/acme\/dev\//);
+});
+
+test('a promotion attestation stating another release repository is refused', () => {
+  refused(promotedRelease({ extra: { release: { repository: 'ghcr.io/acme/other', tag: TAG, digest: OTHER } } }), /states release repository ghcr\.io\/acme\/other, not /);
+});
+
+test('a promotion attestation stating another release tag is refused', () => {
+  refused(promotedRelease({ extra: { release: { repository: RELEASE, tag: 'a'.repeat(64), digest: OTHER } } }), /states release tag a+, not c+/);
+});
+
+test('a promotion attestation stating another release digest is refused', () => {
+  refused(promotedRelease({ extra: { release: { repository: RELEASE, tag: TAG, digest: DIGEST } } }), /states release digest sha256:d+, not /);
+});
+
 test('a proven develop digest is copied by digest and the promotion predicate states the facts', () => {
   const { run, predicatePath, cleanup } = scenario(provenDevelop());
   try {
@@ -200,22 +293,33 @@ test('a proven develop digest is copied by digest and the promotion predicate st
   }
 });
 
-test('an unsigned release tag equal to the proven develop digest is reused with a promotion predicate', () => {
-  const { run, cleanup } = scenario(provenDevelop({ tags: { [`${DEV}:${TAG}`]: DIGEST, [`${RELEASE}:${TAG}`]: DIGEST } }));
-  try {
-    const r = run();
-    assert.equal(r.status, 0, r.stderr);
-    assert.equal(r.outputs.result, 'reused');
-    assert.equal(r.outputs.evidence, 'develop-provenance');
-    assert.equal(r.predicate.source.revision, REVISION);
-    assert.deepEqual(creates(r.state), []);
-  } finally {
-    cleanup();
-  }
+const SBOM = JSON.stringify({
+  _type: 'https://in-toto.io/Statement/v1',
+  subject: [{ name: DEV, digest: { sha256: DIGEST.slice('sha256:'.length) } }],
+  predicateType: 'https://spdx.dev/Document',
+  predicate: {},
 });
 
-test('an unsigned release tag that is not the develop digest is refused', () => {
-  refused(provenDevelop({ tags: { [`${DEV}:${TAG}`]: DIGEST, [`${RELEASE}:${TAG}`]: OTHER } }), /carries no signature from main and is not the develop digest/);
+for (const [name, statements] of [['no attestations', []], ['only an SBOM attestation', [SBOM]]]) {
+  test(`a dev digest with ${name} is a miss with a reason, not an error`, () => {
+    const { run, cleanup } = scenario(provenDevelop({ attestations: { [`${DEV}@${DIGEST}`]: { identity: DEVELOP_IDENTITY, statements } } }));
+    try {
+      const r = run();
+      assert.equal(r.status, 0, r.stderr);
+      assert.equal(r.stdout, 'promote-image result=miss digest= src= revision= evidence=none reason=copy-no-develop-provenance\n');
+      assert.equal(r.predicate, undefined);
+      assert.deepEqual(creates(r.state), []);
+    } finally {
+      cleanup();
+    }
+  });
+}
+
+test('a registry error listing the dev attestations is an error, not a miss', () => {
+  refused(
+    provenDevelop({ downloadErrors: { [`${DEV}@${DIGEST}`]: 'Error: dial tcp: lookup ghcr.io: no such host\n' } }),
+    /copy: listing the attestations of .* failed: .*no such host/,
+  );
 });
 
 test('leg (a): provenance signed by a unit-branch workflow is refused before any copy', () => {
@@ -266,7 +370,7 @@ test('a definite not-found in both repositories is a miss, not an error', () =>
     assert.equal(r.outputs.result, 'miss');
     assert.equal(r.outputs.digest, '');
     assert.equal(r.predicate, undefined);
-    assert.equal(r.state.calls.length, 2);
+    assert.equal(r.state.calls.length, 3);
   } finally {
     cleanup();
   }
@@ -324,3 +428,26 @@ test('missing, malformed or unknown flags are refused before any external call',
     cleanup();
   }
 });
+
+test('cosign of the pinned major passes and is asked once, before any other cosign call', () => {
+  const { run, cleanup } = scenario(provenDevelop());
+  try {
+    const r = run();
+    assert.equal(r.status, 0, r.stderr);
+    const cosign = r.state.calls.filter((call) => call[0] === 'cosign');
+    assert.deepEqual(cosign[0], ['cosign', 'version']);
+    assert.equal(cosign.filter((call) => call[1] === 'version').length, 1);
+  } finally {
+    cleanup();
+  }
+});
+
+test('a cosign of another major is refused before any registry call', () => {
+  const r = refused({ ...provenDevelop(), cosignVersion: 'GitVersion:    v3.0.2\n' }, /cosign major 3 found, but this verb needs cosign v2\.x/);
+  assert.deepEqual(r.state.calls, [['cosign', 'version']]);
+});
+
+test('an unparsable cosign version is refused', () => {
+  const r = refused({ ...provenDevelop(), cosignVersion: 'GitVersion:    devel\n' }, /no parsable GitVersion/);
+  assert.deepEqual(r.state.calls, [['cosign', 'version']]);
+});