@blamejs/core 0.8.10 → 0.8.12

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.8.x
 
+- **0.8.12** (2026-05-07) — WebSocket upgrade refuses credential-shaped query parameters by default. `validateUpgradeRequest(req, opts)` now scans the request URL for the credential-leak names `access_token`, `bearer`, `bearer_token`, `apikey`, `api_key`, `api-key`, `authorization` (case-insensitive, with percent-decoding) and refuses the upgrade with HTTP 400 when one is present. URL query strings leak through web-server access logs, browser history, the Referer header forwarded to third-party CDN / analytics, in-process / proxy log captures, and crash dumps — RFC 6750 §2.3 explicitly cautions against bearer tokens in URI query parameters for these reasons. Operators with a non-credential parameter that happens to share a credential-shaped name opt out per route via `opts.allowQueryAuthParams: true` with an audited operator reason. The refused list is deliberately narrow: overloaded names (`token`, `auth`, `key`, `session`) have non-credential meanings (CSRF tokens, file-share tokens, session-resume identifiers) and are NOT refused.
+
+- **0.8.11** (2026-05-07) — Three new state-and-federal regulatory primitives + a per-primitive test-coverage gate. **`b.breach.deadline` + `b.breach.report`** — all-50-states data-breach-notification deadline registry. `b.breach.deadline.forStates(states, detectedAt)` returns per-state `{ state, kind, dueBy, citation }` records (`kind: "as-soon-as-possible"` for AS-OF / `"hard-deadline"` for fixed-day deadlines like Texas / Florida / Maine). `b.breach.report.create()` opens a multi-state breach with a single record, tracks per-state filings via `fileNotice(id, state, ...)`, exposes `pending(id)` for dashboards, and auto-closes once every affected state has filed. Every transition records a `breach.report.*` audit event. Statutory citations + day counts wired in `lib/breach-deadline.js` per-state. **`b.ai.adverseDecision`** — wraps an operator-supplied `decide(subject)` predicate, automatically attaches a consumer-rights notice when the outcome is `"adverse"` / `"denied"` / `"rejected"`. Built-in regulation templates for `gdpr-22` (Article 22 automated-decision rights), `ai-act-86` (EU AI Act high-risk consumer recourse), `ecoa-1002.9` (US Equal Credit Opportunity Act adverse-action notice), `colorado-ai-act` (CO SB 24-205 §6-1-1701), `nyc-ll-144` (NYC Local Law 144 employment AEDT), `fcra-615` (US FCRA adverse action), and `operator-defined`. Notice carries `principalReasons` + `consumerRights: { requestData, requestExplanation, contestDecision, requestHumanReview }` shaped per regime. **`b.middleware.ageGate`** — request-level age-classification middleware. Operator-supplied `getAge(req)` returns the subject age (or null/undefined when unknown); middleware classifies as `"above-threshold"` / `"below-threshold"` / `"unknown"` against `consentRequired`, sets `X-Privacy-Posture` header, and refuses with 451 + audited reason when `requireAge` is set and `hasParentalConsent(req)` is unmet. Composes upstream of session / authn for COPPA / AADC / UK Children's Code postures. **Per-primitive test-coverage gate** — new `test/layer-0-primitives/test-coverage.test.js` walks every operator-facing `b.*` primitive and refuses release unless the primitive has at least one test reference (or an explicit `UNTESTED_BACKLOG` entry naming the reason). Closes the drift class where a primitive landed on `b.*` but never gained a unit test.
+
 - **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.

package/index.js

