@xemahq/xema 0.40.3 → 0.41.0

package/edition/{develop-seal.mjs → edition-image-seal.mjs}

@@ -1,10 +1,13 @@
-// develop-seal — seal a snapshot's images lock against the DEVELOP repositories.
+// edition-image-seal — seal image subjects against the repositories of one channel.
 //
-// The release sealer verifies `<imageRef>:<contentHash>` and writes the digest
-// the registry served. This does the same for a develop edition, with the
+// The vendor release sealer verifies `<imageRef>:<contentHash>` and writes the digest
+// the registry served. This does the same for an edition of either channel, with the
 // SAME verifier (`verifyDistributionPlatforms`, required platforms enforced)
-// and the SAME digest decision (`planDigestSeal`), against the repository the
-// producer's develop lane pushes to (`developImageRef`, contract C1).
+// and the SAME digest decision (`planDigestSeal`). Only the repository differs:
+//   develop  the repository the producer's develop lane pushes to (`developImageRef`, contract C1)
+//   release  the subject's own imageRef (the identity)
+// It never builds or rebuilds an image: a coordinate that is not there is refused, and the digest
+// 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;
@@ -13,23 +16,39 @@
 
 import { developImageRef } from './develop-image-coordinate.mjs';
 import { notBuiltYetError } from './develop-image-probe.mjs';
