Skip to main content
theAuth’s built-in password auth is username-based: users register with a username (not an email address) and a password. Passwords are hashed with PBKDF2 before storage so a database breach does not expose credentials. It is a headless module, you mount it yourself by forwarding requests to theauth.username.handleRequest.
There is no separate email-based password plugin. For email-first sign-in, pair this module with the email verification module and email OTP, or use magic link for a fully passwordless flow.

Setup

lib/theauth.ts
Forward matching requests to the module from your framework adapter (or call it directly from a catch-all route):
Mount the handler
handleRequest matches the literal pathnames below (/auth/username/sign-up and so on) and only for POST. If you mount it under a prefix such as /api/theauth, strip the prefix from the URL before calling it. theauth.username is null unless the username key is passed and auth.session is configured.

Sign up

POST /auth/username/sign-up
Sign up (client)
Sign-up throws (returned as a 400 with a plain-text error message, not a machine-readable code) when the username fails validation or is already taken, or when the password fails length validation.

Sign in

POST /auth/username/sign-in
Sign in (client)

Change password

POST /auth/username/change-password Requires the caller to know the current password. The module does not read the session for you, pass the authenticated userId from your own session lookup.
The HTTP handler takes userId from the request body and does not check the caller’s session. Do not expose change-password or change-username to browsers as-is. Resolve the session on your server and call theauth.username.changePassword(userId, current, newPassword) and theauth.username.changeUsername(userId, newUsername) instead.
Change password (client)

Change username

POST /auth/username/change-username
Change username (client)
Usernames must still be unique after the change, sign-up validation rules (allowedPattern, length) apply here too.

Using the module directly

theauth.username exposes typed methods in addition to handleRequest, useful when you want to call sign-up/sign-in from server code (e.g. an admin invite flow) instead of going through HTTP:

Configuration reference

number
default:3
Minimum username length.
number
default:32
Maximum username length.
RegExp
default:"/^[a-zA-Z0-9_-]+$/"
Regex the username must match.
boolean
default:"false"
Whether usernames are normalized to lowercase before storage and lookup.
number
default:8
Minimum password length.
number
default:128
Maximum password length.

Magic link

Passwordless, email-based alternative when you don’t want a password field at all.

Two-factor auth

Add TOTP as a second factor on top of username/password sign-in.

Authentication overview

All available auth methods and how to combine them.

Sessions

What happens after sign-in: cookie and JWT session management.
Last modified on October 8, 2026