permdock 0.0.0 → 0.1.0

package/dist/openapi-CwePaF7C.js

@@ -0,0 +1,164 @@
+import { a as listArg, i as globalArgs, s as stringArg, t as COMMAND_DESCRIPTIONS } from "./commands-BMh_Etm2.js";
+import { defineCommand } from "citty";
+//#region src/cli/commands/openapi.ts
+function openapi(ctx) {
+	return defineCommand({
+		meta: {
+			name: "openapi",
+			description: COMMAND_DESCRIPTIONS.openapi
+		},
+		args: {
+			...globalArgs,
+			action: {
+				type: "positional",
+				required: false,
+				description: "emit (default) or import"
+			},
+			doc: {
+				type: "string",
+				description: "OpenAPI document: a path, or a URL for import",
+				valueHint: "path"
+			},
+			out: {
+				type: "string",
+				description: "File to write",
+				valueHint: "file"
+			},
+			from: {
+				type: "string",
+				description: "Module exporting the policy, instead of the config",
+				valueHint: "module"
+			},
+			target: {
+				type: "enum",
+				options: [
+					"3.1",
+					"3.2",
+					"3.3"
+				],
+				default: "3.2",
+				description: "OpenAPI version; 3.3 is the pinned Security Profiles draft"
+			},
+			format: {
+				type: "enum",
+				options: ["document", "overlay"],
+				default: "document",
+				description: "A full document or an Overlay"
+			},
+			overlay: {
+				type: "enum",
+				options: ["1.1", "1.2"],
+				default: "1.1",
+				description: "Overlay version; 1.2 is the pinned reusable-actions draft"
+			},
+			check: {
+				type: "boolean",
+				description: "Exit 1 when --out is stale; write nothing"
+			},
+			profile: {
+				type: "enum",
+				options: ["fapi2"],
+				description: "Security profile to declare"
+			},
+			"profile-scheme": {
+				type: "string",
+				description: "Security scheme name for the profile",
+				valueHint: "name"
+			},
+			scheme: {
+				type: "string",
+				default: "permdockOAuth",
+				description: "OAuth security scheme name",
+				valueHint: "name"
+			},
+			"metadata-url": {
+				type: "string",
+				description: "OAuth authorization server metadata URL",
+				valueHint: "url"
+			},
+			"device-flow": {
+				type: "boolean",
+				description: "Declare the device authorization flow"
+			},
+			arity: {
+				type: "boolean",
+				description: "Mark instance and collection operations"
+			},
+			"authorization-url": {
+				type: "string",
+				description: "OAuth authorization endpoint",
+				valueHint: "url"
+			},
+			"token-url": {
+				type: "string",
+				description: "OAuth token endpoint",
+				valueHint: "url"
+			},
+			"device-authorization-url": {
+				type: "string",
+				description: "OAuth device authorization endpoint",
+				valueHint: "url"
+			},
+			schema: {
+				type: "enum",
+				options: [
+					"zod",
+					"valibot",
+					"arktype"
+				],
+				description: "import: schema library for the generated resources"
+			},
+			map: {
+				type: "string",
+				description: "import: JSON mapping of operations to permissions",
+				valueHint: "json"
+			},
+			annotate: {
+				type: "boolean",
+				description: "import: write x-permdock-permissions back into the document"
+			}
+		},
+		async run({ args: parsed, rawArgs }) {
+			const doc = listArg(rawArgs, "doc")[0];
+			if (parsed._[0] === "import") {
+				if (doc === void 0) throw new Error("openapi --doc is required");
+				const { runOpenapiImport } = await import("./openapi-import-BWRUNNeW.js");
+				ctx.report(await runOpenapiImport({
+					cwd: ctx.cwd,
+					doc,
+					out: stringArg(parsed.out),
+					schema: parsed.schema,
+					map: stringArg(parsed.map),
+					annotate: parsed.annotate === true,
+					io: ctx.io
+				}));
+				return;
+			}
+			const result = await (await import("./openapi-DWD0Uc_4.js")).runOpenapi({
+				cwd: ctx.cwd,
+				config: ctx.config,
+				rest: parsed._,
+				doc,
+				out: stringArg(parsed.out),
+				from: stringArg(parsed.from),
+				target: parsed.target,
+				format: parsed.format,
+				overlay: parsed.overlay,
+				check: parsed.check === true,
+				profile: parsed.profile,
+				profileScheme: stringArg(parsed["profile-scheme"]),
+				scheme: parsed.scheme,
+				metadataUrl: listArg(rawArgs, "metadata-url")[0],
+				deviceFlow: parsed["device-flow"] === true,
+				arity: parsed.arity === true,
+				authorizationUrl: stringArg(parsed["authorization-url"]),
+				tokenUrl: stringArg(parsed["token-url"]),
+				deviceAuthorizationUrl: stringArg(parsed["device-authorization-url"]),
+				io: ctx.io
+			});
+			ctx.report(result);
+		}
+	});
+}
+//#endregion
+export { openapi };

package/dist/openapi-DWD0Uc_4.js

@@ -0,0 +1,250 @@
+import { n as validateOverlay, t as validateOpenapi } from "./openapi-schema-D8j_T9tO.js";
+import { c as getResource, i as findPermission } from "./permissions-DC7GROPA.js";
+import { a as definePolicy } from "./policy-ANp36PnI.js";
+import { a as loadModule, n as asPolicy, o as pickNamed, t as asPermissionTree } from "./load-BZ24CpZP.js";
+import { t as shortDiff } from "./text-diff-BdkkYSbi.js";
+import { r as openapiVersion, t as createPermDock } from "./openapi-DcqM8nU7.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 };