pgkiln 0.65.0 → 0.67.0

package/src/instance-checks.ts

@@ -0,0 +1,260 @@
+import { owner } from './db.ts';
+import { breakGlassAdmins } from './devsso.ts';
+import { mfaPolicy } from './mfa.ts';
+import { remoteClockOffset } from './release-check.ts';
+import { rpIdOf } from './webauthn.ts';
+import { decryptSecret, encryptSecret, keyFingerprint, secretKeyConfigured } from './secrets.ts';
+
+// (sprint 133, SEC-6) Lockout checks of the instance: what could keep developers or application users out
+// later, found before it happens. Shown on Instance settings (administrators), counted on the Workspace home
+// and printed by `pgkiln admin check`.
+//
+//  - Instance key: secrets stored without PGKILN_SECRET_KEY, secrets the current key can't decrypt (the key
+//    changed), and whether an administrator confirmed a backup of this key (meta.setting secret_key_backup,
+//    by fingerprint, so a new key asks again). Authenticator apps are encrypted with it; passkeys and the
+//    hashed recovery codes are not.
+//  - Clock: TOTP codes allow one 30-second step either side, so the server's clock is compared with the
+//    database's and, when the release check is on, with GitHub's.
+//  - Passkey domain: passkeys made for another RP ID than the one PUBLIC_URL (or the given address) gives,
+//    and how many people have no other factor left. `pgkiln admin check --url` asks before a move.
+//  - Break-glass: a workspace that requires single sign-on needs a break-glass administrator, and one with
+//    a second factor when the policy requires it.
+//
+// rotateKey() re-encrypts every stored secret from an old key to a new one in one transaction.
+
+export type Level = 'ok' | 'info' | 'warning' | 'error';
+
+export interface Check {
+  key: 'secret_key' | 'key_backup' | 'clock' | 'passkey_domain' | 'break_glass';
+  level: Level;
+  title: string;
+  detail: string;
+}
+
+/** Every column that holds a secret encrypted with the instance key ("v1:…"). */
+export interface SecretColumn {
+  schema: string;
+  table: string;
+  column: string;
+}
+
+export async function encryptedColumns(): Promise<SecretColumn[]> {
+  return (await owner.query<SecretColumn>(
+    `select table_schema as schema, table_name as table, column_name as column from information_schema.columns
+      where table_schema = 'meta' and data_type = 'text'
+        and (column_name like '%\\_enc' or (table_name = 'push_key' and column_name = 'private_key'))
+      order by 2, 3`)).rows;
+}
+
+const quoteIdent = (s: string) => `"${s.replace(/"/g, '""')}"`;
+const tableOf = (c: SecretColumn) => `${quoteIdent(c.schema)}.${quoteIdent(c.table)}`;
+
+/** Stored secrets per column, and how many the given key (default: the server's) can't decrypt. */
+export async function secretStatus(withKey?: string) {
+  const out: (SecretColumn & { stored: number; unreadable: number })[] = [];
+  const usable = (withKey ?? process.env.PGKILN_SECRET_KEY ?? '').length >= 32;
+  for (const c of await encryptedColumns()) {
+    const rows = (await owner.query<{ v: string }>(`select ${quoteIdent(c.column)} as v from ${tableOf(c)} where ${quoteIdent(c.column)} is not null`)).rows;
+    let unreadable = 0;
+    for (const r of rows) {
+      try {
+        if (!usable) throw new Error();
+        decryptSecret(r.v, withKey);
+      } catch {
+        unreadable++;
+      }
+    }
+    if (rows.length) out.push({ ...c, stored: rows.length, unreadable });
+  }
+  return out;
+}
+
+export interface KeyBackup {
+  fingerprint: string;
+  by: string;
+  at: string;
+}
+
+export async function keyBackup(): Promise<KeyBackup | null> {
+  const v = (await owner.one<{ value: string }>(`select value from meta.setting where name = 'secret_key_backup'`))?.value;
+  try {
+    const b = v ? JSON.parse(v) : null;
+    return b && typeof b.fingerprint === 'string' ? (b as KeyBackup) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** An administrator says the current key is kept somewhere safe (false: no key configured). */
+export async function confirmKeyBackup(by: string) {
+  const fingerprint = keyFingerprint();
+  if (!fingerprint) return false;
+  const value = JSON.stringify({ fingerprint, by, at: new Date().toISOString() });
+  await owner.query(`insert into meta.setting (name, value) values ('secret_key_backup', $1) on conflict (name) do update set value = excluded.value`, [value]);
+  return true;
+}
+
+/** Milliseconds this server's clock is ahead of the database's (half the round trip taken off). */
+export async function databaseClockOffset() {
+  const t0 = Date.now();
+  const r = await owner.one<{ ms: string }>(`select (extract(epoch from clock_timestamp()) * 1000)::bigint as ms`);
+  const t1 = Date.now();
+  return Math.round((t0 + t1) / 2 - Number(r!.ms));
+}
+
+export const CLOCK_WARN_MS = 10_000;
+export const CLOCK_ERROR_MS = 30_000;
+
+export interface PasskeyDomain {
+  rpId: string;
+  who: 'developers' | 'app users';
+  passkeys: number;
+  people: number;
+  /** people with no authenticator app and no passkey for the current RP ID */
+  stranded: number;
+}
+
+/** Passkeys made for another RP ID than rpId. */
+export async function passkeysElsewhere(rpId: string): Promise<PasskeyDomain[]> {
+  const part = (table: string, key: string, who: string) => `
+    select '${who}'::text as who, coalesce(f.rp_id, '(unknown)') as "rpId", count(*)::int as passkeys, count(distinct f.${key})::int as people,
+           count(distinct f.${key}) filter (where not exists (select 1 from meta.${table} o where o.${key} = f.${key}
+             and (o.kind = 'totp' or (o.kind = 'passkey' and o.rp_id = $1))))::int as stranded
+      from meta.${table} f where f.kind = 'passkey' and f.rp_id is distinct from $1 group by f.rp_id`;
+  return (await owner.query<PasskeyDomain>(`${part('developer_factor', 'username', 'developers')} union all ${part('account_factor', 'account_id', 'app users')} order by 2, 1`, [rpId])).rows;
+}
+
+const plural = (n: number, one: string, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+/** All checks; rpId: the RP ID passkeys must have (from PUBLIC_URL or the request; null skips that check). */
+export async function instanceChecks(rpId: string | null): Promise<Check[]> {
+  const checks: Check[] = [];
+
+  // the instance key
+  const status = await secretStatus();
+  const stored = status.reduce((n, s) => n + s.stored, 0);
+  const unreadable = status.filter((s) => s.unreadable);
+  if (!secretKeyConfigured())
+    checks.push(stored
+      ? { key: 'secret_key', level: 'error', title: 'Instance key missing', detail: `${plural(stored, 'secret')} are stored (${status.map((s) => `${s.table}.${s.column}`).join(', ')}), but PGKILN_SECRET_KEY is not set: authenticator apps, web credentials and mail passwords don't work. Set the key they were stored with.` }
+      : { key: 'secret_key', level: 'info', title: 'No instance key', detail: 'PGKILN_SECRET_KEY is not set, so nothing can be stored encrypted (authenticator apps, web credentials, mail and AI keys). Set one of at least 32 characters, e.g. the output of openssl rand -base64 32.' });
+  else if (unreadable.length)
+    checks.push({ key: 'secret_key', level: 'error', title: 'Secrets the instance key can\'t decrypt', detail: `${unreadable.map((s) => `${s.table}.${s.column}: ${s.unreadable} of ${s.stored}`).join('; ')}. PGKILN_SECRET_KEY changed without pgkiln admin rotate-key: set the old key again and rotate, or enter those secrets again (developers set up their authenticator app again after a reset).` });
+  else checks.push({ key: 'secret_key', level: 'ok', title: 'Instance key', detail: stored ? `PGKILN_SECRET_KEY decrypts all ${plural(stored, 'stored secret')}.` : 'PGKILN_SECRET_KEY is set; no secrets are stored yet.' });
+
+  if (secretKeyConfigured()) {
+    const backup = await keyBackup();
+    const fp = keyFingerprint()!;
+    checks.push(backup?.fingerprint === fp
+      ? { key: 'key_backup', level: 'ok', title: 'Instance key backed up', detail: `${backup.by} confirmed a copy of the key with fingerprint ${fp} on ${backup.at.slice(0, 10)}.` }
+      : { key: 'key_backup', level: 'warning', title: 'Instance key not confirmed as backed up', detail: `${backup ? 'The key changed since the last confirmation. ' : ''}Keep a copy of PGKILN_SECRET_KEY (fingerprint ${fp}) outside this server, e.g. in a password manager: without it the authenticator apps and stored credentials are lost. Passkeys and recovery codes keep working.` });
+  }
+
+  // the clock
+  const db = await databaseClockOffset();
+  const remote = remoteClockOffset();
+  const worst = Math.max(Math.abs(db), Math.abs(remote?.offsetMs ?? 0));
+  const s = (ms: number) => (Math.abs(ms) < 50 ? '0.0 s' : `${ms > 0 ? '+' : '−'}${(Math.abs(ms) / 1000).toFixed(1)} s`);
+  const seen = `database (${s(db)})${remote ? ` and GitHub's (${s(remote.offsetMs)}, at the release check)` : ''}`;
+  checks.push(worst >= CLOCK_ERROR_MS
+    ? { key: 'clock', level: 'error', title: 'Server clock is off', detail: `This server's clock differs from the ${seen}. Authenticator codes fail beyond about 30 seconds: synchronise the clock (NTP, e.g. systemd-timesyncd or chrony).` }
+    : worst >= CLOCK_WARN_MS
+      ? { key: 'clock', level: 'warning', title: 'Server clock drifts', detail: `This server's clock differs from the ${seen}. Authenticator codes fail beyond about 30 seconds: check the time synchronisation (NTP).` }
+      : { key: 'clock', level: 'ok', title: 'Clock', detail: `This server's clock agrees with the ${seen}.` });
+
+  // passkeys of another domain
+  if (rpId) {
+    const away = await passkeysElsewhere(rpId);
+    const strandedTotal = away.reduce((n, a) => n + a.stranded, 0);
+    checks.push(away.length
+      ? { key: 'passkey_domain', level: strandedTotal ? 'warning' : 'info', title: `Passkeys for another domain than ${rpId}`,
+          detail: `${away.map((a) => `${a.rpId}: ${plural(a.passkeys, 'passkey')} of ${plural(a.people, a.who === 'developers' ? 'developer' : 'app user')}${a.stranded ? `, ${a.stranded} with no other factor` : ''}`).join('; ')}. Passkeys work only on the domain they were made for${strandedTotal ? ': people with no other factor need a recovery code or a reset' : ''}. Set PUBLIC_URL (or PGKILN_RP_ID) back, or have them add passkeys again.` }
+      : { key: 'passkey_domain', level: 'ok', title: 'Passkey domain', detail: `Every passkey is for ${rpId}.` });
+  }
+
+  // break-glass administrators
+  const ssoOnly = (await owner.query<{ name: string }>(`select name from meta.workspace where sso_only order by name`)).rows.map((r) => r.name);
+  if (ssoOnly.length) {
+    const glass = await breakGlassAdmins();
+    const policy = (await mfaPolicy()).policy;
+    const withFactor = glass.length
+      ? (await owner.query<{ username: string }>(`select distinct username from meta.developer_factor where username = any($1)`, [glass])).rows.map((r) => r.username)
+      : [];
+    checks.push(!glass.length
+      ? { key: 'break_glass', level: 'error', title: 'No break-glass administrator', detail: `${ssoOnly.join(', ')} require${ssoOnly.length === 1 ? 's' : ''} single sign-on and no administrator may use the pgkiln password: when the identity provider fails, only pgkiln admin builder-sign-in password on the server gets anyone in. Mark an administrator as break-glass on Developers.` }
+      : policy !== 'off' && withFactor.length < glass.length
+        ? { key: 'break_glass', level: 'warning', title: 'Break-glass administrator without a second factor', detail: `${glass.filter((g) => !withFactor.includes(g)).join(', ')} must use two-factor sign-in but has no authenticator app or passkey: add one on Security before it is needed.` }
+        : { key: 'break_glass', level: 'ok', title: 'Break-glass administrators', detail: `${glass.join(', ')} may sign in with the pgkiln password when the identity provider fails (${ssoOnly.join(', ')} require${ssoOnly.length === 1 ? 's' : ''} single sign-on).` });
+  }
+  return checks;
+}
+
+/** How many checks need attention (warnings and errors). */
+export const attention = (checks: Check[]) => checks.filter((c) => c.level === 'warning' || c.level === 'error').length;
+
+let cached: { at: number; count: number } | null = null;
+
+/** (Workspace home) how many checks need attention, at most five minutes old; never throws. */
+export async function attentionCount(): Promise<number> {
+  if (cached && Date.now() - cached.at < 300_000) return cached.count;
+  try {
+    const pub = process.env.PUBLIC_URL;
+    const rpId = pub && URL.canParse(pub) ? rpIdOf(new URL(pub).origin) : null;
+    cached = { at: Date.now(), count: attention(await instanceChecks(rpId)) };
+  } catch {
+    return cached?.count ?? 0;
+  }
+  return cached.count;
+}
+
+/** Forget the cached count (after a change on Instance settings, and in tests). */
+export const forgetAttention = () => {
+  cached = null;
+};
+
+export class RotateError extends Error {}
+
+/**
+ * Re-encrypt every stored secret from oldKey to newKey, in one transaction. A value the new key already
+ * decrypts is left alone (a second run after a partial restart changes nothing); a value neither key
+ * decrypts stops the rotation and nothing is changed. dryRun: count only.
+ */
+export async function rotateKey(oldKey: string, newKey: string, { dryRun = false, columns }: { dryRun?: boolean; columns?: SecretColumn[] } = {}) {
+  if (oldKey.length < 32 || newKey.length < 32) throw new RotateError('both keys need at least 32 characters');
+  if (oldKey === newKey) throw new RotateError('the new key is the old key');
+  const cols = columns ?? (await encryptedColumns());
+  return owner.tx(async (c) => {
+    const counts: (SecretColumn & { rotated: number; already: number })[] = [];
+    const failed: string[] = [];
+    for (const col of cols) {
+      const rows = (await c.query<{ ctid: string; v: string }>(
+        `select ctid::text as ctid, ${quoteIdent(col.column)} as v from ${tableOf(col)} where ${quoteIdent(col.column)} is not null for update`)).rows;
+      let rotated = 0;
+      let already = 0;
+      for (const r of rows) {
+        let plain: string;
+        try {
+          decryptSecret(r.v, newKey);
+          already++;
+          continue;
+        } catch {
+          // not yet rotated
+        }
+        try {
+          plain = decryptSecret(r.v, oldKey);
+        } catch {
+          failed.push(`${col.schema}.${col.table}.${col.column}`);
+          continue;
+        }
+        if (!dryRun) await c.query(`update ${tableOf(col)} set ${quoteIdent(col.column)} = $1 where ctid = $2::tid`, [encryptSecret(plain, newKey), r.ctid]);
+        rotated++;
+      }
+      if (rows.length) counts.push({ ...col, rotated, already });
+    }
+    if (failed.length) {
+      const by = [...new Set(failed)].map((f) => `${f} (${failed.filter((x) => x === f).length})`).join(', ');
+      throw new RotateError(`secrets that neither key decrypts: ${by}; nothing was changed`);
+    }
+    return counts;
+  });
+}

package/src/instance.ts

@@ -120,7 +120,7 @@ export const CONFIGURATION: readonly { env: string; secret?: boolean; default: s
   { env: 'BACKGROUND_PROCESSES', default: 'on', help: 'This server runs background execution chains' },
   { env: 'PGKILN_REST_ALLOWED_HOSTS', default: '(none)', help: 'Hosts REST data sources may call' },
   { env: 'PGKILN_REST_PRIVATE_HOSTS', default: '(none)', help: 'Hosts that may resolve to private addresses' },
-  { env: 'PGKILN_SECRET_KEY', secret: true, default: '(none)', help: 'Encrypts web credential secrets and AI keys' },
+  { env: 'PGKILN_SECRET_KEY', secret: true, default: '(none)', help: 'Encrypts authenticator apps, web credential secrets, mail and AI keys (pgkiln admin rotate-key changes it)' },
   { env: 'API_URL', default: '(none)', help: 'PostgREST address (REST API pages)' },
   { env: 'API_JWT_SECRET', secret: true, default: '(none)', help: 'Signs REST API tokens' },
   { env: 'ANTHROPIC_API_KEY', secret: true, default: '(none)', help: 'Default key of Claude AI services' },

package/src/release-check.ts

@@ -29,6 +29,12 @@ export interface Release {
 
 let cache: { at: number; release: Release | null; error: string | null } | null = null;
 let inflight: Promise<void> | null = null;
+let remoteClock: { at: number; offsetMs: number } | null = null;
+
+/** How far this server's clock was ahead of GitHub's at the last release check (null: not asked yet). */
+export function remoteClockOffset() {
+  return remoteClock;
+}
 
 /** The address asked (PGKILN_RELEASE_URL for tests and mirrors; http(s) only). */
 function releaseUrl() {
@@ -91,6 +97,9 @@ async function fetchLatest(): Promise<Release | null> {
     redirect: 'error',
     signal: AbortSignal.timeout(TIMEOUT_MS),
   });
+  // (sprint 133, SEC-6) GitHub's clock, for the clock check on Instance settings (the header has whole seconds)
+  const date = Date.parse(res.headers.get('date') ?? '');
+  if (!Number.isNaN(date)) remoteClock = { at: Date.now(), offsetMs: Date.now() - date };
   if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`);
   const reader = res.body.getReader();
   const chunks: Uint8Array[] = [];
@@ -136,4 +145,5 @@ export function cachedRelease() {
 /** Forget the cache (tests). */
 export function resetReleaseCache() {
   cache = null;
+  remoteClock = null;
 }

package/src/runtime/routes.ts

@@ -49,7 +49,7 @@ import { chrome, dialogClosePage, languagePicker, renderPage } from './render.ts
 import { LOGIN_ERROR, LOGIN_USER, safeNext, signInForm } from './signin.ts';
 import { passwordResetRoutes } from './password-reset.ts';
 import { passwordSignIn, twoStepRoutes } from './two-step.ts';
-import { carriesSecondStep } from '../account-mfa.ts';
+import { carriesSecondStep, markSecondStep } from '../account-mfa.ts';
 import { devbarOf, devbarRoutes, sessionDebugLevel } from './devbar.ts';
 import { availabilityRefusal } from './availability.ts';
 import { feedbackRoutes } from './feedback.ts';
@@ -141,6 +141,8 @@ export async function signIn(req: FastifyRequest, reply: FastifyReply, a: App, o
   // (067) session sharing: the session belongs to the group's shared sign-in (a new one after a real sign-in)
   const shared = opts.shared ?? (await issueShared(req, reply, a, username, { groups: opts.groups, method: opts.method }));
   if (shared) s.state.__SHARED = shared;
+  // (sprint 132) how the session signed in: a step-up after "sso:<provider>" goes back to that provider
+  if (opts.method) s.state.__SIGNIN = opts.method;
   await saveState(s);
 
   // the application processes "after login", then (102) the application computations "after authentication"
@@ -162,6 +164,9 @@ export async function signIn(req: FastifyRequest, reply: FastifyReply, a: App, o
   return s;
 }
 
+/** (sprint 132) Set by the runtime routes: a step-up through an identity provider (two-step.ts). */
+export let ssoStepUp: (reply: FastifyReply, a: App, s: Session, p: Provider, next: string) => Promise<unknown>;
+
 export async function completeLogin(req: FastifyRequest, reply: FastifyReply, a: App, oldSession: Session, username: string, opts: SignInOptions & { next?: string } = {}) {
   await signIn(req, reply, a, oldSession, username, opts);
   return reply.redirect(safeNext(a, opts.next), 303);
@@ -1345,6 +1350,13 @@ export async function runtimeRoutes(app: FastifyInstance) {
     }
   });
 
+  /** (sprint 132) A step-up through the identity provider the session signed in with (two-step.ts). */
+  ssoStepUp = async (reply: FastifyReply, a: App, s: Session, p: Provider, next: string) => {
+    const { url, browserKey } = p.protocol === 'saml' ? await startSamlSignIn(p, a.id, next, undefined, s.id) : await startSignIn(p, a.id, next, undefined, s.id);
+    reply.setCookie(SSO_COOKIE, browserKey, { path: '/sso', httpOnly: true, sameSite: 'lax', secure: process.env.COOKIE_SECURE === 'true', maxAge: 600 });
+    return reply.redirect(url, 303);
+  };
+
   app.get<{ Params: { provider: string } }>('/sso/callback/:provider', async (req, reply) => {
     const ip = clientIp(req);
     const p = await loadProvider(req.params.provider);
@@ -1375,9 +1387,24 @@ export async function runtimeRoutes(app: FastifyInstance) {
         return simplePage(reply, 403, english('login.sso_failed'), e.message, result.link ? '/builder/security' : '/builder/login');
       });
     }
+    if (result.stepup) return withAppDb(result.appId, () => finishSsoStepUp(req, reply, p, result, ip));
     return withAppDb(result.appId, () => finishSsoForApp(req, reply, p, result, ip));
   };
-  const finishSsoForApp = async (req: FastifyRequest, reply: FastifyReply, p: { name: string }, result: SsoResult, ip: string) => {
+  /** (sprint 132) A step-up confirmed by the provider: the session that asked for it gets its second step. */
+  const finishSsoStepUp = async (req: FastifyRequest, reply: FastifyReply, p: Provider, result: SsoResult, ip: string) => {
+    const s = await runtime.one<{ id: string; app_id: number; username: string | null; state: Record<string, unknown> }>(
+      'select id, app_id, username, state from meta.session where id = $1', [result.stepup]);
+    const a = s ? await loadApp((await runtime.one<{ alias: string }>('select alias from meta.app where id = $1', [s.app_id]))?.alias ?? '') : undefined;
+    if (!s || !a || s.app_id !== result.appId || s.username?.toLowerCase() !== result.username.toLowerCase()) {
+      logActivity({ appId: result.appId, username: result.username, event: 'login_failed', ip, detail: `sso:${p.name}: step-up for another session or user` });
+      return simplePage(reply, 403, english('login.sso_failed'), english('login.sso_incomplete'));
+    }
+    markSecondStep(s.state);
+    await runtime.query('update meta.session set state = $2 where id = $1', [s.id, s.state]);
+    await logActivity({ appId: a.id, username: s.username, event: '2fa_stepup', ip, detail: `sso:${p.name}` });
+    return reply.redirect(safeNext(a, result.next ?? undefined), 303);
+  };
+  const finishSsoForApp = async (req: FastifyRequest, reply: FastifyReply, p: Provider, result: SsoResult, ip: string) => {
     const alias = (await runtime.one<{ alias: string }>('select alias from meta.app where id = $1', [result.appId]))?.alias;
     const loaded = alias ? await appWithLocale(req, alias) : undefined;
     if (!loaded || loaded.app.authentication !== 'app_users' || !loaded.app.sso_providers.includes(p.name)) return simplePage(reply, 403, english('login.sso_failed'), english('login.method_unavailable'));
@@ -1388,7 +1415,16 @@ export async function runtimeRoutes(app: FastifyInstance) {
       return simplePage(reply, 403, locale.t('login.no_access_title'), locale.t('login.no_access', { user: result.username, app: a.name }), `/a/${a.alias}/login`, locale);
     }
     const session = await getSession(req, reply, a.id, `/a/${a.alias}`);
-    return completeLogin(req, reply, a, session, result.username, { extraRoles: access.roles, next: result.next ?? undefined, method: `sso:${p.name}`, detail: `sso:${p.name}` });
+    const opts = { extraRoles: access.roles, next: result.next ?? undefined, method: `sso:${p.name}`, detail: `sso:${p.name}${result.mfa ? ' (mfa)' : ''}` };
+    // (sprint 132) pgkiln's own second step after the provider, as after a password
+    if (p.local_second_step) return passwordSignIn(req, reply, a, session, result.username, opts);
+    const s = await signIn(req, reply, a, session, result.username, opts);
+    // the provider's second factor counts for step-up (authorization schemes with mfa_minutes)
+    if (result.mfa) {
+      markSecondStep(s.state);
+      await saveState(s);
+    }
+    return reply.redirect(safeNext(a, opts.next), 303);
   };
 
   // SAML: the IdP posts the response cross-site, where SameSite=Lax cookies aren't sent; post it on

package/src/runtime/two-step.ts

@@ -19,7 +19,8 @@ import { ALGORITHMS, giveChallenge, relyingParty, takeChallenge, verifyAssertion
 import type { PageContext } from './context.ts';
 import type { Locale } from './locale.ts';
 import { pwaHead } from './pwa.ts';
-import { appWithLocale, completeLogin, loadContext, rootAttrs, safeNext, signIn, type Req } from './routes.ts';
+import { loadProvider, type Provider } from '../sso.ts';
+import { appWithLocale, completeLogin, loadContext, rootAttrs, safeNext, signIn, ssoStepUp, type Req } from './routes.ts';
 
 // (sprint 130, SEC-3) The second step of signing in to an application, and "Two-step sign-in" on My account.
 //
@@ -34,6 +35,9 @@ import { appWithLocale, completeLogin, loadContext, rootAttrs, safeNext, signIn,
 // and on My account, also as the first factor a user adds while signing in; a code by e-mail when the application
 // allows it, for users who have another factor; step-up: a signed-in user whose page needs a more recent second step
 // comes here with ?next= and goes back after it (the session's __MFA_AT); and My account → REST API token.
+//
+// (sprint 132, SEC-4) A session signed in through an identity provider steps up there instead: the provider signs the
+// user in again with a second factor (sso.ts, saml.ts), unless the provider leaves the second step to pgkiln.
 
 const PENDING = '__MFA';
 const STEP_SECONDS = 300;
@@ -228,6 +232,15 @@ async function locked(reply: FastifyReply, a: App, locale: Locale, s: Session, p
   return reply.code(429).type('text/html').send(card(a, locale, locale.t('mfa.step_title'), alert(locale.t('login.throttled', { minutes: loginWindowMinutes() }))));
 }
 
+/** (sprint 132) The identity provider a step-up goes back to: the one the session signed in with, if it decides itself. */
+async function stepUpProvider(a: App, s: Session): Promise<Provider | null> {
+  const method = String(s.state.__SIGNIN ?? '');
+  if (!method.startsWith('sso:')) return null;
+  const name = method.slice(4).replace(/\+2fa$/, '');
+  const p = a.sso_providers.includes(name) ? await loadProvider(name) : undefined;
+  return p && !p.local_second_step ? p : null;
+}
+
 export async function twoStepRoutes(app: FastifyInstance) {
   app.get('/a/:alias/login/2fa', async (req: Req, reply) => {
     const r = await start(req, reply);
@@ -237,6 +250,13 @@ export async function twoStepRoutes(app: FastifyInstance) {
     // (sprint 131) step-up: a signed-in user sent here by a page that needs a more recent second step
     const next = typeof (req.query as { next?: unknown }).next === 'string' ? String((req.query as { next: string }).next).slice(0, 2000) : undefined;
     if (s.username && (!p || (next && p.next !== next))) {
+      const via = await stepUpProvider(a, s);
+      if (via)
+        return ssoStepUp(reply, a, s, via, next ?? `/a/${a.alias}/${a.home_page}`).catch((e) => {
+          req.log.warn({ err: e }, 'sso step-up failed');
+          return reply.code(502).type('text/html').send(card(a, locale, locale.t('mfa.stepup_title'),
+            alert(locale.t('login.sso_unavailable', { provider: via.display_name })), `/a/${a.alias}/${a.home_page}`));
+        });
       const id = await accountId(s.username);
       if (id === null || !(await accountHasFactor(id)))
         return reply.code(403).type('text/html').send(card(a, locale, locale.t('mfa.stepup_title'),

package/src/saml.ts

@@ -1,7 +1,7 @@
 import { randomBytes } from 'node:crypto';
 import { SAML, ValidateInResponseTo, type CacheProvider, type Profile } from '@node-saml/node-saml';
 import { owner } from './db.ts';
-import { publicUrl, resolveAccount, sha256, SsoError, usableUsername, type Provider, type SsoResult } from './sso.ts';
+import { MFA_REFUSED, mfaRequest, provedMfa, publicUrl, resolveAccount, sha256, SsoError, stepUpResult, usableUsername, type Provider, type SsoResult } from './sso.ts';
 
 // SAML 2.0 sign-in (APEX: SAML Sign-In), service-provider initiated:
 //
@@ -18,6 +18,9 @@ import { publicUrl, resolveAccount, sha256, SsoError, usableUsername, type Provi
 // answer an AuthnRequest of this flow, once. On top: the assertion's issuer
 // (node-saml doesn't check it for responses), the one-time state and the browser
 // that started the flow (as for OpenID Connect).
+// (sprint 132, SEC-4) The assertion's AuthnContextClassRef tells how the user signed in: with mfa_required it must
+// be one of the provider's mfa_values; mfa_request asks for those (RequestedAuthnContext); a step-up adds ForceAuthn
+// and checks the AuthnInstant.
 
 const PENDING_MINUTES = 10;
 const b64url = (b: Buffer) => b.toString('base64url');
@@ -54,8 +57,9 @@ function requestCache(onSave: (id: string) => void, only?: string): CacheProvide
   };
 }
 
-function client(p: Provider, cache: CacheProvider) {
+function client(p: Provider, cache: CacheProvider, stepup = false) {
   if (!p.idp_sso_url || !p.idp_cert) throw new SsoError('The SAML provider is not configured completely.');
+  const requested = mfaRequest(p);
   return new SAML({
     entryPoint: p.idp_sso_url,
     issuer: spEntityId(p),
@@ -69,37 +73,51 @@ function client(p: Provider, cache: CacheProvider) {
     requestIdExpirationPeriodMs: PENDING_MINUTES * 60_000,
     cacheProvider: cache,
     identifierFormat: null,
-    disableRequestedAuthnContext: true,
+    // (sprint 132) a RequestedAuthnContext only when the administrator names the classes
+    disableRequestedAuthnContext: !requested.length,
+    authnContext: requested,
+    racComparison: 'exact',
+    forceAuthn: stepup,
     acceptedClockSkewMs: 60_000,
     signatureAlgorithm: 'sha256',
   });
 }
 
 /** Start: the IdP URL with the AuthnRequest, and the browser-binding cookie value. */
-export async function startSamlSignIn(p: Provider, appId: number | null, next: string | undefined, link?: string) {
+export async function startSamlSignIn(p: Provider, appId: number | null, next: string | undefined, link?: string, stepup?: string) {
   const state = b64url(randomBytes(32));
   const browserKey = b64url(randomBytes(32));
   await owner.query(`delete from meta.sso_pending where created_at < now() - make_interval(mins => $1)`, [PENDING_MINUTES]);
   await owner.query(`delete from meta.saml_request where created_at < now() - make_interval(mins => $1)`, [PENDING_MINUTES]);
   let requestId = '';
-  const url = await client(p, requestCache((id) => (requestId = id))).getAuthorizeUrlAsync(state, undefined, {});
+  const url = await client(p, requestCache((id) => (requestId = id)), !!stepup).getAuthorizeUrlAsync(state, undefined, {});
   if (!requestId) throw new SsoError('The AuthnRequest has no ID.');
   // code_verifier is unused for SAML; nonce holds the AuthnRequest ID the response must answer
   await owner.query(
-    `insert into meta.sso_pending (state, app_id, provider_id, code_verifier, nonce, browser_hash, next, link_username)
-     values ($1, $2, $3, '', $4, $5, $6, $7)`,
-    [state, appId, p.id, requestId, sha256(browserKey), next ?? null, link ?? null],
+    `insert into meta.sso_pending (state, app_id, provider_id, code_verifier, nonce, browser_hash, next, link_username, stepup_session)
+     values ($1, $2, $3, '', $4, $5, $6, $7, $8)`,
+    [state, appId, p.id, requestId, sha256(browserKey), next ?? null, link ?? null, stepup ?? null],
   );
   return { url, browserKey };
 }
 
+/** (sprint 132) The signed assertion's AuthnContextClassRefs and AuthnInstant (ms), read after node-saml checked it. */
+export function authnContext(assertionXml: string): { classes: string[]; at: number | null } {
+  // comments are outside the signature (exclusive c14n drops them): text split by one is read as one
+  assertionXml = assertionXml.replace(/<!--[\s\S]*?-->/g, '');
+  const classes = [...assertionXml.matchAll(/<(?:[\w-]+:)?AuthnContextClassRef\b[^>]*>\s*([^<\s]+)\s*</g)].map((m) => m[1]);
+  const instant = /<(?:[\w-]+:)?AuthnStatement\b[^>]*\bAuthnInstant="([^"]+)"/.exec(assertionXml)?.[1];
+  const at = instant ? Date.parse(instant) : NaN;
+  return { classes, at: Number.isFinite(at) ? at : null };
+}
+
 const values = (v: unknown): string[] => (v === undefined || v === null ? [] : (Array.isArray(v) ? v : [v]).map(String).filter(Boolean));
 
 /** Finish: check state, browser and the response; the account and its groups. */
 export async function finishSamlSignIn(p: Provider, body: { SAMLResponse?: string; RelayState?: string }, browserKey: string | undefined): Promise<SsoResult> {
   const pending = await owner.one(
     `delete from meta.sso_pending where state = $1 and provider_id = $2 and created_at > now() - make_interval(mins => $3)
-     returning app_id, nonce, browser_hash, next, link_username`,
+     returning app_id, nonce, browser_hash, next, link_username, stepup_session`,
     [body.RelayState ?? '', p.id, PENDING_MINUTES],
   );
   if (!pending) throw new SsoError('This sign-in has expired or was already used. Please try again.');
@@ -115,6 +133,11 @@ export async function finishSamlSignIn(p: Provider, body: { SAMLResponse?: strin
   // node-saml checks the issuer of logout messages only: the assertion must come from the configured IdP
   if (profile?.issuer !== p.issuer) throw new SsoError(`The SAML response comes from ${profile?.issuer ?? 'an unknown issuer'}, not from ${p.issuer}.`);
   if (!profile?.nameID) throw new SsoError('The SAML response names no user.');
+  // (sprint 132, SEC-4) how the user signed in
+  const how = authnContext(profile.getAssertionXml?.() ?? '');
+  const mfa = provedMfa(p, how.classes);
+  if (pending.stepup_session) return stepUpResult(p, pending, profile.nameID, mfa, how.at);
+  if (p.mfa_required && !mfa) throw new SsoError(MFA_REFUSED);
   const username = p.username_claim === 'nameID' ? profile.nameID : values(profile[p.username_claim])[0];
   if (!usableUsername(username)) throw new SsoError(`The SAML response has no usable "${p.username_claim}" attribute.`);
   const name = values(profile.displayName ?? profile.cn)[0];
@@ -122,9 +145,9 @@ export async function finishSamlSignIn(p: Provider, body: { SAMLResponse?: strin
   const groups = values(profile[p.groups_claim]);
   if (pending.app_id === null)
     // the builder: devsso.ts finds the developer (sprint 129)
-    return { appId: null, next: pending.next, username, groups, link: pending.link_username, identity: { subject: profile.nameID, name: name ?? null, email: email ?? null, mayLink: true } };
+    return { appId: null, next: pending.next, username, groups, link: pending.link_username, mfa, identity: { subject: profile.nameID, name: name ?? null, email: email ?? null, mayLink: true } };
   const account = await resolveAccount(p, { sub: profile.nameID, name, email: profile.email ?? profile.mail }, username);
-  return { appId: pending.app_id, next: pending.next, username: account, groups };
+  return { appId: pending.app_id, next: pending.next, username: account, groups, mfa };
 }
 
 /** Service provider metadata (entity ID, ACS) to register pgkiln at the IdP. */

package/src/secrets.ts

@@ -14,26 +14,36 @@ export class SecretKeyMissing extends Error {
   }
 }
 
-function key() {
-  const k = process.env.PGKILN_SECRET_KEY ?? '';
+function key(k = process.env.PGKILN_SECRET_KEY ?? '') {
   if (k.length < 32) throw new SecretKeyMissing();
   return createHash('sha256').update(`pgkiln-secret-v1\0${k}`).digest();
 }
 
 export const secretKeyConfigured = () => (process.env.PGKILN_SECRET_KEY ?? '').length >= 32;
 
-export function encryptSecret(plain: string): string {
+/**
+ * (sprint 133, SEC-6) A short fingerprint of a key, to tell which key a backup confirmation was for. A
+ * different derivation than the encryption key's, so it reveals nothing about that key.
+ */
+export function keyFingerprint(k = process.env.PGKILN_SECRET_KEY ?? ''): string | null {
+  if (k.length < 32) return null;
+  return createHash('sha256').update(`pgkiln-key-fingerprint\0${k}`).digest('hex').slice(0, 16).replace(/(.{4})(?!$)/g, '$1-');
+}
+
+/** Encrypt with the server's key, or (rotate-key) with the key given. */
+export function encryptSecret(plain: string, withKey?: string): string {
   const iv = randomBytes(12);
-  const c = createCipheriv('aes-256-gcm', key(), iv);
+  const c = createCipheriv('aes-256-gcm', key(withKey), iv);
   const ct = Buffer.concat([c.update(plain, 'utf8'), c.final()]);
   return VERSION + Buffer.concat([iv, c.getAuthTag(), ct]).toString('base64');
 }
 
-export function decryptSecret(stored: string): string {
+/** Decrypt with the server's key, or (rotate-key, checks) with the key given. */
+export function decryptSecret(stored: string, withKey?: string): string {
   if (!stored.startsWith(VERSION)) throw new Error('Unknown secret format.');
   const buf = Buffer.from(stored.slice(VERSION.length), 'base64');
   if (buf.length < 28) throw new Error('Damaged secret.');
-  const d = createDecipheriv('aes-256-gcm', key(), buf.subarray(0, 12));
+  const d = createDecipheriv('aes-256-gcm', key(withKey), buf.subarray(0, 12));
   d.setAuthTag(buf.subarray(12, 28));
   try {
     return Buffer.concat([d.update(buf.subarray(28)), d.final()]).toString('utf8');

package/src/server.ts

@@ -14,3 +14,13 @@ await startWorkflowRunner();
 await startProcessJobRunner();
 await startPushListener();
 await startMailListener();
+// (sprint 133, SEC-6) say at start-up what could lock people out: a changed instance key or address, the clock
+try {
+  const { instanceChecks } = await import('./instance-checks.ts');
+  const { rpIdOf } = await import('./webauthn.ts');
+  const pub = process.env.PUBLIC_URL;
+  for (const c of await instanceChecks(pub && URL.canParse(pub) ? rpIdOf(new URL(pub).origin) : null))
+    if (c.level === 'error' || (c.level === 'warning' && c.key !== 'key_backup')) console.warn(`pgkiln: ${c.title}: ${c.detail}`);
+} catch (e) {
+  console.warn('pgkiln: lockout checks failed:', (e as Error).message);
+}