permdock 0.1.0 → 0.3.0

package/dist/store-options-ByhZq1jV.js

@@ -0,0 +1,716 @@
+import { t as compact } from "./compact-y6vfu2_f.js";
+import { c as rowIdOf, n as parseSnapshot } from "./snapshot-Enxd0n-s.js";
+import { u as nowSeconds } from "./validity-uOp8UpYn.js";
+import { n as payloadDigest } from "./token-CIWxJOCh.js";
+import { n as fromSnapshot, t as emptySnapshot } from "./from-snapshot-CTLijvdm.js";
+import { t as timeoutSignal } from "./timeout-D51niuQP.js";
+//#region src/client/approvals.ts
+/** Ceiling for the approval poll backoff after a failed status request. */
+const APPROVAL_BACKOFF_CAP_MS = 6e4;
+/** Consecutive failed status requests after which a token is no longer polled. */
+const APPROVAL_MAX_FAILURES = 5;
+const TERMINAL = /* @__PURE__ */ new Set([
+	"approved",
+	"rejected",
+	"expired"
+]);
+function createApprovals(options) {
+	const { interval } = options;
+	const approvals = /* @__PURE__ */ new Map();
+	const polls = /* @__PURE__ */ new Map();
+	const watched = /* @__PURE__ */ new Set();
+	const failures = /* @__PURE__ */ new Map();
+	let epoch = 0;
+	const stop = () => {
+		for (const timer of polls.values()) clearTimeout(timer);
+		polls.clear();
+	};
+	const poll = async (href) => {
+		try {
+			const response = await options.request(href);
+			if (response.status === 404) return "expired";
+			if (response.status >= 400 && response.status < 500) return "refused";
+			if (!response.ok) return;
+			const body = await response.json();
+			return body.status === "pending" || body.status === "approved" || body.status === "rejected" || body.status === "expired" ? body.status : void 0;
+		} catch {
+			return;
+		}
+	};
+	const schedule = (token) => {
+		if (options.disposed() || options.server || options.approvals === void 0 || polls.has(token) || !options.listening()) return;
+		const started = epoch;
+		const href = `${options.approvals.replace(/\/+$/u, "")}/${encodeURIComponent(token)}`;
+		const failed = failures.get(token) ?? 0;
+		const delay = Math.min(interval * 2 ** failed, Math.max(interval, APPROVAL_BACKOFF_CAP_MS));
+		polls.set(token, setTimeout(() => {
+			poll(href).then((answer) => {
+				if (started !== epoch || options.disposed()) return;
+				polls.delete(token);
+				const next = answer === "refused" ? void 0 : answer;
+				if (next !== void 0 && approvals.get(token) !== next) {
+					approvals.set(token, next);
+					options.emit();
+				}
+				const count = answer === void 0 ? (failures.get(token) ?? 0) + 1 : 0;
+				if (count === 0) failures.delete(token);
+				else failures.set(token, count);
+				if (answer === "refused" || count >= APPROVAL_MAX_FAILURES || TERMINAL.has(approvals.get(token) ?? "required")) {
+					watched.delete(token);
+					failures.delete(token);
+				} else schedule(token);
+			});
+		}, delay));
+	};
+	return {
+		state(decision) {
+			if (decision.outcome !== "approval-required") return "not-needed";
+			const current = approvals.get(decision.token) ?? "required";
+			if (TERMINAL.has(current)) watched.delete(decision.token);
+			else {
+				watched.add(decision.token);
+				schedule(decision.token);
+			}
+			return current;
+		},
+		async request(decision, note) {
+			if (decision.outcome !== "approval-required" || options.simulated()) return;
+			const href = options.approvals ?? options.endpoint;
+			if (href === void 0) return;
+			if ((await options.request(href, {
+				permission: decision.grant.permission,
+				token: decision.token,
+				note
+			})).ok && !TERMINAL.has(approvals.get(decision.token) ?? "required")) {
+				approvals.set(decision.token, "pending");
+				options.emit();
+			}
+		},
+		forget() {
+			epoch += 1;
+			stop();
+			approvals.clear();
+			watched.clear();
+			failures.clear();
+		},
+		stop,
+		resume() {
+			for (const token of watched) schedule(token);
+		}
+	};
+}
+//#endregion
+//#region src/client/batch.ts
+const SERVER_ONLY = {
+	outcome: "denied",
+	denials: [{
+		role: null,
+		reason: "opaque-condition"
+	}],
+	alternatives: []
+};
+/** The client has no endpoint to ask (`endpoint: false`, or none given). */
+const NO_ENDPOINT = {
+	outcome: "denied",
+	denials: [{
+		role: null,
+		reason: "server-only"
+	}],
+	alternatives: []
+};
+/** The row's id under the snapshot's id field, or `undefined` for a row without one. */
+function rowId(snapshot, permission, data) {
+	const id = rowIdOf(data, snapshot.ids?.[permission.resource]);
+	return id === "*" ? void 0 : id;
+}
+function cacheKey(snapshot, permission, data) {
+	if (data === void 0) return `${permission.key}:*`;
+	return `${permission.key}:${rowId(snapshot, permission, data) ?? `#${payloadDigest(data)}`}`;
+}
+/** Collects the checks the snapshot cannot answer and posts them as one AuthZEN batch per microtask. */
+function createBatch(options) {
+	const { answers, endpoint } = options;
+	let queued = [];
+	let flushScheduled = false;
+	const flush = async () => {
+		const batch = queued;
+		queued = [];
+		if (batch.length === 0 || endpoint === void 0) return;
+		const started = options.generation();
+		const snapshot = options.snapshot();
+		if (snapshot.simulated === true) {
+			for (const item of batch) answers.set(item.key, {
+				decision: SERVER_ONLY,
+				status: "server-only"
+			});
+			options.emit();
+			return;
+		}
+		const { principal } = options.instance().subject;
+		try {
+			const response = await options.request(endpoint, { evaluations: batch.map((item) => ({
+				subject: {
+					type: principal?.kind ?? "user",
+					id: principal?.id ?? ""
+				},
+				action: { name: item.permission.action },
+				resource: {
+					type: item.permission.resource,
+					id: rowId(snapshot, item.permission, item.data),
+					properties: item.data
+				}
+			})) });
+			if (!response.ok) throw new Error("evaluations failed");
+			const body = await response.json();
+			if (started !== options.generation()) return;
+			for (const [index, item] of batch.entries()) {
+				const decision = (body.evaluations?.[index])?.context?.permdock ?? SERVER_ONLY;
+				answers.set(item.key, {
+					decision,
+					status: "ready"
+				});
+			}
+		} catch {
+			if (started !== options.generation()) return;
+			for (const item of batch) answers.set(item.key, {
+				decision: SERVER_ONLY,
+				status: "server-only"
+			});
+		}
+		options.emit();
+	};
+	const scheduleFlush = () => {
+		if (flushScheduled || endpoint === void 0) return;
+		flushScheduled = true;
+		queueMicrotask(() => {
+			flushScheduled = false;
+			flush();
+		});
+	};
+	return {
+		enqueue(key, permission, data) {
+			if (answers.has(key)) return;
+			if (endpoint === void 0) {
+				answers.set(key, {
+					decision: NO_ENDPOINT,
+					status: "server-only"
+				});
+				options.onServerOnly?.(permission);
+				options.emitSoon();
+				return;
+			}
+			answers.set(key, {
+				decision: SERVER_ONLY,
+				status: "pending"
+			});
+			queued.push({
+				permission,
+				data,
+				key
+			});
+			options.emitSoon();
+			scheduleFlush();
+		},
+		clear() {
+			queued = [];
+		}
+	};
+}
+//#endregion
+//#region src/client/request.ts
+/** Milliseconds a decision, refresh or approval request may take; a slower one is an error like a failed request. */
+const STORE_TIMEOUT_MS = 1e4;
+function storeRequest(fetchImpl, headers) {
+	return (url, body) => fetchImpl(url, {
+		method: body === void 0 ? "GET" : "POST",
+		credentials: "include",
+		signal: timeoutSignal(STORE_TIMEOUT_MS),
+		headers: body === void 0 ? {
+			accept: "application/json",
+			...headers()
+		} : {
+			accept: "application/json",
+			"content-type": "application/json",
+			...headers()
+		},
+		...body === void 0 ? {} : { body: JSON.stringify(body) }
+	});
+}
+//#endregion
+//#region src/client/source.ts
+/** A compact JWS: three non-empty dot-separated parts. */
+function isJws(value) {
+	const parts = value.split(".");
+	return parts.length === 3 && parts.every((part) => part.length > 0);
+}
+function isPromiseLike(value) {
+	return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}
+//#endregion
+//#region src/client/store.ts
+function withTenant(source, tenant) {
+	if (tenant === void 0) return source;
+	const hashAt = source.indexOf("#");
+	const hash = hashAt === -1 ? "" : source.slice(hashAt);
+	const rest = hashAt === -1 ? source : source.slice(0, hashAt);
+	const queryAt = rest.indexOf("?");
+	const path = queryAt === -1 ? rest : rest.slice(0, queryAt);
+	const params = new URLSearchParams(queryAt === -1 ? "" : rest.slice(queryAt + 1));
+	params.set("tenant", tenant);
+	return `${path}?${params.toString()}${hash}`;
+}
+function refKey(ref) {
+	if ("key" in ref && typeof ref.key === "string") return ref.key;
+	return "";
+}
+const CURRENT = Symbol.for("permdock.current");
+const STORE = Symbol("permdock.store");
+const VALIDATION = {
+	outcome: "denied",
+	denials: [{
+		role: null,
+		reason: "validation"
+	}],
+	alternatives: []
+};
+function report(error) {
+	const reporter = globalThis.reportError;
+	if (typeof reporter === "function") {
+		reporter(error);
+		return;
+	}
+	console.error(error);
+}
+/** The store that emitted `permdock`; a fresh `permdock` follows every change. */
+function storeOf(permdock) {
+	return permdock[STORE];
+}
+function needsEndpoint(decision) {
+	return decision.outcome === "denied" && decision.denials.some((denial) => denial.reason === "opaque-condition");
+}
+function createClientStore(options) {
+	const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+	const server = options.server ?? globalThis.window === void 0;
+	const listeners = /* @__PURE__ */ new Set();
+	const answers = /* @__PURE__ */ new Map();
+	let emitScheduled = false;
+	let snapshot = emptySnapshot();
+	let tenant = options.tenant;
+	let base = "server-only";
+	let instance = fromSnapshot(snapshot, compact({ tenant }));
+	let cached;
+	let verifying = false;
+	let refreshing = 0;
+	let awaiting = options.awaiting === true;
+	let following = awaiting ? 1 : 0;
+	let tracked;
+	let refreshSeq = 0;
+	let silent = false;
+	let adopted;
+	let generation = 0;
+	let disposed = false;
+	let staleNext = options.stale === true;
+	let rawJws;
+	const request = storeRequest(fetchImpl, () => typeof options.headers === "function" ? options.headers() : options.headers);
+	const emit = () => {
+		cached = wrap(instance);
+		if (silent) return;
+		for (const listener of listeners) try {
+			listener();
+		} catch (error) {
+			report(error);
+		}
+	};
+	const emitSoon = () => {
+		if (emitScheduled) return;
+		emitScheduled = true;
+		queueMicrotask(() => {
+			emitScheduled = false;
+			emit();
+		});
+	};
+	const batch = createBatch({
+		endpoint: options.endpoint,
+		request,
+		answers,
+		onServerOnly: options.onServerOnly,
+		generation: () => generation,
+		snapshot: () => snapshot,
+		instance: () => instance,
+		emit,
+		emitSoon
+	});
+	const approvals = createApprovals({
+		approvals: options.approvals,
+		endpoint: options.endpoint,
+		interval: options.approvalInterval ?? 2e3,
+		server,
+		request,
+		emit,
+		disposed: () => disposed,
+		listening: () => listeners.size > 0,
+		simulated: () => snapshot.simulated === true
+	});
+	const reset = () => {
+		generation += 1;
+		answers.clear();
+		decided.clear();
+		batch.clear();
+	};
+	const hydrate = (next) => {
+		reset();
+		if ((snapshot.subject.principal?.id ?? null) !== (next.subject.principal?.id ?? null)) approvals.forget();
+		snapshot = next;
+		instance = fromSnapshot(snapshot, compact({ tenant }));
+		base = "ready";
+		if (staleNext && next.subject.principal !== null) {
+			staleNext = false;
+			base = "stale";
+		}
+		const raw = rawJws;
+		rawJws = void 0;
+		if (!disposed) options.onSnapshot?.(next, tenant, raw);
+		emit();
+	};
+	const storeStatus = () => {
+		if (verifying || refreshing > 0 || following > 0) return "pending";
+		if (base === "server-only") return "server-only";
+		if (base === "stale" || isStale()) return "stale";
+		for (const entry of answers.values()) if (entry.status === "pending") return "pending";
+		return "ready";
+	};
+	const isStale = () => {
+		const maxAge = snapshot.issuedAt > 0 ? options.maxAge : void 0;
+		if (snapshot.expiresAt === void 0 && maxAge === void 0) return false;
+		const now = nowSeconds();
+		if (snapshot.expiresAt !== void 0 && snapshot.expiresAt <= now) return true;
+		return maxAge !== void 0 && now - snapshot.issuedAt > maxAge;
+	};
+	const serverOnly = () => {
+		hydrate(emptySnapshot());
+		base = "server-only";
+		emit();
+	};
+	const applyParsed = (value) => {
+		try {
+			hydrate(parseSnapshot(value));
+		} catch {
+			serverOnly();
+		}
+	};
+	const verifyJws = async (raw) => {
+		if (options.verifier === void 0) return;
+		try {
+			const verified = await options.verifier.verify(raw, { typ: "permdock-snapshot+jwt" });
+			return verified.ok ? verified.claims["snapshot"] : void 0;
+		} catch {
+			return;
+		}
+	};
+	const bootJws = async (raw) => {
+		if (options.verifier === void 0) {
+			serverOnly();
+			return;
+		}
+		const started = generation;
+		verifying = true;
+		emit();
+		const claim = await verifyJws(raw);
+		verifying = false;
+		if (started !== generation) {
+			emit();
+			return;
+		}
+		if (claim === void 0) {
+			serverOnly();
+			return;
+		}
+		rawJws = raw;
+		applyParsed(claim);
+	};
+	const decided = /* @__PURE__ */ new Map();
+	let decidedClear = false;
+	const evaluate = (permission, data) => {
+		try {
+			return instance.decide(permission, data);
+		} catch {
+			return VALIDATION;
+		}
+	};
+	const decideLocal = (permission, data) => {
+		if (options.passCache !== true) return evaluate(permission, data);
+		let byKey = decided.get(data);
+		const hit = byKey?.get(permission.key);
+		if (hit !== void 0) return hit;
+		const decision = evaluate(permission, data);
+		if (byKey === void 0) {
+			byKey = /* @__PURE__ */ new Map();
+			decided.set(data, byKey);
+		}
+		byKey.set(permission.key, decision);
+		if (!decidedClear) {
+			decidedClear = true;
+			queueMicrotask(() => {
+				decidedClear = false;
+				decided.clear();
+			});
+		}
+		return decision;
+	};
+	const permissionState = (permission, data) => {
+		const decision = decideLocal(permission, data);
+		if (decision === VALIDATION) return {
+			allowed: false,
+			status: "ready",
+			decision
+		};
+		if (needsEndpoint(decision)) {
+			let rowKey;
+			try {
+				rowKey = cacheKey(snapshot, permission, data);
+			} catch {
+				return {
+					allowed: false,
+					status: "ready",
+					decision: VALIDATION
+				};
+			}
+			const key = `${tenant ?? ""}|${rowKey}`;
+			const hit = answers.get(key);
+			if (hit !== void 0) return {
+				allowed: hit.decision.outcome === "granted",
+				status: hit.status,
+				decision: hit.decision
+			};
+			if (server && options.endpoint !== void 0) return {
+				allowed: false,
+				status: "pending",
+				decision: SERVER_ONLY
+			};
+			batch.enqueue(key, permission, data);
+			const next = answers.get(key);
+			if (next !== void 0) return {
+				allowed: false,
+				status: next.status,
+				decision: next.decision
+			};
+			return {
+				allowed: false,
+				status: "server-only",
+				decision: NO_ENDPOINT
+			};
+		}
+		return {
+			allowed: decision.outcome === "granted",
+			status: verifying || following > 0 ? "pending" : base === "stale" || isStale() ? "stale" : "ready",
+			decision
+		};
+	};
+	const subscribe = (listener) => {
+		listeners.add(listener);
+		if (listeners.size === 1) approvals.resume();
+		return () => {
+			listeners.delete(listener);
+			if (listeners.size === 0) approvals.stop();
+		};
+	};
+	const wrap = (permdock) => {
+		const client = {
+			...permdock,
+			status(permission, data) {
+				if (permission === void 0) return storeStatus();
+				return permissionState(permission, data).status;
+			},
+			invalidate(ref) {
+				const prefix = refKey(ref);
+				for (const key of answers.keys()) {
+					const unscoped = key.slice(key.indexOf("|") + 1);
+					if (prefix === "" || unscoped === prefix || unscoped.startsWith(`${prefix}:`) || unscoped.startsWith(`${prefix}.`)) answers.delete(key);
+				}
+				base = "stale";
+				emit();
+			},
+			async refresh(query) {
+				const requested = query?.tenant;
+				const source = options.snapshotUrl ?? options.endpoint;
+				if (requested !== void 0 && (snapshot.tenants.includes(requested) || source === void 0)) {
+					const wasStale = base === "stale";
+					tenant = requested;
+					hydrate(snapshot);
+					if (wasStale) {
+						base = "stale";
+						emit();
+					}
+					return;
+				}
+				if (source === void 0 || disposed) return;
+				const started = generation;
+				refreshSeq += 1;
+				const seq = refreshSeq;
+				refreshing += 1;
+				emit();
+				let body;
+				let ok = false;
+				try {
+					const response = await request(withTenant(source, requested));
+					if (response.ok) {
+						body = await response.json();
+						ok = true;
+					}
+				} catch {
+					ok = false;
+				}
+				let signed;
+				if (ok && typeof body === "string" && isJws(body)) {
+					signed = body;
+					body = await verifyJws(body);
+					ok = body !== void 0;
+				}
+				refreshing -= 1;
+				if (started !== generation || seq !== refreshSeq) {
+					emit();
+					return;
+				}
+				let next;
+				try {
+					next = ok ? parseSnapshot(body) : void 0;
+				} catch {
+					next = void 0;
+				}
+				if (next === void 0) {
+					base = "stale";
+					emit();
+					return;
+				}
+				if (requested !== void 0) tenant = requested;
+				staleNext = false;
+				rawJws = signed;
+				hydrate(next);
+			},
+			clear() {
+				reset();
+				tenant = options.tenant;
+				snapshot = emptySnapshot();
+				instance = fromSnapshot(snapshot, compact({ tenant }));
+				base = "server-only";
+				approvals.forget();
+				if (!disposed) options.onClear?.();
+				emit();
+			},
+			subscribe
+		};
+		Object.defineProperty(client, CURRENT, { value: () => cached });
+		Object.defineProperty(client, STORE, { value: store });
+		return client;
+	};
+	const dispatch = (value) => {
+		if (typeof value === "string" && isJws(value)) bootJws(value);
+		else applyParsed(value);
+	};
+	const land = (next) => {
+		if (next === void 0) serverOnly();
+		else dispatch(next);
+	};
+	const follow = (value) => {
+		const started = generation;
+		following += 1;
+		emit();
+		const settle = (next) => {
+			following -= 1;
+			if (started !== generation) {
+				emit();
+				return;
+			}
+			land(next);
+		};
+		Promise.resolve(value).then(settle, () => {
+			settle(void 0);
+		});
+	};
+	const store = {
+		get() {
+			return cached;
+		},
+		subscribe,
+		permissionState,
+		approvalState: approvals.state,
+		replace(value) {
+			staleNext = false;
+			dispatch(value);
+		},
+		follow,
+		track(value) {
+			if (tracked === value) return;
+			tracked = value;
+			if (awaiting) {
+				awaiting = false;
+				following -= 1;
+			}
+			const thenable = value;
+			if (thenable.status === "fulfilled") land(thenable.value);
+			else if (thenable.status === "rejected") serverOnly();
+			else follow(value);
+		},
+		adopt(value, source) {
+			if (adopted === source) return;
+			adopted = source;
+			reset();
+			silent = true;
+			try {
+				dispatch(value);
+			} finally {
+				silent = false;
+			}
+			queueMicrotask(emit);
+		},
+		snapshot() {
+			return snapshot;
+		},
+		tenant() {
+			return tenant;
+		},
+		dispose() {
+			disposed = true;
+			generation += 1;
+			batch.clear();
+			approvals.forget();
+			listeners.clear();
+		},
+		requestApproval: approvals.request
+	};
+	dispatch(options.snapshot);
+	return store;
+}
+//#endregion
+//#region src/client/store-options.ts
+/** One hint per store: the first check `endpoint: false` turns into a `server-only` denial. */
+function hintOnce() {
+	let shown = false;
+	return (permission) => {
+		if (shown) return;
+		shown = true;
+		console.info(`PermDock: ${permission.key} needs the server (a closure, graph relation or period grant) and endpoint is false, so it is denied with reason server-only; check it on the server instead`);
+	};
+}
+function adapterStore(options, snapshot, native) {
+	return createClientStore(compact({
+		snapshot,
+		endpoint: options.endpoint === false ? void 0 : options.endpoint,
+		onServerOnly: options.endpoint === false ? hintOnce() : void 0,
+		snapshotUrl: options.snapshotUrl,
+		approvals: options.approvals,
+		tenant: options.tenant,
+		fetch: options.fetch,
+		headers: options.headers,
+		maxAge: options.maxAge,
+		verifier: options.verifier,
+		awaiting: options.awaiting,
+		passCache: options.passCache,
+		server: native?.server,
+		stale: native?.stale,
+		onSnapshot: native?.onSnapshot,
+		onClear: native?.onClear
+	}));
+}
+//#endregion
+export { isPromiseLike as i, storeOf as n, isJws as r, adapterStore as t };