permdock 0.0.0 → 0.1.0

package/dist/a2a/index.js

@@ -0,0 +1,271 @@
+import { t as compact } from "../compact-y6vfu2_f.js";
+import { n as PermDockDeniedError, t as PermDockApprovalRequiredError } from "../errors-Iy71s7Oj.js";
+import { l as canonicalJson } from "../snapshot-DE8dE_hz.js";
+import { t as bytesToBase64Url } from "../sha256-BO0swRXL.js";
+import { t as createPermDock$1 } from "../permdock-yoZ7EjxX.js";
+import { t as mayUse } from "../may-use-CnFEjVEp.js";
+import { l as storedApprovalToken, s as resumeDecision } from "../helpers-DnSOrhB9.js";
+import { r as bearerChallenge } from "../problem-Cgp9-KZA.js";
+//#region src/a2a/create.ts
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function firstScheme(options) {
+	return Object.keys(options.securitySchemes)[0];
+}
+function skillOf(id, config, scheme) {
+	return {
+		id,
+		name: id,
+		description: config.description ?? config.permission.key,
+		tags: config.tags ?? [config.permission.resource],
+		securityRequirements: scheme === void 0 ? [] : [{ schemes: { [scheme]: { list: [config.permission.scope] } } }]
+	};
+}
+function publicSkills(options) {
+	const scheme = firstScheme(options);
+	return Object.entries(options.skills).map(([id, config]) => skillOf(id, config, scheme));
+}
+function wireScheme(scheme) {
+	switch (scheme.type) {
+		case "oauth2": return { oauth2SecurityScheme: compact({
+			oauth2MetadataUrl: scheme.oauth2MetadataUrl,
+			description: scheme.description
+		}) };
+		case "http": return { httpAuthSecurityScheme: compact({
+			scheme: scheme.scheme,
+			bearerFormat: scheme.bearerFormat,
+			description: scheme.description
+		}) };
+		case "openIdConnect": return { openIdConnectSecurityScheme: compact({
+			openIdConnectUrl: scheme.openIdConnectUrl,
+			description: scheme.description
+		}) };
+		case "mutualTLS": return { mtlsSecurityScheme: compact({ description: scheme.description }) };
+		case "apiKey": return { apiKeySecurityScheme: compact({
+			location: scheme.in,
+			name: scheme.name,
+			description: scheme.description
+		}) };
+		default: return scheme;
+	}
+}
+function cardOf(options, skills) {
+	const info = options.card;
+	return compact({
+		name: info.name,
+		description: info.description ?? info.name,
+		version: info.version,
+		supportedInterfaces: [{
+			url: info.url,
+			protocolBinding: info.protocolBinding ?? "JSONRPC",
+			protocolVersion: "1.0"
+		}],
+		provider: info.provider,
+		documentationUrl: info.documentationUrl,
+		iconUrl: info.iconUrl,
+		capabilities: compact({
+			extendedAgentCard: true,
+			streaming: info.streaming,
+			pushNotifications: info.pushNotifications
+		}),
+		defaultInputModes: info.defaultInputModes ?? DEFAULT_MODES,
+		defaultOutputModes: info.defaultOutputModes ?? DEFAULT_MODES,
+		securitySchemes: Object.fromEntries(Object.entries(options.securitySchemes).map(([name, scheme]) => [name, wireScheme(scheme)])),
+		skills
+	});
+}
+const DEFAULT_MODES = ["text/plain"];
+function delegationOf(auth) {
+	return compact({
+		scopes: auth.scopes,
+		authorizationDetails: auth.extra?.authorizationDetails
+	});
+}
+function actorOf(auth) {
+	return typeof auth.clientId === "string" && auth.clientId !== "" ? {
+		id: auth.clientId,
+		kind: "oauth-client"
+	} : void 0;
+}
+async function resolveTenant(tenant, auth) {
+	if (tenant === void 0 || typeof tenant === "string") return tenant;
+	try {
+		return await tenant(auth);
+	} catch {
+		return;
+	}
+}
+function hasScope(auth, scope) {
+	return auth.scopes?.includes(scope) === true;
+}
+function resourceRef(permission, data) {
+	if (!isRecord(data)) return { type: permission.resource };
+	const id = data["id"];
+	return typeof id === "string" || typeof id === "number" ? {
+		type: permission.resource,
+		id: String(id)
+	} : { type: permission.resource };
+}
+const LOAD_FAILED = {
+	outcome: "denied",
+	denials: [{
+		role: null,
+		reason: "validation"
+	}],
+	alternatives: []
+};
+function deniedOutcome(decision, permission, data, permdock) {
+	return {
+		ok: false,
+		status: 403,
+		state: "failed",
+		problem: new PermDockDeniedError({
+			decision,
+			permission: permission.key,
+			scope: permission.scope,
+			resource: resourceRef(permission, data),
+			subject: permdock.subject,
+			message: `${permission.key} denied.`
+		}).toProblemDetails()
+	};
+}
+function approvalOutcome(decision, permission, data) {
+	return {
+		ok: false,
+		status: 403,
+		state: "input-required",
+		problem: new PermDockApprovalRequiredError({
+			decision,
+			permission: permission.key,
+			scope: permission.scope,
+			resource: resourceRef(permission, data),
+			message: `${permission.key} requires human approval.`
+		}).toProblemDetails()
+	};
+}
+/** A2A 1.0 section 8.4: a detached JWS over the RFC 8785 form of the card. */
+async function signCard(card, signPayload) {
+	const { signatures = [], ...unsigned } = card;
+	const payload = canonicalJson(unsigned);
+	const [header, body, signature, extra] = (await signPayload(payload)).split(".");
+	if (header === void 0 || signature === void 0 || extra !== void 0 || body !== bytesToBase64Url(new TextEncoder().encode(payload))) throw new TypeError("PermDock: an A2A card signer must return a compact JWS over the payload it was given");
+	return {
+		...card,
+		signatures: [...signatures, {
+			protected: header,
+			signature
+		}]
+	};
+}
+function missingScope(permission) {
+	return {
+		ok: false,
+		status: 401,
+		state: "failed",
+		problem: {
+			type: "https://permdock.dev/problems/unauthenticated",
+			title: "Insufficient scope",
+			status: 401,
+			detail: `insufficient_scope: ${permission.scope}`,
+			permission: permission.key,
+			scope: permission.scope
+		},
+		wwwAuthenticate: bearerChallenge({
+			error: "insufficient_scope",
+			scopes: [permission.scope]
+		})
+	};
+}
+function createPermDock(policy, options) {
+	for (const [id, config] of Object.entries(options.skills)) if (config.permission.kind === "instance" && config.data === void 0) throw new TypeError(`PermDock: A2A skill '${id}' checks ${config.permission.key} on a row and needs a data loader; the task body is never used as the row`);
+	const instanceFor = async (auth) => {
+		let user = null;
+		try {
+			user = await options.subject(auth);
+		} catch {
+			user = null;
+		}
+		const tenant = await resolveTenant(options.tenant, auth);
+		return createPermDock$1(policy, user, compact({
+			tenant,
+			actor: actorOf(auth),
+			delegation: delegationOf(auth),
+			memberships: options.memberships,
+			relations: options.relations,
+			entitlements: options.entitlements,
+			customRoles: options.customRoles,
+			policies: options.policies,
+			sink: options.sink,
+			limits: options.limits
+		}));
+	};
+	const agentCard = () => cardOf(options, publicSkills(options));
+	const extendedAgentCard = async (auth) => {
+		const permdock = await instanceFor(auth);
+		const scheme = firstScheme(options);
+		const skills = [];
+		for (const [id, config] of Object.entries(options.skills)) if (mayUse(permdock, config.permission)) skills.push(skillOf(id, config, scheme));
+		return cardOf(options, skills);
+	};
+	const protectSkill = (selector) => async (task, auth) => {
+		const id = selector(task);
+		const config = Object.hasOwn(options.skills, id) ? options.skills[id] : void 0;
+		if (config === void 0) return {
+			ok: false,
+			status: 403,
+			state: "failed",
+			problem: {
+				type: "https://permdock.dev/problems/denied",
+				title: "Permission denied",
+				status: 403,
+				detail: "unknown skill"
+			}
+		};
+		if (!hasScope(auth, config.permission.scope)) return missingScope(config.permission);
+		const permdock = await instanceFor(auth);
+		let data;
+		if (config.data !== void 0) {
+			try {
+				data = await config.data(task);
+			} catch {
+				return deniedOutcome(LOAD_FAILED, config.permission, void 0, permdock);
+			}
+			if (config.permission.kind === "instance" && (data === null || data === void 0)) return deniedOutcome(LOAD_FAILED, config.permission, void 0, permdock);
+		}
+		let decision;
+		try {
+			const raw = permdock.decide(config.permission, data, compact({
+				source: "adapter",
+				adapter: "a2a",
+				trusted: false,
+				boundary: "tool-args"
+			}));
+			decision = await resumeDecision({
+				decision: raw,
+				permission: config.permission,
+				subject: permdock.subject,
+				store: options.store,
+				resource: resourceRef(config.permission, data),
+				adapter: "a2a",
+				token: auth.extra?.approval ?? await storedApprovalToken(options.store, raw, false)
+			});
+		} catch {
+			return deniedOutcome(LOAD_FAILED, config.permission, data, permdock);
+		}
+		switch (decision.outcome) {
+			case "granted": return { ok: true };
+			case "denied": return deniedOutcome(decision, config.permission, data, permdock);
+			case "approval-required": return approvalOutcome(decision, config.permission, data);
+			default: return decision;
+		}
+	};
+	return {
+		agentCard,
+		extendedAgentCard,
+		protectSkill,
+		sign: signCard
+	};
+}
+//#endregion
+export { createPermDock };