+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 { 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. */
+const CHANNEL_IMAGE_REF = Object.freeze({
+  [EditionChannel.Develop]: developImageRef,
+  [EditionChannel.Release]: (releaseImageRef) => releaseImageRef,
+});
+
+/** The repository `channel` seals a subject whose release imageRef is `releaseImageRef` in. */
+export function channelImageRef(channel, releaseImageRef) {
+  const toChannelRef = CHANNEL_IMAGE_REF[channel];
+  if (toChannelRef === undefined) {throw new Error(`cannot seal image subjects for channel ${JSON.stringify(channel)}`);}
+  return toChannelRef(releaseImageRef);
+}
+
 /**
- * The row-level seal: every subject re-homed to its develop repository, verified
+ * The row-level seal: every subject re-homed to its channel's repository, verified
  * there for its required platforms, and given the digest the registry served.
  * It takes SUBJECTS, not a lock, so a caller that owns only some rows of a lock
  * (a customer's own image rows) seals exactly those.
  *
  * @param {object} request
+ * @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)
- * @returns the subjects with develop refs and verified digests
+ * @returns the subjects with the channel's refs and verified digests
  */
-export async function sealDevelopImageSubjects({
+export async function sealImageSubjects({
+  channel,
   distributionId,
   subjects,
   distributionsRoot = editionsRoot(),
@@ -38,12 +57,12 @@ export async function sealDevelopImageSubjects({
   run = null,
   progress = null,
 }) {
-  const developSubjects = subjects.map((subject) => ({
+  const channelSubjects = subjects.map((subject) => ({
     ...subject,
-    imageRef: developImageRef(subject.imageRef),
+    imageRef: channelImageRef(channel, subject.imageRef),
   }));
   const report = await verifyDistributionPlatforms({
-    imageLock: { distributionId, subjects: developSubjects },
+    imageLock: { distributionId, subjects: channelSubjects },
     distributionsRoot,
     env,
     fetchImpl,
@@ -54,11 +73,11 @@ export async function sealDevelopImageSubjects({
   const aborting = report.failures.find(({ error }) => !isNotPublishedYet(error));
   if (aborting) {throw aborting.error;}
   if (report.failures.length > 0) {
-    throw notBuiltYetError(distributionId, report.failures.map(({ subject }) => subject));
+    throw notBuiltYetError(distributionId, report.failures.map(({ subject }) => subject), channel);
   }
-  const { writes, unchanged } = planDigestSeal({ subjects: developSubjects, verified: report.subjects });
+  const { writes, unchanged } = planDigestSeal({ subjects: channelSubjects, verified: report.subjects });
   const digests = new Map([...writes, ...unchanged].map(({ key, digest }) => [key, digest]));
-  return developSubjects.map((subject) => ({
+  return channelSubjects.map((subject) => ({
     ...subject,
     imageDigest: digests.get(`${subject.kind}:${subject.id}`),
   }));
@@ -70,10 +89,10 @@ export async function sealDevelopImageSubjects({
  *
  * @param {object} request
  * @param {object} request.imageLock the snapshot images lock (release refs, unsealed)
- * @returns the images lock with develop refs and verified digests, kernel-validated
+ * @returns the images lock with the channel's refs and verified digests, kernel-validated
  */
-export async function sealDevelopImages({ imageLock, ...sealOptions }) {
-  const subjects = await sealDevelopImageSubjects({
+export async function sealImages({ imageLock, ...sealOptions }) {
+  const subjects = await sealImageSubjects({
     distributionId: imageLock.distributionId,
     subjects: imageLock.subjects,
     ...sealOptions,

package/edition/edition-workspace.mjs

@@ -182,9 +182,10 @@ export function isEntryModule(moduleUrl) {
 /**
  * The entry's one call: configure the roots from `process.argv` and remove the
  * root flags from it, so the entry's own parser sees only its own arguments.
- * `options` are those of `configureEditionWorkspaceFromArgv`.
+ * `options` are those of `configureEditionWorkspaceFromArgv`, plus `failureExitCode` (default 1): the exit code of
+ * a refused root, for a verb whose exit 1 already means something else.
  */
-export function configureEditionWorkspaceFromProcess(needs, options) {
+export function configureEditionWorkspaceFromProcess(needs, { failureExitCode = 1, ...options } = {}) {
   let rest;
   try {
     rest = configureEditionWorkspaceFromArgv(process.argv.slice(2), needs, options);
@@ -195,7 +196,7 @@ export function configureEditionWorkspaceFromProcess(needs, options) {
     process.stderr.write(
       `${error.message}\nusage: this command takes ${needs.map((name) => `${WORKSPACE_FLAGS[name]} <dir>`).join(' ')}\n`,
     );
-    process.exit(1);
+    process.exit(failureExitCode);
   }
   process.argv.splice(2, process.argv.length - 2, ...rest);
 }

package/edition/evidence-trust-pin.mjs

@@ -10,13 +10,15 @@
 // change and the registry reader cannot change without a reviewed data-root
 // commit.
 //
+// A customer data root has no such index; its pin records `kernelContractAuthority: null` and pins only what exists.
+//
 // The kernel contract authority is pinned HERE because nothing else can hold
 // it: `runtime-image-source-index.json` states the authority, and the image
 // locks and statements are compared with what that file states. Comparing the
 // file with itself decides nothing, so its authority is first held to this
 // pin, and only the pinned authority is what evidence is compared with.
 
-import { closeSync, constants as fsConstants, openSync, writeFileSync } from 'node:fs';
+import { closeSync, constants as fsConstants, existsSync, openSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 import { COMMIT_PATTERN } from './evidence-grammars.mjs';
@@ -61,7 +63,7 @@ const VERIFIER_KEYS = Object.freeze(['bundleDigest', 'provenanceDigest']);
 const AUTHORITY_PIN_KEYS = Object.freeze(['digest', 'sourceCommit']);
 const PIN_SHAPE =
   '{schemaVersion, policyDigest, verifier: {bundleDigest, provenanceDigest}, ' +
-  'kernelContractAuthority: {sourceCommit, digest}, trustedOrasBinaryDigests: [sha256:…, …]}';
+  'kernelContractAuthority: {sourceCommit, digest} | null, trustedOrasBinaryDigests: [sha256:…, …]}';
 
 const exactKeys = (value, keys) =>
   value !== null &&
@@ -117,7 +119,7 @@ export function readEvidenceTrustPin({ dataRoot, declaration }) {
   if (
     !exactKeys(pin, PIN_KEYS) ||
     !exactKeys(pin.verifier, VERIFIER_KEYS) ||
-    !exactKeys(pin.kernelContractAuthority, AUTHORITY_PIN_KEYS) ||
+    !(pin.kernelContractAuthority === null || exactKeys(pin.kernelContractAuthority, AUTHORITY_PIN_KEYS)) ||
     !Array.isArray(pin.trustedOrasBinaryDigests)
   ) {
     throw new Error(`${declaration.pin}: the pin is exactly ${PIN_SHAPE}`);
@@ -137,10 +139,13 @@ export function readEvidenceTrustPin({ dataRoot, declaration }) {
         'verifier.provenanceDigest',
       ),
     }),
-    kernelContractAuthority: Object.freeze({
-      sourceCommit: requireCommit(pin.kernelContractAuthority.sourceCommit),
-      digest: requireDigest(pin.kernelContractAuthority.digest, 'kernelContractAuthority.digest'),
-    }),
+    kernelContractAuthority:
+      pin.kernelContractAuthority === null
+        ? null
+        : Object.freeze({
+            sourceCommit: requireCommit(pin.kernelContractAuthority.sourceCommit),
+            digest: requireDigest(pin.kernelContractAuthority.digest, 'kernelContractAuthority.digest'),
+          }),
     trustedOrasBinaryDigests: requireOrasDigests(pin.trustedOrasBinaryDigests),
   });
 }
@@ -175,6 +180,14 @@ export function kernelContractAuthorityPin(authority) {
   });
 }
 
+/**
+ * Whether the data root holds a runtime image source index. A vendor data root does; a customer data root has none
+ * (it consumes a catalogue and states no kernel contract authority of its own), and its pin records `null`.
+ */
+export function hasRuntimeImageSourceIndex(dataRoot) {
+  return existsSync(join(dataRoot, RUNTIME_IMAGE_SOURCE_INDEX_FILE));
+}
+
 /** The kernel contract authority the data root's runtime image source index STATES; nothing is trusted yet. */
 export function readStatedKernelContractAuthority({ dataRoot, schemas }) {
   if (!schemas?.parseRuntimeImageSourceIndex) {
@@ -192,6 +205,13 @@ export function readStatedKernelContractAuthority({ dataRoot, schemas }) {
 /** Refuse an authority that is not the one the pin records. */
 export function assertPinnedKernelContractAuthority({ pin, authority, label }) {
   const actual = kernelContractAuthorityPin(authority);
+  if (pin.kernelContractAuthority === null) {
+    throw new KernelContractAuthorityPinError(
+      KERNEL_CONTRACT_AUTHORITY_NOT_PINNED_ONE,
+      `${label} states kernel contract authority ${actual.sourceCommit} (${actual.digest}) but the pin records none ` +
+        `(it was written for a data root without a runtime image source index); review the index, then re-pin with \`${REPIN_COMMAND}\``,
+    );
+  }
   if (
     actual.sourceCommit !== pin.kernelContractAuthority.sourceCommit ||
     actual.digest !== pin.kernelContractAuthority.digest
@@ -283,7 +303,7 @@ export function writeEvidenceTrustPin({
       bundleDigest: verifier.bundleDigest,
       provenanceDigest: verifier.provenanceDigest,
     },
-    kernelContractAuthority: { ...kernelContractAuthorityPin(kernelContractAuthority) },
+    kernelContractAuthority: kernelContractAuthority === null ? null : { ...kernelContractAuthorityPin(kernelContractAuthority) },
     trustedOrasBinaryDigests: [...requireOrasDigests(trustedOrasBinaryDigests)].sort(),
   };
   const text = `${JSON.stringify(pin, null, 2)}\n`;

package/edition/evidence-trust-policy.mjs

@@ -133,6 +133,28 @@ function loadPinnedPolicy({ dataRoot, declaration, schemas, locateVerifier }) {
   return { policy, policyDigest };
 }
 
+/**
+ * The data root's declared policy, loaded and held to its pin exactly as the
+ * arming checks load it, for a READ-ONLY consumer (the develop coverage verb).
+ * A data root that declares no policy has nothing to report coverage against
+ * and is refused, naming the declaration it lacks. The POLICY is held to its pin; this CLI's built verifier
+ * is not. Coverage therefore runs this CLI's own, unpinned verifier code (case A), so a green coverage is a
+ * forecast of what resolve accepts, not a guarantee: resolve can still refuse under the pinned verifier.
+ *
+ * @returns {{ policy: object, dataRoot: string }}
+ */
+export async function loadDeclaredPinnedPolicy() {
+  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
+  const root = configuredDataRoot();
+  if (declaration.policy === null) {
+    throw new Error(`${join(root, EDITION_WORKSPACE_CONFIG_FILE)} declares no evidenceTrustPolicy; there is no pinned policy to report coverage against`);
+  }
+  const schemas = await loadKernelDistributionSchemas();
+  const { policy, policyDigest } = loadDeclaredTrustPolicy({ dataRoot: root, declaration, schemas });
+  assertPinnedPolicy({ pin: readEvidenceTrustPin({ dataRoot: root, declaration }), policyDigest });
+  return { policy, dataRoot: root };
+}
+
 /**
  * The arming of the data root's declared policy on `channel`, loaded and pinned
  * exactly as `descriptorEvidenceTrust` and the check load it: `{ declared, state,
@@ -140,9 +162,9 @@ function loadPinnedPolicy({ dataRoot, declaration, schemas, locateVerifier }) {
  * false` and one unmet entry; a declared policy that does not hold to its pin
  * (digest, verifier) throws. Nothing is written.
  *
- * @param {{ channel: string, locateVerifier?: () => {bundlePath: string, provenancePath: string} }} options
+ * @param {{ channel: string, locateVerifier?: () => {bundlePath: string, provenancePath: string}, consumesCatalogue?: boolean }} options
  */
-export async function assessDeclaredTrustPolicyArming({ channel, locateVerifier = locateBuiltVerifier }) {
+export async function assessDeclaredTrustPolicyArming({ channel, locateVerifier = locateBuiltVerifier, consumesCatalogue = false }) {
   const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
   const root = configuredDataRoot();
   const schemas = await loadKernelDistributionSchemas();
@@ -155,13 +177,26 @@ export async function assessDeclaredTrustPolicyArming({ channel, locateVerifier
     };
   }
   const { policy } = loadPinnedPolicy({ dataRoot: root, declaration, schemas, locateVerifier });
-  const { state, unmet } = assessTrustPolicyArming(policy, schemas, channel);
+  const { state, unmet } = assessTrustPolicyArming(policy, schemas, channel, { consumesCatalogue });
   return { declared: true, state, unmet };
 }
 
 /** What a develop edition says, once, when it is written or checked without an armed develop channel. */
 export const DEVELOP_NOT_ARMED_NOTICE = 'develop channel: trust policy not armed, evidence is not signature-verified';
 
+/** A customer develop edition under a policy ARMED on develop: its catalogue carries no E4 evidence to verify. */
+export class CatalogueEvidenceUnverifiableError extends Error {
+  constructor(root) {
+    super(
+      `the data root ${root} declares an evidence trust policy ARMED on the develop channel, but a develop catalogue carries no ` +
+        'signed edition-catalogue (E4) evidence, so the catalogue this customer develop edition consumes cannot be verified and ' +
+        'the edition is never recorded as armed. Resolve it under a policy that is not armed on develop (no develop signer rows), ' +
+        'or resolve a release edition, whose catalogue evidence is verified.',
+    );
+    this.name = 'CatalogueEvidenceUnverifiableError';
+  }
+}
+
 /**
  * The evidence state an edition of `channel` records in its descriptor. Arming
  * is judged for that ONE channel (`assessTrustPolicyArming`): the signers of
@@ -179,9 +214,15 @@ export const DEVELOP_NOT_ARMED_NOTICE = 'develop channel: trust policy not armed
  * A policy edited after pinning, a drifted verifier, and a policy PARTIALLY
  * ARMED on `channel` are refused on either channel.
  *
- * @param {{ channel: string, locateVerifier?: () => {bundlePath: string, provenancePath: string} }} options
+ * `consumesCatalogue` (a customer edition consumes a catalogue): on RELEASE it adds the edition-catalogue (E4) row to the
+ * required ones, and the catalogue's E4 evidence is verified before it is parsed. A DEVELOP catalogue carries no E4
+ * evidence (the vendor's develop-edition workflow signs the artifact but attaches no E4 statement), so on develop no E4
+ * row is required and nothing can verify the catalogue: a customer develop edition is never written `armed`. A policy
+ * ARMED on develop throws CatalogueEvidenceUnverifiableError instead of recording a claim nothing checked.
+ *
+ * @param {{ channel: string, locateVerifier?: () => {bundlePath: string, provenancePath: string}, consumesCatalogue?: boolean }} options
  */
-export async function descriptorEvidenceTrust({ channel, locateVerifier = locateBuiltVerifier }) {
+export async function descriptorEvidenceTrust({ channel, locateVerifier = locateBuiltVerifier, consumesCatalogue = false }) {
   const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
   const root = configuredDataRoot();
   const schemas = await loadKernelDistributionSchemas();
@@ -196,8 +237,11 @@ export async function descriptorEvidenceTrust({ channel, locateVerifier = locate
     return developNotArmed();
   }
   const { policy } = loadPinnedPolicy({ dataRoot: root, declaration, schemas, locateVerifier });
-  const { state, unmet } = assessTrustPolicyArming(policy, schemas, channel);
-  if (state === TrustPolicyArmingState.ARMED) {return EvidenceTrustState.Armed;}
+  const { state, unmet } = assessTrustPolicyArming(policy, schemas, channel, { consumesCatalogue: consumesCatalogue && release });
+  if (state === TrustPolicyArmingState.ARMED) {
+    if (consumesCatalogue && !release) {throw new CatalogueEvidenceUnverifiableError(root);}
+    return EvidenceTrustState.Armed;
+  }
   if (state === TrustPolicyArmingState.PARTIAL) {
     if (release) {throw new EvidenceTrustRequiredError(root, `declares a policy that is PARTIALLY ARMED on the ${channel} channel (${unmet.join('; ')})`);}
     throw new Error(`the declared evidence trust policy is PARTIALLY ARMED on the ${channel} channel (${unmet.join('; ')}); an edition cannot be written against it`);

package/edition/image-evidence.mjs

@@ -42,7 +42,7 @@ const MAX_SIGSTORE_BUNDLE_BYTES = 16 * 1024 * 1024;
 const MAX_TRUSTED_ROOT_BYTES = 8 * 1024 * 1024;
 /** The kernel's `SignerKind.OidcCertificate`: the one signer kind this verifier runs (cosign keyless). */
 const OIDC_CERTIFICATE_SIGNER = 'oidc-certificate';
-const COSIGN_ENV = Object.freeze({
+export const COSIGN_ENV = Object.freeze({
   LANG: 'C',
   LC_ALL: 'C',
   PATH: '/usr/bin:/bin',
@@ -632,7 +632,7 @@ function assertEvidenceChannel(channel) {
  * selects which policy rows are tried; what authenticates a channel is the
  * certificate matching a row of that channel.
  */
-function policyCandidates(policy, predicateType, channel, imageRepository) {
+export function policyCandidates(policy, predicateType, channel, imageRepository) {
   const candidates = policy.policies.filter(
     (candidate) =>
       candidate.channel === channel &&

package/edition/lib.mjs

@@ -734,6 +734,8 @@ export async function loadKernelDistributionSchemas() {
     parseImageProducerStatement,
     parseDistributionImagesStatement,
     parseImageDeliveryEntitlementStatement,
+    parseEditionCatalogueStatement,
+    editionCatalogueRefusal,
     parseDistributionImageEvidenceSet,
     parseDistributionImageReplayState,
     parseSigstoreOfflineTrustPolicy,
@@ -751,6 +753,7 @@ export async function loadKernelDistributionSchemas() {
     IMAGE_PRODUCER_PREDICATE_TYPE,
     DISTRIBUTION_IMAGES_PREDICATE_TYPE,
     IMAGE_DELIVERY_ENTITLEMENT_PREDICATE_TYPE,
+    EDITION_CATALOGUE_PREDICATE_TYPE,
     EVIDENCE_CHANNELS,
     EVIDENCE_CHANNEL_REFS,
     resolveFirstPartyCapabilityDomains,
@@ -927,6 +930,8 @@ export async function loadKernelDistributionSchemas() {
     parseImageProducerStatement,
     parseDistributionImagesStatement,
     parseImageDeliveryEntitlementStatement,
+    parseEditionCatalogueStatement,
+    editionCatalogueRefusal,
     parseDistributionImageEvidenceSet,
     parseDistributionImageReplayState,
     parseSigstoreOfflineTrustPolicy,
@@ -943,6 +948,8 @@ export async function loadKernelDistributionSchemas() {
     IMAGE_PRODUCER_PREDICATE_TYPE,
     DISTRIBUTION_IMAGES_PREDICATE_TYPE,
     IMAGE_DELIVERY_ENTITLEMENT_PREDICATE_TYPE,
+    // Optional: a kernel without the E4 predicate is a catalogue consumer that cannot be armed (trust-policy-arming.mjs).
+    EDITION_CATALOGUE_PREDICATE_TYPE,
     EVIDENCE_CHANNELS,
     EVIDENCE_CHANNEL_REFS,
     resolveFirstPartyCapabilityDomains,

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

@@ -22,6 +22,9 @@ import {
 
 export const IMAGE_SOURCE_EVIDENCE_ARTIFACT_TYPE =
   'application/vnd.xema.image-source-evidence.v2';
+/** The E4 statement an edition artifact carries as an `oras attach` referrer (the catalogue's signed evidence). */
+export const EDITION_CATALOGUE_EVIDENCE_ARTIFACT_TYPE =
+  'application/vnd.xema.edition-catalogue-evidence.v1';
 export const OCI_IMAGE_MANIFEST_MEDIA_TYPE =
   'application/vnd.oci.image.manifest.v1+json';
 const OCI_TITLE_ANNOTATION = 'org.opencontainers.image.title';

package/edition/oras-process.mjs

@@ -8,16 +8,16 @@
 import { execFile } from 'node:child_process';
 
 /**
- * Run `file` with `args`; resolve with stdout bytes. A failure rejects with the
+ * Run `file` with `args` (in `cwd` when given); resolve with stdout bytes. A failure rejects with the
  * child's stderr text on `error.stderr` (a string), so the caller reads the
  * registry status from what oras itself wrote.
  */
-export function runExecutable(file, args, { input, env, timeoutMs, maxBufferBytes }) {
+export function runExecutable(file, args, { input, env, cwd, timeoutMs, maxBufferBytes }) {
   return new Promise((resolve, reject) => {
     const child = execFile(
       file,
       args,
-      { env, timeout: timeoutMs, maxBuffer: maxBufferBytes, encoding: 'buffer' },
+      { env, ...(cwd === undefined ? {} : { cwd }), timeout: timeoutMs, maxBuffer: maxBufferBytes, encoding: 'buffer' },
       (error, stdout, stderr) => {
         if (error) {
           error.stderr = stderr.toString('utf8');

package/edition/oras.mjs

@@ -255,7 +255,7 @@ export function prepareTrustedOras({ env = process.env, trustedDigests, notice =
 /** The default runner: the trusted oras of the configured data root, under the scrubbed environment. */
 function defaultRunner(trust = configuredOrasTrust) {
   let prepared;
-  return async (args, { stdin } = {}) => {
+  return async (args, { stdin, cwd } = {}) => {
     if (prepared === undefined) {
       prepared = prepareTrustedOras({ trustedDigests: trust() });
       process.once('exit', prepared.dispose);
@@ -263,6 +263,7 @@ function defaultRunner(trust = configuredOrasTrust) {
     try {
       return await runExecutable(prepared.path(), args, {
         input: stdin,
+        ...(cwd === undefined ? {} : { cwd }),
         env: orasEnvironment(prepared.home),
         timeoutMs: ORAS_RUN_TIMEOUT_MS,
         maxBufferBytes: ORAS_MAX_BUFFER_BYTES,
@@ -364,7 +365,7 @@ export function disposeRegistrySessions() {
 }
 
 /**
- * A read-only OCI registry client bound to ONE registry authority and ONE
+ * An OCI registry client (reads, and `attach`) bound to ONE registry authority and ONE
  * resolved credential, doing every operation with the pinned oras.
  */
 export class OrasRegistry {
@@ -456,7 +457,7 @@ export class OrasRegistry {
   }
 
   /** One oras invocation under this registry's shared empty config; returns stdout bytes. */
-  async #oras(subcommand, flags, ref) {
+  async #oras(subcommand, flags, ref, { cwd, operands = [] } = {}) {
     await this.#ensureRealmIsSameOrigin();
     const { configPath } = registrySession(this.authority);
     const args = [...subcommand, '--registry-config', configPath];
@@ -465,9 +466,9 @@ export class OrasRegistry {
       args.push('--username', this.#username, '--password-stdin');
       stdin = this.#token;
     }
-    args.push(...flags, ref);
+    args.push(...flags, ref, ...operands);
     try {
-      const out = await this.#run(args, { stdin });
+      const out = await this.#run(args, { stdin, ...(cwd === undefined ? {} : { cwd }) });
       return Buffer.isBuffer(out) ? out : Buffer.from(out ?? '');
     } catch (error) {
       throw this.#failure(ref, error);
@@ -559,6 +560,47 @@ export class OrasRegistry {
     return descriptor;
   }
 
+  /**
+   * ATTACH `files` (paths relative to `cwd`, each with its media type) as an artifact of `artifactType` that is a referrer
+   * of `subjectDigest`, under the same referrers form discover reads ({@link REFERRERS_DISTRIBUTION_SPEC}). Returns the
+   * digest of the referrer manifest oras reports. The only write this client does; the caller states every byte.
+   *
+   * @param {string} repository
+   * @param {string} subjectDigest
+   * @param {{ artifactType: string, files: {path: string, mediaType: string}[], annotations?: Record<string,string>, cwd: string }} attachment
+   */
+  async attach(repository, subjectDigest, { artifactType, files, annotations = {}, cwd }) {
+    if (!SHA256_DIGEST_PATTERN.test(subjectDigest)) {
+      throw new Error(`"${subjectDigest}" is not a canonical lowercase sha256 digest`);
+    }
+    if (typeof artifactType !== 'string' || artifactType.length === 0) {
+      throw new Error('an attach requires a non-empty artifact type');
+    }
+    if (!Array.isArray(files) || files.length === 0 || typeof cwd !== 'string' || !isAbsolute(cwd)) {
+      throw new Error('an attach requires at least one file and an absolute working directory');
+    }
+    const ref = `${this.#ref(repository)}@${subjectDigest}`;
+    const flags = ['--distribution-spec', REFERRERS_DISTRIBUTION_SPEC, '--artifact-type', artifactType];
+    for (const [key, value] of Object.entries(annotations)) {
+      flags.push('--annotation', `${key}=${value}`);
+    }
+    flags.push('--format', 'json');
+    const out = await this.#oras(['attach'], flags, ref, {
+      cwd,
+      operands: files.map((file) => `${file.path}:${file.mediaType}`),
+    });
+    let document;
+    try {
+      document = JSON.parse(out.toString('utf8'));
+    } catch (error) {
+      throw new Error(`${ref} attach did not report JSON: ${error.message}`);
+    }
+    if (!SHA256_DIGEST_PATTERN.test(document?.digest)) {
+      throw new Error(`${ref} attach reported no canonical referrer digest`);
+    }
+    return document.digest;
+  }
+
   /** Every tag of a repository; oras follows the registry's pagination. A failure throws, never an empty list. */
   async listTags(repository) {
     const ref = this.#ref(repository);