permdock 0.0.0 → 0.2.0

package/dist/kernel-GSQnMz3O.js

@@ -0,0 +1,208 @@
+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-CzqXjCpU.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";
+//#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));
+	return describe(decision).detail;
+}
+function unmappedReason(toolName) {
+	return `Denied: unmapped tool ${toolName}.`;
+}
+function thrownReason(toolName) {
+	return `Denied: ${toolName} failed closed.`;
+}
+//#endregion
+//#region src/agent/kernel.ts
+/** The resume token an agent run carries under the namespaced `permdockApproval` key. */
+function approvalTokenOf(context) {
+	if (context === null || typeof context !== "object") return;
+	const token = context.permdockApproval;
+	return typeof token === "string" && token !== "" ? token : void 0;
+}
+function runDecide(permdock, permission, data, how) {
+	return permdock.decide(permission, data, how);
+}
+function createAgentKernel(policy, options) {
+	const cache = /* @__PURE__ */ new WeakMap();
+	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 actor = await actorFrom(options.actor, context);
+			let delegation;
+			if (options.delegation !== void 0) try {
+				delegation = await options.delegation(context);
+			} catch {
+				delegation = 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;
+		})();
+		if (typeof context === "object" && context !== null) {
+			cache.set(context, built);
+			const release = () => {
+				if (cache.get(context) === built) cache.delete(context);
+			};
+			built.then(release, release);
+		}
+		return built;
+	};
+	const boundary = options.boundary ?? "tool-args";
+	const tools = options.tools ?? {};
+	const run = async (binding, args, context, how) => {
+		let permdock;
+		try {
+			permdock = await instance(context);
+			let data;
+			if (binding.data !== void 0) {
+				try {
+					data = await binding.data(args);
+				} catch {
+					return {
+						ok: false,
+						failure: "load-failed",
+						permdock
+					};
+				}
+				if (binding.permission.kind === "instance" && (data === null || data === void 0)) return {
+					ok: false,
+					failure: "no-data",
+					permdock
+				};
+			}
+			const raw = runDecide(permdock, binding.permission, data, {
+				adapter: options.adapter,
+				boundary,
+				source: how.source
+			});
+			const decision = how.resume ? await resumeDecision({
+				decision: raw,
+				permission: binding.permission,
+				subject: permdock.subject,
+				store: options.store,
+				resource: resourceRef(binding.permission, data),
+				adapter: options.adapter,
+				token: how.decideOptions.resumeToken ?? await storedApprovalToken(options.store, raw, { denyPending: how.decideOptions.denyPending === true })
+			}) : raw;
+			return {
+				ok: true,
+				permdock,
+				data,
+				raw,
+				decision
+			};
+		} catch {
+			return compact({
+				ok: false,
+				failure: "failed",
+				permdock
+			});
+		}
+	};
+	const check = (binding, args, context, checkOptions = {}) => run(binding, args, context, {
+		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);
+		if (!checked.ok) {
+			if (checked.failure !== "no-data" || checked.permdock === void 0) return {
+				outcome: "denied",
+				decision: null,
+				permission: binding.permission,
+				reason: thrownReason(toolName)
+			};
+			const decision = {
+				outcome: "denied",
+				denials: [{
+					role: null,
+					reason: "validation"
+				}],
+				alternatives: []
+			};
+			return {
+				outcome: "denied",
+				decision,
+				permission: binding.permission,
+				reason: modelReason(decision, binding.permission, checked.permdock.subject.principal?.id)
+			};
+		}
+		const { permdock, decision, data } = checked;
+		if (decision.outcome === "granted") return {
+			outcome: "granted",
+			decision,
+			permission: binding.permission,
+			data
+		};
+		if (decision.outcome === "approval-required") return {
+			outcome: "approval-required",
+			decision,
+			permission: binding.permission,
+			data,
+			token: decision.token,
+			summary: modelReason(decision, binding.permission, permdock.subject.principal?.id)
+		};
+		return {
+			outcome: "denied",
+			decision,
+			permission: binding.permission,
+			reason: modelReason(decision, binding.permission, permdock.subject.principal?.id)
+		};
+	};
+	const tokenFor = async (binding, args, context) => {
+		const checked = await run(binding, args, context, {
+			resume: false,
+			source: "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({
+			outcome: "denied",
+			decision: null,
+			permission: void 0,
+			reason: unmappedReason(toolName)
+		});
+		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);
+		return allowed;
+	};
+	return {
+		instance,
+		decideTool,
+		evaluate,
+		check,
+		tokenFor,
+		allowedToolNames
+	};
+}
+//#endregion
+export { createAgentKernel as n, approvalTokenOf as t };

