@jwilleke/ngdpbase-types 5.41.1 → 5.42.0

package/lib/src/managers/AuthManager.js

@@ -12,7 +12,8 @@
  * multi-factor flow, the per-role check and the boot refusal follow under #1523.
  *
  * Built-in providers, each gated on its own config key and all registered
- * through the public {@link AuthManager.registerProvider} (#1050):
+ * through registerCoreProvider(), which shares the checks of the public
+ * {@link AuthManager.registerProvider} (#1050):
  *   - PasswordAuthProvider          (unless ngdpbase.auth.password.enabled is false)
  *   - MagicLinkAuthProvider         (ngdpbase.auth.magic-link.enabled)
  *   - OidcAuthProvider, one per entry (ngdpbase.auth.oidc.providers; the old
@@ -21,15 +22,16 @@
  *   - AuthentikBearerAuthProvider   (ngdpbase.auth.authentik-bearer.enabled)
  *   - AgentTokenAuthProvider        (ngdpbase.auth.agent-token.enabled)
  *
- * Addons register through the same method, so the contributed path is the one
- * exercised on every boot rather than a second, less-travelled one.
+ * Addons register through registerProvider(), so the contributed path is the one
+ * exercised on every boot rather than a second, less-travelled one. Core's ids
+ * and the `oidc:` prefix are reserved for core there (#2223).
  *
  * Future providers (see #421):
  *   - TotpAuthProvider
  *
  * @see {@link https://github.com/jwilleke/ngdpbase/issues/396}
  */
-import { CONSENT_PATH } from '../types/Consent.js';
+import { CONSENT_PATH, REMEMBER_BROWSER_CONSENT_SCOPE } from '../types/Consent.js';
 import BaseManager from './BaseManager.js';
 import { PasswordAuthProvider } from '../providers/PasswordAuthProvider.js';
 import { MagicLinkAuthProvider, EMAIL_FACTOR } from '../providers/MagicLinkAuthProvider.js';
@@ -43,11 +45,13 @@ import { OidcBearerAuthProvider } from '../providers/OidcBearerAuthProvider.js';
 import { AgentTokenAuthProvider } from '../providers/AgentTokenAuthProvider.js';
 import logger from '../utils/logger.js';
 import LocaleUtils from '../utils/LocaleUtils.js';
-import { describeBrowser } from '../utils/browserDescription.js';
+import { browserIdentity, describeBrowser, sameBrowser } from '../utils/browserDescription.js';
 import { approximateLocation } from '../utils/ipLocation.js';
-import { createHash, createPrivateKey, randomBytes, randomUUID } from 'node:crypto';
+import { createHash, createPrivateKey, createPublicKey, randomBytes, randomUUID, verify as verifySignature } from 'node:crypto';
 import FileCredentialsProvider from '../providers/FileCredentialsProvider.js';
 import { PasskeyAuthProvider, relyingPartyFrom } from '../providers/PasskeyAuthProvider.js';
+import { TotpAuthProvider } from '../providers/TotpAuthProvider.js';
+import QRCode from 'qrcode';
 import { CREDENTIALS_KEY_ENV } from '../providers/BaseCredentialsProvider.js';
 import { recordAuditEvent } from '../utils/auditEvents.js';
 import { actorOf } from '../context/ActorContext.js';
@@ -87,12 +91,25 @@ const allowsProvider = (allowed, providerId) => !allowed || allowed.length === 0
  * provider. The second step runs it itself, so it needs no registered provider.
  */
 const EMAIL_LINK_ENTRY = 'magic-link';
+/**
+ * Every provider id core registers on some site (#1523 Q1), whether or not
+ * this one has it on. An entry naming one is never a typo: a provider that is
+ * off here, such as passkeys without an https base-url, is treated as off.
+ * `oidc:<name>` ids are known from `ngdpbase.auth.oidc.providers` instead.
+ */
+const CORE_PROVIDER_IDS = [
+    'password', 'magic-link', 'passkey', 'totp', 'cloudflare-access', 'authentik-bearer', 'agent-token', 'oidc-bearer'
+];
+/** Ids only core may register (#2223): every core id, and any `oidc:<name>`. */
+function isReservedProviderId(id) {
+    return CORE_PROVIDER_IDS.includes(id) || id.startsWith('oidc:');
+}
 /** 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
  * enrolled one (#1690): the provider id, and the credential kind it needs.
  */
-const ENROLLED_FACTORS = { passkey: 'passkey' };
+const ENROLLED_FACTORS = { passkey: 'passkey', totp: 'totp' };
 /**
  * The factor type each RFC 8176 `amr` value gives. Values not listed give no
  * type: `user` (a presence test), `mfa`, `mca`, `rba`, `geo`, `wia` describe a
@@ -153,6 +170,28 @@ export function credentialLabel(label) {
         throw new Error('Give it a name, so you can tell it apart from your others');
     return tidy;
 }
+const KNOWN_DEVICE_DEFAULT_DAYS = 30;
+/** What a remembered browser signs: this, then the challenge. Separates the signature from any other use of the key. */
+export const KNOWN_DEVICE_SIGNED_PREFIX = 'ngdpbase known device v1\n';
+/** The same factors, in any order (#1523). */
+function sameAmr(a, b) {
+    if (!a || a.length !== b.length)
+        return false;
+    const want = new Set(b);
+    return a.every((v) => want.has(v));
+}
+function parseDeviceSecret(secret) {
+    try {
+        const d = JSON.parse(secret);
+        return typeof d.publicKey === 'string' && typeof d.browser === 'string' && typeof d.os === 'string' && typeof d.platform === 'string' && typeof d.expiresAt === 'string'
+            ? { publicKey: d.publicKey, browser: d.browser, os: d.os, platform: d.platform, amr: Array.isArray(d.amr) ? d.amr.map(String) : [], expiresAt: d.expiresAt, ...(typeof d.generation === 'number' ? { generation: d.generation } : {}),
+                ...(typeof d.auditId === 'string' ? { auditId: d.auditId } : {}), ...(typeof d.signInMethod === 'string' ? { signInMethod: d.signInMethod } : {}) }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * The approval sentence (#1532, decided wording plus the IP and place):
  * "A sign-in request for Willeke Family was sent at 2 Oct 2026, 14:02 EDT
@@ -421,6 +460,12 @@ class AuthManager extends BaseManager {
     factorCache;
     /** The credentials store (#1524); null when it could not be opened. */
     credentials = null;
+    /**
+     * #421: TOTP, built for enrolment only. Not registered as a sign-in
+     * provider until the second-factor step can ask for it (slice 2b): offering
+     * it earlier would raise admins to AAL2 before they could use it.
+     */
+    totp = null;
     /** `ngdpbase.auth.credentials.file`, resolved at start: what a backup copies (#1876). */
     credentialsFile = null;
     constructor(engine) {
@@ -434,7 +479,7 @@ class AuthManager extends BaseManager {
         const configManager = this.engine.getManager('ConfigurationManager');
         // Register password provider if enabled (default: true)
         if (configManager?.getProperty('ngdpbase.auth.password.enabled', true) !== false) {
-            this.registerProvider(new PasswordAuthProvider(this.engine));
+            this.registerCoreProvider(new PasswordAuthProvider(this.engine));
         }
         // Register magic-link provider if enabled
         if (configManager?.getProperty('ngdpbase.auth.magic-link.enabled', false)) {
@@ -453,7 +498,7 @@ class AuthManager extends BaseManager {
             }
             else {
                 const ttlMinutes = configManager.getProperty('ngdpbase.auth.magic-link.ttl-minutes', 15);
-                this.registerProvider(new MagicLinkAuthProvider(this.engine, {
+                this.registerCoreProvider(new MagicLinkAuthProvider(this.engine, {
                     ttlMs: ttlMinutes * 60_000,
                     mailProvider: emailManager
                 }));
@@ -475,7 +520,7 @@ class AuthManager extends BaseManager {
                     defaultRole: configManager.getProperty('ngdpbase.auth.cloudflare-access.default-role', 'reader'),
                     groupMap: configManager.getProperty('ngdpbase.auth.cloudflare-access.group-map', {})
                 };
-                this.registerProvider(new CloudflareAccessAuthProvider(this.engine, cfConfig));
+                this.registerCoreProvider(new CloudflareAccessAuthProvider(this.engine, cfConfig));
                 logger.info(`[AuthManager] cloudflare-access team=${teamDomain}`);
             }
         }
@@ -499,7 +544,7 @@ class AuthManager extends BaseManager {
                     defaultRole: configManager.getProperty('ngdpbase.auth.authentik-bearer.default-role', 'reader'),
                     groupMap: configManager.getProperty('ngdpbase.auth.authentik-bearer.group-map', {})
                 };
-                this.registerProvider(new AuthentikBearerAuthProvider(this.engine, authentikConfig));
+                this.registerCoreProvider(new AuthentikBearerAuthProvider(this.engine, authentikConfig));
                 logger.info(`[AuthManager] authentik-bearer issuer=${issuer}`);
             }
         }
@@ -508,19 +553,20 @@ class AuthManager extends BaseManager {
         // so it registers whenever enabled, with no further required config. Both
         // bearer providers may be active at once; the middleware tries each.
         if (configManager?.getProperty('ngdpbase.auth.agent-token.enabled', false)) {
-            this.registerProvider(new AgentTokenAuthProvider(this.engine));
+            this.registerCoreProvider(new AgentTokenAuthProvider(this.engine));
         }
         // #1576: access tokens from this instance's own OpenID Connect provider,
         // for apps a person allowed. Verified by OidcManager when a request
         // arrives, so registering ahead of it is safe; with the provider off,
         // every token simply fails to verify.
         if (configManager?.getProperty('oidc-auth-server.enabled', false) === true) {
-            this.registerProvider(new OidcBearerAuthProvider(this.engine));
+            this.registerCoreProvider(new OidcBearerAuthProvider(this.engine));
         }
         this.factorEntries = this.readFactorEntries(configManager);
         this.factorCache = null;
         await this.openCredentialsStore(configManager);
         this.registerPasskeys(configManager);
+        this.openTotp(configManager);
         this.registerOidcProviders(configManager);
         this.warnIfEmailSecondFactorsDropped();
         logger.info(`[AuthManager] Initialized — factors: [${this.factorEntries.map(e => e.authproviderid).join(', ')}]`);
@@ -666,7 +712,7 @@ class AuthManager extends BaseManager {
                 continue;
             }
             const store = this.credentials;
-            this.registerProvider(new OidcAuthProvider({
+            this.registerCoreProvider(new OidcAuthProvider({
                 name, displayName: entry['display-name'] || preset?.displayName || name,
                 icon: resolveOutsideProviderIcon(name, entry.icon, preset ? entry.preset : undefined, m => logger.warn(m)), issuer, clientId, clientSecret, redirectUri, policy: egress.policy,
                 ...(preset?.responseMode ? { responseMode: preset.responseMode } : {}),
@@ -1145,12 +1191,78 @@ class AuthManager extends BaseManager {
             return;
         }
         const store = this.credentials;
-        this.registerProvider(new PasskeyAuthProvider(rp, {
+        this.registerCoreProvider(new PasskeyAuthProvider(rp, {
             find: (credentialId) => store.findBySubject('passkey', credentialId),
             used: (id, at, secret) => store.touch(id, at, secret)
         }));
         logger.info(`[AuthManager] passkeys tied to ${rp.rpID}`);
     }
+    /** TOTP enrolment (#421), available whenever the credentials store is open. */
+    openTotp(configManager) {
+        this.totp = null;
+        this.providers.delete('totp');
+        const store = this.credentials;
+        if (!store)
+            return;
+        const name = configManager?.getProperty('ngdpbase.application-name', 'ngdpbase');
+        const issuer = typeof name === 'string' && name ? name : 'ngdpbase';
+        this.totp = new TotpAuthProvider(process.env[CREDENTIALS_KEY_ENV] ?? '', issuer, {
+            rows: (username) => store.list(username).filter(r => r.kind === 'totp'),
+            used: (id, at, secret) => store.touch(id, at, secret)
+        });
+        // #421 slice 2b: registered, so its factor entry counts and the second step can ask for its code.
+        this.registerCoreProvider(this.totp);
+    }
+    /** Whether an authenticator app can be enrolled here (#421). */
+    totpAvailable() {
+        return this.totp !== null;
+    }
+    /**
+     * A new seed for `username` to add to an authenticator app (#421): the
+     * manual key, the `otpauth://` URI and that URI as an SVG QR code. Nothing
+     * is stored. `pending` is the seed sealed for this account: the caller keeps
+     * that, never the seed, (in the session) until a code confirms it. Refused
+     * while the account already has one.
+     */
+    async totpEnrolmentStart(ctx, username) {
+        const totp = await this.totpEnrolGate(ctx, username);
+        if (this.requireCredentialsStore().list(username).some(r => r.kind === 'totp')) {
+            throw new Error('This account already has an authenticator app; remove it before adding another');
+        }
+        const { seed, uri } = totp.newEnrolment(username);
+        const qrSvg = await QRCode.toString(uri, { type: 'svg', errorCorrectionLevel: 'M', margin: 2 });
+        return { seed, pending: totp.sealPending(username, seed), uri, qrSvg };
+    }
+    /**
+     * Confirm an enrolment with a code from the app and store the seed,
+     * encrypted (#421). Returns the credential id, or null when the code does
+     * not match, or when `pending` is not a seed `totpEnrolmentStart` sealed
+     * for this account. The confirming code is spent: it cannot also sign
+     * anyone in.
+     */
+    async totpEnrolmentConfirm(ctx, username, pending, code, label) {
+        const totp = await this.totpEnrolGate(ctx, username);
+        const name = credentialLabel(label || 'Authenticator app');
+        if (this.requireCredentialsStore().list(username).some(r => r.kind === 'totp')) {
+            throw new Error('This account already has an authenticator app; remove it before adding another');
+        }
+        const seed = totp.openPending(username, pending);
+        if (!seed)
+            return null;
+        const sealed = totp.confirmEnrolment(username, seed, code);
+        if (!sealed)
+            return null;
+        return this.storeCredential(ctx, username, { kind: 'totp', subject: randomUUID(), secret: sealed, label: name });
+    }
+    async totpEnrolGate(ctx, username) {
+        if (!(await this.mayManageCredentials(ctx, username)))
+            throw new Error('Permission denied');
+        if (!(await this.userMayUseProvider(username, 'totp')))
+            throw new Error('This account cannot sign in with an authenticator app');
+        if (!this.totp)
+            throw new Error('Authenticator apps are not available on this site');
+        return this.totp;
+    }
     passkeyProvider() {
         const p = this.providers.get('passkey');
         return p instanceof PasskeyAuthProvider ? p : null;
@@ -1295,6 +1407,7 @@ class AuthManager extends BaseManager {
     async listCredentials(ctx, username) {
         if (!(await this.mayManageCredentials(ctx, username, { viewOnly: true })))
             throw new Error('Permission denied');
+        await this.pruneRememberedDevices(username);
         // #1762: a proxy grant is not a sign-in method; it is listed and ended through the proxy-grant methods only.
         return this.requireCredentialsStore().list(username).filter(r => !NOT_SIGN_IN_METHODS.has(r.kind)).map(({ secret: _secret, ...view }) => view);
     }
@@ -1306,6 +1419,8 @@ class AuthManager extends BaseManager {
             throw new Error('A proxy grant is made with grantProxy (#1762)');
         if (input.kind === 'invitation')
             throw new Error('An invitation is sent with inviteUser (#2049)');
+        if (input.kind === 'totp')
+            throw new Error('An authenticator app is enrolled with totpEnrolmentConfirm, which encrypts its seed (#421)');
         return this.storeCredential(ctx, username, input);
     }
     /** Store and audit a credential the caller has already decided may be added; `how` says how it happened. */
@@ -1344,6 +1459,9 @@ class AuthManager extends BaseManager {
         const removed = await store.remove(id);
         if (removed)
             this.auditCredentialChange(ctx, username, 'credential-remove', row);
+        // Q5: removing a remembered browser withdraws the agreement to remember it.
+        if (removed && row.kind === 'device')
+            await this.withdrawRememberConsent(ctx, username, row.subject, 'removed');
         return removed;
     }
     /**
@@ -2172,14 +2290,22 @@ class AuthManager extends BaseManager {
         const aal = fromAmr > fromAcr ? fromAmr : fromAcr;
         return hardwareVerified ? { amr, aal, acr: 'phrh' } : { amr, aal };
     }
-    /** The audit record of one sign-in method's check (#1758): written here, never by a route. */
-    async auditCheck(attempt, username, method, result, reason, reported) {
+    /**
+     * The audit record of one sign-in method's check (#1758): written here, never
+     * by a route. Returns the record's id when it was recorded (#1523).
+     */
+    async auditCheck(attempt, username, method, result, reason, more = {}) {
         try {
             const audit = this.engine.getManager('AuditManager');
-            await audit?.logAuthentication?.({ username: username ?? 'unknown', ipAddress: attempt.ipAddress, userAgent: attempt.userAgent, loginMethod: method, ...(reported ? { reported } : {}) }, result, reason);
+            const recorded = await audit?.logAuthentication?.({
+                username: username ?? 'unknown', ipAddress: attempt.ipAddress, userAgent: attempt.userAgent, loginMethod: method,
+                ...(more.reported ? { reported: more.reported } : {}), ...(more.knownDevice ? { knownDevice: true } : {}), ...(more.amr ? { amr: more.amr } : {})
+            }, result, reason);
+            return typeof recorded?.id === 'string' ? recorded.id : undefined;
         }
         catch (err) {
             logger.warn('[AuthManager] audit record failed for an authentication check:', err);
+            return undefined;
         }
     }
     /** Each role's `required-aal`, and whether the operator set it, read through the catalogue's owner (#1523, #448). */
@@ -2287,6 +2413,48 @@ class AuthManager extends BaseManager {
             .filter(({ aal }) => aal > reachable)
             .map(({ role, aal, operatorSet }) => `role '${role}' requires AAL${aal} (${operatorSet ? 'set in app-custom-config.json' : 'shipped default'}), but the available sign-in factors reach AAL${reachable} — ngdpbase.auth.factors offers: ${offered}`);
     }
+    /**
+     * The start-up check of the `ngdpbase.auth.factors` ids, once add-ons have
+     * registered their providers (#1523 Q1, operator 2026-10-31). An id no
+     * provider could ever register, such as a typo, refuses the boot when its
+     * entry is on, and only warns when it is `enabled: false`. Returns the
+     * problems that must refuse the boot.
+     */
+    checkFactorIds() {
+        const { refused, ignored } = this.unknownFactorIds(this.factorEntries);
+        for (const problem of ignored)
+            logger.warn(`[AuthManager] ${problem}. The entry is off, so it is ignored. (#1523)`);
+        return refused;
+    }
+    /**
+     * The same check for a value the configuration screen is about to save as
+     * `ngdpbase.auth.factors` (#1523), so a typo is refused there rather than
+     * at the next restart, which would refuse to start. `refused` names each
+     * enabled unknown id; `ignored` each one whose entry is `enabled: false`.
+     */
+    checkFactorEntries(value) {
+        const entries = (Array.isArray(value) ? value : [])
+            .filter((e) => typeof e === 'object' && e !== null && typeof e.authproviderid === 'string')
+            .map(e => ({ ...e, authproviderid: FACTOR_ALIASES[e.authproviderid] ?? e.authproviderid }));
+        return this.unknownFactorIds(entries);
+    }
+    /** The entries whose id no provider could ever register, split by whether the entry is on. */
+    unknownFactorIds(entries) {
+        const raw = this.engine.getManager('ConfigurationManager')?.getUnresolvedProperty?.('ngdpbase.auth.oidc.providers', {});
+        const oidcNames = raw && typeof raw === 'object' && !Array.isArray(raw) ? Object.keys(raw) : [];
+        // `oidc:google` is also what the old ngdpbase.auth.google-oidc.* keys register.
+        const known = new Set([...CORE_PROVIDER_IDS, 'oidc:google', ...oidcNames.map(n => `oidc:${n}`), ...this.providers.keys()]);
+        const knownIds = [...known].sort().join(', ');
+        const refused = [];
+        const ignored = [];
+        for (const entry of entries) {
+            if (known.has(entry.authproviderid))
+                continue;
+            const problem = `ngdpbase.auth.factors entry '${entry.authproviderid}' names no provider. Known ids: ${knownIds}`;
+            (entry.enabled === false ? ignored : refused).push(problem);
+        }
+        return { refused, ignored };
+    }
     /**
      * The start-up check, once add-ons have registered their providers (#1523,
      * #448). Returns the problems that must refuse the boot: a level the operator
@@ -2564,7 +2732,7 @@ class AuthManager extends BaseManager {
             ?? (how.unlockWith && this.vaultUnlocker ? await this.vaultUnlocker(username, how.unlockWith.password) : undefined);
         if (handle)
             req.session.privateStoreHandle = handle;
-        await this.auditCheck({ ipAddress: req.ip, userAgent: req.get?.('user-agent'), purpose: 'sign-in' }, username, how.method, 'success', `signed in: ${how.method}`, result.reported);
+        const auditId = await this.auditCheck({ ipAddress: req.ip, userAgent: req.get?.('user-agent'), purpose: 'sign-in' }, username, how.method, 'success', `signed in: ${how.method}`, { reported: result.reported, knownDevice: result.knownDevice, ...(record ? { amr: record.amr } : {}) });
         try {
             await this.engine.getManager('UserManager')?.recordSignIn?.(username);
         }
@@ -2587,9 +2755,9 @@ class AuthManager extends BaseManager {
         // (consentPending, the consent gate) until they accept or sign out.
         if (await this.termsPendingFor(username)) {
             req.session.consentPending = true;
-            return { next: `${CONSENT_PATH}?returnTo=${encodeURIComponent(next ?? safeRedirect(how.returnTo))}` };
+            return { next: `${CONSENT_PATH}?returnTo=${encodeURIComponent(next ?? safeRedirect(how.returnTo))}`, ...(auditId ? { auditId } : {}) };
         }
-        return next ? { next } : {};
+        return { ...(next ? { next } : {}), ...(auditId ? { auditId } : {}) };
     }
     /**
      * Whether `username` has core documents to accept (#1603), asked of
@@ -2691,7 +2859,7 @@ class AuthManager extends BaseManager {
         if (!result.success || !result.provider || result.viaToken)
             return null;
         const factors = result.factors ?? [];
-        return { provider: result.provider, factors, ...this.assess(factors), at: new Date().toISOString() };
+        return { provider: result.provider, factors, ...this.assess(factors), ...(result.knownDevice ? { knownDevice: true } : {}), at: new Date().toISOString() };
     }
     /**
      * Step-up (#1525): which permissions ask for a fresh factor, and how fresh.
@@ -2720,9 +2888,9 @@ class AuthManager extends BaseManager {
     warnedLegacyStepUp = false;
     /**
      * Whether `permission` needs a fresher factor than `signIn` holds (#1525).
-     * Fresh: a factor satisfied within the step-up window that reaches the
-     * level the person's roles require (at least 1 — a known device, aal 0,
-     * never counts). A delegated credential has no sign-in of its own, so it
+     * Fresh: the factors satisfied within the step-up window together reach
+     * the level the person's roles require (at least 1 — a known device, aal 0,
+     * never counts); a password and an authenticator code reach AAL2 (#421). A delegated credential has no sign-in of its own, so it
      * never satisfies step-up.
      */
     stepUpNeeded(permission, signIn, roles, delegated, now = Date.now(), cap) {
@@ -2746,7 +2914,11 @@ class AuthManager extends BaseManager {
             return false;
         const need = Math.max(this.requiredAalFor(roles, cap), 1);
         const since = now - maxAgeMs;
-        return (signIn?.factors ?? []).some((f) => f.aal >= need && Date.parse(f.at) >= since);
+        // #421 slice 2c: the factors satisfied within the window, together — a
+        // password and an authenticator code reach AAL2 as at sign-in. A known
+        // device (aal 0) never counts.
+        const fresh = (signIn?.factors ?? []).filter((f) => f.aal >= 1 && Date.parse(f.at) >= since);
+        return fresh.length > 0 && this.assess(fresh).aal >= need;
     }
     /**
      * A session's sign-in after a re-authentication (#1525): the new factors
@@ -3090,9 +3262,9 @@ class AuthManager extends BaseManager {
     /**
      * 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.
+     * by `preference`. Only what the second step can run is offered — the
+     * email link and an authenticator app (#421) — 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) ?? [];
@@ -3103,6 +3275,9 @@ class AuthManager extends BaseManager {
                     out.push({ id: 'email-link', label: 'Email link', target: maskEmail(r.subject) });
                 }
             }
+            if (id === 'totp' && this.totp && rows.some((c) => c.kind === 'totp')) {
+                out.push({ id: 'totp', label: 'Authenticator app', target: '' });
+            }
         }
         return out;
     }
@@ -3152,7 +3327,13 @@ class AuthManager extends BaseManager {
         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));
+        const roles = (await pip?.subjectFor(username))?.roles ?? [];
+        const requiredAal = this.requiredAalFor(roles, await this.aalCapFor(username));
+        // #1523 slice 1c: the roles' declared levels, not lowered to what the site
+        // or the account can reach (#1690), so an admin who cannot reach AAL2 yet
+        // is still never let past the prompt by a remembered browser.
+        const declared = new Map(this.requiredLevels().map(({ role, aal }) => [role, aal]));
+        const rolesAal = roles.reduce((max, r) => Math.max(max, declared.get(r) ?? 0), 0);
         this.sweepPending();
         const handle = randomBytes(24).toString('base64url');
         const now = Date.now();
@@ -3168,7 +3349,8 @@ class AuthManager extends BaseManager {
             requestUserAgent: ctx.userAgent,
             requestLocation: ctx.location ?? null,
             privateStoreHandle: ctx.privateStoreHandle,
-            requiredAal
+            requiredAal,
+            rolesAal
         });
         // #1532: an expiry is recorded when it happens, not when someone next looks.
         setTimeout(() => this.expirePending(handle), PENDING_SIGN_IN_TTL_MS + 1).unref?.();
@@ -3361,6 +3543,62 @@ class AuthManager extends BaseManager {
         await this.recordApproval(AUDIT_EVENT.SIGNINAPPROVAL_APPROVE, p, 'success', presser);
         return p.username;
     }
+    /**
+     * The authenticator app's code for the waiting sign-in (#421 slice 2b). Its
+     * check goes through `authenticate`, which records a wrong code as a failed
+     * sign-in; a right one approves the pending sign-in, which `completeTwoStep`
+     * then finishes with both factors. `unavailable` when the sign-in is gone,
+     * already decided, or the account has no authenticator app offered here.
+     * The caller throttles wrong codes as it does wrong passwords.
+     */
+    async approveByTotp(handle, binding, code, from = {}) {
+        const p = this.pendingSignIn(handle, binding);
+        if (!p || p.approved || p.denied)
+            return 'unavailable';
+        if (!this.secondFactorsFor(p.username, p).some((f) => f.id === 'totp'))
+            return 'unavailable';
+        const result = await this.authenticate('totp', { username: p.username, code }, { ipAddress: from.ip, userAgent: from.userAgent, purpose: 'sign-in' });
+        const factor = result.factors?.[0];
+        if (!result.success || result.username !== p.username || !factor)
+            return 'wrong';
+        // The code may have taken a moment; the sign-in may have been cancelled or expired meanwhile.
+        if (!this.pendingSignIn(handle, binding) || p.approved || p.denied)
+            return 'unavailable';
+        p.approved = factor;
+        return 'approved';
+    }
+    /**
+     * Whether step-up offers `username` the authenticator app's code (#421
+     * slice 2c): as at the second step, an app enrolled and its
+     * `ngdpbase.auth.factors` entry enabled.
+     */
+    stepUpTotpOffered(username) {
+        return this.secondFactorsFor(username).some((f) => f.id === 'totp');
+    }
+    /**
+     * Step-up with the authenticator app (#421 slice 2c). The code is checked
+     * through `authenticate`, as at the second step of sign-in, so a wrong one
+     * is recorded as a failed re-check. With `password` (a role that needs
+     * AAL2), the password is checked first, and the result carries both
+     * factors, which together reach AAL2. `unavailable` when the app is not
+     * offered here. The caller throttles wrong answers as it does wrong passwords.
+     */
+    async reauthenticateByTotp(username, code, password, attempt = {}) {
+        if (!this.stepUpTotpOffered(username))
+            return 'unavailable';
+        const recheck = { ...attempt, purpose: 're-check' };
+        const factors = [];
+        if (password !== null) {
+            const first = password ? await this.authenticate('password', { username, password }, recheck) : { success: false };
+            if (!first.success || first.username !== username)
+                return { success: false };
+            factors.push(...(first.factors ?? []));
+        }
+        const otp = await this.authenticate('totp', { username, code }, recheck);
+        if (!otp.success || otp.username !== username)
+            return { success: false };
+        return { ...otp, factors: [...factors, ...(otp.factors ?? [])] };
+    }
     /** Refuse the waiting sign-in from its link (Deny). Returns the username, or null. */
     async denyByToken(token, presser) {
         const entry = this.approvalTokens.get(token);
@@ -3382,16 +3620,290 @@ class AuthManager extends BaseManager {
      */
     completeTwoStep(handle, binding) {
         const p = this.pendingSignIn(handle, binding);
-        if (!p?.approved || p.denied)
+        if (!p || p.denied)
+            return null;
+        // #1523 slice 1c: a remembered browser completes it with only the factors
+        // entered, and only while the person's roles still allow the skip.
+        const known = !p.approved && Boolean(p.knownDevice) && this.knownDeviceMaySkip(p);
+        if (!p.approved && !known)
             return null;
         this.pendingSignIns.delete(handle);
         for (const [token, entry] of this.approvalTokens)
             if (entry.handle === handle)
                 this.approvalTokens.delete(token);
+        if (known)
+            return { result: { ...p.first, knownDevice: true }, privateStoreHandle: p.privateStoreHandle };
         return {
             result: { ...p.first, factors: [...(p.first.factors ?? []), p.approved] },
-            privateStoreHandle: p.privateStoreHandle
+            privateStoreHandle: p.privateStoreHandle,
+            // Offered only where the skip could ever apply; see rememberOffered.
+            ...(p.remember && this.rememberOffered(p) ? { remember: p.remember } : {})
+        };
+    }
+    // ── Known devices (#1523 slice 1c) ──────────────────────────────────────
+    //
+    // A remembered browser holds a non-extractable ECDSA P-256 key (WebCrypto)
+    // in IndexedDB; the site keeps the public half as a `device` row. At the
+    // second step it signs a one-time challenge. That skips the prompt, never
+    // raises the level (Q4: no carry-forward), and only for a person whose roles
+    // the factors entered already satisfy (operator, 2026-11-01).
+    /** How many days a remembered browser stays remembered: `ngdpbase.auth.known-device.remember-days`; 0 turns remembering off. */
+    rememberDays() {
+        const cm = this.engine.getManager('ConfigurationManager');
+        const days = Number(cm?.getProperty('ngdpbase.auth.known-device.remember-days', KNOWN_DEVICE_DEFAULT_DAYS));
+        return Number.isFinite(days) && days > 0 ? Math.min(days, 400) : 0;
+    }
+    /**
+     * Whether a remembered browser may skip this sign-in's second step: the
+     * factors entered already reach the highest `required-aal` among the
+     * person's roles (operator, 2026-11-01). A person whose roles need AAL2 is
+     * always asked.
+     */
+    knownDeviceMaySkip(p) {
+        if (this.rememberDays() === 0 || p.rolesAal === undefined)
+            return false;
+        const record = this.signInRecord(p.first);
+        return Boolean(record) && record.aal >= Math.max(p.rolesAal, 1);
+    }
+    /** Whether "Remember this browser" is offered at this second step: only where it could ever skip one. */
+    rememberOffered(p) {
+        return this.knownDeviceMaySkip(p);
+    }
+    /** "Remember this browser" was ticked at the second step, having been shown `version` of its page. */
+    noteRemember(handle, binding, version) {
+        const p = this.pendingSignIn(handle, binding);
+        if (p && this.rememberOffered(p) && /^[\w.-]{1,40}$/.test(version))
+            p.remember = { version };
+    }
+    /**
+     * When a remembered browser stops skipping the prompt: its stored expiry,
+     * or its creation plus the current `remember-days`, whichever is sooner,
+     * so lowering the setting shortens browsers already remembered.
+     */
+    deviceExpiry(row, device) {
+        const created = Date.parse(row.createdAt);
+        const now = Number.isFinite(created) ? created + this.rememberDays() * 86_400_000 : 0;
+        return Math.min(Date.parse(device.expiresAt), now);
+    }
+    /**
+     * `username`'s remembered browsers that have not expired. With the
+     * account's password-change `generation`, also only those remembered
+     * since the last password change (#1482).
+     */
+    rememberedDevices(username, now = Date.now(), generation) {
+        const out = [];
+        for (const row of this.credentials?.list(username) ?? []) {
+            if (row.kind !== 'device')
+                continue;
+            const device = parseDeviceSecret(row.secret);
+            if (!device || this.deviceExpiry(row, device) <= now)
+                continue;
+            if (generation !== undefined && (device.generation ?? 0) !== generation)
+                continue;
+            out.push({ row, device });
+        }
+        return out;
+    }
+    async accountGeneration(username) {
+        const account = await this.engine.getManager('UserManager')?.getUser(username);
+        return sessionGenerationOf(account);
+    }
+    /**
+     * Drop `username`'s remembered browsers that no longer count: expired,
+     * unreadable, or remembered before the last password change. Each is
+     * recorded as `credential-remove` and its consent withdrawn. Returns the
+     * ones that still count.
+     */
+    async pruneRememberedDevices(username, now = Date.now()) {
+        if (!this.credentials)
+            return [];
+        const generation = await this.accountGeneration(username);
+        const live = this.rememberedDevices(username, now, generation);
+        const dead = this.credentials.list(username).filter((r) => r.kind === 'device' && !live.some((d) => d.row.id === r.id));
+        for (const row of dead) {
+            const device = parseDeviceSecret(row.secret);
+            const why = device && this.deviceExpiry(row, device) > now ? 'password-changed' : 'expired';
+            const ctx = systemContext(this.engine, `remembered browser ${row.id} of ${username}: ${why}`);
+            if (!(await this.credentials.remove(row.id)))
+                continue;
+            this.auditCredentialChange(ctx, username, 'credential-remove', row, why);
+            await this.withdrawRememberConsent(ctx, username, row.subject, why);
+        }
+        return live;
+    }
+    /** Withdraw the "remember this browser" consent bound to `deviceId`; a failure is logged, the browser stays removed. */
+    async withdrawRememberConsent(ctx, username, deviceId, why) {
+        const consent = this.engine.getManager('ConsentManager');
+        try {
+            await consent?.withdraw(username, REMEMBER_BROWSER_CONSENT_SCOPE, deviceId, ctx, why);
+        }
+        catch (err) {
+            logger.error(`[AuthManager] remembered browser of ${username} removed (${why}), but its consent could not be withdrawn:`, err);
+        }
+    }
+    /**
+     * A one-time challenge for a remembered browser to sign, or null when the
+     * skip cannot apply (the roles need more, or no browser is remembered).
+     * A new challenge replaces the last.
+     */
+    knownDeviceChallenge(handle, binding) {
+        const p = this.pendingSignIn(handle, binding);
+        if (!p || p.approved || p.denied || !this.knownDeviceMaySkip(p))
+            return null;
+        if (this.rememberedDevices(p.username).length === 0)
+            return null;
+        p.deviceChallenge = randomBytes(32).toString('base64url');
+        return p.deviceChallenge;
+    }
+    /**
+     * A remembered browser's answer to the challenge (#1523 slice 1c). It
+     * counts only when the device is this person's, has not expired, the
+     * signature over the challenge verifies with its public key, and the
+     * browser and system still match what it was issued to, and the audit
+     * record its row names says the same as the row (#1523, operator
+     * 2026-10-31). Any failure is recorded and the prompt stays. A row whose
+     * audit record is missing or disagrees is also a security event; a row
+     * remembered before rows named their record is removed, so the browser is
+     * asked once and may be remembered again. The challenge is spent either way.
+     */
+    async proveKnownDevice(handle, binding, deviceId, signature, from) {
+        const p = this.pendingSignIn(handle, binding);
+        const challenge = p?.deviceChallenge;
+        if (p)
+            delete p.deviceChallenge;
+        if (!p || !challenge || p.approved || p.denied || !this.knownDeviceMaySkip(p))
+            return false;
+        const fail = async (reason) => {
+            await this.auditCheck({ ipAddress: from.ip, userAgent: from.userAgent, purpose: 'sign-in' }, p.username, 'known device', 'failure', `remembered browser not accepted: ${reason}`);
+            return false;
+        };
+        const found = (await this.pruneRememberedDevices(p.username)).find((d) => d.row.subject === deviceId);
+        if (!found)
+            return fail('no remembered browser of this account with that id, or it expired');
+        const now = browserIdentity(from.userAgent, from.platformHint);
+        if (!now || !sameBrowser(now, found.device))
+            return fail('a different browser or system from the one it was issued to');
+        let ok;
+        try {
+            const key = createPublicKey({ key: Buffer.from(found.device.publicKey, 'base64url'), format: 'der', type: 'spki' });
+            ok = verifySignature('sha256', Buffer.from(KNOWN_DEVICE_SIGNED_PREFIX + challenge, 'utf8'), { key, dsaEncoding: 'ieee-p1363' }, Buffer.from(signature, 'base64url'));
+        }
+        catch {
+            ok = false;
+        }
+        if (!ok)
+            return fail('the signature did not verify');
+        // After the signature, so only the browser holding the key can raise this.
+        const disagreement = await this.deviceRecordDisagreement(p.username, found.device);
+        if (disagreement === 'no record named') {
+            const ctx = systemContext(this.engine, `remembered browser ${found.row.id} of ${p.username}: remembered before rows named their sign-in record`);
+            if (await this.credentials?.remove(found.row.id)) {
+                this.auditCredentialChange(ctx, p.username, 'credential-remove', found.row, 'no-sign-in-record');
+                await this.withdrawRememberConsent(ctx, p.username, found.row.subject, 'no-sign-in-record');
+            }
+            return fail('remembered before rows named their sign-in record; asked once, and it may be remembered again');
+        }
+        if (disagreement) {
+            void recordAuditEvent(this.engine.getManager('AuditManager'), {
+                eventType: AUDIT_EVENT.SECURITY_EVENT,
+                user: p.username,
+                ipAddress: from.ip,
+                action: 'remembered-browser-record-mismatch',
+                result: 'deny',
+                severity: 'high',
+                resource: found.row.id,
+                resourceType: 'credential',
+                reason: `remembered browser ${found.row.id} of ${p.username} treated as unknown: ${disagreement}`,
+                metadata: { securityEventType: 'remembered-browser-record-mismatch', credentialId: found.row.id, auditId: found.device.auditId, userAgent: from.userAgent }
+            });
+            return fail(disagreement);
+        }
+        p.knownDevice = found.row.id;
+        await this.credentials?.touch(found.row.id, new Date().toISOString());
+        return true;
+    }
+    /**
+     * How a remembered browser's row disagrees with the audit record it names
+     * (#1523), or null when they agree: the record is the account's sign-in,
+     * made the way the row says, with the same factors. `'no record named'` for
+     * a row remembered before rows named one.
+     */
+    async deviceRecordDisagreement(username, device) {
+        if (!device.auditId)
+            return 'no record named';
+        const audit = this.engine.getManager('AuditManager');
+        const record = await audit?.authenticationRecord?.(device.auditId);
+        if (!record)
+            return `its sign-in record ${device.auditId} was not found`;
+        if (record.user !== username)
+            return `its sign-in record ${device.auditId} is another account's`;
+        if (record.loginMethod !== device.signInMethod)
+            return `its sign-in record ${device.auditId} names a different way of signing in`;
+        if (!sameAmr(record.amr, device.amr))
+            return `its sign-in record ${device.auditId} names different factors`;
+        return null;
+    }
+    /**
+     * Remember this browser for `ctx`'s person (#1523 slice 1c, Q5): the
+     * consent record first, bound to the device id, then the `device` row with
+     * the public key, the browser and system, and when it expires. Refused
+     * when the key is not an ECDSA P-256 public key, the browser cannot be
+     * told, the page changed since it was shown, or consent cannot be recorded.
+     * The row names the audit record of the sign-in (`auditId`, from
+     * `completeSignIn`), which must be readable and be this person's sign-in
+     * with these factors; otherwise nothing is remembered (#1523).
+     */
+    async rememberBrowser(ctx, input) {
+        const days = this.rememberDays();
+        if (!this.credentials || days === 0)
+            return null;
+        const identity = browserIdentity(input.userAgent, input.platformHint);
+        if (!identity)
+            return null;
+        const audit = this.engine.getManager('AuditManager');
+        const signIn = input.auditId ? await audit?.authenticationRecord?.(input.auditId) : null;
+        if (!signIn || signIn.user !== ctx.username || !sameAmr(signIn.amr, input.amr)) {
+            logger.warn(`[AuthManager] ${ctx.username} asked to remember a browser, but the audit record of the sign-in could not be read or does not match; not remembered (#1523)`);
+            return null;
+        }
+        let spki;
+        try {
+            const key = createPublicKey({ key: Buffer.from(input.publicKey, 'base64url'), format: 'der', type: 'spki' });
+            if (key.asymmetricKeyType !== 'ec' || key.asymmetricKeyDetails?.namedCurve !== 'prime256v1')
+                return null;
+            spki = key.export({ format: 'der', type: 'spki' });
+        }
+        catch {
+            return null;
+        }
+        const deviceId = createHash('sha256').update(spki).digest('base64url');
+        // A key is made fresh for each remembering, so its id is new; one already
+        // stored under it (another account's included) is never replaced.
+        if (this.credentials.findBySubject('device', deviceId))
+            return null;
+        const consent = this.engine.getManager('ConsentManager');
+        const doc = (await consent?.documents(REMEMBER_BROWSER_CONSENT_SCOPE))?.[0];
+        if (!consent || !doc || String(doc.version) !== input.version)
+            return null;
+        try {
+            await consent.accept(ctx, REMEMBER_BROWSER_CONSENT_SCOPE, [{ id: doc.id, version: String(doc.version) }], 'sign-in', deviceId);
+        }
+        catch (err) {
+            logger.warn(`[AuthManager] ${ctx.username} asked to remember a browser, but the consent could not be recorded; not remembered:`, err);
+            return null;
+        }
+        const now = new Date();
+        const secret = {
+            publicKey: spki.toString('base64url'),
+            ...identity,
+            amr: input.amr,
+            expiresAt: new Date(now.getTime() + days * 86_400_000).toISOString(),
+            generation: await this.accountGeneration(ctx.username),
+            auditId: signIn.id,
+            ...(signIn.loginMethod !== undefined ? { signInMethod: signIn.loginMethod } : {})
         };
+        await this.storeCredential(ctx, ctx.username, { kind: 'device', subject: deviceId, secret: JSON.stringify(secret), label: `${identity.browser} on ${identity.os}` }, 'remember this browser');
+        return { deviceId };
     }
     /**
      * The waiting browser gave up the sign-in (Cancel, #1532): dropped, its
@@ -3649,9 +4161,11 @@ class AuthManager extends BaseManager {
     /**
      * Register an authentication provider (#1050).
      *
-     * The built-ins call this during `initialize()`, so the path an addon uses is
-     * the path exercised on every boot rather than a second, less-travelled one.
-     * Config gating stays with the caller: this method decides nothing about
+     * The built-ins register during `initialize()` through registerCoreProvider(),
+     * which shares every check below except the reserved ids, so the path an addon
+     * uses is the path exercised on every boot rather than a second, less-travelled
+     * one. Core ids and the `oidc:` prefix are reserved: an addon registering one is
+     * refused, whether or not core registered it on this site (#2223). Config gating stays with the caller: this method decides nothing about
      * whether a provider *should* be active, only that it is.
      *
      * ## Duplicate ids: first registration wins
@@ -3679,33 +4193,62 @@ class AuthManager extends BaseManager {
      * otherwise here would be worse than the gap.
      *
      * @param provider the provider to register
-     * @param source   attribution for logs — an addon name, or 'built-in'
-     * @returns true if registered; false if rejected as malformed or duplicate
+     * @param source   attribution for logs: the add-on's name
+     * @returns true if registered; false if rejected as reserved, malformed or duplicate
      */
-    registerProvider(provider, source = 'built-in') {
+    registerProvider(provider, source = 'an add-on') {
+        // #2223: core's ids and the oidc: prefix are core's alone, registered
+        // through registerCoreProvider() in initialize(). An add-on claiming one
+        // would bring its own verify() and AAL under a name the factors config
+        // trusts, on a site where core left that id unregistered.
+        // The id must be a plain own property, read once, and only that value is
+        // checked and stored: a getter could pass the check as one id and register
+        // as another.
+        const idProperty = provider ? Object.getOwnPropertyDescriptor(provider, 'id') : undefined;
+        if (provider && idProperty && !('value' in idProperty)) {
+            logger.error(`[AuthManager] Rejected provider from ${source}: its id must be a plain property, not a getter`);
+            return false;
+        }
+        const id = idProperty?.value;
+        if (typeof id === 'string' && isReservedProviderId(id)) {
+            logger.error(`[AuthManager] Rejected provider '${id}' from ${source}: core provider ids ` +
+                `(${CORE_PROVIDER_IDS.join(', ')}) and the 'oidc:' prefix are reserved for core`);
+            return false;
+        }
+        return this.addProvider(provider, id, source);
+    }
+    /**
+     * Core's own registrations (#2223): the one way a reserved id gets in. Called
+     * only from initialize() and the helpers it runs; add-ons get the AuthManager
+     * through the engine and call registerProvider(), which refuses these ids.
+     */
+    registerCoreProvider(provider) {
+        return this.addProvider(provider, provider?.id, 'built-in');
+    }
+    addProvider(provider, id, source) {
         // An addon can pass anything. A provider with no id would be unreachable;
         // one with no verify() would throw inside authenticate() on a live request,
         // which is a worse place to find out than boot.
-        if (!provider || typeof provider.id !== 'string' || provider.id.trim() === '') {
+        if (!provider || typeof id !== 'string' || id.trim() === '') {
             logger.error(`[AuthManager] Rejected provider from ${source}: missing id`);
             return false;
         }
         if (typeof provider.verify !== 'function') {
-            logger.error(`[AuthManager] Rejected provider '${provider.id}' from ${source}: no verify()`);
+            logger.error(`[AuthManager] Rejected provider '${id}' from ${source}: no verify()`);
             return false;
         }
-        if (this.providers.has(provider.id)) {
-            logger.warn(`[AuthManager] Provider '${provider.id}' is already registered — ` +
+        if (this.providers.has(id)) {
+            logger.warn(`[AuthManager] Provider '${id}' is already registered — ` +
                 `keeping the existing one, ignoring the registration from ${source}`);
             return false;
         }
-        this.providers.set(provider.id, provider);
+        this.providers.set(id, provider);
         this.factorCache = null;
         // info, not debug: which auth providers are live is a security-relevant
         // fact about a running instance, and the boot log is where an operator
         // checks it. Callers add a second line only when they carry config detail
         // worth seeing (transport, issuer, team) — never a bare repeat of the id.
-        logger.info(`[AuthManager] Registered provider: ${provider.id} (${source})`);
+        logger.info(`[AuthManager] Registered provider: ${id} (${source})`);
         return true;
     }
     /**