cornfield 0.8.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

@@ -15,6 +15,10 @@
  *   thread_seen   the (repo, issue, comment) triples whose thread.* hook event was sent, and each thread's last-seen time, so a
  *                 restart sends none twice and a look asks the forge only for what is new (server/hooks.js, server/threads.js);
  *                 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)
  *
  * The schema is a list of numbered migrations (`MIGRATIONS`); the file's `PRAGMA user_version` is the number of
@@ -148,6 +152,86 @@ export const MIGRATIONS = Object.freeze([
     PRIMARY KEY (repo, issue, comment)
   ) STRICT;
   `,
+  // 7: agent runs (server/agent-runs.js, spec 0005): a table of the runs cornfield asked for, what it has seen of them, and a scope on
+  // the API tokens so one store holds review tokens and agent tokens
+  `
+  ALTER TABLE review_tokens ADD COLUMN scope TEXT NOT NULL DEFAULT 'review' CHECK (scope IN ('review', 'agent'));  -- what the token may call: POST /api/reviews, or POST /api/agent-requests
+
+  CREATE TABLE runs (
+    run_id            TEXT PRIMARY KEY,           -- run-<ulid>, minted with the request
+    repo              TEXT NOT NULL,              -- 'owner/name'
+    kind              TEXT NOT NULL,
+    profile           TEXT,
+    issue             INTEGER,                    -- what the run is about (at least one of the three)
+    proposal          TEXT,
+    thread            INTEGER,
+    target            INTEGER NOT NULL,           -- the issue or pull request the request, and the stop, were posted on
+    comment_id        TEXT NOT NULL DEFAULT '',   -- the request comment; '' while the post is in flight (the row already counts as open)
+    comment_url       TEXT,
+    request           TEXT NOT NULL CHECK (json_valid(request)),   -- the request as posted: no credential in it, ever
+    requested_by      TEXT NOT NULL,
+    requested_by_id   TEXT NOT NULL,
+    requested_at      TEXT NOT NULL,
+    via               TEXT NOT NULL DEFAULT 'dashboard',           -- 'dashboard' | 'api'
+    state             TEXT NOT NULL DEFAULT 'requested' CHECK (state IN ('requested', 'claimed', 'working', 'done', 'failed', 'stopped')),   -- the runner's latest report
+    reported_at       TEXT,
+    reported_by       TEXT,
+    note              TEXT,
+    url               TEXT,
+    tokens            INTEGER,
+    cost              REAL,
+    stop_requested_at TEXT,
+    stop_requested_by TEXT,
+    pull              INTEGER,                    -- the pull request that carries the run's id
+    pull_state        TEXT CHECK (pull_state IS NULL OR pull_state IN ('open', 'merged', 'closed')),
+    pull_url          TEXT,
+    pull_by           TEXT,
+    pull_trusted      INTEGER NOT NULL DEFAULT 0, -- 1 when its author is a runner, a listed agent author or a maintainer: only then does it move the state
+    linked_via        TEXT CHECK (linked_via IS NULL OR linked_via IN ('body', 'commit', 'branch')),
+    branch            TEXT,
+    head_sha          TEXT,
+    checks            TEXT CHECK (checks IS NULL OR checks IN ('success', 'failure', 'running', 'none')),
+    last_activity     TEXT NOT NULL               -- the latest report, push or pull request activity (or the request itself)
+  ) STRICT;
+  CREATE INDEX runs_repo ON runs (repo, requested_at);
+
+  CREATE TABLE run_seen (
+    run_id      TEXT NOT NULL,                    -- '' for what belongs to no run (a pull request's commits already read)
+    key         TEXT NOT NULL,                    -- 'c:<comment>:<n>' a block judged, 'ev:…' a hook event sent, 'commits:<pull>@<sha>'
+    at          TEXT NOT NULL,
+    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/forge-forgejo.js

@@ -82,6 +82,9 @@ const FILE_STATUS = { added: 'added', copied: 'added', deleted: 'removed', remov
 const toFile = (f) => ({ path: f.filename, status: FILE_STATUS[f.status] || 'modified', previousPath: f.previous_filename || null, additions: f.additions ?? 0, deletions: f.deletions ?? 0 });
 
 /** @returns {import('./forge.js').Comment} */
+/** @returns {import('./forge.js').PullCommit} */
+const toCommit = (c) => ({ sha: String(c.sha ?? ''), message: typeof c.commit?.message === 'string' ? c.commit.message : '' });
+
 const toComment = (c) => ({ id: String(c.id), author: author(c.user), body: c.body ?? '', url: c.html_url, createdAt: c.created_at, updatedAt: c.updated_at });
 
 // A warning does not count as passing, so it stands in the way like a failure
@@ -237,6 +240,10 @@ export function createForgejoForge(forge, { token = null, fetch, apiUrl, timeout
       return (await client.list(`repos/${repo}/pulls/${n}/files?limit=${PER_PAGE}`, { what: `the files of ${pullWhat(n)}` })).map(toFile);
     },
 
+    async pullCommits(n) {
+      return (await client.list(`repos/${repo}/pulls/${n}/commits?limit=${PER_PAGE}`, { what: `the commits of ${pullWhat(n)}` })).map(toCommit);
+    },
+
     async comments(n, { since } = {}) {
       return (await client.list(`repos/${repo}/issues/${n}/comments?limit=${PER_PAGE}${since ? `&since=${enc(since)}` : ''}`, { what: `the comments on #${n} in ${forge.repo}` })).map(toComment);
     },

package/server/forge-github.js

@@ -66,6 +66,9 @@ const toPull = (p) => ({
   url: p.html_url, createdAt: p.created_at, updatedAt: p.updated_at, mergedAt: p.merged_at ?? null,
 });
 
+/** @returns {import('./forge.js').PullCommit} */
+const toCommit = (c) => ({ sha: String(c.sha ?? ''), message: typeof c.commit?.message === 'string' ? c.commit.message : '' });
+
 const FILE_STATUS = { added: 'added', copied: 'added', removed: 'removed', renamed: 'renamed', modified: 'modified', changed: 'modified', unchanged: 'modified' };
 /** @returns {import('./forge.js').PullFile} */
 const toFile = (f) => ({ path: f.filename, status: FILE_STATUS[f.status] || 'modified', previousPath: f.previous_filename ?? null, additions: f.additions ?? 0, deletions: f.deletions ?? 0 });
@@ -230,6 +233,10 @@ export function createGitHubForge(forge, { token = null, fetch, apiUrl, timeoutM
       return (await client.list(`repos/${repo}/pulls/${n}/files?per_page=${PER_PAGE}`, { what: `the files of ${pullWhat(n)}` })).map(toFile);
     },
 
+    async pullCommits(n) {
+      return (await client.list(`repos/${repo}/pulls/${n}/commits?per_page=${PER_PAGE}`, { what: `the commits of ${pullWhat(n)}` })).map(toCommit);
+    },
+
     async comments(n, { since } = {}) {
       return (await client.list(`repos/${repo}/issues/${n}/comments?per_page=${PER_PAGE}${since ? `&since=${enc(since)}` : ''}`, { what: `the comments on #${n} in ${forge.repo}` })).map(toComment);
     },

package/server/forge.js

@@ -14,6 +14,7 @@
  *   issue(n)                          one issue (not a pull request: that is `not-found`)
  *   searchIssues(words)               the issues whose text holds the words (one page; the forge's search, which can lag a moment)
  *   pullFiles(n)                      the files a pull request changes
+ *   pullCommits(n)                    the commits of a pull request, oldest first: their shas and full messages (a run's trailer may be in one)
  *   comments(n, { since })            the comments on an issue or pull request, oldest first; `since` (an ISO time) only those
  *                                     created or edited after it, which is how a thread is followed without reading it all again
  *   comment(n, body)                  posts one, and answers it
@@ -55,6 +56,7 @@
  * @typedef {{ number: number, title: string, body: string, state: 'open' | 'closed' | 'merged', draft: boolean, author: Author | null, labels: string[], head: { ref: string, sha: string }, base: { ref: string }, url: string, createdAt: string, updatedAt: string, mergedAt: string | null }} Pull
  * @typedef {{ path: string, status: 'added' | 'modified' | 'removed' | 'renamed', previousPath: string | null, additions: number, deletions: number }} PullFile
  * @typedef {{ id: string, author: Author | null, body: string, url: string, createdAt: string, updatedAt: string }} Comment
+ * @typedef {{ sha: string, message: string }} PullCommit
  * @typedef {'queued' | 'running' | 'success' | 'failure' | 'neutral' | 'skipped' | 'cancelled'} CheckState
  * @typedef {{ id: string, name: string, state: CheckState, url: string | null, rerunnable: boolean }} Check
  * @typedef {{ name: string, sha: string, protected: boolean }} Branch
@@ -83,6 +85,7 @@
  *   createPull(pull: { title: string, body: string, head: string, base: string, draft: boolean }): Promise<Pull>,
  *   createIssue(issue: { title: string, body: string, labels?: string[] }): Promise<Issue>,
  *   pullFiles(n: number): Promise<PullFile[]>,
+ *   pullCommits(n: number): Promise<PullCommit[]>,
  *   comments(n: number, opts?: { since?: string }): Promise<Comment[]>,
  *   comment(n: number, body: string): Promise<Comment>,
  *   checks(ref: string): Promise<Check[]>,
@@ -114,7 +117,7 @@ import { ForgeError, FILE_MAX_BYTES } from './forge-http.js';
 export { ForgeError, rateLimitWords } from './forge-http.js';
 
 /** The calls of the interface (spec 0001 section 3, with `pull(n)`), and `rateLimit()`: what the last answer said is left */
-export const FORGE_METHODS = Object.freeze(['me', 'permission', 'issues', 'searchIssues', 'pulls', 'pull', 'issue', 'pullFiles', 'comments', 'comment', 'checks', 'rerun', 'merge', 'runs', 'branches', 'file', 'fileBytes', 'defaultBranch', 'tags', 'tag', 'createReleaseDraft', 'createBranch', 'createFile', 'createPull', 'createIssue', 'rateLimit']);
+export const FORGE_METHODS = Object.freeze(['me', 'permission', 'issues', 'searchIssues', 'pulls', 'pull', 'issue', 'pullFiles', 'pullCommits', 'comments', 'comment', 'checks', 'rerun', 'merge', 'runs', 'branches', 'file', 'fileBytes', 'defaultBranch', 'tags', 'tag', 'createReleaseDraft', 'createBranch', 'createFile', 'createPull', 'createIssue', 'rateLimit']);
 export const PERMISSIONS = Object.freeze(['admin', 'maintain', 'write', 'triage', 'read', 'none']);
 /** A check that has finished and does not stand in the way: success, or one the forge says does not count */
 export const GREEN_STATES = Object.freeze(['success', 'neutral', 'skipped']);
@@ -276,6 +279,7 @@ export function wrap(a, forge) {
       return a.searchIssues(words.trim());
     },
     pullFiles: async (n) => a.pullFiles(number(n)),
+    pullCommits: async (n) => a.pullCommits(number(n)),
     comments: async (n, opts) => {
       if (opts !== undefined && (opts === null || typeof opts !== 'object' || Array.isArray(opts))) throw invalid('The options are an object.');
       const since = opts && opts.since;

package/server/hooks.js

@@ -23,6 +23,11 @@
  *                  what is there and sends nothing; each (repo, thread, comment) is sent once, across restarts (`thread_seen`)
  *   session.expiring  a maintainer's sign-in ends within a day (`watchSessions`, below). Its body is its own:
  *                   `{ event, at, actor, expiresAt, mapUrl }`
+ *   agent.requested  a maintainer asked for an agent run (server/agent-runs.js). Its body is its own: `{ event, at, request, actor, mapUrl }`,
+ *                   `request` being the whole request JSON of the contract (docs/agent-contract.md), which holds no credential by construction
+ *   run.claimed  run.state  run.stopRequested  run.finished   a run was claimed by its runner, changed state, was asked to stop, ended. They are
+ *                   seen when cornfield looks (the spec poll, server/spec-poll.js), each once. Their body is their own:
+ *                   `{ event, at, runId, state, pull?, issue?, actor, mapUrl }`
  *
  * **A hook never gets in the way.** `emit` returns at once and never throws; the delivery runs in the background, from a
  * queue in memory. A failed delivery (a network error, a timeout, anything but a 2xx) is tried again after 1s, 5s and 30s
@@ -46,6 +51,7 @@ import { createHmac, randomUUID } from 'node:crypto';
 import { HOOK_EVENTS } from '../core/config.js';
 import { pullProposals, readPullProposal } from './proposal-pulls.js';
 import { proposalHash } from './reviews.js';
+import { validateRequest } from '../core/agent-contract.js';
 
 /** @typedef {ReturnType<typeof createHooks>} Hooks */
 
@@ -194,6 +200,19 @@ export function createHooks({ hooks, secret, fetch: doFetch = globalThis.fetch,
   function bodyOf(event, p) {
     // A session's end has no spec, pull request or proposal: its body is only who, until when, and where cornfield is
     if (event === 'session.expiring') return JSON.stringify({ event, at: new Date(now()).toISOString(), actor: p.actor ?? null, expiresAt: p.expiresAt ?? null, mapUrl: publicUrl || null });
+    // A request goes out as it was posted, and is checked once more on the way: nothing like a credential can leave through a hook
+    if (event === 'agent.requested') {
+      const checked = validateRequest(p.request);
+      if (!checked.ok) throw new Error(checked.error);
+      return JSON.stringify({ event, at: new Date(now()).toISOString(), request: checked.value, actor: p.actor ?? null, mapUrl: publicUrl || null });
+    }
+    // The events of a run (claimed, state, stopRequested, finished) say which run, in what state, and about what
+    if (event.startsWith('run.')) {
+      return JSON.stringify({
+        event, at: new Date(now()).toISOString(), runId: p.runId ?? null, state: p.state ?? null,
+        ...(p.pull != null ? { pull: p.pull } : {}), ...(p.issue != null ? { issue: p.issue } : {}), actor: p.actor ?? null, mapUrl: publicUrl || null,
+      });
+    }
     // A thread's event is only which thread, which comment, who and what it links to: never the words said
     if (event.startsWith('thread.')) {
       const out = { event, at: new Date(now()).toISOString(), thread: p.thread ?? null };

package/server/review-api.js

@@ -8,6 +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 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
@@ -41,6 +44,8 @@ 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 */
@@ -88,7 +93,7 @@ export async function serveReviewCall(req, res, ctx) {
   // The token, from the header alone; a cookie is not looked at
   const presented = bearerOf(req.headers.authorization);
   const db = presented ? await auth.store() : null;
-  const found = presented && db ? findToken(db, presented, now()) : null;
+  const found = presented && db ? findToken(db, presented, now(), 'review') : null;
   if (!found) {
     req.resume();
     const reason = presented ? 'unknown-token' : 'no-token';
@@ -101,6 +106,15 @@ export async function serveReviewCall(req, res, ctx) {
 
   const { row, state } = found;
   const token = { id: row.id, label: row.label };
+  // An agent token asks for runs and is no review token: refused whatever its state, and not counted as used
+  if (state === 'wrong-scope') {
+    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 ${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 });
+  }
   if (state !== 'active') {
     req.resume();
     const flood = countAttempt(ctx, row.user_id, now());
@@ -125,7 +139,7 @@ export async function serveReviewCall(req, res, ctx) {
       forge: () => auth.forgeForUser(row.user_id), where, repo, who: { login: row.login, userId: row.user_id },
       record: (entry) => auth.record(entry), limits: { auth, now: ctx.now }, via: { token }, requireSha256: true, hooks: ctx.hooks, lander: ctx.lander,
       stillAllowed: async () => {
-        const again = findToken(await auth.store(), /** @type {string} */ (presented), now());
+        const again = findToken(await auth.store(), /** @type {string} */ (presented), now(), 'review');
         if (again && again.state === 'active') return null;
         return again && again.state === 'expired' ? 'This review token expired while the review was being checked; nothing was posted.' : 'This review token was revoked while the review was being checked; nothing was posted.';
       },
@@ -159,7 +173,7 @@ function inputOf(text) {
 // ---------------------------------------------------------------------------
 
 /** What a token looks like to the dashboard: no hash, no secret */
-const publicToken = ({ id, login, label, created_at, expires_at, revoked_at, last_used, state }) => ({ id, login, label, created: created_at, expires: expires_at, revoked: revoked_at, lastUsed: last_used, state });
+const publicToken = ({ id, login, label, scope, created_at, expires_at, revoked_at, last_used, state }) => ({ id, login, label, scope, created: created_at, expires: expires_at, revoked: revoked_at, lastUsed: last_used, state });
 
 /**
  * The `/api/review-tokens` routes. The caller has passed the sign-in guard, so `session` is a maintainer's.
@@ -170,8 +184,10 @@ const publicToken = ({ id, login, label, created_at, expires_at, revoked_at, las
  * @returns {Promise<boolean>} whether the path was one of these
  */
 export async function serveTokenRoutes(req, res, reqPath, ctx) {
-  const revoke = /^\/api\/review-tokens\/([1-9]\d{0,9})\/revoke$/.exec(reqPath);
-  if (reqPath !== TOKENS_PATH && !revoke) return false;
+  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';
@@ -183,12 +199,12 @@ export async function serveTokenRoutes(req, res, reqPath, ctx) {
   }
   if (!session || !auth.store) {
     req.resume();
-    send(res, 403, { ok: false, error: '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();
   if (method === 'GET') {
-    send(res, 200, { ok: true, tokens: listTokens(db, session.userId, now()).map(publicToken), defaultDays: DEFAULT_DAYS, maxDays: MAX_DAYS, maxActive: MAX_ACTIVE });
+    send(res, 200, { ok: true, tokens: listTokens(db, session.userId, now(), scope).map(publicToken), defaultDays: DEFAULT_DAYS, maxDays: MAX_DAYS, maxActive: MAX_ACTIVE });
     return true;
   }
 
@@ -200,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, ...(revoke ? { id: Number(revoke[1]) } : {}) });
+  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;
@@ -219,10 +235,10 @@ export async function serveTokenRoutes(req, res, reqPath, ctx) {
     const forge = auth.forgeFor(session);
     const me = await forge.me();
     if (String(me.id) !== String(session.userId)) throw new Refused(403, 'The forge says this sign-in is someone else now; sign in again.', 'forbidden');
-    if (!isMaintainer(await forge.permission(config.forge.repo, me.login))) throw new Refused(403, `Only the repo's maintainers make review tokens; ${me.login} is not one now.`, 'forbidden');
+    if (!isMaintainer(await forge.permission(config.forge.repo, me.login))) throw new Refused(403, `Only the repo's maintainers make ${scope} tokens; ${me.login} is not one now.`, 'forbidden');
     if (revoke) {
-      const done = revokeToken(db, session.userId, Number(revoke[1]), now());
-      if (!done) throw new Refused(404, 'You have no review token by that number.', 'not-found');
+      const done = revokeToken(db, session.userId, Number(revoke[2]), now(), scope);
+      if (!done) throw new Refused(404, `You have no ${scope} token by that number.`, 'not-found');
       request.label = done.label;
       out = { status: 200, body: { ok: true, token: publicToken(done) } };
     } else {
@@ -239,7 +255,7 @@ export async function serveTokenRoutes(req, res, reqPath, ctx) {
       Object.assign(request, { label: body.label, days });
       let made;
       try {
-        made = mintToken(db, { userId: session.userId, login: me.login, label: body.label, days }, now());
+        made = mintToken(db, { userId: session.userId, login: me.login, label: body.label, days, scope }, now());
       } catch (err) {
         if (err instanceof RangeError) throw new Refused(409, err.message, 'conflict');
         throw err;

package/server/review-tokens.js

@@ -1,11 +1,16 @@
 /**
  * @module server/review-tokens
  *
- * Review tokens: what a maintainer hands a script or a chat bot so it can Approve or Send back a proposal through
- * `POST /api/reviews` (server/review-api.js). The store over the `review_tokens` table of `cornfield.db`
- * (server/db.js); nothing here knows about HTTP.
+ * API tokens: what a maintainer hands a script or a chat bot so it can Approve or Send back a proposal through
+ * `POST /api/reviews` (server/review-api.js), or ask for an agent run through `POST /api/agent-requests`
+ * (server/agent-api.js). The store over the `review_tokens` table of `cornfield.db` (server/db.js); nothing here knows
+ * about HTTP.
  *
- *   - A token is `cf_rt_` and 32 random bytes in base64url. It is shown once, when it is made; only its SHA-256 is
+ *   - **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
  *     secret, so there is no secret-dependent comparison to time); the token itself is never stored, logged or
  *     returned again.
@@ -17,14 +22,18 @@
  *
  * Times are ISO strings, as everywhere in the file; `now` is milliseconds and is passed in, so tests need no clock.
  *
- * @typedef {{ id: number, user_id: string, login: string, label: string, created_at: string, expires_at: string, revoked_at: string | null, last_used: string | null }} TokenRow
- * @typedef {'active' | 'expired' | 'revoked'} TokenState
+ * @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
  */
 
 import { createHash, randomBytes } from 'node:crypto';
 
-/** What every token starts with, so a leaked one is recognised (by a secret scanner too) */
-export const TOKEN_PREFIX = 'cf_rt_';
+/** 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', '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 */
 export const TOKEN_BYTES = 32;
 export const DEFAULT_DAYS = 30;
@@ -34,10 +43,10 @@ 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_[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, created_at, expires_at, revoked_at, last_used';
+const COLUMNS = 'id, user_id, login, label, scope, created_at, expires_at, revoked_at, last_used';
 
 const iso = (ms) => new Date(ms).toISOString();
 
@@ -46,9 +55,15 @@ 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 (the scheme is matched in any case, as RFC 9110 says).
+ * 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).
  * @param {string | string[] | undefined} header
  * @returns {string | null}
  */
@@ -96,21 +111,22 @@ export function stateOf(row, now) {
  * for a label or a number of days that is not allowed, or when the owner holds `MAX_ACTIVE` live tokens already.
  * Tokens that ended (expired or revoked) more than `MAX_DAYS` days ago are dropped on the way.
  * @param {import('node:sqlite').DatabaseSync} db
- * @param {{ userId: string, login: string, label: string, days?: number }} owner
+ * @param {{ userId: string, login: string, label: string, days?: number, scope?: TokenScope }} owner `scope`: `review` unless said
  * @param {number} now
  * @returns {{ token: string, row: TokenRow }}
  */
-export function mintToken(db, { userId, login, label, days }, now) {
+export function mintToken(db, { userId, login, label, days, scope = 'review' }, now) {
+  if (!SCOPES.includes(scope)) throw new RangeError(`A token's scope is one of ${SCOPES.join(', ')}.`);
   const problem = labelProblem(label);
   if (problem) throw new RangeError(problem);
   const lasts = daysOf(days);
   const nowIso = iso(now);
   db.prepare('DELETE FROM review_tokens WHERE COALESCE(revoked_at, expires_at) <= ?').run(iso(now - MAX_DAYS * DAY_MS));
-  const live = /** @type {{ n: number }} */ (db.prepare('SELECT COUNT(*) AS n FROM review_tokens WHERE user_id = ? AND revoked_at IS NULL AND expires_at > ?').get(String(userId), nowIso)).n;
-  if (live >= MAX_ACTIVE) throw new RangeError(`You hold ${MAX_ACTIVE} live tokens; revoke one you do not use before making another.`);
-  const token = `${TOKEN_PREFIX}${randomBytes(TOKEN_BYTES).toString('base64url')}`;
-  const id = Number(db.prepare('INSERT INTO review_tokens (token_hash, user_id, login, label, created_at, expires_at) VALUES (?, ?, ?, ?, ?, ?)')
-    .run(hashToken(token), String(userId), login, label, nowIso, iso(now + lasts * DAY_MS)).lastInsertRowid);
+  const live = /** @type {{ n: number }} */ (db.prepare('SELECT COUNT(*) AS n FROM review_tokens WHERE user_id = ? AND scope = ? AND revoked_at IS NULL AND expires_at > ?').get(String(userId), scope, nowIso)).n;
+  if (live >= MAX_ACTIVE) throw new RangeError(`You hold ${MAX_ACTIVE} live ${scope === 'review' ? '' : `${scope} `}tokens; revoke one you do not use before making another.`);
+  const token = `${PREFIXES[scope]}${randomBytes(TOKEN_BYTES).toString('base64url')}`;
+  const id = Number(db.prepare('INSERT INTO review_tokens (token_hash, user_id, login, label, scope, created_at, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?)')
+    .run(hashToken(token), String(userId), login, label, scope, nowIso, iso(now + lasts * DAY_MS)).lastInsertRowid);
   return { token, row: /** @type {TokenRow} */ (db.prepare(`SELECT ${COLUMNS} FROM review_tokens WHERE id = ?`).get(id)) };
 }
 
@@ -121,9 +137,12 @@ export function mintToken(db, { userId, login, label, days }, now) {
  * @param {number} now
  * @returns {{ row: TokenRow, state: TokenState } | null}
  */
-export function findToken(db, token, now) {
+export function findToken(db, token, now, scope) {
   const row = /** @type {TokenRow | undefined} */ (db.prepare(`SELECT ${COLUMNS} FROM review_tokens WHERE token_hash = ?`).get(hashToken(token)));
-  return row ? { row, state: stateOf(row, now) } : null;
+  if (!row) return null;
+  // The scope is part of the lookup, not of each route: a token found for another API, or whose prefix is not its scope's, is no token here
+  if (scope !== undefined && (row.scope !== scope || !String(token).startsWith(PREFIXES[row.scope]))) return { row, state: /** @type {const} */ ('wrong-scope') };
+  return { row, state: stateOf(row, now) };
 }
 
 /** Notes that a token was presented (and valid) just now */
@@ -132,17 +151,31 @@ export function touchToken(db, id, now) {
 }
 
 /**
- * An owner's tokens, newest first, each with its state. Never the hash, never the token.
+ * An owner's tokens of one scope (all of them when none is named), newest first, each with its state. Never the hash, never the token.
  * @param {import('node:sqlite').DatabaseSync} db
  * @param {string} userId
  * @param {number} now
+ * @param {TokenScope} [scope]
  * @returns {(TokenRow & { state: TokenState })[]}
  */
-export function listTokens(db, userId, now) {
-  return /** @type {TokenRow[]} */ (db.prepare(`SELECT ${COLUMNS} FROM review_tokens WHERE user_id = ? ORDER BY id DESC`).all(String(userId)))
+export function listTokens(db, userId, now, scope) {
+  return /** @type {TokenRow[]} */ (scope
+    ? db.prepare(`SELECT ${COLUMNS} FROM review_tokens WHERE user_id = ? AND scope = ? ORDER BY id DESC`).all(String(userId), scope)
+    : db.prepare(`SELECT ${COLUMNS} FROM review_tokens WHERE user_id = ? ORDER BY id DESC`).all(String(userId)))
     .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.
@@ -150,11 +183,12 @@ export function listTokens(db, userId, now) {
  * @param {string} userId
  * @param {number} id
  * @param {number} now
+ * @param {TokenScope} [scope] when named, a token of the other scope is no token to them here
  * @returns {(TokenRow & { state: TokenState }) | null} the token as it is now, or null when the owner has none by that id
  */
-export function revokeToken(db, userId, id, now) {
+export function revokeToken(db, userId, id, now, scope) {
   const row = /** @type {TokenRow | undefined} */ (db.prepare(`SELECT ${COLUMNS} FROM review_tokens WHERE id = ? AND user_id = ?`).get(id, String(userId)));
-  if (!row) return null;
+  if (!row || (scope && row.scope !== scope)) return null;
   if (!row.revoked_at) db.prepare('UPDATE review_tokens SET revoked_at = ? WHERE id = ?').run(iso(now), id);
   const after = /** @type {TokenRow} */ (db.prepare(`SELECT ${COLUMNS} FROM review_tokens WHERE id = ?`).get(id));
   return { ...after, state: stateOf(after, now) };