permdock 0.0.0 → 0.2.0

package/dist/pdp/index.js

@@ -0,0 +1,682 @@
+import { n as isReadonlyArray, t as compact } from "../compact-y6vfu2_f.js";
+import { n as freezeDeep } from "../freeze-CrU8nQeX.js";
+import { _ as listPermissions, c as getResource } from "../permissions-DVoF6dMt.js";
+import { n as PermDockValidationError } from "../validation-error-CnjZ4t92.js";
+import { a as deniedMessage, i as approvalMessage, n as PermDockDeniedError, t as PermDockApprovalRequiredError } from "../errors-Cz5zn0mW.js";
+import { d as isArazzoSimulateInput } from "../snapshot-Enxd0n-s.js";
+import { n as isThenable } from "../thenable-okc2xDsj.js";
+import { t as createPermDock$1 } from "../permdock-CzqXjCpU.js";
+import { s as isRecord } from "../map-AcxK9o_D.js";
+import { a as postJson, c as ttlMs, i as joinUrl, n as denied, o as resourceIdOf, r as granted, s as ttlCache, t as cacheKey } from "../shared-DRu8VFVM.js";
+//#region src/pdp/create.ts
+function withoutProviders(policy) {
+	if (policy.providers === void 0 || policy.providers.length === 0) return policy;
+	return freezeDeep(compact({
+		permissions: policy.permissions,
+		roles: policy.roles,
+		rolesByName: policy.rolesByName,
+		grants: policy.grants,
+		vocabulary: policy.vocabulary,
+		scopes: policy.scopes,
+		principal(user) {
+			return policy.principal(user);
+		},
+		subject(user) {
+			return policy.subject(user);
+		},
+		context(user) {
+			return policy.context?.(user);
+		},
+		validate: policy.validate,
+		onDenied: policy.onDenied,
+		fingerprint: policy.fingerprint,
+		resources: policy.resources,
+		index: policy.index
+	}));
+}
+function providerFor(providers, permission) {
+	for (const provider of providers) if (provider.handles(permission)) return provider;
+}
+function idFieldOf(policy, permission) {
+	return getResource(policy.permissions, permission.resource)?.id ?? "id";
+}
+function isExplicitDeny(decision) {
+	return decision.outcome === "denied" && decision.denials.some((denial) => denial.reason === "deny");
+}
+function isLocalShortCircuit(decision) {
+	if (decision.outcome !== "denied") return false;
+	if (isExplicitDeny(decision)) return true;
+	return decision.denials.some((denial) => {
+		switch (denial.reason) {
+			case "no-grant":
+			case "inactive-grant": return false;
+			case "pdp-denied":
+			case "pdp-unavailable":
+			case "pdp-invalid-response": return false;
+			case "anonymous":
+			case "validation":
+			case "not-delegated":
+			case "no-delegation":
+			case "condition":
+			case "deny":
+			case "closure-error":
+			case "opaque-condition":
+			case "server-only":
+			case "insufficient-user-authentication":
+			case "not-entitled":
+			case "purpose":
+			case "reason-required":
+			case "actor-required":
+			case "limit":
+			case "limit-unavailable":
+			case "relation-depth":
+			case "relation-unavailable":
+			case "tenant-mismatch":
+			case "no-membership":
+			case "scope":
+			case "expired-membership":
+			case "stale-credentials":
+			case "unknown-role":
+			case "last-holder":
+			case "max-holders":
+			case "transfer-only":
+			case "not-assignable-by":
+			case "self-demotion":
+			case "externally-managed":
+			case "not-allowed-for-membership":
+			case "conflicting-role":
+			case "approval":
+			case "stale-approval":
+			case "undocumented":
+			case "unsupported":
+			case "exceeds-creator":
+			case "credential-policy": return true;
+			default: return denial.reason;
+		}
+	});
+}
+function wrap(permdock, policy, subject, providers) {
+	const decideLocal = permdock.decide;
+	const decide = async (permission, data, options) => {
+		const local = decideLocal(permission, data, options);
+		const provider = providerFor(providers, permission);
+		if (provider === void 0 || isLocalShortCircuit(local)) return local;
+		try {
+			return await provider.decide({
+				permission,
+				data,
+				subject,
+				local
+			});
+		} catch {
+			return denied("pdp-unavailable");
+		}
+	};
+	/** The local trace; a remote decision evaluated no local grant, so its trace is empty. */
+	const explain = async (permission, data, options) => {
+		const decision = await decide(permission, data, {
+			...options,
+			source: options?.source ?? "explain",
+			explain: true
+		});
+		if (decision.trace !== void 0) return decision;
+		return freezeDeep({
+			...decision,
+			trace: {
+				evaluated: 0,
+				allows: [],
+				denies: [],
+				skipped: []
+			}
+		});
+	};
+	const permittedIds = async (provider, permission) => {
+		if (provider?.permitted === void 0 || subject.principal === null) return;
+		try {
+			return await provider.permitted({
+				permission,
+				subject
+			});
+		} catch {
+			return null;
+		}
+	};
+	const can = async (permission, data, options) => {
+		try {
+			return (await decide(permission, data, options)).outcome === "granted";
+		} catch {
+			return false;
+		}
+	};
+	const assert = async (permission, data, options) => {
+		const decision = await decide(permission, data, {
+			...options,
+			source: options?.source ?? "assert"
+		});
+		if (decision.outcome === "granted") return decision;
+		const onDenied = options?.onDenied ?? policy.onDenied;
+		if (onDenied !== void 0) onDenied(decision);
+		const resource = getResource(policy.permissions, permission.resource);
+		const resourceId = data !== null && typeof data === "object" ? data[resource?.id ?? "id"] : void 0;
+		const resourceRef = compact({
+			type: permission.resource,
+			id: resourceId === void 0 ? void 0 : String(resourceId)
+		});
+		if (decision.outcome === "approval-required") throw new PermDockApprovalRequiredError({
+			decision,
+			permission: permission.key,
+			scope: permission.scope,
+			resource: resourceRef,
+			message: approvalMessage(permission.key, decision.reason, decision.token)
+		});
+		if (decision.denials.some((denial) => denial.reason === "validation")) {
+			const detail = decision.denials[0]?.detail;
+			if (detail instanceof PermDockValidationError) throw detail;
+		}
+		throw new PermDockDeniedError({
+			decision,
+			permission: permission.key,
+			scope: permission.scope,
+			resource: resourceRef,
+			subject,
+			message: deniedMessage(permission.key, subject.principal?.id, decision.denials, decision.alternatives.map((leaf) => leaf.key))
+		});
+	};
+	const simulate = ((input, options) => {
+		if (isReadonlyArray(input)) return Promise.all(input.map(([permission, data]) => decide(permission, data, compact({
+			source: "simulate",
+			now: options?.now
+		}))));
+		if (isArazzoSimulateInput(input)) return permdock.simulate(input);
+		return wrap(permdock.simulate(input), policy, subject, providers);
+	});
+	return {
+		can,
+		decide,
+		assert,
+		explain,
+		async filter(permission, rows, options) {
+			const next = {
+				...options,
+				source: "filter"
+			};
+			const provider = providerFor(providers, permission);
+			const ids = await permittedIds(provider, permission);
+			if (ids === void 0) {
+				const decisions = await Promise.all(rows.map((row) => decide(permission, row, next)));
+				return rows.filter((_, index) => decisions[index]?.outcome === "granted");
+			}
+			const allowed = new Set(ids ?? []);
+			const field = idFieldOf(policy, permission);
+			return rows.filter((row) => {
+				const id = resourceIdOf(row, field);
+				return allowed.has(id) && !isLocalShortCircuit(decideLocal(permission, row, next));
+			});
+		},
+		pick: permdock.pick.bind(permdock),
+		async where(permission) {
+			const provider = providerFor(providers, permission);
+			if (provider === void 0) return permdock.where(permission);
+			const ids = await permittedIds(provider, permission);
+			if (ids === void 0) return {
+				condition: {
+					op: "or",
+					conditions: []
+				},
+				partial: true
+			};
+			if (ids === null || ids.length === 0) return {
+				condition: {
+					op: "or",
+					conditions: []
+				},
+				partial: false
+			};
+			const remote = {
+				op: "in",
+				field: idFieldOf(policy, permission),
+				value: [...ids]
+			};
+			const local = permdock.where(permission);
+			return local.condition.op !== "or" || local.condition.conditions.length > 0 ? {
+				condition: {
+					op: "and",
+					conditions: [local.condition, remote]
+				},
+				partial: local.partial
+			} : {
+				condition: remote,
+				partial: true
+			};
+		},
+		actions: permdock.actions.bind(permdock),
+		simulate,
+		snapshot: permdock.snapshot.bind(permdock),
+		on: permdock.on.bind(permdock),
+		tenant: (id) => {
+			const next = permdock.tenant(id);
+			return wrap(next, policy, next.subject, providers);
+		},
+		team: (id) => {
+			const next = permdock.team(id);
+			return wrap(next, policy, next.subject, providers);
+		},
+		derive: (options) => {
+			const next = permdock.derive(options);
+			return isThenable(next) ? next.then((derived) => wrap(derived, policy, derived.subject, providers)) : wrap(next, policy, next.subject, providers);
+		},
+		memberships: permdock.memberships.bind(permdock),
+		tenants: permdock.tenants.bind(permdock),
+		heldRoles: permdock.heldRoles.bind(permdock),
+		audiences: permdock.audiences.bind(permdock),
+		assignableRoles: permdock.assignableRoles.bind(permdock),
+		assignablePermissions: permdock.assignablePermissions.bind(permdock),
+		assignableLevels: permdock.assignableLevels.bind(permdock),
+		decideRoleChange: permdock.decideRoleChange.bind(permdock),
+		loadRelations: permdock.loadRelations.bind(permdock),
+		whoCan: permdock.whoCan.bind(permdock),
+		activate: permdock.activate.bind(permdock),
+		permissions: permdock.permissions,
+		roles: permdock.roles,
+		plans: permdock.plans,
+		subject
+	};
+}
+async function createPermDock(policy, user, options = {}) {
+	const localPolicy = withoutProviders(policy);
+	const permdock = await createPermDock$1(localPolicy, user, options);
+	return wrap(permdock, localPolicy, permdock.subject, policy.providers ?? []);
+}
+//#endregion
+//#region src/pdp/relations.ts
+function relationProvider(backend) {
+	const callbacks = /* @__PURE__ */ new Map();
+	for (const [permission, callback] of backend.map) callbacks.set(permission.key, callback);
+	const timeout = backend.timeout ?? 300;
+	const decisions = ttlCache(ttlMs(backend.cache));
+	const lists = ttlCache(ttlMs(backend.cache));
+	const fetcher = backend.fetch ?? fetch;
+	const post = async (url, body) => {
+		const posted = await postJson(fetcher, url, body, {
+			auth: backend.auth,
+			timeout
+		});
+		return posted.ok ? posted.response : null;
+	};
+	function tupleFor(permission, subject, data) {
+		const callback = callbacks.get(permission.key);
+		if (callback === void 0) return null;
+		try {
+			return callback(subject, data);
+		} catch {
+			return "invalid";
+		}
+	}
+	return {
+		name: backend.name,
+		handles(permission) {
+			return callbacks.has(permission.key);
+		},
+		async decide(request) {
+			if (request.subject.principal === null) return denied("anonymous");
+			const tuple = tupleFor(request.permission, request.subject, request.data);
+			if (tuple === "invalid") return denied("pdp-invalid-response");
+			if (tuple === null) return denied("pdp-denied");
+			const key = cacheKey(request.subject, request.permission, tuple);
+			const hit = decisions.get(key);
+			if (hit !== void 0) return hit;
+			const result = await backend.check(tuple, post);
+			if (result === "unavailable") return denied("pdp-unavailable");
+			if (result === "invalid") return denied("pdp-invalid-response");
+			const decision = result ? granted(backend.name, request.permission, request.subject, request.data) : denied("pdp-denied");
+			decisions.set(key, decision);
+			return decision;
+		},
+		async permitted(request) {
+			if (request.subject.principal === null) return [];
+			const tuple = tupleFor(request.permission, request.subject, void 0);
+			if (tuple === "invalid") return null;
+			if (tuple === null) return [];
+			const key = cacheKey(request.subject, request.permission, tuple);
+			const hit = lists.get(key);
+			if (hit !== void 0) return hit;
+			const ids = await backend.list(tuple, post);
+			if (ids !== null) lists.set(key, ids);
+			return ids;
+		}
+	};
+}
+async function jsonOf(response) {
+	if (response === null) return;
+	try {
+		return await response.json();
+	} catch {
+		return null;
+	}
+}
+/**
+* An OpenFGA store as a decision provider: `check` decides one row and
+* `list-objects` lists the ids `filter` and `where` use.
+*/
+function openfga(options) {
+	const store = joinUrl(options.url, `/stores/${encodeURIComponent(options.storeId)}`);
+	const model = compact({ authorization_model_id: options.authorizationModelId });
+	return relationProvider(compact({
+		name: "openfga",
+		map: options.map,
+		auth: options.auth,
+		timeout: options.timeout,
+		cache: options.cache,
+		fetch: options.fetch,
+		async check(tuple, post) {
+			if (tuple.id === void 0) return "invalid";
+			const body = await jsonOf(await post(`${store}/check`, {
+				...model,
+				tuple_key: {
+					user: tuple.user,
+					relation: tuple.relation,
+					object: `${tuple.type}:${tuple.id}`
+				}
+			}));
+			if (body === void 0) return "unavailable";
+			return isRecord(body) && typeof body["allowed"] === "boolean" ? body["allowed"] : "invalid";
+		},
+		async list(tuple, post) {
+			const body = await jsonOf(await post(`${store}/list-objects`, {
+				...model,
+				type: tuple.type,
+				relation: tuple.relation,
+				user: tuple.user
+			}));
+			if (!isRecord(body) || !Array.isArray(body["objects"])) return null;
+			const prefix = `${tuple.type}:`;
+			const ids = [];
+			for (const object of body["objects"]) {
+				if (typeof object !== "string" || !object.startsWith(prefix)) return null;
+				ids.push(object.slice(prefix.length));
+			}
+			return Object.freeze(ids);
+		}
+	}));
+}
+function subjectReference(check) {
+	return compact({
+		object: {
+			objectType: check.subject.type,
+			objectId: check.subject.id
+		},
+		optionalRelation: check.subject.relation
+	});
+}
+/**
+* A SpiceDB HTTP gateway as a decision provider: `CheckPermission` decides
+* one row and `LookupResources` lists the ids `filter` and `where` use. A
+* conditional permissionship (a caveat missing context) is a denial.
+*/
+function spicedb(options) {
+	const consistency = options.consistency === "fully-consistent" ? { fullyConsistent: true } : { minimizeLatency: true };
+	return relationProvider(compact({
+		name: "spicedb",
+		map: options.map,
+		auth: { bearer: options.token },
+		timeout: options.timeout,
+		cache: options.cache,
+		fetch: options.fetch,
+		async check(check, post) {
+			if (check.resource.id === void 0) return "invalid";
+			const body = await jsonOf(await post(joinUrl(options.url, "/v1/permissions/check"), {
+				consistency,
+				resource: {
+					objectType: check.resource.type,
+					objectId: check.resource.id
+				},
+				permission: check.permission,
+				subject: subjectReference(check)
+			}));
+			if (body === void 0) return "unavailable";
+			if (!isRecord(body)) return "invalid";
+			switch (body["permissionship"]) {
+				case "PERMISSIONSHIP_HAS_PERMISSION": return true;
+				case "PERMISSIONSHIP_NO_PERMISSION":
+				case "PERMISSIONSHIP_CONDITIONAL_PERMISSION": return false;
+				default: return "invalid";
+			}
+		},
+		async list(check, post) {
+			const response = await post(joinUrl(options.url, "/v1/permissions/resources"), {
+				consistency,
+				resourceObjectType: check.resource.type,
+				permission: check.permission,
+				subject: subjectReference(check)
+			});
+			if (response === null) return null;
+			let text;
+			try {
+				text = await response.text();
+			} catch {
+				return null;
+			}
+			const ids = [];
+			for (const line of text.split("\n")) {
+				if (line.trim() === "") continue;
+				let parsed;
+				try {
+					parsed = JSON.parse(line);
+				} catch {
+					return null;
+				}
+				const result = isRecord(parsed) ? parsed["result"] : void 0;
+				if (!isRecord(result) || typeof result["resourceObjectId"] !== "string") return null;
+				if (result["permissionship"] === "LOOKUP_PERMISSIONSHIP_HAS_PERMISSION") ids.push(result["resourceObjectId"]);
+			}
+			return Object.freeze(ids);
+		}
+	}));
+}
+//#endregion
+//#region src/pdp/remote.ts
+const DEFAULT_EVALUATION = "/access/v1/evaluation";
+const DEFAULT_EVALUATIONS = "/access/v1/evaluations";
+const MAX_SEARCH_PAGES = 100;
+function delegatedKeys(listed) {
+	if (listed === void 0) return null;
+	const keys = /* @__PURE__ */ new Set();
+	for (const item of listed) for (const leaf of listPermissions(item)) keys.add(leaf.key);
+	return keys;
+}
+function parseDiscovery(url, body) {
+	if (!isRecord(body)) return null;
+	const evaluation = typeof body["access_evaluation_endpoint"] === "string" ? body["access_evaluation_endpoint"] : typeof body["policy_decision_point"] === "string" ? joinUrl(body["policy_decision_point"], DEFAULT_EVALUATION) : joinUrl(url, DEFAULT_EVALUATION);
+	return compact({
+		evaluation,
+		evaluations: typeof body["access_evaluations_endpoint"] === "string" ? body["access_evaluations_endpoint"] : joinUrl(url, DEFAULT_EVALUATIONS),
+		searchResource: typeof body["search_resource_endpoint"] === "string" ? body["search_resource_endpoint"] : void 0
+	});
+}
+function mapEvaluationBody(permission, data, subject, mapping) {
+	const defaultId = data !== null && typeof data === "object" ? data["id"] : void 0;
+	const mappedSubject = mapping?.subject?.(subject) ?? compact({
+		type: "user",
+		id: subject.principal?.id,
+		properties: compact({
+			orgId: subject.principal?.tenant,
+			roles: subject.principal?.roles,
+			actor: subject.actor,
+			delegation: subject.delegation
+		})
+	});
+	const mappedResource = mapping?.resource?.(permission, data) ?? compact({
+		type: permission.resource,
+		id: typeof defaultId === "string" || typeof defaultId === "number" ? String(defaultId) : resourceIdOf(data),
+		properties: data
+	});
+	return {
+		subject: mappedSubject,
+		action: mapping?.action?.(permission) ?? { name: permission.action },
+		resource: mappedResource,
+		context: compact({
+			tenant: subject.principal?.tenant,
+			actor: subject.actor,
+			delegation: subject.delegation
+		})
+	};
+}
+function parseRemoteDecision(body, permission, subject, data) {
+	if (!isRecord(body) || typeof body["decision"] !== "boolean") return denied("pdp-invalid-response");
+	if (body["decision"]) return granted("pdp", permission, subject, data);
+	const context = isRecord(body["context"]) && isRecord(body["context"]["permdock"]) ? body["context"]["permdock"] : {};
+	if (context["outcome"] === "approval-required") {
+		const token = typeof context["token"] === "string" ? context["token"] : "";
+		return {
+			outcome: "approval-required",
+			grant: {
+				role: "pdp",
+				permission: permission.key,
+				provider: "pdp",
+				approval: "human"
+			},
+			reason: "human",
+			token
+		};
+	}
+	if (Array.isArray(context["denials"])) {
+		const denials = context["denials"].flatMap((item) => {
+			if (!isRecord(item) || typeof item["reason"] !== "string") return [];
+			return [compact({
+				role: typeof item["role"] === "string" ? item["role"] : null,
+				reason: item["reason"],
+				detail: item["detail"]
+			})];
+		});
+		if (denials.length > 0) return {
+			outcome: "denied",
+			denials,
+			alternatives: []
+		};
+	}
+	return denied("pdp-denied");
+}
+function mapSearchBody(permission, subject, mapping) {
+	const body = mapEvaluationBody(permission, void 0, subject, mapping);
+	const resource = isRecord(body["resource"]) ? body["resource"] : {};
+	return {
+		...body,
+		resource: { type: resource["type"] ?? permission.resource }
+	};
+}
+function searchIds(body, type) {
+	if (!isRecord(body) || !Array.isArray(body["results"])) return null;
+	const ids = [];
+	for (const entity of body["results"]) {
+		if (!isRecord(entity) || entity["type"] !== type || typeof entity["id"] !== "string") return null;
+		ids.push(entity["id"]);
+	}
+	return ids;
+}
+function nextToken(body) {
+	if (!isRecord(body) || !isRecord(body["page"])) return;
+	const token = body["page"]["next_token"];
+	return typeof token === "string" && token !== "" ? token : void 0;
+}
+function remotePdp(options) {
+	const keys = delegatedKeys(options.permissions);
+	const timeout = options.timeout ?? 300;
+	const decisions = ttlCache(ttlMs(options.cache));
+	const lists = ttlCache(ttlMs(options.cache));
+	const fetcher = options.fetch ?? fetch;
+	const post = {
+		auth: options.auth,
+		timeout
+	};
+	let discovery = options.endpoints?.evaluation === void 0 ? null : compact({
+		evaluation: options.endpoints.evaluation,
+		evaluations: options.endpoints.evaluations,
+		searchResource: options.endpoints.searchResource
+	});
+	async function discover() {
+		if (discovery !== null) return discovery;
+		try {
+			const signal = AbortSignal.timeout(timeout);
+			const response = await fetcher(joinUrl(options.url, "/.well-known/authzen-configuration"), { signal });
+			if (!response.ok) return null;
+			const parsed = parseDiscovery(options.url, await response.json());
+			if (parsed === null) return null;
+			discovery = parsed;
+			return parsed;
+		} catch {
+			return null;
+		}
+	}
+	async function readJson(url, body) {
+		const posted = await postJson(fetcher, url, body, post);
+		if (!posted.ok) return posted;
+		try {
+			return {
+				ok: true,
+				body: await posted.response.json()
+			};
+		} catch {
+			return { ok: false };
+		}
+	}
+	return {
+		name: "pdp",
+		handles(permission) {
+			return keys === null || keys.has(permission.key);
+		},
+		async decide(request) {
+			if (request.subject.principal === null) return denied("anonymous");
+			let body;
+			try {
+				body = mapEvaluationBody(request.permission, request.data, request.subject, options.mapping);
+			} catch {
+				return denied("pdp-invalid-response");
+			}
+			const key = cacheKey(request.subject, request.permission, body);
+			const hit = decisions.get(key);
+			if (hit !== void 0) return hit;
+			const endpoints = await discover();
+			if (endpoints === null) return denied("pdp-unavailable");
+			const posted = await readJson(endpoints.evaluation, body);
+			if (!posted.ok) return denied("pdp-unavailable");
+			const decision = parseRemoteDecision(posted.body, request.permission, request.subject, request.data);
+			if (decision.outcome === "granted" || decision.outcome === "approval-required" || decision.outcome === "denied" && decision.denials[0]?.reason === "pdp-denied") decisions.set(key, decision);
+			return decision;
+		},
+		async permitted(request) {
+			if (request.subject.principal === null) return [];
+			const endpoints = await discover();
+			if (endpoints === null) return null;
+			if (endpoints.searchResource === void 0) return;
+			let body;
+			try {
+				body = mapSearchBody(request.permission, request.subject, options.mapping);
+			} catch {
+				return null;
+			}
+			const key = cacheKey(request.subject, request.permission, body);
+			const hit = lists.get(key);
+			if (hit !== void 0) return hit;
+			const type = isRecord(body["resource"]) ? body["resource"]["type"] : void 0;
+			const url = endpoints.searchResource;
+			const collect = async (token, page, ids) => {
+				if (page >= MAX_SEARCH_PAGES) return null;
+				const posted = await readJson(url, token === void 0 ? body : {
+					...body,
+					page: { token }
+				});
+				const found = posted.ok ? searchIds(posted.body, type) : null;
+				if (!posted.ok || found === null) return null;
+				const next = nextToken(posted.body);
+				return next === void 0 ? [...ids, ...found] : collect(next, page + 1, [...ids, ...found]);
+			};
+			const ids = await collect(void 0, 0, []);
+			if (ids === null) return null;
+			const frozen = Object.freeze([...ids]);
+			lists.set(key, frozen);
+			return frozen;
+		}
+	};
+}
+//#endregion
+export { createPermDock, openfga, remotePdp, spicedb };