@edgehero/pi-dispatch-receiver 0.1.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@edgehero/pi-dispatch-receiver",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Webhook receiver for pi-dispatch: the always-on edge that verifies GitHub, GitLab, Forgejo and Azure DevOps deliveries and enqueues (at most) one job per event for the worker.",
+  "keywords": [
+    "pi",
+    "pi-coding-agent",
+    "coding-agent",
+    "ai-agent",
+    "self-hosted",
+    "webhook",
+    "github",
+    "gitlab",
+    "forgejo",
+    "gitea",
+    "azure-devops",
+    "job-queue",
+    "bullmq"
+  ],
+  "license": "MIT",
+  "author": "Rob Boerman",
+  "homepage": "https://github.com/edgehero/pi-dispatch/tree/main/receiver",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/edgehero/pi-dispatch.git",
+    "directory": "receiver"
+  },
+  "bugs": "https://github.com/edgehero/pi-dispatch/issues",
+  "files": [
+    "src"
+  ],
+  "main": "src/start.mjs",
+  "bin": {
+    "pi-dispatch-receiver": "src/cli.mjs"
+  },
+  "exports": {
+    "./start": "./src/start.mjs"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\""
+  },
+  "dependencies": {
+    "@octokit/webhooks": "14.2.0",
+    "@edgehero/pi-dispatch": "^0.1.0",
+    "bullmq": "5.80.4",
+    "ioredis": "5.11.1"
+  }
+}

package/src/azure-members.mjs

