Sankofa/docs/proxmox/dotenv-complete-review.md

# Complete .env File Review

**Review Date**: 2024-12-19  
**File**: `.env`  
**Size**: 1,452 bytes  
**Lines**: 37 total (17 comments, 11 variables, 9 blank)  
**Permissions**: 644 (rw-r--r--) ⚠️ **Should be 600**

---

## File Structure Analysis

### Line-by-Line Breakdown

```
Lines 1-2:   Header comments (security warning)
Line 3:      Blank
Lines 4-5:   Cloudflare Global API Key
Line 6:      Blank
Lines 7-8:   Cloudflare User Email
Line 9:      Blank
Lines 10-11: Cloudflare Origin CA Key
Line 12:     Blank
Lines 13-16: Domain and Cloudflare IDs
Line 17:     Blank
Lines 18-20: Proxmox credentials header comments
Line 21:     Blank
Lines 22-24: Instance 1 (ML110-01) credentials
Line 25:     Blank
Lines 26-28: Instance 2 (R630-01) credentials
Line 29:     Blank
Lines 30-33: Generic Proxmox credentials
Line 34:     Blank
Lines 35-37: Proxmox endpoint examples (commented)
```

---

## Current Configuration

### Cloudflare Variables

| Variable | Line | Status | Value | Notes |
|----------|------|--------|-------|-------|
| `CLOUDFLARE_API_KEY` | 5 | ✅ Set | `e5153f7f2dcf64fec7f25ede78c15482bc950` | ⚠️ Global API Key (full access) |
| `CLOUDFLARE_EMAIL` | 8 | ✅ Set | `pandoramannli@gmail.com` | Used with API Key |
| `CLOUDFLARE_ORIGIN_CA_KEY` | 11 | ✅ Set | `v1.0-40220c19a24...` | Origin CA certificate key |
| `CLOUDFLARE_API_TOKEN` | **MISSING** | ❌ **Not defined** | - | 🔴 **Required for ACME** |
| `DOMAIN` | 14 | ✅ Set | `sankofa.nexus` | Correct domain |
| `CLOUDFLARE_ACCOUNT_ID` | 15 | ✅ Set | `52ad57a71671c5fc009edf0744658196` | Valid format |
| `CLOUDFLARE_ZONE_ID` | 16 | ✅ Set | `13e2c26acc5eda15eafa7c8735b00239` | Valid format |

### Proxmox Variables

| Variable | Line | Status | Value | Notes |
|----------|------|--------|-------|-------|
| `PROXMOX_USERNAME_ML110_01` | 23 | ✅ Set | `root@pam` | Instance 1 username |
| `PROXMOX_TOKEN_ML110_01` | 24 | ✅ Set | `root@pam!sankofa-instance-1-api-token=...` | Instance 1 API token |
| `PROXMOX_USERNAME_R630_01` | 27 | ✅ Set | `root@pam` | Instance 2 username |
| `PROXMOX_TOKEN_R630_01` | 28 | ✅ Set | `root@pam!sankofa-instance-2-api-token=...` | Instance 2 API token |
| `PROXMOX_ROOT_PASS` | 33 | ✅ Set | `L@KERS2010` | ⚠️ Plain text password |
| `PROXMOX_ENDPOINT_ML110_01` | 36 | ⚪ Commented | `https://ml110-01.d-bis.org:8006` | ⚠️ Wrong domain (should be sankofa.nexus) |
| `PROXMOX_ENDPOINT_R630_01` | 37 | ⚪ Commented | `https://r630-01.d-bis.org:8006` | ⚠️ Wrong domain (should be sankofa.nexus) |

---

## Critical Issues

### 🔴 1. Missing CLOUDFLARE_API_TOKEN for ACME Setup

**Severity**: CRITICAL  
**Impact**: Proxmox ACME DNS-01 plugin cannot function without this token

