@lenne.tech/nest-server 11.36.4 → 11.37.0

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

@@ -1,3 +1,4 @@
+import { createLocalAccountIssuer } from '@better-auth/core/db';
 import { ForbiddenException, Injectable, Logger, OnApplicationBootstrap } from '@nestjs/common';
 import { InjectConnection } from '@nestjs/mongoose';
 import { isEmail } from 'class-validator';
@@ -239,6 +240,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);
     }
 
@@ -250,11 +272,32 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
       const normalizedPassword = this.userMapper.normalizePasswordForIam(input.password);
 
       // Create user via internalAdapter (bypasses disableSignUp)
-      const iamUser = await context.internalAdapter.createUser({
-        email: input.email,
-        emailVerified: true,
-        name: input.name || input.email.split('@')[0],
-      });
+      //
+      // better-auth >= 1.7 requires a provisioning source. Without it, `createUser` throws
+      // FORBIDDEN/validation_source_missing as soon as a project configures
+      // `betterAuth.options.user.validateUserInfo`. `admin` is the honest value — the system
+      // provisions the FIRST admin, nobody signs up — and it is what better-auth's own admin
+      // plugin passes.
+      //
+      // This does NOT bypass `validateUserInfo`. The hook still runs and receives
+      // `{ method: 'admin', action: 'create-user' }`, so a project gate can still reject the
+      // initial admin; branch on `method` there if the setup should be exempt.
+      //
+      // KNOWN LIMITATION, and the reason this is spelled out: when `validateUserInfo` is
+      // configured, better-auth additionally calls `getCurrentAuthContext()`, which throws outside
+      // an endpoint context. System setup runs from `OnApplicationBootstrap` / a plain controller,
+      // never inside better-auth's request pipeline, so the call fails with
+      // FORBIDDEN/validation_context_missing and no initial admin is created. Fail-closed, but
+      // opaque. A project using that hook must provision the first admin another way — see
+      // migration-guides/11.36.x-to-11.37.0.md §7.
+      const iamUser = await context.internalAdapter.createUser(
+        {
+          email: input.email,
+          emailVerified: true,
+          name: input.name || input.email.split('@')[0],
+        },
+        { method: 'admin' },
+      );
 
       if (!iamUser) {
         throw new Error('Failed to create IAM user');
@@ -262,8 +305,14 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
 
       // Hash password and create credential account
       const hashedPassword = await context.password.hash(normalizedPassword);
+      // better-auth >= 1.7 keys accounts by (issuer, accountId) and requires the
+      // issuer. Credential accounts have no real issuer, so better-auth derives a
+      // synthetic one — always via this helper, never a hand-written literal:
+      // the format is better-auth's to change, and a copy of it would silently
+      // stop matching the accounts better-auth writes itself.
       await context.internalAdapter.linkAccount({
         accountId: iamUser.id,
+        issuer: createLocalAccountIssuer('credential'),
         password: hashedPassword,
         providerId: 'credential',
         userId: iamUser.id,