@blamejs/core 0.13.12 → 0.13.13

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.13.x
 
+- v0.13.13 (2026-05-27) — **Archive extraction-path verification now refuses Windows reserved names, NTFS data streams, and trailing-dot/space per segment.** b.guardFilename.verifyExtractionPath (the per-entry gate b.archive.read.zip.extract / b.safeArchive run on every extracted file) checked traversal, absolute paths, drive-letter and UNC prefixes, null bytes, PATH_MAX overflow, and realpath containment — but not the per-segment Windows write-target hazards the disk validate / sanitize paths already reject. An archive entry named CON, NUL.txt, subdir/LPT1, file.txt:hidden, or secret.txt. stayed inside the extraction root, so the containment and realpath checks passed it, yet on Windows it would resolve to a device, write a hidden NTFS stream, or (after Windows strips the trailing dot/space) overwrite a sibling file. These are now refused: any path segment that collides with a Windows reserved device name, uses NTFS alternate-data-stream syntax (name:stream), or carries a trailing dot or leading/trailing whitespace. The checks are platform-unconditional — a verifier running on Linux still refuses names that are only dangerous on the Windows host that ultimately extracts the archive — with a per-check opt-out (reservedNamePolicy / adsPolicy / leadingTrailingPolicy: "allow") for Linux-only targets. **Security:** *`verifyExtractionPath` refuses per-segment Windows extraction hazards (reserved names / NTFS ADS / trailing dot-space)* — Closes a within-root write-target-redirection gap: an extracted entry could stay inside the destination yet, on Windows, resolve to a device (`CON` / `NUL` / `COM1` / `LPT1`), write a hidden alternate data stream (`file.txt:payload`), or overwrite a sibling after Windows strips a trailing dot/space (`config.`). The verification gate now rejects all three per path segment. Refusal is platform-unconditional (the verifier may run on a different OS than the extractor); set `reservedNamePolicy` / `adsPolicy` / `leadingTrailingPolicy` to `"allow"` to opt a check out on a Linux-only target. Single-entry, name-only residuals — 8.3 short-name aliasing, case-insensitive cross-entry collisions, and archive symlink/hardlink entry-target validation — remain the extract orchestrator's responsibility (it owns the case-folded seen-set and the link-target gate).
+
 - v0.13.12 (2026-05-27) — **Inbound MX listener now runs the connection-level gate cascade it documented — HELO identity, DNS blocklist, and greylisting.** b.mail.server.mx.create documented helo / rbl / greylist gate options, but the listener never invoked them — an operator who wired them got silent acceptance of mail those gates would have rejected. They are now wired into the live SMTP state machine: the HELO-identity gate evaluates at HELO/EHLO and refuses a spoofed or malformed identity with 550; the DNS-blocklist gate evaluates the connecting IP once per connection and refuses a listed source with 554; the greylisting gate defers a first-seen (ip, sender, recipient) tuple with a 450 tempfail so legitimate senders retry and pass. Each gate is skipped when the operator doesn't wire it. Because these gates do DNS and store lookups, the per-connection command pump was reworked to process commands asynchronously and strictly in arrival order, so pipelined commands (RFC 2920) cannot overtake a gate still resolving and the existing SMTP-smuggling and STARTTLS-stripping defenses are unchanged. The message-authentication gate (SPF/DKIM/DMARC alignment via b.guardEnvelope) needs the inbound SPF + DKIM verification results as inputs; that inbound-auth pipeline lands as a follow-up, and the documentation no longer implies that gate is active today. **Added:** *HELO-identity / RBL / greylist gates wired into `b.mail.server.mx`* — When wired, `opts.helo` (FCrDNS / HELO-shape / self-name checks) refuses a bad HELO identity at HELO/EHLO with 550; `opts.rbl` refuses a connecting IP found on a DNS blocklist with 554 (evaluated once per connection); `opts.greylist` defers a first-seen (ip, sender, recipient) tuple with 450 4.7.1. Their verdicts surface on the `rcpt_to` event (`rblListed`, `greylist`) and the `helo` event (`heloVerdict`), with dedicated `helo_gate_refused` / `rbl_refused` / `greylist_deferred` audit events. A gate the operator doesn't supply is skipped, never synthesized. **Changed:** *MX command pump processes commands asynchronously and in arrival order* — Gate evaluation involves DNS and store lookups, so the per-connection command pump now awaits each command before the next. Pipelined commands are serialized so a gate resolving cannot let a later command answer ahead of an earlier one; reply ordering, the bare-LF SMTP-smuggling refusal, and the STARTTLS-stripping defense are unchanged. No change to the listener's external behaviour when no gates are wired. **Deprecated:** *SPF/DKIM/DMARC-alignment gate documentation corrected to match what is active* — The `envelope` (SPF/DKIM/DMARC alignment) and `dmarc` gate options were documented as wireable but require inbound SPF + DKIM verification results the listener does not yet produce. They are removed from the documented option set until the inbound-authentication pipeline (composing `b.mail.spf` + `b.mail.dmarc` + DKIM verification) lands; run those checks on the delivered message via the agent handoff in the meantime.
 
 - v0.13.11 (2026-05-27) — **Test-suite reliability: replaced fixed-delay waits in the rate-limiter and scheduler suites with condition polling.** No runtime behaviour changes. The rate-limiter, scheduler, and websocket-channel test suites waited for asynchronous work to settle by draining a fixed number of event-loop ticks before asserting. Under heavily parallel CI that budget was occasionally too short, so an assertion read state before the async work (a cluster-backend counter update, a scheduler tick-claim) had landed — an intermittent failure unrelated to the code under test. Those waits now poll the observable condition (helpers.waitUntil) and exit as soon as it holds, with a generous upper bound, so they pass quickly on fast machines and reliably under load. A build gate is added so the fixed-tick-drain shape cannot be reintroduced. **Fixed:** *Flaky fixed-budget waits in the rate-limiter / scheduler / sandbox test suites made contention-tolerant* — The rate-limit-cluster and scheduler-exactly-once suites drained a fixed count of event-loop ticks before asserting on asynchronously-updated state; under contended CI the budget could expire before the work settled, producing intermittent failures. They now wait on the actual observable condition (a written response, a settled counter). The sandbox suite's success-path cases gave the worker a 5 s execution budget that cold worker-thread startup under heavily parallel Windows CI could just exceed; those are raised to the framework's 10 s ceiling. Affects test code only — no change to shipped framework behaviour. The unused tick-drain helper in the websocket-channel suite was removed. **Detectors:** *Build gate rejects the fixed-tick-drain wait shape in tests* — A new test-suite lint rule flags the counted microtask/tick-drain idiom (reassigning a promise to its own `.then()` in a loop to wait a fixed number of ticks), the sibling of the existing fixed-`setTimeout`-sleep rule. A single event-loop yield is unaffected; only the drain-as-wait shape is rejected, directing the wait to condition polling instead.

