4eddf7e094
- 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`.
99 lines
3.0 KiB
Markdown
99 lines
3.0 KiB
Markdown
# 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
|
|
|
|
1. **First Server Start**: When the server starts without any admin users, it generates a cryptographically secure setup token
|
|
2. **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
|
|
=================================================================
|
|
```
|
|
3. **Access Setup Page**: Visit `http://localhost:8080/` and the setup page is automatically served
|
|
4. **Create Admin**: Enter the setup token and admin details
|
|
5. **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:
|
|
|
|
1. Visit `http://localhost:3000/` (frontend dev server)
|
|
2. The dev server checks setup status from backend
|
|
3. If setup required: Serves the setup page directly (proxied from backend)
|
|
4. 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
|
|
```bash
|
|
GET /api/v1/auth/setup-status
|
|
```
|
|
|
|
Response:
|
|
```json
|
|
{
|
|
"setup_required": true,
|
|
"has_valid_token": true,
|
|
"token_expires_at": "2026-03-04T07:19:50.840608Z"
|
|
}
|
|
```
|
|
|
|
### Complete Setup
|
|
```bash
|
|
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:
|
|
|
|
1. **Wait 24 hours**: The token will expire automatically
|
|
2. **Clear database**: Remove the unused token from `setup_tokens` table
|
|
3. **Restart server**: A new token will be generated
|
|
|
|
### Setup Not Working in Dev Mode
|
|
|
|
1. Ensure backend is running on port 8080
|
|
2. Check browser console for errors
|
|
3. 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
|