pgkiln 0.64.0 → 0.66.0

package/src/runtime/two-step.ts

@@ -1,8 +1,12 @@
+import { isIP } from 'node:net';
 import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
 import {
-  accountCodesLeft, accountFactors, accountHasFactor, accountId, addAccountTotp, checkAccountCode, confirmAccountCodes, mfaOn, mfaRequired,
-  newAccountCodes, removeAccountFactor, secondStep, withSecondStep,
+  accountCodesLeft, accountFactors, accountHasFactor, accountId, accountMustUseMfa, accountPasskeys, accountUserHandle, addAccountPasskey,
+  addAccountTotp, checkAccountCode, confirmAccountCodes, EMAIL_CODE_MINUTES, emailCodeHash, emailCodeMatches, emailCodeTarget, markSecondStep,
+  mfaOn, mfaRequired, newAccountCodes, newEmailCode, queueEmailCode, removeAccountFactor, secondStep, secondStepWithin, TOKEN_STEP_MINUTES,
+  useAccountPasskey, withSecondStep,
 } from '../account-mfa.ts';
+import { issueApiToken, MAX_TOKEN_HOURS } from '../api.ts';
 import { html, raw, type Raw } from '../html.ts';
 import { documentShell } from '../layout.ts';
 import { accountRoles, type App } from '../metadata.ts';
@@ -11,10 +15,12 @@ import { qrSvg } from '../qrcode.ts';
 import { secretKeyConfigured } from '../secrets.ts';
 import { loginWindowMinutes } from '../security.ts';
 import { clientIp, getSession, loginThrottled, logActivity, saveState, type Session } from '../session.ts';
+import { ALGORITHMS, giveChallenge, relyingParty, takeChallenge, verifyAssertion, verifyRegistration, WebAuthnError } from '../webauthn.ts';
 import type { PageContext } from './context.ts';
 import type { Locale } from './locale.ts';
 import { pwaHead } from './pwa.ts';
-import { appWithLocale, completeLogin, loadContext, rootAttrs, safeNext, signIn, type Req } from './routes.ts';
+import { loadProvider, type Provider } from '../sso.ts';
+import { appWithLocale, completeLogin, loadContext, rootAttrs, safeNext, signIn, ssoStepUp, type Req } from './routes.ts';
 
 // (sprint 130, SEC-3) The second step of signing in to an application, and "Two-step sign-in" on My account.
 //
