190 lines
7.0 KiB
Markdown
190 lines
7.0 KiB
Markdown
# 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](https://github.com/AGWA/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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```yaml
|
|
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).
|
|
|
|
```bash
|
|
# 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).
|
|
|
|
```bash
|
|
# 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"`)
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
monorepo-cli encrypt --resolve-merge <datei>
|
|
```
|