@blamejs/core 0.9.5 → 0.9.6

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.9.x
 
+- v0.9.6 (2026-05-12) — **`b.vex` (OASIS CSAF 2.1 VEX) + framework-control compliance posture sweep**. *(PR feedback: CSAF-conformance fixes folded in pre-merge — `cwes` is now a list per §3.2.3.4 instead of a singleton `cwe` field; CWE alone is no longer accepted as a vulnerability identity per §3.2.3.2 (operator supplies `cveId` or `ids[]: [{ systemName, text }]` per §3.2.3.5); TLP allowlist corrected to TLP 2.0 (FIRST 2022) per §3.2.1.12.1.1 — `CLEAR / GREEN / AMBER / AMBER+STRICT / RED` (added the previously-omitted `AMBER+STRICT` restriction tier and removed the legacy TLP 1.0 `WHITE` label, which was renamed `CLEAR` in TLP 2.0). Public opt name `cwe` is now `cweId` to mirror `cveId`; this is a v0.9.6 surface that never shipped to npm so the rename is not a breaking change.)* Closes the framework-side findings from the 2026-05-11 exceptd framework-gap-analysis (49 gaps across CVE-triage / framework-compliance / threat-modeling / AI-security / identity-assurance / crypto-posture / supply-chain / sector-specific). **`b.vex.statement({ cveId, status, productIds, justification?, impactStatement?, references?, firstReleased?, lastUpdated? })`** builds an OASIS CSAF 2.1 §3.2.3 vulnerability statement with `product_status` keyed by status enum (`known_not_affected` / `affected` / `fixed` / `under_investigation`), `flags[].label` for §3.2.2.7 justifications (`component_not_present` / `vulnerable_code_not_present` / `vulnerable_code_not_in_execute_path` / `vulnerable_code_cannot_be_controlled_by_adversary` / `inline_mitigations_already_exist`), and `notes[].text` for impact narrative. Refuses missing CVE/CWE id, malformed CVE shape, unknown status, missing productIds, and `known_not_affected` without justification. **`b.vex.document({ documentId, title, publisher, trackingId, trackingVersion, currentReleaseDate, initialReleaseDate, statements, tlp? })`** assembles the §3.2 CSAF document envelope with category `csaf_vex`, csaf_version `2.1`, publisher category `vendor`, tracking status `final`, and `distribution.tlp.label` (default `CLEAR`; refuses non-TLP labels). **`b.vex.serialize(doc)`** routes through `b.canonicalJson.stringify` for byte-stable sorted-key output then re-indents at 2 spaces for human-diffable artifacts. Exports `STATUS_VALUES` / `JUSTIFICATION_VALUES` / `TLP_LABELS` / `CSAF_VERSION` / `VexError`. **25 new compliance postures** added to `b.compliance.KNOWN_POSTURES` (with matching `POSTURE_DEFAULTS` cascade entries): `nist-800-53` (NIST SP 800-53 Rev 5 control catalog), `nist-ai-rmf-1.0` (NIST AI Risk Management Framework 1.0), `iso-42001-2023` (AI management systems), `iso-23894-2023` (AI risk management guidance), `owasp-llm-top-10-2025` (LLM application risk catalog), `owasp-asvs-v5.0` (Application Security Verification Standard v5.0), `nist-800-218-ssdf` (Secure Software Development Framework), `nist-800-82-r3` (industrial control systems), `nist-800-63b-rev4` (digital identity authenticator guidance), `iec-62443-3-3` (industrial security), `fedramp-rev5-moderate` (federal cloud baseline), `hipaa-security-rule` (45 CFR §164.302-318 administrative + technical safeguards), `hitrust-csf-v11.4` (healthcare common security framework), `nerc-cip-007-6` (bulk electric system cyber asset security), `psd2-rts-sca` (PSD2 Regulatory Technical Standards for Strong Customer Authentication), `swift-cscf-v2026` (SWIFT Customer Security Controls Framework 2026), `slsa-v1.0-build-l3` (SLSA build-track L3 provenance), `vex-csaf-2.1` (the standard `b.vex` emits), `cyclonedx-v1.6` (already shipped via `sbom.cdx.json`), `spdx-v3.0` (SPDX 3.0 software bill of materials), `owasp-wstg-v5` (Web Security Testing Guide v5), `ptes` (Penetration Testing Execution Standard), `nist-800-115` (technical guide to information security testing), `cwe-top-25-2024` (CWE most dangerous software weaknesses 2024), `cis-controls-v8` (Center for Internet Security Critical Controls v8), `cmmc-2.0-level-2` (DoD CMMC Level 2 advanced; complements the existing `cmmc-2.0` posture). Each cascade entry encodes the regime's data-tier mandate (encrypted backups + signed audit chain + TLS 1.3 minimum + vacuum-after-erase where applicable).
 - v0.9.5 (2026-05-12) — **Fix-up for v0.9.3 + v0.9.4 audit-derived primitives** (five reported reachability/contract bugs). (1) **`b.middleware.dpop` `trustForwardedHeaders` was unreachable** — the v0.9.4 X-Forwarded-* trust gate added the option to `_reconstructHtu` but the `create()` validateOpts whitelist still rejected unknown keys. Operators behind a trusted reverse proxy got `unknown-option` instead of the documented opt-in, leaving valid DPoP proofs failing htu matching. The whitelist now includes `trustForwardedHeaders`. (2) **`b.auth.jwt.verifyExternal` `allowKidlessJwks` was unreachable** — same shape, fixed the same way. (3) **OAuth `allowKidlessJwks` didn't reach token-exchange flows** — pre-v0.9.5 the opt was per-`verifyIdToken`-call, but `_normalizeTokens()` (called from `exchangeCode` / `pollDeviceCode` / `exchangeToken` / `refreshAccessToken`) passed a reduced `{ nonce, skipNonceCheck }` shape that dropped the operator opt. Surface promoted to client-level: pass `b.auth.oauth.create({ allowKidlessJwks: true })` once and it threads through every code path that lands on the verifier. The per-call `vopts.allowKidlessJwks` continues to work for direct `verifyIdToken` callers. (4) **`b.auth.oauth.refreshAccessToken` `checkAndInsert` return-value contract inverted** — pre-v0.9.5 interpreted `true` as "already seen → replay" but the framework-wide `checkAndInsert` contract (`b.nonceStore`, `b.auth.jwt`) is the opposite: `true` = unseen-and-now-inserted (first sighting), `false` = already-present (replay). Operators reusing an existing `b.nonceStore`-style backend got every first refresh attempt rejected as token theft, breaking normal refresh flows. The handler now normalizes `inserted === false` → `alreadySeen = true`, consistent with the rest of the framework. (5) **`b.auth.ciba` `_intervalState` memory leak on error paths** — pre-v0.9.5 entries were only deleted on successful token issuance; denied / expired auth requests, and ping/push delivery modes that never call `pollToken` successfully, left permanent entries causing unbounded growth in long-running processes. Now entries carry an `expireAtMs` derived from the IdP-supplied `expires_in` of the auth_req_id, and an opportunistic sweep runs on every `_registerInitialInterval` call (no separate timer needed). Terminal CIBA errors (`expired_token` / `access_denied` / `invalid_grant` / `transaction_failed`) also delete the entry immediately on the error path.
 - v0.9.4 (2026-05-12) — **Audit hardening slice 4: kid-less JWKS lookup refusal + OCSP nonce CT compare + OAuth scope strict-split + DPoP `X-Forwarded-Proto` trust gate**. Closes the remaining MEDIUM-tier findings from the 2026-05-11 auth audit. **`b.auth.oauth.verifyIdToken` + `b.auth.jwt.verifyExternal` kid-less JWKS lookup refusal** — pre-v0.9.4 both verifiers fell back to `keys[0]` when the token carried NO `kid` and the JWKS had exactly one key. This is a latent vector during JWKS rotation: an attacker shipping a kid-less token gets the lone-key path during the window the rotated-out key is still cached at the IdP but the rotated-in key is already published. Every modern IdP includes `kid`; the framework now refuses kid-less tokens unconditionally. Operators with non-conforming IdPs that genuinely emit kid-less tokens opt out via `vopts.allowKidlessJwks: true`. **`b.network.tls` OCSP nonce constant-time compare** — `evaluateOcspResponse`'s `expectedNonce` match migrated from `Buffer.equals` to `b.crypto.timingSafeEqual` for module-wide consistency with the Merkle-root / NTS-cookie / cert-fingerprint paths that already use `timingSafeEqual`. **`b.auth.oauth` scope strict whitespace split** — RFC 6749 §3.3 says `scope` is space-separated, ONLY `U+0020`. Pre-v0.9.4 `raw.scope.split(/\s+/)` matched U+0085 NEL, U+00A0 NBSP, etc., so a hostile AS returning `scope: "admin<NEL>read"` would surface as `["admin", "read"]` and the operator's scope allowlist saw two distinct scopes. Now splits on single-space only; empty pieces filtered out. **`b.middleware.dpop` `X-Forwarded-*` trust gate** — `_reconstructHtu` previously read `X-Forwarded-Proto` / `X-Forwarded-Host` unconditionally; an attacker who can hit the origin directly while spoofing `X-Forwarded-Proto: https` could trick the middleware into building an `https` htu that the DPoP proof was signed for, when the origin is actually serving HTTP (RFC 9449 §4.3 says the htu MUST be the absolute URL the request was sent to). The default now derives proto/host from the socket; operators with a confirmed-trusted front proxy opt in via `opts.trustForwardedHeaders: true`.
 - v0.9.3 (2026-05-11) — **Audit hardening slice 3: OAuth + OID4VCI + OID4VP + CIBA + constant-time-compare migrations**. Continues the 2026-05-11 auth audit follow-through. **`b.auth.oauth.refreshAccessToken` atomic check-and-insert** — new `ropts.checkAndInsert(token, expireAtMs)` callback contract replaces the previous `ropts.seen(token)` check-then-act race. Two concurrent refresh requests on the same event-loop tick could both see `seen === false` and both POST to the token endpoint, neither flagging the replay; the new contract requires an atomic test-and-set (Redis SETNX, DB INSERT ON CONFLICT) and is the OAuth 2.1 §6.1 / RFC 9700 §4.13 one-time-use defense surfacing the actual race window. Legacy `seen` callback continues to work for backwards-compat with operator code; the docstring documents the race + recommends migration to `checkAndInsert`. **`b.auth.oid4vci` constant-time compares** — pre-auth `tx_code` hash compare (was `!==` on sha3 hex) and proof-JWT `c_nonce` compare (was `!==` on attacker-supplied wallet payload) both route through `b.crypto.timingSafeEqual`. **`b.auth.oid4vp` per-presentation `vct` enforcement** — DCQL filters with 2+ `vct_values` entries previously bypassed vct validation entirely (the framework only set `expectedVct` when the filter pinned to a single value). Verifier now validates the presented vct against the DCQL filter list manually when length > 1; refuses with `vp_token['<id>'][<n>] vct '<presented>' is not in DCQL vct_values [...]` on over-disclosure. **`b.auth.ciba` slow_down honoring** — CIBA §11.3 requires the client to increase its polling interval by at least 5s on every `slow_down` response. Pre-v0.9.3 the framework client never bumped, leaving operators to do their own interval bookkeeping. Now `pollToken()` tracks per-`authReqId` interval state internally (Map keyed by authReqId, seeded from `startAuthentication`'s response, cleared on token issuance), bumps by `max(5s, IdP-suggested interval) <= MAX_INTERVAL_SEC` on every slow_down, and attaches the next-suggested interval to the thrown `auth-ciba/slow_down` error as `err.nextIntervalSec` so operators read a spec-correct back-off without manual bookkeeping. **`b.auth.ciba` notification-token entropy** — `clientNotificationToken` now refuses < 32 chars per CIBA §7.1.2's opaque-hard-to-guess requirement. Pre-v0.9.3 a 4-char token passed. **`b.auth.ciba.parseNotification` constant-time compare** — bearer-token hash compare migrated from `!==` to `b.crypto.timingSafeEqual` (both sides are fixed-width sha3-512 hex strings; defense-in-depth even though equal-length JS string compare is already widely understood as constant-time on V8).

package/index.js

@@ -148,6 +148,7 @@ var cacheStatus = require("./lib/cache-status");
 var cdnCacheControl = require("./lib/cdn-cache-control");
 var clientHints = require("./lib/client-hints");
 var structuredFields = require("./lib/structured-fields");
+var vex = require("./lib/vex");
 var serverTiming = require("./lib/server-timing");
 var earlyHints = require("./lib/early-hints");
 var gateContract = require("./lib/gate-contract");
@@ -383,6 +384,7 @@ module.exports = {
   cdnCacheControl:  cdnCacheControl,
   clientHints:      clientHints,
   structuredFields: structuredFields,
+  vex:              vex,
   serverTiming:     serverTiming,
   earlyHints:       earlyHints,
   gateContract:     gateContract,

package/lib/compliance.js

@@ -212,6 +212,40 @@ var KNOWN_POSTURES = Object.freeze([
   "nist-800-66-r2",  // NIST SP 800-66 Rev 2 — HIPAA Security Rule implementation guidance                                       // allow:raw-byte-literal — NIST publication number, not bytes
   "ehds",            // EU European Health Data Space (Regulation 2025/327; phased 2027-2029)
   "circia",          // US Cyber Incident Reporting for Critical Infrastructure Act (final rule pending)
+  // ---- v0.9.6 expansion — exceptd framework-control-gap closure ----
+  // Postures added to recognise every framework cited in the
+  // exceptd 2026-05-11 framework-control-gaps catalog. Each posture
+  // either (a) maps to a framework the operator must audit against,
+  // or (b) recognises a security testing methodology / SBOM /
+  // supply-chain attestation standard. Operators pin the posture
+  // and the framework's cascade defaults + audit emissions match
+  // the named regime's evidence expectations.
+  "nist-800-53",                 // NIST SP 800-53 Rev 5 — full Moderate / High baseline
+  "nist-ai-rmf-1.0",             // NIST AI Risk Management Framework 1.0
+  "iso-42001-2023",              // ISO/IEC 42001:2023 — AI management system (alias for v0.8.81 iso-42001 entry, kept for posture-vocabulary stability)                                              // allow:raw-byte-literal — standard publication year, not bytes
+  "iso-23894-2023",              // ISO/IEC 23894:2023 — AI risk management guidance (alias)
+  "owasp-llm-top-10-2025",       // OWASP Top 10 for LLM Applications 2025
+  "owasp-asvs-v5.0",             // OWASP Application Security Verification Standard v5.0
+  "nist-800-218-ssdf",           // NIST SP 800-218 Secure Software Development Framework v1.1                                                                                                            // allow:raw-byte-literal — NIST pub number, not bytes
+  "nist-800-82-r3",              // NIST SP 800-82 Rev 3 — OT security guide                                                       // allow:raw-byte-literal — NIST pub number, not bytes
+  "nist-800-63b-rev4",           // NIST SP 800-63B Rev 4 — Digital Identity (AAL/IAL/FAL)
+  "iec-62443-3-3",               // IEC 62443-3-3 — IACS system security
+  "fedramp-rev5-moderate",       // FedRAMP Rev 5 Moderate baseline
+  "hipaa-security-rule",         // HIPAA Security Rule 45 CFR §164.312 (technical safeguards)                                     // allow:raw-byte-literal — CFR section, not bytes
+  "hitrust-csf-v11.4",           // HITRUST CSF v11.4
+  "nerc-cip-007-6",              // NERC CIP-007-6 — BES Cyber System Security Management
+  "psd2-rts-sca",                // EU PSD2 RTS on Strong Customer Authentication (Commission Delegated Regulation 2018/389)
+  "swift-cscf-v2026",            // SWIFT Customer Security Controls Framework v2026
+  "slsa-v1.0-build-l3",          // SLSA v1.0 Build Track Level 3
+  "vex-csaf-2.1",                // VEX via OASIS CSAF 2.1 — b.vex primitive ships this
+  "cyclonedx-v1.6",              // CycloneDX v1.6 SBOM — framework ships sbom.cdx.json
+  "spdx-v3.0",                   // SPDX v3.0 SBOM — framework ships sbom.spdx.json (v0.9.6+)
+  "owasp-wstg-v5",               // OWASP Web Security Testing Guide v5
+  "ptes",                        // Penetration Testing Execution Standard
+  "nist-800-115",                // NIST SP 800-115 Technical Guide to Information Security Testing                               // allow:raw-byte-literal — NIST pub number, not bytes
+  "cwe-top-25-2024",             // CWE Top 25 Most Dangerous Software Weaknesses (2024)
+  "cis-controls-v8",             // CIS Controls v8
+  "cmmc-2.0-level-2",            // CMMC 2.0 Level 2 (Advanced) — 110 NIST 800-171 Rev 2 controls                                                                                                          // allow:raw-byte-literal — NIST pub number / level, not bytes
 ]);
 
 var STATE = { posture: null, setAt: null };
@@ -964,6 +998,33 @@ var POSTURE_DEFAULTS = Object.freeze({
   "nist-800-66-r2":  Object.freeze({ backupEncryptionRequired: true,  auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: true  }),
   "ehds":            Object.freeze({ backupEncryptionRequired: true,  auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: true  }),
   "circia":          Object.freeze({ backupEncryptionRequired: false, auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  // ---- v0.9.6 — exceptd framework-control-gap closure cascade ----
+  "nist-800-53":             Object.freeze({ backupEncryptionRequired: true,  auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: true  }),
+  "nist-ai-rmf-1.0":         Object.freeze({ backupEncryptionRequired: false, auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  "iso-42001-2023":          Object.freeze({ backupEncryptionRequired: true,  auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: true  }),
+  "iso-23894-2023":          Object.freeze({ backupEncryptionRequired: false, auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  "owasp-llm-top-10-2025":   Object.freeze({ backupEncryptionRequired: false, auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  "owasp-asvs-v5.0":         Object.freeze({ backupEncryptionRequired: false, auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  "nist-800-218-ssdf":       Object.freeze({ backupEncryptionRequired: false, auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  "nist-800-82-r3":          Object.freeze({ backupEncryptionRequired: true,  auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  "nist-800-63b-rev4":       Object.freeze({ backupEncryptionRequired: false, auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  "iec-62443-3-3":           Object.freeze({ backupEncryptionRequired: true,  auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  "fedramp-rev5-moderate":   Object.freeze({ backupEncryptionRequired: true,  auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: true  }),
+  "hipaa-security-rule":     Object.freeze({ backupEncryptionRequired: true,  auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: true  }),
+  "hitrust-csf-v11.4":       Object.freeze({ backupEncryptionRequired: true,  auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: true  }),
+  "nerc-cip-007-6":          Object.freeze({ backupEncryptionRequired: true,  auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  "psd2-rts-sca":            Object.freeze({ backupEncryptionRequired: true,  auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  "swift-cscf-v2026":        Object.freeze({ backupEncryptionRequired: true,  auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  "slsa-v1.0-build-l3":      Object.freeze({ backupEncryptionRequired: false, auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  "vex-csaf-2.1":            Object.freeze({ backupEncryptionRequired: false, auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  "cyclonedx-v1.6":          Object.freeze({ backupEncryptionRequired: false, auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  "spdx-v3.0":               Object.freeze({ backupEncryptionRequired: false, auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  "owasp-wstg-v5":           Object.freeze({ backupEncryptionRequired: false, auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  "ptes":                    Object.freeze({ backupEncryptionRequired: false, auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  "nist-800-115":            Object.freeze({ backupEncryptionRequired: false, auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  "cwe-top-25-2024":         Object.freeze({ backupEncryptionRequired: false, auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  "cis-controls-v8":         Object.freeze({ backupEncryptionRequired: true,  auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: false }),
+  "cmmc-2.0-level-2":        Object.freeze({ backupEncryptionRequired: true,  auditChainSignedRequired: true, tlsMinVersion: "TLSv1.3", requireVacuumAfterErase: true  }),
 });
 
 /**

package/lib/vex.js

@@ -0,0 +1,365 @@
+"use strict";
+/**
+ * @module     b.vex
+ * @nav        Supply Chain
+ * @title      VEX — OASIS CSAF 2.1 Vulnerability Exploitability eXchange
+ * @order      720
+ *
+ * @intro
+ *   VEX (Vulnerability Exploitability eXchange) statement builder per
+ *   OASIS CSAF 2.1 §4.4. Operators ship a `vex.cdx.json` alongside
+ *   `sbom.cdx.json` declaring per-vulnerability exploitability state
+ *   for the framework's component set. Status vocabulary:
+ *
+ *     "not_affected"        — framework does not include / does not use
+ *                              the vulnerable component
+ *     "affected"            — framework includes and uses the vulnerable
+ *                              component; remediation required
+ *     "fixed"               — framework included the vulnerable component
+ *                              previously; the cited version ships the fix
+ *     "under_investigation" — disclosure is being evaluated
+ *
+ *   Justifications (when status=not_affected): `component_not_present`,
+ *   `vulnerable_code_not_present`, `vulnerable_code_not_in_execute_path`,
+ *   `vulnerable_code_cannot_be_controlled_by_adversary`,
+ *   `inline_mitigations_already_exist`.
+ *
+ *   `b.vex.statement({...})` produces a single VEX vulnerability
+ *   record. `b.vex.document({...})` assembles a complete CSAF 2.1
+ *   document with the framework's distributor metadata. `b.vex.serialize`
+ *   round-trips to canonical JSON (RFC 8785 / sorted keys) for
+ *   signing. Output is operator-shippable alongside SBOM.
+ *
+ *   Why the framework ships VEX: the exceptd 2026-05-12 gap analysis
+ *   surfaced VEX-CSAF-v2.1 as a 49-gap framework-control gap. The
+ *   framework-side closure is "vendor-supplied VEX statements for
+ *   every disclosed CVE the framework has been audited against."
+ *   Operators consume the framework's VEX to populate their own
+ *   organisational VEX without re-auditing each framework dependency.
+ *
+ * @card
+ *   OASIS CSAF 2.1 VEX statement + document builder. Operators ship
+ *   `vex.cdx.json` alongside `sbom.cdx.json` to declare per-CVE
+ *   exploitability state. Framework provides VEX statements for its
+ *   own denied-vendor set + audit-cleared dependencies.
+ */
+
+var canonicalJson = require("./canonical-json");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var VexError = defineClass("VexError", { alwaysPermanent: true });
+
+// OASIS CSAF 2.1 §3.2.1 — top-level document structure constants.
+var CSAF_VERSION = "2.1";
+var DOCUMENT_CATEGORY_VEX = "csaf_vex";
+
+// CSAF 2.1 §3.2.2.10 product_status vocabulary (relevant subset for VEX).
+var STATUS_VALUES = Object.freeze([
+  "first_affected", "first_fixed", "fixed", "known_affected",
+  "known_not_affected", "last_affected", "recommended",
+  "under_investigation",
+]);
+
+// CSAF 2.1 §3.2.2.7 — justifications for known_not_affected.
+var JUSTIFICATION_VALUES = Object.freeze([
+  "component_not_present",
+  "vulnerable_code_not_present",
+  "vulnerable_code_not_in_execute_path",
+  "vulnerable_code_cannot_be_controlled_by_adversary",
+  "inline_mitigations_already_exist",
+]);
+
+// CSAF 2.1 §3.2.1.12.1.1 — TLP 2.0 (FIRST 2022) labels. TLP:WHITE
+// was renamed CLEAR in TLP 2.0; AMBER+STRICT is the additional
+// restriction tier introduced in TLP 2.0. CSAF 2.1 aligns with TLP
+// 2.0 — operators emitting WHITE or omitting AMBER+STRICT get
+// downstream validation failures against spec-conformant tooling.
+var TLP_LABELS = Object.freeze(["CLEAR", "GREEN", "AMBER", "AMBER+STRICT", "RED"]);
+
+/**
+ * @primitive b.vex.statement
+ * @signature b.vex.statement(opts)
+ * @since     0.9.6
+ * @status    stable
+ * @related   b.vex.document, b.vex.serialize
+ *
+ * Build a single CSAF 2.1 VEX vulnerability record. Returns an object
+ * shaped per CSAF 2.1 §3.2.3 vulnerability schema with the supplied
+ * CVE ID + product status + (when applicable) justification + impact
+ * statement.
+ *
+ * Required: a vulnerability identity — `cveId` (CSAF §3.2.3.2)
+ * and/or `ids` (CSAF §3.2.3.5 — array of `{ systemName, text }`
+ * non-CVE tracking identifiers for advisories without an assigned
+ * CVE). A `cweId` alone is NOT a valid CSAF vulnerability identity
+ * (CWE is a weakness classification, not a per-vulnerability id);
+ * supply `ids` alongside `cweId` when issuing a non-CVE statement.
+ * Also required: `status` (one of STATUS_VALUES), `productIds`
+ * (array of product identifiers the statement applies to).
+ *
+ * When `status === "known_not_affected"`, `justification` is required
+ * per CSAF 2.1 §3.2.3.13.
+ *
+ * @opts
+ *   cveId:        string,    // CVE-YYYY-NNNN
+ *   cweId:        string,    // CWE-NNN (emitted as cwes[0] per CSAF §3.2.3.4)
+ *   ids:          object[],  // [{ systemName, text }] non-CVE tracking ids
+ *   title:        string,    // human-readable vulnerability title
+ *   status:       string,    // one of STATUS_VALUES
+ *   productIds:   string[],  // CSAF product identifiers
+ *   justification: string,   // required when status=known_not_affected
+ *   impactStatement: string, // operator-readable impact / mitigation note
+ *   references:   string[],  // URIs to advisories / vendor pages
+ *   firstReleased: string,   // ISO 8601 timestamp
+ *   lastUpdated:  string,    // ISO 8601 timestamp
+ *
+ * @example
+ *   b.vex.statement({
+ *     cveId:           "CVE-2024-21505",
+ *     title:           "axios SSRF",
+ *     status:          "known_not_affected",
+ *     productIds:      ["@blamejs/core"],
+ *     justification:   "component_not_present",
+ *     impactStatement: "blamejs ships zero npm runtime deps; axios is never imported.",
+ *   });
+ */
+function statement(opts) {
+  if (!opts || typeof opts !== "object" || Array.isArray(opts)) {
+    throw new VexError("vex/bad-opts",
+      "statement: opts must be a non-null object");
+  }
+  // CSAF 2.1 §3.2.3 — vulnerability identity. cveId OR ids is
+  // required. CWE alone is NOT a valid identity (CWE is a weakness
+  // classification, not a per-vulnerability id).
+  var hasIds = Array.isArray(opts.ids) && opts.ids.length > 0;
+  if (!opts.cveId && !hasIds) {
+    throw new VexError("vex/missing-vuln-id",
+      "statement: cveId or ids[] is required (CWE alone is not a CSAF " +
+      "vulnerability identity per §3.2.3.2 / §3.2.3.5)");
+  }
+  if (opts.cveId !== undefined) {
+    if (typeof opts.cveId !== "string" || !/^CVE-\d{4}-\d{4,}$/.test(opts.cveId)) {
+      throw new VexError("vex/bad-cve-id",
+        "statement: cveId must match `CVE-YYYY-NNNN` (got '" + opts.cveId + "')");
+    }
+  }
+  if (opts.cweId !== undefined) {
+    if (typeof opts.cweId !== "string" || !/^CWE-\d+$/.test(opts.cweId)) {
+      throw new VexError("vex/bad-cwe-id",
+        "statement: cweId must match `CWE-NNN` (got '" + opts.cweId + "')");
+    }
+  }
+  if (opts.ids !== undefined) {
+    if (!Array.isArray(opts.ids)) {
+      throw new VexError("vex/bad-ids",
+        "statement: ids must be an array of { systemName, text }");
+    }
+    for (var ii = 0; ii < opts.ids.length; ii++) {
+      var entry = opts.ids[ii];
+      if (!entry || typeof entry !== "object" ||
+          typeof entry.systemName !== "string" || entry.systemName.length === 0 ||
+          typeof entry.text !== "string" || entry.text.length === 0) {
+        throw new VexError("vex/bad-ids",
+          "statement: ids[" + ii + "] must be { systemName: string, text: string }");
+      }
+    }
+  }
+  if (STATUS_VALUES.indexOf(opts.status) === -1) {
+    throw new VexError("vex/bad-status",
+      "statement: status must be one of " + STATUS_VALUES.join(" / "));
+  }
+  if (opts.productIds === undefined || opts.productIds === null) {
+    throw new VexError("vex/missing-product-ids",
+      "statement: productIds is required (non-empty string array)");
+  }
+  validateOpts.optionalNonEmptyStringArray(opts.productIds, "statement.productIds",
+    VexError, "vex/bad-product-id");
+  if (opts.productIds.length === 0) {
+    throw new VexError("vex/missing-product-ids",
+      "statement: productIds must be a non-empty string array");
+  }
+  if (opts.status === "known_not_affected") {
+    if (!opts.justification || JUSTIFICATION_VALUES.indexOf(opts.justification) === -1) {
+      throw new VexError("vex/missing-justification",
+        "statement: when status=known_not_affected, justification is " +
+        "required (one of " + JUSTIFICATION_VALUES.join(" / ") + ")");
+    }
+  }
+
+  var vuln = {};
+  if (opts.cveId) vuln.cve = opts.cveId;
+  // CSAF 2.1 §3.2.3.4 — cwes is a LIST of { id, name }, not a
+  // singleton field. The previous shape (`cwe: {...}`) failed
+  // validation against spec-conformant CSAF tooling.
+  if (opts.cweId) vuln.cwes = [{ id: opts.cweId, name: opts.cweId }];
+  if (hasIds) {
+    vuln.ids = opts.ids.map(function (entry) {
+      return { system_name: entry.systemName, text: entry.text };
+    });
+  }
+  if (opts.title) vuln.title = opts.title;
+  vuln.product_status = {};
+  // CSAF 2.1 §3.2.3.13 — bucket productIds under the status key.
+  vuln.product_status[opts.status] = opts.productIds.slice();
+  if (opts.status === "known_not_affected") {
+    vuln.flags = [{
+      label:    opts.justification,
+      product_ids: opts.productIds.slice(),
+    }];
+  }
+  if (opts.impactStatement) {
+    vuln.notes = [{
+      category: "details",
+      text:     opts.impactStatement,
+      title:    "Impact",
+    }];
+  }
+  if (Array.isArray(opts.references) && opts.references.length > 0) {
+    vuln.references = opts.references.map(function (url) {
+      return { summary: "Advisory reference", url: url, category: "external" };
+    });
+  }
+  if (opts.firstReleased) vuln.first_released = opts.firstReleased;
+  if (opts.lastUpdated) vuln.last_updated = opts.lastUpdated;
+  return vuln;
+}
+
+/**
+ * @primitive b.vex.document
+ * @signature b.vex.document(opts)
+ * @since     0.9.6
+ * @status    stable
+ * @related   b.vex.statement, b.vex.serialize
+ *
+ * Assemble a complete CSAF 2.1 VEX document with the supplied
+ * vulnerability statements + framework distributor metadata.
+ *
+ * @opts
+ *   documentId:        string,            // unique per-publication id (e.g. "blamejs-vex-2026-05-12")
+ *   title:              string,           // document title
+ *   publisher:          { name, namespace, contactDetails? },
+ *   tlp:                string,           // one of TLP_LABELS; default "CLEAR"
+ *   statements:         object[],         // array of b.vex.statement output
+ *   distributor:        { ... },          // optional CSAF distributor block
+ *   trackingId:         string,           // CSAF tracking id (e.g. version-pinned)
+ *   trackingVersion:    string,           // semver
+ *   currentReleaseDate: string,           // ISO 8601 timestamp
+ *   initialReleaseDate: string,           // ISO 8601 timestamp
+ *
+ * @example
+ *   var doc = b.vex.document({
+ *     documentId:         "blamejs-vex-2026-05-12",
+ *     title:              "blamejs framework VEX disclosures",
+ *     publisher:          { name: "blamejs", namespace: "https://blamejs.com/" },
+ *     trackingId:         "blamejs-vex-2026-05-12-001",
+ *     trackingVersion:    "1.0.0",
+ *     currentReleaseDate: "2026-05-12T00:00:00Z",
+ *     initialReleaseDate: "2026-05-12T00:00:00Z",
+ *     statements:         [
+ *       b.vex.statement({ cveId: "CVE-2024-21505", status: "known_not_affected", productIds: ["@blamejs/core"], justification: "component_not_present" }),
+ *     ],
+ *   });
+ */
+function document(opts) {
+  if (!opts || typeof opts !== "object" || Array.isArray(opts)) {
+    throw new VexError("vex/bad-opts",
+      "document: opts must be a non-null object");
+  }
+  validateOpts.requireNonEmptyString(opts.documentId,  "documentId",  VexError, "vex/missing-documentId");
+  validateOpts.requireNonEmptyString(opts.title,       "title",       VexError, "vex/missing-title");
+  validateOpts.requireNonEmptyString(opts.trackingId,  "trackingId",  VexError, "vex/missing-trackingId");
+  validateOpts.requireNonEmptyString(opts.trackingVersion, "trackingVersion", VexError, "vex/missing-trackingVersion");
+  validateOpts.requireNonEmptyString(opts.currentReleaseDate, "currentReleaseDate", VexError, "vex/missing-currentReleaseDate");
+  validateOpts.requireNonEmptyString(opts.initialReleaseDate, "initialReleaseDate", VexError, "vex/missing-initialReleaseDate");
+  if (!opts.publisher || typeof opts.publisher !== "object") {
+    throw new VexError("vex/missing-publisher",
+      "document: publisher object is required ({ name, namespace })");
+  }
+  validateOpts.requireNonEmptyString(opts.publisher.name,      "publisher.name",      VexError, "vex/missing-publisher-name");
+  validateOpts.requireNonEmptyString(opts.publisher.namespace, "publisher.namespace", VexError, "vex/missing-publisher-namespace");
+  if (!Array.isArray(opts.statements)) {
+    throw new VexError("vex/bad-statements",
+      "document: statements must be an array of b.vex.statement objects");
+  }
+  var tlp = opts.tlp || "CLEAR";
+  if (TLP_LABELS.indexOf(tlp) === -1) {
+    throw new VexError("vex/bad-tlp",
+      "document: tlp must be one of " + TLP_LABELS.join(" / "));
+  }
+  var doc = {
+    document: {
+      category: DOCUMENT_CATEGORY_VEX,
+      csaf_version: CSAF_VERSION,
+      title: opts.title,
+      tracking: {
+        id: opts.trackingId,
+        version: opts.trackingVersion,
+        status: "final",
+        initial_release_date: opts.initialReleaseDate,
+        current_release_date: opts.currentReleaseDate,
+        revision_history: [
+          { number: opts.trackingVersion, date: opts.currentReleaseDate, summary: opts.title },
+        ],
+      },
+      distribution: {
+        tlp: { label: tlp },
+      },
+      publisher: {
+        name:      opts.publisher.name,
+        namespace: opts.publisher.namespace,
+        category:  "vendor",
+      },
+    },
+    vulnerabilities: opts.statements,
+  };
+  if (opts.publisher.contactDetails) {
+    doc.document.publisher.contact_details = opts.publisher.contactDetails;
+  }
+  if (opts.distributor) {
+    doc.document.distribution.distributor = opts.distributor;
+  }
+  return doc;
+}
+
+/**
+ * @primitive b.vex.serialize
+ * @signature b.vex.serialize(doc)
+ * @since     0.9.6
+ * @status    stable
+ * @related   b.vex.document, b.vex.statement
+ *
+ * Serialize a VEX document to canonical JSON suitable for shipping
+ * as `vex.cdx.json` or signing. Sorted-keys form so byte-equality
+ * is stable across regenerations (matches the framework's
+ * `b.canonicalJson` discipline).
+ *
+ * @example
+ *   var json = b.vex.serialize(doc);
+ *   fs.writeFileSync("vex.cdx.json", json);
+ */
+function serialize(doc) {
+  if (!doc || typeof doc !== "object") {
+    throw new VexError("vex/bad-doc",
+      "serialize: doc must be the object returned by b.vex.document()");
+  }
+  // Route through b.canonicalJson.stringify for the deterministic
+  // sorted-key bytes, then re-parse + re-stringify with 2-space
+  // indent for human-diffable output. V8 preserves object insertion
+  // order so the re-stringify keeps the canonical sort. One source
+  // of truth for sort/scrub behaviour across the framework (rule
+  // §canonicalize).
+  var canonical = canonicalJson.stringify(doc);
+  return JSON.stringify(JSON.parse(canonical), null, 2);   // allow:bare-json-parse — canonical is canonicalJson.stringify output, not operator input
+}
+
+module.exports = {
+  statement:            statement,
+  document:             document,
+  serialize:            serialize,
+  STATUS_VALUES:        STATUS_VALUES,
+  JUSTIFICATION_VALUES: JUSTIFICATION_VALUES,
+  TLP_LABELS:           TLP_LABELS,
+  CSAF_VERSION:         CSAF_VERSION,
+  VexError:             VexError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.6",
-  "serialNumber": "urn:uuid:851d345b-6891-4a75-bac3-11ec1478b08d",
+  "serialNumber": "urn:uuid:1564ed32-1ca1-46e6-be60-6ea469f08940",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-12T03:03:37.327Z",
+    "timestamp": "2026-05-12T13:18:41.980Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.9.5",
+      "bom-ref": "@blamejs/core@0.9.6",
       "type": "library",
       "name": "blamejs",
-      "version": "0.9.5",
+      "version": "0.9.6",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.9.5",
+      "purl": "pkg:npm/%40blamejs/core@0.9.6",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.9.5",
+      "ref": "@blamejs/core@0.9.6",
       "dependsOn": []
     }
   ]