package/dist/kysely/index.d.ts

@@ -0,0 +1,78 @@
+import { Ir as Condition, Pr as Subject, mn as WhereResult } from "../policy-CFZAr_Al.js";
+import { r as RelationsMapping } from "../graph-sql-B-dsAT6j.js";
+import { s as MembershipsMapping } from "../compile-CNnl6uIt.js";
+import { n as WithSubjectOptions, t as RowCheck } from "../row-check-Dt35czLy.js";
+//#region src/kysely/types.d.ts
+type KyselySelectQuery = {
+  select(expr: unknown): KyselySelectQuery;
+  where(column: string, op: string, value: unknown): KyselySelectQuery;
+  where(expression: unknown): KyselySelectQuery;
+  whereRef(left: string, op: string, right: string): KyselySelectQuery;
+};
+type KyselyExpressionBuilder = {
+  (left: unknown, op: string, right: unknown): unknown;
+  and(args: readonly unknown[]): unknown;
+  or(args: readonly unknown[]): unknown;
+  not(value: unknown): unknown;
+  lit(value: unknown): unknown;
+  val(value: unknown): unknown;
+  ref(column: string): unknown;
+  exists?(query: unknown): unknown;
+  selectFrom?(table: string): KyselySelectQuery;
+};
+/** Kysely's `sql` tag; `import { sql } from 'kysely'`. */
+type KyselySql = {
+  (strings: TemplateStringsArray, ...values: unknown[]): unknown;
+  ref(reference: string): unknown;
+};
+type KyselyWhereOptions = {
+  readonly columns?: Readonly<Record<string, string>>;
+  /** Condition fields that are Postgres arrays; `contains` on them is `@>`. */
+  readonly listFields?: readonly string[];
+  readonly subject?: Subject;
+  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;
+  /** Kysely's `sql` tag, for graph subqueries on runtimes without `require`; loaded from the `kysely` peer by default. */
+  readonly sql?: KyselySql;
+};
+type KyselyWithSubjectOptions = WithSubjectOptions & {
+  /** Kysely's `sql` tag, on runtimes without `require`; loaded from the `kysely` peer by default. */
+  readonly sql?: KyselySql;
+};
+//#endregion
+//#region src/kysely/to-where.d.ts
+export declare function toWhere(input: Condition | WhereResult, table: string, options?: KyselyWhereOptions): (eb: KyselyExpressionBuilder) => unknown;
+type KyselyLike<Trx> = {
+  transaction(): {
+    execute<T>(fn: (trx: Trx) => Promise<T>): Promise<T>;
+  };
+};
+/**
+ * Runs `fn` in a transaction whose role and claims are `permdock.subject`'s, so the generated
+ * RLS policies decide for the same subject as the in-process checks.
+ */
+export declare function withSubject<Trx, T>(db: KyselyLike<Trx>, permdock: {
+  readonly subject: Subject;
+}, fn: (trx: Trx) => Promise<T>, options?: KyselyWithSubjectOptions): Promise<T>;
+type KyselySelectable = {
+  selectFrom(table: never): {
+    select(selection: (eb: never) => unknown): {
+      where(where: never): {
+        limit(count: number): {
+          execute(): Promise<readonly {
+            readonly granted?: unknown;
+          }[]>;
+        };
+      };
+    };
+  };
+};
+/**
+ * One query for one row: `{ found: false }` when `key` matches nothing, otherwise whether the
+ * permission filter keeps the row. Throws when `key` matches more than one row.
+ */
+export declare function checkRow(db: KyselySelectable, table: string, input: Condition | WhereResult, key: (eb: KyselyExpressionBuilder) => unknown, options?: KyselyWhereOptions): Promise<RowCheck>;
+//#endregion
+export type { KyselyExpressionBuilder, KyselySql, KyselyWhereOptions, KyselyWithSubjectOptions, MembershipsMapping, RelationsMapping, RowCheck, WithSubjectOptions };

