pgkiln 0.59.0 → 0.60.0

package/src/builder/security.ts

@@ -0,0 +1,261 @@
+import type { FastifyInstance } from 'fastify';
+import { owner } from '../db.ts';
+import { html, raw, type Raw } from '../html.ts';
+import { icon } from '../icons.ts';
+import {
+  addTotp, adminEmails, adminFactors, codesLeft, confirmRecoveryCodes, factorsOf, hasFactor, matchTotp, MFA_POLICIES, mfaPolicy, newRecoveryCodes, newTotpSecret,
+  notifyMfa, otpauthUri, policyProblem, requiredFor, resetFactors, setPolicy, unbase32, type MfaPolicy,
+} from '../mfa.ts';
+import { qrSvg } from '../qrcode.ts';
+import { secretKeyConfigured } from '../secrets.ts';
+import { clientIp, logActivity, type Session } from '../session.ts';
+import { tr } from './i18n.ts';
+import { isAdmin } from './locks.ts';
+import { back, BASE, csrf, developer, flash, input, region, send, shell, type Req } from './ui.ts';
+
+// (sprint 126, SEC-2 and SEC-6) Developer › Security: a developer's second factors (authenticator apps, TOTP)
+// and recovery codes; the instance's policy (Instance settings); an administrator's reset of another
+// developer's factors (Developers). Adding an app: a new secret is kept in the session until a code from the
+// app confirms it, then stored encrypted with the instance key. Recovery codes are shown once; they count
+// only after "I saved them". Removing a factor asks for the password, and is refused when it would leave a
+// developer the policy covers without one, or the instance without enough administrators who have one.
+
+const SECRET_MINUTES = 10;
+
+async function verifyPassword(username: string, password: string) {
+  return !!(await owner.one('select 1 as ok from meta.developer where username = $1 and crypt($2, password_hash) = password_hash', [username, password]));
+}
+
+export async function securityRoutes(app: FastifyInstance) {
+  app.get(`${BASE}/security`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const tx = tr(s);
+    const me = s.username!;
+    const [factors, left, pol, admin] = await Promise.all([factorsOf(me), codesLeft(me), mfaPolicy(), isAdmin(me)]);
+    const required = requiredFor(pol.policy, admin);
+    const pending = (() => {
+      try {
+        const p = JSON.parse(String(s.state.__TOTP_NEW ?? ''));
+        return p && Date.now() - p.at < SECRET_MINUTES * 60_000 ? (p as { secret: string; at: number }) : null;
+      } catch {
+        return null;
+      }
+    })();
+    const shownCodes: string[] | null = (() => {
+      try {
+        const c = JSON.parse(String(s.state.__CODES_NEW ?? ''));
+        return Array.isArray(c) ? c : null;
+      } catch {
+        return null;
+      }
+    })();
+    delete s.state.__MFA_DUE; // the page says it itself
+    const when = (v: string | null) => (v ? String(v).slice(0, 16).replace('T', ' ') : '—');
+    const setup = pending
+      ? html`<form method="post" action="${BASE}/security/totp/confirm">${csrf(s)}
+          <ol class="mfa-steps">
+            <li>${tx('mfa.scan')}</li>
+            <li>${tx('mfa.or_enter')} <code class="mfa-secret">${pending.secret.replace(/(.{4})/g, '$1 ').trim()}</code></li>
+            <li>${tx('mfa.enter_code')}</li>
+          </ol>
+          <div class="mfa-qr">${raw(qrSvg(otpauthUri(pending.secret, me), { label: tx('mfa.qr_label'), px: 4 }) ?? '')}</div>
+          <div class="form-grid">
+            ${input('name', tx('mfa.app_name'), tx('mfa.app_default'), { required: true })}
+            <div class="field"><label class="label" for="f_code">${tx('mfa.code')}</label><input id="f_code" name="code" required inputmode="numeric" pattern="[0-9 ]{6,7}" autocomplete="one-time-code" maxlength="7"></div>
+          </div>
+          <div class="buttons"><button class="btn btn-hot">${tx('mfa.confirm_app')}</button></div></form>
+        <form method="post" action="${BASE}/security/totp/cancel">${csrf(s)}<button class="link-button">${tx('mfa.cancel_setup')}</button></form>`
+      : html`<form method="post" action="${BASE}/security/totp/start">${csrf(s)}
+          <div class="buttons"><button class="btn${factors.length ? '' : ' btn-hot'}"${secretKeyConfigured() ? '' : raw(' disabled')}>${icon('plus')} ${tx('mfa.add_app')}</button></div>
+          ${secretKeyConfigured() ? '' : html`<p class="alert alert-error" role="alert">${tx('mfa.no_key')}</p>`}</form>`;
+    const main = html`<h1 class="u-mb1">${tx('mfa.title')}</h1>
+      <p class="muted u-mt0">${tx('mfa.intro')}</p>
+      ${required && !factors.length ? html`<div class="alert alert-warning" role="alert">${tx('mfa.required_you')}</div>` : ''}
+      ${shownCodes
+        ? region(tx('mfa.codes_title'), html`<p>${tx('mfa.codes_once')}</p>
+            <ol class="mfa-codes">${shownCodes.map((c) => html`<li><code>${c}</code></li>`)}</ol>
+            <form method="post" action="${BASE}/security/codes/confirm">${csrf(s)}
+              <label class="check"><input type="checkbox" name="saved" value="1" required> ${tx('mfa.codes_saved')}</label>
+              <div class="buttons"><button class="btn btn-hot">${tx('mfa.codes_done')}</button></div></form>`, '', 'codes')
+        : ''}
+      <div class="columns">
+        ${region(tx('mfa.apps'), html`${factors.length
+          ? html`<div class="table-wrap"><table class="report report-reflow"><thead><tr><th>${tx('mfa.app_name')}</th><th>${tx('mfa.added')}</th><th>${tx('mfa.last_used')}</th><th></th></tr></thead><tbody>
+              ${factors.map((f) => html`<tr><td data-label="${tx('mfa.app_name')}">${icon('key')} ${f.name}</td><td data-label="${tx('mfa.added')}">${when(f.created_at)}</td><td data-label="${tx('mfa.last_used')}">${when(f.last_used_at)}</td>
+                <td><details class="menu"><summary class="btn btn-sm">${tx('mfa.remove')}</summary><div class="menu-panel"><form method="post" action="${BASE}/security/factor/${f.id}/delete" class="menu-section">${csrf(s)}
+                  ${input(`password_${f.id}`, tx('mfa.your_password'), '', { type: 'password', required: true, auto: 'current-password' })}
+                  <button class="btn btn-sm btn-danger">${tx('mfa.remove_app')}</button></form></div></details></td></tr>`)}
+              </tbody></table></div>`
+          : html`<p class="muted">${tx('mfa.no_apps')}</p>`}
+          ${setup}`)}
+        ${region(tx('mfa.codes_title'), html`<p class="u-mt0">${factors.length || left ? tx('mfa.codes_left', { n: left }) : tx('mfa.codes_after')}</p>
+          ${factors.length && left < 3 ? html`<p class="alert alert-warning" role="status">${tx('mfa.codes_low')}</p>` : ''}
+          ${factors.length ? html`<form method="post" action="${BASE}/security/codes">${csrf(s)}<button class="btn" data-confirm="${tx('mfa.codes_new_confirm')}">${tx('mfa.codes_new')}</button></form>` : ''}`)}
+      </div>`;
+    return send(reply, s, shell(s, tx('mfa.title'), [[tx('mfa.title')]], main, 'developers'));
+  });
+
+  app.post(`${BASE}/security/totp/start`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    if (!secretKeyConfigured()) return back(reply, s, `${BASE}/security`);
+    s.state.__TOTP_NEW = JSON.stringify({ secret: newTotpSecret(), at: Date.now() });
+    return back(reply, s, `${BASE}/security`);
+  });
+
+  app.post(`${BASE}/security/totp/cancel`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    delete s.state.__TOTP_NEW;
+    return back(reply, s, `${BASE}/security`);
+  });
+
+  app.post(`${BASE}/security/totp/confirm`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const tx = tr(s);
+    let pending: { secret: string; at: number } | null = null;
+    try {
+      pending = JSON.parse(String(s.state.__TOTP_NEW ?? ''));
+    } catch {
+      pending = null;
+    }
+    if (!pending || Date.now() - pending.at > SECRET_MINUTES * 60_000) {
+      delete s.state.__TOTP_NEW;
+      flash(s, tx('mfa.setup_expired'), 'error');
+      return back(reply, s, `${BASE}/security`);
+    }
+    const step = matchTotp(unbase32(pending.secret), String(req.body?.code ?? '').replace(/\s/g, ''), null);
+    if (step === null) {
+      flash(s, tx('mfa.wrong_setup'), 'error');
+      return back(reply, s, `${BASE}/security`);
+    }
+    const first = !(await hasFactor(s.username!));
+    await addTotp(s.username!, String(req.body?.name ?? ''), pending.secret, step);
+    delete s.state.__TOTP_NEW;
+    delete s.state.__MFA_DUE;
+    await logActivity({ username: s.username, event: '2fa_enrolled', ip: clientIp(req), detail: 'authenticator app' });
+    // the first app: recovery codes at once (they count only once the developer saved them)
+    if (first || !(await codesLeft(s.username!))) s.state.__CODES_NEW = JSON.stringify(await newRecoveryCodes(s.username!));
+    flash(s, tx('mfa.app_added'));
+    return back(reply, s, `${BASE}/security#codes`);
+  });
+
+  app.post(`${BASE}/security/codes`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    if (!(await hasFactor(s.username!))) return back(reply, s, `${BASE}/security`);
+    s.state.__CODES_NEW = JSON.stringify(await newRecoveryCodes(s.username!));
+    await logActivity({ username: s.username, event: '2fa_codes', ip: clientIp(req), detail: 'new recovery codes' });
+    return back(reply, s, `${BASE}/security#codes`);
+  });
+
+  app.post(`${BASE}/security/codes/confirm`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    if (req.body?.saved !== '1') return back(reply, s, `${BASE}/security#codes`);
+    await confirmRecoveryCodes(s.username!);
+    delete s.state.__CODES_NEW;
+    flash(s, tr(s)('mfa.codes_kept'));
+    return back(reply, s, `${BASE}/security`);
+  });
+
+  app.post(`${BASE}/security/factor/:id(^\\d{1,9}$)/delete`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const tx = tr(s);
+    const me = s.username!;
+    const id = Number(req.params.id);
+    const f = await owner.one('select id from meta.developer_factor where id = $1 and username = $2', [id, me]);
+    if (!f) return reply.code(404).send('Not found');
+    if (!(await verifyPassword(me, String(req.body?.[`password_${id}`] ?? '')))) {
+      await logActivity({ username: me, event: 'login_failed', ip: clientIp(req), detail: 'builder (removing a second factor)' });
+      flash(s, tx('mfa.wrong_password'), 'error');
+      return back(reply, s, `${BASE}/security`);
+    }
+    const last = (await factorsOf(me)).length === 1;
+    if (last) {
+      const pol = await mfaPolicy();
+      const admin = await isAdmin(me);
+      if (requiredFor(pol.policy, admin)) {
+        flash(s, tx('mfa.cannot_remove_required'), 'error');
+        return back(reply, s, `${BASE}/security`);
+      }
+      // (SEC-6) never fewer administrators with a factor than the policy needs
+      if (admin && pol.policy !== 'off') {
+        const { admins, enrolled } = await adminFactors();
+        if (enrolled - 1 < Math.min(2, admins)) {
+          flash(s, tx('mfa.cannot_remove_admin'), 'error');
+          return back(reply, s, `${BASE}/security`);
+        }
+      }
+    }
+    await owner.query('delete from meta.developer_factor where id = $1 and username = $2', [id, me]);
+    if (last) await owner.query('delete from meta.developer_recovery_code where username = $1', [me]);
+    await logActivity({ username: me, event: '2fa_removed', ip: clientIp(req), detail: last ? 'the last authenticator app (recovery codes removed)' : 'an authenticator app' });
+    flash(s, tx('mfa.removed'));
+    return back(reply, s, `${BASE}/security`);
+  });
+
+  // (SEC-6) an administrator resets another developer's second factors: logged, the developer and the administrators told
+  app.post(`${BASE}/developers/reset-2fa`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const tx = tr(s);
+    if (!(await isAdmin(s.username))) return reply.code(403).send('Only administrators reset second factors.');
+    const who = String(req.body?.username ?? '');
+    const reason = String(req.body?.[`reason_${who.replace(/[^\w]/g, '_')}`] ?? req.body?.reason ?? '').trim().slice(0, 200);
+    if (who === s.username) return reply.code(400).send('Use your own Security page.');
+    if (!reason) {
+      flash(s, tx('mfa.reason_needed'), 'error');
+      return back(reply, s, `${BASE}/developers`);
+    }
+    if (!(await resetFactors(who))) return reply.code(404).send('Not found');
+    await logActivity({ username: s.username, event: '2fa_reset', ip: clientIp(req), detail: `${who}: ${reason}` });
+    const dev = await owner.one<{ email: string | null }>('select email from meta.developer where username = $1', [who]);
+    await notifyMfa([dev?.email ?? '', ...(await adminEmails())], `pgkiln: two-factor sign-in of ${who} reset`,
+      `${s.username} removed the second factors of developer ${who} (reason: ${reason}). ${who} signs in with the password only until they set up an authenticator app again.`);
+    flash(s, tx('mfa.reset_done', { user: who }));
+    return back(reply, s, `${BASE}/developers`);
+  });
+
+  // (SEC-2, SEC-6) the instance's policy: off, administrators or all developers, with a grace period
+  app.post(`${BASE}/instance/mfa`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const tx = tr(s);
+    if (!(await isAdmin(s.username))) return reply.code(403).send('Only administrators change the policy.');
+    const policy = MFA_POLICIES.includes(req.body?.policy as MfaPolicy) ? (req.body!.policy as MfaPolicy) : null;
+    const grace = Number(req.body?.grace_days);
+    if (!policy || !Number.isInteger(grace) || grace < 0 || grace > 90) return reply.code(400).send('policy is off, admins or all; grace_days 0 to 90');
+    if (await policyProblem(policy)) {
+      flash(s, tx('mfa.policy_needs_admins'), 'error');
+      return back(reply, s, `${BASE}/instance#mfa`);
+    }
+    await setPolicy(policy, grace);
+    await logActivity({ username: s.username, event: '2fa_policy', ip: clientIp(req), detail: `${policy}, grace ${grace} days` });
+    await notifyMfa(await adminEmails(), `pgkiln: two-factor sign-in policy is now ${policy}`, `${s.username} set the two-factor policy to ${policy} (grace period ${grace} days).`);
+    flash(s, tx('mfa.policy_saved'));
+    return back(reply, s, `${BASE}/instance#mfa`);
+  });
+}
+
+/** The Instance settings region for the policy (administrators). */
+export async function policyRegion(s: Session): Promise<Raw> {
+  const tx = tr(s);
+  const [pol, af, without] = await Promise.all([
+    mfaPolicy(), adminFactors(),
+    owner.query<{ username: string; is_admin: boolean }>('select username, is_admin from meta.developer d where not exists (select 1 from meta.developer_factor f where f.username = d.username) order by username'),
+  ]);
+  const opt = (v: MfaPolicy) => html`<option value="${v}"${pol.policy === v ? raw(' selected') : ''}>${tx(({ off: 'mfa.policy_off', admins: 'mfa.policy_admins', all: 'mfa.policy_all' } as const)[v])}</option>`;
+  return region(tx('mfa.policy_title'), html`<form method="post" action="${BASE}/instance/mfa">${csrf(s)}
+      <div class="form-grid">
+        <div class="field"><label class="label" for="f_policy">${tx('mfa.policy_label')}</label><select id="f_policy" name="policy">${MFA_POLICIES.map(opt)}</select></div>
+        ${input('grace_days', tx('mfa.grace'), pol.graceDays, { type: 'number', help: tx('mfa.grace_help') })}
+      </div>
+      <p class="muted small">${tx('mfa.policy_help', { enrolled: af.enrolled, admins: af.admins })}</p>
+      <div class="buttons"><button class="btn btn-hot">${tx('mfa.policy_save')}</button></div></form>
+    ${without.rows.length ? html`<p class="small">${tx('mfa.without', { list: without.rows.map((d) => `${d.username}${d.is_admin ? ' (admin)' : ''}`).join(', ') })}</p>` : ''}
+    <p class="muted small">${tx('mfa.cli_note')}</p>`, '', 'mfa');
+}

