cornfield 0.1.2 → 0.3.0

package/core/config.js

@@ -22,6 +22,7 @@
  *     topology: 'topology.json',
  *     personas: { roles: null },              // the roles a persona may have (null: any)
  *     releaseNotes: { breakingLabel: 'breaking' },   // the pull request label that lists a change under "Breaking" in the release notes
+ *     hooks: [],                              // [{ url, events }]: signed JSON events posted to outside code (docs/config.md#hooks); the secret is env only
  *     links: [],                              // [{ label, href }] shown in the explorer's header
  *     proxy: {},                              // { '/api/': 'http://127.0.0.1:3245' }: same-origin paths for a live source
  *     importMap: {},                          // bare imports a repo-local browser module needs: { name: '/repo/path.js' }
@@ -63,6 +64,10 @@ export const SOURCE_SLOTS = ['live', 'house', 'devices', 'checker'];
 export const FORGE_TYPES = ['github', 'forgejo'];
 /** How a pull request cornfield lands is merged (`forge.mergeMethod`): the way the repo lands its pull requests */
 export const MERGE_METHODS = ['merge', 'squash', 'rebase'];
+/** The events a hook may ask for (`hooks[].events`), and what each one means: docs/config.md#hooks */
+export const HOOK_EVENTS = Object.freeze(['spec.ready', 'spec.approved', 'spec.sentBack', 'build.opened', 'pr.landed']);
+/** The most hooks a config lists */
+export const MAX_HOOKS = 20;
 
 export const DEFAULTS = Object.freeze({
   title: null,
@@ -80,6 +85,7 @@ export const DEFAULTS = Object.freeze({
   cloud: { parent: 'root' },
   releaseNotes: { breakingLabel: 'breaking' },
   agents: { authors: [], labels: [], branchPrefixes: [], bots: true },
+  hooks: [],
   links: [],
   proxy: {},
   importMap: {},
@@ -173,6 +179,24 @@ export function configProblems(c) {
       }
     }
   }
+  if (c.hooks !== undefined) {
+    if (!Array.isArray(c.hooks)) out.push('"hooks" is a list of { url, events }.');
+    else {
+      if (c.hooks.length > MAX_HOOKS) out.push(`"hooks" lists at most ${MAX_HOOKS} hooks.`);
+      c.hooks.forEach((h, i) => {
+        if (!isObject(h)) { out.push(`hooks[${i}] is { url, events }.`); return; }
+        for (const k of Object.keys(h)) if (k !== 'url' && k !== 'events') out.push(`hooks[${i}].${k}: the keys are url, events (the secret is CORNFIELD_HOOK_SECRET in env, never the config).`);
+        const bad = hookUrlProblem(h.url);
+        if (bad) out.push(`hooks[${i}].url ${bad}`);
+        if (h.events === '*') return;
+        if (!Array.isArray(h.events) || h.events.length === 0) out.push(`hooks[${i}].events is "*" or a non-empty list of ${HOOK_EVENTS.join(', ')}.`);
+        else {
+          for (const e of h.events) if (!HOOK_EVENTS.includes(e)) out.push(`hooks[${i}].events: ${JSON.stringify(e)} is not an event; the events are ${HOOK_EVENTS.join(', ')}.`);
+          if (new Set(h.events).size !== h.events.length) out.push(`hooks[${i}].events names an event twice.`);
+        }
+      });
+    }
+  }
   if (c.releaseNotes !== undefined) {
     if (!isObject(c.releaseNotes)) out.push('"releaseNotes" is { breakingLabel }.');
     else if (c.releaseNotes.breakingLabel !== undefined && (!isText(c.releaseNotes.breakingLabel) || c.releaseNotes.breakingLabel.includes(','))) out.push('releaseNotes.breakingLabel is a label\'s name, like "breaking".');
@@ -203,6 +227,26 @@ export function configProblems(c) {
   return out;
 }
 
+/** Whether a host is the machine itself: `localhost`, 127.x.x.x or ::1 */
+const isLoopbackHost = (host) => host === 'localhost' || host === '[::1]' || /^127(?:\.\d{1,3}){3}$/.test(host);
+
+/** What is wrong with a hook's URL, in words that follow "hooks[i].url", or null: https, or http for the machine itself; no login in it */
+function hookUrlProblem(value) {
+  const say = 'is an https URL, like https://chat.example.org/hooks/cornfield.';
+  if (typeof value !== 'string') return say;
+  let u;
+  try {
+    u = new URL(value);
+  } catch {
+    return say;
+  }
+  if (u.protocol === 'http:' && !isLoopbackHost(u.hostname)) return 'is https; http is only for localhost, 127.0.0.1 and [::1].';
+  if (u.protocol !== 'https:' && u.protocol !== 'http:') return 'is an https URL.';
+  if (u.username || u.password) return 'has a user name or password in it; a hook is signed with CORNFIELD_HOOK_SECRET instead.';
+  if (u.hash) return 'has a # fragment, which is never sent.';
+  return null;
+}
+
 /** A short, file-safe name for a repo root, for the default data folder */
 function slugOf(root) {
   return path.basename(root).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'repo';

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": "cornfield",
-  "version": "0.1.2",
+  "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,9 @@
  *   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)
  *
  * The schema is a list of numbered migrations (`MIGRATIONS`); the file's `PRAGMA user_version` is the number of
  * the last one it has. `openStore` runs the ones a file lacks, each in its own transaction, so a fresh file and one
@@ -81,6 +84,32 @@ export const MIGRATIONS = Object.freeze([
   ) STRICT;
   CREATE INDEX forge_cache_expires_at ON forge_cache (expires_at);
   `,
+  // 2: event hooks (server/hooks.js): which spec PR heads have been announced
+  `
+  CREATE TABLE hook_seen (
+    repo        TEXT NOT NULL,                  -- 'owner/name'
+    pr          INTEGER NOT NULL,
+    head_sha    TEXT NOT NULL,                  -- the PR's head when cornfield first saw it
+    slug        TEXT NOT NULL,                  -- the proposal file's slug
+    at          TEXT NOT NULL,
+    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}.`);
+}