@popcorn245/cornfield 0.9.0 → 0.10.0

package/server/auth.js

@@ -42,6 +42,7 @@ import { createCipheriv, createDecipheriv, createHash, createHmac, hkdfSync, ran
 import { createForge as defaultCreateForge, isMaintainer, ForgeError } from './forge.js';
 import { githubApiUrl } from './forge-github.js';
 import { sameOrigin } from './proposals.js';
+import { revokeOwnerTokens } from './review-tokens.js';
 
 /** How often a session's permission is asked of the forge again */
 export const RECHECK_MS = 15 * 60 * 1000;
@@ -335,6 +336,8 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
       forgeFor: () => { throw new Error('Sign-in is not configured.'); },
       forgeForUser: async () => { throw new Error('Sign-in is not configured.'); },
       record: async () => { throw new Error('Sign-in is not configured.'); },
+      knownPermission: async () => null,
+      demoted: async () => {},
       begin: async () => { throw new Error('Sign-in is not configured.'); },
       finish: async () => { throw new Error('Sign-in is not configured.'); },
       store: null,
@@ -610,6 +613,19 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
       return true;
     };
     const due = () => expiresAt !== null && Date.parse(expiresAt) - REFRESH_SKEW_MS <= now();
+    /** Who the forge says this token is: the login a `permission` question about the owner names */
+    let ownLogin = row.login;
+    /**
+     * What the call answered, looked at once on its way out: when the forge says the owner themself does not maintain the repo, their API
+     * tokens (review, agent, runner) are revoked there and then, wherever in cornfield the question was asked
+     */
+    const noted = async (prop, args, result) => {
+      if (prop === 'me' && result && typeof result.login === 'string') ownLogin = result.login;
+      if (prop === 'permission' && args[0] === forgeConfig.repo && typeof args[1] === 'string' && args[1].toLowerCase() === ownLogin.toLowerCase() && !isMaintainer(result)) {
+        await demoted(row.user_id, ownLogin, result);
+      }
+      return result;
+    };
     return new Proxy({}, {
       get(_, prop) {
         const member = forge[prop];
@@ -625,18 +641,40 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
             }
           }
           try {
-            return await forge[prop](...args);
+            return await noted(prop, args, await forge[prop](...args));
           } catch (err) {
             if (!(err instanceof ForgeError) || err.code !== 'unauthorized') throw err;
             // The forge refused the token: renew it (when it can be) and ask once more; else its refusal stands
             if (!(await renewNow())) throw err;
           }
-          return forge[prop](...args);
+          return noted(prop, args, await forge[prop](...args));
         };
       },
     });
   }
 
