# Design This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them. ## Data model Use the database in the `database` input. | Table | Columns | | --- | --- | | `two_factor` | `user_id` (primary key), `secret_encrypted`, `enabled_at` (null until confirmed), `last_step` | | `recovery_codes` | `id`, `user_id`, `code_hash`, `used_at` | | `pending_sign_ins` | `id`, `user_id`, `token_hash` (unique), `attempts`, `expires_at` | | `trusted_devices` | `id`, `user_id`, `token_hash` (unique), `user_agent`, `created_at`, `expires_at` (only if `remember_device` is on) | Sessions gain one column, `second_factor_at`, for R7. ## The code Codes follow RFC 6238: HMAC-SHA-1 over the number of 30-second steps since 1970, six digits. Use a maintained library if the language has one, and check it against these values. The secret is the ASCII text `12345678901234567890`. | Time, in seconds since 1970 | Code | | --- | --- | | 59 | `287082` | | 1111111109 | `081804` | | 1111111111 | `050471` | | 1234567890 | `005924` | | 2000000000 | `279037` | Rules: - Accept the current step and one step either side. Store the step of the last accepted code in `last_step` and refuse any code whose step is not greater. - Compare codes in constant time. - Take the time from one function, so tests can set it. ## The secret - Show it to the person in base32 without padding, and in the QR code as `otpauth://totp/ISSUER:EMAIL?secret=SECRET&issuer=ISSUER`, with the `issuer_name` input as the issuer and both parts URL-encoded. - Encrypt it with AES-256-GCM under `TOTP_ENCRYPTION_KEY`, with a fresh random nonce stored next to it. - Draw the QR code on the server or in the page. Never send the secret to another site to have it drawn. ## The hook into sign-in 1. Where the first step succeeds, ask `second_factor_needed(user, request)`. It is true when two-factor is on and the device is not trusted. 2. If true, create a pending sign-in, set its token in a short-lived cookie and send the person to the second step. Do not start a session. 3. When the second step succeeds, delete the pending sign-in and start the session the app's own way, with `second_factor_at` set. Recovery codes are stored as SHA-256 hashes; they are random and long enough for that. Count wrong recovery codes toward the same 5 attempts as wrong codes. ## Configuration | Secret | Purpose | | --- | --- | | `DATABASE_URL` | Connection string for the chosen database. | | `TOTP_ENCRYPTION_KEY` | Encrypts the secrets. 32 random bytes, base64. | | `EMAIL_API_KEY` | Sends the security notices. Optional in development. | | `EMAIL_API_URL` | Where `send_email` posts each message. Optional in development. | | `EMAIL_FROM` | The address every email is sent from. Optional in development. | ## Sending email Send every email through one function, `send_email(to, subject, text)`. - With `EMAIL_API_URL` and `EMAIL_API_KEY` set, it makes one `POST` to `EMAIL_API_URL` with the header `Authorization: Bearer ` and the JSON body `{"from": EMAIL_FROM, "to": ..., "subject": ..., "text": ...}`. Any 2xx answer means sent. The person points the address at their email service, or at a few lines that translate for it. - With neither set, outside production, the message goes to a local outbox that tests read. It is not printed: a message can hold a link that signs someone in. In production the app refuses to start without both. ## Named here - Recovery codes are drawn from `ABCDEFGHJKLMNPQRSTUVWXYZ23456789`. - "A current code" is a code from the authenticator app, not a recovery code. ## What this spec leaves to you Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.