@blamejs/core 0.15.20 → 0.15.21

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.15.x
 
+- v0.15.21 (2026-06-24) — **Adds a portable compare-and-swap UPDATE, an IPv6 /64 rate-limit key, a verify-only legacy-TOTP path, request-id AsyncLocalStorage scoping, schema-agnostic backup signing, side-effect-free FSM transition resolution, and the public codepoint-threat catalog — and fixes an FSM state transition that committed without an audit record when its entry hook threw.** A batch of additive primitives that close gaps operators hit composing the framework: b.sql.guardedUpdate builds the cross-instance-safe compare-and-swap UPDATE (the conditional-INSERT sibling) with b.sql.casWon reading the won/lost result; b.requestHelpers.ipKey (and a rateLimit ipKeyMode) key an IPv6 client by its routing-significant /64 so one end-site can't rotate the low 64 bits to evade a per-IP limit; b.auth.totp gains an opt-in verify-only SHA-1 path for one-final-login legacy-secret migration while generation stays SHA-512-only; b.middleware.requestId can bind the id into an AsyncLocalStorage scope that survives the awaited route chain; b.backupManifest.signBytes/verifyBytes authenticate a consumer's own canonical bytes with the framework signing key; b.fsm gains a side-effect-free instance.target() and a way to defer its transition audit when composed with an external claim; and the codepoint-threat catalog the guard family composes is exposed as b.codepointClass. A correctness fix: an FSM transition whose onEnter hook threw left the state committed but emitted no audit record — the record now always fires (stamped a failure outcome with the hook error) so a state change is never unaudited. **Added:** *b.sql.guardedUpdate + b.sql.casWon — portable compare-and-swap UPDATE* — b.sql.guardedUpdate(table) builds an UPDATE whose required guardWhere(col, expected) fence makes it land only when the row is still in the expected value — the cross-instance-safe way to advance a status or version on a single-statement-per-request backend (a D1-over-HTTP bridge or any autocommit-only adapter without interactive transactions), and the conditional-UPDATE sibling of b.sql.insertSelectWhere. It refuses to render without a fence (an unfenced guardedUpdate is just a plain update). b.sql.casWon(result) reads the won/lost verdict from the affected-row count, normalizing the rowCount / changes / affectedRows field-name divergence across adapters and throwing on an indeterminate result so a phantom win can't ship. Standard SQL across SQLite / Postgres / MySQL; guardWhereOp(col, op, expected) supports a non-equality fence (an optimistic-version or balance guard), and a null fence renders IS NULL. · *b.requestHelpers.ipKey + rateLimit ipKeyMode — IPv6 /64 keying* — b.requestHelpers.ipKey(ip, { ipv6Bits }) derives a stable rate-limit / blocklist key: an IPv4 address verbatim (one IPv4 is one host) but an IPv6 address collapsed to its routing-significant /64 prefix. A single IPv6 end-site is allocated a whole /64 (RFC 6177 / RFC 4291) and freely rotates the low 64 bits, so keying on the full 128-bit address lets one site mint unlimited fresh keys and walk a per-IP throttle or evade an exact-address block; keying on the /64 closes that while still distinguishing real end-sites. b.middleware.rateLimit gains ipKeyMode: "prefix64" to apply this to its default key (the audit record still logs the full client IP). · *b.auth.totp verify-only SHA-1 path for legacy-secret migration* — b.auth.totp.verify(secret, code, { algorithm: "sha1", verifyOnly: true }) authenticates a single legacy code during a re-enrollment flow, so a consumer migrating pre-existing RFC-6238-default (SHA-1) secrets can reuse the maintained verifier — separator stripping, 64-bit counter, drift / replay semantics — instead of hand-rolling a parallel HOTP. SHA-1 is still refused on every generation path (compute / generate / uri), so new-enrollment posture stays SHA-512-only, and the flag is honored only by verify(); each such verification emits an auth.totp.legacy_sha1_verify audit signal. · *b.middleware.requestId AsyncLocalStorage scoping* — b.middleware.requestId({ asyncContext: true }) binds the request id into the framework's AsyncLocalStorage scope so b.log.getRequestId() (and every b.log.create-built logger) returns it inside awaited route-handler code, not just on req.requestId. Because the b.router dispatch model runs the route handler after the middleware returns, the binding uses AsyncLocalStorage.enterWith (which persists forward across the awaited chain) rather than a callback wrap that would close before the handler runs; each request runs in its own async context so the binding stays request-scoped. The underlying b.log.enterRequestId(id) is exposed for callers wiring their own middleware. · *b.backupManifest.signBytes / verifyBytes — schema-agnostic signing* — b.backupManifest.signBytes(canonicalBytes) and verifyBytes(canonicalBytes, signatureBlock, { expectedFingerprint }) sign and verify a consumer's own canonical bytes with the same audit-sign keypair and fingerprint pinning as the v1-manifest sign() / verifySignature(), without adopting the framework's manifest schema — so a bespoke backup-header format can authenticate itself against the framework signing key. Fingerprint pinning is bound to the key the signature actually verifies under: the pin is checked against the fingerprint recomputed from the signature block's own public key (the new b.auditSign.fingerprintOf(publicKeyPem) helper), not the block's self-asserted fingerprint field, so a block can't claim a trusted fingerprint while being signed by a different key. The same binding now also applies to the v1-manifest verifySignature(). b.auditSign.verify additionally no longer requires init() when given an explicit public key, so a downstream verifier that holds only a trusted public key can check a detached signature. · *b.fsm side-effect-free transition resolution + deferrable audit* — instance.target(event) resolves a transition's destination state side-effect-free — the same edge and guard check as can() but returning the to-state (or null when the edge is illegal or guard-refused) — so a consumer composing an external compare-and-swap (b.sql.guardedUpdate on an autocommit-only substrate) can build the SET status = <to> claim without calling transition(), which would mutate state and emit an audit before the cross-instance claim is known to land. transition(event, { audit: false }) suppresses the built-in emit so that composition can emit its own enriched record once the claim resolves. · *b.codepointClass — the codepoint-threat catalog on the public surface* — The Unicode bidi-override / C0-control / zero-width / null-byte / Unicode-Tags tables and the UTS #39 confusable-script detector that the b.guard* family composes internally are now exposed as b.codepointClass, so a consumer can build a custom unconstrained-free-text screen — detectCharThreats / assertNoCharThreats / applyCharStripPolicies / scriptFor / detectMixedScripts plus the compiled regexes — without re-rolling the regexes (where the zero-width class is mistyped and the astral Unicode-Tags block forgotten) or coupling to an internal module path. For a ready-made free-text guard, b.guardText remains the first-class entry point. **Fixed:** *An FSM transition committed its state change without an audit record when the entry hook threw* — b.fsm commits the new state and pushes the history entry before running the destination state's onEnter hook. When that hook threw, control skipped the audit emission entirely — leaving a committed state transition with no audit record, a compliance gap for any regime that requires state changes to be auditable. The transition audit now always fires even when onEnter throws: it records the committed transition stamped with a failure outcome and the hook error, and still re-raises the error to the caller (the documented contract that an onEnter throw surfaces so the operator can roll back is unchanged).
+
 - v0.15.20 (2026-06-24) — **Vendored SBOM version fields are derived from the bundle so they cannot drift, and the Public Suffix List + @simplewebauthn/server bundles are refreshed.** The vendor manifest recorded each bundled package's version in two scanner-facing places that were hand-maintained and could drift from the code actually shipped — the structured components[].version (the CycloneDX component versions) and the cpe string. Two had drifted: peculiar-pki's @peculiar/x509 component read 1.13.0 while the bundle shipped 2.0.0, and @noble/curves' cpe read 0.0.0 while the bundle shipped 2.2.0. A CVE scanner (Trivy / Grype / a CycloneDX export, or a consumer mirroring the manifest into its own SBOM) keys on those structured fields, so an advisory was matched against the wrong version — a false negative on a real fix or a false positive on a patched one. Both fields are corrected, the vendor-bundle script now derives them from the actually-installed package versions at bundle time so they cannot drift again, and a manifest gate fails the build if they ever disagree. Separately, the vendored Mozilla Public Suffix List is refreshed to the current upstream revision and @simplewebauthn/server is refreshed to 13.3.2. **Changed:** *Vendored Public Suffix List and @simplewebauthn/server refreshed* — The vendored Mozilla Public Suffix List is refreshed to the current upstream revision (used by b.publicSuffix for DMARC / BIMI / cookie-scope / same-site domain classification). @simplewebauthn/server is refreshed from 13.3.1 to 13.3.2, which improves WebAuthn attestation certificate-path validation; the published-tarball diff was reviewed (no install scripts, no network/eval, a self-contained code change) before re-vendoring. **Fixed:** *Vendored SBOM version metadata is bundle-derived, not hand-maintained* — lib/vendor/MANIFEST.json recorded each package's version in two places a CVE/SBOM scanner reads — the structured components[].version sub-object and the cpe string — both hand-maintained alongside the human version string, so they could (and did) drift from the bundled code. @peculiar/x509's component version read 1.13.0 while the bundle shipped 2.0.0; @noble/curves' cpe read 0.0.0 while the bundle shipped 2.2.0. Either drift makes a scanner match advisories against the wrong version. Both are corrected to the shipped versions, and the durable fix is structural: scripts/vendor-update.sh now writes both the structured component versions and the cpe version from the ACTUALLY-INSTALLED package versions captured at bundle time, so a maintainer can no longer update one field and forget the other. A smoke-time manifest gate additionally fails the build if any component or cpe version disagrees with the package version, catching a manual drift before it ships.
 
 - v0.15.19 (2026-06-22) — **Restores the wiki container build by keeping its base image on the continuously-patched rolling tag.** A follow-up to 0.15.18. The framework code is unchanged from 0.15.18 — this patch reverts one part of that release's supply-chain pass: the example wiki container's Chainguard base images had been pinned to specific digests, but Chainguard rebuilds those images continuously to ship CVE fixes, so the frozen digest fell behind an upstream fix within hours and the container's Trivy CRITICAL/HIGH release gate rejected the build (a fixed npm/undici denial-of-service the rolling tag already carried). For a deployed, Trivy-gated image, tracking the rolling, always-patched tag is the correct posture; the wiki Dockerfile is back on it. The ClusterFuzzLite fuzz base (not deployed, not release-gated) stays digest-pinned with Dependabot keeping it current. **Fixed:** *Wiki container builds again on a continuously-patched base* — 0.15.18 digest-pinned the example wiki container's Chainguard base images (runtime + builder). Because Chainguard rebuilds those images continuously to ship CVE fixes, the pinned digest went stale within hours and the container's Trivy CRITICAL/HIGH release gate rejected the build over an already-fixed npm/undici DoS (CVE-2026-12151) the rolling tag carried. The wiki Dockerfile tracks the rolling tag again, so the deployed image is always CVE-current and the build passes the release gate. To keep the Trivy-scanned image identical to the multi-arch image that is published (they are built separately), the release workflow resolves the rolling tag to a digest once at build time and feeds it to both builds via build-args — scan-equals-publish without a committed pin that goes stale. (This trades the OSSF Scorecard PinnedDependencies signal for CVE currency on a deployed, gate-scanned image — the right call here; the non-deployed ClusterFuzzLite fuzz base remains digest-pinned with Dependabot bumping it.) The framework package itself is identical to 0.15.18.

