permdock 0.4.0 → 0.6.0

package/dist/create-CQWIpUG-.js

@@ -0,0 +1,403 @@
+import { r as isRecord, t as compact } from "./compact-CAf557ZB.js";
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+import { i as dateAt, p as nowSeconds } from "./time-DkWjdL98.js";
+import { s as policyDocumentFromClaims } from "./hosted-B46-5LYE.js";
+import { l as isApprovalErrorCode, s as ApprovalError, t as APPROVAL_HEADER } from "./types-DqzsnlSA.js";
+import { h as toCloudEvent, l as isAbsoluteUri } from "./sink-BEZSlMS_.js";
+import { n as parseCatalogEventData, t as catalogFingerprint } from "./catalog-fingerprint-CCP0-yQS.js";
+import { t as parseApprovalRequest } from "./parse-request-D_tUXG6M.js";
+import { t as timeoutSignal } from "./timeout-D51niuQP.js";
+//#region src/cloud/approver.ts
+const APPROVER_HEADER = "PermDock-Approver";
+/** The RFC 9396 `authorization_details` type that binds an approver token to one verdict. */
+const APPROVAL_DETAIL_TYPE = "permdock_approval";
+/** Seconds an approver token lives: it proves one resolve call, and the Cloud refuses a replayed `jti`. */
+const APPROVER_TTL = 60;
+async function facts(read, request, verdict, fallback) {
+	if (read === void 0) return fallback ?? [];
+	try {
+		return (await read(request, verdict.by)).filter((item) => typeof item === "string");
+	} catch {
+		return [];
+	}
+}
+function unauthenticated(detail) {
+	return new ApprovalError("approver-unauthenticated", detail);
+}
+/** A rejection only denies, so the Cloud takes a `system` one without an approver token. */
+function isSystemRejection(verdict) {
+	return verdict.status === "rejected" && verdict.by.actor?.kind === "system";
+}
+/**
+* The `PermDock-Approver` header for `verdict`: an RFC 9068 `at+jwt` whose
+* `sub` is the approver, signed by `options.signer` for `<issuer>/approvals`,
+* with a fresh `jti` and one `permdock_approval` authorization detail naming
+* the request id, the verdict status, `vouched`, and the approver's
+* `permissions` and `relations`. With the `roles`, `memberships` and `tenant`
+* claims they are the only facts the Cloud checks a request's `approvers`
+* against in bring-your-own mode. `target` runs only after the
+* approver checks pass. Throws an `ApprovalError` before any resolve when the
+* approver cannot be proven: no signer, no principal, an actor, a failed
+* lookup or a signer failure.
+*/
+async function approverHeaders(verdict, options, issuer, target) {
+	if (isSystemRejection(verdict)) return {};
+	if (verdict.by.actor !== void 0) throw new ApprovalError("approver-not-eligible", "PermDock Cloud: a person approves; a verdict with an actor has no approver token");
+	const principal = verdict.by.principal;
+	if (principal === null || principal.id === "") throw unauthenticated("PermDock Cloud: the approver has no principal id");
+	if (options === void 0) throw unauthenticated("PermDock Cloud: cloud() needs approver.signer to prove who resolves an approval");
+	const { request, etag } = await target();
+	const permissions = await facts(options.permissions, request, verdict, verdict.permissions);
+	const relations = await facts(options.relations, request, verdict, verdict.relations);
+	const issuedAt = nowSeconds();
+	try {
+		const token = await options.signer.sign({
+			sub: principal.id,
+			roles: principal.roles,
+			...principal.memberships === void 0 ? {} : { memberships: principal.memberships },
+			...principal.tenant === void 0 ? {} : { tenant: principal.tenant },
+			authorization_details: [{
+				type: APPROVAL_DETAIL_TYPE,
+				id: request.id,
+				status: verdict.status,
+				permissions,
+				relations,
+				...etag === void 0 ? {} : { etag },
+				...verdict.vouched === void 0 ? {} : { vouched: verdict.vouched }
+			}]
+		}, {
+			typ: "at+jwt",
+			audience: options.audience ?? `${issuer}/approvals`,
+			issuedAt,
+			expiresAt: issuedAt + APPROVER_TTL,
+			jti: globalThis.crypto.randomUUID()
+		});
+		return { [APPROVER_HEADER]: token };
+	} catch {
+		throw unauthenticated("PermDock Cloud: the approver signer failed");
+	}
+}
+//#endregion
+//#region src/cloud/request.ts
+/** Milliseconds a PermDock Cloud request may take; a slower one fails like an unreachable Cloud. */
+const CLOUD_TIMEOUT_MS = 1e4;
+function readEnv(name) {
+	const value = globalThis.process?.env?.[name];
+	return typeof value === "string" ? value : "";
+}
+function firstNonEmpty(...values) {
+	for (const value of values) if (value !== void 0 && value !== "") return value;
+	return "";
+}
+function trimSlash(value) {
+	return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+/**
+* The environment URL and JWK Set URL `cloud()` uses, resolved with the same
+* fallbacks (`PERMDOCK_CLOUD_URL`; `PERMDOCK_CLOUD_ENV`, `VERCEL_ENV`, `production`).
+*/
+function cloudEndpoints(options = {}) {
+	const url = trimSlash(firstNonEmpty(options.url, readEnv("PERMDOCK_CLOUD_URL")));
+	if (url === "") throw new Error("PermDock: cloud() requires url and key.");
+	const environment = firstNonEmpty(options.environment, readEnv("PERMDOCK_CLOUD_ENV"), readEnv("VERCEL_ENV"), "production");
+	const issuer = `${url}/v1/environments/${encodeURIComponent(environment)}`;
+	return Object.freeze({
+		issuer,
+		jwks: `${issuer}/.well-known/jwks.json`
+	});
+}
+/** The authenticated connection every `permdock/cloud` client shares. Throws without a URL or key. */
+function cloudConnection(options) {
+	const key = firstNonEmpty(options.key, readEnv("PERMDOCK_CLOUD_KEY"));
+	if (key === "") throw new Error("PermDock: cloud() requires url and key.");
+	const endpoints = cloudEndpoints(options);
+	const fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis);
+	const request = (path, init = {}, accept, contentType) => {
+		const headers = new Headers();
+		headers.set("authorization", `Bearer ${key}`);
+		headers.set("content-type", "application/json");
+		for (const [name, value] of new Headers(init.headers)) headers.set(name, value);
+		if (accept !== void 0) headers.set("accept", accept);
+		if (contentType !== void 0) headers.set("content-type", contentType);
+		return fetchFn(`${endpoints.issuer}${path}`, {
+			...init,
+			headers,
+			signal: timeoutSignal(CLOUD_TIMEOUT_MS, init.signal)
+		});
+	};
+	return Object.freeze({
+		...endpoints,
+		request
+	});
+}
+/** `true` for a compact JWS: three dot-separated parts, not JSON. */
+function isCompactJws(value) {
+	return !value.startsWith("{") && value.split(".").length === 3;
+}
+//#endregion
+//#region src/cloud/create.ts
+/** Carries the `at+jwt` that names the subject of `GET /snapshot`. */
+const SUBJECT_HEADER = "PermDock-Subject";
+function catalogPushOf(value) {
+	if (!isRecord(value) || !Number.isSafeInteger(value["version"]) || typeof value["fingerprint"] !== "string") return null;
+	const version = Number(value["version"]);
+	const fingerprint = value["fingerprint"];
+	if (value["unchanged"] === true) return {
+		version,
+		fingerprint,
+		unchanged: true
+	};
+	const data = parseCatalogEventData({
+		kind: "drift",
+		fingerprint,
+		findings: value["findings"]
+	});
+	return data?.findings === void 0 ? null : {
+		version,
+		fingerprint,
+		findings: data.findings
+	};
+}
+function asApproval(value) {
+	if (!isRecord(value) || value["v"] !== 1 || typeof value["token"] !== "string") return null;
+	return value;
+}
+/** The refusal PermDock Cloud names in its body, else the one its status implies. */
+async function approvalErrorFrom(response) {
+	let body;
+	try {
+		body = await response.json();
+	} catch {
+		return approvalErrorFromStatus(response.status);
+	}
+	if (body === null || typeof body !== "object" || !("code" in body)) return approvalErrorFromStatus(response.status);
+	const code = body.code;
+	if (!isApprovalErrorCode(code)) return approvalErrorFromStatus(response.status);
+	const detail = "detail" in body ? body.detail : void 0;
+	return new ApprovalError(code, typeof detail === "string" && detail.length > 0 ? detail : code);
+}
+function approvalErrorFromStatus(status) {
+	if (status === 409) return new ApprovalError("approval-not-pending", "approval is not pending");
+	if (status === 410) return new ApprovalError("approval-expired", "approval has expired");
+	return new ApprovalError("approval-not-found", "approval was not found");
+}
+function cloud(options = {}) {
+	const { issuer: root, jwks, request } = cloudConnection(options);
+	const flushAt = options.flushAt ?? 32;
+	const waitUntil = options.waitUntil;
+	const approvals = {
+		async create(record) {
+			if (!(await request("/approvals", {
+				method: "POST",
+				body: JSON.stringify(record)
+			})).ok) throw new Error("PermDock Cloud rejected the approval create");
+		},
+		async get(token) {
+			try {
+				const response = await request("/approvals/by-token", { headers: { [APPROVAL_HEADER]: token } });
+				if (!response.ok) return null;
+				return asApproval(await response.json());
+			} catch {
+				return null;
+			}
+		},
+		async getById(id) {
+			try {
+				const response = await request(`/approvals/${encodeURIComponent(id)}`);
+				if (!response.ok) return null;
+				return asApproval(await response.json());
+			} catch {
+				return null;
+			}
+		},
+		async resolve(token, verdict) {
+			const approver = await approverHeaders(verdict, options.approver, root, async () => {
+				const response = await request("/approvals/by-token", { headers: { [APPROVAL_HEADER]: token } });
+				if (!response.ok) throw await approvalErrorFrom(response);
+				const found = parseApprovalRequest(await response.json());
+				if (found === null) throw new ApprovalError("approval-not-found", "PermDock Cloud returned an unknown approval shape");
+				const etag = response.headers.get("etag");
+				return etag === null ? { request: found } : {
+					request: found,
+					etag
+				};
+			});
+			const response = await request("/approvals/by-token/resolve", {
+				method: "POST",
+				headers: {
+					[APPROVAL_HEADER]: token,
+					...approver
+				},
+				body: JSON.stringify(verdict)
+			});
+			if (!response.ok) throw await approvalErrorFrom(response);
+			const parsed = asApproval(await response.json());
+			if (parsed === null) throw new ApprovalError("approval-not-found", "PermDock Cloud returned an unknown approval shape");
+			return parsed;
+		},
+		async consume(token, now) {
+			try {
+				const response = await request("/approvals/by-token/consume", {
+					method: "POST",
+					headers: { [APPROVAL_HEADER]: token },
+					body: JSON.stringify(compact({ now: now === void 0 ? void 0 : dateAt(now).toISOString() }))
+				});
+				if (!response.ok) return null;
+				return asApproval(await response.json());
+			} catch {
+				return null;
+			}
+		},
+		async list(query) {
+			const params = new URLSearchParams(compact({
+				status: query.status,
+				principalId: query.principalId,
+				actorId: query.actorId,
+				tenant: query.tenant,
+				session: query.session,
+				limit: query.limit === void 0 ? void 0 : String(query.limit),
+				cursor: query.cursor
+			}));
+			const suffix = params.size === 0 ? "" : `?${params.toString()}`;
+			try {
+				const response = await request(`/approvals${suffix}`);
+				if (!response.ok) return { items: [] };
+				const body = await response.json();
+				if (!isRecord(body) || !Array.isArray(body["items"])) return { items: [] };
+				const items = body["items"].flatMap((item) => {
+					const parsed = asApproval(item);
+					return parsed === null ? [] : [parsed];
+				});
+				return typeof body["next"] === "string" && body["next"] !== "" ? {
+					items,
+					next: body["next"]
+				} : { items };
+			} catch {
+				return { items: [] };
+			}
+		},
+		async cancel(filter, meta) {
+			const response = await request("/approvals/cancel", {
+				method: "POST",
+				body: JSON.stringify(compact({
+					filter,
+					by: meta.by,
+					note: meta.note
+				}))
+			});
+			if (!response.ok) throw new Error("PermDock Cloud rejected the approval cancel");
+			const body = await response.json();
+			if (!isRecord(body) || typeof body["cancelled"] !== "number") throw new Error("PermDock Cloud returned an unknown cancel shape");
+			return body["cancelled"];
+		},
+		async expire(now) {
+			try {
+				const response = await request("/approvals/expire", {
+					method: "POST",
+					body: JSON.stringify(compact({ now: now === void 0 ? void 0 : dateAt(now).toISOString() }))
+				});
+				if (!response.ok) return 0;
+				const body = await response.json();
+				if (!isRecord(body) || typeof body["expired"] !== "number") return 0;
+				return body["expired"];
+			} catch {
+				return 0;
+			}
+		}
+	};
+	const capacity = options.capacity ?? 1e4;
+	const source = options.source ?? root;
+	if (!isAbsoluteUri(source)) throw new TypeError("PermDock: cloud() source is an absolute URI");
+	const pending = [];
+	const bound = () => {
+		if (pending.length > capacity) pending.splice(0, pending.length - capacity);
+	};
+	const flush = async () => {
+		if (pending.length === 0) return;
+		const events = pending.splice(0);
+		try {
+			if (!(await request("/decisions", {
+				method: "POST",
+				body: JSON.stringify(events.map((event) => toCloudEvent(event, { source })))
+			}, void 0, "application/cloudevents-batch+json")).ok) pending.unshift(...events);
+		} catch {
+			pending.unshift(...events);
+		}
+		bound();
+	};
+	const sink = {
+		write(events) {
+			pending.push(...events);
+			bound();
+			if (pending.length >= flushAt) return flush();
+			if (waitUntil !== void 0 && pending.length > 0) waitUntil(flush());
+		},
+		flush
+	};
+	const snapshotsFor = (subject) => ({ async get() {
+		const response = await request("/snapshot", { headers: { [SUBJECT_HEADER]: subject } }, "application/jwt");
+		if (!response.ok) throw new Error("PermDock Cloud snapshot request failed");
+		const text = (await response.text()).trim();
+		if (!isCompactJws(text)) throw new Error("PermDock Cloud served an unsigned snapshot");
+		return text;
+	} });
+	let document = null;
+	return freezeDeep({
+		approvals,
+		sink,
+		snapshotsFor,
+		policies: {
+			current() {
+				return document;
+			},
+			async refresh() {
+				const verifier = options.verifier;
+				if (verifier === void 0) return;
+				let response;
+				try {
+					response = await request("/policy");
+				} catch {
+					return;
+				}
+				if (response.status === 404) {
+					document = null;
+					return;
+				}
+				if (!response.ok) return;
+				const token = (await response.text()).trim();
+				if (!isCompactJws(token)) return;
+				const verified = await verifier.verify(token, {
+					typ: "vnd.permdock.policy+jwt",
+					issuer: root,
+					audience: root
+				});
+				if (!verified.ok) return;
+				let next;
+				try {
+					next = policyDocumentFromClaims(verified.claims);
+				} catch {
+					return;
+				}
+				document = next;
+			}
+		},
+		catalog: { async push(value) {
+			const fingerprint = catalogFingerprint(value);
+			const response = await request("/catalog", {
+				method: "POST",
+				body: JSON.stringify({
+					fingerprint,
+					catalog: value
+				})
+			});
+			if (!response.ok) throw new Error(`PermDock Cloud rejected the catalog: HTTP ${String(response.status)}`);
+			const parsed = catalogPushOf(await response.json());
+			if (parsed === null) throw new Error("PermDock Cloud answered the catalog push in an unknown shape");
+			return parsed;
+		} },
+		issuer: root,
+		jwks
+	});
+}
+//#endregion
+export { approverHeaders as a, isCompactJws as i, cloudConnection as n, cloudEndpoints as r, cloud as t };

