mcp-authz 0.1.0 → 0.3.0

package/dist/proxy.js

@@ -0,0 +1,492 @@
+import { a as policyDenied, i as emitDecision, n as jwksVerifier, o as principalLabel, s as AccessDeniedError, t as identityFromAuth } from "./verifier-D6VIAYuT.js";
+import { a as forwardToUpstream, c as isJsonResponse, d as scopesForCapability, i as runScopedGate, l as readCappedBody, n as permissionForFlatMap, o as headersForRewrittenBody, s as isEventStream, t as capabilityLabel } from "./ladder-CUzOKudC.js";
+import { i as reconcile } from "./policy-BBp3Jq6G.js";
+import { UriTemplate, getOAuthProtectedResourceMetadataUrl, oauthMetadataResponse, requireBearerAuth } from "@modelcontextprotocol/server";
+import { err, isUnexpectedError, ok, run } from "awaitly";
+//#region src/catalogue.ts
+function filterByPermission(items, kind, principal, permissions) {
+	return items.filter((item) => {
+		const label = capabilityLabel(kind, item.name);
+		const permission = permissions.get(label);
+		if (permission === void 0) return false;
+		return principal.can(permission);
+	});
+}
+function filterToolsList(tools, principal, permissions) {
+	return filterByPermission(tools, "tool", principal, permissions);
+}
+function filterPromptsList(prompts, principal, permissions) {
+	return filterByPermission(prompts, "prompt", principal, permissions);
+}
+function filterResourcesList(resources, principal, permissions) {
+	return filterByPermission(resources, "resource", principal, permissions);
+}
+function filterResourceTemplatesList(templates, principal, permissions) {
+	return filterByPermission(templates, "resource", principal, permissions);
+}
+const LISTING_FIELDS = {
+	"tools/list": "tools",
+	"prompts/list": "prompts",
+	"resources/list": "resources",
+	"resources/templates/list": "resourceTemplates"
+};
+function isListingMethod(method) {
+	return method !== void 0 && Object.hasOwn(LISTING_FIELDS, method);
+}
+function isInvocationMethod(method) {
+	return method === "tools/call" || method === "prompts/get" || method === "resources/read";
+}
+function filterListingResult(method, result, principal, permissions) {
+	const field = LISTING_FIELDS[method];
+	const items = result[field];
+	if (!Array.isArray(items)) return result;
+	const filtered = field === "tools" ? filterToolsList(items, principal, permissions) : field === "prompts" ? filterPromptsList(items, principal, permissions) : field === "resources" ? filterResourcesList(items, principal, permissions) : filterResourceTemplatesList(items, principal, permissions);
+	return {
+		...result,
+		[field]: filtered
+	};
+}
+//#endregion
+//#region src/proxy.ts
+const OAUTH_SCOPE_TOKEN = /^[\x21\x23-\x5B\x5D-\x7E]+$/;
+function createMcpProxy(options) {
+	const { resourceServerUrl, oauthMetadata, upstream, policy, permissions: permissionsInput, requiredScopes = ["mcp"], supportedScopes, capabilityScopes, resourceUris, emitter, healthPath = "/health", maxRequestBytes = 1048576 } = options;
+	if (options.tokenVerifier && options.verifier) throw new Error("Pass either `tokenVerifier` or built-in `verifier` options, not both.");
+	const permissions = toPermissionMap(permissionsInput);
+	validatePermissions(permissions);
+	validateScopes(capabilityScopes, permissions);
+	const resources = buildResourceIndex(permissions, resourceUris);
+	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}'.`);
+	if (capabilityScopes && requiredScopes.length === 0) throw new Error("A declarative scope map needs at least one baseline scope.");
+	for (const [key, scopes] of Object.entries(capabilityScopes ?? {})) {
+		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 { error, warning } = reconcile(policy.roles, permissions);
+	if (warning) console.warn(warning);
+	if (error) throw new Error(error);
+	const advertisedScopes = [.../* @__PURE__ */ new Set([
+		...requiredScopes,
+		...supportedScopes ?? [],
+		...Object.values(capabilityScopes ?? {}).flatMap((scope) => typeof scope === "string" ? [scope] : [...scope])
+	])];
+	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 resourceMetadataUrl = getOAuthProtectedResourceMetadataUrl(resourceServerUrl);
+	const metadataOptions = {
+		oauthMetadata,
+		resourceServerUrl,
+		scopesSupported: advertisedScopes
+	};
+	const granted = new Set([...policy.roles.values()].flat());
+	const steps = {
+		/** Baseline OAuth: a valid token for this resource, carrying the baseline scopes. */
+		verify: async (request) => {
+			const answer = await requireBearerAuth({
+				verifier: tokenVerifier,
+				requiredScopes,
+				resourceMetadataUrl
+			})(request);
+			return answer instanceof Response ? err(answer) : ok(answer);
+		},
+		/** Identity to principal. Nothing granted is a refusal, not an empty pass. */
+		authorize: async (auth) => {
+			let principal;
+			try {
+				principal = policy(mapIdentity(auth));
+			} catch (error) {
+				if (error instanceof AccessDeniedError) return err(policyDenied(error));
+				throw error;
+			}
+			if (principal.permissions.length === 0) {
+				await emitDecision(options.onDecision, principal, "deny", "not_permitted", emitter);
+				return err(policyDenied(AccessDeniedError.notPermitted(principalLabel(principal))));
+			}
+			await emitDecision(options.onDecision, principal, "allow", void 0, emitter);
+			return ok(principal);
+		},
+		/** Classify, price the named capability, then step up the scope if one is configured. */
+		gate: async (request, auth, principal) => {
+			const can = (permission) => principal.can(permission);
+			const result = await runScopedGate({
+				request,
+				auth,
+				principal,
+				maxRequestBytes,
+				requiredScopes,
+				scoped: Boolean(capabilityScopes),
+				routed: true,
+				strictClassification: true,
+				scopeMap: capabilityScopes,
+				resolveCapabilityScopes: (route) => {
+					if (route.method !== "resources/read" || !route.name || !capabilityScopes) return void 0;
+					const labels = resources.filter((entry) => entry.matches(route.name)).map((e) => e.label);
+					if (labels.length === 0) return void 0;
+					return [...new Set(labels.flatMap((label) => scopesForCapability(route.method, label.slice(9), capabilityScopes, requiredScopes[0] ?? "mcp")))];
+				},
+				resolvePermission: (route) => permissionForFlatMap(permissions, route, resources, can),
+				onDecision: options.onDecision,
+				resourceMetadataUrl
+			});
+			return result.ok ? ok(result.preflight?.route) : err(result.response);
+		},
+		/** Refuse an invocation nobody priced, so a new upstream tool inherits nothing. */
+		price: async (principal, route) => {
+			const denied = await denyUnpricedInvocation({
+				principal,
+				permissions,
+				resources,
+				route,
+				onDecision: options.onDecision,
+				...emitter ? { emitter } : {}
+			});
+			return denied ? err(denied) : ok(void 0);
+		},
+		/** Swap the caller's credential for the service one and forward. */
+		forward: async (request) => ok(await forwardToUpstream(request, upstream)),
+		/** Hide from a listing what the caller could not have called anyway. */
+		filter: async (response, route, principal) => {
+			const method = route?.method;
+			if (!isListingMethod(method)) return ok(response);
+			if (isEventStream(response)) return ok(filterEventStreamListing(response, method, principal, permissions, maxRequestBytes, idOf(route)));
+			if (isJsonResponse(response)) {
+				const filtered = await filterJsonListing(response, method, principal, permissions, maxRequestBytes);
+				return filtered ? ok(filtered) : err(unfilterable(`${method} was over ${maxRequestBytes} bytes or not readable as JSON-RPC`, idOf(route)));
+			}
+			return err(unfilterable(`${method} came back as '${response.headers.get("content-type") ?? "no content type"}'`, idOf(route)));
+		}
+	};
+	return async function mcpProxy(request) {
+		const metadata = oauthMetadataResponse(request, metadataOptions);
+		if (metadata) return metadata;
+		const { pathname } = new URL(request.url);
+		if (pathname === healthPath) return Response.json({
+			ok: true,
+			mode: "proxy",
+			resource: resourceServerUrl.href,
+			authorization: {
+				mode: "policy",
+				roles: policy.roles.size,
+				permissions: granted.size
+			},
+			capabilities: permissions.size
+		});
+		if (pathname !== resourceServerUrl.pathname) return new Response(`No MCP endpoint at ${pathname}. This proxy answers on ${resourceServerUrl.pathname}, which is also the audience its tokens must carry.\n`, {
+			status: 404,
+			headers: { "Content-Type": "text/plain" }
+		});
+		const result = await run(steps, async (s) => {
+			const auth = await s.verify(request);
+			const principal = await s.authorize(auth);
+			const route = await s.gate(request, auth, principal);
+			await s.price(principal, route);
+			const upstreamResponse = await s.forward(request);
+			return s.filter(upstreamResponse, route, principal);
+		});
+		if (result.ok) return result.value;
+		if (isUnexpectedError(result.error)) throw result.error.cause;
+		return result.error;
+	};
+}
+/**
+* Refuse any invocation the permission map does not price.
+*
+* `runScopedGate` refuses a capability the caller may not reach. This refuses
+* one nobody priced at all, which in a proxy is the more common shape: the
+* upstream grew a tool since the map was recorded, and an unpriced tool must
+* fail closed rather than inherit the service credential.
+*/
+async function denyUnpricedInvocation(options) {
+	const { route, principal, emitter } = options;
+	if (!route || !isInvocationMethod(route.method)) return void 0;
+	const refuse = async (because) => {
+		await emitDecision(options.onDecision, principal, "deny", "policy_denied", emitter);
+		return policyDenied(AccessDeniedError.notPermitted(principalLabel(principal), because));
+	};
+	if (!route.name) return refuse(`a ${route.method} that names no capability`);
+	const permission = permissionForFlatMap(options.permissions, route, options.resources, (candidate) => principal.can(candidate));
+	if (permission === void 0) return refuse(`the capability '${route.name}' is not priced in the permission map`);
+	if (!principal.can(permission)) return refuse(`the permission '${permission}'`);
+}
+/**
+* Match each priced `resource:` label to the URIs it covers.
+*
+* Exact URIs are tried before templates, so a resource registered at its own
+* address is never answered by a template that happens to span it.
+*/
+function buildResourceIndex(permissions, resourceUris) {
+	const exact = [];
+	const templated = [];
+	const unpriced = [];
+	for (const [label, permission] of permissions) {
+		if (!label.startsWith("resource:")) continue;
+		const uri = resourceUris?.[label];
+		if (uri === void 0) {
+			unpriced.push(label);
+			continue;
+		}
+		if (uri.includes("{")) {
+			const template = new UriTemplate(uri);
+			templated.push({
+				label,
+				permission,
+				matches: (target) => template.match(target) !== null
+			});
+		} else exact.push({
+			label,
+			permission,
+			matches: (target) => target === uri
+		});
+	}
+	if (unpriced.length > 0) throw new Error(`A proxy authorizes resources/read by URI, and these priced resources carry none:\n${unpriced.map((label) => `  ${label}`).join("\n")}\n\nPass \`resourceUris\` mapping each label to its uri or uriTemplate. \`recordCapabilities\` writes one for you; see mcp-authz/testing.`);
+	for (const label of Object.keys(resourceUris ?? {})) if (!permissions.has(label)) throw new Error(`resourceUris key '${label}' names no priced capability.`);
+	return [...exact, ...templated];
+}
+/**
+* The filtered response, or `undefined` when the body was over the cap or not
+* readable as JSON-RPC.
+*
+* The body is read once, under the same byte cap the SSE path uses: a catalogue
+* has to be held whole to be filtered, so an upstream that sends an unbounded
+* one would otherwise choose how much memory this spends.
+*/
+async function filterJsonListing(response, method, principal, permissions, maxBytes) {
+	const raw = await readCappedBody(response.body, maxBytes);
+	if (raw === void 0) return void 0;
+	let payload;
+	try {
+		payload = JSON.parse(raw);
+	} catch {
+		return;
+	}
+	const filtered = filterMessage(payload, method, principal, permissions);
+	if (filtered === void 0) return void 0;
+	return Response.json(filtered, {
+		status: response.status,
+		headers: headersForRewrittenBody(response)
+	});
+}
+/**
+* One JSON-RPC message with its listing filtered, or `undefined` when this
+* cannot tell what the message carries.
+*
+* An error reply and a progress notification carry no catalogue and pass
+* through untouched. Anything unrecognisable does not, because the whole point
+* of reading the body is to know whether a capability is hiding in it.
+*/
+function filterMessage(payload, method, principal, permissions) {
+	if (typeof payload !== "object" || payload === null || Array.isArray(payload)) return void 0;
+	const message = payload;
+	if (!("result" in message)) return "error" in message || "method" in message ? message : void 0;
+	const result = message.result;
+	if (typeof result !== "object" || result === null) return void 0;
+	return {
+		...message,
+		result: filterListingResult(method, result, principal, permissions)
+	};
+}
+/**
+* Filter a listing carried over SSE, event by event as it arrives.
+*
+* Streamed rather than buffered: the body is an upstream's to size, and reading
+* it to the end before answering would both hold a catalogue hostage to a slow
+* server and let that server decide how much memory this process spends.
+*
+* Framing is read properly rather than by prefix. `data:` needs no space after
+* it, and one payload may arrive across several `data:` lines that the client
+* rejoins — a filter that only understands `data: ` passes both straight
+* through, which is the whole catalogue, unfiltered.
+*/
+function filterEventStreamListing(response, method, principal, permissions, maxEventBytes, id) {
+	const decoder = new TextDecoder();
+	const encoder = new TextEncoder();
+	let buffered = "";
+	let started = false;
+	/**
+	* Where the search for a terminator has already looked, and how many bytes
+	* the pending event holds.
+	*
+	* Both are carried rather than recomputed. Rescanning and re-encoding the
+	* whole buffer on every chunk is quadratic in the number of chunks, and an
+	* upstream chooses the chunk size: one 900 KB event delivered 64 bytes at a
+	* time costs seconds of CPU that way, under the cap, on one connection.
+	*
+	* Bytes rather than `String.length`, which counts UTF-16 units — for anything
+	* outside ASCII that reads a byte cap as up to three times larger.
+	*/
+	let scanned = 0;
+	let bufferedBytes = 0;
+	const OVERLAP = 3;
+	const filterEvent = (block) => {
+		const lines = block.split(/\r\n|\n|\r/);
+		const data = [];
+		const rest = [];
+		for (const line of lines) {
+			if (line.startsWith(":")) continue;
+			const separator = line.indexOf(":");
+			if ((separator === -1 ? line : line.slice(0, separator)) !== "data") {
+				if (line.length > 0) rest.push(line);
+				continue;
+			}
+			const value = separator === -1 ? "" : line.slice(separator + 1);
+			data.push(value.startsWith(" ") ? value.slice(1) : value);
+		}
+		if (data.length === 0) return block;
+		let payload;
+		try {
+			payload = JSON.parse(data.join("\n"));
+		} catch {
+			return `event: message\ndata: ${JSON.stringify(unfilterableBody(`${method} carried an unreadable event`, id))}`;
+		}
+		const body = filterMessage(payload, method, principal, permissions) ?? unfilterableBody(`${method} carried an unrecognisable event`, id);
+		return [...rest, `data: ${JSON.stringify(body)}`].join("\n");
+	};
+	const drain = (controller) => {
+		for (;;) {
+			const from = Math.max(0, scanned - OVERLAP);
+			const found = EVENT_END.exec(buffered.slice(from));
+			const at = found ? from + found.index : -1;
+			if (!found || buffered.endsWith("\r") && at + found[0].length === buffered.length) {
+				scanned = buffered.length;
+				return bufferedBytes <= maxEventBytes;
+			}
+			const block = buffered.slice(0, at);
+			if (encoder.encode(block).length > maxEventBytes) return false;
+			const consumed = encoder.encode(buffered.slice(0, at + found[0].length)).length;
+			buffered = buffered.slice(at + found[0].length);
+			bufferedBytes -= consumed;
+			scanned = 0;
+			controller.enqueue(encoder.encode(filterEvent(block) + found[0]));
+		}
+	};
+	const stream = new TransformStream({
+		transform(chunk, controller) {
+			let text = decoder.decode(chunk, { stream: true });
+			if (!started) {
+				started = true;
+				if (text.startsWith("")) text = text.slice(1);
+			}
+			buffered += text;
+			bufferedBytes += encoder.encode(text).length;
+			if (drain(controller)) return;
+			controller.enqueue(encoder.encode(`event: message\ndata: ${JSON.stringify(unfilterableBody(`${method} sent an event over ${maxEventBytes} bytes`, id))}\n\n`));
+			buffered = "";
+			bufferedBytes = 0;
+			controller.terminate();
+		},
+		flush(controller) {
+			buffered += decoder.decode();
+			if (buffered.trim().length === 0) return;
+			controller.enqueue(encoder.encode(bufferedBytes > maxEventBytes ? `event: message\ndata: ${JSON.stringify(unfilterableBody(`${method} sent an event over ${maxEventBytes} bytes`, id))}\n\n` : filterEvent(buffered)));
+		}
+	});
+	return new Response(response.body?.pipeThrough(stream) ?? null, {
+		status: response.status,
+		headers: headersForRewrittenBody(response)
+	});
+}
+/**
+* Two line terminators, which is what ends an event.
+*
+* Each may independently be CRLF, LF or a bare CR, so the nine combinations all
+* count — an upstream is under no obligation to be consistent between the two.
+* A lone CR only counts when no LF follows, or a single CRLF would decompose
+* into two terminators and every line would look like the end of an event.
+*/
+const LINE_END = String.raw`(?:\r\n|\r(?!\n)|\n)`;
+const EVENT_END = new RegExp(LINE_END + LINE_END);
+/**
+* A refusal the client can match to what it asked.
+*
+* An error carrying `id: null` answers no pending request, so a client is
+* entitled to ignore it — and then waits on a listing that will never arrive for
+* as long as the stream stays open. The id comes from the request body this
+* already validated.
+*/
+function unfilterableBody(because, id = null) {
+	return {
+		jsonrpc: "2.0",
+		id,
+		error: {
+			code: -32010,
+			message: `Bad Gateway: this catalogue could not be filtered — ${because}.`
+		}
+	};
+}
+/** The JSON-RPC id of the request a route came from, when it carried one. */
+function idOf(route) {
+	const body = route?.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;
+}
+/**
+* A catalogue withheld.
+*
+* Absence from a listing is not the security boundary — naming a hidden
+* capability is still refused — but a listing served unfiltered hands every
+* caller the map, so an unreadable one fails closed rather than through.
+*/
+function unfilterable(because, id = null) {
+	return Response.json(unfilterableBody(because, id), { status: 502 });
+}
+function toPermissionMap(permissions) {
+	if (permissions instanceof Map) return new Map(permissions);
+	return new Map(Object.entries(permissions));
+}
+function validatePermissions(permissions) {
+	for (const [label, permission] of permissions) {
+		if (!label || typeof label !== "string") throw new Error("permissions keys must be non-empty strings.");
+		if (!permission || typeof permission !== "string") throw new Error(`permissions['${label}'] must be a non-empty string.`);
+	}
+}
+function validateScopes(capabilityScopes, permissions) {
+	if (!capabilityScopes) return;
+	const named = /* @__PURE__ */ new Set();
+	for (const key of Object.keys(capabilityScopes)) {
+		const route = routeFromScopeKey(key);
+		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);
+		const label = route.kind === "tool" ? route.name : canonical;
+		if (!(permissions.has(label) || route.kind === "tool" && permissions.has(`tool:${route.name}`))) throw new Error(`Scope map key '${key}' names no registered capability.`);
+	}
+}
+function routeFromScopeKey(key) {
+	for (const kind of [
+		"tool",
+		"prompt",
+		"resource"
+	]) {
+		const prefix = `${kind}:`;
+		if (key.startsWith(prefix)) return {
+			kind,
+			name: key.slice(prefix.length)
+		};
+	}
+	return {
+		kind: "tool",
+		name: key
+	};
+}
+//#endregion
+export { createMcpProxy };

