permdock 0.3.1 → 0.5.0

package/dist/mcp/index.js

@@ -1,83 +1,28 @@
-import { t as compact } from "../compact-y6vfu2_f.js";
+import { r as isRecord, t as compact } from "../compact-CAf557ZB.js";
 import { n as freezeDeep } from "../freeze-CrU8nQeX.js";
-import { t as annotationsFor } from "../permissions-DVoF6dMt.js";
-import { a as wireDenials, i as stepUpOf } from "../problem-details-_AMOYz-w.js";
-import { t as describe } from "../describe-B_gVZEVi.js";
-import { i as scopesReaching, r as challengeScope } from "../permdock-CbgvLnuo.js";
+import { i as stepUpOf } from "../problem-details-cn5X30gZ.js";
+import { t as describe } from "../describe-BybMRY7A.js";
+import { m as annotationsFor } from "../permission-registry-Br4jSNVi.js";
+import { t as actorMayCallTool } from "../delegation-DaXVdDhM.js";
 import { n as resourceRef } from "../resource-ref-CaS9yVPi.js";
-import { t as anonymousSubject } from "../subject-C6dLxqHU.js";
-import { t as mayUse } from "../may-use-DndQ5tQ-.js";
-import { c as protectedResourceMetadataUrl, n as bearerChallenge } from "../problem-B43ztKIm.js";
+import { a as hasScope, c as withApp, i as challengeScope, o as scopesReaching } from "../permdock-B9JxkBwC.js";
+import { t as anonymousSubject } from "../subject-BGoM5o8B.js";
+import { t as composeWraps } from "../wrap-gX61EtpB.js";
+import { l as protectedResourceMetadataUrl, r as bearerChallenge } from "../problem-CTviyH5L.js";
 import { t as clientNameOf } from "../clients-DjU5ABMy.js";
-import { n as mapClaimsToSubject } from "../map-claims-Z4QZOiFF.js";
-import { t as instanceOptions } from "../instance-options-Dhhcnm3y.js";
-import { n as createAgentKernel } from "../kernel-_RRHmnMY.js";
+import { n as mapClaimsToSubject } from "../map-claims-D3oRmTk0.js";
+import { r as instanceOptions } from "../build-instance-BMnAudHn.js";
+import { n as createAgentKernel, r as refusalText } from "../kernel-5JatXyND.js";
 import { t as boundedMap } from "../lru-8q4WZjBV.js";
