@blamejs/core 0.8.8 → 0.8.10

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.8.x
 
+- **0.8.10** (2026-05-07) — Five new compliance / regulatory primitives composing on v0.8.9's `b.incident.report`. **`b.cra.report`** — EU Cyber Resilience Act (Regulation (EU) 2024/2847) Article 14 §1 incident reporting wrapper. Three-stage statutory deadlines: 24h early warning / 72h incident notification / 14d final report. Required `productId` + `manufacturer` per Annex VII §1. Optional ENISA submission via `opts.enisaEndpoint` + `b.httpClient`; submission is operator-opt-in per stage call (regulators uniformly require operator review before filing). **`b.nis2.report`** — NIS2 Directive (Directive (EU) 2022/2555) Article 23 §4 incident reporting wrapper. Three-stage deadlines: 24h / 72h / 1 month. Annex I (essential) / Annex II (important) entity classification + sector codes (`I.6` drinking water / `II.6` digital providers / etc.). **`b.gdpr.ropa`** — GDPR Article 30 Records of Processing Activities registry + JSON / CSV / Markdown exporter. Validates required fields per Article 30 §1; legal-basis enum per Article 6(1); produces a regulator-friendly RoPA document for the operator's DPO to file. **`b.compliance.eaa`** — EU Accessibility Act (Directive (EU) 2019/882) Article 13 declared-conformance generator. Operators declare per-criterion conformance against WCAG 2.1/2.2 AA / EN 301 549; non-conformances ship with reason + mitigation. JSON / Markdown export for the operator's accessibility statement. **`b.middleware.botDisclose`** — California SB 1001 (Cal. Bus. & Prof. Code §17941) bot-disclosure middleware. Injects a disclosure banner into HTML responses, sets `X-Bot-Disclosure` header for API consumers, audits every conversation-initiating request. Operators wire `mountPaths` to scope and `bannerHtml` for visual customization.
+
+- **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

@@ -98,7 +98,9 @@ var safeUrl = require("./lib/safe-url");
 var safeRedirect = require("./lib/safe-redirect");
 var pick = require("./lib/pick");
 var dora = require("./lib/dora");
-var compliance = require("./lib/compliance");
+var compliance = Object.assign({}, require("./lib/compliance"), {
+  eaa: require("./lib/compliance-eaa"),
+});
 var gateContract = require("./lib/gate-contract");
 var guardCsv = require("./lib/guard-csv");
 var guardHtml = require("./lib/guard-html");
