pgkiln 0.65.0 → 0.67.0

package/src/builder/instance.ts

@@ -1,5 +1,7 @@
 import type { FastifyInstance, FastifyReply } from 'fastify';
 import { html } from '../html.ts';
+import { attention, confirmKeyBackup, forgetAttention, instanceChecks, type Level } from '../instance-checks.ts';
+import { relyingParty } from '../webauthn.ts';
 import { configurationValue, CONFIGURATION, INSTANCE_SETTINGS, instanceSetting, origin, refreshInstanceSettings, saveInstanceSettings } from '../instance.ts';
 import { clientIp, logActivity, type Session } from '../session.ts';
 import { isAdmin } from './locks.ts';
@@ -20,6 +22,20 @@ async function adminOnly(s: Session, reply: FastifyReply) {
   return false;
 }
 
+const LEVEL_TEXT: Record<Level, string> = { ok: 'OK', info: 'Note', warning: 'Warning', error: 'Error' };
+
+/** (sprint 133, SEC-6) Lockout checks: what could keep people out later (src/instance-checks.ts). */
+async function checksRegion(s: Session, rpId: string) {
+  const checks = await instanceChecks(rpId);
+  const n = attention(checks);
+  return region('Lockout checks', html`<p class="muted u-mt0">${n ? `${n} of these need attention.` : 'Nothing needs attention.'}
+      The same checks run on the server with <code>pgkiln admin check</code>; <code>--url</code> shows which passkeys a new address would break.</p>
+    <ul class="hits findings">${checks.map((c) => html`<li class="finding-${c.level}"><strong>${c.title}</strong><span></span>
+      <span class="tag tag-${c.level}">${LEVEL_TEXT[c.level]}</span><span class="hit-snippet">${c.detail}</span>
+      ${c.key === 'key_backup' && c.level === 'warning' ? html`<form method="post" action="${BASE}/instance/key-backup" class="u-mt0">${csrf(s)}
+        <button class="btn btn-sm">I have a copy of this key</button></form>` : ''}</li>`)}</ul>`, '', 'lockout-checks');
+}
+
 const ORIGIN_TEXT = { builder: 'set here', environment: 'environment variable', default: 'default' } as const;
 
 export async function instanceRoutes(app: FastifyInstance) {
@@ -39,6 +55,7 @@ export async function instanceRoutes(app: FastifyInstance) {
               <small class="help">${x.help} In effect: <b>${instanceSetting(x.key)}</b> (${ORIGIN_TEXT[from]}; <code>${x.env}</code>, default ${x.default}).</small></div>`;
           })}</div>
           <div class="buttons"><button class="btn btn-hot">Save</button></div></form>`)}
