pgkiln 0.63.0 → 0.64.0

package/SECURITY.md

@@ -116,6 +116,7 @@ first version (MVP). Every finding below has a regression test in
 | Passkeys and trusted browsers (0.61.0) | Passkeys (WebAuthn) are checked in `src/webauthn.ts` without a library: a 32-byte one-time challenge per purpose (registration or sign-in) kept in the session for five minutes and used up on the first answer, the `clientDataJSON` type, challenge and origin (`PUBLIC_URL`'s, else the browser's own), the SHA-256 of the relying party id in the authenticator data, user presence, an ES256, EdDSA or RS256 signature over the authenticator data and the client data hash, and a signature counter that must go up (updated atomically, so a replayed or cloned key is refused). The CBOR reader takes only definite lengths, at most 16 levels and 1,000 entries. Credentials are public keys (no secret to leak, independent of the instance key); attestation is *none*. `PGKILN_RP_ID` is only honoured when it is the host or a parent domain of it. The sign-in options (the developer's credential ids) are only given after the password step, with the CSRF token. Trusted browsers (off by default) are a random 256-bit cookie token (`HttpOnly`, `SameSite=Lax`, `Secure` with `COOKIE_SECURE`, path `/builder`) of which only the SHA-256 is stored; the cookie is only looked at after a correct password, for that developer, and ends with its days, a new password, removing a factor, a reset, *Forget trusted browsers* or turning trust off (which removes every trusted browser at once). |
 | Passkey sign-in without a password, workspace rule (0.62.0) | *Sign in with a passkey* asks the browser for any passkey of this site (empty allow list) with `userVerification: required`, and the server refuses an answer whose authenticator data lacks the user-verified flag, so the passkey alone stands for possession plus a fingerprint, face or PIN. The credential id is looked up for this relying party only; a user handle, when the browser sends one, must be the developer's (a SHA-256-derived handle, not the user name). The same one-time challenge, origin, RP ID hash, signature and counter checks as at the second step apply; failures are logged as `login_failed` with the developer's name when the key is known and count for the per-user and per-IP lockout. Administrators turn it off in Instance settings. A workspace's rule (administrators and its own administrators only, CSRF-checked) can only add a requirement; `pgkiln admin set-2fa-policy off` clears every workspace's rule. While a second factor is required of a developer, a sign-in with the default password leads only to the password change. |
 | Single sign-on for developers (0.63.0) | A provider or directory signs developers in only with *builder* turned on. The flow is the applications' (state, PKCE, nonce, browser-binding cookie, ID token or SAML assertion checks) with a pending row without an application; developers are found by the provider's stable subject in `meta.developer_identity`, never by a name alone. An existing developer is linked by name only when the administrator allows it, once, never a break-glass administrator, and an e-mail user name only when verified; otherwise the developer links the identity on Security, which needs their session and CSRF token to start and the same browser to finish, and one identity can't be linked to two developers. Automatic accounts need the developers group when one is set and start as developers; the administrators group decides the role at every sign-in but never demotes a break-glass administrator. A workspace's single sign-on rule (administrators and its own administrators, CSRF-checked) refuses the pgkiln password and a passkey alone, after the password check so it reveals nothing; it can only be turned on while a break-glass administrator exists and by someone who could still sign in; the last break-glass administrator and a developer's last identity can't be removed while it applies. Failures are logged as `login_failed` with the reason. |
+| Two-factor sign-in for application users (0.64.0) | Per application (`meta.app.mfa`: off, optional, required, required for roles). The account's TOTP secrets are encrypted with `PGKILN_SECRET_KEY` and stored only after a code confirms them; recovery codes are SHA-256 and used up atomically; each 30-second step once, one step either side. A password or LDAP sign-in that needs the step creates no session: the pending sign-in (5 minutes, 10 while adding an app) lives in the signed-out session, bound to it and to the page's CSRF token, and a forged token ends it. Wrong codes count as failed sign-ins (the per-user and per-IP lockout). A *Keep me signed in* or session-sharing token stands in for the step only when its method ends in `+2fa`; an identity provider's sign-in is left to the provider. Without the instance key the step can't be required and enrolment refuses rather than skips. Removing an app needs a current or recovery code and is refused for the last app while the application requires it; a developer's reset (Users, with a reason) removes the apps and codes and ends the account's sessions, remembered and shared sign-ins. Every enrolment, removal, reset and used recovery code is in the activity log. The factor tables are closed to the runtime roles. |
 
 ## Findings of the MVP review and their fixes
 
@@ -240,3 +241,4 @@ A second full review, mainly of what end users and API callers can reach. Regres
 10. With database-account authentication: list exact roles or use a dedicated membership role, and limit what those roles may connect to in `pg_hba.conf` (they can reach the database with their password outside pgkiln too).
 11. Turn on two-factor sign-in for the builder (Instance settings → Two-factor sign-in, at least for administrators) once two administrators have a passkey or an authenticator app; set `PUBLIC_URL` to the address developers use (passkeys belong to its host name), require it per workspace where the instance policy is too broad, keep *Trust a browser* short or at 0 on shared machines, keep `PGKILN_SECRET_KEY` backed up, and keep the recovery commands (`pgkiln admin reset-2fa`) for people with server access only.
 12. With single sign-on for developers: leave *Link an existing developer with the same user name* off unless you trust the provider's user names, set a developers group for automatic accounts, make at least one administrator break-glass (with a second factor and a password kept safe) before a workspace requires single sign-on, and keep `pgkiln admin builder-sign-in password` for people with server access only.
+13. Require two-factor sign-in of an application's users at least for administrators (Application settings → Sign-in methods → Two-factor sign-in → *Required for some roles*: `admin`); the Advisor warns when it is missing. Keep `PGKILN_SECRET_KEY` backed up: without it the authenticator apps stop working and users need their recovery codes or a reset.

package/db/migrations/132_app_user_mfa.sql

@@ -0,0 +1,58 @@
+-- ---------------------------------------------------------------------
+-- 132: two-step sign-in for application users (sprint 130, SEC-3 part 1;
+-- beyond APEX, which has no second factor for application accounts).
+--
+-- meta.account_factor: an account's second factors. This sprint: an
+-- authenticator app (TOTP, RFC 6238), its secret encrypted with the
+-- instance key (PGKILN_SECRET_KEY), like a developer's (128). last_step is
+-- the last 30-second step a code was accepted for, so a code works once.
+-- An account's factors serve every application it may use.
+--
+-- meta.account_recovery_code: ten one-time codes per account, as SHA-256
+-- of the normalised code; confirmed: the user said they saved them.
+--
+-- meta.app.mfa, per application (exported with it):
+--   off      : no second step (the default)
+--   optional : users who added an authenticator app give a code
+--   required : every user gives a code; without an app, they add one while
+--              signing in
+--   roles    : required for users with one of mfa_roles, optional for others
+-- It covers the user directory's passwords and LDAP directories; an identity
+-- provider (OpenID Connect, SAML) decides on its own second factor.
+--
+-- Owner-only, like meta.persistent_login: the runtime roles never read them.
+-- Installation data: not exported with an application or a workspace.
+-- ---------------------------------------------------------------------
+create table meta.account_factor (
+  id           int generated always as identity primary key,
+  account_id   int not null references meta.account on delete cascade,
+  kind         text not null check (kind in ('totp')),
+  name         text not null check (length(name) between 1 and 60),
+  secret_enc   text not null,
+  last_step    bigint,
+  created_at   timestamptz not null default now(),
+  last_used_at timestamptz
+);
+create index on meta.account_factor (account_id);
+revoke all on meta.account_factor from public;
+comment on table meta.account_factor is
+  'An application account''s second factors (132): authenticator apps (TOTP) with the secret encrypted with the instance key.';
+
+create table meta.account_recovery_code (
+  account_id int not null references meta.account on delete cascade,
+  code_hash  text not null,
+  confirmed  boolean not null default false,
+  created_at timestamptz not null default now(),
+  used_at    timestamptz,
+  primary key (account_id, code_hash)
+);
+revoke all on meta.account_recovery_code from public;
+comment on table meta.account_recovery_code is
+  'One-time recovery codes of application accounts (132), as sha256 hex of the normalised code.';
+
+alter table meta.app
+  add column mfa text not null default 'off' check (mfa in ('off', 'optional', 'required', 'roles')),
+  add column mfa_roles text[] not null default '{}';
+comment on column meta.app.mfa is
+  'Two-step sign-in for the application''s users (132): off, optional, required, or roles (required for mfa_roles).';
+comment on column meta.app.mfa_roles is 'Roles (lower case) that must use two-step sign-in when mfa = roles.';

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)); two-factor for application users follows (SEC-3) |
+| 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)) |
 | 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,6 +300,9 @@ 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)).
