@nacre.work/api 0.17.4 → 0.18.0

package/dist/server.js

@@ -3,11 +3,12 @@ import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
 // Imported rather than taken from the global scope: `lib` is ES2023 with no
 // DOM, so the global URL is not typed here.
 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, corsHeaders, isPreflight, preflightHeaders, REGISTER_PATH, TOKEN_PATH, authorizationServerMetadata, consentRedirect, generateClientId, generateCode, redirectAllowed, verifierMatches, ADMIN_PREFIX, adminRoutes, withAuditSinks, TooBusy, } from '@nacre.work/core';
+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,6 +488,81 @@ 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') {
         const problem = notFound(instance, requestId);
@@ -557,41 +633,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 +653,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 +689,149 @@ 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 }, 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.
+     */
+    if (instance === '/v1/auth/second-factor') {
+        const { challenge, code } = (body ?? {});
+        if (typeof challenge !== 'string' || typeof code !== 'string') {
+            const problem = badRequest(instance, requestId, "'challenge' and 'code' are 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, code);
+        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.
+            detail: { second_factor: true },
+            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.");
@@ -705,10 +916,15 @@ async function handle(req, res, options) {
         res.writeHead(204, preflightHeaders({
             origin,
             methods: 'GET, POST, PATCH, PUT, DELETE, OPTIONS',
-            // What this API reads. `idempotency-key` is the one the MCP transport
-            // has never heard of, and a browser that may not send it cannot make
-            // the retry-safe call the contract asks for.
-            headers: 'authorization, content-type, accept, idempotency-key, if-none-match',
+            // What this API reads *on top of* what every MCP client sends. That
+            // shared set is not optional here: this API serves the two `/.well-known`
+            // documents a browser MCP client reads, and the SDK puts
+            // `mcp-protocol-version` on those requests too.
+            //
+            // `idempotency-key` is the one the MCP transport has never heard of, and
+            // a browser that may not send it cannot make the retry-safe call the
+            // contract asks for.
+            headers: allowedRequestHeaders(['idempotency-key', 'if-none-match']),
         }));
         res.end();
         return;
@@ -844,7 +1060,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**
@@ -1757,6 +1988,266 @@ 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,
+                }, 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;
+            }
+            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;
+            }
+            if (rest !== '' && !rest.includes('/') && req.method === 'DELETE') {
+                const id = rest.slice(1);
+                const code = body?.code;
+                if (!UUID_SHAPE.test(id) || typeof code !== 'string') {
+                    const problem = badRequest(instance, requestId, "'code' is required to remove a second factor.");
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                /*
+                 * A current code 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.
+                 */
+                if (!(await factors.verify(auth.orgId, userId, code))) {
+                    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
@@ -3275,6 +3766,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.