@cyanmycelium/mcp-broker 1.0.1 → 1.2.0

package/dist/chunk-FTDKH2C4.js

@@ -0,0 +1,3670 @@
+import * as fs from 'fs';
+import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, writeFileSync, rmSync } from 'fs';
+import * as http from 'http';
+import * as https from 'https';
+import * as nodePath from 'path';
+import { join, dirname, resolve, relative, isAbsolute, sep } from 'path';
+import { randomUUID, timingSafeEqual, X509Certificate, createPublicKey, verify } from 'crypto';
+import { WebSocket, WebSocketServer } from 'ws';
+import { StdioTransport, StreamableHttpEndpoint } from '@cyanmycelium/mcp-core/node';
+import { spawn } from 'child_process';
+import { McpAuthError, McpGrammar, McpBehavior, LoopbackTransport, McpServerBuilder, scopesOf as scopesOf$1, buildProtectedResourceMetadata, PROTECTED_RESOURCE_METADATA_PREFIX, bearerToken, buildChallengeHeader, McpAdapterBase, McpToolResults } from '@cyanmycelium/mcp-core';
+import { fileURLToPath } from 'url';
+import { createRemoteJWKSet, jwtVerify, errors } from 'jose';
+import { createRequire } from 'module';
+import { homedir } from 'os';
+import { inflateRawSync } from 'zlib';
+
+// src/ws/ws.tunnel.ts
+
+// ../provider/dist/protocol/index.js
+var TunnelErrorCodes = {
+  /** The slot is taken by another upstream, or the provider is not connected. */
+  ProviderUnavailable: -32e3,
+  /** The provider's credentials do not allow publishing on this slot. */
+  RegistrationForbidden: -32001
+};
+function encodeEnvelope(provider, frame) {
+  return encodeEnvelopeMessage(provider, JSON.parse(frame));
+}
+function encodeEnvelopeMessage(provider, payload) {
+  const envelope = { provider, payload };
+  return JSON.stringify(envelope);
+}
+function decodeEnvelope(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return void 0;
+  const { provider, payload } = parsed;
+  if (typeof provider !== "string" || provider.length === 0 || payload === void 0) return void 0;
+  return { provider, payload };
+}
+function envelopeFrame(envelope) {
+  return JSON.stringify(envelope.payload);
+}
+function encodeErrorEnvelope(provider, code, message) {
+  return encodeEnvelopeMessage(provider, { jsonrpc: "2.0", id: null, error: { code, message } });
+}
+var StdioUpstream = class {
+  name;
+  _config;
+  _proc = null;
+  _buffer = "";
+  _open = false;
+  _stopped = false;
+  /** Called when a complete JSON-RPC line arrives from the process stdout. */
+  onMessage = null;
+  /** Called when the process has started and stdin is writable. */
+  onOpen = null;
+  /** Called when the process exits (cleanly or otherwise). */
+  onClose = null;
+  /** Called on spawn or runtime errors. */
+  onError = null;
+  constructor(config) {
+    this.name = config.name;
+    this._config = config;
+  }
+  get isOpen() {
+    return this._open;
+  }
+  /** Spawns the child process and wires up stdio listeners. */
+  connect() {
+    this._stopped = false;
+    const { command, args = [], env } = this._config;
+    this._proc = spawn(command, args, {
+      env: { ...process.env, ...env },
+      stdio: ["pipe", "pipe", "inherit"]
+    });
+    this._proc.on("error", (err) => {
+      this._open = false;
+      this.onError?.(new Error(`StdioUpstream "${this.name}": process error, ${err.message}`));
+    });
+    this._proc.on("spawn", () => {
+      this._open = true;
+      this.onOpen?.();
+    });
+    this._proc.stdout.on("data", (chunk) => {
+      this._buffer += chunk.toString("utf8");
+      let nl;
+      while ((nl = this._buffer.indexOf("\n")) !== -1) {
+        const line = this._buffer.slice(0, nl).trim();
+        this._buffer = this._buffer.slice(nl + 1);
+        if (line) this.onMessage?.(line);
+      }
+    });
+    this._proc.on("close", (code) => {
+      this._open = false;
+      this._proc = null;
+      this.onClose?.();
+      if (!this._stopped) {
+        this.onError?.(new Error(`StdioUpstream "${this.name}": process exited with code ${code ?? "null"}`));
+      }
+    });
+  }
+  /** Sends a JSON-RPC message to the process stdin (appends newline). */
+  send(data) {
+    if (!this._open || !this._proc?.stdin?.writable) return;
+    this._proc.stdin.write(data + "\n", "utf8");
+  }
+  /** Kills the child process and prevents further reconnection attempts. */
+  close() {
+    this._stopped = true;
+    this._open = false;
+    this._proc?.stdin?.end();
+    this._proc?.kill();
+    this._proc = null;
+  }
+};
+function makeRequest(url, options, onResponse) {
+  return url.protocol === "https:" ? https.request(url, options, onResponse) : http.request(url, options, onResponse);
+}
+var SseDecoder = class {
+  _buf = "";
+  feed(chunk, emit) {
+    this._buf += chunk.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    let sep3;
+    while ((sep3 = this._buf.indexOf("\n\n")) !== -1) {
+      const block = this._buf.slice(0, sep3);
+      this._buf = this._buf.slice(sep3 + 2);
+      let event = "message";
+      const data = [];
+      for (const line of block.split("\n")) {
+        if (line.startsWith(":")) continue;
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? "" : line.slice(colon + 1);
+        if (value.startsWith(" ")) value = value.slice(1);
+        if (field === "event") event = value;
+        else if (field === "data") data.push(value);
+      }
+      if (data.length > 0) emit(event, data.join("\n"));
+    }
+  }
+};
+var WebSocketRemoteTransport = class {
+  constructor(_url, _headers) {
+    this._url = _url;
+    this._headers = _headers;
+  }
+  _url;
+  _headers;
+  onMessage = null;
+  onOpen = null;
+  onClose = null;
+  onError = null;
+  _ws = null;
+  connect() {
+    const ws = new WebSocket(this._url, { headers: this._headers });
+    this._ws = ws;
+    ws.on("open", () => this.onOpen?.());
+    ws.on("message", (data) => this.onMessage?.(data.toString("utf8")));
+    ws.on("close", () => this.onClose?.());
+    ws.on("error", (err) => this.onError?.(err));
+  }
+  send(data) {
+    if (this._ws && this._ws.readyState === WebSocket.OPEN) this._ws.send(data);
+  }
+  close() {
+    this._ws?.close();
+    this._ws = null;
+  }
+};
+var SseRemoteTransport = class {
+  constructor(_url, _headers) {
+    this._url = _url;
+    this._headers = _headers;
+  }
+  _url;
+  _headers;
+  onMessage = null;
+  onOpen = null;
+  onClose = null;
+  onError = null;
+  _decoder = new SseDecoder();
+  _streamReq = null;
+  _postUrl = null;
+  _closed = false;
+  connect() {
+    const req = makeRequest(new URL(this._url), { method: "GET", headers: { ...this._headers, Accept: "text/event-stream" } }, (res) => {
+      const status = res.statusCode ?? 0;
+      if (status >= 400) {
+        this.onError?.(new Error(`SSE GET responded ${status}`));
+        res.resume();
+        return;
+      }
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => this._decoder.feed(chunk, (ev, data) => this._onEvent(ev, data)));
+      res.on("end", () => {
+        if (!this._closed) this.onClose?.();
+      });
+    });
+    this._streamReq = req;
+    req.on("error", (err) => {
+      if (!this._closed) this.onError?.(err);
+    });
+    req.end();
+  }
+  _onEvent(event, data) {
+    if (event === "endpoint") {
+      this._postUrl = new URL(data, this._url).toString();
+      this.onOpen?.();
+    } else if (event === "message") {
+      this.onMessage?.(data);
+    }
+  }
+  send(data) {
+    if (!this._postUrl) return;
+    const req = makeRequest(new URL(this._postUrl), { method: "POST", headers: { ...this._headers, "Content-Type": "application/json" } }, (res) => res.resume());
+    req.on("error", (err) => this.onError?.(err));
+    req.end(data);
+  }
+  close() {
+    this._closed = true;
+    this._streamReq?.destroy();
+    this._streamReq = null;
+  }
+};
+var StreamableHttpRemoteTransport = class {
+  constructor(_url, _headers) {
+    this._url = _url;
+    this._headers = _headers;
+  }
+  _url;
+  _headers;
+  onMessage = null;
+  onOpen = null;
+  onClose = null;
+  onError = null;
+  _sessionId = null;
+  _streamReq = null;
+  _closed = false;
+  connect() {
+    this._closed = false;
+    this.onOpen?.();
+  }
+  send(data) {
+    if (this._closed) return;
+    const headers = {
+      ...this._headers,
+      "Content-Type": "application/json",
+      Accept: "application/json, text/event-stream"
+    };
+    if (this._sessionId) headers["Mcp-Session-Id"] = this._sessionId;
+    const req = makeRequest(new URL(this._url), { method: "POST", headers }, (res) => this._handleResponse(res));
+    req.on("error", (err) => {
+      if (!this._closed) this.onError?.(err);
+    });
+    req.end(data);
+  }
+  _handleResponse(res) {
+    const sid = res.headers["mcp-session-id"];
+    if (typeof sid === "string" && sid.length > 0 && sid !== this._sessionId) {
+      this._sessionId = sid;
+      this._openServerStream();
+    }
+    const status = res.statusCode ?? 0;
+    if (status === 202) {
+      res.resume();
+      return;
+    }
+    if (status >= 400) {
+      this.onError?.(new Error(`Streamable HTTP POST responded ${status}`));
+      res.resume();
+      return;
+    }
+    res.setEncoding("utf8");
+    if (String(res.headers["content-type"] ?? "").includes("text/event-stream")) {
+      const decoder = new SseDecoder();
+      res.on(
+        "data",
+        (chunk) => decoder.feed(chunk, (ev, data) => {
+          if (ev === "message") this.onMessage?.(data);
+        })
+      );
+    } else {
+      let body = "";
+      res.on("data", (chunk) => {
+        body += chunk;
+      });
+      res.on("end", () => this._emitJsonBody(body));
+    }
+  }
+  _emitJsonBody(body) {
+    const trimmed = body.trim();
+    if (!trimmed) return;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (Array.isArray(parsed)) {
+        for (const message of parsed) this.onMessage?.(JSON.stringify(message));
+        return;
+      }
+    } catch {
+    }
+    this.onMessage?.(trimmed);
+  }
+  /** Opens the optional standalone GET stream for server-initiated messages. */
+  _openServerStream() {
+    if (this._closed || this._streamReq) return;
+    const headers = { ...this._headers, Accept: "text/event-stream" };
+    if (this._sessionId) headers["Mcp-Session-Id"] = this._sessionId;
+    const req = makeRequest(new URL(this._url), { method: "GET", headers }, (res) => {
+      if ((res.statusCode ?? 0) >= 400) {
+        res.resume();
+        this._streamReq = null;
+        return;
+      }
+      const decoder = new SseDecoder();
+      res.setEncoding("utf8");
+      res.on(
+        "data",
+        (chunk) => decoder.feed(chunk, (ev, data) => {
+          if (ev === "message") this.onMessage?.(data);
+        })
+      );
+      res.on("end", () => {
+        this._streamReq = null;
+      });
+    });
+    this._streamReq = req;
+    req.on("error", () => {
+      this._streamReq = null;
+    });
+    req.end();
+  }
+  close() {
+    this._closed = true;
+    this._streamReq?.destroy();
+    this._streamReq = null;
+  }
+};
+function createRemoteTransport(url, kind, headers) {
+  switch (kind) {
+    case "websocket":
+      return new WebSocketRemoteTransport(url, headers);
+    case "sse":
+      return new SseRemoteTransport(url, headers);
+    case "streamable-http":
+      return new StreamableHttpRemoteTransport(url, headers);
+  }
+}
+function detectTransport(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return "streamable-http";
+  }
+  if (parsed.protocol === "ws:" || parsed.protocol === "wss:") return "websocket";
+  if (parsed.pathname.replace(/\/+$/, "").endsWith("/sse")) return "sse";
+  return "streamable-http";
+}
+
+// src/remote.upstream.ts
+var RemoteUpstream = class {
+  name;
+  onMessage = null;
+  onOpen = null;
+  onClose = null;
+  onError = null;
+  _config;
+  _transport = null;
+  _open = false;
+  constructor(config) {
+    this.name = config.name;
+    this._config = config;
+  }
+  get isOpen() {
+    return this._open;
+  }
+  connect() {
+    const kind = this._config.transport ?? detectTransport(this._config.url);
+    const transport = createRemoteTransport(this._config.url, kind, this._config.headers ?? {});
+    this._transport = transport;
+    transport.onOpen = () => {
+      this._open = true;
+      this.onOpen?.();
+    };
+    transport.onMessage = (data) => this.onMessage?.(data);
+    transport.onClose = () => {
+      this._open = false;
+      this.onClose?.();
+    };
+    transport.onError = (err) => {
+      this.onError?.(new Error(`RemoteUpstream "${this.name}": ${err.message}`));
+    };
+    transport.connect();
+  }
+  send(data) {
+    this._transport?.send(data);
+  }
+  close() {
+    this._open = false;
+    this._transport?.close();
+    this._transport = null;
+  }
+};
+var BROKER_INFO_URI = "broker://info";
+var BrokerInfoAdapter = class extends McpAdapterBase {
+  constructor(_context) {
+    super("broker");
+    this._context = _context;
+  }
+  _context;
+  async readResourceAsync(uri) {
+    if (uri !== BROKER_INFO_URI) return void 0;
+    return {
+      uri,
+      mimeType: "application/json",
+      text: JSON.stringify(this._snapshot())
+    };
+  }
+  async executeToolAsync(_uri, toolName, _args) {
+    if (toolName !== "broker_info") {
+      return McpToolResults.error(`Unknown tool: ${toolName}`);
+    }
+    return McpToolResults.json(this._snapshot());
+  }
+  _snapshot() {
+    const c = this._context;
+    return {
+      name: c.name,
+      version: c.version,
+      startedAt: c.startedAt?.toISOString() ?? null,
+      uptimeSeconds: c.uptimeSeconds,
+      host: c.host ?? "0.0.0.0",
+      port: c.port,
+      tls: c.tls,
+      paths: c.paths
+    };
+  }
+};
+function brokerGrammarKey(userAgent, locale, version) {
+  const base = `${userAgent}:${locale}`;
+  return version ? `${base}@${version}` : base;
+}
+function parseBrokerGrammarStem(stem) {
+  const at = stem.indexOf("@");
+  if (at < 0) return stem.length > 0 ? { locale: stem } : null;
+  const locale = stem.slice(0, at);
+  const version = stem.slice(at + 1);
+  if (locale.length === 0 || version.length === 0) return null;
+  return { locale, version };
+}
+var GRAMMARS_DIR = join(dirname(fileURLToPath(import.meta.url)), "grammars");
+var _cache = /* @__PURE__ */ new Map();
+function loadBrokerGrammar(userAgent, locale, version) {
+  const key = brokerGrammarKey(userAgent, locale, version);
+  const cached = _cache.get(key);
+  if (cached) return cached;
+  const filename = version ? `${locale}@${version}.json` : `${locale}.json`;
+  const path = join(GRAMMARS_DIR, userAgent, filename);
+  if (!existsSync(path)) return void 0;
+  const raw = readFileSync(path, "utf-8");
+  const data = JSON.parse(raw);
+  const grammar = McpGrammar.fromJSON(data);
+  _cache.set(key, grammar);
+  return grammar;
+}
+function* iterBrokerGrammarsFrom(grammarsDir) {
+  if (!existsSync(grammarsDir)) return;
+  const userAgents = readdirSync(grammarsDir).sort();
+  for (const userAgent of userAgents) {
+    const uaDir = join(grammarsDir, userAgent);
+    if (!statSync(uaDir).isDirectory()) continue;
+    const files = readdirSync(uaDir).sort();
+    for (const file of files) {
+      if (!file.endsWith(".json")) continue;
+      const stem = file.slice(0, -".json".length);
+      const parsed = parseBrokerGrammarStem(stem);
+      if (!parsed) {
+        process.stderr.write(`[mcp-broker] Skipping unparseable grammar filename ${file} in ${uaDir}
+`);
+        continue;
+      }
+      const { locale, version } = parsed;
+      const path = join(uaDir, file);
+      try {
+        const raw = readFileSync(path, "utf-8");
+        const data = JSON.parse(raw);
+        const grammar = McpGrammar.fromJSON(data);
+        yield {
+          userAgent,
+          locale,
+          version,
+          key: brokerGrammarKey(userAgent, locale, version),
+          grammar
+        };
+      } catch (err) {
+        process.stderr.write(`[mcp-broker] Failed to load grammar ${path}: ${err.message}
+`);
+      }
+    }
+  }
+}
+function* iterAvailableBrokerGrammars() {
+  yield* iterBrokerGrammarsFrom(GRAMMARS_DIR);
+}
+function brokerBaselineGrammar() {
+  const g = loadBrokerGrammar("default", "en");
+  if (!g) {
+    throw new Error(`Required baseline broker grammar "default:en" is missing, expected at ${join(GRAMMARS_DIR, "default", "en.json")}.`);
+  }
+  return g;
+}
+function brokerBaselineToolDescription(toolName) {
+  const desc = brokerBaselineGrammar().getToolDescription(toolName);
+  if (!desc) {
+    throw new Error(`Missing baseline description for tool "${toolName}" in default/en.json.`);
+  }
+  return desc;
+}
+function brokerBaselinePropertyDescription(toolName, propertyName) {
+  const desc = brokerBaselineGrammar().getPropertyDescription(toolName, propertyName);
+  if (!desc) {
+    throw new Error(`Missing baseline description for property "${propertyName}" of tool "${toolName}" in default/en.json.`);
+  }
+  return desc;
+}
+function brokerBaselineResourceName(uri) {
+  const name = brokerBaselineGrammar().getResourceName(uri);
+  if (!name) {
+    throw new Error(`Missing baseline name for resource "${uri}" in default/en.json.`);
+  }
+  return name;
+}
+function brokerBaselineResourceDescription(uri) {
+  const desc = brokerBaselineGrammar().getResourceDescription(uri);
+  if (!desc) {
+    throw new Error(`Missing baseline description for resource "${uri}" in default/en.json.`);
+  }
+  return desc;
+}
+function brokerBaselineResourceTemplateName(uriTemplate) {
+  const name = brokerBaselineGrammar().getResourceTemplateName(uriTemplate);
+  if (!name) {
+    throw new Error(`Missing baseline name for resource template "${uriTemplate}" in default/en.json.`);
+  }
+  return name;
+}
+function brokerBaselineResourceTemplateDescription(uriTemplate) {
+  const desc = brokerBaselineGrammar().getResourceTemplateDescription(uriTemplate);
+  if (!desc) {
+    throw new Error(`Missing baseline description for resource template "${uriTemplate}" in default/en.json.`);
+  }
+  return desc;
+}
+
+// src/broker/behaviors/broker.behavior.info.ts
+var BrokerInfoBehavior = class _BrokerInfoBehavior extends McpBehavior {
+  static NAMESPACE = "broker";
+  constructor(context) {
+    super(new BrokerInfoAdapter(context), {
+      namespace: _BrokerInfoBehavior.NAMESPACE
+    });
+  }
+  _buildResources() {
+    return [
+      {
+        uri: BROKER_INFO_URI,
+        name: brokerBaselineResourceName(BROKER_INFO_URI),
+        mimeType: "application/json",
+        description: brokerBaselineResourceDescription(BROKER_INFO_URI)
+      }
+    ];
+  }
+  _buildTools() {
+    return [
+      {
+        name: "broker_info",
+        description: brokerBaselineToolDescription("broker_info"),
+        inputSchema: {
+          type: "object",
+          properties: {},
+          additionalProperties: false
+        }
+      }
+    ];
+  }
+};
+var PROVIDERS_URI = "broker://providers";
+var PROVIDER_URI_TEMPLATE = "broker://providers/{name}";
+var BrokerProvidersAdapter = class extends McpAdapterBase {
+  constructor(_context) {
+    super("broker");
+    this._context = _context;
+  }
+  _context;
+  async readResourceAsync(uri) {
+    if (uri === PROVIDERS_URI) {
+      return {
+        uri,
+        mimeType: "application/json",
+        text: JSON.stringify(this._listSnapshot())
+      };
+    }
+    const match = /^broker:\/\/providers\/([^/]+)$/.exec(uri);
+    if (match) {
+      const name = decodeURIComponent(match[1]);
+      const info = this._context.getProviderInfo(name);
+      if (!info) return void 0;
+      return {
+        uri,
+        mimeType: "application/json",
+        text: JSON.stringify(info)
+      };
+    }
+    return void 0;
+  }
+  async executeToolAsync(_uri, toolName, args) {
+    switch (toolName) {
+      case "providers_list":
+        return McpToolResults.json(this._listSnapshot());
+      case "provider_status": {
+        const name = typeof args.name === "string" ? args.name : "";
+        if (!name) return McpToolResults.error('Missing required argument: "name" (string).');
+        const info = this._context.getProviderInfo(name);
+        if (!info) return McpToolResults.error(`Unknown provider: "${name}".`);
+        return McpToolResults.json(info);
+      }
+      default:
+        return McpToolResults.error(`Unknown tool: ${toolName}`);
+    }
+  }
+  _listSnapshot() {
+    const providers = this._context.getProvidersInfo();
+    return { count: providers.length, providers };
+  }
+};
+
+// src/broker/behaviors/broker.behavior.providers.ts
+var BrokerProvidersBehavior = class _BrokerProvidersBehavior extends McpBehavior {
+  static NAMESPACE = "broker_providers";
+  constructor(context) {
+    super(new BrokerProvidersAdapter(context), {
+      namespace: _BrokerProvidersBehavior.NAMESPACE
+    });
+  }
+  _buildResources() {
+    return [
+      {
+        uri: PROVIDERS_URI,
+        name: brokerBaselineResourceName(PROVIDERS_URI),
+        mimeType: "application/json",
+        description: brokerBaselineResourceDescription(PROVIDERS_URI)
+      }
+    ];
+  }
+  _buildTemplate() {
+    return [
+      {
+        uriTemplate: PROVIDER_URI_TEMPLATE,
+        name: brokerBaselineResourceTemplateName(PROVIDER_URI_TEMPLATE),
+        mimeType: "application/json",
+        description: brokerBaselineResourceTemplateDescription(PROVIDER_URI_TEMPLATE)
+      }
+    ];
+  }
+  _buildTools() {
+    return [
+      {
+        name: "providers_list",
+        description: brokerBaselineToolDescription("providers_list"),
+        inputSchema: {
+          type: "object",
+          properties: {},
+          additionalProperties: false
+        }
+      },
+      {
+        name: "provider_status",
+        description: brokerBaselineToolDescription("provider_status"),
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: {
+              type: "string",
+              description: brokerBaselinePropertyDescription("provider_status", "name")
+            }
+          },
+          required: ["name"],
+          additionalProperties: false
+        }
+      }
+    ];
+  }
+};
+var BROKER_PROVIDER_NAME = "_broker";
+async function startBrokerServer(context, options = {}) {
+  const [serverEnd, clientEnd] = LoopbackTransport.createPair();
+  const builder = new McpServerBuilder().withName(BROKER_PROVIDER_NAME).withTransport(serverEnd).withInitializer({
+    initialize: () => ({
+      protocolVersion: "2024-11-05",
+      serverInfo: { name: BROKER_PROVIDER_NAME, version: context.version }
+    })
+  }).register(new BrokerInfoBehavior(context), new BrokerProvidersBehavior(context));
+  for (const entry of iterAvailableBrokerGrammars()) {
+    builder.withGrammar(entry.key, entry.grammar);
+  }
+  if (options.localGrammarsDir) {
+    for (const entry of iterBrokerGrammarsFrom(options.localGrammarsDir)) {
+      builder.withGrammar(entry.key, entry.grammar);
+    }
+  }
+  builder.withGrammarResolver({
+    localeSource: () => process.env["MCP_BROKER_LOCALE"],
+    ...options.grammarResolverOptions ?? {}
+  });
+  const server = builder.build();
+  await server.start();
+  return { server, clientTransport: clientEnd };
+}
+
+// src/authorization/resource.path.ts
+var WILDCARD = "*";
+var RECURSIVE_WILDCARD = "**";
+function assertString(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`${label}: a non-empty string is required.`);
+  }
+}
+function splitAbsolutePath(value, label) {
+  assertString(value, label);
+  if (!value.startsWith("/")) {
+    throw new Error(`${label}: "${value}" must start with "/".`);
+  }
+  if (value === "/") return [];
+  const withoutTrailingSlash = value.endsWith("/") ? value.slice(0, -1) : value;
+  const segments = withoutTrailingSlash.slice(1).split("/");
+  for (const segment of segments) {
+    if (!segment) {
+      throw new Error(`${label}: "${value}" contains an empty path segment.`);
+    }
+    if (segment === "." || segment === "..") {
+      throw new Error(`${label}: "${value}" contains a forbidden "${segment}" segment.`);
+    }
+  }
+  return segments;
+}
+function normalizedValue(segments) {
+  return segments.length === 0 ? "/" : `/${segments.join("/")}`;
+}
+var ResourcePath = class _ResourcePath {
+  value;
+  segments;
+  constructor(segments) {
+    this.segments = Object.freeze([...segments]);
+    this.value = normalizedValue(this.segments);
+  }
+  static parse(value) {
+    const segments = splitAbsolutePath(value, "resource path");
+    for (const segment of segments) {
+      if (segment === WILDCARD || segment === RECURSIVE_WILDCARD) {
+        throw new Error(`resource path: wildcards are not allowed in "${value}".`);
+      }
+    }
+    return new _ResourcePath(segments);
+  }
+  static tryParse(value) {
+    try {
+      return _ResourcePath.parse(value);
+    } catch {
+      return void 0;
+    }
+  }
+  toString() {
+    return this.value;
+  }
+};
+var ResourcePathPattern = class _ResourcePathPattern {
+  value;
+  segments;
+  specificity;
+  constructor(segments) {
+    this.segments = Object.freeze([...segments]);
+    this.value = normalizedValue(this.segments);
+    this.specificity = this.segments.reduce((score, segment) => {
+      if (segment === RECURSIVE_WILDCARD) return score;
+      if (segment === WILDCARD) return score + 1;
+      return score + 4;
+    }, this.segments.length);
+  }
+  static parse(value) {
+    const canonical = value === RECURSIVE_WILDCARD ? `/${RECURSIVE_WILDCARD}` : value;
+    const segments = splitAbsolutePath(canonical, "resource pattern");
+    let recursiveSeen = false;
+    for (let index = 0; index < segments.length; index += 1) {
+      const segment = segments[index];
+      if (segment === RECURSIVE_WILDCARD) {
+        if (index !== segments.length - 1) {
+          throw new Error(`resource pattern: "**" must be the final segment in "${value}".`);
+        }
+        recursiveSeen = true;
+      } else if (recursiveSeen) {
+        throw new Error(`resource pattern: no segment may follow "**" in "${value}".`);
+      } else if (segment !== WILDCARD && segment.includes(WILDCARD)) {
+        throw new Error(`resource pattern: wildcards must occupy a complete segment in "${value}".`);
+      }
+    }
+    return new _ResourcePathPattern(segments);
+  }
+  matches(path) {
+    const pattern = this.segments;
+    const target = path.segments;
+    for (let index = 0; index < pattern.length; index += 1) {
+      const segment = pattern[index];
+      if (segment === RECURSIVE_WILDCARD) return true;
+      if (index >= target.length) return false;
+      if (segment !== WILDCARD && segment !== target[index]) return false;
+    }
+    return target.length === pattern.length;
+  }
+  toString() {
+    return this.value;
+  }
+};
+
+// src/authorization/capability.classifier.ts
+var STATIC_CAPABILITIES = {
+  "resources/list": "mcp.resources.read",
+  "resources/read": "mcp.resources.read",
+  "tools/list": "mcp.tools.list",
+  "prompts/list": "mcp.prompts.read",
+  "prompts/get": "mcp.prompts.read",
+  "completion/complete": "mcp.completion.use",
+  "notifications/resources/list_changed": "mcp.resources.read",
+  "notifications/resources/updated": "mcp.resources.read",
+  "notifications/tools/list_changed": "mcp.tools.list",
+  "notifications/prompts/list_changed": "mcp.prompts.read"
+};
+var BROKER_READ_TOOLS = /* @__PURE__ */ new Set(["broker_info", "providers_list", "provider_status"]);
+function toolNameFrom(params) {
+  if (typeof params !== "object" || params === null || Array.isArray(params)) return void 0;
+  const name = params["name"];
+  return typeof name === "string" && name ? name : void 0;
+}
+function validateCapability(capability, label = "capability") {
+  if (typeof capability !== "string" || capability !== "*" && !/^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(capability)) {
+    throw new Error(`authorization ${label}: "${capability}" is malformed.`);
+  }
+}
+var ConfiguredCapabilityClassifier = class {
+  _globalTools;
+  _providerMappings;
+  constructor(toolCapabilities = {}, providerToolCapabilities = {}) {
+    for (const [tool, capability] of Object.entries(toolCapabilities)) {
+      if (!tool) throw new Error("authorization toolCapabilities: tool names must not be empty.");
+      validateCapability(capability, `toolCapabilities["${tool}"]`);
+    }
+    this._globalTools = Object.freeze({ ...toolCapabilities });
+    const mappings = [];
+    for (const [patternValue, tools] of Object.entries(providerToolCapabilities)) {
+      const pattern = ResourcePathPattern.parse(patternValue);
+      for (const [tool, capability] of Object.entries(tools)) {
+        if (!tool) throw new Error(`authorization providerToolCapabilities["${patternValue}"]: tool names must not be empty.`);
+        validateCapability(capability, `providerToolCapabilities["${patternValue}"]["${tool}"]`);
+      }
+      mappings.push({ pattern, tools: Object.freeze({ ...tools }) });
+    }
+    mappings.sort((left, right) => right.pattern.specificity - left.pattern.specificity || left.pattern.value.localeCompare(right.pattern.value));
+    this._providerMappings = Object.freeze(mappings);
+  }
+  classify(operation, resource, provider) {
+    const method = operation.method;
+    if (!method) return void 0;
+    if (provider === "_broker") {
+      if (method === "tools/list" || method === "resources/list" || method === "resources/read") {
+        return { capability: "broker.providers.read" };
+      }
+      if (method === "tools/call") {
+        const tool2 = toolNameFrom(operation.params);
+        if (tool2 && BROKER_READ_TOOLS.has(tool2)) return { capability: "broker.providers.read", tool: tool2 };
+      }
+    }
+    if (method !== "tools/call") {
+      const capability = STATIC_CAPABILITIES[method];
+      return capability ? { capability } : void 0;
+    }
+    const tool = toolNameFrom(operation.params);
+    if (!tool) return { capability: "mcp.tools.call" };
+    for (const mapping of this._providerMappings) {
+      if (mapping.pattern.matches(resource)) {
+        const capability = mapping.tools[tool];
+        if (capability) return { capability, tool };
+      }
+    }
+    return { capability: this._globalTools[tool] ?? "mcp.tools.call", tool };
+  }
+};
+
+// src/authorization/policy.engine.ts
+function validateName(value, label) {
+  if (typeof value !== "string" || !value || value.trim() !== value || value.includes("/")) {
+    throw new Error(`authorization ${label}: "${value}" is invalid.`);
+  }
+}
+function validateSubject(subject, label) {
+  if (typeof subject !== "string" || !/^[A-Za-z][A-Za-z0-9_-]*:.+$/.test(subject)) {
+    throw new Error(`authorization ${label}: subject "${subject}" must use a non-empty extensible prefix such as "user:alice".`);
+  }
+}
+function validatePolicyId(id, label) {
+  if (typeof id !== "string" || !id || id.trim() !== id) {
+    throw new Error(`authorization ${label}: policy ids must be non-empty and must not contain surrounding whitespace.`);
+  }
+}
+function expandRoles(roles) {
+  const expanded = /* @__PURE__ */ new Map();
+  const visiting = [];
+  for (const [name, role] of Object.entries(roles)) {
+    validateName(name, "role");
+    for (const key of Object.keys(role)) {
+      if (key !== "inherits" && key !== "capabilities") {
+        throw new Error(`authorization role "${name}": unsupported field "${key}"; roles contain capabilities, not resource paths.`);
+      }
+    }
+    if (!Array.isArray(role.capabilities)) {
+      throw new Error(`authorization role "${name}": capabilities must be an array.`);
+    }
+    if (role.inherits !== void 0 && !Array.isArray(role.inherits)) {
+      throw new Error(`authorization role "${name}": inherits must be an array.`);
+    }
+    for (const capability of role.capabilities) validateCapability(capability, `role "${name}" capability`);
+    for (const inherited of role.inherits ?? []) {
+      validateName(inherited, `role "${name}" inheritance`);
+      if (!roles[inherited]) {
+        throw new Error(`authorization role "${name}": inherited role "${inherited}" is not defined.`);
+      }
+    }
+  }
+  const visit = (name) => {
+    const cached = expanded.get(name);
+    if (cached) return cached;
+    const cycleStart = visiting.indexOf(name);
+    if (cycleStart >= 0) {
+      const cycle = [...visiting.slice(cycleStart), name].join(" -> ");
+      throw new Error(`authorization roles: inheritance cycle detected: ${cycle}.`);
+    }
+    const role = roles[name];
+    if (!role) throw new Error(`authorization roles: role "${name}" is not defined.`);
+    visiting.push(name);
+    const capabilities = /* @__PURE__ */ new Set();
+    for (const inherited of role.inherits ?? []) {
+      for (const capability of visit(inherited)) capabilities.add(capability);
+    }
+    for (const capability of role.capabilities) capabilities.add(capability);
+    visiting.pop();
+    const frozen = Object.freeze(capabilities);
+    expanded.set(name, frozen);
+    return frozen;
+  };
+  for (const name of Object.keys(roles)) visit(name);
+  return expanded;
+}
+function indexBySubject(entries) {
+  const mutable = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const bucket = mutable.get(entry.subject);
+    if (bucket) bucket.push(entry);
+    else mutable.set(entry.subject, [entry]);
+  }
+  const result = /* @__PURE__ */ new Map();
+  for (const [subject, bucket] of mutable) result.set(subject, Object.freeze(bucket));
+  return result;
+}
+function grants(capabilities, requested) {
+  return capabilities.has("*") || capabilities.has(requested);
+}
+var ConfigPolicyEngine = class {
+  _assignmentsBySubject;
+  _deniesBySubject;
+  constructor(roles, assignments, denies) {
+    const expandedRoles = expandRoles(roles);
+    const policyIds = /* @__PURE__ */ new Set();
+    const reserveId = (id, label) => {
+      validatePolicyId(id, label);
+      if (policyIds.has(id)) throw new Error(`authorization policies: duplicate policy id "${id}".`);
+      policyIds.add(id);
+    };
+    const compiledAssignments = assignments.map((assignment, index) => {
+      const id = assignment.id ?? `assignment:${index}`;
+      reserveId(id, `assignment ${index}`);
+      validateSubject(assignment.subject, `assignment "${id}"`);
+      validateName(assignment.role, `assignment "${id}" role`);
+      const capabilities = expandedRoles.get(assignment.role);
+      if (!capabilities) {
+        throw new Error(`authorization assignment "${id}": role "${assignment.role}" is not defined.`);
+      }
+      if (!assignment.resource) throw new Error(`authorization assignment "${id}": resource must not be empty.`);
+      return {
+        id,
+        subject: assignment.subject,
+        capabilities,
+        resource: ResourcePathPattern.parse(assignment.resource)
+      };
+    });
+    const compiledDenies = denies.map((deny, index) => {
+      const id = deny.id ?? `deny:${index}`;
+      reserveId(id, `deny ${index}`);
+      validateSubject(deny.subject, `deny "${id}"`);
+      if (deny.effect !== void 0 && deny.effect !== "deny") {
+        throw new Error(`authorization deny "${id}": effect must be "deny".`);
+      }
+      if (!Array.isArray(deny.capabilities) || deny.capabilities.length === 0) {
+        throw new Error(`authorization deny "${id}": at least one capability is required.`);
+      }
+      const capabilities = /* @__PURE__ */ new Set();
+      for (const capability of deny.capabilities) {
+        validateCapability(capability, `deny "${id}" capability`);
+        capabilities.add(capability);
+      }
+      if (!deny.resource) throw new Error(`authorization deny "${id}": resource must not be empty.`);
+      return {
+        id,
+        subject: deny.subject,
+        capabilities: Object.freeze(capabilities),
+        resource: ResourcePathPattern.parse(deny.resource)
+      };
+    });
+    this._assignmentsBySubject = indexBySubject(compiledAssignments);
+    this._deniesBySubject = indexBySubject(compiledDenies);
+  }
+  authorize(request3) {
+    if (!request3.resource) return { allowed: false, reason: "invalid-resource" };
+    try {
+      validateCapability(request3.capability, "request capability");
+    } catch {
+      return { allowed: false, reason: "no-matching-grant" };
+    }
+    const matchingDenies = /* @__PURE__ */ new Set();
+    for (const subject of request3.subject.ids) {
+      for (const deny of this._deniesBySubject.get(subject) ?? []) {
+        if (deny.resource.matches(request3.resource) && grants(deny.capabilities, request3.capability)) {
+          matchingDenies.add(deny.id);
+        }
+      }
+    }
+    if (matchingDenies.size > 0) {
+      return {
+        allowed: false,
+        reason: "explicit-deny",
+        matchedPolicies: Object.freeze([...matchingDenies].sort())
+      };
+    }
+    const matchingGrants = /* @__PURE__ */ new Set();
+    for (const subject of request3.subject.ids) {
+      for (const assignment of this._assignmentsBySubject.get(subject) ?? []) {
+        if (assignment.resource.matches(request3.resource) && grants(assignment.capabilities, request3.capability)) {
+          matchingGrants.add(assignment.id);
+        }
+      }
+    }
+    if (matchingGrants.size > 0) {
+      return {
+        allowed: true,
+        reason: "role-grant",
+        matchedPolicies: Object.freeze([...matchingGrants].sort())
+      };
+    }
+    return { allowed: false, reason: "no-matching-grant" };
+  }
+};
+
+// src/authorization/subject.mapper.ts
+var SubjectMappingError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SubjectMappingError";
+  }
+};
+function claimAt(claims, claimName) {
+  const parts = claimName.split(".");
+  let current = claims;
+  for (const part of parts) {
+    if (!part || typeof current !== "object" || current === null || Array.isArray(current)) return void 0;
+    current = current[part];
+  }
+  return current;
+}
+function valuesOf(value, claimName) {
+  if (value === void 0 || value === null) return [];
+  if (typeof value === "string") return value ? [value] : [];
+  if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
+    return value.filter((entry) => typeof entry === "string" && entry.length > 0);
+  }
+  throw new SubjectMappingError(`JWT subject claim "${claimName}" must be a string or an array of strings.`);
+}
+function validateClaimName(value, label) {
+  if (!value || value.split(".").some((part) => !part)) {
+    throw new Error(`authorization subject mapping: ${label} contains an invalid claim name.`);
+  }
+}
+var JwtSubjectMapper = class {
+  _rules;
+  constructor(config = {}) {
+    const userClaim = config.userClaim ?? "sub";
+    const groupClaims = config.groupClaims ?? ["groups", "roles"];
+    const clientClaim = config.clientClaim ?? "client_id";
+    const serviceClaims = config.serviceClaims ?? [];
+    if (!Array.isArray(groupClaims)) throw new Error("authorization subject mapping: groupClaims must be an array.");
+    if (!Array.isArray(serviceClaims)) throw new Error("authorization subject mapping: serviceClaims must be an array.");
+    validateClaimName(userClaim, "userClaim");
+    validateClaimName(clientClaim, "clientClaim");
+    for (const claim of groupClaims) validateClaimName(claim, "groupClaims");
+    for (const claim of serviceClaims) validateClaimName(claim, "serviceClaims");
+    this._rules = Object.freeze([
+      { prefix: "user", claim: userClaim },
+      ...groupClaims.map((claim) => ({ prefix: "group", claim })),
+      { prefix: "client", claim: clientClaim },
+      ...serviceClaims.map((claim) => ({ prefix: "service", claim }))
+    ]);
+  }
+  map(claims) {
+    const ids = /* @__PURE__ */ new Set();
+    for (const rule of this._rules) {
+      for (const value of valuesOf(claimAt(claims, rule.claim), rule.claim)) {
+        ids.add(`${rule.prefix}:${value}`);
+      }
+    }
+    return { ids: Object.freeze([...ids]), claims };
+  }
+};
+
+// src/authorization/slot.resource.ts
+var RESERVED_RESOURCES = {
+  _broker: "/_system/broker",
+  _all: "/_system/all"
+};
+function isReservedNamespace(resource) {
+  return resource.value === "/_system" || resource.value.startsWith("/_system/");
+}
+var DefaultSlotResourceResolver = class {
+  _explicit = /* @__PURE__ */ new Map();
+  constructor(slotResources = {}) {
+    for (const [slot, configuredPath] of Object.entries(slotResources)) {
+      if (!slot) throw new Error("authorization slotResources: slot names must not be empty.");
+      const resource = ResourcePath.parse(configuredPath);
+      const reserved = RESERVED_RESOURCES[slot];
+      if (isReservedNamespace(resource) && reserved !== resource.value) {
+        throw new Error(`authorization slotResources: slot "${slot}" may not use reserved resource "${resource.value}".`);
+      }
+      if (reserved && resource.value !== reserved) {
+        throw new Error(`authorization slotResources: reserved slot "${slot}" must resolve to "${reserved}".`);
+      }
+      this._explicit.set(slot, resource);
+    }
+  }
+  resolve(slot) {
+    const explicit = this._explicit.get(slot);
+    if (explicit) return explicit;
+    const reserved = RESERVED_RESOURCES[slot];
+    if (reserved) return ResourcePath.parse(reserved);
+    if (!slot) return void 0;
+    const candidate = slot.startsWith("/") ? slot : `/${slot}`;
+    const resource = ResourcePath.tryParse(candidate);
+    return resource && !isReservedNamespace(resource) ? resource : void 0;
+  }
+};
+
+// src/authorization/runtime.ts
+function hasAuthorizationPolicies(config) {
+  return Object.keys(config.roles ?? {}).length > 0 || (config.assignments?.length ?? 0) > 0 || (config.denies?.length ?? 0) > 0;
+}
+function compileAuthorizationPolicy(config) {
+  if (config.audit?.logAllowed !== void 0 && typeof config.audit.logAllowed !== "boolean") {
+    throw new Error("authorization audit.logAllowed must be a boolean.");
+  }
+  const engine = new ConfigPolicyEngine(config.roles ?? {}, config.assignments ?? [], config.denies ?? []);
+  const subjectMapper = new JwtSubjectMapper(config.subjectMapping);
+  const slotResourceResolver = new DefaultSlotResourceResolver(config.slotResources);
+  const capabilityClassifier = new ConfiguredCapabilityClassifier(config.toolCapabilities, config.providerToolCapabilities);
+  return {
+    engine,
+    subjectMapper,
+    slotResourceResolver,
+    capabilityClassifier,
+    audit: Object.freeze({ logAllowed: config.audit?.logAllowed ?? false })
+  };
+}
+function authorizationWithEngine(engine, overrides = {}) {
+  return {
+    engine,
+    subjectMapper: overrides.subjectMapper ?? new JwtSubjectMapper(),
+    slotResourceResolver: overrides.slotResourceResolver ?? new DefaultSlotResourceResolver(),
+    capabilityClassifier: overrides.capabilityClassifier ?? new ConfiguredCapabilityClassifier(),
+    audit: Object.freeze({ logAllowed: overrides.audit?.logAllowed ?? false })
+  };
+}
+
+// src/authorization/audit.ts
+function makeAuthorizationAuditEvent(context, decision) {
+  const clientId = context.subject.ids.find((id) => id.startsWith("client:"))?.slice("client:".length);
+  return {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    allowed: decision.allowed,
+    subjectIds: context.subject.ids,
+    clientId,
+    slot: context.slot,
+    resource: context.resource?.value,
+    capability: context.capability,
+    provider: context.provider,
+    tool: context.tool,
+    reason: decision.reason,
+    matchedPolicies: decision.matchedPolicies
+  };
+}
+function writeAuthorizationAuditEvent(event) {
+  console.error(`[broker] authorization ${JSON.stringify(event)}`);
+}
+
+// src/broker/aggregate/aggregate.catalog.ts
+var SEPARATOR = "-";
+var MAX_TOOL_NAME_LENGTH = 64;
+var AggregateCatalog = class {
+  _providers = /* @__PURE__ */ new Map();
+  _tools = [];
+  _prompts = [];
+  _toolRoutes = /* @__PURE__ */ new Map();
+  _promptRoutes = /* @__PURE__ */ new Map();
+  /** Number of providers currently contributing to the aggregate. */
+  get providerCount() {
+    return this._providers.size;
+  }
+  /** The merged, namespaced tool list. */
+  get tools() {
+    return this._tools;
+  }
+  /** The merged, namespaced prompt list. */
+  get prompts() {
+    return this._prompts;
+  }
+  /** Adds or replaces a provider's contribution, then rebuilds the merged view. */
+  setProvider(provider, entry) {
+    this._providers.set(provider, entry);
+    this._rebuild();
+  }
+  /** Drops a provider from the aggregate, then rebuilds. */
+  removeProvider(provider) {
+    if (this._providers.delete(provider)) this._rebuild();
+  }
+  /** The merged tool list restricted to providers `allow` returns `true` for. */
+  toolsFor(allow) {
+    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) {
+    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) {
+    return this._toolRoutes.get(name);
+  }
+  /** Resolves an aggregated prompt name to its origin, or `undefined` if unknown. */
+  resolvePrompt(name) {
+    return this._promptRoutes.get(name);
+  }
+  _rebuild() {
+    const tools = [];
+    const prompts = [];
+    const toolRoutes = /* @__PURE__ */ new Map();
+    const promptRoutes = /* @__PURE__ */ new Map();
+    for (const [provider, entry] of this._providers) {
+      for (const tool of entry.tools) {
+        const name = unique(capToolName(prefixed(provider, tool.name)), toolRoutes);
+        toolRoutes.set(name, { provider, original: tool.name });
+        tools.push({ ...tool, name, description: tag(provider, tool.description) });
+      }
+      for (const prompt of entry.prompts) {
+        const name = unique(prefixed(provider, prompt.name), promptRoutes);
+        promptRoutes.set(name, { provider, original: prompt.name });
+        prompts.push({ ...prompt, name, description: tag(provider, prompt.description) });
+      }
+    }
+    this._tools = tools;
+    this._prompts = prompts;
+    this._toolRoutes = toolRoutes;
+    this._promptRoutes = promptRoutes;
+  }
+};
+function prefixed(provider, original) {
+  return `${provider}${SEPARATOR}${original}`;
+}
+function tag(provider, description) {
+  const label = `[${provider}]`;
+  return description ? `${label} ${description}` : label;
+}
+function capToolName(name) {
+  if (name.length <= MAX_TOOL_NAME_LENGTH) return name;
+  const hash = djb2(name);
+  return name.slice(0, MAX_TOOL_NAME_LENGTH - hash.length - 1) + SEPARATOR + hash;
+}
+function unique(candidate, taken) {
+  if (!taken.has(candidate)) return candidate;
+  let n = 2;
+  while (taken.has(`${candidate}${SEPARATOR}${n}`)) n++;
+  return `${candidate}${SEPARATOR}${n}`;
+}
+function djb2(input) {
+  let h = 5381;
+  for (let i = 0; i < input.length; i++) {
+    h = (h << 5) + h + input.charCodeAt(i) >>> 0;
+  }
+  return h.toString(36).padStart(8, "0").slice(-8);
+}
+
+// src/broker/aggregate/provider.client.session.ts
+var PROTOCOL_VERSION = "2024-11-05";
+var REQUEST_TIMEOUT_MS = 3e4;
+var ProviderClientSession = class {
+  provider;
+  _client;
+  _idPrefix;
+  _pending = /* @__PURE__ */ new Map();
+  _nextId = 0;
+  _tools = [];
+  _prompts = [];
+  _closed = false;
+  /** Fires after the cached catalog changes (initial load or `list_changed`). */
+  onCatalogChanged = null;
+  /** Fires when the underlying provider slot disconnects. */
+  onClosed = null;
+  constructor(provider, client) {
+    this.provider = provider;
+    this._client = client;
+    this._idPrefix = `agg-${provider}-`;
+    client.onMessage = (data) => this._handleMessage(data);
+    client.onClose = () => {
+      if (this._closed) return;
+      this._rejectAll("provider disconnected");
+      this.onClosed?.();
+    };
+  }
+  get tools() {
+    return this._tools;
+  }
+  get prompts() {
+    return this._prompts;
+  }
+  /** Runs the `initialize` handshake and the first catalog fetch. */
+  async initialize() {
+    await this._request("initialize", {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: {},
+      clientInfo: { name: "mcp-broker-aggregate", version: "0" }
+    });
+    this._client.send(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }));
+    await this._refresh();
+  }
+  /** Forwards a `tools/call` to the provider, relaying the raw outcome. */
+  callTool(name, args) {
+    return this._request("tools/call", { name, arguments: args });
+  }
+  /** Forwards a `prompts/get` to the provider, relaying the raw outcome. */
+  getPrompt(name, args) {
+    return this._request("prompts/get", { name, arguments: args });
+  }
+  /** Detaches the session and its internal client. */
+  close() {
+    if (this._closed) return;
+    this._closed = true;
+    this._rejectAll("session closed");
+    this._client.close();
+  }
+  async _refresh() {
+    this._tools = await this._listAll("tools/list", "tools");
+    this._prompts = await this._listAll("prompts/list", "prompts");
+    this.onCatalogChanged?.();
+  }
+  /**
+   * Calls a list method, following `nextCursor` pagination. A provider that
+   * does not implement the primitive answers with an error, which is treated
+   * as an empty list.
+   */
+  async _listAll(method, key) {
+    const items = [];
+    let cursor;
+    do {
+      const { result, error } = await this._request(method, cursor ? { cursor } : {});
+      if (error) return [];
+      const page = result ?? {};
+      const list = page[key];
+      if (Array.isArray(list)) items.push(...list);
+      cursor = typeof page.nextCursor === "string" ? page.nextCursor : void 0;
+    } while (cursor);
+    return items;
+  }
+  _request(method, params) {
+    return new Promise((resolve5) => {
+      if (this._closed) {
+        resolve5({ error: { code: -32e3, message: "session closed" } });
+        return;
+      }
+      const id = this._idPrefix + String(++this._nextId);
+      const timer = setTimeout(() => {
+        this._pending.delete(id);
+        resolve5({ error: { code: -32e3, message: `request "${method}" timed out` } });
+      }, REQUEST_TIMEOUT_MS);
+      this._pending.set(id, { resolve: resolve5, timer });
+      this._client.send(JSON.stringify({ jsonrpc: "2.0", id, method, params }));
+    });
+  }
+  _handleMessage(data) {
+    let msg;
+    try {
+      msg = JSON.parse(data);
+    } catch {
+      return;
+    }
+    if (typeof msg.id === "string") {
+      const pending = this._pending.get(msg.id);
+      if (pending) {
+        this._pending.delete(msg.id);
+        clearTimeout(pending.timer);
+        pending.resolve({ result: msg.result, error: msg.error });
+      }
+      return;
+    }
+    if (msg.id == null && (msg.method === "notifications/tools/list_changed" || msg.method === "notifications/prompts/list_changed")) {
+      void this._refresh();
+    }
+  }
+  _rejectAll(reason) {
+    for (const pending of this._pending.values()) {
+      clearTimeout(pending.timer);
+      pending.resolve({ error: { code: -32e3, message: reason } });
+    }
+    this._pending.clear();
+  }
+};
+
+// src/broker/aggregate/aggregate.server.ts
+var PROTOCOL_VERSION2 = "2024-11-05";
+var AggregateServer = class _AggregateServer {
+  /** Reserved provider slot the aggregate is published on. */
+  static SLOT = "_all";
+  _catalog = new AggregateCatalog();
+  _sessions = /* @__PURE__ */ new Map();
+  _openClient;
+  _running = false;
+  /** Per-caller provider visibility filter; `null` ⇒ every caller sees all. */
+  _scopeFilter = null;
+  /** Provider-aware hierarchical authorization, absent in legacy mode. */
+  _authorization = null;
+  onMessage = null;
+  onOpen = null;
+  onClose = null;
+  onError = null;
+  constructor(openClient) {
+    this._openClient = openClient;
+  }
+  get isOpen() {
+    return this._running;
+  }
+  /** Number of providers currently in the aggregate. */
+  get providerCount() {
+    return this._sessions.size;
+  }
+  /** Marks the aggregate transport open. Call before registering it. */
+  start() {
+    this._running = true;
+  }
+  /** Sets the per-caller provider visibility filter. `null` disables filtering. */
+  setScopeFilter(filter) {
+    this._scopeFilter = filter;
+  }
+  /** Sets the compiled hierarchical policy runtime. */
+  setPolicyAuthorization(authorization) {
+    this._authorization = authorization;
+  }
+  /** WsTunnel hands a client request for the `_all` slot here (no principal). */
+  send(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, principal) {
+    void this._handleClientMessage(data, principal);
+  }
+  /** Closes every provider session and the aggregate transport. */
+  close() {
+    if (!this._running) return;
+    this._running = false;
+    for (const session of this._sessions.values()) session.close();
+    this._sessions.clear();
+    this.onClose?.();
+  }
+  /**
+   * Adds a provider to the aggregate: opens an internal client, runs the
+   * session handshake, and merges the provider's catalog. A no-op for an
+   * already-aggregated provider or the reserved `_all` slot itself.
+   */
+  async addProvider(name) {
+    if (name === _AggregateServer.SLOT || this._sessions.has(name)) return;
+    const session = new ProviderClientSession(name, this._openClient(name));
+    this._sessions.set(name, session);
+    session.onCatalogChanged = () => {
+      this._catalog.setProvider(name, { tools: session.tools, prompts: session.prompts });
+      this._emitListChanged();
+    };
+    session.onClosed = () => this.removeProvider(name);
+    try {
+      await session.initialize();
+    } catch {
+      this.removeProvider(name);
+    }
+  }
+  /** Removes a provider from the aggregate. */
+  removeProvider(name) {
+    const session = this._sessions.get(name);
+    if (!session) return;
+    this._sessions.delete(name);
+    session.close();
+    this._catalog.removeProvider(name);
+    this._emitListChanged();
+  }
+  _subjectFor(principal) {
+    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 };
+    }
+  }
+  _scopeAllows(principal, provider) {
+    const filter = this._scopeFilter;
+    return !filter || !principal || filter(principal, provider);
+  }
+  _policyAllows(principal, provider, operation) {
+    const authorization = this._authorization;
+    if (!authorization) return true;
+    const subject = this._subjectFor(principal);
+    const resource = authorization.slotResourceResolver.resolve(provider);
+    if (!resource) {
+      const decision = { allowed: false, reason: "unknown-resource" };
+      writeAuthorizationAuditEvent(makeAuthorizationAuditEvent({ subject, slot: _AggregateServer.SLOT, provider }, decision));
+      return false;
+    }
+    try {
+      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 = { allowed: false, reason: "no-matching-grant" };
+      writeAuthorizationAuditEvent(
+        makeAuthorizationAuditEvent(
+          {
+            subject,
+            slot: _AggregateServer.SLOT,
+            resource,
+            provider
+          },
+          decision
+        )
+      );
+      return false;
+    }
+  }
+  _allows(principal, provider, operation) {
+    return this._scopeAllows(principal, provider) && this._policyAllows(principal, provider, operation);
+  }
+  async _handleClientMessage(data, principal) {
+    let msg;
+    try {
+      msg = JSON.parse(data);
+    } catch {
+      return;
+    }
+    const id = msg.id;
+    if (id == null) return;
+    switch (msg.method) {
+      case "initialize":
+        this._reply(id, {
+          result: {
+            protocolVersion: PROTOCOL_VERSION2,
+            serverInfo: { name: _AggregateServer.SLOT, version: "0" },
+            capabilities: { tools: { listChanged: true }, prompts: { listChanged: true } }
+          }
+        });
+        break;
+      case "ping":
+        this._reply(id, { result: {} });
+        break;
+      case "tools/list":
+        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.promptsFor((provider) => this._allows(principal, provider, { method: "prompts/list" }))
+          }
+        });
+        break;
+      case "tools/call":
+        await this._route(id, msg.params, "tool", principal);
+        break;
+      case "prompts/get":
+        await this._route(id, msg.params, "prompt", principal);
+        break;
+      default:
+        this._reply(id, { error: { code: -32601, message: `Method not found: ${msg.method ?? "(none)"}` } });
+    }
+  }
+  async _route(id, params, kind, principal) {
+    const p = params ?? {};
+    const route = p.name ? kind === "tool" ? this._catalog.resolveTool(p.name) : this._catalog.resolvePrompt(p.name) : void 0;
+    const operation = route ? kind === "tool" ? { method: "tools/call", params: { name: route.original } } : { method: "prompts/get", params: { name: route.original } } : void 0;
+    if (!route || !operation || !this._allows(principal, route.provider, operation)) {
+      this._reply(id, { error: { code: -32602, message: `Unknown aggregated ${kind}: ${p.name ?? "(none)"}` } });
+      return;
+    }
+    const session = this._sessions.get(route.provider);
+    if (!session) {
+      this._reply(id, { error: { code: -32e3, message: `Provider "${route.provider}" is no longer connected` } });
+      return;
+    }
+    const args = p.arguments ?? {};
+    const outcome = kind === "tool" ? await session.callTool(route.original, args) : await session.getPrompt(route.original, args);
+    this._reply(id, outcome.error !== void 0 ? { error: outcome.error } : { result: outcome.result });
+  }
+  _reply(id, body) {
+    this.onMessage?.(JSON.stringify({ jsonrpc: "2.0", id, ...body }));
+  }
+  _emitListChanged() {
+    if (!this._running) return;
+    this.onMessage?.(JSON.stringify({ jsonrpc: "2.0", method: "notifications/tools/list_changed" }));
+    this.onMessage?.(JSON.stringify({ jsonrpc: "2.0", method: "notifications/prompts/list_changed" }));
+  }
+};
+var AuthError = McpAuthError;
+function scopesOf(claims) {
+  const set = new Set(scopesOf$1(claims));
+  const arrayForm = claims["scopes"];
+  if (Array.isArray(arrayForm)) {
+    for (const scope of arrayForm) if (typeof scope === "string" && scope) set.add(scope);
+  }
+  return set;
+}
+var JwtTokenValidator = class {
+  _jwks;
+  _issuer;
+  _clockTolerance;
+  constructor(options) {
+    this._jwks = createRemoteJWKSet(new URL(options.jwksUri));
+    this._issuer = options.issuer;
+    this._clockTolerance = options.clockToleranceSec ?? 0;
+  }
+  async validate(token, resource) {
+    try {
+      const { payload } = await jwtVerify(token, this._jwks, {
+        audience: resource,
+        issuer: this._issuer,
+        clockTolerance: this._clockTolerance
+      });
+      return payload;
+    } catch (err) {
+      if (err instanceof errors.JOSEError) {
+        throw new AuthError(401, "invalid_token", err.message);
+      }
+      throw err;
+    }
+  }
+};
+function buildResourceMetadata(params) {
+  return buildProtectedResourceMetadata({
+    resource: params.resource,
+    authorizationServers: params.authorizationServers,
+    scopesSupported: params.scopesSupported
+  });
+}
+var PRM_PREFIX = `${PROTECTED_RESOURCE_METADATA_PREFIX}/`;
+var HttpAuthGuard = class {
+  _auth;
+  /** The `/mcp` suffix without a leading slash, e.g. `"mcp"`. */
+  _mcpSuffix;
+  constructor(auth, mcpSuffix) {
+    this._auth = auth;
+    this._mcpSuffix = mcpSuffix.replace(/^\//, "");
+  }
+  /** Canonical resource identifier for a slot (RFC 8707 §2). */
+  resourceFor(slot) {
+    return `${this._auth.publicBaseUrl}/${encodeURIComponent(slot)}/${this._mcpSuffix}`;
+  }
+  /** RFC 9728 metadata URL for a slot, advertised in the `401` challenge. */
+  metadataUrlFor(slot) {
+    return `${this._auth.publicBaseUrl}${PRM_PREFIX}${encodeURIComponent(slot)}/${this._mcpSuffix}`;
+  }
+  /** Required scope(s) for a slot: per-slot override, else the baseline. */
+  requiredScopesFor(slot) {
+    return this._auth.perSlotScopes?.[slot] ?? this._auth.requiredScopes ?? [];
+  }
+  /** The RFC 9728 metadata document for a slot. */
+  metadataFor(slot) {
+    return buildResourceMetadata({
+      resource: this.resourceFor(slot),
+      authorizationServers: this._auth.authorizationServers,
+      scopesSupported: this._auth.scopesSupported
+    });
+  }
+  /**
+   * If `rawUrl` is a Protected Resource Metadata request
+   * (`/.well-known/oauth-protected-resource/<slot>/<mcp>`), returns the slot;
+   * otherwise `null`.
+   */
+  matchMetadataRequest(rawUrl) {
+    if (!rawUrl.startsWith(PRM_PREFIX)) return null;
+    const parts = rawUrl.slice(PRM_PREFIX.length).split("/").filter(Boolean);
+    if (parts.length !== 2 || parts[1] !== this._mcpSuffix) return null;
+    return decodeURIComponent(parts[0]);
+  }
+  /**
+   * Validates the request's bearer token against the slot's canonical resource
+   * and enforces the slot's required scopes. Resolves to the {@link IPrincipal}
+   * on success; rejects with an {@link AuthError} (`401` missing/invalid token,
+   * `403` insufficient scope) otherwise.
+   */
+  async authorize(req, slot) {
+    const token = bearerToken(req.headers["authorization"]);
+    if (!token) {
+      throw new AuthError(401, "invalid_token", "Missing bearer token");
+    }
+    const claims = await this._auth.validator.validate(token, this.resourceFor(slot));
+    const scopes = scopesOf(claims);
+    const required = this.requiredScopesFor(slot);
+    const missing = required.filter((s) => !scopes.has(s));
+    if (missing.length > 0) {
+      throw new AuthError(403, "insufficient_scope", `Missing required scope(s): ${missing.join(" ")}`, required.join(" "));
+    }
+    let subject;
+    try {
+      subject = this._auth.authorization?.subjectMapper.map(claims);
+    } catch (error) {
+      if (error instanceof SubjectMappingError) {
+        throw new AuthError(403, "insufficient_scope", "Malformed configured JWT subject claim");
+      }
+      throw error;
+    }
+    return subject ? { claims, scopes, subject } : { claims, scopes };
+  }
+  /**
+   * Builds the RFC 9728 §5.1 `WWW-Authenticate` header value for a challenge.
+   * Always points the client at the slot's metadata URL so it can discover the
+   * authorization server and retry. Shared by the HTTP and WebSocket paths.
+   */
+  challengeHeader(slot, err) {
+    return buildChallengeHeader({
+      resourceMetadata: this.metadataUrlFor(slot),
+      error: err.code,
+      errorDescription: err.description,
+      scope: err.scope
+    });
+  }
+  /**
+   * Writes an RFC 9728 §5.1 `WWW-Authenticate` challenge and the matching
+   * status to an HTTP response.
+   */
+  writeChallenge(res, slot, err) {
+    res.setHeader("WWW-Authenticate", this.challengeHeader(slot, err));
+    res.writeHead(err.status, { "Content-Type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify({ error: err.code, error_description: err.description }));
+  }
+};
+
+// src/auth/auth.config.ts
+function makeProviderScopeFilter(providerScopes) {
+  return (principal, providerName) => {
+    const required = providerScopes[providerName];
+    if (!required || required.length === 0) return true;
+    return required.some((scope) => principal.scopes.has(scope));
+  };
+}
+function stripTrailingSlash(url) {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+function buildJwtAuth(options) {
+  if (!options.publicBaseUrl) {
+    throw new Error("auth: publicBaseUrl is required.");
+  }
+  if (!options.authorizationServers || options.authorizationServers.length === 0) {
+    throw new Error("auth: at least one authorizationServers entry is required.");
+  }
+  if (!options.jwksUri) {
+    throw new Error("auth: jwksUri is required.");
+  }
+  const publicBaseUrl = stripTrailingSlash(options.publicBaseUrl);
+  const issuer = options.issuer ?? (options.authorizationServers.length === 1 ? options.authorizationServers[0] : void 0);
+  const validator = new JwtTokenValidator({
+    jwksUri: options.jwksUri,
+    issuer,
+    clockToleranceSec: options.clockToleranceSec
+  });
+  const resolved = {
+    publicBaseUrl,
+    authorizationServers: options.authorizationServers,
+    validator
+  };
+  if (options.scopesSupported) resolved.scopesSupported = options.scopesSupported;
+  if (options.requiredScopes) resolved.requiredScopes = options.requiredScopes;
+  if (options.perSlotScopes) resolved.perSlotScopes = options.perSlotScopes;
+  if (options.providerScopes && Object.keys(options.providerScopes).length > 0) {
+    console.warn("[mcp-broker] auth.providerScopes is deprecated; migrate to roles and hierarchical assignments.");
+    resolved.aggregateScopeFilter = makeProviderScopeFilter(options.providerScopes);
+  }
+  if (options.slotResources && Object.keys(options.slotResources).length > 0) {
+    resolved.slotResourceResolver = new DefaultSlotResourceResolver(options.slotResources);
+  }
+  if (hasAuthorizationPolicies(options)) {
+    resolved.authorization = compileAuthorizationPolicy(options);
+    resolved.slotResourceResolver = resolved.authorization.slotResourceResolver;
+  }
+  return resolved;
+}
+function normalizeProviderAuthentication(result, fallbackId = "legacy-provider") {
+  if (typeof result === "boolean") {
+    return result ? { authenticated: true, principal: { id: fallbackId, allowedResources: ["**"] } } : { authenticated: false };
+  }
+  if (!result.authenticated) return result;
+  if (!result.principal.id) return { authenticated: false, reason: "provider principal id is empty" };
+  return result;
+}
+function providerMayPublish(principal, resource) {
+  const allowed = principal.allowedResources;
+  if (allowed === void 0) return true;
+  if (allowed.length === 0) return false;
+  try {
+    const patterns = allowed.map((pattern) => ResourcePathPattern.parse(pattern));
+    return patterns.some((pattern) => pattern.matches(resource));
+  } catch {
+    return false;
+  }
+}
+function safeEqual(a, b) {
+  const ab = Buffer.from(a);
+  const bb = Buffer.from(b);
+  if (ab.length !== bb.length) return false;
+  return timingSafeEqual(ab, bb);
+}
+function presentedSecret(req) {
+  const xheader = req.headers["x-provider-token"];
+  if (typeof xheader === "string" && xheader.trim()) return xheader.trim();
+  const auth = req.headers["authorization"];
+  if (typeof auth === "string") {
+    const match = /^Bearer\s+(.+)$/i.exec(auth.trim());
+    if (match) return match[1].trim();
+  }
+  return null;
+}
+var SharedSecretProviderAuthenticator = class {
+  _secret;
+  constructor(secret) {
+    if (!secret) {
+      throw new Error("provider auth: a non-empty shared secret is required.");
+    }
+    this._secret = secret;
+  }
+  authenticate(req) {
+    const presented = presentedSecret(req);
+    if (!presented || !safeEqual(presented, this._secret)) {
+      return { authenticated: false };
+    }
+    return {
+      authenticated: true,
+      principal: {
+        id: "shared-secret",
+        allowedResources: ["**"]
+      }
+    };
+  }
+};
+var require2 = createRequire(import.meta.url);
+var pkg = require2("../package.json");
+var VERSION = pkg.version;
+var PACKAGE_NAME = pkg.name;
+
+// src/ws/ws.tunnel.ts
+var MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".mjs": "application/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".ico": "image/x-icon",
+  ".woff2": "font/woff2",
+  ".woff": "font/woff"
+};
+function requestIdOf(frame) {
+  try {
+    const parsed = JSON.parse(frame);
+    if (typeof parsed?.id === "string" || typeof parsed?.id === "number") return parsed.id;
+  } catch {
+  }
+  return void 0;
+}
+function originPredicate(allowed) {
+  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);
+}
+function openTransport(transport) {
+  if ("connect" in transport && typeof transport.connect === "function") {
+    transport.connect();
+  }
+}
+var WsTunnel = class {
+  _options;
+  _httpServer = null;
+  _wss = null;
+  /**
+   * Per-provider state, keyed by provider name.
+   * Created lazily: a slot is allocated the first time any client references
+   * a provider name, even before the provider WebSocket connects.
+   */
+  _providers = /* @__PURE__ */ new Map();
+  /** Maps a multiplexed WebSocket to the set of provider names it feeds. */
+  _multiplexSockets = /* @__PURE__ */ new Map();
+  /** Upstream providers (stdio child processes and remote URL servers), keyed by name. */
+  _upstreams = /* @__PURE__ */ new Map();
+  /**
+   * In-process loopback transports registered as provider slots.
+   * Used by the embedded broker server (`_broker`) and any other component
+   * that wants to expose itself as a provider without going through a network.
+   */
+  _loopbackProviders = /* @__PURE__ */ new Map();
+  /** The embedded broker MCP server, when {@link IWsTunnelOptions.enableBrokerProvider} is on. */
+  _brokerServer = null;
+  /** The aggregate MCP server (`_all` slot), when {@link IWsTunnelOptions.enableAggregateProvider} is on. */
+  _aggregateServer = null;
+  /** Provider name that the stdio client transport is bridged to, or null when disabled. */
+  _stdioClientProvider = null;
+  /** mcp-core transport connected to the broker process stdin/stdout. */
+  _stdioClientTransport = null;
+  /** Timestamp of the most recent successful `start()`. */
+  _startedAt = null;
+  /** HTTP resource-server enforcement point, or `null` when auth is disabled. */
+  _authGuard;
+  /** Provider (engine) authenticator, or `null` when provider auth is disabled. */
+  _providerAuth;
+  /** Compiled hierarchical authorization, or `null` for legacy behavior. */
+  _authorization;
+  /** Stable technical-slot to hierarchical-resource mapping. */
+  _slotResourceResolver;
+  /** Origin check applied by every slot's Streamable HTTP endpoint. */
+  _allowedOrigins;
+  /** Principal captured at a client's WS upgrade, keyed by the upgrade request. */
+  _pendingClientPrincipals = /* @__PURE__ */ new WeakMap();
+  /** Authenticated principal per raw WS client socket, for `_all` scope filtering. */
+  _clientPrincipals = /* @__PURE__ */ new WeakMap();
+  /** Authenticated principal attached to long-lived HTTP/SSE streams. */
+  _streamPrincipals = /* @__PURE__ */ new WeakMap();
+  /** Provider principals captured during successful WebSocket upgrades. */
+  _pendingProviderPrincipals = /* @__PURE__ */ new WeakMap();
+  _providerPrincipals = /* @__PURE__ */ new WeakMap();
+  constructor(options) {
+    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();
+  }
+  // -------------------------------------------------------------------------
+  // IBrokerContext implementation
+  // -------------------------------------------------------------------------
+  get version() {
+    return VERSION;
+  }
+  get name() {
+    return this._options.brokerName ?? PACKAGE_NAME;
+  }
+  get startedAt() {
+    return this._startedAt;
+  }
+  get uptimeSeconds() {
+    if (!this._startedAt) return 0;
+    return Math.floor((Date.now() - this._startedAt.getTime()) / 1e3);
+  }
+  get host() {
+    return this._options.host;
+  }
+  get port() {
+    return this._options.port;
+  }
+  get tls() {
+    return !!this._options.tls;
+  }
+  get paths() {
+    const o = this._options;
+    return {
+      provider: o.providerPath ?? "/provider",
+      providers: o.providersPath ?? "/providers",
+      client: o.clientPath ?? "/",
+      mcp: o.mcpPath ?? "/mcp",
+      sse: o.ssePath ?? "/sse",
+      messages: o.messagesPath ?? "/messages"
+    };
+  }
+  getProvidersInfo() {
+    const out = [];
+    for (const [name, state] of this._providers) {
+      out.push(this._buildProviderInfo(name, state));
+    }
+    return out;
+  }
+  getProviderInfo(name) {
+    const state = this._providers.get(name);
+    if (!state) return void 0;
+    return this._buildProviderInfo(name, state);
+  }
+  _buildProviderInfo(name, state) {
+    let transport;
+    let connected;
+    if (this._loopbackProviders.get(name)?.isOpen) {
+      transport = "loopback";
+      connected = true;
+    } else if (this._upstreams.get(name)?.isOpen) {
+      transport = "stdio";
+      connected = true;
+    } else if (state.ws?.readyState === WebSocket.OPEN) {
+      transport = this._multiplexSockets.has(state.ws) ? "ws-multiplex" : "ws";
+      connected = true;
+    } else {
+      transport = "none";
+      connected = false;
+    }
+    return {
+      name,
+      transport,
+      connected,
+      clientCount: state.wsClients.size,
+      sessionCount: state.sseSessions.size + state.httpSessions.size,
+      pendingCount: state.pending.size
+    };
+  }
+  // -------------------------------------------------------------------------
+  // Loopback provider registration (in-process transports)
+  // -------------------------------------------------------------------------
+  /**
+   * Registers an in-process transport as a provider slot. Used by the embedded
+   * broker server and may be used by application code that wants to host an
+   * MCP server inside the same process without opening a real WebSocket.
+   *
+   * @throws if the name is already used by a stdio upstream or another loopback.
+   */
+  registerLoopbackProvider(name, transport) {
+    if (this._loopbackProviders.has(name)) {
+      throw new Error(`Loopback provider "${name}" is already registered.`);
+    }
+    if (this._upstreams.has(name)) {
+      throw new Error(`Cannot register loopback "${name}": a stdio upstream with the same name already exists.`);
+    }
+    const state = this._getOrCreateProviderState(name);
+    this._loopbackProviders.set(name, transport);
+    transport.onMessage = (data) => this._routeFromProvider(state, name, data);
+    transport.onClose = () => {
+      this._loopbackProviders.delete(name);
+      this._failProviderDisconnected(state, name);
+    };
+  }
+  /**
+   * Opens an in-process client to a provider slot. The returned handle can
+   * issue MCP requests and receives both the responses and the provider's
+   * 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
+   * JSON-RPC error while the provider is disconnected.
+   */
+  openInternalClient(providerName) {
+    const state = this._getOrCreateProviderState(providerName);
+    let closed = false;
+    const client = {
+      onMessage: null,
+      onClose: null,
+      send: (message) => {
+        if (closed) return;
+        let id = null;
+        try {
+          const parsed = JSON.parse(message);
+          if (parsed?.id != null) id = parsed.id;
+        } catch {
+        }
+        if (this._isProviderConnected(providerName, state)) {
+          if (id != null) state.pending.set(id, { type: "internal", client });
+          this._sendToProvider(state, providerName, message);
+        } else if (id != null) {
+          client.onMessage?.(
+            JSON.stringify({
+              jsonrpc: "2.0",
+              id,
+              error: { code: -32e3, message: `Provider "${providerName}" not connected` }
+            })
+          );
+        }
+      },
+      close: () => {
+        if (closed) return;
+        closed = true;
+        state.internalClients.delete(client);
+        for (const [id, sink] of state.pending) {
+          if (sink.type === "internal" && sink.client === client) state.pending.delete(id);
+        }
+      }
+    };
+    state.internalClients.add(client);
+    return client;
+  }
+  // -------------------------------------------------------------------------
+  // Public state
+  // -------------------------------------------------------------------------
+  get isListening() {
+    return this._httpServer?.listening ?? false;
+  }
+  /** Total number of connected MCP clients across all providers. */
+  get clientCount() {
+    let n = 0;
+    for (const s of this._providers.values()) {
+      n += s.wsClients.size + s.sseSessions.size + s.httpSessions.size;
+    }
+    return n;
+  }
+  /** Names of all providers that currently have an active connection. */
+  get providerNames() {
+    return [...this._providers.entries()].filter(([name, s]) => this._isProviderConnected(name, s)).map(([name]) => name);
+  }
+  /** @deprecated Check `providerNames.length > 0` instead. */
+  get hasProvider() {
+    return this.providerNames.length > 0;
+  }
+  // -------------------------------------------------------------------------
+  // Lifecycle
+  // -------------------------------------------------------------------------
+  /**
+   * Starts the broker. Resolves once the HTTP server is listening.
+   */
+  start() {
+    return new Promise((resolve5) => {
+      const handler = (req, res) => this._handleHttp(req, res);
+      this._httpServer = this._options.tls ? https.createServer({ cert: this._options.tls.cert, key: this._options.tls.key }, handler) : http.createServer(handler);
+      this._wss = new WebSocketServer({ server: this._httpServer, perMessageDeflate: false, verifyClient: this._makeVerifyClient() });
+      this._wss.on("connection", (ws, req) => {
+        const url = req.url ?? "/";
+        const providerPath = this._options.providerPath ?? "/provider";
+        const providersPath = this._options.providersPath ?? "/providers";
+        if (url === providersPath || url.startsWith(providersPath + "?")) {
+          this._onMultiplexProviderConnect(ws, req);
+        } else if (url.startsWith(providerPath + "/") || url === providerPath) {
+          const raw = url.slice(providerPath.length).replace(/^\//, "");
+          const name = decodeURIComponent(raw.split("?")[0]) || "(unnamed)";
+          this._onProviderConnect(ws, name, req);
+        } else {
+          const raw = url.replace(/^\//, "").split("?")[0];
+          const name = decodeURIComponent(raw) || "";
+          this._onClientConnect(ws, name, req);
+        }
+      });
+      this._httpServer.listen(this._options.port, this._options.host ?? "0.0.0.0", () => {
+        this._maybeStartAggregateServer();
+        const wireUpstream = (cfg, upstream) => {
+          upstream.onMessage = (data) => {
+            const state = this._getOrCreateProviderState(cfg.name);
+            this._routeFromProvider(state, cfg.name, data);
+          };
+          upstream.onError = (err) => {
+            console.error(`[broker] ${err.message}`);
+          };
+          upstream.onClose = () => {
+            const state = this._providers.get(cfg.name);
+            if (state) this._failProviderDisconnected(state, cfg.name);
+          };
+          if (cfg.aggregate) {
+            upstream.onOpen = () => void this._aggregateServer?.addProvider(cfg.name);
+          }
+          this._upstreams.set(cfg.name, upstream);
+          upstream.connect();
+        };
+        for (const cfg of this._options.stdioUpstreams ?? []) wireUpstream(cfg, new StdioUpstream(cfg));
+        for (const cfg of this._options.remoteUpstreams ?? []) wireUpstream(cfg, new RemoteUpstream(cfg));
+        if (this._options.stdioClient) {
+          this._stdioClientProvider = this._options.stdioClient.providerName;
+          const transport = new StdioTransport();
+          this._stdioClientTransport = transport;
+          transport.onMessage = (data) => {
+            const state = this._getOrCreateProviderState(this._stdioClientProvider);
+            this._routeFromStdioClient(state, data);
+          };
+          transport.onError = (err) => {
+            console.error(`[broker] stdio client transport: ${err.message}`);
+          };
+          transport.onClose = () => {
+          };
+          transport.connect();
+        }
+        this._startedAt = /* @__PURE__ */ new Date();
+        void this._maybeStartBrokerServer().then(
+          () => resolve5(),
+          (err) => {
+            console.error("[broker] embedded broker server failed to start:", err);
+            resolve5();
+          }
+        );
+      });
+    });
+  }
+  /**
+   * 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 IWsTunnelOptions.enableBrokerProvider}
+   * is `false`.
+   */
+  async _maybeStartBrokerServer() {
+    if (this._options.enableBrokerProvider === false) return;
+    const { server, clientTransport } = await startBrokerServer(this, {
+      grammarResolverOptions: this._options.brokerGrammarResolverOptions,
+      localGrammarsDir: this._options.brokerLocalGrammarsDir
+    });
+    this._brokerServer = server;
+    this.registerLoopbackProvider(BROKER_PROVIDER_NAME, clientTransport);
+    void this._aggregateServer?.addProvider(BROKER_PROVIDER_NAME);
+  }
+  /**
+   * Starts the aggregate MCP server and registers it on the reserved `_all`
+   * slot. No-op when {@link IWsTunnelOptions.enableAggregateProvider} is `false`.
+   */
+  _maybeStartAggregateServer() {
+    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;
+    } catch (err) {
+      console.error(`[broker] aggregate server failed to start: ${err.message}`);
+    }
+  }
+  /**
+   * Gracefully closes all connections and stops the HTTP server.
+   */
+  async stop() {
+    const brokerServer = this._brokerServer;
+    this._brokerServer = null;
+    if (brokerServer) {
+      try {
+        await brokerServer.stop();
+      } catch {
+      }
+    }
+    const aggregateServer = this._aggregateServer;
+    this._aggregateServer = null;
+    if (aggregateServer) {
+      try {
+        aggregateServer.close();
+      } catch {
+      }
+    }
+    this._stdioClientTransport?.close();
+    this._stdioClientTransport = null;
+    this._stdioClientProvider = null;
+    await Promise.all([...this._providers.values()].map((state) => state.httpEndpoint?.closeAll() ?? Promise.resolve()));
+    return new Promise((resolve5, reject) => {
+      for (const state of this._providers.values()) {
+        for (const res of state.sseSessions.values()) res.end();
+        state.sseSessions.clear();
+        state.httpSessions.clear();
+        state.httpEndpoint = null;
+        for (const client of state.wsClients) client.close();
+        state.wsClients.clear();
+        state.ws?.close();
+      }
+      this._providers.clear();
+      this._multiplexSockets.clear();
+      for (const upstream of this._upstreams.values()) upstream.close();
+      this._upstreams.clear();
+      for (const loopback of this._loopbackProviders.values()) loopback.close();
+      this._loopbackProviders.clear();
+      this._startedAt = null;
+      this._wss?.close();
+      this._httpServer?.close((err) => err ? reject(err) : resolve5());
+    });
+  }
+  _authorizationSubject(principal) {
+    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 };
+    }
+  }
+  _auditDecision(subject, slot, resource, capability, tool, decision) {
+    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.
+   */
+  _authorizeMcpFrame(providerName, data, principal) {
+    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 = { allowed: false, reason: "unknown-resource" };
+      this._auditDecision(subject, providerName, void 0, void 0, void 0, decision);
+      return false;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(data);
+    } 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;
+      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 = { allowed: false, reason: "no-matching-grant" };
+        this._auditDecision(subject, providerName, resource, void 0, void 0, decision);
+        return false;
+      }
+    }
+    return true;
+  }
+  _policyDeniedPayload(data) {
+    let id = null;
+    try {
+      const parsed = JSON.parse(data);
+      if (typeof parsed.id === "string" || typeof parsed.id === "number" || parsed.id === null) {
+        id = parsed.id;
+      }
+    } catch {
+    }
+    return JSON.stringify({
+      jsonrpc: "2.0",
+      id,
+      error: { code: -32001, message: "Forbidden" }
+    });
+  }
+  /** The JSON-RPC error returned when the slot has nobody behind it. */
+  _notConnectedPayload(providerName, frame) {
+    return JSON.stringify({
+      jsonrpc: "2.0",
+      id: requestIdOf(frame) ?? null,
+      error: { code: -32e3, message: `Provider "${providerName}" not connected` }
+    });
+  }
+  // -------------------------------------------------------------------------
+  // HTTP dispatcher
+  // -------------------------------------------------------------------------
+  _handleHttp(req, res) {
+    const method = req.method ?? "GET";
+    const rawUrl = (req.url ?? "/").split("?")[0];
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", req.headers["access-control-request-headers"] ?? "Content-Type, Accept, Mcp-Session-Id");
+    res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
+    if (method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+    const samplesIndexPath = this._options.samplesIndexPath ?? "/__samples_index__";
+    if (method === "GET" && rawUrl === samplesIndexPath) {
+      this._handleSamplesIndex(res);
+      return;
+    }
+    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;
+      }
+    }
+    const route = this._parseProviderRoute(rawUrl);
+    if (route) {
+      const { providerName, endpoint } = route;
+      const kind = this._mcpEndpointKind(endpoint, method);
+      if (kind) {
+        if (this._authGuard) {
+          const guard = this._authGuard;
+          void guard.authorize(req, providerName).then(
+            (principal) => this._dispatchMcpEndpoint(kind, req, res, providerName, principal),
+            (err) => this._handleAuthFailure(guard, res, providerName, err)
+          );
+        } else {
+          this._dispatchMcpEndpoint(kind, req, res, providerName, null);
+        }
+        return;
+      }
+    }
+    if (this._options.staticMounts?.length) {
+      this._serveStatic(req, res);
+    } else {
+      res.writeHead(404);
+      res.end();
+    }
+  }
+  /**
+   * Parses `/<providerName>/<endpoint>` from a URL path.
+   * Returns `null` if the URL does not match this two-segment pattern.
+   */
+  _parseProviderRoute(rawUrl) {
+    const parts = rawUrl.split("/").filter(Boolean);
+    if (parts.length !== 2) return null;
+    const providerName = decodeURIComponent(parts[0]);
+    const endpoint = decodeURIComponent(parts[1]);
+    if (!providerName || !endpoint) return null;
+    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).
+   */
+  _mcpEndpointKind(endpoint, method) {
+    const mcpSuffix = (this._options.mcpPath ?? "/mcp").replace(/^\//, "");
+    const sseSuffix = (this._options.ssePath ?? "/sse").replace(/^\//, "");
+    const messagesSuffix = (this._options.messagesPath ?? "/messages").replace(/^\//, "");
+    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. */
+  _dispatchMcpEndpoint(kind, req, res, providerName, principal) {
+    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. */
+  _handleAuthFailure(guard, res, providerName, err) {
+    if (err instanceof AuthError) {
+      guard.writeChallenge(res, providerName, err);
+      return;
+    }
+    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.
+   */
+  _makeVerifyClient() {
+    const guard = this._authGuard;
+    const providerAuth = this._providerAuth;
+    if (!guard && !providerAuth) return void 0;
+    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) {
+        if (!providerAuth) {
+          cb(true);
+          return;
+        }
+        const slot2 = isDedicated ? decodeURIComponent(url.slice(providerPath.length).replace(/^\//, "").split("?")[0]) || void 0 : void 0;
+        Promise.resolve(providerAuth.authenticate(info.req, slot2)).then(
+          (rawResult) => {
+            const result = normalizeProviderAuthentication(rawResult);
+            if (!result.authenticated) {
+              cb(false, 401, "Unauthorized", { "WWW-Authenticate": 'Bearer realm="provider"' });
+              return;
+            }
+            if (slot2 !== void 0) {
+              const resource = this._slotResourceResolver.resolve(slot2);
+              if (!resource || !providerMayPublish(result.principal, resource)) {
+                this._logProviderRegistration(result.principal, slot2, resource, false);
+                cb(false, 403, "Forbidden");
+                return;
+              }
+            }
+            this._pendingProviderPrincipals.set(info.req, result.principal);
+            cb(true);
+          },
+          () => {
+            console.error(`[broker] provider authentication error for "${slot2 ?? "(multiplex)"}".`);
+            cb(false, 500, "server_error");
+          }
+        );
+        return;
+      }
+      if (!guard) {
+        cb(true);
+        return;
+      }
+      const slot = decodeURIComponent(url.replace(/^\//, "").split("?")[0]);
+      void guard.authorize(info.req, slot).then(
+        (principal) => {
+          this._pendingClientPrincipals.set(info.req, principal);
+          cb(true);
+        },
+        (err) => {
+          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.
+   * Sends an `endpoint` event so Claude knows where to POST its requests.
+   */
+  _handleSseConnect(req, res, providerName, principal) {
+    const sessionId = randomUUID();
+    const messagesSuffix = (this._options.messagesPath ?? "/messages").replace(/^\//, "");
+    const messagesUrl = `/${encodeURIComponent(providerName)}/${messagesSuffix}`;
+    res.writeHead(200, {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive"
+    });
+    res.write(`event: endpoint
+data: ${messagesUrl}?sessionId=${sessionId}
+
+`);
+    const state = this._getOrCreateProviderState(providerName);
+    state.sseSessions.set(sessionId, res);
+    if (principal) this._streamPrincipals.set(res, principal);
+    req.on("close", () => {
+      state.sseSessions.delete(sessionId);
+      for (const [id, sink] of state.pending) {
+        if (sink.type === "sse" && sink.sessionId === sessionId) state.pending.delete(id);
+      }
+    });
+  }
+  /**
+   * 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.
+   */
+  _handleSseMessage(req, res, providerName, principal) {
+    const params = new URL(req.url ?? "", "http://localhost").searchParams;
+    const sessionId = params.get("sessionId") ?? "";
+    const state = this._getOrCreateProviderState(providerName);
+    if (!state.sseSessions.has(sessionId)) {
+      res.writeHead(400, { "Content-Type": "text/plain" });
+      res.end("Unknown or expired session");
+      return;
+    }
+    let body = "";
+    req.on("data", (chunk) => {
+      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);
+        if (msg.id != null) state.pending.set(msg.id, { type: "sse", sessionId });
+      } catch {
+      }
+      if (this._isProviderConnected(providerName, state)) {
+        this._sendToProvider(state, providerName, body, principal);
+      } else {
+        const sseRes = state.sseSessions.get(sessionId);
+        if (sseRes) {
+          let errId = null;
+          try {
+            errId = JSON.parse(body).id ?? null;
+          } catch {
+          }
+          this._sendSseEvent(
+            sseRes,
+            JSON.stringify({
+              jsonrpc: "2.0",
+              id: errId,
+              error: { code: -32e3, message: `Provider "${providerName}" not connected` }
+            })
+          );
+        }
+      }
+      res.writeHead(202);
+      res.end();
+    });
+  }
+  /**
+   * 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.
+   */
+  _handleStreamableHttp(req, res, providerName, principal) {
+    const state = this._getOrCreateProviderState(providerName);
+    const sessionId = req.headers["mcp-session-id"];
+    if (typeof sessionId === "string") {
+      const session = state.httpSessions.get(sessionId);
+      if (session) session.principal = principal;
+    }
+    void this._endpointFor(providerName, state).handleRequest(req, res);
+  }
+  /**
+   * 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.
+   */
+  _endpointFor(providerName, state) {
+    if (state.httpEndpoint) return state.httpEndpoint;
+    state.httpEndpoint = new StreamableHttpEndpoint({
+      allowedOrigins: this._allowedOrigins,
+      createServer: (transport, sessionId, _principal) => {
+        const session = { transport, principal: null };
+        state.httpSessions.set(sessionId, session);
+        transport.onMessage = (frame) => 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);
+            for (const [id, sink] of state.pending) {
+              if (sink.type === "http-session" && sink.sessionId === sessionId) state.pending.delete(id);
+            }
+          }
+        };
+      }
+    });
+    return state.httpEndpoint;
+  }
+  /** Relays one frame from an HTTP session to the provider behind the slot. */
+  _fromHttpSession(state, providerName, sessionId, session, frame) {
+    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 !== void 0) 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. */
+  _sendSseEvent(res, data) {
+    res.write(`event: message
+data: ${data}
+
+`);
+  }
+  // -------------------------------------------------------------------------
+  // WebSocket connection handlers
+  // -------------------------------------------------------------------------
+  _logProviderRegistration(principal, slot, resource, allowed) {
+    const event = {
+      timestamp: (/* @__PURE__ */ 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);
+  }
+  _onProviderConnect(ws, name, req) {
+    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.`
+      );
+      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).`);
+      ws.close(1008, `Provider "${name}" is reserved by the broker`);
+      return;
+    }
+    const existing = this._providers.get(name);
+    if (existing?.ws?.readyState === WebSocket.OPEN) {
+      ws.close(1008, `Provider "${name}" is already connected`);
+      return;
+    }
+    const state = this._getOrCreateProviderState(name);
+    state.ws = ws;
+    if (providerPrincipal) {
+      this._logProviderRegistration(providerPrincipal, name, this._slotResourceResolver.resolve(name), true);
+    }
+    let registrationChecked = false;
+    ws.on("message", (data) => {
+      const text = data.toString();
+      if (!registrationChecked) {
+        registrationChecked = true;
+        if (this._tryHandleRegistration(name, text)) return;
+      }
+      this._routeFromProvider(state, name, text);
+    });
+    ws.on("close", () => {
+      state.ws = null;
+      this._failProviderDisconnected(state, name);
+    });
+  }
+  /**
+   * 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
+   * routed as MCP traffic. A normal MCP frame always carries `jsonrpc`, so it
+   * returns `false` and the provider stays non-aggregated.
+   */
+  _tryHandleRegistration(name, text) {
+    let frame;
+    try {
+      frame = JSON.parse(text);
+    } catch {
+      return false;
+    }
+    if (frame.jsonrpc !== void 0 || frame.type !== "register") return false;
+    if (frame.aggregate === true) {
+      void this._aggregateServer?.addProvider(name);
+    }
+    return true;
+  }
+  _onClientConnect(ws, providerName, req) {
+    const state = this._getOrCreateProviderState(providerName);
+    state.wsClients.add(ws);
+    const principal = this._pendingClientPrincipals.get(req);
+    if (principal) {
+      this._clientPrincipals.set(ws, principal);
+      this._pendingClientPrincipals.delete(req);
+    }
+    ws.on("message", (data) => this._routeFromClient(ws, state, providerName, data.toString()));
+    ws.on("close", () => {
+      state.wsClients.delete(ws);
+      for (const [id, sink] of state.pending) {
+        if (sink.type === "ws" && sink.socket === ws) state.pending.delete(id);
+      }
+    });
+  }
+  /**
+   * Handles a multiplexed provider WebSocket (`/providers`).
+   * A single socket carries traffic for multiple providers using the
+   * envelope format `{ provider: string, payload: object }`.
+   * Provider names are registered lazily on first message.
+   */
+  _onMultiplexProviderConnect(ws, req) {
+    const providerNames = /* @__PURE__ */ new Set();
+    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) => {
+      const envelope = decodeEnvelope(data.toString());
+      if (!envelope) return;
+      const name = envelope.provider;
+      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. Rename one of them to avoid the conflict.`
+          );
+          ws.send(encodeErrorEnvelope(name, TunnelErrorCodes.ProviderUnavailable, `Provider "${name}" is managed by a stdio upstream`));
+          return;
+        }
+        if (this._loopbackProviders.has(name)) {
+          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) {
+          ws.send(encodeErrorEnvelope(name, TunnelErrorCodes.ProviderUnavailable, `Provider "${name}" is already connected`));
+          return;
+        }
+        providerNames.add(name);
+        const state2 = this._getOrCreateProviderState(name);
+        state2.ws = ws;
+        if (providerPrincipal) {
+          this._logProviderRegistration(providerPrincipal, name, this._slotResourceResolver.resolve(name), true);
+        }
+      }
+      const state = this._providers.get(name);
+      this._routeFromProvider(state, name, envelopeFrame(envelope));
+    });
+    ws.on("close", () => {
+      for (const name of providerNames) {
+        const state = this._providers.get(name);
+        if (state && state.ws === ws) {
+          state.ws = null;
+          this._failProviderDisconnected(state, name);
+        }
+      }
+      this._multiplexSockets.delete(ws);
+    });
+  }
+  // -------------------------------------------------------------------------
+  // Message routing
+  // -------------------------------------------------------------------------
+  /**
+   * Sends a raw JSON-RPC message to a provider, wrapping it in a multiplex
+   * envelope when the provider's WebSocket is a multiplexed connection.
+   */
+  _sendToProvider(state, providerName, data, principal = null) {
+    if (providerName === AggregateServer.SLOT && this._aggregateServer) {
+      this._aggregateServer.sendAs(data, principal);
+      return;
+    }
+    const upstream = this._upstreams.get(providerName);
+    if (upstream?.isOpen) {
+      upstream.send(data);
+      return;
+    }
+    const loopback = this._loopbackProviders.get(providerName);
+    if (loopback?.isOpen) {
+      loopback.send(data);
+      return;
+    }
+    if (!state.ws || state.ws.readyState !== WebSocket.OPEN) return;
+    if (this._multiplexSockets.has(state.ws)) {
+      state.ws.send(encodeEnvelope(providerName, data));
+    } else {
+      state.ws.send(data);
+    }
+  }
+  _routeFromStdioClient(state, data) {
+    try {
+      const msg = JSON.parse(data);
+      if (msg?.id != null) state.pending.set(msg.id, { type: "stdio" });
+    } catch {
+    }
+    if (this._isProviderConnected(this._stdioClientProvider, state)) {
+      this._sendToProvider(state, this._stdioClientProvider, data);
+    } else {
+      let errId = null;
+      try {
+        errId = JSON.parse(data).id ?? null;
+      } catch {
+      }
+      if (errId != null) {
+        this._stdioClientTransport?.send(
+          JSON.stringify({
+            jsonrpc: "2.0",
+            id: errId,
+            error: { code: -32e3, message: `Provider "${this._stdioClientProvider}" not connected` }
+          })
+        );
+      }
+    }
+  }
+  _routeFromClient(client, state, providerName, data) {
+    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);
+      if (msg?.id != null) state.pending.set(msg.id, { type: "ws", socket: client });
+    } catch {
+    }
+    if (this._isProviderConnected(providerName, state)) {
+      this._sendToProvider(state, providerName, data, principal);
+    } else {
+      client.send(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          id: null,
+          error: { code: -32e3, message: "No provider connected" }
+        })
+      );
+    }
+  }
+  _routeFromProvider(state, providerName, data) {
+    try {
+      const msg = JSON.parse(data);
+      if (msg.id != null) {
+        const sink = state.pending.get(msg.id);
+        if (sink?.type === "ws" && sink.socket.readyState === WebSocket.OPEN) {
+          sink.socket.send(data);
+        } else if (sink?.type === "sse") {
+          const sseRes = state.sseSessions.get(sink.sessionId);
+          if (sseRes) this._sendSseEvent(sseRes, data);
+        } else if (sink?.type === "http-session") {
+          state.httpSessions.get(sink.sessionId)?.transport.send(data);
+        } else if (sink?.type === "stdio") {
+          this._stdioClientTransport?.send(data);
+        } else if (sink?.type === "internal") {
+          sink.client.onMessage?.(data);
+        }
+        state.pending.delete(msg.id);
+      } else {
+        this._broadcast(state, providerName, data);
+      }
+    } catch {
+      this._broadcast(state, providerName, data);
+    }
+  }
+  /** Sends a message to all clients connected to one provider. */
+  _broadcast(state, providerName, data) {
+    for (const client of state.wsClients) {
+      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()) {
+      const principal = this._streamPrincipals.get(sseRes) ?? null;
+      if (this._authorizeMcpFrame(providerName, data, principal)) {
+        this._sendSseEvent(sseRes, data);
+      }
+    }
+    for (const session of state.httpSessions.values()) {
+      if (this._authorizeMcpFrame(providerName, data, session.principal)) {
+        session.transport.send(data);
+      }
+    }
+    for (const ic of state.internalClients) {
+      ic.onMessage?.(data);
+    }
+    if (this._stdioClientProvider && this._providers.get(this._stdioClientProvider) === state) {
+      this._stdioClientTransport?.send(data);
+    }
+  }
+  /**
+   * Notifies every pending sink and internal client that the provider slot
+   * has disconnected, then clears the pending map. Shared by all provider
+   * close handlers (dedicated WS, multiplexed WS, loopback).
+   */
+  _failProviderDisconnected(state, name) {
+    for (const [id, sink] of state.pending) {
+      const error = JSON.stringify({
+        jsonrpc: "2.0",
+        id,
+        error: { code: -32e3, 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-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);
+      }
+    }
+    state.pending.clear();
+    for (const ic of state.internalClients) ic.onClose?.();
+  }
+  // -------------------------------------------------------------------------
+  // Provider state helpers
+  // -------------------------------------------------------------------------
+  /**
+   * Returns `true` if the provider is reachable, via a WebSocket connection,
+   * a stdio upstream, or an in-process loopback transport.
+   */
+  _isProviderConnected(providerName, state) {
+    if (this._upstreams.get(providerName)?.isOpen) return true;
+    if (this._loopbackProviders.get(providerName)?.isOpen) return true;
+    if (state.ws?.readyState === WebSocket.OPEN) return true;
+    return false;
+  }
+  /** Returns the state for `name`, creating it lazily if it doesn't exist yet. */
+  _getOrCreateProviderState(name) {
+    let state = this._providers.get(name);
+    if (!state) {
+      state = {
+        ws: null,
+        pending: /* @__PURE__ */ new Map(),
+        sseSessions: /* @__PURE__ */ new Map(),
+        httpSessions: /* @__PURE__ */ new Map(),
+        wsClients: /* @__PURE__ */ new Set(),
+        internalClients: /* @__PURE__ */ new Set(),
+        httpEndpoint: null
+      };
+      this._providers.set(name, state);
+    }
+    return state;
+  }
+  // -------------------------------------------------------------------------
+  // Samples index
+  // -------------------------------------------------------------------------
+  _handleSamplesIndex(res) {
+    const rootMount = (this._options.staticMounts ?? []).find((m) => m.urlPrefix === "/");
+    let files = [];
+    if (rootMount) {
+      const samplesDir = nodePath.join(rootMount.dir, "samples");
+      try {
+        if (fs.existsSync(samplesDir) && fs.statSync(samplesDir).isDirectory()) {
+          files = fs.readdirSync(samplesDir).filter((name) => fs.statSync(nodePath.join(samplesDir, name)).isFile());
+        }
+      } catch {
+      }
+    }
+    res.writeHead(200, { "Content-Type": "application/json; charset=utf-8" });
+    res.end(JSON.stringify({ files }));
+  }
+  // -------------------------------------------------------------------------
+  // Static file serving
+  // -------------------------------------------------------------------------
+  _serveStatic(req, res) {
+    const rawUrl = (req.url ?? "/").split("?")[0].split("#")[0];
+    const mounts = this._options.staticMounts ?? [];
+    const mount = [...mounts].filter((m) => {
+      const prefix = m.urlPrefix.endsWith("/") ? m.urlPrefix : m.urlPrefix + "/";
+      return rawUrl === m.urlPrefix || rawUrl.startsWith(prefix);
+    }).sort((a, b) => b.urlPrefix.length - a.urlPrefix.length)[0];
+    if (!mount) {
+      res.writeHead(404, { "Content-Type": "text/plain" });
+      res.end("Not found");
+      return;
+    }
+    const relative2 = rawUrl.slice(mount.urlPrefix.length) || "/";
+    const normalized = nodePath.normalize(relative2);
+    if (normalized.startsWith("..")) {
+      res.writeHead(403);
+      res.end("Forbidden");
+      return;
+    }
+    const mountAbs = nodePath.resolve(mount.dir);
+    let filePath = nodePath.join(mountAbs, normalized);
+    if (!filePath.startsWith(mountAbs + nodePath.sep) && filePath !== mountAbs) {
+      res.writeHead(403);
+      res.end("Forbidden");
+      return;
+    }
+    try {
+      if (fs.statSync(filePath).isDirectory()) filePath = nodePath.join(filePath, "index.html");
+    } catch {
+      res.writeHead(404);
+      res.end("Not found");
+      return;
+    }
+    if (!fs.existsSync(filePath)) {
+      res.writeHead(404);
+      res.end("Not found");
+      return;
+    }
+    const ext = nodePath.extname(filePath).toLowerCase();
+    res.writeHead(200, { "Content-Type": MIME[ext] ?? "application/octet-stream" });
+    fs.createReadStream(filePath).pipe(res);
+  }
+};
+var WsTunnelBuilder = class {
+  _port = 3e3;
+  _host;
+  _providerPath = "/provider";
+  _providersPath = "/providers";
+  _clientPath = "/";
+  _ssePath = "/sse";
+  _messagesPath = "/messages";
+  _mcpPath = "/mcp";
+  _samplesIndexPath = "/__samples_index__";
+  _allowedOrigins = void 0;
+  _staticMounts = [];
+  _stdioUpstreams = [];
+  _remoteUpstreams = [];
+  _stdioClient = void 0;
+  _tls = void 0;
+  _brokerLocalGrammarsDir = void 0;
+  _auth = void 0;
+  _providerAuth = void 0;
+  _authorization = void 0;
+  _slotResourceResolver = void 0;
+  /** Sets the TCP port the broker listens on. */
+  withPort(port) {
+    this._port = port;
+    return this;
+  }
+  /**
+   * Sets the host/interface to bind to.
+   * @default "0.0.0.0" (all interfaces)
+   */
+  withHost(host) {
+    this._host = host;
+    return this;
+  }
+  /**
+   * Sets the URL path the MCP provider connects to.
+   * @default "/provider"
+   */
+  withProviderPath(path) {
+    this._providerPath = path;
+    return this;
+  }
+  /**
+   * Sets the URL path for multiplexed provider connections.
+   * Multiple providers share a single WebSocket using the envelope protocol.
+   * @default "/providers"
+   */
+  withProvidersPath(path) {
+    this._providersPath = path;
+    return this;
+  }
+  /**
+   * Sets the URL path MCP clients connect to.
+   * @default "/"
+   */
+  withClientPath(path) {
+    this._clientPath = path;
+    return this;
+  }
+  /**
+   * Sets the URL path for the SSE stream (legacy Claude transport, GET).
+   * @default "/sse"
+   */
+  withSsePath(path) {
+    this._ssePath = path;
+    return this;
+  }
+  /**
+   * Sets the URL path for JSON-RPC POST requests (legacy Claude transport).
+   * @default "/messages"
+   */
+  withMessagesPath(path) {
+    this._messagesPath = path;
+    return this;
+  }
+  /**
+   * Sets the URL path for the Streamable HTTP transport (MCP 2025-03-26).
+   * MCP Inspector and other 2025+ clients POST JSON-RPC here.
+   * @default "/mcp"
+   */
+  withMcpPath(path) {
+    this._mcpPath = path;
+    return this;
+  }
+  /**
+   * Sets the URL path that returns a `{ files: string[] }` listing of the
+   * `samples/` subdirectory under the root static mount.
+   * @default "/__samples_index__"
+   */
+  withSamplesIndexPath(path) {
+    this._samplesIndexPath = path;
+    return this;
+  }
+  /**
+   * Allows browser origins to reach `/<slot>/mcp`.
+   *
+   * Without this call no browser origin is accepted, which is the safe
+   * default: a request carrying an `Origin` is refused with `403`, while one
+   * carrying none (any non-browser client) always passes. Call it only when a
+   * web page really has to talk to the broker over HTTP.
+   *
+   * @example
+   * ```typescript
+   * builder.withAllowedOrigins(["https://app.example.com"]);
+   * builder.withAllowedOrigins(/^https:\/\/[a-z0-9-]+\.example\.com$/);
+   * builder.withAllowedOrigins((origin) => origin.endsWith(".example.com"));
+   * ```
+   */
+  withAllowedOrigins(allowed) {
+    this._allowedOrigins = allowed;
+    return this;
+  }
+  /**
+   * Adds a static-file mount served over plain HTTP.
+   * Can be called multiple times; longest-prefix match wins at runtime.
+   *
+   * @param urlPrefix  URL prefix that triggers this mount (e.g. `"/"` or `"/bundle"`).
+   * @param dir        Absolute path to the directory to serve.
+   */
+  withStaticMount(urlPrefix, dir) {
+    this._staticMounts.push({ urlPrefix, dir });
+    return this;
+  }
+  /**
+   * Registers a stdio upstream provider. The broker spawns the configured
+   * command and bridges its stdin/stdout as an MCP transport. Clients reach
+   * it using `config.name` directly (e.g. `/<name>/mcp`).
+   *
+   * Can be called multiple times to register multiple providers.
+   */
+  withStdioUpstream(config) {
+    this._stdioUpstreams.push(config);
+    return this;
+  }
+  /**
+   * Registers a remote MCP server reached by URL. The broker connects out to
+   * it and exposes it as a provider slot named `config.name`, bridging the
+   * Streamable HTTP / SSE / WebSocket transport for the slot's clients.
+   *
+   * Can be called multiple times to register multiple servers.
+   */
+  withRemoteUpstream(config) {
+    this._remoteUpstreams.push(config);
+    return this;
+  }
+  /**
+   * Enables the stdio client transport. The broker will read JSON-RPC from
+   * `process.stdin` and write responses to `process.stdout`, bridging Claude
+   * Desktop (or any stdio MCP client) to the named provider.
+   *
+   * All console output is automatically redirected to stderr in this mode so
+   * stdout stays clean for the JSON-RPC stream.
+   *
+   * @param providerName  The provider the stdio client maps to.
+   */
+  withStdioClient(providerName) {
+    this._stdioClient = { providerName };
+    return this;
+  }
+  /**
+   * Enables HTTPS/WSS mode by supplying PEM-encoded certificate and key strings directly.
+   * Call this when you already have the PEM content in memory.
+   */
+  withTls(cert, key) {
+    this._tls = { cert, key };
+    return this;
+  }
+  /**
+   * Enables HTTPS/WSS mode by reading the certificate and key from the given file paths.
+   * Files are read synchronously at call time.
+   *
+   * @param certPath  Path to the PEM certificate file (e.g. `fullchain.pem`).
+   * @param keyPath   Path to the PEM private-key file (e.g. `privkey.pem`).
+   */
+  withTlsFiles(certPath, keyPath) {
+    return this.withTls(fs.readFileSync(certPath, "utf8"), fs.readFileSync(keyPath, "utf8"));
+  }
+  /**
+   * Sets the path to a user-supplied grammars directory whose
+   * `<userAgent>/<locale>.json` files are merged on top of the packaged
+   * grammars used by the embedded broker server (the reserved `_broker`
+   * provider slot). Typically pointed at `.mcp-broker/grammars/`.
+   */
+  withBrokerLocalGrammarsDir(dir) {
+    this._brokerLocalGrammarsDir = dir;
+    return this;
+  }
+  /**
+   * Enables OAuth 2.1 resource-server authorization with a pre-resolved config
+   * (e.g. a custom {@link IResolvedAuth} carrying your own `ITokenValidator`).
+   * Prefer {@link withJwtAuth} for the standard JWKS-backed setup.
+   */
+  withAuth(auth) {
+    this._auth = auth;
+    return this;
+  }
+  /**
+   * Enables OAuth 2.1 authorization with the default stateless JWT validator:
+   * the broker verifies each bearer token's signature against the authorization
+   * server's JWKS and its audience against the slot's canonical resource URI.
+   *
+   * @throws if `publicBaseUrl`, `authorizationServers`, or `jwksUri` are missing.
+   */
+  withJwtAuth(options) {
+    this._auth = buildJwtAuth(options);
+    return this;
+  }
+  /** Installs a custom policy engine behind the broker's transport-neutral API. */
+  withPolicyEngine(engine) {
+    this._authorization = authorizationWithEngine(engine, {
+      slotResourceResolver: this._slotResourceResolver
+    });
+    return this;
+  }
+  /** Compiles and validates roles, assignments, denies, mappings, and paths. */
+  withAuthorizationPolicy(config) {
+    this._authorization = compileAuthorizationPolicy(config);
+    return this;
+  }
+  /** Overrides the technical slot to hierarchical resource resolution strategy. */
+  withSlotResourceResolver(resolver) {
+    this._slotResourceResolver = resolver;
+    return this;
+  }
+  /**
+   * Authenticates providers (engines) with a custom {@link IProviderAuthenticator}.
+   * Prefer {@link withProviderSecret} for the standard shared-secret setup.
+   */
+  withProviderAuth(authenticator) {
+    this._providerAuth = authenticator;
+    return this;
+  }
+  /**
+   * Requires every provider connecting to `/provider/<slot>` or `/providers` to
+   * present the given shared secret (via `X-Provider-Token` or `Authorization:
+   * Bearer`). Closes off slot occupation by strangers.
+   */
+  withProviderSecret(secret) {
+    this._providerAuth = new SharedSecretProviderAuthenticator(secret);
+    return this;
+  }
+  /** Constructs and returns a configured {@link WsTunnel}. */
+  build() {
+    const baseAuthorization = this._authorization ?? this._auth?.authorization;
+    const authorization = baseAuthorization && this._slotResourceResolver ? { ...baseAuthorization, slotResourceResolver: this._slotResourceResolver } : baseAuthorization;
+    const options = {
+      port: this._port,
+      host: this._host,
+      providerPath: this._providerPath,
+      providersPath: this._providersPath,
+      clientPath: this._clientPath,
+      ssePath: this._ssePath,
+      messagesPath: this._messagesPath,
+      mcpPath: this._mcpPath,
+      samplesIndexPath: this._samplesIndexPath,
+      allowedOrigins: this._allowedOrigins,
+      staticMounts: this._staticMounts.length > 0 ? [...this._staticMounts] : void 0,
+      stdioUpstreams: this._stdioUpstreams.length > 0 ? [...this._stdioUpstreams] : void 0,
+      remoteUpstreams: this._remoteUpstreams.length > 0 ? [...this._remoteUpstreams] : void 0,
+      stdioClient: this._stdioClient,
+      tls: this._tls,
+      brokerLocalGrammarsDir: this._brokerLocalGrammarsDir,
+      auth: this._auth,
+      providerAuth: this._providerAuth,
+      authorization,
+      slotResourceResolver: this._slotResourceResolver ?? authorization?.slotResourceResolver ?? this._auth?.slotResourceResolver
+    };
+    return new WsTunnel(options);
+  }
+};
+var EOCD_SIGNATURE = 101010256;
+var CENTRAL_HEADER_SIGNATURE = 33639248;
+var LOCAL_HEADER_SIGNATURE = 67324752;
+function findEocd(buf) {
+  const minPos = Math.max(0, buf.length - 22 - 65535);
+  for (let pos = buf.length - 22; pos >= minPos; pos--) {
+    if (buf.readUInt32LE(pos) === EOCD_SIGNATURE) return pos;
+  }
+  throw new Error("not a ZIP archive (no End Of Central Directory record found)");
+}
+function unzipMcpb(mcpbPath, destDir) {
+  const buf = readFileSync(mcpbPath);
+  const eocd = findEocd(buf);
+  const totalEntries = buf.readUInt16LE(eocd + 10);
+  const centralDirOffset = buf.readUInt32LE(eocd + 16);
+  if (centralDirOffset === 4294967295 || totalEntries === 65535) {
+    throw new Error("ZIP64 archives are not supported");
+  }
+  const absDest = resolve(destDir);
+  mkdirSync(absDest, { recursive: true });
+  let pos = centralDirOffset;
+  for (let i = 0; i < totalEntries; i++) {
+    if (buf.readUInt32LE(pos) !== CENTRAL_HEADER_SIGNATURE) {
+      throw new Error(`corrupt ZIP: bad central directory header at offset ${pos}`);
+    }
+    const method = buf.readUInt16LE(pos + 10);
+    const compressedSize = buf.readUInt32LE(pos + 20);
+    const uncompressedSize = buf.readUInt32LE(pos + 24);
+    const nameLen = buf.readUInt16LE(pos + 28);
+    const extraLen = buf.readUInt16LE(pos + 30);
+    const commentLen = buf.readUInt16LE(pos + 32);
+    const localHeaderOffset = buf.readUInt32LE(pos + 42);
+    const name = buf.toString("utf8", pos + 46, pos + 46 + nameLen);
+    pos += 46 + nameLen + extraLen + commentLen;
+    if (compressedSize === 4294967295 || uncompressedSize === 4294967295 || localHeaderOffset === 4294967295) {
+      throw new Error("ZIP64 archives are not supported");
+    }
+    const target = resolve(absDest, name);
+    const rel = relative(absDest, target);
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+      throw new Error(`unsafe ZIP entry path (zip-slip): ${name}`);
+    }
+    if (name.endsWith("/")) {
+      mkdirSync(target, { recursive: true });
+      continue;
+    }
+    if (buf.readUInt32LE(localHeaderOffset) !== LOCAL_HEADER_SIGNATURE) {
+      throw new Error(`corrupt ZIP: bad local header for "${name}"`);
+    }
+    const localNameLen = buf.readUInt16LE(localHeaderOffset + 26);
+    const localExtraLen = buf.readUInt16LE(localHeaderOffset + 28);
+    const dataStart = localHeaderOffset + 30 + localNameLen + localExtraLen;
+    const compressed = buf.subarray(dataStart, dataStart + compressedSize);
+    let data;
+    if (method === 0) {
+      data = compressed;
+    } else if (method === 8) {
+      data = inflateRawSync(compressed);
+    } else {
+      throw new Error(`unsupported ZIP compression method ${method} for "${name}"`);
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, data);
+  }
+}
+
+// src/mcpb/mcpb.loader.ts
+function loadPublicKey(pem) {
+  if (pem.includes("BEGIN CERTIFICATE")) {
+    return new X509Certificate(pem).publicKey;
+  }
+  return createPublicKey(pem);
+}
+function verifyDetachedSignature(data, signature, publicKey) {
+  const keyType = publicKey.asymmetricKeyType;
+  const algorithm = keyType === "ed25519" || keyType === "ed448" ? null : "sha256";
+  return verify(algorithm, data, publicKey, signature);
+}
+function resolvePlaceholder(key, dirname4, userConfig) {
+  if (key === "__dirname") return dirname4;
+  if (key === "HOME") return homedir();
+  if (key === "DESKTOP") return join(homedir(), "Desktop");
+  if (key === "DOCUMENTS") return join(homedir(), "Documents");
+  if (key === "DOWNLOADS") return join(homedir(), "Downloads");
+  if (key === "pathSeparator" || key === "/") return sep;
+  if (key.startsWith("user_config.")) {
+    const name = key.slice("user_config.".length);
+    const value = userConfig?.[name];
+    if (value === void 0) throw new Error(`missing user_config value: "${name}"`);
+    return value;
+  }
+  return void 0;
+}
+function expandScalar(input, dirname4, userConfig) {
+  return input.replace(/\$\{([^}]+)\}/g, (match, key) => {
+    const value = resolvePlaceholder(key, dirname4, userConfig);
+    if (value === void 0) return match;
+    if (Array.isArray(value)) throw new Error(`placeholder "\${${key}}" is multi-valued and cannot be used here`);
+    return String(value);
+  });
+}
+function expandArg(arg, dirname4, userConfig) {
+  const standalone = /^\$\{(user_config\.[^}]+)\}$/.exec(arg);
+  if (standalone) {
+    const value = resolvePlaceholder(standalone[1], dirname4, userConfig);
+    if (Array.isArray(value)) return value.map(String);
+    return [String(value)];
+  }
+  return [expandScalar(arg, dirname4, userConfig)];
+}
+async function loadMcpbBundle(cfg, baseDir) {
+  const tag2 = `[mcp-broker] mcpb bundle "${cfg.name}"`;
+  try {
+    const mcpbPath = resolve(baseDir, cfg.path);
+    const publicKeyPath = resolve(baseDir, cfg.publicKey);
+    const signaturePath = cfg.signature ? resolve(baseDir, cfg.signature) : `${mcpbPath}.sig`;
+    for (const [label, file] of [
+      ["bundle", mcpbPath],
+      ["public key", publicKeyPath],
+      ["signature", signaturePath]
+    ]) {
+      if (!existsSync(file)) {
+        console.error(`${tag2}: ${label} file not found at ${file}, bundle refused.`);
+        return null;
+      }
+    }
+    const bundleBytes = readFileSync(mcpbPath);
+    const signatureBytes = readFileSync(signaturePath);
+    const publicKey = loadPublicKey(readFileSync(publicKeyPath, "utf8"));
+    if (!verifyDetachedSignature(bundleBytes, signatureBytes, publicKey)) {
+      console.error(`${tag2}: detached signature is invalid for the configured public key, bundle refused.`);
+      return null;
+    }
+    const outputDir = resolve(baseDir, ".cache", "mcpb", cfg.name);
+    rmSync(outputDir, { recursive: true, force: true });
+    unzipMcpb(mcpbPath, outputDir);
+    const manifestPath = join(outputDir, "manifest.json");
+    if (!existsSync(manifestPath)) {
+      console.error(`${tag2}: manifest.json missing inside the bundle, bundle refused.`);
+      return null;
+    }
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    const mcpConfig = manifest.server?.mcp_config;
+    if (!mcpConfig) {
+      console.error(`${tag2}: manifest has no server.mcp_config, bundle refused.`);
+      return null;
+    }
+    const override = mcpConfig.platform_overrides?.[process.platform];
+    const command = override?.command ?? mcpConfig.command;
+    const rawArgs = override?.args ?? mcpConfig.args ?? [];
+    const rawEnv = { ...mcpConfig.env, ...override?.env };
+    if (!command) {
+      console.error(`${tag2}: manifest mcp_config has no command, bundle refused.`);
+      return null;
+    }
+    const expandedCommand = expandScalar(command, outputDir, cfg.userConfig);
+    const expandedArgs = rawArgs.flatMap((arg) => expandArg(arg, outputDir, cfg.userConfig));
+    const expandedEnv = {};
+    for (const [key, value] of Object.entries(rawEnv)) {
+      expandedEnv[key] = expandScalar(value, outputDir, cfg.userConfig);
+    }
+    return {
+      name: cfg.name,
+      command: expandedCommand,
+      args: expandedArgs,
+      env: Object.keys(expandedEnv).length > 0 ? expandedEnv : void 0,
+      aggregate: cfg.aggregate ?? true
+    };
+  } catch (err) {
+    console.error(`${tag2}: ${err.message}, bundle refused.`);
+    return null;
+  }
+}
+var DEFAULT_CONFIG_DIR = ".mcp-broker";
+var DEFAULT_CONFIG_FILENAME = "config.json";
+var LEGACY_CONFIG_FILENAME = "mcp-broker.config.json";
+function loadBrokerConfig(path) {
+  const cwd = process.cwd();
+  const envPath = process.env["MCP_BROKER_CONFIG"];
+  let sourcePath = null;
+  if (path) {
+    sourcePath = resolve(cwd, path);
+  } else if (envPath) {
+    sourcePath = resolve(cwd, envPath);
+  } else {
+    const modern = resolve(cwd, DEFAULT_CONFIG_DIR, DEFAULT_CONFIG_FILENAME);
+    const legacy = resolve(cwd, LEGACY_CONFIG_FILENAME);
+    if (existsSync(modern)) {
+      sourcePath = modern;
+    } else if (existsSync(legacy)) {
+      sourcePath = legacy;
+      process.stderr.write(
+        `[mcp-broker] Using legacy config at ${legacy}. Move it to ${resolve(cwd, DEFAULT_CONFIG_DIR, DEFAULT_CONFIG_FILENAME)} to silence this warning.
+`
+      );
+    }
+  }
+  if (!sourcePath || !existsSync(sourcePath)) {
+    return { config: {}, baseDir: cwd, sourcePath: null };
+  }
+  const baseDir = dirname(sourcePath);
+  try {
+    const raw = readFileSync(sourcePath, "utf-8");
+    const config = JSON.parse(raw);
+    return { config, baseDir, sourcePath };
+  } catch (err) {
+    process.stderr.write(`[mcp-broker] Failed to parse config file at ${sourcePath}: ${err.message}
+`);
+    return { config: {}, baseDir: cwd, sourcePath: null };
+  }
+}
+
+export { AuthError, BROKER_PROVIDER_NAME, BrokerInfoBehavior, BrokerProvidersBehavior, ConfigPolicyEngine, ConfiguredCapabilityClassifier, DEFAULT_CONFIG_FILENAME, DefaultSlotResourceResolver, HttpAuthGuard, JwtSubjectMapper, JwtTokenValidator, PACKAGE_NAME, RemoteUpstream, ResourcePath, ResourcePathPattern, SharedSecretProviderAuthenticator, StdioUpstream, SubjectMappingError, VERSION, WsTunnel, WsTunnelBuilder, authorizationWithEngine, brokerGrammarKey, buildJwtAuth, buildResourceMetadata, compileAuthorizationPolicy, hasAuthorizationPolicies, iterAvailableBrokerGrammars, iterBrokerGrammarsFrom, loadBrokerConfig, loadBrokerGrammar, loadMcpbBundle, normalizeProviderAuthentication, providerMayPublish, scopesOf, startBrokerServer, unzipMcpb, validateCapability };
+//# sourceMappingURL=chunk-FTDKH2C4.js.map
+//# sourceMappingURL=chunk-FTDKH2C4.js.map