permdock 0.4.0 → 0.6.0

package/dist/mcp/index.js

@@ -1,21 +1,21 @@
 import { r as isRecord, t as compact } from "../compact-CAf557ZB.js";
 import { n as freezeDeep } from "../freeze-CrU8nQeX.js";
-import { i as stepUpOf } from "../problem-details-DECUnXAn.js";
-import { t as describe } from "../describe-Cgkp7eP0.js";
-import { m as annotationsFor } from "../permission-registry-BsblpB-z.js";
-import { a as scopesReaching, i as hasScope, r as challengeScope } from "../permdock-L26udHSk.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-j6-rc37o.js";
 import { n as resourceRef } from "../resource-ref-CaS9yVPi.js";
-import { t as anonymousSubject } from "../subject-C6dLxqHU.js";
-import { t as composeWraps } from "../wrap-DWsU_5Bd.js";
-import { t as mayUse } from "../may-use-BOn_dR_w.js";
-import { l as protectedResourceMetadataUrl, r as bearerChallenge } from "../problem-CnWraVhC.js";
+import { a as hasScope, c as withApp, i as challengeScope, o as scopesReaching } from "../permdock-BrAscV28.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-AVlBaJoa.js";
-import { r as instanceOptions } from "../build-instance-DIIV9DbC.js";
-import { n as createAgentKernel, r as deniedText } from "../kernel-CB3LrIJM.js";
+import { n as mapClaimsToSubject } from "../map-claims-D3oRmTk0.js";
+import { r as instanceOptions } from "../build-instance-Bu_eDqYw.js";
+import { n as createAgentKernel, r as refusalText } from "../kernel-D0NVb1cK.js";
 import { t as boundedMap } from "../lru-8q4WZjBV.js";
 import { t as delegationFrom } from "../delegation-input-FTxMK3ji.js";
