Files

GW_MC 4eddf7e094 feat: Implement initial setup service for admin user creation

- Added `SetupService` to handle the generation and validation of setup tokens.
- Integrated setup token generation during application startup if no admin users exist.
- Created API endpoints for checking setup status and completing the initial setup.
- Updated `AuthService` to include functionality for creating the initial admin user.
- Enhanced error handling for setup and authentication processes.
- Added frontend components for login and protected routes.
- Implemented Zustand store for managing authentication state.
- Updated Vite configuration to check setup status and serve the setup page if required.
- Documented the initial setup process in `setup.md`.

2026-03-03 07:46:49 +00:00

3.0 KiB

Raw Permalink Blame History

NxMesh Initial Setup

Overview

NxMesh uses a secure, production-ready initial setup system for creating the first admin account. This ensures no default credentials exist in the system.

How It Works

Production Mode

First Server Start: When the server starts without any admin users, it generates a cryptographically secure setup token

Token Display: The token is displayed only in the server console/logs:

=================================================================
                     INITIAL SETUP REQUIRED                      
=================================================================
SETUP TOKEN: nxm_CbCa87uchQye6ZOWysnitrZC0F5mhrrJPcPmwDrq...
EXPIRES AT:  2026-03-04 07:19:50.840608304 UTC
=================================================================

Access Setup Page: Visit http://localhost:8080/ and the setup page is automatically served
Create Admin: Enter the setup token and admin details
Done: After setup, the normal application is served

Development Mode

In development (just dev or bun dev), the Vite dev server automatically checks setup status:

Visit http://localhost:3000/ (frontend dev server)
The dev server checks setup status from backend
If setup required: Serves the setup page directly (proxied from backend)
If setup complete: Serves the React application

The dev experience is seamless - you don't need to switch ports.

Security Features

Feature	Description
Token Format	68-character random string: `nxm_` prefix + 64 chars
Storage	SHA-256 hash stored in database, plain token never saved
Expiration	24-hour validity period
Single Use	Token invalidated after successful admin creation
Console Only	Token displayed only in server logs, not exposed via API
Cryptographic RNG	Uses `OsRng` for secure random generation

API Endpoints

Check Setup Status

GET /api/v1/auth/setup-status

Response:

{
  "setup_required": true,
  "has_valid_token": true,
  "token_expires_at": "2026-03-04T07:19:50.840608Z"
}

Complete Setup

POST /api/v1/auth/setup
Content-Type: application/json

{
  "token": "nxm_...",
  "email": "admin@example.com",
  "password": "SecurePass123!",
  "name": "Administrator"
}

Troubleshooting

Lost Setup Token

If you lose the setup token before completing setup:

Wait 24 hours: The token will expire automatically
Clear database: Remove the unused token from setup_tokens table
Restart server: A new token will be generated

Setup Not Working in Dev Mode

Ensure backend is running on port 8080
Check browser console for errors
Try accessing http://localhost:8080/ directly (backend URL)

Already Completed Setup

Once setup is complete:

The setup token is invalidated
The setup page will no longer be served
Normal login flow is required
Use /api/v1/auth/login to authenticate

3.0 KiB Raw Permalink Blame History