pgkiln 0.64.0 → 0.65.0

package/db/migrations/133_app_user_passkeys_stepup.sql

@@ -0,0 +1,54 @@
+-- ---------------------------------------------------------------------
+-- 133: passkeys, e-mail codes and step-up for application users (sprint
+-- 131, SEC-3 part 2; beyond APEX).
+--
+-- meta.account_factor gets a second kind, 'passkey' (WebAuthn), with the
+-- same columns as a developer's (129): the credential id (base64url, unique),
+-- its public key as a JWK, the COSE algorithm, the signature counter, the
+-- relying party id (host name) it was made for and the transports. A passkey
+-- keeps working without the instance key (it is a public key).
+--
+-- meta.app.mfa_email: at the second step, a user may ask for a one-time code
+-- by e-mail (through the application's mail service) instead of opening their
+-- authenticator app. Only users who have an authenticator app or a passkey
+-- are offered it: an e-mail code is never someone's only factor (SEC-6).
+--
+-- meta.authz_scheme.mfa_minutes (step-up): the scheme passes only when the
+-- session's last second step is at most this many minutes old; a page that
+-- needs it asks for a code (or a passkey) again before it opens. null: no
+-- step-up (the default). Exported with the application.
+-- ---------------------------------------------------------------------
+alter table meta.account_factor drop constraint account_factor_kind_check;
+alter table meta.account_factor
+  alter column secret_enc drop not null,
+  add column credential_id text unique,
+  add column public_key   jsonb,
+  add column alg          int,
+  add column sign_count   bigint not null default 0,
+  add column rp_id        text,
+  add column transports   text[] not null default '{}',
+  add constraint account_factor_kind_check check (kind in ('totp', 'passkey')),
+  add constraint account_factor_kind_fields check (
+    case kind
+      when 'totp' then secret_enc is not null
+      when 'passkey' then credential_id is not null and public_key is not null and alg is not null and rp_id is not null
+    end);
+comment on table meta.account_factor is
+  'An application account''s second factors: authenticator apps (TOTP, 132; the secret encrypted with the instance key) and passkeys (WebAuthn, 133; a public key).';
+
+alter table meta.app add column mfa_email boolean not null default false;
+comment on column meta.app.mfa_email is
+  'Two-step sign-in (133): users with an authenticator app or a passkey may get a one-time code by e-mail instead.';
+
+alter table meta.authz_scheme
+  add column mfa_minutes int check (mfa_minutes between 1 and 1440);
+comment on column meta.authz_scheme.mfa_minutes is
+  'Step-up (133): the scheme passes only when the session''s last second step is at most this many minutes old (null: no step-up).';
+
+-- meta.app.api_self_tokens: signed-in users create their own REST API token
+-- on My account. A user the application requires a second step of gets one
+-- only after a second step at most 15 minutes old; the builder's "Issue a
+-- token" refuses such accounts (SEC-3: no token around two-step sign-in).
+alter table meta.app add column api_self_tokens boolean not null default false;
+comment on column meta.app.api_self_tokens is
+  'Users create their own REST API token on My account (133); after a recent second step when the app requires one of them.';

package/docs/apex-feature-parity.md

@@ -138,7 +138,7 @@ the 26.2 comparison.)
 | APEX accounts | ✅ | Instance-wide user directory, bcrypt, session rotation, idle and absolute timeouts |
 | Application Access Control (roles per app, any-user switch) | ✅ | Access control per application |
 | Social sign-in / OpenID Connect | ✅ | Any OIDC provider (Entra ID, Google, Okta, Keycloak, …): PKCE, group → role mapping, account linking, automatic accounts |
