@blamejs/core 0.8.43 → 0.8.50

package/lib/audit-tools.js

@@ -1,54 +1,57 @@
 "use strict";
 /**
- * audit-tools — operator tooling on top of the audit chain.
- *
- * Four operations the compliance matrix calls for:
- *
- *   archive(opts)      Bundle audit rows older than `before` into a
- *                      PQC-encrypted archive with chain proof + a
- *                      covering signed checkpoint. Live rows untouched.
- *   exportSlice(opts)  Auditor-shaped slice (date range / subject /
- *                      action filter) with chain proof. Live rows
- *                      untouched. Purpose: deliver an evidence bundle
- *                      to an external auditor without surrendering the
- *                      whole log.
- *   verifyBundle(opts) Round-trip integrity: decrypt the bundle, walk
- *                      the chain math across the contained rows,
- *                      verify the covering checkpoint signature
- *                      (archive bundles only).
- *   purge(opts)        Confirmation-gated deletion of live audit rows
- *                      already captured in a verified archive bundle.
- *                      Inserts a purge-anchor so live audit.verify()
- *                      keeps working post-purge — the anchor's
- *                      lastRowHash becomes the new chain origin.
- *
- * Bundle layout (POSIX-flat directory; matches the backup-bundle shape
- * so operators see one mental model for "encrypted blamejs bundle"):
- *
- *   <out>/manifest.json    Canonical-JSON manifest. Includes format,
- *                          kind, range (firstCounter/lastCounter/
- *                          firstRecordedAt/lastRecordedAt/
- *                          firstRowHash/lastRowHash), rowCount, the
- *                          per-blob salts, the framework version, and
- *                          (archive only) a copy of the covering
- *                          checkpoint row plus its public-key
- *                          fingerprint.
- *   <out>/rows.enc         PQC-encrypted JSONL — one row per line,
- *                          monotonic-counter ASC, sealed form (rowHash
- *                          stays computable from disk bytes). Each
- *                          field in a sealed column is the on-disk
- *                          ciphertext, not the plaintext, so the chain
- *                          recomputes byte-for-byte.
- *   <out>/checkpoint.enc   Archive only. PQC-encrypted JSON of the
- *                          covering audit_checkpoints row.
- *
- * `kind="archive"` bundles always include a covering checkpoint
- * (atMonotonicCounter >= lastCounter) so the anchor signature
- * tamper-evidences the whole archive. `kind="export"` bundles are
- * auditor evidence; the chain math is self-contained but the
- * upstream signature anchor is optional (auditors typically follow
- * up with an `audit.verify` call against the live system to confirm
- * the slice still chains).
+ * @module b.auditTools
+ * @nav    Observability
+ * @title  Audit Tools
+ *
+ * @intro
+ *   Operator-side audit-chain inspection / export — verify chain
+ *   integrity end-to-end, export RFC 8785 canonical-JSON slices,
+ *   format rows for downstream SIEM (CADF / ISO 19395), and generate
+ *   tamper-evident compliance-evidence bundles auditors can verify
+ *   off-line.
+ *
+ *   Four core operations on top of the live `audit_log` chain:
+ *
+ *     archive(opts)      Bundle rows older than `before` into a
+ *                        PQC-encrypted archive with chain proof + a
+ *                        covering signed checkpoint. Live rows are
+ *                        untouched until a separate `purge()` call.
+ *     exportSlice(opts)  Auditor-shaped slice (date range / action
+ *                        filter) with chain proof — deliver evidence
+ *                        to an external auditor without surrendering
+ *                        the whole log.
+ *     verifyBundle(opts) Round-trip integrity: decrypt the bundle,
+ *                        walk chain math across the contained rows,
+ *                        verify the covering checkpoint's ML-DSA
+ *                        signature (archive bundles only).
+ *     purge(opts)        Confirmation-gated deletion of live rows
+ *                        already captured in a verified archive
+ *                        bundle. Inserts a purge-anchor so
+ *                        `b.audit.verify()` keeps working post-purge.
+ *
+ *   Bundle layout (POSIX-flat directory; matches the backup-bundle
+ *   shape so operators see one mental model for "encrypted blamejs
+ *   bundle"):
+ *
+ *     <out>/manifest.json   Canonical-JSON manifest (format / kind /
+ *                           range / rowCount / per-blob salts /
+ *                           framework version; archive bundles also
+ *                           carry the covering checkpoint summary).
+ *     <out>/rows.enc        PQC-encrypted JSONL of audit rows in
+ *                           sealed form so rowHash stays computable
+ *                           from disk bytes byte-for-byte.
+ *     <out>/checkpoint.enc  Archive-only. PQC-encrypted JSON of the
+ *                           covering audit_checkpoints row.
+ *
+ *   `kind="archive"` bundles always include a covering checkpoint
+ *   (atMonotonicCounter >= lastCounter) so the off-chain signature
+ *   tamper-evidences the whole archive. `kind="export"` bundles are
+ *   auditor evidence; the chain math is self-contained, with the
+ *   upstream signature anchor optional.
+ *
+ * @card
+ *   Operator-side audit-chain inspection / export — verify chain integrity end-to-end, export RFC 8785 canonical-JSON slices, format rows for downstream SIEM (CADF / ISO 19395), and generate tamper-evident compliance-evidence bundles auditors can verify off-line.
  */
 
 var fs = require("fs");
