@blamejs/core 0.8.67 → 0.8.69

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.8.x
 
+- v0.8.69 (2026-05-10) — test-side `waitUntil` helper + CLAUDE.md §11b convention. Every recurring "test passes alone, fails under SMOKE_PARALLEL=64 / macOS GitHub-Actions runner" flake we've fought across v0.8.55 (rate-limit-cluster), v0.8.60 (watcher), v0.8.63 / v0.8.65 / v0.8.68 (log-stream-otlp / sandbox) was the same root cause: a fixed-budget `setTimeout(r, N)` sleep too short for runner-contention reality. New `test/helpers/wait.js` ships `waitUntil(predicate, opts?)` (polls every `intervalMs` default 25ms up to `timeoutMs` default 5000ms, exits early when predicate truthy, throws labeled error on timeout) + `waitUntilEqual(getter, expected)` convenience wrapper. `test/helpers/index.js` re-exports both. Refactored `test/layer-0-primitives/log-stream-otlp.test.js`'s "collector saw retries" gate (the most-recently-flaked one) to use `waitUntil({ failCount >= 2, dropEvents.length === 1 })` instead of `_sleep(200)` — fast platforms exit in ~30ms, contended platforms get the full budget. CLAUDE.md §11b documents the convention: when you find yourself bumping a hand-tuned sleep to fix a CI flake, that's the smell — convert to `waitUntil`. Future flake fixes update one timeout ceiling instead of N inline budgets.
+- v0.8.68 (2026-05-10) — `b.watcher` polling backend for environments where `fs.watch` doesn't deliver events. Pre-v0.8.68 the watcher used `fs.watch(root, { recursive: true })` exclusively — works on real Linux/macOS/Windows kernels but silent on filesystems where the kernel→userspace event bridge doesn't exist: Docker Desktop bind-mounts on Windows / macOS hosts (gRPC-FUSE / VirtioFS doesn't propagate inotify events from the Linux container's mount through to the host fs the operator runs node on), NFS / SMB mounts, some FUSE filesystems. Add `mode: "fs" | "poll"` (default `"fs"`) — when `mode: "poll"`, the watcher walks the tree on a fixed interval and diffs against the previous snapshot. New file / mtime-change / size-change → `onChange` via the existing debounce + ignore + lstat dispatch; missing path → `onDelete`. `pollIntervalMs` (default 1s) sets cadence; `pollMaxFiles` (default 50000) caps the per-tick walk so a misconfigured root can't stall the event loop stat'ing 100k files every second — overflow refuses with `watcher/poll-overflow`. Symlinks skipped (matches fs.watch path). The initial walk happens synchronously in `create()` so the first event fires only on real post-start changes (not on pre-existing files). `_flushForTest()` runs one synchronous tick + drains pending debounces so polling tests don't have to sleep `pollIntervalMs`. Returned handle gains `.mode` for operator introspection. fs.watch-backend error messages now suggest `mode: "poll"` as the fallback. New Layer 0 polling tests cover create / modify / delete detection across nested directories + mode validation + pollMaxFiles overflow.
 - v0.8.67 (2026-05-10) — SAML XMLDSig Reference Transforms (`enveloped-signature` + per-Reference c14n) + full IdP-emitted SAML round-trip in the federation-auth integration test. Pre-v0.8.67 `b.auth.saml.sp.verifyResponse` only honored the SignedInfo's `CanonicalizationMethod`; it didn't process the `<ds:Transforms>` block on the Reference. Real-world IdP-signed responses (Keycloak, ADFS, Okta) attach `http://www.w3.org/2000/09/xmldsig#enveloped-signature` (strip the `<Signature>` child of the referenced element before c14n) and a per-Reference `xml-exc-c14n#` Transform — without them, the digest computed over the assertion-including-signature never matches the signed-then-signature-injected reality and verifyResponse rejected legitimate IdP responses. `_verifyXmldsig` now reads the Transforms list, applies enveloped-signature by filtering the parsed-tree's `<Signature>` element children before canonicalization, and honors the per-Reference c14n choice (with vs without comments). The single-match-by-ID invariant + signature-wrapping defense moves into the saml.js path directly so the modified subtree (signature stripped) is the one that gets canonicalized + digested. `test/integration/federation-auth.test.js` now drives Keycloak's HTML login form via cookie-jar curl-equivalent (no headless browser needed), captures the IdP-signed SAMLResponse, fetches the IdP signing certificate from `/protocol/saml/descriptor`, hands the response to `sp.verifyResponse(b64, { expectedInResponseTo })`, and asserts the extracted `nameId` / `issuer` / `audience` / `inResponseTo` match the realm's signed claims. Verified end-to-end: Keycloak alice user → SAML AuthnRequest → login form POST → signed Response → `sp.verifyResponse()` → `{ nameId: "alice", issuer: <realm>, audience: <SP entityID>, attributes: { Role: "default-roles-..." } }`. Unsupported Transform algorithms refuse loudly via `auth-saml/unsupported-transform`. No primitive surface change versus v0.8.66 (the Transforms processing is internal to `_verifyXmldsig`).
 - v0.8.66 (2026-05-10) — `b.session.updateData(token, data, opts?)`. Update the sealed `data` payload on a session WITHOUT rotating the sid. Pre-v0.8.66 the only path to mutate session data was `b.session.rotate(token, { data })` which forces an sid rotation — appropriate for security-boundary transitions (login, MFA, role escalation) but heavyweight for cart-state writes / preference flips / step-up-completion flags. Default semantics: full payload replace, `lastActivity` bumped (idle-timeout reset), reserved `__bj_fingerprint` binding preserved automatically so verify() still surfaces drift correctly. `opts.merge: true` does a one-level deep merge into the existing payload; `opts.touchLastActivity: false` skips the idle-timeout bump. Returns `false` for unknown / expired / pre-v0.8.61-raw-format tokens (no throw). Anonymous-session userIds work the same as named userIds. Leader-only. New Layer 0 tests: 13 checks covering replace / merge / null-clear / fingerprint preservation / unknown-token returns / array refusal.
 - v0.8.65 (2026-05-10) — federated-authentication integration test fixture (Keycloak as OIDC OP + SAML IdP). Adds `quay.io/keycloak/keycloak:26.0` to `docker-compose.test.yml` running with realm-import on port `:18080` (HTTP) + `:18081` (Quarkus health). Realm `blamejs-test` boots with one OIDC client (`blamejs-rp-oidc`, secret `blamejs-test-rp-secret`, frontchannel + backchannel logout enabled), one SAML SP client (entityID `https://sp.blamejs-test.example`, RSA-SHA256 assertion signature), and a test user (`alice` / `blamejs-test-password`). New `test/integration/federation-auth.test.js` exercises end-to-end against the live Keycloak: OIDC discovery, `b.auth.oauth.authorizationUrl` (state + nonce + PKCE), password-grant token retrieval, `verifyIdToken` against the realm JWKS, `fetchUserInfo` with `idTokenSub` cross-check, RP-Initiated Logout URL build, `parseFrontchannelLogoutRequest` iss-mismatch refusal, `verifyBackchannelLogoutToken` JWKS-lookup + signature + typ-check failure paths, SAML `buildAuthnRequest` POST to the IdP's `/protocol/saml` endpoint, SP `metadata()` XML emit, and CIBA `startAuthentication` wire-format check (Keycloak's `backchannel_authentication_endpoint` is at `/protocol/openid-connect/ext/ciba/auth`). `b.auth.ciba._postForm` now sets `responseMode: "always-resolve"` so deterministic OAuth-shape error JSON (`{ error, error_description }`) reaches the AuthError-mapping path instead of being rejected as a generic HTTP error. `b.auth.ciba._postForm` URL validation switched from a non-existent `safeUrl.assertHttpUrl` to `safeUrl.parse({ allowedProtocols })`. `scripts/check-services.js` registers `keycloak` + `keycloak-health` (both v4 + v6); `test/helpers/services.js` exposes `URLS.keycloak`. CLAUDE.md release-workflow §6 documents the federation-auth integration test path. OID4VCI / OID4VP / OpenID Federation deferred — Keycloak's `oid4vc-issuer` SPI is preview-only and there's no entity-statement publisher in the base image.