package/index.js

@@ -124,6 +124,7 @@ var handlers = require("./lib/handlers");
 var safeSql = require("./lib/safe-sql");
 var sql = require("./lib/sql");
 var chainWriter = require("./lib/chain-writer");
+var codepointClass = require("./lib/codepoint-class");
 var safeBuffer = require("./lib/safe-buffer");
 var safeDecompress = require("./lib/safe-decompress").safeDecompress;
 var safeMountInfo = require("./lib/safe-mount-info");
@@ -530,6 +531,7 @@ module.exports = {
   safeSql:          safeSql,
   sql:              sql,
   chainWriter:      chainWriter,
+  codepointClass:   codepointClass,
   safeBuffer:       safeBuffer,
   safeDecompress:   safeDecompress,
   safeMountInfo:    safeMountInfo,

package/lib/audit-sign.js

@@ -498,13 +498,45 @@ function sign(payload) {
  *   // → true (when payload + signature were produced under that key)
  */
 function verify(payload, signature, publicKeyPem) {
-  _requireInit();
+  // Only the DEFAULT-key path needs an initialized keypair; when the caller
+  // supplies an explicit publicKeyPem, verification needs no private material
+  // or in-memory key state. Gating init on the absence of publicKeyPem lets a
+  // verifier-only process (one that holds a trusted public key but never ran
+  // init()) verify a detached signature — the path b.backupManifest.verifyBytes
+  // relies on for downstream verifiers.
+  if (!publicKeyPem) _requireInit();
   var buf = Buffer.isBuffer(payload) ? payload : Buffer.from(String(payload), "utf8");
   var sigBuf = Buffer.isBuffer(signature) ? signature : Buffer.from(signature);
   var pub = publicKeyPem || keys.publicKey;
   return nodeCrypto.verify(null, buf, pub, sigBuf);
 }
 
+/**
+ * @primitive b.auditSign.fingerprintOf
+ * @signature b.auditSign.fingerprintOf(publicKeyPem)
+ * @since     0.15.21
+ * @status    stable
+ * @related   b.auditSign.getPublicKeyFingerprint, b.auditSign.verify
+ *
+ * Compute the SHA3-512 fingerprint (lowercase hex) of a SPKI-PEM public key —
+ * the same derivation `getPublicKeyFingerprint()` returns for the active key,
+ * but for any supplied key and WITHOUT requiring `init()`. A verifier pins a
+ * trusted fingerprint and checks it against `fingerprintOf(block.publicKey)`
+ * before trusting a detached signature block, so an attacker can't substitute
+ * their own key while claiming the trusted fingerprint.
+ *
+ * @example
+ *   var fp = b.auditSign.fingerprintOf(block.publicKey);
+ *   if (fp !== trustedFingerprint) throw new Error("untrusted signing key");
+ */
+function fingerprintOf(publicKeyPem) {
+  if (typeof publicKeyPem !== "string" || publicKeyPem.length === 0) {
+    throw new AuditSignError("audit-sign/bad-public-key",
+      "fingerprintOf: publicKeyPem must be a non-empty PEM string");
+  }
+  return _computeFingerprint(publicKeyPem);
+}
+
 /**
  * @primitive b.auditSign.getPublicKey
  * @signature b.auditSign.getPublicKey()
@@ -1073,6 +1105,7 @@ module.exports = {
   getPublicKey:             getPublicKey,
   getPublicKeyFingerprint:  getPublicKeyFingerprint,
   getPublicKeyByFingerprint: getPublicKeyByFingerprint,
+  fingerprintOf:            fingerprintOf,
   getMode:                  getMode,
   getAlgorithm:             getAlgorithm,
   DEFAULT_SIGNING_ALG:      DEFAULT_SIGNING_ALG,

package/lib/backup/manifest.js

@@ -314,47 +314,39 @@ function serialize(manifest) {
 // or SLH-DSA-SHAKE-256f — whichever audit-sign was initialized with).
 // The signature covers the manifest's canonical bytes WITHOUT the
 // signature field; appending it does not change the signed payload.
-function sign(manifest) {
-  var v = validate(manifest);
-  if (!v.ok) {
-    throw new BackupManifestError("backup-manifest/invalid",
-      "sign: " + v.errors.join("; "));
-  }
+// Sign caller-supplied canonical bytes with the audit-sign keypair, returning a
+// detached signature block. Shared by sign() (v1 manifest schema) and
+// signBytes() (schema-agnostic). `payload` is a Buffer (signed verbatim) or a
+// string (signed as UTF-8) — auditSign.sign normalizes both identically.
+function _signPayload(payload, who) {
   var signer = auditSign();
   if (!signer || typeof signer.sign !== "function") {
     throw new BackupManifestError("backup-manifest/no-signer",
-      "sign: audit-sign module is not available; call b.auditSign.init() first");
+      who + ": audit-sign module is not available; call b.auditSign.init() first");
   }
-  var payload = signingPayload(manifest);
   var signatureBytes;
   try { signatureBytes = signer.sign(payload); }
   catch (e) {
     throw new BackupManifestError("backup-manifest/sign-failed",
-      "sign: audit-sign.sign threw: " + ((e && e.message) || String(e)));
+      who + ": audit-sign.sign threw: " + ((e && e.message) || String(e)));
   }
-  manifest.signature = {
+  return {
     algorithm:   signer.getAlgorithm(),
     publicKey:   signer.getPublicKey(),
     fingerprint: signer.getPublicKeyFingerprint(),
     value:       signatureBytes.toString("base64"),
     signedAt:    new Date().toISOString(),
   };
-  return manifest;
 }
 
-// Verify a previously-signed manifest. Returns { ok, reason?,
-// fingerprint? }. Caller policy decides whether a missing or
-// fingerprint-mismatched signature is fatal — verifyManifestSignature
-// in lib/backup/index.js wraps this with operator-facing semantics.
-function verifySignature(manifest, opts) {
+// Verify `payload` against a detached signature block (the shape _signPayload
+// returns). Shared by verifySignature() and verifyBytes(). Returns
+// { ok, reason?, fingerprint? }; enforces opts.expectedFingerprint pinning.
+function _verifyPayloadAgainstBlock(payload, sig, opts) {
   opts = opts || {};
-  if (!manifest || typeof manifest !== "object") {
-    return { ok: false, reason: "manifest must be an object" };
-  }
-  if (!manifest.signature || typeof manifest.signature !== "object") {
-    return { ok: false, reason: "manifest has no signature block" };
+  if (!sig || typeof sig !== "object") {
+    return { ok: false, reason: "signature block must be an object" };
   }
-  var sig = manifest.signature;
   if (typeof sig.algorithm !== "string" || sig.algorithm.length === 0) {
     return { ok: false, reason: "signature.algorithm is required" };
   }
@@ -364,28 +356,50 @@ function verifySignature(manifest, opts) {
   if (typeof sig.value !== "string" || sig.value.length === 0) {
     return { ok: false, reason: "signature.value is required" };
   }
-  // Caller may pin the expected fingerprint — operators tracking key
-  // rotation pass the active audit-sign fingerprint and refuse any
-  // bundle signed under a different historical key.
-  if (typeof opts.expectedFingerprint === "string" &&
-      opts.expectedFingerprint.length > 0 &&
-      sig.fingerprint !== opts.expectedFingerprint) {
-    return {
-      ok: false,
-      reason: "signature.fingerprint=" + sig.fingerprint +
-              " does not match expectedFingerprint=" + opts.expectedFingerprint,
-      fingerprint: sig.fingerprint,
-    };
+  // The fingerprint of the key the signature is ACTUALLY verified under —
+  // recomputed from sig.publicKey, never the block's self-asserted
+  // sig.fingerprint (which an attacker controls). Used for the pin check below
+  // and returned on success so the caller sees the real key, not a claim.
+  var derivedFingerprint = null;
+  try {
+    var signerForFp = auditSign();
+    if (signerForFp && typeof signerForFp.fingerprintOf === "function") {
+      derivedFingerprint = signerForFp.fingerprintOf(sig.publicKey);
+    }
+  } catch (fpErr) {
+    return { ok: false, reason: "could not derive fingerprint from publicKey: " +
+      ((fpErr && fpErr.message) || String(fpErr)) };
+  }
+  // Caller may pin the expected fingerprint — operators tracking key rotation
+  // pass the active audit-sign fingerprint and refuse any payload signed under
+  // a different historical key. CRITICAL: the pin is checked against the
+  // fingerprint RECOMPUTED from the block's own publicKey, NOT the block's
+  // self-asserted `fingerprint` field. An attacker can sign arbitrary bytes
+  // with their own key and set `fingerprint` to the trusted value; binding the
+  // pin to fingerprintOf(publicKey) — the key the signature is actually
+  // verified under — closes that substitution (the signature can only verify
+  // under publicKey, and publicKey must hash to the trusted fingerprint).
+  if (typeof opts.expectedFingerprint === "string" && opts.expectedFingerprint.length > 0) {
+    if (derivedFingerprint === null) {
+      return { ok: false, reason: "fingerprint pinning requires audit-sign.fingerprintOf (unavailable)" };
+    }
+    if (derivedFingerprint !== opts.expectedFingerprint) {
+      return {
+        ok: false,
+        reason: "publicKey fingerprint=" + derivedFingerprint +
+                " does not match expectedFingerprint=" + opts.expectedFingerprint,
+        fingerprint: derivedFingerprint,
+      };
+    }
   }
-  var payload = signingPayload(manifest);
   var sigBuf;
   try { sigBuf = Buffer.from(sig.value, "base64"); }
   catch (_e) {
     return { ok: false, reason: "signature.value is not valid base64" };
   }
-  // Use audit-sign.verify when available (handles algorithm dispatch
-  // identically to the signer); fall back to nodeCrypto.verify for
-  // verifier processes that don't init audit-sign.
+  // Use audit-sign.verify when available (handles algorithm dispatch identically
+  // to the signer); fall back to nodeCrypto.verify for verifier processes that
+  // don't init audit-sign.
   var ok;
   try {
     var signer = auditSign();
@@ -393,23 +407,154 @@ function verifySignature(manifest, opts) {
       ok = signer.verify(payload, sigBuf, sig.publicKey);
     } else {
       ok = require("node:crypto").verify(null,
-        Buffer.from(payload, "utf8"), sig.publicKey, sigBuf);
+        Buffer.isBuffer(payload) ? payload : Buffer.from(payload, "utf8"), sig.publicKey, sigBuf);
     }
   } catch (e) {
     return {
-      ok:           false,
-      reason:       "verify threw: " + ((e && e.message) || String(e)),
-      fingerprint:  sig.fingerprint,
+      ok:          false,
+      reason:      "verify threw: " + ((e && e.message) || String(e)),
+      fingerprint: sig.fingerprint,
     };
   }
   if (!ok) {
     return {
       ok:          false,
       reason:      "signature did not verify under provided publicKey",
-      fingerprint: sig.fingerprint,
+      fingerprint: derivedFingerprint || sig.fingerprint,
     };
   }
-  return { ok: true, fingerprint: sig.fingerprint };
+  // Return the fingerprint of the key the signature actually verified under
+  // (recomputed), not the block's self-asserted value.
+  return { ok: true, fingerprint: derivedFingerprint || sig.fingerprint };
+}
+
+/**
+ * @primitive b.backupManifest.sign
+ * @signature b.backupManifest.sign(manifest)
+ * @since     0.6.0
+ * @status    stable
+ * @related   b.backupManifest.verifySignature, b.backupManifest.signBytes, b.auditSign.sign
+ *
+ * Sign a v1 backup manifest in place with the audit-sign keypair, attaching a
+ * detached `signature` block over the manifest's canonical bytes (the
+ * serialization WITHOUT the signature field, so appending it doesn't change
+ * the signed payload). Validates the manifest against the v1 schema first;
+ * throws `backup-manifest/invalid` on a malformed manifest and
+ * `backup-manifest/no-signer` when `b.auditSign.init()` hasn't run. For a
+ * schema-agnostic alternative see `signBytes`.
+ *
+ * @example
+ *   b.backupManifest.sign(manifest);
+ *   manifest.signature.fingerprint;   // the signing key's fingerprint
+ */
+function sign(manifest) {
+  var v = validate(manifest);
+  if (!v.ok) {
+    throw new BackupManifestError("backup-manifest/invalid",
+      "sign: " + v.errors.join("; "));
+  }
+  manifest.signature = _signPayload(signingPayload(manifest), "sign");
+  return manifest;
+}
+
+/**
+ * @primitive b.backupManifest.signBytes
+ * @signature b.backupManifest.signBytes(canonicalBytes)
+ * @since     0.15.21
+ * @status    stable
+ * @related   b.backupManifest.verifyBytes, b.backupManifest.sign, b.auditSign.sign
+ *
+ * Sign caller-supplied canonical bytes with the framework's audit-sign keypair,
+ * returning a detached signature block — the schema-agnostic counterpart of
+ * `sign()`. Where `sign()` is bound to the v1 manifest schema (it `validate()`s
+ * the whole `{ version, framework, files[] }` shape before signing), this signs
+ * any bytes a consumer canonicalizes itself, so a bespoke backup-header /
+ * manifest format reuses the same post-quantum signing keypair + fingerprint
+ * pinning without adopting the framework schema.
+ *
+ * `canonicalBytes` is a Buffer (signed verbatim) or a string (signed as UTF-8).
+ * Returns `{ algorithm, publicKey, fingerprint, value, signedAt }`. Requires
+ * `b.auditSign.init()` (throws `backup-manifest/no-signer` otherwise).
+ *
+ * @example
+ *   var sig = b.backupManifest.signBytes(myCanonicalHeaderBuffer);
+ *   // store sig alongside the header; later:
+ *   var v = b.backupManifest.verifyBytes(myCanonicalHeaderBuffer, sig,
+ *     { expectedFingerprint: b.auditSign.getPublicKeyFingerprint() });
+ *   // v.ok === true
+ */
+function signBytes(canonicalBytes) {
+  if (typeof canonicalBytes !== "string" && !Buffer.isBuffer(canonicalBytes)) {
+    throw new BackupManifestError("backup-manifest/bad-input",
+      "signBytes: canonicalBytes must be a string or Buffer");
+  }
+  return _signPayload(canonicalBytes, "signBytes");
+}
+
+// Verify a previously-signed manifest. Returns { ok, reason?,
+// fingerprint? }. Caller policy decides whether a missing or
+// fingerprint-mismatched signature is fatal — verifyManifestSignature
+// in lib/backup/index.js wraps this with operator-facing semantics.
+/**
+ * @primitive b.backupManifest.verifySignature
+ * @signature b.backupManifest.verifySignature(manifest, opts)
+ * @since     0.6.0
+ * @status    stable
+ * @related   b.backupManifest.sign, b.backupManifest.verifyBytes
+ *
+ * Verify a signed v1 backup manifest's detached `signature` block over its
+ * canonical bytes. Returns `{ ok, reason?, fingerprint? }` — never throws — so
+ * a caller decides whether a missing / mismatched signature is fatal. Pass
+ * `opts.expectedFingerprint` to pin the active audit-sign key and refuse a
+ * manifest signed under a different (rotated) key. For a schema-agnostic
+ * alternative see `verifyBytes`.
+ *
+ * @opts
+ *   expectedFingerprint: string,   // refuse a manifest whose fingerprint differs
+ *
+ * @example
+ *   var v = b.backupManifest.verifySignature(manifest,
+ *     { expectedFingerprint: b.auditSign.getPublicKeyFingerprint() });
+ *   if (!v.ok) throw new Error("untrusted backup: " + v.reason);
+ */
+function verifySignature(manifest, opts) {
+  if (!manifest || typeof manifest !== "object") {
+    return { ok: false, reason: "manifest must be an object" };
+  }
+  if (!manifest.signature || typeof manifest.signature !== "object") {
+    return { ok: false, reason: "manifest has no signature block" };
+  }
+  return _verifyPayloadAgainstBlock(signingPayload(manifest), manifest.signature, opts);
+}
+
+/**
+ * @primitive b.backupManifest.verifyBytes
+ * @signature b.backupManifest.verifyBytes(canonicalBytes, signatureBlock, opts?)
+ * @since     0.15.21
+ * @status    stable
+ * @related   b.backupManifest.signBytes, b.backupManifest.verifySignature
+ *
+ * Verify caller-supplied canonical bytes against a detached signature block
+ * produced by `signBytes()` — the schema-agnostic counterpart of
+ * `verifySignature()`. Returns `{ ok, reason?, fingerprint? }`. Pass
+ * `opts.expectedFingerprint` to pin the active audit-sign key and refuse a
+ * block signed under a different (rotated / historical) key. Falls back to
+ * `node:crypto.verify` when audit-sign isn't initialized, so a downstream
+ * verifier process can check a signature without holding the signing key.
+ *
+ * @opts
+ *   expectedFingerprint: string,   // refuse a block whose fingerprint differs
+ *
+ * @example
+ *   var v = b.backupManifest.verifyBytes(headerBytes, sigBlock,
+ *     { expectedFingerprint: trustedFingerprint });
+ *   if (!v.ok) throw new Error("untrusted header: " + v.reason);
+ */
+function verifyBytes(canonicalBytes, signatureBlock, opts) {
+  if (typeof canonicalBytes !== "string" && !Buffer.isBuffer(canonicalBytes)) {
+    return { ok: false, reason: "verifyBytes: canonicalBytes must be a string or Buffer" };
+  }
+  return _verifyPayloadAgainstBlock(canonicalBytes, signatureBlock, opts);
 }
 
 function parse(jsonStr) {
@@ -440,8 +585,10 @@ module.exports = {
   serialize:            serialize,
   parse:                parse,
   sign:                 sign,
+  signBytes:            signBytes,
   signingPayload:       signingPayload,
   verifySignature:      verifySignature,
+  verifyBytes:          verifyBytes,
   FORMAT_VERSION:       FORMAT_VERSION,
   FRAMEWORK_NAME:       FRAMEWORK_NAME,
   VALID_KINDS:          VALID_KINDS,