@celilo/cli 0.1.0

package/src/api-clients/proxmox.ts

@@ -0,0 +1,655 @@
+/**
+ * Proxmox API Client
+ * Validates connection to Proxmox Virtual Environment
+ */
+
+import https from 'node:https';
+import type { TestResult } from '../types/infrastructure';
+
+export interface ProxmoxCredentials {
+  api_url: string;
+  api_token_id: string;
+  api_token_secret: string;
+}
+
+export interface ProxmoxProviderConfig {
+  default_target_node: string;
+  lxc_template: string;
+  storage: string;
+}
+
+interface ProxmoxApiResponse<T> {
+  data: T;
+}
+
+interface ProxmoxError {
+  success: false;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+type ProxmoxResult<T> = { success: true; data: T } | ProxmoxError;
+
+/**
+ * Make an authenticated API request to Proxmox
+ * Helper function for all Proxmox API calls
+ */
+async function makeProxmoxRequest<T>(
+  credentials: ProxmoxCredentials,
+  path: string,
+): Promise<ProxmoxResult<T>> {
+  return new Promise((resolve) => {
+    try {
+      const { api_url, api_token_id, api_token_secret } = credentials;
+      const authHeader = `PVEAPIToken=${api_token_id}=${api_token_secret}`;
+      const fullUrl = `${api_url}${path}`;
+      const url = new URL(fullUrl);
+
+      if (process.env.DEBUG) {
+        console.log(`[Proxmox] Request: ${fullUrl}`);
+      }
+
+      const agent = new https.Agent({
+        rejectUnauthorized: false,
+      });
+
+      const req = https.request(
+        {
+          hostname: url.hostname,
+          port: url.port || 443,
+          path: url.pathname,
+          method: 'GET',
+          headers: {
+            Authorization: authHeader,
+          },
+          agent,
+        },
+        (res) => {
+          let body = '';
+
+          res.on('data', (chunk) => {
+            body += chunk;
+          });
+
+          res.on('end', () => {
+            const statusCode = res.statusCode || 0;
+
+            if (statusCode === 401) {
+              resolve({
+                success: false,
+                message: 'Authentication failed - check API token credentials',
+                details: { status: statusCode },
+              });
+              return;
+            }
+
+            if (statusCode < 200 || statusCode >= 300) {
+              resolve({
+                success: false,
+                message: `API request failed with status ${statusCode}`,
+                details: { status: statusCode, response: body },
+              });
+              return;
+            }
+
+            try {
+              const data = JSON.parse(body) as ProxmoxApiResponse<T>;
+              resolve({ success: true, data: data.data });
+            } catch (error) {
+              resolve({
+                success: false,
+                message: 'Failed to parse API response',
+                details: { error: String(error), body },
+              });
+            }
+          });
+        },
+      );
+
+      req.on('error', (error) => {
+        resolve({
+          success: false,
+          message: `Connection error: ${error.message}`,
+          details: { error: String(error) },
+        });
+      });
+
+      req.end();
+    } catch (error) {
+      resolve({
+        success: false,
+        message: `Request failed: ${error instanceof Error ? error.message : String(error)}`,
+        details: { error: String(error) },
+      });
+    }
+  });
+}
+
+/**
+ * Check if a Proxmox node exists and is online
+ */
+async function checkNodeStatus(
+  credentials: ProxmoxCredentials,
+  nodeName: string,
+): Promise<ProxmoxResult<{ status: string }>> {
+  return makeProxmoxRequest(credentials, `/nodes/${nodeName}/status`);
+}
+
+/**
+ * List all nodes in the Proxmox cluster/standalone
+ */
+async function listNodes(
+  credentials: ProxmoxCredentials,
+): Promise<ProxmoxResult<Array<{ node: string; status: string; level?: string }>>> {
+  return makeProxmoxRequest(credentials, '/nodes');
+}
+
+/**
+ * Verify node name matches actual Proxmox configuration
+ * Returns actual node name and warns if mismatch
+ */
+async function verifyNodeName(
+  credentials: ProxmoxCredentials,
+  expectedNodeName: string,
+): Promise<ProxmoxResult<{ actual_node: string; matches: boolean }>> {
+  const nodesResult = await listNodes(credentials);
+
+  if (!nodesResult.success) {
+    return nodesResult;
+  }
+
+  const nodes = nodesResult.data;
+  const nodeNames = nodes.map((n) => n.node);
+
+  // Check if expected node exists
+  if (!nodeNames.includes(expectedNodeName)) {
+    return {
+      success: false,
+      message: `Node '${expectedNodeName}' not found in Proxmox. Available nodes: ${nodeNames.join(', ')}.\n\nPossible causes:\n  1. Wrong node name configured in Celilo\n  2. Node hostname doesn't match Proxmox registration\n  3. Node not part of this cluster\n\nTo fix:\n  1. Check actual node name: ssh root@<node-ip> 'hostname'\n  2. Update Celilo service to use correct node name\n  3. Or update Proxmox node hostname:\n     - hostnamectl set-hostname ${expectedNodeName}\n     - Update /etc/hosts: echo '<node-ip> ${expectedNodeName}' >> /etc/hosts\n     - Restart: systemctl restart pvedaemon pveproxy`,
+      details: {
+        expected: expectedNodeName,
+        available: nodeNames,
+      },
+    };
+  }
+
+  return {
+    success: true,
+    data: {
+      actual_node: expectedNodeName,
+      matches: true,
+    },
+  };
+}
+
+/**
+ * Check if storage exists on a node
+ */
+async function checkStorageStatus(
+  credentials: ProxmoxCredentials,
+  nodeName: string,
+  storageName: string,
+): Promise<ProxmoxResult<{ active: number; enabled: number }>> {
+  return makeProxmoxRequest(credentials, `/nodes/${nodeName}/storage/${storageName}/status`);
+}
+
+/**
+ * Check if an LXC template exists in storage
+ */
+async function checkTemplateExists(
+  credentials: ProxmoxCredentials,
+  nodeName: string,
+  storageName: string,
+  templateName: string,
+): Promise<ProxmoxResult<boolean>> {
+  const result = await makeProxmoxRequest<Array<{ volid: string; content: string }>>(
+    credentials,
+    `/nodes/${nodeName}/storage/${storageName}/content`,
+  );
+
+  if (!result.success) {
+    return result;
+  }
+
+  // Check if any volume matches the template name
+  const templateExists = result.data.some((item) => item.volid.includes(templateName));
+
+  return { success: true, data: templateExists };
+}
+
+/**
+ * Required permissions for Celilo to deploy containers
+ * These are the minimum permissions needed for Terraform/Ansible deployment
+ *
+ * Note: VM.Monitor was removed in Proxmox 9.0+
+ * VM.Audit now covers monitoring functionality
+ */
+const REQUIRED_PERMISSIONS = [
+  'VM.Allocate', // Create VMs/containers
+  'VM.Audit', // View VM status (includes monitoring in Proxmox 9+)
+  'VM.Config.CDROM',
+  'VM.Config.CPU',
+  'VM.Config.Disk',
+  'VM.Config.Memory',
+  'VM.Config.Network',
+  'VM.Config.Options',
+  'VM.PowerMgmt', // Start/stop VMs
+  'Datastore.AllocateSpace', // Allocate disk space
+  'SDN.Use', // Use software-defined networking
+];
+
+/**
+ * Check if API token has required permissions
+ * Returns list of missing permissions
+ */
+async function checkTokenPermissions(
+  credentials: ProxmoxCredentials,
+): Promise<ProxmoxResult<{ missing: string[]; granted: string[]; privilegeSeparation?: boolean }>> {
+  // Get permissions for the token
+  // Proxmox API returns permissions as nested object: { "/path": { "permission": 1 } }
+  const result = await makeProxmoxRequest<Record<string, Record<string, number>>>(
+    credentials,
+    '/access/permissions',
+  );
+
+  if (!result.success) {
+    return result;
+  }
+
+  if (process.env.DEBUG) {
+    console.log('[Proxmox] Permissions response:', JSON.stringify(result.data, null, 2));
+  }
+
+  // Collect all granted permissions from all paths
+  const grantedPermissions = new Set<string>();
+
+  for (const path of Object.keys(result.data)) {
+    const pathPermissions = result.data[path];
+    if (typeof pathPermissions === 'object' && pathPermissions !== null) {
+      for (const permission of Object.keys(pathPermissions)) {
+        grantedPermissions.add(permission);
+      }
+    }
+  }
+
+  if (process.env.DEBUG) {
+    console.log('[Proxmox] Granted permissions:', Array.from(grantedPermissions).sort());
+  }
+
+  // Check which required permissions are missing
+  const missing = REQUIRED_PERMISSIONS.filter((perm) => !grantedPermissions.has(perm));
+  const granted = REQUIRED_PERMISSIONS.filter((perm) => grantedPermissions.has(perm));
+
+  // Detect if token likely has privilege separation (if it has very few permissions)
+  // Tokens without privilege separation typically have 40-50+ permissions
+  // Tokens WITH separation typically have < 20 permissions (only what's explicitly granted)
+  const privilegeSeparation = grantedPermissions.size < 20;
+
+  return {
+    success: true,
+    data: {
+      missing,
+      granted,
+      privilegeSeparation,
+    },
+  };
+}
+
+/**
+ * Test connection to Proxmox API
+ * Verifies credentials, connectivity, and optionally checks node/storage/template configuration
+ */
+export async function testProxmoxConnection(
+  credentials: ProxmoxCredentials,
+  providerConfig?: ProxmoxProviderConfig,
+): Promise<TestResult> {
+  const checks: string[] = [];
+
+  // Step 1: Check version (basic connectivity and authentication)
+  const versionResult = await makeProxmoxRequest<{ version: string; release?: string }>(
+    credentials,
+    '/version',
+  );
+
+  if (!versionResult.success) {
+    return {
+      success: false,
+      message: versionResult.message,
+      details: versionResult.details,
+    };
+  }
+
+  checks.push(`Connected to Proxmox VE ${versionResult.data.version}`);
+
+  // Step 2: Check API token permissions
+  const permissionResult = await checkTokenPermissions(credentials);
+
+  if (!permissionResult.success) {
+    return {
+      success: false,
+      message: `Failed to check API token permissions: ${permissionResult.message}`,
+      details: permissionResult.details,
+    };
+  }
+
+  if (permissionResult.data.missing.length > 0) {
+    const missingList = permissionResult.data.missing.join(', ');
+    const hasSeparation = permissionResult.data.privilegeSeparation;
+
+    // Build fix instructions based on whether privilege separation is enabled
+    let fixInstructions: string;
+    if (hasSeparation) {
+      fixInstructions =
+        'To fix:\n  1. In Proxmox UI: Datacenter → Permissions → API Tokens\n  2. Delete the existing token\n  3. Create a new token with "Privilege Separation" UNCHECKED\n  4. Update Celilo with the new token credentials';
+    } else {
+      fixInstructions = `To fix:\n  1. In Proxmox UI: Datacenter → Permissions → Users\n  2. Edit the 'root@pam' user\n  3. Grant the missing permissions to the user\n  4. OR check if the token has explicit permission overrides that need updating`;
+    }
+
+    return {
+      success: false,
+      message: `API token is missing required permissions: ${missingList}\n\nRequired permissions:\n${REQUIRED_PERMISSIONS.map((p) => `  - ${p}`).join('\n')}\n\n${fixInstructions}`,
+      details: {
+        missing: permissionResult.data.missing,
+        granted: permissionResult.data.granted,
+        privilegeSeparation: hasSeparation,
+      },
+    };
+  }
+
+  checks.push('API token has all required permissions');
+
+  // If no providerConfig, return basic connectivity check
+  if (!providerConfig) {
+    return {
+      success: true,
+      message: checks.join('\n✓ '),
+      details: {
+        version: versionResult.data.version,
+        release: versionResult.data.release,
+        permissions: {
+          granted: permissionResult.data.granted,
+          privilegeSeparation: permissionResult.data.privilegeSeparation,
+        },
+      },
+    };
+  }
+
+  // Step 3: Verify node name matches Proxmox configuration
+  const nodeNameResult = await verifyNodeName(credentials, providerConfig.default_target_node);
+
+  if (!nodeNameResult.success) {
+    return {
+      success: false,
+      message: nodeNameResult.message,
+      details: nodeNameResult.details,
+    };
+  }
+
+  checks.push(`Node '${providerConfig.default_target_node}' found in cluster`);
+
+  // Step 4: Check node is online
+  const nodeResult = await checkNodeStatus(credentials, providerConfig.default_target_node);
+
+  if (!nodeResult.success) {
+    return {
+      success: false,
+      message: `Node '${providerConfig.default_target_node}' not found or not accessible`,
+      details: nodeResult.details,
+    };
+  }
+
+  checks.push(`Node '${providerConfig.default_target_node}' is online`);
+
+  // Step 5: Check storage is available
+  const storageResult = await checkStorageStatus(
+    credentials,
+    providerConfig.default_target_node,
+    providerConfig.storage,
+  );
+
+  if (!storageResult.success) {
+    return {
+      success: false,
+      message: `Storage '${providerConfig.storage}' not found or not accessible on node '${providerConfig.default_target_node}'`,
+      details: storageResult.details,
+    };
+  }
+
+  if (!storageResult.data.active || !storageResult.data.enabled) {
+    return {
+      success: false,
+      message: `Storage '${providerConfig.storage}' is not active or enabled`,
+      details: { active: storageResult.data.active, enabled: storageResult.data.enabled },
+    };
+  }
+
+  checks.push(`Storage '${providerConfig.storage}' is available`);
+
+  // Step 6: Check template exists
+  // Extract storage name and template filename from the full template path
+  // Format: "local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst"
+  const templateParts = providerConfig.lxc_template.split(':');
+  const templateStorage = templateParts[0] || providerConfig.storage;
+  const templateFilename = templateParts[1]?.split('/').pop() || providerConfig.lxc_template;
+
+  const templateResult = await checkTemplateExists(
+    credentials,
+    providerConfig.default_target_node,
+    templateStorage,
+    templateFilename,
+  );
+
+  if (!templateResult.success) {
+    return {
+      success: false,
+      message: `Failed to check template availability: ${templateResult.message}`,
+      details: templateResult.details,
+    };
+  }
+
+  if (!templateResult.data) {
+    return {
+      success: false,
+      message: `Template '${templateFilename}' not found in storage '${templateStorage}'`,
+      details: { template: providerConfig.lxc_template },
+    };
+  }
+
+  checks.push(`Template '${templateFilename}' found`);
+
+  // All checks passed
+  return {
+    success: true,
+    message: checks.join('\n✓ '),
+    details: {
+      version: versionResult.data.version,
+      node: providerConfig.default_target_node,
+      storage: providerConfig.storage,
+      template: templateFilename,
+      permissions: {
+        granted: permissionResult.data.granted,
+        privilegeSeparation: permissionResult.data.privilegeSeparation,
+      },
+    },
+  };
+}
+
+/**
+ * List all storage on a node
+ */
+export async function listNodeStorage(
+  credentials: ProxmoxCredentials,
+  nodeName: string,
+): Promise<
+  ProxmoxResult<Array<{ storage: string; content: string; active: number; enabled: number }>>
+> {
+  return makeProxmoxRequest(credentials, `/nodes/${nodeName}/storage`);
+}
+
+/**
+ * List available LXC templates in storage
+ */
+export async function listAvailableTemplates(
+  credentials: ProxmoxCredentials,
+  nodeName: string,
+  storageName: string,
+): Promise<ProxmoxResult<Array<{ volid: string; content: string; size: number }>>> {
+  return makeProxmoxRequest(
+    credentials,
+    `/nodes/${nodeName}/storage/${storageName}/content?content=vztmpl`,
+  );
+}
+
+/**
+ * Download an LXC template from Proxmox repository
+ * Returns task ID (UPID) for tracking download progress
+ */
+export async function downloadTemplate(
+  credentials: ProxmoxCredentials,
+  nodeName: string,
+  storageName: string,
+  templateUrl: string,
+): Promise<ProxmoxResult<string>> {
+  return new Promise((resolve) => {
+    try {
+      const { api_url, api_token_id, api_token_secret } = credentials;
+      const authHeader = `PVEAPIToken=${api_token_id}=${api_token_secret}`;
+      const fullUrl = `${api_url}/nodes/${nodeName}/storage/${storageName}/download-url`;
+      const url = new URL(fullUrl);
+
+      if (process.env.DEBUG) {
+        console.log(`[Proxmox] Download template: ${fullUrl}`);
+        console.log(`[Proxmox] Template URL: ${templateUrl}`);
+        console.log(`[Proxmox] Storage: ${storageName}`);
+      }
+
+      const agent = new https.Agent({
+        rejectUnauthorized: false,
+      });
+
+      // POST request with form data
+      // Note: Proxmox requires 'filename' parameter for download-url endpoint
+      const filename = templateUrl.split('/').pop() || 'template.tar.zst';
+      const postData = new URLSearchParams({
+        url: templateUrl,
+        content: 'vztmpl',
+        filename: filename,
+      }).toString();
+
+      const req = https.request(
+        {
+          hostname: url.hostname,
+          port: url.port || 443,
+          path: url.pathname,
+          method: 'POST',
+          headers: {
+            Authorization: authHeader,
+            'Content-Type': 'application/x-www-form-urlencoded',
+            'Content-Length': Buffer.byteLength(postData),
+          },
+          agent,
+        },
+        (res) => {
+          let body = '';
+
+          res.on('data', (chunk) => {
+            body += chunk;
+          });
+
+          res.on('end', () => {
+            const statusCode = res.statusCode || 0;
+
+            if (statusCode < 200 || statusCode >= 300) {
+              if (process.env.DEBUG || statusCode === 400) {
+                console.error(`[Proxmox] Download failed: ${body}`);
+              }
+              resolve({
+                success: false,
+                message: `Download request failed with status ${statusCode}: ${body}`,
+                details: { status: statusCode, response: body },
+              });
+              return;
+            }
+
+            try {
+              const data = JSON.parse(body) as ProxmoxApiResponse<string>;
+              resolve({ success: true, data: data.data });
+            } catch (error) {
+              resolve({
+                success: false,
+                message: 'Failed to parse download response',
+                details: { error: String(error), body },
+              });
+            }
+          });
+        },
+      );
+
+      req.on('error', (error) => {
+        resolve({
+          success: false,
+          message: `Download request failed: ${error.message}`,
+          details: { error: String(error) },
+        });
+      });
+
+      req.write(postData);
+      req.end();
+    } catch (error) {
+      resolve({
+        success: false,
+        message: `Download failed: ${error instanceof Error ? error.message : String(error)}`,
+        details: { error: String(error) },
+      });
+    }
+  });
+}
+
+/**
+ * Check status of a running task (UPID)
+ * Returns task status and completion percentage
+ */
+export async function checkTaskStatus(
+  credentials: ProxmoxCredentials,
+  nodeName: string,
+  upid: string,
+): Promise<ProxmoxResult<{ status: string; exitstatus?: string }>> {
+  // UPID needs to be URL-encoded
+  const encodedUpid = encodeURIComponent(upid);
+  return makeProxmoxRequest(credentials, `/nodes/${nodeName}/tasks/${encodedUpid}/status`);
+}
+
+/**
+ * Build template URL for downloading from Proxmox repository
+ */
+export function buildTemplateUrl(ubuntuVersion: string): string {
+  // Proxmox mirrors Ubuntu cloud images
+  // Format: http://download.proxmox.com/images/system/ubuntu-{version}-standard_{version}-1_amd64.tar.zst
+  return `http://download.proxmox.com/images/system/ubuntu-${ubuntuVersion}-standard_${ubuntuVersion}-1_amd64.tar.zst`;
+}
+
+/**
+ * Extract template filename from full template path
+ * Format: "local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst" -> "ubuntu-22.04-standard_22.04-1_amd64.tar.zst"
+ */
+export function extractTemplateFilename(templatePath: string): string {
+  const parts = templatePath.split(':');
+  const filename = parts[1]?.split('/').pop() || templatePath;
+  return filename;
+}
+
+/**
+ * Build full template path from components
+ */
+export function buildTemplatePath(storageName: string, ubuntuVersion: string): string {
+  const filename = `ubuntu-${ubuntuVersion}-standard_${ubuntuVersion}-1_amd64.tar.zst`;
+  return `${storageName}:vztmpl/${filename}`;
+}
+
+/**
+ * Build Proxmox API URL from IP address and port
+ * Automatically adds https:// and /api2/json
+ */
+export function buildProxmoxApiUrl(ipAddress: string, port = 8006): string {
+  return `https://${ipAddress}:${port}/api2/json`;
+}