@xemahq/edition-tooling 0.0.0-stage → 0.1.1

package/edition/fleet-coordinate-finality.mjs

@@ -0,0 +1,363 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// fleet-coordinate-finality — has this coordinate FINISHED MOVING?
+//
+// WHY THIS EXISTS
+// ---------------
+// A seal pins what a MUTABLE TAG currently resolves to. `imageRef:contentHash`
+// is a build-input key, not a content address: two builds of one input set wear
+// the same tag, and the arm64 lane REPUBLISHES that tag by design —
+// `imagetools create -t :<contentHash>` writes a NEW index at the SAME
+// coordinate. So sealing a coordinate that is still awaiting its arm64
+// supplement pins a manifest the tag will stop serving.
+//
+// THE REGRESSION THIS WAS WRITTEN FOR, measured — and how it is now graded
+// -----------------------------------------------------------------------
+// `xema-internal` was sealed at 09:25 on 2026-09-18 while 40 of its coordinates
+// were still amd64-only, awaiting the supplement. The arm64 backfill — the
+// CORRECT repair — then moved those digests, and 63 of its 66 seals named a
+// manifest their tag no longer served.
+//
+// Its own per-edition verification PASSED, and passed CORRECTLY: `xema-internal`
+// declares `requiredPlatforms: ["linux/amd64"]`, and amd64-only satisfies that.
+// No rule the sealer could evaluate was violated.
+//
+// WHY A PER-EDITION CHECK CANNOT CATCH IT — the whole point of this module
+// -----------------------------------------------------------------------
+// `appliance-base` and `appliance-lean` declare `linux/arm64`, and they share 63
+// of those coordinates with `xema-internal` by identical `imageRef` AND
+// `contentHash`. So `xema-internal`'s stability depended on a platform
+// requirement declared in an edition it cannot see.
+//
+//   > PLATFORM VERIFICATION IS PER-EDITION. FINALITY IS A FLEET PROPERTY.
+//
+// OWNER RULING 2026-09-29 NARROWS WHAT IS REFUSED. Finality is graded against
+// the sealing edition's OWN requiredPlatforms. The xema-internal shape above —
+// an amd64-only edition sealing while another edition's arm64 is pending — is
+// now ALLOWED and RECORDED (`pendingElsewhere`), the residual accepted: its
+// sealed digest stays resolvable and serves every platform it requires. A
+// coordinate pending a platform the sealing edition itself declares is still
+// refused. The fleet map is still built from every edition, because the
+// recorded residual must name who is waiting.
+//
+// A per-edition sealer cannot express that even in principle. This module is the
+// fleet-scoped half, and it lives HERE — beside the sealer, in the repository
+// that holds every edition's lock — because that is where the data and the edit
+// both are. An aggregator gate would grade this repository at a RECORDED
+// GITLINK: it would fire late, in a repository nobody was editing, about a
+// change made somewhere else.
+//
+// IT RESOLVES NOTHING ITSELF
+// --------------------------
+// `verifyDistributionPlatforms` already fetches each index, hash-checks the
+// bytes, walks every child manifest BY DIGEST and reads each image CONFIG for
+// its real platform — and it already returns `publishedPlatforms`, the FULL set
+// the coordinate serves rather than only the subset this edition required. That
+// return value is the input here. There is no second registry walk and no
+// second opinion about what a coordinate serves.
+//
+// WHAT IT DOES NOT COVER, said out loud rather than discovered
+// -----------------------------------------------------------
+// The fleet is the EDITIONS ROOT IT IS GIVEN. Run against a customer's own root
+// it grades that customer's editions and cannot see the vendor's, because they
+// are not there to read. That is why every verdict prints its corpus — the
+// number of editions and coordinates graded — so the scope of an answer is
+// visible in the answer rather than assumed from the fact that it passed.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { discoverEditionDirectories } from './distribution-paths.mjs';
+import { platformIdentity } from './verify-image-platforms.mjs';
+
+export const IMAGE_LOCK_FILENAME = 'images.lock.json';
+
+/**
+ * The coordinate a subject names, in the ONE spelling the verifier uses.
+ *
+ * `verifyDistributionPlatforms` builds `${imageRef}:${contentHash}` and returns
+ * it as `coordinate` on every verified subject. This function must produce the
+ * same string for the lock-side map, or the two halves would silently fail to
+ * join and every lookup would miss — which is a refusal that grades nothing
+ * while reporting success. The join is asserted rather than trusted: see the
+ * unknown-coordinate throw in {@link assertCoordinatesFinal}.
+ */
+export function coordinateOf(subject) {
+  return `${subject.imageRef}:${subject.contentHash}`;
+}
+
+/**
+ * Pure: every platform any edition requires at each coordinate, and WHO
+ * requires it.
+ *
+ * `editions` is `[{ distributionId, subjects }]` — already read, so the
+ * decision table is testable without a filesystem or a registry.
+ *
+ * The returned shape is `Map<coordinate, Map<platformIdentity, string[]>>`,
+ * where the array is the sorted edition ids requiring that platform there. The
+ * REQUIRERS are carried rather than only the platforms because a refusal that
+ * cannot name who is still waiting sends the reader to look for the reason
+ * themselves, and the reason is in another edition's declaration.
+ */
+export function collectFleetPlatformRequirements({ editions, isThirdPartySubject = () => false }) {
+  if (!Array.isArray(editions) || editions.length === 0) {
+    throw new Error(
+      'fleet-coordinate-finality: no edition was supplied; a fleet requirement map ' +
+        'built over zero editions would make every coordinate look final, which is ' +
+        'the refusal passing while grading nothing',
+    );
+  }
+  const byCoordinate = new Map();
+  for (const edition of editions) {
+    const { distributionId, subjects } = edition;
+    if (typeof distributionId !== 'string' || distributionId.length === 0) {
+      throw new Error(
+        'fleet-coordinate-finality: an edition was supplied with no distributionId',
+      );
+    }
+    if (!Array.isArray(subjects) || subjects.length === 0) {
+      throw new Error(
+        `fleet-coordinate-finality: "${distributionId}" has an image lock declaring no ` +
+          'subjects. An edition that contributes no coordinate is indistinguishable ' +
+          'from one this pass failed to read, so it is refused rather than skipped.',
+      );
+    }
+    for (const subject of subjects) {
+      if (
+        !Array.isArray(subject.requiredPlatforms) ||
+        subject.requiredPlatforms.length === 0
+      ) {
+        throw new Error(
+          `fleet-coordinate-finality: "${distributionId}" subject ${subject.kind}:${subject.id} ` +
+            'declares no requiredPlatforms. It would contribute nothing to the fleet map ' +
+            'and silently weaken the refusal for every edition sharing its coordinate.',
+        );
+      }
+      // A third-party subject is read by its pinned digest, not at `<imageRef>:<contentHash>` (its contentHash is
+      // publisher-attested, not a tag), and no fleet lane supplements it: it contributes no first-party coordinate.
+      if (isThirdPartySubject(subject)) {continue;}
+      const coordinate = coordinateOf(subject);
+      let platforms = byCoordinate.get(coordinate);
+      if (!platforms) {
+        platforms = new Map();
+        byCoordinate.set(coordinate, platforms);
+      }
+      for (const platform of subject.requiredPlatforms) {
+        const identity = platformIdentity(platform);
+        let requirers = platforms.get(identity);
+        if (!requirers) {
+          requirers = new Set();
+          platforms.set(identity, requirers);
+        }
+        requirers.add(distributionId);
+      }
+    }
+  }
+  // Freeze the requirer sets into sorted arrays so a message built from this map
+  // is deterministic, and so a caller cannot mutate the map it was handed.
+  return new Map(
+    [...byCoordinate].map(([coordinate, platforms]) => [
+      coordinate,
+      new Map(
+        [...platforms].map(([identity, requirers]) => [
+          identity,
+          [...requirers].sort(),
+        ]),
+      ),
+    ]),
+  );
+}
+
+/**
+ * Read every edition's image lock under `editionsRoot`, in BOTH tiers.
+ *
+ * A pending-merge edition is a real edition that will ship its coordinates, so
+ * a platform IT requires is just as much a reason a coordinate can still move.
+ * Measured 2026-09-19: the two pending editions carry a declaration and no lock,
+ * so today this widening admits nothing — which is the point at which to add it,
+ * rather than after a pending edition has acquired one.
+ *
+ * TWO ABSENCES THAT ARE NOT THE SAME, and conflating them is how this check
+ * would quietly stop working:
+ *
+ *   * NO LOCK FILE — the edition makes no coordinate claim at all. It
+ *     contributes nothing, legitimately, and is COUNTED and reported so the
+ *     corpus line shows it was seen and skipped.
+ *   * A LOCK THAT CANNOT BE READ — refused. An unreadable lock contributes no
+ *     requirements either, and the difference between "requires nothing" and
+ *     "we failed to find out" is the whole value of the refusal.
+ *
+ * `JSON.parse` rather than the kernel's `parseImageLock` is deliberate. Only
+ * three fields are read — `imageRef`, `contentHash`, `requiredPlatforms` — and
+ * requiring a BUILT KERNEL to grade the OTHER editions would make this refusal
+ * unrunnable in exactly the checkouts that have no kernel to build. The edition
+ * being sealed is still parsed by the kernel on the path that seals it.
+ */
+export function readFleetImageLocks(editionsRoot) {
+  const editions = [];
+  const withoutLock = [];
+  for (const { id, directory } of discoverEditionDirectories(editionsRoot)) {
+    const lockPath = join(directory, IMAGE_LOCK_FILENAME);
+    if (!existsSync(lockPath)) {
+      withoutLock.push(id);
+      continue;
+    }
+    let raw;
+    try {
+      raw = JSON.parse(readFileSync(lockPath, 'utf8'));
+    } catch (error) {
+      throw new Error(
+        `fleet-coordinate-finality: cannot read ${lockPath}: ${error.message}. ` +
+          'Refusing to grade coordinate finality over a fleet this pass could not ' +
+          'fully read — an unreadable lock declares no requirement, which would make ' +
+          'a coordinate look final because it was never asked about.',
+      );
+    }
+    editions.push({ distributionId: id, subjects: raw.subjects });
+  }
+  if (editions.length === 0) {
+    throw new Error(
+      `fleet-coordinate-finality: found no image lock under ${editionsRoot}; an empty ` +
+        'scan is not a result',
+    );
+  }
+  return { editions, withoutLock: withoutLock.sort() };
+}
+
+/**
+ * Refuse to seal a coordinate THIS edition still awaits a platform at; record —
+ * and allow — one only ANOTHER edition still awaits.
+ *
+ * Owner ruling 2026-09-29: finality is TARGET-PLATFORM aware. A coordinate
+ * pending only a platform this edition does not declare is the accepted
+ * residual, returned as `pendingElsewhere` so the caller prints it. A later
+ * supplement for that other edition may move the tag's digest; this edition's
+ * seal keeps pinning the manifest it verified, which still resolves by digest
+ * and still carries every platform this edition requires.
+ *
+ * `verified` is `verifyDistributionPlatforms(...).subjects`, each carrying
+ * `coordinate` and `publishedPlatforms` — the platforms the registry ACTUALLY
+ * serves there, which is strictly wider than the subset this edition required.
+ *
+ * THE SUBJECT SET IS THE WRITES, NOT THE LOCK. This grades the subjects about to
+ * RECEIVE a digest, because that is the moment the regression is introduced. An
+ * already-sealed subject is past it: re-refusing one would make the daily
+ * reconciler permanently red with no action available to clear it, and a gate
+ * that cannot be cleared is one people learn to bypass.
+ *
+ * THIRD-PARTY SUBJECTS ARE EXCLUDED, NAMED. `thirdPartyKeys` (`kind:id`) are the pinned third-party subjects of this
+ * edition: each is read by its pinned manifest digest (an immutable coordinate no fleet lane supplements), so it has no
+ * first-party fleet coordinate to grade. They are returned as `thirdParty` so the caller prints them.
+ *
+ * Throws with `error.notFinal === true` — a PROPERTY, never a message match, so
+ * the reconciler's skip cannot silently widen the day this wording changes. Same
+ * discipline as `error.status` on the not-published-yet path.
+ */
+export function assertCoordinatesFinal({
+  distributionId,
+  writes: plannedWrites,
+  verified,
+  fleetRequirements,
+  thirdPartyKeys = new Set(),
+}) {
+  const graded = [];
+  const pendingElsewhere = [];
+  if (!Array.isArray(plannedWrites)) {
+    return { distributionId, graded, coordinateCount: 0, pendingElsewhere, thirdParty: [] };
+  }
+  const thirdParty = plannedWrites.filter((write) => thirdPartyKeys.has(write.key)).map((write) => write.key);
+  const writes = plannedWrites.filter((write) => !thirdPartyKeys.has(write.key));
+  if (writes.length === 0) {
+    return { distributionId, graded, coordinateCount: 0, pendingElsewhere, thirdParty };
+  }
+  const byKey = new Map(
+    verified.map((entry) => [`${entry.subjectKind}:${entry.subjectId}`, entry]),
+  );
+  const blockers = [];
+  for (const write of writes) {
+    const entry = byKey.get(write.key);
+    if (!entry) {
+      throw new Error(
+        `fleet-coordinate-finality: ${write.key} is planned for sealing but has no ` +
+          'verification result to read published platforms from; refusing to grade ' +
+          'finality for a subject the verifier did not cover',
+      );
+    }
+    const required = fleetRequirements.get(entry.coordinate);
+    if (!required) {
+      // NON-VACUITY GUARD. The edition being sealed is itself one of the
+      // editions read into the map, so every coordinate it seals MUST be in
+      // there. A miss means the two halves are keyed differently and every
+      // lookup would return nothing — a refusal that passes while grading
+      // nothing, which is this tree's most-repeated defect.
+      throw new Error(
+        `fleet-coordinate-finality: coordinate ${entry.coordinate} (${write.key}) is absent ` +
+          'from the fleet requirement map, which cannot happen while the edition being ' +
+          'sealed is itself in that map. The lock-side and verifier-side coordinate ' +
+          'spellings have diverged; refusing rather than passing over a lookup that ' +
+          'silently misses.',
+      );
+    }
+    const served = new Set(entry.publishedPlatforms ?? []);
+    const unmet = [...required]
+      .filter(([identity]) => !served.has(identity))
+      .map(([identity, requirers]) => ({ platform: identity, requiredBy: requirers }));
+    graded.push({ key: write.key, coordinate: entry.coordinate });
+    // TARGET-PLATFORM AWARE (owner ruling 2026-09-29). Finality is graded
+    // against THIS edition's own requiredPlatforms: a platform only ANOTHER
+    // edition awaits here is the accepted residual — allowed, and RECORDED so
+    // the caller can print it. A platform this edition itself declares and the
+    // registry does not serve is still refused.
+    const own = unmet.filter((u) => u.requiredBy.includes(distributionId));
+    const foreign = unmet.filter((u) => !u.requiredBy.includes(distributionId));
+    if (foreign.length > 0) {
+      pendingElsewhere.push({
+        key: write.key,
+        coordinate: entry.coordinate,
+        unmet: foreign,
+        served: [...served].sort(),
+      });
+    }
+    if (own.length > 0) {
+      blockers.push({ key: write.key, coordinate: entry.coordinate, unmet: own, served: [...served].sort() });
+    }
+  }
+  if (blockers.length > 0) {
+    const detail = blockers
+      .slice(0, 6)
+      .map(
+        (b) =>
+          `    ${b.key}  ${b.coordinate}\n` +
+          b.unmet
+            .map(
+              (u) =>
+                `        awaits ${u.platform}, required by ${u.requiredBy.join(', ')} ` +
+                `(serves: ${b.served.join(', ') || 'nothing'})`,
+            )
+            .join('\n'),
+      )
+      .join('\n');
+    const error = new Error(
+      `fleet-coordinate-finality: "${distributionId}" cannot be sealed — ${blockers.length} of ` +
+        `${writes.length} coordinate(s) are NOT FINAL for a platform THIS edition requires: ` +
+        'the registry does not yet serve it there, so the coordinate will be supplemented ' +
+        '— and the arm64 lane supplements by REPUBLISHING the tag (`imagetools create -t ' +
+        ':<contentHash>`), which would move the very digest this seal is about to pin.\n' +
+        `${detail}${blockers.length > 6 ? `\n    ... and ${blockers.length - 6} more` : ''}\n` +
+        'Complete the supplement for this edition\'s own platforms, then seal.',
+    );
+    error.notFinal = true;
+    error.blockers = blockers;
+    throw error;
+  }
+  return { distributionId, graded, coordinateCount: graded.length, pendingElsewhere, thirdParty };
+}
+
+/**
+ * Is this failure "another edition can still supplement this coordinate"?
+ *
+ * A PROPERTY, never a message match — see {@link assertCoordinatesFinal}.
+ */
+export function isNotFinalYet(error) {
+  return Boolean(error) && error.notFinal === true;
+}

