@cyanmycelium/mcp-broker 0.4.0 → 1.2.0

package/src/{ws.tunnel.ts → ws/ws.tunnel.ts}

@@ -4,15 +4,41 @@ import * as https from "https";
 import * as nodePath from "path";
 import { randomUUID } from "crypto";
 import type { IncomingMessage, ServerResponse } from "http";
-import { WebSocket, WebSocketServer } from "ws";
-import type { GrammarResolverOptions, IMessageTransport, IMcpServer } from "@cyanmycelium/mcp-core";
-import { StdioUpstream, type StdioUpstreamConfig } from "./stdio.upstream.js";
-import { RemoteUpstream, type RemoteUpstreamConfig } from "./remote.upstream.js";
-import type { Upstream } from "./upstream.js";
-import { startBrokerServer, BROKER_PROVIDER_NAME } from "./broker/index.js";
-import type { BrokerContext, BrokerProviderInfo, BrokerProviderTransport } from "./broker/index.js";
-import { AggregateServer } from "./broker/aggregate/aggregate.server.js";
-import { VERSION, PACKAGE_NAME } from "./version.js";
+import { WebSocket, WebSocketServer, type VerifyClientCallbackAsync } from "ws";
+import type { IMessageTransport, IMcpServer } from "@cyanmycelium/mcp-core";
+import { StdioTransport, StreamableHttpEndpoint } from "@cyanmycelium/mcp-core/node";
+// The broker is itself a provider: it publishes its own `_broker` and `_all`
+// slots: so sharing the provider package's wire contract is the natural way to
+// keep one definition of the envelope rather than two that drift.
+import { decodeEnvelope, encodeEnvelope, encodeErrorEnvelope, envelopeFrame, TunnelErrorCodes } from "@cyanmycelium/mcp-broker-provider/protocol";
+import { StdioUpstream } from "../stdio.upstream";
+import { RemoteUpstream } from "../remote.upstream";
+import type { IUpstream } from "../upstream";
+import { startBrokerServer, BROKER_PROVIDER_NAME } from "../broker/index";
+import type { IBrokerContext, IBrokerProviderInfo, BrokerProviderTransport } from "../broker/index";
+import { AggregateServer } from "../broker/aggregate/aggregate.server";
+import {
+    HttpAuthGuard,
+    AuthError,
+    normalizeProviderAuthentication,
+    providerMayPublish,
+    type IProviderAuthenticator,
+    type IPrincipal,
+    type IProviderPrincipal,
+} from "../auth/index";
+import {
+    DefaultSlotResourceResolver,
+    SubjectMappingError,
+    makeAuthorizationAuditEvent,
+    writeAuthorizationAuditEvent,
+    type IAuthorizationDecision,
+    type IAuthorizationSubject,
+    type IPolicyAuthorization,
+    type ResourcePath,
+    type ISlotResourceResolver,
+} from "../authorization/index";
+import { VERSION, PACKAGE_NAME } from "../version";
+import type { AllowedOrigins, IHttpSession, IInternalClient, IProviderState, IWsTunnelOptions, McpEndpointKind } from "./ws.interfaces";
 
 // ---------------------------------------------------------------------------
 // Static-file helpers
@@ -34,251 +60,61 @@ const MIME: Readonly<Record<string, string>> = {
 };
 
 // ---------------------------------------------------------------------------
-// Internal types
+// JSON-RPC helpers
 // ---------------------------------------------------------------------------
 
 /**
- * Where a JSON-RPC response should be delivered.
- * Either a WebSocket socket (raw WS client), an SSE session (legacy MCP/HTTP),
- * a held-open HTTP response (Streamable HTTP transport, MCP 2025-03-26),
- * the process stdout (stdio transport for Claude Desktop), or an in-process
- * internal client (e.g. the aggregate server).
- */
-type ResponseSink =
-    | { type: "ws"; socket: WebSocket }
-    | { type: "sse"; sessionId: string }
-    | { type: "http"; res: ServerResponse }
-    | { type: "stdio" }
-    | { type: "internal"; client: InternalClient };
-
-/**
- * All mutable state for one named provider slot.
- * Created lazily on first client connection; the WebSocket field is set when
- * the provider actually connects (and cleared on disconnect).
- */
-interface ProviderState {
-    /** The active provider WebSocket, or `null` when the provider is not connected. */
-    ws: WebSocket | null;
-    /** Pending JSON-RPC request ids → response sinks waiting for a reply. */
-    readonly pending: Map<string | number, ResponseSink>;
-    /** Active legacy SSE sessions (Claude), keyed by session id. */
-    readonly sseSessions: Map<string, ServerResponse>;
-    /** Active Streamable HTTP GET streams (MCP Inspector), keyed by session id. */
-    readonly mcpGetSessions: Map<string, ServerResponse>;
-    /** Raw WebSocket MCP clients connected to this provider. */
-    readonly wsClients: Set<WebSocket>;
-    /** In-process clients (e.g. the aggregate server) attached to this slot. */
-    readonly internalClients: Set<InternalClient>;
-}
-
-// ---------------------------------------------------------------------------
-// Public types
-// ---------------------------------------------------------------------------
-
-/**
- * A single static-file mount: serves the contents of `dir` under `urlPrefix`.
+ * The JSON-RPC id a frame is waiting on, or `undefined` when nothing will come
+ * back for it: a notification, or something that did not parse.
  *
- * @example
- * { urlPrefix: "/",       dir: "/absolute/path/to/www" }
- * { urlPrefix: "/bundle", dir: "/absolute/path/to/bundle" }
+ * `null` is a legal id in an error response, so absence cannot be signalled
+ * with it, hence `undefined`.
  */