@@ -0,0 +1,119 @@
+/**
+ * Resolve an Azure DevOps actor's project membership -- the enforcement half of
+ * `CONST-TRIGGER-AUTHOR-GATE` on the Azure side.
+ *
+ * Azure has no `author_association` and no numeric access level. What it has is a graph of subjects and
+ * groups, and "is this person a member of this project" is answered by walking it. That is TWO calls, not
+ * one, which is a real cost this arm carries and the other three do not:
+ *
+ *   1. the actor -> a subject DESCRIPTOR. A pull-request payload gives a GUID, a work-item payload gives
+ *      only an email address, so there are two lookups depending on which the event carried.
+ *   2. the descriptor -> membership of the project's own group.
+ *
+ * Both can go indeterminate, so the indeterminate surface here is wider than GitLab's, not merely equal to
+ * it. `OQ-013` is amended to say so rather than leaving it implied.
+ *
+ * The verdict shape is every other forge's: `{ authorized }` | `{ indeterminate }`. A determinate "not a
+ * member" refuses; anything that could not be answered is a 503 so Azure redelivers.
+ *
+ * WHY MEMBERSHIP AND NOT A PERMISSION EVALUATION. Azure's Security namespace API can answer "may this
+ * subject contribute to this repository" exactly, which is closer to the property the constitution wants.
+ * It is not used, for one reason worth stating: it requires the caller to construct a security-namespace
+ * token by hand, and a token constructed slightly wrong returns a confident answer about a DIFFERENT
+ * object. Project membership is coarser and readable, and coarser-but-right beats exact-but-fragile on a
+ * gate that decides whether a stranger can spend money.
+ *
+ * The email is never logged or returned; it is personal data with exactly one consumer, like Forgejo's
+ * login and GitLab's username.
+ */
+
+import { fetchFailureReason } from "@edgehero/pi-dispatch/gitlab-identity";
+
+/**
+ * Build the resolver.
+ *
+ * `orgUrl` is `https://dev.azure.com/<org>`; the Graph API lives on a DIFFERENT host
+ * (`https://vssps.dev.azure.com/<org>`), which is derived here rather than asked for, so an operator
+ * configures one URL and cannot get the pair inconsistent.
+ *
+ * Returns `resolveAuthority(projectId, actor)` where `actor` is `{ id }` or `{ email }`.
+ */
+export function makeResolveAzureAuthority({ orgUrl, token, fetchFn = fetch }) {
+	const root = String(orgUrl ?? "").replace(/\/+$/, "");
+	const vssps = root.replace("https://dev.azure.com", "https://vssps.dev.azure.com");
+	// Azure authenticates a PAT as HTTP Basic with an empty username.
+	const auth = `Basic ${Buffer.from(`:${token}`, "utf8").toString("base64")}`;
+
+	async function get(url) {
+		let res;
+		try {
+			res = await fetchFn(url, { headers: { Authorization: auth, accept: "application/json" }, redirect: "error" });
+		} catch (err) {
+			return { indeterminate: fetchFailureReason(err) };
+		}
+		if (!res.ok) {
+			// Status only. An Azure error body can echo the request, and the request carried the token.
+			return { indeterminate: `azure lookup returned ${res.status}` };
+		}
+		try {
+			return { body: await res.json() };
+		} catch (err) {
+			return { indeterminate: `azure lookup returned unparseable JSON: ${err?.message ?? "unknown"}` };
+		}
+	}
+
+	return async function resolveAuthority(projectId, actor) {
+		if (typeof projectId !== "string" || projectId === "") {
+			// The payload named no project, so there is nothing to ask about. Determinate, and refused.
+			return { authorized: false };
+		}
+
+		const descriptor = await resolveDescriptor(actor);
+		if (descriptor.indeterminate) return descriptor;
+		if (descriptor.value === null) return { authorized: false };
+
+		// The project's own scope descriptor -- the container every project member belongs to.
+		const scope = await get(`${vssps}/_apis/graph/descriptors/${encodeURIComponent(projectId)}?api-version=7.1-preview.1`);
+		if (scope.indeterminate) return scope;
+		const container = scope.body?.value;
+		if (typeof container !== "string" || container === "") {
+			// A 200 whose shape we do not recognise is not a refusal: answering `false` here would turn an
+			// upstream schema change into a silent, permanent refusal of every trigger.
+			return { indeterminate: "azure project descriptor lookup returned no descriptor" };
+		}
+
+		// Membership is TRANSITIVE via `direction=up`: a member of a team inside the project is a member of
+		// the project, and asking only for direct membership would refuse most real organisations -- the same
+		// mistake `members/all` avoids on GitLab.
+		const memberships = await get(`${vssps}/_apis/graph/memberships/${encodeURIComponent(descriptor.value)}?direction=up&api-version=7.1-preview.1`);
+		if (memberships.indeterminate) return memberships;
+		const list = memberships.body?.value;
+		if (!Array.isArray(list)) {
+			return { indeterminate: "azure memberships lookup returned no array" };
+		}
+		return { authorized: list.some((m) => m?.containerDescriptor === container) };
+	};
+
+	/** The actor's subject descriptor: by GUID for a pull request, by email for a work item. */
+	async function resolveDescriptor(actor) {
+		if (typeof actor?.id === "string" && actor.id !== "") {
+			const res = await get(`${vssps}/_apis/graph/descriptors/${encodeURIComponent(actor.id)}?api-version=7.1-preview.1`);
+			if (res.indeterminate) return res;
+			const value = res.body?.value;
+			return { value: typeof value === "string" && value !== "" ? value : null };
+		}
+		if (typeof actor?.email === "string" && actor.email !== "") {
+			// There is no lookup-by-email endpoint, so the users list is filtered. `subjectTypes=aad,msa`
+			// excludes groups and service principals, which cannot be the human this gate is about.
+			const res = await get(`${vssps}/_apis/graph/users?subjectTypes=aad,msa&api-version=7.1-preview.1`);
+			if (res.indeterminate) return res;
+			const users = res.body?.value;
+			if (!Array.isArray(users)) return { indeterminate: "azure users lookup returned no array" };
+			const wanted = actor.email.toLowerCase();
+			const hit = users.find((u) => String(u?.principalName ?? "").toLowerCase() === wanted || String(u?.mailAddress ?? "").toLowerCase() === wanted);
+			return { value: typeof hit?.descriptor === "string" ? hit.descriptor : null };
+		}
+		// Neither a GUID nor a parseable address: the delivery named nobody this gate can ask about.
+		return { value: null };
+	}
+}

package/src/azure-subset.mjs