+  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
   table or column refuses the deployment instead of failing at run time.

package/docs/guide/08-security.md

@@ -410,6 +410,46 @@ opening another application of the group signs the user in there without the sig
 
 Applications of different groups, and applications without a group, sign in on their own.
 
+### Two-factor sign-in
+
+APEX has no second factor for an application's own accounts: its documented route is an identity provider whose
+sign-on policy asks for one, or a hand-written TOTP check in a custom authentication scheme. pgkiln has it built in.
+**Application settings → Sign-in methods → Two-factor sign-in → Second step**:
+
+| 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 |
+| **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:
+
+- The second step follows the user directory's **password** and **LDAP** directories. An identity provider
+  ([OpenID Connect](#single-sign-on-openid-connect), [SAML](#single-sign-on-saml-20)) asks for its own second factor;
+  database accounts, custom authentication and HTTP header authentication are not covered.
+- The code comes from any authenticator app (TOTP, RFC 6238: Google Authenticator, Microsoft Authenticator,
+  1Password …), each code once, one 30-second step either side for clock drift. A **recovery code** (ten per account,
+  each usable once) works instead, and leads to *My account*, which says how many are left.
+- Until the code is right there is no session: the pending sign-in waits five minutes (ten while adding an app) in
+  the signed-out session. Wrong codes count as failed sign-ins, so the usual lockout applies.
+- An account's apps serve every application it uses, and each application decides whether it asks for them.
+- **My account → Two-factor sign-in** adds an app (QR code or key, then its first code), shows new recovery codes,
+  and removes an app with a current code or a recovery code. The last app can't be removed while the application
+  requires a code of the user.
+- A *Keep me signed in* or session-sharing sign-in skips the second step only when it was made with one (its method
+  ends in `+2fa`, shown in the Activity monitor); one made with just a password signs in again with the code.
+- **Users → account → Two-factor sign-in** shows who has an app; **Reset two-factor sign-in** (with a reason, logged
+  as `2fa_reset`) removes the apps and recovery codes after a lost phone and signs the account out everywhere. Where
+  an application requires the step, the user adds a new app at the next sign-in.
+- The apps' secrets are encrypted with the instance key `PGKILN_SECRET_KEY` (in `meta.account_factor`, readable by
+  the owner connection only); without that key *Required* can't be chosen, and the sign-in refuses rather than skips
+  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.
+
 ### What sign-in protects against
 
 - **Brute force**: after 5 failed attempts for a username (or 50 from one IP address) within 15
@@ -418,13 +458,13 @@ Applications of different groups, and applications without a group, sign in on t
   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),