package/dist/kysely/index.js

@@ -0,0 +1,129 @@
+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";
+//#region src/kysely/to-where.ts
+function ident(name) {
+	assertSafeKey(name, "sql identifier");
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(name)) throw new Error(`PermDock: unsafe SQL identifier '${name}'`);
+	return name;
+}
+function col(table, field, columns) {
+	assertSafeKey(field, "condition field");
+	return `${ident(table)}.${ident(columns?.[field] ?? field)}`;
+}
+function existsExpr(eb, node, table, options) {
+	if (eb.exists === void 0 || eb.selectFrom === void 0) return eb.lit(false);
+	const m = (name) => `m.${ident(name)}`;
+	let query = eb.selectFrom(`${ident(node.table)} as m`).select(eb.lit(1)).whereRef(m(node.rowColumn), "=", col(table, node.rowField, options.columns)).where(m(node.user), "=", eb.val(node.userValue));
+	if (node.roles.length > 0) query = query.where(m(node.role), "in", node.roles);
+	if (node.expiresAt !== void 0) {
+		const expires = eb.ref(m(node.expiresAt));
+		query = query.where(eb.or([eb(expires, "is", null), eb(expires, ">", eb.val(node.now))]));
+	}
+	if (node.tenantColumn !== void 0 && node.tenantValue !== void 0) {
+		const tenant = eb.ref(m(node.tenantColumn));
+		query = query.where(eb.or([eb(tenant, "is", null), eb(tenant, "=", eb.val(node.tenantValue))]));
+	}
+	if (node.resourceColumn !== void 0 && node.resourceValue !== void 0) query = query.where(m(node.resourceColumn), "=", eb.val(node.resourceValue));
+	return eb.exists(query);
+}
+function containsExpr(eb, column, field, value, options) {
+	if (options.listFields?.includes(field) === true) return eb(column, "@>", eb.val([value]));
+	return typeof value === "string" ? eb(column, "like", eb.val(`%${escapeLike(value)}%`)) : eb(column, "@>", eb.val(value));
+}
+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");
+	}
+}
+function graphExpr(node, table, options) {
+	const sql = loadSql(options.sql);
+	const strings = [""];
+	const values = [];
+	for (const part of node.parts) {
+		if ("text" in part) {
+			strings[strings.length - 1] += part.text;
+			continue;
+		}
+		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);
+}
+function render(eb, node, table, options) {
+	switch (node.kind) {
+		case "never": return eb.lit(false);
+		case "always": return eb.lit(true);
+		case "isNull": {
+			const column = eb.ref(col(table, node.field, options.columns));
+			return node.negated ? eb(column, "is not", null) : eb(column, "is", null);
+		}
+		case "and": return eb.and(node.items.map((item) => render(eb, item, table, options)));
+		case "or": return eb.or(node.items.map((item) => render(eb, item, table, options)));
+		case "not": return eb.not(render(eb, node.item, table, options));
+		case "exists": return existsExpr(eb, node, table, options);
+		case "sql": return graphExpr(node, table, options);
+		case "compare": {
+			const column = eb.ref(col(table, node.field, options.columns));
+			switch (node.op) {
+				case "eq": return eb(column, "=", eb.val(node.value));
+				case "ne": return eb(column, "!=", eb.val(node.value));
+				case "gt": return eb(column, ">", eb.val(node.value));
+				case "gte": return eb(column, ">=", eb.val(node.value));
+				case "lt": return eb(column, "<", eb.val(node.value));
+				case "lte": return eb(column, "<=", eb.val(node.value));
+				case "in": return eb(column, "in", node.value);
+				case "notIn": return eb(column, "not in", node.value);
+				case "contains": return containsExpr(eb, column, node.field, node.value, options);
+				/* v8 ignore next 4 */
+				default: {
+					const exhaustive = node.op;
+					throw new Error(`PermDock: unknown compare '${String(exhaustive)}'`);
+				}
+			}
+		}
+		/* v8 ignore next 6 */
+		default: throw new Error(`PermDock: unknown compiled node '${String(node)}'`);
+	}
+}
+function toWhere(input, table, options = {}) {
+	const compiled = compileWhere(input, compact({
+		subject: options.subject,
+		memberships: options.memberships,
+		now: options.now,
+		relations: options.relations
+	}));
+	return (eb) => render(eb, compiled, table, options);
+}
+/**
+* Runs `fn` in a transaction whose role and claims are `permdock.subject`'s, so the generated
+* RLS policies decide for the same subject as the in-process checks.
+*/
+function withSubject(db, permdock, fn, options = {}) {
+	const statements = subjectStatements(permdock, options);
+	const sql = loadSql(options.sql);
+	return db.transaction().execute(async (trx) => {
+		for (const statement of statements) await sql(statementTemplate(statement), ...statement.values).execute(trx);
+		return fn(trx);
+	});
+}
+/**
+* One query for one row: `{ found: false }` when `key` matches nothing, otherwise whether the
+* permission filter keeps the row. Throws when `key` matches more than one row.
+*/
+async function checkRow(db, table, input, key, options = {}) {
+	const sql = loadSql(options.sql);
+	const filter = toWhere(input, table, options);
+	const rows = await db.selectFrom(table).select(((eb) => sql`coalesce(${filter(eb)}, false)`.as("granted"))).where(key).limit(2).execute();
+	return rowCheckFrom(rows);
+}
+//#endregion
+export { checkRow, toWhere, withSubject };

