permdock 0.1.0 → 0.3.0

package/dist/mcp/index.js

@@ -1,20 +1,71 @@
 import { t as compact } from "../compact-y6vfu2_f.js";
-import { n as freezeDeep } from "../freeze-y1_jQL4v.js";
-import { t as annotationsFor } from "../permissions-DC7GROPA.js";
-import { t as describe } from "../describe-Bt1YD5uS.js";
-import { s as wireDenials } from "../errors-Iy71s7Oj.js";
-import { t as createPermDock$1 } from "../permdock-yoZ7EjxX.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 { n as resourceRef } from "../resource-ref-CaS9yVPi.js";
 import { t as anonymousSubject } from "../subject-C6dLxqHU.js";
-import { t as mayUse } from "../may-use-CnFEjVEp.js";
-import { l as storedApprovalToken, s as resumeDecision } from "../helpers-DnSOrhB9.js";
-import { n as mapClaimsToSubject } from "../map-claims-B_6I1Rn-.js";
-import { c as stepUpOf, r as bearerChallenge, s as protectedResourceMetadataUrl } from "../problem-Cgp9-KZA.js";
+import { t as mayUse } from "../may-use-DndQ5tQ-.js";
+import { c as protectedResourceMetadataUrl, n as bearerChallenge } from "../problem-B43ztKIm.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 { 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
 /** `_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) {
@@ -24,11 +75,11 @@ function stillAllowed(decision, approved) {
 		default: return decision;
 	}
 }
-function isRecord$1(value) {
+function isRecord(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function contextOf(value) {
-	return isRecord$1(value) ? value : {};
+	return isRecord(value) ? value : {};
 }
 function approvalTokenOf(context) {
 	let fromState;
@@ -53,8 +104,8 @@ function delegationOf(authInfo) {
 		authorizationDetails: authorizationDetailsOf(authInfo)
 	});
 }
-function hasScope(authInfo, scope) {
-	return (authInfo.scopes ?? []).includes(scope);
+function hasScope(authInfo, scopes) {
+	return scopes.some((scope) => (authInfo.scopes ?? []).includes(scope));
 }
 function resourceMetadataOf(authInfo) {
 	if (authInfo.resourceMetadataUrl !== void 0) return authInfo.resourceMetadataUrl;
@@ -69,11 +120,20 @@ function sameResource(expected, actual) {
 		return false;
 	}
 }
+/**
+* Whether the request was sent under a revision that defines `cacheScope` on
+* list results. Only those requests carry the per-request envelope; a
+* 2025-era request has none and gets no cache fields.
+*/
+function definesCacheScope(context) {
+	const version = context.mcpReq?.envelope?.[PROTOCOL_VERSION];
+	return typeof version === "string" && version >= CACHEABLE_LISTS_SINCE;
+}
 function acceptsUrlElicitation(context, fallback) {
 	const fromEnvelope = context.mcpReq?.envelope?.[CLIENT_CAPABILITIES];
-	const capabilities = isRecord$1(fromEnvelope) ? fromEnvelope : fallback?.();
-	if (!isRecord$1(capabilities) || !isRecord$1(capabilities["elicitation"])) return false;
-	return isRecord$1(capabilities["elicitation"]["url"]);
+	const capabilities = isRecord(fromEnvelope) ? fromEnvelope : fallback?.();
+	if (!isRecord(capabilities) || !isRecord(capabilities["elicitation"])) return false;
+	return isRecord(capabilities["elicitation"]["url"]);
 }
 function withParams(at, params) {
 	let url;
@@ -99,16 +159,6 @@ function urlElicitation(key, message, url, requestState) {
 		requestState
 	});
 }
