permdock 0.3.1 → 0.5.0

package/dist/delivery-DCAgNyCn.js

@@ -0,0 +1,499 @@
+import { t as compact } from "./compact-CAf557ZB.js";
+import { n as freezeDeep } from "./freeze-CrU8nQeX.js";
+import { a as ownRecord } from "./paths-DXSHAMIa.js";
+import { n as loadPrincipalByIdentity } from "./principal-source-pHneukrx.js";
+import { t as deliveryEvent } from "./delivery-event-xX4obB8F.js";
+import { n as CLOUDEVENTS_CONTENT_TYPE } from "./sink-BEZSlMS_.js";
+import { a as isWebhookAddress, i as isDeliveryTarget, n as isAddrSpec, r as isChatAddress, t as idempotencyKeyFor } from "./target-Bw37TFNA.js";
+//#region src/delivery/memory-transport.ts
+/** An in-process transport for tests and examples: it records what it would have sent. */
+function memoryDeliveryTransport(channel, options = {}) {
+	const deliveries = [];
+	return Object.freeze({
+		channel,
+		name: "memory",
+		deliveries,
+		deliver(target, message, transportOptions) {
+			if (!isDeliveryTarget(target, channel)) return {
+				status: "failed",
+				cause: "invalid-recipient",
+				retryable: false
+			};
+			const result = options.respond?.(target, message) ?? { status: "sent" };
+			if (result.status === "sent") deliveries.push(Object.freeze({
+				target,
+				message,
+				options: transportOptions
+			}));
+			return result;
+		}
+	});
+}
+//#endregion
+//#region src/delivery/email.ts
+/** RFC 5322 `field-name`: printable US-ASCII except the colon. */
+const FIELD_NAME = /^[!-9;-~]{1,76}$/u;
+const NAME_ADDR = /^([^<>]*)<([^<>]+)>$/u;
+/** Fields the router owns, compared lower-cased. */
+const ROUTER_FIELDS = /* @__PURE__ */ new Set([
+	"auto-submitted",
+	"list-unsubscribe",
+	"list-unsubscribe-post"
+]);
+/** Fields that would add recipients or rewrite the envelope past the recipient check. */
+const ENVELOPE_FIELDS = /* @__PURE__ */ new Set([
+	"to",
+	"cc",
+	"bcc",
+	"from",
+	"sender",
+	"reply-to",
+	"subject",
+	"return-path",
+	"resent-to",
+	"resent-cc",
+	"resent-bcc"
+]);
+/** An unfolded field body: no CR, LF or other control character but tab. */
+function isFieldBody(value) {
+	for (const char of value) {
+		const code = char.codePointAt(0) ?? 0;
+		if (code < 32 && code !== 9 || code === 127) return false;
+	}
+	return true;
+}
+function fail(reason) {
+	return {
+		ok: false,
+		reason
+	};
+}
+function isMailbox(value) {
+	const named = NAME_ADDR.exec(value.trim());
+	return named === null ? isAddrSpec(value) : isAddrSpec(named[2]?.trim() ?? "");
+}
+function unsubscribeFor(message, target) {
+	const unsubscribe = message.unsubscribe;
+	return typeof unsubscribe === "function" ? unsubscribe(target) : unsubscribe;
+}
+function unsubscribeHeaders(unsubscribe) {
+	let url;
+	try {
+		url = new URL(unsubscribe?.url ?? "");
+	} catch {
+		return "a notification needs an https unsubscribe url (RFC 8058)";
+	}
+	if (url.protocol !== "https:") return "a notification needs an https unsubscribe url (RFC 8058)";
+	const mailto = unsubscribe?.mailto;
+	if (mailto !== void 0 && !isAddrSpec(mailto)) return "unsubscribe mailto is not an addr-spec";
+	return {
+		"List-Unsubscribe": mailto === void 0 ? `<${url.href}>` : `<${url.href}>, <mailto:${mailto}>`,
+		"List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
+	};
+}
+/**
+* The email a transport sends to `target`: `from` resolved, the caller's
+* headers checked, `Auto-Submitted: auto-generated` (RFC 3834) on every
+* message, and the RFC 2369 / RFC 8058 unsubscribe pair on `notification`
+* only. A message that cannot be sent as given returns the reason.
+*/
+function outgoingEmail(message, target, defaultFrom) {
+	const from = message.from ?? defaultFrom;
+	if (from === void 0 || !isFieldBody(from) || !isMailbox(from)) return fail("from is not a mailbox");
+	if (message.replyTo !== void 0 && !isAddrSpec(message.replyTo)) return fail("replyTo is not an addr-spec");
+	if (typeof message.subject !== "string" || message.subject.trim() === "" || !isFieldBody(message.subject)) return fail("subject is empty or has a line break");
+	if (typeof message.text !== "string" || message.text === "") return fail("text is empty");
+	const headers = { "Auto-Submitted": "auto-generated" };
+	for (const [name, value] of Object.entries(message.headers ?? {})) {
+		const lower = name.toLowerCase();
+		if (!FIELD_NAME.test(name) || typeof value !== "string" || !isFieldBody(value)) return fail(`header ${JSON.stringify(name)} is not a single-line field`);
+		if (ENVELOPE_FIELDS.has(lower)) return fail(`header ${name} is set through the message, not headers`);
+		if (!ROUTER_FIELDS.has(lower)) headers[name] = value;
+	}
+	if (message.category === "notification") {
+		const pair = unsubscribeHeaders(unsubscribeFor(message, target));
+		if (typeof pair === "string") return fail(pair);
+		Object.assign(headers, pair);
+	}
+	return {
+		ok: true,
+		email: Object.freeze(compact({
+			from,
+			replyTo: message.replyTo,
+			subject: message.subject,
+			text: message.text,
+			html: message.html,
+			category: message.category,
+			headers: Object.freeze(headers)
+		}))
+	};
+}
+//#endregion
+//#region src/delivery/router.ts
+const CHANNELS = /* @__PURE__ */ new Set([
+	"email",
+	"chat",
+	"webhook"
+]);
+function optionalString(value) {
+	if (value === void 0) return;
+	return typeof value === "string" && value !== "" ? value : null;
+}
+/** The recipient in the form its channel compares, or `null` when it is malformed. */
+function checkRecipient(value) {
+	const record = ownRecord(value);
+	const channel = record?.["channel"];
+	const raw = record?.["address"];
+	if (record === void 0 || typeof channel !== "string" || !CHANNELS.has(channel) || typeof raw !== "string") return null;
+	const principal = optionalString(record["principal"]);
+	const provider = optionalString(record["provider"]);
+	const workspace = optionalString(record["workspace"]);
+	if (principal === null || provider === null || workspace === null) return null;
+	const typed = channel;
+	const address = typed === "email" ? raw.trim().toLowerCase() : raw;
+	if (!(typed === "email" ? isAddrSpec(address) : typed === "chat" ? isChatAddress(address) && (principal !== void 0 || provider !== void 0) : isWebhookAddress(address) && principal !== void 0)) return null;
+	return compact({
+		channel: typed,
+		address,
+		principal,
+		provider,
+		workspace,
+		trusted: principal === void 0 && record["trusted"] === true
+	});
+}
+function denialReason(decision) {
+	switch (decision.outcome) {
+		case "granted": return "granted";
+		case "approval-required": return "approval-required";
+		case "denied": return decision.denials[0]?.reason ?? "no-grant";
+		default: return decision;
+	}
+}
+const TRANSPORT_CAUSES = /* @__PURE__ */ new Set([
+	"invalid-recipient",
+	"invalid-message",
+	"rate-limited",
+	"quota-exceeded",
+	"unauthorized",
+	"unavailable",
+	"suppressed",
+	"rejected"
+]);
+function isTransportCause(value) {
+	return typeof value === "string" && TRANSPORT_CAUSES.has(value);
+}
+function resultOf(value) {
+	const record = ownRecord(value);
+	if (record?.["status"] === "sent") {
+		const providerId = record["providerId"];
+		return typeof providerId === "string" && providerId !== "" ? {
+			status: "sent",
+			providerId
+		} : { status: "sent" };
+	}
+	if (record?.["status"] === "failed") {
+		const cause = record["cause"];
+		const reason = record["reason"];
+		return compact({
+			cause: isTransportCause(cause) ? cause : "rejected",
+			retryable: record["retryable"] === true,
+			reason: typeof reason === "string" ? reason : void 0
+		});
+	}
+	return {
+		cause: "unavailable",
+		retryable: true,
+		reason: "transport returned no result"
+	};
+}
+const THREW = Object.freeze({
+	cause: "unavailable",
+	retryable: true,
+	reason: "transport threw"
+});
+async function sendOne(ready) {
+	try {
+		return ready.finish(resultOf(await ready.transport.deliver(ready.item.target, ready.item.message, ready.item.options)));
+	} catch {
+		return ready.finish(THREW);
+	}
+}
+async function sendBatch(transport, batch) {
+	let results = [];
+	try {
+		results = await transport.deliverBatch?.(batch.map((ready) => ready.item)) ?? [];
+	} catch {
+		return batch.map((ready) => ready.finish(THREW));
+	}
+	return batch.map((ready, index) => ready.finish(results.length === batch.length ? resultOf(results[index]) : {
+		cause: "unavailable",
+		retryable: true,
+		reason: "batch returned the wrong number of results"
+	}));
+}
+/**
+* Sends every ready item: one batch call per `batchSize` items for a
+* transport with `deliverBatch`, one `deliver` call each otherwise. Events
+* keep recipient order.
+*/
+async function send(prepared) {
+	const events = prepared.map((entry) => "transport" in entry ? void 0 : entry);
+	const groups = /* @__PURE__ */ new Map();
+	for (const [index, entry] of prepared.entries()) if ("transport" in entry) {
+		const group = groups.get(entry.transport) ?? [];
+		group.push(index);
+		groups.set(entry.transport, group);
+	}
+	const ready = (index) => prepared[index];
+	await Promise.all([...groups].map(async ([transport, indexes]) => {
+		if (transport.deliverBatch === void 0 || indexes.length < 2) {
+			await Promise.all(indexes.map(async (index) => {
+				events[index] = await sendOne(ready(index));
+			}));
+			return;
+		}
+		const size = Math.max(1, Math.min(transport.batchSize ?? 100, 1e3));
+		for (let start = 0; start < indexes.length; start += size) {
+			const chunk = indexes.slice(start, start + size);
+			const sent = await sendBatch(transport, chunk.map(ready));
+			for (const [offset, index] of chunk.entries()) events[index] = sent[offset];
+		}
+	}));
+	return events;
+}
+/** Routes checked recipients to channel transports and records a delivery event for each. */
+function createPermDock(_policy, options) {
+	const source = options.source ?? "permdock";
+	const decideRecipient = async (permdock, checked, permission, row) => {
+		if (checked.principal !== void 0) return {
+			decision: await permdock.decideFor(checked.principal, permission, row),
+			principal: checked.principal
+		};
+		const kind = checked.channel;
+		const linked = await loadPrincipalByIdentity(options.principals, compact({
+			kind,
+			provider: kind === "chat" ? checked.provider : void 0,
+			value: checked.address,
+			workspace: kind === "chat" ? checked.workspace : void 0
+		}));
+		if (linked !== null) return {
+			decision: await permdock.decideFor(linked.id, permission, row),
+			principal: linked.id
+		};
+		if (!checked.trusted) return {
+			cause: "unlinked",
+			retryable: false,
+			reason: "no principal is linked to the address"
+		};
+		return { decision: permdock.decide(permission, row, {
+			call: "can",
+			adapter: "delivery"
+		}) };
+	};
+	const prepare = async (permdock, recipient, permission, row, messages, id, base) => {
+		const checked = checkRecipient(recipient);
+		const rawChannel = ownRecord(recipient)?.["channel"];
+		const channel = checked?.channel ?? (rawChannel === "chat" || rawChannel === "webhook" ? rawChannel : "email");
+		const key = idempotencyKeyFor(id, channel, JSON.stringify([
+			checked?.principal ?? null,
+			checked?.provider ?? null,
+			checked?.workspace ?? null,
+			checked?.address ?? null
+		]));
+		const category = channel === "email" ? messages.email?.category : void 0;
+		let principal = checked?.principal;
+		let trusted = false;
+		let provider;
+		const event = (operation, extra = {}) => deliveryEvent(compact({
+			source,
+			operation,
+			channel,
+			delivery: {
+				id,
+				key
+			},
+			recipient: principal === void 0 && !trusted ? void 0 : compact({
+				principal: principal === void 0 ? void 0 : { id: principal },
+				trusted: trusted ? true : void 0
+			}),
+			...base,
+			category,
+			provider,
+			...extra
+		}));
+		const fail = (failure) => event("failed", compact({
+			cause: failure.cause,
+			retryable: failure.retryable,
+			reason: failure.reason
+		}));
+		if (checked === null) return fail({
+			cause: "invalid-recipient",
+			retryable: false,
+			reason: "recipient is malformed"
+		});
+		const transport = options.transports[checked.channel];
+		if (transport === void 0) return fail({
+			cause: "no-transport",
+			retryable: false
+		});
+		const message = messages[checked.channel];
+		if (message === void 0) return fail({
+			cause: "no-message",
+			retryable: false
+		});
+		let decided;
+		try {
+			decided = await decideRecipient(permdock, checked, permission, row);
+		} catch {
+			return fail({
+				cause: "denied",
+				retryable: false,
+				reason: "closure-error"
+			});
+		}
+		if (!("decision" in decided)) return fail(decided);
+		principal = decided.principal;
+		trusted = decided.principal === void 0;
+		if (decided.decision.outcome !== "granted") return fail({
+			cause: "denied",
+			retryable: false,
+			reason: denialReason(decided.decision)
+		});
+		const target = Object.freeze(compact({
+			channel: checked.channel,
+			address: checked.address,
+			principal,
+			provider: checked.provider,
+			workspace: checked.workspace,
+			trusted: trusted ? true : void 0,
+			decision: decided.decision
+		}));
+		let outgoing;
+		if (checked.channel === "email") try {
+			const built = outgoingEmail(message, target, options.from ?? options.transports.email?.from);
+			if (!built.ok) return fail({
+				cause: "invalid-message",
+				retryable: false,
+				reason: built.reason
+			});
+			outgoing = built.email;
+		} catch {
+			return fail({
+				cause: "invalid-message",
+				retryable: false,
+				reason: "unsubscribe threw"
+			});
+		}
+		else outgoing = message;
+		provider = { name: transport.name };
+		return {
+			transport,
+			item: Object.freeze({
+				target,
+				message: outgoing,
+				options: Object.freeze({
+					idempotencyKey: key,
+					delivery: id
+				})
+			}),
+			finish(result) {
+				if ("status" in result && result.status === "sent") {
+					provider = compact({
+						name: transport.name,
+						id: result.providerId
+					});
+					return event("sent");
+				}
+				return fail(result);
+			}
+		};
+	};
+	return Object.freeze({ async deliver(permdock, target, row, recipients, messages, deliverOptions = {}) {
+		const permission = "permission" in target ? target.permission : target;
+		const id = deliverOptions.id ?? `dlv_${globalThis.crypto.randomUUID()}`;
+		const base = compact({
+			permission: permission.key,
+			tenant: permdock.subject.principal?.tenant,
+			approval: deliverOptions.approval
+		});
+		const events = await send(await Promise.all(recipients.map((recipient) => prepare(permdock, recipient, permission, row, messages, id, base))));
+		try {
+			await options.sink?.write(events);
+		} catch {}
+		const sent = events.filter((entry) => entry.operation === "sent").length;
+		return freezeDeep({
+			id,
+			events,
+			sent,
+			failed: events.length - sent
+		});
+	} });
+}
+//#endregion
+//#region src/delivery/webhook-transport.ts
+function failed(cause, retryable, reason) {
+	return {
+		status: "failed",
+		cause,
+		retryable,
+		reason
+	};
+}
+function fromStatus(status) {
+	if (status >= 200 && status < 300) return { status: "sent" };
+	if (status === 429) return failed("rate-limited", true, `HTTP ${status}`);
+	if (status === 408 || status >= 500) return failed("unavailable", true, `HTTP ${status}`);
+	if (status === 401 || status === 403) return failed("unauthorized", false, `HTTP ${status}`);
+	return failed("rejected", false, `HTTP ${status}`);
+}
+/**
+* Posts each CloudEvent to the target's https endpoint as
+* `application/cloudevents+json`, signed with the Standard Webhooks
+* headers. `webhook-id` is the idempotency key, so a retry repeats it and
+* the receiver drops the duplicate. Redirects are not followed.
+*/
+function webhookTransport(signer, options = {}) {
+	const timeout = options.timeout ?? 1e4;
+	return Object.freeze({
+		channel: "webhook",
+		name: "webhook",
+		async deliver(target, message, transportOptions) {
+			if (!isDeliveryTarget(target, "webhook") || !isWebhookAddress(target.address)) return {
+				status: "failed",
+				cause: "invalid-recipient",
+				retryable: false
+			};
+			let body;
+			try {
+				body = JSON.stringify(message.event);
+			} catch {
+				return {
+					status: "failed",
+					cause: "invalid-message",
+					retryable: false
+				};
+			}
+			const headers = await signer.sign({
+				id: transportOptions.idempotencyKey,
+				body
+			});
+			const send = options.fetch ?? globalThis.fetch;
+			try {
+				return fromStatus((await send(target.address, {
+					method: "POST",
+					headers: {
+						...headers,
+						"content-type": CLOUDEVENTS_CONTENT_TYPE
+					},
+					body,
+					redirect: "manual",
+					signal: AbortSignal.timeout(timeout)
+				})).status);
+			} catch {
+				return failed("unavailable", true, "request failed");
+			}
+		}
+	});
+}
+//#endregion
+export { createPermDock as n, memoryDeliveryTransport as r, webhookTransport as t };

