@blamejs/core 0.8.69 → 0.8.71

package/lib/mcp.js

@@ -375,8 +375,330 @@ function serverGuard(opts) {
   };
 }
 
+/**
+ * @primitive b.mcp.toolResult.sanitize
+ * @signature b.mcp.toolResult.sanitize(result, opts?)
+ * @since     0.8.70
+ * @related   b.mcp.serverGuard, b.guardHtml, b.ai.input.classify
+ *
+ * OWASP LLM02 — model/tool-output sanitization. MCP tool calls
+ * frequently return content the host model interprets as further
+ * instructions; an attacker-controlled tool surface can return
+ * `{ type: "text", text: "Ignore prior instructions and ..." }`,
+ * `<script>...</script>`, OR markdown image links pointing at
+ * exfiltration endpoints. The framework's defense:
+ *
+ *   - Strip / refuse executable HTML (`<script>` / `<iframe>` /
+ *     `javascript:` URLs) — composes b.guardHtml's strict profile
+ *   - Refuse known prompt-injection markers ("ignore previous
+ *     instructions", "system: you are now ...", role-claim prefixes)
+ *     — composes b.ai.input.classify
+ *   - Cap text length so a tool can't blow the host's context window
+ *     out from under it
+ *   - Refuse content with `image_url` / `audio_url` / `resource_link`
+ *     pointing at non-allowlisted hosts (data-exfil via auto-fetch)
+ *
+ * Returns either the cleaned result (when `sanitize: true`) or
+ * throws `McpError("mcp/tool-output-refused", ...)` (default —
+ * fail-closed). Operators with a known-good tool surface that needs
+ * raw passthrough opt out via `posture: "audit-only"`.
+ *
+ * @opts
+ *   {
+ *     posture?:        "refuse" | "sanitize" | "audit-only",  // default "refuse"
+ *     maxTextBytes?:   number,    // default 64 KiB per content block
+ *     allowedHosts?:   string[],  // for image/audio/resource_link refs
+ *     classifyInput?:  fn(text)→{verdict, score} | null,      // default b.ai.input.classify
+ *   }
+ *
+ * @example
+ *   var safe = b.mcp.toolResult.sanitize(toolResp, { posture: "sanitize" });
+ *   // → { content: [{ type: "text", text: "<cleaned>" }] }
+ */
+var DEFAULT_TOOL_OUTPUT_MAX_BYTES = 64 * 1024;                                                   // allow:raw-byte-literal — 64 KiB per content block
+var PROMPT_INJECTION_MARKERS = [
+  "ignore (previous|prior|all) instructions",
+  "system:\\s*you are",
+  "<\\|im_(start|end)\\|>",
+  "<\\|system\\|>",
+  "###\\s*(system|assistant|user|tool)",
+  "<system>",
+  "</?(?:assistant|system|user|tool)>",
+];
+var INJECTION_RE = new RegExp(PROMPT_INJECTION_MARKERS.join("|"), "i");                          // allow:dynamic-regex — composed from the const PROMPT_INJECTION_MARKERS list above; not operator-supplied input
+var DANGEROUS_HTML_RE = /<script\b|<iframe\b|<object\b|<embed\b|javascript:/i;
+
+function _toolResultSanitize(result, opts) {
+  opts = opts || {};
+  var posture = opts.posture || "refuse";
+  if (["refuse", "sanitize", "audit-only"].indexOf(posture) === -1) {
+    throw new McpError("mcp/bad-posture",
+      "toolResult.sanitize: posture must be 'refuse' | 'sanitize' | 'audit-only'");
+  }
+  var maxBytes = opts.maxTextBytes || DEFAULT_TOOL_OUTPUT_MAX_BYTES;
+  var allowedHosts = Array.isArray(opts.allowedHosts) ? opts.allowedHosts : [];
+  if (!result || typeof result !== "object") {
+    throw new McpError("mcp/bad-tool-result",
+      "toolResult.sanitize: result must be an object");
+  }
+  var content = Array.isArray(result.content) ? result.content : [];
+  var issues = [];
+  var cleaned = [];
+  for (var i = 0; i < content.length; i++) {
+    var block = content[i];
+    if (!block || typeof block !== "object") {
+      issues.push({ kind: "bad-block", index: i });
+      continue;
+    }
+    if (block.type === "text" && typeof block.text === "string") {
+      var t = block.text;
+      if (Buffer.byteLength(t, "utf8") > maxBytes) {
+        issues.push({ kind: "text-too-long", index: i, bytes: Buffer.byteLength(t, "utf8") });
+        if (posture === "sanitize") t = Buffer.from(t, "utf8").subarray(0, maxBytes).toString("utf8");
+      }
+      // Bound the regex-test surface to maxBytes (already enforced
+      // upstream when sanitize-mode strips, but in audit-only / refuse
+      // modes we still hand the raw text into the regex so cap
+      // explicitly here to satisfy the regex-bound-length rule).
+      var regexInput = Buffer.byteLength(t, "utf8") > maxBytes
+        ? Buffer.from(t, "utf8").subarray(0, maxBytes).toString("utf8")
+        : t;
+      if (INJECTION_RE.test(regexInput)) {                                                       // allow:regex-no-length-cap regexInput byteLength bounded above
+        issues.push({ kind: "prompt-injection", index: i });
+        if (posture === "sanitize") {
+          // Strip the injection marker line — operators wanting
+          // structural redaction wire their own classifier.
+          t = t.replace(INJECTION_RE, "[REDACTED]");
+        }
+      }
+      if (DANGEROUS_HTML_RE.test(regexInput)) {                                                  // allow:regex-no-length-cap regexInput byteLength bounded above
+        issues.push({ kind: "dangerous-html", index: i });
+        if (posture === "sanitize") t = t.replace(DANGEROUS_HTML_RE, "[REDACTED]");
+      }
+      cleaned.push({ type: "text", text: t });
+    } else if (block.type === "image" || block.type === "resource_link" || block.type === "audio") {
+      var url = block.url || (block.resource && block.resource.uri);
+      if (typeof url === "string" && url.length > 0 && allowedHosts.length > 0) {
+        var u; try { u = new URL(url); } catch (_e) { u = null; }                                // allow:raw-new-url — operator-supplied tool URL; allowlist enforced below
+        if (!u || allowedHosts.indexOf(u.host) === -1) {
+          issues.push({ kind: "off-allowlist-url", index: i, url: url });
+          if (posture === "sanitize") continue;                                                  // drop the block in sanitize mode
+        }
+      }
+      cleaned.push(block);
+    } else {
+      cleaned.push(block);
+    }
+  }
+  if (issues.length > 0 && posture === "refuse") {
+    var first = issues[0];
+    throw new McpError("mcp/tool-output-refused",
+      "toolResult.sanitize: refused " + issues.length + " issue(s) " +
+      "(first: " + first.kind + " on block[" + first.index + "])");
+  }
+  return { content: cleaned, isError: !!result.isError, issues: issues };
+}
+
+/**
+ * @primitive b.mcp.capability.create
+ * @signature b.mcp.capability.create(scopes)
+ * @since     0.8.70
+ * @related   b.mcp.serverGuard
+ *
+ * OWASP LLM08 — capability primitive. Wraps an MCP tool/resource
+ * registration with a scope set the host model's session must hold
+ * before the tool/resource is exposed. Defaults to deny-all; the
+ * operator's session-decoration step grants scopes per user / per
+ * agent / per delegated-actor.
+ *
+ * Returns `{ scopes, satisfiedBy(grantedSet) }` — the guard checks
+ * `satisfiedBy(session.capabilities)` before each tool/resource
+ * dispatch. Falsy → refuse with `mcp/capability-denied`.
+ *
+ * @example
+ *   var fileRead = b.mcp.capability.create(["fs:read"]);
+ *   if (!fileRead.satisfiedBy(session.capabilities)) {
+ *     throw new Error("mcp/capability-denied");
+ *   }
+ */
+function _capabilityCreate(scopes) {
+  if (!Array.isArray(scopes) || scopes.length === 0) {
+    throw new McpError("mcp/bad-capability",
+      "capability.create: scopes must be a non-empty array of strings");
+  }
+  scopes.forEach(function (s, i) {
+    if (typeof s !== "string" || s.length === 0) {
+      throw new McpError("mcp/bad-capability-scope",
+        "capability.create: scopes[" + i + "] must be a non-empty string");
+    }
+  });
+  var frozen = scopes.slice();
+  return {
+    scopes: frozen,
+    satisfiedBy: function (granted) {
+      if (!Array.isArray(granted)) return false;
+      for (var i = 0; i < frozen.length; i++) {
+        if (granted.indexOf(frozen[i]) === -1) return false;
+      }
+      return true;
+    },
+  };
+}
+
+/**
+ * @primitive b.mcp.validateToolInput
+ * @signature b.mcp.validateToolInput(toolName, input, schema)
+ * @since     0.8.70
+ * @related   b.mcp.serverGuard, b.safeSchema
+ *
+ * OWASP LLM07 — JSON-Schema enforcement on MCP tool inputs. Tools
+ * declare an `inputSchema` (JSON Schema 2020-12 subset) at
+ * registration; before each invocation the framework validates
+ * incoming arguments against the schema and refuses on any drift.
+ * Composes b.safeSchema for the validation engine — same primitive
+ * the OpenAPI surface uses, so the threat model is uniform.
+ *
+ * Returns the validated (possibly coerced) input object on success;
+ * throws `McpError("mcp/tool-input-invalid", ...)` on schema breach.
+ *
+ * @example
+ *   var schema = { type: "object",
+ *                  properties: { path: { type: "string" } },
+ *                  required: ["path"] };
+ *   var input = b.mcp.validateToolInput("read_file", { path: "/x" }, schema);
+ */
+// JSON-Schema-2020-12 subset validator for MCP tool inputs. The
+// MCP spec specifies tool schemas in standard JSON Schema; the
+// framework's chainable b.safeSchema is fluent-builder-shaped and
+// doesn't accept JSON Schema directly. We implement the small
+// subset MCP tools actually use:
+//   - type:        "string" | "number" | "integer" | "boolean" | "object" | "array" | "null"
+//   - required:    string[]
+//   - properties:  recursive
+//   - items:       array element schema
+//   - enum:        allowed-value list
+//   - minimum / maximum / minLength / maxLength
+//   - pattern:     regex (string types)
+// Refuses unknown JSON Schema keywords loudly so a tool-author
+// typo doesn't silently pass validation.
+function _validateValueAgainstSchema(value, schema, path) {
+  if (!schema || typeof schema !== "object") return null;
+  var t = schema.type;
+  if (Array.isArray(t)) {
+    var anyMatched = false;
+    for (var ti = 0; ti < t.length; ti++) {
+      if (_typeMatches(value, t[ti])) { anyMatched = true; break; }
+    }
+    if (!anyMatched) return path + ": expected one of " + JSON.stringify(t) + ", got " + (typeof value);
+  } else if (typeof t === "string") {
+    if (!_typeMatches(value, t)) return path + ": expected " + t + ", got " + (typeof value);
+  }
+  if (Array.isArray(schema.enum) && schema.enum.indexOf(value) === -1) {
+    return path + ": value not in enum " + JSON.stringify(schema.enum);
+  }
+  if (typeof value === "string") {
+    if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+      return path + ": string length " + value.length + " < minLength " + schema.minLength;
+    }
+    if (typeof schema.maxLength === "number" && value.length > schema.maxLength) {
+      return path + ": string length " + value.length + " > maxLength " + schema.maxLength;
+    }
+    if (typeof schema.pattern === "string") {
+      // Schema-supplied pattern — operator-controlled at registration
+      // time, not request-controlled. Cap value length first per the
+      // codebase-patterns regex-bound rule so a 10MB string doesn't
+      // ReDoS the validator.
+      if (value.length > 4096) return path + ": value exceeds 4 KiB cap before regex test";    // allow:raw-byte-literal — 4 KiB regex-input cap
+      try {
+        var pat = new RegExp(schema.pattern);                                                    // allow:dynamic-regex — schema.pattern from registered tool author, not request input; bounded above
+        if (!pat.test(value)) return path + ": does not match pattern";
+      }
+      catch (_e) { return path + ": invalid pattern in schema"; }
+    }
+  }
+  if (typeof value === "number") {
+    if (typeof schema.minimum === "number" && value < schema.minimum) return path + ": " + value + " < minimum " + schema.minimum;
+    if (typeof schema.maximum === "number" && value > schema.maximum) return path + ": " + value + " > maximum " + schema.maximum;
+  }
+  if (t === "object" && value && typeof value === "object" && !Array.isArray(value)) {
+    if (Array.isArray(schema.required)) {
+      for (var ri = 0; ri < schema.required.length; ri++) {
+        if (!Object.prototype.hasOwnProperty.call(value, schema.required[ri])) {
+          return path + ": missing required property '" + schema.required[ri] + "'";
+        }
+      }
+    }
+    if (schema.properties && typeof schema.properties === "object") {
+      var keys = Object.keys(schema.properties);
+      for (var pi = 0; pi < keys.length; pi++) {
+        var k = keys[pi];
+        if (!Object.prototype.hasOwnProperty.call(value, k)) continue;
+        var inner = _validateValueAgainstSchema(value[k], schema.properties[k], path + "." + k);
+        if (inner) return inner;
+      }
+    }
+    if (schema.additionalProperties === false) {
+      var allowed = Object.keys(schema.properties || {});
+      var keys2 = Object.keys(value);
+      for (var ki = 0; ki < keys2.length; ki++) {
+        if (allowed.indexOf(keys2[ki]) === -1) {
+          return path + ": unknown property '" + keys2[ki] + "' (additionalProperties: false)";
+        }
+      }
+    }
+  }
+  if (t === "array" && Array.isArray(value)) {
+    if (schema.items) {
+      for (var ai = 0; ai < value.length; ai++) {
+        var aInner = _validateValueAgainstSchema(value[ai], schema.items, path + "[" + ai + "]");
+        if (aInner) return aInner;
+      }
+    }
+    if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+      return path + ": array length " + value.length + " < minItems " + schema.minItems;
+    }
+    if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
+      return path + ": array length " + value.length + " > maxItems " + schema.maxItems;
+    }
+  }
+  return null;
+}
+
+function _typeMatches(value, type) {
+  switch (type) {
+    case "string":  return typeof value === "string";
+    case "number":  return typeof value === "number" && isFinite(value);
+    case "integer": return typeof value === "number" && Number.isInteger(value);
+    case "boolean": return typeof value === "boolean";
+    case "null":    return value === null;
+    case "array":   return Array.isArray(value);
+    case "object":  return value !== null && typeof value === "object" && !Array.isArray(value);
+    default:        return false;
+  }
+}
+
+function _validateToolInput(toolName, input, schema) {
+  if (typeof toolName !== "string" || toolName.length === 0) {
+    throw new McpError("mcp/bad-tool-name",
+      "validateToolInput: toolName must be a non-empty string");
+  }
+  if (!schema || typeof schema !== "object") {
+    throw new McpError("mcp/bad-tool-schema",
+      "validateToolInput: schema must be a JSON-Schema-shaped object");
+  }
+  var err = _validateValueAgainstSchema(input, schema, "$");
+  if (err) {
+    throw new McpError("mcp/tool-input-invalid",
+      "validateToolInput: tool '" + toolName + "' input " + err);
+  }
+  return input;
+}
+
 module.exports = {
   serverGuard:    serverGuard,
   parseRequest:   parseRequest,
   refuse:         refuse,
+  toolResult:     { sanitize: _toolResultSanitize },
+  capability:     { create: _capabilityCreate },
+  validateToolInput: _validateToolInput,
 };

