permdock 0.4.0 → 0.6.0

package/dist/convex/index.js

@@ -1,8 +1,9 @@
 import { t as compact } from "../compact-CAf557ZB.js";
 import { n as PermDockValidationError } from "../validation-error-ZfUHbKvf.js";
-import { n as PermDockDeniedError, t as PermDockApprovalRequiredError } from "../errors-drnfxYtm.js";
-import { n as resolveOrNull, t as buildInstance } from "../build-instance-DIIV9DbC.js";
-import { n as tenantScope, t as actorFrom } from "../adapter-context-mlWsVGGg.js";
+import { n as PermDockDeniedError, t as PermDockApprovalRequiredError } from "../errors-BKy0EfhN.js";
+import { c as withApp } from "../permdock-BrAscV28.js";
+import { n as resolveOrNull, t as buildInstance } from "../build-instance-Bu_eDqYw.js";
+import { n as tenantScope, t as actorFrom } from "../adapter-context-CRhqyzCk.js";
 //#region src/convex/create.ts
 /** Convex's runtime sends `data` to the client only for an error carrying this symbol. */
 const CONVEX_ERROR = Symbol.for("ConvexError");
@@ -19,7 +20,8 @@ function toConvexError(error) {
 	if (error instanceof PermDockDeniedError || error instanceof PermDockApprovalRequiredError || error instanceof PermDockValidationError) return new ConvexError(error.toProblemDetails());
 	return error;
 }
