@lenne.tech/nest-server 11.36.4 → 11.36.5

package/docs/REQUEST-LIFECYCLE.md

@@ -620,6 +620,30 @@ async updateUser(...): Promise<User> { ... }
 async getPublicUsers(): Promise<User[]> { ... }
 ```
 
+**Public does not mean anonymous (since 11.36.5).** On a public endpoint (`S_EVERYONE`, or no
+`@Roles` at all) `RolesGuard` still tries to IDENTIFY the caller before granting access —
+Better-Auth first, Passport JWT second, every failure swallowed. Access is granted either way: a
+missing, expired or malformed token can never turn a public endpoint into a 401. The effect is that
+`@CurrentUser()`, `serviceOptions.currentUser` and `securityCheck(user)` see a signed-in caller, so
+a public endpoint can personalise — a search ranking by the caller's own location, a list marking
+the caller's own entries.
+
+Before 11.36.5 the guard returned early and `request.user` stayed unset. That mattered **only in
+legacy-JWT deployments**: with Better-Auth enabled, `CoreBetterAuthMiddleware` is applied via
+`forRoutes('(.*)')` and had already set `request.user` before any guard ran. `BetterAuthRolesGuard`
+keeps its early return for exactly that reason — it only runs when Better-Auth is enabled, where the
+middleware has already done the work.
+
+Two consequences worth knowing when you own a public endpoint:
+
+- **Owner-restricted output widens for its owner.** `@Restricted(S_SELF)` / `@Restricted(S_CREATOR)`
+  fields evaluate against `currentUser`; with `undefined` they always stripped. They now appear for
+  the caller who owns the record. That is the declared policy finally being applied, not a leak —
+  but it may be the first time anyone sees those fields on that route.
+- **An anonymous caller stays ABSENT, not falsy.** Passport answers `false` for "no credentials";
+  the guard normalises that away so `@CurrentUser()` yields `undefined` as before. Pinned by
+  `tests/public-endpoint-identity.e2e-spec.ts`.
+
 **Important:** `@Roles()` already handles JWT authentication internally. Do NOT add `@UseGuards(AuthGuard(JWT))` — it is redundant.
 
 #### System Roles (S_ prefix)
@@ -634,7 +658,7 @@ When `X-Tenant-Id` header is present and a system role grants access, membership
 
 | System Role | Check Logic | Use Case |
 |-------------|-------------|----------|
-| `S_EVERYONE` | Always true | Public endpoints |
+| `S_EVERYONE` | Always true — access granted unconditionally; the caller is still identified when a valid token is present (see above) | Public endpoints |
 | `S_NO_ONE` | Always false | Permanently locked |
 | `S_USER` | `currentUser` exists | Any authenticated user |
 | `S_VERIFIED` | `user.verified \|\| user.verifiedAt \|\| user.emailVerified` | Email-verified users |

package/migration-guides/11.32.x-to-11.33.x.md

@@ -10,7 +10,7 @@
 | **Bugfixes** | Migration lock gained heartbeat + stale-break + bounded wait; `runOnInit` cron dedup no longer keyed on each replica's boot clock and no longer crashes the process on a failed startup run; BullMQ worker no longer swallows a tick delivered during bootstrap; rate limiters degrade instead of 500-ing on a Redis outage; Hub buffer mirror failures no longer recurse through the Logger they buffer; the email-verification cooldown timer can no longer expire a later cooldown early; a presigned S3 download no longer serves the file under a different name than the streamed one (§14) |
 | **Under the hood (§14)** | Two new MongoDB collections (`s3-files`, `filesystem-files` — include them in backups), new public exports, a bucket-less `s3` block is now ignored, NestJS 11.1.28 → 11.1.29, plus two dependency MAJORS: `js-sha256` 0.12.0 → 1.0.0 (**digests unchanged — no password-hash break**) and `graphql-query-complexity` 1.1.1 → 2.0.0 |
 | **Dependency Housekeeping** | The framework's own `pnpm audit` went from 20 findings to 0. Those are `pnpm-workspace.yaml` overrides, which **do not reach npm consumers** — run your own audit (§13) |
-| **Migration Effort** | **Start with §A and §B — they are the only changes that can break a single-replica project, and they break it silently** (no crash, just 401/403 on `/files/**` and `/tus`). Then **§11a / §11b if your config already contains a `redis` or an `s3` key** — the framework reads both now, and an existing `s3` key makes the boot FAIL until you act. Everything else is opt-in: read §1 if you call or override the rate limiters, §2 if you override Hub services, §4 before your next multi-replica deploy, §10 if you copied the avatar upload from `src/server`, **§11c if you rate-limit behind a reverse proxy** (a boot warning will tell you), §13 for what the security overrides do and do not do for you |
+| **Migration Effort** | **Start with §A and §B — they are the only changes that can break a single-replica project, and they break it silently** (no crash, just 401/403 on `/files/**` and `/tus`). Then **§11a / §11b if your config already contains a `redis` or an `s3` key** — the framework reads both now, and an existing `s3` key makes the boot FAIL until you act. Everything else is opt-in: read §1 if you call or override the rate limiters, §2 if you override Hub services, §4 before your next multi-replica deploy, §10 if you copied the avatar upload from `src/server`, **§11c if you rate-limit behind a reverse proxy** (a boot warning will tell you), §13 for what the security overrides do and do not do for you, and **§5 if any test suite of yours resets the database to replay system setup** — emptying `users` is no longer enough |
 
 Most of this release exists to make one deployment shape possible: **more than one replica**. Nothing there is required to keep running on one.
 
@@ -547,9 +547,42 @@ creating, an instance now claims the setup by upserting `{ _id: 'initial-admin'
 `system-setup-locks` collection — an atomic operation exactly one instance wins. The others log a
 debug line and skip. If creation then fails, the marker is removed so a later boot can retry.
 
-**Action: none.** The unique email index already prevented duplicate *users*; this removes the noisy
-failures and the ambiguity about which replica actually did the setup. A new collection
-`system-setup-locks` appears in the database with a single small document.
+**Action: none in production.** The unique email index already prevented duplicate *users*; this
+removes the noisy failures and the ambiguity about which replica actually did the setup. A new
+collection `system-setup-locks` appears in the database with a single small document.
+
+**Action (test suites only): if you reset the database to replay system setup.** The marker is
+removed only when creation FAILS. After a SUCCESSFUL setup it stays, which is what you want for a
+deployment: setup must never run twice. But it also means that emptying `users` no longer restores
+the fresh-install state, because `createInitialAdmin()` now guards on two conditions, not one. The
+second `POST /system-setup/init` is then refused until the claim goes stale — **five minutes after
+the claim was taken, i.e. after the successful setup, not five minutes after the refusal.** That is
+why the symptom looks intermittent and gets misfiled as flake: a suite resetting ten minutes after
+boot is not blocked at all, one resetting immediately is.
+
+Drop the collection wherever you drop `users`:
+
+```typescript
+// deleteMany, not drop: dropping `users` would drop its unique email index — the very
+// index that prevents a duplicate admin, credited above. deleteMany preserves indexes.
+for (const col of ['users', 'account', 'session', 'system-setup-locks']) {
+  await db.collection(col).deleteMany({});
+}
+```
+
+That is the framework's own reset, executed on every test run in
+`tests/stories/system-setup.e2e-spec.ts` — prefer reading it there over copying this snippet, since
+a spec that runs cannot drift. (The whole-database `dropDatabase()` elsewhere in `tests/` is a
+different job: per-run teardown, not a mid-run reset.)
+
+Both refusals raise the same `LTNS_0050`. **Up to 11.36.4** its message read *"System setup not
+available - users already exist"*, so a suite hitting the claim was told the users were the problem
+while the users collection was empty. **From 11.36.5** the message names both conditions and the
+server logs a warning naming `system-setup-locks`, the release-on-failure semantics and the stale
+window. If setup fails right after a reset, check this collection before anything else.
+
+Note that `GET /system-setup/status` does **not** help here: `needsSetup` is computed from the user
+count alone, so it reports `true` while init is refused by the claim.
 
 ---
 

package/migration-guides/11.36.4-to-11.36.5.md

@@ -0,0 +1,184 @@
+# Migration Guide: 11.36.4 → 11.36.5
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None that removes or renames anything. **One behaviour change** on the legacy-JWT path: a signed-in caller is now identified on public endpoints (§2). One **consumer-visible string**: the `LTNS_0050` message and both its translations (§1) |
+| **New Features** | None |
+| **Bugfixes** | A signed-in caller lost their identity on a public endpoint in legacy-JWT deployments (§2). `LTNS_0050` described only one of the two guards that raise it, so a caller that had just emptied `users` was told users already exist while the collection was empty (§1) |
+| **Migration Effort** | **None for most projects.** `pnpm update`. Read **§2 if you run legacy JWT auth WITHOUT Better-Auth and have public endpoints** — that is the only behaviour change here. Read §1 if you assert on the 403 body of `POST /system-setup/init`, or if a test suite of yours resets the database to replay system setup |
+
+---
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server@11.36.5
+```
+
+---
+
+## 1. `LTNS_0050` now names both of the conditions that raise it
+
+**Were you affected?** Only if you assert on the exact message text of a 403 from
+`POST /system-setup/init`, or if you reset the database in tests to replay the setup flow.
+
+### What changed
+
+`createInitialAdmin()` refuses under **two** different conditions, and both raise
+`ErrorCode.SYSTEM_SETUP_NOT_AVAILABLE` / `LTNS_0050`:
+
+1. Users already exist.
+2. The initial-admin setup is **claimed** — the marker `{ _id: 'initial-admin' }` in
+   `system-setup-locks` is held.
+
+Up to 11.36.4 the message described only the first:
+
+```diff
+- System setup not available - users already exist
++ System setup not available - users already exist, or the initial-admin setup is claimed
+```
+
+Both translations (`de`, `en`) moved with it, as did the `@ApiResponse` description on the
+controller and the sample response in the module README.
+
+**The code is unchanged.** It is still `LTNS_0050`, still HTTP 403. If you branch on the error
+**code** — which is what the framework asks you to do — nothing breaks. Only an assertion on the
+literal message string does.
+
+### Why this was worth a release
+
+The second guard is reachable in an ordinary situation that looks nothing like it: the marker is
+released **only when creation fails**, so it outlives a SUCCESSFUL setup by design. Emptying `users`
+to replay the flow therefore leaves setup refused — and the response said *"users already exist"*
+while `users` was empty. That is a message pointing away from the cause, in a flow that runs once per
+deployment and is rarely instrumented. It cost a consumer project a full CI cycle to find.
+
+Since 11.36.5 the claim path also logs a warning naming the collection, the release-on-failure
+semantics and the stale window, so the server log answers the question even when the response body is
+all you kept.
+
+### If you reset the database in tests
+
+Emptying `users` is not enough. Drop the claim collection alongside it:
+
+```typescript
+// deleteMany, not drop: dropping `users` would drop its unique email index,
+// which is what prevents a duplicate admin.
+for (const col of ['users', 'account', 'session', 'system-setup-locks']) {
+  await db.collection(col).deleteMany({});
+}
+```
+
+That is the framework's own reset, executed on every test run in
+`tests/stories/system-setup.e2e-spec.ts`.
+
+Two things that will otherwise mislead you:
+
+- **`GET /system-setup/status` does not see the claim.** `needsSetup` is computed from the user
+  count alone, so it reports `true` while init is refused.
+- **The stale window is measured from when the claim was taken**, not from your reset — five minutes
+  after the successful setup. A suite resetting ten minutes after boot is not blocked at all, one
+  resetting immediately is. That is why the symptom looks intermittent and gets misfiled as flake.
+
+---
+
+## 2. A signed-in caller is now IDENTIFIED on a public endpoint
+
+**Were you affected?** Only if **both** are true: you run **legacy JWT auth without Better-Auth**,
+and you have endpoints carrying `@Roles(RoleEnum.S_EVERYONE)` (or no `@Roles` at all).
+
+**With Better-Auth enabled, nothing changes for you.** `CoreBetterAuthMiddleware` is applied via
+`forRoutes('(.*)')`, so it already ran on public routes and set `request.user` before any guard.
+`BetterAuthRolesGuard` is deliberately unchanged for that reason.
+
+### What changed
+
+`RolesGuard` returned `true` for a public endpoint **without ever looking at the token**, so
+`request.user` stayed unset and a signed-in caller arrived anonymous:
+
+```typescript
+@Get('search')
+@Roles(RoleEnum.S_EVERYONE)          // public — intended, anonymous visitors may search
+search(@CurrentUser() user) {
+  // `user` was ALWAYS undefined, even with a valid Bearer token on the request
+}
+```
+
+Since 11.36.5 the guard identifies first — Better-Auth, then Passport JWT — with **every** failure
+swallowed. A missing, expired or malformed token still means "anonymous": this can never turn a
+public endpoint into a 401. **Access control is untouched.** Only identification is restored.
+
+An anonymous caller still yields `undefined`, not a falsy-but-present value — worth stating because
+Passport itself answers `false`, and code written as `if ('user' in request)` would have noticed.
+
+### What to check before updating
+
+Nothing needs changing to keep working. This is a list of places where behaviour may legitimately
+widen, in order of how likely they are to surprise you:
+
+1. **`@Restricted(S_SELF)` / `@Restricted(S_CREATOR)` fields un-hide for their owner.** They
+   evaluate against `currentUser`; with `undefined` they always stripped. On a public endpoint
+   returning records the caller owns, those fields now appear in the response — for that caller
+   only. The decorator sanctions it, but if you treated "this route is public, therefore always
+   anonymous, therefore owner-only fields never appear" as a redaction boundary, that assumption
+   no longer holds. Audit public endpoints whose response models carry owner-restricted fields.
+2. **`checkRights()` starts receiving a user on these routes.** Both common shapes flip:
+   `if (!user) return data;` was a bypass on public routes and is now enforced; `if (!user) throw …`
+   refused and now passes.
+3. **Ownership stamping.** `CrudService` writes `createdBy: serviceOptions?.currentUser?.id`. A
+   public create called by a signed-in caller now records ownership where it previously wrote
+   `undefined` — which later unlocks `S_CREATOR`-restricted fields on that record.
+4. **`securityCheck(user)` on your models** now sees a real user on public endpoints, so a branch
+   you wrote as "the anonymous path" stops being the only one taken.
+
+Find the places worth looking at:
+
+```bash
+# public endpoints that branch on the absence of a user
+grep -rn "S_EVERYONE" src/server/ --include="*.ts" | grep -v ".spec.ts"
+grep -rn "if (!currentUser\|if (!user" src/server/ --include="*.ts" | grep -v ".spec.ts"
+```
+
+### If you relied on the old behaviour
+
+A public endpoint that must be anonymous for **everyone** should not read `currentUser` at all.
+If you built on "public implies anonymous", make it explicit — the guard no longer enforces it
+for you as a side effect.
+
+### Also reachable now: `/ai/mcp` in legacy-JWT deployments
+
+`POST /ai/mcp` is `@Roles(S_EVERYONE)` and self-authenticating. In a legacy-JWT deployment it
+previously answered 401 for everyone, because `req.user` was unset and no other resolution path
+applied. It now authenticates any holder of a valid legacy access token. This is not an elevation —
+the MCP server is still built per user, with the tool registry's role filter and the per-owner
+session binding intact — but a surface you may have considered unreachable is now live. If you do
+not want it, set `ai.mcp: false`.
+
+---
+
+## Compatibility Notes
+
+| Pattern | Status |
+|---------|--------|
+| Branching on `error.code === 'LTNS_0050'` | Unaffected — the code did not change |
+| Asserting the literal 403 message string | **Update the expected string** (§1) |
+| Displaying the translated message to users | Unaffected, but the text is longer and now mentions the claim |
+| Overriding `CoreSystemSetupService.createInitialAdmin()` | Unaffected — the guard order and the thrown exception are unchanged |
+| A test suite that resets only `users` | Was already broken since 11.33; now the message and the server log say so (§1) |
+| Legacy JWT + public endpoints reading `currentUser` | **Now receives a user** (§2) |
+| Better-Auth enabled (hybrid or IAM-only) | Unaffected by §2 — the middleware already identified the caller |
+| Public endpoint returning owner-restricted fields | Those fields now reach the owner (§2.1) — audit before shipping |
+
+---
+
+## Troubleshooting
+
+**`POST /system-setup/init` returns 403 and `users` is empty.**
+The claim is held. Check `db.getCollection('system-setup-locks').find()`. Either another instance is
+running the setup, or a previous successful setup left the marker. Drop the collection, or wait five
+minutes from when the claim was taken.
+
+**A test asserting the 403 message fails after the update.**
+Expected — see §1. Prefer asserting the error **code** (`LTNS_0050`), which is stable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.36.4",
+  "version": "11.36.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",

package/src/core/modules/ai/core-ai-mcp.controller.ts

@@ -18,9 +18,15 @@ import { CoreAiMcpService } from './services/core-ai-mcp.service';
  * Exposes the AI tool registry to external MCP clients. The request must carry a
  * valid Bearer token (or session); the handler resolves the user via
  * {@link CoreAiMcpController.resolveUser} (which reuses `req.user` and falls back to
- * verifying the Bearer token directly, since `@Roles(S_EVERYONE)` does not populate
- * `req.user`). The MCP session is bound to that user and only their permitted tools
- * are exposed/executed.
+ * verifying the Bearer token directly). Since 11.36.5 `@Roles(S_EVERYONE)` DOES populate
+ * `req.user` — the guard identifies without denying — so the fallback is now a second line
+ * of defence rather than the only path. One consequence worth knowing: in a legacy-JWT
+ * deployment this endpoint previously answered 401 for everyone, because `req.user` was
+ * unset and no other resolution path applied; it now authenticates any holder of a valid
+ * legacy access token. That is not an elevation — the server is still built per user with
+ * the registry's role filter and the per-owner session binding — but it is a surface that
+ * was effectively unreachable before. The MCP session is bound to that user and only their
+ * permitted tools are exposed/executed.
  *
  * `@Roles(S_EVERYONE)` lets the request reach the handler (the guard would
  * otherwise reject), and the handler performs the MCP-specific 401 with a

package/src/core/modules/auth/guards/roles.guard.ts

@@ -147,7 +147,14 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
 
     // If no roles required, or S_EVERYONE is set, allow access without authentication
     // This allows public endpoints (without @Roles decorator or with S_EVERYONE) to work
+    //
+    // Access is granted either way, but the caller is still IDENTIFIED when they sent a valid
+    // token: returning early here left `request.user` unset, so a signed-in user hitting a
+    // public endpoint arrived as anonymous. Endpoints that are public AND personalise for
+    // signed-in callers — a search ranking by the caller's own location, a list marking the
+    // caller's own entries — silently lost that personalisation, with no error anywhere.
     if (!roles || !roles.some((value) => !!value) || roles.includes(RoleEnum.S_EVERYONE)) {
+      await this.tryIdentifyOptionalUser(context);
       return true;
     }
 
@@ -339,6 +346,67 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
     return user;
   }
 
+  /**
+   * Identify the caller on a PUBLIC endpoint without ever denying access.
+   *
+   * Mirrors the authentication order of the protected path (Better-Auth first, Passport JWT
+   * second) but treats every failure as "anonymous" instead of raising: a missing, expired or
+   * malformed token must not turn a public endpoint into a 401. It only sets `request.user`,
+   * so `@CurrentUser()` and `serviceOptions.currentUser` see a signed-in caller again.
+   *
+   * ANONYMOUS MUST STAY ABSENT. Passport's verify callback answers `false` — not `undefined` —
+   * when a request carries no usable credentials, and `MixinAuthGuard` assigns that verbatim.
+   * Without the normalisation at the end, every anonymous request to a public route would come
+   * out of here with `request.user === false` where it previously had no `user` at all. That is
+   * invisible to `!!user` and to `user?.id`, and visible to a handler that types the parameter
+   * `User`, tests `'user' in request`, or forwards it into `serviceOptions.currentUser`. Pinned
+   * by the `userType` assertions in tests/public-endpoint-identity.e2e-spec.ts.
+   */
+  protected async tryIdentifyOptionalUser(context: ExecutionContext): Promise<void> {
+    try {
+      const request = this.getRequest(context);
+      if (!request || request.user) {
+        return;
+      }
+
+      this.resolveServices();
+
+      if (this.betterAuthService?.isEnabled()) {
+        const user = await this.verifyBetterAuthTokenFromContext(context);
+        if (user) {
+          request.user = user;
+          return;
+        }
+      }
+
+      const result = super.canActivate(context);
+      if (isObservable(result)) {
+        await firstValueFrom(result);
+      } else {
+        await result;
+      }
+    } catch (error) {
+      // Never denies — but "the caller sent no usable token" and "the strategy itself failed" are
+      // not the same thing, and a bare `catch {}` makes them indistinguishable. A rotated secret,
+      // an unreachable database inside `validate()`, or a throwing user lookup would degrade every
+      // PUBLIC endpoint to anonymous while protected ones 401 — a split brain with nothing in the
+      // log to explain it. `debug`, not `warn`: the ordinary case (no credentials, expired token)
+      // reaches here too and must not be noise.
+      this.logger.debug(
+        `Optional identification failed on a public endpoint: ${
+          error instanceof Error ? error.message : 'Unknown error'
+        }`,
+      );
+    } finally {
+      // `finally`, not the try body: the catch above swallows a throw from Passport, and that
+      // path can have assigned a falsy user before throwing.
+      const request = this.getRequest(context);
+      if (request && !request.user && 'user' in request) {
+        delete request.user;
+      }
+    }
+  }
+
   /**
    * Integrate request from GraphQL
    */

