@cyanmycelium/mcp-broker 0.4.0 → 1.2.0

package/src/authorization/policy.types.ts

@@ -0,0 +1,105 @@
+import type { ResourcePath } from "./resource.path";
+
+export interface IAuthorizationSubject {
+    readonly ids: readonly string[];
+    readonly claims?: Readonly<Record<string, unknown>>;
+}
+
+export interface IAuthorizationRequest {
+    readonly subject: IAuthorizationSubject;
+    readonly capability: string;
+    readonly resource: ResourcePath;
+    readonly provider?: string;
+    readonly tool?: string;
+}
+
+export type AuthorizationDecisionReason = "explicit-deny" | "role-grant" | "no-matching-grant" | "invalid-resource" | "unknown-resource";
+
+export interface IAuthorizationDecision {
+    readonly allowed: boolean;
+    readonly reason: AuthorizationDecisionReason;
+    readonly matchedPolicies?: readonly string[];
+}
+
+export interface IPolicyEngine {
+    authorize(request: IAuthorizationRequest): IAuthorizationDecision;
+}
+
+export interface IRoleDefinition {
+    readonly inherits?: readonly string[];
+    readonly capabilities: readonly string[];
+}
+
+export interface IPolicyAssignment {
+    readonly id?: string;
+    readonly subject: string;
+    readonly role: string;
+    readonly resource: string;
+}
+
+export interface IDenyPolicy {
+    readonly id?: string;
+    readonly subject: string;
+    readonly effect?: "deny";
+    readonly capabilities: readonly string[];
+    readonly resource: string;
+}
+
+export interface ISubjectMappingConfig {
+    readonly userClaim?: string;
+    readonly groupClaims?: readonly string[];
+    readonly clientClaim?: string;
+    readonly serviceClaims?: readonly string[];
+}
+
+export interface IAuthorizationAuditConfig {
+    readonly logAllowed?: boolean;
+}
+
+export 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;
+}
+
+export 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}. */
+export type AuthorizationSubject = IAuthorizationSubject;
+/** @deprecated Use {@link IAuthorizationRequest}. */
+export type AuthorizationRequest = IAuthorizationRequest;
+/** @deprecated Use {@link IAuthorizationDecision}. */
+export type AuthorizationDecision = IAuthorizationDecision;
+/** @deprecated Use {@link IPolicyEngine}. */
+export type PolicyEngine = IPolicyEngine;
+/** @deprecated Use {@link IRoleDefinition}. */
+export type RoleDefinition = IRoleDefinition;
+/** @deprecated Use {@link IPolicyAssignment}. */
+export type PolicyAssignment = IPolicyAssignment;
+/** @deprecated Use {@link IDenyPolicy}. */
+export type DenyPolicy = IDenyPolicy;
+/** @deprecated Use {@link ISubjectMappingConfig}. */
+export type SubjectMappingConfig = ISubjectMappingConfig;
+/** @deprecated Use {@link IAuthorizationAuditConfig}. */
+export type AuthorizationAuditConfig = IAuthorizationAuditConfig;
+/** @deprecated Use {@link IAuthorizationPolicyConfig}. */
+export type AuthorizationPolicyConfig = IAuthorizationPolicyConfig;
+/** @deprecated Use {@link IAuthorizationAuditEvent}. */
+export type AuthorizationAuditEvent = IAuthorizationAuditEvent;

package/src/authorization/resource.path.ts

