permdock 0.7.0 → 0.8.0

package/dist/next/index.d.ts

@@ -1,13 +1,15 @@
-import { Bn as DenialReason, Gt as Snapshot, Ln as Decision, T as Policy, j as PolicyVocabulary, lr as Subject, sr as Principal } from "../policy-types-B-F-qAZk.js";
-import { u as Permission } from "../permission-types-DhNEmoRG.js";
-import { a as PermDock } from "../permdock-Dco6dyCK.js";
-import { m as ApprovalStore } from "../types-DC44-hqb.js";
-import { t as InstanceOptions } from "../instance-options-CU0YQCLH.js";
-import { n as PermDockWrap } from "../wrap-B6R0cMRL.js";
-import { o as OtelWrap } from "../types-CIeZcG8v.js";
-import { n as DescribeMessages } from "../describe-O0SwYIK8.js";
-import { a as snapshotHeaders, i as cacheLifeFor, n as SnapshotHeaders, o as snapshotTag, r as SnapshotHeadersOptions, t as CacheLifeForOptions } from "../snapshot-cache-Pahd3IYJ.js";
+import { Bn as DenialReason, Gt as Snapshot, Ln as Decision, T as Policy, j as PolicyVocabulary, lr as Subject, sr as Principal } from "../policy-types-CCiDRZBH.js";
+import { u as Permission } from "../permission-types-CAY-GU7e.js";
+import { a as PermDock, d as UncheckedData, s as RowData } from "../permdock-B6Sf4T_S.js";
+import { m as ApprovalStore } from "../types-B_tiYvk8.js";
+import { t as InstanceOptions } from "../instance-options-B0KXqTrJ.js";
+import { n as PermDockWrap } from "../wrap-DlJE3gS_.js";
+import { o as OtelWrap } from "../types-DHKPcqzr.js";
+import { n as DescribeMessages } from "../describe-ByS9LgHK.js";
+import { a as snapshotHeaders, i as cacheLifeFor, n as SnapshotHeaders, o as snapshotTag, r as SnapshotHeadersOptions, t as CacheLifeForOptions } from "../snapshot-cache-BAXZ0KOp.js";
+import { n as ProtectedAction, t as ActionResult } from "../action-result-CL-QCITA.js";
 import { ReactElement, ReactNode } from "react";
+import { StandardSchemaV1 } from "@standard-schema/spec";
 //#region src/next/types.d.ts
 type NextSubjectInput = unknown;
 type NextPermDockOptions<TUser = NextSubjectInput> = InstanceOptions & {
@@ -18,12 +20,15 @@ type NextPermDockOptions<TUser = NextSubjectInput> = InstanceOptions & {
   readonly store?: ApprovalStore;
   /** `(permdock) => withOtel(permdock, options)` from `permdock/otel`. */
   readonly otel?: OtelWrap;
-  /** Wraps each instance after `otel`; build it with `wrapPermDock` to cover derived instances. */
+  /**
+   * Wraps each instance after `otel`; build it with `wrapPermDock` to cover
+   * derived instances.
+   */
   readonly wrap?: PermDockWrap;
   /**
-   * Where `PermDockProvider` sends checks the snapshot cannot answer; default `/api/permdock`.
-   * `false` is snapshot-only: no `permdockHandler` route, and those checks are denied with
-   * reason `server-only`.
+   * Where `PermDockProvider` sends checks the snapshot cannot answer; default
+   * `/api/permdock`. `false` is snapshot-only: no `permdockHandler` route, and
+   * those checks are denied with reason `server-only`.
    */
   readonly endpoint?: string | false;
 };
@@ -35,7 +40,10 @@ type GetSnapshotQuery = GetPermDockQuery & {
     readonly [key: string]: unknown;
   })[];
   readonly tenants?: "all";
