Sign-in with email
Sign-up, sign-in by password or emailed link, sessions and password reset, with a test for every way an account can be taken over.
This is an app part spec on Spekkr, published by kato. It is listed with the other specs. Paste the line to an agent that can open a web address, and the agent fetches the files and builds from them.
- Spec
kato/email-sign-in- Version
- 0.1.2
- Published by
- kato
- Updated
- 15 Nov 2026
Build this spec
Build the spec at https://spekkr.com/kato/email-sign-in/start.md.
Paste this to your AI agent. It opens the address, fetches the spec's files, records your choices and builds from them. Nothing to install, no account.
Published by kato.
What does the result look like?
What can I customize?
Your choices go into the line you copy. Anything else is yours to edit, but it leaves the tested path.
What do I get?
-
spec.mdRequirements and acceptance criteria.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.jsonfirst.methoddecides which of R3 and R4 exist.email_verificationdecides whether R2 exists. Useapp_namein every page and email, andsession_daysfor how long a session lasts.Out of scope
- Sign-in through another service, such as Google or GitHub.
- Two-factor sign-in.
spekkr/two-factoradds it. - Teams, roles and invitations.
spekkr/team-permissionsadds 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
methodisemail_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_verificationis 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
methodispasswordorboth.- 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
methodisemail_linkorboth.- 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,SecureandSameSite=Lax. Only a hash of the token is stored. - A session ends
session_daysdays 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
methodispasswordorboth.- 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_linkalone 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.
# 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.
-
design.mdData model, rules and flows.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
databaseinput.Table Columns usersid,email(unique, lowercase),email_confirmed_at,password_hash(null withemail_linkalone),created_atsessionsid,user_id,token_hash(unique),user_agent,created_at,expires_atemail_tokensid,purpose,email,user_id(null for a first sign-in),token_hash(unique),expires_at,used_atsign_in_attemptsemail,ip,at,okpurposeis one ofconfirm,sign_in,resetandchange_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
Originheader 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_URLConnection string for the chosen database. SESSION_SECRETSigns CSRF tokens. At least 32 random bytes. EMAIL_API_KEYSends the emails. Optional in development. EMAIL_API_URLWhere send_emailposts each message. Optional in development.EMAIL_FROMThe 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_URLandEMAIL_API_KEYset, it makes onePOSTtoEMAIL_API_URLwith the headerAuthorization: Bearer <EMAIL_API_KEY>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.
# 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 <EMAIL_API_KEY>` 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. -
tasks.mdBuild tasks in order, each with a check.Tasks
Work in order. Finish a task's check before starting the next.
- Set up the project. Add the database from the
databaseinput, a migration tool and a test runner. Check: an empty test run passes and the app answers on a health route. - Create the schema. Add the tables in
design.md. Check: migrations run from empty, and a test proves two users cannot share an address that differs only in case. - Sessions and the guard (R5). Tokens, the cookie,
require_user, sign-out and the safe redirect. Check: the R5 acceptance tests pass. - Sign up (R1) and confirm (R2). Capture emails in memory in tests. Check: the R1 tests pass, and the R2 tests pass if
email_verificationis on. - Password sign-in (R3). Only if
methodispasswordorboth. Check: the R3 acceptance tests pass, including the dummy hash. - Emailed link (R4). Only if
methodisemail_linkorboth. Check: the R4 acceptance tests pass. - Reset (R6) and change of address (R7). Check: the R6 and R7 acceptance tests pass.
- Pages (R8). Use the person's
app_name. Check: every page can be used with a keyboard alone and at 360 pixels wide. - Finish. Write the README and run the whole test suite. Check: every item under "Definition of done" in
spec.mdis true.
# Tasks Work in order. Finish a task's check before starting the next. 1. **Set up the project.** Add the database from the `database` input, a migration tool and a test runner. Check: an empty test run passes and the app answers on a health route. 2. **Create the schema.** Add the tables in `design.md`. Check: migrations run from empty, and a test proves two users cannot share an address that differs only in case. 3. **Sessions and the guard (R5).** Tokens, the cookie, `require_user`, sign-out and the safe redirect. Check: the R5 acceptance tests pass. 4. **Sign up (R1) and confirm (R2).** Capture emails in memory in tests. Check: the R1 tests pass, and the R2 tests pass if `email_verification` is on. 5. **Password sign-in (R3).** Only if `method` is `password` or `both`. Check: the R3 acceptance tests pass, including the dummy hash. 6. **Emailed link (R4).** Only if `method` is `email_link` or `both`. Check: the R4 acceptance tests pass. 7. **Reset (R6) and change of address (R7).** Check: the R6 and R7 acceptance tests pass. 8. **Pages (R8).** Use the person's `app_name`. Check: every page can be used with a keyboard alone and at 360 pixels wide. 9. **Finish.** Write the README and run the whole test suite. Check: every item under "Definition of done" in `spec.md` is true.
- Set up the project. Add the database from the
Is it for me?
- Kind
- app part
- Platforms
- web, backend
What does it need?
- Accounts
- An email-sending service
- Agent permissions
- shell, network
- Secrets it reads
DATABASE_URLSESSION_SECRETEMAIL_API_KEY
What changed?
- 0.1.215 Nov 2026Names what it builds.
- 0.1.114 Nov 2026Says "person" where it said "buyer".
- 0.1.014 Nov 2026Moved from dwrtz/email-sign-in.
For agents: start.md says how to build this spec, spec.json holds everything on this page, and bundle.tar.gz holds its files.