permdock 0.0.0 → 0.2.0

package/dist/node/index.js

@@ -0,0 +1,34 @@
+import { i as discoverViaSignatureAgent, r as InvalidSignatureError, s as verifyWebBotAuth } from "../evaluations-tz6D9A2G.js";
+import { r as bindKernel } from "../bind-VnYn2HKq.js";
+import { i as toRequest, n as isServerResponse, r as sendResponse, t as fromResponse } from "../http-BIhmLfCc.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 permdockHandler = () => {
+		const { POST, GET } = kernel.permdockHandler(handlerScope);
+		return async (req, res) => {
+			if (req.method === "GET" || req.method === "HEAD") {
+				await sendResponse(res, await GET(bind(req)));
+				return;
+			}
+			await sendResponse(res, await POST(bound.rebind(nodeRequest(req))));
+		};
+	};
+	return {
+		permdock,
+		protect,
+		send: sendResponse,
+		permdockHandler,
+		toRequest,
+		fromResponse,
+		openapi: kernel.openapi
+	};
+}
+//#endregion
+export { InvalidSignatureError, createPermDock, discoverViaSignatureAgent, fromResponse, isServerResponse, sendResponse, toRequest, verifyWebBotAuth };

package/dist/openai/index.d.ts

@@ -0,0 +1,62 @@
+import { C as Policy, D as PolicyVocabulary, Nr as Principal, kr as Delegation, ln as PermDock } from "../policy-CFZAr_Al.js";
+import { f as Permission } from "../permissions-DttnqqxC.js";
+import { c as ApprovalRequest, f as ApprovalStore } from "../types-vKyAMtcX.js";
+import { t as InstanceOptions } from "../instance-options-BK_rNOSC.js";
+import { t as ToolMap } from "../types-Bvc4oWT6.js";
+//#region src/openai/create.d.ts
+/** The app context passed to `run(agent, input, { context })`. */
+type OpenAiContext = {
+  readonly user?: unknown;
+  readonly agentId?: string;
+  readonly permdockApproval?: string;
+  readonly [key: string]: unknown;
+};
+/** Structural `RunContext` from `@openai/agents`: the app context sits under `context`. */
+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 OpenAiTool = {
+  readonly name: string;
+};
+/** Structural `RunToolApprovalItem` from `@openai/agents`. */
+type OpenAiInterruption = {
+  readonly type?: string;
+  readonly name?: string | undefined;
+  readonly arguments?: string | undefined;
+  readonly rawItem?: {
+    readonly type?: string;
+    readonly callId?: string;
+    readonly name?: string;
+    readonly arguments?: unknown;
+  };
+};
+/** Structural `RunState` from `@openai/agents`. */
+type OpenAiRunState<TItem> = {
+  approve(item: TItem, options?: {
+    alwaysApprove?: boolean;
+  }): unknown;
+  reject(item: TItem, options?: {
+    alwaysReject?: boolean;
+    message?: string;
+  }): unknown;
+};
+type OpenAiPermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
+  /** 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>>;
+};
+export declare function createPermDock<TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, options: OpenAiPermDockOptions<TUser>): OpenAiPermDock<V>;
+//#endregion
+export type { OpenAiContext, OpenAiInterruption, OpenAiPermDock, OpenAiPermDockOptions, OpenAiRunState, OpenAiTool };

package/dist/openai/index.js

@@ -0,0 +1,92 @@
+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-GSQnMz3O.js";
+//#region src/openai/create.ts
+function appContext(runContext) {
+	const context = runContext?.context;
+	return typeof context === "object" && context !== null ? context : {};
+}
+function parseCall(item) {
+	const name = item.name ?? item.rawItem?.name;
+	if (typeof name !== "string") return { ok: false };
+	const raw = item.arguments ?? item.rawItem?.arguments;
+	if (typeof raw !== "string") return typeof raw === "object" && raw !== null ? {
+		ok: true,
+		name,
+		args: raw
+	} : { ok: false };
+	try {
+		return {
+			ok: true,
+			name,
+			args: JSON.parse(raw)
+		};
+	} catch {
+		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"
+	});
+	const byPermission = /* @__PURE__ */ new Map();
+	for (const [name, binding] of Object.entries(options.tools)) byPermission.set(binding.permission.key, name);
+	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];
+		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));
+	};
+	const resolveOne = async (state, item, context) => {
+		const call = parseCall(item);
+		if (!call.ok) {
+			await state.reject(item, { message: "Denied: unreadable tool call." });
+			return null;
+		}
+		const verdict = await kernel.decideTool(call.name, call.args, context, compact({ resumeToken: approvalTokenOf(context) }));
+		if (verdict.outcome === "granted") {
+			await state.approve(item);
+			return null;
+		}
+		if (verdict.outcome === "denied") {
+			await state.reject(item, { message: verdict.reason });
+			return null;
+		}
+		try {
+			return await store.get(verdict.token);
+		} catch {
+			return null;
+		}
+	};
+	const resolveInterruptions = async (state, interruptions, resolveOptions) => {
+		const resolved = [];
+		for (const item of interruptions) resolved.push(await resolveOne(state, item, resolveOptions.context));
+		return resolved.filter((record) => record !== null);
+	};
+	return {
+		needsApproval,
+		guardTools,
+		resolveInterruptions,
+		permdock: (context) => kernel.instance(context)
+	};
+}
+//#endregion
+export { createPermDock };

