mcp-authz 0.3.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";
@@ -8,7 +8,7 @@ type DiscoverOptions = {
   /** Swap in for tests, or to add a timeout or proxy. Defaults to global fetch. */
   fetch?: typeof globalThis.fetch;
 };
-declare function discoverOAuth(issuer: string, options?: DiscoverOptions): Promise<OAuthMetadata>;
+export declare function discoverOAuth(issuer: string, options?: DiscoverOptions): Promise<OAuthMetadata>;
 //#endregion
 //#region src/gate.d.ts
 /**
@@ -60,7 +60,7 @@ type GateOptions = {
 };
 /** Bare name for a tool, `prompt:`/`resource:` prefixed for the rest. */
 type PermissionMap<P extends string> = Readonly<Record<string, P>> | ReadonlyMap<string, P>;
-declare function gate<P extends string>(server: McpServer, principal: Principal<P>, permissions: PermissionMap<P>, options?: GateOptions): McpServer;
+export declare function gate<P extends string>(server: McpServer, principal: Principal<P>, permissions: PermissionMap<P>, options?: GateOptions): McpServer;
 //#endregion
 //#region src/handler.d.ts
 /**
@@ -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;
   };
@@ -189,20 +193,20 @@ type McpFetchOptions<TContext, P extends string = string> = {
  * policy ran first and already refused anyone it grants nothing. Saying so here
  * saves every caller the same non-null assertion.
  */
