Two-factor authentication, recovery codes, and what we changed about signing in with GitHub or Google

Two-factor authentication is now available on every account: a standard TOTP secret, a QR code for whichever authenticator you already use, and a set of single-use recovery codes for the day the phone is gone.

There is not much novelty in a TOTP implementation, and that is the point — this one is built on Laravel Fortify rather than hand-rolled, because the interesting security work on an account is never the six digits. It is everything around them.

What is stored, and what confirms it

The shared secret is encrypted at rest. Enabling two-factor is two steps rather than one: the secret is generated and shown as a QR code and an otpauth:// URL, and it does not arm anything until you have typed a code it accepts. The confirmation timestamp is what the sign-in path checks, so a half-finished setup — the QR code scanned, the tab closed — never locks you out of your own account.

Recovery codes come with the secret. They are single-use, they are listed once, and viewing them or regenerating them is itself recorded. That last part matters more than it sounds: "someone looked at the recovery codes" is exactly the line you want to find in the activity journal when you are reconstructing an incident, and a recovery code being spent is its own event, distinct from an ordinary sign-in.

A failed second factor is recorded too. A password that works followed by codes that do not is a specific and unpleasant shape, and it should be visible without anyone having to correlate two systems.

The part that was actually risky: linking a provider

Mailclutch lets you sign in with GitHub or Google. Any product that offers both a password and a provider has the same trapdoor: if the provider path signs you straight in, then adding a provider to an account is a way of walking past whatever that account had protecting it.

So provider linking is treated as an account-security operation, not a convenience. Linking and unlinking are recorded. Claiming an existing account through a provider — arriving with a Google identity whose address matches an account that already exists — is its own distinct event rather than a silent sign-in, so it can never be mistaken for a normal login when you read the trail back.

The rule underneath is simple: nothing you can add to an account should be a cheaper door into it than the door you already chose.

Turning it on

Account settings, security. Scan the code with any authenticator, confirm one code, and save the recovery codes somewhere that is not the machine you sign in from. If you share an organization, do it before you invite anyone: an owner without a second factor is the weakest thing about an organization that has one.

The session list and the new-device alert are the other half of this. Two-factor stops a sign-in with a stolen password; the alert is what tells you it happened; the journal is what you read afterwards. If you drive Mailclutch from your own tooling rather than the app, the API reference covers tokens, which are managed and revoked separately from the browser session.