mcp-authz 0.1.0 → 0.3.0

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+//#region src/cli.d.ts
+declare function main(argv: readonly string[]): number | Promise<number>;
+//#endregion
+export { main };

package/dist/cli.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+import { i as reconcile, r as definePolicy } from "./policy-BBp3Jq6G.js";
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+//#region src/cli.ts
+/**
+* Two questions a policy file cannot answer by being read.
+*
+* `check` runs the same reconciliation the server runs at boot, without booting
+* it, so CI catches drift on the pull request rather than on deploy. `explain`
+* answers "why can Alice do this", which nothing else answers at all: the
+* decision carries the permissions, and only `policy.explain` carries the rules
+* that produced them.
+*
+* Deliberately no colour library and no argument parser. `node:util` has one,
+* and a dependency here would be a dependency in every install of the package.
+*/
+const USAGE = `mcp-authz — inspect a policy without running a server
+
+  mcp-authz check <policy.json> [--capabilities <map.json>]
+  mcp-authz record <connector.ts> [--out <permissions.ts>]
+  mcp-authz record --upstream <url> [--token <bearer>] [--out <permissions.ts>]
+  mcp-authz record <connector.ts|--upstream <url>> --check <permissions.ts>
+  mcp-authz explain <policy.json> --identity <identity.json>|- [--capabilities <map.json>]
+
+Files
+  <policy.json>     the object you would hand definePolicy
+  --capabilities    a .json map, or a .ts/.js module exporting PERMISSIONS,
+                    which is what record writes
+  --identity        an Identity, or a decoded token payload (iss, sub, email,
+                    email_verified, hd). Use - to read it from stdin.
+
+Exit codes
+  0  fine, warnings included
+  1  the policy is invalid, or a capability no role can reach
+`;
+function main(argv) {
+	const { values, positionals } = parseArgs({
+		args: [...argv],
+		allowPositionals: true,
+		options: {
+			capabilities: { type: "string" },
+			identity: { type: "string" },
+			out: { type: "string" },
+			upstream: { type: "string" },
+			token: { type: "string" },
+			check: { type: "string" },
+			help: {
+				type: "boolean",
+				short: "h"
+			}
+		}
+	});
+	const [command, policyPath] = positionals;
+	if (values.help || !command) {
+		process.stdout.write(USAGE);
+		return values.help ? 0 : 1;
+	}
+	if (command === "record") {
+		if (values.upstream) return record({
+			upstream: values.upstream,
+			token: values.token
+		}, values.out, values.check);
+		if (!policyPath) {
+			process.stderr.write("record needs a module whose default export builds the server, or --upstream <url>.\n");
+			return 1;
+		}
+		return record({ module: policyPath }, values.out, values.check);
+	}
+	if (!policyPath) {
+		process.stderr.write(`${command} needs a path to a policy file.\n`);
+		return 1;
+	}
+	const policy = definePolicy(readJson(policyPath));
+	const run = (capabilities) => {
+		if (command === "check") return check(policy, capabilities);
+		if (command === "explain") {
+			if (!values.identity) {
+				process.stderr.write("explain needs --identity <file>, or - for stdin.\n");
+				return 1;
+			}
+			return explain(policy, identityFrom(readJson(values.identity)), capabilities);
+		}
+		process.stderr.write(`Unknown command '${command}'.\n\n${USAGE}`);
+		return 1;
+	};
+	if (!values.capabilities) return run(void 0);
+	if (values.capabilities.endsWith(".json")) return run(new Map(Object.entries(readJson(values.capabilities))));
+	return importCapabilities(values.capabilities).then(run);
+}
+/** Read the map out of a module `record` produced, or one written by hand. */
+async function importCapabilities(path) {
+	const loaded = await import(pathToFileURL(resolve(path)).href);
+	const map = loaded.PERMISSIONS ?? loaded.default;
+	if (!map || typeof map !== "object") throw new Error(`${path} must export PERMISSIONS, or default, mapping each capability to a permission.`);
+	return new Map(Object.entries(map));
+}
+async function record(source, out, against) {
+	let toolkit;
+	try {
+		toolkit = await import("./testing.js");
+	} catch {
+		process.stderr.write("record needs @modelcontextprotocol/client, which is an optional peer.\n  npm install -D @modelcontextprotocol/client\n");
+		return 1;
+	}
+	let capabilities;
+	if ("upstream" in source) capabilities = await toolkit.recordUpstream(source.upstream, { bearer: source.token });
+	else {
+		const loaded = await import(pathToFileURL(resolve(source.module)).href);
+		if (typeof loaded.default !== "function") {
+			process.stderr.write(`${source.module} must default-export a function that builds the server.\n`);
+			return 1;
+		}
+		capabilities = await toolkit.recordCapabilities(loaded.default);
+	}
+	if (against) return drift(capabilities, against);
+	const generated = toolkit.toPermissionsModule(capabilities);
+	if (out) writeFileSync(out, generated);
+	else process.stdout.write(generated);
+	return 0;
+}
+/**
+* Compare what the server has now against the map somebody committed.
+*
+* The snapshot story needs a test runner, and the upstream path has none — this
+* is what lets a URL-only server be watched from CI at all.
+*/
+async function drift(live, path) {
+	const loaded = await import(pathToFileURL(resolve(path)).href);
+	const priced = Object.keys(loaded.PERMISSIONS ?? {});
+	const recorded = loaded.FINGERPRINTS ?? {};
+	const added = live.names.filter((name) => !priced.includes(name));
+	const removed = priced.filter((name) => !live.names.includes(name));
+	const changed = live.names.filter((name) => priced.includes(name) && recorded[name] && recorded[name] !== live.fingerprints[name]);
+	const unbaselined = Object.keys(recorded).length === 0 ? ` — ${path} carries no FINGERPRINTS, so definitions were not compared; re-record to add one` : "";
+	if (added.length === 0 && removed.length === 0 && changed.length === 0) {
+		process.stdout.write(`${live.names.length} capabilities, names unchanged since ${path}${unbaselined}\n`);
+		return 0;
+	}
+	const lines = ["The server no longer matches the recorded capabilities:", ""];
+	for (const name of added) lines.push(`  + ${name}`, "      never priced, so nobody decided who may reach it");
+	for (const name of removed) lines.push(`  - ${name}`, "      priced here, but the server no longer offers it");
+	for (const name of changed) lines.push(`  ~ ${name}`, "      same name, different definition than the one recorded");
+	if (unbaselined) lines.push("", `Note:${unbaselined.slice(3)}`);
+	lines.push("", "Re-record when the change is expected, and review the diff.", "");
+	process.stdout.write(lines.join("\n"));
+	return 1;
+}
+function check(policy, capabilities) {
+	const lines = [`${policy.roles.size} role${policy.roles.size === 1 ? "" : "s"}`, `${policy.permissions.length} permission${policy.permissions.length === 1 ? "" : "s"}`];
+	if (capabilities) lines.push(`${capabilities.size} capabilities`);
+	for (const line of lines) process.stdout.write(`  ok  ${line}\n`);
+	if (!capabilities) {
+		process.stdout.write("\nPass --capabilities to reconcile the policy against the tools that use it.\n");
+		return 0;
+	}
+	const { error, warning } = reconcile(policy.roles, capabilities);
+	if (warning) process.stdout.write(`\n${warning}\n`);
+	if (error) {
+		process.stderr.write(`\n${error}\n`);
+		return 1;
+	}
+	return 0;
+}
+function explain(policy, identity, capabilities) {
+	const { principal, matched, deniedBy } = policy.explain(identity);
+	process.stdout.write(`${identity.email ?? identity.sub}\n\n`);
+	process.stdout.write("Matched rules\n");
+	if (matched.length === 0) process.stdout.write("  none, so this caller holds nothing\n");
+	for (const rule of matched) {
+		const verdict = rule.deny ? "DENY" : rule.roles.join(", ");
+		process.stdout.write(`  rule ${rule.index}  ${describe(rule)} -> ${verdict}\n`);
+	}
+	if (deniedBy) process.stdout.write(`\nRule ${deniedBy.index} denies, which empties the grant whatever else matched.\n`);
+	process.stdout.write(`\nEffective roles\n  ${list(principal.roles)}\n`);
+	const permissions = principal.permissions.map((p) => p === "*" ? "* (every permission)" : p);
+	process.stdout.write(`\nPermissions\n  ${list(permissions)}\n`);
+	if (capabilities) {
+		const usable = [...capabilities].filter(([, permission]) => principal.can(permission)).map(([capability]) => capability);
+		process.stdout.write(`\nCapabilities\n  ${list(usable)}\n`);
+	}
+	return 0;
+}
+/** Every field of a match, so a rule that matched on two things reads as two. */
+function describe(rule) {
+	const parts = Object.entries(rule.match).flatMap(([field, value]) => field === "claim" ? Object.entries(value).map(([path, want]) => `${path}=${want}`) : [`${field}=${String(value)}`]);
+	return parts.length > 0 ? parts.join(" and ") : "every caller";
+}
+function list(values) {
+	return values.length > 0 ? values.join("\n  ") : "none";
+}
+/**
+* An Identity as written, or a decoded token payload.
+*
+* This mirrors what the verifier produces, for a caller who has not been
+* verified: `explain` answers a what-if, so it trusts the file it was handed.
+*/
+function identityFrom(value) {
+	if (typeof value !== "object" || value === null) throw new Error("Identity must be an object.");
+	const raw = value;
+	const issuer = str(raw.issuer) ?? str(raw.iss);
+	const sub = str(raw.sub);
+	if (!issuer || !sub) throw new Error("Identity needs an issuer ('iss') and a subject ('sub').");
+	return {
+		issuer,
+		sub,
+		email: str(raw.email),
+		emailVerified: raw.emailVerified === true || raw.email_verified === true,
+		domain: str(raw.domain) ?? str(raw.hd),
+		claims: typeof raw.claims === "object" && raw.claims !== null ? raw.claims : raw
+	};
+}
+function str(value) {
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function readJson(path) {
+	return JSON.parse(readFileSync(path === "-" ? 0 : path, "utf8"));
+}
+if (import.meta.url === `file://${process.argv[1]}`) try {
+	process.exitCode = await main(process.argv.slice(2));
+} catch (error) {
+	process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+	process.exitCode = 1;
+}
+//#endregion
+export { main };

package/dist/index.d.ts

@@ -1,5 +1,8 @@
-import { a as Policy, c as Rule, d as definePolicy, f as reconcile, h as Identity, i as PermissionOf, l as createPrincipal, m as DenialReason, n as Match, o as PolicySpec, p as AccessDeniedError, r as PermissionCatalog, s as Principal, u as definePermissions } from "./policy-CnQj53Hq.js";
-import { AuthInfo, CallToolResult, GetPromptResult, Icon, Implementation, InboundClassificationOutcome, McpServer, OAuthMetadata, OAuthTokenVerifier, ReadResourceResult, ResourceMetadata, ResourceTemplate, ServerOptions as ServerOptions$1, StandardSchemaV1, StandardSchemaWithJSON, ToolAnnotations } from "@modelcontextprotocol/server";
+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 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";
 //#region src/discovery.d.ts
 type DiscoverOptions = {
   /** Swap in for tests, or to add a timeout or proxy. Defaults to global fetch. */
@@ -7,125 +10,6 @@ type DiscoverOptions = {
 };
 declare function discoverOAuth(issuer: string, options?: DiscoverOptions): Promise<OAuthMetadata>;
 //#endregion
-//#region src/tools.d.ts
-/**
- * Tools, prompts and resources that carry the permission they require.
- *
- * Declaring it here rather than in a separate rules file is the whole point: it
- * is checked against the policy by the compiler, reconciled against the policy
- * at boot, and it cannot drift when somebody renames the tool.
- *
- * MCP exposes three things a caller can reach, so gating only tools leaves two
- * doors open. All three register the same way: check the permission, skip the
- * registration when the caller lacks it, audit what they do reach.
- */
-/** Which of the three a caller reached. */
-type Capability = 'tool' | 'prompt' | 'resource';
-/** What actually happened, for the audit log the downstream API cannot write. */
-type AuditEvent = {
-  issuer: string;
-  sub: string;
-  email?: string;
-  kind: Capability;
-  /** The registered name, e.g. `update_case`. */
-  name: string;
-  permission: string;
-  /** Whatever the definition's own `audit` said the call touched, e.g. `case:C1234`. */
-  resource?: string;
-  decision: 'allow';
-  phase: 'attempt' | 'success' | 'failure';
-  at: string;
-  durationMs?: number;
-  error?: string;
-};
-type AuditSink = (event: AuditEvent) => unknown | Promise<unknown>;
-type InferArgs<S> = S extends StandardSchemaV1<unknown, infer Output> ? Output : undefined;
-/** Shared by all three: what it costs, and what the call touched. */
-type Gated<P extends string, A> = {
-  /** Required to reach it. Typed to the policy's permissions, so a typo is a build error. */
-  permission: P;
-  /**
-   * Name the thing the call touched, for the audit event. The library cannot
-   * know that `{ caseId: 'C1234' }` means a case; the application always does.
-   */
-  audit?: (args: A) => string | undefined;
-};
-type ToolConfig<P extends string, S> = Gated<P, InferArgs<S>> & {
-  title?: string;
-  description?: string;
-  inputSchema?: S;
-  outputSchema?: StandardSchemaWithJSON;
-  annotations?: ToolAnnotations;
-  icons?: Icon[];
-};
-type PromptConfig<P extends string, S> = Gated<P, InferArgs<S>> & {
-  title?: string;
-  description?: string;
-  argsSchema?: S;
-  icons?: Icon[];
-};
-type ResourceConfig<P extends string> = Gated<P, URL> & ResourceMetadata & {
-  /** The URI clients read, or a template for a family of them. */
-  uri: string | ResourceTemplate;
-};
-/**
- * Erased once built, so a server registers every capability the same way
- * whatever it accepts.
- */
-type Definition<P extends string, C = Principal<P>> = {
-  /**
-   * Unique key for the boot-time check. Bare for a tool, prefixed otherwise, so
-   * a prompt sharing a tool's name stays a separate entry rather than shadowing
-   * it.
-   */
-  label: string;
-  kind: Capability;
-  /** Exact protocol name used to refuse an unpermitted direct invocation before scope step-up. */
-  routeName?: string;
-  routeMatches?: (name: string) => boolean;
-  permission: P;
-  register: (server: McpServer, principal: Principal<P>, context: C, onAudit?: AuditSink) => void;
-};
-type ServerOptions = Implementation & {
-  /** Called on every permitted invocation. The one record tying a person to an action. */
-  onAudit?: AuditSink;
-  /** Pass-through SDK options; declared gated capabilities are merged in. */
-  mcp?: ServerOptions$1;
-};
-/**
- * A per-request server factory over a fixed set of capabilities, plus the
- * label-to-permission map that `createMcpFetch` reconciles against the policy
- * at boot.
- */
-type ServerFactory<C> = ((context: C) => McpServer) & {
-  permissions: ReadonlyMap<string, string>;
-  routePermissions: ReadonlyMap<string, string>;
-  permissionForRoute: (kind: Capability, name: string) => string | undefined;
-};
-/**
- * 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);
- * ```
- */
-declare function bindAuthz<P extends string, C, H>(_permissions: Policy<P> | PermissionCatalog<P>, principalOf: (context: C) => Principal<P>, handlerContext: (context: C, principal: Principal<P>) => H): {
-  tool: <S extends StandardSchemaWithJSON | undefined = undefined>(name: string, config: ToolConfig<P, S>, handler: (args: InferArgs<S>, context: H) => CallToolResult | Promise<CallToolResult>) => Definition<P, C>;
-  prompt: <S extends StandardSchemaWithJSON | undefined = undefined>(name: string, config: PromptConfig<P, S>, handler: (args: InferArgs<S>, context: H) => GetPromptResult | Promise<GetPromptResult>) => Definition<P, C>;
-  resource: (name: string, config: ResourceConfig<P>, handler: (uri: URL, context: H) => ReadResourceResult | Promise<ReadResourceResult>) => Definition<P, C>;
-  server: (definitions: readonly Definition<P, C>[], options: ServerOptions) => ServerFactory<C>;
-};
-declare function authz<P extends string>(policy: Policy<P> | PermissionCatalog<P>): ReturnType<typeof bindAuthz<P, Principal<P>, {
-  principal: Principal<P>;
-}>>;
-declare function authz<P extends string, C>(policy: Policy<P> | PermissionCatalog<P>, options: {
-  principal: (context: C) => Principal<P>;
-}): ReturnType<typeof bindAuthz<P, C, C>>;
-//#endregion
 //#region src/gate.d.ts
 /**
  * Gate a server somebody else builds.
@@ -154,102 +38,31 @@ declare function authz<P extends string, C>(policy: Policy<P> | PermissionCatalo
 type GateOptions = {
   /** Same event as `authz`, for tools this package did not define. */
   onAudit?: AuditSink;
+  /** Names this deployment on every event it emits. See `ServerOptions`. */
+  emitter?: string;
+  /** Receives a failed terminal audit write without changing the completed action's result. */
+  onAuditError?: AuditErrorSink;
   /**
    * Name the thing a call touched, keyed by the same label as `permissions`.
    * Their tool, your domain knowledge.
    */
   audit?: Readonly<Record<string, (args: never) => string | undefined>>;
+  /**
+   * Ask a person before one of their tools runs, keyed by the same label. The
+   * one thing worth adding to somebody else's destructive tool without touching
+   * their code.
+   */
+  approval?: Readonly<Record<string, boolean | ((args: never) => boolean)>>;
+  /** Awaited human decision. Required when `approval` names anything. */
+  onApproval?: ApprovalSink;
+  /** Silence is a refusal after this long. Defaults to 45s, as in `authz`. */
+  approvalTimeoutMs?: number;
 };
 /** 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;
 //#endregion
-//#region src/routing.d.ts
-type TrustedMcpRoute = {
-  kind: 'modern';
-  body: unknown;
-  outcome: Extract<InboundClassificationOutcome, {
-    kind: 'modern';
-  }>;
-  method: string;
-  name?: string;
-};
-//#endregion
-//#region src/scopes.d.ts
-/**
- * Helpers for deriving required OAuth scopes from Streamable HTTP headers
- * (SEP-2243). Use with `createMcpFetch({ scopesForRequest })`.
- */
-type ScopeRequirement = string | readonly string[];
-type ToolScopeMap = Readonly<Record<string, ScopeRequirement>>;
-type CapabilityScopeMap = ToolScopeMap;
-/**
- * Tools use their bare name (or `tool:name`); prompts use `prompt:name`; and
- * resources use `resource:<uri>`. Everything else needs only the baseline.
- */
-declare function scopesFromMcpHeaders(request: Request, toolScopes: ToolScopeMap, baseline?: string): string[];
-/** Select scopes from an already validated MCP method/name pair. */
-declare function scopesForCapability(method: string | undefined, name: string | undefined, capabilityScopes: CapabilityScopeMap, baseline?: string): string[];
-/** Decode SEP-2243's optional Base64 sentinel without accepting non-canonical input. */
-declare function decodeMcpNameHeader(value: string): string | undefined;
-//#endregion
-//#region src/verifier.d.ts
-/**
- * Token verification, the one thing the SDK deliberately leaves to you.
- *
- * `authInfo` is strictly pass-through in the SDK: it is never derived from
- * request headers, and no token is checked unless we check it. So this file is
- * the security boundary of the whole server.
- *
- * The authorization server is something that already exists (WorkOS, Stytch,
- * Auth0) doing dynamic client registration / CIMD and Google Workspace login.
- * Google cannot play that role itself: it has no DCR/CIMD, and it will not
- * mint a token whose audience is this server.
- */
-type VerifierOptions = {
-  /** The AS issuer, e.g. `https://auth.acme.com`. Must match the token's `iss`. */
-  issuer: string;
-  /** Where the AS publishes its signing keys. */
-  jwksUri: string;
-  /**
-   * This server's public URL. A token minted for a different resource is
-   * refused even when its signature is valid (RFC 8707).
-   */
-  resource: URL;
-  /**
-   * Restrict to one Google Workspace domain, checked against the `hd` claim
-   * the AS passes through. Omit to accept any domain the AS admits.
-   */
-  allowedDomain?: string;
-  /** Claim carrying the verified email. Auth0 and WorkOS both use `email`. */
-  emailClaim?: string;
-  /** Claim proving the email was verified. Defaults to `email_verified`. */
-  emailVerifiedClaim?: string;
-  /** Require an explicit `true` verified-email claim. Defaults to true. */
-  requireEmailVerified?: boolean;
-};
-/**
- * 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.
- */
-declare function jwksVerifier(options: VerifierOptions): OAuthTokenVerifier & {
-  identityOf: (auth: AuthInfo) => Identity;
-};
-/** Default identity mapper for custom verifiers using `AuthInfo.extra`. */
-declare function identityFromAuth(auth: AuthInfo): Identity;
-//#endregion
 //#region src/handler.d.ts
-type AuthorizationDecisionEvent = {
-  issuer: string;
-  sub: string;
-  email?: string;
-  decision: 'allow' | 'deny';
-  roles: readonly string[];
-  permissions: readonly string[];
-  reason?: string;
-  at: string;
-};
-type AuthorizationDecisionSink = (event: AuthorizationDecisionEvent) => unknown | Promise<unknown>;
 /**
  * An MCP Streamable HTTP resource server (2026-07-28) with
  * each person's own Google login in front of a per-request server factory.
@@ -325,6 +138,13 @@ type McpFetchOptions<TContext, P extends string = string> = {
   authorize?: (identity: Identity) => Promise<Principal<P>> | Principal<P>;
   /** Awaited access-decision sink. A rejection fails closed. */
   onDecision?: AuthorizationDecisionSink;
+  /**
+   * Names this deployment on every event it emits.
+   *
+   * Set the same value here and in `server(...)`, or a dashboard reading both
+   * cannot tell that a refusal and a call came from the same place.
+   */
+  emitter?: string;
   /**
    * After auth: map the verified identity to backend context, or throw
    * `AccessDeniedError` for an actionable 403. Omit to use `policy` alone.
@@ -341,6 +161,7 @@ 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;
     /** Resolve exact and templated protocol routes to their declared permission. */
     permissionForRoute?: (kind: 'tool' | 'prompt' | 'resource', name: string) => string | undefined;
   };
