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?

Sign-in with email: signup desktopSign-in with email: signup error 360Sign-in with email: check emailSign-in with email: account security

What can I customize?

Database
How people sign in A password, a link sent by email, or either.

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.md Requirements 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.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.
    # 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.
    

    Open spec.md as plain text

  • design.md Data 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 database input.

    TableColumns
    usersid, email (unique, lowercase), email_confirmed_at, password_hash (null with email_link alone), created_at
    sessionsid, user_id, token_hash (unique), user_agent, created_at, expires_at
    email_tokensid, purpose, email, user_id (null for a first sign-in), token_hash (unique), expires_at, used_at
    sign_in_attemptsemail, 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

    SecretPurpose
    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_email posts 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_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.

    # 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.
    

    Open design.md as plain text

  • tasks.md Build tasks in order, each with a check.

    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.
    # 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.
    

    Open tasks.md as plain text

Is it for me?

Platforms
web, backend

What does it need?

Accounts
An email-sending service
Agent permissions
shell, network
Secrets it reads
DATABASE_URL SESSION_SECRET EMAIL_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.