@cyanmycelium/mcp-broker 0.4.0 → 1.2.0

package/dist/index.js

@@ -1,15 +1,3 @@
-export { WsTunnel } from "./ws.tunnel.js";
-export { WsTunnelBuilder } from "./ws.tunnel.builder.js";
-export { StdioUpstream } from "./stdio.upstream.js";
-export { RemoteUpstream } from "./remote.upstream.js";
-// `.mcpb` bundle loading — verifies + unpacks a bundle into a stdio upstream.
-export { loadMcpbBundle } from "./mcpb.loader.js";
-export { unzipMcpb } from "./mcpb.unzip.js";
-// Broker introspection — tier 1.
-export { BrokerInfoBehavior, BrokerProvidersBehavior, startBrokerServer, BROKER_PROVIDER_NAME } from "./broker/index.js";
-export { brokerGrammarKey, iterAvailableBrokerGrammars, iterBrokerGrammarsFrom, loadBrokerGrammar } from "./broker/index.js";
-export { VERSION, PACKAGE_NAME } from "./version.js";
-// 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 { AuthError, BROKER_PROVIDER_NAME, BrokerInfoBehavior, BrokerProvidersBehavior, ConfigPolicyEngine, ConfiguredCapabilityClassifier, DEFAULT_CONFIG_FILENAME, DefaultSlotResourceResolver, HttpAuthGuard, JwtSubjectMapper, JwtTokenValidator, PACKAGE_NAME, RemoteUpstream, ResourcePath, ResourcePathPattern, SharedSecretProviderAuthenticator, StdioUpstream, SubjectMappingError, VERSION, WsTunnel, WsTunnelBuilder, authorizationWithEngine, brokerGrammarKey, buildJwtAuth, buildResourceMetadata, compileAuthorizationPolicy, hasAuthorizationPolicies, iterAvailableBrokerGrammars, iterBrokerGrammarsFrom, loadBrokerConfig, loadBrokerGrammar, loadMcpbBundle, normalizeProviderAuthentication, providerMayPublish, scopesOf, startBrokerServer, unzipMcpb, validateCapability } from './chunk-FTDKH2C4.js';
+//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAItD,8EAA8E;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,iCAAiC;AACjC,OAAO,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEzH,OAAO,EAAE,gBAAgB,EAAE,2BAA2B,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAG7H,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAErD,2EAA2E;AAC3E,6DAA6D;AAC7D,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cyanmycelium/mcp-broker",
-    "version": "0.4.0",
+    "version": "1.2.0",
     "description": "WebSocket-based Model Context Protocol broker. Aggregates multiple MCP providers behind a single endpoint with stdio, SSE, and Streamable HTTP client transports.",
     "type": "module",
     "license": "Apache-2.0",
