@lenne.tech/nest-server 12.3.2 → 12.4.0

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

@@ -3611,7 +3611,10 @@ export interface IServerOptions {
    *
    * Auto-creation via config/ENV (no REST call needed):
    * - `{ initialAdmin: { email: '...', password: '...' } }`
-   * - `NSC__systemSetup__initialAdmin__email` + `NSC__systemSetup__initialAdmin__password`
+   * - `NSC__SYSTEM_SETUP__INITIAL_ADMIN__EMAIL` + `NSC__SYSTEM_SETUP__INITIAL_ADMIN__PASSWORD`
+   *
+   * The anonymous `POST /system-setup/init` is open only in `local`, `ci` and `e2e` unless `httpInit` opens it
+   * (12.4.0+, see {@link ISystemSetup.httpInit}).
    *
    * @since 11.14.0
    *
@@ -4048,23 +4051,74 @@ export interface ISystemSetup {
    */
   enabled?: boolean;
 
+  /**
+   * Whether the anonymous `POST /system-setup/init` may create the first administrator.
+   *
+   * Fail-closed outside the local environments: whoever reaches an API without users through that route becomes its
+   * administrator, so a deployment provisions the first admin through {@link initialAdmin} and opens the HTTP route
+   * only on purpose.
+   *
+   * | Value | `local` / `ci` / `e2e` | every other environment (`develop`, `test`, `production`, …) |
+   * |-------|------------------------|---------------------------------------------------------------|
+   * | not set | open | **closed** (403 `LTNS_0053`) |
+   * | `true` | open | open, without a token |
+   * | `{ token: '<at least 16 characters>' }` | open, token required | open, token required |
+   * | `false` / `{ enabled: false, … }` | closed | closed |
+   *
+   * The token is sent in the `X-System-Setup-Token` header; a missing or wrong one answers 403 `LTNS_0054`. An object
+   * whose token is missing, empty, shorter than 16 characters or not a string keeps the route CLOSED and logs an
+   * error at boot — `{ token: process.env.SETUP_TOKEN }` with the variable unset must not open it. A value that is
+   * neither a boolean nor an object (the string `'true'` from `NEST_SERVER_CONFIG`) counts as not set.
+   *
+   * Environment variables: `NSC__SYSTEM_SETUP__HTTP_INIT=true`, or `NSC__SYSTEM_SETUP__HTTP_INIT__TOKEN=<secret>` (a
+   * token of digits only is converted to a number by the environment reader and refused; set one of the two, not
+   * both).
+   *
+   * `GET /system-setup/status` reports the result as `httpInitEnabled` / `httpInitTokenRequired`.
+   *
+   * @default undefined (open only in `local`, `ci` and `e2e`)
+   * @since 12.4.0
+   */
+  httpInit?: boolean | ISystemSetupHttpInit;
+
   /**
    * Pre-configured initial admin credentials for automatic creation on server start.
    *
    * When set, the service will automatically create the initial admin user
    * during application bootstrap if zero users exist. This is useful for
    * automated deployments (Docker, CI/CD) where no manual REST call is possible.
+   * It is not affected by {@link httpInit}.
    *
-   * Can be provided via environment variables:
-   * - `NSC__systemSetup__initialAdmin__email`
-   * - `NSC__systemSetup__initialAdmin__password`
-   * - `NSC__systemSetup__initialAdmin__name` (optional)
+   * Can be provided via environment variables (SCREAMING_SNAKE segments — a camelCase segment such as
+   * `NSC__systemSetup__…` is NOT read, the boot warns about it):
+   * - `NSC__SYSTEM_SETUP__INITIAL_ADMIN__EMAIL`
+   * - `NSC__SYSTEM_SETUP__INITIAL_ADMIN__PASSWORD`
+   * - `NSC__SYSTEM_SETUP__INITIAL_ADMIN__NAME` (optional)
    *
    * Security: Same zero-user guard applies - only works when no users exist.
    */
   initialAdmin?: ISystemSetupInitialAdmin;
 }
 
+/**
+ * Object form of {@link ISystemSetup.httpInit}: the HTTP init, protected by a setup token
+ *
+ * @since 12.4.0
+ */
+export interface ISystemSetupHttpInit {
+  /**
+   * `false` keeps the HTTP init closed while the token stays configured
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * The secret `POST /system-setup/init` must carry in the `X-System-Setup-Token` header. At least 16 characters;
+   * a missing, shorter or non-string value keeps the HTTP init closed.
+   */
+  token?: string;
+}
+
 /**
  * System setup configuration interface
  *

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

@@ -637,6 +637,33 @@ export const LtnsErrors = {
     },
   },
 
+  /**
+   * `POST /system-setup/init` is closed in this environment (12.4.0+): by default it is open only in `local`, `ci`
+   * and `e2e`. A deployment provisions its first admin through `systemSetup.initialAdmin`, or opens the HTTP init
+   * explicitly with `systemSetup.httpInit`.
+   */
+  SYSTEM_SETUP_HTTP_INIT_DISABLED: {
+    code: 'LTNS_0053',
+    message: 'Initial admin setup over HTTP is not enabled in this environment',
+    translations: {
+      de: 'Die Ersteinrichtung über die Oberfläche ist in dieser Umgebung nicht freigegeben.',
+      en: 'Initial admin setup over HTTP is not enabled in this environment.',
+    },
+  },
+
+  /**
+   * `POST /system-setup/init` requires the setup token (`systemSetup.httpInit.token`) in the `X-System-Setup-Token`
+   * header, and the request sent none or a different one (12.4.0+).
+   */
+  SYSTEM_SETUP_TOKEN_INVALID: {
+    code: 'LTNS_0054',
+    message: 'Missing or invalid system setup token',
+    translations: {
+      de: 'Der Einrichtungs-Token fehlt oder ist falsch.',
+      en: 'The system setup token is missing or invalid.',
+    },
+  },
+
   // =====================================================
   // AI Errors (LTNS_0600-LTNS_0699)
   // =====================================================

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

@@ -2,7 +2,9 @@
 
 **For initial admin creation on fresh deployments in projects using `@lenne.tech/nest-server`.**
 
-> **Note:** System setup is **enabled by default** when BetterAuth is active. No explicit configuration is needed for the REST endpoints to work.
+> **Note:** System setup is **enabled by default** when BetterAuth is active. Locally (`local`, `ci`, `e2e`) the REST
+> endpoints work without configuration. **In a deployed environment `POST /system-setup/init` is closed since 12.4.0**:
+> provision the first admin via ENV (Step 1), or open the HTTP init on purpose (Step 1b).
 
 ---
 
@@ -10,8 +12,9 @@
 
 | Scenario                                             | Action Needed                                   |
 | ---------------------------------------------------- | ----------------------------------------------- |
-| Fresh deployment needs initial admin creation        | None - endpoints are available by default       |
-| Automated deployment (Docker/CI) needs auto-creation | Set ENV variables (Step 1)                      |
+| Local development / e2e tests create the first admin | None - the HTTP init is open there by default   |
+| Deployed instance needs its first admin              | Set ENV variables (Step 1) - recommended        |
+| Deployed instance must be set up through the UI      | Open the HTTP init with a token (Step 1b)       |
 | Want to disable system setup                         | Set `systemSetup: { enabled: false }` in config |
 | Custom setup logic (extra fields, notifications)     | Step 2 (Custom Controller)                      |
 
@@ -35,12 +38,16 @@ https://github.com/lenneTech/nest-server/tree/develop/src/core/modules/system-se
 For automated deployments where no manual REST call is possible:
 
 ```bash
-# .env or Docker environment
-NSC__systemSetup__initialAdmin__email=admin@example.com
-NSC__systemSetup__initialAdmin__password=YourSecurePassword123!
-NSC__systemSetup__initialAdmin__name=Admin  # optional
+# .env or Docker environment — every segment in SCREAMING_SNAKE_CASE
+NSC__SYSTEM_SETUP__INITIAL_ADMIN__EMAIL=admin@example.com
+NSC__SYSTEM_SETUP__INITIAL_ADMIN__PASSWORD=YourSecurePassword123!
+NSC__SYSTEM_SETUP__INITIAL_ADMIN__NAME=Admin  # optional
 ```
 
+**WHY SCREAMING_SNAKE_CASE?** The environment reader lowercases every segment it does not split at `_`. The camelCase
+form `NSC__systemSetup__initialAdmin__email` (shown in this checklist until 12.4.0) is therefore never read, and no
+admin is created. Since 12.4.0 the boot warns about such a variable.
+
 Or in `config.env.ts`:
 
 ```typescript
@@ -58,6 +65,26 @@ The admin is created automatically on server start when zero users exist.
 
 ---
 
+## Step 1b: Open the HTTP init on a deployed instance (Optional, 12.4.0+)
+
+Only when the first admin must be created through the UI on a deployed stage:
+
+```bash
+NSC__SYSTEM_SETUP__HTTP_INIT__TOKEN=<secret of at least 16 characters>   # recommended
+# or, without a token (whoever reaches the API first becomes admin):
+NSC__SYSTEM_SETUP__HTTP_INIT=true
+```
+
+The frontend sends the token in the `X-System-Setup-Token` header; `GET /system-setup/status` tells it with
+`httpInitEnabled` / `httpInitTokenRequired` whether to show the form and a token field.
+
+**WHY closed by default?** The init is anonymous. On a deployment without `initialAdmin` it made whoever called it
+first the administrator, until the first sign-up.
+
+Remove the setting once the admin exists — the init is locked from then on anyway.
+
+---
+
 ## Step 2: Custom Controller (Optional)
 
 Only needed if you want to add extra validation, logging, or custom fields.
@@ -76,6 +103,9 @@ export class SystemSetupController extends CoreSystemSetupController {
 ```
 
 > **Note:** The SystemSetup module auto-registers its controller via CoreModule. To use a custom controller, you would need to disable auto-registration and register your own module.
+>
+> **An override of `createInitialAdmin()` must call `this.systemSetupService.assertHttpInitAllowed(token)` first**
+> (the token from the `x-system-setup-token` header), or it opens the anonymous init in every environment.
 
 ---
 
@@ -84,7 +114,9 @@ export class SystemSetupController extends CoreSystemSetupController {
 - [ ] `npm run build` succeeds
 - [ ] `npm test` passes
 - [ ] `GET /system-setup/status` returns `{ needsSetup: true }` on empty database
-- [ ] `POST /system-setup/init` creates admin user with correct role
+- [ ] Locally: `httpInitEnabled: true`, and `POST /system-setup/init` creates admin user with correct role
+- [ ] Deployed stage without `httpInit`: `httpInitEnabled: false`, and the init answers 403 `LTNS_0053`
+- [ ] Deployed stage with `initialAdmin`: the admin exists after the first start
 - [ ] `GET /system-setup/status` returns `{ needsSetup: false }` after init
 - [ ] `POST /system-setup/init` returns 403 when users already exist
 
@@ -92,14 +124,17 @@ 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 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                                                                                                                                        |
+| 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                                                                                                                           |
+| camelCase ENV names (`NSC__systemSetup__…`)   | No admin, boot warning           | Write every segment in SCREAMING_SNAKE_CASE: `NSC__SYSTEM_SETUP__INITIAL_ADMIN__EMAIL`                                                                             |
+| Setting up a deployed stage through the UI    | 403 `LTNS_0053`                  | Set `initialAdmin` via ENV, or open the init with `NSC__SYSTEM_SETUP__HTTP_INIT__TOKEN`                                                                            |
+| `httpInit: { token: process.env.X }`, X unset | 403 `LTNS_0053`, boot error      | A missing, empty or short token keeps the init closed on purpose — set the variable                                                                                |
+| `systemSetup: { enabled: false }` in config   | 404 on endpoints                 | Remove the explicit disable                                                                                                                                        |
 
 ---
 

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

@@ -4,13 +4,20 @@ Initial admin user creation for fresh deployments of @lenne.tech/nest-server.
 
 ## TL;DR
 
-System setup is **enabled by default** when BetterAuth is active. No configuration needed.
+System setup is **enabled by default** when BetterAuth is active. No configuration needed locally.
 
-For automated deployments (Docker, CI/CD), set initial admin credentials via ENV:
+**In a deployed environment** (anything but `local`, `ci` and `e2e`) the anonymous `POST /system-setup/init` is
+**closed** since 12.4.0. Provision the first admin via ENV instead — it is created on the next start:
 
 ```bash
-NSC__systemSetup__initialAdmin__email=admin@example.com
-NSC__systemSetup__initialAdmin__password=YourSecurePassword123!
+NSC__SYSTEM_SETUP__INITIAL_ADMIN__EMAIL=admin@example.com
+NSC__SYSTEM_SETUP__INITIAL_ADMIN__PASSWORD=YourSecurePassword123!
+```
+
+Or open the HTTP init on purpose, preferably with a setup token (see [HTTP init](#http-init-systemsetuphttpinit)):
+
+```bash
+NSC__SYSTEM_SETUP__HTTP_INIT__TOKEN=<secret of at least 16 characters>   # sent as X-System-Setup-Token
 ```
 
 **Quick Links:** [Integration Checklist](./INTEGRATION-CHECKLIST.md) | [Endpoints](#endpoints) | [Configuration](#configuration) | [Security](#security)
@@ -22,6 +29,7 @@ NSC__systemSetup__initialAdmin__password=YourSecurePassword123!
 - [Purpose](#purpose)
 - [Endpoints](#endpoints)
 - [Configuration](#configuration)
+- [HTTP init (`systemSetup.httpInit`)](#http-init-systemsetuphttpinit)
 - [Auto-Creation via Config/ENV](#auto-creation-via-configenv)
 - [Security](#security)
 - [Frontend Integration](#frontend-integration)
@@ -33,8 +41,8 @@ NSC__systemSetup__initialAdmin__password=YourSecurePassword123!
 
 When a system is freshly deployed (zero users in the database), there is no way to create an initial admin user - especially when BetterAuth's `disableSignUp` is enabled. This module provides:
 
-1. **REST endpoints** - Manual admin creation via API call
-2. **Auto-creation** - Automatic admin creation on server start via config/ENV
+1. **REST endpoints** - Manual admin creation via API call — open by default only in `local`, `ci` and `e2e`
+2. **Auto-creation** - Automatic admin creation on server start via config/ENV — the way for a deployment
 
 Once any user exists, the init endpoint is permanently locked (returns 403) and auto-creation is skipped.
 
@@ -56,13 +64,28 @@ Returns the current setup status.
 ```json
 {
   "needsSetup": true,
-  "betterAuthEnabled": true
+  "betterAuthEnabled": true,
+  "httpInitEnabled": true,
+  "httpInitTokenRequired": false
 }
 ```
 
+| Field                   | Meaning                                                                                                 |
+| ----------------------- | ------------------------------------------------------------------------------------------------------- |
+| `needsSetup`            | No user exists yet                                                                                      |
+| `betterAuthEnabled`     | BetterAuth is active (required for the init)                                                            |
+| `httpInitEnabled`       | `POST /system-setup/init` is open in this environment (12.4.0+). Independent of `needsSetup`            |
+| `httpInitTokenRequired` | The init needs the `X-System-Setup-Token` header (12.4.0+). Only `true` together with `httpInitEnabled` |
+
+A frontend offers the setup form only when `needsSetup && httpInitEnabled`, with a token field when
+`httpInitTokenRequired`. A backend older than 12.4.0 sends neither field; its init is open as before.
+
 ### POST /system-setup/init
 
-Creates the initial admin user. Only works when zero users exist.
+Creates the initial admin user. Only works when zero users exist, and only where `systemSetup.httpInit` opens it
+(by default in `local`, `ci` and `e2e`).
+
+**Request Header** (only when a token is configured): `X-System-Setup-Token: <setup token>`
 
 **Request Body:**
 
@@ -98,17 +121,21 @@ Creates the initial admin user. Only works when zero users exist.
 }
 ```
 
+The refusals are checked in this order: `LTNS_0053` (HTTP init not enabled here), `LTNS_0054` (setup token missing
+or wrong), then `LTNS_0050` and `LTNS_0052` as before. See [Error Codes](#error-codes).
+
 ---
 
 ## Configuration
 
 System setup is **enabled by default** when BetterAuth is active:
 
-| Config                                   | Effect                              |
-| ---------------------------------------- | ----------------------------------- |
-| _(not set)_                              | Enabled (when BetterAuth is active) |
-| `systemSetup: { enabled: false }`        | Disabled explicitly                 |
-| `systemSetup: { initialAdmin: { ... } }` | Enabled with auto-creation          |
+| Config                                   | Effect                                                                |
+| ---------------------------------------- | --------------------------------------------------------------------- |
+| _(not set)_                              | Enabled (when BetterAuth is active); HTTP init open only locally      |
+| `systemSetup: { enabled: false }`        | Disabled explicitly (no endpoints)                                    |
+| `systemSetup: { initialAdmin: { ... } }` | Enabled with auto-creation                                            |
+| `systemSetup: { httpInit: ... }`         | Opens or closes `POST /system-setup/init` explicitly (12.4.0+, below) |
 
 ```typescript
 // config.env.ts
@@ -129,6 +156,54 @@ systemSetup: {
 
 ---
 
+## HTTP init (`systemSetup.httpInit`)
+
+`POST /system-setup/init` is anonymous: on an API without users, whoever calls it becomes the administrator. Since
+12.4.0 it is therefore **fail-closed** outside the local environments.
+
+| `httpInit`                              | `local` / `ci` / `e2e` | every other environment (`develop`, `test`, `production`, …) |
+| --------------------------------------- | ---------------------- | ------------------------------------------------------------ |
+| _(not set)_                             | open                   | **closed** — 403 `LTNS_0053`                                 |
+| `true`                                  | open                   | open, without a token                                        |
+| `{ token: '<at least 16 characters>' }` | open, token required   | open, token required — 403 `LTNS_0054` without it            |
+| `false` / `{ enabled: false, token }`   | closed                 | closed                                                       |
+
+The environment is the configured `env` (else `NODE_ENV`), compared with the framework's one list of local
+environments (`isLocalEnv()`). The deployed `develop` and `test` stages of a starter-based project, `production`,
+`staging` and any unknown or missing name count as deployed.
+
+```typescript
+// config.env.ts — open with a token (recommended when the setup must happen over the UI)
+systemSetup: {
+  httpInit: { token: process.env.SETUP_TOKEN },
+},
+```
+
+```bash
+# the same via ENV — set ONE of the two
+NSC__SYSTEM_SETUP__HTTP_INIT__TOKEN=<secret of at least 16 characters>
+NSC__SYSTEM_SETUP__HTTP_INIT=true   # open WITHOUT a token: whoever is first becomes admin
+```
+
+**The token** travels in the `X-System-Setup-Token` header, never in the body, and is compared in constant time.
+Hand it to the person who sets the system up, the same way as a password.
+
+**Misconfigurations close, they never open:**
+
+- an object whose token is missing, empty, shorter than 16 characters or not a string keeps the init closed and logs
+  an error at boot. `{ token: process.env.SETUP_TOKEN }` with the variable unset must not become an open init.
+- an empty or all-digit `NSC__SYSTEM_SETUP__HTTP_INIT__TOKEN` is converted to a number by the environment reader, and
+  a long digit string loses digits on the way — such a value is refused. Use a token with letters.
+- a value that is neither a boolean nor an object (the string `"true"` from `NEST_SERVER_CONFIG`) counts as not set.
+
+**Boot report.** A deployed instance that starts with zero users, no usable `initialAdmin` and a closed HTTP init logs
+an error naming both ways in. With the init open without a token it logs a warning. Local environments stay silent.
+
+The Swagger document leaves `POST /system-setup/init` out while the init is closed, like every operation that would
+refuse every caller.
+
+---
+
 ## Auto-Creation via Config/ENV
 
 For automated deployments where no manual REST call is possible (Docker, CI/CD, Kubernetes), configure initial admin credentials via environment variables:
@@ -136,11 +211,16 @@ For automated deployments where no manual REST call is possible (Docker, CI/CD,
 ### Via NSC Environment Variables
 
 ```bash
-NSC__systemSetup__initialAdmin__email=admin@example.com
-NSC__systemSetup__initialAdmin__password=YourSecurePassword123!
-NSC__systemSetup__initialAdmin__name=Admin  # optional
+NSC__SYSTEM_SETUP__INITIAL_ADMIN__EMAIL=admin@example.com
+NSC__SYSTEM_SETUP__INITIAL_ADMIN__PASSWORD=YourSecurePassword123!
+NSC__SYSTEM_SETUP__INITIAL_ADMIN__NAME=Admin  # optional
 ```
 
+Every segment in SCREAMING_SNAKE_CASE. The environment reader lowercases a segment it does not split at `_`, so the
+camelCase form `NSC__systemSetup__initialAdmin__email` — which this README showed until 12.4.0 — lands under
+`systemsetup.initialadmin` and is never read. Since 12.4.0 the boot warns about such a variable and names the correct
+spelling.
+
 ### Via config.env.ts
 
 ```typescript
@@ -162,6 +242,7 @@ NEST_SERVER_CONFIG='{ "systemSetup": { "initialAdmin": { "email": "admin@example
 ### Behavior
 
 - The admin is created automatically during application bootstrap (`OnApplicationBootstrap`)
+- Not affected by `systemSetup.httpInit`: the configured admin is created in every environment
 - Same zero-user guard applies: only works when no users exist
 - If users already exist, auto-creation is silently skipped (no error)
 - Race conditions between multiple instances are handled gracefully: the zero-user check alone is
@@ -187,14 +268,19 @@ NEST_SERVER_CONFIG='{ "systemSetup": { "initialAdmin": { "email": "admin@example
 
 ## Security
 
-1. **Zero-user guard** - Init requires `countDocuments({}) === 0`. Necessary but not sufficient:
+1. **Fail-closed HTTP init (12.4.0)** - Outside `local`, `ci` and `e2e` the anonymous init answers 403
+   `LTNS_0053` unless `systemSetup.httpInit` opens it, preferably with a setup token. Before 12.4.0 a
+   deployment without `initialAdmin` could be taken over by whoever called the init first
+2. **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
+3. **Rollback on failure (12.4.0)** - When a step after creating the user fails (account, sync, role),
+   the user is removed again, so `needsSetup` stays `true` and the setup can be retried. Before,
+   the deployment kept a user without the admin role and was locked for good
+4. **Race condition protection** - MongoDB unique email index prevents duplicates; auto-creation on
    bootstrap is additionally claimed atomically via the `system-setup-locks` marker
-4. **Permanent lock** - Once any user exists, init returns 403
-5. **BetterAuth required** - Returns 403 if BetterAuth is not enabled
+5. **Permanent lock** - Once any user exists, init returns 403
+6. **BetterAuth required** - Returns 403 if BetterAuth is not enabled
 
 ### How It Bypasses disableSignUp
 
@@ -207,15 +293,19 @@ The service uses BetterAuth's `$context.internalAdapter.createUser()` directly,
 Typical frontend flow:
 
 ```typescript
-// 1. Check if setup is needed
+// 1. Check if setup is needed AND possible over HTTP
 const status = await fetch('/system-setup/status');
-const { needsSetup } = await status.json();
+const { needsSetup, httpInitEnabled = true, httpInitTokenRequired = false } = await status.json();
+// (the defaults keep a backend older than 12.4.0 working, where both fields are missing)
 
-if (needsSetup) {
-  // 2. Show setup form and submit
+if (needsSetup && httpInitEnabled) {
+  // 2. Show setup form (with a token field when httpInitTokenRequired) and submit
   const result = await fetch('/system-setup/init', {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
+    headers: {
+      'Content-Type': 'application/json',
+      ...(httpInitTokenRequired ? { 'X-System-Setup-Token': setupToken } : {}),
+    },
     body: JSON.stringify({
       email: 'admin@example.com',
       password: 'SecurePassword123!',
@@ -232,6 +322,29 @@ if (needsSetup) {
 
 ## Troubleshooting
 
+### Init returns 403 `LTNS_0053` "not enabled in this environment"
+
+**Cause:** the environment is not `local`, `ci` or `e2e`, and `systemSetup.httpInit` does not open the init — the
+default since 12.4.0.
+
+**Solutions:**
+
+1. Set `NSC__SYSTEM_SETUP__INITIAL_ADMIN__EMAIL` / `__PASSWORD` and restart — the admin is created at boot
+2. Or open the init with a token: `NSC__SYSTEM_SETUP__HTTP_INIT__TOKEN=<secret>` (sent as `X-System-Setup-Token`)
+3. Check the boot log: an unusable token configuration is logged as an error naming what is wrong
+
+### Init returns 403 `LTNS_0054` "setup token is missing or invalid"
+
+**Cause:** the init requires a token and the request sent none or a different one. Send the configured value in the
+`X-System-Setup-Token` header. A frontend learns that a token is needed from `httpInitTokenRequired`.
+
+### `needsSetup` is `false`, but nobody can sign in as admin
+
+**Cause (before 12.4.0):** a creation failed after the user was written (for example a failing account link), and
+the user stayed behind without the admin role. Since 12.4.0 such a user is removed again. On an older version, or if
+the server log says the partially created user "could not be removed", delete that user and its `account` rows and
+retry.
+
 ### Init returns 403 "System setup not available"
 
 **Two different guards raise this, and the response cannot tell you which.**
@@ -290,11 +403,12 @@ DELETE FROM lt_locks WHERE id = 'system-setup:initial-admin';
 
 ### Auto-creation not working
 
-**Cause:** Missing or incomplete ENV variables.
+**Cause:** Missing, incomplete or misspelled ENV variables.
 
 **Solutions:**
 
-1. Verify both `email` and `password` are set
+1. Verify both `email` and `password` are set, spelled `NSC__SYSTEM_SETUP__INITIAL_ADMIN__EMAIL` /
+   `__PASSWORD` — a camelCase spelling (`NSC__systemSetup__…`) is not read; the boot warns about it
 2. Check server logs for `Auto-created initial admin on startup` or warning messages
 3. Ensure BetterAuth is fully initialized (check startup logs)
 
@@ -316,6 +430,8 @@ DELETE FROM lt_locks WHERE id = 'system-setup:initial-admin';
 | 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                                 |
+| LTNS_0053 | `SYSTEM_SETUP_HTTP_INIT_DISABLED`  | HTTP init not enabled in this environment (12.4.0+)        |
+| LTNS_0054 | `SYSTEM_SETUP_TOKEN_INVALID`       | Setup token missing or wrong (12.4.0+)                     |
 
 ---
 

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

@@ -1,10 +1,15 @@
-import { Body, Controller, Get, Post } from '@nestjs/common';
-import { ApiBody, ApiOperation, ApiProperty, ApiResponse, ApiTags } from '@nestjs/swagger';
+import { Body, Controller, Get, Headers, Post } from '@nestjs/common';
+import { ApiBody, ApiHeader, ApiOperation, ApiProperty, ApiResponse, ApiTags } from '@nestjs/swagger';
 import { IsEmail, IsNotEmpty, IsOptional, IsString, MinLength } from 'class-validator';
 
 import { Roles } from '../../common/decorators/roles.decorator.js';
 import { RoleEnum } from '../../common/enums/role.enum.js';
-import { CoreSystemSetupService, SystemSetupInitResult, SystemSetupStatus } from './core-system-setup.service.js';
+import {
+  CoreSystemSetupService,
+  type SystemSetupInitResult,
+  type SystemSetupStatus,
+} from './core-system-setup.service.js';
+import { SYSTEM_SETUP_TOKEN_HEADER } from './system-setup-http-init.helper.js';
 
 /**
  * DTO for system setup init request
@@ -31,8 +36,12 @@ export class SystemSetupInitDto {
  * CoreSystemSetupController provides REST endpoints for initial system setup.
  *
  * These endpoints are public (S_EVERYONE) to allow first-time admin creation
- * on a fresh system with zero users. The service enforces security by checking
- * that no users exist before allowing creation.
+ * on a fresh system with zero users. The service enforces security: the init is
+ * refused where `systemSetup.httpInit` does not open it (by default every
+ * environment except `local`, `ci` and `e2e`), and once any user exists.
+ *
+ * A subclass that overrides `createInitialAdmin()` must call
+ * `systemSetupService.assertHttpInitAllowed(token)` itself.
  */
 @ApiTags('System Setup')
 @Controller('system-setup')
@@ -55,18 +64,31 @@ export class CoreSystemSetupController {
    * Create the initial admin user (only works when zero users exist)
    */
   @ApiBody({ type: SystemSetupInitDto })
+  @ApiHeader({
+    description: 'The setup token, required when systemSetup.httpInit configures one (see GET /system-setup/status)',
+    name: SYSTEM_SETUP_TOKEN_HEADER,
+    required: false,
+  })
   @ApiOperation({
-    description: 'Creates the initial admin user. Only works when zero users exist in the database.',
+    description:
+      'Creates the initial admin user. Only works when zero users exist in the database, and only where ' +
+      'systemSetup.httpInit opens it (by default in the local, ci and e2e environments).',
     summary: 'Create initial admin',
   })
   @ApiResponse({ description: 'Initial admin created', status: 201 })
   @ApiResponse({
-    description: 'System setup not available - users already exist, or the initial-admin setup is claimed',
+    description:
+      'LTNS_0053: HTTP init not enabled in this environment; LTNS_0054: setup token missing or invalid; ' +
+      'LTNS_0050: 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> {
+  async createInitialAdmin(
+    @Body() input: SystemSetupInitDto,
+    @Headers(SYSTEM_SETUP_TOKEN_HEADER) token?: string,
+  ): Promise<SystemSetupInitResult> {
+    this.systemSetupService.assertHttpInitAllowed(token);
     return this.systemSetupService.createInitialAdmin(input);
   }
 }