# 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