+        ${await checksRegion(s, relyingParty(req).rpId)}
         ${await releaseCheckRegion(s)}
         ${await policyRegion(s)}
         ${region('Configuration', html`<p class="muted u-mt0">Environment variables of this server (chapter 1 of the guide). Secrets show only whether they are set.</p>
@@ -51,6 +68,16 @@ export async function instanceRoutes(app: FastifyInstance) {
     return send(reply, s, shell(s, 'Instance settings', crumbs, main));
   });
 
+  app.post(`${BASE}/instance/key-backup`, async (req: Req, reply) => {
+    const s = await developer(req, reply);
+    if (!s || !(await adminOnly(s, reply))) return;
+    const ok = await confirmKeyBackup(s.username!);
+    forgetAttention();
+    if (ok) await logActivity({ username: s.username, event: 'secret_key', ip: clientIp(req), detail: 'backup confirmed' });
+    flash(s, ok ? 'Backup of the instance key confirmed.' : 'PGKILN_SECRET_KEY is not set.', ok ? 'ok' : 'error');
+    return back(reply, s, `${BASE}/instance#lockout-checks`);
+  });
+
   app.post(`${BASE}/instance`, async (req: Req, reply) => {
     const s = await developer(req, reply);
     if (!s || !(await adminOnly(s, reply))) return;

package/src/builder/login-page.ts

@@ -23,7 +23,7 @@ interface AppRow {
   mfa_email: boolean;
 }
 
-/** The fields in the settings form. */
+/** The fields in the settings form: the sign-in page, and two-factor sign-in (each placed by the settings page). */
 export async function loginSettingsFields(a: AppRow) {
   const pages = (await owner.query<{ page_no: number; name: string; requires_auth: boolean }>(
     'select page_no, name, requires_auth from meta.page where app_id = $1 order by page_no', [a.id],
@@ -33,35 +33,33 @@ export async function loginSettingsFields(a: AppRow) {
        from meta.app_mail_service ams join meta.mail_service s on s.id = ams.service_id where ams.app_id = $1`, [a.id],
   );
   const mailOk = !!(mail?.enabled && mail.from_address?.trim());
+  const noMail = html`<strong>Not offered yet:</strong> the application needs an enabled mail service with a From address (Workspace utilities → Mail services).`;
   const opt = (v: string, label: string, cur: string) => html`<option value="${v}"${v === cur ? raw(' selected') : ''}>${label}</option>`;
   const current = a.login_page ? String(a.login_page) : '';
-  return html`<div class="form-grid">
+  const page = html`<div class="form-grid">
       <div class="field"><label class="label" for="f_login_page">Login page</label>
         <select id="f_login_page" name="login_page">${opt('', '- the built-in sign-in page -', current)}${pages.map((p) =>
           opt(String(p.page_no), `${p.page_no} ${p.name}${p.requires_auth ? ' (requires sign-in: not usable)' : ''}`, current))}</select>
-        <small class="help">A page of the application with a <em>Login</em> region replaces the built-in sign-in page (APEX: the login page). It must not require authentication; with page template <em>Minimal</em> it has no header and navigation.
+        <small class="help">A public page with a <em>Login</em> region (APEX: the login page); page template <em>Minimal</em> hides the header and navigation.
           <button class="link-button" formaction="${BASE}/apps/${a.id}/login-page">Create a login page</button></small></div>
-      <div class="field"><span class="label" aria-hidden="true"></span><label class="check"><input type="checkbox" name="password_reset" value="true"${a.password_reset ? raw(' checked') : ''}> Offer "Forgot password?"</label>
-        <small class="help">Users with a password and an e-mail address in the user directory get a link to choose a new password (single-use, valid for 30 minutes).
-          ${mailOk
-            ? 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="check"><input type="checkbox" name="password_reset" value="true"${a.password_reset ? raw(' checked') : ''}> Offer "Forgot password?"</label>
+      <small class="help">Users with a password and an e-mail address in the user directory get a single-use link, valid for 30 minutes, to choose a new password. Only for the user directory's own passwords.
+        ${mailOk ? html`Sent through mail service ${mail!.service} as ${mail!.from_address}.` : noMail}</small></div>`;
+  const twoFactor = html`<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.
+        <small class="help" id="f_mfa_help">After the password or an LDAP directory: a code from an authenticator app, a passkey or a recovery code, added on <em>My account</em> or while signing in.
           ${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>`;
+    <div class="field"><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">Users who already have an app or a passkey may get a one-time code by e-mail instead (valid ${EMAIL_CODE_MINUTES} minutes, at most ${EMAIL_CODES_PER_HOUR} an hour); never as their only factor.
+        ${mailOk ? '' : noMail}</small></div>
+    <p class="muted small">Passkeys need the application at a host name, not an IP address. Identity providers ask for their own second factor (see the provider's <em>Multi-factor sign-in</em>). To ask again before a page opens (step-up), give its authorization scheme <em>Second step within (minutes)</em> in Shared Components.</p>`;
+  return { page, twoFactor };
 }
 
 const MFA_LABELS: Record<AppMfa, string> = { off: 'Off', optional: 'Optional (users may add an app)', required: 'Required', roles: 'Required for some roles' };

package/src/builder/routes.ts

@@ -264,7 +264,16 @@ export async function builderRoutes(app: FastifyInstance) {
     const username = await resolveDeveloper(src, { ...result.identity, username: result.username, groups: result.groups });
     const dev = await owner.one<{ username: string; language: string | null }>('select username, language from meta.developer where username = $1', [username]);
     if (!dev) throw new SsoError('The developer was removed.');
-    return finishSignIn(req, reply, null, dev, { ws: null, workspace: '', next: safeNext(result.next), remember: false, weak: false, picked: null, detail: `builder sso:${p.name}`, sso: p.name });
+    // (sprint 132, SEC-4) the provider leaves the second step to pgkiln: as after a password (the trusted-browser
+    // cookie belongs to /builder and doesn't reach this callback, so the step is always asked); a developer without a
+    // factor signs in without __SSO, so a 2FA rule makes them add one (ui.ts)
+    if (p.local_second_step && (await hasFactor(dev.username))) {
+      const ns = await createSession(reply, null, BASE);
+      ns.state.__MFA = JSON.stringify({ u: dev.username, ws: null, w: '', next: safeNext(result.next), remember: false, weak: false, at: Date.now() });
+      await saveState(ns);
+      return reply.redirect(`${BASE}/login/2fa`, 303);
+    }
+    return finishSignIn(req, reply, null, dev, { ws: null, workspace: '', next: safeNext(result.next), remember: false, weak: false, picked: null, detail: `builder sso:${p.name}${result.mfa ? ' (mfa)' : ''}`, sso: p.local_second_step ? undefined : p.name });
   });
 
   // (sprint 128, SEC-2) signing in with a passkey alone: no user name, no password. The browser offers the
@@ -762,6 +771,7 @@ export async function builderRoutes(app: FastifyInstance) {
     if (!a) return reply.code(404).send('Not found');
     const providers = (await owner.query('select name, display_name, enabled from meta.auth_provider order by display_name')).rows;
     const directories = (await owner.query('select name, display_name, enabled from meta.ldap_directory order by display_name')).rows;
+    const signinFields = await loginSettingsFields(a);
     const lists = (await owner.query('select name from meta.list where app_id = $1 order by name', [a.id])).rows.map((r) => r.name as string);
     const listChoices = (v: string | null, none: string): [string, string][] => [['', none], ...lists.map((n): [string, string] => [n, n]), ...(v && !lists.includes(v) ? [[v, tx('st.missing', { name: v })] as [string, string]] : [])];
     // (sprint 74) tabs like APEX's Edit Application Definition and Security Attributes: every tab of the
@@ -822,15 +832,21 @@ export async function builderRoutes(app: FastifyInstance) {
             <h3>${tx('st.methods')}</h3>
             <div class="field"><label class="check"><input type="checkbox" name="local_login" value="true"${a.local_login ? raw(' checked') : ''}> ${tx('st.local')}</label></div>
             ${directories.length
-              ? directories.map((d) => html`<div class="field"><label class="check"><input type="checkbox" name="ldap_directories" value="${d.name}"${a.ldap_directories.includes(d.name) ? raw(' checked') : ''}> ${tx('st.ldap', { name: d.display_name })}${d.enabled ? '' : ` ${tx('st.disabled')}`}</label></div>`)
-              : html`<p class="muted">${tx.rich('st.no_ldap', { add: html`<a href="${BASE}/users/directories">${tx('st.add_one')}</a>` })}</p>`}
-            <small class="help">${tx('st.ldap_help')}</small>
-            <div class="form-grid">${input('session_group', tx('st.session_group'), a.session_group ?? '', { placeholder: tx('st.session_group_ph'), help: tx('st.session_group_help') })}</div>
-            ${await loginSettingsFields(a)}
-            <div class="form-grid">${input('remember_me_days', tx('st.remember'), a.remember_me_days ?? '', { type: 'number', placeholder: tx('st.remember_ph'), help: tx('st.remember_help') })}</div>
+              ? html`${directories.map((d) => html`<div class="field"><label class="check"><input type="checkbox" name="ldap_directories" value="${d.name}"${a.ldap_directories.includes(d.name) ? raw(' checked') : ''}> ${tx('st.ldap', { name: d.display_name })}${d.enabled ? '' : ` ${tx('st.disabled')}`}</label></div>`)}
+                <small class="help">${tx('st.ldap_help')}</small>`
+              : html`<p class="muted small">${tx.rich('st.no_ldap', { add: html`<a href="${BASE}/users/directories">${tx('st.add_one')}</a>` })}</p>`}
             ${providers.length
               ? providers.map((pr) => html`<div class="field"><label class="check"><input type="checkbox" name="sso_providers" value="${pr.name}"${a.sso_providers.includes(pr.name) ? raw(' checked') : ''}> ${tx('st.sso', { name: pr.display_name })}${pr.enabled ? '' : ` ${tx('st.disabled')}`}</label></div>`)
-              : html`<p class="muted">${tx.rich('st.no_sso', { add: html`<a href="${BASE}/users/providers">${tx('st.add_one')}</a>` })}</p>`}
+              : html`<p class="muted small">${tx.rich('st.no_sso', { add: html`<a href="${BASE}/users/providers">${tx('st.add_one')}</a>` })}</p>`}
+            <h3>${tx('st.signin_page')}</h3>
+            ${signinFields.page}
+            <h3>${tx('st.staying')}</h3>
+            <div class="form-grid">
+              ${input('remember_me_days', tx('st.remember'), a.remember_me_days ?? '', { type: 'number', placeholder: tx('st.remember_ph'), help: tx('st.remember_help') })}
+              ${input('session_group', tx('st.session_group'), a.session_group ?? '', { placeholder: tx('st.session_group_ph'), help: tx('st.session_group_help') })}
+            </div>
+            <h3 id="two-factor">${tx('st.two_factor')}</h3>
+            ${signinFields.twoFactor}
             `)}${end}
             ${panel('ui')}${region(tx('st.tab.ui'), html`
             <h3>${tx('st.theme')}</h3>

package/src/builder/users.ts

@@ -398,6 +398,9 @@ export async function usersRoutes(app: FastifyInstance) {
   });
 
   // ---------------------------------------------------------------- identity providers (OpenID Connect)
+  /** (134) the values a new provider counts as a second factor: amr "mfa" (Entra ID, Okta), Entra ID's and SAML's own */
+  const DEFAULT_MFA_VALUES = ['mfa', 'http://schemas.microsoft.com/claims/multipleauthn',
+    'urn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorContract', 'urn:oasis:names:tc:SAML:2.0:ac:classes:MobileTwoFactorUnregistered'];
   const providerForm = (pr: any, action: string, csrfField: ReturnType<typeof csrf>, isNew: boolean, tx: BuilderTranslate) => html`
     <form method="post" action="${action}">${csrfField}
       <div class="form-grid">
@@ -419,6 +422,16 @@ export async function usersRoutes(app: FastifyInstance) {
         <small class="help">${tx('idp.auto_create_help')}</small></div>
       <div class="field"><label class="check"><input type="checkbox" name="link_existing" value="true"${pr.link_existing ? raw(' checked') : ''}> ${tx('idp.link')}</label>
         <small class="help">${tx('idp.link_help')}</small></div>
+      <fieldset class="prop-group u-mt075"><legend>${tx('idp.mfa_title')}</legend>
+        <div class="field"><label class="check"><input type="checkbox" name="mfa_required" value="true"${pr.mfa_required ? raw(' checked') : ''}> ${tx('idp.mfa_required')}</label>
+          <small class="help">${tx('idp.mfa_required_help')}</small></div>
+        <div class="form-grid">
+          ${input('mfa_request', tx('idp.mfa_request'), pr.mfa_request ?? '', { help: tx('idp.mfa_request_help') })}
+          ${input('mfa_values', tx('idp.mfa_values'), (pr.mfa_values ?? DEFAULT_MFA_VALUES).join(' '), { help: tx('idp.mfa_values_help') })}
+        </div>
+        <div class="field"><label class="check"><input type="checkbox" name="local_second_step" value="true"${pr.local_second_step ? raw(' checked') : ''}> ${tx('idp.local_step')}</label>
+          <small class="help">${tx('idp.local_step_help')}</small></div>
+      </fieldset>
       <div class="field"><label class="check"><input type="checkbox" name="enabled" value="true"${pr.enabled !== false ? raw(' checked') : ''}> ${tx('idp.enabled')}</label></div>
       ${!isNew && pr.has_secret ? html`<div class="field"><label class="check"><input type="checkbox" name="remove_secret" value="true"> ${tx('idp.remove_secret')}</label></div>` : ''}
       <div class="buttons"><button class="btn btn-hot">${isNew ? tx('idp.add') : tx('us.save')}</button></div>
@@ -439,13 +452,17 @@ export async function usersRoutes(app: FastifyInstance) {
     b.auto_create === 'true', b.enabled === 'true',
     protocol === 'saml' ? b.idp_sso_url?.trim() || null : null, protocol === 'saml' ? pem(b.idp_cert) : null,
     b.link_existing === 'true',
+    // (sprint 132, SEC-4) multi-factor sign-in at the provider
+    b.mfa_required === 'true', b.mfa_request?.trim().replace(/\s+/g, ' ').slice(0, 500) || null,
+    words(b.mfa_values).length ? words(b.mfa_values) : DEFAULT_MFA_VALUES, b.local_second_step === 'true',
   ];
+  const words = (v: string | undefined) => [...new Set((v ?? '').split(/\s+/).filter(Boolean))].slice(0, 20);
 
   app.get(`${BASE}/users/providers`, async (req: Req, reply) => {
     const s = await administrator(req, reply, 'Identity providers');
     if (!s) return;
     const tx = tr(s);
-    const rows = (await owner.query(`select id, name, display_name, issuer, enabled, auto_create, link_existing,
+    const rows = (await owner.query(`select id, name, display_name, issuer, enabled, auto_create, link_existing, mfa_required,
         (select count(*) from meta.account_identity i where i.provider_id = p.id)::int as linked,
         (select string_agg(a.alias, ', ' order by a.alias) from meta.app a where p.name = any(a.sso_providers)) as apps
       from meta.auth_provider p order by display_name`)).rows;
@@ -460,7 +477,7 @@ export async function usersRoutes(app: FastifyInstance) {
             <td data-label="${tx('idp.issuer_col')}">${r.issuer}</td>
             <td data-label="${tx('idp.used_by')}">${r.apps ?? html`<span class="muted">${tx('idp.no_apps')}</span>`}</td>
             <td data-label="${tx('idp.linked')}">${r.linked}</td>
-            <td data-label="${tx('us.status')}">${r.enabled ? tx('idp.enabled_s') : html`<b>${tx('idp.disabled_s')}</b>`}${r.auto_create ? ` · ${tx('idp.auto_s')}` : ''}${r.link_existing ? ` · ${tx('idp.links_s')}` : ''}</td>
+            <td data-label="${tx('us.status')}">${r.enabled ? tx('idp.enabled_s') : html`<b>${tx('idp.disabled_s')}</b>`}${r.auto_create ? ` · ${tx('idp.auto_s')}` : ''}${r.link_existing ? ` · ${tx('idp.links_s')}` : ''}${r.mfa_required ? ` · ${tx('idp.mfa_s')}` : ''}</td>
           </tr>`) : html`<tr><td colspan="5" class="empty">${tx('idp.none')}</td></tr>`}</tbody></table></div>`)}
         ${region(tx('idp.add'), providerForm({}, `${BASE}/users/providers`, csrf(s), true, tx))}
       </div>`;
@@ -473,8 +490,9 @@ export async function usersRoutes(app: FastifyInstance) {
     const b = req.body ?? {};
     try {
       const r = await owner.one(
-        `insert into meta.auth_provider (name, display_name, issuer, client_id, scopes, username_claim, groups_claim, auto_create, enabled, idp_sso_url, idp_cert, link_existing, protocol, client_secret)
-         values ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14) returning id`,
+        `insert into meta.auth_provider (name, display_name, issuer, client_id, scopes, username_claim, groups_claim, auto_create, enabled, idp_sso_url, idp_cert, link_existing,
+                                         mfa_required, mfa_request, mfa_values, local_second_step, protocol, client_secret)
+         values ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17, $18) returning id`,
         [b.name?.trim().toLowerCase(), ...providerValues(b, protocolOf(b.protocol), b.name?.trim().toLowerCase() ?? ''), protocolOf(b.protocol), b.client_secret || null],
       );
       flash(s, tr(s)('idp.added'));
@@ -523,7 +541,8 @@ export async function usersRoutes(app: FastifyInstance) {
       await owner.query(
         `update meta.auth_provider set display_name = $2, issuer = $3, client_id = $4, scopes = $5, username_claim = $6,
                 groups_claim = $7, auto_create = $8, enabled = $9, idp_sso_url = $10, idp_cert = $11, link_existing = $12,
-                client_secret = case when $14 then null when $13::text is null then client_secret else $13 end
+                mfa_required = $13, mfa_request = $14, mfa_values = $15, local_second_step = $16,
+                client_secret = case when $18 then null when $17::text is null then client_secret else $17 end
           where id = $1`,
         [req.params.id, ...providerValues(b, current.protocol, current.name), b.client_secret || null, b.remove_secret === 'true'],
       );

package/src/builder/workspace-home.ts

@@ -9,6 +9,7 @@ import { isAdmin } from './locks.ts';
 import { back, BASE, csrf, developer, flash, region, send, shell, type Req } from './ui.ts';
 import { currentWorkspace, inWorkspaceSql, workspaceAdmin } from './workspaces.ts';
 import { teamHomeBlock } from './team.ts';
+import { attentionCount } from '../instance-checks.ts';
 import { tr } from './i18n.ts';
 
 // (sprint 109, WS-1) The Workspace home (APEX: the workspace home page), the page the builder opens after
@@ -112,7 +113,12 @@ async function systemMessage(s: Session, admin: boolean) {
           ? html`<button class="btn btn-sm" name="check" value="now">${icon('refresh')} ${tx('wh.check_now')}</button><button class="btn btn-sm" name="check" value="off">${tx('wh.turn_off')}</button>`
           : html`<button class="btn btn-sm" name="check" value="on">${tx('wh.check_on')}</button>`}</div></form>`
     : '';
-  return region(tx('wh.system'), html`${body}${admins}`, '', 'system-message');
+  // (sprint 133, SEC-6) administrators hear about lockout risks here, not only on Instance settings
+  const lockout = admin ? await attentionCount() : 0;
+  const checks = lockout
+    ? html`<p class="alert alert-warning" role="status">${icon('alert')} ${tx('wh.lockout', { count: lockout })} <a href="${BASE}/instance#lockout-checks">${tx('wh.lockout_open')}</a></p>`
+    : '';
+  return region(tx('wh.system'), html`${checks}${body}${admins}`, '', 'system-message');
 }
 
 /** (Instance settings page) the release check: on, off, or as the environment says. */

