feat: [#28] add secure token storage for Hetzner Cloud API

josecelano · josecelano · commit a9c94e9cd510 · 2025-08-04T09:41:57.000+01:00
Implement secure file-based storage for Hetzner Cloud API tokens following
the same pattern established for Hetzner DNS tokens.

**Infrastructure Changes:**
- Enhanced Hetzner provider script to auto-detect tokens from secure storage
- Added fallback to environment variables for backward compatibility
- Improved error messages with setup instructions for both methods

**Documentation Updates:**
- Added Hetzner Cloud token secure storage section to DNS setup guide
- Updated Hetzner Cloud setup guide with secure storage instructions
- Enhanced help text and setup instructions in provider scripts

**Security Benefits:**
- Tokens stored in ~/.config/hetzner/cloud_api_token with 600 permissions
- Reduced exposure in environment variables and command history
- Consistent approach across all Hetzner API integrations

**User Experience:**
- Automatic token detection - no environment variables needed
- Clear setup instructions for both storage methods
- Backward compatible with existing HETZNER_TOKEN workflows

All infrastructure tests pass. Successfully validated with production
infrastructure destruction using secure token storage.
diff --git a/docs/guides/hetzner-cloud-setup-guide.md b/docs/guides/hetzner-cloud-setup-guide.md
@@ -23,6 +23,53 @@ This guide explains how to set up and use the Hetzner Cloud provider with the To
 5. Set permissions to **Read & Write**
 6. Copy the generated token (64 characters)
 
+## Step 2.5: Secure Token Storage (Recommended)
+
+For enhanced security, store your Hetzner Cloud API token using secure file storage
+instead of environment variables:
+
+### Option 1: Secure Storage (Recommended)
+
+```bash
+# Create secure storage directory
+mkdir -p ~/.config/hetzner
+chmod 700 ~/.config/hetzner
+
+# Store the Hetzner Cloud API token (replace YOUR_TOKEN_HERE with actual token)
+echo "YOUR_TOKEN_HERE" > ~/.config/hetzner/cloud_api_token
+chmod 600 ~/.config/hetzner/cloud_api_token
+
+# Verify storage
+ls -la ~/.config/hetzner/
+# Should show: -rw------- 1 user user 65 date time cloud_api_token
+```
+
+### Test Token Storage
+
+```bash
+# Test that token can be loaded from storage
+CLOUD_TOKEN=$(cat ~/.config/hetzner/cloud_api_token)
+echo "Token length: ${#CLOUD_TOKEN} characters"
+# Should show: Token length: 64 characters
+
+# Test API access
+curl -H "Authorization: Bearer $CLOUD_TOKEN" \
+     "https://api.hetzner.cloud/v1/servers" | jq
+# Expected output: {"servers": []}
+```
+
+### Option 2: Environment Variable (Fallback)
+
+If you prefer environment variables, you can still use the traditional approach:
+
+```bash
+export HETZNER_TOKEN=your_64_character_token_here
+```
+
+> **Note**: The infrastructure scripts will automatically detect tokens from secure
+> storage first, then fall back to environment variables. Secure storage is
+> recommended for production use.
+
 ## Step 3: Configure Provider
 
 1. Copy the provider configuration template:
@@ -79,31 +126,29 @@ For production deployment, create a production environment:
 
 ## Step 5: Deploy Infrastructure
 
-1. Export your Hetzner token:
-
-   ```bash
-   export HETZNER_TOKEN=your_64_character_token_here
-   ```
+The infrastructure scripts will automatically detect your Hetzner token from secure
+The infrastructure scripts will automatically detect your Hetzner token from secure
+storage (`~/.config/hetzner/cloud_api_token`) or from environment variables.
 
-2. Initialize Terraform:
+1. Initialize Terraform:
 
    ```bash
    make infra-init ENVIRONMENT=production PROVIDER=hetzner
    ```
 
-3. Plan the deployment:
+2. Plan the deployment:
 
    ```bash
    make infra-plan ENVIRONMENT=production PROVIDER=hetzner
    ```
 
-4. Apply the infrastructure:
+3. Apply the infrastructure:
 
    ```bash
    make infra-apply ENVIRONMENT=production PROVIDER=hetzner
    ```
 
-5. Deploy the application:
+4. Deploy the application:
 
    ```bash
    make app-deploy ENVIRONMENT=production
diff --git a/docs/guides/hetzner-dns-setup-guide.md b/docs/guides/hetzner-dns-setup-guide.md
@@ -89,6 +89,62 @@ curl -H "Auth-API-Token: $DNS_TOKEN" \
 # Expected output: {"zones": []} (empty array for new accounts)
 ```
 
+## 🔑 Step 1.5: Hetzner Cloud API Token (Infrastructure Integration)
+
+For complete Hetzner integration, you'll also need a Hetzner Cloud API token for
+infrastructure provisioning. This is separate from the DNS API token but can be
+stored using the same secure method.
+
+### 1.5.1 Generate Hetzner Cloud API Token
+
+1. Go to [Hetzner Cloud Console](https://console.hetzner.cloud/)
+2. Navigate to your project
+3. Go to **"Security" → "API Tokens"**
+4. Click **"Generate API token"**
+5. Provide a descriptive name:
+
+   ```text
+   Name: torrust-infrastructure-automation
+   Description: Infrastructure automation for Torrust Tracker Demo
+   Permissions: Read & Write (required for creating/destroying servers)
+   ```
+
+6. Click **"Generate token"**
+7. **Important**: Copy and save the token immediately
+
+### 1.5.2 Secure Cloud Token Storage
+
+Store the Hetzner Cloud API token alongside the DNS token:
+
+```bash
+# Store the Hetzner Cloud API token (replace YOUR_CLOUD_TOKEN_HERE with actual token)
+echo "YOUR_CLOUD_TOKEN_HERE" > ~/.config/hetzner/cloud_api_token
+chmod 600 ~/.config/hetzner/cloud_api_token
+
+# Verify both tokens are stored securely
+ls -la ~/.config/hetzner/
+# Should show:
+# -rw------- 1 user user 65 date time cloud_api_token
+# -rw------- 1 user user 65 date time dns_api_token
+```
+
+### 1.5.3 Test Cloud API Access
+
+```bash
+# Load token from secure storage
+CLOUD_TOKEN=$(cat ~/.config/hetzner/cloud_api_token)
+
+# Test API access
+curl -H "Authorization: Bearer $CLOUD_TOKEN" \
+     "https://api.hetzner.cloud/v1/servers" | jq
+
+# Expected output: {"servers": []} (empty array for new accounts)
+```
+
+> **Note**: The infrastructure scripts will automatically detect and use the token
+> from `~/.config/hetzner/cloud_api_token`. You no longer need to set the
+> `HETZNER_TOKEN` environment variable if using secure storage.
+
 ## 🌐 Step 2: Create DNS Zone
 
 ### 2.1 Create Zone for Your Domain
diff --git a/infrastructure/terraform/providers/hetzner/provider.sh b/infrastructure/terraform/providers/hetzner/provider.sh
@@ -19,11 +19,29 @@ provider_validate_prerequisites() {
         log_info "Note: CLI is optional, Terraform provider will work without it"
     fi
 
-    # Validate required environment variables
-    if [[ -z "${HETZNER_TOKEN:-}" ]]; then
-        log_error "HETZNER_TOKEN environment variable is required"
+    # Load Hetzner Cloud API token from secure storage or environment variable
+    local hetzner_token_file="$HOME/.config/hetzner/cloud_api_token"
+    
+    if [[ -f "$hetzner_token_file" ]]; then
+        # Load token from secure storage (preferred method)
+        HETZNER_TOKEN=$(cat "$hetzner_token_file")
+        log_info "Loaded Hetzner Cloud API token from secure storage"
+    elif [[ -n "${HETZNER_TOKEN:-}" ]]; then
+        # Use token from environment variable (fallback)
+        log_info "Using Hetzner Cloud API token from environment variable"
+    else
+        # No token found
+        log_error "HETZNER_TOKEN not found in environment or secure storage"
+        log_error ""
+        log_error "Option 1 - Secure Storage (Recommended):"
+        log_error "  1. mkdir -p ~/.config/hetzner"
+        log_error "  2. echo 'your_token_here' > ~/.config/hetzner/cloud_api_token"
+        log_error "  3. chmod 600 ~/.config/hetzner/cloud_api_token"
+        log_error ""
+        log_error "Option 2 - Environment Variable:"
+        log_error "  export HETZNER_TOKEN=your_token_here"
+        log_error ""
         log_error "Get your token from: https://console.hetzner.cloud/"
-        log_error "Set it with: export HETZNER_TOKEN=your_token_here"
         exit 1
     fi
 
@@ -131,6 +149,12 @@ provider_get_info() {
     echo ""
     echo "Required variables:"
     echo "  - HETZNER_TOKEN (Hetzner Cloud API token)"
+    echo "    Option 1 - Secure Storage (Recommended):"
+    echo "      mkdir -p ~/.config/hetzner"
+    echo "      echo 'your_token' > ~/.config/hetzner/cloud_api_token"
+    echo "      chmod 600 ~/.config/hetzner/cloud_api_token"
+    echo "    Option 2 - Environment Variable:"
+    echo "      export HETZNER_TOKEN=your_token_here"
     echo ""
     echo "Optional variables:"
     echo "  - HETZNER_SERVER_TYPE (default: cx31 - 2 vCPU, 8GB RAM, 80GB SSD)"
@@ -155,7 +179,10 @@ provider_get_info() {
     echo "Setup instructions:"
     echo "  1. Create Hetzner Cloud account: https://console.hetzner.cloud/"
     echo "  2. Generate API token: Project → Security → API Tokens"
-    echo "  3. Export token: export HETZNER_TOKEN=your_token_here"
+    echo "  3. Secure token storage (recommended):"
+    echo "     mkdir -p ~/.config/hetzner && chmod 700 ~/.config/hetzner"
+    echo "     echo 'your_token_here' > ~/.config/hetzner/cloud_api_token"
+    echo "     chmod 600 ~/.config/hetzner/cloud_api_token"
     echo "  4. Deploy: make infra-apply ENVIRONMENT=production PROVIDER=hetzner"
 }
 
