@lenne.tech/nest-server 11.41.4 → 11.41.5

package/docs/security-overrides.md

@@ -17,14 +17,15 @@ The framework pulls in three transitive packages that its `@nestjs/*` dependenci
 | Package | Advisory | Why it cannot resolve forward on its own |
 |---------|----------|------------------------------------------|
 | `ws` | [GHSA-96hv-2xvq-fx4p](https://github.com/advisories/GHSA-96hv-2xvq-fx4p) — high: memory-exhaustion DoS + uninitialized memory disclosure. Patched `>=8.21.0` | Older `@nestjs/graphql` releases declare `"ws": "8.20.1"` — an **exact pin**, not a caret. 13.4.5, the version this framework declares, pins `8.21.3` |
-| `js-yaml` | [GHSA-pm4m-ph32-ghv5](https://github.com/advisories/GHSA-pm4m-ph32-ghv5) — high: exponential parsing time in flow collections (DoS). Patched `>=5.2.2` | Older `@nestjs/swagger` releases declare `"js-yaml": "5.2.1"` — an **exact pin**, the same shape as the `ws` case. 11.4.7, the version this framework declares, pins `5.3.0` |
+| `js-yaml` | [GHSA-pm4m-ph32-ghv5](https://github.com/advisories/GHSA-pm4m-ph32-ghv5) — high: exponential parsing time in flow collections (DoS), patched `>=5.2.2`; [GHSA-r3ph-w7gj-g6xm](https://github.com/advisories/GHSA-r3ph-w7gj-g6xm) — moderate: `maxTotalMergeKeys` does not bound CPU use for empty merge sources, covers `<=5.4.0`, patched `>=5.4.1` (published 2026-09-29) | `@nestjs/swagger` declares js-yaml as an **exact pin**, the same shape as the `ws` case: older releases `5.2.1`, 11.4.7 — the version this framework declares, and the newest 11.x — `5.3.0`. No swagger update reaches the fix, so **this entry is load-bearing again** |
 | `multer` | [GHSA-wc9g-mqfw-jrwm](https://github.com/advisories/GHSA-wc9g-mqfw-jrwm), [GHSA-535w-7cp7-47q4](https://github.com/advisories/GHSA-535w-7cp7-47q4), [GHSA-qfvm-cv95-jqjf](https://github.com/advisories/GHSA-qfvm-cv95-jqjf) — high: DoS via crafted multipart input; [GHSA-qvfw-j98x-7q72](https://github.com/advisories/GHSA-qvfw-j98x-7q72) — low: file size limit bypass. Patched `>=2.3.0` | `@nestjs/platform-express` up to 11.2.5 declares `"multer": "2.2.0"` — an **exact pin**. A direct `multer` dependency does not move it: you get both copies, and FileInterceptor uses the vulnerable one. 11.2.6, the version this framework declares since 11.41.4, pins `2.4.0` |
 
-**Status since 11.41.4:** with the `@nestjs/*` versions this framework declares, all three resolve to
-a patched version on their own. The entries below are insurance for a project whose own
-`package.json` pins an older `@nestjs/graphql`, `@nestjs/swagger` or `@nestjs/platform-express` —
-duplicates of those are exactly how an old exact pin comes back. Keep them; they cost nothing while
-inert, and keep the `multer` target in lockstep (now `2.4.0`).
+**Status since 11.41.5:** `ws` and `multer` resolve to a patched version on their own with the
+`@nestjs/*` versions this framework declares; their entries below are insurance for a project whose
+own `package.json` pins an older `@nestjs/graphql` or `@nestjs/platform-express`. **`js-yaml` does
+not**: GHSA-r3ph-w7gj-g6xm covers the `5.3.0` that `@nestjs/swagger` 11.4.7 pins, so without the
+entry your `pnpm audit` reports it. Its key and target were raised in 11.41.5 — an entry copied
+before that (`<5.2.2`) no longer reaches swagger's pin.
 
 `@nestjs/graphql` is a plain `dependencies` entry, so `ws` is installed even when you run with
 `graphQl: false`. `@nestjs/swagger` and `@nestjs/platform-express` are likewise plain `dependencies`
@@ -43,10 +44,11 @@ overrides:
   # Remove once @nestjs/graphql stops pinning it.
   'ws@>=8.0.0 <8.21.0': '8.21.3'
 
-  # Older @nestjs/swagger releases exact-pin js-yaml@5.2.1 (GHSA-pm4m-ph32-ghv5, high, patched >=5.2.2).
-  # Same shape as the ws entry: an exact pin cannot resolve forward.
-  # Remove once @nestjs/swagger stops pinning it.
-  'js-yaml@>=5.0.0 <5.2.2': '5.2.2'
+  # @nestjs/swagger exact-pins js-yaml (11.4.7: 5.3.0) — GHSA-r3ph-w7gj-g6xm (moderate, patched >=5.4.1)
+  # and, for older swagger releases, GHSA-pm4m-ph32-ghv5 (high, patched >=5.2.2).
+  # Same shape as the ws entry: an exact pin cannot resolve forward. LOAD-BEARING since 11.41.5.
+  # Remove once @nestjs/swagger pins >=5.4.1 itself.
+  'js-yaml@>=5.0.0 <5.4.2': '5.4.2'
 
   # @nestjs/platform-express <=11.2.5 exact-pins multer@2.2.0 (GHSA-wc9g-mqfw-jrwm and three more, patched >=2.3.0).
   # Keep the target in LOCKSTEP with the multer version @lenne.tech/nest-server declares (2.4.0 since 11.41.4).

package/migration-guides/11.41.4-to-11.41.5.md

@@ -0,0 +1,144 @@
+# Migration Guide: 11.41.4 → 11.41.5
+
+## Overview
+
+| Category              | Details                                                                                                          |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **Breaking Changes**  | None in the package                                                                                              |
+| **Bugfix**            | `migrate down` now holds the migration lock, like `migrate up` already did                                       |
+| **Template change**   | nest-server-starter's `docker-entrypoint.sh` now aborts the start when a migration RAN AND FAILED (§2)           |
+| **New option**        | `MIGRATIONS_ALLOW_FAILURE=true` — start anyway for one deploy (starter and this repo's entrypoint)               |
+| **Dependencies**      | nodemailer 9 → 10 (security; the only break is Node >= 20), js-yaml override now needed in your project (§3)     |
+| **Migration Effort**  | Raise two overrides in your `pnpm-workspace.yaml` (§3); decide once whether to adopt the strict entrypoint (§2)  |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+pnpm run update            # starter-based projects: aligns the framework's ecosystem (see §3)
+pnpm run build && pnpm test
+```
+
+Vendor-mode projects pick up `migration-runner.ts` through the core update.
+
+## What's New in 11.41.5
+
+### 1. `migrate down` holds the migration lock
+
+Since 11.33.0, `migrate up` (`MigrationRunner.up()`) runs under the lock of the state store's lock
+collection — `migrations_lock` by default for stores built by `createMigrationStore()` — so replicas
+booting together serialize instead of each applying the same pending migration. `migrate down`
+did not. A rollback is typically run while a deploy is failing, i.e. exactly while replicas restart
+and each boots into `migrate up`; outside the lock the two read and rewrote the migration state
+concurrently. `MigrationRunner.down()` now takes the same lock. `migrate list` only reads and stays
+unlocked.
+
+Nothing to do: projects using `createMigrationStore()` get it automatically. A store built with an
+empty lock collection name (`createMigrationStore(uri, 'migrations', '')`) still runs unlocked, as
+before.
+
+### 2. The starter's entrypoint aborts on a migration that ran and failed
+
+This concerns `docker-entrypoint.sh` in **nest-server-starter** (and therefore in projects created
+from it), not the npm package. Until now the starter's entrypoint logged a failed migration and
+started the server anyway. A failed schema migration is then indistinguishable from a good deploy
+on every level anyone watches — health check 200, the right commit on `/meta`, drift detection
+green, `turbo deploy --wait` converging — over an app that works against the empty collections
+Mongoose created at boot while the data still sits under the old names.
+
+| Situation | Before | Now |
+| --------- | ------ | --- |
+| A migration ran and threw | warning, server starts | **start aborted** (exit 1); the container runtime retries |
+| `MIGRATIONS_ALLOW_FAILURE=true` | — | warning, server starts — a deliberate exception for ONE deploy |
+| `MIGRATE_FAILURE_POLICY=warn` / `abort` | `warn` was the default | still honoured; wins over `MIGRATIONS_ALLOW_FAILURE` |
+| Unknown value in either variable | fell back to `warn` | falls back to `abort`, with a warning |
+| A recorded migration whose FILE is gone | warning, server starts | unchanged: warning, server starts |
+| No migrations bundled / no CLI in the image | skipped | unchanged: skipped |
+
+The last-but-one row is deliberate: migrations that ran everywhere may simply be deleted once a new
+instance no longer needs them (git history restores them). The migrate CLI reports such a file as a
+warning, and the entrypoint passes no `--strict`. A project that wants the opposite sets
+`NSC__MIGRATE__STRICT=true` explicitly — that stays available, it is just not the default.
+
+**What to do in an existing project:** your `docker-entrypoint.sh` is your own file, so nothing
+changes until you adopt the new one. To adopt it, copy `docker-entrypoint.sh` from
+nest-server-starter 11.41.5. If a deploy must go out with a migration known to fail, set
+`MIGRATIONS_ALLOW_FAILURE=true` for that deploy and unset it again once the migration is fixed.
+
+This repository's own `docker-entrypoint.sh` already defaulted to `abort`; it gained the
+`MIGRATIONS_ALLOW_FAILURE` alias.
+
+### 3. Dependency updates
+
+| Package | 11.41.4 | 11.41.5 |
+| ------- | ------- | ------- |
+| `nodemailer` | 9.1.1 | **10.0.13** |
+| `mongoose` | 9.10.2 | 9.10.3 |
+| `@modelcontextprotocol/sdk` | 1.30.1 | 1.31.0 |
+| dev: `@swc/core`, `@types/multer`, `@types/node`, `oxfmt`, `oxlint` | 1.16.2, 2.2.0, 26.6.2, 0.70.0, 1.85.0 | 1.16.12, 2.3.0, 26.6.3, 0.71.0, 1.86.0 |
+
+**nodemailer 10 is a major, and it ships in a patch on purpose.** Five advisories cover 9.1.1 — two
+of them high (GHSA-v53p-9fqp-m79j, GHSA-prgh-xp8r-p3m5), three moderate — and they are fixed only in
+10.x; there is no 9.x backport. The single breaking change of 10.0.0 is "Node.js 20 or newer is
+required", and this package already requires Node >= 22.12. 10.x is a TypeScript rewrite that ships
+its own declarations; `@types/nodemailer` is no longer read. Only one thing changes for code that
+uses nodemailer's types directly:
+
+```typescript
+import type * as SMTPTransport from 'nodemailer/lib/smtp-transport';
+
+let transport: SMTPTransport;          // before: the namespace WAS the class
+let transport: SMTPTransport.default;  // nodemailer 10: the class is the default export
+let options: SMTPTransport.Options;    // unchanged
+```
+
+`MailTransportOptions` in `IServerOptions` was adjusted the same way; a project that only passes a
+plain options object (`email.smtp`) is unaffected.
+
+**What to do:**
+
+1. Starter-based projects: `pnpm run update` raises `mongoose` and the dev tooling to the versions above.
+2. Two overrides `pnpm run update` does NOT touch — edit `overrides:` in your `pnpm-workspace.yaml`:
+
+   ```yaml
+   # The lockstep entry from nest-server-starter. Left at 9.1.1 it forces the framework's
+   # nodemailer back DOWN to 9.1.1 — and keeps all five advisories.
+   nodemailer: 10.0.13
+
+   # @nestjs/swagger 11.4.7 (the newest 11.x) exact-pins js-yaml 5.3.0, covered by
+   # GHSA-r3ph-w7gj-g6xm (moderate, patched >=5.4.1). Replaces an older `<5.2.2` entry, which no
+   # longer reaches that pin. Background: docs/security-overrides.md.
+   'js-yaml@>=5.0.0 <5.4.2': '5.4.2'
+   ```
+
+3. Run `pnpm install` and `pnpm audit` — both advisories must be gone.
+
+Overrides in this repository never reach your project (pnpm applies them only to the root of an
+install), which is why the js-yaml entry has to be repeated there.
+
+## Compatibility Notes
+
+| Pattern | Status |
+| ------- | ------ |
+| `createMigrationStore(uri)` / `createMigrationStore(uri, 'migrations')` | Lock active for `up` and now `down` |
+| A custom `MongoStateStore` without `lockCollectionName` | Unchanged: runs unlocked |
+| `NSC__MIGRATE__STRICT=true` | Unchanged: a missing recorded migration file fails the run |
+| A `nodemailer: 9.1.1` override (starter-derived projects) | Pins nodemailer 9.1.1 under the framework — raise it to `10.0.13` (§3) |
+| Code typing `import * as X from 'nodemailer/lib/…'` as `X` | Use `X.default` (§3) |
+| Your own `docker-entrypoint.sh` | Unchanged until you adopt the starter's (§2) |
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| ------- | ----- | --- |
+| Container restarts in a loop, log: `refusing to start against a possibly half-applied schema` | A migration ran and failed (new entrypoint) | Fix the migration; for one deploy, `MIGRATIONS_ALLOW_FAILURE=true` |
+| `migrate down` waits with `Waiting for migration lock release …` | Another replica is running `migrate up` | Wait; a lock whose holder died is broken after 60 s without heartbeat |
+| `Strict mode: N recorded migration file(s) missing` | `NSC__MIGRATE__STRICT=true` and a migration file was deleted | Restore the file from git, or unset `NSC__MIGRATE__STRICT` |
+| `pnpm audit` still reports nodemailer advisories after the update | A `nodemailer: 9.1.1` override pins the old version | Raise it to `10.0.13` |
+| `pnpm audit` reports GHSA-r3ph-w7gj-g6xm (js-yaml) | No (or an old `<5.2.2`) js-yaml override | Add `'js-yaml@>=5.0.0 <5.4.2': '5.4.2'` |
+| `TS2709` / `Cannot use namespace 'SMTPTransport' as a type` | nodemailer 10 types | Use `SMTPTransport.default` |
+
+## Module Documentation
+
+- [Migrate module README](../src/core/modules/migrate/README.md) — locking, strict mode, CLI
+- nest-server-starter `README.md` → Environment — `MIGRATE_FAILURE_POLICY` / `MIGRATIONS_ALLOW_FAILURE`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.41.4",
+  "version": "11.41.5",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -25,12 +25,13 @@
     "cf": "pnpm run check:fix",
     "check": "node scripts/check.mjs",
     "check:consumer": "node scripts/check-consumer.mjs",
-    "check:fix": "pnpm install && pnpm run spectaql:sync && pnpm audit --fix && pnpm run check:overrides && pnpm peers check && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
+    "check:fix": "pnpm install && pnpm run spectaql:sync && pnpm audit --fix && pnpm run check:overrides && pnpm peers check && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && pnpm run check:server-start",
     "check:manifest": "node scripts/check-package-manifest.mjs",
     "check:mutations": "node scripts/check-mutations.mjs",
-    "check:naf": "pnpm install && pnpm run spectaql:sync && pnpm run check:overrides && pnpm peers check && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
+    "check:naf": "pnpm install && pnpm run spectaql:sync && pnpm run check:overrides && pnpm peers check && pnpm run format && pnpm run lint:fix && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && pnpm run check:server-start",
     "check:overrides": "node scripts/check-overrides.mjs",
-    "check:raw": "pnpm install --frozen-lockfile && pnpm run spectaql:sync && pnpm audit && pnpm run check:overrides && pnpm peers check && pnpm run format:check && pnpm run lint && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && bash scripts/check-server-start.sh",
+    "check:raw": "pnpm install --frozen-lockfile && pnpm run spectaql:sync && pnpm audit && pnpm run check:overrides && pnpm peers check && pnpm run format:check && pnpm run lint && pnpm run typecheck:tests && pnpm run check:swc-tdz && pnpm test && pnpm run build && pnpm run check:manifest && pnpm run check:server-start",
+    "check:server-start": "cross-env NODE_ENV=local node scripts/check-server-start.mjs --entry=dist/main.js --port-env=NSC__PORT --ready=\"Server starte[dt] at\" --path=/",
     "check:swc-tdz": "nest build -b swc -p tsconfig.swc-tdz.json && node scripts/check-swc-tdz.mjs",
     "cnaf": "pnpm run check:naf",
     "docs": "pnpm run docs:ci && open http://127.0.0.1:8080/ && open ./public/index.html && compodoc -p tsconfig.json -s ",
@@ -92,7 +93,7 @@
     "@apollo/server": "5.5.1",
     "@as-integrations/express5": "1.1.2",
     "@getbrevo/brevo": "6.0.3",
-    "@modelcontextprotocol/sdk": "1.30.1",
+    "@modelcontextprotocol/sdk": "1.31.0",
     "@nestjs/apollo": "13.4.5",
     "@nestjs/common": "11.2.6",
     "@nestjs/core": "11.2.6",
@@ -126,10 +127,10 @@
     "json-to-graphql-query": "2.3.0",
     "lodash": "4.18.1",
     "mongodb": "7.6.0",
-    "mongoose": "9.10.2",
+    "mongoose": "9.10.3",
     "multer": "2.4.0",
     "node-mailjet": "6.0.11",
-    "nodemailer": "9.1.1",
+    "nodemailer": "10.0.13",
     "passport": "0.7.0",
     "passport-jwt": "4.0.1",
     "reflect-metadata": "0.2.2",
@@ -177,8 +178,8 @@
     }
   },
   "devDependencies": {
-    "@aws-sdk/client-s3": "3.1140.0",
-    "@aws-sdk/s3-request-presigner": "3.1140.0",
+    "@aws-sdk/client-s3": "3.1143.0",
+    "@aws-sdk/s3-request-presigner": "3.1143.0",
     "@better-auth/core": "1.7.1",
     "@better-auth/passkey": "1.7.1",
     "@compodoc/compodoc": "2.0.0",
@@ -186,21 +187,21 @@
     "@nestjs/schematics": "11.1.0",
     "@nestjs/testing": "11.2.6",
     "@swc/cli": "0.8.1",
-    "@swc/core": "1.16.2",
+    "@swc/core": "1.16.12",
     "@tus/s3-store": "2.0.7",
     "@types/compression": "1.8.1",
     "@types/cookie-parser": "1.4.10",
     "@types/ejs": "3.1.5",
     "@types/express": "5.0.6",
     "@types/lodash": "4.17.25",
-    "@types/multer": "2.2.0",
-    "@types/node": "26.6.2",
+    "@types/multer": "2.3.0",
+    "@types/node": "26.6.3",
     "@types/nodemailer": "8.0.2",
     "@types/passport": "1.0.17",
     "@vitest/coverage-v8": "4.1.11",
     "ansi-colors": "4.1.3",
     "better-auth": "1.7.1",
-    "bullmq": "6.3.8",
+    "bullmq": "6.3.10",
     "cross-env": "10.1.0",
     "find-file-up": "2.0.1",
     "husky": "9.1.7",
@@ -208,8 +209,8 @@
     "nodemon": "3.1.14",
     "npm-watch": "0.13.0",
     "otpauth": "9.5.2",
-    "oxfmt": "0.70.0",
-    "oxlint": "1.85.0",
+    "oxfmt": "0.71.0",
+    "oxlint": "1.86.0",
     "rimraf": "6.1.3",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",

package/src/core/common/interfaces/server-options.interface.ts

@@ -37,19 +37,25 @@ export type BetterAuthFieldType = 'boolean' | 'date' | 'json' | 'number' | 'numb
  * particularly useful in CI / e2e tests: `{ jsonTransport: true }` serializes
  * outgoing mail to a JSON string and returns a valid response without any
  * network I/O — no SMTP server, no credentials, no flakiness.
+ *
+ * The `X.default` members are the transport INSTANCE types. nodemailer >= 10 ships its own
+ * declarations, where each `nodemailer/lib/<transport>` module is `export default class` plus a
+ * module-level `Options` alias, so `import type * as X` yields a module namespace — the class is
+ * `X.default`. (`@types/nodemailer` used `export =` with a merged namespace, where `X` itself
+ * was the class.)
  */
 export type MailTransportOptions =
-  | JSONTransport
+  | JSONTransport.default
   | JSONTransport.Options
-  | SendmailTransport
+  | SendmailTransport.default
   | SendmailTransport.Options
-  | SESTransport
+  | SESTransport.default
   | SESTransport.Options
-  | SMTPPool
+  | SMTPPool.default
   | SMTPPool.Options
-  | SMTPTransport
+  | SMTPTransport.default
   | SMTPTransport.Options
-  | StreamTransport
+  | StreamTransport.default
   | StreamTransport.Options
   | string;
 

package/src/core/modules/migrate/README.md

@@ -240,9 +240,12 @@ How the lock works, regardless of which entry point uses it:
 
 This ensures that in a cluster with multiple nodes, migrations run on only one machine at a time.
 
-**Active by default for `migrate up`.** Stores built by `createMigrationStore()` use the
-lock collection `migrations_lock` unless another name is given, and `MigrationRunner.up()`
-(the CLI's `up` command) acquires that lock around the whole run. This matters because the
+**Active by default for `migrate up` and `migrate down`.** Stores built by `createMigrationStore()` use the
+lock collection `migrations_lock` unless another name is given, and `MigrationRunner.up()` / `.down()`
+(the CLI's `up` / `down` commands) acquire that lock around the whole run. `down` joined later (DEV-2728): a
+rollback is typically run while a deploy is failing, i.e. while replicas restart and each boots into
+`migrate up` — outside the lock the two rewrote the migration state concurrently. `migrate list` only
+reads and stays unlocked. This matters because the
 container entrypoint runs migrations on **every** boot: without the lock, N replicas
 starting together each read the same empty state and apply the same pending migration N
 times. A replica that waited re-reads the state inside the lock and finds nothing pending.
@@ -530,10 +533,15 @@ Enable it via any of:
 | `NSC__MIGRATE__STRICT=1\|true\|yes` env var  | CLI **and** programmatic runners (resolved in the `MigrationRunner` constructor) |
 | `new MigrationRunner({ strict: true, ... })` | programmatic                                                                     |
 
-**Recommended for production images:** set `NSC__MIGRATE__STRICT=true` in the container
-environment. In an immutable image, a recorded-but-missing migration file can only mean a
-broken build (empty/miscopied `migrations/` directory) or a state-store mismatch (wrong
-database) — both are conditions where refusing to boot is correct.
+**Off by default, on only when a project explicitly wants it.** Deleting migration files that
+ran everywhere is a normal practice — a new instance never needs them, and git history restores
+them if ever needed — and under strict mode every such deletion would refuse the boot. Turn it on
+for images that must carry the FULL migration history. Where the history is complete by
+design, a recorded-but-missing file can only mean a broken build (empty/miscopied
+`migrations/` directory) or a state-store mismatch (wrong database), and refusing to boot is
+correct. This is independent of the entrypoint's failure policy: a migration that RAN AND
+FAILED aborts the container start by default (`MIGRATIONS_ALLOW_FAILURE=true` opts out per
+deploy), whatever `strict` says.
 
 ### Programmatic usage (MigrationRunner)
 

package/src/core/modules/migrate/migration-runner.ts

@@ -297,8 +297,17 @@ export class MigrationRunner {
 
   /**
    * Rollback the last migration (down)
+   *
+   * Serialized through the same lock as `up()`. A rollback is typically run while a deploy
+   * is failing, i.e. exactly while replicas restart and each boots into `migrate up`; outside
+   * the lock the two would read and rewrite the migration state concurrently, and one of them
+   * would save a state that no longer matches the database.
    */
   async down(): Promise<void> {
+    await withMigrationLock(this.options.stateStore, () => this.runDown());
+  }
+
+  protected async runDown(): Promise<void> {
     const { _endMigration, _startMigration } = await import('./helpers/migration.helper');
 
     const state = await this.options.stateStore.loadAsync();