mcp-authz 0.4.0 → 0.5.0

package/dist/definitions-CZVk-j1C.d.ts

@@ -0,0 +1,5 @@
+import { Client } from "@modelcontextprotocol/client";
+//#region src/definitions.d.ts
+type Definition = Record<string, unknown>;
+//#endregion
+export { Definition as t };

package/dist/definitions-CyIy4YSZ.js

@@ -0,0 +1,132 @@
+//#region src/definitions.ts
+/**
+* Left out of a definition: servers stamp these per build, the model does not
+* read them, and a record that churns teaches people to ignore its diff. Every
+* other field is kept, so the next field the spec adds is covered by default.
+*/
+const UNRECORDED = /* @__PURE__ */ new Set(["_meta", "icons"]);
+/**
+* Where a server's own `instructions` are recorded: beside its capabilities,
+* because they reach the model the same way a description does, and a server
+* that keeps every tool identical could otherwise change what it tells the
+* model there instead.
+*/
+const INSTRUCTIONS = "server:instructions";
+/** The labels a record must cover and does not, so a gap fails loudly rather than passing unchecked. */
+function missingDefinitions(labels, definitions) {
+	return [...labels].filter((label) => {
+		const definition = definitions.get(label);
+		return typeof definition !== "object" || definition === null || Array.isArray(definition);
+	});
+}
+/** The parts of a listed tool, prompt or resource that are held to the record. */
+function definitionOf(item) {
+	return canonical(Object.fromEntries(Object.entries(item).filter(([field]) => !UNRECORDED.has(field))));
+}
+/** The fields that differ, compared regardless of key order. */
+function changedFields(recorded, live) {
+	const fields = new Set([...Object.keys(recorded), ...Object.keys(live)].filter((f) => !UNRECORDED.has(f)));
+	const same = (a, b) => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+	return [...fields].sort().filter((field) => !same(recorded[field], live[field]));
+}
+/**
+* Key order is an accident of how a value was built, so sort it away. Without
+* this an SDK that emitted the same definition in a different order would churn
+* every record, and teach people to ignore the diff.
+*/
+function canonical(value) {
+	if (Array.isArray(value)) return value.map(canonical);
+	if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, inner]) => [key, canonical(inner)]));
+	return value;
+}
+/**
+* Characters a person reviewing the text cannot see but a model reads:
+* zero-width characters, bidirectional overrides that reorder what is
+* displayed, and the Unicode tag block, which can spell out a whole hidden
+* sentence. Not U+200D, the joiner inside every family or flag emoji: flagging
+* it would flag honest output until nobody reads the flag.
+*/
+const INVISIBLE = /[\u200B\u200C\u200E\u200F\u202A-\u202E\u2060-\u2064\u2066-\u2069\uFEFF]|[\u{E0000}-\u{E007F}]/u;
+/**
+* Wording seen in published tool-poisoning attacks: text addressed to the model
+* rather than describing the tool. A short list on purpose. It flags a
+* definition for a closer read and decides nothing, and a long list would flag
+* honest tools until nobody reads the flag.
+*/
+const ADDRESSED_TO_MODEL = [
+	/ignore (all |any )?(previous|prior|above) (instructions|prompts)/i,
+	/<\/?(important|system|instructions?)>/i,
+	/do not (tell|inform|mention|alert|notify) the user/i,
+	/without (telling|informing|asking) the user/i,
+	/\bid_rsa\b|~\/\.ssh|\.aws\/credentials/i
+];
+/**
+* Text with each invisible character spelled out as `\u{200B}`, so a person
+* reading a listing or a diff sees what the model will read.
+*/
+function reveal(text) {
+	return text.replace(new RegExp(INVISIBLE.source, "gu"), (char) => {
+		return `\\u{${char.codePointAt(0).toString(16).toUpperCase()}}`;
+	});
+}
+/** Why a definition deserves a closer read before it is approved, if it does. */
+function suspicious(definition) {
+	const text = JSON.stringify(definition);
+	const reasons = [];
+	if (INVISIBLE.test(text)) reasons.push("contains invisible characters");
+	if (ADDRESSED_TO_MODEL.some((pattern) => pattern.test(text))) reasons.push("contains text addressed to the model");
+	return reasons;
+}
+const LISTED = [
+	["tools", ""],
+	["prompts", "prompt:"],
+	["resources", "resource:"],
+	["resourceTemplates", "resource:"]
+];
+/**
+* Every listing that arrives on a client transport, as the server wrote it and
+* keyed by the label `gate()` gives it. A record is compared against what the
+* proxy and `wrap` read off the wire, so it is taken from the wire too, not from
+* what the SDK parsed it into. Install after `client.connect`, which sets the
+* handler this wraps.
+*/
+function captureListings(transport) {
+	const listed = /* @__PURE__ */ new Map();
+	const deliver = transport.onmessage;
+	transport.onmessage = (message, ...rest) => {
+		const result = message.result;
+		for (const [field, prefix] of LISTED) {
+			const items = result?.[field];
+			if (!Array.isArray(items)) continue;
+			for (const item of items) listed.set(`${prefix}${String(item.name)}`, item);
+		}
+		deliver?.(message, ...rest);
+	};
+	return listed;
+}
+/**
+* Connect a client and list everything the server advertises, returning each
+* item as the server wrote it, keyed by label, with its instructions under
+* `server:instructions`. One function for recording a catalogue and for
+* checking it later, so the two cannot read a server differently.
+*
+* Only what the server says it has is asked for: the SDK answers an
+* unadvertised list with a warning on stdout, which is the generated module
+* when a caller redirects it. The SDK follows `nextCursor` itself.
+*/
+async function listCatalogue(client, transport) {
+	const listed = captureListings(transport);
+	await client.connect(transport);
+	const instructions = client.getInstructions();
+	if (instructions !== void 0) listed.set(INSTRUCTIONS, { instructions });
+	const advertised = client.getServerCapabilities() ?? {};
+	await Promise.all([
+		advertised.tools && client.listTools(),
+		advertised.prompts && client.listPrompts(),
+		advertised.resources && client.listResources(),
+		advertised.resources && client.listResourceTemplates()
+	]);
+	return listed;
+}
+//#endregion
+export { listCatalogue as a, suspicious as c, definitionOf as i, captureListings as n, missingDefinitions as o, changedFields as r, reveal as s, INSTRUCTIONS as t };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { _ as Identity, a as PermissionCatalog, c as PolicySpec, d as createPrincipal, f as definePermissions, g as DenialReason, h as AccessDeniedError, i as MatchedRule, l as Principal, m as reconcile, n as Explanation, o as PermissionOf, p as definePolicy, r as Match, s as Policy, u as Rule } from "./policy-DuZbwrKf.js";
-import { a as AuditDeliveryFailure, c as AuditSink, d as PromptConfig, f as ResourceConfig, h as authz, i as ApprovalSink, l as Capability, m as ToolConfig, n as ApprovalRefusedError, o as AuditErrorSink, p as ServerOptions, r as ApprovalRequest, s as AuditEvent, t as ApprovalDecision, u as Definition } from "./tools-BQE1O-7P.js";
+import { a as AuditDeliveryFailure, c as AuditSink, d as PromptConfig, f as ResourceConfig, h as authz, i as ApprovalSink, l as Capability, m as ToolConfig, n as ApprovalRefusedError, o as AuditErrorSink, p as ServerOptions, r as ApprovalRequest, s as AuditEvent, t as ApprovalDecision, u as Definition } from "./tools-C1dZESYK.js";
 import { a as AuthorizationDecisionSink, i as AuthorizationDecisionEvent, n as identityFromAuth, r as jwksVerifier, t as VerifierOptions } from "./verifier-DF6gUMQ6.js";
 import { a as scopesForCapability, i as decodeMcpNameHeader, n as ScopeRequirement, o as scopesFromMcpHeaders, r as ToolScopeMap, s as TrustedMcpRoute, t as CapabilityScopeMap } from "./ladder-D18eJ7tD.js";
 import { AuthInfo, McpServer, OAuthMetadata, OAuthTokenVerifier } from "@modelcontextprotocol/server";
