# Sign-in with email ## What this builds Accounts for a web app. A person signs up with an email address, signs in with a password or a link sent to that address, stays signed in with a session cookie, and can reset a forgotten password. Other code asks one guard who is signed in. Read `spekkr.inputs.json` first. `method` decides which of R3 and R4 exist. `email_verification` decides whether R2 exists. Use `app_name` in every page and email, and `session_days` for how long a session lasts. ## Out of scope - Sign-in through another service, such as Google or GitHub. - Two-factor sign-in. `spekkr/two-factor` adds it. - Teams, roles and invitations. `spekkr/team-permissions` adds them. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. Sign up - A person signs up with an email address and, unless `method` is `email_link`, a password. - Addresses are trimmed, stored in lowercase and unique. - A password has at least 12 characters and is not the email address. It is stored as a slow, salted hash made for passwords. - Signing up with an address that already has an account answers exactly as a new address does. The owner of the address gets an email that says someone tried. Accept when: a new address gets an account, a short password is refused with a message next to the field, and the response for a taken address cannot be told from the response for a new one. ### R2. Confirm the email address Only if `email_verification` is on. - Signing up sends a link that confirms the address. It works once, for 24 hours. - An account that is not confirmed cannot sign in. The sign-in page says so and offers to send the link again, at most 3 times an hour per address. Accept when: the link confirms the account, a used or expired link is refused, and the fourth resend inside an hour is refused. ### R3. Sign in with a password Only if `method` is `password` or `both`. - The error for a wrong password and for an unknown address is the same, and the two take the same time to within the cost of one password hash. - After 5 failed attempts for one address inside 15 minutes, further attempts for that address are refused until the 15 minutes pass, with a message that says when to try again. A correct password during that time is refused too. - No more than 20 attempts come from one IP address inside 15 minutes. Accept when: a correct password starts a session, the sixth attempt is refused even with the right password, and a test shows an unknown address runs a password hash. ### R4. Sign in with an emailed link Only if `method` is `email_link` or `both`. - The person enters an address and gets a link. The response is the same whether or not the address has an account. With `email_link`, an unknown address gets an account. - The link works once, for 15 minutes. It opens a page with one button, and the session starts when the button is pressed, so a mail scanner that opens the link does not use it up. - At most 5 links are sent per address inside 15 minutes. Accept when: pressing the button starts a session, fetching the link with GET alone does not use it up, and a used or expired link is refused. ### R5. Sessions - A session is a random token of at least 32 bytes in a cookie that is `HttpOnly`, `Secure` and `SameSite=Lax`. Only a hash of the token is stored. - A session ends `session_days` days after it started, at sign-out, or when the person ends it from the list in R8. - "Sign out everywhere" ends every session of the account. - One guard, `require_user`, gives the signed-in user to a route or answers 401 for an API call and a redirect to sign-in for a page. After sign-in the person lands on the page they first asked for, if it is a path on this site. Accept when: a signed-out request to a guarded route gets 401, an expired session is refused, and a redirect address that points at another site is ignored. ### R6. Reset a password Only if `method` is `password` or `both`. - Asking for a reset answers the same whether or not the address has an account. - The link works once, for 30 minutes. At most 3 are sent per address in an hour. - Setting a new password ends every other session of the account and cancels every unused reset link. Accept when: the new password signs in, the old one does not, a second use of the link is refused, and a session that was open on another device is ended. ### R7. Change the email address - The person asks from the account page. With a password they give it again. With `email_link` alone they must have signed in during the last 10 minutes. - A link goes to the new address and the change happens when it is opened and confirmed. The old address gets a message that says the address was changed. Accept when: the account signs in under the new address only after the link is confirmed, and a new address that belongs to another account is refused. ### R8. Pages - Pages: sign up, sign in, "check your email", reset password, and account security with the email address, the password and the list of open sessions. - The session list shows the browser, the time of sign-in and which one is this one. - Every form shows its errors next to the field that caused them. 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 password, a session token or a link token. - A README explains how to set the secrets, run the app and run the tests.