@ebowwa/hetzner 0.1.0

package/bootstrap/ssh-hardening.js

@@ -0,0 +1,182 @@
+/**
+ * SSH Hardening Cloud-Init Components
+ *
+ * Composable cloud-init blocks for securing sshd on new servers.
+ * Includes: hardened sshd config, fail2ban, and health monitoring.
+ *
+ * Background: Hetzner public IPs get brute-forced constantly (~5k failed SSH
+ * logins per 24h observed on genesis). Without hardening, the default sshd
+ * MaxStartups (10:30:100) gets overwhelmed and legitimate connections time out
+ * with "Timed out while waiting for handshake".
+ *
+ * This module is imported by both cloud-init.ts (seed/worker nodes) and
+ * genesis.ts (control plane) so every new server gets hardened at first boot.
+ *
+ * Three composable functions return cloud-init line arrays for splicing into
+ * the appropriate YAML sections:
+ *   - sshdHardeningPackages()    → packages: section
+ *   - sshdHardeningWriteFiles()  → write_files: section
+ *   - sshdHardeningRunCmd()      → runcmd: section
+ */
+/**
+ * Packages required for SSH hardening.
+ * Returns cloud-init YAML lines for the `packages:` section.
+ *
+ * - fail2ban: bans IPs after repeated failed SSH attempts (3 tries → 1hr ban)
+ */
+export function sshdHardeningPackages() {
+    return [
+        "  - fail2ban",
+    ];
+}
+/**
+ * Files to write at first boot for SSH hardening.
+ * Returns cloud-init YAML lines for the `write_files:` section.
+ *
+ * Drops 5 files onto the server:
+ *
+ * 1. /etc/ssh/sshd_config.d/hardened.conf
+ *    - Disables password auth entirely (key-only)
+ *    - Raises MaxStartups from default 10:30:100 → 20:50:60 so brute-force
+ *      traffic doesn't starve legitimate connections
+ *    - Reduces LoginGraceTime from 2min → 30s (attackers hold slots open)
+ *    - Limits MaxAuthTries to 3 per connection
+ *    - Enables keepalive (30s interval, 3 missed = disconnect)
+ *
+ * 2. /etc/fail2ban/jail.local
+ *    - Monitors sshd via systemd journal
+ *    - Bans IP for 1 hour after 3 failures within 10 minutes
+ *    - Uses nftables (Ubuntu 24.04 default firewall backend)
+ *
+ * 3. /opt/monitoring/sshd-health.sh
+ *    - Collects sshd + fail2ban + system metrics into JSON
+ *    - Writes to /var/log/sshd-health.json (read by the app via SSH)
+ *    - Auto-restarts sshd if it detects it's down
+ *
+ * 4. /etc/systemd/system/sshd-health.service (oneshot runner)
+ * 5. /etc/systemd/system/sshd-health.timer (runs every 60 seconds)
+ */
+export function sshdHardeningWriteFiles() {
+    const lines = [];
+    // 1. Hardened sshd config — dropped into sshd_config.d/ so it overrides defaults
+    //    without touching the main sshd_config file
+    lines.push("  # Hardened SSH configuration");
+    lines.push("  - path: /etc/ssh/sshd_config.d/hardened.conf");
+    lines.push("    owner: root:root");
+    lines.push("    permissions: '0644'");
+    lines.push("    content: |");
+    lines.push("      # Hardened SSH config - applied via cloud-init");
+    lines.push("      PasswordAuthentication no");
+    lines.push("      PermitEmptyPasswords no");
+    lines.push("      KbdInteractiveAuthentication no");
+    lines.push("      PermitRootLogin prohibit-password");
+    lines.push("      LoginGraceTime 30");
+    lines.push("      MaxStartups 20:50:60");
+    lines.push("      ClientAliveInterval 30");
+    lines.push("      ClientAliveCountMax 3");
+    lines.push("      MaxAuthTries 3");
+    lines.push("");
+    // 2. fail2ban jail — 3 failed attempts in 10min = 1hr ban via nftables
+    lines.push("  # fail2ban SSH jail configuration");
+    lines.push("  - path: /etc/fail2ban/jail.local");
+    lines.push("    owner: root:root");
+    lines.push("    permissions: '0644'");
+    lines.push("    content: |");
+    lines.push("      [sshd]");
+    lines.push("      enabled = true");
+    lines.push("      port = ssh");
+    lines.push("      backend = systemd");
+    lines.push("      maxretry = 3");
+    lines.push("      findtime = 600");
+    lines.push("      bantime = 3600");
+    lines.push("      banaction = nftables-multiport");
+    lines.push("");
+    // 3. Health monitoring script — collects sshd/fail2ban/system stats into JSON
+    //    Output at /var/log/sshd-health.json is read by the app's collectSSHDHealth()
+    //    function (src/lib/metrics.ts) every 5 minutes via SSH
+    lines.push("  # sshd health monitoring script");
+    lines.push("  - path: /opt/monitoring/sshd-health.sh");
+    lines.push("    owner: root:root");
+    lines.push("    permissions: '0755'");
+    lines.push("    content: |");
+    lines.push("      #!/bin/bash");
+    lines.push("      set -euo pipefail");
+    lines.push("      LOGFILE=\"/var/log/sshd-health.json\"");
+    lines.push("      sshd_active=$(systemctl is-active ssh 2>/dev/null || echo \"inactive\")");
+    lines.push("      sshd_pid=$(pgrep -x sshd | head -1 || echo \"0\")");
+    lines.push("      f2b_active=$(systemctl is-active fail2ban 2>/dev/null || echo \"inactive\")");
+    lines.push("      f2b_banned=$(fail2ban-client status sshd 2>/dev/null | grep \"Currently banned\" | awk '{print $NF}' || echo \"0\")");
+    lines.push("      f2b_total=$(fail2ban-client status sshd 2>/dev/null | grep \"Total banned\" | awk '{print $NF}' || echo \"0\")");
+    lines.push("      failed_1h=$(journalctl -u ssh --since \"1 hour ago\" --no-pager 2>/dev/null | grep -c \"Failed\" || true)");
+    lines.push("      failed_24h=$(journalctl -u ssh --since \"24 hours ago\" --no-pager 2>/dev/null | grep -c \"Failed\" || true)");
+    lines.push("      active_connections=$(ss -tnp | grep -c \":22 \" || echo \"0\")");
+    lines.push("      uptime_seconds=$(awk '{print int($1)}' /proc/uptime)");
+    lines.push("      load=$(awk '{print $1}' /proc/loadavg)");
+    lines.push("      mem_used_pct=$(free | awk '/Mem:/{printf \"%.1f\", $3/$2*100}')");
+    lines.push("      timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)");
+    lines.push("      cat > \"$LOGFILE\" <<HEALTHEOF");
+    lines.push("      {");
+    lines.push("        \"timestamp\": \"$timestamp\",");
+    lines.push("        \"sshd\": { \"active\": \"$sshd_active\", \"pid\": $sshd_pid },");
+    lines.push("        \"fail2ban\": { \"active\": \"$f2b_active\", \"currently_banned\": $f2b_banned, \"total_banned\": $f2b_total },");
+    lines.push("        \"connections\": { \"active\": $active_connections, \"failed_1h\": $failed_1h, \"failed_24h\": $failed_24h },");
+    lines.push("        \"system\": { \"uptime_seconds\": $uptime_seconds, \"load\": $load, \"memory_used_pct\": $mem_used_pct }");
+    lines.push("      }");
+    lines.push("      HEALTHEOF");
+    lines.push("      if [ \"$sshd_active\" != \"active\" ]; then");
+    lines.push("        logger -t sshd-health -p auth.crit \"ALERT: sshd is $sshd_active\"");
+    lines.push("        systemctl start ssh 2>/dev/null || logger -t sshd-health -p auth.crit \"FAILED to restart sshd\"");
+    lines.push("      fi");
+    lines.push("");
+    // 4. Systemd oneshot service — wraps the health script for timer-based execution
+    lines.push("  # sshd health check systemd service");
+    lines.push("  - path: /etc/systemd/system/sshd-health.service");
+    lines.push("    owner: root:root");
+    lines.push("    permissions: '0644'");
+    lines.push("    content: |");
+    lines.push("      [Unit]");
+    lines.push("      Description=sshd health check");
+    lines.push("      After=ssh.service");
+    lines.push("      [Service]");
+    lines.push("      Type=oneshot");
+    lines.push("      ExecStart=/opt/monitoring/sshd-health.sh");
+    lines.push("");
+    // 5. Systemd timer — fires the health check every 60 seconds, starting 30s after boot
+    lines.push("  # sshd health check timer (every 60s)");
+    lines.push("  - path: /etc/systemd/system/sshd-health.timer");
+    lines.push("    owner: root:root");
+    lines.push("    permissions: '0644'");
+    lines.push("    content: |");
+    lines.push("      [Unit]");
+    lines.push("      Description=Run sshd health check every minute");
+    lines.push("      [Timer]");
+    lines.push("      OnBootSec=30");
+    lines.push("      OnUnitActiveSec=60");
+    lines.push("      [Install]");
+    lines.push("      WantedBy=timers.target");
+    lines.push("");
+    return lines;
+}
+/**
+ * Commands to activate all SSH hardening services at first boot.
+ * Returns cloud-init YAML lines for the `runcmd:` section.
+ *
+ * Order matters:
+ *   1. Create /opt/monitoring dir (health script target)
+ *   2. Reload sshd to pick up hardened.conf (fallback: full restart)
+ *   3. Enable + start fail2ban (reads jail.local immediately)
+ *   4. Reload systemd to pick up the health service/timer units
+ *   5. Enable + start the health timer (begins 60s monitoring loop)
+ */
+export function sshdHardeningRunCmd() {
+    const lines = [];
+    lines.push("  # SSH hardening: reload sshd, enable fail2ban and health monitoring");
+    lines.push("  - mkdir -p /opt/monitoring");
+    lines.push("  - systemctl reload ssh || systemctl restart ssh");
+    lines.push("  - systemctl enable --now fail2ban");
+    lines.push("  - systemctl daemon-reload");
+    lines.push("  - systemctl enable --now sshd-health.timer");
+    lines.push("");
+    return lines;
+}
+//# sourceMappingURL=ssh-hardening.js.map

