permdock 0.0.0 → 0.2.0

package/dist/approvals-DbYAuNkG.js

@@ -0,0 +1,224 @@
+import { t as compact } from "./compact-y6vfu2_f.js";
+import { t as PROBLEM_BASE } from "./validation-error-CnjZ4t92.js";
+import { s as rootMembershipId } from "./scopes-CVdPrWN-.js";
+import { n as isApprovalError } from "./errors-DRnGZHzF.js";
+import { n as hasCredentials } from "./http-SO7qGttf.js";
+import { l as unauthenticatedProblem } from "./problem-B43ztKIm.js";
+import { n as assertApprover } from "./store-DMAWwAJV.js";
+import { m as approverRelations, p as heldPermissions } from "./helpers-H_KARDVC.js";
+//#region src/approvals/handler.ts
+function problem(status, title, detail, slug) {
+	const body = {
+		type: `${PROBLEM_BASE}/${slug}`,
+		title,
+		status,
+		detail
+	};
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "content-type": "application/problem+json" }
+	});
+}
+function json(status, body) {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "content-type": "application/json" }
+	});
+}
+function parseRoute(url, method) {
+	const parts = url.pathname.replace(/\/+$/u, "").split("/").filter(Boolean);
+	const last = parts.at(-1);
+	const prev = parts.at(-2);
+	if (last === void 0) return;
+	if (method === "GET" && last === "pending") return { kind: "pending" };
+	if (method === "GET" && last === "mine") return { kind: "mine" };
+	if (method === "POST" && last === "approve" && prev !== void 0) return {
+		kind: "approve",
+		token: decodeURIComponent(prev)
+	};
+	if (method === "POST" && last === "reject" && prev !== void 0) return {
+		kind: "reject",
+		token: decodeURIComponent(prev)
+	};
+	if (method === "GET" && last !== "pending" && last !== "mine") return {
+		kind: "get",
+		token: decodeURIComponent(last)
+	};
+}
+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 mayResolve(request, subject, requireDistinct, options) {
+	try {
+		const relations = await approverRelations(request, subject, options);
+		const permissions = await heldPermissions(request, subject, options.permdockFor);
+		assertApprover(request, subject, requireDistinct, /* @__PURE__ */ new Date(), relations, permissions);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function canView(request, subject) {
+	const principal = subject.principal;
+	if (principal === null) return false;
+	if (request.subject.principal?.id === principal.id) return true;
+	const tenant = request.subject.principal?.tenant;
+	if (tenant !== void 0) return belongsToTenant(subject, tenant);
+	return true;
+}
+/**
+* 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
+	};
+}
+function signedApproval(request, signer, audience) {
+	if (signer === void 0 || request.status !== "approved") return Promise.resolve(void 0);
+	const payload = { approval: {
+		token: request.token,
+		permission: request.permission,
+		resource: request.resource,
+		status: request.status
+	} };
+	if (request.subject.principal !== null) payload["sub"] = request.subject.principal.id;
+	return signer.sign(payload, compact({
+		typ: "permdock-approval+jwt",
+		audience,
+		expiresAt: Math.floor(Date.parse(request.expiresAt) / 1e3)
+	}));
+}
+async function readNote(request) {
+	const contentType = request.headers.get("content-type") ?? "";
+	if (request.method !== "POST" || contentType === "") return;
+	if (!contentType.includes("application/json")) return;
+	try {
+		const body = await request.json();
+		if (body !== null && typeof body === "object" && "note" in body && typeof body.note === "string") return body.note;
+	} catch {
+		return;
+	}
+}
+function mapError(error, credentials) {
+	if (!isApprovalError(error)) return problem(500, "Internal error", "approval store failed", "internal");
+	if (error.code === "approval-not-found") return problem(404, "Not found", error.message, "not-found");
+	if (error.code === "approval-not-pending" || error.code === "approval-expired" || error.code === "approver-repeated") return problem(409, "Conflict", error.message, "conflict");
+	if (error.code === "approver-unauthenticated") return unauthenticatedProblem(credentials);
+	return problem(403, "Permission denied", error.message, "denied");
+}
+function approvalsHandler(store, options) {
+	const requireDistinct = options.requireDistinctApprover === true;
+	return async (request) => {
+		const url = new URL(request.url);
+		const route = parseRoute(url, request.method);
+		if (route === void 0) return problem(405, "Method not allowed", "unknown approvals route", "method-not-allowed");
+		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 {
+			if (route.kind === "pending") {
+				const scoped = inboxScope(url, subject);
+				if (!scoped.ok) return problem(403, "Permission denied", "approver does not belong to that tenant", "denied");
+				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),
+					next: page.next
+				}));
+			}
+			if (route.kind === "mine") {
+				const page = await store.list({
+					...pageQuery(url),
+					principalId: principal.id
+				});
+				return json(200, compact({
+					items: page.items,
+					next: page.next
+				}));
+			}
+			if (route.kind === "get") {
+				const current = await store.get(route.token);
+				if (current === null || !canView(current, subject)) return problem(404, "Not found", "approval was not found", "not-found");
+				return json(200, current);
+			}
+			const current = await store.get(route.token);
+			if (current === null) return problem(404, "Not found", "approval was not found", "not-found");
+			const relations = await approverRelations(current, subject, options);
+			const permissions = await heldPermissions(current, subject, options.permdockFor);
+			assertApprover(current, subject, requireDistinct, /* @__PURE__ */ new Date(), relations, permissions);
+			const note = await readNote(request);
+			const resolved = await store.resolve(route.token, compact({
+				status: route.kind === "approve" ? "approved" : "rejected",
+				by: subject,
+				note,
+				relations,
+				permissions
+			}));
+			const signed = await signedApproval(resolved, options.signer, options.audience);
+			return json(200, compact({
+				...resolved,
+				signed
+			}));
+		} catch (error) {
+			return mapError(error, hasCredentials(request));
+		}
+	};
+}
+//#endregion
+export { approvalsHandler as t };

