@cyanmycelium/mcp-broker 0.4.0 → 1.2.0

package/src/broker/aggregate/aggregate.catalog.ts

@@ -1,5 +1,5 @@
 /**
- * AggregateCatalog — merges the tool and prompt catalogs of several providers
+ * AggregateCatalog, merges the tool and prompt catalogs of several providers
  * into a single namespaced view, and routes aggregated names back to their
  * origin provider.
  *
@@ -9,14 +9,14 @@
  */
 
 /** Minimal shape of an MCP tool entry. Extra fields are preserved as-is. */
-export interface CatalogTool {
+export interface ICatalogTool {
     name: string;
     description?: string;
     [key: string]: unknown;
 }
 
 /** Minimal shape of an MCP prompt entry. Extra fields are preserved as-is. */
-export interface CatalogPrompt {
+export interface ICatalogPrompt {
     name: string;
     title?: string;
     description?: string;
@@ -24,13 +24,13 @@ export interface CatalogPrompt {
 }
 
 /** One provider's raw contribution to the aggregate. */
-export interface ProviderEntry {
-    tools: CatalogTool[];
-    prompts: CatalogPrompt[];
+export interface IProviderEntry {
+    tools: ICatalogTool[];
+    prompts: ICatalogPrompt[];
 }
 
 /** Where an aggregated name routes back to. */
-export interface Route {
+export interface IRoute {
     provider: string;
     original: string;
 }
@@ -42,11 +42,11 @@ const SEPARATOR = "-";
 const MAX_TOOL_NAME_LENGTH = 64;
 
 export class AggregateCatalog {
-    private readonly _providers = new Map<string, ProviderEntry>();
-    private _tools: CatalogTool[] = [];
-    private _prompts: CatalogPrompt[] = [];
-    private _toolRoutes = new Map<string, Route>();
-    private _promptRoutes = new Map<string, Route>();
+    private readonly _providers = new Map<string, IProviderEntry>();
+    private _tools: ICatalogTool[] = [];
+    private _prompts: ICatalogPrompt[] = [];
+    private _toolRoutes = new Map<string, IRoute>();
+    private _promptRoutes = new Map<string, IRoute>();
 
     /** Number of providers currently contributing to the aggregate. */
     get providerCount(): number {
@@ -54,17 +54,17 @@ export class AggregateCatalog {
     }
 
     /** The merged, namespaced tool list. */
-    get tools(): CatalogTool[] {
+    get tools(): ICatalogTool[] {
         return this._tools;
     }
 
     /** The merged, namespaced prompt list. */
-    get prompts(): CatalogPrompt[] {
+    get prompts(): ICatalogPrompt[] {
         return this._prompts;
     }
 
     /** Adds or replaces a provider's contribution, then rebuilds the merged view. */
-    setProvider(provider: string, entry: ProviderEntry): void {
+    setProvider(provider: string, entry: IProviderEntry): void {
         this._providers.set(provider, entry);
         this._rebuild();
     }
@@ -74,21 +74,37 @@ export class AggregateCatalog {
         if (this._providers.delete(provider)) this._rebuild();
     }
 
+    /** The merged tool list restricted to providers `allow` returns `true` for. */
+    toolsFor(allow: (provider: string) => boolean): ICatalogTool[] {
+        return this._tools.filter((tool) => {
+            const route = this._toolRoutes.get(tool.name);
+            return route ? allow(route.provider) : false;
+        });
+    }
+
+    /** The merged prompt list restricted to providers `allow` returns `true` for. */
+    promptsFor(allow: (provider: string) => boolean): ICatalogPrompt[] {
+        return this._prompts.filter((prompt) => {
+            const route = this._promptRoutes.get(prompt.name);
+            return route ? allow(route.provider) : false;
+        });
+    }
+
     /** Resolves an aggregated tool name to its origin, or `undefined` if unknown. */
-    resolveTool(name: string): Route | undefined {
+    resolveTool(name: string): IRoute | undefined {
         return this._toolRoutes.get(name);
     }
 
     /** Resolves an aggregated prompt name to its origin, or `undefined` if unknown. */
-    resolvePrompt(name: string): Route | undefined {
+    resolvePrompt(name: string): IRoute | undefined {
         return this._promptRoutes.get(name);
     }
 
     private _rebuild(): void {
-        const tools: CatalogTool[] = [];
-        const prompts: CatalogPrompt[] = [];
-        const toolRoutes = new Map<string, Route>();
-        const promptRoutes = new Map<string, Route>();
+        const tools: ICatalogTool[] = [];
+        const prompts: ICatalogPrompt[] = [];
+        const toolRoutes = new Map<string, IRoute>();
+        const promptRoutes = new Map<string, IRoute>();
 
         for (const [provider, entry] of this._providers) {
             for (const tool of entry.tools) {
@@ -110,6 +126,18 @@ export class AggregateCatalog {
     }
 }
 
+/** @deprecated Use {@link ICatalogTool}. */
+export type CatalogTool = ICatalogTool;
+
+/** @deprecated Use {@link ICatalogPrompt}. */
+export type CatalogPrompt = ICatalogPrompt;
+
+/** @deprecated Use {@link IProviderEntry}. */
+export type ProviderEntry = IProviderEntry;
+
+/** @deprecated Use {@link IRoute}. */
+export type Route = IRoute;
+
 function prefixed(provider: string, original: string): string {
     return `${provider}${SEPARATOR}${original}`;
 }

package/src/broker/aggregate/aggregate.server.ts

@@ -1,21 +1,31 @@
 import type { IMessageTransport } from "@cyanmycelium/mcp-core";
-import type { InternalClient } from "../../ws.tunnel.js";
-import { AggregateCatalog } from "./aggregate.catalog.js";
-import { ProviderClientSession } from "./provider.client.session.js";
+import type { IInternalClient } from "../../ws/ws.interfaces";
+import type { AggregateScopeFilter, IPrincipal } from "../../auth/index";
+import {
+    SubjectMappingError,
+    makeAuthorizationAuditEvent,
+    writeAuthorizationAuditEvent,
+    type IAuthorizationDecision,
+    type IAuthorizationSubject,
+    type IMcpOperation,
+    type IPolicyAuthorization,
+} from "../../authorization/index";
+import { AggregateCatalog } from "./aggregate.catalog";
+import { ProviderClientSession } from "./provider.client.session";
 
 /** MCP protocol version advertised by the aggregate server. */
 const PROTOCOL_VERSION = "2024-11-05";
 
 /** Opens an in-process client to a named provider slot. Supplied by WsTunnel. */
-export type InternalClientFactory = (providerName: string) => InternalClient;
+export type InternalClientFactory = (providerName: string) => IInternalClient;
 
-interface ClientMessage {
+interface IClientMessage {
     id?: string | number | null;
     method?: string;
     params?: unknown;
 }
 
-interface CallParams {
+interface ICallParams {
     name?: string;
     arguments?: Record<string, unknown>;
 }
@@ -37,6 +47,10 @@ export class AggregateServer implements IMessageTransport {
     private readonly _sessions = new Map<string, ProviderClientSession>();
     private readonly _openClient: InternalClientFactory;
     private _running = false;
+    /** Per-caller provider visibility filter; `null` ⇒ every caller sees all. */
+    private _scopeFilter: AggregateScopeFilter | null = null;
+    /** Provider-aware hierarchical authorization, absent in legacy mode. */
+    private _authorization: IPolicyAuthorization | null = null;
 
     onMessage: ((data: string) => void) | null = null;
     onOpen: (() => void) | null = null;
@@ -61,9 +75,27 @@ export class AggregateServer implements IMessageTransport {
         this._running = true;
     }
 
-    /** WsTunnel hands a client request for the `_all` slot here. */
+    /** Sets the per-caller provider visibility filter. `null` disables filtering. */
+    setScopeFilter(filter: AggregateScopeFilter | null): void {
+        this._scopeFilter = filter;
+    }
+
+    /** Sets the compiled hierarchical policy runtime. */
+    setPolicyAuthorization(authorization: IPolicyAuthorization | null): void {
+        this._authorization = authorization;
+    }
+
+    /** WsTunnel hands a client request for the `_all` slot here (no principal). */
     send(data: string): void {
-        void this._handleClientMessage(data);
+        void this._handleClientMessage(data, null);
+    }
+
+    /**
+     * Like {@link send}, but carries the authenticated caller so the aggregate
+     * narrows the catalog and routing to the providers the caller may see.
+     */
+    sendAs(data: string, principal: IPrincipal | null): void {
+        void this._handleClientMessage(data, principal);
     }
 
     /** Closes every provider session and the aggregate transport. */
@@ -109,15 +141,98 @@ export class AggregateServer implements IMessageTransport {
         this._emitListChanged();
     }
 
-    private async _handleClientMessage(data: string): Promise<void> {
-        let msg: ClientMessage;
+    private _subjectFor(principal: IPrincipal | null): IAuthorizationSubject {
+        if (principal?.subject) return principal.subject;
+        if (!principal) return { ids: [] };
+        try {
+            return (
+                this._authorization?.subjectMapper.map(principal.claims) ?? {
+                    ids: [],
+                    claims: principal.claims,
+                }
+            );
+        } catch (error) {
+            if (!(error instanceof SubjectMappingError)) {
+                console.error("[broker] aggregate authorization subject mapping failed.");
+            }
+            return { ids: [], claims: principal.claims };
+        }
+    }
+
+    private _scopeAllows(principal: IPrincipal | null, provider: string): boolean {
+        const filter = this._scopeFilter;
+        return !filter || !principal || filter(principal, provider);
+    }
+
+    private _policyAllows(principal: IPrincipal | null, provider: string, operation: IMcpOperation): boolean {
+        const authorization = this._authorization;
+        if (!authorization) return true;
+
+        const subject = this._subjectFor(principal);
+        const resource = authorization.slotResourceResolver.resolve(provider);
+        if (!resource) {
+            const decision: IAuthorizationDecision = { allowed: false, reason: "unknown-resource" };
+            writeAuthorizationAuditEvent(makeAuthorizationAuditEvent({ subject, slot: AggregateServer.SLOT, provider }, decision));
+            return false;
+        }
+
         try {
-            msg = JSON.parse(data) as ClientMessage;
+            const classified = authorization.capabilityClassifier.classify(operation, resource, provider);
+            if (!classified) return true;
+            const decision = authorization.engine.authorize({
+                subject,
+                capability: classified.capability,
+                resource,
+                provider,
+                tool: classified.tool,
+            });
+            if (!decision.allowed || authorization.audit.logAllowed) {
+                writeAuthorizationAuditEvent(
+                    makeAuthorizationAuditEvent(
+                        {
+                            subject,
+                            slot: AggregateServer.SLOT,
+                            resource,
+                            capability: classified.capability,
+                            provider,
+                            tool: classified.tool,
+                        },
+                        decision
+                    )
+                );
+            }
+            return decision.allowed;
+        } catch {
+            console.error("[broker] aggregate policy evaluation failed.");
+            const decision: IAuthorizationDecision = { allowed: false, reason: "no-matching-grant" };
+            writeAuthorizationAuditEvent(
+                makeAuthorizationAuditEvent(
+                    {
+                        subject,
+                        slot: AggregateServer.SLOT,
+                        resource,
+                        provider,
+                    },
+                    decision
+                )
+            );
+            return false;
+        }
+    }
+
+    private _allows(principal: IPrincipal | null, provider: string, operation: IMcpOperation): boolean {
+        return this._scopeAllows(principal, provider) && this._policyAllows(principal, provider, operation);
+    }
+
+    private async _handleClientMessage(data: string, principal: IPrincipal | null): Promise<void> {
+        let msg: IClientMessage;
+        try {
+            msg = JSON.parse(data) as IClientMessage;
         } catch {
             return;
         }
         const id = msg.id;
-        if (id == null) return; // client notification — nothing to answer
+        if (id == null) return; // client notification: nothing to answer
 
         switch (msg.method) {
             case "initialize":
@@ -133,26 +248,41 @@ export class AggregateServer implements IMessageTransport {
                 this._reply(id, { result: {} });
                 break;
             case "tools/list":
-                this._reply(id, { result: { tools: this._catalog.tools } });
+                this._reply(id, {
+                    result: {
+                        tools: this._catalog.toolsFor((provider) => this._allows(principal, provider, { method: "tools/list" })),
+                    },
+                });
                 break;
             case "prompts/list":
-                this._reply(id, { result: { prompts: this._catalog.prompts } });
+                this._reply(id, {
+                    result: {
+                        prompts: this._catalog.promptsFor((provider) => this._allows(principal, provider, { method: "prompts/list" })),
+                    },
+                });
                 break;
             case "tools/call":
-                await this._route(id, msg.params, "tool");
+                await this._route(id, msg.params, "tool", principal);
                 break;
             case "prompts/get":
-                await this._route(id, msg.params, "prompt");
+                await this._route(id, msg.params, "prompt", principal);
                 break;
             default:
                 this._reply(id, { error: { code: -32601, message: `Method not found: ${msg.method ?? "(none)"}` } });
         }
     }
 
-    private async _route(id: string | number, params: unknown, kind: "tool" | "prompt"): Promise<void> {
-        const p = (params ?? {}) as CallParams;
+    private async _route(id: string | number, params: unknown, kind: "tool" | "prompt", principal: IPrincipal | null): Promise<void> {
+        const p = (params ?? {}) as ICallParams;
         const route = p.name ? (kind === "tool" ? this._catalog.resolveTool(p.name) : this._catalog.resolvePrompt(p.name)) : undefined;
-        if (!route) {
+        // Treat a provider the caller may not see as if it did not exist, do not
+        // leak its presence through a distinct "forbidden" error.
+        const operation: IMcpOperation | undefined = route
+            ? kind === "tool"
+                ? { method: "tools/call", params: { name: route.original } }
+                : { method: "prompts/get", params: { name: route.original } }
+            : undefined;
+        if (!route || !operation || !this._allows(principal, route.provider, operation)) {
             this._reply(id, { error: { code: -32602, message: `Unknown aggregated ${kind}: ${p.name ?? "(none)"}` } });
             return;
         }

package/src/broker/aggregate/provider.client.session.ts

@@ -1,5 +1,5 @@
-import type { InternalClient } from "../../ws.tunnel.js";
-import type { CatalogTool, CatalogPrompt } from "./aggregate.catalog.js";
+import type { IInternalClient } from "../../ws/ws.interfaces";
+import type { ICatalogTool, ICatalogPrompt } from "./aggregate.catalog";
 
 /** MCP protocol version the aggregate sessions negotiate with sub-providers. */
 const PROTOCOL_VERSION = "2024-11-05";
@@ -8,17 +8,17 @@ const PROTOCOL_VERSION = "2024-11-05";
 const REQUEST_TIMEOUT_MS = 30_000;
 
 /** Outcome of a JSON-RPC request: exactly one of `result` / `error` is set. */
-interface RpcOutcome {
+interface IRpcOutcome {
     result?: unknown;
     error?: unknown;
 }
 
-interface PendingRequest {
-    resolve: (outcome: RpcOutcome) => void;
+interface IPendingRequest {
+    resolve: (outcome: IRpcOutcome) => void;
     timer: ReturnType<typeof setTimeout>;
 }
 
-interface IncomingMessage {
+interface IIncomingMessage {
     id?: string | number | null;
     method?: string;
     result?: unknown;
@@ -27,7 +27,7 @@ interface IncomingMessage {
 
 /**
  * A hand-rolled JSON-RPC client session to one aggregated provider, running
- * over an in-process {@link InternalClient}.
+ * over an in-process {@link IInternalClient}.
  *
  * Performs the MCP `initialize` handshake, caches the provider's `tools/list`
  * and `prompts/list`, and re-fetches them when the provider emits a
@@ -37,12 +37,12 @@ interface IncomingMessage {
 export class ProviderClientSession {
     readonly provider: string;
 
-    private readonly _client: InternalClient;
+    private readonly _client: IInternalClient;
     private readonly _idPrefix: string;
-    private readonly _pending = new Map<string, PendingRequest>();
+    private readonly _pending = new Map<string, IPendingRequest>();
     private _nextId = 0;
-    private _tools: CatalogTool[] = [];
-    private _prompts: CatalogPrompt[] = [];
+    private _tools: ICatalogTool[] = [];
+    private _prompts: ICatalogPrompt[] = [];
     private _closed = false;
 
     /** Fires after the cached catalog changes (initial load or `list_changed`). */
@@ -51,7 +51,7 @@ export class ProviderClientSession {
     /** Fires when the underlying provider slot disconnects. */
     onClosed: (() => void) | null = null;
 
-    constructor(provider: string, client: InternalClient) {
+    constructor(provider: string, client: IInternalClient) {
         this.provider = provider;
         this._client = client;
         this._idPrefix = `agg-${provider}-`;
@@ -63,11 +63,11 @@ export class ProviderClientSession {
         };
     }
 
-    get tools(): CatalogTool[] {
+    get tools(): ICatalogTool[] {
         return this._tools;
     }
 
-    get prompts(): CatalogPrompt[] {
+    get prompts(): ICatalogPrompt[] {
         return this._prompts;
     }
 
@@ -83,12 +83,12 @@ export class ProviderClientSession {
     }
 
     /** Forwards a `tools/call` to the provider, relaying the raw outcome. */
-    callTool(name: string, args: Record<string, unknown>): Promise<RpcOutcome> {
+    callTool(name: string, args: Record<string, unknown>): Promise<IRpcOutcome> {
         return this._request("tools/call", { name, arguments: args });
     }
 
     /** Forwards a `prompts/get` to the provider, relaying the raw outcome. */
-    getPrompt(name: string, args: Record<string, unknown>): Promise<RpcOutcome> {
+    getPrompt(name: string, args: Record<string, unknown>): Promise<IRpcOutcome> {
         return this._request("prompts/get", { name, arguments: args });
     }
 
@@ -101,8 +101,8 @@ export class ProviderClientSession {
     }
 
     private async _refresh(): Promise<void> {
-        this._tools = await this._listAll<CatalogTool>("tools/list", "tools");
-        this._prompts = await this._listAll<CatalogPrompt>("prompts/list", "prompts");
+        this._tools = await this._listAll<ICatalogTool>("tools/list", "tools");
+        this._prompts = await this._listAll<ICatalogPrompt>("prompts/list", "prompts");
         this.onCatalogChanged?.();
     }
 
@@ -125,8 +125,8 @@ export class ProviderClientSession {
         return items;
     }
 
-    private _request(method: string, params: unknown): Promise<RpcOutcome> {
-        return new Promise<RpcOutcome>((resolve) => {
+    private _request(method: string, params: unknown): Promise<IRpcOutcome> {
+        return new Promise<IRpcOutcome>((resolve) => {
             if (this._closed) {
                 resolve({ error: { code: -32000, message: "session closed" } });
                 return;
@@ -142,9 +142,9 @@ export class ProviderClientSession {
     }
 
     private _handleMessage(data: string): void {
-        let msg: IncomingMessage;
+        let msg: IIncomingMessage;
         try {
-            msg = JSON.parse(data) as IncomingMessage;
+            msg = JSON.parse(data) as IIncomingMessage;
         } catch {
             return;
         }

package/src/broker/behaviors/broker.behavior.info.ts

@@ -1,8 +1,8 @@
 import { McpBehavior } from "@cyanmycelium/mcp-core";
 import type { McpResource, McpTool } from "@cyanmycelium/mcp-core";
-import { BROKER_INFO_URI, BrokerInfoAdapter } from "../adapters/broker.adapter.info.js";
-import { brokerBaselineResourceDescription, brokerBaselineResourceName, brokerBaselineToolDescription } from "../broker.grammars.js";
-import type { BrokerContext } from "../broker.context.js";
+import { BROKER_INFO_URI, BrokerInfoAdapter } from "../adapters/broker.adapter.info";
+import { brokerBaselineResourceDescription, brokerBaselineResourceName, brokerBaselineToolDescription } from "../broker.grammars";
+import type { IBrokerContext } from "../broker.context";
 
 /**
  * Exposes basic broker identity (name, version, uptime, listening config) as
@@ -13,7 +13,7 @@ import type { BrokerContext } from "../broker.context.js";
 export class BrokerInfoBehavior extends McpBehavior {
     public static readonly NAMESPACE = "broker";
 
-    constructor(context: BrokerContext) {
+    constructor(context: IBrokerContext) {
         super(new BrokerInfoAdapter(context), {
             namespace: BrokerInfoBehavior.NAMESPACE,
         });

package/src/broker/behaviors/broker.behavior.providers.ts

@@ -1,6 +1,6 @@
 import { McpBehavior } from "@cyanmycelium/mcp-core";
 import type { McpResource, McpResourceTemplate, McpTool } from "@cyanmycelium/mcp-core";
-import { BrokerProvidersAdapter, PROVIDERS_URI, PROVIDER_URI_TEMPLATE } from "../adapters/broker.adapter.providers.js";
+import { BrokerProvidersAdapter, PROVIDERS_URI, PROVIDER_URI_TEMPLATE } from "../adapters/broker.adapter.providers";
 import {
     brokerBaselinePropertyDescription,
     brokerBaselineResourceDescription,
@@ -8,22 +8,22 @@ import {
     brokerBaselineResourceTemplateDescription,
     brokerBaselineResourceTemplateName,
     brokerBaselineToolDescription,
-} from "../broker.grammars.js";
-import type { BrokerContext } from "../broker.context.js";
+} from "../broker.grammars";
+import type { IBrokerContext } from "../broker.context";
 
 /**
  * Exposes the broker's provider slots so an MCP agent can discover what is
  * currently routable behind the broker, with two tools:
  *
- * - `providers_list` — every slot (including disconnected ones).
- * - `provider_status({ name })` — detail on one slot.
+ * - `providers_list`: every slot (including disconnected ones).
+ * - `provider_status({ name })`, detail on one slot.
  *
  * Plus matching resources at `broker://providers` and `broker://providers/<name>`.
  */
 export class BrokerProvidersBehavior extends McpBehavior {
     public static readonly NAMESPACE = "broker_providers";
 
-    constructor(context: BrokerContext) {
+    constructor(context: IBrokerContext) {
         super(new BrokerProvidersAdapter(context), {
             namespace: BrokerProvidersBehavior.NAMESPACE,
         });

package/src/broker/broker.context.ts

@@ -4,7 +4,7 @@
  * Decouples the behaviors from the concrete `WsTunnel` class, making them
  * unit-testable and reusable (e.g. a future .NET-backed context).
  */
-export interface BrokerContext {
+export interface IBrokerContext {
     /** Package version (from package.json). */
     readonly version: string;
 
@@ -37,10 +37,10 @@ export interface BrokerContext {
     };
 
     /** Snapshot of every known provider slot, including disconnected ones. */
-    getProvidersInfo(): BrokerProviderInfo[];
+    getProvidersInfo(): IBrokerProviderInfo[];
 
     /** Snapshot of a single provider slot, or `undefined` if the name is unknown. */
-    getProviderInfo(name: string): BrokerProviderInfo | undefined;
+    getProviderInfo(name: string): IBrokerProviderInfo | undefined;
 }
 
 /**
@@ -54,7 +54,7 @@ export interface BrokerContext {
  */
 export type BrokerProviderTransport = "ws" | "ws-multiplex" | "stdio" | "loopback" | "none";
 
-export interface BrokerProviderInfo {
+export interface IBrokerProviderInfo {
     /** Slot name as advertised on `/<name>/...` endpoints. */
     name: string;
 
@@ -73,3 +73,9 @@ export interface BrokerProviderInfo {
     /** Number of in-flight JSON-RPC requests awaiting a response. */
     pendingCount: number;
 }
+
+/** @deprecated Use {@link IBrokerContext}. */
+export type BrokerContext = IBrokerContext;
+
+/** @deprecated Use {@link IBrokerProviderInfo}. */
+export type BrokerProviderInfo = IBrokerProviderInfo;