@xemahq/xema 0.48.0 → 0.49.0

package/edition/edition-contract-parse.mjs

@@ -1,11 +1,95 @@
 // edition-contract-parse — the strict parse of edition-contract.json. A consumer
 // that vendors the contract holds it to this same shape: a contract that is not
-// v2, or lacks `repositories`, or names a channel this CLI does not know, is
-// refused rather than read with a default.
+// v3, or lacks `repositories`, or names a channel, kind or evidence trust state
+// this CLI does not know, is refused rather than read with a default.
 
 import { EditionChannel } from './edition-channel.mjs';
+import { EditionKind, EvidenceTrustState } from './edition-kind.mjs';
 
-export const EDITION_CONTRACT_SCHEMA = 'xema.edition-contract/v2';
+export const EDITION_CONTRACT_SCHEMA = 'xema.edition-contract/v3';
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const sameSet = (left, right) => Array.isArray(left) && left.length === right.length && right.every((name) => left.includes(name));
+
+/**
+ * The descriptor vocabulary: the descriptor schema (read from the contract, never restated), the closed kind enum,
+ * `sealOf` (its pattern, its repository rule and the one channel a seal is of), the signers (the issuer, and the SHAPE of
+ * a publisher: which kinds and channels have one and its {repository, workflow, ref} grammar; the publisher VALUES are
+ * the data root's edition-workspace.json, never the contract's) and the evidence trust states each kind may record per
+ * channel. A kind's channels are the same in `signers.publishers.channelsByKind` and `evidenceTrust.statesByKind`: every
+ * channel for a resolved edition, exactly `sealOf.channel` for a sealed one (a seal is release-only).
+ */
+/** `source` is an anchored (^...$) regular expression source that compiles. */
+function assertAnchoredPattern(source, where) {
+  if (typeof source !== 'string' || !source.startsWith('^') || !source.endsWith('$')) {
+    throw new Error(`edition-contract.json: ${where} must be an anchored (^...$) regular expression source`);
+  }
+  try {
+    new RegExp(source);
+  } catch (error) {
+    throw new Error(`edition-contract.json: ${where} is not a regular expression: ${error.message}`);
+  }
+}
+
+function assertDescriptorVocabulary(contract) {
+  if (typeof contract.descriptorSchema !== 'string' || contract.descriptorSchema === '') {
+    throw new Error('edition-contract.json: "descriptorSchema" must be a non-empty string');
+  }
+  const kinds = Object.values(EditionKind);
+  const channels = Object.values(EditionChannel);
+  if (!sameSet(contract.descriptorKinds, kinds)) {
+    throw new Error(`edition-contract.json: descriptorKinds must be exactly ${kinds.join(' | ')} (got ${JSON.stringify(contract.descriptorKinds)})`);
+  }
+  const sealOf = contract.sealOf;
+  const texts = ['names', 'repository', 'sealedEdition'];
+  if (!isObject(sealOf) || !sameSet(Object.keys(sealOf), ['pattern', 'channel', ...texts]) || !texts.every((key) => typeof sealOf[key] === 'string' && sealOf[key] !== '')) {
+    throw new Error('edition-contract.json: "sealOf" must be exactly {pattern, names, repository, channel, sealedEdition}: the one statement of a sealed edition\'s sealOf');
+  }
+  assertAnchoredPattern(sealOf.pattern, 'sealOf.pattern');
+  if (!channels.includes(sealOf.channel)) {
+    throw new Error(`edition-contract.json: sealOf.channel must be one of ${channels.join(' | ')}`);
+  }
+  const channelsOf = { [EditionKind.Resolved]: channels, [EditionKind.Sealed]: [sealOf.channel] };
+  const signers = contract.signers;
+  if (!isObject(signers) || !sameSet(Object.keys(signers), ['oidcIssuer', 'identity', 'publishers']) || !/^https:\/\/\S+$/.test(signers.oidcIssuer ?? '') || typeof signers.identity !== 'string' || signers.identity === '') {
+    throw new Error('edition-contract.json: "signers" must be exactly {oidcIssuer: <https URL>, identity, publishers}');
+  }
+  const publishers = signers.publishers;
+  if (!isObject(publishers) || !sameSet(Object.keys(publishers), ['values', 'channelsByKind', 'shape']) || typeof publishers.values !== 'string' || publishers.values === '') {
+    throw new Error('edition-contract.json: signers.publishers must be exactly {values, channelsByKind, shape}');
+  }
+  const fields = ['repository', 'workflow', 'ref'];
+  if (!isObject(publishers.shape) || !sameSet(Object.keys(publishers.shape), fields)) {
+    throw new Error(`edition-contract.json: signers.publishers.shape must be exactly {${fields.join(', ')}}`);
+  }
+  for (const field of fields) {
+    assertAnchoredPattern(publishers.shape[field], `signers.publishers.shape.${field}`);
+  }
+  const trust = contract.evidenceTrust;
+  const states = Object.values(EvidenceTrustState);
+  if (!isObject(trust) || !isObject(trust.states) || !sameSet(Object.keys(trust.states), states)) {
+    throw new Error(`edition-contract.json: evidenceTrust.states must name exactly ${states.join(' | ')}`);
+  }
+  for (const [where, byKind] of [['signers.publishers.channelsByKind', publishers.channelsByKind], ['evidenceTrust.statesByKind', trust.statesByKind]]) {
+    if (!isObject(byKind) || !sameSet(Object.keys(byKind), kinds)) {
+      throw new Error(`edition-contract.json: ${where} must have exactly one entry per kind (${kinds.join(' | ')})`);
+    }
+    for (const kind of kinds) {
+      const named = Array.isArray(byKind[kind]) ? byKind[kind] : isObject(byKind[kind]) ? Object.keys(byKind[kind]) : undefined;
+      if (!sameSet(named, channelsOf[kind]) || new Set(named).size !== named.length) {
+        throw new Error(`edition-contract.json: ${where}.${kind} must have exactly one entry per channel of a ${kind} edition (${channelsOf[kind].join(' | ')})`);
+      }
+    }
+  }
+  for (const kind of kinds) {
+    for (const channel of channelsOf[kind]) {
+      const admitted = trust.statesByKind[kind][channel];
+      if (!Array.isArray(admitted) || admitted.length === 0 || new Set(admitted).size !== admitted.length || !admitted.every((state) => states.includes(state))) {
+        throw new Error(`edition-contract.json: evidenceTrust.statesByKind.${kind}.${channel} must be a non-empty set of ${states.join(' | ')}`);
+      }
+    }
+  }
+}
 
 const SEGMENT = /^[a-z0-9][a-z0-9.-]*$/;
 