@@ -0,0 +1,126 @@
+const WILDCARD = "*";
+const RECURSIVE_WILDCARD = "**";
+
+function assertString(value: string, label: string): void {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`${label}: a non-empty string is required.`);
+    }
+}
+
+function splitAbsolutePath(value: string, label: string): readonly string[] {
+    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: readonly string[]): string {
+    return segments.length === 0 ? "/" : `/${segments.join("/")}`;
+}
+
+/**
+ * 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.
+ */
+export class ResourcePath {
+    readonly value: string;
+    readonly segments: readonly string[];
+
+    private constructor(segments: readonly string[]) {
+        this.segments = Object.freeze([...segments]);
+        this.value = normalizedValue(this.segments);
+    }
+
+    static parse(value: string): ResourcePath {
+        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: string): ResourcePath | undefined {
+        try {
+            return ResourcePath.parse(value);
+        } catch {
+            return undefined;
+        }
+    }
+
+    toString(): string {
+        return this.value;
+    }
+}
+
+/**
+ * A compiled resource expression supporting exact segments, `*` for one
+ * segment, and a final `**` for zero or more trailing segments.
+ */
+export class ResourcePathPattern {
+    readonly value: string;
+    readonly segments: readonly string[];
+    readonly specificity: number;
+
+    private constructor(segments: readonly string[]) {
+        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: string): ResourcePathPattern {
+        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: ResourcePath): boolean {
+        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(): string {
+        return this.value;
+    }
+}

package/src/authorization/runtime.ts

@@ -0,0 +1,56 @@
+import { ConfiguredCapabilityClassifier, type ICapabilityClassifier } from "./capability.classifier";
+import { ConfigPolicyEngine } from "./policy.engine";
+import type { IAuthorizationAuditConfig, IAuthorizationPolicyConfig, IPolicyEngine } from "./policy.types";
+import { DefaultSlotResourceResolver, type ISlotResourceResolver } from "./slot.resource";
+import { JwtSubjectMapper, type ISubjectMapper } from "./subject.mapper";
+
+export interface IPolicyAuthorization {
+    readonly engine: IPolicyEngine;
+    readonly subjectMapper: ISubjectMapper;
+    readonly slotResourceResolver: ISlotResourceResolver;
+    readonly capabilityClassifier: ICapabilityClassifier;
+    readonly audit: Readonly<Required<IAuthorizationAuditConfig>>;
+}
+
+export function hasAuthorizationPolicies(config: IAuthorizationPolicyConfig): boolean {
+    return Object.keys(config.roles ?? {}).length > 0 || (config.assignments?.length ?? 0) > 0 || (config.denies?.length ?? 0) > 0;
+}
+
+/** Compiles and validates the complete hierarchical authorization runtime. */
+export function compileAuthorizationPolicy(config: IAuthorizationPolicyConfig): IPolicyAuthorization {
+    if (config.audit?.logAllowed !== undefined && 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 }),
+    };
+}
+
+export function authorizationWithEngine(
+    engine: IPolicyEngine,
+    overrides: {
+        readonly subjectMapper?: ISubjectMapper;
+        readonly slotResourceResolver?: ISlotResourceResolver;
+        readonly capabilityClassifier?: ICapabilityClassifier;
+        readonly audit?: IAuthorizationAuditConfig;
+    } = {}
+): IPolicyAuthorization {
+    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 }),
+    };
+}
+
+/** @deprecated Use {@link IPolicyAuthorization}. */
+export type PolicyAuthorization = IPolicyAuthorization;

package/src/authorization/slot.resource.ts

@@ -0,0 +1,50 @@
+import { ResourcePath } from "./resource.path";
+
+export interface ISlotResourceResolver {
+    resolve(slot: string): ResourcePath | undefined;
+}
+
+const RESERVED_RESOURCES: Readonly<Record<string, string>> = {
+    _broker: "/_system/broker",
+    _all: "/_system/all",
+};
+
+function isReservedNamespace(resource: ResourcePath): boolean {
+    return resource.value === "/_system" || resource.value.startsWith("/_system/");
+}
+
+/** Default resolver with optional explicit technical-slot mappings. */
+export class DefaultSlotResourceResolver implements ISlotResourceResolver {
+    private readonly _explicit = new Map<string, ResourcePath>();
+
+    constructor(slotResources: Readonly<Record<string, string>> = {}) {
+        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: string): ResourcePath | undefined {
+        const explicit = this._explicit.get(slot);
+        if (explicit) return explicit;
+
+        const reserved = RESERVED_RESOURCES[slot];
+        if (reserved) return ResourcePath.parse(reserved);
+        if (!slot) return undefined;
+
+        const candidate = slot.startsWith("/") ? slot : `/${slot}`;
+        const resource = ResourcePath.tryParse(candidate);
+        return resource && !isReservedNamespace(resource) ? resource : undefined;
+    }
+}
+
+/** @deprecated Use {@link ISlotResourceResolver}. */
+export type SlotResourceResolver = ISlotResourceResolver;

package/src/authorization/subject.mapper.ts

