@cyanmycelium/mcp-broker 0.4.0 → 1.2.0

package/dist/index.d.ts

@@ -1,18 +1,1790 @@
-export { WsTunnel } from "./ws.tunnel.js";
-export { WsTunnelBuilder } from "./ws.tunnel.builder.js";
-export type { WsTunnelOptions, StaticMount } from "./ws.tunnel.js";
-export { StdioUpstream } from "./stdio.upstream.js";
-export type { StdioUpstreamConfig } from "./stdio.upstream.js";
-export { RemoteUpstream } from "./remote.upstream.js";
-export type { RemoteUpstreamConfig } from "./remote.upstream.js";
-export type { Upstream } from "./upstream.js";
-export { loadMcpbBundle } from "./mcpb.loader.js";
-export type { McpbBundleConfig } from "./mcpb.loader.js";
-export { unzipMcpb } from "./mcpb.unzip.js";
-export { BrokerInfoBehavior, BrokerProvidersBehavior, startBrokerServer, BROKER_PROVIDER_NAME } from "./broker/index.js";
-export type { StartBrokerServerOptions } from "./broker/index.js";
-export { brokerGrammarKey, iterAvailableBrokerGrammars, iterBrokerGrammarsFrom, loadBrokerGrammar } from "./broker/index.js";
-export type { BrokerContext, BrokerProviderInfo, BrokerProviderTransport, BrokerLocale, BrokerUserAgent } from "./broker/index.js";
-export { VERSION, PACKAGE_NAME } from "./version.js";
-export { loadBrokerConfig, DEFAULT_CONFIG_FILENAME } from "./config.js";
-export type { BrokerConfig } from "./config.js";
+import * as _cyanmycelium_mcp_core from '@cyanmycelium/mcp-core';
+import { McpBehavior, McpResource, McpTool, McpResourceTemplate, GrammarResolverOptions, IMcpServer, IMessageTransport, McpGrammar, IAccessTokenClaims, IMcpPrincipal, McpAuthError, ITokenValidator, IProtectedResourceMetadata } from '@cyanmycelium/mcp-core';
+export { IAccessTokenClaims, IProtectedResourceMetadata, ITokenValidator } from '@cyanmycelium/mcp-core';
+import { IncomingMessage, ServerResponse } from 'http';
+
+/**
+ * Read-only view of the broker's runtime state, exposed to broker behaviors.
+ *
+ * Decouples the behaviors from the concrete `WsTunnel` class, making them
+ * unit-testable and reusable (e.g. a future .NET-backed context).
+ */
+interface IBrokerContext {
+    /** Package version (from package.json). */
+    readonly version: string;
+    /** Logical broker name reported to MCP clients. */
+    readonly name: string;
+    /** Timestamp of the most recent successful `start()`, or `null` if never started. */
+    readonly startedAt: Date | null;
+    /** Seconds since `startedAt`, or `0` if not running. */
+    readonly uptimeSeconds: number;
+    /** Bind host. `undefined` means default (`0.0.0.0`). */
+    readonly host: string | undefined;
+    /** TCP port the broker is listening on. */
+    readonly port: number;
+    /** Whether TLS is active for the HTTP/WS server. */
+    readonly tls: boolean;
+    /** All configured URL paths, with defaults already substituted. */
+    readonly paths: {
+        provider: string;
+        providers: string;
+        client: string;
+        mcp: string;
+        sse: string;
+        messages: string;
+    };
+    /** Snapshot of every known provider slot, including disconnected ones. */
+    getProvidersInfo(): IBrokerProviderInfo[];
+    /** Snapshot of a single provider slot, or `undefined` if the name is unknown. */
+    getProviderInfo(name: string): IBrokerProviderInfo | undefined;
+}
+/**
+ * Transport kind currently feeding a provider slot.
+ *
+ * - `ws`: dedicated WebSocket provider (`/provider/<name>`).
+ * - `ws-multiplex`: multiplexed WebSocket envelope on `/providers`.
+ * - `stdio`: child process spawned at broker startup.
+ * - `loopback`: in-process transport (e.g. the broker exposing itself as `_broker`).
+ * - `none`: the slot was referenced by a client but no provider has attached yet.
+ */
+type BrokerProviderTransport = "ws" | "ws-multiplex" | "stdio" | "loopback" | "none";
+interface IBrokerProviderInfo {
+    /** Slot name as advertised on `/<name>/...` endpoints. */
+    name: string;
+    /** Which transport is currently feeding the slot. */
+    transport: BrokerProviderTransport;
+    /** `true` iff the slot is reachable for routing right now. */
+    connected: boolean;
+    /** Number of raw-WebSocket MCP clients on this slot. */
+    clientCount: number;
+    /** Number of long-lived sessions (SSE + Streamable HTTP GET streams). */
+    sessionCount: number;
+    /** Number of in-flight JSON-RPC requests awaiting a response. */
+    pendingCount: number;
+}
+/** @deprecated Use {@link IBrokerContext}. */
+type BrokerContext = IBrokerContext;
+/** @deprecated Use {@link IBrokerProviderInfo}. */
+type BrokerProviderInfo = IBrokerProviderInfo;
+
+/**
+ * Exposes basic broker identity (name, version, uptime, listening config) as
+ * one tool (`broker_info`) and one resource (`broker://info`).
+ *
+ * An MCP agent typically calls `broker_info` first to learn who it is talking to.
+ */
+declare class BrokerInfoBehavior extends McpBehavior {
+    static readonly NAMESPACE = "broker";
+    constructor(context: IBrokerContext);
+    protected _buildResources(): McpResource[];
+    protected _buildTools(): McpTool[];
+}
+
+/**
+ * Exposes the broker's provider slots so an MCP agent can discover what is
+ * currently routable behind the broker, with two tools:
+ *
+ * - `providers_list`: every slot (including disconnected ones).
+ * - `provider_status({ name })`, detail on one slot.
+ *
+ * Plus matching resources at `broker://providers` and `broker://providers/<name>`.
+ */
+declare class BrokerProvidersBehavior extends McpBehavior {
+    static readonly NAMESPACE = "broker_providers";
+    constructor(context: IBrokerContext);
+    protected _buildResources(): McpResource[];
+    protected _buildTemplate(): McpResourceTemplate[];
+    protected _buildTools(): McpTool[];
+}
+
+/**
+ * Reserved provider slot name under which the broker exposes itself as an MCP
+ * server. Clients reach it via `<host>/_broker/mcp` (or any other client transport).
+ *
+ * Prefixed with `_` to make it unambiguously a system slot, and to reduce the
+ * chance of collision with user-supplied provider names.
+ */
+declare const BROKER_PROVIDER_NAME = "_broker";
+/**
+ * Optional knobs passed to {@link startBrokerServer}. Lets the embedder
+ * replace either resolver with custom logic without touching mcp-broker
+ * internals.
+ */
+interface IStartBrokerServerOptions {
+    /**
+     * Overrides for the built-in grammar resolver from `@cyanmycelium/mcp-core`.
+     *
+     * The broker installs sensible defaults: `localeSource` reads
+     * `process.env.MCP_BROKER_LOCALE`, the `agents` map uses the mcp-core
+     * defaults (`claude`, `gpt`, `mistral`, `copilot`, `default`), the
+     * narrowing chain is BCP-47-style, and `fallbackKey` is `default:en`
+     * so the baseline grammar always matches as last resort.
+     *
+     * Pass partial overrides here to inject a custom `localeSource` (e.g.
+     * pull from an HTTP header proxied by your transport), enable the
+     * `versionFrom` dimension, or extend the `agents` map with additional
+     * LLM families. Anything you omit keeps the broker default.
+     */
+    grammarResolverOptions?: Partial<GrammarResolverOptions>;
+    /**
+     * Path to a user-supplied grammars directory whose `<userAgent>/<locale>.json`
+     * files are registered **in addition to** the packaged grammars.
+     *
+     * Both packaged and local entries are registered raw against the server
+     * via `withGrammar(brokerGrammarKey(ua, locale), grammar)`. The
+     * candidate-chain resolution implemented by `McpServer.initialize` in
+     * mcp-core@0.3.0 then walks the chain and merges the four layers
+     * (behavior, adapter, static, store) for the first matching key ,
+     * the old hand-rolled pre-merge cascade is no longer needed.
+     *
+     * When `undefined` (default), only the packaged grammars are loaded.
+     */
+    localGrammarsDir?: string;
+}
+/**
+ * Constructs the broker's own MCP server (the Tier-1 introspection behaviors)
+ * and returns the running server plus the loopback transport that must be
+ * registered against the {@link WsTunnel} as the `_broker` provider slot.
+ *
+ * Usage from {@link WsTunnel.start}:
+ * ```ts
+ * const { server, clientTransport } = await startBrokerServer(this, { ... });
+ * this._registerLoopbackProvider(BROKER_PROVIDER_NAME, clientTransport);
+ * ```
+ *
+ * @param context  Read-only view of the broker's state.
+ * @param options  Optional resolver overrides.
+ * @returns The running {@link IMcpServer} (call `.stop()` on shutdown) and the
+ *          loopback transport to attach to the tunnel.
+ */
+declare function startBrokerServer(context: IBrokerContext, options?: IStartBrokerServerOptions): Promise<{
+    server: IMcpServer;
+    clientTransport: IMessageTransport;
+}>;
+/** @deprecated Use {@link IStartBrokerServerOptions}. */
+type StartBrokerServerOptions = IStartBrokerServerOptions;
+
+/**
+ * Locale identifier used to look up a grammar JSON file under
+ * `<userAgent>/<locale>.json`. Open string: a host application can use any
+ * value its grammar resources support.
+ *
+ * The broker registers each `(userAgent, locale)` pair found on disk as a
+ * separate `McpGrammar` keyed by {@link brokerGrammarKey}. The actual
+ * resolution of "which key to use for this session" is delegated to
+ * `@cyanmycelium/mcp-core@0.3.0`'s `grammarResolverFromOptions`, which
+ * handles BCP-47 narrowing (`fr-CA` → `fr` → `en`), agent-family fallback,
+ * and the optional version dimension natively.
+ */
+type BrokerLocale = string;
+/**
+ * User-agent family identifier used to look up a grammar JSON file under
+ * `<userAgent>/<locale>.json`. Open string. Conventional values follow
+ * the defaults emitted by `grammarResolverFromOptions`: `claude`, `gpt`,
+ * `mistral`, `copilot`, plus the universal `default`. Custom families
+ * are supported by passing a custom `agents` map in
+ * `IStartBrokerServerOptions.grammarResolverOptions`.
+ */
+type BrokerUserAgent = string;
+/**
+ * Builds the canonical grammar key for the `(userAgent, locale, version?)`
+ * matrix the broker registers on disk.
+ *
+ * Pattern:
+ *   - `"<userAgent>:<locale>"` (no version), e.g. `"claude:fr"`, `"default:en"`
+ *   - `"<userAgent>:<locale>@<version>"` (versioned), e.g. `"claude:fr@v2"`
+ *
+ * The colon separator is reserved for the `<ua>:<locale>` composition; the
+ * `@` separator is reserved for the optional version suffix. Neither
+ * character is allowed inside the identifier segments. This matches the
+ * default `composeKey` of `grammarResolverFromOptions` exactly, so a
+ * broker-loaded grammar at `claude/fr@v2.json` is automatically picked up
+ * when a Claude session resolves to the `claude:fr@v2` candidate.
+ */
+declare function brokerGrammarKey(userAgent: BrokerUserAgent, locale: BrokerLocale, version?: string): string;
+/**
+ * Loads and caches the grammar for a given `(userAgent, locale, version?)`
+ * combination. Returns `undefined` (instead of throwing) when the resource
+ * file is missing, so the caller can implement a fallback chain.
+ *
+ * Filename convention on disk:
+ *   - `<userAgent>/<locale>.json` (no version)
+ *   - `<userAgent>/<locale>@<version>.json` (versioned)
+ */
+declare function loadBrokerGrammar(userAgent: BrokerUserAgent, locale: BrokerLocale, version?: string): McpGrammar | undefined;
+/**
+ * Walks a grammars directory and yields every `(userAgent, locale)` pair
+ * found on disk. The directory must follow the layout
+ * `<dir>/<userAgent>/<locale>.json`.
+ *
+ * Used by the broker server at startup to bulk-register both the packaged
+ * grammars and any local overrides. No hard-coded list of supported
+ * user-agents or locales, adding a new grammar is dropping a JSON file.
+ */
+interface IBrokerGrammarEntry {
+    userAgent: BrokerUserAgent;
+    locale: BrokerLocale;
+    /** Set only for filenames carrying an `@<version>` suffix. */
+    version?: string;
+    /** Composed via {@link brokerGrammarKey} from the three segments above. */
+    key: string;
+    grammar: McpGrammar;
+}
+declare function iterBrokerGrammarsFrom(grammarsDir: string): Generator<IBrokerGrammarEntry>;
+/**
+ * Walks the **packaged** grammars directory (the one shipped with the
+ * mcp-broker package). Equivalent to `iterBrokerGrammarsFrom(<packaged-dir>)`.
+ *
+ * For local user overrides, see {@link iterBrokerGrammarsFrom} with a custom
+ * directory, typically `.mcp-broker/grammars/` next to the config file.
+ */
+declare function iterAvailableBrokerGrammars(): Generator<IBrokerGrammarEntry>;
+/** @deprecated Use {@link IBrokerGrammarEntry}. */
+type BrokerGrammarEntry = IBrokerGrammarEntry;
+
+/**
+ * Common contract for an upstream MCP server bound to a provider slot.
+ *
+ * The broker treats every upstream the same way: it muxes the slot's clients
+ * onto the single upstream connection, regardless of the underlying transport.
+ *
+ * Implementations:
+ * - `StdioUpstream` : a local child process (newline-delimited JSON-RPC over stdio).
+ * - `RemoteUpstream`: a remote MCP server reached by URL (Streamable HTTP / SSE / WebSocket).
+ *
+ * `StdioUpstream` is reused as-is by the future `.mcpb` bundle loader: a bundle
+ * is a local server whose `mcp_config` maps directly onto a stdio upstream.
+ */
+interface IUpstream {
+    /** Provider slot name this upstream is bound to. */
+    readonly name: string;
+    /** Whether the upstream connection is currently usable. */
+    readonly isOpen: boolean;
+    /** Receives one complete JSON-RPC message from the upstream server. */
+    onMessage: ((data: string) => void) | null;
+    /** Fires once the upstream connection is established and ready to send. */
+    onOpen: (() => void) | null;
+    /** Fires when the upstream connection closes. */
+    onClose: (() => void) | null;
+    /** Fires on a connection or runtime error. */
+    onError: ((error: Error) => void) | null;
+    /** Opens the upstream connection. */
+    connect(): void;
+    /** Sends one JSON-RPC message to the upstream server. */
+    send(data: string): void;
+    /** Closes the upstream connection. */
+    close(): void;
+}
+/** @deprecated Use {@link IUpstream}. */
+type Upstream = IUpstream;
+
+interface IStdioUpstreamConfig {
+    /** Logical name of this provider (matched against incoming WebSocket provider names). */
+    name: string;
+    /** Executable to spawn (e.g. `"node"`, `"python"`, an absolute path). */
+    command: string;
+    /** Arguments passed to the command. */
+    args?: string[];
+    /** Extra environment variables merged with `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** When `true`, this upstream joins the `_all` aggregate slot once connected. */
+    aggregate?: boolean;
+}
+/**
+ * Manages a stdio-based MCP server process.
+ * JSON-RPC messages are exchanged over the child process stdin/stdout using
+ * newline-delimited framing (matching the MCP SDK stdio transport).
+ *
+ * One instance per configured provider. The broker uses this to bridge
+ * WebSocket/SSE/HTTP clients to local MCP server processes.
+ */
+declare class StdioUpstream implements IUpstream {
+    readonly name: string;
+    private readonly _config;
+    private _proc;
+    private _buffer;
+    private _open;
+    private _stopped;
+    /** Called when a complete JSON-RPC line arrives from the process stdout. */
+    onMessage: ((data: string) => void) | null;
+    /** Called when the process has started and stdin is writable. */
+    onOpen: (() => void) | null;
+    /** Called when the process exits (cleanly or otherwise). */
+    onClose: (() => void) | null;
+    /** Called on spawn or runtime errors. */
+    onError: ((error: Error) => void) | null;
+    constructor(config: IStdioUpstreamConfig);
+    get isOpen(): boolean;
+    /** Spawns the child process and wires up stdio listeners. */
+    connect(): void;
+    /** Sends a JSON-RPC message to the process stdin (appends newline). */
+    send(data: string): void;
+    /** Kills the child process and prevents further reconnection attempts. */
+    close(): void;
+}
+/** @deprecated Use {@link IStdioUpstreamConfig}. */
+type StdioUpstreamConfig = IStdioUpstreamConfig;
+
+/** The three supported remote transports. */
+type RemoteTransportKind = "streamable-http" | "sse" | "websocket";
+
+interface IRemoteUpstreamConfig {
+    /** Provider slot name this upstream is bound to. */
+    name: string;
+    /** URL of the remote MCP server. */
+    url: string;
+    /** Transport to use. Auto-detected from the URL scheme/path when omitted. */
+    transport?: RemoteTransportKind;
+    /** Extra HTTP / WebSocket headers (e.g. an `Authorization` header). */
+    headers?: Record<string, string>;
+    /** When `true`, this upstream joins the `_all` aggregate slot once connected. */
+    aggregate?: boolean;
+}
+/**
+ * Bridges a remote MCP server (reachable by URL) into a broker provider slot.
+ *
+ * The broker-facing contract is identical to {@link StdioUpstream}: the broker
+ * muxes the slot's clients onto this single upstream. The only difference is
+ * the transport, Streamable HTTP / SSE / WebSocket instead of a child process.
+ */
+declare class RemoteUpstream implements IUpstream {
+    readonly name: string;
+    onMessage: ((data: string) => void) | null;
+    onOpen: (() => void) | null;
+    onClose: (() => void) | null;
+    onError: ((error: Error) => void) | null;
+    private readonly _config;
+    private _transport;
+    private _open;
+    constructor(config: IRemoteUpstreamConfig);
+    get isOpen(): boolean;
+    connect(): void;
+    send(data: string): void;
+    close(): void;
+}
+/** @deprecated Use {@link IRemoteUpstreamConfig}. */
+type RemoteUpstreamConfig = IRemoteUpstreamConfig;
+
+/**
+ * A normalized, case-sensitive hierarchical resource path.
+ *
+ * Parsing is deliberately independent from URLs and transports. A path is a
+ * stable resource identity, not a network address.
+ */
+declare class ResourcePath {
+    readonly value: string;
+    readonly segments: readonly string[];
+    private constructor();
+    static parse(value: string): ResourcePath;
+    static tryParse(value: string): ResourcePath | undefined;
+    toString(): string;
+}
+/**
+ * A compiled resource expression supporting exact segments, `*` for one
+ * segment, and a final `**` for zero or more trailing segments.
+ */
+declare class ResourcePathPattern {
+    readonly value: string;
+    readonly segments: readonly string[];
+    readonly specificity: number;
+    private constructor();
+    static parse(value: string): ResourcePathPattern;
+    matches(path: ResourcePath): boolean;
+    toString(): string;
+}
+
+interface IMcpOperation {
+    readonly method?: string;
+    readonly params?: unknown;
+}
+interface IClassifiedCapability {
+    readonly capability: string;
+    readonly tool?: string;
+}
+interface ICapabilityClassifier {
+    classify(operation: IMcpOperation, resource: ResourcePath, provider?: string): IClassifiedCapability | undefined;
+}
+declare function validateCapability(capability: string, label?: string): void;
+/**
+ * Classifies MCP methods without deriving privilege from arbitrary tool names.
+ * Provider-qualified mappings win over global mappings, then tools/call falls
+ * back to `mcp.tools.call`.
+ */
+declare class ConfiguredCapabilityClassifier implements ICapabilityClassifier {
+    private readonly _globalTools;
+    private readonly _providerMappings;
+    constructor(toolCapabilities?: Readonly<Record<string, string>>, providerToolCapabilities?: Readonly<Record<string, Readonly<Record<string, string>>>>);
+    classify(operation: IMcpOperation, resource: ResourcePath, provider?: string): IClassifiedCapability | undefined;
+}
+/** @deprecated Use {@link IMcpOperation}. */
+type McpOperation = IMcpOperation;
+/** @deprecated Use {@link IClassifiedCapability}. */
+type ClassifiedCapability = IClassifiedCapability;
+/** @deprecated Use {@link ICapabilityClassifier}. */
+type CapabilityClassifier = ICapabilityClassifier;
+
+interface IAuthorizationSubject {
+    readonly ids: readonly string[];
+    readonly claims?: Readonly<Record<string, unknown>>;
+}
+interface IAuthorizationRequest {
+    readonly subject: IAuthorizationSubject;
+    readonly capability: string;
+    readonly resource: ResourcePath;
+    readonly provider?: string;
+    readonly tool?: string;
+}
+type AuthorizationDecisionReason = "explicit-deny" | "role-grant" | "no-matching-grant" | "invalid-resource" | "unknown-resource";
+interface IAuthorizationDecision {
+    readonly allowed: boolean;
+    readonly reason: AuthorizationDecisionReason;
+    readonly matchedPolicies?: readonly string[];
+}
+interface IPolicyEngine {
+    authorize(request: IAuthorizationRequest): IAuthorizationDecision;
+}
+interface IRoleDefinition {
+    readonly inherits?: readonly string[];
+    readonly capabilities: readonly string[];
+}
+interface IPolicyAssignment {
+    readonly id?: string;
+    readonly subject: string;
+    readonly role: string;
+    readonly resource: string;
+}
+interface IDenyPolicy {
+    readonly id?: string;
+    readonly subject: string;
+    readonly effect?: "deny";
+    readonly capabilities: readonly string[];
+    readonly resource: string;
+}
+interface ISubjectMappingConfig {
+    readonly userClaim?: string;
+    readonly groupClaims?: readonly string[];
+    readonly clientClaim?: string;
+    readonly serviceClaims?: readonly string[];
+}
+interface IAuthorizationAuditConfig {
+    readonly logAllowed?: boolean;
+}
+interface IAuthorizationPolicyConfig {
+    readonly roles?: Readonly<Record<string, IRoleDefinition>>;
+    readonly assignments?: readonly IPolicyAssignment[];
+    readonly denies?: readonly IDenyPolicy[];
+    readonly subjectMapping?: ISubjectMappingConfig;
+    readonly slotResources?: Readonly<Record<string, string>>;
+    readonly toolCapabilities?: Readonly<Record<string, string>>;
+    readonly providerToolCapabilities?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    readonly audit?: IAuthorizationAuditConfig;
+}
+interface IAuthorizationAuditEvent {
+    readonly timestamp: string;
+    readonly allowed: boolean;
+    readonly subjectIds: readonly string[];
+    readonly clientId?: string;
+    readonly slot: string;
+    readonly resource?: string;
+    readonly capability?: string;
+    readonly provider?: string;
+    readonly tool?: string;
+    readonly reason: AuthorizationDecisionReason;
+    readonly matchedPolicies?: readonly string[];
+}
+/** @deprecated Use {@link IAuthorizationSubject}. */
+type AuthorizationSubject = IAuthorizationSubject;
+/** @deprecated Use {@link IAuthorizationRequest}. */
+type AuthorizationRequest = IAuthorizationRequest;
+/** @deprecated Use {@link IAuthorizationDecision}. */
+type AuthorizationDecision = IAuthorizationDecision;
+/** @deprecated Use {@link IPolicyEngine}. */
+type PolicyEngine = IPolicyEngine;
+/** @deprecated Use {@link IRoleDefinition}. */
+type RoleDefinition = IRoleDefinition;
+/** @deprecated Use {@link IPolicyAssignment}. */
+type PolicyAssignment = IPolicyAssignment;
+/** @deprecated Use {@link IDenyPolicy}. */
+type DenyPolicy = IDenyPolicy;
+/** @deprecated Use {@link ISubjectMappingConfig}. */
+type SubjectMappingConfig = ISubjectMappingConfig;
+/** @deprecated Use {@link IAuthorizationAuditConfig}. */
+type AuthorizationAuditConfig = IAuthorizationAuditConfig;
+/** @deprecated Use {@link IAuthorizationPolicyConfig}. */
+type AuthorizationPolicyConfig = IAuthorizationPolicyConfig;
+/** @deprecated Use {@link IAuthorizationAuditEvent}. */
+type AuthorizationAuditEvent = IAuthorizationAuditEvent;
+
+/**
+ * Immutable, indexed in-memory policy engine. Role inheritance and resource
+ * expressions are fully compiled in the constructor.
+ */
+declare class ConfigPolicyEngine implements IPolicyEngine {
+    private readonly _assignmentsBySubject;
+    private readonly _deniesBySubject;
+    constructor(roles: Readonly<Record<string, IRoleDefinition>>, assignments: readonly IPolicyAssignment[], denies: readonly IDenyPolicy[]);
+    authorize(request: IAuthorizationRequest): IAuthorizationDecision;
+}
+
+interface ISubjectMapper {
+    map(claims: Readonly<Record<string, unknown>>): IAuthorizationSubject;
+}
+declare class SubjectMappingError extends Error {
+    constructor(message: string);
+}
+/** Maps validated JWT claims to canonical, deduplicated authorization subjects. */
+declare class JwtSubjectMapper implements ISubjectMapper {
+    private readonly _rules;
+    constructor(config?: ISubjectMappingConfig);
+    map(claims: Readonly<Record<string, unknown>>): IAuthorizationSubject;
+}
+/** @deprecated Use {@link ISubjectMapper}. */
+type SubjectMapper = ISubjectMapper;
+
+interface ISlotResourceResolver {
+    resolve(slot: string): ResourcePath | undefined;
+}
+/** Default resolver with optional explicit technical-slot mappings. */
+declare class DefaultSlotResourceResolver implements ISlotResourceResolver {
+    private readonly _explicit;
+    constructor(slotResources?: Readonly<Record<string, string>>);
+    resolve(slot: string): ResourcePath | undefined;
+}
+/** @deprecated Use {@link ISlotResourceResolver}. */
+type SlotResourceResolver = ISlotResourceResolver;
+
+interface IPolicyAuthorization {
+    readonly engine: IPolicyEngine;
+    readonly subjectMapper: ISubjectMapper;
+    readonly slotResourceResolver: ISlotResourceResolver;
+    readonly capabilityClassifier: ICapabilityClassifier;
+    readonly audit: Readonly<Required<IAuthorizationAuditConfig>>;
+}
+declare function hasAuthorizationPolicies(config: IAuthorizationPolicyConfig): boolean;
+/** Compiles and validates the complete hierarchical authorization runtime. */
+declare function compileAuthorizationPolicy(config: IAuthorizationPolicyConfig): IPolicyAuthorization;
+declare function authorizationWithEngine(engine: IPolicyEngine, overrides?: {
+    readonly subjectMapper?: ISubjectMapper;
+    readonly slotResourceResolver?: ISlotResourceResolver;
+    readonly capabilityClassifier?: ICapabilityClassifier;
+    readonly audit?: IAuthorizationAuditConfig;
+}): IPolicyAuthorization;
+/** @deprecated Use {@link IPolicyAuthorization}. */
+type PolicyAuthorization = IPolicyAuthorization;
+
+interface IAuditContext {
+    readonly subject: IAuthorizationSubject;
+    readonly slot: string;
+    readonly resource?: ResourcePath;
+    readonly capability?: string;
+    readonly provider?: string;
+    readonly tool?: string;
+}
+/** @deprecated Use {@link IAuditContext}. */
+type AuditContext = IAuditContext;
+
+/** OAuth 2.1 error codes the broker emits in `WWW-Authenticate` challenges. */
+type AuthErrorCode = _cyanmycelium_mcp_core.McpAuthErrorCode;
+/**
+ * A thrown authorization failure carrying the HTTP status and OAuth error code
+ * the enforcement point should surface. `scope` is set for `insufficient_scope`
+ * challenges to advertise the scope(s) the resource requires.
+ *
+ * The broker's own name for `mcp-core`'s `McpAuthError`, kept so `instanceof`
+ * checks and the published API survive the consolidation. There is one class at
+ * runtime, so an error thrown by `mcp-core` is caught by the broker and the
+ * other way round.
+ */
+declare const AuthError: typeof McpAuthError;
+type AuthError = McpAuthError;
+/**
+ * The authenticated caller, produced once a token passes validation and the
+ * required scopes are satisfied. Threaded through the request so downstream
+ * components (e.g. the `_all` aggregate) can make scope-aware decisions.
+ *
+ * Extends `mcp-core`'s principal with the subject the policy engine reasons
+ * about, which the specification says nothing about and which therefore stays
+ * here.
+ */
+interface IPrincipal extends IMcpPrincipal {
+    readonly claims: IAccessTokenClaims;
+    readonly scopes: ReadonlySet<string>;
+    /** Subjects derived exclusively from validated token claims. */
+    readonly subject?: IAuthorizationSubject;
+}
+/**
+ * Decides, per authenticated caller, whether a given provider is visible in the
+ * `_all` aggregate. This is the content-confidentiality enforcement point: a
+ * client only sees (and can call) tools/prompts from providers it is authorized
+ * for. Return `true` to include the provider for this principal.
+ */
+type AggregateScopeFilter = (principal: IPrincipal, providerName: string) => boolean;
+/**
+ * A fully resolved authorization configuration, ready for the enforcement
+ * layer. Built either from JSON config (via `buildJwtAuth`) or supplied
+ * directly by an embedder with a custom {@link ITokenValidator}.
+ */
+interface IResolvedAuth {
+    /**
+     * Public origin the broker is reached at, used to build canonical resource
+     * URIs and metadata URLs. No trailing slash (e.g. `https://mcp.example.com`).
+     */
+    publicBaseUrl: string;
+    /** One or more authorization server issuer URLs, advertised in the PRM. */
+    authorizationServers: string[];
+    /** Optional list of scopes advertised in the PRM `scopes_supported`. */
+    scopesSupported?: string[];
+    /** The token validator (JWKS-backed by default). */
+    validator: ITokenValidator;
+    /** Baseline scope(s) required to reach any slot. Empty ⇒ any valid token. */
+    requiredScopes?: string[];
+    /** Per-slot required-scope overrides (e.g. an admin scope for `_broker`). */
+    perSlotScopes?: Record<string, string[]>;
+    /**
+     * Per-caller filter for the `_all` aggregate. When set, a client's view of
+     * `_all` is narrowed to the providers this returns `true` for. When absent,
+     * every authenticated caller sees the full aggregate.
+     */
+    aggregateScopeFilter?: AggregateScopeFilter;
+    /** Compiled hierarchical policy runtime, absent for legacy OAuth behavior. */
+    authorization?: IPolicyAuthorization;
+    /** Optional resolver usable for provider namespace checks without policies. */
+    slotResourceResolver?: ISlotResourceResolver;
+}
+/**
+ * Extracts the effective set of granted scopes from token claims.
+ *
+ * A deliberate superset of `mcp-core`'s: OAuth 2.1 only defines the
+ * space-delimited `scope` string, which is what the spec-level helper reads,
+ * but several authorization servers emit an array-form `scopes` claim instead.
+ * Dropping that here would silently strip every scope for those deployments, so
+ * the two are unioned. The `scope` half is parsed by `mcp-core` rather than
+ * re-implemented.
+ */
+declare function scopesOf(claims: IAccessTokenClaims): Set<string>;
+/** @deprecated Use {@link IAccessTokenClaims}. */
+type AccessTokenClaims = IAccessTokenClaims;
+/** @deprecated Use {@link ITokenValidator}. */
+type TokenValidator = ITokenValidator;
+/** @deprecated Use {@link IPrincipal}. */
+type Principal = IPrincipal;
+/** @deprecated Use {@link IResolvedAuth}. */
+type ResolvedAuth = IResolvedAuth;
+
+/**
+ * Options for {@link JwtTokenValidator}. `jwksUri` points at the authorization
+ * server's JWKS endpoint; `issuer` (when set) is checked against the token `iss`.
+ */
+interface IJwtValidatorOptions {
+    /** URL of the authorization server's JWKS document. */
+    jwksUri: string;
+    /** Expected token issuer(s). When omitted, the `iss` claim is not checked. */
+    issuer?: string | string[];
+    /** Leeway in seconds for `exp`/`nbf` checks. Defaults to jose's `0`. */
+    clockToleranceSec?: number;
+}
+/**
+ * An {@link ITokenValidator} that verifies JWT access tokens **statelessly** by
+ * checking the signature against the authorization server's JWKS and validating
+ * the standard claims. This is the default validator for a public deployment:
+ * no per-request round-trip to the AS, no shared introspection secret.
+ *
+ * Audience binding (RFC 8707) is enforced by passing the per-request canonical
+ * resource URI as the required `audience`, so a token minted for another slot ,
+ * or another service, is rejected.
+ *
+ * The JWKS is fetched lazily and cached (with rotation/cooldown) by
+ * `jose.createRemoteJWKSet`.
+ */
+declare class JwtTokenValidator implements ITokenValidator {
+    private readonly _jwks;
+    private readonly _issuer?;
+    private readonly _clockTolerance;
+    constructor(options: IJwtValidatorOptions);
+    validate(token: string, resource: string): Promise<IAccessTokenClaims>;
+}
+/** @deprecated Use {@link IJwtValidatorOptions}. */
+type JwtValidatorOptions = IJwtValidatorOptions;
+
+/**
+ * OAuth 2.0 Protected Resource Metadata (RFC 9728).
+ *
+ * Each slot exposed over HTTP is an independent resource server; its metadata
+ * document tells an MCP client which authorization server(s) issue tokens for
+ * that slot and which bearer methods it accepts. Served (unauthenticated, it is
+ * public discovery data) at
+ * `<publicBaseUrl>/.well-known/oauth-protected-resource/<slot>/<mcp>`.
+ */
+
+/**
+ * Builds the RFC 9728 metadata document for one slot.
+ *
+ * The document itself is shaped by `mcp-core`: it is defined by the MCP
+ * specification, identically for every server. What is broker-specific is only
+ * which resource a slot maps to, and that is decided by the caller.
+ * `bearer_methods_supported` comes out fixed to `["header"]`, matching the
+ * broker's refusal to read a token from anywhere but the header (OAuth 2.1 §5).
+ */
+declare function buildResourceMetadata(params: {
+    resource: string;
+    authorizationServers: string[];
+    scopesSupported?: string[];
+}): IProtectedResourceMetadata;
+/** @deprecated Use {@link IProtectedResourceMetadata}. */
+type ProtectedResourceMetadata = IProtectedResourceMetadata;
+
+/**
+ * The HTTP enforcement point for the resource-server layer. Wraps a
+ * {@link IResolvedAuth} plus the configured `/mcp` path suffix and turns it into
+ * the three operations the transport needs: serve Protected Resource Metadata,
+ * authorize a request, and write an RFC 9728 `401`/`403` challenge.
+ *
+ * A slot's **canonical resource URI** is `<publicBaseUrl>/<slot>/<mcp>` and is
+ * used uniformly across all of that slot's HTTP endpoints (`/mcp`, `/sse`,
+ * `/messages`) so a single token audience covers the whole slot.
+ */
+declare class HttpAuthGuard {
+    private readonly _auth;
+    /** The `/mcp` suffix without a leading slash, e.g. `"mcp"`. */
+    private readonly _mcpSuffix;
+    constructor(auth: IResolvedAuth, mcpSuffix: string);
+    /** Canonical resource identifier for a slot (RFC 8707 §2). */
+    resourceFor(slot: string): string;
+    /** RFC 9728 metadata URL for a slot, advertised in the `401` challenge. */
+    metadataUrlFor(slot: string): string;
+    /** Required scope(s) for a slot: per-slot override, else the baseline. */
+    requiredScopesFor(slot: string): string[];
+    /** The RFC 9728 metadata document for a slot. */
+    metadataFor(slot: string): IProtectedResourceMetadata;
+    /**
+     * If `rawUrl` is a Protected Resource Metadata request
+     * (`/.well-known/oauth-protected-resource/<slot>/<mcp>`), returns the slot;
+     * otherwise `null`.
+     */
+    matchMetadataRequest(rawUrl: string): string | null;
+    /**
+     * 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.
+     */
+    authorize(req: IncomingMessage, slot: string): Promise<IPrincipal>;
+    /**
+     * 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: string, err: AuthError): string;
+    /**
+     * Writes an RFC 9728 §5.1 `WWW-Authenticate` challenge and the matching
+     * status to an HTTP response.
+     */
+    writeChallenge(res: ServerResponse, slot: string, err: AuthError): void;
+}
+
+/**
+ * High-level options for the default JWT/JWKS resource-server setup. Mirrors the
+ * `auth` block of the broker JSON config and is turned into a fully
+ * {@link IResolvedAuth} (with a {@link JwtTokenValidator}) by {@link buildJwtAuth}.
+ */
+interface IJwtAuthOptions extends IAuthorizationPolicyConfig {
+    /** Public origin the broker is reached at (e.g. `https://mcp.example.com`). */
+    publicBaseUrl: string;
+    /** Authorization server issuer URL(s) advertised in the PRM. At least one. */
+    authorizationServers: string[];
+    /** URL of the authorization server's JWKS document. */
+    jwksUri: string;
+    /** Expected token issuer(s). Defaults to the sole authorization server. */
+    issuer?: string | string[];
+    /** Scopes advertised in the PRM `scopes_supported`. */
+    scopesSupported?: string[];
+    /** Baseline scope(s) required to reach any slot. */
+    requiredScopes?: string[];
+    /** Per-slot required-scope overrides (e.g. an admin scope for `_broker`). */
+    perSlotScopes?: Record<string, string[]>;
+    /**
+     * Per-provider scope requirements for the `_all` aggregate. A caller sees a
+     * provider in `_all` only if it holds at least one of the listed scopes.
+     * Providers not listed here stay visible to every authenticated caller.
+     * Turned into an {@link AggregateScopeFilter} automatically.
+     */
+    providerScopes?: Record<string, string[]>;
+    /** Leeway in seconds for token `exp`/`nbf` checks. */
+    clockToleranceSec?: number;
+}
+/**
+ * Builds an {@link IResolvedAuth} backed by a {@link JwtTokenValidator}. Validates
+ * the required inputs up front and throws a descriptive error on misconfig, so
+ * an operator sees the problem at boot rather than as opaque `401`s later.
+ */
+declare function buildJwtAuth(options: IJwtAuthOptions): IResolvedAuth;
+/** @deprecated Use {@link IJwtAuthOptions}. */
+type JwtAuthOptions = IJwtAuthOptions;
+
+interface IProviderPrincipal {
+    readonly id: string;
+    readonly subjects?: readonly string[];
+    readonly allowedResources?: readonly string[];
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+type ProviderAuthenticationResult = {
+    readonly authenticated: true;
+    readonly principal: IProviderPrincipal;
+} | {
+    readonly authenticated: false;
+    readonly reason?: string;
+};
+type ProviderAuthenticatorReturn = boolean | ProviderAuthenticationResult;
+/**
+ * Authenticates a **provider** (the engine that connects _into_ the broker to
+ * serve a slot) at the WebSocket upgrade handshake. This is a distinct concern
+ * from the OAuth 2.1 resource-server layer that guards *clients*: a provider is
+ * not an OAuth client acting for a resource owner, it is the backend claiming a
+ * slot. Authenticating it is what stops a stranger from occupying a free slot
+ * (`ws://host/provider/<slot>`) and impersonating the real engine.
+ */
+interface IProviderAuthenticator {
+    /**
+     * Returns a structured result, or a legacy boolean for backward
+     * compatibility. `slot` is the dedicated slot name for
+     * `/provider/<slot>`, or `undefined` for the multiplexed `/providers`
+     * socket, which is authenticated before any provider name is known.
+     */
+    authenticate(req: IncomingMessage, slot: string | undefined): ProviderAuthenticatorReturn | Promise<ProviderAuthenticatorReturn>;
+}
+declare function normalizeProviderAuthentication(result: ProviderAuthenticatorReturn, fallbackId?: string): ProviderAuthenticationResult;
+declare function providerMayPublish(principal: IProviderPrincipal, resource: ResourcePath): boolean;
+/**
+ * The default {@link IProviderAuthenticator}: every provider connection must
+ * present a single shared secret (via `X-Provider-Token` or `Authorization:
+ * Bearer`). Compared in constant time. Suitable when the broker and its
+ * providers are operated by the same party; swap in a custom authenticator for
+ * per-slot secrets, mTLS, or a signed handshake.
+ */
+declare class SharedSecretProviderAuthenticator implements IProviderAuthenticator {
+    private readonly _secret;
+    constructor(secret: string);
+    authenticate(req: IncomingMessage): ProviderAuthenticationResult;
+}
+/** @deprecated Use {@link IProviderPrincipal}. */
+type ProviderPrincipal = IProviderPrincipal;
+/** @deprecated Use {@link IProviderAuthenticator}. */
+type ProviderAuthenticator = IProviderAuthenticator;
+
+/**
+ * How `/<slot>/mcp` decides whether a browser origin may reach it.
+ *
+ * - a list of origins, matched exactly against the whole `Origin` header
+ * - a `RegExp`, tested against the whole header
+ * - a predicate, when the decision needs more than the string
+ */
+type AllowedOrigins = readonly string[] | RegExp | ((origin: string) => boolean);
+/**
+ * A single static-file mount: serves the contents of `dir` under `urlPrefix`.
+ *
+ * @example
+ * { urlPrefix: "/",       dir: "/absolute/path/to/www" }
+ * { urlPrefix: "/bundle", dir: "/absolute/path/to/bundle" }
+ */
+interface IStaticMount {
+    /** URL prefix that triggers this mount (e.g. `"/"` or `"/bundle"`). */
+    urlPrefix: string;
+    /** Absolute path to the directory to serve. */
+    dir: string;
+}
+/**
+ * In-process client handle for a provider slot: the symmetric counterpart of
+ * {@link WsTunnel.registerLoopbackProvider}. Lets a component inside the broker
+ * process (e.g. the aggregate server) issue MCP requests to a provider slot and
+ * receive both the responses and the provider's broadcast notifications,
+ * without opening a real network connection.
+ */
+interface IInternalClient {
+    /**
+     * Sends a JSON-RPC message to the provider slot. When the message carries an
+     * `id`, the matching response is delivered to {@link onMessage}. When the
+     * provider is not connected, a JSON-RPC error is delivered synchronously.
+     */
+    send(message: string): void;
+    /** Receives responses to this client's requests and the provider's notifications. */
+    onMessage: ((data: string) => void) | null;
+    /** Fires when the provider slot loses its connection. */
+    onClose: (() => void) | null;
+    /** Detaches this internal client; pending requests are dropped. */
+    close(): void;
+}
+/**
+ * Configuration options for a {@link WsTunnel} instance.
+ */
+interface IWsTunnelOptions {
+    /** TCP port to listen on. */
+    port: number;
+    /**
+     * Host/interface to bind to.
+     * @default "0.0.0.0"
+     */
+    host?: string;
+    /**
+     * URL path **prefix** the MCP provider connects to via WebSocket.
+     * Each provider appends its name: `<providerPath>/<encodedName>`.
+     * @default "/provider"
+     */
+    providerPath?: string;
+    /**
+     * URL path for **multiplexed** provider connections.
+     * A single WebSocket carries traffic for multiple providers using the
+     * envelope protocol `{ provider: string, payload: object }`.
+     * @default "/providers"
+     */
+    providersPath?: string;
+    /**
+     * URL path raw WebSocket MCP clients connect to.
+     * @default "/"
+     */
+    clientPath?: string;
+    /**
+     * **Suffix** appended to a provider name for the SSE endpoint.
+     * Full URL: `/<providerName>/sse`
+     * @default "/sse"
+     */
+    ssePath?: string;
+    /**
+     * **Suffix** appended to a provider name for the legacy SSE POST endpoint.
+     * Full URL: `/<providerName>/messages`
+     * @default "/messages"
+     */
+    messagesPath?: string;
+    /**
+     * **Suffix** appended to a provider name for the Streamable HTTP endpoint (MCP 2025-03-26).
+     * Full URL: `/<providerName>/mcp`
+     * MCP Inspector connects here.
+     * @default "/mcp"
+     */
+    mcpPath?: string;
+    /**
+     * URL path that returns a `{ files: string[] }` JSON listing of every file
+     * inside the `samples/` subdirectory of the root static mount.
+     * @default "/__samples_index__"
+     */
+    samplesIndexPath?: string;
+    /**
+     * Browser origins allowed to reach `/<slot>/mcp`.
+     *
+     * The MCP specification requires the `Origin` header to be validated,
+     * because without it any web page the operator's browser happens to load
+     * can drive a broker that machine can reach. A request carrying **no**
+     * `Origin` is always allowed: that covers every non-browser client, which
+     * is what Claude Desktop, MCP Inspector and the server-side SDKs are.
+     *
+     * Omit this and every browser origin is refused with `403`. The default is
+     * deliberately closed; opening it is an operator decision.
+     *
+     * @default undefined, no browser origin is allowed
+     */
+    allowedOrigins?: AllowedOrigins;
+    /**
+     * Optional static-file mounts served over plain HTTP.
+     * Matched by longest URL prefix; directory requests fall back to `index.html`.
+     */
+    staticMounts?: IStaticMount[];
+    /**
+     * Stdio upstream providers. Each entry spawns a child process and wires its
+     * stdin/stdout as an MCP transport. Clients reach the process using its `name`
+     * directly.
+     *
+     * If a WebSocket provider connects with the same name as a stdio upstream, the
+     * connection is rejected and a warning is logged, stdio takes priority.
+     * @default undefined: no stdio providers
+     */
+    stdioUpstreams?: IStdioUpstreamConfig[];
+    /** Remote MCP servers reached by URL, exposed as provider slots. */
+    remoteUpstreams?: IRemoteUpstreamConfig[];
+    /**
+     * Stdio client transport. When set, the broker reads JSON-RPC from
+     * `process.stdin` and writes responses to `process.stdout`, bridging an
+     * external MCP client (e.g. Claude Desktop) to the named provider.
+     *
+     * In this mode ALL logging is redirected to stderr so stdout stays clean
+     * for the JSON-RPC stream.
+     *
+     * Claude Desktop config example:
+     * ```json
+     * {
+     *   "command": "npx",
+     *   "args": ["-y", "@cyanmycelium/mcp-broker"],
+     *   "env": { "MCP_BROKER_STDIO_PROVIDER": "my-provider" }
+     * }
+     * ```
+     * @default undefined, stdio client transport disabled
+     */
+    stdioClient?: {
+        providerName: string;
+    };
+    /**
+     * TLS configuration. When provided, the server uses HTTPS and WSS instead of HTTP and WS.
+     * Both `cert` and `key` must be PEM-encoded strings (file contents, not file paths).
+     * Use {@link WsTunnelBuilder.withTlsFiles} to load from disk paths.
+     * @default undefined, plain HTTP/WS
+     */
+    tls?: {
+        /** PEM-encoded TLS certificate. */
+        cert: string;
+        /** PEM-encoded private key. */
+        key: string;
+    };
+    /**
+     * When `true` (default), the broker exposes itself as an MCP server under the
+     * reserved slot `_broker`. Tier-1 behaviors (`broker_info`, `providers_list`,
+     * `provider_status`) become callable at `<host>/_broker/mcp`.
+     *
+     * Set to `false` to keep the broker invisible to MCP clients.
+     * @default true
+     */
+    enableBrokerProvider?: boolean;
+    /**
+     * When `true` (default), the broker exposes the reserved slot `_all`: an
+     * aggregate MCP server that unions the tools and prompts of every provider
+     * that opted in via the registration handshake. Reachable like any other
+     * slot (`<host>/_all/mcp`, etc.).
+     *
+     * Set to `false` to disable aggregation entirely.
+     * @default true
+     */
+    enableAggregateProvider?: boolean;
+    /**
+     * Logical name reported by `broker_info`. Useful when running multiple
+     * broker instances and you want to tell them apart from the agent side
+     * (e.g. `"broker-eu-west"`).
+     * @default PACKAGE_NAME, `@cyanmycelium/mcp-broker`
+     */
+    brokerName?: string;
+    /**
+     * Overrides for the embedded broker server's grammar resolver, passed
+     * straight through to `mcp-core`'s `grammarResolverFromOptions`. The
+     * broker installs its own default `localeSource` (reads
+     * `process.env.MCP_BROKER_LOCALE`); anything you set here wins.
+     *
+     * Use this to inject a custom `localeSource` (e.g. read from an HTTP
+     * header proxied by your transport), enable the optional `versionFrom`
+     * dimension, or extend the `agents` map with additional LLM families.
+     */
+    brokerGrammarResolverOptions?: Partial<GrammarResolverOptions>;
+    /**
+     * Path to a user-supplied grammars directory whose `<userAgent>/<locale>.json`
+     * files are registered alongside the packaged grammars used by the
+     * embedded broker server. Typically pointed at `.mcp-broker/grammars/`.
+     *
+     * The candidate-chain resolution in `McpServer.initialize`
+     * (mcp-core@0.3.0) handles cascade across user-agent and locale
+     * dimensions, so partial files no longer need to be pre-merged with a
+     * baseline.
+     */
+    brokerLocalGrammarsDir?: string;
+    /**
+     * OAuth 2.1 resource-server authorization. When set, every HTTP client
+     * request to a slot (`/<slot>/mcp`, `/<slot>/sse`, `/<slot>/messages`) must
+     * carry a valid `Authorization: Bearer` token issued for that slot, and the
+     * broker publishes Protected Resource Metadata (RFC 9728) under
+     * `/.well-known/oauth-protected-resource/<slot>/<mcp>`.
+     *
+     * When `undefined` (default), the broker performs **no** authentication ,
+     * appropriate only behind a trusted network boundary.
+     */
+    auth?: IResolvedAuth;
+    /**
+     * Authenticates **providers** (engines) connecting to `/provider/<slot>` and
+     * the multiplexed `/providers` socket. Independent of {@link auth} (which
+     * guards clients): set this to stop strangers from occupying a free slot and
+     * impersonating the real engine.
+     *
+     * When `undefined` (default), provider connections are **not** authenticated.
+     */
+    providerAuth?: IProviderAuthenticator;
+    /** Hierarchical policy runtime. Absent preserves legacy OAuth behavior. */
+    authorization?: IPolicyAuthorization;
+    /** Slot-to-resource resolver also used for provider namespace restrictions. */
+    slotResourceResolver?: ISlotResourceResolver;
+}
+/** @deprecated Use {@link IStaticMount}. */
+type StaticMount = IStaticMount;
+/** @deprecated Use {@link IInternalClient}. */
+type InternalClient = IInternalClient;
+/** @deprecated Use {@link IWsTunnelOptions}. */
+type WsTunnelOptions = IWsTunnelOptions;
+
+/**
+ * A multi-provider relay that bridges any number of MCP server instances
+ * (the **providers**) with their respective MCP clients.
+ *
+ * ## Transport overview
+ * ```
+ * Provider "<name>"
+ *   ws://host/provider/<name>           ← WebSocket registration
+ *
+ * MCP Inspector (Streamable HTTP, 2025-03-26)
+ *   GET  http://host/<name>/mcp         ← persistent SSE notification stream
+ *   POST http://host/<name>/mcp         → JSON-RPC requests
+ *
+ * Claude (legacy SSE transport)
+ *   GET  http://host/<name>/sse              ← SSE notification stream
+ *   POST http://host/<name>/messages         → JSON-RPC requests
+ * ```
+ *
+ * Each provider gets its own isolated set of sessions, pending requests, and
+ * notification streams. Multiple providers can be connected simultaneously.
+ */
+declare class WsTunnel implements IBrokerContext {
+    private readonly _options;
+    private _httpServer;
+    private _wss;
+    /**
+     * 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.
+     */
+    private readonly _providers;
+    /** Maps a multiplexed WebSocket to the set of provider names it feeds. */
+    private readonly _multiplexSockets;
+    /** Upstream providers (stdio child processes and remote URL servers), keyed by name. */
+    private readonly _upstreams;
+    /**
+     * 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.
+     */
+    private readonly _loopbackProviders;
+    /** The embedded broker MCP server, when {@link IWsTunnelOptions.enableBrokerProvider} is on. */
+    private _brokerServer;
+    /** The aggregate MCP server (`_all` slot), when {@link IWsTunnelOptions.enableAggregateProvider} is on. */
+    private _aggregateServer;
+    /** Provider name that the stdio client transport is bridged to, or null when disabled. */
+    private _stdioClientProvider;
+    /** mcp-core transport connected to the broker process stdin/stdout. */
+    private _stdioClientTransport;
+    /** Timestamp of the most recent successful `start()`. */
+    private _startedAt;
+    /** HTTP resource-server enforcement point, or `null` when auth is disabled. */
+    private readonly _authGuard;
+    /** Provider (engine) authenticator, or `null` when provider auth is disabled. */
+    private readonly _providerAuth;
+    /** Compiled hierarchical authorization, or `null` for legacy behavior. */
+    private readonly _authorization;
+    /** Stable technical-slot to hierarchical-resource mapping. */
+    private readonly _slotResourceResolver;
+    /** Origin check applied by every slot's Streamable HTTP endpoint. */
+    private readonly _allowedOrigins;
+    /** Principal captured at a client's WS upgrade, keyed by the upgrade request. */
+    private readonly _pendingClientPrincipals;
+    /** Authenticated principal per raw WS client socket, for `_all` scope filtering. */
+    private readonly _clientPrincipals;
+    /** Authenticated principal attached to long-lived HTTP/SSE streams. */
+    private readonly _streamPrincipals;
+    /** Provider principals captured during successful WebSocket upgrades. */
+    private readonly _pendingProviderPrincipals;
+    private readonly _providerPrincipals;
+    constructor(options: IWsTunnelOptions);
+    get version(): string;
+    get name(): string;
+    get startedAt(): Date | null;
+    get uptimeSeconds(): number;
+    get host(): string | undefined;
+    get port(): number;
+    get tls(): boolean;
+    get paths(): IBrokerContext["paths"];
+    getProvidersInfo(): IBrokerProviderInfo[];
+    getProviderInfo(name: string): IBrokerProviderInfo | undefined;
+    private _buildProviderInfo;
+    /**
+     * 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: string, transport: IMessageTransport): void;
+    /**
+     * 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: string): IInternalClient;
+    get isListening(): boolean;
+    /** Total number of connected MCP clients across all providers. */
+    get clientCount(): number;
+    /** Names of all providers that currently have an active connection. */
+    get providerNames(): readonly string[];
+    /** @deprecated Check `providerNames.length > 0` instead. */
+    get hasProvider(): boolean;
+    /**
+     * Starts the broker. Resolves once the HTTP server is listening.
+     */
+    start(): Promise<void>;
+    /**
+     * 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`.
+     */
+    private _maybeStartBrokerServer;
+    /**
+     * Starts the aggregate MCP server and registers it on the reserved `_all`
+     * slot. No-op when {@link IWsTunnelOptions.enableAggregateProvider} is `false`.
+     */
+    private _maybeStartAggregateServer;
+    /**
+     * Gracefully closes all connections and stops the HTTP server.
+     */
+    stop(): Promise<void>;
+    private _authorizationSubject;
+    private _auditDecision;
+    /**
+     * Applies hierarchical policy to the MCP operations carried in one
+     * JSON-RPC frame. `_all` performs provider-specific checks internally.
+     */
+    private _authorizeMcpFrame;
+    private _policyDeniedPayload;
+    /** The JSON-RPC error returned when the slot has nobody behind it. */
+    private _notConnectedPayload;
+    private _handleHttp;
+    /**
+     * Parses `/<providerName>/<endpoint>` from a URL path.
+     * Returns `null` if the URL does not match this two-segment pattern.
+     */
+    private _parseProviderRoute;
+    /**
+     * Classifies a `(endpoint, method)` pair as one of the four MCP/SSE client
+     * handlers, or `null` when it is not a client transport request (the caller
+     * then falls through to static-file serving, preserving prior behavior).
+     */
+    private _mcpEndpointKind;
+    /** Routes an already-authorized (or auth-disabled) request to its handler. */
+    private _dispatchMcpEndpoint;
+    /** Turns a rejected {@link HttpAuthGuard.authorize} into an HTTP response. */
+    private _handleAuthFailure;
+    /**
+     * Builds the `ws` verifyClient hook that authenticates every WebSocket
+     * upgrade before the connection is accepted, returning a real `401`/`403`
+     * during the handshake rather than a post-handshake close:
+     *
+     * - **Raw MCP clients** (`/<slot>`) are gated by the OAuth 2.1 resource
+     *   server ({@link _authGuard}) with the RFC 9728 `WWW-Authenticate` challenge.
+     * - **Providers** (`/provider/<slot>`, `/providers`) are gated by the
+     *   {@link _providerAuth} shared-secret / custom authenticator.
+     *
+     * Each side is independent: a branch with no authenticator configured is let
+     * through unchanged. Returns `undefined` (no hook) when neither is set.
+     */
+    private _makeVerifyClient;
+    /**
+     * Handles `GET /<providerName>/sse`, opens a long-lived SSE stream for Claude.
+     * Sends an `endpoint` event so Claude knows where to POST its requests.
+     */
+    private _handleSseConnect;
+    /**
+     * Handles `POST /<providerName>/messages?sessionId=…`, receives a JSON-RPC
+     * request from Claude and forwards it to the provider.
+     * Always responds 202 Accepted; the real response arrives over SSE.
+     */
+    private _handleSseMessage;
+    /**
+     * Serves `/<providerName>/mcp` by handing the request to the slot's
+     * Streamable HTTP endpoint.
+     *
+     * Everything protocol-shaped, sessions, `Mcp-Session-Id`, `DELETE`, the
+     * `404` on a terminated session, `Origin` and `MCP-Protocol-Version`
+     * validation, `202` on a notification, belongs to `mcp-core` and is no
+     * longer reimplemented here. What stays is the broker's own business:
+     * deciding who may speak (already done upstream by the auth guard) and
+     * relaying frames to a provider that lives somewhere else entirely.
+     */
+    private _handleStreamableHttp;
+    /**
+     * The slot's Streamable HTTP endpoint, built on first use.
+     *
+     * Its factory does not create an MCP server: the server is the provider,
+     * reachable only through the tunnel. It creates a bridge instead: frames the
+     * client sends go out to the provider, and frames coming back are addressed
+     * to this session by id.
+     */
+    private _endpointFor;
+    /** Relays one frame from an HTTP session to the provider behind the slot. */
+    private _fromHttpSession;
+    /** Writes one JSON-RPC message as an SSE `message` event. */
+    private _sendSseEvent;
+    private _logProviderRegistration;
+    private _onProviderConnect;
+    /**
+     * 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.
+     */
+    private _tryHandleRegistration;
+    private _onClientConnect;
+    /**
+     * 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.
+     */
+    private _onMultiplexProviderConnect;
+    /**
+     * Sends a raw JSON-RPC message to a provider, wrapping it in a multiplex
+     * envelope when the provider's WebSocket is a multiplexed connection.
+     */
+    private _sendToProvider;
+    private _routeFromStdioClient;
+    private _routeFromClient;
+    private _routeFromProvider;
+    /** Sends a message to all clients connected to one provider. */
+    private _broadcast;
+    /**
+     * 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).
+     */
+    private _failProviderDisconnected;
+    /**
+     * Returns `true` if the provider is reachable, via a WebSocket connection,
+     * a stdio upstream, or an in-process loopback transport.
+     */
+    private _isProviderConnected;
+    /** Returns the state for `name`, creating it lazily if it doesn't exist yet. */
+    private _getOrCreateProviderState;
+    private _handleSamplesIndex;
+    private _serveStatic;
+}
+
+/**
+ * Fluent builder that constructs a configured {@link WsTunnel}.
+ *
+ * @example
+ * ```typescript
+ * const tunnel = new WsTunnelBuilder()
+ *     .withPort(3000)
+ *     .withHost("localhost")
+ *     .withStaticMount("/", "/abs/path/to/www")
+ *     .build();
+ *
+ * await tunnel.start();
+ * console.log("Broker listening on ws://localhost:3000");
+ * console.log("  Provider connects to: ws://localhost:3000/provider/<name>");
+ * console.log("  Clients  connect to:  ws://localhost:3000/<name>");
+ * ```
+ */
+declare class WsTunnelBuilder {
+    private _port;
+    private _host;
+    private _providerPath;
+    private _providersPath;
+    private _clientPath;
+    private _ssePath;
+    private _messagesPath;
+    private _mcpPath;
+    private _samplesIndexPath;
+    private _allowedOrigins;
+    private _staticMounts;
+    private _stdioUpstreams;
+    private _remoteUpstreams;
+    private _stdioClient;
+    private _tls;
+    private _brokerLocalGrammarsDir;
+    private _auth;
+    private _providerAuth;
+    private _authorization;
+    private _slotResourceResolver;
+    /** Sets the TCP port the broker listens on. */
+    withPort(port: number): this;
+    /**
+     * Sets the host/interface to bind to.
+     * @default "0.0.0.0" (all interfaces)
+     */
+    withHost(host: string): this;
+    /**
+     * Sets the URL path the MCP provider connects to.
+     * @default "/provider"
+     */
+    withProviderPath(path: string): this;
+    /**
+     * Sets the URL path for multiplexed provider connections.
+     * Multiple providers share a single WebSocket using the envelope protocol.
+     * @default "/providers"
+     */
+    withProvidersPath(path: string): this;
+    /**
+     * Sets the URL path MCP clients connect to.
+     * @default "/"
+     */
+    withClientPath(path: string): this;
+    /**
+     * Sets the URL path for the SSE stream (legacy Claude transport, GET).
+     * @default "/sse"
+     */
+    withSsePath(path: string): this;
+    /**
+     * Sets the URL path for JSON-RPC POST requests (legacy Claude transport).
+     * @default "/messages"
+     */
+    withMessagesPath(path: string): 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: string): 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: string): 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: AllowedOrigins): 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: string, dir: string): 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: IStdioUpstreamConfig): 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: IRemoteUpstreamConfig): 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: string): 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: string, key: string): 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: string, keyPath: string): this;
+    /**
+     * 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: string): 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: IResolvedAuth): 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: IJwtAuthOptions): this;
+    /** Installs a custom policy engine behind the broker's transport-neutral API. */
+    withPolicyEngine(engine: IPolicyEngine): this;
+    /** Compiles and validates roles, assignments, denies, mappings, and paths. */
+    withAuthorizationPolicy(config: IAuthorizationPolicyConfig): this;
+    /** Overrides the technical slot to hierarchical resource resolution strategy. */
+    withSlotResourceResolver(resolver: ISlotResourceResolver): this;
+    /**
+     * Authenticates providers (engines) with a custom {@link IProviderAuthenticator}.
+     * Prefer {@link withProviderSecret} for the standard shared-secret setup.
+     */
+    withProviderAuth(authenticator: IProviderAuthenticator): 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: string): this;
+    /** Constructs and returns a configured {@link WsTunnel}. */
+    build(): WsTunnel;
+}
+
+/** A `.mcpb` bundle entry from the broker config file. */
+interface IMcpbBundleConfig {
+    /** Provider slot name the bundle is bound to. */
+    name: string;
+    /** Path to the `.mcpb` file. */
+    path: string;
+    /** Path to the trusted public key (PEM) verifying the detached signature. */
+    publicKey: string;
+    /** Path to the detached signature file. Defaults to `<path>.sig`. */
+    signature?: string;
+    /** Values substituted into the manifest's `${user_config.*}` placeholders. */
+    userConfig?: Record<string, string | number | boolean | Array<string | number>>;
+    /** When `false`, the bundle stays out of the `_all` aggregate slot. Defaults to `true`. */
+    aggregate?: boolean;
+}
+/**
+ * Verifies, unpacks and resolves a `.mcpb` bundle into an `IStdioUpstreamConfig`.
+ *
+ * @param cfg      The bundle entry from the broker config.
+ * @param baseDir  Directory the bundle paths are resolved against.
+ * @returns        A ready upstream config, or `null` when the bundle is refused.
+ */
+declare function loadMcpbBundle(cfg: IMcpbBundleConfig, baseDir: string): Promise<IStdioUpstreamConfig | null>;
+/** @deprecated Use {@link IMcpbBundleConfig}. */
+type McpbBundleConfig = IMcpbBundleConfig;
+
+/**
+ * Extracts every entry of the `.mcpb` archive at `mcpbPath` into `destDir`.
+ * `destDir` is created if missing. Entries whose resolved path would escape
+ * `destDir` (zip-slip) are rejected.
+ */
+declare function unzipMcpb(mcpbPath: string, destDir: string): void;
+
+declare const VERSION: string;
+declare const PACKAGE_NAME: string;
+
+interface IBrokerAuthConfig extends IAuthorizationPolicyConfig {
+    /** Master switch. Absent/`false` keeps the broker unauthenticated. */
+    enabled?: boolean;
+    /** Public origin the broker is reached at (e.g. `https://mcp.example.com`). */
+    publicBaseUrl?: string;
+    /** Authorization server issuer URL(s) advertised in the metadata. */
+    authorizationServers?: string[];
+    /** URL of the authorization server's JWKS document. */
+    jwks?: string;
+    /** Expected token issuer. Defaults to the sole `authorizationServers` entry. */
+    issuer?: string;
+    /** Scopes advertised in the metadata `scopes_supported`. */
+    scopesSupported?: string[];
+    /** Baseline scope(s) required to reach any slot. */
+    requiredScopes?: string[];
+    /** Per-slot required-scope overrides (e.g. an admin scope for `_broker`). */
+    perSlotScopes?: Record<string, string[]>;
+    /**
+     * Per-provider scope requirements for the `_all` aggregate. Deprecated in
+     * favor of hierarchical policy assignments.
+     */
+    providerScopes?: Record<string, string[]>;
+    /**
+     * Shared secret every provider must present to occupy a slot. Independent
+     * of client authorization.
+     */
+    providerSecret?: string;
+}
+/**
+ * Shape of the optional JSON config file consumed by `bin.ts` at startup.
+ * Every field is optional. Environment variables (`MCP_BROKER_*`) always win
+ * over file values, and file values win over the built-in defaults.
+ *
+ * @example
+ * ```json
+ * {
+ *     "port": 3001,
+ *     "locale": "fr",
+ *     "tls": { "cert": "certs/cert.pem", "key": "certs/key.pem" },
+ *     "stdioUpstreams": [
+ *         { "name": "fs", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/data"] }
+ *     ]
+ * }
+ * ```
+ */
+interface IBrokerConfig {
+    /** TCP port. Maps to `MCP_BROKER_PORT`. */
+    port?: number;
+    /** Bind host. Maps to `MCP_BROKER_HOST`. */
+    host?: string;
+    /** Force protocol (`http`/`https`) regardless of cert presence. Maps to `MCP_BROKER_PROTOCOL`. */
+    protocol?: "http" | "https";
+    /** Locale fed to the broker grammar resolver. Maps to `MCP_BROKER_LOCALE`. */
+    locale?: string;
+    /** Bridge stdin/stdout for a Claude-Desktop-style client. Maps to `MCP_BROKER_STDIO_PROVIDER`. */
+    stdioProvider?: string;
+    /** Logical broker name reported by `broker_info`. */
+    brokerName?: string;
+    /**
+     * Browser origins allowed to reach `/<slot>/mcp`.
+     *
+     * Absent means no browser origin is accepted: a request carrying an
+     * `Origin` header gets `403`, one carrying none (Claude Desktop, MCP
+     * Inspector, any server-side SDK) always passes. The MCP specification asks
+     * for this check, since without it any web page loaded in a browser that
+     * can reach the broker could drive it.
+     *
+     * An array lists origins matched **exactly**. An object supplies a regular
+     * expression tested against the whole `Origin` header. Also maps to
+     * `MCP_BROKER_ALLOWED_ORIGINS` (comma-separated list form only; a pattern
+     * needs the config file).
+     *
+     * @example
+     * ```json
+     * { "allowedOrigins": ["https://app.example.com", "http://localhost:5173"] }
+     * { "allowedOrigins": { "pattern": "^https://[a-z0-9-]+\\.example\\.com$" } }
+     * ```
+     */
+    allowedOrigins?: string[] | {
+        pattern: string;
+        flags?: string;
+    };
+    /**
+     * OAuth 2.1 resource-server authorization. When `enabled` is `true`, every
+     * HTTP client request to a slot must carry a valid `Authorization: Bearer`
+     * token issued for that slot, and the broker publishes Protected Resource
+     * Metadata (RFC 9728). Absent/`false` ⇒ no authentication (trusted-network
+     * mode, the historical behavior).
+     *
+     * Scalars also map to env vars (which win): `MCP_BROKER_AUTH_ENABLED`,
+     * `MCP_BROKER_PUBLIC_BASE_URL`, `MCP_BROKER_JWKS`, `MCP_BROKER_ISSUER`.
+     */
+    auth?: IBrokerAuthConfig;
+    /** URL paths (override the defaults). */
+    paths?: {
+        provider?: string;
+        providers?: string;
+        client?: string;
+        mcp?: string;
+        sse?: string;
+        messages?: string;
+    };
+    /** TLS material as paths on disk. Resolved against the config file's directory. */
+    tls?: {
+        cert: string;
+        key: string;
+    };
+    /**
+     * Static-file serving alongside the JSON-RPC endpoints. JSON-RPC routes
+     * always take precedence.
+     */
+    www?: {
+        /** Auto-launch the default browser at the root URL on startup. */
+        open?: boolean;
+        /** URL-prefix → directory mappings. Longest-prefix match wins. */
+        mounts?: Array<{
+            urlPrefix: string;
+            dir: string;
+        }>;
+    };
+    /** Stdio upstream providers spawned by the broker at startup. */
+    stdioUpstreams?: Array<{
+        name: string;
+        command: string;
+        args?: string[];
+        env?: Record<string, string>;
+        /** When `true`, the upstream joins the `_all` aggregate slot once connected. */
+        aggregate?: boolean;
+    }>;
+    /**
+     * Remote MCP servers the broker connects out to and exposes as provider
+     * slots. Each entry is reached by URL (Streamable HTTP / SSE / WebSocket);
+     * local servers should be shipped as `.mcpb` bundles instead.
+     */
+    mcpServers?: Array<{
+        name: string;
+        url: string;
+        transport?: "streamable-http" | "sse" | "websocket";
+        headers?: Record<string, string>;
+        /** Defaults to `true`; set to `false` to exclude this upstream from the `_all` aggregate slot. */
+        aggregate?: boolean;
+    }>;
+    /**
+     * Local `.mcpb` bundles the broker loads at startup and runs as stdio
+     * provider slots. A bundle is a ZIP with a `manifest.json`; the broker
+     * verifies a detached signature against a trusted public key before
+     * unpacking and spawning it.
+     */
+    mcpbBundles?: Array<{
+        /** Provider slot name the bundle is bound to. */
+        name: string;
+        /** Path to the `.mcpb` file (resolved against the config file's directory). */
+        path: string;
+        /** Path to the trusted public key (PEM) used to verify the detached signature. */
+        publicKey: string;
+        /** Path to the detached signature file. Defaults to `<path>.sig`. */
+        signature?: string;
+        /** Values substituted into the manifest's `${user_config.*}` placeholders. */
+        userConfig?: Record<string, string | number | boolean | Array<string | number>>;
+        /** Defaults to `true`; set to `false` to exclude this bundle from the `_all` aggregate slot. */
+        aggregate?: boolean;
+    }>;
+}
+/**
+ * Returned by {@link loadBrokerConfig}. The {@link config} is the parsed JSON;
+ * {@link baseDir} is the directory used to resolve relative paths inside it
+ * (the directory containing the config file when one was found, otherwise
+ * `process.cwd()`).
+ */
+interface ILoadedBrokerConfig {
+    config: IBrokerConfig;
+    baseDir: string;
+    /** Absolute path of the config file that was loaded, or `null` if none. */
+    sourcePath: string | null;
+}
+/** Default config filename inside {@link DEFAULT_CONFIG_DIR}. */
+declare const DEFAULT_CONFIG_FILENAME = "config.json";
+/**
+ * Loads the broker config from a JSON file.
+ *
+ * Discovery order:
+ * 1. The `path` argument when provided (explicit override).
+ * 2. The `MCP_BROKER_CONFIG` env var.
+ * 3. `./.mcp-broker/config.json` relative to `process.cwd()`.
+ * 4. `./mcp-broker.config.json` relative to `process.cwd()` (legacy layout ,
+ *    a deprecation warning is written to stderr).
+ *
+ * When no file is found, returns the built-in empty config with
+ * `baseDir = process.cwd()`. On invalid JSON, logs a warning to stderr and
+ * returns the same empty config, never throws.
+ *
+ * Paths inside the config file are intended to be resolved against
+ * {@link ILoadedBrokerConfig.baseDir} by the consumer.
+ */
+declare function loadBrokerConfig(path?: string): ILoadedBrokerConfig;
+/** @deprecated Use {@link IBrokerAuthConfig}. */
+type BrokerAuthConfig = IBrokerAuthConfig;
+/** @deprecated Use {@link IBrokerConfig}. */
+type BrokerConfig = IBrokerConfig;
+/** @deprecated Use {@link ILoadedBrokerConfig}. */
+type LoadedBrokerConfig = ILoadedBrokerConfig;
+
+export { type AccessTokenClaims, type AggregateScopeFilter, type AllowedOrigins, type AuditContext, AuthError, type AuthErrorCode, type AuthorizationAuditConfig, type AuthorizationAuditEvent, type AuthorizationDecision, type AuthorizationDecisionReason, type AuthorizationPolicyConfig, type AuthorizationRequest, type AuthorizationSubject, BROKER_PROVIDER_NAME, type BrokerAuthConfig, type BrokerConfig, type BrokerContext, type BrokerGrammarEntry, BrokerInfoBehavior, type BrokerLocale, type BrokerProviderInfo, type BrokerProviderTransport, BrokerProvidersBehavior, type BrokerUserAgent, type CapabilityClassifier, type ClassifiedCapability, ConfigPolicyEngine, ConfiguredCapabilityClassifier, DEFAULT_CONFIG_FILENAME, DefaultSlotResourceResolver, type DenyPolicy, HttpAuthGuard, type IAuditContext, type IAuthorizationAuditConfig, type IAuthorizationAuditEvent, type IAuthorizationDecision, type IAuthorizationPolicyConfig, type IAuthorizationRequest, type IAuthorizationSubject, type IBrokerAuthConfig, type IBrokerConfig, type IBrokerContext, type IBrokerGrammarEntry, type IBrokerProviderInfo, type ICapabilityClassifier, type IClassifiedCapability, type IDenyPolicy, type IInternalClient, type IJwtAuthOptions, type IJwtValidatorOptions, type ILoadedBrokerConfig, type IMcpOperation, type IMcpbBundleConfig, type IPolicyAssignment, type IPolicyAuthorization, type IPolicyEngine, type IPrincipal, type IProviderAuthenticator, type IProviderPrincipal, type IRemoteUpstreamConfig, type IResolvedAuth, type IRoleDefinition, type ISlotResourceResolver, type IStartBrokerServerOptions, type IStaticMount, type IStdioUpstreamConfig, type ISubjectMapper, type ISubjectMappingConfig, type IUpstream, type IWsTunnelOptions, type InternalClient, type JwtAuthOptions, JwtSubjectMapper, JwtTokenValidator, type JwtValidatorOptions, type LoadedBrokerConfig, type McpOperation, type McpbBundleConfig, PACKAGE_NAME, type PolicyAssignment, type PolicyAuthorization, type PolicyEngine, type Principal, type ProtectedResourceMetadata, type ProviderAuthenticationResult, type ProviderAuthenticator, type ProviderAuthenticatorReturn, type ProviderPrincipal, RemoteUpstream, type RemoteUpstreamConfig, type ResolvedAuth, ResourcePath, ResourcePathPattern, type RoleDefinition, SharedSecretProviderAuthenticator, type SlotResourceResolver, type StartBrokerServerOptions, type StaticMount, StdioUpstream, type StdioUpstreamConfig, type SubjectMapper, type SubjectMappingConfig, SubjectMappingError, type TokenValidator, type Upstream, VERSION, WsTunnel, WsTunnelBuilder, type WsTunnelOptions, authorizationWithEngine, brokerGrammarKey, buildJwtAuth, buildResourceMetadata, compileAuthorizationPolicy, hasAuthorizationPolicies, iterAvailableBrokerGrammars, iterBrokerGrammarsFrom, loadBrokerConfig, loadBrokerGrammar, loadMcpbBundle, normalizeProviderAuthentication, providerMayPublish, scopesOf, startBrokerServer, unzipMcpb, validateCapability };