@@ -357,8 +178,9 @@ type McpFetchOptions<TContext, P extends string = string> = {
   /** Reject 2025-era requests by default; opt in only when legacy clients are required. */
   legacy?: 'reject' | 'stateless';
   /**
-   * Cap on a body read before authentication, which only the declarative scope
-   * path does. Defaults to 1 MiB; over it is a 413.
+   * Cap on the body read that names the capability. Defaults to 1 MiB; over it
+   * is a 413. The read happens after the bearer gate, so the cap bounds an
+   * authenticated caller rather than anyone who can reach the port.
    */
   maxRequestBytes?: number;
 };
@@ -383,4 +205,4 @@ declare function createMcpFetch<TContext = Principal<string>, P extends string =
   resolve: (identity: Identity, principal: undefined) => Promise<TContext> | TContext;
 }): (request: Request) => Promise<Response>;
 //#endregion
-export { AccessDeniedError, type AuditEvent, type AuditSink, type AuthorizationDecisionEvent, type AuthorizationDecisionSink, type Capability, type CapabilityScopeMap, type Definition, type DenialReason, type DiscoverOptions, type GateOptions, type Identity, type Match, 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, createMcpFetch, createPrincipal, decodeMcpNameHeader, definePermissions, definePolicy, discoverOAuth, gate, identityFromAuth, jwksVerifier, reconcile, scopesForCapability, scopesFromMcpHeaders };