permdock 0.4.0 → 0.5.0

package/dist/create-BWRSXgOF.js

@@ -0,0 +1,403 @@
+import { r as isRecord, t as compact } from "./compact-CAf557ZB.js";
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+import { i as dateAt, p as nowSeconds } from "./time-DkWjdL98.js";
+import { s as policyDocumentFromClaims } from "./hosted-BZIAYvon.js";
+import { l as isApprovalErrorCode, s as ApprovalError, t as APPROVAL_HEADER } from "./types-DqzsnlSA.js";
+import { h as toCloudEvent, l as isAbsoluteUri } from "./sink-BEZSlMS_.js";
+import { n as parseCatalogEventData, t as catalogFingerprint } from "./catalog-fingerprint-CCP0-yQS.js";
+import { t as parseApprovalRequest } from "./parse-request-D_tUXG6M.js";
+import { t as timeoutSignal } from "./timeout-D51niuQP.js";
+//#region src/cloud/approver.ts
+const APPROVER_HEADER = "PermDock-Approver";
+/** The RFC 9396 `authorization_details` type that binds an approver token to one verdict. */
+const APPROVAL_DETAIL_TYPE = "permdock_approval";
+/** Seconds an approver token lives: it proves one resolve call, and the Cloud refuses a replayed `jti`. */
+const APPROVER_TTL = 60;
+async function facts(read, request, verdict, fallback) {
+	if (read === void 0) return fallback ?? [];
+	try {
+		return (await read(request, verdict.by)).filter((item) => typeof item === "string");
+	} catch {
+		return [];
+	}
+}
+function unauthenticated(detail) {
+	return new ApprovalError("approver-unauthenticated", detail);
+}
+/** A rejection only denies, so the Cloud takes a `system` one without an approver token. */
+function isSystemRejection(verdict) {
+	return verdict.status === "rejected" && verdict.by.actor?.kind === "system";
+}
+/**
+* The `PermDock-Approver` header for `verdict`: an RFC 9068 `at+jwt` whose
+* `sub` is the approver, signed by `options.signer` for `<issuer>/approvals`,
+* with a fresh `jti` and one `permdock_approval` authorization detail naming
+* the request id, the verdict status, `vouched`, and the approver's
+* `permissions` and `relations`. With the `roles`, `memberships` and `tenant`
+* claims they are the only facts the Cloud checks a request's `approvers`
+* against in bring-your-own mode. `target` runs only after the
+* approver checks pass. Throws an `ApprovalError` before any resolve when the
+* approver cannot be proven: no signer, no principal, an actor, a failed
+* lookup or a signer failure.
+*/
+async function approverHeaders(verdict, options, issuer, target) {
+	if (isSystemRejection(verdict)) return {};
+	if (verdict.by.actor !== void 0) throw new ApprovalError("approver-not-eligible", "PermDock Cloud: a person approves; a verdict with an actor has no approver token");
+	const principal = verdict.by.principal;
+	if (principal === null || principal.id === "") throw unauthenticated("PermDock Cloud: the approver has no principal id");
+	if (options === void 0) throw unauthenticated("PermDock Cloud: cloud() needs approver.signer to prove who resolves an approval");
+	const { request, etag } = await target();
+	const permissions = await facts(options.permissions, request, verdict, verdict.permissions);
+	const relations = await facts(options.relations, request, verdict, verdict.relations);
+	const issuedAt = nowSeconds();
+	try {
+		const token = await options.signer.sign({
+			sub: principal.id,
+			roles: principal.roles,
+			...principal.memberships === void 0 ? {} : { memberships: principal.memberships },
+			...principal.tenant === void 0 ? {} : { tenant: principal.tenant },
+			authorization_details: [{
+				type: APPROVAL_DETAIL_TYPE,
+				id: request.id,
+				status: verdict.status,
+				permissions,
+				relations,
+				...etag === void 0 ? {} : { etag },
+				...verdict.vouched === void 0 ? {} : { vouched: verdict.vouched }
+			}]
+		}, {
+			typ: "at+jwt",
+			audience: options.audience ?? `${issuer}/approvals`,
+			issuedAt,
+			expiresAt: issuedAt + APPROVER_TTL,
+			jti: globalThis.crypto.randomUUID()
+		});
+		return { [APPROVER_HEADER]: token };
+	} catch {
+		throw unauthenticated("PermDock Cloud: the approver signer failed");
+	}
+}
+//#endregion
+//#region src/cloud/request.ts
+/** Milliseconds a PermDock Cloud request may take; a slower one fails like an unreachable Cloud. */
+const CLOUD_TIMEOUT_MS = 1e4;
+function readEnv(name) {
+	const value = globalThis.process?.env?.[name];
+	return typeof value === "string" ? value : "";
+}
+function firstNonEmpty(...values) {
+	for (const value of values) if (value !== void 0 && value !== "") return value;
+	return "";
+}
+function trimSlash(value) {
+	return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+/**
+* The environment URL and JWK Set URL `cloud()` uses, resolved with the same
+* fallbacks (`PERMDOCK_CLOUD_URL`; `PERMDOCK_CLOUD_ENV`, `VERCEL_ENV`, `production`).
+*/
+function cloudEndpoints(options = {}) {
+	const url = trimSlash(firstNonEmpty(options.url, readEnv("PERMDOCK_CLOUD_URL")));
+	if (url === "") throw new Error("PermDock: cloud() requires url and key.");
+	const environment = firstNonEmpty(options.environment, readEnv("PERMDOCK_CLOUD_ENV"), readEnv("VERCEL_ENV"), "production");
+	const issuer = `${url}/v1/environments/${encodeURIComponent(environment)}`;
+	return Object.freeze({
+		issuer,
+		jwks: `${issuer}/.well-known/jwks.json`
+	});
+}
+/** The authenticated connection every `permdock/cloud` client shares. Throws without a URL or key. */
+function cloudConnection(options) {
+	const key = firstNonEmpty(options.key, readEnv("PERMDOCK_CLOUD_KEY"));
+	if (key === "") throw new Error("PermDock: cloud() requires url and key.");
+	const endpoints = cloudEndpoints(options);
+	const fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis);
+	const request = (path, init = {}, accept, contentType) => {
+		const headers = new Headers();
+		headers.set("authorization", `Bearer ${key}`);
+		headers.set("content-type", "application/json");
+		for (const [name, value] of new Headers(init.headers)) headers.set(name, value);
+		if (accept !== void 0) headers.set("accept", accept);
+		if (contentType !== void 0) headers.set("content-type", contentType);
+		return fetchFn(`${endpoints.issuer}${path}`, {
+			...init,
+			headers,
+			signal: timeoutSignal(CLOUD_TIMEOUT_MS, init.signal)
+		});
+	};
+	return Object.freeze({
+		...endpoints,
+		request
+	});
+}
+/** `true` for a compact JWS: three dot-separated parts, not JSON. */
+function isCompactJws(value) {
+	return !value.startsWith("{") && value.split(".").length === 3;
+}
+//#endregion
+//#region src/cloud/create.ts
+/** Carries the `at+jwt` that names the subject of `GET /snapshot`. */
+const SUBJECT_HEADER = "PermDock-Subject";
+function catalogPushOf(value) {
+	if (!isRecord(value) || !Number.isSafeInteger(value["version"]) || typeof value["fingerprint"] !== "string") return null;
+	const version = Number(value["version"]);
+	const fingerprint = value["fingerprint"];
+	if (value["unchanged"] === true) return {
+		version,
+		fingerprint,
+		unchanged: true
+	};
+	const data = parseCatalogEventData({
+		kind: "drift",
+		fingerprint,
+		findings: value["findings"]
+	});
+	return data?.findings === void 0 ? null : {
+		version,
+		fingerprint,
+		findings: data.findings
+	};
+}
+function asApproval(value) {
+	if (!isRecord(value) || value["v"] !== 1 || typeof value["token"] !== "string") return null;
+	return value;
+}
+/** The refusal PermDock Cloud names in its body, else the one its status implies. */
+async function approvalErrorFrom(response) {
+	let body;
+	try {
+		body = await response.json();
+	} catch {
+		return approvalErrorFromStatus(response.status);
+	}
+	if (body === null || typeof body !== "object" || !("code" in body)) return approvalErrorFromStatus(response.status);
+	const code = body.code;
+	if (!isApprovalErrorCode(code)) return approvalErrorFromStatus(response.status);
+	const detail = "detail" in body ? body.detail : void 0;
+	return new ApprovalError(code, typeof detail === "string" && detail.length > 0 ? detail : code);
+}
+function approvalErrorFromStatus(status) {
+	if (status === 409) return new ApprovalError("approval-not-pending", "approval is not pending");
+	if (status === 410) return new ApprovalError("approval-expired", "approval has expired");
+	return new ApprovalError("approval-not-found", "approval was not found");
+}
+function cloud(options = {}) {
+	const { issuer: root, jwks, request } = cloudConnection(options);
+	const flushAt = options.flushAt ?? 32;
+	const waitUntil = options.waitUntil;
+	const approvals = {
+		async create(record) {
+			if (!(await request("/approvals", {
+				method: "POST",
+				body: JSON.stringify(record)
+			})).ok) throw new Error("PermDock Cloud rejected the approval create");
+		},
+		async get(token) {
+			try {
+				const response = await request("/approvals/by-token", { headers: { [APPROVAL_HEADER]: token } });
+				if (!response.ok) return null;
+				return asApproval(await response.json());
+			} catch {
+				return null;
+			}
+		},
+		async getById(id) {
+			try {
+				const response = await request(`/approvals/${encodeURIComponent(id)}`);
+				if (!response.ok) return null;
+				return asApproval(await response.json());
+			} catch {
+				return null;
+			}
+		},
+		async resolve(token, verdict) {
+			const approver = await approverHeaders(verdict, options.approver, root, async () => {
+				const response = await request("/approvals/by-token", { headers: { [APPROVAL_HEADER]: token } });
+				if (!response.ok) throw await approvalErrorFrom(response);
+				const found = parseApprovalRequest(await response.json());
+				if (found === null) throw new ApprovalError("approval-not-found", "PermDock Cloud returned an unknown approval shape");
+				const etag = response.headers.get("etag");
+				return etag === null ? { request: found } : {
+					request: found,
+					etag
+				};
+			});
+			const response = await request("/approvals/by-token/resolve", {
+				method: "POST",
+				headers: {
+					[APPROVAL_HEADER]: token,
+					...approver
+				},
+				body: JSON.stringify(verdict)
+			});
+			if (!response.ok) throw await approvalErrorFrom(response);
+			const parsed = asApproval(await response.json());
+			if (parsed === null) throw new ApprovalError("approval-not-found", "PermDock Cloud returned an unknown approval shape");
+			return parsed;
+		},
+		async consume(token, now) {
+			try {
+				const response = await request("/approvals/by-token/consume", {
+					method: "POST",
+					headers: { [APPROVAL_HEADER]: token },
+					body: JSON.stringify(compact({ now: now === void 0 ? void 0 : dateAt(now).toISOString() }))
+				});
+				if (!response.ok) return null;
+				return asApproval(await response.json());
+			} catch {
+				return null;
+			}
+		},
+		async list(query) {
+			const params = new URLSearchParams(compact({
+				status: query.status,
+				principalId: query.principalId,
+				actorId: query.actorId,
+				tenant: query.tenant,
+				session: query.session,
+				limit: query.limit === void 0 ? void 0 : String(query.limit),
+				cursor: query.cursor
+			}));
+			const suffix = params.size === 0 ? "" : `?${params.toString()}`;
+			try {
+				const response = await request(`/approvals${suffix}`);
+				if (!response.ok) return { items: [] };
+				const body = await response.json();
+				if (!isRecord(body) || !Array.isArray(body["items"])) return { items: [] };
+				const items = body["items"].flatMap((item) => {
+					const parsed = asApproval(item);
+					return parsed === null ? [] : [parsed];
+				});
+				return typeof body["next"] === "string" && body["next"] !== "" ? {
+					items,
+					next: body["next"]
+				} : { items };
+			} catch {
+				return { items: [] };
+			}
+		},
+		async cancel(filter, meta) {
+			const response = await request("/approvals/cancel", {
+				method: "POST",
+				body: JSON.stringify(compact({
+					filter,
+					by: meta.by,
+					note: meta.note
+				}))
+			});
+			if (!response.ok) throw new Error("PermDock Cloud rejected the approval cancel");
+			const body = await response.json();
+			if (!isRecord(body) || typeof body["cancelled"] !== "number") throw new Error("PermDock Cloud returned an unknown cancel shape");
+			return body["cancelled"];
+		},
+		async expire(now) {
+			try {
+				const response = await request("/approvals/expire", {
+					method: "POST",
+					body: JSON.stringify(compact({ now: now === void 0 ? void 0 : dateAt(now).toISOString() }))
+				});
+				if (!response.ok) return 0;
+				const body = await response.json();
+				if (!isRecord(body) || typeof body["expired"] !== "number") return 0;
+				return body["expired"];
+			} catch {
+				return 0;
+			}
+		}
+	};
+	const capacity = options.capacity ?? 1e4;
+	const source = options.source ?? root;
+	if (!isAbsoluteUri(source)) throw new TypeError("PermDock: cloud() source is an absolute URI");
+	const pending = [];
+	const bound = () => {
+		if (pending.length > capacity) pending.splice(0, pending.length - capacity);
+	};
+	const flush = async () => {
+		if (pending.length === 0) return;
+		const events = pending.splice(0);
+		try {
+			if (!(await request("/decisions", {
+				method: "POST",
+				body: JSON.stringify(events.map((event) => toCloudEvent(event, { source })))
+			}, void 0, "application/cloudevents-batch+json")).ok) pending.unshift(...events);
+		} catch {
+			pending.unshift(...events);
+		}
+		bound();
+	};
+	const sink = {
+		write(events) {
+			pending.push(...events);
+			bound();
+			if (pending.length >= flushAt) return flush();
+			if (waitUntil !== void 0 && pending.length > 0) waitUntil(flush());
+		},
+		flush
+	};
+	const snapshotsFor = (subject) => ({ async get() {
+		const response = await request("/snapshot", { headers: { [SUBJECT_HEADER]: subject } }, "application/jwt");
+		if (!response.ok) throw new Error("PermDock Cloud snapshot request failed");
+		const text = (await response.text()).trim();
+		if (!isCompactJws(text)) throw new Error("PermDock Cloud served an unsigned snapshot");
+		return text;
+	} });
+	let document = null;
+	return freezeDeep({
+		approvals,
+		sink,
+		snapshotsFor,
+		policies: {
+			current() {
+				return document;
+			},
+			async refresh() {
+				const verifier = options.verifier;
+				if (verifier === void 0) return;
+				let response;
+				try {
+					response = await request("/policy");
+				} catch {
+					return;
+				}
+				if (response.status === 404) {
+					document = null;
+					return;
+				}
+				if (!response.ok) return;
+				const token = (await response.text()).trim();
+				if (!isCompactJws(token)) return;
+				const verified = await verifier.verify(token, {
+					typ: "vnd.permdock.policy+jwt",
+					issuer: root,
+					audience: root
+				});
+				if (!verified.ok) return;
+				let next;
+				try {
+					next = policyDocumentFromClaims(verified.claims);
+				} catch {
+					return;
+				}
+				document = next;
+			}
+		},
+		catalog: { async push(value) {
+			const fingerprint = catalogFingerprint(value);
+			const response = await request("/catalog", {
+				method: "POST",
+				body: JSON.stringify({
+					fingerprint,
+					catalog: value
+				})
+			});
+			if (!response.ok) throw new Error(`PermDock Cloud rejected the catalog: HTTP ${String(response.status)}`);
+			const parsed = catalogPushOf(await response.json());
+			if (parsed === null) throw new Error("PermDock Cloud answered the catalog push in an unknown shape");
+			return parsed;
+		} },
+		issuer: root,
+		jwks
+	});
+}
+//#endregion
+export { approverHeaders as a, isCompactJws as i, cloudConnection as n, cloudEndpoints as r, cloud as t };

