@blamejs/core 0.8.8 → 0.8.9

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.8.x
 
+- **0.8.9** (2026-05-07) — `b.incident.report` — generic 3-stage incident-reporting primitive. The three stages mirror the deadline pattern that recurs across regulatory regimes: initial / early-warning notification (within 24h of detection), intermediate / status update (within 72h), final report (within 30d or per-regime deadline). Built-in per-regime deadlines for `gdpr` (Article 33), `nis2` (Article 23), `dora` (Article 19), `cra` (Article 14), `hipaa` (Breach Notification Rule); operators select via `regime: "gdpr"` and `opts.deadlines` can override per-stage. Each stage records a tamper-evident audit event (`incident.report.stage_recorded`) with a `late: bool` + `lateBy: ms` flag — late filings are recorded with `outcome: "late"` so regulator audits can distinguish on-time from late-but-eventually filings. Operator-supplied `persist(record)` writes to a DB / SIEM / SOAR system; `onStage(event)` fires for synchronous routing. `status()` returns aggregate counts (open / closed / late-per-stage) for dashboards.
+
 - **0.8.8** (2026-05-07) — `b.middleware.requireBoundKey` + `b.audit.rotateSigningKey` / `reSignAll` + `b.circuitBreaker` top-level surface + `b.htmlBalance.checkSafe` + permissions predicate-shape audit + FIPS 140-3 boundary docs + ESLint pin. **`b.middleware.requireBoundKey`** — Bearer-API-key middleware with three-axis binding: required scopes, bound-field equality (operator pulls values from headers / query / body via `getBoundField` getters; bound-fields registered on the key are checked with constant-time match), and peer-cert fingerprint allowlist (composes with v0.8.4's `b.crypto.hashCertFingerprint` / `isCertRevoked`). Operator-supplied async `resolver(apiKey)` returns the registered record `{ id, scopes, boundFields, peerCertFingerprints }` or `null` when revoked. Refusals carry structured reasons (`no-bearer-token`, `key-unknown-or-revoked`, `missing-scope`, `bound-field-missing`, `bound-field-mismatch`, `peer-cert-required`, `peer-cert-not-pinned`); audit chain captures the keyId + reason on every refusal. **`b.audit.rotateSigningKey`** — operator-callable rotation of the audit-signing keypair. Generates (or accepts BYO) a new keypair, copies the existing sealed file to a timestamped history path so historical signatures remain verifiable, re-seals with the operator's passphrase, and atomic-swaps the in-memory keys. Companion `reSignAll(iter)` walks an operator-supplied async iterable of `{ payload, signature, oldPublicKeyPem }` and re-signs each entry with the new key — the audit module's checkpoint store calls this to re-stamp historical checkpoints after a rotation. **`b.circuitBreaker`** — top-level re-export of `b.retry.CircuitBreaker` so operators discover it alongside `b.retry`; same state machine, same `wrap()` API, ergonomic `create(opts)` factory. **`b.htmlBalance.checkSafe(html, opts)`** — combines structural `balance()` check with a `b.guardHtml.gate` security pass under the same `{ profile, posture }` opt shape used by `b.fileUpload({ contentSafety })` / `b.staticServe({ contentSafety })`. **`b.permissions.policy(scope, predicate)`** — emits `permissions.policy_predicate_shape_warning` audit on register-time when the predicate's `.length < 2` (operators commonly forget the `context` argument and ship a predicate that's always-true on the actor parameter). **`SECURITY.md`** — new "FIPS 140-3 cryptographic boundary" section explaining the dual boundary (Node.js OpenSSL FIPS provider for classical primitives, vendored noble-* implementations for PQ algorithms — the latter implement FIPS-published algorithms but the *implementations themselves* are not CMVP-validated). Operator path for FIPS-mandated environments documented. **CI** — eslint pinned to `10.3.0` across `ci.yml` / `npm-publish.yml` / `release-container.yml`; `eslint@latest` was silently letting new rule additions break the publish gate on releases that had passed the day before. The pin moves on operator-confirmed bumps.
 
 - **0.8.7** (2026-05-06) — `b.auth.accessLock` — three-mode access-lock primitive for stop-the-world / read-only / role-restricted operator interventions. `"open"` is normal operation; `"read-only"` refuses non-idempotent methods (POST/PUT/PATCH/DELETE) with 503 + Retry-After while letting GET/HEAD/OPTIONS pass; `"locked"` refuses everything except an operator-supplied `passthroughPaths` allowlist (status / health / unlock endpoint). Operators flip modes during incident response, schema-migration windows, or break-glass review via `lock.set("locked", { actor, reason })`; the transition emits `auth.access_lock.mode_changed` audit + metric. `unlockRoles: ["sre", ...]` lets a privileged role bypass all three modes via `getRole(req)` so a break-glass operator can always reach the unlock endpoint to flip back. The boot-time mode emits `auth.access_lock.boot` so the audit chain captures the deploy posture.

package/index.js

@@ -248,6 +248,7 @@ module.exports = {
   objectStore:      objectStore,
   retry:            retry,
   circuitBreaker:   require("./lib/circuit-breaker"),
+  incident:         { report: require("./lib/incident-report") },
   queue:            queue,
   logStream:        logStream,
   redact:           redact,

package/lib/incident-report.js

@@ -0,0 +1,314 @@
+"use strict";
+/**
+ * b.incident.report — generic 3-stage incident-reporting primitive.
+ *
+ * The three stages mirror the deadline pattern that recurs across
+ * regulatory regimes (GDPR Article 33 / NIS2 Article 23 / DORA
+ * Article 19 / CRA Article 14 / HIPAA Breach Notification Rule):
+ *
+ *   1. Initial / early-warning notification — within 24 hours of
+ *      detection. Operators report what they know: scope, suspected
+ *      cause, immediate-mitigation plan.
+ *   2. Intermediate / status update — within 72 hours of detection.
+ *      Updated impact assessment, root-cause analysis progress,
+ *      operator's response posture.
+ *   3. Final report — within 30 days of detection (or per-regime
+ *      deadline). Full incident narrative, affected-data-subject
+ *      count, remediation, lessons learned.
+ *
+ *   var ir = b.incident.report.create({
+ *     audit:    b.audit,
+ *     persist:  async function (record) { await db.run("INSERT ..."); },
+ *     onStage:  function (event) {
+ *       // event = { incidentId, stage: "initial"|"intermediate"|"final",
+ *       //           dueBy, regime, fields }
+ *     },
+ *     deadlines: {                                  // operator-overridable per regime
+ *       initial:      C.TIME.hours(24),
+ *       intermediate: C.TIME.hours(72),
+ *       final:        C.TIME.days(30),
+ *     },
+ *   });
+ *   var incident = await ir.open({
+ *     regime:       "gdpr",                         // identifies the regulatory regime
+ *     detectedAt:   Date.now(),
+ *     scope:        "data-confidentiality-breach",
+ *     summary:      "...",
+ *     impact:       { dataSubjects: 1200, categories: ["pii", "phi"] },
+ *   });
+ *   await ir.recordInitial(incident.id, { ... });
+ *   await ir.recordIntermediate(incident.id, { ... });
+ *   await ir.recordFinal(incident.id, { ... });
+ *
+ * Each stage records a tamper-evident audit event with the regime,
+ * incident ID, stage, due-by timestamp, and operator-supplied
+ * payload. The `persist` hook writes to the operator's incident
+ * registry (DB / SIEM / SOAR system); audits give regulator-friendly
+ * proof-of-process when the primitive is queried later.
+ *
+ * Late-stage detection (filing past the due-by) is recorded with a
+ * `lateBy` field on the audit metadata and `outcome: "late"`, so
+ * regulator audits can distinguish "filed on time" from "filed late
+ * but eventually". Refusing to record at all would lose the data;
+ * the framework's posture is "always record, always flag late".
+ */
+
+var C = require("./constants");
+var defineClass = require("./framework-error").defineClass;
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+
+var audit = lazyRequire(function () { return require("./audit"); });
+var observability = lazyRequire(function () { return require("./observability"); });
+
+var IncidentReportError = defineClass("IncidentReportError", { alwaysPermanent: true });
+
+var DEFAULT_DEADLINES = Object.freeze({
+  initial:      C.TIME.hours(24),
+  intermediate: C.TIME.hours(72),
+  final:        C.TIME.days(30),
+});
+
+var VALID_STAGES = Object.freeze({ initial: 1, intermediate: 1, final: 1 });
+
+// Regime defaults — operators select these via opts.regime so the
+// per-regime deadline shape is the framework default, not something
+// the operator has to redefine each time. Operators with mixed
+// regimes per incident pick the shortest deadline (the "first wall
+// to hit" rule). Per-regime overrides go on opts.deadlines and
+// override the regime defaults.
+var REGIME_DEADLINES = Object.freeze({
+  // GDPR Article 33 §1: notify within 72 hours of awareness.
+  // No formal "initial" stage — the framework adds an internal
+  // 24-hour initial-warning checkpoint as a practical posture.
+  gdpr: Object.freeze({
+    initial:      C.TIME.hours(24),
+    intermediate: C.TIME.hours(72),
+    final:        C.TIME.days(30),
+  }),
+  // NIS2 Directive Article 23 §4: early warning within 24h, full
+  // notification within 72h, final report within 1 month.
+  nis2: Object.freeze({
+    initial:      C.TIME.hours(24),
+    intermediate: C.TIME.hours(72),
+    final:        C.TIME.days(30),
+  }),
+  // DORA (EU Digital Operational Resilience Act) Article 19: initial
+  // within 4h of classification, intermediate within 24h, final
+  // within 1 month.
+  dora: Object.freeze({
+    initial:      C.TIME.hours(4),
+    intermediate: C.TIME.hours(24),
+    final:        C.TIME.days(30),
+  }),
+  // CRA (EU Cyber Resilience Act) Article 14: early warning within
+  // 24h, vulnerability/incident notification within 72h, final
+  // report within 14 days.
+  cra: Object.freeze({
+    initial:      C.TIME.hours(24),
+    intermediate: C.TIME.hours(72),
+    final:        C.TIME.days(14),
+  }),
+  // HIPAA Breach Notification Rule (45 CFR §164.404 etc.): notify
+  // affected individuals within 60 days; HHS within 60 days for
+  // breaches affecting 500+ individuals (annually otherwise). The
+  // initial / intermediate stages have no statutory deadline; we
+  // adopt the EU 24/72-hour internal checkpoints as good operator
+  // practice.
+  hipaa: Object.freeze({
+    initial:      C.TIME.hours(24),
+    intermediate: C.TIME.hours(72),
+    final:        C.TIME.days(60),
+  }),
+});
+
+function _resolveDeadlines(regime, override) {
+  var base = (regime && REGIME_DEADLINES[regime]) || DEFAULT_DEADLINES;
+  if (!override || typeof override !== "object") return base;
+  return Object.freeze({
+    initial:      typeof override.initial      === "number" ? override.initial      : base.initial,
+    intermediate: typeof override.intermediate === "number" ? override.intermediate : base.intermediate,
+    final:        typeof override.final        === "number" ? override.final        : base.final,
+  });
+}
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "audit", "persist", "onStage", "deadlines", "now",
+  ], "incident.report");
+
+  var auditOn = opts.audit !== false;
+  var persist = typeof opts.persist === "function" ? opts.persist : null;
+  var onStage = typeof opts.onStage === "function" ? opts.onStage : null;
+  var deadlinesOverride = opts.deadlines || null;
+  var now = typeof opts.now === "function" ? opts.now : function () { return Date.now(); };
+
+  // In-memory registry — operators wire `persist` for durable
+  // storage. The in-memory map is for unit tests + small operator
+  // deployments that don't yet wire a DB-backed registry.
+  var incidents = new Map();
+  var seq = 0;
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   "incident.report." + action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+  function _emitMetric(verb, n, labels) {
+    try { observability().safeEvent("incident.report." + verb, n || 1, labels || {}); }
+    catch (_e) { /* drop-silent */ }
+  }
+
+  function _genIncidentId(regime, detectedAt) {
+    seq += 1;
+    var ts = new Date(detectedAt).toISOString().replace(/[:.]/g, "-");
+    return "incident-" + (regime || "generic") + "-" + ts + "-" + seq;
+  }
+
+  async function open(spec) {
+    if (!spec || typeof spec !== "object") {
+      throw new IncidentReportError("incident-report/bad-spec",
+        "incident.report.open: spec must be an object with { regime, detectedAt, scope, summary, impact }");
+    }
+    if (typeof spec.regime !== "string" || spec.regime.length === 0) {
+      throw new IncidentReportError("incident-report/bad-regime",
+        "incident.report.open: spec.regime must be a non-empty string (gdpr / nis2 / dora / cra / hipaa or operator-defined)");
+    }
+    if (typeof spec.detectedAt !== "number" || !isFinite(spec.detectedAt)) {
+      throw new IncidentReportError("incident-report/bad-detected-at",
+        "incident.report.open: spec.detectedAt must be a finite Unix-ms timestamp");
+    }
+    var deadlines = _resolveDeadlines(spec.regime, deadlinesOverride);
+    var id = _genIncidentId(spec.regime, spec.detectedAt);
+    var record = {
+      id:           id,
+      regime:       spec.regime,
+      detectedAt:   spec.detectedAt,
+      scope:        spec.scope || null,
+      summary:      spec.summary || null,
+      impact:       spec.impact || null,
+      deadlines:    deadlines,
+      dueBy: {
+        initial:      spec.detectedAt + deadlines.initial,
+        intermediate: spec.detectedAt + deadlines.intermediate,
+        final:        spec.detectedAt + deadlines.final,
+      },
+      stages:       {},                                                                  // populated by recordInitial / recordIntermediate / recordFinal
+      openedAt:     now(),
+      closedAt:     null,
+    };
+    incidents.set(id, record);
+    _emitAudit("opened", "success", {
+      incidentId: id, regime: spec.regime, detectedAt: spec.detectedAt,
+      dueByInitial:      record.dueBy.initial,
+      dueByIntermediate: record.dueBy.intermediate,
+      dueByFinal:        record.dueBy.final,
+    });
+    _emitMetric("opened", 1, { regime: spec.regime });
+    if (persist) {
+      try { await persist(record); }
+      catch (e) { _emitAudit("persist_failed", "failure", { incidentId: id, error: (e && e.message) || String(e) }); }
+    }
+    return record;
+  }
+
+  async function _recordStage(incidentId, stage, payload) {
+    if (!VALID_STAGES[stage]) {
+      throw new IncidentReportError("incident-report/bad-stage",
+        "incident.report._recordStage: stage must be one of " + Object.keys(VALID_STAGES).join(", "));
+    }
+    var rec = incidents.get(incidentId);
+    if (!rec) {
+      throw new IncidentReportError("incident-report/unknown-incident",
+        "incident.report: no incident with id '" + incidentId + "'");
+    }
+    if (rec.stages[stage]) {
+      throw new IncidentReportError("incident-report/stage-already-filed",
+        "incident.report: incident '" + incidentId + "' already has a '" + stage + "' stage filing");
+    }
+    var nowMs = now();
+    var dueBy = rec.dueBy[stage];
+    var late = nowMs > dueBy;
+    var lateBy = late ? (nowMs - dueBy) : 0;
+    rec.stages[stage] = {
+      filedAt:  nowMs,
+      dueBy:    dueBy,
+      late:     late,
+      lateBy:   lateBy,
+      payload:  payload || {},
+    };
+    if (stage === "final") rec.closedAt = nowMs;
+
+    _emitAudit("stage_recorded", late ? "late" : "success", {
+      incidentId: incidentId, regime: rec.regime, stage: stage,
+      dueBy: dueBy, filedAt: nowMs, late: late, lateBy: lateBy,
+    });
+    _emitMetric("stage_recorded", 1, { regime: rec.regime, stage: stage, late: String(late) });
+    if (onStage) {
+      try { onStage({ incidentId: incidentId, stage: stage, dueBy: dueBy, late: late, regime: rec.regime, fields: payload }); }
+      catch (_e) { /* drop-silent — operator hook */ }
+    }
+    if (persist) {
+      try { await persist(rec); }
+      catch (e) { _emitAudit("persist_failed", "failure", { incidentId: incidentId, stage: stage, error: (e && e.message) || String(e) }); }
+    }
+    return rec;
+  }
+
+  function recordInitial(incidentId, payload)      { return _recordStage(incidentId, "initial",      payload); }
+  function recordIntermediate(incidentId, payload) { return _recordStage(incidentId, "intermediate", payload); }
+  function recordFinal(incidentId, payload)        { return _recordStage(incidentId, "final",        payload); }
+
+  function get(incidentId) { return incidents.get(incidentId) || null; }
+  function list() {
+    var out = [];
+    incidents.forEach(function (rec) { out.push(rec); });
+    return out;
+  }
+
+  // Operator-facing summary for dashboards / regulator-prep — counts
+  // open / late / closed across all tracked regimes.
+  function status() {
+    var nowMs = now();
+    var summary = {
+      total:  incidents.size,
+      open:   0,
+      closed: 0,
+      late:   { initial: 0, intermediate: 0, final: 0 },
+    };
+    incidents.forEach(function (rec) {
+      if (rec.closedAt) summary.closed += 1; else summary.open += 1;
+      ["initial", "intermediate", "final"].forEach(function (s) {
+        if (!rec.stages[s] && nowMs > rec.dueBy[s]) summary.late[s] += 1;
+        else if (rec.stages[s] && rec.stages[s].late) summary.late[s] += 1;
+      });
+    });
+    return summary;
+  }
+
+  return {
+    open:               open,
+    recordInitial:      recordInitial,
+    recordIntermediate: recordIntermediate,
+    recordFinal:        recordFinal,
+    get:                get,
+    list:               list,
+    status:             status,
+    REGIME_DEADLINES:   REGIME_DEADLINES,
+    DEFAULT_DEADLINES:  DEFAULT_DEADLINES,
+  };
+}
+
+module.exports = {
+  create:                create,
+  IncidentReportError:   IncidentReportError,
+  REGIME_DEADLINES:      REGIME_DEADLINES,
+  DEFAULT_DEADLINES:     DEFAULT_DEADLINES,
+  VALID_STAGES:          Object.keys(VALID_STAGES),
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.8.8",
+  "version": "0.8.9",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:44e2ace4-98b8-425c-a2f3-bd209fde34f3",
+  "serialNumber": "urn:uuid:b2addb57-b40a-4a44-9c34-7f7bd7d741c3",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-07T01:56:20.867Z",
+    "timestamp": "2026-05-07T02:18:24.599Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.8.8",
+      "bom-ref": "@blamejs/core@0.8.9",
       "type": "library",
       "name": "blamejs",
-      "version": "0.8.8",
+      "version": "0.8.9",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.8.8",
+      "purl": "pkg:npm/%40blamejs/core@0.8.9",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.8.8",
+      "ref": "@blamejs/core@0.8.9",
       "dependsOn": []
     }
   ]