# 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>
```