+  [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.
 
 All sign-ins, failures and lockouts appear in the **Activity** monitor.
 
-A second factor for an application's users comes from the identity provider ([OpenID Connect](#single-sign-on-openid-connect),
-[SAML](#single-sign-on-saml-20)). Developers can use an authenticator app for the builder itself:
-[two-factor sign-in](03-builder.md#two-factor-sign-in).
-
 ## Authorization: what may the user do?
 
 ### Authorization schemes
@@ -643,4 +683,5 @@ decision.
 4. Checksum protection on pages (the default).
 5. Business rules in constraints, triggers or functions, not only in validations.
 6. Debug mode and debug messages off.
-7. Review the app's **Settings → Security checklist** and **Activity** monitor now and then.
+7. [Two-factor sign-in](#two-factor-sign-in) required at least for administrators (the Advisor checks it).
+8. Review the app's **Settings → Security checklist** and **Activity** monitor now and then.

package/docs/guide/09-reference.md

@@ -337,6 +337,7 @@ All in schema `meta`. `id` columns are generated; `seq` orders siblings (default
 | `sso_providers` | text[] | Names of identity providers (OpenID Connect or SAML) offered on the login page |
 | `ldap_directories` | text[] | LDAP directories the password form checks, after local accounts |
 | `remember_me_days` | int | Days a "Keep me signed in" sign-in lasts; NULL = not offered |
+| `mfa`, `mfa_roles` | text, text[] | [Two-factor sign-in](08-security.md#two-factor-sign-in): `off`, `optional`, `required` or `roles` (required for `mfa_roles`) |
 | `pwa`, `pwa_short_name`, `pwa_icon`, `pwa_offline_pages`, `pwa_offline_submit` | boolean, text, bytea, boolean, boolean | Progressive Web App ([chapter 17](17-mobile.md)) |
 | `db_role` | text | Database role every request runs as |
 | `api_role` | text | Database role of REST API tokens for this app (PostgREST switches to it) |
@@ -510,7 +511,8 @@ navigation entries and application processes have the same `build_option` column
 | `supporting_script` | Supporting objects per app (see above) | no |
 | `document_template` | Document templates per app: `name`, `description`, `query`, `template`, `layout`, `filename`, `authz` | yes (read) |
 | `ldap_identity` | Links an account to a directory entry (`directory_id`, `subject` = entryUUID or DN) | no |
-| `persistent_login` | "Keep me signed in" tokens: `token_hash`, `account_id`, `app_id`, `groups`, `method`, `expires_at` | no |
+| `persistent_login` | "Keep me signed in" tokens: `token_hash`, `account_id`, `app_id`, `groups`, `method` (`+2fa` after a second step), `expires_at` | no |
+| `account_factor`, `account_recovery_code` | An account's authenticator apps (secret encrypted with the instance key) and recovery codes (SHA-256) | no |
 | `instance_setting` | Secrets, e.g. the URL checksum key | no |
 | `setting` | Account settings: `password_min_length`, `password_require_mixed`, `password_lifetime_days` | yes (read) |
 | `text_message` | Per app: `name`, `language`, `text` | yes |
@@ -609,6 +611,8 @@ pgkiln's icons; its filter box also searches the Lucide icons by name and search
 | any page `?doc=NAME` | Download a document template filled with the page's values |
 | `POST /a/:alias/account/devices` | Sign out on all devices ("Keep me signed in") |
 | `POST /a/:alias/password` | Change an expired password while signing in |
+| `GET/POST /a/:alias/login/2fa`, `POST /a/:alias/login/2fa/done` | The second step of signing in: a code, or adding the first app and seeing the recovery codes |
+| `POST /a/:alias/account/2fa/start`, `…/cancel`, `…/confirm`, `…/codes`, `…/codes/confirm`, `…/:id/delete` | My account → Two-factor sign-in |
 | `GET/POST /a/:alias/account`, `POST /a/:alias/account/password`, `POST /a/:alias/account/theme`, `POST /a/:alias/account/style` | My account, own password, the light/dark switch, the [style variant](14-globalization.md#style-variants-theme-roller) switch |
 | `POST /a/:alias/tz` | The browser's time zone for the session (automatic time zone; sent by `app.js`, CSRF token required) |
 | any page `?lang=xx` | Switch the language for the session |

package/docs/guide/11-from-apex.md

@@ -98,7 +98,8 @@ APEX's "Social Sign-In" scheme, with identity-provider groups mapped to applicat
 in to a second app is then silent via the identity provider's session. See
 [chapter 8](08-security.md#single-sign-on-openid-connect). **SAML 2.0** providers and **LDAP /
 Active Directory** passwords work the same way (groups → roles), and *Keep me signed in* matches
-APEX's persistent authentication. **Database accounts** sign in with PostgreSQL login roles, and
+APEX's persistent authentication. Unlike APEX, the user directory's accounts can have
+[two-factor sign-in](08-security.md#two-factor-sign-in) (an authenticator app), per application and per role. **Database accounts** sign in with PostgreSQL login roles, and
 **custom authentication** calls your own PL/pgSQL function (APEX: a custom PL/SQL scheme), see
 [chapter 8](08-security.md#custom-authentication-a-plpgsql-function). The **login page** (APEX: page 9999 with
 the Login region template) is a page you design in the Page Designer around a **Login** region, and

package/docs/guide/12-development.md

@@ -62,6 +62,10 @@ src/
   dbauth.ts                database-account authentication: role lists, a short connection as the role (DATABASE_URL target), membership/superuser checks
   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)
+  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
   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
@@ -171,6 +175,8 @@ src/
     routes.ts              HTTP handlers: show, submit, dynamic actions, cascading lists, login
     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
     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)
     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

package/package.json

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

package/public/app.css

@@ -2164,3 +2164,13 @@ body.nav-pillar-dark .t-nav details:has(> summary.in-trail) > ul { border-inline
   .region[aria-busy="true"]::after { animation: busy-slide 1.2s cubic-bezier(0.45, 0.05, 0.55, 0.95) infinite; }
 }
 @keyframes busy-slide { from { background-position: -60% 0, 0 0; } to { background-position: 160% 0, 0 0; } }
+
+/* (sprint 130) two-step sign-in: the QR code for an authenticator app, its key and the recovery codes */
+.mfa-qr { margin: .5rem 0 1rem; }
+.mfa-qr svg { width: 200px; max-width: 100%; height: auto; background: #fff; padding: 8px; border-radius: 6px; }
+.mfa-secret { word-break: break-all; letter-spacing: .05em; }
+.mfa-steps { padding-left: 1.25rem; margin: 0; }
+.mfa-codes { columns: 2; column-gap: 2rem; padding-left: 1.5rem; }
+.mfa-factors { list-style: none; padding: 0; margin: 0 0 .75rem; }
+.mfa-factors li { padding: .4rem 0; border-bottom: 1px solid var(--border); }
+@media (max-width: 480px) { .mfa-codes { columns: 1; } }

package/src/account-mfa.ts

@@ -0,0 +1,93 @@
+import { owner } from './db.ts';
+import { ACCOUNTS, storeAddTotp, storeCheck, storeCodesLeft, storeConfirmCodes, storeHasFactor, storeNewCodes } 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,
+// migration 132) serve every application it may use; each application decides whether it asks for them (meta.app.mfa):
+// 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.
+
+export type AppMfa = 'off' | 'optional' | 'required' | 'roles';
+export const APP_MFA: AppMfa[] = ['off', 'optional', 'required', 'roles'];
+
+export interface MfaApp { authentication: string; mfa?: AppMfa | null; mfa_roles?: string[] | null }
+
+/** Whether the application has a second step at all (its own accounts, and not "off"). */
+export const mfaOn = (a: MfaApp) => a.authentication === 'app_users' && !!a.mfa && a.mfa !== 'off';
+
+/** Whether the application requires a second step of a user with these roles. */
+export function mfaRequired(a: MfaApp, roles: string[]): boolean {
+  if (!mfaOn(a)) return false;
+  if (a.mfa === 'required') return true;
+  const need = new Set((a.mfa_roles ?? []).map((r) => r.toLowerCase()));
+  return a.mfa === 'roles' && roles.some((r) => need.has(r.toLowerCase()));
+}
+
+/** The sign-in methods a second step follows (the directory's password, an LDAP directory). */
+export const knowsPassword = (method: string | undefined) => !method || method.startsWith('password') || method.startsWith('ldap:');
+export const MFA_SUFFIX = '+2fa';
+export const withSecondStep = (method: string | undefined) => `${method ?? 'password'}${MFA_SUFFIX}`;
+
+/** An active account's id by user name (accounts are matched without regard to case). */
+export async function accountId(username: string): Promise<number | null> {
+  return (await owner.one<{ id: number }>('select id from meta.account where lower(username) = lower($1) and active', [username]))?.id ?? null;
+}
+
+/**
+ * What a password (or LDAP) sign-in to this application still needs: 'code' (the user has an authenticator app),
+ * 'enrol' (required, and the user has none yet) or null (no second step).
+ */
+export async function secondStep(a: MfaApp, username: string, roles: string[]): Promise<'code' | 'enrol' | null> {
+  if (!mfaOn(a)) return null;
+  const id = await accountId(username);
+  if (id === null) return null;
+  if (await storeHasFactor(ACCOUNTS, id)) return 'code';
+  return mfaRequired(a, roles) ? 'enrol' : null;
+}
+
+/**
+ * Whether a remembered or shared sign-in may sign the user in here without a second step: one made with an identity
+ * provider, one that had a second step, or a user this application asks nothing of.
+ */
+export async function carriesSecondStep(a: MfaApp, username: string, roles: string[], method: string | undefined): Promise<boolean> {
+  if (!knowsPassword(method) || method?.endsWith(MFA_SUFFIX)) return true;
+  return (await secondStep(a, username, roles)) === null;
+}
+
+export interface AccountFactor { id: number; name: string; created_at: string; last_used_at: 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;
+}
+
+export const accountHasFactor = (id: number) => storeHasFactor(ACCOUNTS, id);
+export const accountCodesLeft = (id: number) => storeCodesLeft(ACCOUNTS, id);
+export const addAccountTotp = (id: number, name: string, secret: string, step: number) => storeAddTotp(ACCOUNTS, id, name, secret, step);
+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);
+
+/** 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> {
+  return owner.tx(async (c) => {
+    const gone = (await c.query('delete from meta.account_factor where id = $1 and account_id = $2', [factorId, id])).rowCount;
+    if (gone && !(await c.query('select 1 from meta.account_factor where account_id = $1', [id])).rowCount)
+      await c.query('delete from meta.account_recovery_code where account_id = $1', [id]);
+    return !!gone;
+  });
+}
+
+/** (Manage users) Remove every second factor of an account and end its sessions and remembered sign-ins. */
+export async function resetAccountFactors(id: number): Promise<boolean> {
+  return owner.tx(async (c) => {
+    const acc = (await c.query<{ username: string }>('select username from meta.account where id = $1', [id])).rows[0];
+    if (!acc) return false;
+    await c.query('delete from meta.account_factor where account_id = $1', [id]);
+    await c.query('delete from meta.account_recovery_code where account_id = $1', [id]);
+    await c.query('delete from meta.persistent_login where account_id = $1', [id]);
+    await c.query('delete from meta.shared_login where account_id = $1', [id]);
+    await c.query('delete from meta.session where app_id is not null and lower(username) = lower($1)', [acc.username]);
+    return true;
+  });
+}

package/src/builder/advisor.ts

@@ -187,6 +187,14 @@ export async function advise(appId: number, tx?: pg.ClientBase, opts: { db?: Db
     else if (!all.some((x) => x.kind === 'region' && x.row.type === 'login' && Number(x.row.page_no) === Number(app.login_page)))
       findings.push({ severity: 'error', entry: null, field, message: `Page ${app.login_page} has no Login region: nobody can sign in.` });
   }
+  // (sprint 130, SEC-3) administrators of the application who sign in with only a password
+  if (app.authentication === 'app_users' && (app.local_login || (app.ldap_directories ?? []).length)) {
+    const covered = app.mfa === 'required' || (app.mfa === 'roles' && (app.mfa_roles ?? []).includes('admin'));
+    const admins = covered ? 0 : (await one(`select count(*)::int as n from meta.app_access where app_id = $1 and 'admin' = any(roles)`, [appId])).n;
+    if (admins)
+      findings.push({ severity: 'warning', entry: null, field: 'Application settings → Two-factor sign-in',
+        message: `${admins === 1 ? 'A user' : `${admins} users`} with the admin role sign${admins === 1 ? 's' : ''} in with only a password: require two-factor sign-in (Required, or Required for roles: admin).` });
+  }
   // (089) a page's group exists
   for (const p of (await query(`select p.page_no, p.page_group from meta.page p where p.app_id = $1 and p.page_group is not null
                                    and not exists (select 1 from meta.page_group g where g.app_id = p.app_id and g.name = p.page_group) order by 1`, [appId])).rows)

package/src/builder/i18n/de.ts

@@ -1870,4 +1870,10 @@ export const de: BuilderMessages = {
   'wsp.sso_off': 'Die Entwickler des Workspace dürfen wieder das pgkiln-Kennwort verwenden.',
   'wsp.sso_no_break_glass': 'Geben Sie zuerst einem Administrator Notfallzugang (Entwickler), damit sich jemand anmelden kann, wenn der Identitätsanbieter ausfällt.',
   'wsp.sso_link_first': 'Verknüpfen Sie zuerst auf Ihrer Sicherheitsseite eine Identität, sonst könnten Sie sich selbst nicht anmelden.',
+  'us.mfa_title': 'Zwei-Faktor-Anmeldung',
+  'us.mfa_status': 'Authenticator-Apps: {n}. Verbleibende Wiederherstellungscodes: {codes}.',
+  'us.mfa_none': 'Noch keine Authenticator-App.',
+  'us.mfa_reset_help': 'Entfernt die Authenticator-Apps und Wiederherstellungscodes von {user} und meldet das Konto überall ab. Wo eine Anwendung die Zwei-Faktor-Anmeldung verlangt, wird bei der nächsten Anmeldung eine neue App hinzugefügt. Wird protokolliert.',
+  'us.mfa_reset_done': 'Die Zwei-Faktor-Anmeldung von {user} wurde zurückgesetzt.',
+  'us.mfa_reason_needed': 'Geben Sie einen Grund für das Zurücksetzen an.',
 };

package/src/builder/i18n/en.ts

@@ -1873,4 +1873,10 @@ export const en = {
   'wsp.sso_off': 'The workspace’s developers may use the pgkiln password again.',
   'wsp.sso_no_break_glass': 'Make an administrator break-glass first (Developers), so someone can still sign in when the identity provider fails.',
   'wsp.sso_link_first': 'Link an identity on your Security page first, or you could not sign in yourself.',
+  'us.mfa_title': 'Two-factor sign-in',
+  'us.mfa_status': 'Authenticator apps: {n}. Recovery codes left: {codes}.',
+  'us.mfa_none': 'No authenticator app yet.',
+  'us.mfa_reset_help': 'Removes the authenticator apps and recovery codes of {user} and signs them out everywhere. Where an application requires two-factor sign-in, they add a new app at their next sign-in. Logged.',
+  'us.mfa_reset_done': 'Two-factor sign-in of {user} was reset.',
+  'us.mfa_reason_needed': 'Give a reason for the reset.',
 } as const;

package/src/builder/i18n/es.ts

@@ -1870,4 +1870,10 @@ export const es: BuilderMessages = {
   'wsp.sso_off': 'Los desarrolladores del espacio de trabajo pueden volver a usar la contraseña de pgkiln.',
   'wsp.sso_no_break_glass': 'Primero dé acceso de emergencia a un administrador (Desarrolladores), para que alguien pueda entrar si falla el proveedor de identidad.',
   'wsp.sso_link_first': 'Vincule primero una identidad en su página de seguridad, o usted mismo no podría iniciar sesión.',
+  'us.mfa_title': 'Inicio de sesión en dos pasos',
+  'us.mfa_status': 'Aplicaciones de autenticación: {n}. Códigos de recuperación restantes: {codes}.',
+  'us.mfa_none': 'Aún no hay ninguna aplicación de autenticación.',
+  'us.mfa_reset_help': 'Quita las aplicaciones de autenticación y los códigos de recuperación de {user} y cierra todas sus sesiones. Donde una aplicación exija el inicio de sesión en dos pasos, añadirá una aplicación nueva en su próximo inicio de sesión. Queda registrado.',
+  'us.mfa_reset_done': 'Se restableció el inicio de sesión en dos pasos de {user}.',
+  'us.mfa_reason_needed': 'Indique un motivo para el restablecimiento.',
 };

package/src/builder/i18n/fr.ts

@@ -1870,4 +1870,10 @@ export const fr: BuilderMessages = {
   'wsp.sso_off': 'Les développeurs de l’espace de travail peuvent de nouveau utiliser le mot de passe pgkiln.',
   'wsp.sso_no_break_glass': 'Donnez d’abord l’accès de secours à un administrateur (Développeurs), pour que quelqu’un puisse se connecter si le fournisseur d’identité tombe en panne.',
   'wsp.sso_link_first': 'Liez d’abord une identité sur votre page Sécurité, sinon vous ne pourriez plus vous connecter.',
+  'us.mfa_title': 'Connexion à deux facteurs',
+  'us.mfa_status': 'Applications d’authentification : {n}. Codes de récupération restants : {codes}.',
+  'us.mfa_none': 'Aucune application d’authentification pour l’instant.',
+  'us.mfa_reset_help': 'Supprime les applications d’authentification et les codes de récupération de {user} et le déconnecte partout. Là où une application exige la connexion à deux facteurs, une nouvelle application est ajoutée à la prochaine connexion. Journalisé.',
+  'us.mfa_reset_done': 'La connexion à deux facteurs de {user} a été réinitialisée.',
+  'us.mfa_reason_needed': 'Indiquez la raison de la réinitialisation.',
 };

package/src/builder/i18n/nl.ts

@@ -1870,4 +1870,10 @@ export const nl: BuilderMessages = {
   'wsp.sso_off': 'De ontwikkelaars van de werkruimte mogen weer het pgkiln-wachtwoord gebruiken.',
   'wsp.sso_no_break_glass': 'Geef eerst een beheerder noodtoegang (Ontwikkelaars), zodat iemand kan aanmelden als de identiteitsprovider uitvalt.',
   'wsp.sso_link_first': 'Koppel eerst een identiteit op uw beveiligingspagina, anders kunt u zelf niet aanmelden.',
+  'us.mfa_title': 'Aanmelden in twee stappen',
+  'us.mfa_status': 'Authenticator-apps: {n}. Resterende herstelcodes: {codes}.',
+  'us.mfa_none': 'Nog geen authenticator-app.',
+  'us.mfa_reset_help': 'Verwijdert de authenticator-apps en herstelcodes van {user} en meldt het account overal af. Waar een applicatie aanmelden in twee stappen vereist, voegt de gebruiker bij de volgende aanmelding een nieuwe app toe. Wordt gelogd.',
+  'us.mfa_reset_done': 'Aanmelden in twee stappen van {user} is gereset.',
+  'us.mfa_reason_needed': 'Geef een reden voor de reset.',
 };

package/src/builder/i18n/pt.ts

@@ -1870,4 +1870,10 @@ export const pt: BuilderMessages = {
   'wsp.sso_off': 'Os desenvolvedores do espaço de trabalho podem voltar a usar a senha do pgkiln.',
   'wsp.sso_no_break_glass': 'Primeiro dê acesso de emergência a um administrador (Desenvolvedores), para que alguém possa entrar se o provedor de identidade falhar.',
   'wsp.sso_link_first': 'Vincule primeiro uma identidade na sua página de segurança, ou você mesmo não conseguiria entrar.',
+  'us.mfa_title': 'Login em duas etapas',
+  'us.mfa_status': 'Aplicativos autenticadores: {n}. Códigos de recuperação restantes: {codes}.',
+  'us.mfa_none': 'Nenhum aplicativo autenticador ainda.',
+  'us.mfa_reset_help': 'Remove os aplicativos autenticadores e os códigos de recuperação de {user} e encerra todas as sessões. Onde um aplicativo exigir login em duas etapas, um novo aplicativo será adicionado no próximo login. Registrado.',
+  'us.mfa_reset_done': 'O login em duas etapas de {user} foi redefinido.',
+  'us.mfa_reason_needed': 'Informe um motivo para a redefinição.',
 };

package/src/builder/login-page.ts

@@ -1,12 +1,15 @@
 import type { FastifyInstance } from 'fastify';
 import { owner } from '../db.ts';
+import { APP_MFA, 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';
 
 // Application settings → Sign-in methods (migration 087): the application's
 // 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.
+// 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.
 
 interface AppRow {
   id: number;
@@ -15,6 +18,8 @@ interface AppRow {
   local_login: boolean;
   login_page: number | null;
   password_reset: boolean;
+  mfa: AppMfa;
+  mfa_roles: string[];
 }
 
 /** The fields in the settings form. */
@@ -41,14 +46,33 @@ export async function loginSettingsFields(a: AppRow) {
             ? html`Sent through mail service ${mail!.service} as ${mail!.from_address}.`
             : html`<strong>Not offered yet:</strong> the application needs an enabled mail service with a From address (Workspace utilities → Mail services).`}
           Only for the user directory's own passwords: not for LDAP, single sign-on, database accounts or custom authentication.</small></div>
+    </div>
+    <h3 id="two-factor">Two-factor sign-in</h3>
+    <div class="form-grid">
+      <div class="field"><label class="label" for="f_mfa">Second step</label>
+        <select id="f_mfa" name="mfa" aria-describedby="f_mfa_help">${(APP_MFA as string[]).map((m) => opt(m, MFA_LABELS[m as AppMfa], a.mfa))}</select>
+        <small class="help" id="f_mfa_help">After the password (or an LDAP directory), users give a code from an authenticator app or a recovery code. They add the app on <em>My account</em>, or while signing in when it is required. An identity provider asks for its own second factor. Accounts share their apps across applications.
+          ${secretKeyConfigured() ? '' : html`<strong>Not available yet:</strong> the server needs <code>PGKILN_SECRET_KEY</code> to keep the apps' secrets.`}</small></div>
+      <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>`;
 }
 
+const MFA_LABELS: Record<AppMfa, string> = { off: 'Off', optional: 'Optional (users may add an app)', required: 'Required', roles: 'Required for some roles' };
+
 /** Save them (with the rest of the settings form). */
 export async function saveLoginSettings(appId: string, b: Record<string, string | undefined>) {
   const page = b.login_page?.trim() ? Number(b.login_page) : null;
   if (page !== null && !(await owner.one('select 1 from meta.page where app_id = $1 and page_no = $2', [appId, page]))) throw new Error(`Login page: there is no page ${b.login_page}.`);
-  await owner.query('update meta.app set login_page = $2, password_reset = $3 where id = $1', [appId, page, b.password_reset === 'true']);
+  const mfa = (APP_MFA as string[]).includes(b.mfa ?? '') ? (b.mfa as AppMfa) : 'off';
+  const roles = [...new Set((b.mfa_roles ?? '').split(',').map((r) => r.trim().toLowerCase()).filter(Boolean))];
+  if (roles.some((r) => r.length > 100)) throw new Error('Two-factor sign-in: a role name is too long.');
+  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]);
 }
 
 export async function loginPageRoutes(app: FastifyInstance) {

package/src/builder/users.ts

@@ -4,6 +4,9 @@ import { owner } from '../db.ts';
 import { appAllowed } from './workspaces.ts';
 import { html, raw } from '../html.ts';
 import { accountSettings, clearAccountSettings, passwordProblem } from '../accounts.ts';
+import { accountCodesLeft, accountFactors, resetAccountFactors } from '../account-mfa.ts';
+import { icon } from '../icons.ts';
+import { clientIp, logActivity } from '../session.ts';
 import { loginMaxFailuresPerUser, loginWindowMinutes } from '../security.ts';
 import { acsUrl, metadataUrl, spEntityId } from '../saml.ts';
 import { discover, publicUrl, redirectUri } from '../sso.ts';
@@ -107,7 +110,8 @@ export async function usersRoutes(app: FastifyInstance) {
     const users = (
       await owner.query(
         `select a.*, coalesce((select jsonb_agg(jsonb_build_object('alias', p.alias, 'roles', aa.roles) order by p.alias)
-                                 from meta.app_access aa join meta.app p on p.id = aa.app_id where aa.account_id = a.id), '[]') as apps
+                                 from meta.app_access aa join meta.app p on p.id = aa.app_id where aa.account_id = a.id), '[]') as apps,
+                exists (select 1 from meta.account_factor f where f.account_id = a.id) as mfa
            from meta.account a
           where $1 = '' or a.username ilike '%' || $1 || '%' or a.display_name ilike '%' || $1 || '%' or a.email ilike '%' || $1 || '%'
           order by lower(a.username)
@@ -125,16 +129,17 @@ export async function usersRoutes(app: FastifyInstance) {
             <input type="search" name="q" value="${q}" placeholder="${tx('us.search_ph')}" aria-label="${tx('us.search_label')}"><button class="btn">${tx('us.search')}</button>
           </form>
           <div class="table-wrap"><table class="report report-reflow">
-            <thead><tr><th>${tx('us.username')}</th><th>${tx('us.name')}</th><th>${tx('us.apps_roles')}</th><th>${tx('us.signin')}</th><th>${tx('us.status')}</th></tr></thead>
+            <thead><tr><th>${tx('us.username')}</th><th>${tx('us.name')}</th><th>${tx('us.apps_roles')}</th><th>${tx('us.signin')}</th><th>${tx('mfa.column')}</th><th>${tx('us.status')}</th></tr></thead>
             <tbody>${users.length
               ? users.map((u) => html`<tr>
                   <td data-label="${tx('us.username')}"><a href="${BASE}/users/${u.id}">${u.username}</a></td>
                   <td data-label="${tx('us.name')}">${u.display_name ?? ''}${u.email ? html`<div class="muted">${u.email}</div>` : ''}</td>
                   <td data-label="${tx('us.applications')}">${u.apps.length ? u.apps.map((x: any) => html`<span class="chip">${x.alias}${x.roles.length ? `: ${x.roles.join(', ')}` : ''}</span> `) : html`<span class="muted">${tx('us.none')}</span>`}</td>
                   <td data-label="${tx('us.signin')}">${u.password_hash ? tx('us.password') : html`<span class="muted">${tx('us.no_password')}</span>`}</td>
+                  <td data-label="${tx('mfa.column')}">${u.mfa ? html`${icon('lock')} ${tx('mfa.on')}` : html`<span class="muted">${tx('mfa.off')}</span>`}</td>
                   <td data-label="${tx('us.status')}">${u.active ? tx('us.active') : html`<b>${tx('us.inactive')}</b>`}${u.last_login_at ? html`<div class="muted">${tx('us.last', { at: String(u.last_login_at).slice(0, 16) })}</div>` : ''}</td>
                 </tr>`)
-              : html`<tr><td colspan="5" class="empty">${tx('us.no_accounts')}</td></tr>`}</tbody>
+              : html`<tr><td colspan="6" class="empty">${tx('us.no_accounts')}</td></tr>`}</tbody>
           </table></div>`)}
         ${region(tx('us.create'), html`
           <form method="post" action="${BASE}/users">${csrf(s)}
@@ -215,6 +220,7 @@ export async function usersRoutes(app: FastifyInstance) {
       owner.query(`select id, name, alias from meta.app where id not in (select app_id from meta.app_access where account_id = $1) order by name`, [u.id]),
     ]);
     const hints = await roleHints([...access.rows.map((a) => a.app_id), ...apps.rows.map((a) => a.id)]);
+    const [factors, codes] = await Promise.all([accountFactors(u.id), accountCodesLeft(u.id)]);
     const main = html`
       <div class="title-row"><h1>${u.username}</h1></div>
       <div class="columns">
@@ -244,6 +250,13 @@ export async function usersRoutes(app: FastifyInstance) {
             <div class="buttons"><button class="btn">${tx('us.set_password')}</button>
               ${u.password_hash ? html`<button class="btn" name="remove" value="1" data-confirm="${tx('us.remove_confirm')}">${tx('us.remove_password')}</button>` : ''}</div>
           </form>
+          <h3 id="two-factor">${tx('us.mfa_title')}</h3>
+          <p>${factors.length ? tx('us.mfa_status', { n: factors.length, codes }) : tx('us.mfa_none')}</p>
+          ${factors.length
+            ? html`<form method="post" action="${BASE}/users/${u.id}/reset-2fa" class="danger-zone">${csrf(s)}
+                <div class="form-grid">${input('reason', tx('mfa.reason'), '', { required: true, help: tx('us.mfa_reset_help', { user: u.username }) })}</div>
+                <div class="buttons"><button class="btn btn-danger">${tx('mfa.reset_btn')}</button></div></form>`
+            : ''}
           <form method="post" action="${BASE}/users/${u.id}/delete" class="danger-zone">${csrf(s)}
             <button class="btn btn-danger" data-confirm="${tx('us.delete_confirm', { user: u.username })}">${tx('us.delete')}</button>
           </form>`)}
@@ -326,6 +339,24 @@ export async function usersRoutes(app: FastifyInstance) {
     return back(reply, s, `${BASE}/users/${req.params.id}`);
   });
 
+  // (sprint 130, SEC-3) remove an account's authenticator apps and recovery codes (a lost phone), with a reason
+  app.post(`${BASE}/users/:id(^\\d+$)/reset-2fa`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s) return;
+    const tx = tr(s);
+    const reason = String(req.body?.reason ?? '').trim().slice(0, 200);
+    const acc = await owner.one<{ id: number; username: string }>('select id, username from meta.account where id = $1', [req.params.id]);
+    if (!acc) return reply.code(404).send('Not found');
+    if (!reason) {
+      flash(s, tx('us.mfa_reason_needed'), 'error');
+      return back(reply, s, `${BASE}/users/${acc.id}#two-factor`);
+    }
+    await resetAccountFactors(acc.id);
+    await logActivity({ username: acc.username, event: '2fa_reset', ip: clientIp(req), detail: `by ${s.username}: ${reason}` });
+    flash(s, tx('us.mfa_reset_done', { user: acc.username }));
+    return back(reply, s, `${BASE}/users/${acc.id}`);
+  });
+
   app.post(`${BASE}/users/:id(^\\d+$)/delete`, async (req: Req, reply) => {
     const s = await developer(req, reply);
     if (!s) return;