@xemahq/edition-tooling 0.0.0-stage → 0.1.1

package/edition/oras.mjs

@@ -0,0 +1,664 @@
+// 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 {
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+
+import {
+  assertOrasVersion,
+  locateOras,
+  orasScrubbedEnvironment,
+  REFERRERS_DISTRIBUTION_SPEC,
+} from '@xemahq/oci-closure';
+
+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,
+  prepareDigestPinnedExecutable,
+} from './trusted-executable.mjs';
+
+/** 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_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')}`;
+}
+
+/**
+ * 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: orasScrubbedEnvironment(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,
+  };
+}