@blamejs/core 0.5.18 → 0.6.1

package/CHANGELOG.md

@@ -6,8 +6,13 @@ Pre-1.0 the surface is intentionally evolving — every release may
 change something operators depend on. Read each entry before
 upgrading across more than a few patches at a time.
 
+## v0.6.x
+
+- **0.6.0** (2026-05-01) — wiki restructured into 22 focused pages + missing-primitive coverage
+
 ## v0.5.x
 
+- **0.5.18** (2026-05-01) — bypass-fix sweep: route through existing primitives
 - **0.5.17** (2026-05-01) — primitive-drift sweep: csv unify + 3 new shared primitives
 - **0.5.16** (2026-04-30) — b.otelExport: OTLP/HTTP exporter for b.observability
 - **0.5.15** (2026-04-30) — b.archive: ZIP creation

package/README.md

@@ -17,7 +17,7 @@ The modern Node app is a 1,200-package supply-chain liability with no LTS calend
 
 ## Status
 
-Pre-1.0. The framework is usable end-to-end — envelope-versioned PQC crypto, sealed storage, HTTP router with a full middleware stack, vault, sessions, permissions, audit chain, scheduler, jobs, notify, mail, websocket, i18n, cluster mode, backup/restore, a wiki reference app under `examples/wiki/`. Operators can build production apps on it today; the surface is still subject to change before 1.0.
+Pre-1.0. Usable end-to-end — operators can build production apps on it today; the surface is still subject to change before 1.0. Recent line is **v0.6.1** ([releases](https://github.com/blamejs/blamejs/releases) · [npm](https://www.npmjs.com/package/@blamejs/core) · [container](https://github.com/blamejs/blamejs/pkgs/container/blamejs-wiki)).
 
 ```js
 var b = require("@blamejs/core");
@@ -37,6 +37,34 @@ var b = require("@blamejs/core");
 
 **Requirements:** Node.js 24+ (current active LTS).
 
+## What ships in the box
+
+The framework bundles the surface a typical Node app reaches for. Every primitive listed is callable today; nothing is a stub.
+
+- **Data layer** — SQLite with sealed-by-default columns (`b.db`), migrations, seeders, atomic-file writes; S3 / R2 / B2 / GCS / Azure object store with multipart upload + SSE + bucket ops (`b.storage`, `b.objectStore`); durable queue with priority + cron + flows (`b.queue`, `b.jobs`); cluster-shared cache (`b.cache`).
+- **Identity & access** — passwords (Argon2id), passkeys (WebAuthn), TOTP, JWT (PQ-default), OAuth, sessions, brute-force lockout (`b.auth.*`, `b.session`); RBAC (`b.permissions`); API keys with rotation (`b.apiKey`); break-glass column gates with second-factor + audit (`b.breakGlass`).
+- **Crypto** — envelope-versioned PQC at rest (ML-KEM-1024 + P-384 hybrid, XChaCha20-Poly1305, SHAKE256), vault sealing, field-level crypto, signed webhooks (SLH-DSA-SHAKE-256f), ECIES API encryption (`b.crypto`, `b.vault`, `b.webhook`); pure-JS mTLS CA, PQC TLS gates inbound + outbound (`b.mtlsCa`, `b.pqcGate`, `b.pqcAgent`).
+- **HTTP** — router with schema-validated routes + OpenAPI publication; full middleware stack (CSRF, CORS, rate-limit, security headers, CSP nonce, body parser, compression, SSE, request log) wired by `createApp`; HTTP/1.1 + HTTP/2 outbound client with SSRF gate, redirects, multipart, interceptors, progress, encrypted cookie jar (`b.httpClient`, `b.ssrfGuard`, `b.safeUrl`).
+- **Defensive parsers** — `b.safeJson`, `b.safeBuffer`, `b.safeSql`, `b.safeSchema`, `b.parsers` (XML / TOML / YAML / .env), `b.config` (schema-validated env).
+- **Communication** — WebSockets with channel/room fan-out across cluster replicas (`b.websocket`, `b.websocketChannels`); mail with multipart + attachments + DKIM + calendar invites + bounce intake (`b.mail`, `b.mailBounce`); generic notification dispatcher with operator-supplied transports (`b.notify`).
+- **Observability** — tamper-evident audit chain with SLH-DSA-signed checkpoints, metrics, tracing (OTel pass-through when wired), PII redaction, log-stream sinks, OTLP/HTTP-JSON exporter for any OTel-compatible backend (`b.audit`, `b.metrics`, `b.tracing`, `b.redact`, `b.logStream`, `b.otelExport`).
+- **i18n** — CLDR plural rules, Accept-Language negotiation, Intl formatters, RTL (`b.i18n`).
+- **Format helpers** — RFC 4180 CSV with Excel formula-injection prevention (`b.csv`), RFC 9562 UUID v4 + v7 (`b.uuid`), URL-safe slugs (`b.slug`), TZ-aware datetime (`b.time`), ZIP creation (`b.archive`), HMAC-signed cursor pagination (`b.pagination`), HTML form rendering + validation + CSRF (`b.forms`).
+- **Production** — cluster leader election with fenced leases over Postgres/SQLite (`b.cluster`); cron + interval scheduler that runs exactly-once globally (`b.scheduler`); retry with full-jitter backoff + circuit breaker (`b.retry`); graceful shutdown (`b.appShutdown`); NTP boot check (`b.ntpCheck`); end-to-end-encrypted backup bundles (`b.backup`).
+
+## Documentation
+
+Full primitive-by-primitive docs live at [blamejs.com](https://blamejs.com), which is itself the `examples/wiki/` app running in production. The wiki is organized by concern:
+
+- **Data** — [Database](https://blamejs.com/database) · [Object Store](https://blamejs.com/object-store) · [Queue & Cache](https://blamejs.com/queue-cache)
+- **Identity** — [Authentication](https://blamejs.com/auth) · [Access Control](https://blamejs.com/access-control)
+- **Crypto** — [Crypto & Vault](https://blamejs.com/crypto-vault) · [Network Crypto](https://blamejs.com/network-crypto)
+- **HTTP** — [Routing](https://blamejs.com/routing) · [Middleware](https://blamejs.com/middleware) · [Outbound HTTP](https://blamejs.com/outbound-http)
+- **Validation** — [Safe Parsers](https://blamejs.com/safe-parsers)
+- **Communication** — [WebSockets](https://blamejs.com/websockets) · [Mail](https://blamejs.com/mail) · [Notifications](https://blamejs.com/notifications)
+- **Tools** — [Observability](https://blamejs.com/observability) · [Testing](https://blamejs.com/testing) · [i18n & Locale](https://blamejs.com/i18n-locale) · [Format Helpers](https://blamejs.com/format-helpers)
+- **Production** — [Cluster Mode](https://blamejs.com/cluster) · [Reliability](https://blamejs.com/reliability) · [Backup & Restore](https://blamejs.com/backup-restore)
+
 ## CLI
 
 `blamejs` ships an operator-facing CLI for the recurring ops work. Each subcommand boots a headless app instance from `--data-dir` (no HTTP listener), runs the operation, and shuts down. Same vault + DB + audit chain the running app uses.
@@ -87,7 +115,7 @@ Because when something breaks, `blame` should know exactly where it lives. We ow
 
 ## Contributing
 
-Patches welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev setup, house rules (zero npm runtime deps, PQC-only crypto, audit-on-every-action, no-MVP), and the PR loop. New to the codebase? Start with [ARCHITECTURE.md](ARCHITECTURE.md) for the orientation map.
+Patches welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev setup, house rules (zero npm runtime deps, PQC-only crypto, audit-on-every-action, ship-complete-not-incremental), and the PR loop. New to the codebase? Start with [ARCHITECTURE.md](ARCHITECTURE.md) for the orientation map.
 
 Community standards: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) (Contributor Covenant 2.1). Be excellent.
 

package/lib/auth/jwt.js

@@ -258,11 +258,28 @@ async function verify(token, opts) {
   }
   var tol = typeof opts.clockToleranceSec === "number" ? opts.clockToleranceSec : 0;
   var p = decoded.payload;
-  if (typeof p.exp === "number" && p.exp + tol < nowSec) {
+
+  // Strict registered-claim typing per RFC 7519 §4.1. exp / nbf / iat MUST
+  // be NumericDate values (JSON numeric, seconds since epoch). A claim
+  // present-but-not-a-number is a malformed token — silently skipping the
+  // check would let a token with `exp: "0"` or `exp: "9999999999"` (string)
+  // bypass expiration enforcement entirely.
+  function _requireNumericDate(name, value) {
+    if (typeof value !== "number" || !isFinite(value)) {
+      throw new AuthError("auth-jwt/malformed",
+        "claim '" + name + "' must be a finite number (RFC 7519 NumericDate), got " +
+        (value === null ? "null" : typeof value));
+    }
+  }
+  if (p.exp !== undefined) _requireNumericDate("exp", p.exp);
+  if (p.nbf !== undefined) _requireNumericDate("nbf", p.nbf);
+  if (p.iat !== undefined) _requireNumericDate("iat", p.iat);
+
+  if (p.exp !== undefined && p.exp + tol < nowSec) {
     throw new AuthError("auth-jwt/expired",
       "token expired at exp=" + p.exp + " (now=" + nowSec + ", tolerance=" + tol + "s)");
   }
-  if (typeof p.nbf === "number" && p.nbf - tol > nowSec) {
+  if (p.nbf !== undefined && p.nbf - tol > nowSec) {
     throw new AuthError("auth-jwt/not-yet-valid",
       "token not yet valid: nbf=" + p.nbf + " (now=" + nowSec + ", tolerance=" + tol + "s)");
   }

package/lib/middleware/cors.js

@@ -13,14 +13,19 @@
  *      works behind TLS-terminating proxies where the framework can't
  *      infer scheme), or
  *   2. Origin === request's inferred scheme/host/port (from req.socket
- *      and req.headers.host — correct for direct deployments), or
- *   3. Origin == "null" AND Sec-Fetch-Site == "same-origin" or "none".
- *      Browsers send `Origin: null` on form-navigation POSTs from a
- *      page whose response carries `Referrer-Policy: no-referrer` (or
- *      similarly strict policy) — the Origin is opaqued to prevent a
- *      cross-site leak of the page's origin. Sec-Fetch-Site is the
- *      Fetch-metadata signal that distinguishes a same-origin nav
- *      from a genuine cross-site post in that opaque-origin world.
+ *      and req.headers.host — correct for direct deployments).
+ *
+ * Origin: null shortcut (opt-in via strictNullOrigin: false): browsers
+ * send `Origin: null` on form-navigation POSTs from a page whose response
+ * carries `Referrer-Policy: no-referrer` (or similarly strict policy) —
+ * the Origin is opaqued to prevent a cross-site leak. The Sec-Fetch-Site
+ * Fetch-metadata signal distinguishes a same-origin nav from a genuine
+ * cross-site post in that opaque-origin world. Default is to REFUSE the
+ * shortcut (strictNullOrigin: true) — non-browser clients can forge
+ * Sec-Fetch-Site freely, and operators using `refuseUnknown: true` as a
+ * stricter "refuse unrecognized origin" policy expect the gate to hold.
+ * Operators with a no-referrer page that legitimately produces
+ * Origin: null on same-origin POSTs flip strictNullOrigin: false.
  *
  * Options:
  *   {
@@ -33,14 +38,16 @@
  *     maxAgeSeconds:  600
  *     refuseUnknown:  true     (refuse cross-origin requests from unlisted
  *                                origins instead of just omitting CORS headers)
+ *     strictNullOrigin: true   (default — refuse Origin: null even with
+ *                                Sec-Fetch-Site: same-origin. Set false to
+ *                                allow the no-referrer-page edge case.)
  *   }
  *
  * Audit: refuseUnknown blocks emit system.cors.block with the offending Origin.
  *
- * Validation tier: Tier A (config-time throw) — opts.siteOrigin must
- * parse as an http(s) URL, opts.origins entries must be strings or
- * RegExp. Bad config surfaces at create() not at first cross-origin
- * request.
+ * Configuration validation: opts.siteOrigin must parse as an http(s) URL,
+ * opts.origins entries must be strings or RegExp. Bad config surfaces at
+ * create() not at first cross-origin request.
  */
 var lazyRequire = require("../lazy-require");
 var audit = lazyRequire(function () { return require("../audit"); });
@@ -104,12 +111,15 @@ function _inferRequestOrigin(req, trustProxy) {
   return _canonicalOrigin(proto + "://" + host);
 }
 
-function _isSameOrigin(req, originHeader, configuredSiteOrigins, trustProxy) {
-  // Origin: null + Sec-Fetch-Site: same-origin|none — browser opaqued
-  // the Origin (typically because of Referrer-Policy: no-referrer on the
-  // page) but is also explicitly telling us the request is same-origin.
-  // Trust the Fetch-metadata signal in that case.
+function _isSameOrigin(req, originHeader, configuredSiteOrigins, trustProxy, strictNullOrigin) {
+  // Origin: null arrives when a browser opaques the Origin (e.g.
+  // Referrer-Policy: no-referrer on the page). Sec-Fetch-Site can
+  // distinguish the same-origin case, but non-browser clients can forge
+  // that header freely — strictNullOrigin: true (default) refuses the
+  // shortcut so refuseUnknown holds against forged callers. Operators
+  // with a legitimate no-referrer page flip strictNullOrigin: false.
   if (originHeader === "null") {
+    if (strictNullOrigin) return false;
     var sfs = req && req.headers && req.headers["sec-fetch-site"];
     if (sfs === "same-origin" || sfs === "none") return true;
     return false;
@@ -137,6 +147,7 @@ function create(opts) {
   validateOpts(opts, [
     "origins", "siteOrigin", "methods", "headers", "exposeHeaders",
     "credentials", "maxAgeSeconds", "refuseUnknown", "trustProxy",
+    "strictNullOrigin",
   ], "middleware.cors");
   var trustProxy = opts.trustProxy === true || typeof opts.trustProxy === "number"
     ? opts.trustProxy : false;
@@ -185,6 +196,11 @@ function create(opts) {
   var credentials = !!opts.credentials;
   var maxAge = String(opts.maxAgeSeconds || 600);
   var refuseUnknown = opts.refuseUnknown !== false;
+  // strictNullOrigin defaults true: refuse Origin: null even with
+  // Sec-Fetch-Site: same-origin (non-browser callers can forge that
+  // header). Operators with a no-referrer page producing legitimate
+  // Origin: null on same-origin POSTs flip to false explicitly.
+  var strictNullOrigin = opts.strictNullOrigin !== false;
 
   return function cors(req, res, next) {
     var origin = req.headers && req.headers.origin;
@@ -193,7 +209,7 @@ function create(opts) {
     // Same-origin POST/PUT/etc. carry an Origin header per the Fetch
     // spec but should not be subject to CORS allow-listing — they're
     // the operator's own site talking to itself.
-    if (_isSameOrigin(req, origin, siteOrigins, trustProxy)) return next();
+    if (_isSameOrigin(req, origin, siteOrigins, trustProxy, strictNullOrigin)) return next();
 
     var matched = _matchOrigin(origin, origins);
     if (!matched) {

package/lib/middleware/csrf-protect.js

@@ -50,7 +50,9 @@
  * Full options:
  *   {
  *     cookie:      true | {                  EITHER this...
- *       name:      "csrf",
+ *       name:      auto: "__Host-csrf" over HTTPS, "csrf" over HTTP.
+ *                  Operators with a custom name override here; the framework
+ *                  validates that __Host-* names carry path="/" and Secure.
  *       sameSite:  "Lax" | "Strict" | "None",
  *       secure:    auto-detected from request scheme,
  *       path:      "/",
@@ -73,7 +75,15 @@ var audit = lazyRequire(function () { return require("../audit"); });
 var DEFAULT_FIELD_NAME    = "_csrf";
 var DEFAULT_HEADER_NAME   = "X-CSRF-Token";
 var DEFAULT_METHODS       = Object.freeze(["POST", "PUT", "DELETE", "PATCH"]);
-var DEFAULT_COOKIE_NAME   = "csrf";
+
+// Default cookie name uses the RFC 6265bis __Host- prefix when the request
+// is over HTTPS. The prefix forces browsers to refuse the cookie unless
+// it carries Secure + Path=/ + no Domain attribute — closing the
+// "malicious sibling subdomain sets a cookie on the parent domain to
+// subvert double-submit verification" attack class. On plain HTTP (dev),
+// browsers reject __Host- entirely, so we fall back to the bare name.
+var DEFAULT_COOKIE_NAME_SECURE   = "__Host-csrf";
+var DEFAULT_COOKIE_NAME_INSECURE = "csrf";
 
 function _parseCookieHeader(header) {
   // Minimal cookie-header parser — RFC 6265 §5.2 form. Ignores attributes,
@@ -191,7 +201,9 @@ function create(opts) {
       throw new Error("middleware.csrfProtect: opts.cookie must be true or an object");
     }
     cookieCfg = {
-      name:     raw.name     || DEFAULT_COOKIE_NAME,
+      // name: explicit operator override wins; otherwise auto-resolved
+      // per-request based on whether the cookie is being issued Secure.
+      name:     raw.name || null,
       sameSite: raw.sameSite || "Lax",
       // secure: undefined means auto-detect from request scheme; explicit
       // true/false overrides.
@@ -203,6 +215,27 @@ function create(opts) {
     if (["Lax", "Strict", "None"].indexOf(cookieCfg.sameSite) === -1) {
       throw new Error("middleware.csrfProtect: opts.cookie.sameSite must be Lax|Strict|None");
     }
+    // __Host- prefix safety: if operator picks a __Host- name, the
+    // Path/Domain/Secure constraints must be compatible. Path must be "/",
+    // no Domain (we never set one), Secure resolved per-request. Catch
+    // operator-side typos (e.g. __Host-csrf with a custom path) at boot.
+    if (cookieCfg.name && /^__Host-/.test(cookieCfg.name)) {
+      if (cookieCfg.path !== "/") {
+        throw new Error("middleware.csrfProtect: __Host-* cookie name requires path='/'");
+      }
+      if (cookieCfg.secure === false) {
+        throw new Error("middleware.csrfProtect: __Host-* cookie name requires secure (cannot be explicit false)");
+      }
+    }
+  }
+
+  // Resolve the cookie name for a specific request — operator override
+  // wins; otherwise __Host-csrf when the cookie will be Secure, plain
+  // csrf when over HTTP (browsers reject __Host- without Secure).
+  function _resolveCookieName(req) {
+    if (cookieCfg.name) return cookieCfg.name;
+    var willBeSecure = cookieCfg.secure == null ? _isHttps(req) : !!cookieCfg.secure;
+    return willBeSecure ? DEFAULT_COOKIE_NAME_SECURE : DEFAULT_COOKIE_NAME_INSECURE;
   }
 
   function _emitDenied(req, reason) {
@@ -221,14 +254,15 @@ function create(opts) {
   // req.csrfToken so templates have something to render.
   function _issueIfNeeded(req, res) {
     if (!cookieCfg) return null;
+    var cookieName = _resolveCookieName(req);
     var cookies = _parseCookieHeader(req.headers && req.headers.cookie);
-    var existing = cookies[cookieCfg.name];
+    var existing = cookies[cookieName];
     if (existing && /^[a-f0-9]{2,}$/.test(existing)) {
       req.csrfToken = existing;
       return existing;
     }
     var fresh = forms.generateCsrfToken();
-    var setCookie = _formatSetCookie(cookieCfg.name, fresh, {
+    var setCookie = _formatSetCookie(cookieName, fresh, {
       path:     cookieCfg.path,
       sameSite: cookieCfg.sameSite,
       secure:   cookieCfg.secure == null ? _isHttps(req) : !!cookieCfg.secure,

package/lib/middleware/rate-limit.js

@@ -64,11 +64,23 @@ function _clientIpFor(trustProxy) {
   };
 }
 
+// Reject NaN / Infinity / negative / non-positive / non-number at create
+// time so a misconfigured rate-limit can't silently degrade to "no
+// limit" or produce divide-by-zero verdicts at request time.
+function _requirePositiveNumber(name, value) {
+  if (typeof value !== "number" || !isFinite(value) || value <= 0) {
+    throw new Error("middleware.rateLimit: " + name + " must be a positive finite number, got " +
+      JSON.stringify(value));
+  }
+}
+
 // ---- Memory backend (token bucket) ----
 
 function _memoryBackend(opts) {
-  var burst = opts.burst || 60;
-  var refillPerSecond = opts.refillPerSecond || 10;
+  var burst = opts.burst != null ? opts.burst : 60;
+  var refillPerSecond = opts.refillPerSecond != null ? opts.refillPerSecond : 10;
+  _requirePositiveNumber("burst", burst);
+  _requirePositiveNumber("refillPerSecond", refillPerSecond);
   var buckets = new Map();
 
   // Periodic GC of stale buckets so the map doesn't grow unbounded.
@@ -128,9 +140,13 @@ function _memoryBackend(opts) {
 // ---- Cluster backend (fixed-window counter, SQL-backed) ----
 
 function _clusterBackend(opts) {
-  var limit    = opts.limit    || 60;
-  var windowMs = opts.windowMs || C.TIME.minutes(1);
-  var pruneIntervalMs = opts.pruneIntervalMs || C.TIME.minutes(5);
+  var limit    = opts.limit    != null ? opts.limit    : 60;
+  var windowMs = opts.windowMs != null ? opts.windowMs : C.TIME.minutes(1);
+  var pruneIntervalMs = opts.pruneIntervalMs != null
+    ? opts.pruneIntervalMs : C.TIME.minutes(5);
+  _requirePositiveNumber("limit", limit);
+  _requirePositiveNumber("windowMs", windowMs);
+  _requirePositiveNumber("pruneIntervalMs", pruneIntervalMs);
   var lastPruneAt = 0;
 
   // Best-effort prune of expired window rows. Rate-limited at the

package/package.json

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