permdock 0.0.0 → 0.2.0

package/dist/openapi-CqqEbHsL.js

@@ -0,0 +1,250 @@
+import { n as validateOverlay, t as validateOpenapi } from "./openapi-schema--ARjyfQr.js";
+import { c as getResource, i as findPermission } from "./permissions-DVoF6dMt.js";
+import { a as definePolicy } from "./policy-xyWg7QdR.js";
+import { a as loadModule, n as asPolicy, o as pickNamed, t as asPermissionTree } from "./load-DhWEB9P1.js";
+import { t as shortDiff } from "./text-diff-BdkkYSbi.js";
+import { c as openapiVersion, o as createPermDock } from "./openapi-BqRBvAng.js";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+//#region src/cli/openapi.ts
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function mergeRecord(base, extra) {
+	const result = {};
+	for (const [key, value] of Object.entries(base)) result[key] = value;
+	for (const [key, value] of Object.entries(extra)) result[key] = value;
+	return result;
+}
+/** Keeps what the document already says about a scheme (flow URLs, other flows, description); PermDock owns the scopes. */
+function mergeSchemes(existing, emitted) {
+	const result = {};
+	for (const [name, scheme] of Object.entries(emitted)) {
+		const before = existing[name];
+		if (!isRecord(before) || !isRecord(scheme)) {
+			result[name] = scheme;
+			continue;
+		}
+		const beforeFlows = isRecord(before["flows"]) ? before["flows"] : {};
+		const flows = { ...beforeFlows };
+		for (const [kind, flow] of Object.entries(isRecord(scheme["flows"]) ? scheme["flows"] : {})) {
+			const previous = beforeFlows[kind];
+			flows[kind] = isRecord(previous) && isRecord(flow) ? {
+				...previous,
+				...flow
+			} : flow;
+		}
+		result[name] = {
+			...before,
+			...scheme,
+			...isRecord(scheme["flows"]) ? { flows } : {}
+		};
+	}
+	return result;
+}
+function stableJson(value) {
+	return `${JSON.stringify(value, null, 2)}\n`;
+}
+async function loadPolicy(cwd, config, from) {
+	const policyPath = from ?? config.policy;
+	if (policyPath !== void 0) {
+		const abs = resolve(cwd, policyPath);
+		return asPolicy(pickNamed(await loadModule(abs), ["policy"]));
+	}
+	const permissionsPath = config.permissions;
+	if (permissionsPath === void 0) throw new Error("PermDock CLI: openapi needs --from, policy or permissions in the config");
+	const tree = asPermissionTree(pickNamed(await loadModule(resolve(cwd, permissionsPath)), ["permissions"]));
+	return definePolicy(tree, {
+		roles: [],
+		subject: () => null
+	});
+}
+function leavesOf(policy, keys) {
+	return keys.map((key) => {
+		if (typeof key !== "string") throw new TypeError("PermDock CLI: x-permdock-permissions must be strings");
+		const leaf = findPermission(policy.permissions, key);
+		if (leaf === void 0) throw new Error(`PermDock CLI: unknown permission '${key}'`);
+		return leaf;
+	});
+}
+/** Operations carrying `x-permdock-permissions`, joined by `operationId`; those without one are findings. */
+function overlayOperations(document, policy) {
+	const operations = [];
+	const unnamed = [];
+	const secured = [];
+	const paths = isRecord(document["paths"]) ? document["paths"] : {};
+	for (const [path, item] of Object.entries(paths)) for (const [method, operation] of Object.entries(isRecord(item) ? item : {})) {
+		if (!isRecord(operation) || !Array.isArray(operation["x-permdock-permissions"])) continue;
+		const permissions = leavesOf(policy, operation["x-permdock-permissions"]);
+		const operationId = operation["operationId"];
+		if (typeof operationId !== "string" || operationId.length === 0) {
+			unnamed.push(`${method.toUpperCase()} ${path}`);
+			continue;
+		}
+		if (operation["security"] !== void 0) secured.push(operationId);
+		operations.push({
+			operationId,
+			permissions
+		});
+	}
+	return {
+		operations,
+		unnamed,
+		secured
+	};
+}
+/** `instance` when any listed permission acts on one row; the id is the last path template parameter. */
+function arityOf(policy, leaves, path) {
+	if (!leaves.some((leaf) => getResource(policy.permissions, leaf.resource)?.instanceActions.has(leaf.action) === true)) return { kind: "collection" };
+	const parameter = [...path.matchAll(/\{([^}]+)\}/gu)].at(-1)?.[1];
+	return parameter === void 0 ? { kind: "instance" } : {
+		kind: "instance",
+		parameter
+	};
+}
+function applyDocument(document, policy, openapi, arity, target) {
+	const components = isRecord(document["components"]) ? document["components"] : {};
+	const schemes = isRecord(components["securitySchemes"]) ? components["securitySchemes"] : {};
+	const nextSchemes = mergeRecord(schemes, mergeSchemes(schemes, openapi.securitySchemes()));
+	const scopeSets = [];
+	const paths = isRecord(document["paths"]) ? document["paths"] : {};
+	const nextPaths = {};
+	for (const [path, item] of Object.entries(paths)) {
+		if (!isRecord(item)) {
+			nextPaths[path] = item;
+			continue;
+		}
+		const nextItem = {};
+		for (const [method, operation] of Object.entries(item)) {
+			if (!isRecord(operation)) {
+				nextItem[method] = operation;
+				continue;
+			}
+			const keys = operation["x-permdock-permissions"];
+			if (!Array.isArray(keys)) {
+				nextItem[method] = operation;
+				continue;
+			}
+			const leaves = leavesOf(policy, keys);
+			scopeSets.push(leaves.map((leaf) => leaf.scope));
+			const described = mergeRecord(operation, openapi.describe(leaves));
+			nextItem[method] = arity ? mergeRecord(described, { "x-permdock-arity": arityOf(policy, leaves, path) }) : described;
+		}
+		nextPaths[path] = nextItem;
+	}
+	const requirements = openapi.securityProfileRequirements(scopeSets);
+	const nextComponents = mergeRecord(components, mergeRecord({ securitySchemes: nextSchemes }, requirements === void 0 ? {} : { securityProfileRequirements: requirements }));
+	return mergeRecord(document, {
+		...target === "3.3" ? { openapi: openapiVersion(target) } : {},
+		components: nextComponents,
+		paths: nextPaths,
+		"x-permdock-catalog": openapi.catalog()
+	});
+}
+function urls(values) {
+	return Object.fromEntries(Object.entries(values).filter((entry) => entry[1] !== void 0));
+}
+/** A finding when the source validates but PermDock's output does not. */
+function outputConformance(source, result, format, overlay) {
+	if (format === "overlay") {
+		if (overlay !== "1.1") return;
+		const checked = validateOverlay(result);
+		return checked.ok ? void 0 : `openapi emit: ${checked.error}`;
+	}
+	if (!validateOpenapi(source).ok) return;
+	const checked = validateOpenapi(result);
+	return checked.ok ? void 0 : `openapi emit: ${checked.error}\npass --authorization-url and --token-url, or declare the scheme's flows in the document`;
+}
+async function runOpenapi(input) {
+	if ((input.rest[0] ?? "emit") !== "emit") return {
+		code: 2,
+		output: "openapi action must be emit or import"
+	};
+	if (input.doc === void 0) return {
+		code: 2,
+		output: "openapi --doc is required"
+	};
+	const policy = await loadPolicy(input.cwd, input.config, input.from);
+	const openapi = createPermDock(policy, {
+		target: input.target,
+		...input.profile === void 0 ? {} : { securityProfile: input.profile },
+		...input.profileScheme === void 0 ? {} : { profileScheme: input.profileScheme },
+		scheme: {
+			name: input.scheme,
+			type: "oauth2",
+			...input.metadataUrl === void 0 ? {} : { oauth2MetadataUrl: input.metadataUrl },
+			flows: {
+				authorizationCode: urls({
+					authorizationUrl: input.authorizationUrl,
+					tokenUrl: input.tokenUrl
+				}),
+				...input.deviceFlow ? { deviceAuthorization: urls({
+					deviceAuthorizationUrl: input.deviceAuthorizationUrl,
+					tokenUrl: input.tokenUrl
+				}) } : {}
+			}
+		}
+	});
+	const docPath = resolve(input.cwd, input.doc);
+	if (!existsSync(docPath)) return {
+		code: 2,
+		output: `PermDock CLI: document not found: ${input.doc}`
+	};
+	let parsed;
+	try {
+		parsed = JSON.parse(readFileSync(docPath, "utf8"));
+	} catch {
+		return {
+			code: 2,
+			output: "PermDock CLI: --doc must be a JSON OpenAPI document"
+		};
+	}
+	if (!isRecord(parsed)) return {
+		code: 2,
+		output: "PermDock CLI: OpenAPI document must be an object"
+	};
+	const covered = input.format === "overlay" ? overlayOperations(parsed, policy) : void 0;
+	if (covered !== void 0 && covered.unnamed.length > 0) return {
+		code: 1,
+		output: `openapi emit: an Overlay targets operations by operationId; none on ${covered.unnamed.join(", ")}`
+	};
+	if (input.check && covered !== void 0 && covered.secured.length > 0) return {
+		code: 1,
+		output: `openapi drift: the source already sets security the Overlay replaces on ${covered.secured.join(", ")}`
+	};
+	const result = covered !== void 0 ? openapi.overlay({
+		extends: input.doc,
+		version: input.overlay,
+		operations: covered.operations
+	}) : applyDocument(parsed, policy, openapi, input.arity === true, input.target);
+	const conformance = outputConformance(parsed, result, input.format, input.overlay);
+	if (conformance !== void 0) return {
+		code: 1,
+		output: conformance
+	};
+	const text = stableJson(result);
+	const outPath = resolve(input.cwd, input.out ?? input.doc);
+	if (input.check) {
+		if (!existsSync(outPath)) return {
+			code: 1,
+			output: `openapi drift: missing ${input.out ?? input.doc}`
+		};
+		const current = readFileSync(outPath, "utf8");
+		if (current === text) return {
+			code: 0,
+			output: "openapi up to date"
+		};
+		return {
+			code: 1,
+			output: `openapi drift\n${shortDiff(input.out ?? input.doc, current, text)}`
+		};
+	}
+	mkdirSync(dirname(outPath), { recursive: true });
+	writeFileSync(outPath, text);
+	return {
+		code: 0,
+		output: `wrote ${input.out ?? input.doc}`
+	};
+}
+//#endregion
+export { runOpenapi };