cornfield 0.2.0 → 0.4.0

package/server/proposals.js

@@ -19,8 +19,9 @@
  * holds it when the maintainer approves (`hashPullMockups`); every approval also carries `proposal`, the SHA-256 of the
  * proposal file at the head (`proposalHash`). The page never sends either, and a PUT that does is refused. The agent drafting the spec
  * reads it (`cornfield review <slug>`) and folds the edits into the proposal. The PUT is same-origin only
- * (`sameOrigin`), at most `REVIEW_LIMIT` bytes, checked by `validateReview`, and only for a proposal the forge
- * says the PR holds; it is written to the `actions` audit table. A proposal in the checkout or a worktree has no
+ * (`sameOrigin`), at most `REVIEW_LIMIT` bytes, and goes through `submitReview` (server/submit-review.js), the one path the review
+ * API shares: the review is checked, the maintainer asked of the forge now, and only a proposal the forge says the PR
+ * holds is reviewed; every attempt is written to the `actions` audit table. A proposal in the checkout or a worktree has no
  * PR yet, so there is nothing to review it on: the PUT answers 409 and says to push it as a spec PR. Stage 1 kept
  * the review in the data folder; `migrateStage1Reviews` carries those over once, when the menu is opened.
  *
@@ -43,10 +44,10 @@ import path from 'node:path';
 import { findProposalFile, listProposalFiles } from './files.js';
 import { summarize, proposalProblems } from '../core/proposal.js';
 import { ForgeError } from './forge.js';
-import { REVIEW_LIMIT, validateReview, latestReview, postReview, migrateStage1Reviews, proposalHash } from './reviews.js';
-import { proposalPayload } from './hooks.js';
+import { REVIEW_LIMIT, latestReview, migrateStage1Reviews } from './reviews.js';
+import { submitReview, refusal } from './submit-review.js';
 import { findPullProposal, forgeWords, listPullProposals, pullNumber, readPullProposal } from './proposal-pulls.js';
-import { hashPullMockups, serveMockups } from './mockups.js';
+import { serveMockups } from './mockups.js';
 
 // The review's checks live in server/reviews.js; these are re-exported for the callers that always had them here
 export { REVIEW_LIMIT, MAX_REVIEW_EDITS, MAX_NOTE_CHARS, validateReview } from './reviews.js';
@@ -261,28 +262,19 @@ async function putPullReview(req, res, where, forgeFor, signedIn, slug, n) {
   }
   // What an approval covers is the server's to record, from the files themselves, never the page's word
   if (parsed !== null && typeof parsed === 'object' && ('mockups' in parsed || 'proposal' in parsed)) return send(res, 400, { error: 'What an approval covers (the proposal and its mockups) is recorded by the server; a review does not send it.' });
-  const checked = validateReview(parsed);
-  if (!checked.ok) return send(res, 400, { error: checked.error });
   try {
-    const forge = forgeFor();
-    const entry = await findPullProposal(forge, where, slug, n);
-    if (!entry) return send(res, 404, { error: 'No such proposal' });
-    let review = checked.value;
-    if (review.verdict === 'approved') {
-      // The proposal as the head holds it now: a later push that changes it is not this approval's
-      review = { ...review, proposal: proposalHash(await readPullProposal(forge, where, entry)) };
-      const mockups = await hashPullMockups(forge, where, entry);
-      if (mockups.length) review = { ...review, mockups };
-    }
-    const posted = await postReview(forge, n, slug, review, { login: signedIn.login, record: signedIn.record });
-    signedIn.hooks?.emit(review.verdict === 'approved' ? 'spec.approved' : 'spec.sentBack', () => proposalPayload(forge, where, entry, { actor: signedIn.login, note: review.note, edits: review.edits }));
-    return send(res, 200, posted);
+    // The checks and the post are submitReview's, shared with the review API (server/submit-review.js)
+    const found = await submitReview({
+      forge: forgeFor, where, repo: signedIn.repo, who: { login: signedIn.login, userId: signedIn.userId }, record: signedIn.record, limits: signedIn.limits, hooks: signedIn.hooks, lander: signedIn.lander,
+    }, { pull: n, slug, review: parsed });
+    return send(res, 200, found);
   } catch (err) {
-    return send(res, forgeStatus(err), { error: forgeWords(err) });
+    const out = refusal(err);
+    return send(res, out.status, { error: out.body.error }, out.headers);
   }
 }
 
