@blamejs/core 0.17.12 → 0.17.13

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.17.x
 
+- v0.17.13 (2026-07-23) — **A cross-surface hardening sweep: the log pipeline redacts secrets embedded in a message string, the SSRF guard gains a hostname-aware loopback classifier, crypto gains an RFC 7469 SPKI pin, and a batch of cross-platform lifecycle bugs across the watcher, self-update, daemon, and WebSocket-client primitives are fixed.** The structured-log pipeline redacted metadata but shipped the free-text message verbatim, so a secret interpolated into a log message reached file and remote sinks unscrubbed; a new in-place free-text redactor closes that at the emit chokepoint and every sink. The SSRF guard grows a hostname-aware loopback classifier so consumers stop re-deriving the localhost/127.0.0.1/::1 triad, crypto grows an RFC 7469 SubjectPublicKeyInfo pin plus a pin-verifying checkServerIdentity builder, and the self-update verifier now accepts the same SHA3-512 / IEEE-P1363 ECDSA signatures its standalone counterpart does. Alongside: cross-platform lifecycle fixes in the recursive watcher (long-path stat, lost-root signalling, dead-handle classification, case-folded ignore matching), the self-updater (Windows in-use-binary replacement, asset-to-signature pairing, post-install probation), the daemon (detached-spawn failure reporting, a Windows cooperative-stop channel, a read-only status probe, a pid-lock adopt window), and the WebSocket client (a close during a slow initial dial no longer opens an orphan socket). **Added:** *New primitives across the watcher, self-update, daemon, crypto, SSRF, redaction, and object surfaces* — b.watcher exports its ignore-pattern length and wildcard caps so a consumer pre-filter aligns with what create() enforces. b.selfUpdate gains a post-install probation lifecycle (beginProbation / confirmHealthy / evaluateOnBoot) that distinguishes a clean stop from a crash and decides a next-boot rollback. b.daemon gains a read-only status() PID-probe and, on Windows, a cooperative stop-request channel so stop() can drain the graceful-shutdown orchestration instead of a hard terminate. b.crypto adds spkiPin / spkiPinVerifier (above). b.ssrfGuard adds isLoopbackHost / isExactLoopbackName (above). b.redact adds redactText (above). And b.safeObject.ownProp / ownSet provide one prototype-pollution-safe own-property get/set that the framework's interpolators compose instead of re-rolling a guarded read. **Changed:** *Public Suffix List refreshed to the current upstream snapshot* — The vendored Mozilla Public Suffix List is updated to the current upstream snapshot, so organizational-domain derivation reflects the latest registry delegations wherever the framework draws a registrable-domain boundary -- DMARC identifier alignment, BIMI issuer scoping, cookie-scope confinement, and same-site policy. The .data.js carrier is regenerated and re-signed across all four integrity layers. **Fixed:** *Recursive watcher: long paths, lost roots, dead handles, case-folded ignores* — b.watcher no longer misreads a change on a Windows path over MAX_PATH as a delete (the post-event stat is long-path-aware); a poll walk that can no longer read the ROOT surfaces a distinct fatal `watcher/root-lost` signal and keeps its prior snapshot instead of diffing an empty tree as a delete of every tracked entry; a native-handle error whose code leaves change detection permanently off is classified fatal (`watcher/handle-dead`) so a wrapper can recreate rather than treat it as transient; and an opt-in `ignoreCaseFold` folds the walk-prune to match a case-insensitive filesystem so an on-disk `Node_Modules` is pruned by a `node_modules/**` ignore. · *Self-update: Windows in-use-binary replacement and asset-to-signature pairing* — swap/rollback install by moving the existing target aside and placing the new bytes at the freed path, so a self-updating Windows daemon can replace its own running image (which the OS locks against an overwrite-in-place); the backup and rollback share the same relocation. And poll now pairs the returned signature to the returned asset by the detached-signature name relationship rather than two independent first-matches, failing closed when the pairing is ambiguous, so a release with several sidecars per binary can no longer hand a foreign signature to the verifier. · *Daemon: detached-spawn failure is reported, pid-lock adopts without a gap* — b.daemon.start's detached mode validated the child pid before writing the pidfile and now subscribes the child's async error so a failed spawn (a bad command) throws instead of returning success and writing an `undefined` pid. And appShutdown's pid-lock adopts an existing pidfile that already records the current process id (the detached parent-handoff) instead of unlinking and recreating it -- closing a window in which the pidfile briefly did not exist and a concurrent stop misread a running daemon as not-running. · *WebSocket client: a close during a slow initial dial opens no orphan socket* — b.wsClient.connect ran its post-SSRF-resolve dial continuation even when close() was called during the (asynchronous, over-a-second) SSRF re-resolve, opening a socket and heartbeat nobody owned. The reconnect path already re-checked the closed flag after its await; the initial dial now does too (guarded at the shared dial funnel), and a close() while still connecting retires immediately rather than leaving the flag unset across the graceful-close window. · *crypto hash error preserves its errno; PQC agent mirrors the curve into TLS groups* — b.crypto.hashFilesParallel now preserves the underlying fs error's `code` / `errno` / `path` on the pre-open stat failure (and gives the symlink-refusal, non-regular-file, and size-cap rejections stable codes) so a caller can tell a benign save-then-delete race from a real read failure without string-matching a message. And b.pqcAgent.create mirrors a caller's `ecdhCurve` into the TLS `groups` option, so narrowing or reordering the curve preference is actually advertised on builds that honor `groups`. · *Reserved-word identifier parity for operator-supplied table and column names* — Several sites that quote an operator- or schema-supplied identifier -- CSV export, the outbox and webhook table-name guards, the DSR ticket store, the Postgres row-level-security emitter, and the view declarator -- rejected a schema-valid name that collides with a SQL keyword, stricter than b.db.from() which permits it. Those sites now match db.from()'s parity (still failing closed on shape, length, null bytes, and the reserved table prefix). **Security:** *The log pipeline redacts secrets embedded in a message string* — b.logStream.emit ran the redactor over structured `meta` but wrote the free-text `message` verbatim, so a credential interpolated into a log line -- a JWT, an AWS access key, a URL-embedded password -- reached file, webhook, syslog, CloudWatch, and OTLP sinks unscrubbed. And the built-in value detectors are whole-value anchored, so even redacting the message with the structured redactor would miss a token embedded mid-sentence. A new `b.redact.redactText` scrubs credentials in place with word-boundary matching (PEM blocks, JWTs, AWS keys, URL-userinfo passwords, bearer tokens, key=secret assignments, SSN/EIN, Luhn-valid PANs) while keeping the surrounding message, deliberately excluding the high-entropy shape detector that would eat ordinary identifiers in prose. It is applied at the emit chokepoint (covering every sink) and at the OTLP encoders' direct path, and is drop-safe on the hot path. · *The SSRF guard gains a hostname-aware loopback classifier* — b.ssrfGuard.classify recognized only IP literals, so `localhost`, `*.localhost`, and bracketed IPv6 forms were not classified as loopback and every consumer re-derived the strip-brackets / strip-trailing-dot / special-case triad by hand. `b.ssrfGuard.isLoopbackHost` composes canonicalization plus classification plus the RFC 6761 reserved names (`localhost` and `*.localhost`); a companion `b.ssrfGuard.isExactLoopbackName` omits the subdomain reservation for the OAuth loopback-redirect exception, which must accept only the exact `localhost` name and never widen to a `*.localhost` an attacker could register. Neither resolves DNS. · *Crypto gains an RFC 7469 SPKI pin and a pin-verifying identity check* — There was no primitive producing the HPKP / RFC 7469 pin -- the base64 SHA-256 over a certificate's SubjectPublicKeyInfo -- so consumers hand-derived it at both the verify and the report site, where drift mints a never-matching pin. `b.crypto.spkiPin` returns that pin (composing the certificate's SPKI export), and `b.crypto.spkiPinVerifier` returns a checkServerIdentity-compatible function that runs the RFC 9525 hostname check first, then constant-time-compares the peer's SPKI pin against a supplied set (requiring the RFC 7469 backup pin). The pin binds the certificate's long-term key, not the ephemeral post-quantum key-exchange group. · *The self-update verifier accepts the release-signing ECDSA form* — b.selfUpdate.verify delegated to an algorithm-agnostic verify that, for an EC P-384 key, pinned neither the SHA3-512 digest nor the raw IEEE-P1363 signature encoding the release pipeline emits -- so a sidecar signed the way the standalone verifier and install script expect only verified through that standalone path, even inside a fully-installed framework. verify now routes through the same streaming SHA3-512 / DER-or-P1363 verifier, collapsing the two into one acceptance set and dropping the whole-asset in-memory buffer.
+
 - v0.17.12 (2026-07-22) — **The vendored Public Suffix List is refreshed to the current upstream snapshot.** The vendored Mozilla Public Suffix List is updated to the current upstream build, so organizational-domain derivation for DMARC identifier alignment, BIMI issuer scoping, cookie-scope confinement, and same-site policy reflects the current registry delegations. The data module is regenerated and re-signed across all four integrity layers, the manifest hashes are refreshed, and the NOTICE attribution date is updated. **Security:** *Public Suffix List refreshed to the current upstream snapshot* — The vendored Mozilla Public Suffix List is updated to the current upstream snapshot, so organizational-domain derivation reflects the current registry delegations everywhere the framework draws a registrable-domain boundary -- DMARC identifier alignment, BIMI issuer scoping, cookie-scope confinement, and same-site policy. The precise upstream commit and version are recorded in the signed data file and the vendor manifest. The .data.js carrier is regenerated and re-signed across all four integrity layers (SHA-256 + SHA3-512 + SLH-DSA-SHAKE-256f signature + in-payload canary), the manifest hashes are refreshed, and the NOTICE attribution date is updated.
 
 - v0.17.11 (2026-07-17) — **The DER decoder rejects a non-minimal length encoding, and the OAuth client-attestation verifier pins the JWT type so a JWT minted for another purpose can't be replayed into the attestation slot.** The shared ASN.1 DER decoder accepted a non-minimal long-form length encoding (a long form used for a value that fits the short form, or a length carrying a leading-zero octet), a BER/DER parser-differential an attacker could use to smuggle an alternate encoding of a certificate, CMS structure, or OCSP response past the strict decoder. And the OAuth client-attestation verifier did not pin the JOSE type header of the attestation and proof-of-possession JWTs, so a JWT minted for another purpose but signed by the same key could be replayed into the attestation slot. **Security:** *DER decoder rejects a non-minimal length encoding* — b.asn1Der is the shared DER reader every certificate, CMS, and OCSP parse in the framework routes through. X.690 §10.1 requires the minimum number of length octets: the long form may be used only for lengths of 128 or more, and must carry no leading-zero octet. The decoder accepted both non-minimal forms -- a long-form length for a value that fits the short form, and a long-form length with a leading zero -- which is a BER/DER parser-differential an attacker can use to encode the same structure two ways and slip an alternate encoding past a strict verifier that canonicalizes differently. The decoder already refused every other BER-ism it encounters (indefinite-length, non-minimal OID sub-identifiers, non-minimal high-tag-number tags); it now also refuses a non-minimal length, closing the remaining differential. · *OAuth client-attestation verifier pins the JWT type* — b.auth.oauth's attestation-based client authentication (draft-ietf-oauth-attestation-based-client-auth) verifies two JWTs -- the client-attestation JWT and its proof-of-possession JWT -- each of which carries a REQUIRED, distinct JOSE type header (oauth-client-attestation+jwt and oauth-client-attestation-pop+jwt). The verifier checked the signature and claims but not the type header, so a JWT minted for a different purpose but signed by the same key -- a private_key_jwt client assertion, or the other proof-of-possession JWT -- could be replayed into the attestation or PoP slot (the cross-JWT confused-deputy class RFC 8725 §3.11 explicit typing defends against). The verifier now pins the expected type for each slot, and the builders emit the same literals so a produced and a checked type can never drift; the framework's DPoP and back-channel-logout JWT verifiers already pin their type, and the attestation verifier now matches.