package/dist/testing.d.ts

@@ -0,0 +1,44 @@
+import { n as UNASSIGNED, r as toPermissionsModule, t as PermissionMapRecord } from "./permissions-module-DxCHuE-N.js";
+import { McpServer } from "@modelcontextprotocol/server";
+//#region src/testing.d.ts
+/**
+ * What a caller can reach, read from the server rather than from your notes.
+ *
+ * A permission map has to name every capability a server registers, and nothing
+ * generates that list today — you write it by hand and hope. This connects a
+ * real client to your own server over an in-memory pair and asks it, so the
+ * answer is the one a caller would get.
+ *
+ * Build the server *ungated* here. A gated server answers per principal, so
+ * listing one would hand you a map missing exactly the capabilities that most
+ * need a price.
+ */
+type CapabilityRecord = {
+  /** Every capability, labelled as `gate()` labels them, sorted. */
+  names: string[];
+  /** A digest per capability, so a snapshot can catch one changing under you. */
+  fingerprints: Record<string, string>;
+  /**
+   * `resource:` labels to the URI or URI template each answers on.
+   *
+   * A listing names a resource; a read names a URI, and only the server knows
+   * which URIs a label covers. `createMcpProxy` authorizes reads by URI, so it
+   * needs this alongside the permission map — and refuses to boot without it.
+   */
+  resourceUris: Record<string, string>;
+};
+declare function recordCapabilities(factory: () => McpServer | Promise<McpServer>): Promise<CapabilityRecord>;
+/**
+ * Record a server you can only reach by URL.
+ *
+ * The objection that rules out listing a *gated* server does not apply here: an
+ * upstream reached with a service credential answers with everything it has, so
+ * the map is complete. Pass `fetch` to drive a handler directly instead of a
+ * socket.
+ */
+declare function recordUpstream(url: string | URL, options?: {
+  bearer?: string;
+  fetch?: typeof fetch;
+}): Promise<CapabilityRecord>;
+//#endregion
+export { CapabilityRecord, type PermissionMapRecord, UNASSIGNED, recordCapabilities, recordUpstream, toPermissionsModule };