# 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 | | --- | --- | | `users` | `id`, `email` (unique, lowercase), `email_confirmed_at`, `password_hash` (null with `email_link` alone), `created_at` | | `sessions` | `id`, `user_id`, `token_hash` (unique), `user_agent`, `created_at`, `expires_at` | | `email_tokens` | `id`, `purpose`, `email`, `user_id` (null for a first sign-in), `token_hash` (unique), `expires_at`, `used_at` | | `sign_in_attempts` | `email`, `ip`, `at`, `ok` | `purpose` is one of `confirm`, `sign_in`, `reset` and `change_email`. ## Rules - Every token is random, at least 32 bytes, and stored only as a SHA-256 hash. Compare hashes in constant time. - Hash passwords with argon2id or with bcrypt at cost 12 or more. When an address has no account, hash the submitted password against a fixed dummy hash anyway, so the two cases take the same time. - Mark a token used and act on it in one transaction, so two requests cannot both use it. - Count attempts from `sign_in_attempts`. A successful sign-in does not clear the count inside the 15 minutes. - State-changing requests need a CSRF token, or a check that the `Origin` header is the app's own. - A redirect after sign-in is followed only when it starts with one `/` and has no backslash. ## Email Five messages: confirm address, sign-in link, reset link, "someone tried to sign up with your address", and "your address was changed". Put sending behind one small interface so tests capture messages without a network. ## Configuration | Secret | Purpose | | --- | --- | | `DATABASE_URL` | Connection string for the chosen database. | | `SESSION_SECRET` | Signs CSRF tokens. At least 32 random bytes. | | `EMAIL_API_KEY` | Sends the emails. 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 - A link that changes an email address works for 24 hours. - A password is at most 200 characters. ## 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.