# Add an Audit Log to a Mongoose and Express API

Yes. An agent adds an AuditLog model and a service that records who changed which user and what, wires it into the user and auth services, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-audit-log/mongoose/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads where writes happen before it records any, because an audit log that hooks the wrong layer either misses changes or logs the password hash. In an API laid out like hagopj13/node-express-boilerplate, `package.json` pins `mongoose` `^5.7.7`, `express` `^4.17.1`, `joi` `^17.3.0`, `passport` `^0.4.0` and `winston` `^3.2.1`, with `jest` `^26.0.1` and `supertest` `^6.0.1` for tests and `jest -i --colors --verbose --detectOpenHandles` as the `test` script. Every write to a user goes through `src/services/user.service.js`: `createUser` calls `User.create`, `updateUserById` does `Object.assign(user, updateBody)` then `user.save()`, and `deleteUserById` calls `user.remove()`. `src/services/auth.service.js` reuses `updateUserById` for `resetPassword` and `verifyEmail`, and `src/controllers/user.controller.js` wraps each call in `catchAsync` with `req.user` already set by `src/middlewares/auth.js`, which checks `manageUsers` and `getUsers` rights from `src/config/roles.js`. The services never see the request, so the actor has to be passed in.

The model mirrors the two that exist. `src/models/auditLog.model.js` defines `actor` as an `ObjectId` ref to `User` that may be null for self-service flows like password reset, `action` as an enum of `user.create`, `user.update`, `user.delete`, `auth.password_reset` and `auth.email_verified`, `target` as an `ObjectId` with a `targetModel` string, `changes` as a map of field name to `{ from, to }`, `ip` and `userAgent` as strings, and `timestamps: true` for the moment it happened. It applies the `toJSON` plugin from `src/models/plugins`, which already strips `_id`, `__v` and any path marked `private: true`, and the `paginate` plugin so an admin can page through entries the way `queryUsers` pages users. A compound index on `{ target: 1, createdAt: -1 }` serves the one query the log exists for. `src/models/index.js` exports it beside `User` and `Token`.

The recording goes into the service layer, not a Mongoose `post('save')` hook, because a hook cannot know who made the change. `src/services/audit.service.js` exposes `record({ actor, action, target, changes, request })` and never throws: a failed insert is logged through `src/config/logger.js` and the original write still succeeds, which the pull request states as a deliberate choice. `updateUserById` gains an optional `context` argument, computes `changes` from `user.modifiedPaths()` before `save()` with the previous values from `user.$__.activePaths` replaced by a plain snapshot taken with `user.toObject()` first, and records `password` as `{ from: '[redacted]', to: '[redacted]' }` so a hash never lands in the log. `createUser` and `deleteUserById` record the full document minus private paths. `user.controller.js` passes `{ actor: req.user, request: req }` on each call, and `auth.service.js` passes no actor on `resetPassword` and `verifyEmail` but names the action. A `GET /v1/users/:userId/audit` route behind `auth('manageUsers')` with a Joi validator in `src/validations/user.validation.js` returns the paginated entries.

Tests follow the shape of `tests/integration/user.test.js`, which uses `setupTestDB()` from `tests/utils/setupTestDB.js` to connect to `config.mongoose.url` and clear every collection before each test, and the `admin`, `userOne` and `insertUsers` fixtures with `adminAccessToken`. The new `tests/integration/audit.test.js` patches a user as admin and asserts one entry with `action` `user.update`, the admin's id as `actor` and a `changes.name` pair; patches the password and asserts the redacted pair; deletes a user and asserts the `user.delete` entry survives the deletion; and reads `/v1/users/:userId/audit` as `userOne` to assert `403`. A unit test in `tests/unit/services/audit.service.test.js` makes `AuditLog.create` reject and asserts `record` resolves anyway. The agent starts MongoDB in its sandbox with `MONGODB_URL` from `.env.example`, runs `yarn lint` and `yarn test` as `.travis.yml` does, and runs `yarn coverage` to show the new files are covered.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add an audit log to this Express and Mongoose API. Read package.json, src/app.js, src/models/user.model.js, src/models/token.model.js, src/models/plugins/toJSON.plugin.js, src/models/plugins/paginate.plugin.js, src/services/user.service.js, src/services/auth.service.js, src/controllers/user.controller.js, src/middlewares/auth.js, src/config/roles.js, src/routes/v1/user.route.js, src/validations/user.validation.js, tests/utils/setupTestDB.js, tests/fixtures/user.fixture.js and tests/integration/user.test.js first. Add an AuditLog model with actor, action, target, changes, ip and userAgent, using the toJSON and paginate plugins and an index on target and createdAt. Add an audit service whose record function never throws. Record create, update and delete in the user service with the actor passed from the controller, redact password values, and record password reset and email verification from the auth service. Add GET /v1/users/:userId/audit for manageUsers with a Joi validator. Write integration tests for each action and the 403, and a unit test for the failing insert. Start MongoDB, run lint, test and coverage, then open a pull request that says why recording happens in the service layer and why a failed audit insert does not fail the request.",
  "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

