permdock 0.3.1 → 0.5.0

package/dist/node/index.d.ts

@@ -1,24 +1,24 @@
-import { C as Policy, D as PolicyVocabulary, Nr as Principal, ln as PermDock } from "../policy-IB6yxpC3.js";
-import { f as Permission } from "../permissions-DttnqqxC.js";
-import { a as ScopeGuard, h as InvalidSignatureError, i as ProtectOptions, n as OpenApiHooks, t as Guard, w as verifyWebBotAuth, x as discoverViaSignatureAgent } from "../create-B1d519XK.js";
-import { t as ServerAdapterOptions } from "../bind-C_ob3LKa.js";
-import { a as toRequest, i as sendResponse, n as fromResponse, r as isServerResponse, t as NodeRequest } from "../http-DPuDaChb.js";
+import { T as Policy, j as PolicyVocabulary, rr as Principal } from "../policy-types-DzwivBgR.js";
+import { w as Permission } from "../vocabulary-D6lPdb4Z.js";
+import { r as PermDock } from "../permdock-D7eeLJER.js";
+import { f as InvalidSignatureError, i as OpenApiHooks, o as ProtectOptions, r as Guard, s as ScopeGuard, v as discoverViaSignatureAgent, x as webBotAuthVerifier } from "../server-types-BLd4MnBX.js";
+import { t as ServerAdapterOptions } from "../bind--9EFVYWF.js";
+import { i as toRequest, n as isServerResponse, r as sendResponse, t as NodeRequest } from "../http-B_LphE5Y.js";
 import { IncomingMessage, ServerResponse } from "node:http";
 //#region src/node/create.d.ts
 type NodePermDockOptions<TUser = unknown> = ServerAdapterOptions<NodeRequest, TUser>;
 type NodeProtect = {
-  (permission: Permission, loadData?: (req: NodeRequest) => unknown, protectOptions?: ProtectOptions): (req: IncomingMessage) => Promise<Guard>;
-  (permission: null, loadData?: (req: NodeRequest) => unknown, protectOptions?: ProtectOptions): (req: IncomingMessage) => Promise<ScopeGuard>;
+  (permission: Permission, data?: (req: NodeRequest) => unknown, protectOptions?: ProtectOptions): (req: IncomingMessage) => Promise<Guard>;
+  (permission: null, data?: (req: NodeRequest) => unknown, protectOptions?: ProtectOptions): (req: IncomingMessage) => Promise<ScopeGuard>;
 };
 type NodePermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
-  readonly permdock: (req: IncomingMessage) => Promise<PermDock<V>>;
+  readonly getPermDock: (req: IncomingMessage) => Promise<PermDock<V>>;
   readonly protect: NodeProtect;
   readonly send: typeof sendResponse;
   readonly permdockHandler: () => (req: IncomingMessage, res: ServerResponse) => Promise<void>;
   readonly toRequest: typeof toRequest;
-  readonly fromResponse: typeof fromResponse;
   readonly openapi: OpenApiHooks;
 };
 export declare function createPermDock<TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, options: NodePermDockOptions<TUser>): NodePermDock<V>;
 //#endregion
-export { InvalidSignatureError, type NodePermDock, type NodePermDockOptions, type NodeRequest, discoverViaSignatureAgent, fromResponse, isServerResponse, sendResponse, toRequest, verifyWebBotAuth };
+export { InvalidSignatureError, type NodePermDock, type NodePermDockOptions, type NodeRequest, discoverViaSignatureAgent, isServerResponse, sendResponse, toRequest, webBotAuthVerifier };

package/dist/node/index.js

