permdock 0.6.0 → 0.8.0

package/dist/openai/index.d.ts

@@ -1,8 +1,8 @@
-import { T as Policy, j as PolicyVocabulary, rr as Principal } from "../policy-types-n0uRTsW8.js";
-import { w as Permission } from "../vocabulary-CN8H_9UF.js";
-import { r as PermDock } from "../permdock-SV8ZINYT.js";
-import { u as ApprovalRequest } from "../types-BdtSDbBO.js";
-import { o as AgentAdapterOptions, t as AgentPermDock } from "../create-CBMmFie-.js";
+import { T as Policy, j as PolicyVocabulary, sr as Principal } from "../policy-types-CCiDRZBH.js";
+import { u as Permission } from "../permission-types-CAY-GU7e.js";
+import { a as PermDock } from "../permdock-B6Sf4T_S.js";
+import { u as ApprovalRequest } from "../types-B_tiYvk8.js";
+import { o as AgentAdapterOptions, t as AgentPermDock } from "../create-BSNrVuxh.js";
 //#region src/openai/create.d.ts
 /** The app context passed to `run(agent, input, { context })`. */
 type OpenAiContext = {
@@ -11,7 +11,10 @@ type OpenAiContext = {
   readonly permdockApproval?: string;
   readonly [key: string]: unknown;
 };
-/** Structural `RunContext` from `@openai/agents`: the app context sits under `context`. */
+/**
+ * Structural `RunContext` from `@openai/agents`: the app context sits under
+ * `context`.
+ */
 type OpenAiRunContext = {
   readonly context?: unknown;
 };
@@ -31,7 +34,10 @@ type OpenAiInterruption = {
     readonly arguments?: unknown;
   };
 };
