@lenne.tech/nest-server 12.3.1 → 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);
   }
 }

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

@@ -15,6 +15,8 @@ import {
   systemSetupMongoLocks,
 } from '../../common/persistence/infrastructure-locks.js';
 import type { LockStore } from '../../common/persistence/lock-store.interface.js';
+import { isLocalEnv } from '../../common/helpers/cookies.helper.js';
+import type { ISystemSetupInitialAdmin } from '../../common/interfaces/server-options.interface.js';
 import { ConfigService } from '../../common/services/config.service.js';
 import { legacyCredentialAccountIssuer } from '../better-auth/core-better-auth-account-issuer.helper.js';
 import { CoreBetterAuthUserMapper } from '../better-auth/core-better-auth-user.mapper.js';
@@ -22,6 +24,12 @@ import { CoreBetterAuthService } from '../better-auth/core-better-auth.service.j
 import { ErrorCode } from '../error-code/error-codes.js';
 import { getPersistenceRuntime } from '../../common/persistence/persistence-runtime.registry.js';
 import { getBetterAuthSqlStore } from '../better-auth/core-better-auth-sql.registry.js';
+import {
+  type ISystemSetupHttpInitPolicy,
+  isSystemSetupTokenValid,
+  resolveSystemSetupHttpInit,
+  SYSTEM_SETUP_TOKEN_HEADER,
+} from './system-setup-http-init.helper.js';
 
 /**
  * Collection holding the bootstrap claim marker on MongoDB — the 12.0.0 document (`{ _id, claimedAt }`), kept so
@@ -63,6 +71,23 @@ export interface SystemSetupInitResult {
  */
 export interface SystemSetupStatus {
   betterAuthEnabled: boolean;
+
+  /**
+   * Whether `POST /system-setup/init` is open in this environment (`systemSetup.httpInit`; by default only in
+   * `local`, `ci` and `e2e`). Independent of `needsSetup`: a frontend offers the setup form only when both are true.
+   *
+   * @since 12.4.0
+   */
+  httpInitEnabled: boolean;
+
+  /**
+   * Whether the init must carry the setup token in the `X-System-Setup-Token` header. Only ever true together with
+   * `httpInitEnabled`.
+   *
+   * @since 12.4.0
+   */
+  httpInitTokenRequired: boolean;
+
   needsSetup: boolean;
 }
 