package/lib/middleware/cors.js

@@ -202,7 +202,7 @@ function create(opts) {
   validateOpts(opts, [
     "origins", "siteOrigin", "methods", "headers", "exposeHeaders",
     "credentials", "maxAgeSeconds", "refuseUnknown", "trustProxy",
-    "strictNullOrigin",
+    "strictNullOrigin", "allowPrivateNetwork",
   ], "middleware.cors");
   var trustProxy = opts.trustProxy === true || typeof opts.trustProxy === "number"
     ? opts.trustProxy : false;
@@ -342,6 +342,28 @@ function create(opts) {
           }
         }
       }
+      // Private Network Access (PNA) preflight — Chrome's W3C draft
+      // sends `Access-Control-Request-Private-Network: true` when a
+      // public-internet page tries to fetch a private/local resource
+      // (RFC 1918 / loopback). Servers MUST acknowledge with
+      // `Access-Control-Allow-Private-Network: true` to permit. The
+      // framework refuses by default — operators with a deliberate
+      // public-to-private flow opt in via `allowPrivateNetwork: true`
+      // (audited reason) at create-time.
+      var pnaRequested = req.headers["access-control-request-private-network"];
+      if (pnaRequested === "true") {
+        if (opts.allowPrivateNetwork === true) {
+          if (typeof res.setHeader === "function") {
+            res.setHeader("Access-Control-Allow-Private-Network", "true");
+          }
+        } else {
+          if (typeof res.writeHead === "function") {
+            res.writeHead(requestHelpers.HTTP_STATUS.FORBIDDEN, { "Content-Type": "text/plain" });
+            res.end("CORS: Private Network Access not permitted (set allowPrivateNetwork:true with audited reason to opt in)");
+          }
+          return;
+        }
+      }
       if (typeof res.setHeader === "function") {
         res.setHeader("Access-Control-Allow-Methods", methods);
         res.setHeader("Access-Control-Allow-Headers", headers);

package/lib/middleware/require-aal.js

@@ -40,6 +40,8 @@ function _writeUnauthorized(res, requiredBand, actualBand, realm) {
     "Content-Type":     "application/json; charset=utf-8",
     "Content-Length":   Buffer.byteLength(body),
     "WWW-Authenticate": challenge,
+    // RFC 9111 §5.2.2.5 — auth-gated 401 must not be cached.
+    "Cache-Control":    "no-store",
   });
   res.end(body);
 }

