@ebowwa/hetzner 0.1.0

package/ssh-keys.ts

@@ -0,0 +1,122 @@
+/**
+ * Hetzner SSH key operations
+ */
+
+import { z } from "zod";
+import type {
+  HetznerSSHKey,
+  CreateSSHKeyOptions,
+} from "./types.js";
+import type { HetznerClient } from "./client.js";
+import {
+  HetznerListSSHKeysResponseSchema,
+  HetznerGetSSHKeyResponseSchema,
+  HetznerCreateSSHKeyRequestSchema,
+  HetznerCreateSSHKeyResponseSchema,
+} from "./schemas.js";
+
+export class SSHKeyOperations {
+  constructor(private client: HetznerClient) {}
+
+  /**
+   * List all SSH keys
+   */
+  async list(): Promise<HetznerSSHKey[]> {
+    const response = await this.client.request<{ ssh_keys: HetznerSSHKey[] }>(
+      "/ssh_keys",
+    );
+
+    // Validate response with Zod
+    const validated = HetznerListSSHKeysResponseSchema.safeParse(response);
+    if (!validated.success) {
+      console.warn('Hetzner list SSH keys validation warning:', validated.error.issues);
+      return response.ssh_keys; // Return unvalidated data for backward compatibility
+    }
+
+    return validated.data.ssh_keys;
+  }
+
+  /**
+   * Get a specific SSH key by ID or name
+   */
+  async get(idOrName: number | string): Promise<HetznerSSHKey> {
+    const endpoint = typeof idOrName === 'number'
+      ? `/ssh_keys/${idOrName}`
+      : `/ssh_keys?name=${encodeURIComponent(idOrName)}`;
+
+    const response = await this.client.request<{ ssh_key: HetznerSSHKey }>(
+      endpoint,
+    );
+
+    // Validate response with Zod
+    const validated = HetznerGetSSHKeyResponseSchema.safeParse(response);
+    if (!validated.success) {
+      console.warn('Hetzner get SSH key validation warning:', validated.error.issues);
+      return response.ssh_key; // Return unvalidated data for backward compatibility
+    }
+
+    return validated.data.ssh_key;
+  }
+
+  /**
+   * Create a new SSH key
+   *
+   * @param options - SSH key creation options
+   * @returns Created SSH key
+   */
+  async create(options: CreateSSHKeyOptions): Promise<HetznerSSHKey> {
+    // Validate input with Zod
+    const validatedOptions = HetznerCreateSSHKeyRequestSchema.safeParse(options);
+    if (!validatedOptions.success) {
+      throw new Error(`Invalid SSH key options: ${validatedOptions.error.issues.map(i => i.message).join(', ')}`);
+    }
+
+    const body = {
+      name: validatedOptions.data.name,
+      public_key: validatedOptions.data.public_key,
+      ...(validatedOptions.data.labels && { labels: validatedOptions.data.labels }),
+    };
+
+    const response = await this.client.request<{ ssh_key: HetznerSSHKey }>(
+      "/ssh_keys",
+      {
+        method: "POST",
+        body: JSON.stringify(body),
+      }
+    );
+
+    // Validate response with Zod
+    const validated = HetznerCreateSSHKeyResponseSchema.safeParse(response);
+    if (!validated.success) {
+      console.warn('Hetzner create SSH key validation warning:', validated.error.issues);
+      return response.ssh_key; // Return unvalidated data for backward compatibility
+    }
+
+    return validated.data.ssh_key;
+  }
+
+  /**
+   * Delete an SSH key
+   *
+   * @param id - SSH key ID
+   */
+  async delete(id: number): Promise<void> {
+    await this.client.request(
+      `/ssh_keys/${id}`,
+      { method: "DELETE" }
+    );
+  }
+
+  /**
+   * Find an SSH key by name
+   * Returns undefined if not found
+   */
+  async findByName(name: string): Promise<HetznerSSHKey | undefined> {
+    try {
+      const keys = await this.list();
+      return keys.find(key => key.name === name);
+    } catch {
+      return undefined;
+    }
+  }
+}

package/ssh-setup.ts