package/dist/openapi/index.d.ts

@@ -0,0 +1,176 @@
+import { C as Policy, Ir as Condition, Nr as Principal } from "../policy-CFZAr_Al.js";
+import { f as Permission, m as PermissionTree } from "../permissions-DttnqqxC.js";
+import { a as ProblemDetails } from "../errors-DAqevpNk.js";
+import { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/openapi/types.d.ts
+type OpenApiTarget = "3.1" | "3.2" | "3.3";
+type OverlayVersion = "1.1" | "1.2";
+type SecurityProfileName = "fapi2";
+type SchemeType = "oauth2" | "openIdConnect" | "http" | "apiKey" | "gnap";
+type OpenApiSchemeOptions = {
+  readonly name: string;
+  readonly type: SchemeType;
+  readonly oauth2MetadataUrl?: string;
+  readonly flows?: {
+    readonly authorizationCode?: Readonly<Record<string, unknown>>;
+    readonly clientCredentials?: Readonly<Record<string, unknown>>;
+    readonly deviceAuthorization?: Readonly<Record<string, unknown>>;
+  };
+  readonly openIdConnectUrl?: string;
+  readonly ref?: string;
+  /** Retires the scheme: `deprecated` on 3.2 and 3.3, `x-oai-deprecated` on 3.1. */
+  readonly deprecated?: boolean;
+};
+type OpenApiDocsHints = {
+  readonly badges?: boolean;
+};
+type OpenApiPermDockOptions = {
+  readonly scheme: OpenApiSchemeOptions;
+  readonly target?: OpenApiTarget;
+  readonly securityProfile?: SecurityProfileName;
+  readonly profileScheme?: string;
+  readonly docsHints?: OpenApiDocsHints;
+};
+type OpenApiSecurityRequirement = Readonly<Record<string, readonly string[]>>;
+type OpenApiDescribe = {
+  readonly security: readonly OpenApiSecurityRequirement[];
+  readonly "x-permdock-permissions": readonly string[];
+  /** Keyed by permission key: the portable conditions of its allow grants. */
+  readonly "x-permdock-conditions"?: Readonly<Record<string, Condition>>;
+  /** Keyed by permission key: the permissions whose grants need an approval. */
+  readonly "x-permdock-approval"?: Readonly<Record<string, {
+    readonly reason: "human";
+  }>>;
+  readonly "x-permdock-securityProfile"?: SecurityProfileName;
+  readonly "x-badges"?: readonly {
+    readonly name: string;
+  }[];
+};
+/** One operation the Overlay targets, joined by `operationId`. */
+type OverlayOperation = {
+  readonly operationId: string;
+  readonly permissions: readonly Permission[];
+};
+type OpenApiOverlayOptions = {
+  readonly extends?: string;
+  readonly version?: OverlayVersion;
+  /** The operations to cover; without them, one per permission whose `operationId` is the permission key. */
+  readonly operations?: readonly OverlayOperation[];
+};
+type OpenApiPermDock = {
+  readonly securitySchemes: () => Readonly<Record<string, unknown>>;
+  readonly security: (permission: Permission | readonly Permission[], options?: {
+    readonly anyOf?: boolean;
+  }) => readonly OpenApiSecurityRequirement[];
+  readonly describe: (permission: Permission | readonly Permission[], options?: {
+    readonly anyOf?: boolean;
+  }) => 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. */
+  readonly securityProfileRequirements: (scopeSets?: readonly (readonly string[])[]) => Readonly<Record<string, unknown>> | undefined;
+  readonly catalog: () => Record<string, unknown>;
+};
+type OpenApiFactory = <TUser, TPrincipal extends Principal = Principal>(policy: Policy<TUser, TPrincipal>, options: OpenApiPermDockOptions) => OpenApiPermDock;
+//#endregion
+//#region src/openapi/create.d.ts
+export declare const createPermDock: OpenApiFactory;
+//#endregion
+//#region src/openapi/pins.d.ts
+export declare const DRAFT_PINS: {
+  readonly oas: "3.3-dev@2026-09-01";
+  readonly securityProfiles: "oai-discussion-5304@2026-09-01";
+  readonly overlay: "1.2-dev@edd4adea";
+};
+export declare const PROFILE_NAMES: {
+  readonly fapi2: "fapi-20-security-profile";
+};
+export declare const GNAP_RESERVED = "scheme.type 'gnap' is reserved and emits nothing. See https://permdock.com/docs/standards/watch-list#gnap";
+//#endregion
+//#region src/openapi/emit.d.ts
+export declare function securitySchemesOf(policy: Policy, options: OpenApiPermDockOptions): Record<string, unknown>;
+export declare function catalogOf(options: OpenApiPermDockOptions, extraDrafts?: Readonly<Record<string, string>>): Record<string, unknown>;
+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)`).
+ */
+type OperationEntry = Permission | {
+  readonly permission: Permission;
+  readonly operationId?: string;
+  readonly oauthScopes?: readonly string[];
+} | {
+  readonly permission?: undefined;
+  readonly operationId?: string;
+  readonly oauthScopes: readonly string[];
+};
+/**
+ * The permission of each operation of an API, declared once and read by the
+ * HTTP gate and by `permdock/mcp`'s `permissionFor`, so a REST route and the
+ * MCP tool that calls it can never disagree.
+ */
+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.
+   */
+  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
+ * (`/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.
+ */
+export declare function operationPermissionsFromOpenApi(document: unknown, tree: PermissionTree, options?: {
+  readonly base?: string;
+}): OperationPermissions;
+//#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 } })`.
+ * 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. */
+  readonly scheme?: string;
+  /** Any one of the permissions suffices: one requirement per scope instead of one with every scope. */
+  readonly anyOf?: boolean;
+};
+type SecurityFor = {
+  readonly security: readonly OpenApiSecurityRequirement[];
+  readonly "x-permdock-permissions": readonly string[];
+};
+/** 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
+ * 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.
+ */
+export declare function securityFor(permission: Permission | readonly Permission[], options?: SecurityForOptions): SecurityFor;
+//#endregion
+export type { OpenApiDescribe, OpenApiDocsHints, OpenApiFactory, OpenApiOverlayOptions, OpenApiPermDock, OpenApiPermDockOptions, OpenApiSchemeOptions, OpenApiSecurityRequirement, OpenApiTarget, OperationEntry, OperationPermissions, OverlayOperation, OverlayVersion, SchemeType, SecurityFor, SecurityForOptions, SecurityProfileName };

package/dist/openapi/index.js

@@ -0,0 +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";
+export { DRAFT_PINS, GNAP_RESERVED, PROFILE_NAMES, catalogOf, createPermDock, openapiVersion, operationPermissions, operationPermissionsFromOpenApi, permissionsExtension, problemDetails, securityFor, securitySchemesOf };

package/dist/openapi-Bbg4wGVL.js

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