permdock 0.0.0 → 0.2.0

package/dist/store-DMAWwAJV.js

@@ -0,0 +1,371 @@
+import { t as compact } from "./compact-y6vfu2_f.js";
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+import { i as flattenApprovers } from "./approvers-DT4AVyIg.js";
+import { s as rootMembershipId } from "./scopes-CVdPrWN-.js";
+import { t as parseDuration } from "./duration-xK2jGFVc.js";
+import { d as matchGrantee } from "./grantee-Cv5Sogfv.js";
+import { t as ApprovalError } from "./errors-DRnGZHzF.js";
+//#region src/approvals/types.ts
+const APPROVAL_HEADER = "PermDock-Approval";
+const DEFAULT_APPROVAL_TTL_MS = 36e5;
+/** The approvals a request needs in total: `approvers.quorum` (or 1), or the sum of its stages' quorums. */
+function approvalQuorum(request) {
+	const stages = request.approvers?.stages;
+	if (stages !== void 0) return stages.reduce((sum, stage) => sum + (stage.quorum ?? 1), 0);
+	return request.approvers?.quorum ?? 1;
+}
+/**
+* The instant from which `approvers.escalation.to` may approve, in epoch
+* milliseconds, or `undefined` when the request has no escalation or its
+* `after` does not parse (then nobody escalates: fail-closed).
+*/
+function escalationOpenAt(request) {
+	const after = request.approvers?.escalation?.after;
+	const seconds = parseDuration(after);
+	if (seconds === void 0) return;
+	return Date.parse(request.createdAt) + seconds * 1e3;
+}
+/** The instant from which a stage's own `escalation.to` may approve it, in epoch milliseconds; `undefined` when it has none or `after` does not parse. */
+function stageEscalationOpenAt(request, stage) {
+	const seconds = parseDuration(stage.escalation?.after);
+	if (seconds === void 0) return;
+	return Date.parse(request.createdAt) + seconds * 1e3;
+}
+/** The key a verdict's `relations` lists a relation approver under. */
+function approverRelationKey(item) {
+	return JSON.stringify([
+		item.resource,
+		item.relation,
+		item.through ?? null,
+		item.depth ?? null
+	]);
+}
+//#endregion
+//#region src/approvals/page.ts
+const DEFAULT_PAGE_SIZE = 50;
+const MAX_PAGE_SIZE = 200;
+const MAX_PAGES = 1e3;
+/** The page size of a query: `limit` within 1 to 200, 50 when absent. */
+function approvalPageSize(limit) {
+	if (limit === void 0 || !Number.isFinite(limit)) return DEFAULT_PAGE_SIZE;
+	return Math.min(Math.max(Math.trunc(limit), 1), MAX_PAGE_SIZE);
+}
+function positionOf(request) {
+	return [request.createdAt, request.token];
+}
+function compare(a, b) {
+	if (a[0] !== b[0]) return a[0] < b[0] ? -1 : 1;
+	if (a[1] === b[1]) return 0;
+	return a[1] < b[1] ? -1 : 1;
+}
+/** The `next` cursor after `request`, for a store that pages in its own query. */
+function encodeApprovalCursor(request) {
+	return JSON.stringify(positionOf(request));
+}
+/** The `(createdAt, token)` position a `next` cursor names, or `null` for one that does not parse. */
+function decodeApprovalCursor(cursor) {
+	try {
+		const parsed = JSON.parse(cursor);
+		return Array.isArray(parsed) && parsed.length === 2 && typeof parsed[0] === "string" && typeof parsed[1] === "string" ? [parsed[0], parsed[1]] : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Pages already-filtered requests in `(createdAt, token)` order, as the
+* built-in stores do: `limit` within 1 to 200 (50 when absent), `cursor` from
+* the previous page's `next`, and no items for a cursor that does not parse.
+* A custom `ApprovalStore` that filters in memory returns it from `list`.
+*/
+function pageApprovals(matching, query) {
+	const after = query.cursor === void 0 ? void 0 : decodeApprovalCursor(query.cursor);
+	if (after === null) return { items: [] };
+	const sorted = matching.filter((request) => after === void 0 || compare(positionOf(request), after) > 0).toSorted((a, b) => compare(positionOf(a), positionOf(b)));
+	const size = approvalPageSize(query.limit);
+	const items = sorted.slice(0, size);
+	const last = items.at(-1);
+	return sorted.length > size && last !== void 0 ? {
+		items,
+		next: encodeApprovalCursor(last)
+	} : { items };
+}
+/** Every matching request of `store`, following `next` until the last page (at most 1000 pages of 200). */
+function listAllApprovals(store, filter) {
+	const collect = async (cursor, pages, items) => {
+		const page = await store.list(cursor === void 0 ? {
+			...filter,
+			limit: MAX_PAGE_SIZE
+		} : {
+			...filter,
+			limit: MAX_PAGE_SIZE,
+			cursor
+		});
+		const next = [...items, ...page.items];
+		return page.next === void 0 || pages + 1 >= MAX_PAGES ? next : collect(page.next, pages + 1, next);
+	};
+	return collect(void 0, 0, []);
+}
+//#endregion
+//#region src/approvals/store.ts
+function tenantOf(request) {
+	return request.subject.principal?.tenant;
+}
+function membershipTenants(subject) {
+	const principal = subject.principal;
+	if (principal === null) return [];
+	const tenants = /* @__PURE__ */ new Set();
+	if (principal.tenant !== void 0) tenants.add(principal.tenant);
+	for (const membership of principal.memberships ?? []) {
+		const tenant = rootMembershipId(membership);
+		if (tenant !== void 0) tenants.add(tenant);
+	}
+	return [...tenants];
+}
+function belongsToTenant(subject, tenant) {
+	return membershipTenants(subject).includes(tenant);
+}
+function holdsRole(subject, role, tenant) {
+	const principal = subject.principal;
+	if (principal === null) return false;
+	if ((principal.roles ?? []).includes(role)) return true;
+	for (const membership of principal.memberships ?? []) {
+		if (!membership.roles.includes(role)) continue;
+		if (tenant !== void 0 && rootMembershipId(membership) !== tenant) continue;
+		return true;
+	}
+	return false;
+}
+function matchesApprovers(by, subject, tenant, now, facts) {
+	const items = flattenApprovers(by);
+	if (items.length === 0) return false;
+	for (const item of items) {
+		if (item.kind === "any-of") {
+			if (!item.of.some((entry) => matchesApprovers(entry, subject, tenant, now, facts))) return false;
+			continue;
+		}
+		if (item.kind === "permission") {
+			if (!facts.permissions.has(item.permission)) return false;
+			continue;
+		}
+		if (item.kind === "role") {
+			if (!holdsRole(subject, item.role, tenant)) return false;
+			continue;
+		}
+		if (item.kind === "user") {
+			if (subject.principal?.id !== item.id) return false;
+			continue;
+		}
+		if (item.kind === "relation") {
+			if (!facts.relations.has(approverRelationKey(item))) return false;
+			continue;
+		}
+		const result = matchGrantee(item, subject, now, void 0);
+		if (!result.matched || result.where !== void 0) return false;
+	}
+	return true;
+}
+/** Approvals recorded per stage index. */
+function stageCounts(approvals, stages) {
+	const counts = stages.map(() => 0);
+	for (const item of approvals ?? []) if (item.stage !== void 0 && item.stage < counts.length) counts[item.stage] = (counts[item.stage] ?? 0) + 1;
+	return counts;
+}
+function isComplete(request, approvals) {
+	const stages = request.approvers?.stages;
+	if (stages === void 0) return approvals.length >= approvalQuorum(request);
+	const counts = stageCounts(approvals, stages);
+	return stages.every((stage, index) => (counts[index] ?? 0) >= (stage.quorum ?? 1));
+}
+function matchesFilter(request, filter) {
+	if (filter.status !== void 0 && request.status !== filter.status) return false;
+	if (filter.principalId !== void 0 && request.subject.principal?.id !== filter.principalId) return false;
+	if (filter.actorId !== void 0 && request.subject.actor?.id !== filter.actorId) return false;
+	if (filter.tenant !== void 0 && tenantOf(request) !== filter.tenant) return false;
+	if (filter.session !== void 0 && request.subject.session !== filter.session) return false;
+	return true;
+}
+function assertSeparateApprover(request, by, requireDistinctApprover) {
+	const principal = by.principal;
+	if (principal === null) throw new ApprovalError("approver-unauthenticated", "approver must be authenticated");
+	if (request.subject.actor !== void 0 && principal.id === request.subject.actor.id) throw new ApprovalError("approver-is-actor", "approver is the actor of this request");
+	if ((requireDistinctApprover || request.approvers?.distinct !== false) && request.subject.principal !== null && principal.id === request.subject.principal.id) throw new ApprovalError("approver-is-principal", "approver is the principal of this request");
+	return principal;
+}
+function assertNotRepeated(request, id) {
+	if ((request.approvals ?? []).some((item) => item.by === id)) throw new ApprovalError("approver-repeated", "approver has already approved this request");
+}
+function vouchedRule(verdict) {
+	return typeof verdict.vouched === "string" && verdict.vouched !== "" ? verdict.vouched : void 0;
+}
+/**
+* Refuses `by` as an approver of `request`, or returns the index of the
+* stage the approval counts for (`undefined` without `stages`). Eligibility
+* is `approvers.by` or, under `stages`, the first incomplete stage
+* (`sequential`) or any incomplete stage (`all`); `approvers.escalation.to`
+* is eligible too once the request has waited `escalation.after`. A
+* principal who already approved is refused, so one person never completes
+* two stages. `relations` are the relation approvers `by` holds on the
+* request's resource (see `ApprovalVerdict.relations`).
+*/
+function assertApprover(request, by, requireDistinctApprover, now = /* @__PURE__ */ new Date(), relations = [], permissions = []) {
+	const principal = assertSeparateApprover(request, by, requireDistinctApprover);
+	const tenant = request.subject.principal?.tenant;
+	if (tenant !== void 0 && !belongsToTenant(by, tenant)) throw new ApprovalError("approver-not-eligible", "approver does not belong to the request tenant");
+	assertNotRepeated(request, principal.id);
+	const approvers = request.approvers;
+	if (approvers === void 0) return;
+	const facts = {
+		relations: new Set(relations),
+		permissions: new Set(permissions)
+	};
+	const instant = now.getTime() / 1e3;
+	const eligible = (target) => matchesApprovers(target, by, tenant, instant, facts);
+	const stageEscalated = (stage) => {
+		const openAt = stageEscalationOpenAt(request, stage);
+		return stage.escalation !== void 0 && openAt !== void 0 && now.getTime() >= openAt && eligible(stage.escalation.to);
+	};
+	const openAt = escalationOpenAt(request);
+	const escalated = approvers.escalation !== void 0 && openAt !== void 0 && now.getTime() >= openAt && eligible(approvers.escalation.to);
+	const stages = approvers.stages;
+	if (stages === void 0) {
+		if (escalated || approvers.by !== void 0 && eligible(approvers.by)) return;
+		throw new ApprovalError("approver-not-eligible", "approver does not hold an eligible role");
+	}
+	const counts = stageCounts(request.approvals, stages);
+	const open = stages.flatMap((stage, index) => (counts[index] ?? 0) < (stage.quorum ?? 1) ? [index] : []);
+	const candidates = approvers.mode === "sequential" ? open.slice(0, 1) : open;
+	for (const index of candidates) {
+		const stage = stages[index];
+		if (stage !== void 0 && (escalated || eligible(stage.by) || stageEscalated(stage))) return index;
+	}
+	throw new ApprovalError("approver-not-eligible", approvers.mode === "sequential" ? "approver is not eligible for the current stage" : "approver is not eligible for an open stage");
+}
+function isSystemSubject(by) {
+	return by.actor?.kind === "system";
+}
+/**
+* The request after `verdict`, for a store to persist: a rejection resolves
+* it; an approval is appended to `approvals` and resolves it once there are
+* `approvers.quorum` (default 1). Throws an `ApprovalError` when the request
+* is not pending, has expired or `verdict.by` may not approve it. Stores
+* should write the result only when the stored row is still pending with the
+* same number of approvals, so two approvers racing both count.
+*/
+function applyApprovalVerdict(request, verdict, now = /* @__PURE__ */ new Date()) {
+	const principal = verdict.by.principal;
+	if (principal === null) throw new ApprovalError("approver-unauthenticated", "approver must be authenticated");
+	if (request.status !== "pending") throw new ApprovalError("approval-not-pending", "approval is not pending");
+	if (Date.parse(request.expiresAt) <= now.getTime()) throw new ApprovalError("approval-expired", "approval has expired");
+	const vouched = vouchedRule(verdict);
+	const stage = verdict.status === "rejected" && isSystemSubject(verdict.by) || vouched !== void 0 ? void 0 : assertApprover(request, verdict.by, false, now, verdict.relations, verdict.permissions);
+	if (vouched !== void 0) assertNotRepeated(request, assertSeparateApprover(request, verdict.by, false).id);
+	if (verdict.status === "rejected") return freezeDeep(compact({
+		...request,
+		status: "rejected",
+		resolvedAt: now.toISOString(),
+		resolvedBy: principal.id,
+		vouched,
+		note: verdict.note ?? request.note
+	}));
+	const approvals = [...request.approvals ?? [], compact({
+		by: principal.id,
+		at: now.toISOString(),
+		stage,
+		vouched
+	})];
+	if (vouched === void 0 && !isComplete(request, approvals)) return freezeDeep(compact({
+		...request,
+		approvals,
+		note: verdict.note ?? request.note
+	}));
+	return freezeDeep(compact({
+		...request,
+		status: "approved",
+		approvals,
+		resolvedAt: now.toISOString(),
+		resolvedBy: principal.id,
+		vouched,
+		note: verdict.note ?? request.note
+	}));
+}
+function rejectPending(request, meta, now) {
+	return freezeDeep(compact({
+		...request,
+		status: "rejected",
+		resolvedAt: now.toISOString(),
+		resolvedBy: `system:${meta.by}`,
+		note: meta.note
+	}));
+}
+/** A request a new ask may replace: expired, or past its deadline. */
+function isStale(request, now) {
+	return request.status === "expired" || Date.parse(request.expiresAt) <= now.getTime();
+}
+function memoryApprovalStore(options = {}) {
+	const ttl = options.ttl ?? 36e5;
+	const records = /* @__PURE__ */ new Map();
+	return {
+		ttl,
+		create(request) {
+			const current = records.get(request.token);
+			if (current !== void 0 && !isStale(current, /* @__PURE__ */ new Date())) return;
+			records.set(request.token, freezeDeep(request));
+		},
+		get(token) {
+			return records.get(token) ?? null;
+		},
+		resolve(token, verdict) {
+			const current = records.get(token);
+			if (current === void 0) throw new ApprovalError("approval-not-found", "approval was not found");
+			const next = applyApprovalVerdict(current, verdict, /* @__PURE__ */ new Date());
+			records.set(token, next);
+			return next;
+		},
+		consume(token, now = /* @__PURE__ */ new Date()) {
+			const current = records.get(token);
+			if (current?.status !== "approved" || current.consumedAt !== void 0 || Date.parse(current.expiresAt) <= now.getTime()) return null;
+			const next = freezeDeep({
+				...current,
+				consumedAt: now.toISOString()
+			});
+			records.set(token, next);
+			return next;
+		},
+		list(query) {
+			const matching = [];
+			for (const request of records.values()) if (matchesFilter(request, query)) matching.push(request);
+			return pageApprovals(matching, query);
+		},
+		expire(now = /* @__PURE__ */ new Date()) {
+			let count = 0;
+			const instant = now.getTime();
+			for (const [token, request] of records) {
+				const deadline = Date.parse(request.expiresAt);
+				if (request.status !== "pending" && deadline + ttl <= instant) {
+					records.delete(token);
+					continue;
+				}
+				if (request.status === "pending" && deadline <= instant) {
+					records.set(token, freezeDeep(compact({
+						...request,
+						status: "expired"
+					})));
+					count += 1;
+				}
+			}
+			return count;
+		},
+		cancel(filter, meta) {
+			const now = /* @__PURE__ */ new Date();
+			let count = 0;
+			for (const [token, request] of records) {
+				if (request.status !== "pending" || !matchesFilter(request, filter)) continue;
+				records.set(token, rejectPending(request, meta, now));
+				count += 1;
+			}
+			return count;
+		}
+	};
+}
+//#endregion
+export { decodeApprovalCursor as a, pageApprovals as c, approvalQuorum as d, approverRelationKey as f, approvalPageSize as i, APPROVAL_HEADER as l, assertApprover as n, encodeApprovalCursor as o, escalationOpenAt as p, memoryApprovalStore as r, listAllApprovals as s, applyApprovalVerdict as t, DEFAULT_APPROVAL_TTL_MS as u };

package/dist/store-D_pjn91-.d.ts

@@ -0,0 +1,36 @@
+import { Tt as Snapshot, Yn as Decision } from "./policy-CFZAr_Al.js";
+import { f as Permission } from "./permissions-DttnqqxC.js";
+import { n as ApprovalState, r as ClientPermDock, s as PermissionState } from "./types-kxznc7cn.js";
+//#region src/client/store.d.ts
+type ClientStore = {
+  get(): ClientPermDock;
+  subscribe(listener: () => void): () => void;
+  permissionState(permission: Permission, data?: unknown): PermissionState;
+  requestApproval(decision: Decision, note?: string): Promise<void>;
+  /** Hydrate from a pushed snapshot; a compact JWS goes through the verifier. */
+  replace(value: unknown): void;
+  /** Stay `pending` until `value` settles, then hydrate; a rejection fails closed. */
+  follow(value: PromiseLike<Snapshot | string>): void;
+  /**
+   * `follow()` once per `value`, without suspending. A thenable React already
+   * settled (`status: 'fulfilled'`) hydrates at once.
+   */
+  track(value: PromiseLike<Snapshot | string>): void;
+  /**
+   * The approval state for a decision. While something subscribes, an
+   * `approval-required` decision is polled at `<approvals>/<token>`.
+   */
+  approvalState(decision: Decision): ApprovalState;
+  /**
+   * Hydrate from a resolved `snapshotPromise` during render. Idempotent per `source`;
+   * subscribers are notified in a microtask, never synchronously inside render.
+   */
+  adopt(value: Snapshot | string, source: object): void;
+  snapshot(): Snapshot;
+  /** The tenant the store currently answers for. */
+  tenant(): string | undefined;
+  /** Stops polls, drops in-flight results and persistence; the store keeps answering from its last snapshot. */
+  dispose(): void;
+};
+//#endregion
+export { ClientStore as t };