@blamejs/core 0.8.76 → 0.8.78

package/lib/mcp.js

@@ -694,11 +694,244 @@ function _validateToolInput(toolName, input, schema) {
   return input;
 }
 
+// ---- MCP 2025-11-25 spec — sampling / elicitation / protocol version ----
+
+var MCP_PROTOCOL_VERSIONS_ACCEPTED = ["2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25"];
+
+/**
+ * @primitive b.mcp.assertProtocolVersion
+ * @signature b.mcp.assertProtocolVersion(req, opts?)
+ * @since     0.8.77
+ * @related   b.mcp.serverGuard
+ *
+ * MCP 2025-11-25 spec §4.1 — every HTTP request after `initialize`
+ * MUST carry an `MCP-Protocol-Version` header naming a version the
+ * server supports. Returns the resolved version on success; throws
+ * with a tagged refusal when the header is missing OR names an
+ * unsupported version. Clients pre-negotiation (before `initialize`)
+ * may omit the header — the resolved value is `null` in that case.
+ *
+ * @opts
+ *   {
+ *     accepted?:  string[],   // override the default acceptance set
+ *     allowMissing?: boolean, // true → return null when header absent
+ *   }
+ *
+ * @example
+ *   var version = b.mcp.assertProtocolVersion(req, { allowMissing: false });
+ *   // throws if missing/unsupported; returns e.g. "2025-11-25" on success.
+ */
+function _assertProtocolVersion(req, opts) {
+  opts = opts || {};
+  var accepted = Array.isArray(opts.accepted) && opts.accepted.length > 0
+    ? opts.accepted : MCP_PROTOCOL_VERSIONS_ACCEPTED;
+  var hdr = req && req.headers && req.headers["mcp-protocol-version"];
+  if (typeof hdr !== "string" || hdr.length === 0) {
+    if (opts.allowMissing === true) return null;
+    throw new McpError("mcp/missing-protocol-version",
+      "assertProtocolVersion: request missing MCP-Protocol-Version header " +
+      "(MCP 2025-11-25 §4.1 requires it on every post-initialize request)");
+  }
+  if (accepted.indexOf(hdr) === -1) {
+    throw new McpError("mcp/unsupported-protocol-version",
+      "assertProtocolVersion: '" + hdr + "' not in accepted set: " +
+      accepted.join(", "));
+  }
+  return hdr;
+}
+
+var SAMPLING_DEFAULTS = {
+  maxRequestsPerSession:   10,
+  maxMessagesPerRequest:   20,
+  maxTokensPerRequest:     4096,                  // allow:raw-byte-literal — LLM token count, not bytes
+  allowedModelHint:        null,    // null = allow all
+  refuseStopSequences:     false,
+};
+
+/**
+ * @primitive b.mcp.sampling.guard
+ * @signature b.mcp.sampling.guard(opts?)
+ * @since     0.8.77
+ * @related   b.mcp.toolResult.sanitize
+ *
+ * MCP server-initiated `sampling/createMessage` gate — the highest-
+ * risk surface in the protocol. A compromised tool can issue
+ * `sampling/createMessage` to make the host model emit attacker-
+ * chosen text. This primitive returns a guard function the operator
+ * wraps around the sampling endpoint that refuses requests violating
+ * size caps, allow-listed models, or budget-per-session.
+ *
+ * Returns `{ enforce(samplingRequest, sessionId), reset(sessionId) }`.
+ * `enforce` throws on violation; the operator wraps the actual model
+ * call only after `enforce` returns.
+ *
+ * @opts
+ *   {
+ *     maxRequestsPerSession?: number,   // default 10
+ *     maxMessagesPerRequest?: number,   // default 20
+ *     maxTokensPerRequest?:   number,   // default 4096
+ *     allowedModelHints?:     string[], // null → allow all
+ *     refuseStopSequences?:   boolean,  // refuse client-supplied stop sequences
+ *   }
+ *
+ * @example
+ *   var guard = b.mcp.sampling.guard({ maxRequestsPerSession: 5 });
+ *   server.on("sampling/createMessage", function (req, sid) {
+ *     guard.enforce(req, sid);     // throws on violation
+ *     return invokeModel(req);
+ *   });
+ */
+function _samplingGuard(opts) {
+  opts = opts || {};
+  var maxReq    = opts.maxRequestsPerSession || SAMPLING_DEFAULTS.maxRequestsPerSession;
+  var maxMsg    = opts.maxMessagesPerRequest || SAMPLING_DEFAULTS.maxMessagesPerRequest;
+  var maxTokens = opts.maxTokensPerRequest   || SAMPLING_DEFAULTS.maxTokensPerRequest;
+  var allowedModels  = Array.isArray(opts.allowedModelHints) ? opts.allowedModelHints.slice() : null;
+  var refuseStop     = opts.refuseStopSequences === true;
+  var sessionCounts  = new Map();
+
+  function enforce(samplingRequest, sessionId) {
+    if (!samplingRequest || typeof samplingRequest !== "object") {
+      throw new McpError("mcp/sampling-bad-request",
+        "sampling.guard: request must be an object");
+    }
+    var sid = sessionId || "_anonymous";
+    var n = (sessionCounts.get(sid) || 0) + 1;
+    if (n > maxReq) {
+      throw new McpError("mcp/sampling-session-budget-exceeded",
+        "sampling.guard: session '" + sid + "' exceeded " + maxReq + " sampling requests");
+    }
+    sessionCounts.set(sid, n);
+    var messages = samplingRequest.messages;
+    if (!Array.isArray(messages) || messages.length === 0) {
+      throw new McpError("mcp/sampling-no-messages",
+        "sampling.guard: request.messages must be a non-empty array");
+    }
+    if (messages.length > maxMsg) {
+      throw new McpError("mcp/sampling-too-many-messages",
+        "sampling.guard: " + messages.length + " messages > maxMessagesPerRequest=" + maxMsg);
+    }
+    if (typeof samplingRequest.maxTokens === "number" && samplingRequest.maxTokens > maxTokens) {
+      throw new McpError("mcp/sampling-too-many-tokens",
+        "sampling.guard: requested maxTokens " + samplingRequest.maxTokens +
+        " > cap " + maxTokens);
+    }
+    if (refuseStop && samplingRequest.stopSequences) {
+      throw new McpError("mcp/sampling-stop-sequences-refused",
+        "sampling.guard: client-supplied stopSequences refused by policy");
+    }
+    if (allowedModels && samplingRequest.modelPreferences &&
+        samplingRequest.modelPreferences.hints) {
+      var hints = samplingRequest.modelPreferences.hints;
+      if (Array.isArray(hints)) {
+        hints.forEach(function (h, i) {
+          if (h && typeof h.name === "string" && allowedModels.indexOf(h.name) === -1) {
+            throw new McpError("mcp/sampling-model-not-allowed",
+              "sampling.guard: modelPreferences.hints[" + i + "].name='" + h.name +
+              "' not in allowedModelHints: " + allowedModels.join(", "));
+          }
+        });
+      }
+    }
+  }
+
+  function reset(sessionId) {
+    if (sessionId) sessionCounts.delete(sessionId);
+    else           sessionCounts.clear();
+  }
+
+  return { enforce: enforce, reset: reset };
+}
+
+/**
+ * @primitive b.mcp.elicitation.guard
+ * @signature b.mcp.elicitation.guard(opts?)
+ * @since     0.8.77
+ * @related   b.mcp.sampling.guard
+ *
+ * MCP 2025-11-25 `elicitation/create` gate — server-initiated user
+ * prompt requests. Refuses prompts whose `message` contains
+ * prompt-injection markers OR `requestedSchema` shape is missing.
+ * The risk class is symmetric to `sampling`: a compromised tool can
+ * elicit credentials / approval-text from the user. This guard
+ * applies the same prompt-injection scan `toolResult.sanitize` does,
+ * plus an allow-listed `requestedSchema.type` set.
+ *
+ * @opts
+ *   {
+ *     maxMessageBytes?:   number,   // default 8 KiB
+ *     allowedSchemaTypes?: string[], // default ["object"]
+ *     posture?: "refuse" | "sanitize" | "audit-only",
+ *   }
+ *
+ * @example
+ *   var guard = b.mcp.elicitation.guard({ posture: "refuse" });
+ *   guard.enforce({
+ *     message: "What's your name?",
+ *     requestedSchema: { type: "object", properties: { name: { type: "string" } } },
+ *   });
+ */
+function _elicitationGuard(opts) {
+  opts = opts || {};
+  var maxBytes    = opts.maxMessageBytes || (8 * 1024);                                          // allow:raw-byte-literal — 8 KiB elicitation message cap
+  var allowedSchemaTypes = Array.isArray(opts.allowedSchemaTypes) && opts.allowedSchemaTypes.length > 0
+    ? opts.allowedSchemaTypes : ["object"];
+  var posture     = opts.posture || "refuse";
+
+  function enforce(elicitRequest) {
+    if (!elicitRequest || typeof elicitRequest !== "object") {
+      throw new McpError("mcp/elicitation-bad-request",
+        "elicitation.guard: request must be an object");
+    }
+    var message = elicitRequest.message;
+    if (typeof message !== "string" || message.length === 0) {
+      throw new McpError("mcp/elicitation-no-message",
+        "elicitation.guard: request.message must be a non-empty string");
+    }
+    if (Buffer.byteLength(message, "utf8") > maxBytes) {
+      throw new McpError("mcp/elicitation-message-too-large",
+        "elicitation.guard: message exceeds " + maxBytes + " bytes");
+    }
+    var schema = elicitRequest.requestedSchema;
+    if (!schema || typeof schema !== "object") {
+      throw new McpError("mcp/elicitation-no-schema",
+        "elicitation.guard: request.requestedSchema must be an object");
+    }
+    if (allowedSchemaTypes.indexOf(schema.type) === -1) {
+      throw new McpError("mcp/elicitation-bad-schema-type",
+        "elicitation.guard: requestedSchema.type '" + schema.type +
+        "' not in allowed: " + allowedSchemaTypes.join(", "));
+    }
+    // Prompt-injection scan over the prompt-to-user message.
+    var regexInput = Buffer.byteLength(message, "utf8") > maxBytes
+      ? Buffer.from(message, "utf8").subarray(0, maxBytes).toString("utf8")
+      : message;
+    if (INJECTION_RE.test(regexInput)) {                                                          // allow:regex-no-length-cap regexInput byteLength bounded above
+      if (posture === "refuse") {
+        throw new McpError("mcp/elicitation-injection-refused",
+          "elicitation.guard: message contains prompt-injection markers");
+      }
+      if (posture === "sanitize") {
+        return Object.assign({}, elicitRequest, {
+          message: message.replace(INJECTION_RE, "[REDACTED]"),
+        });
+      }
+    }
+    return elicitRequest;
+  }
+
+  return { enforce: enforce };
+}
+
 module.exports = {
-  serverGuard:    serverGuard,
-  parseRequest:   parseRequest,
-  refuse:         refuse,
-  toolResult:     { sanitize: _toolResultSanitize },
-  capability:     { create: _capabilityCreate },
-  validateToolInput: _validateToolInput,
+  serverGuard:        serverGuard,
+  parseRequest:       parseRequest,
+  refuse:             refuse,
+  toolResult:         { sanitize: _toolResultSanitize },
+  capability:         { create: _capabilityCreate },
+  validateToolInput:  _validateToolInput,
+  assertProtocolVersion: _assertProtocolVersion,
+  sampling:           { guard: _samplingGuard },
+  elicitation:        { guard: _elicitationGuard },
+  MCP_PROTOCOL_VERSIONS_ACCEPTED: MCP_PROTOCOL_VERSIONS_ACCEPTED,
 };

