permdock 0.3.0 → 0.4.0

package/dist/{context-Bcy85rGi.js → context-DieZVJXu.js}

@@ -1,10 +1,11 @@
-import { t as compact } from "./compact-y6vfu2_f.js";
-import { i as isPromiseLike } from "./store-options-ByhZq1jV.js";
-import { n as switchTenant, t as providerStore } from "./provider-store-Cfbvo4DE.js";
+import { t as compact } from "./compact-CAf557ZB.js";
+import { i as isPromiseLike } from "./store-options-CbUHDoSe.js";
+import { n as switchTenant, t as providerStore } from "./provider-store-Ctt-81Ni.js";
 import { getContext, onDestroy, setContext } from "svelte";
 import { toStore } from "svelte/store";
 //#region src/svelte/context.ts
 const permDockKey = Symbol("permdock");
+const permDockUiKey = Symbol("permdock-ui");
 function isReadable(value) {
 	return typeof value === "object" && value !== null && "subscribe" in value && typeof value.subscribe === "function";
 }
@@ -32,7 +33,10 @@ function connectSvelteStore(options) {
 		snapshotUrl: options.snapshotUrl,
 		approvals: options.approvals,
 		tenant: typeof tenant === "function" ? tenant() : tenant,
-		maxAge: options.maxAge
+		maxAge: options.maxAge,
+		onSnapshot: options.onSnapshot,
+		onClear: options.onClear,
+		approvalInterval: options.approvalInterval
 	}), () => ({
 		headers: typeof headers === "function" ? headers() : headers,
 		fetch: options.fetch,
@@ -71,12 +75,19 @@ function providePermDock(options) {
 		store.dispose();
 	});
 	setContext(permDockKey, store);
+	setContext(permDockUiKey, {
+		defaults: options.defaults,
+		messages: options.messages
+	});
 	return store;
 }
+function getUi() {
+	return getContext(permDockUiKey) ?? {};
+}
 function getStore() {
 	const store = getContext(permDockKey);
 	if (store === void 0) throw new Error("PermDock: stores require setPermDock.");
 	return store;
 }
 //#endregion
-export { providePermDock as n, getStore as t };
+export { getUi as n, providePermDock as r, getStore as t };

package/dist/convex/index.d.ts

