Two-factor authentication
23 files3 packages1 dependency
This pack adds two-factor authentication to your app. Signed-in users turn it on from their security settings, and once it is on, signing in takes a second step after the password.
- Authenticator enrollment by QR code or a secret entered by hand, confirmed with a six-digit code.
- One-time recovery codes for signing in when the authenticator is unavailable, which the user can regenerate.
- A rate-limited login challenge that accepts either a TOTP code or a recovery code.
- An email to the account owner whenever two-factor is turned on, turned off, or its recovery codes change.
Apply the two-factor pack with Flow. Start a new session in your selected coding agent and execute the following slash command inside it.
$ npx @adonisplus/flow apply --pack=two-factor --agent=claude
$ npx @adonisplus/flow apply --pack=two-factor --agent=codex
$ npx @adonisplus/flow apply --pack=two-factor --agent=cursor
$ npx @adonisplus/flow apply --pack=two-factor --agent=opencode
After applying, Flow will make the following changes to your app.
- Establish a Security page to host the controls and back the modals, wherever your app is missing one.
- Land the backend as shipped, from the migration and model mixin through the validators, controllers, routes, and the change-notification mailer.
- Wire the modal runtime, then restyle the enrollment, recovery-codes, and challenge screens to your design system.
- Add the challenge branch to your login, and to social sign-in when you already have it.
- Run the tests, then walk enrollment, the recovery codes, and the login challenge and show you the result.
Delta will differ
Flow adapts the pack to your app, so the exact set of created and edited files depends on what you already have. This is the shape of an apply onto the React starter kit with the auth pack in place.
Foundation
security_controller.tsapp/controllers/security_controller.tsRenders the Security page that hosts the two-factor controls.createdsecurity.tsxinertia/pages/account/security.tsxSecurity page, with the two-factor section appended below its content.createdsettings.tsxinertia/layouts/settings.tsxLists the Security page in the settings sidebar.editedapp.tsxinertia/layouts/app.tsxLinks the settings area in the navigation and renders<ModalRoot />.edited
Modal runtime
app.tsxinertia/app.tsxWires the modal runtime.editedadonisrc.tsadonisrc.tsRegisters the modal provider.edited
Migration
xxxx_add_totp_columns_to_users.tsdatabase/migrations/xxxx_add_totp_columns_to_users.tsAdds the TOTP and recovery-code columns to the users table.created
Model, transformer & validators
user.tsapp/models/user.tsAdds thewithTotpManagement()mixin.editeduser_transformer.tsapp/transformers/user_transformer.tsExposes the two-factor state and the remaining-codes count.editeduser.tsapp/validators/user.tsAdds the TOTP and recovery-code validators.edited
Controllers
two_factor_enrollment_controller.tsapp/controllers/two_factor_enrollment_controller.tsStarts enrollment, verifies the first code, and disables two-factor.createdrecovery_codes_controller.tsapp/controllers/recovery_codes_controller.tsShows the recovery codes once and regenerates them.createdtwo_factor_challenge_controller.tsapp/controllers/two_factor_challenge_controller.tsRenders and verifies the rate-limited login challenge.createdsession_controller.tsapp/controllers/session_controller.tsRedirects a two-factor user to the challenge instead of logging in.edited
Mailer & email template
two_factor_changed_notification.tsapp/mails/two_factor_changed_notification.tsThe change-notification email for enable, disable, and regenerate.createdtwo_factor_changed.edgeresources/views/emails/two_factor_changed.edgeBody of the change-notification email.created
Pages
two_factor_enroll.tsxinertia/pages/account/two_factor_enroll.tsxEnrollment modal with the QR code and manual secret.createdtwo_factor_recovery_codes.tsxinertia/pages/account/two_factor_recovery_codes.tsxRecovery-codes modal with copy and download.createdtwo_factor_challenge.tsxinertia/pages/auth/two_factor_challenge.tsxLogin challenge screen with the TOTP and recovery-code toggle.created
Routes
routes.tsstart/routes.tsAdds the enrollment, recovery-codes, and challenge routes.edited
Factory & tests
user_factory.tsdatabase/factories/user_factory.tsAdds thetwoFactorEnabledstate and the enable hook.editedenrollment.spec.tstests/browser/two_factor/enrollment.spec.tsEnrollment, disable, and regenerate specs.createdlogin_challenge.spec.tstests/browser/two_factor/login_challenge.spec.tsLogin-challenge specs for TOTP and recovery codes.created
Configuration
Section titled "Configuration"The withTotpManagement() mixin on the User model backs the whole feature. Pass an options object to change its defaults.
issuerstringAdonisJS App.windownumber1 accepts the previous, current, and next period, about 90 seconds. Defaults to 1.recoveryCodesCountnumber10.withTotpManagement(encryption, hash, { issuer: 'ACME', window: 2 }) Secrets are encrypted, recovery codes are hashed
Section titled "Secrets are encrypted, recovery codes are hashed"The confirmed TOTP secret is encrypted at rest and each recovery code is stored only as a hash. A leaked database row cannot be turned back into a working secret or a usable code.
Enrolling takes two steps
Section titled "Enrolling takes two steps"Enabling first creates a pending secret and shows the QR code. Two-factor is not active until the user confirms it with a code from their authenticator. Until that first code lands, nothing about the account has changed.
Recovery codes are shown once
Section titled "Recovery codes are shown once"The codes appear a single time, right after the user enables two-factor or regenerates them. The screen cannot be reopened, so a refresh or a direct visit shows nothing. Regenerating replaces the whole set and retires the old codes.
A used code cannot be replayed
Section titled "A used code cannot be replayed"Each accepted code's time step is recorded, so the same code cannot be used a second time inside its window.
The login challenge is rate limited
Section titled "The login challenge is rate limited"Failed challenge attempts run through two limiter keys, one scoped per IP and a stricter one per IP-and-user that adds a 20-minute block after five failures. Both run through penalize, so the budget is spent only when a code is wrong and a correct code is always free.
const ipKey = `two_factor_${request.ip()}`
const userKey = `two_factor_${request.ip()}_${challenge.userId}`
const challengeLimiter = limiter.multi([
{ duration: '1 min', requests: 10, key: ipKey },
{ duration: '1 min', requests: 5, blockDuration: '20 mins', key: userKey },
])Every change emails the account owner
Section titled "Every change emails the account owner"Turning two-factor on or off, or regenerating the recovery codes, sends the account owner an email out of band. If a compromised session quietly strips two-factor, the change is at least visible to the real owner.
Added in Flow 0.2.0.