@cyanmycelium/mcp-broker 1.0.1 → 1.2.0

package/src/authorization/slot.resource.ts

@@ -1,4 +1,4 @@
-import { ResourcePath } from "./resource.path.js";
+import { ResourcePath } from "./resource.path";
 
 export interface ISlotResourceResolver {
     resolve(slot: string): ResourcePath | undefined;

package/src/authorization/subject.mapper.ts

@@ -1,4 +1,4 @@
-import type { IAuthorizationSubject, ISubjectMappingConfig } from "./policy.types.js";
+import type { IAuthorizationSubject, ISubjectMappingConfig } from "./policy.types";
 
 export interface ISubjectMapper {
     map(claims: Readonly<Record<string, unknown>>): IAuthorizationSubject;

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).
  */
@@ -92,7 +94,7 @@ 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;
@@ -125,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;
@@ -149,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
@@ -254,7 +284,7 @@ async function main(): Promise<void> {
 
     // ── 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.
+    // present the shared secret, closes off slot occupation by strangers.
     const providerSecret = process.env["MCP_BROKER_PROVIDER_SECRET"];
     if (providerSecret) {
         builder.withProviderSecret(providerSecret);
@@ -298,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,6 +1,6 @@
 import { McpAdapterBase, McpToolResults } from "@cyanmycelium/mcp-core";
 import type { McpResourceContent, McpToolResult } from "@cyanmycelium/mcp-core";
-import type { IBrokerContext } 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";

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 { IBrokerContext, IBrokerProviderInfo } 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";

package/src/broker/aggregate/aggregate.catalog.ts

@@ -1,5 +1,5 @@
 /**
- * AggregateCatalog — merges the tool and prompt catalogs of several providers
+ * AggregateCatalog, merges the tool and prompt catalogs of several providers
  * into a single namespaced view, and routes aggregated names back to their
  * origin provider.
  *

package/src/broker/aggregate/aggregate.server.ts

@@ -1,6 +1,6 @@
 import type { IMessageTransport } from "@cyanmycelium/mcp-core";
-import type { IInternalClient } from "../../ws.tunnel.js";
-import type { AggregateScopeFilter, IPrincipal } from "../../auth/index.js";
+import type { IInternalClient } from "../../ws/ws.interfaces";
+import type { AggregateScopeFilter, IPrincipal } from "../../auth/index";
 import {
     SubjectMappingError,
     makeAuthorizationAuditEvent,
@@ -9,9 +9,9 @@ import {
     type IAuthorizationSubject,
     type IMcpOperation,
     type IPolicyAuthorization,
-} from "../../authorization/index.js";
-import { AggregateCatalog } from "./aggregate.catalog.js";
-import { ProviderClientSession } from "./provider.client.session.js";
+} from "../../authorization/index";
+import { AggregateCatalog } from "./aggregate.catalog";
+import { ProviderClientSession } from "./provider.client.session";
 
 /** MCP protocol version advertised by the aggregate server. */
 const PROTOCOL_VERSION = "2024-11-05";
@@ -232,7 +232,7 @@ export class AggregateServer implements IMessageTransport {
             return;
         }
         const id = msg.id;
-        if (id == null) return; // client notification — nothing to answer
+        if (id == null) return; // client notification: nothing to answer
 
         switch (msg.method) {
             case "initialize":
@@ -275,7 +275,7 @@ export class AggregateServer implements IMessageTransport {
     private async _route(id: string | number, params: unknown, kind: "tool" | "prompt", principal: IPrincipal | null): Promise<void> {
         const p = (params ?? {}) as ICallParams;
         const route = p.name ? (kind === "tool" ? this._catalog.resolveTool(p.name) : this._catalog.resolvePrompt(p.name)) : undefined;
-        // Treat a provider the caller may not see as if it did not exist — do not
+        // Treat a provider the caller may not see as if it did not exist, do not
         // leak its presence through a distinct "forbidden" error.
         const operation: IMcpOperation | undefined = route
             ? kind === "tool"

package/src/broker/aggregate/provider.client.session.ts

@@ -1,5 +1,5 @@
-import type { IInternalClient } from "../../ws.tunnel.js";
-import type { ICatalogTool, ICatalogPrompt } from "./aggregate.catalog.js";
+import type { IInternalClient } from "../../ws/ws.interfaces";
+import type { ICatalogTool, ICatalogPrompt } from "./aggregate.catalog";
 
 /** MCP protocol version the aggregate sessions negotiate with sub-providers. */
 const PROTOCOL_VERSION = "2024-11-05";

package/src/broker/behaviors/broker.behavior.info.ts

@@ -1,8 +1,8 @@
 import { McpBehavior } from "@cyanmycelium/mcp-core";
 import type { McpResource, McpTool } from "@cyanmycelium/mcp-core";
-import { BROKER_INFO_URI, BrokerInfoAdapter } from "../adapters/broker.adapter.info.js";
-import { brokerBaselineResourceDescription, brokerBaselineResourceName, brokerBaselineToolDescription } from "../broker.grammars.js";
-import type { IBrokerContext } from "../broker.context.js";
+import { BROKER_INFO_URI, BrokerInfoAdapter } from "../adapters/broker.adapter.info";
+import { brokerBaselineResourceDescription, brokerBaselineResourceName, brokerBaselineToolDescription } from "../broker.grammars";
+import type { IBrokerContext } from "../broker.context";
 
 /**
  * Exposes basic broker identity (name, version, uptime, listening config) as

package/src/broker/behaviors/broker.behavior.providers.ts

@@ -1,6 +1,6 @@
 import { McpBehavior } from "@cyanmycelium/mcp-core";
 import type { McpResource, McpResourceTemplate, McpTool } from "@cyanmycelium/mcp-core";
-import { BrokerProvidersAdapter, PROVIDERS_URI, PROVIDER_URI_TEMPLATE } from "../adapters/broker.adapter.providers.js";
+import { BrokerProvidersAdapter, PROVIDERS_URI, PROVIDER_URI_TEMPLATE } from "../adapters/broker.adapter.providers";
 import {
     brokerBaselinePropertyDescription,
     brokerBaselineResourceDescription,
@@ -8,15 +8,15 @@ import {
     brokerBaselineResourceTemplateDescription,
     brokerBaselineResourceTemplateName,
     brokerBaselineToolDescription,
-} from "../broker.grammars.js";
-import type { IBrokerContext } from "../broker.context.js";
+} from "../broker.grammars";
+import type { IBrokerContext } from "../broker.context";
 
 /**
  * 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.
+ * - `providers_list`: every slot (including disconnected ones).
+ * - `provider_status({ name })`, detail on one slot.
  *
  * Plus matching resources at `broker://providers` and `broker://providers/<name>`.
  */

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
 // ---------------------------------------------------------------------------
 
 /**
@@ -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,7 +132,7 @@ 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 IBrokerGrammarEntry {
     userAgent: BrokerUserAgent;
@@ -186,7 +186,7 @@ export function* iterBrokerGrammarsFrom(grammarsDir: string): Generator<IBrokerG
  * 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<IBrokerGrammarEntry> {
     yield* iterBrokerGrammarsFrom(GRAMMARS_DIR);
@@ -206,20 +206,20 @@ export type BrokerGrammarEntry = IBrokerGrammarEntry;
  * 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 { IBrokerContext } 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
@@ -44,7 +44,7 @@ export interface IStartBrokerServerOptions {
      * 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.
@@ -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.

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 { IStartBrokerServerOptions, 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 { IBrokerGrammarEntry, BrokerGrammarEntry, BrokerLocale, BrokerUserAgent } from "./broker.grammars.js";
-export type { IBrokerContext, IBrokerProviderInfo, 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,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import type { IAuthorizationPolicyConfig } from "./authorization/index.js";
+import type { IAuthorizationPolicyConfig } from "./authorization/index";
 
 export interface IBrokerAuthConfig extends IAuthorizationPolicyConfig {
     /** Master switch. Absent/`false` keeps the broker unauthenticated. */
@@ -67,6 +67,28 @@ export interface IBrokerConfig {
     /** 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`
@@ -184,12 +206,12 @@ 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 ILoadedBrokerConfig.baseDir} by the consumer.

package/src/index.ts

@@ -1,21 +1,21 @@
-export { WsTunnel } from "./ws.tunnel.js";
-export { WsTunnelBuilder } from "./ws.tunnel.builder.js";
-export type { IInternalClient, IWsTunnelOptions, IStaticMount, InternalClient, WsTunnelOptions, StaticMount } from "./ws.tunnel.js";
-export { StdioUpstream } from "./stdio.upstream.js";
-export type { IStdioUpstreamConfig, StdioUpstreamConfig } from "./stdio.upstream.js";
-export { RemoteUpstream } from "./remote.upstream.js";
-export type { IRemoteUpstreamConfig, RemoteUpstreamConfig } from "./remote.upstream.js";
-export type { IUpstream, 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 { IMcpbBundleConfig, 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 { IStartBrokerServerOptions, StartBrokerServerOptions } from "./broker/index.js";
-export { brokerGrammarKey, iterAvailableBrokerGrammars, iterBrokerGrammarsFrom, loadBrokerGrammar } 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,
@@ -26,9 +26,9 @@ export type {
     BrokerProviderTransport,
     BrokerLocale,
     BrokerUserAgent,
-} from "./broker/index.js";
+} from "./broker/index";
 
-export { VERSION, PACKAGE_NAME } from "./version.js";
+export { VERSION, PACKAGE_NAME } from "./version";
 
 // OAuth 2.1 resource-server authorization.
 export {
@@ -41,7 +41,7 @@ export {
     normalizeProviderAuthentication,
     providerMayPublish,
     SharedSecretProviderAuthenticator,
-} from "./auth/index.js";
+} from "./auth/index";
 export type {
     IAccessTokenClaims,
     ITokenValidator,
@@ -65,7 +65,7 @@ export type {
     ProviderAuthenticationResult,
     ProviderAuthenticatorReturn,
     ProviderPrincipal,
-} from "./auth/index.js";
+} from "./auth/index";
 
 // Hierarchical, domain-neutral authorization.
 export {
@@ -80,7 +80,7 @@ export {
     compileAuthorizationPolicy,
     hasAuthorizationPolicies,
     validateCapability,
-} from "./authorization/index.js";
+} from "./authorization/index";
 export type {
     IAuditContext,
     IAuthorizationAuditConfig,
@@ -119,9 +119,9 @@ export type {
     SlotResourceResolver,
     SubjectMapper,
     SubjectMappingConfig,
-} from "./authorization/index.js";
+} 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 { IBrokerAuthConfig, IBrokerConfig, ILoadedBrokerConfig, BrokerAuthConfig, BrokerConfig, LoadedBrokerConfig } 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}

@@ -5,14 +5,14 @@
  * 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
  *    `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,8 +22,8 @@ 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 { IStdioUpstreamConfig } 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 IMcpbBundleConfig {
@@ -85,7 +85,7 @@ function resolvePlaceholder(key: string, dirname: string, userConfig: IMcpbBundl
 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);
     });
@@ -122,7 +122,7 @@ export async function loadMcpbBundle(cfg: IMcpbBundleConfig, baseDir: string): P
             ["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: IMcpbBundleConfig, baseDir: string): P
         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: IMcpbBundleConfig, baseDir: string): P
         // ── 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?: 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: IMcpbBundleConfig, baseDir: string): P
         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,7 @@ export async function loadMcpbBundle(cfg: IMcpbBundleConfig, baseDir: string): P
             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;
     }
 }

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";