@@ -8,7 +8,7 @@
     "repository": {
         "type": "git",
         "url": "git+https://github.com/pandaGaume/mcp-broker.git",
-        "directory": "node"
+        "directory": "node/packages/broker"
     },
     "homepage": "https://github.com/pandaGaume/mcp-broker#readme",
     "bugs": {
@@ -36,6 +36,7 @@
         "dist",
         "src",
         "scripts",
+        "web",
         ".mcp-broker.example",
         "LICENSE",
         "README.md"
@@ -48,15 +49,17 @@
         }
     },
     "scripts": {
-        "build": "npm run clean && npm run compile && npm run copy:assets",
-        "clean": "rimraf dist tsconfig.build.tsbuildinfo",
-        "compile": "tsc -b tsconfig.build.json",
+        "build": "tsup && npm run copy:assets",
+        "clean": "rimraf dist",
         "copy:assets": "node scripts/copy-assets.mjs",
-        "watch": "tsc -b tsconfig.build.json -w",
+        "watch": "tsup --watch",
+        "typecheck": "tsc -p tsconfig.json --noEmit",
         "start": "node dist/bin.js",
         "pack:mcpb": "npm run build && node scripts/pack-mcpb.mjs",
         "test": "vitest run",
         "test:watch": "vitest",
+        "demo:oauth": "npm run build && node web/demos/oauth-lab/server/start.mjs",
+        "demo:oauth:smoke": "node web/demos/oauth-lab/server/smoke-test.mjs",
         "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\"",
         "lint:fix": "eslint \"src/**/*.ts\" \"tests/**/*.ts\" --fix",
         "format": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",
@@ -65,11 +68,13 @@
         "prepublishOnly": "npm run lint && npm run build && npm test"
     },
     "dependencies": {
-        "@cyanmycelium/mcp-core": "^0.3.0",
+        "@cyanmycelium/mcp-core": "^0.7.0",
+        "jose": "^6.2.3",
         "open": "^11.0.0",
         "ws": "^8.18.0"
     },
     "devDependencies": {
+        "@cyanmycelium/mcp-broker-provider": "^0.1.0",
         "@types/node": "^20.11.0",
         "@types/ws": "^8.5.0",
         "@typescript-eslint/eslint-plugin": "^7.0.0",
@@ -81,7 +86,8 @@
         "rimraf": "~6.0.1",
         "selfsigned": "^2.4.1",
         "tslib": "^2.8.1",
+        "tsup": "^8.5.1",
         "typescript": "^5.4.0",
-        "vitest": "^1.6.0"
+        "vitest": "^4.1.9"
     }
 }

package/scripts/copy-assets.mjs