@@ -161,7 +161,11 @@ type McpFetchOptions<TContext, P extends string = string> = {
     permissions?: ReadonlyMap<string, string>;
     /** Protocol route to permission, used to distinguish policy denial from scope step-up. */
     routePermissions?: ReadonlyMap<string, string>;
-    routeNameFor?: (kind: 'tool' | 'prompt' | 'resource', name: string) => string | undefined;
+    /** Every registration a concrete request name reaches, so overlapping ones are all enforced. */
+    routesFor?: (kind: 'tool' | 'prompt' | 'resource', name: string) => readonly {
+      routeName: string;
+      permission: string;
+    }[];
     /** Resolve exact and templated protocol routes to their declared permission. */
     permissionForRoute?: (kind: 'tool' | 'prompt' | 'resource', name: string) => string | undefined;
   };

package/dist/index.js

@@ -1,5 +1,5 @@
 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 { d as scopesForCapability, f as scopesFromMcpHeaders, i as runScopedGate, r as permissionForRoute, u as decodeMcpNameHeader } from "./ladder-6TnD3hTJ.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
@@ -308,11 +308,15 @@ function buildServer(definitions, options, principalOf) {
 		for (const definition of enabled) definition.register(server, principal, context, guards);
 		return server;
 	};
+	const routesFor = (kind, name) => definitions.filter((definition) => definition.kind === kind && (definition.routeMatches?.(name) ?? definition.routeName === name)).map((definition) => ({
+		routeName: definition.routeName,
+		permission: definition.permission
+	}));
 	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