@@ -1,15 +1,14 @@
-import { i as discoverViaSignatureAgent, r as InvalidSignatureError, s as verifyWebBotAuth } from "../evaluations-tz6D9A2G.js";
-import { r as bindKernel } from "../bind-CuzGytRf.js";
-import { i as toRequest, n as isServerResponse, r as sendResponse, t as fromResponse } from "../http-BIhmLfCc.js";
+import { d as discoverViaSignatureAgent, m as webBotAuthVerifier, u as InvalidSignatureError } from "../evaluations-DZ2CbV5k.js";
+import { r as bindKernel } from "../bind-CZzhx-Vj.js";
+import { n as sendResponse, r as toRequest, t as isServerResponse } from "../http-ujKm0JXE.js";
 //#region src/node/create.ts
 const nodeRequest = (req) => req;
 function createPermDock(policy, options) {
 	const bound = bindKernel(policy, options, "node", toRequest);
 	const { kernel, handlerScope } = bound;
 	const bind = (req) => bound.bind(nodeRequest(req));
-	const scopeOf = (req) => bound.scopeOf(nodeRequest(req));
-	const permdock = async (req) => kernel.permdock(bind(req), await scopeOf(req));
-	const protect = ((permission, loadData, protectOptions) => async (req) => kernel.protect(permission, loadData === void 0 ? void 0 : () => loadData(nodeRequest(req)), protectOptions)(bind(req), await scopeOf(req)));
+	const getPermDock = (req) => bound.getPermDock(nodeRequest(req));
+	const protect = ((permission, data, protectOptions) => (req) => bound.guard(permission, data, nodeRequest(req), protectOptions));
 	const permdockHandler = () => {
 		const { POST, GET } = kernel.permdockHandler(handlerScope);
 		return async (req, res) => {
@@ -21,14 +20,13 @@ function createPermDock(policy, options) {
 		};
 	};
 	return {
-		permdock,
+		getPermDock,
 		protect,
 		send: sendResponse,
 		permdockHandler,
 		toRequest,
-		fromResponse,
 		openapi: kernel.openapi
 	};
 }
 //#endregion
-export { InvalidSignatureError, createPermDock, discoverViaSignatureAgent, fromResponse, isServerResponse, sendResponse, toRequest, verifyWebBotAuth };
+export { InvalidSignatureError, createPermDock, discoverViaSignatureAgent, isServerResponse, sendResponse, toRequest, webBotAuthVerifier };

package/dist/ocsf-BFp-PZZA.js

@@ -0,0 +1,126 @@
+import { t as compact } from "./compact-CAf557ZB.js";
+//#region src/core/ocsf.ts
+/** The OCSF schema version `toOcsf` emits. */
+const OCSF_VERSION = "1.9.0";
+function status(outcome) {
+	switch (outcome) {
+		case "granted": return {
+			status_id: 1,
+			status: "Success"
+		};
+		case "denied": return {
+			status_id: 2,
+			status: "Failure"
+		};
+		case "approval-required": return {
+			status_id: 99,
+			status: "Approval Required"
+		};
+		default: return unknownStatus(outcome);
+	}
+}
+/** An outcome this build does not know, from a newer producer, is reported as OCSF Unknown. */
+function unknownStatus(_outcome) {
+	return {
+		status_id: 0,
+		status: "Unknown"
+	};
+}
+/** The names of a decision event's app obligations, or `undefined` when it has none. */
+function appObligationNames(event) {
+	const names = (event.obligations ?? []).flatMap((obligation) => obligation.kind === "app" ? [obligation.name] : []);
+	return names.length === 0 ? void 0 : names;
+}
+/** Epoch milliseconds of an RFC 3339 `at`, or `undefined` when it does not parse. */
+function epochMillis(at) {
+	const time = Date.parse(at);
+	return Number.isNaN(time) ? void 0 : time;
+}
+/**
+* Projects a decision or approval event onto OCSF Authorize Session; the event itself is unchanged.
+* An event whose `at` does not parse has no OCSF `time` and projects to `undefined`.
+*/
+function toOcsf(event) {
+	const time = epochMillis(event.at);
+	if (time === void 0) return;
+	const principal = event.subject.principal;
+	const actor = event.subject.actor;
+	const breakGlass = event.matched?.breakGlass === true;
+	const detail = event.outcome === "approval-required" ? "approval-required" : event.denials?.map((denial) => denial.reason).join(",");
+	return compact({
+		class_uid: 3003,
+		category_uid: 3,
+		activity_id: 1,
+		type_uid: 300301,
+		severity_id: breakGlass ? 4 : 1,
+		time,
+		...status(event.outcome),
+		status_detail: detail === "" ? void 0 : detail,
+		message: `${event.permission} ${event.outcome}`,
+		privileges: [event.permission],
+		user: principal === null ? { name: "anonymous" } : { uid: principal.id },
+		actor: actor === void 0 ? void 0 : compact({
+			user: principal === null ? void 0 : { uid: principal.id },
+			app_name: actor.id
+		}),
+		metadata: compact({
+			version: OCSF_VERSION,
+			product: compact({
+				name: "PermDock",
+				vendor_name: "PermDock",
+				feature: event.adapter === void 0 ? void 0 : { name: event.adapter }
+			}),
+			tenant_uid: event.tenant,
+			correlation_uid: event.token
+		}),
+		unmapped: compact({
+			outcome: event.outcome,
+			scope: event.scope,
+			resource: event.resource,
+			call: event.call,
+			phase: event.phase,
+			role: event.matched?.role,
+			grant: event.matched?.name,
+			obligations: appObligationNames(event),
+			via: event.via,
+			breakGlass: breakGlass ? true : void 0,
+			purpose: event.purpose,
+			reason: event.reason
+		})
+	});
+}
+/** An access event whose `at` does not parse projects to `undefined`. */
+function accessToOcsf(event) {
+	const time = epochMillis(event.at);
+	if (time === void 0) return;
+	const enable = event.operation === "started";
+	return compact({
+		class_uid: 3007,
+		category_uid: 3,
+		activity_id: enable ? 4 : 5,
+		type_uid: enable ? 300704 : 300705,
+		severity_id: 4,
+		time,
+		message: `support access ${event.operation}`,
+		user: { uid: event.principal.id },
+		actor: event.actor === void 0 ? void 0 : { user: { uid: event.actor.id } },
+		metadata: {
+			version: OCSF_VERSION,
+			product: {
+				name: "PermDock",
+				vendor_name: "PermDock"
+			},
+			tenant_uid: event.tenant
+		},
+		unmapped: compact({
+			operation: event.operation,
+			via: event.via,
+			roles: event.roles,
+			member: event.member,
+			grantedBy: event.grantedBy,
+			reason: event.reason
+		})
+	});
+}
+//#endregion
+export { toOcsf as i, accessToOcsf as n, appObligationNames as r, OCSF_VERSION as t };

package/dist/openai/index.d.ts

@@ -1,8 +1,8 @@
-import { C as Policy, D as PolicyVocabulary, Nr as Principal, kr as Delegation, ln as PermDock } from "../policy-IB6yxpC3.js";
-import { f as Permission } from "../permissions-DttnqqxC.js";
-import { c as ApprovalRequest, f as ApprovalStore } from "../types-aqOHTHcp.js";
-import { t as InstanceOptions } from "../instance-options-jARdwfPN.js";
-import { t as ToolMap } from "../types-Bvc4oWT6.js";
+import { T as Policy, j as PolicyVocabulary, rr as Principal } from "../policy-types-DzwivBgR.js";
+import { w as Permission } from "../vocabulary-D6lPdb4Z.js";
+import { r as PermDock } from "../permdock-D7eeLJER.js";
+import { u as ApprovalRequest } from "../types-CCpc2Dcv.js";
+import { o as AgentAdapterOptions, t as AgentPermDock } from "../create-BDS7wc3y.js";
 //#region src/openai/create.d.ts
 /** The app context passed to `run(agent, input, { context })`. */
 type OpenAiContext = {
@@ -15,14 +15,7 @@ type OpenAiContext = {
 type OpenAiRunContext = {
   readonly context?: unknown;
 };
-type OpenAiPermDockOptions<TUser = unknown> = InstanceOptions & {
-  readonly subject: (context: OpenAiContext) => TUser | Promise<TUser>;
-  readonly actor?: (context: OpenAiContext) => unknown;
-  readonly delegation?: (context: OpenAiContext) => Delegation | undefined | Promise<Delegation | undefined>;
-  readonly tenant?: string | ((context: OpenAiContext) => string | undefined | Promise<string | undefined>);
-  readonly tools: ToolMap;
-  readonly store?: ApprovalStore;
-};
+type OpenAiPermDockOptions<TUser = unknown> = AgentAdapterOptions<OpenAiContext, TUser>;
 type OpenAiTool = {
   readonly name: string;
 };
@@ -48,15 +41,15 @@ type OpenAiRunState<TItem> = {
     message?: string;
   }): unknown;
 };
-type OpenAiPermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
+type OpenAiPermDock<V extends PolicyVocabulary = PolicyVocabulary> = AgentPermDock<OpenAiContext, V> & {
   /** A `ToolApprovalFunction`: pass it as a tool's `needsApproval`. */
   readonly needsApproval: (permission: Permission) => (runContext: OpenAiRunContext | undefined, input: unknown, callId?: string) => Promise<boolean>;
   readonly guardTools: <T extends OpenAiTool>(tools: readonly T[], context: OpenAiContext) => Promise<readonly T[]>;
   readonly resolveInterruptions: <TItem extends OpenAiInterruption>(state: OpenAiRunState<TItem>, interruptions: readonly TItem[], options: {
     readonly context: OpenAiContext;
   }) => Promise<readonly ApprovalRequest[]>;
-  readonly permdock: (context: OpenAiContext) => Promise<PermDock<V>>;
+  readonly getPermDock: (context: OpenAiContext) => Promise<PermDock<V>>;
 };
-export declare function createPermDock<TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, options: OpenAiPermDockOptions<TUser>): OpenAiPermDock<V>;
+export declare function createPermDock<TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, given: OpenAiPermDockOptions<TUser>): OpenAiPermDock<V>;
 //#endregion
 export type { OpenAiContext, OpenAiInterruption, OpenAiPermDock, OpenAiPermDockOptions, OpenAiRunState, OpenAiTool };