@@ -1,10 +1,15 @@
 /**
  * Copies non-TypeScript assets from `src/` to `dist/`.
  *
- * tsc does not copy non-`.ts` files (e.g. `.json`, `.proto`, `.txt`) to the
- * output directory. This script walks the known asset directories and mirrors
- * them under `dist/`, preserving their relative layout so runtime
- * `fileURLToPath(import.meta.url)`-based resolution keeps working.
+ * A bundler emits no `.json`, and it also **flattens the module tree**: code
+ * that lived in `src/broker/` ends up in a bundle at the root of `dist/`. Any
+ * asset resolved at runtime from `fileURLToPath(import.meta.url)` must therefore
+ * be copied next to the bundle, not to a path mirroring the source layout.
+ *
+ * That is why each entry below is an explicit `from → to` pair rather than a
+ * single relative path: the two sides genuinely differ, and assuming otherwise
+ * builds a `dist` that passes every test (they run against `src`) and fails
+ * the moment the published artifact is executed.
  *
  * Usage (called from npm scripts):
  *   node scripts/copy-assets.mjs
@@ -18,17 +23,18 @@ const here = dirname(fileURLToPath(import.meta.url));
 const root = join(here, "..");
 
 const assets = [
-    // Broker grammar resources (loaded at runtime by broker.grammars.ts)
-    "broker/grammars",
+    // Broker grammars, read at runtime by broker.grammars.ts relative to its own
+    // module. Bundled, that module sits at the root of `dist`.
+    { from: "broker/grammars", to: "grammars" },
 ];
 
-for (const rel of assets) {
-    const src = join(root, "src", rel);
-    const dst = join(root, "dist", rel);
+for (const { from, to } of assets) {
+    const src = join(root, "src", from);
+    const dst = join(root, "dist", to);
     if (!existsSync(src)) {
         console.warn(`[copy-assets] skipping missing source: ${src}`);
         continue;
     }
     cpSync(src, dst, { recursive: true });
-    console.log(`[copy-assets] copied ${rel}`);
+    console.log(`[copy-assets] copied ${from} -> dist/${to}`);
 }

package/scripts/gen-cert.mjs

@@ -2,12 +2,12 @@
  * Generates a self-signed TLS certificate for local development.
  *
  * Usage (from the `node/` directory):
- *   npm run gen-cert                  — writes to ../certs/ (repo root)
- *   npm run gen-cert -- --out <dir>   — writes to a custom directory
+ *   npm run gen-cert                 , writes to ../certs/ (repo root)
+ *   npm run gen-cert -- --out <dir>  , writes to a custom directory
  *
  * Outputs:
- *   <outDir>/cert.pem  — TLS certificate (pass as MCP_BROKER_TLS_CERT)
- *   <outDir>/key.pem   — Private key    (pass as MCP_BROKER_TLS_KEY)
+ *   <outDir>/cert.pem , TLS certificate (pass as MCP_BROKER_TLS_CERT)
+ *   <outDir>/key.pem  , Private key    (pass as MCP_BROKER_TLS_KEY)
  *
  * The certificate covers: localhost, 127.0.0.1, ::1
  * Validity: 365 days  |  Key: RSA 2048-bit
@@ -20,7 +20,7 @@ import { mkdirSync, writeFileSync } from "fs";
 import { resolve, join } from "path";
 import { createRequire } from "module";
 
-// selfsigned is a CJS module — use createRequire for a clean import from ESM.
+// selfsigned is a CJS module, use createRequire for a clean import from ESM.
 const require = createRequire(import.meta.url);
 const selfsigned = require("selfsigned");
 

package/scripts/pack-mcpb.mjs

@@ -12,7 +12,7 @@
  *   ├── node_modules/     ← npm install --omit=dev (the host does not install)
  *   └── dist/             ← compiled broker
  *
- * Requires `dist/` to exist — run `npm run build` first (the `pack:mcpb`
+ * Requires `dist/` to exist, run `npm run build` first (the `pack:mcpb`
  * npm script chains it).
  *
  * Usage (from node/):
@@ -35,13 +35,13 @@ function run(command, args, cwd) {
     }
 }
 
-// ── Read package metadata — single source of truth for version + deps ───────
+// ── Read package metadata, single source of truth for version + deps ───────
 const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
 const { version, dependencies } = pkg;
 
 // ── Preconditions ───────────────────────────────────────────────────────────
 if (!existsSync(join(root, "dist", "bin.js"))) {
-    console.error("[pack-mcpb] dist/bin.js not found — run `npm run build` first.");
+    console.error("[pack-mcpb] dist/bin.js not found, run `npm run build` first.");
     process.exit(1);
 }
 
@@ -55,7 +55,7 @@ mkdirSync(stage, { recursive: true });
 cpSync(join(root, "dist"), join(stage, "dist"), { recursive: true });
 console.log("[pack-mcpb] copied dist/");
 
-// ── Production package.json — drives the bundled npm install ────────────────
+// ── Production package.json, drives the bundled npm install ────────────────
 // type=module is required so Node treats the compiled .js as ESM.
 writeFileSync(
     join(stage, "package.json"),
@@ -81,4 +81,4 @@ console.log("[pack-mcpb] running mcpb pack …");
 run("npx", ["--yes", "@anthropic-ai/mcpb@2", "pack", stage, output]);
 
 const sizeMb = (statSync(output).size / 1024 / 1024).toFixed(2);
-console.log(`[pack-mcpb] done — ${output} (${sizeMb} MB)`);
+console.log(`[pack-mcpb] done, ${output} (${sizeMb} MB)`);

package/scripts/sign-bundle.mjs

@@ -1,22 +1,22 @@
 /**
- * Signs `.mcpb` bundles for the broker's bundle loader — built-ins only.
+ * Signs `.mcpb` bundles for the broker's bundle loader, built-ins only.
  *
  * The broker verifies a **detached signature** of a `.mcpb` file against a
  * trusted public key (see `src/mcpb.loader.ts`). This script produces that
- * signature using `node:crypto` only — no dependency on OpenSSL or the
+ * signature using `node:crypto` only: no dependency on OpenSSL or the
  * `@anthropic-ai/mcpb` CLI.
  *
  * Usage (from the `node/` directory):
  *
  *   node scripts/sign-bundle.mjs keygen [outDir]
  *       Generates an Ed25519 key pair:
- *         <outDir>/mcpb-signing.key.pem  — private key (keep secret)
- *         <outDir>/mcpb-signing.pub.pem  — public key  (point `publicKey` at this)
+ *         <outDir>/mcpb-signing.key.pem , private key (keep secret)
+ *         <outDir>/mcpb-signing.pub.pem , public key  (point `publicKey` at this)
  *       outDir defaults to the current directory.
  *
  *   node scripts/sign-bundle.mjs sign <bundle.mcpb> <privateKey.pem> [signaturePath]
  *       Writes the detached signature. signaturePath defaults to
- *       `<bundle.mcpb>.sig` — the path the broker looks for by default.
+ *       `<bundle.mcpb>.sig`: the path the broker looks for by default.
  */
 import { generateKeyPairSync, createPrivateKey, sign } from "node:crypto";
 import { readFileSync, writeFileSync } from "node:fs";
