permdock 0.4.0 → 0.5.0

package/dist/wire-delegation-Cv3W2eaM.js

@@ -0,0 +1,36 @@
+import { r as isRecord, t as compact } from "./compact-CAf557ZB.js";
+//#region src/core/wire-delegation.ts
+function toWireDelegation(delegation) {
+	if (delegation === void 0) return;
+	return compact({
+		scope: delegation.scopes?.join(" "),
+		authorization_details: delegation.authorizationDetails,
+		access: delegation.access
+	});
+}
+function scopeList(value) {
+	if (typeof value !== "string") return;
+	return value.split(" ").filter((item) => item.length > 0);
+}
+/**
+* The runtime `Delegation` of a wire delegation. A field of the wrong type
+* becomes an empty scope list, so a malformed delegation narrows to nothing.
+*/
+function fromWireDelegation(value) {
+	if (value === void 0) return;
+	if (!isRecord(value)) return { scopes: [] };
+	const scope = value["scope"];
+	const details = value["authorization_details"];
+	const access = value["access"];
+	if (scope !== void 0 && typeof scope !== "string" || details !== void 0 && !(Array.isArray(details) && details.every(isDetail)) || access !== void 0 && !Array.isArray(access)) return { scopes: [] };
+	return compact({
+		scopes: scopeList(scope),
+		authorizationDetails: details,
+		access
+	});
+}
+function isDetail(value) {
+	return isRecord(value) && typeof value["type"] === "string";
+}
+//#endregion
+export { toWireDelegation as n, fromWireDelegation as t };

package/dist/wire-denial-C7PaVYEM.js

@@ -0,0 +1,27 @@
+import { t as compact } from "./compact-CAf557ZB.js";
+//#region src/core/wire-denial.ts
+const IN_PROCESS = /* @__PURE__ */ new Set(["closure-error", "validation"]);
+function jsonDetail(value) {
+	if (value === void 0 || value === null || value instanceof Error) return;
+	if (typeof value === "string" || typeof value === "boolean") return value;
+	if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
+	if (typeof value !== "object") return;
+	try {
+		return JSON.parse(JSON.stringify(value));
+	} catch {
+		return;
+	}
+}
+function wireDenial(denial) {
+	return compact({
+		role: denial.role,
+		reason: denial.reason,
+		to: denial.to,
+		detail: IN_PROCESS.has(denial.reason) ? void 0 : jsonDetail(denial.detail)
+	});
+}
+function wireDenials(denials) {
+	return denials.map(wireDenial);
+}
+//#endregion
+export { wireDenials as t };

package/dist/workflow/index.d.ts

@@ -0,0 +1,5 @@
+import { a as AutomationSource, i as AutomationRequest, l as memoryAutomationSource, n as AutomationDecision, r as AutomationMode, s as MemoryAutomationSource, t as Automation, u as parseAutomation } from "../automation-BMZPIVUM.js";
+import { i as pollingApprovalWaiter, n as ApprovalWaiter, r as PollingApprovalWaiterOptions, t as ApprovalWaitOptions } from "../waiter-CKy4MQSY.js";
+import { a as WorkflowPermDockOptions, i as WorkflowPermDock, n as AwaitApprovalOptions, o as createPermDock, r as StartAutomationResult, t as AutomationOptions } from "../create-BFfm17UA.js";
+import "../index-CaxrMD1A.js";
+export { type ApprovalWaitOptions, type ApprovalWaiter, type Automation, type AutomationDecision, type AutomationMode, type AutomationOptions, type AutomationRequest, type AutomationSource, type AwaitApprovalOptions, type MemoryAutomationSource, type PollingApprovalWaiterOptions, type StartAutomationResult, type WorkflowPermDock, type WorkflowPermDockOptions, createPermDock, memoryAutomationSource, parseAutomation, pollingApprovalWaiter };

package/dist/workflow/index.js