@@ -153,6 +156,28 @@ function _rowToWireForm(row) {
 // unchanged AND _rowToWireForm (which the chain-hash canonicalizes
 // over) doesn't change its bytes — so chain verify continues to
 // match. Operators call this on retrieved rows for export.
+/**
+ * @primitive b.auditTools.withRecordedAtIso
+ * @signature b.auditTools.withRecordedAtIso(row)
+ * @since     0.7.30
+ * @related   b.auditTools.exportSlice, b.auditTools.exportCadf
+ *
+ * Surface `recordedAt` as ISO-8601 / RFC 3339 (with explicit `Z`)
+ * alongside the framework's primary Unix-ms integer. Auditors
+ * comparing rows against external SIEM events expect ISO; the chain
+ * hash is unaffected because the canonical wire form used for
+ * hashing doesn't include the derived `recordedAtIso` field.
+ *
+ * Returns a shallow copy with `recordedAtIso` added when
+ * `recordedAt` is a finite number / bigint; otherwise returns the
+ * input unchanged.
+ *
+ * @example
+ *   var row = { _id: "evt-1", recordedAt: 1762560000000, action: "auth.login" };
+ *   var formatted = b.auditTools.withRecordedAtIso(row);
+ *   // → { _id: "evt-1", recordedAt: 1762560000000,
+ *   //     recordedAtIso: "2025-11-08T00:00:00.000Z", action: "auth.login" }
+ */
 function withRecordedAtIso(row) {
   if (!row) return row;
   var out = Object.assign({}, row);
@@ -396,6 +421,37 @@ async function _readBundle(inDir, passphrase) {
 
 // ---- Public ops ----
 
+/**
+ * @primitive b.auditTools.archive
+ * @signature b.auditTools.archive(opts)
+ * @since     0.7.30
+ * @compliance hipaa, pci-dss, gdpr, soc2, sox-404
+ * @related   b.auditTools.verifyBundle, b.auditTools.purge, b.audit.checkpoint
+ *
+ * Bundle every audit row older than `opts.before` into a
+ * PQC-encrypted archive (XChaCha20-Poly1305 + Argon2id-derived key)
+ * containing a chain proof and the covering ML-DSA-87 checkpoint.
+ * Live rows are untouched — call `b.auditTools.purge` separately
+ * once the archive is verified.
+ *
+ * Refuses if `opts.out` exists, no rows match, or no signed
+ * checkpoint covers the slice (run `b.audit.checkpoint()` first).
+ *
+ * @opts
+ *   out:        string,         // fresh directory path for the bundle
+ *   before:     number|Date|string,  // archive rows recordedAt < this
+ *   passphrase: Buffer|string,  // bundle-encryption passphrase
+ *
+ * @example
+ *   var ninetyDaysAgo = Date.now() - 90 * 24 * 60 * 60 * 1000;
+ *   var result = await b.auditTools.archive({
+ *     out:        "/var/audit/2026-Q1.bundle",
+ *     before:     ninetyDaysAgo,
+ *     passphrase: process.env.AUDIT_BUNDLE_PASSPHRASE,
+ *   });
+ *   // → { rowCount: 14823, range: { firstCounter: 1, lastCounter: 14823, ... },
+ *   //     manifestPath: "/var/audit/2026-Q1.bundle/manifest.json", ... }
+ */
 async function archive(opts) {
   opts = opts || {};
   _requirePassphrase(opts.passphrase);
@@ -444,6 +500,39 @@ async function archive(opts) {
   };
 }
 
+/**
+ * @primitive b.auditTools.exportSlice
+ * @signature b.auditTools.exportSlice(opts)
+ * @since     0.7.30
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related   b.auditTools.archive, b.auditTools.verifyBundle, b.auditTools.exportCadf
+ *
+ * Auditor-shaped slice — bundle the audit rows in `[from, to]`
+ * (optionally filtered by exact `action`) into a PQC-encrypted
+ * directory carrying chain-proof material. Refuses non-contiguous
+ * slices because chain verification cannot ground a sequence with
+ * gaps in `monotonicCounter`.
+ *
+ * Use date-range filters that cover every row in the range; an
+ * action filter that drops intermediate counters is rejected with
+ * `audit-tools/non-contiguous`.
+ *
+ * @opts
+ *   out:        string,                // fresh directory path
+ *   from:       number|Date|string,    // recordedAt >= this (inclusive)
+ *   to:         number|Date|string,    // recordedAt <= this (inclusive)
+ *   action:     string,                // exact action match (optional)
+ *   passphrase: Buffer|string,         // bundle-encryption passphrase
+ *
+ * @example
+ *   var bundle = await b.auditTools.exportSlice({
+ *     out:        "/tmp/audit-2026-q1.bundle",
+ *     from:       "2026-01-01T00:00:00Z",
+ *     to:         "2026-03-31T23:59:59Z",
+ *     passphrase: process.env.AUDIT_BUNDLE_PASSPHRASE,
+ *   });
+ *   // → { rowCount: 4218, manifest: { kind: "export", ... }, ... }
+ */
 async function exportSlice(opts) {
   opts = opts || {};
   _requirePassphrase(opts.passphrase);
@@ -496,6 +585,42 @@ async function exportSlice(opts) {
   };
 }
 
+/**
+ * @primitive b.auditTools.verifyBundle
+ * @signature b.auditTools.verifyBundle(opts)
+ * @since     0.7.30
+ * @compliance hipaa, pci-dss, gdpr, soc2, sox-404
+ * @related   b.auditTools.archive, b.auditTools.exportSlice, b.auditTools.purge
+ *
+ * Round-trip integrity check on a bundle directory: decrypt
+ * `rows.enc`, walk the prevHash → rowHash chain across the contained
+ * rows starting from the manifest's `predecessorRowHash` witness,
+ * confirm `firstRowHash` / `lastRowHash` match, and (archive only)
+ * verify the covering checkpoint's ML-DSA-87 signature against the
+ * locally-loaded audit-sign public key (or `opts.verifySignature`
+ * for cross-machine auditors).
+ *
+ * Returns `{ ok: true, kind, rowsVerified, range, manifest }` on
+ * success or `{ ok: false, reason, breakAt? }` at the first break.
+ *
+ * @opts
+ *   in:                          string,               // bundle directory
+ *   passphrase:                  Buffer|string,        // decryption passphrase
+ *   verifyCheckpointSignature:   boolean,              // default true
+ *   verifySignature:             function(checkpoint), // override the default verifier
+ *   includeRows:                 boolean,              // attach decrypted rows to result
+ *
+ * @example
+ *   var result = await b.auditTools.verifyBundle({
+ *     in:         "/var/audit/2026-Q1.bundle",
+ *     passphrase: process.env.AUDIT_BUNDLE_PASSPHRASE,
+ *   });
+ *   if (!result.ok) {
+ *     console.error("bundle integrity break:", result.reason);
+ *     process.exit(1);
+ *   }
+ *   // → { ok: true, kind: "archive", rowsVerified: 14823, range: { ... } }
+ */
 async function verifyBundle(opts) {
   opts = opts || {};
   _requirePassphrase(opts.passphrase);
@@ -590,6 +715,35 @@ function _defaultVerifyCheckpointSignature(checkpoint) {
   } catch (_e) { return false; }
 }
 
+/**
+ * @primitive b.auditTools.purge
+ * @signature b.auditTools.purge(opts)
+ * @since     0.7.30
+ * @compliance hipaa, pci-dss, gdpr, soc2, sox-404
+ * @related   b.auditTools.archive, b.auditTools.verifyBundle, b.audit.verify
+ *
+ * Confirmation-gated deletion of live audit rows already captured in
+ * a verified archive bundle. Refuses unless `opts.confirm === true`,
+ * the bundle verifies clean as `kind="archive"`, and the bundle's
+ * `firstCounter` / `predecessorRowHash` match the next contiguous
+ * purge point on disk. Inserts a `_blamejs_audit_purge_anchor` row
+ * so `b.audit.verify()` keeps chaining post-purge — the anchor's
+ * `lastPurgedRowHash` becomes the new chain origin.
+ *
+ * @opts
+ *   confirm:         true,                // exact `true` required
+ *   archive:         string,              // path to a verified archive bundle
+ *   passphrase:      Buffer|string,       // bundle decryption passphrase
+ *   verifySignature: function(checkpoint),// auditor pubkey override
+ *
+ * @example
+ *   var result = await b.auditTools.purge({
+ *     confirm:    true,
+ *     archive:    "/var/audit/2026-Q1.bundle",
+ *     passphrase: process.env.AUDIT_BUNDLE_PASSPHRASE,
+ *   });
+ *   // → { purged: true, rowsDeleted: 14823, lastPurgedCounter: 14823, ... }
+ */
 async function purge(opts) {
   opts = opts || {};
   if (opts.confirm !== true) {
@@ -683,20 +837,40 @@ async function _defaultApplyPurge(args) {
   };
 }
 
-// forensicSnapshot — post-compromise composer that bundles an audit
-// archive slice, current break-glass grants, the active incident
-// report (if any), and process-runtime metadata into a single signed
-// bundle. The operator passes this to legal / regulators / the IR
-// team as one tamper-evident artifact.
-//
-//   var snap = await b.auditTools.forensicSnapshot({
-//     out:        "/forensics/2026-05-07-incident-42",
-//     since:      Date.now() - C.TIME.days(7),
-//     passphrase: process.env.AUDIT_BUNDLE_PASSPHRASE,
-//     incidentId: "inc-2026-05-07-42",
-//     reason:     "ATO investigation: 14 failed MFA from new geo, user u_42",
-//     actor:      { id: "alice@ops.example.com", role: "incident-commander" },
-//   });
+/**
+ * @primitive b.auditTools.forensicSnapshot
+ * @signature b.auditTools.forensicSnapshot(opts)
+ * @since     0.8.40
+ * @compliance hipaa, pci-dss, gdpr, soc2, sox-404, dora, nis2
+ * @related   b.auditTools.exportSlice, b.auditTools.archive
+ *
+ * Post-compromise composer that bundles an audit slice (from
+ * `since` → now) plus operator-supplied incident metadata
+ * (incidentId, reason, actor) and runtime fingerprint (Node version
+ * / platform / pid / uptime) into a single tamper-evident artifact
+ * for legal / regulators / the IR team. Emits an
+ * `audit.forensic_snapshot.composed` audit event so the act of
+ * composing the snapshot is itself on-chain.
+ *
+ * @opts
+ *   out:        string,               // fresh directory path
+ *   since:      number|Date|string,   // include rows recordedAt >= this
+ *   passphrase: Buffer|string,        // bundle-encryption passphrase
+ *   reason:     string,               // required incident-context reason
+ *   incidentId: string,               // optional ticket / incident id
+ *   actor:      { id, role },         // optional incident-commander identity
+ *
+ * @example
+ *   var snap = await b.auditTools.forensicSnapshot({
+ *     out:        "/forensics/2026-05-08-inc-42",
+ *     since:      Date.now() - 7 * 24 * 60 * 60 * 1000,
+ *     passphrase: process.env.AUDIT_BUNDLE_PASSPHRASE,
+ *     incidentId: "inc-2026-05-08-42",
+ *     reason:     "ATO investigation: 14 failed MFA from new geo, user u-42",
+ *     actor:      { id: "alice@ops.example.com", role: "incident-commander" },
+ *   });
+ *   // → { snapshotKind: "forensic", incidentId: "inc-2026-05-08-42", ... }
+ */
 async function forensicSnapshot(opts) {
   opts = opts || {};
   _requirePassphrase(opts.passphrase);
@@ -750,9 +924,184 @@ async function forensicSnapshot(opts) {
   return Object.assign({}, manifest, { manifestPath: manifestPath });
 }
 
+// CADF (Cloud Auditing Data Federation, ISO/IEC 19395:2017) is the
+// OpenStack/FedRAMP-tier cloud-audit envelope auditors increasingly
+// expect for federated tooling (cross-tenant SIEM, CSP reporting).
+//
+// We map blamejs audit fields onto CADF attributes:
+//
+//   blamejs                CADF
+//   ---------------------- ----------------------------------
+//   _id                    eventid (UUID-ish)
+//   action                 action (typed verb namespace)
+//   outcome                outcome (success | failure | unknown | pending)
+//   actorUserId            initiator.id (typed via initiator.typeURI)
+//   resourceKind+resourceId target.id + target.typeURI
+//   recordedAt             eventTime (ISO-8601)
+//   reason                 reason.reasonCode + reason.policyType
+//   metadata               attachments[] (operator-supplied free-form)
+//   prevHash/rowHash       observer.id link to chain anchor
+//
+// CADF requires every event to declare its observer (the auditing
+// system). We declare blamejs as the observer with a typeURI of
+// service/audit. The framework version pins observer.id so an auditor
+// can correlate envelope-level events back to a deployment.
+function _toCadfOutcome(outcome) {
+  if (outcome === "success") return "success";
+  if (outcome === "failure" || outcome === "denied") return "failure";
+  if (outcome === "warning") return "unknown";
+  return outcome || "unknown";
+}
+
+function _toCadfEvent(row) {
+  var meta = null;
+  if (row.metadata) {
+    try { meta = typeof row.metadata === "string" ? jsonSafe.parse(row.metadata) : row.metadata; }
+    catch (_e) { meta = { raw: String(row.metadata) }; }
+  }
+  var ev = {
+    typeURI:   "http://schemas.dmtf.org/cloud/audit/1.0/event",
+    eventType: "activity",
+    id:        row._id,
+    eventTime: new Date(Number(row.recordedAt)).toISOString(),
+    action:    row.action,
+    outcome:   _toCadfOutcome(row.outcome),
+    initiator: {
+      id:      row.actorUserIdHash || row.actorUserId || "unknown",
+      typeURI: "service/security/account/user",
+      addresses: row.actorIp ? [{ url: row.actorIp, name: "actorIp" }] : undefined,
+      name:    row.actorSessionId || undefined,
+    },
+    target: {
+      id:      row.resourceIdHash || row.resourceId || row.resourceKind || "n/a",
+      typeURI: row.resourceKind ? ("service/storage/" + row.resourceKind) : "service/security",
+    },
+    observer: {
+      id:      "blamejs:" + (pkg.version || "unknown"),
+      typeURI: "service/security/audit",
+      name:    "blamejs.audit",
+    },
+    reason: row.reason ? {
+      reasonCode: String(row.reason).slice(0, 256),                                // allow:raw-byte-literal — reason cap
+      policyType: "blamejs.audit-chain",
+    } : undefined,
+    attachments: meta ? [{
+      contentType: "application/json",
+      content:     JSON.stringify(meta),
+      name:        "blamejs.metadata",
+    }] : undefined,
+    // Custom CADF extension — anchors back into the audit chain.
+    "blamejs:chain": {
+      monotonicCounter: Number(row.monotonicCounter),
+      prevHash:         row.prevHash,
+      rowHash:          row.rowHash,
+    },
+  };
+  return ev;
+}
+
+/**
+ * @primitive b.auditTools.exportCadf
+ * @signature b.auditTools.exportCadf(opts)
+ * @since     0.7.30
+ * @compliance soc2, pci-dss, gdpr
+ * @related   b.auditTools.exportAudit, b.auditTools.exportSlice
+ *
+ * Format an audit slice as a CADF event-batch (Cloud Auditing Data
+ * Federation, ISO/IEC 19395:2017 + DMTF) — the FedRAMP / OpenStack
+ * envelope cross-tenant SIEMs and CSP reporting tools expect for
+ * federated tooling. Maps blamejs fields onto CADF attributes
+ * (initiator / target / observer / outcome / reason) and embeds a
+ * `blamejs:chain` extension carrying `monotonicCounter` / prevHash /
+ * rowHash so auditors can correlate the envelope back to the chain.
+ *
+ * Returns an object with `events: [...]` ready to ship as JSON.
+ *
+ * @opts
+ *   format:   "cadf",                // optional — defaults to "cadf"
+ *   from:     number|Date|string,    // recordedAt >= this
+ *   to:       number|Date|string,    // recordedAt <= this
+ *   action:   string,                // exact action filter
+ *
+ * @example
+ *   var batch = await b.auditTools.exportCadf({
+ *     from:   "2026-05-01T00:00:00Z",
+ *     to:     "2026-05-08T00:00:00Z",
+ *     action: "auth.login",
+ *   });
+ *   // → { typeURI: ".../event-batch", framework: "blamejs", events: [...] }
+ */
+async function exportCadf(opts) {
+  opts = opts || {};
+  if (opts.format !== undefined && opts.format !== "cadf") {
+    throw new AuditToolsError("audit-tools/bad-format",
+      "audit.export: format must be 'cadf' for exportCadf");
+  }
+  var fromMs = _toMs(opts.from);
+  var toMs   = _toMs(opts.to);
+  var readRows = opts.readRows || _defaultReadRows;
+  var criteria = {};
+  if (fromMs != null) criteria.fromMs = fromMs;
+  if (toMs   != null) criteria.toMs   = toMs;
+  if (opts.action) criteria.action = opts.action;
+  var rows = await readRows(criteria);
+  var events = new Array(rows.length);
+  for (var i = 0; i < rows.length; i++) {
+    events[i] = _toCadfEvent(rows[i]);
+  }
+  return {
+    typeURI:        "http://schemas.dmtf.org/cloud/audit/1.0/event-batch",
+    framework:      "blamejs",
+    frameworkVersion: pkg.version,
+    range: {
+      from: fromMs != null ? new Date(fromMs).toISOString() : null,
+      to:   toMs   != null ? new Date(toMs).toISOString()   : null,
+    },
+    events: events,
+  };
+}
+
+// Operator-facing dispatcher — `b.audit.export({ format })`. Future
+// formats register here.
+/**
+ * @primitive b.auditTools.exportAudit
+ * @signature b.auditTools.exportAudit(opts)
+ * @since     0.7.30
+ * @compliance soc2, pci-dss, gdpr
+ * @related   b.auditTools.exportCadf, b.auditTools.exportSlice
+ *
+ * Format dispatcher for downstream-SIEM exports. Reads `opts.format`
+ * (default `"cadf"`) and delegates to the matching formatter. Future
+ * envelope formats (CEF / OCSF / etc.) register here so callers stay
+ * on a stable signature even when the framework adds formats.
+ *
+ * @opts
+ *   format:   "cadf",                // selector — defaults to "cadf"
+ *   from:     number|Date|string,    // recordedAt >= this
+ *   to:       number|Date|string,    // recordedAt <= this
+ *   action:   string,                // exact action filter
+ *
+ * @example
+ *   var batch = await b.auditTools.exportAudit({
+ *     format: "cadf",
+ *     from:   "2026-05-01T00:00:00Z",
+ *     to:     "2026-05-08T00:00:00Z",
+ *   });
+ *   // → { typeURI: ".../event-batch", framework: "blamejs", events: [...] }
+ */
+async function exportAudit(opts) {
+  opts = opts || {};
+  var format = opts.format || "cadf";
+  if (format === "cadf") return await exportCadf(opts);
+  throw new AuditToolsError("audit-tools/bad-format",
+    "audit.export: format must be one of: cadf (got '" + format + "')");
+}
+
 module.exports = {
   archive:           archive,
   exportSlice:       exportSlice,
+  exportAudit:       exportAudit,
+  exportCadf:        exportCadf,
   forensicSnapshot:  forensicSnapshot,
   verifyBundle:      verifyBundle,
   purge:             purge,