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
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
lib/theauth.ts
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 trackemailVerified; those live in separate modules (see below).
lib/theauth.ts
Password hashing
Passwords are hashed with PBKDF2-HMAC-SHA256 at 600000 iterations (OWASP guidance). Each hash is stored aspbkdf2:<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
trustedProxyso 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
429withRetry-Afterand the body{ error, code: "SIGN_IN_LOCKED", retryAfter }; the signIn function throwsLoginLockedError. 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.
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
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.
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:
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.
Related
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.