@edgehero/pi-dispatch-receiver 1.1.0 → 1.3.0

package/src/filter.mjs

@@ -33,9 +33,19 @@
  * All three are hard-coded here, never config-optional -- an ungated auto-trigger is an unbounded paid run
  * started by whoever opens a fork PR (CONST-TRIGGER-AUTHOR-GATE, job-budget rules).
  *
+ * CLOSE ROUTES (issue #231): `issues.closed` and `pull_request.closed` route over the close-trigger
+ * groups (`triggers.issue` / `triggers.prClose`) via the ONE shared derivation in ./close.mjs. Their
+ * gate is `closerAuthorized`, the OPTIONAL sixth parameter: the receiver's pre-resolved answer to
+ * "does the account that closed this item hold write access". It is a parameter because this module
+ * is pure and that answer needs a network lookup the receiver performs (only when
+ * `wantsCloserAuthority` below says a rule wants this close). Strict `=== true` -- anything else,
+ * absence included, fails closed -- so every existing five-argument call site behaves byte-identically:
+ * their routes never read the value.
+ *
  * `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 { findCloseRule } from "./close.mjs";
 import { escapeRegExp, firstMatchingRule, labelSet, matchedLabel, matchesRule } from "./predicate.mjs";
 
 const AUTHOR_ALLOWLIST = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
@@ -48,8 +58,17 @@ const REVIEW_ACTION = "review_submitted";
 const REVIEW_EVENT_ACTION = "submitted";
 // PR_AUTO_ACTIONS is deliberately NOT extended with REVIEW_ACTION: it exists only to select the
 // `pr-author-not-allowed` drop reason, and the review path has reasons of its own.
+//
+// GitHub's close word (issue #231), byte-equal to PR_CLOSE_ACTIONS.github in the shared forge table
+// (worker/src/triggers.mjs). Spelled here rather than imported, deliberately: this file is the GITHUB
+// gate and already spells GitHub's action vocabulary in its own Sets above -- pulling the per-forge
+// table into it would suggest this gate routes other forges' words, which it never does (each forge
+// has a filter of its own, and the config grouping already consumed the table to build the groups this
+// file reads). The word cannot drift: it is what the wire sends, and the route arm below matches the
+// raw payload action against it.
+const CLOSE_ACTION = "closed";
 
-export function filter(eventName, subset, cfg, selfId, deliveryId) {
+export function filter(eventName, subset, cfg, selfId, deliveryId, closerAuthorized) {
 	// (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" };
@@ -85,6 +104,16 @@ export function filter(eventName, subset, cfg, selfId, deliveryId) {
 		// text the harness has already been paid to read, and a dismissal removes a verdict rather than
 		// stating one.
 		resolved = routePullRequest(subset, triggers, REVIEW_ACTION);
+	} else if (eventName === "issues" && action === CLOSE_ACTION) {
+		// The issue close-trigger route (issue #231). The closer-authority gate lives INSIDE the route,
+		// after the rule match -- see routeClose for why it cannot sit up here.
+		resolved = routeIssueClose(subset, triggers, closerAuthorized);
+	} else if (eventName === "pull_request" && action === CLOSE_ACTION) {
+		// `closed` is deliberately NOT in PR_ACTIONS: a close rule gates on the CLOSER's resolved write
+		// access while every other PR rule gates on the author's association or a collaborator's label,
+		// and one route cannot gate on two different actors -- the same line config.mjs's prClose split
+		// draws, which is what makes `triggers.prClose` the only list this arm ever reads.
+		resolved = routePrClose(subset, triggers, closerAuthorized);
 	} else {
 		return { enqueue: false, reason: "unhandled-event" };
 	}
@@ -121,6 +150,11 @@ export function filter(eventName, subset, cfg, selfId, deliveryId) {
 		// /job/event.json, and a worker-host path in an agent-readable file is the leak prepare-local's
 		// basename(folder) restraint already exists to prevent.
 		...(resolved.skillsDir !== undefined ? { skillsDir: resolved.skillsDir } : {}),
+		// REQ-TRIGGER-SECRETS. Conditional exactly like skillsDir above, so a trigger that binds no
+		// secret enqueues the job data it always has. The map holds REFERENCES, never values: the
+		// receiver has no resolver and reaches no vault -- the worker resolves them pre-spend.
+		...(resolved.secrets !== undefined ? { secrets: resolved.secrets } : {}),
+		...(resolved.secretsProfile !== undefined ? { secretsProfile: resolved.secretsProfile } : {}),
 		...(resolved.instructions !== undefined ? { instructions: resolved.instructions } : {}),
 		// 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.
@@ -166,6 +200,8 @@ function routeIssueLabel(subset, triggers) {
 		packages: rule.packages, // the MATCHED rule's fields -- rules in one file may differ on them
 		image: rule.image,
 		skillsDir: rule.skillsDir,
+		secrets: rule.secrets,
+		secretsProfile: rule.secretsProfile,
 		instructions: rule.instructions,
 		resume: rule.resume,
 		replicas: rule.replicas,
@@ -223,6 +259,8 @@ function routeComment(subset, triggers, knownFlows) {
 		packages: triggers.comment.packages,
 		image: triggers.comment.image,
 		skillsDir: triggers.comment.skillsDir,
+		secrets: triggers.comment.secrets,
+		secretsProfile: triggers.comment.secretsProfile,
 		instructions: triggers.comment.instructions,
 		resume: triggers.comment.resume,
 		replicas: triggers.comment.replicas,
@@ -318,6 +356,8 @@ function routePullRequest(subset, triggers, action) {
 			packages: rule.packages, // the MATCHED rule's fields -- rules in one file may differ on them
 			image: rule.image,
 			skillsDir: rule.skillsDir,
+			secrets: rule.secrets,
+			secretsProfile: rule.secretsProfile,
 			instructions: rule.instructions,
 			resume: rule.resume,
 			replicas: rule.replicas,
@@ -347,3 +387,135 @@ function buildPrTarget(pr) {
 	if (pr.base) target.base = { ref: pr.base.ref };
 	return target;
 }
+
+/**
+ * Issue close path (issue #231). `matched.number` is the CLOSED ITEM's number, not the rule's
+ * narrowing -- an unnarrowed rule fires for any issue, and the decision record must still name which
+ * one spent it, or a once disarm is unexplainable back to an item.
+ */
+function routeIssueClose(subset, triggers, closerAuthorized) {
+	const number = subset.issue?.number;
+	// Integer or refuse, the PR arm's missing-object guard sharpened for BOTH arms: parseSubset always
+	// fabricates `subset.issue` as an object, so object presence proves nothing here, and an UNNARROWED
+	// rule matches on the action alone -- without this line a signed body replayed under a swapped
+	// event header enqueues a paid job whose target has no number at all (and a crafted string number
+	// would ride verbatim into event.json). GitHub only ever sends integers; anything else is a shape
+	// this route must not spend on.
+	if (!Number.isInteger(number)) {
+		return { enqueue: false, reason: "missing-issue-number" };
+	}
+	return routeClose(
+		triggers.issue,
+		number,
+		closerAuthorized,
+		(rule) => ({ index: rule.index, type: "issue", action: CLOSE_ACTION, number, ...(rule.once === true && { once: true }) }),
+		() => ({ type: "issue", number, title: subset.issue?.title, body: subset.issue?.body }),
+	);
+}
+
+/**
+ * PR close path (issue #231), the same guard shape routePullRequest opens with: no pull_request
+ * object is a malformed delivery, refused before any rule is consulted. `matched` carries no number
+ * here -- the target does, exactly as on every other pull_request match.
+ */
+function routePrClose(subset, triggers, closerAuthorized) {
+	const pr = subset.pull_request;
+	// Object AND integer number, the issue arm's rule: a pull_request object without an integer
+	// number is the same malformed delivery wearing a shape, and the dedup key would otherwise read
+	// `#undefined`. One reason for both cases -- to an operator they are one fact.
+	if (pr === null || typeof pr !== "object" || !Number.isInteger(pr.number)) {
+		return { enqueue: false, reason: "missing-pull-request" };
+	}
+	return routeClose(
+		triggers.prClose,
+		pr.number,
+		closerAuthorized,
+		(rule) => ({ index: rule.index, type: "pull_request", action: CLOSE_ACTION, ...(rule.once === true && { once: true }) }),
+		() => buildPrTarget(pr),
+	);
+}
+
+/**
+ * The shared close route: one body for both arms, driving the ONE rule derivation in ./close.mjs --
+ * the same findCloseRule call `wantsCloserAuthority` makes, so "which close does a rule want" can
+ * never drift between the receiver's pre-lookup question and this routing answer.
+ *
+ * `once` rides `matched` only when literally true, mirroring how every optional job field is absent
+ * rather than present-and-false: matched is the downstream disarm signal, and its consumers test
+ * presence, not truthiness.
+ */
+function routeClose(rules, number, closerAuthorized, matchedFor, targetFor) {
+	const found = findCloseRule(rules, CLOSE_ACTION, number);
+	if (found.rule === undefined) {
+		return { enqueue: false, reason: found.reason };
+	}
+	// The authority gate sits INSIDE the route and AFTER the match, deliberately. The receiver performs
+	// the closer's permission lookup only for a delivery some close rule actually wants (that is what
+	// `wantsCloserAuthority` exists for), so a gate BEFORE the rule loop would emit `closer-not-allowed`
+	// for closes no rule matches -- a security token no lookup ever backed, telling an operator an
+	// authority decision was made about a delivery nobody ever resolved. A close nothing wants is
+	// `no-matching-close-trigger`, whoever closed it.
+	//
+	// Strict `!== true`, never truthiness: the value is the receiver's RESOLVED answer, and anything
+	// else reaching here -- undefined from an unwired caller, an indeterminate lookup, a "true" string
+	// or a count from a parse bug -- is a wiring fault that must fail CLOSED, the direction every gate
+	// in this file already takes (CONST-TRIGGER-AUTHOR-GATE).
+	if (closerAuthorized !== true) {
+		return { enqueue: false, reason: "closer-not-allowed" };
+	}
+	const rule = found.rule;
+	return {
+		enqueue: true,
+		// A command rule (issue #189) skips flow resolution entirely: the rule match IS the dispatch.
+		...(rule.command !== undefined ? { command: rule.command } : { flow: rule.flow }),
+		packages: rule.packages, // the MATCHED rule's fields -- rules in one file may differ on them
+		image: rule.image,
+		skillsDir: rule.skillsDir,
+		secrets: rule.secrets,
+		secretsProfile: rule.secretsProfile,
+		instructions: rule.instructions,
+		resume: rule.resume,
+		replicas: rule.replicas,
+		matched: matchedFor(rule),
+		target: targetFor(),
+	};
+}
+
+/**
+ * Does this forge group arm any close trigger at all? Pure, for the receiver/poller arm: whether the
+ * closer-authority machinery is worth wiring up for a delivery stream is a per-group fact, and
+ * deriving it anywhere else would be a second spelling of "which groups are the close groups".
+ */
+export function hasCloseTriggers(group) {
+	return group?.issue?.length > 0 || group?.prClose?.length > 0;
+}
+
+/**
+ * Should the receiver spend a permission lookup on this delivery before calling `filter`? Pure, and
+ * the SINGLE derivation shared with the route above: it calls the same findCloseRule over the same
+ * groups, so the pre-lookup question and the routing answer cannot drift -- a delivery never costs a
+ * lookup the route then ignores, and never routes a close the lookup never gated (./close.mjs's
+ * header names exactly this hazard).
+ */
+export function wantsCloserAuthority(eventName, subset, group, selfId) {
+	// Filter's own step-0/1 guards, replicated FIRST and in the same order (fail-closed identity, then
+	// the unconditional bot-loop guard): the harness closing its own issue -- the natural last act of
+	// the very flow a close trigger arms -- must not cost a lookup, and an INDETERMINATE lookup on a
+	// self-delivery would 503 (so: redeliver, retry, loop) traffic the filter would only ever drop as
+	// `self`.
+	if (typeof subset?.sender?.id !== "number") return false;
+	if (subset.sender.id === selfId) return false;
+	if (eventName === "issues" && subset.action === CLOSE_ACTION) {
+		// The routes' own shape guards, replicated for the same one-derivation reason as the step-0/1
+		// guards above: an UNNARROWED rule matches an undefined number, so without these lines a
+		// degenerate payload costs a token mint and a lookup the route then drops -- the exact "lookup
+		// the route ignores" this function exists to make impossible.
+		if (!Number.isInteger(subset.issue?.number)) return false;
+		return findCloseRule(group?.issue, CLOSE_ACTION, subset.issue.number).rule !== undefined;
+	}
+	if (eventName === "pull_request" && subset.action === CLOSE_ACTION) {
+		if (subset.pull_request === null || typeof subset.pull_request !== "object" || !Number.isInteger(subset.pull_request.number)) return false;
+		return findCloseRule(group?.prClose, CLOSE_ACTION, subset.pull_request.number).rule !== undefined;
+	}
+	return false;
+}