What comes back is a pull request that adds `src/models/auditLog.model.js`, `src/services/audit.service.js`, `tests/integration/audit.test.js` and `tests/unit/services/audit.service.test.js`, and changes `src/models/index.js`, `src/services/index.js`, `src/services/user.service.js`, `src/services/auth.service.js`, `src/controllers/user.controller.js`, `src/routes/v1/user.route.js` and `src/validations/user.validation.js`. The route's Swagger comment block follows the ones already in `user.route.js`, so `/v1/docs` shows the new endpoint. The description pastes the `jest --verbose` output with each new test's name and the coverage table rows for the two new files.

The run's record keeps the MongoDB start, the `yarn lint` and `yarn test` runs and the `yarn coverage` table, so a reviewer can tell a lint warning from a failing assertion without rerunning anything. Because `.travis.yml` is the only CI in this repository, the pull request also notes that no GitHub check runs on it and names the two commands a reviewer runs locally.

Before merging, a reviewer decides how long entries are kept, since the pull request adds no TTL index and says so, whether `ip` should honour `X-Forwarded-For` behind the team's proxy, and whether the audit route belongs under `manageUsers` or a new right in `src/config/roles.js`. The agent changes no existing validator and no response shape.

## Run it on every Mongoose service that changes user records

A team with several Express services on this boilerplate starts one run per repository from its own server: one `POST /o/{org}/sessions` each, with the 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. Each run reads its own `src/services`, so a service with more models than `User` gets `record` calls in each service that writes, and one that already has a `history` collection gets a pull request that extends it rather than a second log.

After that, an automation in the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` and the prompt "if this pull request adds a save, update, remove or deleteOne call on a model, check that the surrounding service records an audit entry with an actor, and say so in a comment" keeps new writes in the log. The trigger adds the pull request after the prompt and fires only for work by owners, members and collaborators.

## Why run it on Rush?

An audit log written without running the tests goes wrong in ways a reviewer only finds in production: a `post('save')` hook that records every change with no actor, a `changes` map that stores the bcrypt hash of a new password, or an insert failure that turns a successful user update into a 500. The agent runs the real suite against a real MongoDB in its sandbox, reads the real entries back through the new route, and shows the redacted password pair in the pull request before anyone merges.

Every command stays with the run, from `yarn lint` to the coverage table, and the pull request quotes them. The same change across a fleet of services built from one boilerplate costs no more attention than one, because each run has its own machine, its own record and its own pull request to review.

## Frequently asked questions

### Why not a Mongoose plugin with a post save hook?

Because the hook sees the document and nothing else: not the admin who made the change, not the request's address, and not whether the write came from a password reset or an admin edit. The services in this boilerplate are the one place every write passes through with that context one argument away, so recording there keeps the log complete and the models unchanged. A plugin stays an option for models the services never touch.

### What exactly is stored for a password change?

The entry says the `password` path changed and stores `[redacted]` for both sides, so a reader knows the event happened without the log holding a hash. The `pre('save')` hook in `user.model.js` hashes with bcrypt after the service runs, so the service would otherwise see the plaintext, which is a second reason to redact at the service rather than in the hook.

### Will a failing audit insert break my API?

No. `record` catches its own errors, logs them through the existing winston logger and resolves, so the user write that triggered it still returns its normal status. The unit test makes `AuditLog.create` reject to prove that path. A team that would rather fail closed changes one line, and the pull request names it.

### How do entries get cleaned up?

They do not, in this pull request. Retention is a policy decision, so the pull request leaves the collection unbounded and shows the one-line TTL index on `createdAt` to add once the team picks a period. The compound index on `target` and `createdAt` keeps the per-user query fast either way.

## More Mongoose jobs

- [Add Cursor Pagination to a Mongoose and Express API](https://getrush.ai/run/add-cursor-pagination/mongoose/)
- [Add Database Indexes to a Mongoose App](https://getrush.ai/run/add-database-indexes/mongoose/)
- [Add Database Migrations to a Mongoose App](https://getrush.ai/run/add-database-migrations/mongoose/)

## The same job on other stacks

- [Add an Audit Log to a Prisma Project](https://getrush.ai/run/add-audit-log/prisma/)
- [Add an Audit Log to a Quarkus API](https://getrush.ai/run/add-audit-log/quarkus/)
- [Add an Audit Log to a Sequelize and Express API](https://getrush.ai/run/add-audit-log/sequelize/)

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