package/dist/ai-sdk/index.d.ts

@@ -0,0 +1,74 @@
+import { $ as DecisionSink, C as Policy, at as LimitStore, ct as MembershipSource, ft as RelationSource, mr as Principal, pt as RoleSource, sn as PolicySource, tt as EntitlementSource, ur as Delegation, xt as SnapshotSource } from "../policy-CInmNGkM.js";
+import { d as Permission } from "../permissions-B4apnahQ.js";
+import { f as ApprovalStore } from "../types-B8w5PFtS.js";
+import { t as ToolMap } from "../types-CxquUByI.js";
+//#region src/ai-sdk/create.d.ts
+type AiSdkContext = {
+  readonly runtimeContext?: unknown;
+  readonly permdockApproval?: string;
+  readonly [key: string]: unknown;
+};
+type AiSdkPermDockOptions<TUser = unknown> = {
+  readonly subject: (context: AiSdkContext) => TUser | Promise<TUser>;
+  readonly actor?: (context: AiSdkContext) => unknown;
+  readonly delegation?: (context: AiSdkContext) => Delegation | undefined | Promise<Delegation | undefined>;
+  readonly tenant?: string | ((context: AiSdkContext) => string | undefined | Promise<string | undefined>);
+  readonly tools: ToolMap;
+  readonly memberships?: MembershipSource | readonly MembershipSource[];
+  /** The object graph for relation grants that walk a parent chain; without it they deny. */
+  readonly relations?: RelationSource;
+  readonly entitlements?: EntitlementSource;
+  readonly customRoles?: RoleSource;
+  /** Hosted grants, read once per instance; see `PolicySource`. */
+  readonly policies?: PolicySource;
+  readonly store?: ApprovalStore;
+  readonly sink?: DecisionSink;
+  readonly limits?: LimitStore;
+  readonly snapshots?: SnapshotSource;
+};
+type ToolApprovalStatus = "approved" | {
+  readonly type: "denied";
+  readonly reason: string;
+} | {
+  readonly type: "user-approval";
+  readonly reason: string;
+  readonly token: string;
+};
+/** Structural `GenericToolApprovalFunction` options from `ai`. */
+type ToolApprovalCall = {
+  readonly toolCall: {
+    readonly toolName: string;
+    readonly toolCallId?: string;
+    readonly input?: unknown;
+  };
+  readonly messages?: readonly unknown[];
+  readonly runtimeContext?: unknown;
+};
+/** Structural `ToolNeedsApprovalFunction` options from `ai`. */
+type NeedsApprovalOptions = {
+  readonly toolCallId?: string;
+  readonly messages?: readonly unknown[];
+  readonly context?: unknown;
+};
+type CallParams = {
+  readonly tools?: readonly {
+    readonly name?: string;
+  }[];
+  readonly toolChoice?: unknown;
+};
+/** Structural `LanguageModelMiddleware` (specification `v4`) from `ai`. */
+type LanguageModelMiddleware = {
+  readonly specificationVersion: "v4";
+  readonly transformParams: <TParams extends CallParams>(options: {
+    readonly params: TParams;
+  }) => Promise<TParams>;
+};
+type AiSdkPermDock = {
+  readonly toolApproval: (call: ToolApprovalCall) => Promise<ToolApprovalStatus>;
+  /** Hides tools the subject in `context` can never use, before the model sees them. */
+  readonly capabilityMiddleware: (context: AiSdkContext) => LanguageModelMiddleware;
+  readonly needsApproval: (permission: Permission) => (input: unknown, options?: NeedsApprovalOptions) => Promise<boolean>;
+};
+export declare function createPermDock<TUser, TPrincipal extends Principal = Principal>(policy: Policy<TUser, TPrincipal>, options: AiSdkPermDockOptions<TUser>): AiSdkPermDock;
+//#endregion
+export type { AiSdkContext, AiSdkPermDock, AiSdkPermDockOptions, LanguageModelMiddleware, NeedsApprovalOptions, ToolApprovalCall, ToolApprovalStatus };

