@blamejs/core 0.18.39 → 0.18.41

package/lib/gate-contract.js

@@ -85,7 +85,9 @@ var DEFAULT_CACHE_TTL_MS = C.TIME.minutes(5);
  * shape violations: `gate-contract/bad-shape` from
  * `validateGateShape`, `gate-contract/bad-opt` from `defineGate` /
  * `cachingGate` / `workerThreadGate`, `gate-contract/profile-cycle`
- * and `gate-contract/unknown-profile` from `buildProfile`.
+ * and `gate-contract/unknown-profile` from `buildProfile`, and
+ * `gate-contract/bad-context` from a gate's `check` when the context
+ * it is handed is neither an object nor absent.
  * `alwaysPermanent` — never retried by `b.retry`.
  *
  * @example
@@ -290,6 +292,126 @@ function validateGateShape(gate, label, errorClass) {
  *   var d = await gate.check({ bytes: Buffer.from("name,age\nada,36") });
  *   d.action;                                            // → "serve"
  */
+// A gate context with some fields REPLACED, leaving the caller's object alone.
+// Used by the two paths that genuinely change the context — a `beforeCheck`
+// transform, and the sanitize rebind that feeds scrubbed bytes to the next gate
+// in a composition. Module scope on purpose: `composeGates` is not inside
+// defineGate's closure.
+//
+// A context is not required to be a plain object, and the obvious shortcuts
+// each break a different kind of one. Every line here is a fix for a shape that
+// was mishandled:
+//
+//   - `Object.assign({}, base, ...)` copies OWN enumerable properties, so a
+//     class instance whose fields come from prototype getters arrives with them
+//     missing. A guard reading an absent subject as nothing-to-inspect then
+//     serves bytes it used to examine.
+//   - `Object.create(base)` fixes that but makes inherited getters run with the
+//     DERIVED object as `this`, so a getter returning a private field throws
+//     and a valid context is refused.
+//   - Assigning the overrides (including via `Object.assign`) performs [[Set]],
+//     which walks the chain: an inherited non-writable property throws, and an
+//     inherited setter runs and writes into the caller.
+//
+// So: forward each readable name to `base` with `base` as the receiver, and
+// install the overrides as own data properties via [[DefineOwnProperty]]. The
+// readable names are collected once, which is sound because both callers derive
+// from a context that is already fully formed.
+function _deriveContext(base, overrides) {
+  // Same prototype as the caller's object, so `ctx instanceof TheirClass` still
+  // answers what it did — a guard may dispatch or validate on the context's
+  // type, and a wrapper on a bare object would fail that while carrying every
+  // one of the instance's fields. The forwarding accessors below are installed
+  // as OWN properties, so they shadow the prototype for everything readable and
+  // the prototype serves only identity.
+  var derived = Object.create(Object.getPrototypeOf(base));
+  var seen = Object.create(null);
+  // Copy-on-write. The getter forwards to `base` with `base` as the receiver;
+  // the setter REPLACES itself with a plain own data property holding the new
+  // value, so a guard that normalizes its subject in place (`ctx.bytes = ...`)
+  // succeeds and every later read sees the update. Without the setter the
+  // assignment silently does nothing, or throws under strict mode and turns a
+  // completed check into a refusal. The caller's object is still never touched.
+  //
+  // Functions are forwarded AS THEY ARE — never bound. That is a deliberate
+  // choice between two things that cannot both hold, and it is worth stating
+  // because the losing side is a real capability:
+  //
+  //   - Called as `ctx.read()`, an unbound method runs with the DERIVED context
+  //     as `this`, so a method reading `this.bytes` sees an override a
+  //     `beforeCheck` transform or a sanitize step installed. This is the whole
+  //     point of a sanitize chain: nothing downstream may see the original
+  //     bytes. Binding to the caller's object was measured handing back
+  //     `ORIGINAL` from a method while direct access returned `SANITIZED`.
+  //   - Bound to the caller's object instead, a method carrying a brand — one
+  //     reading a private field, or a built-in like `Map#get` — works, but then
+  //     every ordinary method reads around the overrides.
+  //
+  // A brand requires the original instance as the receiver; an override
+  // requires the derived one. No receiver satisfies both, so the security
+  // property wins: overrides are always visible. A context whose data is only
+  // reachable through a branded method is therefore REFUSED rather than
+  // inspected against stale bytes — fail-closed, and visible to the operator,
+  // who can pass the fields directly instead.
+  //
+  // Not binding also keeps every function's identity and lets a guard choose a
+  // receiver with `.call()`, which matters for a callback the caller stored on
+  // the context.
+  var forward = function (key, enumerable) {
+    Object.defineProperty(derived, key, {
+      get: function () { return base[key]; },
+      set: function (value) {
+        Object.defineProperty(derived, key, {
+          value:        value,
+          writable:     true,
+          enumerable:   enumerable,
+          configurable: true,
+        });
+      },
+      // Mirror the source. Enumerability is observable — a guard that spreads
+      // the context, calls Object.keys, or serializes it would otherwise see
+      // fields the original hid, and serializing a hidden accessor RUNS a
+      // getter the guard never chose to read.
+      enumerable:   enumerable,
+      configurable: true,
+    });
+  };
+  // Reflect.ownKeys, not getOwnPropertyNames: a guard may tag its context with
+  // a Symbol to avoid colliding with a caller's field names, and a
+  // string-key-only walk drops it silently.
+  for (var proto = base; proto && proto !== Object.prototype;
+       proto = Object.getPrototypeOf(proto)) {
+    var names = Reflect.ownKeys(proto);
+    for (var i = 0; i < names.length; i += 1) {
+      var key = names[i];
+      if (seen[key]) continue;
+      var desc = Object.getOwnPropertyDescriptor(proto, key);
+      // Skip a class prototype's own back-reference to its constructor, which
+      // is plumbing rather than context — but NOT a field the caller happens to
+      // have named `constructor`, which is theirs and carries their value.
+      if (key === "constructor" && proto !== base && desc &&
+          typeof desc.value === "function" && desc.value.prototype === proto) {
+        continue;
+      }
+      seen[key] = true;
+      forward(key, desc ? desc.enumerable : true);
+    }
+  }
+  if (overrides) {
+    var keys = Reflect.ownKeys(overrides);
+    for (var k = 0; k < keys.length; k += 1) {
+      var od = Object.getOwnPropertyDescriptor(overrides, keys[k]);
+      Object.defineProperty(derived, keys[k], {
+        value:        overrides[keys[k]],
+        writable:     true,
+        enumerable:   od ? od.enumerable : true,
+        configurable: true,
+      });
+    }
+  }
+  return derived;
+}
+
 function defineGate(opts) {
   validateOpts.requireObject(opts, "gateContract.defineGate", GateContractError);
   validateOpts.requireNonEmptyString(opts.name, "gateContract.defineGate: name", GateContractError, "gate-contract/bad-opt");
@@ -350,8 +472,30 @@ function defineGate(opts) {
 
   async function check(ctx) {
     var startedAt = Date.now();
-    ctx = ctx || {};
-    if (!ctx.forensicId) ctx.forensicId = bCrypto.generateToken(FORENSIC_ID_BYTES);
+    // The gate owns the context it works with; the caller's object is read, not
+    // written. Stamping the forensic id onto whatever arrived meant a string
+    // raised a raw TypeError — and `check` is async, so that surfaced as an
+    // unhandled rejection taking the process down rather than the request — and
+    // a frozen context, which an operator freezes precisely so middleware
+    // cannot edit the request shape, was refused for being frozen.
+    if (ctx === null || ctx === undefined) {
+      ctx = {};
+    } else if (typeof ctx !== "object") {
+      throw _err("gate-contract/bad-context",
+        opts.name + ".check: context must be an object (got " + typeof ctx + ")");
+    }
+    // A guard can read `ctx.forensicId` to correlate its own audit records, so
+    // the id stays visible on the context the check receives. What changes is
+    // how it gets there: an id the caller supplied is used as-is and the
+    // caller's object is passed straight through, and only when one has to be
+    // generated is a context derived to carry it — never by writing into the
+    // object the caller handed over.
+    // Derive unconditionally. Whether the caller supplied an id decides only
+    // whether one is generated — never whether the caller's object is isolated,
+    // because a hook or guard that assigns to the context would otherwise be
+    // writing into the caller's own state, and would throw against a frozen one.
+    var forensicId = ctx.forensicId || bCrypto.generateToken(FORENSIC_ID_BYTES);
+    ctx = _deriveContext(ctx, { forensicId: forensicId });
 
     // Decision cache lookup (memoize per-forensicHash).
     var bytes = ctx.bytes;
@@ -376,7 +520,11 @@ function defineGate(opts) {
       return _build({ ok: true, action: "serve", forensicHash: forensicHash, runtimeMs: Date.now() - startedAt });
     }
     if (beforeRv && beforeRv.transform) {
-      ctx = Object.assign({}, ctx, beforeRv.transform);
+      // Extend the chain, never flatten it: the caller's fields are reached
+      // THROUGH `ctx` rather than owned by it, so rebuilding from own
+      // enumerable properties would drop the subject on exactly the gates an
+      // operator attached a hook to.
+      ctx = _deriveContext(ctx, beforeRv.transform);
     }
 
     // Run operator check with optional runtime cap.
@@ -455,6 +603,10 @@ function defineGate(opts) {
         decision.forensicSnapshot = snippet;
         if (forensicEvidenceStore && typeof forensicEvidenceStore.write === "function") {
           await forensicEvidenceStore.write({
+            // Read from the context as it stands, not from the id computed
+            // before the hooks ran: a `beforeCheck` transform may replace the
+            // forensic id, and the guard saw the replacement. Recording the
+            // earlier one breaks exactly the correlation the id exists for.
             forensicId: ctx.forensicId,
             forensicHash: forensicHash,
             ruleHash: ruleHash,
@@ -664,7 +816,9 @@ function composeGates(gates, opts) {
           if (d.sanitized) sanitized = d.sanitized;
           // Feeding the scrubbed bytes forward is what makes the chain a
           // pipeline rather than N independent opinions on the same input.
-          if (firstRefusalWins) ctx = Object.assign({}, ctx, { bytes: d.sanitized });
+          // Same chain-extending rebind as the beforeCheck transform above —
+          // only `bytes` is being replaced, not the rest of the context.
+          if (firstRefusalWins) ctx = _deriveContext(ctx, { bytes: d.sanitized });
         }
       }
       return _build({

package/lib/guard-filename.js

@@ -881,7 +881,17 @@ function sanitize(input, opts) {
  * every reject-policy off — strip-eligible classes only) → `refuse`
  * (any reject-policy active or sanitize fails). Path-traversal /
  * null-byte / NTFS-ADS / UNC / overlong-UTF-8 always cause `refuse`
- * — there is no `sanitize` action for those classes.
+ * — there is no `sanitize` action for those classes, and no policy
+ * setting reaches them.
+ *
+ * Each finding is dispositioned by its own policy and the strongest
+ * answer across them decides the action. The repair itself is not
+ * per-finding: `sanitize` dispatches to `b.guardFilename.sanitize`,
+ * which applies every transform the profile declares, so a name that
+ * enters sanitization because one class asked to strip also has the
+ * profile's other repairs applied — including to a class whose own
+ * policy was `audit`. The verdict's `sanitized` is byte-identical to
+ * calling `b.guardFilename.sanitize(name, opts)` directly.
  *
  * @opts
  *   profile:    "strict"|"balanced"|"permissive",
@@ -896,6 +906,52 @@ function sanitize(input, opts) {
  *   var ok = await fnGate.check({ filename: "report.txt" });
  *   ok.action;                                         // → "serve"
  */
+// Bind each finding to the operator's policy for it. The shared character
+// classes resolve through the one family helper; the filename-specific kinds
+// map to the policy this guard names for them. A kind with no policy returns
+// null and the caller applies the conservative severity answer.
+// The classes this guard refuses unconditionally, whatever any policy says.
+// Documented on the gate itself: there is no `sanitize` action for them, and a
+// name carrying one is not repairable into a safe name — a UNC prefix reaches
+// another host, a traversal segment escapes the directory, a NUL truncates the
+// name at whichever consumer reads it first, and an ADS suffix names a second
+// stream on the same file. Reading these from `traversalPolicy` would let a
+// profile that sets it to `audit` serve the name unchanged, which is the
+// bypass the floor exists to prevent.
+var ALWAYS_REFUSE_KINDS = Object.freeze({
+  "path-traversal":         true,
+  "path-traversal-encoded": true,
+  "unc-path":               true,
+  "ntfs-ads":               true,
+  "null-byte":              true,
+  "overlong-utf8":          true,
+});
+
+function _gateDispositionFor(issue, opts) {
+  if (ALWAYS_REFUSE_KINDS[issue.kind]) return "refuse";
+  var shared = gateContract.charThreatDisposition(issue, opts);
+  if (shared) return shared;
+  switch (issue.kind) {
+    case "path-separator-in-leaf":
+    case "url-encoded-separator":    return gateContract.policyDisposition(opts.pathSeparatorsPolicy);
+    case "reserved-char":            return gateContract.policyDisposition(opts.reservedCharPolicy);
+    case "reserved-name":            return gateContract.policyDisposition(opts.reservedNamePolicy);
+    case "leading-trailing-strip":   return gateContract.policyDisposition(opts.leadingTrailingPolicy);
+    case "homoglyph":                return gateContract.policyDisposition(opts.homoglyphPolicy);
+    case "non-ascii":                return gateContract.policyDisposition(opts.nonAsciiPolicy);
+    // Both of these fire on the same condition — a last extension in
+    // SHELL_EXEC_EXTS — so they are one finding reported twice and answer to
+    // one policy. Mapping only the first left the second on the conservative
+    // severity default, where `critical` refuses, and a profile asking to
+    // audit a disguised executable refused it instead.
+    case "shell-exec-ext":
+    case "double-extension":         return gateContract.policyDisposition(opts.shellExecExtPolicy);
+    // Length, extension allowlisting and the dot-shape findings carry no
+    // policy of their own and admit no repair that preserves intent.
+    default:                         return null;
+  }
+}
+
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -907,27 +963,46 @@ function gate(opts) {
       if (!name) return { ok: true, action: "serve" };
       var rv = validate(name, opts);
       if (rv.issues.length === 0) return { ok: true, action: "serve" };
-      var hasCritical = rv.issues.some(function (i) {
-        return i.severity === "critical" || i.severity === "high";
-      });
-      if (!hasCritical) return { ok: true, action: "audit-only", issues: rv.issues };
-
-      // Sanitize-eligibility — every reject-policy must be off.
-      var canSanitize = opts.bidiPolicy !== "reject" &&
-                        opts.controlPolicy !== "reject" &&
-                        opts.nullBytePolicy !== "reject" &&
-                        opts.traversalPolicy !== "reject" &&
-                        opts.reservedCharPolicy !== "reject" &&
-                        opts.reservedNamePolicy !== "reject" &&
-                        opts.adsPolicy !== "reject" &&
-                        opts.pathSeparatorsPolicy !== "reject" &&
-                        opts.leadingTrailingPolicy !== "reject";
-      if (canSanitize) {
+
+      // The action comes from what each finding's OWN policy asks, and the
+      // strongest answer across the findings wins. Resolving it from severity
+      // instead made `critical` and `high` both refuse, so a profile asking to
+      // strip a zero-width character refused the filename rather than cleaning
+      // it — and the sanitize-eligibility test below compounded that by being
+      // all-or-nothing: one `reject` policy anywhere in the profile made every
+      // OTHER policy refuse too, whatever it declared.
+      //
+      // Taking the strongest disposition keeps that from weakening anything: a
+      // traversal finding still refuses on its own policy no matter what the
+      // character policies say, which is the case the all-or-nothing test was
+      // reaching for.
+      var strongest = "serve";
+      var RANK = { serve: 0, "audit-only": 1, sanitize: 2, refuse: 3 };
+      for (var qi = 0; qi < rv.issues.length; qi += 1) {
+        var d = _gateDispositionFor(rv.issues[qi], opts);
+        if (d === "audit") d = "audit-only";
+        // A finding with no policy of its own carries no instruction, so it
+        // falls back to the conservative severity answer rather than serving.
+        if (!d) {
+          d = (rv.issues[qi].severity === "critical" || rv.issues[qi].severity === "high")
+            ? "refuse" : "audit-only";
+        }
+        if (RANK[d] > RANK[strongest]) strongest = d;
+      }
+      if (strongest === "serve") return { ok: true, action: "serve", issues: rv.issues };
+      if (strongest === "audit-only") return { ok: true, action: "audit-only", issues: rv.issues };
+
+      if (strongest === "sanitize") {
         try {
           var clean = sanitize(name, opts);
+          // `sanitized` is the field the gate contract carries through; a
+          // guard-specific name is dropped by the verdict builder, which would
+          // hand the caller `action: "sanitize"` with nothing to use. This
+          // branch was all but unreachable while sanitize-eligibility was
+          // all-or-nothing, so the wrong field name never showed.
           return {
             ok: true, action: "sanitize",
-            sanitizedFilename: clean,
+            sanitized: clean,
             issues: rv.issues,
           };
         } catch (_e) { /* fall through */ }

package/lib/guard-yaml.js

@@ -735,6 +735,69 @@ function _sanitizeTransform(input, opts) {
   return codepointClass.scrubCharThreats(input, opts, _err, "yaml");
 }
 
+/**
+ * @primitive  b.guardYaml.gate
+ * @signature  b.guardYaml.gate(opts?)
+ * @since      0.7.14
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardYaml.validate, b.guardYaml.parse, b.staticServe.create, b.fileUpload.create
+ *
+ * Build a `b.gateContract` gate for plugging into
+ * `b.staticServe({ contentSafety: { ".yaml": gate } })`,
+ * `b.fileUpload({ contentSafety: { "application/yaml": gate } })`,
+ * or any host primitive that consumes the gate-contract shape.
+ *
+ * The action comes from the POLICY the active profile declares for each
+ * finding, not from the finding's severity: a character class set to `strip`
+ * is repaired and returned as `sanitize`, one set to `audit` reports
+ * `audit-only`, and one set to `reject` refuses. Findings that carry no policy
+ * and admit no repair — an alias explosion, a blown anchor cap, an oversized
+ * document, one that does not parse — fall back to the conservative severity
+ * answer and refuse.
+ *
+ * Only character-level repair is offered. Stripping an invisible or control
+ * character is a text edit needing no re-emit; the tag, alias and
+ * multi-document shapes have no faithful round-trip, so they refuse through
+ * their own policies rather than being rewritten.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliancePosture: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   name:       string,    // gate identity for audit / observability
+ *
+ * @example
+ *   var yamlGate = b.guardYaml.gate({ profile: "balanced" });
+ *   var d = await yamlGate.check({ bytes: Buffer.from("key: value\n") });
+ *   d.action;                                            // → "serve"
+ */
+// The gate every other content guard builds explicitly. Without it `defineGuard`
+// falls back to the default gate, which ends in `severityDisposition` and never
+// consults this guard's disposition map — so a class the profile sets to `strip`
+// or `audit` was refused anyway, because its finding happens to carry a high
+// severity. Seven of the twelve character-policy cells resolved that way.
+function gate(opts) {
+  // Resolve the profile FIRST. `buildContentGate` hands these opts straight to
+  // the disposition map, and an unresolved bag carries no `zeroWidthPolicy` /
+  // `bidiPolicy` / `controlPolicy` / `nullBytePolicy` at all — so every char
+  // finding falls through to the severity answer and refuses, which is the
+  // same wrong outcome by a different route.
+  opts = gateContract.resolveProfileAndPosture(opts, {
+    profiles:           PROFILES,
+    compliancePostures: COMPLIANCE_POSTURES,
+    defaults:           DEFAULTS,
+    errorClass:         GuardYamlError,
+    errCodePrefix:      "yaml",
+  });
+  return gateContract.buildContentGate({
+    name:     opts.name || "guardYaml:" + (opts.profile || "default"),
+    opts:     opts,
+    validate: module.exports.validate,
+    dispositionFor:   _gateDispositionFor,
+    produceSanitized: _sanitizeTransform,
+  });
+}
+
 module.exports = gateContract.defineGuard({
   name:        "yaml",
   kind:        "content",
@@ -748,6 +811,7 @@ module.exports = gateContract.defineGuard({
   detect:      _detectIssues,
   intOpts:     ["maxBytes", "maxDepth", "maxAnchors", "maxAliasDepth",
                 "maxDocuments", "maxNodes", "maxScalarLength"],
+  gate:              gate,
   dispositionFor:    _gateDispositionFor,
   sanitizeTransform: _sanitizeTransform,
   extra: {

package/lib/http-client.js

@@ -851,9 +851,7 @@ function _attachJarCookie(headers, jar, url) {
 function _buildMultipartBody(spec) {
   var boundary = "----blamejs-mp-" + bCrypto.generateToken(C.BYTES.bytes(16));
   var CRLF = "\r\n";
-  var nodeFs = require("node:fs");                                             // allow:inline-require — only on multipart paths that touch the filesystem
-  var path = require("node:path");                                         // allow:inline-require — same
-  var nodeStream = require("node:stream");                                 // allow:inline-require — Readable subclass only when streaming
+  var path = require("node:path");                                         // allow:inline-require — only on multipart paths that touch the filesystem
 
   // Each entry is { headerBytes, source } where source is one of:
   //   { kind: "buffer", buf: Buffer }