@blamejs/core 0.15.14 → 0.15.15

package/lib/x509-chain.js

@@ -1,33 +1,80 @@
 "use strict";
+/**
+ * @module b.x509Chain
+ * @nav    Crypto
+ * @title  X.509 chain (CA-bit issuer test)
+ *
+ * @intro
+ *   The basicConstraints-enforcing issuer test the framework's own
+ *   certificate-chain walkers route through (<code>b.tsa.verifyToken</code>,
+ *   <code>b.mail.bimi</code> VMC/CMC, <code>b.mail.crypto.smime</code>,
+ *   <code>b.mdoc</code>, <code>b.contentCredentials</code>,
+ *   <code>b.auth.fido</code>). It exists because node:crypto's
+ *   <code>X509Certificate.checkIssued()</code> validates the issuer/subject
+ *   DN match, the AKI/SKI linkage, and — only when a keyUsage extension is
+ *   present — keyCertSign, but it does <strong>not</strong> enforce
+ *   basicConstraints cA:TRUE. A leaf / end-entity certificate (cA:FALSE)
+ *   that omits keyUsage is therefore wrongly accepted as a signing CA for
+ *   the next certificate in the chain — the classic basicConstraints bypass
+ *   (CVE-2002-0862 class). Every in-tree walker routes its issuer test
+ *   through these helpers so the cA enforcement can never be forgotten in
+ *   one walker but present in another.
+ *
+ *   Exposed so a consumer validating an X.509 chain <em>outside</em> a TLS
+ *   handshake — an operator-uploaded CA bundle, a non-handshake PQ-signed
+ *   certificate — has the same hardened, fail-closed test instead of being
+ *   pushed toward the raw <code>checkIssued()</code> path this module
+ *   exists to prevent. Both helpers fail closed: any malformed input or
+ *   unsupported key type returns false rather than throwing.
+ *
+ * @card
+ *   basicConstraints cA:TRUE-enforcing X.509 issuer test, fail-closed —
+ *   the hardened alternative to node's checkIssued() for chains built
+ *   outside a TLS handshake.
+ */
 
-// Internal X.509 path-validation helpers shared by the framework's
-// certificate-chain walkers (b.tsa.verifyToken, b.mail.bimi VMC/CMC,
-// b.mail.crypto.smime.verify). They exist because node:crypto's
-// X509Certificate.checkIssued() validates the issuer/subject DN match,
-// the AKI/SKI linkage, and — when a keyUsage extension is present —
-// keyCertSign, but it does NOT enforce basicConstraints cA:TRUE. A
-// leaf / end-entity certificate (cA:FALSE) that omits keyUsage is
-// therefore wrongly accepted as a signing CA for the next cert in the
-// chain — the classic basicConstraints bypass (CVE-2002-0862 class).
-// Every chain walker routes its issuer test through these helpers so the
-// cA enforcement can never be forgotten in one walker but present in
-// another.
-
-// True only when `cert` asserts basicConstraints cA:TRUE. node's
-// X509Certificate exposes `.ca` (a boolean); a cert with no
-// basicConstraints extension or with cA:FALSE returns false. A missing
-// cert or a non-boolean `.ca` (parse failure / unsupported runtime)
-// fails closed.
+/**
+ * @primitive b.x509Chain.isCaCert
+ * @signature b.x509Chain.isCaCert(cert)
+ * @since     0.15.15
+ * @status    stable
+ * @related   b.x509Chain.issuerValidlyIssued
+ *
+ * True only when <code>cert</code> asserts basicConstraints cA:TRUE.
+ * node's <code>X509Certificate</code> exposes <code>.ca</code> (a boolean);
+ * a certificate with no basicConstraints extension or with cA:FALSE
+ * returns false. A missing cert or a non-boolean <code>.ca</code> (parse
+ * failure / unsupported runtime) fails closed to false.
+ *
+ * @example
+ *   var crypto = require("crypto");
+ *   var ca = new crypto.X509Certificate(caPem);
+ *   b.x509Chain.isCaCert(ca);   // → true only if basicConstraints cA:TRUE
+ */
 function isCaCert(cert) {
   return !!cert && cert.ca === true;
 }
 
-// True when `issuer` validly issued `subject` AND is itself a CA: the
-// DN / AKI-SKI / keyUsage linkage (checkIssued), the cryptographic
-// signature (verify), and basicConstraints cA:TRUE (isCaCert). The cA
-// check runs first so a non-CA cert is rejected before the expensive
-// signature verification. Any exception (malformed cert, unsupported
-// key type) fails closed to false.
+/**
+ * @primitive b.x509Chain.issuerValidlyIssued
+ * @signature b.x509Chain.issuerValidlyIssued(issuer, subject)
+ * @since     0.15.15
+ * @status    stable
+ * @related   b.x509Chain.isCaCert
+ *
+ * True when <code>issuer</code> validly issued <code>subject</code> AND is
+ * itself a CA: the DN / AKI-SKI / keyUsage linkage (checkIssued), the
+ * cryptographic signature (verify), and basicConstraints cA:TRUE
+ * (isCaCert). The cA check runs first so a non-CA certificate is rejected
+ * before the expensive signature verification. Any exception (malformed
+ * cert, unsupported key type) fails closed to false.
+ *
+ * @example
+ *   var crypto = require("crypto");
+ *   var issuer  = new crypto.X509Certificate(issuerPem);
+ *   var subject = new crypto.X509Certificate(leafPem);
+ *   b.x509Chain.issuerValidlyIssued(issuer, subject);   // → boolean
+ */
 function issuerValidlyIssued(issuer, subject) {
   try {
     return isCaCert(issuer) &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.15.14",
+  "version": "0.15.15",
   "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.5",
-  "serialNumber": "urn:uuid:81a205f2-938f-47e5-9426-3245e2ac5859",
+  "serialNumber": "urn:uuid:b3337d85-2941-4510-a9ff-2246e428aef5",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-21T13:24:58.132Z",
+    "timestamp": "2026-06-22T03:24:08.024Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.15.14",
+      "bom-ref": "@blamejs/core@0.15.15",
       "type": "application",
       "name": "blamejs",
-      "version": "0.15.14",
+      "version": "0.15.15",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.15.14",
+      "purl": "pkg:npm/%40blamejs/core@0.15.15",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.15.14",
+      "ref": "@blamejs/core@0.15.15",
       "dependsOn": []
     }
   ]