@blamejs/core 0.8.9 → 0.8.11

package/lib/middleware/age-gate.js

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * ageGate middleware — request-level age classification + high-privacy
+ * default headers for routes that need stricter handling for users
+ * below an operator-configured age threshold.
+ *
+ * COPPA (US, 13 and under), UK Children's Code (16 and under),
+ * California AADC (18 and under), and similar regimes require
+ * operators to apply heightened privacy protections when serving
+ * users below a regulatory age. The middleware:
+ *
+ *   1. Reads the operator's `getAge(req)` predicate to classify the
+ *      request as "above-threshold" / "below-threshold" / "unknown"
+ *   2. Sets high-privacy defaults on below-threshold + unknown
+ *      responses:
+ *      - `Cache-Control: private, no-store`
+ *      - `Referrer-Policy: no-referrer`
+ *      - `X-Privacy-Posture: below-threshold`
+ *   3. Refuses with 451 (Unavailable For Legal Reasons) when the
+ *      operator-supplied requireAge: 18 is set and the request is
+ *      below threshold without a parental-consent record
+ *   4. Audits the classification decision
+ *
+ *   var gate = b.middleware.ageGate({
+ *     getAge:           function (req) {
+ *       if (req.user && typeof req.user.age === "number") return req.user.age;
+ *       return null;                                // unknown
+ *     },
+ *     requireAge:       null,                       // null = don't gate, just headers
+ *     consentRequired:  18,                          // require parental consent below this
+ *     hasParentalConsent: function (req) {
+ *       return req.user && req.user.parentalConsent === true;
+ *     },
+ *   });
+ *   router.use(gate);
+ */
+
+var defineClass = require("../framework-error").defineClass;
+var lazyRequire = require("../lazy-require");
+var validateOpts = require("../validate-opts");
+
+var audit = lazyRequire(function () { return require("../audit"); });
+
+var AgeGateError = defineClass("AgeGateError", { alwaysPermanent: true });
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "audit", "getAge", "requireAge", "consentRequired",
+    "hasParentalConsent", "skipPaths", "errorMessage",
+  ], "middleware.ageGate");
+
+  if (typeof opts.getAge !== "function") {
+    throw new AgeGateError("age-gate/bad-get-age",
+      "middleware.ageGate: opts.getAge must be a function (req) -> number | null");
+  }
+  var getAge = opts.getAge;
+  var requireAge = (typeof opts.requireAge === "number" && opts.requireAge > 0)            // allow:numeric-opt-Infinity — age is operator domain, not a bytes/time-shaped opt
+    ? opts.requireAge : null;
+  var consentRequired = (typeof opts.consentRequired === "number" && opts.consentRequired > 0)  // allow:numeric-opt-Infinity — age threshold, not a bytes/time-shaped opt
+    ? opts.consentRequired : null;
+  var hasParentalConsent = typeof opts.hasParentalConsent === "function" ? opts.hasParentalConsent : null;
+  var skipPaths = Array.isArray(opts.skipPaths) ? opts.skipPaths.slice() : [];
+  var auditOn = opts.audit !== false;
+  var errorMessage = typeof opts.errorMessage === "string" && opts.errorMessage.length > 0
+    ? opts.errorMessage : "service unavailable without parental consent";
+
+  function _shouldSkip(req) {
+    if (skipPaths.length === 0) return false;
+    var p = req.url || "";
+    var qpos = p.indexOf("?");
+    if (qpos !== -1) p = p.slice(0, qpos);
+    for (var i = 0; i < skipPaths.length; i++) {
+      var s = skipPaths[i];
+      if (typeof s === "string" && (p === s || p.indexOf(s + "/") === 0)) return true;
+      if (s instanceof RegExp && s.test(p)) return true;
+    }
+    return false;
+  }
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   "middleware.age_gate." + action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+
+  return function ageGateMiddleware(req, res, next) {
+    if (_shouldSkip(req)) return next();
+
+    var age;
+    try { age = getAge(req); }
+    catch (e) {
+      _emitAudit("get_age_failed", "failure", { error: (e && e.message) || String(e) });
+      age = null;
+    }
+
+    var classification;
+    if (age === null || typeof age !== "number") classification = "unknown";
+    else if (consentRequired !== null && age < consentRequired) classification = "below-threshold";
+    else classification = "above-threshold";
+
+    if (classification !== "above-threshold") {
+      if (typeof res.setHeader === "function") {
+        res.setHeader("Cache-Control",   "private, no-store");
+        res.setHeader("Referrer-Policy", "no-referrer");
+        res.setHeader("X-Privacy-Posture", classification);
+      }
+    }
+
+    if (requireAge !== null && classification === "below-threshold" && (age === null || age < requireAge)) {
+      var hasConsent = hasParentalConsent ? !!hasParentalConsent(req) : false;
+      if (!hasConsent) {
+        _emitAudit("refused", "denied", { age: age, classification: classification, requireAge: requireAge });
+        if (!res.writableEnded && typeof res.writeHead === "function") {
+          res.writeHead(451, {                                                            // allow:raw-byte-literal — HTTP 451 Unavailable For Legal Reasons
+            "Content-Type":  "application/json; charset=utf-8",
+            "Cache-Control": "no-store, private",
+          });
+          res.end(JSON.stringify({ error: errorMessage, requireAge: requireAge, parentalConsent: false }));
+        }
+        return;
+      }
+    }
+
+    if (req.locals && typeof req.locals === "object") {
+      req.locals.ageGateClassification = classification;
+    }
+    _emitAudit("classified", "success", { classification: classification, age: age });
+    return next();
+  };
+}
+
+module.exports = {
+  create:       create,
+  AgeGateError: AgeGateError,
+};

