@popcorn245/cornfield 0.5.0 → 0.6.0

package/core/config.js

@@ -66,7 +66,7 @@ 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']);
+export const HOOK_EVENTS = Object.freeze(['spec.ready', 'spec.approved', 'spec.sentBack', 'build.opened', 'pr.landed', 'session.expiring']);
 /** The most hooks a config lists */
 export const MAX_HOOKS = 20;
 /** The bounds of `hookPoll.specs` in milliseconds: not under a minute (the forge is not hammered), not over an hour */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popcorn245/cornfield",
-  "version": "0.5.0",
+  "version": "0.6.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

@@ -45,15 +45,50 @@ import { sameOrigin } from './proposals.js';
 
 /** How often a session's permission is asked of the forge again */
 export const RECHECK_MS = 15 * 60 * 1000;
-/** How long a session lasts */
-export const SESSION_MS = 7 * 24 * 60 * 60 * 1000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** How long a session lasts unless `CORNFIELD_SESSION_DAYS` says otherwise */
+export const SESSION_MS = 7 * DAY_MS;
+export const SESSION_DAYS_ENV = 'CORNFIELD_SESSION_DAYS';
+export const DEFAULT_SESSION_DAYS = 7;
+export const MAX_SESSION_DAYS = 30;
+/** A forge token this close to its expiry (or past it) is renewed before it is used */
+export const REFRESH_SKEW_MS = 30_000;
 /** How long the way out to the forge and back may take */
 export const STATE_MS = 10 * 60 * 1000;
 export const MIN_SESSION_SECRET = 32;
 const TOKEN_TIMEOUT_MS = 15_000;
 const REVOKE_TIMEOUT_MS = 5_000;
+/** The most of a token endpoint's answer that is read: a token pair is a few hundred bytes */
+const MAX_TOKEN_ANSWER = 64 * 1024;
+/** Statuses that say "not now" (a timeout, a rate limit), never "no": a renewal answered with one ends no session */
+const NOT_NOW = [408, 425, 429];
+
+/** A response's text, at most `max` bytes: past that the body is dropped and the read throws */
+async function cappedText(res, max) {
+  if (!res.body || typeof res.body.getReader !== 'function') {
+    const text = await res.text();
+    if (Buffer.byteLength(text) > max) throw new Error('the answer is too large');
+    return text;
+  }
+  const reader = res.body.getReader();
+  const chunks = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > max) {
+      await reader.cancel().catch(() => {});
+      throw new Error('the answer is too large');
+    }
+    chunks.push(Buffer.from(value));
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
 /** What a session row keeps in place of a token when it keeps none (a signed-in non-maintainer) */
 const NO_TOKEN = '';
