@cyanmycelium/mcp-broker 1.2.0 → 1.3.0

package/dist/index.js

@@ -1,3 +1,3 @@
-export { AuthError, BROKER_PROVIDER_NAME, BrokerInfoBehavior, BrokerProvidersBehavior, ConfigPolicyEngine, ConfiguredCapabilityClassifier, DEFAULT_CONFIG_FILENAME, DefaultSlotResourceResolver, HttpAuthGuard, JwtSubjectMapper, JwtTokenValidator, PACKAGE_NAME, RemoteUpstream, ResourcePath, ResourcePathPattern, SharedSecretProviderAuthenticator, StdioUpstream, SubjectMappingError, VERSION, WsTunnel, WsTunnelBuilder, authorizationWithEngine, brokerGrammarKey, buildJwtAuth, buildResourceMetadata, compileAuthorizationPolicy, hasAuthorizationPolicies, iterAvailableBrokerGrammars, iterBrokerGrammarsFrom, loadBrokerConfig, loadBrokerGrammar, loadMcpbBundle, normalizeProviderAuthentication, providerMayPublish, scopesOf, startBrokerServer, unzipMcpb, validateCapability } from './chunk-FTDKH2C4.js';
+export { AuthError, BROKER_AGGREGATE_NAME, BROKER_GUIDES, BROKER_GUIDE_MIME_TYPE, BROKER_GUIDE_TOPICS, BROKER_GUIDE_URI_PREFIX, BROKER_GUIDE_URI_TEMPLATE, BROKER_PROVIDER_NAME, BROKER_RESERVED_SLOTS, BrokerDiagnoseAdapter, BrokerDiagnoseBehavior, BrokerGuideAdapter, BrokerGuideBehavior, BrokerInfoBehavior, BrokerProvidersBehavior, ConfigPolicyEngine, ConfiguredCapabilityClassifier, DEFAULT_CONFIG_FILENAME, DefaultSlotResourceResolver, HttpAuthGuard, JwtSubjectMapper, JwtTokenValidator, PACKAGE_NAME, RemoteUpstream, ResourcePath, ResourcePathPattern, SharedSecretProviderAuthenticator, StdioUpstream, SubjectMappingError, VERSION, WsTunnel, WsTunnelBuilder, authorizationWithEngine, brokerGrammarKey, brokerGuide, brokerGuideIndex, brokerGuideTopicFromUri, brokerGuideUri, buildJwtAuth, buildResourceMetadata, compileAuthorizationPolicy, compileProviderAllowedResources, diagnoseBroker, hasAuthorizationPolicies, isReservedBrokerSlot, iterAvailableBrokerGrammars, iterBrokerGrammarsFrom, loadBrokerConfig, loadBrokerGrammar, loadMcpbBundle, normalizeProviderAuthentication, providerMayPublish, providerPublishDecision, resolveOpenTarget, scopesOf, startBrokerServer, unzipMcpb, validateCapability } from './chunk-BZUZYXVA.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cyanmycelium/mcp-broker",
-    "version": "1.2.0",
+    "version": "1.3.0",
     "description": "WebSocket-based Model Context Protocol broker. Aggregates multiple MCP providers behind a single endpoint with stdio, SSE, and Streamable HTTP client transports.",
     "type": "module",
     "license": "Apache-2.0",