package/lib/middleware/bot-disclose.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * botDisclose middleware — California SB 1001 bot-disclosure.
+ *
+ * Cal. Bus. & Prof. Code §17941 (SB 1001, effective 2019) requires
+ * that any "bot" used to communicate with persons in California for
+ * the purpose of incentivizing a sale or influencing an election
+ * disclose its non-human nature. Operators serving an automated
+ * conversation surface (LLM-backed chat / IVR / SMS) wire this
+ * middleware to:
+ *
+ *   1. Inject a disclosure banner into HTML responses (server-rendered)
+ *   2. Set an X-Bot-Disclosure header for API consumers
+ *   3. Emit an audit event for every conversation-initiating request
+ *
+ *   var bot = b.middleware.botDisclose({
+ *     audit:        b.audit,
+ *     mountPaths:   ["/chat", "/api/chat"],
+ *     bannerHtml:   '<div role="status">You are interacting with an automated assistant.</div>',
+ *     bannerJson:   { _bot: true, disclosure: "automated-assistant" },
+ *   });
+ *   router.use(bot);
+ *
+ * Per SB 1001 §17941(a), the disclosure must be "clear, conspicuous,
+ * and reasonably designed to inform"; operators with custom UI wire
+ * `bannerHtml` to match their visual design.
+ */
+
+var defineClass = require("../framework-error").defineClass;
+var lazyRequire = require("../lazy-require");
+var validateOpts = require("../validate-opts");
+
+var audit = lazyRequire(function () { return require("../audit"); });
+
+var BotDiscloseError = defineClass("BotDiscloseError", { alwaysPermanent: true });
+
+var DEFAULT_BANNER_HTML = '<div role="status" data-bot-disclosure="true" ' +
+  'style="border:1px solid #888;padding:8px;margin:8px 0;background:#fff8e1;font-size:14px;">' +
+  '<strong>Automated assistant.</strong> ' +
+  'You are interacting with an automated agent. ' +
+  'For California users: this disclosure is provided per Cal. Bus. &amp; Prof. Code §17941.' +
+  '</div>';
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "audit", "mountPaths", "bannerHtml", "bannerJson",
+    "headerName", "auditAction",
+  ], "middleware.botDisclose");
+
+  var mountPaths = Array.isArray(opts.mountPaths) ? opts.mountPaths.slice() : null;
+  var bannerHtml = typeof opts.bannerHtml === "string" ? opts.bannerHtml : DEFAULT_BANNER_HTML;
+  var bannerJson = (opts.bannerJson && typeof opts.bannerJson === "object")
+    ? opts.bannerJson : { _bot: true, disclosure: "automated-assistant" };
+  var headerName = typeof opts.headerName === "string" && opts.headerName.length > 0
+    ? opts.headerName : "X-Bot-Disclosure";
+  var auditOn = opts.audit !== false;
+  var actionBase = typeof opts.auditAction === "string" && opts.auditAction.length > 0
+    ? opts.auditAction : "middleware.bot_disclose";
+
+  function _matches(req) {
+    if (!mountPaths) return true;                                                        // null = match every path
+    var p = req.url || "";
+    var qpos = p.indexOf("?");
+    if (qpos !== -1) p = p.slice(0, qpos);
+    for (var i = 0; i < mountPaths.length; i++) {
+      var m = mountPaths[i];
+      if (typeof m === "string" && (p === m || p.indexOf(m + "/") === 0)) return true;
+      if (m instanceof RegExp && m.test(p)) return true;
+    }
+    return false;
+  }
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   actionBase + "." + action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+
+  return function botDiscloseMiddleware(req, res, next) {
+    if (!_matches(req)) return next();
+
+    // Always set the header (cheap; API consumers see the disclosure
+    // even on JSON endpoints).
+    if (typeof res.setHeader === "function") {
+      res.setHeader(headerName, "automated-assistant");
+    }
+    _emitAudit("disclosed", "success", { method: req.method, path: req.url });
+
+    // Patch res.write / res.end so the first text/html response gets
+    // the banner injected before <body>'s first child. Operators
+    // wanting deeper integration override bannerHtml or set
+    // mountPaths to scope where injection happens.
+    var origWrite = res.write && res.write.bind(res);
+    var origEnd = res.end && res.end.bind(res);
+    var injected = false;
+
+    function _maybeInject(chunk, encoding) {
+      if (injected) return chunk;
+      var ct = typeof res.getHeader === "function" ? res.getHeader("content-type") : "";
+      if (typeof ct !== "string" || ct.indexOf("text/html") === -1) return chunk;
+      var body = Buffer.isBuffer(chunk) ? chunk.toString("utf8") :
+        (typeof chunk === "string" ? chunk : "");
+      // Inject after <body> opening tag if present, else after <html>
+      // opening tag, else prepend.
+      var bodyMatch = body.match(/<body[^>]*>/i);
+      if (bodyMatch) {
+        var idx = bodyMatch.index + bodyMatch[0].length;
+        body = body.slice(0, idx) + "\n" + bannerHtml + "\n" + body.slice(idx);
+      } else {
+        body = bannerHtml + "\n" + body;
+      }
+      injected = true;
+      return Buffer.from(body, "utf8");
+    }
+
+    if (origWrite) {
+      res.write = function (chunk, encoding, cb) {
+        return origWrite(_maybeInject(chunk, encoding), encoding, cb);
+      };
+    }
+    if (origEnd) {
+      res.end = function (chunk, encoding, cb) {
+        if (chunk) chunk = _maybeInject(chunk, encoding);
+        return origEnd(chunk, encoding, cb);
+      };
+    }
+
+    // For JSON responses, attach the disclosure to res.locals so
+    // operator handlers building JSON via res.json(...) can include
+    // it explicitly. We don't auto-merge into the JSON body — the
+    // header + audit are the load-bearing disclosure surfaces.
+    if (res.locals && typeof res.locals === "object") {
+      res.locals.botDisclosure = bannerJson;
+    }
+    return next();
+  };
+}
+
+module.exports = {
+  create:               create,
+  BotDiscloseError:     BotDiscloseError,
+  DEFAULT_BANNER_HTML:  DEFAULT_BANNER_HTML,
+};

