@edgehero/pi-dispatch-receiver 4.3.0 → 4.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch-receiver",
-  "version": "4.3.0",
+  "version": "4.3.1",
   "type": "module",
   "description": "The pi-dispatch trigger edge: verifies GitHub, GitLab, Forgejo and Azure DevOps webhooks, or polls GitHub with no public URL, and queues one pi coding agent job per event (per replica, if set) for the worker.",
   "keywords": [
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@octokit/webhooks": "14.2.0",
-    "@edgehero/pi-dispatch": "^4.3.0",
+    "@edgehero/pi-dispatch": "^4.3.1",
     "bullmq": "5.80.4",
     "ioredis": "5.11.1"
   }

package/src/config.mjs

@@ -184,6 +184,16 @@ function loadGitLabConfig(env) {
  * `FORGEJO_BOT_ID` is optional and exists for one reason: a repository-scoped token cannot call
  * `GET /user` (see worker/src/forgejo-identity.mjs). Without it, following the token-scoping advice would
  * make the receiver unable to identify itself, and identity is not optional here.
+ *
+ * `FORGEJO_PERMISSION_TOKEN` is optional and is the author gate's alone (OQ-043). Forgejo answers a lookup of
+ * ANOTHER user's repository permission only to a site admin or a repository admin, so whichever token asks must
+ * belong to one. FORGEJO_TOKEN is also every forgejo job's token, so making ITS account an admin hands each job
+ * a token that can lift branch protection. This variable lets a DIFFERENT account, an admin of the repositories,
+ * answer that one GET with a `read:repository` token, while the job's account stays a `write` collaborator.
+ * Read here and nowhere else: it never reaches the worker's job env, and the worker refuses it in PI_FORWARD_ENV
+ * and run.secrets (WORKER_ONLY_SECRET_VARS). Unset (or blank), the lookup falls back to FORGEJO_TOKEN, which is
+ * the behaviour before it existed and works only if that account is an admin; `lookupTokenVar` names which one
+ * is in use, so the boot line and a 403's reason can say so.
  */
 function loadForgejoConfig(env) {
 	const secret = env.FORGEJO_WEBHOOK_SECRET;
@@ -206,7 +216,15 @@ function loadForgejoConfig(env) {
 	if (typeof token !== "string" || token.trim() === "") {
 		throw configError("FORGEJO_TOKEN is required for forgejo triggers -- the receiver resolves the actor's repository permission before it may enqueue");
 	}
-	return { secret, token, apiUrl: apiUrl.trim(), botId };
+	const permissionToken = typeof env.FORGEJO_PERMISSION_TOKEN === "string" ? env.FORGEJO_PERMISSION_TOKEN.trim() : "";
+	return {
+		secret,
+		token,
+		apiUrl: apiUrl.trim(),
+		botId,
+		lookupToken: permissionToken !== "" ? permissionToken : token,
+		lookupTokenVar: permissionToken !== "" ? "FORGEJO_PERMISSION_TOKEN" : "FORGEJO_TOKEN",
+	};
 }
 
 /**

package/src/forgejo-members.mjs

@@ -4,9 +4,12 @@
  *
  * 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.
+ * `{ permission: "owner"|"admin"|"write"|"read"|"none" }`. `owner`, `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. `owner` is not hypothetical and not rare: measured on
+ * Forgejo 14.0.5, the owner of a personal repository asking about themselves gets
+ * `{"permission":"owner","role_name":"owner",...}`, and a set without it dropped every trigger they set
+ * as `author-not-allowed`.
  *
  * The shape of this module is the GitLab resolver's, for the same three reasons, and they are worth
  * restating rather than cross-referencing:
@@ -31,18 +34,31 @@ 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.
+ * draws. These are the strings of Forgejo's access modes (none, read, write, admin, owner); `owner` is what
+ * a personal repository's owner is answered with (measured, see the header).
  */
-const WRITE_PERMISSIONS = new Set(["admin", "write"]);
+const WRITE_PERMISSIONS = new Set(["owner", "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.
+ * What a 403 tells the operator to fix, by which variable's token asked. Fixed strings, never the body.
+ * With the dedicated lookup token, its account is the one that must be an admin. With the fallback, the right repair
+ * is NOT to make the job's account an admin (that hands every job a token able to lift branch protection, OQ-043) but
+ * to give the lookup its own token.
+ */
+const FORBIDDEN_REASON = Object.freeze({
+	FORGEJO_PERMISSION_TOKEN: "collaborator permission lookup returned 403 (the account behind FORGEJO_PERMISSION_TOKEN must be an admin or the owner of the repository, and the token must carry read:repository)",
+	FORGEJO_TOKEN: "collaborator permission lookup returned 403 (FORGEJO_TOKEN's account is not an admin of the repository: set FORGEJO_PERMISSION_TOKEN to a read:repository token of an account that is, docs/forgejo.md)",
+});
+
+/**
+ * Build the resolver. `token` is the lookup token (FORGEJO_PERMISSION_TOKEN, or FORGEJO_TOKEN as the fallback) and
+ * `tokenVar` names which, for a 403's reason; `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 }) {
+export function makeResolveForgejoAuthority({ apiUrl, token, tokenVar = "FORGEJO_TOKEN", fetchFn = fetch }) {
+	const forbidden = FORBIDDEN_REASON[tokenVar] ?? FORBIDDEN_REASON.FORGEJO_TOKEN;
 	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
@@ -68,6 +84,23 @@ export function makeResolveForgejoAuthority({ apiUrl, token, fetchFn = fetch })
 			// a refusal rather than a failure.
 			return { authorized: false };
 		}
+		if (res.status === 403) {
+			// A CONFIGURATION error, named as one. Forgejo lets only a site admin, a repository admin, or the
+			// user themselves read a permission (measured on 14.0.5: a `write` collaborator's token gets 403
+			// {"message":"Only admins can query all permissions, repo admins can query all repo permissions,
+			// collaborators can query only their own"}; the same account raised to repo admin gets 200). The
+			// other 403s this route can give are the token's scope (`token does not have at least one of
+			// required scope(s)`, `token scope is limited to public repos`), so the dedicated token's reason names its scope too.
+			// Still indeterminate, and that is a decision, not an oversight. A retry cannot heal it, but the
+			// retry costs nothing (no token is minted and nothing spends before this answer), while the
+			// alternative is worse in the way this file's header names: a determinate refusal answers 204, which
+			// Forgejo records as a successful delivery, so the one place the operator looks would show every
+			// trigger "delivered" while nothing ran. A 503 marks each delivery failed there, the log line below
+			// names the repair, and a delivery that failed this way still describes real work to redo once the
+			// account is fixed. The body is still not read: the fixed reason is enough, and a body is not ours
+			// to log. The reason names the variable whose token asked (FORBIDDEN_REASON).
+			return { indeterminate: forbidden };
+		}
 		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.

package/src/start.mjs

@@ -211,10 +211,14 @@ export async function startReceiver(
 		if (cfg.forgejo) {
 			const forgejoSelfId = await retryIdentity(() => resolveForgejoSelfIdFn({ apiUrl: cfg.forgejo.apiUrl, token: cfg.forgejo.token, botId: cfg.forgejo.botId }), { forge: "forgejo", ...retryOpts });
 			log({ event: "self_identity", forge: "forgejo", id: forgejoSelfId, source: cfg.forgejo.botId ? "FORGEJO_BOT_ID" : "api" });
+			// The author gate's lookup token, by NAME only (OQ-043): FORGEJO_PERMISSION_TOKEN when set, else FORGEJO_TOKEN,
+			// whose account must then be a repository admin. Identity above stays FORGEJO_TOKEN's: it is the account the
+			// jobs post as, which the bot-loop guard must recognise.
+			log({ event: "forgejo_permission_token", source: cfg.forgejo.lookupTokenVar });
 			forgejo = {
 				secret: cfg.forgejo.secret,
 				selfId: forgejoSelfId,
-				resolveAuthority: makeResolveForgejoAuthorityFn({ apiUrl: cfg.forgejo.apiUrl, token: cfg.forgejo.token }),
+				resolveAuthority: makeResolveForgejoAuthorityFn({ apiUrl: cfg.forgejo.apiUrl, token: cfg.forgejo.lookupToken, tokenVar: cfg.forgejo.lookupTokenVar }),
 			};
 		}