@@ -48,5 +132,6 @@ export function parseEditionContract(contract) {
   if (segments.size !== channels.length) {
     throw new Error('edition-contract.json: the channels\' namespace segments must differ');
   }
+  assertDescriptorVocabulary(contract);
   return contract;
 }

package/edition/edition-contract.json

@@ -1,5 +1,5 @@
 {
-  "schema": "xema.edition-contract/v2",
+  "schema": "xema.edition-contract/v3",
   "vendoring": "This file is the single source of the edition artifact coordinates and names. A consumer vendors it BYTE-IDENTICAL from a stated xema-cli commit and never edits it. It reads both repository namespace segments (repositories.<channel>.namespaceSegment) and the repository prefix (repositoryPrefix) only from this file, and refuses a contract that has no `repositories`.",
   "artifactType": "application/vnd.xema.edition.v1+json",
   "repositoryPrefix": "xema-edition-",
@@ -12,7 +12,18 @@
     }
   },
   "descriptorFile": "xema-edition.json",
-  "descriptorSchema": "xema.edition/v1",
+  "descriptorSchema": "xema.edition/v2",
+  "descriptorKinds": [
+    "resolved",
+    "sealed"
+  ],
+  "sealOf": {
+    "pattern": "^[a-z0-9.-]+(:[0-9]+)?(/[a-z0-9._-]+)+@sha256:[0-9a-f]{64}$",
+    "names": "the digest-pinned ref (<registry>/<path>@sha256:<64 hex>) of the one resolved edition a sealed edition seals; a sealed descriptor carries it and no other descriptor does. A consumer reads the pattern from here (a JavaScript RegExp source, anchored) and restates it nowhere",
+    "repository": "beyond the pattern: the repository of sealOf (everything before @) is an edition repository, <registry root>/<repositories.<channel>.namespaceSegment>/<repositoryPrefix><distributionId>, whose channel is sealOf.channel and whose distributionId is the sealed descriptor's distributionId",
+    "channel": "release",
+    "sealedEdition": "a seal is release-only: only a resolved edition of sealOf.channel is sealed (a resolved edition of any other channel is refused), and the sealed edition is pushed to the repository of that channel (repositories.<sealOf.channel>) and records provenance.channel sealOf.channel"
+  },
   "locks": [
     "distribution.lock.json",
     "images.lock.json",
@@ -30,11 +41,43 @@
   "evidenceTrust": {
     "states": {
       "armed": "the data root declares an evidence trust policy that is pinned and ARMED on the channel of the edition",
-      "not-armed": "a develop edition only: its data root declares no policy, or one that is not armed on the develop channel. A release edition never records not-armed"
+      "not-armed": "a RESOLVED edition of the develop channel only (vendor or customer): its data root declares no policy, or one that is UNARMED on the develop channel. A customer develop edition always records it while a develop catalogue carries no edition-catalogue (E4) evidence. A sealed edition, and a resolved edition of any other channel, never records not-armed"
+    },
+    "statesByKind": {
+      "resolved": {
+        "develop": [
+          "armed",
+          "not-armed"
+        ],
+        "release": [
+          "armed"
+        ]
+      },
+      "sealed": {
+        "release": [
+          "armed"
+        ]
+      }
     },
     "refusal": {
       "code": "EVIDENCE_TRUST_REQUIRED_UNARMED",
-      "when": "a release edition is written while the data root's evidence trust policy is not armed on the release channel (none declared, or declared but UNARMED or PARTIALLY ARMED there): no release descriptor or artifact is written, and no configuration key admits one. Arming is judged per channel: a develop edition admits not-armed"
+      "when": "an edition is written while the data root's evidence trust policy is not armed on the channel of the edition (none declared, or declared but UNARMED or PARTIALLY ARMED there) and statesByKind admits only armed for its kind on that channel (every sealed edition; a resolved edition of any channel but develop): no descriptor or artifact is written, and no configuration key admits one. A resolved develop edition records not-armed instead, except under a policy PARTIALLY ARMED on develop, which is refused for every edition"
+    }
+  },
+  "signers": {
+    "oidcIssuer": "https://token.actions.githubusercontent.com",
+    "identity": "the exact keyless certificate identity of a publisher is https://github.com/<repository>/<workflow>@<ref>, issued by oidcIssuer and by nothing else; no wildcard, and no identity signs both kinds",
+    "publishers": {
+      "values": "the publisher of an edition of each kind on each channel is data root data, never this contract's: <data root>/edition-workspace.json editionPublishers.<kind>.<channel>, each exactly publishers.shape; a publisher the data root does not declare is refused by name, with no default and no fallback",
+      "channelsByKind": {
+        "resolved": ["develop", "release"],
+        "sealed": ["release"]
+      },
+      "shape": {
+        "repository": "^[A-Za-z0-9][A-Za-z0-9-]*/[A-Za-z0-9._-]+$",
+        "workflow": "^\\.github/workflows/[A-Za-z0-9._-]+\\.ya?ml$",
+        "ref": "^refs/heads/[A-Za-z0-9._/-]+$"
+      }
     }
   }
 }