**Details**:
- Variable is completely missing (not even commented)
- Required for automatic Let's Encrypt certificate issuance/renewal
- Token must have Zone DNS Edit permissions for `sankofa.nexus`

**Action Required**:
```env
# Add after line 11 (after CLOUDFLARE_ORIGIN_CA_KEY):
# Cloudflare API Token for ACME DNS-01 (Proxmox Let's Encrypt)
# Token Name: proxmox-acme-dns01
# Permissions: Zone DNS Edit (sankofa.nexus only)
CLOUDFLARE_API_TOKEN=your-acme-dns01-token-here
```

**Token Creation**:
1. Go to: https://dash.cloudflare.com/profile/api-tokens
2. Click "Create Token"
3. Use "Edit zone DNS" template
4. Zone Resources: Include → `sankofa.nexus`
5. Copy token and add to `.env`

---

### ⚠️ 2. File Permissions Too Permissive

**Severity**: HIGH  
**Current**: 644 (rw-r--r--) - readable by group and others  
**Should be**: 600 (rw-------) - readable/writable by owner only

**Action Required**:
```bash
chmod 600 .env
```

**Verify**:
```bash
ls -l .env
# Should show: -rw------- 1 intlc intlc 1452 Dec 15 15:46 .env
```

---

### ⚠️ 3. Security: Global API Key Exposed

**Severity**: HIGH  
**Issue**: Global API Key provides full account access if compromised

**Recommendations**:
1. **Preferred**: Use API tokens with limited scope instead
2. **If Global API Key must be used**:
   - Rotate regularly (every 90 days)
   - Monitor API usage for unauthorized access
   - Consider IP restrictions if possible
   - Ensure file permissions are 600

**Migration Path**:
- Current scripts support both methods (API Key + Email OR API Token)
- `scripts/configure-cloudflare.sh` checks for `CLOUDFLARE_API_TOKEN` first, falls back to API Key
- Prefer API tokens for new integrations (like ACME)

---

### ⚠️ 4. Security: Plain Text Password

**Severity**: MEDIUM  
**Issue**: `PROXMOX_ROOT_PASS` stored in plain text

**Current Usage**:
- Proxmox API tokens are already configured (better practice) ✅
- Password may be used by some legacy scripts

**Recommendations**:
1. **Best**: Remove password if not needed (API tokens are sufficient)
2. **If password must be stored**:
   - Use secrets management (HashiCorp Vault, Kubernetes Secrets)
   - Encrypt the `.env` file
   - Store in password manager
   - Document why it's needed

---

### ⚠️ 5. Incorrect Domain in Commented Endpoints

**Severity**: LOW  
**Issue**: Commented endpoints reference `d-bis.org` instead of `sankofa.nexus`

**Lines 36-37**:
```env
# PROXMOX_ENDPOINT_ML110_01=https://ml110-01.d-bis.org:8006
# PROXMOX_ENDPOINT_R630_01=https://r630-01.d-bis.org:8006
```

**Should be**:
```env
# PROXMOX_ENDPOINT_ML110_01=https://ml110-01.sankofa.nexus:8006
# PROXMOX_ENDPOINT_R630_01=https://r630-01.sankofa.nexus:8006
```

**Impact**: Low (commented out), but could cause confusion

---

## Configuration Completeness

### For ACME Certificate Setup

| Requirement | Status | Variable | Notes |
|-------------|--------|----------|-------|
| Cloudflare Account ID | ✅ | `CLOUDFLARE_ACCOUNT_ID` | Configured |
| Cloudflare Zone ID | ✅ | `CLOUDFLARE_ZONE_ID` | Configured |
| Domain Name | ✅ | `DOMAIN` | `sankofa.nexus` |
| **API Token for DNS-01** | ❌ | `CLOUDFLARE_API_TOKEN` | **MISSING** |

### For Proxmox API Access