package/src/builder/ui.ts

@@ -12,6 +12,7 @@ import { ensureDevbar } from '../runtime/devbar.ts';
 import { noteChange } from './app-updates.ts';
 import { clientTexts, tr } from './i18n.ts';
 import { languageMenu, loadLanguage } from './language.ts';
+import { enrolmentDue } from '../mfa.ts';
 
 // Shared building blocks of the builder UI.
 
@@ -112,6 +113,7 @@ export function shell(s: Session, title: string, crumbs: [string, string?][], ma
   // (sprint 74) the default-password warning: on the Workspace home (sprint 109), the App Builder home and the Developers page only, until
   // dismissed (for this sign-in); a dot on the avatar stays until the password is changed
   const weak = !!s.state.__WEAK;
+  const mfaDue = typeof s.state.__MFA_DUE === 'string' ? s.state.__MFA_DUE : '';
   const weakBanner = weak && !s.state.__WEAK_HIDDEN && crumbs.length === 1 && (crumbs[0][0] === 'Home' || crumbs[0][0] === 'App Builder' || crumbs[0][0] === 'Developers');
   const trail = crumbs.map(([label, href]): [string, string?] => [tx.label(label), href]);
   const back = [...trail].reverse().find(([, href], i) => i > 0 && href);
@@ -175,6 +177,7 @@ export function shell(s: Session, title: string, crumbs: [string, string?][], ma
               </form></div>
             <div class="menu-section menu-links">
               <a href="${BASE}/developers">${icon('key')} ${tx('user.change_password')}</a>
+              <a href="${BASE}/security">${icon('lock')} ${tx('mfa.menu')}</a>
               <form method="post" action="${BASE}/logout">${csrf(s)}<button>${icon('logout')} ${tx('user.sign_out')}</button></form>
             </div>
           </div></details></li>
@@ -191,7 +194,8 @@ export function shell(s: Session, title: string, crumbs: [string, string?][], ma
         <div class="ide-tools">${opts.toolbar ?? ''}</div>
       </header>
       ${s.workspace?.banner_label ? html`<div class="ide-banner ide-banner-${BANNER_COLORS.includes(s.workspace.banner_color ?? '') ? s.workspace.banner_color : 'blue'}" role="note" aria-label="${tx('bar.environment')}">${s.workspace.banner_label}</div>` : ''}
-      ${weakBanner || ok || err ? html`<div class="ide-alerts">
+      ${weakBanner || mfaDue || ok || err ? html`<div class="ide-alerts">
+        ${mfaDue ? html`<div class="alert alert-warning" role="status">${tx.rich('mfa.banner', { date: mfaDue.slice(0, 10), link: html`<a href="${BASE}/security">${tx('mfa.set_up_now')}</a>` })}</div>` : ''}
         ${weakBanner ? html`<div class="alert alert-error alert-dismissible" role="alert"><span>${tx.rich('weak.banner', { link: html`<a href="${BASE}/developers">${tx('weak.change_now')}</a>` })}</span>
           <form method="post" action="${BASE}/weak/dismiss">${csrf(s)}<button class="link-button" aria-label="${tx('weak.dismiss')}" title="${tx('weak.dismiss')}">${icon('close')}</button></form></div>` : ''}
         ${ok ? html`<div class="alert alert-success" role="status">${ok}</div>` : ''}
@@ -317,6 +321,14 @@ export async function developer(req: Req, reply: FastifyReply) {
   }
   // (sprint 121) a session from before the developer's language was kept in it: the stored choice (language.ts)
   if (s.state.__BLANG === undefined) await loadLanguage(s);
+  // (sprint 126, SEC-2) the two-factor policy: a banner during the grace period, then only the Security page until they enrol
+  delete s.state.__MFA_DUE;
+  const due = await enrolmentDue(s.username, await isAdmin(s.username));
+  if (due?.due === 'grace') s.state.__MFA_DUE = due.until.toISOString();
+  else if (due && !/^\/builder\/(security|logout|language|theme)(?:[/?]|$)/.test(req.url)) {
+    reply.redirect(`${BASE}/security`);
+    return null;
+  }
   // (079) the developer toolbar on the applications' pages in this browser
   await ensureDevbar(req, reply, s);
   // workspaces: an application outside the developer's workspaces doesn't exist for them

package/src/cli/main.ts

@@ -469,6 +469,57 @@ const COMMANDS: Record<string, Command> = {
       });
     },
   },
+  // (sprint 126, SEC-6) lockout recovery on the server, when nobody can sign in to the builder
+  admin: {
+    usage: 'pgkiln admin reset-2fa <developer> | set-2fa-policy off|admins|all [options]',
+    summary: 'lockout recovery: reset a developer\'s two-factor sign-in, set the two-factor policy',
+    details:
+      'pgkiln admin reset-2fa <developer> [--reason <text>]\n' +
+      'pgkiln admin set-2fa-policy off|admins|all [--grace <days>]\n\n' +
+      "reset-2fa removes the developer's authenticator apps and recovery codes and ends their builder\n" +
+      'sessions; they sign in with the password and set up an app again. set-2fa-policy off always works;\n' +
+      'admins and all need at least two administrators with two-factor sign-in (or every one, when there\n' +
+      'are fewer). Both are written to the activity log and mailed to the administrators.',
+    options: { reason: { type: 'string' }, grace: { type: 'string' } },
+    optionHelp: [
+      ['--reason <text>', 'reset-2fa: why (in the activity log and the mail)'],
+      ['--grace <days>', 'set-2fa-policy: days developers have to set up an app (0 to 90, default 7)'],
+    ],
+    positionals: [2, 2],
+    async run(v, [action, arg]) {
+      process.env.RUNTIME_DATABASE_URL ??= process.env.DATABASE_URL; // the CLI runs as the owner
+      const mfa = await import('../mfa.ts');
+      const { logActivity } = await import('../session.ts');
+      const { closePools } = await import('../db.ts');
+      const by = `pgkiln admin (${userInfo().username})`;
+      try {
+        if (action === 'reset-2fa') {
+          const reason = String(v.reason ?? 'command line').slice(0, 200);
+          if (!(await mfa.resetFactors(arg))) throw new Error(`no developer ${arg}`);
+          await logActivity({ username: arg, event: '2fa_reset', ip: 'cli', detail: `${arg}: ${reason} (${by})` });
+          const sent = await mfa.notifyMfa(await mfa.adminEmails(), `pgkiln: two-factor sign-in of ${arg} reset`,
+            `${by} removed the second factors of developer ${arg} on the server (reason: ${reason}).`);
+          out(`Two-factor sign-in of ${arg} reset; their builder sessions ended.${sent ? ` ${sent} administrator(s) told by mail.` : ''}\n`);
+          return EXIT.ok;
+        }
+        if (action === 'set-2fa-policy') {
+          if (!mfa.MFA_POLICIES.includes(arg as never)) throw new UsageError('set-2fa-policy takes off, admins or all');
+          const grace = v.grace === undefined ? (await mfa.mfaPolicy()).graceDays : Number(v.grace);
+          if (!Number.isInteger(grace) || grace < 0 || grace > 90) throw new UsageError('--grace takes 0 to 90 days');
+          const policy = arg as 'off' | 'admins' | 'all';
+          if (await mfa.policyProblem(policy)) throw new Error('at least two administrators (or every one, when there are fewer) need two-factor sign-in first');
+          await mfa.setPolicy(policy, grace);
+          await logActivity({ event: '2fa_policy', ip: 'cli', detail: `${policy}, grace ${grace} days (${by})` });
+          const sent = await mfa.notifyMfa(await mfa.adminEmails(), `pgkiln: two-factor sign-in policy is now ${policy}`, `${by} set the two-factor policy to ${policy} on the server.`);
+          out(`Two-factor policy: ${policy}${policy === 'off' ? '' : `, grace ${grace} days`}.${sent ? ` ${sent} administrator(s) told by mail.` : ''}\n`);
+          return EXIT.ok;
+        }
+        throw new UsageError(`unknown action ${action}: use reset-2fa or set-2fa-policy`);
+      } finally {
+        await closePools();
+      }
+    },
+  },
 };
 
 // ------------------------------------------------------------------ help and dispatch