package/edition/edition-image-seal.mjs

@@ -10,7 +10,8 @@
 // sealed is the digest the registry serves for `<repository>:<contentHash>`.
 //
 // A coordinate that is not there is "not built yet": the producer's CI is not
-// green or still running. EVERY such subject is collected and named at once;
+// green or still running. A third-party subject (a pinned OCI biome's image) is never re-homed and never "not built":
+// it keeps its pinned imageRef and is verified BY the pin's manifest digest (third-party-image-pins.mjs). EVERY such subject is collected and named at once;
 // any other failure (a 403, a malformed index, an absent required platform)
 // aborts as it does in the release.
 
@@ -20,6 +21,7 @@ import { EditionChannel } from './edition-channel.mjs';
 import { editionsRoot } from './edition-workspace.mjs';
 import { validateImmutableImageLock, loadKernelDistributionSchemas, } from './lib.mjs';
 import { isNotPublishedYet, planDigestSeal } from './seal-image-digests.mjs';
+import { imageSubjectKey, pinnedManifestDigests, thirdPartyImagePins } from './third-party-image-pins.mjs';
 import { verifyDistributionPlatforms } from './verify-image-platforms.mjs';
 
 /** The repository a channel's own image subjects are verified and sealed in, from the subject's release imageRef. */
