permdock 0.0.0 → 0.2.0

package/dist/helpers-H_KARDVC.js

@@ -0,0 +1,421 @@
+import { t as compact } from "./compact-y6vfu2_f.js";
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+import { i as findPermission, s as getRegistry } from "./permissions-DVoF6dMt.js";
+import { r as approverLeaves } from "./approvers-DT4AVyIg.js";
+import { t as describe } from "./describe-B_gVZEVi.js";
+import { t as parseDuration } from "./duration-xK2jGFVc.js";
+import { i as relationReader, n as pendingRelations, o as resolveRelated } from "./relations-cjOL01hZ.js";
+import { t as ApprovalError } from "./errors-DRnGZHzF.js";
+import { f as approverRelationKey, l as APPROVAL_HEADER, n as assertApprover, s as listAllApprovals } from "./store-DMAWwAJV.js";
+//#region src/approvals/relations.ts
+const DEFAULT_PARENT_DEPTH = 16;
+/** Every approver a request names: `by`, each stage and its escalation, and `escalation.to`, inside `anyOf` groups too. */
+function requestApprovers(approvers) {
+	return [
+		...approverLeaves(approvers.by),
+		...(approvers.stages ?? []).flatMap((stage) => approverLeaves(stage.by).concat(approverLeaves(stage.escalation?.to))),
+		...approverLeaves(approvers.escalation?.to)
+	];
+}
+/** Reads until nothing is in flight: each round loads one more layer of facts. */
+async function settled(read, unread, cache) {
+	for (;;) {
+		const value = read();
+		if (!unread(value)) return value;
+		const pending = pendingRelations(cache);
+		if (pending.length === 0) return value;
+		await Promise.all(pending);
+	}
+}
+/** The id of `item.resource` the walk starts from, after following `through` links. */
+async function startOf(item, resource, id, reader, cache, registry) {
+	if (!Array.isArray(item.through)) return resource === item.resource ? id : void 0;
+	let current = resource;
+	let at = id;
+	for (const link of item.through) {
+		const node = registry.get(current);
+		const target = node !== void 0 && Object.hasOwn(node.links, link) ? node.links[link] : void 0;
+		if (target === void 0) return;
+		const query = {
+			resource: current,
+			id: at,
+			depth: 1,
+			through: link
+		};
+		const chain = await settled(() => reader.chain(query), (value) => value === "pending", cache);
+		const next = chain === "pending" || chain === "failed" ? void 0 : chain.ancestors[0]?.id;
+		if (next === void 0) return;
+		current = target.resource;
+		at = next;
+	}
+	return current === item.resource ? at : void 0;
+}
+function depthOf(item) {
+	if (item.through === "parent") return item.depth ?? DEFAULT_PARENT_DEPTH;
+	return item.depth ?? 0;
+}
+/**
+* The relation approvers of `request` that `subject` holds on its resource,
+* keyed by `approverRelationKey`, for `ApprovalVerdict.relations`. Reads go
+* through `relations` by the request's resource id; a request without an id,
+* a missing source or a read that fails holds nothing.
+*/
+async function approverRelations(request, subject, options) {
+	const approvers = request.approvers;
+	const id = request.resource.id;
+	if (approvers === void 0 || id === void 0 || options.relations === void 0 || options.permissions === void 0 || subject.principal === null) return [];
+	const items = /* @__PURE__ */ new Map();
+	for (const item of requestApprovers(approvers)) if (item.kind === "relation") items.set(approverRelationKey(item), item);
+	if (items.size === 0) return [];
+	const registry = getRegistry(options.permissions);
+	const cache = /* @__PURE__ */ new Map();
+	const reader = relationReader(options.relations, cache, registry);
+	const now = (options.now ?? /* @__PURE__ */ new Date()).getTime() / 1e3;
+	const holds = async (item) => {
+		const start = await startOf(item, request.resource.type, id, reader, cache, registry);
+		if (start === void 0) return false;
+		const condition = {
+			op: "related",
+			resource: item.resource,
+			relation: item.relation,
+			field: "id",
+			depth: depthOf(item)
+		};
+		return await settled(() => resolveRelated(condition, { id: start }, subject, now, reader), (value) => value === "relation-unavailable", cache) === true;
+	};
+	const entries = [...items];
+	const verdicts = await Promise.all(entries.map(([, item]) => holds(item)));
+	return entries.flatMap(([key], index) => verdicts[index] === true ? [key] : []);
+}
+//#endregion
+//#region src/approvals/permissions.ts
+/**
+* The `holder(permission)` approvers of `request` that `approver` holds, for
+* `ApprovalVerdict.permissions`: each permission key the approver's own
+* instance grants without a row. `approver` must be an instance for the
+* approving principal in the request's tenant; for any other tenant, or an
+* anonymous instance, it holds nothing. A check that throws holds nothing.
+*/
+function approverPermissions(request, approver) {
+	const approvers = request.approvers;
+	const principal = approver.subject.principal;
+	const tenant = request.subject.principal?.tenant;
+	if (approvers === void 0 || principal === null || tenant !== void 0 && principal.tenant !== tenant) return [];
+	const keys = /* @__PURE__ */ new Set();
+	for (const item of requestApprovers(approvers)) if (item.kind === "permission") keys.add(item.permission);
+	return [...keys].filter((key) => {
+		const leaf = findPermission(approver.permissions, key);
+		if (leaf === void 0) return false;
+		try {
+			const decide = approver.decide;
+			return decide(leaf).outcome === "granted";
+		} catch {
+			return false;
+		}
+	});
+}
+/** The permission approvers `subject` holds on `request`, read through `permdockFor`. */
+async function heldPermissions(request, subject, permdockFor) {
+	if (permdockFor === void 0 || request.approvers === void 0) return [];
+	try {
+		return approverPermissions(request, await permdockFor(subject, request));
+	} catch {
+		return [];
+	}
+}
+//#endregion
+//#region src/approvals/helpers.ts
+function permissionMeta(permission) {
+	return {
+		key: permission.key,
+		scope: permission.scope,
+		resource: permission.resource
+	};
+}
+function summariseSubject(subject) {
+	const principal = subject.principal;
+	return compact({
+		principal: principal === null ? null : compact({
+			id: principal.id,
+			roles: principal.roles ?? [],
+			tenant: principal.tenant
+		}),
+		actor: subject.actor === void 0 ? void 0 : {
+			id: subject.actor.id,
+			kind: subject.actor.kind
+		},
+		session: subject.session,
+		delegation: subject.delegation === void 0 ? void 0 : compact({
+			scopes: subject.delegation.scopes,
+			authorizationDetails: subject.delegation.authorizationDetails
+		})
+	});
+}
+/**
+* The window (`meta.ttl`, else the store's `ttl`, else the default) capped by the grant's
+* `approval.ttl`: a grant shortens how long a request stays open, never
+* extends it.
+*/
+function approvalTtl(storeTtl, approval) {
+	if (storeTtl !== void 0 && (!Number.isSafeInteger(storeTtl) || storeTtl <= 0)) throw new RangeError(`PermDock: approval ttl must be a positive whole number of milliseconds, got ${String(storeTtl)}`);
+	const base = storeTtl ?? 36e5;
+	const grant = approval === void 0 || approval === "human" ? void 0 : parseDuration(approval.ttl);
+	return grant === void 0 ? base : Math.min(base, grant * 1e3);
+}
+async function requestApproval(store, decision, meta) {
+	const now = meta.now ?? /* @__PURE__ */ new Date();
+	const leaf = permissionMeta(meta.permission);
+	const approval = decision.grant.approval;
+	const approvers = approval === void 0 || approval === "human" ? void 0 : compact({
+		by: approval.by,
+		mode: approval.mode,
+		stages: approval.stages,
+		distinct: approval.distinct,
+		staleOn: approval.staleOn,
+		quorum: approval.quorum,
+		escalation: approval.escalation
+	});
+	const ttl = approvalTtl(meta.ttl ?? store.ttl, approval);
+	const request = freezeDeep(compact({
+		v: 1,
+		token: decision.token,
+		permission: leaf.key,
+		scope: leaf.scope,
+		resource: meta.resource ?? { type: leaf.resource },
+		subject: summariseSubject(meta.subject),
+		membership: meta.membership,
+		approvers,
+		detail: meta.detail ?? describe(decision).detail,
+		adapter: meta.adapter,
+		createdAt: now.toISOString(),
+		expiresAt: new Date(now.getTime() + ttl).toISOString(),
+		status: "pending"
+	}));
+	await store.create(request);
+	return request;
+}
+/**
+* Checks `verdict.by` and resolves the request. Relation approvers are read
+* through `options.relations` unless `verdict.relations` is already set.
+*/
+async function resolveApproval(store, token, verdict, options = {}) {
+	const current = await store.get(token);
+	if (current === null) throw new ApprovalError("approval-not-found", "approval was not found");
+	const relations = verdict.relations ?? await approverRelations(current, verdict.by, options);
+	const permissions = verdict.permissions ?? await heldPermissions(current, verdict.by, options.permdockFor);
+	assertApprover(current, verdict.by, options.requireDistinctApprover === true, options.now, relations, permissions);
+	return store.resolve(token, {
+		...verdict,
+		relations,
+		permissions
+	});
+}
+async function vouchApproval(store, token, verdict) {
+	if (typeof verdict.rule !== "string" || verdict.rule === "") throw new TypeError("PermDock: vouchApproval needs the name of the rule that decided the verdict");
+	return await store.resolve(token, compact({
+		status: verdict.status,
+		by: verdict.by,
+		note: verdict.note,
+		vouched: verdict.rule
+	}));
+}
+async function inspectApproval(store, token, now = /* @__PURE__ */ new Date()) {
+	await store.expire(now);
+	const request = await store.get(token);
+	if (request === null) return {
+		ok: false,
+		detail: "approval-not-found"
+	};
+	if (request.status === "pending") return {
+		ok: false,
+		detail: "approval-pending"
+	};
+	if (request.status === "rejected") return {
+		ok: false,
+		detail: "approval-rejected"
+	};
+	if (request.consumedAt !== void 0) return {
+		ok: false,
+		detail: "approval-consumed"
+	};
+	if (request.status === "expired" || Date.parse(request.expiresAt) <= now.getTime()) return {
+		ok: false,
+		detail: "approval-expired"
+	};
+	return {
+		ok: true,
+		request
+	};
+}
+/** Inspects `token` and, when it is approved, consumes it so it resumes once. */
+async function consumeApproval(store, token, now = /* @__PURE__ */ new Date()) {
+	const inspected = await inspectApproval(store, token, now);
+	if (!inspected.ok) return inspected;
+	if (typeof store.consume !== "function") return {
+		ok: false,
+		detail: "approval-not-found"
+	};
+	const consumed = await store.consume(token, now);
+	if (consumed === null) return {
+		ok: false,
+		detail: "approval-consumed"
+	};
+	return {
+		ok: true,
+		request: consumed
+	};
+}
+function approvalDenied(detail) {
+	return {
+		outcome: "denied",
+		denials: [{
+			role: null,
+			reason: "approval",
+			detail
+		}],
+		alternatives: []
+	};
+}
+function staleOnChange(decision) {
+	const approval = decision.grant.approval;
+	return approval !== void 0 && approval !== "human" && approval.staleOn === "resource-change";
+}
+/**
+* True when `token` names a pending or approved request for this permission,
+* resource and principal: the same request, issued while the row had another
+* `version`.
+*/
+async function isStaleToken(store, token, input) {
+	const principal = input.subject.principal;
+	if (principal === null) return false;
+	let request;
+	try {
+		request = await store.get(token);
+	} catch {
+		return false;
+	}
+	return request !== null && (request.status === "approved" || request.status === "pending") && request.permission === input.permission.key && request.resource.type === input.resource.type && request.resource.id === input.resource.id && request.subject.principal?.id === principal.id;
+}
+/**
+* Applies a resume token to a decision. The token only matters when the
+* decision is `approval-required` and the token is the one this call was
+* issued; otherwise a new approval is requested. A matching token is consumed
+* unless `consume` is `false`, so an approval resumes exactly one call. Under
+* `staleOn: 'resource-change'`, a token issued for an earlier version of the
+* same row denies with `stale-approval`; the next call without it asks again.
+*/
+async function resumeDecision(input) {
+	const { decision, store, token } = input;
+	if (decision.outcome !== "approval-required") return decision;
+	if (token === void 0 || token !== decision.token) {
+		if (store !== void 0 && token !== void 0 && staleOnChange(decision) && await isStaleToken(store, token, input)) return {
+			outcome: "denied",
+			denials: [{
+				role: null,
+				reason: "stale-approval"
+			}],
+			alternatives: []
+		};
+		if (store !== void 0) await requestApproval(store, decision, compact({
+			permission: input.permission,
+			resource: input.resource,
+			subject: input.subject,
+			adapter: input.adapter,
+			ttl: input.ttl
+		}));
+		return decision;
+	}
+	if (store === void 0) return approvalDenied("approval-not-found");
+	let inspected;
+	try {
+		inspected = await inspectApproval(store, token, input.now);
+		if (inspected.ok) {
+			const { request } = inspected;
+			if (request.permission !== input.permission.key || request.resource.id !== void 0 && request.resource.id !== input.resource.id) return approvalDenied("approval-mismatch");
+			if (input.consume !== false) inspected = await consumeApproval(store, token, input.now);
+		}
+	} catch {
+		return approvalDenied("approval-not-found");
+	}
+	if (!inspected.ok) return approvalDenied(inspected.detail);
+	const principal = input.subject.principal;
+	if (principal === null) return approvalDenied("approval-mismatch");
+	return {
+		outcome: "granted",
+		subject: {
+			...input.subject,
+			principal
+		},
+		matched: decision.grant,
+		token: decision.token
+	};
+}
+const SYSTEM_KIND = "system";
+async function cancelApprovals(store, filter, meta) {
+	if (store.cancel !== void 0) return store.cancel(filter, meta);
+	const pending = await listAllApprovals(store, {
+		...filter,
+		status: "pending"
+	});
+	const by = {
+		principal: {
+			id: `system:${meta.by}`,
+			kind: "service",
+			roles: []
+		},
+		actor: {
+			id: `system:${meta.by}`,
+			kind: SYSTEM_KIND
+		},
+		context: {}
+	};
+	return (await Promise.all(pending.map(async (request) => {
+		try {
+			await store.resolve(request.token, compact({
+				status: "rejected",
+				by,
+				note: meta.note
+			}));
+			return true;
+		} catch {
+			return false;
+		}
+	}))).filter(Boolean).length;
+}
+function readApprovalHeader(headers) {
+	const value = headers.get(APPROVAL_HEADER);
+	if (value === null || value.trim() === "") return;
+	return value.trim();
+}
+function resumeFromHeader(store, headers, now) {
+	const token = readApprovalHeader(headers);
+	if (token === void 0) return Promise.resolve({
+		ok: false,
+		detail: "approval-not-found"
+	});
+	return inspectApproval(store, token, now);
+}
+/**
+* The token to resume `decision` with when the caller carries none: the
+* decision's own token when the store holds an approved or rejected request
+* for it, so `resumeDecision` resumes (or denies) the call without the
+* caller passing the token back. The token already binds permission,
+* resource (or the call's data when there is no row id), subject and actor.
+* A pending request counts only with `denyPending: true`, which makes the
+* call deny with `approval-pending` instead of asking again. `undefined` when
+* the decision needs no approval, there is no store, or the store has no
+* unexpired request for the token; a store that throws counts as none.
+*/
+async function storedApprovalToken(store, decision, options = {}) {
+	if (store === void 0 || decision.outcome !== "approval-required") return;
+	const now = (options.now ?? /* @__PURE__ */ new Date()).getTime();
+	try {
+		const record = await store.get(decision.token);
+		if (record === null || record.status === "pending" && options.denyPending !== true || record.status === "expired" || Date.parse(record.expiresAt) <= now) return;
+		return decision.token;
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { requestApproval as a, resumeFromHeader as c, vouchApproval as d, approverPermissions as f, readApprovalHeader as i, storedApprovalToken as l, approverRelations as m, consumeApproval as n, resolveApproval as o, heldPermissions as p, inspectApproval as r, resumeDecision as s, cancelApprovals as t, summariseSubject as u };

package/dist/hono/index.d.ts

@@ -0,0 +1,48 @@
+import { C as Policy, D as PolicyVocabulary, Nr as Principal, ln as PermDock } from "../policy-CFZAr_Al.js";
+import { f as Permission } from "../permissions-DttnqqxC.js";
+import { n as RevocationFeed } from "../revocations-Cy06JNx2.js";
+import { A as ConnectionOptions, O as Connection, h as InvalidSignatureError, i as ProtectOptions, n as OpenApiHooks, w as verifyWebBotAuth, x as discoverViaSignatureAgent } from "../create-BWyx3jua.js";
+import { t as ServerAdapterOptions } from "../bind-CVy3Espv.js";
+import { Context, Hono, MiddlewareHandler } from "hono";
+import { SSEMessage, SSEStreamingApi } from "hono/streaming";
+import { WSEvents } from "hono/ws";
+//#region src/hono/create.d.ts
+type HonoPermDockOptions<TUser = unknown> = ServerAdapterOptions<Context, TUser> & {
+  /** Ends or revalidates open sockets and streams. */
+  readonly revocations?: RevocationFeed;
+};
+/** The `Variables` both middlewares set; Hono merges them into the route's Env. */
+type PermDockEnv<TData = unknown, V extends PolicyVocabulary = PolicyVocabulary> = {
+  readonly Variables: {
+    readonly permdock: PermDock<V>;
+    readonly permdockData: TData;
+  };
+};
+type HonoPermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
+  readonly permdock: () => MiddlewareHandler<PermDockEnv<unknown, V>>;
+  readonly protect: <TData = unknown>(permission: Permission | null, loadData?: (c: Context) => TData | Promise<TData>, protectOptions?: ProtectOptions) => MiddlewareHandler<PermDockEnv<NonNullable<TData>, V>>;
+  /** A long-lived connection for the request behind `c`. */
+  readonly connection: (c: Context, connectionOptions?: ConnectionOptions) => Promise<Connection>;
+  /** `upgradeWebSocket` events that close with `1008` when the connection aborts. */
+  readonly socket: <T = unknown>(connection: Connection, events: WSEvents<T>) => WSEvents<T>;
+  /**
+   * Writes `source` to a `streamSSE` stream, dropping items the subscriber
+   * cannot read, and resolves when it ends: after an `event: permdock` frame
+   * when the connection aborts, when the client disconnects, or when the
+   * source is done. Await it as the last statement of the callback.
+   */
+  readonly sse: <T>(connection: Connection, stream: SSEStreamingApi, source: AsyncIterable<T>, options?: SseOptions<T>) => Promise<void>;
+  readonly permdockHandler: () => Hono;
+  readonly openapi: OpenApiHooks;
+};
+type SseOptions<T> = {
+  /** Items the subscriber cannot read under this permission are dropped. */
+  readonly items?: Permission<string, unknown, "instance">;
+  /** The row to check for an item, when the item wraps it. */
+  readonly unwrap?: (item: T) => unknown;
+  /** The frame for an item; defaults to `{ data: JSON.stringify(item) }`. */
+  readonly format?: (item: T) => SSEMessage;
+};
+export declare function createPermDock<TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, options: HonoPermDockOptions<TUser>): HonoPermDock<V>;
+//#endregion
+export { type HonoPermDock, type HonoPermDockOptions, InvalidSignatureError, type PermDockEnv, type SseOptions, discoverViaSignatureAgent, verifyWebBotAuth };

