init tools repo

2025-11-23 19:57:05 +01:00
commit d778206940
35 changed files with 6197 additions and 0 deletions
--- a/asf-cloud-server/TBM_devbench/docs/API.md
+++ b/asf-cloud-server/TBM_devbench/docs/API.md
@@ -0,0 +1,649 @@
+# DevBench Manager - API Documentation
+
+## Base URL
+
+```
+http://localhost:9090
+https://tbm.nabd-co.com
+```
+
+## Authentication
+
+All API endpoints (except `/login` and `/health`) require authentication via session cookies.
+
+### Session Cookie
+- **Name**: `connect.sid`
+- **Type**: HTTP-only
+- **Secure**: true (in production with HTTPS)
+- **SameSite**: Lax
+
+## Endpoints
+
+### Health Check
+
+#### GET /health
+
+Check application health status.
+
+**Authentication**: Not required
+
+**Response**:
+```json
+{
+  "status": "ok",
+  "timestamp": "2025-11-23T12:00:00.000Z",
+  "version": "1.0.0"
+}
+```
+
+**Status Codes**:
+- `200`: Application is healthy
+
+---
+
+### Authentication
+
+#### GET /login
+
+Display login page.
+
+**Authentication**: Not required
+
+**Response**: HTML page
+
+---
+
+#### POST /login
+
+Authenticate user and create session.
+
+**Authentication**: Not required
+
+**Request Body**:
+```json
+{
+  "username": "admin",
+  "password": "admin123"
+}
+```
+
+**Response**: Redirect to `/dashboard` or `/admin`
+
+**Status Codes**:
+- `302`: Success, redirect to dashboard
+- `200`: Failed, re-render login with error
+
+---
+
+#### GET /logout
+
+Destroy session and logout user.
+
+**Authentication**: Required
+
+**Response**: Redirect to `/login`
+
+**Status Codes**:
+- `302`: Success, redirect to login
+
+---
+
+### User Dashboard
+
+#### GET /dashboard
+
+Display user's DevBench dashboard.
+
+**Authentication**: Required (User role)
+
+**Response**: HTML page with user's DevBenches
+
+**Status Codes**:
+- `200`: Success
+- `302`: Redirect to `/admin` if user is admin
+- `302`: Redirect to `/login` if not authenticated
+
+---
+
+#### GET /help
+
+Display help page with SSH configuration guide.
+
+**Authentication**: Required
+
+**Response**: HTML page with documentation
+
+**Status Codes**:
+- `200`: Success
+- `302`: Redirect to `/login` if not authenticated
+
+---
+
+### DevBench Management
+
+#### POST /create-devbench
+
+Create a new DevBench.
+
+**Authentication**: Required (User role)
+
+**Request Body**:
+```json
+{
+  "name": "test-vm"
+}
+```
+
+**Validation**:
+- Name must match pattern: `[a-zA-Z0-9_-]+`
+- Name must be unique for user
+
+**Response**:
+```json
+{
+  "success": true,
+  "devbenchId": 123
+}
+```
+
+**Error Response**:
+```json
+{
+  "error": "DevBench with this name already exists"
+}
+```
+
+**Status Codes**:
+- `200`: Success
+- `400`: Validation error
+- `500`: Database error
+
+**Side Effects**:
+- Creates database record with status "creating"
+- Spawns provision script execution
+- Sends real-time updates via WebSocket
+
+---
+
+#### POST /delete-devbench/:id
+
+Delete a DevBench.
+
+**Authentication**: Required (User role, owner only)
+
+**Parameters**:
+- `id`: DevBench ID (integer)
+
+**Response**:
+```json
+{
+  "success": true
+}
+```
+
+**Error Response**:
+```json
+{
+  "error": "DevBench not found"
+}
+```
+
+**Status Codes**:
+- `200`: Success
+- `404`: DevBench not found
+- `500`: Database error
+
+**Side Effects**:
+- Executes delete command on remote host
+- Removes database record
+
+---
+
+#### POST /activate-devbench/:id
+
+Activate a DevBench.
+
+**Authentication**: Required (User role, owner only)
+
+**Parameters**:
+- `id`: DevBench ID (integer)
+
+**Response**:
+```json
+{
+  "success": true
+}
+```
+
+**Error Response**:
+```json
+{
+  "error": "DevBench not found"
+}
+```
+
+**Status Codes**:
+- `200`: Success
+- `404`: DevBench not found
+
+**Side Effects**:
+- Executes activate command on remote host
+- Updates status via WebSocket
+
+---
+
+#### GET /check-status/:id
+
+Check DevBench status.
+
+**Authentication**: Required (User role, owner only)
+
+**Parameters**:
+- `id`: DevBench ID (integer)
+
+**Response**:
+```json
+{
+  "status": "active"
+}
+```
+
+**Possible Status Values**:
+- `active`: VM is running
+- `inactive`: VM is stopped
+- `creating`: VM is being created
+- `error`: VM creation failed
+- `unknown`: Status cannot be determined
+
+**Status Codes**:
+- `200`: Success
+
+**Side Effects**:
+- Updates database with current status
+
+---
+
+### Admin Panel
+
+#### GET /admin
+
+Display admin dashboard.
+
+**Authentication**: Required (Admin role)
+
+**Response**: HTML page with users and DevBenches
+
+**Status Codes**:
+- `200`: Success
+- `403`: Access denied (not admin)
+- `302`: Redirect to `/login` if not authenticated
+
+---
+
+#### POST /admin/add-user
+
+Create a new user.
+
+**Authentication**: Required (Admin role)
+
+**Request Body**:
+```json
+{
+  "username": "john",
+  "email": "john@example.com",
+  "password": "password123"
+}
+```
+
+**Validation**:
+- Username must match pattern: `[a-zA-Z]+` (letters only)
+- Username must be unique
+- Email must be valid format
+- Password required
+
+**Response**:
+```json
+{
+  "success": true
+}
+```
+
+**Error Response**:
+```json
+{
+  "error": "Username already exists"
+}
+```
+
+**Status Codes**:
+- `200`: Success
+- `400`: Validation error
+- `500`: Database error
+
+---
+
+#### POST /admin/delete-user/:id
+
+Delete a user and all their DevBenches.
+
+**Authentication**: Required (Admin role)
+
+**Parameters**:
+- `id`: User ID (integer)
+
+**Response**:
+```json
+{
+  "success": true
+}
+```
+
+**Error Response**:
+```json
+{
+  "error": "Database error"
+}
+```
+
+**Status Codes**:
+- `200`: Success
+- `500`: Database error
+
+**Side Effects**:
+- Deletes all user's DevBenches
+- Deletes user record
+- Cannot delete admin users
+
+---
+
+#### POST /admin/reset-password/:id
+
+Reset user password.
+
+**Authentication**: Required (Admin role)
+
+**Parameters**:
+- `id`: User ID (integer)
+
+**Request Body**:
+```json
+{
+  "newPassword": "newpassword123"
+}
+```
+
+**Response**:
+```json
+{
+  "success": true
+}
+```
+
+**Error Response**:
+```json
+{
+  "error": "Database error"
+}
+```
+
+**Status Codes**:
+- `200`: Success
+- `500`: Database error
+
+**Side Effects**:
+- Updates user password (hashed with bcrypt)
+- Cannot reset admin passwords
+
+---
+
+### User Info
+
+#### GET /api/user-info
+
+Get current user information for WebSocket registration.
+
+**Authentication**: Required
+
+**Response**:
+```json
+{
+  "userId": 1,
+  "username": "admin",
+  "isAdmin": true
+}
+```
+
+**Status Codes**:
+- `200`: Success
+- `302`: Redirect to `/login` if not authenticated
+
+---
+
+## WebSocket API
+
+### Connection
+
+```javascript
+const ws = new WebSocket('ws://localhost:9090');
+```
+
+### Registration
+
+After connection, register with user ID:
+
+```javascript
+ws.send(JSON.stringify({
+  type: 'register',
+  userId: 1
+}));
+```
+
+### Message Types
+
+#### script_output
+
+Real-time output from provision script.
+
+```json
+{
+  "type": "script_output",
+  "devbenchId": 123,
+  "data": "Cloning VM...\n"
+}
+```
+
+#### script_complete
+
+Script execution completed.
+
+```json
+{
+  "type": "script_complete",
+  "devbenchId": 123,
+  "exitCode": 0
+}
+```
+
+#### status_update
+
+DevBench status changed.
+
+```json
+{
+  "type": "status_update",
+  "devbenchId": 123,
+  "status": "active"
+}
+```
+
+---
+
+## Error Responses
+
+### Standard Error Format
+
+```json
+{
+  "error": "Error message description"
+}
+```
+
+### Common HTTP Status Codes
+
+- `200`: Success
+- `302`: Redirect
+- `400`: Bad Request (validation error)
+- `401`: Unauthorized (not authenticated)
+- `403`: Forbidden (insufficient permissions)
+- `404`: Not Found
+- `500`: Internal Server Error
+
+---
+
+## Rate Limiting
+
+Currently not implemented. Consider adding rate limiting for production:
+
+- Login attempts: 5 per minute
+- DevBench creation: 10 per hour per user
+- API calls: 100 per minute per user
+
+---
+
+## Data Models
+
+### User
+
+```json
+{
+  "id": 1,
+  "username": "admin",
+  "email": "admin@example.com",
+  "password": "$2a$10$...", // bcrypt hash
+  "is_admin": 1,
+  "created_at": "2025-11-23T12:00:00.000Z"
+}
+```
+
+### DevBench
+
+```json
+{
+  "id": 1,
+  "user_id": 1,
+  "name": "test-vm",
+  "actual_name": "admin_test-vm",
+  "status": "active",
+  "ssh_info": "6004",
+  "vnc_info": "5004",
+  "created_at": "2025-11-23T12:00:00.000Z",
+  "updated_at": "2025-11-23T12:05:00.000Z"
+}
+```
+
+---
+
+## Examples
+
+### Create DevBench with cURL
+
+```bash
+# Login first to get session cookie
+curl -c cookies.txt -X POST http://localhost:9090/login \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "username=admin&password=admin123"
+
+# Create DevBench
+curl -b cookies.txt -X POST http://localhost:9090/create-devbench \
+  -H "Content-Type: application/json" \
+  -d '{"name":"test-vm"}'
+```
+
+### Check Status with cURL
+
+```bash
+curl -b cookies.txt http://localhost:9090/check-status/1
+```
+
+### Add User with cURL
+
+```bash
+curl -b cookies.txt -X POST http://localhost:9090/admin/add-user \
+  -H "Content-Type: application/json" \
+  -d '{
+    "username":"john",
+    "email":"john@example.com",
+    "password":"password123"
+  }'
+```
+
+### WebSocket with JavaScript
+
+```javascript
+// Connect
+const ws = new WebSocket('ws://localhost:9090');
+
+// Register
+ws.onopen = () => {
+  fetch('/api/user-info')
+    .then(res => res.json())
+    .then(data => {
+      ws.send(JSON.stringify({
+        type: 'register',
+        userId: data.userId
+      }));
+    });
+};
+
+// Listen for messages
+ws.onmessage = (event) => {
+  const message = JSON.parse(event.data);
+  console.log('Received:', message);
+  
+  if (message.type === 'script_output') {
+    // Update UI with script output
+    document.getElementById('log').textContent += message.data;
+  }
+};
+```
+
+---
+
+## Security Considerations
+
+### Authentication
+- Session-based authentication
+- HTTP-only cookies
+- Password hashing with bcrypt (10 rounds)
+
+### Authorization
+- Role-based access control (Admin/User)
+- Owner-only access to DevBenches
+- Admin-only routes protected
+
+### Input Validation
+- Username: Letters only
+- DevBench name: Alphanumeric, hyphens, underscores
+- SQL injection prevention: Parameterized queries
+- XSS prevention: EJS auto-escaping
+
+### Best Practices
+- Always use HTTPS in production
+- Change default admin password
+- Use strong session secret
+- Implement rate limiting
+- Add CSRF protection
+- Enable security headers
+
+---
+
+## Changelog
+
+### Version 1.0.0 (2025-11-23)
+- Initial API release
+- User authentication
+- DevBench management
+- Admin panel
+- WebSocket support
+- Help page
+- Dark theme support