@edgehero/pi-dispatch-receiver 0.1.0

package/src/filter-forgejo.mjs

@@ -0,0 +1,206 @@
+/**
+ * The Forgejo/Gitea trigger gate. Pure, total, and offline-testable: this module imports nothing
+ * side-effecting, does no I/O and never throws, so the security-critical decision can be exercised
+ * without a server, a socket, or a queue.
+ *
+ * The evaluation ORDER is fail-closed and load-bearing, and is the same order both other gates use:
+ *   0. A non-numeric `sender.id` is rejected FIRST. It must precede the `=== selfId` compare, because
+ *      `undefined === selfId` is `false` and would fall through to enqueue -- failing OPEN on a malformed
+ *      payload. Missing identity is a reject, never a pass.
+ *   1. The bot-loop guard runs UNCONDITIONALLY, before any authority or label check. Under a hand-minted
+ *      Forgejo token the harness IS a repository collaborator and would clear the gate, so a status
+ *      comment it posts -- or its own push to a PR head, which fires `synchronized` -- is an event that
+ *      passes: an unbounded paid recursion. Gating this drop behind the authority check reintroduces it.
+ *   2. The authority gate, for EVERY trigger type.
+ *   3. Only then route on event + action.
+ *
+ * WHY THE AUTHORITY GATE COVERS LABELS TOO, unlike GitHub's. On GitHub the label path needs no author
+ * check because applying a label already required write access, so the label IS the approval. That is very
+ * probably true on Forgejo as well -- issue #61 argues it, and Forgejo's permission model agrees on
+ * inspection. It is not, however, something this project has verified against a running instance across
+ * versions, and the cost of being wrong is a stranger starting paid jobs. So the gate does not rest on it:
+ * `authorized` is required for every trigger type, and if the label really is self-gating then this check
+ * is redundant rather than wrong. That is the cheaper direction to be wrong in.
+ *
+ * `authorized` is resolved by the receiver BEFORE this function (forgejo-members.mjs) and passed in,
+ * occupying the slot `author_association` holds on the GitHub side: the lookup is a network call, and
+ * putting a fetch inside the gate would destroy the purity that makes it testable.
+ *
+ * ACTIONS ARRIVE IN FORGEJO'S OWN WORDS and are mapped explicitly (forgejo-subset.mjs). A recognised
+ * action that is not actionable drops under its OWN reason rather than as `unhandled-event`, so an
+ * operator whose trigger never fires can tell "Forgejo said something we deliberately ignore" from "we did
+ * not recognise this at all". `label_cleared` is the case that matters: removing a label must never start
+ * a paid run, and it must be visible that it was seen and refused.
+ */
+
+import { escapeRegExp, firstMatchingRule, labelSet, matchedLabel, matchesRule } from "./predicate.mjs";
+import { isRecognizedAction, mapAction } from "./forgejo-subset.mjs";
+
+const LABEL_ACTIONS = new Set(["opened", "labeled", "reopened"]);
+const PR_ACTIONS = new Set(["labeled", "opened", "synchronize", "reopened"]);
+
+/**
+ * Decide. Returns `{ enqueue: false, reason }` or `{ enqueue: true, job }`.
+ *
+ * `subset` is a `parseForgejoSubset` projection; `triggers` is the forgejo rule group; `knownFlows` is the
+ * whole file's flow vocabulary; `authorized` is the receiver's resolved verdict; `deliveryId` is the
+ * `X-GitHub-Delivery` GUID, which Forgejo emits and keeps stable across its own retries.
+ */
+export function filterForgejo(eventName, subset, triggers, knownFlows, selfId, authorized, deliveryId) {
+	// (0) Fail-closed on identity. MUST precede the self compare -- see header.
+	if (typeof subset?.sender?.id !== "number") {
+		return { enqueue: false, reason: "missing-sender-id" };
+	}
+
+	// (1) Bot-loop guard: unconditional, independent of the authority outcome below.
+	if (subset.sender.id === selfId) {
+		return { enqueue: false, reason: "self" };
+	}
+
+	// (2) The authority gate, for EVERY trigger type. Strict `!== true` so anything that is not an explicit
+	// yes -- undefined, a stray truthy value, a resolver that returned the wrong shape -- refuses.
+	if (authorized !== true) {
+		return { enqueue: false, reason: "author-not-allowed" };
+	}
+
+	// (3) Map Forgejo's action word, then route. The mapping is what stops `label_updated` and
+	// `synchronized` -- one letter from GitHub's words -- from falling out as unrecognised.
+	const raw = subset.action;
+	const group = triggers ?? {};
+	// Recognised and deliberately ignored, versus never heard of. Two reasons, because they call for two
+	// different operator responses: one is "that is not a trigger", the other is "check your action
+	// vocabulary against your forge's".
+	const unactionable = () => ({ enqueue: false, reason: isRecognizedAction(raw) ? "action-not-actionable" : "unhandled-event" });
+	let resolved;
+
+	if (eventName === "issue_comment") {
+		// Deliberately OUTSIDE the action map. A comment's `created` is the same word on Forgejo as on
+		// GitHub, and a comment carries no label semantics to translate -- mapping it would only create a
+		// place for it to fall through.
+		if (raw !== "created") return unactionable();
+		resolved = routeComment(subset, group, knownFlows);
+	} else {
+		const action = mapAction(eventName, raw);
+		if (action === null) return unactionable();
+		if (eventName === "issues" && LABEL_ACTIONS.has(action)) {
+			resolved = routeIssueLabel(subset, group);
+		} else if (eventName === "pull_request" && PR_ACTIONS.has(action)) {
+			// The RAW word, not the mapped one. A trigger file names actions in the forge's own vocabulary
+			// (`label_updated`, `synchronized`) because that is what an operator reads in Forgejo's docs and
+			// what the loader validates against -- so the rule match has to be against the same words. The
+			// mapped action decided WHICH route; it must not also decide which rule.
+			resolved = routePullRequest(subset, group, raw);
+		} else {
+			return { enqueue: false, reason: "unhandled-event" };
+		}
+	}
+
+	if (!resolved.enqueue) return resolved; // carries the drop reason
+
+	// The job literal mirrors the other two forges' exactly -- `repo`, `target`, `flow`, the three
+	// conditional execution knobs, and a descriptive `trigger`. `sender.login` is in the subset but is NOT
+	// carried here: it exists for the permission lookup and nowhere else, and this object is copied verbatim
+	// into /job/event.json, which must stay free of personal data.
+	const job = {
+		repo: subset.repository?.full_name,
+		target: resolved.target,
+		flow: resolved.flow,
+		...(resolved.packages !== undefined ? { packages: resolved.packages } : {}),
+		...(resolved.image !== undefined ? { image: resolved.image } : {}),
+		...(resolved.resume !== undefined ? { resume: resolved.resume } : {}),
+		trigger: {
+			event: eventName,
+			// Forgejo's OWN word, not our translation of it. The run record should say what the forge said.
+			action: raw,
+			deliveryId,
+			sender: { id: subset.sender.id },
+			matched: resolved.matched,
+			...(resolved.comment ? { comment: resolved.comment } : {}),
+		},
+	};
+	return { enqueue: true, job };
+}
+
+/** Issue label path: the label predicate selects, and the resolved permission has already gated. */
+function routeIssueLabel(subset, triggers) {
+	const L = labelSet(subset.issue?.labels);
+	const rule = firstMatchingRule(triggers.label, L);
+	if (rule === undefined) {
+		return { enqueue: false, reason: "no-allowlisted-label" };
+	}
+	return {
+		enqueue: true,
+		flow: rule.flow,
+		packages: rule.packages, // the MATCHED rule's fields -- rules in one file may differ on them
+		image: rule.image,
+		resume: rule.resume,
+		matched: { index: rule.index, type: "label", label: matchedLabel(L, rule.predicate) },
+		target: { type: "issue", number: subset.issue?.number, title: subset.issue?.title, body: subset.issue?.body },
+	};
+}
+
+/** Comment path. The authority gate above has already run, so this only has to match the phrase. */
+function routeComment(subset, triggers, knownFlows) {
+	const phrase = triggers.comment?.phrase;
+	const body = subset.comment?.body;
+	if (typeof phrase !== "string" || typeof body !== "string" || !body.includes(phrase)) {
+		return { enqueue: false, reason: "no-trigger-phrase" };
+	}
+	// Default to the configured flow; an explicit `<phrase> <flow>` overrides only when `<flow>` is a known
+	// flow name, so a comment cannot summon an unlisted flow.
+	let flow = triggers.comment?.defaultFlow;
+	const match = body.match(new RegExp(escapeRegExp(phrase) + "\\s+(\\S+)"));
+	if (match && knownFlows?.has(match[1])) {
+		flow = match[1];
+	}
+	if (flow === null || flow === undefined || flow === "") {
+		return { enqueue: false, reason: "no-flow" };
+	}
+	// `is_pull` is TOP-LEVEL on Forgejo, where GitHub carries `issue.pull_request`. Reading the wrong one
+	// routes every pull-request comment as an issue, and the envelope then tells the agent to open
+	// `pi/issue-<n>` for something that is already a pull request: wrong work, no error, and a run that
+	// looks successful. The issue number IS the PR number here, exactly as on GitHub.
+	const isPR = subset.isPull === true;
+	return {
+		enqueue: true,
+		flow,
+		packages: triggers.comment.packages,
+		image: triggers.comment.image,
+		resume: triggers.comment.resume,
+		matched: { index: triggers.comment.index, type: "comment", phrase },
+		// The invoking comment rides on the trigger. No author_association: Forgejo has none, and the
+		// authority that admitted this comment was resolved from the API, not read off the body.
+		comment: { body: subset.comment.body },
+		target: { type: isPR ? "pull_request" : "issue", number: subset.issue?.number, title: subset.issue?.title, body: subset.issue?.body },
+	};
+}
+
+/** Pull-request path. `action` is Forgejo's OWN word, matching the vocabulary the loader validated. */
+function routePullRequest(subset, triggers, action) {
+	const pr = subset.pull_request;
+	if (!pr) {
+		return { enqueue: false, reason: "missing-pull-request" };
+	}
+	const L = labelSet(pr.labels);
+	for (const rule of triggers.pullRequest ?? []) {
+		if (!rule.actions.has(action)) continue;
+		if (rule.predicate && !matchesRule(L, rule.predicate)) continue;
+		return {
+			enqueue: true,
+			flow: rule.flow,
+			packages: rule.packages,
+			image: rule.image,
+			resume: rule.resume,
+			matched: { index: rule.index, type: "pull_request", action },
+			target: {
+				type: "pull_request",
+				number: pr.number,
+				title: pr.title,
+				body: pr.body,
+				head: pr.head,
+				base: pr.base,
+			},
+		};
+	}
+	return { enqueue: false, reason: "no-matching-pr-trigger" };
+}