package/dist/hono/index.js

@@ -0,0 +1,99 @@
+import { t as compact } from "../compact-y6vfu2_f.js";
+import { r as PermDockRevokedError } from "../errors-Cz5zn0mW.js";
+import { i as discoverViaSignatureAgent, r as InvalidSignatureError, s as verifyWebBotAuth } from "../evaluations-tz6D9A2G.js";
+import { t as problemFromError } from "../map-error-pgUWNNtG.js";
+import { r as bindKernel } from "../bind-VnYn2HKq.js";
+import { i as onRevoked, n as guardIterable, t as POLICY_VIOLATION } from "../stream-DDpvynSB.js";
+import { Hono } from "hono";
+//#region src/hono/create.ts
+function socket(connection, events) {
+	return {
+		...events,
+		onOpen: (evt, ws) => {
+			onRevoked(connection, (problem) => {
+				ws.close(POLICY_VIOLATION, problem.type);
+			});
+			if (!connection.signal.aborted) events.onOpen?.(evt, ws);
+		},
+		onClose: (evt, ws) => {
+			connection.close();
+			events.onClose?.(evt, ws);
+		}
+	};
+}
+async function sse(connection, stream, source, options = {}) {
+	const disconnected = new Promise((resolve) => {
+		stream.onAbort(() => {
+			connection.close();
+			resolve({
+				done: true,
+				value: void 0
+			});
+		});
+	});
+	const iterator = guardIterable(source, connection, compact({
+		items: options.items,
+		unwrap: options.unwrap,
+		onRevoked: (error) => error
+	}))[Symbol.asyncIterator]();
+	try {
+		for (;;) {
+			const next = await Promise.race([iterator.next(), disconnected]);
+			if (next.done === true || stream.aborted) return;
+			const item = next.value;
+			await stream.writeSSE(options.format?.(item) ?? { data: JSON.stringify(item) });
+		}
+	} catch (error) {
+		if (!(error instanceof PermDockRevokedError)) throw error;
+		if (!stream.aborted) await stream.writeSSE({
+			event: "permdock",
+			data: JSON.stringify(error.toProblemDetails())
+		});
+	} finally {
+		Promise.resolve(iterator.return(void 0)).catch(() => void 0);
+	}
+}
+function mapDownstream(c) {
+	const mapped = c.error === void 0 ? void 0 : problemFromError(c.error, { credentials: c.req.header("authorization") !== void 0 });
+	if (mapped !== void 0) {
+		c.res = void 0;
+		c.res = mapped;
+	}
+}
+function createPermDock(policy, options) {
+	const { kernel, bind, scopeOf, handlerScope, attach } = bindKernel(policy, options, "hono", (c) => c.req.raw);
+	const permdock = () => async (c, next) => {
+		const attached = await attach(c);
+		if (!attached.ok) return attached.response;
+		c.set("permdock", attached.permdock);
+		await next();
+		mapDownstream(c);
+	};
+	const protect = (permission, loadData, protectOptions) => async (c, next) => {
+		const guard = await kernel.protect(permission, loadData === void 0 ? void 0 : () => loadData(c), protectOptions)(bind(c), await scopeOf(c));
+		if (!guard.ok) return guard.response;
+		c.set("permdock", guard.permdock);
+		c.set("permdockData", guard.data);
+		await next();
+		mapDownstream(c);
+	};
+	const connection = async (c, connectionOptions) => kernel.connection(bind(c), connectionOptions, await scopeOf(c));
+	const permdockHandler = () => {
+		const { POST, GET } = kernel.permdockHandler(handlerScope);
+		const app = new Hono();
+		app.post("/", (c) => POST(bind(c)));
+		app.get("/", (c) => GET(bind(c)));
+		return app;
+	};
+	return {
+		permdock,
+		protect,
+		connection,
+		socket,
+		sse,
+		permdockHandler,
+		openapi: kernel.openapi
+	};
+}
+//#endregion
+export { InvalidSignatureError, createPermDock, discoverViaSignatureAgent, verifyWebBotAuth };