@blamejs/core 0.8.11 → 0.8.12

package/CHANGELOG.md

@@ -8,6 +8,8 @@ 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.

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.11",
+  "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:ae68f706-2c92-4dfa-b852-f29896f91c62",
+  "serialNumber": "urn:uuid:02642e79-38a6-4075-930b-85e7d621de64",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-07T03:30:10.287Z",
+    "timestamp": "2026-05-07T04:37:53.397Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.8.11",
+      "bom-ref": "@blamejs/core@0.8.12",
       "type": "library",
       "name": "blamejs",
-      "version": "0.8.11",
+      "version": "0.8.12",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.8.11",
+      "purl": "pkg:npm/%40blamejs/core@0.8.12",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.8.11",
+      "ref": "@blamejs/core@0.8.12",
       "dependsOn": []
     }
   ]