@nacre.work/api 0.17.5 → 0.19.0

package/dist/server.js

@@ -5,9 +5,10 @@ import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
 import { URL } from 'node:url';
 import { logger, MetadataError, MultipartError, multipartBoundary, parseMultipart, queryAudit, parseFilters, parseMetadata, PROTECTED_RESOURCE_PATH, JWKS_PATH, AUTHORIZATION_SERVER_PATH, AUTHORIZE_PATH, CODE_TTL_MS, allowedRequestHeaders, corsHeaders, isPreflight, preflightHeaders, REGISTER_PATH, TOKEN_PATH, authorizationServerMetadata, consentRedirect, generateClientId, generateCode, redirectAllowed, verifierMatches, ADMIN_PREFIX, adminRoutes, withAuditSinks, TooBusy, } from '@nacre.work/core';
 import { administers, administersTenants, authenticate, rejectTenantOverride, } from './auth.js';
-import { badRequest, internal, notAdministeredHere, notFound, Problem } from './errors.js';
+import { badRequest, internal, notAdministeredHere, notFound, Problem, tooBusy } from './errors.js';
 import { isConflict, isReplay } from './idempotency.js';
 import { limitHeaders } from './limits.js';
+import { MIN_PASSWORD_LENGTH } from './recovery.js';
 import { looksLikeEmail } from './principals.js';
 import { clientSource } from './source.js';
 import { auditFormat, auditJson, readAuditQuery, toCsv, toNdjson, } from './audit-export.js';