package/dist/approvers-DT4AVyIg.js

@@ -0,0 +1,52 @@
+import { n as isReadonlyArray } from "./compact-y6vfu2_f.js";
+//#region src/core/approvers.ts
+/** Approves when the approver holds `permission` in the request's tenant (any role, custom roles included). */
+function holder(permission) {
+	const key = permission?.key;
+	if (typeof key !== "string" || key === "") throw new Error("PermDock: holder() needs a permission");
+	return Object.freeze({
+		kind: "permission",
+		permission: key
+	});
+}
+/** Approves when the approver matches any one of `items`. */
+function anyOf(...items) {
+	if (items.length === 0) throw new Error("PermDock: anyOf() needs at least one approver");
+	return Object.freeze({
+		kind: "any-of",
+		of: Object.freeze([...items])
+	});
+}
+/** Approves when the approver matches every one of `items`; the same as a list. */
+function allOf(...items) {
+	if (items.length === 0) throw new Error("PermDock: allOf() needs at least one approver");
+	return Object.freeze([...items]);
+}
+/** A named approver for `approval.by`, matched on the approver's principal id. */
+function user(id) {
+	if (typeof id !== "string" || id === "") throw new Error("PermDock: user() needs a non-empty principal id");
+	return Object.freeze({
+		kind: "user",
+		id
+	});
+}
+function isUserApprover(value) {
+	return value !== null && typeof value === "object" && "kind" in value && value.kind === "user";
+}
+function flattenApprovers(input) {
+	if (input === void 0) return [];
+	if (isReadonlyArray(input)) return input;
+	return [input];
+}
+/** Every approver `input` names, inside `anyOf` groups too, for reading facts and labels. */
+function approverLeaves(input) {
+	return flattenApprovers(input).flatMap((item) => item.kind === "any-of" ? item.of.flatMap((entry) => approverLeaves(entry)) : [item]);
+}
+function isPermissionApprover(value) {
+	return value !== null && typeof value === "object" && "kind" in value && value.kind === "permission";
+}
+function isAnyOfInput(value) {
+	return value !== null && typeof value === "object" && "kind" in value && value.kind === "any-of";
+}
+//#endregion
+export { holder as a, isUserApprover as c, flattenApprovers as i, user as l, anyOf as n, isAnyOfInput as o, approverLeaves as r, isPermissionApprover as s, allOf as t };

package/dist/arazzo-BAgw9ap6.js

@@ -0,0 +1,70 @@
+import { u as arazzoFindings } from "./snapshot-Enxd0n-s.js";
+import { a as loadModule, o as pickNamed, t as asPermissionTree } from "./load-DhWEB9P1.js";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+//#region src/cli/arazzo.ts
+async function runArazzo(input) {
+	if (input.rest[0] !== "check") return {
+		code: 2,
+		output: "permdock arazzo check --doc <arazzo> --openapi <doc>"
+	};
+	const docPath = input.doc;
+	const openapiPath = input.openapi;
+	if (docPath === void 0 || openapiPath === void 0) return {
+		code: 2,
+		output: "arazzo check requires --doc and --openapi"
+	};
+	const arazzoFile = resolve(input.cwd, docPath);
+	const openapiFile = resolve(input.cwd, openapiPath);
+	if (!existsSync(arazzoFile) || !existsSync(openapiFile)) return {
+		code: 2,
+		output: "arazzo check: document not found"
+	};
+	let arazzo;
+	let openapi;
+	try {
+		arazzo = JSON.parse(readFileSync(arazzoFile, "utf8"));
+		openapi = JSON.parse(readFileSync(openapiFile, "utf8"));
+	} catch {
+		return {
+			code: 2,
+			output: "arazzo check: unreadable JSON"
+		};
+	}
+	const from = input.from ?? input.config.permissions;
+	let tree;
+	if (from !== void 0) {
+		const abs = resolve(input.cwd, from);
+		if (!existsSync(abs)) return {
+			code: 2,
+			output: `arazzo check: permissions not found: ${from}`
+		};
+		const mod = await loadModule(abs);
+		tree = asPermissionTree(pickNamed(mod, ["permissions"]));
+	}
+	const findings = arazzoFindings(input.workflow === void 0 ? {
+		arazzo,
+		openapi
+	} : {
+		arazzo,
+		openapi,
+		workflowId: input.workflow
+	}, tree);
+	if (input.json) return {
+		code: findings.length === 0 ? 0 : 1,
+		output: JSON.stringify({
+			$schema: "permdock-arazzo-check",
+			findings
+		})
+	};
+	if (findings.length === 0) return {
+		code: 0,
+		output: "arazzo check: all steps documented"
+	};
+	return {
+		code: 1,
+		output: findings.map((finding) => `${finding.workflowId} ${finding.stepId}: ${finding.reason} (${finding.detail})`).join("\n")
+	};
+}
+//#endregion
+export { runArazzo };

