permdock 0.0.0 → 0.2.0

package/dist/mcp/index.js

@@ -0,0 +1,603 @@
+import { t as compact } from "../compact-y6vfu2_f.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-CzqXjCpU.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 { 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-GSQnMz3O.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) {
+		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 : {};
+}
+function approvalTokenOf(context) {
+	let fromState;
+	try {
+		fromState = context.mcpReq?.requestState?.();
+	} catch {
+		fromState = void 0;
+	}
+	if (typeof fromState === "string" && fromState !== "") return fromState;
+	const fromMeta = context.mcpReq?._meta?.[APPROVAL_META_KEY];
+	if (typeof fromMeta === "string" && fromMeta !== "") return fromMeta;
+	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;
+	return resource?.protocol === "https:" || resource?.protocol === "http:" ? protectedResourceMetadataUrl(resource) : void 0;
+}
+function sameResource(expected, actual) {
+	if (actual === void 0) return false;
+	try {
+		return new URL(String(expected)).href === new URL(String(actual)).href;
+	} catch {
+		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(fromEnvelope) ? fromEnvelope : fallback?.();
+	if (!isRecord(capabilities) || !isRecord(capabilities["elicitation"])) return false;
+	return isRecord(capabilities["elicitation"]["url"]);
+}
+function withParams(at, params) {
+	let url;
+	try {
+		url = new URL(at);
+	} catch {
+		return;
+	}
+	for (const [name, value] of Object.entries(params)) if (value !== void 0) url.searchParams.set(name, value);
+	return url.href;
+}
+function urlElicitation(key, message, url, requestState) {
+	return compact({
+		resultType: "input_required",
+		inputRequests: { [key]: {
+			method: "elicitation/create",
+			params: {
+				mode: "url",
+				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
+		}
+	};
+}
+function approvalRefusal(decision, permission, data) {
+	return {
+		text: describe(decision).detail,
+		structured: {
+			outcome: "approval-required",
+			permission: permission.key,
+			resource: resourceRef(permission, data),
+			token: decision.token
+		}
+	};
+}
+function plainRefusal(permission, text, extra) {
+	return {
+		text,
+		structured: {
+			outcome: "denied",
+			permission: permission.key,
+			resource: { type: permission.resource },
+			alternatives: [],
+			...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 {
+		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 ?? "";
+}
+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]);
+}
+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);
+	};
+}
+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 ? {
+		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);
+	};
+	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)
+		});
+	};
+	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 {
+			ok: false,
+			refusal: plainRefusal(permission, "Denied: the token was not issued for this server.", { error: "invalid_token" })
+		};
+		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 ${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)
+			};
+			if (stillAllowed(rechecked.raw, completion.approved)) return { ok: true };
+			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.`, {})
+			};
+		}
+		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;
+		}
+	};
+	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);
+		return shown;
+	};
+	const guard = (permission, load, handler, dataArgs, onRefusal, extra = {}) => 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);
+		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 });
+				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));
+			}
+		}
+		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 {}
+		};
+		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 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;
+	};
+	return { protectServer };
+}
+//#endregion
+export { APPROVAL_META_KEY, createPermDock, subjectFromMcp };

package/dist/nest/index.d.ts

@@ -0,0 +1,75 @@
+import { C as Policy, Nr as Principal, ln as PermDock } from "../policy-CFZAr_Al.js";
+import { f as Permission } from "../permissions-DttnqqxC.js";
+import { n as RevocationFeed } from "../revocations-Cy06JNx2.js";
+import { A as ConnectionOptions, O as Connection, h as InvalidSignatureError, i as ProtectOptions, n as OpenApiHooks, w as verifyWebBotAuth, x as discoverViaSignatureAgent } from "../create-BWyx3jua.js";
+import { t as ServerAdapterOptions } from "../bind-CVy3Espv.js";
+import { i as sendResponse, t as NodeRequest } from "../http-DPuDaChb.js";
+import { CanActivate, DynamicModule, ExceptionFilter, ExecutionContext, Type } from "@nestjs/common";
+//#region src/nest/http.d.ts
+/**
+ * `@nestjs/platform-express` hands the guard an `IncomingMessage`;
+ * `@nestjs/platform-fastify` hands it a `FastifyRequest` whose stream is `raw`.
+ */
+export declare function toRequest(req: NodeRequest): Request;
+//#endregion
+//#region src/nest/create.d.ts
+type NestRequest = NodeRequest & {
+  readonly params?: Readonly<Record<string, string>>;
+  permdock?: PermDock;
+  permdockData?: unknown;
+};
+type NestPermDockOptions<TUser = unknown> = ServerAdapterOptions<NestRequest, TUser> & {
+  /**
+   * Maps a `ws`, `rpc` or `graphql` context to the request its subject comes
+   * from. Without it, a protected handler outside HTTP is denied.
+   */
+  readonly request?: (context: ExecutionContext) => NestRequest | undefined;
+  /** Ends or revalidates open gateway connections. */
+  readonly revocations?: RevocationFeed;
+};
+/** A gateway client: Socket.IO (`emit`, `disconnect`) or `ws` (`close`). */
+type NestSocket = {
+  emit?(event: string, payload: unknown): unknown;
+  disconnect?(close?: boolean): unknown;
+  close?(code?: number, reason?: string): unknown;
+};
+/** `Protect(null, loadData?, { oauthScopes })` needs a principal and one of the OAuth scopes, but no permission. */
+type NestProtect = (permission: Permission | null, loadData?: (req: NestRequest) => unknown, protectOptions?: ProtectOptions) => ClassDecorator & MethodDecorator;
+type NestHandlerOptions = {
+  /** Controller path; may hold route params such as `:org`. Default `api/permdock`. */
+  readonly path?: string;
+};
+type PermDockModuleOptions = {
+  /** `"global"` registers `PermDockGuard` as `APP_GUARD`, so every `Protect` rule runs without `UseGuards`. */
+  readonly guard?: "global";
+};
+type NestPermDock = {
+  readonly PermDockModule: Type<unknown> & {
+    readonly forRoot: (options?: PermDockModuleOptions) => DynamicModule;
+  };
+  readonly PermDockGuard: Type<CanActivate>;
+  readonly Protect: NestProtect;
+  readonly InjectPermDock: () => ParameterDecorator;
+  readonly PermDockExceptionFilter: Type<ExceptionFilter>;
+  readonly permdockHandler: (options?: NestHandlerOptions) => Type<unknown>;
+  /**
+   * Opens the connection for a gateway client in `handleConnection`, from the
+   * handshake request. `Protect` rules on that client's messages then decide
+   * against the connection's current instance.
+   */
+  readonly connection: (client: NestSocket, req: NestRequest, connectionOptions?: ConnectionOptions) => Promise<Connection>;
+  readonly openapi: OpenApiHooks;
+};
+export declare function createPermDock<TUser, TPrincipal extends Principal = Principal>(policy: Policy<TUser, TPrincipal>, options: NestPermDockOptions<TUser>): NestPermDock;
+//#endregion
+//#region src/nest/decorate.d.ts
+/**
+ * Applies method decorators to `cls.prototype[key]` without decorator syntax,
+ * for projects limited to erasable TypeScript. Decorators apply in the order
+ * given; each sees the descriptor the previous one left.
+ */
+export declare function decorateMethod(cls: {
+  readonly prototype: object;
+}, key: string, ...decorators: readonly MethodDecorator[]): void;
+//#endregion
+export { InvalidSignatureError, type NestHandlerOptions, type NestPermDock, type NestPermDockOptions, type NestProtect, type NestRequest, type NestSocket, type PermDockModuleOptions, discoverViaSignatureAgent, sendResponse, verifyWebBotAuth };