@@ -248,6 +250,10 @@ module.exports = {
   objectStore:      objectStore,
   retry:            retry,
   circuitBreaker:   require("./lib/circuit-breaker"),
+  incident:         { report: require("./lib/incident-report") },
+  cra:              { report: require("./lib/cra-report") },
+  nis2:             { report: require("./lib/nis2-report") },
+  gdpr:             { ropa: require("./lib/gdpr-ropa") },
   queue:            queue,
   logStream:        logStream,
   redact:           redact,

package/lib/compliance-eaa.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * b.compliance.eaa — EU Accessibility Act declared-conformance.
+ *
+ * Directive (EU) 2019/882 (the European Accessibility Act) requires
+ * digital products + services placed on the EU market to meet WCAG
+ * 2.1 AA accessibility requirements (extended to 2.2 by national
+ * implementing law in many member states). Operators producing a
+ * compliant deployment ship a "conformance statement" — a document
+ * declaring the product, the assessed standards (WCAG 2.1 / 2.2 /
+ * EN 301 549), the scope of testing, and any non-conforming
+ * features with operator-supplied justification.
+ *
+ *   var eaa = b.compliance.eaa.create({
+ *     audit:        b.audit,
+ *     productName:  "Acme Customer Portal",
+ *     productScope: "https://portal.acme.example",
+ *     standards:    ["WCAG 2.2 AA", "EN 301 549 v3.2.1"],
+ *   });
+ *   eaa.declareCriterion("1.1.1", { conformance: "supports", note: "..." });
+ *   eaa.declareCriterion("1.4.3", { conformance: "supports", note: "ratio >= 4.5:1" });
+ *   eaa.declareNonConformance({
+ *     criterion: "2.5.5",
+ *     reason:    "legacy desktop-only interaction, replacement Q3 2026",
+ *     mitigation: "alternative keyboard path documented",
+ *   });
+ *   var doc = eaa.export({ format: "markdown" });
+ *
+ * The exported document goes alongside the operator's product
+ * documentation and serves as the "Accessibility Statement" required
+ * by Article 13 §3.
+ */
+
+var defineClass = require("./framework-error").defineClass;
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+var ComplianceEaaError = defineClass("ComplianceEaaError", { alwaysPermanent: true });
+
+var VALID_CONFORMANCE = Object.freeze({
+  "supports":          1,                                                                // criterion fully met
+  "partially-supports": 1,                                                               // some content meets, gaps documented
+  "does-not-support":  1,                                                                // criterion not met (declared non-conformance)
+  "not-applicable":    1,                                                                // criterion does not apply to product
+  "not-evaluated":     1,                                                                // outside the assessed scope
+});
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "audit", "productName", "productScope", "standards",
+    "contact", "supervisoryAuthority", "now",
+  ], "compliance.eaa");
+
+  validateOpts.requireNonEmptyString(opts.productName,
+    "compliance.eaa.create: opts.productName is required (Article 13 §3 requires product identification)",
+    ComplianceEaaError, "compliance-eaa/bad-product");
+  if (!Array.isArray(opts.standards) || opts.standards.length === 0) {
+    throw new ComplianceEaaError("compliance-eaa/bad-standards",
+      "compliance.eaa.create: opts.standards is required (e.g. ['WCAG 2.2 AA', 'EN 301 549 v3.2.1'])");
+  }
+  var productName = opts.productName;
+  var productScope = opts.productScope || null;
+  var standards = opts.standards.slice();
+  var contact = opts.contact || null;
+  var supervisoryAuthority = opts.supervisoryAuthority || null;
+  var auditOn = opts.audit !== false;
+  var now = typeof opts.now === "function" ? opts.now : function () { return Date.now(); };
+
+  var criteria = new Map();
+  var nonConformances = [];
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   "compliance.eaa." + action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+
+  function declareCriterion(id, decl) {
+    if (typeof id !== "string" || id.length === 0) {
+      throw new ComplianceEaaError("compliance-eaa/bad-criterion-id",
+        "compliance.eaa.declareCriterion: id must be a non-empty string (e.g. '1.1.1')");
+    }
+    if (!decl || typeof decl !== "object") {
+      throw new ComplianceEaaError("compliance-eaa/bad-decl",
+        "compliance.eaa.declareCriterion: decl must be an object with { conformance, note? }");
+    }
+    if (!VALID_CONFORMANCE[decl.conformance]) {
+      throw new ComplianceEaaError("compliance-eaa/bad-conformance",
+        "compliance.eaa.declareCriterion: conformance must be one of " + Object.keys(VALID_CONFORMANCE).join(", "));
+    }
+    criteria.set(id, {
+      criterion:   id,
+      conformance: decl.conformance,
+      note:        decl.note || "",
+      declaredAt:  now(),
+    });
+    _emitAudit("criterion_declared", "success", { criterion: id, conformance: decl.conformance });
+  }
+
+  function declareNonConformance(decl) {
+    if (!decl || typeof decl !== "object" || !decl.criterion || !decl.reason) {
+      throw new ComplianceEaaError("compliance-eaa/bad-non-conformance",
+        "compliance.eaa.declareNonConformance: decl must include { criterion, reason, mitigation? }");
+    }
+    nonConformances.push({
+      criterion:   decl.criterion,
+      reason:      decl.reason,
+      mitigation:  decl.mitigation || null,
+      declaredAt:  now(),
+    });
+    criteria.set(decl.criterion, {
+      criterion:   decl.criterion,
+      conformance: "does-not-support",
+      note:        decl.reason + (decl.mitigation ? " (mitigation: " + decl.mitigation + ")" : ""),
+      declaredAt:  now(),
+    });
+    _emitAudit("non_conformance_declared", "warning", { criterion: decl.criterion });
+  }
+
+  function _stats() {
+    var counts = { supports: 0, "partially-supports": 0, "does-not-support": 0, "not-applicable": 0, "not-evaluated": 0 };
+    criteria.forEach(function (c) { counts[c.conformance] += 1; });
+    return counts;
+  }
+
+  function _exportJson() {
+    var c = []; criteria.forEach(function (rec) { c.push(rec); });
+    return {
+      directive:            "(EU) 2019/882",
+      article:              "13",
+      generatedAt:          new Date(now()).toISOString(),
+      product:              { name: productName, scope: productScope },
+      standards:            standards,
+      contact:              contact,
+      supervisoryAuthority: supervisoryAuthority,
+      criteria:             c,
+      nonConformances:      nonConformances,
+      stats:                _stats(),
+    };
+  }
+  function _exportMarkdown() {
+    var stats = _stats();
+    var c = []; criteria.forEach(function (rec) { c.push(rec); });
+    var md = "# Accessibility Statement — " + productName + "\n\n";
+    md += "**Standards:** " + standards.join(", ") + "\n\n";
+    if (productScope) md += "**Scope:** " + productScope + "\n\n";
+    md += "Generated: " + new Date(now()).toISOString() + "\n\n";
+    md += "## Conformance summary\n\n";
+    md += "- Supports: " + stats.supports + "\n";
+    md += "- Partially supports: " + stats["partially-supports"] + "\n";
+    md += "- Does not support: " + stats["does-not-support"] + "\n";
+    md += "- Not applicable: " + stats["not-applicable"] + "\n\n";
+    if (nonConformances.length > 0) {
+      md += "## Non-conformances\n\n";
+      for (var i = 0; i < nonConformances.length; i++) {
+        var nc = nonConformances[i];
+        md += "### " + nc.criterion + "\n\n";
+        md += "- Reason: " + nc.reason + "\n";
+        if (nc.mitigation) md += "- Mitigation: " + nc.mitigation + "\n";
+        md += "\n";
+      }
+    }
+    md += "## Per-criterion declarations\n\n";
+    for (var ci = 0; ci < c.length; ci++) {
+      md += "- **" + c[ci].criterion + "** — " + c[ci].conformance;
+      if (c[ci].note) md += " — " + c[ci].note;
+      md += "\n";
+    }
+    if (contact) md += "\n## Contact\n\n" + (contact.name || "") + " (" + (contact.email || "") + ")\n";
+    return md;
+  }
+
+  function exportEaa(eopts) {
+    eopts = eopts || {};
+    var format = (eopts.format || "json").toLowerCase();
+    _emitAudit("exported", "success", { format: format, criteriaCount: criteria.size });
+    if (format === "json")     return _exportJson();
+    if (format === "markdown") return _exportMarkdown();
+    throw new ComplianceEaaError("compliance-eaa/bad-format",
+      "compliance.eaa.export: format must be 'json' or 'markdown'");
+  }
+
+  return {
+    declareCriterion:       declareCriterion,
+    declareNonConformance:  declareNonConformance,
+    "export":               exportEaa,
+    stats:                  _stats,
+    VALID_CONFORMANCE:      Object.keys(VALID_CONFORMANCE),
+  };
+}
+
+module.exports = {
+  create:               create,
+  ComplianceEaaError:   ComplianceEaaError,
+  VALID_CONFORMANCE:    Object.keys(VALID_CONFORMANCE),
+};

