@blamejs/core 0.8.43 → 0.8.49

package/lib/audit-sign.js

@@ -1,60 +1,62 @@
 "use strict";
 /**
- * Audit signing key — separate PQC keypair for periodic checkpoint
- * signatures over the audit chain.
- *
- * Algorithm: SLH-DSA-SHAKE-256f (FIPS 205) by default. ML-DSA-87
- * (FIPS 204) supported as an opt-in alternative for throughput-
- * sensitive deployments. Both are NIST PQC Category 5 (~256-bit
- * symmetric security). SLH-DSA-SHAKE-256f is hash-only — its
- * security depends solely on the underlying hash function, with no
- * lattice / module-hardness assumptions — and matches the framework's
- * SHAKE256 KDF + SHA3-512 hash family. Audit checkpoints are long-
- * lived integrity attestations (must verify for the data retention
- * period — years for HIPAA / SOX), so the conservative-PQC posture
- * carries more weight here than the smaller ML-DSA-87 signature
- * (~5 KB) and faster sign (0.6 ms vs 76 ms).
- *
- * The algorithm is recorded in the on-disk key file's `algorithm`
- * field. Older key files that predate the algorithm field are loaded
- * as ML-DSA-87 (the previous implicit default) and continue to verify
- * their checkpoint history. Operators who want to migrate rotate
- * their audit-signing key.
- *
- * Design:
- *   - Different keypair from the vault encryption keys. Compromise of the
- *     vault DOES NOT let an attacker forge audit checkpoints.
- *   - Stored at <dataDir>/audit-sign.key.sealed (default 'wrapped' mode)
- *     or <dataDir>/audit-sign.key (opt-out 'plaintext' mode with warning).
- *   - Wrapped under its OWN passphrase, sourced via:
- *       BLAMEJS_AUDIT_SIGNING_PASSPHRASE         (env)
- *       BLAMEJS_AUDIT_SIGNING_PASSPHRASE_FILE    (file)
- *       BLAMEJS_AUDIT_SIGNING_PASSPHRASE_SOURCE  (selector: auto|env|file|stdin)
- *     These are intentionally distinct from BLAMEJS_VAULT_PASSPHRASE so
- *     operator-error reuse of the same passphrase is at least explicit.
- *   - First-run generates the keypair automatically.
- *
- * Threat model:
- *   - Vault key compromised + DB write access:
- *       attacker can read sealed values + rewrite audit_log rows + recompute
- *       per-row chain hashes. They CANNOT forge new audit_checkpoint rows
- *       because each checkpoint requires the audit-signing private key.
- *   - Audit signing key compromised:
- *       attacker can forge new checkpoints but cannot read sealed values.
- *       Existing checkpoints still anchor history that pre-dated the
- *       compromise (operator should rotate signing key on detection).
- *   - Both compromised:
- *       framework cannot defend against this — by design, the operator's
- *       physical / administrative controls (HIPAA §164.310, GDPR Art. 32(1)(d))
- *       cover this case.
- *
- * Public API:
- *   await auditSign.init({ dataDir, mode? })   ← call at db.init()
- *   auditSign.sign(payload)                    ← Buffer/string → Buffer signature
- *   auditSign.verify(payload, signature, publicKey?) ← bool
- *   auditSign.getPublicKey()                   ← PEM string
- *   auditSign.getPublicKeyFingerprint()        ← sha3 hex (stable id)
- *   auditSign.getMode()                        ← 'wrapped' | 'plaintext'
+ * @module b.auditSign
+ * @nav    Crypto
+ * @title  Audit Signing
+ *
+ * @intro
+ *   SLH-DSA-SHAKE-256f post-quantum signature for audit-chain
+ *   checkpoints. Wrapped vs plaintext on-disk modes, key derivation
+ *   from an operator passphrase, periodic checkpoint sign / verify,
+ *   multiple-key support so a key rotation doesn't strand history.
+ *
+ *   Algorithm: SLH-DSA-SHAKE-256f (FIPS 205) by default. ML-DSA-87
+ *   (FIPS 204 Category 5) and ML-DSA-65 (FIPS 204 Category 3, ~192-bit
+ *   symmetric security, smaller signatures + faster verify than 87)
+ *   ship as opt-in alternatives for throughput-sensitive deployments.
+ *   SLH-DSA-SHAKE-256f is hash-only — its security depends solely on
+ *   the underlying hash function, with no lattice / module-hardness
+ *   assumptions — and matches the framework's SHAKE256 KDF + SHA3-512
+ *   hash family. Audit checkpoints are long-lived integrity
+ *   attestations (must verify for the data retention period — years
+ *   for HIPAA / SOX), so the conservative-PQC posture carries more
+ *   weight here than the smaller ML-DSA signatures (~5 KB at 87,
+ *   ~3.3 KB at 65) and faster sign (~0.6 ms vs 76 ms).
+ *
+ *   The algorithm is recorded in the on-disk key file's `algorithm`
+ *   field. The framework refuses to load a key file that lacks it.
+ *   Operators upgrading the algorithm rotate their audit-signing key
+ *   via `b.auditSign.rotateSigningKey({ algorithm })`.
+ *
+ *   Design:
+ *     - Different keypair from the vault encryption keys. Compromise
+ *       of the vault DOES NOT let an attacker forge audit checkpoints.
+ *     - Stored at <dataDir>/audit-sign.key.sealed (default 'wrapped'
+ *       mode) or <dataDir>/audit-sign.key (opt-out 'plaintext' mode
+ *       with warning).
+ *     - Wrapped under its OWN passphrase, sourced via:
+ *         BLAMEJS_AUDIT_SIGNING_PASSPHRASE         (env)
+ *         BLAMEJS_AUDIT_SIGNING_PASSPHRASE_FILE    (file)
+ *         BLAMEJS_AUDIT_SIGNING_PASSPHRASE_SOURCE  (auto|env|file|stdin)
+ *       Intentionally distinct from BLAMEJS_VAULT_PASSPHRASE so
+ *       operator-error reuse of the same passphrase is explicit.
+ *     - First-run generates the keypair automatically.
+ *
+ *   Threat model:
+ *     - Vault key compromised + DB write access: attacker can read
+ *       sealed values + rewrite audit_log rows + recompute per-row
+ *       chain hashes. They CANNOT forge new audit_checkpoint rows —
+ *       each checkpoint requires the audit-signing private key.
+ *     - Audit signing key compromised: attacker can forge new
+ *       checkpoints but cannot read sealed values. Existing
+ *       checkpoints still anchor history that pre-dated the compromise
+ *       (operator should rotate signing key on detection).
+ *     - Both compromised: framework cannot defend against this — the
+ *       operator's physical / administrative controls (HIPAA §164.310,
+ *       GDPR Art. 32(1)(d)) cover this case.
+ *
+ * @card
+ *   SLH-DSA-SHAKE-256f post-quantum signature for audit-chain checkpoints.
  */
 var fs = require("fs");
 var path = require("path");