package/bootstrap/ssh-hardening.ts

@@ -0,0 +1,192 @@
+/**
+ * SSH Hardening Cloud-Init Components
+ *
+ * Composable cloud-init blocks for securing sshd on new servers.
+ * Includes: hardened sshd config, fail2ban, and health monitoring.
+ *
+ * Background: Hetzner public IPs get brute-forced constantly (~5k failed SSH
+ * logins per 24h observed on genesis). Without hardening, the default sshd
+ * MaxStartups (10:30:100) gets overwhelmed and legitimate connections time out
+ * with "Timed out while waiting for handshake".
+ *
+ * This module is imported by both cloud-init.ts (seed/worker nodes) and
+ * genesis.ts (control plane) so every new server gets hardened at first boot.
+ *
+ * Three composable functions return cloud-init line arrays for splicing into
+ * the appropriate YAML sections:
+ *   - sshdHardeningPackages()    → packages: section
+ *   - sshdHardeningWriteFiles()  → write_files: section
+ *   - sshdHardeningRunCmd()      → runcmd: section
+ */
+
+/**
+ * Packages required for SSH hardening.
+ * Returns cloud-init YAML lines for the `packages:` section.
+ *
+ * - fail2ban: bans IPs after repeated failed SSH attempts (3 tries → 1hr ban)
+ */
+export function sshdHardeningPackages(): string[] {
+  return [
+    "  - fail2ban",
+  ];
+}
+
+/**
+ * Files to write at first boot for SSH hardening.
+ * Returns cloud-init YAML lines for the `write_files:` section.
+ *
+ * Drops 5 files onto the server:
+ *
+ * 1. /etc/ssh/sshd_config.d/hardened.conf
+ *    - Disables password auth entirely (key-only)
+ *    - Raises MaxStartups from default 10:30:100 → 20:50:60 so brute-force
+ *      traffic doesn't starve legitimate connections
+ *    - Reduces LoginGraceTime from 2min → 30s (attackers hold slots open)
+ *    - Limits MaxAuthTries to 3 per connection
+ *    - Enables keepalive (30s interval, 3 missed = disconnect)
+ *
+ * 2. /etc/fail2ban/jail.local
+ *    - Monitors sshd via systemd journal
+ *    - Bans IP for 1 hour after 3 failures within 10 minutes
+ *    - Uses nftables (Ubuntu 24.04 default firewall backend)
+ *
+ * 3. /opt/monitoring/sshd-health.sh
+ *    - Collects sshd + fail2ban + system metrics into JSON
+ *    - Writes to /var/log/sshd-health.json (read by the app via SSH)
+ *    - Auto-restarts sshd if it detects it's down
+ *
+ * 4. /etc/systemd/system/sshd-health.service (oneshot runner)
+ * 5. /etc/systemd/system/sshd-health.timer (runs every 60 seconds)
+ */
+export function sshdHardeningWriteFiles(): string[] {
+  const lines: string[] = [];
+
+  // 1. Hardened sshd config — dropped into sshd_config.d/ so it overrides defaults
+  //    without touching the main sshd_config file
+  lines.push("  # Hardened SSH configuration");
+  lines.push("  - path: /etc/ssh/sshd_config.d/hardened.conf");
+  lines.push("    owner: root:root");
+  lines.push("    permissions: '0644'");
+  lines.push("    content: |");
+  lines.push("      # Hardened SSH config - applied via cloud-init");
+  lines.push("      PasswordAuthentication no");
+  lines.push("      PermitEmptyPasswords no");
+  lines.push("      KbdInteractiveAuthentication no");
+  lines.push("      PermitRootLogin prohibit-password");
+  lines.push("      LoginGraceTime 30");
+  lines.push("      MaxStartups 20:50:60");
+  lines.push("      ClientAliveInterval 30");
+  lines.push("      ClientAliveCountMax 3");
+  lines.push("      MaxAuthTries 3");
+  lines.push("");
+
+  // 2. fail2ban jail — 3 failed attempts in 10min = 1hr ban via nftables
+  lines.push("  # fail2ban SSH jail configuration");
+  lines.push("  - path: /etc/fail2ban/jail.local");
+  lines.push("    owner: root:root");
+  lines.push("    permissions: '0644'");
+  lines.push("    content: |");
+  lines.push("      [sshd]");
+  lines.push("      enabled = true");
+  lines.push("      port = ssh");
+  lines.push("      backend = systemd");
+  lines.push("      maxretry = 3");
+  lines.push("      findtime = 600");
+  lines.push("      bantime = 3600");
+  lines.push("      banaction = nftables-multiport");
+  lines.push("");
+
+  // 3. Health monitoring script — collects sshd/fail2ban/system stats into JSON
+  //    Output at /var/log/sshd-health.json is read by the app's collectSSHDHealth()
+  //    function (src/lib/metrics.ts) every 5 minutes via SSH
+  lines.push("  # sshd health monitoring script");
+  lines.push("  - path: /opt/monitoring/sshd-health.sh");
+  lines.push("    owner: root:root");
+  lines.push("    permissions: '0755'");
+  lines.push("    content: |");
+  lines.push("      #!/bin/bash");
+  lines.push("      set -euo pipefail");
+  lines.push("      LOGFILE=\"/var/log/sshd-health.json\"");
+  lines.push("      sshd_active=$(systemctl is-active ssh 2>/dev/null || echo \"inactive\")");
+  lines.push("      sshd_pid=$(pgrep -x sshd | head -1 || echo \"0\")");
+  lines.push("      f2b_active=$(systemctl is-active fail2ban 2>/dev/null || echo \"inactive\")");
+  lines.push("      f2b_banned=$(fail2ban-client status sshd 2>/dev/null | grep \"Currently banned\" | awk '{print $NF}' || echo \"0\")");
+  lines.push("      f2b_total=$(fail2ban-client status sshd 2>/dev/null | grep \"Total banned\" | awk '{print $NF}' || echo \"0\")");
+  lines.push("      failed_1h=$(journalctl -u ssh --since \"1 hour ago\" --no-pager 2>/dev/null | grep -c \"Failed\" || true)");
+  lines.push("      failed_24h=$(journalctl -u ssh --since \"24 hours ago\" --no-pager 2>/dev/null | grep -c \"Failed\" || true)");
+  lines.push("      active_connections=$(ss -tnp | grep -c \":22 \" || echo \"0\")");
+  lines.push("      uptime_seconds=$(awk '{print int($1)}' /proc/uptime)");
+  lines.push("      load=$(awk '{print $1}' /proc/loadavg)");
+  lines.push("      mem_used_pct=$(free | awk '/Mem:/{printf \"%.1f\", $3/$2*100}')");
+  lines.push("      timestamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)");
+  lines.push("      cat > \"$LOGFILE\" <<HEALTHEOF");
+  lines.push("      {");
+  lines.push("        \"timestamp\": \"$timestamp\",");
+  lines.push("        \"sshd\": { \"active\": \"$sshd_active\", \"pid\": $sshd_pid },");
+  lines.push("        \"fail2ban\": { \"active\": \"$f2b_active\", \"currently_banned\": $f2b_banned, \"total_banned\": $f2b_total },");
+  lines.push("        \"connections\": { \"active\": $active_connections, \"failed_1h\": $failed_1h, \"failed_24h\": $failed_24h },");
+  lines.push("        \"system\": { \"uptime_seconds\": $uptime_seconds, \"load\": $load, \"memory_used_pct\": $mem_used_pct }");
+  lines.push("      }");
+  lines.push("      HEALTHEOF");
+  lines.push("      if [ \"$sshd_active\" != \"active\" ]; then");
+  lines.push("        logger -t sshd-health -p auth.crit \"ALERT: sshd is $sshd_active\"");
+  lines.push("        systemctl start ssh 2>/dev/null || logger -t sshd-health -p auth.crit \"FAILED to restart sshd\"");
+  lines.push("      fi");
+  lines.push("");
+
+  // 4. Systemd oneshot service — wraps the health script for timer-based execution
+  lines.push("  # sshd health check systemd service");
+  lines.push("  - path: /etc/systemd/system/sshd-health.service");
+  lines.push("    owner: root:root");
+  lines.push("    permissions: '0644'");
+  lines.push("    content: |");
+  lines.push("      [Unit]");
+  lines.push("      Description=sshd health check");
+  lines.push("      After=ssh.service");
+  lines.push("      [Service]");
+  lines.push("      Type=oneshot");
+  lines.push("      ExecStart=/opt/monitoring/sshd-health.sh");
+  lines.push("");
+
+  // 5. Systemd timer — fires the health check every 60 seconds, starting 30s after boot
+  lines.push("  # sshd health check timer (every 60s)");
+  lines.push("  - path: /etc/systemd/system/sshd-health.timer");
+  lines.push("    owner: root:root");
+  lines.push("    permissions: '0644'");
+  lines.push("    content: |");
+  lines.push("      [Unit]");
+  lines.push("      Description=Run sshd health check every minute");
+  lines.push("      [Timer]");
+  lines.push("      OnBootSec=30");
+  lines.push("      OnUnitActiveSec=60");
+  lines.push("      [Install]");
+  lines.push("      WantedBy=timers.target");
+  lines.push("");
+
+  return lines;
+}
+
+/**
+ * Commands to activate all SSH hardening services at first boot.
+ * Returns cloud-init YAML lines for the `runcmd:` section.
+ *
+ * Order matters:
+ *   1. Create /opt/monitoring dir (health script target)
+ *   2. Reload sshd to pick up hardened.conf (fallback: full restart)
+ *   3. Enable + start fail2ban (reads jail.local immediately)
+ *   4. Reload systemd to pick up the health service/timer units
+ *   5. Enable + start the health timer (begins 60s monitoring loop)
+ */
+export function sshdHardeningRunCmd(): string[] {
+  const lines: string[] = [];
+
+  lines.push("  # SSH hardening: reload sshd, enable fail2ban and health monitoring");
+  lines.push("  - mkdir -p /opt/monitoring");
+  lines.push("  - systemctl reload ssh || systemctl restart ssh");
+  lines.push("  - systemctl enable --now fail2ban");
+  lines.push("  - systemctl daemon-reload");
+  lines.push("  - systemctl enable --now sshd-health.timer");
+  lines.push("");
+
+  return lines;
+}