@@ -0,0 +1,81 @@
+import type { IAuthorizationSubject, ISubjectMappingConfig } from "./policy.types";
+
+export interface ISubjectMapper {
+    map(claims: Readonly<Record<string, unknown>>): IAuthorizationSubject;
+}
+
+export class SubjectMappingError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = "SubjectMappingError";
+    }
+}
+
+interface IClaimRule {
+    readonly prefix: string;
+    readonly claim: string;
+}
+
+function claimAt(claims: Readonly<Record<string, unknown>>, claimName: string): unknown {
+    const parts = claimName.split(".");
+    let current: unknown = claims;
+    for (const part of parts) {
+        if (!part || typeof current !== "object" || current === null || Array.isArray(current)) return undefined;
+        current = (current as Readonly<Record<string, unknown>>)[part];
+    }
+    return current;
+}
+
+function valuesOf(value: unknown, claimName: string): readonly string[] {
+    if (value === undefined || value === null) return [];
+    if (typeof value === "string") return value ? [value] : [];
+    if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
+        return value.filter((entry): entry is string => 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: string, label: string): void {
+    if (!value || value.split(".").some((part) => !part)) {
+        throw new Error(`authorization subject mapping: ${label} contains an invalid claim name.`);
+    }
+}
+
+/** Maps validated JWT claims to canonical, deduplicated authorization subjects. */
+export class JwtSubjectMapper implements ISubjectMapper {
+    private readonly _rules: readonly IClaimRule[];
+
+    constructor(config: ISubjectMappingConfig = {}) {
+        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: Readonly<Record<string, unknown>>): IAuthorizationSubject {
+        const ids = new Set<string>();
+        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 };
+    }
+}
+
+/** @deprecated Use {@link ISubjectMapper}. */
+export type SubjectMapper = ISubjectMapper;

package/src/bin.ts

@@ -16,7 +16,7 @@
  * - Env-var paths (`MCP_BROKER_*_DIR`, `MCP_BROKER_TLS_*`) are resolved
  *   against `process.cwd()`.
  * - Config-file paths (`tls.cert`, `www.mounts[*].dir`, `stdioUpstreams[*]`,
- *   `mcpbBundles[*]`) are resolved against the **config file's directory** — so a config in
+ *   `mcpbBundles[*]`) are resolved against the **config file's directory**: so a config in
  *   `./.mcp-broker/config.json` referring to `"certs/cert.pem"` points at
  *   `./.mcp-broker/certs/cert.pem`. The folder is self-contained.
  *
@@ -48,13 +48,15 @@
  * |                                |          | provider (Claude Desktop bridge).                      |
  * | MCP_BROKER_LOCALE              | en       | Locale used for tool descriptions on the `_broker`     |
  * |                                |          | slot. ISO 639-1 base; regional variants accepted.      |
+ * | MCP_BROKER_ALLOWED_ORIGINS     | (none)   | Comma-separated browser origins allowed on             |
+ * |                                |          | `/<slot>/mcp`. None means no browser origin passes.    |
  */
 import * as fs from "fs";
 import * as path from "path";
 import open from "open";
-import { WsTunnelBuilder } from "./index.js";
-import { loadBrokerConfig } from "./config.js";
-import { loadMcpbBundle } from "./mcpb.loader.js";
+import { WsTunnelBuilder } from "./index";
+import { loadBrokerConfig } from "./config";
+import { loadMcpbBundle } from "./mcpb/mcpb.loader";
 
 // ---------------------------------------------------------------------------
 // Configuration
@@ -65,7 +67,7 @@ const cwd = process.cwd();
 
 /**
  * Fills an env var from the config file when the env var is not already set.
- * Used for **non-path** scalars — path-bearing fields are read directly so
+ * Used for **non-path** scalars, path-bearing fields are read directly so
  * they can be resolved against `baseDir` (config file's directory) instead
  * of `cwd` (deploy environment).
  */
@@ -84,10 +86,15 @@ envFromConfig("MCP_BROKER_PROVIDER_PATH", config.paths?.provider);
 envFromConfig("MCP_BROKER_CLIENT_PATH", config.paths?.client);
 envFromConfig("MCP_BROKER_MCP_PATH", config.paths?.mcp);
 envFromConfig("MCP_BROKER_OPEN", config.www?.open === true ? "1" : undefined);
+envFromConfig("MCP_BROKER_AUTH_ENABLED", config.auth?.enabled === true ? "1" : undefined);
+envFromConfig("MCP_BROKER_PUBLIC_BASE_URL", config.auth?.publicBaseUrl);
+envFromConfig("MCP_BROKER_JWKS", config.auth?.jwks);
+envFromConfig("MCP_BROKER_ISSUER", config.auth?.issuer);
+envFromConfig("MCP_BROKER_PROVIDER_SECRET", config.auth?.providerSecret);
 
 const stdioProvider = process.env["MCP_BROKER_STDIO_PROVIDER"];
 