@@ -82,7 +84,13 @@ var _err = AuditSignError.factory;
 // that lacks it. The legacy implicit-default-to-ml-dsa-87 fallback was
 // removed as part of the pre-v1 compat-shim sweep.
 var DEFAULT_SIGNING_ALG = "slh-dsa-shake-256f";
-var SUPPORTED_SIGNING_ALGS = Object.freeze(["slh-dsa-shake-256f", "ml-dsa-87"]);
+// ml-dsa-65 (FIPS 204 Category 3, ~192-bit symmetric security) is opt-
+// in alongside ml-dsa-87 — same code path (both auto-detected by
+// node:crypto from the PEM), smaller signatures (~3.3 KB vs ~5 KB at
+// 87 / ~29.5 KB at SLH-DSA-SHAKE-256f), faster verify. Operators with
+// throughput-sensitive checkpoint streams or audit-feed shippers
+// elect ml-dsa-65 explicitly via opts.algorithm.
+var SUPPORTED_SIGNING_ALGS = Object.freeze(["slh-dsa-shake-256f", "ml-dsa-87", "ml-dsa-65"]);
 
 var SIGNING_KEY_SCHEMA = {
   type: "object",
@@ -136,6 +144,37 @@ function _getPassphrase(promptText) {
 // files take their algorithm from the file itself, ignoring this.
 var pendingNewKeyAlg = null;
 
+/**
+ * @primitive  b.auditSign.init
+ * @signature  b.auditSign.init(opts)
+ * @since      0.1.0
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2, sox-404
+ * @related    b.auditSign.sign, b.auditSign.verify, b.auditSign.rotateSigningKey
+ *
+ * Boot the audit-signing keypair. Called once during `b.db.init()`;
+ * later calls are no-ops. First run generates a fresh PQC keypair and
+ * either seals it under an operator passphrase ('wrapped' mode,
+ * default) or writes it plaintext at 0600 ('plaintext' mode, opt-out
+ * with stderr warning). Subsequent boots load the existing key file
+ * and refuse if both wrapped + plaintext copies exist on disk
+ * (KEY_FILE_CONFLICT) or the on-disk mode disagrees with `opts.mode`
+ * (MODE_MISMATCH).
+ *
+ * @opts
+ *   dataDir:   string,                                          // required — directory holding the key file
+ *   mode:      "wrapped" | "plaintext",                         // default "wrapped"
+ *   algorithm: "slh-dsa-shake-256f" | "ml-dsa-87" | "ml-dsa-65" // default "slh-dsa-shake-256f"; only consulted when generating a fresh key
+ *
+ * @example
+ *   await b.auditSign.init({
+ *     dataDir:   "/var/lib/blamejs/data",
+ *     mode:      "wrapped",
+ *     algorithm: "slh-dsa-shake-256f",
+ *   });
+ *   b.auditSign.getMode();        // → "wrapped"
+ *   b.auditSign.getAlgorithm();   // → "slh-dsa-shake-256f"
+ */
 async function init(opts) {
   if (initialized) return;
   if (!opts || !opts.dataDir) {
@@ -307,12 +346,66 @@ function _requireInit() {
   }
 }
 
+/**
+ * @primitive  b.auditSign.sign
+ * @signature  b.auditSign.sign(payload)
+ * @since      0.1.0
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2, sox-404
+ * @related    b.auditSign.verify, b.audit.checkpoint
+ *
+ * Sign a payload (Buffer or string) with the in-memory PQC private
+ * key. Returns the raw signature bytes as a Buffer. Throws if `init()`
+ * has not been awaited. Used by `b.audit.checkpoint()` to anchor the
+ * chain tip; operators normally don't call it directly.
+ *
+ * @example
+ *   await b.auditSign.init({ dataDir: "/var/lib/blamejs/data" });
+ *
+ *   // Sign a chain checkpoint payload (the audit module passes the
+ *   // chain tip's row hash + monotonic counter as canonical bytes).
+ *   var tip = { rowHash: "9f4e2c3a", counter: 1042 };
+ *   var payload = Buffer.from(JSON.stringify(tip), "utf8");
+ *   var signature = b.auditSign.sign(payload);
+ *   // → <Buffer ...> roughly 29.5 KB for SLH-DSA-SHAKE-256f
+ */
 function sign(payload) {
   _requireInit();
   var buf = Buffer.isBuffer(payload) ? payload : Buffer.from(String(payload), "utf8");
   return nodeCrypto.sign(null, buf, keys.privateKey);
 }
 
+/**
+ * @primitive  b.auditSign.verify
+ * @signature  b.auditSign.verify(payload, signature, publicKeyPem)
+ * @since      0.1.0
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2, sox-404
+ * @related    b.auditSign.sign, b.audit.verifyCheckpoints
+ *
+ * Verify a signature against the supplied (or current) public key.
+ * Returns `true` when the signature is valid, `false` otherwise; never
+ * throws on a forgery — callers branch on the boolean. The third
+ * argument lets verification use a HISTORICAL key (read from
+ * `audit-sign.key.sealed.history-*`) so a checkpoint signed years
+ * earlier still verifies after rotation.
+ *
+ * @example
+ *   await b.auditSign.init({ dataDir: "/var/lib/blamejs/data" });
+ *
+ *   // Re-walk every checkpoint to confirm chain integrity.
+ *   var tip = { rowHash: "9f4e2c3a", counter: 1042 };
+ *   var payload = Buffer.from(JSON.stringify(tip), "utf8");
+ *   var signature = b.auditSign.sign(payload);
+ *
+ *   var ok = b.auditSign.verify(payload, signature);
+ *   // → true
+ *
+ *   // A historical checkpoint signed under an old key:
+ *   var oldPubPem = "-----BEGIN PUBLIC KEY-----\nMII...\n-----END PUBLIC KEY-----";
+ *   b.auditSign.verify(payload, signature, oldPubPem);
+ *   // → true (when payload + signature were produced under that key)
+ */
 function verify(payload, signature, publicKeyPem) {
   _requireInit();
   var buf = Buffer.isBuffer(payload) ? payload : Buffer.from(String(payload), "utf8");
@@ -321,9 +414,80 @@ function verify(payload, signature, publicKeyPem) {
   return nodeCrypto.verify(null, buf, pub, sigBuf);
 }
 
+/**
+ * @primitive b.auditSign.getPublicKey
+ * @signature b.auditSign.getPublicKey()
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.auditSign.getPublicKeyFingerprint, b.auditSign.verify
+ *
+ * Return the in-memory public key as a SPKI PEM string. Operators
+ * publish this so external auditors can verify checkpoint signatures
+ * without holding any private material.
+ *
+ * @example
+ *   await b.auditSign.init({ dataDir: "/var/lib/blamejs/data" });
+ *   var pem = b.auditSign.getPublicKey();
+ *   // → "-----BEGIN PUBLIC KEY-----\nMII...\n-----END PUBLIC KEY-----\n"
+ */
 function getPublicKey() { _requireInit(); return keys.publicKey; }
+
+/**
+ * @primitive b.auditSign.getPublicKeyFingerprint
+ * @signature b.auditSign.getPublicKeyFingerprint()
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.auditSign.getPublicKey, b.auditSign.rotateSigningKey
+ *
+ * Return the SHA3-512 fingerprint of the public key as a lowercase
+ * hex string. Stable across boots for the same keypair; a different
+ * fingerprint after `rotateSigningKey()` is the signal that the
+ * rotation actually changed material.
+ *
+ * @example
+ *   await b.auditSign.init({ dataDir: "/var/lib/blamejs/data" });
+ *   var fp = b.auditSign.getPublicKeyFingerprint();
+ *   // → "9f4e2c3a..." (128 hex chars, SHA3-512)
+ */
 function getPublicKeyFingerprint() { _requireInit(); return keys.fingerprint; }
+
+/**
+ * @primitive b.auditSign.getMode
+ * @signature b.auditSign.getMode()
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.auditSign.init
+ *
+ * Return the on-disk storage mode chosen at `init()` — `"wrapped"`
+ * (passphrase-sealed, default) or `"plaintext"` (0600 file, opt-out).
+ * Returns `null` before `init()` runs.
+ *
+ * @example
+ *   await b.auditSign.init({ dataDir: "/var/lib/blamejs/data" });
+ *   b.auditSign.getMode();
+ *   // → "wrapped"
+ */
 function getMode() { return currentMode; }
+
+/**
+ * @primitive b.auditSign.getAlgorithm
+ * @signature b.auditSign.getAlgorithm()
+ * @since     0.7.0
+ * @status    stable
+ * @related   b.auditSign.init, b.auditSign.rotateSigningKey
+ *
+ * Return the algorithm of the currently-loaded keypair —
+ * `"slh-dsa-shake-256f"`, `"ml-dsa-87"`, or `"ml-dsa-65"`. Read from
+ * the on-disk key file, not from the operator's `init()` opts (the
+ * file's algorithm wins so a key generated under one alg keeps
+ * verifying under that alg even when a later boot passes a different
+ * default).
+ *
+ * @example
+ *   await b.auditSign.init({ dataDir: "/var/lib/blamejs/data" });
+ *   b.auditSign.getAlgorithm();
+ *   // → "slh-dsa-shake-256f"
+ */
 function getAlgorithm() { _requireInit(); return keys.algorithm; }
 
 // Re-sign every payload in the operator-supplied iterable using the
@@ -339,6 +503,45 @@ function getAlgorithm() { _requireInit(); return keys.algorithm; }
 // internal key-history. The caller persists the new signature in
 // place — this primitive returns the new bytes without touching
 // storage.
+/**
+ * @primitive  b.auditSign.reSignAll
+ * @signature  b.auditSign.reSignAll(iter, opts)
+ * @since      0.7.0
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2, sox-404
+ * @related    b.auditSign.rotateSigningKey, b.auditSign.sign
+ *
+ * Re-sign every payload in `iter` under the CURRENT in-memory key.
+ * Each iteration yields `{ id, payload, signature, oldPublicKeyPem }`
+ * — payloads whose old signature fails to verify under
+ * `oldPublicKeyPem` are skipped (already tampered or never signed
+ * under that key) rather than aborting the whole walk. Returns
+ * `{ reSigned, skipped, errors }`. The caller (typically the audit
+ * module's checkpoint store) persists the new bytes; this primitive
+ * does not touch storage.
+ *
+ * @opts
+ *   onProgress: function (entry),   // called with { id, newSignature } per re-sign; errors in the hook are drop-silent
+ *
+ * @example
+ *   await b.auditSign.init({ dataDir: "/var/lib/blamejs/data" });
+ *
+ *   async function* allCheckpoints() {
+ *     yield {
+ *       id:               1,
+ *       payload:          Buffer.from("{\"counter\":1}", "utf8"),
+ *       signature:        Buffer.from("00", "hex"),
+ *       oldPublicKeyPem:  b.auditSign.getPublicKey(),
+ *     };
+ *   }
+ *
+ *   var summary = await b.auditSign.reSignAll(allCheckpoints(), {
+ *     onProgress: function (entry) {
+ *       // persist entry.newSignature against entry.id atomically
+ *     },
+ *   });
+ *   // → { reSigned: 1, skipped: 0, errors: 0 }
+ */
 async function reSignAll(iter, opts) {
   _requireInit();
   opts = opts || {};
@@ -382,6 +585,49 @@ async function reSignAll(iter, opts) {
 //   2. Call rotateSigningKey() — gets new keys live
 //   3. Walk checkpoints through reSignAll()
 //   4. Write back the new signatures atomically
+/**
+ * @primitive  b.auditSign.rotateSigningKey
+ * @signature  b.auditSign.rotateSigningKey(opts)
+ * @since      0.7.0
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2, sox-404
+ * @related    b.auditSign.reSignAll, b.auditSign.init
+ *
+ * Generate (or accept) a fresh keypair, copy the existing sealed /
+ * plaintext key file to a timestamped `*.history-<iso>-<fp>` path, and
+ * persist the new key to disk through the same wrap path as boot. The
+ * in-memory swap happens last so a write failure leaves the framework
+ * with the OLD key still in memory + on disk. Refuses (`ROTATE_NOOP`)
+ * when the new keypair has the same fingerprint as the current one.
+ * Operators rotating the audit-signing key in production typically:
+ * read existing checkpoints, call `rotateSigningKey()`, walk the
+ * checkpoints through `reSignAll()`, then write the new signatures
+ * back atomically. Returns metadata about the rotation including the
+ * `historyPath` so external tools can verify pre-rotation checkpoints
+ * later.
+ *
+ * @opts
+ *   privateKeyPem: string,                                     // BYO keypair (pair with publicKeyPem); when omitted the framework generates fresh material
+ *   publicKeyPem:  string,
+ *   algorithm:     "slh-dsa-shake-256f" | "ml-dsa-87" | "ml-dsa-65"  // defaults to the current keypair's algorithm
+ *
+ * @example
+ *   await b.auditSign.init({ dataDir: "/var/lib/blamejs/data" });
+ *
+ *   // Annual rotation — same algorithm, framework-generated material:
+ *   var result = await b.auditSign.rotateSigningKey();
+ *   // → {
+ *   //     previousFingerprint: "9f4e...",
+ *   //     newFingerprint:      "3a7c...",
+ *   //     algorithm:           "slh-dsa-shake-256f",
+ *   //     rotatedAt:           "2026-05-09T12:00:00.000Z",
+ *   //     historyPath:         "/var/lib/blamejs/data/audit-sign.key.sealed.history-2026-05-09T12-00-00-000Z-9f4e2c3aabbccdd0",
+ *   //     ...
+ *   //   }
+ *
+ *   // Algorithm upgrade — same call, with explicit `algorithm`:
+ *   await b.auditSign.rotateSigningKey({ algorithm: "ml-dsa-65" });
+ */
 async function rotateSigningKey(rotOpts) {
   _requireInit();
   rotOpts = rotOpts || {};