package/src/core/modules/error-code/error-codes.ts

@@ -468,12 +468,22 @@ export const LtnsErrors = {
   // System Setup Errors (LTNS_0050-LTNS_0059)
   // =====================================================
 
+  /**
+   * Raised by BOTH guards in `createInitialAdmin()`, which is why the message names both.
+   *
+   * The first guard refuses because users exist. The second refuses because the initial-admin
+   * claim in `system-setup-locks` is held — and that marker is removed only when creation FAILS,
+   * so it OUTLIVES a successful setup by design. A test suite that resets the database by
+   * emptying `users` therefore still hits the claim, and until 11.36.5 was told "users already
+   * exist" while the users collection was empty. That mismatch cost a consumer project a full CI
+   * cycle to diagnose, so the message now covers both conditions.
+   */
   SYSTEM_SETUP_NOT_AVAILABLE: {
     code: 'LTNS_0050',
-    message: 'System setup not available - users already exist',
+    message: 'System setup not available - users already exist, or the initial-admin setup is claimed',
     translations: {
-      de: 'System-Setup nicht verfügbar - es existieren bereits Benutzer.',
-      en: 'System setup not available - users already exist.',
+      de: 'System-Setup nicht verfügbar - es existieren bereits Benutzer, oder das Initial-Admin-Setup ist bereits beansprucht.',
+      en: 'System setup not available - users already exist, or the initial-admin setup is claimed.',
     },
   },
 

package/src/core/modules/system-setup/INTEGRATION-CHECKLIST.md

@@ -92,13 +92,14 @@ export class SystemSetupController extends CoreSystemSetupController {
 
 ## Common Mistakes
 
-| Mistake                                     | Symptom                          | Fix                                      |
-| ------------------------------------------- | -------------------------------- | ---------------------------------------- |
-| BetterAuth not enabled                      | 404 on endpoints or 403 on init  | Ensure `betterAuth` is configured        |
-| Calling init with existing users            | 403 "System setup not available" | Init only works on empty database        |
-| Password too short                          | 400 validation error             | Password must be at least 8 characters   |
-| Missing ENV password                        | Auto-creation silently skipped   | Set both `email` and `password` ENV vars |
-| `systemSetup: { enabled: false }` in config | 404 on endpoints                 | Remove the explicit disable              |
+| Mistake                                     | Symptom                          | Fix                                                                                                                                                                |
+| ------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| BetterAuth not enabled                      | 404 on endpoints or 403 on init  | Ensure `betterAuth` is configured                                                                                                                                  |
+| Calling init with existing users            | 403 "System setup not available" | Init requires an empty `users` collection                                                                                                                          |
+| Re-running init after a successful setup    | 403, even with an empty `users`  | The claim marker in `system-setup-locks` outlives a SUCCESSFUL setup (it is released only on failure) — drop that collection too, or wait 5 min for it to go stale |
+| Password too short                          | 400 validation error             | Password must be at least 8 characters                                                                                                                             |
+| Missing ENV password                        | Auto-creation silently skipped   | Set both `email` and `password` ENV vars                                                                                                                           |
+| `systemSetup: { enabled: false }` in config | 404 on endpoints                 | Remove the explicit disable                                                                                                                                        |
 
 ---
 

package/src/core/modules/system-setup/README.md

@@ -94,7 +94,7 @@ Creates the initial admin user. Only works when zero users exist.
 
 ```json
 {
-  "message": "LTNS_0050: System setup not available - users already exist"
+  "message": "LTNS_0050: System setup not available - users already exist, or the initial-admin setup is claimed"
 }
 ```
 
@@ -169,6 +169,9 @@ NEST_SERVER_CONFIG='{ "systemSetup": { "initialAdmin": { "email": "admin@example
   instance claims the setup by upserting the marker `{ _id: 'initial-admin' }` into the
   `system-setup-locks` collection — an atomic operation only one instance wins. The others log a
   debug message and skip. If creation fails, the marker is removed again so a later boot can retry.
+  After a SUCCESSFUL setup the marker REMAINS — setup must never run twice in a deployment. Test
+  suites that reset the database to replay the setup flow therefore have to drop `system-setup-locks`
+  alongside `users`; clearing only `users` leaves setup refused until the claim goes stale (5 min).
 
 ### Security Best Practices
 
@@ -181,7 +184,9 @@ NEST_SERVER_CONFIG='{ "systemSetup": { "initialAdmin": { "email": "admin@example
 
 ## Security
 
-1. **Zero-user guard** - Init only works when `countDocuments({}) === 0`
+1. **Zero-user guard** - Init requires `countDocuments({}) === 0`. Necessary but not sufficient:
+   the atomic claim below must also be winnable, so an empty `users` collection alone does not
+   re-open setup
 2. **Enabled by default** - Safe because endpoints are permanently locked once any user exists
 3. **Race condition protection** - MongoDB unique email index prevents duplicates; auto-creation on
    bootstrap is additionally claimed atomically via the `system-setup-locks` marker
@@ -226,13 +231,42 @@ if (needsSetup) {
 
 ### Init returns 403 "System setup not available"
 
-**Cause:** Users already exist in the database.
+**Two different guards raise this, and the response cannot tell you which.**
 
-**Solutions:**
+**Cause 1 - users already exist.** The ordinary case on a deployment that is already set up.
 
 1. Check `GET /system-setup/status` - `needsSetup` should be `true`
 2. If this is a fresh deployment, verify the database is empty
 
+**Cause 2 - the initial-admin setup is claimed.** The marker `{ _id: 'initial-admin' }` in
+`system-setup-locks` is held. Either another instance is running the setup right now, or a previous
+SUCCESSFUL setup left it behind: it is removed only when creation FAILS.
+
+This is the one that costs time, because the obvious checks all point the other way. `needsSetup` is
+computed from the **user count alone**, so it reports `true` while init is refused - step 1 above
+confirms a state that is not the problem, and step 2 confirms an empty database that is genuinely
+empty.
+
+1. Look at the server log. Since 11.36.5 the service logs a warning naming the collection, the
+   release-on-failure semantics and the stale window.
+2. Check the collection directly: `db.getCollection('system-setup-locks').find()`
+3. If you reset the database to replay the setup, drop `system-setup-locks` alongside `users` -
+   see **Resetting for tests** below. Otherwise wait for the claim to go stale (5 minutes after it
+   was taken).
+
+### Resetting for tests
+
+Emptying `users` is not enough - the claim outlives a successful setup. The framework's own reset,
+executed on every test run in `tests/stories/system-setup.e2e-spec.ts`:
+
+```typescript
+// deleteMany, not drop: dropping `users` would drop its unique email index,
+// which is what prevents a duplicate admin.
+for (const col of ['users', 'account', 'session', 'system-setup-locks']) {
+  await db.collection(col).deleteMany({});
+}
+```
+
 ### Init returns 403 "System setup requires BetterAuth"
 
 **Cause:** BetterAuth is not configured or not enabled.
@@ -265,11 +299,11 @@ if (needsSetup) {
 
 ## Error Codes
 
-| Code      | Key                                | Description                        |
-| --------- | ---------------------------------- | ---------------------------------- |
-| LTNS_0050 | `SYSTEM_SETUP_NOT_AVAILABLE`       | Users already exist, setup locked  |
-| LTNS_0051 | `SYSTEM_SETUP_DISABLED`            | System setup is disabled in config |
-| LTNS_0052 | `SYSTEM_SETUP_BETTERAUTH_REQUIRED` | BetterAuth must be enabled         |
+| Code      | Key                                | Description                                                |
+| --------- | ---------------------------------- | ---------------------------------------------------------- |
+| LTNS_0050 | `SYSTEM_SETUP_NOT_AVAILABLE`       | Users already exist, OR the initial-admin setup is claimed |
+| LTNS_0051 | `SYSTEM_SETUP_DISABLED`            | System setup is disabled in config                         |
+| LTNS_0052 | `SYSTEM_SETUP_BETTERAUTH_REQUIRED` | BetterAuth must be enabled                                 |
 
 ---
 

package/src/core/modules/system-setup/core-system-setup.controller.ts

@@ -60,7 +60,10 @@ export class CoreSystemSetupController {
     summary: 'Create initial admin',
   })
   @ApiResponse({ description: 'Initial admin created', status: 201 })
-  @ApiResponse({ description: 'System setup not available - users already exist', status: 403 })
+  @ApiResponse({
+    description: 'System setup not available - users already exist, or the initial-admin setup is claimed',
+    status: 403,
+  })
   @Post('init')
   @Roles(RoleEnum.S_EVERYONE)
   async createInitialAdmin(@Body() input: SystemSetupInitDto): Promise<SystemSetupInitResult> {

package/src/core/modules/system-setup/core-system-setup.service.ts

@@ -239,6 +239,27 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
     // racing a fresh deployment can no longer obtain an admin account ALONGSIDE the
     // configured one.
     if (!(await this.claimInitialAdminSetup())) {
+      // Say WHICH guard refused. This one and the user-count guard above share
+      // ErrorCode.SYSTEM_SETUP_NOT_AVAILABLE, and the response cannot tell them apart — so
+      // without this line a caller that just emptied `users` is told users exist while the
+      // collection is empty. That is a genuinely expensive thing to diagnose from the outside:
+      // the marker outlives a SUCCESSFUL setup (it is released only on failure), so the usual
+      // "reset the database" reflex does not clear it.
+      // `log`, not `warn`. Both entry points reach this line, and for one of them a refusal is
+      // the EXPECTED outcome: on a multi-replica fresh rollout every replica but one loses the
+      // claim race, so `warn` would fire N-1 times per normal deployment — each time immediately
+      // followed by onApplicationBootstrap's own INFO line calling the same event a normal skip.
+      // Two records with contradictory severity for one non-event trains operators to ignore the
+      // louder one. The HTTP caller is not left without a diagnosis: the message is unchanged and
+      // an operator investigating a 403 reads it at the default level.
+      this.logger.log(
+        `System setup refused: the initial-admin claim in "${SETUP_LOCK_COLLECTION}" is held. ` +
+          'Either another instance is running the setup right now, or a previous SUCCESSFUL setup ' +
+          'left the marker behind — it is removed only when creation FAILS. If you reset the ' +
+          `database to replay the setup, drop "${SETUP_LOCK_COLLECTION}" alongside "users"; ` +
+          `otherwise setup stays refused until the claim goes stale after ` +
+          `${INITIAL_ADMIN_CLAIM_STALE_AFTER_MS / 60_000} minutes.`,
+      );
       throw new ForbiddenException(ErrorCode.SYSTEM_SETUP_NOT_AVAILABLE);
     }