Orchestrator/shared/config/ONBOARDING.md

Onboarding: Neue Maschine einrichten

Dieses Dokument beschreibt den Prozess, um eine neue Maschine für die Arbeit mit dem Monorepo und seinen verschlüsselten Secrets einzurichten.

Voraussetzungen

• Git ist installiert (>= 2.25)
• git-crypt ist installiert
• Zugang zum Passwort-Manager (Bitwarden) oder direkter Schlüsselzugang

Übersicht: Verschlüsselungsarchitektur

Das Monorepo verwendet git-crypt mit kontextspezifischen Filtern:

Kontext	Filter-Name	Verschlüsselte Patterns
privat	git-crypt-privat	.env, *.pem, *.key, token, secret
dhive	git-crypt-dhive	.env, *.pem, *.key, token, secret
bahn	git-crypt-bahn	.env, *.pem, *.key, token, secret
shared	git-crypt (basis)	shared/.env, shared//*.pem, shared//*.key

Jeder Kontext hat einen eigenen symmetrischen Schlüssel. Eine Maschine kann nur die Secrets der Kontexte entschlüsseln, für die sie autorisiert ist.

Schritt 1: Repository klonen

git clone <repo-url> monorepo
cd monorepo

Nach dem Klonen sind alle Secret-Dateien als verschlüsselte Binärdaten vorhanden. Code, Konfiguration und Dokumentation sind sofort lesbar.

Schritt 2: Maschinenkontext konfigurieren

Bearbeite shared/config/machine-context.yaml und passe sie an die neue Maschine an:

machine:
  name: "mein-neuer-rechner"
  description: "Beschreibung des Rechners und seines Einsatzzwecks"
  authorized_contexts:
    - privat        # Nur Kontexte eintragen, die entschlüsselt werden sollen
    - dhive
    # - bahn        # Auskommentiert = kein Zugriff auf bahn-Secrets
  key_source: "keyring"   # Siehe Abschnitt "Schlüsselquellen"
  password_manager:
    type: "bitwarden"
    vault: "monorepo-keys"

Felder

Feld	Beschreibung
name	Eindeutiger Name der Maschine (z.B. "dhive-laptop", "home-pc")
description	Kurze Beschreibung des Einsatzzwecks
authorized_contexts	Liste der Kontexte, deren Secrets entschlüsselt werden dürfen
key_source	Woher die Schlüssel geladen werden (siehe unten)
password_manager	Optionale Passwort-Manager-Konfiguration

Schritt 3: Entschlüsselungsschlüssel installieren

Schlüsselquellen (key_source)

Das System unterstützt drei Quellen für Entschlüsselungsschlüssel:

1. Keyring (key_source: "keyring")

Schlüssel werden im OS-Keyring gespeichert (empfohlen für Entwicklermaschinen).

# Schlüssel aus sicherer Quelle importieren
git-crypt unlock /pfad/zum/schlüssel-privat.key
git-crypt unlock /pfad/zum/schlüssel-dhive.key
git-crypt unlock /pfad/zum/schlüssel-bahn.key

# Alternativ: Schlüssel im Keyring speichern (via monorepo-cli)
monorepo-cli onboard --context privat --key-file /pfad/zum/schlüssel.key
monorepo-cli onboard --context dhive --key-file /pfad/zum/schlüssel.key

2. Datei (key_source: "file")

Schlüssel liegen als Dateien auf der Festplatte (nur für isolierte Maschinen).

# Schlüsseldateien an erwarteter Stelle ablegen
mkdir -p ~/.monorepo-keys/
cp schlüssel-privat.key ~/.monorepo-keys/git-crypt-privat.key
cp schlüssel-dhive.key ~/.monorepo-keys/git-crypt-dhive.key
cp schlüssel-bahn.key ~/.monorepo-keys/git-crypt-bahn.key

# Berechtigungen einschränken
chmod 600 ~/.monorepo-keys/*.key

3. Passwort-Manager (key_source: "password-manager")

Schlüssel werden bei Bedarf aus einem Passwort-Manager abgerufen.

Unterstützte Manager:

• Bitwarden (type: "bitwarden")
• 1Password (type: "1password")
• KeePass (type: "keepass")

# Bitwarden-Beispiel: Schlüssel sind im Vault "monorepo-keys" gespeichert
# Einträge haben das Format: monorepo-key-{context}
# z.B. monorepo-key-privat, monorepo-key-dhive, monorepo-key-bahn

# Login in Bitwarden (einmalig pro Session)
bw login

# Entschlüsselung wird automatisch über den SecretEncryptionManager gesteuert
monorepo-cli decrypt --context privat

Schritt 4: Secrets entschlüsseln

Nach Installation der Schlüssel werden die Secrets für autorisierte Kontexte entschlüsselt:

# Alle autorisierten Kontexte entschlüsseln
monorepo-cli decrypt --all

# Oder einzelne Kontexte
monorepo-cli decrypt --context privat
monorepo-cli decrypt --context dhive

Verhalten bei nicht-autorisierten Kontexten

Wenn eine Maschine keinen Schlüssel für einen Kontext besitzt:

• Die Secret-Dateien bleiben als verschlüsselte Binärdaten im Working Tree
• Der restliche Code und die Konfiguration des Kontexts sind lesbar
• Es wird keine Fehlermeldung ausgegeben, die den Inhalt offenlegt
• Das Repository bleibt voll funktionsfähig für die autorisierten Kontexte

Schritt 5: Einrichtung verifizieren

# Status der Verschlüsselung prüfen
monorepo-cli encrypt --status

# Erwartete Ausgabe für "dhive-laptop" (nur dhive autorisiert):
#   privat: verschlüsselt (kein Schlüssel)
#   dhive:  entschlüsselt ✓
#   bahn:   verschlüsselt (kein Schlüssel)
#   shared: entschlüsselt ✓

Typische Maschinenkontexte

Maschine	Autorisierte Kontexte	key_source
andre-hauptrechner	privat, dhive, bahn	keyring
dhive-laptop	dhive	password-manager
bahn-arbeitsrechner	bahn	keyring
familie-nas	privat	file

Sicherheitshinweise

1. Schlüssel niemals committen: Die Schlüsseldateien selbst gehören NICHT ins Repository
2. Maschinenkontext-Datei ist kein Secret: machine-context.yaml enthält nur das Mapping, keine Schlüssel
3. Minimaler Zugriff: Jede Maschine erhält nur die Schlüssel, die sie benötigt
4. Schlüsselrotation: Bei Kompromittierung eines Schlüssels → neuen Schlüssel generieren, alle autorisierten Maschinen aktualisieren, Secrets neu verschlüsseln

Troubleshooting

Dateien erscheinen als Binärdaten

Ursache: Schlüssel für den betreffenden Kontext nicht installiert.

Lösung: Schlüssel gemäß Schritt 3 installieren und monorepo-cli decrypt ausführen.

git-crypt meldet "not a git-crypt repo"

Ursache: git-crypt wurde im Repository noch nicht initialisiert.

Lösung: git-crypt init (nur beim erstmaligen Setup des Repositories nötig).

Merge-Konflikte in verschlüsselten Dateien

Ursache: Zwei Branches haben dieselbe Secret-Datei geändert.

Lösung: Der SecretEncryptionManager löst Merges auf verschlüsselter Ebene auf. Falls dies fehlschlägt:

monorepo-cli encrypt --resolve-merge <datei>