@@ -68,13 +68,13 @@
         "prepublishOnly": "npm run lint && npm run build && npm test"
     },
     "dependencies": {
-        "@cyanmycelium/mcp-core": "^0.7.0",
+        "@cyanmycelium/mcp-core": "^1.0.0",
         "jose": "^6.2.3",
         "open": "^11.0.0",
         "ws": "^8.18.0"
     },
     "devDependencies": {
-        "@cyanmycelium/mcp-broker-provider": "^0.1.0",
+        "@cyanmycelium/mcp-broker-provider": "^0.2.0",
         "@types/node": "^20.11.0",
         "@types/ws": "^8.5.0",
         "@typescript-eslint/eslint-plugin": "^7.0.0",

package/src/auth/index.ts

@@ -23,12 +23,14 @@ export { HttpAuthGuard } from "./http.auth";
 export { buildJwtAuth } from "./auth.config";
 export type { IJwtAuthOptions, JwtAuthOptions } from "./auth.config";
 export { SharedSecretProviderAuthenticator } from "./provider.auth";
-export { normalizeProviderAuthentication, providerMayPublish } from "./provider.auth";
+export { compileProviderAllowedResources, normalizeProviderAuthentication, providerMayPublish, providerPublishDecision } from "./provider.auth";
 export type {
     IProviderAuthenticator,
     IProviderPrincipal,
+    IProviderPublishDecision,
     ProviderAuthenticationResult,
     ProviderAuthenticator,
     ProviderAuthenticatorReturn,
     ProviderPrincipal,
+    ProviderPublishDenialReason,
 } from "./provider.auth";

package/src/auth/provider.auth.ts

@@ -40,16 +40,134 @@ export function normalizeProviderAuthentication(result: ProviderAuthenticatorRet
     return result;
 }
 
-export function providerMayPublish(principal: IProviderPrincipal, resource: ResourcePath): boolean {
-    const allowed = principal.allowedResources;
-    if (allowed === undefined) return true;
-    if (allowed.length === 0) return false;
+/** Wording shared by every "this pattern is not valid" diagnostic. */
+const PATTERN_SYNTAX_HINT = 'Resource patterns are absolute and segment-based: "/enterprise/**", "/enterprise/*/line-3", "/enterprise/site-a/asset", or "**" for everything.';
+
+/**
+ * Compiled `allowedResources` patterns, keyed by the exact pattern string, with
+ * the compile failure cached alongside the successes.
+ *
+ * {@link providerMayPublish} runs on every provider WebSocket upgrade, and the
+ * previous per-call `ResourcePathPattern.parse` inside a `try` meant a single
+ * typo re-threw on every registration and was mapped to a bare `false`. Caching
+ * the outcome makes the parse happen once per distinct pattern and gives the
+ * failure a stable identity we can report exactly once.
+ */
+const compiledPatterns = new Map<string, ResourcePathPattern | Error>();
+
+/** Malformed-pattern reports already emitted, so a wedged config logs once. */
+const reportedMalformedPatterns = new Set<string>();
+
+/** Parses one pattern, memoizing both the success and the failure. */
+function compilePattern(pattern: string): ResourcePathPattern | Error {
+    const cached = compiledPatterns.get(pattern);
+    if (cached !== undefined) return cached;
+    let compiled: ResourcePathPattern | Error;
     try {
-        const patterns = allowed.map((pattern) => ResourcePathPattern.parse(pattern));
-        return patterns.some((pattern) => pattern.matches(resource));
-    } catch {
-        return false;
+        compiled = ResourcePathPattern.parse(pattern);
+    } catch (error) {
+        compiled = error instanceof Error ? error : new Error(String(error));
+    }
+    compiledPatterns.set(pattern, compiled);
+    return compiled;
+}
+
+/** Why a provider was refused a slot. `undefined` when it was allowed. */
+export type ProviderPublishDenialReason = "no-allowed-resources" | "out-of-namespace" | "malformed-pattern";
+
+/** The outcome of a provider namespace check, with the cause when it denies. */
+export interface IProviderPublishDecision {
+    readonly allowed: boolean;
+    /** Machine-readable cause, present only when `allowed` is `false`. */
+    readonly reason?: ProviderPublishDenialReason;
+    /** Operator-facing explanation that already names the fix. */
+    readonly detail?: string;
+}
+
+/**
+ * Compiles a principal's `allowedResources`, throwing on the first malformed
+ * pattern with the offending pattern quoted in the message.
+ *
+ * Call this wherever a provider principal is *built* (config load, a custom
+ * authenticator's constructor) so a typo fails the broker at startup instead of
+ * silently 403-ing every provider on that principal forever.
+ * {@link providerPublishDecision} deliberately does not throw: it runs inside the
+ * WebSocket upgrade, where the only safe answer to "is this pattern valid?" is
+ * to deny loudly.
+ */
+export function compileProviderAllowedResources(allowed: readonly string[], label = "provider allowedResources"): readonly ResourcePathPattern[] {
+    return allowed.map((pattern) => {
+        const compiled = compilePattern(pattern);
+        if (compiled instanceof Error) {
+            throw new Error(`${label}: "${pattern}" is not a valid resource pattern: ${compiled.message} ${PATTERN_SYNTAX_HINT}`);
+        }
+        return compiled;
+    });
+}
+
+/**
+ * Decides whether a provider principal may claim `resource`, and says why when
+ * it may not.
+ *
+ * Every denial here surfaces to the provider as a bare 403 at the WebSocket
+ * handshake, which a browser reports as a contentless error event. The reason is
+ * therefore the only thing an operator (or an agent wiring this up) has to work
+ * from, so it is returned to the caller for the registration log and, for the
+ * configuration-fault case, logged here as well.
+ */
+export function providerPublishDecision(principal: IProviderPrincipal, resource: ResourcePath): IProviderPublishDecision {
+    const allowed = principal.allowedResources;
+    if (allowed === undefined) return { allowed: true };
+    if (allowed.length === 0) {
+        return {
+            allowed: false,
+            reason: "no-allowed-resources",
+            detail:
+                `Provider principal "${principal.id}" has an empty allowedResources list, which forbids every slot. ` +
+                `Remove the key entirely to allow all slots, or list the namespaces this principal may publish, for example ["/enterprise/**"].`,
+        };
+    }
+
+    const patterns: ResourcePathPattern[] = [];
+    const malformed: string[] = [];
+    for (const pattern of allowed) {
+        const compiled = compilePattern(pattern);
+        if (compiled instanceof Error) malformed.push(`"${pattern}" (${compiled.message})`);
+        else patterns.push(compiled);
     }
+
+    if (malformed.length > 0) {
+        const detail =
+            `Provider principal "${principal.id}" carries ${malformed.length} malformed allowedResources pattern(s): ${malformed.join("; ")} ` +
+            `Every provider registration on this principal is refused with 403 until they are fixed, whatever slot it asks for. ${PATTERN_SYNTAX_HINT}`;
+        // Loud, but once per (principal, bad pattern set): this is a
+        // startup-class configuration fault the broker can never honor, and its
+        // request-time symptom is a 403 that names nothing.
+        const key = `${principal.id}|${malformed.join("|")}`;
+        if (!reportedMalformedPatterns.has(key)) {
+            reportedMalformedPatterns.add(key);
+            console.error(`[broker] provider auth: ${detail}`);
+        }
+        return { allowed: false, reason: "malformed-pattern", detail };
+    }
+
+    if (patterns.some((pattern) => pattern.matches(resource))) return { allowed: true };
+    return {
+        allowed: false,
+        reason: "out-of-namespace",
+        detail:
+            `Provider principal "${principal.id}" may not publish resource "${resource.value}": it is outside allowedResources [${allowed.join(", ")}]. ` +
+            `Either connect the provider to a slot inside one of those namespaces, or widen allowedResources for this principal.`,
+    };
+}
+
+/**
+ * Boolean form of {@link providerPublishDecision}, kept for callers that only
+ * need the verdict. Prefer the decision form so the refusal can be logged with
+ * its cause.
+ */
+export function providerMayPublish(principal: IProviderPrincipal, resource: ResourcePath): boolean {
+    return providerPublishDecision(principal, resource).allowed;
 }
 
 /** Constant-time string comparison; `false` on any length mismatch. */

package/src/authorization/policy.engine.ts

@@ -172,8 +172,17 @@ export class ConfigPolicyEngine implements IPolicyEngine {
         if (!request.resource) return { allowed: false, reason: "invalid-resource" };
         try {
             validateCapability(request.capability, "request capability");
-        } catch {
-            return { allowed: false, reason: "no-matching-grant" };
+        } catch (error) {
+            // Not a policy miss: the capability string itself is malformed, so no
+            // grant could ever match it. Reporting this as "no-matching-grant"
+            // pointed operators at their grants instead of at the mapping that
+            // produced the bad value.
+            const detail = error instanceof Error ? error.message : String(error);
+            console.error(
+                `[broker] authorization: capability "${String(request.capability)}" requested on resource "${request.resource.value}" is malformed, denying. ${detail} ` +
+                    `Capability names look like "mcp.tools.call" or "broker.providers.read": fix the authorization.toolCapabilities / providerToolCapabilities entry that produced this value, or the caller that passed it.`
+            );
+            return { allowed: false, reason: "invalid-capability" };
         }
 
         const matchingDenies = new Set<string>();

package/src/authorization/policy.types.ts

@@ -13,7 +13,31 @@ export interface IAuthorizationRequest {
     readonly tool?: string;
 }
 
-export type AuthorizationDecisionReason = "explicit-deny" | "role-grant" | "no-matching-grant" | "invalid-resource" | "unknown-resource";
+/**
+ * Why a decision came out the way it did, as written to the audit log.
+ *
+ * The distinction between a policy outcome and a fault is load-bearing: the
+ * audit log is what an operator actually reads, and reporting a fault as
+ * `"no-matching-grant"` sends them off writing grants that can never help.
+ *
+ * - `explicit-deny`      a deny policy matched.
+ * - `role-grant`         an assignment matched; the only allowing reason.
+ * - `no-matching-grant`  no policy matched. A genuine policy outcome.
+ * - `invalid-resource`   the request carried no resource at all.
+ * - `unknown-resource`   the slot maps to no configured resource path.
+ * - `invalid-capability` the requested capability string is malformed, so no
+ *                        grant could ever match it. A configuration fault.
+ * - `evaluation-error`   evaluation threw. Nothing was decided; the request is
+ *                        denied because that is the safe answer. A fault.
+ */
+export type AuthorizationDecisionReason =
+    | "explicit-deny"
+    | "role-grant"
+    | "no-matching-grant"
+    | "invalid-resource"
+    | "unknown-resource"
+    | "invalid-capability"
+    | "evaluation-error";
 
 export interface IAuthorizationDecision {
     readonly allowed: boolean;