package/src/cli/main.ts

@@ -471,24 +471,35 @@ const COMMANDS: Record<string, Command> = {
   },
   // (sprint 126, SEC-6) lockout recovery on the server, when nobody can sign in to the builder
   admin: {
-    usage: 'pgkiln admin reset-2fa <developer> | set-2fa-policy off|admins|all | builder-sign-in password [options]',
-    summary: 'lockout recovery: reset a developer\'s two-factor sign-in, set the two-factor policy, allow the password again',
+    usage: 'pgkiln admin reset-2fa <developer> | set-2fa-policy off|admins|all | builder-sign-in password | rotate-key | key-backed-up | check [options]',
+    summary: 'lockout recovery and checks: two-factor reset and policy, the builder password, the instance key',
     details:
       'pgkiln admin reset-2fa <developer> [--reason <text>]\n' +
       'pgkiln admin set-2fa-policy off|admins|all [--grace <days>]\n' +
-      'pgkiln admin builder-sign-in password\n\n' +
+      'pgkiln admin builder-sign-in password\n' +
+      'pgkiln admin rotate-key [--dry-run]\n' +
+      'pgkiln admin key-backed-up\n' +
+      'pgkiln admin check [--url <public url>]\n\n' +
       "reset-2fa removes the developer's authenticator apps and recovery codes and ends their builder\n" +
       'sessions; they sign in with the password and set up an app again. set-2fa-policy off always works\n' +
       "(and clears the workspaces' own two-factor rules); admins and all need at least two administrators\n" +
       'with two-factor sign-in (or every one, when there are fewer). builder-sign-in password turns off the\n' +
       "workspaces' single sign-on rule, for when the identity provider fails and no break-glass administrator\n" +
-      'can sign in. All are written to the activity log and mailed to the administrators.',
-    options: { reason: { type: 'string' }, grace: { type: 'string' } },
+      'can sign in. All are written to the activity log and mailed to the administrators.\n\n' +
+      'rotate-key re-encrypts every stored secret (authenticator apps, web credentials, mail and AI keys)\n' +
+      'from PGKILN_OLD_SECRET_KEY to PGKILN_SECRET_KEY in one transaction; stop the servers first and start\n' +
+      'them with the new key. key-backed-up records that the current key is kept outside the server.\n' +
+      'check prints the lockout checks of Instance settings (instance key, clock, passkey domain,\n' +
+      'break-glass administrators); --url shows which passkeys a move to that address would break.\n' +
+      'Exit code 1 when a check needs attention.',
+    options: { reason: { type: 'string' }, grace: { type: 'string' }, 'dry-run': { type: 'boolean' }, url: { type: 'string' } },
     optionHelp: [
       ['--reason <text>', 'reset-2fa: why (in the activity log and the mail)'],
       ['--grace <days>', 'set-2fa-policy: days developers have to set up an app (0 to 90, default 7)'],
+      ['--dry-run', 'rotate-key: count what would be re-encrypted, change nothing'],
+      ['--url <url>', 'check: the public address to check passkeys against (default PUBLIC_URL)'],
     ],
-    positionals: [2, 2],
+    positionals: [1, 2],
     async run(v, [action, arg]) {
       process.env.RUNTIME_DATABASE_URL ??= process.env.DATABASE_URL; // the CLI runs as the owner
       const mfa = await import('../mfa.ts');
@@ -497,6 +508,7 @@ const COMMANDS: Record<string, Command> = {
       const by = `pgkiln admin (${userInfo().username})`;
       try {
         if (action === 'reset-2fa') {
+          if (!arg) throw new UsageError('reset-2fa takes a developer');
           const reason = String(v.reason ?? 'command line').slice(0, 200);
           if (!(await mfa.resetFactors(arg))) throw new Error(`no developer ${arg}`);
           await logActivity({ username: arg, event: '2fa_reset', ip: 'cli', detail: `${arg}: ${reason} (${by})` });
@@ -530,7 +542,46 @@ const COMMANDS: Record<string, Command> = {
           out(`Developers may sign in with the pgkiln password again; ${cleared} workspace(s) no longer require single sign-on.${sent ? ` ${sent} administrator(s) told by mail.` : ''}\n`);
           return EXIT.ok;
         }
-        throw new UsageError(`unknown action ${action}: use reset-2fa, set-2fa-policy or builder-sign-in`);
+        // (sprint 133, SEC-6) the instance key and the lockout checks
+        if (action === 'rotate-key' || action === 'key-backed-up' || action === 'check') {
+          if (arg !== undefined) throw new UsageError(`${action} takes no argument`);
+          const checks = await import('../instance-checks.ts');
+          if (action === 'rotate-key') {
+            const oldKey = process.env.PGKILN_OLD_SECRET_KEY ?? '';
+            const newKey = process.env.PGKILN_SECRET_KEY ?? '';
+            if (!oldKey) throw new UsageError('set PGKILN_OLD_SECRET_KEY to the key the secrets are stored with, and PGKILN_SECRET_KEY to the new one');
+            const dry = !!v['dry-run'];
+            const counts = await checks.rotateKey(oldKey, newKey, { dryRun: dry });
+            const rotated = counts.reduce((n, c) => n + c.rotated, 0);
+            for (const c of counts) out(`  ${c.schema}.${c.table}.${c.column}: ${c.rotated} ${dry ? 'to re-encrypt' : 're-encrypted'}${c.already ? `, ${c.already} already with the new key` : ''}\n`);
+            if (dry) {
+              out(`Dry run: ${rotated} secret(s) would be re-encrypted; nothing changed.\n`);
+              return EXIT.ok;
+            }
+            await logActivity({ event: 'secret_key', ip: 'cli', detail: `rotated, ${rotated} secret(s) re-encrypted (${by})` });
+            const sent = await mfa.notifyMfa(await mfa.adminEmails(), 'pgkiln: the instance key was rotated',
+              `${by} re-encrypted ${rotated} stored secret(s) with a new PGKILN_SECRET_KEY on the server. Keep a copy of the new key and confirm it on Instance settings.`);
+            out(`${rotated} secret(s) re-encrypted with the new key. Start the servers with it, keep a copy, then run 'pgkiln admin key-backed-up'.${sent ? ` ${sent} administrator(s) told by mail.` : ''}\n`);
+            return EXIT.ok;
+          }
+          if (action === 'key-backed-up') {
+            if (!(await checks.confirmKeyBackup(by))) throw new Error('PGKILN_SECRET_KEY is not set (at least 32 characters)');
+            await logActivity({ event: 'secret_key', ip: 'cli', detail: `backup confirmed (${by})` });
+            out('Backup of the instance key confirmed.\n');
+            return EXIT.ok;
+          }
+          let rpId: string | null = null;
+          const url = (v.url as string | undefined) ?? process.env.PUBLIC_URL;
+          if (url) {
+            if (!URL.canParse(url) || !/^https?:$/.test(new URL(url).protocol)) throw new UsageError('--url takes an http(s) address');
+            rpId = (await import('../webauthn.ts')).rpIdOf(new URL(url).origin);
+          }
+          const list = await checks.instanceChecks(rpId);
+          for (const c of list) out(`${c.level.toUpperCase().padEnd(7)}  ${c.title}\n         ${c.detail}\n`);
+          if (!rpId) out('(passkey domain not checked: set PUBLIC_URL or pass --url)\n');
+          return checks.attention(list) ? EXIT.differences : EXIT.ok;
+        }
+        throw new UsageError(`unknown action ${action}: use reset-2fa, set-2fa-policy, builder-sign-in, rotate-key, key-backed-up or check`);
       } finally {
         await closePools();
       }