@xemahq/xema 0.59.1 → 0.60.1

package/edition/oras.mjs

@@ -1,742 +0,0 @@
-// OCI registry read transport for delivery-time verification, done by the
-// pinned `oras` CLI.
-//
-// This module owns one concern: getting BYTES out of a real registry and
-// proving they are the bytes that were asked for. It does not know what a
-// distribution is or why anything is being fetched. The credential
-// DECLARATION contract lives in `registry-credentials.mjs`.
-//
-// Every read is fail-closed, and there is no retry and no fallback:
-//   * the oras binary is a TRUSTED EXECUTABLE: on a data root that declares an
-//     evidence-trust pin its bytes must hash to one of the pin's
-//     `trustedOrasBinaryDigests`, and it runs from a private copy of exactly
-//     those bytes; its version must be the one this module's parsing is written
-//     against;
-//   * oras runs under a scrubbed environment (no ambient proxy, config or
-//     credential variable reaches it) and an EMPTY registry config, so
-//     ambient docker/oras credentials are never used and an authenticated
-//     registry never degrades into an anonymous read;
-//   * the token travels on stdin only (`--password-stdin`), never in argv;
-//   * before oras ever receives a credential, the registry's own `/v2/`
-//     challenge is probed and a token realm on another origin is refused;
-//   * a manifest or blob is fetched in ONE call (`--descriptor --output <file>`:
-//     the descriptor on stdout, the raw content in a scratch file). Its bytes
-//     must hash to the digest the registry described (and, for a digest read,
-//     to the requested digest), or the read throws; the manifest media type is
-//     the descriptor's, never the manifest body's optional `mediaType` (Helm's
-//     has none);
-//   * declared size, on-disk size and read length are all held to the cap
-//     BEFORE the content is read into memory;
-//   * oras runs asynchronously, so a caller's worker pool really runs in parallel;
-//   * every call of one registry shares one empty registry config for the run;
-//   * a registry status is read only from oras's own error forms; any other
-//     failure carries no status and is thrown as undecided;
-//   * `--plain-http` and `--insecure` are never passed.
-
-import { createHash, randomUUID } from 'node:crypto';
-import {
-  accessSync,
-  constants,
-  mkdtempSync,
-  readFileSync,
-  realpathSync,
-  rmSync,
-  statSync,
-  unlinkSync,
-  writeFileSync,
-} from 'node:fs';
-import { tmpdir } from 'node:os';
-import { delimiter, isAbsolute, join } from 'node:path';
-
-import { editionWorkspaceConfig } from './edition-config.mjs';
-import { dataRoot as configuredDataRoot } from './edition-workspace.mjs';
-import { SHA256_DIGEST_PATTERN } from './evidence-grammars.mjs';
-import { readEvidenceTrustPin } from './evidence-trust-pin.mjs';
-import { runExecutable } from './oras-process.mjs';
-import {
-  OCI_INDEX_MEDIA_TYPES,
-  REGISTRY_CREDENTIALS_FILE,
-} from './registry-credentials.mjs';
-import {
-  assertPreparedExecutable,
-  exactExecutableOutput,
-  prepareDigestPinnedExecutable,
-} from './trusted-executable.mjs';
-
-/** The oras version whose arguments, JSON and error forms this module is written against. */
-export const ORAS_PINNED_VERSION = '1.3.4';
-
-/**
- * The referrers form every artifact is ATTACHED and DISCOVERED with. One
- * constant for both directions: an artifact attached under the referrers tag
- * schema is only found by a discover that reads the same schema.
- */
-export const REFERRERS_DISTRIBUTION_SPEC = 'v1.1-referrers-tag';
-
-/** The refusal of a Bearer token realm on another origin than the registry's. */
-export const REGISTRY_TOKEN_REALM_CROSS_HOST = 'REGISTRY_TOKEN_REALM_CROSS_HOST';
-
-export class RegistryTokenRealmError extends Error {
-  /** @param {string} authority @param {string} realmOrigin */
-  constructor(authority, realmOrigin) {
-    super(
-      `registry ${authority} advertised token realm "${realmOrigin}", which is not its own origin; ` +
-        'the pull credential is never sent to a third-party host',
-    );
-    this.name = 'RegistryTokenRealmError';
-    this.code = REGISTRY_TOKEN_REALM_CROSS_HOST;
-  }
-}
-
-const ORAS_VERSION_PATTERN = /^Version:\s+1\.3\.4(\+\S+)?$/m;
-const ORAS_BIN_ENV = 'XEMA_ORAS_BIN';
-const ORAS_RUN_TIMEOUT_MS = 120_000;
-const ORAS_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
-
-const ACCEPTED_MANIFEST_MEDIA_TYPES = Object.freeze([
-  ...OCI_INDEX_MEDIA_TYPES,
-  'application/vnd.oci.image.manifest.v1+json',
-  'application/vnd.docker.distribution.manifest.v2+json',
-]);
-
-const REGISTRY_REQUEST_TIMEOUT_MS = 30_000;
-const MAX_MANIFEST_BYTES = 4 * 1024 * 1024;
-const MAX_DESCRIPTOR_BYTES = 64 * 1024;
-const MAX_CONFIG_BLOB_BYTES = 4 * 1024 * 1024;
-const MAX_ERROR_DETAIL_CHARS = 512;
-
-function sha256DigestOf(bytes) {
-  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
-}
-
-function isExecutableFile(path) {
-  try {
-    if (!statSync(path).isFile()) {return false;}
-    accessSync(path, constants.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function firstOnPath(env) {
-  for (const directory of (env.PATH ?? '').split(delimiter)) {
-    if (!directory) {continue;}
-    const candidate = join(directory, 'oras');
-    if (isExecutableFile(candidate)) {return candidate;}
-  }
-  return null;
-}
-
-/**
- * The oras binary as a real file: `XEMA_ORAS_BIN` (an absolute path) wins,
- * otherwise the first `oras` on PATH. Symbolic links are resolved here, so the
- * path returned is the file whose bytes are digested. Nothing is executed.
- */
-export function locateOras({ env = process.env } = {}) {
-  let bin;
-  if (env[ORAS_BIN_ENV] !== undefined && env[ORAS_BIN_ENV] !== '') {
-    bin = env[ORAS_BIN_ENV];
-    if (!isAbsolute(bin)) {
-      throw new Error(`${ORAS_BIN_ENV} must be an absolute path to the oras binary, got "${bin}"`);
-    }
-  } else {
-    bin = firstOnPath(env);
-    if (!bin) {
-      throw new Error(
-        `no oras binary found on PATH; install oras ${ORAS_PINNED_VERSION} or set ${ORAS_BIN_ENV} to its absolute path`,
-      );
-    }
-  }
-  try {
-    return realpathSync(bin);
-  } catch (error) {
-    throw new Error(`the oras binary ${bin} is not readable: ${error.message}`);
-  }
-}
-
-/** The environment oras runs under: nothing ambient, and a HOME that holds nothing. */
-function orasEnvironment(home) {
-  return { HOME: home, LANG: 'C', LC_ALL: 'C', PATH: '/usr/bin:/bin', TZ: 'UTC' };
-}
-
-function assertOrasVersion(bin, home) {
-  let output;
-  try {
-    output = exactExecutableOutput(bin, ['version'], { timeout: 30_000, env: orasEnvironment(home) });
-  } catch (error) {
-    throw new Error(
-      `could not run "${bin} version": ${error instanceof Error ? error.message : String(error)}`,
-    );
-  }
-  if (!ORAS_VERSION_PATTERN.test(output)) {
-    const found = /^Version:\s+(\S+)/m.exec(output)?.[1] ?? '(unreadable)';
-    throw new Error(
-      `${bin} is oras ${found}, but this tooling is pinned to oras ${ORAS_PINNED_VERSION}`,
-    );
-  }
-  return /^Version:\s+(\S+)/m.exec(output)[1];
-}
-
-/**
- * The oras digests the configured data root trusts: `trustedOrasBinaryDigests`
- * of its evidence-trust pin. `null` when the data root declares no evidence
- * trust at all (`evidenceTrustPolicy: null`):
- * such a data root has no reviewed pin to hold a binary to.
- */
-export function configuredOrasTrust() {
-  const declaration = editionWorkspaceConfig().evidenceTrustPolicy;
-  if (declaration.policy === null) {return null;}
-  return readEvidenceTrustPin({ dataRoot: configuredDataRoot(), declaration })
-    .trustedOrasBinaryDigests;
-}
-
-/** Each notice sink is told once: the default `console.warn` once per process, a test's own sink once per test. */
-const noticesGiven = new WeakSet();
-
-/**
- * Prepare the oras binary for use. With `trustedDigests` (an array) the binary
- * must hash to one of them and a private copy of exactly those bytes is what
- * runs; an empty list trusts no binary. With `trustedDigests: null` (no
- * evidence trust in force: a publisher's run with no data root, or a data root
- * that declares none) the binary is held to its version only,
- * and the run says so once.
- *
- * @returns {{version: string, pinned: boolean, path: () => string, dispose: () => void}}
- */
-export function prepareTrustedOras({ env = process.env, trustedDigests, notice = console.warn } = {}) {
-  if (trustedDigests !== null && !Array.isArray(trustedDigests)) {
-    throw new Error('the trusted oras digests are a list, or null for a data root that declares no evidence trust');
-  }
-  const located = locateOras({ env });
-  const home = mkdtempSync(join(tmpdir(), 'xema-oras-home-'));
-  try {
-    if (trustedDigests === null) {
-      const version = assertOrasVersion(located, home);
-      if (!noticesGiven.has(notice)) {
-        noticesGiven.add(notice);
-        notice(
-          `[oras] ${located} is held to its version (${version}) only: no evidence-trust pin is in force ` +
-            '(a publisher run, or a data root that declares none), so there are no trustedOrasBinaryDigests to hold it to.',
-        );
-      }
-      return {
-        version,
-        pinned: false,
-        home,
-        path: () => located,
-        dispose: () => rmSync(home, { recursive: true, force: true }),
-      };
-    }
-    let version;
-    const handle = prepareDigestPinnedExecutable({
-      executablePath: located,
-      trustedDigests,
-      label: 'oras',
-      verifyVersion: (privateBinary) => {
-        version = assertOrasVersion(privateBinary, home);
-      },
-    });
-    return {
-      version,
-      pinned: true,
-      home,
-      path: () => assertPreparedExecutable(handle, 'oras'),
-      dispose: () => {
-        handle.dispose();
-        rmSync(home, { recursive: true, force: true });
-      },
-    };
-  } catch (error) {
-    rmSync(home, { recursive: true, force: true });
-    throw error;
-  }
-}
-
-/** 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, cwd } = {}) => {
-    if (prepared === undefined) {
-      prepared = prepareTrustedOras({ trustedDigests: trust() });
-      process.once('exit', prepared.dispose);
-    }
-    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,
-      });
-    } catch (error) {
-      const stderr = error?.stderr ? error.stderr.toString('utf8') : '';
-      const wrapped = new Error(stderr.trim() || (error instanceof Error ? error.message : String(error)));
-      // Only what oras itself wrote is offered as a registry answer; a spawn
-      // failure, a timeout or a signal carries no stderr and so no status.
-      wrapped.stderr = stderr;
-      throw wrapped;
-    }
-  };
-}
-
-function parseWwwAuthenticate(header) {
-  if (typeof header !== 'string' || !/^Bearer\s/i.test(header)) {return null;}
-  const parameters = new Map();
-  const pattern = /([a-zA-Z_]+)="((?:[^"\\]|\\.)*)"/g;
-  let match = pattern.exec(header);
-  while (match) {
-    parameters.set(match[1], match[2].replace(/\\(.)/g, '$1'));
-    match = pattern.exec(header);
-  }
-  const realm = parameters.get('realm');
-  if (!realm) {return null;}
-  return { realm };
-}
-
-const ORAS_REGISTRY_ERROR_PREFIX = 'Error response from registry: ';
-const ORAS_ERROR_PREFIX = 'Error: ';
-
-/**
- * The HTTP status a registry answered with; null when the failure is not a
- * registry answer.
- *
- * oras 1.3.4 has no structured error output and exits 1 for every failure, so
- * the status is read from its stderr, and ONLY from the forms oras itself
- * prints (captured against a registry; see oras.test.mjs). The FIRST line of
- * stderr must be oras's own error line, and within it:
- *   * `Error response from registry: … response status code <NNN>: …` carries
- *     the registry's status itself;
- *   * `Error response from registry: … <ref>: not found` and
- *     `Error: … <ref>: not found`, ending the line with the EXACT reference that
- *     was asked for, are oras's resolution of a 404;
- *   * `Error response from registry: name unknown: …` is the registry's error
- *     code for a missing repository, in the position oras prints it.
- * Everything else is null: text from a wrapper, a shell (`oras: not found`,
- * `Permission denied`), a proxy or a transport failure is not a registry
- * answer, whatever words it contains, and neither is a status-like word inside
- * a reference or a quoted string. A null status is thrown by the caller as an
- * UNDECIDED failure; it is never read as "absent".
- */
-export function statusOfOrasFailure(text, { ref = '' } = {}) {
-  const [line] = String(text).split('\n');
-  const fromRegistry = line.startsWith(ORAS_REGISTRY_ERROR_PREFIX);
-  if (!fromRegistry && !line.startsWith(ORAS_ERROR_PREFIX)) {return null;}
-  if (fromRegistry) {
-    // The status oras reports sits after the quoted request URL; a reference
-    // that spells `response status code 404` is inside the quotes.
-    const explicit = /\bresponse status code (\d{3})\b/.exec(line.replace(/"(?:[^"\\]|\\.)*"/g, '""'));
-    if (explicit) {return Number(explicit[1]);}
-    if (/^name unknown: /.test(line.slice(ORAS_REGISTRY_ERROR_PREFIX.length))) {return 404;}
-  }
-  if (ref && line.endsWith(` ${ref}: not found`)) {return 404;}
-  return null;
-}
-
-/**
- * ONE oras working directory per registry authority per process: the (empty)
- * registry config every call of that registry points at, and the scratch
- * files a fetch writes its content to. The config never holds a credential
- * (that goes to oras on stdin, per call), so sharing it carries no secret; it
- * replaces a temp directory made and removed around every single call.
- */
-const registrySessions = new Map();
-
-function registrySession(authority) {
-  let session = registrySessions.get(authority);
-  if (session === undefined) {
-    const directory = mkdtempSync(join(tmpdir(), 'xema-oras-'));
-    const configPath = join(directory, 'registry-config.json');
-    writeFileSync(configPath, '');
-    session = { directory, configPath };
-    registrySessions.set(authority, session);
-    if (registrySessions.size === 1) {
-      process.once('exit', disposeRegistrySessions);
-    }
-  }
-  return session;
-}
-
-/** Remove every registry session directory; called at process exit, and by tests. */
-export function disposeRegistrySessions() {
-  for (const { directory } of registrySessions.values()) {
-    rmSync(directory, { recursive: true, force: true });
-  }
-  registrySessions.clear();
-}
-
-/**
- * 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 {
-  #credential;
-  #run;
-  #fetchImpl;
-  #username = null;
-  #token = null;
-  #realmCheck = null;
-
-  /**
-   * `run` replaces the oras invocation (tests). Without it the trusted oras of
-   * the configured data root runs; `trust` states the trusted digests instead
-   * of reading them from the data root's pin.
-   */
-  constructor({ credential, run, trust, fetchImpl = globalThis.fetch }) {
-    if (typeof credential?.authority !== 'string') {
-      throw new Error('an oras registry requires a resolved credential');
-    }
-    if (typeof fetchImpl !== 'function') {
-      throw new Error('an oras registry requires a fetch implementation for the token-realm check');
-    }
-    this.#credential = credential;
-    this.#run = run ?? defaultRunner(trust);
-    this.#fetchImpl = fetchImpl;
-    if (credential.access === 'authenticated') {
-      const decoded = Buffer.from(credential.basicAuth ?? '', 'base64').toString('utf8');
-      const colon = decoded.indexOf(':');
-      if (colon <= 0 || colon === decoded.length - 1) {
-        throw new Error(`registry ${credential.authority} is authenticated but its credential is incomplete`);
-      }
-      this.#username = decoded.slice(0, colon);
-      this.#token = decoded.slice(colon + 1);
-    }
-  }
-
-  get authority() {
-    return this.#credential.authority;
-  }
-
-  /**
-   * The Bearer token realm must be the registry's OWN origin. Checked once,
-   * with an unauthenticated probe, BEFORE oras is handed the credential: a
-   * registry that points its realm at another host would otherwise receive the
-   * pull token (a credential exfiltration primitive).
-   */
-  #ensureRealmIsSameOrigin() {
-    if (this.#credential.access !== 'authenticated') {return Promise.resolve();}
-    this.#realmCheck ??= this.#probeRealm();
-    return this.#realmCheck;
-  }
-
-  async #probeRealm() {
-    const origin = `https://${this.authority}`;
-    let response;
-    try {
-      response = await this.#fetchImpl(`${origin}/v2/`, {
-        method: 'GET',
-        redirect: 'manual',
-        headers: { 'user-agent': 'xema-edition-platform-verifier/1' },
-        signal: AbortSignal.timeout(REGISTRY_REQUEST_TIMEOUT_MS),
-      });
-    } catch (error) {
-      throw new Error(
-        `registry request to ${origin}/v2/ failed: ${error instanceof Error ? error.message : String(error)}`,
-      );
-    }
-    if (response.status === 200) {return;}
-    if (response.status !== 401) {
-      throw new Error(`registry ${this.authority} answered its /v2/ probe with ${response.status}`);
-    }
-    const challenge = parseWwwAuthenticate(response.headers.get('www-authenticate'));
-    if (!challenge) {return;}
-    let url;
-    try {
-      url = new URL(challenge.realm);
-    } catch {
-      throw new Error(
-        `registry ${this.authority} advertised a token realm that is not an absolute URL`,
-      );
-    }
-    if (url.origin !== origin) {
-      throw new RegistryTokenRealmError(this.authority, url.origin);
-    }
-  }
-
-  #scrub(text) {
-    return this.#token ? text.split(this.#token).join('***') : text;
-  }
-
-  /** One oras invocation under this registry's shared empty config; returns stdout bytes. */
-  async #oras(subcommand, flags, ref, { cwd, operands = [] } = {}) {
-    await this.#ensureRealmIsSameOrigin();
-    const { configPath } = registrySession(this.authority);
-    const args = [...subcommand, '--registry-config', configPath];
-    let stdin;
-    if (this.#credential.access === 'authenticated') {
-      args.push('--username', this.#username, '--password-stdin');
-      stdin = this.#token;
-    }
-    args.push(...flags, ref, ...operands);
-    try {
-      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);
-    }
-  }
-
-  /**
-   * ONE oras call that returns the descriptor (stdout) AND the raw content
-   * (written to a scratch file by `--output`): the call that used to be a
-   * descriptor round trip followed by a content round trip. The content is
-   * read into memory only after both its declared and its on-disk size are
-   * inside `maxBytes`.
-   */
-  async #fetchContent(subcommand, ref, maxBytes, acceptDescriptor) {
-    const { directory } = registrySession(this.authority);
-    const outputPath = join(directory, `content-${randomUUID()}`);
-    try {
-      const described = await this.#oras(subcommand, ['--descriptor', '--output', outputPath], ref);
-      const descriptor = this.#parseDescriptor(described, ref);
-      acceptDescriptor(descriptor);
-      if (descriptor.size > maxBytes) {
-        throw new Error(`${ref} declares ${descriptor.size} bytes, exceeding ${maxBytes}`);
-      }
-      const onDisk = statSync(outputPath).size;
-      if (onDisk > maxBytes) {
-        throw new Error(`${ref} returned more than ${maxBytes} bytes`);
-      }
-      const bytes = readFileSync(outputPath);
-      const actual = sha256DigestOf(bytes);
-      if (actual !== descriptor.digest) {
-        throw new Error(`${ref} returned content addressed ${actual}, not the digest ${descriptor.digest} it described`);
-      }
-      return { descriptor, bytes };
-    } finally {
-      try {
-        unlinkSync(outputPath);
-      } catch {
-        // No content file exists when the fetch itself failed; the failure is already thrown.
-      }
-    }
-  }
-
-  #failure(ref, error) {
-    // The status comes from oras's stderr ALONE. A failure with no stderr (the
-    // binary did not start, timed out, was killed) is local, and its message is
-    // shown but never parsed for a status.
-    const stderr = this.#scrub(typeof error?.stderr === 'string' ? error.stderr.trim() : '');
-    const status = stderr ? statusOfOrasFailure(stderr, { ref }) : null;
-    const raw = this.#scrub(error instanceof Error ? error.message : String(error));
-    const detail = (stderr || raw).slice(0, MAX_ERROR_DETAIL_CHARS).trim();
-    if (status === null) {
-      return new Error(`registry request to ${ref} failed: ${detail}`);
-    }
-    const hint =
-      (status === 401 || status === 403) && this.#credential.access === 'anonymous'
-        ? ` — registry "${this.authority}" is declared "anonymous" in ${REGISTRY_CREDENTIALS_FILE}; if its packages are private, declare it "authenticated"`
-        : '';
-    const failure = new Error(
-      `${ref} returned HTTP ${status}${hint}${detail ? `: ${detail}` : ''}`,
-    );
-    failure.status = status;
-    return failure;
-  }
-
-  #ref(repository) {
-    return `${this.authority}/${repository}`;
-  }
-
-  #parseDescriptor(bytes, ref) {
-    if (bytes.length > MAX_DESCRIPTOR_BYTES) {
-      throw new Error(`${ref} descriptor is larger than ${MAX_DESCRIPTOR_BYTES} bytes`);
-    }
-    let descriptor;
-    try {
-      descriptor = JSON.parse(bytes.toString('utf8'));
-    } catch (error) {
-      throw new Error(`${ref} descriptor is not JSON: ${error.message}`);
-    }
-    if (
-      typeof descriptor !== 'object' ||
-      descriptor === null ||
-      typeof descriptor.mediaType !== 'string' ||
-      !SHA256_DIGEST_PATTERN.test(descriptor.digest) ||
-      !Number.isSafeInteger(descriptor.size) ||
-      descriptor.size < 0
-    ) {
-      throw new Error(`${ref} did not return a usable descriptor`);
-    }
-    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);
-    const out = await this.#oras(['repo', 'tags'], [], ref);
-    return out
-      .toString('utf8')
-      .split('\n')
-      .map((line) => line.trim())
-      .filter((line) => line.length > 0);
-  }
-
-  /**
-   * Referrers whose subject is the exact immutable digest, filtered by artifact
-   * type, read under the SAME referrers form evidence is attached with
-   * ({@link REFERRERS_DISTRIBUTION_SPEC}). Every returned descriptor is still re-read by digest by the caller.
-   */
-  async listReferrers(repository, subjectDigest, artifactType) {
-    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('referrers query requires a non-empty artifact type');
-    }
-    const ref = `${this.#ref(repository)}@${subjectDigest}`;
-    const out = await this.#oras(
-      ['discover'],
-      ['--distribution-spec', REFERRERS_DISTRIBUTION_SPEC, '--format', 'json', '--artifact-type', artifactType],
-      ref,
-    );
-    if (out.length > MAX_MANIFEST_BYTES) {
-      throw new Error(`${ref} referrers listing is larger than ${MAX_MANIFEST_BYTES} bytes`);
-    }
-    let document;
-    try {
-      document = JSON.parse(out.toString('utf8'));
-    } catch (error) {
-      throw new Error(`${ref} referrers listing is not JSON: ${error.message}`);
-    }
-    if (!Array.isArray(document?.referrers)) {
-      throw new Error(`${ref} did not return a referrers listing`);
-    }
-    const seen = new Set();
-    const manifests = [];
-    for (const referrer of document.referrers) {
-      if (!SHA256_DIGEST_PATTERN.test(referrer?.digest)) {
-        throw new Error(`${ref} listed a referrer without a canonical digest`);
-      }
-      if (referrer.artifactType !== artifactType) {continue;}
-      if (seen.has(referrer.digest)) {
-        throw new Error(`registry ${this.authority} repeated referrer ${referrer.digest}`);
-      }
-      seen.add(referrer.digest);
-      manifests.push({
-        mediaType: referrer.mediaType,
-        digest: referrer.digest,
-        size: referrer.size,
-        artifactType: referrer.artifactType,
-        ...(referrer.annotations ? { annotations: referrer.annotations } : {}),
-      });
-    }
-    return manifests;
-  }
-
-  /**
-   * Fetch a manifest in ONE call and hold it to everything a separate
-   * descriptor call used to: its media type is an accepted manifest type, its
-   * size is inside the cap, and its bytes hash to the digest the registry
-   * described. `expectedDigest`, when the caller asked by digest, must be that
-   * digest. The media type is the descriptor's, never the body's optional
-   * `mediaType` (Helm's has none).
-   */
-  async #manifest(ref, expectedDigest) {
-    const { descriptor, bytes } = await this.#fetchContent(['manifest', 'fetch'], ref, MAX_MANIFEST_BYTES, (described) => {
-      if (!ACCEPTED_MANIFEST_MEDIA_TYPES.includes(described.mediaType)) {
-        throw new Error(`${ref} returned unsupported manifest media type "${described.mediaType}"`);
-      }
-      if (expectedDigest !== undefined && described.digest !== expectedDigest) {
-        throw new Error(`${ref} described ${described.digest}, not the requested ${expectedDigest}`);
-      }
-    });
-    return { ...decodeManifest(bytes, descriptor.mediaType, ref), digest: descriptor.digest, bytes };
-  }
-
-  /** Fetch a manifest by TAG: one call, the content verified against the digest the registry described. */
-  async getManifestByTag(repository, tag) {
-    return this.#manifest(`${this.#ref(repository)}:${tag}`);
-  }
-
-  /** Fetch a manifest by DIGEST: one call, the bytes must hash to exactly that digest. */
-  async getManifestByDigest(repository, digest) {
-    if (!SHA256_DIGEST_PATTERN.test(digest)) {
-      throw new Error(`"${digest}" is not a canonical lowercase sha256 digest`);
-    }
-    return this.#manifest(`${this.#ref(repository)}@${digest}`, digest);
-  }
-
-  /** Fetch a blob by DIGEST in one call; its declared and actual size are bounded by `maxBytes`, its bytes must hash to that digest. */
-  async getBlob(repository, digest, maxBytes = MAX_CONFIG_BLOB_BYTES) {
-    if (!SHA256_DIGEST_PATTERN.test(digest)) {
-      throw new Error(`"${digest}" is not a canonical lowercase sha256 digest`);
-    }
-    const ref = `${this.#ref(repository)}@${digest}`;
-    const { bytes } = await this.#fetchContent(['blob', 'fetch'], ref, maxBytes, (described) => {
-      if (described.digest !== digest) {
-        throw new Error(`${ref} described ${described.digest}, not the requested ${digest}`);
-      }
-    });
-    return bytes;
-  }
-}
-
-function decodeManifest(bytes, expectedMediaType, ref) {
-  let document;
-  try {
-    document = JSON.parse(bytes.toString('utf8'));
-  } catch (error) {
-    throw new Error(`${ref} returned a manifest that is not valid JSON: ${error.message}`);
-  }
-  if (typeof document !== 'object' || document === null || Array.isArray(document)) {
-    throw new Error(`${ref} returned a manifest that is not a JSON object`);
-  }
-  const mediaType = expectedMediaType;
-  if (!ACCEPTED_MANIFEST_MEDIA_TYPES.includes(mediaType)) {
-    throw new Error(
-      `${ref} returned unsupported manifest media type "${mediaType}"`,
-    );
-  }
-  if (typeof document.mediaType === 'string' && document.mediaType !== mediaType) {
-    throw new Error(
-      `${ref} served media type "${mediaType}" but the manifest declares "${document.mediaType}"`,
-    );
-  }
-  return {
-    mediaType,
-    isIndex: OCI_INDEX_MEDIA_TYPES.includes(mediaType),
-    document,
-  };
-}