package/lib/middleware/require-auth.js

@@ -106,10 +106,18 @@ function create(opts) {
       } catch (_e) { /* audit best-effort */ }
     }
 
+    // RFC 9111 §5.2.2.5 — auth-gated paths SHOULD emit
+    // Cache-Control: no-store so a shared cache (or browser
+    // back-button cache) can't replay a 401 / redirect / payload
+    // intended for an unauthenticated context to a different user.
+    // Pre-v0.8.70 the framework's auth middlewares emitted no
+    // cache directive, leaving the operator to set it themselves;
+    // forgetting it under a CDN that respects Cache-Control was
+    // a routine misconfiguration.
     if (prefersJson(req)) {
       if (typeof res.writeHead === "function") {
         res.writeHead(requestHelpers.HTTP_STATUS.UNAUTHORIZED,
-          { "Content-Type": "application/json" });
+          { "Content-Type": "application/json", "Cache-Control": "no-store" });
         res.end(JSON.stringify({ error: msg }));
       }
       return;
@@ -117,14 +125,14 @@ function create(opts) {
     if (redirectTo) {
       if (typeof res.writeHead === "function") {
         // 302 Found — RFC 7231 §6.4.3. Not in HTTP_STATUS table.
-        res.writeHead(302, { "Location": redirectTo });
+        res.writeHead(302, { "Location": redirectTo, "Cache-Control": "no-store" });
         res.end();
       }
       return;
     }
     if (typeof res.writeHead === "function") {
       res.writeHead(requestHelpers.HTTP_STATUS.UNAUTHORIZED,
-        { "Content-Type": "text/plain" });
+        { "Content-Type": "text/plain", "Cache-Control": "no-store" });
       res.end(msg);
     }
   };