@@ -487,8 +488,91 @@ const neverCached = (instance) => NEVER_CACHED.some((path) => instance === path
  * key, and an operator reading `KEYS nacre:rl:*` should not be reading a list
  * of who has an account here.
  */
+/**
+ * Tell a person their second factor changed, where this deployment can.
+ *
+ * Best effort in every direction: no sender configured means no message, a
+ * relay that refuses is a log line, and neither stops the change that already
+ * happened. The address is read here rather than carried through the handler,
+ * because `AuthContext` holds a principal id and not an address.
+ *
+ * The two events are worth a message for the same reason a password change is:
+ * a factor appearing on an account, or disappearing from one, is what somebody
+ * taking it over does first.
+ */
+async function notifySecurityChange(options, orgId, userId, what, requestId) {
+    const mailer = options.mailer;
+    if (mailer === undefined)
+        return;
+    try {
+        const address = await options.secondFactors?.emailOf(orgId, userId);
+        if (address === undefined || address === null)
+            return;
+        await mailer.send({
+            to: address,
+            subject: what === 'enrolled' ? 'A second factor was added to your Nacre account' : 'A second factor was removed from your Nacre account',
+            text: what === 'enrolled'
+                ? [
+                    'An authenticator was just added to this account.',
+                    '',
+                    'If it was not you, somebody is signing in as you: change your password',
+                    'and tell your administrator.',
+                ].join('\n')
+                : [
+                    'An authenticator was just removed from this account.',
+                    '',
+                    'Removing one is the first thing somebody with a stolen session does. If',
+                    'it was not you, change your password and tell your administrator.',
+                ].join('\n'),
+        });
+    }
+    catch (error) {
+        logger.warn('could not send a security notice', {
+            request_id: requestId,
+            error: String(error).slice(0, 200),
+        });
+    }
+}
+/**
+ * The one answer to a full password gate, at whichever boundary caught it.
+ *
+ * There are two, and the split is authentication: sign-in and password recovery
+ * are reached without a credential and run before the request path that has
+ * one, so a single `catch` cannot cover both. Both call this, so there is one
+ * status, one wording and one header however a hashing route was reached.
+ *
+ * It used to be caught beside `login()` alone, which made the claim in
+ * `core/passwords.ts` — "the caller answers 503" — true of sign-in and false of
+ * the three other routes that hash: creating a user, an administrator resetting
+ * somebody's password, and redeeming a recovery link each turned a loaded
+ * process into a `500`, which a client reports as a broken server and an
+ * operator investigates as a bug. A rule stated in a comment and held in one of
+ * four places is the shape this repository keeps closing.
+ *
+ * Logged as load rather than as a failure, and deliberately not written to the
+ * journal: an audit row saying a request failed is read as a defect, and
+ * shedding load is the design working.
+ *
+ * @returns whether it answered, so a caller reads as `if (handled) return`.
+ */
+function handledTooBusy(res, error, instance, requestId) {
+    if (!(error instanceof TooBusy))
+        return false;
+    logger.warn('password gate full', { request_id: requestId, instance });
+    const problem = tooBusy(instance, requestId);
+    send(res, problem.status, problem.toJSON(), requestId, { 'retry-after': '2' });
+    return true;
+}
 async function handleAuth(req, res, instance, requestId, options) {
-    if (options.login === undefined || req.method !== 'POST') {
+    // Every route here produces a credential and therefore takes a body, with
+    // exactly one exception: `/v1/auth/methods` is a **read**, and the contract
+    // has said `get` since it was written. A blanket `!== 'POST'` refused it, so
+    // the endpoint whose whole job is telling a sign-in screen what exists
+    // answered 404 — and the console, reading `password_reset` off a problem
+    // document, hid the recovery link on every deployment including the ones
+    // with a relay configured. The feature did the opposite of its purpose.
+    const reads = instance === '/v1/auth/methods';
+    if (options.login === undefined || req.method !== (reads ? 'GET' : 'POST')) {
         const problem = notFound(instance, requestId);
         send(res, problem.status, problem.toJSON(), requestId);
         return;
@@ -557,41 +641,12 @@ async function handleAuth(req, res, instance, requestId, options) {
                 return;
             }
         }
-        let tokens;
-        try {
-            tokens = await options.login.login({
-                email,
-                password,
-                ...(typeof organization === 'string' ? { organization } : {}),
-            });
-        }
-        catch (error) {
-            // The process is already verifying as many passwords as it will. scrypt
-            // runs on libuv's thread pool, which is shared with DNS and file I/O, so
-            // an unbounded login endpoint stops the *rest* of the API on a name
-            // lookup — see the gate in core/passwords.ts.
-            //
-            // 503 and not 401: nothing was decided about these credentials, and
-            // answering "not valid" to a request that was never checked is a lie the
-            // client will act on. 503 with Retry-After is the honest one.
-            //
-            // Not an oracle either. It depends on how loaded the process is and not
-            // at all on whether the account exists.
-            if (error instanceof TooBusy) {
-                const problem = new Problem({
-                    type: 'https://nacre.work/errors/unavailable',
-                    title: 'Service unavailable',
-                    status: 503,
-                    detail: 'Too many sign-in attempts are being processed. Try again shortly.',
-                    instance,
-                    requestId,
-                });
-                send(res, problem.status, problem.toJSON(), requestId, { 'retry-after': '2' });
-                return;
-            }
-            throw error;
-        }
-        if (tokens === undefined) {
+        const outcome = await options.login.login({
+            email,
+            password,
+            ...(typeof organization === 'string' ? { organization } : {}),
+        });
+        if (outcome === undefined) {
             // Logged rather than audited, and the difference is not laziness. The
             // audit log is per-organization; an address that matches no user belongs
             // to no tenant, and giving that row an owner would put one
@@ -606,6 +661,27 @@ async function handleAuth(req, res, instance, requestId, options) {
             refuse();
             return;
         }
+        /*
+         * A correct password and a second factor to produce.
+         *
+         * Not an audit event yet, and not a `login` one whatever happens next: this
+         * is half of an authentication, and writing "login allow" here would put a
+         * successful sign-in in the journal for somebody who never produced their
+         * code. The event is written where the session is issued.
+         *
+         * 200 rather than 401, because nothing was refused — the client is being
+         * asked for the rest of what it needs, which is what `second_factor_required`
+         * says.
+         */
+        if (outcome.kind === 'second-factor') {
+            send(res, 200, {
+                second_factor_required: true,
+                challenge: outcome.challenge,
+                expires_in: outcome.expiresIn,
+            }, requestId);
+            return;
+        }
+        const tokens = outcome.tokens;
         // The successful one does have an organization to belong to, and it is the
         // event that answers "who has been in here". Awaited: a lost audit event is
         // worse than a slow response.
@@ -621,6 +697,189 @@ async function handleAuth(req, res, instance, requestId, options) {
         send(res, 200, tokenJson(tokens), requestId);
         return;
     }
+    /*
+     * What this installation offers before anybody has signed in.
+     *
+     * One boolean, and it exists so the console can leave the recovery link
+     * **off the screen** where no sender is configured rather than showing a
+     * control that answers 404. A screen offering what the server refuses is a
+     * defect this console has already shipped once.
+     *
+     * It tells a stranger that this deployment can send email, which is what they
+     * would learn by pressing the link anyway. It says nothing about any address.
+     */
+    if (instance === '/v1/auth/methods') {
+        send(res, 200, {
+            password_reset: options.recovery !== undefined,
+            // Which second factors this installation can *challenge* with. A
+            // sign-in screen that offered "use your security key" where the
+            // deployment has no relying party would be the same defect the
+            // recovery link was: a control the server refuses.
+            second_factor_kinds: options.secondFactors?.kinds ?? [],
+        }, requestId);
+        return;
+    }
+    /*
+     * Ask for a recovery link.
+     *
+     * **`204` whatever happened**, including for an address with no account, an
+     * address in two organizations, a disabled account and a send that failed.
+     * Anything else makes this the account-enumeration oracle the sign-in path is
+     * careful not to be — and this one needs no credential at all.
+     */
+    if (instance === '/v1/auth/password-reset' && options.recovery !== undefined) {
+        const email = (body ?? {});
+        if (typeof email.email !== 'string') {
+            const problem = badRequest(instance, requestId, "'email' is required.");
+            send(res, problem.status, problem.toJSON(), requestId);
+            return;
+        }
+        // The same two buckets sign-in has, and for the same reasons: the address
+        // one defends a mailbox from being flooded on somebody's behalf, and the
+        // source one bounds the sweep across a directory that never repeats an
+        // address.
+        if (options.limits !== undefined && options.limitPolicies?.login !== undefined) {
+            const subject = createHash('sha256').update(email.email.trim().toLowerCase()).digest('hex').slice(0, 32);
+            const source = clientSource(req, { trustProxy: options.trustProxy ?? 0 });
+            const decisions = [await options.limits.check(subject, 'login')];
+            if (source !== undefined && options.limitPolicies.login_source !== undefined) {
+                decisions.push(await options.limits.check(`src:${source}`, 'login_source'));
+            }
+            if (decisions.some((d) => !d.allowed)) {
+                // Still 204. A 429 here would say "this address is being asked about",
+                // which is the thing the endpoint refuses to say.
+                send(res, 204, null, requestId);
+                return;
+            }
+        }
+        // Awaited, but its failure is swallowed: the answer is the same either way,
+        // and an unhandled rejection would take the process down over a relay being
+        // briefly unreachable.
+        await options.recovery.request(email.email).catch((error) => {
+            logger.warn('could not start a password recovery', {
+                request_id: requestId,
+                error: String(error).slice(0, 200),
+            });
+        });
+        send(res, 204, null, requestId);
+        return;
+    }
+    if (instance === '/v1/auth/password-reset/confirm' && options.recovery !== undefined) {
+        const { token, password } = (body ?? {});
+        if (typeof token !== 'string' || typeof password !== 'string') {
+            const problem = badRequest(instance, requestId, "'token' and 'password' are required.");
+            send(res, problem.status, problem.toJSON(), requestId);
+            return;
+        }
+        const outcome = await options.recovery.redeem(token, password);
+        if (outcome === 'too-short') {
+            // The one thing this endpoint does say, because it is about what the
+            // caller sent rather than about what exists. A refusal with no reason
+            // here is a person retyping a password that will never be accepted.
+            const problem = badRequest(instance, requestId, `A password is at least ${String(MIN_PASSWORD_LENGTH)} characters. Length is the whole rule — there is no requirement about digits or symbols.`);
+            send(res, problem.status, problem.toJSON(), requestId);
+            return;
+        }
+        if (outcome === 'refused') {
+            // One answer for a link that never existed, one already used, one that
+            // expired, and an account disabled since it was sent.
+            refuse();
+            return;
+        }
+        send(res, 204, null, requestId);
+        return;
+    }
+    /*
+     * The second half of a sign-in.
+     *
+     * Rate limited on the same buckets as `/v1/auth/login`, because otherwise the
+     * limit is a limit on passwords and not on sessions: an attacker holding a
+     * password spends one login and then guesses six digits here without ever
+     * meeting a bucket again. The per-factor lock in Postgres is the bound that
+     * survives a Redis restart; this one is the bound that costs an attacker
+     * their source.
+     */
+    /*
+     * The options a browser needs before it can produce an assertion.
+     *
+     * It takes the sign-in challenge and nothing else, so this is not a route
+     * that will tell a stranger which authenticators an address holds: the
+     * challenge is a JWT this server signed one password ago. Not rate limited
+     * separately, because reaching it costs a correct password.
+     */
+    if (instance === '/v1/auth/second-factor/webauthn') {
+        const challenge = body?.challenge;
+        if (typeof challenge !== 'string') {
+            const problem = badRequest(instance, requestId, "'challenge' is required.");
+            send(res, problem.status, problem.toJSON(), requestId);
+            return;
+        }
+        const begun = await options.login.beginSecondFactorWebAuthn(challenge);
+        if (begun === undefined) {
+            // One refusal for a challenge that is not ours, one that has expired, and
+            // a person holding no key — the same rule the rest of this path follows.
+            refuse();
+            return;
+        }
+        send(res, 200, assertionOptionsJson(begun), requestId);
+        return;
+    }
+    if (instance === '/v1/auth/second-factor') {
+        const { challenge, code, assertion } = (body ?? {});
+        if (typeof challenge !== 'string') {
+            const problem = badRequest(instance, requestId, "'challenge' is required.");
+            send(res, problem.status, problem.toJSON(), requestId);
+            return;
+        }
+        const proof = readProof(code, assertion);
+        if (proof === undefined) {
+            const problem = badRequest(instance, requestId, "Either 'code' or 'assertion' is required.");
+            send(res, problem.status, problem.toJSON(), requestId);
+            return;
+        }
+        if (options.limits !== undefined && options.limitPolicies?.login !== undefined) {
+            const source = clientSource(req, { trustProxy: options.trustProxy ?? 0 });
+            if (source !== undefined && options.limitPolicies.login_source !== undefined) {
+                const decision = await options.limits.check(`src:${source}`, 'login_source');
+                if (!decision.allowed) {
+                    const problem = new Problem({
+                        type: 'https://nacre.work/errors/rate-limited',
+                        title: 'Too many requests',
+                        status: 429,
+                        detail: `Too many sign-in attempts. Try again in ${decision.reset} seconds.`,
+                        instance,
+                        requestId,
+                    });
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+            }
+        }
+        const tokens = await options.login.completeSecondFactor(challenge, proof);
+        if (tokens === undefined) {
+            // One refusal for an expired challenge, a forged one, a wrong code and a
+            // disabled account alike. Which of the four it was is nothing a client
+            // needs and something an attacker would use.
+            logger.warn('second factor refused', { request_id: requestId });
+            refuse();
+            return;
+        }
+        await options.audit.write({
+            orgId: tokens.orgId,
+            actor: `user:${tokens.userId}`,
+            action: 'login',
+            result: 'allow',
+            target: { user_id: tokens.userId },
+            // The journal says which door, because "signed in with a second factor"
+            // and "signed in with a password" are different facts to an investigator
+            // — and so are the two kinds of second factor, since only one of them is
+            // proof against a page that looked like this one.
+            detail: { second_factor: true, second_factor_kind: proof.kind },
+            requestId,
+        });
+        send(res, 200, tokenJson(tokens), requestId);
+        return;
+    }
     const token = body?.refresh_token;
     if (typeof token !== 'string' || token === '') {
         const problem = badRequest(instance, requestId, "'refresh_token' is required.");
@@ -646,6 +905,71 @@ async function handleAuth(req, res, instance, requestId, options) {
     const problem = notFound(instance, requestId);
     send(res, problem.status, problem.toJSON(), requestId);
 }
+/**
+ * A WebAuthn assertion out of a request body, or nothing.
+ *
+ * One parser, because two routes take one: the second half of a sign-in and
+ * taking a factor off an account. Two would be two ideas of which fields are
+ * required and which encoding they arrive in, and the half that got it wrong
+ * would refuse every authenticator with a message about neither.
+ *
+ * base64url throughout, which is what a browser reports and what
+ * `webauthn_challenges.challenge` stores — so the comparison downstream is a
+ * string equality and never an encoding round trip.
+ */
+function readAssertion(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const it = value;
+    const fields = ['credential_id', 'authenticator_data', 'client_data_json', 'signature', 'challenge'];
+    if (fields.some((f) => typeof it[f] !== 'string' || it[f] === ''))
+        return undefined;
+    const bytes = (name) => new Uint8Array(Buffer.from(it[name], 'base64url'));
+    return {
+        credentialId: it.credential_id,
+        authenticatorData: bytes('authenticator_data'),
+        clientDataJSON: bytes('client_data_json'),
+        signature: bytes('signature'),
+        challenge: it.challenge,
+    };
+}
+/**
+ * Which of the two proofs a body carries.
+ *
+ * Both present is a refusal rather than a precedence. A caller sending each is
+ * a caller with two ideas of how it is signing in, and resolving that by
+ * preferring one leaves the other apparently offered and ignored — which is
+ * the argument `loadConfig` makes about a secret and a key ref together.
+ */
+function readProof(code, assertion) {
+    const hasCode = typeof code === 'string' && code !== '';
+    if (hasCode && assertion !== undefined)
+        return undefined;
+    if (hasCode)
+        return { kind: 'code', code: code };
+    const response = readAssertion(assertion);
+    return response === undefined ? undefined : { kind: 'webauthn', response };
+}
+/** The wire shape of what a browser needs for `navigator.credentials.get`. */
+function assertionOptionsJson(options) {
+    return {
+        challenge: options.challenge,
+        rp_id: options.rpId,
+        allow_credentials: options.allowCredentials,
+        timeout_ms: options.timeoutMs,
+    };
+}
+/** And for `navigator.credentials.create`. */
+function registrationOptionsJson(options) {
+    return {
+        challenge: options.challenge,
+        rp: { id: options.rp.id, name: options.rp.name },
+        user: { id: options.user.id, name: options.user.name, display_name: options.user.displayName },
+        algorithms: options.algorithms,
+        exclude_credentials: options.excludeCredentials,
+        timeout_ms: options.timeoutMs,
+    };
+}
 function tokenJson(tokens) {
     return {
         access_token: tokens.accessToken,
@@ -849,7 +1173,22 @@ async function handle(req, res, options) {
     // different way — see login.ts. The organization in the issued token comes
     // from the row that authenticated, never from the request.
     if (instance.startsWith('/v1/auth/')) {
-        await handleAuth(req, res, instance, requestId, options);
+        try {
+            await handleAuth(req, res, instance, requestId, options);
+        }
+        catch (error) {
+            // The second of this file's two error boundaries, and the split is
+            // authentication: everything below this line has a credential and is
+            // covered by the catch at the bottom of this function, while sign-in and
+            // password recovery are reached without one and cannot be.
+            //
+            // Both defer to `handledTooBusy` rather than answering, so there is one
+            // 503 and one wording however a hashing route was reached. Anything else
+            // is rethrown to the handler `createApi` installs.
+            if (handledTooBusy(res, error, instance, requestId))
+                return;
+            throw error;
+        }
         return;
     }
     // A path this server does not route is `404`, and it says so **before**
@@ -1762,6 +2101,371 @@ async function handle(req, res, options) {
             }, requestId);
             return;
         }
+        /*
+         * The caller's own password.
+         *
+         * Under `/v1/me` for the same reason the second factor is: this is a person
+         * acting on themselves, and there is no id in the path for anybody to put
+         * somebody else's in. `POST /v1/users/{id}/password` beside it is the other
+         * thing — an administrator issuing a generated password to a colleague who
+         * lost theirs — and the two are deliberately not one endpoint with a
+         * branch.
+         *
+         * A service account is refused: a key has no password, and `nacre_sk_` is
+         * rotated by minting another. A delegation is refused because changing how
+         * somebody signs in is not something a third party acting for them was
+         * approved to do — the same line the second factor draws.
+         */
+        if (instance === '/v1/me/password') {
+            if (req.method !== 'POST' || options.login === undefined) {
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            if (auth.principal.type !== 'user' || auth.delegation !== undefined) {
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            const { current_password: currentPassword, new_password: newPassword } = (body ?? {});
+            if (typeof currentPassword !== 'string' || typeof newPassword !== 'string') {
+                const problem = badRequest(instance, requestId, "'current_password' and 'new_password' are required.");
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            if (newPassword.length < MIN_PASSWORD_LENGTH) {
+                const problem = badRequest(instance, requestId, `A password is at least ${String(MIN_PASSWORD_LENGTH)} characters. Length is the whole rule — there is no requirement about digits or symbols.`);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            const outcome = await options.login.changePassword(auth.orgId, auth.principal.id, currentPassword, newPassword);
+            if (typeof outcome === 'string') {
+                await options.audit.write({
+                    orgId: auth.orgId,
+                    actor: `user:${auth.principal.id}`,
+                    action: 'password.change',
+                    result: 'deny',
+                    target: { user_id: auth.principal.id },
+                    detail: { reason: outcome },
+                    requestId,
+                });
+                /*
+                 * `403`, and the choice is about clients rather than about semantics.
+                 *
+                 * `401` is the obvious status for a credential that did not check out,
+                 * and it is the wrong one here: on an authenticated route `401` means
+                 * "your session is over", and every client in this repository renews on
+                 * it and replays. A wrong current password would therefore spend a
+                 * refresh token, replay, fail again, and reach the person as two
+                 * failures with a renewal between them — for something they can fix by
+                 * retyping.
+                 *
+                 * Not `404` either. The caller is looking straight at their own
+                 * account, so there is nothing invisible for invariant 4 to protect —
+                 * the same reasoning as the `platform_admin` refusal on `/v1/users`.
+                 *
+                 * One wording for a wrong password and for the guard cases beside it,
+                 * because the guard cases are unreachable by anyone holding a token
+                 * this row issued and telling them apart would say nothing true.
+                 */
+                const problem = new Problem({
+                    type: 'https://nacre.work/errors/forbidden',
+                    title: 'Forbidden',
+                    status: 403,
+                    detail: 'The current password is not correct.',
+                    instance,
+                    requestId,
+                });
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            await options.audit.write({
+                orgId: auth.orgId,
+                actor: `user:${auth.principal.id}`,
+                action: 'password.change',
+                result: 'allow',
+                target: { user_id: auth.principal.id },
+                detail: {},
+                requestId,
+            });
+            // A notice, not a confirmation. Somebody who has taken an account changes
+            // the password to keep it, so the person who did not do this is the one
+            // who needs to know. Dropped rather than raised: the password *is*
+            // changed, and refusing the request over a notice would be worse than a
+            // notice that did not arrive.
+            void options.mailer
+                ?.send({
+                to: outcome.email,
+                subject: 'Your Nacre password was changed',
+                text: [
+                    'The password for this account was just changed from a signed-in session.',
+                    '',
+                    'Every other session was signed out. Any second factor on the account is',
+                    'untouched and is still required.',
+                    '',
+                    'If this was not you, somebody knew your password — reset it from the',
+                    'sign-in screen and tell your administrator.',
+                ].join('\n'),
+            })
+                .catch(() => undefined);
+            // The pair that replaces the sessions this just ended. Answering 204 and
+            // leaving the caller holding a revoked refresh token would sign a person
+            // out of the browser they changed their password in, which reads as a
+            // failure.
+            send(res, 200, {
+                access_token: outcome.tokens.accessToken,
+                token_type: 'Bearer',
+                expires_in: outcome.tokens.expiresIn,
+                refresh_token: outcome.tokens.refreshToken,
+            }, requestId);
+            return;
+        }
+        /*
+         * The caller's own second factor.
+         *
+         * Under `/v1/me` and never `/v1/users/{id}`, which is the security property
+         * rather than a URL preference: an administrator resets somebody's password
+         * and must not be able to enrol, read or remove their second factor —
+         * doing so would make the factor a thing the account's administrator holds,
+         * and the whole point is that it is a thing the *person* holds.
+         *
+         * A service account and a delegation are refused. A key is not a person and
+         * has nobody to carry an authenticator; a delegation is a third party
+         * acting for somebody, and letting it change how that somebody signs in
+         * would be an escalation out of what was approved.
+         */
+        if (instance === '/v1/me/second-factor' || instance.startsWith('/v1/me/second-factor/')) {
+            if (options.secondFactors === undefined || !options.secondFactors.available) {
+                // No key configured, so the feature is absent rather than broken. 404
+                // and not 501: from outside, a route this installation does not serve
+                // and one it has not been given a key for are the same thing.
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            if (auth.principal.type !== 'user' || auth.delegation !== undefined) {
+                const problem = notFound(instance, requestId);
+                send(res, problem.status, problem.toJSON(), requestId);
+                return;
+            }
+            const factors = options.secondFactors;
+            const userId = auth.principal.id;
+            const rest = instance.slice('/v1/me/second-factor'.length);
+            if (rest === '' && req.method === 'GET') {
+                const [items, left] = await Promise.all([
+                    factors.list(auth.orgId, userId),
+                    factors.recoveryCodesLeft(auth.orgId, userId),
+                ]);
+                send(res, 200, {
+                    items: items.map((f) => ({
+                        id: f.id,
+                        kind: f.kind,
+                        label: f.label,
+                        created_at: f.createdAt.toISOString(),
+                        last_used_at: f.lastUsedAt?.toISOString() ?? null,
+                    })),
+                    recovery_codes_left: left,
+                    // What this installation can enrol, so the screen draws the
+                    // controls that work rather than one that answers 404. The same
+                    // "ask, do not assume" rule `GET /v1/auth/methods` exists for: a
+                    // deployment with no `NACRE_2FA_KEY` offers `webauthn` alone.
+                    kinds: factors.kinds,
+                }, requestId);
+                return;
+            }
+            if (rest === '' && req.method === 'POST') {
+                const label = body?.label;
+                const named = typeof label === 'string' && label.trim() !== '' ? label.trim().slice(0, 60) : 'Authenticator';
+                const begun = await factors.begin(auth.orgId, userId, named);
+                if (begun === undefined) {
+                    const problem = notFound(instance, requestId);
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                // The secret in the response and nowhere else: this is the one moment
+                // it exists outside the sealed column, exactly as a generated password
+                // is.
+                send(res, 201, { id: begun.id, secret: begun.secret, otpauth_url: begun.otpauthUrl, label: named }, requestId);
+                return;
+            }
+            /*
+             * Enrolling a key, which is two calls because a ceremony is.
+             *
+             * The first hands out a challenge and what the authenticator needs to
+             * see; the second brings back what it signed. They are separate because
+             * the challenge has to exist in the database before the browser is asked
+             * for anything — a server that made one up when the answer arrived would
+             * be verifying a signature over a number the client chose.
+             */
+            if (rest === '/webauthn' && req.method === 'POST') {
+                const begun = await factors.beginWebAuthnRegistration(auth.orgId, userId);
+                if (begun === undefined) {
+                    // This installation offers TOTP only. 404 rather than a message
+                    // about configuration, for the reason the whole block is behind one.
+                    const problem = notFound(instance, requestId);
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                send(res, 201, registrationOptionsJson(begun), requestId);
+                return;
+            }
+            if (rest === '/webauthn/finish' && req.method === 'POST') {
+                const it = (body ?? {});
+                const label = typeof it.label === 'string' && it.label.trim() !== '' ? it.label.trim().slice(0, 60) : 'Security key';
+                const fields = ['challenge', 'attestation_object', 'client_data_json'];
+                if (fields.some((f) => typeof it[f] !== 'string' || it[f] === '')) {
+                    const problem = badRequest(instance, requestId, "'challenge', 'attestation_object' and 'client_data_json' are required.");
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                const codes = await factors.finishWebAuthnRegistration(auth.orgId, userId, label, {
+                    attestationObject: new Uint8Array(Buffer.from(it.attestation_object, 'base64url')),
+                    clientDataJSON: new Uint8Array(Buffer.from(it.client_data_json, 'base64url')),
+                    challenge: it.challenge,
+                });
+                if (codes === undefined) {
+                    // One refusal for a spent challenge, a wrong origin, an unsupported
+                    // algorithm and a signature that does not verify. Telling them apart
+                    // would describe this server's checks to whoever is probing them.
+                    const problem = notFound(instance, requestId);
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                await options.audit.write({
+                    orgId: auth.orgId,
+                    actor: `user:${userId}`,
+                    action: 'second_factor.enrol',
+                    result: 'allow',
+                    target: { user_id: userId },
+                    detail: { kind: 'webauthn' },
+                    requestId,
+                });
+                void notifySecurityChange(options, auth.orgId, userId, 'enrolled', requestId);
+                send(res, 200, { recovery_codes: codes }, requestId);
+                return;
+            }
+            /*
+             * A challenge for proving possession to *this* surface, which exists
+             * because taking a factor off takes a current proof and an assertion
+             * cannot be produced without one.
+             *
+             * `purpose = 'authenticate'` is the same pool a sign-in spends from, and
+             * that is deliberate rather than an oversight: this caller has a session,
+             * so a challenge they can spend on a sign-in buys them nothing they do
+             * not already hold. What must not share a pool is *enrolment*, since
+             * that one is asked for by somebody already signed in and would let a
+             * session mint the input to a ceremony it is not in.
+             */
+            if (rest === '/webauthn/assert' && req.method === 'POST') {
+                const begun = await factors.beginWebAuthnAssertion(auth.orgId, userId);
+                if (begun === undefined) {
+                    const problem = notFound(instance, requestId);
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                send(res, 200, assertionOptionsJson(begun), requestId);
+                return;
+            }
+            if (rest.endsWith('/confirm') && req.method === 'POST') {
+                const id = rest.slice(1, -'/confirm'.length);
+                const code = body?.code;
+                if (!UUID_SHAPE.test(id) || typeof code !== 'string') {
+                    const problem = badRequest(instance, requestId, "'code' is required.");
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                const codes = await factors.confirm(auth.orgId, userId, id, code);
+                if (codes === undefined) {
+                    // One refusal for a wrong code and for an enrolment that is not
+                    // there. Telling them apart would say whether a given id exists.
+                    const problem = notFound(instance, requestId);
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                await options.audit.write({
+                    orgId: auth.orgId,
+                    actor: `user:${userId}`,
+                    action: 'second_factor.enrol',
+                    result: 'allow',
+                    target: { user_id: userId },
+                    detail: {},
+                    requestId,
+                });
+                // A notice, where the deployment can send one. The person who did not
+                // do this is the one who needs to know, and a second factor appearing
+                // on an account is exactly what somebody taking it over would do.
+                // Dropped rather than raised: the enrolment happened.
+                void notifySecurityChange(options, auth.orgId, userId, 'enrolled', requestId);
+                // Printed once. A second call returns an empty list rather than new
+                // codes, because reissuing them here would invalidate the set somebody
+                // has already written down.
+                send(res, 200, { recovery_codes: codes }, requestId);
+                return;
+            }
+            /*
+             * Taking a factor off, and the condition is what it is because the one
+             * it replaced could never be true. `rest` is `/{id}` for this route, so
+             * `!rest.includes('/')` asked whether a string beginning with a slash
+             * contains one — false for every id, always. `DELETE
+             * /v1/me/second-factor/{id}` answered 404 from the day it was written
+             * and shipped that way in 0.18.0: a second factor could be enrolled and
+             * never removed, on the one surface an administrator deliberately
+             * cannot reach on somebody's behalf.
+             *
+             * No suite could see it. `second-factor-live.test.ts` calls
+             * `factors.remove` directly and passes, because the store was never the
+             * broken half — nothing had asked the *server* for this path.
+             */
+            if (rest.startsWith('/') && !rest.slice(1).includes('/') && req.method === 'DELETE') {
+                const id = rest.slice(1);
+                const { code, assertion } = (body ?? {});
+                const proof = readProof(code, assertion);
+                if (!UUID_SHAPE.test(id) || proof === undefined) {
+                    const problem = badRequest(instance, requestId, "Either 'code' or 'assertion' is required to remove a second factor.");
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                /*
+                 * A current proof to take one off, and that is the whole reason this
+                 * endpoint takes a body at all. Removing the second factor is the first
+                 * thing somebody with a stolen session does, and a session is exactly
+                 * what the factor exists to be more than.
+                 *
+                 * Either kind, because an account can hold either kind — an
+                 * installation with no `NACRE_2FA_KEY` has no code to ask for, and
+                 * demanding one there would make every WebAuthn factor permanent.
+                 */
+                const proved = proof.kind === 'code'
+                    ? await factors.verify(auth.orgId, userId, proof.code)
+                    : await factors.verifyWebAuthnAssertion(auth.orgId, userId, proof.response);
+                if (!proved) {
+                    const problem = notFound(instance, requestId);
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                const removed = await factors.remove(auth.orgId, userId, id);
+                if (!removed) {
+                    const problem = notFound(instance, requestId);
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                await options.audit.write({
+                    orgId: auth.orgId,
+                    actor: `user:${userId}`,
+                    action: 'second_factor.remove',
+                    result: 'allow',
+                    target: { user_id: userId },
+                    detail: {},
+                    requestId,
+                });
+                void notifySecurityChange(options, auth.orgId, userId, 'removed', requestId);
+                send(res, 204, null, requestId);
+                return;
+            }
+            const problem = notFound(instance, requestId);
+            send(res, problem.status, problem.toJSON(), requestId);
+            return;
+        }
         if (instance === '/v1/embedding-providers' && options.embeddingProviders !== undefined) {
             if (req.method === 'GET') {
                 // Not paged. A deployment has a handful of these — one per model it
@@ -3280,6 +3984,11 @@ async function handle(req, res, options) {
         send(res, problem.status, problem.toJSON(), requestId);
     }
     catch (error) {
+        // Load, not a failure — and deliberately before the log and the journal
+        // below, because an audit row saying a request failed is read as a defect
+        // and shedding load is the design working.
+        if (handledTooBusy(res, error, instance, requestId))
+            return;
         // The 500 body says "whatever went wrong is in the journal under this
         // request_id", and until this line nothing wrote it there: the error was
         // discarded by a bare `catch`, and the audit row carried an empty detail.