@cyanmycelium/mcp-broker 0.4.0 → 1.2.0

package/src/broker/broker.grammars.ts

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 import { McpGrammar } from "@cyanmycelium/mcp-core";
 
 // ---------------------------------------------------------------------------
-// Open string types — extensibility by convention
+// Open string types, extensibility by convention
 // ---------------------------------------------------------------------------
 
 /**
@@ -27,7 +27,7 @@ export type BrokerLocale = string;
  * the defaults emitted by `grammarResolverFromOptions`: `claude`, `gpt`,
  * `mistral`, `copilot`, plus the universal `default`. Custom families
  * are supported by passing a custom `agents` map in
- * `StartBrokerServerOptions.grammarResolverOptions`.
+ * `IStartBrokerServerOptions.grammarResolverOptions`.
  */
 export type BrokerUserAgent = string;
 
@@ -40,8 +40,8 @@ export type BrokerUserAgent = string;
  * 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"`
+ *   - `"<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
@@ -94,7 +94,7 @@ export function parseBrokerGrammarStem(stem: string): { locale: BrokerLocale; ve
  * JSON files live alongside this module in `src/broker/grammars/` during
  * development and are mirrored under `dist/broker/grammars/` at build time
  * by `scripts/copy-assets.mjs`. Adding a new `(userAgent, locale)` pair is
- * just a matter of dropping a new JSON file — no code change required.
+ * just a matter of dropping a new JSON file: no code change required.
  */
 const GRAMMARS_DIR = join(dirname(fileURLToPath(import.meta.url)), "grammars");
 
@@ -132,9 +132,9 @@ export function loadBrokerGrammar(userAgent: BrokerUserAgent, locale: BrokerLoca
  *
  * 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.
+ * user-agents or locales, adding a new grammar is dropping a JSON file.
  */
-export interface BrokerGrammarEntry {
+export interface IBrokerGrammarEntry {
     userAgent: BrokerUserAgent;
     locale: BrokerLocale;
     /** Set only for filenames carrying an `@<version>` suffix. */
@@ -144,7 +144,7 @@ export interface BrokerGrammarEntry {
     grammar: McpGrammar;
 }
 
-export function* iterBrokerGrammarsFrom(grammarsDir: string): Generator<BrokerGrammarEntry> {
+export function* iterBrokerGrammarsFrom(grammarsDir: string): Generator<IBrokerGrammarEntry> {
     if (!existsSync(grammarsDir)) return;
 
     const userAgents = readdirSync(grammarsDir).sort();
@@ -186,12 +186,15 @@ export function* iterBrokerGrammarsFrom(grammarsDir: string): Generator<BrokerGr
  * 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.
+ * directory, typically `.mcp-broker/grammars/` next to the config file.
  */
-export function* iterAvailableBrokerGrammars(): Generator<BrokerGrammarEntry> {
+export function* iterAvailableBrokerGrammars(): Generator<IBrokerGrammarEntry> {
     yield* iterBrokerGrammarsFrom(GRAMMARS_DIR);
 }
 
+/** @deprecated Use {@link IBrokerGrammarEntry}. */
+export type BrokerGrammarEntry = IBrokerGrammarEntry;
+
 // ---------------------------------------------------------------------------
 // Baseline helpers (used by behaviors to source their inline descriptions)
 // ---------------------------------------------------------------------------
@@ -203,20 +206,20 @@ export function* iterAvailableBrokerGrammars(): Generator<BrokerGrammarEntry> {
  * Conventionally this is `default:en`. Session-specific grammars selected by
  * the resolver override individual entries on top of this baseline.
  *
- * Throws if the JSON resource is missing — the broker behaviors cannot be
+ * Throws if the JSON resource is missing: the broker behaviors cannot be
  * built without baseline descriptions.
  */
 export function brokerBaselineGrammar(): McpGrammar {
     const g = loadBrokerGrammar("default", "en");
     if (!g) {
-        throw new Error(`Required baseline broker grammar "default:en" is missing — expected at ${join(GRAMMARS_DIR, "default", "en.json")}.`);
+        throw new Error(`Required baseline broker grammar "default:en" is missing, expected at ${join(GRAMMARS_DIR, "default", "en.json")}.`);
     }
     return g;
 }
 
 /**
  * Convenience accessor for a baseline tool description. Throws when the
- * tool is not listed in the baseline grammar — i.e. the JSON file is missing
+ * tool is not listed in the baseline grammar, i.e. the JSON file is missing
  * an entry for a tool the code knows about.
  */
 export function brokerBaselineToolDescription(toolName: string): string {

package/src/broker/broker.server.ts

@@ -1,9 +1,9 @@
 import { McpServerBuilder, LoopbackTransport } from "@cyanmycelium/mcp-core";
 import type { GrammarResolverOptions, IMcpServer, IMessageTransport } from "@cyanmycelium/mcp-core";
-import { BrokerInfoBehavior } from "./behaviors/broker.behavior.info.js";
-import { BrokerProvidersBehavior } from "./behaviors/broker.behavior.providers.js";
-import { iterAvailableBrokerGrammars, iterBrokerGrammarsFrom } from "./broker.grammars.js";
-import type { BrokerContext } from "./broker.context.js";
+import { BrokerInfoBehavior } from "./behaviors/broker.behavior.info";
+import { BrokerProvidersBehavior } from "./behaviors/broker.behavior.providers";
+import { iterAvailableBrokerGrammars, iterBrokerGrammarsFrom } from "./broker.grammars";
+import type { IBrokerContext } from "./broker.context";
 
 /**
  * Reserved provider slot name under which the broker exposes itself as an MCP
@@ -19,7 +19,7 @@ export const BROKER_PROVIDER_NAME = "_broker";
  * replace either resolver with custom logic without touching mcp-broker
  * internals.
  */
-export interface StartBrokerServerOptions {
+export interface IStartBrokerServerOptions {
     /**
      * Overrides for the built-in grammar resolver from `@cyanmycelium/mcp-core`.
      *
@@ -44,7 +44,7 @@ export interface StartBrokerServerOptions {
      * 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 —
+     * (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.
@@ -69,8 +69,8 @@ export interface StartBrokerServerOptions {
  *          loopback transport to attach to the tunnel.
  */
 export async function startBrokerServer(
-    context: BrokerContext,
-    options: StartBrokerServerOptions = {}
+    context: IBrokerContext,
+    options: IStartBrokerServerOptions = {}
 ): Promise<{
     server: IMcpServer;
     clientTransport: IMessageTransport;
@@ -93,7 +93,7 @@ export async function startBrokerServer(
     // Register every `(userAgent, locale)` JSON found on disk as a raw
     // grammar layer. The candidate-chain resolution in
     // McpServer.initialize (mcp-core@0.3.0) walks the resolver's chain
-    // and merges all matching layers — so partial user-agent files no
+    // and merges all matching layers: so partial user-agent files no
     // longer need to be pre-merged with the default-locale baseline at
     // boot. Local overrides come after packaged entries; identical keys
     // get overlaid via the registry's last-write-wins.
@@ -124,3 +124,6 @@ export async function startBrokerServer(
 
     return { server, clientTransport: clientEnd };
 }
+
+/** @deprecated Use {@link IStartBrokerServerOptions}. */
+export type StartBrokerServerOptions = IStartBrokerServerOptions;

package/src/broker/grammars/claude/en.json

@@ -7,7 +7,7 @@
             "description": "List every provider slot on this broker, connected or not. Each entry tells you the transport kind, current client count, and how many requests are in flight. Use this to discover what you can route to."
         },
         "provider_status": {
-            "description": "Get the full status of one provider slot by name. Returns an error if the slot does not exist — start with providers_list if you are not sure of the name.",
+            "description": "Get the full status of one provider slot by name. Returns an error if the slot does not exist, start with providers_list if you are not sure of the name.",
             "properties": {
                 "name": "The exact provider slot name. Case-sensitive. Use providers_list to discover valid values."
             }

package/src/broker/grammars/claude/fr.json

@@ -7,7 +7,7 @@
             "description": "Liste tous les emplacements de providers de ce broker, connectés ou non. Chaque entrée indique le type de transport, le nombre de clients actuels et le nombre de requêtes en cours. Utilise-le pour découvrir vers qui tu peux router."
         },
         "provider_status": {
-            "description": "Récupère le statut complet d'un emplacement de provider par son nom. Retourne une erreur si l'emplacement n'existe pas — commence par providers_list si tu n'es pas sûr du nom.",
+            "description": "Récupère le statut complet d'un emplacement de provider par son nom. Retourne une erreur si l'emplacement n'existe pas, commence par providers_list si tu n'es pas sûr du nom.",
             "properties": {
                 "name": "Le nom exact de l'emplacement provider. Sensible à la casse. Utilise providers_list pour découvrir les valeurs valides."
             }

package/src/broker/index.ts

@@ -1,9 +1,9 @@
-export { BrokerInfoBehavior } from "./behaviors/broker.behavior.info.js";
-export { BrokerProvidersBehavior } from "./behaviors/broker.behavior.providers.js";
-export { BrokerInfoAdapter, BROKER_INFO_URI } from "./adapters/broker.adapter.info.js";
-export { BrokerProvidersAdapter, PROVIDERS_URI, PROVIDER_URI_TEMPLATE } from "./adapters/broker.adapter.providers.js";
-export { startBrokerServer, BROKER_PROVIDER_NAME } from "./broker.server.js";
-export type { StartBrokerServerOptions } from "./broker.server.js";
+export { BrokerInfoBehavior } from "./behaviors/broker.behavior.info";
+export { BrokerProvidersBehavior } from "./behaviors/broker.behavior.providers";
+export { BrokerInfoAdapter, BROKER_INFO_URI } from "./adapters/broker.adapter.info";
+export { BrokerProvidersAdapter, PROVIDERS_URI, PROVIDER_URI_TEMPLATE } from "./adapters/broker.adapter.providers";
+export { startBrokerServer, BROKER_PROVIDER_NAME } from "./broker.server";
+export type { IStartBrokerServerOptions, StartBrokerServerOptions } from "./broker.server";
 export {
     brokerBaselineGrammar,
     brokerBaselinePropertyDescription,
@@ -17,6 +17,6 @@ export {
     iterBrokerGrammarsFrom,
     loadBrokerGrammar,
     parseBrokerGrammarStem,
-} from "./broker.grammars.js";
-export type { BrokerGrammarEntry, BrokerLocale, BrokerUserAgent } from "./broker.grammars.js";
-export type { BrokerContext, BrokerProviderInfo, BrokerProviderTransport } from "./broker.context.js";
+} from "./broker.grammars";
+export type { IBrokerGrammarEntry, BrokerGrammarEntry, BrokerLocale, BrokerUserAgent } from "./broker.grammars";
+export type { IBrokerContext, IBrokerProviderInfo, BrokerContext, BrokerProviderInfo, BrokerProviderTransport } from "./broker.context";

package/src/config.ts

@@ -1,5 +1,35 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
+import type { IAuthorizationPolicyConfig } from "./authorization/index";
+
+export 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.
@@ -18,7 +48,7 @@ import { dirname, resolve } from "node:path";
  * }
  * ```
  */
