# 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 Rush](https://cloud.getrush.ai/run/add-password-reset/adonisjs/). Opens 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`

```json
{
  "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.

## 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

- [Add Rate Limiting to an AdonisJS API](https://getrush.ai/run/add-rate-limiting/adonisjs/)
- [Add Request ID Logging to an AdonisJS App](https://getrush.ai/run/add-request-id-logging/adonisjs/)
- [Add Database Seeders to an AdonisJS API](https://getrush.ai/run/add-seed-data/adonisjs/)

## The same job on other stacks

- [Add a Password Reset API to a Django REST Framework Project](https://getrush.ai/run/add-password-reset/django-rest-framework/)
- [Add Password Reset to a Fastify API](https://getrush.ai/run/add-password-reset/fastify/)
- [Add Password Reset to a Filament Admin Panel](https://getrush.ai/run/add-password-reset/filament/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
