primcli 1.75.0 → 3.0.0-preview.10

package/dist/receiver.js

@@ -0,0 +1,569 @@
+// src/oclif/contact-rule-matcher.ts
+const localPart = /^[a-z0-9!#$%&'+/=^_`{|}~-]+(?:\.[a-z0-9!#$%&'+/=^_`{|}~-]+)*$/;
+const patternPart = /^[a-z0-9.!#$%&'+/=^_`{|}~*-]+$/;
+const label = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+function domain(value) {
+	const labels = value.split(".");
+	return value.length <= 253 && labels.length >= 2 && labels.every((part) => label.test(part)) && /[a-z]/.test(labels.at(-1) ?? "");
+}
+function domainPattern(value) {
+	return domain(value.startsWith("*.") ? value.slice(2) : value);
+}
+function splitAddress(value) {
+	const parts = value.split("@");
+	const [local, host] = parts;
+	return parts.length === 2 && local && host ? [local, host] : null;
+}
+/** Restricted selectors are canonical data, never regular expressions. */
+function canonicalContactSelector(input) {
+	const invalid = () => /* @__PURE__ */ new Error("Invalid contact approval selector.");
+	const trimmed = input.value.trim();
+	for (const character of trimmed) if (character.charCodeAt(0) > 127) throw invalid();
+	const value = trimmed.toLowerCase();
+	if (!value || value.length > 254) throw invalid();
+	if (input.kind === "domain") {
+		if (!domainPattern(value)) throw invalid();
+		return {
+			kind: input.kind,
+			value
+		};
+	}
+	const parts = splitAddress(value);
+	if (!parts) throw invalid();
+	const [local, host] = parts;
+	if (local.length > 64 || local.startsWith(".") || local.endsWith(".") || local.includes("..")) throw invalid();
+	if (input.kind === "address") {
+		if (!localPart.test(local) || !domain(host)) throw invalid();
+	} else if (input.kind === "pattern") {
+		if (!patternPart.test(local) || local !== "*" && !localPart.test(local.endsWith("*") ? local.slice(0, -1) : local) || !domainPattern(host) || local.includes("*") && (!local.endsWith("*") || local.slice(0, -1).includes("*"))) throw invalid();
+	} else throw invalid();
+	return {
+		kind: input.kind,
+		value
+	};
+}
+function matchesDomain(pattern, value) {
+	if (!pattern.startsWith("*.")) return pattern === value;
+	const suffix = pattern.slice(1);
+	return value.length > suffix.length && value.endsWith(suffix);
+}
+function matchesLocal(pattern, value) {
+	return pattern.endsWith("*") ? value.startsWith(pattern.slice(0, -1)) : value === pattern;
+}
+function matchesContactPattern(pattern, sender) {
+	return matchesContactSelector({
+		kind: "pattern",
+		value: pattern
+	}, sender);
+}
+/** Malformed sender identities never match; malformed stored rules fail closed. */
+function matchesContactSelector(input, sender) {
+	const selector = canonicalContactSelector(input);
+	let address;
+	try {
+		address = canonicalContactSelector({
+			kind: "address",
+			value: sender
+		}).value;
+	} catch {
+		return false;
+	}
+	if (selector.kind === "address") return selector.value === address;
+	const [local, host] = splitAddress(address) ?? [];
+	if (!local || !host) return false;
+	if (selector.kind === "domain") return matchesDomain(selector.value, host);
+	const [localPattern, hostPattern] = splitAddress(selector.value) ?? [];
+	return Boolean(localPattern && hostPattern && matchesDomain(hostPattern, host) && matchesLocal(localPattern, local));
+}
+// src/oclif/listen-state.ts
+var ListenStateError = class extends Error {};
+// src/oclif/shared-mail-files.ts
+var SharedMailStateError = class extends ListenStateError {};
+const invalidSharedMail = () => new SharedMailStateError("Shared mail state is invalid or inconsistent. Preserve it before retrying to avoid duplicate delivery.");
+function mailId(value) {
+	if (typeof value !== "string" || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(value)) throw invalidSharedMail();
+	return value.toLowerCase();
+}
+function mailString(value, max = 256) {
+	if (typeof value !== "string" || !value || value.length > max || Array.from(value).some((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127)) throw invalidSharedMail();
+	return value;
+}
+function mailAddress(value) {
+	const address = mailString(value, 254).toLowerCase();
+	if (!/^[^\s<>@]+@[^\s<>@]+\.[^\s<>@]+$/.test(address)) throw invalidSharedMail();
+	return address;
+}
+function mailTime(value) {
+	const time = mailString(value, 40);
+	if (!Number.isFinite(Date.parse(time))) throw invalidSharedMail();
+	return new Date(time).toISOString();
+}
+// src/oclif/contact-policy.ts
+function record(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid contact policy.");
+	return value;
+}
+function fingerprint(value) {
+	if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value)) throw new Error("Invalid contact policy version.");
+	return value;
+}
+function document(value, organization) {
+	const row = record(value);
+	if (!Array.isArray(row.rules) || row.rules.length > 100 || !(typeof row.allow_contact_requests === "boolean" || !organization && row.allow_contact_requests === null)) throw new Error("Invalid contact policy document.");
+	const seen = /* @__PURE__ */ new Set();
+	const rules = row.rules.map((value) => {
+		const rule = record(value);
+		if (typeof rule.pattern !== "string" || rule.effect !== "allow" && rule.effect !== "silence") throw new Error("Invalid contact policy rule.");
+		const pattern = canonicalContactSelector({
+			kind: "pattern",
+			value: rule.pattern
+		}).value;
+		const key = `${pattern}:${rule.effect}`;
+		if (pattern !== rule.pattern || seen.has(key)) throw new Error("Invalid contact policy rule.");
+		seen.add(key);
+		if (rule.effect === "silence") {
+			if (rule.notify_since !== null || rule.notification_generation !== null) throw new Error("Invalid silence rule.");
+			return {
+				pattern,
+				effect: "silence",
+				notify_since: null,
+				notification_generation: null
+			};
+		}
+		return {
+			pattern,
+			effect: "allow",
+			notify_since: mailTime(rule.notify_since),
+			notification_generation: mailId(rule.notification_generation)
+		};
+	});
+	const version = row.version === null ? null : mailId(row.version);
+	const updatedAt = row.updated_at === null ? null : mailTime(row.updated_at);
+	if (version === null !== (updatedAt === null)) throw new Error("Invalid contact policy document version.");
+	const requests = row.allow_contact_requests;
+	if (requests !== true && (row.contact_request_since !== null || row.contact_request_generation !== null)) throw new Error("Invalid contact request activation.");
+	if (version === null && (rules.length || requests !== (organization ? false : null))) throw new Error("Invalid missing contact policy document.");
+	return {
+		rules,
+		allow_contact_requests: requests,
+		contact_request_since: requests === true ? mailTime(row.contact_request_since) : null,
+		contact_request_generation: requests === true ? mailId(row.contact_request_generation) : null,
+		version,
+		updated_at: updatedAt
+	};
+}
+function parseAgentContactPolicy(value, recipient) {
+	const row = record(value);
+	if (row.agent_address !== recipient || typeof row.allow_contact_requests !== "boolean") throw new Error("Contact policy recipient mismatch.");
+	const org = document(row.org_policy, true);
+	const agent = document(row.agent_policy, false);
+	if (row.allow_contact_requests !== (agent.allow_contact_requests ?? org.allow_contact_requests)) throw new Error("Inconsistent contact request policy.");
+	if (!row.allow_contact_requests && (row.contact_request_since !== null || row.contact_request_generation !== null)) throw new Error("Invalid effective contact request activation.");
+	return {
+		agent_address: recipient,
+		org_policy: org,
+		agent_policy: agent,
+		effective_version: fingerprint(row.effective_version),
+		effective_since: mailTime(row.effective_since),
+		allow_contact_requests: row.allow_contact_requests,
+		contact_request_since: row.allow_contact_requests ? mailTime(row.contact_request_since) : null,
+		contact_request_generation: row.allow_contact_requests ? fingerprint(row.contact_request_generation) : null
+	};
+}
+const latest = (left, right) => Date.parse(left) >= Date.parse(right) ? left : right;
+const arrived = (received, since) => Date.parse(received) >= Date.parse(since);
+/** Owner rules are unordered. Agent matches take precedence; silence wins ties. */
+function evaluateContactPolicy(options) {
+	const { policy, sender, receivedAt, membership } = options;
+	if (membership?.notify === false) return {
+		kind: "silent",
+		source: "membership"
+	};
+	for (const source of ["agent", "org"]) {
+		const matches = policy[`${source}_policy`].rules.filter((rule) => matchesContactPattern(rule.pattern, sender));
+		if (!matches.length) continue;
+		if (matches.some((rule) => rule.effect === "silence")) return {
+			kind: "silent",
+			source
+		};
+		for (const rule of matches.sort((a, b) => a.pattern < b.pattern ? -1 : a.pattern > b.pattern ? 1 : 0)) {
+			if (!rule.notify_since || !rule.notification_generation) throw new Error("Missing rule activation.");
+			const since = latest(rule.notify_since, policy.effective_since);
+			if (arrived(receivedAt, since)) return {
+				kind: "allowed",
+				source,
+				pattern: rule.pattern,
+				generation: rule.notification_generation,
+				notifySince: since
+			};
+		}
+		return {
+			kind: "silent",
+			source
+		};
+	}
+	if (membership?.notify === true) {
+		const since = membership.notifySince;
+		return arrived(receivedAt, since) ? {
+			kind: "allowed",
+			source: "membership",
+			generation: membership.generation,
+			notifySince: since
+		} : {
+			kind: "silent",
+			source: "membership"
+		};
+	}
+	if (options.contactRequests && policy.allow_contact_requests && policy.contact_request_since && policy.contact_request_generation) {
+		const since = latest(policy.contact_request_since, policy.effective_since);
+		if (arrived(receivedAt, since)) return {
+			kind: "request",
+			generation: policy.contact_request_generation,
+			notifySince: since
+		};
+	}
+	return {
+		kind: "silent",
+		source: "default"
+	};
+}
+// src/oclif/notify-session-content.ts
+var NotificationRetryError = class extends ListenStateError {};
+const CONTACT_POLICY_RETRY_MIN_MS = 1e3;
+const CONTACT_POLICY_RETRY_MAX_MS = 3e4;
+var NetworkAdmissionPendingError = class extends NotificationRetryError {
+	constructor() {
+		super("Network mail admission is pending delivery proof.");
+	}
+};
+var ContactPolicyReadRetryError = class extends NotificationRetryError {
+	constructor() {
+		super("Contact notification policy is temporarily unavailable. Mail remains pending while permissions are refreshed.");
+	}
+};
+/** A network decision is trusted only when every field agrees with the others. */
+function consistentNetworkAdmission(decision) {
+	const relation = decision.sender_relation;
+	return typeof decision.allowed === "boolean" && typeof decision.pending === "boolean" && typeof decision.member_policy_required === "boolean" && (relation === void 0 || decision.member_policy_required && (relation === "owner" || relation === "member")) && !(decision.member_policy_required && decision.allowed && !relation) && !(decision.pending && (decision.allowed || decision.allowed_since !== null)) && (decision.allowed ? typeof decision.allowed_since === "string" : decision.allowed_since === null);
+}
+const unavailable = () => new ListenStateError("Contact notification preferences are unavailable or invalid. No contact notification was submitted; restart after access is restored.");
+const changed = () => new NotificationRetryError("Contact notification permission changed or expired before dispatch.");
+/** Read one connected address's policy. Partial pages never authorize delivery. */
+function createNotificationContactPolicy(options) {
+	const recipient = mailAddress(options.recipient);
+	const now = options.now ?? (() => performance.now());
+	let snapshot;
+	let retryAt = 0;
+	let retryDelay = CONTACT_POLICY_RETRY_MIN_MS;
+	function fresh(value) {
+		if (!value) return false;
+		const elapsed = now() - value.startedAt;
+		return elapsed >= 0 && elapsed < 3e4;
+	}
+	async function refreshOnce(signal) {
+		snapshot = void 0;
+		signal.throwIfAborted();
+		if (now() < retryAt) throw new ContactPolicyReadRetryError();
+		const startedAt = now();
+		const peers = /* @__PURE__ */ new Set();
+		let cursor;
+		try {
+			const next = {
+				startedAt,
+				senders: /* @__PURE__ */ new Map(),
+				policy: parseAgentContactPolicy(await options.readPolicy(signal), recipient)
+			};
+			do {
+				signal.throwIfAborted();
+				const page = await options.readPage(cursor, signal);
+				signal.throwIfAborted();
+				if (!fresh(next) || !Array.isArray(page.data) || page.data.length > 100) throw unavailable();
+				let previous = cursor;
+				for (const value of page.data) {
+					if (!value || typeof value !== "object" || Array.isArray(value)) throw unavailable();
+					const row = value;
+					const peer = mailAddress(row.contact_address);
+					if (row.agent_address !== recipient || row.contact_address !== peer || previous !== void 0 && peer <= previous || peers.has(peer) || typeof row.notify !== "boolean") throw unavailable();
+					mailId(row.version);
+					peers.add(peer);
+					previous = peer;
+					if (row.notify) next.senders.set(peer, {
+						notify: true,
+						generation: mailId(row.notification_generation),
+						notifySince: mailTime(row.notify_since)
+					});
+					else if (row.notification_generation !== null || row.notify_since !== null) throw unavailable();
+					else next.senders.set(peer, { notify: false });
+				}
+				if (page.cursor === null) cursor = void 0;
+				else {
+					const following = mailAddress(page.cursor);
+					if (!page.data.length || following !== previous) throw unavailable();
+					cursor = following;
+				}
+			} while (cursor !== void 0);
+			if (!fresh(next)) throw unavailable();
+			snapshot = next;
+			retryAt = 0;
+			retryDelay = CONTACT_POLICY_RETRY_MIN_MS;
+			return next;
+		} catch (error) {
+			snapshot = void 0;
+			signal.throwIfAborted();
+			if (error instanceof ContactPolicyReadRetryError) {
+				retryAt = now() + retryDelay;
+				retryDelay = Math.min(retryDelay * 2, CONTACT_POLICY_RETRY_MAX_MS);
+				throw error;
+			}
+			throw unavailable();
+		}
+	}
+	function admission(value, sender, receivedAt, solicited = false) {
+		const decision = evaluateContactPolicy({
+			policy: value.policy,
+			sender,
+			receivedAt,
+			membership: value.senders.get(sender),
+			contactRequests: options.contactRequests === true
+		});
+		if (decision.kind === "silent") {
+			if (!solicited || decision.source !== "default") return null;
+			return {
+				sender,
+				receivedAt,
+				generation: value.policy.effective_version,
+				notifySince: value.policy.effective_since,
+				kind: "response",
+				effectiveVersion: value.policy.effective_version
+			};
+		}
+		return {
+			sender,
+			receivedAt,
+			generation: decision.generation,
+			notifySince: decision.notifySince,
+			kind: solicited ? "response" : decision.kind,
+			effectiveVersion: value.policy.effective_version
+		};
+	}
+	async function admissionWithNetwork(value, sender, receivedAt, signal, emailId, networkReader = options.readNetworkAdmission, solicited = false) {
+		const contact = admission(value, sender, receivedAt, solicited);
+		const decision = evaluateContactPolicy({
+			policy: value.policy,
+			sender,
+			receivedAt,
+			membership: value.senders.get(sender),
+			contactRequests: options.contactRequests === true
+		});
+		if (!networkReader) return contact;
+		if (!emailId) throw unavailable();
+		const network = await networkReader(emailId, sender, signal);
+		signal.throwIfAborted();
+		if (!consistentNetworkAdmission(network)) throw unavailable();
+		if (network.member_policy_required) {
+			if (network.pending) throw new NetworkAdmissionPendingError();
+			if (!network.allowed) return null;
+			if (decision.kind === "silent" && decision.source !== "default") return null;
+			return networkAdmission(value, sender, receivedAt, emailId, network, solicited);
+		}
+		const scopedContact = contact ? {
+			...contact,
+			emailId
+		} : null;
+		if (contact?.kind === "allowed" || contact?.kind === "response") return scopedContact;
+		if (decision.kind !== "request" && !(decision.kind === "silent" && decision.source === "default")) return scopedContact;
+		if (network.pending) throw new NetworkAdmissionPendingError();
+		if (!network.allowed) return scopedContact;
+		return networkAdmission(value, sender, receivedAt, emailId, network, solicited);
+	}
+	function networkAdmission(value, sender, receivedAt, emailId, network, solicited) {
+		const networkSince = network.allowed_since && mailTime(network.allowed_since);
+		if (!networkSince) throw unavailable();
+		const since = Date.parse(value.policy.effective_since) > Date.parse(networkSince) ? value.policy.effective_since : networkSince;
+		if (Date.parse(receivedAt) < Date.parse(since)) return null;
+		return {
+			sender,
+			emailId,
+			receivedAt,
+			generation: since,
+			notifySince: since,
+			kind: solicited ? "response" : "allowed",
+			effectiveVersion: value.policy.effective_version,
+			source: "network",
+			...network.sender_relation ? { senderRelation: network.sender_relation } : {}
+		};
+	}
+	function permits(prior, current) {
+		return current !== null && current.emailId === prior.emailId && current.kind === prior.kind && current.source === prior.source && current.senderRelation === prior.senderRelation && current.generation === prior.generation && current.notifySince === prior.notifySince && current.effectiveVersion === prior.effectiveVersion;
+	}
+	return {
+		refresh: refreshOnce,
+		members() {
+			if (!fresh(snapshot)) throw unavailable();
+			return snapshot.senders.keys();
+		},
+		async admit(sender, receivedAt, signal, emailId) {
+			signal.throwIfAborted();
+			let peer;
+			try {
+				peer = mailAddress(sender);
+			} catch {
+				return null;
+			}
+			const received = mailTime(receivedAt);
+			const inboundId = emailId === void 0 ? void 0 : mailId(emailId);
+			const reader = options.readNetworkAdmission;
+			let networkResult;
+			const networkReader = reader ? (id, address, abort) => networkResult ??= reader(id, address, abort) : void 0;
+			const cached = fresh(snapshot);
+			let current = cached && snapshot ? snapshot : await refreshOnce(signal);
+			let allowed = await admissionWithNetwork(current, peer, received, signal, inboundId, networkReader);
+			if (cached && allowed?.kind !== "allowed") {
+				current = await refreshOnce(signal);
+				allowed = await admissionWithNetwork(current, peer, received, signal, inboundId, networkReader);
+			}
+			return allowed;
+		},
+		async recheck(prior, signal) {
+			const current = await refreshOnce(signal);
+			const candidate = await admissionWithNetwork(current, prior.sender, prior.receivedAt, signal, prior.emailId, options.readNetworkAdmission, prior.kind === "response");
+			if (!permits(prior, candidate)) throw changed();
+			return () => {
+				signal.throwIfAborted();
+				if (!fresh(snapshot) || snapshot !== current || !permits(prior, candidate)) throw changed();
+			};
+		},
+		async admitResponse(sender, receivedAt, signal, emailId) {
+			return admissionWithNetwork(await refreshOnce(signal), mailAddress(sender), mailTime(receivedAt), signal, emailId, options.readNetworkAdmission, true);
+		}
+	};
+}
+// src/receiver.ts
+/**
+* Supported API for receivers that wake a coding session on Primitive mail.
+* Import it as `primitive/receiver`. See "Supported receiver API" in the
+* package README.
+*/
+const RETRYABLE = {
+	policy_read_failed: true,
+	network_admission_pending: true,
+	permission_changed: true,
+	policy_unavailable: false
+};
+var WakePolicyError = class extends Error {
+	code;
+	/** Whether the same email may be admitted later without operator action. */
+	retryable;
+	constructor(code, options) {
+		super(`Wake policy: ${code}`, options);
+		this.name = "WakePolicyError";
+		this.code = code;
+		this.retryable = RETRYABLE[code];
+	}
+};
+function publicError(error, signal) {
+	if (signal.aborted) return signal.reason;
+	if (error instanceof WakePolicyError) return error;
+	if (error instanceof NetworkAdmissionPendingError) return new WakePolicyError("network_admission_pending");
+	if (error instanceof ContactPolicyReadRetryError) return new WakePolicyError("policy_read_failed");
+	if (error instanceof NotificationRetryError) return new WakePolicyError("permission_changed");
+	return new WakePolicyError("policy_unavailable", { cause: error });
+}
+function transient(read) {
+	return async (...args) => {
+		try {
+			return await read(...args);
+		} catch (error) {
+			if (error instanceof WakePolicyError && error.code === "policy_read_failed") throw new ContactPolicyReadRetryError();
+			throw error;
+		}
+	};
+}
+/**
+* The policy backs off its own reads but not the network read, which runs per
+* email. Give that read the same backoff so a receiver that retries right away
+* does not keep calling a failing server.
+*/
+function paced(read) {
+	let retryAt = 0;
+	let retryDelay = CONTACT_POLICY_RETRY_MIN_MS;
+	return async (...args) => {
+		if (performance.now() < retryAt) throw new ContactPolicyReadRetryError();
+		try {
+			const value = await read(...args);
+			retryAt = 0;
+			retryDelay = CONTACT_POLICY_RETRY_MIN_MS;
+			return value;
+		} catch (error) {
+			if (error instanceof ContactPolicyReadRetryError) {
+				retryAt = performance.now() + retryDelay;
+				retryDelay = Math.min(retryDelay * 2, CONTACT_POLICY_RETRY_MAX_MS);
+			}
+			throw error;
+		}
+	};
+}
+function inbound(email) {
+	try {
+		return {
+			emailId: mailId(email.emailId),
+			receivedAt: mailTime(email.receivedAt)
+		};
+	} catch {
+		throw new TypeError("admit needs an email ID (UUID) and an ISO 8601 received time.");
+	}
+}
+/** Create the contact admission policy for one connected address. */
+function createWakePolicy(options) {
+	let recipient;
+	try {
+		recipient = mailAddress(options.recipient);
+	} catch {
+		throw new TypeError("createWakePolicy needs a recipient email address.");
+	}
+	const policy = createNotificationContactPolicy({
+		recipient,
+		contactRequests: options.contactRequests === true,
+		readPolicy: transient(options.readContactPolicy),
+		readPage: transient(options.readContactPage),
+		readNetworkAdmission: paced(transient(options.readNetworkAdmission))
+	});
+	const issued = /* @__PURE__ */ new WeakMap();
+	return {
+		async admit(email, signal) {
+			const { emailId, receivedAt } = inbound(email);
+			let admitted;
+			try {
+				admitted = await policy.admit(email.sender, receivedAt, signal, emailId);
+			} catch (error) {
+				throw publicError(error, signal);
+			}
+			if (admitted === null || admitted.kind === "response") return { kind: "denied" };
+			const admission = Object.freeze({
+				kind: admitted.kind,
+				emailId,
+				sender: admitted.sender,
+				receivedAt
+			});
+			issued.set(admission, admitted);
+			return admission;
+		},
+		async recheck(admission, signal) {
+			const prior = issued.get(admission);
+			if (!prior) throw new TypeError("recheck takes an admission returned by this policy's admit.");
+			try {
+				const confirm = await policy.recheck(prior, signal);
+				return () => {
+					try {
+						confirm();
+					} catch (error) {
+						throw publicError(error, signal);
+					}
+				};
+			} catch (error) {
+				throw publicError(error, signal);
+			}
+		}
+	};
+}
+export { WakePolicyError, createWakePolicy };