package/client.js

@@ -0,0 +1,137 @@
+/**
+ * Hetzner Cloud API client
+ * For server-side use only (requires API token)
+ *
+ * TODO: RE-REVIEW https://docs.hetzner.cloud/reference/cloud#authentication
+ * - https://tailscale.com/kb/1150/cloud-hetzner
+ */
+// Explicitly import fetch for Bun compatibility
+import { fetch as bunFetch } from "bun";
+import { HETZNER_API_BASE } from "./config.js";
+// Use Bun's fetch if available, otherwise try global fetch
+const fetch = bunFetch || globalThis.fetch;
+import { resolveApiToken, getTokenFromCLI, isAuthenticated } from "./auth.js";
+import { ServerOperations } from "./servers.js";
+import { ActionOperations } from "./actions.js";
+import { PricingOperations } from "./pricing.js";
+import { SSHKeyOperations } from "./ssh-keys.js";
+import { VolumeOperations } from "./volumes.js";
+import { createHetznerError, } from "./errors.js";
+import { parseRateLimitHeaders, } from "./actions.js";
+export class HetznerClient {
+    apiToken;
+    constructor(apiToken) {
+        this.apiToken = resolveApiToken(apiToken);
+        // If no token from env or explicit, try CLI config
+        if (!this.apiToken) {
+            this.apiToken = getTokenFromCLI();
+        }
+    }
+    get isAuthenticated() {
+        return isAuthenticated(this.apiToken);
+    }
+    /**
+     * Make a request to the Hetzner Cloud API
+     *
+     * @param endpoint - API endpoint (e.g., "/servers")
+     * @param options - RequestInit options
+     * @returns Parsed JSON response
+     * @throws {HetznerAPIError} On API errors
+     */
+    async request(endpoint, options = {}) {
+        const response = await fetch(`${HETZNER_API_BASE}${endpoint}`, {
+            ...options,
+            headers: {
+                Authorization: `Bearer ${this.apiToken}`,
+                "Content-Type": "application/json",
+                ...options.headers,
+            },
+        });
+        // Parse rate limit headers
+        const rateLimit = parseRateLimitHeaders(response.headers);
+        this.handleRateLimit(rateLimit);
+        if (!response.ok) {
+            const body = await response.json().catch(() => ({}));
+            throw createHetznerError(response.status, body);
+        }
+        const data = await response.json();
+        return data;
+    }
+    /**
+     * Validate Hetzner API response with Zod schema
+     *
+     * @param schema - Zod schema to validate against
+     * @param data - Data to validate
+     * @returns Validated data
+     */
+    validateResponse(schema, data) {
+        const result = schema.safeParse(data);
+        if (result.success) {
+            return result.data;
+        }
+        // Log validation errors but don't throw to maintain backward compatibility
+        console.warn("Hetzner API response validation warning:", result.error.issues);
+        return data;
+    }
+    /**
+     * Handle rate limit information from response headers
+     *
+     * @param rateLimit - Rate limit info from response
+     */
+    handleRateLimit(rateLimit) {
+        if (!rateLimit)
+            return;
+        // Warn if rate limit is low
+        if (rateLimit.remaining < 100) {
+            console.warn(`[Hetzner API] Rate limit low: ${rateLimit.remaining}/${rateLimit.limit} remaining. Resets at ${new Date(rateLimit.reset * 1000).toISOString()}`);
+        }
+    }
+    /**
+     * Get current rate limit information
+     *
+     * Makes a lightweight request to check rate limit status
+     *
+     * @returns Rate limit info or null if not available
+     */
+    async getRateLimit() {
+        try {
+            const response = await fetch(`${HETZNER_API_BASE}/servers`, {
+                headers: {
+                    Authorization: `Bearer ${this.apiToken}`,
+                },
+            });
+            return parseRateLimitHeaders(response.headers);
+        }
+        catch {
+            return null;
+        }
+    }
+    servers = new ServerOperations(this);
+    actions = new ActionOperations(this);
+    pricing = new PricingOperations(this);
+    ssh_keys = new SSHKeyOperations(this);
+    volumes = new VolumeOperations(this);
+    // Backward-compatible convenience methods (delegates to servers operations)
+    async listServers() {
+        return this.servers.list();
+    }
+    async getServer(id) {
+        return this.servers.get(id);
+    }
+    async createServer(options) {
+        return this.servers.create(options);
+    }
+    async deleteServer(id) {
+        return this.servers.delete(id);
+    }
+    async powerOn(id) {
+        return this.servers.powerOn(id);
+    }
+    async powerOff(id) {
+        return this.servers.powerOff(id);
+    }
+    async reboot(id) {
+        return this.servers.reboot(id);
+    }
+}
+//# sourceMappingURL=client.js.map