+		routesFor,
+		permissionForRoute: (kind, name) => routesFor(kind, name)[0]?.permission
 	});
 }
 /**
@@ -509,6 +513,7 @@ function createMcpFetch(options) {
 			throw error;
 		}
 		const scoped = Boolean(scopeMap || scopesForRequest);
+		const resourceRoutes = (route) => route.method === "resources/read" && route.name ? createServer.routesFor?.("resource", route.name) ?? [] : [];
 		const routed = Boolean(createServer.permissionForRoute ?? createServer.routePermissions);
 		const gateResult = await runScopedGate({
 			request,
@@ -520,12 +525,16 @@ function createMcpFetch(options) {
 			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");
+				const matches = resourceRoutes(route);
+				if (matches.length === 0 || !scopeMap) return void 0;
+				return [...new Set(matches.flatMap((match) => scopesForCapability(route.method, match.routeName, scopeMap, requiredScopes[0] ?? "mcp")))];
 			},
 			scopesForRequest,
-			resolvePermission: (route) => permissionForRoute(createServer.permissionForRoute, createServer.routePermissions, route),
+			resolvePermission: (route) => {
+				const matches = resourceRoutes(route);
+				if (matches.length === 0) return permissionForRoute(createServer.permissionForRoute, createServer.routePermissions, route);
+				return (matches.find((match) => principal && !principal.can(match.permission)) ?? matches[0])?.permission;
+			},
 			onDecision: options.onDecision,
 			...emitter ? { emitter } : {},
 			resourceMetadataUrl

package/dist/{ladder-CUzOKudC.js → ladder-6TnD3hTJ.js}

@@ -1,4 +1,5 @@
 import { a as policyDenied, i as emitDecision, o as principalLabel, s as AccessDeniedError } from "./verifier-D6VIAYuT.js";
+import { r as parseChecked, t as hasDuplicateKey } from "./strict-json-DLKOgsGE.js";
 import { OAuthError, OAuthErrorCode, bearerAuthChallengeResponse, classifyInboundRequest, isJsonContentType } from "@modelcontextprotocol/server";
 //#region src/scopes.ts
 const BASE64_SENTINEL = /^=\?base64\?([A-Za-z0-9+/]*(?:={0,2}))\?=$/;
@@ -355,10 +356,11 @@ async function preflightScopedRequest(request, maxBytes) {
 	if (raw === void 0) return protocolError(413, -32e3, `Request body exceeds the ${maxBytes} byte limit.`);
 	let body;
 	try {
-		body = JSON.parse(raw);
+		body = parseChecked(raw);
 	} catch {
 		return protocolError(400, -32700, "Parse error: the request body is not valid JSON");
 	}
+	if (hasDuplicateKey(raw)) return protocolError(400, -32600, "Invalid Request: the body repeats a key, which parsers resolve differently.", void 0, requestId(body));
 	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") {

package/dist/openapi.d.ts

@@ -1,7 +1,7 @@
 import { _ as Identity, l as Principal, s as Policy } from "./policy-DuZbwrKf.js";
-import { c as AuditSink, o as AuditErrorSink } from "./tools-BQE1O-7P.js";
+import { c as AuditSink, o as AuditErrorSink } from "./tools-C1dZESYK.js";
 import { a as AuthorizationDecisionSink, t as VerifierOptions } from "./verifier-DF6gUMQ6.js";
-import { t as PermissionMapRecord } from "./permissions-module-Cr0K1a7x.js";
+import { t as PermissionMapRecord } from "./permissions-module-TOpt20D4.js";
 import { AuthInfo, OAuthMetadata, OAuthTokenVerifier } from "@modelcontextprotocol/server";
 //#region src/openapi.d.ts
 /**

package/dist/{permissions-module-Cr0K1a7x.d.ts → permissions-module-TOpt20D4.d.ts}

@@ -10,8 +10,8 @@
 type PermissionMapRecord = {
   /** Every capability, sorted, labelled the way the gate labels it. */
   names: string[];
