# Two-factor sign-in ## What this builds A second step for an app that already has sign-in. After the first step, a person with two-factor turned on enters a six-digit code from an authenticator app, or a recovery code, before a session starts. Read `spekkr.inputs.json` first. `issuer_name` is the name authenticator apps show. `remember_device` decides whether R5 exists and `required_for_all` whether R6 does. This spec needs two things from the app it is added to: a `users` table, and the place in the sign-in code where the first step has succeeded and a session is about to start. `spekkr/email-sign-in` has both. ## Out of scope - Codes by text message or email. - Passkeys and hardware keys. - The first sign-in step itself. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. Turn it on - The person asks to turn two-factor on and is shown a QR code and the same secret as text, to add to an authenticator app. - Two-factor is on only after they enter a code the app made from that secret. - The secret is 20 random bytes. It is stored encrypted, never as it is. - Turning it on shows the recovery codes of R3 once, and sends an email that says two-factor was turned on. Accept when: a correct code turns it on, a wrong code leaves it off, and the stored secret cannot be read without `TOTP_ENCRYPTION_KEY`. ### R2. The second step - When the first step succeeds for an account with two-factor on, no session starts. The person gets a pending sign-in that lasts 10 minutes and is asked for a code. - A code is the six-digit TOTP for the current 30 seconds. The step before and the step after are accepted too, to allow for clocks that differ. - A code works once. The same code a second time is refused, even inside its 30 seconds. - After 5 wrong codes the pending sign-in ends and the person starts again. Accept when: the tests in `design.md` produce the expected codes, a correct code starts a session, a repeated code is refused, and the sixth attempt is refused even with a correct code. ### R3. Recovery codes - 10 codes, each 10 characters from letters and digits that are not easily confused, shown once and stored as hashes. - A recovery code can be used in place of a code in R2. It works once. Using one sends an email that says how many are left. - The person can make a new set, which cancels the old one. That needs a current code. Accept when: a recovery code signs in once and never again, and a new set cancels every old code. ### R4. Turn it off - Turning two-factor off needs a current code or a recovery code. - It deletes the secret, the recovery codes and any trusted devices, and sends an email that says two-factor was turned off. Accept when: after turning it off the first step alone starts a session, and the secret is gone from the database. ### R5. Trusted devices Only if `remember_device` is on. - At the second step the person can tick "trust this device for 30 days". The device gets a cookie with a random token, stored as a hash. - On a trusted device the second step is skipped. - The account page lists trusted devices and can remove one or all. Changing the password, if the app has one, removes them all. Accept when: a trusted device skips the code for 30 days and not after, and a removed device is asked for a code again. ### R6. Required for every account Only if `required_for_all` is on. - An account without two-factor is sent to R1 after the first step. Until it is on, every other page redirects there and every API call answers 403. - R4 is not offered. Accept when: an account without two-factor can reach nothing but the set-up pages and sign-out. ### R7. Ask again before something sensitive - A guard, `require_recent_second_factor(minutes)`, lets a route ask for a code again when the last one was entered longer ago than `minutes`. - The person is sent to a page that asks for a code and then back to what they were doing. Accept when: a guarded route asks for a code after the time has passed and not before. ### R8. Pages - Pages: set up (QR code, secret as text, code field), the recovery codes with a way to copy and download them, the second step, and the two-factor part of the account page. - The code field takes digits only, offers the device's one-time-code autofill, and accepts a code typed with a space in the middle. - Under it, "Use a recovery code" swaps it for a second field that takes a recovery code's letters and digits. The two are never one field. Accept when: each page works with a keyboard alone and at a 360 pixel wide screen. ## Definition of done - Every acceptance check above has an automated test, and all tests pass. - No test or log line contains a secret, a code or a recovery code. - A README explains how to set the secrets, where the two hooks into the app's sign-in are, and how to run the tests.