@@ -0,0 +1,223 @@
+import { t as compact } from "../compact-CAf557ZB.js";
+import { n as freezeDeep } from "../freeze-CrU8nQeX.js";
+import { n as findPermission } from "../permission-registry-Br4jSNVi.js";
+import { n as isThenable } from "../thenable-yD7SabqG.js";
+import { n as memoryAutomationSource, r as parseAutomation } from "../automation-DVjOckjV.js";
+import { c as withApp, t as getPermDock } from "../permdock-B9JxkBwC.js";
+import { o as automationEvent } from "../sink-BEZSlMS_.js";
+import { a as requestApproval, s as resumeDecision } from "../helpers-DTcZOzhF.js";
+import { n as signRunTicket, r as subjectFromRunTicket } from "../run-ticket-sxFI6LAk.js";
+import { t as pollingApprovalWaiter } from "../waiter-BGUtGYoU.js";
+//#region src/workflow/create.ts
+function writeQuietly(sink, event) {
+	try {
+		const written = sink.write([event]);
+		if (isThenable(written)) Promise.resolve(written).catch(() => void 0);
+	} catch {}
+}
+const DEFAULT_TTL = 86400;
+function deniedStart(reason, detail) {
+	return freezeDeep({
+		outcome: "denied",
+		denials: [compact({
+			role: null,
+			reason,
+			detail
+		})]
+	});
+}
+async function readAutomation(source, id, tenant) {
+	try {
+		const found = await source.automation(id, compact({ tenant }));
+		const parsed = found === null ? void 0 : parseAutomation(found);
+		return parsed === void 0 || parsed.revoked === true ? void 0 : parsed;
+	} catch {
+		return;
+	}
+}
+function idOf(row) {
+	if (row === null || typeof row !== "object") return;
+	const id = Reflect.get(row, "id");
+	return typeof id === "string" ? id : void 0;
+}
+function targetOf(permission, data, resource) {
+	return resource ?? compact({
+		type: permission.resource,
+		id: idOf(data)
+	});
+}
+/**
+* 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.
+*/
+function createPermDock(policy, given) {
+	const { signer, verifier, principals, automations, store: approvals, waiter, audience, issuer, expiresIn = DEFAULT_TTL, onAuth, ...permdockOptions } = withApp(policy, given);
+	const instanceFor = (subject) => getPermDock(policy, subject, permdockOptions);
+	const publisherCanAssign = async (automation) => {
+		const publisher = await principals.principal(automation.publishedBy, compact({ tenant: automation.tenant }));
+		if (publisher === null) return false;
+		const instance = await instanceFor({
+			principal: publisher,
+			context: {}
+		});
+		const roles = new Set(instance.assignableRoles(compact({ tenant: automation.tenant })).map((role) => role.key));
+		const ceiling = new Set(instance.assignablePermissions(compact({ tenant: automation.tenant })).map((leaf) => leaf.key));
+		return (automation.roles ?? []).every((role) => roles.has(role)) && automation.permissions.every((key) => ceiling.has(key));
+	};
+	const getPermDock$1 = async (ticket) => {
+		let current;
+		const tracked = { async automation(id, readOptions) {
+			current = await readAutomation(automations, id, readOptions?.tenant);
+			return current ?? null;
+		} };
+		const live = { async principal(id, readOptions) {
+			if (current === void 0) return principals.principal(id, readOptions);
+			if (id !== current.principal) return null;
+			if (current.mode === "publisher") return principals.principal(id, readOptions);
+			if (current.tenant === void 0 || !await publisherCanAssign(current)) return null;
+			return freezeDeep({
+				id: current.principal,
+				kind: "service",
+				tenant: current.tenant,
+				memberships: [{
+					tenant: current.tenant,
+					roles: current.roles ?? []
+				}]
+			});
+		} };
+		let subject;
+		try {
+			subject = await subjectFromRunTicket(ticket, compact({
+				verifier,
+				principals: live,
+				automations: tracked,
+				audience,
+				issuer,
+				onAuth
+			}));
+		} catch {
+			subject = {
+				principal: null,
+				context: {}
+			};
+		}
+		return instanceFor(subject);
+	};
+	const start = async (id, startOptions = {}) => {
+		const automation = await readAutomation(automations, id, startOptions.tenant);
+		if (automation === void 0) return deniedStart("validation", { cause: "automation-unavailable" });
+		const { caller } = startOptions;
+		if (caller !== void 0) {
+			const run = automation.run === void 0 ? void 0 : findPermission(policy.permissions, automation.run);
+			if (run === void 0) return deniedStart("no-grant", { permission: automation.run ?? null });
+			const decision = caller.decide(run, startOptions.row);
+			if (decision.outcome !== "granted") return freezeDeep({
+				outcome: "denied",
+				denials: decision.outcome === "denied" ? decision.denials : [{
+					role: null,
+					reason: "approval"
+				}]
+			});
+		}
+		const scopes = [];
+		for (const key of automation.permissions) {
+			const leaf = findPermission(policy.permissions, key);
+			if (leaf === void 0) return deniedStart("validation", { permission: key });
+			scopes.push(leaf.scope);
+		}
+		const runId = startOptions.id ?? globalThis.crypto.randomUUID();
+		const runAutomation = {
+			id: automation.id,
+			version: automation.version
+		};
+		const signed = await signRunTicket(compact({
+			principal: automation.principal,
+			kind: "automation",
+			actor: {
+				id: automation.id,
+				kind: "automation"
+			},
+			delegation: { scopes },
+			automation: runAutomation,
+			tenant: automation.tenant,
+			trigger: startOptions.trigger,
+			binding: startOptions.binding,
+			id: runId,
+			expiresIn
+		}), signer, compact({
+			audience,
+			now: startOptions.now
+		}));
+		if (permdockOptions.sink !== void 0) writeQuietly(permdockOptions.sink, automationEvent({
+			operation: "run",
+			automation,
+			run: runId
+		}));
+		return freezeDeep({
+			outcome: "started",
+			ticket: signed,
+			run: {
+				id: runId,
+				automation: runAutomation
+			}
+		});
+	};
+	const opened = async (ticket, permission, data, decideOptions) => {
+		const { resource, ttl, signal: _signal, ...rest } = decideOptions;
+		const first = await getPermDock$1(ticket);
+		const decision = first.decide(permission, data, rest);
+		if (decision.outcome !== "approval-required" || approvals === void 0) return { decision };
+		return {
+			decision,
+			expiresAt: (await requestApproval(approvals, decision, compact({
+				permission,
+				resource: targetOf(permission, data, resource),
+				subject: first.subject,
+				adapter: "workflow",
+				ttl
+			}))).expiresAt
+		};
+	};
+	const openApproval = async (ticket, permission, data, decideOptions = {}) => (await opened(ticket, permission, data, decideOptions)).decision;
+	const resumeApproval = async (ticket, permission, token, data, decideOptions = {}) => {
+		const { resource, ttl: _ttl, signal: _signal, ...rest } = decideOptions;
+		const run = await getPermDock$1(ticket);
+		const decision = run.decide(permission, data, rest);
+		if (approvals === void 0) return decision;
+		return resumeDecision({
+			decision,
+			permission,
+			subject: run.subject,
+			store: approvals,
+			resource: targetOf(permission, data, resource),
+			adapter: "workflow",
+			token
+		});
+	};
+	const awaitApproval = async (ticket, permission, data, decideOptions = {}) => {
+		if (waiter === void 0) {
+			const { resource: _resource, ttl: _ttl, signal: _signal, ...rest } = decideOptions;
+			return (await getPermDock$1(ticket)).decide(permission, data, rest);
+		}
+		const { decision, expiresAt } = await opened(ticket, permission, data, decideOptions);
+		if (decision.outcome !== "approval-required" || expiresAt === void 0) return decision;
+		try {
+			await waiter.wait(decision.token, compact({
+				expiresAt: { epochMilliseconds: Date.parse(expiresAt) },
+				signal: decideOptions.signal
+			}));
+		} catch {}
+		return resumeApproval(ticket, permission, decision.token, data, decideOptions);
+	};
+	return Object.freeze({
+		start,
+		getPermDock: getPermDock$1,
+		awaitApproval,
+		openApproval,
+		resumeApproval
+	});
+}
+//#endregion
+export { createPermDock, memoryAutomationSource, parseAutomation, pollingApprovalWaiter };