-declare function createMcpFetch<TContext = Principal<string>, P extends string = string>(options: Omit<McpFetchOptions<TContext, P>, 'policy' | 'authorize' | 'resolve'> & {
+export declare function createMcpFetch<TContext = Principal<string>, P extends string = string>(options: Omit<McpFetchOptions<TContext, P>, 'policy' | 'authorize' | 'resolve'> & {
   policy: Policy<P>;
   authorize?: never;
   resolve?: (identity: Identity, principal: Principal<P>) => Promise<TContext> | TContext;
 }): (request: Request) => Promise<Response>;
-declare function createMcpFetch<TContext = Principal<string>, P extends string = string>(options: Omit<McpFetchOptions<TContext, P>, 'policy' | 'authorize' | 'resolve'> & {
+export declare function createMcpFetch<TContext = Principal<string>, P extends string = string>(options: Omit<McpFetchOptions<TContext, P>, 'policy' | 'authorize' | 'resolve'> & {
   policy?: never;
   authorize: (identity: Identity) => Promise<Principal<P>> | Principal<P>;
   resolve?: (identity: Identity, principal: Principal<P>) => Promise<TContext> | TContext;
 }): (request: Request) => Promise<Response>;
-declare function createMcpFetch<TContext = Principal<string>, P extends string = string>(options: Omit<McpFetchOptions<TContext, P>, 'policy' | 'authorize' | 'resolve'> & {
+export declare function createMcpFetch<TContext = Principal<string>, P extends string = string>(options: Omit<McpFetchOptions<TContext, P>, 'policy' | 'authorize' | 'resolve'> & {
   policy?: never;
   authorize?: never;
   resolve: (identity: Identity, principal: undefined) => Promise<TContext> | TContext;
 }): (request: Request) => Promise<Response>;
 //#endregion
-export { AccessDeniedError, type ApprovalDecision, ApprovalRefusedError, type ApprovalRequest, type ApprovalSink, type AuditDeliveryFailure, type AuditErrorSink, type AuditEvent, type AuditSink, type AuthorizationDecisionEvent, type AuthorizationDecisionSink, type Capability, type CapabilityScopeMap, type Definition, type DenialReason, type DiscoverOptions, type Explanation, type GateOptions, type Identity, type Match, type MatchedRule, type McpFetchOptions, type PermissionCatalog, type PermissionMap, type PermissionOf, type Policy, type PolicySpec, type Principal, type PromptConfig, type ResourceConfig, type Rule, type ScopeRequirement, type ServerOptions, type ToolConfig, type ToolScopeMap, type TrustedMcpRoute, type VerifierOptions, authz, createMcpFetch, createPrincipal, decodeMcpNameHeader, definePermissions, definePolicy, discoverOAuth, gate, identityFromAuth, jwksVerifier, reconcile, scopesForCapability, scopesFromMcpHeaders };
+export { AccessDeniedError, type ApprovalDecision, ApprovalRefusedError, type ApprovalRequest, type ApprovalSink, type AuditDeliveryFailure, type AuditErrorSink, type AuditEvent, type AuditSink, type AuthorizationDecisionEvent, type AuthorizationDecisionSink, type Capability, type CapabilityScopeMap, type Definition, type DenialReason, type DiscoverOptions, type Explanation, type GateOptions, type Identity, type Match, type MatchedRule, type McpFetchOptions, type PermissionCatalog, type PermissionMap, type PermissionOf, type Policy, type PolicySpec, type Principal, type PromptConfig, type ResourceConfig, type Rule, type ScopeRequirement, type ServerOptions, type ToolConfig, type ToolScopeMap, type TrustedMcpRoute, type VerifierOptions, authz, createPrincipal, decodeMcpNameHeader, definePermissions, definePolicy, identityFromAuth, jwksVerifier, reconcile, scopesForCapability, scopesFromMcpHeaders };

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/node.d.ts

@@ -1,6 +1,6 @@
 import { Server } from "node:http";
 //#region src/node.d.ts
-type ListenMcpOptions = {
+export type ListenMcpOptions = {
   port: number;
   /** Log label. Defaults to `mcp-authz`. */
   name?: string;
@@ -11,6 +11,5 @@ type ListenMcpOptions = {
  * Bind a `createMcpFetch` handler to every interface. Safe because the
  * bearer gate is the security boundary, not the bind address.
  */
-declare function listenMcp(fetch: (request: Request) => Promise<Response>, options: ListenMcpOptions): Promise<Server>;
-//#endregion
-export { ListenMcpOptions, listenMcp };
+export declare function listenMcp(fetch: (request: Request) => Promise<Response>, options: ListenMcpOptions): Promise<Server>;
+//#endregion

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-DxCHuE-N.js";
+import { t as PermissionMapRecord } from "./permissions-module-TOpt20D4.js";
 import { AuthInfo, OAuthMetadata, OAuthTokenVerifier } from "@modelcontextprotocol/server";
 //#region src/openapi.d.ts
 /**
@@ -22,11 +22,11 @@ import { AuthInfo, OAuthMetadata, OAuthTokenVerifier } from "@modelcontextprotoc
  * rides along untouched, so a document with `components`, `webhooks` or a
  * vendor extension comes back out the way it went in.
  */
-type OpenApiDocument = {
+export type OpenApiDocument = {
   paths?: Record<string, Record<string, unknown> | undefined>;
   [key: string]: unknown;
 };
-type OpenApiOperation = {
+export type OpenApiOperation = {
   /** The document's own `operationId`, which is what the permission map is keyed by. */
   operationId: string;
   /** Lowercased HTTP method. */
@@ -34,7 +34,7 @@ type OpenApiOperation = {
   /** The templated path, e.g. `/cases/{id}`. */
   path: string;
 };
-type OperationRecord = PermissionMapRecord & {
+export type OperationRecord = PermissionMapRecord & {
   /** Every operation the document describes, in document order. */
   operations: OpenApiOperation[];
 };
@@ -47,7 +47,7 @@ type OperationRecord = PermissionMapRecord & {
  * role grants and the boot refuses until somebody decides what each operation
  * costs.
  */
-declare function recordOperations(spec: OpenApiDocument): OperationRecord;
+export declare function recordOperations(spec: OpenApiDocument): OperationRecord;
 /**
  * The document as this caller should see it: their operations, and nothing else.
  *
@@ -56,8 +56,8 @@ declare function recordOperations(spec: OpenApiDocument): OperationRecord;
  * means walking the `$ref` graph, and a schema nobody references costs a few
  * hundred tokens where a wrongly-pruned one breaks the document.
  */
-declare function filterSpec<P extends string>(spec: OpenApiDocument, principal: Principal<P>, permissions: Readonly<Record<string, string>>): OpenApiDocument;
-type OpenApiFetchOptions<P extends string = string> = {
+export declare function filterSpec<P extends string>(spec: OpenApiDocument, principal: Principal<P>, permissions: Readonly<Record<string, string>>): OpenApiDocument;
+export type OpenApiFetchOptions<P extends string = string> = {
   /** The document describing this API. Also the catalogue served to callers. */
   spec: OpenApiDocument;
   /** `operationId` to the permission it costs. Every operation needs an entry. */
@@ -107,6 +107,5 @@ type OpenApiFetchOptions<P extends string = string> = {
  * out of the spec (a health check, static files) belong outside this wrapper
  * rather than behind it.
  */
-declare function createOpenApiFetch<P extends string = string>(options: OpenApiFetchOptions<P>): (request: Request) => Promise<Response>;
-//#endregion
-export { OpenApiDocument, OpenApiFetchOptions, OpenApiOperation, OperationRecord, createOpenApiFetch, filterSpec, recordOperations };
+export declare function createOpenApiFetch<P extends string = string>(options: OpenApiFetchOptions<P>): (request: Request) => Promise<Response>;
+//#endregion

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

@@ -3,15 +3,15 @@
  * Rendering a permission map as source, shared by everything that records a
  * catalogue.
  *
- * Its own module because the MCP recorder needs an optional peer dependency to
- * talk to a server, and the OpenAPI one only needs a file it was handed. A
- * caller after the scaffold should not have to install a client to get it.
+ * Its own module because the MCP recorder loads a client to talk to a server,
+ * and the OpenAPI one only needs a file it was handed. A caller after the
+ * scaffold should not have to load a client to get it.
  */
 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 = {
@@ -11,7 +12,7 @@ type UpstreamConfig = {
 };
 //#endregion
 //#region src/proxy.d.ts
-type McpProxyOptions<P extends string = string> = {
+export type McpProxyOptions<P extends string = string> = {
   /** This proxy's public URL, e.g. `https://mcp.acme.com/mcp`. */
   resourceServerUrl: URL;
   /** RFC 8414 metadata for the authorization server in front of the proxy. */
@@ -23,6 +24,18 @@ 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.
    *
@@ -41,6 +54,5 @@ type McpProxyOptions<P extends string = string> = {
   healthPath?: string;
   maxRequestBytes?: number;
 };
-declare function createMcpProxy<P extends string = string>(options: McpProxyOptions<P>): (request: Request) => Promise<Response>;
-//#endregion
-export { McpProxyOptions, createMcpProxy };
+export declare function createMcpProxy<P extends string = string>(options: McpProxyOptions<P>): (request: Request) => Promise<Response>;
+//#endregion