-/** @typedef {{ login: string, record: (entry: import('./reviews.js').AuditEntry) => Promise<void> | void, hooks?: import('./hooks.js').Hooks | null }} SignedIn */
+/** @typedef {{ login: string, userId: string, repo: string, record: (entry: import('./reviews.js').AuditEntry) => Promise<void> | void, limits: { auth: object, now?: () => number }, hooks?: import('./hooks.js').Hooks | null, lander?: import('./lander.js').Lander | null }} SignedIn who is signed in, the repo, where their actions are recorded, and what the flood and repeat limits count by */
 
 /**
  * Answers a request under `/proposals`, or returns false when it is not one.

package/server/review-api.js

@@ -0,0 +1,288 @@
+/**
+ * @module server/review-api
+ *
+ * The review API (spec 0002, issue #67): Approve or Send back from somewhere that is not the button, a script or a chat
+ * reaction, with a review token the maintainer made in the dashboard. The tokens are kept by the review-tokens module.
+ *
+ *   POST /api/reviews                    { pull, slug, sha256, verdict, note?, edits? }, with `Authorization: Bearer cf_rt_…`
+ *   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
+ *
+ * **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
+ * cookie-borne request it needs no same-origin check (a browser never adds an `Authorization` header by itself); the
+ * `Host` check in front of every route still applies. It is a review like the button's: both go through `submitReview`
+ * (server/submit-review.js), which asks the forge NOW whether the token's owner still maintains the repo (a demoted owner is
+ * 403), checks the proposal's SHA-256 at the PR's head (409), needs a note to send back (400), counts the flood and the
+ * repeat, and posts the comment as the owner with their kept sign-in (`auth.forgeForUser`; without a live one, 401). The
+ * comment says it came through the API and names the token's label.
+ *
+ * **Every call is a row in `actions`** (`review`, with the token's id and label in the request, never the token):
+ *
+ *   no token, or one that no row has    401 (`WWW-Authenticate: Bearer`), logged under `(no token)`. Past `ANONYMOUS_PER_MINUTE` a minute
+ *                                       nothing is written and the answer is 429, so anyone who can reach the server cannot fill the table
+ *   a token that is revoked or expired  403, under its owner
+ *   a live token                        whatever `submitReview` answers: 200 with the review, or 400, 401, 403, 404, 409, 429, 502
+ *
+ * The three routes under `/api/review-tokens` are for the signed-in maintainer only: they pass the sign-in guard like
+ * every other route, take a POST from cornfield's own page only (`sameOrigin`) with a JSON body, and a review token is
+ * no way to them (the guard reads cookies, never `Authorization`), so a token cannot make tokens. A token is
+ * made after the forge is asked who the maintainer is now, and the make and the revoke are rows in `actions` too
+ * (`review-token`), begun before the change is made.
+ */
+
+import { ForgeError, isMaintainer } from './forge.js';
+import { sameOrigin, readBody } from './proposals.js';
+import { REVIEW_LIMIT } from './reviews.js';
+import { MAX_ACTIVE, MAX_DAYS, DEFAULT_DAYS, bearerOf, daysOf, findToken, labelProblem, listTokens, mintToken, revokeToken, touchToken } from './review-tokens.js';
+import { refusal, submitReview } from './submit-review.js';
+import { Refused, countAttempt } from './throttle.js';
+
+export const REVIEWS_PATH = '/api/reviews';
+export const TOKENS_PATH = '/api/review-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 */
+export const NO_TOKEN_LOGIN = '(no token)';
+/** The keys of a call's body */
+const CALL_KEYS = ['pull', 'slug', 'sha256', 'verdict', 'note', 'edits'];
+const TOKEN_BODY_LIMIT = 4096;
+const HEADERS = { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' };
+
+function send(res, status, body, headers = {}) {
+  res.writeHead(status, { ...HEADERS, ...headers });
+  res.end(JSON.stringify(body));
+}
+
+const plainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/** @typedef {{ config: any, where: any, auth: any, hooks?: import('./hooks.js').Hooks | null, lander?: import('./lander.js').Lander | null, now?: () => number, publicHost?: string | null }} ApiContext */
+
+/**
+ * `POST /api/reviews`. The caller has found the path to be this one; this runs before the sign-in guard.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {ApiContext} ctx
+ */
+export async function serveReviewCall(req, res, ctx) {
+  const { config, where, auth } = ctx;
+  const now = ctx.now ?? Date.now;
+  if (!auth.enabled) {
+    req.resume();
+    return send(res, 403, { ok: false, error: 'Review tokens need sign-in: set it up first (docs/sign-in.md).', code: 'forbidden' });
+  }
+  if (req.method !== 'POST') {
+    req.resume();
+    return send(res, 405, { ok: false, error: 'A review is sent with POST.', code: 'invalid' }, { Allow: 'POST' });
+  }
+  const repo = config.forge.repo;
+  const audit = async (login, request, status, body, target = repo) => {
+    try {
+      await auth.record({ login, action: 'review', target, request: { via: 'api', ...request }, status, answer: { error: body.error, code: body.code } });
+    } catch (err) {
+      console.error(`[cornfield] a refused review call could not be written to the audit table: ${err instanceof Error ? err.message : err}`);
+    }
+  };
+
+  // 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;
+  if (!found) {
+    req.resume();
+    const reason = presented ? 'unknown-token' : 'no-token';
+    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);
+    const body = { error: 'A review token is needed: send "Authorization: Bearer cf_rt_…". A token is made in the dashboard; a sign-in is not taken in its place.', code: 'unauthorized' };
+    await audit(NO_TOKEN_LOGIN, { reason }, 401, body);
+    return send(res, 401, { ok: false, ...body }, { '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 body = { error: state === 'revoked' ? 'This review token was revoked; make a new one in the dashboard.' : 'This review token has expired; make a new one in the dashboard.', code: 'forbidden' };
+    await audit(row.login, { reason: state, token }, 403, body);
+    return send(res, 403, { ok: false, ...body });
+  }
+  touchToken(/** @type {import('node:sqlite').DatabaseSync} */ (db), row.id, now());
+
+  // The body: whatever is wrong with it is submitReview's to refuse, after the flood count and with a row
+  let input;
+  try {
+    const body = await readBody(req, REVIEW_LIMIT);
+    if (body.tooLarge) input = { problem: { status: 413, message: `A review is at most ${REVIEW_LIMIT / 1024} KB.` } };
+    else input = inputOf(body.text);
+  } catch {
+    input = { problem: { status: 400, message: 'The request could not be read.' } };
+  }
+  try {
+    const found = await submitReview({
+      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());
+        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.';
+      },
+    }, input);
+    return send(res, 200, { ok: true, ...found });
+  } catch (err) {
+    const out = refusal(err);
+    return send(res, out.status, { ok: false, ...out.body }, out.headers);
+  }
+}
+
+/** A call's body as `submitReview` takes it, or the problem with it */
+function inputOf(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    // Not the parser's words: they quote the body, which the audit row would then keep (a token pasted in by mistake)
+    return { problem: { status: 400, message: 'The body is not valid JSON.' } };
+  }
+  if (!plainObject(parsed)) return { problem: { status: 400, message: 'A review call is a JSON object: { pull, slug, sha256, verdict, note?, edits? }.' } };
+  const extra = Object.keys(parsed).find((k) => !CALL_KEYS.includes(k));
+  // What an approval covers (the proposal and its mockups) is recorded by the server from the files themselves
+  if (extra !== undefined) return { problem: { status: 400, message: `A review call has only pull, slug, sha256, verdict, note and edits, not "${extra}".` } };
+  const { pull, slug, sha256, ...review } = parsed;
+  return { pull, slug, sha256, review };
+}
+
+// ---------------------------------------------------------------------------
+//  The routes of the signed-in maintainer: make, list, revoke
+// ---------------------------------------------------------------------------
+
+/** 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 });
+
+/**
+ * The `/api/review-tokens` routes. The caller has passed the sign-in guard, so `session` is a maintainer's.
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {string} reqPath
+ * @param {ApiContext & { session: { login: string, userId: string } | null }} ctx
+ * @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 { config, auth, session } = ctx;
+  const now = ctx.now ?? Date.now;
+  const allow = revoke ? 'POST' : 'GET, POST';
+  const method = req.method;
+  if (!allow.split(', ').includes(method || '')) {
+    req.resume();
+    send(res, 405, { ok: false, error: 'Method not allowed.', code: 'invalid' }, { Allow: allow });
+    return true;
+  }
+  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' });
+    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 });
+    return true;
+  }
+
+  // A change: from cornfield's own page only, as JSON, counted and written down, and the forge asked who this is now
+  const flood = countAttempt(ctx, session.userId, now());
+  if (flood) {
+    req.resume();
+    send(res, flood.status, { ok: false, error: flood.message, code: flood.code }, flood.headers);
+    return true;
+  }
+  const what = revoke ? 'revoke' : 'mint';
+  const request = /** @type {Record<string, unknown>} */ ({ op: what, ...(revoke ? { id: Number(revoke[1]) } : {}) });
+  let rowId = null;
+  /** @type {{ status: number, body: object }} */
+  let out;
+  try {
+    try {
+      rowId = await auth.begin({ login: session.login, action: 'review-token', target: config.forge.repo, request });
+    } catch (err) {
+      console.error(`[cornfield] the audit row of a review token could not be written: ${err instanceof Error ? err.message : err}`);
+      throw new Refused(503, 'cornfield cannot write its audit log, so it will not change review tokens.', 'unavailable');
+    }
+    if (!sameOrigin(req, ctx.publicHost ?? null)) {
+      req.resume();
+      throw new Refused(403, 'Do this from cornfield\'s own page.', 'forbidden');
+    }
+    const body = revoke ? {} : await jsonBody(req);
+    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 (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');
+      request.label = done.label;
+      out = { status: 200, body: { ok: true, token: publicToken(done) } };
+    } else {
+      const unknown = Object.keys(body).find((k) => k !== 'label' && k !== 'days');
+      if (unknown !== undefined) throw new Refused(400, `A token has a label and, if you like, a number of days, not "${unknown}".`, 'invalid');
+      const problem = labelProblem(body.label);
+      if (problem) throw new Refused(400, problem, 'invalid');
+      let days;
+      try {
+        days = daysOf(body.days);
+      } catch (err) {
+        throw new Refused(400, err.message, 'invalid');
+      }
+      Object.assign(request, { label: body.label, days });
+      let made;
+      try {
+        made = mintToken(db, { userId: session.userId, login: me.login, label: body.label, days }, now());
+      } catch (err) {
+        if (err instanceof RangeError) throw new Refused(409, err.message, 'conflict');
+        throw err;
+      }
+      request.id = made.row.id;
+      // The token is in this answer and nowhere else: not in the audit row, not in a log
+      out = { status: 201, body: { ok: true, secret: made.token, token: publicToken({ ...made.row, state: 'active' }) } };
+    }
+  } catch (err) {
+    if (err instanceof Refused) out = { status: err.status, body: { ok: false, error: err.message, code: err.code } };
+    else if (err instanceof ForgeError) {
+      const r = refusal(err);
+      out = { status: r.status, body: { ok: false, ...r.body } };
+    } else {
+      console.error(`[cornfield] review token ${what}: ${err instanceof Error ? err.stack || err.message : err}`);
+      out = { status: 500, body: { ok: false, error: 'Something went wrong in cornfield; the log says what.', code: 'unavailable' } };
+    }
+  }
+  if (rowId !== null) {
+    try {
+      await auth.finish(rowId, { request, status: out.status, answer: 'error' in out.body ? { error: out.body.error, code: out.body.code } : { ok: true, id: request.id } });
+    } catch (err) {
+      console.error(`[cornfield] the audit row of a review token could not be finished: ${err instanceof Error ? err.message : err}`);
+    }
+  }
+  send(res, out.status, out.body);
+  return true;
+}
+
+/** A small JSON object body, or a Refused */
+async function jsonBody(req) {
+  if (!/^application\/json(?:\s*;|$)/i.test(String(req.headers['content-type'] || ''))) {
+    req.resume();
+    throw new Refused(415, 'Send the request as JSON (Content-Type: application/json).', 'invalid');
+  }
+  const body = await readBody(req, TOKEN_BODY_LIMIT);
+  if (body.tooLarge) throw new Refused(413, 'The request is too large for a token.', 'invalid');
+  let parsed;
+  try {
+    parsed = JSON.parse(body.text);
+  } catch {
+    throw new Refused(400, 'The request is not a JSON object.', 'invalid');
+  }
+  if (!plainObject(parsed)) throw new Refused(400, 'The request is not a JSON object.', 'invalid');
+  return parsed;
+}

