@blamejs/core 0.8.43 → 0.8.49

package/lib/audit-chain.js

@@ -1,22 +1,37 @@
 "use strict";
 /**
- * Audit hash chain — tamper-evidence math.
+ * @module b.auditChain
+ * @nav    Observability
+ * @title  Audit Chain Primitives
  *
- * Per the compliance spec ("Tamper evidence (the chain + checkpoint signing)"
- * in the roadmap):
+ * @intro
+ *   Low-level audit-chain hash + verify primitives — `b.audit` composes
+ *   on top of these so operators rarely call them directly. Every audit
+ *   row carries `prevHash` + `rowHash` + `nonce` and the chain math is:
  *
- *   rowHash = SHA3-512(
- *     prevHash || canonicalize(row-fields-except-hash) || nonce
- *   )
+ *     rowHash = SHA3-512(
+ *       prevHash || canonicalize(row-fields-except-hash) || nonce
+ *     )
  *
- * Each row's prevHash equals the previous row's rowHash (in monotonic-counter
- * order). The first row uses ZERO_HASH as prevHash. Verification walks the
- * chain forward; any row whose prevHash doesn't match the running hash, or
- * whose rowHash recomputes differently, breaks the chain.
+ *   Each row's `prevHash` equals the previous row's `rowHash` in
+ *   monotonic-counter order. The first row uses `ZERO_HASH` as the
+ *   anchor. `verifyChain` walks every row forward, recomputing each
+ *   hash; any mismatch returns `{ ok: false, reason, breakAt, ... }`
+ *   and the caller (audit boot, `b.cli verify-chain`, restore-rollback,
+ *   forensic snapshot) decides whether to refuse-to-boot or just log.
  *
- * Checkpoint signing (ML-DSA-87 over (atRow || atRowHash)) lives in
- * lib/audit-sign.js. This module owns the chain hash math only;
- * verification is O(n) and walks every row at boot.
+ *   Checkpoint signing (SLH-DSA-SHAKE-256f over `(atRow || atRowHash)`)
+ *   lives in `b.auditSign`. This module owns the chain hash math only;
+ *   verification is O(n) over `audit_log` rows.
+ *
+ *   Operators reach for `b.auditChain.verifyChain` directly when
+ *   restoring from backup (verify the restored DB before promoting it),
+ *   when running a forensic offline check, or when extending the chain
+ *   primitive into a custom append-only table. Day-to-day appends go
+ *   through `b.audit.record` / `b.audit.safeEmit`.
+ *
+ * @card
+ *   Low-level audit-chain hash + verify primitives — `b.audit` composes on top of these so operators rarely call them directly.
  */
 var canonicalJson = require("./canonical-json");
 var C = require("./constants");
@@ -31,13 +46,26 @@ var SHA3_512_HEX_LEN = SHA3_512_BYTES * 2;
 // All-zero SHA3-512 sentinel prevHash for the first row.
 var ZERO_HASH = "0".repeat(SHA3_512_HEX_LEN);
 
