docs: Consolidate homelab documentation and update SSH guide

operations/ssh-management.md

@@ -0,0 +1,150 @@
+# SOP: SSH Key Management & Access (Zero Trust)
+
+**Purpose:** Standardize the creation, storage, and usage of SSH keys for accessing internal homelab services (Gitea, servers, etc.) protected by Cloudflare Tunnels, without opening firewall ports.
+
+**Prerequisites:**
+
+* **Client:** Windows 10/11 with OpenSSH Client installed.
+* **Software:** Keeper Password Manager (Desktop App), `cloudflared` daemon.
+* **Network:** Cloudflare Tunnel configured for the target service (SSH protocol).
+
+---
+
+## 1. Key Generation
+
+Use **Ed25519** for all new keys (faster, smaller, more secure than RSA).
+
+1. Open PowerShell.
+2. Generate a new key pair (replace `service` with app name, e.g., `gitea`, `prod-server`):
+```powershell
+ssh-keygen -t ed25519 -C "davisdre@service" -f "$env:USERPROFILE\.ssh\id_ed25519_service"
+
+```
+
+
+3. **Do not** set a passphrase if relying on Keeper (Keeper protects the key).
+
+## 2. Storage & Agent Setup (Keeper)
+
+We do not store private keys permanently on the local disk. They live in Keeper and are injected into memory via the SSH Agent.
+
+1. **Create Record:** Create a new record in Keeper (e.g., "SSH Key - Gitea").
+2. **Attach Keys:** Upload the `.pub` (Public) and the private key file (no extension) to the record attachments or dedicated SSH Key fields.
+3. **Enable Agent:**
+* In Keeper Desktop: Go to **Settings > SSH Agent**.
+* Ensure **Enable SSH Agent Integration** is ON.
+* Select the key record you just created and ensure it is listed/active.
+
+
+4. **Cleanup:** Delete the **private** key file from your local `.ssh` folder. You may keep the `.pub` file for reference.
+
+## 3. Client Configuration (`config`)
+
+Configure the local SSH client to route traffic through Cloudflare and use the Keeper agent.
+
+1. Open your config file: `C:\Users\davis\.ssh\config`.
+2. Add a new block for the service.
+* **Note:** Do *not* hardcode `IdentityAgent` lines; rely on the `SSH_AUTH_SOCK` environment variable set by Keeper.
+
+
+
+```text
+# Template for Cloudflare Tunnel Services
+Host service.davisdre.com
+  User git
+  # Proxy traffic via Cloudflare (requires cloudflared installed)
+  ProxyCommand cloudflared access ssh --hostname %h
+
+```
+
+## 4. Service Configuration
+
+1. Copy the content of your **Public Key** (`.pub` file).
+2. Navigate to the Service (e.g., Gitea Settings > SSH / GPG Keys).
+3. Add Key and paste the string (starts with `ssh-ed25519`).
+
+## 5. Connection Verification
+
+Before using the tool (VS Code, git, etc.), verify the handshake in PowerShell.
+
+1. **Unlock Keeper:** Ensure the vault is open.
+2. **Test Connection:**
+```powershell
+ssh -T git@service.davisdre.com
+
+```
+
+
+3. **Expected Output:**
+* *First time:* Prompts to verify host fingerprint (Type `yes`).
+* *Success:* `Hi there...! You've successfully authenticated...`
+
+---
+
+## 6. WSL & Keeper Desktop SSH Agent Setup
+
+This configuration bridges Windows Subsystem for Linux (WSL) with the Keeper Desktop SSH Agent using native Windows executables.
+
+### The Core Concept
+WSL uses Unix sockets for SSH, while Windows applications like Keeper Desktop use Windows Named Pipes. By default, they cannot communicate. The most reliable solution is to instruct WSL to use the native Windows `ssh.exe` executables, which inherently understand Windows Named Pipes and can talk directly to Keeper.
+
+### Configuration Steps
+
+1. **Remove Linux SSH-Agent Scripts**
+   If you previously configured your `~/.bashrc` to start the Linux ssh-agent (e.g., `eval "$(ssh-agent -s)"`), remove those lines to prevent conflicts.
+
+2. **Alias Windows Executables in WSL**
+   Open your bash configuration file:
+   ```bash
+   nano ~/.bashrc
+   ```
+
+   Add the following aliases to the bottom of the file:
+   ```bash
+   # Use Windows native SSH tools to interface with Keeper Desktop
+   alias ssh='ssh.exe'
+   alias ssh-add='ssh-add.exe'
+   alias scp='scp.exe'
+   ```
+
+3. **Configure Git (Optional but Recommended)**
+   If you use Git inside WSL and want to push/pull using Keeper's SSH keys, configure Git to use the Windows SSH executable:
+   ```bash
+   git config --global core.sshCommand "ssh.exe"
+   ```
+
+4. **Apply the Changes**
+   Reload your shell configuration:
+   ```bash
+   source ~/.bashrc
+   ```
+
+### Verification
+To confirm the setup is working, run:
+```bash
+ssh-add -l
+```
+*(This executes `ssh-add.exe -l` under the hood via the alias).*
+
+---
+
+## Troubleshooting
+
+| Issue | Check |
+| --- | --- |
+| **Permission Denied (publickey)** | 1. Is Keeper unlocked? <br> <br> 2. Run `ssh-add -l` to see if keys are loaded. <br> <br> 3. Ensure `git config core.sshCommand` is set to Windows OpenSSH. |
+| **"The agent has no identities"** | WSL can see Keeper, but Keeper isn't providing keys. Check that the vault is unlocked and the specific key record has "Add to SSH Agent" toggled ON. |
+| **"Error connecting to agent"** | The Keeper SSH Agent is not running. In Keeper Desktop Settings > Developer, toggle the SSH Agent OFF and back ON. |
+| **TLS Handshake Failure** | Cloudflare SSL mismatch. Ensure the tunnel hostname is not 4th level (e.g., use `git-ssh.domain.com`, NOT `ssh.git.domain.com`). |
+| **"Unknown Port" / Proxy Error** | Ensure `cloudflared` is installed and the Tunnel Public Hostname is set to `SSH` service (not HTTP). |
+
+---
+
+### **Git Configuration (One-Time Setup)**
+
+Ensure Git uses the Windows Native SSH (which talks to Keeper) rather than the bundled MinGW SSH.
+
+```powershell
+git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"
+
+```