@@ -254,6 +254,8 @@ module.exports = {
   cra:              { report: require("./lib/cra-report") },
   nis2:             { report: require("./lib/nis2-report") },
   gdpr:             { ropa: require("./lib/gdpr-ropa") },
+  breach:           require("./lib/breach-deadline"),
+  ai:               { adverseDecision: require("./lib/ai-adverse-decision") },
   queue:            queue,
   logStream:        logStream,
   redact:           redact,

package/lib/ai-adverse-decision.js

@@ -0,0 +1,184 @@
+"use strict";
+/**
+ * b.ai.adverseDecision — adverse-decision wrapper for automated
+ * decisions affecting consumer rights.
+ *
+ * GDPR Article 22, EU AI Act Article 86, Colorado AI Act, NYC Local
+ * Law 144, and Equal Credit Opportunity Act §1002.9 all require some
+ * form of consumer notice + explanation when an automated decision
+ * adversely affects a person (denial of credit, denial of employment,
+ * adverse insurance pricing, etc.).
+ *
+ * The primitive wraps an operator-supplied predicate and:
+ *   - logs every decision with audit-chain attribution
+ *   - emits a structured consumer-rights notice on adverse outcomes
+ *   - pulls operator-supplied principal reasons (the "specific reasons
+ *     for the action" that ECOA + similar regimes require)
+ *
+ *   var hireDecision = b.ai.adverseDecision.wrap({
+ *     name:         "hire-screening",
+ *     model:        "screening-v3.1",
+ *     legalBasis:   "ecoa-1002.9",
+ *     decide:       function (applicant) {
+ *       var score = scoreModel(applicant);
+ *       return {
+ *         outcome:        score < 0.5 ? "adverse" : "favorable",
+ *         score:          score,
+ *         principalReasons: score < 0.5 ? ["insufficient-credit-history", "..."] : [],
+ *       };
+ *     },
+ *     onAdverse:    async function (subject, decision) {
+ *       await mailer.send({ to: subject.email, ... });
+ *     },
+ *   });
+ *
+ *   var decision = await hireDecision({ id: "applicant-1234", email: "..." });
+ *   // decision = { outcome, score, principalReasons, adverseNotice? }
+ *
+ * adverseNotice (when outcome === "adverse"):
+ *   {
+ *     subjectId:     "applicant-1234",
+ *     decisionAt:    1715040000000,
+ *     model:         "screening-v3.1",
+ *     legalBasis:    "ecoa-1002.9",
+ *     principalReasons: [...],
+ *     consumerRights: {
+ *       requestExplanation: true,
+ *       requestHumanReview: true,
+ *       requestAppeal:      true,
+ *       requestData:        true,
+ *       statutoryDeadlines: { explanation: "30d", appeal: "60d" }
+ *     }
+ *   }
+ */
+
+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 AdverseDecisionError = defineClass("AdverseDecisionError", { alwaysPermanent: true });
+
+// Per-regime statutory deadlines for the consumer-rights surfaces.
+// Operators select via opts.legalBasis; the framework attaches the
+// right deadline shape to each adverseNotice.
+var REGIME_DEADLINES = Object.freeze({
+  "gdpr-22":           { explanation: "30d", humanReview: "30d", appeal: "30d", regulation: "GDPR Article 22" },
+  "ai-act-86":         { explanation: "30d", humanReview: "30d", appeal: "30d", regulation: "EU AI Act Article 86" },
+  "ecoa-1002.9":       { explanation: "30d", humanReview: null, appeal: null,   regulation: "ECOA 12 CFR §1002.9" },
+  "colorado-ai-act":   { explanation: "60d", humanReview: "60d", appeal: "60d", regulation: "Colorado AI Act" },
+  "nyc-ll-144":        { explanation: "10d", humanReview: null, appeal: null,   regulation: "NYC Local Law 144" },
+  "fcra-615":          { explanation: "60d", humanReview: null, appeal: null,   regulation: "FCRA 15 USC §1681m" },
+  "operator-defined":  { explanation: null,  humanReview: null, appeal: null,   regulation: "operator-supplied" },
+});
+
+function wrap(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "name", "model", "legalBasis", "decide", "onAdverse",
+    "audit", "now",
+  ], "ai.adverseDecision");
+
+  validateOpts.requireNonEmptyString(opts.name,
+    "ai.adverseDecision.wrap: opts.name is required",
+    AdverseDecisionError, "ai-adverse/bad-name");
+  validateOpts.requireNonEmptyString(opts.model,
+    "ai.adverseDecision.wrap: opts.model is required (model id + version for audit attribution)",
+    AdverseDecisionError, "ai-adverse/bad-model");
+  validateOpts.requireNonEmptyString(opts.legalBasis,
+    "ai.adverseDecision.wrap: opts.legalBasis is required (e.g. 'ecoa-1002.9' / 'gdpr-22' / 'colorado-ai-act')",
+    AdverseDecisionError, "ai-adverse/bad-legal-basis");
+  if (typeof opts.decide !== "function") {
+    throw new AdverseDecisionError("ai-adverse/bad-decide",
+      "ai.adverseDecision.wrap: opts.decide must be a function (subject) -> { outcome, principalReasons }");
+  }
+  var name = opts.name;
+  var model = opts.model;
+  var legalBasis = opts.legalBasis;
+  var decide = opts.decide;
+  var onAdverse = typeof opts.onAdverse === "function" ? opts.onAdverse : null;
+  var auditOn = opts.audit !== false;
+  var now = typeof opts.now === "function" ? opts.now : function () { return Date.now(); };
+
+  var deadlines = REGIME_DEADLINES[legalBasis] || REGIME_DEADLINES["operator-defined"];
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   "ai.adverse_decision." + action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+  function _emitMetric(verb, n, labels) {
+    try { observability().safeEvent("ai.adverse_decision." + verb, n || 1, labels || {}); }
+    catch (_e) { /* drop-silent */ }
+  }
+
+  return async function adverseDecisionDecorated(subject) {
+    if (!subject || typeof subject !== "object") {
+      throw new AdverseDecisionError("ai-adverse/bad-subject",
+        "ai.adverseDecision: subject must be an object with at least { id }");
+    }
+    var subjectId = subject.id || null;
+    var decidedAt = now();
+    var decision;
+    try {
+      decision = await decide(subject);
+    } catch (e) {
+      _emitAudit("decide_failed", "failure", { name: name, subjectId: subjectId, error: (e && e.message) || String(e) });
+      throw e;
+    }
+    if (!decision || typeof decision !== "object") {
+      throw new AdverseDecisionError("ai-adverse/bad-decision-shape",
+        "ai.adverseDecision: opts.decide must return an object with { outcome, principalReasons }");
+    }
+    var outcome = decision.outcome;
+    var isAdverse = outcome === "adverse" || outcome === "denied" || outcome === "rejected";
+
+    _emitAudit("decided", isAdverse ? "denied" : "success", {
+      name: name, model: model, legalBasis: legalBasis,
+      subjectId: subjectId, outcome: outcome,
+      principalReasons: Array.isArray(decision.principalReasons) ? decision.principalReasons : [],
+    });
+    _emitMetric("decided", 1, { name: name, outcome: outcome });
+
+    if (isAdverse) {
+      decision.adverseNotice = {
+        subjectId:        subjectId,
+        decisionAt:       decidedAt,
+        model:            model,
+        legalBasis:       legalBasis,
+        regulation:       deadlines.regulation,
+        principalReasons: Array.isArray(decision.principalReasons) ? decision.principalReasons : [],
+        consumerRights: {
+          requestExplanation: deadlines.explanation !== null,
+          requestHumanReview: deadlines.humanReview !== null,
+          requestAppeal:      deadlines.appeal !== null,
+          requestData:        true,
+          statutoryDeadlines: {
+            explanation: deadlines.explanation,
+            humanReview: deadlines.humanReview,
+            appeal:      deadlines.appeal,
+          },
+        },
+      };
+      if (onAdverse) {
+        try { await onAdverse(subject, decision); }
+        catch (e) { _emitAudit("on_adverse_threw", "failure", { error: (e && e.message) || String(e) }); }
+      }
+    }
+    return decision;
+  };
+}
+
+module.exports = {
+  wrap:                  wrap,
+  REGIME_DEADLINES:      REGIME_DEADLINES,
+  AdverseDecisionError:  AdverseDecisionError,
+  VALID_REGIMES:         Object.keys(REGIME_DEADLINES),
+};