package/src/mfa.ts

@@ -0,0 +1,260 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import type pg from 'pg';
+import { owner } from './db.ts';
+import { decryptSecret, encryptSecret } from './secrets.ts';
+
+// (sprint 126, SEC-2 and SEC-6) Two-factor sign-in for developers: authenticator apps (TOTP, RFC 6238:
+// HMAC-SHA1, 30-second steps, 6 digits; one step either side is accepted for clock drift, and a step is
+// accepted only once) and one-time recovery codes. The policy (off, administrators, all developers) is a
+// setting; it can only be required while two administrators (or every administrator, when there are fewer)
+// have a working second factor, so it never locks the instance out. The command line resets a developer's
+// factors and turns the policy off without signing in (src/cli/main.ts, `pgkiln admin`).
+
+export const TOTP_STEP = 30;
+export const TOTP_DIGITS = 6;
+export const RECOVERY_CODES = 10;
+export type MfaPolicy = 'off' | 'admins' | 'all';
+export const MFA_POLICIES: MfaPolicy[] = ['off', 'admins', 'all'];
+
+const B32 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+export function base32(buf: Buffer): string {
+  let bits = 0, value = 0, out = '';
+  for (const b of buf) {
+    value = (value << 8) | b;
+    bits += 8;
+    while (bits >= 5) {
+      out += B32[(value >>> (bits - 5)) & 31];
+      bits -= 5;
+    }
+  }
+  if (bits > 0) out += B32[(value << (5 - bits)) & 31];
+  return out;
+}
+export function unbase32(text: string): Buffer {
+  const clean = text.toUpperCase().replace(/[\s=]/g, '');
+  let bits = 0, value = 0;
+  const out: number[] = [];
+  for (const ch of clean) {
+    const i = B32.indexOf(ch);
+    if (i < 0) throw new Error('not base32');
+    value = (value << 5) | i;
+    bits += 5;
+    if (bits >= 8) {
+      out.push((value >>> (bits - 8)) & 255);
+      bits -= 8;
+    }
+  }
+  return Buffer.from(out);
+}
+
+/** A new authenticator secret: 160 random bits, base32 (what apps expect). */
+export const newTotpSecret = () => base32(randomBytes(20));
+
+/** The code of one 30-second step (RFC 4226 dynamic truncation). */
+export function totpAt(secret: Buffer, step: number, digits = TOTP_DIGITS): string {
+  const msg = Buffer.alloc(8);
+  msg.writeBigUInt64BE(BigInt(step));
+  const h = createHmac('sha1', secret).update(msg).digest();
+  const o = h[h.length - 1] & 15;
+  const n = ((h[o] & 127) << 24) | (h[o + 1] << 16) | (h[o + 2] << 8) | h[o + 3];
+  return String(n % 10 ** digits).padStart(digits, '0');
+}
+
+export const stepNow = (ms = Date.now()) => Math.floor(ms / 1000 / TOTP_STEP);
+
+/** The step a code matches (now, or one step either side), newer than `after`; null otherwise. */
+export function matchTotp(secret: Buffer, code: string, after: number | null, now = stepNow()): number | null {
+  if (!/^\d{6}$/.test(code)) return null;
+  const given = Buffer.from(code);
+  let found: number | null = null;
+  for (const step of [now - 1, now, now + 1]) {
+    if (after !== null && step <= after) continue;
+    if (timingSafeEqual(Buffer.from(totpAt(secret, step)), given)) found = step;
+  }
+  return found;
+}
+
+/** The otpauth URI an authenticator app reads from the QR code. */
+export const otpauthUri = (secret: string, account: string, issuer = 'pgkiln') =>
+  `otpauth://totp/${encodeURIComponent(issuer)}:${encodeURIComponent(account)}?secret=${secret}&issuer=${encodeURIComponent(issuer)}&algorithm=SHA1&digits=${TOTP_DIGITS}&period=${TOTP_STEP}`;
+
+// ---------------------------------------------------------------- recovery codes
+
+const CODE_ALPHABET = 'abcdefghjkmnpqrstuvwxyz23456789'; // no 0/o, 1/l/i
+/** A recovery code: ten characters in two groups (xxxxx-xxxxx), about 50 bits. */
+export function newRecoveryCode(): string {
+  const bytes = randomBytes(10);
+  const chars = [...bytes].map((b) => CODE_ALPHABET[b % CODE_ALPHABET.length]).join('');
+  return `${chars.slice(0, 5)}-${chars.slice(5)}`;
+}
+export const normaliseCode = (code: string) => code.toLowerCase().replace(/[^a-z0-9]/g, '');
+export const hashCode = (code: string) => createHash('sha256').update(normaliseCode(code)).digest('hex');
+
+// ---------------------------------------------------------------- the developer's factors
+
+export interface Factor { id: number; kind: 'totp'; name: string; created_at: string; last_used_at: string | null }
+
+export async function factorsOf(username: string, db: Pick<pg.ClientBase, 'query'> = owner.pool): Promise<Factor[]> {
+  return (await db.query<Factor>('select id, kind, name, created_at, last_used_at from meta.developer_factor where username = $1 order by id', [username])).rows;
+}
+
+/** Recovery codes left (confirmed, unused). */
+export async function codesLeft(username: string): Promise<number> {
+  return (await owner.one<{ n: number }>('select count(*)::int as n from meta.developer_recovery_code where username = $1 and confirmed and used_at is null', [username]))!.n;
+}
+
+/** Whether the developer has a working second factor (an authenticator app; recovery codes back it up). */
+export async function hasFactor(username: string): Promise<boolean> {
+  return !!(await owner.one('select 1 as ok from meta.developer_factor where username = $1', [username]));
+}
+
+/** Add an authenticator app (after the developer confirmed a code from it). */
+export async function addTotp(username: string, name: string, secret: string, step: number) {
+  await owner.query(
+    `insert into meta.developer_factor (username, kind, name, secret_enc, last_step, last_used_at) values ($1, 'totp', $2, $3, $4, now())`,
+    [username, name.trim().slice(0, 60) || 'Authenticator', encryptSecret(secret), step],
+  );
+}
+
+/** New recovery codes (the old ones stop working); shown once, counted only when confirmed. */
+export async function newRecoveryCodes(username: string): Promise<string[]> {
+  const codes = Array.from({ length: RECOVERY_CODES }, newRecoveryCode);
+  await owner.tx(async (c) => {
+    await c.query('delete from meta.developer_recovery_code where username = $1', [username]);
+    for (const code of codes) await c.query('insert into meta.developer_recovery_code (username, code_hash) values ($1, $2)', [username, hashCode(code)]);
+  });
+  return codes;
+}
+
+export async function confirmRecoveryCodes(username: string) {
+  await owner.query('update meta.developer_recovery_code set confirmed = true where username = $1 and used_at is null', [username]);
+}
+
+/**
+ * Check a second-factor code at sign-in: an authenticator code (each step once) or a confirmed, unused
+ * recovery code (then used up). Returns what matched, or null.
+ */
+export async function checkSecondFactor(username: string, code: string): Promise<{ kind: 'totp' | 'recovery'; name?: string } | null> {
+  const digits = code.replace(/\s/g, '');
+  if (/^\d{6}$/.test(digits)) {
+    const rows = (await owner.query<{ id: number; name: string; secret_enc: string; last_step: string | null }>(
+      'select id, name, secret_enc, last_step from meta.developer_factor where username = $1 and kind = $2', [username, 'totp'])).rows;
+    for (const f of rows) {
+      let secret: Buffer;
+      try {
+        secret = unbase32(decryptSecret(f.secret_enc));
+      } catch {
+        continue; // the instance key changed: recovery codes still work
+      }
+      const step = matchTotp(secret, digits, f.last_step === null ? null : Number(f.last_step));
+      // the update only wins once per step, also with two requests at the same time
+      if (step !== null && (await owner.query('update meta.developer_factor set last_step = $2, last_used_at = now() where id = $1 and (last_step is null or last_step < $2)', [f.id, step])).rowCount)
+        return { kind: 'totp', name: f.name };
+    }
+    return null;
+  }
+  if (normaliseCode(code).length !== 10) return null;
+  const used = await owner.query(
+    'update meta.developer_recovery_code set used_at = now() where username = $1 and code_hash = $2 and confirmed and used_at is null',
+    [username, hashCode(code)]);
+  return used.rowCount ? { kind: 'recovery' } : null;
+}
+
+// ---------------------------------------------------------------- policy
+
+export async function mfaPolicy(): Promise<{ policy: MfaPolicy; since: Date | null; graceDays: number }> {
+  const rows = (await owner.query<{ name: string; value: string }>(`select name, value from meta.setting where name in ('mfa_required', 'mfa_required_since', 'mfa_grace_days')`)).rows;
+  const get = (n: string) => rows.find((r) => r.name === n)?.value;
+  const p = get('mfa_required');
+  const since = get('mfa_required_since');
+  const grace = Number(get('mfa_grace_days'));
+  return { policy: MFA_POLICIES.includes(p as MfaPolicy) ? (p as MfaPolicy) : 'off', since: since ? new Date(since) : null, graceDays: Number.isInteger(grace) && grace >= 0 && grace <= 90 ? grace : 7 };
+}
+
+/** Does the policy require a second factor of this developer? */
+export const requiredFor = (policy: MfaPolicy, isAdmin: boolean) => policy === 'all' || (policy === 'admins' && isAdmin);
+
+/** The administrators, and how many of them have a working second factor. */
+export async function adminFactors(): Promise<{ admins: number; enrolled: number }> {
+  return (await owner.one<{ admins: number; enrolled: number }>(
+    `select count(*)::int as admins,
+            count(*) filter (where exists (select 1 from meta.developer_factor f where f.username = d.username))::int as enrolled
+       from meta.developer d where d.is_admin`))!;
+}
+
+/** Why the policy can't be required now (two administrators with a factor, or every one when fewer), or null. */
+export async function policyProblem(policy: MfaPolicy): Promise<'admins' | null> {
+  if (policy === 'off') return null;
+  const { admins, enrolled } = await adminFactors();
+  return enrolled >= Math.min(2, admins) && enrolled > 0 ? null : 'admins';
+}
+
+/** (SEC-6) Would taking `username` out of the administrators (a role change, removal) break the rule above? */
+export async function leavesTooFewAdmins(username: string): Promise<boolean> {
+  const { policy } = await mfaPolicy();
+  if (policy === 'off') return false;
+  const r = (await owner.one<{ admins: number; enrolled: number }>(
+    `select count(*)::int as admins,
+            count(*) filter (where exists (select 1 from meta.developer_factor f where f.username = d.username))::int as enrolled
+       from meta.developer d where d.is_admin and d.username <> $1`, [username]))!;
+  return !(r.enrolled >= Math.min(2, r.admins) && r.enrolled > 0);
+}
+
+/** Set the policy; `force` skips the two-administrator rule (only the command line uses it, to turn it off). */
+export async function setPolicy(policy: MfaPolicy, graceDays: number) {
+  await owner.tx(async (c) => {
+    const cur = (await c.query<{ value: string }>(`select value from meta.setting where name = 'mfa_required'`)).rows[0]?.value ?? 'off';
+    await c.query(`insert into meta.setting (name, value) values ('mfa_required', $1), ('mfa_grace_days', $2) on conflict (name) do update set value = excluded.value`, [policy, String(graceDays)]);
+    // the grace period counts from when a stricter policy was turned on
+    if (policy !== 'off' && (cur === 'off' || (cur === 'admins' && policy === 'all')))
+      await c.query(`insert into meta.setting (name, value) values ('mfa_required_since', now()::text) on conflict (name) do update set value = excluded.value`);
+    if (policy === 'off') await c.query(`delete from meta.setting where name = 'mfa_required_since'`);
+  });
+}
+
+/**
+ * A developer without a factor while the policy requires one: 'grace' until the grace period ends (a
+ * banner), then 'enrol' (only the Security page and signing out until they enrol); null otherwise.
+ */
+export async function enrolmentDue(username: string, isAdmin: boolean): Promise<{ due: 'grace' | 'enrol'; until: Date } | null> {
+  const { policy, since, graceDays } = await mfaPolicy();
+  if (!requiredFor(policy, isAdmin) || (await hasFactor(username))) return null;
+  const until = new Date((since ?? new Date()).getTime() + graceDays * 86_400_000);
+  return { due: Date.now() < until.getTime() ? 'grace' : 'enrol', until };
+}
+
+/** Remove every second factor of a developer (an administrator, or the command line) and end their sessions. */
+export async function resetFactors(username: string): Promise<boolean> {
+  return owner.tx(async (c) => {
+    const known = (await c.query('select 1 from meta.developer where username = $1', [username])).rowCount;
+    if (!known) return false;
+    await c.query('delete from meta.developer_factor where username = $1', [username]);
+    await c.query('delete from meta.developer_recovery_code where username = $1', [username]);
+    await c.query('delete from meta.session where app_id is null and username = $1', [username]);
+    return true;
+  });
+}
+
+/** The e-mail addresses of the administrators (to tell them about a reset or a policy change). */
+export async function adminEmails(): Promise<string[]> {
+  return (await owner.query<{ email: string }>(`select email from meta.developer where is_admin and email is not null`)).rows.map((r) => r.email);
+}
+
+/** Tell people about a reset or a policy change by mail, when the builder has a mail service (best effort). */
+export async function notifyMfa(to: string[], subject: string, text: string): Promise<number> {
+  const list = [...new Set(to.filter(Boolean))];
+  if (!list.length) return 0;
+  const { builderMail } = await import('./builder/find-workspace.ts');
+  const { sendWith } = await import('./mail/mail.ts');
+  const mail = await builderMail().catch(() => null);
+  if (!mail) return 0;
+  let sent = 0;
+  for (const address of list)
+    try {
+      await sendWith(mail.service, { from: mail.from, to: [address], cc: [], bcc: [], replyTo: null, subject, text, html: null, attachments: [] });
+      sent++;
+    } catch {
+      // the activity log has the event; a mail that fails doesn't undo it
+    }
+  return sent;
+}