Forgot password
8 files0 packages1 dependency
This pack adds password-recovery endpoints. A user who forgets their password requests a reset link by email through a public endpoint, then submits a new password with the token carried in that link.
- The request endpoint returns the same response whether or not the email is registered, so it cannot be used to discover which addresses have accounts.
- Both the reset email and the request endpoint are throttled against abuse.
- A branded, MJML reset-password email that links to your frontend with the token.
Depends on Auth
This pack extends the auth pack's User model and reuses its transactional email setup. Apply the auth pack first.
Apply the forgot password 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=forgot-password --agent=claude
$ npx @adonisplus/flow apply --pack=forgot-password --agent=codex
$ npx @adonisplus/flow apply --pack=forgot-password --agent=cursor
$ npx @adonisplus/flow apply --pack=forgot-password --agent=opencode
After applying, Flow will make the following changes to your app.
- Land the backend as shipped, from the password-reset table and the User mixin through the validators, the controller, the reset mailer and email template.
- Add the request and reset endpoints to your public API group.
- Run the tests, then drive the endpoints 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 API starter kit with the auth pack in place.
Migrations
xxxx_create_password_reset_tokens.tsdatabase/migrations/xxxx_create_password_reset_tokens.tsCreates thepassword_reset_tokenstable.created
Model
user.tsapp/models/user.tsAdds thewithManagedPassword()mixin.edited
Validators
user.tsapp/validators/user.tsAdds the forgot-password and reset-password validators.edited
Controllers & responses
password_resets_controller.tsapp/controllers/password_resets_controller.tsRequests a reset link and sets the new password, each answering204.created
Mailers & email templates
password_reset_provision.tsapp/mails/password_reset_provision.tsThe reset-password message, linking to your frontend with the token.createdreset_password.edgeresources/views/emails/reset_password.edgeBody of the reset-password message.created
Routes
routes.tsstart/routes.tsAdds the request and token endpoints to your public/api/v1group.edited
Tests
forgot_password.spec.tstests/functional/auth/forgot_password.spec.tsKnown-email, unknown-email, valid-token, and invalid-token specs.created
Configuration
Section titled "Configuration"The reset link is minted by the withManagedPassword() mixin on the User model, the mixin this pack adds beside auth's withManagedEmail(). It creates each reset token, hashes it, and stores it in a database table. Pass an options object to the mixin to change its defaults.
expiresInstring | number1 day.tablestringpassword_reset_tokens.tokenSecretLengthnumber40.export default class User extends compose(
UserSchema,
withAuthFinder(hash),
withManagedEmail(),
withManagedPassword({ expiresIn: '1 hour' })
) {}A request answers the same way for every email
Section titled "A request answers the same way for every email"The request action looks the user up but answers the same whether or not an account exists, so the flow cannot be used to discover which addresses are registered. The reset email is sent only when the account exists, and minting a token is throttled to one send a minute per address, so a burst of requests still delivers at most one message. The request route sits behind the formsThrottle limiter, which rate-limits the endpoint itself.
A reset link works once, then expires
Section titled "A reset link works once, then expires"Setting a new password verifies the token and updates the password in one step, then clears the account's remaining reset tokens, so any other outstanding link stops working. A link that is invalid or past its expiry is rejected and the password stays unchanged. Change how long a link stays valid with the mixin's expiresIn option above.
A new password follows the signup rules
Section titled "A new password follows the signup rules"The reset validator reuses the password() helper of the auth pack, so a new password must meet the same rules as a signup password. These rules include the password policy and the leaked-password check, when your app uses them.
Added in Flow 0.2.0.