-function resourceRef(permission, data) {
-	if (isRecord$1(data)) {
-		const id = data["id"];
-		if (typeof id === "string" || typeof id === "number") return {
-			type: permission.resource,
-			id: String(id)
-		};
-	}
-	return { type: permission.resource };
-}
 function deniedRefusal(decision, permission, data) {
 	const alternatives = decision.alternatives.map((leaf) => leaf.key);
 	const resource = resourceRef(permission, data);
@@ -147,6 +197,24 @@ 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: [{
+			role: null,
+			reason: "validation"
+		}] });
+		case "no-data": return plainRefusal(permission, `Denied: ${permission.key} found nothing to decide on.`, { denials: [{
+			role: null,
+			reason: "validation"
+		}] });
+		case "failed": return plainRefusal(permission, `Denied: ${permission.key} failed closed.`, {});
+		default: return failure;
+	}
+}
 function toolRefusal(refusal) {
 	if (refusal.inputRequired !== void 0) return refusal.inputRequired;
 	return {
@@ -159,8 +227,8 @@ function toolRefusal(refusal) {
 	};
 }
 function requirePermission(kind, name, config) {
-	const permission = isRecord$1(config) ? config["permission"] : void 0;
-	if (!isRecord$1(permission) || typeof permission["key"] !== "string") throw new TypeError(`permdock/mcp: ${kind} ${name} has no permission; every guarded registration needs one.`);
+	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) {
@@ -170,13 +238,21 @@ function throwRefusal(refusal) {
 	if (refusal.inputRequired !== void 0) return refusal.inputRequired;
 	throw new Error(refusal.text);
 }
-function challengeFor(permission, own) {
+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, permission.scope)) return;
-		return { scopes: [permission.scope] };
+		if (authInfo === void 0 || hasScope(authInfo, reaching)) return;
+		return { scopes: [challenged] };
 	};
 }
 function guardUpdates(registered, wrap, rename, currentName) {
@@ -192,40 +268,35 @@ function guardUpdates(registered, wrap, rename, currentName) {
 	};
 }
 function createPermDock(policy, options) {
-	const instanceFor = async (authInfo) => {
-		const material = authInfo ?? {};
-		let user = null;
-		try {
-			user = await options.subject(material);
-		} catch {
-			user = null;
-		}
-		let tenant;
-		try {
-			tenant = typeof options.tenant === "function" ? await options.tenant(material) : options.tenant;
-		} catch {
-			tenant = void 0;
-		}
-		const clientId = authInfo?.clientId;
-		const built = await createPermDock$1(policy, user, compact({
-			tenant,
-			actor: typeof clientId === "string" && clientId !== "" ? {
+	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: "mcp-client"
-			} : void 0,
-			delegation: authInfo === void 0 ? void 0 : delegationOf(authInfo),
-			memberships: options.memberships,
-			relations: options.relations,
-			entitlements: options.entitlements,
-			customRoles: options.customRoles,
-			policies: options.policies,
-			sink: options.sink,
-			limits: options.limits
-		}));
-		return options.otel === void 0 ? built : options.otel(built);
-	};
+				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 reachable = (authInfo, permission) => authInfo === void 0 ? options.requireAuthInfo !== true : forThisServer(authInfo) && hasScope(authInfo, permission.scope);
+	const reachOf = (permission, declared) => 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;
@@ -258,7 +329,7 @@ function createPermDock(policy, options) {
 			inputRequired: url === void 0 ? void 0 : urlElicitation("step_up", `Sign in again to use ${permission.key}.`, url, void 0)
 		});
 	};
