← Pattern library

Authentication

Email Login

Standard email-and-password sign-in. The user enters credentials, the system verifies them, and a session is created on success.

🌱

When to use this

When your app needs basic email-based authentication and you're not using social login or magic links yet.

authloginemailpasswordsignin
✨ Built using these library patterns:
email-login

What I assumed

I made these guesses to fill gaps. Let me know if any are wrong.

    Flow diagram

    Step-by-step recipe

    Copy this and paste into Cursor, Claude Code, or v0.

    PATTERN: Email Login
INPUT: email, password
OUTPUT: session_token | error_message

STEPS:
  1. User opens login form
  2. User enters email and password
  3. Validate email format on the client (quick feedback)
  4. Send credentials to server over HTTPS
  5. IF account locked (too many failures) → show "Account temporarily locked, try again in N minutes"
  6. Look up user by email
  7. IF no user found OR password mismatch → show "Email or password doesn't match" (same message for both — security)
  8. Create session token, store as HttpOnly cookie
  9. Redirect to the page the user was trying to reach (or home)

ERROR_HANDLING:
  - Database unreachable → retry once, then show "Something's wrong on our end, please try again shortly"
  - 5 failed attempts in 10 minutes → temporary lock, send "unusual activity" email
  - Session creation fails → log out cleanly, do not partial-login

EXTENSION_POINTS:
  - 2FA after password check (composable_with: ["2fa"])
  - "Remember me" longer session (composable_with: ["remember-me"])
  - Password reset link on login screen (composable_with: ["password-reset"])

    States — how things change

    StateDescriptionTransitions
    Login form openUser is entering credentials
    • Submitted→Verifying
    Verifying credentialsServer is checking email and password
    • Match→Signed in
    • Mismatch→Login form open
    • Locked→Account locked
    Signed inSession active, user can access protected pagesterminal
    Account lockedToo many failed attempts, temporarily blocked
    • Cooldown elapsed→Login form open

    Easy-to-miss situations

    The kinds of edge cases that break demos.

    • What if the user forgets their password?

      high

      They'll fail repeatedly and possibly get locked out.

      Suggested handling: Show "Forgot password?" link prominently below the password field. Compose with `password-reset` pattern.

    • What if someone tries every common password?

      high

      Brute-force attack. Without rate limiting, attackers can guess weak passwords.

      Suggested handling: Lock the account after 5 failures in 10 minutes. Send "unusual activity" email. Add CAPTCHA after 3 failures.

    • What if the user is on a shared computer?

      medium

      They might forget to log out, exposing the account.

      Suggested handling: Add a "This is a public device" checkbox that gives a shorter session (e.g., 30 minutes idle timeout).

    • What if the session token is stolen via XSS?

      high

      An attacker with the token can impersonate the user.

      Suggested handling: Set cookie as `HttpOnly` and `Secure`. Add CSRF tokens for state-changing actions. Rotate session on privilege escalation.

    • What if the email service is down?

      medium

      Lock notifications and password resets fail silently — user is confused.

      Suggested handling: Queue critical emails (using a reliable provider like Resend). Show "We had trouble sending — try again or contact support".

    Composes well with

    Combine these patterns when you need a richer flow.

    2faemail-verificationpassword-resetmagic-link
    Build a flow starting from this pattern →