package/src/forgejo-members.mjs

@@ -77,7 +77,10 @@ export function makeResolveForgejoAuthority({ apiUrl, token, fetchFn = fetch })
 		try {
 			body = await res.json();
 		} catch (err) {
-			return { indeterminate: `collaborator permission lookup returned unparseable JSON: ${err?.message ?? "unknown"}` };
+			// A FIXED reason, never err.message: V8's JSON.parse errors quote the offending input,
+			// so a failed res.json() here would carry response-body bytes into a log line -- the
+			// no-pii-in-logs rule the github resolver states, applied to its elders (issue #231).
+			return { indeterminate: "collaborator permission lookup returned unparseable JSON" };
 		}
 		const permission = body?.permission;
 		if (typeof permission !== "string" || permission === "") {

package/src/forgejo-subset.mjs

@@ -44,6 +44,11 @@ const ISSUE_ACTIONS = {
 	opened: "opened",
 	reopened: "reopened",
 	label_updated: "labeled",
+	// The close trigger (issue #231) made `closed` actionable, so it moved OUT of IGNORED_ACTIONS
+	// below. It sits in BOTH maps deliberately: the maps are selected by EVENT NAME, so `closed` on
+	// `issues` and `closed` on `pull_request` are two different routes sharing a spelling, not one
+	// word listed twice -- the never-in-two rule below is about a map versus the ignored set.
+	closed: "closed",
 };
 
 const PR_ACTIONS = {
@@ -51,12 +56,19 @@ const PR_ACTIONS = {
 	reopened: "reopened",
 	label_updated: "labeled",
 	synchronized: "synchronize",
+	closed: "closed", // issue #231 -- see the note on ISSUE_ACTIONS
 };
 
-/** Recognised, and deliberately not actionable. Named so the drop reason can say which it was. */
+/**
+ * Recognised, and deliberately not actionable. Named so the drop reason can say which it was.
+ *
+ * DISJOINT from both action maps, and that is an invariant rather than an accident: `mapAction`
+ * would happily route a word that also sat here, and this set's claim of "ignored" would then be a
+ * lie the drop reason repeats to an operator. `closed` lived here until issue #231 made closes
+ * routable; it MOVED into the maps rather than gaining a twin.
+ */
 const IGNORED_ACTIONS = new Set([
 	"label_cleared", // removing a label must never start a paid run
-	"closed",
 	"edited",
 	"assigned",
 	"unassigned",

package/src/github-members.mjs

@@ -0,0 +1,140 @@
+/**
+ * Resolve a GitHub CLOSER's repository permission -- the enforcement half of `CONST-TRIGGER-AUTHOR-GATE`'s
+ * close arm on the GitHub side.
+ *
+ * Every other GitHub route reads an association straight off the payload and pays no lookup. A close
+ * cannot: an issue's own author can close it with no write access whatsoever, and on a pull request
+ * `author_association` names the AUTHOR, a different person from the closer -- the review inversion a
+ * second time. The payload carries NO association for the closer at all, so the closer is resolved by
+ * login through `GET /repos/{owner}/{repo}/collaborators/{username}/permission`, whose legacy
+ * `permission` field answers `"admin"|"write"|"read"|"none"`. `admin` and `write` are exactly the levels
+ * that can push a branch, which is the property the constitution actually requires.
+ *
+ * The shape of this module is the Forgejo resolver's, for the same three reasons, restated rather than
+ * cross-referenced:
+ *   - it runs in the RECEIVER, between verification and the gate, so `filter` 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 -- and, unlike every sibling resolver, only for a close delivery an
+ *     armed close rule actually matches (`wantsCloserAuthority`), so every other GitHub path stays
+ *     payload-only and lookup-free, and an unauthenticated flood cannot make this project call GitHub;
+ *   - it returns a two-armed verdict, because "not a collaborator" and "could not tell" are different
+ *     answers. A 404 is determinate and refuses; anything unrecognised is INDETERMINATE and the receiver
+ *     answers 503, so GitHub 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.
+ *
+ * One difference from every sibling: there is no operator token in config to close over. The GitHub arm
+ * holds the boot-time auth object instead, so the credential is MINTED per call. On the App source the
+ * caller asks the mint to scope it to the one repository AND narrow it to metadata:read, so what this
+ * function holds cannot write even if leaked; on pat/gh no narrowing exists (the operator's standing
+ * token is what it is, and it already lives in this process's env), so what the wiring buys there is
+ * one read with a credential the receiver held anyway. Never a job credential on any source, and no
+ * container ever receives it (`CONST-TOKEN-SCOPED-PER-JOB`, whose per-job wording start.mjs's header
+ * records). Closes are rare, so per-delivery minting is the recorded cost; the poller's token cache is
+ * the fallback if that changes.
+ *
+ * The username is required (the endpoint takes no numeric id) and is never logged or returned. One
+ * honest bound on that claim, shared with every sibling resolver: the network-throw arm returns
+ * `fetchFailureReason(err)`, and undici's error messages carry the HOST, never the request path --
+ * so the guarantee on that one arm rests on undici's phrasing rather than a fixed token, exactly as
+ * it does in the forgejo/gitlab/azure resolvers. Every arm this module authors itself is a fixed
+ * string.
+ */
+
+import { fetchFailureReason } from "@edgehero/pi-dispatch/gitlab-identity";
+
+/** GitHub's API root. Not configurable: this arm serves github.com, the forges with a host knob have their own resolvers. */
+const API_ROOT = "https://api.github.com";
+
+/**
+ * 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. Two members is the COMPLETE honest mapping, not a shortcut: GitHub folds `maintain` into `write`
+ * and `triage` into `read` in this legacy field, so every role that can push already reads as one of
+ * these. The response's richer `role_name` is deliberately not read -- it can name Ultimate custom roles
+ * this code has no table to rank, and ranking them wrongly fails OPEN.
+ */
+const WRITE_PERMISSIONS = new Set(["admin", "write"]);
+
+/**
+ * Build the resolver. `mintToken` is the boot auth object's own minter (it takes a job-shaped `{ repo }`
+ * and scopes the token to it); `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 makeResolveGitHubAuthority({ mintToken, 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. Whitespace joins the
+		// refused set here because a GitHub login can never carry it, so its presence is a malformed payload,
+		// not a user. Determinate refusals, before the mint: nothing is asked about, so nothing is spent.
+		const repo = typeof repoFullName === "string" ? repoFullName.split("/") : [];
+		// The repo halves get the login's charset discipline PLUS the dot-segment refusal: a half of
+		// exactly "." or ".." would URL-normalize the request onto a different endpoint than the one
+		// this function believes it is asking (a repo NAME may contain dots -- "next.js" is real -- so
+		// only the two pure dot segments are refused, never dots inside a name).
+		const badHalf = (h) => !h || h === "." || h === ".." || /[/?#\s]/.test(h);
+		if (repo.length !== 2 || badHalf(repo[0]) || badHalf(repo[1]) || typeof login !== "string" || login === "" || /[/?#\s]/.test(login)) {
+			// Not a lookup failure -- the payload never named a repository and an actor we could ask about.
+			return { authorized: false };
+		}
+		// Minted per call, repo-scoped (the auth object's minter reads `job.repo`). A mint failure is
+		// INDETERMINATE -- the closer's standing was never established -- and the reason is a fixed token,
+		// never the thrown message: configError texts name auth sources and key paths, which have no
+		// business in a per-delivery log line.
+		let token;
+		try {
+			token = await mintToken({ repo: repoFullName });
+		} catch {
+			return { indeterminate: "token-mint-failed" };
+		}
+		const url = `${API_ROOT}/repos/${encodeURIComponent(repo[0])}/${encodeURIComponent(repo[1])}/collaborators/${encodeURIComponent(login)}/permission`;
+		let res;
+		try {
+			// `redirect: "error"` so a 30x on this path cannot silently send the token somewhere else -- the
+			// same rule the Forgejo and GitLab resolvers apply.
+			res = await fetchFn(url, {
+				headers: {
+					accept: "application/vnd.github+json",
+					"x-github-api-version": "2022-11-28",
+					authorization: `Bearer ${token}`,
+				},
+				redirect: "error",
+			});
+		} catch (err) {
+			return { indeterminate: fetchFailureReason(err) };
+		}
+		if (res.status === 404) {
+			// Unknown user or unknown repository -- determinate, and refused. NOT the usual non-collaborator
+			// answer: see the `permission: "none"` note below.
+			return { authorized: false };
+		}
+		if (!res.ok) {
+			// Status only. What is NOT here: the response body -- a GitHub error body can echo the request,
+			// and the request carried the token.
+			return { indeterminate: `status-${res.status}` };
+		}
+		let body;
+		try {
+			body = await res.json();
+		} catch {
+			// A fixed token, deliberately WITHOUT the parse error's message -- a divergence from the Forgejo
+			// resolver worth its own line: V8's JSON.parse errors quote the offending input, and the input
+			// here is the response body, which must never reach a returned string.
+			return { indeterminate: "collaborator permission lookup returned unparseable JSON" };
+		}
+		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 close trigger.
+			return { indeterminate: "collaborator permission lookup returned no permission string" };
+		}
+		// The NORMAL answer for a non-collaborator is a 200 with `permission: "none"` -- GitHub answers the
+		// question for any visible user rather than 404ing strangers -- so this line, not the 404 arm above,
+		// is where most unauthorized closers are refused.
+		return { authorized: WRITE_PERMISSIONS.has(permission) };
+	};
+}

package/src/gitlab-members.mjs

@@ -78,7 +78,10 @@ export function makeResolveAuthority({ apiUrl, token, fetchFn = fetch }) {
 		try {
 			body = await res.json();
 		} catch (err) {
-			return { indeterminate: `members lookup returned unparseable JSON: ${err?.message ?? "unknown"}` };
+			// A FIXED reason, never err.message: V8's JSON.parse errors quote the offending input,
+			// so a failed res.json() here would carry response-body bytes into a log line -- the
+			// no-pii-in-logs rule the github resolver states, applied to its elders (issue #231).
+			return { indeterminate: "members lookup returned unparseable JSON" };
 		}
 		const level = body?.access_level;
 		if (!Number.isInteger(level)) {