-  /** Tags added next to `snapshotTag(sub)`, such as the app's own organisation tag. */
+  /**
+   * Tags added next to `snapshotTag(sub)`, such as the app's own organisation
+   * tag.
+   */
   readonly tags?: readonly string[];
 };
 type PermissionRequirementOptions = GetPermDockQuery & {
@@ -59,7 +67,10 @@ type NextPermDockProviderProps = {
   readonly tenants?: "all";
   /** Overrides the factory's `endpoint`; `false` is snapshot-only. */
   readonly endpoint?: string | false;
-  /** Suspends permission readers until the snapshot streams in, instead of answering `pending`. */
+  /**
+   * Suspends permission readers until the snapshot streams in, instead of
+   * answering `pending`.
+   */
   readonly suspend?: boolean;
   /**
    * What every `<Protected>` below renders for a slot it leaves out. Nodes
@@ -79,18 +90,39 @@ type PermDockHandler = {
   readonly POST: (request: Request) => Promise<Response>;
   readonly GET: (request: Request) => Promise<Response>;
 };
+type ProtectActionOptions<TInput, TRow> = {
+  /** Validates the action's argument before anything else runs. */
+  readonly input: StandardSchemaV1<unknown, TInput>;
+  /** The row to decide on; `null` or `undefined` answers `404`. */
+  readonly data?: (input: TInput) => TRow | null | undefined | Promise<TRow | null | undefined>;
+  /** The tenant to build the instance for; default the factory's `tenant`. */
+  readonly tenant?: (input: TInput) => string | undefined;
+};
+type ProtectedActionContext<TRow, V extends PolicyVocabulary> = {
+  readonly permdock: PermDock<V>;
+  readonly decision: Extract<Decision, {
+    readonly outcome: "granted";
+  }>;
+  /** The loaded row; `undefined` without a `data` loader. */
+  readonly data: TRow;
+};
+type ProtectedActionHandler<TInput, TRow, TResult, V extends PolicyVocabulary> = (input: TInput, context: ProtectedActionContext<TRow, V>) => TResult | Promise<TResult>;
+type ProtectAction<V extends PolicyVocabulary> = <TInput, TRow = undefined>(permission: Permission, options: ProtectActionOptions<TInput, TRow>) => <TResult>(handler: ProtectedActionHandler<TInput, TRow, TResult, V>) => ProtectedAction<Awaited<TResult>>;
 type NextPermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
   readonly getPermDock: (query?: GetPermDockQuery) => Promise<PermDock<V>>;
   /**
-   * `{ allowed, status: 'ready', decision }`. Any failure to build the
-   * instance denies; Next.js interrupts (`redirect()`, `notFound()`,
-   * request-time bailouts) from `subject` or `tenant` pass through.
+   * `{ allowed, status: 'ready', decision }`. Any failure to build the instance
+   * denies; Next.js interrupts (`redirect()`, `notFound()`, request-time
+   * bailouts) from `subject` or `tenant` pass through.
    */
-  readonly getPermission: (permission: Permission, data?: unknown, query?: GetPermDockQuery) => Promise<ServerPermissionState>;
+  readonly getPermission: {
+    <D>(permission: Permission, data?: UncheckedData<D>, query?: GetPermDockQuery): Promise<ServerPermissionState>;
+    <P extends Permission>(permission: P, data?: RowData<P>, query?: GetPermDockQuery): Promise<ServerPermissionState>;
+  };
   /**
    * The session's snapshot for a `'use cache: private'` function the app owns:
-   * calls `cacheLife(cacheLifeFor(snapshot))` and `cacheTag(snapshotTag(sub), ...tags)`
-   * in that scope, and throws outside one.
+   * calls `cacheLife(cacheLifeFor(snapshot))` and `cacheTag(snapshotTag(sub),
+   * ...tags)` in that scope, and throws outside one.
    */
   readonly getSnapshot: (query?: GetSnapshotQuery) => Promise<Snapshot>;
   /**
@@ -99,15 +131,29 @@ type NextPermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
    * subject and `forbidden()` otherwise (`experimental.authInterrupts`);
    * approval-required and boundary validation throw as from `assert`.
    */
-  readonly requirePermission: (permission: Permission, data?: unknown, options?: PermissionRequirementOptions) => Promise<Extract<Decision, {
-    readonly outcome: "granted";
-  }>>;
-  /** Never awaits: passes an unawaited snapshot to the client provider, whose hooks suspend. */
+  readonly requirePermission: {
+    <D>(permission: Permission, data?: UncheckedData<D>, options?: PermissionRequirementOptions): Promise<Extract<Decision, {
+      readonly outcome: "granted";
+    }>>;
+    <P extends Permission>(permission: P, data?: RowData<P>, options?: PermissionRequirementOptions): Promise<Extract<Decision, {
+      readonly outcome: "granted";
+    }>>;
+  };
+  /**
+   * Never awaits: passes an unawaited snapshot to the client provider, whose
+   * hooks suspend.
+   */
   readonly PermDockProvider: (props: NextPermDockProviderProps) => ReactElement;
   readonly permdockHandler: () => PermDockHandler;
+  /**
+   * Wraps a server action: validates `input`, loads `data`, decides, then runs
+   * the handler. Resolves to `{ ok: true, value }` or `{ ok: false, problem }`
+   * with RFC 9457 Problem Details; only Next.js interrupts throw.
+   */
+  readonly protectAction: ProtectAction<V>;
 };
 //#endregion
 //#region src/next/create.d.ts
 export declare function createPermDock<TUser = NextSubjectInput, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, given: NextPermDockOptions<TUser>): NextPermDock<V>;
 //#endregion