package/dist/workflow-sdk/index.d.ts

@@ -0,0 +1,56 @@
+import { Nn as Decision } from "../policy-types-DzwivBgR.js";
+import { w as Permission } from "../vocabulary-D6lPdb4Z.js";
+import { r as PermDock } from "../permdock-D7eeLJER.js";
+import { n as ApprovalWaiter } from "../waiter-CKy4MQSY.js";
+import { i as WorkflowPermDock, r as StartAutomationResult, t as AutomationOptions } from "../create-BFfm17UA.js";
+//#region src/workflow-sdk/index.d.ts
+/** The part of a Workflow SDK `Hook` the waiter reads: awaiting it suspends the run. */
+export type WorkflowSdkHook = {
+  readonly then: PromiseLike<unknown>["then"];
+  dispose(): void;
+};
+/** `createHook` from `workflow`; valid only inside a `"use workflow"` function. */
+export type WorkflowSdkCreateHook = (options: {
+  readonly token: string;
+}) => WorkflowSdkHook;
+/** `resumeHook` from `workflow/api`. */
+export type WorkflowSdkResumeHook = (token: string, payload: unknown) => Promise<unknown>;
+/** `sleep` from `workflow`; valid only inside a `"use workflow"` function. */
+export type WorkflowSdkSleep = (until: Date) => PromiseLike<unknown>;
+/** `start` from `workflow/api`, with the workflow function and its arguments. */
+export type WorkflowSdkStart<TArgs extends unknown[], TRun> = (workflow: (ticket: string, ...args: TArgs) => Promise<unknown>, args: [string, ...TArgs]) => Promise<TRun>;
+export type WorkflowSdkWaiterOptions = {
+  readonly createHook: WorkflowSdkCreateHook;
+  readonly resumeHook: WorkflowSdkResumeHook;
+  /** With `sleep`, a wait ends at the request's `expiresAt`; without it, only a wake ends it. */
+  readonly sleep?: WorkflowSdkSleep;
+};
+/** The Workflow SDK hook token a run parks on while approval `token` is pending. */
+export declare function approvalHookToken(token: string): string;
+/**
+ * An `ApprovalWaiter` over Workflow SDK hooks. `wait` parks the run on a hook
+ * and must run inside the workflow function; `wake` resumes it from an
+ * approval handler. The hook carries no verdict: the run decides again from
+ * the approval store after it wakes.
+ */
+export declare function workflowSdkWaiter(options: WorkflowSdkWaiterOptions): ApprovalWaiter;
+export type StartAutomationRunResult<TRun> = (Extract<StartAutomationResult, {
+  readonly outcome: "started";
+}> & {
+  readonly workflowRun: TRun;
+}) | Extract<StartAutomationResult, {
+  readonly outcome: "denied";
+}>;
+/**
+ * Starts automation `id` and, when PermDock grants it, the Workflow SDK run
+ * that executes it, with the run ticket as the workflow's first argument. A
+ * denied start starts nothing.
+ */
+export declare function startAutomation<TArgs extends unknown[], TRun>(workflow: Pick<WorkflowPermDock, "start">, start: WorkflowSdkStart<TArgs, TRun>, run: (ticket: string, ...args: TArgs) => Promise<unknown>, id: string, args: TArgs, options?: AutomationOptions): Promise<StartAutomationRunResult<TRun>>;
+/**
+ * Resumes hook `token` with `payload` only when `caller` is granted
+ * `permission` on `row`. A token alone never resumes a run. A hook that is
+ * gone or a resume that throws denies with `validation`.
+ */
+export declare function authorizeHook(resumeHook: WorkflowSdkResumeHook, caller: PermDock, permission: Permission, row: unknown, token: string, payload: unknown): Promise<Decision>;
+//#endregion