-// In stdio mode stdout is reserved for JSON-RPC — redirect all console output to stderr.
+// In stdio mode stdout is reserved for JSON-RPC, redirect all console output to stderr.
 if (stdioProvider) {
     const toStderr = (...args: unknown[]) => process.stderr.write(args.join(" ") + "\n");
     console.log = toStderr;
@@ -120,6 +127,30 @@ if (protocolOverride === "https" && (!tlsCertPath || !tlsKeyPath)) {
 
 const useTls = protocolOverride === "http" ? false : protocolOverride === "https" ? true : !!(tlsCertPath && tlsKeyPath);
 
+// ── Allowed browser origins for /<slot>/mcp ──────────────────────────────────
+// Absent leaves the endpoint closed to browsers, which is the safe default.
+// The env var only carries the list form; a pattern needs the config file,
+// since a regular expression cannot survive comma-splitting.
+const envOrigins = process.env["MCP_BROKER_ALLOWED_ORIGINS"]
+    ?.split(",")
+    .map((origin) => origin.trim())
+    .filter(Boolean);
+
+let allowedOrigins: readonly string[] | RegExp | undefined;
+if (envOrigins?.length) {
+    allowedOrigins = envOrigins;
+} else if (Array.isArray(config.allowedOrigins)) {
+    allowedOrigins = config.allowedOrigins;
+} else if (config.allowedOrigins) {
+    try {
+        allowedOrigins = new RegExp(config.allowedOrigins.pattern, config.allowedOrigins.flags);
+    } catch (err) {
+        // Falling back to the closed default rather than starting with a rule
+        // the operator believes is in force but which never compiled.
+        console.error(`[mcp-broker] Ignoring allowedOrigins.pattern: ${(err as Error).message}`);
+    }
+}
+
 // ── Env-var static mount shortcuts (relative to cwd) ─────────────────────────
 const envWwwDir = process.env["MCP_BROKER_WWW_DIR"] ? path.resolve(cwd, process.env["MCP_BROKER_WWW_DIR"]) : null;
 const envBundleDir = process.env["MCP_BROKER_BUNDLE_DIR"] ? path.resolve(cwd, process.env["MCP_BROKER_BUNDLE_DIR"]) : null;
@@ -144,6 +175,10 @@ async function main(): Promise<void> {
         builder.withTlsFiles(tlsCertPath!, tlsKeyPath!);
     }
 
+    if (allowedOrigins) {
+        builder.withAllowedOrigins(allowedOrigins);
+    }
+
     // ── Static mounts ────────────────────────────────────────────────────────
     // First the env-var shortcuts (relative to cwd), then the config `www.mounts`
     // (relative to baseDir). Order matters: /bundle before / so the prefix router
@@ -209,6 +244,52 @@ async function main(): Promise<void> {
         builder.withBrokerLocalGrammarsDir(localGrammarsDir);
     }
 
+    // ── Authorization (OAuth 2.1 resource server) ────────────────────────────
+    // Opt-in: only wired when MCP_BROKER_AUTH_ENABLED / config.auth.enabled is on.
+    // Env scalars win over config; array/object fields are read from config.
+    const authEnabledEnv = process.env["MCP_BROKER_AUTH_ENABLED"];
+    const authEnabled = authEnabledEnv === "1" || authEnabledEnv === "true";
+    if (authEnabled) {
+        const publicBaseUrl = process.env["MCP_BROKER_PUBLIC_BASE_URL"];
+        const jwks = process.env["MCP_BROKER_JWKS"];
+        const issuer = process.env["MCP_BROKER_ISSUER"];
+        const authorizationServers = config.auth?.authorizationServers ?? (issuer ? [issuer] : []);
+        if (!publicBaseUrl || !jwks || authorizationServers.length === 0) {
+            console.error(
+                "[mcp-broker] auth.enabled requires publicBaseUrl, jwks, and at least one " +
+                    "authorizationServers entry (or issuer). Set them via config.auth or " +
+                    "MCP_BROKER_PUBLIC_BASE_URL / MCP_BROKER_JWKS / MCP_BROKER_ISSUER."
+            );
+            process.exit(1);
+        }
+        builder.withJwtAuth({
+            publicBaseUrl,
+            authorizationServers,
+            jwksUri: jwks,
+            issuer,
+            scopesSupported: config.auth?.scopesSupported,
+            requiredScopes: config.auth?.requiredScopes,
+            perSlotScopes: config.auth?.perSlotScopes,
+            providerScopes: config.auth?.providerScopes,
+            subjectMapping: config.auth?.subjectMapping,
+            roles: config.auth?.roles,
+            assignments: config.auth?.assignments,
+            denies: config.auth?.denies,
+            slotResources: config.auth?.slotResources,
+            toolCapabilities: config.auth?.toolCapabilities,
+            providerToolCapabilities: config.auth?.providerToolCapabilities,
+            audit: config.auth?.audit,
+        });
+    }
+
+    // ── Provider authentication (independent of client OAuth) ────────────────
+    // Requires every provider connecting to /provider/<slot> or /providers to
+    // present the shared secret, closes off slot occupation by strangers.
+    const providerSecret = process.env["MCP_BROKER_PROVIDER_SECRET"];
+    if (providerSecret) {
+        builder.withProviderSecret(providerSecret);
+    }
+
     const tunnel = builder.build();
     await tunnel.start();
 
@@ -230,6 +311,8 @@ async function main(): Promise<void> {
     if (hasLocalGrammars) {
         console.log(`🌐  Local grammars        ${localGrammarsDir}`);
     }
+    console.log(`🔐  Authorization         ${authEnabled ? "OAuth 2.1 (Bearer required)" : "disabled (trusted network only)"}`);
+    console.log(`🛡️   Provider auth         ${providerSecret ? "shared secret required" : "disabled"}`);
     console.log(hr);
     console.log(`   Press Ctrl+C to stop.`);
     console.log();
@@ -245,7 +328,7 @@ async function main(): Promise<void> {
 
     // ── Signal handlers ─────────────────────────────────────────────────────
     const shutdown = async (signal: string): Promise<void> => {
-        console.log(`\n⛔  ${signal} received — shutting down…`);
+        console.log(`\n⛔  ${signal} received, shutting down…`);
         await tunnel.stop();
         process.exit(0);
     };

package/src/broker/adapters/broker.adapter.info.ts

@@ -1,16 +1,16 @@
 import { McpAdapterBase, McpToolResults } from "@cyanmycelium/mcp-core";
 import type { McpResourceContent, McpToolResult } from "@cyanmycelium/mcp-core";
-import type { BrokerContext } from "../broker.context.js";
+import type { IBrokerContext } from "../broker.context";
 
 /** URI of the static resource backing the `broker_info` snapshot. */
 export const BROKER_INFO_URI = "broker://info";
 
 /**
  * Read-only adapter that produces a snapshot of the broker's identity and
- * configuration. Backed by the live {@link BrokerContext}.
+ * configuration. Backed by the live {@link IBrokerContext}.
  */
 export class BrokerInfoAdapter extends McpAdapterBase {
-    constructor(private readonly _context: BrokerContext) {
+    constructor(private readonly _context: IBrokerContext) {
         super("broker");
     }
 

package/src/broker/adapters/broker.adapter.providers.ts

@@ -1,6 +1,6 @@
 import { McpAdapterBase, McpToolResults } from "@cyanmycelium/mcp-core";
 import type { McpResourceContent, McpToolResult } from "@cyanmycelium/mcp-core";
-import type { BrokerContext, BrokerProviderInfo } from "../broker.context.js";
+import type { IBrokerContext, IBrokerProviderInfo } from "../broker.context";
 
 /** URI of the static resource that lists every provider slot. */
 export const PROVIDERS_URI = "broker://providers";
@@ -13,7 +13,7 @@ export const PROVIDER_URI_TEMPLATE = "broker://providers/{name}";
  * (read of `broker://providers`) and individually (`broker://providers/<name>`).
  */
 export class BrokerProvidersAdapter extends McpAdapterBase {
-    constructor(private readonly _context: BrokerContext) {
+    constructor(private readonly _context: IBrokerContext) {
         super("broker");
     }
 
@@ -60,7 +60,7 @@ export class BrokerProvidersAdapter extends McpAdapterBase {
         }
     }
 
-    private _listSnapshot(): { count: number; providers: BrokerProviderInfo[] } {
+    private _listSnapshot(): { count: number; providers: IBrokerProviderInfo[] } {
         const providers = this._context.getProvidersInfo();
         return { count: providers.length, providers };
     }