Sigstore

Zero-dependency verifier for a Sigstore bundle -- the exact artifact npm publish --provenance produces and the npm registry serves at its attestations API. A bundle is a keyless (Fulcio) signature over a DSSE-wrapped in-toto SLSA provenance attestation, with a Rekor transparency-log inclusion proof. verifyBundle composes five fail-closed legs against caller-supplied trust material (the Fulcio CA roots + Rekor log keys, never trusted from the bundle): the DSSE signature over its PAE preimage under the Fulcio leaf key; the Fulcio certificate chain, validated as of the Rekor log time (the cert is ephemeral, ~10 minutes); the Rekor inclusion proof folded to a Rekor-signed tree root; the log entry binding to this exact signature; and the in-toto subject digest the caller confirms against the published artifact. Verify-only and offline -- every input is in the bundle or a caller argument. Reuses the shipped X.509 parser, RFC 5280 path validator, RFC 9162 Merkle verifier, and native crypto engine; the net-new codecs are the DSSE PAE byte-builder and a fail-closed JSON bundle reader.

pki.sigstore.pae

since 0.2.3 experimental
pki.sigstore.pae(payloadType, payloadBytes) -> Buffer

The DSSE Pre-Authentication Encoding: "DSSEv1" SP LEN(type) SP type SP LEN(body) SP body, where LEN is the ASCII-decimal byte length (no leading zeros) and type is the UTF-8 payloadType. This is the exact preimage a DSSE signature covers; LEN is over the decoded body byte length, never the base64 length -- any deviation is a signature-verify bypass.

Example

var b = pki.sigstore.pae("application/vnd.in-toto+json", Buffer.from("{}"));
b.slice(0, 6).toString(); // "DSSEv1"

See also: pki.sigstore.verifyBundle

References

  • spec DSSE

pki.sigstore.parseBundle

since 0.2.3 experimental
pki.sigstore.parseBundle(input) -> bundle

Decode + structurally validate a Sigstore bundle (a JSON object, string, or Buffer) fail-closed: a non-object, malformed JSON, an oversize input, an unknown mediaType, or a missing required member throws a typed sigstore/bad-bundle / sigstore/bad-bundle-version. Returns the validated bundle object (structure only -- no cryptographic verification).

Example

var b = pki.sigstore.parseBundle(bundle);
b.mediaType; // "application/vnd.dev.sigstore.bundle.v0.3+json"

See also: pki.sigstore.verifyBundle

References

  • spec Sigstore bundle v0.3

pki.sigstore.verifyBundle

since 0.2.3 experimental
pki.sigstore.verifyBundle(bundle, opts) -> Promise<result>

Verify a Sigstore bundle (an npm --provenance artifact) offline against caller-supplied trust material, composing five fail-closed legs: the DSSE signature over its PAE under the Fulcio leaf key; the Fulcio chain validated as of the Rekor log time; the Rekor inclusion proof folded to a Rekor-signed root; the log entry bound to this exact signature; and the in-toto SLSA statement. Any leg failing throws a typed sigstore/* error. On success returns { verified: true, payload, statement, subjects, predicateType, predicate, identity, integratedTime } -- payload is the RAW verified envelope bytes (never a re-serialization), and the caller confirms a subjects[].digest matches the published artifact.

Options

fulcioRoots:   Array,      // the Fulcio CA anchors: a DER Buffer or { der, validFor } each
rekorKeys:     Array,      // [{ keyId, spki, validFor? }] the Rekor log public keys
identity:      object,     // optional policy: { san, issuer, sourceRepositoryURI }
predicateType: string,     // optional: require this in-toto predicateType (e.g. the SLSA URI)
time:          Date,       // optional check-date override (default: the Rekor integratedTime)

Example

async function example() {
  var out = await pki.sigstore.verifyBundle(bundle, sigstoreTrust);
  out.verified;            // true
  out.subjects[0].digest;  // { sha512: "..." } -- confirm against your tarball
}
example();

See also: pki.sigstore.parseBundle, pki.sigstore.pae

References

  • spec DSSE
  • spec Sigstore bundle v0.3
  • spec RFC 9162
  • spec SLSA provenance v1