-export { type CacheLifeForOptions, type GetPermDockQuery, type GetSnapshotQuery, type NextPermDock, type NextPermDockOptions, type NextPermDockProviderProps, type PermDockHandler, type PermissionRequirementOptions, type ServerPermissionState, type SnapshotHeaders, type SnapshotHeadersOptions, cacheLifeFor, snapshotHeaders, snapshotTag };
+export { type ActionResult, type CacheLifeForOptions, type GetPermDockQuery, type GetSnapshotQuery, type NextPermDock, type NextPermDockOptions, type NextPermDockProviderProps, type PermDockHandler, type PermissionRequirementOptions, type ProtectAction, type ProtectActionOptions, type ProtectedAction, type ProtectedActionContext, type ProtectedActionHandler, type ServerPermissionState, type SnapshotHeaders, type SnapshotHeadersOptions, cacheLifeFor, snapshotHeaders, snapshotTag };

package/dist/next/index.js

@@ -1,15 +1,113 @@
 import { t as compact } from "../compact-CAf557ZB.js";
-import { l as withApp } from "../permdock-BfWEeMqk.js";
-import { n as wrapPermDock } from "../wrap-CiSc_KCq.js";
-import { n as snapshotHeaders, r as snapshotTag, t as cacheLifeFor } from "../snapshot-cache-DT2Kx1F8.js";
-import { n as resolveOrNull, t as buildInstance } from "../build-instance-DxE7czo9.js";
-import { _ as NO_GRANT, o as evaluationsHandler } from "../evaluations-DReoiVBw.js";
+import { n as PermDockValidationError } from "../validation-error-CYg2kJEw.js";
+import { o as statusProblem, t as notFoundDetails } from "../problem-details-CLDgX1KV.js";
+import { n as isThenable } from "../thenable-BNSM1U2R.js";
+import { n as resourceRef } from "../resource-ref-CaS9yVPi.js";
+import { l as withApp } from "../permdock-L-_I_3zP.js";
+import { n as wrapPermDock } from "../wrap-B2wziJI_.js";
+import { i as decisionProblem } from "../problem-BVLHFK33.js";
+import { s as resumeDecision } from "../helpers-DJicaG6f.js";
+import { n as snapshotHeaders, r as snapshotTag, t as cacheLifeFor } from "../snapshot-cache-Bx_4xC_6.js";
+import { n as resolveOrNull, t as buildInstance } from "../build-instance-CNWaYJyr.js";
+import { _ as LOAD_FAILED, o as evaluationsHandler, v as NO_GRANT } from "../evaluations-IBceAeKT.js";
 import { cache } from "react";
 import { jsx } from "react/jsx-runtime";
 import { forbidden, unauthorized, unstable_rethrow } from "#next/navigation";
 import { cacheLife, cacheTag, io } from "next/cache.js";
 import { after } from "next/server.js";
 import { PermDockProvider } from "../react/provider-client.js";
