@edgehero/pi-dispatch-receiver 0.1.0

package/src/filter.mjs

@@ -0,0 +1,224 @@
+/**
+ * The trigger gate: decide whether a verified webhook becomes a paid agent job, and if so with what
+ * shape. This is CONST-TRIGGER-AUTHOR-GATE made executable -- the independent controls it names (label
+ * allowlist, comment author_association, pull_request author gate, bot-loop guard) plus the
+ * INT-WEBHOOK-PAYLOAD-SUBSET extraction that keeps the job carrying only the named fields.
+ *
+ * Pure and total: imports nothing, touches no I/O, and NEVER throws. A rejected event returns
+ * `{ enqueue: false, reason }`; an accepted one returns `{ enqueue: true, job }`. Purity is the point --
+ * the whole gate is decidable offline from its inputs, so the security-critical decision is unit testable
+ * without a server, a socket, or a queue.
+ *
+ * The evaluation ORDER is fail-closed and load-bearing:
+ *   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 (`sender.id === selfId`) runs UNCONDITIONALLY, before any author/label check.
+ *      Under a PAT the harness is repo OWNER and would clear the author gate, so a completion comment the
+ *      harness posts -- or the flow's own push to a PR head, which fires `pull_request.synchronize` -- is
+ *      an event that passes the gate: an unbounded paid recursion. Gating this drop behind the author
+ *      check would reintroduce exactly that loop.
+ *   2. Only then route on event + action: issue label, author-gated comment, or pull_request.
+ *
+ * PR AUTHOR GATE (security-critical): auto actions (`opened|synchronize|reopened`) fire ONLY when the PR
+ * `author_association` is a collaborator. This is hard-coded here, never config-optional -- a fork PR from
+ * a stranger would otherwise launch an unbounded paid run (CONST-TRIGGER-AUTHOR-GATE, job-budget rules).
+ * PR labeling is self-gating: only collaborators can apply labels, so the label predicate IS the approval,
+ * exactly as on the issue label path.
+ *
+ * `selfId` is the numeric id of whichever identity posts as the harness (the App's bot user, or the PAT
+ * user); `deliveryId` is the `X-GitHub-Delivery` GUID, carried into the job for downstream dedup.
+ */
+import { escapeRegExp, firstMatchingRule, labelSet, matchedLabel, matchesRule } from "./predicate.mjs";
+
+const AUTHOR_ALLOWLIST = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
+const LABEL_ACTIONS = new Set(["opened", "labeled", "reopened"]);
+const PR_ACTIONS = new Set(["labeled", "opened", "synchronize", "reopened"]);
+const PR_AUTO_ACTIONS = new Set(["opened", "synchronize", "reopened"]);
+
+export function filter(eventName, subset, cfg, selfId, deliveryId) {
+	// (0) Fail-closed on identity. MUST precede the self compare -- see header, ordering constraint.
+	if (typeof subset?.sender?.id !== "number") {
+		return { enqueue: false, reason: "missing-sender-id" };
+	}
+
+	// (1) Bot-loop guard: unconditional, independent of the author/label outcome below.
+	if (subset.sender.id === selfId) {
+		return { enqueue: false, reason: "self" };
+	}
+
+	// (2) Route on event + action -> resolve { flow, target } or a drop reason.
+	// Only the GITHUB rule group is ever read here: rules are grouped per forge at load
+	// (receiver/src/config.mjs), so a rule an operator wrote for another forge is not merely unmatched,
+	// it is unreachable from this gate.
+	const action = subset.action;
+	const triggers = cfg?.triggers?.github ?? {};
+	let resolved;
+
+	if (eventName === "issues" && LABEL_ACTIONS.has(action)) {
+		resolved = routeIssueLabel(subset, triggers);
+	} else if (eventName === "issue_comment" && action === "created") {
+		resolved = routeComment(subset, triggers, cfg?.triggers?.knownFlows);
+	} else if (eventName === "pull_request" && PR_ACTIONS.has(action)) {
+		resolved = routePullRequest(subset, triggers, action);
+	} else {
+		return { enqueue: false, reason: "unhandled-event" };
+	}
+
+	if (!resolved.enqueue) return resolved; // carries the drop reason
+
+	// (3) Build the job from the INT-WEBHOOK-PAYLOAD-SUBSET fields only. No sender.login (not in the
+	// subset), no provider/model/maxTurns (the worker fills defaults), no field outside the subset --
+	// with two trigger-context additions (issue #49): `matched` is harness-computed, the filter's own
+	// decision record naming the triggers.json entry that fired (not payload data at all); `comment`,
+	// present only on the comment route, carries the invoking comment's body/author_association, both
+	// fields INT-WEBHOOK-PAYLOAD-SUBSET already names.
+	//
+	// `packages` and `image` are harness-computed EXECUTION knobs read off the matched triggers.json entry
+	// (like `matched`), never payload data -- REQ-GLOBAL-PI-OVERLAY's per-trigger control over loading the
+	// operator-staged pi packages, and INT-TRIGGERS-FILE-CONTRACT's per-trigger container image. Both sit at
+	// JOB level, NOT inside `trigger`: `trigger` is the descriptive context object carried verbatim into
+	// /job/event.json (INT-CONTAINER-JOB-INPUTS) and must stay descriptive, so an execution switch has no
+	// business there. Both are omitted entirely when the matched rule did not set them, so an unflagged
+	// trigger's job literal is byte-identical to today's.
+	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 } : {}),
+		// 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 } : {}),
+		// How many independent sandboxes race this flow (REQ-REPLICA-RUNS). At JOB level like the rest, never
+		// inside `trigger`, and for the sharpest version of that reason: this is the caller's fanout count --
+		// receiver.mjs reads it to decide how many times to enqueue -- and a descriptive context object copied
+		// into /job/event.json is no place for the number of jobs to create.
+		...(resolved.replicas !== undefined ? { replicas: resolved.replicas } : {}),
+		trigger: {
+			event: eventName,
+			action,
+			deliveryId,
+			sender: { id: subset.sender.id },
+			matched: resolved.matched,
+			...(resolved.comment ? { comment: resolved.comment } : {}),
+		},
+	};
+	return { enqueue: true, job };
+}
+
+/** Issue label path: the label allowlist IS the human approval gate -- only collaborators can label. */
+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,
+		replicas: rule.replicas,
+		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: author_association is the approval gate (no label event to carry it).
+ *
+ * `knownFlows` is passed separately because it is NOT a per-forge rule -- it is the whole file's flow
+ * vocabulary, and it bounds which names a comment may summon rather than which rules may match.
+ */
+function routeComment(subset, triggers, knownFlows) {
+	if (!AUTHOR_ALLOWLIST.has(subset.comment?.author_association)) {
+		return { enqueue: false, reason: "author-not-allowed" };
+	}
+	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" };
+	}
+	// An issue_comment on a PR carries issue.pull_request; its issue.number IS the PR number and the
+	// issue title/body are the PR's. Route it as a pull_request target so the flow gets PR context and
+	// does not mint a fresh pi/issue-<n> branch. head/base are absent here (not in the comment payload);
+	// the flow resolves them from the number via `gh`.
+	const isPR = subset.issue?.pull_request === true;
+	return {
+		enqueue: true,
+		flow,
+		// The single comment trigger IS the matched rule here, so its opt-in is the job's. A `<phrase>
+		// <flow>` override changes WHICH flow runs, never which triggers.json entry authorized it.
+		packages: triggers.comment.packages,
+		image: triggers.comment.image,
+		resume: triggers.comment.resume,
+		replicas: triggers.comment.replicas,
+		matched: { index: triggers.comment.index, type: "comment", phrase },
+		// The invoking comment rides on the trigger: body and author_association are both named by
+		// INT-WEBHOOK-PAYLOAD-SUBSET, and the body stays DATA all the way down (CONST-ISSUE-TEXT-IS-DATA).
+		comment: { body: subset.comment.body, author_association: subset.comment.author_association },
+		target: { type: isPR ? "pull_request" : "issue", number: subset.issue?.number, title: subset.issue?.title, body: subset.issue?.body },
+	};
+}
+
+/**
+ * Pull-request path. `labeled` is gated by the label predicate (collaborator-applied label = approval);
+ * auto actions (`opened|synchronize|reopened`) are gated by the PR author_association (hard-coded, never
+ * config-optional). A trigger's optional predicate only narrows an auto action; an empty predicate is
+ * vacuously true. First matching rule (in file order) wins.
+ */
+function routePullRequest(subset, triggers, action) {
+	const pr = subset.pull_request;
+	if (pr === null || typeof pr !== "object") {
+		return { enqueue: false, reason: "missing-pull-request" };
+	}
+	const L = labelSet(pr.labels);
+	const authorOk = AUTHOR_ALLOWLIST.has(pr.author_association);
+
+	for (const rule of triggers.pullRequest ?? []) {
+		if (!rule.actions.has(action)) continue;
+		if (action === "labeled") {
+			if (!matchesRule(L, rule.predicate)) continue;
+		} else {
+			// Auto action -- author_association is the hard gate; the predicate (if any) narrows scope.
+			if (!authorOk) continue;
+			if (!matchesRule(L, rule.predicate)) continue;
+		}
+		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,
+			replicas: rule.replicas,
+			matched: { index: rule.index, type: "pull_request", action },
+			target: buildPrTarget(pr),
+		};
+	}
+
+	// Surface the security-relevant author drop distinctly from a plain no-match so it is observable.
+	if (PR_AUTO_ACTIONS.has(action) && !authorOk) {
+		return { enqueue: false, reason: "pr-author-not-allowed" };
+	}
+	return { enqueue: false, reason: "no-matching-pr-trigger" };
+}
+
+/** Build the pull_request target. head/base are carried as DATA only -- never a clone ref (see header). */
+function buildPrTarget(pr) {
+	const target = { type: "pull_request", number: pr.number, title: pr.title, body: pr.body };
+	if (pr.head) target.head = { ref: pr.head.ref, sha: pr.head.sha, repo: pr.head.repo?.full_name };
+	if (pr.base) target.base = { ref: pr.base.ref };
+	return target;
+}