-//#region src/mcp/subject.ts
-const DEFAULT_MCP_ACTOR_KIND = "mcp-client";
-/** `kind`, or the default when absent; `undefined` for a kind that is not a non-empty string. */
-function mcpActorKind(kind) {
-	if (kind === void 0) return DEFAULT_MCP_ACTOR_KIND;
-	return typeof kind === "string" && kind !== "" ? kind : void 0;
-}
-function isRecord$1(value) {
-	return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-/**
-* Maps the `AuthInfo` the MCP SDK's bearer verification produced to a
-* `Subject`: the principal from the verified claims in `extra`, the client
-* as an actor of kind `actorKind` (`mcp-client` by default), the granted
-* scopes as the delegation. Never verifies and never throws; anything
-* unusable, including an `actorKind` that is not a non-empty string, is
-* the anonymous subject.
-*/
-function subjectFromMcp(authInfo, options = {}) {
-	try {
-		const kind = mcpActorKind(options.actorKind);
-		if (authInfo === void 0 || !isRecord$1(authInfo.extra) || kind === void 0) return anonymousSubject();
-		const claims = compact({
-			...authInfo.extra,
-			authorization_details: authInfo.extra["authorizationDetails"] ?? authInfo.extra["authorization_details"],
-			scope: authInfo.scopes?.join(" "),
-			client_id: authInfo.clientId,
-			exp: authInfo.expiresAt
-		});
-		const mapped = mapClaimsToSubject(claims, options);
-		if (mapped.invalidClaims || mapped.invalidChain || mapped.subject.principal === null) return anonymousSubject();
-		const clientId = authInfo.clientId;
-		return freezeDeep(compact({
-			...mapped.subject,
-			actor: typeof clientId === "string" && clientId !== "" ? compact({
-				id: clientId,
-				kind,
-				client: clientNameOf(options.clients, clientId)
-			}) : mapped.subject.actor
-		}));
-	} catch {
-		return anonymousSubject();
-	}
-}
-//#endregion
-//#region src/mcp/create.ts
+import { t as delegationFrom } from "../delegation-input-FTxMK3ji.js";
+import { n as deniedToolRefusal, r as toolErrorResult, t as approvalToolRefusal } from "../tool-refusal-CMLN5xhn.js";
+//#region src/mcp/mcp-auth.ts
 /** `_meta` key on `tools/call`, `resources/read` and `prompts/get` carrying an approval token. */
 const APPROVAL_META_KEY = "dev.permdock/approval";
-const SESSIONS_PER_SERVER = 1e3;
 const CLIENT_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
 const PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion";
 /** The first protocol revision whose list results define `ttlMs` and `cacheScope`. */
 const CACHEABLE_LISTS_SINCE = "2026-07-28";
-/** What a completion re-check still accepts after the handler ran. */
-function stillAllowed(decision, approved) {
-	switch (decision.outcome) {
-		case "granted": return true;
-		case "approval-required": return approved !== void 0 && decision.token === approved;
-		case "denied": return decision.denials.length > 0 && decision.denials.every((denial) => denial.reason === "limit");
-		default: return decision;
-	}
-}
-function isRecord(value) {
-	return value !== null && typeof value === "object" && !Array.isArray(value);
-}
 function contextOf(value) {
 	return isRecord(value) ? value : {};
 }
@@ -94,19 +39,6 @@ function approvalTokenOf(context) {
 	const fromAuth = context.http?.authInfo?.extra?.["approval"];
 	return typeof fromAuth === "string" && fromAuth !== "" ? fromAuth : void 0;
 }
-function authorizationDetailsOf(authInfo) {
-	const details = authInfo.extra?.["authorizationDetails"] ?? authInfo.extra?.["authorization_details"];
-	return Array.isArray(details) ? details : void 0;
-}
-function delegationOf(authInfo) {
-	return compact({
-		scopes: authInfo.scopes,
-		authorizationDetails: authorizationDetailsOf(authInfo)
-	});
-}
-function hasScope(authInfo, scopes) {
-	return scopes.some((scope) => (authInfo.scopes ?? []).includes(scope));
-}
 function resourceMetadataOf(authInfo) {
 	if (authInfo.resourceMetadataUrl !== void 0) return authInfo.resourceMetadataUrl;
 	const resource = authInfo.resource;
@@ -129,6 +61,41 @@ function definesCacheScope(context) {
 	const version = context.mcpReq?.envelope?.[PROTOCOL_VERSION];
 	return typeof version === "string" && version >= CACHEABLE_LISTS_SINCE;
 }
+function tenantOf(tenant) {
+	if (typeof tenant !== "function") return tenant;
+	return (call) => tenant(call.authInfo ?? {});
+}
+function sessionKey(context) {
+	return context.sessionId ?? "";
+}
+function declaredScopes(name, value) {
+	if (value === void 0) return;
+	const scopes = Array.isArray(value) ? value : [];
+	const names = scopes.filter((scope) => typeof scope === "string" && scope !== "");
+	const [first, ...rest] = names;
+	if (first === void 0 || names.length !== scopes.length) throw new TypeError(`permdock/mcp: tool ${name} sets oauthScopes, which must be a non-empty list of scope names.`);
+	return Object.freeze([first, ...rest]);
+}
+function challengeFor(own, reaching, challenged) {
+	return async (context) => {
+		const first = await own?.(context);
+		if (first !== void 0) return first;
+		const authInfo = context.authInfo;
+		if (authInfo === void 0 || hasScope(authInfo.scopes, reaching)) return;
+		return { scopes: [challenged] };
+	};
+}
+//#endregion
+//#region src/mcp/refusals.ts
+/** What a completion re-check still accepts after the handler ran. */
+function stillAllowed(decision, approved) {
+	switch (decision.outcome) {
+		case "granted": return true;
+		case "approval-required": return approved !== void 0 && decision.token === approved;
+		case "denied": return decision.denials.length > 0 && decision.denials.every((denial) => denial.reason === "limit");
+		default: return decision;
+	}
+}
 function acceptsUrlElicitation(context, fallback) {
 	const fromEnvelope = context.mcpReq?.envelope?.[CLIENT_CAPABILITIES];
 	const capabilities = isRecord(fromEnvelope) ? fromEnvelope : fallback?.();
@@ -160,30 +127,10 @@ function urlElicitation(key, message, url, requestState) {
 	});
 }
 function deniedRefusal(decision, permission, data) {
-	const alternatives = decision.alternatives.map((leaf) => leaf.key);
-	const resource = resourceRef(permission, data);
-	return {
-		text: `Denied: ${resource.id === void 0 ? permission.key : `${permission.key} on ${resource.id}`}.${alternatives.length === 0 ? "" : ` You may: ${alternatives.join(", ")}.`}`,
-		structured: {
-			outcome: "denied",
-			permission: permission.key,
-			resource,
-			denials: wireDenials(decision.denials),
-			alternatives,
-			detail: describe(decision).detail
-		}
-	};
+	return deniedToolRefusal(decision, permission, resourceRef(permission, data));
 }
 function approvalRefusal(decision, permission, data) {
-	return {
-		text: describe(decision).detail,
-		structured: {
-			outcome: "approval-required",
-			permission: permission.key,
-			resource: resourceRef(permission, data),
-			token: decision.token
-		}
-	};
+	return approvalToolRefusal(decision, permission, resourceRef(permission, data));
 }
 function plainRefusal(permission, text, extra) {
 	return {
@@ -197,10 +144,6 @@ function plainRefusal(permission, text, extra) {
 		}
 	};
 }
-function tenantOf(tenant) {
-	if (typeof tenant !== "function") return tenant;
-	return (call) => tenant(call.authInfo ?? {});
-}
 function failedRefusal(permission, failure) {
 	switch (failure) {
 		case "load-failed": return plainRefusal(permission, `Denied: ${permission.key} failed closed.`, { denials: [{
@@ -216,388 +159,473 @@ function failedRefusal(permission, failure) {
 	}
 }
 function toolRefusal(refusal) {
-	if (refusal.inputRequired !== void 0) return refusal.inputRequired;
-	return {
-		isError: true,
-		content: [{
-			type: "text",
-			text: refusal.text
-		}],
-		structuredContent: refusal.structured
-	};
-}
-function requirePermission(kind, name, config) {
-	const permission = isRecord(config) ? config["permission"] : void 0;
-	if (!isRecord(permission) || typeof permission["key"] !== "string") throw new TypeError(`permdock/mcp: ${kind} ${name} has no permission; every guarded registration needs one.`);
-	return permission;
-}
-function sessionKey(context) {
-	return context.sessionId ?? "";
+	return refusal.inputRequired ?? toolErrorResult(refusal);
 }
 function throwRefusal(refusal) {
 	if (refusal.inputRequired !== void 0) return refusal.inputRequired;
 	throw new Error(refusal.text);
 }
-function declaredScopes(name, value) {
-	if (value === void 0) return;
-	const scopes = Array.isArray(value) ? value : [];
-	const names = scopes.filter((scope) => typeof scope === "string" && scope !== "");
-	const [first, ...rest] = names;
-	if (first === void 0 || names.length !== scopes.length) throw new TypeError(`permdock/mcp: tool ${name} sets oauthScopes, which must be a non-empty list of scope names.`);
-	return Object.freeze([first, ...rest]);
+/** The MRTR URL elicitation that sends the user to `options.approval.at`, when the client accepts one. */
+async function approvalInput(options, decision, handlerContext, context, capabilities) {
+	const at = options.approval?.at;
+	if (at === void 0 || !acceptsUrlElicitation(context, capabilities)) return;
+	const url = withParams(at, { token: decision.token });
+	if (url === void 0) return;
+	const requestState = options.requestState === void 0 ? decision.token : await options.requestState.mint(decision.token, handlerContext);
+	return urlElicitation("approval", options.approval?.hint ?? describe(decision).detail, url, requestState);
 }
-function challengeFor(own, reaching, challenged) {
-	return async (context) => {
-		const first = await own?.(context);
-		if (first !== void 0) return first;
-		const authInfo = context.authInfo;
-		if (authInfo === void 0 || hasScope(authInfo, reaching)) return;
-		return { scopes: [challenged] };
-	};
-}
-function guardUpdates(registered, wrap, rename, currentName) {
-	const update = registered.update.bind(registered);
-	registered.update = (updates) => {
-		const next = { ...updates };
-		if (typeof updates["callback"] === "function") next["callback"] = wrap(updates["callback"]);
-		if (rename !== void 0 && currentName !== void 0) {
-			const to = updates["name"];
-			if (typeof to === "string" || to === null) rename(currentName(), to);
-		}
-		update(next);
-	};
+/** A step-up denial: the RFC 9470 challenge, and a URL elicitation to `stepUpAt` when the client accepts one. */
+function stepUpRefusal(stepUpAt, decision, permission, data, context, capabilities) {
+	const base = deniedRefusal(decision, permission, data);
+	const { acrValues, maxAge } = stepUpOf(decision);
+	const url = stepUpAt === void 0 || !acceptsUrlElicitation(context, capabilities) ? void 0 : withParams(stepUpAt, {
+		acr_values: acrValues?.join(" "),
+		max_age: maxAge === void 0 ? void 0 : String(maxAge)
+	});
+	return compact({
+		text: base.text,
+		structured: compact({
+			...base.structured,
+			error: "insufficient_user_authentication",
+			acr_values: acrValues?.join(" "),
+			max_age: maxAge,
+			www_authenticate: bearerChallenge(compact({
+				error: "insufficient_user_authentication",
+				acrValues,
+				maxAge
+			}))
+		}),
+		inputRequired: url === void 0 ? void 0 : urlElicitation("step_up", `Sign in again to use ${permission.key}.`, url, void 0)
+	});
 }
-function createPermDock(policy, options) {
-	const actorKind = mcpActorKind(options.actorKind);
-	if (actorKind === void 0) throw new TypeError("permdock/mcp: actorKind must be a non-empty string");
-	const kernel = createAgentKernel(policy, compact({
-		subject: (call) => options.subject(call.authInfo ?? {}),
-		actor: (call) => {
-			const clientId = call.authInfo?.clientId;
-			return typeof clientId === "string" && clientId !== "" ? compact({
-				id: clientId,
-				kind: actorKind,
-				client: clientNameOf(options.clients, clientId)
-			}) : void 0;
-		},
-		delegation: (call) => call.authInfo === void 0 ? void 0 : delegationOf(call.authInfo),
-		tenant: tenantOf(options.tenant),
-		store: options.store,
-		adapter: "mcp",
-		boundary: "mcp-args",
-		wrap: options.otel,
-		...instanceOptions(options)
-	}));
-	const forThisServer = (authInfo) => options.resource === void 0 || sameResource(options.resource, authInfo.resource);
-	const reachOf = (permission, declared) => declared === void 0 ? {
+//#endregion
+//#region src/mcp/call-check.ts
+function reachOf(policy, permission, declared) {
+	return declared === void 0 ? {
 		scopes: scopesReaching(policy, permission),
 		challenge: challengeScope(policy, permission)
 	} : {
 		scopes: declared,
 		challenge: declared[0]
 	};
-	const reachable = (authInfo, reach) => authInfo === void 0 ? options.requireAuthInfo !== true : forThisServer(authInfo) && hasScope(authInfo, reach.scopes);
-	const approvalInput = async (decision, handlerContext, context, capabilities) => {
-		const at = options.approval?.at;
-		if (at === void 0 || !acceptsUrlElicitation(context, capabilities)) return;
-		const url = withParams(at, { token: decision.token });
-		if (url === void 0) return;
-		const requestState = options.requestState === void 0 ? decision.token : await options.requestState.mint(decision.token, handlerContext);
-		return urlElicitation("approval", options.approval?.hint ?? describe(decision).detail, url, requestState);
+}
+function forThisServer(checks, authInfo) {
+	return checks.options.resource === void 0 || sameResource(checks.options.resource, authInfo.resource);
+}
+function reachable(checks, authInfo, reach) {
+	return authInfo === void 0 ? checks.options.requireAuthInfo !== true : forThisServer(checks, authInfo) && hasScope(authInfo.scopes, reach.scopes);
+}
+/** The refusal a token earns before any decision: none, the wrong resource, or a missing scope. */
+function credentialRefusal(checks, permission, reach, authInfo) {
+	if (authInfo === void 0) return checks.options.requireAuthInfo === true ? plainRefusal(permission, "Denied: no verified credentials.", { error: "invalid_token" }) : void 0;
+	if (!forThisServer(checks, authInfo)) return plainRefusal(permission, "Denied: the token was not issued for this server.", { error: "invalid_token" });
+	if (hasScope(authInfo.scopes, reach.scopes)) return;
+	const resourceMetadata = resourceMetadataOf(authInfo);
+	const challenged = reach.challenge;
+	return plainRefusal(permission, `Denied: ${permission.key} needs the ${challenged} scope.`, compact({
+		error: "insufficient_scope",
+		scope: challenged,
+		resource_metadata: resourceMetadata,
+		www_authenticate: bearerChallenge(compact({
+			error: "insufficient_scope",
+			scopes: [challenged],
+			resourceMetadata
+		}))
+	}));
+}
+/** The completion re-check of a long-running tool: the call must still be allowed, or approved with the same token. */
+async function recheck(checks, binding, args, call, permission, approved, tool) {
+	const rechecked = await checks.kernel.check(binding, args, call, compact({
+		simulate: true,
+		tool
+	}));
+	if (!rechecked.ok) return {
+		ok: false,
+		refusal: failedRefusal(permission, rechecked.failure)
 	};
-	const stepUpRefusal = (decision, permission, data, context, capabilities) => {
-		const base = deniedRefusal(decision, permission, data);
-		const { acrValues, maxAge } = stepUpOf(decision);
-		const at = options.stepUp?.at;
-		const url = at === void 0 || !acceptsUrlElicitation(context, capabilities) ? void 0 : withParams(at, {
-			acr_values: acrValues?.join(" "),
-			max_age: maxAge === void 0 ? void 0 : String(maxAge)
-		});
-		return compact({
-			text: base.text,
-			structured: compact({
-				...base.structured,
-				error: "insufficient_user_authentication",
-				acr_values: acrValues?.join(" "),
-				max_age: maxAge,
-				www_authenticate: bearerChallenge(compact({
-					error: "insufficient_user_authentication",
-					acrValues,
-					maxAge
-				}))
-			}),
-			inputRequired: url === void 0 ? void 0 : urlElicitation("step_up", `Sign in again to use ${permission.key}.`, url, void 0)
-		});
+	if (stillAllowed(rechecked.raw, approved)) return { ok: true };
+	return {
+		ok: false,
+		refusal: rechecked.raw.outcome === "denied" ? {
+			...deniedRefusal(rechecked.raw, permission, rechecked.data),
+			decision: rechecked.raw,
+			permdock: rechecked.permdock
+		} : plainRefusal(permission, `Denied: ${permission.key} was revoked before the call completed.`, {})
 	};
-	const check = async (permission, reach, load, context, handlerContext, capabilities, completion) => {
-		const authInfo = context.http?.authInfo;
-		if (authInfo === void 0 && options.requireAuthInfo === true) return {
-			ok: false,
-			refusal: plainRefusal(permission, "Denied: no verified credentials.", { error: "invalid_token" })
-		};
-		if (authInfo !== void 0 && !forThisServer(authInfo)) return {
+}
+async function decideCall(checks, permission, reach, args, load, context, handlerContext, capabilities, completion, tool) {
+	const authInfo = context.http?.authInfo;
+	const refused = credentialRefusal(checks, permission, reach, authInfo);
+	if (refused !== void 0) return {
+		ok: false,
+		refusal: refused
+	};
+	const binding = compact({
+		permission,
+		data: load === void 0 ? void 0 : () => load()
+	});
+	const call = compact({ authInfo });
+	if (completion !== void 0) return recheck(checks, binding, args, call, permission, completion.approved, tool);
+	const checked = await checks.kernel.check(binding, args, call, compact({
+		resumeToken: approvalTokenOf(context),
+		tool
+	}));
+	if (!checked.ok) return {
+		ok: false,
+		refusal: failedRefusal(permission, checked.failure)
+	};
+	const { raw, decision, data } = checked;
+	switch (decision.outcome) {
+		case "granted": return raw.outcome === "approval-required" ? {
+			ok: true,
+			approved: raw.token
+		} : { ok: true };
+		case "denied": return {
 			ok: false,
-			refusal: plainRefusal(permission, "Denied: the token was not issued for this server.", { error: "invalid_token" })
+			refusal: {
+				...decision.denials.some((denial) => denial.reason === "insufficient-user-authentication") ? stepUpRefusal(checks.options.stepUp?.at, decision, permission, data, context, capabilities) : deniedRefusal(decision, permission, data),
+				decision,
+				permdock: checked.permdock
+			}
 		};
-		if (authInfo !== void 0 && !hasScope(authInfo, reach.scopes)) {
-			const resourceMetadata = resourceMetadataOf(authInfo);
-			const challenged = reach.challenge;
+		case "approval-required": try {
 			return {
 				ok: false,
-				refusal: plainRefusal(permission, `Denied: ${permission.key} needs the ${challenged} scope.`, compact({
-					error: "insufficient_scope",
-					scope: challenged,
-					resource_metadata: resourceMetadata,
-					www_authenticate: bearerChallenge(compact({
-						error: "insufficient_scope",
-						scopes: [challenged],
-						resourceMetadata
-					}))
-				}))
-			};
-		}
-		const binding = compact({
-			permission,
-			data: load === void 0 ? void 0 : () => load()
-		});
-		const call = compact({ authInfo });
-		if (completion !== void 0) {
-			const rechecked = await kernel.check(binding, void 0, call, { simulate: true });
-			if (!rechecked.ok) return {
-				ok: false,
-				refusal: failedRefusal(permission, rechecked.failure)
+				refusal: compact({
+					...approvalRefusal(decision, permission, data),
+					decision,
+					permdock: checked.permdock,
+					inputRequired: await approvalInput(checks.options, decision, handlerContext, context, capabilities)
+				})
 			};
-			if (stillAllowed(rechecked.raw, completion.approved)) return { ok: true };
+		} catch {
 			return {
 				ok: false,
-				refusal: rechecked.raw.outcome === "denied" ? deniedRefusal(rechecked.raw, permission, rechecked.data) : plainRefusal(permission, `Denied: ${permission.key} was revoked before the call completed.`, {})
+				refusal: failedRefusal(permission, "failed")
 			};
 		}
-		const checked = await kernel.check(binding, void 0, call, compact({ resumeToken: approvalTokenOf(context) }));
-		if (!checked.ok) return {
-			ok: false,
-			refusal: failedRefusal(permission, checked.failure)
-		};
-		const { raw, decision, data } = checked;
-		switch (decision.outcome) {
-			case "granted": return raw.outcome === "approval-required" ? {
-				ok: true,
-				approved: raw.token
-			} : { ok: true };
-			case "denied": return {
-				ok: false,
-				refusal: decision.denials.some((denial) => denial.reason === "insufficient-user-authentication") ? stepUpRefusal(decision, permission, data, context, capabilities) : deniedRefusal(decision, permission, data)
-			};
-			case "approval-required": try {
-				return {
-					ok: false,
-					refusal: compact({
-						...approvalRefusal(decision, permission, data),
-						inputRequired: await approvalInput(decision, handlerContext, context, capabilities)
-					})
-				};
-			} catch {
-				return {
-					ok: false,
-					refusal: failedRefusal(permission, "failed")
-				};
-			}
-			default: return decision;
+		default: return decision;
+	}
+}
+/** `decideCall` with the refusal text replaced by `deniedText`'s. */
+async function checkCall(checks, permission, reach, args, load, context, handlerContext, capabilities, completion, tool) {
+	const checked = await decideCall(checks, permission, reach, args, load, context, handlerContext, capabilities, completion, tool);
+	const { deniedText } = checks.options;
+	if (checked.ok || deniedText === void 0) return checked;
+	const { refusal } = checked;
+	return {
+		ok: false,
+		refusal: {
+			...refusal,
+			text: refusalText(deniedText, {
+				decision: refusal.decision ?? null,
+				permission,
+				text: refusal.text
+			}, (error) => {
+				checks.kernel.report(refusal.permdock, error);
+			})
 		}
 	};
-	const visible = async (context, permissionOf, keys, declaredOf = () => void 0) => {
-		const authInfo = context.http?.authInfo;
-		const shown = /* @__PURE__ */ new Set();
-		const guarded = [];
-		for (const key of keys) {
-			const permission = permissionOf(key);
-			if (permission === void 0) shown.add(key);
-			else if (reachable(authInfo, reachOf(permission, declaredOf(key)))) guarded.push({
-				key,
-				permission
-			});
-		}
-		if (guarded.length === 0) return shown;
-		let permdock;
-		try {
-			permdock = await kernel.instance(compact({ authInfo }));
-		} catch {
-			return shown;
-		}
-		for (const entry of guarded) if (mayUse(permdock, entry.permission)) shown.add(entry.key);
+}
+/**
+* The keys a list shows: unguarded ones, and guarded ones the token reaches and the subject may use.
+* With `tools`, a guarded key is also a tool name an `agent` actor's `tools` list must name.
+*/
+async function visible(checks, context, permissionOf, keys, declaredOf = () => void 0, tools = false) {
+	const authInfo = context.http?.authInfo;
+	const shown = /* @__PURE__ */ new Set();
+	const guarded = [];
+	for (const key of keys) {
+		const permission = permissionOf(key);
+		if (permission === void 0) shown.add(key);
+		else if (reachable(checks, authInfo, reachOf(checks.policy, permission, declaredOf(key)))) guarded.push({
+			key,
+			permission
+		});
+	}
+	if (guarded.length === 0) return shown;
+	let permdock;
+	try {
+		permdock = await checks.kernel.instance(compact({ authInfo }));
+	} catch {
 		return shown;
-	};
-	const guard = (permission, load, handler, dataArgs, onRefusal, extra = {}) => async (...params) => {
+	}
+	for (const entry of guarded) if ((!tools || actorMayCallTool(permdock.subject.actor, entry.key)) && permdock.mayUse(entry.permission)) shown.add(entry.key);
+	return shown;
+}
+/** `handler` behind the call check; a refusal goes to `onRefusal` instead. */
+function guard(checks, permission, load, handler, dataArgs, onRefusal, extra = {}) {
+	return async (...params) => {
 		const raw = params.at(-1);
 		const context = contextOf(raw);
-		const loader = load === void 0 ? void 0 : () => load(...dataArgs(params));
-		const reach = extra.reach ?? reachOf(permission, void 0);
-		const checked = await check(permission, reach, loader, context, raw, extra.capabilities);
+		const args = dataArgs(params);
+		const loader = load === void 0 ? void 0 : () => load(...args);
+		const reach = extra.reach ?? reachOf(checks.policy, permission, void 0);
+		const tool = extra.tool?.();
+		const checked = await checkCall(checks, permission, reach, args, loader, context, raw, extra.capabilities, void 0, tool);
 		let result;
 		if (checked.ok) {
 			result = await handler(...params);
 			if (extra.longRunning === true) {
-				const again = await check(permission, reach, loader, context, raw, extra.capabilities, { approved: checked.approved });
+				const again = await checkCall(checks, permission, reach, args, loader, context, raw, extra.capabilities, { approved: checked.approved }, tool);
 				if (!again.ok) result = onRefusal(again.refusal);
 			}
 		} else result = onRefusal(checked.refusal);
 		await extra.after?.(context);
 		return result;
 	};
-	const protectServer = (server, enforcement) => {
-		const tools = /* @__PURE__ */ new Map();
-		const toolScopes = /* @__PURE__ */ new Map();
-		const prompts = /* @__PURE__ */ new Map();
-		const resources = /* @__PURE__ */ new Map();
-		const templates = [];
-		const lastListed = boundedMap(SESSIONS_PER_SERVER);
-		const toolPermission = (name) => tools.get(name);
-		const toolDeclared = (name) => toolScopes.get(name);
-		const promptPermission = (name) => prompts.get(name);
-		const resourcePermission = (uri) => {
-			const direct = resources.get(uri);
-			if (direct !== void 0) return direct;
-			return templates.find((entry) => entry.template.uriTemplate.match(uri) !== null)?.permission;
-		};
-		const templatePermission = (uriTemplate) => templates.find((entry) => entry.template.uriTemplate.toString() === uriTemplate)?.permission;
-		const listFilter = (field, keyOf, permissionOf, remember) => async (result, rawContext) => {
-			if (!isRecord(result) || !Array.isArray(result[field])) return result;
-			const context = contextOf(rawContext);
-			const entries = result[field];
-			const shown = await visible(context, permissionOf, entries.map(keyOf), remember ? toolDeclared : void 0);
-			const kept = entries.filter((entry) => shown.has(keyOf(entry)));
-			if (remember) lastListed.set(sessionKey(context), [...shown].toSorted().join(","));
-			return definesCacheScope(context) ? {
-				...result,
-				[field]: kept,
-				cacheScope: "private"
-			} : {
-				...result,
-				[field]: kept
-			};
-		};
-		const filters = {
-			"tools/list": listFilter("tools", (entry) => entry.name, toolPermission, true),
-			"prompts/list": listFilter("prompts", (entry) => entry.name, promptPermission, false),
-			"resources/list": listFilter("resources", (entry) => entry.uri, resourcePermission, false),
-			"resources/templates/list": listFilter("resourceTemplates", (entry) => entry.uriTemplate, templatePermission, false)
-		};
-		const inner = server.server;
-		const capabilities = () => inner.getClientCapabilities?.();
-		const set = inner.setRequestHandler.bind(inner);
-		inner.setRequestHandler = (method, ...rest) => {
-			const filter = Object.hasOwn(filters, method) ? filters[method] : void 0;
-			const [handler] = rest;
-			if (filter !== void 0 && rest.length === 1 && typeof handler === "function") {
-				set(method, async (request, context) => filter(await handler(request, context), context));
-				return;
-			}
-			set(method, ...rest);
-		};
-		for (const method of Object.keys(filters)) {
-			const existing = inner._getRequestHandler?.(method);
-			if (existing !== void 0) {
-				inner.removeRequestHandler(method);
-				inner.setRequestHandler(method, (request, context) => existing(request, context));
-			}
+}
+//#endregion
+//#region src/mcp/protect-server.ts
+const SESSIONS_PER_SERVER = 1e3;
+function requirePermission(kind, name, config) {
+	const permission = isRecord(config) ? config["permission"] : void 0;
+	if (!isRecord(permission) || typeof permission["key"] !== "string") throw new TypeError(`permdock/mcp: ${kind} ${name} has no permission; every guarded registration needs one.`);
+	return permission;
+}
+function guardUpdates(registered, wrap, rename, currentName) {
+	const update = registered.update.bind(registered);
+	registered.update = (updates) => {
+		const next = { ...updates };
+		if (typeof updates["callback"] === "function") next["callback"] = wrap(updates["callback"]);
+		if (rename !== void 0 && currentName !== void 0) {
+			const to = updates["name"];
+			if (typeof to === "string" || to === null) rename(currentName(), to);
 		}
-		const announce = async (context) => {
-			const key = sessionKey(context);
-			const before = lastListed.get(key);
-			if (before === void 0) return;
-			const after = [...await visible(context, toolPermission, [...tools.keys()], toolDeclared)].toSorted().join(",");
-			if (after === before) return;
-			lastListed.set(key, after);
-			try {
-				await (context.mcpReq?.notify?.({ method: "notifications/tools/list_changed" }) ?? inner.sendToolListChanged?.());
-			} catch {}
+		update(next);
+	};
+}
+function protectServer(checks, server, enforcement) {
+	const tools = /* @__PURE__ */ new Map();
+	const toolScopes = /* @__PURE__ */ new Map();
+	const prompts = /* @__PURE__ */ new Map();
+	const resources = /* @__PURE__ */ new Map();
+	const templates = [];
+	const lastListed = boundedMap(SESSIONS_PER_SERVER);
+	const toolPermission = (name) => tools.get(name);
+	const toolDeclared = (name) => toolScopes.get(name);
+	const promptPermission = (name) => prompts.get(name);
+	const resourcePermission = (uri) => {
+		const direct = resources.get(uri);
+		if (direct !== void 0) return direct;
+		return templates.find((entry) => entry.template.uriTemplate.match(uri) !== null)?.permission;
+	};
+	const templatePermission = (uriTemplate) => templates.find((entry) => entry.template.uriTemplate.toString() === uriTemplate)?.permission;
+	const listFilter = (field, keyOf, permissionOf, remember) => async (result, rawContext) => {
+		if (!isRecord(result) || !Array.isArray(result[field])) return result;
+		const context = contextOf(rawContext);
+		const entries = result[field];
+		const shown = await visible(checks, context, permissionOf, entries.map(keyOf), remember ? toolDeclared : void 0, remember);
+		const kept = entries.filter((entry) => shown.has(keyOf(entry)));
+		if (remember) lastListed.set(sessionKey(context), [...shown].toSorted().join(","));
+		return definesCacheScope(context) ? {
+			...result,
+			[field]: kept,
+			cacheScope: "private"
+		} : {
+			...result,
+			[field]: kept
 		};
-		const guardTool = (permission, reach, load, handler, longRunning) => guard(permission, load, handler, (params) => params.length >= 2 ? [params[0]] : [void 0], toolRefusal, {
-			after: announce,
-			longRunning,
-			capabilities,
-			reach
+	};
+	const filters = {
+		"tools/list": listFilter("tools", (entry) => entry.name, toolPermission, true),
+		"prompts/list": listFilter("prompts", (entry) => entry.name, promptPermission, false),
+		"resources/list": listFilter("resources", (entry) => entry.uri, resourcePermission, false),
+		"resources/templates/list": listFilter("resourceTemplates", (entry) => entry.uriTemplate, templatePermission, false)
+	};
+	const inner = server.server;
+	const capabilities = () => inner.getClientCapabilities?.();
+	const set = inner.setRequestHandler.bind(inner);
+	inner.setRequestHandler = (method, ...rest) => {
+		const filter = Object.hasOwn(filters, method) ? filters[method] : void 0;
+		const [handler] = rest;
+		if (filter !== void 0 && rest.length === 1 && typeof handler === "function") {
+			set(method, async (request, context) => filter(await handler(request, context), context));
+			return;
+		}
+		set(method, ...rest);
+	};
+	for (const method of Object.keys(filters)) {
+		const existing = inner._getRequestHandler?.(method);
+		if (existing !== void 0) {
+			inner.removeRequestHandler(method);
+			inner.setRequestHandler(method, (request, context) => existing(request, context));
+		}
+	}
+	const announce = async (context) => {
+		const key = sessionKey(context);
+		const before = lastListed.get(key);
+		if (before === void 0) return;
+		const after = [...await visible(checks, context, toolPermission, [...tools.keys()], toolDeclared, true)].toSorted().join(",");
+		if (after === before) return;
+		lastListed.set(key, after);
+		try {
+			await (context.mcpReq?.notify?.({ method: "notifications/tools/list_changed" }) ?? inner.sendToolListChanged?.());
+		} catch {}
+	};
+	const guardTool = (tool, permission, reach, load, handler, longRunning) => guard(checks, permission, load, handler, (params) => params.length >= 2 ? [params[0]] : [void 0], toolRefusal, {
+		after: announce,
+		longRunning,
+		capabilities,
+		reach,
+		tool
+	});
+	const originalTool = server.registerTool.bind(server);
+	const toolPermissionOf = (name, config) => {
+		if (enforcement === void 0 || config["permission"] !== void 0) return requirePermission("tool", name, config);
+		for (const field of ["data", "longRunning"]) if (config[field] !== void 0) throw new TypeError(`permdock/mcp: tool ${name} sets ${field}, but with enforce: 'procedure' its procedure decides.`);
+		return requirePermission("tool", name, { permission: enforcement.permissionFor(name) });
+	};
+	/** With `enforce: 'procedure'` the handler runs undecided: the procedure it calls decides. */
+	const wrapTool = (tool, permission, reach, load, handler, longRunning) => enforcement === void 0 ? guardTool(tool, permission, reach, load, handler, longRunning) : async (...params) => {
+		const result = await handler(...params);
+		await announce(contextOf(params.at(-1)));
+		return result;
+	};
+	const registerTool = (name, config, handler) => {
+		const permission = toolPermissionOf(name, config);
+		const { permission: _permission, data, scopeChallenge, longRunning: rawLongRunning, oauthScopes: rawScopes, ...passthrough } = config;
+		const load = data;
+		const longRunning = rawLongRunning === true;
+		const declared = declaredScopes(name, rawScopes === void 0 ? enforcement?.oauthScopesFor?.(name) : rawScopes);
+		const reach = reachOf(checks.policy, permission, declared);
+		let current = name;
+		const tool = () => current;
+		const registered = originalTool(name, {
+			...passthrough,
+			annotations: {
+				...annotationsFor(permission),
+				...passthrough["annotations"]
+			},
+			scopeChallenge: challengeFor(scopeChallenge, reach.scopes, reach.challenge)
+		}, wrapTool(tool, permission, reach, load, handler, longRunning));
+		tools.set(name, permission);
+		if (declared !== void 0) toolScopes.set(name, declared);
+		guardUpdates(registered, (callback) => wrapTool(tool, permission, reach, load, callback, longRunning), (from, to) => {
+			tools.delete(from);
+			toolScopes.delete(from);
+			if (to !== null) {
+				tools.set(to, permission);
+				if (declared !== void 0) toolScopes.set(to, declared);
+				current = to;
+			}
+		}, () => current);
+		return registered;
+	};
+	const originalPrompt = server.registerPrompt.bind(server);
+	const registerPrompt = (name, config, handler) => {
+		const permission = requirePermission("prompt", name, config);
+		const { permission: _permission, data, scopeChallenge, ...passthrough } = config;
+		const load = data;
+		const wrap = (callback) => guard(checks, permission, load, callback, (params) => params.length >= 2 ? [params[0]] : [void 0], throwRefusal, { capabilities });
+		const registered = originalPrompt(name, {
+			...passthrough,
+			scopeChallenge: challengeFor(scopeChallenge, scopesReaching(checks.policy, permission), challengeScope(checks.policy, permission))
+		}, wrap(handler));
+		prompts.set(name, permission);
+		guardUpdates(registered, wrap);
+		return registered;
+	};
+	const originalResource = server.registerResource.bind(server);
+	const registerResource = (name, uriOrTemplate, config, read) => {
+		const permission = requirePermission("resource", name, config);
+		const { permission: _permission, data, scopeChallenge, ...passthrough } = config;
+		const load = data;
+		const wrap = (callback) => guard(checks, permission, load, callback, (params) => params.slice(0, -1), throwRefusal, { capabilities });
+		const registered = originalResource(name, uriOrTemplate, {
+			...passthrough,
+			scopeChallenge: challengeFor(scopeChallenge, scopesReaching(checks.policy, permission), challengeScope(checks.policy, permission))
+		}, wrap(read));
+		if (typeof uriOrTemplate === "string") resources.set(uriOrTemplate, permission);
+		else templates.push({
+			template: uriOrTemplate,
+			permission
 		});
-		const originalTool = server.registerTool.bind(server);
-		const toolPermissionOf = (name, config) => {
-			if (enforcement === void 0 || config["permission"] !== void 0) return requirePermission("tool", name, config);
-			for (const field of ["data", "longRunning"]) if (config[field] !== void 0) throw new TypeError(`permdock/mcp: tool ${name} sets ${field}, but with enforce: 'procedure' its procedure decides.`);
-			return requirePermission("tool", name, { permission: enforcement.permissionFor(name) });
-		};
-		/** With `enforce: 'procedure'` the handler runs undecided: the procedure it calls decides. */
-		const wrapTool = (permission, reach, load, handler, longRunning) => enforcement === void 0 ? guardTool(permission, reach, load, handler, longRunning) : async (...params) => {
-			const result = await handler(...params);
-			await announce(contextOf(params.at(-1)));
-			return result;
-		};
-		const registerTool = (name, config, handler) => {
-			const permission = toolPermissionOf(name, config);
-			const { permission: _permission, data, scopeChallenge, longRunning: rawLongRunning, oauthScopes: rawScopes, ...passthrough } = config;
-			const load = data;
-			const longRunning = rawLongRunning === true;
-			const declared = declaredScopes(name, rawScopes === void 0 ? enforcement?.oauthScopesFor?.(name) : rawScopes);
-			const reach = reachOf(permission, declared);
-			const registered = originalTool(name, {
-				...passthrough,
-				annotations: {
-					...annotationsFor(permission),
-					...passthrough["annotations"]
-				},
-				scopeChallenge: challengeFor(scopeChallenge, reach.scopes, reach.challenge)
-			}, wrapTool(permission, reach, load, handler, longRunning));
-			tools.set(name, permission);
-			if (declared !== void 0) toolScopes.set(name, declared);
-			let current = name;
-			guardUpdates(registered, (callback) => wrapTool(permission, reach, load, callback, longRunning), (from, to) => {
-				tools.delete(from);
-				toolScopes.delete(from);
-				if (to !== null) {
-					tools.set(to, permission);
-					if (declared !== void 0) toolScopes.set(to, declared);
-					current = to;
-				}
-			}, () => current);
-			return registered;
-		};
-		const originalPrompt = server.registerPrompt.bind(server);
-		const registerPrompt = (name, config, handler) => {
-			const permission = requirePermission("prompt", name, config);
-			const { permission: _permission, data, scopeChallenge, ...passthrough } = config;
-			const load = data;
-			const wrap = (callback) => guard(permission, load, callback, (params) => params.length >= 2 ? [params[0]] : [void 0], throwRefusal, { capabilities });
-			const registered = originalPrompt(name, {
-				...passthrough,
-				scopeChallenge: challengeFor(scopeChallenge, scopesReaching(policy, permission), challengeScope(policy, permission))
-			}, wrap(handler));
-			prompts.set(name, permission);
-			guardUpdates(registered, wrap);
-			return registered;
-		};
-		const originalResource = server.registerResource.bind(server);
-		const registerResource = (name, uriOrTemplate, config, read) => {
-			const permission = requirePermission("resource", name, config);
-			const { permission: _permission, data, scopeChallenge, ...passthrough } = config;
-			const load = data;
-			const wrap = (callback) => guard(permission, load, callback, (params) => params.slice(0, -1), throwRefusal, { capabilities });
-			const registered = originalResource(name, uriOrTemplate, {
-				...passthrough,
-				scopeChallenge: challengeFor(scopeChallenge, scopesReaching(policy, permission), challengeScope(policy, permission))
-			}, wrap(read));
-			if (typeof uriOrTemplate === "string") resources.set(uriOrTemplate, permission);
-			else templates.push({
-				template: uriOrTemplate,
-				permission
-			});
-			guardUpdates(registered, wrap);
-			return registered;
-		};
-		const guarded = server;
-		guarded["registerTool"] = registerTool;
-		guarded["registerPrompt"] = registerPrompt;
-		guarded["registerResource"] = registerResource;
-		return server;
+		guardUpdates(registered, wrap);
+		return registered;
+	};
+	const guarded = server;
+	guarded["registerTool"] = registerTool;
+	guarded["registerPrompt"] = registerPrompt;
+	guarded["registerResource"] = registerResource;
+	return server;
+}
+//#endregion
+//#region src/mcp/subject.ts
+const DEFAULT_MCP_ACTOR_KIND = "mcp-client";
+/** `kind`, or the default when absent; `undefined` for a kind that is not a non-empty string. */
+function mcpActorKind(kind) {
+	if (kind === void 0) return DEFAULT_MCP_ACTOR_KIND;
+	return typeof kind === "string" && kind !== "" ? kind : void 0;
+}
+/**
+* Maps the `AuthInfo` the MCP SDK's bearer verification produced to a
+* `Subject`: the principal from the verified claims in `extra`, the client
+* as an actor of kind `actorKind` (`mcp-client` by default), the granted
+* scopes as the delegation. Never verifies and never throws; anything
+* unusable, including an `actorKind` that is not a non-empty string, is
+* the anonymous subject.
+*/
+function subjectFromMcp(authInfo, options = {}) {
+	try {
+		const kind = mcpActorKind(options.actorKind);
+		if (authInfo === void 0 || !isRecord(authInfo.extra) || kind === void 0) return anonymousSubject();
+		const claims = compact({
+			...authInfo.extra,
+			authorization_details: authInfo.extra["authorizationDetails"] ?? authInfo.extra["authorization_details"],
+			scope: authInfo.scopes?.join(" "),
+			client_id: authInfo.clientId,
+			exp: authInfo.expiresAt
+		});
+		const mapped = mapClaimsToSubject(claims, options);
+		if (mapped.invalidClaims || mapped.invalidChain || mapped.subject.principal === null) return anonymousSubject();
+		const clientId = authInfo.clientId;
+		return freezeDeep(compact({
+			...mapped.subject,
+			actor: typeof clientId === "string" && clientId !== "" ? compact({
+				id: clientId,
+				kind,
+				client: clientNameOf(options.clients, clientId)
+			}) : mapped.subject.actor
+		}));
+	} catch {
+		return anonymousSubject();
+	}
+}
+//#endregion
+//#region src/mcp/create.ts
+function createPermDock(policy, given) {
+	const options = withApp(policy, given);
+	const actorKind = mcpActorKind(options.actorKind);
+	if (actorKind === void 0) throw new TypeError("permdock/mcp: actorKind must be a non-empty string");
+	const checks = {
+		policy,
+		options,
+		kernel: createAgentKernel(policy, compact({
+			subject: (call) => options.subject(call.authInfo ?? {}),
+			actor: (call) => {
+				if (options.actor !== void 0) return options.actor(call.authInfo ?? {});
+				const clientId = call.authInfo?.clientId;
+				return typeof clientId === "string" && clientId !== "" ? compact({
+					id: clientId,
+					kind: actorKind,
+					client: clientNameOf(options.clients, clientId)
+				}) : void 0;
+			},
+			delegation: (call) => {
+				if (options.delegation !== void 0) return options.delegation(call.authInfo ?? {});
+				return call.authInfo === void 0 ? void 0 : delegationFrom(call.authInfo.scopes, call.authInfo.extra);
+			},
+			tenant: tenantOf(options.tenant),
+			store: options.store,
+			adapter: "mcp",
+			boundary: "mcp-args",
+			wrap: composeWraps(options.otel, options.wrap),
+			context: options.context === void 0 ? void 0 : (call) => options.context?.(call.authInfo ?? {}),
+			...instanceOptions(options)
+		}))
 	};
-	return { protectServer };
+	return { protectServer: ((server, enforcement) => protectServer(checks, server, enforcement)) };
 }
 //#endregion
 export { APPROVAL_META_KEY, createPermDock, subjectFromMcp };