-/** Structural `RunState` from `@openai/agents`. */
+/**
+ * Structural `RunState` from `@openai/agents`. Its methods take the SDK's own
+ * interruption item, so they stay bivariant in `TItem`.
+ */
 type OpenAiRunState<TItem> = {
   approve(item: TItem, options?: {
     alwaysApprove?: boolean;

package/dist/openai/index.js

@@ -1,7 +1,7 @@
 import { t as compact } from "../compact-CAf557ZB.js";
-import { c as withApp } from "../permdock-BrAscV28.js";
-import { t as approvalTokenOf } from "../kernel-D0NVb1cK.js";
-import { t as agentRuntime } from "../create-CGm28gyI.js";
+import { l as withApp } from "../permdock-L-_I_3zP.js";
+import { t as approvalTokenOf } from "../kernel-C-fYydV2.js";
+import { t as agentRuntime } from "../create-Cq4Uox0f.js";
 //#region src/openai/create.ts
 function appContext(runContext) {
 	const context = runContext?.context;

package/dist/openapi/index.d.ts

@@ -1,6 +1,6 @@
-import { T as Policy, rr as Principal, ur as Condition } from "../policy-types-n0uRTsW8.js";
-import { E as PermissionTree, w as Permission } from "../vocabulary-CN8H_9UF.js";
-import { a as ProblemDetails } from "../errors-DH5QEGXh.js";
+import { T as Policy, mr as Condition, sr as Principal } from "../policy-types-CCiDRZBH.js";
+import { f as PermissionTree, u as Permission } from "../permission-types-CAY-GU7e.js";
+import { a as ProblemDetails } from "../errors-zi_4T-rx.js";
 import { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/openapi/types.d.ts
 type OpenApiTarget = "3.1" | "3.2" | "3.3";
@@ -54,7 +54,10 @@ type OverlayOperation = {
 type OpenApiOverlayOptions = {
   readonly extends?: string;
   readonly version?: OverlayVersion;
-  /** The operations to cover; without them, one per permission whose `operationId` is the permission key. */
+  /**
+   * The operations to cover; without them, one per permission whose
+   * `operationId` is the permission key.
+   */
   readonly operations?: readonly OverlayOperation[];
 };
 type OpenApiPermDock = {
@@ -67,7 +70,10 @@ type OpenApiPermDock = {
   }) => OpenApiDescribe;
   readonly spec: (permission: Permission | readonly Permission[]) => (operation: Readonly<Record<string, unknown>>) => Record<string, unknown>;
   readonly overlay: (options?: OpenApiOverlayOptions) => Record<string, unknown>;
-  /** One requirement per distinct scope set; without `scopeSets`, one per permission. */
+  /**
+   * One requirement per distinct scope set; without `scopeSets`, one per
+   * permission.
+   */
   readonly securityProfileRequirements: (scopeSets?: readonly (readonly string[])[]) => Readonly<Record<string, unknown>> | undefined;
   readonly catalog: () => Record<string, unknown>;
 };
@@ -94,9 +100,9 @@ export declare function openapiVersion(target: OpenApiTarget): string;
 //#endregion
 //#region src/openapi/operations.d.ts
 /**
- * One declared operation: a permission, or a permission with the operation id
- * a tool name uses and the OAuth scopes that reach it, or only OAuth scopes
- * for a route that checks no permission (`protect(null)`).
+ * One declared operation: a permission, or a permission with the operation id a
+ * tool name uses and the OAuth scopes that reach it, or only OAuth scopes for a
+ * route that checks no permission (`protect(null)`).
  */
 type OperationEntry = Permission | {
   readonly permission: Permission;
@@ -114,31 +120,34 @@ type OperationEntry = Permission | {
  */
 type OperationPermissions = {
   /**
-   * The permission of a request: the declared operation whose method and
-   * path template match, a literal segment winning over a `{param}`.
-   * `undefined` for an undeclared operation, which a gate denies, and for an
-   * operation that declares only OAuth scopes. A `HEAD` request matches the
-   * `GET` entry of its path when no `HEAD` entry matches.
+   * The permission of a request: the declared operation whose method and path
+   * template match, a literal segment winning over a `{param}`. `undefined` for
+   * an undeclared operation, which a gate denies, and for an operation that
+   * declares only OAuth scopes. A `HEAD` request matches the `GET` entry of its
+   * path when no `HEAD` entry matches.
    */
-  forRequest(method: string, path: string): Permission | undefined;
-  /** The permission of an operation id; pass it as `permissionFor` when tool names are operation ids. */
-  forOperation(id: string): Permission | undefined;
-  oauthScopesForRequest(method: string, path: string): readonly string[] | undefined;
-  oauthScopesForOperation(id: string): readonly string[] | undefined;
+  forRequest: (method: string, path: string) => Permission | undefined;
+  /**
+   * The permission of an operation id; pass it as `permissionFor` when tool
+   * names are operation ids.
+   */
+  forOperation: (id: string) => Permission | undefined;
+  oauthScopesForRequest: (method: string, path: string) => readonly string[] | undefined;
+  oauthScopesForOperation: (id: string) => readonly string[] | undefined;
 };
 /**
- * Operations as `"METHOD /path/{param}"` keys, the OpenAPI path template, to
- * a permission. `base` is a prefix requests carry and the keys do not
+ * Operations as `"METHOD /path/{param}"` keys, the OpenAPI path template, to a
+ * permission. `base` is a prefix requests carry and the keys do not
  * (`/api/v1`). A key that is not a method and a path throws.
  */
 export declare function operationPermissions(operations: Readonly<Record<string, OperationEntry>>, options?: {
   readonly base?: string;
 }): OperationPermissions;
 /**
- * The operation permissions an OpenAPI document declares: every operation
- * whose `x-permdock-permissions` names exactly one permission of `tree`, keyed
- * by its method, path and `operationId`. An operation naming none, several or
- * an unknown key is left out, so a gate denies it.
+ * The operation permissions an OpenAPI document declares: every operation whose
+ * `x-permdock-permissions` names exactly one permission of `tree`, keyed by its
+ * method, path and `operationId`. An operation naming none, several or an
+ * unknown key is left out, so a gate denies it.
  */
 export declare function operationPermissionsFromOpenApi(document: unknown, tree: PermissionTree, options?: {
   readonly base?: string;
@@ -146,24 +155,44 @@ export declare function operationPermissionsFromOpenApi(document: unknown, tree:
 //#endregion
 //#region src/openapi/problem-details.d.ts
 /**
- * The Problem Details body the adapters send on a denial, as a Standard
- * Schema with a JSON Schema, for `oc.errors({ FORBIDDEN: { data: problemDetails } })`.
+ * The Problem Details body the adapters send on a denial, as a Standard Schema
+ * with a JSON Schema, for `oc.errors({ FORBIDDEN: { data: problemDetails } })`.
  * Extension members pass through: RFC 9457 lets a problem type add them.
  */
 export declare const problemDetails: StandardSchemaV1<ProblemDetails> & StandardJSONSchemaV1<ProblemDetails>;
 //#endregion
 //#region src/openapi/security.d.ts
 type SecurityForOptions = {
-  /** The security scheme name; defaults to `oauth2`, the name the adapters' `openapi.securitySchemes()` declares. */
+  /**
+   * The security scheme name; defaults to `oauth2`, the name the adapters'
+   * `openapi.securitySchemes()` declares.
+   */
   readonly scheme?: string;
-  /** Any one of the permissions suffices: one requirement per scope instead of one with every scope. */
+  /**
+   * Any one of the permissions suffices: one requirement per scope instead of
+   * one with every scope.
+   */
   readonly anyOf?: boolean;
+  readonly security?: true;
+};
+/**
+ * `security: false` emits only `x-permdock-permissions`, for an API whose
+ * `security` is set elsewhere, such as OIDC-only bearer auth.
+ */
+type SecurityExtensionOptions = Omit<SecurityForOptions, "security"> & {
+  readonly security: false;
+};
+type SecurityExtensionFor = {
+  readonly "x-permdock-permissions": readonly string[];
 };
 type SecurityFor = {
   readonly security: readonly OpenApiSecurityRequirement[];
   readonly "x-permdock-permissions": readonly string[];
 };
-/** The `x-permdock-permissions` value: the permission keys an operation enforces. */
+/**
+ * The `x-permdock-permissions` value: the permission keys an operation
+ * enforces.
+ */
 export declare function permissionsExtension(permissions: Permission | readonly Permission[]): readonly string[];
 /**
  * An operation's `security` and `x-permdock-permissions`, from permission
@@ -171,6 +200,8 @@ export declare function permissionsExtension(permissions: Permission | readonly
  * Unlike `permdock openapi emit`, it never drops `security` for a public
  * permission: that needs the policy.
  */
+export declare function securityFor(permission: Permission | readonly Permission[], options: SecurityExtensionOptions): SecurityExtensionFor;
 export declare function securityFor(permission: Permission | readonly Permission[], options?: SecurityForOptions): SecurityFor;
+export declare function securityFor(permission: Permission | readonly Permission[], options?: SecurityForOptions | SecurityExtensionOptions): SecurityFor | SecurityExtensionFor;
 //#endregion
-export type { OpenApiDescribe, OpenApiDocsHints, OpenApiFactory, OpenApiOverlayOptions, OpenApiPermDock, OpenApiPermDockOptions, OpenApiSchemeOptions, OpenApiSecurityRequirement, OpenApiTarget, OperationEntry, OperationPermissions, OverlayOperation, OverlayVersion, SchemeType, SecurityFor, SecurityForOptions, SecurityProfileName };
+export type { OpenApiDescribe, OpenApiDocsHints, OpenApiFactory, OpenApiOverlayOptions, OpenApiPermDock, OpenApiPermDockOptions, OpenApiSchemeOptions, OpenApiSecurityRequirement, OpenApiTarget, OperationEntry, OperationPermissions, OverlayOperation, OverlayVersion, SchemeType, SecurityExtensionFor, SecurityExtensionOptions, SecurityFor, SecurityForOptions, SecurityProfileName };

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-B7HZ0f-r.js";
+import { n as GNAP_RESERVED, r as PROFILE_NAMES, t as DRAFT_PINS } from "../pins-nqarl3oE.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-BOsx0xn9.js";
 export { DRAFT_PINS, GNAP_RESERVED, PROFILE_NAMES, catalogOf, createPermDock, openapiVersion, operationPermissions, operationPermissionsFromOpenApi, permissionsExtension, problemDetails, securityFor, securitySchemesOf };

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

@@ -1,8 +1,8 @@
 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 { c as listPermissions, n as findPermission, o as isPermission } from "./permission-registry-B8tYxPIt.js";
+import { r as sha256Digest } from "./sha256-C-4WXKIu.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";
+import { i as PROFILE_PARAMETERS, n as GNAP_RESERVED, r as PROFILE_NAMES, t as DRAFT_PINS } from "./pins-nqarl3oE.js";
 //#region src/openapi/emit.ts
 function assertScheme(options) {
 	if (options.scheme.type === "gnap") throw new TypeError(GNAP_RESERVED);
@@ -17,7 +17,10 @@ function grantsOf(policy, permissions) {
 function grantsAnyone(grant) {
 	return (Array.isArray(grant.to) ? grant.to : [grant.to]).some((grantee) => grantee.kind === "anyone");
 }
-/** Every subject is granted it: an unconditional allow to `anyone()` and no deny. */
+/**
+* Every subject is granted it: an unconditional allow to `anyone()` and no
+* deny.
+*/
 function isPublic(policy, permission) {
 	const grants = grantsOf(policy, [permission]);
 	return grants.every((grant) => grant.effect === "allow") && grants.some((grant) => grantsAnyone(grant) && grant.where === void 0 && grant.check === void 0 && grant.approval === void 0 && grant.closure === void 0 && grant.limit === void 0 && grant.purpose === void 0 && grant.viaOnly === void 0);
@@ -137,14 +140,17 @@ const FLOWS = [
 	"clientCredentials",
 	"deviceAuthorization"
 ];
-/** The client authentication methods FAPI 2.0 section 5.3.2.1 allows: sender-constrained, no shared secret. */
+/**
+* The client authentication methods FAPI 2.0 section 5.3.2.1 allows:
+* sender-constrained, no shared secret.
+*/
 const FAPI2_AUTH_METHODS = ["private_key_jwt", "tls_client_auth"];
 function pascal(value) {
 	return value.split(/[^A-Za-z0-9]+/u).filter((part) => part.length > 0).map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`).join("");
 }
 /**
-* One Security Profile Requirement per distinct scope set: `scopeSets` from
-* the operations, else one per permission.
+* One Security Profile Requirement per distinct scope set: `scopeSets` from the
+* operations, else one per permission.
 */
 function securityProfileRequirementsOf(policy, options, scopeSets) {
 	if ((options.target ?? "3.2") !== "3.3" || options.securityProfile === void 0) return;
@@ -188,7 +194,10 @@ function jsonPathString(value) {
 function operationTarget(operationId) {
 	return `$.paths.*[?@.operationId == ${jsonPathString(operationId)}]`;
 }
-/** The `sha-256:` digest of 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 sha256Digest(lines.join("\n"));
@@ -318,7 +327,10 @@ function segmentsOf(path) {
 function isParam(segment) {
 	return segment.startsWith("{") && segment.endsWith("}");
 }
-/** The number of literal segments that match, or -1 when the template does not match. */
+/**
+* The number of literal segments that match, or -1 when the template does not
+* match.
+*/
 function score(route, segments) {
 	if (route.segments.length !== segments.length) return -1;
 	let literal = 0;
@@ -339,8 +351,8 @@ function scopesOf(key, entry) {
 	return Object.freeze([...entry.oauthScopes]);
 }
 /**
-* Operations as `"METHOD /path/{param}"` keys, the OpenAPI path template, to
-* a permission. `base` is a prefix requests carry and the keys do not
+* Operations as `"METHOD /path/{param}"` keys, the OpenAPI path template, to a
+* permission. `base` is a prefix requests carry and the keys do not
 * (`/api/v1`). A key that is not a method and a path throws.
 */
 function operationPermissions(operations, options = {}) {
@@ -400,10 +412,10 @@ function operationPermissions(operations, options = {}) {
 	};
 }
 /**
-* The operation permissions an OpenAPI document declares: every operation
-* whose `x-permdock-permissions` names exactly one permission of `tree`, keyed
-* by its method, path and `operationId`. An operation naming none, several or
-* an unknown key is left out, so a gate denies it.
+* The operation permissions an OpenAPI document declares: every operation whose
+* `x-permdock-permissions` names exactly one permission of `tree`, keyed by its
+* method, path and `operationId`. An operation naming none, several or an
+* unknown key is left out, so a gate denies it.
 */
 function operationPermissionsFromOpenApi(document, tree, options = {}) {
 	const operations = {};
@@ -491,8 +503,8 @@ function jsonSchema(options) {
 	return structuredClone(JSON_SCHEMA);
 }
 /**
-* The Problem Details body the adapters send on a denial, as a Standard
-* Schema with a JSON Schema, for `oc.errors({ FORBIDDEN: { data: problemDetails } })`.
+* The Problem Details body the adapters send on a denial, as a Standard Schema
+* with a JSON Schema, for `oc.errors({ FORBIDDEN: { data: problemDetails } })`.
 * Extension members pass through: RFC 9457 lets a problem type add them.
 */
 const problemDetails = Object.freeze({ "~standard": Object.freeze({
@@ -512,18 +524,16 @@ function isList(permission) {
 function listOf(permission) {
 	return isList(permission) ? permission : [permission];
 }
-/** The `x-permdock-permissions` value: the permission keys an operation enforces. */
+/**
+* The `x-permdock-permissions` value: the permission keys an operation
+* enforces.
+*/
 function permissionsExtension(permissions) {
 	return Object.freeze(listOf(permissions).map((leaf) => leaf.key));
 }
-/**
-* An operation's `security` and `x-permdock-permissions`, from permission
-* references alone. Needs no policy, so a contract package can import it.
-* Unlike `permdock openapi emit`, it never drops `security` for a public
-* permission: that needs the policy.
-*/
 function securityFor(permission, options = {}) {
 	const leaves = listOf(permission);
+	if (options.security === false) return Object.freeze({ "x-permdock-permissions": permissionsExtension(leaves) });
 	const scheme = options.scheme ?? "oauth2";
 	const security = options.anyOf === true && leaves.length > 0 ? leaves.map((leaf) => ({ [scheme]: [leaf.scope] })) : [{ [scheme]: leaves.map((leaf) => leaf.scope) }];
 	return Object.freeze({

package/dist/{openapi-C4dDTVEd.js → openapi-CBZUhA3l.js}

@@ -1,6 +1,6 @@
-import { c as missingInput } from "./errors-CWTY6uih.js";
+import { c as missingInput } from "./errors-Vpu6rKHl.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";
+import { c as given, d as policyFlag, f as validatorFlag, l as outFlag, o as fileOut, t as checkFlag } from "./flags-DXjoTVbS.js";
 //#region src/cli/commands/openapi.ts
 const docFlag = { doc: {
 	type: "string",
@@ -80,7 +80,7 @@ const emit = defineLeaf({
 		}
 	},
 	async run(ctx, { flags }) {
-		return (await import("./openapi-DD1SV-5-.js")).runOpenapi({
+		return (await import("./openapi-VeHHU2l9.js")).runOpenapi({
 			cwd: ctx.cwd,
 			config: ctx.config,
 			rest: ["emit"],
@@ -122,8 +122,7 @@ const importDocument = defineLeaf({
 	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({
+		return (await import("./import-_YqhhwvX.js")).runOpenapiImport({
 			cwd: ctx.cwd,
 			doc,
 			out: fileOut("openapi import", flags.out),

package/dist/{openapi-DD1SV-5-.js → openapi-VeHHU2l9.js}

@@ -1,13 +1,13 @@
 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-DbM5YYtV.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 { a as getResource, n as findPermission } from "./permission-registry-B8tYxPIt.js";
+import { r as definePolicy } from "./policy-CLQ8__GF.js";
+import { i as configError } from "./errors-Vpu6rKHl.js";
+import { i as readJsonFile, s as writeFileEnsuringDir } from "./files-BSjrtIHw.js";
+import { a as loadModule, n as asPolicy, s as pickNamed, t as asPermissionTree } from "./load-DjSU5KXO.js";
+import { t as shortDiff } from "./text-diff-BtfSmdUo.js";
+import { c as openapiVersion, o as createPermDock } from "./openapi-BOsx0xn9.js";
+import { i as fileDrift } from "./output-files-BIQ_9pIs.js";
+import { n as validateOverlay, t as validateOpenapi } from "./schema-Dst9I9Gs.js";
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 //#region src/cli/openapi/openapi.ts
@@ -17,7 +17,10 @@ function mergeRecord(base, extra) {
 	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. */
+/**
+* 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)) {
@@ -68,7 +71,10 @@ function leavesOf(policy, keys) {
 		return leaf;
 	});
 }
-/** Operations carrying `x-permdock-permissions`, joined by `operationId`; those without one are findings. */
+/**
+* Operations carrying `x-permdock-permissions`, joined by `operationId`; those
+* without one are findings.
+*/
 function overlayOperations(document, policy) {
 	const operations = [];
 	const unnamed = [];
@@ -94,7 +100,10 @@ function overlayOperations(document, policy) {
 		secured
 	};
 }
-/** `instance` when any listed permission acts on one row; the id is the last path template parameter. */
+/**
+* `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];
@@ -213,11 +222,11 @@ async function runOpenapi(input) {
 		code: 1,
 		output: `openapi drift: the source already sets security the Overlay replaces on ${covered.secured.join(", ")}`
 	};
-	const result = covered !== void 0 ? openapi.overlay({
+	const result = covered === void 0 ? applyDocument(parsed, policy, openapi, input.arity === true, input.target) : 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,

package/dist/{operation-findings-DgATDpvh.js → operation-findings-CXtFzlKJ.js}

@@ -1,4 +1,4 @@
-import { n as OPERATION_RISKS } from "./permissions-B-wCP5ZC.js";
+import { n as OPERATION_RISKS } from "./permissions-CVXmRILq.js";
 //#region src/catalog/operation-findings.ts
 function rank(risk) {
 	return OPERATION_RISKS.indexOf(risk ?? "low");
@@ -8,8 +8,8 @@ function requiresApproval(catalog, permission) {
 }
 /**
 * Operations, matched by name, whose `meta.risk` rose or whose permission
-* stopped requiring approval between two catalogs. A new or removed
-* operation is not a finding.
+* stopped requiring approval between two catalogs. A new or removed operation
+* is not a finding.
 */
 function operationFindings(previous, next) {
 	const before = new Map((previous.operations ?? []).map((operation) => [operation.name, operation]));

package/dist/{operations-X0VM7F3m.d.ts → operations-Ci_rT6Uo.d.ts}

@@ -1,4 +1,4 @@
-import { E as PermissionTree, w as Permission } from "./vocabulary-CN8H_9UF.js";
+import { f as PermissionTree, u as Permission } from "./permission-types-CAY-GU7e.js";
 //#region src/core/operation-risks.d.ts
 type OperationRisk = "low" | "medium" | "high" | "critical";
 /** Every `meta.risk` level, lowest first. */
@@ -7,7 +7,10 @@ declare function isOperationRisk(value: unknown): value is OperationRisk;
 //#endregion
 //#region src/core/operations.d.ts
 type OperationEffect = "read" | "write" | "delete" | "send" | "spend" | "external";
-/** Plain JSON a host reads to label, confirm or gate an operation; PermDock never decides on it. */
+/**
+ * Plain JSON a host reads to label, confirm or gate an operation; PermDock
+ * never decides on it.
+ */
 type OperationMeta = {
   readonly risk?: OperationRisk;
   /** What running the operation does, each effect at most once. */
@@ -15,9 +18,9 @@ type OperationMeta = {
   readonly title?: string;
 };
 /**
- * Loads the row the check runs on from the operation's input, the binding
- * every surface shares. The row is validated against the permission's
- * resource schema like any request-derived data (invariant 9).
+ * Loads the row the check runs on from the operation's input, the binding every
+ * surface shares. The row is validated against the permission's resource schema
+ * like any request-derived data (invariant 9).
  */
 type OperationData<TInput = never> = {
   load(input: TInput): unknown;
@@ -32,8 +35,8 @@ type OperationDefinition = {
 };
 /**
  * A permission-bound action that agent tools, workflow nodes, MCP operations,
- * HTTP routes and chat commands read by name. `TInput` is the parameter type
- * of `data`; an operation without `data` takes `undefined`.
+ * HTTP routes and chat commands read by name. `TInput` is the parameter type of
+ * `data`; an operation without `data` takes `undefined`.
  */
 type Operation<TInput = unknown, TName extends string = string, TPermission extends Permission = Permission> = {
   readonly name: TName;

package/dist/orpc/index.d.ts

@@ -1,11 +1,44 @@
-import { T as Policy, j as PolicyVocabulary, rr as Principal } from "../policy-types-n0uRTsW8.js";
-import { w as Permission } from "../vocabulary-CN8H_9UF.js";
-import { r as PermDock } from "../permdock-SV8ZINYT.js";
-import { n as RevocationFeed } from "../revocations-R07lFBnX.js";
-import { D as ConnectionOptions, T as Connection, i as OpenApiHooks } from "../server-types-CKQiCnON.js";
-import { t as ServerAdapterOptions } from "../bind-DOyrv6zi.js";
-import { t as StreamProtectOptions } from "../stream-CeCMJmBB.js";
-import { Middleware } from "@orpc/server";
+import { T as Policy, j as PolicyVocabulary, sr as Principal } from "../policy-types-CCiDRZBH.js";
+import { u as Permission } from "../permission-types-CAY-GU7e.js";
+import { a as OperationInput, t as Operation } from "../operations-Ci_rT6Uo.js";
+import { a as PermDock } from "../permdock-B6Sf4T_S.js";
+import { n as RevocationFeed } from "../revocations-BaUXHM1N.js";
+import { D as ConnectionOptions, T as Connection, i as OpenApiHooks } from "../server-types-CIlpSA2G.js";
+import { t as ServerAdapterOptions } from "../bind-Cp2hBHzP.js";
+import { t as StreamProtectOptions } from "../stream-ltuLdtTG.js";
+import { AnySchema, MetaPlugin, Middleware, Procedure, Schema } from "@orpc/server";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/orpc/operations.d.ts
+type OperationProcedureContext<TCtx extends object, V extends PolicyVocabulary = PolicyVocabulary> = TCtx & {
+  readonly permdock: PermDock<V>;
+  /** The row the operation's `data` loader read; `undefined` without one. */
+  readonly permdockData?: unknown;
+};
+type OperationRoute<TCtx extends object, TInput, V extends PolicyVocabulary = PolicyVocabulary> = {
+  readonly handler: (opts: {
+    readonly input: TInput;
+    readonly context: OperationProcedureContext<TCtx, V>;
+  }) => unknown;
+} & ([TInput] extends [undefined] ? {
+  readonly input?: StandardSchemaV1<unknown, TInput>;
+} : {
+  /** Required: the operation's `data` loader never sees raw input. */
+  readonly input: StandardSchemaV1<unknown, TInput>;
+});
+type OperationRoutes<TOperations extends Readonly<Record<string, Operation>>, TCtx extends object, V extends PolicyVocabulary = PolicyVocabulary> = { readonly [TName in keyof TOperations]: OperationRoute<TCtx, OperationInput<TOperations[TName]>, V>; };
+type OperationsRouterOptions = {
+  /** oRPC meta plugins per operation, such as `openapi()` from `@orpc/openapi`. */
+  readonly meta?: (operation: Operation) => readonly MetaPlugin<AnySchema, AnySchema, Record<never, never>>[];
+};
+type InputSchemaOf<TRoute> = TRoute extends {
+  readonly input: infer TSchema extends AnySchema;
+} ? TSchema : Schema<undefined>;
+type OutputOf<TRoute> = TRoute extends {
+  readonly handler: (...args: never[]) => infer TResult;
+} ? Awaited<TResult> : never;
+type OperationsRouter<TCtx extends object, TRoutes> = { readonly [TName in keyof TRoutes]: Procedure<TCtx, any, InputSchemaOf<TRoutes[TName]>, Schema<OutputOf<TRoutes[TName]>>, Record<never, never>>; };
+type OperationsRouterOf<TCtx extends object, V extends PolicyVocabulary> = <TOperations extends Readonly<Record<string, Operation>>, const TRoutes extends OperationRoutes<TOperations, TCtx, V>>(operations: TOperations, routes: TRoutes, options?: OperationsRouterOptions) => OperationsRouter<TCtx, TRoutes>;
+//#endregion
 //#region src/orpc/create.d.ts
 type OrpcMiddlewareOpts<TCtx extends object = object, TInput = unknown> = {
   readonly context: TCtx;
@@ -20,7 +53,10 @@ type OrpcMiddleware<TCtx extends object = object, TInput = unknown, V extends Po
   readonly permdockData?: unknown;
 }, TInput, any, Record<never, never>>;
 type OrpcPermDockOptions<TCtx extends object = object, TUser = unknown> = ServerAdapterOptions<OrpcMiddlewareOpts<TCtx>, TUser> & {
-  /** The Web `Request` behind a context; defaults to `context.request` or `context.req`. */
+  /**
+   * The Web `Request` behind a context; defaults to `context.request` or
+   * `context.req`.
+   */
   readonly request?: (context: TCtx) => Request | null | undefined;
   /** Ends or revalidates open event iterators. */
   readonly revocations?: RevocationFeed;
@@ -31,10 +67,22 @@ type OrpcOpenApiHooks<TCtx extends object = object, V extends PolicyVocabulary =
     readonly security: readonly Record<string, readonly string[]>[];
     readonly "x-permdock-permissions": readonly string[];
   };
+  /**
+   * `security` as the merge function oRPC 2's `openapi({ spec })` takes, with
+   * mutable arrays so it type-checks against oRPC's `OperationObject`.
+   */
+  readonly spec: (permission: Permission) => <TSpec extends object>(current: TSpec) => TSpec & OrpcSecuritySpec;
   readonly securitySchemes: OpenApiHooks["securitySchemes"];
 };
+type OrpcSecuritySpec = {
+  security: Record<string, string[]>[];
+  "x-permdock-permissions": string[];
+};
 type OrpcPermDock<TCtx extends object = object, V extends PolicyVocabulary = PolicyVocabulary> = {
-  /** The `PermDock` for one procedure call, for code the middleware does not run before. */
+  /**
+   * The `PermDock` for one procedure call, for code the middleware does not run
+   * before.
+   */
   readonly getPermDock: (opts: OrpcMiddlewareOpts<TCtx>) => Promise<PermDock<V>>;
   readonly middleware: () => OrpcMiddleware<TCtx, unknown, V>;
   readonly protect: (permission: Permission | null, data?: (opts: OrpcMiddlewareOpts<TCtx>) => unknown, protectOptions?: StreamProtectOptions) => OrpcMiddleware<TCtx, unknown, V>;
@@ -42,13 +90,19 @@ type OrpcPermDock<TCtx extends object = object, V extends PolicyVocabulary = Pol
   readonly connection: (opts: OrpcMiddlewareOpts<TCtx>, connectionOptions?: ConnectionOptions) => Promise<Connection>;
   readonly permdockHandler: () => (request: Request) => Promise<Response>;
   readonly openapi: OrpcOpenApiHooks<TCtx, V>;
+  /**
+   * One procedure per `defineOperations` entry, guarded by the operation's
+   * permission and `data` loader; `meta` attaches oRPC meta such as
+   * `openapi()`.
+   */
+  readonly operationsRouter: OperationsRouterOf<TCtx, V>;
 };
 /**
- * The permission the procedure's first `protect` decides, or `undefined`
- * when no `protect` is attached. Reads the procedure definition only and
- * never decides.
+ * The permission the procedure's first `protect` decides, or `undefined` when
+ * no `protect` is attached. Reads the procedure definition only and never
+ * decides.
  */
 export declare function permissionOf(procedure: unknown): Permission | undefined;
 export declare function createPermDock<TCtx extends object = object, TUser = unknown, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, options: OrpcPermDockOptions<TCtx, TUser>): OrpcPermDock<TCtx, V>;
 //#endregion
-export type { OrpcMiddleware, OrpcMiddlewareOpts, OrpcOpenApiHooks, OrpcPermDock, OrpcPermDockOptions };
+export type { OperationProcedureContext, OperationRoute, OperationRoutes, OperationsRouter, OperationsRouterOf, OperationsRouterOptions, OrpcMiddleware, OrpcMiddlewareOpts, OrpcOpenApiHooks, OrpcPermDock, OrpcPermDockOptions, OrpcSecuritySpec };