ASF_tools/asf-cloud-server/TBM_devbench/docs/API.md

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:

{
  "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:

{
  "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:

{
  "name": "test-vm"
}

Validation:

• Name must match pattern: [a-zA-Z0-9_-]+
• Name must be unique for user

Response:

{
  "success": true,
  "devbenchId": 123
}

Error Response:

{
  "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:

{
  "success": true
}

Error Response:

{
  "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:

{
  "success": true
}

Error Response:

{
  "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:

{
  "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:

{
  "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:

{
  "success": true
}

Error Response:

{
  "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:

{
  "success": true
}

Error Response:

{
  "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:

{
  "newPassword": "newpassword123"
}

Response:

{
  "success": true
}

Error Response:

{
  "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:

{
  "userId": 1,
  "username": "admin",
  "isAdmin": true
}

Status Codes:

• 200: Success
• 302: Redirect to /login if not authenticated

---

WebSocket API

Connection

const ws = new WebSocket('ws://localhost:9090');

Registration

After connection, register with user ID:

ws.send(JSON.stringify({
  type: 'register',
  userId: 1
}));

Message Types

script_output

Real-time output from provision script.

{
  "type": "script_output",
  "devbenchId": 123,
  "data": "Cloning VM...\n"
}

script_complete

Script execution completed.

{
  "type": "script_complete",
  "devbenchId": 123,
  "exitCode": 0
}

status_update

DevBench status changed.

{
  "type": "status_update",
  "devbenchId": 123,
  "status": "active"
}

---

Error Responses

Standard Error Format

{
  "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

{
  "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

{
  "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

# 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

curl -b cookies.txt http://localhost:9090/check-status/1

Add User with cURL

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

// 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