-  /** A digest per capability, when the source can produce one. */
-  fingerprints?: Record<string, string>;
+  /** What each capability says to the model, when the source can record it. */
+  definitions?: Record<string, unknown>;
   /** `resource:` labels to the URI or template each answers on. */
   resourceUris?: Record<string, string>;
 };

package/dist/proxy.d.ts

@@ -1,6 +1,7 @@
 import { _ as Identity, s as Policy } from "./policy-DuZbwrKf.js";
 import { a as AuthorizationDecisionSink, t as VerifierOptions } from "./verifier-DF6gUMQ6.js";
 import { t as CapabilityScopeMap } from "./ladder-D18eJ7tD.js";
+import { t as Definition } from "./definitions-CZVk-j1C.js";
 import { AuthInfo, OAuthMetadata, OAuthTokenVerifier } from "@modelcontextprotocol/server";
 //#region src/upstream.d.ts
 type UpstreamConfig = {
@@ -23,6 +24,18 @@ export type McpProxyOptions<P extends string = string> = {
   upstream: UpstreamConfig;
   /** Flat permission map — same labels as `gate()` and `recordCapabilities`. */
   permissions: Readonly<Record<string, P>> | ReadonlyMap<string, P>;
+  /**
+   * What each priced capability said to the model when it was recorded: the
+   * `DEFINITIONS` that `mcp-authz record` writes beside `PERMISSIONS`.
+   *
+   * A permission prices a name, and the upstream decides what stands behind
+   * it. Without this, an upstream could keep an approved tool's name and
+   * rewrite its description to steer the model, or add an argument to carry
+   * data out, and every caller would be served the new one. With it, a
+   * capability whose definition has changed is left out of listings and its
+   * invocations are refused until someone re-records and approves the change.
+   */
+  definitions: Readonly<Record<string, Definition>>;
   /**
    * `resource:<label>` to the URI or URI template it answers on.
    *