package/dist/ai-sdk/index.js

@@ -0,0 +1,137 @@
+import { t as compact } from "../compact-y6vfu2_f.js";
+import { n as PermDockDeniedError, t as PermDockApprovalRequiredError } from "../errors-Iy71s7Oj.js";
+import { n as createAgentKernel, t as approvalTokenOf } from "../kernel-YOGCWNLf.js";
+//#region src/ai-sdk/create.ts
+function contextOf(call) {
+	const runtime = call.runtimeContext !== null && typeof call.runtimeContext === "object" ? call.runtimeContext : {};
+	return compact({
+		...runtime,
+		runtimeContext: call.runtimeContext
+	});
+}
+function toolContextOf(options) {
+	const tool = options.context !== null && typeof options.context === "object" ? options.context : {};
+	return compact({
+		...tool,
+		toolContext: options.context
+	});
+}
+/**
+* Whether `messages` already carry an approval request for `toolCallId`: the
+* SDK is re-checking a call a user approved, and treats any answer other
+* than `denied` as approval.
+*/
+function isRecheck(messages, toolCallId) {
+	if (!Array.isArray(messages) || typeof toolCallId !== "string") return false;
+	return messages.some((message) => {
+		if (typeof message !== "object" || message === null) return false;
+		const { role, content } = message;
+		return role === "assistant" && Array.isArray(content) && content.some((part) => typeof part === "object" && part !== null && part.type === "tool-approval-request" && part.toolCallId === toolCallId);
+	});
+}
+function resourceOf(permission, data) {
+	const id = typeof data === "object" && data !== null ? data.id : void 0;
+	return typeof id === "string" || typeof id === "number" ? {
+		type: permission.resource,
+		id: String(id)
+	} : { type: permission.resource };
+}
+function deniedError(verdict, permission, permdock) {
+	return new PermDockDeniedError({
+		decision: verdict.decision ?? {
+			outcome: "denied",
+			denials: [],
+			alternatives: []
+		},
+		permission: permission.key,
+		scope: permission.scope,
+		resource: { type: permission.resource },
+		subject: permdock.subject,
+		message: verdict.reason
+	});
+}
+function createPermDock(policy, options) {
+	const kernel = createAgentKernel(policy, {
+		...compact({
+			actor: options.actor,
+			delegation: options.delegation,
+			tenant: options.tenant,
+			memberships: options.memberships,
+			relations: options.relations,
+			entitlements: options.entitlements,
+			customRoles: options.customRoles,
+			policies: options.policies,
+			store: options.store,
+			sink: options.sink,
+			limits: options.limits,
+			snapshots: options.snapshots
+		}),
+		subject: options.subject,
+		tools: options.tools,
+		adapter: "ai-sdk"
+	});
+	const byPermission = /* @__PURE__ */ new Map();
+	for (const [name, binding] of Object.entries(options.tools)) byPermission.set(binding.permission.key, name);
+	const decide = (toolName, args, context) => kernel.decideTool(toolName, args, context, compact({ resumeToken: approvalTokenOf(context) }));
+	const toolApproval = async (call) => {
+		const context = contextOf(call);
+		const verdict = await decide(call.toolCall.toolName, call.toolCall.input, context);
+		if (verdict.outcome === "granted") return "approved";
+		if (verdict.outcome === "denied") return {
+			type: "denied",
+			reason: verdict.reason
+		};
+		if (isRecheck(call.messages, call.toolCall.toolCallId)) return {
+			type: "denied",
+			reason: `${verdict.summary} No approval is recorded for this call.`
+		};
+		return {
+			type: "user-approval",
+			reason: verdict.summary,
+			token: verdict.token
+		};
+	};
+	const capabilityMiddleware = (context) => ({
+		specificationVersion: "v4",
+		transformParams: async ({ params }) => {
+			if (params.tools === void 0) return params;
+			const allowed = await kernel.allowedToolNames(context);
+			const tools = params.tools.filter((tool) => typeof tool.name === "string" && allowed.has(tool.name));
+			const choice = params.toolChoice;
+			const forcedAway = choice?.type === "tool" && !(typeof choice.toolName === "string" && allowed.has(choice.toolName));
+			return {
+				...params,
+				tools,
+				...forcedAway ? { toolChoice: { type: "none" } } : {}
+			};
+		}
+	});
+	const needsApproval = (permission) => async (input, needsOptions = {}) => {
+		const context = toolContextOf(needsOptions);
+		const toolName = byPermission.get(permission.key);
+		if (toolName === void 0) throw deniedError({
+			outcome: "denied",
+			decision: null,
+			permission,
+			reason: `${permission.key} is not bound to a tool.`
+		}, permission, await kernel.instance(context));
+		const verdict = await decide(toolName, input, context);
+		if (verdict.outcome === "granted") return false;
+		if (verdict.outcome === "denied") throw deniedError(verdict, permission, await kernel.instance(context));
+		if (isRecheck(needsOptions.messages, needsOptions.toolCallId)) throw new PermDockApprovalRequiredError({
+			decision: verdict.decision,
+			permission: permission.key,
+			scope: permission.scope,
+			resource: resourceOf(permission, verdict.data),
+			message: `${verdict.summary} No approval is recorded for this call.`
+		});
+		return true;
+	};
+	return {
+		toolApproval,
+		capabilityMiddleware,
+		needsApproval
+	};
+}
+//#endregion
+export { createPermDock };

