@nacre.work/api 0.18.0 → 0.20.0

package/dist/server.js

@@ -118,6 +118,11 @@ function userJson(u) {
         // account, which is a fact an administrator needs and which says nothing
         // about the credential.
         has_password: u.hasPassword,
+        // Whether several people hold this password. An administrator who ticked
+        // that box when creating the account has no other way to see it afterwards,
+        // and it decides whether the person on the other end can hold a second
+        // factor at all.
+        shared: u.shared,
     };
 }
 function groupJson(g) {
@@ -563,8 +568,331 @@ function handledTooBusy(res, error, instance, requestId) {
     send(res, problem.status, problem.toJSON(), requestId, { 'retry-after': '2' });
     return true;
 }
+/**
+ * Whether this principal holds its own credentials, and may therefore change
+ * them.
+ *
+ * One predicate for the whole `/v1/me` credential surface — the password and
+ * both kinds of second factor — because the question each of those routes asks
+ * is the same one, and a route that asked it in its own words is a route the
+ * next one is written without.
+ *
+ * Three classes answer no, and the third is the one this exists for.
+ *
+ * A **service account** is a key and has nobody to carry an authenticator. A
+ * **delegation** is a third party acting for somebody, and changing how that
+ * somebody signs in is not what was approved. And a **shared account** is a
+ * credential more than one person holds — a published demo login is the case —
+ * so there is no "the person" to hold a factor, and the first holder to enrol
+ * one locks out every other one with no administrative route back, because an
+ * administrator deliberately cannot remove a second factor.
+ *
+ * `404` rather than `403` on a refusal, which is what the two existing classes
+ * already answered: this is a surface that is not there for this principal
+ * rather than one it is being kept out of.
+ *
+ * The `shared` read is per request rather than a token claim. A claim is fixed
+ * when the session is minted, so marking an account shared would leave its
+ * holder fifteen minutes in which the surface is still open — which is the
+ * argument a delegation's `disabled` check already makes, and this is the same
+ * kind of fact.
+ */
+async function holdsOwnCredentials(auth, options) {
+    if (auth.principal.type !== 'user' || auth.delegation !== undefined)
+        return false;
+    // Unset in a harness that does not mount the principals surface, and there
+    // an account cannot have been marked shared in the first place.
+    if (options.users === undefined)
+        return true;
+    return !(await options.users.isShared(auth.orgId, auth.principal.id));
+}
+/**
+ * The `/v1/me/second-factor` routes, reachable through either door.
+ *
+ * One implementation with the door as a parameter, rather than a second copy
+ * behind the enrolment challenge. Four of these seven routes would have been
+ * duplicated, and a fix applied to one copy and not its sibling is the defect
+ * this repository names most often.
+ */
+async function handleSecondFactorRoutes(req, res, instance, requestId, body, options, factors, door) {
+    const { orgId, userId } = door;
+    const rest = instance.slice('/v1/me/second-factor'.length);
+    // Default-deny, and the door says what it offers rather than the routes
+    // saying who may reach them. A route added later is unreachable through the
+    // narrow door until somebody widens it deliberately, which is the direction
+    // to be wrong in.
+    if (!door.offers(rest, req.method ?? 'GET')) {
+        const problem = notFound(instance, requestId);
+        send(res, problem.status, problem.toJSON(), requestId);
+        return;
+    }
+    if (rest === '' && req.method === 'GET') {
+        const [items, left] = await Promise.all([
+            factors.list(orgId, userId),
+            factors.recoveryCodesLeft(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(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(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(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: orgId,
+            actor: `user:${userId}`,
+            action: 'second_factor.enrol',
+            result: 'allow',
+            target: { user_id: userId },
+            detail: { kind: 'webauthn' },
+            requestId,
+        });
+        void notifySecurityChange(options, orgId, userId, 'enrolled', requestId);
+        send(res, 200, { recovery_codes: codes, ...(await door.onEnrolled()) }, 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(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(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: 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, 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, ...(await door.onEnrolled()) }, 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(orgId, userId, proof.code)
+            : await factors.verifyWebAuthnAssertion(orgId, userId, proof.response);
+        if (!proved) {
+            const problem = notFound(instance, requestId);
+            send(res, problem.status, problem.toJSON(), requestId);
+            return;
+        }
+        const removed = await factors.remove(orgId, userId, id);
+        if (!removed) {
+            const problem = notFound(instance, requestId);
+            send(res, problem.status, problem.toJSON(), requestId);
+            return;
+        }
+        await options.audit.write({
+            orgId: orgId,
+            actor: `user:${userId}`,
+            action: 'second_factor.remove',
+            result: 'allow',
+            target: { user_id: userId },
+            detail: {},
+            requestId,
+        });
+        void notifySecurityChange(options, orgId, userId, 'removed', requestId);
+        send(res, 204, null, requestId);
+        return;
+    }
+    const problem = notFound(instance, requestId);
+    send(res, problem.status, problem.toJSON(), requestId);
+    return;
+}
+/**
+ * The two session outcomes that are not a session, rendered in one place.
+ *
+ * Four handlers can reach them — sign-in, the second half of a sign-in, a
+ * refresh, and a password change — because the gates are consulted where a
+ * session is minted and all four mint one. Four copies of this rendering is
+ * four chances to answer one of them with a `200` and no tokens, which a client
+ * reads as a successful sign-in that produced nothing.
+ *
+ * `enrol` is a **200**, on the same argument the second-factor challenge is:
+ * nothing was refused. The client is being asked for something more, and told
+ * where to send it. `second_factor_enrolment_required` rather than reusing
+ * `second_factor_required`, because the two ask for different things — one for
+ * a code from an authenticator that exists, one for an authenticator.
+ *
+ * `refuse` is a **403**. Not `401`: the credential was correct, and every
+ * client here renews on a `401` and replays, so a policy refusal spelled that
+ * way would spend a refresh token and arrive as two failures. Not `404` either
+ * — the caller is looking straight at their own account. The reason is the
+ * gate's own words, because a refusal a person cannot act on and cannot read is
+ * indistinguishable from the product being broken.
+ */
+function sendSessionOutcome(res, outcome, instance, requestId) {
+    if (outcome.kind === 'enrol-second-factor') {
+        send(res, 200, {
+            second_factor_enrolment_required: true,
+            challenge: outcome.challenge,
+            expires_in: outcome.expiresIn,
+            reason: outcome.reason,
+        }, requestId);
+        return;
+    }
+    const problem = new Problem({
+        type: 'https://nacre.work/errors/sign-in-refused',
+        title: 'Sign-in refused',
+        status: 403,
+        detail: outcome.reason,
+        instance,
+        requestId,
+    });
+    send(res, problem.status, problem.toJSON(), requestId);
+}
 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;
@@ -673,6 +1001,13 @@ async function handleAuth(req, res, instance, requestId, options) {
             }, requestId);
             return;
         }
+        if (outcome.kind !== 'tokens') {
+            // A gate answered. Not an audit event either way: `enrol` is half an
+            // authentication, like the challenge above, and `refused` never became a
+            // session — the `login allow` event is written where one is issued.
+            sendSessionOutcome(res, outcome, instance, 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
@@ -701,7 +1036,14 @@ async function handleAuth(req, res, instance, requestId, options) {
      * 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);
+        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;
     }
     /*
@@ -784,10 +1126,41 @@ async function handleAuth(req, res, instance, requestId, options) {
      * 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 } = (body ?? {});
-        if (typeof challenge !== 'string' || typeof code !== 'string') {
-            const problem = badRequest(instance, requestId, "'challenge' and 'code' are required.");
+        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;
         }
@@ -809,8 +1182,8 @@ async function handleAuth(req, res, instance, requestId, options) {
                 }
             }
         }
-        const tokens = await options.login.completeSecondFactor(challenge, code);
-        if (tokens === undefined) {
+        const outcome = await options.login.completeSecondFactor(challenge, proof);
+        if (outcome === 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.
@@ -818,6 +1191,14 @@ async function handleAuth(req, res, instance, requestId, options) {
             refuse();
             return;
         }
+        if (outcome.kind !== 'tokens') {
+            // A gate that wanted a *particular* kind can still refuse the one that
+            // was just produced, which is why the gates run after the proof rather
+            // than instead of it.
+            sendSessionOutcome(res, outcome, instance, requestId);
+            return;
+        }
+        const tokens = outcome.tokens;
         await options.audit.write({
             orgId: tokens.orgId,
             actor: `user:${tokens.userId}`,
@@ -825,8 +1206,10 @@ async function handleAuth(req, res, instance, requestId, options) {
             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 },
+            // 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);
@@ -839,12 +1222,21 @@ async function handleAuth(req, res, instance, requestId, options) {
         return;
     }
     if (instance === '/v1/auth/refresh') {
-        const tokens = await options.login.refresh(token);
-        if (tokens === undefined) {
+        const outcome = await options.login.refresh(token);
+        if (outcome === undefined) {
             refuse();
             return;
         }
-        send(res, 200, tokenJson(tokens), requestId);
+        if (outcome.kind !== 'tokens') {
+            // A renewal is gated like a sign-in, so a policy turned on while people
+            // are signed in reaches them rather than waiting for every session to
+            // expire. The refresh token is spent either way — the claim commits
+            // before the gates are asked — so this is the end of that session and the
+            // challenge is the way on.
+            sendSessionOutcome(res, outcome, instance, requestId);
+            return;
+        }
+        send(res, 200, tokenJson(outcome.tokens), requestId);
         return;
     }
     if (instance === '/v1/auth/logout') {
@@ -857,6 +1249,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,
@@ -1386,6 +1843,87 @@ async function handle(req, res, options) {
             : presented.slice(7).startsWith('nacre_sk_')
                 ? 'service_key'
                 : 'jwt';
+        /*
+         * The narrow door, and it is reached only by a credential this API has
+         * already refused as an access token — which is exactly what an enrolment
+         * challenge is, since its audience is deliberately not the API's.
+         *
+         * Placed here rather than ahead of `authenticate` for two reasons, and the
+         * first was found by running the suite: ahead of it, every ordinary request
+         * to this path paid a JWT verification for a token it was never carrying.
+         * The second is the better one — down here the door cannot widen anything,
+         * because the only requests that reach it are ones already on their way to
+         * a 401.
+         *
+         * That is also what makes it safe to be wrong about. A route that forgets
+         * this door answers 401, never 200. A design that instead minted a real
+         * access token and asked every other route to refuse it would fail the
+         * other way, and on an authorization boundary that is the dangerous
+         * direction.
+         *
+         * Keyed on the instance, so nothing else in the API is reachable with one
+         * of these however this branch is edited. The door then narrows further, to
+         * the four routes that add a factor.
+         */
+        if ((instance === '/v1/me/second-factor' || instance.startsWith('/v1/me/second-factor/')) &&
+            options.login !== undefined &&
+            options.secondFactors !== undefined &&
+            options.secondFactors.available) {
+            const bearer = presented?.startsWith('Bearer ') === true ? presented.slice(7) : undefined;
+            const who = bearer === undefined ? undefined : await options.login.readEnrolmentChallenge(bearer);
+            // A shared account cannot enrol through this door either. It could only
+            // get here by a gate demanding a factor of an account that must not hold
+            // one, and the database refuses the row regardless — so without this the
+            // symptom is a 500 rather than the 404 the wide door answers.
+            const enrolling = who === undefined || options.users === undefined
+                ? who
+                : (await options.users.isShared(who.orgId, who.userId))
+                    ? undefined
+                    : who;
+            if (enrolling !== undefined) {
+                const who = enrolling;
+                const login = options.login;
+                const factors = options.secondFactors;
+                let enrolmentBody;
+                try {
+                    enrolmentBody = await readBody(req, options.maxBodyBytes ?? MAX_BODY_BYTES);
+                }
+                catch {
+                    const problem = badRequest(instance, requestId, 'The request body could not be read.');
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                await handleSecondFactorRoutes(req, res, instance, requestId, enrolmentBody, options, factors, {
+                    orgId: who.orgId,
+                    userId: who.userId,
+                    // Adding a factor, and nothing else. Not the listing, because a
+                    // half-authenticated caller is not owed an inventory of the account;
+                    // not the removal, because taking a factor off under a mandate to add
+                    // one is the move somebody who has stolen a password would make; and
+                    // not the sign-in assertion, which belongs to the other ceremony.
+                    offers: (rest, method) => method === 'POST' &&
+                        (rest === '' ||
+                            rest === '/webauthn' ||
+                            rest === '/webauthn/finish' ||
+                            (rest.startsWith('/') && rest.endsWith('/confirm'))),
+                    // The end of a sign-in as well as the end of an enrolment. The gates
+                    // run again inside `sessionAfterEnrolment`, because a gate that
+                    // wanted a particular kind is entitled to refuse the one just added.
+                    onEnrolled: async () => {
+                        const outcome = await login.sessionAfterEnrolment(who.orgId, who.userId);
+                        if (outcome === undefined || outcome.kind !== 'tokens')
+                            return {};
+                        return {
+                            access_token: outcome.tokens.accessToken,
+                            token_type: 'Bearer',
+                            expires_in: outcome.tokens.expiresIn,
+                            refresh_token: outcome.tokens.refreshToken,
+                        };
+                    },
+                });
+                return;
+            }
+        }
         options.observe?.authFailures.inc({ kind });
         send(res, auth.status, auth.toJSON(), requestId);
         return;
@@ -1976,15 +2514,25 @@ async function handle(req, res, options) {
                 send(res, problem.status, problem.toJSON(), requestId);
                 return;
             }
-            // Composed from the token and nothing else — no query, so this cannot
-            // grow a way to name somebody else. `organization` is included because a
-            // UI showing "you are an administrator" has to say of what, and it is the
-            // same value invariant 1 already took from the token.
+            /*
+             * Composed from the token, plus one read.
+             *
+             * It was from the token and nothing else, on the argument that no query
+             * means no way to grow into naming somebody else — which still holds,
+             * because the read takes the id the token already carries and asks one
+             * boolean about it.
+             *
+             * `holds_own_credentials` is here so a screen can leave the password and
+             * second-factor controls **off** rather than drawing controls that answer
+             * 404. That is the same rule `GET /v1/auth/methods` exists for, applied
+             * to the account instead of to the installation: ask, do not assume.
+             */
             send(res, 200, {
                 organization: auth.orgId,
                 principal_type: auth.principal.type,
                 principal_id: auth.principal.id,
                 role: auth.role,
+                holds_own_credentials: await holdsOwnCredentials(auth, options),
             }, requestId);
             return;
         }
@@ -2009,7 +2557,7 @@ async function handle(req, res, options) {
                 send(res, problem.status, problem.toJSON(), requestId);
                 return;
             }
-            if (auth.principal.type !== 'user' || auth.delegation !== undefined) {
+            if (!(await holdsOwnCredentials(auth, options))) {
                 const problem = notFound(instance, requestId);
                 send(res, problem.status, problem.toJSON(), requestId);
                 return;
@@ -2066,6 +2614,31 @@ async function handle(req, res, options) {
                 send(res, problem.status, problem.toJSON(), requestId);
                 return;
             }
+            if (outcome.kind !== 'changed') {
+                /*
+                 * A gate answered, and the password **is** already changed — the
+                 * statement committed before the session was minted. So this is not a
+                 * failure to report: it is a person who now has a new password and no
+                 * session, and the challenge is what gets them one.
+                 *
+                 * The audit event is written first for that reason. `password.change`
+                 * records what happened to the row, and it happened whatever the gate
+                 * then said about the session; writing it only on the way to a token
+                 * would leave the one action an investigator most wants out of the
+                 * journal precisely when a policy is being enforced.
+                 */
+                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,
+                });
+                sendSessionOutcome(res, outcome, instance, requestId);
+                return;
+            }
             await options.audit.write({
                 orgId: auth.orgId,
                 actor: `user:${auth.principal.id}`,
@@ -2130,122 +2703,20 @@ async function handle(req, res, options) {
                 send(res, problem.status, problem.toJSON(), requestId);
                 return;
             }
-            if (auth.principal.type !== 'user' || auth.delegation !== undefined) {
+            if (!(await holdsOwnCredentials(auth, options))) {
                 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);
+            // The wide door: a signed-in person reaches all seven routes, and a
+            // completed enrolment adds nothing to the response because they already
+            // hold a session.
+            await handleSecondFactorRoutes(req, res, instance, requestId, body, options, options.secondFactors, {
+                orgId: auth.orgId,
+                userId: auth.principal.id,
+                offers: () => true,
+                onEnrolled: async () => ({}),
+            });
             return;
         }
         if (instance === '/v1/embedding-providers' && options.embeddingProviders !== undefined) {
@@ -3411,7 +3882,24 @@ async function handle(req, res, options) {
                     send(res, problem.status, problem.toJSON(), requestId);
                     return;
                 }
-                const created = await options.users.create(auth, email, role);
+                /*
+                 * `shared` is a credential more than one person will hold, and it is
+                 * refused rather than coerced when it is not a boolean: a caller that
+                 * sent a string got the account they asked for either way, and only one
+                 * of the two answers is the one they meant.
+                 *
+                 * It cannot be changed afterwards, deliberately. Clearing it on an
+                 * account whose password is already published would reopen the surface
+                 * for whoever holds that password; setting it on somebody's real
+                 * account would take their second factor's meaning away without
+                 * removing the factor. Both are new accounts, which is cheap.
+                 */
+                if (fields.shared !== undefined && typeof fields.shared !== 'boolean') {
+                    const problem = badRequest(instance, requestId, "'shared' must be a boolean.");
+                    send(res, problem.status, problem.toJSON(), requestId);
+                    return;
+                }
+                const created = await options.users.create(auth, email, role, fields.shared === true);
                 if (created === undefined) {
                     await options.audit.write({
                         orgId: auth.orgId,