package/NOTICE

@@ -90,7 +90,7 @@ Used for:    Top-10000 most-common (breach-derived) passwords. Loaded by
              baseline.
 --------------------------------------------------------------------------------
 Component:   publicsuffix-list (Mozilla Public Suffix List)
-Version:     master snapshot (bundled 2026-07-22)
+Version:     master snapshot (bundled 2026-07-23)
 Source:      https://publicsuffix.org/list/public_suffix_list.dat
 License:     MPL-2.0
 Copyright:   Copyright (c) Mozilla Foundation and Public Suffix List contributors

package/index.js

@@ -128,6 +128,7 @@ var sql = require("./lib/sql");
 var chainWriter = require("./lib/chain-writer");
 var codepointClass = require("./lib/codepoint-class");
 var safeBuffer = require("./lib/safe-buffer");
+var safeObject = require("./lib/safe-object");
 var safeDecompress = require("./lib/safe-decompress").safeDecompress;
 var safeMountInfo = require("./lib/safe-mount-info");
 var lazyRequire = require("./lib/lazy-require");
@@ -539,6 +540,7 @@ module.exports = {
   chainWriter:      chainWriter,
   codepointClass:   codepointClass,
   safeBuffer:       safeBuffer,
+  safeObject:       safeObject,
   safeDecompress:   safeDecompress,
   safeMountInfo:    safeMountInfo,
   lazyRequire:      lazyRequire,

package/lib/app-shutdown.js

@@ -45,6 +45,7 @@
 
 var safeAsync = require("./safe-async");
 var numericBounds = require("./numeric-bounds");
+var pidProbe = require("./pid-probe");
 var validateOpts = require("./validate-opts");
 var tracing = null;
 try { tracing = require("./tracing"); } catch (_e) { /* tracing optional */ }
@@ -547,35 +548,37 @@ function pidLock(lockPath) {
   var fd = null;
   var ownsLock = false;
 
-  function _isLivePid(pid) {
-    if (!pid || pid <= 0) return false;
-    try { process.kill(pid, 0); return true; }                                            // signal 0 = existence-check
-    catch (e) { return e.code === "EPERM"; }                                              // EPERM means process exists, just no rights
-  }
-
-  function _readExisting() {
-    try {
-      // fd-safe + capped + symlink-refusing read: a PID lockfile is never a
-      // legitimate symlink (unlike a k8s/certbot secret mount), so refuseSymlink
-      // is safe here and stops a planted symlink/oversized file from redirecting
-      // or OOM-ing the read. Any throw (symlink/too-large/enoent) → null, the
-      // existing "no live lock" semantic.
-      var raw = atomicFile.fdSafeReadSync(lockPath, { maxBytes: C.BYTES.kib(1), refuseSymlink: true, encoding: "utf8" });
-      var pid = parseInt(String(raw).trim(), 10);
-      return isFinite(pid) && pid > 0 ? pid : null;
-    } catch (_e) { return null; }
-  }
+  // Signal-0 liveness probe + fd-safe pidfile reader are the shared
+  // lib/pid-probe primitive (b.daemon carried a byte-identical copy).
+  function _readExisting() { return pidProbe.readPidFile(lockPath); }
 
   function acquire() {
     if (ownsLock) return;
     nodeFs.mkdirSync(nodePath.dirname(lockPath), { recursive: true });
     var existing = _readExisting();
-    if (existing && _isLivePid(existing) && existing !== process.pid) {
+    if (existing && pidProbe.isLivePid(existing) && existing !== process.pid) {
       throw new AppShutdownError("app-shutdown/pidlock-held",
         "pidLock: '" + lockPath + "' already held by live PID " + existing);
     }
+    if (existing === process.pid) {
+      // The lockfile already records OUR PID — a parent wrote it and handed off,
+      // or start() re-acquires after leaving its own live pidfile. ADOPT the
+      // existing inode in place: the reap path below would unlink + O_EXCL-
+      // recreate, opening a no-pidfile window a concurrent daemon.stop misreads
+      // as "no-pidfile". openNoFollowSync holds the inode (a symlink at lockPath
+      // is refused with ELOOP) so we own the lock without ever removing the
+      // file. release() closes this fd + unlinks as usual.
+      try {
+        fd = atomicFile.openNoFollowSync(lockPath);
+      } catch (e) {
+        throw new AppShutdownError("app-shutdown/pidlock-open-failed",
+          "pidLock: failed to adopt self-held '" + lockPath + "': " + e.message);
+      }
+      ownsLock = true;
+      return;
+    }
     if (existing) {
-      // Stale lock — owner is dead. Reap.
+      // Stale lock — owner is dead (foreign PID that is no longer live). Reap.
       try { nodeFs.unlinkSync(lockPath); } catch (_e) { /* race: someone else reaped it */ }
     }
     try {

package/lib/audit.js

@@ -1799,12 +1799,14 @@ function generateActorBindingTriggerSql(opts) {
   // so operator-supplied opts.column / opts.tableName / opts.roleMappingFn
   // can't reach raw concatenation. PostgreSQL + SQLite both use the
   // double-quote dialect.
-  var qColumn   = safeSql.quoteIdentifier(columnRaw, "postgres");
-  var qTable    = safeSql.quoteIdentifier(tableNameRaw, "postgres");
-  var qFn       = safeSql.quoteIdentifier(fnNameRaw, "postgres");
-  var qTrig     = safeSql.quoteIdentifier(trigNameRaw, "postgres");
+  // allowReserved: parity with b.db.from() — an operator column/table/function
+  // named as a SQL keyword must quote here too (safe once quoted).
+  var qColumn   = safeSql.quoteIdentifier(columnRaw, "postgres", { allowReserved: true });
+  var qTable    = safeSql.quoteIdentifier(tableNameRaw, "postgres", { allowReserved: true });
+  var qFn       = safeSql.quoteIdentifier(fnNameRaw, "postgres", { allowReserved: true });
+  var qTrig     = safeSql.quoteIdentifier(trigNameRaw, "postgres", { allowReserved: true });
   var qRoleMapFn = opts.roleMappingFn
-    ? safeSql.quoteIdentifier(opts.roleMappingFn, "postgres")
+    ? safeSql.quoteIdentifier(opts.roleMappingFn, "postgres", { allowReserved: true })
     : null;
   var allowList = allowRoles.length === 0 ? "" :
     "  IF current_user IN (" +

package/lib/content-digest.js

@@ -32,6 +32,7 @@
 var nodeCrypto = require("node:crypto");
 var bCrypto = require("./crypto");
 var safeBuffer = require("./safe-buffer");
+var safeObject = require("./safe-object");
 var structuredFields = require("./structured-fields");
 var validateOpts = require("./validate-opts");
 var { defineClass } = require("./framework-error");
@@ -104,7 +105,7 @@ function create(body, opts) {
     // hasOwnProperty: the algorithm name is operator/caller input; a bracket
     // lookup lets "constructor"/"toString" inherit a truthy value off the
     // prototype and pass the support check (proto shadowing).
-    var nodeAlg = Object.prototype.hasOwnProperty.call(ACTIVE, name) ? ACTIVE[name] : undefined;
+    var nodeAlg = safeObject.ownProp(ACTIVE, name);
     if (!nodeAlg) {
       if (Object.prototype.hasOwnProperty.call(DEPRECATED, name)) throw new ContentDigestError("content-digest/insecure-algorithm", "contentDigest.create: '" + name + "' is a deprecated/insecure digest algorithm (RFC 9530 §6); use sha-256 or sha-512");
       throw new ContentDigestError("content-digest/unsupported-algorithm", "contentDigest.create: unsupported digest algorithm '" + name + "'");

package/lib/crypto.js

@@ -68,6 +68,10 @@ var safeBuffer  = lazyRequire(function () { return require("./safe-buffer"); });
 // pqc-software requires this module (b.crypto) — lazy-load to break the
 // cycle. Only the power-on self-test needs it here.
 var pqcSoftware = lazyRequire(function () { return require("./pqc-software"); });
+// network-tls requires this module (b.crypto) at top-of-file — lazy-load
+// to break the cycle. Only spkiPinVerifier composes its RFC 9525 strict
+// hostname/SAN matcher.
+var networkTls  = lazyRequire(function () { return require("./network-tls"); });
 
 // Streaming-hash algorithm allowlist. Mirrors the framework's PQC-
 // first crypto policy: SHA3 / SHAKE family is the default surface;
@@ -198,19 +202,38 @@ function _hashFileMulti(filePath, algorithms, opts) {
     var st;
     try { st = nodeFs.lstatSync(filePath); }
     catch (statErr) {
-      reject(new Error("crypto.hashFilesParallel: stat failed for '" +
-        filePath + "': " + (statErr && statErr.message ? statErr.message : String(statErr))));
+      // Preserve the underlying fs error metadata (.code / .errno /
+      // .syscall / .path) so callers branch on ENOENT vs EACCES vs
+      // ELOOP rather than string-matching the wrapped message. The
+      // mid-read `stream.on("error", reject)` path below rejects the
+      // raw fs error and already carries .code; wrapping the pre-open
+      // stat error WITHOUT copying it forward made the observable
+      // failure shape nondeterministic by timing. Match atomic-file's
+      // posture of surfacing the raw fs code on the ENOENT-class path.
+      var statWrapped = new Error("crypto.hashFilesParallel: stat failed for '" +
+        filePath + "': " + (statErr && statErr.message ? statErr.message : String(statErr)));
+      if (statErr) {
+        statWrapped.code    = statErr.code;
+        statWrapped.errno   = statErr.errno;
+        statWrapped.syscall = statErr.syscall;
+        statWrapped.cause   = statErr;
+      }
+      statWrapped.path = filePath;
+      reject(statWrapped);
       return;
     }
     if (st.isSymbolicLink() && !followSymlink) {
-      reject(new Error("crypto.hashFilesParallel: refusing symlink '" +
+      var symErr = new Error("crypto.hashFilesParallel: refusing symlink '" +
         filePath + "' — pass {followSymlinks: true} to opt in (an attacker " +
         "with write access to the input list can otherwise direct the hasher " +
-        "to files the caller cannot read directly)"));
+        "to files the caller cannot read directly)");
+      symErr.code = "crypto/hash-refused-symlink";
+      symErr.path = filePath;
+      reject(symErr);
       return;
     }
     if (!st.isFile() && !st.isSymbolicLink()) {
-      reject(new Error("crypto.hashFilesParallel: refusing non-regular file '" +
+      var nonRegularErr = new Error("crypto.hashFilesParallel: refusing non-regular file '" +
         filePath + "' (FIFOs / sockets / character / block devices read indefinitely " +
         "or return platform-undefined bytes; hashing them is meaningless and " +
         "DoS-prone). Type: " +
@@ -218,7 +241,10 @@ function _hashFileMulti(filePath, algorithms, opts) {
          st.isSocket() ? "socket" :
          st.isBlockDevice() ? "block-device" :
          st.isCharacterDevice() ? "char-device" :
-         st.isDirectory() ? "directory" : "unknown")));
+         st.isDirectory() ? "directory" : "unknown"));
+      nonRegularErr.code = "crypto/hash-refused-non-regular-file";
+      nonRegularErr.path = filePath;
+      reject(nonRegularErr);
       return;
     }
     var hashers = new Array(algorithms.length);
@@ -240,9 +266,12 @@ function _hashFileMulti(filePath, algorithms, opts) {
       if (maxBytes && byteLength > maxBytes) {
         aborted = true;
         try { stream.destroy(); } catch (_e) { /* best-effort */ }
-        reject(new Error("crypto.hashFilesParallel: file '" + filePath +
+        var maxBytesErr = new Error("crypto.hashFilesParallel: file '" + filePath +
           "' exceeded opts.maxBytesPerFile (" + maxBytes +
-          " bytes); refusing to continue hashing"));
+          " bytes); refusing to continue hashing");
+        maxBytesErr.code = "crypto/hash-max-bytes-exceeded";
+        maxBytesErr.path = filePath;
+        reject(maxBytesErr);
         return;
       }
       for (var j = 0; j < hashers.length; j += 1) hashers[j].update(chunk);
@@ -2042,6 +2071,219 @@ function isCertRevoked(pemOrDer, denyList) {
   return false;
 }
 
+// ---- RFC 7469 SubjectPublicKeyInfo pinning ----
+//
+// The pin is base64(SHA-256(SPKI DER)) — RFC 7469 §2.4 / HPKP. This
+// deliberately uses SHA-256, which is otherwise absent from the b.crypto
+// surface (see the @module intro): it is an interop WIRE CONSTANT, not a
+// framework hashing choice. Browsers, curl `--pinnedpubkey sha256//...`,
+// OpenSSL, and every HPKP-style pin store speak SHA-256(SPKI); a SHA3-512
+// pin would not interoperate with any of them. `hashCertFingerprint`
+// documents the same "framework-canonical hash vs interop rendering"
+// split. The pin binds the certificate's LONG-TERM SubjectPublicKeyInfo
+// (which survives certificate reissue on the same key) — it says nothing
+// about the ephemeral PQC TLS key-exchange group negotiated per
+// handshake; those are orthogonal (identity of the peer key vs secrecy
+// of the session).
+var SPKI_PIN_PREFIX = "sha256/";
+
+// Decode a `sha256/<base64>` pin string into its raw 32-byte digest
+// Buffer, throwing a TypeError on any malformed entry (config-time /
+// entry-point tier — the operator catches the typo at construction).
+function _decodeSpkiPin(pinStr, ctx) {
+  if (typeof pinStr !== "string" || pinStr.length === 0) {
+    throw new TypeError(ctx + ": each pin must be a non-empty 'sha256/<base64>' string");
+  }
+  if (pinStr.indexOf(SPKI_PIN_PREFIX) !== 0) {
+    throw new TypeError(ctx + ": pin '" + pinStr +
+      "' must carry the RFC 7469 'sha256/' prefix");
+  }
+  var body = pinStr.slice(SPKI_PIN_PREFIX.length);
+  var buf = Buffer.from(body, "base64");
+  // SHA-256 digest = 32 bytes; require a canonical base64 round-trip so a
+  // silently-truncated / non-canonical body is refused rather than
+  // matching a shorter buffer.
+  if (buf.length !== 32 || buf.toString("base64") !== body) {
+    throw new TypeError(ctx + ": pin '" + pinStr +
+      "' must be base64 of a 32-byte SHA-256 SPKI digest");
+  }
+  return buf;
+}
+
+/**
+ * @primitive b.crypto.spkiPin
+ * @signature b.crypto.spkiPin(pemOrDer)
+ * @since     0.17.13
+ * @status    stable
+ * @related   b.crypto.spkiPinVerifier, b.crypto.hashCertFingerprint
+ *
+ * Computes the RFC 7469 (HPKP §2.4) public-key pin of an X.509
+ * certificate: `base64(SHA-256(SubjectPublicKeyInfo DER))`. Accepts DER
+ * bytes (Buffer) or a PEM string (BEGIN/END envelope stripped, base64
+ * body decoded — same 64 KiB ReDoS cap as `hashCertFingerprint`).
+ * Returns `{ sha256, b64, hex }`: `sha256` is the `sha256/<base64>` wire
+ * form browsers and `curl --pinnedpubkey` render, `b64` the bare base64
+ * body, `hex` the lowercase-hex digest.
+ *
+ * Unlike `hashCertFingerprint` (SHA3-512 over the WHOLE certificate), an
+ * SPKI pin binds only the public key, so it survives certificate reissue
+ * on the same key pair — the property RFC 7469 pinning relies on.
+ *
+ * This is the one place SHA-256 appears on the b.crypto surface: it is an
+ * RFC 7469 interop wire constant (browsers / curl / OpenSSL pin stores),
+ * not a framework hashing default. The pin binds the peer's long-term
+ * SPKI, not the ephemeral PQC key-exchange group negotiated per TLS
+ * handshake.
+ *
+ * @example
+ *   var fs  = require("fs");
+ *   var pem = fs.readFileSync("/etc/ssl/peer.cert.pem", "utf8");
+ *   var pin = b.crypto.spkiPin(pem);
+ *   pin.sha256;
+ *   // → "sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg="
+ */
+function spkiPin(pemOrDer) {
+  var der = _pemToDer(pemOrDer);
+  // SubjectPublicKeyInfo DER — the exact bytes RFC 7469 §2.4 hashes.
+  var spkiDer = new nodeCrypto.X509Certificate(der)
+    .publicKey.export({ type: "spki", format: "der" });
+  var digest = nodeCrypto.createHash("sha256").update(spkiDer).digest();
+  var b64 = digest.toString("base64");
+  return { sha256: SPKI_PIN_PREFIX + b64, b64: b64, hex: digest.toString("hex") };
+}
+
+/**
+ * @primitive b.crypto.spkiPinVerifier
+ * @signature b.crypto.spkiPinVerifier(opts)
+ * @since     0.17.13
+ * @status    stable
+ * @related   b.crypto.spkiPin, b.network.tls.checkServerIdentity9525
+ *
+ * Builds a `tls.checkServerIdentity`-compatible `(host, cert) =>
+ * Error | undefined` that enforces RFC 7469 public-key pinning on top of
+ * RFC 9525 strict hostname verification. Pass the returned function as
+ * `tls.connect({ checkServerIdentity })`.
+ *
+ * The verifier runs hostname/SAN identity FIRST (via
+ * `b.network.tls.checkServerIdentity9525` — SAN-required, no Common Name
+ * fallback), so a pin match on a certificate issued for the wrong name is
+ * still refused. Only when identity passes does it derive the peer's SPKI
+ * pin from the presented DER and constant-time-compare
+ * (`crypto.timingSafeEqual`) it against every configured pin. Returns the
+ * identity `Error` on a hostname/SAN failure, an `Error` with code
+ * `crypto/spki-pin-mismatch` when no pin matches, or `undefined` when
+ * both identity and pin check out.
+ *
+ * `opts.pins` MUST be an array of at least two `sha256/<base64>` pins:
+ * RFC 7469 §4.3 requires a backup pin corresponding to a key not in the
+ * current chain so key rotation does not brick the pinned endpoint. When
+ * `opts.hostname` is set, the certificate identity is checked against it
+ * instead of the host argument Node supplies — pin the expected name
+ * explicitly. Produce pin strings with `b.crypto.spkiPin(...).sha256`.
+ *
+ * @opts
+ *   pins:      string[],  // required — >= 2 'sha256/<base64>' pins (RFC 7469 backup-pin rule)
+ *   hostname:  string,    // optional — verify cert identity against this name instead of the host arg
+ *
+ * @example
+ *   var tls    = require("node:tls");
+ *   var verify = b.crypto.spkiPinVerifier({
+ *     pins: [
+ *       "sha256/YLh1dUR9y6Kja30RrAn7JKnbQG/uEtLMkBgFF2Fuihg=",
+ *       "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",   // backup key
+ *     ],
+ *   });
+ *   var sock = tls.connect({
+ *     host: "api.example.com",
+ *     port: 443,
+ *     checkServerIdentity: verify,
+ *   });
+ */
+function spkiPinVerifier(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new TypeError("crypto.spkiPinVerifier: opts is required");
+  }
+  if (!Array.isArray(opts.pins)) {
+    throw new TypeError(
+      "crypto.spkiPinVerifier: opts.pins must be an array of 'sha256/<base64>' pins"
+    );
+  }
+  // RFC 7469 §4.3 requires a backup pin corresponding to a key NOT in the
+  // current chain. Two IDENTICAL pins are not a backup (the same key repeated),
+  // so require at least two DISTINCT pins — a length-only check would accept a
+  // duplicate and silently leave the endpoint with no rotation key.
+  var distinctPins = [];
+  for (var dpi = 0; dpi < opts.pins.length; dpi += 1) {
+    if (distinctPins.indexOf(opts.pins[dpi]) === -1) distinctPins.push(opts.pins[dpi]);
+  }
+  if (distinctPins.length < 2) {
+    throw new TypeError(
+      "crypto.spkiPinVerifier: opts.pins must contain at least two DISTINCT " +
+      "'sha256/<base64>' pins — RFC 7469 §4.3 requires a backup pin " +
+      "corresponding to a key not in the current chain so key rotation " +
+      "does not brick the pinned endpoint"
+    );
+  }
+  var pinBufs = new Array(distinctPins.length);
+  for (var pi = 0; pi < distinctPins.length; pi += 1) {
+    pinBufs[pi] = _decodeSpkiPin(distinctPins[pi], "crypto.spkiPinVerifier");
+  }
+  var expectedHost = opts.hostname;
+  if (expectedHost !== undefined &&
+      (typeof expectedHost !== "string" || expectedHost.length === 0)) {
+    throw new TypeError(
+      "crypto.spkiPinVerifier: opts.hostname must be a non-empty string when supplied"
+    );
+  }
+  return function verifySpkiPin(host, cert) {
+    // Identity (hostname / SAN) FIRST — a pin match on a cert issued for
+    // the wrong name is still impersonation. checkServerIdentity9525 is
+    // RFC 9525 strict (SAN-required, no CN fallback) and returns
+    // Error | undefined.
+    var effectiveHost = expectedHost !== undefined ? expectedHost : host;
+    var identityError = networkTls().checkServerIdentity9525(effectiveHost, cert);
+    if (identityError) return identityError;
+    // Peer SPKI pin — hash the DER the peer actually presented. Node's
+    // detailed cert object exposes the raw DER as cert.raw.
+    if (!cert || !Buffer.isBuffer(cert.raw)) {
+      var noDerErr = new Error(
+        "crypto.spkiPinVerifier: peer cert object carries no DER `raw` bytes to pin"
+      );
+      noDerErr.code = "crypto/spki-pin-no-peer-der";
+      return noDerErr;
+    }
+    var peerBuf;
+    try {
+      peerBuf = Buffer.from(spkiPin(cert.raw).b64, "base64");
+    } catch (parseErr) {
+      var peerErr = new Error(
+        "crypto.spkiPinVerifier: failed to derive peer SPKI pin (" +
+        (parseErr && parseErr.message ? parseErr.message : String(parseErr)) + ")"
+      );
+      peerErr.code = "crypto/spki-pin-peer-parse-failed";
+      return peerErr;
+    }
+    var matched = false;
+    for (var mi = 0; mi < pinBufs.length; mi += 1) {
+      // No early exit — comparing against every pin keeps the match
+      // timing from leaking which configured pin matched.
+      if (peerBuf.length === pinBufs[mi].length &&
+          nodeCrypto.timingSafeEqual(peerBuf, pinBufs[mi])) {
+        matched = true;
+      }
+    }
+    if (!matched) {
+      var mismatchErr = new Error(
+        "crypto.spkiPinVerifier: peer SPKI pin (" + SPKI_PIN_PREFIX +
+        peerBuf.toString("base64") + ") does not match any configured pin"
+      );
+      mismatchErr.code = "crypto/spki-pin-mismatch";
+      return mismatchErr;
+    }
+    return undefined;
+  };
+}
+
 var SUPPORTED_KEM_ALGORITHMS = Object.freeze([
   { id: "ml-kem-1024",          envelopeId: C.KEM_IDS.ML_KEM_1024,        description: "ML-KEM-1024 KEM-only (legacy single-component)" },
   { id: "ml-kem-1024-p384",     envelopeId: C.KEM_IDS.ML_KEM_1024_P384,   description: "ML-KEM-1024 + ECDH P-384 hybrid (framework default)" },
@@ -2191,6 +2433,8 @@ module.exports = {
   // Cert fingerprint helpers
   hashCertFingerprint:         hashCertFingerprint,
   isCertRevoked:               isCertRevoked,
+  spkiPin:                     spkiPin,
+  spkiPinVerifier:             spkiPinVerifier,
   // Random
   generateBytes:               generateBytes,
   generateToken:               generateToken,