@blamejs/pki 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -4,7 +4,25 @@ All notable changes to `@blamejs/pki` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## v0.2.1 — 2026-07-12
+## v0.2.3 — 2026-07-12
+
+Offline Sigstore bundle verification joins the toolkit as pki.sigstore.
+
+### Added
+
+- pki.sigstore.verifyBundle(bundle, opts) verifies a Sigstore bundle offline against caller-supplied trust material (opts.fulcioRoots, the Fulcio CA certificates; opts.rekorKeys, the Rekor log public keys, each with an optional validFor window honored against the log time so a rotated-out key is not used; optional opts.identity policy and opts.time). It returns { verified: true, payload, statement, subjects, predicateType, predicate, identity, integratedTime } on success -- payload being the raw verified envelope bytes, never a re-serialization -- and throws a typed sigstore/* error on any leg's failure. The transparency-log entry is bound to both the bundle signature and its leaf certificate, and only the v0.1-v0.3 bundle versions this release verifies are accepted (a newer version is recognized and deferred). pki.sigstore.parseBundle(input) decodes and structurally validates a bundle (object, JSON string, or Buffer) fail-closed. pki.sigstore.pae(payloadType, payloadBytes) builds the DSSE Pre-Authentication Encoding a signature covers. DSSE / Sigstore bundle v0.3 / RFC 9162 / SLSA provenance v1.
+- The OID registry gains the Fulcio (Sigstore) certificate-extension arc 1.3.6.1.4.1.57264.1.* (the OIDC issuer, build-signer and source-repository identity claims), honoring the raw-string-vs-DER-UTF8String encoding split by member. The error taxonomy gains SigstoreError (sigstore/*): a malformed or oversize bundle (sigstore/bad-bundle), an unknown media type (sigstore/bad-bundle-version), an unsupported content arm (sigstore/unsupported-content), a DSSE signature that does not verify under the Fulcio leaf key (sigstore/dsse-verify-failed), an inclusion proof that does not reconstruct the tree root (sigstore/inclusion-proof-mismatch) or is malformed (sigstore/bad-inclusion-proof), a tree root not attested by the Rekor key (sigstore/unsigned-root), a log time not attested by the Rekor SET that signs it (sigstore/unattested-time, so an attacker cannot backdate the ephemeral Fulcio certificate into validity), a Fulcio chain that does not terminate at a caller-supplied trust anchor (sigstore/chain-incomplete) or fails validation as of the log time (sigstore/chain-invalid), an undecodable certificate identity (sigstore/bad-certificate), a malformed transparency-log entry (sigstore/bad-tlog-entry), a log entry that does not bind this signature (sigstore/entry-mismatch), an identity that fails the caller policy (sigstore/identity-mismatch), a payload that is not the expected in-toto statement (sigstore/bad-statement), and a predicateType that does not match a caller-pinned one (sigstore/predicate-mismatch). Fulcio CA anchors and Rekor keys honor their trusted-root validity windows so a rotated-out key or CA is not used, and every anchor sharing a subject DN is tried.
+
+## v0.2.2 — 2026-07-11
+
+Hybrid Public Key Encryption (RFC 9180) joins the toolkit as pki.hpke.
+
+### Added
+
+- pki.hpke.setupS(suiteIds, recipientPublicKey, opts) / pki.hpke.setupR(suiteIds, enc, recipientPrivateKey, opts) establish a sender / recipient HPKE context (RFC 9180 sec. 5.1); the returned context exposes seal(aad, pt) / open(aad, ct) with the sequence-counter nonce and a message-limit guard, and export(exporterContext, L) for the secret-export interface. pki.hpke.seal / pki.hpke.open are the single-shot wrappers (sec. 6). pki.hpke.suites carries the RFC 9180 sec. 7 KEM / KDF / AEAD / MODE code points. Keys are node KeyObjects or serialized bytes; the offered suites are DHKEM P-256, P-521, X25519, and X448, HKDF-SHA256 / HKDF-SHA512, the three AEADs plus export-only, and all four modes. RFC 9180.
+- The error taxonomy gains HpkeError (hpke/*): a malformed, low-order, or otherwise invalid encapsulated or KEM key (hpke/bad-key, so a Diffie-Hellman that fails during derivation surfaces as a typed error, never a raw fault), an unknown or unsupported ciphersuite code point (hpke/unknown-suite, never a silent default), an unsupported mode (hpke/unknown-mode, so an out-of-registry mode is rejected rather than key-scheduled), an authenticated mode invoked without the sender's key (hpke/auth-key-required), inconsistent PSK inputs (hpke/inconsistent-psk), an AEAD tag that does not verify (hpke/open-failed, returning no plaintext), a sequence-number overflow (hpke/message-limit, before any nonce reuse), a seal/open against an export-only suite (hpke/export-only), and a wrong-direction context call (hpke/wrong-role, so a recipient context cannot seal nor a sender context open -- they share a key and base nonce).
+
+## v0.2.1 — 2026-07-11
 
 Stateful hash-based signature verification (HSS/LMS) joins the toolkit as pki.shbs.
 

package/README.md

@@ -225,6 +225,8 @@ is callable today; nothing below is a stub.
 | `pki.merkle` | RFC 6962 / RFC 9162 Merkle-tree proof verification — `leafHash` / `nodeHash` / `emptyRootHash` build the domain-separated (0x00 leaf / 0x01 node) SHA-256 tree hashes; `verifyInclusion` folds an audit proof back to a root and `verifyConsistency` reconstructs both the old and new root (the append-only guarantee), each constant-time-compared to a trusted checkpoint root. Fail-closed on bad geometry, sync hashing, transport-free — `leafHash`, `nodeHash`, `emptyRootHash`, `verifyInclusion`, `verifyConsistency` |
 | `pki.trust` | Mozilla / CCADB trust-store ingestion — `parseCertdata` reads the NSS `certdata.txt` object stream and `parseCcadbCsv` the CCADB CSV export into one identical constraint-carrying anchor shape: the per-purpose trust bits (only `CKT_NSS_TRUSTED_DELEGATOR` grants) and the per-purpose distrust-after dates the bare root list omits. Certificate and trust objects pair by byte-exact issuer + serial (never adjacency) and are cross-checked against the parsed DER, so metadata can never attach to the wrong root; `anchor()` hands an entry to `pki.path.validate({ trustAnchor, checkPurpose })`. Offline, fail-closed, bounded — `parseCertdata`, `parseCcadbCsv`, `anchor` |
 | `pki.shbs` | Stateful hash-based signature **verification** — HSS/LMS (RFC 8554), carried in X.509 by RFC 9802 and CMS by RFC 9708, profiled by NIST SP 800-208 (CNSA 2.0 firmware signing). `verify` checks an HSS signature (every level must pass) and `verifyLms` a single-tree LMS, over the raw public-key / signature blobs the parsers already surface. Pure public-input SHA-256 / SHAKE256 hashing, a data-driven typecode registry, bounds-before-slice reads; a malformed blob throws a typed `ShbsError`, a well-formed-but-wrong signature returns `false`. **Verify only by design** — stateful signing needs atomic one-time-key state that belongs in an HSM — `verify`, `verifyLms` |
+| `pki.hpke` | Hybrid Public Key Encryption (RFC 9180) — the encrypt-to-a-public-key primitive behind TLS ECH, MLS, and OHTTP. `setupS`/`setupR` establish a sender/recipient context (KEM encapsulation + HKDF key schedule); the context's `seal`/`open` AEAD-encrypt with a sequence-counter nonce and `export` derives further secrets; `seal`/`open` are single-shot wrappers. DHKEM (P-256, P-521, X25519, X448) × HKDF-SHA256/SHA512 × AES-GCM/ChaCha20Poly1305/export-only × all four modes, proven against the RFC 9180 Appendix A vectors. DHKEM(P-384) and HKDF-SHA384 are RFC-registered but Appendix A ships no vector for them, so they fail closed until an authoritative KAT exists. Pure composition over `node:crypto`; ML-KEM / X-Wing are a registry data-row extension pending stable drafts — `suites`, `setupS`, `setupR`, `seal`, `open` |
+| `pki.sigstore` | Offline verifier for a Sigstore bundle — the exact artifact `npm publish --provenance` produces and the registry serves. `verifyBundle` composes five fail-closed legs against caller-pinned trust (Fulcio CA roots + Rekor log keys, never trusted from the bundle): the DSSE signature over its PAE preimage under the Fulcio leaf key; the ephemeral Fulcio certificate chain, validated as of the Rekor log time; the RFC 9162 inclusion proof folded to a Rekor-signed tree root; the log entry bound to this exact signature; and the in-toto SLSA subject digest the caller confirms against the published artifact. Zero runtime deps — reuses the X.509 parser, RFC 5280 path validator, and Merkle verifier; the net-new codecs are the DSSE PAE byte-builder and a fail-closed JSON reader. `pae`, `parseBundle`, `verifyBundle` |
 | `pki.C` / `pki.constants` | Version-stable constants — functional scale helpers (`C.TIME.*`, `C.BYTES.*`), codec `LIMITS`, `version` |
 | `pki.errors` | The `PkiError` taxonomy — `defineClass` plus `ConstantsError` / `Asn1Error` / `OidError` / `PemError` / `CertificateError` / `CrlError` / `CsrError` / `Pkcs8Error` / `CmsError` / `OcspError` / `TspError` / `AttrCertError` / `CrmfError` / `Pkcs12Error` / `CmpError` / `PathError` / `CtError` / `JoseError` / `AcmeError`, each carrying a stable `code` in `domain/reason` form |
 | `pki` CLI | `pki version`, `pki oid <dotted\|name>`, `pki parse <cert>` |
@@ -260,34 +262,42 @@ reintroduce the bug class it prevents. Adding a format is a schema declaration
 plus a documentation comment block, not new parse logic.
 
 ```
-┌─ Detect + route ────────────────────────────────────────────────────────┐
-│  pki.schema.parse — inspect the DER root, route to the matching sibling │
-└─────────────────────────────────────────────────────────────────────────┘
+┌─ Detect + route ─────────────────────────────────────────────────────────┐
+│ pki.schema.parse — inspect the DER root, route to the matching sibling   │
+└──────────────────────────────────────────────────────────────────────────┘
                                      │
- ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐   Format
- │  x509  │ │  crl   │ │  csr   │ │ pkcs8  │   parsers
- └────────┘ └────────┘ └────────┘ └────────┘   (siblings)
  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
- │  cms   │ │  ocsp  │ │  tsp   │ │attrcert│
+ │  x509  │ │  crl   │ │  csr   │ │ pkcs8  │
  └────────┘ └────────┘ └────────┘ └────────┘
-                                     │  every sibling composes ↓
-┌─ Shared structure ──────────────────────────────────────────────────────┐
-│  pki.schema.engine — walk + combinators (positional reads, tag order,   │
-│  SET-OF uniqueness, arity, typed errors) · the PKIX sub-schemas —       │
-│  AlgorithmIdentifier · Name · Extension · a bounded version reader —    │
-│  and the one coerce → decode → walk parse-entry (PEM cap + DER wrap).   │
-└─────────────────────────────────────────────────────────────────────────┘
+ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
+ │  cms   │ │  ocsp  │ │  tsp   │ │  crmf  │
+ └────────┘ └────────┘ └────────┘ └────────┘
+ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
+ │ pkcs12 │ │  cmp   │ │ smime  │ │attrcert│
+ └────────┘ └────────┘ └────────┘ └────────┘
+                                     │  routed DER format parsers (siblings)
+┌─ Protocols · trust · supply chain  (reached by explicit call) ───────────┐
+│ pki.path RFC 5280 · pki.trust anchors · pki.ct SCTs · pki.hpke RFC 9180  │
+│ pki.shbs HSS/LMS · pki.merkle RFC 9162 · pki.sigstore npm provenance     │
+│ pki.jose · pki.acme · pki.est — compose the layers below directly.       │
+└──────────────────────────────────────────────────────────────────────────┘
+                                     │  every module composes ↓
+┌─ Shared structure ───────────────────────────────────────────────────────┐
+│ pki.schema.engine — walk + combinators (positional reads, tag order,     │
+│ SET-OF uniqueness, typed errors) · the PKIX sub-schemas · and the        │
+│ guard family (guard-*) — one fail-closed choke point per CVE class.      │
+└──────────────────────────────────────────────────────────────────────────┘
                                      │  built on ↓
-┌─ Foundation ────────────────────────────────────────────────────────────┐
-│  pki.asn1 — strict, bounded DER codec · pki.oid — two-way, PQC-seeded   │
-│  OID registry · pki.errors — the PkiError domain/reason taxonomy ·      │
-│  pki.C — version-stable LIMITS + scale constants.                       │
-└─────────────────────────────────────────────────────────────────────────┘
-
-┌─ Crypto ────────────────────────────────────────────────────────────────┐
-│  pki.webcrypto ──▶ node:crypto — a W3C SubtleCrypto engine: the         │
-│  classical set + post-quantum ML-DSA / SLH-DSA + ML-KEM key generation. │
-└─────────────────────────────────────────────────────────────────────────┘
+┌─ Foundation ─────────────────────────────────────────────────────────────┐
+│ pki.asn1 — strict bounded DER codec · pki.cbor — deterministic CBOR ·    │
+│ pki.oid — two-way PQC-seeded registry · pki.errors — PkiError taxonomy   │
+│ · pki.C — version-stable LIMITS + scale constants.                       │
+└──────────────────────────────────────────────────────────────────────────┘
+
+┌─ Crypto ─────────────────────────────────────────────────────────────────┐
+│ pki.webcrypto ─▶ node:crypto — a W3C SubtleCrypto engine: the            │
+│ classical set + post-quantum ML-DSA / SLH-DSA + ML-KEM key generation.   │
+└──────────────────────────────────────────────────────────────────────────┘
 ```
 
 **Foundation.** The strict, bounded DER codec (`pki.asn1`), the two-way OID
@@ -301,12 +311,24 @@ bounded version reader, and the single coerce → decode → walk parse-entry th
 every format's `parse` is bound to. Because input coercion, the PEM size cap, and
 the DER-decode wrapping live here once, a format cannot diverge on a guard.
 
-**Format parsers.** `x509`, `crl`, `csr`, `pkcs8`, `cms`, `ocsp`, `tsp`, and `attrcert` are siblings:
-each is a schema declaration composed from the shared pieces, emitting its own
-typed `domain/reason` error codes. `pki.schema.parse` inspects a decoded root and
+**Format parsers.** `x509`, `crl`, `csr`, `pkcs8`, `cms`, `ocsp`, `tsp`, `attrcert`,
+`crmf`, `pkcs12`, `cmp`, `smime`, and `csrattrs` are siblings: each is a schema
+declaration composed from the shared pieces, emitting its own typed
+`domain/reason` error codes. `pki.schema.parse` inspects a decoded root and
 detect-and-routes to the matching sibling; the detectors are mutually exclusive by
 construction, so routing is unambiguous regardless of registration order.
 
+**Protocols, trust, and supply chain.** Above the format parsers sit the domain
+modules reached by explicit call rather than DER routing: `pki.path` (RFC 5280
+path validation), `pki.trust` (trust anchors), `pki.ct` (Certificate Transparency
+SCTs), `pki.hpke` (RFC 9180), `pki.shbs` (HSS/LMS stateful hash signatures),
+`pki.merkle` (RFC 9162 transparency proofs), `pki.sigstore` (offline npm-provenance
+verification), and the `jose` / `acme` / `est` enrollment surfaces. Each composes
+the shared structure, foundation, and crypto layers directly. Alongside the schema
+engine, the fail-closed **guard family** (`guard-*`) centralizes each CVE-class
+defense — detached-buffer re-view, resource caps, constant-time compares,
+canonical-DN comparison — as one choke point a format cannot re-inline.
+
 **Crypto.** `pki.webcrypto` is a W3C `SubtleCrypto` engine over `node:crypto`,
 carrying the classical suite plus post-quantum ML-DSA / SLH-DSA signatures and
 ML-KEM key generation. Sign/verify resolves algorithms through the same OID

package/index.js

@@ -38,6 +38,8 @@ var path      = require("./lib/path-validate");
 var ct        = require("./lib/ct");
 var merkle    = require("./lib/merkle");
 var shbs      = require("./lib/shbs");
+var hpke      = require("./lib/hpke");
+var sigstore  = require("./lib/sigstore");
 var est        = require("./lib/est");
 var jose       = require("./lib/jose");
 var acme       = require("./lib/acme");
@@ -79,6 +81,14 @@ module.exports = {
   // VERIFY ONLY by design: stateful signing requires atomic one-time-key index
   // state that belongs in an HSM, so this module never mints a signature.
   shbs:      shbs,
+  // `hpke` is RFC 9180 Hybrid Public Key Encryption -- the KEM + HKDF key
+  // schedule + AEAD context construction behind TLS ECH / MLS / OHTTP. Pure
+  // composition over node:crypto; the classical DHKEM suites, all four modes.
+  hpke:      hpke,
+  // `sigstore` verifies a Sigstore bundle (the npm --provenance artifact): a
+  // keyless Fulcio signature over a DSSE-wrapped in-toto SLSA attestation with a
+  // Rekor inclusion proof -- offline, zero-dep, against caller-pinned trust.
+  sigstore:  sigstore,
   // `est` is RFC 7030 / 8951 / 9908 Enrollment over Secure Transport -- the
   // transport-agnostic client codecs (base64 transfer, multipart splitter),
   // certs-only + serverkeygen validators over CMS, the enroll-attribute builders,

package/lib/framework-error.js

@@ -282,6 +282,17 @@ var AcmeError = defineClass("AcmeError", { withCause: true });
 // asn1/* error) as `.cause`.
 var TrustError = defineClass("TrustError", { withCause: true });
 var ShbsError = defineClass("ShbsError", { withCause: true });
+var HpkeError = defineClass("HpkeError", { withCause: true });
+// SigstoreError -- a Sigstore bundle (npm --provenance artifact) that is not a
+// well-formed / verifiable keyless signature: a malformed or oversize JSON
+// bundle, an unknown media type or content arm, a DSSE envelope missing a
+// required field or whose signature does not verify under the Fulcio leaf key, a
+// Rekor inclusion proof that does not reconstruct the signed tree root, an
+// unsigned/attacker-supplied root, an entry that does not bind this signature, a
+// Fulcio identity that fails the caller policy, or a payload that is not the
+// expected in-toto Statement. Carries the underlying leaf fault (an x509/*,
+// merkle/*, or asn1/* error) as `.cause`.
+var SigstoreError = defineClass("SigstoreError", { withCause: true });
 
 module.exports = {
   PkiError:         PkiError,
@@ -306,6 +317,8 @@ module.exports = {
   PathError:        PathError,
   CtError:          CtError,
   ShbsError:        ShbsError,
+  HpkeError:        HpkeError,
+  SigstoreError:    SigstoreError,
   MerkleError:      MerkleError,
   SmimeError:       SmimeError,
   CsrattrsError:    CsrattrsError,