@xemahq/xema 0.45.1 → 0.46.0

package/edition/operation-grant-admission.mjs

@@ -14,7 +14,7 @@
 export class OperationGrantAdmissionError extends Error {
   /**
    * @param {string} distributionId
-   * @param {ReadonlyArray<{code: string, biome: string, component: string, operation: string, message: string}>} refusals
+   * @param {ReadonlyArray<{code: string, operation: string, message: string}>} refusals
    */
   constructor(distributionId, refusals) {
     super(
@@ -45,9 +45,11 @@ export function ungrantedOptionalOperationLines(distributionId, ungrantedOptiona
  * {@link ungrantedOptionalOperationLines}; an ungranted optional operation never fails.
  */
 export function assertOperationGrantsAdmitted(schemas, lock, { report } = {}) {
-  const { grants, refusals, ungrantedOptional } = schemas.admitOperationGrants(lock);
-  if (refusals.length > 0) {
-    throw new OperationGrantAdmissionError(lock.distributionId, refusals);
+  const { grants, refusals, ungrantedOptional, platformServiceRefusals } = schemas.admitOperationGrants(lock);
+  // A platform service's refused requirement fails exactly like a biome component's, through the same error.
+  const allRefusals = [...refusals, ...platformServiceRefusals];
+  if (allRefusals.length > 0) {
+    throw new OperationGrantAdmissionError(lock.distributionId, allRefusals);
   }
   if (report !== undefined) {
     for (const line of ungrantedOptionalOperationLines(lock.distributionId, ungrantedOptional)) {report(line);}
@@ -86,6 +88,37 @@ export function assertOrganizationSweepsAdmitted(schemas, lock) {
   return grants;
 }
 
+/** Thrown when one or more declared exact audiences are not admitted. */
+export class ExactAudienceAdmissionError extends Error {
+  /**
+   * @param {string} distributionId
+   * @param {ReadonlyArray<{code: string, message: string}>} refusals
+   */
+  constructor(distributionId, refusals) {
+    super(
+      `distribution "${distributionId}" declares audience requirements that are not admitted:\n` +
+        refusals.map((refusal) => `[${refusal.code}] ${refusal.message}`).join('\n'),
+    );
+    this.name = 'ExactAudienceAdmissionError';
+    this.distributionId = distributionId;
+    this.refusals = refusals;
+  }
+}
+
+/**
+ * Admit every exact-audience requirement of `lock` through the kernel
+ * (`admitExactAudiences`), or throw {@link ExactAudienceAdmissionError} listing
+ * every refusal. Returns the admitted grants. The resolve and the seal call it
+ * beside {@link assertOperationGrantsAdmitted}.
+ */
+export function assertExactAudiencesAdmitted(schemas, lock) {
+  const { grants, refusals } = schemas.admitExactAudiences(lock);
+  if (refusals.length > 0) {
+    throw new ExactAudienceAdmissionError(lock.distributionId, refusals);
+  }
+  return grants;
+}
+
 /** Thrown when one or more requested installed operations are not admitted into the ceiling. */
 export class InstalledOperationCeilingAdmissionError extends Error {
   /**
@@ -147,3 +180,64 @@ export function assertStoreWorkloadCeilingAdmitted(schemas, lock) {
   }
   return ceiling;
 }
+
+/** Thrown when one or more declared organization-context relays are not admitted. */
+export class OrgContextRelayAdmissionError extends Error {
+  /**
+   * @param {string} distributionId
+   * @param {ReadonlyArray<{code: string, biome: string, component: string, message: string}>} refusals
+   */
+  constructor(distributionId, refusals) {
+    super(
+      `distribution "${distributionId}" declares organization-context relays that are not admitted:\n` +
+        refusals.map((refusal) => `[${refusal.code}] ${refusal.message}`).join('\n'),
+    );
+    this.name = 'OrgContextRelayAdmissionError';
+    this.distributionId = distributionId;
+    this.refusals = refusals;
+  }
+}
+
+/**
+ * Admit every `orgContextRelayers` entry of `lock` through the kernel
+ * (`admitOrgContextRelays`), or throw {@link OrgContextRelayAdmissionError}
+ * listing every refusal. Returns the admitted relay rows.
+ */
+export function assertOrgContextRelaysAdmitted(schemas, lock) {
+  const { relays, refusals } = schemas.admitOrgContextRelays(lock);
+  if (refusals.length > 0) {
+    throw new OrgContextRelayAdmissionError(lock.distributionId, refusals);
+  }
+  return relays;
+}
+
+/** Thrown when one or more declared event subscription clauses are not admitted. */
+export class EventSubscriptionAdmissionError extends Error {
+  /**
+   * @param {string} distributionId
+   * @param {ReadonlyArray<{code: string, biome: string, component: string, message: string}>} refusals
+   */
+  constructor(distributionId, refusals) {
+    super(
+      `distribution "${distributionId}" declares event subscriptions that are not admitted:\n` +
+        refusals.map((refusal) => `[${refusal.code}] ${refusal.message}`).join('\n'),
+    );
+    this.name = 'EventSubscriptionAdmissionError';
+    this.distributionId = distributionId;
+    this.refusals = refusals;
+  }
+}
+
+/**
+ * Admit every `eventSubscriptionRequirements` clause of `lock` through the
+ * kernel (`admitEventSubscriptions`), or throw
+ * {@link EventSubscriptionAdmissionError} listing every refusal. Returns the
+ * admission: the first-party grants and the installed ceilings.
+ */
+export function assertEventSubscriptionsAdmitted(schemas, lock) {
+  const admission = schemas.admitEventSubscriptions(lock);
+  if (admission.refusals.length > 0) {
+    throw new EventSubscriptionAdmissionError(lock.distributionId, admission.refusals);
+  }
+  return admission;
+}

package/edition/operation-requirements.mjs

@@ -6,6 +6,7 @@ import { compareStrings } from './string-order.mjs';
 const requireFromHere = createRequire(import.meta.url);
 
 let kernelPrivilegeGrammars;
+let kernelAudienceGrammars;
 
 /**
  * The kernel's ONE operation-id grammar (`OperationIdSchema`) and closed
@@ -15,16 +16,54 @@ let kernelPrivilegeGrammars;
 function loadKernelPrivilegeGrammars() {
   if (kernelPrivilegeGrammars) {return kernelPrivilegeGrammars;}
   const mod = requireFromHere(kernelDistPath('distribution', 'index.js'));
-  if (typeof mod.OperationIdSchema?.safeParse !== 'function' || typeof mod.PlatformSweepSchema?.safeParse !== 'function') {
+  if (
+    typeof mod.OperationIdSchema?.safeParse !== 'function' ||
+    typeof mod.PlatformSweepSchema?.safeParse !== 'function' ||
+    typeof mod.DeclaredEventSubscriptionClauseSchema?.safeParse !== 'function' ||
+    typeof mod.canonicalEventSubscriptionClauses !== 'function'
+  ) {
     throw new Error(
       `Built kernel distribution module at ${kernelDistPath('distribution', 'index.js')} does not export ` +
-        'OperationIdSchema and PlatformSweepSchema — the dist is stale; rebuild kernel-contracts at a commit that carries them.',
+        'OperationIdSchema, PlatformSweepSchema, DeclaredEventSubscriptionClauseSchema and canonicalEventSubscriptionClauses — the dist is stale; rebuild kernel-contracts at a commit that carries them.',
     );
   }
   kernelPrivilegeGrammars = mod;
   return mod;
 }
 
+/**
+ * The kernel's exact-audience and audience-namespace grammars, as ELEMENT schemas.
+ * The edition protocol exposes no subpath that exports the element grammars, so each is read
+ * from the one list schema the distribution subpath does export
+ * (`PlatformServiceSourceIdentitySchema.shape.requiresAudiences` / `.ownsAudienceNamespaces`):
+ * a value is graded as a one-element list, and the parsed element is returned.
+ */
+function loadKernelAudienceGrammars() {
+  if (kernelAudienceGrammars) {return kernelAudienceGrammars;}
+  const mod = requireFromHere(kernelDistPath('distribution', 'index.js'));
+  const shape = mod.PlatformServiceSourceIdentitySchema?.shape;
+  const elementSchema = (listField) => {
+    const list = shape?.[listField]?.unwrap?.();
+    if (typeof list?.safeParse !== 'function') {
+      throw new Error(
+        `Built kernel distribution module at ${kernelDistPath('distribution', 'index.js')} has no PlatformServiceSourceIdentitySchema.${listField} — ` +
+          'the dist is stale; rebuild kernel-contracts at a commit that carries the index-row audience fields.',
+      );
+    }
+    return {
+      safeParse: (value) => {
+        const parsed = list.safeParse([value]);
+        return parsed.success ? { success: true, data: parsed.data[0] } : parsed;
+      },
+    };
+  };
+  kernelAudienceGrammars = {
+    ExactAudienceSchema: elementSchema('requiresAudiences'),
+    AudienceNamespaceSchema: elementSchema('ownsAudienceNamespaces'),
+  };
+  return kernelAudienceGrammars;
+}
+
 /**
  * One component's declared privilege list, as the index carries it: sorted,
  * unique, every entry graded by the kernel schema. `null` when undeclared. An
@@ -32,7 +71,7 @@ function loadKernelPrivilegeGrammars() {
  * reads the RAW manifest, and the kernel's component schema is not applied on
  * this path.
  */
-function declaredPrivilegeList(component, where, field, schema, what) {
+export function declaredPrivilegeList(component, where, field, schema, what) {
   const declared = component[field];
   if (declared === undefined) {return null;}
   if (!Array.isArray(declared) || declared.length === 0) {
@@ -45,7 +84,7 @@ function declaredPrivilegeList(component, where, field, schema, what) {
     const parsed = schema.safeParse(value);
     if (!parsed.success) {
       throw new Error(
-        `${where} ${field}[${position}] ${JSON.stringify(value)} is not ${what === 'operation id' ? 'an' : 'a'} ${what}: ` +
+        `${where} ${field}[${position}] ${JSON.stringify(value)} is not ${/^[aeiou]/.test(what) ? 'an' : 'a'} ${what}: ` +
           parsed.error.issues.map((issue) => issue.message).join('; '),
       );
     }
@@ -104,6 +143,77 @@ export function componentOrganizationSweepRequirements(component, where) {
   return declaredPrivilegeList(component, where, 'requiresOrganizationSweeps', PlatformSweepSchema, 'platform sweep');
 }
 
+/**
+ * The exact audiences one workload component requires (`requiresAudiences`),
+ * graded by the kernel's exact-audience grammar (no wildcard, no prefix).
+ * Declared INTENT only; `admitExactAudiences` admits or refuses each.
+ */
+export function componentAudienceRequirements(component, where) {
+  const { ExactAudienceSchema } = loadKernelAudienceGrammars();
+  return declaredPrivilegeList(component, where, 'requiresAudiences', ExactAudienceSchema, 'exact audience');
+}
+
+/**
+ * The audience namespaces one workload component owns (`ownsAudienceNamespaces`),
+ * graded by the kernel's namespace grammar.
+ */
+export function componentOwnedAudienceNamespaces(component, where) {
+  const { AudienceNamespaceSchema } = loadKernelAudienceGrammars();
+  return declaredPrivilegeList(component, where, 'ownsAudienceNamespaces', AudienceNamespaceSchema, 'audience namespace');
+}
+
+/**
+ * The event subscription clauses one workload component declares
+ * (`subscribesEvents`), each graded by the kernel's clause grammar and returned
+ * in the kernel's canonical order, as the lock carries them
+ * (`eventSubscriptionRequirements`). An empty list, a repeated clause or an
+ * invalid one REFUSES naming the manifest; `null` when undeclared. Declared
+ * INTENT only; the lock admits it (`admitEventSubscriptions`).
+ */
+export function componentEventSubscriptionRequirements(component, where) {
+  const { DeclaredEventSubscriptionClauseSchema, canonicalEventSubscriptionClauses } = loadKernelPrivilegeGrammars();
+  const declared = component.subscribesEvents;
+  if (declared === undefined) {return null;}
+  if (!Array.isArray(declared) || declared.length === 0) {
+    throw new Error(
+      `${where} declares subscribesEvents that is not a non-empty array of event subscription clauses — ` +
+        'a list that names nothing states nothing, so omit the field',
+    );
+  }
+  const clauses = declared.map((value, position) => {
+    const parsed = DeclaredEventSubscriptionClauseSchema.safeParse(value);
+    if (!parsed.success) {
+      throw new Error(
+        `${where} subscribesEvents[${position}] ${JSON.stringify(value)} is not an event subscription clause: ` +
+          parsed.error.issues.map((issue) => issue.message).join('; '),
+      );
+    }
+    return parsed.data;
+  });
+  const canonical = canonicalEventSubscriptionClauses(clauses);
+  if (canonical.length !== clauses.length) {
+    throw new Error(`${where} subscribesEvents lists the same clause more than once`);
+  }
+  return canonical;
+}
+
+/**
+ * Whether one workload component declares `relaysOrgContext`: the privilege to
+ * relay an organization context its caller handed it. The only legal value is
+ * `true` (the kernel's component grammar); absent means it does not relay.
+ * Declared INTENT only; the lock admits it (`admitOrgContextRelays`).
+ */
+export function componentRelaysOrgContext(component, where) {
+  const declared = component.relaysOrgContext;
+  if (declared === undefined) {return false;}
+  if (declared !== true) {
+    throw new Error(
+      `${where} declares relaysOrgContext ${JSON.stringify(declared)} — the only legal value is true; omit the field to not relay`,
+    );
+  }
+  return true;
+}
+
 /**
  * The privilege declarations a component may carry only if it is a workload
  * principal in the lock.
@@ -112,7 +222,11 @@ export const PRINCIPAL_PRIVILEGE_FIELDS = Object.freeze([
   'requiresOperations',
   'optionalOperations',
   'requestsInstalledOperations',
+  'relaysOrgContext',
+  'subscribesEvents',
   'requiresOrganizationSweeps',
+  'requiresAudiences',
+  'ownsAudienceNamespaces',
 ]);
 
 /**

package/edition/plan-image-evidence-refresh.mjs

@@ -72,8 +72,9 @@ import { assertKernelContractAuthorityEqual } from './kernel-contract-authority.
 import { compareStrings, loadKernelDistributionSchemas } from './lib.mjs';
 import {
   createRegistryClientResolver,
+  describeInvalidReferrer,
   resolveImageSourceEvidenceReferrer,
-  writeForeignAuthorityReferrerReport,
+  writeInvalidReferrerReport,
 } from './oci-image-source-evidence.mjs';
 import {
   loadProducerKernelSchemas,
@@ -169,7 +170,10 @@ export async function planImageEvidenceRefresh({
       // planner: measured that day, ALL 68 locked coordinates were absent from
       // ghcr, and the run died on the first of them and said nothing about the
       // other 67.
-      let coordinateAbsence = null;
+      let unusableReason = null;
+      // Every referrer of this subject that is not valid evidence, as reported
+      // by the resolver. All of them invalid is a decided UNUSABLE verdict.
+      const invalidReferrers = [];
       {
         const { authority, repository } = splitImageRef(subject.imageRef);
         const client = clientFor(authority);
@@ -182,7 +186,7 @@ export async function planImageEvidenceRefresh({
           // that cannot decide must never report "nothing to do" — so it still
           // escapes and the run still exits 1.
           if (error?.status !== 404) {throw error;}
-          coordinateAbsence =
+          unusableReason =
             `the registry has no image at the locked coordinate ` +
             `${subject.imageRef}:${subject.contentHash} — nothing was ever ` +
             `published there, so no producer evidence can attest it and the ` +
@@ -195,8 +199,18 @@ export async function planImageEvidenceRefresh({
             subjectDigest: image.digest,
             schemas,
             expectedContractAuthority,
-            onForeignAuthorityReferrer: writeForeignAuthorityReferrerReport,
+            onInvalidReferrer: (skipped) => {
+              invalidReferrers.push(skipped);
+              writeInvalidReferrerReport(skipped);
+            },
           });
+          if (artifact === null && invalidReferrers.length > 0) {
+            unusableReason =
+              `every evidence referrer of ${subject.imageRef}@${image.digest} ` +
+              `(repo ${subject.repo}) is invalid under the required kernel contract ` +
+              `authority ${expectedContractAuthority.sourceCommit}: ` +
+              invalidReferrers.map(describeInvalidReferrer).join('; ');
+          }
           if (artifact !== null) {
             matches = artifact.records.filter(
               (record) =>
@@ -207,11 +221,11 @@ export async function planImageEvidenceRefresh({
         }
       }
       const verdict =
-        coordinateAbsence !== null
+        unusableReason !== null
           ? {
               status: EvidenceRefreshStatus.Unusable,
               remainingSeconds: null,
-              reason: coordinateAbsence,
+              reason: unusableReason,
             }
           : classifySubject({ matches, horizonSeconds, now });
       subjects.push({

package/edition/platform-service-class.mjs

@@ -1,4 +1,5 @@
 import { isKernelCapabilityDomain } from './kernel-capability-domain.mjs';
+import { componentAudienceRequirements, componentOperationRequirements, componentOwnedAudienceNamespaces } from './operation-requirements.mjs';
 import { compareStrings } from './string-order.mjs';
 
 /**
@@ -54,6 +55,28 @@ export function sourceOwnedCapabilityDomains(sourceManifest, where) {
   return { ownsCapabilityDomains: sorted };
 }
 
+/**
+ * What a platform service declares it requires and owns, as the index carries it, read from the
+ * same declaration as {@link sourceOwnedCapabilityDomains} (the `xema` block of its source manifest):
+ * `requiresOperations`, `requiresAudiences` and `ownsAudienceNamespaces`. Each is sorted, unique and
+ * non-empty, or no key at all. Declared INTENT: the lock admits or refuses each
+ * (`admitOperationGrants`, `admitExactAudiences`).
+ *
+ * @param {unknown} sourceManifest the parsed source manifest
+ * @param {string} where names the manifest in a refusal
+ */
+export function sourceDeclaredRequirements(sourceManifest, where) {
+  const xema = sourceManifest?.xema ?? {};
+  const requiresOperations = componentOperationRequirements(xema, where);
+  const requiresAudiences = componentAudienceRequirements(xema, where);
+  const ownsAudienceNamespaces = componentOwnedAudienceNamespaces(xema, where);
+  return {
+    ...(requiresOperations === null ? {} : { requiresOperations }),
+    ...(requiresAudiences === null ? {} : { requiresAudiences }),
+    ...(ownsAudienceNamespaces === null ? {} : { ownsAudienceNamespaces }),
+  };
+}
+
 /** The (name, tier, declared class) a declaration and an index entry must agree on. */
 export function comparablePlatformService(entry) {
   return { name: entry.name, tier: entry.tier, ...declaredInstallationClass(entry) };

package/edition/platform-service-ownership.mjs

@@ -1,6 +1,14 @@
 import { sourcePath } from './edition-workspace.mjs';
 import { readGitJsonAtCommit, serializeJson, sha256Hex } from './lib.mjs';
-import { sourceOwnedCapabilityDomains } from './platform-service-class.mjs';
+import { sourceDeclaredRequirements, sourceOwnedCapabilityDomains } from './platform-service-class.mjs';
+
+/** The index-row fields re-derived from a service's own source manifest and compared on read. */
+const DERIVED_ROW_FIELDS = Object.freeze([
+  'ownsCapabilityDomains',
+  'requiresOperations',
+  'requiresAudiences',
+  'ownsAudienceNamespaces',
+]);
 
 /** Why a platform service's capability-domain ownership was refused. */
 export const PlatformServiceOwnershipFault = Object.freeze({
@@ -8,7 +16,7 @@ export const PlatformServiceOwnershipFault = Object.freeze({
   ManifestUnavailable: 'manifest-unavailable',
   /** The manifest bytes do not hash to the index entry's `sourceManifestHash`. */
   ManifestHashMismatch: 'manifest-hash-mismatch',
-  /** The index entry's `ownsCapabilityDomains` differs from the source manifest's. */
+  /** An index entry's ownership or requirement field differs from the source manifest's. */
   OwnershipMismatch: 'ownership-mismatch',
 });
 
@@ -38,7 +46,7 @@ export function readPinnedSourceManifest(entry) {
 }
 
 /**
- * Re-derive each platform service's `ownsCapabilityDomains` from its pinned
+ * Re-derive each platform service's ownership and requirement fields (`DERIVED_ROW_FIELDS`) from its pinned
  * source manifest and refuse the index when an entry disagrees. The index is a
  * hand-editable file; the SERVICE's own manifest is the authority for which
  * service owns a domain, and so for where grants land.
@@ -61,17 +69,19 @@ export function verifiedPlatformServiceIndex(index, { names, readManifest = read
           `but the index pins sourceManifestHash ${entry.sourceManifestHash}`,
       );
     }
-    const derived = sourceOwnedCapabilityDomains(manifest, `${entry.path} at ${entry.sourceCommit}`);
-    const claimed = entry.ownsCapabilityDomains;
-    if (serializeJson(claimed ?? null) !== serializeJson(derived.ownsCapabilityDomains ?? null)) {
-      throw new PlatformServiceOwnershipError(
-        PlatformServiceOwnershipFault.OwnershipMismatch,
-        `platform service "${entry.name}": the index claims ownsCapabilityDomains ${JSON.stringify(claimed ?? [])}, ` +
-          `its source manifest declares ${JSON.stringify(derived.ownsCapabilityDomains ?? [])} ` +
-          `(sourceManifestHash ${entry.sourceManifestHash})`,
-      );
+    const where = `${entry.path} at ${entry.sourceCommit}`;
+    const derived = { ...sourceOwnedCapabilityDomains(manifest, where), ...sourceDeclaredRequirements(manifest, where) };
+    for (const field of DERIVED_ROW_FIELDS) {
+      if (serializeJson(entry[field] ?? null) !== serializeJson(derived[field] ?? null)) {
+        throw new PlatformServiceOwnershipError(
+          PlatformServiceOwnershipFault.OwnershipMismatch,
+          `platform service "${entry.name}": the index claims ${field} ${JSON.stringify(entry[field] ?? [])}, ` +
+            `its source manifest declares ${JSON.stringify(derived[field] ?? [])} ` +
+            `(sourceManifestHash ${entry.sourceManifestHash})`,
+        );
+      }
     }
-    const { ownsCapabilityDomains: _claimed, ...rest } = entry;
+    const rest = Object.fromEntries(Object.entries(entry).filter(([key]) => !DERIVED_ROW_FIELDS.includes(key)));
     return { ...rest, ...derived };
   });
   return { ...index, services };

package/edition/produce-distribution-completeness-evidence.mjs

@@ -37,6 +37,7 @@ import {
   isEntryModule,
 } from './edition-workspace.mjs';
 import { canonicalJsonBytes } from './image-evidence.mjs';
+import { oidcCertificateSignerKind } from './kernel-signer-kind.mjs';
 import { serializeJson } from './lib.mjs';
 import {
   assertGitHubProducerContext,
@@ -52,6 +53,7 @@ const COMPLETENESS_BUNDLE_PATH = 'completeness/bundle.sigstore.json';
 /** The keyless signer a GitHub workflow is: its certificate identity and issuer. */
 export function githubWorkflowSigner({ repository, ref, path }) {
   return {
+    kind: oidcCertificateSignerKind(),
     certificateIdentity: `https://github.com/${repository}/${path}@${ref}`,
     oidcIssuer: 'https://token.actions.githubusercontent.com',
     githubWorkflow: { repository, ref, path },

package/edition/produce-image-source-evidence.mjs

@@ -25,6 +25,7 @@ import {
 import { isAbsolute, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
+import { certificateConstraintArgs } from './cosign-certificate-constraints.mjs';
 import { editionWorkspaceConfig } from './edition-config.mjs';
 import {
   WorkspaceRoot,
@@ -50,6 +51,7 @@ import {
   sha256Digest,
 } from './image-evidence.mjs';
 import { assertKernelContractAuthorityEqual } from './kernel-contract-authority.mjs';
+import { oidcCertificateSignerKind } from './kernel-signer-kind.mjs';
 import { serializeJson } from './lib.mjs';
 import { assertStagedExactly, reserveSealing, sealAccepted } from './sealed-evidence-accept.mjs';
 import { BUNDLE_MEDIA_TYPE } from './sigstore-bundle-media-type.mjs';
@@ -219,7 +221,7 @@ function artifactStem(subject) {
 function assertSigner(signer) {
   exactKeys(
     signer,
-    ['certificateIdentity', 'oidcIssuer', 'githubWorkflow'],
+    ['kind', 'certificateIdentity', 'oidcIssuer', 'githubWorkflow'],
     'image-source producer signer',
   );
   exactKeys(
@@ -238,6 +240,11 @@ function assertSigner(signer) {
     throw new Error('image-source producer GitHub workflow is not canonical');
   }
   const expectedIdentity = `https://github.com/${repository}/${path}@${ref}`;
+  if (signer.kind !== oidcCertificateSignerKind()) {
+    throw new Error(
+      `image-source producer signer kind must be "${oidcCertificateSignerKind()}"`,
+    );
+  }
   if (
     signer.certificateIdentity !== expectedIdentity ||
     signer.oidcIssuer !== 'https://token.actions.githubusercontent.com'
@@ -514,16 +521,7 @@ export function cosignVerifyAttestationArgs({ bundlePath, signer, certificateWor
     '--new-bundle-format',
     '--bundle',
     bundlePath,
-    '--certificate-identity',
-    signer.certificateIdentity,
-    '--certificate-oidc-issuer',
-    signer.oidcIssuer,
-    '--certificate-github-workflow-repository',
-    signer.githubWorkflow.repository,
-    '--certificate-github-workflow-ref',
-    signer.githubWorkflow.ref,
-    '--certificate-github-workflow-sha',
-    certificateWorkflowSha,
+    ...certificateConstraintArgs(signer, certificateWorkflowSha),
     '--type',
     predicateType,
   ];

package/edition/producer-evidence-bundle.mjs

@@ -93,6 +93,17 @@ export function readRawStatementAuthorityCommits({ directory }) {
   return commits;
 }
 
+/**
+ * Evidence bytes that do not match the digests that describe them: a tampering
+ * signal. It is never an invalid-but-skippable referrer; it fails closed.
+ */
+export class EvidenceIntegrityError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'EvidenceIntegrityError';
+  }
+}
+
 /** Read and structurally validate one producer evidence directory. */
 export function readProducerEvidenceDirectory({ directory, schemas }) {
   if (!isAbsolute(directory)) {
@@ -150,7 +161,7 @@ export function readProducerEvidenceDirectory({ directory, schemas }) {
       sha256Digest(statementBytes) !== descriptor.statementDigest ||
       sha256Digest(bundleBytes) !== descriptor.bundleDigest
     ) {
-      throw new Error(`${key} artifacts do not match their descriptor`);
+      throw new EvidenceIntegrityError(`${key} artifacts do not match their descriptor`);
     }
     validateProducedBundle(statementBytes, bundleBytes);
     const statement = schemas.parseImageProducerStatement(

package/edition/record-refused.mjs

@@ -0,0 +1,11 @@
+// record-refused — the refusal class of `select-records`: the data says no (a record is missing, unsigned,
+// contradicts its tag, or its commit is not the develop line). Leaf module, so the ancestry check and the
+// selection can both subclass it. A registry, cosign or git that could not answer is a plain Error instead.
+
+export class RecordRefused extends Error {
+  constructor(repo, message) {
+    super(`select-records: ${repo}: ${message}`);
+    this.name = 'RecordRefused';
+    this.repo = repo;
+  }
+}