@blamejs/core 0.17.15 → 0.17.16

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.17.x
 
+- v0.17.16 (2026-07-23) — **A shared path-containment primitive backs both the strict resolver and static file serving.** b.safePath.resolve and b.staticServe each hand-rolled the same lexical traversal-containment check -- resolve a request path against a base and confirm it stays strictly inside. That core is now one primitive, b.safePath.confineToBase, which both compose: resolve layers its user-input strictness (reserved names, NTFS ADS markers, bidi, control chars) on top, while static serving composes only the bare containment and keeps its own separate basename gate. Static serving keeps that separation deliberately -- its containment barrier and its per-file guardFilename validation are distinct concerns -- and inherits the resolver's cross-platform-aware containment, which the runtime path module missed for a backslash traversal on a POSIX host. Static serving's basename policy is unchanged. **Added:** *b.safePath.confineToBase -- the lexical traversal-containment core* — b.safePath.confineToBase(base, rel, opts?) resolves rel against base using the target platform's path semantics and returns the confined absolute path, or null if it escapes. It is the containment barrier b.safePath.resolve layers its user-input strictness on top of, exposed for a consumer that wants ONLY traversal containment and applies its own, differently-calibrated filename validation -- so it does not reject a reserved name, NTFS ADS marker, or trailing dot the way resolve does for untrusted input. opts.platform forces windows path semantics on any host. **Changed:** *Static file serving composes the shared containment primitive* — b.staticServe's path-traversal barrier now composes b.safePath.confineToBase for its final lexical containment instead of a hand-rolled join + base-prefix check, so both the strict resolver and static serving route through one implementation. Static serving gains the cross-platform-aware containment (the runtime path module treats the other platform's separator as an ordinary filename character and missed a backslash traversal on a POSIX host). Serve behavior is unchanged: containment and the separate per-file guardFilename basename gate remain distinct steps, and static composes only the containment core rather than resolve so it does not fuse resolve's all-segment user-input strictness into the barrier (which would reject a legitimate colon-named intermediate directory that the basename gate permits). The basename policy itself is untouched.
+
 - v0.17.15 (2026-07-23) — **The standalone multipart parser honors storage: memory and every other documented upload knob.** b.parsers.multipart(req, opts) is documented as a thin wrapper over the same engine b.middleware.bodyParser drives, but its option resolver carried a hand-maintained passthrough list that had drifted: storage ("disk" | "memory") and filenameCharsets were silently dropped, so a serverless / read-only-filesystem handler passing storage: "memory" got disk mode instead and threw when the parser tried to open a temp file. The passthrough is now derived from the parser's own defaults, so every documented knob reaches the standalone path and a future knob cannot silently vanish, and an invalid storage value throws at the call the same way the middleware does instead of falling through to disk. **Fixed:** *b.parsers.multipart honors storage: memory and filenameCharsets* — The standalone multipart parser's option resolver passed through a hand-maintained subset of the multipart knobs, omitting storage and filenameCharsets: b.parsers.multipart(req, { storage: "memory" }) silently used disk mode and then threw on a read-only / serverless filesystem, and a filename*=ISO-8859-1'' part could not be opted in via filenameCharsets. The passthrough is now derived from the parser's DEFAULTS so every documented knob reaches the standalone path (only the maxBytes/maxFiles aliases and the dispatch-only contentTypes are excluded), and an invalid storage value throws a TypeError at the call rather than falling back to disk -- matching b.middleware.bodyParser.
 
 - v0.17.14 (2026-07-23) — **The framework's file watchers are hardened against an uncatchable process abort on Windows 8.3 short-name paths.** fs.watch aborts the whole Node process -- an uncatchable libuv assertion in the directory-change backend -- when the watched path is reached through a Windows 8.3 short-name component (the shape of a path under C:\Users\SOMEUS~1\... or a short-named temp directory). The recursive file watcher already expanded the short name before watching; this closes the same gap everywhere else the framework watches a path: the feature-flag file watcher now stat-polls its config file instead of directory-watching it, and the dev-server and bundler watchers expand the short name before watching. Three structural detectors lock the invariant in so it cannot regress in a way a behavioral test cannot reach (the abort only fires on a real short-name path, which a host with 8.3 generation disabled cannot reproduce). **Changed:** *Public Suffix List refreshed to the current upstream snapshot* — The vendored Mozilla Public Suffix List is updated to the current upstream snapshot, so organizational-domain derivation reflects the latest registry delegations wherever the framework draws a registrable-domain boundary -- DMARC identifier alignment, BIMI issuer scoping, cookie-scope confinement, and same-site policy. The .data.js carrier is regenerated and re-signed across all four integrity layers. **Fixed:** *The feature-flag file watcher no longer aborts on a Windows short-name config path* — b.flags localFile provider with watch enabled directory-watched the config file via fs.watch, which aborts the process (uncatchable) when the config path resolves through a Windows 8.3 short-name component -- its surrounding try/catch cannot recover from a libuv abort(). It now stat-polls the file (StatWatcher opens no directory-change handle, so it is immune to the path form) and reloads on change with sub-second latency. · *The dev-server and bundler watchers expand a short-name path before watching* — b.dev and b.bundler watch a source directory or file via fs.watch; on Windows a path reached through an 8.3 short-name component aborts libuv. Both now resolve the real long-form path (realpathSync.native) before the watch, matching the guard the recursive b.watcher already applied. **Detectors:** *Filesystem-watch short-name safety and pid-liveness composition are enforced structurally* — Three codebase-patterns detectors close invariants a behavioral test cannot assert (the underlying abort is environment-specific to a real 8.3 short-name path): any lib fs.watch must expand the short name via realpathSync.native in the same file (or use the StatWatcher path instead); the daemon's Windows cooperative-stop sentinel must poll a synchronous existsSync rather than watch the filesystem; and a signal-0 process-liveness probe must compose the shared pid-probe classifier rather than re-roll process.kill(pid, 0) with its own EPERM/ESRCH interpretation.

package/lib/safe-path.js

@@ -138,6 +138,53 @@ function validate(base, rel, opts) {
   catch (e) { return { ok: false, code: e.code || "safe-path/unknown", message: e.message }; }
 }
 
+/**
+ * @primitive b.safePath.confineToBase
+ * @signature b.safePath.confineToBase(base, rel, opts?)
+ * @since     0.17.16
+ * @status    stable
+ * @related   b.safePath.resolve, b.staticServe.create
+ *
+ * The lexical traversal-containment core, WITHOUT the user-input
+ * strictness of `resolve` (no reserved-name / ADS / bidi / control-char
+ * refusal). Resolve `rel` against `base` using the TARGET platform's path
+ * semantics and confirm the result stays strictly inside `base`; return
+ * the confined absolute path, or `null` if it escapes.
+ *
+ * This is the barrier `resolve` layers its user-input checks on top of,
+ * and the one a consumer composes when it wants ONLY traversal containment
+ * and runs its OWN, separately-calibrated filename validation — as
+ * b.staticServe does, keeping its per-file basename gate (b.guardFilename)
+ * a distinct step rather than fusing `resolve`'s all-segment user-input
+ * strictness into the containment barrier.
+ *
+ * @opts
+ *   platform: string,   // "windows" forces win32 path semantics regardless of host
+ *
+ * @example
+ *   var p = b.safePath.confineToBase("/srv/www", "docs/a.html");
+ *   // → "/srv/www/docs/a.html"  (null if rel escaped /srv/www)
+ */
+function confineToBase(base, rel, opts) {
+  opts = opts || {};
+  if (typeof base !== "string" || base.length === 0) return null;
+  if (typeof rel !== "string") return null;
+  var platform = opts.platform || process.platform;
+  var isWin = platform === "win32" || platform === "windows";
+  // Resolve + contain using the TARGET platform's path module, NOT the
+  // runtime's: the runtime path module would treat the OTHER platform's
+  // separator as an ordinary filename character and miss a backslash
+  // traversal on a POSIX host (and inversely false-refuse legitimate paths).
+  var pathMod = isWin ? nodePath.win32 : nodePath.posix;
+  var baseResolved = pathMod.resolve(base);
+  var joined = pathMod.resolve(baseResolved, rel);
+  var sepChar = pathMod.sep;
+  if (joined !== baseResolved && joined.slice(0, baseResolved.length + 1) !== baseResolved + sepChar) {
+    return null;
+  }
+  return joined;
+}
+
 function _resolveCore(base, rel, opts) {
   if (typeof base !== "string" || base.length === 0) {
     _refuse("safe-path/bad-input", "b.safePath.resolve: base must be a non-empty string");
@@ -219,11 +266,11 @@ function _resolveCore(base, rel, opts) {
   // that hole AND stops the inverse false-refusal of legitimate in-base paths.
   var pathMod = isWin ? nodePath.win32 : nodePath.posix;
   var baseResolved = pathMod.resolve(base);
-  var joined = pathMod.resolve(baseResolved, rel);
-  var sepChar = pathMod.sep;
-  if (joined !== baseResolved && joined.slice(0, baseResolved.length + 1) !== baseResolved + sepChar) {
+  var joined = confineToBase(base, rel, { platform: platform });
+  if (joined === null) {
     _refuse("safe-path/escapes-base",
-      "b.safePath.resolve: rel resolves outside base ('" + joined + "' not inside '" + baseResolved + "')");
+      "b.safePath.resolve: rel resolves outside base ('" +
+      pathMod.resolve(baseResolved, rel) + "' not inside '" + baseResolved + "')");
   }
   if (opts.realpath === true) {
     // realpath resolves symlinks on the RUNTIME filesystem, so it must use the
@@ -266,5 +313,6 @@ module.exports = {
   resolve:        resolve,
   resolveOrNull:  resolveOrNull,
   validate:       validate,
+  confineToBase:  confineToBase,
   SafePathError:  SafePathError,
 };

package/lib/static.js

@@ -50,6 +50,7 @@ var gateContract = require("./gate-contract");
 var lazyRequire = require("./lazy-require");
 var numericBounds = require("./numeric-bounds");
 var requestHelpers = require("./request-helpers");
+var safePath = require("./safe-path");
 var validateOpts = require("./validate-opts");
 var { StaticServeError } = require("./framework-error");
 
@@ -205,11 +206,10 @@ function _assertInsideRoot(root, candidate) {
       rel.indexOf(".." + nodePath.sep) !== -1 ||
       rel.indexOf(".." + (nodePath.sep === "/" ? "\\" : "/")) !== -1 ||
       nodePath.isAbsolute(rel)) return null;
-  var safe = nodePath.join(rootResolved, rel);
-  // Defense-in-depth lexical containment alongside the join sanitizer.
-  if (safe !== rootResolved &&
-      !safe.startsWith(rootResolved + nodePath.sep)) return null;
-  return safe;
+  // Final lexical containment via the shared traversal-containment primitive
+  // (cross-platform-aware resolve + strict base-prefix check). rel is already
+  // `..`-stripped and relative above, so this confines to root or returns null.
+  return safePath.confineToBase(rootResolved, rel);
 }
 
 // Module-level metadata cache. Entries hold:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.17.15",
+  "version": "0.17.16",
   "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:de6a5295-f203-43a2-9beb-1d4c36015b11",
+  "serialNumber": "urn:uuid:361e1563-6d41-499d-b266-962cb2dc64ef",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-24T02:18:59.855Z",
+    "timestamp": "2026-07-24T03:55:41.218Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.17.15",
+      "bom-ref": "@blamejs/core@0.17.16",
       "type": "application",
       "name": "blamejs",
-      "version": "0.17.15",
+      "version": "0.17.16",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.17.15",
+      "purl": "pkg:npm/%40blamejs/core@0.17.16",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.17.15",
+      "ref": "@blamejs/core@0.17.16",
       "dependsOn": []
     }
   ]