package/lib/breach-deadline.js

@@ -0,0 +1,272 @@
+"use strict";
+/**
+ * b.breach.deadline + b.breach.report — US state breach-notification
+ * deadline registry + reporter.
+ *
+ * Every US state + territory has its own breach-notification statute
+ * with a deadline (60 days, 45 days, "without unreasonable delay").
+ * Operators detecting a breach affecting residents in multiple states
+ * face a fan-out problem: which state(s), what deadline for each,
+ * what notice content. The registry encodes the per-jurisdiction
+ * deadline + statutory citation; the reporter surfaces an operator-
+ * friendly "what do I owe and when" plan.
+ *
+ *   var deadlines = b.breach.deadline.forStates(["CA", "NY", "TX"], breachDetectedAt);
+ *   // -> [{ state: "CA", dueBy: ..., statute: "Cal. Civ. Code §1798.82" }, ...]
+ *
+ *   var reporter = b.breach.report.create({ audit: b.audit });
+ *   var rec = reporter.open({
+ *     detectedAt: Date.now(),
+ *     affectedStates: ["CA", "NY", "TX"],
+ *     scope:    "data-confidentiality-breach",
+ *     impact:   { individualsAffected: 5000 },
+ *   });
+ *   await reporter.fileNotice(rec.id, "CA", { ... });
+ *
+ * The registry is statutory data — operators don't override it
+ * without legal counsel review. Updates ride into the framework via
+ * patch releases when state legislatures amend their breach laws.
+ */
+
+var C = require("./constants");
+var defineClass = require("./framework-error").defineClass;
+var lazyRequire = require("./lazy-require");
+
+var audit = lazyRequire(function () { return require("./audit"); });
+
+var BreachError = defineClass("BreachError", { alwaysPermanent: true });
+
+// Per-state deadlines as days-from-detection. "WITHOUT_UNREASONABLE_DELAY"
+// is encoded as a sentinel; operators interpret as "as soon as
+// reasonably possible, never later than the longest acceptable for
+// the state's tort-liability standard". Common interpretation: 60 days
+// is a defensible ceiling, but operators with active forensics may
+// stretch to 90 days with documented investigative justification.
+var WITHOUT_UNREASONABLE_DELAY = "WITHOUT_UNREASONABLE_DELAY";
+
+var STATE_DEADLINES = Object.freeze({
+  // Each entry: { days, statute, asapCeilingDays }
+  // Days = statutory hard deadline in days. asapCeilingDays = the
+  // operator-defensible ceiling for "without unreasonable delay" states.
+  AL: { days: 45,  statute: "Ala. Code §8-38-5" }, /* allow:raw-time-literal — statutory deadline days */
+  AK: { days: 45,  statute: "Alaska Stat. §45.48.010" }, /* allow:raw-time-literal — statutory deadline days */
+  AZ: { days: 45,  statute: "Ariz. Rev. Stat. §18-552" }, /* allow:raw-time-literal — statutory deadline days */
+  AR: { days: 45,  statute: "Ark. Code §4-110-105" }, /* allow:raw-time-literal — statutory deadline days */
+  CA: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Cal. Civ. Code §1798.82", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  CO: { days: 30,  statute: "Colo. Rev. Stat. §6-1-716" }, /* allow:raw-time-literal — statutory deadline days */
+  CT: { days: 60,  statute: "Conn. Gen. Stat. §36a-701b" }, /* allow:raw-time-literal — statutory deadline days */
+  DE: { days: 60,  statute: "Del. Code §12B-102" }, /* allow:raw-time-literal — statutory deadline days */
+  DC: { days: 60,  statute: "D.C. Code §28-3852" }, /* allow:raw-time-literal — statutory deadline days */
+  FL: { days: 30,  statute: "Fla. Stat. §501.171" }, /* allow:raw-time-literal — statutory deadline days */
+  GA: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Ga. Code §10-1-911", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  HI: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Haw. Rev. Stat. §487N-2", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  ID: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Idaho Code §28-51-105", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  IL: { days: WITHOUT_UNREASONABLE_DELAY, statute: "815 ILCS 530/10", asapCeilingDays: 45 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  IN: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Ind. Code §24-4.9-3-3", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  IA: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Iowa Code §715C.2", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  KS: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Kan. Stat. §50-7a02", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  KY: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Ky. Rev. Stat. §365.732", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  LA: { days: 60,  statute: "La. Rev. Stat. §51:3074" }, /* allow:raw-time-literal — statutory deadline days */
+  ME: { days: 30,  statute: "Me. Rev. Stat. tit. 10 §1348" }, /* allow:raw-time-literal — statutory deadline days */
+  MD: { days: 45,  statute: "Md. Code Com. Law §14-3504" }, /* allow:raw-time-literal — statutory deadline days */
+  MA: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Mass. Gen. Laws ch. 93H §3", asapCeilingDays: 30 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  MI: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Mich. Comp. Laws §445.72", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  MN: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Minn. Stat. §325E.61", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  MS: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Miss. Code §75-24-29", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  MO: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Mo. Rev. Stat. §407.1500", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  MT: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Mont. Code §30-14-1704", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  NE: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Neb. Rev. Stat. §87-803", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  NV: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Nev. Rev. Stat. §603A.220", asapCeilingDays: 45 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  NH: { days: WITHOUT_UNREASONABLE_DELAY, statute: "N.H. Rev. Stat. §359-C:20", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  NJ: { days: WITHOUT_UNREASONABLE_DELAY, statute: "N.J. Stat. §56:8-163", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  NM: { days: 45,  statute: "N.M. Stat. §57-12C-6" }, /* allow:raw-time-literal — statutory deadline days */
+  NY: { days: WITHOUT_UNREASONABLE_DELAY, statute: "N.Y. Gen. Bus. Law §899-aa (SHIELD Act)", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  NC: { days: WITHOUT_UNREASONABLE_DELAY, statute: "N.C. Gen. Stat. §75-65", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  ND: { days: WITHOUT_UNREASONABLE_DELAY, statute: "N.D. Cent. Code §51-30-02", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  OH: { days: 45,  statute: "Ohio Rev. Code §1349.19" }, /* allow:raw-time-literal — statutory deadline days */
+  OK: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Okla. Stat. tit. 24 §163", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  OR: { days: 45,  statute: "Or. Rev. Stat. §646A.604" }, /* allow:raw-time-literal — statutory deadline days */
+  PA: { days: WITHOUT_UNREASONABLE_DELAY, statute: "73 Pa. Cons. Stat. §2303", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  PR: { days: 10,  statute: "P.R. Laws Ann. tit. 10 §4051 (Citizen Information Security Act)" }, /* allow:raw-time-literal — statutory deadline days */
+  RI: { days: 45,  statute: "R.I. Gen. Laws §11-49.3-3" }, /* allow:raw-time-literal — statutory deadline days */
+  SC: { days: WITHOUT_UNREASONABLE_DELAY, statute: "S.C. Code §39-1-90", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  SD: { days: 60,  statute: "S.D. Codified Laws §22-40-20" }, /* allow:raw-time-literal — statutory deadline days */
+  TN: { days: 45,  statute: "Tenn. Code §47-18-2107" }, /* allow:raw-time-literal — statutory deadline days */
+  TX: { days: 60,  statute: "Tex. Bus. & Com. Code §521.053" }, /* allow:raw-time-literal — statutory deadline days */
+  UT: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Utah Code §13-44-202", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  VT: { days: 45,  statute: "Vt. Stat. tit. 9 §2435" }, /* allow:raw-time-literal — statutory deadline days */
+  VA: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Va. Code §18.2-186.6", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  WA: { days: 30,  statute: "Wash. Rev. Code §19.255.010" }, /* allow:raw-time-literal — statutory deadline days */
+  WV: { days: WITHOUT_UNREASONABLE_DELAY, statute: "W. Va. Code §46A-2A-102", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+  WI: { days: 45,  statute: "Wis. Stat. §134.98" }, /* allow:raw-time-literal — statutory deadline days */
+  WY: { days: WITHOUT_UNREASONABLE_DELAY, statute: "Wyo. Stat. §40-12-502", asapCeilingDays: 60 }, /* allow:raw-time-literal — statutory ASAP ceiling days */
+});
+
+function _msPerDay() { return C.TIME.days(1); }
+
+function _deadlineFor(state, detectedAtMs) {
+  var rec = STATE_DEADLINES[state.toUpperCase()];
+  if (!rec) {
+    throw new BreachError("breach/unknown-state",
+      "breach.deadline: unknown state code '" + state + "' (use US 2-letter codes)");
+  }
+  if (rec.days === WITHOUT_UNREASONABLE_DELAY) {
+    return {
+      state:    state.toUpperCase(),
+      kind:     "as-soon-as-possible",
+      ceilingDays: rec.asapCeilingDays,
+      ceilingDueBy: detectedAtMs + (rec.asapCeilingDays * _msPerDay()),
+      statute:  rec.statute,
+    };
+  }
+  return {
+    state:    state.toUpperCase(),
+    kind:     "hard-deadline",
+    days:     rec.days,
+    dueBy:    detectedAtMs + (rec.days * _msPerDay()),
+    statute:  rec.statute,
+  };
+}
+
+function forStates(states, detectedAtMs) {
+  if (!Array.isArray(states)) {
+    throw new BreachError("breach/bad-states",
+      "breach.deadline.forStates: states must be an array of US state codes");
+  }
+  if (typeof detectedAtMs !== "number" || !isFinite(detectedAtMs)) {
+    throw new BreachError("breach/bad-detected-at",
+      "breach.deadline.forStates: detectedAtMs must be a finite Unix-ms timestamp");
+  }
+  var out = [];
+  for (var i = 0; i < states.length; i++) {
+    out.push(_deadlineFor(states[i], detectedAtMs));
+  }
+  return out;
+}
+
+// b.breach.report — operator-side breach-tracking that wraps the
+// deadline registry and tracks per-state filing status.
+function createReporter(opts) {
+  opts = opts || {};
+  var auditOn = opts.audit !== false;
+  var now = typeof opts.now === "function" ? opts.now : function () { return Date.now(); };
+  var seq = 0;
+  var breaches = new Map();
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   "breach.report." + action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+
+  function open(spec) {
+    if (!spec || typeof spec !== "object") {
+      throw new BreachError("breach-report/bad-spec",
+        "breach.report.open: spec must be an object with { detectedAt, affectedStates, scope, impact }");
+    }
+    if (typeof spec.detectedAt !== "number" || !isFinite(spec.detectedAt)) {
+      throw new BreachError("breach-report/bad-detected-at",
+        "breach.report.open: spec.detectedAt must be a finite Unix-ms timestamp");
+    }
+    if (!Array.isArray(spec.affectedStates) || spec.affectedStates.length === 0) {
+      throw new BreachError("breach-report/bad-states",
+        "breach.report.open: spec.affectedStates must be a non-empty array of US state codes");
+    }
+    seq += 1;
+    var id = "breach-" + new Date(spec.detectedAt).toISOString().replace(/[:.]/g, "-") + "-" + seq;
+    var deadlines = forStates(spec.affectedStates, spec.detectedAt);
+    var rec = {
+      id:               id,
+      detectedAt:       spec.detectedAt,
+      affectedStates:   spec.affectedStates.map(function (s) { return s.toUpperCase(); }),
+      scope:            spec.scope || null,
+      impact:           spec.impact || null,
+      deadlines:        deadlines,
+      filings:          {},                                                              // state -> { filedAt, late }
+      openedAt:         now(),
+      closedAt:         null,
+    };
+    breaches.set(id, rec);
+    _emitAudit("opened", "success", {
+      breachId: id,
+      states:   rec.affectedStates,
+      detectedAt: spec.detectedAt,
+    });
+    return rec;
+  }
+
+  async function fileNotice(breachId, state, fields) {
+    var rec = breaches.get(breachId);
+    if (!rec) {
+      throw new BreachError("breach-report/unknown-breach",
+        "breach.report.fileNotice: no breach with id '" + breachId + "'");
+    }
+    var stateUp = state.toUpperCase();
+    if (rec.affectedStates.indexOf(stateUp) === -1) {
+      throw new BreachError("breach-report/state-not-tracked",
+        "breach.report.fileNotice: state '" + stateUp + "' is not in this breach's affectedStates");
+    }
+    if (rec.filings[stateUp]) {
+      throw new BreachError("breach-report/already-filed",
+        "breach.report.fileNotice: filing for state '" + stateUp + "' is already recorded");
+    }
+    var deadline = rec.deadlines.filter(function (d) { return d.state === stateUp; })[0];
+    var filedAt = now();
+    var dueBy = deadline.kind === "hard-deadline" ? deadline.dueBy : deadline.ceilingDueBy;
+    var late = filedAt > dueBy;
+    rec.filings[stateUp] = {
+      filedAt: filedAt,
+      dueBy:   dueBy,
+      late:    late,
+      lateBy:  late ? (filedAt - dueBy) : 0,
+      payload: fields || {},
+    };
+    if (Object.keys(rec.filings).length === rec.affectedStates.length) {
+      rec.closedAt = filedAt;
+    }
+    _emitAudit("notice_filed", late ? "late" : "success", {
+      breachId: breachId, state: stateUp, dueBy: dueBy, late: late,
+      lateBy: rec.filings[stateUp].lateBy,
+    });
+    return rec;
+  }
+
+  function get(id) { return breaches.get(id) || null; }
+  function list() { var out = []; breaches.forEach(function (rec) { out.push(rec); }); return out; }
+  function pending(breachId) {
+    var rec = breaches.get(breachId);
+    if (!rec) return [];
+    var pendingStates = [];
+    for (var i = 0; i < rec.affectedStates.length; i++) {
+      if (!rec.filings[rec.affectedStates[i]]) {
+        pendingStates.push(rec.deadlines.filter(function (d) { return d.state === rec.affectedStates[i]; })[0]);
+      }
+    }
+    return pendingStates;
+  }
+
+  return {
+    open:         open,
+    fileNotice:   fileNotice,
+    get:          get,
+    list:         list,
+    pending:      pending,
+  };
+}
+
+module.exports = {
+  // b.breach.deadline.* — registry lookups
+  deadline: {
+    forStates:                 forStates,
+    STATE_DEADLINES:           STATE_DEADLINES,
+    WITHOUT_UNREASONABLE_DELAY: WITHOUT_UNREASONABLE_DELAY,
+  },
+  // b.breach.report.create(...) — per-incident reporter
+  report:      { create: createReporter },
+  BreachError: BreachError,
+};

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/index.js

@@ -48,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");
@@ -74,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,
@@ -120,6 +122,7 @@ module.exports = {
     requireAal:       requireAal,
     requireAuth:      requireAuth,
     requireContentType: requireContentType,
+    ageGate:          ageGate,
     requireMethods:   requireMethods,
     requireMtls:      requireMtls,
     requireStepUp:    requireStepUp,

package/lib/websocket.js

@@ -108,6 +108,36 @@ var GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
 // catches the typo class.
 var GUID_RE = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/;
 
+// Credential-shaped query parameter names refused at upgrade time. URL
+// query strings end up in: web-server access logs, the browser's
+// history + Referer header forwarded to third-party CDN / analytics
+// requests, in-process / proxy log captures, and crash dumps. Any
+// authentication credential placed in the query string is leaked
+// through one of those channels by default. RFC 6750 §2.3 explicitly
+// cautions against bearer tokens in URI query parameters for exactly
+// these reasons.
+//
+// Operators with a non-credential query parameter that happens to
+// match one of these names (e.g. an "apikey" field passed to a
+// downstream tenant API by mistake) opt out per route via
+// `opts.allowQueryAuthParams: true` with an audited operator reason —
+// the lift exists, but the operator owns the audit trail.
+//
+// The list is deliberately narrow — overloaded names like `token`,
+// `auth`, `key`, `session` have non-credential meanings (CSRF tokens,
+// file-share tokens, ICE candidates, session-resume identifiers) and
+// would create false-positive friction without closing a genuine
+// leak vector. The names below are unambiguously credential-shaped.
+var REFUSED_AUTH_QUERY_PARAMS = Object.freeze([
+  "access_token",      // OAuth 2.0 bearer (RFC 6750)
+  "bearer",            // synonym
+  "bearer_token",      // synonym
+  "apikey",            // common convention
+  "api_key",           // common convention
+  "api-key",           // common convention
+  "authorization",     // literal Authorization-header value
+]);
+
 var OPCODE_CONTINUATION = 0x0;
 var OPCODE_TEXT         = 0x1;
 var OPCODE_BINARY       = 0x2;
@@ -186,7 +216,7 @@ function computeAcceptKey(secWebSocketKey, handshakeGuid) {
   return hash.digest("base64");
 }
 
-function validateUpgradeRequest(req) {
+function validateUpgradeRequest(req, opts) {
   if (req.method !== "GET") {
     return { ok: false, status: HTTP.METHOD_NOT_ALLOWED, reason: "method must be GET" };
   }
@@ -205,9 +235,54 @@ function validateUpgradeRequest(req) {
   if (h["sec-websocket-version"] !== "13") {
     return { ok: false, status: HTTP.BAD_REQUEST, reason: "Sec-WebSocket-Version must be 13" };
   }
+  if (!(opts && opts.allowQueryAuthParams === true)) {
+    var leaked = _findCredentialQueryParam(req.url);
+    if (leaked) {
+      return {
+        ok:     false,
+        status: HTTP.BAD_REQUEST,
+        reason: "credential-shaped query parameter '" + leaked +
+          "' refused — query strings leak via logs / Referer / history. " +
+          "Move the credential to the Authorization header, or set " +
+          "opts.allowQueryAuthParams: true with an audited operator reason " +
+          "if this parameter is not actually a credential.",
+      };
+    }
+  }
   return { ok: true };
 }
 
+// _findCredentialQueryParam walks the request's query string and
+// returns the first credential-shaped parameter name it finds, or
+// null. Comparison is case-insensitive; an attacker who URL-encodes
+// the parameter name (e.g. "%41ccess_token") still hits the check
+// because URL parsing decodes the name before comparison.
+function _findCredentialQueryParam(reqUrl) {
+  if (typeof reqUrl !== "string" || reqUrl.length === 0) return null;
+  var qIdx = reqUrl.indexOf("?");
+  if (qIdx === -1) return null;
+  var query = reqUrl.slice(qIdx + 1);
+  // Strip a fragment if any (defensive — real HTTP requests don't carry
+  // one, but req.url has been observed with appended fragments behind
+  // misconfigured proxies).
+  var fIdx = query.indexOf("#");
+  if (fIdx !== -1) query = query.slice(0, fIdx);
+  if (query.length === 0) return null;
+  var pairs = query.split("&");
+  for (var p = 0; p < pairs.length; p++) {
+    var eqIdx = pairs[p].indexOf("=");
+    var rawName = eqIdx === -1 ? pairs[p] : pairs[p].slice(0, eqIdx);
+    if (rawName.length === 0) continue;
+    var name;
+    try { name = decodeURIComponent(rawName).toLowerCase(); }
+    catch (_e) { name = rawName.toLowerCase(); }
+    for (var r = 0; r < REFUSED_AUTH_QUERY_PARAMS.length; r++) {
+      if (name === REFUSED_AUTH_QUERY_PARAMS[r]) return name;
+    }
+  }
+  return null;
+}
+
 function negotiateSubprotocol(req, supported) {
   if (!supported || supported.length === 0) return null;
   var raw = (req.headers || {})["sec-websocket-protocol"] || "";
@@ -885,9 +960,9 @@ function handleUpgrade(req, socket, head, opts) {
   // Validate handshake first — refusing here writes a plain HTTP/1.1
   // response and closes the socket, matching what the upgrade-event
   // consumer would expect for a malformed request.
-  var v = validateUpgradeRequest(req);
+  var v = validateUpgradeRequest(req, opts);
   if (!v.ok) {
-    _refuseUpgrade(socket, v.status || 400, v.reason);
+    _refuseUpgrade(socket, v.status || 400, v.reason);          // allow:raw-byte-literal — HTTP 400 fallback
     return null;
   }
 
@@ -1047,6 +1122,7 @@ module.exports = {
   handleExtendedConnect:   handleExtendedConnect,   // h2 — RFC 8441 Extended CONNECT
   // Constants
   GUID:                    GUID,
+  REFUSED_AUTH_QUERY_PARAMS: REFUSED_AUTH_QUERY_PARAMS,
   OPCODE_CONTINUATION:     OPCODE_CONTINUATION,
   OPCODE_TEXT:             OPCODE_TEXT,
   OPCODE_BINARY:           OPCODE_BINARY,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.8.10",
+  "version": "0.8.12",
   "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:4c9e2f2f-795d-4920-a093-90770087d324",
+  "serialNumber": "urn:uuid:02642e79-38a6-4075-930b-85e7d621de64",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-07T02:38:14.544Z",
+    "timestamp": "2026-05-07T04:37:53.397Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.8.10",
+      "bom-ref": "@blamejs/core@0.8.12",
       "type": "library",
       "name": "blamejs",
-      "version": "0.8.10",
+      "version": "0.8.12",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.8.10",
+      "purl": "pkg:npm/%40blamejs/core@0.8.12",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.8.10",
+      "ref": "@blamejs/core@0.8.12",
       "dependsOn": []
     }
   ]