pgkiln 0.63.0 → 0.65.0

package/src/account-mfa.ts

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

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

package/src/builder/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/api.ts

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

package/src/builder/components.ts

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

package/src/builder/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, EMAIL_CODE_MINUTES, EMAIL_CODES_PER_HOUR, type AppMfa } from '../account-mfa.ts';
 import { html, raw } from '../html.ts';
+import { secretKeyConfigured } from '../secrets.ts';
 import { back, BASE, developer, flash, type Req } from './ui.ts';
 
 // 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. (sprint 131) A code by e-mail.
 
 interface AppRow {
   id: number;
@@ -15,6 +18,9 @@ interface AppRow {
   local_login: boolean;
   login_page: number | null;
   password_reset: boolean;
+  mfa: AppMfa;
+  mfa_roles: string[];
+  mfa_email: boolean;
 }
 
 /** The fields in the settings form. */
@@ -41,14 +47,37 @@ 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>`;
+    </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 class="field"><span class="label" aria-hidden="true"></span><label class="check"><input type="checkbox" name="mfa_email" value="true"${a.mfa_email ? raw(' checked') : ''}> Offer a code by e-mail</label>
+        <small class="help">At the second step, users who have an authenticator app or a passkey may ask for a one-time code by e-mail instead (valid ${EMAIL_CODE_MINUTES} minutes, at most ${EMAIL_CODES_PER_HOUR} an hour). It is never someone's only factor: a user who must add one still adds an app or a passkey.
+          ${mailOk ? '' : html`<strong>Not offered yet:</strong> the application needs an enabled mail service with a From address.`}</small></div>
+    </div>
+    <p class="muted small">Users also add <strong>passkeys</strong> (fingerprint, face, PIN or a security key) on <em>My account</em> or while signing in; they need the application at a host name, not an IP address. To ask for the second step again before a page opens (step-up), give its authorization scheme <em>Second step within (minutes)</em> in Shared Components.</p>`;
 }
 
+const MFA_LABELS: Record<AppMfa, string> = { off: 'Off', optional: 'Optional (users may add an app)', required: 'Required', roles: 'Required for some roles' };
+
 /** 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, mfa_email = $6 where id = $1',
+    [appId, page, b.password_reset === 'true', mfa, roles, b.mfa_email === 'true']);
 }
 
 export async function loginPageRoutes(app: FastifyInstance) {

package/src/builder/rest-modules.ts

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

package/src/builder/security.ts

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

package/src/builder/shared.ts

@@ -156,7 +156,8 @@ export async function sharedRoutes(app: FastifyInstance) {
       rows[kind] = (await owner.query(`select * from ${COMPONENTS[kind].table} where app_id = $1 order by ${ORDER[kind] ?? 'name'}`, [a.id])).rows;
     const users = (
       await owner.query(
-        `select ac.id, ac.username, ac.display_name, ac.active, ac.last_login_at, aa.roles
+        `select ac.id, ac.username, ac.display_name, ac.active, ac.last_login_at, aa.roles,
+                exists (select 1 from meta.account_factor f where f.account_id = ac.id) as mfa
            from meta.app_access aa join meta.account ac on ac.id = aa.account_id
           where aa.app_id = $1 order by lower(ac.username)`,
         [a.id],
@@ -247,7 +248,7 @@ export async function sharedRoutes(app: FastifyInstance) {
           <button class="btn u-selfend">${tx('sc.save')}</button>
         </form>
         <p class="muted">${tx.rich('sc.access_help', { directory: html`<a href="${BASE}/users">${tx('sc.directory')}</a>`, app: html`<b>${a.name}</b>`, fn: html`<code>meta.has_role()</code>` })}</p>
-        <div class="table-wrap"><table class="report report-reflow"><thead><tr><th>${tx('sc.account')}</th><th>${tx('sc.roles_in_app')}</th><th>${tx('sc.last_signin')}</th><th></th></tr></thead><tbody>
+        <div class="table-wrap"><table class="report report-reflow"><thead><tr><th>${tx('sc.account')}</th><th>${tx('sc.roles_in_app')}</th><th>${tx('sc.last_signin')}</th><th>${tx('mfa.column')}</th><th></th></tr></thead><tbody>
           ${users.length
             ? users.map((u) => html`<tr>
                 <td data-label="${tx('sc.account')}"><a href="${BASE}/users/${u.id}">${u.username}</a>${u.display_name ? html` <span class="muted">${u.display_name}</span>` : ''}${u.active ? '' : html` <b>${tx('sc.inactive')}</b>`}</td>
@@ -255,9 +256,10 @@ export async function sharedRoutes(app: FastifyInstance) {
                   <input name="roles" value="${u.roles.join(', ')}" aria-label="${tx('sc.roles_of', { user: u.username })}" placeholder="${tx('sc.no_roles')}"><button class="btn">${tx('sc.save')}</button>
                   ${roleHintsHtml(appHints, tx('us.hints_add'), tx)}</form></td>
                 <td data-label="${tx('sc.last_signin')}">${u.last_login_at ? String(u.last_login_at).slice(0, 16) : '—'}</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=""><form method="post" action="${BASE}/apps/${a.id}/access/${u.id}/revoke">${csrf(s)}<button class="link-button" data-confirm="${tx('sc.revoke_confirm', { user: u.username, app: a.name })}">${tx('sc.revoke')}</button></form></td>
               </tr>`)
-            : html`<tr><td colspan="4" class="empty">${tx('sc.no_access')}</td></tr>`}
+            : html`<tr><td colspan="5" class="empty">${tx('sc.no_access')}</td></tr>`}
         </tbody></table></div>
         ${groupMap}
         <h3>${tx('sc.grant')}</h3>

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;