package/client.ts

@@ -0,0 +1,177 @@
+/**
+ * Hetzner Cloud API client
+ * For server-side use only (requires API token)
+ *
+ * TODO: RE-REVIEW https://docs.hetzner.cloud/reference/cloud#authentication
+ * - https://tailscale.com/kb/1150/cloud-hetzner
+ */
+
+// Explicitly import fetch for Bun compatibility
+import { fetch as bunFetch } from "bun";
+import { z } from "zod";
+import { HETZNER_API_BASE } from "./config.js";
+
+// Use Bun's fetch if available, otherwise try global fetch
+const fetch = bunFetch || (globalThis as any).fetch;
+import { resolveApiToken, getTokenFromCLI, isAuthenticated } from "./auth.js";
+import { ServerOperations } from "./servers.js";
+import { ActionOperations } from "./actions.js";
+import { PricingOperations } from "./pricing.js";
+import { SSHKeyOperations } from "./ssh-keys.js";
+import { VolumeOperations } from "./volumes.js";
+import {
+  HetznerListServersResponseSchema,
+  HetznerGetServerResponseSchema,
+  HetznerCreateServerResponseSchema,
+} from "./schemas.js";
+import {
+  createHetznerError,
+  isRateLimitError,
+} from "./errors.js";
+import {
+  parseRateLimitHeaders,
+  waitForRateLimitReset,
+} from "./actions.js";
+import type { RateLimitInfo } from "./types.js";
+
+export class HetznerClient {
+  private apiToken: string;
+
+  constructor(apiToken?: string) {
+    this.apiToken = resolveApiToken(apiToken);
+
+    // If no token from env or explicit, try CLI config
+    if (!this.apiToken) {
+      this.apiToken = getTokenFromCLI();
+    }
+  }
+
+  get isAuthenticated(): boolean {
+    return isAuthenticated(this.apiToken);
+  }
+
+  /**
+   * Make a request to the Hetzner Cloud API
+   *
+   * @param endpoint - API endpoint (e.g., "/servers")
+   * @param options - RequestInit options
+   * @returns Parsed JSON response
+   * @throws {HetznerAPIError} On API errors
+   */
+  async request<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
+    const response = await fetch(`${HETZNER_API_BASE}${endpoint}`, {
+      ...options,
+      headers: {
+        Authorization: `Bearer ${this.apiToken}`,
+        "Content-Type": "application/json",
+        ...options.headers,
+      },
+    });
+
+    // Parse rate limit headers
+    const rateLimit = parseRateLimitHeaders(response.headers);
+    this.handleRateLimit(rateLimit);
+
+    if (!response.ok) {
+      const body = await response.json().catch(() => ({}));
+      throw createHetznerError(response.status, body);
+    }
+
+    const data = await response.json();
+    return data as T;
+  }
+
+  /**
+   * Validate Hetzner API response with Zod schema
+   *
+   * @param schema - Zod schema to validate against
+   * @param data - Data to validate
+   * @returns Validated data
+   */
+  private validateResponse<T>(schema: z.ZodType<T>, data: unknown): T {
+    const result = schema.safeParse(data);
+    if (result.success) {
+      return result.data;
+    }
+    // Log validation errors but don't throw to maintain backward compatibility
+    console.warn(
+      "Hetzner API response validation warning:",
+      result.error.issues
+    );
+    return data as T;
+  }
+
+  /**
+   * Handle rate limit information from response headers
+   *
+   * @param rateLimit - Rate limit info from response
+   */
+  private handleRateLimit(rateLimit: RateLimitInfo | null): void {
+    if (!rateLimit) return;
+
+    // Warn if rate limit is low
+    if (rateLimit.remaining < 100) {
+      console.warn(
+        `[Hetzner API] Rate limit low: ${rateLimit.remaining}/${rateLimit.limit} remaining. Resets at ${new Date(rateLimit.reset * 1000).toISOString()}`
+      );
+    }
+  }
+
+  /**
+   * Get current rate limit information
+   *
+   * Makes a lightweight request to check rate limit status
+   *
+   * @returns Rate limit info or null if not available
+   */
+  async getRateLimit(): Promise<RateLimitInfo | null> {
+    try {
+      const response = await fetch(`${HETZNER_API_BASE}/servers`, {
+        headers: {
+          Authorization: `Bearer ${this.apiToken}`,
+        },
+      });
+      return parseRateLimitHeaders(response.headers);
+    } catch {
+      return null;
+    }
+  }
+
+  readonly servers = new ServerOperations(this);
+  readonly actions = new ActionOperations(this);
+  readonly pricing = new PricingOperations(this);
+  readonly ssh_keys = new SSHKeyOperations(this);
+  readonly volumes = new VolumeOperations(this);
+
+  // Backward-compatible convenience methods (delegates to servers operations)
+  async listServers() {
+    return this.servers.list();
+  }
+
+  async getServer(id: number) {
+    return this.servers.get(id);
+  }
+
+  async createServer(options: import("./types.js").CreateServerOptions) {
+    return this.servers.create(options);
+  }
+
+  async deleteServer(id: number) {
+    return this.servers.delete(id);
+  }
+
+  async powerOn(id: number) {
+    return this.servers.powerOn(id);
+  }
+
+  async powerOff(id: number) {
+    return this.servers.powerOff(id);
+  }
+
+  async reboot(id: number) {
+    return this.servers.reboot(id);
+  }
+}
+
+// Re-export types for convenience
+export type * from "./types.js";