permdock 0.4.0 → 0.6.0

package/dist/approvals-p1PGoVjb.js

@@ -0,0 +1,995 @@
+import { t as compact } from "./compact-CAf557ZB.js";
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+import { a as ownRecord } from "./paths-DXSHAMIa.js";
+import { a as problemType, o as statusProblem } from "./problem-details-cn5X30gZ.js";
+import { a as isId } from "./expiry-D4_YKRKD.js";
+import { d as isoNow, f as nowMillis, g as secondsOf, i as dateAt } from "./time-DkWjdL98.js";
+import { t as canonicalJson } from "./canonical-json-BC8_nMTw.js";
+import { r as sha256Digest } from "./sha256-D9ihqmvd.js";
+import { s as rootMembershipId } from "./scopes-CUPSjo9q.js";
+import { o as flattenGrantee } from "./grantee-hxrUsbpM.js";
+import { c as isApprovalError, s as ApprovalError } from "./types-DqzsnlSA.js";
+import { a as approvalPageSize, c as listAllApprovals, n as assertApprover, o as decodeApprovalCursor, r as matchesApprovers } from "./store-BDutJkDL.js";
+import { n as readBodyText } from "./body-text-QcXok_SI.js";
+import { r as hasCredentials } from "./http-BBoKefeS.js";
+import { a as methodNotAllowed, c as problemResponse, d as validationProblem, u as unauthenticatedProblem } from "./problem-CTviyH5L.js";
+import { f as approverPermissions, m as approverRelations, p as heldPermissions } from "./helpers-CBYVMjwh.js";
+import { n as isAccessReviewError, t as AccessReviewError } from "./errors-BDUwg2qC.js";
+import { t as bodyTooLarge } from "./body-CH5of8Ne.js";
+//#region src/approvals/access-reviews/decide.ts
+/** Whether `by` is named as a reviewer. A link, a feed or a contact is never a reviewer. */
+function accessReviewerEligible(review, by, permissions = [], now) {
+	const principal = by.principal;
+	if (principal === null || principal.kind === "link" || principal.kind === "feed" || principal.kind === "contact") return false;
+	return matchesApprovers(review.reviewers, by, review.tenant, dateAt(now).getTime() / 1e3, {
+		relations: /* @__PURE__ */ new Set(),
+		permissions: new Set(permissions)
+	});
+}
+/**
+* The decision to persist, or throws. A reviewer cannot decide a holding
+* of their own principal. `holder()` matches only through `permissions`.
+*/
+function decideAccessReviewItem(review, item, verdict, at) {
+	const now = dateAt(at);
+	if (review.status !== "open") throw new AccessReviewError("review-closed", "access review is closed");
+	if (item.review !== review.id) throw new AccessReviewError("item-not-found", "item does not belong to the review");
+	if (item.status !== "pending") throw new AccessReviewError("item-not-pending", "item is already decided");
+	const principal = verdict.by.principal;
+	if (principal === null) throw new AccessReviewError("reviewer-unauthenticated", "reviewer must be authenticated");
+	if (principal.id === item.principal) throw new AccessReviewError("reviewer-is-holder", "reviewer cannot decide their own access");
+	if (!accessReviewerEligible(review, verdict.by, verdict.permissions ?? [], { epochMilliseconds: now.getTime() })) throw new AccessReviewError("reviewer-not-eligible", "reviewer is not eligible for this review");
+	return {
+		status: verdict.status,
+		decidedBy: principal.id,
+		decidedAt: now.toISOString(),
+		...verdict.note === void 0 ? {} : { note: verdict.note }
+	};
+}
+//#endregion
+//#region src/approvals/access-reviews/handler.ts
+function problem$1(status, detail) {
+	return problemResponse(statusProblem(status, detail));
+}
+function json$1(status, body) {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "content-type": "application/json" }
+	});
+}
+/** The route a path names, the methods it allows, or `undefined` for an unknown path. */
+function parseRoute$1(url, method) {
+	const parts = url.pathname.replace(/\/+$/u, "").split("/").filter(Boolean);
+	const last = parts.at(-1);
+	const prev = parts.at(-2);
+	const review = parts.at(-3);
+	if (last === void 0) return;
+	if (last === "items" && prev !== void 0) return method === "GET" ? {
+		kind: "items",
+		id: decodeURIComponent(prev)
+	} : { allow: "GET" };
+	if (last === "close" && prev !== void 0) return method === "POST" ? {
+		kind: "close",
+		id: decodeURIComponent(prev)
+	} : { allow: "POST" };
+	if ((last === "keep" || last === "revoke" || last === "applied") && prev !== void 0 && review !== void 0) return method === "POST" ? {
+		kind: last,
+		id: decodeURIComponent(review),
+		item: decodeURIComponent(prev)
+	} : { allow: "POST" };
+	return method === "GET" ? {
+		kind: "get",
+		id: decodeURIComponent(last)
+	} : { allow: "GET" };
+}
+async function resolveSubject$1(request, resolve) {
+	try {
+		return await resolve(request) ?? null;
+	} catch {
+		return null;
+	}
+}
+const MAX_NOTE = 2e3;
+const MAX_NOTE_BODY_BYTES = 16384;
+async function readNote$1(request) {
+	if (!(request.headers.get("content-type") ?? "").includes("application/json")) return;
+	const read = await readBodyText(request, MAX_NOTE_BODY_BYTES);
+	if (!read.ok) return;
+	try {
+		const body = JSON.parse(read.text);
+		if (body !== null && typeof body === "object" && "note" in body && typeof body.note === "string" && body.note.length <= MAX_NOTE) return body.note;
+	} catch {
+		return;
+	}
+}
+async function findItem(store, review, id) {
+	let cursor;
+	for (let page = 0; page < 1e3; page += 1) {
+		const listed = await store.items(cursor === void 0 ? {
+			review,
+			limit: 200
+		} : {
+			review,
+			limit: 200,
+			cursor
+		});
+		const found = listed.items.find((entry) => entry.id === id);
+		if (found !== void 0 || listed.next === void 0) return found;
+		cursor = listed.next;
+	}
+}
+function mapError$1(error, credentials) {
+	if (!isAccessReviewError(error)) return problem$1(500, "access review store failed");
+	if (error.code === "review-not-found" || error.code === "item-not-found") return problem$1(404, error.message);
+	if (error.code === "review-closed" || error.code === "item-not-pending" || error.code === "not-revoked" || error.code === "already-applied") return problem$1(409, error.message);
+	if (error.code === "reviewer-unauthenticated") return unauthenticatedProblem(credentials);
+	return problemResponse({
+		type: problemType("denied"),
+		title: "Permission denied",
+		status: 403,
+		detail: error.message
+	});
+}
+/**
+* HTTP for one access-review store: `GET` a review and its items, `POST`
+* `.../keep`, `.../revoke`, `.../applied` and `.../close`. A caller who is
+* not a reviewer and did not open the review gets 404.
+*/
+function accessReviewsHandler(store, options) {
+	return async (request) => {
+		const url = new URL(request.url);
+		const route = parseRoute$1(url, request.method);
+		if (route === void 0) return problem$1(404, "unknown access review route");
+		if ("allow" in route) return methodNotAllowed(route.allow);
+		const subject = await resolveSubject$1(request, options.subject);
+		const principal = subject?.principal ?? null;
+		if (subject === null || principal === null) return unauthenticatedProblem(hasCredentials(request));
+		try {
+			const review = await store.get(route.id);
+			if (review === null) return problem$1(404, "access review was not found");
+			let held = [];
+			if (options.permdockFor !== void 0) held = approverPermissions({
+				v: 1,
+				id: review.id,
+				token: review.id,
+				permission: review.permissions[0] ?? "",
+				scope: "",
+				resource: {
+					type: "access-review",
+					id: review.id
+				},
+				subject: { principal: {
+					id: review.createdBy,
+					roles: [],
+					tenant: review.tenant
+				} },
+				detail: "",
+				createdAt: review.createdAt,
+				expiresAt: review.dueAt,
+				status: "pending",
+				approvers: { by: review.reviewers }
+			}, await options.permdockFor(subject, review.tenant));
+			if (review.createdBy !== principal.id && !accessReviewerEligible(review, subject, held)) return problem$1(404, "access review was not found");
+			if (route.kind === "get") return json$1(200, review);
+			if (route.kind === "items") {
+				const limit = url.searchParams.get("limit");
+				const cursor = url.searchParams.get("cursor");
+				const status = url.searchParams.get("status");
+				return json$1(200, await store.items(compact({
+					review: route.id,
+					limit: limit === null ? void 0 : Number(limit),
+					cursor: cursor ?? void 0,
+					status: status === "pending" || status === "kept" || status === "revoked" ? status : void 0
+				})));
+			}
+			if (route.kind === "close") return json$1(200, await store.close(route.id));
+			const item = await findItem(store, route.id, route.item);
+			if (item === void 0) return problem$1(404, "item was not found");
+			if (route.kind === "applied") return json$1(200, await store.markApplied(route.id, route.item, isoNow()));
+			const note = await readNote$1(request);
+			const decision = decideAccessReviewItem(review, item, {
+				status: route.kind === "keep" ? "kept" : "revoked",
+				by: subject,
+				...note === void 0 ? {} : { note },
+				permissions: held
+			});
+			return json$1(200, await store.decide(route.id, route.item, decision));
+		} catch (error) {
+			return mapError$1(error, hasCredentials(request));
+		}
+	};
+}
+//#endregion
+//#region src/approvals/access-reviews/start.ts
+function itemId(review, principal, permission) {
+	return `${review}:${principal}:${permission}`;
+}
+function populationComplete(policy, keys) {
+	if (policy === void 0) return false;
+	for (const grant of policy.grants) {
+		if (grant.effect !== "allow" || !keys.has(grant.permission.key)) continue;
+		if (!enumerable(grant)) return false;
+	}
+	return true;
+}
+function enumerable(grant) {
+	for (const item of flattenGrantee(grant.to)) {
+		if (item.kind === "plan" || item.kind === "relation" || item.kind === "inherit") return false;
+		if (item.kind === "role" && item.scope === "global") return false;
+	}
+	return true;
+}
+async function fromMembers(tenant, keys, options) {
+	const source = options.memberships;
+	const permdockFor = options.permdockFor;
+	const keySet = new Set(keys.map((permission) => permission.key));
+	if (source?.list === void 0 || permdockFor === void 0) return {
+		holders: [],
+		complete: false
+	};
+	try {
+		const members = await source.list({
+			scope: options.scope ?? "tenant",
+			id: tenant
+		});
+		return {
+			holders: (await Promise.all(members.map(async (member) => {
+				const instance = await permdockFor(member.principal.id);
+				const via = member.membership.roles;
+				return keys.flatMap((permission) => {
+					const decide = instance.decide;
+					return decide(permission).outcome === "granted" ? [{
+						principal: member.principal.id,
+						permission: permission.key,
+						via
+					}] : [];
+				});
+			}))).flat(),
+			complete: populationComplete(options.policy, keySet)
+		};
+	} catch {
+		return {
+			holders: [],
+			complete: false
+		};
+	}
+}
+function itemsFrom(reviewId, holders, keys) {
+	const seen = /* @__PURE__ */ new Set();
+	const items = [];
+	for (const holder of holders) {
+		if (!keys.has(holder.permission) || holder.principal.length === 0) continue;
+		const id = itemId(reviewId, holder.principal, holder.permission);
+		if (seen.has(id)) continue;
+		seen.add(id);
+		items.push({
+			v: 1,
+			id,
+			review: reviewId,
+			principal: holder.principal,
+			permission: holder.permission,
+			via: holder.via,
+			status: "pending"
+		});
+	}
+	return items;
+}
+/**
+* Opens a review of who holds `permissions` in the caller's active tenant.
+* The caller must be signed in. PermDock stores the population and does not
+* revoke anything: the application changes the source, then `markApplied`.
+*/
+async function startAccessReview(permdock, input, options) {
+	const principal = permdock.subject.principal;
+	const tenant = principal?.tenant;
+	if (principal === null || tenant === void 0) throw new AccessReviewError("reviewer-unauthenticated", "access review needs a tenant member");
+	if (input.permissions.length === 0 || !Number.isFinite(Date.parse(input.dueAt))) throw new TypeError("PermDock: an access review needs permissions and a due date");
+	const keys = new Set(input.permissions.map((permission) => permission.key));
+	const now = dateAt(options.now);
+	const listed = options.holders === void 0 ? await fromMembers(tenant, input.permissions, options) : {
+		holders: options.holders,
+		complete: options.complete ?? true
+	};
+	const review = {
+		v: 1,
+		id: input.id,
+		tenant,
+		permissions: [...keys],
+		reviewers: input.reviewers,
+		createdBy: principal.id,
+		createdAt: now.toISOString(),
+		dueAt: input.dueAt,
+		status: "open",
+		complete: listed.complete
+	};
+	await options.reviews.create(review, itemsFrom(input.id, listed.holders, keys));
+	return review;
+}
+//#endregion
+//#region src/approvals/access-reviews/store.ts
+function position(item) {
+	return [item.principal, item.id];
+}
+function compare(left, right) {
+	if (left[0] !== right[0]) return left[0] < right[0] ? -1 : 1;
+	if (left[1] === right[1]) return 0;
+	return left[1] < right[1] ? -1 : 1;
+}
+/** Pages items in `(principal, id)` order with the approval cursor codec. */
+function pageAccessReviewItems(matching, query) {
+	const after = query.cursor === void 0 ? void 0 : decodeApprovalCursor(query.cursor);
+	if (after === null) return { items: [] };
+	const sorted = matching.filter((item) => after === void 0 || compare(position(item), after) > 0).toSorted((left, right) => compare(position(left), position(right)));
+	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: JSON.stringify(position(last))
+	} : { items };
+}
+function requireOpen(review) {
+	if (review.status !== "open") throw new AccessReviewError("review-closed", "access review is closed");
+}
+/** In-process access reviews for tests and single-replica apps. */
+function memoryAccessReviewStore() {
+	const records = /* @__PURE__ */ new Map();
+	const load = (id) => {
+		const recorded = records.get(id);
+		if (recorded === void 0) throw new AccessReviewError("review-not-found", "access review was not found");
+		return recorded;
+	};
+	return Object.freeze({
+		reviews: () => [...records.values()].map((recorded) => recorded.review),
+		create(review, items) {
+			if (records.has(review.id)) return;
+			const byId = /* @__PURE__ */ new Map();
+			for (const item of items) {
+				if (item.review !== review.id) throw new AccessReviewError("item-not-found", "item does not belong to the review");
+				byId.set(item.id, item);
+			}
+			records.set(review.id, {
+				review: freezeDeep(review),
+				items: byId
+			});
+		},
+		get(id) {
+			return records.get(id)?.review ?? null;
+		},
+		items(query) {
+			const recorded = records.get(query.review);
+			if (recorded === void 0) return { items: [] };
+			return pageAccessReviewItems([...recorded.items.values()].filter((item) => query.status === void 0 || item.status === query.status), query);
+		},
+		decide(reviewId, itemId, decision) {
+			const recorded = load(reviewId);
+			requireOpen(recorded.review);
+			const current = recorded.items.get(itemId);
+			if (current === void 0) throw new AccessReviewError("item-not-found", "item was not found");
+			if (current.status !== "pending") throw new AccessReviewError("item-not-pending", "item is already decided");
+			const next = freezeDeep({
+				...current,
+				status: decision.status,
+				decidedBy: decision.decidedBy,
+				decidedAt: decision.decidedAt,
+				...decision.note === void 0 ? {} : { note: decision.note }
+			});
+			recorded.items.set(itemId, next);
+			return next;
+		},
+		markApplied(reviewId, itemId, at) {
+			const recorded = load(reviewId);
+			const current = recorded.items.get(itemId);
+			if (current === void 0) throw new AccessReviewError("item-not-found", "item was not found");
+			if (current.status !== "revoked") throw new AccessReviewError("not-revoked", "only a revoked holding can be marked applied");
+			if (current.appliedAt !== void 0) throw new AccessReviewError("already-applied", "holding is already marked applied");
+			const next = freezeDeep({
+				...current,
+				appliedAt: at
+			});
+			recorded.items.set(itemId, next);
+			return next;
+		},
+		close(id) {
+			const recorded = load(id);
+			requireOpen(recorded.review);
+			const next = freezeDeep({
+				...recorded.review,
+				status: "closed"
+			});
+			records.set(id, {
+				review: next,
+				items: recorded.items
+			});
+			return next;
+		}
+	});
+}
+//#endregion
+//#region src/approvals/delegation.ts
+function isInstant(value) {
+	return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+function stringList(value) {
+	if (!Array.isArray(value) || value.length === 0 || value.length > 64 || !value.every(isId)) return;
+	return [...new Set(value)];
+}
+/**
+* A frozen copy of a delegation with only the known fields, or `undefined`
+* when a known field has the wrong type, `until` is not after `from`, or
+* the delegate and the delegator are the same principal.
+*/
+function parseApprovalDelegation(input) {
+	const value = ownRecord(input);
+	if (value === void 0) return;
+	if (!isId(value["id"]) || !isId(value["delegator"]) || !isId(value["delegate"]) || value["delegator"] === value["delegate"]) return;
+	if (!isInstant(value["from"]) || !isInstant(value["until"])) return;
+	if (Date.parse(value["from"]) >= Date.parse(value["until"])) return;
+	if (value["tenant"] !== void 0 && !isId(value["tenant"])) return;
+	const permissions = value["permissions"] === void 0 ? void 0 : stringList(value["permissions"]);
+	if (value["permissions"] !== void 0 && permissions === void 0) return;
+	const resources = value["resources"] === void 0 ? void 0 : stringList(value["resources"]);
+	if (value["resources"] !== void 0 && resources === void 0) return;
+	const tenant = value["tenant"];
+	return freezeDeep({
+		id: value["id"],
+		delegator: value["delegator"],
+		delegate: value["delegate"],
+		...typeof tenant === "string" ? { tenant } : {},
+		...permissions === void 0 ? {} : { permissions },
+		...resources === void 0 ? {} : { resources },
+		from: value["from"],
+		until: value["until"]
+	});
+}
+/** In-process delegations. An entry that does not parse is dropped. */
+function memoryApprovalDelegationSource(entries) {
+	const stored = entries.flatMap((entry) => {
+		const parsed = parseApprovalDelegation(entry);
+		return parsed === void 0 ? [] : [parsed];
+	});
+	return Object.freeze({ delegationsFor(query) {
+		const at = Date.parse(query.at);
+		if (!Number.isFinite(at)) return [];
+		return stored.filter((entry) => {
+			if (entry.delegate !== query.delegate) return false;
+			if (query.tenant === void 0) {
+				if (entry.tenant !== void 0) return false;
+			} else if (entry.tenant !== void 0 && entry.tenant !== query.tenant) return false;
+			return Date.parse(entry.from) <= at && at < Date.parse(entry.until);
+		});
+	} });
+}
+function inTenant(subject, tenant) {
+	if (tenant === void 0) return true;
+	const principal = subject.principal;
+	if (principal === null) return false;
+	if (principal.tenant === tenant) return true;
+	return (principal.memberships ?? []).some((membership) => rootMembershipId(membership) === tenant);
+}
+function covers(entry, request, delegate, tenant, at) {
+	if (entry.delegate !== delegate || entry.delegator === delegate) return false;
+	if (Date.parse(entry.from) > at || !(at < Date.parse(entry.until))) return false;
+	if (entry.tenant !== void 0 && entry.tenant !== tenant) return false;
+	if (entry.permissions !== void 0 && !entry.permissions.includes(request.permission)) return false;
+	return entry.resources === void 0 || entry.resources.includes(request.resource.type);
+}
+/**
+* The first active delegation under which `delegate` may approve `request`,
+* or `undefined`. The delegator is resolved by `subjectFor` and checked with
+* `assertApprover`, so relation and permission approvers use the delegator's
+* facts. A throw, a missing option or a delegator the source does not name
+* matches nobody. The delegator's own delegations are never read.
+*/
+async function matchDelegation(request, delegate, options) {
+	const principal = delegate.principal;
+	const source = options.approvalDelegations;
+	const subjectFor = options.subjectFor;
+	if (principal === null || principal.kind === "link" || principal.kind === "feed" || principal.kind === "contact" || source === void 0 || subjectFor === void 0) return;
+	const now = dateAt(options.now);
+	const tenant = request.subject.principal?.tenant;
+	if (!inTenant(delegate, tenant)) return;
+	let listed;
+	try {
+		listed = await source.delegationsFor({
+			delegate: principal.id,
+			...tenant === void 0 ? {} : { tenant },
+			at: now.toISOString()
+		});
+	} catch {
+		return;
+	}
+	if (!Array.isArray(listed)) return;
+	const at = now.getTime();
+	return (await Promise.all(listed.map(async (raw) => {
+		const entry = parseApprovalDelegation(raw);
+		if (entry === void 0 || !covers(entry, request, principal.id, tenant, at)) return;
+		try {
+			const resolved = await subjectFor(entry.delegator, request);
+			if (resolved === null || resolved === void 0 || resolved.principal === null || resolved.principal.id !== entry.delegator || resolved.principal.kind === "link" || resolved.principal.kind === "feed" || resolved.principal.kind === "contact") return;
+			const facts = await options.factsFor(resolved);
+			assertApprover(request, resolved, options.requireDistinct, { epochMilliseconds: now.getTime() }, facts.relations, facts.permissions);
+			return {
+				delegation: entry,
+				delegator: resolved,
+				relations: facts.relations,
+				permissions: facts.permissions
+			};
+		} catch {
+			return;
+		}
+	}))).find((match) => match !== void 0);
+}
+//#endregion
+//#region src/approvals/idempotency.ts
+/** An in-process `IdempotencyStore`, for one instance and for tests. */
+function memoryIdempotencyStore() {
+	const entries = /* @__PURE__ */ new Map();
+	return {
+		get(key) {
+			const entry = entries.get(key);
+			if (entry === void 0) return;
+			if (entry.expiresAt <= nowMillis()) {
+				entries.delete(key);
+				return;
+			}
+			return entry.response;
+		},
+		set(key, response, expiresAt) {
+			entries.set(key, {
+				response,
+				expiresAt
+			});
+		}
+	};
+}
+//#endregion
+//#region src/approvals/signature.ts
+function actionOf(request) {
+	const prefix = `${request.resource.type}.`;
+	return request.permission.startsWith(prefix) ? request.permission.slice(prefix.length) : request.permission.slice(request.permission.lastIndexOf(".") + 1);
+}
+function approvalSignatureClaims(request) {
+	const actor = request.subject.actor;
+	return compact({
+		sub: request.subject.principal?.id,
+		act: actor === void 0 ? void 0 : { sub: actor.id },
+		token: request.token,
+		resolved_by: request.resolvedBy,
+		approvals: (request.approvals ?? []).map((item) => compact({
+			by: item.by,
+			at: item.at,
+			stage: item.stage,
+			vouched: item.vouched,
+			on_behalf_of: item.onBehalfOf,
+			delegation: item.delegation
+		})),
+		authorization_details: [compact({
+			type: request.resource.type,
+			actions: [actionOf(request)],
+			identifier: request.resource.id
+		})]
+	});
+}
+/**
+* Signs an approved request as a `vnd.permdock.approval+jwt`: `jti` is the
+* request id, `iat` its `resolvedAt` and `exp` its `expiresAt`. `undefined`
+* without a signer or for any status but `approved`.
+*/
+function signApproval(request, signer, options = {}) {
+	if (signer === void 0 || request.status !== "approved") return Promise.resolve(void 0);
+	return signer.sign(approvalSignatureClaims(request), compact({
+		typ: "vnd.permdock.approval+jwt",
+		audience: options.audience,
+		jti: request.id,
+		issuedAt: secondsOf(request.resolvedAt),
+		expiresAt: secondsOf(request.expiresAt)
+	}));
+}
+//#endregion
+//#region src/approvals/handler.ts
+const IDEMPOTENCY_TTL_MS = 864e5;
+const MAX_IDEMPOTENCY_KEY_LENGTH = 256;
+function problem(status, detail) {
+	return problemResponse(statusProblem(status, detail));
+}
+function json(status, body, headers = {}) {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: {
+			...headers,
+			"content-type": "application/json"
+		}
+	});
+}
+function viewOf(request) {
+	const { token: _token, ...view } = request;
+	return view;
+}
+/** A strong RFC 9110 entity tag: the `sha-256:` digest of the view's RFC 8785 JSON. */
+function entityTag(request) {
+	return `"${sha256Digest(canonicalJson(viewOf(request)))}"`;
+}
+function entityTags(field) {
+	return field.split(",").map((tag) => tag.trim()).filter((tag) => tag !== "");
+}
+/** RFC 9110 section 13.1.1: strong comparison, so a weak tag never matches. */
+function ifMatchFails(request, current) {
+	const field = request.headers.get("if-match");
+	if (field === null) return false;
+	const tags = entityTags(field);
+	if (tags.includes("*")) return false;
+	return !tags.includes(entityTag(current));
+}
+/** RFC 9110 section 13.1.2: weak comparison. */
+function ifNoneMatchHolds(request, etag) {
+	const field = request.headers.get("if-none-match");
+	if (field === null) return false;
+	return entityTags(field).some((tag) => tag === "*" || tag.replace(/^W\//u, "") === etag);
+}
+function decodeSegment(segment) {
+	try {
+		return decodeURIComponent(segment);
+	} catch {
+		return;
+	}
+}
+/**
+* The route the path names and the methods it allows. The handler mounts at
+* any prefix, so a path reads from its last segments; a path naming none is
+* `undefined` (`404`).
+*/
+function parseRoute(url) {
+	const parts = url.pathname.split("/").filter(Boolean);
+	const last = parts.at(-1);
+	const prev = parts.at(-2);
+	if (last === void 0) return;
+	if (last === "pending" || last === "mine") {
+		const kind = last;
+		return {
+			allow: "GET",
+			route: (method) => method === "GET" ? { kind } : void 0
+		};
+	}
+	if ((last === "approve" || last === "reject" || last === "signature") && prev !== void 0) {
+		const id = decodeSegment(prev);
+		if (id === void 0) return;
+		const kind = last;
+		const method = kind === "signature" ? "GET" : "POST";
+		return {
+			allow: method,
+			route: (requested) => requested === method ? {
+				kind,
+				id
+			} : void 0
+		};
+	}
+	const id = decodeSegment(last);
+	if (id === void 0) return;
+	return {
+		allow: "GET",
+		route: (method) => method === "GET" ? {
+			kind: "get",
+			id
+		} : void 0
+	};
+}
+/** `store.getById`, else the first page run of `list` that carries the id. */
+async function findById(store, id) {
+	if (store.getById !== void 0) return store.getById(id);
+	return (await listAllApprovals(store, {})).find((request) => request.id === id) ?? null;
+}
+/** RFC 8288 `Link: <…>; rel="next"` for a page with a `next` cursor. */
+function nextLink(url, next) {
+	if (next === void 0) return {};
+	const target = new URL(url);
+	target.searchParams.set("cursor", next);
+	return { Link: `<${target.href}>; rel="next"` };
+}
+/** The signature sub-resource beside an `…/<id>/approve` or `…/<id>/reject` URL. */
+function signatureLink(url) {
+	const target = new URL(url);
+	target.search = "";
+	target.pathname = target.pathname.replace(/\/(?:approve|reject)\/*$/u, "/signature");
+	return { Link: `<${target.href}>; rel="alternate"; type="application/jwt"` };
+}
+async function resolveSubject(request, resolve) {
+	try {
+		const subject = await resolve(request);
+		if (subject === null || subject === void 0) return null;
+		return subject;
+	} catch {
+		return null;
+	}
+}
+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);
+}
+async function factsFor(request, subject, options) {
+	return {
+		relations: await approverRelations(request, subject, options),
+		permissions: await heldPermissions(request, subject, options.permdockFor)
+	};
+}
+/** The caller as themselves, or the first delegation that makes them an approver. */
+async function actingApprover(request, subject, requireDistinct, options) {
+	const facts = await factsFor(request, subject, options);
+	try {
+		assertApprover(request, subject, requireDistinct, void 0, facts.relations, facts.permissions);
+		return {
+			kind: "self",
+			...facts
+		};
+	} catch (error) {
+		if (!isApprovalError(error) || error.code !== "approver-not-eligible") throw error;
+	}
+	const match = await matchDelegation(request, subject, {
+		...options.approvalDelegations === void 0 ? {} : { approvalDelegations: options.approvalDelegations },
+		...options.subjectFor === void 0 ? {} : { subjectFor: options.subjectFor },
+		requireDistinct,
+		factsFor: (delegator) => factsFor(request, delegator, options)
+	});
+	if (match === void 0) throw new ApprovalError("approver-not-eligible", "approver does not hold an eligible role");
+	return {
+		kind: "delegated",
+		delegation: match.delegation.id,
+		delegator: match.delegator,
+		relations: match.relations,
+		permissions: match.permissions
+	};
+}
+async function mayResolve(request, subject, requireDistinct, options) {
+	try {
+		await actingApprover(request, subject, requireDistinct, options);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* The requester, a tenant member for a tenant request, and for a request
+* without a tenant only who answered it or may answer it.
+*/
+function canView(request, subject, requireDistinct, options) {
+	const principal = subject.principal;
+	if (principal === null) return Promise.resolve(false);
+	if (request.subject.principal?.id === principal.id) return Promise.resolve(true);
+	const tenant = request.subject.principal?.tenant;
+	if (tenant !== void 0) return Promise.resolve(belongsToTenant(subject, tenant));
+	if (request.resolvedBy === principal.id || (request.approvals ?? []).some((item) => item.by === principal.id)) return Promise.resolve(true);
+	return mayResolve(request, subject, requireDistinct, options);
+}
+/** The requester and who answered: the signed approval carries the resume token, so only they read it. */
+function party(request, principalId) {
+	return request.subject.principal?.id === principalId || request.resolvedBy === principalId || (request.approvals ?? []).some((item) => item.by === principalId);
+}
+/**
+* The tenants whose pending requests the approver may list: the requested one,
+* else the active one, else every membership tenant. Requests without a tenant
+* are listed only when no tenant was requested or active.
+*/
+function pageQuery(url) {
+	const limit = url.searchParams.get("limit");
+	const cursor = url.searchParams.get("cursor");
+	return compact({
+		limit: limit === null ? void 0 : Number(limit),
+		cursor: cursor ?? void 0
+	});
+}
+function inboxScope(url, subject) {
+	const requested = url.searchParams.get("tenant");
+	if (requested !== null && requested !== "") {
+		if (!belongsToTenant(subject, requested)) return { ok: false };
+		return {
+			ok: true,
+			tenants: [requested],
+			tenantless: false
+		};
+	}
+	const active = subject.principal?.tenant;
+	if (active !== void 0) return {
+		ok: true,
+		tenants: [active],
+		tenantless: false
+	};
+	return {
+		ok: true,
+		tenants: membershipTenants(subject),
+		tenantless: true
+	};
+}
+const MAX_BODY_BYTES = 16384;
+const MAX_NOTE_LENGTH = 2e3;
+/** An unreadable body is no note; an oversized body or note is refused, never truncated. */
+async function readNote(request) {
+	if (!(request.headers.get("content-type") ?? "").includes("application/json")) return { text: "" };
+	const read = await readBodyText(request, MAX_BODY_BYTES);
+	if (!read.ok) return read.cause === "too-large" ? {
+		text: "",
+		refusal: bodyTooLarge(MAX_BODY_BYTES)
+	} : { text: "" };
+	const { text } = read;
+	try {
+		const body = JSON.parse(text);
+		if (body !== null && typeof body === "object" && "note" in body && typeof body.note === "string") return body.note.length > MAX_NOTE_LENGTH ? {
+			text,
+			refusal: validationProblem(`note exceeds ${String(MAX_NOTE_LENGTH)} characters`)
+		} : {
+			text,
+			note: body.note
+		};
+	} catch {
+		return { text };
+	}
+	return { text };
+}
+function mapError(error, credentials) {
+	if (!isApprovalError(error)) return problem(500, "approval store failed");
+	switch (error.code) {
+		case "approval-not-found": return problem(404, error.message);
+		case "approval-not-pending":
+		case "approval-expired":
+		case "approver-repeated": return problem(409, error.message);
+		case "approver-unauthenticated": return unauthenticatedProblem(credentials);
+		case "approver-not-eligible":
+		case "approver-is-actor":
+		case "approver-is-principal": return problemResponse({
+			type: problemType("approver-not-eligible"),
+			title: "Approver not eligible",
+			status: 403,
+			detail: error.message,
+			reason: error.code
+		});
+		default: {
+			const unhandled = error.code;
+			return problem(500, `unknown approval error ${String(unhandled)}`);
+		}
+	}
+}
+/** The `Idempotency-Key` field: an RFC 9651 sf-string, 1 to 256 characters. */
+function idempotencyKey(request) {
+	const field = request.headers.get("idempotency-key");
+	if (field === null) return {};
+	const key = /^"([\u0020-\u007E]*)"$/u.exec(field.trim())?.[1];
+	if (key === void 0 || key === "" || key.length > MAX_IDEMPOTENCY_KEY_LENGTH || /["\\]/u.test(key)) return { refusal: validationProblem("Idempotency-Key must be a quoted string of 1 to 256 characters") };
+	return { key };
+}
+async function stored(response, fingerprint) {
+	return {
+		fingerprint,
+		status: response.status,
+		headers: [...response.headers.entries()],
+		body: await response.clone().text()
+	};
+}
+function approvalsHandler(store, options) {
+	const requireDistinct = options.requireDistinctApprover === true;
+	const idempotency = options.idempotency ?? memoryIdempotencyStore();
+	const visible = async (id, subject) => {
+		const current = await findById(store, id);
+		return current !== null && await canView(current, subject, requireDistinct, options) ? current : null;
+	};
+	const resolve = async (request, url, route, subject, read) => {
+		const current = await visible(route.id, subject);
+		if (current === null) return problem(404, "approval was not found");
+		if (ifMatchFails(request, current)) return problem(412, "the approval changed since it was read");
+		const acting = await actingApprover(current, subject, requireDistinct, options);
+		const resolved = await store.resolve(current.token, compact({
+			status: route.kind === "approve" ? "approved" : "rejected",
+			by: subject,
+			note: read.note,
+			relations: acting.kind === "self" ? acting.relations : void 0,
+			permissions: acting.kind === "self" ? acting.permissions : void 0,
+			onBehalfOf: acting.kind === "delegated" ? {
+				subject: acting.delegator,
+				delegation: acting.delegation,
+				relations: acting.relations,
+				permissions: acting.permissions
+			} : void 0
+		}));
+		return json(200, viewOf(resolved), {
+			ETag: entityTag(resolved),
+			...options.signer !== void 0 && resolved.status === "approved" ? signatureLink(url) : {}
+		});
+	};
+	return async (request) => {
+		const url = new URL(request.url);
+		const parsed = parseRoute(url);
+		if (parsed === void 0) return problem(404, "unknown approvals route");
+		const route = parsed.route(request.method);
+		if (route === void 0) return methodNotAllowed(parsed.allow);
+		await store.expire();
+		const subject = await resolveSubject(request, options.subject);
+		const principal = subject?.principal ?? null;
+		if (subject === null || principal === null) return unauthenticatedProblem(hasCredentials(request));
+		try {
+			switch (route.kind) {
+				case "pending": {
+					const scoped = inboxScope(url, subject);
+					if (!scoped.ok) return problemResponse({
+						type: problemType("denied"),
+						title: "Permission denied",
+						status: 403,
+						detail: "approver does not belong to that tenant"
+					});
+					const page = await store.list({
+						...pageQuery(url),
+						status: "pending"
+					});
+					const tenants = new Set(scoped.tenants);
+					const eligible = await Promise.all(page.items.map(async (item) => {
+						const tenant = item.subject.principal?.tenant;
+						return (tenant === void 0 ? scoped.tenantless : tenants.has(tenant)) && await mayResolve(item, subject, requireDistinct, options);
+					}));
+					return json(200, compact({
+						items: page.items.filter((_, index) => eligible[index] === true).map(viewOf),
+						next: page.next
+					}), nextLink(url, page.next));
+				}
+				case "mine": {
+					const page = await store.list({
+						...pageQuery(url),
+						principalId: principal.id
+					});
+					return json(200, compact({
+						items: page.items.map(viewOf),
+						next: page.next
+					}), nextLink(url, page.next));
+				}
+				case "get": {
+					const current = await visible(route.id, subject);
+					if (current === null) return problem(404, "approval was not found");
+					const etag = entityTag(current);
+					if (ifNoneMatchHolds(request, etag)) return new Response(null, {
+						status: 304,
+						headers: { ETag: etag }
+					});
+					return json(200, viewOf(current), { ETag: etag });
+				}
+				case "signature": {
+					const current = await findById(store, route.id);
+					const signed = current === null || !party(current, principal.id) ? void 0 : await signApproval(current, options.signer, compact({ audience: options.audience }));
+					if (signed === void 0) return problem(404, "no signed approval for that request");
+					return new Response(signed, {
+						status: 200,
+						headers: { "content-type": "application/jwt" }
+					});
+				}
+				case "approve":
+				case "reject": {
+					const keyed = idempotencyKey(request);
+					if ("refusal" in keyed) return keyed.refusal;
+					const read = await readNote(request);
+					if (read.refusal !== void 0) return read.refusal;
+					if (keyed.key === void 0) return await resolve(request, url, route, subject, read);
+					const key = `${principal.id}\n${keyed.key}`;
+					const fingerprint = `${route.kind} ${route.id} ${sha256Digest(read.text)}`;
+					const replay = await idempotency.get(key);
+					if (replay !== void 0) return replay.fingerprint === fingerprint ? new Response(replay.body, {
+						status: replay.status,
+						headers: replay.headers.map(([name, value]) => [name, value])
+					}) : problem(422, "Idempotency-Key was used for another request");
+					const response = await resolve(request, url, route, subject, read);
+					if (response.ok) await idempotency.set(key, await stored(response, fingerprint), nowMillis() + IDEMPOTENCY_TTL_MS);
+					return response;
+				}
+				default: return problem(404, `unknown approvals route ${String(route)}`);
+			}
+		} catch (error) {
+			return mapError(error, hasCredentials(request));
+		}
+	};
+}
+//#endregion
+export { matchDelegation as a, memoryAccessReviewStore as c, accessReviewsHandler as d, accessReviewerEligible as f, memoryIdempotencyStore as i, pageAccessReviewItems as l, approvalSignatureClaims as n, memoryApprovalDelegationSource as o, decideAccessReviewItem as p, signApproval as r, parseApprovalDelegation as s, approvalsHandler as t, startAccessReview as u };