@@ -74,9 +99,12 @@ export interface SystemSetupStatus {
  * which is the same approach used by Better-Auth's own admin plugin.
  *
  * Security:
+ * - The anonymous HTTP init is open only where `systemSetup.httpInit` allows it — by default only in `local`, `ci`
+ *   and `e2e` ({@link assertHttpInitAllowed}); a deployment provisions its first admin via `initialAdmin` instead
  * - Only works when zero users exist in the database
  * - Once any user exists, the init endpoint is permanently locked
- * - Race conditions handled by MongoDB unique email index
+ * - Race conditions handled by an atomic claim shared by both entry points
+ * - A creation that fails after the user was created removes that user again, so `needsSetup` stays true
  */
 @Injectable()
 export class CoreSystemSetupService implements OnApplicationBootstrap {
@@ -100,32 +128,21 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
    * is fully initialized before attempting user creation.
    */
   async onApplicationBootstrap(): Promise<void> {
-    const initialAdmin = this.configService.configFastButReadOnly?.systemSetup?.initialAdmin;
+    await this.createInitialAdminFromConfig();
+    await this.reportSetupReachability();
+  }
 
-    // No initialAdmin config at all → skip silently
+  /**
+   * Create the initial admin from `systemSetup.initialAdmin` when zero users exist (the boot half of
+   * {@link onApplicationBootstrap}). Not gated by `systemSetup.httpInit`: it is the deployment's own configuration,
+   * not an anonymous request.
+   */
+  protected async createInitialAdminFromConfig(): Promise<void> {
+    const initialAdmin = this.usableInitialAdmin({ warn: true });
     if (!initialAdmin) {
       return;
     }
 
-    // Partial credentials → warn and skip
-    if (!initialAdmin.email || !initialAdmin.password) {
-      const missing = [!initialAdmin.email && 'email', !initialAdmin.password && 'password'].filter(Boolean).join(', ');
-      this.logger.warn(`Incomplete initialAdmin config - missing: ${missing}. Auto-creation skipped.`);
-      return;
-    }
-
-    // Validate email format (same validator as @IsEmail() decorator)
-    if (!isEmail(initialAdmin.email)) {
-      this.logger.warn(`Invalid initialAdmin email format: "${initialAdmin.email}". Auto-creation skipped.`);
-      return;
-    }
-
-    // Validate password is not empty/whitespace
-    if (!initialAdmin.password.trim()) {
-      this.logger.warn('Empty initialAdmin password. Auto-creation skipped.');
-      return;
-    }
-
     const status = await this.getSetupStatus();
     if (!status.needsSetup) {
       return;
@@ -161,6 +178,169 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
     }
   }
 
+  /**
+   * The configured `systemSetup.initialAdmin`, or `undefined` when it is absent or cannot be used.
+   *
+   * With `warn`, each reason it cannot be used is logged (the boot path); without, it only answers.
+   */
+  protected usableInitialAdmin(options?: { warn?: boolean }): ISystemSetupInitialAdmin | undefined {
+    const initialAdmin = this.configService.configFastButReadOnly?.systemSetup?.initialAdmin;
+    const skip = (message: string): undefined => {
+      if (options?.warn) {
+        this.logger.warn(message);
+      }
+      return undefined;
+    };
+
+    // No initialAdmin config at all → nothing to report here
+    if (!initialAdmin) {
+      return undefined;
+    }
+
+    // Partial credentials → skip
+    if (!initialAdmin.email || !initialAdmin.password) {
+      const missing = [!initialAdmin.email && 'email', !initialAdmin.password && 'password'].filter(Boolean).join(', ');
+      return skip(`Incomplete initialAdmin config - missing: ${missing}. Auto-creation skipped.`);
+    }
+
+    // Validate email format (same validator as @IsEmail() decorator)
+    if (!isEmail(initialAdmin.email)) {
+      return skip(`Invalid initialAdmin email format: "${initialAdmin.email}". Auto-creation skipped.`);
+    }
+
+    // An all-digit NSC__SYSTEM_SETUP__INITIAL_ADMIN__PASSWORD arrives as a NUMBER (getEnvironmentObject() converts
+    // numeric strings), and `.trim()` on it used to throw at boot. Name the cause instead.
+    if (typeof initialAdmin.password !== 'string') {
+      return skip(
+        `initialAdmin password is a ${typeof initialAdmin.password}, not a string (an all-digit ENV value is ` +
+          'converted to a number). Auto-creation skipped.',
+      );
+    }
+
+    // Validate password is not empty/whitespace
+    if (!initialAdmin.password.trim()) {
+      return skip('Empty initialAdmin password. Auto-creation skipped.');
+    }
+
+    return initialAdmin;
+  }
+
+  /**
+   * The environment the HTTP-init policy is decided for: the configured `env`, else `NODE_ENV`
+   */
+  protected currentEnv(): string | undefined {
+    return this.configService.configFastButReadOnly?.env ?? process.env.NODE_ENV;
+  }
+
+  /**
+   * Whether the anonymous `POST /system-setup/init` is open here, and whether it needs the setup token
+   * (`systemSetup.httpInit`, see {@link resolveSystemSetupHttpInit}).
+   */
+  getHttpInitPolicy(): ISystemSetupHttpInitPolicy {
+    return resolveSystemSetupHttpInit(
+      this.configService.configFastButReadOnly?.systemSetup?.httpInit,
+      this.currentEnv(),
+    );
+  }
+
+  /**
+   * Refuse an HTTP init the configuration does not allow — call it from every HTTP entry point before
+   * {@link createInitialAdmin}, which does not check it (the boot path must not be gated).
+   *
+   * @param token the value of the `X-System-Setup-Token` header
+   * @throws ForbiddenException `SYSTEM_SETUP_HTTP_INIT_DISABLED` when the HTTP init is closed in this environment,
+   *   `SYSTEM_SETUP_TOKEN_INVALID` when it needs a token and `token` is missing or wrong
+   */
+  assertHttpInitAllowed(token?: unknown): void {
+    const policy = this.getHttpInitPolicy();
+    if (!policy.enabled) {
+      throw new ForbiddenException(ErrorCode.SYSTEM_SETUP_HTTP_INIT_DISABLED);
+    }
+    if (policy.tokenRequired && !isSystemSetupTokenValid(policy.token, token)) {
+      throw new ForbiddenException(ErrorCode.SYSTEM_SETUP_TOKEN_INVALID);
+    }
+  }
+
+  /**
+   * Say at boot when a deployment has no way to its first admin, or an open one (the second half of
+   * {@link onApplicationBootstrap}).
+   *
+   * A deployed environment with zero users, no usable `initialAdmin` and a closed HTTP init cannot be set up at all:
+   * nobody notices until somebody tries to sign in. With the HTTP init open WITHOUT a token, whoever reaches the API
+   * first becomes the administrator. Both are logged; neither stops the boot. Local environments are left alone,
+   * and an instance with a usable `initialAdmin` reports through the auto-creation instead — reporting here as well
+   * would raise a false alarm on every replica that lost the creation race while the winner is still creating.
+   */
+  protected async reportSetupReachability(): Promise<void> {
+    const policy = this.getHttpInitPolicy();
+    if (policy.problem) {
+      this.logger.error(
+        `POST /system-setup/init stays closed: ${policy.problem}. Set a token of at least 16 characters ` +
+          '(NSC__SYSTEM_SETUP__HTTP_INIT__TOKEN), or systemSetup.httpInit: true to open it without one.',
+      );
+    }
+    this.warnAboutIgnoredEnvironmentNames();
+
+    if (isLocalEnv(this.currentEnv()) || this.usableInitialAdmin() || (policy.enabled && policy.tokenRequired)) {
+      return;
+    }
+
+    let needsSetup: boolean;
+    try {
+      needsSetup = (await this.getSetupStatus()).needsSetup;
+    } catch (error) {
+      // A diagnostic must never be the reason a boot fails
+      this.logger.warn(
+        `Could not check whether initial setup is needed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      );
+      return;
+    }
+    if (!needsSetup) {
+      return;
+    }
+
+    const env = this.currentEnv() ?? '(not set)';
+    if (!policy.enabled) {
+      this.logger.error(
+        `No users exist and this instance cannot be set up: environment "${env}" closes POST /system-setup/init, ` +
+          'and no initialAdmin is configured. Set NSC__SYSTEM_SETUP__INITIAL_ADMIN__EMAIL and ' +
+          'NSC__SYSTEM_SETUP__INITIAL_ADMIN__PASSWORD (created on the next start), or open the HTTP init explicitly ' +
+          'with NSC__SYSTEM_SETUP__HTTP_INIT__TOKEN=<secret of at least 16 characters> ' +
+          `(sent as the "${SYSTEM_SETUP_TOKEN_HEADER}" header).`,
+      );
+      return;
+    }
+    this.logger.warn(
+      `No users exist and POST /system-setup/init is open without a token in environment "${env}": whoever reaches ` +
+        'the API first becomes the administrator. Prefer NSC__SYSTEM_SETUP__INITIAL_ADMIN__EMAIL / __PASSWORD, or ' +
+        'protect the init with NSC__SYSTEM_SETUP__HTTP_INIT__TOKEN.',
+    );
+  }
+
+  /**
+   * Warn about `NSC__` variables for `systemSetup` that carry a camelCase segment (`NSC__systemSetup__initialAdmin__email`).
+   *
+   * `getEnvironmentObject()` lowercases every segment it does not split at `_`, so such a variable lands under
+   * `systemsetup.initialadmin` — a key nothing reads — and the auto-creation silently never happens. The framework's
+   * own documentation spelled the variables that way until 12.4.0. Only the variable NAMES are logged, never values.
+   */
+  protected warnAboutIgnoredEnvironmentNames(): void {
+    for (const key of Object.keys(process.env)) {
+      if (!key.startsWith('NSC__')) {
+        continue;
+      }
+      const segments = key.slice('NSC__'.length).split('__');
+      if (
+        segments[0]?.replace(/_/g, '').toLowerCase() !== 'systemsetup' ||
+        !segments.some((s) => /[a-z][A-Z]/.test(s))
+      ) {
+        continue;
+      }
+      const corrected = `NSC__${segments.map((s) => s.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toUpperCase()).join('__')}`;
+      this.logger.warn(`Environment variable ${key} is not read (camelCase segment). Use ${corrected} instead.`);
+    }
+  }
+
   /**
    * Try to claim the initial-admin creation for this instance
    *
@@ -193,6 +373,31 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
     }
   }
 
+  /**
+   * Remove the user a failed {@link createInitialAdmin} had already created: Better-Auth's sessions and accounts and
+   * the `users` row, which Better-Auth and the user model share. Without it the deployment keeps a user without the
+   * admin role, `needsSetup` turns false and init stays refused for good.
+   *
+   * Never throws: the failure that triggered the rollback is the one the caller must see. A rollback that fails is
+   * logged with what to remove by hand.
+   */
+  protected async rollbackInitialAdmin(
+    context: { internalAdapter: { deleteUser(userId: string): Promise<unknown> } },
+    iamUserId: string,
+    email: string,
+  ): Promise<void> {
+    try {
+      await context.internalAdapter.deleteUser(iamUserId);
+      this.logger.warn(`Initial admin creation failed; the partially created user ${email} was removed again`);
+    } catch (error) {
+      this.logger.error(
+        `Initial admin creation failed and the partially created user ${email} could not be removed ` +
+          `(${error instanceof Error ? error.message : 'Unknown error'}). Remove that user and its accounts from ` +
+          '"users" and "account", otherwise initial setup stays refused because a user exists.',
+      );
+    }
+  }
+
   /**
    * Where the claim lives: the lease table when the default data source is a SQL database, else the MongoDB marker
    */
@@ -229,8 +434,11 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
    */
   async getSetupStatus(): Promise<SystemSetupStatus> {
     const userCount = await this.countUsers();
+    const httpInit = this.getHttpInitPolicy();
     return {
       betterAuthEnabled: this.betterAuthService.isEnabled(),
+      httpInitEnabled: httpInit.enabled,
+      httpInitTokenRequired: httpInit.enabled && httpInit.tokenRequired,
       needsSetup: userCount === 0,
     };
   }
@@ -240,6 +448,9 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
    *
    * Uses BetterAuth's internalAdapter to bypass disableSignUp,
    * then syncs to nest-server users collection with admin role.
+   *
+   * Does NOT check `systemSetup.httpInit`: the boot path calls it too. An HTTP entry point calls
+   * {@link assertHttpInitAllowed} first, as `CoreSystemSetupController` does.
    */
   async createInitialAdmin(input: SystemSetupInitInput): Promise<SystemSetupInitResult> {
     // Pre-check: only allow when zero users exist
@@ -291,9 +502,12 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
       throw new ForbiddenException(ErrorCode.SYSTEM_SETUP_NOT_AVAILABLE);
     }
 
+    // Set once the IAM user exists: every failure after that point removes the user again (see the catch below)
+    let createdIamUserId: string | undefined;
+    let context: Awaited<typeof authInstance.$context> | undefined;
     try {
       // Access BetterAuth internal context (same pattern as core-better-auth-api.middleware.ts)
-      const context = await authInstance.$context;
+      context = await authInstance.$context;
 
       // Normalize password for IAM (SHA256 if plain text)
       const normalizedPassword = this.userMapper.normalizePasswordForIam(input.password);
@@ -329,6 +543,7 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
       if (!iamUser) {
         throw new Error('Failed to create IAM user');
       }
+      createdIamUserId = iamUser.id;
 
       // Hash password and create credential account
       const hashedPassword = await context.password.hash(normalizedPassword);
@@ -382,6 +597,14 @@ export class CoreSystemSetupService implements OnApplicationBootstrap {
         success: true,
       };
     } catch (error) {
+      // Remove the user this call created BEFORE releasing the claim. A failure after createUser (linkAccount,
+      // the sync, the role update, the legacy password) otherwise left a user without the admin role — and from then
+      // on `needsSetup` is false and init refused, so the deployment had users but no administrator and no way back
+      // short of editing the database. Seen on a deployed stage when linkAccount threw.
+      if (createdIamUserId && context) {
+        await this.rollbackInitialAdmin(context, createdIamUserId, input.email);
+      }
+
       // Release the claim we took above: a caller that failed mid-creation must not
       // leave a deployment with zero users and no way in. The marker is additionally
       // stale-expiring, so this is belt AND braces for the crash-before-release case.

package/src/core/modules/system-setup/system-setup-http-init.helper.ts

@@ -0,0 +1,130 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+
+import { isLocalEnv } from '../../common/helpers/cookies.helper.js';
+
+/**
+ * The request header `POST /system-setup/init` reads the setup token from (`systemSetup.httpInit.token`).
+ *
+ * A header, never a body field: the body is the admin's credentials and is shaped by the DTO, while the token is a
+ * deployment secret the operator hands out separately. Header names are case-insensitive; Express lowercases them.
+ *
+ * @since 12.4.0
+ */
+export const SYSTEM_SETUP_TOKEN_HEADER = 'x-system-setup-token';
+
+/**
+ * Minimum length of a configured setup token.
+ *
+ * The init route is anonymous and not rate-limited, so the token is all that stands between a caller and an
+ * administrator account. A shorter value is refused as a misconfiguration (the HTTP init stays closed), never
+ * accepted as a weak gate.
+ *
+ * @since 12.4.0
+ */
+export const SYSTEM_SETUP_TOKEN_MIN_LENGTH = 16;
+
+/**
+ * Whether `POST /system-setup/init` may run, as decided from `systemSetup.httpInit` and the environment.
+ *
+ * @since 12.4.0
+ */
+export interface ISystemSetupHttpInitPolicy {
+  /** The HTTP init is open (with or without a token) */
+  enabled: boolean;
+
+  /**
+   * What is wrong with the configuration when it is unusable — a token that is missing, empty, too short or not a
+   * string. Set only when the configuration asked for a token-protected init and could not get one; the init then
+   * stays CLOSED. Meant for the boot log.
+   */
+  problem?: string;
+
+  /** Why the decision came out this way: the environment default, or an explicit setting */
+  source: 'config' | 'default';
+
+  /** The configured token, when the init is open and token-protected */
+  token?: string;
+
+  /** A token must be sent in {@link SYSTEM_SETUP_TOKEN_HEADER} */
+  tokenRequired: boolean;
+}
+
+/**
+ * Decide whether the anonymous `POST /system-setup/init` is open, from `systemSetup.httpInit` and the environment.
+ *
+ * Fail-closed in every branch that is not an explicit, well-formed opt-in:
+ *
+ * | `httpInit`                            | `local` / `ci` / `e2e` | every other environment |
+ * |---------------------------------------|------------------------|-------------------------|
+ * | not set (or not a boolean / object)   | open, no token         | **closed**              |
+ * | `true`                                | open, no token         | open, no token          |
+ * | `false` / `{ enabled: false, … }`     | closed                 | closed                  |
+ * | `{ token: '<≥ 16 characters>' }`      | open, token required   | open, token required    |
+ * | an object without a usable token      | closed + `problem`     | closed + `problem`      |
+ *
+ * The environment test is {@link isLocalEnv}: the deployed `develop` and `test` stages of a starter-based project,
+ * `production`, `staging` and an unknown or missing name all count as deployed.
+ *
+ * Why an object without a usable token CLOSES rather than opening without one: the natural way to write the option is
+ * `httpInit: { token: process.env.SETUP_TOKEN }`, and with the variable missing that is `{ token: undefined }`. Reading
+ * it as "open, no token" would turn a forgotten secret into an anonymous administrator endpoint — the incident this
+ * exists for. A value from `NSC__SYSTEM_SETUP__HTTP_INIT__TOKEN` that is empty or all digits arrives as a NUMBER
+ * (`getEnvironmentObject()` converts numeric strings, `''` included, and a long digit string loses digits on the way),
+ * so a non-string token is refused too. And a non-boolean `httpInit` (the string `'true'` from `NEST_SERVER_CONFIG`)
+ * reads as "not set", so a string cannot open the route by truthiness.
+ *
+ * @since 12.4.0
+ */
+export function resolveSystemSetupHttpInit(httpInit: unknown, env: string | undefined): ISystemSetupHttpInitPolicy {
+  if (httpInit === true) {
+    return { enabled: true, source: 'config', tokenRequired: false };
+  }
+  if (httpInit === false) {
+    return { enabled: false, source: 'config', tokenRequired: false };
+  }
+  if (httpInit && typeof httpInit === 'object' && !Array.isArray(httpInit)) {
+    const { enabled, token } = httpInit as { enabled?: unknown; token?: unknown };
+    if (enabled === false) {
+      return { enabled: false, source: 'config', tokenRequired: false };
+    }
+    const problem = tokenProblem(token);
+    if (problem) {
+      return { enabled: false, problem, source: 'config', tokenRequired: false };
+    }
+    return { enabled: true, source: 'config', token: token as string, tokenRequired: true };
+  }
+  return { enabled: isLocalEnv(env), source: 'default', tokenRequired: false };
+}
+
+/**
+ * Whether `provided` (the header value) matches the configured `expected` token.
+ *
+ * Both sides are hashed to the same length before `timingSafeEqual`, so neither the content nor the LENGTH of the
+ * configured token leaks through the response time. A missing, empty or non-string value never matches.
+ *
+ * @since 12.4.0
+ */
+export function isSystemSetupTokenValid(expected: string | undefined, provided: unknown): boolean {
+  if (typeof expected !== 'string' || !expected || typeof provided !== 'string' || !provided) {
+    return false;
+  }
+  const digest = (value: string) => createHash('sha256').update(value, 'utf8').digest();
+  return timingSafeEqual(digest(expected), digest(provided));
+}
+
+/** Why a configured token cannot be used, or `undefined` when it can */
+function tokenProblem(token: unknown): string | undefined {
+  if (token === undefined || token === null) {
+    return 'systemSetup.httpInit is an object without a token';
+  }
+  if (typeof token !== 'string') {
+    return (
+      `systemSetup.httpInit.token is a ${typeof token}, not a string — an empty or all-digit ` +
+      'NSC__SYSTEM_SETUP__HTTP_INIT__TOKEN is converted to a number; use a token with letters'
+    );
+  }
+  if (token.trim().length < SYSTEM_SETUP_TOKEN_MIN_LENGTH) {
+    return `systemSetup.httpInit.token is shorter than ${SYSTEM_SETUP_TOKEN_MIN_LENGTH} characters`;
+  }
+  return undefined;
+}

package/src/index.ts

@@ -277,6 +277,7 @@ export * from './core/modules/permissions/permissions-scanner.js';
 export * from './core/modules/system-setup/core-system-setup.controller.js';
 export * from './core/modules/system-setup/core-system-setup.module.js';
 export * from './core/modules/system-setup/core-system-setup.service.js';
+export * from './core/modules/system-setup/system-setup-http-init.helper.js';
 
 // =====================================================================================================================
 // Core - Modules - Sync (offline sync)