+//#region src/next/action.ts
+function refused(problem) {
+	return {
+		ok: false,
+		problem
+	};
+}
+/** Issues reduced to JSON a server action can return: a symbol path is lost. */
+function plainIssues(issues) {
+	return issues.map((issue) => compact({
+		message: issue.message,
+		path: issue.path?.map((segment) => {
+			const key = typeof segment === "object" ? segment.key : segment;
+			return typeof key === "number" ? key : String(key);
+		})
+	}));
+}
+async function parseInput(schema, value) {
+	const result = schema["~standard"].validate(value);
+	const settled = isThenable(result) ? await result : result;
+	if (settled.issues === void 0) return settled;
+	return { issues: plainIssues(settled.issues) };
+}
+function invalidInput(permission, issues) {
+	return refused(new PermDockValidationError({
+		code: "invalid-data",
+		permission: permission.key,
+		resource: permission.resource,
+		issues,
+		boundary: "action-input",
+		message: `${permission.key}: ${issues.map((issue) => issue.message).join("; ")}.`
+	}).toProblemDetails());
+}
+/**
+* `protectAction(permission, { input, data?, tenant? })(handler)`: validates
+* the input, loads the row, decides, then runs the handler. Every refusal,
+* including a throw, is a Problem Details result; nothing but Next.js
+* interrupts leaves as an exception.
+*/
+function protectActionOf(deps) {
+	return (permission, options) => (handler) => async (value, call) => {
+		const parsed = await parseInput(options.input, value);
+		if (parsed.issues !== void 0) return invalidInput(permission, parsed.issues);
+		const input = parsed.value;
+		let permdock;
+		let data;
+		try {
+			permdock = await deps.getPermDock(compact({ tenant: options.tenant?.(input) }));
+		} catch (error) {
+			deps.rethrow(error);
+			return refused(decisionProblem(NO_GRANT, permission, void 0));
+		}
+		if (options.data !== void 0) {
+			try {
+				data = await options.data(input) ?? void 0;
+			} catch (error) {
+				deps.rethrow(error);
+				return refused(decisionProblem(LOAD_FAILED, permission, void 0));
+			}
+			if (data === void 0) return refused(notFoundDetails());
+		}
+		const decide = permdock.decide;
+		const decision = await resumeDecision({
+			decision: decide(permission, data, {
+				call: "adapter",
+				adapter: "next",
+				trusted: true
+			}),
+			permission,
+			subject: permdock.subject,
+			store: deps.store,
+			resource: resourceRef(permission, data),
+			adapter: "next",
+			token: call?.approval
+		});
+		if (decision.outcome !== "granted") return refused(decisionProblem(decision, permission, permdock.subject, compact({ disclosure: data === void 0 ? void 0 : deps.policy.resources.get(permission.resource)?.disclosure })));
+		try {
+			return {
+				ok: true,
+				value: await handler(input, {
+					permdock,
+					decision,
+					data
+				})
+			};
+		} catch (error) {
+			deps.rethrow(error);
+			return refused(statusProblem(500, `${permission.key}: the action failed`));
+		}
+	};
+}
+//#endregion
 //#region src/next/provider.tsx
 function renderClientProvider(options) {
 	return /* @__PURE__ */ jsx(PermDockProvider, {
@@ -171,7 +269,13 @@ function createPermDock(policy, given) {
 		getSnapshot,
 		requirePermission,
 		PermDockProvider,
-		permdockHandler
+		permdockHandler,
+		protectAction: protectActionOf({
+			policy,
+			getPermDock,
+			store: options.store,
+			rethrow: unstable_rethrow
+		})
 	};
 }
 //#endregion

package/dist/next/plugin.d.ts

@@ -1,4 +1,4 @@
-import { a as PermDockPluginOptions } from "../types-BWZybqs9.js";
+import { s as PermDockPluginOptions } from "../types-DC1Loeh3.js";
 //#region src/cli/plugin.d.ts
 /** Any object: Next's `NextConfig` is an interface, so no index signature. */
 type NextConfigLike = object;

package/dist/next/plugin.js

@@ -1,5 +1,5 @@
-import { a as describeError } from "../errors-DpP_U6Bf.js";
-import { n as createCollectScheduler, r as report, t as collectOnce } from "../watch-C-4VmFlL.js";
+import { a as describeError } from "../errors-Vpu6rKHl.js";
+import { n as createCollectScheduler, r as report, t as collectOnce } from "../watch-Cx_WciLE.js";
 //#region src/cli/plugin.ts
 const PHASE_BUILD = "phase-production-build";
 const PHASE_DEV = "phase-development-server";
@@ -27,7 +27,8 @@ function createPermDockPlugin(options) {
 	};
 }
 async function runPluginCollect(cwd, options, check) {
-	return (await collectOnce(cwd, options, check, false)).message;
+	const { message } = await collectOnce(cwd, options, check, false);
+	return message;
 }
 //#endregion
 export { createPermDockPlugin };

package/dist/node/index.d.ts

@@ -1,8 +1,8 @@
-import { T as Policy, j as PolicyVocabulary, sr as Principal } from "../policy-types-B-F-qAZk.js";
-import { u as Permission } from "../permission-types-DhNEmoRG.js";
-import { a as PermDock } from "../permdock-Dco6dyCK.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-C4gZUEZy.js";
-import { t as ServerAdapterOptions } from "../bind-JDuvxjuW.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 { f as InvalidSignatureError, i as OpenApiHooks, o as ProtectOptions, r as Guard, s as ScopeGuard, v as discoverViaSignatureAgent, x as webBotAuthVerifier } from "../server-types-CIlpSA2G.js";
+import { t as ServerAdapterOptions } from "../bind-Cp2hBHzP.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

package/dist/node/index.js

@@ -1,6 +1,6 @@
-import { l as InvalidSignatureError, p as webBotAuthVerifier, u as discoverViaSignatureAgent } from "../evaluations-DReoiVBw.js";
-import { r as bindKernel } from "../bind-D1nO6fiC.js";
-import { n as sendResponse, r as toRequest, t as isServerResponse } from "../http-ujKm0JXE.js";
+import { l as InvalidSignatureError, p as webBotAuthVerifier, u as discoverViaSignatureAgent } from "../evaluations-IBceAeKT.js";
+import { r as bindKernel } from "../bind-D_sZSVA3.js";
+import { n as sendResponse, r as toRequest, t as isServerResponse } from "../http-DH94eh6f.js";
 //#region src/node/create.ts
 const nodeRequest = (req) => req;
 function createPermDock(policy, options) {

package/dist/{ocsf-BFp-PZZA.js → ocsf-TcjRBgIs.js}

@@ -19,26 +19,36 @@ function status(outcome) {
 		default: return unknownStatus(outcome);
 	}
 }
-/** An outcome this build does not know, from a newer producer, is reported as OCSF Unknown. */
+/**
+* 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. */
+/**
+* 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. */
+/**
+* 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`.
+* 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);

package/dist/openai/index.d.ts

@@ -1,8 +1,8 @@
-import { T as Policy, j as PolicyVocabulary, sr as Principal } from "../policy-types-B-F-qAZk.js";
-import { u as Permission } from "../permission-types-DhNEmoRG.js";
-import { a as PermDock } from "../permdock-Dco6dyCK.js";
-import { u as ApprovalRequest } from "../types-DC44-hqb.js";
-import { o as AgentAdapterOptions, t as AgentPermDock } from "../create-UTnUVETj.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 { l as withApp } from "../permdock-BfWEeMqk.js";
-import { t as approvalTokenOf } from "../kernel-DVExUwkp.js";
-import { t as agentRuntime } from "../create-Cb86Z8Im.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, mr as Condition, sr as Principal } from "../policy-types-B-F-qAZk.js";
-import { f as PermissionTree, u as Permission } from "../permission-types-DhNEmoRG.js";
-import { a as ProblemDetails } from "../errors-B_Qg9D3e.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,21 +155,30 @@ 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. */
+/**
+ * `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;
 };
@@ -171,7 +189,10 @@ 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

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-Ddb4628T.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 };