TOTP
Two-factor sign-in with an authenticator app, with recovery codes and a reset for a lost device.
On this page
Setup
One-time codes are encrypted with the site's key. Make one first, which saves app.key in site/data/env.json:
phlat key:generate
key:generate refuses to replace a key that exists, because everything encrypted under the old one stops being readable. --force replaces it anyway. Code reads the key with $app->encryptionKey().
Then each user turns it on from their profile page in the dash. Set up shows a QR code to scan, and a code from the app confirms it. Eight recovery codes are shown once, and each works a single time in place of a code. Turning it off asks for a code (or a recovery code) and the password.
Signing in
Once the password checks out, the visitor lands on a page that asks for the code, and a right code finishes the sign-in. It applies to password sign-in only (auth.password). An OpenID Connect sign-in is proven by its provider, which has its own second step.
Requiring codes
Codes are optional for each user until the site asks for them. Turn the rule on in the site config:
{
"addons": {
"phlat/totp": { "require": true }
}
}
With require on, a user who has no codes sets them up when they sign in: after the right password they scan a QR code, confirm a code and save their recovery codes, and the sign-in finishes. Users who have codes are asked for one as usual. The first sign-in after turning it on is trusted on the password alone, so turn it on once your users are ready to set up.
Lost authenticator
An editor with the users.manage permission can reset a user's codes from the users page, or on the command line:
phlat @totp:reset adam
Both turn the codes off and end every session the user has. The user signs in with their password alone and sets it up again.
Limits
A wrong code counts against five tries in five minutes for that user, then answers 429. A code that was accepted can't be used again in its 30-second window.
Adding another step
The step is held by $app->session->afterPassword(), a core hook that runs once a password checks out. A hook returns the URL of a page that finishes the sign-in, and the first URL wins: login() returns false, pending() and pendingUrl() say who and where, and that page ends it with loginAs(). A passkey or a forced password change registers its own hook the same way.