What the agent does
The agent starts from the login path, because a lockout is a state machine attached to it. In a project like hagopj13/node-express-boilerplate, src/services/auth.service.js looks the user up by email in loginUserWithEmailAndPassword, compares the password with the isPasswordMatch method on src/models/user.model.js, and throws ApiError(httpStatus.UNAUTHORIZED, 'Incorrect email or password') for a missing user and a wrong password alike. The user schema has name, email, password, role and isEmailVerified, hashes the password in a pre('save') hook, and uses a toJSON plugin that strips any path marked private. The only brute-force defence is src/middlewares/rateLimiter.js, an express-rate-limit of 20 failed requests per 15 minutes per IP, mounted on /v1/auth in production only, which does nothing against one password tried from many addresses. mongoose is on 5.x, tests run with Jest 26 and supertest against a real MongoDB named by MONGODB_URL, and yarn.lock says yarn.
It adds two fields to the schema, failedLoginAttempts as a number with a default of 0 and lockUntil as a date, both private: true so the toJSON plugin keeps them out of every response the way it already hides password. Two settings join src/config/config.js, where every variable goes through a Joi schema: LOGIN_MAX_ATTEMPTS defaulting to 5 and LOGIN_LOCK_MINUTES defaulting to 15, with matching lines in .env.example. The model gets two methods, isLocked, true while lockUntil is in the future, and registerFailedLogin, which increments the counter with one updateOne using $inc so two parallel attempts cannot lose an increment, and sets lockUntil and resets the counter when the limit is reached.
loginUserWithEmailAndPassword then checks the lock before the password. A locked account answers 423 Locked with the number of minutes left, so a real user learns what happened; a wrong password on an unlocked account registers the failure and answers the existing 401; a correct password clears failedLoginAttempts and lockUntil in one update. The agent keeps the 401 message identical for an unknown email and a wrong password, and says in the pull request that 423 is only reachable after the limit on an account that exists, so it reveals nothing a patient attacker would not already have learned.
The tests go in tests/integration/auth.test.js beside the existing POST /v1/auth/login cases, using insertUsers from tests/fixtures/user.fixture.js and the setupTestDB helper that clears collections between tests: five wrong passwords then the right one gets 423, the stored document shows a lockUntil, moving lockUntil into the past with User.updateOne makes the next correct login a 200 and resets the counter, and no response body ever contains the two new fields. A unit test under tests/unit/models covers the counter arithmetic. The sandbox has no MongoDB and no Docker, so the agent installs Docker (sudo apt-get install -y docker.io, then starts dockerd), brings up the mongodb service from the repository's docker-compose.yml with docker-compose, which that package carries where the docker compose plugin is not, points MONGODB_URL at it, and runs yarn test, yarn lint and yarn prettier before opening the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add account lockout after repeated failed logins to this Express and Mongoose app. Read package.json, src/index.js, src/app.js, src/config/config.js, src/models/user.model.js, src/models/plugins/toJSON.plugin.js, src/services/auth.service.js, src/controllers/auth.controller.js, src/validations/auth.validation.js, src/middlewares/rateLimiter.js, src/middlewares/error.js, src/utils/ApiError.js, tests/utils/setupTestDB.js, tests/fixtures/user.fixture.js and the login section of tests/integration/auth.test.js first. Add failedLoginAttempts and lockUntil to the user schema as private fields so toJSON hides them. Add LOGIN_MAX_ATTEMPTS defaulting to 5 and LOGIN_LOCK_MINUTES defaulting to 15 to the Joi config schema and .env.example. In the login service, answer 423 with the minutes left while an account is locked, count a wrong password with an atomic $inc and lock when the limit is reached, and clear both fields on a correct login. Keep the 401 message the same for an unknown email and a wrong password. Add integration tests for the lock, the expiry and the hidden fields, and a unit test for the counter. MongoDB is not running here and Docker is not installed: install docker.io, start dockerd, bring up the mongodb service from docker-compose.yml with docker-compose, set MONGODB_URL, and run yarn test, yarn lint and yarn prettier, then open a pull request.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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
What comes back is a pull request that changes src/models/user.model.js, src/services/auth.service.js, src/config/config.js and .env.example, and adds tests under tests/integration and tests/unit. The description walks the state machine in four lines, wrong password, limit reached, locked attempt, expiry, with the status and body for each, and states the two defaults and the variables that change them.
The run's record holds the MongoDB start, the full jest -i output with the new cases listed, the ESLint and Prettier runs, and a curl session against the running app that hits the lock, so the 423 in the description is one that was observed.
Before merging, a reviewer decides whether a locked account should answer 423 or the same 401 as a wrong password, whether an admin route to clear a lock is needed, and whether a successful password reset through the existing resetPassword service should also clear the lock, which the agent leaves out and flags as a choice. The controllers, routes and validations are unchanged.
Run it on every login endpoint without a lockout
A team with several services on this boilerplate starts one run per repository from its own server: one POST /o/{org}/sessions each, with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started instead of a second pull request. Each run reads that service's own user model and login service and fits the fields and checks to them.
After the lock exists, an automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize and the prompt "if this pull request adds a route that verifies a password, check that it registers failures and honours lockUntil the way the login service does, and comment if it does not" keeps a new password-checking path from bypassing the lock. The trigger puts the pull request after the prompt; only work by an owner, member or collaborator fires it, never a fork's.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A lockout that is wrong fails quietly in one of two directions: a counter that two concurrent requests can race past, so the limit is really six or seven, or a lock that is checked after the password compare, so a locked account still leaks whether a guess was right. The agent writes the update as one atomic $inc, checks the lock first, and proves both with tests that run against a real MongoDB in its own sandbox rather than a mocked model.
The sandbox keeps the database start, the Jest output and the curl session with the run, and the pull request cites them. A team can start the same job on each service that shares this login code, each on its own machine with its own record, and review one state machine per pull request.
Frequently asked questions
Why is this needed when the auth routes already have a rate limiter?
The limiter in src/middlewares/rateLimiter.js counts failed requests per client address and only in production. One account attacked from many addresses never trips it, and the test and development environments have no protection at all. The lock lives on the account, so the number of addresses makes no difference.
Why answer 423 instead of the usual 401?
So a real user whose account was locked by someone else's guesses learns to wait rather than to keep retrying the right password, and so a client can show the minutes left. The cost is that 423 confirms the account exists, which an attacker who reached the limit already knew. A reviewer who prefers a uniform 401 changes one status in the service; the counting and the tests stay.
Why update with $inc rather than load, add one and save?
Two wrong passwords arriving together would each load a count of 3 and each save 4, and the limit becomes a suggestion. A single updateOne with $inc lets MongoDB do the arithmetic, so the fifth failure is the fifth whichever order the requests land in. The unit test sends parallel failures and checks the stored count.
Do the new fields show up in API responses?
No. The schema marks them private: true, which the repository's own toJSON plugin already uses to remove password from every serialised user. The integration test asserts the login and register responses carry neither field.
More Mongoose jobs
The same job on other stacks
More jobs like this: Hand off a long task
- Add actionlint to CI for Your GitHub Actions Workflows (GitHub Actions)