package/dist/create-C3b4B5eF.js

@@ -0,0 +1,130 @@
+import { t as compact } from "./compact-CAf557ZB.js";
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+import { a as deniedFor } from "./where-scope-Dv-WTP-w.js";
+import { c as withApp } from "./permdock-B9JxkBwC.js";
+import { t as composeWraps } from "./wrap-gX61EtpB.js";
+import { r as instanceOptions } from "./build-instance-BMnAudHn.js";
+import { n as createAgentKernel } from "./kernel-5JatXyND.js";
+//#region src/agent/create.ts
+function modelRow(modelId) {
+	return { id: modelId };
+}
+function unlistedModel(modelId) {
+	return freezeDeep({
+		outcome: "denied",
+		denials: [{
+			role: null,
+			reason: "no-grant",
+			detail: { model: modelId }
+		}],
+		alternatives: []
+	});
+}
+function decideModelOn(permdock, models, modelId, adapter) {
+	const permission = models !== void 0 && Object.hasOwn(models, modelId) ? models[modelId] : void 0;
+	if (permission === void 0) return unlistedModel(modelId);
+	try {
+		return permdock.decide(permission, permission.kind === "instance" ? modelRow(modelId) : void 0, {
+			trusted: true,
+			adapter,
+			call: "adapter",
+			model: modelId
+		});
+	} catch {
+		return deniedFor(permission, "closure-error");
+	}
+}
+/** Builds the agent contract and its kernel for an adapter named `adapter`. */
+function agentRuntime(policy, options, adapter) {
+	const kernel = createAgentKernel(policy, {
+		...compact({
+			actor: options.actor,
+			delegation: options.delegation,
+			tenant: options.tenant,
+			store: options.store,
+			context: options.context,
+			wrap: composeWraps(options.otel, options.wrap),
+			deniedText: options.deniedText
+		}),
+		...instanceOptions(options),
+		subject: options.subject,
+		tools: options.operations,
+		adapter
+	});
+	const operations = options.operations;
+	const bindingOf = (name) => Object.hasOwn(operations, name) ? operations[name] : void 0;
+	const decideModel = async (modelId, context) => {
+		try {
+			return decideModelOn(await kernel.instance(context), options.models, modelId, adapter);
+		} catch {
+			return unlistedModel(modelId);
+		}
+	};
+	const permittedModels = async (context) => {
+		if (options.models === void 0) return [];
+		let permdock;
+		try {
+			permdock = await kernel.instance(context);
+		} catch {
+			return [];
+		}
+		return Object.keys(options.models).filter((modelId) => decideModelOn(permdock, options.models, modelId, adapter).outcome === "granted");
+	};
+	const filterResults = async (name, rows, context) => {
+		const binding = bindingOf(name);
+		if (binding === void 0) return [];
+		if (binding.results === void 0) return [...rows];
+		try {
+			const permdock = await kernel.instance(context);
+			const results = binding.results;
+			if (results.kind !== "instance") return permdock.can(results, void 0) ? [...rows] : [];
+			await permdock.prefetchRelations(results, rows);
+			return permdock.filter(results, rows, {
+				adapter,
+				call: "filter"
+			});
+		} catch {
+			return [];
+		}
+	};
+	const gatewayOptions = async (context) => {
+		let permdock;
+		try {
+			permdock = await kernel.instance(context);
+		} catch {
+			return { gateway: {} };
+		}
+		const { principal, actor } = permdock.subject;
+		const tags = [...principal?.tenant === void 0 ? [] : [`tenant:${principal.tenant}`], ...actor === void 0 ? [] : [`actor:${actor.kind}`]];
+		return { gateway: compact({
+			user: principal?.id,
+			tags: tags.length > 0 ? tags : void 0
+		}) };
+	};
+	return {
+		agent: Object.freeze({
+			getPermDock: (context) => kernel.instance(context),
+			decideOperation: (name, input, context, decideOptions) => kernel.decideTool(name, input, context, decideOptions),
+			allowedOperations: (context) => kernel.allowedToolNames(context),
+			tokenFor: (name, input, context) => {
+				const binding = bindingOf(name);
+				return binding === void 0 ? Promise.resolve(void 0) : kernel.tokenFor(binding, input, context);
+			},
+			decideModel,
+			permittedModels,
+			filterResults,
+			gatewayOptions
+		}),
+		kernel
+	};
+}
+/**
+* The agent contract for a runtime PermDock has no adapter for: decide
+* operations by name, gate models and filter results. The subject comes from
+* `subject(context)` on the server, never from model output.
+*/
+function createPermDock(policy, given) {
+	return agentRuntime(policy, withApp(policy, given), "agent").agent;
+}
+//#endregion
+export { createPermDock as n, agentRuntime as t };