package/server/review-tokens.js

@@ -0,0 +1,161 @@
+/**
+ * @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.
+ *
+ *   - A token is `cf_rt_` 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.
+ *   - It belongs to the maintainer who made it (their forge user id and login), has a label they chose (the review
+ *     comment names it), and expires: 30 days unless asked, 90 at most.
+ *   - It can be revoked, by its owner, at once and for good. `last_used` says when it was last presented while valid.
+ *   - What a token is worth is not kept in the row: the owner's maintainer status is asked of the forge on every call
+ *     (server/submit-review.js), so a token of someone who is demoted stops working with no row changed.
+ *
+ * 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
+ */
+
+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_';
+/** Random bytes in a token */
+export const TOKEN_BYTES = 32;
+export const DEFAULT_DAYS = 30;
+export const MAX_DAYS = 90;
+/** Live tokens one maintainer may hold at once */
+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}$/;
+/** 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 iso = (ms) => new Date(ms).toISOString();
+
+/** The SHA-256 of a token, as hex: what the table keeps */
+export function hashToken(token) {
+  return createHash('sha256').update(String(token)).digest('hex');
+}
+
+/**
+ * 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).
+ * @param {string | string[] | undefined} header
+ * @returns {string | null}
+ */
+export function bearerOf(header) {
+  if (typeof header !== 'string') return null;
+  const m = /^bearer[ \t]+(\S+)$/i.exec(header.trim());
+  return m && TOKEN_SHAPE.test(m[1]) ? m[1] : null;
+}
+
+/**
+ * What is wrong with a label, in words, or null.
+ * @param {unknown} label
+ */
+export function labelProblem(label) {
+  if (typeof label !== 'string' || !label.trim()) return 'Give the token a label: what will use it, like "chat bot".';
+  if (label.trim() !== label) return 'A label does not start or end with a space.';
+  if (label.length > MAX_LABEL) return `A label is at most ${MAX_LABEL} characters.`;
+  if (!LABEL.test(label)) return 'A label is letters, digits, spaces and . _ : / ( ) - only.';
+  return null;
+}
+
+/**
+ * How many days a token lasts, from what was asked: `DEFAULT_DAYS` when nothing was. Throws a `RangeError` in words.
+ * @param {unknown} days
+ */
+export function daysOf(days) {
+  if (days === undefined || days === null) return DEFAULT_DAYS;
+  if (typeof days !== 'number' || !Number.isInteger(days) || days < 1 || days > MAX_DAYS) throw new RangeError(`A token lasts 1 to ${MAX_DAYS} days.`);
+  return days;
+}
+
+/**
+ * Whether a row is usable at `now`.
+ * @param {TokenRow} row
+ * @param {number} now
+ * @returns {TokenState}
+ */
+export function stateOf(row, now) {
+  if (row.revoked_at) return 'revoked';
+  return Date.parse(row.expires_at) <= now ? 'expired' : 'active';
+}
+
+/**
+ * Makes a token for `owner`. The token is in the answer once; the table keeps its hash. Throws a `RangeError` in words
+ * 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 {number} now
+ * @returns {{ token: string, row: TokenRow }}
+ */
+export function mintToken(db, { userId, login, label, days }, now) {
+  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);
+  return { token, row: /** @type {TokenRow} */ (db.prepare(`SELECT ${COLUMNS} FROM review_tokens WHERE id = ?`).get(id)) };
+}
+
+/**
+ * The row a presented token names, with whether it is usable, or null when no token has that hash.
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {string} token what was presented
+ * @param {number} now
+ * @returns {{ row: TokenRow, state: TokenState } | null}
+ */
+export function findToken(db, token, now) {
+  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;
+}
+
+/** Notes that a token was presented (and valid) just now */
+export function touchToken(db, id, now) {
+  db.prepare('UPDATE review_tokens SET last_used = ? WHERE id = ?').run(iso(now), id);
+}
+
+/**
+ * An owner's tokens, newest first, each with its state. Never the hash, never the token.
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {string} userId
+ * @param {number} now
+ * @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)))
+    .map((row) => ({ ...row, state: stateOf(row, now) }));
+}
+
+/**
+ * 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.
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {string} userId
+ * @param {number} id
+ * @param {number} now
+ * @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) {
+  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.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) };
+}

package/server/reviews.js

@@ -41,6 +41,7 @@
  * @typedef {{ verdict: 'approved' | 'notes', note: string, edits: object[], mockups?: ReviewedMockup[], proposal?: string }} Review
  * @typedef {Review & { version: 1, slug: string, at: string, by: string, comment: { id: string, url: string } }} FoundReview
  * @typedef {{ login: string, action: string, target: string, request: object, status: number | null, answer: object | null }} AuditEntry
+ * @typedef {{ token: { id: number, label: string } }} ApiVia how a review reached cornfield when it was not the button: the review token it came with
  */
 
 import fs from 'node:fs';