package/lib/middleware/index.js

@@ -25,6 +25,7 @@ var assetlinks = require("./assetlinks");
 var attachUser = require("./attach-user");
 var bearerAuth = require("./bearer-auth");
 var bodyParser = require("./body-parser");
+var botDisclose = require("./bot-disclose");
 var botGuard = require("./bot-guard");
 var compression = require("./compression");
 var cookies = require("./cookies");
@@ -47,6 +48,7 @@ var requestLog = require("./request-log");
 var requireAal = require("./require-aal");
 var requireAuth = require("./require-auth");
 var requireContentType = require("./require-content-type");
+var ageGate = require("./age-gate");
 var requireMethods = require("./require-methods");
 var requireMtls = require("./require-mtls");
 var requireStepUp = require("./require-step-up");
@@ -63,6 +65,7 @@ module.exports = {
   requestId:        requestId.create,
   securityHeaders:  securityHeaders.create,
   errorHandler:     errorHandler.create,
+  botDisclose:      botDisclose.create,
   botGuard:         botGuard.create,
   cors:             cors.create,
   dailyByteQuota:   dailyByteQuota.create,
@@ -72,6 +75,7 @@ module.exports = {
   requireAal:       requireAal.create,
   requireAuth:      requireAuth.create,
   requireContentType: requireContentType.create,
+  ageGate:          ageGate.create,
   requireMethods:   requireMethods.create,
   requireMtls:      requireMtls.create,
   requireStepUp:    requireStepUp.create,
@@ -108,6 +112,7 @@ module.exports = {
     requestId:        requestId,
     securityHeaders:  securityHeaders,
     errorHandler:     errorHandler,
+    botDisclose:      botDisclose,
     botGuard:         botGuard,
     cors:             cors,
     dailyByteQuota:   dailyByteQuota,
@@ -117,6 +122,7 @@ module.exports = {
     requireAal:       requireAal,
     requireAuth:      requireAuth,
     requireContentType: requireContentType,
+    ageGate:          ageGate,
     requireMethods:   requireMethods,
     requireMtls:      requireMtls,
     requireStepUp:    requireStepUp,

package/lib/nis2-report.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * b.nis2.report — NIS2 Directive incident-reporting wrapper.
+ *
+ * Directive (EU) 2022/2555 (NIS2) Article 23 mandates that essential
+ * + important entities report significant incidents to the national
+ * CSIRT or competent authority. Three-stage pattern with statutory
+ * deadlines:
+ *   - early warning within 24h of becoming aware (Art. 23 §4(a))
+ *   - incident notification within 72h, including initial assessment
+ *     of severity + impact + indicators of compromise (Art. 23 §4(b))
+ *   - final report within 1 month, with detailed root cause +
+ *     remediation + cross-border implications (Art. 23 §4(d))
+ *
+ *   var nis2 = b.nis2.report.create({
+ *     audit:        b.audit,
+ *     entityId:     "acme-cloud-1",
+ *     entityType:   "essential",                  // "essential" | "important"
+ *     sectorAnnex:  "I.6",                        // NIS2 Annex I/II row id
+ *     csirtEndpoint: "https://csirt.example/api",
+ *     httpClient:   b.httpClient,
+ *   });
+ *
+ * Sector annex codes follow NIS2's two annexes:
+ *   - Annex I (essential): I.1 energy / I.2 transport / I.3 banking /
+ *     I.4 financial-market-infrastructures / I.5 health /
+ *     I.6 drinking-water / I.7 wastewater / I.8 digital-infrastructure /
+ *     I.9 ICT-service-management / I.10 public-administration /
+ *     I.11 space
+ *   - Annex II (important): II.1 postal / II.2 waste-management /
+ *     II.3 chemicals / II.4 food / II.5 manufacturing /
+ *     II.6 digital-providers / II.7 research
+ */
+
+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 Nis2ReportError = defineClass("Nis2ReportError", { alwaysPermanent: true });
+
+var VALID_ENTITY_TYPES = Object.freeze({ essential: 1, important: 1 });
+
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "audit", "persist", "httpClient", "csirtEndpoint",
+    "entityId", "entityType", "sectorAnnex", "now",
+  ], "nis2.report");
+
+  validateOpts.requireNonEmptyString(opts.entityId,
+    "nis2.report.create: opts.entityId is required (NIS2 registration ID)",
+    Nis2ReportError, "nis2-report/bad-entity-id");
+  if (!VALID_ENTITY_TYPES[opts.entityType]) {
+    throw new Nis2ReportError("nis2-report/bad-entity-type",
+      "nis2.report.create: opts.entityType must be 'essential' or 'important' (NIS2 Article 3 classification)");
+  }
+  validateOpts.requireNonEmptyString(opts.sectorAnnex,
+    "nis2.report.create: opts.sectorAnnex is required (e.g. 'I.6' for drinking water, 'II.6' for digital-providers)",
+    Nis2ReportError, "nis2-report/bad-sector");
+  var entityId = opts.entityId;
+  var entityType = opts.entityType;
+  var sectorAnnex = opts.sectorAnnex;
+  var csirtEndpoint = opts.csirtEndpoint || null;
+  var httpClient = opts.httpClient || null;
+  var auditOn = opts.audit !== false;
+
+  var ir = incidentReport().create({
+    audit:    opts.audit,
+    persist:  opts.persist,
+    now:      opts.now,
+    deadlines: {
+      initial:      C.TIME.hours(24),                                                     // NIS2 Art. 23 §4(a) — early warning
+      intermediate: C.TIME.hours(72),                                                     // NIS2 Art. 23 §4(b) — incident notification
+      final:        C.TIME.days(30),                                                      // NIS2 Art. 23 §4(d) — final report (1 month)
+    },
+  });
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   "nis2.report." + action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+
+  async function _submitToCsirt(payload) {
+    if (!csirtEndpoint || !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: csirtEndpoint, 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 });
+      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 _envelope(stage, incident, fields) {
+    return {
+      directive:    "(EU) 2022/2555",
+      article:      "23",
+      stage:        stage,                                                                // "early-warning" / "notification" / "final"
+      entity:       { id: entityId, type: entityType, sector: sectorAnnex },
+      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: "nis2" });
+    var rec = await ir.open(spec);
+    _emitAudit("opened", "success", { incidentId: rec.id, entityId: entityId, entityType: entityType });
+    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 _submitToCsirt(_envelope("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 _submitToCsirt(_envelope("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 _submitToCsirt(_envelope("final", rec, fields));
+    }
+    return result;
+  }
+
+  return {
+    open:           open,
+    earlyWarning:   earlyWarning,
+    notification:   notification,
+    finalReport:    finalReport,
+    get:            function (id) { return ir.get(id); },
+    list:           function ()   { return ir.list(); },
+    status:         function ()   { return ir.status(); },
+    entityId:       entityId,
+    entityType:     entityType,
+    sectorAnnex:    sectorAnnex,
+  };
+}
+
+module.exports = {
+  create:             create,
+  Nis2ReportError:    Nis2ReportError,
+  VALID_ENTITY_TYPES: Object.keys(VALID_ENTITY_TYPES),
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.8.9",
+  "version": "0.8.11",
   "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:b2addb57-b40a-4a44-9c34-7f7bd7d741c3",
+  "serialNumber": "urn:uuid:ae68f706-2c92-4dfa-b852-f29896f91c62",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-07T02:18:24.599Z",
+    "timestamp": "2026-05-07T03:30:10.287Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.8.9",
+      "bom-ref": "@blamejs/core@0.8.11",
       "type": "library",
       "name": "blamejs",
-      "version": "0.8.9",
+      "version": "0.8.11",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.8.9",
+      "purl": "pkg:npm/%40blamejs/core@0.8.11",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.8.9",
+      "ref": "@blamejs/core@0.8.11",
       "dependsOn": []
     }
   ]