permdock 0.4.0 → 0.5.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-B9JxkBwC.js";
+import { n as resolveOrNull, t as buildInstance } from "../build-instance-BMnAudHn.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-0VZ7Pdiu.d.ts

@@ -0,0 +1,107 @@
+import { Ln as DeniedDecision, Mn as ApprovalRequiredDecision, T as Policy, ir as Subject, j as PolicyVocabulary, rr as Principal, zn as GrantedDecision } from "./policy-types-DzwivBgR.js";
+import { t as Operation } from "./operations-CxybZErY.js";
+import { i as PermDockOptions, p as PrincipalSource, r as PermDock } from "./permdock-D7eeLJER.js";
+import { m as ApprovalStore, p as ApprovalStatus } from "./types-CCpc2Dcv.js";
+import { n as ApprovalErrorCode } from "./errors-BWXBMaKK.js";
+import { t as ApprovalPrompt } from "./approval-prompt-Djo_PyZc.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-BDS7wc3y.d.ts

@@ -0,0 +1,138 @@
+import { $n as Delegation, Nn as Decision, T as Policy, ir as Subject, j as PolicyVocabulary, rr as Principal } from "./policy-types-DzwivBgR.js";
+import { w as Permission } from "./vocabulary-D6lPdb4Z.js";
+import { t as Operation } from "./operations-CxybZErY.js";
+import { r as PermDock } from "./permdock-D7eeLJER.js";
+import { m as ApprovalStore } from "./types-CCpc2Dcv.js";
+import { t as InstanceOptions } from "./instance-options-Omfd793B.js";
+import { t as RequestContext } from "./request-context-C2_1lchh.js";
+import { n as PermDockWrap } from "./wrap-Bd1Tejur.js";
+import { o as OtelWrap } from "./types-BqAKcRNW.js";
+import { t as DeniedText } from "./denied-text-D8jDHgsl.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-BFfm17UA.d.ts

