permdock 0.3.1 → 0.5.0

package/dist/{rls-migrate-CN4TlJTO.js → migrate-BShP7Vf4.js}

@@ -1,15 +1,24 @@
-import { i as describeError } from "./errors-CWfoNg9N.js";
-import { a as sqlFiles } from "./files-DWUN9PzI.js";
-import { i as quoteSqlLiteral, n as escapeSqlIdent } from "./sql-xdg5f4Fi.js";
-import "./sources-4p0-4xQm.js";
-import { r as HELPERS } from "./rls-shared-Cewd_-zI.js";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { r as isRecord } from "./compact-CAf557ZB.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 { 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-CD11nBbC.js";
+import { o as sqlStatements } from "./deciding-columns-Sq12mEA6.js";
+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
+//#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) {
@@ -24,14 +33,12 @@ 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 isNode(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function child(node, key) {
-	return isNode(node) ? node[key] : void 0;
+	return isRecord(node) ? node[key] : void 0;
 }
 function list(value) {
 	return Array.isArray(value) ? value : [];
@@ -171,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);
@@ -185,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;
@@ -259,9 +282,9 @@ async function migrateSql(file, text, config, target) {
 			for (const item of node) visit(item, inPolicy);
 			return;
 		}
-		if (!isNode(node)) return;
+		if (!isRecord(node)) return;
 		for (const [kind, value] of Object.entries(node)) {
-			if (kind === "FuncCall" && isNode(value)) {
+			if (kind === "FuncCall" && isRecord(value)) {
 				const call = rewriter.call(value);
 				if (call !== void 0) {
 					const source = call.end === -1 ? call.name : text.slice(call.start, call.end);
@@ -305,7 +328,7 @@ async function migrateSql(file, text, config, target) {
 		const statement = child(raw, "stmt");
 		const offset = child(raw, "stmt_location");
 		const statementStart = at(typeof offset === "number" ? offset : 0);
-		const kind = isNode(statement) ? Object.keys(statement)[0] : void 0;
+		const kind = isRecord(statement) ? Object.keys(statement)[0] : void 0;
 		if (kind !== void 0 && BODY_STATEMENTS.has(kind)) {
 			for (const body of bodyStrings(child(statement, kind))) {
 				const bodyStart = text.indexOf(body, statementStart);
@@ -329,11 +352,17 @@ async function migrateSql(file, text, config, target) {
 		text: out
 	};
 }
+function describeRetire(plan) {
+	return plan.tables.flatMap((table) => {
+		if (!table.present) return [`retire ${table.table}: no longer created by --sql`];
+		return [`retire ${table.table}: ${String(table.refreshTriggers.length)} refresh trigger(s), ${String(table.refreshFunctions.length)} refresh function(s), ${String(table.readers.length)} reader(s)${table.readers.length === 0 ? "; --retire-out drops it" : ""}`, ...table.readers.map((reader) => `  read by ${reader.kind} ${reader.name} at ${reader.file}:${String(reader.line)}`)];
+	});
+}
 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. */
@@ -346,21 +375,91 @@ async function runRlsMigrate(input) {
 	const files = sqlFiles(root, ["."]);
 	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
+		});
+	}
+	if (input.retireOut !== void 0 && input.config.tables === void 0) return {
+		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 report = {
+	const retire = input.config.tables === void 0 ? void 0 : retirePlan(statements, input.config);
+	const report = retire === void 0 ? {
 		rewrites,
 		skipped
+	} : {
+		rewrites,
+		skipped,
+		retire
+	};
+	const unknown = skipped.some((item) => item.reason === "unknown-key");
+	const output = input.json ? JSON.stringify(report, void 0, 2) : [describe(report, input.write), ...retire === void 0 ? [] : describeRetire(retire)].join("\n");
+	if (input.retireOut === void 0 || retire === void 0) return {
+		code: unknown ? 1 : 0,
+		output
+	};
+	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, dryRun) {
+	const read = plan.tables.filter((table) => table.present && table.readers.length > 0);
+	if (read.length > 0) return {
+		code: 1,
+		output: `rls migrate --retire-out: ${read.map((table) => table.table).join(", ")} still read; nothing written`
+	};
+	const text = retireSql(plan);
+	if (text === void 0) return {
+		code: 0,
+		output: "rls migrate --retire-out: nothing to retire"
+	};
+	const file = dataMigrationFile({
+		cwd,
+		out,
+		part: "retire",
+		marker: RETIRE_MARKER,
+		text,
+		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: skipped.some((item) => item.reason === "unknown-key") ? 1 : 0,
-		output: input.json ? JSON.stringify(report, void 0, 2) : describe(report, input.write)
+		code: 0,
+		output: written.printed === "" ? `wrote ${written.wrote.join(", ")}` : written.printed
 	};
 }
 //#endregion

package/dist/nest/index.d.ts

@@ -1,9 +1,10 @@
-import { C as Policy, Nr as Principal, ln as PermDock } from "../policy-IB6yxpC3.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-B1d519XK.js";
-import { t as ServerAdapterOptions } from "../bind-C_ob3LKa.js";
-import { i as sendResponse, t as NodeRequest } from "../http-DPuDaChb.js";
+import { T as Policy, rr as Principal } from "../policy-types-DzwivBgR.js";
+import { w as Permission } from "../vocabulary-D6lPdb4Z.js";
+import { r as PermDock } from "../permdock-D7eeLJER.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-BLd4MnBX.js";
+import { t as ServerAdapterOptions } from "../bind--9EFVYWF.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,11 +1,12 @@
-import { t as compact } from "../compact-y6vfu2_f.js";
-import { n as PermDockValidationError } from "../validation-error-CnjZ4t92.js";
-import { n as PermDockDeniedError, r as PermDockRevokedError, t as PermDockApprovalRequiredError } from "../errors-Cz5zn0mW.js";
-import { i as discoverViaSignatureAgent, r as InvalidSignatureError, s as verifyWebBotAuth } from "../evaluations-tz6D9A2G.js";
-import { t as problemFromError } from "../map-error-pgUWNNtG.js";
-import { a as socketConnection, r as bindKernel } from "../bind-CuzGytRf.js";
-import { i as onRevoked, t as POLICY_VIOLATION } from "../stream-DDpvynSB.js";
-import { i as toRequest$1, n as isServerResponse, r as sendResponse } from "../http-BIhmLfCc.js";
+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-BKy0EfhN.js";
+import { c as writeReply, r as hasCredentials } from "../http-BBoKefeS.js";
+import { d as discoverViaSignatureAgent, m as webBotAuthVerifier, u as InvalidSignatureError } from "../evaluations-DZ2CbV5k.js";
+import { t as problemFromError } from "../map-error-TCAdw-eW.js";
+import { a as socketConnection, r as bindKernel } from "../bind-CZzhx-Vj.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
@@ -47,9 +48,7 @@ async function sendNestResponse(res, response) {
 		return;
 	}
 	if (isFastifyReply(res)) {
-		res.code(response.status);
-		for (const [key, value] of response.headers.entries()) res.header(key, value);
-		await res.send(await response.text());
+		await writeReply(res, response);
 		return;
 	}
 	throw new TypeError("permdock/nest supports @nestjs/platform-express and @nestjs/platform-fastify responses");
@@ -97,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) => {
@@ -111,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;
@@ -127,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;
 	});
@@ -137,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);
 		}
 	};
@@ -159,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;
 		}
@@ -174,7 +173,7 @@ function createPermDock(policy, options) {
 	class PermDockExceptionFilter {
 		send = sendNestResponse;
 		async catch(exception, host) {
-			const problem = exception instanceof PermDockHttpError ? exception.response : problemFromError(exception, { credentials: host.getType() === "http" && host.switchToHttp().getRequest().headers.authorization !== void 0 });
+			const problem = exception instanceof PermDockHttpError ? exception.response : problemFromError(exception, { credentials: host.getType() === "http" && hasCredentials(host.switchToHttp().getRequest()) });
 			if (problem === void 0) throw new TypeError("unhandled permdock exception");
 			if (host.getType() === "http") {
 				await this.send(host.switchToHttp().getResponse(), problem);
@@ -247,6 +246,7 @@ function createPermDock(policy, options) {
 		return EvaluationsController;
 	};
 	return {
+		getPermDock,
 		PermDockModule: PermDockRoot,
 		PermDockGuard,
 		Protect,
@@ -258,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,19 +1,25 @@
-import { C as Policy, D as PolicyVocabulary, Nr as Principal, Tt as Snapshot, Yn as Decision, ln as PermDock } from "../policy-IB6yxpC3.js";
-import { f as Permission } from "../permissions-DttnqqxC.js";
-import { f as ApprovalStore } from "../types-aqOHTHcp.js";
-import { t as InstanceOptions } from "../instance-options-jARdwfPN.js";
-import { o as OtelWrap } from "../types-QCuYJh4q.js";
-import { a as snapshotHeaders, i as cacheLifeFor, n as SnapshotHeaders, o as snapshotTag, r as SnapshotHeadersOptions, t as CacheLifeForOptions } from "../snapshot-cache-B-LxUahj.js";
+import { In as DenialReason, Nn as Decision, T as Policy, Vt as Snapshot, ir as Subject, j as PolicyVocabulary, rr as Principal } from "../policy-types-DzwivBgR.js";
+import { w as Permission } from "../vocabulary-D6lPdb4Z.js";
+import { r as PermDock } from "../permdock-D7eeLJER.js";
+import { m as ApprovalStore } from "../types-CCpc2Dcv.js";
+import { t as InstanceOptions } from "../instance-options-Omfd793B.js";
+import { n as PermDockWrap } from "../wrap-Bd1Tejur.js";
+import { o as OtelWrap } from "../types-BqAKcRNW.js";
+import { n as DescribeMessages } from "../describe-BZUsixiL.js";
+import { a as snapshotHeaders, i as cacheLifeFor, n as SnapshotHeaders, o as snapshotTag, r as SnapshotHeadersOptions, t as CacheLifeForOptions } from "../snapshot-cache-DqK9eDmM.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;
   /** `(permdock) => withOtel(permdock, options)` from `permdock/otel`. */
   readonly otel?: OtelWrap;
+  /** Wraps each instance after `otel`; build it with `wrapPermDock` to cover derived instances. */
+  readonly wrap?: PermDockWrap;
   /**
    * Where `PermDockProvider` sends checks the snapshot cannot answer; default `/api/permdock`.
    * `false` is snapshot-only: no `permdockHandler` route, and those checks are denied with
@@ -32,19 +38,19 @@ 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`.
+   */
+  readonly onDenied?: (decision: Decision) => never | void;
 };
 type ServerPermissionState = {
   readonly allowed: boolean;
   readonly status: "ready";
   readonly decision: Decision;
 };
-type ServerPermDockProviderProps = {
+type NextPermDockProviderProps = {
   readonly children: ReactNode;
   readonly tenant?: string;
   readonly include?: readonly (Permission | {
@@ -55,6 +61,19 @@ type ServerPermDockProviderProps = {
   readonly endpoint?: string | false;
   /** Suspends permission readers until the snapshot streams in, instead of answering `pending`. */
   readonly suspend?: boolean;
+  /**
+   * What every `<Protected>` below renders for a slot it leaves out. Nodes
+   * only: a function cannot cross from a Server Component to the client.
+   */
+  readonly defaults?: {
+    readonly pending?: ReactNode;
+    readonly denied?: ReactNode;
+    readonly approval?: ReactNode;
+  };
+  /** Localised text for `useDescribe()`; records only, for the same reason. */
+  readonly messages?: Pick<DescribeMessages, "titles" | "separator"> & {
+    readonly reasons?: Partial<Record<DenialReason, string>>;
+  };
 };
 type PermDockHandler = {
   readonly POST: (request: Request) => Promise<Response>;
@@ -75,19 +94,20 @@ type NextPermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
    */
   readonly getSnapshot: (query?: GetSnapshotQuery) => Promise<Snapshot>;
   /**
-   * Resolves to the granted `Decision`. A denial calls `unauthorized()` for an
-   * anonymous subject and `forbidden()` otherwise (`experimental.authInterrupts`);
+   * Resolves to the granted `Decision`. A denial first runs `onDenied` (the
+   * call's, else the factory's), then calls `unauthorized()` for an anonymous
+   * 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 };

package/dist/next/index.js

@@ -1,8 +1,9 @@
-import { t as compact } from "../compact-y6vfu2_f.js";
-import { t as createPermDock$1 } from "../permdock-CbgvLnuo.js";
-import { n as snapshotHeaders, r as snapshotTag, t as cacheLifeFor } from "../snapshot-cache-D6jLelln.js";
-import { c as NO_GRANT, n as createEvaluationsHandler } from "../evaluations-tz6D9A2G.js";
-import { t as instanceOptions } from "../instance-options-Dhhcnm3y.js";
+import { t as compact } from "../compact-CAf557ZB.js";
+import { c as withApp } from "../permdock-B9JxkBwC.js";
+import { n as wrapPermDock } from "../wrap-gX61EtpB.js";
+import { n as snapshotHeaders, r as snapshotTag, t as cacheLifeFor } from "../snapshot-cache-DZHQ0KF6.js";
+import { n as resolveOrNull, t as buildInstance } from "../build-instance-BMnAudHn.js";
+import { o as evaluationsHandler, v as NO_GRANT } from "../evaluations-DZ2CbV5k.js";
 import { cache } from "react";
 import { jsx } from "react/jsx-runtime";
 import { forbidden, unauthorized, unstable_rethrow } from "#next/navigation";
@@ -16,7 +17,9 @@ function renderClientProvider(options) {
 			snapshotPromise: options.snapshotPromise,
 			endpoint: options.endpoint,
 			tenant: options.tenant,
-			suspend: options.suspend
+			suspend: options.suspend,
+			defaults: options.defaults,
+			messages: options.messages
 		}),
 		children: options.children
 	});
@@ -65,44 +68,35 @@ function afterResponse(sink) {
 }
 function wrapInstance(permdock, onDenied) {
 	if (onDenied === void 0) return permdock;
-	const wrap = (next) => wrapInstance(next, onDenied);
-	const assert = ((permission, data, options) => permdock.assert(permission, data, compact({
+	return wrapPermDock(permdock, (inner) => ({ assert: ((permission, data, options) => inner.assert(permission, data, compact({
 		...options,
 		onDenied: options?.onDenied ?? onDenied
-	})));
-	return Object.freeze({
-		...permdock,
-		assert,
-		tenant: (id) => wrap(permdock.tenant(id)),
-		team: (id) => wrap(permdock.team(id)),
-		derive: (options) => {
-			const derived = permdock.derive(options);
-			return derived instanceof Promise ? derived.then(wrap) : wrap(derived);
-		}
-	});
+	}))) }));
 }
-function createPermDock(policy, options) {
+function createPermDock(policy, given) {
+	const options = withApp(policy, given);
 	assertServerOnly();
 	const sink = options.sink === void 0 ? void 0 : afterResponse(options.sink);
-	const resolveSubject = cache(async () => {
-		try {
-			return await options.subject();
-		} catch (error) {
-			unstable_rethrow(error);
-			return null;
-		}
-	});
+	const resolveSubject = cache(() => resolveOrNull(() => options.subject(), unstable_rethrow));
+	const decorate = (permdock) => {
+		const traced = options.otel === void 0 ? permdock : options.otel(permdock);
+		return wrapInstance(options.wrap === void 0 ? traced : options.wrap(traced), options.onDenied);
+	};
 	const resolveFallbackTenant = cache(() => readTenant(options.tenant));
 	const instantiate = cache(async (tenantKey) => {
 		const tenant = tenantKey === "" ? void 0 : tenantKey;
 		const user = await resolveSubject();
 		await io();
-		const built = await createPermDock$1(policy, user, compact({
-			tenant,
-			...instanceOptions(options),
-			sink
-		}));
-		return wrapInstance(options.otel === void 0 ? built : options.otel(built), options.onDenied);
+		return (await buildInstance({
+			policy,
+			user,
+			sources: options,
+			scope: {
+				tenant,
+				sink
+			},
+			wrap: decorate
+		})).permdock;
 	});
 	const getPermDock = async (query) => {
 		const tenant = query?.tenant ?? await resolveFallbackTenant();
@@ -140,10 +134,12 @@ function createPermDock(policy, options) {
 		}
 		return snapshot;
 	};
-	const requireAccess = async (input) => {
-		const permdock = await getPermDock(input.tenant === void 0 ? void 0 : { tenant: input.tenant });
+	const requirePermission = async (permission, data, requirement = {}) => {
+		const permdock = await getPermDock(requirement.tenant === void 0 ? void 0 : { tenant: requirement.tenant });
 		const assert = permdock.assert;
-		return assert(input.permission, input.data, { onDenied: (decision) => {
+		const handler = requirement.onDenied ?? options.onDenied;
+		return assert(permission, data, { onDenied: (decision) => {
+			handler?.(decision);
 			if (decision.outcome !== "denied" || decision.denials.some((denial) => denial.reason === "validation")) return;
 			if (permdock.subject.principal === null) unauthorized();
 			forbidden();
@@ -159,10 +155,12 @@ function createPermDock(policy, options) {
 			endpoint: props.endpoint ?? options.endpoint ?? "/api/permdock",
 			tenant: props.tenant,
 			suspend: props.suspend,
+			defaults: props.defaults,
+			messages: props.messages,
 			children: props.children
 		}));
 	};
-	const permdockHandler = () => createEvaluationsHandler(compact({
+	const permdockHandler = () => evaluationsHandler(compact({
 		policy,
 		getPermDock,
 		store: options.store
@@ -171,7 +169,7 @@ function createPermDock(policy, options) {
 		getPermDock,
 		getPermission,
 		getSnapshot,
-		requireAccess,
+		requirePermission,
 		PermDockProvider,
 		permdockHandler
 	};

package/dist/next/plugin.d.ts

@@ -1,4 +1,4 @@
-import { a as PermDockPluginOptions } from "../types-DbjRN55U.js";
+import { a as PermDockPluginOptions } from "../types-5Ut_pbKy.js";
 //#region src/cli/plugin.d.ts
 /** Any object: Next's `NextConfig` is an interface, so no index signature. */
 type NextConfigLike = object;

package/dist/next/plugin.js

@@ -1,5 +1,5 @@
-import { i as describeError } from "../errors-CWfoNg9N.js";
-import { n as createCollectScheduler, r as report, t as collectOnce } from "../watch-DVBJ9cBq.js";
+import { a as describeError } from "../errors-CWTY6uih.js";
+import { n as createCollectScheduler, r as report, t as collectOnce } from "../watch-CszoTJMq.js";
 //#region src/cli/plugin.ts
 const PHASE_BUILD = "phase-production-build";
 const PHASE_DEV = "phase-development-server";