Two-factor authentication and recovery codes

There is no identity-based recovery

Start here, because it changes what the rest of this article is for. We never asked who you are. There is no document, no phone number and no billing address on file, so no procedure exists by which you could prove an account is yours after losing access to it. That is the trade the no-KYC policy makes, and it does not bend in either direction.

The recovery codes are the recovery procedure. Treat them as though they are the account, because operationally they are.

Enabling it

Two mechanisms, usable together:

• TOTP: the familiar six digits on a thirty-second step. Any authenticator works.
• WebAuthn: a hardware security key or a platform authenticator. Register two.

Once it is on, the second factor is required at sign-in, before an out-of-band console session, and before the account email can be changed. It is not required for API tokens, which are a separate credential with their own scopes.

Verifying a TOTP secret yourself

apt install -y oathtool
oathtool --totp -b JBSWY3DPEHPK3PXP

The code printed should match the one on your phone at the same second. When it does not, the cause is almost always a clock rather than a secret.

Clock drift

TOTP is a function of the time. We accept one step either side, so thirty seconds of slack: plenty for a phone, not enough for a server that has been up for a year without a working time client.

timedatectl status
systemctl status systemd-timesyncd     # Debian
chronyc tracking                       # AlmaLinux

System clock synchronized: yes is the line that matters. Fix the clock before concluding that anything else is broken.

Recovery codes

Ten codes, single use, generated when you enable the second factor. Each signs you in once and is then dead.

• Print them. Paper has no battery, no firmware update and no lock screen.
• Keep one copy in a different building from the machine you sign in from.
• Do not store them in the password manager holding the account password. That turns two factors back into one.
• Regenerate the set after using one, or whenever you are unsure a copy is still private. Regenerating kills every code in the old set.

If you lose the factor but still have codes

Sign in with a code, remove the old factor, enrol the new one, regenerate the set. Four minutes, no ticket, no waiting for anybody.

If you lose both

The account is gone. Not locked pending a form, not suspended while somebody reviews it — gone, along with everything running under it. We would rather write that plainly than imply an escape hatch that does not exist, and support cannot make one appear; there is nothing on our side to check you against.

The mitigation is boring and it works. Two hardware keys, or one key and a printed set of codes in a drawer somewhere else. And a copy of anything genuinely irreplaceable held somewhere that is not us, which is good practice regardless of who your host is.