From 9aec29f6052c4d5024c4bfb55c24e8bef77bb88f Mon Sep 17 00:00:00 2001
From: Thore Cimbal <cfx@riot.8shield.net>
Date: Tue, 28 Jul 2026 16:41:32 +0200
Subject: [PATCH] docs: Document age key recovery from an already-running
 cluster

install.md only covered generating a brand-new key during fresh setup.
Added the actual recovery path (retrieve the existing key from the
sops-age secret) - what today's session actually needed after the Mac
reinstall. Also flags the age key's single-backup-location weakness,
tracked in issue #20.
---
 docs/install.md | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)
 mode change 100644 => 100755 docs/install.md

diff --git a/docs/install.md b/docs/install.md
old mode 100644
new mode 100755
index eef01bb..631adcf
--- a/docs/install.md
+++ b/docs/install.md
@@ -75,4 +75,32 @@ flux get helmreleases -n matrix --watch
 # Zeigt, wie die Pods hochfahren:
 kubectl get pods -n matrix -w
 ```
-Sobald alle Pods auf `Running` stehen und die Zertifikate über Let's Encrypt validiert wurden (`kubectl get certificate -n matrix`), ist dein Matrix-Stack unter `https://axion1337.chat` erreichbar.
\ No newline at end of file
+Sobald alle Pods auf `Running` stehen und die Zertifikate über Let's Encrypt validiert wurden (`kubectl get certificate -n matrix`), ist dein Matrix-Stack unter `https://axion1337.chat` erreichbar.
+
+---
+
+## 🔁 Recovery: lokalen age-Key wiederherstellen (Server läuft bereits)
+
+Anders als Schritt 2 oben (neuen Key **erzeugen**) — falls der Server bereits läuft und nur der
+lokale Rechner den age-Key verloren hat (z.B. nach einer Neuinstallation), lässt sich der
+**bestehende** Private Key direkt aus dem Cluster zurückholen, ohne einen neuen zu generieren
+(das würde `.sops.yaml` und alle bereits verschlüsselten Secrets ungültig machen):
+
+```bash
+mkdir -p ~/.age
+kubectl get secret sops-age -n flux-system -o jsonpath='{.data.age\.agekey}' | base64 -d > ~/.age/keys.txt
+chmod 600 ~/.age/keys.txt
+
+# Public Key zur Kontrolle gegen .sops.yaml abgleichen:
+grep 'public key:' ~/.age/keys.txt
+grep 'age:' .sops.yaml
+```
+
+Voraussetzung: laufender Kubeconfig-Zugriff auf den Cluster (siehe Schritt 1 oben — auch das
+ist reines Zurückkopieren, kein Neu-Erzeugen).
+
+**Bekannte Schwachstelle**: Dieser Key existiert aktuell nur an zwei Orten — im
+`sops-age`-Secret selbst (auf demselben Server) und lokal bei wem auch immer ihn zuletzt
+zurückgeholt hat. Es gibt kein separates, offsite Backup. Fällt der Server komplett aus
+(nicht nur der lokale Rechner), sind alle SOPS-verschlüsselten Secrets im Repo unlesbar.
+Siehe Issue-Backlog für die Entscheidung, ob/wie das abgesichert wird.
\ No newline at end of file