@@ -57,5 +57,5 @@ if (command === "keygen") {
     writeFileSync(sigPath, signature);
     console.log(`[sign-bundle] signature (${keyType}) → ${sigPath}`);
 } else {
-    fail('unknown command — use "keygen" or "sign". See the file header for usage.');
+    fail('unknown command, use "keygen" or "sign". See the file header for usage.');
 }

package/src/auth/auth.config.ts

@@ -0,0 +1,98 @@
+import { JwtTokenValidator } from "./jwt.validator";
+import type { AggregateScopeFilter, IResolvedAuth } from "./auth.types";
+import { compileAuthorizationPolicy, DefaultSlotResourceResolver, hasAuthorizationPolicies, type IAuthorizationPolicyConfig } from "../authorization/index";
+
+/**
+ * High-level options for the default JWT/JWKS resource-server setup. Mirrors the
+ * `auth` block of the broker JSON config and is turned into a fully
+ * {@link IResolvedAuth} (with a {@link JwtTokenValidator}) by {@link buildJwtAuth}.
+ */
+export interface IJwtAuthOptions extends IAuthorizationPolicyConfig {
+    /** Public origin the broker is reached at (e.g. `https://mcp.example.com`). */
+    publicBaseUrl: string;
+    /** Authorization server issuer URL(s) advertised in the PRM. At least one. */
+    authorizationServers: string[];
+    /** URL of the authorization server's JWKS document. */
+    jwksUri: string;
+    /** Expected token issuer(s). Defaults to the sole authorization server. */
+    issuer?: string | string[];
+    /** Scopes advertised in the PRM `scopes_supported`. */
+    scopesSupported?: string[];
+    /** Baseline scope(s) required to reach any slot. */
+    requiredScopes?: string[];
+    /** Per-slot required-scope overrides (e.g. an admin scope for `_broker`). */
+    perSlotScopes?: Record<string, string[]>;
+    /**
+     * Per-provider scope requirements for the `_all` aggregate. A caller sees a
+     * provider in `_all` only if it holds at least one of the listed scopes.
+     * Providers not listed here stay visible to every authenticated caller.
+     * Turned into an {@link AggregateScopeFilter} automatically.
+     */
+    providerScopes?: Record<string, string[]>;
+    /** Leeway in seconds for token `exp`/`nbf` checks. */
+    clockToleranceSec?: number;
+}
+
+/** Builds the default aggregate filter from a per-provider scope map. */
+function makeProviderScopeFilter(providerScopes: Record<string, string[]>): AggregateScopeFilter {
+    return (principal, providerName) => {
+        const required = providerScopes[providerName];
+        if (!required || required.length === 0) return true; // unlisted ⇒ visible to all
+        return required.some((scope) => principal.scopes.has(scope));
+    };
+}
+
+/** Removes a single trailing slash so resource URIs concatenate cleanly. */
+function stripTrailingSlash(url: string): string {
+    return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+
+/**
+ * Builds an {@link IResolvedAuth} backed by a {@link JwtTokenValidator}. Validates
+ * the required inputs up front and throws a descriptive error on misconfig, so
+ * an operator sees the problem at boot rather than as opaque `401`s later.
+ */
+export function buildJwtAuth(options: IJwtAuthOptions): IResolvedAuth {
+    if (!options.publicBaseUrl) {
+        throw new Error("auth: publicBaseUrl is required.");
+    }
+    if (!options.authorizationServers || options.authorizationServers.length === 0) {
+        throw new Error("auth: at least one authorizationServers entry is required.");
+    }
+    if (!options.jwksUri) {
+        throw new Error("auth: jwksUri is required.");
+    }
+
+    const publicBaseUrl = stripTrailingSlash(options.publicBaseUrl);
+    const issuer = options.issuer ?? (options.authorizationServers.length === 1 ? options.authorizationServers[0] : undefined);
+
+    const validator = new JwtTokenValidator({
+        jwksUri: options.jwksUri,
+        issuer,
+        clockToleranceSec: options.clockToleranceSec,
+    });
+
+    const resolved: IResolvedAuth = {
+        publicBaseUrl,
+        authorizationServers: options.authorizationServers,
+        validator,
+    };
+    if (options.scopesSupported) resolved.scopesSupported = options.scopesSupported;
+    if (options.requiredScopes) resolved.requiredScopes = options.requiredScopes;
+    if (options.perSlotScopes) resolved.perSlotScopes = options.perSlotScopes;
+    if (options.providerScopes && Object.keys(options.providerScopes).length > 0) {
+        console.warn("[mcp-broker] auth.providerScopes is deprecated; migrate to roles and hierarchical assignments.");
+        resolved.aggregateScopeFilter = makeProviderScopeFilter(options.providerScopes);
+    }
+    if (options.slotResources && Object.keys(options.slotResources).length > 0) {
+        resolved.slotResourceResolver = new DefaultSlotResourceResolver(options.slotResources);
+    }
+    if (hasAuthorizationPolicies(options)) {
+        resolved.authorization = compileAuthorizationPolicy(options);
+        resolved.slotResourceResolver = resolved.authorization.slotResourceResolver;
+    }
+    return resolved;
+}
+
+/** @deprecated Use {@link IJwtAuthOptions}. */
+export type JwtAuthOptions = IJwtAuthOptions;

package/src/auth/auth.types.ts

@@ -0,0 +1,120 @@
+/**
+ * Core contracts for the broker's OAuth 2.1 **resource server** layer.
+ *
+ * The broker never acts as an authorization server: it only validates the
+ * access tokens minted by an external AS and advertises that AS through
+ * Protected Resource Metadata (RFC 9728). These types are the seam every other
+ * auth module builds on, so a host can drop in a custom {@link ITokenValidator}
+ * (e.g. RFC 7662 introspection) without touching the enforcement code.
+ *
+ * Everything the MCP specification itself defines comes from `mcp-core` and is
+ * re-exported here under the broker's historical names: the claim shape, the
+ * validator seam, the error carrying a challenge. What stays broker-owned is
+ * what the spec does not define, namely a multi-slot resource server whose
+ * principals feed a hierarchical policy engine.
+ */
+import { McpAuthError, scopesOf as mcpScopesOf, type IAccessTokenClaims, type IMcpPrincipal, type ITokenValidator } from "@cyanmycelium/mcp-core";
+import type { IAuthorizationSubject, IPolicyAuthorization, ISlotResourceResolver } from "../authorization/index";
+
+export type { IAccessTokenClaims, ITokenValidator } from "@cyanmycelium/mcp-core";
+
+/** OAuth 2.1 error codes the broker emits in `WWW-Authenticate` challenges. */
+export type AuthErrorCode = import("@cyanmycelium/mcp-core").McpAuthErrorCode;
+
+/**
+ * A thrown authorization failure carrying the HTTP status and OAuth error code
+ * the enforcement point should surface. `scope` is set for `insufficient_scope`
+ * challenges to advertise the scope(s) the resource requires.
+ *
+ * The broker's own name for `mcp-core`'s `McpAuthError`, kept so `instanceof`
+ * checks and the published API survive the consolidation. There is one class at
+ * runtime, so an error thrown by `mcp-core` is caught by the broker and the
+ * other way round.
+ */
+export const AuthError = McpAuthError;
+export type AuthError = McpAuthError;
+
+/**
+ * The authenticated caller, produced once a token passes validation and the
+ * required scopes are satisfied. Threaded through the request so downstream
+ * components (e.g. the `_all` aggregate) can make scope-aware decisions.
+ *
+ * Extends `mcp-core`'s principal with the subject the policy engine reasons
+ * about, which the specification says nothing about and which therefore stays
+ * here.
+ */
+export interface IPrincipal extends IMcpPrincipal {
+    readonly claims: IAccessTokenClaims;
+    readonly scopes: ReadonlySet<string>;
+    /** Subjects derived exclusively from validated token claims. */
+    readonly subject?: IAuthorizationSubject;
+}
+
+/**
+ * Decides, per authenticated caller, whether a given provider is visible in the
+ * `_all` aggregate. This is the content-confidentiality enforcement point: a
+ * client only sees (and can call) tools/prompts from providers it is authorized
+ * for. Return `true` to include the provider for this principal.
+ */
+export type AggregateScopeFilter = (principal: IPrincipal, providerName: string) => boolean;
+
+/**
+ * A fully resolved authorization configuration, ready for the enforcement
+ * layer. Built either from JSON config (via `buildJwtAuth`) or supplied
+ * directly by an embedder with a custom {@link ITokenValidator}.
+ */
+export interface IResolvedAuth {
+    /**
+     * Public origin the broker is reached at, used to build canonical resource
+     * URIs and metadata URLs. No trailing slash (e.g. `https://mcp.example.com`).
+     */
+    publicBaseUrl: string;
+    /** One or more authorization server issuer URLs, advertised in the PRM. */
+    authorizationServers: string[];
+    /** Optional list of scopes advertised in the PRM `scopes_supported`. */
+    scopesSupported?: string[];
+    /** The token validator (JWKS-backed by default). */
+    validator: ITokenValidator;
+    /** Baseline scope(s) required to reach any slot. Empty ⇒ any valid token. */
+    requiredScopes?: string[];
+    /** Per-slot required-scope overrides (e.g. an admin scope for `_broker`). */
+    perSlotScopes?: Record<string, string[]>;
+    /**
+     * Per-caller filter for the `_all` aggregate. When set, a client's view of
+     * `_all` is narrowed to the providers this returns `true` for. When absent,
+     * every authenticated caller sees the full aggregate.
+     */
+    aggregateScopeFilter?: AggregateScopeFilter;
+    /** Compiled hierarchical policy runtime, absent for legacy OAuth behavior. */
+    authorization?: IPolicyAuthorization;
+    /** Optional resolver usable for provider namespace checks without policies. */
+    slotResourceResolver?: ISlotResourceResolver;
+}
+
+/**
+ * Extracts the effective set of granted scopes from token claims.
+ *
+ * A deliberate superset of `mcp-core`'s: OAuth 2.1 only defines the
+ * space-delimited `scope` string, which is what the spec-level helper reads,
+ * but several authorization servers emit an array-form `scopes` claim instead.
+ * Dropping that here would silently strip every scope for those deployments, so
+ * the two are unioned. The `scope` half is parsed by `mcp-core` rather than
+ * re-implemented.
+ */
+export function scopesOf(claims: IAccessTokenClaims): Set<string> {
+    const set = new Set<string>(mcpScopesOf(claims));
+    const arrayForm: unknown = claims["scopes"];
+    if (Array.isArray(arrayForm)) {
+        for (const scope of arrayForm) if (typeof scope === "string" && scope) set.add(scope);
+    }
+    return set;
+}
+
+/** @deprecated Use {@link IAccessTokenClaims}. */
+export type AccessTokenClaims = IAccessTokenClaims;
+/** @deprecated Use {@link ITokenValidator}. */
+export type TokenValidator = ITokenValidator;
+/** @deprecated Use {@link IPrincipal}. */
+export type Principal = IPrincipal;
+/** @deprecated Use {@link IResolvedAuth}. */
+export type ResolvedAuth = IResolvedAuth;

package/src/auth/http.auth.ts

@@ -0,0 +1,128 @@
+import type { IncomingMessage, ServerResponse } from "http";
+import { bearerToken, buildChallengeHeader, PROTECTED_RESOURCE_METADATA_PREFIX } from "@cyanmycelium/mcp-core";
+import { AuthError, scopesOf, type IPrincipal, type IResolvedAuth } from "./auth.types";
+import { buildResourceMetadata, type IProtectedResourceMetadata } from "./resource.metadata";
+import { SubjectMappingError } from "../authorization/index";
+
+/**
+ * Well-known prefix under which per-slot Protected Resource Metadata is served.
+ *
+ * Carries a trailing slash because every use here splits a slot off it, while
+ * `mcp-core` exports the bare RFC 9728 prefix.
+ */
+const PRM_PREFIX = `${PROTECTED_RESOURCE_METADATA_PREFIX}/`;
+
+/**
+ * The HTTP enforcement point for the resource-server layer. Wraps a
+ * {@link IResolvedAuth} plus the configured `/mcp` path suffix and turns it into
+ * the three operations the transport needs: serve Protected Resource Metadata,
+ * authorize a request, and write an RFC 9728 `401`/`403` challenge.
+ *
+ * A slot's **canonical resource URI** is `<publicBaseUrl>/<slot>/<mcp>` and is
+ * used uniformly across all of that slot's HTTP endpoints (`/mcp`, `/sse`,
+ * `/messages`) so a single token audience covers the whole slot.
+ */
+export class HttpAuthGuard {
+    private readonly _auth: IResolvedAuth;
+    /** The `/mcp` suffix without a leading slash, e.g. `"mcp"`. */
+    private readonly _mcpSuffix: string;
+
+    constructor(auth: IResolvedAuth, mcpSuffix: string) {
+        this._auth = auth;
+        this._mcpSuffix = mcpSuffix.replace(/^\//, "");
+    }
+
+    /** Canonical resource identifier for a slot (RFC 8707 §2). */
+    resourceFor(slot: string): string {
+        return `${this._auth.publicBaseUrl}/${encodeURIComponent(slot)}/${this._mcpSuffix}`;
+    }
+
+    /** RFC 9728 metadata URL for a slot, advertised in the `401` challenge. */
+    metadataUrlFor(slot: string): string {
+        return `${this._auth.publicBaseUrl}${PRM_PREFIX}${encodeURIComponent(slot)}/${this._mcpSuffix}`;
+    }
+
+    /** Required scope(s) for a slot: per-slot override, else the baseline. */
+    requiredScopesFor(slot: string): string[] {
+        return this._auth.perSlotScopes?.[slot] ?? this._auth.requiredScopes ?? [];
+    }
+
+    /** The RFC 9728 metadata document for a slot. */
+    metadataFor(slot: string): IProtectedResourceMetadata {
+        return buildResourceMetadata({
+            resource: this.resourceFor(slot),
+            authorizationServers: this._auth.authorizationServers,
+            scopesSupported: this._auth.scopesSupported,
+        });
+    }
+
+    /**
+     * If `rawUrl` is a Protected Resource Metadata request
+     * (`/.well-known/oauth-protected-resource/<slot>/<mcp>`), returns the slot;
+     * otherwise `null`.
+     */
+    matchMetadataRequest(rawUrl: string): string | null {
+        if (!rawUrl.startsWith(PRM_PREFIX)) return null;
+        const parts = rawUrl.slice(PRM_PREFIX.length).split("/").filter(Boolean);
+        if (parts.length !== 2 || parts[1] !== this._mcpSuffix) return null;
+        return decodeURIComponent(parts[0]);
+    }
+
+    /**
+     * Validates the request's bearer token against the slot's canonical resource
+     * and enforces the slot's required scopes. Resolves to the {@link IPrincipal}
+     * on success; rejects with an {@link AuthError} (`401` missing/invalid token,
+     * `403` insufficient scope) otherwise.
+     */
+    async authorize(req: IncomingMessage, slot: string): Promise<IPrincipal> {
+        const token = bearerToken(req.headers["authorization"]);
+        if (!token) {
+            throw new AuthError(401, "invalid_token", "Missing bearer token");
+        }
+
+        const claims = await this._auth.validator.validate(token, this.resourceFor(slot));
+        const scopes = scopesOf(claims);
+
+        const required = this.requiredScopesFor(slot);
+        const missing = required.filter((s) => !scopes.has(s));
+        if (missing.length > 0) {
+            throw new AuthError(403, "insufficient_scope", `Missing required scope(s): ${missing.join(" ")}`, required.join(" "));
+        }
+
+        let subject: IPrincipal["subject"];
+        try {
+            subject = this._auth.authorization?.subjectMapper.map(claims);
+        } catch (error) {
+            if (error instanceof SubjectMappingError) {
+                throw new AuthError(403, "insufficient_scope", "Malformed configured JWT subject claim");
+            }
+            throw error;
+        }
+
+        return subject ? { claims, scopes, subject } : { claims, scopes };
+    }
+
+    /**
+     * Builds the RFC 9728 §5.1 `WWW-Authenticate` header value for a challenge.
+     * Always points the client at the slot's metadata URL so it can discover the
+     * authorization server and retry. Shared by the HTTP and WebSocket paths.
+     */
+    challengeHeader(slot: string, err: AuthError): string {
+        return buildChallengeHeader({
+            resourceMetadata: this.metadataUrlFor(slot),
+            error: err.code,
+            errorDescription: err.description,
+            scope: err.scope,
+        });
+    }
+
+    /**
+     * Writes an RFC 9728 §5.1 `WWW-Authenticate` challenge and the matching
+     * status to an HTTP response.
+     */
+    writeChallenge(res: ServerResponse, slot: string, err: AuthError): void {
+        res.setHeader("WWW-Authenticate", this.challengeHeader(slot, err));
+        res.writeHead(err.status, { "Content-Type": "application/json; charset=utf-8" });
+        res.end(JSON.stringify({ error: err.code, error_description: err.description }));
+    }
+}

package/src/auth/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Barrel for the broker's OAuth 2.1 resource-server layer. See the individual
+ * modules for details; the transport wires these up in `ws.tunnel.ts`.
+ */
+export { AuthError, scopesOf } from "./auth.types";
+export type {
+    IAccessTokenClaims,
+    ITokenValidator,
+    AuthErrorCode,
+    IPrincipal,
+    IResolvedAuth,
+    AggregateScopeFilter,
+    AccessTokenClaims,
+    TokenValidator,
+    Principal,
+    ResolvedAuth,
+} from "./auth.types";
+export { JwtTokenValidator } from "./jwt.validator";
+export type { IJwtValidatorOptions, JwtValidatorOptions } from "./jwt.validator";
+export { buildResourceMetadata } from "./resource.metadata";
+export type { IProtectedResourceMetadata, ProtectedResourceMetadata } from "./resource.metadata";
+export { HttpAuthGuard } from "./http.auth";
+export { buildJwtAuth } from "./auth.config";
+export type { IJwtAuthOptions, JwtAuthOptions } from "./auth.config";
+export { SharedSecretProviderAuthenticator } from "./provider.auth";
+export { normalizeProviderAuthentication, providerMayPublish } from "./provider.auth";
+export type {
+    IProviderAuthenticator,
+    IProviderPrincipal,
+    ProviderAuthenticationResult,
+    ProviderAuthenticator,
+    ProviderAuthenticatorReturn,
+    ProviderPrincipal,
+} from "./provider.auth";