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 Environment-spezifische 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 Einstellungen > 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

# Befehl mit Secrets als Umgebungsvariablen ausführen
kazzle run --collection=stripe-keys --env=production -- bun run server.ts

# Secrets als KEY=value-Zeilen exportieren
kazzle secrets.export --collection=stripe-keys --env=production

Secrets aus deiner App referenzieren

Verweise mit dem env 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:

import { defineConfig } from './kazzle.types';

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:

env: {
  collection: 'stripe-keys',
  environment: 'production',
  include: ['STRIPE_SECRET_KEY']
}

Wie Secrets zu Umgebungsvariablen werden

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

Die Collection wird nach Slug in deinem Space gefunden
Secrets, die auf das angegebene Environment beschränkt sind, werden geladen
Collection-Secrets (ohne Environment) werden als Standardwerte einbezogen
Environment-spezifische Secrets überschreiben Collection-Secrets mit demselben Namen
Secret-Referenzen innerhalb von Werten werden aufgelöst
Secret-Namen werden in das Umgebungsvariablenformat 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	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	In die Umgebung des Befehls eingefügt
CLI (`secrets.export`)	Ja	Als `KEY=value`-Zeilen exportiert
Dev-Vorschau	Noch nicht	Die Preview-Starter löst Component-`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. Verwende dieses Format für App-Umgebung/Konfiguration.
${secret.<uuid>} – gesamter Secret-Body. Verwende nur, wenn ein Tool explizit das gesamte Raw-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.

​Secrets

​Konzepte

​Secrets verwalten

​In der App

​Mit der KI

​Mit der CLI

​Secrets aus deiner App referenzieren

​Wie Secrets zu Umgebungsvariablen werden

​Wann Secrets eingefügt werden

​Template-Referenzen