-function createPermDock(policy, options) {
+function createPermDock(policy, given) {
+	const options = withApp(policy, given);
 	const withPermDock = (handler) => {
 		return async (ctx, args) => {
 			const user = await resolveOrNull(() => options.subject(ctx));

package/dist/create-B30OMUOJ.d.ts

@@ -0,0 +1,107 @@
+import { Ln as DeniedDecision, Mn as ApprovalRequiredDecision, T as Policy, ar as Subject, j as PolicyVocabulary, rr as Principal, zn as GrantedDecision } from "./policy-types-n0uRTsW8.js";
+import { t as Operation } from "./operations-X0VM7F3m.js";
+import { i as PermDockOptions, p as PrincipalSource, r as PermDock } from "./permdock-SV8ZINYT.js";
+import { m as ApprovalStore, p as ApprovalStatus } from "./types-BdtSDbBO.js";
+import { n as ApprovalErrorCode } from "./errors-BWXBMaKK.js";
+import { t as ApprovalPrompt } from "./approval-prompt-DvSSPQJX.js";
+//#region src/chat/subject.d.ts
+/**
+ * The platform user behind a chat message or action. Fill it only from an
+ * event whose platform signature the transport verified; a body field or a
+ * model argument is never an author.
+ */
+type ChatAuthor = {
+  /** The chat platform (`slack`, `teams`, `discord`, …). */
+  readonly provider: string;
+  /** The platform's user id, never a display name. */
+  readonly userId: string;
+  /** The workspace, team or tenant id on the platform. */
+  readonly workspace?: string;
+};
+/** The principal a chat author's identity link names, as the `PrincipalSource` returns it. */
+type ChatPrincipal = Principal;
+type SubjectFromChatOptions = {
+  /** Resolves the author through `principalByIdentity({ kind: 'chat', … })`. */
+  readonly principals: PrincipalSource;
+};
+declare function isChatAuthor(value: unknown): value is ChatAuthor;
+/**
+ * The subject a chat author acts as: the principal its identity link
+ * names, or anonymous when there is no link. Never throws.
+ */
+declare function subjectFromChat(author: ChatAuthor | null | undefined, options: SubjectFromChatOptions): Promise<Subject>;
+//#endregion
+//#region src/chat/create.d.ts
+type ChatPermDockOptions = PermDockOptions & {
+  /** Resolves chat authors through `principalByIdentity`; also the instance's principal source. */
+  readonly principals: PrincipalSource;
+  /** Where approval requests open and resolve. Without it an approval-required command only reports the decision. */
+  readonly store?: ApprovalStore;
+};
+/** What a protected command's handler receives once the author is granted. */
+type ChatCommandContext<TInput, V extends PolicyVocabulary> = {
+  readonly author: ChatAuthor;
+  readonly input: TInput;
+  /** The row the operation's `data` loaded, `undefined` without `data`. */
+  readonly row: unknown;
+  readonly permdock: PermDock<V>;
+  readonly decision: GrantedDecision;
+};
+type ChatCommandResult<T> = {
+  readonly outcome: "granted";
+  readonly value: T;
+} | {
+  readonly outcome: "denied";
+  readonly decision: DeniedDecision;
+} | {
+  readonly outcome: "approval-required";
+  readonly decision: ApprovalRequiredDecision;
+  /** The open request to deliver to approvers; `null` without an approval store. */
+  readonly prompt: ApprovalPrompt | null;
+};
+/** A command guarded by `protect`. Never throws for a refusal; the handler's own errors propagate. */
+type ChatCommand<TInput, T> = (author: ChatAuthor | null | undefined, input: TInput) => Promise<ChatCommandResult<T>>;
+/** A verdict from a chat button or reaction, by approval request `id`; the token never leaves the server. */
+type ChatAction = {
+  readonly approval: string;
+  readonly status: "approved" | "rejected";
+  readonly note?: string;
+};
+type ChatActionResult = {
+  readonly ok: true;
+  readonly id: string;
+  readonly status: ApprovalStatus;
+} | {
+  readonly ok: false;
+  readonly cause: ApprovalErrorCode | "invalid-action";
+};
+/**
+ * The runtime-neutral chat contract: commands decided as the linked
+ * principal of a verified chat author, and approval verdicts from chat
+ * actions. `permdock/chat-sdk` implements it for Chat SDK bots.
+ */
+type ChatPermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
+  /** The instance for `author`; anonymous, and so denying, when the author is unlinked. */
+  readonly getPermDock: (author: ChatAuthor | null | undefined) => Promise<PermDock<V>>;
+  /**
+   * Guards `handler` with `operation`: loads the row through the
+   * operation's `data`, decides as the author, and on `approval-required`
+   * opens one request per author, permission and row. The handler runs only
+   * when granted; an approved request runs it once.
+   */
+  readonly protect: <TInput, T>(operation: Operation<TInput>, handler: (context: ChatCommandContext<TInput, V>) => T | Promise<T>) => ChatCommand<TInput, T>;
+  /**
+   * Resolves approval request `action.approval` as `author`. The author must
+   * be linked and an eligible, distinct approver; the request's requester
+   * never approves their own request.
+   */
+  readonly resolveAction: (author: ChatAuthor | null | undefined, action: ChatAction) => Promise<ChatActionResult>;
+};
+/**
+ * Creates the chat PermDock. Every command and action is decided as the
+ * principal the author's chat identity links to, loaded live; an unlinked
+ * author is anonymous and denied.
+ */
+declare function createPermDock<TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, given: ChatPermDockOptions): ChatPermDock<V>;
+//#endregion
+export { ChatCommandResult as a, createPermDock as c, SubjectFromChatOptions as d, isChatAuthor as f, ChatCommandContext as i, ChatAuthor as l, ChatActionResult as n, ChatPermDock as o, subjectFromChat as p, ChatCommand as r, ChatPermDockOptions as s, ChatAction as t, ChatPrincipal as u };

package/dist/create-CBMmFie-.d.ts

@@ -0,0 +1,138 @@
+import { $n as Delegation, Nn as Decision, T as Policy, ar as Subject, j as PolicyVocabulary, rr as Principal } from "./policy-types-n0uRTsW8.js";
+import { w as Permission } from "./vocabulary-CN8H_9UF.js";
+import { t as Operation } from "./operations-X0VM7F3m.js";
+import { r as PermDock } from "./permdock-SV8ZINYT.js";
+import { m as ApprovalStore } from "./types-BdtSDbBO.js";
+import { t as InstanceOptions } from "./instance-options-BsVpyGIk.js";
+import { t as RequestContext } from "./request-context-C2_1lchh.js";
+import { n as PermDockWrap } from "./wrap-C5jC6sKI.js";
+import { o as OtelWrap } from "./types-lUlG3TVd.js";
+import { t as DeniedText } from "./denied-text-CiFQNuMV.js";
+//#region src/agent/types.d.ts
+/** The part of an operation a tool decision reads; an `OperationMap` entry is one. */
+type ToolBinding = Pick<Operation, "permission" | "data" | "results"> & Partial<Pick<Operation, "name" | "meta">>;
+type ToolMap = Readonly<Record<string, ToolBinding>>;
+/**
+ * The models an agent may call, by model id (`'openai/gpt-5'`), each bound to
+ * the permission that grants it. An instance permission is decided on the
+ * row `{ id }`.
+ */
+type ModelMap = Readonly<Record<string, Permission>>;
+/** The options `permdock/ai-sdk`, `permdock/openai`, `permdock/claude-agent` and `permdock/eve` share. */
+type AgentAdapterOptions<TContext, TUser = unknown> = InstanceOptions & {
+  /** The user, or a full `Subject` (core then skips `policy.subject`). */
+  readonly subject: (context: TContext) => TUser | Subject | Promise<TUser | Subject>;
+  readonly actor?: (context: TContext) => unknown;
+  readonly delegation?: (context: TContext) => Delegation | undefined | Promise<Delegation | undefined>;
+  readonly tenant?: string | ((context: TContext) => string | undefined | Promise<string | undefined>);
+  /** The tools the agent may call, by tool name: the map `defineOperations` returns. */
+  readonly operations: ToolMap;
+  /**
+   * The model gate. Absent: the adapter never checks a model. Present: a
+   * model id it does not name is denied.
+   */
+  readonly models?: ModelMap;
+  readonly store?: ApprovalStore;
+  /**
+   * Tools `operations` does not name. `'deny'` (default) denies them.
+   * `'allow'` leaves them to the runtime's own approval.
+   */
+  readonly unmapped?: "deny" | "allow";
+  /**
+   * Request values merged into `subject.context`, under `policy.context`.
+   * Only values the server derived belong here, never model output.
+   */
+  readonly context?: (context: TContext) => RequestContext | undefined | Promise<RequestContext | undefined>;
+  /** `(permdock) => withOtel(permdock, options)` from `permdock/otel`. */
+  readonly otel?: OtelWrap;
+  /** Wraps each instance after `otel`; build it with `wrapPermDock` to cover derived instances. */
+  readonly wrap?: PermDockWrap;
+  /** Replaces the denial reason or approval summary text; nothing else. */
+  readonly deniedText?: DeniedText;
+};
+type ToolVerdict = {
+  readonly outcome: "granted";
+  readonly decision: Extract<Decision, {
+    readonly outcome: "granted";
+  }>;
+  readonly permission: Permission;
+  readonly data: unknown;
+} | {
+  readonly outcome: "denied";
+  readonly decision: Extract<Decision, {
+    readonly outcome: "denied";
+  }> | null;
+  readonly permission: Permission | undefined;
+  readonly reason: string;
+} | {
+  readonly outcome: "approval-required";
+  readonly decision: Extract<Decision, {
+    readonly outcome: "approval-required";
+  }>;
+  readonly permission: Permission;
+  readonly data: unknown;
+  readonly token: string;
+  readonly summary: string;
+};
+type DecideToolOptions = {
+  readonly resumeToken?: string;
+  /**
+   * Treat an existing pending record as a re-check of a call that already
+   * asked: deny with `approval-pending` instead of asking again. For runtimes
+   * that re-run the approval hook after a human answers and run the tool on
+   * anything but a denial.
+   */
+  readonly denyPending?: boolean;
+};
+//#endregion
+//#region src/agent/create.d.ts
+type AgentPermDockOptions<TContext, TUser = unknown> = AgentAdapterOptions<TContext, TUser>;
+/** What one operation call decides: granted with the loaded row, denied with the text a model reads, or parked for approval. */
+type OperationVerdict = ToolVerdict;
+/** `providerOptions` for the Vercel AI Gateway: spend and usage attributed to the caller. */
+type GatewayOptions = {
+  readonly gateway: {
+    readonly user?: string;
+    readonly tags?: readonly string[];
+  };
+};
+/**
+ * The runtime-neutral agent contract: operations decided by name, the model
+ * gate and the results filter. `permdock/ai-sdk`, `permdock/openai`,
+ * `permdock/claude-agent` and `permdock/eve` each return one, plus the hooks
+ * their runtime calls.
+ */
+type AgentPermDock<TContext, V extends PolicyVocabulary = PolicyVocabulary> = {
+  /** One instance per context object while a call is in flight; later calls re-read the subject. */
+  readonly getPermDock: (context: TContext) => Promise<PermDock<V>>;
+  /**
+   * Decides operation `name` on `input`: loads the row through the
+   * operation's `data`, validates it, decides and resumes an approval. Never
+   * throws; an operation `operations` does not name is denied.
+   */
+  readonly decideOperation: (name: string, input: unknown, context: TContext, options?: DecideToolOptions) => Promise<OperationVerdict>;
+  /** Operation names the subject could be granted for some row; a listing hint, never a decision. */
+  readonly allowedOperations: (context: TContext) => Promise<ReadonlySet<string>>;
+  /** The approval token a call would park under, without touching the store. */
+  readonly tokenFor: (name: string, input: unknown, context: TContext) => Promise<string | undefined>;
+  /** Decides whether the subject may call model `modelId`. A model `models` does not name is denied. */
+  readonly decideModel: (modelId: string, context: TContext) => Promise<Decision>;
+  /** The ids in `models` the subject is granted, in declaration order. */
+  readonly permittedModels: (context: TContext) => Promise<readonly string[]>;
+  /**
+   * The rows of an operation's output the subject may see, by the
+   * operation's `results` permission. Without `results` the rows come back
+   * unchanged; an operation `operations` does not name returns none.
+   */
+  readonly filterResults: <T>(name: string, rows: readonly T[], context: TContext) => Promise<T[]>;
+  /** `providerOptions.gateway` with the principal as `user` and the tenant and actor as tags. */
+  readonly gatewayOptions: (context: TContext) => Promise<GatewayOptions>;
+};
+/**
+ * The agent contract for a runtime PermDock has no adapter for: decide
+ * operations by name, gate models and filter results. The subject comes from
+ * `subject(context)` on the server, never from model output.
+ */
+declare function createPermDock<TContext, TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, given: AgentPermDockOptions<TContext, TUser>): AgentPermDock<TContext, V>;
+//#endregion
+export { createPermDock as a, ModelMap as c, OperationVerdict as i, ToolBinding as l, AgentPermDockOptions as n, AgentAdapterOptions as o, GatewayOptions as r, DecideToolOptions as s, AgentPermDock as t, ToolMap as u };

package/dist/create-CGm28gyI.js

@@ -0,0 +1,130 @@
+import { t as compact } from "./compact-CAf557ZB.js";
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+import { a as deniedFor } from "./where-scope-C9vfEphl.js";
+import { c as withApp } from "./permdock-BrAscV28.js";
+import { t as composeWraps } from "./wrap-gX61EtpB.js";
+import { r as instanceOptions } from "./build-instance-Bu_eDqYw.js";
+import { n as createAgentKernel } from "./kernel-D0NVb1cK.js";
+//#region src/agent/create.ts
+function modelRow(modelId) {
+	return { id: modelId };
+}
+function unlistedModel(modelId) {
+	return freezeDeep({
+		outcome: "denied",
+		denials: [{
+			role: null,
+			reason: "no-grant",
+			detail: { model: modelId }
+		}],
+		alternatives: []
+	});
+}
+function decideModelOn(permdock, models, modelId, adapter) {
+	const permission = models !== void 0 && Object.hasOwn(models, modelId) ? models[modelId] : void 0;
+	if (permission === void 0) return unlistedModel(modelId);
+	try {
+		return permdock.decide(permission, permission.kind === "instance" ? modelRow(modelId) : void 0, {
+			trusted: true,
+			adapter,
+			call: "adapter",
+			model: modelId
+		});
+	} catch {
+		return deniedFor(permission, "closure-error");
+	}
+}
+/** Builds the agent contract and its kernel for an adapter named `adapter`. */
+function agentRuntime(policy, options, adapter) {
+	const kernel = createAgentKernel(policy, {
+		...compact({
+			actor: options.actor,
+			delegation: options.delegation,
+			tenant: options.tenant,
+			store: options.store,
+			context: options.context,
+			wrap: composeWraps(options.otel, options.wrap),
+			deniedText: options.deniedText
+		}),
+		...instanceOptions(options),
+		subject: options.subject,
+		tools: options.operations,
+		adapter
+	});
+	const operations = options.operations;
+	const bindingOf = (name) => Object.hasOwn(operations, name) ? operations[name] : void 0;
+	const decideModel = async (modelId, context) => {
+		try {
+			return decideModelOn(await kernel.instance(context), options.models, modelId, adapter);
+		} catch {
+			return unlistedModel(modelId);
+		}
+	};
+	const permittedModels = async (context) => {
+		if (options.models === void 0) return [];
+		let permdock;
+		try {
+			permdock = await kernel.instance(context);
+		} catch {
+			return [];
+		}
+		return Object.keys(options.models).filter((modelId) => decideModelOn(permdock, options.models, modelId, adapter).outcome === "granted");
+	};
+	const filterResults = async (name, rows, context) => {
+		const binding = bindingOf(name);
+		if (binding === void 0) return [];
+		if (binding.results === void 0) return [...rows];
+		try {
+			const permdock = await kernel.instance(context);
+			const results = binding.results;
+			if (results.kind !== "instance") return permdock.can(results, void 0) ? [...rows] : [];
+			await permdock.prefetchRelations(results, rows);
+			return permdock.filter(results, rows, {
+				adapter,
+				call: "filter"
+			});
+		} catch {
+			return [];
+		}
+	};
+	const gatewayOptions = async (context) => {
+		let permdock;
+		try {
+			permdock = await kernel.instance(context);
+		} catch {
+			return { gateway: {} };
+		}
+		const { principal, actor } = permdock.subject;
+		const tags = [...principal?.tenant === void 0 ? [] : [`tenant:${principal.tenant}`], ...actor === void 0 ? [] : [`actor:${actor.kind}`]];
+		return { gateway: compact({
+			user: principal?.id,
+			tags: tags.length > 0 ? tags : void 0
+		}) };
+	};
+	return {
+		agent: Object.freeze({
+			getPermDock: (context) => kernel.instance(context),
+			decideOperation: (name, input, context, decideOptions) => kernel.decideTool(name, input, context, decideOptions),
+			allowedOperations: (context) => kernel.allowedToolNames(context),
+			tokenFor: (name, input, context) => {
+				const binding = bindingOf(name);
+				return binding === void 0 ? Promise.resolve(void 0) : kernel.tokenFor(binding, input, context);
+			},
+			decideModel,
+			permittedModels,
+			filterResults,
+			gatewayOptions
+		}),
+		kernel
+	};
+}
+/**
+* The agent contract for a runtime PermDock has no adapter for: decide
+* operations by name, gate models and filter results. The subject comes from
+* `subject(context)` on the server, never from model output.
+*/
+function createPermDock(policy, given) {
+	return agentRuntime(policy, withApp(policy, given), "agent").agent;
+}
+//#endregion
+export { createPermDock as n, agentRuntime as t };