package/dist/live-options-H2eG8dfJ.js

@@ -0,0 +1,60 @@
+import { createContext, useLayoutEffect, useRef, useState } from "react";
+//#region src/react/context.ts
+const PermDockStoreContext = createContext(null);
+const PermDockSnapshotPromiseContext = createContext(null);
+//#endregion
+//#region src/react/keyed.ts
+/**
+* `create()` once per distinct `inputs`, held in state: React may drop a
+* `useMemo` value and rebuild it, and a rebuilt store loses its answers,
+* polls and followed snapshot.
+*/
+function useKeyed(create, inputs) {
+	const [held, setHeld] = useState(() => ({
+		inputs,
+		value: create()
+	}));
+	if (held.inputs.length === inputs.length && held.inputs.every((input, index) => Object.is(input, inputs[index]))) return held.value;
+	const next = {
+		inputs,
+		value: create()
+	};
+	setHeld(next);
+	return next.value;
+}
+//#endregion
+//#region src/react/live-options.ts
+function sameHeaders(a, b) {
+	if (a === b) return true;
+	if (a === void 0 || b === void 0) return false;
+	const keys = Object.keys(a);
+	return keys.length === Object.keys(b).length && keys.every((key) => Object.hasOwn(b, key) && a[key] === b[key]);
+}
+/**
+* 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.
+*/
+function useLiveOptions(props, headersByValue = true) {
+	const latest = useRef(props);
+	useLayoutEffect(() => {
+		latest.current = props;
+	});
+	const [headers, setHeaders] = useState(props.headers);
+	if (headersByValue && !sameHeaders(headers, props.headers)) setHeaders(props.headers);
+	const [readHeaders] = useState(() => () => latest.current.headers);
+	const [liveFetch] = useState(() => (...args) => (latest.current.fetch ?? fetch)(...args));
+	const [liveVerifier] = useState(() => ({ verify: (token, expectations) => {
+		const verifier = latest.current.verifier;
+		return verifier === void 0 ? Promise.reject(/* @__PURE__ */ new Error("PermDock: the verifier prop was removed.")) : verifier.verify(token, expectations);
+	} }));
+	return {
+		headers,
+		readHeaders,
+		fetch: liveFetch,
+		verifier: props.verifier === void 0 ? void 0 : liveVerifier
+	};
+}
+//#endregion
+export { PermDockStoreContext as i, useKeyed as n, PermDockSnapshotPromiseContext as r, useLiveOptions as t };

