@xemahq/edition-tooling 0.0.0-stage → 0.1.0

package/edition/third-party-source-evidence.mjs

@@ -0,0 +1,326 @@
+// Re-verification of ONE third-party source pin from its COMMITTED evidence (XEMA-1611 design section 3, checks
+// (a) to (d)). The trusted writer runs it on the evidence it is about to commit, and `--check-third-party` runs it
+// on the committed tree, so the two cannot disagree about what a pin proves. Nothing here reads a network: the
+// signatures are verified by `verifySigstoreEvidenceDescriptor` (cosign `verify-blob-attestation --offline` against the
+// pinned trusted root, the tlog inclusion proof taken from the committed bundle, never `--insecure-ignore-tlog`).
+//
+// Where the evidence lives, relative to the data root:
+//   third-party-provenance/sha256-<bundle manifest hex>/{statement.json,bundle.sigstore.json}
+//       the SLSA provenance attestation of the biome bundle (the bytes cosign signed, which are not canonical JSON),
+//       and its signature as a Sigstore bundle v0.1 (`PROVENANCE_BUNDLE_MEDIA_TYPE`): publishers attest in the classic
+//       cosign format, whose Rekor entry carries a signed entry timestamp (an inclusion promise), not an inclusion proof;
+//   evidence/sha256-<image manifest hex>/producer-evidence.json (+ statements/, bundles/)
+//       the image-source/v2 evidence, stored the way a first-party producer commits it.
+
+import { EvidenceSubjectKind, isAuthorityBound } from './authority-binding.mjs';
+import { assertProducerTtlCeiling, decodeExactUtf8, evidenceDirectoryForDigest, policyCandidates, verifySigstoreEvidenceDescriptor } from './image-evidence.mjs';
+import { assertKernelContractAuthorityEqual } from './kernel-contract-authority.mjs';
+import { readBoundedNoFollowFile } from './no-follow-file.mjs';
+import { PRODUCER_EVIDENCE_INDEX_FILE } from './producer-evidence-index-file.mjs';
+import { BUNDLE_MEDIA_TYPE } from './sigstore-bundle-media-type.mjs';
+import { soleImageSignerRow } from './third-party-admission.mjs';
+import { assertCertificateExtensions } from './third-party-certificate-extensions.mjs';
+
+export const THIRD_PARTY_PROVENANCE_ROOT = 'third-party-provenance';
+export const PROVENANCE_STATEMENT_FILE = 'statement.json';
+export const PROVENANCE_BUNDLE_FILE = 'bundle.sigstore.json';
+/**
+ * The committed provenance signature is a Sigstore bundle v0.1, the form a classic `cosign attest` entry (certificate,
+ * Rekor v1 entry with its signed entry timestamp) takes; v0.2+ requires an inclusion proof a classic entry does not carry.
+ */
+export const PROVENANCE_BUNDLE_MEDIA_TYPE = 'application/vnd.dev.sigstore.bundle+json;version=0.1';
+/** The SLSA v1 provenance predicate a biome bundle is attested with (what the fetcher's `verify-attestation --type` matches). */
+export const SLSA_PROVENANCE_V1 = 'https://slsa.dev/provenance/v1';
+export const GITHUB_ACTIONS_OIDC_ISSUER = 'https://token.actions.githubusercontent.com';
+/** The only channel a third-party source is admitted on: signed from refs/heads/main. */
+export const THIRD_PARTY_EVIDENCE_CHANNEL = 'release';
+
+const MAX_EVIDENCE_INDEX_BYTES = 4 * 1024 * 1024;
+/** `cosign attest --type slsaprovenance1` wraps the predicate in an in-toto v0.1 statement; v1 is the same subject shape. */
+const IN_TOTO_STATEMENT_TYPES = new Set(['https://in-toto.io/Statement/v0.1', 'https://in-toto.io/Statement/v1']);
+
+/** `third-party-provenance/sha256-<hex>` of an OCI manifest digest. */
+export function provenanceDirectoryForDigest(manifestDigest) {
+  return `${THIRD_PARTY_PROVENANCE_ROOT}/${evidenceDirectoryForDigest(manifestDigest).split('/')[1]}`;
+}
+
+/** The digest of an `<oci repository>@sha256:<hex>` reference. */
+export const digestOfOciRef = (ociRef) => ociRef.slice(ociRef.indexOf('@') + 1);
+
+/** The statement bytes are the DSSE payload cosign signed: exact UTF-8 JSON, not this CLI's canonical form. */
+export function decodeJsonStatement(bytes, label) {
+  try {
+    return JSON.parse(decodeExactUtf8(bytes, label));
+  } catch (error) {
+    throw new Error(`${label} is not exact UTF-8 JSON: ${error.message}`);
+  }
+}
+
+/** The in-toto statement of a provenance attestation, held to the shape this plane reads (subject digest, predicate type). */
+export function parseProvenanceStatement(value) {
+  const digest = value?.subject?.[0]?.digest?.sha256;
+  if (
+    !IN_TOTO_STATEMENT_TYPES.has(value?._type) ||
+    value.predicateType !== SLSA_PROVENANCE_V1 ||
+    !Array.isArray(value.subject) ||
+    value.subject.length !== 1 ||
+    typeof digest !== 'string'
+  ) {
+    throw new Error(
+      `the bundle provenance is not an in-toto statement of ${SLSA_PROVENANCE_V1} over exactly one subject`,
+    );
+  }
+  return value;
+}
+
+const readEvidenceFile = (root, path, label, maxBytes) => readBoundedNoFollowFile(root, path, label, maxBytes);
+
+/**
+ * A keyless signer row of `channel`, held to everything such a row must be: the channel signed from that channel's ref, the
+ * GitHub Actions issuer and the exact identity of its own workflow. Throws naming the row and the field.
+ */
+export function assertChannelSignerRow({ row, channel, schemas, label }) {
+  const ref = schemas.EVIDENCE_CHANNEL_REFS[channel];
+  if (row.channel !== channel || row.githubWorkflow?.ref !== ref) {
+    throw new Error(
+      `${label}: row "${row.policyId}" is not a ${channel} row signed from ${ref} ` +
+        `(channel ${JSON.stringify(row.channel)}, ref ${JSON.stringify(row.githubWorkflow?.ref)})`,
+    );
+  }
+  if (row.oidcIssuer !== GITHUB_ACTIONS_OIDC_ISSUER) {
+    throw new Error(`${label}: row "${row.policyId}" oidcIssuer ${JSON.stringify(row.oidcIssuer)} is not ${GITHUB_ACTIONS_OIDC_ISSUER}`);
+  }
+  const { repository, path } = row.githubWorkflow;
+  const identity = `https://github.com/${repository}/${path}@${ref}`;
+  if (row.certificateIdentity !== identity) {
+    throw new Error(`${label}: row "${row.policyId}" certificateIdentity ${JSON.stringify(row.certificateIdentity)} is not the exact workflow identity ${identity}`);
+  }
+  return row;
+}
+
+/**
+ * The ONE `channel` row that signs the SLSA provenance of `repository`'s biome bundles, held to `assertChannelSignerRow`.
+ * None, or several, is refused naming the repository and the channel.
+ */
+export function bundleSignerRowFor({ policy, repository, channel, schemas, label }) {
+  const rows = policy.policies.filter(
+    (row) => row.channel === channel && row.predicateTypes?.includes(SLSA_PROVENANCE_V1) && row.githubWorkflow?.repository === repository,
+  );
+  if (rows.length !== 1) {
+    throw new Error(
+      `${label}: the trust policy has ${rows.length} ${channel} rows authorizing ${SLSA_PROVENANCE_V1} for ${repository}; exactly one bundle-signer row is required`,
+    );
+  }
+  return assertChannelSignerRow({ row: rows[0], channel, schemas, label });
+}
+
+/**
+ * The trust-policy row `policyId` names, held to everything a third-party signer row must be: one row, the release
+ * channel signed from refs/heads/main, the GitHub Actions issuer, the exact identity of its own workflow, the source's
+ * repository, and `workflowPath`, the workflow the pin records for the ONE artifact this row signs (the bundle's
+ * `signerWorkflow`, an image's `producerWorkflow`). Throws naming the row and the field.
+ */
+export function thirdPartySignerRow({ policy, policyId, source, workflowPath, schemas, label }) {
+  const rows = policy.policies.filter((row) => row.policyId === policyId);
+  if (rows.length !== 1) {
+    throw new Error(`${label}: the trust policy has ${rows.length} rows with policyId "${policyId}"; exactly one is required`);
+  }
+  const row = thirdPartySourceRow({ row: rows[0], source, schemas, label });
+  if (row.githubWorkflow.path !== workflowPath) {
+    throw new Error(`${label}: row "${policyId}" signs workflow ${row.githubWorkflow.path}, but the pin records workflow ${workflowPath}`);
+  }
+  return row;
+}
+
+/** `row` held to `assertChannelSignerRow` on the release channel and to the source's repository. */
+function thirdPartySourceRow({ row, source, schemas, label }) {
+  assertChannelSignerRow({ row, channel: THIRD_PARTY_EVIDENCE_CHANNEL, schemas, label });
+  if (row.githubWorkflow.repository !== source.repository) {
+    throw new Error(`${label}: row "${row.policyId}" signs for ${row.githubWorkflow.repository}, but the source is pinned to ${source.repository}`);
+  }
+  return row;
+}
+
+/**
+ * The ONE release image-source row listing `imageRef` (`soleImageSignerRow`), held to `thirdPartySourceRow`: none,
+ * several, or one of another repository is refused. This is the row the writer pins for the image.
+ */
+export function soleThirdPartyImageRow({ policy, source, imageRef, schemas, label }) {
+  const rows = policyCandidates(policy, schemas.IMAGE_PRODUCER_PREDICATE_TYPE, THIRD_PARTY_EVIDENCE_CHANNEL, imageRef);
+  return thirdPartySourceRow({ row: soleImageSignerRow({ rows, imageRef, channel: THIRD_PARTY_EVIDENCE_CHANNEL, label }), source, schemas, label });
+}
+
+/** The policy narrowed to ONE row, so cosign is run with exactly that row's identity and issuer. */
+const exactRowPolicy = (policy, row) => ({ ...policy, policies: [row] });
+
+function verifiedBundleProvenance({ source, evidenceRoot, context, hold }) {
+  const label = `third-party source "${source.name}" bundle ${source.bundle.ociRef}`;
+  const row = thirdPartySignerRow({
+    policy: context.policy,
+    policyId: source.bundle.signerPolicyId,
+    source,
+    workflowPath: source.bundle.signerWorkflow,
+    schemas: context.schemas,
+    label,
+  });
+  if (!row.predicateTypes.includes(SLSA_PROVENANCE_V1)) {
+    throw new Error(`${label}: row "${row.policyId}" does not authorize ${SLSA_PROVENANCE_V1}, so it is not a bundle signer`);
+  }
+  const directory = provenanceDirectoryForDigest(digestOfOciRef(source.bundle.ociRef));
+  let verified;
+  try {
+    verified = verifySigstoreEvidenceDescriptor({
+      evidenceRoot,
+      descriptor: {
+        statementPath: `${directory}/${PROVENANCE_STATEMENT_FILE}`,
+        statementDigest: source.bundle.statementDigest,
+        bundlePath: `${directory}/${PROVENANCE_BUNDLE_FILE}`,
+        bundleDigest: source.bundle.bundleDigest,
+        bundleMediaType: PROVENANCE_BUNDLE_MEDIA_TYPE,
+      },
+      policy: exactRowPolicy(context.policy, row),
+      policyRoot: context.policyRoot,
+      predicateType: SLSA_PROVENANCE_V1,
+      channel: THIRD_PARTY_EVIDENCE_CHANNEL,
+      expectedWorkflowSha: source.sourceCommit,
+      parseStatement: parseProvenanceStatement,
+      decodeStatement: decodeJsonStatement,
+      trustedCosign: context.trustedCosign,
+      holdProducerWorkflow: hold,
+    });
+  } catch (error) {
+    throw new Error(`${label}: ${error.message}`);
+  }
+  const attested = `sha256:${verified.statement.subject[0].digest.sha256}`;
+  if (attested !== digestOfOciRef(source.bundle.ociRef)) {
+    throw new Error(`${label}: the provenance attests ${attested}, not the pinned bundle digest ${digestOfOciRef(source.bundle.ociRef)}`);
+  }
+  const bundleBytes = readEvidenceFile(evidenceRoot, `${directory}/${PROVENANCE_BUNDLE_FILE}`, `${label} bundle`, 16 * 1024 * 1024).bytes;
+  assertCertificateExtensions({ bundle: JSON.parse(decodeExactUtf8(bundleBytes, `${label} bundle`)), source, signerIdentity: row.certificateIdentity, label });
+  return { row, statement: verified.statement };
+}
+
+/** The `statementPath`/`bundlePath` the committed `producer-evidence.json` of an image's evidence directory gives its subject. */
+export function committedImageDescriptor({ image, evidenceRoot, label }) {
+  const directory = evidenceDirectoryForDigest(image.manifestDigest);
+  const index = JSON.parse(
+    decodeExactUtf8(readEvidenceFile(evidenceRoot, `${directory}/${PRODUCER_EVIDENCE_INDEX_FILE}`, `${label} producer evidence index`, MAX_EVIDENCE_INDEX_BYTES).bytes, `${label} producer evidence index`),
+  );
+  const entries = Array.isArray(index?.producerEvidence) ? index.producerEvidence : [];
+  const entry = entries.find((candidate) => candidate?.subjectKind === image.subjectKind && candidate?.subjectId === image.subjectId);
+  if (entry === undefined) {
+    throw new Error(`${label}: ${directory}/${PRODUCER_EVIDENCE_INDEX_FILE} carries no evidence for ${image.subjectKind}:${image.subjectId}`);
+  }
+  const { statementPath, bundlePath } = entry.evidence;
+  return {
+    statementPath: `${directory}/${statementPath}`,
+    statementDigest: image.statementDigest,
+    bundlePath: `${directory}/${bundlePath}`,
+    bundleDigest: image.bundleDigest,
+    bundleMediaType: BUNDLE_MEDIA_TYPE,
+  };
+}
+
+const repositoryPathOf = (repositoryUrl) => new URL(repositoryUrl).pathname.replace(/^\//u, '').replace(/\.git$/u, '');
+
+/** (c) for one image statement: one repository, one commit, the pinned subject and authority. */
+export function assertImageStatementBindsPin({ statement, source, image, expectedContractAuthority, channel, label }) {
+  const { predicate } = statement;
+  const claimed = predicate.source;
+  const mismatch = (what, actual, expected) => {
+    throw new Error(`${label}: ${what} is ${JSON.stringify(actual)}, but the pin requires ${JSON.stringify(expected)}`);
+  };
+  if (isAuthorityBound(channel, EvidenceSubjectKind.ThirdParty)) {
+    assertKernelContractAuthorityEqual(predicate.contractAuthority, expectedContractAuthority, label);
+  }
+  if (repositoryPathOf(claimed.repositoryUrl) !== source.repository) {
+    mismatch('predicate source.repositoryUrl repository', repositoryPathOf(claimed.repositoryUrl), source.repository);
+  }
+  if (claimed.repo !== source.repository) {mismatch('predicate source.repo', claimed.repo, source.repository);}
+  if (claimed.path !== claimed.repo && !claimed.path.startsWith(`${claimed.repo}/`)) {
+    mismatch('predicate source.path (it must be the repository or a directory of it)', claimed.path, `${source.repository}[/<directory>]`);
+  }
+  if (predicate.producerRun.producerWorkflowSha !== source.sourceCommit) {
+    mismatch('predicate producerRun.producerWorkflowSha (the certificate workflow commit)', predicate.producerRun.producerWorkflowSha, source.sourceCommit);
+  }
+  if (claimed.sourceCommit !== predicate.producerRun.producerWorkflowSha) {
+    mismatch('predicate source.sourceCommit (it must be the commit the certificate was issued for)', claimed.sourceCommit, predicate.producerRun.producerWorkflowSha);
+  }
+  if (claimed.sourceManifestHash !== source.bundle.sourceManifestHash) {
+    mismatch('predicate source.sourceManifestHash', claimed.sourceManifestHash, source.bundle.sourceManifestHash);
+  }
+  if (claimed.kind !== image.subjectKind || claimed.id !== image.subjectId) {
+    mismatch('predicate source kind/id', `${claimed.kind}:${claimed.id}`, `${image.subjectKind}:${image.subjectId}`);
+  }
+  if (claimed.sourceTreeHash !== image.sourceTreeHash) {mismatch('predicate source.sourceTreeHash', claimed.sourceTreeHash, image.sourceTreeHash);}
+  if (claimed.sourceHashAlgorithm !== image.sourceHashAlgorithm) {
+    mismatch('predicate source.sourceHashAlgorithm', claimed.sourceHashAlgorithm, image.sourceHashAlgorithm);
+  }
+  if (predicate.artifact.imageRepository !== image.imageRef || statement.subject[0].name !== image.imageRef) {
+    mismatch('predicate artifact.imageRepository', predicate.artifact.imageRepository, image.imageRef);
+  }
+  if (predicate.artifact.manifestDigest !== image.manifestDigest) {
+    mismatch('predicate artifact.manifestDigest', predicate.artifact.manifestDigest, image.manifestDigest);
+  }
+}
+
+/**
+ * The row an image's evidence is held to: the ONE release row listing the image repository (`soleThirdPartyImageRow`),
+ * which must be the row its pin names, signed from refs/heads/main by the workflow the pin records for this image (not
+ * necessarily the bundle signer's). The commit is the source commit, held by cosign and by `assertImageStatementBindsPin`.
+ */
+export function thirdPartyImageSignerRow({ policy, source, image, schemas, label }) {
+  const sole = soleThirdPartyImageRow({ policy, source, imageRef: image.imageRef, schemas, label });
+  if (sole.policyId !== image.policyId) {
+    throw new Error(`${label}: the one ${THIRD_PARTY_EVIDENCE_CHANNEL} row listing ${image.imageRef} is "${sole.policyId}", but the pin names row "${image.policyId}"`);
+  }
+  return thirdPartySignerRow({ policy, policyId: image.policyId, source, workflowPath: image.producerWorkflow, schemas, label });
+}
+
+function verifiedImageEvidence({ source, image, evidenceRoot, context, hold, channel }) {
+  const label = `third-party source "${source.name}" image ${image.imageRef}@${image.manifestDigest}`;
+  const row = thirdPartyImageSignerRow({ policy: context.policy, source, image, schemas: context.schemas, label });
+  const descriptor = committedImageDescriptor({ image, evidenceRoot, label });
+  let verified;
+  try {
+    verified = verifySigstoreEvidenceDescriptor({
+      evidenceRoot,
+      descriptor,
+      policy: exactRowPolicy(context.policy, row),
+      policyRoot: context.policyRoot,
+      predicateType: context.schemas.IMAGE_PRODUCER_PREDICATE_TYPE,
+      channel: THIRD_PARTY_EVIDENCE_CHANNEL,
+      imageRepository: image.imageRef,
+      expectedWorkflowSha: source.sourceCommit,
+      parseStatement: context.schemas.parseImageProducerStatement,
+      trustedCosign: context.trustedCosign,
+      holdProducerWorkflow: hold,
+    });
+  } catch (error) {
+    throw new Error(`${label}: ${error.message}`);
+  }
+  assertImageStatementBindsPin({ statement: verified.statement, source, image, expectedContractAuthority: context.expectedContractAuthority, channel, label });
+  // The ceiling is held here, at the publisher's door, as well as by verify-evidence: a too-long lifetime is never pinned.
+  assertProducerTtlCeiling({
+    issuedAt: verified.statement.predicate.producerRun.issuedAt,
+    expiresAt: verified.statement.predicate.producerRun.expiresAt,
+    maxTtlSeconds: context.policy.maxProducerTtlSeconds,
+    label,
+  });
+  const bundleBytes = readEvidenceFile(evidenceRoot, descriptor.bundlePath, `${label} bundle`, 16 * 1024 * 1024).bytes;
+  assertCertificateExtensions({ bundle: JSON.parse(decodeExactUtf8(bundleBytes, `${label} bundle`)), source, signerIdentity: row.certificateIdentity, label });
+  return verified.statement;
+}
+
+/**
+ * Checks (a) to (d) for one pin, from the evidence under `evidenceRoot`. `context` is
+ * `{policy, policyRoot, schemas, trustedCosign, expectedContractAuthority, runtimeSourceIndex}`; the runtime
+ * image source index must already carry `{repository, workflowCommit: sourceCommit}` in its `producerWorkflowPins`
+ * (the writer passes the index it is about to write), which `holdProducerWorkflow` then enforces unchanged.
+ */
+export function verifyThirdPartySourceEvidence({ source, evidenceRoot, context, channel }) {
+  const hold = (producer) => context.schemas.producerWorkflowPinRefusal(context.runtimeSourceIndex, producer);
+  const bundle = verifiedBundleProvenance({ source, evidenceRoot, context, hold });
+  const images = source.images.map((image) => verifiedImageEvidence({ source, image, evidenceRoot, context, hold, channel }));
+  return { bundle, images };
+}

package/edition/third-party-source-flags.mjs

@@ -0,0 +1,148 @@
+// The flags of `xema-edition index runtime-image-source --trusted-write --third-party <name>` and of
+// `--check-third-party` (XEMA-1611 design section 3). The writer takes DECLARED facts and proves them; nothing here
+// is derived from a clone of the third-party repository.
+
+import { isAbsolute } from 'node:path';
+
+import { EditionChannel, parseChannelArgs } from './edition-channel.mjs';
+import { COMMIT_PATTERN, GITHUB_REPOSITORY_PATTERN, SHA256_DIGEST_PATTERN } from './evidence-grammars.mjs';
+import { RunnerEnvironment, parseDeclaredRunnerEnvironment } from './fulcio-certificate-extensions.mjs';
+
+export const THIRD_PARTY_FLAG = '--third-party';
+export const CHECK_THIRD_PARTY_FLAG = '--check-third-party';
+export const COSIGN_FLAG = '--cosign';
+export const CHANNEL_FLAG = '--channel';
+/** The environment variable `dist-check` reads the cosign binary of the third-party check from (an absolute path). */
+export const COSIGN_BIN_ENV = 'XEMA_COSIGN_BIN';
+
+const WRITER_FLAGS = Object.freeze({
+  repository: '--repository',
+  repositoryId: '--repository-id',
+  repositoryOwnerId: '--repository-owner-id',
+  sourceCommit: '--source-commit',
+  bundle: '--bundle',
+  biomeId: '--biome-id',
+  runnerEnvironment: '--runner-environment',
+});
+const IMAGE_FLAG = '--image';
+
+export const THIRD_PARTY_WRITER_USAGE =
+  `${THIRD_PARTY_FLAG} <name> --repository <owner/name> --repository-id <github id> --repository-owner-id <github id> ` +
+  '--source-commit <40-hex> --bundle <oci repository>@sha256:<64-hex> --biome-id <id> ' +
+  `${IMAGE_FLAG} <image repository>@sha256:<64-hex> [${IMAGE_FLAG} ...] ${COSIGN_FLAG} <absolute cosign path> ` +
+  `[${WRITER_FLAGS.runnerEnvironment} ${RunnerEnvironment.SelfHosted} (verify the signer workflow's runs-on by hand first), default ${RunnerEnvironment.GithubHosted}] ` +
+  `[${CHANNEL_FLAG} <${Object.values(EditionChannel).join('|')}>, default ${EditionChannel.Release}]`;
+
+/** Remove every `flag value` pair named `flag` from argv; the values in order, and the argv without them. */
+function take(argv, flag) {
+  const values = [];
+  const remaining = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] !== flag) {
+      remaining.push(argv[index]);
+      continue;
+    }
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith('--')) {
+      throw new Error(`${flag} requires a value`);
+    }
+    values.push(value);
+    index += 1;
+  }
+  return { values, remaining };
+}
+
+function single(argv, flag) {
+  const { values, remaining } = take(argv, flag);
+  if (values.length > 1) {
+    throw new Error(`${flag} was given more than once`);
+  }
+  return { value: values[0], remaining };
+}
+
+function matching(flag, value, pattern, expectation) {
+  if (!pattern.test(value)) {
+    throw new Error(`${flag} must be ${expectation}; got ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+
+export const OCI_REPOSITORY_AT_DIGEST = /^[^@\s]+@sha256:[a-f0-9]{64}$/u;
+const NUMERIC_ID = /^[1-9][0-9]*$/u;
+
+function parseImage(value) {
+  matching(IMAGE_FLAG, value, OCI_REPOSITORY_AT_DIGEST, '<image repository>@sha256:<64-hex>');
+  const at = value.indexOf('@');
+  const manifestDigest = value.slice(at + 1);
+  matching(IMAGE_FLAG, manifestDigest, SHA256_DIGEST_PATTERN, 'a sha256 digest');
+  return { imageRef: value.slice(0, at), manifestDigest };
+}
+
+/**
+ * Take the third-party flags out of `argv`. `writer` is the parsed write request (or `undefined` when `--third-party`
+ * is absent, in which case any writer-only flag is refused); `cosignBinary` is `--cosign` (absolute) or `undefined`;
+ * `channel` is `--channel` parsed by `parseChannelArgs`, or `undefined` when absent (the caller applies the release default).
+ */
+export function takeThirdPartyFlags(argv) {
+  let rest = argv;
+  const name = single(rest, THIRD_PARTY_FLAG);
+  rest = name.remaining;
+  const cosign = single(rest, COSIGN_FLAG);
+  rest = cosign.remaining;
+  const channelFlag = single(rest, CHANNEL_FLAG);
+  rest = channelFlag.remaining;
+  const channel = channelFlag.value === undefined ? undefined : parseChannelArgs([CHANNEL_FLAG, channelFlag.value]).channel;
+  const taken = {};
+  for (const [key, flag] of Object.entries(WRITER_FLAGS)) {
+    const result = single(rest, flag);
+    rest = result.remaining;
+    taken[key] = result.value;
+  }
+  const images = take(rest, IMAGE_FLAG);
+  rest = images.remaining;
+  if (cosign.value !== undefined && !isAbsolute(cosign.value)) {
+    throw new Error(`${COSIGN_FLAG} must be an absolute path to the cosign binary`);
+  }
+  const writerFlagsGiven = Object.values(taken).some((value) => value !== undefined) || images.values.length > 0;
+  if (name.value === undefined) {
+    if (writerFlagsGiven) {
+      throw new Error(`the writer flags (${[...Object.values(WRITER_FLAGS), IMAGE_FLAG].join(', ')}) belong to ${THIRD_PARTY_FLAG} <name>`);
+    }
+    return { writer: undefined, cosignBinary: cosign.value, channel, remaining: rest };
+  }
+  const require = (key) => {
+    if (taken[key] === undefined) {
+      throw new Error(`${THIRD_PARTY_FLAG} requires ${WRITER_FLAGS[key]}\nusage: ${THIRD_PARTY_WRITER_USAGE}`);
+    }
+    return taken[key];
+  };
+  if (images.values.length === 0) {
+    throw new Error(`${THIRD_PARTY_FLAG} requires ${IMAGE_FLAG} at least once\nusage: ${THIRD_PARTY_WRITER_USAGE}`);
+  }
+  if (cosign.value === undefined) {
+    throw new Error(`${THIRD_PARTY_FLAG} requires ${COSIGN_FLAG}\nusage: ${THIRD_PARTY_WRITER_USAGE}`);
+  }
+  const parsedImages = images.values.map(parseImage);
+  if (new Set(parsedImages.map((image) => image.imageRef)).size !== parsedImages.length) {
+    throw new Error(`${IMAGE_FLAG} names an image repository more than once`);
+  }
+  const bundle = matching(WRITER_FLAGS.bundle, require('bundle'), OCI_REPOSITORY_AT_DIGEST, '<oci repository>@sha256:<64-hex>');
+  return {
+    writer: {
+      name: name.value,
+      repository: matching(WRITER_FLAGS.repository, require('repository'), GITHUB_REPOSITORY_PATTERN, 'owner/name'),
+      repositoryId: matching(WRITER_FLAGS.repositoryId, require('repositoryId'), NUMERIC_ID, 'a decimal GitHub repository id'),
+      repositoryOwnerId: matching(WRITER_FLAGS.repositoryOwnerId, require('repositoryOwnerId'), NUMERIC_ID, 'a decimal GitHub owner id'),
+      sourceCommit: matching(WRITER_FLAGS.sourceCommit, require('sourceCommit'), COMMIT_PATTERN, 'an exact 40-hex commit'),
+      bundleOciRef: bundle,
+      biomeId: require('biomeId'),
+      ...(taken.runnerEnvironment === undefined
+        ? {}
+        : { runnerEnvironment: parseDeclaredRunnerEnvironment(taken.runnerEnvironment, WRITER_FLAGS.runnerEnvironment) }),
+      images: parsedImages,
+    },
+    cosignBinary: cosign.value,
+    channel,
+    remaining: rest,
+  };
+}