package/dist/workflow-sdk/index.js

@@ -0,0 +1,78 @@
+import { n as freezeDeep } from "../freeze-CrU8nQeX.js";
+//#region src/workflow-sdk/index.ts
+const HOOK_PREFIX = "permdock:approval:";
+/** The Workflow SDK hook token a run parks on while approval `token` is pending. */
+function approvalHookToken(token) {
+	return `${HOOK_PREFIX}${token}`;
+}
+/**
+* An `ApprovalWaiter` over Workflow SDK hooks. `wait` parks the run on a hook
+* and must run inside the workflow function; `wake` resumes it from an
+* approval handler. The hook carries no verdict: the run decides again from
+* the approval store after it wakes.
+*/
+function workflowSdkWaiter(options) {
+	const { createHook, resumeHook, sleep } = options;
+	return Object.freeze({
+		async wait(token, waitOptions = {}) {
+			const hook = createHook({ token: approvalHookToken(token) });
+			try {
+				const expiresAt = waitOptions.expiresAt?.epochMilliseconds;
+				if (sleep === void 0 || expiresAt === void 0) {
+					await hook;
+					return;
+				}
+				await Promise.race([hook, sleep(new Date(expiresAt))]);
+			} finally {
+				hook.dispose();
+			}
+		},
+		async wake(token) {
+			try {
+				await resumeHook(approvalHookToken(token), { token });
+			} catch {}
+		}
+	});
+}
+/**
+* Starts automation `id` and, when PermDock grants it, the Workflow SDK run
+* that executes it, with the run ticket as the workflow's first argument. A
+* denied start starts nothing.
+*/
+async function startAutomation(workflow, start, run, id, args, options) {
+	const started = await workflow.start(id, options);
+	if (started.outcome !== "started") return started;
+	const workflowRun = await start(run, [started.ticket, ...args]);
+	return Object.freeze({
+		...started,
+		workflowRun
+	});
+}
+function hookDenied() {
+	return freezeDeep({
+		outcome: "denied",
+		denials: [{
+			role: null,
+			reason: "validation",
+			detail: { cause: "hook-unavailable" }
+		}],
+		alternatives: []
+	});
+}
+/**
+* Resumes hook `token` with `payload` only when `caller` is granted
+* `permission` on `row`. A token alone never resumes a run. A hook that is
+* gone or a resume that throws denies with `validation`.
+*/
+async function authorizeHook(resumeHook, caller, permission, row, token, payload) {
+	const decision = caller.decide(permission, row);
+	if (decision.outcome !== "granted") return decision;
+	try {
+		await resumeHook(token, payload);
+	} catch {
+		return hookDenied();
+	}
+	return decision;
+}
+//#endregion
+export { approvalHookToken, authorizeHook, startAutomation, workflowSdkWaiter };