-export interface BrokerConfig {
+export interface IBrokerConfig {
     /** TCP port. Maps to `MCP_BROKER_PORT`. */
     port?: number;
 
@@ -37,6 +67,40 @@ export interface BrokerConfig {
     /** 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;
@@ -119,8 +183,8 @@ export interface BrokerConfig {
  * (the directory containing the config file when one was found, otherwise
  * `process.cwd()`).
  */
-export interface LoadedBrokerConfig {
-    config: BrokerConfig;
+export interface ILoadedBrokerConfig {
+    config: IBrokerConfig;
     baseDir: string;
     /** Absolute path of the config file that was loaded, or `null` if none. */
     sourcePath: string | null;
@@ -142,17 +206,17 @@ export const LEGACY_CONFIG_FILENAME = "mcp-broker.config.json";
  * 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 —
+ * 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.
+ * returns the same empty config, never throws.
  *
  * Paths inside the config file are intended to be resolved against
- * {@link LoadedBrokerConfig.baseDir} by the consumer.
+ * {@link ILoadedBrokerConfig.baseDir} by the consumer.
  */
-export function loadBrokerConfig(path?: string): LoadedBrokerConfig {
+export function loadBrokerConfig(path?: string): ILoadedBrokerConfig {
     const cwd = process.cwd();
     const envPath = process.env["MCP_BROKER_CONFIG"];
 
@@ -183,10 +247,19 @@ export function loadBrokerConfig(path?: string): LoadedBrokerConfig {
 
     try {
         const raw = readFileSync(sourcePath, "utf-8");
-        const config = JSON.parse(raw) as BrokerConfig;
+        const config = JSON.parse(raw) as IBrokerConfig;
         return { config, baseDir, sourcePath };
     } catch (err) {
         process.stderr.write(`[mcp-broker] Failed to parse config file at ${sourcePath}: ${(err as Error).message}\n`);
         return { config: {}, baseDir: cwd, sourcePath: null };
     }
 }
+
+/** @deprecated Use {@link IBrokerAuthConfig}. */
+export type BrokerAuthConfig = IBrokerAuthConfig;
+
+/** @deprecated Use {@link IBrokerConfig}. */
+export type BrokerConfig = IBrokerConfig;
+
+/** @deprecated Use {@link ILoadedBrokerConfig}. */
+export type LoadedBrokerConfig = ILoadedBrokerConfig;

package/src/index.ts

@@ -1,26 +1,127 @@
-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 { WsTunnel } from "./ws/ws.tunnel";
+export { WsTunnelBuilder } from "./ws/ws.tunnel.builder";
+export type { AllowedOrigins, IInternalClient, IWsTunnelOptions, IStaticMount, InternalClient, WsTunnelOptions, StaticMount } from "./ws/ws.interfaces";
+export { StdioUpstream } from "./stdio.upstream";
+export type { IStdioUpstreamConfig, StdioUpstreamConfig } from "./stdio.upstream";
+export { RemoteUpstream } from "./remote.upstream";
+export type { IRemoteUpstreamConfig, RemoteUpstreamConfig } from "./remote.upstream";
+export type { IUpstream, Upstream } from "./upstream";
 
-// `.mcpb` bundle loading — verifies + unpacks a bundle into a stdio upstream.
-export { loadMcpbBundle } from "./mcpb.loader.js";
-export type { McpbBundleConfig } from "./mcpb.loader.js";
-export { unzipMcpb } from "./mcpb.unzip.js";
+// `.mcpb` bundle loading, verifies + unpacks a bundle into a stdio upstream.
+export { loadMcpbBundle } from "./mcpb/mcpb.loader";
+export type { IMcpbBundleConfig, McpbBundleConfig } from "./mcpb/mcpb.loader";
+export { unzipMcpb } from "./mcpb/mcpb.unzip";
 
-// Broker introspection — tier 1.
-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";
+// Broker introspection, tier 1.
+export { BrokerInfoBehavior, BrokerProvidersBehavior, startBrokerServer, BROKER_PROVIDER_NAME } from "./broker/index";
+export type { IStartBrokerServerOptions, StartBrokerServerOptions } from "./broker/index";
+export { brokerGrammarKey, iterAvailableBrokerGrammars, iterBrokerGrammarsFrom, loadBrokerGrammar } from "./broker/index";
+export type {
+    IBrokerContext,
+    IBrokerGrammarEntry,
+    IBrokerProviderInfo,
+    BrokerContext,
+    BrokerGrammarEntry,
+    BrokerProviderInfo,
+    BrokerProviderTransport,
+    BrokerLocale,
+    BrokerUserAgent,
+} from "./broker/index";
 
-export { VERSION, PACKAGE_NAME } from "./version.js";
+export { VERSION, PACKAGE_NAME } from "./version";
+
+// OAuth 2.1 resource-server authorization.
+export {
+    AuthError,
+    scopesOf,
+    JwtTokenValidator,
+    buildResourceMetadata,
+    HttpAuthGuard,
+    buildJwtAuth,
+    normalizeProviderAuthentication,
+    providerMayPublish,
+    SharedSecretProviderAuthenticator,
+} from "./auth/index";
+export type {
+    IAccessTokenClaims,
+    ITokenValidator,
+    IPrincipal,
+    IResolvedAuth,
+    IJwtValidatorOptions,
+    IProtectedResourceMetadata,
+    IJwtAuthOptions,
+    IProviderAuthenticator,
+    IProviderPrincipal,
+    AccessTokenClaims,
+    TokenValidator,
+    AuthErrorCode,
+    Principal,
+    ResolvedAuth,
+    JwtValidatorOptions,
+    ProtectedResourceMetadata,
+    JwtAuthOptions,
+    ProviderAuthenticator,
+    AggregateScopeFilter,
+    ProviderAuthenticationResult,
+    ProviderAuthenticatorReturn,
+    ProviderPrincipal,
+} from "./auth/index";
+
+// Hierarchical, domain-neutral authorization.
+export {
+    ConfigPolicyEngine,
+    ConfiguredCapabilityClassifier,
+    DefaultSlotResourceResolver,
+    JwtSubjectMapper,
+    ResourcePath,
+    ResourcePathPattern,
+    SubjectMappingError,
+    authorizationWithEngine,
+    compileAuthorizationPolicy,
+    hasAuthorizationPolicies,
+    validateCapability,
+} from "./authorization/index";
+export type {
+    IAuditContext,
+    IAuthorizationAuditConfig,
+    IAuthorizationAuditEvent,
+    IAuthorizationDecision,
+    IAuthorizationPolicyConfig,
+    IAuthorizationRequest,
+    IAuthorizationSubject,
+    ICapabilityClassifier,
+    IClassifiedCapability,
+    IDenyPolicy,
+    IMcpOperation,
+    IPolicyAssignment,
+    IPolicyAuthorization,
+    IPolicyEngine,
+    IRoleDefinition,
+    ISlotResourceResolver,
+    ISubjectMapper,
+    ISubjectMappingConfig,
+    AuditContext,
+    AuthorizationAuditConfig,
+    AuthorizationAuditEvent,
+    AuthorizationDecision,
+    AuthorizationDecisionReason,
+    AuthorizationPolicyConfig,
+    AuthorizationRequest,
+    AuthorizationSubject,
+    CapabilityClassifier,
+    ClassifiedCapability,
+    DenyPolicy,
+    McpOperation,
+    PolicyAssignment,
+    PolicyAuthorization,
+    PolicyEngine,
+    RoleDefinition,
+    SlotResourceResolver,
+    SubjectMapper,
+    SubjectMappingConfig,
+} from "./authorization/index";
 
 // JSON config file used by `bin.ts` at startup. Exported so a programmatic
 // embedder can re-use the same loader against a custom path.
-export { loadBrokerConfig, DEFAULT_CONFIG_FILENAME } from "./config.js";
-export type { BrokerConfig } from "./config.js";
+export { loadBrokerConfig, DEFAULT_CONFIG_FILENAME } from "./config";
+export type { IBrokerAuthConfig, IBrokerConfig, ILoadedBrokerConfig, BrokerAuthConfig, BrokerConfig, LoadedBrokerConfig } from "./config";

package/src/{mcpb.loader.ts → mcpb/mcpb.loader.ts}

@@ -1,18 +1,18 @@
 /**
- * Loads a local `.mcpb` bundle into a {@link StdioUpstreamConfig}.
+ * Loads a local `.mcpb` bundle into an {@link IStdioUpstreamConfig}.
  *
  * A `.mcpb` bundle is a ZIP holding a `manifest.json` whose `server.mcp_config`
  * describes a stdio MCP server process. The broker:
  *
  * 1. verifies a **detached signature** of the `.mcpb` file against a trusted
- *    public key (PEM) — integrity *and* provenance, using `node:crypto` only;
+ *    public key (PEM), integrity *and* provenance, using `node:crypto` only;
  * 2. unpacks the archive;
  * 3. reads the manifest, expands the `mcp_config` placeholders, and produces a
- *    `StdioUpstreamConfig` that the existing upstream wiring spawns.
+ *    `IStdioUpstreamConfig` that the existing upstream wiring spawns.
  *
  * The broker stays compatible with the `.mcpb` format without depending on the
  * `@anthropic-ai/mcpb` package: the bundle's *own* (native PKCS#7) signature is
- * never parsed — the detached signature layer is the broker's trust anchor.
+ * never parsed: the detached signature layer is the broker's trust anchor.
  *
  * Any failure (missing files, bad signature, malformed manifest, missing
  * `user_config` value) is logged and yields `null`: the bundle is refused and
@@ -22,11 +22,11 @@ import { createPublicKey, verify, X509Certificate, type KeyObject } from "node:c
 import { existsSync, readFileSync, rmSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve, sep } from "node:path";
-import { unzipMcpb } from "./mcpb.unzip.js";
-import type { StdioUpstreamConfig } from "./stdio.upstream.js";
+import { unzipMcpb } from "./mcpb.unzip";
+import type { IStdioUpstreamConfig } from "../stdio.upstream";
 
 /** A `.mcpb` bundle entry from the broker config file. */
-export interface McpbBundleConfig {
+export interface IMcpbBundleConfig {
     /** Provider slot name the bundle is bound to. */
     name: string;
     /** Path to the `.mcpb` file. */
@@ -41,7 +41,7 @@ export interface McpbBundleConfig {
     aggregate?: boolean;
 }
 
-interface McpConfig {
+interface IMcpConfig {
     command?: string;
     args?: string[];
     env?: Record<string, string>;
@@ -65,7 +65,7 @@ function verifyDetachedSignature(data: Buffer, signature: Buffer, publicKey: Key
 }
 
 /** Resolves a single `${...}` placeholder key, or `undefined` when unknown. */
-function resolvePlaceholder(key: string, dirname: string, userConfig: McpbBundleConfig["userConfig"]): string | number | boolean | Array<string | number> | undefined {
+function resolvePlaceholder(key: string, dirname: string, userConfig: IMcpbBundleConfig["userConfig"]): string | number | boolean | Array<string | number> | undefined {
     if (key === "__dirname") return dirname;
     if (key === "HOME") return homedir();
     if (key === "DESKTOP") return join(homedir(), "Desktop");
@@ -82,17 +82,17 @@ function resolvePlaceholder(key: string, dirname: string, userConfig: McpbBundle
 }
 
 /** Expands placeholders in a scalar string (command, env value). */
-function expandScalar(input: string, dirname: string, userConfig: McpbBundleConfig["userConfig"]): string {
+function expandScalar(input: string, dirname: string, userConfig: IMcpbBundleConfig["userConfig"]): string {
     return input.replace(/\$\{([^}]+)\}/g, (match, key: string) => {
         const value = resolvePlaceholder(key, dirname, userConfig);
-        if (value === undefined) return match; // unknown placeholder — leave verbatim
+        if (value === undefined) return match; // unknown placeholder, leave verbatim
         if (Array.isArray(value)) throw new Error(`placeholder "\${${key}}" is multi-valued and cannot be used here`);
         return String(value);
     });
 }
 
 /** Expands one manifest argument; a standalone multi-valued placeholder spreads. */
-function expandArg(arg: string, dirname: string, userConfig: McpbBundleConfig["userConfig"]): string[] {
+function expandArg(arg: string, dirname: string, userConfig: IMcpbBundleConfig["userConfig"]): string[] {
     const standalone = /^\$\{(user_config\.[^}]+)\}$/.exec(arg);
     if (standalone) {
         const value = resolvePlaceholder(standalone[1], dirname, userConfig);
@@ -103,13 +103,13 @@ function expandArg(arg: string, dirname: string, userConfig: McpbBundleConfig["u
 }
 
 /**
- * Verifies, unpacks and resolves a `.mcpb` bundle into a `StdioUpstreamConfig`.
+ * 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.
  */
-export async function loadMcpbBundle(cfg: McpbBundleConfig, baseDir: string): Promise<StdioUpstreamConfig | null> {
+export async function loadMcpbBundle(cfg: IMcpbBundleConfig, baseDir: string): Promise<IStdioUpstreamConfig | null> {
     const tag = `[mcp-broker] mcpb bundle "${cfg.name}"`;
     try {
         const mcpbPath = resolve(baseDir, cfg.path);
@@ -122,7 +122,7 @@ export async function loadMcpbBundle(cfg: McpbBundleConfig, baseDir: string): Pr
             ["signature", signaturePath],
         ] as const) {
             if (!existsSync(file)) {
-                console.error(`${tag}: ${label} file not found at ${file} — bundle refused.`);
+                console.error(`${tag}: ${label} file not found at ${file}, bundle refused.`);
                 return null;
             }
         }
@@ -132,7 +132,7 @@ export async function loadMcpbBundle(cfg: McpbBundleConfig, baseDir: string): Pr
         const signatureBytes = readFileSync(signaturePath);
         const publicKey = loadPublicKey(readFileSync(publicKeyPath, "utf8"));
         if (!verifyDetachedSignature(bundleBytes, signatureBytes, publicKey)) {
-            console.error(`${tag}: detached signature is invalid for the configured public key — bundle refused.`);
+            console.error(`${tag}: detached signature is invalid for the configured public key, bundle refused.`);
             return null;
         }
 
@@ -144,13 +144,13 @@ export async function loadMcpbBundle(cfg: McpbBundleConfig, baseDir: string): Pr
         // ── Manifest → mcp_config ───────────────────────────────────────────
         const manifestPath = join(outputDir, "manifest.json");
         if (!existsSync(manifestPath)) {
-            console.error(`${tag}: manifest.json missing inside the bundle — bundle refused.`);
+            console.error(`${tag}: manifest.json missing inside the bundle, bundle refused.`);
             return null;
         }
-        const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as { server?: { mcp_config?: McpConfig } };
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as { server?: { mcp_config?: IMcpConfig } };
         const mcpConfig = manifest.server?.mcp_config;
         if (!mcpConfig) {
-            console.error(`${tag}: manifest has no server.mcp_config — bundle refused.`);
+            console.error(`${tag}: manifest has no server.mcp_config, bundle refused.`);
             return null;
         }
 
@@ -160,7 +160,7 @@ export async function loadMcpbBundle(cfg: McpbBundleConfig, baseDir: string): Pr
         const rawArgs = override?.args ?? mcpConfig.args ?? [];
         const rawEnv = { ...mcpConfig.env, ...override?.env };
         if (!command) {
-            console.error(`${tag}: manifest mcp_config has no command — bundle refused.`);
+            console.error(`${tag}: manifest mcp_config has no command, bundle refused.`);
             return null;
         }
 
@@ -180,7 +180,10 @@ export async function loadMcpbBundle(cfg: McpbBundleConfig, baseDir: string): Pr
             aggregate: cfg.aggregate ?? true,
         };
     } catch (err) {
-        console.error(`${tag}: ${(err as Error).message} — bundle refused.`);
+        console.error(`${tag}: ${(err as Error).message}, bundle refused.`);
         return null;
     }
 }
+
+/** @deprecated Use {@link IMcpbBundleConfig}. */
+export type McpbBundleConfig = IMcpbBundleConfig;

package/src/{mcpb.unzip.ts → mcpb/mcpb.unzip.ts}

@@ -3,12 +3,12 @@
  *
  * A `.mcpb` bundle is an ordinary ZIP archive. The broker deliberately avoids
  * the `@anthropic-ai/mcpb` package so it stays compatible with the format
- * without being coupled to Anthropic's tooling — hence this small reader.
+ * without being coupled to Anthropic's tooling, hence this small reader.
  *
  * Supports the two compression methods used in practice: stored (0) and
  * deflate (8). ZIP64 archives are rejected with a clear error (`.mcpb` bundles
  * are small and never need it). Any trailing bytes after the End Of Central
- * Directory record — e.g. a native PKCS#7 signature block — are ignored, since
+ * Directory record (e.g. a native PKCS#7 signature block) are ignored, since
  * extraction is driven entirely by the central directory.
  */
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";