All jobs

Add Password Reset to an AdonisJS App

Yes. An agent adds forgot and reset password flows to your AdonisJS 7 app: signed expiring links, a mail class, Edge pages, Japa tests with a fake mailer, and a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the authentication the app already has before it adds a way around a lost password. In an app laid out like the hypermedia kit in adonisjs/starter-kits, package.json runs @adonisjs/core 7.5 with @adonisjs/auth 10, @adonisjs/lucid 22 on better-sqlite3, @adonisjs/session 8, @adonisjs/shield, VineJS 4, Edge and Alpine, with Japa 5 and @japa/plugin-adonisjs for tests and scripts for dev, test, lint and typecheck; its imports map already declares #mails/* though no mail package is installed. start/routes.ts has a guest group with signup and login on controllers.NewAccount and controllers.Session from the generated #generated/controllers, and an auth group with /dashboard and logout. app/validators/user.ts shares an email() rule (max 254) and a password() rule (8 to 32) between signupValidator, which adds unique and sameAs, and loginValidator. app/models/user.ts composes the generated UserSchema with withAuthFinder(hash), so a password assigned to the model is hashed on save and User.verifyCredentials checks it. config/auth.ts is a session guard with useRememberMeTokens: false; config/session.ts stores sessions in a cookie for 2h. The pages under resources/views/pages/auth use the kit's @form, @field.root, @input.control and @button components and the auth layout; partials/flash_alerts.edge shows flash messages. .env.example defines APP_URL and no mail keys, tests/bootstrap.ts configures unit, functional and browser suites, and .github/workflows/ci.yml runs lint and typecheck for each kit.

Mail and links come from the framework. The agent runs node ace add @adonisjs/mail --transports=smtp, which installs the package, registers its provider and commands in adonisrc.ts, writes config/mail.ts, and adds MAIL_MAILER, MAIL_FROM_ADDRESS, MAIL_FROM_NAME, SMTP_HOST and SMTP_PORT with their validations; those keys are added to .env.example too. node ace make:mail password_reset creates app/mails/password_reset.ts, a BaseMail whose prepare() sets to, subject and htmlView('emails/password_reset', { url }). The link is a signed URL rather than a token table: signedUrlFor('password_reset.edit', { id: user.id }, { expiresIn: '30 minutes', prefixUrl: env.get('APP_URL') }) from @adonisjs/core/services/url_builder, and the receiving route checks request.hasValidSignature(), which covers both the signature and the expiry. To keep a link from being reused inside its window, the agent adds a short fingerprint of the current password hash to the query; after a successful reset the hash changes and the old link no longer matches.

A PasswordReset controller gets four actions in the guest group: request renders pages/auth/forgot_password.edge; send validates the email with the shared email() rule, looks the user up, queues mail.sendLater(new PasswordResetNotification(user)) when one exists, and flashes the same message either way so the form does not reveal which addresses have accounts; edit renders pages/auth/reset_password.edge when hasValidSignature() and the fingerprint hold and otherwise flashes an expired-link message back to the request page; update validates password and passwordConfirmation with the existing rules, merges the new password so withAuthFinder hashes it, signs the user in with auth.use('web').login(user) and redirects to dashboard. The two pages reuse the kit's form components and the auth layout, login.edge gains a Forgot your password? link, and resources/views/emails/password_reset.edge holds the message.