package/lib/middleware/index.js

@@ -64,6 +64,8 @@ var traceLogCorrelation = require("./trace-log-correlation");
 var tracePropagate = require("./trace-propagate");
 var tusUpload = require("./tus-upload");
 var webAppManifest = require("./web-app-manifest");
+var protectedResourceMetadata = require("./protected-resource-metadata");
+var scimServer = require("./scim-server");
 
 module.exports = {
   requestId:        requestId.create,
@@ -114,6 +116,8 @@ module.exports = {
   clearSiteData:    clearSiteData.create,
   nel:              nel.create,
   speculationRules: speculationRules.create,
+  protectedResourceMetadata: protectedResourceMetadata.create,
+  scimServer:       scimServer.create,
 
   // Module exports for advanced use (constants, raw factory access)
   _modules: {

package/lib/middleware/protected-resource-metadata.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * @module     b.middleware.protectedResourceMetadata
+ * @nav        Identity & access
+ * @title      Protected Resource Metadata
+ * @order      210
+ * @slug       protected-resource-metadata
+ *
+ * @intro
+ *   draft-ietf-oauth-resource-metadata: serves the
+ *   `/.well-known/oauth-protected-resource` document so RFC 9728
+ *   clients can auto-discover which authorization servers issue
+ *   tokens for this resource, what scopes the resource accepts,
+ *   what dpop algorithms the resource verifies, and which bearer-
+ *   method binding (DPoP / mTLS cnf claim) is required. Pairs with
+ *   b.middleware.bearerAuth so a 401 from the protected resource
+ *   includes `WWW-Authenticate: Bearer resource_metadata=<url>` and
+ *   the client can self-rediscover.
+ *
+ * @card
+ *   `.well-known/oauth-protected-resource` discovery endpoint per
+ *   draft-ietf-oauth-resource-metadata. Closes the gap that previously
+ *   forced operators to hand-write the JSON.
+ */
+
+var framework_error = require("../framework-error");
+var validateOpts    = require("../validate-opts");
+var requestHelpers  = require("../request-helpers");
+
+var H = requestHelpers.HTTP_STATUS;
+
+var ProtectedResourceMetadataError = framework_error.defineClass(
+  "ProtectedResourceMetadataError",
+  "middleware/protected-resource-metadata"
+);
+
+var ALLOWED_BEARER_METHODS  = ["header", "body", "query"];
+var ALLOWED_DPOP_ALGS       = ["ES256", "ES384", "RS256", "PS256", "EdDSA", "ML-DSA-65", "ML-DSA-87"];
+
+/**
+ * @primitive b.middleware.protectedResourceMetadata
+ * @signature b.middleware.protectedResourceMetadata(opts)
+ * @since     0.8.77
+ * @related   b.auth.oauth.introspectToken, b.middleware.bearerAuth
+ *
+ * Returns a request middleware that serves the protected-resource
+ * metadata JSON document at `/.well-known/oauth-protected-resource`
+ * (or operator-overridden path).
+ *
+ * @opts
+ *   {
+ *     resource:                       string,        // canonical resource URI (required)
+ *     authorizationServers:           string[],      // issuer URLs that mint tokens for this resource (required, ≥1)
+ *     scopesSupported?:               string[],
+ *     bearerMethodsSupported?:        ("header"|"body"|"query")[],   // default ["header"]
+ *     resourceSigningAlgValuesSupported?: string[], // for signed introspection / jwt-secured responses
+ *     resourceDocumentation?:         string,        // URL to operator docs
+ *     resourcePolicyUri?:             string,
+ *     resourceTosUri?:                string,
+ *     dpopSigningAlgValuesSupported?: string[],
+ *     dpopBoundAccessTokensRequired?: boolean,
+ *     mtlsBoundAccessTokensRequired?: boolean,
+ *     path?:                          string,        // default "/.well-known/oauth-protected-resource"
+ *   }
+ *
+ * @example
+ *   var mw = b.middleware.protectedResourceMetadata({
+ *     resource:             "https://api.example.com",
+ *     authorizationServers: ["https://idp.example.com"],
+ *     scopesSupported:      ["read", "write"],
+ *     dpopBoundAccessTokensRequired: true,
+ *   });
+ *   app.use(mw);
+ */
+function create(opts) {
+  validateOpts.requireObject(opts, "middleware.protectedResourceMetadata",
+    ProtectedResourceMetadataError, "middleware/protected-resource-metadata/bad-opts");
+  validateOpts.requireNonEmptyString(opts.resource, "resource",
+    ProtectedResourceMetadataError, "middleware/protected-resource-metadata/no-resource");
+
+  if (!Array.isArray(opts.authorizationServers) || opts.authorizationServers.length === 0) {
+    throw new ProtectedResourceMetadataError(
+      "middleware/protected-resource-metadata/no-as",
+      "authorizationServers must be a non-empty array of issuer URLs");
+  }
+  opts.authorizationServers.forEach(function (u, i) {
+    if (typeof u !== "string" || u.length === 0) {
+      throw new ProtectedResourceMetadataError(
+        "middleware/protected-resource-metadata/bad-as",
+        "authorizationServers[" + i + "] must be a non-empty string");
+    }
+  });
+
+  var bearerMethods = opts.bearerMethodsSupported || ["header"];
+  bearerMethods.forEach(function (m, i) {
+    if (ALLOWED_BEARER_METHODS.indexOf(m) === -1) {
+      throw new ProtectedResourceMetadataError(
+        "middleware/protected-resource-metadata/bad-bearer-method",
+        "bearerMethodsSupported[" + i + "] must be one of: " + ALLOWED_BEARER_METHODS.join(", "));
+    }
+  });
+
+  if (opts.dpopSigningAlgValuesSupported) {
+    opts.dpopSigningAlgValuesSupported.forEach(function (a, i) {
+      if (ALLOWED_DPOP_ALGS.indexOf(a) === -1) {
+        throw new ProtectedResourceMetadataError(
+          "middleware/protected-resource-metadata/bad-dpop-alg",
+          "dpopSigningAlgValuesSupported[" + i + "] = '" + a +
+          "' not in allowlist: " + ALLOWED_DPOP_ALGS.join(", "));
+      }
+    });
+  }
+
+  var path = opts.path || "/.well-known/oauth-protected-resource";
+
+  var doc = {
+    resource:                opts.resource,
+    authorization_servers:   opts.authorizationServers,
+    bearer_methods_supported: bearerMethods,
+  };
+  if (opts.scopesSupported)                       doc.scopes_supported = opts.scopesSupported;
+  if (opts.resourceSigningAlgValuesSupported)     doc.resource_signing_alg_values_supported = opts.resourceSigningAlgValuesSupported;
+  if (opts.resourceDocumentation)                 doc.resource_documentation = opts.resourceDocumentation;
+  if (opts.resourcePolicyUri)                     doc.resource_policy_uri = opts.resourcePolicyUri;
+  if (opts.resourceTosUri)                        doc.resource_tos_uri = opts.resourceTosUri;
+  if (opts.dpopSigningAlgValuesSupported)         doc.dpop_signing_alg_values_supported = opts.dpopSigningAlgValuesSupported;
+  if (opts.dpopBoundAccessTokensRequired === true) doc.dpop_bound_access_tokens_required = true;
+  if (opts.mtlsBoundAccessTokensRequired === true) doc.tls_client_certificate_bound_access_tokens = true;
+
+  var bodyText  = JSON.stringify(doc);
+  var bodyBytes = Buffer.byteLength(bodyText, "utf8");
+
+  function middleware(req, res, next) {
+    if (req.url !== path && req.url.split("?")[0] !== path) {
+      next();
+      return;
+    }
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      res.writeHead(H.METHOD_NOT_ALLOWED, {
+        "Allow":         "GET, HEAD",
+        "Cache-Control": "no-store",
+      });
+      res.end();
+      return;
+    }
+    res.writeHead(H.OK, {
+      "Content-Type":   "application/json",
+      "Content-Length": String(bodyBytes),
+      "Cache-Control":  "public, max-age=3600",
+    });
+    if (req.method === "HEAD") { res.end(); return; }
+    res.end(bodyText);
+  }
+
+  middleware.document = doc;
+  middleware.path     = path;
+  return middleware;
+}
+
+module.exports = {
+  create:                        create,
+  ProtectedResourceMetadataError: ProtectedResourceMetadataError,
+  ALLOWED_BEARER_METHODS:        ALLOWED_BEARER_METHODS,
+  ALLOWED_DPOP_ALGS:             ALLOWED_DPOP_ALGS,
+};

package/lib/middleware/rate-limit.js

@@ -159,12 +159,16 @@ function _memoryTokenBucketBackend(opts) {
     buckets.delete(key);
   }
 
+  function resetAll() {
+    buckets.clear();
+  }
+
   function close() {
     try { gcInterval.stop(); } catch (_e) { /* timer already stopped */ }
     buckets.clear();
   }
 
-  return { take: take, reset: reset, close: close };
+  return { take: take, reset: reset, resetAll: resetAll, close: close };
 }
 
 // Fixed-window in-memory algorithm — per-key counter that resets at the
@@ -224,12 +228,14 @@ function _memoryFixedWindowBackend(opts) {
 
   function reset(key) { counters.delete(key); }
 
+  function resetAll() { counters.clear(); }
+
   function close() {
     try { gcInterval.stop(); } catch (_e) { /* timer already stopped */ }
     counters.clear();
   }
 
-  return { take: take, reset: reset, close: close };
+  return { take: take, reset: reset, resetAll: resetAll, close: close };
 }
 
 // ---- Cluster backend (fixed-window counter, SQL-backed) ----
@@ -485,13 +491,63 @@ function create(opts) {
 
   // Expose a couple of operator hooks on the middleware function.
   middleware.reset = function (key) { return backend.reset(key); };
-  middleware.close = function ()    { return backend.close && backend.close(); };
+  // Global drop-all for the in-memory backend. Used by incident-
+  // response workflows ("operator confirmed false-positive lockout
+  // wave, drop the whole table") + by test suites that need a clean
+  // slate between cases without re-creating the middleware. For the
+  // cluster backend this is a no-op (cluster backends are
+  // multi-process and require operator-side coordination — flushing
+  // a shared row table from one replica races every other replica's
+  // in-flight take() calls).
+  middleware.resetAll = function () {
+    if (typeof backend.resetAll === "function") return backend.resetAll();
+    return null;
+  };
+  middleware.close = function () {
+    _instances.delete(middleware);
+    return backend.close && backend.close();
+  };
 
+  _instances.add(middleware);
   return middleware;
 }
 
+// Module-level registry of every rate-limit middleware in the running
+// process. Operators reach for this during incident response: when a
+// false-positive lockout wave hits, an oncall script can iterate
+// `instances()` and call `.resetAll()` on each, without having to
+// thread a reference to every rate-limit middleware through wherever
+// the response code runs. Tests use it to assert a clean slate.
+//
+// Lifetime: a middleware joins on `create()` return and leaves on
+// `middleware.close()`. Long-lived servers create rate-limiters once at
+// boot; throwaway middlewares (tests, sandboxes) must close() to
+// deregister. We deliberately don't use WeakRef here — operators want
+// strong, observable membership ("did this rate-limiter actually get
+// created?"), and the count is bounded by how many limiters an app
+// configures, not how much traffic it sees.
+var _instances = new Set();
+
+function instances() {
+  return Array.from(_instances);
+}
+
+// Global drop-all across every middleware in the process. Returns the
+// number of instances that responded to resetAll (cluster-backed
+// middlewares no-op their own resetAll but still count toward the
+// total so operators see all instances were addressed).
+function resetAll() {
+  var n = 0;
+  _instances.forEach(function (m) {
+    try { m.resetAll(); n += 1; } catch (_e) { /* best-effort */ }
+  });
+  return n;
+}
+
 module.exports = {
   create:           create,
+  instances:        instances,
+  resetAll:         resetAll,
   // Backends exported for tests + advanced operator wiring.
   _memoryBackend:              _memoryBackend,
   _memoryTokenBucketBackend:   _memoryTokenBucketBackend,