@blamejs/core 0.8.51 → 0.8.57

package/lib/middleware/clear-site-data.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * @module     b.middleware.clearSiteData
+ * @nav        HTTP
+ * @title      Clear-Site-Data
+ * @order      120
+ * @card       RFC 9527 Clear-Site-Data middleware — wipe browser-side
+ *             state (cookies, storage, cache, executionContexts) when
+ *             a session ends. Mount on logout/erase routes; the
+ *             header tells the UA to drop everything before navigating
+ *             away so the next request starts clean.
+ *
+ * @intro
+ *   The framework's logout primitive should not just delete the
+ *   server-side session — it should tell the user-agent to drop every
+ *   browser-side trace too. RFC 9527 Clear-Site-Data is the header
+ *   that does it: the UA sees the response and synchronously evicts
+ *   the named state types BEFORE running any subsequent navigation
+ *   code, so a stale tab doesn't leak post-logout requests carrying
+ *   the previous user's cookies.
+ *
+ *   Common shape on a logout endpoint:
+ *
+ *     app.post("/logout", [
+ *       b.middleware.requireAuth(),
+ *       async function (req, res) {
+ *         await req.session.destroy();
+ *         b.middleware.clearSiteData()(req, res, function () {});
+ *         res.redirect("/");
+ *       },
+ *     ]);
+ *
+ *   Or as drop-in middleware on every route under a path prefix:
+ *
+ *     app.use("/account/erase", b.middleware.clearSiteData());
+ *
+ *   Default types: `cookies`, `storage`, `cache`, `executionContexts`.
+ *   Operators wanting a narrower wipe (e.g. only `cache`) pass
+ *   `{ types: ["cache"] }`. Wildcard `"*"` is supported but discouraged
+ *   — it tells the UA to wipe the whole origin including cross-tab
+ *   service workers, which often surprises operators.
+ */
+
+var validateOpts = require("../validate-opts");
+
+// RFC 9527 §3 — the canonical token set. `clientHints` was added in
+// the 2024 revision; `executionContexts` reloads any documents the
+// origin currently has open (closes XSS-style hijacked tabs).
+var KNOWN_TYPES = {
+  "cookies":            true,
+  "storage":            true,
+  "cache":              true,
+  "executionContexts":  true,
+  "clientHints":        true,
+  "*":                  true,
+};
+
+var DEFAULT_TYPES = ["cookies", "storage", "cache", "executionContexts"];
+
+/**
+ * @primitive b.middleware.clearSiteData
+ * @signature b.middleware.clearSiteData(req, res, next)
+ * @since     0.8.53
+ * @status    stable
+ * @related   b.middleware.securityHeaders, b.session
+ *
+ * Builds middleware that emits an RFC 9527 Clear-Site-Data response
+ * header. Mount on logout / account-erase / consent-revoke routes
+ * so the user-agent wipes browser-side state synchronously before
+ * the next navigation. Without this header, a logged-out tab can
+ * still carry cookies and cached responses past the server-side
+ * session destruction, leaking post-logout requests.
+ *
+ * @opts
+ *   {
+ *     types: Array<"cookies"|"storage"|"cache"|"executionContexts"|"clientHints"|"*">,
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.post("/logout", [
+ *     b.middleware.clearSiteData(),
+ *     async function (req, res) {
+ *       await req.session.destroy();
+ *       res.redirect("/");
+ *     },
+ *   ]);
+ */
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, ["types"], "middleware.clearSiteData");
+  var types = opts.types === undefined ? DEFAULT_TYPES : opts.types;
+  if (!Array.isArray(types) || types.length === 0) {
+    throw new TypeError("middleware.clearSiteData: opts.types must be a non-empty array");
+  }
+  for (var i = 0; i < types.length; i += 1) {
+    var t = types[i];
+    if (typeof t !== "string" || !KNOWN_TYPES[t]) {
+      throw new TypeError(
+        "middleware.clearSiteData: unknown type '" + t +
+        "' (expected one of: " + Object.keys(KNOWN_TYPES).join(", ") + ")");
+    }
+  }
+  // Header value is a comma-separated list of double-quoted tokens
+  // per RFC 9527 §3 (Structured Field Value List of Strings). Build
+  // once at construction time — runtime cost is one setHeader call.
+  var headerValue = types.map(function (t) { return '"' + t + '"'; }).join(", ");
+
+  return function clearSiteData(req, res, next) {
+    if (typeof res.setHeader === "function") {
+      res.setHeader("Clear-Site-Data", headerValue);
+    }
+    next();
+  };
+}
+
+module.exports = {
+  create:        create,
+  KNOWN_TYPES:   Object.keys(KNOWN_TYPES),
+  DEFAULT_TYPES: DEFAULT_TYPES,
+};