package/dist/openai/index.js

@@ -1,7 +1,7 @@
-import { t as compact } from "../compact-y6vfu2_f.js";
-import { r as memoryApprovalStore } from "../store-DMAWwAJV.js";
-import { t as instanceOptions } from "../instance-options-Dhhcnm3y.js";
-import { n as createAgentKernel, t as approvalTokenOf } from "../kernel-_RRHmnMY.js";
+import { t as compact } from "../compact-CAf557ZB.js";
+import { c as withApp } from "../permdock-B9JxkBwC.js";
+import { t as approvalTokenOf } from "../kernel-5JatXyND.js";
+import { t as agentRuntime } from "../create-C3b4B5eF.js";
 //#region src/openai/create.ts
 function appContext(runContext) {
 	const context = runContext?.context;
@@ -26,34 +26,25 @@ function parseCall(item) {
 		return { ok: false };
 	}
 }
-function createPermDock(policy, options) {
-	const store = options.store ?? memoryApprovalStore();
-	const kernel = createAgentKernel(policy, {
-		...compact({
-			actor: options.actor,
-			delegation: options.delegation,
-			tenant: options.tenant
-		}),
-		...instanceOptions(options),
-		subject: options.subject,
-		tools: options.tools,
-		store,
-		adapter: "openai"
-	});
+function createPermDock(policy, given) {
+	const options = withApp(policy, given);
+	const store = options.store;
+	const { agent, kernel } = agentRuntime(policy, options, "openai");
 	const byPermission = /* @__PURE__ */ new Map();
-	for (const [name, binding] of Object.entries(options.tools)) byPermission.set(binding.permission.key, name);
+	for (const [name, binding] of Object.entries(options.operations)) byPermission.set(binding.permission.key, name);
+	const passes = (toolName) => options.unmapped === "allow" && !Object.hasOwn(options.operations, toolName);
 	const needsApproval = (permission) => async (runContext, input) => {
 		const toolName = byPermission.get(permission.key);
 		if (toolName === void 0) return true;
 		const context = appContext(runContext);
-		const binding = options.tools[toolName];
+		const binding = options.operations[toolName];
 		if (binding === void 0) return true;
 		const checked = await kernel.check(binding, input, context, { simulate: true });
 		return !checked.ok || checked.raw.outcome !== "granted";
 	};
 	const guardTools = async (tools, context) => {
 		const allowed = await kernel.allowedToolNames(context);
-		return tools.filter((tool) => allowed.has(tool.name));
+		return tools.filter((tool) => allowed.has(tool.name) || passes(tool.name));
 	};
 	const resolveOne = async (state, item, context) => {
 		const call = parseCall(item);
@@ -61,6 +52,7 @@ function createPermDock(policy, options) {
 			await state.reject(item, { message: "Denied: unreadable tool call." });
 			return null;
 		}
+		if (passes(call.name)) return null;
 		const verdict = await kernel.decideTool(call.name, call.args, context, compact({ resumeToken: approvalTokenOf(context) }));
 		if (verdict.outcome === "granted") {
 			await state.approve(item);
@@ -70,6 +62,7 @@ function createPermDock(policy, options) {
 			await state.reject(item, { message: verdict.reason });
 			return null;
 		}
+		if (store === void 0) return null;
 		try {
 			return await store.get(verdict.token);
 		} catch {
@@ -81,12 +74,12 @@ function createPermDock(policy, options) {
 		for (const item of interruptions) resolved.push(await resolveOne(state, item, resolveOptions.context));
 		return resolved.filter((record) => record !== null);
 	};
-	return {
+	return Object.freeze({
+		...agent,
 		needsApproval,
 		guardTools,
-		resolveInterruptions,
-		permdock: (context) => kernel.instance(context)
-	};
+		resolveInterruptions
+	});
 }
 //#endregion
 export { createPermDock };

package/dist/openapi/index.d.ts

@@ -1,6 +1,6 @@
-import { C as Policy, Ir as Condition, Nr as Principal } from "../policy-IB6yxpC3.js";
-import { f as Permission, m as PermissionTree } from "../permissions-DttnqqxC.js";
-import { a as ProblemDetails } from "../errors-DPdqI50v.js";
+import { T as Policy, lr as Condition, rr as Principal } from "../policy-types-DzwivBgR.js";
+import { E as PermissionTree, w as Permission } from "../vocabulary-D6lPdb4Z.js";
+import { a as ProblemDetails } from "../errors-C2PXIv4c.js";
 import { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/openapi/types.d.ts
 type OpenApiTarget = "3.1" | "3.2" | "3.3";

package/dist/openapi/index.js

@@ -1,3 +1,3 @@
 import { n as GNAP_RESERVED, r as PROFILE_NAMES, t as DRAFT_PINS } from "../pins-8ILTftC9.js";
-import { a as operationPermissionsFromOpenApi, c as openapiVersion, i as operationPermissions, l as securitySchemesOf, n as securityFor, o as createPermDock, r as problemDetails, s as catalogOf, t as permissionsExtension } from "../openapi-BqRBvAng.js";
+import { a as operationPermissionsFromOpenApi, c as openapiVersion, i as operationPermissions, l as securitySchemesOf, n as securityFor, o as createPermDock, r as problemDetails, s as catalogOf, t as permissionsExtension } from "../openapi-B7HZ0f-r.js";
 export { DRAFT_PINS, GNAP_RESERVED, PROFILE_NAMES, catalogOf, createPermDock, openapiVersion, operationPermissions, operationPermissionsFromOpenApi, permissionsExtension, problemDetails, securityFor, securitySchemesOf };

package/dist/{openapi-BqRBvAng.js → openapi-B7HZ0f-r.js}

@@ -1,6 +1,6 @@
-import { t as compact } from "./compact-y6vfu2_f.js";
-import { _ as listPermissions, i as findPermission, p as isPermission } from "./permissions-DVoF6dMt.js";
-import { n as sha256 } from "./sha256-BO0swRXL.js";
+import { r as isRecord, t as compact } from "./compact-CAf557ZB.js";
+import { c as listPermissions, n as findPermission, o as isPermission } from "./permission-registry-Br4jSNVi.js";
+import { r as sha256Digest } from "./sha256-D9ihqmvd.js";
 import { t as requiresApproval } from "./approval-required-TzNB9oQA.js";
 import { i as PROFILE_PARAMETERS, n as GNAP_RESERVED, r as PROFILE_NAMES, t as DRAFT_PINS } from "./pins-8ILTftC9.js";
 //#region src/openapi/emit.ts
@@ -188,13 +188,10 @@ function jsonPathString(value) {
 function operationTarget(operationId) {
 	return `$.paths.*[?@.operationId == ${jsonPathString(operationId)}]`;
 }
-function hex(bytes) {
-	return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
-}
-/** `sha256:` over the sorted permission keys and scopes, so the same catalog gives the same Overlay. */
+/** The `sha-256:` digest of the sorted permission keys and scopes, so the same catalog gives the same Overlay. */
 function fingerprint(policy) {
 	const lines = listPermissions(policy.permissions).map((leaf) => `${leaf.key} ${leaf.scope}`).toSorted();
-	return `sha256:${hex(sha256(lines.join("\n")))}`;
+	return sha256Digest(lines.join("\n"));
 }
 function overlayOf(policy, options, overlayOptions = {}) {
 	const version = overlayOptions.version ?? "1.1";
@@ -402,9 +399,6 @@ function operationPermissions(operations, options = {}) {
 		}
 	};
 }
-function isRecord(value) {
-	return value !== null && typeof value === "object" && !Array.isArray(value);
-}
 /**
 * The operation permissions an OpenAPI document declares: every operation
 * whose `x-permdock-permissions` names exactly one permission of `tree`, keyed
@@ -459,7 +453,10 @@ const JSON_SCHEMA = Object.freeze({
 			maximum: 599
 		},
 		detail: { type: "string" },
-		instance: { type: "string" },
+		instance: {
+			type: "string",
+			format: "uri-reference"
+		},
 		permission: { type: "string" },
 		scope: { type: "string" },
 		reason: { type: "string" }

package/dist/{openapi-CqqEbHsL.js → openapi-DTaEmTSW.js}

@@ -1,15 +1,16 @@
-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);
-}
+import { r as isRecord } from "./compact-CAf557ZB.js";
+import { a as getResource, n as findPermission } from "./permission-registry-Br4jSNVi.js";
+import { n as definePolicy } from "./policy-DLZJ5gAp.js";
+import { i as configError } from "./errors-CWTY6uih.js";
+import { i as readJsonFile, s as writeFileEnsuringDir } from "./files-D_JIzUrP.js";
+import { a as loadModule, n as asPolicy, s as pickNamed, t as asPermissionTree } from "./load-DFS_ry0W.js";
+import { t as shortDiff } from "./text-diff-BQcUapOb.js";
+import { c as openapiVersion, o as createPermDock } from "./openapi-B7HZ0f-r.js";
+import { i as fileDrift } from "./output-files-DhRBBE4n.js";
+import { n as validateOverlay, t as validateOpenapi } from "./schema-yLuBWWsh.js";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+//#region src/cli/openapi/openapi.ts
 function mergeRecord(base, extra) {
 	const result = {};
 	for (const [key, value] of Object.entries(base)) result[key] = value;
@@ -52,7 +53,7 @@ async function loadPolicy(cwd, config, from) {
 		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");
+	if (permissionsPath === void 0) throw configError("PermDock CLI: openapi emit needs --policy, or policy or permissions in the config");
 	const tree = asPermissionTree(pickNamed(await loadModule(resolve(cwd, permissionsPath)), ["permissions"]));
 	return definePolicy(tree, {
 		roles: [],
@@ -63,7 +64,7 @@ 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}'`);
+		if (leaf === void 0) throw configError(`PermDock CLI: unknown permission '${key}'`);
 		return leaf;
 	});
 }
@@ -192,7 +193,7 @@ async function runOpenapi(input) {
 	};
 	let parsed;
 	try {
-		parsed = JSON.parse(readFileSync(docPath, "utf8"));
+		parsed = readJsonFile(docPath);
 	} catch {
 		return {
 			code: 2,
@@ -223,27 +224,23 @@ async function runOpenapi(input) {
 		output: conformance
 	};
 	const text = stableJson(result);
-	const outPath = resolve(input.cwd, input.out ?? input.doc);
+	const outFile = input.out ?? input.doc;
+	const outPath = resolve(input.cwd, outFile);
 	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 {
+		const found = fileDrift(outPath, text);
+		if (found === void 0) return {
 			code: 0,
 			output: "openapi up to date"
 		};
 		return {
 			code: 1,
-			output: `openapi drift\n${shortDiff(input.out ?? input.doc, current, text)}`
+			output: found.kind === "missing" ? `openapi drift: missing ${outFile}` : `openapi drift\n${shortDiff(outFile, found.onDisk, text)}`
 		};
 	}
-	mkdirSync(dirname(outPath), { recursive: true });
-	writeFileSync(outPath, text);
+	writeFileEnsuringDir(outPath, text);
 	return {
 		code: 0,
-		output: `wrote ${input.out ?? input.doc}`
+		output: `wrote ${outFile}`
 	};
 }
 //#endregion

package/dist/openapi-ahr8rHu3.js

@@ -0,0 +1,138 @@
+import { c as missingInput } from "./errors-CWTY6uih.js";
+import { t as defineLeaf } from "./command-L8EstFNm.js";
+import { c as given, d as policyFlag, f as validatorFlag, l as outFlag, o as fileOut, t as checkFlag } from "./flags-C3DktBDY.js";
+//#region src/cli/commands/openapi.ts
+const docFlag = { doc: {
+	type: "string",
+	description: "OpenAPI document: a path, or a URL for import",
+	valueHint: "path"
+} };
+const emit = defineLeaf({
+	flags: {
+		...docFlag,
+		...outFlag,
+		...checkFlag,
+		...policyFlag,
+		target: {
+			type: "enum",
+			options: [
+				"3.1",
+				"3.2",
+				"3.3"
+			],
+			default: "3.2",
+			description: "OpenAPI version; 3.3 is the pinned Security Profiles draft"
+		},
+		kind: {
+			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"
+		},
+		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",
+			description: "OAuth security scheme name (default permdockOAuth)",
+			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"
+		}
+	},
+	async run(ctx, { flags }) {
+		return (await import("./openapi-DTaEmTSW.js")).runOpenapi({
+			cwd: ctx.cwd,
+			config: ctx.config,
+			rest: ["emit"],
+			doc: given(flags.doc),
+			out: fileOut("openapi emit", flags.out),
+			from: given(flags.policy),
+			target: flags.target,
+			format: flags.kind,
+			overlay: flags.overlay,
+			check: flags.check,
+			profile: flags.profile,
+			profileScheme: given(flags["profile-scheme"]),
+			scheme: given(flags.scheme) ?? "permdockOAuth",
+			metadataUrl: given(flags["metadata-url"]),
+			deviceFlow: flags["device-flow"],
+			arity: flags.arity,
+			authorizationUrl: given(flags["authorization-url"]),
+			tokenUrl: given(flags["token-url"]),
+			deviceAuthorizationUrl: given(flags["device-authorization-url"]),
+			io: ctx.io
+		});
+	}
+});
+const importDocument = defineLeaf({
+	flags: {
+		...docFlag,
+		...outFlag,
+		...validatorFlag,
+		map: {
+			type: "string",
+			description: "JSON mapping of operations to permissions",
+			valueHint: "json"
+		},
+		annotate: {
+			type: "boolean",
+			description: "Write x-permdock-permissions back into the document"
+		}
+	},
+	async run(ctx, { flags }) {
+		const doc = given(flags.doc);
+		if (doc === void 0) throw missingInput("openapi import", ["--doc"], "the OpenAPI document to import");
+		const { runOpenapiImport } = await import("./import-CNV7I2Dw.js");
+		return runOpenapiImport({
+			cwd: ctx.cwd,
+			doc,
+			out: fileOut("openapi import", flags.out),
+			schema: flags.validator,
+			map: given(flags.map),
+			annotate: flags.annotate,
+			io: ctx.io
+		});
+	}
+});
+//#endregion
+export { emit, importDocument };