@xemahq/xema 0.45.0 → 0.46.0

package/edition/build-platform-service-index.mjs

@@ -14,6 +14,7 @@ import {
 import {
   comparablePlatformService,
   declaredInstallationClass,
+  sourceDeclaredRequirements,
   sourceOwnedCapabilityDomains,
 } from './platform-service-class.mjs';
 import {
@@ -144,6 +145,7 @@ function buildTrustedIndex(sourceAuthority) {
       tier: declaration.tier,
       ...declaredInstallationClass(declaration),
       ...sourceOwnedCapabilityDomains(sourceManifest, `${binding.path} at ${before}`),
+      ...sourceDeclaredRequirements(sourceManifest, `${binding.path} at ${before}`),
       repositoryUrl,
       repo: binding.repo,
       path: binding.path,

package/edition/canonical-repository-url.mjs

@@ -33,3 +33,15 @@ export function canonicalPublicHttpsRepositoryUrl(raw, context) {
   }
   return parsed.toString();
 }
+
+/**
+ * The `owner/name` of a canonical public HTTPS repository URL (`https://host/owner/name[.git]`): exactly two
+ * path segments, the optional `.git` suffix dropped. Anything else is refused, naming `context`.
+ */
+export function repositoryOwnerName(canonicalUrl, context) {
+  const segments = new URL(canonicalUrl).pathname.replace(/\.git$/, '').split('/').filter((segment) => segment.length > 0);
+  if (segments.length !== 2) {
+    throw new Error(`${context} must name exactly <owner>/<name> on its host; got ${JSON.stringify(canonicalUrl)}`);
+  }
+  return segments.join('/');
+}

package/edition/cosign-certificate-constraints.mjs

@@ -0,0 +1,40 @@
+// cosign-certificate-constraints — the certificate claims every keyless verification here pins.
+//
+// One signer shape, `{certificateIdentity, oidcIssuer, githubWorkflow: {repository, ref}}`, plus the exact
+// workflow commit the certificate must carry. Every `cosign verify*` of this CLI takes its constraints
+// from here, so no call site can leave one of the five out.
+
+const WORKFLOW_SHA = /^[0-9a-f]{40}$/;
+
+function requireText(value, what) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`certificate constraints: ${what} must be a non-empty string; got ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+
+/**
+ * @param {{ certificateIdentity: string, oidcIssuer: string, githubWorkflow: { repository: string, ref: string } }} signer
+ * @param {string} workflowSha the 40-hex commit the signing workflow ran at
+ * @returns {string[]} the cosign flags that pin identity, issuer, workflow repository, ref and sha
+ */
+export function certificateConstraintArgs(signer, workflowSha) {
+  if (signer === null || typeof signer !== 'object') {
+    throw new Error('certificate constraints: the signer must be an object');
+  }
+  if (typeof workflowSha !== 'string' || !WORKFLOW_SHA.test(workflowSha)) {
+    throw new Error(`certificate constraints: the workflow sha must be 40 lowercase hex characters; got ${JSON.stringify(workflowSha)}`);
+  }
+  return [
+    '--certificate-identity',
+    requireText(signer.certificateIdentity, 'certificateIdentity'),
+    '--certificate-oidc-issuer',
+    requireText(signer.oidcIssuer, 'oidcIssuer'),
+    '--certificate-github-workflow-repository',
+    requireText(signer.githubWorkflow?.repository, 'githubWorkflow.repository'),
+    '--certificate-github-workflow-ref',
+    requireText(signer.githubWorkflow?.ref, 'githubWorkflow.ref'),
+    '--certificate-github-workflow-sha',
+    workflowSha,
+  ];
+}

package/edition/customer-edition-verbs.mjs

@@ -213,6 +213,12 @@ const COMMANDS = Object.freeze({
     switches: ['--json'],
     required: ['--pins', '--cosign'],
   },
+  'select-records': {
+    positional: false,
+    values: ['--branch', '--registry', '--cosign', '--out', '--at', '--published-pins'],
+    switches: [],
+    required: ['--branch', '--registry', '--cosign', '--out'],
+  },
   'check-overrides': { positional: false, values: ['--overrides'], switches: [], required: ['--overrides'] },
   'choose-kernel': { positional: false, values: ['--kernel-pin', '--out'], switches: [], required: ['--out'] },
   'check-existing': {

package/edition/develop-coverage-readers.mjs

@@ -12,7 +12,7 @@ import { promisify } from 'node:util';
 
 import { AttestationStatus, DEVELOP_EVIDENCE_CHANNEL } from './develop-coverage-verdict.mjs';
 import { COSIGN_ENV, policyCandidates, sha256Digest, validatePinnedTrustedRoot, verifySigstoreEvidenceDescriptor } from './image-evidence.mjs';
-import { resolveImageSourceEvidenceReferrer } from './oci-image-source-evidence.mjs';
+import { resolveImageSourceEvidenceReferrer, writeInvalidReferrerReport } from './oci-image-source-evidence.mjs';
 import { BUNDLE_MEDIA_TYPE } from './produce-image-source-evidence.mjs';
 import { loadRegistryCredentialDeclarations, resolveRegistryCredential, splitImageRef } from './registry-credentials.mjs';
 import { isNotPublishedYet } from './seal-image-digests.mjs';
@@ -59,7 +59,8 @@ export function parseCosignVerifyOutput(stdout, digest) {
   });
 }
 
-function defaultRunCosign(cosignPath, args, env) {
+/** Run cosign once; resolves `{code, stdout, stderr}` for a cosign exit, throws when cosign could not run at all. */
+export function defaultRunCosign(cosignPath, args, env) {
   return execFileAsync(cosignPath, args, { env, timeout: COSIGN_CALL_TIMEOUT_MS, maxBuffer: COSIGN_MAX_OUTPUT_BYTES }).then(
     ({ stdout }) => ({ code: 0, stdout, stderr: '' }),
     (error) => {
@@ -69,7 +70,8 @@ function defaultRunCosign(cosignPath, args, env) {
   );
 }
 
-function basicAuthParts(credential) {
+/** The username and password of a resolved basic-auth registry credential. */
+export function basicAuthParts(credential) {
   const decoded = Buffer.from(credential.basicAuth, 'base64').toString('utf8');
   const colon = decoded.indexOf(':');
   return { username: decoded.slice(0, colon), password: decoded.slice(colon + 1) };
@@ -81,13 +83,14 @@ function basicAuthParts(credential) {
  * @param {string} request.policyRoot the directory the policy's trusted root is read from (the data root)
  * @param {object} request.trustedCosign the digest-pinned cosign handle (prepareTrustedCosignBinary)
  * @param {object} request.schemas kernel distribution schemas
+ * @param {object} request.expectedContractAuthority the kernel contract authority the data root pins
  * @param {string} request.dataRoot declares how each registry is read
  * @param {object} request.env environment the registry credentials are named in
  * @param {Function} [request.runCosign] (path, args, env) => { code, stdout, stderr }; replaced by tests
  * @param {Function} [request.fetchImpl] @param {Function} [request.run] oras runner, replaced by tests
  * @param {Function} [request.clientFor] (authority) => registry client, replaced by tests
  */
-export function createCoverageReaders({ policy, policyRoot, trustedCosign, schemas, dataRoot, env, runCosign = defaultRunCosign, fetchImpl, run, clientFor: injectedClientFor }) {
+export function createCoverageReaders({ policy, policyRoot, trustedCosign, schemas, expectedContractAuthority, dataRoot, env, runCosign = defaultRunCosign, fetchImpl, run, clientFor: injectedClientFor }) {
   const cosignPath = assertPreparedExecutable(trustedCosign, 'cosign');
   const declarations = injectedClientFor === undefined ? loadRegistryCredentialDeclarations(dataRoot) : null;
   const scratch = mkdtempSync(join(tmpdir(), 'xema-coverage-'));
@@ -141,6 +144,8 @@ export function createCoverageReaders({ policy, policyRoot, trustedCosign, schem
       imageRepository: subject.imageRef,
       subjectDigest: digest,
       schemas,
+      expectedContractAuthority,
+      onInvalidReferrer: writeInvalidReferrerReport,
     });
     if (evidence === null) {return { status: AttestationStatus.None };}
     if (rows.length === 0) {return { status: AttestationStatus.NoRow };}

package/edition/develop-coverage-run.mjs

@@ -8,6 +8,7 @@ import { collectCoverage, coverageExitCode, renderCoverageTable } from './develo
 import { DEVELOP_EDITION_STEPS, resolveDevelopSnapshot } from './develop-edition-resolve.mjs';
 import { loadDeclaredPinnedPolicy } from './evidence-trust-policy.mjs';
 import { prepareTrustedCosignBinary } from './image-evidence.mjs';
+import { readPinnedContractAuthority } from './produce-image-source-evidence.mjs';
 
 const stderrProgress = (line) => process.stderr.write(`${line}\n`);
 
@@ -34,7 +35,7 @@ export async function runDevelopCoverage({
     const { schemas, inputs, lock } = await resolveDevelopSnapshot({ id, pins, steps, phase: (name) => progress(`[coverage] ${name}`) });
     const { imageLock } = await steps.resolveImages(id, { inputs, lock });
     progress(`[coverage] image content hashes computed (${imageLock.subjects.length} subjects)`);
-    const readers = createCoverageReaders({ policy, policyRoot: dataRoot, trustedCosign, schemas, dataRoot, env, ...readerOptions });
+    const readers = createCoverageReaders({ policy, policyRoot: dataRoot, trustedCosign, schemas, expectedContractAuthority: readPinnedContractAuthority({ dataRoot, schemas }), dataRoot, env, ...readerOptions });
     try {
       const report = await collectCoverage({ distributionId: id, subjects: imageLock.subjects, policy, readers, progress });
       write(json ? `${JSON.stringify(report, null, 2)}\n` : renderCoverageTable(report));

package/edition/develop-edition.mjs

@@ -45,6 +45,22 @@
 //       annotations-missing | annotation-mismatch | not-built). Prints a table grouped by producer repo
 //       and `covered N/M` (--json: the same as data). Exit 0 only when every subject is covered, 1 when
 //       not, 2 on an operational error. Takes the roots `resolve` takes; writes nothing.
+//   select-records --branch develop --registry <root> --cosign <absolute-path> --out <file> [--at <ISO-8601 UTC>] [--published-pins <file>]
+//       for every develop-graph member, take the newest build record the data root's record workflow signed for
+//       the branch (<root>/build-records/<name>, verified offline by digest against the pinned trusted root, as
+//       signed by <data root>/.github/workflows/record-build.yaml at refs/heads/<branch>, called by the member at the
+//       record's own commit) and write { pins, snapshot, images }, once (wx). Any missing, unsigned, mismatched or
+//       unreadable record refuses the whole run and writes nothing: a newer bad record is never skipped for an older
+//       one. --at takes the newest record completed at or before that time. Only `develop` has a declared signer; the
+//       data root must declare dataRootRepositoryUrl. Takes the roots `resolve` takes (no registry root is implied).
+//       "Newest" is the newest COMMIT on develop, not the highest run: EVERY record of the branch is read and cosign-verified,
+//       the selected commit must equal or descend from every other record's commit (git merge-base on develop fetched
+//       from the member), and among that commit's records the highest run and attempt wins. --published-pins takes a file
+//       this verb wrote (only .pins is read): a member's published commit is kept when the records are not ahead of it
+//       (its own record must exist), a diverged one is refused. Without the flag the rule applies among the records only;
+//       part 07 passes the flag.
+//       Residual: anyone who can delete registry tags can remove newer records, and this then pins the newest remaining
+//       valid one; the guard is part 07's, deploy-latest's owner refuses a snapshot that goes backwards.
 //   choose-kernel [--kernel-pin <40-hex>] --out <file>
 //       choose the develop kernel commit in the --kernel checkout (full history; its refs/remotes/origin/develop is the develop head):
 //       the newest first-parent commit whose declared edition protocol this CLI supports
@@ -74,6 +90,7 @@ import { runDevelopCoverage } from './develop-coverage-run.mjs';
 import { CoverageExit } from './develop-coverage.mjs';
 import { resolveDevelopEdition } from './develop-edition-resolve.mjs';
 import { assertNoToolingOverride, freezeGraph, freezeSources } from './develop-freeze.mjs';
+import { runSelectRecords } from './develop-select-records.mjs';
 import { LOCAL_WORKFLOW, assertExistingArtifactMatches, developEditionTarget, workflowFromEnv, writeEditionArtifact } from './edition-artifact.mjs';
 import { EditionChannel } from './edition-constants.mjs';
 import { WorkspaceRoot, configureEditionWorkspaceFromProcess, isEntryModule, kernelRepoDir } from './edition-workspace.mjs';
@@ -162,6 +179,9 @@ async function run(argv, env) {
         json: options['--json'] === true,
         env,
       });
+    case 'select-records':
+      await runSelectRecords({ options, env });
+      return;
     case 'check-existing': {
       if (customer) {return runCustomerVerb({ channel: EditionChannel.Develop, command, options, env });}
       assertExistingArtifactMatches({

package/edition/develop-record-ancestry.mjs

@@ -0,0 +1,121 @@
+// develop-record-ancestry — which verified record commit is the newest COMMIT on develop.
+//
+// "Newest" is the commit that equals or descends from every other candidate's commit, never the highest run:
+// a re-run of an old commit carries a higher run number and must lose. History comes from git alone: one bare
+// scratch repository per member, fetched blobless from the member's own URL through the same hold and credential
+// environment freeze uses (`withSourceGitEnv`; no token on argv, none beyond the workspace's). Candidates are
+// compared with each other only, never with a published pin.
+//
+// With a published commit for the member, the records may not take it backwards: behind or equal keeps the published
+// commit (its own record must then exist), ahead selects the records' commit, otherwise the run is refused.
+//
+// Refusals (`RecordRefused`): a commit absent from the fetched develop history, two commits that are not
+// ancestor-related. Operational (plain Error): git cannot be spawned, a fetch fails, or merge-base answers
+// anything but 0 (ancestor) or 1 (not an ancestor).
+
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { withSourceGitEnv } from './git-source-auth.mjs';
+import { RecordRefused } from './record-refused.mjs';
+
+const DEVELOP_REF = 'refs/heads/develop';
+// One external call to a git remote; a fetch that exceeds it fails naming the member, never a verdict.
+const GIT_CALL_TIMEOUT_MS = 300_000;
+const GIT_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
+
+export class IncomparableRecordCommitsError extends RecordRefused {
+  constructor(repo, first, second) {
+    super(repo, `record commits ${first.commit} (${first.tags.join(', ')}) and ${second.commit} (${second.tags.join(', ')}) are not ancestor-related on develop`);
+    this.name = 'IncomparableRecordCommitsError';
+  }
+}
+
+export class RecordCommitNotOnDevelopError extends RecordRefused {
+  constructor(repo, commit, tags) {
+    super(repo, `record commit ${commit} (${tags.join(', ')}) is not in the fetched develop history`);
+    this.name = 'RecordCommitNotOnDevelopError';
+  }
+}
+
+export class DivergedFromPublishedError extends RecordRefused {
+  constructor(repo, selected, published) {
+    super(repo, `the newest record commit ${selected} and the published commit ${published} are not ancestor-related on develop`);
+    this.name = 'DivergedFromPublishedError';
+  }
+}
+
+/** The published commit is newer than every record, and none of its own survives among the candidates. */
+export class PublishedRecordMissingError extends RecordRefused {
+  constructor(repo, published) {
+    super(repo, `no verified build record exists for the published commit ${published}; it is newer than every candidate record`);
+    this.name = 'PublishedRecordMissingError';
+  }
+}
+
+/** `{ status, stdout, stderr }` of one git run; a git that could not be spawned or timed out throws. */
+export function defaultRunGit(args, { cwd, env }) {
+  const result = spawnSync('git', args, { cwd, env, encoding: 'utf8', timeout: GIT_CALL_TIMEOUT_MS, maxBuffer: GIT_MAX_OUTPUT_BYTES });
+  if (result.error !== undefined || result.status === null) {
+    throw new Error(`git ${args[0]} could not run: ${result.error?.message ?? `killed by ${result.signal}`}`);
+  }
+  return { status: result.status, stdout: result.stdout, stderr: result.stderr };
+}
+
+/**
+ * @param {object} request
+ * @param {{repo: string, repositoryUrl: string}} request.member
+ * @param {{commit: string, tag: string}[]} request.candidates verified records' commits with their tags
+ * @param {string} [request.published] the commit already published for this member: kept when the records are not ahead of it
+ * @param {object} request.workspace the workspace config the source hold reads
+ * @param {object} request.env
+ * @param {Function} [request.runGit] (args, {cwd, env}) => {status, stdout, stderr}; replaced by tests
+ * @returns {string} the selected commit
+ */
+export function newestCommitOnDevelop({ member, candidates, published, workspace, env, runGit = defaultRunGit }) {
+  const byCommit = new Map();
+  for (const { commit, tag } of candidates) {
+    byCommit.set(commit, [...(byCommit.get(commit) ?? []), tag]);
+  }
+  const commits = [...byCommit].map(([commit, tags]) => ({ commit, tags }));
+  const scratch = mkdtempSync(join(tmpdir(), 'xema-select-history-'));
+  try {
+    return withSourceGitEnv({ name: member.repo, url: member.repositoryUrl }, { workspace, env }, (gitEnv) => {
+      const git = (args, extraEnv = {}) => runGit(args, { cwd: scratch, env: { ...gitEnv, ...extraEnv } });
+      const init = git(['init', '--bare', '--quiet']);
+      if (init.status !== 0) {throw new Error(`select-records: ${member.repo}: git init failed: ${init.stderr.trim()}`);}
+      const fetched = git(['fetch', '--quiet', '--filter=blob:none', '--no-tags', member.repositoryUrl, `+${DEVELOP_REF}:${DEVELOP_REF}`]);
+      if (fetched.status !== 0) {
+        throw new Error(`select-records: ${member.repo}: git fetch of develop from ${member.repositoryUrl} failed (exit ${fetched.status}): ${fetched.stderr.trim()}`);
+      }
+      // 0 = ancestor (or equal), 1 = not; anything else is git failing, never a verdict
+      const isAncestor = (older, newer) => {
+        const result = git(['merge-base', '--is-ancestor', older, newer]);
+        if (result.status === 0) {return true;}
+        if (result.status === 1) {return false;}
+        throw new Error(`select-records: ${member.repo}: git merge-base ${older} ${newer} failed (exit ${result.status}): ${result.stderr.trim()}`);
+      };
+      const assertOnDevelop = (commit, tags) => {
+        // no lazy fetch: a commit the develop fetch did not bring is not on develop
+        const known = git(['cat-file', '-e', `${commit}^{commit}`], { GIT_NO_LAZY_FETCH: '1' });
+        if (known.status !== 0 || !isAncestor(commit, DEVELOP_REF)) {throw new RecordCommitNotOnDevelopError(member.repo, commit, tags);}
+      };
+      for (const { commit, tags } of commits) {assertOnDevelop(commit, tags);}
+      let selected = commits[0];
+      for (const other of commits.slice(1)) {
+        if (isAncestor(other.commit, selected.commit)) {continue;}
+        if (!isAncestor(selected.commit, other.commit)) {throw new IncomparableRecordCommitsError(member.repo, selected, other);}
+        selected = other;
+      }
+      if (published === undefined) {return selected.commit;}
+      assertOnDevelop(published, ['published pin']);
+      if (isAncestor(selected.commit, published)) {return published;} // equal, or the records are behind it
+      if (isAncestor(published, selected.commit)) {return selected.commit;}
+      throw new DivergedFromPublishedError(member.repo, selected.commit, published);
+    });
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}