package/src/forgejo-members.mjs

@@ -0,0 +1,90 @@
+/**
+ * Resolve a Forgejo actor's repository permission -- the enforcement half of `CONST-TRIGGER-AUTHOR-GATE`
+ * on the Forgejo side.
+ *
+ * Forgejo has no `author_association`; the concept is GitHub's. What it has instead is
+ * `GET /repos/{owner}/{repo}/collaborators/{collaborator}/permission`, which answers
+ * `{ permission: "admin"|"write"|"read"|"none" }`. `admin` and `write` are the honest analogue of
+ * `OWNER|MEMBER|COLLABORATOR`: they are exactly the levels that can push a branch, which is the property
+ * the constitution actually requires.
+ *
+ * The shape of this module is the GitLab resolver's, for the same three reasons, and they are worth
+ * restating rather than cross-referencing:
+ *   - it runs in the RECEIVER, between verification and the gate, so `filterForgejo` stays pure, total and
+ *     offline-testable -- a fetch inside the gate would make the security-critical decision untestable
+ *     without a server;
+ *   - it runs AFTER verification, so an unauthenticated flood cannot make this project call Forgejo;
+ *   - it returns a two-armed verdict, because "not a collaborator" and "could not tell" are different
+ *     answers. A 404 is determinate and refuses; anything else is INDETERMINATE and the receiver answers
+ *     503, so Forgejo redelivers and the stable `X-GitHub-Delivery` GUID dedups the retry. Collapsing
+ *     indeterminate to "deny" would drop real work during an outage behind a 204 that looks exactly like a
+ *     stranger being correctly refused.
+ *
+ * The username is required (Forgejo's endpoint takes no numeric id) and is never logged or returned.
+ */
+
+import { fetchFailureReason } from "@edgehero/pi-dispatch/gitlab-identity";
+
+/** Forgejo/Gitea's API path prefix. `apiUrl` is the instance root, e.g. `https://codeberg.org`. */
+const API_PREFIX = "/api/v1";
+
+/**
+ * The permission levels that can push to the repository. `read` and `none` cannot, so a job started on
+ * their say-so would be doing work the actor could not do themselves -- the line CONST-TRIGGER-AUTHOR-GATE
+ * draws.
+ */
+const WRITE_PERMISSIONS = new Set(["admin", "write"]);
+
+/**
+ * Build the resolver. `token` is the same operator-supplied access token the worker uses; `fetchFn` is
+ * injected so the whole module is testable offline.
+ *
+ * Returns `resolveAuthority(repoFullName, login)` -> `{ authorized: boolean }` | `{ indeterminate: string }`
+ * -- the same shape every forge's resolver returns.
+ */
+export function makeResolveForgejoAuthority({ apiUrl, token, fetchFn = fetch }) {
+	return async function resolveAuthority(repoFullName, login) {
+		// Both halves have to be present AND well-formed before they become path segments. A slash or a `..`
+		// in either would reach a different endpoint than the one this function believes it is asking, and
+		// the answer would be attributed to the wrong repository or the wrong person.
+		const repo = typeof repoFullName === "string" ? repoFullName.split("/") : [];
+		if (repo.length !== 2 || !repo[0] || !repo[1] || typeof login !== "string" || login === "" || /[/?#]/.test(login)) {
+			// Not a lookup failure -- the payload never named a repository and an actor we could ask about.
+			// Determinate, and refused.
+			return { authorized: false };
+		}
+		const root = String(apiUrl).replace(/\/+$/, "") + API_PREFIX;
+		const url = `${root}/repos/${encodeURIComponent(repo[0])}/${encodeURIComponent(repo[1])}/collaborators/${encodeURIComponent(login)}/permission`;
+		let res;
+		try {
+			// `redirect: "error"` so an instance that 30x-es this path cannot silently send the token
+			// somewhere else -- the same rule the GitLab host applies.
+			res = await fetchFn(url, { headers: { Authorization: `token ${token}` }, redirect: "error" });
+		} catch (err) {
+			return { indeterminate: fetchFailureReason(err) };
+		}
+		if (res.status === 404) {
+			// Forgejo's answer for "no such collaborator on this repository". The one status that may read as
+			// a refusal rather than a failure.
+			return { authorized: false };
+		}
+		if (!res.ok) {
+			// Note what is NOT here: the response body. A Forgejo error body can echo the request, and the
+			// request carried the token.
+			return { indeterminate: `collaborator permission lookup returned ${res.status}` };
+		}
+		let body;
+		try {
+			body = await res.json();
+		} catch (err) {
+			return { indeterminate: `collaborator permission lookup returned unparseable JSON: ${err?.message ?? "unknown"}` };
+		}
+		const permission = body?.permission;
+		if (typeof permission !== "string" || permission === "") {
+			// 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: "collaborator permission lookup returned no permission string" };
+		}
+		return { authorized: WRITE_PERMISSIONS.has(permission) };
+	};
+}

package/src/forgejo-subset.mjs

@@ -0,0 +1,113 @@
+/**
+ * Project ONLY the fields the Forgejo gate and job are allowed to see (`INT-FORGEJO-PAYLOAD-SUBSET`).
+ *
+ * A sibling of `parseSubset` (GitHub) and `parseGitLabSubset`, not a reuse of either. Forgejo's payload is
+ * the closest of the three to GitHub's -- `modules/structs/hook.go` carries the same JSON tags for
+ * `action`, `issue.{number,title,body}`, `issue.labels[].name`, `comment.body`, `repository.full_name` and
+ * `pull_request.{number,title,body,labels,head,base}` -- which is exactly why it gets its own projection
+ * rather than sharing GitHub's. "Almost the same" is the shape that breaks quietly, and there are three
+ * differences, each of which is a wrong job rather than an error:
+ *
+ *   1. NO `author_association`. Forgejo has no such concept anywhere. GitHub's gate reads that field, so
+ *      against a Forgejo body it is `undefined` and the gate denies everything -- which fails closed, and
+ *      is therefore the RIGHT accident, but it means the comment and PR-auto paths are simply dead until
+ *      an authority verdict is resolved from the API instead (forgejo-members.mjs).
+ *   2. `is_pull` AT TOP LEVEL, not `issue.pull_request`. Get this wrong and every comment on a pull request
+ *      routes as an ISSUE target, so the envelope 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 like it succeeded.
+ *   3. `sender.login` IS CARRIED, where GitHub's subset deliberately excludes it. It is personal data, and
+ *      it is here for exactly one consumer -- the collaborator-permission lookup, which is by username
+ *      because that is the only key Forgejo's endpoint takes. Same justification, and same obligation, as
+ *      `user.username` in the GitLab subset: it exists to have been asked about, and `no-pii-in-logs`
+ *      applies to everything the resolution path writes down.
+ *
+ * Everything else in the delivery is ignored.
+ */
+
+/**
+ * Forgejo's issue/PR action vocabulary, mapped to the words this codebase's gate is written in.
+ *
+ * This map is why the module exists in the shape it does. Forgejo's `HookEventType.Event()` reports
+ * `issue_label` as `X-GitHub-Event: issues` and `pull_request_label` as `pull_request`, so a label change
+ * arrives looking exactly like a GitHub label event -- and then says `"action": "label_updated"`. Against
+ * GitHub's vocabulary that passes the event check, fails the action check, and falls out as
+ * `unhandled-event`: HTTP 200, no job, no error, and nothing that says why. An operator watching a trigger
+ * that never fires has nothing to look at.
+ *
+ * So the mapping is explicit and tested, never incidental. Two rules it encodes:
+ *   - `label_cleared` maps to NOTHING, permanently. It has no GitHub counterpart and must not acquire one:
+ *     REMOVING a label must never start a paid run.
+ *   - An action that is recognised but not actionable drops under its OWN reason, so "Forgejo sent
+ *     something we understand and chose to ignore" is distinguishable from "we did not recognise this".
+ */
+const ISSUE_ACTIONS = {
+	opened: "opened",
+	reopened: "reopened",
+	label_updated: "labeled",
+};
+
+const PR_ACTIONS = {
+	opened: "opened",
+	reopened: "reopened",
+	label_updated: "labeled",
+	synchronized: "synchronize",
+};
+
+/** Recognised, and deliberately not actionable. Named so the drop reason can say which it was. */
+const IGNORED_ACTIONS = new Set([
+	"label_cleared", // removing a label must never start a paid run
+	"closed",
+	"edited",
+	"assigned",
+	"unassigned",
+	"milestoned",
+	"demilestoned",
+	"reviewed",
+	"review_requested",
+	"review_request_removed",
+]);
+
+/** Forgejo's word for this event's action, in this codebase's vocabulary, or `null` when it maps to none. */
+export function mapAction(eventName, action) {
+	const table = eventName === "pull_request" ? PR_ACTIONS : ISSUE_ACTIONS;
+	return Object.hasOwn(table, action) ? table[action] : null;
+}
+
+/** Whether Forgejo names this action at all -- distinguishes "ignored on purpose" from "never heard of it". */
+export function isRecognizedAction(action) {
+	return IGNORED_ACTIONS.has(action) || Object.hasOwn(ISSUE_ACTIONS, action) || Object.hasOwn(PR_ACTIONS, action);
+}
+
+export function parseForgejoSubset(payload) {
+	const pr = payload.pull_request;
+	return {
+		// Forgejo's raw action word, kept verbatim: the gate maps it, and the job's trigger records what the
+		// forge actually said rather than our translation of it.
+		action: payload.action,
+		sender: { id: payload.sender?.id, login: payload.sender?.login },
+		issue: {
+			number: payload.issue?.number,
+			title: payload.issue?.title,
+			body: payload.issue?.body,
+			labels: Array.isArray(payload.issue?.labels) ? payload.issue.labels.map((l) => ({ name: l?.name })) : [],
+		},
+		comment: { body: payload.comment?.body },
+		// TOP-LEVEL on Forgejo, and a boolean rather than a presence marker for an object. This is the field
+		// that decides whether a comment routes as a pull request or an issue.
+		isPull: payload.is_pull === true,
+		pull_request: pr
+			? {
+					number: pr.number,
+					title: pr.title,
+					body: pr.body,
+					labels: Array.isArray(pr.labels) ? pr.labels.map((l) => ({ name: l?.name })) : [],
+					// head/base are attacker-controlled fork DATA, projected for the flow's event.json and NEVER
+					// used as a clone ref -- the worker clones the base default-branch SHA
+					// (INT-WEBHOOK-PAYLOAD-SUBSET's acceptance clause, which holds here for the same reason).
+					head: { ref: pr.head?.ref, sha: pr.head?.sha, repo: { full_name: pr.head?.repo?.full_name } },
+					base: { ref: pr.base?.ref },
+				}
+			: undefined,
+		repository: { full_name: payload.repository?.full_name },
+	};
+}

package/src/gitlab-members.mjs

@@ -0,0 +1,91 @@
+/**
+ * Resolve a GitLab actor's project access level -- the enforcement half of `CONST-TRIGGER-AUTHOR-GATE` on
+ * the GitLab side.
+ *
+ * GitHub puts `author_association` in the payload, so its gate is decidable from the delivery alone.
+ * GitLab puts nothing equivalent anywhere in a webhook body, so the level has to be ASKED FOR. That single
+ * fact shapes everything here:
+ *
+ *   - It runs in the receiver, between verification and `filterGitLab`, and only its VERDICT is passed into
+ *     the gate. The gate stays pure, total and offline-testable; a fetch inside it would make the
+ *     security-critical decision untestable without a server.
+ *   - It runs AFTER verification, never before, so an unauthenticated flood cannot make this project issue
+ *     API calls on an attacker's behalf.
+ *   - It distinguishes "not a member" from "could not tell", and those are different answers. A 404 is
+ *     determinate and yields `authorized: false`, which the gate refuses. Anything else -- a 5xx, a dead
+ *     socket, a revoked token -- is INDETERMINATE, and the receiver answers 503 so GitLab redelivers.
+ *     Collapsing indeterminate to "deny" would silently drop legitimate work during an outage, with a 204
+ *     that reads exactly like a correctly-refused stranger.
+ *
+ * `members/all` and not `members`: the `all` variant includes membership inherited from a parent group,
+ * which is how most real GitLab organisations grant access. The plain endpoint reports only direct members
+ * and would refuse a maintainer who holds their role at the group level -- a denial that looks like a
+ * policy decision and is really a wrong question.
+ *
+ * The username is never sent, logged or returned; the lookup is by numeric user id.
+ */
+
+import { fetchFailureReason } from "@edgehero/pi-dispatch/gitlab-identity";
+
+/** GitLab's API path prefix. `apiUrl` is the instance root, e.g. `https://gitlab.com`. */
+const API_PREFIX = "/api/v4";
+
+/**
+ * GitLab's Developer role. At or above it, an actor can push to the project, which is the property
+ * CONST-TRIGGER-AUTHOR-GATE actually requires -- "write access or above", by whatever mechanism the forge
+ * offers.
+ *
+ * The threshold lives HERE, with the lookup that produces the number, rather than in the gate. The gate's
+ * job is "is this actor authorised", and every forge answers that differently: GitLab with an integer role,
+ * Forgejo with a string enum, GitHub with a payload field, Azure DevOps with a group membership. Only the
+ * VERDICT is common, so only the verdict crosses into the filter.
+ */
+const DEVELOPER = 30;
+
+/**
+ * Build the resolver. `token` is the same operator-supplied access token the worker uses; `fetchFn` is
+ * injected so the whole module is testable offline.
+ *
+ * Returns `resolveAuthority(projectId, userId)` -> `{ authorized: boolean }` | `{ indeterminate: string }`.
+ *
+ * That two-armed shape is the one every forge's resolver returns, and it is deliberately not a bare
+ * boolean: `false` and "could not tell" are different answers with different HTTP responses, and a type
+ * that cannot express the difference would collapse them at the first call site that forgot.
+ */
+export function makeResolveAuthority({ apiUrl, token, fetchFn = fetch }) {
+	return async function resolveAuthority(projectId, userId) {
+		if (!Number.isInteger(projectId) || !Number.isInteger(userId)) {
+			// Not a lookup failure -- the payload never named a project or an actor, so there is nothing to
+			// ask about. Determinate, and refused.
+			return { authorized: false };
+		}
+		const url = `${String(apiUrl).replace(/\/+$/, "")}${API_PREFIX}/projects/${projectId}/members/all/${userId}`;
+		let res;
+		try {
+			res = await fetchFn(url, { headers: { "PRIVATE-TOKEN": token }, redirect: "error" });
+		} catch (err) {
+			return { indeterminate: fetchFailureReason(err) };
+		}
+		if (res.status === 404) {
+			// GitLab's documented answer for "this user is not a member of this project", including via any
+			// ancestor group. The one status this may read as a refusal rather than a failure.
+			return { authorized: false };
+		}
+		if (!res.ok) {
+			return { indeterminate: `members lookup returned ${res.status}` };
+		}
+		let body;
+		try {
+			body = await res.json();
+		} catch (err) {
+			return { indeterminate: `members lookup returned unparseable JSON: ${err?.message ?? "unknown"}` };
+		}
+		const level = body?.access_level;
+		if (!Number.isInteger(level)) {
+			// A 200 whose shape we do not recognise is not a refusal. Reporting `authorized: false` here would
+			// turn an upstream schema change into a silent, permanent refusal of every trigger.
+			return { indeterminate: "members lookup returned no integer access_level" };
+		}
+		return { authorized: level >= DEVELOPER };
+	};
+}

package/src/gitlab-subset.mjs

@@ -0,0 +1,76 @@
+/**
+ * INT-GITLAB-PAYLOAD-SUBSET: the exact set of GitLab webhook fields this project reads, and nothing else.
+ *
+ * Naming the subset IS the contract, for the same reason `parseSubset` does it on the GitHub side: because
+ * everything unlisted is ignored by construction, an upstream schema addition cannot change our behaviour,
+ * and a reviewer sees the whole attack surface as one list rather than inferring it from destructuring
+ * scattered across a handler. Every field here is attacker-controlled except the headers, and the headers
+ * are only trustworthy after verify-gitlab.mjs has run.
+ *
+ * Three fields have no GitHub counterpart and are the reason this is a separate projection rather than a
+ * rename of the other one:
+ *
+ *   - `changes.labels` -- on GitLab, adding a label is not an action. It arrives as `action: "update"`
+ *     with a before/after diff, so the DIFF is the trigger and the current label set is not. Carrying only
+ *     the set would make every later edit of an already-labelled issue re-fire (filter-gitlab.mjs).
+ *   - `noteable_type` -- how a comment says whether it is on an issue or a merge request. GitHub uses the
+ *     presence of `issue.pull_request`; GitLab states it.
+ *   - `user.username` -- carried, where GitHub's `sender.login` is deliberately dropped, because GitLab
+ *     puts no access level in the payload and the member lookup needs an identity. It is PERSONAL DATA: it
+ *     exists to be handed to the resolver, and must never enter a log line, the job, or the run record.
+ *
+ * `iid` and not `id`: `iid` is the per-project number a human sees and an API path takes. `id` is a global
+ * database key that would produce a valid-looking URL to somebody else's issue.
+ */
+
+/** Map one label array (`[{ title }]`) to `[{ name }]`, so the shared predicate helpers read one shape. */
+function labelNames(labels) {
+	return Array.isArray(labels) ? labels.map((l) => ({ name: l?.title })) : [];
+}
+
+/**
+ * Project a verified GitLab payload down to the subset above. Total: a malformed or partial payload yields
+ * a record with missing fields, never a throw -- the gate is what refuses it, and it does so by finding
+ * nothing to match rather than by crashing the endpoint.
+ */
+export function parseGitLabSubset(payload) {
+	const oa = payload?.object_attributes ?? {};
+	const changes = payload?.changes ?? {};
+	return {
+		objectKind: payload?.object_kind,
+		action: oa.action,
+		user: { id: payload?.user?.id, username: payload?.user?.username },
+		project: {
+			id: payload?.project?.id,
+			path: payload?.project?.path_with_namespace,
+			defaultBranch: payload?.project?.default_branch,
+		},
+		// The issue or merge request the event is about. A note event carries the noteable under its own
+		// key (`issue` / `merge_request`) instead of in object_attributes, which holds the note itself.
+		target: targetOf(payload, oa),
+		note: oa.note,
+		noteableType: oa.noteable_type,
+		labels: labelNames(oa.labels),
+		// Present ONLY when this event changed the labels. Absent is meaningful: it says no label moved,
+		// which is what stops an unrelated `update` from re-firing a label rule.
+		labelChanges: changes.labels
+			? { previous: labelNames(changes.labels.previous), current: labelNames(changes.labels.current) }
+			: undefined,
+		// A merge-request `update` carrying `oldrev` is a push to the source branch -- GitLab's analogue of
+		// GitHub's `synchronize`, which it has no distinct action for.
+		oldrev: oa.oldrev,
+	};
+}
+
+function targetOf(payload, oa) {
+	if (payload?.object_kind === "note") {
+		const noteable = oa.noteable_type === "MergeRequest" ? payload?.merge_request : payload?.issue;
+		return {
+			iid: noteable?.iid,
+			title: noteable?.title,
+			description: noteable?.description,
+			labels: labelNames(noteable?.labels),
+		};
+	}
+	return { iid: oa.iid, title: oa.title, description: oa.description, labels: labelNames(oa.labels) };
+}

package/src/http-body.mjs

@@ -0,0 +1,73 @@
+/**
+ * The forge-neutral half of a webhook endpoint: read a bounded raw body, recognise a JSON content type,
+ * and write a small JSON response.
+ *
+ * Extracted from verify.mjs when a second forge arrived (issue #42), and extracted rather than copied for
+ * one reason: `readRawBody`'s per-chunk accounting is a memory bound on attacker-controlled input. Two
+ * copies of a security limit drift -- one gets the fix, the other keeps the bug -- and the copy that keeps
+ * it is the one nobody is looking at. Verification itself is NOT here; each forge's gate owns its own,
+ * because that is exactly the part that differs.
+ *
+ * Nothing here reads a header that identifies a forge, and nothing here decides whether a request is
+ * trusted. A caller must still verify before parsing a single field (CONST-HMAC-OVER-RAW-BODY).
+ */
+
+/** Accept `application/json`, ignoring any parameters and case. */
+export function isJsonContentType(contentType) {
+	return String(contentType ?? "").split(";")[0].trim().toLowerCase() === "application/json";
+}
+
+/**
+ * Collect the request stream into a Buffer, bounded by `limit`. Accumulation is checked on every
+ * chunk so the buffer can never grow past the cap: exceeding it destroys the request and rejects
+ * with `code: "E_PAYLOAD_TOO_LARGE"` rather than reading an unbounded body into memory.
+ */
+export function readRawBody(req, limit) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let size = 0;
+		let settled = false;
+
+		const cleanup = () => {
+			req.removeListener("data", onData);
+			req.removeListener("end", onEnd);
+			req.removeListener("error", onError);
+		};
+		const onData = (chunk) => {
+			if (settled) return;
+			size += chunk.length;
+			if (size > limit) {
+				settled = true;
+				cleanup();
+				req.destroy();
+				const err = new Error("payload too large");
+				err.code = "E_PAYLOAD_TOO_LARGE";
+				reject(err);
+				return;
+			}
+			chunks.push(chunk);
+		};
+		const onEnd = () => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			resolve(Buffer.concat(chunks));
+		};
+		const onError = (err) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			reject(err);
+		};
+
+		req.on("data", onData);
+		req.on("end", onEnd);
+		req.on("error", onError);
+	});
+}
+
+/** Write a small JSON body with an explicit status. `writeHead` sets the status code on the response. */
+export function respond(res, status, body) {
+	res.writeHead(status, { "content-type": "application/json" });
+	res.end(JSON.stringify(body));
+}