permdock 0.3.1 → 0.5.0

package/dist/{kernel-_RRHmnMY.js → kernel-5JatXyND.js}

@@ -1,12 +1,28 @@
-import { t as compact } from "./compact-y6vfu2_f.js";
-import { t as describe } from "./describe-B_gVZEVi.js";
-import { a as deniedMessage } from "./errors-Cz5zn0mW.js";
-import { t as createPermDock } from "./permdock-CbgvLnuo.js";
+import { t as compact } from "./compact-CAf557ZB.js";
+import { t as describe } from "./describe-BybMRY7A.js";
+import { a as deniedMessage } from "./errors-BKy0EfhN.js";
+import { t as actorMayCallTool } from "./delegation-DaXVdDhM.js";
 import { n as resourceRef } from "./resource-ref-CaS9yVPi.js";
-import { t as mayUse } from "./may-use-DndQ5tQ-.js";
-import { l as storedApprovalToken, s as resumeDecision } from "./helpers-H_KARDVC.js";
-import { t as instanceOptions } from "./instance-options-Dhhcnm3y.js";
-import { n as tenantScope, t as actorFrom } from "./adapter-context-mlWsVGGg.js";
+import { c as withApp } from "./permdock-B9JxkBwC.js";
+import { l as storedApprovalToken, s as resumeDecision } from "./helpers-DTcZOzhF.js";
+import { n as resolveOrNull } from "./build-instance-BMnAudHn.js";
+import { n as tenantScope, t as actorFrom } from "./adapter-context-CRhqyzCk.js";
+import { n as requestContext, t as buildReportingInstance } from "./request-context-BTRTG7OT.js";
+//#region src/agent/denied-text.ts
+/** The hook's text, or `event.text` when there is no hook or it throws or returns no string. */
+function refusalText(hook, event, report) {
+	if (hook === void 0) return event.text;
+	try {
+		const text = hook(event);
+		if (text === void 0) return event.text;
+		if (typeof text !== "string" || text === "") throw new TypeError("PermDock: deniedText must return a non-empty string or undefined");
+		return text;
+	} catch (error) {
+		report(error);
+		return event.text;
+	}
+}
+//#endregion
 //#region src/agent/reason.ts
 function modelReason(decision, permission, subjectId) {
 	if (decision.outcome === "denied") return deniedMessage(permission?.key ?? "unknown", subjectId, decision.denials, decision.alternatives.map((leaf) => leaf.key));
@@ -29,35 +45,43 @@ function approvalTokenOf(context) {
 function runDecide(permdock, permission, data, how) {
 	return permdock.decide(permission, data, how);
 }
-function createAgentKernel(policy, options) {
+function createAgentKernel(policy, given) {
+	const options = withApp(policy, given);
 	const cache = /* @__PURE__ */ new WeakMap();
+	const reporters = /* @__PURE__ */ new WeakMap();
+	const report = (permdock, error) => {
+		if (permdock !== void 0) reporters.get(permdock)?.(error);
+	};
 	const instance = (context) => {
 		if (typeof context === "object" && context !== null) {
 			const hit = cache.get(context);
 			if (hit !== void 0) return hit;
 		}
 		const built = (async () => {
-			let user = null;
-			try {
-				user = await options.subject(context);
-			} catch {
-				user = null;
-			}
+			const user = await resolveOrNull(() => options.subject(context));
 			const actor = await actorFrom(options.actor, context);
-			let delegation;
-			if (options.delegation !== void 0) try {
-				delegation = await options.delegation(context);
-			} catch {
-				delegation = void 0;
-			}
+			const delegate = options.delegation;
+			const delegation = delegate === void 0 ? void 0 : await resolveOrNull(() => delegate(context)) ?? void 0;
 			const { tenant } = await tenantScope(options.tenant, context);
-			const created = await createPermDock(policy, user, compact({
-				tenant,
-				actor,
-				delegation,
-				...instanceOptions(options)
-			}));
-			return options.wrap?.(created) ?? created;
+			const errors = [];
+			const requestValues = await requestContext(options.context, context, errors);
+			const wrap = options.wrap;
+			const typedWrap = (created) => wrap === void 0 ? created : wrap(created);
+			const { permdock, report: reportTo } = await buildReportingInstance({
+				policy,
+				user,
+				sources: options,
+				scope: {
+					tenant,
+					actor,
+					delegation,
+					context: requestValues
+				},
+				errors,
+				wrap: typedWrap
+			});
+			reporters.set(permdock, reportTo);
+			return permdock;
 		})();
 		if (typeof context === "object" && context !== null) {
 			cache.set(context, built);
@@ -74,6 +98,23 @@ function createAgentKernel(policy, options) {
 		let permdock;
 		try {
 			permdock = await instance(context);
+			if (how.tool !== void 0 && !actorMayCallTool(permdock.subject.actor, how.tool)) {
+				const refused = {
+					outcome: "denied",
+					denials: [{
+						role: null,
+						reason: "agent-tool-not-delegated"
+					}],
+					alternatives: []
+				};
+				return {
+					ok: true,
+					permdock,
+					data: void 0,
+					raw: refused,
+					decision: refused
+				};
+			}
 			let data;
 			if (binding.data !== void 0) {
 				try {
@@ -91,11 +132,16 @@ function createAgentKernel(policy, options) {
 					permdock
 				};
 			}
-			const raw = runDecide(permdock, binding.permission, data, {
+			const raw = runDecide(permdock, binding.permission, data, compact({
 				adapter: options.adapter,
 				boundary,
-				source: how.source
-			});
+				call: how.call,
+				args,
+				operation: binding.meta === void 0 ? void 0 : {
+					name: binding.name ?? "",
+					meta: binding.meta
+				}
+			}));
 			const decision = how.resume ? await resumeDecision({
 				decision: raw,
 				permission: binding.permission,
@@ -120,13 +166,13 @@ function createAgentKernel(policy, options) {
 			});
 		}
 	};
-	const check = (binding, args, context, checkOptions = {}) => run(binding, args, context, {
+	const check = (binding, args, context, checkOptions = {}) => run(binding, args, context, compact({
 		resume: checkOptions.simulate !== true,
-		source: checkOptions.simulate === true ? "simulate" : "adapter",
-		decideOptions: checkOptions
-	});
-	const evaluate = async (binding, toolName, args, context, decideOptions = {}) => {
-		const checked = await check(binding, args, context, decideOptions);
+		call: checkOptions.simulate === true ? "simulate" : "adapter",
+		decideOptions: checkOptions,
+		tool: checkOptions.tool
+	}));
+	const verdictOf = (checked, binding, toolName) => {
 		if (!checked.ok) {
 			if (checked.failure !== "no-data" || checked.permdock === void 0) return {
 				outcome: "denied",
@@ -171,28 +217,58 @@ function createAgentKernel(policy, options) {
 			reason: modelReason(decision, binding.permission, permdock.subject.principal?.id)
 		};
 	};
+	const evaluate = async (binding, toolName, args, context, decideOptions = {}) => {
+		const checked = await check(binding, args, context, {
+			...decideOptions,
+			tool: toolName
+		});
+		return relabel(verdictOf(checked, binding, toolName), checked.permdock);
+	};
+	const relabel = (verdict, permdock) => {
+		const hook = options.deniedText;
+		if (hook === void 0 || verdict.outcome === "granted") return verdict;
+		const onError = (error) => {
+			report(permdock, error);
+		};
+		if (verdict.outcome === "denied") return {
+			...verdict,
+			reason: refusalText(hook, {
+				decision: verdict.decision,
+				permission: verdict.permission,
+				text: verdict.reason
+			}, onError)
+		};
+		return {
+			...verdict,
+			summary: refusalText(hook, {
+				decision: verdict.decision,
+				permission: verdict.permission,
+				text: verdict.summary
+			}, onError)
+		};
+	};
 	const tokenFor = async (binding, args, context) => {
 		const checked = await run(binding, args, context, {
 			resume: false,
-			source: "adapter",
+			call: "adapter",
 			decideOptions: {}
 		});
 		return checked.ok && checked.raw.outcome === "approval-required" ? checked.raw.token : void 0;
 	};
 	const decideTool = (toolName, args, context, decideOptions = {}) => {
 		const binding = Object.hasOwn(tools, toolName) ? tools[toolName] : void 0;
-		if (binding === void 0) return Promise.resolve({
+		if (binding === void 0) return Promise.resolve(relabel({
 			outcome: "denied",
 			decision: null,
 			permission: void 0,
 			reason: unmappedReason(toolName)
-		});
+		}, void 0));
 		return evaluate(binding, toolName, args, context, decideOptions);
 	};
 	const allowedToolNames = async (context) => {
 		const permdock = await instance(context);
 		const allowed = /* @__PURE__ */ new Set();
-		for (const [name, binding] of Object.entries(tools)) if (mayUse(permdock, binding.permission)) allowed.add(name);
+		for (const [name, binding] of Object.entries(tools)) if (actorMayCallTool(permdock.subject.actor, name) && permdock.mayUse(binding.permission)) allowed.add(name);
 		return allowed;
 	};
 	return {
@@ -201,8 +277,9 @@ function createAgentKernel(policy, options) {
 		evaluate,
 		check,
 		tokenFor,
-		allowedToolNames
+		allowedToolNames,
+		report
 	};
 }
 //#endregion
-export { createAgentKernel as n, approvalTokenOf as t };
+export { createAgentKernel as n, refusalText as r, approvalTokenOf as t };

package/dist/kysely/index.d.ts

@@ -1,6 +1,7 @@
-import { Ir as Condition, Pr as Subject, mn as WhereResult } from "../policy-IB6yxpC3.js";
+import { Rt as Instant, ir as Subject, lr as Condition } from "../policy-types-DzwivBgR.js";
+import { c as WhereResult } from "../permdock-D7eeLJER.js";
 import { r as RelationsMapping } from "../graph-sql-B-dsAT6j.js";
-import { s as MembershipsMapping } from "../compile-BkRyBDBw.js";
+import { s as MembershipsMapping } from "../compile-Ckm2HqBZ.js";
 import { n as WithSubjectOptions, t as RowCheck } from "../row-check-Dt35czLy.js";
 //#region src/kysely/types.d.ts
 type KyselySelectQuery = {
@@ -33,7 +34,8 @@ type KyselyWhereOptions = {
   readonly memberships?: MembershipsMapping;
   /** Where the relation graph lives; graph grants compile to Postgres subqueries with it and are refused without. */
   readonly relations?: RelationsMapping;
-  readonly now?: number;
+  /** The clock membership expiry is read at; a `Temporal.Instant` fits. Defaults to the current time. */
+  readonly now?: Instant;
   /** Kysely's `sql` tag, for graph subqueries on runtimes without `require`; loaded from the `kysely` peer by default. */
   readonly sql?: KyselySql;
 };

package/dist/kysely/index.js

@@ -1,7 +1,7 @@
-import { t as compact } from "../compact-y6vfu2_f.js";
-import { w as assertSafeKey } from "../permissions-DVoF6dMt.js";
-import { n as escapeLike, t as compileWhere } from "../compile-Ba4blROR.js";
-import { i as rowCheckFrom, r as subjectStatements, t as statementTemplate } from "../subject-settings-BwBmCdTR.js";
+import { t as compact } from "../compact-CAf557ZB.js";
+import { t as assertSafeKey } from "../paths-DXSHAMIa.js";
+import { n as escapeLike, t as compileWhere } from "../compile-CMqMx_IN.js";
+import { a as rowCheckFrom, i as templateOf, r as subjectStatements, s as loadPeer, t as statementTemplate } from "../subject-settings-CkEwrw3W.js";
 //#region src/kysely/to-where.ts
 function ident(name) {
 	assertSafeKey(name, "sql identifier");
@@ -34,13 +34,7 @@ function containsExpr(eb, column, field, value, options) {
 }
 function loadSql(injected) {
 	if (injected !== void 0) return injected;
-	const loader = globalThis.process?.getBuiltinModule?.("node:module");
-	try {
-		if (loader === void 0) throw new Error("no module loader");
-		return loader.createRequire(import.meta.url)("kysely").sql;
-	} catch {
-		throw new Error("PermDock: graph grants and withSubject in permdock/kysely need the kysely peer; pass `sql` on runtimes without require");
-	}
+	return loadPeer("kysely", "PermDock: graph grants and withSubject in permdock/kysely need the kysely peer; pass `sql` on runtimes without require").sql;
 }
 function graphExpr(node, table, options) {
 	const sql = loadSql(options.sql);
@@ -54,9 +48,7 @@ function graphExpr(node, table, options) {
 		values.push("column" in part ? sql.ref(col(table, part.column, options.columns)) : "subject" in part ? node.subject : part.value);
 		strings.push("");
 	}
-	const template = strings;
-	Object.defineProperty(template, "raw", { value: strings });
-	return sql(template, ...values);
+	return sql(templateOf(strings), ...values);
 }
 function render(eb, node, table, options) {
 	switch (node.kind) {

package/dist/{live-options-H2eG8dfJ.js → live-options-BaAFCIiu.js}

@@ -1,6 +1,7 @@
 import { createContext, useLayoutEffect, useRef, useState } from "react";
 //#region src/react/context.ts
 const PermDockStoreContext = createContext(null);
+const PermDockUiContext = createContext({});
 const PermDockSnapshotPromiseContext = createContext(null);
 //#endregion
 //#region src/react/keyed.ts
@@ -34,7 +35,8 @@ function sameHeaders(a, b) {
 * Store options whose identity survives a re-render, so an inline `headers`
 * object or `fetch` arrow does not rebuild the store and drop its snapshot.
 * `headers` compare by value, unless `headersByValue` is `false` for a store
-* that only reads `readHeaders`; `fetch` and `verifier` call the latest prop.
+* that only reads `readHeaders`; `fetch`, `verifier`, `onSnapshot` and
+* `onClear` call the latest prop.
 */
 function useLiveOptions(props, headersByValue = true) {
 	const latest = useRef(props);
@@ -49,12 +51,23 @@ function useLiveOptions(props, headersByValue = true) {
 		const verifier = latest.current.verifier;
 		return verifier === void 0 ? Promise.reject(/* @__PURE__ */ new Error("PermDock: the verifier prop was removed.")) : verifier.verify(token, expectations);
 	} }));
+	const [liveOnSnapshot] = useState(() => {
+		const call = (snapshot, tenant, raw) => {
+			latest.current.onSnapshot?.(snapshot, tenant, raw);
+		};
+		return call;
+	});
+	const [liveOnClear] = useState(() => () => {
+		latest.current.onClear?.();
+	});
 	return {
 		headers,
 		readHeaders,
 		fetch: liveFetch,
-		verifier: props.verifier === void 0 ? void 0 : liveVerifier
+		verifier: props.verifier === void 0 ? void 0 : liveVerifier,
+		onSnapshot: props.onSnapshot === void 0 ? void 0 : liveOnSnapshot,
+		onClear: props.onClear === void 0 ? void 0 : liveOnClear
 	};
 }
 //#endregion
-export { PermDockStoreContext as i, useKeyed as n, PermDockSnapshotPromiseContext as r, useLiveOptions as t };
+export { PermDockUiContext as a, PermDockStoreContext as i, useKeyed as n, PermDockSnapshotPromiseContext as r, useLiveOptions as t };

package/dist/load-BxEtwlBS.js

@@ -0,0 +1 @@
+export { a as loadModule, s as pickNamed } from "./load-DFS_ry0W.js";

package/dist/{load-DhWEB9P1.js → load-DFS_ry0W.js}

@@ -1,8 +1,16 @@
-import { _ as listPermissions } from "./permissions-DVoF6dMt.js";
+import { c as listPermissions } from "./permission-registry-Br4jSNVi.js";
+import { a as describeError, n as CliError } from "./errors-CWTY6uih.js";
 import { dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createJiti } from "jiti";
-//#region src/cli/load.ts
+//#region src/cli/project/load.ts
+/** A project module the CLI cannot use: the project's to fix, so a usage error. */
+function invalidModule(message, cause) {
+	return new CliError("usage", message, {
+		code: "config_invalid",
+		...cause === void 0 ? {} : { cause }
+	});
+}
 /**
 * Errors Node raises while resolving or parsing a module graph, before any of
 * its code runs, so loading it again through jiti cannot repeat a side effect.
@@ -36,6 +44,14 @@ function importWithJiti(abs, fresh) {
 * returned as written; `default` is not merged into the namespace.
 */
 async function loadModule(abs, options) {
+	try {
+		return await importModule(abs, options);
+	} catch (error) {
+		if (error instanceof CliError) throw error;
+		throw invalidModule(describeError(error), error);
+	}
+}
+async function importModule(abs, options) {
 	let loaded;
 	if (options?.fresh === true) loaded = await importWithJiti(abs, true);
 	else try {
@@ -44,7 +60,7 @@ async function loadModule(abs, options) {
 		if (!loadsWithJiti(error)) throw error;
 		loaded = await importWithJiti(abs, false);
 	}
-	if (loaded === null || typeof loaded !== "object") throw new Error(`PermDock CLI: module '${abs}' did not export an object`);
+	if (loaded === null || typeof loaded !== "object") throw invalidModule(`PermDock CLI: module '${abs}' did not export an object`);
 	return loaded;
 }
 function pickNamed(mod, names) {
@@ -52,24 +68,32 @@ function pickNamed(mod, names) {
 	return mod["default"];
 }
 function asPermissionTree(value) {
-	if (value === null || typeof value !== "object") throw new Error("PermDock CLI: permissions export is not a permission tree");
+	if (value === null || typeof value !== "object") throw invalidModule("PermDock CLI: permissions export is not a permission tree");
 	return value;
 }
 function asPolicy(value) {
-	if (value === null || typeof value !== "object" || !("roles" in value) || !("permissions" in value)) throw new Error("PermDock CLI: policy export is not a Policy");
+	if (value === null || typeof value !== "object" || !("roles" in value) || !("permissions" in value)) throw invalidModule("PermDock CLI: policy export is not a Policy");
 	return value;
 }
 function leavesOf(tree) {
 	return listPermissions(tree);
 }
+/** The `policy` export of the module at `path`. */
+async function loadPolicyAt(cwd, path, options) {
+	return asPolicy(pickNamed(await loadModule(resolve(cwd, path), options), ["policy"]));
+}
+/** The `policy` export at `path`; without one, throws `PermDock CLI: <missing>`. */
+function requirePolicy(cwd, path, missing) {
+	return path === void 0 ? Promise.reject(new CliError("usage", `PermDock CLI: ${missing}`, { code: "config_invalid" })) : loadPolicyAt(cwd, path);
+}
 /** The configured policy export, or `undefined` when unset or unloadable. */
 async function loadConfiguredPolicy(cwd, path, options) {
 	if (path === void 0) return;
 	try {
-		return asPolicy(pickNamed(await loadModule(resolve(cwd, path), options), ["policy"]));
+		return await loadPolicyAt(cwd, path, options);
 	} catch {
 		return;
 	}
 }
 //#endregion
-export { loadModule as a, loadConfiguredPolicy as i, asPolicy as n, pickNamed as o, leavesOf as r, asPermissionTree as t };
+export { loadModule as a, requirePolicy as c, loadConfiguredPolicy as i, asPolicy as n, loadPolicyAt as o, leavesOf as r, pickNamed as s, asPermissionTree as t };

package/dist/{load-jose-BL6LH4bL.js → load-jose-DZ4dnjri.js}

@@ -1,11 +1,8 @@
 //#region src/jwt/load-jose.ts
-let cached;
 function loadJose() {
-	cached ??= import("jose").catch((cause) => {
-		cached = void 0;
+	return import("jose").catch((cause) => {
 		throw new Error("PermDock: permdock/jwt requires the optional peer \"jose\".", { cause });
 	});
-	return cached;
 }
 //#endregion
 export { loadJose as t };

package/dist/login-Dfe5RlYk.js

@@ -0,0 +1,68 @@
+import { t as defineLeaf } from "./command-L8EstFNm.js";
+import { c as given } from "./flags-C3DktBDY.js";
+//#region src/cli/commands/login.ts
+const urlFlag = { url: {
+	type: "string",
+	description: "Issuer URL (default PERMDOCK_CLOUD_URL, then https://permdock.com/api)",
+	valueHint: "url"
+} };
+const login = defineLeaf({
+	flags: {
+		...urlFlag,
+		loopback: {
+			type: "boolean",
+			description: "Use a 127.0.0.1 redirect with PKCE instead of the device flow"
+		},
+		scope: {
+			type: "enum",
+			options: ["catalog:write"],
+			repeatable: true,
+			description: "Scopes beyond projects:read and policy:read; catalog:write for permdock cloud push"
+		},
+		open: {
+			type: "boolean",
+			default: true,
+			description: "Open the browser at the verification URL",
+			negativeDescription: "Print the URL only"
+		}
+	},
+	async run(ctx, { flags }) {
+		const { runLogin } = await import("./login-imhuwvn3.js");
+		return runLogin({
+			cwd: ctx.cwd,
+			url: given(flags.url),
+			loopback: flags.loopback,
+			scopes: flags.scope,
+			open: flags.open && ctx.interactive,
+			json: ctx.json,
+			env: ctx.env,
+			io: ctx.io
+		});
+	}
+});
+const logout = defineLeaf({
+	flags: { ...urlFlag },
+	async run(ctx, { flags }) {
+		const { runLogout } = await import("./login-imhuwvn3.js");
+		return runLogout({
+			url: given(flags.url),
+			json: ctx.json,
+			env: ctx.env,
+			io: ctx.io
+		});
+	}
+});
+const whoami = defineLeaf({
+	flags: { ...urlFlag },
+	async run(ctx, { flags }) {
+		const { runWhoami } = await import("./login-imhuwvn3.js");
+		return runWhoami({
+			url: given(flags.url),
+			json: ctx.json,
+			env: ctx.env,
+			io: ctx.io
+		});
+	}
+});
+//#endregion
+export { login, logout, whoami };