package/lib/guard-filename.js

@@ -91,6 +91,20 @@ var WIN_RESERVED_NAMES = Object.freeze([
   "CLOCK$", "CONFIG$",
 ]);
 
+// Windows folds the superscript digits U+00B9 / U+00B2 / U+00B3 to
+// 1 / 2 / 3 when matching COM/LPT device names, so a superscript-digit
+// form resolves to the same device. Built from numeric codepoints so
+// the source stays pure-ASCII (guard-family rule).
+var _SUPERSCRIPT_DIGIT_MAP = (function () {
+  var m = {};
+  m[String.fromCharCode(0xB9)] = "1";
+  m[String.fromCharCode(0xB2)] = "2";
+  m[String.fromCharCode(0xB3)] = "3";
+  return m;
+})();
+var _SUPERSCRIPT_DIGIT_RE = new RegExp("[" + String.fromCharCode(0xB9, 0xB2, 0xB3) + "]", "g"); // allow:dynamic-regex — superscript-digit codepoints from a numeric table
+
+
 // Path-traversal indicators (anchored matches on raw and percent-decoded
 // forms).
 var PATH_TRAVERSAL_RE = /(^|[/\\])\.\.($|[/\\])/;
@@ -243,7 +257,16 @@ function _normalizeNFC(s) {
 function _isWinReserved(name) {
   // Reserved-name check applies to the base (without extension) AND to
   // the entire leaf — both `CON` and `CON.txt` collide with the device.
-  var upper = name.toUpperCase();
+  // Windows normalizes the superscript digits U+00B9 / U+00B2 / U+00B3
+  // to 1 / 2 / 3 when matching COM/LPT device names, so those superscript
+  // forms resolve to the same devices as COM1 / LPT3; fold them to ASCII
+  // before comparison so the spoofed forms are caught too. (Source stays
+  // pure-ASCII per the guard-family rule — the codepoints are escaped.)
+  // Fold COM/LPT superscript-digit spoofs to ASCII before matching
+  // (Windows treats them as the device). See _SUPERSCRIPT_DIGIT_* below.
+  var upper = name.toUpperCase().replace(_SUPERSCRIPT_DIGIT_RE, function (ch) {
+    return _SUPERSCRIPT_DIGIT_MAP[ch] || ch;
+  });
   for (var i = 0; i < WIN_RESERVED_NAMES.length; i += 1) {
     var r = WIN_RESERVED_NAMES[i];
     if (upper === r) return true;
@@ -952,6 +975,29 @@ var PATH_MAX_BYTES = 4096;
  * resolved absolute path on success; throws `GuardFilenameError` on
  * any refusal.
  *
+ * Per-segment Windows-extraction hazards are refused too — these are
+ * within-root write-target redirections / collisions that the
+ * containment + realpath checks structurally cannot see, so they need
+ * a name-level check the disk `validate` / `sanitize` paths already
+ * carry: a Windows reserved device name (`CON` / `NUL` / `COM1` / …,
+ * which resolves to the device), NTFS alternate-data-stream syntax
+ * (`name:stream`, which writes a hidden stream of the base file), and a
+ * trailing dot / leading-or-trailing whitespace (`secret.txt.`, which
+ * Windows strips so the entry overwrites an existing sibling). The
+ * checks are platform-unconditional — the verifier may run on Linux
+ * while extraction happens on Windows — and each has an opt-out for
+ * Linux-only targets (`reservedNamePolicy` / `adsPolicy` /
+ * `leadingTrailingPolicy: "allow"`), mirroring `validate`.
+ *
+ * Out of this primitive's scope (single-entry, name-only): 8.3 short-name
+ * aliasing (`PROGRA~1`), case-insensitive cross-entry collision
+ * (`Readme.txt` vs `README.TXT` on a case-preserving FS), and archive
+ * symlink/hardlink ENTRY-target validation. The first two are cross-entry
+ * properties and the third needs the entry's declared link target, which
+ * this function never sees — they belong to the extract orchestrator
+ * (`b.archive.read.zip.extract` / `b.safeArchive`), which owns the
+ * case-folded seen-set and the link-target gate.
+ *
  * Companion to `b.guardArchive.checkExtractionPath` (the string-only
  * portable gate the guard-archive primitive keeps fs-free for use as
  * a posture cascade member). `verifyExtractionPath` deliberately
@@ -964,8 +1010,13 @@ var PATH_MAX_BYTES = 4096;
  * Operators rolling their own extract loop call it per entry.
  *
  * @opts
- *   followSymlinks:  boolean,       // default false — symlink in the
+ *   followSymlinks:       boolean,  // default false — symlink in the
  *                                   //   resolved path refuses unless set
+ *   reservedNamePolicy:   string,   // "allow" opts out of the Windows
+ *                                   //   reserved-device-name segment check
+ *   adsPolicy:            string,   // "allow" opts out of the NTFS-ADS check
+ *   leadingTrailingPolicy: string,  // "allow" opts out of the trailing-dot /
+ *                                   //   leading-or-trailing-whitespace check
  *
  * @example
  *   var resolved = b.guardFilename.verifyExtractionPath(
@@ -1023,19 +1074,53 @@ function verifyExtractionPath(entryName, extractionRoot, opts) {
     throw new GuardFilenameError("filename.extraction-unc",
       "verifyExtractionPath: entryName starts with a UNC prefix");
   }
-  // `..` segment refuses — walk path components.
+  // `..` segment refuses — walk path components. The same walk also
+  // refuses per-segment Windows-extraction hazards the disk `validate`
+  // / `sanitize` paths already catch but that string-containment +
+  // realpath agreement cannot see, because they're WITHIN-root
+  // collisions / write-target redirections rather than boundary
+  // escapes. These checks are platform-UNCONDITIONAL: the verifier may
+  // run on Linux while the archive is extracted on Windows, so a name
+  // that's only dangerous on Windows must still be refused here.
+  // Operators on a Linux-only target opt out per check, mirroring
+  // `validate`'s policy vocabulary.
   var segs = normalized.split("/");
   for (var si = 0; si < segs.length; si += 1) {
-    if (segs[si] === ".." || segs[si] === "..\\" || segs[si] === "..%2f" || segs[si] === "..%5c") {
+    var seg = segs[si];
+    if (seg === ".." || seg === "..\\" || seg === "..%2f" || seg === "..%5c") {
       throw new GuardFilenameError("filename.extraction-traversal",
         "verifyExtractionPath: entryName contains .. segment");
     }
     // URL-encoded variants — explicit refusal so operators don't
     // need to percent-decode before passing the entry name in.
-    if (/%2e%2e/i.test(segs[si]) || /%c0%ae/i.test(segs[si])) {
+    if (/%2e%2e/i.test(seg) || /%c0%ae/i.test(seg)) {
       throw new GuardFilenameError("filename.extraction-traversal-encoded",
         "verifyExtractionPath: entryName contains encoded .. segment");
     }
+    if (seg === "" || seg === ".") continue;   // separators / current-dir — nothing to name-check
+    // Windows reserved device name (CON / NUL / COM1 / LPT1 / …): on
+    // Windows the segment resolves to the device, redirecting the write.
+    if (opts.reservedNamePolicy !== "allow" && _isWinReserved(seg)) {
+      throw new GuardFilenameError("filename.extraction-reserved-name",
+        "verifyExtractionPath: entryName segment " + JSON.stringify(seg) +
+        " collides with a Windows reserved device name");
+    }
+    // NTFS alternate data stream (name:stream): on Windows the write
+    // lands on a hidden stream of the base file, not a normal file.
+    if (opts.adsPolicy !== "allow" && /:[^:\\/]+$/.test(seg)) {
+      throw new GuardFilenameError("filename.extraction-ntfs-ads",
+        "verifyExtractionPath: entryName segment " + JSON.stringify(seg) +
+        " uses NTFS alternate-data-stream syntax (name:stream)");
+    }
+    // Trailing dot / leading-or-trailing whitespace: Windows silently
+    // strips these, so `secret.txt.` or `secret.txt ` collides with an
+    // existing sibling — an in-root overwrite the containment check
+    // cannot see.
+    if (opts.leadingTrailingPolicy !== "allow" && /^\s|\s$|\.$/.test(seg)) {
+      throw new GuardFilenameError("filename.extraction-leading-trailing",
+        "verifyExtractionPath: entryName segment " + JSON.stringify(seg) +
+        " has leading/trailing whitespace or a trailing dot (Windows strips it)");
+    }
   }
   // Resolve the destination path against the root via path.resolve
   // (string-level computation; no fs hits).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.13.12",
+  "version": "0.13.13",
   "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:cfe1e116-abd7-4631-96e5-8a2a865e2a16",
+  "serialNumber": "urn:uuid:b3c8f3dc-4ada-41d3-9b05-66ce6774c125",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-27T11:02:44.192Z",
+    "timestamp": "2026-05-27T12:37:28.862Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.13.12",
+      "bom-ref": "@blamejs/core@0.13.13",
       "type": "application",
       "name": "blamejs",
-      "version": "0.13.12",
+      "version": "0.13.13",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.13.12",
+      "purl": "pkg:npm/%40blamejs/core@0.13.13",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.13.12",
+      "ref": "@blamejs/core@0.13.13",
       "dependsOn": []
     }
   ]