permdock 0.0.0 → 0.2.0

package/dist/cloud/index.js

@@ -0,0 +1,404 @@
+import { t as compact } from "../compact-y6vfu2_f.js";
+import { n as freezeDeep } from "../freeze-CrU8nQeX.js";
+import { T as isForbiddenKey } from "../permissions-DVoF6dMt.js";
+import { i as parsePolicyDocument } from "../hosted-DJQw46hn.js";
+import { t as CLOUD_EVENT_TYPES } from "../sink-Bd9PSyfq.js";
+import { r as isApprovalErrorCode, t as ApprovalError } from "../errors-DRnGZHzF.js";
+import { t as joseTokenVerifier } from "../verifier-BxBo6I44.js";
+import { t as timeoutSignal } from "../timeout-D51niuQP.js";
+//#region src/cloud/create.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;
+}
+function isRecord$1(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function asApproval(value) {
+	if (!isRecord$1(value) || value["v"] !== 1 || typeof value["token"] !== "string") return null;
+	return value;
+}
+function isCompactJws$1(value) {
+	return !value.startsWith("{") && value.split(".").length === 3;
+}
+/** 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");
+}
+/**
+* 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`
+	});
+}
+function cloud(options = {}) {
+	const key = firstNonEmpty(options.key, readEnv("PERMDOCK_CLOUD_KEY"));
+	if (key === "") throw new Error("PermDock: cloud() requires url and key.");
+	const { issuer: root, jwks } = cloudEndpoints(options);
+	const fetchFn = options.fetch ?? globalThis.fetch.bind(globalThis);
+	const flushAt = options.flushAt ?? 32;
+	const waitUntil = options.waitUntil;
+	const headers = () => {
+		const next = new Headers();
+		next.set("authorization", `Bearer ${key}`);
+		next.set("content-type", "application/json");
+		return next;
+	};
+	const request = (path, init = {}, accept) => {
+		const next = headers();
+		if (accept !== void 0) next.set("accept", accept);
+		return fetchFn(`${root}${path}`, {
+			...init,
+			headers: next,
+			signal: timeoutSignal(CLOUD_TIMEOUT_MS, init.signal)
+		});
+	};
+	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/${encodeURIComponent(token)}`);
+				if (!response.ok) return null;
+				return asApproval(await response.json());
+			} catch {
+				return null;
+			}
+		},
+		async resolve(token, verdict) {
+			const response = await request(`/approvals/${encodeURIComponent(token)}/resolve`, {
+				method: "POST",
+				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/${encodeURIComponent(token)}/consume`, {
+					method: "POST",
+					body: JSON.stringify(compact({ now: now === void 0 ? void 0 : 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$1(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$1(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 : now.toISOString() }))
+				});
+				if (!response.ok) return 0;
+				const body = await response.json();
+				if (!isRecord$1(body) || typeof body["expired"] !== "number") return 0;
+				return body["expired"];
+			} catch {
+				return 0;
+			}
+		}
+	};
+	const capacity = options.capacity ?? 1e4;
+	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 })
+			})).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 snapshots = { async get() {
+		const response = await request("/snapshot", {}, "application/jwt");
+		if (!response.ok) throw new Error("PermDock Cloud snapshot request failed");
+		const text = (await response.text()).trim();
+		if (!isCompactJws$1(text)) throw new Error("PermDock Cloud served an unsigned snapshot");
+		return text;
+	} };
+	let document = null;
+	return freezeDeep({
+		approvals,
+		sink,
+		snapshots,
+		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$1(token)) return;
+				const verified = await verifier.verify(token, {
+					typ: "permdock-policy+jwt",
+					issuer: root,
+					audience: root
+				});
+				if (!verified.ok) return;
+				let next;
+				try {
+					next = parsePolicyDocument(verified.claims["policy"]);
+				} catch {
+					return;
+				}
+				document = next;
+			}
+		},
+		issuer: root,
+		jwks
+	});
+}
+//#endregion
+//#region src/cloud/webhook.ts
+const TYPES = new Set(Object.values(CLOUD_EVENT_TYPES));
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function hasUnsafeKey(value) {
+	if (Array.isArray(value)) return value.some(hasUnsafeKey);
+	if (!isRecord(value)) return false;
+	return Object.keys(value).some((key) => isForbiddenKey(key) || hasUnsafeKey(value[key]));
+}
+const FINDING_CODES = /* @__PURE__ */ new Set([
+	"permission-removed",
+	"not-hostable",
+	"grantee-removed",
+	"approval-tightened"
+]);
+function isFinding(value) {
+	return isRecord(value) && FINDING_CODES.has(value["code"]) && typeof value["permission"] === "string" && (value["grant"] === void 0 || typeof value["grant"] === "string");
+}
+function validData(type, data) {
+	switch (type) {
+		case "dev.permdock.decision": return data["type"] === "decision" && typeof data["permission"] === "string";
+		case "dev.permdock.approval": return data["type"] === "decision" && (data["phase"] === "requested" || data["phase"] === "resolved");
+		case "dev.permdock.directory": return data["type"] === "directory" && typeof data["tenant"] === "string";
+		case "dev.permdock.membership": return data["type"] === "membership" && isRecord(data["principal"]);
+		case "dev.permdock.credential": return data["type"] === "credential" && isRecord(data["credential"]) && typeof data["credential"]["id"] === "string" && (data["credential"]["kind"] === "user" || data["credential"]["kind"] === "service") && isRecord(data["principal"]) && (data["operation"] === "created" || data["operation"] === "used" || data["operation"] === "rotated" || data["operation"] === "revoked");
+		case "dev.permdock.catalog": return (data["kind"] === "publish" || data["kind"] === "drift") && typeof data["fingerprint"] === "string" && (data["previous"] === void 0 || typeof data["previous"] === "string") && (data["findings"] === void 0 || Array.isArray(data["findings"]) && data["findings"].every(isFinding));
+		case "dev.permdock.access.started":
+		case "dev.permdock.access.ended":
+		case "dev.permdock.access.revoked": return data["type"] === "access" && typeof data["tenant"] === "string" && isRecord(data["principal"]) && typeof data["principal"]["id"] === "string";
+		default: return type;
+	}
+}
+/**
+* Validates one CloudEvent against the closed type list and its data shape;
+* returns `null` for anything else, never throws.
+*/
+function parseCloudEvent(value) {
+	if (!isRecord(value) || hasUnsafeKey(value) || value["specversion"] !== "1.0" || typeof value["type"] !== "string" || !TYPES.has(value["type"]) || typeof value["source"] !== "string" || typeof value["id"] !== "string" || typeof value["time"] !== "string" || value["subject"] !== void 0 && typeof value["subject"] !== "string" || !isRecord(value["data"]) || !validData(value["type"], value["data"])) return null;
+	return freezeDeep(JSON.parse(JSON.stringify(value)));
+}
+function verifierFor(options) {
+	if (options.verifier !== void 0) return options.verifier;
+	if (options.jwks === void 0) return;
+	try {
+		return joseTokenVerifier({
+			jwks: typeof options.jwks === "string" ? new URL(options.jwks) : options.jwks,
+			algorithms: ["Ed25519", "ES256"]
+		});
+	} catch {
+		return;
+	}
+}
+function isCompactJws(value) {
+	return /^[\w-]+\.[\w-]+\.[\w-]+$/u.test(value);
+}
+/**
+* Verifies a PermDock Cloud webhook delivery: a compact JWS with
+* `typ: permdock-decisions+jwt` whose `events` claim holds CloudEvents.
+* There is no unsigned mode, and it never throws.
+*/
+async function verifyWebhook(request, options) {
+	let body;
+	try {
+		body = (await request.text()).trim();
+	} catch {
+		return {
+			ok: false,
+			reason: "unsigned"
+		};
+	}
+	if (!isCompactJws(body)) return {
+		ok: false,
+		reason: "unsigned"
+	};
+	const verifier = verifierFor(options);
+	if (verifier === void 0) return {
+		ok: false,
+		reason: "invalid-token",
+		cause: "jwks-unavailable"
+	};
+	let verified;
+	try {
+		verified = await verifier.verify(body, {
+			typ: "permdock-decisions+jwt",
+			audience: options.audience
+		});
+	} catch {
+		return {
+			ok: false,
+			reason: "invalid-token",
+			cause: "malformed"
+		};
+	}
+	if (!verified.ok) return {
+		ok: false,
+		reason: "invalid-token",
+		cause: verified.cause
+	};
+	const jti = verified.claims["jti"];
+	const raw = verified.claims["events"];
+	if (typeof jti !== "string" || !Array.isArray(raw)) return {
+		ok: false,
+		reason: "invalid-events"
+	};
+	const events = [];
+	for (const item of raw) {
+		const parsed = parseCloudEvent(item);
+		if (parsed === null) return {
+			ok: false,
+			reason: "invalid-events"
+		};
+		events.push(parsed);
+	}
+	if (options.replay !== void 0) {
+		const key = `permdock-webhook:${jti}`;
+		const expiresAt = typeof verified.claims.exp === "number" ? verified.claims.exp : void 0;
+		try {
+			if (options.replay.claim === void 0) {
+				if (await options.replay.seen(key)) return {
+					ok: false,
+					reason: "replayed"
+				};
+				await options.replay.remember(key, expiresAt);
+			} else if (!await options.replay.claim(key, expiresAt)) return {
+				ok: false,
+				reason: "replayed"
+			};
+		} catch {
+			return {
+				ok: false,
+				reason: "replayed"
+			};
+		}
+	}
+	return freezeDeep({
+		ok: true,
+		id: jti,
+		events
+	});
+}
+//#endregion
+export { cloud, cloudEndpoints, parseCloudEvent, verifyWebhook };

package/dist/cloud-BGhHS-lY.js

@@ -0,0 +1,50 @@
+import { i as globalArgs, s as stringArg, t as COMMAND_DESCRIPTIONS } from "./commands-DWOrSQic.js";
+import { defineCommand } from "citty";
+//#region src/cli/commands/cloud.ts
+function cloud(ctx) {
+	return defineCommand({
+		meta: {
+			name: "cloud",
+			description: COMMAND_DESCRIPTIONS.cloud
+		},
+		args: {
+			...globalArgs,
+			action: {
+				type: "positional",
+				required: false,
+				description: "push"
+			},
+			"dry-run": {
+				type: "boolean",
+				description: "Print the payload; send nothing"
+			},
+			url: {
+				type: "string",
+				description: "Cloud API base URL",
+				valueHint: "url"
+			},
+			environment: {
+				type: "string",
+				description: "Target environment",
+				valueHint: "env"
+			}
+		},
+		async run({ args: parsed }) {
+			const result = await (await import("./cloud-Bo3e9Ak3.js")).runCloud({
+				cwd: ctx.cwd,
+				config: ctx.config,
+				rest: parsed._,
+				url: stringArg(parsed.url),
+				environment: stringArg(parsed.environment),
+				dryRun: parsed["dry-run"] === true,
+				json: ctx.json,
+				env: ctx.io.env ?? process.env,
+				now: ctx.now,
+				io: ctx.io
+			});
+			ctx.report(result);
+		}
+	});
+}
+//#endregion
+export { cloud };

package/dist/cloud-Bo3e9Ak3.js

@@ -0,0 +1,118 @@
+import { t as catalogFingerprint } from "./src-CSbUiozF.js";
+import { s as snapshotScopes } from "./permdock-CzqXjCpU.js";
+import { i as describeError } from "./errors-CWfoNg9N.js";
+import { i as loadConfiguredPolicy } from "./load-DhWEB9P1.js";
+import { t as parseCatalog } from "./parse-BuyjxhZV.js";
+import { t as runCatalog } from "./catalog-z8q6bi_r.js";
+//#region src/cli/cloud.ts
+function firstNonEmpty(...values) {
+	for (const value of values) if (value !== void 0 && value !== "") return value;
+	return "";
+}
+function pushedGrant(grant) {
+	const entry = {
+		permission: grant.permission.key,
+		effect: grant.effect,
+		role: grant.role,
+		to: grant.to,
+		where: grant.portable ? grant.where : void 0,
+		check: grant.portable ? grant.check : void 0,
+		approval: grant.approval,
+		scope: grant.scope === "global" ? void 0 : typeof grant.scope === "string" ? grant.scope : { resource: grant.scope.resource },
+		portable: grant.portable ? void 0 : false,
+		fields: grant.fields,
+		limit: grant.limit
+	};
+	return Object.fromEntries(Object.entries(entry).filter(([, value]) => value !== void 0));
+}
+/** The code policy as the hosted AuthZEN endpoint evaluates it; closures travel as `portable: false` and deny there. */
+function pushedPolicy(policy) {
+	const scopes = snapshotScopes(policy);
+	return {
+		fingerprint: policy.fingerprint,
+		...scopes === void 0 ? {} : { scopes },
+		grants: policy.grants.filter((grant) => grant.hosted === void 0).map(pushedGrant)
+	};
+}
+async function runCloud(input) {
+	if (input.rest[0] !== "push") return {
+		code: 2,
+		output: `usage: permdock cloud push [--dry-run] [--url <url>] [--environment <env>]`
+	};
+	const built = await runCatalog({
+		cwd: input.cwd,
+		config: input.config,
+		format: "json",
+		from: void 0,
+		include: [],
+		now: input.now,
+		io: input.io
+	});
+	if (built.code !== 0) return {
+		code: built.code,
+		output: built.output
+	};
+	const catalog = parseCatalog(built.output);
+	const fingerprint = catalogFingerprint(catalog);
+	const loaded = await loadConfiguredPolicy(input.cwd, input.config.policy);
+	const policy = loaded === void 0 ? void 0 : pushedPolicy(loaded);
+	const hostable = catalog.permissions.filter((permission) => permission.hostable === true).map((permission) => permission.key);
+	const summary = {
+		fingerprint,
+		permissions: catalog.permissions.length,
+		hostable,
+		roles: (catalog.roles ?? []).length,
+		plans: (catalog.plans ?? []).length,
+		grants: policy?.grants.length ?? 0
+	};
+	const url = firstNonEmpty(input.url, input.env["PERMDOCK_CLOUD_URL"]).replace(/\/$/u, "");
+	const environment = firstNonEmpty(input.environment, input.env["PERMDOCK_CLOUD_ENV"], input.env["VERCEL_ENV"], "production");
+	const describe = (verb) => input.json ? JSON.stringify({
+		...summary,
+		environment,
+		status: verb
+	}) : `${verb} catalog ${fingerprint} (${String(summary.permissions)} permissions, ${String(hostable.length)} hostable) to ${environment}`;
+	if (input.dryRun) return {
+		code: 0,
+		output: describe("would push")
+	};
+	const key = input.env["PERMDOCK_CLOUD_KEY"] ?? "";
+	if (url === "" || key === "") return {
+		code: 2,
+		output: "permdock cloud push needs PERMDOCK_CLOUD_URL (or --url) and PERMDOCK_CLOUD_KEY in the environment"
+	};
+	const fetchFn = input.io.fetch ?? globalThis.fetch.bind(globalThis);
+	let response;
+	try {
+		response = await fetchFn(`${url}/v1/environments/${encodeURIComponent(environment)}/catalog`, {
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${key}`,
+				"content-type": "application/json"
+			},
+			body: JSON.stringify(policy === void 0 ? {
+				fingerprint,
+				catalog
+			} : {
+				fingerprint,
+				catalog,
+				policy
+			})
+		});
+	} catch (error) {
+		return {
+			code: 1,
+			output: `PermDock Cloud unreachable: ${describeError(error)}`
+		};
+	}
+	if (!response.ok) return {
+		code: 1,
+		output: `PermDock Cloud rejected the catalog: HTTP ${String(response.status)}`
+	};
+	return {
+		code: 0,
+		output: describe("pushed")
+	};
+}
+//#endregion
+export { runCloud };