Email and password
27 files4 packagesNo dependencies
This pack adds email and password authentication to your app. Users sign up, log in, and log out, and every new account confirms its email address before it is treated as active.
- Email verification for new signups, with a screen to resend the confirmation mail.
- Rate-limited login that penalises repeated failed attempts, and a throttled signup.
- Password and email rules that you choose, with a live strength meter on the signup screen.
- A branded, MJML-based confirmation email.
Apply the authentication pack with Flow. Start a new session in your selected coding agent and execute the following slash command inside it.
$ npx @adonisplus/flow apply --pack=auth --agent=claude
$ npx @adonisplus/flow apply --pack=auth --agent=codex
$ npx @adonisplus/flow apply --pack=auth --agent=cursor
$ npx @adonisplus/flow apply --pack=auth --agent=opencode
After applying, Flow will make the following changes to your app.
- Establish the foundation it needs, a session
webguard, theguestandauthmiddleware, and an authenticated landing route, wherever your app is missing one. - Land the backend as shipped, from the migrations and model mixin through the validators, controllers, routes, middleware, and mailer.
- Configure mail and the limiter to the choices you give it.
- Restyle the login, signup, activation, and verify-email screens to your design system.
- Run the tests, then walk the signup, verify, and login flow and show you the result.
Delta will differ
Flow adapts the pack to your app, so the exact set of created and edited files depends on what you already have. This is the shape of an apply onto the React starter kit.
Migrations
xxxx_add_unverified_email_to_users.tsdatabase/migrations/xxxx_add_unverified_email_to_users.tsAdds theunverified_emailcolumn to the users table.createdxxxx_create_email_verification_tokens.tsdatabase/migrations/xxxx_create_email_verification_tokens.tsCreates theemail_verification_tokenstable.created
Model
user.tsapp/models/user.tsAdds thewithManagedEmail()mixin.edited
Validators
user.tsapp/validators/user.tsAdds the login and signup validators.editedpassword_policy.tsapp/validators/password_policy.tsThe password policy, with the rules you chose.created
Controllers & responses
email_verifications_controller.tsapp/controllers/email_verifications_controller.tsServes the activation screen, resends the email, and consumes the verification token.createdsession_controller.tsapp/controllers/session_controller.tsAdds the rate-limited credential check and the post-login redirect.editednew_account_controller.tsapp/controllers/new_account_controller.tsPasses the password policy to the signup page, sets the unverified email, mints a token, and sends the activation email.editeduser_transformer.tsapp/transformers/user_transformer.tsExposesunverifiedEmailin the serialized user.edited
Middleware
verified_account_middleware.tsapp/middleware/verified_account_middleware.tsRedirects unverified accounts to the activation screen.created
Mailers & email templates
account_activation_provision.tsapp/mails/account_activation_provision.tsThe activation email, carrying the verification link.createdemail_layout.edgeresources/views/components/email_layout.edgeShared MJML layout for the emails.createdaccount_activation.edgeresources/views/emails/account_activation.edgeBody of the activation email.created
Password strength meter
password_strength.tsxinertia/components/password_strength.tsxWraps the password field and checks the password against the policy.createdpassword_meter.tsxinertia/components/password_meter.tsxThe strength bar and its label.createdpassword_requirements.tsxinertia/components/password_requirements.tsxThe checklist of the policy rules.created
Pages
activate.tsxinertia/pages/account/activate.tsxActivation screen with the resend action.createdverify_email.tsxinertia/pages/auth/verify_email.tsxVerify-email screen.createdlogin.tsxinertia/pages/auth/login.tsxAdds the email and password login form.editedsignup.tsxinertia/pages/auth/signup.tsxAdds the signup form with the confirmation field and the password strength meter.edited
Routes & config
routes.tsstart/routes.tsAdds the login, signup, logout, and verification routes.editedmail.tsconfig/mail.tsMail configuration, with thebrandNameglobal and thefromaddress.createdlimiter.tsstart/limiter.tsLimiter configuration, with theformsThrottledefinition.created
Factories & tests
user_factory.tsdatabase/factories/user_factory.tsUser factory with averifiedstate for the tests.createdlogin.spec.tstests/browser/auth/login.spec.tsLogin and logout specs.createdsignup.spec.tstests/browser/auth/signup.spec.tsSignup specs.createdemail_verification.spec.tstests/browser/auth/email_verification.spec.tsEmail verification specs.created
Configuration
Section titled "Configuration"Verification is backed by the withManagedEmail() mixin on the User model, which stores each token in a database table. Pass an options object to the mixin to change its defaults.
expiresInstring | number1 day.tablestringemail_verification_tokens.tokenSecretLengthnumber40.export default class User extends compose(
UserSchema,
withAuthFinder(hash),
withManagedEmail({ expiresIn: '2 hours' })
) {}Password policy
Section titled "Password policy"Flow asks which password and email rules you want before it writes the validators. It records the password rules as one policy in app/validators/password_policy.ts. The signup validator checks each new password against it, and each later screen that sets a password reuses it. The login validator checks only the format, so accounts made before the rules can still log in.
minLengthnumber8.maxLengthnumber32. Keep it generous, so passphrases and password managers are not cut off.minScorenumber0 to 4, estimated from its length and the variety of its characters. Defaults to 0, which turns the check off.lettersbooleanfalse.mixedCasebooleanfalse.numbersbooleanfalse.symbolsboolean!, #, or a space. Defaults to false.export const passwordPolicy = definePasswordPolicy({
minLength: 8,
maxLength: 32,
minScore: 3,
})Two more checks are rules on the validator. Both are off by default.
- The leaked-password check,
uncompromised(), rejects a password that appears in a known data leak. It asks the Have I Been Pwned service, and only the first five characters of the password hash leave the server. When the service cannot be reached, the password is accepted. - The disposable-email check,
nonDisposable(), rejects a signup email from a throwaway provider. It uses a list in the package and makes no outgoing request. Existing users with such an address can still log in.
const newEmail = () => email().nonDisposable()
const password = () => vine.string().passwordPolicy(passwordPolicy).uncompromised() Password strength meter
Section titled "Password strength meter"The signup screen shows a strength bar and a checklist of the policy rules under the password field. They update as the user types. NewAccountController passes the policy to the page, and PasswordStrength calls the same checkPassword function that the validator uses, so the screen and the server agree. The bar turns green only when every rule passes, not from the score alone. The leaked-password check runs only on the server.
Verification is two email columns, not a boolean
Section titled "Verification is two email columns, not a boolean"The mixin tracks verification with two columns:
emailis the confirmed address.unverifiedEmailis one still waiting on confirmation.
Signup writes the same value to both, so the two agree and the account reads as unverified. Confirming the address moves it into email and clears unverifiedEmail, so they diverge and the account reads as active. hasInactiveAccount exposes this state, and VerifiedAccountMiddleware gates on it.
Verification tokens
Section titled "Verification tokens"Tokens live in the email_verification_tokens table, one row per outstanding token, linked to the user by tokenable_id. The mixin generates a token when you ask for one and verifies it when the link comes back, storing only its hash so a leaked row cannot be turned back into a working link.
Resend throttling
Section titled "Resend throttling"Resending is throttled to one token a minute. Inside that window the endpoint does nothing and answers exactly as it would have, so the timing stays invisible to callers.
Rate-limited credentials
Section titled "Rate-limited credentials"Login runs the credential check through two limiter keys:
- one scoped per IP, and
- a stricter one per IP-and-email that adds a 20-minute block after five failures, which slows a targeted guess at a single account.
Both run through penalize, which spends the budget only when credentials fail, so a valid login is always free.
const ipKey = `login_${request.ip()}`
const emailKey = `login_${request.ip()}_${payload.email}`
const loginLimiter = limiter.multi([
{ duration: '1 min', requests: 10, key: ipKey },
{ duration: '1 min', requests: 5, blockDuration: '20 mins', key: emailKey },
])
const [error, user] = await loginLimiter.penalize(() => {
return User.verifyCredentials(payload.email, payload.password)
})Signup takes a simpler guard, formsThrottle, a named limiter capped at ten requests a minute per route and IP.
export const formsThrottle = limiter.define('forms', (ctx) => {
return limiter
.allowRequests(10)
.every('1 minute')
.usingKey(`${ctx.route?.name ?? 'global'}_${ctx.request.ip()}`)
})Added in Flow 0.2.0.