@@ -45,21 +47,25 @@ export function channelImageRef(channel, releaseImageRef) {
  * @param {string} request.channel `develop` or `release`: which repositories the subjects are sealed in
  * @param {string} request.distributionId the edition the subjects belong to (named in refusals)
  * @param {object[]} request.subjects image subjects (release refs, unsealed)
+ * @param {{byRepository: (repository: string) => object|undefined}} [request.thirdPartyPins] the data root's third-party
+ *   source pins: a subject of a pinned repository keeps its imageRef and is sealed at the pin's manifest digest
  * @returns the subjects with the channel's refs and verified digests
  */
 export async function sealImageSubjects({
   channel,
   distributionId,
   subjects,
+  thirdPartyPins = undefined,
   distributionsRoot = editionsRoot(),
   env = process.env,
   fetchImpl = globalThis.fetch,
   run = null,
   progress = null,
 }) {
+  const pinnedImages = thirdPartyPins === undefined ? new Map() : thirdPartyImagePins({ pins: thirdPartyPins, subjects });
   const channelSubjects = subjects.map((subject) => ({
     ...subject,
-    imageRef: channelImageRef(channel, subject.imageRef),
+    imageRef: pinnedImages.has(imageSubjectKey(subject)) ? subject.imageRef : channelImageRef(channel, subject.imageRef),
   }));
   const report = await verifyDistributionPlatforms({
     imageLock: { distributionId, subjects: channelSubjects },
@@ -69,6 +75,7 @@ export async function sealImageSubjects({
     run,
     collectFailures: true,
     progress,
+    pinnedDigests: pinnedManifestDigests(pinnedImages),
   });
   const aborting = report.failures.find(({ error }) => !isNotPublishedYet(error));
   if (aborting) {throw aborting.error;}

package/edition/edition-kind.mjs

@@ -0,0 +1,10 @@
+// edition-kind — the closed vocabularies of an edition descriptor (xema.edition/v2) that the
+// contract (edition-contract.json) names: the lock KIND and the evidence trust STATE. They are
+// enums here so a reader branches on names, and edition-contract-parse holds the contract to
+// exactly these sets: a contract that names another kind or state is refused, never read.
+
+/** What an edition IS: a lock resolved by a resolve run, or the seal of one exact resolved edition (`sealOf`). */
+export const EditionKind = Object.freeze({ Resolved: 'resolved', Sealed: 'sealed' });
+
+/** Whether the data root's editions are evidence-gated, as the descriptor records it. */
+export const EvidenceTrustState = Object.freeze({ Armed: 'armed', NotArmed: 'not-armed' });

package/edition/edition-protocol.mjs

@@ -31,11 +31,17 @@ import { readBoundedNoFollowFile } from './no-follow-file.mjs';
 /** The edition protocols this library interprets: version -> content digest. A protocol is listed only
  * while every kernel published under it exports what this library imports (`kernel-export-coverage.test.mjs`):
  * v27 and older kernels lack `serviceImageSubjects` (first exported by the v28 kernel), so they are not listed.
- * No published kernel declares v29 (0.110.2 is v28, 0.110.3 is v30, 0.111.0 is v31), so v29 is not listed either. */
+ * No published kernel declares v29 (0.110.2 is v28, 0.110.3 is v30, 0.111.0 is v31, XEMA-2070 kernel is v32; v33 is the kernel's
+ * bundle-signer protocol (`bundleSigner` on every OCI bundle row); v34 is the kernel's output-mapping, JSON Pointer and
+ * handoff-repair-turns closure additions (XEMA-2122); v33 and v34 are not yet published: their identities and contracts are captured from the
+ * linked kernel), so v29 is not listed either. */
 export const SUPPORTED_EDITION_PROTOCOLS = Object.freeze([
   Object.freeze({ version: 28, contentDigest: 'f7795478b1bfe9a41bcbea9efe496011fcd209a56c90294029a08801e84cf92c' }),
   Object.freeze({ version: 30, contentDigest: '91e3cdff255778b5aa94b64ca9316d031be549ead2267a9a9311ff06d4f1db2c' }),
   Object.freeze({ version: 31, contentDigest: 'b2026847fdd202e7b9e05815cdc2c9819b60be7007c789cc5b5f291c9c682fdd' }),
+  Object.freeze({ version: 32, contentDigest: 'a4ca824486052ca7f61b9a68f759b798defb620b6b3e9cbaab2c701bee2c6700' }),
+  Object.freeze({ version: 33, contentDigest: 'b070713e7abeeefad6da3a9053843b0f7420a466f6d504f60aaa00ef196b2b05' }),
+  Object.freeze({ version: 34, contentDigest: '370ceef5956d66035265ddbf7b9c46aa686cd10c1e95171c806c0d590ef5f49c' }),
 ]);
 
 /** Where a kernel package publishes its identity and its contract, package-relative. */

package/edition/edition-publisher.mjs

@@ -0,0 +1,21 @@
+// edition-publisher — the grammar of an edition publisher: the exact GitHub Actions workflow whose keyless
+// signature admits an edition. `{repository, workflow, ref}`, each held to edition-contract.json
+// signers.publishers.shape; its certificate identity is `https://github.com/<repository>/<workflow>@<ref>`
+// (signers.identity), never a wildcard. The issuer is the contract's (edition-constants.mjs); the publisher
+// VALUES are the data root's (edition-workspace.json editionPublishers, edition-config.mjs).
+
+import { EDITION_CONTRACT } from './edition-constants.mjs';
+
+const SHAPE = Object.freeze(Object.fromEntries(Object.entries(EDITION_CONTRACT.signers.publishers.shape).map(([field, source]) => [field, new RegExp(source)])));
+
+/** Hold `publisher` to exactly `{repository, workflow, ref}`, each in the contract's shape; returns it. */
+export function assertPublisher(publisher, where) {
+  const keys = publisher !== null && typeof publisher === 'object' && !Array.isArray(publisher) ? Object.keys(publisher).sort().join() : '';
+  if (keys !== 'ref,repository,workflow' || !Object.entries(SHAPE).every(([field, pattern]) => typeof publisher[field] === 'string' && pattern.test(publisher[field]))) {
+    throw new Error(`${where} must be exactly {repository: <owner>/<name>, workflow: .github/workflows/<file>.yaml, ref: refs/heads/<branch>} (edition-contract.json signers.publishers.shape; got ${JSON.stringify(publisher)})`);
+  }
+  return publisher;
+}
+
+/** The exact keyless certificate identity of a publisher. */
+export const publisherIdentity = ({ repository, workflow, ref }) => `https://github.com/${repository}/${workflow}@${ref}`;

package/edition/edition-seal.mjs

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+// edition-seal — seal ONE exact resolved edition.
+//
+//   xema edition seal --resolved <registry root>/<channel segment>/xema-edition-<id>@sha256:<64 hex>
+//                     --manifest <file> --artifact <dir> --out <dir>
+//                     --cosign <absolute path> --resolve-workflow-sha <40 hex>
+//                     [--local]
+//                     --data-root <dir> --editions-root <dir> --kernel <dir>
+//
+// FIRST, the seal verifies its input and fails closed: `cosign verify` of --resolved (the manifest digest),
+// through the one pinned-cosign path (pinned-cosign.mjs: the caller's cosign held to the digest the data root's
+// pinned policy names, `--offline` against the policy's pinned trusted root), with every certificate constraint
+// (cosign-certificate-constraints.mjs): the identity of the RESOLVE publisher, the contract's issuer (never
+// overridden), its workflow repository and ref, and --resolve-workflow-sha, the commit the resolve workflow ran
+// at (it only narrows the constraint: a wrong value fails the verify). The publisher is the data root's resolved
+// publisher of the --resolved repository's channel (edition-workspace.json editionPublishers.resolved.<channel>,
+// refused by name when undeclared: no default, and no flag names another). Its repository must be the
+// repository the resolved descriptor records as its workflow (provenance.workflow.repository), checked before
+// cosign runs. A refused or unrunnable verify writes nothing.
+//
+// The caller pulls the resolved edition BY DIGEST (`oras manifest fetch` into --manifest, `oras pull`
+// into --artifact). A seal is RELEASE-ONLY (edition-contract.json sealOf.channel, D99): a --resolved edition of any
+// other channel is refused by name, and the sealed edition records provenance.channel release and goes to the
+// release repository. Nothing pulled is trusted until it is proven to be the edition --resolved names:
+//
+//   * the manifest bytes hash to the --resolved digest, it is an edition artifact (artifactType), and
+//     every layer is titled with a file an edition may hold, once;
+//   * every pulled file hashes to the digest of its layer, and the artifact holds no other file;
+//   * the descriptor parses (xema.edition/v2) and is `kind: resolved`, of the distribution and the
+//     channel the --resolved repository names.
+//
+// The sealed edition (written to --out, outside the committed trees) holds every layer of the resolved
+// edition but its descriptor BYTE FOR BYTE, plus a `kind: sealed` descriptor naming --resolved as `sealOf`,
+// with the resolved edition's channel (release), pins and engine image and the seal run as provenance.workflow.
+// A seal must be ARMED (edition-contract.json evidenceTrust.statesByKind): the data root's evidence trust
+// policy is judged on the resolved edition's channel, and anything but armed is refused by name
+// (EvidenceTrustRequiredError, EVIDENCE_TRUST_REQUIRED_UNARMED). The sealed repository is printed:
+// the same registry root, the release namespace segment. The workflow pushes --out there and signs the
+// manifest digest with the SEAL identity; who may seal is the signer's, not this command's.
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import { certificateConstraintArgs } from './cosign-certificate-constraints.mjs';
+import { LOCAL_WORKFLOW, editionRepository, parseEditionDescriptor, parseSealOf, workflowFromEnv, writeSealedEditionArtifact } from './edition-artifact.mjs';
+import { editionPublisher } from './edition-config.mjs';
+import {
+  CATALOGUE_PIN_KEY,
+  EDITION_ARTIFACT_TYPE,
+  EDITION_DESCRIPTOR_FILE,
+  EDITION_FILES,
+  EDITION_SIGNER_OIDC_ISSUER,
+  EDITION_OFFERING_LAYERS,
+  EditionKind,
+  SEALED_EDITION_CHANNEL,
+} from './edition-constants.mjs';
+import { publisherIdentity } from './edition-publisher.mjs';
+import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule } from './edition-workspace.mjs';
+import { descriptorEvidenceTrust } from './evidence-trust-policy.mjs';
+import { sha256Hex } from './lib.mjs';
+import { cosignEnvironment, withPinnedCosign } from './pinned-cosign.mjs';
+import { splitImageRef } from './registry-credentials.mjs';
+import { parseStrictJson } from './strict-json.mjs';
+
+if (isEntryModule(import.meta.url)) {
+  configureEditionWorkspaceFromProcess([WorkspaceRoot.Data, WorkspaceRoot.Editions, WorkspaceRoot.Kernel]);
+}
+
+const REQUIRED_FLAGS = Object.freeze(['--resolved', '--manifest', '--artifact', '--out', '--cosign', '--resolve-workflow-sha']);
+const VALUE_FLAGS = REQUIRED_FLAGS;
+const USAGE =
+  'usage: seal --resolved <repository>@sha256:<digest> --manifest <file> --artifact <dir> --out <dir> --cosign <absolute path> ' +
+  '--resolve-workflow-sha <40 hex> [--local]';
+const WORKFLOW_SHA = /^[0-9a-f]{40}$/;
+const TITLE = 'org.opencontainers.image.title';
+/** Every file an edition artifact may hold: the descriptor, the locks, the offering layers. */
+const ADMITTED_FILES = Object.freeze([...EDITION_FILES, ...Object.values(EDITION_OFFERING_LAYERS)]);
+
+/** Parse the argv after the `seal` verb: every value flag exactly once, `--local` optional, nothing else. */
+export function parseSealArgs(argv) {
+  const options = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--local') {
+      options[arg] = true;
+    } else if (VALUE_FLAGS.includes(arg)) {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith('--')) {throw new Error(`${arg} requires a value`);}
+      if (arg in options) {throw new Error(`${arg} is given twice`);}
+      options[arg] = value;
+      i += 1;
+    } else {
+      throw new Error(`unknown argument ${arg} for seal (${USAGE})`);
+    }
+  }
+  const missing = REQUIRED_FLAGS.filter((flag) => !(flag in options));
+  if (missing.length > 0) {throw new Error(`seal requires ${missing.join(', ')} (${USAGE})`);}
+  if (!WORKFLOW_SHA.test(options['--resolve-workflow-sha'])) {
+    throw new Error(`--resolve-workflow-sha ${JSON.stringify(options['--resolve-workflow-sha'])} is not the 40-hex commit the resolve workflow ran at`);
+  }
+  return options;
+}
+
+/**
+ * Prove the pulled manifest and files are the resolved edition `sealOf` names, and return
+ * `{ resolved, layers }`: its parsed descriptor and every other layer's bytes by title.
+ *
+ * @param {{ sealOf: string, manifestBytes: Buffer, artifactDir: string }} input
+ */
+export function readResolvedEdition({ sealOf, manifestBytes, artifactDir }) {
+  const ref = parseSealOf(sealOf);
+  if (ref.channel !== SEALED_EDITION_CHANNEL) {
+    throw new Error(
+      `${sealOf} is a ${ref.channel} edition: a seal is ${SEALED_EDITION_CHANNEL}-only (edition-contract.json sealOf.channel); ` +
+        `seal the resolved ${SEALED_EDITION_CHANNEL} edition of "${ref.distributionId}" instead`,
+    );
+  }
+  if (`sha256:${sha256Hex(manifestBytes)}` !== ref.digest) {
+    throw new Error(`the manifest given hashes to sha256:${sha256Hex(manifestBytes)}, not to ${ref.digest}: it is not the manifest of ${sealOf}`);
+  }
+  const manifest = parseStrictJson(manifestBytes.toString('utf8'), 'the manifest');
+  if (manifest?.artifactType !== EDITION_ARTIFACT_TYPE || !Array.isArray(manifest.layers)) {
+    throw new Error(`${sealOf} is not an edition artifact (artifactType ${JSON.stringify(manifest?.artifactType)}, expected ${EDITION_ARTIFACT_TYPE})`);
+  }
+  const digestByTitle = new Map();
+  for (const layer of manifest.layers) {
+    const title = layer?.annotations?.[TITLE];
+    if (!ADMITTED_FILES.includes(title)) {
+      throw new Error(`${sealOf} carries a layer titled ${JSON.stringify(title)}, which is not a file an edition holds (${ADMITTED_FILES.join(', ')})`);
+    }
+    if (digestByTitle.has(title)) {throw new Error(`${sealOf} carries two layers titled ${title}`);}
+    digestByTitle.set(title, layer.digest);
+  }
+  const pulled = readdirSync(artifactDir).sort();
+  const expected = [...digestByTitle.keys()].sort();
+  if (pulled.join('\0') !== expected.join('\0')) {
+    throw new Error(`${artifactDir} holds ${pulled.join(', ') || 'nothing'}, but ${sealOf} has the layers ${expected.join(', ')}; pull exactly that artifact`);
+  }
+  const layers = new Map();
+  let descriptorBytes;
+  for (const [title, digest] of digestByTitle) {
+    const bytes = readFileSync(join(artifactDir, title));
+    if (`sha256:${sha256Hex(bytes)}` !== digest) {
+      throw new Error(`${join(artifactDir, title)} hashes to sha256:${sha256Hex(bytes)}, not to its layer digest ${digest} in ${sealOf}`);
+    }
+    if (title === EDITION_DESCRIPTOR_FILE) {descriptorBytes = bytes;} else {layers.set(title, bytes);}
+  }
+  if (descriptorBytes === undefined) {throw new Error(`${sealOf} carries no ${EDITION_DESCRIPTOR_FILE}`);}
+  const resolved = parseEditionDescriptor(parseStrictJson(descriptorBytes.toString('utf8'), `${sealOf} ${EDITION_DESCRIPTOR_FILE}`));
+  if (resolved.kind !== EditionKind.Resolved) {
+    throw new Error(`${sealOf} is a ${resolved.kind} edition; a seal seals exactly one resolved edition`);
+  }
+  if (resolved.distributionId !== ref.distributionId || resolved.provenance.channel !== ref.channel) {
+    throw new Error(
+      `${sealOf} is the ${ref.channel} repository of "${ref.distributionId}", but its descriptor records the ${resolved.provenance.channel} edition "${resolved.distributionId}"`,
+    );
+  }
+  return { resolved, layers };
+}
+
+/**
+ * The resolve publisher a seal verifies against: ONLY the data root's edition-workspace.json
+ * editionPublishers.resolved.<channel> (refused by name when undeclared; no flag or default names another), and only
+ * when its repository is the one the resolved descriptor records as its workflow: a seal never verifies an edition
+ * against a publisher its own provenance does not name. Checked before cosign runs.
+ */
+export function resolvePublisher(resolved, sealOf) {
+  const channel = resolved.provenance.channel;
+  const publisher = editionPublisher(EditionKind.Resolved, channel);
+  const recorded = resolved.provenance.workflow?.repository;
+  if (publisher.repository !== recorded) {
+    throw new Error(
+      `${sealOf} records its resolve workflow in ${JSON.stringify(recorded)}, but the data root's resolved ${channel} publisher ` +
+        `(edition-workspace.json editionPublishers.resolved.${channel}) is in "${publisher.repository}": a seal verifies an edition only ` +
+        'against the publisher its provenance names; nothing is sealed',
+    );
+  }
+  return publisher;
+}
+
+/**
+ * `cosign verify` of `sealOf` against the exact resolve publisher, through the one pinned-cosign path. Throws, naming
+ * the publisher, when cosign refuses (unsigned, another identity, another commit) or cannot run; returns nothing.
+ *
+ * @param {{ sealOf: string, publisher: {repository: string, workflow: string, ref: string}, workflowSha: string, cosignBinary: string, env: object, pinned?: object }} input
+ *   `pinned` are withPinnedCosign's injections (tests)
+ */
+export async function verifyResolvedSignature({ sealOf, publisher, workflowSha, cosignBinary, env, pinned = {} }) {
+  const signer = {
+    certificateIdentity: publisherIdentity(publisher),
+    oidcIssuer: EDITION_SIGNER_OIDC_ISSUER,
+    githubWorkflow: { repository: publisher.repository, ref: publisher.ref },
+  };
+  const constraints = certificateConstraintArgs(signer, workflowSha);
+  const { authority } = splitImageRef(parseSealOf(sealOf).repository);
+  await withPinnedCosign({ cosignBinary, env, ...pinned }, async ({ runCosign, cosignEnvFor, trustedRootPath }) => {
+    let result;
+    try {
+      result = await runCosign(['verify', '--offline', '--trusted-root', trustedRootPath, ...constraints, sealOf], cosignEnvironment(cosignEnvFor, authority));
+    } catch (error) {
+      throw new Error(`cosign could not run for ${sealOf}: ${error.message}; nothing is sealed`);
+    }
+    if (result.code !== 0) {
+      throw new Error(
+        `cosign refused ${sealOf} as signed by the resolve publisher ${signer.certificateIdentity} (issuer ${EDITION_SIGNER_OIDC_ISSUER}, ` +
+          `workflow commit ${workflowSha}) (exit ${result.code}): ${String(result.stderr).trim()}; nothing is sealed`,
+      );
+    }
+  });
+}
+
+/**
+ * Seal: prove the pulled edition by digest, verify the resolve publisher's signature over it, require an ARMED policy
+ * on its channel, write the sealed edition. Returns `{ descriptor, repository }`; the repository is where the sealed edition goes.
+ */
+export async function sealEdition({ options, env, evidenceTrust = descriptorEvidenceTrust, pinned = {} }) {
+  const sealOf = options['--resolved'];
+  const { resolved, layers } = readResolvedEdition({
+    sealOf,
+    manifestBytes: readFileSync(options['--manifest']),
+    artifactDir: resolve(options['--artifact']),
+  });
+  const channel = resolved.provenance.channel;
+  await verifyResolvedSignature({
+    sealOf,
+    publisher: resolvePublisher(resolved, sealOf),
+    workflowSha: options['--resolve-workflow-sha'],
+    cosignBinary: options['--cosign'],
+    env,
+    pinned,
+  });
+  const evidenceTrustPolicy = await evidenceTrust({
+    kind: EditionKind.Sealed,
+    channel,
+    consumesCatalogue: CATALOGUE_PIN_KEY in resolved.provenance.pins,
+  });
+  const descriptor = writeSealedEditionArtifact({
+    outDir: resolve(options['--out']),
+    resolved,
+    sealOf,
+    layers,
+    workflow: options['--local'] ? LOCAL_WORKFLOW : workflowFromEnv(env),
+    evidenceTrustPolicy,
+  });
+  const repository = editionRepository(resolved.distributionId, parseSealOf(sealOf).registryRoot, SEALED_EDITION_CHANNEL);
+  return { descriptor, repository };
+}
+
+if (isEntryModule(import.meta.url)) {
+  Promise.resolve()
+    .then(() => sealEdition({ options: parseSealArgs(process.argv.slice(2)), env: process.env }))
+    .then(({ repository }) => console.log(repository))
+    .catch((error) => {
+      console.error(`[edition-seal] ${error.message}`);
+      process.exit(1);
+    });
+}

package/edition/evidence-grammars.mjs

@@ -12,5 +12,7 @@ export const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/;
 export const SHA256_DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
 /** `owner/repository` of a GitHub repository. */
 export const GITHUB_REPOSITORY_PATTERN = /^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/;
+/** A policy, subject or run identifier: alphanumeric ends, `._:/@+-` inside, at most 256 characters. */
+export const CANONICAL_IDENTIFIER = /^[a-zA-Z0-9](?:[a-zA-Z0-9._:/@+-]{0,254}[a-zA-Z0-9])?$/;
 /** A GitHub branch or tag ref. */
 export const GITHUB_REF_PATTERN = /^refs\/(?:heads|tags)\/.+$/;