package/dist/approval-required-TzNB9oQA.js

@@ -0,0 +1,6 @@
+//#region src/core/approval-required.ts
+function requiresApproval(approval) {
+	return approval !== void 0;
+}
+//#endregion
+export { requiresApproval as t };

package/dist/approvals/index.d.ts

@@ -0,0 +1,3 @@
+import { _ as approverRelationKey, a as ApprovalListFilter, c as ApprovalRequest, d as ApprovalStatus, f as ApprovalStore, g as approvalQuorum, h as DEFAULT_APPROVAL_TTL_MS, i as ApprovalInspectResult, l as ApprovalResumeFailure, m as ApprovalVerdict, n as ApprovalApprovers, o as ApprovalListQuery, p as ApprovalSubjectSummary, r as ApprovalCancelMeta, s as ApprovalPage, t as APPROVAL_HEADER, u as ApprovalSignature, v as escalationOpenAt } from "../types-B8w5PFtS.js";
+import { _ as approvalsHandler, a as cancelApprovals, b as isApprovalError, c as readApprovalHeader, d as resumeDecision, f as resumeFromHeader, g as ApprovalsHandlerOptions, h as approverRelations, i as memoryApprovalStore, l as requestApproval, m as ApproverRelationsOptions, n as applyApprovalVerdict, o as consumeApproval, p as summariseSubject, r as assertApprover, s as inspectApproval, t as MemoryApprovalStore, u as resolveApproval, v as ApprovalError, y as ApprovalErrorCode } from "../index-CltcQ4Bf.js";
+export { APPROVAL_HEADER, type ApprovalApprovers, type ApprovalCancelMeta, ApprovalError, type ApprovalErrorCode, type ApprovalInspectResult, type ApprovalListFilter, type ApprovalListQuery, type ApprovalPage, type ApprovalRequest, type ApprovalResumeFailure, type ApprovalSignature, type ApprovalStatus, type ApprovalStore, type ApprovalSubjectSummary, type ApprovalVerdict, type ApprovalsHandlerOptions, type ApproverRelationsOptions, DEFAULT_APPROVAL_TTL_MS, type MemoryApprovalStore, applyApprovalVerdict, approvalQuorum, approvalsHandler, approverRelationKey, approverRelations, assertApprover, cancelApprovals, consumeApproval, escalationOpenAt, inspectApproval, isApprovalError, memoryApprovalStore, readApprovalHeader, requestApproval, resolveApproval, resumeDecision, resumeFromHeader, summariseSubject };

package/dist/approvals/index.js

@@ -0,0 +1,4 @@
+import { n as isApprovalError, t as ApprovalError } from "../errors-m3u9TmDu.js";
+import { _ as approvalQuorum, a as requestApproval, c as resumeFromHeader, d as applyApprovalVerdict, f as assertApprover, g as DEFAULT_APPROVAL_TTL_MS, h as APPROVAL_HEADER, i as readApprovalHeader, m as approverRelations, n as consumeApproval, o as resolveApproval, p as memoryApprovalStore, r as inspectApproval, s as resumeDecision, t as cancelApprovals, u as summariseSubject, v as approverRelationKey, y as escalationOpenAt } from "../helpers-DnSOrhB9.js";
+import { t as approvalsHandler } from "../approvals-DaxY-Bdg.js";
+export { APPROVAL_HEADER, ApprovalError, DEFAULT_APPROVAL_TTL_MS, applyApprovalVerdict, approvalQuorum, approvalsHandler, approverRelationKey, approverRelations, assertApprover, cancelApprovals, consumeApproval, escalationOpenAt, inspectApproval, isApprovalError, memoryApprovalStore, readApprovalHeader, requestApproval, resolveApproval, resumeDecision, resumeFromHeader, summariseSubject };