-	const check = async (permission, load, context, handlerContext, capabilities, completion) => {
+	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,
@@ -268,99 +339,80 @@ function createPermDock(policy, options) {
 			ok: false,
 			refusal: plainRefusal(permission, "Denied: the token was not issued for this server.", { error: "invalid_token" })
 		};
-		if (authInfo !== void 0 && !hasScope(authInfo, permission.scope)) {
+		if (authInfo !== void 0 && !hasScope(authInfo, reach.scopes)) {
 			const resourceMetadata = resourceMetadataOf(authInfo);
+			const challenged = reach.challenge;
 			return {
 				ok: false,
-				refusal: plainRefusal(permission, `Denied: ${permission.key} needs the ${permission.scope} scope.`, compact({
+				refusal: plainRefusal(permission, `Denied: ${permission.key} needs the ${challenged} scope.`, compact({
 					error: "insufficient_scope",
-					scope: permission.scope,
+					scope: challenged,
 					resource_metadata: resourceMetadata,
 					www_authenticate: bearerChallenge(compact({
 						error: "insufficient_scope",
-						scopes: [permission.scope],
+						scopes: [challenged],
 						resourceMetadata
 					}))
 				}))
 			};
 		}
-		let data;
-		if (load !== void 0) {
-			try {
-				data = await load();
-			} catch {
-				return {
-					ok: false,
-					refusal: plainRefusal(permission, `Denied: ${permission.key} failed closed.`, { denials: [{
-						role: null,
-						reason: "validation"
-					}] })
-				};
-			}
-			if (data === null || data === void 0) return {
+		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)
+			};
+			if (stillAllowed(rechecked.raw, completion.approved)) return { ok: true };
+			return {
 				ok: false,
-				refusal: plainRefusal(permission, `Denied: ${permission.key} found nothing to decide on.`, { denials: [{
-					role: null,
-					reason: "validation"
-				}] })
+				refusal: rechecked.raw.outcome === "denied" ? deniedRefusal(rechecked.raw, permission, rechecked.data) : plainRefusal(permission, `Denied: ${permission.key} was revoked before the call completed.`, {})
 			};
 		}
-		try {
-			const permdock = await instanceFor(authInfo);
-			const raw = permdock.decide(permission, data, {
-				source: completion === void 0 ? "adapter" : "simulate",
-				adapter: "mcp",
-				boundary: "mcp-args"
-			});
-			if (completion !== void 0) {
-				if (stillAllowed(raw, completion.approved)) return { ok: true };
+		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: raw.outcome === "denied" ? deniedRefusal(raw, permission, data) : plainRefusal(permission, `Denied: ${permission.key} was revoked before the call completed.`, {})
-				};
-			}
-			const decision = await resumeDecision({
-				decision: raw,
-				permission,
-				subject: permdock.subject,
-				store: options.store,
-				resource: resourceRef(permission, data),
-				adapter: "mcp",
-				token: approvalTokenOf(context) ?? await storedApprovalToken(options.store, raw, false)
-			});
-			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": return {
 					ok: false,
 					refusal: compact({
 						...approvalRefusal(decision, permission, data),
 						inputRequired: await approvalInput(decision, handlerContext, context, capabilities)
 					})
 				};
-				default: return decision;
+			} catch {
+				return {
+					ok: false,
+					refusal: failedRefusal(permission, "failed")
+				};
 			}
-		} catch {
-			return {
-				ok: false,
-				refusal: plainRefusal(permission, `Denied: ${permission.key} failed closed.`, {})
-			};
+			default: return decision;
 		}
 	};