@@ -1,7 +1,7 @@
-import { C as Policy, D as PolicyVocabulary, Nr as Principal, ln as PermDock } from "../policy-IB6yxpC3.js";
-import { f as Permission } from "../permissions-DttnqqxC.js";
-import { a as ProblemDetails, r as PermDockDeniedError } from "../errors-DPdqI50v.js";
-import { t as InstanceOptions } from "../instance-options-jARdwfPN.js";
+import { E as Policy, Or as Principal, j as PolicyVocabulary, jt as PermDock } from "../policy-types-sp9P1iIV.js";
+import { d as Permission } from "../permission-types-Dg39z9Kv.js";
+import { a as ProblemDetails, r as PermDockDeniedError } from "../errors-OD_4c__H.js";
+import { t as InstanceOptions } from "../instance-options-plkrsAog.js";
 //#region src/convex/types.d.ts
 type ConvexCtxLike = {
   readonly auth?: {

package/dist/convex/index.js

@@ -1,8 +1,7 @@
-import { t as compact } from "../compact-y6vfu2_f.js";
-import { n as PermDockValidationError } from "../validation-error-CnjZ4t92.js";
-import { n as PermDockDeniedError, t as PermDockApprovalRequiredError } from "../errors-Cz5zn0mW.js";
-import { t as createPermDock$1 } from "../permdock-CbgvLnuo.js";
-import { t as instanceOptions } from "../instance-options-Dhhcnm3y.js";
+import { t as compact } from "../compact-CAf557ZB.js";
+import { n as PermDockValidationError } from "../validation-error-ZfUHbKvf.js";
+import { n as PermDockDeniedError, t as PermDockApprovalRequiredError } from "../errors-drnfxYtm.js";
+import { n as resolveOrNull, t as buildInstance } from "../build-instance-DIIV9DbC.js";
 import { n as tenantScope, t as actorFrom } from "../adapter-context-mlWsVGGg.js";
 //#region src/convex/create.ts
 /** Convex's runtime sends `data` to the client only for an error carrying this symbol. */
@@ -23,17 +22,16 @@ function toConvexError(error) {
 function createPermDock(policy, options) {
 	const withPermDock = (handler) => {
 		return async (ctx, args) => {
-			let user = null;
-			try {
-				user = await options.subject(ctx);
-			} catch {
-				user = null;
-			}
-			const permdock = await createPermDock$1(policy, user, compact({
-				tenant: (await tenantScope(options.tenant, ctx)).tenant,
-				...instanceOptions(options),
-				actor: await actorFrom(options.actor, ctx)
-			}));
+			const user = await resolveOrNull(() => options.subject(ctx));
+			const { permdock } = await buildInstance({
+				policy,
+				user,
+				sources: options,
+				scope: {
+					tenant: (await tenantScope(options.tenant, ctx)).tenant,
+					actor: await actorFrom(options.actor, ctx)
+				}
+			});
 			const next = {
 				...ctx,
 				permdock

package/dist/create-BBO24vj6.js

@@ -0,0 +1,324 @@
+import { t as compact } from "./compact-CAf557ZB.js";
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+import { n as problemDetails } from "./problem-details-DECUnXAn.js";
+import { c as listPermissions } from "./permission-registry-BsblpB-z.js";
+import { r as challengeScope } from "./permdock-L26udHSk.js";
+import { n as resourceRef } from "./resource-ref-CaS9yVPi.js";
+import { r as hasCredentials } from "./http-BBoKefeS.js";
+import { i as decisionResponse, o as notFoundProblem, s as problemFromDecision, t as ANONYMOUS, u as unauthenticatedProblem } from "./problem-CnWraVhC.js";
+import { n as resolveOrNull } from "./build-instance-DIIV9DbC.js";
+import { n as createEvaluationsHandler, r as InvalidSignatureError, t as applyApprovalResume } from "./evaluations-C9YJsv3H.js";
+import { n as tenantScope, t as actorFrom } from "./adapter-context-mlWsVGGg.js";
+import { n as requestContext, t as buildReportingInstance } from "./request-context-BVM7aWNs.js";
+//#region src/server/kernel-problems.ts
+const NOT_DELEGATED = freezeDeep({
+	outcome: "denied",
+	denials: [{
+		role: null,
+		reason: "not-delegated"
+	}],
+	alternatives: []
+});
+const LOAD_FAILED = freezeDeep({
+	outcome: "denied",
+	denials: [{
+		role: null,
+		reason: "validation"
+	}],
+	alternatives: []
+});
+/** The `403` for a loader that threw: the check fails closed, as on MCP. */
+function loadFailedProblem(permission) {
+	const key = permission?.key ?? "the route";
+	return decisionResponse(problemDetails(compact({
+		decision: LOAD_FAILED,
+		detail: `${key} failed closed: the row could not be loaded`,
+		permission: permission?.key
+	})), LOAD_FAILED);
+}
+/** The `403` `insufficient_scope` for a token that holds none of a route's OAuth scopes. */
+function scopeProblem(permission, subject, credentials, scope) {
+	return permission === null ? decisionResponse(problemDetails(compact({
+		decision: NOT_DELEGATED,
+		detail: `the token holds none of the OAuth scopes this route needs, such as ${String(scope)}`,
+		scope
+	})), NOT_DELEGATED, compact({
+		credentials,
+		scope
+	})) : problemFromDecision(NOT_DELEGATED, permission, subject, compact({
+		credentials,
+		scope
+	}));
+}
+function problemFor(decision, init, approval) {
+	if (init?.permission !== void 0) return problemFromDecision(decision, init.permission, void 0, compact({
+		instance: init.instance,
+		approval
+	}));
+	if (decision.outcome === "granted") return new Response(null, { status: 204 });
+	return decisionResponse(problemDetails(compact({
+		decision,
+		detail: decision.outcome,
+		instance: init?.instance
+	})), decision);
+}
+//#endregion
+//#region src/server/route-guard.ts
+function routeScopes(value) {
+	if (value === void 0) return;
+	const scopes = Array.isArray(value) ? value : [];
+	const names = scopes.filter((scope) => typeof scope === "string" && scope !== "");
+	if (names.length === 0 || names.length !== scopes.length) throw new TypeError("PermDock: oauthScopes must be a non-empty list of scope names");
+	return names;
+}
+async function refused(hook, fallback, decision, request, report) {
+	if (hook === void 0) return {
+		ok: false,
+		response: fallback,
+		decision
+	};
+	try {
+		const result = await hook({
+			decision,
+			problem: await fallback.clone().json(),
+			request
+		});
+		if (result === void 0) return {
+			ok: false,
+			response: fallback,
+			decision
+		};
+		const status = result.status;
+		if (typeof status !== "number" || status < 300) throw new TypeError(`PermDock: onDenied returned status ${String(status)}; a refusal keeps a status of 300 or more`);
+		return {
+			ok: false,
+			response: result instanceof Response ? result : new Response(JSON.stringify(result), {
+				status,
+				headers: fallback.headers
+			}),
+			decision
+		};
+	} catch (error) {
+		report(error);
+		return {
+			ok: false,
+			response: fallback,
+			decision
+		};
+	}
+}
+async function guardOn(deps, instance, remote, report, request, permission, load, protectOptions) {
+	const declared = routeScopes(protectOptions.oauthScopes ?? (request === void 0 ? void 0 : deps.options.operations?.oauthScopesForRequest(request.method, new URL(request.url).pathname)));
+	const credentials = request === void 0 ? false : hasCredentials(request);
+	if (permission === null) {
+		if (declared === void 0) throw new TypeError(request === void 0 ? "PermDock: protect(null) needs oauthScopes" : `PermDock: protect(null) needs oauthScopes, and no operation declares them for ${request.method} ${new URL(request.url).pathname}`);
+		if (instance.subject.principal === null) return refused(deps.options.onDenied, unauthenticatedProblem(credentials), ANONYMOUS, request, report);
+	}
+	const { actor, delegation } = instance.subject;
+	const held = permission === null && (actor !== void 0 || delegation !== void 0) ? delegation?.scopes ?? [] : delegation?.scopes;
+	if (declared !== void 0 && held !== void 0 && !declared.some((granted) => held.includes(granted))) return refused(deps.options.onDenied, scopeProblem(permission, instance.subject, credentials, declared[0]), NOT_DELEGATED, request, report);
+	let data;
+	if (load !== void 0) {
+		let loaded;
+		try {
+			loaded = await load();
+		} catch (error) {
+			report(error);
+			return refused(deps.options.onDenied, loadFailedProblem(permission), LOAD_FAILED, request, report);
+		}
+		if (loaded === null || loaded === void 0) return {
+			ok: false,
+			response: notFoundProblem()
+		};
+		data = loaded;
+	}
+	if (permission === null) return {
+		ok: true,
+		permdock: instance,
+		data
+	};
+	const decideOptions = compact({
+		source: "adapter",
+		adapter: deps.adapter,
+		field: protectOptions.field,
+		explain: protectOptions.explain,
+		...protectOptions.trusted === true ? { trusted: true } : {
+			trusted: false,
+			boundary: "http-body"
+		}
+	});
+	const raw = remote === void 0 ? instance.decide(permission, data, decideOptions) : await remote.decide(permission, data, decideOptions).catch(() => ({
+		outcome: "denied",
+		denials: [{
+			role: null,
+			reason: "pdp-unavailable"
+		}],
+		alternatives: []
+	}));
+	const decision = await applyApprovalResume(raw, permission, instance, deps.options.store, request, resourceRef(permission, data), deps.adapter);
+	if (decision.outcome === "granted") return {
+		ok: true,
+		permdock: instance,
+		decision,
+		data
+	};
+	return refused(deps.options.onDenied, problemFromDecision(decision, permission, instance.subject, compact({
+		approval: deps.options.approval,
+		credentials,
+		scope: declared?.[0] ?? challengeScope(deps.policy, permission),
+		disclosure: data === void 0 ? void 0 : deps.policy.resources.get(permission.resource)?.disclosure
+	})), decision, request, report);
+}
+//#endregion
+//#region src/server/create.ts
+async function resolveActor(request, options) {
+	return (options.webBotAuth === void 0 ? void 0 : await options.webBotAuth(request)) ?? actorFrom(options.actor, request);
+}
+const NO_TENANT = "\0";
+function createPermDock(policy, options) {
+	return createServerKernel(policy, options);
+}
+/**
+* The kernel behind every HTTP adapter. The subject and actor are resolved
+* once per `Request`; one instance is cached per `(Request, tenant)`, so a
+* global middleware and a later tenant-scoped `protect` never share a tenant.
+*/
+function createServerKernel(policy, options) {
+	const adapter = options.adapter ?? "server";
+	const subjects = /* @__PURE__ */ new WeakMap();
+	const instances = /* @__PURE__ */ new WeakMap();
+	const freshSubject = async (request) => {
+		const actor = await resolveActor(request, options);
+		const errors = [];
+		const context = await requestContext(options.context, request, errors);
+		return {
+			user: await resolveOrNull(() => options.subject(request)),
+			actor,
+			context,
+			errors
+		};
+	};
+	const resolveSubject = (request) => {
+		const hit = subjects.get(request);
+		if (hit !== void 0) return hit;
+		const resolved = freshSubject(request);
+		subjects.set(request, resolved);
+		return resolved;
+	};
+	const reporters = /* @__PURE__ */ new WeakMap();
+	const instanceFor = async ({ user, actor, context, errors }, tenant) => {
+		const built = await buildReportingInstance({
+			policy,
+			user,
+			sources: options,
+			scope: {
+				tenant,
+				actor,
+				context
+			},
+			errors,
+			wrap: options.wrap
+		});
+		const remote = options.pdp === void 0 ? void 0 : await options.pdp(policy, user, built.options);
+		reporters.set(built.permdock, built.report);
+		return {
+			permdock: built.permdock,
+			remote,
+			report: built.report
+		};
+	};
+	const build = async (request, scope) => {
+		const { tenant } = scope ?? await tenantScope(options.tenant, request);
+		let byTenant = instances.get(request);
+		if (byTenant === void 0) {
+			byTenant = /* @__PURE__ */ new Map();
+			instances.set(request, byTenant);
+		}
+		const key = tenant ?? NO_TENANT;
+		const hit = byTenant.get(key);
+		if (hit !== void 0) return hit;
+		const built = (async () => instanceFor(await resolveSubject(request), tenant))();
+		byTenant.set(key, built);
+		return built;
+	};
+	const connection = async (request, connectionOptions = {}, scope) => {
+		const { tenant } = scope ?? await tenantScope(options.tenant, request);
+		const { openConnection } = await import("./connection-DUsczpB5.js");
+		return openConnection({
+			open: async () => (await build(request, { tenant })).permdock,
+			rebuild: async () => (await instanceFor(await freshSubject(request), tenant)).permdock,
+			tenant,
+			...options.revocations === void 0 ? {} : { feed: options.revocations },
+			adapter,
+			options: connectionOptions
+		});
+	};
+	const permdock = async (request, scope) => (await build(request, scope)).permdock;
+	const getSnapshot = async (request, query = {}) => {
+		return (await permdock(request, query.tenant === void 0 ? void 0 : { tenant: query.tenant })).snapshot(compact({
+			include: query.include,
+			tenants: query.tenants
+		}));
+	};
+	const deps = {
+		policy,
+		options,
+		adapter
+	};
+	const protectRoute = (permission, loadData, protectOptions = {}) => {
+		if (permission === null && routeScopes(protectOptions.oauthScopes) === void 0 && options.operations === void 0) throw new TypeError("PermDock: protect(null) needs oauthScopes, in its options or an operations entry");
+		return async (request, scope) => {
+			let instance;
+			let remote;
+			let report;
+			try {
+				({permdock: instance, remote, report} = await build(request, scope));
+			} catch (error) {
+				if (error instanceof InvalidSignatureError) return {
+					ok: false,
+					response: error.response
+				};
+				throw error;
+			}
+			return guardOn(deps, instance, remote, report, request, permission, loadData === void 0 ? void 0 : () => loadData(request), protectOptions);
+		};
+	};
+	const protect = protectRoute;
+	const openapi = {
+		security: (permission) => ({
+			security: [{ oauth2: [permission.scope] }],
+			"x-permdock-permissions": [permission.key]
+		}),
+		securitySchemes: () => {
+			const scopes = {};
+			for (const leaf of listPermissions(policy.permissions)) scopes[leaf.scope] = leaf.meta.title ?? leaf.key;
+			return { oauth2: {
+				type: "oauth2",
+				flows: {},
+				scopes
+			} };
+		}
+	};
+	const permdockHandler = (scope) => createEvaluationsHandler(compact({
+		policy,
+		resolve: scope === void 0 ? permdock : async (request) => permdock(request, await scope(request)),
+		store: options.store,
+		adapter
+	}));
+	return {
+		permdock,
+		getSnapshot,
+		protect,
+		protectOn: (instance, permission, load, protectOptions = {}, request) => guardOn(deps, instance, void 0, reporters.get(instance) ?? (() => void 0), request, permission, load, protectOptions),
+		connection,
+		shareSubject: (from, to) => {
+			const resolved = subjects.get(from);
+			if (resolved !== void 0 && !subjects.has(to)) subjects.set(to, resolved);
+		},
+		problem: (decision, init) => problemFor(decision, init, options.approval),
+		openapi,
+		permdockHandler
+	};
+}
+//#endregion
+export { createServerKernel as n, createPermDock as t };

package/dist/{credential-8P81ff4u.js → credential-kue0qpbm.js}

@@ -1,10 +1,10 @@
-import { n as isReadonlyArray, t as compact } from "./compact-y6vfu2_f.js";
+import { n as isReadonlyArray, t as compact } from "./compact-CAf557ZB.js";
 import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
-import { _ as listPermissions, a as formerKeys } from "./permissions-DVoF6dMt.js";
+import { s as coveredByDelegation } from "./snapshot-Dc9CHPME.js";
+import { c as listPermissions, h as formerKeys } from "./permission-registry-BsblpB-z.js";
 import { n as sha256, t as bytesToBase64Url } from "./sha256-BO0swRXL.js";
-import { t as coveredByDelegation } from "./delegation-D8pUEuce.js";
 import { t as anonymousSubject } from "./subject-C6dLxqHU.js";
-import { a as ownRecord, n as idList, r as isId } from "./capability-4qPdO9gk.js";
+import { a as ownRecord, n as idList, r as isId } from "./capability-txATtKV4.js";
 //#region src/core/credential.ts
 const MAX_NAME = 256;
 function policies(policy) {

package/dist/deciding-columns-Sq12mEA6.js

@@ -0,0 +1,123 @@
+//#region src/cli/sql/statements.ts
+function blankComments(sql) {
+	return sql.replaceAll(/--[^\n]*/gu, (comment) => " ".repeat(comment.length)).replaceAll(/\/\*[\s\S]*?\*\//gu, (comment) => comment.replaceAll(/[^\n]/gu, " "));
+}
+/** Split on `;` outside string literals and dollar-quoted bodies. */
+function sqlStatements(sql) {
+	const text = blankComments(sql);
+	const statements = [];
+	const push = (start, end) => {
+		const body = text.slice(start, end);
+		const lead = body.length - body.trimStart().length;
+		const trimmed = body.trim();
+		if (trimmed !== "") statements.push({
+			line: text.slice(0, start + lead).split("\n").length,
+			text: trimmed
+		});
+	};
+	let start = 0;
+	let index = 0;
+	while (index < text.length) {
+		const char = text[index];
+		if (char === "'") {
+			const end = text.indexOf("'", index + 1);
+			index = end === -1 ? text.length : end + 1;
+			continue;
+		}
+		if (char === "$") {
+			const tag = /^\$[A-Za-z_]*\$/u.exec(text.slice(index, index + 64));
+			if (tag !== null) {
+				const end = text.indexOf(tag[0], index + tag[0].length);
+				index = end === -1 ? text.length : end + tag[0].length;
+				continue;
+			}
+		}
+		if (char === ";") {
+			push(start, index);
+			start = index + 1;
+		}
+		index += 1;
+	}
+	push(start, text.length);
+	return statements;
+}
+/** Capture group `index` of a match, or '' when an optional group took no part. */
+function group(match, index) {
+	return match[index] ?? "";
+}
+const VIEW = /^create\s+(?:or\s+replace\s+)?view\s+(?<name>\S+?)(?:\s+with\s*\((?<options>[^)]*)\))?\s+as\b/iu;
+const PRIVILEGE = /^(?:grant|revoke)\s[\s\S]*?\son\s+(?<target>[\s\S]+?)\s+(?:to|from)\s/iu;
+const UNDIFFED_TARGET = /^(?:schema|function|procedure|routine|all\s+(?:functions|procedures|routines)\s+in\s+schema)\s/iu;
+function privilegeTable(target) {
+	return target.replace(/^table\s+/iu, "").trim();
+}
+function splitUndiffed(sql) {
+	const statements = sqlStatements(sql);
+	const views = /* @__PURE__ */ new Set();
+	const moved = [];
+	let kept = sql;
+	for (const { text } of statements) {
+		const view = VIEW.exec(text)?.groups;
+		if (view !== void 0) {
+			views.add(view["name"] ?? "");
+			if (view["options"] !== void 0) moved.push(`alter view ${view["name"] ?? ""} set (${view["options"]});`);
+			continue;
+		}
+		const target = PRIVILEGE.exec(text)?.groups?.["target"];
+		if (target !== void 0 && (UNDIFFED_TARGET.test(target) || views.has(privilegeTable(target)))) {
+			moved.push(`${text};`);
+			kept = kept.replace(`${text};\n`, "");
+		}
+	}
+	return {
+		kept,
+		moved
+	};
+}
+//#endregion
+//#region src/cli/sql/deciding-columns.ts
+/** `schema.table`, unquoted and lower case; `public` when unqualified. */
+function tableKey(name) {
+	const parts = name.split(".").map((part) => part.replaceAll("\"", ""));
+	return (parts.length === 1 ? ["public", ...parts] : parts).join(".").toLowerCase();
+}
+/**
+* The columns of each membership source's table that decide who holds which
+* membership (user, scope, id, `within`, role, `via`, expiry), and the id and
+* value columns of a table a role or user column references, keyed by
+* {@link tableKey}. A client that can write one can give itself a membership.
+*/
+function membershipColumns(config) {
+	const sources = config.supabase?.hook?.memberships ?? config.rls?.membershipSources ?? [];
+	const byTable = /* @__PURE__ */ new Map();
+	for (const source of sources) {
+		const table = tableKey(source.sql.table);
+		const columns = byTable.get(table) ?? /* @__PURE__ */ new Set();
+		for (const column of source.sql.columns) columns.add(column);
+		byTable.set(table, columns);
+		for (const through of [...source.sql.throughs, ...source.sql.userThrough === void 0 ? [] : [source.sql.userThrough]]) {
+			const keys = tableKey(through.table);
+			byTable.set(keys, /* @__PURE__ */ new Set([
+				...byTable.get(keys) ?? [],
+				through.id,
+				through.key
+			]));
+		}
+	}
+	return byTable;
+}
+/**
+* Every `schema.table.column` a claim or a membership is computed from: the
+* membership columns and the `attrs` table columns. Sorted.
+*/
+function decidingColumns(config, attrs) {
+	const entries = /* @__PURE__ */ new Set();
+	for (const [table, columns] of membershipColumns(config)) for (const column of columns) entries.add(`${table}.${column}`);
+	if (attrs?.table !== void 0) {
+		const table = tableKey(attrs.table);
+		for (const column of attrs.columns) entries.add(`${table}.${column}`);
+	}
+	return [...entries].toSorted();
+}
+//#endregion
+export { splitUndiffed as a, group as i, membershipColumns as n, sqlStatements as o, tableKey as r, decidingColumns as t };

package/dist/delegation-input-FTxMK3ji.js

@@ -0,0 +1,19 @@
+import { t as compact } from "./compact-CAf557ZB.js";
+//#region src/core/delegation-input.ts
+/**
+* RFC 9396 entries a token verifier put in `extra`, under
+* `authorizationDetails` or the claim's own `authorization_details`.
+*/
+function authorizationDetailsOf(extra) {
+	const details = extra?.["authorizationDetails"] ?? extra?.["authorization_details"];
+	return Array.isArray(details) ? details : void 0;
+}
+/** The delegation a verified token's scopes and `extra` carry. */
+function delegationFrom(scopes, extra) {
+	return compact({
+		scopes,
+		authorizationDetails: authorizationDetailsOf(extra)
+	});
+}
+//#endregion
+export { delegationFrom as t };

package/dist/denied-text-DfRk15uw.d.ts

@@ -0,0 +1,19 @@
+import { ir as Decision } from "./policy-types-sp9P1iIV.js";
+import { d as Permission } from "./permission-types-Dg39z9Kv.js";
+//#region src/agent/denied-text.d.ts
+/** What an agent adapter's `onDenied` receives: the refusal and the text PermDock wrote for it. */
+type DeniedTextEvent = {
+  readonly decision: Exclude<Decision, {
+    readonly outcome: "granted";
+  }> | null;
+  readonly permission: Permission | undefined;
+  readonly text: string;
+};
+/**
+ * Replaces the human-readable text of a refusal, and nothing else: the
+ * outcome, `isError`, the structured content and the approval token stay.
+ * `undefined` keeps PermDock's text.
+ */
+type OnDeniedText = (event: DeniedTextEvent) => string | undefined;
+//#endregion
+export { OnDeniedText as n, DeniedTextEvent as t };

package/dist/{describe-DMYiCjJV.d.ts → describe-C3ldA9os.d.ts}

@@ -1,5 +1,5 @@
-import { Qn as DeniedDecision, Yn as Decision, Zn as DenialReason } from "./policy-IB6yxpC3.js";
-import { f as Permission } from "./permissions-DttnqqxC.js";
+import { cr as DeniedDecision, ir as Decision, sr as DenialReason } from "./policy-types-sp9P1iIV.js";
+import { d as Permission } from "./permission-types-Dg39z9Kv.js";
 //#region src/core/describe.d.ts
 type DecisionDescription = {
   readonly kind: "granted" | "denied" | "approval" | "tenant" | "delegation" | "server-only" | "upgrade";
@@ -30,6 +30,15 @@ type DescribeMessages = {
 };
 type DescribeOptions = {
   readonly messages?: DescribeMessages;
+  /**
+   * The permission the decision is about. Its `meta.title` replaces the key in
+   * the `granted` and `approval` text, and is what the message functions get.
+   */
+  readonly permission?: Pick<Permission, "key"> & {
+    readonly meta?: {
+      readonly title?: string;
+    };
+  };
 };
 declare function describe(decision: Decision, options?: DescribeOptions): DecisionDescription;
 //#endregion

package/dist/{describe-B_gVZEVi.js → describe-Cgkp7eP0.js}

@@ -1,5 +1,5 @@
-import { i as flattenApprovers } from "./approvers-DT4AVyIg.js";
-import { r as requiredPlans } from "./problem-details-_AMOYz-w.js";
+import { i as flattenApprovers } from "./approvers-CqPOLD-o.js";
+import { r as requiredPlans } from "./problem-details-DECUnXAn.js";
 //#region src/core/describe.ts
 const TENANT_REASONS = /* @__PURE__ */ new Set([
 	"tenant-mismatch",
@@ -51,9 +51,10 @@ function approvalDetail(permission, labels) {
 }
 function describe(decision, options) {
 	const messages = options?.messages;
+	const labelOf = (key) => options?.permission?.key === key ? options.permission.meta?.title ?? key : key;
 	const titleOf = (kind) => messages?.titles?.[kind] ?? TITLES[kind];
 	if (decision.outcome === "granted") {
-		const { permission } = decision.matched;
+		const permission = labelOf(decision.matched.permission);
 		return {
 			kind: "granted",
 			title: titleOf("granted"),
@@ -62,7 +63,7 @@ function describe(decision, options) {
 		};
 	}
 	if (decision.outcome === "approval-required") {
-		const { permission } = decision.grant;
+		const permission = labelOf(decision.grant.permission);
 		const labels = approvers(decision.grant.approval);
 		return {
 			kind: "approval",

package/dist/{diff-DBIhz_f2.js → diff-Cnghh_Ip.js}

@@ -1,4 +1,4 @@
-import { i as globalArgs, s as stringArg, t as COMMAND_DESCRIPTIONS } from "./commands-DSxCqG9A.js";
+import { i as globalArgs, s as stringArg, t as COMMAND_DESCRIPTIONS } from "./commands-Cpip4ULx.js";
 import { defineCommand } from "citty";
 //#region src/cli/commands/diff.ts
 function diff(ctx) {
@@ -30,7 +30,7 @@ function diff(ctx) {
 			}
 		},
 		async run({ args: parsed }) {
-			const result = await (await import("./diff-2VaeChzX.js")).runDiff({
+			const result = await (await import("./diff-rpqoe7Ag.js")).runDiff({
 				cwd: ctx.cwd,
 				config: ctx.config,
 				sources: parsed._,