| Requirement | Status | Variable | Notes |
|-------------|--------|----------|-------|
| ML110-01 Username | ✅ | `PROXMOX_USERNAME_ML110_01` | `root@pam` |
| ML110-01 Token | ✅ | `PROXMOX_TOKEN_ML110_01` | Properly formatted |
| R630-01 Username | ✅ | `PROXMOX_USERNAME_R630_01` | `root@pam` |
| R630-01 Token | ✅ | `PROXMOX_TOKEN_R630_01` | Properly formatted |

### For Cloudflare Scripts

| Requirement | Status | Variable | Notes |
|-------------|--------|----------|-------|
| API Authentication | ✅ | `CLOUDFLARE_API_KEY` + `CLOUDFLARE_EMAIL` | Configured (fallback) |
| API Token | ❌ | `CLOUDFLARE_API_TOKEN` | Missing (preferred method) |
| Account ID | ✅ | `CLOUDFLARE_ACCOUNT_ID` | Configured |
| Zone ID | ✅ | `CLOUDFLARE_ZONE_ID` | Configured |

---

## Script Compatibility

### Scripts That Use .env Variables

1. **`scripts/configure-cloudflare.sh`**
   - ✅ Supports both API Key + Email (current) and API Token (preferred)
   - ✅ Uses `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_ZONE_ID`
   - ⚠️ Will use Global API Key since `CLOUDFLARE_API_TOKEN` is missing

2. **`scripts/setup-proxmox-agents.sh`**
   - ✅ Uses `PROXMOX_TOKEN_ML110_01` and `PROXMOX_TOKEN_R630_01`
   - ✅ Doesn't require password if tokens are configured

3. **Proxmox ACME Plugin** (via Proxmox UI/CLI)
   - ❌ **Cannot function** without `CLOUDFLARE_API_TOKEN`
   - Must be added manually in Proxmox UI (not from .env)
   - But should be documented/synced

---

## Recommended .env Structure

```env
# =============================================================================
# Cloudflare Configuration
# =============================================================================

# Cloudflare Global API Key (legacy - prefer API tokens)
# ⚠️ Provides full account access - use API tokens when possible
CLOUDFLARE_API_KEY=e5153f7f2dcf64fec7f25ede78c15482bc950
CLOUDFLARE_EMAIL=pandoramannli@gmail.com

# Cloudflare API Token for ACME DNS-01 (Proxmox Let's Encrypt certificates)
# Token Name: proxmox-acme-dns01
# Permissions: Zone DNS Edit (sankofa.nexus only)
# Create at: https://dash.cloudflare.com/profile/api-tokens
# Use "Edit zone DNS" template, scope to sankofa.nexus zone
CLOUDFLARE_API_TOKEN=your-acme-dns01-token-here

# Cloudflare Origin CA Key (for Origin Certificates)
CLOUDFLARE_ORIGIN_CA_KEY=v1.0-40220c19a24f6e2980fb37b0-291269e9961901c18546cfbb6ad75c0427e8b74c4db0e8f6692a1cb6312abc9117fa0fed8b8e34e6912de4be243686a605d5f9d1c29d4fb2c5f62e74ced3c48c96dab035fced95e9d5

# Domain Configuration
DOMAIN=sankofa.nexus

# Cloudflare Account and Zone IDs
CLOUDFLARE_ACCOUNT_ID=52ad57a71671c5fc009edf0744658196
CLOUDFLARE_ZONE_ID=13e2c26acc5eda15eafa7c8735b00239

# =============================================================================
# Proxmox Configuration
# =============================================================================

# Instance 1 (ML110-01) - Admin Node (us-sfvalley)
PROXMOX_USERNAME_ML110_01=root@pam
PROXMOX_TOKEN_ML110_01=root@pam!sankofa-instance-1-api-token=73c7e1a2-c969-409c-ae5b-68e83f012ee9

# Instance 2 (R630-01) - VM/Compute Node (us-sfvalley-2)
PROXMOX_USERNAME_R630_01=root@pam
PROXMOX_TOKEN_R630_01=root@pam!sankofa-instance-2-api-token=d0d45212-a9dc-4048-ab60-528c1aae41d4

# Generic Proxmox credentials (used by scripts if instance-specific not set)
# PROXMOX_USERNAME=root@pam
# PROXMOX_TOKEN=user@realm!token-id=token-secret

# Root Password (⚠️ Consider using secrets management instead)
# Only needed if API tokens are not available
PROXMOX_ROOT_PASS=L@KERS2010

# Proxmox Endpoints (optional - defaults to FQDNs)
# PROXMOX_ENDPOINT_ML110_01=https://ml110-01.sankofa.nexus:8006
# PROXMOX_ENDPOINT_R630_01=https://r630-01.sankofa.nexus:8006
```