-	const visible = async (context, permissionOf, keys) => {
+	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, permission)) guarded.push({
+			else if (reachable(authInfo, reachOf(permission, declaredOf(key)))) guarded.push({
 				key,
 				permission
 			});
@@ -368,7 +420,7 @@ function createPermDock(policy, options) {
 		if (guarded.length === 0) return shown;
 		let permdock;
 		try {
-			permdock = await instanceFor(authInfo);
+			permdock = await kernel.instance(compact({ authInfo }));
 		} catch {
 			return shown;
 		}
@@ -379,25 +431,28 @@ function createPermDock(policy, options) {
 		const raw = params.at(-1);
 		const context = contextOf(raw);
 		const loader = load === void 0 ? void 0 : () => load(...dataArgs(params));
-		const checked = await check(permission, loader, context, raw, extra.capabilities);
+		const reach = extra.reach ?? reachOf(permission, void 0);
+		const checked = await check(permission, reach, loader, context, raw, extra.capabilities);
 		let result;
 		if (checked.ok) {
 			result = await handler(...params);
 			if (extra.longRunning === true) {
-				const again = await check(permission, loader, context, raw, extra.capabilities, { approved: checked.approved });
+				const again = await check(permission, reach, loader, context, raw, extra.capabilities, { approved: checked.approved });
 				if (!again.ok) result = onRefusal(again.refusal);
 			}
 		} else result = onRefusal(checked.refusal);
 		await extra.after?.(context);
 		return result;
 	};
-	const protectServer = (server) => {
+	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);
@@ -406,16 +461,19 @@ function createPermDock(policy, options) {
 		};
 		const templatePermission = (uriTemplate) => templates.find((entry) => entry.template.uriTemplate.toString() === uriTemplate)?.permission;
 		const listFilter = (field, keyOf, permissionOf, remember) => async (result, rawContext) => {
-			if (!isRecord$1(result) || !Array.isArray(result[field])) return result;
+			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));
+			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 {
+			return definesCacheScope(context) ? {
 				...result,
 				[field]: kept,
 				cacheScope: "private"
+			} : {
+				...result,
+				[field]: kept
 			};
 		};
 		const filters = {
@@ -447,38 +505,55 @@ function createPermDock(policy, options) {
 			const key = sessionKey(context);
 			const before = lastListed.get(key);
 			if (before === void 0) return;
-			const after = [...await visible(context, toolPermission, [...tools.keys()])].toSorted().join(",");
+			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 {}
 		};
-		const guardTool = (permission, load, handler, longRunning) => guard(permission, load, handler, (params) => params.length >= 2 ? [params[0]] : [void 0], toolRefusal, {
+		const guardTool = (permission, reach, load, handler, longRunning) => guard(permission, load, handler, (params) => params.length >= 2 ? [params[0]] : [void 0], toolRefusal, {
 			after: announce,
 			longRunning,
-			capabilities
+			capabilities,
+			reach
 		});
 		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 = requirePermission("tool", name, config);
-			const { permission: _permission, data, scopeChallenge, longRunning: rawLongRunning, ...passthrough } = config;
+			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(permission, scopeChallenge)
-			}, guardTool(permission, load, handler, longRunning));
+				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) => guardTool(permission, load, callback, longRunning), (from, to) => {
+			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);
@@ -492,7 +567,7 @@ function createPermDock(policy, options) {
 			const wrap = (callback) => guard(permission, load, callback, (params) => params.length >= 2 ? [params[0]] : [void 0], throwRefusal, { capabilities });
 			const registered = originalPrompt(name, {
 				...passthrough,
-				scopeChallenge: challengeFor(permission, scopeChallenge)
+				scopeChallenge: challengeFor(scopeChallenge, scopesReaching(policy, permission), challengeScope(policy, permission))
 			}, wrap(handler));
 			prompts.set(name, permission);
 			guardUpdates(registered, wrap);
@@ -506,7 +581,7 @@ function createPermDock(policy, options) {
 			const wrap = (callback) => guard(permission, load, callback, (params) => params.slice(0, -1), throwRefusal, { capabilities });
 			const registered = originalResource(name, uriOrTemplate, {
 				...passthrough,
-				scopeChallenge: challengeFor(permission, scopeChallenge)
+				scopeChallenge: challengeFor(scopeChallenge, scopesReaching(policy, permission), challengeScope(policy, permission))
 			}, wrap(read));
 			if (typeof uriOrTemplate === "string") resources.set(uriOrTemplate, permission);
 			else templates.push({
@@ -525,39 +600,4 @@ function createPermDock(policy, options) {
 	return { protectServer };
 }
 //#endregion
-//#region src/mcp/subject.ts
-function isRecord(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 `mcp-client` actor, the granted scopes as the delegation. Never
-* verifies and never throws; anything unusable is the anonymous subject.
-*/
-function subjectFromMcp(authInfo, options = {}) {
-	try {
-		if (authInfo === void 0 || !isRecord(authInfo.extra)) 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 !== "" ? {
-				id: clientId,
-				kind: "mcp-client"
-			} : mapped.subject.actor
-		}));
-	} catch {
-		return anonymousSubject();
-	}
-}
-//#endregion
 export { APPROVAL_META_KEY, createPermDock, subjectFromMcp };