pgkiln 0.63.0 → 0.65.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/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)); 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; 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,6 +300,11 @@ 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.
+- (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
   table or column refuses the deployment instead of failing at run time.

package/docs/guide/08-security.md

@@ -410,6 +410,79 @@ 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 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:
+
+- 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
+
+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
 
 - **Brute force**: after 5 failed attempts for a username (or 50 from one IP address) within 15
@@ -418,13 +491,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 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.
 
 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
@@ -440,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:
 
@@ -643,4 +718,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,13 @@ 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 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;
+                           (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
@@ -171,8 +178,13 @@ 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; (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.63.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.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/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.