@@ -49,6 +50,7 @@ import path from 'node:path';
 import { isMaintainer, ForgeError } from './forge.js';
 import { PROPOSAL_FILE } from './files.js';
 import { MAX_MOCKUPS, mockupPathProblem } from '../core/proposal.js';
+import { defuse } from './defuse.js';
 
 // ---------------------------------------------------------------------------
 //  The review a person sends
@@ -136,14 +138,19 @@ const FENCE = '```';
  * then the fenced block.
  * @param {string} slug
  * @param {Review} review
- * @param {{ login: string, carriedOver?: string }} by who sent it; `carriedOver` is the day of a Stage 1 review being migrated
+ * @param {{ login: string, carriedOver?: string, via?: ApiVia }} by who sent it; `carriedOver` is the day of a Stage 1 review being migrated;
+ *   `via` says it came through the review API (server/review-api.js) with the token of that label, which the line names (never the token)
  */
-export function reviewComment(slug, review, { login, carriedOver }) {
+export function reviewComment(slug, review, { login, carriedOver, via }) {
   const verdict = review.verdict === 'approved' ? 'Approved' : 'Sent back';
   const withEdits = review.edits.length ? ` with ${plural(review.edits.length, 'edit')}` : '';
-  const how = carriedOver ? `${login}, in cornfield on ${carriedOver}; carried over from before reviews were comments` : `${login}, in cornfield`;
+  const how = carriedOver ? `${login}, in cornfield on ${carriedOver}; carried over from before reviews were comments`
+    : via ? `${login}, through the review API with the token \`${via.token.label}\`` : `${login}, in cornfield`;
   const line = `${verdict} \`${slug}\`${withEdits} (${how}).`;
-  const quoted = review.note.trim() ? `\n\n${review.note.trim().split(/\r?\n/).map((l) => (l ? `> ${l}` : '>')).join('\n')}` : '';
+  // A note that came through the API may be relayed from anywhere (a chat): in the quote people read, its mentions and
+  // references are broken so it pings and links nobody. The block keeps the note as it was sent, for the agent.
+  const shown = via ? defuse(review.note.trim()) : review.note.trim();
+  const quoted = shown ? `\n\n${shown.split(/\r?\n/).map((l) => (l ? `> ${l}` : '>')).join('\n')}` : '';
   const json = JSON.stringify({ verdict: review.verdict, note: review.note, edits: review.edits, ...(review.mockups ? { mockups: review.mockups } : {}), ...(review.proposal ? { proposal: review.proposal } : {}) }, null, 2);
   return `${line}${quoted}\n\n${FENCE}${REVIEW_TAG} ${slug}\n${json}\n${FENCE}`;
 }
@@ -207,12 +214,12 @@ export async function latestReview(forge, n, slug, comments) {
  * @param {number} n
  * @param {string} slug
  * @param {Review} review a checked review (`validateReview`)
- * @param {{ login: string, record?: (entry: AuditEntry) => Promise<void> | void, carriedOver?: string }} who
+ * @param {{ login: string, record?: (entry: AuditEntry) => Promise<void> | void, carriedOver?: string, via?: ApiVia }} who `via`: the review came through the API, with this token (its id and label go in the comment and the audit row)
  * @returns {Promise<FoundReview>}
  */
-export async function postReview(forge, n, slug, review, { login, record, carriedOver }) {
+export async function postReview(forge, n, slug, review, { login, record, carriedOver, via }) {
   const target = `${forge.repo}#${n}`;
-  const request = { slug, ...review, ...(carriedOver ? { migrated: carriedOver } : {}) };
+  const request = { slug, ...review, ...(carriedOver ? { migrated: carriedOver } : {}), ...(via ? { via: 'api', token: via.token } : {}) };
   const audit = async (status, answer) => {
     if (!record) return;
     try {
@@ -221,7 +228,7 @@ export async function postReview(forge, n, slug, review, { login, record, carrie
       console.error(`[cornfield] the review of ${target} was posted but could not be written to the audit table: ${err.message}`);
     }
   };
-  const body = reviewComment(slug, review, { login, carriedOver });
+  const body = reviewComment(slug, review, { login, carriedOver, via });
   try {
     if (body.length > MAX_COMMENT_CHARS) throw new ForgeError(`That review is too long for a comment (${body.length} characters, at most ${MAX_COMMENT_CHARS}); shorten the note or send fewer edits.`, { code: 'invalid' });
     const comment = await forge.comment(n, body);
@@ -233,6 +240,22 @@ export async function postReview(forge, n, slug, review, { login, record, carrie
   }
 }
 
+/**
+ * Posts a plain note on PR `n`, as the token's user: the other thing cornfield says on a spec PR besides a review (server/lander.js:
+ * a landing on approval that was cancelled or left open). It goes by the same comment call as a review, with every mention and
+ * reference in it defused, since part of it (a check's name) is the forge's text and not cornfield's. The caller records it.
+ * Throws what the forge throws.
+ * @param {import('./forge.js').Forge} forge
+ * @param {number} n
+ * @param {string} text
+ * @returns {Promise<import('./forge.js').Comment>}
+ */
+export async function postNote(forge, n, text) {
+  const body = defuse(text);
+  if (body.length > MAX_COMMENT_CHARS) throw new ForgeError(`That note is too long for a comment (${body.length} characters, at most ${MAX_COMMENT_CHARS}).`, { code: 'invalid' });
+  return forge.comment(n, body);
+}
+
 // ---------------------------------------------------------------------------
 //  Stage 1 reviews, once
 // ---------------------------------------------------------------------------