@@ -0,0 +1,110 @@
+import { Nn as Decision, Pn as Denial, Rt as Instant, T as Policy, dt as TokenVerifier, j as PolicyVocabulary, qt as AuthEvent, rr as Principal, ut as TokenSigner } from "./policy-types-DzwivBgR.js";
+import { w as Permission } from "./vocabulary-D6lPdb4Z.js";
+import { i as PermDockOptions, p as PrincipalSource, r as PermDock, t as DecideOptions } from "./permdock-D7eeLJER.js";
+import { m as ApprovalStore } from "./types-CCpc2Dcv.js";
+import { a as AutomationSource } from "./automation-BMZPIVUM.js";
+import { n as ApprovalWaiter } from "./waiter-CKy4MQSY.js";
+import { n as RunAutomation, r as RunBinding } from "./run-ticket-BjhTOi6u.js";
+//#region src/workflow/create.d.ts
+type WorkflowPermDockOptions = PermDockOptions & {
+  /** Signs the run tickets `start` mints. */
+  readonly signer: TokenSigner;
+  /** Verifies run tickets in `getPermDock`. */
+  readonly verifier: TokenVerifier;
+  /** Loads the principal a run acts as, live, on every `getPermDock`. */
+  readonly principals: PrincipalSource;
+  /** The live automation records, read by `start` and on every `getPermDock`. */
+  readonly automations: AutomationSource;
+  /** Where `awaitApproval` opens and resumes requests; the same option name as every other adapter. */
+  readonly store?: ApprovalStore;
+  /** Suspends `awaitApproval` until a request is decided. */
+  readonly waiter?: ApprovalWaiter;
+  readonly audience?: string | readonly string[];
+  readonly issuer?: string;
+  /** Run ticket lifetime in seconds. Defaults to 86400; a run past it denies. */
+  readonly expiresIn?: number;
+  readonly onAuth?: (event: AuthEvent) => void;
+};
+type AutomationOptions = {
+  /** The tenant the automation is read for. */
+  readonly tenant?: string;
+  /**
+   * The caller starting the run. It needs only the automation's `run`
+   * permission and lends the run nothing. Absent: server code starts the run,
+   * which an automation without `run` requires.
+   */
+  readonly caller?: PermDock;
+  /** The row `run` is decided on, when it is an instance permission. */
+  readonly row?: unknown;
+  /** The event that started the run, as JSON. Kept in `subject.context.trigger`; never a grant. */
+  readonly trigger?: Readonly<Record<string, unknown>>;
+  /** The run id (`jti`); a fresh UUID when absent. */
+  readonly id?: string;
+  readonly binding?: RunBinding;
+  readonly now?: Instant;
+};
+type StartAutomationResult = {
+  readonly outcome: "started";
+  readonly ticket: string;
+  readonly run: {
+    readonly id: string;
+    readonly automation: RunAutomation;
+  };
+} | {
+  readonly outcome: "denied";
+  readonly denials: readonly Denial[];
+};
+type AwaitApprovalOptions = DecideOptions & {
+  /** The resource the approval request names; defaults to the permission's resource and the row's `id`. */
+  readonly resource?: {
+    readonly type: string;
+    readonly id?: string;
+  };
+  /** Seconds the request stays open; the store's `ttl` when absent. */
+  readonly ttl?: number;
+  readonly signal?: AbortSignal;
+};
+type WorkflowPermDock<V extends PolicyVocabulary = PolicyVocabulary> = {
+  /**
+   * Starts a run of the automation `id` and returns its run ticket. Denied
+   * when the automation is unknown or revoked (`validation`) or when the
+   * caller is not granted its `run` permission.
+   */
+  readonly start: (id: string, options?: AutomationOptions) => Promise<StartAutomationResult>;
+  /**
+   * The PermDock of a run, rebuilt from its ticket: the principal loaded
+   * live, narrowed to the automation's permissions and to any policy
+   * delegation to `actor('automation')`. A changed, revoked or unknown
+   * automation, or a publisher who is gone, gives an anonymous instance
+   * that denies everything.
+   */
+  readonly getPermDock: (ticket: string) => Promise<PermDock<V>>;
+  /**
+   * Decides `permission`; on `approval-required` opens a request, waits on
+   * the `waiter`, then rebuilds the run from its ticket and decides again
+   * with the token. The second decision reads the publisher's rights as of
+   * then, so a demotion while waiting denies.
+   */
+  readonly awaitApproval: (ticket: string, permission: Permission, data?: unknown, options?: AwaitApprovalOptions) => Promise<Decision>;
+  /**
+   * The first half of `awaitApproval`, for runners that wait outside the
+   * call: decides, and on `approval-required` opens the request and returns
+   * the decision with its token.
+   */
+  readonly openApproval: (ticket: string, permission: Permission, data?: unknown, options?: AwaitApprovalOptions) => Promise<Decision>;
+  /**
+   * The second half: rebuilds the run from its ticket and decides again with
+   * the approval `token`. A request still pending denies with reason
+   * `approval`.
+   */
+  readonly resumeApproval: (ticket: string, permission: Permission, token: string, data?: unknown, options?: AwaitApprovalOptions) => Promise<Decision>;
+};
+/**
+ * Creates the PermDock for durable runs of published automations. A run
+ * acts as the automation's principal with that principal's rights at each
+ * step, narrowed to the automation's operations; the trigger is recorded
+ * and never grants.
+ */
+declare function createPermDock<TUser, TPrincipal extends Principal = Principal, V extends PolicyVocabulary = PolicyVocabulary>(policy: Policy<TUser, TPrincipal, V>, given: WorkflowPermDockOptions): WorkflowPermDock<V>;
+//#endregion
+export { WorkflowPermDockOptions as a, WorkflowPermDock as i, AwaitApprovalOptions as n, createPermDock as o, StartAutomationResult as r, AutomationOptions as t };