Tests go in tests/functional/password_reset.spec.ts: with using fake = mail.fake() the first test posts an email, asserts fake.mails.assertSent(PasswordResetNotification, ({ message }) => message.hasTo(user.email)), takes the URL from the sent message, posts a new password to it and asserts User.verifyCredentials accepts the new one; the second test tampers with the signature and expects the expired-link flash; the third uses a link after a successful reset and expects the same. node ace test functional, npm run lint and npm run typecheck pass before the pull request opens.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add a forgot-password and reset-password flow to this AdonisJS 7 app. Read package.json, adonisrc.ts, .env.example, start/routes.ts, start/kernel.ts, start/env.ts, config/auth.ts, config/session.ts, app/models/user.ts, app/validators/user.ts, the controllers, the views under resources/views and tests/bootstrap.ts first. Run node ace add @adonisjs/mail --transports=smtp and add the new keys to .env.example. Create a PasswordReset controller with request, send, edit and update actions in the guest group: send validates the email with the shared rule, sends a mail class made with make:mail through mail.sendLater when the user exists, and flashes the same message either way; the link is a signedUrlFor of the edit route with expiresIn 30 minutes and prefixUrl from APP_URL plus a fingerprint of the current password hash; edit checks request.hasValidSignature and the fingerprint; update validates with the existing password rules, saves through the model so it is hashed, logs the user in and redirects to the dashboard. Add forgot_password and reset_password pages using the kit's form components and auth layout, a link on the login page, and an email view. Write functional Japa tests with mail.fake for the full flow, a tampered link and a reused link. Run node ace test functional, npm run lint and npm run typecheck, then open a pull request that quotes the test output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

The pull request changes package.json, the lockfile, adonisrc.ts, .env.example, start/env.ts, start/routes.ts and resources/views/pages/auth/login.edge, and adds config/mail.ts, app/controllers/password_reset_controller.ts, app/mails/password_reset.ts, app/validators/password_reset.ts, two pages under resources/views/pages/auth, one email view and tests/functional/password_reset.spec.ts. Its description quotes the three tests passing, shows the signed URL shape, and names the environment variables a deployment must set before the first email leaves.

A reviewer runs the app with a local SMTP catcher, requests a reset for an existing and a missing address and checks both show the same message, opens the link, sets a password and lands on the dashboard, then opens the same link again and reads the expired-link flash. They read send for the lookup and the queued mail, and read config/mail.ts to decide whether SMTP is the transport they want or whether to switch to one of the others the package lists.

mail.sendLater uses the in-memory queue the package provides, which is lost if the process exits; the description says so and names a persistent queue as the next step for production.

Run it on every Linear issue labelled auth

An automation on the Project with a linear trigger on linear.issue.labeled and the label auth starts one run per account feature, such as email verification or a password change page. The trigger adds the issue after the prompt and fills in no placeholder, so the prompt tells the agent to read the feature from the issue and to reuse the mail class pattern, the signed-URL helper and the shared validator rules this change introduces.

A team that starts projects from the same kit sends this body once per repository from its own server, each POST /o/{org}/sessions naming that repository in resources with a request_id that is a UUID v5 of the repository name, so a retried call returns the run already started. Each run reads its own routes and validators and places the flow beside the login it finds.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Password reset is small and security-sensitive at the same time: an enumeration leak in the form, a link that outlives its purpose, a mail sent synchronously from a request, a password saved unhashed. The agent builds the flow against the real app in its own sandbox, drives it end to end with the framework's fake mailer, and keeps the test output with the pull request so the reviewer starts from evidence.

A reviewer reads one controller, two pages and three tests. A team with several AdonisJS apps starts the same request across all of them at once.

Frequently asked questions

Why signed URLs instead of a tokens table?

The framework signs URLs with the app key and checks both signature and expiry in request.hasValidSignature(), so there is nothing to store or clean up. The fingerprint of the current password hash makes a link single-use within its window; a team that wants revocation lists or audit rows can add a table later.

Does the form reveal whether an email exists?

No. send flashes the same message whether or not a user was found, and only queues the mail when one was. The timing difference of a database lookup is the remaining signal, which the pull request mentions.

Which mail transport does it set up?

SMTP, through node ace add @adonisjs/mail --transports=smtp, with the host, port and sender in environment variables. config/mail.ts can switch to another transport the package supports without touching the controller or the mail class.

Is the email sent during the request?

It is queued with mail.sendLater, which the package backs with an in-memory queue by default. That keeps the response fast but loses queued mail on a restart, so the description points at a persistent queue for production.

How do the tests send mail?

They do not. mail.fake() captures every message, the tests assert on the captured mail class and recipient, and the reset link is read from the captured message to drive the rest of the flow.

More AdonisJS jobs

The same job on other stacks

Keep reading