-| Multi-factor authentication | ✅ | As in APEX: through the identity provider (OpenID Connect, SAML). Beyond APEX (sprints 126–128): the builder itself has two-factor sign-in with passkeys (WebAuthn, also on their own without a password), authenticator apps (TOTP) and recovery codes, trusted browsers, an instance and per-workspace policy with a grace period and lockout recovery ([chapter 3](guide/03-builder.md#two-factor-sign-in)). Sprint 130: application users too, per application (off, optional, required, required for roles) with authenticator apps and recovery codes, added while signing in or on My account, reset from Users ([chapter 8](guide/08-security.md#two-factor-sign-in)) |
+| Multi-factor authentication | ✅ | As in APEX: through the identity provider (OpenID Connect, SAML). Beyond APEX (sprints 126–128): the builder itself has two-factor sign-in with passkeys (WebAuthn, also on their own without a password), authenticator apps (TOTP) and recovery codes, trusted browsers, an instance and per-workspace policy with a grace period and lockout recovery ([chapter 3](guide/03-builder.md#two-factor-sign-in)). Sprint 130: application users too, per application (off, optional, required, required for roles) with authenticator apps and recovery codes, added while signing in or on My account, reset from Users; sprint 131: passkeys, e-mail codes as a fallback, step-up per authorization scheme and REST API tokens only after a second step ([chapter 8](guide/08-security.md#two-factor-sign-in)) |
 | Change own password | ✅ | A built-in *My account* page (APEX offers the API `CHANGE_CURRENT_USER_PW`) |
 | Password expiry, change on first use, admin reset, complexity | ✅ | Lifetime in days, expire/unexpire, admin reset, length and letters+digits rules, unlock |
 | Lockout after failed sign-ins | ✅ | Per user and per IP, time-based (APEX: until an administrator unlocks) |
@@ -300,8 +300,10 @@ Small but real differences, for teams comparing the two:
   passkey alone), authenticator apps (TOTP), recovery codes, a policy for administrators, all developers or a
   workspace's developers with a grace period, and lockout recovery on the
   command line ([chapter 3](guide/03-builder.md#two-factor-sign-in)). APEX relies on the identity provider.
-- (sprint 130) **Two-factor sign-in for application users**: per application and per role, with authenticator apps
-  and recovery codes, added while signing in when required ([chapter 8](guide/08-security.md#two-factor-sign-in)).
+- (sprints 130–131) **Two-factor sign-in for application users**: per application and per role, with authenticator
+  apps, passkeys and recovery codes, added while signing in when required, a code by e-mail as a fallback, step-up
+  before sensitive pages (an authorization scheme's *Second step within*) and REST API tokens only after a second step
+  ([chapter 8](guide/08-security.md#two-factor-sign-in)).
   APEX's application authentication schemes have no second factor.
 - One RLS policy set protects both the web UI and the REST API.
 - An import can be checked before it commits (`pgkiln import --check`): SQL that names a missing

package/docs/guide/08-security.md

@@ -419,8 +419,8 @@ sign-on policy asks for one, or a hand-written TOTP check in a custom authentica
 | Setting | Who gives a code after the password |
 |---|---|
 | **Off** (the default) | Nobody |
-| **Optional** | Users who added an authenticator app on *My account* |
-| **Required** | Everybody. A user without an app adds one while signing in: a QR code, the app's first code, then ten recovery codes shown once |
+| **Optional** | Users who added an authenticator app or a passkey on *My account* |
+| **Required** | Everybody. A user without one adds an app (a QR code, then its first code) or a passkey while signing in, then sees ten recovery codes once |
 | **Required for some roles** | Users with one of the roles in *Required for roles* (for example `admin, manager`); others as with *Optional* |
 
 How it works:
@@ -447,8 +447,41 @@ How it works:
   the step. Recovery codes are stored as SHA-256 hashes.
 - The **Advisor** warns when users with the role `admin` sign in with only a password.
 
-Passkeys, e-mail codes, asking again before a sensitive page (step-up) and tokens for REST and MCP that need a
-two-factor sign-in come in a later release.
+#### Passkeys
+
+Next to authenticator apps, users add **passkeys** (WebAuthn: a fingerprint, face or screen lock on the device, or a
+security key) on *My account*, or while signing in when the application requires a second step and they have none
+yet (the page offers an app and a passkey). At the second step **Use a passkey** replaces the code. pgkiln checks the
+answer itself (challenge, origin, relying party, signature, counter), as for [developers](03-builder.md#two-factor-sign-in).
+A passkey works only at the host name it was made for (`PUBLIC_URL`'s host, or `PGKILN_RP_ID`), not at an IP address,
+and needs JavaScript; codes keep working without either. Passkeys are public keys: they don't need the instance key.
+The first factor a user adds, app or passkey, brings ten recovery codes.
+
+#### A code by e-mail
+
+**Offer a code by e-mail** (same settings) adds *E-mail me a code instead* to the second step, for users who have an
+authenticator app or a passkey and an e-mail address in the user directory. The code (six digits, valid 10 minutes,
+once) goes through the application's mail service; at most three per sign-in and five per account per hour. It is
+**never someone's only factor**: it is not offered while a user adds their first one, so a lost mailbox or a mail
+outage never locks anyone out and a stolen mailbox alone never signs anyone in.
+
+#### Asking again before a sensitive page (step-up)
+
+An authorization scheme's **Second step within (minutes)** makes it pass only when the session's last second step
+(code, passkey, e-mail code or recovery code) is at most that old. A page behind such a scheme sends a user who passes
+the scheme otherwise to *Confirm it's you* (the second-step page) and back to the page afterwards; regions, buttons and
+processes behind it stay hidden or skipped until then. A user without a factor is told to add one on *My account*.
+Typical: `SALARY_EDIT` (role `hr_manager`, second step within 15 minutes) on the page that changes salaries. A
+*Keep me signed in*, shared or single sign-on session has no recent second step of pgkiln's own, so it is asked too.
+A form posted after the time ran out is not processed: the user confirms, comes back to the page and submits again.
+
+#### REST API tokens
+
+A developer's **REST API → Issue a token** acts as an account without its sign-in, so it is refused for accounts the
+application requires a second step of. Turn on **REST API → Users create their own tokens** and those users (and
+everyone else) create a token on *My account → REST API token* instead; one who must use two-factor sign-in gives a
+second step first when their last one is older than 15 minutes. The token is shown once. MCP has no tokens for
+application users, so nothing to cover there.
 
 ### What sign-in protects against
 
@@ -458,8 +491,8 @@ two-factor sign-in come in a later release.
   time.
 - **Session fixation**: the session token is replaced at sign-in.
 - **Stale sessions**: 60 minutes idle or 8 hours total (configurable).
-- **Stolen passwords**: [two-factor sign-in](#two-factor-sign-in) asks for a code from an authenticator app, for every
-  user or for some roles; with an identity provider ([OpenID Connect](#single-sign-on-openid-connect),
+- **Stolen passwords**: [two-factor sign-in](#two-factor-sign-in) asks for a code from an authenticator app or a
+  passkey, for every user or for some roles, and again before sensitive pages ([step-up](#asking-again-before-a-sensitive-page-step-up)); with an identity provider ([OpenID Connect](#single-sign-on-openid-connect),
   [SAML](#single-sign-on-saml-20)) the provider asks for its own. Developers have
   [two-factor sign-in](03-builder.md#two-factor-sign-in) for the builder too.
 
@@ -480,6 +513,8 @@ Plus the built-in `MUST_NOT_BE_PUBLIC_USER` (signed in). Reference a scheme by n
 `authz` property of a page, region, item, button, process, dynamic action or navigation entry;
 prefix it with `!` to negate (`!ADMIN`). Unknown schemes **fail closed** (deny). Each scheme is
 evaluated at most once per request, and its `error_message` is shown when a page is refused.
+With **Second step within (minutes)** it also needs a recent second factor
+([step-up](#asking-again-before-a-sensitive-page-step-up)).
 
 What happens when a scheme fails:
 

package/docs/guide/12-development.md

@@ -63,9 +63,12 @@ src/
   customauth.ts            custom authentication: the app's function or PL/pgSQL body (a pg_temp function) and post-authentication code, as the app's role
   remember.ts              "Keep me signed in": rotating persistent sign-in tokens
   mfa.ts                   second factors: TOTP, recovery codes, a FactorStore per kind of user (developers, accounts);
-                           the developers' policy, passkeys, trusted browsers (webauthn.ts: WebAuthn checks)
+                           the developers' policy, passkeys, trusted browsers (webauthn.ts: WebAuthn checks and the
+                           session's one-time challenge)
   account-mfa.ts           (sprint 130) two-factor sign-in for application accounts: the application's rule (off, optional,
-                           required, roles), secondStep, carriesSecondStep (remembered/shared sign-ins), resets
+                           required, roles), secondStep, carriesSecondStep (remembered/shared sign-ins), resets;
+                           (sprint 131) account passkeys, e-mail codes (emailCodeTarget, queueEmailCode), the session's
+                           last second step (__MFA_AT, secondStepWithin) for step-up, accountMustUseMfa (API tokens)
   workflow.ts              workflows: step checks, the runner with parallel branches (NOTIFY + polling), invoke_api steps
                            (the call between two transactions, with a lease), Advisor references, the diagram;
                            (sprint 114) send_mail and draft steps, switch cases on task outcomes, the diagram as a standalone SVG
@@ -176,9 +179,12 @@ src/
     signin.ts              the sign-in form (built-in page and the login region of an application's own login page), safeNext, passwordResetAvailable
     password-reset.ts      Forgot password: request (same answer either way), the link (token into the session), the new password
     two-step.ts            (sprint 130) the second step of signing in (/login/2fa: a code, or the first app and its recovery
-                           codes), passwordSignIn, and My account → Two-factor sign-in
+                           codes), passwordSignIn, and My account → Two-factor sign-in; (sprint 131) passkeys at the
+                           second step and as the first factor, e-mail codes, step-up (?next=, a signed-in user), My
+                           account → REST API token (tokenSection)
     context.ts             PageContext, dbg()/timed() debug helpers, bind values, substitutions, public error messages, writeOut (streamed responses with back pressure)
-    authz.ts               authorization schemes, conditions, visibility (menu requests count as buttons)
+    authz.ts               authorization schemes, conditions, visibility (menu requests count as buttons); (sprint 131)
+                           step-up (mfa_minutes; StepUp sends the page's user to /login/2fa?next=)
     engine.ts              form fetch, validations, processes (conditions, execution chains, queueing background chains; web requests queued by an sql process are made right after it), application processes
     processes.ts           download (file or zip from a query, safe headers), workflow processes, configuration checks of chains
     logic.ts               computations (the page's and (102) the application's), branches (page, URL, function returning a URL, another application) and their conditions

package/docs/guide/13-rest-api.md

@@ -362,6 +362,10 @@ curl https://api.example.com/employees -H "Authorization: Bearer eyJ…"
 Under **REST API → Issue a token**, pick an account and a lifetime (1 hour to 30 days). The token
 is shown once and not stored. Issuing is logged in the activity log (`api_token`).
 
+An account the application requires two-factor sign-in of gets no token here: with **Users create their
+own tokens** on, it creates one on *My account → REST API token* after a recent second step
+([chapter 8](08-security.md#rest-api-tokens)).
+
 Such a token contains `role`, `app` and `app_user`, but **no roles**. `meta.has_role()` reads the
 account's roles in the application at every request, and `meta.api_check()` rejects the token as
 soon as the account is deactivated or loses access. Changing `API_JWT_SECRET` (in pgkiln and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgkiln",
-  "version": "0.64.0",
+  "version": "0.65.0",
   "description": "Open source low-code, SQL-driven application builder for PostgreSQL, inspired by Oracle APEX",
   "keywords": [
     "postgresql",

package/public/app.js

@@ -4299,3 +4299,66 @@ document.addEventListener('change', (e) => {
     }
   });
 })();
+
+// (sprint 127, moved here from builder.js in sprint 131) Passkeys, for developers (the builder loads app.js too) and
+// application users: a [data-passkey] button asks the server (its URL) for WebAuthn options, calls
+// navigator.credentials.create() (Security, My account, adding one while signing in) or .get() (the second step, a
+// passkey alone on the builder's sign-in page) and posts the answer in its own form, to data-passkey-submit when set.
+// Without WebAuthn or JavaScript the buttons stay hidden; codes keep working.
+(() => {
+  'use strict';
+  if (!window.PublicKeyCredential || !navigator.credentials) return;
+  const b64 = (buf) => btoa(String.fromCharCode(...new Uint8Array(buf))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+  const bytes = (s) => Uint8Array.from(atob(s.replace(/-/g, '+').replace(/_/g, '/') + '==='.slice((s.length + 3) % 4)), (c) => c.charCodeAt(0));
+  for (const btn of document.querySelectorAll('[data-passkey]')) {
+    const form = btn.closest('form');
+    if (!form) continue;
+    btn.hidden = false;
+    btn.addEventListener('click', async (e) => {
+      e.preventDefault();
+      const status = form.querySelector('[data-passkey-status]');
+      const set = (name, value) => {
+        const field = form.querySelector(`[name="${name}"]`);
+        if (field) field.value = value;
+      };
+      btn.disabled = true;
+      if (status) status.textContent = '';
+      try {
+        const res = await fetch(btn.dataset.passkey, {
+          method: 'POST', credentials: 'same-origin', headers: { accept: 'application/json' },
+          body: new URLSearchParams({ __csrf: form.querySelector('[name="__csrf"]').value }),
+        });
+        if (!res.ok) throw new Error(String(res.status));
+        const o = await res.json();
+        if (o.mode === 'create') {
+          const c = await navigator.credentials.create({ publicKey: {
+            challenge: bytes(o.challenge), rp: o.rp,
+            user: { id: bytes(o.user.id), name: o.user.name, displayName: o.user.displayName },
+            pubKeyCredParams: o.algs.map((alg) => ({ type: 'public-key', alg })),
+            excludeCredentials: o.exclude.map((id) => ({ type: 'public-key', id: bytes(id) })),
+            authenticatorSelection: { residentKey: 'preferred', userVerification: 'preferred' },
+            attestation: 'none', timeout: 120000,
+          } });
+          set('clientDataJSON', b64(c.response.clientDataJSON));
+          set('attestationObject', b64(c.response.attestationObject));
+          set('transports', (c.response.getTransports ? c.response.getTransports() : []).join(','));
+        } else {
+          const c = await navigator.credentials.get({ publicKey: {
+            challenge: bytes(o.challenge), rpId: o.rpId, userVerification: o.uv || 'preferred', timeout: 120000,
+            allowCredentials: o.allow.map((a) => ({ type: 'public-key', id: bytes(a.id), transports: a.transports })),
+          } });
+          set('credentialId', b64(c.rawId));
+          set('clientDataJSON', b64(c.response.clientDataJSON));
+          set('authenticatorData', b64(c.response.authenticatorData));
+          set('signature', b64(c.response.signature));
+          if (c.response.userHandle) set('userHandle', b64(c.response.userHandle));
+        }
+        if (btn.dataset.passkeySubmit) form.action = btn.dataset.passkeySubmit;
+        form.submit();
+      } catch (err) {
+        btn.disabled = false;
+        if (status) status.textContent = btn.dataset.passkeyError || String(err);
+      }
+    });
+  }
+})();

package/public/builder.js

@@ -1334,65 +1334,4 @@ document.querySelectorAll('input[data-filter-tree]').forEach((el) => {
   }
 })();
 
-// (sprint 127) Passkeys: a [data-passkey] button asks the server (its URL) for WebAuthn options, calls
-// navigator.credentials.create() (Security page) or .get() (the second sign-in step) and posts the answer in
-// its own form, to data-passkey-submit when set, so the server answers with a redirect as for any form.
-// (sprint 128) On the sign-in page the list of allowed passkeys is empty: the browser offers the ones it holds.
-// Without WebAuthn or JavaScript the buttons stay hidden; codes keep working.
-(() => {
-  'use strict';
-  if (!window.PublicKeyCredential || !navigator.credentials) return;
-  const b64 = (buf) => btoa(String.fromCharCode(...new Uint8Array(buf))).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
-  const bytes = (s) => Uint8Array.from(atob(s.replace(/-/g, '+').replace(/_/g, '/') + '==='.slice((s.length + 3) % 4)), (c) => c.charCodeAt(0));
-  for (const btn of document.querySelectorAll('[data-passkey]')) {
-    const form = btn.closest('form');
-    if (!form) continue;
-    btn.hidden = false;
-    btn.addEventListener('click', async (e) => {
-      e.preventDefault();
-      const status = form.querySelector('[data-passkey-status]');
-      const set = (name, value) => {
-        const field = form.querySelector(`[name="${name}"]`);
-        if (field) field.value = value;
-      };
-      btn.disabled = true;
-      if (status) status.textContent = '';
-      try {
-        const res = await fetch(btn.dataset.passkey, {
-          method: 'POST', credentials: 'same-origin', headers: { accept: 'application/json' },
-          body: new URLSearchParams({ __csrf: form.querySelector('[name="__csrf"]').value }),
-        });
-        if (!res.ok) throw new Error(String(res.status));
-        const o = await res.json();
-        if (o.mode === 'create') {
-          const c = await navigator.credentials.create({ publicKey: {
-            challenge: bytes(o.challenge), rp: o.rp,
-            user: { id: bytes(o.user.id), name: o.user.name, displayName: o.user.displayName },
-            pubKeyCredParams: o.algs.map((alg) => ({ type: 'public-key', alg })),
-            excludeCredentials: o.exclude.map((id) => ({ type: 'public-key', id: bytes(id) })),
-            authenticatorSelection: { residentKey: 'preferred', userVerification: 'preferred' },
-            attestation: 'none', timeout: 120000,
-          } });
-          set('clientDataJSON', b64(c.response.clientDataJSON));
-          set('attestationObject', b64(c.response.attestationObject));
-          set('transports', (c.response.getTransports ? c.response.getTransports() : []).join(','));
-        } else {
-          const c = await navigator.credentials.get({ publicKey: {
-            challenge: bytes(o.challenge), rpId: o.rpId, userVerification: o.uv || 'preferred', timeout: 120000,
-            allowCredentials: o.allow.map((a) => ({ type: 'public-key', id: bytes(a.id), transports: a.transports })),
-          } });
-          set('credentialId', b64(c.rawId));
-          set('clientDataJSON', b64(c.response.clientDataJSON));
-          set('authenticatorData', b64(c.response.authenticatorData));
-          set('signature', b64(c.response.signature));
-          if (c.response.userHandle) set('userHandle', b64(c.response.userHandle));
-        }
-        if (btn.dataset.passkeySubmit) form.action = btn.dataset.passkeySubmit;
-        form.submit();
-      } catch (err) {
-        btn.disabled = false;
-        if (status) status.textContent = btn.dataset.passkeyError || String(err);
-      }
-    });
-  }
-})();
+// (sprint 127) Passkeys: the [data-passkey] buttons are handled by app.js (sprint 131), which every builder page loads too.

package/src/account-mfa.ts

@@ -1,5 +1,9 @@
+import { createHash, randomInt, timingSafeEqual } from 'node:crypto';
 import { owner } from './db.ts';
-import { ACCOUNTS, storeAddTotp, storeCheck, storeCodesLeft, storeConfirmCodes, storeHasFactor, storeNewCodes } from './mfa.ts';
+import {
+  ACCOUNTS, storeAddPasskey, storeAddTotp, storeCheck, storeCodesLeft, storeConfirmCodes, storeHasFactor, storeNewCodes, storePasskeys,
+  storeUsePasskey,
+} from './mfa.ts';
 
 // (sprint 130, SEC-3) Two-step sign-in for application users, beyond APEX (whose application authentication has no
 // second factor). An account's authenticator apps and recovery codes (meta.account_factor, account_recovery_code,
@@ -7,6 +11,9 @@ import { ACCOUNTS, storeAddTotp, storeCheck, storeCodesLeft, storeConfirmCodes,
 // off, optional (users who added an app give a code), required, or required for some roles. The second step follows
 // the user directory's passwords and LDAP directories; an identity provider decides on its own second factor (SEC-4).
 // A remembered or shared sign-in carries its method: only one that ends in "+2fa" stands in for the second step.
+// (sprint 131, SEC-3 part 2) Passkeys next to authenticator apps; a code by e-mail for users who have one of those
+// (never someone's only factor, SEC-6); step-up: an authorization scheme with mfa_minutes passes only when the session's
+// last second step (session state __MFA_AT) is that recent; and REST API tokens a user creates on My account.
 
 export type AppMfa = 'off' | 'optional' | 'required' | 'roles';
 export const APP_MFA: AppMfa[] = ['off', 'optional', 'required', 'roles'];
@@ -55,10 +62,11 @@ export async function carriesSecondStep(a: MfaApp, username: string, roles: stri
   return (await secondStep(a, username, roles)) === null;
 }
 
-export interface AccountFactor { id: number; name: string; created_at: string; last_used_at: string | null }
+export interface AccountFactor { id: number; kind: 'totp' | 'passkey'; name: string; created_at: string; last_used_at: string | null; rp_id: string | null }
 
 export async function accountFactors(id: number): Promise<AccountFactor[]> {
-  return (await owner.query<AccountFactor>('select id, name, created_at, last_used_at from meta.account_factor where account_id = $1 order by id', [id])).rows;
+  return (await owner.query<AccountFactor>(
+    'select id, kind, name, created_at, last_used_at, rp_id from meta.account_factor where account_id = $1 order by kind desc, id', [id])).rows;
 }
 
 export const accountHasFactor = (id: number) => storeHasFactor(ACCOUNTS, id);
@@ -67,6 +75,89 @@ export const addAccountTotp = (id: number, name: string, secret: string, step: n
 export const newAccountCodes = (id: number) => storeNewCodes(ACCOUNTS, id);
 export const confirmAccountCodes = (id: number) => storeConfirmCodes(ACCOUNTS, id);
 export const checkAccountCode = (id: number, code: string) => storeCheck(ACCOUNTS, id, code);
+export const addAccountPasskey = (id: number, name: string, p: Parameters<typeof storeAddPasskey>[3]) => storeAddPasskey(ACCOUNTS, id, name, p);
+export const accountPasskeys = (id: number, rpId: string) => storePasskeys(ACCOUNTS, id, rpId);
+export const useAccountPasskey = (factorId: number, oldCount: string, newCount: number) => storeUsePasskey(ACCOUNTS, factorId, oldCount, newCount);
+/** The user handle an account's passkeys carry: stable, and not the user name. */
+export const accountUserHandle = (id: number) => createHash('sha256').update(`pgkiln-account:${id}`).digest().subarray(0, 16).toString('base64url');
+
+// ---------------------------------------------------------------- step-up (sprint 131)
+
+/** Session state: when (ms) the session last had a second step (signing in with one, or asked again). */
+export const MFA_AT = '__MFA_AT';
+export const markSecondStep = (state: Record<string, unknown>) => { state[MFA_AT] = Date.now(); };
+/** Whether the session had a second step at most `minutes` ago. */
+export function secondStepWithin(state: Record<string, unknown>, minutes: number): boolean {
+  const at = Number(state[MFA_AT]);
+  return Number.isFinite(at) && at > 0 && Date.now() - at <= minutes * 60_000;
+}
+
+// ---------------------------------------------------------------- e-mail codes (sprint 131)
+
+export const EMAIL_CODE_MINUTES = 10;
+/** Codes one account may get by e-mail per hour (every application together). */
+export const EMAIL_CODES_PER_HOUR = 5;
+export const newEmailCode = () => String(randomInt(0, 1_000_000)).padStart(6, '0');
+export const emailCodeHash = (code: string) => createHash('sha256').update(`pgkiln-mail-code:${code}`).digest('hex');
+export function emailCodeMatches(hash: string | undefined, code: string): boolean {
+  const digits = code.replace(/\s/g, '');
+  if (!hash || !/^\d{6}$/.test(digits)) return false;
+  return timingSafeEqual(Buffer.from(emailCodeHash(digits)), Buffer.from(hash));
+}
+
+/**
+ * Where an e-mail code would go for this account in this application: the account's address and the application's
+ * mail service, or null (not offered). Only for an application that allows it and an account with another factor.
+ */
+export async function emailCodeTarget(a: { id: number; mfa_email?: boolean | null }, accountIdValue: number): Promise<{ to: string; from: string } | null> {
+  if (!a.mfa_email || !(await storeHasFactor(ACCOUNTS, accountIdValue))) return null;
+  const r = await owner.one<{ email: string | null; from_address: string | null; ok: boolean }>(
+    `select ac.email, ams.from_address, coalesce(s.enabled and meta.mail_sender_allowed(s.senders, ams.from_address), false) as ok
+       from meta.account ac
+       left join meta.app_mail_service ams on ams.app_id = $2
+       left join meta.mail_service s on s.id = ams.service_id
+      where ac.id = $1 and ac.active`, [accountIdValue, a.id]);
+  const to = r?.email?.trim();
+  return r?.ok && to && r.from_address?.trim() ? { to, from: r.from_address.trim() } : null;
+}
+
+/**
+ * Queue a sign-in code mail (the application's mail service, its daily limit). Returns false when the account had
+ * too many this hour or the limit is reached; the caller says nothing more specific (no hint about the address).
+ */
+export async function queueEmailCode(a: { id: number }, username: string, target: { to: string; from: string }, subject: string, text: string): Promise<boolean> {
+  return owner.tx(async (c) => {
+    const recent = (await c.query<{ n: number }>(
+      `select count(*)::int as n from meta.mail_queue where template = 'SIGNIN_CODE' and lower(username) = lower($1) and created_at > now() - interval '1 hour'`,
+      [username])).rows[0].n;
+    if (recent >= EMAIL_CODES_PER_HOUR) return false;
+    const over = (await c.query<{ over: boolean }>(
+      `select ams.max_per_day is not null and (select count(*) from meta.mail_queue q where q.app_id = $1
+                 and q.created_at >= date_trunc('day', now() at time zone 'UTC') at time zone 'UTC' and q.status <> 'cancelled') >= ams.max_per_day as over
+         from meta.app_mail_service ams where ams.app_id = $1`, [a.id])).rows[0]?.over;
+    if (over) return false;
+    const id = (await c.query<{ id: string }>(
+      `insert into meta.mail_queue (app_id, username, from_address, to_addresses, subject, body_text, template)
+       values ($1, $2, $3, array[$4], left($5, 998), $6, 'SIGNIN_CODE') returning id`,
+      [a.id, username, target.from, target.to, subject.replace(/[\r\n]+/g, ' '), text])).rows[0].id;
+    await c.query(`select pg_notify('pgkiln_mail', $1)`, [String(id)]);
+    return true;
+  });
+}
+
+// ---------------------------------------------------------------- REST API tokens (sprint 131)
+
+/** Minutes a second step may be old for a user to create their own API token (when the app requires one of them). */
+export const TOKEN_STEP_MINUTES = 15;
+
+/** Whether the application requires a second step of this account (by its roles in the application). */
+export async function accountMustUseMfa(a: MfaApp & { id: number }, username: string): Promise<boolean> {
+  if (!mfaOn(a)) return false;
+  const roles = (await owner.query<{ roles: string[] }>(
+    `select aa.roles from meta.app_access aa join meta.account ac on ac.id = aa.account_id where aa.app_id = $1 and lower(ac.username) = lower($2)`,
+    [a.id, username])).rows[0]?.roles ?? [];
+  return mfaRequired(a, roles);
+}
 
 /** Remove one of the account's authenticator apps (and the recovery codes with the last one). */
 export async function removeAccountFactor(id: number, factorId: number): Promise<boolean> {

package/src/api.ts

@@ -1,4 +1,5 @@
 import { SignJWT } from 'jose';
+import { accountMustUseMfa } from './account-mfa.ts';
 import { owner } from './db.ts';
 
 // Tokens for the REST API that PostgREST serves next to pgkiln. They're
@@ -47,9 +48,11 @@ export async function apiStatus(): Promise<{ ok: boolean; detail: string }> {
  * active and have access to the app. Roles are not put in the token:
  * meta.has_role() reads them from meta.app_access at each request, and
  * meta.api_check() rejects the token once the account loses access.
+ * (sprint 131) `self`: the user asked for it on My account (two-step.ts checked the second step); `internal`: the
+ * token never leaves the server (the builder's Try it).
  */
-export async function issueApiToken(appId: number, username: string, hours: number) {
-  const app = await owner.one('select alias, api_role, access_control from meta.app where id = $1', [appId]);
+export async function issueApiToken(appId: number, username: string, hours: number, opts: { self?: boolean; internal?: boolean } = {}) {
+  const app = await owner.one('select id, alias, api_role, access_control, authentication, mfa, mfa_roles from meta.app where id = $1', [appId]);
   if (!app) throw new Error('No such application.');
   // without an API role the token is for pgkiln's own REST modules only (they run as the app's role)
   const problem = app.api_role ? await apiRoleProblem(app.api_role) : null;
@@ -63,6 +66,10 @@ export async function issueApiToken(appId: number, username: string, hours: numb
   if (!acc) throw new Error(`There is no account "${username}".`);
   if (!acc.active) throw new Error('This account is inactive.');
   if (!acc.has_access && app.access_control !== 'any_user') throw new Error('This account has no access to the application.');
+  // (sprint 131, SEC-3) a user who must sign in in two steps gets a token only from their own sign-in, after a second
+  // step (My account, src/runtime/two-step.ts), never one a developer issues for them
+  if (!opts.self && !opts.internal && (await accountMustUseMfa(app, acc.username)))
+    throw new Error(`The application requires two-factor sign-in of "${acc.username}": they create their own on My account, after a second step (REST API → Users create their own tokens).`);
   const ttl = Math.max(1, Math.min(MAX_TOKEN_HOURS, Math.round(hours)));
   const token = await new SignJWT({ ...(app.api_role ? { role: app.api_role } : {}), app_user: acc.username, app: app.alias })
     .setProtectedHeader({ alg: 'HS256', typ: 'JWT' })

package/src/builder/api.ts

@@ -123,6 +123,8 @@ async function apiPage(s: Session, a: any, issued?: { token: string; username: s
         <form method="post" action="${BASE}/apps/${a.id}/api">${csrf(s)}
           <div class="form-grid">
             ${input('api_role', 'API database role', role, { placeholder: 'e.g. myapp_api', help: 'For PostgREST: grant it only the api schema’s views and functions, and grant it to pgkiln_authenticator. Empty: tokens work for the REST modules pgkiln serves (Shared Components → REST modules) only.' })}
+            <div class="field"><span class="label" aria-hidden="true"></span><label class="check"><input type="checkbox" name="api_self_tokens" value="true"${a.api_self_tokens ? raw(' checked') : ''}> Users create their own tokens</label>
+              <small class="help">On <em>My account</em>, signed-in users create a token that acts as them. A user the application requires two-factor sign-in of gives a second step first (if their last one is older than 15 minutes); for such users this is the only way to get a token.</small></div>
           </div>
           <div class="buttons"><button class="btn btn-hot">Save</button></div>
         </form>
@@ -171,7 +173,7 @@ export async function apiRoutes(app: FastifyInstance) {
     try {
       const problem = role ? await apiRoleProblem(role) : null;
       if (problem) throw new Error(problem);
-      await owner.query('update meta.app set api_role = $2, updated_at = now() where id = $1', [req.params.id, role]);
+      await owner.query('update meta.app set api_role = $2, api_self_tokens = $3, updated_at = now() where id = $1', [req.params.id, role, req.body?.api_self_tokens === 'true']);
       flash(s, role ? `API role set to ${role}.` : 'API role removed; new tokens work for the REST modules pgkiln serves only.');
     } catch (e) {
       flash(s, (e as Error).message, 'error');

package/src/builder/components.ts

@@ -420,6 +420,7 @@ export const COMPONENTS: Record<string, ComponentSpec> = {
       { name: 'type', label: 'Type', kind: 'select', options: ['role', 'sql'] },
       { name: 'value', label: 'Role name / SQL expression', kind: 'code', wide: true, help: "role: e.g. admin · sql: e.g. meta.has_role('manager') or :APP_USER = 'boss'" },
       { name: 'error_message', label: 'Error message', kind: 'text', wide: true },
+      { name: 'mfa_minutes', label: 'Second step within (minutes)', kind: 'int', help: 'Step-up: the scheme passes only when the user gave a second factor (code or passkey) at most this many minutes ago; a page that needs it asks again, then opens. Users without one are refused. Empty: no step-up.' },
     ],
   },
   lov: {

package/src/builder/login-page.ts

@@ -1,6 +1,6 @@
 import type { FastifyInstance } from 'fastify';
 import { owner } from '../db.ts';
-import { APP_MFA, type AppMfa } from '../account-mfa.ts';
+import { APP_MFA, EMAIL_CODE_MINUTES, EMAIL_CODES_PER_HOUR, type AppMfa } from '../account-mfa.ts';
 import { html, raw } from '../html.ts';
 import { secretKeyConfigured } from '../secrets.ts';
 import { back, BASE, developer, flash, type Req } from './ui.ts';
@@ -9,7 +9,7 @@ import { back, BASE, developer, flash, type Req } from './ui.ts';
 // own login page (APEX: the login page, usually 9999) and "Forgot password?".
 // "Create login page" adds a minimal public page with a login region and
 // makes it the login page. (sprint 130, SEC-3) Two-factor sign-in for the
-// application's users: off, optional, required, or required for some roles.
+// application's users: off, optional, required, or required for some roles. (sprint 131) A code by e-mail.
 
 interface AppRow {
   id: number;
@@ -20,6 +20,7 @@ interface AppRow {
   password_reset: boolean;
   mfa: AppMfa;
   mfa_roles: string[];
+  mfa_email: boolean;
 }
 
 /** The fields in the settings form. */
@@ -56,7 +57,11 @@ export async function loginSettingsFields(a: AppRow) {
       <div class="field"><label class="label" for="f_mfa_roles">Required for roles</label>
         <input id="f_mfa_roles" name="mfa_roles" value="${(a.mfa_roles ?? []).join(', ')}" placeholder="admin, manager" aria-describedby="f_mfa_roles_help">
         <small class="help" id="f_mfa_roles_help">With <em>Required for some roles</em>: users with one of these roles must use it, others may.</small></div>
-    </div>`;
+      <div class="field"><span class="label" aria-hidden="true"></span><label class="check"><input type="checkbox" name="mfa_email" value="true"${a.mfa_email ? raw(' checked') : ''}> Offer a code by e-mail</label>
+        <small class="help">At the second step, users who have an authenticator app or a passkey may ask for a one-time code by e-mail instead (valid ${EMAIL_CODE_MINUTES} minutes, at most ${EMAIL_CODES_PER_HOUR} an hour). It is never someone's only factor: a user who must add one still adds an app or a passkey.
+          ${mailOk ? '' : html`<strong>Not offered yet:</strong> the application needs an enabled mail service with a From address.`}</small></div>
+    </div>
+    <p class="muted small">Users also add <strong>passkeys</strong> (fingerprint, face, PIN or a security key) on <em>My account</em> or while signing in; they need the application at a host name, not an IP address. To ask for the second step again before a page opens (step-up), give its authorization scheme <em>Second step within (minutes)</em> in Shared Components.</p>`;
 }
 
 const MFA_LABELS: Record<AppMfa, string> = { off: 'Off', optional: 'Optional (users may add an app)', required: 'Required', roles: 'Required for some roles' };
@@ -71,8 +76,8 @@ export async function saveLoginSettings(appId: string, b: Record<string, string
   if (mfa === 'roles' && !roles.length) throw new Error('Two-factor sign-in: name the roles that must use it.');
   // without the instance key, users could not add an app: requiring one would lock them out
   if ((mfa === 'required' || mfa === 'roles') && !secretKeyConfigured()) throw new Error('Two-factor sign-in: the server needs PGKILN_SECRET_KEY before it can be required.');
-  await owner.query('update meta.app set login_page = $2, password_reset = $3, mfa = $4, mfa_roles = $5 where id = $1',
-    [appId, page, b.password_reset === 'true', mfa, roles]);
+  await owner.query('update meta.app set login_page = $2, password_reset = $3, mfa = $4, mfa_roles = $5, mfa_email = $6 where id = $1',
+    [appId, page, b.password_reset === 'true', mfa, roles, b.mfa_email === 'true']);
 }
 
 export async function loginPageRoutes(app: FastifyInstance) {

package/src/builder/rest-modules.ts

@@ -599,7 +599,7 @@ export async function restModuleRoutes(app: FastifyInstance) {
       const headers: Record<string, string> = {};
       if (as) {
         if (!(await tryAccounts(m.app_id)).includes(as)) throw new Error('Choose an account with access to the application.');
-        headers.authorization = `Bearer ${(await issueApiToken(m.app_id, as, 1)).token}`;
+        headers.authorization = `Bearer ${(await issueApiToken(m.app_id, as, 1, { internal: true })).token}`;
       }
       const raw = h.method === 'GET' || h.method === 'DELETE' ? '' : String(b.body ?? '').trim();
       if (raw) {

package/src/builder/security.ts

@@ -11,7 +11,7 @@ import {
 import { qrSvg } from '../qrcode.ts';
 import { secretKeyConfigured } from '../secrets.ts';
 import { clientIp, logActivity, saveState, type Session } from '../session.ts';
-import { ALGORITHMS, newChallenge, relyingParty, verifyRegistration, WebAuthnError } from '../webauthn.ts';
+import { ALGORITHMS, giveChallenge, relyingParty, takeChallenge, verifyRegistration, WebAuthnError } from '../webauthn.ts';
 import { tr } from './i18n.ts';
 import { isAdmin } from './locks.ts';
 import { identitiesRegion } from './builder-sso.ts';
@@ -28,24 +28,8 @@ import { back, BASE, csrf, developer, flash, input, region, send, shell, type Re
 // (public/builder.js, [data-passkey]); without JavaScript the button stays hidden. Trusted browsers can be
 // forgotten here; the instance decides how long a browser may be trusted (0 = never).
 
-const CHALLENGE_SECONDS = 300;
-
-/** A one-time WebAuthn challenge kept in the session (for this purpose only), or null when there is none or it expired. */
-export function takeChallenge(s: Session, purpose: 'create' | 'get'): string | null {
-  try {
-    const p = JSON.parse(String(s.state.__PK ?? ''));
-    delete s.state.__PK;
-    return p && p.purpose === purpose && Date.now() - Number(p.at) < CHALLENGE_SECONDS * 1000 && typeof p.c === 'string' ? p.c : null;
-  } catch {
-    delete s.state.__PK;
-    return null;
-  }
-}
-export function giveChallenge(s: Session, purpose: 'create' | 'get'): string {
-  const c = newChallenge();
-  s.state.__PK = JSON.stringify({ c, purpose, at: Date.now() });
-  return c;
-}
+// (sprint 131) the challenge helpers moved to src/webauthn.ts: application users have passkeys too
+export { giveChallenge, takeChallenge };
 
 const SECRET_MINUTES = 10;