@jwilleke/ngdpbase-types 5.40.0 → 5.41.0

package/lib/src/managers/AuthManager.js

@@ -69,6 +69,24 @@ import { sameUsername } from '../utils/username.js';
 import { isEmail } from '../types/guards.js';
 import { jobContextFromRequestWithReason } from '../context/JobContext.js';
 import { systemContext, systemPrincipalOf } from '../context/bootActions.js';
+/**
+ * Old provider ids whose entries still govern the provider (#1743; #1523 Q3,
+ * operator 2026-10-31): an entry, or an account's `allowedAuthMethods`, under
+ * the old id is read as the current one.
+ */
+const FACTOR_ALIASES = { 'google-oidc': 'oidc:google', 'email-link': 'magic-link' };
+/**
+ * Do an account's `allowedAuthMethods` let it use `providerId`? Absent or
+ * empty means any; an old id names the provider it was renamed to (Q3). The
+ * one reading for signing in and for the level the account can reach.
+ */
+const allowsProvider = (allowed, providerId) => !allowed || allowed.length === 0 || allowed.some(a => (FACTOR_ALIASES[a] ?? a) === providerId);
+/**
+ * The entry that governs the email link as a second factor (#1523 Q3): the
+ * magic link's, since starting a sign-in and confirming one are the same
+ * provider. The second step runs it itself, so it needs no registered provider.
+ */
+const EMAIL_LINK_ENTRY = 'magic-link';
 /** A factor as offered: its entry lowered to what the provider's code gives. */
 /**
  * Providers that count toward a sign-in level only once the account has
@@ -291,6 +309,91 @@ function proxyGrantLive(grant, now) {
 export function answeredWithPage(mode) {
     return mode === 'page' || mode === 'download';
 }
+/** How many prompts one session keeps (#2193), the newest: a few tabs' worth. */
+const STEP_UP_PROMPTS_PER_SESSION = 5;
+/** A prompt id as minted (#2193), or null for anything else. */
+export function stepUpPromptId(value) {
+    return typeof value === 'string' && /^[0-9a-f]{32}$/.test(value) ? value : null;
+}
+/** A waiting prompt of this session confirmed or cancelled (#2193); one already settled stays as it is. */
+function settleStepUpPrompt(req, id, state) {
+    const prompt = stepUpPromptId(id);
+    const kept = req.session?.stepUpPrompts?.find((p) => p.id === prompt);
+    if (kept?.state === 'waiting')
+        kept.state = state;
+}
+/** Where a fresh sign-in sends the browser to redo a form POST (#2154). */
+export const STEP_UP_CONTINUE_PATH = '/auth/reauth/continue';
+/** How long a kept form POST waits for its fresh sign-in (#2154): reading the prompt may take a while. */
+const STEP_UP_REPLAY_WAIT_MS = 60 * 60_000;
+/** How long a confirmed form POST waits to be redone (#2154), from the confirmation: the browser goes there at once. */
+const STEP_UP_REPLAY_TTL_MS = 2 * 60_000;
+/** How many kept form POSTs one session holds at once (#2176): a few tabs' worth, so memory stays bounded. */
+const STEP_UP_REPLAYS_PER_SESSION = 5;
+/** How many one account holds across its sessions (#2176): signing in many times does not hold more. */
+const STEP_UP_REPLAYS_PER_ACCOUNT = 10;
+/** How many the site holds in all (#2176): each may hold a form body of up to 100 KB, so at most 20 MB. */
+const STEP_UP_REPLAYS_TOTAL = 200;
+/** The kept form POST a prompt's `next` names (#2154), or null when it names none. */
+function stepUpReplayId(next) {
+    const url = new URL(next, 'http://site.invalid');
+    return url.pathname === STEP_UP_CONTINUE_PATH ? url.searchParams.get('replay') : null;
+}
+/**
+ * Field names whose value is a secret (#2154): a password, recovery words, a
+ * token. A form holding one is never kept or written back into a page; it
+ * returns with the note instead.
+ */
+const SECRET_FIELD = /password|secret|token|^words$/i;
+/** Drop kept form POSTs past their time (#2154). */
+function dropExpiredReplays(replays, now) {
+    for (const [id, kept] of replays)
+        if (kept.expires <= now)
+            replays.delete(id);
+}
+/**
+ * Drop the oldest of `entries` from `replays` until `room` are left (#2176),
+ * the unconfirmed first: a confirmed one is an action about to be carried out.
+ * `entries` are in the Map's insertion order, oldest first.
+ */
+function dropOldestReplays(replays, entries, room) {
+    const order = [...entries.filter(([, kept]) => !kept.ready), ...entries.filter(([, kept]) => kept.ready)];
+    for (const [id] of order.slice(0, Math.max(0, order.length - room)))
+        replays.delete(id);
+}
+/** A kept form POST's address for the log and the audit (#2176): the path, never the query. */
+function replayPath(action) {
+    return new URL(action, 'http://site.invalid').pathname;
+}
+/**
+ * A form POST's fields as they can be posted again to give the same body
+ * (#2154), or null when they cannot: a file upload, a nested field, a name
+ * with brackets. A list goes back as `name[]`, which parses to a list even
+ * of one. `_csrf` is left out: the replay carries the session's token. A
+ * secret (`SECRET_FIELD`) is never kept, so such a form is null too.
+ */
+export function replayableFields(req) {
+    if (!req.is('application/x-www-form-urlencoded'))
+        return null;
+    const body = req.body;
+    if (!body || typeof body !== 'object')
+        return null;
+    const fields = [];
+    for (const [name, value] of Object.entries(body)) {
+        if (name === '_csrf')
+            continue;
+        if (/[[\]]/.test(name) || SECRET_FIELD.test(name))
+            return null;
+        if (typeof value === 'string')
+            fields.push([name, value]);
+        else if (Array.isArray(value) && value.every((v) => typeof v === 'string'))
+            for (const v of value)
+                fields.push([`${name}[]`, v]);
+        else
+            return null;
+    }
+    return fields;
+}
 /**
  * Where to return after re-authenticating: this page for a page GET, and the
  * page the person was on for anything else — a POST (the form is filled in
@@ -419,6 +522,7 @@ class AuthManager extends BaseManager {
         await this.openCredentialsStore(configManager);
         this.registerPasskeys(configManager);
         this.registerOidcProviders(configManager);
+        this.warnIfEmailSecondFactorsDropped();
         logger.info(`[AuthManager] Initialized — factors: [${this.factorEntries.map(e => e.authproviderid).join(', ')}]`);
     }
     /**
@@ -430,24 +534,61 @@ class AuthManager extends BaseManager {
             return [{ authproviderid: 'password' }];
         const legacy = configManager.getCustomProperty('ngdpbase.auth.required-factors');
         const custom = configManager.getCustomProperty('ngdpbase.auth.factors');
-        if (Array.isArray(legacy)) {
+        const legacyIds = Array.isArray(legacy) ? legacy.filter((id) => typeof id === 'string') : null;
+        if (legacyIds) {
             logger.warn('[AuthManager] ngdpbase.auth.required-factors is retired — ' +
-                (custom === undefined
-                    ? 'converted to ngdpbase.auth.factors entries; rename it in custom config. (#1523)'
-                    : 'ignored, because ngdpbase.auth.factors is also set; remove it from custom config. (#1523)'));
-            if (custom === undefined) {
-                return legacy.filter((id) => typeof id === 'string').map(id => ({ authproviderid: id }));
-            }
-        }
-        const entries = configManager.getProperty('ngdpbase.auth.factors', [{ authproviderid: 'password' }]);
+                (custom !== undefined
+                    ? 'ignored, because ngdpbase.auth.factors is also set; remove it from custom config. (#1523)'
+                    : legacyIds.some(id => (FACTOR_ALIASES[id] ?? id) === EMAIL_LINK_ENTRY)
+                        ? 'converted to ngdpbase.auth.factors entries; rename it in custom config. (#1523)'
+                        : `converted to ngdpbase.auth.factors entries; rename it in custom config. It lists no ${EMAIL_LINK_ENTRY}, so the email second factor is off: ` +
+                            `accounts that enrolled one sign in with one step. List ${EMAIL_LINK_ENTRY} to keep it. (#1523)`));
+        }
+        const entries = legacyIds && custom === undefined
+            ? legacyIds.map(id => ({ authproviderid: id }))
+            : configManager.getProperty('ngdpbase.auth.factors', [{ authproviderid: 'password' }]);
         if (!Array.isArray(entries)) {
             logger.error('[AuthManager] ngdpbase.auth.factors is not a list — offering password only. (#1523)');
             return [{ authproviderid: 'password' }];
         }
-        return entries
-            .filter((e) => typeof e === 'object' && e !== null && typeof e.authproviderid === 'string')
-            // #1743: Google's provider is now `oidc:google`; an entry under its old id still governs it.
-            .map(e => (e.authproviderid === 'google-oidc' ? { ...e, authproviderid: 'oidc:google' } : e));
+        // An entry without a string authproviderid is dropped, and it also made
+        // the merge replace the shipped list instead of merging by id.
+        const wellFormed = entries.filter((e) => {
+            if (typeof e === 'object' && e !== null && typeof e.authproviderid === 'string')
+                return true;
+            logger.warn(`[AuthManager] ngdpbase.auth.factors: dropped ${JSON.stringify(e)}, which has no string authproviderid. ` +
+                'A custom list holding such an entry replaces the shipped list rather than merging with it, so every shipped entry it does not restate is off. (#1523)');
+            return false;
+        });
+        // #1743, #1523 Q3: an entry under an old id governs the provider. The merge
+        // appends a custom entry under the old id after the shipped one, so of two
+        // entries for one provider the later wins, in the earlier one's place.
+        const byProvider = new Map();
+        for (const e of wellFormed) {
+            const id = FACTOR_ALIASES[e.authproviderid] ?? e.authproviderid;
+            byProvider.set(id, { ...e, authproviderid: id });
+        }
+        const read = [...byProvider.values()];
+        // #1523 Q10: no longer shipped, so only a site's own config still says it.
+        const trusting = read.filter(e => Array.isArray(e.amr) && e.amr.includes('trust')).map(e => e.authproviderid);
+        if (trusting.length > 0) {
+            logger.warn(`[AuthManager] ngdpbase.auth.factors: "amr": ["trust"] on ${trusting.join(', ')} does nothing — trust an outside provider's own second factor with "trust-mfa": true on its entry in ngdpbase.auth.oidc.providers. (#1633)`);
+        }
+        return read;
+    }
+    /**
+     * #1523: with the `magic-link` entry off or not listed, an enrolled email
+     * second factor is no longer asked for. The operator may mean that, but it
+     * must not happen silently.
+     */
+    warnIfEmailSecondFactorsDropped() {
+        if (this.factorEntries.some(e => e.authproviderid === EMAIL_LINK_ENTRY && e.enabled !== false))
+            return;
+        const accounts = new Set((this.credentials?.listKind('email') ?? []).map(r => r.username)).size;
+        if (accounts === 0)
+            return;
+        logger.warn(`[AuthManager] ngdpbase.auth.factors: the ${EMAIL_LINK_ENTRY} entry is off or not listed, so the enrolled email second factor ` +
+            `of ${accounts} account(s) is no longer asked for — they sign in with one step, and magic-link sign-in is off too. (#1523)`);
     }
     /**
      * The outside OpenID Connect providers (#1743): one `OidcAuthProvider` per
@@ -1027,9 +1168,7 @@ class AuthManager extends BaseManager {
      */
     async userMayUseProvider(username, providerId) {
         const user = await this.engine.getManager('UserManager')?.getUser(username);
-        const allowed = user?.allowedAuthMethods;
-        // #1743: Google's provider was `google-oidc`; an account limited to it keeps it as `oidc:google`.
-        return !allowed || allowed.length === 0 || allowed.includes(providerId) || (providerId === 'oidc:google' && allowed.includes('google-oidc'));
+        return allowsProvider(user?.allowedAuthMethods, providerId);
     }
     async passkeyRegistrationOptions(ctx, username, displayName) {
         if (!(await this.mayManageCredentials(ctx, username)))
@@ -2085,7 +2224,7 @@ class AuthManager extends BaseManager {
     async aalReachFor(username) {
         const user = await this.engine.getManager('UserManager')?.getUser(username);
         const allowed = user?.allowedAuthMethods;
-        const offered = this.getFactors().filter(f => !allowed || allowed.length === 0 || allowed.includes(f.provider));
+        const offered = this.getFactors().filter(f => allowsProvider(allowed, f.provider));
         const reach = (factors) => Math.max(factors.some(f => f.primary) ? this.assess(factors).aal : 0, 1);
         const usable = offered.filter(f => {
             const kind = ENROLLED_FACTORS[f.provider];
@@ -2185,11 +2324,21 @@ class AuthManager extends BaseManager {
         await this.recordReauth(req, AUDIT_EVENT.REAUTH_PROMPT, 'failure', permission, delegated ? 'delegated credential cannot re-authenticate' : 'fresh sign-in asked for');
         if (delegated)
             return { permission, delegated, error: 'This needs a fresh sign-in by the person; a token cannot give one' };
-        const next = reauthReturnTo(req, mode);
+        const back = reauthReturnTo(req, mode);
+        // #2154: a form POST is kept, and the confirmation returns to redo it.
+        const replay = req.session ? this.keepStepUpReplay(req, permission, mode, back) : null;
+        const next = replay ? `${STEP_UP_CONTINUE_PATH}?replay=${replay}` : back;
+        // #2193: a script's request names its own prompt, so the page that sent it
+        // waits for that confirmation and no other.
+        const prompt = req.session && mode === 'json' ? randomBytes(16).toString('hex') : null;
+        if (prompt)
+            req.session.stepUpPrompts = [...(req.session.stepUpPrompts ?? []), { id: prompt, state: 'waiting' }].slice(-STEP_UP_PROMPTS_PER_SESSION);
         // #2145: what the prompt was for, so its success is recorded against it and,
         // when returning does not redo the action, the page says it can be done now.
         if (req.session) {
-            req.session.pendingStepUp = { permission, next, replays: req.method === 'GET' && mode === 'page' };
+            req.session.pendingStepUp = replay
+                ? { permission, next, replays: true, replay }
+                : { permission, next, replays: req.method === 'GET' && mode === 'page' };
             // Saved before the answer goes out: the browser follows a redirect on its
             // headers, before express-session's own save at the end lands, and the
             // prompt's request would read (and write back) the session without it.
@@ -2202,9 +2351,22 @@ class AuthManager extends BaseManager {
             permission,
             delegated,
             error: 'A fresh sign-in is needed',
-            reauth: `/auth/reauth?next=${encodeURIComponent(next)}`
+            reauth: `/auth/reauth?next=${encodeURIComponent(next)}${prompt ? `&prompt=${prompt}` : ''}`
         };
     }
+    /**
+     * Where this session's prompt `id` is (#2193): waiting, confirmed or
+     * cancelled, or unknown (another session's, dropped, or not an id). Reads
+     * only, so asking it often changes nothing in the session.
+     */
+    stepUpPromptState(req, id) {
+        const prompt = stepUpPromptId(id);
+        return req.session?.stepUpPrompts?.find((p) => p.id === prompt)?.state ?? 'unknown';
+    }
+    /** The prompt's Cancel (#2193): a waiting prompt of this session is cancelled, so its page stops waiting. */
+    cancelStepUpPrompt(req, id) {
+        settleStepUpPrompt(req, id, 'cancelled');
+    }
     /** Record a step-up event: a prompt, a success or a failure (#1525). */
     async recordReauth(req, eventType, result, permission, detail) {
         await recordAuditEvent(this.engine.getManager('AuditManager'), {
@@ -2229,17 +2391,36 @@ class AuthManager extends BaseManager {
      * directly, against the method), and when going there does not redo the
      * action (a form POST, a script's request, a download) the page there says
      * it can be done now (`takeStepUpNotice`).
+     *
+     * #2193: `prompt`, the id a script's refusal named, is confirmed when it is
+     * this session's and still waiting; no other prompt is.
      */
-    async completeReauth(req, result, method, next) {
+    async completeReauth(req, result, method, next, prompt) {
         const record = this.reauthenticated(req.session.signIn, result);
         if (record)
             req.session.signIn = record;
+        if (record)
+            settleStepUpPrompt(req, prompt, 'confirmed');
         const pending = req.session.pendingStepUp;
         delete req.session.pendingStepUp;
         const answered = pending && pending.next === next ? pending : undefined;
         if (answered && !answered.replays)
             req.session.stepUpConfirmed = new URL(next, 'http://site.invalid').pathname;
-        await this.recordReauth(req, AUDIT_EVENT.REAUTH_SUCCESS, 'success', answered?.permission ?? method, `re-authenticated with ${method}${answered ? ` for ${answered.permission}` : ''}; acr ${record?.acr ?? 'unknown'}`);
+        // #2154: the confirmation releases the form POST it was asked for, named by
+        // `next` itself (the session's pending prompt may be another tab's), and
+        // its time to be redone starts now, however long the prompt was open.
+        // Another session's or person's is not released, nor is the success recorded
+        // against its permission: the attempt is a `reauth-failure`, as at the take.
+        const kept = this.stepUpReplays.get(stepUpReplayId(next) ?? '');
+        const mine = kept && kept.sessionId === req.sessionID && kept.username === req.session.username ? kept : undefined;
+        if (kept && !mine) {
+            await this.recordReauth(req, AUDIT_EVENT.REAUTH_FAILURE, 'failure', kept.permission, `kept form POST for ${replayPath(kept.action)} confirmed from another session; not released`);
+        }
+        if (mine && mine.expires > Date.now()) {
+            mine.ready = true;
+            mine.expires = Date.now() + STEP_UP_REPLAY_TTL_MS;
+        }
+        await this.recordReauth(req, AUDIT_EVENT.REAUTH_SUCCESS, 'success', answered?.permission ?? mine?.permission ?? method, `re-authenticated with ${method}${answered ? ` for ${answered.permission}` : ''}; acr ${record?.acr ?? 'unknown'}`);
         return record;
     }
     /**
@@ -2257,6 +2438,79 @@ class AuthManager extends BaseManager {
         delete req.session.stepUpConfirmed;
         return req.path === path;
     }
+    /** #2154: form POSTs kept for their fresh sign-in, by a random id. In memory: a restart drops them. */
+    stepUpReplays = new Map();
+    /**
+     * Keep a form POST answered with the prompt, to be redone after it
+     * (#2154); its id, or null when it cannot be redone exactly. Only a page's
+     * POST by a signed-in person, to an address on this site. Each prompt keeps
+     * its own, so the same button pressed in two tabs loses neither (#2176); a
+     * session keeps at most `STEP_UP_REPLAYS_PER_SESSION`, an account
+     * `STEP_UP_REPLAYS_PER_ACCOUNT` and the site `STEP_UP_REPLAYS_TOTAL`, a new
+     * prompt dropping the oldest past that, unconfirmed first, and any past its
+     * time. It waits `STEP_UP_REPLAY_WAIT_MS` for the confirmation, which
+     * restarts its clock. A session's end drops its own (`dropStepUpReplays`).
+     */
+    keepStepUpReplay(req, permission, mode, back) {
+        const username = req.session.username;
+        if (req.method !== 'POST' || mode !== 'page' || typeof username !== 'string' || !req.sessionID)
+            return null;
+        const action = req.originalUrl;
+        if (safeRedirect(action) !== action)
+            return null;
+        const fields = replayableFields(req);
+        if (!fields)
+            return null;
+        const now = Date.now();
+        dropExpiredReplays(this.stepUpReplays, now);
+        // A Map iterates in insertion order: the oldest come first.
+        const all = () => Array.from(this.stepUpReplays);
+        dropOldestReplays(this.stepUpReplays, all().filter(([, kept]) => kept.sessionId === req.sessionID), STEP_UP_REPLAYS_PER_SESSION - 1);
+        dropOldestReplays(this.stepUpReplays, all().filter(([, kept]) => kept.username === username), STEP_UP_REPLAYS_PER_ACCOUNT - 1);
+        dropOldestReplays(this.stepUpReplays, all(), STEP_UP_REPLAYS_TOTAL - 1);
+        const id = randomBytes(16).toString('hex');
+        this.stepUpReplays.set(id, { sessionId: req.sessionID, username, permission, action, fields, back, expires: now + STEP_UP_REPLAY_WAIT_MS, ready: false });
+        return id;
+    }
+    /** A session ended (#2176): the form POSTs it kept go with it (`endSession`). */
+    dropStepUpReplays(sessionId) {
+        for (const [id, kept] of this.stepUpReplays)
+            if (kept.sessionId === sessionId)
+                this.stepUpReplays.delete(id);
+    }
+    /**
+     * Take the kept form POST `id` for the continue page (#2154). Single-use:
+     * taken, it is gone, whatever the answer. Another session's or person's is
+     * refused (null); one not confirmed (the prompt's Cancel) or past its time
+     * only goes back, a confirmed one with the note (#2145). Otherwise the page
+     * posts the fields to the same address. A refusal or one past its time is
+     * recorded as a `reauth-failure`; any other past its time is dropped.
+     */
+    async takeStepUpReplay(req, id) {
+        const kept = typeof id === 'string' ? this.stepUpReplays.get(id) : undefined;
+        if (kept)
+            this.stepUpReplays.delete(id);
+        const now = Date.now();
+        dropExpiredReplays(this.stepUpReplays, now);
+        if (!kept) {
+            await this.recordReauth(req, AUDIT_EVENT.REAUTH_FAILURE, 'failure', STEP_UP_CONTINUE_PATH, 'kept form POST not found: already used, past its time, or unknown');
+            return null;
+        }
+        if (kept.sessionId !== req.sessionID || kept.username !== req.session?.username) {
+            logger.warn(`[step-up] a kept form POST for ${replayPath(kept.action)} was asked for from another session; refused`);
+            await this.recordReauth(req, AUDIT_EVENT.REAUTH_FAILURE, 'failure', kept.permission, `kept form POST for ${replayPath(kept.action)} asked for from another session`);
+            return null;
+        }
+        if (now > kept.expires) {
+            await this.recordReauth(req, AUDIT_EVENT.REAUTH_FAILURE, 'failure', kept.permission, `kept form POST for ${replayPath(kept.action)} past its time; not redone`);
+            if (kept.ready)
+                req.session.stepUpConfirmed = new URL(kept.back, 'http://site.invalid').pathname;
+            return { back: kept.back };
+        }
+        if (!kept.ready)
+            return { back: kept.back };
+        return { action: kept.action, fields: kept.fields, back: kept.back };
+    }
     /**
      * The one sign-in completion step (#1758): every way a person finishes
      * signing in — a password, a passkey, a second factor, an email link, an
@@ -2475,11 +2729,24 @@ class AuthManager extends BaseManager {
         const policy = this.stepUpPolicy();
         if (!policy.permissions.has(permission))
             return false;
+        return !this.freshUnder(policy.maxAgeMs, signIn, roles, delegated, now, cap);
+    }
+    /**
+     * Whether `signIn` is fresh enough for every step-up permission (#2193): the
+     * window and the level are one for all of them, so a page waiting on its
+     * prompt asks this without naming the permission. With step-up off, every
+     * sign-in is.
+     */
+    signInFresh(signIn, roles, delegated, now = Date.now(), cap) {
+        const policy = this.stepUpPolicy();
+        return policy.permissions.size === 0 || this.freshUnder(policy.maxAgeMs, signIn, roles, delegated, now, cap);
+    }
+    freshUnder(maxAgeMs, signIn, roles, delegated, now, cap) {
         if (delegated)
-            return true;
+            return false;
         const need = Math.max(this.requiredAalFor(roles, cap), 1);
-        const since = now - policy.maxAgeMs;
-        return !(signIn?.factors ?? []).some((f) => f.aal >= need && Date.parse(f.at) >= since);
+        const since = now - maxAgeMs;
+        return (signIn?.factors ?? []).some((f) => f.aal >= need && Date.parse(f.at) >= since);
     }
     /**
      * A session's sign-in after a re-authentication (#1525): the new factors
@@ -2793,16 +3060,48 @@ class AuthManager extends BaseManager {
         return this.mailForLinks() !== null;
     }
     /**
-     * The second factors `username` has enrolled and can use now (#1523). Any
-     * enrolled factor works; one that is not truly available (no mail transport)
-     * is not offered. Empty means the sign-in is one step, as before.
+     * Whether the email link can be a second factor now (#1523): its entry in
+     * `ngdpbase.auth.factors` (`magic-link`, or its alias `email-link`) listed
+     * and enabled, mail, and an explicit base-url.
+     */
+    emailSecondFactorAvailable() {
+        return this.mailForLinks() !== null && this.factorEntries.some(e => e.authproviderid === EMAIL_LINK_ENTRY && e.enabled !== false);
+    }
+    /**
+     * The second factors that may follow `first`, in the order they are offered
+     * (#1523; Q2, operator 2026-10-31): every enabled entry of
+     * `ngdpbase.auth.factors` other than the one the sign-in started with, whose
+     * level is known (its provider registered, or the email link). Those that,
+     * with the first step, reach `requiredAal` come first; then by `preference`,
+     * lower first, an entry with none last. Entry ids.
      */
-    secondFactorsFor(username) {
+    secondFactorOrder(first, requiredAal) {
+        const ranked = this.factorEntries.flatMap((entry) => {
+            if (entry.enabled === false || entry.authproviderid === first.provider)
+                return [];
+            const factor = entry.authproviderid === EMAIL_LINK_ENTRY ? EMAIL_FACTOR : this.getFactors().find(f => f.provider === entry.authproviderid);
+            if (!factor)
+                return [];
+            const reaches = this.assess([...(first.factors ?? []), factor]).aal >= requiredAal;
+            return [{ id: entry.authproviderid, reaches, preference: entry.preference ?? Number.MAX_SAFE_INTEGER }];
+        });
+        return ranked.sort((a, b) => Number(b.reaches) - Number(a.reaches) || a.preference - b.preference).map(r => r.id);
+    }
+    /**
+     * The second factors `username` has enrolled and can use now (#1523), in
+     * `secondFactorOrder` after the pending sign-in's first step; without one,
+     * by `preference`. Only what the second step can run is offered — today the
+     * email link — and one that is not truly available (no mail transport) is
+     * not. Empty means the sign-in is one step, as before.
+     */
+    secondFactorsFor(username, signIn) {
         const rows = this.credentials?.list(username) ?? [];
         const out = [];
-        if (this.mailForLinks()) {
-            for (const r of rows.filter((c) => c.kind === 'email')) {
-                out.push({ id: 'email-link', label: 'Email link', target: maskEmail(r.subject) });
+        for (const id of this.secondFactorOrder(signIn?.first ?? {}, signIn?.requiredAal ?? 0)) {
+            if (id === EMAIL_LINK_ENTRY && this.mailForLinks()) {
+                for (const r of rows.filter((c) => c.kind === 'email')) {
+                    out.push({ id: 'email-link', label: 'Email link', target: maskEmail(r.subject) });
+                }
             }
         }
         return out;
@@ -2820,7 +3119,7 @@ class AuthManager extends BaseManager {
         const record = result.success && result.username ? this.signInRecord(result) : null;
         if (!record || record.aal >= 2 || record.amr.includes('email'))
             return false;
-        return this.secondFactorsFor(result.username).length > 0;
+        return this.secondFactorsFor(result.username, { first: result }).length > 0;
     }
     /**
      * Roughly where `req` came from, for the approval message (#1532):
@@ -2851,6 +3150,9 @@ class AuthManager extends BaseManager {
         if (!username)
             throw new Error('beginTwoStep: no stored account has that username (#1882)');
         first = { ...first, username };
+        // #1523 Q2: what this account's roles require, so the factors that reach it are offered first.
+        const pip = this.engine.getManager('PolicyInformationPoint');
+        const requiredAal = this.requiredAalFor((await pip?.subjectFor(username))?.roles ?? [], await this.aalCapFor(username));
         this.sweepPending();
         const handle = randomBytes(24).toString('base64url');
         const now = Date.now();
@@ -2865,7 +3167,8 @@ class AuthManager extends BaseManager {
             requestIp: ctx.ip,
             requestUserAgent: ctx.userAgent,
             requestLocation: ctx.location ?? null,
-            privateStoreHandle: ctx.privateStoreHandle
+            privateStoreHandle: ctx.privateStoreHandle,
+            requiredAal
         });
         // #1532: an expiry is recorded when it happens, not when someone next looks.
         setTimeout(() => this.expirePending(handle), PENDING_SIGN_IN_TTL_MS + 1).unref?.();
@@ -2938,11 +3241,12 @@ class AuthManager extends BaseManager {
         const p = this.pendingSignIn(handle, binding);
         if (!p)
             return 'unavailable';
-        const mail = this.mailForLinks();
+        const mail = this.emailSecondFactorAvailable() ? this.mailForLinks() : null;
         const row = (this.credentials?.list(p.username) ?? []).find((c) => c.kind === 'email');
         const from = AuthManager.askedFrom(p);
         if (!mail || !row) {
-            await this.recordApproval(AUDIT_EVENT.SIGNINAPPROVAL_SENDFAIL, p, 'error', from, { reason: mail ? 'no email factor enrolled' : 'mail is not configured' });
+            const reason = mail ? 'no email factor enrolled' : this.mailForLinks() ? 'the email link is off in ngdpbase.auth.factors' : 'mail is not configured';
+            await this.recordApproval(AUDIT_EVENT.SIGNINAPPROVAL_SENDFAIL, p, 'error', from, { reason });
             return 'unavailable';
         }
         if (p.lastSentAt && Date.now() - p.lastSentAt < APPROVAL_RESEND_MS) {
@@ -3143,7 +3447,7 @@ class AuthManager extends BaseManager {
     async startEmailFactorEnrolment(ctx, username) {
         if (!(await this.mayManageCredentials(ctx, username)))
             throw new Error('Permission denied');
-        const mail = this.mailForLinks();
+        const mail = this.emailSecondFactorAvailable() ? this.mailForLinks() : null;
         if (!mail)
             return 'unavailable';
         const user = await this.engine.getManager('UserManager')?.getUser(username);

package/lib/src/managers/ExportManager.d.ts

@@ -128,6 +128,11 @@ declare class ExportManager extends BaseManager {
      * with the reason, as `none` is.
      */
     private pdfProvider;
+    /**
+     * Is a PDF provider chosen (#2120)? The Export action offers PDF only then.
+     * Whether the chosen one works is known only by rendering, as before.
+     */
+    isPdfConfigured(): boolean;
     /** Log why, flag the manager (unless something worse is already shown), and refuse. */
     private pdfUnavailable;
     private acquirePdfSlot;
@@ -148,6 +153,17 @@ declare class ExportManager extends BaseManager {
      * @returns {Promise<string>} HTML content
      */
     exportPageToHtml(pageName: string, ctx: ActorContext, user?: ExportUser | null): Promise<string>;
+    /**
+     * One page as a complete HTML document: its content rendered, with the
+     * export's styling and metadata footer. It reads nothing: the caller has
+     * read the page through its door (the page export source, #2120).
+     *
+     * @param pageName - The page's name, its heading
+     * @param page - Its content and metadata
+     * @param user - User object for locale-aware formatting
+     * @returns The HTML document
+     */
+    renderPageDocument(pageName: string, page: PageForExport, user?: ExportUser | null): Promise<string>;
     /**
      * Export multiple pages to a single HTML file
      * @param {string[]} pageNames - Array of page names

package/lib/src/managers/ExportManager.js

@@ -182,6 +182,14 @@ class ExportManager extends BaseManager {
                 return new NonePdfProvider(`ngdpbase.export.pdf.provider '${name}' is not a PDF provider: use ${PDF_PROVIDERS.join(', ')}`);
         }
     }
+    /**
+     * Is a PDF provider chosen (#2120)? The Export action offers PDF only then.
+     * Whether the chosen one works is known only by rendering, as before.
+     */
+    isPdfConfigured() {
+        const name = this.engine.getManager('ConfigurationManager')?.getProperty('ngdpbase.export.pdf.provider', PDF_DEFAULTS.provider);
+        return (name ?? PDF_DEFAULTS.provider) !== 'none';
+    }
     /** Log why, flag the manager (unless something worse is already shown), and refuse. */
     pdfUnavailable(reason) {
         logger.warn(`[ExportManager] PDF export unavailable: ${reason}`);
@@ -248,6 +256,23 @@ class ExportManager extends BaseManager {
         if (!page) {
             throw new Error(`Page '${pageName}' not found`);
         }
+        return this.renderPageDocument(pageName, page, user);
+    }
+    /**
+     * One page as a complete HTML document: its content rendered, with the
+     * export's styling and metadata footer. It reads nothing: the caller has
+     * read the page through its door (the page export source, #2120).
+     *
+     * @param pageName - The page's name, its heading
+     * @param page - Its content and metadata
+     * @param user - User object for locale-aware formatting
+     * @returns The HTML document
+     */
+    async renderPageDocument(pageName, page, user = null) {
+        const renderingManager = this.engine.getManager('RenderingManager');
+        if (!renderingManager) {
+            throw new Error('Required managers not available');
+        }
         // Render the page content (without user context for exports)
         const renderedContent = await renderingManager.renderMarkdown(page.content, pageName, null);
         // Create full HTML document