-// Canonicalize a row for hashing. Excludes the hash/nonce columns themselves
-// and any caller-specified columns. Sorted keys, JSON-encoded values; Buffer
-// values converted to hex for stable byte serialization. Routes through
-// the shared `lib/canonical-json` walker so the four canonicalize sites
-// (this one, audit-tools, config-drift, pagination) share one
-// implementation of the bug-class fix that started in v0.6.60 and
-// completed in v0.6.67.
+/**
+ * @primitive b.auditChain.canonicalize
+ * @signature b.auditChain.canonicalize(row, excludeKeys)
+ * @since     0.6.67
+ * @related   b.auditChain.computeRowHash
+ *
+ * RFC 8785 (JSON Canonicalization Scheme) serialization of an audit
+ * row's logical fields, used as the middle slice of the row-hash
+ * preimage. Sorted keys, Buffer values rendered as hex, every other
+ * value passed through the shared `lib/canonical-json` walker so the
+ * four canonicalize sites in the framework (chain, audit-tools,
+ * config-drift, pagination) emit byte-identical output.
+ *
+ * @example
+ *   var bytes = b.auditChain.canonicalize(
+ *     { actor: "u-42", action: "auth.login.success", recordedAt: 1700000000000 },
+ *     ["prevHash", "rowHash", "nonce"]
+ *   );
+ *   // → '{"action":"auth.login.success","actor":"u-42","recordedAt":1700000000000}'
+ */
 function canonicalize(row, excludeKeys) {
   var ex = new Set(excludeKeys || []);
   var keys = Object.keys(row).filter(function (k) { return !ex.has(k); }).sort();
@@ -48,8 +76,30 @@ function canonicalize(row, excludeKeys) {
   return canonicalJson.stringify(pairs);
 }
 
-// Compute a row's hash given its predecessor's hash, the row's logical fields
-// (already excluding prevHash, rowHash, nonce), and the row's nonce buffer.
+/**
+ * @primitive b.auditChain.computeRowHash
+ * @signature b.auditChain.computeRowHash(prevHash, rowFields, nonce)
+ * @since     0.4.0
+ * @related   b.auditChain.verifyChain, b.auditChain.canonicalize
+ *
+ * Compute a row's `rowHash` given its predecessor's hash, the row's
+ * logical fields (already excluding `prevHash` / `rowHash` / `nonce`),
+ * and the row's nonce buffer. The hash is `SHA3-512(prevHashBytes ||
+ * canonicalize(rowFields) || nonce)`, returned as a 128-char lowercase
+ * hex string.
+ *
+ * `prevHash` must be the 128-char hex form (use `b.auditChain.ZERO_HASH`
+ * for the chain anchor). `nonce` must be a non-empty Buffer; the
+ * framework writes 16 random bytes per row.
+ *
+ * @example
+ *   var rowHash = b.auditChain.computeRowHash(
+ *     b.auditChain.ZERO_HASH,
+ *     { action: "system.boot", recordedAt: 1700000000000, outcome: "success" },
+ *     Buffer.from("0123456789abcdef0123456789abcdef", "hex")
+ *   );
+ *   // → "<128-char SHA3-512 hex>"
+ */
 function computeRowHash(prevHash, rowFields, nonce) {
   if (typeof prevHash !== "string" || prevHash.length !== SHA3_512_HEX_LEN) {
     throw new Error("prevHash must be a " + SHA3_512_HEX_LEN +
@@ -68,9 +118,27 @@ function computeRowHash(prevHash, rowFields, nonce) {
   return sha3Hash(input);
 }
 
-// Read the current chain tip (last row's rowHash + monotonicCounter) for a
-// given audit table. Async to accommodate operator-supplied external-db
-// drivers; queryOneAsync is `async (sql, params?) → row | null`.
+/**
+ * @primitive b.auditChain.getChainTip
+ * @signature b.auditChain.getChainTip(queryOneAsync, tableName)
+ * @since     0.4.0
+ * @related   b.auditChain.verifyChain, b.auditChain.computeRowHash
+ *
+ * Read the current chain tip (last row's `rowHash` + `monotonicCounter`)
+ * for a given audit table. Empty tables return
+ * `{ prevHash: ZERO_HASH, counter: 0 }` so callers can treat first-row
+ * insert and append uniformly. Async so operator-supplied external-db
+ * drivers can use any await-able query function of the shape
+ * `async (sql, params?) -> row | null`.
+ *
+ * @example
+ *   async function queryOne(sql) {
+ *     var rows = await myDriver.query(sql);
+ *     return rows[0] || null;
+ *   }
+ *   var tip = await b.auditChain.getChainTip(queryOne, "audit_log");
+ *   // → { prevHash: "<128-char hex>", counter: 4217 }
+ */
 async function getChainTip(queryOneAsync, tableName) {
   var row = await queryOneAsync(
     'SELECT rowHash, monotonicCounter FROM "' + tableName + '" ' +
@@ -80,15 +148,36 @@ async function getChainTip(queryOneAsync, tableName) {
   return { prevHash: row.rowHash, counter: row.monotonicCounter };
 }
 
-// Walk the entire chain forward, recomputing each row's hash. Returns an
-// object describing the result; callers decide how to react (refuse-to-boot,
-// log warning, etc.). queryAllAsync is `async (sql, params?) → rows`.
-//
-// audit_log only: if a `_blamejs_audit_purge_anchor` row exists, the walk
-// starts at lastPurgedCounter+1 with prevHash = lastPurgedRowHash. The
-// anchor is written by audit-tools.purge() after a successful archive,
-// and lets the chain math survive deletion of historical rows without
-// the bundle as the source of truth.
+/**
+ * @primitive b.auditChain.verifyChain
+ * @signature b.auditChain.verifyChain(queryAllAsync, tableName, opts)
+ * @since     0.4.0
+ * @related   b.auditChain.getChainTip, b.audit.verify, b.auditTools.archive
+ *
+ * Walk the entire chain forward, recomputing each row's hash and
+ * comparing against the stored `prevHash` / `rowHash`. Returns
+ * `{ ok: true, table, rowsVerified, lastHash }` on a clean walk, or
+ * `{ ok: false, table, rowsVerified, breakAt, breakRowId, reason,
+ * expected, actual }` on the first mismatch. Callers decide how to
+ * react — `b.audit.verify` refuses-to-boot, `b.cli verify-chain`
+ * exits non-zero, `b.restoreRollback` blocks promotion.
+ *
+ * For `audit_log`: if a `_blamejs_audit_purge_anchor` row exists, the
+ * walk starts at `lastPurgedCounter+1` with `prevHash =
+ * lastPurgedRowHash`. The anchor is written by `b.auditTools.purge`
+ * after a successful archive and lets the chain math survive deletion
+ * of historical rows without the archive bundle as source of truth.
+ *
+ * @opts
+ *   {
+ *     maxRows?: number,   // stop after N rows (default: walk every row)
+ *   }
+ *
+ * @example
+ *   async function queryAll(sql) { return await myDriver.query(sql); }
+ *   var result = await b.auditChain.verifyChain(queryAll, "audit_log", {});
+ *   // → { ok: true, table: "audit_log", rowsVerified: 4217, lastHash: "<hex>" }
+ */
 async function verifyChain(queryAllAsync, tableName, opts) {
   opts = opts || {};
 

package/lib/audit-daily-review.js

@@ -0,0 +1,389 @@
+"use strict";
+/**
+ * @module b.auditDailyReview
+ * @nav    Compliance
+ * @title  Audit Daily Review
+ *
+ * @intro
+ *   PCI DSS 4.0 Req 10.4.1.1 daily-review primitive (mandatory
+ *   effective 2025-03-31). Automated review of all security event
+ *   logs, CHD/SAD components, critical system components, and security-
+ *   function components — surfacing anomalies and exceptions for
+ *   follow-up. The framework provides scheduling, query, severity
+ *   classification, and notify wiring; the operator supplies the
+ *   notify channel and any post-review workflow.
+ *
+ *   Adjacent regimes covered: HIPAA §164.308(a)(1)(ii)(D) (regular
+ *   review of activity records), SOX §302/§404 (quarterly self-
+ *   attestation), SOC 2 CC7.2 (anomaly identification and response),
+ *   GDPR Art. 32 (ongoing security testing/evaluation). When `posture`
+ *   is one of `pci-dss` / `hipaa` / `sox` / `soc2`, a `notify`
+ *   callback is mandatory at create-time — the regulators all demand
+ *   a follow-up channel.
+ *
+ *   Severity classification: `denied` / `failure` outcomes default to
+ *   `warning`; `auth.fail*` / `audit.read` / `csrf.bad_*` / `ato.*` /
+ *   `honeytoken.tripped` / `breakglass.*` / `ddl.change.applied`
+ *   raise to `alert`; `audit.tamper*` / `vault.aad.unseal_failed` /
+ *   `config.drift.detected` / `vendor.integrity.tampered` /
+ *   `ato.killSwitch.tripped` raise to `critical`. Operators with
+ *   richer rules pass `opts.classify(event) → severity`.
+ *
+ *   Audit events: `audit.daily_review.completed` (every run),
+ *   `.notified` (notify fired), `.notify_failed` (notify threw or
+ *   rejected; the review itself still completed), `.scheduled`,
+ *   `.stopped`.
+ *
+ * @card
+ *   PCI DSS 4.0 Req 10.4.1.1 daily-review primitive (mandatory effective 2025-03-31).
+ */
+
+var validateOpts = require("./validate-opts");
+var C = require("./constants");
+var { AuditDailyReviewError } = require("./framework-error");
+
+var SEVERITY_ORDER = ["info", "notice", "warning", "alert", "critical"];
+
+var ALERT_PATTERNS = [
+  /^auth\.(fail|failed|locked|denied|invalid)/,
+  /^audit\.read$/,
+  /^audit\.tamper/,
+  /^csrf\.bad_/,
+  /^ato\./,
+  /^honeytoken\.tripped/,
+  /^compliance\.posture\.set_rejected/,
+  /^audit\.actor_binding\.violation/,
+  /^ddl\.change\.applied/,
+  /^breakglass\./,
+];
+
+var CRITICAL_PATTERNS = [
+  /^audit\.tamper/,
+  /^vault\.aad\.unseal_failed/,
+  /^config\.drift\.detected/,
+  /^vendor\.integrity\.tampered/,
+  /^ato\.killSwitch\.tripped/,
+];
+
+var POSTURES_REQUIRING_NOTIFY = ["pci-dss", "hipaa", "sox", "soc2"];
+
+function _defaultClassify(event) {
+  if (!event || typeof event !== "object" || typeof event.action !== "string") {
+    return "info";
+  }
+  var action = event.action;
+  for (var i = 0; i < CRITICAL_PATTERNS.length; i++) {
+    if (CRITICAL_PATTERNS[i].test(action)) return "critical";
+  }
+  for (var j = 0; j < ALERT_PATTERNS.length; j++) {
+    if (ALERT_PATTERNS[j].test(action)) return "alert";
+  }
+  if (event.outcome === "denied" || event.outcome === "failure") return "warning";
+  return "info";
+}
+
+function _severityAtLeast(severity, threshold) {
+  var sIdx = SEVERITY_ORDER.indexOf(severity);
+  var tIdx = SEVERITY_ORDER.indexOf(threshold);
+  if (sIdx === -1 || tIdx === -1) return false;
+  return sIdx >= tIdx;
+}
+
+function _err(code, msg) {
+  return new AuditDailyReviewError(code, msg);
+}
+
+/**
+ * @primitive b.auditDailyReview.create
+ * @signature b.auditDailyReview.create(opts)
+ * @since     0.8.48
+ * @status    stable
+ * @compliance pci-dss, hipaa, sox-404, soc2, gdpr
+ * @related   b.audit, b.scheduler, b.compliance
+ *
+ * Build a daily-review scheduler. Returns
+ * `{ run, list, lastRun, schedule, start, stop, classify, posture,
+ * cron, severityThreshold, lookbackHours }`. `run()` executes a single
+ * review window on demand; `start()` arms the scheduler so the review
+ * fires on the configured cron; `list()` returns the bounded history
+ * buffer of past summaries.
+ *
+ * @opts
+ *   audit:             Object,     // b.audit instance (query / safeEmit)
+ *   scheduler:         Object,     // b.scheduler instance; required for start()
+ *   lookbackHours:     number,     // window size in hours (default 24)
+ *   severityThreshold: string,     // info|notice|warning|alert|critical (default "warning")
+ *   posture:           string,     // pci-dss | hipaa | sox-404 | soc2 | …
+ *   cron:              string,     // POSIX 5-field expr (default "0 6 * * *")
+ *   notify:            Function,   // async (summary) → void; required under listed postures
+ *   classify:          Function,   // (event) → severity; default action-prefix table
+ *   queryLimit:        number,     // max rows pulled from audit.query (default 10000)
+ *   historyLimit:      number,     // bounded summary buffer (default 30)
+ *   now:               Function,   // () → number; testing override
+ *
+ * @example
+ *   var review = b.auditDailyReview.create({
+ *     audit:             auditInstance,
+ *     scheduler:         schedulerInstance,
+ *     lookbackHours:     24,
+ *     severityThreshold: "warning",
+ *     posture:           "pci-dss",
+ *     cron:              "0 6 * * *",
+ *     notify:            async function (summary) {
+ *       if (summary.hitCount > 0) {
+ *         // page on-call with summary.thresholdHits
+ *       }
+ *     },
+ *   });
+ *
+ *   // On-demand:
+ *   var summary = await review.run();
+ *   summary.totalEvents;       // → 1842
+ *   summary.bySeverity;        // → { info: 1700, warning: 120, alert: 22, critical: 0, notice: 0 }
+ *   summary.hitCount;          // → 142  (events at-or-above warning)
+ *
+ *   // Or arm the scheduler so the review fires nightly at 06:00 UTC:
+ *   await review.start();
+ *   review.lastRun();          // → most recent summary or null
+ */
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "audit", "scheduler", "lookbackHours", "severityThreshold",
+    "posture", "cron", "notify", "classify", "queryLimit", "historyLimit",
+    "now",
+  ], "auditDailyReview.create");
+
+  validateOpts.auditShape(opts.audit, "auditDailyReview",
+    AuditDailyReviewError, "auditDailyReview/bad-audit");
+  if (!opts.audit) {
+    throw _err("auditDailyReview/audit-required",
+      "auditDailyReview.create: opts.audit is required (must expose query() / safeEmit())");
+  }
+  if (typeof opts.audit.query !== "function") {
+    throw _err("auditDailyReview/audit-query-missing",
+      "auditDailyReview.create: opts.audit.query must be a function");
+  }
+  validateOpts.optionalFunction(opts.notify,
+    "auditDailyReview: notify", AuditDailyReviewError, "auditDailyReview/bad-notify");
+  validateOpts.optionalFunction(opts.classify,
+    "auditDailyReview: classify", AuditDailyReviewError, "auditDailyReview/bad-classify");
+  validateOpts.optionalFunction(opts.now,
+    "auditDailyReview: now", AuditDailyReviewError, "auditDailyReview/bad-now");
+  validateOpts.optionalNonEmptyString(opts.posture,
+    "auditDailyReview: posture", AuditDailyReviewError, "auditDailyReview/bad-posture");
+  validateOpts.optionalNonEmptyString(opts.cron,
+    "auditDailyReview: cron", AuditDailyReviewError, "auditDailyReview/bad-cron");
+  validateOpts.optionalPositiveInt(opts.queryLimit,
+    "auditDailyReview: queryLimit", AuditDailyReviewError, "auditDailyReview/bad-querylimit");
+  validateOpts.optionalPositiveInt(opts.historyLimit,
+    "auditDailyReview: historyLimit", AuditDailyReviewError, "auditDailyReview/bad-historylimit");
+
+  // lookbackHours — default 24 per PCI DSS 4.0 daily cadence. Caller can
+  // pass weekly / monthly via larger numbers.
+  var lookbackHours = 24; // allow:raw-byte-literal — lookback in HOURS, not bytes
+  if (opts.lookbackHours !== undefined) {
+    if (typeof opts.lookbackHours !== "number" || !isFinite(opts.lookbackHours) ||
+        opts.lookbackHours <= 0) {
+      throw _err("auditDailyReview/bad-lookback",
+        "auditDailyReview.create: lookbackHours must be a positive finite number");
+    }
+    lookbackHours = opts.lookbackHours;
+  }
+
+  var severityThreshold = opts.severityThreshold || "warning";
+  if (SEVERITY_ORDER.indexOf(severityThreshold) === -1) {
+    throw _err("auditDailyReview/bad-severity",
+      "auditDailyReview.create: severityThreshold must be one of " +
+      SEVERITY_ORDER.join(", "));
+  }
+
+  var posture = opts.posture || null;
+  if (posture && POSTURES_REQUIRING_NOTIFY.indexOf(posture) !== -1 && !opts.notify) {
+    throw _err("auditDailyReview/notify-required-under-posture",
+      "auditDailyReview.create: posture '" + posture + "' requires notify callback " +
+      "(PCI DSS 10.4.1.1 / HIPAA §164.308(a)(1)(ii)(D) demand a follow-up channel)");
+  }
+
+  var cron = opts.cron || "0 6 * * *";   // 06:00 UTC daily
+  var queryLimit = opts.queryLimit || 10000;                                    // allow:raw-byte-literal — operator-tunable result cap, count not bytes
+  var historyLimit = opts.historyLimit || 30;                                   // allow:raw-byte-literal — bounded history buffer (count, not bytes)
+  var classify = typeof opts.classify === "function" ? opts.classify : _defaultClassify;
+  var now = typeof opts.now === "function" ? opts.now : Date.now;
+  var auditMod = opts.audit;
+  var notify = typeof opts.notify === "function" ? opts.notify : null;
+  var schedulerMod = opts.scheduler || null;
+
+  var history = [];
+  var taskName = "blamejs.auditDailyReview." + (posture || "default");
+  var armedScheduler = null;
+
+  function _emit(action, metadata, outcome) {
+    try {
+      auditMod.safeEmit({
+        action:   action,
+        outcome:  outcome || "success",
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* audit best-effort */ }
+  }
+
+  async function run() {
+    var startedAt = now();
+    var fromMs = startedAt - C.TIME.hours(lookbackHours);
+    var rows;
+    try {
+      rows = await auditMod.query({
+        from:  fromMs,
+        to:    startedAt,
+        limit: queryLimit,
+      });
+    } catch (e) {
+      _emit("audit.daily_review.failed", {
+        reason: (e && e.message) || String(e),
+        lookbackHours: lookbackHours,
+      }, "failure");
+      throw _err("auditDailyReview/query-failed",
+        "auditDailyReview.run: audit.query failed: " + ((e && e.message) || String(e)));
+    }
+
+    var bySeverity = { info: 0, notice: 0, warning: 0, alert: 0, critical: 0 };
+    var byOutcome  = { success: 0, failure: 0, denied: 0, other: 0 };
+    var byNamespace = Object.create(null);
+    var thresholdHits = [];
+    for (var i = 0; i < rows.length; i++) {
+      var r = rows[i];
+      var sev = classify(r);
+      if (bySeverity[sev] === undefined) bySeverity[sev] = 0;
+      bySeverity[sev]++;
+
+      var oc = r && r.outcome;
+      if (oc === "success" || oc === "failure" || oc === "denied") byOutcome[oc]++;
+      else byOutcome.other++;
+
+      var ns = (r && typeof r.action === "string") ? r.action.split(".")[0] : "unknown";
+      byNamespace[ns] = (byNamespace[ns] || 0) + 1;
+
+      if (_severityAtLeast(sev, severityThreshold)) {
+        thresholdHits.push({
+          action:   r.action,
+          outcome:  r.outcome,
+          severity: sev,
+          recordedAt: r.recordedAt,
+          actorUserId: r.actorUserId || null,
+          requestId: r.requestId || null,
+        });
+      }
+    }
+
+    var summary = {
+      runAt:           new Date(startedAt).toISOString(),
+      lookbackHours:   lookbackHours,
+      windowFromMs:    fromMs,
+      windowToMs:      startedAt,
+      totalEvents:     rows.length,
+      bySeverity:      bySeverity,
+      byOutcome:       byOutcome,
+      byNamespace:     byNamespace,
+      severityThreshold: severityThreshold,
+      thresholdHits:   thresholdHits,
+      hitCount:        thresholdHits.length,
+      durationMs:      now() - startedAt,
+      posture:         posture,
+    };
+
+    history.push(summary);
+    if (history.length > historyLimit) history.splice(0, history.length - historyLimit);
+
+    _emit("audit.daily_review.completed", {
+      lookbackHours: lookbackHours,
+      totalEvents:   summary.totalEvents,
+      hitCount:      summary.hitCount,
+      durationMs:    summary.durationMs,
+      posture:       posture,
+    });
+
+    if (notify && thresholdHits.length > 0) {
+      try {
+        await notify(summary);
+        _emit("audit.daily_review.notified", {
+          hitCount: thresholdHits.length, posture: posture,
+        });
+      } catch (e) {
+        _emit("audit.daily_review.notify_failed", {
+          reason: (e && e.message) || String(e),
+          hitCount: thresholdHits.length, posture: posture,
+        }, "failure");
+        // Don't throw — the daily review completed, only notify failed.
+        // Operators read audit.daily_review.notify_failed to chase down
+        // their notify-channel outage.
+      }
+    }
+
+    return summary;
+  }
+
+  function lastRun() {
+    return history.length > 0 ? history[history.length - 1] : null;
+  }
+
+  function list() {
+    return history.slice();
+  }
+
+  function schedule() {
+    return cron;
+  }
+
+  async function start() {
+    if (!schedulerMod) {
+      throw _err("auditDailyReview/no-scheduler",
+        "auditDailyReview.start: opts.scheduler is required to arm the cron firing — " +
+        "operators without a scheduler call run() on their own cadence");
+    }
+    if (armedScheduler) return;
+    armedScheduler = schedulerMod;
+    armedScheduler.schedule({
+      name: taskName,
+      cron: cron,
+      run:  run,
+    });
+    if (typeof armedScheduler.start === "function") {
+      // Scheduler.start() is idempotent — safe to call when the scheduler
+      // was already armed by other tasks.
+      try { await armedScheduler.start(); } catch (_e) { /* operator-controlled */ }
+    }
+    _emit("audit.daily_review.scheduled", {
+      cron: cron, taskName: taskName, posture: posture,
+    });
+  }
+
+  async function stop() {
+    if (!armedScheduler) return;
+    armedScheduler = null;
+    _emit("audit.daily_review.stopped", { taskName: taskName, posture: posture });
+  }
+
+  return {
+    run:        run,
+    list:       list,
+    lastRun:    lastRun,
+    schedule:   schedule,
+    start:      start,
+    stop:       stop,
+    classify:   classify,
+    posture:    posture,
+    cron:       cron,
+    severityThreshold: severityThreshold,
+    lookbackHours:     lookbackHours,
+  };
+}
+
+module.exports = {
+  create: create,
+  SEVERITY_ORDER:           SEVERITY_ORDER,
+  ALERT_PATTERNS:           ALERT_PATTERNS,
+  CRITICAL_PATTERNS:        CRITICAL_PATTERNS,
+  POSTURES_REQUIRING_NOTIFY: POSTURES_REQUIRING_NOTIFY,
+  AuditDailyReviewError:    AuditDailyReviewError,
+};