teleportation-cli 1.0.0 → 1.0.2

package/lib/remote/providers/base-provider.js

@@ -0,0 +1,407 @@
+/**
+ * Base Provider Interface for Remote Development Environments
+ *
+ * All remote providers (Fly.io, Daytona, etc.) must implement this interface.
+ * This class provides common functionality for:
+ * - SSH key management
+ * - LivePort tunnel setup
+ * - Secret storage and retrieval
+ * - Resource cleanup
+ *
+ * @abstract
+ */
+
+export class BaseProvider {
+  /**
+   * Initialize the base provider
+   * @param {Object} config - Provider configuration
+   * @param {VaultClient} config.vaultClient - Mech Vault client instance
+   * @param {LivePortClient} config.livePortClient - LivePort client instance
+   * @param {Object} [config.validationRules] - Custom validation rules for provider
+   */
+  constructor(config) {
+    if (!config) {
+      throw new Error('Provider config is required');
+    }
+    if (!config.vaultClient) {
+      throw new Error('VaultClient is required in provider config');
+    }
+    if (!config.livePortClient) {
+      throw new Error('LivePortClient is required in provider config');
+    }
+
+    this.config = config;
+    this.vaultClient = config.vaultClient;
+    this.livePortClient = config.livePortClient;
+    this.validationRules = config.validationRules || {};
+  }
+
+  /**
+   * Create a remote machine/workspace
+   *
+   * @abstract
+   * @param {Object} sessionConfig - Session configuration
+   * @param {string} sessionConfig.sessionId - Unique session identifier
+   * @param {string} sessionConfig.repoUrl - Git repository URL
+   * @param {string} [sessionConfig.branch] - Git branch to checkout
+   * @param {string} sessionConfig.relayApiUrl - Relay API endpoint
+   * @param {string} sessionConfig.relayApiKey - Relay API key
+   * @param {string} sessionConfig.githubToken - GitHub personal access token
+   * @param {string} [sessionConfig.mechApiKey] - Mech API key for router
+   * @param {Object} [sessionConfig.additionalSecrets] - Additional secrets to store
+   * @returns {Promise<Object>} Machine details
+   * @returns {string} return.machineId - Unique machine identifier
+   * @returns {string} return.sshHost - SSH hostname
+   * @returns {number} return.sshPort - SSH port
+   * @returns {string} return.tunnelUrl - LivePort tunnel URL
+   * @returns {string} return.namespace - Vault namespace for secrets
+   * @returns {string[]} return.secretIds - Array of stored secret IDs
+   * @returns {string} return.sshKeyId - SSH key ID in Vault
+   * @returns {string} return.bridgeKeyId - LivePort bridge key ID
+   * @throws {Error} If machine creation fails
+   */
+  async createMachine(sessionConfig) {
+    throw new Error('createMachine must be implemented');
+  }
+
+  /**
+   * Destroy the remote machine/workspace
+   *
+   * @abstract
+   * @param {string} machineId - Machine identifier
+   * @returns {Promise<boolean>} True if destroyed successfully
+   * @throws {Error} If machine destruction fails
+   */
+  async destroyMachine(machineId) {
+    throw new Error('destroyMachine must be implemented');
+  }
+
+  /**
+   * Get machine status
+   *
+   * @abstract
+   * @param {string} machineId - Machine identifier
+   * @returns {Promise<Object>} Machine status
+   * @returns {string} return.status - Machine status (running, stopped, error)
+   * @returns {string} [return.ip] - Machine IP address
+   * @returns {string} [return.uptime] - Machine uptime
+   * @throws {Error} If status retrieval fails
+   */
+  async getMachineStatus(machineId) {
+    throw new Error('getMachineStatus must be implemented');
+  }
+
+  /**
+   * Execute command on remote machine
+   *
+   * @abstract
+   * @param {string} machineId - Machine identifier
+   * @param {string} command - Command to execute
+   * @returns {Promise<Object>} Command execution result
+   * @returns {string} return.stdout - Standard output
+   * @returns {string} return.stderr - Standard error
+   * @returns {number} return.exitCode - Exit code
+   * @throws {Error} If command execution fails
+   */
+  async executeCommand(machineId, command) {
+    throw new Error('executeCommand must be implemented');
+  }
+
+  /**
+   * Get machine logs
+   *
+   * @abstract
+   * @param {string} machineId - Machine identifier
+   * @param {Object} [options] - Log retrieval options
+   * @param {number} [options.tail] - Number of lines to retrieve
+   * @param {boolean} [options.follow] - Stream logs continuously
+   * @returns {Promise<Object>} Log data
+   * @returns {Array<string>} return.logs - Array of log lines
+   * @throws {Error} If log retrieval fails
+   */
+  async getLogs(machineId, options = {}) {
+    throw new Error('getLogs must be implemented');
+  }
+
+  /**
+   * Validate session configuration before machine creation
+   *
+   * @protected
+   * @param {Object} sessionConfig - Session configuration to validate
+   * @throws {Error} If validation fails
+   */
+  _validateSessionConfig(sessionConfig) {
+    if (!sessionConfig) {
+      throw new Error('Session config is required');
+    }
+
+    const requiredFields = ['sessionId', 'repoUrl', 'relayApiUrl', 'relayApiKey'];
+    for (const field of requiredFields) {
+      if (!sessionConfig[field]) {
+        throw new Error(`Session config missing required field: ${field}`);
+      }
+    }
+
+    // Validate sessionId format
+    if (!/^[a-zA-Z0-9_-]+$/.test(sessionConfig.sessionId)) {
+      throw new Error('Invalid sessionId: must contain only alphanumeric characters, dashes, and underscores');
+    }
+
+    // Validate repoUrl format and hostname
+    this._validateRepoUrl(sessionConfig.repoUrl);
+  }
+
+  /**
+   * Validate repository URL format and hostname
+   *
+   * @protected
+   * @param {string} repoUrl - Repository URL to validate
+   * @throws {Error} If URL is invalid or hostname not allowed
+   */
+  _validateRepoUrl(repoUrl) {
+    let hostname;
+
+    try {
+      if (repoUrl.startsWith('http://') || repoUrl.startsWith('https://')) {
+        // Parse HTTP(S) URLs
+        const url = new URL(repoUrl);
+        hostname = url.hostname;
+      } else if (repoUrl.startsWith('git@')) {
+        // Parse git@github.com:user/repo.git format
+        const match = repoUrl.match(/^git@([^:]+):(.+)$/);
+        if (!match) {
+          throw new Error('Invalid git URL format. Expected: git@hostname:user/repo.git');
+        }
+        hostname = match[1];
+      } else {
+        throw new Error('Invalid repoUrl: must start with http://, https://, or git@');
+      }
+
+      // Validate against allowed Git hosts
+      const allowedHosts = this.validationRules.allowedGitHosts || [
+        'github.com',
+        'gitlab.com',
+        'bitbucket.org',
+        'git.sr.ht', // SourceHut
+        'codeberg.org',
+      ];
+
+      if (!allowedHosts.includes(hostname)) {
+        throw new Error(`Git host not allowed: ${hostname}. Allowed hosts: ${allowedHosts.join(', ')}`);
+      }
+    } catch (error) {
+      if (error.message.includes('Invalid URL')) {
+        throw new Error(`Invalid repoUrl format: ${error.message}`);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Validate machine ID format
+   *
+   * @protected
+   * @param {string} machineId - Machine identifier to validate
+   * @throws {Error} If validation fails
+   */
+  _validateMachineId(machineId) {
+    if (!machineId || typeof machineId !== 'string' || machineId.trim() === '') {
+      throw new Error('Invalid machineId: must be a non-empty string');
+    }
+  }
+
+  /**
+   * Setup SSH access to the machine
+   *
+   * Generates an ED25519 SSH key pair via Vault and returns the credentials.
+   *
+   * @protected
+   * @param {string} machineId - Machine identifier
+   * @param {string} namespace - Vault namespace for the key
+   * @returns {Promise<Object>} SSH key details
+   * @returns {string} return.keyId - Vault secret ID for the SSH key
+   * @returns {string} return.publicKey - SSH public key
+   * @returns {string} return.privateKey - SSH private key
+   * @returns {string} return.fingerprint - SSH key fingerprint
+   * @throws {Error} If SSH key generation fails
+   */
+  async _setupSSHAccess(machineId, namespace) {
+    try {
+      // Generate SSH key via Vault
+      const sshKey = await this.vaultClient.generateSSHKey('ed25519', {
+        namespace,
+        name: `machine-${machineId}`,
+        metadata: {
+          machineId,
+          provider: this.constructor.name,
+          createdAt: new Date().toISOString(),
+        },
+      });
+
+      return {
+        keyId: sshKey.secretId,
+        publicKey: sshKey.publicKey,
+        privateKey: sshKey.privateKey,
+        fingerprint: sshKey.fingerprint,
+      };
+    } catch (error) {
+      throw new Error(`Failed to setup SSH access: ${error.message}`);
+    }
+  }
+
+  /**
+   * Setup LivePort tunnel for the machine
+   *
+   * Creates a bridge key and generates tunnel configuration for the remote machine.
+   *
+   * @protected
+   * @param {string} sessionId - Session identifier
+   * @param {string} machineId - Machine identifier
+   * @returns {Promise<Object>} Tunnel details
+   * @returns {string} return.bridgeKey - LivePort bridge key
+   * @returns {string} return.keyId - Bridge key ID
+   * @returns {string} return.tunnelUrl - Public tunnel URL
+   * @returns {string} return.tunnelCommand - Command to run on remote machine
+   * @throws {Error} If tunnel setup fails
+   */
+  async _setupTunnel(sessionId, machineId) {
+    try {
+      // Create bridge key for this session
+      const bridgeKey = await this.livePortClient.createBridgeKey({
+        name: `session-${sessionId}`,
+        metadata: {
+          sessionId,
+          machineId,
+          provider: this.constructor.name,
+        },
+      });
+
+      // Get the tunnel command to run on remote machine
+      const tunnelCmd = this.livePortClient.getTunnelCommand(bridgeKey.key, {
+        port: 3000, // Default port for remote services
+      });
+
+      return {
+        bridgeKey: bridgeKey.key,
+        keyId: bridgeKey.keyId,
+        tunnelUrl: this.livePortClient.getTunnelUrl(sessionId),
+        tunnelCommand: tunnelCmd,
+      };
+    } catch (error) {
+      throw new Error(`Failed to setup LivePort tunnel: ${error.message}`);
+    }
+  }
+
+  /**
+   * Store secrets for the remote machine
+   *
+   * Stores multiple secrets in Vault under the session namespace.
+   *
+   * @protected
+   * @param {string} namespace - Vault namespace
+   * @param {Object} secrets - Key-value pairs of secrets to store
+   * @returns {Promise<string[]>} Array of secret IDs
+   * @throws {Error} If secret storage fails
+   */
+  async _storeSecrets(namespace, secrets) {
+    const secretIds = [];
+
+    try {
+      for (const [name, value] of Object.entries(secrets)) {
+        const result = await this.vaultClient.storeSecret(
+          namespace,
+          name,
+          value,
+          {
+            description: `Secret for remote session: ${name}`,
+            tags: ['teleportation', 'remote'],
+          }
+        );
+
+        secretIds.push(result.secretId);
+      }
+
+      return secretIds;
+    } catch (error) {
+      throw new Error(`Failed to store secrets: ${error.message}`);
+    }
+  }
+
+  /**
+   * Export environment file for the remote machine
+   *
+   * Exports all secrets in the namespace as a .env file format.
+   *
+   * @protected
+   * @param {string} namespace - Vault namespace
+   * @returns {Promise<string>} Environment file content
+   * @throws {Error} If export fails
+   */
+  async _exportEnvFile(namespace) {
+    try {
+      return await this.vaultClient.exportEnvFile(namespace, 'env');
+    } catch (error) {
+      throw new Error(`Failed to export env file: ${error.message}`);
+    }
+  }
+
+  /**
+   * Cleanup resources after session ends
+   *
+   * Removes all session resources: bridge keys, SSH keys, and stored secrets.
+   * Failures are collected and returned but don't throw to ensure cleanup continues.
+   *
+   * @protected
+   * @param {string} namespace - Vault namespace to clean up
+   * @param {string} [bridgeKeyId] - LivePort bridge key ID to revoke
+   * @param {string} [sshKeyId] - SSH key ID to delete
+   * @returns {Promise<Object>} Cleanup result with success status and errors
+   * @returns {boolean} return.success - True if all operations succeeded
+   * @returns {string[]} return.errors - Array of error messages (empty if successful)
+   */
+  async _cleanup(namespace, bridgeKeyId, sshKeyId) {
+    const errors = [];
+
+    // Revoke LivePort bridge key
+    if (bridgeKeyId) {
+      try {
+        await this.livePortClient.revokeBridgeKey(bridgeKeyId);
+      } catch (error) {
+        errors.push(`Failed to revoke bridge key: ${error.message}`);
+      }
+    }
+
+    // Delete SSH key from vault
+    if (sshKeyId) {
+      try {
+        await this.vaultClient.deleteSecret(sshKeyId);
+      } catch (error) {
+        errors.push(`Failed to delete SSH key: ${error.message}`);
+      }
+    }
+
+    // Delete all secrets in the namespace
+    try {
+      const secrets = await this.vaultClient.listSecrets(namespace);
+      for (const secret of secrets.data || []) {
+        try {
+          await this.vaultClient.deleteSecret(secret.secretId);
+        } catch (error) {
+          errors.push(`Failed to delete secret ${secret.secretId}: ${error.message}`);
+        }
+      }
+    } catch (error) {
+      errors.push(`Failed to list secrets: ${error.message}`);
+    }
+
+    // Log warnings if there were errors
+    if (errors.length > 0) {
+      console.warn('Cleanup encountered errors:', errors.join('; '));
+    }
+
+    return {
+      success: errors.length === 0,
+      errors,
+    };
+  }
+}