@popcorn245/cornfield 0.2.0 → 0.3.0

package/explorer/explorer.css

@@ -879,6 +879,16 @@ a.hx-forge-row:hover, button.hx-forge-row:hover { background: var(--hx-control-h
 .hx-confirm-pre:focus-visible { outline: 2px solid var(--hx-indigo); outline-offset: 2px; }
 .hx-confirm-note { margin: 0; color: var(--hx-text-2); line-height: 1.5; }
 .hx-confirm-actions { display: flex; justify-content: flex-end; gap: 8px; }
+.hx-tokens-list { display: flex; flex-direction: column; gap: 6px; margin: 0; padding: 0; list-style: none; }
+.hx-tokens-item { display: grid; grid-template-columns: 1fr auto; gap: 2px 8px; align-items: center; padding: 6px 8px; border-radius: 8px; border: 1px solid var(--hx-line); background: var(--hx-well-soft); }
+.hx-tokens-item[data-state="revoked"], .hx-tokens-item[data-state="expired"] { opacity: 0.65; }
+.hx-tokens-label { font-weight: 600; color: var(--hx-ink); overflow-wrap: anywhere; }
+.hx-tokens-meta { grid-column: 1; }
+.hx-tokens-item .hx-btn { grid-column: 2; grid-row: 1 / span 2; }
+.hx-tokens-row { display: flex; gap: 8px; align-items: center; }
+.hx-tokens-row .hx-forge-input { flex: 1; }
+.hx-tokens-form { display: grid; grid-template-columns: 1fr 5rem; gap: 8px; align-items: end; }
+.hx-tokens-form .hx-btn { grid-column: 1 / -1; justify-self: start; }
 .hx-forge-nodes { flex-basis: 100%; display: flex; flex-wrap: wrap; gap: 4px; padding-left: 62px; }
 .hx-forge-node { padding: 1px 8px; border-radius: 9999px; border: 1px solid var(--hx-amber); background: var(--hx-well-soft); color: var(--hx-text-2); font-size: 11px; }
 .hx-forge-node:hover { background: var(--hx-control-hover); }

package/explorer/index.html

@@ -103,6 +103,12 @@
         <span id="forge-btn-lit" class="hx-forge-lit" hidden></span>
       </button>
 
+      <!-- Review tokens (explorer/review-tokens.js): shown only when somebody is signed in to a forge -->
+      <button type="button" id="tokens-btn" class="hx-btn" aria-haspopup="dialog" aria-expanded="false" aria-controls="tokens-dialog" aria-label="Review tokens" title="Review tokens: let a script or a chat bot approve or send back a proposal as you" hidden>
+        <span aria-hidden="true">⚿</span>
+        <span class="hx-only-wide">Review tokens</span>
+      </button>
+
       <!-- The live layer's chip (explorer/live.js, spec 0029): shown once a live layer is on; a dot on a phone, its line on tap -->
       <div id="live-wrap" class="hx-menu-wrap hx-live" data-tone="idle" hidden>
         <button type="button" id="live-chip" class="hx-btn hx-live-chip" aria-haspopup="true" aria-expanded="false" aria-label="Live layer">
@@ -315,6 +321,32 @@
     </div>
   </div>
 
+  <!-- Review tokens (review-tokens.js): make one (shown once), list them, revoke; a modal dialog over a scrim, the focus stays in it -->
+  <div id="tokens-dialog" class="hx-confirm-scrim" hidden>
+    <div class="hx-confirm glass" role="dialog" aria-modal="true" aria-labelledby="tokens-title" aria-describedby="tokens-intro">
+      <h2 id="tokens-title" class="hx-confirm-title" tabindex="-1">Review tokens</h2>
+      <p id="tokens-intro" class="hx-confirm-note">A review token lets a script or a chat bot approve or send back a proposal as you (<code class="hx-code">POST /api/reviews</code>). It works while you are signed in here and still maintain the repo; it expires, and you can revoke it below.</p>
+      <p id="tokens-msg" class="hx-forge-msg" role="status" hidden></p>
+      <div id="tokens-secret" class="hx-tokens-secret" hidden>
+        <label class="hx-forge-field" for="tokens-secret-value">Your new token (copy it now, it is not shown again)</label>
+        <div class="hx-tokens-row">
+          <input id="tokens-secret-value" class="hx-forge-input hx-mono" type="text" readonly spellcheck="false" autocomplete="off" />
+          <button type="button" class="hx-btn" data-tokens-copy>Copy</button>
+        </div>
+      </div>
+      <ul id="tokens-list" class="hx-tokens-list" aria-label="Your review tokens"></ul>
+      <form id="tokens-form" class="hx-tokens-form" autocomplete="off">
+        <label class="hx-forge-field">Label<input id="tokens-label" class="hx-forge-input" type="text" maxlength="60" placeholder="chat bot" /></label>
+        <label class="hx-forge-field">Days<input id="tokens-days" class="hx-forge-input" type="text" inputmode="numeric" maxlength="2" aria-describedby="tokens-days-hint" /></label>
+        <span id="tokens-days-hint" class="hx-sr-only"></span>
+        <button type="submit" id="tokens-make" class="hx-btn hx-btn--approve">Make a token</button>
+      </form>
+      <div class="hx-confirm-actions">
+        <button type="button" class="hx-btn" data-tokens-close>Close</button>
+      </div>
+    </div>
+  </div>
+
   <script type="module" src="/explorer/main.js"></script>
 </body>
 </html>

package/explorer/main.js

@@ -17,6 +17,7 @@
  *   bench.js    /?bench=1 stopwatch and /?fixture=5k (the generated topology, from the server)
  *   keyboard.js the map by keyboard and the screen reader's announcer; keyboard-model.js its pure half
  *   live.js     the live layer: the chip, polling, laying a live source's answer over the map; live-model.js its pure half
+ *   review-tokens.js  review tokens for the review API, when somebody is signed in: make one (shown once), list, revoke; review-tokens-model.js its pure half
  *   forge-panel.js  the issues and PRs panel, when the config names a forge: a PR lights the nodes it changes; forge-panel-model.js its pure half
  *   theme.js    light or dark: the system setting and the header toggle; theme-model.js the colours (theme-boot.js before the first paint)
  */
@@ -41,6 +42,7 @@ import { initHouse } from './house.js';
 import { initChecks } from './check.js';
 import { initKeyboard } from './keyboard.js';
 import { initForgePanel } from './forge-panel.js';
+import { initReviewTokens } from './review-tokens.js';
 import { loadClientConfig, loadSources, applyBranding } from './plugins.js';
 import { cycleTheme, initTheme } from './theme.js';
 
@@ -207,6 +209,7 @@ loadTopology().then(async (ok) => {
   const config = await configReady;
   const { liveSource, floorRenderer, checker } = await loadSources(config);
   initForgePanel(config); // issues and PRs: only when the config names a forge (forge-panel.js)
+  initReviewTokens(config); // review tokens for the review API: only for somebody signed in (review-tokens.js)
   initWhatIf(); // before a proposal can open, so its edits come with it
   initReview(); // after it: the review controls sit under the edit controls on the bar
   initMockups(); // a proposal's screens open from the node they name

package/explorer/review-tokens-model.js

@@ -0,0 +1,86 @@
+/**
+ * @module explorer/review-tokens-model
+ *
+ * The pure half of the review tokens panel (spec 0002): no DOM, no `window`, no clock (the time is passed in).
+ * review-tokens.js is the half that touches the page and the network; the words and the request are decided here so
+ * they can be tested without a page.
+ *
+ *   TOKENS_URL         the server's address for them (server/review-api.js)
+ *   makeRequest        what a new token's form sends: { label, days? }, or why it cannot be sent yet
+ *   tokenLine          one token as the list shows it: its label, its state, when it ends, when it was last used
+ *   revokeUrl          the address that revokes one
+ *   errorWords         what a refusal of the server says, in plain words
+ *
+ * The server answers a list as `{ ok, tokens: [{ id, login, label, created, expires, revoked, lastUsed, state }], defaultDays, maxDays, maxActive }`
+ * and a new token as `{ ok, secret, token }`: the secret is in that answer only.
+ */
+
+import { relativeTime } from './review-model.js';
+
+export const TOKENS_URL = '/api/review-tokens';
+export const DEFAULT_DAYS = 30;
+export const MAX_DAYS = 90;
+export const MAX_LABEL = 60;
+const DAY = 24 * 60 * 60 * 1000;
+const HOUR = 60 * 60 * 1000;
+const LABEL = /^[\p{L}\p{N}][\p{L}\p{N} ._:/()-]*$/u;
+
+/** The address that revokes token `id` */
+export const revokeUrl = (id) => `${TOKENS_URL}/${encodeURIComponent(String(id))}/revoke`;
+
+/**
+ * What the form sends: the label, and the days when they were given. The server checks everything again.
+ * @param {string} label
+ * @param {string} days what the field holds; empty is the default
+ * @returns {{ ok: true, body: { label: string, days?: number } } | { ok: false, error: string }}
+ */
+export function makeRequest(label, days) {
+  const text = typeof label === 'string' ? label.trim() : '';
+  if (!text) return { ok: false, error: 'Give the token a label: what will use it, like "chat bot".' };
+  if (text.length > MAX_LABEL) return { ok: false, error: `A label is at most ${MAX_LABEL} characters.` };
+  if (!LABEL.test(text)) return { ok: false, error: 'A label is letters, digits, spaces and . _ : / ( ) - only.' };
+  const d = typeof days === 'string' ? days.trim() : '';
+  if (d === '') return { ok: true, body: { label: text } };
+  if (!/^\d{1,3}$/.test(d) || Number(d) < 1 || Number(d) > MAX_DAYS) return { ok: false, error: `A token lasts 1 to ${MAX_DAYS} days.` };
+  return { ok: true, body: { label: text, days: Number(d) } };
+}
+
+/** "in 12 days", "in 5 hours", "in under an hour", or "" for a time that does not read or is not ahead */
+function untilWords(iso, nowMs) {
+  const then = typeof iso === 'string' ? Date.parse(iso) : NaN;
+  if (!Number.isFinite(then) || !Number.isFinite(nowMs) || then <= nowMs) return '';
+  const left = then - nowMs;
+  if (left < HOUR) return 'in under an hour';
+  if (left < DAY) { const h = Math.floor(left / HOUR); return `in ${h} hour${h === 1 ? '' : 's'}`; }
+  const d = Math.floor(left / DAY);
+  return `in ${d} day${d === 1 ? '' : 's'}`;
+}
+
+/**
+ * One token as the list shows it.
+ * @param {{ id: number, label: string, expires: string, revoked: string | null, lastUsed: string | null, state: string }} token
+ * @param {number} nowMs
+ * @returns {{ id: number, label: string, state: 'active' | 'expired' | 'revoked', status: string, used: string, canRevoke: boolean }}
+ */
+export function tokenLine(token, nowMs) {
+  const state = token.state === 'revoked' || token.state === 'expired' ? token.state : 'active';
+  const status = state === 'revoked' ? `Revoked ${relativeTime(token.revoked, nowMs)}`.trim()
+    : state === 'expired' ? `Expired ${relativeTime(token.expires, nowMs)}`.trim()
+      : `Expires ${untilWords(token.expires, nowMs)}`.trim();
+  const used = token.lastUsed ? `Last used ${relativeTime(token.lastUsed, nowMs)}` : 'Never used';
+  return { id: token.id, label: String(token.label), state, status, used, canRevoke: state !== 'revoked' };
+}
+
+/**
+ * What a refusal says, in plain words: the server's own where it gave some.
+ * @param {number | null} status null when the server could not be reached
+ * @param {{ error?: string } | null} body
+ */
+export function errorWords(status, body) {
+  if (status === null) return 'cornfield could not be reached. Try again in a moment.';
+  if (status === 401) return 'Your sign-in has ended. Sign in again.';
+  if (body && typeof body.error === 'string' && body.error) return body.error;
+  if (status === 403) return 'Only the repo\'s maintainers can do that.';
+  if (status === 429) return 'Too many tries. Wait a little.';
+  return 'That did not work. Try again in a moment.';
+}

package/explorer/review-tokens.js

@@ -0,0 +1,216 @@
+/**
+ * @module explorer/review-tokens
+ *
+ * Review tokens in the dashboard (spec 0002, server/review-api.js): a signed-in maintainer makes a token so a script or a
+ * chat bot can Approve or Send back a proposal as them (`POST /api/reviews`), sees the tokens they hold and revokes one.
+ * A header button opens a dialog over the map (a scrim, `aria-modal`, the focus stays in it, Escape and Close give it
+ * back to the button). Shown only when the config names a forge and somebody is signed in: without sign-in there are no
+ * tokens.
+ *
+ *   GET  /api/review-tokens              the list: label, when it ends, when it was last used
+ *   POST /api/review-tokens              { label, days? } -> the new token, **in that answer only**
+ *   POST /api/review-tokens/<id>/revoke  ends one
+ *
+ * A new token is put in a read-only field with a Copy button and the words that it is not shown again; it lives in
+ * that field and nowhere else (not in a variable, a storage or an announcement for a screen reader), and Close or
+ * making another empties it. The list never holds a secret; the server has only a hash.
+ *
+ * The words and the request are review-tokens-model.js, tested without a page.
+ */
+
+import { escHtml } from './state.js';
+import { announce } from './keyboard.js';
+import { TOKENS_URL, DEFAULT_DAYS, MAX_DAYS, makeRequest, revokeUrl, tokenLine, errorWords } from './review-tokens-model.js';
+
+const $ = (id) => document.getElementById(id);
+let wired = false;
+let now = () => Date.now();
+const ui = { open: false, busy: false, tokens: [], loaded: false, message: null };
+
+const dialog = () => $('tokens-dialog');
+
+async function request(method, url, payload) {
+  try {
+    const res = await fetch(url, { method, cache: 'no-store', headers: payload === undefined ? {} : { 'Content-Type': 'application/json' }, ...(payload === undefined ? {} : { body: JSON.stringify(payload) }) });
+    let body = null;
+    try { body = await res.json(); } catch { /* no body */ }
+    return { ok: !!res.ok && !!body && body.ok === true, status: res.status, body };
+  } catch {
+    return { ok: false, status: null, body: null };
+  }
+}
+
+function say(text, ok = true) {
+  ui.message = text ? { text, ok } : null;
+  paint();
+  if (text) announce(text);
+}
+
+/** Everything the dialog shows, from `ui` */
+function paint() {
+  if (!dialog()) return;
+  const list = $('tokens-list');
+  if (!ui.loaded) list.innerHTML = '<li class="hx-faint">Loading …</li>';
+  else if (!ui.tokens.length) list.innerHTML = '<li class="hx-faint">You have no review tokens yet.</li>';
+  else {
+    list.innerHTML = ui.tokens.map((t) => {
+      const line = tokenLine(t, now());
+      return `<li class="hx-tokens-item" data-state="${line.state}"><span class="hx-tokens-label">${escHtml(line.label)}</span> <span class="hx-tokens-meta hx-faint">${escHtml(line.status)} · ${escHtml(line.used)}</span> ${line.canRevoke ? `<button type="button" class="hx-btn hx-btn--quiet" data-revoke="${escHtml(String(line.id))}" aria-label="Revoke ${escHtml(line.label)}"${ui.busy ? ' disabled' : ''}>Revoke</button>` : ''}</li>`;
+    }).join('');
+  }
+  const msg = $('tokens-msg');
+  msg.hidden = !ui.message;
+  msg.textContent = ui.message ? ui.message.text : '';
+  msg.classList.toggle('hx-forge-msg--bad', !!ui.message && !ui.message.ok);
+  $('tokens-make').disabled = ui.busy;
+}
+
+async function load() {
+  const res = await request('GET', TOKENS_URL);
+  if (res.ok && Array.isArray(res.body.tokens)) {
+    ui.tokens = res.body.tokens;
+    ui.loaded = true;
+    paint();
+    return;
+  }
+  ui.loaded = true;
+  ui.tokens = [];
+  say(errorWords(res.status, res.body), false);
+}
+
+function clearSecret() {
+  const box = $('tokens-secret');
+  $('tokens-secret-value').value = '';
+  box.hidden = true;
+}
+
+async function make(e) {
+  e.preventDefault();
+  if (ui.busy) return;
+  const checked = makeRequest($('tokens-label').value, $('tokens-days').value);
+  if (!checked.ok) { say(checked.error, false); $('tokens-label').focus(); return; }
+  clearSecret();
+  ui.busy = true;
+  say('');
+  const res = await request('POST', TOKENS_URL, checked.body);
+  ui.busy = false;
+  if (!res.ok || typeof res.body.secret !== 'string') { say(errorWords(res.status, res.body), false); return; }
+  // The one time the secret is seen: in the field, and not in a live region
+  $('tokens-secret-value').value = res.body.secret;
+  $('tokens-secret').hidden = false;
+  $('tokens-label').value = '';
+  $('tokens-days').value = '';
+  say(`Made the token "${res.body.token.label}". Copy it now: it is not shown again.`);
+  $('tokens-secret-value').focus();
+  $('tokens-secret-value').select();
+  await load();
+}
+
+async function revoke(id) {
+  if (ui.busy) return;
+  ui.busy = true;
+  paint();
+  const res = await request('POST', revokeUrl(id), {});
+  ui.busy = false;
+  if (!res.ok) say(errorWords(res.status, res.body), false);
+  else say(`Revoked "${res.body.token.label}". It no longer works.`);
+  await load();
+}
+
+async function copy() {
+  const field = $('tokens-secret-value');
+  try {
+    await navigator.clipboard.writeText(field.value);
+    announce('Copied.');
+    say('Copied. It is not shown again.');
+  } catch {
+    field.focus();
+    field.select();
+    say('Select the token and copy it by hand.', false);
+  }
+}
+
+/** While the dialog is open the focus cannot leave it */
+function keepFocusIn(e) {
+  const el = dialog();
+  if (ui.open && el && !el.contains(e.target)) $('tokens-title').focus();
+}
+
+export function openTokens() {
+  const el = dialog();
+  if (!el || ui.open) return;
+  ui.open = true;
+  ui.loaded = false;
+  ui.message = null;
+  document.addEventListener('focusin', keepFocusIn);
+  el.hidden = false;
+  $('tokens-btn').setAttribute('aria-expanded', 'true');
+  paint();
+  $('tokens-title').focus();
+  load();
+}
+
+export function closeTokens({ restoreFocus = true } = {}) {
+  const el = dialog();
+  if (!el || !ui.open) return;
+  ui.open = false;
+  clearSecret();
+  el.hidden = true;
+  document.removeEventListener('focusin', keepFocusIn);
+  $('tokens-btn').setAttribute('aria-expanded', 'false');
+  if (restoreFocus) $('tokens-btn').focus();
+}
+
+function onClick(e) {
+  if (e.target === dialog()) { closeTokens(); return; } // the scrim
+  const t = e.target.closest ? e.target.closest('button') : null;
+  if (!t) return;
+  if (t.hasAttribute('data-tokens-close')) closeTokens();
+  else if (t.hasAttribute('data-tokens-copy')) copy();
+  else if (t.hasAttribute('data-revoke')) revoke(t.getAttribute('data-revoke'));
+}
+
+/** Escape closes; Tab stays inside; nothing reaches the map behind */
+function onKey(e) {
+  e.stopPropagation();
+  if (e.key === 'Escape') { e.preventDefault(); closeTokens(); return; }
+  if (e.key !== 'Tab') return;
+  const items = [...dialog().querySelectorAll('button:not([disabled]), input:not([disabled])')].filter((el) => !el.closest('[hidden]'));
+  if (!items.length) { e.preventDefault(); return; }
+  const at = items.indexOf(document.activeElement);
+  const next = e.shiftKey ? (at <= 0 ? items.length - 1 : at - 1) : (at === -1 || at === items.length - 1 ? 0 : at + 1);
+  e.preventDefault();
+  items[next].focus();
+}
+
+/**
+ * Wires the button and the dialog (main.js calls this once the config is read). With no forge in the config, or nobody
+ * signed in, both stay hidden, and this returns false.
+ * @param {{ forge?: { type: string, repo: string } | null, signIn?: false | { login: string } }} config what `/cornfield/config.json` said
+ * @param {{ clock?: () => number }} [opts] `clock` for the times shown (tests)
+ * @returns {boolean} whether it is on
+ */
+export function initReviewTokens(config, opts = {}) {
+  const btn = $('tokens-btn');
+  if (!config || !config.forge || !config.signIn || !btn || !dialog()) return false;
+  if (opts.clock) now = opts.clock;
+  btn.hidden = false;
+  $('tokens-days').placeholder = String(DEFAULT_DAYS);
+  $('tokens-days-hint').textContent = `1 to ${MAX_DAYS}, ${DEFAULT_DAYS} if left empty`;
+  if (!wired) {
+    wired = true;
+    btn.addEventListener('click', openTokens);
+    dialog().addEventListener('click', onClick);
+    dialog().addEventListener('keydown', onKey);
+    $('tokens-form').addEventListener('submit', make);
+  }
+  return true;
+}
+
+/** For tests: forget the page this was wired to, and everything shown */
+export function resetReviewTokensForTests(clock = () => Date.now()) {
+  if (ui.open) closeTokens({ restoreFocus: false });
+  wired = false;
+  now = clock;
+  Object.assign(ui, { open: false, busy: false, tokens: [], loaded: false, message: null });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popcorn245/cornfield",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A self-hostable dev dashboard with the topology map at its centre: proposals on the map, scenarios, outages and what-if edits, for any repo.",
   "license": "MIT",
   "author": "popcorn245 (https://github.com/popcorn245)",

package/server/auth.js

@@ -279,6 +279,7 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
       /** Stage 1: everything passes; the routes under /auth/ are not there */
       gate: async () => ({ done: false, session: null }),
       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.'); },
       begin: async () => { throw new Error('Sign-in is not configured.'); },
       finish: async () => { throw new Error('Sign-in is not configured.'); },
@@ -578,6 +579,20 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
       if (token === null) throw new ForgeError(`${forgeName} sign-in has to be renewed; sign in again.`, { code: 'unauthorized', forge: forgeName });
       return forgeWith(token);
     },
+    /**
+     * The forge as a user who may not be at the dashboard now, with the token their newest live sign-in keeps (a
+     * maintainer's session row holds it, encrypted, until the session ends: sign-out, expiry, or a demotion). This is how
+     * a review that came through the API (server/review-api.js) is posted as its token's owner. Throws a ForgeError
+     * `unauthorized` when they have no live sign-in, so there is nothing to post with. It does not check the permission:
+     * the caller asks the forge, with this token, every time.
+     * @param {string} userId the forge's id for the user
+     */
+    async forgeForUser(userId) {
+      const row = /** @type {SessionRow | undefined} */ ((await store()).prepare('SELECT * FROM sessions WHERE user_id = ? AND token <> ? AND expires_at > ? ORDER BY created_at DESC, rowid DESC LIMIT 1').get(String(userId), NO_TOKEN, iso(now())));
+      const token = row ? openToken(keys.enc, row.token) : null;
+      if (token === null) throw new ForgeError(`The token's owner has no live sign-in to ${forgeName}; they sign in to cornfield again, then the token works again.`, { code: 'unauthorized', forge: forgeName });
+      return forgeWith(token);
+    },
     /** The SQLite file (opened on first use), for the routes that keep answers in it (server/forge-routes.js) */
     store,
     close() {

package/server/db.js

@@ -8,6 +8,7 @@
  *   reviews       a cache of the latest review per spec PR and proposal (the PR comment is the truth)
  *   actions       the audit of every action cornfield takes on the forge: who, what, when, the forge's answer
  *   forge_cache   forge answers kept for a while (an ETag and a body), so a page load is not a dozen API calls
+ *   review_tokens the review API's tokens: a SHA-256 hash, owner, label, expiry, revoked, last used (never the token)
  *   hook_seen     the (pull request, head, proposal) triples whose `spec.ready` event was sent, so a restart sends none twice;
  *                 a row with `pr = 0` says the repo has been looked at once (server/hooks.js)
  *
@@ -94,6 +95,21 @@ export const MIGRATIONS = Object.freeze([
     PRIMARY KEY (repo, pr, head_sha, slug)
   ) STRICT;
   `,
+  // 3: review tokens, for the review API (server/review-tokens.js)
+  `
+  CREATE TABLE review_tokens (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    token_hash  TEXT NOT NULL UNIQUE,           -- the SHA-256 of the token, hex; the token itself is never kept
+    user_id     TEXT NOT NULL,                  -- the owner, by the forge's id (a rename is followed)
+    login       TEXT NOT NULL,                  -- the owner's login when it was made
+    label       TEXT NOT NULL,                  -- what the owner calls it; the review comment names it
+    created_at  TEXT NOT NULL,
+    expires_at  TEXT NOT NULL,
+    revoked_at  TEXT,
+    last_used   TEXT
+  ) STRICT;
+  CREATE INDEX review_tokens_user_id ON review_tokens (user_id);
+  `,
 ]);
 
 /** The version a file is at: its `user_version` */

package/server/defuse.js

@@ -0,0 +1,16 @@
+/**
+ * @module server/defuse
+ *
+ * Breaking the mentions and references in text cornfield posts on the forge for someone else: `@user`, `@org/team`,
+ * `#1`, `owner/repo#1`, `GH-1`, and the links the forge would make of `https://…` or `www.…`. A zero-width space after
+ * the character keeps the text as it reads and stops it notifying anyone or linking anything. The pipeline's issues
+ * (server/pipeline.js) and a review that came through the review API (server/reviews.js) use it.
+ */
+
+/** A zero-width space: it ends a mention or a reference without showing */
+export const ZW = '​';
+
+/** Text with every mention, reference and auto-link broken (see the module's head) */
+export function defuse(text) {
+  return String(text).replace(/[@#]/g, (c) => `${c}${ZW}`).replace(/\b(GH)-(?=\d)/gi, `$1${ZW}-`).replace(/:\/\//g, `:${ZW}//`).replace(/\b(www)\./gi, `$1${ZW}.`);
+}

package/server/forge-actions.js

@@ -45,14 +45,12 @@ import { ForgeError, RERUN_STATES, canRerun, isMaintainer } from './forge.js';
 import { sameOrigin } from './proposals.js';
 import { planSpec, planBuild, startSpec, openBuildIssue } from './pipeline.js';
 import { PROPOSAL_FILE } from './files.js';
+import { Refused, throttle, countAttempt } from './throttle.js';
+
+// The limits live in server/throttle.js (reviews share them); these are re-exported for the callers that always had them here
+export { COOLDOWN_MS, PER_MINUTE, ATTEMPTS_PER_MINUTE, countAttempt } from './throttle.js';
 import { proposalPayload, landedPayload } from './hooks.js';
 
-/** The same action on the same target is not asked again for this long (a double click, a retry before the forge has caught up) */
-export const COOLDOWN_MS = 5000;
-/** The most actions one person takes in a minute */
-export const PER_MINUTE = 20;
-/** The most attempts of any kind (refused ones too) one person makes in a minute, before any is written down */
-export const ATTEMPTS_PER_MINUTE = 60;
 /** A request body is a sha and a check's id */
 const MAX_BODY = 4096;
 
@@ -63,39 +61,6 @@ const DIGEST = /^[0-9a-f]{32}$/;
 const DOING = { merge: 'Landing', rerun: 'Re-running', spec: 'Starting a spec', build: 'Opening the build issue' };
 const ONLY_MAINTAINERS = { merge: 'land pull requests or re-run checks', rerun: 'land pull requests or re-run checks', spec: 'start specs', build: 'open build issues' };
 
-/** @type {WeakMap<object, { busy: Set<string>, last: Map<string, number>, perUser: Map<string, number[]>, attempts: Map<string, number[]> }>} */
-const throttles = new WeakMap();
-
-function throttlesOf(auth) {
-  let t = throttles.get(auth);
-  if (!t) throttles.set(auth, (t = { busy: new Set(), last: new Map(), perUser: new Map(), attempts: new Map() }));
-  return t;
-}
-
-/** Counts an attempt of any kind; refuses one past the ceiling, without writing anything down (the release draft shares it) */
-export function countAttempt(ctx, userId, at) {
-  const t = throttlesOf(ctx.auth);
-  for (const [k, list] of t.attempts) if (!list.length || at - list[list.length - 1] >= 60_000) t.attempts.delete(k);
-  const mine = (t.attempts.get(userId) || []).filter((when) => at - when < 60_000);
-  if (mine.length >= ATTEMPTS_PER_MINUTE) {
-    t.attempts.set(userId, mine);
-    return new Refused(429, `That is ${ATTEMPTS_PER_MINUTE} attempts in a minute; wait a little.`, 'rate-limited', { 'Retry-After': String(Math.max(1, Math.ceil((60_000 - (at - mine[0])) / 1000))) });
-  }
-  mine.push(at);
-  t.attempts.set(userId, mine);
-  return null;
-}
-
-/** An action's own refusal: the status to answer and the words */
-class Refused extends Error {
-  constructor(status, message, code, headers = {}) {
-    super(message);
-    this.status = status;
-    this.code = code;
-    this.headers = headers;
-  }
-}
-
 /** Reads a small JSON object body, or refuses */
 function readJson(req) {
   return new Promise((resolve, reject) => {
@@ -130,23 +95,6 @@ function readJson(req) {
   });
 }
 
-/** Refuses a repeat and a flood; answers the key to release when the attempt is over */
-function throttle(ctx, userId, key, at) {
-  const t = throttlesOf(ctx.auth);
-  for (const [k, when] of t.last) if (at - when >= COOLDOWN_MS) t.last.delete(k);
-  const mine = (t.perUser.get(userId) || []).filter((when) => at - when < 60_000);
-  t.perUser.set(userId, mine);
-  const wait = (ms, words) => new Refused(429, words, 'rate-limited', { 'Retry-After': String(Math.max(1, Math.ceil(ms / 1000))) });
-  if (t.busy.has(key)) throw wait(COOLDOWN_MS, 'That is already being done; wait for it to finish.');
-  const before = t.last.get(key);
-  if (before !== undefined && at - before < COOLDOWN_MS) throw wait(COOLDOWN_MS - (at - before), 'That was just asked; wait a few seconds before asking again.');
-  if (mine.length >= PER_MINUTE) throw wait(60_000 - (at - mine[0]), `That is ${PER_MINUTE} actions in a minute; wait a little.`);
-  t.busy.add(key);
-  t.last.set(key, at);
-  mine.push(at);
-  return () => { t.busy.delete(key); };
-}
-
 /**
  * The permission of the signed-in user on the repo, asked of the forge now with their own token. Refuses unless it is
  * the same forge user as the session's and a maintainer.

package/server/pipeline.js

@@ -35,6 +35,7 @@ import { ForgeError, MAX_BODY, MAX_TITLE, isMaintainer } from './forge.js';
 import { PROPOSAL_FILE } from './files.js';
 import { findPullProposal, folderOf, readPullProposal } from './proposal-pulls.js';
 import { latestReview, proposalHash } from './reviews.js';
+import { defuse } from './defuse.js';
 import { applyEdits, slug as slugOf, validateProposal } from '../core/proposal.js';
 
 /** The longest slug of a proposal's name made from an issue's title, before its number */
@@ -62,16 +63,8 @@ export function plain(value, max = 200) {
   return defuse(clip(one, max)).replace(/[&<>\\`*_[\]|~!]/g, (c) => `&#${c.charCodeAt(0)};`);
 }
 
-/** A zero-width space: it ends a mention or a reference without showing */
-const ZW = '\u200B';
-
-/**
- * Text with every mention and reference broken: `@user`, `@org/team`, `#1`, `owner/repo#1`, `GH-1`, and links the forge
- * would make of `https://…` or `www.…`. A zero-width space after the character keeps the text as it reads.
- */
-export function defuse(text) {
-  return String(text).replace(/[@#]/g, (c) => `${c}${ZW}`).replace(/\b(GH)-(?=\d)/gi, `$1${ZW}-`).replace(/:\/\//g, `:${ZW}//`).replace(/\b(www)\./gi, `$1${ZW}.`);
-}
+// Mentions and references are broken by server/defuse.js, which reviews share; re-exported for the callers that had it here
+export { defuse } from './defuse.js';
 
 /** Untrusted text as a code span: no backtick or control character can end it */
 export function code(value, max = 100) {