package/dist/delivery-event-xX4obB8F.js

@@ -0,0 +1,40 @@
+import { t as compact } from "./compact-CAf557ZB.js";
+import { t as assertAppData } from "./app-data-MuyzVqX8.js";
+import { d as isoNow } from "./time-DkWjdL98.js";
+import { n as requireEventInstant } from "./event-time-CsegxXxB.js";
+//#region src/core/delivery-event.ts
+/**
+* A `delivery` sink event. Throws a `TypeError` when `cause` or `retryable`
+* is set on an operation other than `failed`, and a `RangeError` for a
+* malformed `at`.
+*/
+function checkedX(x) {
+	assertAppData(x, "x of a delivery event");
+	return x;
+}
+function deliveryEvent(input) {
+	if (input.operation !== "failed" && (input.cause !== void 0 || input.retryable !== void 0)) throw new TypeError("PermDock: cause and retryable belong on failed delivery events only");
+	return compact({
+		type: "delivery",
+		at: requireEventInstant(input.at, "at") ?? isoNow(),
+		source: input.source,
+		operation: input.operation,
+		channel: input.channel,
+		delivery: {
+			id: input.delivery.id,
+			key: input.delivery.key
+		},
+		recipient: input.recipient,
+		permission: input.permission,
+		tenant: input.tenant,
+		category: input.category,
+		approval: input.approval,
+		provider: input.provider,
+		cause: input.cause,
+		retryable: input.retryable,
+		reason: input.reason,
+		x: input.x === void 0 ? void 0 : checkedX(input.x)
+	});
+}
+//#endregion
+export { deliveryEvent as t };