@@ -0,0 +1,166 @@
+/**
+ * Project ONLY the fields the Azure DevOps gate and job are allowed to see (`INT-AZURE-PAYLOAD-SUBSET`).
+ *
+ * The third sibling of `parseSubset` and `parseGitLabSubset`, and the least like either. Where Forgejo's
+ * payload is GitHub's with three differences, Azure's shares almost nothing:
+ *
+ *   1. NO DELIVERY-ID HEADER. Azure sends none at all. The only per-delivery unique value is the body's
+ *      top-level `id`, a GUID. (Issue #43 proposes `notificationId`, which is WRONG: it is a
+ *      per-subscription integer sequence -- 1, 2, 3 -- so two subscriptions collide on delivery 1.)
+ *   2. TWO ACTOR REPRESENTATIONS, inside one forge. A pull-request event carries
+ *      `resource.createdBy.id`, a GUID. A work-item event carries the actor only as the string
+ *      `"Display Name <email>"` in `System.CreatedBy`/`System.ChangedBy`, with no id anywhere. So both the
+ *      author gate and the bot-loop guard need two extractions on one forge -- see `actorOf`.
+ *   3. TAGS ARE A SEMICOLON STRING, not `[{name}]`, and on an update they arrive as a DIFF. The diff is
+ *      the trigger; see `tagChange`.
+ *   4. THE SCOPE IS A TRIPLE. `org/project/repo`, not `owner/repo`.
+ *
+ * Everything else in the delivery is ignored -- including `message`/`detailedMessage`, which are
+ * pre-rendered prose containing the work item's title and are exactly the kind of field that looks
+ * convenient and drags untrusted text into places it was never classified for.
+ */
+
+/** The Service Hook event ids this project consumes. Anything else is an unhandled event. */
+export const WORK_ITEM_EVENTS = new Set(["workitem.created", "workitem.updated", "workitem.commented"]);
+export const PR_EVENTS = new Set(["git.pullrequest.created", "git.pullrequest.updated"]);
+export const PR_COMMENT_EVENT = "ms.vss-code.git-pullrequest-comment-event";
+
+/**
+ * Split Azure's `System.Tags` into the `[{ name }]` shape `predicate.mjs` reads.
+ *
+ * Azure renders tags as one string. Which SEPARATOR spacing it uses has varied (`"a;b"` and `"a; b"` both
+ * occur across versions and resource versions), so every part is trimmed and empties dropped -- a tag list
+ * that silently matched nothing because of a space would look exactly like a trigger nobody armed.
+ */
+export function parseTags(raw) {
+	if (typeof raw !== "string") return [];
+	return raw
+		.split(";")
+		.map((s) => s.trim())
+		.filter((s) => s !== "")
+		.map((name) => ({ name }));
+}
+
+/**
+ * The tag change on a work-item update, as `{ previous, current }`, or `undefined` when this event carries
+ * no tag change at all.
+ *
+ * THE DIFF IS THE TRIGGER, and this is the single most expensive thing to get wrong on this forge. Azure
+ * has no `labeled` event: a tag change arrives as `workitem.updated` with a `fields` map of
+ * `{ oldValue, newValue }` pairs. Matching the CURRENT tag set instead of the change would fire the
+ * trigger again on every later edit of any field on that work item -- a paid run per typo fix, forever.
+ *
+ * `filter-gitlab.mjs` documents this exact trap for GitLab's `changes.labels`, and its `no-label-change`
+ * drop is the existing machinery. Azure is its second customer.
+ */
+export function tagChange(fields) {
+	const entry = fields?.["System.Tags"];
+	if (entry === null || typeof entry !== "object") return undefined;
+	// `oldValue` is absent when the field had no previous value -- a first tag on an untagged work item --
+	// which is a real change and must read as "previously empty", not as "no change".
+	return { previous: parseTags(entry.oldValue), current: parseTags(entry.newValue) };
+}
+
+/**
+ * The actor, in whichever form this event carries one: `{ id }` for a GUID, `{ email }` for a work item's
+ * `"Display Name <email>"` string, or `{}` when neither is present.
+ *
+ * The address is extracted with an ANCHORED trailing `<...>` match and lowercased. The display-name half is
+ * attacker-settable -- a user can call themselves anything -- so a substring test would let
+ * `"pi-bot@example.com is not me <mallory@evil.test>"` read as the harness and defeat the bot-loop guard,
+ * or read as a member and defeat the author gate. Neither is a theoretical concern: both gates compare
+ * against this value.
+ */
+export function actorOf(payload) {
+	const resource = payload?.resource;
+	const guid = resource?.createdBy?.id ?? resource?.comment?.author?.id ?? resource?.pullRequest?.createdBy?.id;
+	if (typeof guid === "string" && guid !== "") return { id: guid };
+
+	const fields = resource?.fields;
+	// On an update, `System.ChangedBy` is a `{ oldValue, newValue }` pair like every other changed field;
+	// on a create it is a bare string. The person who acted is the NEW value.
+	const changedBy = fields?.["System.ChangedBy"];
+	const raw = typeof changedBy === "object" && changedBy !== null ? changedBy.newValue : (changedBy ?? fields?.["System.CreatedBy"]);
+	const email = extractEmail(raw);
+	return email === null ? {} : { email };
+}
+
+/** The address inside a trailing `<...>`, lowercased, or `null`. Anchored -- see `actorOf`. */
+export function extractEmail(raw) {
+	if (typeof raw !== "string") return null;
+	const match = raw.trim().match(/<([^<>]+)>$/);
+	if (match) return match[1].trim().toLowerCase();
+	// A bare address with no display name is also legal, and is accepted only when the WHOLE string is one.
+	const bare = raw.trim();
+	return /^[^\s<>@]+@[^\s<>@]+$/.test(bare) ? bare.toLowerCase() : null;
+}
+
+/**
+ * The field value for a work item, unwrapping the `{ oldValue, newValue }` shape an update uses. A create
+ * carries bare values; an update carries pairs for the fields that changed and nothing for the rest.
+ */
+function fieldValue(fields, name) {
+	const v = fields?.[name];
+	return typeof v === "object" && v !== null ? v.newValue : v;
+}
+
+export function parseAzureSubset(payload) {
+	const eventType = payload?.eventType;
+	const resource = payload?.resource ?? {};
+	const containers = payload?.resourceContainers ?? {};
+
+	if (WORK_ITEM_EVENTS.has(eventType)) {
+		const fields = resource.fields ?? {};
+		// `resource.revision.fields` carries the full post-change state on an update, where `resource.fields`
+		// carries only the diff. Read the full state for the CURRENT tag set, and the diff separately for
+		// whether tags changed at all -- conflating the two is how the diff-not-set trap gets reintroduced.
+		const full = resource.revision?.fields ?? fields;
+		return {
+			eventType,
+			id: payload?.id,
+			actor: actorOf(payload),
+			project: { id: containers.project?.id, name: fieldValue(fields, "System.TeamProject") ?? fieldValue(full, "System.TeamProject") },
+			// `resource.workItemId` on a comment event, `resource.id` on create/update. Work item ids are
+			// ORGANIZATION-scoped on Azure DevOps, which is why the dedup key namespaces them on the org
+			// rather than on the repository.
+			target: {
+				number: resource.workItemId ?? resource.id,
+				title: fieldValue(full, "System.Title"),
+				// System.Description is a rich-text (HTML) field on most work item types. It stays DATA either
+				// way -- it is fenced below the delimiter like every other payload string -- but a reader of
+				// the envelope should not be surprised to find markup there.
+				body: fieldValue(full, "System.Description"),
+			},
+			tags: parseTags(fieldValue(full, "System.Tags")),
+			tagChanges: tagChange(fields),
+			// `System.History` is where a work-item comment's text arrives.
+			comment: eventType === "workitem.commented" ? fieldValue(fields, "System.History") : undefined,
+		};
+	}
+
+	const isPrComment = eventType === PR_COMMENT_EVENT;
+	const pr = isPrComment ? (resource.pullRequest ?? {}) : resource;
+	const repository = pr.repository ?? resource.repository ?? {};
+	return {
+		eventType,
+		id: payload?.id,
+		actor: actorOf(payload),
+		project: { id: containers.project?.id ?? repository.project?.id, name: repository.project?.name },
+		repository: { id: repository.id, name: repository.name },
+		target: {
+			number: pr.pullRequestId,
+			title: pr.title,
+			body: pr.description,
+			// Azure refs are fully qualified (`refs/heads/main`). They are attacker-controlled DATA,
+			// projected for the flow's event.json and NEVER used as a clone ref.
+			head: { ref: stripRefsHeads(pr.sourceRefName) },
+			base: { ref: stripRefsHeads(pr.targetRefName) },
+		},
+		comment: isPrComment ? resource.comment?.content : undefined,
+	};
+}
+
+/** `refs/heads/main` -> `main`. Azure qualifies its refs; the rest of this codebase does not. */
+export function stripRefsHeads(ref) {
+	return typeof ref === "string" ? ref.replace(/^refs\/heads\//, "") : undefined;
+}

package/src/cli.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * The receiver's own bin (issue #80). Before it, the only start command in the repo lived inside
+ * deploy/receiver.service -- an operator without systemd had nothing documented to type.
+ *
+ * It is a separate bin rather than a `receiver` case in the worker CLI because the dependency points
+ * the other way: the receiver depends on `@edgehero/pi-dispatch` (queue, config, the shared triggers
+ * schema), so teaching the worker CLI to start the receiver would invert that into a circular
+ * workspace dependency. And the receiver is the always-on public trigger surface that lives OUTSIDE
+ * pi (DES-TRIGGER-OUTSIDE-PI) -- the edge deserves its own entry point, not a mode of the thing it
+ * feeds.
+ *
+ * Thin by design, mirroring worker/src/cli.mjs: recognise the command, lazy-import the real work.
+ */
+
+import { EXIT_POLICY } from "@edgehero/pi-dispatch/exit-code";
+
+const USAGE = `pi-dispatch-receiver — the always-on trigger edge: turns GitHub activity into queued jobs
+
+  pi-dispatch-receiver serve   start the webhook receiver (the default when no command is given)
+  pi-dispatch-receiver poll    start the polling producer — no public URL, no DNS, no tunnel: it
+                               reads api.github.com with the operator's own credential instead
+
+Config comes from the environment (see .env.example): WEBHOOK_SECRET is required for serve
+(poll needs none — there is no inbound delivery to verify), PI_TRIGGERS_FILE overrides the
+./triggers.json default, VALKEY_URL names the queue, RECEIVER_PORT/RECEIVER_BIND choose where
+serve listens, and POLL_REPOS / POLL_INTERVAL_SECONDS shape what poll watches and how often.`;
+
+/**
+ * `start`/`startPoll` are injection seams defaulting to the lazy imports of ./start.mjs and
+ * ./poller.mjs, so tests can run the command dispatch without resolving identity, opening a socket,
+ * or touching Valkey -- and the help/unknown paths stay runnable even where the queue deps are not
+ * installed.
+ */
+export async function main(argv = process.argv.slice(2), env = process.env, { start, startPoll } = {}) {
+	const cmd = argv[0];
+
+	if (cmd === undefined || cmd === "serve") {
+		const startReceiver = start ?? (await import("./start.mjs")).startReceiver;
+		await startReceiver(env);
+		return 0; // the server keeps the process alive until SIGTERM
+	}
+
+	if (cmd === "poll") {
+		// The polling producer (issue #81): the same gate and the same queue as serve, fed by reading
+		// api.github.com instead of by being reachable from it. Awaiting `done` is what keeps the
+		// process alive -- unlike serve there is no listening socket holding the loop open, only the
+		// loop itself, and returning early would let the bin exit under a healthy poller.
+		const startPoller = startPoll ?? (await import("./poller.mjs")).startPoller;
+		const poller = await startPoller(env);
+		await poller?.done;
+		return 0;
+	}
+
+	process.stdout.write(`${USAGE}\n`);
+	return cmd === "--help" || cmd === "-h" ? 0 : 1; // asked-for help is success; a typo is not
+}
+
+/**
+ * Exit code for an error that escaped main() as a rejection. A tagged config error
+ * (`piDispatchConfig`, from loadReceiverConfig or the HARD-FAIL identity boot gate) is a determinate
+ * refusal -> EXIT_POLICY (2, never retried); anything else is infra -> 1 (retryable). The same
+ * mapping as the worker CLI's entryExitCode, for the same reason: a supervisor restarting on exit 2
+ * would loop on a config that can never parse.
+ */
+export function entryExitCode(err) {
+	return err?.piDispatchConfig ? EXIT_POLICY : 1;
+}
+
+// Entry point when run as a bin. Kept out of the exported main so tests can call main() directly.
+// The error line mirrors start.mjs's own entry guard: `err.message` only -- never a secret or PII.
+// (start.mjs's guard keys on argv[1] ending in start.mjs, so importing it from here never double-boots.)
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("cli.mjs")) {
+	main()
+		.then((code) => {
+			if (code) process.exitCode = code;
+		})
+		.catch((err) => {
+			process.stderr.write(`${JSON.stringify({ event: "receiver_start_failed", reason: err?.message })}\n`);
+			process.exitCode = entryExitCode(err);
+		});
+}