@cyanmycelium/mcp-broker 0.3.0 → 1.0.1

package/.mcp-broker.example/README.md

@@ -7,6 +7,11 @@ broker, then adapt to your needs:
 cp -r .mcp-broker.example .mcp-broker
 ```
 
+Property-by-property educational guides:
+
+- [English](CONFIGURATION-EN.md)
+- [Français](CONFIGURATION-FR.md)
+
 ## Layout
 
 ```

package/.mcp-broker.example/config.json

@@ -22,6 +22,92 @@
         ]
     },
 
+    "auth": {
+        "enabled": true,
+        "publicBaseUrl": "https://mcp.factory.local",
+        "authorizationServers": [
+            "https://identity.factory.local"
+        ],
+        "jwks": "https://identity.factory.local/.well-known/jwks.json",
+        "requiredScopes": ["mcp:call"],
+        "perSlotScopes": {
+            "_broker": ["broker:admin"]
+        },
+        "subjectMapping": {
+            "userClaim": "sub",
+            "groupClaims": ["groups"],
+            "clientClaim": "client_id"
+        },
+        "roles": {
+            "viewer": {
+                "capabilities": [
+                    "mcp.resources.read",
+                    "mcp.tools.list",
+                    "mcp.prompts.read"
+                ]
+            },
+            "maintenance": {
+                "inherits": ["viewer"],
+                "capabilities": [
+                    "mcp.tools.call",
+                    "mcp.tools.diagnose",
+                    "mcp.tools.configure-analysis"
+                ]
+            },
+            "operator": {
+                "inherits": ["viewer"],
+                "capabilities": ["mcp.tools.operate"]
+            },
+            "administrator": {
+                "capabilities": ["*"]
+            }
+        },
+        "assignments": [
+            {
+                "id": "maintenance-area-a",
+                "subject": "group:maintenance-area-a",
+                "role": "maintenance",
+                "resource": "/enterprise-a/site-paris/area-a/**"
+            },
+            {
+                "id": "energy-team",
+                "subject": "group:energy-team",
+                "role": "viewer",
+                "resource": "/enterprise-a/site-paris/**"
+            }
+        ],
+        "denies": [
+            {
+                "id": "protect-critical-furnace",
+                "subject": "group:maintenance-area-a",
+                "capabilities": [
+                    "mcp.tools.configure-analysis",
+                    "mcp.tools.operate"
+                ],
+                "resource": "/enterprise-a/site-paris/area-a/line-2/cell-4/critical-furnace"
+            }
+        ],
+        "slotResources": {
+            "spoony-00452": "/enterprise-a/site-paris/area-a/line-3/cell-2/motor-7",
+            "site-energy": "/enterprise-a/site-paris"
+        },
+        "toolCapabilities": {
+            "get_electrical_state": "mcp.resources.read",
+            "diagnose_motor": "mcp.tools.diagnose",
+            "reset_baseline": "mcp.tools.configure-analysis",
+            "start_motor": "mcp.tools.operate"
+        },
+        "providerToolCapabilities": {
+            "/enterprise-a/site-paris/area-a/**": {
+                "start_motor": "mcp.tools.operate"
+            }
+        },
+        "audit": {
+            "logAllowed": false
+        },
+        "providerSecret": "change-me"
+    },
+
     "stdioUpstreams": [
         {
             "name":    "fs",

package/README.md

@@ -96,6 +96,81 @@ Full reference (every field, defaults, recipes, grammar overrides): **[docs/conf
 | `MCP_BROKER_TLS_KEY` | (unset) | Path to a PEM private key. Enables HTTPS/WSS |
 | `MCP_BROKER_PROTOCOL` | auto | `http` forces plain, `https` forces TLS, unset auto-detects from cert+key |
 | `MCP_BROKER_STDIO_PROVIDER` | (unset) | When set, bridge stdin/stdout JSON-RPC to this provider (Claude Desktop integration) |
+| `MCP_BROKER_AUTH_ENABLED` | (unset) | `1` to turn on the OAuth 2.1 resource server (requires the three below) |
+| `MCP_BROKER_PUBLIC_BASE_URL` | (unset) | Public origin used to build canonical resource URIs, e.g. `https://mcp.example.com` |
+| `MCP_BROKER_JWKS` | (unset) | Authorization server's JWKS URL, used to verify token signatures |
+| `MCP_BROKER_ISSUER` | (unset) | Expected token issuer (defaults to the sole authorization server) |
+| `MCP_BROKER_PROVIDER_SECRET` | (unset) | Shared secret every provider must present to occupy a slot |
+
+## Authorization (OAuth 2.1)
+
+By default the broker performs **no** authentication. That is fine behind a
+trusted network boundary, but do not expose it publicly as-is. Turn on the OAuth 2.1
+resource server to require a bearer token on every client request, authenticate
+providers, and filter the `_all` aggregate per caller.
+
+Enabled via the `auth` config block (or env vars). Minimal `.mcp-broker/config.json`:
+
+```json
+{
+    "auth": {
+        "enabled": true,
+        "publicBaseUrl": "https://mcp.example.com",
+        "authorizationServers": ["https://auth.example.com"],
+        "jwks": "https://auth.example.com/.well-known/jwks.json",
+        "requiredScopes": ["mcp:call"],
+        "perSlotScopes": { "_broker": ["broker:admin"] },
+        "subjectMapping": {
+            "userClaim": "sub",
+            "groupClaims": ["groups"],
+            "clientClaim": "client_id"
+        },
+        "roles": {
+            "viewer": {
+                "capabilities": ["mcp.tools.list", "mcp.resources.read"]
+            },
+            "maintenance": {
+                "inherits": ["viewer"],
+                "capabilities": ["mcp.tools.diagnose"]
+            }
+        },
+        "assignments": [
+            {
+                "subject": "group:maintenance-site-a",
+                "role": "maintenance",
+                "resource": "/enterprise/site-a/**"
+            }
+        ],
+        "slotResources": {
+            "motor-7": "/enterprise/site-a/area-a/line-3/cell-2/motor-7"
+        },
+        "toolCapabilities": {
+            "diagnose_motor": "mcp.tools.diagnose"
+        },
+        "providerSecret": "change-me"
+    }
+}
+```
+
+With this on:
+
+- `POST /<slot>/mcp` (and `/sse`, `/messages`, `ws://…/<slot>`) require
+  `Authorization: Bearer <token>`; the token's audience must be
+  `https://mcp.example.com/<slot>/mcp`.
+- Clients discover the authorization server via
+  `GET /.well-known/oauth-protected-resource/<slot>/mcp` (RFC 9728), advertised
+  in the `401` challenge.
+- Providers must present `providerSecret` (via `X-Provider-Token` or
+  `Authorization: Bearer`) to connect to `/provider/<slot>` or `/providers`.
+- `_all` only shows providers allowed by the caller's hierarchical policy.
+- Explicit denies override inherited role grants.
+- Structured provider principals can publish only inside their allowed resource
+  namespace.
+
+Full model, flows, scopes, and endpoints: **[../docs/authorization.md](../docs/authorization.md)**.
+Roles, resource paths, denies, and migration:
+**[../docs/hierarchical-authorization.md](../docs/hierarchical-authorization.md)**.
+Config field reference: **[docs/config.md](docs/config.md#auth-oauth-21-authorization)**.
 
 ## Programmatic API
 
@@ -111,12 +186,52 @@ const broker = new WsTunnelBuilder()
     .withStdioUpstream("my-server", "node", ["./my-server.js"])
     // Optional: serve a dev harness at /
     .withStaticMount("/", "/abs/path/to/www")
+    // Optional: enable the OAuth 2.1 resource server + provider auth
+    .withJwtAuth({
+        publicBaseUrl: "https://mcp.example.com",
+        authorizationServers: ["https://auth.example.com"],
+        jwksUri: "https://auth.example.com/.well-known/jwks.json",
+        requiredScopes: ["mcp:call"],
+        roles: {
+            viewer: { capabilities: ["mcp.tools.list"] },
+        },
+        assignments: [
+            {
+                subject: "group:operators",
+                role: "viewer",
+                resource: "/enterprise/site-a/**",
+            },
+        ],
+        subjectMapping: { groupClaims: ["groups"] },
+    })
+    .withProviderSecret(process.env.PROVIDER_SECRET!)
     .build();
 
 await broker.start();
 ```
 
-All builder methods are documented inline. The full options interface is `WsTunnelOptions`, also exported.
+All builder methods are documented inline. The full options interface is
+`IWsTunnelOptions`, also exported. Use `withAuthorizationPolicy` for a
+standalone policy configuration, `withPolicyEngine` for a custom engine, and
+`withSlotResourceResolver` for a custom namespace mapping. For a custom token
+validator (for example RFC 7662 introspection) or provider authenticator, use
+`withAuth(resolvedAuth)` or `withProviderAuth(authenticator)` with your own
+`ITokenValidator` or `IProviderAuthenticator`.
+
+## Interactive OAuth demo
+
+The bundled [OAuth Policy Lab](web/demos/oauth-lab/) runs a complete local
+Authorization Code and PKCE flow with signed JWTs, JWKS validation,
+audience-bound tokens, hierarchical policies, explicit denies, and a live
+audit:
+
+```sh
+npm run demo:oauth
+```
+
+The page opens at `http://127.0.0.1:3001/demos/oauth-lab/`. See the
+[demo README](web/demos/oauth-lab/README.md) for its identities, policy matrix,
+and automated smoke test.
 
 ## TLS for local development
 

package/dist/auth/auth.config.d.ts

@@ -0,0 +1,40 @@
+import type { IResolvedAuth } from "./auth.types.js";
+import { type IAuthorizationPolicyConfig } from "../authorization/index.js";
+/**
+ * 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 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 declare function buildJwtAuth(options: IJwtAuthOptions): IResolvedAuth;
+/** @deprecated Use {@link IJwtAuthOptions}. */
+export type JwtAuthOptions = IJwtAuthOptions;

package/dist/auth/auth.config.js

@@ -0,0 +1,62 @@
+import { JwtTokenValidator } from "./jwt.validator.js";
+import { compileAuthorizationPolicy, DefaultSlotResourceResolver, hasAuthorizationPolicies } from "../authorization/index.js";
+/** Builds the default aggregate filter from a per-provider scope map. */
+function makeProviderScopeFilter(providerScopes) {
+    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) {
+    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) {
+    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 = {
+        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;
+}
+//# sourceMappingURL=auth.config.js.map

package/dist/auth/auth.config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.config.js","sourceRoot":"","sources":["../../src/auth/auth.config.ts"],"names":[],"mappings":"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"}

package/dist/auth/auth.types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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.
+ */
+import type { IAuthorizationSubject, IPolicyAuthorization, ISlotResourceResolver } from "../authorization/index.js";
+/**
+ * The subset of OAuth 2.1 / RFC 9068 access-token claims a resource server
+ * cares about. `aud` carries the audience binding (RFC 8707), `scope` the
+ * space-delimited granted scopes; some authorization servers emit `scopes` as
+ * an array instead. Unknown claims are preserved via the index signature.
+ */
+export interface IAccessTokenClaims {
+    /** Subject — the principal the token was issued for. */
+    sub?: string;
+    /** Intended audience(s). MUST include the slot's canonical resource URI. */
+    aud?: string | string[];
+    /** Issuer (the authorization server). */
+    iss?: string;
+    /** Expiry, seconds since the epoch. */
+    exp?: number;
+    /** Space-delimited granted scopes (RFC 8693). */
+    scope?: string;
+    /** Array-form granted scopes, emitted by some authorization servers. */
+    scopes?: string[];
+    [claim: string]: unknown;
+}
+/**
+ * Validates a bearer access token for a specific resource. Implementations MUST
+ * verify the token's signature/validity **and** that it was issued for
+ * `resource` (audience binding, RFC 8707). On any failure they MUST throw an
+ * {@link AuthError} with status `401` and code `invalid_token`; unexpected
+ * infrastructure failures (e.g. JWKS unreachable) should throw a plain error so
+ * the caller can surface a `500` rather than a misleading `401`.
+ */
+export interface ITokenValidator {
+    validate(token: string, resource: string): Promise<IAccessTokenClaims>;
+}
+/** OAuth 2.1 error codes the broker emits in `WWW-Authenticate` challenges. */
+export type AuthErrorCode = "invalid_token" | "insufficient_scope" | "invalid_request";
+/**
+ * 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.
+ */
+export declare class AuthError extends Error {
+    readonly status: 401 | 403 | 400;
+    readonly code: AuthErrorCode;
+    readonly description?: string;
+    readonly scope?: string;
+    constructor(status: 401 | 403 | 400, code: AuthErrorCode, description?: string, scope?: string);
+}
+/**
+ * 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.
+ */
+export interface IPrincipal {
+    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, unioning the
+ * space-delimited `scope` string and the array-form `scopes` claim.
+ */
+export declare function scopesOf(claims: IAccessTokenClaims): Set<string>;
+/** @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/dist/auth/auth.types.js

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+export class AuthError extends Error {
+    status;
+    code;
+    description;
+    scope;
+    constructor(status, code, description, scope) {
+        super(description ?? code);
+        this.name = "AuthError";
+        this.status = status;
+        this.code = code;
+        this.description = description;
+        this.scope = scope;
+    }
+}
+/**
+ * Extracts the effective set of granted scopes from token claims, unioning the
+ * space-delimited `scope` string and the array-form `scopes` claim.
+ */
+export function scopesOf(claims) {
+    const set = new Set();
+    if (typeof claims.scope === "string") {
+        for (const s of claims.scope.split(/\s+/))
+            if (s)
+                set.add(s);
+    }
+    if (Array.isArray(claims.scopes)) {
+        for (const s of claims.scopes)
+            if (typeof s === "string" && s)
+                set.add(s);
+    }
+    return set;
+}
+//# sourceMappingURL=auth.types.js.map

package/dist/auth/auth.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.types.js","sourceRoot":"","sources":["../../src/auth/auth.types.ts"],"names":[],"mappings":"AAgDA;;;;GAIG;AACH,MAAM,OAAO,SAAU,SAAQ,KAAK;IACvB,MAAM,CAAkB;IACxB,IAAI,CAAgB;IACpB,WAAW,CAAU;IACrB,KAAK,CAAU;IAExB,YAAY,MAAuB,EAAE,IAAmB,EAAE,WAAoB,EAAE,KAAc;QAC1F,KAAK,CAAC,WAAW,IAAI,IAAI,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC;CACJ;AAuDD;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,MAA0B;IAC/C,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QACnC,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC;YAAE,IAAI,CAAC;gBAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/B,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM;YAAE,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC;gBAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC"}

package/dist/auth/http.auth.d.ts

@@ -0,0 +1,51 @@
+import type { IncomingMessage, ServerResponse } from "http";
+import { AuthError, type IPrincipal, type IResolvedAuth } from "./auth.types.js";
+import { type IProtectedResourceMetadata } from "./resource.metadata.js";
+/**
+ * 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 declare class HttpAuthGuard {
+    private readonly _auth;
+    /** The `/mcp` suffix without a leading slash, e.g. `"mcp"`. */
+    private readonly _mcpSuffix;
+    constructor(auth: IResolvedAuth, mcpSuffix: string);
+    /** Canonical resource identifier for a slot (RFC 8707 §2). */
+    resourceFor(slot: string): string;
+    /** RFC 9728 metadata URL for a slot, advertised in the `401` challenge. */
+    metadataUrlFor(slot: string): string;
+    /** Required scope(s) for a slot: per-slot override, else the baseline. */
+    requiredScopesFor(slot: string): string[];
+    /** The RFC 9728 metadata document for a slot. */
+    metadataFor(slot: string): IProtectedResourceMetadata;
+    /**
+     * If `rawUrl` is a Protected Resource Metadata request
+     * (`/.well-known/oauth-protected-resource/<slot>/<mcp>`), returns the slot;
+     * otherwise `null`.
+     */
+    matchMetadataRequest(rawUrl: string): string | null;
+    /**
+     * Validates the request's bearer token against the slot's canonical resource
+     * and enforces the slot's required scopes. Resolves to the {@link IPrincipal}
+     * on success; rejects with an {@link AuthError} (`401` missing/invalid token,
+     * `403` insufficient scope) otherwise.
+     */
+    authorize(req: IncomingMessage, slot: string): Promise<IPrincipal>;
+    /**
+     * Builds the RFC 9728 §5.1 `WWW-Authenticate` header value for a challenge.
+     * Always points the client at the slot's metadata URL so it can discover the
+     * authorization server and retry. Shared by the HTTP and WebSocket paths.
+     */
+    challengeHeader(slot: string, err: AuthError): string;
+    /**
+     * Writes an RFC 9728 §5.1 `WWW-Authenticate` challenge and the matching
+     * status to an HTTP response.
+     */
+    writeChallenge(res: ServerResponse, slot: string, err: AuthError): void;
+}