+  /**
+   * A token owner the forge says no longer maintains the repo: every API token of theirs (review, agent and runner) is revoked at once, and
+   * the revoking is a row in the audit table. Never throws: what learned it goes on with its own answer.
+   * @param {string} userId
+   * @param {string} login
+   * @param {string} permission what the forge said
+   */
+  async function demoted(userId, login, permission) {
+    try {
+      const n = revokeOwnerTokens(await store(), userId, now());
+      if (!n) return;
+      try {
+        (await store()).prepare('INSERT INTO actions (at, login, action, target, request, status, answer) VALUES (?, ?, ?, ?, ?, ?, ?)')
+          .run(iso(now()), login, 'token-revoke', forgeConfig.repo, JSON.stringify({ reason: 'owner-not-maintainer', permission }), null, JSON.stringify({ revoked: n }));
+      } catch (err) {
+        console.error(`[cornfield] the revoking of ${login}'s tokens could not be written to the audit table: ${err instanceof Error ? err.message : err}`);
+      }
+    } catch (err) {
+      console.error(`[cornfield] the tokens of ${login}, no longer a maintainer, could not be revoked: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+
   async function callback(req, res, url) {
     // The state cookie is cleared only by an answer to the sign-in it belongs to: a link from anywhere else
     // (`/auth/callback?error=x`) cannot cancel one in progress
@@ -668,7 +706,11 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
     file.prepare('INSERT INTO sessions (id, forge, user_id, login, token, permission, created_at, checked_at, expires_at, refresh_token, token_expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)')
       .run(id, forgeConfig.type, String(user.id), user.login, keep ? sealFor(id, 'token', token) : NO_TOKEN, permission, iso(at), iso(at), iso(at + sessionMs),
         keep && given.refreshToken !== '' ? sealFor(id, 'refresh_token', given.refreshToken) : '', keep ? given.expiresAt : null);
-    if (!keep) await revoke(token);
+    if (!keep) {
+      await revoke(token);
+      // Signed in, and not a maintainer: whatever API tokens they made while they were one stop working now
+      await demoted(String(user.id), user.login, permission);
+    }
     redirect(res, '/', [cookie(SESSION_COOKIE, value, { maxAge: sessionMs / 1000, secure }), clearState]);
   }
 
@@ -740,6 +782,19 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
      * decides what happens when this throws (the action it records has usually happened already).
      * @param {{ login: string, action: string, target: string, request?: object, status?: number | null, answer?: object | null }} entry
      */
+    /**
+     * What cornfield last heard of a user's permission on the repo: their newest sign-in's (asked of the forge at sign-in and every 15 minutes
+     * while they use cornfield), or null when it has no sign-in of theirs at all. A runner token is not asked of the forge per call; this is its
+     * cheap guard (server/runner-api.js).
+     * @param {string} userId
+     * @returns {Promise<string | null>}
+     */
+    async knownPermission(userId) {
+      const row = /** @type {{ permission: string } | undefined} */ ((await store()).prepare('SELECT permission FROM sessions WHERE user_id = ? ORDER BY checked_at DESC, rowid DESC LIMIT 1').get(String(userId)));
+      return row ? row.permission : null;
+    },
+    /** Revokes a user's API tokens when cornfield has learned they no longer maintain the repo (see `demoted`) */
+    demoted,
     async record({ login, action, target, request = {}, status = null, answer = null }) {
       (await store()).prepare('INSERT INTO actions (at, login, action, target, request, status, answer) VALUES (?, ?, ?, ?, ?, ?, ?)')
         .run(iso(now()), login, action, target, JSON.stringify(request), status, answer === null ? null : JSON.stringify(answer));

package/server/db.js

@@ -17,6 +17,7 @@
  *                 a row with `issue = 0` says the repo's threads have been looked at once
  *   runs          the agent runs cornfield asked for: the request, where it was posted, the latest report, the pull request found for
  *                 it and when anything last happened (server/agent-runs.js, migration 7); review_tokens also keep a scope
+ *                 (review, agent, or runner: migration 8, which also gives a run its transport and the runner token that claimed it)
  *   run_seen      what has been seen of each run (a comment judged, a hook event sent), so a restart sends and judges nothing twice
  *                 sessions also keep a forge refresh token, the access token's expiry and when `session.expiring` was sent (migration 5)
  *
@@ -201,6 +202,36 @@ export const MIGRATIONS = Object.freeze([
     PRIMARY KEY (run_id, key)
   ) STRICT;
   `,
+  // 8: push and pull transports, and runner tokens (server/agent-runs.js, server/runner-api.js, spec 0005 D2, D5): a run records how its request
+  // travels and which runner token claimed it; the token scope check gains 'runner'. SQLite cannot change a CHECK, so review_tokens is rebuilt
+  // (the documented way: a new table, the rows copied with their ids, the old one dropped, the new one renamed) and keeps its id sequence
+  `
+  ALTER TABLE runs ADD COLUMN transport  TEXT NOT NULL DEFAULT 'forge' CHECK (transport IN ('forge', 'push', 'pull'));  -- how the request reaches the runner; a push or pull run has no request comment (comment_id stays '')
+  ALTER TABLE runs ADD COLUMN claimed_by INTEGER;   -- the runner token (review_tokens.id) that claimed a pull run, or that first reported on a push run
+  ALTER TABLE runs ADD COLUMN claimed_at TEXT;
+  CREATE INDEX runs_queue ON runs (repo, transport, state, requested_at);
+
+  CREATE TABLE review_tokens_new (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    token_hash  TEXT NOT NULL UNIQUE,
+    user_id     TEXT NOT NULL,
+    login       TEXT NOT NULL,
+    label       TEXT NOT NULL,
+    created_at  TEXT NOT NULL,
+    expires_at  TEXT NOT NULL,
+    revoked_at  TEXT,
+    last_used   TEXT,
+    scope       TEXT NOT NULL DEFAULT 'review' CHECK (scope IN ('review', 'agent', 'runner'))  -- what the token may call: POST /api/reviews, POST /api/agent-requests, or the runner routes
+  ) STRICT;
+  INSERT INTO review_tokens_new (id, token_hash, user_id, login, label, created_at, expires_at, revoked_at, last_used, scope)
+    SELECT id, token_hash, user_id, login, label, created_at, expires_at, revoked_at, last_used, scope FROM review_tokens;
+  UPDATE sqlite_sequence SET seq = MAX(seq, COALESCE((SELECT seq FROM sqlite_sequence WHERE name = 'review_tokens'), 0)) WHERE name = 'review_tokens_new';
+  INSERT INTO sqlite_sequence (name, seq) SELECT 'review_tokens_new', seq FROM sqlite_sequence WHERE name = 'review_tokens'
+    AND NOT EXISTS (SELECT 1 FROM sqlite_sequence WHERE name = 'review_tokens_new');
+  DROP TABLE review_tokens;
+  ALTER TABLE review_tokens_new RENAME TO review_tokens;
+  CREATE INDEX review_tokens_user_id ON review_tokens (user_id);
+  `,
 ]);
 
 /** The version a file is at: its `user_version` */

package/server/review-api.js

@@ -8,8 +8,9 @@
  *   GET  /api/review-tokens              the signed-in maintainer's tokens: id, label, made, expires, revoked, last used (never a secret)
  *   POST /api/review-tokens              { label, days? } -> the new token, in this answer only
  *   POST /api/review-tokens/<id>/revoke  ends one of theirs for good
- *   *    /api/agent-tokens…                  the same three for tokens of the other scope: an agent token asks for runs
+ *   *    /api/agent-tokens…                  the same three for tokens of another scope: an agent token asks for runs
  *                                        (`POST /api/agent-requests`, server/agent-api.js) and is no good here, as a review token is no good there
+ *   *    /api/runner-tokens…                 and for a runner token, which lists, claims and reports on runs (server/runner-api.js)
  *
  * **The call takes the token and nothing else.** It runs before the sign-in guard (a script has no cookie) and reads no
  * cookie: a session cookie is never a substitute for the token, and a request that sends only one is 401. Being no
@@ -44,6 +45,7 @@ import { Refused, countAttempt } from './throttle.js';
 export const REVIEWS_PATH = '/api/reviews';
 export const TOKENS_PATH = '/api/review-tokens';
 export const AGENT_TOKENS_PATH = '/api/agent-tokens';
+export const RUNNER_TOKENS_PATH = '/api/runner-tokens';
 /** Calls with no token, or one nobody holds, that are written down in a minute, all callers together */
 export const ANONYMOUS_PER_MINUTE = 20;
 /** What the audit row of a call nobody could name says in place of a login */
@@ -109,7 +111,7 @@ export async function serveReviewCall(req, res, ctx) {
     req.resume();
     const flood = countAttempt(ctx, row.user_id, now());
     if (flood) return send(res, flood.status, { ok: false, error: flood.message, code: flood.code }, flood.headers);
-    const body = { error: `This is an ${row.scope} token. Reviews take a review token; make one in the dashboard.`, code: 'forbidden' };
+    const body = { error: `This is ${row.scope === 'agent' ? 'an' : 'a'} ${row.scope} token. Reviews take a review token; make one in the dashboard.`, code: 'forbidden' };
     await audit(row.login, { reason: 'wrong-scope', token, scope: row.scope }, 403, body);
     return send(res, 403, { ok: false, ...body });
   }
@@ -182,10 +184,10 @@ const publicToken = ({ id, login, label, scope, created_at, expires_at, revoked_
  * @returns {Promise<boolean>} whether the path was one of these
  */
 export async function serveTokenRoutes(req, res, reqPath, ctx) {
-  const revoke = /^\/api\/(review|agent)-tokens\/([1-9]\d{0,9})\/revoke$/.exec(reqPath);
-  if (reqPath !== TOKENS_PATH && reqPath !== AGENT_TOKENS_PATH && !revoke) return false;
-  /** @type {'review' | 'agent'} the scope of the tokens this path is about */
-  const scope = revoke ? /** @type {'review' | 'agent'} */ (revoke[1]) : reqPath === AGENT_TOKENS_PATH ? 'agent' : 'review';
+  const revoke = /^\/api\/(review|agent|runner)-tokens\/([1-9]\d{0,9})\/revoke$/.exec(reqPath);
+  if (reqPath !== TOKENS_PATH && reqPath !== AGENT_TOKENS_PATH && reqPath !== RUNNER_TOKENS_PATH && !revoke) return false;
+  /** @type {import('./review-tokens.js').TokenScope} the scope of the tokens this path is about */
+  const scope = revoke ? /** @type {import('./review-tokens.js').TokenScope} */ (revoke[1]) : reqPath === AGENT_TOKENS_PATH ? 'agent' : reqPath === RUNNER_TOKENS_PATH ? 'runner' : 'review';
   const { config, auth, session } = ctx;
   const now = ctx.now ?? Date.now;
   const allow = revoke ? 'POST' : 'GET, POST';
@@ -197,7 +199,7 @@ export async function serveTokenRoutes(req, res, reqPath, ctx) {
   }
   if (!session || !auth.store) {
     req.resume();
-    send(res, 403, { ok: false, error: `${scope === 'agent' ? 'Agent' : 'Review'} tokens belong to a signed-in maintainer: set up sign-in first (docs/sign-in.md).`, code: 'forbidden' });
+    send(res, 403, { ok: false, error: `${scope === 'agent' ? 'Agent' : scope === 'runner' ? 'Runner' : 'Review'} tokens belong to a signed-in maintainer: set up sign-in first (docs/sign-in.md).`, code: 'forbidden' });
     return true;
   }
   const db = await auth.store();
@@ -214,7 +216,7 @@ export async function serveTokenRoutes(req, res, reqPath, ctx) {
     return true;
   }
   const what = revoke ? 'revoke' : 'mint';
-  const request = /** @type {Record<string, unknown>} */ ({ op: what, ...(scope === 'agent' ? { scope } : {}), ...(revoke ? { id: Number(revoke[2]) } : {}) });
+  const request = /** @type {Record<string, unknown>} */ ({ op: what, ...(scope !== 'review' ? { scope } : {}), ...(revoke ? { id: Number(revoke[2]) } : {}) });
   let rowId = null;
   /** @type {{ status: number, body: object }} */
   let out;

package/server/review-tokens.js

@@ -6,9 +6,9 @@
  * (server/agent-api.js). The store over the `review_tokens` table of `cornfield.db` (server/db.js); nothing here knows
  * about HTTP.
  *
- *   - **A token has a scope,** `review` or `agent`, and is good for the one API its scope names; each API refuses the other's
- *     token (403) and says so. One store serves both, so hashing, expiry, revoking, `last_used` and the limits are written
- *     once and cannot drift. A review token is `cf_rt_…` and an agent token `cf_at_…`, so a leaked one is told apart on
+ *   - **A token has a scope,** `review`, `agent` or `runner`, and is good for the one API its scope names; each API refuses the
+ *     others' tokens (403) and says so. One store serves both, so hashing, expiry, revoking, `last_used` and the limits are written
+ *     once and cannot drift. A review token is `cf_rt_…`, an agent token `cf_at_…` and a runner token `cf_nt_…`, so a leaked one is told apart on
  *     sight (and by a secret scanner). Rows from before scopes existed are review tokens.
  *   - A token is its prefix and 32 random bytes in base64url. It is shown once, when it is made; only its SHA-256 is
  *     kept. A presented token is found by the hash of what was presented (an indexed equality on a hash of a 256-bit
@@ -22,7 +22,7 @@
  *
  * Times are ISO strings, as everywhere in the file; `now` is milliseconds and is passed in, so tests need no clock.
  *
- * @typedef {'review' | 'agent'} TokenScope
+ * @typedef {'review' | 'agent' | 'runner'} TokenScope
  * @typedef {{ id: number, user_id: string, login: string, label: string, scope: TokenScope, created_at: string, expires_at: string, revoked_at: string | null, last_used: string | null }} TokenRow
  * @typedef {'active' | 'expired' | 'revoked' | 'wrong-scope'} TokenState  `wrong-scope` only from `findToken` asked for a scope
  */
@@ -30,8 +30,8 @@
 import { createHash, randomBytes } from 'node:crypto';
 
 /** The scopes a token may have, and what each one's tokens start with, so a leaked one is recognised (by a secret scanner too) */
-export const SCOPES = Object.freeze(['review', 'agent']);
-export const PREFIXES = Object.freeze({ review: 'cf_rt_', agent: 'cf_at_' });
+export const SCOPES = Object.freeze(['review', 'agent', 'runner']);
+export const PREFIXES = Object.freeze({ review: 'cf_rt_', agent: 'cf_at_', runner: 'cf_nt_' });
 /** What a review token starts with (the original, kept for the callers that always had it) */
 export const TOKEN_PREFIX = PREFIXES.review;
 /** Random bytes in a token */
@@ -43,7 +43,7 @@ export const MAX_ACTIVE = 20;
 export const MAX_LABEL = 60;
 const DAY_MS = 24 * 60 * 60 * 1000;
 /** A token as presented: the prefix and base64url (43 characters for 32 bytes); anything else is not one */
-const TOKEN_SHAPE = /^cf_(?:rt|at)_[A-Za-z0-9_-]{43,128}$/;
+const TOKEN_SHAPE = /^cf_(?:rt|at|nt)_[A-Za-z0-9_-]{43,128}$/;
 /** A label is words: letters, digits, spaces and a little punctuation. No backtick, no @, no newline: the comment quotes it */
 const LABEL = /^[\p{L}\p{N}][\p{L}\p{N} ._:/()-]*$/u;
 const COLUMNS = 'id, user_id, login, label, scope, created_at, expires_at, revoked_at, last_used';
@@ -55,6 +55,12 @@ export function hashToken(token) {
   return createHash('sha256').update(String(token)).digest('hex');
 }
 
+/** Which scope a presented token's shape names (by its prefix; the row's `scope` is what counts), or null when it is not shaped like one of ours */
+export function scopeOfShape(token) {
+  if (typeof token !== 'string' || !TOKEN_SHAPE.test(token)) return null;
+  return /** @type {TokenScope} */ (Object.keys(PREFIXES).find((k) => token.startsWith(PREFIXES[k])) ?? null);
+}
+
 /**
  * The token a request presents: the value of `Authorization: Bearer <token>`, or null when there is none, or it is
  * not shaped like one of ours (either scope's; which API it is good for is the row's `scope`) (the scheme is matched in any case, as RFC 9110 says).
@@ -159,6 +165,17 @@ export function listTokens(db, userId, now, scope) {
     .map((row) => ({ ...row, state: stateOf(row, now) }));
 }
 
+/**
+ * Revokes every live token of an owner, of every scope (review, agent, runner): what is done when cornfield learns they no longer maintain the
+ * repo. A token revoked already keeps its first time. Answers how many were revoked.
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {string} userId
+ * @param {number} now
+ */
+export function revokeOwnerTokens(db, userId, now) {
+  return Number(db.prepare('UPDATE review_tokens SET revoked_at = ? WHERE user_id = ? AND revoked_at IS NULL').run(iso(now), String(userId)).changes);
+}
+
 /**
  * Revokes one of an owner's tokens, for good. Another owner's id is no token to them. Revoking a token that is
  * revoked already keeps the first time.

package/server/runner-api.js

@@ -0,0 +1,270 @@
+/**
+ * @module server/runner-api
+ *
+ * The runner's side of the pull and push transports (issue #81, spec 0005 D2, D3, D5). The engine is server/agent-runs.js, the contract is
+ * core/agent-contract.js, and docs/agents.md says how a runner uses these routes. A runner behind NAT asks cornfield for work, claims it, and
+ * reports on it; a runner that was pushed a request (the `agent.requested` hook event) reports the same way.
+ *
+ *   GET  /api/agent-requests?state=queued      the queued requests (the contract's request JSON), oldest first, at most `QUEUE_LIMIT`
+ *   POST /api/agent-requests/<runId>/claim     claims one; a second claim of it is 409. Answers the request and the run
+ *   GET  /api/runs/<runId>                     { state, stopRequested, … } of a run this token holds: how a runner learns it was asked to stop
+ *   POST /api/runs/<runId>                     the report JSON ({ state, note?, url?, tokens?, cost? }), checked by the contract's `validateReport`
+ *
+ * **These routes take a runner token (`Authorization: Bearer cf_nt_…`) and nothing else,** as the review API takes a review token
+ * (server/review-api.js): they run before the sign-in guard (a runner has no cookie), read no cookie (a cookie is never a substitute, and a
+ * request that sends only one is 401), need no same-origin check (a browser never adds an `Authorization` header itself), and keep the `Host`
+ * check in front of every route. **The three scopes are kept apart both ways:** a review or an agent token here is 403 whatever else is true
+ * of it, and a runner token on any other route (the review API, the agent API, the dashboard's routes, the page itself) is 403 too
+ * (`serveStrayRunner`, which `server.js` calls before anything else is looked at).
+ *
+ * What a runner token may do, and nothing more: read the queue, claim, and read and report on **the runs it holds**. A pull run is held by the
+ * token that claimed it; a push run by the first token to report on it (nothing else tells a push run apart: the hook went to a URL, not a
+ * token). A run asked for on the forge is nobody's: its reports are `cornfield-run` comments. A token never reads a request it did not claim,
+ * and never anything of cornfield's besides.
+ *
+ * **Token states, the anonymous flood ceiling and the rows in `actions` follow the review API.** Every call is a row (`runner-list`,
+ * `runner-claim`, `runner-run`, `runner-report`, and `runner-call` for a token on the wrong route), with the token's id and label and the
+ * run id in the request, and the status and error in the answer, **never the token and never a note's words**. Two bounds keep the table from
+ * growing without end: past `RUNNER_PER_MINUTE` calls a minute a token is 429 and nothing is written, and an empty queue read is written down
+ * at most once every `EMPTY_LIST_ROW_MS` per token (a runner polls; a poll that finds nothing says little).
+ *
+ *   no token, or one that no row has    401 (`WWW-Authenticate: Bearer`), logged under `(no token)`; past `ANONYMOUS_PER_MINUTE` a minute 429 and no row
+ *   a review or an agent token          403, under its owner
+ *   a token that is revoked or expired  403, under its owner
+ *   a live runner token                 whatever the engine answers: 200, or 400, 403, 404, 409, 429
+ *
+ * **The token is not asked of the forge.** A runner has its own identity, and cornfield's forge sign-in of the token's owner may well have
+ * ended by the time a runner polls. What bounds a runner token is its scope, its expiry (90 days at most), that its owner revokes it in
+ * the dashboard at once, and that **an owner who stops maintaining the repo loses it**: whenever cornfield learns that (their sign-in, the
+ * 15-minute re-check, any question it puts to the forge with their token) all their API tokens are revoked (`auth.demoted`), and each call
+ * here also refuses, and revokes, when the owner's newest sign-in says they are not a maintainer (`auth.knownPermission`). No sign-in on
+ * record is no answer: the token goes on. (Review and agent tokens, which act as their owner on the forge, are checked against the forge on
+ * every call.)
+ *
+ * Nothing in an answer is a credential: the request is the contract's (validated again on the way out), and a run shows its state.
+ */
+
+import { readBody } from './proposals.js';
+import { ANONYMOUS_PER_MINUTE, NO_TOKEN_LOGIN } from './review-api.js';
+import { bearerOf, findToken, scopeOfShape, touchToken } from './review-tokens.js';
+import { QUEUE_LIMIT } from './agent-runs.js';
+import { refusal } from './submit-review.js';
+import { Refused, countAttempt } from './throttle.js';
+import { ForgeError, isMaintainer } from './forge.js';
+
+export const REQUESTS_PATH = '/api/agent-requests';
+/** Calls one runner token may make in a minute: a runner polls, so this is well over a person's ceiling */
+export const RUNNER_PER_MINUTE = 120;
+/** An empty queue read is written down at most this often per token */
+export const EMPTY_LIST_ROW_MS = 10 * 60_000;
+/** A report's body, in bytes: a note, a link and two numbers, with room */
+export const REPORT_LIMIT = 16 * 1024;
+const HEADERS = { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' };
+const RUN_ID = '(run-[0-9A-Za-z]{26})';
+const CLAIM = new RegExp(`^/api/agent-requests/${RUN_ID}/claim$`);
+const RUN = new RegExp(`^/api/runs/${RUN_ID}$`);
+
+function send(res, status, body, headers = {}) {
+  res.writeHead(status, { ...HEADERS, ...headers });
+  res.end(JSON.stringify(body));
+}
+
+/** The routes of this module: the action each is audited as, the run it names, and the methods it answers. Null for any other path. */
+export function runnerRoute(reqPath) {
+  let m;
+  if (reqPath === REQUESTS_PATH) return { action: 'runner-list', runId: null, allow: ['GET', 'HEAD'] };
+  if ((m = CLAIM.exec(reqPath))) return { action: 'runner-claim', runId: m[1], allow: ['POST'] };
+  if ((m = RUN.exec(reqPath))) return { action: 'runner-run', runId: m[1], allow: ['GET', 'HEAD', 'POST'] };
+  return null;
+}
+
+/** Whether a path is one that takes a bearer token of some scope (so a runner token on it is answered by that route, not as a stray) */
+export const takesTokens = (reqPath, { reviews }) => reqPath === reviews || reqPath === REQUESTS_PATH || runnerRoute(reqPath) !== null;
+
+/** The scope of a bearer token as the request presents it, by its shape alone (the row decides what it is worth) */
+export const presentedScope = (req) => scopeOfShape(bearerOf(req.headers.authorization));
+
+/** @type {WeakMap<object, Map<number, number>>} when each token's empty queue read was last written down */
+const emptyReads = new WeakMap();
+
+function emptyReadDue(auth, id, at) {
+  let m = emptyReads.get(auth);
+  if (!m) emptyReads.set(auth, (m = new Map()));
+  for (const [k, when] of m) if (at - when >= EMPTY_LIST_ROW_MS) m.delete(k);
+  if (m.has(id)) return false;
+  m.set(id, at);
+  return true;
+}
+
+/** What to answer for an error out of the engine: a refusal in words, or a plain 500 that says nothing of what went wrong */
+function answerFor(err) {
+  if (err instanceof Refused || err instanceof ForgeError) return refusal(err);
+  console.error(`[cornfield] a runner call failed: ${err instanceof Error ? err.stack || err.message : err}`);
+  return { status: 500, body: { error: 'Something went wrong in cornfield; the log says what.', code: 'unavailable' }, headers: {} };
+}
+
+/** @typedef {{ config: any, auth: any, runs: import('./agent-runs.js').Runs | null, now?: () => number }} RunnerContext */
+
+/**
+ * The runner routes. The caller has found the path to be one of `runnerRoute`'s; this runs before the sign-in guard.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {NonNullable<ReturnType<typeof runnerRoute>>} route
+ * @param {URL} url
+ * @param {RunnerContext} ctx
+ */
+export async function serveRunnerCall(req, res, route, url, ctx) {
+  const { config, auth, runs } = ctx;
+  const now = ctx.now ?? Date.now;
+  const method = req.method || 'GET';
+  if (!route.allow.includes(method)) {
+    req.resume();
+    return send(res, 405, { ok: false, error: 'Method not allowed.', code: 'invalid' }, { Allow: route.allow.join(', ') });
+  }
+  if (!auth.enabled || !runs) {
+    req.resume();
+    return send(res, 403, { ok: false, error: 'Runner tokens need sign-in and a forge: set them up first (docs/sign-in.md, docs/config.md#forge).', code: 'forbidden' });
+  }
+  const repo = config.forge.repo;
+  const audit = async (login, request, status, answer, target = repo) => {
+    try {
+      await auth.record({ login, action: route.action, target, request: { via: 'api', ...(route.runId ? { runId: route.runId } : {}), ...request }, status, answer });
+    } catch (err) {
+      console.error(`[cornfield] a runner call could not be written to the audit table: ${err instanceof Error ? err.message : err}`);
+    }
+  };
+  const refuse = async (login, request, status, body, headers = {}) => {
+    await audit(login, request, status, { error: body.error, code: body.code });
+    return send(res, status, { ok: false, ...body }, headers);
+  };
+
+  const presented = bearerOf(req.headers.authorization);
+  const db = presented ? await auth.store() : null;
+  const found = presented && db ? findToken(db, presented, now(), 'runner') : null;
+  if (!found) {
+    req.resume();
+    const flood = countAttempt(ctx, NO_TOKEN_LOGIN, now(), ANONYMOUS_PER_MINUTE);
+    if (flood) return send(res, flood.status, { ok: false, error: flood.message, code: flood.code }, flood.headers);
+    return refuse(NO_TOKEN_LOGIN, { reason: presented ? 'unknown-token' : 'no-token' }, 401,
+      { error: 'A runner token is needed: send "Authorization: Bearer cf_nt_…". A token is made in the dashboard; a sign-in is not taken in its place.', code: 'unauthorized' },
+      { 'WWW-Authenticate': 'Bearer realm="cornfield"' });
+  }
+
+  const { row, state } = found;
+  const token = { id: row.id, label: row.label };
+  if (state !== 'active') {
+    req.resume();
+    const flood = countAttempt(ctx, row.user_id, now());
+    if (flood) return send(res, flood.status, { ok: false, error: flood.message, code: flood.code }, flood.headers);
+    const wrong = state === 'wrong-scope';
+    return refuse(row.login, { reason: wrong ? 'wrong-scope' : state, token, ...(wrong ? { scope: row.scope } : {}) }, 403, {
+      error: wrong ? `This is ${row.scope === 'agent' ? 'an' : 'a'} ${row.scope} token. Runners take a runner token; make one in the dashboard.`
+        : state === 'revoked' ? 'This runner token was revoked; make a new one in the dashboard.' : 'This runner token has expired; make a new one in the dashboard.',
+      code: 'forbidden',
+    });
+  }
+  const flood = countAttempt(ctx, `runner|${row.id}`, now(), RUNNER_PER_MINUTE);
+  if (flood) {
+    req.resume();
+    return send(res, flood.status, { ok: false, error: flood.message, code: flood.code }, flood.headers);
+  }
+  // The cheap guard: what cornfield last heard of the owner's permission (their newest sign-in's). A runner needs no live sign-in, so no sign-in
+  // at all is no answer; one that says they no longer maintain the repo refuses the call and revokes their tokens there and then
+  const known = await auth.knownPermission(row.user_id);
+  if (known !== null && !isMaintainer(known)) {
+    req.resume();
+    await auth.demoted(row.user_id, row.login, known);
+    return refuse(row.login, { reason: 'owner-not-maintainer', token }, 403, { error: `This runner token's owner, ${row.login}, does not maintain ${repo} any more, so it is revoked.`, code: 'forbidden' });
+  }
+  touchToken(/** @type {import('node:sqlite').DatabaseSync} */ (db), row.id, now());
+  const who = row.login;
+
+  try {
+    if (route.action === 'runner-list') {
+      req.resume();
+      if (url.searchParams.get('state') !== 'queued') throw new Refused(400, 'The only listing is ?state=queued: the requests waiting for a runner.', 'invalid');
+      const requests = await runs.queued();
+      if (requests.length || emptyReadDue(auth, row.id, now())) await audit(who, { token }, 200, { ok: true, count: requests.length });
+      return send(res, 200, { ok: true, requests, limit: QUEUE_LIMIT });
+    }
+    if (route.action === 'runner-claim') {
+      req.resume();
+      const claimed = await runs.claim(token, route.runId);
+      await audit(who, { token }, 200, { ok: true, claimed: true }, `${repo}#${claimed.row.target}`);
+      return send(res, 200, { ok: true, request: claimed.request, run: claimed.run });
+    }
+    if (method === 'POST') {
+      let body;
+      let problem = null;
+      try {
+        const read = await readBody(req, REPORT_LIMIT);
+        if (read.tooLarge) problem = new Refused(413, `A report is at most ${REPORT_LIMIT / 1024} KB.`, 'invalid');
+        else {
+          try {
+            body = JSON.parse(read.text);
+          } catch {
+            // Not the parser's words: they quote the body, which the audit row would keep (a credential pasted in by mistake)
+            problem = new Refused(400, 'The body is not valid JSON.', 'invalid');
+          }
+        }
+      } catch {
+        problem = new Refused(400, 'The report could not be read.', 'invalid');
+      }
+      const shape = body && typeof body === 'object' && !Array.isArray(body) ? { ...(typeof body.state === 'string' && body.state.length <= 20 ? { state: body.state } : {}), ...(typeof body.note === 'string' ? { noteChars: body.note.length } : {}) } : {};
+      try {
+        if (problem) throw problem;
+        const done = await runs.report(token, route.runId, body);
+        await audit(who, { token, ...shape }, 200, { ok: true, state: done.row.state }, `${repo}#${done.row.target}`);
+        return send(res, 200, { ok: true, run: done.run });
+      } catch (err) {
+        const out = answerFor(err);
+        await audit(who, { token, ...shape }, out.status, { error: out.body.error, code: out.body.code });
+        return send(res, out.status, { ok: false, ...out.body }, out.headers);
+      }
+    }
+    req.resume();
+    const view = await runs.runnerGet(token, route.runId);
+    await audit(who, { token }, 200, { ok: true, state: view.state });
+    return send(res, 200, { ok: true, run: view });
+  } catch (err) {
+    const out = answerFor(err);
+    await audit(who, { token }, out.status, { error: out.body.error, code: out.body.code });
+    return send(res, out.status, { ok: false, ...out.body }, out.headers);
+  }
+}
+
+/**
+ * A runner token on a route that is not a runner's: 403, whatever the route would have said (even a path that does not exist). Called by
+ * `server.js` for any request that presents something shaped like a runner token on a path outside `takesTokens`, before the guard, the proxies
+ * and the page. A token that is a live runner's is counted under its own id, anything else under the anonymous ceiling; either way one row.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {string} reqPath
+ * @param {RunnerContext} ctx
+ */
+export async function serveStrayRunner(req, res, reqPath, ctx) {
+  const { config, auth } = ctx;
+  const now = ctx.now ?? Date.now;
+  req.resume();
+  const body = { ok: false, error: 'A runner token is good for the runner routes only (docs/agents.md#pull): listing, claiming and reporting on runs. Nothing else of cornfield takes it.', code: 'forbidden' };
+  const presented = bearerOf(req.headers.authorization);
+  let owner = null;
+  let token;
+  if (presented && auth.enabled) {
+    const found = findToken(await auth.store(), presented, now(), 'runner');
+    if (found && found.state !== 'wrong-scope') { owner = found.row.login; token = { id: found.row.id, label: found.row.label }; }
+  }
+  const flood = owner === null ? countAttempt(ctx, NO_TOKEN_LOGIN, now(), ANONYMOUS_PER_MINUTE) : countAttempt(ctx, `runner|${token.id}`, now(), RUNNER_PER_MINUTE);
+  if (flood) return send(res, flood.status, { ok: false, error: flood.message, code: flood.code }, flood.headers);
+  if (auth.enabled) {
+    try {
+      await auth.record({
+        login: owner ?? NO_TOKEN_LOGIN, action: 'runner-call', target: config.forge?.repo ?? '',
+        request: { via: 'api', reason: 'wrong-route', method: String(req.method).slice(0, 10), path: reqPath.slice(0, 80), ...(token ? { token } : {}) }, status: 403, answer: { error: body.error, code: body.code },
+      });
+    } catch (err) {
+      console.error(`[cornfield] a runner call could not be written to the audit table: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+  return send(res, 403, body);
+}

package/server/server.js

@@ -25,6 +25,9 @@
  *   *    /api/review-tokens…, /api/agent-tokens…
  *                                       make, list and revoke review tokens, and agent tokens: the signed-in maintainer only (server/review-api.js)
  *   POST /api/agent-requests            ask for an agent run with an agent token (`Authorization: Bearer cf_at_…`), no cookie: before the guard too (server/agent-api.js)
+ *   GET  /api/agent-requests, POST /api/agent-requests/<run>/claim, GET and POST /api/runs/<run>
+ *                                       a runner's: list the queue, claim, read and report, with a runner token (`cf_nt_…`) and no cookie, before the guard
+ *                                       too; a runner token on any other route is 403 (server/runner-api.js)
  *   *    /api/agent-runs…               the dashboard's runs: list, one, start, stop; the signed-in maintainer only (server/agent-api.js, server/agent-runs.js)
  *   *    /proposals…                    server/proposals.js (with sign-in, the open spec PRs too: server/proposal-pulls.js,
  *                                       and a review is a comment on one: server/reviews.js)
@@ -45,7 +48,7 @@ import http from 'node:http';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
-import { browserSources, BUILTIN_SOURCES, parseDuration, specPollMs, DEFAULTS, ideaLabel } from '../core/config.js';
+import { browserSources, BUILTIN_SOURCES, parseDuration, specPollMs, DEFAULTS, hookWants, ideaLabel } from '../core/config.js';
 import { CLOUD_FILE } from '../core/cloud.js';
 import { decodePath, inside, notFound, sendFile } from './files.js';
 import { serveProposals } from './proposals.js';
@@ -53,6 +56,7 @@ import { serveForge } from './forge-routes.js';
 import { hasAdapter } from './forge.js';
 import { createRuns } from './agent-runs.js';
 import { REQUESTS_PATH, serveAgentCall, serveRunRoutes } from './agent-api.js';
+import { presentedScope, runnerRoute, serveRunnerCall, serveStrayRunner, takesTokens } from './runner-api.js';
 import { REVIEWS_PATH, serveReviewCall, serveTokenRoutes } from './review-api.js';
 import { proxyTo } from './proxy.js';
 import { HA_ENV, homeAssistantHouse } from '../plugins/house/home-assistant.js';
@@ -166,6 +170,10 @@ export function createCornfieldServer(config, opts = {}) {
   }
   // Agent runs (server/agent-runs.js) need a signed-in maintainer to ask as and a forge to ask on; the runs are followed on the spec poll's tick
   const runs = config.forge && auth.enabled && hasAdapter(config.forge.type) ? createRuns({ config, where, auth, hooks, now: opts.now, onAsk: () => specPoll?.start() }) : null;
+  // Push and pull need the same two things a request on the forge does (a maintainer's sign-in to ask as, a forge to check against), and push needs the hook that delivers it
+  const transport = config.agents?.transport ?? 'forge';
+  if (transport !== 'forge' && !runs) throw new Error(`agents.transport is "${transport}", which needs sign-in and a forge to ask as a maintainer and to check them: set them up (docs/sign-in.md, docs/config.md#forge).`);
+  if (transport === 'push' && !hookWants(config, ['agent.requested'])) throw new Error('agents.transport is "push", so a hook must subscribe to agent.requested: add { url, events: ["agent.requested"] } to "hooks" (docs/config.md#hooks). Without one a request would go nowhere.');
   runs?.resume().catch((err) => console.error(`[cornfield] agent runs could not be picked up: ${err instanceof Error ? err.message : err}`));
   // Looks at the open spec PRs on a timer when a hook wants spec.ready (config `hookPoll`); started when the server listens. The same timer follows
   // agent runs: it is started for them when there is a run to follow, or as one is asked for, and does nothing while there is none
@@ -249,6 +257,9 @@ export function createCornfieldServer(config, opts = {}) {
       return res.end('400 Bad Request');
     }
 
+    // A runner token is good for the runner routes only: on any other route it is refused here, before anything else is looked at
+    if (presentedScope(req) === 'runner' && !takesTokens(reqPath, { reviews: REVIEWS_PATH })) return serveStrayRunner(req, res, reqPath, { config, auth, now: opts.now });
+
     if (reqPath === '/healthz') {
       req.resume();
       return sendJson(res, 200, { ok: true });
@@ -256,6 +267,9 @@ export function createCornfieldServer(config, opts = {}) {
     // The review API takes a token, not a session: it is the one route before the guard (and it reads no cookie)
     if (reqPath === REVIEWS_PATH) return serveReviewCall(req, res, { config, where, auth, hooks, lander, now: opts.now });
     // …and so does asking for a run: an agent token, not a session
+    // …and a runner asks for work and reports on it with a runner token (the GET of the same path lists the queue)
+    const runner = runnerRoute(reqPath);
+    if (runner && !(reqPath === REQUESTS_PATH && req.method !== 'GET' && req.method !== 'HEAD')) return serveRunnerCall(req, res, runner, url, { config, auth, runs, now: opts.now });
     if (reqPath === REQUESTS_PATH) return serveAgentCall(req, res, { config, auth, runs, now: opts.now });
     const gate = await auth.gate(req, res, reqPath, url);
     if (gate.done) return;