package/dist/arazzo-cmvX2jDe.js

@@ -0,0 +1,54 @@
+import { a as listArg, i as globalArgs, s as stringArg, t as COMMAND_DESCRIPTIONS } from "./commands-DWOrSQic.js";
+import { defineCommand } from "citty";
+//#region src/cli/commands/arazzo.ts
+function arazzo(ctx) {
+	return defineCommand({
+		meta: {
+			name: "arazzo",
+			description: COMMAND_DESCRIPTIONS.arazzo
+		},
+		args: {
+			...globalArgs,
+			action: {
+				type: "positional",
+				required: false,
+				description: "check"
+			},
+			doc: {
+				type: "string",
+				description: "Arazzo document",
+				valueHint: "arazzo.json"
+			},
+			openapi: {
+				type: "string",
+				description: "OpenAPI document the workflows call",
+				valueHint: "doc.json"
+			},
+			workflow: {
+				type: "string",
+				description: "Check one workflow",
+				valueHint: "id"
+			},
+			from: {
+				type: "string",
+				description: "Module exporting the policy, instead of the config",
+				valueHint: "module"
+			}
+		},
+		async run({ args: parsed, rawArgs }) {
+			const result = await (await import("./arazzo-BAgw9ap6.js")).runArazzo({
+				cwd: ctx.cwd,
+				config: ctx.config,
+				rest: parsed._,
+				doc: listArg(rawArgs, "doc")[0],
+				openapi: stringArg(parsed.openapi),
+				workflow: stringArg(parsed.workflow),
+				from: stringArg(parsed.from),
+				json: ctx.json
+			});
+			ctx.report(result);
+		}
+	});
+}
+//#endregion
+export { arazzo };

package/dist/authzen/index.d.ts

@@ -0,0 +1,39 @@
+import { C as Policy, Nr as Principal } from "../policy-CFZAr_Al.js";
+import { f as ApprovalStore } from "../types-vKyAMtcX.js";
+import { t as InstanceOptions } from "../instance-options-BK_rNOSC.js";
+//#region src/authzen/types.d.ts
+type AuthzenResourceAdapter = {
+  readonly load?: (id: string) => unknown;
+  readonly list?: (query: {
+    readonly where?: unknown;
+  }) => readonly unknown[] | Promise<readonly unknown[]>;
+};
+type AuthzenSubjectRecord = {
+  readonly id: string;
+  readonly [key: string]: unknown;
+};
+type AuthzenPermDockOptions<TUser = unknown> = InstanceOptions & {
+  readonly subject: (request: Request) => TUser | Promise<TUser>;
+  readonly anonymous?: boolean;
+  /**
+   * Allow-list over the authenticated PEP. Only a PEP it returns `true` for
+   * may evaluate the body's `subject`, `actor` and `delegation`; every other
+   * caller is evaluated as itself. Off by default.
+   */
+  readonly trustedPep?: (pep: unknown) => boolean;
+  readonly resources?: Readonly<Record<string, AuthzenResourceAdapter>>;
+  readonly subjects?: {
+    readonly list?: () => readonly AuthzenSubjectRecord[] | Promise<readonly AuthzenSubjectRecord[]>;
+  };
+  readonly store?: ApprovalStore;
+  readonly maxEvaluations?: number;
+};
+type AuthzenPermDock = {
+  readonly permdockHandler: (request: Request) => Promise<Response>;
+};
+type AuthzenFactory = <TUser, TPrincipal extends Principal = Principal>(policy: Policy<TUser, TPrincipal>, options: AuthzenPermDockOptions<TUser>) => AuthzenPermDock;
+//#endregion
+//#region src/authzen/create.d.ts
+export declare const createPermDock: AuthzenFactory;
+//#endregion
+export type { AuthzenFactory, AuthzenPermDock, AuthzenPermDockOptions, AuthzenResourceAdapter, AuthzenSubjectRecord };