package/edition/fulcio-certificate-extensions.mjs

@@ -0,0 +1,278 @@
+// The Fulcio v2 certificate extensions cosign has no verification flag for, read from the
+// leaf certificate of a sigstore bundle with a small DER walker (Node's X509Certificate does
+// not expose arbitrary extensions).
+//
+//   1.3.6.1.4.1.57264.1.9   Build Signer URI (the workflow whose job ran: GitHub's job_workflow_ref)
+//   1.3.6.1.4.1.57264.1.11  Runner Environment
+//   1.3.6.1.4.1.57264.1.15  Source Repository Identifier
+//   1.3.6.1.4.1.57264.1.17  Source Repository Owner Identifier
+//   1.3.6.1.4.1.57264.1.18  Build Config URI (the top-level workflow of the run: GitHub's workflow_ref)
+//
+// The three source/runner extensions are always read; the two build URIs only when asked for
+// (`readFulcioBuildIdentity`), so a reader of the three needs nothing more of a certificate.
+//
+// Each is the v2 form: the extension's OCTET STRING contains a DER UTF8String. The legacy raw
+// forms (.1 to .6, which put the bare bytes in the OCTET STRING) are never read. An absent
+// extension, a repeated one or one that is not a UTF8String is refused naming its OID.
+//
+// The certificate is the one cosign verified: the bytes come from the bundle that was verified
+// (`verificationMaterial.certificate.rawBytes`, else the first
+// `verificationMaterial.x509CertificateChain.certificates[].rawBytes`), never from a second fetch.
+
+const TAG_SEQUENCE = 0x30;
+const TAG_OID = 0x06;
+const TAG_BOOLEAN = 0x01;
+const TAG_OCTET_STRING = 0x04;
+const TAG_UTF8_STRING = 0x0c;
+const TAG_CONTEXT_0 = 0xa0;
+const TAG_CONTEXT_1 = 0xa1;
+const TAG_CONTEXT_2 = 0xa2;
+const TAG_CONTEXT_3 = 0xa3;
+
+export const FulcioExtensionOid = Object.freeze({
+  RunnerEnvironment: '1.3.6.1.4.1.57264.1.11',
+  SourceRepositoryIdentifier: '1.3.6.1.4.1.57264.1.15',
+  SourceRepositoryOwnerIdentifier: '1.3.6.1.4.1.57264.1.17',
+});
+
+/** The Fulcio build identity extensions, read only by `readFulcioBuildIdentity`. */
+export const FulcioBuildOid = Object.freeze({
+  BuildSignerUri: '1.3.6.1.4.1.57264.1.9',
+  BuildConfigUri: '1.3.6.1.4.1.57264.1.18',
+});
+
+/** The Runner Environment (.11) values Fulcio issues for GitHub Actions: the closed domain of a runner declaration. */
+export const RunnerEnvironment = Object.freeze({
+  GithubHosted: 'github-hosted',
+  SelfHosted: 'self-hosted',
+});
+
+/**
+ * THE ONE parser of a declared runner environment (the pin's `runnerEnvironment`, the writer's and the publisher's
+ * `--runner-environment`). Absent (`undefined`) is the default and returns `undefined`; the only value a declaration
+ * may state is `self-hosted`, so the default has no second spelling. Anything else throws naming `what`.
+ *
+ * @returns {'self-hosted'|undefined}
+ */
+export function parseDeclaredRunnerEnvironment(value, what) {
+  if (value === undefined || value === RunnerEnvironment.SelfHosted) {
+    return value;
+  }
+  throw new Error(
+    `${what} must be "${RunnerEnvironment.SelfHosted}" when present (absent means ${RunnerEnvironment.GithubHosted}); got ${JSON.stringify(value)}`,
+  );
+}
+
+const OID_FIELDS = Object.freeze([
+  ['runnerEnvironment', FulcioExtensionOid.RunnerEnvironment],
+  ['sourceRepositoryIdentifier', FulcioExtensionOid.SourceRepositoryIdentifier],
+  ['sourceRepositoryOwnerIdentifier', FulcioExtensionOid.SourceRepositoryOwnerIdentifier],
+]);
+const BUILD_OID_FIELDS = Object.freeze([
+  ['buildSignerUri', FulcioBuildOid.BuildSignerUri],
+  ['buildConfigUri', FulcioBuildOid.BuildConfigUri],
+]);
+
+/** One DER element at `offset`: its tag, content bounds and the offset after it. Indefinite lengths are refused (DER). */
+function readElement(bytes, offset, end, what) {
+  if (offset + 2 > end) {
+    throw new Error(`certificate DER is truncated at ${what}`);
+  }
+  const tag = bytes[offset];
+  if ((tag & 0x1f) === 0x1f) {
+    throw new Error(`certificate DER has a multi-byte tag at ${what}`);
+  }
+  let length = bytes[offset + 1];
+  let contentStart = offset + 2;
+  if (length === 0x80) {
+    throw new Error(`certificate DER has an indefinite length at ${what}`);
+  }
+  if (length > 0x80) {
+    const count = length & 0x7f;
+    if (count > 4 || contentStart + count > end) {
+      throw new Error(`certificate DER has an invalid length at ${what}`);
+    }
+    length = 0;
+    for (let index = 0; index < count; index += 1) {
+      length = length * 256 + bytes[contentStart + index];
+    }
+    contentStart += count;
+  }
+  const contentEnd = contentStart + length;
+  if (contentEnd > end) {
+    throw new Error(`certificate DER overruns its container at ${what}`);
+  }
+  return { tag, contentStart, contentEnd };
+}
+
+function expectElement(bytes, offset, end, tag, what) {
+  const element = readElement(bytes, offset, end, what);
+  if (element.tag !== tag) {
+    throw new Error(`certificate DER: ${what} has tag 0x${element.tag.toString(16)}, expected 0x${tag.toString(16)}`);
+  }
+  return element;
+}
+
+function decodeOid(bytes, start, end) {
+  if (end <= start) {
+    throw new Error('certificate DER has an empty OBJECT IDENTIFIER');
+  }
+  const arcs = [];
+  let value = 0;
+  for (let index = start; index < end; index += 1) {
+    value = value * 128 + (bytes[index] & 0x7f);
+    if ((bytes[index] & 0x80) === 0) {
+      if (arcs.length === 0) {
+        const first = Math.min(Math.floor(value / 40), 2);
+        arcs.push(first, value - first * 40);
+      } else {
+        arcs.push(value);
+      }
+      value = 0;
+    }
+  }
+  return arcs.join('.');
+}
+
+/** The extensions of the certificate: `Map<oid, {critical, value: Buffer}>` where `value` is the OCTET STRING content. */
+function certificateExtensions(der) {
+  const certificate = expectElement(der, 0, der.length, TAG_SEQUENCE, 'Certificate');
+  if (certificate.contentEnd !== der.length) {
+    throw new Error('certificate DER has trailing bytes after the Certificate');
+  }
+  const tbs = expectElement(der, certificate.contentStart, certificate.contentEnd, TAG_SEQUENCE, 'TBSCertificate');
+  let offset = tbs.contentStart;
+  let element = readElement(der, offset, tbs.contentEnd, 'TBSCertificate field');
+  if (element.tag === TAG_CONTEXT_0) {
+    offset = element.contentEnd;
+  }
+  // serialNumber, signature, issuer, validity, subject, subjectPublicKeyInfo
+  for (let field = 0; field < 6; field += 1) {
+    element = readElement(der, offset, tbs.contentEnd, 'TBSCertificate field');
+    offset = element.contentEnd;
+  }
+  let extensionsBlock = null;
+  while (offset < tbs.contentEnd) {
+    element = readElement(der, offset, tbs.contentEnd, 'TBSCertificate trailing field');
+    offset = element.contentEnd;
+    if (element.tag === TAG_CONTEXT_3) {
+      extensionsBlock = element;
+    } else if (element.tag !== TAG_CONTEXT_1 && element.tag !== TAG_CONTEXT_2) {
+      throw new Error(`certificate DER: unexpected TBSCertificate field tag 0x${element.tag.toString(16)}`);
+    }
+  }
+  if (extensionsBlock === null) {
+    throw new Error('certificate has no extensions block');
+  }
+  const list = expectElement(der, extensionsBlock.contentStart, extensionsBlock.contentEnd, TAG_SEQUENCE, 'Extensions');
+  const found = new Map();
+  let cursor = list.contentStart;
+  while (cursor < list.contentEnd) {
+    const extension = expectElement(der, cursor, list.contentEnd, TAG_SEQUENCE, 'Extension');
+    cursor = extension.contentEnd;
+    const oidElement = expectElement(der, extension.contentStart, extension.contentEnd, TAG_OID, 'Extension OID');
+    const oid = decodeOid(der, oidElement.contentStart, oidElement.contentEnd);
+    let next = oidElement.contentEnd;
+    let critical = false;
+    let part = readElement(der, next, extension.contentEnd, 'Extension field');
+    if (part.tag === TAG_BOOLEAN) {
+      critical = der[part.contentStart] !== 0;
+      next = part.contentEnd;
+      part = readElement(der, next, extension.contentEnd, 'Extension value');
+    }
+    if (part.tag !== TAG_OCTET_STRING || part.contentEnd !== extension.contentEnd) {
+      throw new Error(`certificate DER: extension ${oid} value is not a lone OCTET STRING`);
+    }
+    if (found.has(oid)) {
+      throw new Error(`certificate carries extension ${oid} more than once`);
+    }
+    found.set(oid, { critical, value: der.subarray(part.contentStart, part.contentEnd) });
+  }
+  return found;
+}
+
+/** The extension's string: the OCTET STRING content must be exactly one DER UTF8String. */
+function utf8ExtensionValue(extensions, oid) {
+  const extension = extensions.get(oid);
+  if (extension === undefined) {
+    throw new Error(`certificate does not carry Fulcio extension ${oid}`);
+  }
+  const { value } = extension;
+  let element;
+  try {
+    element = readElement(value, 0, value.length, `extension ${oid}`);
+  } catch (error) {
+    throw new Error(`Fulcio extension ${oid} is not a DER UTF8String: ${error.message}`);
+  }
+  if (element.tag !== TAG_UTF8_STRING || element.contentEnd !== value.length) {
+    throw new Error(`Fulcio extension ${oid} is not a DER UTF8String`);
+  }
+  const text = value.subarray(element.contentStart, element.contentEnd);
+  if (text.length === 0) {
+    throw new Error(`Fulcio extension ${oid} is an empty UTF8String`);
+  }
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(text);
+  } catch {
+    throw new Error(`Fulcio extension ${oid} is not valid UTF-8`);
+  }
+}
+
+function decodeBase64Der(rawBytes, what) {
+  if (typeof rawBytes !== 'string' || rawBytes.length === 0) {
+    throw new Error(`${what} has no rawBytes`);
+  }
+  return Buffer.from(rawBytes, 'base64');
+}
+
+/**
+ * The DER bytes of the leaf certificate of a parsed sigstore bundle:
+ * `verificationMaterial.certificate.rawBytes`, else the first
+ * `verificationMaterial.x509CertificateChain.certificates[].rawBytes`.
+ */
+export function leafCertificateDerFromBundle(bundle) {
+  const material = bundle?.verificationMaterial;
+  if (material === null || typeof material !== 'object') {
+    throw new Error('sigstore bundle has no verificationMaterial');
+  }
+  if (material.certificate !== undefined) {
+    return decodeBase64Der(material.certificate?.rawBytes, 'verificationMaterial.certificate');
+  }
+  const first = material.x509CertificateChain?.certificates?.[0];
+  if (first === undefined) {
+    throw new Error('sigstore bundle verificationMaterial carries no certificate and no x509CertificateChain');
+  }
+  return decodeBase64Der(first.rawBytes, 'verificationMaterial.x509CertificateChain.certificates[0]');
+}
+
+/** The named UTF8String extensions of a DER certificate, each required. */
+const readFields = (der, fields) => {
+  const extensions = certificateExtensions(der);
+  return Object.freeze(Object.fromEntries(fields.map(([field, oid]) => [field, utf8ExtensionValue(extensions, oid)])));
+};
+
+/**
+ * The runner environment, source repository identifier and source repository owner identifier of a
+ * DER certificate. Throws naming the OID when one is missing or is not a UTF8String.
+ *
+ * @param {Buffer} der
+ * @returns {{runnerEnvironment: string, sourceRepositoryIdentifier: string, sourceRepositoryOwnerIdentifier: string}}
+ */
+export function readFulcioCertificateExtensions(der) {
+  return readFields(der, OID_FIELDS);
+}
+
+/**
+ * The Build Signer URI and Build Config URI of the leaf certificate of a parsed sigstore bundle. Throws naming the OID
+ * when one is missing or is not a UTF8String.
+ *
+ * @returns {{buildSignerUri: string, buildConfigUri: string}}
+ */
+export function readFulcioBuildIdentity(bundle) {
+  return readFields(leafCertificateDerFromBundle(bundle), BUILD_OID_FIELDS);
+}
+
+/** The three extensions of the leaf certificate of a parsed sigstore bundle (the bytes cosign verified). */
+export function readFulcioExtensionsFromBundle(bundle) {
+  return readFulcioCertificateExtensions(leafCertificateDerFromBundle(bundle));
+}