@blamejs/core 0.12.68 → 0.12.69

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.69 (2026-05-26) — **`b.middleware.botGuard` no longer blocks browsers that omit Sec-Fetch-Mode.** b.middleware.botGuard treated a missing Sec-Fetch-Mode header as a bot signal and returned 403 Forbidden, which refused legitimate browsers on any origin where the browser does not emit Fetch Metadata: every plain-HTTP non-localhost origin (Umbrel apps, LAN and *.local reverse-proxy deployments) and Safari before 16.4 even over HTTPS. Browsers only send Sec-Fetch-* in a secure context, so its absence is normal there — not a bot. Sec-Fetch-Mode is now advisory only: it never blocks, and it sets req.suspectedBot in mode:"tag" only on a secure-context HTML GET where a modern browser would have sent it. Drive-by bots are still blocked by the missing-Accept-Language and User-Agent heuristics. No configuration change is needed; if you had widened skipPaths or disabled bot-guard to work around this, you can revert that. **Fixed:** *`b.middleware.botGuard` no longer 403s browsers over plain HTTP or older Safari* — A missing `Sec-Fetch-Mode` was a blocking heuristic, but browsers omit Fetch Metadata outside a secure context (every plain-HTTP non-localhost origin — Umbrel, LAN, `*.local` proxies) and Safari < 16.4 omits it even over HTTPS. Those legitimate browsers were refused with `403 Forbidden`. `Sec-Fetch-Mode` is now advisory: it never blocks, and only sets `req.suspectedBot` in `mode: "tag"` on a secure-context HTML GET. The `Accept-Language` and User-Agent heuristics (which catch the same bots) are unchanged. **Detectors:** *reserved-hostname trailing-dot detector recognizes regex strips* — The codebase-patterns gate that requires stripping the RFC 1034 trailing root-zone dot before a reserved-hostname comparison now also recognizes end-anchored regex strips (`.replace(/\.$/, …)`), not only the `charAt` / `while`-loop forms.
+
 - v0.12.68 (2026-05-26) — **`b.jwk` — RFC 7638 JWK thumbprint.** Compute the RFC 7638 thumbprint of a JSON Web Key — the canonical base64url(SHA-256(canonical-JSON)) identifier used to name a key (DPoP jkt bindings, ACME account-key thumbprints, DBSC session pins, kid derivation). b.jwk.thumbprint(jwk) returns the digest; b.jwk.canonicalize(jwk) returns the exact JSON that is hashed — only the key-type's required members, member names in lexicographic order, no whitespace, so the same key always yields the same thumbprint regardless of how its JWK was serialized. The standard key types are supported (EC, RSA, oct, OKP per RFC 8037) plus AKP, the IANA key type Node uses for ML-DSA / SLH-DSA post-quantum public keys; SHA-256 is the default, with hash: "sha384" | "sha512" for RFC 9278 thumbprint-with-hash. Verified against the RFC 7638 §3.1 worked example. b.auth.dpop, b.acme, and b.dbsc now compute their thumbprints through this primitive. **Added:** *`b.jwk.thumbprint` / `b.jwk.canonicalize`* — RFC 7638 JWK thumbprint. `thumbprint(jwk, opts)` returns `base64url(hash(canonical-JSON))` — only the key-type's required members feed the hash, so optional fields (`kid`, `use`, `alg`, …) never change the result. `canonicalize(jwk)` returns the canonical JSON string itself. Supports EC / RSA / oct / OKP and the AKP post-quantum key type; SHA-256 default, `hash` selects SHA-384 / SHA-512. Throws `JwkError` on an invalid key or unknown hash. **Changed:** *DPoP, ACME, and DBSC compose `b.jwk`* — `b.auth.dpop` (the `jkt` proof-key thumbprint), `b.acme` (the RFC 8555 account-key authorization), and `b.dbsc` (the session-pin thumbprint) now compute RFC 7638 thumbprints through `b.jwk` instead of carrying their own implementations. Behavior is unchanged — DPoP still refuses symmetric key types, and each surface keeps its own error codes.
 
 - v0.12.66 (2026-05-26) — **`b.uriTemplate` — RFC 6570 URI Template expansion.** Expand RFC 6570 URI Templates — the {var} syntax that OpenAPI links, HAL _links, and hypermedia API clients use to turn a template plus a set of variables into a concrete URI. The full Level 4 grammar is supported: every operator ({+var} reserved, {#var} fragment, {.var} label, {/var} path, {;var} path-style parameters, {?var} query, {&var} query continuation), the {var:3} prefix modifier, and the {var*} explode modifier for lists and associative arrays. b.uriTemplate.expand(template, vars) returns the expanded string; b.uriTemplate.compile(template) parses once for templates applied to many variable sets. A malformed template (unclosed expression, reserved operator, non-numeric prefix, unmatched brace) throws UriTemplateError. Verified against the official uritemplate-test conformance suite (all 135 spec, extended, and negative cases). **Added:** *`b.uriTemplate.expand` / `b.uriTemplate.compile`* — RFC 6570 URI Template expansion, full Level 4. `expand(template, vars)` substitutes variables into a template and returns the URI; `compile(template)` returns a reusable `{ expand }` for repeated use. Variable values may be strings, numbers, booleans, arrays (lists), or plain objects (associative arrays); undefined, null, and empty list/map variables are omitted. All eight operators, the `:N` prefix modifier, and the `*` explode modifier follow §3.2, including reserved-set encoding for `{+var}` / `{#var}`. Composes naturally with `b.hal`, `b.linkHeader`, and `b.openapi` link objects. A malformed template throws `UriTemplateError`.

package/lib/middleware/bot-guard.js

@@ -6,8 +6,12 @@
  *
  * Heuristics (all combined):
  *   - Missing Accept-Language header (real browsers always send one)
- *   - Missing Sec-Fetch-Mode header (modern browsers send these on every
- *     navigation; absence is suspicious for HTML routes but not API)
+ *   - Missing Sec-Fetch-Mode header — ADVISORY ONLY (never blocks). Tagged
+ *     in mode:"tag" on secure-context HTML GETs where a modern browser
+ *     would have sent it. It cannot block because the header is absent for
+ *     entire browser families (Safari < 16.4) and for every plain-HTTP
+ *     non-localhost origin (Umbrel, LAN / *.local proxies) — a 403 on it
+ *     alone would refuse real users.
  *   - User-Agent matches known automation libraries (curl, wget, python-
  *     requests, axios, Go-http-client) — operators can add or remove
  *     entries via config
@@ -86,9 +90,13 @@ function _xffIpFor(trustProxy) {
  * Cheap fingerprint-based detection of obviously-non-browser requests.
  * Constructed via `b.middleware.botGuard(opts)`; the resulting
  * middleware has the `(req, res, next)` shape shown above.
- * Combines three heuristics: missing `Accept-Language`, missing
- * `Sec-Fetch-Mode` (HTML routes), and User-Agent regex match against
- * a default list (curl / wget / python-requests / axios / etc.). Not
+ * Two blocking heuristics — missing `Accept-Language` and a User-Agent
+ * regex match against a default list (curl / wget / python-requests /
+ * axios / etc.) — plus one advisory signal: a missing `Sec-Fetch-Mode`
+ * on a secure-context HTML GET sets `req.suspectedBot` in `mode: "tag"`
+ * but NEVER blocks (the header is absent for Safari < 16.4 and every
+ * plain-HTTP non-localhost origin, so blocking on it refuses real
+ * users). Not
  * a substitute for proper authentication — catches drive-by scrapers
  * and low-effort bots. In `mode: "block"` (default) the request is
  * refused; in `mode: "tag"` `req.suspectedBot = true` is set and the
@@ -152,6 +160,28 @@ function create(opts) {
     return /^\/api\//.test(path);
   }
 
+  // Browsers only emit Fetch Metadata (Sec-Fetch-*) in a *secure context*
+  // (W3C Secure Contexts): an HTTPS origin, or a localhost-family origin
+  // even over plain HTTP. On a plain-HTTP non-localhost origin — an Umbrel
+  // app, a LAN / *.local reverse-proxy deployment — the browser omits
+  // Sec-Fetch-* entirely, so a missing Sec-Fetch-Mode is NORMAL there and
+  // must not be read as a bot signal. The effective scheme honours
+  // X-Forwarded-Proto only under trustProxy (otherwise it is forgeable).
+  function _isSecureContext(req) {
+    if (requestHelpers.requestProtocol(req, { trustProxy: trustProxy }) === "https") return true;
+    var host = (req.headers && req.headers.host) || "";
+    host = String(host).toLowerCase().replace(/:\d+$/, "");   // strip :port
+    if (host.charAt(0) === "[") {                              // [::1] IPv6 literal
+      var end = host.indexOf("]");
+      host = end === -1 ? host.slice(1) : host.slice(1, end);
+    }
+    host = host.replace(/\.$/, "");                            // strip trailing root-zone dot (RFC 1034 §3.1) so "localhost." matches
+    if (host === "localhost" || /\.localhost$/.test(host)) return true;
+    if (host === "::1") return true;
+    if (/^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host)) return true;   // allow:regex-no-length-cap — bounded dotted-quad loopback
+    return false;
+  }
+
   function _checkHeuristics(req) {
     var headers = req.headers || {};
     var ua = headers["user-agent"] || "";
@@ -167,7 +197,14 @@ function create(opts) {
       return null;
     }
     if (!headers["accept-language"]) return "missing-accept-language";
-    if (req.method === "GET" && !headers["sec-fetch-mode"]) return "missing-sec-fetch-mode";
+    // Missing Sec-Fetch-Mode NEVER blocks: the header is absent for entire
+    // browser families (Safari < 16.4 omits Fetch Metadata even over HTTPS)
+    // and for every plain-HTTP non-localhost origin (Umbrel, LAN / *.local
+    // reverse proxies), so a 403 on it alone refuses real users. It survives
+    // only as an advisory TAG in mode:"tag", and even then only in a secure
+    // context where a modern browser would have sent it. Drive-by bots are
+    // still blocked by missing Accept-Language + the User-Agent deny-list.
+    if (mode === "tag" && req.method === "GET" && _isSecureContext(req) && !headers["sec-fetch-mode"]) return "missing-sec-fetch-mode";
     return null;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.68",
+  "version": "0.12.69",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:fafe52fa-5ff1-4704-af03-e5aeca4e55cf",
+  "serialNumber": "urn:uuid:99cf7113-3c76-4163-809f-e0478728ac1c",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-26T14:23:38.200Z",
+    "timestamp": "2026-05-26T15:45:38.862Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.68",
+      "bom-ref": "@blamejs/core@0.12.69",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.68",
+      "version": "0.12.69",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.68",
+      "purl": "pkg:npm/%40blamejs/core@0.12.69",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.68",
+      "ref": "@blamejs/core@0.12.69",
       "dependsOn": []
     }
   ]