package/lib/watcher.js

@@ -55,6 +55,17 @@ var audit = lazyRequire(function () { return require("./audit"); });
 var observability = lazyRequire(function () { return require("./observability"); });
 
 var DEFAULT_DEBOUNCE_MS = 100;
+// Polling-mode defaults. The polling backend exists for environments
+// where fs.watch's native events don't reach userspace — most commonly
+// Docker Desktop bind-mounts on Windows / macOS hosts (where the
+// inotify events from the Linux container's mount don't propagate
+// through the gRPC-FUSE / VirtioFS bridge to the host fs), or NFS /
+// SMB mounts that don't fire change notifications. Operators opt in
+// explicitly via `mode: "poll"`. Default cadence is 1s per tick;
+// pollMaxFiles caps the per-tick walk so a misconfigured root can't
+// stall the event loop by stat'ing 100k files every second.
+var DEFAULT_POLL_INTERVAL_MS = 1000;                                                              // allow:raw-byte-literal — 1-second poll cadence
+var DEFAULT_POLL_MAX_FILES   = 50000;                                                             // allow:raw-byte-literal — per-tick stat cap
 // Per-watcher event count cap before we self-terminate as a safety net
 // against runaway directories that emit millions of events per minute.
 // Operators with legitimate high-churn directories raise this via opts.