@@ -24,10 +30,19 @@ import { appWithLocale, completeLogin, loadContext, rootAttrs, safeNext, signIn,
 // the step and the user has no app yet, the same page shows a QR code first, then the recovery codes once. Wrong
 // codes count as failed sign-ins (the same lockout). The sign-in's method gets "+2fa", so a remembered or shared
 // sign-in made from it may skip the step later.
+//
+// (sprint 131, SEC-3 part 2) Passkeys (WebAuthn, src/webauthn.ts; public/app.js [data-passkey]) at the second step
+// and on My account, also as the first factor a user adds while signing in; a code by e-mail when the application
+// allows it, for users who have another factor; step-up: a signed-in user whose page needs a more recent second step
+// comes here with ?next= and goes back after it (the session's __MFA_AT); and My account → REST API token.
+//
+// (sprint 132, SEC-4) A session signed in through an identity provider steps up there instead: the provider signs the
+// user in again with a second factor (sso.ts, saml.ts), unless the provider leaves the second step to pgkiln.
 
 const PENDING = '__MFA';
 const STEP_SECONDS = 300;
 const ENROL_SECONDS = 600;
+const EMAILS_PER_STEP = 3;
 
 interface Pending {
   u: string;
@@ -39,21 +54,31 @@ interface Pending {
   detail?: string;
   at: number;
   enrol?: boolean;
+  /** (sprint 131) a signed-in user asked again (step-up): no new session, back to `next` */
+  stepup?: boolean;
   /** while adding an app: the new secret, then (after its first code) the recovery codes to show once */
   secret?: string;
   codes?: string[];
+  /** (sprint 131) what was added while signing in, for the activity log */
+  added?: 'app' | 'passkey';
+  /** (sprint 131) a code sent by e-mail: its hash, when, and how many were sent in this step */
+  mail?: { h: string; at: number; n: number };
 }
 
 function pendingOf(s: Session): Pending | null {
   try {
     const p = JSON.parse(String(s.state[PENDING] ?? '')) as Pending;
     const limit = (p?.enrol ? ENROL_SECONDS : STEP_SECONDS) * 1000;
-    return p && typeof p.u === 'string' && Date.now() - Number(p.at) < limit ? p : null;
+    if (!p || typeof p.u !== 'string' || Date.now() - Number(p.at) >= limit) return null;
+    // a step-up belongs to the signed-in user; a sign-in's step to a signed-out session
+    return !!p.stepup === !!s.username && (!p.stepup || p.u === s.username) ? p : null;
   } catch {
     return null;
   }
 }
 
+const keep = (s: Session, p: Pending) => { s.state[PENDING] = JSON.stringify(p); };
+
 interface PasswordSignIn {
   next?: string;
   remember?: boolean;
@@ -71,20 +96,19 @@ export async function passwordSignIn(req: FastifyRequest, reply: FastifyReply, a
   const roles = [...(await accountRoles(a.id, username)), ...(opts.extraRoles ?? []).map((r) => r.toLowerCase())];
   const need = await secondStep(a, username, roles);
   if (!need) return completeLogin(req, reply, a, session, username, opts);
-  const p: Pending = { u: username, ...opts, at: Date.now(), enrol: need === 'enrol' };
-  session.state[PENDING] = JSON.stringify(p);
+  keep(session, { u: username, ...opts, at: Date.now(), enrol: need === 'enrol' });
   await saveState(session);
   return reply.redirect(`/a/${a.alias}/login/2fa`, 303);
 }
 
-function card(a: App, locale: Locale, title: string, body: Raw) {
+function card(a: App, locale: Locale, title: string, body: Raw, back = `/a/${a.alias}/login`) {
   return documentShell(
     `${title} · ${a.name}`,
     html`<main class="login">
       <div class="card login-card">
         <h1>${title}</h1>
         ${body}
-        <a class="login-forgot" href="/a/${a.alias}/login">${locale.t('reset.back')}</a>
+        <a class="login-forgot" href="${back}">${locale.t('reset.back')}</a>
       </div>
     </main>`,
     'login-body',
@@ -95,86 +119,166 @@ function card(a: App, locale: Locale, title: string, body: Raw) {
 }
 
 const csrfField = (s: Session) => html`<input type="hidden" name="__csrf" value="${s.csrf_token}">`;
-const alert = (error?: string) => html`${error ? html`<div class="alert alert-error" role="alert">${error}</div>` : ''}`;
+const alert = (error?: string, kind = 'error') => html`${error ? html`<div class="alert alert-${kind}" role="${kind === 'error' ? 'alert' : 'status'}">${error}</div>` : ''}`;
 const grouped = (secret: string) => secret.replace(/(.{4})/g, '$1 ').trim();
 
 function codesList(codes: string[]) {
   return html`<ol class="mfa-codes">${codes.map((c) => html`<li><code>${c}</code></li>`)}</ol>`;
 }
 
+/** The hidden fields public/app.js fills with the browser's WebAuthn answer. */
+const passkeyFields = (names: string[]) => html`${names.map((n) => html`<input type="hidden" name="${n}">`)}`;
+const ASSERTION = ['credentialId', 'clientDataJSON', 'authenticatorData', 'signature', 'userHandle'];
+const ATTESTATION = ['clientDataJSON', 'attestationObject', 'transports'];
+
+/** What the second step's page offers besides a code. */
+interface Offers { passkey: boolean; mail: boolean; newPasskey: boolean; notice?: string }
+
 /** The second step's page: a code; or a new app (QR code, then its first code); or the recovery codes, once. */
-function stepPage(a: App, locale: Locale, s: Session, p: Pending, error?: string) {
+function stepPage(a: App, locale: Locale, s: Session, p: Pending, offers: Offers, error?: string) {
   const t = locale.t;
   const action = `/a/${a.alias}/login/2fa`;
+  const back = p.stepup ? safeNext(a, p.next) : undefined;
   if (p.codes)
     return card(a, locale, t('mfa.codes_title'), html`<p>${t('mfa.codes_once')}</p>${codesList(p.codes)}
       <form method="post" action="${action}/done" class="login-form">${csrfField(s)}
         <label class="check"><input type="checkbox" name="saved" value="1" required> ${t('mfa.codes_saved')}</label>
         <button class="btn btn-hot">${t('mfa.continue')}</button></form>`);
-  if (p.enrol && p.secret)
+  if (p.enrol && (p.secret || offers.newPasskey))
     return card(a, locale, t('mfa.enrol_title'), html`<p class="muted">${t('mfa.enrol_intro')}</p>${alert(error)}
-      <ol class="mfa-steps">
-        <li>${t('mfa.scan')}</li>
-        <li>${t('mfa.or_enter')} <code class="mfa-secret">${grouped(p.secret)}</code></li>
-        <li>${t('mfa.enter_code')}</li>
-      </ol>
-      <div class="mfa-qr">${raw(qrSvg(otpauthUri(p.secret, p.u, a.name), { label: t('mfa.qr_label'), px: 4 }) ?? '')}</div>
-      <form method="post" action="${action}" class="login-form">${csrfField(s)}
-        <div class="field"><label class="label" for="code">${t('mfa.code')}</label><input id="code" name="code" required inputmode="numeric" autocomplete="one-time-code" maxlength="7" autofocus></div>
-        <button class="btn btn-hot">${t('mfa.verify')}</button></form>`);
-  return card(a, locale, t('mfa.step_title'), html`<p class="muted">${t('mfa.step_intro')}</p>${alert(error)}
+      ${p.secret
+        ? html`<ol class="mfa-steps">
+            <li>${t('mfa.scan')}</li>
+            <li>${t('mfa.or_enter')} <code class="mfa-secret">${grouped(p.secret)}</code></li>
+            <li>${t('mfa.enter_code')}</li>
+          </ol>
+          <div class="mfa-qr">${raw(qrSvg(otpauthUri(p.secret, p.u, a.name), { label: t('mfa.qr_label'), px: 4 }) ?? '')}</div>
+          <form method="post" action="${action}" class="login-form">${csrfField(s)}
+            <div class="field"><label class="label" for="code">${t('mfa.code')}</label><input id="code" name="code" required inputmode="numeric" autocomplete="one-time-code" maxlength="7" autofocus></div>
+            <button class="btn btn-hot">${t('mfa.verify')}</button></form>`
+        : ''}
+      ${offers.newPasskey
+        ? html`<form method="post" action="${action}/passkey/new" class="login-form mfa-passkey">${csrfField(s)}${passkeyFields(ATTESTATION)}
+            <p class="muted">${p.secret ? t('mfa.or_passkey') : t('mfa.passkey_intro')}</p>
+            <button class="btn${p.secret ? '' : ' btn-hot'}" hidden data-passkey="${action}/passkey/new/options" data-passkey-error="${t('mfa.passkey_failed')}">${t('mfa.add_passkey')}</button>
+            <p class="small" role="status" data-passkey-status></p></form>`
+        : ''}`);
+  return card(a, locale, p.stepup ? t('mfa.stepup_title') : t('mfa.step_title'), html`<p class="muted">${p.stepup ? t('mfa.stepup_intro') : t('mfa.step_intro')}</p>
+    ${alert(offers.notice, 'success')}${alert(error)}
     <form method="post" action="${action}" class="login-form">${csrfField(s)}
       <div class="field"><label class="label" for="code">${t('mfa.code')}</label><input id="code" name="code" required autocomplete="one-time-code" maxlength="20" spellcheck="false" autocapitalize="off" autofocus></div>
-      <button class="btn btn-hot">${t('mfa.verify')}</button></form>`);
+      <button class="btn btn-hot">${t('mfa.verify')}</button></form>
+    ${offers.passkey
+      ? html`<form method="post" action="${action}/passkey" class="login-form mfa-passkey">${csrfField(s)}${passkeyFields(ASSERTION)}
+          <button class="btn" hidden data-passkey="${action}/passkey/options" data-passkey-error="${t('mfa.passkey_failed')}">${t('mfa.use_passkey')}</button>
+          <p class="small" role="status" data-passkey-status></p></form>`
+      : ''}
+    ${offers.mail
+      ? html`<form method="post" action="${action}/email" class="login-form">${csrfField(s)}<button class="link-button">${t('mfa.email_send')}</button></form>`
+      : ''}`, back);
 }
 
-/** The signed-out session's pending sign-in, or a page that says it expired. */
+/** The signed-out session's pending sign-in (or a signed-in user's step-up), or a page that says it expired. */
 async function start(req: Req, reply: FastifyReply) {
   const loaded = await appWithLocale(req, req.params.alias);
   if (!loaded) return null;
   const session = await getSession(req, reply, loaded.app.id, `/a/${loaded.app.alias}`);
   const { app: a, locale } = (await appWithLocale(req, req.params.alias, session))!;
-  const p = session.username ? null : pendingOf(session);
-  return { a, locale, session, p };
+  return { a, locale, session, p: pendingOf(session) };
 }
 
 const expired = async (reply: FastifyReply, a: App, locale: Locale, s: Session) => {
+  const wasStepUp = !!s.username;
   delete s.state[PENDING];
   await saveState(s);
+  if (wasStepUp) return reply.redirect(`/a/${a.alias}/${a.home_page}`, 303);
   return reply.code(410).type('text/html').send(card(a, locale, locale.t('mfa.step_title'), alert(locale.t('mfa.expired'))));
 };
 
-/** Sign in with the pending sign-in's options, now with "+2fa" in its method. */
+/** What the page offers this user here: their passkeys for this site, an e-mail code, a new passkey while enrolling. */
+async function offersFor(req: FastifyRequest, a: App, p: Pending, id: number, notice?: string): Promise<Offers> {
+  const rp = relyingParty(req);
+  const host = !isIP(rp.rpId);
+  const [keys, mail] = await Promise.all([accountPasskeys(id, rp.rpId), p.enrol ? null : emailCodeTarget(a, id)]);
+  return { passkey: host && keys.length > 0, mail: !!mail && (p.mail?.n ?? 0) < EMAILS_PER_STEP, newPasskey: host && !!p.enrol && !p.codes, notice };
+}
+
+/** Signed in (or, for a step-up, confirmed) with the pending sign-in's options, now with "+2fa" in its method. */
 async function finish(req: Req, reply: FastifyReply, a: App, s: Session, p: Pending, detail: string, next?: string, flash?: string) {
+  if (p.stepup) {
+    delete s.state[PENDING];
+    markSecondStep(s.state);
+    if (flash) s.state.__FLASH = flash;
+    await saveState(s);
+    await logActivity({ appId: a.id, username: p.u, event: '2fa_stepup', ip: clientIp(req), detail });
+    return reply.redirect(safeNext(a, p.next), 303);
+  }
   const n = await signIn(req, reply, a, s, p.u, {
     extraRoles: p.extraRoles, groups: p.groups, remember: p.remember, method: withSecondStep(p.method),
     detail: `${p.detail ?? 'password'} ${detail}`,
   });
-  if (flash) {
-    n.state.__FLASH = flash;
-    await saveState(n);
-  }
+  markSecondStep(n.state);
+  if (flash) n.state.__FLASH = flash;
+  await saveState(n);
   return reply.redirect(next ?? safeNext(a, p.next), 303);
 }
 
+/** Too many wrong codes: the same lockout as wrong passwords. Returns a reply when locked. */
+async function locked(reply: FastifyReply, a: App, locale: Locale, s: Session, p: Pending, ip: string, what: string) {
+  if (!(await loginThrottled(a.id, p.u, ip))) return null;
+  logActivity({ appId: a.id, username: p.u, event: 'login_locked', ip, detail: what });
+  delete s.state[PENDING];
+  await saveState(s);
+  return reply.code(429).type('text/html').send(card(a, locale, locale.t('mfa.step_title'), alert(locale.t('login.throttled', { minutes: loginWindowMinutes() }))));
+}
+
+/** (sprint 132) The identity provider a step-up goes back to: the one the session signed in with, if it decides itself. */
+async function stepUpProvider(a: App, s: Session): Promise<Provider | null> {
+  const method = String(s.state.__SIGNIN ?? '');
+  if (!method.startsWith('sso:')) return null;
+  const name = method.slice(4).replace(/\+2fa$/, '');
+  const p = a.sso_providers.includes(name) ? await loadProvider(name) : undefined;
+  return p && !p.local_second_step ? p : null;
+}
+
 export async function twoStepRoutes(app: FastifyInstance) {
   app.get('/a/:alias/login/2fa', async (req: Req, reply) => {
     const r = await start(req, reply);
     if (!r) return reply.code(404).send('Not found');
-    const { a, locale, session: s, p } = r;
+    const { a, locale, session: s } = r;
+    let p = r.p;
+    // (sprint 131) step-up: a signed-in user sent here by a page that needs a more recent second step
+    const next = typeof (req.query as { next?: unknown }).next === 'string' ? String((req.query as { next: string }).next).slice(0, 2000) : undefined;
+    if (s.username && (!p || (next && p.next !== next))) {
+      const via = await stepUpProvider(a, s);
+      if (via)
+        return ssoStepUp(reply, a, s, via, next ?? `/a/${a.alias}/${a.home_page}`).catch((e) => {
+          req.log.warn({ err: e }, 'sso step-up failed');
+          return reply.code(502).type('text/html').send(card(a, locale, locale.t('mfa.stepup_title'),
+            alert(locale.t('login.sso_unavailable', { provider: via.display_name })), `/a/${a.alias}/${a.home_page}`));
+        });
+      const id = await accountId(s.username);
+      if (id === null || !(await accountHasFactor(id)))
+        return reply.code(403).type('text/html').send(card(a, locale, locale.t('mfa.stepup_title'),
+          html`${alert(locale.t('mfa.stepup_none'))}<p><a class="btn" href="/a/${a.alias}/account#two-step">${locale.t('mfa.my_account')}</a></p>`, `/a/${a.alias}/${a.home_page}`));
+      p = { u: s.username, next, at: Date.now(), stepup: true };
+      keep(s, p);
+    }
     if (!p) return expired(reply, a, locale, s);
     const id = await accountId(p.u);
     if (id === null) return expired(reply, a, locale, s);
+    const offers = await offersFor(req, a, p, id);
     if (p.enrol && !p.codes && !(await accountHasFactor(id))) {
-      // fail closed: without the instance key there is nowhere safe to keep the app's secret
-      if (!secretKeyConfigured()) return reply.code(503).type('text/html').send(card(a, locale, locale.t('mfa.enrol_title'), alert(locale.t('mfa.no_key'))));
-      if (!p.secret) {
+      // fail closed: without the instance key there is nowhere safe to keep the app's secret (a passkey needs none)
+      if (!secretKeyConfigured() && !offers.newPasskey)
+        return reply.code(503).type('text/html').send(card(a, locale, locale.t('mfa.enrol_title'), alert(locale.t('mfa.no_key'))));
+      if (!p.secret && secretKeyConfigured()) {
         p.secret = newTotpSecret();
-        s.state[PENDING] = JSON.stringify(p);
+        keep(s, p);
       }
     }
     await saveState(s);
-    return reply.type('text/html').send(stepPage(a, locale, s, p));
+    return reply.header('cache-control', 'no-store').type('text/html').send(stepPage(a, locale, s, p, offers));
   });
 
   app.post('/a/:alias/login/2fa', async (req: Req, reply) => {
@@ -186,53 +290,163 @@ export async function twoStepRoutes(app: FastifyInstance) {
     const ip = clientIp(req);
     const id = await accountId(p.u);
     if (id === null) return expired(reply, a, locale, s);
-    if (await loginThrottled(a.id, p.u, ip)) {
-      logActivity({ appId: a.id, username: p.u, event: 'login_locked', ip, detail: '2fa' });
-      delete s.state[PENDING];
-      await saveState(s);
-      return reply.code(429).type('text/html').send(card(a, locale, t('mfa.step_title'), alert(t('login.throttled', { minutes: loginWindowMinutes() }))));
-    }
+    const lock = await locked(reply, a, locale, s, p, ip, '2fa');
+    if (lock) return lock;
     const code = String(req.body?.code ?? '').slice(0, 40);
+    const wrong = async (detail: string) => {
+      await logActivity({ appId: a.id, username: p.u, event: 'login_failed', ip, detail });
+      return reply.code(401).type('text/html').send(stepPage(a, locale, s, p, await offersFor(req, a, p, id), t('mfa.wrong')));
+    };
     // adding the first app while signing in: its first code proves it works
     if (p.enrol && p.secret && !p.codes) {
       const step = matchTotp(unbase32(p.secret), code.replace(/\s/g, ''), null);
-      if (step === null) {
-        await logActivity({ appId: a.id, username: p.u, event: 'login_failed', ip, detail: '2fa (new app)' });
-        return reply.code(401).type('text/html').send(stepPage(a, locale, s, p, t('mfa.wrong')));
-      }
+      if (step === null) return wrong('2fa (new app)');
       await addAccountTotp(id, t('mfa.app_default'), p.secret, step);
       await logActivity({ appId: a.id, username: p.u, event: '2fa_enrolled', ip, detail: 'authenticator app (sign-in)' });
       p.codes = await newAccountCodes(id);
+      p.added = 'app';
       delete p.secret;
-      s.state[PENDING] = JSON.stringify(p);
+      keep(s, p);
       await saveState(s);
-      return reply.type('text/html').send(stepPage(a, locale, s, p));
+      return reply.type('text/html').send(stepPage(a, locale, s, p, await offersFor(req, a, p, id)));
     }
-    const ok = await checkAccountCode(id, code);
-    if (!ok) {
-      await logActivity({ appId: a.id, username: p.u, event: 'login_failed', ip, detail: '2fa' });
-      return reply.code(401).type('text/html').send(stepPage(a, locale, s, p, t('mfa.wrong')));
+    if (p.enrol) return expired(reply, a, locale, s);
+    // (sprint 131) the code sent by e-mail, valid for some minutes and once
+    if (p.mail && Date.now() - p.mail.at < EMAIL_CODE_MINUTES * 60_000 && emailCodeMatches(p.mail.h, code)) {
+      delete p.mail;
+      keep(s, p);
+      return finish(req, reply, a, s, p, '2fa (e-mail code)');
     }
+    const ok = await checkAccountCode(id, code);
+    if (!ok) return wrong('2fa');
     if (ok.kind === 'recovery') {
       const left = await accountCodesLeft(id);
       await logActivity({ appId: a.id, username: p.u, event: '2fa_recovery_used', ip, detail: `${left} left` });
       // to My account: one code fewer, maybe time for new ones
-      return finish(req, reply, a, s, p, '2fa (recovery code)', `/a/${a.alias}/account#two-step`, t('mfa.recovery_used', { n: left }));
+      return finish(req, reply, a, s, p, '2fa (recovery code)', p.stepup ? undefined : `/a/${a.alias}/account#two-step`, t('mfa.recovery_used', { n: left }));
     }
     return finish(req, reply, a, s, p, '2fa');
   });
 
-  // the recovery codes were shown once after adding the first app while signing in
+  // (sprint 131) a code by e-mail, for a user who has an authenticator app or a passkey (never the only factor)
+  app.post('/a/:alias/login/2fa/email', async (req: Req, reply) => {
+    const r = await start(req, reply);
+    if (!r) return reply.code(404).send('Not found');
+    const { a, locale, session: s, p } = r;
+    const t = locale.t;
+    if (!p || p.enrol || req.body?.__csrf !== s.csrf_token) return expired(reply, a, locale, s);
+    const ip = clientIp(req);
+    const id = await accountId(p.u);
+    if (id === null) return expired(reply, a, locale, s);
+    const lock = await locked(reply, a, locale, s, p, ip, '2fa e-mail');
+    if (lock) return lock;
+    const target = (p.mail?.n ?? 0) < EMAILS_PER_STEP ? await emailCodeTarget(a, id) : null;
+    const code = newEmailCode();
+    const sent = !!target && (await queueEmailCode(a, p.u, target,
+      t('mfa.email_subject', { app: a.name }), t('mfa.email_body', { app: a.name, code, minutes: EMAIL_CODE_MINUTES })));
+    if (sent) {
+      p.mail = { h: emailCodeHash(code), at: Date.now(), n: (p.mail?.n ?? 0) + 1 };
+      keep(s, p);
+      await logActivity({ appId: a.id, username: p.u, event: '2fa_email', ip, detail: 'code sent' });
+    }
+    await saveState(s);
+    const offers = await offersFor(req, a, p, id, sent ? t('mfa.email_sent', { minutes: EMAIL_CODE_MINUTES }) : undefined);
+    return reply.code(sent ? 200 : 429).type('text/html').send(stepPage(a, locale, s, p, offers, sent ? undefined : t('mfa.email_failed')));
+  });
+
+  // (sprint 131) the second step with a passkey: options for navigator.credentials.get(), then the browser's answer
+  app.post('/a/:alias/login/2fa/passkey/options', async (req: Req, reply) => {
+    const r = await start(req, reply);
+    if (!r) return reply.code(404).send('Not found');
+    const { session: s, p } = r;
+    if (!p || p.enrol || req.body?.__csrf !== s.csrf_token) return reply.code(403).send('Sign in again.');
+    const id = await accountId(p.u);
+    const rp = relyingParty(req);
+    const keys = id === null ? [] : await accountPasskeys(id, rp.rpId);
+    if (!keys.length) return reply.code(404).send('No passkey for this site.');
+    const challenge = giveChallenge(s, 'get');
+    await saveState(s);
+    return reply.header('cache-control', 'no-store').send({ mode: 'get', challenge, rpId: rp.rpId, allow: keys.map((k) => ({ id: k.credential_id, transports: k.transports })) });
+  });
+
+  app.post('/a/:alias/login/2fa/passkey', async (req: Req, reply) => {
+    const r = await start(req, reply);
+    if (!r) return reply.code(404).send('Not found');
+    const { a, locale, session: s, p } = r;
+    const challenge = takeChallenge(s, 'get');
+    if (!p || p.enrol || req.body?.__csrf !== s.csrf_token) return expired(reply, a, locale, s);
+    const ip = clientIp(req);
+    const id = await accountId(p.u);
+    if (id === null) return expired(reply, a, locale, s);
+    const lock = await locked(reply, a, locale, s, p, ip, '2fa passkey');
+    if (lock) return lock;
+    const rp = relyingParty(req);
+    const key = (await accountPasskeys(id, rp.rpId)).find((k) => k.credential_id === String(req.body?.credentialId ?? ''));
+    let why = key ? '' : 'unknown passkey';
+    if (key && !challenge) why = 'no or an expired challenge';
+    if (key && challenge) {
+      try {
+        const v = verifyAssertion(
+          { clientDataJSON: String(req.body?.clientDataJSON ?? ''), authenticatorData: String(req.body?.authenticatorData ?? ''), signature: String(req.body?.signature ?? '') },
+          { alg: key.alg, jwk: key.public_key, signCount: Number(key.sign_count) }, { challenge, ...rp });
+        if (!(await useAccountPasskey(key.id, key.sign_count, v.signCount))) why = 'used at the same time elsewhere';
+      } catch (e) {
+        why = e instanceof WebAuthnError ? e.message : 'unreadable answer';
+      }
+    }
+    if (why) {
+      await logActivity({ appId: a.id, username: p.u, event: 'login_failed', ip, detail: `2fa passkey: ${why}` });
+      await saveState(s);
+      return reply.code(401).type('text/html').send(stepPage(a, locale, s, p, await offersFor(req, a, p, id), locale.t('mfa.passkey_failed')));
+    }
+    return finish(req, reply, a, s, p, '2fa (passkey)');
+  });
+
+  // (sprint 131) adding a passkey as the first factor while signing in (the application requires one)
+  app.post('/a/:alias/login/2fa/passkey/new/options', async (req: Req, reply) => {
+    const r = await start(req, reply);
+    if (!r) return reply.code(404).send('Not found');
+    const { a, session: s, p } = r;
+    if (!p?.enrol || p.codes || req.body?.__csrf !== s.csrf_token) return reply.code(403).send('Sign in again.');
+    const id = await accountId(p.u);
+    if (id === null) return reply.code(403).send('Sign in again.');
+    return reply.header('cache-control', 'no-store').send(await createOptions(req, s, a, id, p.u));
+  });
+
+  app.post('/a/:alias/login/2fa/passkey/new', async (req: Req, reply) => {
+    const r = await start(req, reply);
+    if (!r) return reply.code(404).send('Not found');
+    const { a, locale, session: s, p } = r;
+    const t = locale.t;
+    const challenge = takeChallenge(s, 'create');
+    if (!p?.enrol || p.codes || req.body?.__csrf !== s.csrf_token) return expired(reply, a, locale, s);
+    const id = await accountId(p.u);
+    if (id === null) return expired(reply, a, locale, s);
+    const ip = clientIp(req);
+    const added = challenge ? await registerPasskey(req, a, id, p.u, challenge, t('mfa.passkey_default'), ip, 'sign-in') : 'expired';
+    if (added !== 'ok') {
+      await saveState(s);
+      return reply.code(422).type('text/html').send(stepPage(a, locale, s, p, await offersFor(req, a, p, id), t(added === 'known' ? 'mfa.passkey_known' : 'mfa.passkey_failed')));
+    }
+    p.codes = await newAccountCodes(id);
+    p.added = 'passkey';
+    delete p.secret;
+    keep(s, p);
+    await saveState(s);
+    return reply.type('text/html').send(stepPage(a, locale, s, p, await offersFor(req, a, p, id)));
+  });
+
+  // the recovery codes were shown once after adding the first app or passkey while signing in
   app.post('/a/:alias/login/2fa/done', async (req: Req, reply) => {
     const r = await start(req, reply);
     if (!r) return reply.code(404).send('Not found');
     const { a, locale, session: s, p } = r;
     if (!p?.codes || req.body?.__csrf !== s.csrf_token) return expired(reply, a, locale, s);
-    if (req.body?.saved !== '1') return reply.code(422).type('text/html').send(stepPage(a, locale, s, p));
     const id = await accountId(p.u);
     if (id === null) return expired(reply, a, locale, s);
+    if (req.body?.saved !== '1') return reply.code(422).type('text/html').send(stepPage(a, locale, s, p, await offersFor(req, a, p, id)));
     await confirmAccountCodes(id);
-    return finish(req, reply, a, s, p, '2fa (new app)');
+    return finish(req, reply, a, s, p, `2fa (new ${p.added === 'passkey' ? 'passkey' : 'app'})`);
   });
 
   // ---------------------------------------------------------------- My account → Two-step sign-in
@@ -247,10 +461,10 @@ export async function twoStepRoutes(app: FastifyInstance) {
     }
     return { ctx, id };
   };
-  const done = async (reply: FastifyReply, ctx: PageContext, flash?: string, error?: boolean) => {
+  const done = async (reply: FastifyReply, ctx: PageContext, flash?: string, error?: boolean, anchor = 'two-step') => {
     if (flash) ctx.session.state[error ? '__FLASH_ERROR' : '__FLASH'] = flash;
     await saveState(ctx.session);
-    return reply.redirect(`${ctx.base}/account#two-step`, 303);
+    return reply.redirect(`${ctx.base}/account#${anchor}`, 303);
   };
 
   app.post('/a/:alias/account/2fa/start', async (req: Req, reply) => {
@@ -287,6 +501,28 @@ export async function twoStepRoutes(app: FastifyInstance) {
     return done(reply, ctx, t('mfa.added'));
   });
 
+  // (sprint 131) a passkey on My account: the options for navigator.credentials.create(), then the browser's answer
+  app.post('/a/:alias/account/2fa/passkey/options', async (req: Req, reply) => {
+    const r = await signedIn(req, reply);
+    if (!r) return;
+    await saveState(r.ctx.session);
+    return reply.header('cache-control', 'no-store').send(await createOptions(req, r.ctx.session, r.ctx.app, r.id, r.ctx.user));
+  });
+
+  app.post('/a/:alias/account/2fa/passkey', async (req: Req, reply) => {
+    const r = await signedIn(req, reply);
+    if (!r) return;
+    const { ctx, id } = r;
+    const t = ctx.locale.t;
+    const challenge = takeChallenge(ctx.session, 'create');
+    if (!challenge) return done(reply, ctx, t('mfa.expired'), true);
+    const first = !(await accountHasFactor(id));
+    const added = await registerPasskey(req, ctx.app, id, ctx.user, challenge, String(req.body?.pk_name ?? '') || t('mfa.passkey_default'), ctx.ip, 'My account');
+    if (added !== 'ok') return done(reply, ctx, t(added === 'known' ? 'mfa.passkey_known' : 'mfa.passkey_failed'), true);
+    if (first || !(await accountCodesLeft(id))) ctx.session.state.__CODES_NEW = JSON.stringify(await newAccountCodes(id));
+    return done(reply, ctx, t('mfa.passkey_added'));
+  });
+
   app.post('/a/:alias/account/2fa/codes', async (req: Req, reply) => {
     const r = await signedIn(req, reply);
     if (!r) return;
@@ -305,7 +541,7 @@ export async function twoStepRoutes(app: FastifyInstance) {
     return done(reply, r.ctx);
   });
 
-  // removing an app asks for a code (from any app, or a recovery code): a session left open is not enough
+  // removing an app or a passkey asks for a code (from any app, or a recovery code): a session left open is not enough
   app.post('/a/:alias/account/2fa/:id/delete', async (req: Req, reply) => {
     const r = await signedIn(req, reply);
     if (!r) return;
@@ -317,16 +553,73 @@ export async function twoStepRoutes(app: FastifyInstance) {
     }
     const factors = await accountFactors(id);
     const factorId = Number((req.params as { id?: string }).id);
-    if (!factors.some((f) => f.id === factorId)) return done(reply, ctx);
+    const factor = factors.find((f) => f.id === factorId);
+    if (!factor) return done(reply, ctx);
     if (factors.length === 1 && mfaRequired(ctx.app, ctx.roles)) return done(reply, ctx, t('mfa.keep_one'), true);
     if (!(await checkAccountCode(id, String(req.body?.code ?? '').slice(0, 40)))) {
       await logActivity({ appId: ctx.app.id, username: ctx.user, event: 'login_failed', ip: ctx.ip, detail: '2fa remove' });
       return done(reply, ctx, t('mfa.wrong'), true);
     }
     await removeAccountFactor(id, factorId);
-    await logActivity({ appId: ctx.app.id, username: ctx.user, event: '2fa_removed', ip: ctx.ip, detail: 'authenticator app' });
-    return done(reply, ctx, t('mfa.removed'));
+    await logActivity({ appId: ctx.app.id, username: ctx.user, event: '2fa_removed', ip: ctx.ip, detail: factor.kind === 'passkey' ? 'passkey' : 'authenticator app' });
+    return done(reply, ctx, t(factor.kind === 'passkey' ? 'mfa.passkey_removed' : 'mfa.removed'));
   });
+
+  // ---------------------------------------------------------------- My account → REST API token (sprint 131)
+  // Only when the application lets users create their own (meta.app.api_self_tokens). A user the application
+  // requires a second step of gives one first, unless the session had one in the last 15 minutes. The token is
+  // kept in the session until the page has shown it once.
+  app.post('/a/:alias/account/token', async (req: Req, reply) => {
+    const ctx = await loadContext(req, reply, { pageNo: 'home' });
+    if (!ctx) return;
+    const t = ctx.locale.t;
+    if (req.body?.__csrf !== ctx.session.csrf_token || !ctx.app.api_self_tokens || ctx.user === 'nobody') return reply.redirect(`${ctx.base}/account`, 303);
+    if ((await accountMustUseMfa(ctx.app, ctx.user)) && !secondStepWithin(ctx.session.state, TOKEN_STEP_MINUTES)) {
+      ctx.session.state.__FLASH = t('token.step_first');
+      await saveState(ctx.session);
+      return reply.redirect(`${ctx.base}/login/2fa?next=${encodeURIComponent(`${ctx.base}/account#api-token`)}`, 303);
+    }
+    try {
+      const issued = await issueApiToken(ctx.app.id, ctx.user, Number(req.body?.hours) || 8, { self: true });
+      ctx.session.state.__TOKEN_NEW = JSON.stringify({ token: issued.token, hours: issued.expiresInHours });
+      await logActivity({ appId: ctx.app.id, username: issued.username, event: 'api_token', ip: ctx.ip, detail: `by the user on My account, ${issued.expiresInHours} h` });
+      return done(reply, ctx, undefined, false, 'api-token');
+    } catch (e) {
+      return done(reply, ctx, (e as Error).message, true, 'api-token');
+    }
+  });
+}
+
+/** WebAuthn options for adding a passkey to an account (a one-time challenge kept in the session). */
+async function createOptions(req: FastifyRequest, s: Session, a: App, id: number, username: string) {
+  const rp = relyingParty(req);
+  const challenge = giveChallenge(s, 'create');
+  await saveState(s);
+  return {
+    mode: 'create', challenge, rp: { id: rp.rpId, name: a.name }, algs: ALGORITHMS,
+    // a stable handle that isn't the user name (the authenticator may show it, but it says nothing)
+    user: { id: accountUserHandle(id), name: username, displayName: username },
+    exclude: (await accountPasskeys(id, rp.rpId)).map((k) => k.credential_id),
+  };
+}
+
+/** Check the browser's answer and keep the passkey: 'ok', 'known' (added already) or 'failed'. */
+async function registerPasskey(req: Req, a: App, id: number, username: string, challenge: string, name: string, ip: string, where: string) {
+  const rp = relyingParty(req);
+  let reg;
+  try {
+    reg = verifyRegistration({ clientDataJSON: String(req.body?.clientDataJSON ?? ''), attestationObject: String(req.body?.attestationObject ?? '') }, { challenge, ...rp });
+  } catch (e) {
+    await logActivity({ appId: a.id, username, event: '2fa_refused', ip, detail: `passkey: ${e instanceof WebAuthnError ? e.message : 'unreadable answer'}` });
+    return 'failed' as const;
+  }
+  try {
+    await addAccountPasskey(id, name, { ...reg, rpId: rp.rpId, transports: String(req.body?.transports ?? '').split(',').filter(Boolean) });
+  } catch {
+    return 'known' as const;
+  }
+  await logActivity({ appId: a.id, username, event: '2fa_enrolled', ip, detail: `passkey (${rp.rpId}, ${where})` });
+  return 'ok' as const;
 }
 
 /** The app secret being added on My account (kept in the session for some minutes), or null. */
@@ -339,8 +632,18 @@ function newSecret(s: Session, minutes: number): string | null {
   }
 }
 
+/** Something kept in the session to show once (recovery codes, a token), taken out. */
+function takeOnce<T>(s: Session, key: string): T | null {
+  try {
+    const v = JSON.parse(String(s.state[key] ?? ''));
+    return v ?? null;
+  } catch {
+    return null;
+  }
+}
+
 /** My account → Two-step sign-in (when the application has a second step). */
-export async function twoStepSection(ctx: PageContext): Promise<Raw | ''> {
+export async function twoStepSection(ctx: PageContext, rpId = ''): Promise<Raw | ''> {
   if (!mfaOn(ctx.app)) return '';
   const id = await accountId(ctx.user);
   if (id === null) return '';
@@ -348,13 +651,7 @@ export async function twoStepSection(ctx: PageContext): Promise<Raw | ''> {
   const [factors, left] = await Promise.all([accountFactors(id), accountCodesLeft(id)]);
   const required = mfaRequired(ctx.app, ctx.roles);
   const pending = newSecret(ctx.session, 10);
-  let shown: string[] | null = null;
-  try {
-    const c = JSON.parse(String(ctx.session.state.__CODES_NEW ?? ''));
-    shown = Array.isArray(c) ? c : null;
-  } catch {
-    shown = null;
-  }
+  const shown = takeOnce<string[]>(ctx.session, '__CODES_NEW');
   const error = typeof ctx.session.state.__FLASH_ERROR === 'string' ? ctx.session.state.__FLASH_ERROR : '';
   delete ctx.session.state.__FLASH_ERROR;
   const base = `${ctx.base}/account/2fa`;
@@ -362,15 +659,16 @@ export async function twoStepSection(ctx: PageContext): Promise<Raw | ''> {
   const when = (v: string | null) => (v ? String(v).slice(0, 10) : '');
   return html`<section class="region region-standard col-6" id="two-step"><header class="region-header"><h2>${t('mfa.step_title')}</h2></header><div class="region-body">
     ${error ? html`<div class="alert alert-error" role="alert">${error}</div>` : ''}
-    <p class="muted u-mt0">${factors.length ? t('mfa.on') : required ? t('mfa.required_you') : t('mfa.off')}</p>
-    ${shown
+    <p class="muted u-mt0">${factors.length ? t('mfa.on_any') : required ? t('mfa.required_you') : t('mfa.off')}</p>
+    ${Array.isArray(shown)
       ? html`<h3>${t('mfa.codes_title')}</h3><p>${t('mfa.codes_once')}</p>${codesList(shown)}
         <form method="post" action="${base}/codes/confirm">${csrf}
           <label class="check"><input type="checkbox" name="saved" value="1" required> ${t('mfa.codes_saved')}</label>
           <div class="buttons"><button class="btn btn-hot">${t('mfa.continue')}</button></div></form>`
       : ''}
     ${factors.length
-      ? html`<ul class="mfa-factors">${factors.map((f) => html`<li><strong>${f.name}</strong> <span class="muted">${when(f.created_at)}</span>
+      ? html`<ul class="mfa-factors">${factors.map((f) => html`<li><strong>${f.name}</strong> <span class="muted">${f.kind === 'passkey' ? t('mfa.kind_passkey') : t('mfa.kind_app')} · ${when(f.created_at)}</span>
+          ${f.kind === 'passkey' && rpId && f.rp_id !== rpId ? html` <span class="badge">${f.rp_id}</span>` : ''}
           <details><summary class="link-button">${t('mfa.remove')}</summary>
             <form method="post" action="${base}/${f.id}/delete">${csrf}
               <div class="field"><label class="label" for="rm_${f.id}">${t('mfa.remove_code')}</label><input id="rm_${f.id}" name="code" required autocomplete="one-time-code" maxlength="20"></div>
@@ -390,6 +688,35 @@ export async function twoStepSection(ctx: PageContext): Promise<Raw | ''> {
       : secretKeyConfigured()
         ? html`<form method="post" action="${base}/start">${csrf}<div class="buttons"><button class="btn${factors.length ? '' : ' btn-hot'}">${t('mfa.add_app')}</button></div></form>`
         : html`<p class="alert alert-info" role="status">${t('mfa.no_key')}</p>`}
+    ${pending
+      ? ''
+      : html`<h3>${t('mfa.kind_passkey')}</h3><p class="muted u-mt0">${t('mfa.passkey_intro')}</p>
+        ${rpId && isIP(rpId)
+          ? html`<p class="alert alert-info" role="status">${t('mfa.passkey_needs_host')}</p>`
+          : html`<form method="post" action="${base}/passkey" class="mfa-passkey">${csrf}${passkeyFields(ATTESTATION)}
+              <div class="field"><label class="label" for="pk_name">${t('mfa.app_name')}</label><input id="pk_name" name="pk_name" value="${t('mfa.passkey_default')}" required maxlength="60"></div>
+              <div class="buttons"><button class="btn" hidden data-passkey="${base}/passkey/options" data-passkey-error="${t('mfa.passkey_failed')}">${t('mfa.add_passkey')}</button></div>
+              <p class="small" role="status" data-passkey-status></p>
+              <noscript><p class="muted small">${t('mfa.passkey_needs_js')}</p></noscript></form>`}`}
   </div></section>`;
 }
 
+/** (sprint 131) My account → REST API token, when the application lets users create their own. */
+export async function tokenSection(ctx: PageContext): Promise<Raw | ''> {
+  if (!ctx.app.api_self_tokens || (await accountId(ctx.user)) === null) return '';
+  const t = ctx.locale.t;
+  const issued = takeOnce<{ token: string; hours: number }>(ctx.session, '__TOKEN_NEW');
+  delete ctx.session.state.__TOKEN_NEW;
+  const needsStep = await accountMustUseMfa(ctx.app, ctx.user);
+  const csrf = html`<input type="hidden" name="__csrf" value="${ctx.session.csrf_token}">`;
+  return html`<section class="region region-standard col-6" id="api-token"><header class="region-header"><h2>${t('token.title')}</h2></header><div class="region-body">
+    <p class="muted u-mt0">${t('token.intro')}${needsStep ? html` ${t('token.needs_step')}` : ''}</p>
+    ${issued?.token
+      ? html`<div class="field"><label class="label" for="api_token">${t('token.shown_once', { hours: issued.hours })}</label>
+          <textarea id="api_token" rows="4" readonly spellcheck="false">${issued.token}</textarea></div>`
+      : ''}
+    <form method="post" action="${ctx.base}/account/token">${csrf}
+      <div class="field"><label class="label" for="token_hours">${t('token.hours')}</label><input id="token_hours" name="hours" type="number" min="1" max="${MAX_TOKEN_HOURS}" value="8" required></div>
+      <div class="buttons"><button class="btn">${t('token.create')}</button></div></form>
+  </div></section>`;
+}