package/dist/{create-BBO24vj6.js → create-DCF2SvoT.js}

@@ -1,15 +1,15 @@
 import { t as compact } from "./compact-CAf557ZB.js";
 import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
-import { n as problemDetails } from "./problem-details-DECUnXAn.js";
-import { c as listPermissions } from "./permission-registry-BsblpB-z.js";
-import { r as challengeScope } from "./permdock-L26udHSk.js";
+import { n as problemDetails } from "./problem-details-cn5X30gZ.js";
+import { c as listPermissions } from "./permission-registry-Br4jSNVi.js";
 import { n as resourceRef } from "./resource-ref-CaS9yVPi.js";
+import { c as withApp, i as challengeScope } from "./permdock-BrAscV28.js";
 import { r as hasCredentials } from "./http-BBoKefeS.js";
-import { i as decisionResponse, o as notFoundProblem, s as problemFromDecision, t as ANONYMOUS, u as unauthenticatedProblem } from "./problem-CnWraVhC.js";
-import { n as resolveOrNull } from "./build-instance-DIIV9DbC.js";
-import { n as createEvaluationsHandler, r as InvalidSignatureError, t as applyApprovalResume } from "./evaluations-C9YJsv3H.js";
-import { n as tenantScope, t as actorFrom } from "./adapter-context-mlWsVGGg.js";
-import { n as requestContext, t as buildReportingInstance } from "./request-context-BVM7aWNs.js";
+import { i as decisionResponse, o as notFoundProblem, s as problemFromDecision, t as ANONYMOUS, u as unauthenticatedProblem } from "./problem-CTviyH5L.js";
+import { n as resolveOrNull } from "./build-instance-Bu_eDqYw.js";
+import { n as applyApprovalResume, o as evaluationsHandler, u as InvalidSignatureError } from "./evaluations-beAooV0n.js";
+import { n as tenantScope, t as actorFrom } from "./adapter-context-CRhqyzCk.js";
+import { n as requestContext, t as buildReportingInstance } from "./request-context-C81Pip9n.js";
 //#region src/server/kernel-problems.ts
 const NOT_DELEGATED = freezeDeep({
 	outcome: "denied",
@@ -89,7 +89,7 @@ async function refused(hook, fallback, decision, request, report) {
 			decision
 		};
 		const status = result.status;
-		if (typeof status !== "number" || status < 300) throw new TypeError(`PermDock: onDenied returned status ${String(status)}; a refusal keeps a status of 300 or more`);
+		if (typeof status !== "number" || status < 300) throw new TypeError(`PermDock: deniedResponse returned status ${String(status)}; a refusal keeps a status of 300 or more`);
 		return {
 			ok: false,
 			response: result instanceof Response ? result : new Response(JSON.stringify(result), {
@@ -112,11 +112,11 @@ async function guardOn(deps, instance, remote, report, request, permission, load
 	const credentials = request === void 0 ? false : hasCredentials(request);
 	if (permission === null) {
 		if (declared === void 0) throw new TypeError(request === void 0 ? "PermDock: protect(null) needs oauthScopes" : `PermDock: protect(null) needs oauthScopes, and no operation declares them for ${request.method} ${new URL(request.url).pathname}`);
-		if (instance.subject.principal === null) return refused(deps.options.onDenied, unauthenticatedProblem(credentials), ANONYMOUS, request, report);
+		if (instance.subject.principal === null) return refused(deps.options.deniedResponse, unauthenticatedProblem(credentials), ANONYMOUS, request, report);
 	}
 	const { actor, delegation } = instance.subject;
 	const held = permission === null && (actor !== void 0 || delegation !== void 0) ? delegation?.scopes ?? [] : delegation?.scopes;
-	if (declared !== void 0 && held !== void 0 && !declared.some((granted) => held.includes(granted))) return refused(deps.options.onDenied, scopeProblem(permission, instance.subject, credentials, declared[0]), NOT_DELEGATED, request, report);
+	if (declared !== void 0 && held !== void 0 && !declared.some((granted) => held.includes(granted))) return refused(deps.options.deniedResponse, scopeProblem(permission, instance.subject, credentials, declared[0]), NOT_DELEGATED, request, report);
 	let data;
 	if (load !== void 0) {
 		let loaded;
@@ -124,7 +124,7 @@ async function guardOn(deps, instance, remote, report, request, permission, load
 			loaded = await load();
 		} catch (error) {
 			report(error);
-			return refused(deps.options.onDenied, loadFailedProblem(permission), LOAD_FAILED, request, report);
+			return refused(deps.options.deniedResponse, loadFailedProblem(permission), LOAD_FAILED, request, report);
 		}
 		if (loaded === null || loaded === void 0) return {
 			ok: false,
@@ -138,7 +138,7 @@ async function guardOn(deps, instance, remote, report, request, permission, load
 		data
 	};
 	const decideOptions = compact({
-		source: "adapter",
+		call: "adapter",
 		adapter: deps.adapter,
 		field: protectOptions.field,
 		explain: protectOptions.explain,
@@ -162,7 +162,7 @@ async function guardOn(deps, instance, remote, report, request, permission, load
 		decision,
 		data
 	};
-	return refused(deps.options.onDenied, problemFromDecision(decision, permission, instance.subject, compact({
+	return refused(deps.options.deniedResponse, problemFromDecision(decision, permission, instance.subject, compact({
 		approval: deps.options.approval,
 		credentials,
 		scope: declared?.[0] ?? challengeScope(deps.policy, permission),
@@ -172,18 +172,17 @@ async function guardOn(deps, instance, remote, report, request, permission, load
 //#endregion
 //#region src/server/create.ts
 async function resolveActor(request, options) {
-	return (options.webBotAuth === void 0 ? void 0 : await options.webBotAuth(request)) ?? actorFrom(options.actor, request);
+	return (options.webBotAuth === void 0 ? void 0 : await options.webBotAuth.verify(request)) ?? actorFrom(options.actor, request);
 }
 const NO_TENANT = "\0";
-function createPermDock(policy, options) {
-	return createServerKernel(policy, options);
-}
 /**
-* The kernel behind every HTTP adapter. The subject and actor are resolved
-* once per `Request`; one instance is cached per `(Request, tenant)`, so a
-* global middleware and a later tenant-scoped `protect` never share a tenant.
+* The Fetch factory behind every HTTP adapter. The subject and actor are
+* resolved once per `Request`; one instance is cached per `(Request, tenant)`,
+* so a global middleware and a later tenant-scoped `protect` never share a
+* tenant.
 */
-function createServerKernel(policy, options) {
+function createPermDock(policy, given) {
+	const options = withApp(policy, given);
 	const adapter = options.adapter ?? "server";
 	const subjects = /* @__PURE__ */ new WeakMap();
 	const instances = /* @__PURE__ */ new WeakMap();
@@ -217,7 +216,7 @@ function createServerKernel(policy, options) {
 				context
 			},
 			errors,
-			wrap: options.wrap
+			wrap: (created) => options.wrap === void 0 ? created : options.wrap(created)
 		});
 		const remote = options.pdp === void 0 ? void 0 : await options.pdp(policy, user, built.options);
 		reporters.set(built.permdock, built.report);
@@ -243,7 +242,7 @@ function createServerKernel(policy, options) {
 	};
 	const connection = async (request, connectionOptions = {}, scope) => {
 		const { tenant } = scope ?? await tenantScope(options.tenant, request);
-		const { openConnection } = await import("./connection-DUsczpB5.js");
+		const { openConnection } = await import("./connection-DjhIJSs2.js");
 		return openConnection({
 			open: async () => (await build(request, { tenant })).permdock,
 			rebuild: async () => (await instanceFor(await freshSubject(request), tenant)).permdock,
@@ -253,9 +252,9 @@ function createServerKernel(policy, options) {
 			options: connectionOptions
 		});
 	};
-	const permdock = async (request, scope) => (await build(request, scope)).permdock;
+	const getPermDock = async (request, scope) => (await build(request, scope)).permdock;
 	const getSnapshot = async (request, query = {}) => {
-		return (await permdock(request, query.tenant === void 0 ? void 0 : { tenant: query.tenant })).snapshot(compact({
+		return (await getPermDock(request, query.tenant === void 0 ? void 0 : { tenant: query.tenant })).snapshot(compact({
 			include: query.include,
 			tenants: query.tenants
 		}));
@@ -265,7 +264,7 @@ function createServerKernel(policy, options) {
 		options,
 		adapter
 	};
-	const protectRoute = (permission, loadData, protectOptions = {}) => {
+	const protectRoute = (permission, data, protectOptions = {}) => {
 		if (permission === null && routeScopes(protectOptions.oauthScopes) === void 0 && options.operations === void 0) throw new TypeError("PermDock: protect(null) needs oauthScopes, in its options or an operations entry");
 		return async (request, scope) => {
 			let instance;
@@ -280,7 +279,7 @@ function createServerKernel(policy, options) {
 				};
 				throw error;
 			}
-			return guardOn(deps, instance, remote, report, request, permission, loadData === void 0 ? void 0 : () => loadData(request), protectOptions);
+			return guardOn(deps, instance, remote, report, request, permission, data === void 0 ? void 0 : () => data(request), protectOptions);
 		};
 	};
 	const protect = protectRoute;
@@ -299,14 +298,14 @@ function createServerKernel(policy, options) {
 			} };
 		}
 	};
-	const permdockHandler = (scope) => createEvaluationsHandler(compact({
+	const permdockHandler = (scope) => evaluationsHandler(compact({
 		policy,
-		resolve: scope === void 0 ? permdock : async (request) => permdock(request, await scope(request)),
+		resolve: scope === void 0 ? getPermDock : async (request) => getPermDock(request, await scope(request)),
 		store: options.store,
 		adapter
 	}));
 	return {
-		permdock,
+		getPermDock,
 		getSnapshot,
 		protect,
 		protectOn: (instance, permission, load, protectOptions = {}, request) => guardOn(deps, instance, void 0, reporters.get(instance) ?? (() => void 0), request, permission, load, protectOptions),
@@ -321,4 +320,4 @@ function createServerKernel(policy, options) {
 	};
 }
 //#endregion
-export { createServerKernel as n, createPermDock as t };
+export { createPermDock as t };

package/dist/create-D_NmPOdH.d.ts

@@ -0,0 +1,110 @@
+import { Nn as Decision, Pn as Denial, Rt as Instant, T as Policy, dt as TokenVerifier, j as PolicyVocabulary, qt as AuthEvent, rr as Principal, ut as TokenSigner } from "./policy-types-n0uRTsW8.js";
+import { w as Permission } from "./vocabulary-CN8H_9UF.js";
+import { i as PermDockOptions, p as PrincipalSource, r as PermDock, t as DecideOptions } from "./permdock-SV8ZINYT.js";
+import { m as ApprovalStore } from "./types-BdtSDbBO.js";
+import { a as AutomationSource } from "./automation-BNM3TtDo.js";
+import { n as ApprovalWaiter } from "./waiter-B986w1oK.js";
+import { n as RunAutomation, r as RunBinding } from "./run-ticket-DocwaTKn.js";
+//#region src/workflow/create.d.ts
+type WorkflowPermDockOptions = PermDockOptions & {
+  /** Signs the run tickets `start` mints. */
+  readonly signer: TokenSigner;
+  /** Verifies run tickets in `getPermDock`. */
+  readonly verifier: TokenVerifier;
+  /** Loads the principal a run acts as, live, on every `getPermDock`. */
+  readonly principals: PrincipalSource;
+  /** The live automation records, read by `start` and on every `getPermDock`. */
+  readonly automations: AutomationSource;
+  /** Where `awaitApproval` opens and resumes requests; the same option name as every other adapter. */
+  readonly store?: ApprovalStore;
+  /** Suspends `awaitApproval` until a request is decided. */
+  readonly waiter?: ApprovalWaiter;
+  readonly audience?: string | readonly string[];
+  readonly issuer?: string;
+  /** Run ticket lifetime in seconds. Defaults to 86400; a run past it denies. */
+  readonly expiresIn?: number;
+  readonly onAuth?: (event: AuthEvent) => void;
+};
+type AutomationOptions = {
+  /** The tenant the automation is read for. */
+  readonly tenant?: string;
+  /**
+   * The caller starting the run. It needs only the automation's `run`
+   * permission and lends the run nothing. Absent: server code starts the run,
+   * which an automation without `run` requires.
+   */
+  readonly caller?: PermDock;
+  /** The row `run` is decided on, when it is an instance permission. */
+  readonly row?: unknown;
+  /** The event that started the run, as JSON. Kept in `subject.context.trigger`; never a grant. */
+  readonly trigger?: Readonly<Record<string, unknown>>;
+  /** The run id (`jti`); a fresh UUID when absent. */
+  readonly id?: string;
+  readonly binding?: RunBinding;
+  readonly now?: Instant;
+};
+type StartAutomationResult = {
+  readonly outcome: "started";
+  readonly ticket: string;
+  readonly run: {
+    readonly id: string;
+    readonly automation: RunAutomation;
+  };
+} | {
+  readonly outcome: "denied";
+  readonly denials: readonly Denial[];
+};
+type AwaitApprovalOptions = DecideOptions & {
+  /** The resource the approval request names; defaults to the permission's resource and the row's `id`. */
+  readonly resource?: {
+    readonly type: string;
+    readonly id?: string;
+  };
+  /** Seconds the request stays open; the store's `ttl` when absent. */
+  readonly ttl?: number;
+  readonly signal?: AbortSignal;
+};
+type WorkflowPermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
+  /**
+   * Starts a run of the automation `id` and returns its run ticket. Denied
+   * when the automation is unknown or revoked (`validation`) or when the
+   * caller is not granted its `run` permission.
+   */
+  readonly start: (id: string, options?: AutomationOptions) => Promise<StartAutomationResult>;
+  /**
+   * The PermDock of a run, rebuilt from its ticket: the principal loaded
+   * live, narrowed to the automation's permissions and to any policy
+   * delegation to `actor('automation')`. A changed, revoked or unknown
+   * automation, or a publisher who is gone, gives an anonymous instance
+   * that denies everything.
+   */
+  readonly getPermDock: (ticket: string) => Promise<PermDock<V>>;
+  /**
+   * Decides `permission`; on `approval-required` opens a request, waits on
+   * the `waiter`, then rebuilds the run from its ticket and decides again
+   * with the token. The second decision reads the publisher's rights as of
+   * then, so a demotion while waiting denies.
+   */
+  readonly awaitApproval: (ticket: string, permission: Permission, data?: unknown, options?: AwaitApprovalOptions) => Promise<Decision>;
+  /**
+   * The first half of `awaitApproval`, for runners that wait outside the
+   * call: decides, and on `approval-required` opens the request and returns
+   * the decision with its token.
+   */
+  readonly openApproval: (ticket: string, permission: Permission, data?: unknown, options?: AwaitApprovalOptions) => Promise<Decision>;
+  /**
+   * The second half: rebuilds the run from its ticket and decides again with
+   * the approval `token`. A request still pending denies with reason
+   * `approval`.
+   */
+  readonly resumeApproval: (ticket: string, permission: Permission, token: string, data?: unknown, options?: AwaitApprovalOptions) => Promise<Decision>;
+};
+/**
+ * Creates the PermDock for durable runs of published automations. A run
+ * acts as the automation's principal with that principal's rights at each
+ * step, narrowed to the automation's operations; the trigger is recorded
+ * and never grants.
+ */
+declare function createPermDock<TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, given: WorkflowPermDockOptions): WorkflowPermDock<V>;
+//#endregion
+export { WorkflowPermDockOptions as a, WorkflowPermDock as i, AwaitApprovalOptions as n, createPermDock as o, StartAutomationResult as r, AutomationOptions as t };