package/src/filter-gitlab.mjs

@@ -0,0 +1,252 @@
+/**
+ * The GitLab trigger gate: decide whether a verified GitLab webhook becomes a paid agent job, and with
+ * what shape. The counterpart of filter.mjs, and pure for the same reason -- imports nothing side-effecting,
+ * touches no I/O, and NEVER throws -- so the security-critical decision is unit testable offline, without a
+ * server, a socket, or a GitLab.
+ *
+ * The evaluation ORDER is fail-closed and load-bearing, mirroring filter.mjs:
+ *   0. A non-numeric `user.id` is rejected FIRST, before the self compare -- `undefined === selfId` is
+ *      false and would fall through to enqueue, failing OPEN on a malformed payload.
+ *   1. The bot-loop guard runs UNCONDITIONALLY. Under a project access token the harness is a project
+ *      member and would clear the access gate, so its own status comment is an event that passes -- an
+ *      unbounded paid recursion. Gating this behind the access check would reintroduce exactly that loop.
+ *   2. THEN the access gate, then the route.
+ *
+ * WHY THE ACCESS GATE COVERS LABEL TRIGGERS TOO, unlike GitHub.
+ *
+ * `CONST-TRIGGER-AUTHOR-GATE` rests on "only collaborators can apply labels -- therefore the label IS the
+ * human approval step". On GitLab that premise does not hold, in three independent ways: the minimum role
+ * for label management has differed across versions, Ultimate's custom roles let an operator grant it at
+ * any level, and a Guest can set labels on an issue AT CREATION -- so a stranger can open an issue already
+ * carrying the trigger label. A label therefore proves nothing here on its own, and every gitlab trigger
+ * is gated on the actor's resolved authority regardless of type. That verdict is produced by the receiver
+ * BEFORE this function (gitlab-members.mjs) and passed in, occupying the slot `author_association` holds
+ * on the GitHub side: the lookup is a network call, and putting a fetch inside the gate would destroy the
+ * purity that makes the gate testable.
+ *
+ * What crosses that boundary is a BOOLEAN, not GitLab's role integer. Every forge answers "may this actor
+ * start a job" in its own vocabulary -- an integer role here, a string enum on Forgejo, a payload field on
+ * GitHub, a group membership on Azure DevOps -- and only the answer is common. The `>= 30` threshold lives
+ * with the lookup that produces the number; this file owns what to DO about the verdict, which is the part
+ * that has to be the same everywhere.
+ *
+ * WHY A LABEL RULE MATCHES THE DIFF AND NOT THE LABEL SET.
+ *
+ * GitLab has no `labeled` action. Adding a label arrives as `action: "update"` carrying
+ * `changes.labels: { previous, current }`. Matching the CURRENT set -- the shape the GitHub path uses --
+ * would re-fire on every subsequent edit of that issue, because the label is still there: retitle it,
+ * reassign it, change its milestone, and each one starts another paid run. So the label set a rule is
+ * tested against is `current \ previous`, the labels THIS event added, and an `update` carrying no
+ * `changes.labels` matches nothing.
+ */
+
+import { firstMatchingRule, labelSet, matchedLabel } from "./predicate.mjs";
+
+/**
+/** The merge-request actions a trigger may name, mirrored from the loader's gitlab vocabulary. */
+const MR_ACTIONS = new Set(["open", "update", "reopen", "approved"]);
+
+/**
+ * Decide. Returns `{ enqueue: false, reason }` or `{ enqueue: true, job }`.
+ *
+ * `subset` is a `parseGitLabSubset` projection; `triggers` is the gitlab rule group; `authorized` is the
+ * receiver's resolved verdict for this actor; `deliveryId` is the stable `webhook-id`, carried into the job
+ * for dedup.
+ */
+export function filterGitLab(subset, triggers, knownFlows, selfId, authorized, deliveryId) {
+	// (0) Fail-closed on identity. MUST precede the self compare -- see header.
+	if (typeof subset?.user?.id !== "number") {
+		return { enqueue: false, reason: "missing-sender-id" };
+	}
+
+	// (1) Bot-loop guard: unconditional, independent of the access outcome below.
+	if (subset.user.id === selfId) {
+		return { enqueue: false, reason: "self" };
+	}
+
+	// (2) The access gate, for EVERY trigger type. See the header for why a label does not substitute.
+	// Strict `!== true`, so anything that is not an explicit yes -- undefined, a stray truthy value, a
+	// resolver that returned the wrong shape -- refuses rather than passes.
+	if (authorized !== true) {
+		return { enqueue: false, reason: "author-not-allowed" };
+	}
+
+	// (3) Route on the object kind.
+	const kind = subset.objectKind;
+	let resolved;
+	if (kind === "issue") {
+		resolved = routeLabel(subset, triggers, "issue");
+	} else if (kind === "merge_request") {
+		resolved = routeMergeRequest(subset, triggers);
+	} else if (kind === "note") {
+		resolved = routeNote(subset, triggers, knownFlows);
+	} else {
+		return { enqueue: false, reason: "unhandled-event" };
+	}
+
+	if (!resolved.enqueue) return resolved; // carries the drop reason
+
+	// (4) Build the job from the INT-GITLAB-PAYLOAD-SUBSET fields only. `user.username` is deliberately
+	// NOT carried: it exists so the receiver could resolve an access level, and it is personal data with no
+	// downstream reader (no-pii-in-logs). `projectId` rides the job because every GitLab API path the
+	// worker needs takes the numeric id -- a `group/subgroup/project` path has no fixed segment count, and
+	// splitting one is how a nested project silently becomes its own parent group.
+	const job = {
+		repo: subset.project?.path,
+		projectId: subset.project?.id,
+		target: resolved.target,
+		flow: resolved.flow,
+		...(resolved.packages !== undefined ? { packages: resolved.packages } : {}),
+		...(resolved.image !== undefined ? { image: resolved.image } : {}),
+		// Conditional like packages/image, and for the same reason: an unflagged job's data must stay
+		// byte-identical to today's, so the key is absent rather than present-and-undefined.
+		...(resolved.resume !== undefined ? { resume: resolved.resume } : {}),
+		trigger: {
+			event: kind,
+			action: subset.action,
+			deliveryId,
+			sender: { id: subset.user.id },
+			matched: resolved.matched,
+			...(resolved.comment ? { comment: resolved.comment } : {}),
+		},
+	};
+	return { enqueue: true, job };
+}
+
+/**
+ * Issue path. Fires on the labels THIS event added, never on the labels the issue happens to carry.
+ *
+ * `open` is included because an issue can be created with labels already on it, and that is a real
+ * trigger -- but only because the access gate above has already established the creator is a member. On
+ * GitHub the same case is safe for a different reason (only collaborators can apply labels at all).
+ */
+function routeLabel(subset, triggers, targetType) {
+	const added = addedLabels(subset);
+	if (added === null) return { enqueue: false, reason: "no-label-change" };
+
+	const rule = firstMatchingRule(triggers?.label, added);
+	if (!rule) return { enqueue: false, reason: "no-allowlisted-label" };
+	return {
+		enqueue: true,
+		flow: rule.flow,
+		packages: rule.packages,
+		image: rule.image,
+		resume: rule.resume,
+		matched: { index: rule.index, type: "label", label: matchedLabel(added, rule.predicate) },
+		target: buildTarget(subset, targetType),
+	};
+}
+
+/**
+ * The label set an event ADDED, or `null` when it added none.
+ *
+ * `open` is the one case where there is no diff and the whole set is the addition: the issue did not
+ * exist before, so every label on it arrived with it. Every other action needs `changes.labels`, and its
+ * absence means no label moved -- which is precisely the case that must not re-fire.
+ */
+function addedLabels(subset) {
+	if (subset.action === "open") {
+		const L = labelSet(subset.target?.labels);
+		return L.size > 0 ? L : null;
+	}
+	const changes = subset.labelChanges;
+	if (!changes) return null;
+	const previous = labelSet(changes.previous);
+	const added = new Set();
+	for (const name of labelSet(changes.current)) {
+		if (!previous.has(name)) added.add(name);
+	}
+	return added.size > 0 ? added : null;
+}
+
+/**
+ * Merge-request path. A rule carrying a positive selector is label-gated and matches the added labels
+ * exactly as an issue rule does; a rule without one fires on its named actions alone -- which is safe here
+ * only because the access gate already ran, and is why the loader does not demand a positive selector on
+ * a gitlab MR rule the way it does on a github `labeled` one.
+ */
+function routeMergeRequest(subset, triggers) {
+	const action = subset.action;
+	if (!MR_ACTIONS.has(action)) return { enqueue: false, reason: "unhandled-event" };
+
+	const added = addedLabels(subset);
+	for (const rule of triggers?.pullRequest ?? []) {
+		if (!rule.actions.has(action)) continue;
+		const positive = (rule.predicate?.any?.length ?? 0) + (rule.predicate?.all?.length ?? 0) > 0;
+		if (positive) {
+			if (added === null || !firstMatchingRule([rule], added)) continue;
+			return mrResult(subset, rule, { index: rule.index, type: "label", label: matchedLabel(added, rule.predicate) });
+		}
+		return mrResult(subset, rule, { index: rule.index, type: "pull_request", action });
+	}
+	return { enqueue: false, reason: "no-matching-pr-trigger" };
+}
+
+function mrResult(subset, rule, matched) {
+	return {
+		enqueue: true,
+		flow: rule.flow,
+		packages: rule.packages,
+		image: rule.image,
+		resume: rule.resume,
+		matched,
+		target: buildTarget(subset, "pull_request"),
+	};
+}
+
+/**
+ * Note (comment) path. `noteable_type` states whether the comment is on an issue or a merge request --
+ * GitHub infers the same thing from the presence of `issue.pull_request`. Routing it wrong would mint an
+ * issue branch for something that is already a merge request: wrong work, no error, and it looks like a
+ * successful run.
+ */
+function routeNote(subset, triggers, knownFlows) {
+	if (subset.action !== "create") return { enqueue: false, reason: "unhandled-event" };
+
+	const phrase = triggers?.comment?.phrase;
+	const body = subset.note;
+	if (typeof phrase !== "string" || typeof body !== "string" || !body.includes(phrase)) {
+		return { enqueue: false, reason: "no-trigger-phrase" };
+	}
+	// Default to the configured flow; an explicit `<phrase> <flow>` overrides only when `<flow>` is a
+	// known flow name, so a comment cannot summon an unlisted flow.
+	let flow = triggers.comment?.defaultFlow;
+	const match = body.match(new RegExp(escapeLiteral(phrase) + "\\s+(\\S+)"));
+	if (match && knownFlows?.has(match[1])) flow = match[1];
+	if (flow === null || flow === undefined || flow === "") {
+		return { enqueue: false, reason: "no-flow" };
+	}
+	const targetType = subset.noteableType === "MergeRequest" ? "pull_request" : "issue";
+	return {
+		enqueue: true,
+		flow,
+		packages: triggers.comment.packages,
+		image: triggers.comment.image,
+		resume: triggers.comment.resume,
+		matched: { index: triggers.comment.index, type: "comment", phrase },
+		target: buildTarget(subset, targetType),
+		// The invoking comment rides the job as DATA (CONST-ISSUE-TEXT-IS-DATA). No author_association
+		// counterpart exists on GitLab: the approval is the resolved access level, which is a harness
+		// decision and belongs in `matched`, not in a field that looks like payload.
+		comment: { body },
+	};
+}
+
+/** Escape a literal for embedding in a RegExp -- the trigger phrase is config, not a pattern. */
+function escapeLiteral(literal) {
+	return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * The job's target. `iid` is the per-project number a human sees and an API path takes; `id` would be a
+ * global key naming somebody else's issue. `type` uses the SHARED vocabulary (`issue` / `pull_request`)
+ * rather than GitLab's nouns, because it discriminates a job shape the worker already understands.
+ */
+function buildTarget(subset, type) {
+	return {
+		type,
+		number: subset.target?.iid,
+		title: subset.target?.title,
+		body: subset.target?.description,
+	};
+}