package/dist/load-DhWEB9P1.js

@@ -0,0 +1,75 @@
+import { _ as listPermissions } from "./permissions-DVoF6dMt.js";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createJiti } from "jiti";
+//#region src/cli/load.ts
+/**
+* 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.
+*/
+const NOT_NATIVE = /* @__PURE__ */ new Set([
+	"ERR_MODULE_NOT_FOUND",
+	"ERR_UNKNOWN_FILE_EXTENSION",
+	"ERR_UNSUPPORTED_DIR_IMPORT",
+	"ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX",
+	"ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING"
+]);
+function loadsWithJiti(error) {
+	if (error instanceof SyntaxError) return true;
+	const code = error !== null && typeof error === "object" && "code" in error ? error.code : void 0;
+	return typeof code === "string" && NOT_NATIVE.has(code);
+}
+function importWithJiti(abs, fresh) {
+	return createJiti(import.meta.url, {
+		interopDefault: false,
+		jsx: true,
+		tsconfigPaths: dirname(abs),
+		moduleCache: !fresh,
+		fsCache: !fresh
+	}).import(abs);
+}
+/**
+* Imports a project module the way its bundler would. Node's own `import()`
+* comes first; a module it cannot resolve or parse (tsconfig `paths`
+* aliases, extensionless relative imports, `enum`, TSX) loads through jiti
+* with the `paths` of the nearest `tsconfig.json` above it. Exports are
+* returned as written; `default` is not merged into the namespace.
+*/
+async function loadModule(abs, options) {
+	let loaded;
+	if (options?.fresh === true) loaded = await importWithJiti(abs, true);
+	else try {
+		loaded = await import(pathToFileURL(abs).href);
+	} catch (error) {
+		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`);
+	return loaded;
+}
+function pickNamed(mod, names) {
+	for (const name of names) if (name in mod) return mod[name];
+	return mod["default"];
+}
+function asPermissionTree(value) {
+	if (value === null || typeof value !== "object") throw new Error("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");
+	return value;
+}
+function leavesOf(tree) {
+	return listPermissions(tree);
+}
+/** 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"]));
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { loadModule as a, loadConfiguredPolicy as i, asPolicy as n, pickNamed as o, leavesOf as r, asPermissionTree as t };

package/dist/load-DwJUafYN.js

@@ -0,0 +1,2 @@
+import { a as loadModule, o as pickNamed } from "./load-DhWEB9P1.js";
+export { loadModule, pickNamed };

package/dist/load-jose-BL6LH4bL.js

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

package/dist/lru-8q4WZjBV.js

@@ -0,0 +1,28 @@
+//#region src/agent/lru.ts
+function boundedMap(limit) {
+	const map = /* @__PURE__ */ new Map();
+	return {
+		get: (key) => {
+			const value = map.get(key);
+			if (value !== void 0) {
+				map.delete(key);
+				map.set(key, value);
+			}
+			return value;
+		},
+		set: (key, value) => {
+			map.delete(key);
+			map.set(key, value);
+			if (map.size > limit) {
+				const oldest = map.keys().next();
+				if (oldest.done !== true) map.delete(oldest.value);
+			}
+		},
+		delete: (key) => {
+			map.delete(key);
+		},
+		size: () => map.size
+	};
+}
+//#endregion
+export { boundedMap as t };