@@ -0,0 +1,218 @@
+/**
+ * SSH Key Management for Hetzner
+ *
+ * This module ensures SSH keys are properly configured between:
+ * 1. Local machine (~/.ssh/)
+ * 2. Hetzner Cloud API
+ *
+ * PROBLEM:
+ * - Creating random keys in Hetzner doesn't work because we need the matching private key locally
+ * - Password auth is unreliable and often disabled
+ * - IP reuse causes known_hosts conflicts
+ *
+ * SOLUTION:
+ * - Always use existing local keys or create new key pairs
+ * - Upload public key to Hetzner, keep private key local
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import crypto from "crypto";
+import { SSHPresets, SSHFlags, buildSSHArgs, sshConfig } from "@codespaces/ssh";
+
+interface SSHKey {
+  id: number;
+  name: string;
+  fingerprint: string;
+  public_key: string;
+}
+
+interface LocalKeyPair {
+  name: string;
+  publicKey: string;
+  privateKeyPath: string;
+}
+
+const HETZNER_SSH_DIR = join(process.env.HOME || "", ".ssh");
+const HETZNER_KEY_PREFIX = "hetzner-codespaces";
+
+/**
+ * Get or create a local SSH key pair for Hetzner
+ * Returns the key name to use with Hetzner API
+ */
+export async function getOrCreateHetznerSSHKey(): Promise<LocalKeyPair> {
+  // Check for existing Hetzner keys
+  const existingKey = findExistingHetznerKey();
+  if (existingKey) {
+    console.log(`✓ Using existing SSH key: ${existingKey.name}`);
+    return existingKey;
+  }
+
+  // Create new key pair
+  console.log("Creating new SSH key pair for Hetzner...");
+  return createNewKeyPair();
+}
+
+/**
+ * Find existing Hetzner SSH key in local ~/.ssh/
+ */
+function findExistingHetznerKey(): LocalKeyPair | null {
+  const privateKeyPath = join(HETZNER_SSH_DIR, `${HETZNER_KEY_PREFIX}`);
+  const publicKeyPath = `${privateKeyPath}.pub`;
+
+  if (!existsSync(privateKeyPath) || !existsSync(publicKeyPath)) {
+    return null;
+  }
+
+  const publicKey = readFileSync(publicKeyPath, "utf-8").trim();
+
+  return {
+    name: HETZNER_KEY_PREFIX,
+    publicKey,
+    privateKeyPath,
+  };
+}
+
+/**
+ * Create a new SSH key pair for Hetzner
+ */
+function createNewKeyPair(): LocalKeyPair {
+  const keyName = `${HETZNER_KEY_PREFIX}-${Date.now()}`;
+  const privateKeyPath = join(HETZNER_SSH_DIR, keyName);
+  const publicKeyPath = `${privateKeyPath}.pub`;
+
+  // Generate new ed25519 key pair
+  try {
+    // Bun.spawn automatically escapes arguments to prevent shell injection
+    Bun.spawnSync(["ssh-keygen", "-t", "ed25519", "-f", privateKeyPath, "-N", "", "-C", keyName], {
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+
+    // Set proper permissions
+    Bun.spawnSync(["chmod", "600", privateKeyPath], { stdout: "ignore", stderr: "ignore" });
+    Bun.spawnSync(["chmod", "644", publicKeyPath], { stdout: "ignore", stderr: "ignore" });
+
+    const publicKey = readFileSync(publicKeyPath, "utf-8").trim();
+
+    console.log(`✓ Created new SSH key: ${keyName}`);
+    console.log(`  Private: ${privateKeyPath}`);
+    console.log(`  Public:  ${publicKeyPath}`);
+
+    return {
+      name: keyName,
+      publicKey,
+      privateKeyPath,
+    };
+  } catch (error) {
+    throw new Error(`Failed to create SSH key: ${error}`);
+  }
+}
+
+/**
+ * Ensure SSH key exists in Hetzner
+ * Returns the SSH key name to use when creating servers
+ */
+export async function ensureHetznerSSHKey(
+  hetznerAPI: (endpoint: string, method: string, body?: unknown) => Promise<Response>
+): Promise<string> {
+  // 1. Get or create local key pair
+  const localKey = await getOrCreateHetznerSSHKey();
+
+  // 2. Check if key exists in Hetzner
+  const existingKeys = await hetznerAPI("/ssh_keys", "GET", null)
+    .then((r) => r.json())
+    .then((data) => data.ssh_keys as SSHKey[]);
+
+  // 3. Find matching key by public key
+  const matchingKey = existingKeys.find((k) => k.public_key.trim() === localKey.publicKey.trim());
+
+  if (matchingKey) {
+    console.log(`✓ SSH key already exists in Hetzner: ${matchingKey.name} (${matchingKey.id})`);
+    return matchingKey.name; // Use existing key name
+  }
+
+  // 4. Upload new key to Hetzner
+  console.log(`Uploading SSH key to Hetzner: ${localKey.name}...`);
+  const createResponse = await hetznerAPI("/ssh_keys", "POST", {
+    name: localKey.name,
+    public_key: localKey.publicKey,
+  });
+
+  if (!createResponse.ok) {
+    const error = await createResponse.text();
+    throw new Error(`Failed to upload SSH key to Hetzner: ${error}`);
+  }
+
+  const createdKey = (await createResponse.json()) as SSHKey;
+  console.log(`✓ SSH key uploaded: ${createdKey.name} (${createdKey.id})`);
+
+  return createdKey.name;
+}
+
+/**
+ * Clear known_hosts entry for an IP (to fix IP reuse issues)
+ */
+export function clearKnownHosts(ip: string): void {
+  try {
+    // Bun.spawn automatically escapes arguments to prevent shell injection
+    Bun.spawnSync(["ssh-keygen", "-R", ip], { stdout: "ignore", stderr: "ignore" });
+    console.log(`✓ Cleared known_hosts entry for ${ip}`);
+  } catch {
+    // Ignore if entry doesn't exist
+  }
+}
+
+/**
+ * Test SSH connection to a server using typed flags
+ */
+export async function testSSHConnection(
+  ip: string,
+  privateKeyPath: string,
+  username: string = "root"
+): Promise<boolean> {
+  try {
+    // Build SSH args using typed flags
+    const flags = [
+      ...SSHPresets.default,
+      SSHFlags.identity(privateKeyPath),
+      sshConfig("ConnectTimeout", "10"),
+    ];
+
+    const sshArgs = buildSSHArgs(flags, ip, username);
+    sshArgs.push("echo", "connected");
+
+    // Bun.spawn automatically escapes arguments to prevent shell injection
+    const proc = Bun.spawn(sshArgs, {
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+
+    // Wait for process to complete with timeout
+    const timeout = setTimeout(() => proc.kill(), 15000);
+    await proc.exited;
+    clearTimeout(timeout);
+
+    return proc.exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Full workflow: Prepare SSH keys before creating servers
+ */
+export async function prepareSSHKeys(
+  hetznerAPI: (endpoint: string, method: string, body?: unknown) => Promise<Response>
+): Promise<{
+  sshKeyName: string;
+  privateKeyPath: string;
+}> {
+  const sshKeyName = await ensureHetznerSSHKey(hetznerAPI);
+  const localKey = await getOrCreateHetznerSSHKey();
+
+  return {
+    sshKeyName,
+    privateKeyPath: localKey.privateKeyPath,
+  };
+}

package/types.js

@@ -0,0 +1,96 @@
+/**
+ * Hetzner Cloud API types
+ */
+// ============================================================================
+// Import shared status enums
+// ============================================================================
+import { EnvironmentStatus, ActionStatus, VolumeStatus, } from "@ebowwa/codespaces-types/compile";
+// Re-export for convenience
+export { EnvironmentStatus, ActionStatus, VolumeStatus };
+// ============================================================================
+// Action Types
+// ============================================================================
+/**
+ * Action command types from Hetzner Cloud API
+ */
+export var ActionCommand;
+(function (ActionCommand) {
+    // Server actions
+    ActionCommand["CreateServer"] = "create_server";
+    ActionCommand["DeleteServer"] = "delete_server";
+    ActionCommand["StartServer"] = "start_server";
+    ActionCommand["StopServer"] = "stop_server";
+    ActionCommand["RebootServer"] = "reboot_server";
+    ActionCommand["ResetServer"] = "reset_server";
+    ActionCommand["ShutdownServer"] = "shutdown_server";
+    ActionCommand["Poweroff"] = "poweroff";
+    ActionCommand["ChangeServerType"] = "change_server_type";
+    ActionCommand["RebuildServer"] = "rebuild_server";
+    ActionCommand["EnableBackup"] = "enable_backup";
+    ActionCommand["DisableBackup"] = "disable_backup";
+    ActionCommand["CreateImage"] = "create_image";
+    ActionCommand["ChangeDnsPtr"] = "change_dns_ptr";
+    ActionCommand["AttachToNetwork"] = "attach_to_network";
+    ActionCommand["DetachFromNetwork"] = "detach_from_network";
+    ActionCommand["ChangeAliasIps"] = "change_alias_ips";
+    ActionCommand["EnableRescue"] = "enable_rescue";
+    ActionCommand["DisableRescue"] = "disable_rescue";
+    ActionCommand["ChangeProtection"] = "change_protection";
+    // Volume actions
+    ActionCommand["CreateVolume"] = "create_volume";
+    ActionCommand["DeleteVolume"] = "delete_volume";
+    ActionCommand["AttachVolume"] = "attach_volume";
+    ActionCommand["DetachVolume"] = "detach_volume";
+    ActionCommand["ResizeVolume"] = "resize_volume";
+    ActionCommand["VolumeChangeProtection"] = "volume_change_protection";
+    // Network actions
+    ActionCommand["AddSubnet"] = "add_subnet";
+    ActionCommand["DeleteSubnet"] = "delete_subnet";
+    ActionCommand["AddRoute"] = "add_route";
+    ActionCommand["DeleteRoute"] = "delete_route";
+    ActionCommand["ChangeIpRange"] = "change_ip_range";
+    ActionCommand["NetworkChangeProtection"] = "network_change_protection";
+    // Floating IP actions
+    ActionCommand["AssignFloatingIp"] = "assign_floating_ip";
+    ActionCommand["UnassignFloatingIp"] = "unassign_floating_ip";
+    ActionCommand["FloatingIpChangeDnsPtr"] = "floating_ip_change_dns_ptr";
+    ActionCommand["FloatingIpChangeProtection"] = "floating_ip_change_protection";
+    // Load Balancer actions
+    ActionCommand["CreateLoadBalancer"] = "create_load_balancer";
+    ActionCommand["DeleteLoadBalancer"] = "delete_load_balancer";
+    ActionCommand["AddTarget"] = "add_target";
+    ActionCommand["RemoveTarget"] = "remove_target";
+    ActionCommand["AddService"] = "add_service";
+    ActionCommand["UpdateService"] = "update_service";
+    ActionCommand["DeleteService"] = "delete_service";
+    ActionCommand["LoadBalancerAttachToNetwork"] = "load_balancer_attach_to_network";
+    ActionCommand["LoadBalancerDetachFromNetwork"] = "load_balancer_detach_from_network";
+    ActionCommand["ChangeAlgorithm"] = "change_algorithm";
+    ActionCommand["ChangeType"] = "change_type";
+    ActionCommand["LoadBalancerChangeProtection"] = "load_balancer_change_protection";
+    // Certificate actions
+    ActionCommand["IssueCertificate"] = "issue_certificate";
+    ActionCommand["RetryCertificate"] = "retry_certificate";
+    // Firewall actions
+    ActionCommand["SetFirewallRules"] = "set_firewall_rules";
+    ActionCommand["ApplyFirewall"] = "apply_firewall";
+    ActionCommand["RemoveFirewall"] = "remove_firewall";
+    ActionCommand["FirewallChangeProtection"] = "firewall_change_protection";
+    // Image actions
+    ActionCommand["ImageChangeProtection"] = "image_change_protection";
+})(ActionCommand || (ActionCommand = {}));
+/**
+ * Resource types that can be affected by actions
+ */
+export var ResourceType;
+(function (ResourceType) {
+    ResourceType["Server"] = "server";
+    ResourceType["Volume"] = "volume";
+    ResourceType["Network"] = "network";
+    ResourceType["FloatingIp"] = "floating_ip";
+    ResourceType["LoadBalancer"] = "load_balancer";
+    ResourceType["Certificate"] = "certificate";
+    ResourceType["Firewall"] = "firewall";
+    ResourceType["Image"] = "image";
+})(ResourceType || (ResourceType = {}));
+//# sourceMappingURL=types.js.map