-import { n as deniedToolRefusal, r as toolErrorResult, t as approvalToolRefusal } from "../tool-refusal-CQ7OEia9.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";
@@ -234,8 +234,11 @@ function credentialRefusal(checks, permission, reach, authInfo) {
 	}));
 }
 /** 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, call, permission, approved) {
-	const rechecked = await checks.kernel.check(binding, void 0, call, { simulate: true });
+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)
@@ -250,7 +253,7 @@ async function recheck(checks, binding, call, permission, approved) {
 		} : plainRefusal(permission, `Denied: ${permission.key} was revoked before the call completed.`, {})
 	};
 }
-async function decideCall(checks, permission, reach, load, context, handlerContext, capabilities, completion) {
+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 {
@@ -262,8 +265,11 @@ async function decideCall(checks, permission, reach, load, context, handlerConte
 		data: load === void 0 ? void 0 : () => load()
 	});
 	const call = compact({ authInfo });
-	if (completion !== void 0) return recheck(checks, binding, call, permission, completion.approved);
-	const checked = await checks.kernel.check(binding, void 0, call, compact({ resumeToken: approvalTokenOf(context) }));
+	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)
@@ -301,17 +307,17 @@ async function decideCall(checks, permission, reach, load, context, handlerConte
 		default: return decision;
 	}
 }
-/** `decideCall` with the refusal text replaced by `onDenied`'s. */
-async function checkCall(checks, permission, reach, load, context, handlerContext, capabilities, completion) {
-	const checked = await decideCall(checks, permission, reach, load, context, handlerContext, capabilities, completion);
-	const { onDenied } = checks.options;
-	if (checked.ok || onDenied === void 0) return checked;
+/** `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: deniedText(onDenied, {
+			text: refusalText(deniedText, {
 				decision: refusal.decision ?? null,
 				permission,
 				text: refusal.text
@@ -321,8 +327,11 @@ async function checkCall(checks, permission, reach, load, context, handlerContex
 		}
 	};
 }
-/** The keys a list shows: unguarded ones, and guarded ones the token reaches and the subject may use. */
-async function visible(checks, context, permissionOf, keys, declaredOf = () => void 0) {
+/**
+* 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 = [];
@@ -341,7 +350,7 @@ async function visible(checks, context, permissionOf, keys, declaredOf = () => v
 	} catch {
 		return shown;
 	}
-	for (const entry of guarded) if (mayUse(permdock, entry.permission)) shown.add(entry.key);
+	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. */
@@ -349,14 +358,16 @@ 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 args = dataArgs(params);
+		const loader = load === void 0 ? void 0 : () => load(...args);
 		const reach = extra.reach ?? reachOf(checks.policy, permission, void 0);
-		const checked = await checkCall(checks, permission, reach, loader, context, raw, extra.capabilities);
+		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 checkCall(checks, 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);
@@ -404,7 +415,7 @@ function protectServer(checks, server, enforcement) {
 		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);
+		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) ? {
@@ -445,18 +456,19 @@ function protectServer(checks, server, enforcement) {
 		const key = sessionKey(context);
 		const before = lastListed.get(key);
 		if (before === void 0) return;
-		const after = [...await visible(checks, context, toolPermission, [...tools.keys()], toolDeclared)].toSorted().join(",");
+		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 = (permission, reach, load, handler, longRunning) => guard(checks, permission, load, handler, (params) => params.length >= 2 ? [params[0]] : [void 0], toolRefusal, {
+	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
+		reach,
+		tool
 	});
 	const originalTool = server.registerTool.bind(server);
 	const toolPermissionOf = (name, config) => {
@@ -465,7 +477,7 @@ function protectServer(checks, server, enforcement) {
 		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 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;
@@ -477,6 +489,8 @@ function protectServer(checks, server, enforcement) {
 		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: {
@@ -484,11 +498,10 @@ function protectServer(checks, server, enforcement) {
 				...passthrough["annotations"]
 			},
 			scopeChallenge: challengeFor(scopeChallenge, reach.scopes, reach.challenge)
-		}, wrapTool(permission, reach, load, handler, longRunning));
+		}, wrapTool(tool, 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) => {
+		guardUpdates(registered, (callback) => wrapTool(tool, permission, reach, load, callback, longRunning), (from, to) => {
 			tools.delete(from);
 			toolScopes.delete(from);
 			if (to !== null) {
@@ -581,7 +594,8 @@ function subjectFromMcp(authInfo, options = {}) {
 }
 //#endregion
 //#region src/mcp/create.ts
-function createPermDock(policy, options) {
+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 = {
@@ -590,6 +604,7 @@ function createPermDock(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,
@@ -597,7 +612,10 @@ function createPermDock(policy, options) {
 					client: clientNameOf(options.clients, clientId)
 				}) : void 0;
 			},
-			delegation: (call) => call.authInfo === void 0 ? void 0 : delegationFrom(call.authInfo.scopes, call.authInfo.extra),
+			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",

package/dist/{migrate-BwlB5-Wk.js → migrate-CIq4-E9F.js}

@@ -1,20 +1,24 @@
 import { r as isRecord } from "./compact-CAf557ZB.js";
-import { i as describeError } from "./errors-CWfoNg9N.js";
+import { i as dateAt } from "./time-DkWjdL98.js";
+import { a as describeError } from "./errors-CWTY6uih.js";
 import { o as sqlFiles } from "./files-D_JIzUrP.js";
-import { n as escapeSqlIdent, o as quoteSqlLiteral } from "./sql-t8teWOfo.js";
-import "./sources-B1-b-R0t.js";
-import { a as RETIRE_MARKER } from "./markers-CiwAOZtO.js";
-import { r as HELPERS } from "./shared-1uhI-e-b.js";
-import { l as writeOutputFiles, t as dataMigrationFile } from "./output-files-CgIsvdSa.js";
+import { r as escapeSqlIdent, s as quoteSqlLiteral } from "./sql-B5T1IL83.js";
+import "./sources-vs5dGOsS.js";
+import { a as RETIRE_MARKER } from "./markers-C6joDI3o.js";
+import { r as refuseDirty, t as applyFiles } from "./files-C5ZI27eV.js";
+import { f as writeOutputFiles, n as dataMigrationFile } from "./output-files-DhRBBE4n.js";
+import { r as HELPERS } from "./shared-BAK8t4Uo.js";
 import { o as sqlStatements } from "./deciding-columns-Sq12mEA6.js";
-import { i as retireSql, r as retirePlan } from "./retire-BFcxL6un.js";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { i as retireSql, r as retirePlan } from "./retire-CALjIQ7e.js";
+import { existsSync, readFileSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import { parse } from "pgsql-parser";
 //#region src/cli/rls/migrate.ts
 function migrateTarget(generated) {
 	const granted = /* @__PURE__ */ new Map();
+	const roles = /* @__PURE__ */ new Set();
 	for (const row of generated.seeds ?? []) {
+		roles.add(row.role);
 		if (row.effect !== "allow") continue;
 		let keys = granted.get(row.scope);
 		if (keys === void 0) {
@@ -29,7 +33,8 @@ function migrateTarget(generated) {
 		permissions: new Set(generated.keys?.permissions ?? []),
 		rowConditions: new Set(generated.keys?.rowConditions ?? []),
 		granted,
-		renamed: generated.keys?.renamed ?? {}
+		renamed: generated.keys?.renamed ?? {},
+		roles
 	};
 }
 function child(node, key) {
@@ -173,6 +178,21 @@ var Rewriter = class {
 		const column = this.#column(idArg);
 		return "to" in column ? { to: `(${column.to} in (select ${helper}()))` } : column;
 	}
+	#role(scope, idArg, roleArgs) {
+		const name = `member_${scope}_ids`;
+		const helper = this.#helper(name);
+		if (helper === void 0 || !this.#target.sql.includes(`.${name}(p_roles text[])`)) return skip("missing-helper", `rls generate writes no ${name}(p_roles text[]): run it with this rls.migrate config, which asks for it`);
+		const legacy = roleArgs.map((arg) => stringConst(arg)).filter((role) => role !== void 0);
+		if (legacy.length === 0 || legacy.length !== roleArgs.length) return skip("dynamic-role", "a role is not a string literal; map it by hand");
+		const mapped = [];
+		for (const value of legacy) {
+			const declared = this.#target.roleValues?.[value] ?? value;
+			if (!this.#target.roles.has(declared)) return skip("unknown-role", `${value} maps to ${declared}, which no role grants; add it to rls.roleValues or declare the role`);
+			mapped.push(declared);
+		}
+		const column = this.#column(idArg);
+		return "to" in column ? { to: `(${column.to} in (select ${helper}(array[${mapped.map(literal).join(", ")}])))` } : column;
+	}
 	#scoped(args, selected) {
 		const [scopeArg, idArg, keyArg] = args;
 		const named = stringConst(scopeArg);
@@ -187,6 +207,7 @@ var Rewriter = class {
 			case "ids": return this.#ids(helper.scope, args[0]);
 			case "row": return this.#row(helper.scope, args[0], args[1]);
 			case "membership": return this.#membership(helper.scope, args[0]);
+			case "role": return this.#role(helper.scope, args[0], args.slice(1));
 			case "scoped": return this.#scoped(args, selected);
 			case "global": return this.#global(args[0], selected);
 			default: return helper;
@@ -341,7 +362,7 @@ function describe(report, write) {
 	const lines = [...report.rewrites.map((item) => `${item.file}:${String(item.line)}  ${item.from}  ->  ${item.to}`), ...report.skipped.map((item) => `skipped ${item.file}:${String(item.line)}  ${item.call}: ${item.detail}`)];
 	const files = new Set(report.rewrites.map((item) => item.file)).size;
 	const unknown = report.skipped.filter((item) => item.reason === "unknown-key").length;
-	lines.push(`rls migrate: ${write ? "rewrote" : "would rewrite"} ${String(report.rewrites.length)} call(s) in ${String(files)} file(s), skipped ${String(report.skipped.length)}${unknown === 0 ? "" : `, ${String(unknown)} with an unknown key`}${write ? "" : "; --write applies them"}`);
+	lines.push(`rls migrate: ${write ? "rewrote" : "would rewrite"} ${String(report.rewrites.length)} call(s) in ${String(files)} file(s), skipped ${String(report.skipped.length)}${unknown === 0 ? "" : `, ${String(unknown)} with an unknown key`}${write ? "" : "; drop --dry-run to apply them"}`);
 	return lines.join("\n");
 }
 /** `permdock rls migrate`: a dry run unless `write`; exits 1 while a key is unknown. */
@@ -355,13 +376,17 @@ async function runRlsMigrate(input) {
 	const rewrites = [];
 	const skipped = [];
 	const statements = [];
+	const writes = [];
 	for (const path of files) {
 		const file = relative(input.cwd, path);
 		const text = readFileSync(path, "utf8");
 		const result = await migrateSql(file, text, input.config, input.target);
 		rewrites.push(...result.rewrites);
 		skipped.push(...result.skipped);
-		if (input.write && result.text !== text) writeFileSync(path, result.text);
+		if (input.write && result.text !== text) writes.push({
+			path,
+			text: result.text
+		});
 		for (const statement of sqlStatements(input.write ? result.text : text)) statements.push({
 			file,
 			...statement
@@ -371,6 +396,16 @@ async function runRlsMigrate(input) {
 		code: 2,
 		output: "rls migrate --retire-out needs rls.migrate.tables in permdock.config.ts"
 	};
+	if (writes.length > 0) {
+		refuseDirty({
+			command: "rls migrate",
+			invocation: `rls migrate --sql ${input.sql}`,
+			cwd: input.cwd,
+			paths: writes.map((write) => write.path),
+			force: input.force === true
+		});
+		applyFiles(input.cwd, writes);
+	}
 	const retire = input.config.tables === void 0 ? void 0 : retirePlan(statements, input.config);
 	const report = retire === void 0 ? {
 		rewrites,
@@ -386,14 +421,14 @@ async function runRlsMigrate(input) {
 		code: unknown ? 1 : 0,
 		output
 	};
-	const retired = writeRetire(input.cwd, input.retireOut, retire, input.now);
+	const retired = writeRetire(input.cwd, input.retireOut, retire, input.now, !input.write);
 	return {
 		code: unknown || retired.code === 1 ? 1 : 0,
 		output: `${output}\n${retired.output}`
 	};
 }
 /** `--retire-out`: nothing is written while any listed table is still read. */
-function writeRetire(cwd, out, plan, now) {
+function writeRetire(cwd, out, plan, now, dryRun) {
 	const read = plan.tables.filter((table) => table.present && table.readers.length > 0);
 	if (read.length > 0) return {
 		code: 1,
@@ -410,13 +445,17 @@ function writeRetire(cwd, out, plan, now) {
 		part: "retire",
 		marker: RETIRE_MARKER,
 		text,
-		now: now ?? /* @__PURE__ */ new Date(),
+		now: now ?? dateAt(),
 		check: false
 	});
 	if (file === void 0) return {
 		code: 0,
 		output: "rls migrate --retire-out: up to date"
 	};
+	if (dryRun && file.rel !== "-") return {
+		code: 0,
+		output: `would write ${file.rel}`
+	};
 	const written = writeOutputFiles(cwd, [file]);
 	return {
 		code: 0,

package/dist/nest/index.d.ts

@@ -1,9 +1,10 @@
-import { E as Policy, Or as Principal, jt as PermDock } from "../policy-types-sp9P1iIV.js";
-import { d as Permission } from "../permission-types-Dg39z9Kv.js";
-import { n as RevocationFeed } from "../revocations-Cy06JNx2.js";
-import { A as ConnectionOptions, C as verifyWebBotAuth, O as Connection, b as discoverViaSignatureAgent, i as OpenApiHooks, m as InvalidSignatureError, o as ProtectOptions } from "../server-types-DdqBwZN_.js";
-import { t as ServerAdapterOptions } from "../bind-BzqG8SMb.js";
-import { i as sendResponse, t as NodeRequest } from "../http-DPuDaChb.js";
+import { T as Policy, rr as Principal } from "../policy-types-n0uRTsW8.js";
+import { w as Permission } from "../vocabulary-CN8H_9UF.js";
+import { r as PermDock } from "../permdock-SV8ZINYT.js";
+import { n as RevocationFeed } from "../revocations-R07lFBnX.js";
+import { D as ConnectionOptions, T as Connection, f as InvalidSignatureError, i as OpenApiHooks, o as ProtectOptions, v as discoverViaSignatureAgent, x as webBotAuthVerifier } from "../server-types-CKQiCnON.js";
+import { t as ServerAdapterOptions } from "../bind-DOyrv6zi.js";
+import { r as sendResponse, t as NodeRequest } from "../http-B_LphE5Y.js";
 import { CanActivate, DynamicModule, ExceptionFilter, ExecutionContext, Type } from "@nestjs/common";
 //#region src/nest/http.d.ts
 /**
@@ -33,8 +34,8 @@ type NestSocket = {
   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;
+/** `Protect(null, data?, { oauthScopes })` needs a principal and one of the OAuth scopes, but no permission. */
+type NestProtect = (permission: Permission | null, data?: (req: NestRequest) => unknown, protectOptions?: ProtectOptions) => ClassDecorator & MethodDecorator;
 type NestHandlerOptions = {
   /** Controller path; may hold route params such as `:org`. Default `api/permdock`. */
   readonly path?: string;
@@ -44,6 +45,8 @@ type PermDockModuleOptions = {
   readonly guard?: "global";
 };
 type NestPermDock = {
+  /** The `PermDock` for one request, for code the guard does not run before. */
+  readonly getPermDock: (req: NestRequest) => Promise<PermDock>;
   readonly PermDockModule: Type<unknown> & {
     readonly forRoot: (options?: PermDockModuleOptions) => DynamicModule;
   };
@@ -72,4 +75,4 @@ 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 };
+export { InvalidSignatureError, type NestHandlerOptions, type NestPermDock, type NestPermDockOptions, type NestProtect, type NestRequest, type NestSocket, type PermDockModuleOptions, discoverViaSignatureAgent, sendResponse, webBotAuthVerifier };

package/dist/nest/index.js

@@ -1,12 +1,12 @@
 import { t as compact } from "../compact-CAf557ZB.js";
 import { n as PermDockValidationError } from "../validation-error-ZfUHbKvf.js";
-import { n as PermDockDeniedError, r as PermDockRevokedError, t as PermDockApprovalRequiredError } from "../errors-drnfxYtm.js";
+import { n as PermDockDeniedError, r as PermDockRevokedError, t as PermDockApprovalRequiredError } from "../errors-BKy0EfhN.js";
 import { c as writeReply, r as hasCredentials } from "../http-BBoKefeS.js";
-import { i as discoverViaSignatureAgent, r as InvalidSignatureError, s as verifyWebBotAuth } from "../evaluations-C9YJsv3H.js";
-import { t as problemFromError } from "../map-error-BE27PYkE.js";
-import { a as socketConnection, r as bindKernel } from "../bind-kk-uyCwH.js";
-import { i as onRevoked, t as POLICY_VIOLATION } from "../stream-BMui98KK.js";
-import { i as toRequest$1, n as isServerResponse, r as sendResponse } from "../http-BEbdMZ05.js";
+import { d as discoverViaSignatureAgent, m as webBotAuthVerifier, u as InvalidSignatureError } from "../evaluations-beAooV0n.js";
+import { t as problemFromError } from "../map-error-Dr70oA_3.js";
+import { a as socketConnection, r as bindKernel } from "../bind-CAvgUuKs.js";
+import { a as onRevoked, n as closeReason, t as POLICY_VIOLATION } from "../stream-CvdUS9V1.js";
+import { n as sendResponse, r as toRequest$1, t as isServerResponse } from "../http-ujKm0JXE.js";
 import { Catch, Controller, Get, Inject, Injectable, Module, Post, Req, Res, createParamDecorator } from "@nestjs/common";
 import { APP_FILTER, APP_GUARD, Reflector } from "@nestjs/core";
 //#region src/nest/decorate.ts
@@ -96,10 +96,10 @@ function rulesOf(target) {
 	if (!Array.isArray(found)) return [];
 	return found;
 }
-const Protect = (permission, loadData, protectOptions) => {
+const Protect = (permission, data, protectOptions) => {
 	const rule = compact({
 		permission,
-		loadData,
+		data,
 		options: protectOptions
 	});
 	return ((target, _propertyKey, descriptor) => {
@@ -110,11 +110,11 @@ const Protect = (permission, loadData, protectOptions) => {
 	});
 };
 function createPermDock(policy, options) {
-	const { kernel, bind, rebind, scopeOf, handlerScope } = bindKernel(policy, options, "nest", toRequest);
+	const { kernel, bind, rebind, scopeOf, handlerScope, getPermDock } = bindKernel(policy, options, "nest", toRequest);
 	const applyProtect = async (remaining, req, request, scope, load) => {
 		const [rule, ...rest] = remaining;
 		if (rule === void 0) return;
-		const guard = await kernel.protect(rule.permission, load(rule.loadData), rule.options)(request, scope);
+		const guard = await kernel.protect(rule.permission, load(rule.data), rule.options)(request, scope);
 		if (!guard.ok) throw new PermDockHttpError(guard.response);
 		req.permdock = guard.permdock;
 		req.permdockData = guard.data;
@@ -126,7 +126,7 @@ function createPermDock(policy, options) {
 		onRevoked(conn, (problem) => {
 			client.emit?.("permdock:error", problem);
 			if (typeof client.disconnect === "function") client.disconnect(true);
-			else client.close?.(POLICY_VIOLATION, problem.type);
+			else client.close?.(POLICY_VIOLATION, closeReason(problem));
 		});
 		return conn;
 	});
@@ -136,7 +136,7 @@ function createPermDock(policy, options) {
 		const load = loadsFor(req);
 		for (const rule of rules) {
 			if (conn.signal.aborted) throw conn.signal.reason instanceof PermDockRevokedError ? conn.signal.reason : new PermDockRevokedError({ code: "denied" });
-			const guard = await kernel.protectOn(conn.permdock, rule.permission, load(rule.loadData), rule.options, request);
+			const guard = await kernel.protectOn(conn.permdock, rule.permission, load(rule.data), rule.options, request);
 			if (!guard.ok) throw new PermDockHttpError(guard.response);
 		}
 	};
@@ -158,7 +158,7 @@ function createPermDock(policy, options) {
 			if (req === void 0) return rules.length === 0;
 			const request = bind(req);
 			const scope = await scopeOf(req);
-			req.permdock = await kernel.permdock(request, scope);
+			req.permdock = await kernel.getPermDock(request, scope);
 			await applyProtect(rules, req, request, scope, loadsFor(req));
 			return true;
 		}
@@ -246,6 +246,7 @@ function createPermDock(policy, options) {
 		return EvaluationsController;
 	};
 	return {
+		getPermDock,
 		PermDockModule: PermDockRoot,
 		PermDockGuard,
 		Protect,
@@ -257,4 +258,4 @@ function createPermDock(policy, options) {
 	};
 }
 //#endregion
-export { InvalidSignatureError, createPermDock, decorateMethod, discoverViaSignatureAgent, sendResponse, toRequest, verifyWebBotAuth };
+export { InvalidSignatureError, createPermDock, decorateMethod, discoverViaSignatureAgent, sendResponse, toRequest, webBotAuthVerifier };

package/dist/next/index.d.ts

@@ -1,16 +1,18 @@
-import { E as Policy, Or as Principal, an as Snapshot, ir as Decision, j as PolicyVocabulary, jt as PermDock, sr as DenialReason } from "../policy-types-sp9P1iIV.js";
-import { d as Permission } from "../permission-types-Dg39z9Kv.js";
-import { f as ApprovalStore } from "../types-Br9IXUBG.js";
-import { t as InstanceOptions } from "../instance-options-plkrsAog.js";
-import { n as PermDockWrap } from "../wrap-Cr93qqdP.js";
-import { o as OtelWrap } from "../types-CUcFZfpU.js";
-import { n as DescribeMessages } from "../describe-C3ldA9os.js";
-import { a as snapshotHeaders, i as cacheLifeFor, n as SnapshotHeaders, o as snapshotTag, r as SnapshotHeadersOptions, t as CacheLifeForOptions } from "../snapshot-cache-J5T7t_vD.js";
+import { In as DenialReason, Nn as Decision, T as Policy, Vt as Snapshot, ar as Subject, j as PolicyVocabulary, rr as Principal } from "../policy-types-n0uRTsW8.js";
+import { w as Permission } from "../vocabulary-CN8H_9UF.js";
+import { r as PermDock } from "../permdock-SV8ZINYT.js";
+import { m as ApprovalStore } from "../types-BdtSDbBO.js";
+import { t as InstanceOptions } from "../instance-options-BsVpyGIk.js";
+import { n as PermDockWrap } from "../wrap-C5jC6sKI.js";
+import { o as OtelWrap } from "../types-lUlG3TVd.js";
+import { n as DescribeMessages } from "../describe-B5qgDvEW.js";
+import { a as snapshotHeaders, i as cacheLifeFor, n as SnapshotHeaders, o as snapshotTag, r as SnapshotHeadersOptions, t as CacheLifeForOptions } from "../snapshot-cache-PXI-vGpY.js";
 import { ReactElement, ReactNode } from "react";
 //#region src/next/types.d.ts
 type NextSubjectInput = unknown;
 type NextPermDockOptions<TUser = NextSubjectInput> = InstanceOptions & {
-  readonly subject: () => TUser | Promise<TUser>;
+  /** The user, or a full `Subject` (core then skips `policy.subject`). */
+  readonly subject: () => TUser | Subject | Promise<TUser | Subject>;
   readonly tenant?: string | (() => string | undefined | Promise<string | undefined>);
   readonly onDenied?: (decision: Decision) => never | void;
   readonly store?: ApprovalStore;
@@ -36,12 +38,7 @@ type GetSnapshotQuery = GetPermDockQuery & {
   /** Tags added next to `snapshotTag(sub)`, such as the app's own organisation tag. */
   readonly tags?: readonly string[];
 };
-type RequireAccessInput = {
-  readonly permission: Permission;
-  /** The row for an instance permission; omit it for a collection permission. */
-  readonly data?: unknown;
-  /** The active tenant, as for `getPermDock({ tenant })`; defaults to the factory's `tenant`. */
-  readonly tenant?: string;
+type PermissionRequirementOptions = GetPermDockQuery & {
   /**
    * Runs before the default interrupts; throw or redirect to replace them.
    * Defaults to the factory's `onDenied`.
@@ -53,7 +50,7 @@ type ServerPermissionState = {
   readonly status: "ready";
   readonly decision: Decision;
 };
-type ServerPermDockProviderProps = {
+type NextPermDockProviderProps = {
   readonly children: ReactNode;
   readonly tenant?: string;
   readonly include?: readonly (Permission | {
@@ -70,7 +67,7 @@ type ServerPermDockProviderProps = {
    */
   readonly defaults?: {
     readonly pending?: ReactNode;
-    readonly fallback?: ReactNode;
+    readonly denied?: ReactNode;
     readonly approval?: ReactNode;
   };
   /** Localised text for `useDescribe()`; records only, for the same reason. */
@@ -102,15 +99,15 @@ type NextPermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
    * subject and `forbidden()` otherwise (`experimental.authInterrupts`);
    * approval-required and boundary validation throw as from `assert`.
    */
-  readonly requireAccess: (input: RequireAccessInput) => Promise<Extract<Decision, {
+  readonly requirePermission: (permission: Permission, data?: unknown, options?: PermissionRequirementOptions) => Promise<Extract<Decision, {
     readonly outcome: "granted";
   }>>;
   /** Never awaits: passes an unawaited snapshot to the client provider, whose hooks suspend. */
-  readonly PermDockProvider: (props: ServerPermDockProviderProps) => ReactElement;
+  readonly PermDockProvider: (props: NextPermDockProviderProps) => ReactElement;
   readonly permdockHandler: () => PermDockHandler;
 };
 //#endregion
 //#region src/next/create.d.ts
-export declare function createPermDock<TUser = NextSubjectInput, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, options: NextPermDockOptions<TUser>): NextPermDock<V>;
+export declare function createPermDock<TUser = NextSubjectInput, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, given: NextPermDockOptions<TUser>): NextPermDock<V>;
 //#endregion
-export { type CacheLifeForOptions, type GetPermDockQuery, type GetSnapshotQuery, type NextPermDock, type NextPermDockOptions, type PermDockHandler, type RequireAccessInput, type ServerPermDockProviderProps, type ServerPermissionState, type SnapshotHeaders, type SnapshotHeadersOptions, cacheLifeFor, snapshotHeaders, snapshotTag };
+export { type CacheLifeForOptions, type GetPermDockQuery, type GetSnapshotQuery, type NextPermDock, type NextPermDockOptions, type NextPermDockProviderProps, type PermDockHandler, type PermissionRequirementOptions, type ServerPermissionState, type SnapshotHeaders, type SnapshotHeadersOptions, cacheLifeFor, snapshotHeaders, snapshotTag };