@xemahq/xema 0.26.0 → 0.27.0

package/edition/oras.mjs

@@ -0,0 +1,648 @@
+// 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 a fresh 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 digest-addressed read whose bytes do not hash to the requested digest
+//     throws; a tag read is resolved to a descriptor first, then read by digest,
+//     so its bytes are always hash-checked;
+//   * descriptor sizes are checked BEFORE the fetch, actual lengths after it;
+//   * 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 { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  accessSync,
+  constants,
+  mkdtempSync,
+  realpathSync,
+  rmSync,
+  statSync,
+  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 {
+  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: {"required": false}` with no policy):
+ * 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` (a data
+ * root that declares no evidence trust) 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: this data root declares no evidence-trust pin, ` +
+            '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 (args, { stdin } = {}) => {
+    if (prepared === undefined) {
+      prepared = prepareTrustedOras({ trustedDigests: trust() });
+      process.once('exit', prepared.dispose);
+    }
+    try {
+      return execFileSync(prepared.path(), args, {
+        input: stdin,
+        env: orasEnvironment(prepared.home),
+        timeout: ORAS_RUN_TIMEOUT_MS,
+        maxBuffer: ORAS_MAX_BUFFER_BYTES,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+    } 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;
+}
+
+/**
+ * A read-only OCI registry client 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 with an empty registry config; returns stdout bytes. */
+  async #oras(subcommand, flags, ref) {
+    await this.#ensureRealmIsSameOrigin();
+    const configDirectory = mkdtempSync(join(tmpdir(), 'xema-oras-'));
+    const configPath = join(configDirectory, 'registry-config.json');
+    try {
+      writeFileSync(configPath, '');
+      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);
+      try {
+        const out = await this.#run(args, { stdin });
+        return Buffer.isBuffer(out) ? out : Buffer.from(out ?? '');
+      } catch (error) {
+        throw this.#failure(ref, error);
+      }
+    } finally {
+      rmSync(configDirectory, { recursive: true, force: true });
+    }
+  }
+
+  #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;
+  }
+
+  /** 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 by TAG: resolve the descriptor, then read by digest, so the
+   * bytes are always hash-checked against what the registry said the tag is.
+   */
+  async getManifestByTag(repository, tag) {
+    const ref = `${this.#ref(repository)}:${tag}`;
+    const out = await this.#oras(['manifest', 'fetch'], ['--descriptor'], ref);
+    const descriptor = this.#parseDescriptor(out, ref);
+    if (!ACCEPTED_MANIFEST_MEDIA_TYPES.includes(descriptor.mediaType)) {
+      throw new Error(
+        `${ref} returned unsupported manifest media type "${descriptor.mediaType}"`,
+      );
+    }
+    if (descriptor.size > MAX_MANIFEST_BYTES) {
+      throw new Error(`${ref} declares ${descriptor.size} bytes, exceeding ${MAX_MANIFEST_BYTES}`);
+    }
+    return this.#manifestByDigest(repository, descriptor.digest, descriptor.mediaType);
+  }
+
+  /** Fetch a manifest by DIGEST; the bytes must hash to exactly that digest. */
+  async getManifestByDigest(repository, digest) {
+    return this.#manifestByDigest(repository, digest, null);
+  }
+
+  async #manifestByDigest(repository, digest, expectedMediaType) {
+    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.#oras(['manifest', 'fetch'], [], ref);
+    if (bytes.length > MAX_MANIFEST_BYTES) {
+      throw new Error(`${ref} returned more than ${MAX_MANIFEST_BYTES} bytes`);
+    }
+    const actual = sha256DigestOf(bytes);
+    if (actual !== digest) {
+      throw new Error(`${ref} returned content addressed ${actual}, not the requested ${digest}`);
+    }
+    return { ...decodeManifest(bytes, expectedMediaType, ref), digest, bytes };
+  }
+
+  /** Fetch a blob by DIGEST; the descriptor size is checked before the fetch, the bytes after. */
+  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 described = await this.#oras(['blob', 'fetch'], ['--descriptor'], ref);
+    const descriptor = this.#parseDescriptor(described, ref);
+    if (descriptor.digest !== digest) {
+      throw new Error(`${ref} described ${descriptor.digest}, not the requested ${digest}`);
+    }
+    if (descriptor.size > maxBytes) {
+      throw new Error(`${ref} declares ${descriptor.size} bytes, exceeding ${maxBytes}`);
+    }
+    const bytes = await this.#oras(['blob', 'fetch'], ['--output', '-'], ref);
+    if (bytes.length > maxBytes) {
+      throw new Error(`${ref} returned more than ${maxBytes} bytes`);
+    }
+    const actual = sha256DigestOf(bytes);
+    if (actual !== digest) {
+      throw new Error(`${ref} returned content addressed ${actual}, 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 ?? document.mediaType;
+  if (!ACCEPTED_MANIFEST_MEDIA_TYPES.includes(mediaType)) {
+    throw new Error(
+      `${ref} returned unsupported manifest media type "${mediaType || '(none)'}"`,
+    );
+  }
+  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,
+  };
+}