mcp-authz 0.1.0 → 0.3.0

package/dist/index.js

@@ -1,6 +1,7 @@
-import { createPrincipal, definePermissions, definePolicy, reconcile } from "./policy.js";
-import { McpServer, OAuthError, OAuthErrorCode, UriTemplate, bearerAuthChallengeResponse, classifyInboundRequest, createMcpHandler, getOAuthProtectedResourceMetadataUrl, isJsonContentType, oauthMetadataResponse, requireBearerAuth } from "@modelcontextprotocol/server";
-import { createRemoteJWKSet, jwtVerify } from "jose";
+import { a as policyDenied, i as emitDecision, n as jwksVerifier, o as principalLabel, r as verifierFor, s as AccessDeniedError, t as identityFromAuth } from "./verifier-D6VIAYuT.js";
+import { d as scopesForCapability, f as scopesFromMcpHeaders, i as runScopedGate, r as permissionForRoute, u as decodeMcpNameHeader } from "./ladder-CUzOKudC.js";
+import { i as reconcile, n as definePermissions, r as definePolicy, t as createPrincipal } from "./policy-BBp3Jq6G.js";
+import { McpServer, UriTemplate, createMcpHandler, getOAuthProtectedResourceMetadataUrl, oauthMetadataResponse, requireBearerAuth } from "@modelcontextprotocol/server";
 //#region src/discovery.ts
 /**
 * Fetch the authorization server's own metadata instead of hand-copying it.
@@ -34,6 +35,310 @@ async function discoverOAuth(issuer, options = {}) {
 	throw new Error(`No OAuth metadata for '${issuer}'. Tried:\n  ${tried.join("\n  ")}\nPass \`oauthMetadata\` directly if your AS publishes it somewhere else.`);
 }
 //#endregion
+//#region src/tools.ts
+const AUDIT_EVENT_TYPE = "mcp_authz.audit.v1";
+/** Thrown into the handler's place when a person said no, or said nothing in time. */
+var ApprovalRefusedError = class extends Error {
+	capability;
+	by;
+	constructor(capability, reason, by) {
+		super(`${capability} was not approved: ${reason}`);
+		this.name = "ApprovalRefusedError";
+		this.capability = capability;
+		this.by = by;
+	}
+};
+/**
+* Everything that wraps a permitted invocation, whatever kind it is, and
+* whether the capability was defined here or wrapped by `gate`.
+*
+* Recording and asking live together because they share one decision: what the
+* call touches. Splitting them would mean calling `audit(args)` twice and
+* hoping the two answers stayed the same.
+*/
+function guarding(kind, name, permission, audit, principal, guards) {
+	const { onAudit, onAuditError, onApproval, approvalTimeoutMs, needsApproval, emitter } = guards;
+	return async (args, run) => {
+		const asking = needsApproval?.(args) === true;
+		if (!onAudit && !asking) return run();
+		const started = performance.now();
+		const resource = audit?.(args);
+		const base = {
+			issuer: principal.issuer,
+			sub: principal.sub,
+			email: principal.email,
+			domain: principal.domain,
+			kind,
+			name,
+			permission,
+			resource
+		};
+		const audited = {
+			...base,
+			callId: crypto.randomUUID(),
+			...emitter ? { emitter } : {}
+		};
+		const now = () => (/* @__PURE__ */ new Date()).toISOString();
+		await onAudit?.({
+			type: AUDIT_EVENT_TYPE,
+			...audited,
+			decision: "allow",
+			phase: "attempt",
+			at: now()
+		});
+		let approvedBy;
+		if (asking) {
+			const decision = await decideWithin(() => onApproval({
+				...base,
+				arguments: args,
+				at: now()
+			}), approvalTimeoutMs);
+			if (decision.approved && (typeof decision.by !== "string" || decision.by.trim().length === 0)) {
+				const reason = "approval did not name who gave it";
+				await deliverTerminalAudit(onAudit, onAuditError, {
+					...audited,
+					decision: "deny",
+					phase: "refused",
+					at: now(),
+					durationMs: performance.now() - started,
+					error: reason
+				});
+				throw new ApprovalRefusedError(name, reason);
+			}
+			if (!decision.approved) {
+				const reason = decision.reason ?? "refused";
+				await deliverTerminalAudit(onAudit, onAuditError, {
+					...audited,
+					decision: "deny",
+					phase: "refused",
+					approvedBy: decision.by,
+					at: now(),
+					durationMs: performance.now() - started,
+					error: reason
+				});
+				throw new ApprovalRefusedError(name, reason, decision.by);
+			}
+			approvedBy = decision.by;
+		}
+		try {
+			const result = await run();
+			await deliverTerminalAudit(onAudit, onAuditError, {
+				...audited,
+				decision: "allow",
+				phase: "success",
+				approvedBy,
+				at: now(),
+				durationMs: performance.now() - started
+			});
+			return result;
+		} catch (error) {
+			await deliverTerminalAudit(onAudit, onAuditError, {
+				...audited,
+				decision: "allow",
+				phase: "failure",
+				approvedBy,
+				at: now(),
+				durationMs: performance.now() - started,
+				error: error instanceof Error ? error.message : String(error)
+			});
+			throw error;
+		}
+	};
+}
+async function deliverTerminalAudit(sink, onError, event) {
+	try {
+		await sink?.({
+			type: AUDIT_EVENT_TYPE,
+			...event
+		});
+	} catch (error) {
+		try {
+			await onError?.({
+				error,
+				event: {
+					type: AUDIT_EVENT_TYPE,
+					...event
+				}
+			});
+		} catch {}
+	}
+}
+/**
+* Wait for a person, but not forever.
+*
+* The deadline is the whole reason this stays a library rather than a service:
+* the caller is still on the other end of an open request, so nothing has to
+* survive a restart — a process that dies mid-question takes the request with
+* it, and the action correctly did not happen.
+*
+* The ceiling is deliberate: blocking, in-memory, one process. Keep the
+* deadline under the idle timeout of whatever proxy sits in front, and reach
+* for MCP progress notifications (or a pending-ticket tool of your own) if you
+* need longer.
+*/
+async function decideWithin(ask, ms) {
+	let timer;
+	const expiry = new Promise((resolve) => {
+		timer = setTimeout(() => resolve({
+			approved: false,
+			reason: `no answer within ${ms}ms`
+		}), ms);
+	});
+	try {
+		return await Promise.race([Promise.resolve(ask()), expiry]);
+	} catch (error) {
+		return {
+			approved: false,
+			reason: error instanceof Error ? error.message : String(error)
+		};
+	} finally {
+		clearTimeout(timer);
+	}
+}
+function toolsFor(handlerContext) {
+	return function tool(name, config, handler) {
+		const { permission, audit, approval, ...toolConfig } = config;
+		return {
+			label: name,
+			kind: "tool",
+			routeName: name,
+			permission,
+			approval: Boolean(approval),
+			register(server, principal, context, guards) {
+				if (!principal.can(permission)) return;
+				const record = guarding("tool", name, permission, audit, principal, {
+					...guards,
+					needsApproval: approvalPredicate(approval)
+				});
+				server.registerTool(name, toolConfig, (async (args) => {
+					return record(args, () => handler(args, handlerContext(context, principal)));
+				}));
+			}
+		};
+	};
+}
+/**
+* Approval is decided per call, not per registration, because it turns on the
+* arguments — which is why it is the one check here that cannot be a decision
+* about whether to register something.
+*/
+function approvalPredicate(approval) {
+	if (approval === void 0 || approval === false) return void 0;
+	return approval === true ? () => true : approval;
+}
+function promptsFor(handlerContext) {
+	return function prompt(name, config, handler) {
+		const { permission, audit, approval, ...promptConfig } = config;
+		return {
+			label: `prompt:${name}`,
+			kind: "prompt",
+			routeName: name,
+			permission,
+			approval: Boolean(approval),
+			register(server, principal, context, guards) {
+				if (!principal.can(permission)) return;
+				const record = guarding("prompt", name, permission, audit, principal, {
+					...guards,
+					needsApproval: approvalPredicate(approval)
+				});
+				server.registerPrompt(name, promptConfig, (async (args) => {
+					return record(args, () => handler(args, handlerContext(context, principal)));
+				}));
+			}
+		};
+	};
+}
+function resourcesFor(handlerContext) {
+	return function resource(name, config, handler) {
+		const { permission, audit, approval, uri, ...metadata } = config;
+		const routeTemplate = typeof uri === "string" ? new UriTemplate(uri) : uri.uriTemplate;
+		return {
+			label: `resource:${name}`,
+			kind: "resource",
+			routeName: typeof uri === "string" ? uri : routeTemplate.toString(),
+			routeMatches: (target) => routeTemplate.match(target) !== null,
+			permission,
+			approval: Boolean(approval),
+			register(server, principal, context, guards) {
+				if (!principal.can(permission)) return;
+				const record = guarding("resource", name, permission, audit, principal, {
+					...guards,
+					needsApproval: approvalPredicate(approval)
+				});
+				server.registerResource(name, uri, metadata, (async (target) => {
+					return record(target, () => handler(target, handlerContext(context, principal)));
+				}));
+			}
+		};
+	};
+}
+function buildServer(definitions, options, principalOf) {
+	const permissions = /* @__PURE__ */ new Map();
+	const routePermissions = /* @__PURE__ */ new Map();
+	for (const definition of definitions) {
+		if (permissions.has(definition.label)) throw new Error(`'${definition.label}' is registered twice.`);
+		permissions.set(definition.label, definition.permission);
+		if (definition.routeName !== void 0) routePermissions.set(`${definition.kind}:${definition.routeName}`, definition.permission);
+	}
+	const unaskable = definitions.filter((definition) => definition.approval).map((d) => d.label);
+	if (unaskable.length > 0 && !options.onApproval) throw new Error(`MCP approval is not configured\n\nThese capabilities ask for a person:\n${unaskable.map((label) => `  ${label}`).join("\n")}\n\nPass \`onApproval\` to server(), or drop \`approval\` from them.`);
+	const factory = (context) => {
+		const principal = principalOf(context);
+		const enabled = definitions.filter((definition) => principal.can(definition.permission));
+		const declared = {
+			...enabled.some((definition) => definition.kind === "tool") ? { tools: {} } : {},
+			...enabled.some((definition) => definition.kind === "prompt") ? { prompts: {} } : {},
+			...enabled.some((definition) => definition.kind === "resource") ? { resources: {} } : {}
+		};
+		const { onAudit, onAuditError, onApproval, emitter, approvalTimeoutMs = 45e3, mcp: mcpOptions = {}, ...serverInfo } = options;
+		const server = new McpServer(serverInfo, {
+			...mcpOptions,
+			capabilities: {
+				...mcpOptions.capabilities,
+				...declared
+			}
+		});
+		const guards = {
+			onAudit,
+			onAuditError,
+			onApproval,
+			approvalTimeoutMs,
+			emitter
+		};
+		for (const definition of enabled) definition.register(server, principal, context, guards);
+		return server;
+	};
+	return Object.assign(factory, {
+		permissions,
+		routePermissions,
+		routeNameFor: (kind, name) => definitions.find((definition) => definition.kind === kind && (definition.routeMatches?.(name) ?? definition.routeName === name))?.routeName,
+		permissionForRoute: (kind, name) => definitions.find((definition) => definition.kind === kind && (definition.routeMatches?.(name) ?? definition.routeName === name))?.permission
+	});
+}
+/**
+* Everything bound to one policy: `permission` accepts only what that policy can
+* grant, in all four places, from one call.
+*
+* The policy is a type carrier here and is never invoked. Authorization happens
+* once per request when the principal is resolved, not once per definition.
+*
+* ```ts
+* const { tool, prompt, resource, server } = authz(policy);
+* ```
+*/
+function bindAuthz(_permissions, principalOf, handlerContext) {
+	return {
+		tool: toolsFor(handlerContext),
+		prompt: promptsFor(handlerContext),
+		resource: resourcesFor(handlerContext),
+		server: (definitions, options) => buildServer(definitions, options, principalOf)
+	};
+}
+function authz(policy, options) {
+	if (options) return bindAuthz(policy, options.principal, (context) => context);
+	return bindAuthz(policy, (principal) => principal, (_context, principal) => ({ principal }));
+}
+//#endregion
 //#region src/gate.ts
 function gate(server, principal, permissions, options = {}) {
 	const required = isMapLike(permissions) ? new Map(permissions) : new Map(Object.entries(permissions));
@@ -42,47 +347,22 @@ function gate(server, principal, permissions, options = {}) {
 		const label = kind === "tool" ? name : `${kind}:${name}`;
 		const permission = required.get(label);
 		if (permission === void 0) throw new Error(`gate(): no permission declared for ${kind} '${name}'. Add '${label}' to the permission map, or stop registering it.`);
+		const approval = options.approval?.[label];
+		if (approval && !options.onApproval) throw new Error(`gate(): ${kind} '${name}' asks for approval, but no 'onApproval' was passed.`);
 		const last = args.length - 1;
 		const handler = args[last];
-		if (options.onAudit && typeof handler === "function") {
-			const resource = options.audit?.[label];
+		if ((options.onAudit || approval) && typeof handler === "function") {
+			const record = guarding(kind, name, permission, options.audit?.[label], principal, {
+				onAudit: options.onAudit,
+				onAuditError: options.onAuditError,
+				onApproval: options.onApproval,
+				approvalTimeoutMs: options.approvalTimeoutMs ?? 45e3,
+				needsApproval: approvalPredicate(approval),
+				...options.emitter ? { emitter: options.emitter } : {}
+			});
 			const inner = handler;
-			args[last] = async function audited(...called) {
-				const started = performance.now();
-				const base = {
-					issuer: principal.issuer,
-					sub: principal.sub,
-					email: principal.email,
-					kind,
-					name,
-					permission,
-					resource: resource?.(called[0]),
-					decision: "allow"
-				};
-				await options.onAudit?.({
-					...base,
-					phase: "attempt",
-					at: (/* @__PURE__ */ new Date()).toISOString()
-				});
-				try {
-					const result = await inner.apply(this, called);
-					await options.onAudit?.({
-						...base,
-						phase: "success",
-						at: (/* @__PURE__ */ new Date()).toISOString(),
-						durationMs: performance.now() - started
-					});
-					return result;
-				} catch (error) {
-					await options.onAudit?.({
-						...base,
-						phase: "failure",
-						at: (/* @__PURE__ */ new Date()).toISOString(),
-						durationMs: performance.now() - started,
-						error: error instanceof Error ? error.message : String(error)
-					});
-					throw error;
-				}
+			args[last] = async function guarded(...called) {
+				return record(called[0], () => inner.apply(this, called));
 			};
 		}
 		const registered = register.apply(server, args);
@@ -108,240 +388,38 @@ function isMapLike(value) {
 	return typeof value === "object" && value !== null && typeof value.get === "function" && Symbol.iterator in value;
 }
 //#endregion
-//#region src/identity.ts
-var AccessDeniedError = class AccessDeniedError extends Error {
-	email;
-	reason;
-	constructor(email, reason, message) {
-		super(message);
-		this.name = "AccessDeniedError";
-		this.email = email;
-		this.reason = reason;
-	}
-	static notPermitted(email, policyHint = "the access policy") {
-		return new AccessDeniedError(email, "not_permitted", `${email} matches no rule in ${policyHint}, so they hold no permissions. Ask an administrator to grant them a role.`);
-	}
-	static noCredential(email, credentialHint = "a backend credential") {
-		return new AccessDeniedError(email, "no_credential", `${email} is permitted but has no ${credentialHint}, and no shared account is configured.`);
-	}
-};
-//#endregion
-//#region src/scopes.ts
-const BASE64_SENTINEL = /^=\?base64\?([A-Za-z0-9+/]*(?:={0,2}))\?=$/;
-const CANONICAL_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
-/**
-* Tools use their bare name (or `tool:name`); prompts use `prompt:name`; and
-* resources use `resource:<uri>`. Everything else needs only the baseline.
-*/
-function scopesFromMcpHeaders(request, toolScopes, baseline = "mcp") {
-	const method = request.headers.get("mcp-method");
-	const rawName = request.headers.get("mcp-name");
-	const name = rawName === null ? void 0 : decodeMcpNameHeader(rawName);
-	return scopesForCapability(method ?? void 0, name, toolScopes, baseline);
-}
-/** Select scopes from an already validated MCP method/name pair. */
-function scopesForCapability(method, name, capabilityScopes, baseline = "mcp") {
-	if (!name) return [baseline];
-	const key = method === "tools/call" ? capabilityScopes[name] === void 0 ? `tool:${name}` : name : method === "prompts/get" ? `prompt:${name}` : method === "resources/read" ? `resource:${name}` : void 0;
-	const required = (key ? capabilityScopes[key] : void 0) ?? baseline;
-	return typeof required === "string" ? [required] : [...required];
-}
-/** Decode SEP-2243's optional Base64 sentinel without accepting non-canonical input. */
-function decodeMcpNameHeader(value) {
-	const normalized = value.trim();
-	if (!normalized.startsWith("=?base64?") || !normalized.endsWith("?=")) return normalized;
-	const encoded = BASE64_SENTINEL.exec(normalized)?.[1];
-	if (encoded === void 0 || !CANONICAL_BASE64.test(encoded)) return void 0;
-	try {
-		const binary = atob(encoded);
-		const bytes = Uint8Array.from(binary, (character) => character.codePointAt(0) ?? 0);
-		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-	} catch {
-		return;
-	}
-}
-//#endregion
-//#region src/routing.ts
-const NAME_SOURCE = {
-	"tools/call": "name",
-	"prompts/get": "name",
-	"resources/read": "uri"
-};
-/**
-* Parse and validate every routing input before it can influence OAuth scopes.
-* This mirrors the SDK's standard-header rung, including Base64 sentinel
-* decoding, but runs before bearer authorization rather than during dispatch.
-*/
-function classifyScopedRequest(request, body) {
-	if (request.method.toUpperCase() !== "POST") return {
-		kind: "legacy",
-		body: void 0,
-		outcome: {
-			kind: "legacy",
-			reason: "http-method"
-		}
-	};
-	const outcome = classifyInboundRequest({
-		httpMethod: request.method,
-		...header(request, "mcp-protocol-version", "protocolVersionHeader"),
-		...header(request, "mcp-method", "mcpMethodHeader"),
-		...header(request, "mcp-name", "mcpNameHeader"),
-		body
-	});
-	if (outcome.kind === "reject") return rejected(outcome.httpStatus, outcome.code, outcome.message, outcome.data, requestId$1(body));
-	if (outcome.kind === "legacy") return {
-		kind: "legacy",
-		body,
-		outcome
-	};
-	const method = outcome.message.method;
-	if (outcome.messageKind !== "request") return {
-		kind: "modern",
-		body,
-		outcome,
-		method
-	};
-	if (request.headers.get("mcp-method") === null) return mismatch("(missing)", `the body names method ${method} but the required Mcp-Method header is absent`, body);
-	const source = Object.hasOwn(NAME_SOURCE, method) ? NAME_SOURCE[method] : void 0;
-	if (source === void 0) return {
-		kind: "modern",
-		body,
-		outcome,
-		method
-	};
-	const params = isRecord$1(outcome.message.params) ? outcome.message.params : void 0;
-	const bodyName = typeof params?.[source] === "string" ? params[source] : void 0;
-	const rawName = request.headers.get("mcp-name");
-	if (rawName === null) {
-		if (bodyName === void 0) return {
-			kind: "modern",
-			body,
-			outcome,
-			method
-		};
-		return mismatch("(missing)", `the body carries params.${source}="${bodyName}" but the required Mcp-Name header is absent`, body);
-	}
-	const decodedName = decodeMcpNameHeader(rawName);
-	if (decodedName === void 0) return mismatch(rawName.trim(), "the Mcp-Name header carries an invalid Base64 sentinel value", body);
-	if (bodyName !== void 0 && decodedName !== bodyName) return mismatch(rawName.trim(), `the body carries params.${source}="${bodyName}" but the Mcp-Name header names "${decodedName}"`, body);
-	return {
-		kind: "modern",
-		body,
-		outcome,
-		method,
-		...bodyName === void 0 ? {} : { name: bodyName }
-	};
-}
-function header(request, name, property) {
-	const value = request.headers.get(name);
-	return value === null ? {} : { [property]: value };
-}
-function mismatch(headerValue, bodyDescription, body) {
-	return rejected(400, -32020, `Bad Request: the request headers and body disagree: ${bodyDescription}`, { mismatch: {
-		header: headerValue,
-		body: bodyDescription
-	} }, requestId$1(body));
-}
-function rejected(httpStatus, code, message, data, id) {
-	return {
-		kind: "reject",
-		httpStatus,
-		code,
-		message,
-		...data === void 0 ? {} : { data },
-		id
-	};
-}
-function requestId$1(body) {
-	if (!isRecord$1(body)) return null;
-	const id = body.id;
-	return typeof id === "string" || typeof id === "number" ? id : null;
-}
-function isRecord$1(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-//#endregion
-//#region src/verifier.ts
-const invalidToken = (message) => new OAuthError(OAuthErrorCode.InvalidToken, message);
-/**
-* A JWKS-backed verifier. Keys are fetched once and cached by `jose`, which
-* also handles rotation, so a key roll at the AS does not need a redeploy.
-*/
-function jwksVerifier(options) {
-	const jwks = createRemoteJWKSet(new URL(options.jwksUri));
-	const emailClaim = options.emailClaim ?? "email";
-	const emailVerifiedClaim = options.emailVerifiedClaim ?? "email_verified";
-	const expectedResource = new URL(options.resource.href).href.split("#")[0];
-	return {
-		async verifyAccessToken(token) {
-			let payload;
-			try {
-				payload = (await jwtVerify(token, jwks, {
-					issuer: options.issuer,
-					audience: expectedResource
-				})).payload;
-			} catch (error) {
-				throw invalidToken(`Token rejected: ${error instanceof Error ? error.message : String(error)}`);
-			}
-			if (typeof payload.exp !== "number") throw invalidToken("Token has no `exp` claim.");
-			const email = payload[emailClaim];
-			if (typeof email !== "string" || !email) throw invalidToken(`Token carries no '${emailClaim}' claim, so there is no identity to map.`);
-			if ((options.requireEmailVerified ?? true) && payload[emailVerifiedClaim] !== true) throw invalidToken(`Token does not prove '${emailClaim}' with '${emailVerifiedClaim}: true'.`);
-			const sub = payload.sub;
-			if (typeof sub !== "string" || !sub) throw invalidToken("Token has no `sub` claim, so there is no stable subject to bind to.");
-			const domain = typeof payload.hd === "string" ? payload.hd : void 0;
-			if (options.allowedDomain && domain?.toLowerCase() !== options.allowedDomain.toLowerCase()) throw invalidToken(`Token is for ${domain ?? "an unknown domain"}, not ${options.allowedDomain}.`);
-			return {
-				token,
-				clientId: typeof payload.client_id === "string" ? payload.client_id : typeof payload.azp === "string" ? payload.azp : sub,
-				scopes: scopesOf(payload.scope),
-				expiresAt: payload.exp,
-				resource: options.resource,
-				extra: {
-					issuer: options.issuer,
-					sub,
-					email,
-					emailVerified: options.requireEmailVerified === false || payload[emailVerifiedClaim] === true,
-					domain,
-					claims: payload
-				}
-			};
-		},
-		identityOf: identityFromAuth
-	};
-}
-/** Default identity mapper for custom verifiers using `AuthInfo.extra`. */
-function identityFromAuth(auth) {
-	const { issuer, sub, email, emailVerified, domain, claims } = auth.extra ?? {};
-	if (typeof issuer !== "string" || !issuer || typeof sub !== "string" || !sub) throw invalidToken("Verified token carried no issuer or subject.");
-	if (email !== void 0 && (typeof email !== "string" || !email)) throw invalidToken("Verified token carried an invalid email.");
-	return {
-		issuer,
-		sub,
-		email: typeof email === "string" ? email : void 0,
-		emailVerified: emailVerified === true,
-		domain: typeof domain === "string" ? domain : void 0,
-		claims: isRecord(claims) ? claims : {}
-	};
-}
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-/** OAuth scope is a space-delimited string; some servers send an array anyway. */
-function scopesOf(scope) {
-	if (Array.isArray(scope)) return scope.filter((s) => typeof s === "string");
-	if (typeof scope === "string") return scope.split(" ").filter(Boolean);
-	return [];
-}
-//#endregion
 //#region src/handler.ts
 /** Where the resolved per-request context rides from the gate to the factory. */
 const CONTEXT_KEY = "mcp-authz.context";
+const OAUTH_SCOPE_TOKEN = /^[\x21\x23-\x5B\x5D-\x7E]+$/;
 function createMcpFetch(options) {
-	const { resourceServerUrl, oauthMetadata, requiredScopes = ["mcp"], supportedScopes, toolScopes, capabilityScopes, policy, createServer, contextExtraKey = CONTEXT_KEY, healthPath = "/health", legacy = "reject", maxRequestBytes = 1048576 } = options;
+	const { resourceServerUrl, oauthMetadata, requiredScopes = ["mcp"], supportedScopes, toolScopes, capabilityScopes, policy, createServer, emitter, contextExtraKey = CONTEXT_KEY, healthPath = "/health", legacy = "reject", maxRequestBytes = 1048576 } = options;
 	if (toolScopes && capabilityScopes) throw new Error("Pass either `toolScopes` or `capabilityScopes`, not both.");
+	const invalidRequiredScope = requiredScopes.find((scope) => !OAUTH_SCOPE_TOKEN.test(scope));
+	if (invalidRequiredScope !== void 0) throw new Error(`requiredScopes has an invalid scope: '${invalidRequiredScope}'.`);
+	const invalidSupportedScope = supportedScopes?.find((scope) => !OAUTH_SCOPE_TOKEN.test(scope));
+	if (invalidSupportedScope !== void 0) throw new Error(`supportedScopes has an invalid scope: '${invalidSupportedScope}'.`);
 	const scopeMap = capabilityScopes ?? toolScopes;
 	if (scopeMap && options.scopesForRequest) throw new Error("Pass a declarative scope map or `scopesForRequest`, not both.");
+	if (scopeMap && requiredScopes.length === 0) throw new Error("A declarative scope map needs at least one baseline scope.");
+	for (const [key, scopes] of Object.entries(scopeMap ?? {})) {
+		if (Array.isArray(scopes) && scopes.length === 0) throw new Error(`Scope map key '${key}' needs at least one scope.`);
+		if ((typeof scopes === "string" ? [scopes] : scopes).some((scope) => !OAUTH_SCOPE_TOKEN.test(scope))) throw new Error(`Scope map key '${key}' has an invalid scope.`);
+	}
+	const scopeRoutes = Object.keys(scopeMap ?? {}).map((key) => ({
+		key,
+		route: routeFromScopeKey(key)
+	}));
+	const named = /* @__PURE__ */ new Set();
+	for (const { route } of scopeRoutes) {
+		const canonical = `${route.kind}:${route.name}`;
+		if (named.has(canonical)) throw new Error(`Scope map names ${route.kind} '${route.name}' more than once.`);
+		named.add(canonical);
+	}
+	if (scopeMap && (createServer.permissionForRoute || createServer.routePermissions)) for (const { key, route } of scopeRoutes) {
+		const canonical = `${route.kind}:${route.name}`;
+		if ((createServer.permissionForRoute?.(route.kind, route.name) ?? createServer.routePermissions?.get(canonical)) === void 0) throw new Error(`Scope map key '${key}' names no registered capability.`);
+	}
 	const scopesForRequest = options.scopesForRequest;
 	const advertisedScopes = [.../* @__PURE__ */ new Set([
 		...requiredScopes,
@@ -363,7 +441,7 @@ function createMcpFetch(options) {
 		const principal = policy ? policy(identity) : await options.authorize(identity);
 		if (!isPrincipal(principal)) throw new Error("The authorizer returned an invalid principal. Use `createPrincipal` to construct one.");
 		if (principal.permissions.length === 0) {
-			await emitDecision(options.onDecision, principal, "deny", "not_permitted");
+			await emitDecision(options.onDecision, principal, "deny", "not_permitted", emitter);
 			throw AccessDeniedError.notPermitted(principalLabel(principal));
 		}
 		return principal;
@@ -372,32 +450,20 @@ function createMcpFetch(options) {
 		if (!policy && !options.authorize) return enrich(identity, void 0);
 		try {
 			const context = enrich ? await enrich(identity, principal) : principal;
-			await emitDecision(options.onDecision, principal, "allow");
+			await emitDecision(options.onDecision, principal, "allow", void 0, emitter);
 			return context;
 		} catch (error) {
-			if (error instanceof AccessDeniedError) await emitDecision(options.onDecision, principal, "deny", error.reason);
+			if (error instanceof AccessDeniedError) await emitDecision(options.onDecision, principal, "deny", error.reason, emitter);
 			throw error;
 		}
 	};
-	if (options.tokenVerifier && options.verifier) throw new Error("Pass either `tokenVerifier` or built-in `verifier` options, not both.");
-	let tokenVerifier;
-	let mapIdentity;
-	if (options.tokenVerifier) {
-		tokenVerifier = options.tokenVerifier;
-		mapIdentity = options.identityFromAuth ?? identityFromAuth;
-	} else {
-		const published = typeof oauthMetadata.jwks_uri === "string" ? oauthMetadata.jwks_uri : void 0;
-		const jwksUri = options.verifier?.jwksUri ?? published;
-		if (!jwksUri) throw new Error("No JWKS to verify tokens against. Set `verifier.jwksUri`, use a custom `tokenVerifier`, or use `discoverOAuth(issuer)`, whose metadata carries `jwks_uri`.");
-		const builtIn = jwksVerifier({
-			...options.verifier,
-			jwksUri,
-			issuer: options.verifier?.issuer ?? oauthMetadata.issuer,
-			resource: options.verifier?.resource ?? resourceServerUrl
-		});
-		tokenVerifier = builtIn;
-		mapIdentity = options.identityFromAuth ?? builtIn.identityOf;
-	}
+	const { tokenVerifier, mapIdentity } = verifierFor({
+		oauthMetadata,
+		resourceServerUrl,
+		...options.verifier ? { verifier: options.verifier } : {},
+		...options.tokenVerifier ? { tokenVerifier: options.tokenVerifier } : {},
+		...options.identityFromAuth ? { identityFromAuth: options.identityFromAuth } : {}
+	});
 	const resourceMetadataUrl = getOAuthProtectedResourceMetadataUrl(resourceServerUrl);
 	const metadataOptions = {
 		oauthMetadata,
@@ -427,9 +493,6 @@ function createMcpFetch(options) {
 			status: 404,
 			headers: { "Content-Type": "text/plain" }
 		});
-		const preflight = Boolean(scopeMap || scopesForRequest) && request.method.toUpperCase() === "POST" ? await preflightScopedRequest(request, maxRequestBytes) : void 0;
-		if (preflight instanceof Response) return preflight;
-		const scopes = preflight ? scopeMap ? [.../* @__PURE__ */ new Set([...requiredScopes, ...scopesForCapability(preflight.route.method, preflight.route.name, scopeMap, requiredScopes[0] ?? "mcp")])] : scopesForRequest(request, preflight.route) : requiredScopes;
 		const auth = await requireBearerAuth({
 			verifier: tokenVerifier,
 			requiredScopes,
@@ -445,15 +508,30 @@ function createMcpFetch(options) {
 			if (error instanceof AccessDeniedError) return policyDenied(error);
 			throw error;
 		}
-		const routePermission = preflight ? permissionForRoute(createServer.permissionForRoute, createServer.routePermissions, preflight.route) : void 0;
-		if (routePermission && principal && !principal.can(routePermission)) {
-			await emitDecision(options.onDecision, principal, "deny", "policy_denied");
-			return policyDenied(AccessDeniedError.notPermitted(principalLabel(principal), `the permission '${routePermission}'`));
-		}
-		if (scopes.filter((scope) => !auth.scopes.includes(scope)).length > 0) return bearerAuthChallengeResponse(new OAuthError(OAuthErrorCode.InsufficientScope, "Insufficient scope"), {
-			requiredScopes: scopes,
+		const scoped = Boolean(scopeMap || scopesForRequest);
+		const routed = Boolean(createServer.permissionForRoute ?? createServer.routePermissions);
+		const gateResult = await runScopedGate({
+			request,
+			auth,
+			principal,
+			maxRequestBytes,
+			requiredScopes,
+			scoped,
+			routed,
+			scopeMap,
+			resolveCapabilityScopes: (route) => {
+				if (route.method !== "resources/read" || !route.name || !scopeMap) return void 0;
+				const registered = createServer.routeNameFor?.("resource", route.name);
+				return registered === void 0 ? void 0 : scopesForCapability(route.method, registered, scopeMap, requiredScopes[0] ?? "mcp");
+			},
+			scopesForRequest,
+			resolvePermission: (route) => permissionForRoute(createServer.permissionForRoute, createServer.routePermissions, route),
+			onDecision: options.onDecision,
+			...emitter ? { emitter } : {},
 			resourceMetadataUrl
 		});
+		if (!gateResult.ok) return gateResult.response;
+		const preflight = gateResult.preflight;
 		let context;
 		try {
 			context = await enrichIdentity(identity, principal);
@@ -461,7 +539,7 @@ function createMcpFetch(options) {
 			if (error instanceof AccessDeniedError) return policyDenied(error);
 			throw error;
 		}
-		return mcp.fetch(request, {
+		const answer = await mcp.fetch(request, {
 			authInfo: {
 				...auth,
 				extra: {
@@ -471,261 +549,56 @@ function createMcpFetch(options) {
 			},
 			...preflight ? { parsedBody: preflight.body } : {}
 		});
+		return legacy === "reject" ? explainLegacyRefusal(answer) : answer;
 	};
 }
-function policyDenied(error) {
-	return Response.json({
-		error: "forbidden",
-		reason: "policy_denied",
-		error_description: error.message
-	}, { status: 403 });
-}
-function permissionForRoute(resolver, permissions, route) {
-	if (!route.name || !resolver && !permissions) return void 0;
-	const kind = route.method === "tools/call" ? "tool" : route.method === "prompts/get" ? "prompt" : route.method === "resources/read" ? "resource" : void 0;
-	return kind ? resolver?.(kind, route.name) ?? permissions?.get(`${kind}:${route.name}`) : void 0;
-}
-async function emitDecision(sink, principal, decision, reason) {
-	await sink?.({
-		issuer: principal.issuer,
-		sub: principal.sub,
-		email: principal.email,
-		decision,
-		roles: principal.roles,
-		permissions: principal.permissions,
-		...reason ? { reason } : {},
-		at: (/* @__PURE__ */ new Date()).toISOString()
-	});
-}
-function principalLabel(principal) {
-	return principal.email ?? `${principal.issuer}#${principal.sub}`;
-}
-function isPrincipal(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const candidate = value;
-	return typeof candidate.sub === "string" && typeof candidate.email === "string" && Array.isArray(candidate.roles) && candidate.roles.every((role) => typeof role === "string") && Array.isArray(candidate.permissions) && candidate.permissions.every((permission) => typeof permission === "string") && typeof candidate.can === "function";
-}
-async function preflightScopedRequest(request, maxBytes) {
-	if (!isJsonContentType(request.headers.get("content-type"))) return protocolError(415, -32e3, "Per-capability scopes require an application/json body.");
-	const raw = await readCapped(request, maxBytes);
-	if (raw === void 0) return protocolError(413, -32e3, `Request body exceeds the ${maxBytes} byte limit.`);
-	let body;
-	try {
-		body = JSON.parse(raw);
-	} catch {
-		return protocolError(400, -32700, "Parse error: the request body is not valid JSON");
-	}
-	const route = classifyScopedRequest(request, body);
-	if (route.kind === "reject") return protocolError(route.httpStatus, route.code, route.message, route.data, route.id);
-	if (route.kind !== "modern") return protocolError(400, -32020, "Per-capability scopes require a 2026-07-28 request with matching MCP routing headers.", void 0, requestId(body));
-	return {
-		body,
-		route
-	};
-}
-function requestId(body) {
-	if (typeof body !== "object" || body === null || Array.isArray(body)) return null;
-	const id = body.id;
-	return typeof id === "string" || typeof id === "number" ? id : null;
-}
-function protocolError(status, code, message, data, id = null) {
-	return Response.json({
-		jsonrpc: "2.0",
-		error: {
-			code,
-			message,
-			...data === void 0 ? {} : { data }
-		},
-		id
-	}, { status });
-}
 /**
-* The body as text, or `undefined` when it is over the cap.
+* Say what to do about the refusal every new deployment meets first.
 *
-* Reads the clone chunk by chunk and stops at the limit rather than buffering
-* first and measuring after, because measuring after is how an unauthenticated
-* caller decides how much memory this process spends.
+* `legacy: 'reject'` is strict on purpose, but no MCP client shipping today can
+* satisfy it: they all still open with the `initialize` handshake that 2026-07-28
+* removed. So the first connection anybody makes fails with a bare protocol
+* error that does not mention that a setting exists, let alone which one. The
+* refusal stands; it just stops being a riddle.
 */
-async function readCapped(request, maxBytes) {
-	const declared = Number(request.headers.get("content-length"));
-	if (Number.isFinite(declared) && declared > maxBytes) return void 0;
-	const body = request.clone().body;
-	if (!body) return "";
-	const reader = body.getReader();
-	const chunks = [];
-	let total = 0;
-	for (;;) {
-		const { done, value } = await reader.read();
-		if (done) break;
-		total += value.byteLength;
-		if (total > maxBytes) {
-			reader.cancel().catch(() => {});
-			return;
-		}
-		chunks.push(value);
-	}
-	const joined = new Uint8Array(total);
-	let at = 0;
-	for (const chunk of chunks) {
-		joined.set(chunk, at);
-		at += chunk.byteLength;
+async function explainLegacyRefusal(response) {
+	if (response.ok) return response;
+	const body = await response.clone().text();
+	if (!body.includes("Unsupported protocol version")) return response;
+	let payload;
+	try {
+		payload = JSON.parse(body);
+	} catch {
+		return response;
 	}
-	return new TextDecoder().decode(joined);
+	if (typeof payload.error?.message !== "string") return response;
+	payload.error.message += ". No MCP client currently ships without the initialize handshake, so this refuses every client available today. Set legacy: 'stateless' to serve them.";
+	return Response.json(payload, {
+		status: response.status,
+		headers: response.headers
+	});
 }
-//#endregion
-//#region src/tools.ts
-/** The audit call every permitted invocation makes, whatever kind it is. */
-function auditing(kind, name, permission, audit, principal, onAudit) {
-	return async (args, run) => {
-		if (!onAudit) return run();
-		const started = performance.now();
-		const base = {
-			issuer: principal.issuer,
-			sub: principal.sub,
-			email: principal.email,
+function routeFromScopeKey(key) {
+	for (const kind of [
+		"tool",
+		"prompt",
+		"resource"
+	]) {
+		const prefix = `${kind}:`;
+		if (key.startsWith(prefix)) return {
 			kind,
-			name,
-			permission,
-			resource: audit?.(args),
-			decision: "allow"
-		};
-		await onAudit({
-			...base,
-			phase: "attempt",
-			at: (/* @__PURE__ */ new Date()).toISOString()
-		});
-		try {
-			const result = await run();
-			await onAudit({
-				...base,
-				phase: "success",
-				at: (/* @__PURE__ */ new Date()).toISOString(),
-				durationMs: performance.now() - started
-			});
-			return result;
-		} catch (error) {
-			await onAudit({
-				...base,
-				phase: "failure",
-				at: (/* @__PURE__ */ new Date()).toISOString(),
-				durationMs: performance.now() - started,
-				error: error instanceof Error ? error.message : String(error)
-			});
-			throw error;
-		}
-	};
-}
-function toolsFor(handlerContext) {
-	return function tool(name, config, handler) {
-		const { permission, audit, ...toolConfig } = config;
-		return {
-			label: name,
-			kind: "tool",
-			routeName: name,
-			permission,
-			register(server, principal, context, onAudit) {
-				if (!principal.can(permission)) return;
-				const record = auditing("tool", name, permission, audit, principal, onAudit);
-				server.registerTool(name, toolConfig, (async (args) => {
-					return record(args, () => handler(args, handlerContext(context, principal)));
-				}));
-			}
-		};
-	};
-}
-function promptsFor(handlerContext) {
-	return function prompt(name, config, handler) {
-		const { permission, audit, ...promptConfig } = config;
-		return {
-			label: `prompt:${name}`,
-			kind: "prompt",
-			routeName: name,
-			permission,
-			register(server, principal, context, onAudit) {
-				if (!principal.can(permission)) return;
-				const record = auditing("prompt", name, permission, audit, principal, onAudit);
-				server.registerPrompt(name, promptConfig, (async (args) => {
-					return record(args, () => handler(args, handlerContext(context, principal)));
-				}));
-			}
-		};
-	};
-}
-function resourcesFor(handlerContext) {
-	return function resource(name, config, handler) {
-		const { permission, audit, uri, ...metadata } = config;
-		const routeTemplate = typeof uri === "string" ? new UriTemplate(uri) : uri.uriTemplate;
-		return {
-			label: `resource:${name}`,
-			kind: "resource",
-			...typeof uri === "string" ? { routeName: uri } : {},
-			routeMatches: (target) => routeTemplate.match(target) !== null,
-			permission,
-			register(server, principal, context, onAudit) {
-				if (!principal.can(permission)) return;
-				const record = auditing("resource", name, permission, audit, principal, onAudit);
-				server.registerResource(name, uri, metadata, (async (target) => {
-					return record(target, () => handler(target, handlerContext(context, principal)));
-				}));
-			}
+			name: key.slice(prefix.length)
 		};
-	};
-}
-function buildServer(definitions, options, principalOf) {
-	const permissions = /* @__PURE__ */ new Map();
-	const routePermissions = /* @__PURE__ */ new Map();
-	for (const definition of definitions) {
-		if (permissions.has(definition.label)) throw new Error(`'${definition.label}' is registered twice.`);
-		permissions.set(definition.label, definition.permission);
-		if (definition.routeName !== void 0) routePermissions.set(`${definition.kind}:${definition.routeName}`, definition.permission);
 	}
-	const factory = (context) => {
-		const principal = principalOf(context);
-		const enabled = definitions.filter((definition) => principal.can(definition.permission));
-		const declared = {
-			...enabled.some((definition) => definition.kind === "tool") ? { tools: {} } : {},
-			...enabled.some((definition) => definition.kind === "prompt") ? { prompts: {} } : {},
-			...enabled.some((definition) => definition.kind === "resource") ? { resources: {} } : {}
-		};
-		const { onAudit, mcp: mcpOptions = {}, ...serverInfo } = options;
-		const server = new McpServer(serverInfo, {
-			...mcpOptions,
-			capabilities: {
-				...mcpOptions.capabilities,
-				...declared
-			}
-		});
-		for (const definition of enabled) definition.register(server, principal, context, onAudit);
-		return server;
-	};
-	return Object.assign(factory, {
-		permissions,
-		routePermissions,
-		permissionForRoute: (kind, name) => definitions.find((definition) => definition.kind === kind && (definition.routeMatches?.(name) ?? definition.routeName === name))?.permission
-	});
-}
-/**
-* Everything bound to one policy: `permission` accepts only what that policy can
-* grant, in all four places, from one call.
-*
-* The policy is a type carrier here and is never invoked. Authorization happens
-* once per request when the principal is resolved, not once per definition.
-*
-* ```ts
-* const { tool, prompt, resource, server } = authz(policy);
-* ```
-*/
-function bindAuthz(_permissions, principalOf, handlerContext) {
 	return {
-		tool: toolsFor(handlerContext),
-		prompt: promptsFor(handlerContext),
-		resource: resourcesFor(handlerContext),
-		server: (definitions, options) => buildServer(definitions, options, principalOf)
+		kind: "tool",
+		name: key
 	};
 }
-function authz(policy, options) {
-	if (options) return bindAuthz(policy, options.principal, (context) => context);
-	return bindAuthz(policy, (principal) => principal, (_context, principal) => ({ principal }));
+function isPrincipal(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	return typeof candidate.issuer === "string" && typeof candidate.sub === "string" && (candidate.email === void 0 || typeof candidate.email === "string") && Array.isArray(candidate.roles) && candidate.roles.every((role) => typeof role === "string") && Array.isArray(candidate.permissions) && candidate.permissions.every((permission) => typeof permission === "string") && typeof candidate.can === "function";
 }
 //#endregion
-export { AccessDeniedError, authz, createMcpFetch, createPrincipal, decodeMcpNameHeader, definePermissions, definePolicy, discoverOAuth, gate, identityFromAuth, jwksVerifier, reconcile, scopesForCapability, scopesFromMcpHeaders };
+export { AccessDeniedError, ApprovalRefusedError, authz, createMcpFetch, createPrincipal, decodeMcpNameHeader, definePermissions, definePolicy, discoverOAuth, gate, identityFromAuth, jwksVerifier, reconcile, scopesForCapability, scopesFromMcpHeaders };