@@ -167,10 +178,23 @@ function _compileIgnore(patterns) {
   };
 }
 
+var ALLOWED_MODES = ["fs", "poll"];
+
 function _validateOpts(opts) {
   validateOpts.requireObject(opts, "watcher.create", WatcherError, "watcher/bad-opts");
   validateOpts.requireNonEmptyString(opts.root, "root", WatcherError, "watcher/bad-root");
   validateOpts.optionalFiniteNonNegative(opts.debounceMs, "debounceMs", WatcherError, "watcher/bad-debounce-ms");
+  if (opts.mode !== undefined && ALLOWED_MODES.indexOf(opts.mode) === -1) {
+    throw new WatcherError("watcher/bad-mode",
+      "watcher.create: mode must be one of " + ALLOWED_MODES.join(", ") +
+      ", got " + JSON.stringify(opts.mode));
+  }
+  validateOpts.optionalPositiveFinite(opts.pollIntervalMs, "pollIntervalMs", WatcherError, "watcher/bad-poll-interval-ms");
+  if (opts.pollMaxFiles !== undefined &&
+      (typeof opts.pollMaxFiles !== "number" || !isFinite(opts.pollMaxFiles) || opts.pollMaxFiles < 1)) {
+    throw new WatcherError("watcher/bad-poll-max-files",
+      "watcher.create: pollMaxFiles must be a positive finite integer");
+  }
   if (opts.maxPending !== undefined &&
       (typeof opts.maxPending !== "number" || !isFinite(opts.maxPending) || opts.maxPending < 1)) {
     throw new WatcherError("watcher/bad-max-pending",
@@ -191,6 +215,9 @@ function create(opts) {
   var root        = path.resolve(opts.root);
   var debounceMs  = (opts.debounceMs !== undefined) ? opts.debounceMs : DEFAULT_DEBOUNCE_MS;
   var maxPending  = (opts.maxPending !== undefined) ? opts.maxPending : DEFAULT_MAX_PENDING;
+  var mode        = opts.mode || "fs";
+  var pollIntervalMs = opts.pollIntervalMs || DEFAULT_POLL_INTERVAL_MS;
+  var pollMaxFiles   = opts.pollMaxFiles   || DEFAULT_POLL_MAX_FILES;
   var onChange    = opts.onChange || function () {};
   var onDelete    = opts.onDelete || function () {};
   var onError     = opts.onError  || function () {};
@@ -292,41 +319,126 @@ function create(opts) {
     pending.set(relPath, entry);
   }
 
-  // ---- start the underlying watch ----
-  try {
-    watcherHandle = fs.watch(root, { recursive: true, persistent: true }, function (eventType, filename) {
-      if (stopped) return;
-      // filename can be null on some platforms when the buffer
-      // overflows. Drop — there is nothing actionable.
-      if (!filename) return;
-      // node returns OS-native paths; normalize to root-relative.
-      var rel = filename;
-      // fs.watch passes a relative path already, but on macOS it can
-      // be an absolute path under /private/var/... when the root is a
-      // tmpdir symlink. Strip the root prefix defensively.
-      if (path.isAbsolute(rel) && rel.indexOf(root) === 0) {
-        rel = path.relative(root, rel);
+  // ---- start the underlying backend ----
+  // pollSnapshot lives at function scope so stop() and _flushForTest()
+  // can reach the polling tick state.
+  var pollTimer    = null;
+  var pollSnapshot = null;            // Map<relPath, { type, size, mtimeMs }>
+
+  // Walk the tree honoring `ignore` patterns + the pollMaxFiles cap.
+  // Returns the new snapshot Map, OR throws watcher/poll-overflow when
+  // the cap is hit (that's an operator-misconfigured root signal — a
+  // 100k-file tree under a 1s polling cadence stalls the event loop).
+  function _walkPollTree() {
+    var snapshot = new Map();
+    var fileCount = 0;
+    var stack = [""];
+    while (stack.length > 0) {
+      var relDir = stack.pop();
+      var absDir = relDir === "" ? root : path.join(root, relDir);
+      var entries;
+      try { entries = fs.readdirSync(absDir, { withFileTypes: true }); }
+      catch (_e) {
+        // Root vanished mid-walk OR an inner dir got deleted between
+        // the parent listing and the descent. Skip — the next tick's
+        // walk surfaces the deletion via the snapshot diff.
+        continue;
+      }
+      for (var i = 0; i < entries.length; i += 1) {
+        var entry = entries[i];
+        var relPath = relDir === "" ? entry.name : (relDir + "/" + entry.name);
+        // Normalize to forward-slash so glob ignore-matching is
+        // consistent with the fs.watch path the operator's hooks see.
+        relPath = relPath.split(path.sep).join("/");
+        if (isIgnored(relPath)) continue;
+        if (entry.isSymbolicLink()) continue;            // never follow symlinks
+        fileCount += 1;
+        if (fileCount > pollMaxFiles) {
+          throw new WatcherError("watcher/poll-overflow",
+            "watcher.poll: tree exceeds pollMaxFiles=" + pollMaxFiles +
+            " — narrow `ignore` patterns OR raise pollMaxFiles, OR switch to mode: \"fs\"");
+        }
+        var absPath = path.join(absDir, entry.name);
+        var st;
+        try { st = fs.statSync(absPath); }
+        catch (_e) { continue; }                          // race — entry vanished
+        if (entry.isDirectory()) {
+          snapshot.set(relPath, { type: "dir", size: 0, mtimeMs: st.mtimeMs });
+          stack.push(relPath);
+        } else if (entry.isFile()) {
+          snapshot.set(relPath, { type: "file", size: st.size, mtimeMs: st.mtimeMs });
+        }
+        // Other kinds (sockets, FIFOs, devices) — skip.
+      }
+    }
+    return snapshot;
+  }
+
+  function _pollTick() {
+    if (stopped) return;
+    var next;
+    try { next = _walkPollTree(); }
+    catch (e) { _safeError(e); return; }
+    if (pollSnapshot === null) {
+      // First tick — establish the baseline without firing events.
+      // Operators get add events on file CREATION after start, not on
+      // pre-existing files (matches fs.watch semantics).
+      pollSnapshot = next;
+      return;
+    }
+    // Diff: anything in `next` not in `pollSnapshot`, OR with size /
+    // mtimeMs different, fires onChange via the same _enqueue path the
+    // fs.watch backend uses (so debounce + ignore + lstat dispatch
+    // stay uniform). Anything in `pollSnapshot` missing from `next`
+    // fires onDelete (via _normalizeAndDispatch's ENOENT branch).
+    next.forEach(function (info, relPath) {
+      var prev = pollSnapshot.get(relPath);
+      if (!prev) { _enqueue(relPath); return; }
+      if (prev.size !== info.size || prev.mtimeMs !== info.mtimeMs || prev.type !== info.type) {
+        _enqueue(relPath);
       }
-      // Both inotify and ReadDirectoryChangesW occasionally fire with
-      // an empty filename for the root directory itself — ignore.
-      if (rel === "" || rel === ".") return;
-      _enqueue(rel);
     });
-    watcherHandle.on("error", function (err) { _safeError(err); });
-  } catch (e) {
-    // Older kernels without recursive inotify return ERR_FEATURE_UNAVAILABLE.
-    // Surface as an operator-actionable error rather than a silent
-    // single-directory degradation.
-    if (e && (e.code === "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM" || e.code === "ENOSYS")) {
-      throw new WatcherError("watcher/recursive-unsupported",
-        "watcher.create: recursive watch not supported on this platform/kernel: " +
-        ((e && e.message) || String(e)));
+    pollSnapshot.forEach(function (_info, relPath) {
+      if (!next.has(relPath)) _enqueue(relPath);
+    });
+    pollSnapshot = next;
+  }
+
+  if (mode === "poll") {
+    // Establish the initial snapshot synchronously so the first
+    // operator-side onChange fires only on real post-start changes.
+    try { pollSnapshot = _walkPollTree(); }
+    catch (e) {
+      throw new WatcherError("watcher/start-failed",
+        "watcher.create: initial poll walk failed: " + ((e && e.message) || String(e)));
+    }
+    pollTimer = setInterval(_pollTick, pollIntervalMs);                                            // allow:setinterval-unref — .unref() called immediately below; timer doesn't pin the event loop
+    if (typeof pollTimer.unref === "function") pollTimer.unref();
+  } else {
+    try {
+      watcherHandle = fs.watch(root, { recursive: true, persistent: true }, function (eventType, filename) {
+        if (stopped) return;
+        if (!filename) return;
+        var rel = filename;
+        if (path.isAbsolute(rel) && rel.indexOf(root) === 0) {
+          rel = path.relative(root, rel);
+        }
+        if (rel === "" || rel === ".") return;
+        _enqueue(rel);
+      });
+      watcherHandle.on("error", function (err) { _safeError(err); });
+    } catch (e) {
+      if (e && (e.code === "ERR_FEATURE_UNAVAILABLE_ON_PLATFORM" || e.code === "ENOSYS")) {
+        throw new WatcherError("watcher/recursive-unsupported",
+          "watcher.create: recursive watch not supported on this platform/kernel: " +
+          ((e && e.message) || String(e)) + " — pass mode: \"poll\" to fall back to interval polling");
+      }
+      throw new WatcherError("watcher/start-failed",
+        "watcher.create: fs.watch failed: " + ((e && e.message) || String(e)));
     }
-    throw new WatcherError("watcher/start-failed",
-      "watcher.create: fs.watch failed: " + ((e && e.message) || String(e)));
   }
 
-  _safeEmitAudit("watcher.started", { root: root });
+  _safeEmitAudit("watcher.started", { root: root, mode: mode });
 
   function stop() {
     if (stopped) return;
@@ -340,13 +452,23 @@ function create(opts) {
       try { watcherHandle.close(); } catch (_e) { /* best-effort */ }
       watcherHandle = null;
     }
-    _safeEmitAudit("watcher.stopped", { root: root, eventCount: eventCount });
+    if (pollTimer) {
+      try { clearInterval(pollTimer); } catch (_e) { /* best-effort */ }
+      pollTimer = null;
+    }
+    _safeEmitAudit("watcher.stopped", { root: root, mode: mode, eventCount: eventCount });
   }
 
   // Test seam — flushes all pending debounce timers immediately so
   // tests don't have to await debounceMs. Not part of the operator
-  // contract.
+  // contract. In poll mode, also synchronously runs one tick so a
+  // test can write a file, call _flushForTest(), and observe the
+  // resulting onChange without sleeping for pollIntervalMs.
   function _flushForTest() {
+    if (mode === "poll" && !stopped) {
+      try { _pollTick(); }
+      catch (_e) { /* tests assert via the operator's onChange callback */ }
+    }
     var snapshot = Array.from(pending.entries());
     pending.clear();
     for (var i = 0; i < snapshot.length; i += 1) {
@@ -358,6 +480,7 @@ function create(opts) {
   return {
     stop:           stop,
     root:           root,
+    mode:           mode,
     _flushForTest:  _flushForTest,
   };
 }

package/package.json

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

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:7b747b8f-4f21-448f-a73e-50b8615f6937",
+  "serialNumber": "urn:uuid:cf3aa594-6a94-4be5-9952-a87c315ec5eb",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-10T14:43:14.112Z",
+    "timestamp": "2026-05-10T15:19:22.438Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.8.67",
+      "bom-ref": "@blamejs/core@0.8.69",
       "type": "library",
       "name": "blamejs",
-      "version": "0.8.67",
+      "version": "0.8.69",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.8.67",
+      "purl": "pkg:npm/%40blamejs/core@0.8.69",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.8.67",
+      "ref": "@blamejs/core@0.8.69",
       "dependsOn": []
     }
   ]