package/lib/middleware/dpop.js

@@ -121,7 +121,7 @@ function _reconstructHtu(req) {
  * @primitive b.middleware.dpop
  * @signature b.middleware.dpop(opts)
  * @since     0.1.0
- * @related   b.middleware.bearerAuth, b.auth.jwt
+ * @related   b.middleware.bearerAuth
  *
  * RFC 9449 Demonstrating Proof of Possession (DPoP). Verifies the
  * `DPoP` header on inbound requests, attaches `req.dpop = { header,

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 clearSiteData = require("./clear-site-data");
 var botDisclose = require("./bot-disclose");
 var botGuard = require("./bot-guard");
 var compression = require("./compression");
@@ -42,8 +43,10 @@ var gpc = require("./gpc");
 var headers = require("./headers");
 var health = require("./health");
 var hostAllowlist = require("./host-allowlist");
+var nel = require("./nel");
 var networkAllowlist = require("./network-allowlist");
 var rateLimit = require("./rate-limit");
+var speculationRules = require("./speculation-rules");
 var requestId = require("./request-id");
 var requestLog = require("./request-log");
 var requireAal = require("./require-aal");
@@ -108,6 +111,9 @@ module.exports = {
   tracePropagate:        tracePropagate.create,
   tusUpload:        tusUpload.create,
   webAppManifest:   webAppManifest.create,
+  clearSiteData:    clearSiteData.create,
+  nel:              nel.create,
+  speculationRules: speculationRules.create,
 
   // Module exports for advanced use (constants, raw factory access)
   _modules: {
@@ -152,6 +158,9 @@ module.exports = {
     tracePropagate:        tracePropagate,
     tusUpload:        tusUpload,
     webAppManifest:   webAppManifest,
+    clearSiteData:    clearSiteData,
+    nel:              nel,
+    speculationRules: speculationRules,
   },
 };
 

package/lib/middleware/nel.js

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * @module     b.middleware.nel
+ * @nav        HTTP
+ * @title      Network Error Logging
+ * @order      125
+ * @card       W3C Network Error Logging — emits the `NEL` and companion
+ *             `Report-To` headers so user-agents post network-failure
+ *             reports (DNS failures, TLS handshake errors, TCP resets,
+ *             HTTP-error class samples) back to an operator-controlled
+ *             collector. Pair with `b.middleware.cspReport` for a
+ *             unified browser-side telemetry channel.
+ *
+ * @intro
+ *   Network Error Logging (W3C draft) is the browser's native channel
+ *   for surfacing failures the server never sees: TLS handshake
+ *   collapse before the request body, DNS lookup misses, CDN routing
+ *   resets, premature TCP teardown mid-response. The user-agent
+ *   buffers these and POSTs JSON reports to a configured collector,
+ *   keyed by the `report-to` group named in the `NEL` header.
+ *
+ *   The middleware emits two response headers on every request it
+ *   sees:
+ *
+ *     Report-To: { "group": "default", "max_age": 86400, "endpoints":
+ *       [ { "url": "https://collector.example.com/nel" } ] }
+ *     NEL:       { "report_to": "default", "max_age": 86400,
+ *       "include_subdomains": false, "success_fraction": 0,
+ *       "failure_fraction": 1 }
+ *
+ *   Both header values are JSON dictionaries; the framework refuses
+ *   any operator-supplied collector URL containing CR/LF/NUL so a
+ *   typo can't smuggle a header-injection payload into the wire
+ *   format.
+ *
+ *   Mount AFTER `securityHeaders` (so the response writeHead order
+ *   stays predictable) and BEFORE business middleware. Pair with
+ *   `b.middleware.cspReport` so a single collector receives both NEL
+ *   and CSP reports — operators commonly point both at the same
+ *   `/_telemetry` endpoint.
+ *
+ *     app.use(b.middleware.requestId());
+ *     app.use(b.middleware.securityHeaders());
+ *     app.use(b.middleware.nel({
+ *       reportTo:           "default",
+ *       collectorUrl:       "https://collector.example.com/nel",
+ *       maxAge:             86400,
+ *       includeSubdomains:  false,
+ *       successFraction:    0,
+ *       failureFraction:    1,
+ *     }));
+ *
+ *   The `successFraction` defaults to 0 because reporting every
+ *   successful request is a billing surprise on busy origins;
+ *   operators tune it up (0.001, 0.01) when sampling success
+ *   distribution intentionally.
+ */
+
+var validateOpts = require("../validate-opts");
+var C = require("../constants");
+
+// Per W3C draft + the practical browser implementations. successFraction
+// = 1.0 reports every request — fine for a low-traffic admin surface,
+// catastrophic on a high-traffic CDN. failureFraction = 1.0 is the
+// security-correct default; operators only lower it when they have a
+// downstream rate-limit on the collector.
+var DEFAULT_REPORT_GROUP    = "default";
+var DEFAULT_MAX_AGE         = C.TIME.hours(24) / C.TIME.seconds(1);  // NEL header takes seconds
+var DEFAULT_SUCCESS_FRACTION = 0;
+var DEFAULT_FAILURE_FRACTION = 1;
+
+// Header injection defense — every operator-supplied string that
+// reaches a header value is screened for CR/LF/NUL. The collector
+// URL flows into JSON inside Report-To; a CR there would let an
+// attacker forge an arbitrary follow-up header on stacks that
+// concatenate header lines naively.
+var INJECTION_RE = /[\r\n\0]/;
+
+function _refuseInjection(value, label) {
+  if (typeof value !== "string") return;
+  if (INJECTION_RE.test(value)) {  // allow:regex-no-length-cap — CR/LF/NUL injection check, length bounded by caller
+    throw new TypeError(
+      "middleware.nel: " + label + " contains CR/LF/NUL — refused as a " +
+      "header-injection vector");
+  }
+}
+
+/**
+ * @primitive b.middleware.nel
+ * @signature b.middleware.nel(req, res, next)
+ * @since     0.8.53
+ * @status    stable
+ * @related   b.middleware.cspReport, b.middleware.securityHeaders
+ *
+ * Builds middleware that emits the W3C Network Error Logging `NEL`
+ * and companion `Report-To` headers so user-agents post failure
+ * telemetry back to an operator-controlled collector. Mount near the
+ * top of the chain (after `requestId` and `securityHeaders`) so every
+ * response carries the headers — NEL is a long-lived browser policy,
+ * not a per-route concern.
+ *
+ * The two header bodies are JSON dictionaries built once at construct
+ * time. Operator-supplied strings flow through a CR/LF/NUL refusal
+ * check so a typo in `collectorUrl` can't smuggle additional headers
+ * onto the wire.
+ *
+ * @opts
+ *   {
+ *     reportTo:          string,    // group name (default "default")
+ *     collectorUrl:      string,    // required — collector POST URL
+ *     maxAge:            number,    // policy lifetime in seconds (default 86400)
+ *     includeSubdomains: boolean,   // default false
+ *     successFraction:   number,    // 0..1, default 0
+ *     failureFraction:   number,    // 0..1, default 1
+ *   }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var app = b.router.create();
+ *   app.use(b.middleware.requestId());
+ *   app.use(b.middleware.securityHeaders());
+ *   app.use(b.middleware.nel({
+ *     collectorUrl:      "https://collector.example.com/nel",
+ *     maxAge:            86400,
+ *     successFraction:   0,
+ *     failureFraction:   1,
+ *   }));
+ */
+function create(opts) {
+  opts = opts || {};
+  validateOpts(opts, [
+    "reportTo", "collectorUrl", "maxAge",
+    "includeSubdomains", "successFraction", "failureFraction",
+  ], "middleware.nel");
+
+  // Per-file allowlist in test/layer-0-primitives/codebase-patterns.test.js
+  // for inline-require-non-empty-string-validation — the operator-readable
+  // "collectorUrl is required" prose is part of the public test contract;
+  // validateOpts.requireNonEmptyString would emit a generic
+  // "validate-opts/missing-non-empty-string" message instead.
+  if (typeof opts.collectorUrl !== "string" || opts.collectorUrl.length === 0) {
+    throw new TypeError(
+      "middleware.nel: opts.collectorUrl is required (the URL the user-agent " +
+      "POSTs network-failure reports to)");
+  }
+  _refuseInjection(opts.collectorUrl, "opts.collectorUrl");
+
+  // The collector URL must be an https:// scheme — browsers only
+  // honor secure-origin report endpoints. Refusing at config-time so
+  // an operator typo (`http://`) surfaces at boot, not as silent
+  // never-fires-in-production.
+  if (opts.collectorUrl.slice(0, 8) !== "https://") {                                       // allow:raw-byte-literal — string-prefix length, not bytes
+    throw new TypeError(
+      "middleware.nel: opts.collectorUrl must be https:// (browsers " +
+      "ignore non-secure NEL collectors); got " + opts.collectorUrl);
+  }
+
+  var reportTo = opts.reportTo === undefined ? DEFAULT_REPORT_GROUP : opts.reportTo;
+  if (typeof reportTo !== "string" || reportTo.length === 0) {
+    throw new TypeError("middleware.nel: opts.reportTo must be a non-empty string");
+  }
+  _refuseInjection(reportTo, "opts.reportTo");
+
+  var maxAge = opts.maxAge === undefined ? DEFAULT_MAX_AGE : opts.maxAge;
+  if (typeof maxAge !== "number" || !isFinite(maxAge) || maxAge < 0) {
+    throw new TypeError("middleware.nel: opts.maxAge must be a non-negative finite number (seconds)");
+  }
+
+  var includeSubdomains = opts.includeSubdomains === undefined ? false : !!opts.includeSubdomains;
+
+  var successFraction = opts.successFraction === undefined ? DEFAULT_SUCCESS_FRACTION : opts.successFraction;
+  if (typeof successFraction !== "number" || !isFinite(successFraction) ||
+      successFraction < 0 || successFraction > 1) {
+    throw new TypeError("middleware.nel: opts.successFraction must be a number in [0, 1]");
+  }
+
+  var failureFraction = opts.failureFraction === undefined ? DEFAULT_FAILURE_FRACTION : opts.failureFraction;
+  if (typeof failureFraction !== "number" || !isFinite(failureFraction) ||
+      failureFraction < 0 || failureFraction > 1) {
+    throw new TypeError("middleware.nel: opts.failureFraction must be a number in [0, 1]");
+  }
+
+  // Build the two header values once at construct time. JSON.stringify
+  // produces the canonical compact form; the property ordering is
+  // stable per V8 spec.
+  var reportToHeader = JSON.stringify({
+    group:     reportTo,
+    max_age:   maxAge,
+    endpoints: [{ url: opts.collectorUrl }],
+  });
+  var nelHeader = JSON.stringify({
+    report_to:          reportTo,
+    max_age:            maxAge,
+    include_subdomains: includeSubdomains,
+    success_fraction:   successFraction,
+    failure_fraction:   failureFraction,
+  });
+
+  return function nel(req, res, next) {
+    if (typeof res.setHeader === "function") {
+      res.setHeader("Report-To", reportToHeader);
+      res.setHeader("NEL",       nelHeader);
+    }
+    next();
+  };
+}
+
+module.exports = {
+  create:                   create,
+  DEFAULT_REPORT_GROUP:     DEFAULT_REPORT_GROUP,
+  DEFAULT_MAX_AGE:          DEFAULT_MAX_AGE,
+  DEFAULT_SUCCESS_FRACTION: DEFAULT_SUCCESS_FRACTION,
+  DEFAULT_FAILURE_FRACTION: DEFAULT_FAILURE_FRACTION,
+};

