Skip to main content

Option 1: Email and password in core

emailPassword is a top-level config key. It stores a real email in users.email, hashes the password with PBKDF2, locks repeated failures, and creates ordinary core sessions, so GET /auth/session, POST /auth/sign-out, every framework adapter and the client bindings work with no extra wiring. createTheAuthHandler serves its routes under /auth/email/*.
lib/theauth.ts
emailPassword needs auth.session. With requireVerification on (the default) it also needs emailVerification, and createTheAuth throws at startup if that is missing. passwordReset is optional: without it the forgot and reset routes are not served. Errors are { error: { code, message } } with one of INVALID_EMAIL, INVALID_PASSWORD, INVALID_CREDENTIALS (401), EMAIL_NOT_VERIFIED (403), INVALID_TOKEN, EMAIL_TAKEN (409, only with verification off) or SIGN_IN_LOCKED (429 with Retry-After). A sign-in that the sign-in gate holds back answers like the username module does.

What it does and does not tell the caller

  • Verification on (default). Sign-up creates the account and sends the email, but creates no session. Sign-in checks the password first and only then answers EMAIL_NOT_VERIFIED, so someone who guesses an address learns nothing.
  • Taken addresses look new. Sign-up for an address that already has a user answers the same 201 { verificationRequired: true }. It never attaches a password to the existing user, so an address that signed up through Google cannot be claimed by someone else. A password account that is still unverified gets a fresh verification email; its password does not change.
  • A reset proves the inbox. A completed password reset marks the address verified and replaces the password, which also clears an account that someone else pre-registered with your address.
  • Lockout and rate limits follow the username module (emailPassword.lockout, same defaults) and each route has a per-IP limit.
  • Credentials live in the same table as username accounts, so password reset, forced password change and two-factor through the gate work unchanged. Accounts imported with theauth migrate (credential keyed by the lowercase address) sign in here too.

Sign up, verify and sign in without a browser

flow.ts
The client bindings take emailPassword: true and talk to these routes. There is a test of exactly this flow through the session store, in packages/client/tests/session-store-email-password.test.ts.

Programmatic use

theauth.emailPassword is the module behind the routes: signUp, signIn, verifyEmail, resendVerification, changePassword and markVerified. They throw EmailPasswordError (with a code), LoginLockedError or SignInGateError.

Option 1a: The email plugin (@glinr/theauth-email), legacy

The plugin predates the core module and does not work with core sessions. Its sign-in token is a random id in its own format, so GET /auth/session, POST /auth/sign-out and the adapters answer 401 for it, it sets no cookie, it writes with raw SQLite statements so it is only reliable on the SQLite drivers, and its sign-up returns a session token before the address is verified. Use Option 1 for new projects. The package stays published for existing installs and is deprecated.
lib/theauth.ts
It registers POST /auth/sign-up, /auth/sign-in, /auth/verify-email, /auth/request-reset, /auth/reset-password and /auth/change-password. To move to the core module, replace the plugin with the emailPassword, emailVerification and passwordReset config keys and point your client at /auth/email/*. The plugin keeps its accounts in theauth_email_accounts, so existing users need to reset their password once or be imported.

Option 1b: Username as the identifier

The username module hashes a password against a username string. It does not send verification or reset emails or track emailVerified; those live in separate modules (see below).
lib/theauth.ts
The username module stores a placeholder ({username}@username.local) in users.email, so do not rely on that column for delivery.

Password hashing

Passwords are hashed with PBKDF2-HMAC-SHA256 at 600000 iterations (OWASP guidance). Each hash is stored as pbkdf2:<iterations>:<salt_hex>:<hash_hex>, so the algorithm and cost travel with the hash and older hashes keep verifying with their own parameters. On a successful sign-in, a hash made with fewer iterations than the target is rewritten transparently. Comparison is constant time, and an unknown username still pays one hash so timing does not reveal which usernames exist. Set the target with pbkdf2Iterations on the username or password reset config, or with the THEAUTH_PBKDF2_ITERATIONS environment variable (config wins). Raising it upgrades users gradually as they sign in. Cost: about 100 ms per hash at 600000 iterations on an Apple Silicon laptop (about 17 ms at the former 100000). Cloudflare Workers limits CPU time per request, so on the free plan or tight budgets set a lower value such as 100000 and compensate with rate limiting and breached password checks. Where the runtime allows, prefer a memory hard function (scrypt or argon2id) through your own hasher. The Go library uses argon2id (64 MiB, t=3, p=4) with parameters stored in a PHC string.

Failed sign-in lockout

Username sign-in locks repeated failures, on by default. It follows the Go library’s login throttle.
  • Per account, any IP. 10 failures inside 15 minutes lock the account for 15 minutes. Each repeat lockout inside 24 hours doubles the lock, capped at 1 hour.
  • Per account and IP. After 3 misses the pair is delayed 1 second, doubling per extra miss up to 15 minutes. Other IPs are not slowed. This needs trustedProxy so the IP is known; without it only the per-account lock applies.
  • Same answer for unknown names. The counters are keyed by the submitted username, so a name that does not exist locks exactly like one that does. A locked sign-in answers 429 with Retry-After and the body { error, code: "SIGN_IN_LOCKED", retryAfter }; the signIn function throws LoginLockedError. Locked attempts are refused before any hashing and are not counted.
  • Unlock. The lock ends on its own. theauth.username.unlockAccount("alice") lifts it at once, and a correct password from an unlocked client clears the counters.
The trade-off: anyone who knows a username can lock its owner out from any IP. The harm is bounded. The lock never extends while it is active, it is capped by maxLockoutSeconds, escalation is forgotten after the strike window, and an admin can unlock. If that is not acceptable, raise maxFailures or set lockout: false and rely on the per-IP rate limit.
theauth.ts
Counters live in the rateLimit secondary storage (memory by default, so share a store such as Redis or the database across instances). If the store errors, sign-in is let through by default and a startup warning says so; set failClosed: true to answer 429 instead. THEAUTH_LOGIN_LOCKOUT_DISABLED=true or lockout: false turns the feature off.

Option 2: Passwordless

If you would rather not store passwords at all, theAuth’s passwordless methods sign users in with a real email address, so there is no password reset screen to build:
  • Magic link, a single-use link emailed to the user, no password.
  • Email OTP, a numeric code emailed to the user, no password.
Both can be added as a plugin (magicLink(), emailOtp()) or as a top-level config key on createTheAuth(), which exposes a module with a handleRequest you forward matching requests to. Both require auth.session.

Option 3: Bring your own (better-auth, Auth.js, Clerk, custom)

If you already run email+password auth in an existing system, don’t migrate it, adapt it. customAuth wraps an arbitrary resolver function as an AuthAdapter so theAuth’s agent layer can resolve the human user from an inbound request without owning the credential flow:
See Concepts for how theAuth’s agent layer composes with an external human-auth provider, and the migration guides for better-auth, Auth0, and Clerk specifically.

Supporting modules (compose with any of the above)

These are independent, headless modules, use them regardless of which sign-in method you pick:

Email verification

createEmailVerificationModule (@glinr/theauth/auth), or theauth.emailVerification when you pass the emailVerification config key. Sends and confirms email verification tokens.

Password reset

createPasswordResetModule (@glinr/theauth/auth), or theauth.passwordReset when you pass the passwordReset config key. Token-based reset flow that revokes existing sessions on success by default (revokeSessionsOnReset).

Breach checking

Reject passwords found in known breaches via HaveIBeenPwned.

Two-factor auth

Add TOTP as a second factor.

Username and password

theAuth’s actual built-in password module.

Magic link

Passwordless alternative using a single-use email link.

Email OTP

Numeric code via email, no password required.

Authentication overview

All sign-in methods available in theAuth.
Last modified on October 19, 2026