package/lib/cra-report.js

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * b.cra.report — EU Cyber Resilience Act incident-reporting wrapper.
+ *
+ * The Cyber Resilience Act (Regulation (EU) 2024/2847) Article 14 §1
+ * mandates that manufacturers of digital products report actively-
+ * exploited vulnerabilities and severe incidents to ENISA + national
+ * authorities. The framework's b.incident.report primitive provides
+ * the generic 3-stage shape; this wrapper specializes it with the
+ * CRA-specific reporting fields, deadlines (24h early warning / 72h
+ * incident notification / 14d final report), and the ENISA single-
+ * reporting-point destination.
+ *
+ *   var cra = b.cra.report.create({
+ *     enisaEndpoint: "https://enisa-spr.europa.eu/api/incidents",
+ *     httpClient:    b.httpClient,
+ *     audit:         b.audit,
+ *     productId:     "blamejs-1.x",
+ *     manufacturer:  { name: "Acme Co", contact: "security@acme.example" },
+ *   });
+ *   var inc = await cra.open({
+ *     detectedAt:    Date.now(),
+ *     vulnerability: { cveId: "CVE-2026-99999", actively_exploited: true },
+ *     impact:        { ... },
+ *   });
+ *   await cra.earlyWarning(inc.id, { ... });        // 24h
+ *   await cra.notification(inc.id, { ... });        // 72h
+ *   await cra.finalReport(inc.id, { ... });         // 14d
+ *
+ * The wrapper composes b.incident.report so the audit chain shape,
+ * persistence hook, and status surface stay consistent across every
+ * regulatory regime. Per-regime CRA semantics:
+ *   - early warning may be terse ("incident detected, scope unknown")
+ *   - notification carries impact + mitigation + scope
+ *   - final report adds root cause + lessons learned
+ *
+ * Submission to ENISA is opt-in per call (operators may want to
+ * batch / approve before submission); pass { submit: true } on each
+ * stage call to push through the operator's b.httpClient. The
+ * primitive does NOT auto-submit on stage transitions — regulators
+ * uniformly require operator review before filing.
+ */
+
+var C = require("./constants");
+var defineClass = require("./framework-error").defineClass;
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+
+var incidentReport = lazyRequire(function () { return require("./incident-report"); });
+var audit = lazyRequire(function () { return require("./audit"); });
+
+var CraReportError = defineClass("CraReportError", { alwaysPermanent: true });
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "audit", "persist", "httpClient", "enisaEndpoint",
+    "productId", "manufacturer", "now",
+  ], "cra.report");
+
+  validateOpts.requireNonEmptyString(opts.productId,
+    "cra.report.create: opts.productId is required (CRA Annex VII §1 requires a stable product identifier)",
+    CraReportError, "cra-report/bad-product-id");
+  if (!opts.manufacturer || typeof opts.manufacturer !== "object") {
+    throw new CraReportError("cra-report/bad-manufacturer",
+      "cra.report.create: opts.manufacturer is required (CRA Annex VII §1 requires manufacturer name + contact)");
+  }
+  var productId = opts.productId;
+  var manufacturer = opts.manufacturer;
+  var enisaEndpoint = typeof opts.enisaEndpoint === "string" && opts.enisaEndpoint.length > 0
+    ? opts.enisaEndpoint : null;
+  var httpClient = opts.httpClient || null;
+  var auditOn = opts.audit !== false;
+
+  // CRA Article 14 deadlines — operators don't override these without
+  // documented regulatory justification (the deadlines are statutory,
+  // not operator preference).
+  var ir = incidentReport().create({
+    audit:    opts.audit,
+    persist:  opts.persist,
+    now:      opts.now,
+    deadlines: {
+      // initial = "early warning" per CRA Article 14 §1(a) — 24h
+      initial:      C.TIME.hours(24),
+      // intermediate = "incident notification" per CRA Article 14 §1(b) — 72h
+      intermediate: C.TIME.hours(72),
+      // final = "final report" per CRA Article 14 §1(c) — 14 days
+      final:        C.TIME.days(14),
+    },
+  });
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   "cra.report." + action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+
+  async function _submitToEnisa(payload) {
+    if (!enisaEndpoint || !httpClient) {
+      _emitAudit("submit_skipped", "warning", { reason: "no-endpoint-or-client" });
+      return { submitted: false, reason: "no-endpoint-or-client" };
+    }
+    try {
+      var res = await httpClient.request({
+        url:           enisaEndpoint,
+        method:        "POST",
+        headers:       { "Content-Type": "application/json" },
+        body:          Buffer.from(JSON.stringify(payload), "utf8"),
+        responseMode:  "always-resolve",
+      });
+      var ok = res.statusCode >= 200 && res.statusCode < 300;                        // allow:raw-byte-literal — HTTP status range
+      _emitAudit("submitted", ok ? "success" : "failure", {
+        statusCode: res.statusCode, productId: productId,
+      });
+      return { submitted: ok, statusCode: res.statusCode };
+    } catch (e) {
+      _emitAudit("submit_failed", "failure", { error: (e && e.message) || String(e) });
+      return { submitted: false, error: (e && e.message) || String(e) };
+    }
+  }
+
+  function _craEnvelope(stage, incident, fields) {
+    return {
+      cra_version:   "2024/2847",
+      stage:         stage,                                                            // "early-warning" / "notification" / "final"
+      product:       { id: productId },
+      manufacturer:  manufacturer,
+      incident: {
+        id:           incident.id,
+        detected_at:  new Date(incident.detectedAt).toISOString(),
+        scope:        incident.scope,
+        summary:      incident.summary,
+        impact:       incident.impact,
+      },
+      fields:        fields || {},
+    };
+  }
+
+  async function open(spec) {
+    spec = Object.assign({}, spec || {}, { regime: "cra" });
+    var rec = await ir.open(spec);
+    _emitAudit("opened", "success", { incidentId: rec.id, productId: productId });
+    return rec;
+  }
+
+  async function earlyWarning(incidentId, fields) {
+    var rec = await ir.recordInitial(incidentId, fields || {});
+    var result = { record: rec, submitted: null };
+    if (fields && fields.submit === true) {
+      result.submitted = await _submitToEnisa(_craEnvelope("early-warning", rec, fields));
+    }
+    return result;
+  }
+
+  async function notification(incidentId, fields) {
+    var rec = await ir.recordIntermediate(incidentId, fields || {});
+    var result = { record: rec, submitted: null };
+    if (fields && fields.submit === true) {
+      result.submitted = await _submitToEnisa(_craEnvelope("notification", rec, fields));
+    }
+    return result;
+  }
+
+  async function finalReport(incidentId, fields) {
+    var rec = await ir.recordFinal(incidentId, fields || {});
+    var result = { record: rec, submitted: null };
+    if (fields && fields.submit === true) {
+      result.submitted = await _submitToEnisa(_craEnvelope("final", rec, fields));
+    }
+    return result;
+  }
+
+  return {
+    open:           open,
+    earlyWarning:   earlyWarning,
+    notification:   notification,
+    finalReport:    finalReport,
+    // Forward incident.report observability surface
+    get:            function (id) { return ir.get(id); },
+    list:           function ()   { return ir.list(); },
+    status:         function ()   { return ir.status(); },
+    productId:      productId,
+    manufacturer:   manufacturer,
+  };
+}
+
+module.exports = {
+  create:           create,
+  CraReportError:   CraReportError,
+};