@xemahq/biome-supply-chain

This package belongs to Layer 1 — a framework-free runtime SDK utility.

Shared cosign supply-chain verification for Xema biomes. It centralizes the two things that were previously copy-pasted between biome-fetcher-api (OCI bundle verification) and xema-store-api:

• the single cosign CLI invocation (ensureCosignAvailable, verifyCosignSignature, verifyCosignAttestation, verifyCosignBlob), and
• the signature / provenance verdict vocabulary (SignatureVerdict, ProvenanceVerdict, CosignErrorCode, CosignVerifyOutcome).

It shells out to the cosign binary and uses only Node built-ins — no NestJS, no framework, no external runtime dependencies — so it is safe to import from a service runtime image and from a build-time CLI alike.

Usage

import {
  ensureCosignAvailable,
  verifyCosignSignature,
  verifyCosignBlob,
  CosignTrustAnchorKind,
  SignatureVerdict,
  CosignVerifyOutcome,
} from '@xemahq/biome-supply-chain';

await ensureCosignAvailable();

// OCI ref (keyless identity allowlist)
await verifyCosignSignature({
  ociRef: 'oci://registry/biome:1.2.0',
  trustedIdentities: ['https://github.com/xema-dev/...'],
  oidcIssuer: 'https://token.actions.githubusercontent.com',
});

// Detached blob (caller owns artifact/bundle/public-key files on disk).
// A trust anchor is EITHER a keyless certificate-identity pattern OR a NAMED
// public key; both kinds share one list and one result shape, and the anchors
// are tried in order until one verifies.
const { outcome, matchedAnchor } = await verifyCosignBlob({
  artifactPath: '/tmp/remoteEntry.js',
  bundlePath: '/tmp/remoteEntry.js.bundle',
  anchors: [
    {
      kind: CosignTrustAnchorKind.KeylessIdentity,
      name: '^https://github.com/xema-dev/.*$', // the name IS the regexp
    },
    {
      kind: CosignTrustAnchorKind.PublicKey,
      name: 'release-2026',
      publicKeyPath: '/etc/cosign/release.pub',
    },
  ],
  // Optional: pin the Sigstore trusted root so KEYLESS anchors verify with
  // `--offline --trusted-root` (air-gap capable). A missing, unreadable or
  // digest-mismatched root THROWS `CosignTrustedRootError` before cosign is
  // spawned — it never falls back to cosign's online default.
  trustedRoot: { path: '/etc/sigstore/trusted-root.json', sha256: '<64 hex>' },
});
if (outcome === CosignVerifyOutcome.Verified) {
  // matchedAnchor is { kind, name } — WHICH anchor vouched for the bytes
}

An empty anchors list resolves to Failed without spawning cosign, and a failed verification is a neutral outcome rather than a throw.

Artifact resolution (resolving an OCI ref, or fetching + writing a blob to a temp file) stays with each consumer; this package owns only the cosign exec, the trust-anchor vocabulary and the verdict enums.

License

Business Source License 1.1 (BSL-1.1) — source-available; converts to MPL-2.0 four years after each release. © Xema — xema.dev. See the repository LICENSE.