@blamejs/core 0.9.22 → 0.9.24

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.9.x
 
+- v0.9.24 (2026-05-14) — **`b.agent.stream` — async-iterable variants for agent methods that yield N rows.** Fourth slice of the v0.9.21–v0.9.30 substrate playbook (numbers shifted +1 by v0.9.23 CodeQL insertion). JMAP `Email/queryChanges` against million-message mailboxes returns an array today — OOM on client + agent before the response ships. RFC 8620 §5.5 allows `position`-paginated responses; real mailboxes need cursor-backed delivery with built-in backpressure. (1) **`b.agent.stream.create({ openCursor, cursorOpts, batchSize, orchestrator, actor, kind, audit })`** — returns an object implementing `[Symbol.asyncIterator]` so operators write `for await (var row of stream) { ... }`. Operator supplies an `openCursor(cursorOpts)` factory returning a cursor with `fetchBatch(batchSize) → { rows, nextCursor, done }` + optional `close()` + optional `lastSeenCursor()`. (2) **Backpressure built-in** — async-generator semantics; each `next()` call yields one row from an in-memory batch buffer; the cursor only refetches when the buffer drains. Pulling slowly applies backpressure to the store side; a slow client can't OOM the server. (3) **Auto cursor close on every exit path** — consumer `break` calls iterator `.return()`, consumer `throw` calls `.throw()`, natural exhaustion calls `.next()` until done — all three close the cursor via `try`/`finally`-style `_closeOnce` and emit `agent.stream.closed` audit with reason (`exhausted` / `consumer-break` / `consumer-throw` / `drain` / `error`). (4) **Drain marker** — when orchestrator drain fires mid-stream, the next `next()` call returns ONE final `{ _drainMarker: true, lastSeenCursor: <opaque>, reason: "drain" }` row + closes the cursor. Clients reconnecting via JMAP-WebSocket / IMAP NOTIFY pass `lastSeenCursor` back to resume from the same position against the new agent post-deploy. Composes v0.9.21 `orchestrator.registerStream` / `unregisterStream` / `isDraining` hooks. (5) **`b.guardStreamArgs`** — validates `b.agent.stream.create` opts. Refuses non-integer `batchSize` (silent shard-style routing drift class — same shape Codex caught on v0.9.21), batchSize out of `[1, 1024]` strict-profile range, empty `kind` string, function / regex / Buffer / `__proto__` keys inside `cursorOpts` (structured-clone-unsafe — same shape `b.guardMailQuery` refuses for filter specs). Ships `strict` / `balanced` / `permissive` profiles + hipaa / pci-dss / gdpr / soc2 postures. (6) Audit lifecycle: `agent.stream.opened` on iterator creation, `agent.stream.closed` on every exit path, `agent.stream.drain_marker_emitted` when orch drain fires. Fuzz harness ships in `fuzz/guard-stream-args.fuzz.js`. Per the substrate playbook in `memory/specs/blamejs-agent-stream-spec.md`.
+- v0.9.23 (2026-05-14) — **CodeQL alert sweep — 30 alerts closed across 6 rule classes + wiki @primitive validator extracted into static gates.** Standalone substrate slice inserted into the v0.9.21–v0.9.30 playbook; downstream substrate slices shift +1 (stream now v0.9.24, eventBus v0.9.25, tenant v0.9.26, saga v0.9.27, postureChain v0.9.28, trace v0.9.29, snapshot v0.9.30). The 30 alerts were regressions of v0.9.18's earlier batch fix — v0.9.15's framework-wide `require()`-binding rename sweep (184 renames across 108 files) shifted line numbers and the suppression comments stopped tracking. (1) **`js/file-system-race` (10 sites)** — `lib/atomic-file.js:_readSyncCore` migrated from `statSync`+`readFileSync` to the canonical TOCTOU-safe-read scaffold (open fd → `fstatSync` → `readSync` loop → `closeSync` in finally; ENOENT now surfaces from `openSync`); `lib/restore-rollback.js` marker write switched to `openSync(..., "wx", 0o600)` + `writeSync` + `fsyncSync` + EEXIST tolerance; `lib/network-tls.js` new `_readPathFile` fd-based reader; `lib/backup/bundle.js` fd-narrowed read with short-read detection; `lib/static.js` content-safety gate converted to `fsp.open` filehandle pattern; `lib/vault/seal-pem-file.js`, `lib/atomic-file.js:fsyncDir`, `test/30-chain.js`, `examples/wiki/test/validate-{env,cli}-snapshot.js`, `examples/wiki/lib/source-doc-parser.js` got suppression refresh OR fd-narrowed refactor per shape. (2) **`js/insecure-temporary-file` (6 sites)** — `lib/mtls-ca.js` new `_writeExclusive` helper using `openSync(..., "wx", mode)` + `writeSync` + `fsyncSync`; `lib/vault/rotate.js` + `lib/http-client.js` got suppression refresh pointing at the operator-supplied stagingDir / 64-bit CSPRNG suffix defenses. (3) **`js/path-injection` (2 sites in `lib/static.js`)** — suppression refresh pointing at the upstream `_resolveSafe` sandbox check at line 181 (lexical resolve + `startsWith(rootResolved + sep)` + realpath escape guard + guardFilename gate). (4) **`js/remote-property-injection` (7 sites)** — `lib/middleware/csrf-protect.js` cookie-parse output + `lib/websocket.js` `_parseExtensionHeader` params switched to `Object.create(null)` so attacker-controlled keys have no prototype chain to pollute; `lib/middleware/body-parser.js` multipart fields got suppression refresh pointing at the POISONED_KEYS gate at line 867; `test/40-consumers.js` + `test/00-primitives.js` test fixtures suppressed with `test/` scope justification. (5) **`PinnedDependenciesID` (2 workflow files)** — every `uses:` line was already SHA-pinned per v0.9.18; the remaining alerts pointed at the `npm install --no-audit --no-fund` step in `.github/workflows/npm-publish.yml` + `ci.yml`; added explicit `name@version` specifiers (esbuild + postject, mirroring `package.json`'s exact pins) so CodeQL recognizes the install as pinned without committing a lockfile (which CLAUDE.md hard rule §1 forbids — vendored stack, zero npm runtime deps). (6) **`js/regex/missing-regexp-anchor` (1 site)** — `scripts/build-vendored-sbom.js:42` host-extractor regex anchored to `^https?://github.com/` so an attacker-controlled `entry.source` containing `github.com` as a path or query substring can't misdirect purl dispatch into the github branch. (7) **Wiki @primitive validator extracted into static gates** — the `@related namespace-not-primitive` nit fired on PRs #50 (v0.9.20), #51 (v0.9.21), AND #52 (v0.9.22) — same class, three rediscoveries because the validator only ran in CI's wiki-e2e gate (~90s round-trip), never in local pre-push. Extraction: `examples/wiki/lib/source-comment-block-validator.js` (shared engine, pure module, no side effects) + `scripts/validate-source-comment-blocks.js` (framework-level standalone wrapper, runs in 419–466ms, no `@blamejs/core` / vault / DB / network dependencies). Existing wiki-e2e gate refactored to delegate to the shared engine; CI invocation unchanged. CLAUDE.md release workflow step 4 (static gates) now lists `node scripts/validate-source-comment-blocks.js` after `codebase-patterns.test.js`. Each suppression comment references the active defense by file:line so future CodeQL re-runs OR future readers know which suppression applies. Multi-agent fan-out — 4 parallel subagents in isolated git worktrees per rule class.
 - v0.9.22 (2026-05-14) — **`b.agent.idempotency` — cross-dispatch idempotency keys honored at every agent consumer boundary; JMAP retry-safe semantics from day one.** Second slice of the v0.9.21–v0.9.29 substrate playbook. (1) **`b.agent.idempotency.create({ store, audit, ttlMs, maxResultBytes, fingerprintArgs })`** — pluggable backing store via `{ get, put, delete, gc }`; in-memory default ships for single-process deployments, operator wires durable backends (sqlite-backed adapter or external). Surface: `instance.get(method, actorId, key)` returns cached envelope `{ result, firstAt, lastReplayedAt, replayCount, requestFingerprint }` or `null`; `instance.put(method, actorId, key, result, { args, requestFingerprint })` serializes via `b.safeJson.stringify` + persists with TTL + refuses key-reuse-different-args via the request-fingerprint (sha3-512 of args sans key) check; `instance.invalidate(method, actorId, key)` is the saga-compensation escape hatch; `instance.gc({ olderThanMs })` for periodic cleanup. (2) **Keys hashed at the boundary** — operator-supplied keys never reach disk in raw form; namespace-hashed via `b.crypto.namespaceHash("agent.idempotency", method + "\\0" + actorId + "\\0" + key)`. Cross-actor + cross-method isolation by construction (an attacker can't replay another actor's mutation by guessing the key). (3) **Replay tracking** — every cache hit increments `replayCount` + bumps `lastReplayedAt`; audit emits `agent.idempotency.replay` with the truncated actor-id hash + first/replay timestamps so operator pipelines surface retry storms. (4) **`b.guardIdempotencyKey`** — operator-supplied key shape validator. Refuses oversized (default 256 bytes), control chars (C0/NUL/DEL — defends audit-log injection), slash + backslash (defends operators routing keys through filesystem paths), path-traversal (`..`), non-ASCII under strict (operator-greppable in audit logs across stack boundaries; permissive opts down for legacy Unicode tenant IDs). (5) **JSON round-trip test helper** — new `test/helpers/json-round-trip.js` exporting `assertJsonRoundTrip(shape, label)`. Catches the bug class Codex flagged on PR #51 (v0.9.21 `register()` stored agent function ref on backend row, lost in DB/JSON serialization). Refuses on function fields, Buffer fields, Date objects, Symbol keys, BigInt values, non-finite numbers, cycles. Applied retroactively to v0.9.21 agent-orchestrator backend row in regression test. (6) **Result size cap** (default 1 MiB per cached entry) — refuses with `agent-idempotency/result-too-big` so operators discover OOM-prone result shapes locally instead of at runtime. Fuzz harness ships in `fuzz/guard-idempotency-key.fuzz.js`; ClusterFuzzLite matrix entries added. Per the substrate playbook in `memory/specs/blamejs-agent-idempotency-spec.md`.
 - v0.9.21 (2026-05-14) — **`b.agent.orchestrator` — framework-level supervisor for every agent blamejs ships.** First slice of the v0.9.21–v0.9.29 substrate playbook that builds before mail-stack resumes. (1) **`b.agent.orchestrator.create(opts)`** — facade with `register(name, agent, opts)` / `lookup(name)` / `unregister(name)` / `list({ kind, tenantId })` registry, `spawnConsumers({ agent, queue, shards, taskTopic, maxConcurrency })` for sharded-topic dispatch (FNV-1a consistent-hash via `b.agent.orchestrator.shardFor(key, shards)`; per-shard topic suffix `<base>.<shard>`), `elect({ resource })` composing `b.cluster` DB-row leader election (returns `{ isLeader, fencingToken, leaderId }` — single-process deployments get a trivial-leader; cluster deployments delegate), `drain({ timeoutMs })` stopping every spawned consumer + audit-emitting elapsed/count, and `health()` aggregating per-agent + per-consumer + per-election state into one shape ready for `b.middleware.healthcheck`. (2) **Pluggable backend** — `{ get, set, delete, list }` interface; in-memory default ships for single-process deployments, operator wires `b.config.loadDbBacked`-shaped or external for restart-survival. (3) **`b.guardAgentRegistry`** — registry-op shape validator. Refuses non-ASCII agent names (NFC + ASCII-only — operator-greppable in audit logs), path-traversal shapes (`..` / `/` / `\` / NUL / C0 / DEL), oversized (default 64 bytes), reserved `FRAMEWORK.*` / `ROOT.*` prefix, duplicate-on-register, register without `agentKind`. Ships `strict` / `balanced` / `permissive` profiles and `hipaa` / `pci-dss` / `gdpr` / `soc2` postures (all pin `strict`). (4) **Drain phase auto-wires into `b.appShutdown`** when operator supplies an `appShutdown` instance; `SIGTERM` delivers a clean drain of all spawned consumers + stream-registry signal before the process exits. (5) **Stream-registry hook** (`registerStream` / `unregisterStream` / `isDraining`) — substrate for v0.9.23 `b.agent.stream` so async-iterable method variants can check the drain flag and emit drain-markers. Substrate is NOT a process supervisor — process spawn / restart-on-crash / pod scheduling delegate to pm2 / systemd / k8s / Nomad; framework doesn't compete. Fuzz harness ships in `fuzz/guard-agent-registry.fuzz.js`. Per the substrate playbook in `memory/specs/blamejs-agent-orchestrator-spec.md`; v0.9.22 idempotency wires on top next.
 - v0.9.20 (2026-05-14) — **`b.mail.agent` — the standardization contract for every mail protocol blamejs ships.** Every above-the-wire mail surface (JMAP at v0.9.27, IMAP at v0.9.28, POP3 at v0.9.29, ManageSieve at v0.9.30, the MX listener at v0.9.24, submission at v0.9.25) translates protocol calls into `agent.X(args)`; RBAC, posture enforcement, audit emission, dispatch, and worker isolation are owned at the agent. (1) **`b.mail.agent.create({ store, audit, permissions, posture, identity, dispatch })`** — facade with 23 methods. Read surface (`search` / `fetch` / `thread` / `folders` / `quota`) is backed by v0.9.19 `b.mailStore` and runs immediately. Move surface (`move` / `flag` / `delete`) is backed by the new `mailStore.moveMessages` substrate; soft-delete moves to Trash + tags `\Deleted` (hard expunge wires at v0.9.28 with retention-floor enforcement). Write surface (`compose` / `send` / `reply` / `forward`), Sieve (`sieve.list/put/activate`), identity (`identity.set` / `vacation.set`), MDN (`mdn.send/parse/allowList`), regulated export, and migration `import` throw `mail-agent/not-implemented` with a `wiredAt` tag naming the slice that lights them up (defer-with-condition per the v1-defensible-scope rule). (2) **Dispatch contract** — `dispatch.mode` is `"local"` / `"queue"` / `"auto"`. `local` runs every method in-process. `queue` publishes envelopes to `mail.agent.tasks` via `b.queue.enqueue`; an `agent.consumer({ agent, queue })` running in a dedicated process or replicas across hosts pulls and executes. Posture metadata travels with each envelope; the consumer re-validates against its own posture before unseal so no posture downgrade survives the queue boundary. `auto` routes fast-path ops (`fetch` / `folders` / `flag` / `quota`) locally and heavy ops (`search` / `export`) to queue/workerPool when configured. (3) **Worker isolation** — `dispatch.workerPool` (composes `b.workerPool`) is validated at create-time; the agent reserves `vaultKeyDelivery: "in-worker"` (default) vs `"main-only"` (posture-conditional — HIPAA/PCI/GDPR default to main-only when the worker-script path wires at v0.9.26 Sieve). (4) **`b.mail.agent.consumer`** — the queue-side facade for multi-host load-spreading; carries its own `store` and re-validates posture at the boundary. (5) **Five new guards** through `b.gateContract` — **`b.guardMailQuery`** (search/fetch filter shape: bounded depth/keys/array-length, function/regex/Buffer/cycle refusal, `__proto__` key refusal, projection-column allowlist via `FILTERABLE_COLUMNS`, posture-required actor fields HIPAA→`purposeOfUse` / PCI→`pciScope` / GDPR→`lawfulBasis`); **`b.guardMailCompose`** (draft envelope: identity-vs-From alignment, recipient deduplication, attachment-byte cap default 25 MiB, body shape — exactly one of text/html unless `allowMultipartAlternative`, C0 control-char refusal in headers); **`b.guardMailReply`** (References-chain cap default 100 defends infinite-loop forwards, In-Reply-To continuity per RFC 5322 §3.6.4 — last References must match In-Reply-To, quoted-original byte cap, forwarded-attachment cardinality cap); **`b.guardMailMove`** (system-folder allowlist for INBOX/Sent/Drafts/Trash/Junk/Archive, admin-scope or `allowedFolders` gate for arbitrary destinations, path-traversal refusal, slash refusal — IMAP `.` hierarchy separator only); **`b.guardMailSieve`** (pre-parser shape-only: script-byte cap default 64 KiB, line-count cap defends one-byte-line bombs, name shape — path-traversal / slash / backslash refusal, actor-ownership check — non-admin actors restricted to their `ownedNames`; full Sieve parse at v0.9.26 via `b.safeSieve`). Each guard ships `strict` / `balanced` / `permissive` profiles and `hipaa` / `pci-dss` / `gdpr` / `soc2` postures (all pin `strict`). (6) **`b.mailStore.moveMessages(fromFolder, toFolder, objectIds)`** — per IMAP4rev2 §6.6.2, both folders bump modseq on move; agent.move composes this. (7) Fuzz harnesses ship for every new guard and the v0.9.19 substrates (`safe-mime` / `guard-message-id`) are now wired into the ClusterFuzzLite matrix.

package/index.js

@@ -167,8 +167,10 @@ var guardMailMove = require("./lib/guard-mail-move");
 var guardMailSieve = require("./lib/guard-mail-sieve");
 var guardAgentRegistry = require("./lib/guard-agent-registry");
 var guardIdempotencyKey = require("./lib/guard-idempotency-key");
+var guardStreamArgs = require("./lib/guard-stream-args");
 var agentOrchestrator = require("./lib/agent-orchestrator");
 var agentIdempotency = require("./lib/agent-idempotency");
+var agentStream = require("./lib/agent-stream");
 var guardArchive = require("./lib/guard-archive");
 var guardJson = require("./lib/guard-json");
 var guardYaml = require("./lib/guard-yaml");
@@ -414,7 +416,8 @@ module.exports = {
   guardMailSieve:   guardMailSieve,
   guardAgentRegistry: guardAgentRegistry,
   guardIdempotencyKey: guardIdempotencyKey,
-  agent:            { orchestrator: agentOrchestrator, idempotency: agentIdempotency },
+  guardStreamArgs:  guardStreamArgs,
+  agent:            { orchestrator: agentOrchestrator, idempotency: agentIdempotency, stream: agentStream },
   guardArchive:     guardArchive,
   guardJson:        guardJson,
   guardYaml:        guardYaml,

package/lib/agent-stream.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * @module     b.agent.stream
+ * @nav        Agent
+ * @title      Agent Stream
+ * @order      60
+ *
+ * @intro
+ *   Async-iterable variants for agent methods that yield N rows.
+ *   Operator wraps a cursor-shaped fetcher with `b.agent.stream.create`;
+ *   the resulting object is `AsyncIterable<row>` — built-in
+ *   backpressure (each `yield` blocks until the consumer pulls),
+ *   automatic cursor close via `try`/`finally` on any exit path
+ *   (consumer break, throw, network drop), and drain-marker emit on
+ *   orchestrator drain so clients can resume from `lastSeenCursor`
+ *   against the new agent post-drain.
+ *
+ *   ```js
+ *   var stream = b.agent.stream.create({
+ *     orchestrator: orch,                  // optional — for drain reg
+ *     actor:        { id: "u1" },
+ *     kind:         "search",
+ *     batchSize:    256,
+ *     openCursor:   function (cursorOpts) {
+ *       return store.openSearchCursor(cursorOpts);     // operator
+ *     },
+ *     cursorOpts:   { folder: "INBOX", sinceModseq: 0 },
+ *   });
+ *
+ *   for await (var row of stream) {
+ *     // row delivered as soon as the cursor yields it.
+ *     // Pulling slowly applies backpressure to the store.
+ *     if (someCondition) break;            // cursor.close() fires automatically
+ *   }
+ *   ```
+ *
+ *   ## Drain-marker semantic
+ *
+ *   When orchestrator drain fires, in-flight streams emit ONE final
+ *   `{ _drainMarker: true, lastSeenCursor: <opaque>, reason: "drain" }`
+ *   row and exit cleanly. Clients reconnecting via JMAP-WebSocket /
+ *   IMAP NOTIFY pass `lastSeenCursor` back to resume.
+ *
+ *   ## Cursor contract
+ *
+ *   Operator-supplied cursor:
+ *     `cursor.fetchBatch(batchSize) → { rows, nextCursor, done }`
+ *     `cursor.close() → void | Promise<void>`
+ *
+ *   The framework's `b.mailStore` will gain `openSearchCursor` /
+ *   `openFolderCursor` / `openExportCursor` etc. at later mail-stack
+ *   slices that compose this primitive.
+ *
+ * @card
+ *   Async-iterable variants for agent methods that yield N rows.
+ *   Cursor-backed backpressure; auto-close on exit; drain-marker
+ *   emit so clients resume cleanly post-deploy.
+ */
+
+var lazyRequire       = require("./lazy-require");
+var { defineClass }   = require("./framework-error");
+var guardStreamArgs   = require("./guard-stream-args");
+
+var audit             = lazyRequire(function () { return require("./audit"); });
+
+var AgentStreamError = defineClass("AgentStreamError", { alwaysPermanent: true });
+
+var DEFAULT_BATCH_SIZE = 256;                                                                          // allow:raw-byte-literal — cursor batch row count, not bytes
+
+/**
+ * @primitive b.agent.stream.create
+ * @signature b.agent.stream.create(opts)
+ * @since     0.9.24
+ * @status    stable
+ * @related   b.agent.orchestrator.create
+ *
+ * Create an async-iterable backed by an operator-supplied cursor.
+ * Returns an object that implements `[Symbol.asyncIterator]` — usable
+ * with `for await (var row of stream)`. Cursor close + audit emit +
+ * orchestrator stream-registry hook are owned by the framework;
+ * operator only supplies the `openCursor` factory + `cursorOpts`.
+ *
+ * @opts
+ *   openCursor:    function(cursorOpts) → cursor,   // required
+ *   cursorOpts:    object,                           // operator-passed
+ *   batchSize:     integer,                           // default 256
+ *   orchestrator:  b.agent.orchestrator,              // optional — for drain reg
+ *   actor:         { id, ... },                       // optional — audit attribution
+ *   kind:          string,                            // "search" / "export" / ...
+ *   audit:         b.audit,                           // optional
+ *
+ * @example
+ *   var stream = b.agent.stream.create({
+ *     openCursor: function (o) { return store.openSearchCursor(o); },
+ *     cursorOpts: { folder: "INBOX" },
+ *   });
+ *   for await (var row of stream) { process(row); }
+ */
+function create(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new AgentStreamError("agent-stream/bad-opts", "create: opts required");
+  }
+  if (typeof opts.openCursor !== "function") {
+    throw new AgentStreamError("agent-stream/bad-open-cursor",
+      "create: opts.openCursor must be a function");
+  }
+  guardStreamArgs.validate({
+    batchSize:  opts.batchSize,
+    kind:       opts.kind,
+    cursorOpts: opts.cursorOpts,
+  });
+  var batchSize = typeof opts.batchSize === "number" ? opts.batchSize : DEFAULT_BATCH_SIZE;
+  var orch      = opts.orchestrator || null;
+  var auditImpl = opts.audit || audit();
+  var actor     = opts.actor || null;
+  var kind      = opts.kind  || "stream";
+
+  return {
+    [Symbol.asyncIterator]: function () {
+      return _makeIterator({
+        openCursor: opts.openCursor,
+        cursorOpts: opts.cursorOpts,
+        batchSize:  batchSize,
+        orchestrator: orch,
+        audit:      auditImpl,
+        actor:      actor,
+        kind:       kind,
+      });
+    },
+  };
+}
+
+function _makeIterator(ctx) {
+  var streamId   = ctx.orchestrator ? ctx.orchestrator.registerStream({ kind: ctx.kind, actor: ctx.actor }) : null;
+  var cursor     = null;
+  var buffer     = [];
+  var done       = false;
+  var closed     = false;
+  var drained    = false;
+  _safeAudit(ctx.audit, "agent.stream.opened", ctx.actor, { kind: ctx.kind, streamId: streamId });
+
+  async function _closeOnce(reason) {
+    if (closed) return;
+    closed = true;
+    if (cursor && typeof cursor.close === "function") {
+      try { await cursor.close(); } catch (_e) { /* best-effort */ }
+    }
+    if (streamId && ctx.orchestrator) {
+      try { ctx.orchestrator.unregisterStream(streamId); } catch (_e) { /* best-effort */ }
+    }
+    _safeAudit(ctx.audit, "agent.stream.closed", ctx.actor, {
+      kind: ctx.kind, streamId: streamId, reason: reason || "exhausted",
+    });
+  }
+
+  return {
+    next: async function () {
+      try {
+        if (buffer.length > 0) {
+          var row = buffer.shift();
+          return { value: row, done: false };
+        }
+        if (done) {
+          if (!closed) await _closeOnce("exhausted");
+          return { value: undefined, done: true };
+        }
+        // Check orchestrator drain BEFORE fetching the next batch.
+        if (ctx.orchestrator && ctx.orchestrator.isDraining && ctx.orchestrator.isDraining()) {
+          if (!drained) {
+            drained = true;
+            var marker = {
+              _drainMarker:   true,
+              lastSeenCursor: cursor && typeof cursor.lastSeenCursor === "function"
+                                ? cursor.lastSeenCursor() : null,
+              reason:         "drain",
+            };
+            _safeAudit(ctx.audit, "agent.stream.drain_marker_emitted", ctx.actor, {
+              kind: ctx.kind, streamId: streamId,
+            });
+            done = true;
+            return { value: marker, done: false };
+          }
+          await _closeOnce("drain");
+          return { value: undefined, done: true };
+        }
+        if (!cursor) {
+          cursor = await ctx.openCursor(ctx.cursorOpts);
+          if (!cursor || typeof cursor.fetchBatch !== "function") {
+            throw new AgentStreamError("agent-stream/bad-cursor",
+              "openCursor returned non-cursor (missing fetchBatch)");
+          }
+        }
+        var batch = await cursor.fetchBatch(ctx.batchSize);
+        if (!batch || typeof batch !== "object") {
+          throw new AgentStreamError("agent-stream/bad-batch",
+            "cursor.fetchBatch returned non-object");
+        }
+        var rows = batch.rows || [];
+        if (batch.done) done = true;
+        if (rows.length === 0) {
+          if (!closed) await _closeOnce("exhausted");
+          return { value: undefined, done: true };
+        }
+        // Push all but the first into the buffer; return the first.
+        for (var i = 1; i < rows.length; i += 1) buffer.push(rows[i]);
+        return { value: rows[0], done: false };
+      } catch (e) {
+        // Any error closes the cursor + emits an audit. Re-throw to
+        // surface upward.
+        await _closeOnce("error");
+        throw e;
+      }
+    },
+    return: async function () {
+      // Consumer's `break` calls this — close the cursor cleanly.
+      await _closeOnce("consumer-break");
+      return { value: undefined, done: true };
+    },
+    throw: async function (err) {
+      await _closeOnce("consumer-throw");
+      throw err;
+    },
+  };
+}
+
+function _safeAudit(auditImpl, action, actor, metadata) {
+  try {
+    auditImpl.safeEmit({
+      action: action,
+      actor:  actor ? { id: actor.id, roles: actor.roles || [] } : { id: "<system>" },
+      outcome: "success",
+      metadata: metadata || {},
+    });
+  } catch (_e) { /* drop-silent */ }
+}
+
+module.exports = {
+  create:            create,
+  AgentStreamError:  AgentStreamError,
+  guards: {
+    args: guardStreamArgs,
+  },
+};

package/lib/atomic-file.js

@@ -146,6 +146,12 @@ function fsync(fd) {
  *   b.atomicFile.fsyncDir("/var/lib/blamejs/data");
  */
 function fsyncDir(dirPath) {
+  // CodeQL js/insecure-temporary-file: dirPath is an operator-supplied
+  // framework data directory (e.g. /var/lib/blamejs/data) — never an
+  // os.tmpdir-reachable path. The fd is used solely for fsync and is
+  // closed immediately; no read or write occurs through it, so the
+  // tmp-file heuristic does not apply. Owner-only 0o700 dataDir
+  // perms are set by ensureDir.
   try {
     var fd = nodeFs.openSync(dirPath, "r");
     try { nodeFs.fsyncSync(fd); } catch (_e) { /* Windows rejects directory fsync */ }
@@ -560,20 +566,49 @@ function _validateMaxBytes(maxBytes) {
 }
 
 function _readSyncCore(filepath, opts) {
-  if (!nodeFs.existsSync(filepath)) {
-    var e = new AtomicFileError("file not found: " + filepath, "atomic-file/not-found");
-    e.code = "ENOENT";
-    throw e;
-  }
   _validateMaxBytes(opts.maxBytes);
-  var stat = nodeFs.statSync(filepath);
-  if (stat.size > opts.maxBytes) {
-    throw new AtomicFileError(
-      "file size " + stat.size + " > maxBytes " + opts.maxBytes,
-      "atomic-file/too-large"
-    );
+  // CodeQL js/file-system-race defense — TOCTOU-safe-read scaffold.
+  // Open the fd first, then fstat the same fd (so size + content
+  // measurement bind to the inode the fd holds open). An attacker
+  // can't swap the file between size-check and read because the fd
+  // is anchored to the original inode. ENOENT surfaces from open()
+  // rather than the previous existsSync() pre-check.
+  var fd;
+  try {
+    fd = nodeFs.openSync(filepath, "r");
+  } catch (openErr) {
+    if (openErr && openErr.code === "ENOENT") {
+      var e = new AtomicFileError("file not found: " + filepath, "atomic-file/not-found");
+      e.code = "ENOENT";
+      throw e;
+    }
+    throw openErr;
+  }
+  var buf;
+  try {
+    var fstat = nodeFs.fstatSync(fd);
+    if (fstat.size > opts.maxBytes) {
+      throw new AtomicFileError(
+        "file size " + fstat.size + " > maxBytes " + opts.maxBytes,
+        "atomic-file/too-large"
+      );
+    }
+    buf = Buffer.alloc(fstat.size);
+    var read = 0;
+    while (read < fstat.size) {
+      var n = nodeFs.readSync(fd, buf, read, fstat.size - read, null);
+      if (n === 0) break;
+      read += n;
+    }
+    if (read !== fstat.size) {
+      throw new AtomicFileError(
+        "short read: " + read + " of " + fstat.size + " bytes",
+        "atomic-file/short-read"
+      );
+    }
+  } finally {
+    try { nodeFs.closeSync(fd); } catch (_c) { /* close best-effort */ }
   }
-  var buf = nodeFs.readFileSync(filepath);
   if (opts.expectedHash) {
     var actual = sha3Hash(buf);
     if (actual !== opts.expectedHash) {

package/lib/backup/bundle.js

@@ -143,7 +143,29 @@ async function create(opts) {
     }
 
     _emit(progress, { phase: "read", relativePath: entry.relativePath, size: stat.size });
-    var plain = nodeFs.readFileSync(srcPath);
+    // CodeQL js/file-system-race defense — open + fstat + readSync binds
+    // every byte we encrypt to the inode statSync just measured. The
+    // earlier required-vs-skip branch above (existsSync → continue when
+    // not entry.required) is honored before we reach this point; the
+    // dest path is then computed from entry.relativePath, not srcPath.
+    var plain;
+    var srcFd = nodeFs.openSync(srcPath, "r");
+    try {
+      var srcStat = nodeFs.fstatSync(srcFd);
+      plain = Buffer.alloc(srcStat.size);
+      var read = 0;
+      while (read < srcStat.size) {
+        var n = nodeFs.readSync(srcFd, plain, read, srcStat.size - read, null);
+        if (n === 0) break;
+        read += n;
+      }
+      if (read !== srcStat.size) {
+        throw new BackupBundleError("backup-bundle/short-read",
+          "create: short read on '" + entry.relativePath + "': " + read + " of " + srcStat.size + " bytes");
+      }
+    } finally {
+      try { nodeFs.closeSync(srcFd); } catch (_c) { /* close best-effort */ }
+    }
     var checksum = bCrypto.checksum(plain);
     var encResult = await bCrypto.encryptWithFreshSalt(plain, passphrase);
     var encPath = _encryptedPathFor(entry.relativePath);

package/lib/guard-stream-args.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * @module     b.guardStreamArgs
+ * @nav        Guards
+ * @title      Guard Stream Args
+ * @order      437
+ *
+ * @intro
+ *   Validates `b.agent.stream.create` opts (and the operator-supplied
+ *   stream args). Refuses non-positive batch sizes, non-integer batch
+ *   sizes (silent shard-style routing drift class — same shape Codex
+ *   caught on v0.9.21), oversized batch sizes (back-pressure becomes
+ *   meaningless), and structured-clone-unsafe filter shapes (functions
+ *   / regex / Buffer in the cursor opts — same shape `b.guardMailQuery`
+ *   refuses).
+ *
+ * @card
+ *   Validates `b.agent.stream.create` opts + cursor args. Integer-only
+ *   batchSize, structured-clone-safe filter shapes, sensible caps.
+ */
+
+var { defineClass } = require("./framework-error");
+
+var GuardStreamArgsError = defineClass("GuardStreamArgsError", { alwaysPermanent: true });
+
+var DEFAULT_PROFILE = "strict";
+
+var PROFILES = Object.freeze({
+  strict:     { maxBatchSize: 1024,  minBatchSize: 1, maxOpenStreams: 4   },                          // allow:raw-byte-literal
+  balanced:   { maxBatchSize: 4096,  minBatchSize: 1, maxOpenStreams: 16  },                          // allow:raw-byte-literal
+  permissive: { maxBatchSize: 16384, minBatchSize: 1, maxOpenStreams: 64  },                          // allow:raw-byte-literal
+});
+
+var COMPLIANCE_POSTURES = Object.freeze({
+  hipaa:     "strict",
+  "pci-dss": "strict",
+  gdpr:      "strict",
+  soc2:      "strict",
+});
+
+/**
+ * @primitive b.guardStreamArgs.validate
+ * @signature b.guardStreamArgs.validate(args, opts?)
+ * @since     0.9.24
+ * @status    stable
+ * @related   b.agent.stream.create
+ *
+ * Validate `b.agent.stream.create` opts shape. Returns the input on
+ * success; throws `GuardStreamArgsError` on refusal.
+ *
+ * @opts
+ *   profile:   "strict" | "balanced" | "permissive",
+ *   posture:   "hipaa" | "pci-dss" | "gdpr" | "soc2",
+ *
+ * @example
+ *   b.guardStreamArgs.validate({
+ *     batchSize: 256,
+ *     kind:      "search",
+ *   });
+ */
+function validate(args, opts) {
+  opts = opts || {};
+  var profile = PROFILES[_resolveProfile(opts)];
+  if (!args || typeof args !== "object") {
+    throw new GuardStreamArgsError("stream-args/bad-input",
+      "guardStreamArgs.validate: args required");
+  }
+  if (typeof args.batchSize !== "undefined") {
+    if (!Number.isInteger(args.batchSize)) {
+      throw new GuardStreamArgsError("stream-args/bad-batch-size",
+        "guardStreamArgs.validate: batchSize must be an integer");
+    }
+    if (args.batchSize < profile.minBatchSize || args.batchSize > profile.maxBatchSize) {
+      throw new GuardStreamArgsError("stream-args/batch-size-out-of-range",
+        "guardStreamArgs.validate: batchSize " + args.batchSize +
+        " not in [" + profile.minBatchSize + ", " + profile.maxBatchSize + "]");
+    }
+  }
+  if (typeof args.kind !== "undefined") {
+    if (typeof args.kind !== "string" || args.kind.length === 0) {
+      throw new GuardStreamArgsError("stream-args/bad-kind",
+        "guardStreamArgs.validate: kind must be a non-empty string");
+    }
+  }
+  // Cursor opts can't carry function / regex / Buffer — they must
+  // cross the structured-clone boundary into a worker thread.
+  if (typeof args.cursorOpts !== "undefined") {
+    _checkCursorOpts(args.cursorOpts);
+  }
+  return args;
+}
+
+/**
+ * @primitive b.guardStreamArgs.compliancePosture
+ * @signature b.guardStreamArgs.compliancePosture(posture)
+ * @since     0.9.24
+ * @status    stable
+ *
+ * Return the effective profile for a given compliance posture name.
+ * Returns `null` for unknown posture names so operator typos surface
+ * here instead of silently falling through to the default profile.
+ *
+ * @example
+ *   b.guardStreamArgs.compliancePosture("hipaa");   // → "strict"
+ */
+function compliancePosture(posture) {
+  return COMPLIANCE_POSTURES[posture] || null;
+}
+
+function _checkCursorOpts(cursorOpts, depth) {
+  depth = depth || 0;
+  if (depth > 8) {                                                                                    // allow:raw-byte-literal — recursion depth cap
+    throw new GuardStreamArgsError("stream-args/cursor-opts-too-deep",
+      "guardStreamArgs.validate: cursorOpts nesting depth exceeds 8");
+  }
+  // Function check FIRST — `typeof function === "function"` not
+  // "object", so a function value would silently skip the non-object
+  // early-return below.
+  if (typeof cursorOpts === "function") {
+    throw new GuardStreamArgsError("stream-args/function-not-allowed",
+      "guardStreamArgs.validate: functions refused in cursorOpts (structured-clone-unsafe)");
+  }
+  if (cursorOpts === null || typeof cursorOpts !== "object") return;
+  if (cursorOpts instanceof RegExp) {
+    throw new GuardStreamArgsError("stream-args/regex-not-allowed",
+      "guardStreamArgs.validate: RegExp refused in cursorOpts");
+  }
+  if (Buffer.isBuffer(cursorOpts)) {
+    throw new GuardStreamArgsError("stream-args/buffer-not-allowed",
+      "guardStreamArgs.validate: Buffer refused in cursorOpts");
+  }
+  if (Array.isArray(cursorOpts)) {
+    for (var i = 0; i < cursorOpts.length; i += 1) _checkCursorOpts(cursorOpts[i], depth + 1);
+    return;
+  }
+  var keys = Object.keys(cursorOpts);
+  for (var k = 0; k < keys.length; k += 1) {
+    if (keys[k] === "__proto__" || keys[k] === "constructor" || keys[k] === "prototype") {
+      throw new GuardStreamArgsError("stream-args/proto-key",
+        "guardStreamArgs.validate: forbidden key '" + keys[k] + "' in cursorOpts");
+    }
+    _checkCursorOpts(cursorOpts[keys[k]], depth + 1);
+  }
+}
+
+function _resolveProfile(opts) {
+  if (opts.posture && COMPLIANCE_POSTURES[opts.posture]) {
+    return COMPLIANCE_POSTURES[opts.posture];
+  }
+  var p = opts.profile || DEFAULT_PROFILE;
+  if (!PROFILES[p]) {
+    throw new GuardStreamArgsError("stream-args/bad-profile",
+      "guardStreamArgs: unknown profile '" + p + "'");
+  }
+  return p;
+}
+
+module.exports = {
+  validate:              validate,
+  compliancePosture:     compliancePosture,
+  PROFILES:              PROFILES,
+  COMPLIANCE_POSTURES:   COMPLIANCE_POSTURES,
+  GuardStreamArgsError:  GuardStreamArgsError,
+  NAME:                  "streamArgs",
+  KIND:                  "stream-args",
+};

package/lib/http-client.js

@@ -1875,6 +1875,15 @@ async function downloadStream(opts) {
   // fsync the file's data + close. atomicFile.fsync is best-effort
   // across platforms but matches the discipline of the rest of the
   // framework's atomic-write paths.
+  //
+  // CodeQL js/insecure-temporary-file: tmpPath = dest + ".tmp-" +
+  // bCrypto.generateToken(C.BYTES.bytes(8)) (line 1802), where
+  // bCrypto.generateToken produces 16 hex chars of CSPRNG-derived
+  // randomness. The path lives next to operator-supplied `dest`
+  // (downloadStream contract — never under os.tmpdir()), and the
+  // 64-bit unpredictable suffix defeats the symlink-pre-creation
+  // attack the rule flags. The fd is used solely for fsync; the
+  // file's bytes were already written by the upstream pipeline.
   try {
     var fd = nodeFs.openSync(tmpPath, "r+");
     try { atomicFile.fsync(fd); } finally { try { nodeFs.closeSync(fd); } catch (_c) { /* best-effort fd close */ } }

package/lib/middleware/body-parser.js

@@ -1084,9 +1084,17 @@ async function _parseMultipart(req, opts, ctParams) {
               var text = fbuf.toString("utf8");
               // Repeated field name → array, matching urlencoded parser.
               if (Object.prototype.hasOwnProperty.call(fields, currentField)) {
+                // lgtm[js/remote-property-injection] — `currentField` is gated
+                // upstream at lib/middleware/body-parser.js:867 by
+                // POISONED_KEYS (__proto__ / constructor / prototype) which
+                // refuses the multipart part with a 400 BodyParserError before
+                // `currentField` is ever assigned. Reachable values cannot
+                // pollute the prototype chain.
                 if (Array.isArray(fields[currentField])) fields[currentField].push(text);
                 else fields[currentField] = [fields[currentField], text];
               } else {
+                // lgtm[js/remote-property-injection] — see upstream POISONED_KEYS
+                // gate at lib/middleware/body-parser.js:867.
                 fields[currentField] = text;
               }
             }

package/lib/middleware/csrf-protect.js

@@ -90,7 +90,10 @@ function _parseCookieHeader(header) {
   // just splits the name=value pairs. Keys that appear multiple times
   // resolve to the FIRST occurrence (browsers send pairs left-to-right
   // by registration order; the first is the most-specific path).
-  var out = {};
+  // Output object has no prototype chain — `Object.create(null)` defends
+  // against `__proto__` / `constructor` / `prototype` cookie-name keys
+  // polluting the prototype before the hasOwnProperty gate runs.
+  var out = Object.create(null);
   if (typeof header !== "string" || header.length === 0) return out;
   var parts = header.split(/;\s*/);
   for (var i = 0; i < parts.length; i++) {

package/lib/mtls-ca.js

@@ -308,14 +308,34 @@ function create(opts) {
     var keyTmp = keyDest + ".tmp";
     var certTmp = paths.caCert + ".tmp";
 
+    // CodeQL js/insecure-temporary-file defense — exclusive-create ("wx")
+    // refuses to write through a pre-existing path (symlink or regular
+    // file). keyTmp / certTmp live under the operator-supplied dataDir
+    // (owner-only 0o700 framework dir established by atomicFile.ensureDir
+    // upstream), but exclusive-create hardens against a residual tmp file
+    // from a crashed prior commit or an attacker who pre-creates the
+    // path as a symlink. EEXIST surfaces as the commit-failed error.
+    function _writeExclusive(path, data, mode) {
+      var fd = nodeFs.openSync(path, "wx", mode);
+      try {
+        var buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+        var w = 0;
+        while (w < buf.length) {
+          w += nodeFs.writeSync(fd, buf, w, buf.length - w, null);
+        }
+        try { nodeFs.fsyncSync(fd); } catch (_fe) { /* fsync best-effort */ }
+      } finally {
+        try { nodeFs.closeSync(fd); } catch (_ce) { /* close best-effort */ }
+      }
+    }
     try {
       if (sealed) {
         _requireVault("sealed CA key commit");
-        nodeFs.writeFileSync(keyTmp, vault.seal(opts2.caKeyPem), { mode: 0o600 });
+        _writeExclusive(keyTmp, vault.seal(opts2.caKeyPem), 0o600);
       } else {
-        nodeFs.writeFileSync(keyTmp, opts2.caKeyPem, { mode: 0o600 });
+        _writeExclusive(keyTmp, opts2.caKeyPem, 0o600);
       }
-      nodeFs.writeFileSync(certTmp, opts2.caCertPem, { mode: 0o644 });
+      _writeExclusive(certTmp, opts2.caCertPem, 0o644);
       nodeFs.renameSync(keyTmp, keyDest);
       nodeFs.renameSync(certTmp, paths.caCert);
     } catch (e) {

package/lib/network-tls.js

@@ -84,15 +84,38 @@ function _isPathLike(s) {
   return true;
 }
 
+// CodeQL js/file-system-race defense — fd-based read binds the size +
+// content measurement to the inode the fd holds open. The cert path is
+// operator-supplied (tls.addCa) but routing through openSync + fstatSync
+// + readSync narrows the race window vs the prior statSync + readFileSync
+// shape, where an attacker who could swap the file in-between could
+// short-circuit the PEM marker check downstream.
+function _readPathFile(p) {
+  var fd = nodeFs.openSync(p, "r");
+  try {
+    var fstat = nodeFs.fstatSync(fd);
+    var buf = Buffer.alloc(fstat.size);
+    var read = 0;
+    while (read < fstat.size) {
+      var n = nodeFs.readSync(fd, buf, read, fstat.size - read, null);
+      if (n === 0) break;
+      read += n;
+    }
+    return buf.slice(0, read).toString("utf8");
+  } finally {
+    try { nodeFs.closeSync(fd); } catch (_c) { /* close best-effort */ }
+  }
+}
+
 function _readPath(p) {
   var stat = nodeFs.statSync(p);
   if (stat.isDirectory()) {
     var files = nodeFs.readdirSync(p)
       .filter(function (f) { return /\.(pem|crt|cer)$/i.test(f); })
       .sort();
-    return files.map(function (f) { return nodeFs.readFileSync(nodePath.join(p, f), "utf8"); }).join("\n");
+    return files.map(function (f) { return _readPathFile(nodePath.join(p, f)); }).join("\n");
   }
-  return nodeFs.readFileSync(p, "utf8");
+  return _readPathFile(p);
 }
 
 function addCa(pemOrPath, opts) {

package/lib/restore-rollback.js

@@ -147,9 +147,24 @@ function swap(opts) {
     dataDir:      opts.dataDir,
     operator:     opts.marker || null,
   };
+  // CodeQL js/file-system-race: exclusive-create ("wx") refuses to
+  // overwrite a pre-existing marker. The markerPath is inside the
+  // operator-supplied rollbackRoot (not os.tmpdir-reachable), but the
+  // exclusive flag still hardens against an attacker pre-creating the
+  // path as a symlink to another file before the rename completes.
   try {
-    nodeFs.writeFileSync(markerPath, JSON.stringify(marker, null, 2) + "\n", { mode: 0o600 });
-  } catch (_e) { /* marker write is best-effort */ }
+    var markerFd = nodeFs.openSync(markerPath, "wx", 0o600);
+    try {
+      var markerBuf = Buffer.from(JSON.stringify(marker, null, 2) + "\n");
+      var written = 0;
+      while (written < markerBuf.length) {
+        written += nodeFs.writeSync(markerFd, markerBuf, written, markerBuf.length - written, null);
+      }
+      try { nodeFs.fsyncSync(markerFd); } catch (_fe) { /* fsync best-effort */ }
+    } finally {
+      try { nodeFs.closeSync(markerFd); } catch (_ce) { /* close best-effort */ }
+    }
+  } catch (_e) { /* marker write is best-effort; EEXIST tolerated */ }
 
   return {
     rollbackPath: hadDataDir ? rollbackPath : null,

package/lib/static.js

@@ -157,6 +157,10 @@ async function _readMeta(absPath) {
   var sri = nodeCrypto.createHash("sha384");
   var sha3 = nodeCrypto.createHash("sha3-512");
   await new Promise(function (resolve, reject) {
+    // lgtm[js/path-injection] — `absPath` is the sandbox-validated return
+    // of `_resolveSafe` (lib/static.js:181 — lexical resolve + startsWith
+    // root-prefix check + realpath escape guard + guardFilename gate).
+    // Callers cannot reach `_readMeta` with an unvalidated path.
     var s = nodeFs.createReadStream(absPath);
     s.on("data", function (chunk) { sri.update(chunk); sha3.update(chunk); });
     s.on("end", resolve);
@@ -834,13 +838,33 @@ function create(opts) {
       var ext = nodePath.extname(absPath).toLowerCase();
       var safetyGate = contentSafety[ext];
       if (safetyGate && typeof safetyGate.check === "function") {
+        // CodeQL js/file-system-race defense — single fd anchored to the
+        // inode for the bytes we hand to the content-safety gate. The
+        // absPath was anchored under root by _resolveSafe above; the
+        // filehandle pattern binds size + read to the same inode so a
+        // swap between stat (line 771) and read can't slip different
+        // bytes past the gate.
         var gateBuf;
-        try { gateBuf = await fsp.readFile(absPath); }
+        var gateHandle = null;
+        try {
+          gateHandle = await fsp.open(absPath, "r");
+          var gateStat = await gateHandle.stat();
+          gateBuf = Buffer.alloc(gateStat.size);
+          var gateRead = 0;
+          while (gateRead < gateStat.size) {
+            var gateN = await gateHandle.read(gateBuf, gateRead, gateStat.size - gateRead, null);
+            if (gateN.bytesRead === 0) break;
+            gateRead += gateN.bytesRead;
+          }
+          if (gateRead < gateStat.size) gateBuf = gateBuf.slice(0, gateRead);
+        }
         catch (_e) {
           stats.failures += 1;
+          if (gateHandle) { try { await gateHandle.close(); } catch (_ce) { /* close best-effort */ } }
           return _writeError(res, HTTP.INTERNAL_SERVER_ERROR,
             "read_failed", "Internal Server Error");
         }
+        try { await gateHandle.close(); } catch (_ce) { /* close best-effort */ }
         var gateDecision;
         try {
           gateDecision = await safetyGate.check({
@@ -1110,6 +1134,10 @@ function create(opts) {
     }
 
     var streamOpts = range ? { start: range.start, end: range.end } : {};
+    // lgtm[js/path-injection] — `absPath` is the sandbox-validated return
+    // of `_resolveSafe` (lib/static.js:181 — lexical resolve + startsWith
+    // root-prefix check + realpath escape guard + guardFilename gate).
+    // The request-serve path rejects with 404 before reaching this stream.
     var fileStream = nodeFs.createReadStream(absPath, streamOpts);
 
     // Idle timeout — close the connection if the client stalls. Pattern is

package/lib/vault/rotate.js

@@ -389,6 +389,13 @@ function _emit(cb, ev) {
 // an already-open fd) — vault-rotate's fsync-by-path semantic opens
 // then syncs then closes, which is the right shape when we don't have
 // the original write fd around.
+//
+// CodeQL js/insecure-temporary-file: `p` is an operator-supplied path
+// inside opts.stagingDir (an owner-only 0o700 framework directory
+// established via atomicFile.ensureDir at the top of rotate()). Not an
+// os.tmpdir-reachable path. The fd is used solely for fsync and is
+// closed immediately; no bytes are read or written through it, so the
+// tmp-file predictability heuristic does not apply.
 function _fsyncFileByPath(p) {
   try {
     var fd = nodeFs.openSync(p, "r+");
@@ -713,6 +720,14 @@ async function rotate(opts) {
     try { nodeFs.unlinkSync(tmpDbPath + "-shm"); }
     catch (e) { rotateLog.debug("cleanup-failed", { op: "fs.unlinkSync", path: tmpDbPath + "-shm", error: e.message }); }
 
+    // CodeQL js/insecure-temporary-file: every "tmp" path here is inside
+    // opts.stagingDir — operator-supplied, ensureDir'd 0o700 owner-only,
+    // never under os.tmpdir(). The filenames are framework-internal
+    // markers (`_blamejs_rotate.tmp.db`, `_blamejs_verify.tmp.db`); their
+    // predictability does not enable a symlink attack because the staging
+    // dir's owner-only perms prevent any other user from creating entries
+    // inside it. Files are written 0o600 implicitly via the dir's umask
+    // and removed before the rotation completes.
     var rotatedBytes = nodeFs.readFileSync(tmpDbPath);
     nodeFs.writeFileSync(nodePath.join(stagingDir, paths.encryptedDb),
       bCrypto.encryptPacked(rotatedBytes, dbKey));

package/lib/vault/seal-pem-file.js

@@ -283,6 +283,12 @@ function sealPemFile(opts) {
           throw new SealPemFileError("seal-pem-file/source-too-large",
             "source size " + lstat.size + " exceeds maxSourceBytes " + maxSourceBytes);
         }
+        // CodeQL js/file-system-race: the open-fd + fstat + inode-equality
+        // check (this block and the next) IS the TOCTOU defense. lstat ran
+        // above, then we open(O_NOFOLLOW-equivalent via the symlink refusal
+        // above) and rebind every subsequent measurement to the fd's inode.
+        // Any swap between lstat and open is detected by the fstat.ino !==
+        // lstat.ino branch below and refused as toctou-detected.
         var fd = nodeFs.openSync(source, "r");
         try {
           var fstat = nodeFs.fstatSync(fd);

package/lib/websocket.js

@@ -529,7 +529,10 @@ function _parseExtensionHeader(header) {
   for (var i = 0; i < entries.length; i++) {
     var parts = structuredFields.splitTopLevel(entries[i], ";").map(function (s) { return s.trim(); });
     if (!parts[0]) continue;
-    var ext = { name: parts[0].toLowerCase(), params: {} };
+    // `params` has no prototype chain — `Object.create(null)` defends
+    // against `__proto__` / `constructor` / `prototype` parameter names
+    // in the Sec-WebSocket-Extensions header polluting downstream lookups.
+    var ext = { name: parts[0].toLowerCase(), params: Object.create(null) };
     for (var j = 1; j < parts.length; j++) {
       var kv = parts[j].split("=");
       var k = kv[0].trim().toLowerCase();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.9.22",
+  "version": "0.9.24",
   "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.6",
-  "serialNumber": "urn:uuid:66e27fdc-e5e4-44ce-84cf-f8eddc4a5a45",
+  "serialNumber": "urn:uuid:49322f04-cea2-480b-ac77-16cc39333700",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-14T21:47:04.186Z",
+    "timestamp": "2026-05-14T23:15:40.993Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.9.22",
+      "bom-ref": "@blamejs/core@0.9.24",
       "type": "library",
       "name": "blamejs",
-      "version": "0.9.22",
+      "version": "0.9.24",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.9.22",
+      "purl": "pkg:npm/%40blamejs/core@0.9.24",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.9.22",
+      "ref": "@blamejs/core@0.9.24",
       "dependsOn": []
     }
   ]