---

## Immediate Action Items

### Priority 1 (Critical - Blocks ACME Setup)

1. **Add CLOUDFLARE_API_TOKEN**
   ```bash
   # Edit .env and add after line 11:
   CLOUDFLARE_API_TOKEN=your-token-from-cloudflare-dashboard
   ```

2. **Fix File Permissions**
   ```bash
   chmod 600 .env
   ```

### Priority 2 (Security - Should fix soon)

3. **Verify .gitignore**
   ```bash
   grep -q "^\.env$" .gitignore || echo ".env" >> .gitignore
   ```

4. **Update Commented Endpoints** (optional)
   - Change `d-bis.org` to `sankofa.nexus` in lines 36-37

### Priority 3 (Best Practices)

5. **Consider Removing/Encrypting Password**
   - If API tokens are sufficient, remove `PROXMOX_ROOT_PASS`
   - Or move to secrets management

6. **Plan API Key Migration**
   - Gradually migrate scripts to use `CLOUDFLARE_API_TOKEN`
   - Consider rotating Global API Key

---

## Security Checklist

- [ ] `.env` file permissions set to 600 (currently 644)
- [ ] `.env` in `.gitignore` (verify)
- [ ] No secrets committed to git history (audit if needed)
- [ ] `CLOUDFLARE_API_TOKEN` added for ACME
- [ ] API tokens use minimal required permissions
- [ ] Consider rotating Global API Key
- [ ] Document why plain text password is needed (if it is)
- [ ] Review access to `.env` file (who can read it)

---

## Testing Checklist

After making changes:

```bash
# 1. Verify file permissions
ls -l .env
# Should show: -rw------- (600)

# 2. Test Cloudflare API token (if added)
export $(grep -v '^#' .env | xargs)
curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" | jq

# 3. Verify variables are loaded
echo "Account ID: ${CLOUDFLARE_ACCOUNT_ID}"
echo "Zone ID: ${CLOUDFLARE_ZONE_ID}"
echo "Domain: ${DOMAIN}"

# 4. Test Proxmox token format (should not output error)
echo "${PROXMOX_TOKEN_ML110_01}" | grep -q "!" && echo "✅ Token format valid"
```

---

## Related Documentation

- [ACME Setup Guide](./acme-setup.md) - Complete ACME certificate setup
- [ACME Commands](./acme-commands.md) - Command reference
- [ENV Examples](../ENV_EXAMPLES.md) - Environment variable examples
- [Cloudflare README](../cloudflare/README.md) - Cloudflare configuration

---

## Summary

**Overall Status**: ⚠️ **Needs Attention**

**Strengths**:
- ✅ Well-structured with clear comments
- ✅ Proxmox API tokens properly configured
- ✅ Cloudflare IDs correctly set
- ✅ Domain correctly specified

**Critical Issues**:
- 🔴 Missing `CLOUDFLARE_API_TOKEN` (blocks ACME setup)
- ⚠️ File permissions too permissive (644 → should be 600)

**Recommendations**:
- Add ACME token immediately
- Fix file permissions
- Consider security improvements (API token migration, password management)