-export interface StaticMount {
-    /** URL prefix that triggers this mount (e.g. `"/"` or `"/bundle"`). */
-    urlPrefix: string;
-    /** Absolute path to the directory to serve. */
-    dir: string;
+function requestIdOf(frame: string): string | number | undefined {
+    try {
+        const parsed = JSON.parse(frame) as { id?: unknown };
+        if (typeof parsed?.id === "string" || typeof parsed?.id === "number") return parsed.id;
+    } catch {
+        /* not JSON: nothing to route by */
+    }
+    return undefined;
 }
 
 /**
- * In-process client handle for a provider slot — the symmetric counterpart of
- * {@link WsTunnel.registerLoopbackProvider}. Lets a component inside the broker
- * process (e.g. the aggregate server) issue MCP requests to a provider slot and
- * receive both the responses and the provider's broadcast notifications,
- * without opening a real network connection.
+ * Turns the three shapes an operator may configure into the single predicate
+ * the Streamable HTTP endpoint expects.
+ *
+ * Absent means closed, not open: a browser origin is refused unless it was
+ * named. A `RegExp` is reset before each test, because one carrying the `g`
+ * flag keeps `lastIndex` between calls and would otherwise accept and refuse
+ * the same origin in turn.
  */
-export interface InternalClient {
-    /**
-     * Sends a JSON-RPC message to the provider slot. When the message carries an
-     * `id`, the matching response is delivered to {@link onMessage}. When the
-     * provider is not connected, a JSON-RPC error is delivered synchronously.
-     */
-    send(message: string): void;
-    /** Receives responses to this client's requests and the provider's notifications. */
-    onMessage: ((data: string) => void) | null;
-    /** Fires when the provider slot loses its connection. */
-    onClose: (() => void) | null;
-    /** Detaches this internal client; pending requests are dropped. */
-    close(): void;
+function originPredicate(allowed: AllowedOrigins | undefined): (origin: string) => boolean {
+    if (!allowed) return () => false;
+    if (typeof allowed === "function") return allowed;
+    if (allowed instanceof RegExp) {
+        return (origin) => {
+            allowed.lastIndex = 0;
+            return allowed.test(origin);
+        };
+    }
+    const exact = new Set(allowed);
+    return (origin) => exact.has(origin);
 }
 
 /**
- * Configuration options for a {@link WsTunnel} instance.
+ * Opens a transport that was handed over closed.
+ *
+ * `connect` is not part of `IMessageTransport`, because some transports arrive
+ * already open, so it is probed for rather than required. This is the same
+ * check `McpServer` makes on the transport it is given, and for the same
+ * reason: testing for a concrete class would tie the caller to one
+ * implementation.
  */
-export interface WsTunnelOptions {
-    /** TCP port to listen on. */
-    port: number;
-
-    /**
-     * Host/interface to bind to.
-     * @default "0.0.0.0"
-     */
-    host?: string;
-
-    /**
-     * URL path **prefix** the MCP provider connects to via WebSocket.
-     * Each provider appends its name: `<providerPath>/<encodedName>`.
-     * @default "/provider"
-     */
-    providerPath?: string;
-
-    /**
-     * URL path for **multiplexed** provider connections.
-     * A single WebSocket carries traffic for multiple providers using the
-     * envelope protocol `{ provider: string, payload: object }`.
-     * @default "/providers"
-     */
-    providersPath?: string;
-
-    /**
-     * URL path raw WebSocket MCP clients connect to.
-     * @default "/"
-     */
-    clientPath?: string;
-
-    /**
-     * **Suffix** appended to a provider name for the SSE endpoint.
-     * Full URL: `/<providerName>/sse`
-     * @default "/sse"
-     */
-    ssePath?: string;
-
-    /**
-     * **Suffix** appended to a provider name for the legacy SSE POST endpoint.
-     * Full URL: `/<providerName>/messages`
-     * @default "/messages"
-     */
-    messagesPath?: string;
-
-    /**
-     * **Suffix** appended to a provider name for the Streamable HTTP endpoint (MCP 2025-03-26).
-     * Full URL: `/<providerName>/mcp`
-     * MCP Inspector connects here.
-     * @default "/mcp"
-     */
-    mcpPath?: string;
-
-    /**
-     * URL path that returns a `{ files: string[] }` JSON listing of every file
-     * inside the `samples/` subdirectory of the root static mount.
-     * @default "/__samples_index__"
-     */
-    samplesIndexPath?: string;
-
-    /**
-     * Optional static-file mounts served over plain HTTP.
-     * Matched by longest URL prefix; directory requests fall back to `index.html`.
-     */
-    staticMounts?: StaticMount[];
-
-    /**
-     * Stdio upstream providers. Each entry spawns a child process and wires its
-     * stdin/stdout as an MCP transport. Clients reach the process using its `name`
-     * directly.
-     *
-     * If a WebSocket provider connects with the same name as a stdio upstream, the
-     * connection is rejected and a warning is logged — stdio takes priority.
-     * @default undefined — no stdio providers
-     */
-    stdioUpstreams?: StdioUpstreamConfig[];
-
-    /** Remote MCP servers reached by URL, exposed as provider slots. */
-    remoteUpstreams?: RemoteUpstreamConfig[];
-
-    /**
-     * Stdio client transport. When set, the broker reads JSON-RPC from
-     * `process.stdin` and writes responses to `process.stdout`, bridging an
-     * external MCP client (e.g. Claude Desktop) to the named provider.
-     *
-     * In this mode ALL logging is redirected to stderr so stdout stays clean
-     * for the JSON-RPC stream.
-     *
-     * Claude Desktop config example:
-     * ```json
-     * {
-     *   "command": "npx",
-     *   "args": ["-y", "@cyanmycelium/mcp-broker"],
-     *   "env": { "MCP_BROKER_STDIO_PROVIDER": "my-provider" }
-     * }
-     * ```
-     * @default undefined — stdio client transport disabled
-     */
-    stdioClient?: { providerName: string };
-
-    /**
-     * TLS configuration. When provided, the server uses HTTPS and WSS instead of HTTP and WS.
-     * Both `cert` and `key` must be PEM-encoded strings (file contents, not file paths).
-     * Use {@link WsTunnelBuilder.withTlsFiles} to load from disk paths.
-     * @default undefined — plain HTTP/WS
-     */
-    tls?: {
-        /** PEM-encoded TLS certificate. */
-        cert: string;
-        /** PEM-encoded private key. */
-        key: string;
-    };
-
-    /**
-     * When `true` (default), the broker exposes itself as an MCP server under the
-     * reserved slot `_broker`. Tier-1 behaviors (`broker_info`, `providers_list`,
-     * `provider_status`) become callable at `<host>/_broker/mcp`.
-     *
-     * Set to `false` to keep the broker invisible to MCP clients.
-     * @default true
-     */
-    enableBrokerProvider?: boolean;
-
-    /**
-     * When `true` (default), the broker exposes the reserved slot `_all` — an
-     * aggregate MCP server that unions the tools and prompts of every provider
-     * that opted in via the registration handshake. Reachable like any other
-     * slot (`<host>/_all/mcp`, etc.).
-     *
-     * Set to `false` to disable aggregation entirely.
-     * @default true
-     */
-    enableAggregateProvider?: boolean;
-
-    /**
-     * Logical name reported by `broker_info`. Useful when running multiple
-     * broker instances and you want to tell them apart from the agent side
-     * (e.g. `"broker-eu-west"`).
-     * @default PACKAGE_NAME — `@cyanmycelium/mcp-broker`
-     */
-    brokerName?: string;
-
-    /**
-     * Overrides for the embedded broker server's grammar resolver — passed
-     * straight through to `mcp-core`'s `grammarResolverFromOptions`. The
-     * broker installs its own default `localeSource` (reads
-     * `process.env.MCP_BROKER_LOCALE`); anything you set here wins.
-     *
-     * Use this to inject a custom `localeSource` (e.g. read from an HTTP
-     * header proxied by your transport), enable the optional `versionFrom`
-     * dimension, or extend the `agents` map with additional LLM families.
-     */
-    brokerGrammarResolverOptions?: Partial<GrammarResolverOptions>;
-
-    /**
-     * Path to a user-supplied grammars directory whose `<userAgent>/<locale>.json`
-     * files are registered alongside the packaged grammars used by the
-     * embedded broker server. Typically pointed at `.mcp-broker/grammars/`.
-     *
-     * The candidate-chain resolution in `McpServer.initialize`
-     * (mcp-core@0.3.0) handles cascade across user-agent and locale
-     * dimensions, so partial files no longer need to be pre-merged with a
-     * baseline.
-     */
-    brokerLocalGrammarsDir?: string;
+function openTransport(transport: IMessageTransport): void {
+    if ("connect" in transport && typeof (transport as { connect: unknown }).connect === "function") {
+        (transport as { connect(): void }).connect();
+    }
 }
 
 // ---------------------------------------------------------------------------
@@ -306,8 +142,8 @@ export interface WsTunnelOptions {
  * Each provider gets its own isolated set of sessions, pending requests, and
  * notification streams. Multiple providers can be connected simultaneously.
  */
-export class WsTunnel implements BrokerContext {
-    private readonly _options: WsTunnelOptions;
+export class WsTunnel implements IBrokerContext {
+    private readonly _options: IWsTunnelOptions;
     private _httpServer: http.Server | https.Server | null = null;
     private _wss: WebSocketServer | null = null;
 
@@ -316,13 +152,13 @@ export class WsTunnel implements BrokerContext {
      * Created lazily: a slot is allocated the first time any client references
      * a provider name, even before the provider WebSocket connects.
      */
-    private readonly _providers = new Map<string, ProviderState>();
+    private readonly _providers = new Map<string, IProviderState>();
 
     /** Maps a multiplexed WebSocket to the set of provider names it feeds. */
     private readonly _multiplexSockets = new Map<WebSocket, Set<string>>();
 
     /** Upstream providers (stdio child processes and remote URL servers), keyed by name. */
-    private readonly _upstreams = new Map<string, Upstream>();
+    private readonly _upstreams = new Map<string, IUpstream>();
 
     /**
      * In-process loopback transports registered as provider slots.
@@ -331,27 +167,61 @@ export class WsTunnel implements BrokerContext {
      */
     private readonly _loopbackProviders = new Map<string, IMessageTransport>();
 
-    /** The embedded broker MCP server, when {@link WsTunnelOptions.enableBrokerProvider} is on. */
+    /** The embedded broker MCP server, when {@link IWsTunnelOptions.enableBrokerProvider} is on. */
     private _brokerServer: IMcpServer | null = null;
 
-    /** The aggregate MCP server (`_all` slot), when {@link WsTunnelOptions.enableAggregateProvider} is on. */
+    /** The aggregate MCP server (`_all` slot), when {@link IWsTunnelOptions.enableAggregateProvider} is on. */
     private _aggregateServer: AggregateServer | null = null;
 
     /** Provider name that the stdio client transport is bridged to, or null when disabled. */
     private _stdioClientProvider: string | null = null;
 
-    /** Buffered partial line from stdin (stdio client transport). */
-    private _stdioClientBuffer = "";
+    /** mcp-core transport connected to the broker process stdin/stdout. */
+    private _stdioClientTransport: StdioTransport | null = null;
 
     /** Timestamp of the most recent successful `start()`. */
     private _startedAt: Date | null = null;
 
-    constructor(options: WsTunnelOptions) {
+    /** HTTP resource-server enforcement point, or `null` when auth is disabled. */
+    private readonly _authGuard: HttpAuthGuard | null;
+
+    /** Provider (engine) authenticator, or `null` when provider auth is disabled. */
+    private readonly _providerAuth: IProviderAuthenticator | null;
+
+    /** Compiled hierarchical authorization, or `null` for legacy behavior. */
+    private readonly _authorization: IPolicyAuthorization | null;
+
+    /** Stable technical-slot to hierarchical-resource mapping. */
+    private readonly _slotResourceResolver: ISlotResourceResolver;
+
+    /** Origin check applied by every slot's Streamable HTTP endpoint. */
+    private readonly _allowedOrigins: (origin: string) => boolean;
+
+    /** Principal captured at a client's WS upgrade, keyed by the upgrade request. */
+    private readonly _pendingClientPrincipals = new WeakMap<IncomingMessage, IPrincipal>();
+
+    /** Authenticated principal per raw WS client socket, for `_all` scope filtering. */
+    private readonly _clientPrincipals = new WeakMap<WebSocket, IPrincipal>();
+
+    /** Authenticated principal attached to long-lived HTTP/SSE streams. */
+    private readonly _streamPrincipals = new WeakMap<ServerResponse, IPrincipal>();
+
+    /** Provider principals captured during successful WebSocket upgrades. */
+    private readonly _pendingProviderPrincipals = new WeakMap<IncomingMessage, IProviderPrincipal>();
+    private readonly _providerPrincipals = new WeakMap<WebSocket, IProviderPrincipal>();
+
+    constructor(options: IWsTunnelOptions) {
         this._options = options;
+        this._authGuard = options.auth ? new HttpAuthGuard(options.auth, options.mcpPath ?? "/mcp") : null;
+        this._providerAuth = options.providerAuth ?? null;
+        this._allowedOrigins = originPredicate(options.allowedOrigins);
+        this._authorization = options.authorization ?? options.auth?.authorization ?? null;
+        this._slotResourceResolver =
+            options.slotResourceResolver ?? this._authorization?.slotResourceResolver ?? options.auth?.slotResourceResolver ?? new DefaultSlotResourceResolver();
     }
 
     // -------------------------------------------------------------------------
-    // BrokerContext implementation
+    // IBrokerContext implementation
     // -------------------------------------------------------------------------
 
     get version(): string {
@@ -383,7 +253,7 @@ export class WsTunnel implements BrokerContext {
         return !!this._options.tls;
     }
 
-    get paths(): BrokerContext["paths"] {
+    get paths(): IBrokerContext["paths"] {
         const o = this._options;
         return {
             provider: o.providerPath ?? "/provider",
@@ -395,21 +265,21 @@ export class WsTunnel implements BrokerContext {
         };
     }
 
-    public getProvidersInfo(): BrokerProviderInfo[] {
-        const out: BrokerProviderInfo[] = [];
+    public getProvidersInfo(): IBrokerProviderInfo[] {
+        const out: IBrokerProviderInfo[] = [];
         for (const [name, state] of this._providers) {
             out.push(this._buildProviderInfo(name, state));
         }
         return out;
     }
 
-    public getProviderInfo(name: string): BrokerProviderInfo | undefined {
+    public getProviderInfo(name: string): IBrokerProviderInfo | undefined {
         const state = this._providers.get(name);
         if (!state) return undefined;
         return this._buildProviderInfo(name, state);
     }
 
-    private _buildProviderInfo(name: string, state: ProviderState): BrokerProviderInfo {
+    private _buildProviderInfo(name: string, state: IProviderState): IBrokerProviderInfo {
         let transport: BrokerProviderTransport;
         let connected: boolean;
 
@@ -432,7 +302,7 @@ export class WsTunnel implements BrokerContext {
             transport,
             connected,
             clientCount: state.wsClients.size,
-            sessionCount: state.sseSessions.size + state.mcpGetSessions.size,
+            sessionCount: state.sseSessions.size + state.httpSessions.size,
             pendingCount: state.pending.size,
         };
     }
@@ -459,7 +329,7 @@ export class WsTunnel implements BrokerContext {
         const state = this._getOrCreateProviderState(name);
         this._loopbackProviders.set(name, transport);
 
-        transport.onMessage = (data: string) => this._routeFromProvider(state, data);
+        transport.onMessage = (data: string) => this._routeFromProvider(state, name, data);
         transport.onClose = () => {
             this._loopbackProviders.delete(name);
             this._failProviderDisconnected(state, name);
@@ -472,14 +342,14 @@ export class WsTunnel implements BrokerContext {
      * broadcast notifications. Used by the aggregate server to fan a single
      * in-process client out to every aggregated provider.
      *
-     * The slot does not need a provider attached yet — `send` returns a
+     * The slot does not need a provider attached yet, `send` returns a
      * JSON-RPC error while the provider is disconnected.
      */
-    public openInternalClient(providerName: string): InternalClient {
+    public openInternalClient(providerName: string): IInternalClient {
         const state = this._getOrCreateProviderState(providerName);
         let closed = false;
 
-        const client: InternalClient = {
+        const client: IInternalClient = {
             onMessage: null,
             onClose: null,
             send: (message: string): void => {
@@ -530,7 +400,7 @@ export class WsTunnel implements BrokerContext {
     get clientCount(): number {
         let n = 0;
         for (const s of this._providers.values()) {
-            n += s.wsClients.size + s.sseSessions.size + s.mcpGetSessions.size;
+            n += s.wsClients.size + s.sseSessions.size + s.httpSessions.size;
         }
         return n;
     }
@@ -559,7 +429,7 @@ export class WsTunnel implements BrokerContext {
             // Disable perMessageDeflate: payloads may be large base64-encoded blobs
             // (snapshots, images) that are already compressed. Deflating them wastes
             // CPU without reducing size, and caused multi-second stalls in practice.
-            this._wss = new WebSocketServer({ server: this._httpServer, perMessageDeflate: false });
+            this._wss = new WebSocketServer({ server: this._httpServer, perMessageDeflate: false, verifyClient: this._makeVerifyClient() });
 
             this._wss.on("connection", (ws: WebSocket, req: IncomingMessage) => {
                 const url = req.url ?? "/";
@@ -568,17 +438,17 @@ export class WsTunnel implements BrokerContext {
 
                 if (url === providersPath || url.startsWith(providersPath + "?")) {
                     // Multiplexed provider: one WebSocket carries N providers via envelopes.
-                    this._onMultiplexProviderConnect(ws);
+                    this._onMultiplexProviderConnect(ws, req);
                 } else if (url.startsWith(providerPath + "/") || url === providerPath) {
                     // Extract name: everything after "<providerPath>/"
                     const raw = url.slice(providerPath.length).replace(/^\//, "");
                     const name = decodeURIComponent(raw.split("?")[0]) || "(unnamed)";
-                    this._onProviderConnect(ws, name);
+                    this._onProviderConnect(ws, name, req);
                 } else {
                     // Raw WS MCP client: URL is "/<providerName>" or "/"
                     const raw = url.replace(/^\//, "").split("?")[0];
                     const name = decodeURIComponent(raw) || "";
-                    this._onClientConnect(ws, name);
+                    this._onClientConnect(ws, name, req);
                 }
             });
 
@@ -590,10 +460,10 @@ export class WsTunnel implements BrokerContext {
                 // Attach configured upstreams (stdio child processes + remote URL
                 // servers). Both implement the Upstream contract, so the wiring
                 // into a provider slot is identical.
-                const wireUpstream = (cfg: { name: string; aggregate?: boolean }, upstream: Upstream): void => {
+                const wireUpstream = (cfg: { name: string; aggregate?: boolean }, upstream: IUpstream): void => {
                     upstream.onMessage = (data) => {
                         const state = this._getOrCreateProviderState(cfg.name);
-                        this._routeFromProvider(state, data);
+                        this._routeFromProvider(state, cfg.name, data);
                     };
                     upstream.onError = (err) => {
                         console.error(`[broker] ${err.message}`);
@@ -615,22 +485,19 @@ export class WsTunnel implements BrokerContext {
                 // stdin carries Claude Desktop's JSON-RPC requests; stdout carries responses.
                 if (this._options.stdioClient) {
                     this._stdioClientProvider = this._options.stdioClient.providerName;
-                    process.stdin.setEncoding("utf8");
-                    process.stdin.on("data", (chunk: string) => {
-                        this._stdioClientBuffer += chunk;
-                        let nl: number;
-                        while ((nl = this._stdioClientBuffer.indexOf("\n")) !== -1) {
-                            const line = this._stdioClientBuffer.slice(0, nl).trim();
-                            this._stdioClientBuffer = this._stdioClientBuffer.slice(nl + 1);
-                            if (line) {
-                                const state = this._getOrCreateProviderState(this._stdioClientProvider!);
-                                this._routeFromStdioClient(state, line);
-                            }
-                        }
-                    });
-                    process.stdin.on("end", () => {
-                        // Client disconnected — nothing to clean up; pending sinks will time out.
-                    });
+                    const transport = new StdioTransport();
+                    this._stdioClientTransport = transport;
+                    transport.onMessage = (data: string): void => {
+                        const state = this._getOrCreateProviderState(this._stdioClientProvider!);
+                        this._routeFromStdioClient(state, data);
+                    };
+                    transport.onError = (err: Error): void => {
+                        console.error(`[broker] stdio client transport: ${err.message}`);
+                    };
+                    transport.onClose = (): void => {
+                        // Client disconnected: nothing to clean up; pending sinks will time out.
+                    };
+                    transport.connect();
                 }
 
                 this._startedAt = new Date();
@@ -652,7 +519,7 @@ export class WsTunnel implements BrokerContext {
     /**
      * Starts the in-process MCP server that exposes the broker's own behaviors
      * (`broker_info`, `providers_list`, `provider_status`) under the reserved
-     * provider slot `_broker`. No-op when {@link WsTunnelOptions.enableBrokerProvider}
+     * provider slot `_broker`. No-op when {@link IWsTunnelOptions.enableBrokerProvider}
      * is `false`.
      */
     private async _maybeStartBrokerServer(): Promise<void> {
@@ -672,12 +539,14 @@ export class WsTunnel implements BrokerContext {
 
     /**
      * Starts the aggregate MCP server and registers it on the reserved `_all`
-     * slot. No-op when {@link WsTunnelOptions.enableAggregateProvider} is `false`.
+     * slot. No-op when {@link IWsTunnelOptions.enableAggregateProvider} is `false`.
      */
     private _maybeStartAggregateServer(): void {
         if (this._options.enableAggregateProvider === false) return;
         try {
             const server = new AggregateServer((providerName) => this.openInternalClient(providerName));
+            server.setScopeFilter(this._options.auth?.aggregateScopeFilter ?? null);
+            server.setPolicyAuthorization(this._authorization);
             server.start();
             this.registerLoopbackProvider(AggregateServer.SLOT, server);
             this._aggregateServer = server;
@@ -714,12 +583,21 @@ export class WsTunnel implements BrokerContext {
             }
         }
 
+        this._stdioClientTransport?.close();
+        this._stdioClientTransport = null;
+        this._stdioClientProvider = null;
+
+        // Streamable HTTP sessions are torn down by the endpoint that owns them,
+        // not by ending their responses here: `closeAll` runs each session's
+        // `stop`, which is what empties `httpSessions`.
+        await Promise.all([...this._providers.values()].map((state) => state.httpEndpoint?.closeAll() ?? Promise.resolve()));
+
         return new Promise((resolve, reject) => {
             for (const state of this._providers.values()) {
                 for (const res of state.sseSessions.values()) res.end();
                 state.sseSessions.clear();
-                for (const res of state.mcpGetSessions.values()) res.end();
-                state.mcpGetSessions.clear();
+                state.httpSessions.clear();
+                state.httpEndpoint = null;
                 for (const client of state.wsClients) client.close();
                 state.wsClients.clear();
                 state.ws?.close();
@@ -736,6 +614,123 @@ export class WsTunnel implements BrokerContext {
         });
     }
 
+    private _authorizationSubject(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] authorization subject mapping failed.");
+            }
+            return { ids: [], claims: principal.claims };
+        }
+    }
+
+    private _auditDecision(
+        subject: IAuthorizationSubject,
+        slot: string,
+        resource: ResourcePath | undefined,
+        capability: string | undefined,
+        tool: string | undefined,
+        decision: IAuthorizationDecision
+    ): void {
+        const authorization = this._authorization;
+        if (!authorization || (decision.allowed && !authorization.audit.logAllowed)) return;
+        writeAuthorizationAuditEvent(
+            makeAuthorizationAuditEvent(
+                {
+                    subject,
+                    slot,
+                    resource,
+                    capability,
+                    provider: slot,
+                    tool,
+                },
+                decision
+            )
+        );
+    }
+
+    /**
+     * Applies hierarchical policy to the MCP operations carried in one
+     * JSON-RPC frame. `_all` performs provider-specific checks internally.
+     */
+    private _authorizeMcpFrame(providerName: string, data: string, principal: IPrincipal | null): boolean {
+        const authorization = this._authorization;
+        if (!authorization || providerName === AggregateServer.SLOT) return true;
+
+        const subject = this._authorizationSubject(principal);
+        const resource = this._slotResourceResolver.resolve(providerName);
+        if (!resource) {
+            const decision: IAuthorizationDecision = { allowed: false, reason: "unknown-resource" };
+            this._auditDecision(subject, providerName, undefined, undefined, undefined, decision);
+            return false;
+        }
+
+        let parsed: unknown;
+        try {
+            parsed = JSON.parse(data) as unknown;
+        } catch {
+            return true;
+        }
+        const operations = Array.isArray(parsed) ? parsed : [parsed];
+        for (const value of operations) {
+            if (typeof value !== "object" || value === null || Array.isArray(value)) continue;
+            const operation = value as Readonly<{ method?: string; params?: unknown }>;
+            try {
+                const classified = authorization.capabilityClassifier.classify(operation, resource, providerName);
+                if (!classified) continue;
+                const decision = authorization.engine.authorize({
+                    subject,
+                    capability: classified.capability,
+                    resource,
+                    provider: providerName,
+                    tool: classified.tool,
+                });
+                this._auditDecision(subject, providerName, resource, classified.capability, classified.tool, decision);
+                if (!decision.allowed) return false;
+            } catch {
+                console.error("[broker] policy evaluation failed.");
+                const decision: IAuthorizationDecision = { allowed: false, reason: "no-matching-grant" };
+                this._auditDecision(subject, providerName, resource, undefined, undefined, decision);
+                return false;
+            }
+        }
+        return true;
+    }
+
+    private _policyDeniedPayload(data: string): string {
+        let id: string | number | null = null;
+        try {
+            const parsed = JSON.parse(data) as { id?: unknown };
+            if (typeof parsed.id === "string" || typeof parsed.id === "number" || parsed.id === null) {
+                id = parsed.id;
+            }
+        } catch {
+            // A malformed frame has no usable request id.
+        }
+        return JSON.stringify({
+            jsonrpc: "2.0",
+            id,
+            error: { code: -32001, message: "Forbidden" },
+        });
+    }
+
+    /** The JSON-RPC error returned when the slot has nobody behind it. */
+    private _notConnectedPayload(providerName: string, frame: string): string {
+        return JSON.stringify({
+            jsonrpc: "2.0",
+            id: requestIdOf(frame) ?? null,
+            error: { code: -32000, message: `Provider "${providerName}" not connected` },
+        });
+    }
+
     // -------------------------------------------------------------------------
     // HTTP dispatcher
     // -------------------------------------------------------------------------
@@ -763,30 +758,34 @@ export class WsTunnel implements BrokerContext {
             return;
         }
 
+        // Protected Resource Metadata (RFC 9728), public discovery data, served
+        // unauthenticated so a client can find the authorization server after a 401.
+        if (this._authGuard && method === "GET") {
+            const metaSlot = this._authGuard.matchMetadataRequest(rawUrl);
+            if (metaSlot) {
+                res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+                res.end(JSON.stringify(this._authGuard.metadataFor(metaSlot)));
+                return;
+            }
+        }
+
         // Route /<providerName>/<endpoint>
         const route = this._parseProviderRoute(rawUrl);
         if (route) {
             const { providerName, endpoint } = route;
-            const mcpSuffix = (this._options.mcpPath ?? "/mcp").replace(/^\//, "");
-            const sseSuffix = (this._options.ssePath ?? "/sse").replace(/^\//, "");
-            const messagesSuffix = (this._options.messagesPath ?? "/messages").replace(/^\//, "");
-
-            if (endpoint === mcpSuffix) {
-                if (method === "GET") {
-                    this._handleMcpGetStream(req, res, providerName);
-                    return;
-                }
-                if (method === "POST") {
-                    this._handleMcpPost(req, res, providerName);
-                    return;
+            const kind = this._mcpEndpointKind(endpoint, method);
+            if (kind) {
+                if (this._authGuard) {
+                    // Gate on a valid bearer token issued for this slot before touching
+                    // the provider. On failure, emit an RFC 9728 challenge / 500.
+                    const guard = this._authGuard;
+                    void guard.authorize(req, providerName).then(
+                        (principal) => this._dispatchMcpEndpoint(kind, req, res, providerName, principal),
+                        (err: unknown) => this._handleAuthFailure(guard, res, providerName, err)
+                    );
+                } else {
+                    this._dispatchMcpEndpoint(kind, req, res, providerName, null);
                 }
-            }
-            if (endpoint === sseSuffix && method === "GET") {
-                this._handleSseConnect(req, res, providerName);
-                return;
-            }
-            if (endpoint === messagesSuffix && method === "POST") {
-                this._handleSseMessage(req, res, providerName);
                 return;
             }
         }
@@ -813,15 +812,142 @@ export class WsTunnel implements BrokerContext {
         return { providerName, endpoint };
     }
 
+    /**
+     * Classifies a `(endpoint, method)` pair as one of the four MCP/SSE client
+     * handlers, or `null` when it is not a client transport request (the caller
+     * then falls through to static-file serving, preserving prior behavior).
+     */
+    private _mcpEndpointKind(endpoint: string, method: string): McpEndpointKind | null {
+        const mcpSuffix = (this._options.mcpPath ?? "/mcp").replace(/^\//, "");
+        const sseSuffix = (this._options.ssePath ?? "/sse").replace(/^\//, "");
+        const messagesSuffix = (this._options.messagesPath ?? "/messages").replace(/^\//, "");
+        // GET, POST and DELETE all belong to the Streamable HTTP state machine.
+        if (endpoint === mcpSuffix) return "mcp";
+        if (endpoint === sseSuffix && method === "GET") return "sse-connect";
+        if (endpoint === messagesSuffix && method === "POST") return "sse-message";
+        return null;
+    }
+
+    /** Routes an already-authorized (or auth-disabled) request to its handler. */
+    private _dispatchMcpEndpoint(kind: McpEndpointKind, req: IncomingMessage, res: ServerResponse, providerName: string, principal: IPrincipal | null): void {
+        switch (kind) {
+            case "mcp":
+                this._handleStreamableHttp(req, res, providerName, principal);
+                return;
+            case "sse-connect":
+                this._handleSseConnect(req, res, providerName, principal);
+                return;
+            case "sse-message":
+                this._handleSseMessage(req, res, providerName, principal);
+                return;
+        }
+    }
+
+    /** Turns a rejected {@link HttpAuthGuard.authorize} into an HTTP response. */
+    private _handleAuthFailure(guard: HttpAuthGuard, res: ServerResponse, providerName: string, err: unknown): void {
+        if (err instanceof AuthError) {
+            guard.writeChallenge(res, providerName, err);
+            return;
+        }
+        // Not a token failure (e.g. the JWKS endpoint is unreachable), surface a
+        // 500 rather than a misleading 401.
+        console.error(`[broker] token validation error for "${providerName}":`, err);
+        res.writeHead(500, { "Content-Type": "application/json; charset=utf-8" });
+        res.end(JSON.stringify({ error: "server_error" }));
+    }
+
+    /**
+     * Builds the `ws` verifyClient hook that authenticates every WebSocket
+     * upgrade before the connection is accepted, returning a real `401`/`403`
+     * during the handshake rather than a post-handshake close:
+     *
+     * - **Raw MCP clients** (`/<slot>`) are gated by the OAuth 2.1 resource
+     *   server ({@link _authGuard}) with the RFC 9728 `WWW-Authenticate` challenge.
+     * - **Providers** (`/provider/<slot>`, `/providers`) are gated by the
+     *   {@link _providerAuth} shared-secret / custom authenticator.
+     *
+     * Each side is independent: a branch with no authenticator configured is let
+     * through unchanged. Returns `undefined` (no hook) when neither is set.
+     */
+    private _makeVerifyClient(): VerifyClientCallbackAsync | undefined {
+        const guard = this._authGuard;
+        const providerAuth = this._providerAuth;
+        if (!guard && !providerAuth) return undefined;
+
+        const providerPath = this._options.providerPath ?? "/provider";
+        const providersPath = this._options.providersPath ?? "/providers";
+
+        return (info, cb) => {
+            const url = info.req.url ?? "/";
+            const isMultiplex = url === providersPath || url.startsWith(providersPath + "?");
+            const isDedicated = url.startsWith(providerPath + "/") || url === providerPath;
+
+            if (isMultiplex || isDedicated) {
+                // Provider (engine) upgrade, shared-secret / custom authenticator.
+                if (!providerAuth) {
+                    cb(true);
+                    return;
+                }
+                const slot = isDedicated ? decodeURIComponent(url.slice(providerPath.length).replace(/^\//, "").split("?")[0]) || undefined : undefined;
+                Promise.resolve(providerAuth.authenticate(info.req, slot)).then(
+                    (rawResult) => {
+                        const result = normalizeProviderAuthentication(rawResult);
+                        if (!result.authenticated) {
+                            cb(false, 401, "Unauthorized", { "WWW-Authenticate": 'Bearer realm="provider"' });
+                            return;
+                        }
+                        if (slot !== undefined) {
+                            const resource = this._slotResourceResolver.resolve(slot);
+                            if (!resource || !providerMayPublish(result.principal, resource)) {
+                                this._logProviderRegistration(result.principal, slot, resource, false);
+                                cb(false, 403, "Forbidden");
+                                return;
+                            }
+                        }
+                        this._pendingProviderPrincipals.set(info.req, result.principal);
+                        cb(true);
+                    },
+                    () => {
+                        console.error(`[broker] provider authentication error for "${slot ?? "(multiplex)"}".`);
+                        cb(false, 500, "server_error");
+                    }
+                );
+                return;
+            }
+
+            // Raw WS MCP client upgrade, OAuth 2.1 resource server.
+            if (!guard) {
+                cb(true);
+                return;
+            }
+            const slot = decodeURIComponent(url.replace(/^\//, "").split("?")[0]);
+            void guard.authorize(info.req, slot).then(
+                (principal) => {
+                    // Stash the principal so _onClientConnect can bind it to the socket.
+                    this._pendingClientPrincipals.set(info.req, principal);
+                    cb(true);
+                },
+                (err: unknown) => {
+                    if (err instanceof AuthError) {
+                        cb(false, err.status, err.code, { "WWW-Authenticate": guard.challengeHeader(slot, err) });
+                    } else {
+                        console.error(`[broker] token validation error for WS client "${slot}":`, err);
+                        cb(false, 500, "server_error");
+                    }
+                }
+            );
+        };
+    }
+
     // -------------------------------------------------------------------------
     // MCP / SSE transport (per provider)
     // -------------------------------------------------------------------------
 
     /**
-     * Handles `GET /<providerName>/sse` — opens a long-lived SSE stream for Claude.
+     * Handles `GET /<providerName>/sse`, opens a long-lived SSE stream for Claude.
      * Sends an `endpoint` event so Claude knows where to POST its requests.
      */
-    private _handleSseConnect(req: IncomingMessage, res: ServerResponse, providerName: string): void {
+    private _handleSseConnect(req: IncomingMessage, res: ServerResponse, providerName: string, principal: IPrincipal | null): void {
         const sessionId = randomUUID();
         const messagesSuffix = (this._options.messagesPath ?? "/messages").replace(/^\//, "");
         const messagesUrl = `/${encodeURIComponent(providerName)}/${messagesSuffix}`;
@@ -835,6 +961,7 @@ export class WsTunnel implements BrokerContext {
 
         const state = this._getOrCreateProviderState(providerName);
         state.sseSessions.set(sessionId, res);
+        if (principal) this._streamPrincipals.set(res, principal);
 
         req.on("close", () => {
             state.sseSessions.delete(sessionId);
@@ -845,11 +972,11 @@ export class WsTunnel implements BrokerContext {
     }
 
     /**
-     * Handles `POST /<providerName>/messages?sessionId=…` — receives a JSON-RPC
+     * Handles `POST /<providerName>/messages?sessionId=…`, receives a JSON-RPC
      * request from Claude and forwards it to the provider.
      * Always responds 202 Accepted; the real response arrives over SSE.
      */
-    private _handleSseMessage(req: IncomingMessage, res: ServerResponse, providerName: string): void {
+    private _handleSseMessage(req: IncomingMessage, res: ServerResponse, providerName: string, principal: IPrincipal | null): void {
         const params = new URL(req.url ?? "", "http://localhost").searchParams;
         const sessionId = params.get("sessionId") ?? "";
         const state = this._getOrCreateProviderState(providerName);
@@ -865,15 +992,20 @@ export class WsTunnel implements BrokerContext {
             body += chunk.toString();
         });
         req.on("end", () => {
+            if (!this._authorizeMcpFrame(providerName, body, principal)) {
+                res.writeHead(403, { "Content-Type": "application/json; charset=utf-8" });
+                res.end(this._policyDeniedPayload(body));
+                return;
+            }
             try {
                 const msg = JSON.parse(body) as { id?: string | number };
                 if (msg.id != null) state.pending.set(msg.id, { type: "sse", sessionId });
             } catch {
-                /* malformed — forward anyway */
+                /* malformed, forward anyway */
             }
 
             if (this._isProviderConnected(providerName, state)) {
-                this._sendToProvider(state, providerName, body);
+                this._sendToProvider(state, providerName, body, principal);
             } else {
                 const sseRes = state.sseSessions.get(sessionId);
                 if (sseRes) {
@@ -900,79 +1032,94 @@ export class WsTunnel implements BrokerContext {
     }
 
     /**
-     * Handles `POST /<providerName>/mcp` — Streamable HTTP transport (MCP 2025-03-26).
-     * Forwards the JSON-RPC request to the provider and holds the HTTP response
-     * open until the reply arrives, then writes it as `application/json`.
+     * Serves `/<providerName>/mcp` by handing the request to the slot's
+     * Streamable HTTP endpoint.
+     *
+     * Everything protocol-shaped, sessions, `Mcp-Session-Id`, `DELETE`, the
+     * `404` on a terminated session, `Origin` and `MCP-Protocol-Version`
+     * validation, `202` on a notification, belongs to `mcp-core` and is no
+     * longer reimplemented here. What stays is the broker's own business:
+     * deciding who may speak (already done upstream by the auth guard) and
+     * relaying frames to a provider that lives somewhere else entirely.
      */
-    private _handleMcpPost(req: IncomingMessage, res: ServerResponse, providerName: string): void {
-        let body = "";
-        req.on("data", (chunk: Buffer) => {
-            body += chunk.toString();
-        });
-        req.on("end", () => {
-            let msg: { id?: string | number } = {};
-            try {
-                msg = JSON.parse(body) as { id?: string | number };
-            } catch {
-                res.writeHead(400, { "Content-Type": "text/plain" });
-                res.end("Invalid JSON");
-                return;
-            }
-
-            const state = this._getOrCreateProviderState(providerName);
-
-            if (!this._isProviderConnected(providerName, state)) {
-                res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
-                res.end(
-                    JSON.stringify({
-                        jsonrpc: "2.0",
-                        id: msg.id ?? null,
-                        error: { code: -32000, message: `Provider "${providerName}" not connected` },
-                    })
-                );
-                return;
-            }
+    private _handleStreamableHttp(req: IncomingMessage, res: ServerResponse, providerName: string, principal: IPrincipal | null): void {
+        const state = this._getOrCreateProviderState(providerName);
 
-            if (msg.id != null) {
-                // Request: hold the response open; reply arrives in _routeFromProvider.
-                state.pending.set(msg.id, { type: "http", res });
-            } else {
-                // Notification: forward and acknowledge immediately.
-                res.writeHead(202);
-                res.end();
-            }
+        // The endpoint authenticates nothing: this broker has its own guard,
+        // richer than the spec's (per-slot scopes, subject mapping into the
+        // policy engine). So the principal is attached to the session here,
+        // refreshed on every request, and read back when a frame is checked.
+        const sessionId = req.headers["mcp-session-id"];
+        if (typeof sessionId === "string") {
+            const session = state.httpSessions.get(sessionId);
+            if (session) session.principal = principal;
+        }
 
-            this._sendToProvider(state, providerName, body);
-        });
+        void this._endpointFor(providerName, state).handleRequest(req, res);
     }
 
     /**
-     * Handles `GET /<providerName>/mcp` — opens a persistent SSE stream per MCP 2025-03-26.
-     * Streamable HTTP clients (e.g. MCP Inspector) use this to receive
-     * server-initiated notifications without re-polling.
+     * The slot's Streamable HTTP endpoint, built on first use.
+     *
+     * Its factory does not create an MCP server: the server is the provider,
+     * reachable only through the tunnel. It creates a bridge instead: frames the
+     * client sends go out to the provider, and frames coming back are addressed
+     * to this session by id.
      */
-    private _handleMcpGetStream(req: IncomingMessage, res: ServerResponse, providerName: string): void {
-        const sessionId = (req.headers["mcp-session-id"] as string | undefined) ?? randomUUID();
-
-        res.writeHead(200, {
-            "Content-Type": "text/event-stream",
-            "Cache-Control": "no-cache, no-transform",
-            Connection: "keep-alive",
-            "Mcp-Session-Id": sessionId,
+    private _endpointFor(providerName: string, state: IProviderState): StreamableHttpEndpoint {
+        if (state.httpEndpoint) return state.httpEndpoint;
+
+        state.httpEndpoint = new StreamableHttpEndpoint({
+            allowedOrigins: this._allowedOrigins,
+
+            createServer: (transport, sessionId, _principal) => {
+                const session: IHttpSession = { transport, principal: null };
+                state.httpSessions.set(sessionId, session);
+
+                transport.onMessage = (frame: string) => this._fromHttpSession(state, providerName, sessionId, session, frame);
+
+                return {
+                    // No server to launch: the one serving this session is the
+                    // provider, at the far end of the tunnel. What `start` still
+                    // owes is opening the transport, since a closed one drops
+                    // every frame it is handed.
+                    start: () => openTransport(transport),
+                    stop: () => {
+                        state.httpSessions.delete(sessionId);
+                        // Nothing can answer the requests this session had in
+                        // flight; leaving them would pin the ids forever.
+                        for (const [id, sink] of state.pending) {
+                            if (sink.type === "http-session" && sink.sessionId === sessionId) state.pending.delete(id);
+                        }
+                    },
+                };
+            },
         });
-        res.write(": stream open\n\n");
 
-        const state = this._getOrCreateProviderState(providerName);
-        state.mcpGetSessions.set(sessionId, res);
+        return state.httpEndpoint;
+    }
 
-        req.on("close", () => {
-            state.mcpGetSessions.delete(sessionId);
-        });
+    /** Relays one frame from an HTTP session to the provider behind the slot. */
+    private _fromHttpSession(state: IProviderState, providerName: string, sessionId: string, session: IHttpSession, frame: string): void {
+        if (!this._authorizeMcpFrame(providerName, frame, session.principal)) {
+            session.transport.send(this._policyDeniedPayload(frame));
+            return;
+        }
+
+        if (!this._isProviderConnected(providerName, state)) {
+            session.transport.send(this._notConnectedPayload(providerName, frame));
+            return;
+        }
+
+        const id = requestIdOf(frame);
+        if (id !== undefined) state.pending.set(id, { type: "http-session", sessionId });
+
+        this._sendToProvider(state, providerName, frame, session.principal);
     }
 
     /** Writes one JSON-RPC message as an SSE `message` event. */
     private _sendSseEvent(res: ServerResponse, data: string): void {
-        // data is already a compact JSON string — no need to parse+re-serialize.
+        // data is already a compact JSON string: no need to parse+re-serialize.
         res.write(`event: message\ndata: ${data}\n\n`);
     }
 
@@ -980,18 +1127,35 @@ export class WsTunnel implements BrokerContext {
     // WebSocket connection handlers
     // -------------------------------------------------------------------------
 
-    private _onProviderConnect(ws: WebSocket, name: string): void {
+    private _logProviderRegistration(principal: IProviderPrincipal, slot: string, resource: ResourcePath | undefined, allowed: boolean): void {
+        const event = {
+            timestamp: new Date().toISOString(),
+            providerId: principal.id,
+            slot,
+            resource: resource?.value,
+            allowed,
+        };
+        const line = `[broker] provider-registration ${JSON.stringify(event)}`;
+        if (allowed) console.info(line);
+        else console.warn(line);
+    }
+
+    private _onProviderConnect(ws: WebSocket, name: string, req: IncomingMessage): void {
+        const providerPrincipal = this._pendingProviderPrincipals.get(req);
+        if (providerPrincipal) {
+            this._pendingProviderPrincipals.delete(req);
+            this._providerPrincipals.set(ws, providerPrincipal);
+        }
         if (this._upstreams.has(name)) {
             console.warn(
-                `[broker] WARNING: WebSocket provider "${name}" rejected — a stdio upstream with the same name is already configured. ` +
-                    `Rename one of them to avoid the conflict.`
+                `[broker] WARNING: WebSocket provider "${name}" rejected: a stdio upstream with the same name is already configured. ` + `Rename one of them to avoid the conflict.`
             );
             ws.close(1008, `Provider "${name}" is managed by a stdio upstream`);
             return;
         }
 
         if (this._loopbackProviders.has(name)) {
-            console.warn(`[broker] WARNING: WebSocket provider "${name}" rejected — the slot is held by an in-process loopback (reserved system slot).`);
+            console.warn(`[broker] WARNING: WebSocket provider "${name}" rejected: the slot is held by an in-process loopback (reserved system slot).`);
             ws.close(1008, `Provider "${name}" is reserved by the broker`);
             return;
         }
@@ -1004,10 +1168,13 @@ export class WsTunnel implements BrokerContext {
 
         const state = this._getOrCreateProviderState(name);
         state.ws = ws;
+        if (providerPrincipal) {
+            this._logProviderRegistration(providerPrincipal, name, this._slotResourceResolver.resolve(name), true);
+        }
 
         // A provider MAY send a registration control frame as its very first
-        // message (see _tryHandleRegistration). Any other first message —
-        // including a normal MCP frame — is routed and leaves the provider
+        // message (see _tryHandleRegistration). Any other first message ,
+        // including a normal MCP frame, is routed and leaves the provider
         // non-aggregated, so every pre-existing provider keeps working.
         let registrationChecked = false;
         ws.on("message", (data: Buffer) => {
@@ -1016,7 +1183,7 @@ export class WsTunnel implements BrokerContext {
                 registrationChecked = true;
                 if (this._tryHandleRegistration(name, text)) return;
             }
-            this._routeFromProvider(state, text);
+            this._routeFromProvider(state, name, text);
         });
 
         ws.on("close", () => {
@@ -1028,7 +1195,7 @@ export class WsTunnel implements BrokerContext {
     /**
      * Inspects a provider's first WebSocket message for an optional registration
      * control frame `{ "type": "register", "aggregate": boolean }`. Returns
-     * `true` when the message was a registration frame — and thus consumed, not
+     * `true` when the message was a registration frame: and thus consumed, not
      * routed as MCP traffic. A normal MCP frame always carries `jsonrpc`, so it
      * returns `false` and the provider stays non-aggregated.
      */
@@ -1046,10 +1213,18 @@ export class WsTunnel implements BrokerContext {
         return true;
     }
 
-    private _onClientConnect(ws: WebSocket, providerName: string): void {
+    private _onClientConnect(ws: WebSocket, providerName: string, req: IncomingMessage): void {
         const state = this._getOrCreateProviderState(providerName);
         state.wsClients.add(ws);
 
+        // Carry the principal captured at the upgrade onto the socket, so requests
+        // this client makes to `_all` can be scope-filtered.
+        const principal = this._pendingClientPrincipals.get(req);
+        if (principal) {
+            this._clientPrincipals.set(ws, principal);
+            this._pendingClientPrincipals.delete(req);
+        }
+
         ws.on("message", (data: Buffer) => this._routeFromClient(ws, state, providerName, data.toString()));
 
         ws.on("close", () => {
@@ -1066,77 +1241,61 @@ export class WsTunnel implements BrokerContext {
      * envelope format `{ provider: string, payload: object }`.
      * Provider names are registered lazily on first message.
      */
-    private _onMultiplexProviderConnect(ws: WebSocket): void {
+    private _onMultiplexProviderConnect(ws: WebSocket, req: IncomingMessage): void {
         const providerNames = new Set<string>();
         this._multiplexSockets.set(ws, providerNames);
+        const providerPrincipal = this._pendingProviderPrincipals.get(req);
+        if (providerPrincipal) {
+            this._pendingProviderPrincipals.delete(req);
+            this._providerPrincipals.set(ws, providerPrincipal);
+        }
 
         ws.on("message", (data: Buffer) => {
-            let envelope: { provider?: string; payload?: unknown };
-            try {
-                envelope = JSON.parse(data.toString()) as { provider?: string; payload?: unknown };
-            } catch {
-                return; // malformed — drop
-            }
+            const envelope = decodeEnvelope(data.toString());
+            if (!envelope) return; // malformed, drop
 
             const name = envelope.provider;
-            if (!name || envelope.payload === undefined) return;
 
             // Register provider name lazily on first encounter.
             if (!providerNames.has(name)) {
+                if (providerPrincipal) {
+                    const resource = this._slotResourceResolver.resolve(name);
+                    if (!resource || !providerMayPublish(providerPrincipal, resource)) {
+                        this._logProviderRegistration(providerPrincipal, name, resource, false);
+                        ws.send(encodeErrorEnvelope(name, TunnelErrorCodes.RegistrationForbidden, "Provider registration forbidden"));
+                        return;
+                    }
+                }
                 if (this._upstreams.has(name)) {
                     console.warn(
-                        `[broker] WARNING: Multiplexed WebSocket provider "${name}" rejected — a stdio upstream with the same name is already configured. ` +
+                        `[broker] WARNING: Multiplexed WebSocket provider "${name}" rejected: a stdio upstream with the same name is already configured. ` +
                             `Rename one of them to avoid the conflict.`
                     );
-                    ws.send(
-                        JSON.stringify({
-                            provider: name,
-                            payload: {
-                                jsonrpc: "2.0",
-                                id: null,
-                                error: { code: -32000, message: `Provider "${name}" is managed by a stdio upstream` },
-                            },
-                        })
-                    );
+                    ws.send(encodeErrorEnvelope(name, TunnelErrorCodes.ProviderUnavailable, `Provider "${name}" is managed by a stdio upstream`));
                     return;
                 }
 
                 if (this._loopbackProviders.has(name)) {
-                    ws.send(
-                        JSON.stringify({
-                            provider: name,
-                            payload: {
-                                jsonrpc: "2.0",
-                                id: null,
-                                error: { code: -32000, message: `Provider "${name}" is reserved by the broker` },
-                            },
-                        })
-                    );
+                    ws.send(encodeErrorEnvelope(name, TunnelErrorCodes.ProviderUnavailable, `Provider "${name}" is reserved by the broker`));
                     return;
                 }
 
                 const existing = this._providers.get(name);
                 if (existing?.ws?.readyState === WebSocket.OPEN) {
-                    // Provider already connected via another socket — reject this name.
-                    ws.send(
-                        JSON.stringify({
-                            provider: name,
-                            payload: {
-                                jsonrpc: "2.0",
-                                id: null,
-                                error: { code: -32000, message: `Provider "${name}" is already connected` },
-                            },
-                        })
-                    );
+                    // Provider already connected via another socket, reject this name.
+                    ws.send(encodeErrorEnvelope(name, TunnelErrorCodes.ProviderUnavailable, `Provider "${name}" is already connected`));
                     return;
                 }
                 providerNames.add(name);
                 const state = this._getOrCreateProviderState(name);
                 state.ws = ws;
+                if (providerPrincipal) {
+                    this._logProviderRegistration(providerPrincipal, name, this._slotResourceResolver.resolve(name), true);
+                }
             }
 
             const state = this._providers.get(name)!;
-            this._routeFromProvider(state, JSON.stringify(envelope.payload));
+            this._routeFromProvider(state, name, envelopeFrame(envelope));
         });
 
         ws.on("close", () => {
@@ -1159,7 +1318,15 @@ export class WsTunnel implements BrokerContext {
      * Sends a raw JSON-RPC message to a provider, wrapping it in a multiplex
      * envelope when the provider's WebSocket is a multiplexed connection.
      */
-    private _sendToProvider(state: ProviderState, providerName: string, data: string): void {
+    private _sendToProvider(state: IProviderState, providerName: string, data: string, principal: IPrincipal | null = null): void {
+        // The `_all` aggregate is a loopback, but it needs the caller's principal
+        // to scope its catalog/routing, hand it off directly rather than through
+        // the generic transport, which would drop the context.
+        if (providerName === AggregateServer.SLOT && this._aggregateServer) {
+            this._aggregateServer.sendAs(data, principal);
+            return;
+        }
+
         // Upstreams (stdio child processes and remote URL servers) take priority.
         const upstream = this._upstreams.get(providerName);
         if (upstream?.isOpen) {
@@ -1178,14 +1345,13 @@ export class WsTunnel implements BrokerContext {
 
         if (this._multiplexSockets.has(state.ws)) {
             // Wrap in envelope for the multiplexed socket.
-            const payload = JSON.parse(data) as unknown;
-            state.ws.send(JSON.stringify({ provider: providerName, payload }));
+            state.ws.send(encodeEnvelope(providerName, data));
         } else {
             state.ws.send(data);
         }
     }
 
-    private _routeFromStdioClient(state: ProviderState, data: string): void {
+    private _routeFromStdioClient(state: IProviderState, data: string): void {
         try {
             const msg = JSON.parse(data) as { id?: string | number };
             if (msg?.id != null) state.pending.set(msg.id, { type: "stdio" });
@@ -1203,18 +1369,24 @@ export class WsTunnel implements BrokerContext {
                 /* */
             }
             if (errId != null) {
-                process.stdout.write(
+                this._stdioClientTransport?.send(
                     JSON.stringify({
                         jsonrpc: "2.0",
                         id: errId,
                         error: { code: -32000, message: `Provider "${this._stdioClientProvider}" not connected` },
-                    }) + "\n"
+                    })
                 );
             }
         }
     }
 
-    private _routeFromClient(client: WebSocket, state: ProviderState, providerName: string, data: string): void {
+    private _routeFromClient(client: WebSocket, state: IProviderState, providerName: string, data: string): void {
+        const principal = this._clientPrincipals.get(client) ?? null;
+        if (!this._authorizeMcpFrame(providerName, data, principal)) {
+            client.send(this._policyDeniedPayload(data));
+            return;
+        }
+
         try {
             const msg = JSON.parse(data) as { id?: string | number };
             if (msg?.id != null) state.pending.set(msg.id, { type: "ws", socket: client });
@@ -1223,7 +1395,7 @@ export class WsTunnel implements BrokerContext {
         }
 
         if (this._isProviderConnected(providerName, state)) {
-            this._sendToProvider(state, providerName, data);
+            this._sendToProvider(state, providerName, data, principal);
         } else {
             client.send(
                 JSON.stringify({
@@ -1235,7 +1407,7 @@ export class WsTunnel implements BrokerContext {
         }
     }
 
-    private _routeFromProvider(state: ProviderState, data: string): void {
+    private _routeFromProvider(state: IProviderState, providerName: string, data: string): void {
         try {
             const msg = JSON.parse(data) as { id?: string | number };
 
@@ -1247,41 +1419,53 @@ export class WsTunnel implements BrokerContext {
                 } else if (sink?.type === "sse") {
                     const sseRes = state.sseSessions.get(sink.sessionId);
                     if (sseRes) this._sendSseEvent(sseRes, data);
-                } else if (sink?.type === "http") {
-                    sink.res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
-                    sink.res.end(data);
+                } else if (sink?.type === "http-session") {
+                    // The session transport decides whether this answers a held-open
+                    // POST or travels on the GET stream: it correlates by id.
+                    state.httpSessions.get(sink.sessionId)?.transport.send(data);
                 } else if (sink?.type === "stdio") {
-                    process.stdout.write(data + "\n");
+                    this._stdioClientTransport?.send(data);
                 } else if (sink?.type === "internal") {
                     sink.client.onMessage?.(data);
                 }
                 state.pending.delete(msg.id);
             } else {
                 // Notification (no id): broadcast to all clients of this provider.
-                this._broadcast(state, data);
+                this._broadcast(state, providerName, data);
             }
         } catch {
-            this._broadcast(state, data);
+            this._broadcast(state, providerName, data);
         }
     }
 
     /** Sends a message to all clients connected to one provider. */
-    private _broadcast(state: ProviderState, data: string): void {
+    private _broadcast(state: IProviderState, providerName: string, data: string): void {
         for (const client of state.wsClients) {
-            if (client.readyState === WebSocket.OPEN) client.send(data);
+            const principal = this._clientPrincipals.get(client) ?? null;
+            if (client.readyState === WebSocket.OPEN && this._authorizeMcpFrame(providerName, data, principal)) {
+                client.send(data);
+            }
         }
         for (const sseRes of state.sseSessions.values()) {
-            this._sendSseEvent(sseRes, data);
+            const principal = this._streamPrincipals.get(sseRes) ?? null;
+            if (this._authorizeMcpFrame(providerName, data, principal)) {
+                this._sendSseEvent(sseRes, data);
+            }
         }
-        for (const mcpRes of state.mcpGetSessions.values()) {
-            this._sendSseEvent(mcpRes, data);
+        for (const session of state.httpSessions.values()) {
+            // The principal rides on the session here rather than in a WeakMap
+            // keyed by the response: a Streamable HTTP session spans many HTTP
+            // exchanges, so there is no single response to hang it on.
+            if (this._authorizeMcpFrame(providerName, data, session.principal)) {
+                session.transport.send(data);
+            }
         }
         for (const ic of state.internalClients) {
             ic.onMessage?.(data);
         }
         // Forward notifications to the stdio client if it is watching this provider.
         if (this._stdioClientProvider && this._providers.get(this._stdioClientProvider) === state) {
-            process.stdout.write(data + "\n");
+            this._stdioClientTransport?.send(data);
         }
     }
 
@@ -1290,21 +1474,25 @@ export class WsTunnel implements BrokerContext {
      * has disconnected, then clears the pending map. Shared by all provider
      * close handlers (dedicated WS, multiplexed WS, loopback).
      */
-    private _failProviderDisconnected(state: ProviderState, name: string): void {
-        const error = JSON.stringify({
-            jsonrpc: "2.0",
-            id: null,
-            error: { code: -32000, message: `Provider "${name}" disconnected` },
-        });
-        for (const sink of state.pending.values()) {
+    private _failProviderDisconnected(state: IProviderState, name: string): void {
+        // Echoing the pending id rather than `null`: a Streamable HTTP session
+        // matches the answer to its held-open POST by id, so an unaddressed
+        // error would leave that request hanging until it times out.
+        for (const [id, sink] of state.pending) {
+            const error = JSON.stringify({
+                jsonrpc: "2.0",
+                id,
+                error: { code: -32000, message: `Provider "${name}" disconnected` },
+            });
             if (sink.type === "ws" && sink.socket.readyState === WebSocket.OPEN) {
                 sink.socket.send(error);
             } else if (sink.type === "sse") {
                 const sseRes = state.sseSessions.get(sink.sessionId);
                 if (sseRes) this._sendSseEvent(sseRes, error);
-            } else if (sink.type === "http") {
-                sink.res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
-                sink.res.end(error);
+            } else if (sink.type === "http-session") {
+                state.httpSessions.get(sink.sessionId)?.transport.send(error);
+            } else if (sink.type === "stdio") {
+                this._stdioClientTransport?.send(error);
             } else if (sink.type === "internal") {
                 sink.client.onMessage?.(error);
             }
@@ -1318,10 +1506,10 @@ export class WsTunnel implements BrokerContext {
     // -------------------------------------------------------------------------
 
     /**
-     * Returns `true` if the provider is reachable — via a WebSocket connection,
+     * Returns `true` if the provider is reachable, via a WebSocket connection,
      * a stdio upstream, or an in-process loopback transport.
      */
-    private _isProviderConnected(providerName: string, state: ProviderState): boolean {
+    private _isProviderConnected(providerName: string, state: IProviderState): boolean {
         if (this._upstreams.get(providerName)?.isOpen) return true;
         if (this._loopbackProviders.get(providerName)?.isOpen) return true;
         if (state.ws?.readyState === WebSocket.OPEN) return true;
@@ -1329,16 +1517,17 @@ export class WsTunnel implements BrokerContext {
     }
 
     /** Returns the state for `name`, creating it lazily if it doesn't exist yet. */
-    private _getOrCreateProviderState(name: string): ProviderState {
+    private _getOrCreateProviderState(name: string): IProviderState {
         let state = this._providers.get(name);
         if (!state) {
             state = {
                 ws: null,
                 pending: new Map(),
                 sseSessions: new Map(),
-                mcpGetSessions: new Map(),
+                httpSessions: new Map(),
                 wsClients: new Set(),
                 internalClients: new Set(),
+                httpEndpoint: null,
             };
             this._providers.set(name, state);
         }