docs(mfa): add multi-factor authentication guide

docs/vantage/multi-factor-authentication.md

@@ -0,0 +1,120 @@
+---
+id: multi-factor-authentication
+title: Multi-factor authentication
+sidebar_label: Multi-factor authentication
+---
+
+A second sign-in factor for password accounts, available on every plan, no
+licence required. Two kinds: an authenticator app (TOTP) and a passkey.
+
+:::info Not for single sign-on accounts
+If you sign in through your organisation's identity provider, two-factor
+authentication and passkeys are set up there, not in Vantage. Your provider's
+own session policy applies instead.
+:::
+
+## Setting up an authenticator app
+
+1. Go to your account menu and choose **Security**.
+2. Under **Authenticator app**, choose **Set up**.
+3. Scan the QR code with an app such as Google Authenticator, 1Password or
+   Authy, or enter the shown key manually if you cannot scan.
+4. Enter the 6-digit code the app displays to confirm it.
+
+Once confirmed, you will be asked for a fresh code from that app every time
+you sign in with your password.
+
+## Setting up a passkey
+
+A passkey uses your device's built-in security (a fingerprint, face
+recognition, or a security key) instead of a code. It can be used two ways:
+as a second factor after your password, or on its own for **passwordless**
+sign-in.
+
+1. Go to **Security** in your account menu.
+2. Under **Passkeys**, choose **Add a passkey**.
+3. Follow your browser or device's prompt.
+
+Once added, the login page offers a **Sign in with passkey** button that
+needs no password at all, alongside the usual second-factor prompt if you
+sign in with a password instead.
+
+You can add more than one passkey (for example, one per device) and rename or
+remove them individually from the Security page.
+
+## Recovery codes
+
+The first time you set up either factor, Vantage shows you ten **recovery
+codes**. Each one works once, in place of your authenticator app or passkey,
+if you lose access to both. Save them somewhere safe - a password manager or
+a printed copy - because they are shown only this one time.
+
+If you run low, regenerate a fresh batch of ten from the Security page. This
+immediately invalidates every code from the previous batch.
+
+:::warning Losing every factor and every recovery code
+If you lose your authenticator app, your passkeys and your recovery codes all
+at once, you cannot sign yourself back in. An owner or admin can reset your
+MFA from **Settings → People** (see below), after which you can sign in with
+your password and set up a new factor.
+:::
+
+## Owners: requiring MFA for everyone
+
+Owners can turn on **Require MFA for password sign-in** under **Settings →
+Access**. When this is on:
+
+- Anyone signing in with a password who has not yet set up a factor is asked
+  to enrol one immediately, before they can do anything else.
+- Anyone who already has a factor is unaffected beyond the normal prompt.
+- Members who sign in through single sign-on, or with a passkey used
+  passwordlessly, already satisfy the requirement and are not interrupted.
+- People already signed in are not signed out. The requirement applies from
+  their next sign-in.
+- Nobody who is required to have a factor can remove their last one - the
+  **Remove** buttons on the Security page are disabled once removing them
+  would leave the account with none.
+
+## Resetting a locked-out member's MFA
+
+If a member loses access to their authenticator app, their passkeys and their
+recovery codes, an owner or admin can clear their MFA entirely:
+
+1. Go to **Settings → People**.
+2. Find the member and choose **Reset MFA**.
+3. Confirm your own identity when prompted (this is a sensitive action, so it
+   asks you to re-authenticate first).
+
+This removes their authenticator app, every passkey and every recovery code.
+They sign in with their password alone and are asked to set up a new factor
+on their next sign-in, or immediately if **Require MFA** is on.
+
+An admin cannot reset an owner's MFA - only another owner can.
+
+## Passkeys and moving your instance
+
+A passkey is tied to the exact address you registered it on. If you later
+move a self-hosted instance to a new domain, or rename a cloud instance so
+its address changes, every passkey registered on the old address stops
+working - your browser and device will not offer them for a different host,
+by design of the WebAuthn standard itself.
+
+Authenticator app codes and recovery codes are unaffected by a host change,
+since neither is bound to an address. If you rely on passkeys, plan to
+re-register them after moving or renaming an instance, and keep your recovery
+codes handy in the meantime.
+
+## Re-confirming your identity for sensitive actions
+
+A handful of actions ask you to confirm your identity again even while
+signed in, whether or not you have MFA enrolled: revealing a vault secret,
+downloading a private key, and connecting to the browser console. This
+confirmation (using your factor, or your password if you have none) is valid
+for ten minutes, so you are not asked again for a second sensitive action
+shortly after the first.
+
+:::info API tokens are not prompted
+An API token performs these same actions with no re-confirmation step, since
+there is no person present to prompt. If this matters for your use case,
+issue narrowly scoped, short-lived tokens rather than broad ones.
+:::

docs/vantage/settings.md

@@ -78,6 +78,12 @@ sign-in. Vantage refuses any change that would leave nobody able to sign in,
 whether that is switching off passwords or disabling your last provider. Keep
 one route open until everyone who needs access can use the new one.
 
+### Require MFA
+
+Owners can require a second sign-in factor for everyone signing in with a
+password. See [Multi-factor authentication](multi-factor-authentication.md)
+for what this does, how members enrol, and how to reset a locked-out member.
+
 ## Monitoring
 
 - **Offline threshold**, how long a server may go unheard from before it is