> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kazzle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

> Verschlüsselter Tresor für API-Schlüssel, Anmeldedaten und sensible Konfiguration.

# Secrets

Kazzle hat einen integrierten verschlüsselten Tresor zum Speichern von API-Schlüsseln, Datenbankzugangsdaten, Token und anderen sensiblen Werten, die deine App benötigt. Secrets werden im Ruhezustand mit AES-256-GCM verschlüsselt, wobei KMS-umhüllte Datenverschlüsselungsschlüssel verwendet werden — Klartextwerte gelangen niemals in die Datenbank.

## Konzepte

**Collections** gruppieren zusammenhängende Secrets (z. B. `stripe-keys`, `database-credentials`). Jede Collection hat einen **Slug** (Kleinbuchstaben, mit Bindestrichen), auf den du in Konfigurationsdateien und CLI-Befehlen verweist.

**Environments** sind optionale Bereiche innerhalb einer Collection (z. B. `production`, `staging`). Secrets können auf ein bestimmtes Environment beschränkt oder auf Collection-Ebene als Standardwerte belassen werden.

**Auflösungsreihenfolge:** Bei der Auflösung von Secrets für eine bestimmte Collection + Environment überschreiben umgebungsspezifische Secrets Collection-Secrets mit demselben Namen. Dies ermöglicht es dir, die meisten Secrets über Environments hinweg zu teilen und gleichzeitig bestimmte Werte pro Environment zu überschreiben.

## Secrets verwalten

### In der App

Öffne **Settings > Vault**, um Collections, Environments und Secrets über die Benutzeroberfläche zu erstellen.

### Mit der KI

Die KI kann Collections erstellen, Environments erstellen, Secrets speichern, sie zwischen Bereichen verschieben und sie für dich löschen.

Die KI sieht Secret-Namen und Metadaten, aber nicht die verschlüsselten Werte.

### Mit der CLI

```bash theme={"theme":"material-theme-darker"}
# Secrets als KEY=value-Zeilen exportieren
kazzle secrets.export --collection=stripe-keys --env=production
```

## Secrets aus deiner App referenzieren

Verweise mit der `env`-Eigenschaft einer Komponente auf eine Secret-Collection und ein Environment in `kazzle.config.ts`. Jedes Secret in diesem Bereich wird als Prozessumgebungsvariable eingefügt, deren Name dem Secret-Namen entspricht:

```typescript theme={"theme":"material-theme-darker"}
import { defineConfig } from '@kazzle/app';

export default defineConfig({
  components: [
    {
      name: 'API Server',
      type: 'process',
      path: './server',
      env: {
        collection: 'stripe-keys',
        environment: 'production'
      }
    }
  ]
});
```

`env.collection` und `env.environment` sind **Slugs**, keine Anzeigenamen. Verwende `env.include`, um nur eine Teilmenge der Secrets der Collection einzufügen:

```typescript theme={"theme":"material-theme-darker"}
env: {
  collection: 'stripe-keys',
  environment: 'production',
  include: ['STRIPE_SECRET_KEY']
}
```

## Wie Secrets zu Umgebungsvariablen werden

Wenn Secrets für eine Komponente aufgelöst werden:

1. Die Collection wird nach Slug in deinem Space gefunden
2. Secrets, die auf das angegebene Environment beschränkt sind, werden geladen
3. Collection-Secrets (ohne Environment) werden als Standardwerte einbezogen
4. Umgebungsspezifische Secrets überschreiben Collection-Secrets mit demselben Namen
5. Secret-Referenzen innerhalb von Werten werden aufgelöst
6. Secret-Namen werden in das Format der Umgebungsvariablen konvertiert: Großbuchstaben, nicht-alphanumerische Zeichen werden zu Unterstrichen

Ein Secret namens `Stripe Secret Key` wird zu `STRIPE_SECRET_KEY`.

Jedes Secret hat einen **Body-Modus**, der bestimmt, wie es eingefügt wird:

* **`string`** Secrets (API-Schlüssel, Token, URIs) werden als einfache Skalarzeichenfolgen eingefügt
* **`json`** Secrets (strukturierte Konfiguration) werden als JSON-Zeichenfolgen eingefügt
* **`fields`** Secrets (Anmeldedaten, typisierte Feldgruppen) werden als JSON-Zeichenfolgen eingefügt

## Wann Secrets eingefügt werden

| Kontext                         | Eingefügt? | Details                                                                                       |
| ------------------------------- | ---------- | --------------------------------------------------------------------------------------------- |
| **Deploy** (Process-Komponente) | Ja         | Wird als Laufzeit-Umgebungsvariablen in der Produktion hinzugefügt                            |
| **Deploy** (UI-Komponente)      | Teilweise  | Nur Secrets mit `VITE_*`-Präfix werden zur Build-Zeit übergeben                               |
| **CLI** (`kazzle run`)          | Ja         | Wird in die Umgebung des Befehls eingefügt                                                    |
| **CLI** (`secrets.export`)      | Ja         | Wird als `KEY=value`-Zeilen exportiert                                                        |
| **Dev-Vorschau**                | Noch nicht | Der Preview-Starter löst die Komponenten-`env` noch nicht auf — verwende vorerst `kazzle run` |

## Template-Referenzen

Secret-Werte können andere Secret-Felder mit der gleichen Syntax referenzieren, die Kazzle anderswo verwendet:

```
postgresql://${secret.123e4567-e89b-12d3-a456-426614174000.username}:${secret.123e4567-e89b-12d3-a456-426614174000.password}@db.example.com:5432/mydb
```

Unterstützte Formate:

* `${secret.<uuid>.<field>}` — spezifisches Feld oder JSON-Pfad innerhalb von Secret-Werten oder Tool-Parametern, wo Vault-Referenzen aktiviert sind.
* `${secret.<uuid>}` — gesamter Secret-Body. Verwende dies nur, wenn ein Tool explizit das gesamte rohe Secret anfordert; verwende dies nicht in App-Umgebung/Konfiguration.

Referenzen werden aufgelöst, nachdem Secrets geladen wurden. Zirkuläre oder unterbrochene Referenzen schlagen fehl, anstatt stillschweigend zurückzufallen.