package/lib/middleware/security-headers.js

@@ -76,12 +76,51 @@ var DEFAULT_CSP =
   "font-src 'self'; " +
   "connect-src 'self'; " +
   "frame-ancestors 'none'; " +
+  // CSP3 fenced-frame-src: refuse <fencedframe> embeds entirely. The
+  // Privacy-Sandbox-era element bypasses traditional frame controls;
+  // operators wanting to embed a Privacy-Sandbox vendor opt in by
+  // passing their own csp.
+  "fenced-frame-src 'none'; " +
   "base-uri 'self'; " +
   "form-action 'self'; " +
   "object-src 'none'; " +
   "require-trusted-types-for 'script'; " +
   "trusted-types 'allow-duplicates' default;";
 
+// Document-Policy default — denies the highest-risk DOM/JS surfaces
+// that aren't otherwise covered by Permissions-Policy. `unsized-media`
+// blocks layout-jank from images without explicit width/height,
+// `oversized-images` caps the served-vs-displayed ratio, and the
+// document-write feature disables the legacy synchronous DOM-injection
+// API. Operators with a third-party widget that needs the legacy API
+// override.
+var DEFAULT_DOCUMENT_POLICY =
+  "document-write=?0, " +
+  "unsized-media=?0, " +
+  "oversized-images=?0";
+
+// RFC 9651 (Structured Field Values) Permissions-Policy validation —
+// each policy is `feature=value-list` where value-list is `*` /
+// `(self)` / `(self "https://...")` / `()` (empty = deny). Reject
+// header values that don't conform; operators get a clear refusal at
+// boot rather than a silently-broken header at runtime.
+var PP_POLICY_RE =
+  /^[a-z][a-z0-9-]*=(?:\*|\([^)]*\)|self)$/;
+function _validatePermissionsPolicy(value) {
+  if (typeof value !== "string" || value.length === 0) return;
+  var parts = String(value).split(/\s*,\s*/);
+  for (var i = 0; i < parts.length; i += 1) {
+    var p = parts[i];
+    if (!p) continue;
+    if (!PP_POLICY_RE.test(p)) {  // allow:regex-no-length-cap — RFC 9651 SF entries are bounded by browser parsers; operator-supplied
+      throw new TypeError(
+        "middleware.securityHeaders: permissionsPolicy entry '" + p +
+        "' is not a valid RFC 9651 structured field (expected " +
+        "'feature=*' / 'feature=()' / 'feature=(self ...)')");
+    }
+  }
+}
+
 /**
  * @primitive b.middleware.securityHeaders
  * @signature b.middleware.securityHeaders(req, res, next)
@@ -115,6 +154,9 @@ var DEFAULT_CSP =
  *     originAgentCluster: "?1"|"?0"|false,
  *     dnsPrefetchControl: "off"|"on"|false,
  *     csp:                string|false,
+ *     documentPolicy:     string|false,
+ *     acceptCh:           string|false,
+ *     criticalCh:         string|false,
  *     reportingEndpoints: object,
  *     trustProxy:         boolean|number,
  *   }
@@ -132,8 +174,11 @@ function create(opts) {
     "hsts", "contentTypeOptions", "frameOptions", "referrerPolicy",
     "permissionsPolicy", "coop", "coep", "corp",
     "originAgentCluster", "dnsPrefetchControl", "csp", "trustProxy",
-    "reportingEndpoints",
+    "reportingEndpoints", "documentPolicy", "criticalCh", "acceptCh",
   ], "middleware.securityHeaders");
+  if (opts.permissionsPolicy && typeof opts.permissionsPolicy === "string") {
+    _validatePermissionsPolicy(opts.permissionsPolicy);
+  }
   var trustProxy = opts.trustProxy === true || typeof opts.trustProxy === "number"
     ? opts.trustProxy : false;
   var hsts = opts.hsts === undefined ? "max-age=63072000; includeSubDomains; preload" : opts.hsts;
@@ -147,6 +192,9 @@ function create(opts) {
   var oac   = opts.originAgentCluster === undefined ? "?1" : opts.originAgentCluster;
   var dpc   = opts.dnsPrefetchControl === undefined ? "off" : opts.dnsPrefetchControl;
   var csp   = opts.csp === undefined ? DEFAULT_CSP : opts.csp;
+  var docPolicy = opts.documentPolicy === undefined ? DEFAULT_DOCUMENT_POLICY : opts.documentPolicy;
+  var criticalCh = opts.criticalCh && typeof opts.criticalCh === "string" ? opts.criticalCh : false;
+  var acceptCh   = opts.acceptCh   && typeof opts.acceptCh   === "string" ? opts.acceptCh   : false;
   // Reporting-Endpoints (W3C Reporting API) — when operator passes a
   // map of endpoint-name → URL, we emit `Reporting-Endpoints: name="url",
   // name2="url2", ...` and (when default CSP is in force) append
@@ -194,13 +242,17 @@ function create(opts) {
     if (oac)        res.setHeader("Origin-Agent-Cluster", oac);
     if (dpc)        res.setHeader("X-DNS-Prefetch-Control", dpc);
     if (csp)                res.setHeader("Content-Security-Policy", csp);
+    if (docPolicy)          res.setHeader("Document-Policy", docPolicy);
+    if (acceptCh)           res.setHeader("Accept-CH", acceptCh);
+    if (criticalCh)         res.setHeader("Critical-CH", criticalCh);
     if (reportingEndpoints) res.setHeader("Reporting-Endpoints", reportingEndpoints);
     next();
   };
 }
 
 module.exports = {
-  create:               create,
-  DEFAULT_PERMISSIONS:  DEFAULT_PERMISSIONS,
-  DEFAULT_CSP:          DEFAULT_CSP,
+  create:                  create,
+  DEFAULT_PERMISSIONS:     DEFAULT_PERMISSIONS,
+  DEFAULT_CSP:             DEFAULT_CSP,
+  DEFAULT_DOCUMENT_POLICY: DEFAULT_DOCUMENT_POLICY,
 };