package/dist/{wrap-Cr93qqdP.d.ts → wrap-Bd1Tejur.d.ts}

@@ -1,4 +1,5 @@
-import { j as PolicyVocabulary, jt as PermDock } from "./policy-types-sp9P1iIV.js";
+import { j as PolicyVocabulary } from "./policy-types-DzwivBgR.js";
+import { r as PermDock } from "./permdock-D7eeLJER.js";
 //#region src/core/wrap.d.ts
 /** A wrapper an adapter applies to each instance it builds, as `withOtel` does. */
 type PermDockWrap = <V extends PolicyVocabulary>(permdock: PermDock<V>) => PermDock<V>;

package/dist/{wrap-DWsU_5Bd.js → wrap-gX61EtpB.js}

@@ -1,3 +1,4 @@
+import { n as internalsOf, t as attachInternals } from "./internals-Dk8A8fX3.js";
 //#region src/core/wrap.ts
 /**
 * A frozen copy of `permdock` with the members `overrides` returns replaced.
@@ -6,16 +7,16 @@
 */
 function wrapPermDock(permdock, overrides) {
 	const wrap = (next) => wrapPermDock(next, overrides);
-	return Object.freeze({
+	const wrapped = {
 		...permdock,
 		...overrides(permdock),
 		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);
-		}
-	});
+		derive: async (options) => wrap(await permdock.derive(options))
+	};
+	const internals = internalsOf(permdock);
+	if (internals !== void 0) attachInternals(wrapped, internals);
+	return Object.freeze(wrapped);
 }
 /** `otel`, then `wrap`. */
 function composeWraps(otel, wrap) {