package/dist/denied-text-D8jDHgsl.d.ts

@@ -0,0 +1,19 @@
+import { Nn as Decision } from "./policy-types-DzwivBgR.js";
+import { w as Permission } from "./vocabulary-D6lPdb4Z.js";
+//#region src/agent/denied-text.d.ts
+/** What an agent adapter's `deniedText` receives: the refusal and the text PermDock wrote for it. */
+type DeniedTextEvent = {
+  readonly decision: Exclude<Decision, {
+    readonly outcome: "granted";
+  }> | null;
+  readonly permission: Permission | undefined;
+  readonly text: string;
+};
+/**
+ * Replaces the human-readable text of a refusal, and nothing else: the
+ * outcome, `isError`, the structured content and the approval token stay.
+ * `undefined` keeps PermDock's text.
+ */
+type DeniedText = (event: DeniedTextEvent) => string | undefined;
+//#endregion
+export { DeniedTextEvent as n, DeniedText as t };

package/dist/{describe-DMYiCjJV.d.ts → describe-BZUsixiL.d.ts}

@@ -1,5 +1,5 @@
-import { Qn as DeniedDecision, Yn as Decision, Zn as DenialReason } from "./policy-IB6yxpC3.js";
-import { f as Permission } from "./permissions-DttnqqxC.js";
+import { In as DenialReason, Ln as DeniedDecision, Nn as Decision } from "./policy-types-DzwivBgR.js";
+import { w as Permission } from "./vocabulary-D6lPdb4Z.js";
 //#region src/core/describe.d.ts
 type DecisionDescription = {
   readonly kind: "granted" | "denied" | "approval" | "tenant" | "delegation" | "server-only" | "upgrade";
@@ -30,6 +30,15 @@ type DescribeMessages = {
 };
 type DescribeOptions = {
   readonly messages?: DescribeMessages;
+  /**
+   * The permission the decision is about. Its `meta.title` replaces the key in
+   * the `granted` and `approval` text, and is what the message functions get.
+   */
+  readonly permission?: Pick<Permission, "key"> & {
+    readonly meta?: {
+      readonly title?: string;
+    };
+  };
 };
 declare function describe(decision: Decision, options?: DescribeOptions): DecisionDescription;
 //#endregion

package/dist/{describe-B_gVZEVi.js → describe-BybMRY7A.js}

@@ -1,5 +1,5 @@
-import { i as flattenApprovers } from "./approvers-DT4AVyIg.js";
-import { r as requiredPlans } from "./problem-details-_AMOYz-w.js";
+import { i as flattenApprovers } from "./approvers-CqPOLD-o.js";
+import { r as requiredPlans } from "./problem-details-cn5X30gZ.js";
 //#region src/core/describe.ts
 const TENANT_REASONS = /* @__PURE__ */ new Set([
 	"tenant-mismatch",
@@ -7,7 +7,11 @@ const TENANT_REASONS = /* @__PURE__ */ new Set([
 	"expired-membership",
 	"scope"
 ]);
-const DELEGATION_REASONS = /* @__PURE__ */ new Set(["not-delegated", "no-delegation"]);
+const DELEGATION_REASONS = /* @__PURE__ */ new Set([
+	"not-delegated",
+	"no-delegation",
+	"agent-tool-not-delegated"
+]);
 function labelGrantee(grantee) {
 	switch (grantee.kind) {
 		case "role": return grantee.role;
@@ -51,9 +55,10 @@ function approvalDetail(permission, labels) {
 }
 function describe(decision, options) {
 	const messages = options?.messages;
+	const labelOf = (key) => options?.permission?.key === key ? options.permission.meta?.title ?? key : key;
 	const titleOf = (kind) => messages?.titles?.[kind] ?? TITLES[kind];
 	if (decision.outcome === "granted") {
-		const { permission } = decision.matched;
+		const permission = labelOf(decision.matched.permission);
 		return {
 			kind: "granted",
 			title: titleOf("granted"),
@@ -62,7 +67,7 @@ function describe(decision, options) {
 		};
 	}
 	if (decision.outcome === "approval-required") {
-		const { permission } = decision.grant;
+		const permission = labelOf(decision.grant.permission);
 		const labels = approvers(decision.grant.approval);
 		return {
 			kind: "approval",