+/** What a renewal answers for a session that has no refresh token */
+const NO_REFRESH = Symbol('no refresh token');
 
 /** The env each forge's OAuth app is read from */
 export const OAUTH_ENV = Object.freeze({
@@ -79,15 +114,29 @@ export function oauthEndpoints(forge) {
   };
 }
 
+/**
+ * How many days a session lasts: `CORNFIELD_SESSION_DAYS`, a whole number from 1 to 30, 7 when unset. Anything else
+ * throws, in words (a value that is quietly ignored would leave a team on 7 days without knowing).
+ * @param {Record<string, string | undefined>} [env]
+ */
+export function sessionDays(env = process.env) {
+  const raw = env[SESSION_DAYS_ENV];
+  if (raw === undefined || raw === '') return DEFAULT_SESSION_DAYS;
+  const days = /^[0-9]{1,3}$/.test(raw.trim()) ? Number(raw.trim()) : NaN;
+  if (!Number.isInteger(days) || days < 1 || days > MAX_SESSION_DAYS) throw new Error(`${SESSION_DAYS_ENV} is ${JSON.stringify(raw.slice(0, 40))}: use a whole number of days from 1 to ${MAX_SESSION_DAYS} (${DEFAULT_SESSION_DAYS} when unset).`);
+  return days;
+}
+
 /**
  * The sign-in settings env gives, or null when sign-in is not configured at all. Throws, in words, when it is
  * half configured: one of a pair, no session secret, a short one, no public URL, no forge.
  * @param {{ forge?: { type: string, url?: string, repo: string } | null, publicUrl?: string | null }} config
  * @param {Record<string, string | undefined>} [env]
- * @returns {null | { forge: { type: string, url?: string, repo: string }, forgeName: string, clientId: string, clientSecret: string, sessionSecret: string, publicUrl: URL, secure: boolean }}
+ * @returns {null | { forge: { type: string, url?: string, repo: string }, forgeName: string, clientId: string, clientSecret: string, sessionSecret: string, publicUrl: URL, secure: boolean, sessionDays: number }}
  */
 export function signInSettings(config, env = process.env) {
   const set = (name) => typeof env[name] === 'string' && env[name] !== '';
+  const days = sessionDays(env);
   const anyPair = Object.values(OAUTH_ENV).some((p) => set(p.id) || set(p.secret));
   if (!anyPair) {
     if (set(SESSION_SECRET_ENV)) throw new Error(`${SESSION_SECRET_ENV} is set but no OAuth app is: set the forge's client id and secret too (docs/sign-in.md), or unset it.`);
@@ -114,7 +163,7 @@ export function signInSettings(config, env = process.env) {
   if (publicUrl.pathname !== '/' || publicUrl.search || publicUrl.hash) throw new Error('The public URL is an origin, like https://cornfield.example.org: cornfield is served at its root.');
   return {
     forge, forgeName: FORGE_NAMES[forge.type], clientId: env[pair.id], clientSecret: env[pair.secret], sessionSecret: env[SESSION_SECRET_ENV],
-    publicUrl, secure: publicUrl.protocol === 'https:',
+    publicUrl, secure: publicUrl.protocol === 'https:', sessionDays: days,
   };
 }
 
@@ -152,19 +201,24 @@ function keysOf(secret) {
 const macOf = (key, text) => createHmac('sha256', key).update(text).digest('base64url');
 
 /** A forge token, encrypted for its row: `v1.<iv>.<tag>.<ciphertext>` */
-export function sealToken(key, token) {
+export function sealToken(key, token, aad) {
   const iv = randomBytes(12);
   const c = createCipheriv('aes-256-gcm', key, iv);
+  // With `aad` (v2) the ciphertext opens only for that row and column: one cannot be moved into another session's row
+  if (aad !== undefined) c.setAAD(Buffer.from(String(aad), 'utf8'));
   const body = Buffer.concat([c.update(token, 'utf8'), c.final()]);
-  return `v1.${b64url(iv)}.${b64url(c.getAuthTag())}.${b64url(body)}`;
+  return `${aad !== undefined ? 'v2' : 'v1'}.${b64url(iv)}.${b64url(c.getAuthTag())}.${b64url(body)}`;
 }
 
 /** The token a row holds, or null when it does not open under this key (another secret, or tampered) */
-export function openToken(key, sealed) {
+export function openToken(key, sealed, aad, { legacy = true } = {}) {
   const [v, iv, tag, body] = String(sealed).split('.');
-  if (v !== 'v1' || !iv || !tag || body === undefined) return null;
+  if (!iv || !tag || body === undefined) return null;
+  // v2 is bound to its row and column (`aad`); v1, sealed before that, opens only where a legacy value may still be
+  if (v === 'v2' ? aad === undefined : v !== 'v1' || !legacy) return null;
   try {
     const d = createDecipheriv('aes-256-gcm', key, Buffer.from(iv, 'base64url'));
+    if (v === 'v2') d.setAAD(Buffer.from(String(aad), 'utf8'));
     d.setAuthTag(Buffer.from(tag, 'base64url'));
     return Buffer.concat([d.update(Buffer.from(body, 'base64url')), d.final()]).toString('utf8');
   } catch {
@@ -255,7 +309,7 @@ function wantsPage(req, reqPath) {
 }
 
 /**
- * @typedef {{ id: string, forge: string, user_id: string, login: string, token: string, permission: string, created_at: string, checked_at: string, expires_at: string }} SessionRow
+ * @typedef {{ id: string, forge: string, user_id: string, login: string, token: string, permission: string, created_at: string, checked_at: string, expires_at: string, refresh_token: string, token_expires_at: string | null, expiring_sent_at: string | null }} SessionRow
  * @typedef {{ login: string, userId: string, permission: string, admin: boolean, row: SessionRow }} Session
  */
 
@@ -290,6 +344,7 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
 
   const title = config.title || 'cornfield';
   const { forge: forgeConfig, forgeName, clientId, clientSecret, publicUrl, secure } = settings;
+  const sessionMs = settings.sessionDays * DAY_MS;
   const keys = keysOf(settings.sessionSecret);
   const endpoints = oauthEndpoints(forgeConfig);
   const redirectUri = new URL('/auth/callback', publicUrl).href;
@@ -305,6 +360,16 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
   const store = () => (opening ??= import('./db.js').then((m) => (db = m.openStore(config.dataDir))).catch((err) => { opening = null; throw err; }));
   const iso = (ms) => new Date(ms).toISOString();
   const forgeWith = (token) => createForge(forgeConfig, { token, ...forgeOptions });
+  /** Session ids whose forge token is being renewed right now: one renewal per session, however many calls wait on it */
+  const renewals = new Map();
+  /**
+   * A session's tokens are sealed for their row and column (AES-GCM's additional data): a sealed token copied into
+   * another session's row, or from one column to the other, does not open. An access token sealed before this (v1)
+   * still opens until its session ends; a refresh token never had a v1.
+   */
+  const aadOf = (id, column) => `cornfield session ${id} ${column}`;
+  const sealFor = (id, column, value) => sealToken(keys.enc, value, aadOf(id, column));
+  const openFor = (row, column) => openToken(keys.enc, row[column], aadOf(row.id, column), { legacy: column === 'token' });
 
   const send = (res, status, body, headers = {}) => {
     res.writeHead(status, { ...(typeof body === 'string' ? HTML_HEADERS : JSON_HEADERS), ...headers });
@@ -350,7 +415,7 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
   /** Ends a session: its row goes, and the token it kept is revoked */
   async function endRow(row) {
     (await store()).prepare('DELETE FROM sessions WHERE id = ?').run(row.id);
-    if (row.token !== NO_TOKEN) await revoke(openToken(keys.enc, row.token));
+    if (row.token !== NO_TOKEN) await revoke(openFor(row, 'token'));
   }
 
   /** The session row a request's cookie names, live, or null */
@@ -379,13 +444,13 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
     const row = await rowOf(req);
     if (!row) return { session: null };
     if (row.token === NO_TOKEN || now() - Date.parse(row.checked_at) < RECHECK_MS) return { session: sessionOf(row) };
-    const token = openToken(keys.enc, row.token);
+    const token = openFor(row, 'token');
     if (token === null) {
       await endRow(row);
       return { session: null };
     }
     try {
-      const forge = forgeWith(token);
+      const forge = managedForge(row);
       const user = await forge.me();
       if (String(user.id) !== row.user_id) {
         await endRow(row);
@@ -393,9 +458,14 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
       }
       const permission = await forge.permission(forgeConfig.repo, user.login);
       const keep = isMaintainer(permission);
-      const next = { ...row, login: user.login, permission, checked_at: iso(now()), token: keep ? row.token : NO_TOKEN };
-      (await store()).prepare('UPDATE sessions SET login = ?, permission = ?, checked_at = ?, token = ? WHERE id = ?').run(next.login, next.permission, next.checked_at, next.token, row.id);
-      if (!keep) await revoke(token);
+      // The token is not written back when it is kept: a renewal during these calls has stored a newer one
+      const file = await store();
+      const kept = /** @type {SessionRow | undefined} */ (file.prepare('SELECT * FROM sessions WHERE id = ?').get(row.id));
+      if (!kept) return { session: null };
+      const next = { ...kept, login: user.login, permission, checked_at: iso(now()), ...(keep ? {} : { token: NO_TOKEN, refresh_token: '', token_expires_at: null }) };
+      file.prepare('UPDATE sessions SET login = ?, permission = ?, checked_at = ?, token = ?, refresh_token = ?, token_expires_at = ? WHERE id = ?')
+        .run(next.login, next.permission, next.checked_at, next.token, next.refresh_token, next.token_expires_at, row.id);
+      if (!keep) await revoke(openFor(kept, 'token') ?? token);
       return { session: sessionOf(next) };
     } catch (err) {
       if (err instanceof ForgeError && err.code === 'unauthorized') {
@@ -430,22 +500,141 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
     return { verifier };
   }
 
-  /** The forge's token for a code, or throws a ForgeError */
-  async function exchange(code, verifier) {
-    const body = new URLSearchParams({ client_id: clientId, client_secret: clientSecret, code, redirect_uri: redirectUri, grant_type: 'authorization_code', code_verifier: verifier });
+  /**
+   * The forge's token endpoint, for a code (sign-in) or a refresh token (renewal). Answers the pair it gave, or throws
+   * a ForgeError: `unauthorized` when the forge refused (a code or refresh token that is bad, revoked or expired),
+   * `unavailable` when it did not answer or said it could not now (nothing is ended for that).
+   * @returns {Promise<{ accessToken: string, refreshToken: string, expiresAt: string | null }>}
+   */
+  async function tokenRequest(grant, what) {
+    const body = new URLSearchParams({ client_id: clientId, client_secret: clientSecret, ...grant });
     let res;
     let parsed = null;
     try {
       res = await doFetch(endpoints.token, { method: 'POST', headers: { Accept: 'application/json', 'Content-Type': 'application/x-www-form-urlencoded', 'User-Agent': 'cornfield' }, body, redirect: 'manual', signal: AbortSignal.timeout(TOKEN_TIMEOUT_MS) });
-      parsed = JSON.parse(await res.text());
+      parsed = JSON.parse(await cappedText(res, MAX_TOKEN_ANSWER));
     } catch (err) {
-      throw new ForgeError(`${forgeName} did not answer the sign-in; try again in a minute.`, { code: 'unavailable', forge: forgeName, cause: err });
+      // A forge that answered 4xx with a body that is not JSON said no; one that did not answer, or broke, did not
+      if (res && res.status >= 400 && res.status < 500 && !NOT_NOW.includes(res.status)) throw new ForgeError(`${forgeName} did not give a token for ${what}.`, { code: 'unauthorized', status: res.status, forge: forgeName });
+      throw new ForgeError(`${forgeName} did not answer ${what}; try again in a minute.`, { code: 'unavailable', forge: forgeName, cause: err });
+    }
+    if (res.status >= 500 || NOT_NOW.includes(res.status) || (res.status >= 300 && res.status < 400) || (parsed && (parsed.error === 'temporarily_unavailable' || parsed.error === 'server_error'))) {
+      throw new ForgeError(`${forgeName} could not answer ${what} just now; try again in a minute.`, { code: 'unavailable', status: res.status, forge: forgeName });
     }
     if (!res.ok || !parsed || typeof parsed.access_token !== 'string' || parsed.access_token === '') {
       const said = parsed && typeof parsed.error_description === 'string' ? ` ${forgeName} said: "${parsed.error_description.slice(0, 200)}"` : '';
-      throw new ForgeError(`${forgeName} did not give a token for this sign-in.${said}`, { code: 'unauthorized', status: res.status, forge: forgeName });
+      throw new ForgeError(`${forgeName} did not give a token for ${what}.${said}`, { code: 'unauthorized', status: res.status, forge: forgeName });
     }
-    return parsed.access_token;
+    // Forgejo always says how long an access token lasts (1 hour unless the instance changed it) and gives a refresh
+    // token; GitHub does only for an app with token expiration on. A token that says nothing is not expiring
+    const seconds = Number(parsed.expires_in);
+    return {
+      accessToken: parsed.access_token,
+      refreshToken: typeof parsed.refresh_token === 'string' ? parsed.refresh_token : '',
+      expiresAt: Number.isFinite(seconds) && seconds > 0 ? iso(now() + seconds * 1000) : null,
+    };
+  }
+
+  const exchange = (code, verifier) => tokenRequest({ code, redirect_uri: redirectUri, grant_type: 'authorization_code', code_verifier: verifier }, 'this sign-in');
+
+  /**
+   * Renews a session's forge token with its refresh token, once at a time per session. `used` is the sealed token the
+   * caller found stale: if the row holds another by now, somebody renewed it already and that is what answers. Persists
+   * the new pair together (a rotated refresh token makes the old one useless). Answers the row; `NO_REFRESH` when the
+   * session keeps no refresh token (a GitHub app whose tokens do not expire, the usual case: nothing changes for it);
+   * or null when the session is over: the refresh token is refused (revoked, expired), and the row is ended so the
+   * "sign in again" behaviour applies. Throws a ForgeError `unavailable` when the forge cannot be asked now: the session
+   * stays and the next call tries again.
+   * @param {string} id the session row's id
+   * @param {string} used
+   * @returns {Promise<SessionRow | typeof NO_REFRESH | null>}
+   */
+  function renew(id, used) {
+    const going = renewals.get(id);
+    if (going) return going;
+    const job = (async () => {
+      const file = await store();
+      const row = /** @type {SessionRow | undefined} */ (file.prepare('SELECT * FROM sessions WHERE id = ?').get(id));
+      if (!row || row.token === NO_TOKEN) return null;
+      if (row.token !== used) return row;
+      const refresh = row.refresh_token === '' ? null : openFor(row, 'refresh_token');
+      // Nothing to renew with: the session is left as it is, and the call that found the token stale gets the forge's own answer
+      if (refresh === null) return NO_REFRESH;
+      // Another process (cornfield restarted, or two behind one data folder) may renew the same row at the same time. The
+      // forge rotates the refresh token, so the slower of the two is refused: that is a lost race, not a refused sign-in,
+      // and the row the winner wrote is the answer. The write itself only lands on the row as it was read.
+      const rowNow = () => /** @type {SessionRow | undefined} */ (file.prepare('SELECT * FROM sessions WHERE id = ?').get(id));
+      let got;
+      try {
+        got = await tokenRequest({ grant_type: 'refresh_token', refresh_token: refresh }, 'a renewed sign-in');
+      } catch (err) {
+        if (err instanceof ForgeError && err.code === 'unauthorized') {
+          const after = rowNow();
+          if (after && after.token !== row.token && after.token !== NO_TOKEN) return after;
+          if (after) await endRow(after);
+          return null;
+        }
+        throw err;
+      }
+      const next = { ...row, token: sealFor(id, 'token', got.accessToken), refresh_token: got.refreshToken === '' ? row.refresh_token : sealFor(id, 'refresh_token', got.refreshToken), token_expires_at: got.expiresAt };
+      const wrote = file.prepare('UPDATE sessions SET token = ?, refresh_token = ?, token_expires_at = ? WHERE id = ? AND token = ? AND refresh_token = ?').run(next.token, next.refresh_token, next.token_expires_at, id, row.token, row.refresh_token).changes;
+      if (wrote === 1) return next;
+      // The row changed while the forge was asked: ended (sign-out), or renewed elsewhere. The row as it is now answers
+      const after = rowNow();
+      return after && after.token !== NO_TOKEN ? after : null;
+    })().finally(() => renewals.delete(id));
+    renewals.set(id, job);
+    return job;
+  }
+
+  /**
+   * The forge as the session's owner, with a token that renews itself: past (or about to pass) its expiry it is renewed
+   * before the call, and a call the forge answers 401 is renewed once and made again. A renewal that cannot be had
+   * ends the session and the call throws the same `unauthorized` ForgeError as a session that is gone.
+   * @param {SessionRow} row
+   */
+  function managedForge(row) {
+    let sealed = row.token;
+    let expiresAt = row.token_expires_at;
+    let forge = forgeWith(/** @type {string} */ (openFor({ id: row.id, token: sealed }, 'token')));
+    const over = () => new ForgeError(`${forgeName} sign-in has to be renewed; sign in again.`, { code: 'unauthorized', forge: forgeName });
+    /** Whether the token is a new one: false when this session cannot renew (the call goes on as it would have) */
+    const renewNow = async () => {
+      const next = await renew(row.id, sealed);
+      if (next === NO_REFRESH) return false;
+      const token = next ? openFor(next, 'token') : null;
+      if (!next || token === null) throw over();
+      sealed = next.token;
+      expiresAt = next.token_expires_at;
+      forge = forgeWith(token);
+      return true;
+    };
+    const due = () => expiresAt !== null && Date.parse(expiresAt) - REFRESH_SKEW_MS <= now();
+    return new Proxy({}, {
+      get(_, prop) {
+        const member = forge[prop];
+        if (typeof member !== 'function' || prop === 'rateLimit') return member;
+        return async (...args) => {
+          if (due()) {
+            try {
+              await renewNow();
+            } catch (err) {
+              // Renewing ahead of time could not be done now (the forge is down): a token that has not expired yet still works
+              const stillGood = expiresAt !== null && Date.parse(expiresAt) > now();
+              if (!(err instanceof ForgeError && err.code === 'unavailable' && stillGood)) throw err;
+            }
+          }
+          try {
+            return await forge[prop](...args);
+          } catch (err) {
+            if (!(err instanceof ForgeError) || err.code !== 'unauthorized') throw err;
+            // The forge refused the token: renew it (when it can be) and ask once more; else its refusal stands
+            if (!(await renewNow())) throw err;
+          }
+          return forge[prop](...args);
+        };
+      },
+    });
   }
 
   async function callback(req, res, url) {
@@ -457,12 +646,12 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
     if (url.searchParams.get('error')) return fail(url.searchParams.get('error') === 'access_denied' ? `The sign-in was cancelled on ${forgeName}.` : `${forgeName} did not sign you in.`);
     const code = url.searchParams.get('code');
     if (!code || code.length > 1000) return fail(`${forgeName} came back without a sign-in code.`);
-    let token;
+    let given;
     let user;
     let permission;
     try {
-      token = await exchange(code, checked.verifier);
-      const forge = forgeWith(token);
+      given = await exchange(code, checked.verifier);
+      const forge = forgeWith(given.accessToken);
       user = await forge.me();
       permission = await forge.permission(forgeConfig.repo, user.login);
     } catch (err) {
@@ -470,14 +659,17 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
     }
     const value = random();
     const at = now();
+    const token = given.accessToken;
     const file = await store();
     for (const old of file.prepare('SELECT * FROM sessions WHERE expires_at <= ?').all(iso(at))) await endRow(/** @type {SessionRow} */ (old));
     // Only a maintainer's token is kept; anyone else's is revoked at once (they are asked again at their next sign-in)
     const keep = isMaintainer(permission);
-    file.prepare('INSERT INTO sessions (id, forge, user_id, login, token, permission, created_at, checked_at, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)')
-      .run(macOf(keys.mac, value), forgeConfig.type, String(user.id), user.login, keep ? sealToken(keys.enc, token) : NO_TOKEN, permission, iso(at), iso(at), iso(at + SESSION_MS));
+    const id = macOf(keys.mac, value);
+    file.prepare('INSERT INTO sessions (id, forge, user_id, login, token, permission, created_at, checked_at, expires_at, refresh_token, token_expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)')
+      .run(id, forgeConfig.type, String(user.id), user.login, keep ? sealFor(id, 'token', token) : NO_TOKEN, permission, iso(at), iso(at), iso(at + sessionMs),
+        keep && given.refreshToken !== '' ? sealFor(id, 'refresh_token', given.refreshToken) : '', keep ? given.expiresAt : null);
     if (!keep) await revoke(token);
-    redirect(res, '/', [cookie(SESSION_COOKIE, value, { maxAge: SESSION_MS / 1000, secure }), clearState]);
+    redirect(res, '/', [cookie(SESSION_COOKIE, value, { maxAge: sessionMs / 1000, secure }), clearState]);
   }
 
   async function authRoute(req, res, reqPath, url) {
@@ -575,9 +767,9 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
     },
     /** The forge as a signed-in user, with their own token (for the routes that act on the forge) */
     forgeFor(session) {
-      const token = session.row.token === NO_TOKEN ? null : openToken(keys.enc, session.row.token);
+      const token = session.row.token === NO_TOKEN ? null : openFor(session.row, 'token');
       if (token === null) throw new ForgeError(`${forgeName} sign-in has to be renewed; sign in again.`, { code: 'unauthorized', forge: forgeName });
-      return forgeWith(token);
+      return managedForge(session.row);
     },
     /**
      * The forge as a user who may not be at the dashboard now, with the token their newest live sign-in keeps (a
@@ -589,9 +781,9 @@ export function createAuth(config, { env = process.env, now = Date.now, fetch: d
      */
     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;
+      const token = row ? openFor(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);
+      return managedForge(/** @type {SessionRow} */ (row));
     },
     /** The SQLite file (opened on first use), for the routes that keep answers in it (server/forge-routes.js) */
     store,

package/server/db.js

@@ -12,6 +12,7 @@
  *   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)
  *   landings      the spec PRs an approval is waiting to land (`proposals.approveLands`), so a restart picks them up (server/lander.js)
+ *                 sessions also keep a forge refresh token, the access token's expiry and when `session.expiring` was sent (migration 5)
  *
  * The schema is a list of numbered migrations (`MIGRATIONS`); the file's `PRAGMA user_version` is the number of
  * the last one it has. `openStore` runs the ones a file lacks, each in its own transaction, so a fresh file and one
@@ -125,6 +126,13 @@ export const MIGRATIONS = Object.freeze([
     PRIMARY KEY (repo, pull)
   ) STRICT;
   `,
+  // 5: long sessions (server/auth.js, server/hooks.js): the forge's refresh token (encrypted, like the access token) and
+  // when the access token expires, so an expiring forge token is renewed; and when \`session.expiring\` was sent for a session
+  `
+  ALTER TABLE sessions ADD COLUMN refresh_token TEXT NOT NULL DEFAULT '';  -- the forge's refresh token, encrypted like \`token\`; '' when there is none
+  ALTER TABLE sessions ADD COLUMN token_expires_at TEXT;                   -- when the access token stops working; NULL when it does not expire
+  ALTER TABLE sessions ADD COLUMN expiring_sent_at TEXT;                   -- when the \`session.expiring\` hook event was sent; NULL before
+  `,
 ]);
 
 /** The version a file is at: its `user_version` */

package/server/hooks.js

@@ -13,6 +13,8 @@
  *   spec.approved   a maintainer approved a proposal          spec.sentBack   a maintainer sent one back
  *   build.opened    the build issue of an approved proposal was opened
  *   pr.landed       a pull request was landed through cornfield (its Land it); a merge made on the forge sends nothing
+ *   session.expiring  a maintainer's sign-in ends within a day (`watchSessions`, below). Its body is its own:
+ *                   `{ event, at, actor, expiresAt, mapUrl }`
  *
  * **A hook never gets in the way.** `emit` returns at once and never throws; the delivery runs in the background, from a
  * queue in memory. A failed delivery (a network error, a timeout, anything but a 2xx) is tried again after 1s, 5s and 30s
@@ -49,6 +51,9 @@ export const BACKOFF_MS = Object.freeze([1_000, 5_000, 30_000]);
 export const TIMEOUT_MS = 10_000;
 /** How much of an answer is read before it is dropped */
 export const MAX_RESPONSE_BYTES = 4096;
+/** How often live sessions are looked at for `session.expiring`, and how far ahead of the end the event is sent */
+export const SESSION_CHECK_MS = 60 * 60 * 1000;
+export const EXPIRING_WITHIN_MS = 24 * 60 * 60 * 1000;
 /** The most deliveries waiting (or being retried) at once; one past it is dropped, and the audit table says so */
 export const MAX_PENDING = 500;
 
@@ -179,6 +184,8 @@ export function createHooks({ hooks, secret, fetch: doFetch = globalThis.fetch,
 
   /** The body of an event: only the fields of the payload, in a fixed order */
   function bodyOf(event, p) {
+    // A session's end has no spec, pull request or proposal: its body is only who, until when, and where cornfield is
+    if (event === 'session.expiring') return JSON.stringify({ event, at: new Date(now()).toISOString(), actor: p.actor ?? null, expiresAt: p.expiresAt ?? null, mapUrl: publicUrl || null });
     const out = {
       event, at: new Date(now()).toISOString(), slug: p.slug ?? null, pull: p.pull ?? null, headSha: p.headSha ?? null,
       proposalSha256: p.proposalSha256 ?? null, actor: p.actor ?? null,
@@ -254,13 +261,42 @@ export function createHooks({ hooks, secret, fetch: doFetch = globalThis.fetch,
     })().catch((err) => console.error(`[cornfield] the spec PRs could not be checked for spec.ready: ${err instanceof Error ? err.message : err}`));
   }
 
+  /**
+   * `session.expiring`: once an hour (and once now), the live sessions of maintainers (the ones that keep a forge token)
+   * that end within 24 hours are announced, each once: the row's `expiring_sent_at` is set before the event is
+   * emitted, so a restart sends none twice (and a delivery lost for good is not tried again later). A session that was
+   * signed out, or ended, is not a row any more and is never announced. A user with several live sessions (a laptop and
+   * a phone) gets an event for each, naming the same login and that session's own end. Needs the SQLite file, and only
+   * runs when a hook asked for the event. The timer is unref'd and stopped by `close`. Returns at once, never throws.
+   */
+  function watchSessions() {
+    if (closed || !store || !targets.some((t) => t.events.includes('session.expiring'))) return;
+    const check = async () => {
+      const db = await store();
+      const at = now();
+      const rows = db.prepare("SELECT id, login, expires_at FROM sessions WHERE token <> '' AND expiring_sent_at IS NULL AND expires_at > ? AND expires_at <= ? ORDER BY expires_at")
+        .all(new Date(at).toISOString(), new Date(at + EXPIRING_WITHIN_MS).toISOString());
+      const mark = db.prepare('UPDATE sessions SET expiring_sent_at = ? WHERE id = ? AND expiring_sent_at IS NULL');
+      for (const r of rows) {
+        if (mark.run(new Date(at).toISOString(), r.id).changes === 1) emit('session.expiring', { actor: r.login, expiresAt: r.expires_at });
+      }
+    };
+    const tick = () => {
+      if (closed) return;
+      check()
+        .catch((err) => console.error(`[cornfield] the sessions could not be checked for session.expiring: ${err instanceof Error ? err.message : err}`))
+        .finally(() => { if (!closed) later(tick, SESSION_CHECK_MS); });
+    };
+    later(tick, 0);
+  }
+
   function close() {
     closed = true;
     for (const t of timers) timer.clearTimeout(t);
     timers.clear();
   }
 
-  return { emit, specsSeen, close };
+  return { emit, specsSeen, watchSessions, close };
 }
 
 /** The SHA-256 of a proposal file as `read` gives it, or null when it cannot be read (an event still goes out) */

package/server/server.js

@@ -141,6 +141,7 @@ export function createCornfieldServer(config, opts = {}) {
   const hooks = hookSettings
     ? createHooks({ hooks: config.hooks, secret: hookSettings.secret, fetch: opts.hookFetch, record: (entry) => auth.record(entry), store: auth.store, now: opts.now, publicUrl: config.publicUrl, timer: opts.hookTimer })
     : null;
+  hooks?.watchSessions();
   // Landing on approval needs somebody signed in to land as, like the hooks' events: a half-set key is a startup error
   if (config.approveLands && !auth.enabled) throw new Error('The config says proposals.approveLands, but sign-in is not set up. An approval is a signed-in maintainer\'s, and it lands as them, so without sign-in nothing would ever land: set up sign-in (docs/sign-in.md), or remove approveLands.');
   const root = config.root;