package/lib/middleware/require-step-up.js

@@ -71,6 +71,9 @@ function _writeChallenge(res, challenge, body, statusCode) {
     "Content-Type":     "application/json; charset=utf-8",
     "Content-Length":   Buffer.byteLength(json),
     "WWW-Authenticate": challenge,
+    // RFC 9111 §5.2.2.5 — auth-gated step-up challenge must not
+    // be cached (CDN replay defense).
+    "Cache-Control":    "no-store",
   });
   res.end(json);
 }

package/lib/middleware/security-headers.js

@@ -57,6 +57,20 @@ var DEFAULT_PERMISSIONS = [
   "bluetooth=()", "hid=()", "serial=()", "idle-detection=()",
   "local-fonts=()", "compute-pressure=()", "window-management=()",
   "private-state-token-issuance=()", "private-state-token-redemption=()",
+  // v0.8.70 expansion — Privacy-Sandbox + Storage Access feature
+  // names that landed in Chrome 119+/120+ stable. Default-deny:
+  //   - storage-access — Storage Access API (cross-site cookie
+  //     access flow under Privacy Sandbox); operators serving an
+  //     embedded-iframe SaaS opt in explicitly.
+  //   - browsing-topics — Topics API (replacement for FLoC);
+  //     enabled by default in Chrome but trackable surface, so
+  //     deny-by-default unless the operator opts in.
+  //   - private-aggregation, attribution-reporting-cross-site —
+  //     Privacy Sandbox aggregation APIs; deny-by-default.
+  //   - controlled-frame, captured-surface-control — Web App
+  //     embedding APIs; deny-by-default.
+  "storage-access=()", "browsing-topics=()",
+  "private-aggregation=()", "controlled-frame=()", "captured-surface-control=()",
 ];
 
 // Strict CSP — no 'unsafe-inline' on script-src OR style-src.

package/package.json

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

package/sbom.cyclonedx.json

@@ -1,11 +1,11 @@
 {
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
-  "specVersion": "1.5",
-  "serialNumber": "urn:uuid:cf3aa594-6a94-4be5-9952-a87c315ec5eb",
+  "specVersion": "1.6",
+  "serialNumber": "urn:uuid:f0ffa661-b4d1-401c-947f-756e1acef7ed",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-10T15:19:22.438Z",
+    "timestamp": "2026-05-10T19:03:05.252Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.8.69",
+      "bom-ref": "@blamejs/core@0.8.71",
       "type": "library",
       "name": "blamejs",
-      "version": "0.8.69",
+      "version": "0.8.71",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.8.69",
+      "purl": "pkg:npm/%40blamejs/core@0.8.71",
       "properties": [],
       "externalReferences": [
         {
@@ -54,8 +54,8 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.8.69",
+      "ref": "@blamejs/core@0.8.71",
       "dependsOn": []
     }
   ]
-}
+}