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

# Sekrety

> Zaszyfrowana skarbnica dla kluczy API, poświadczeń i wrażliwych konfiguracji.

# Sekrety

Kazzle ma wbudowaną zaszyfrowaną skarbnicę do przechowywania kluczy API, poświadczeń bazy danych, tokenów i innych wrażliwych wartości, których potrzebuje Twoja aplikacja. Sekrety są szyfrowane w spoczynku za pomocą AES-256-GCM przy użyciu kluczy szyfrowania danych zawinięte w KMS — wartości w postaci zwykłego tekstu nigdy nie trafiają do bazy danych.

## Koncepcje

**Kolekcje** grupują powiązane sekrety razem (np. `stripe-keys`, `database-credentials`). Każda kolekcja ma **slug** (małe litery, z myślnikami), do którego odwołujesz się w plikach konfiguracyjnych i poleceniach CLI.

**Środowiska** to opcjonalne zakresy w obrębie kolekcji (np. `production`, `staging`). Sekrety mogą być ograniczone do określonego środowiska lub pozostawione na poziomie kolekcji jako wartości domyślne.

**Kolejność rozwiązywania:** podczas rozwiązywania sekretów dla danej kolekcji + środowiska, sekrety specyficzne dla środowiska zastępują sekrety na poziomie kolekcji o tej samej nazwie. Pozwala to na udostępnianie większości sekretów w różnych środowiskach przy jednoczesnym zastępowaniu określonych wartości dla każdego środowiska.

## Zarządzanie sekretami

### W aplikacji

Otwórz **Ustawienia > Skarbnica**, aby tworzyć kolekcje, środowiska i sekrety za pośrednictwem interfejsu użytkownika.

### Za pomocą AI

AI może tworzyć kolekcje, tworzyć środowiska, przechowywać sekrety, przenosić je między zakresami i usuwać je dla Ciebie.

AI widzi nazwy sekretów i metadane, ale nie zaszyfrowane wartości.

### Za pomocą CLI

```bash theme={"theme":"material-theme-darker"}
# Eksportuj sekrety jako linie KEY=value
kazzle secrets.export --collection=stripe-keys --env=production
```

## Odwoływanie się do sekretów z Twojej aplikacji

Wskaż `env` komponentu na kolekcję sekretów i środowisko w `kazzle.config.ts`. Każdy sekret w tym zakresie jest wstrzykiwany jako zmienna środowiskowa procesu, której nazwa odpowiada nazwie sekretu:

```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` i `env.environment` to **slugi**, nie nazwy wyświetlane. Użyj `env.include`, aby wstrzyknąć tylko podzbiór sekretów kolekcji:

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

## Jak sekrety stają się zmiennymi środowiskowymi

Gdy sekrety są rozwiązywane dla komponentu:

1. Kolekcja jest wyszukiwana po slugu w Twojej przestrzeni
2. Sekrety ograniczone do określonego środowiska są ładowane
3. Sekrety na poziomie kolekcji (bez środowiska) są dołączane jako wartości domyślne
4. Sekrety specyficzne dla środowiska zastępują sekrety na poziomie kolekcji o tej samej nazwie
5. Odwołania do sekretów wewnątrz wartości są rozwiązywane
6. Nazwy sekretów są konwertowane na format zmiennej środowiskowej: wielkie litery, znaki niealfanumeryczne stają się podkreśleniami

Sekret o nazwie `Stripe Secret Key` staje się `STRIPE_SECRET_KEY`.

Każdy sekret ma **tryb treści**, który określa sposób jego wstrzyknięcia:

* Sekrety **`string`** (klucze API, tokeny, URI) są wstrzykiwane jako zwykłe skalarne ciągi znaków
* Sekrety **`json`** (konfiguracja strukturalna) są wstrzykiwane jako ciągi JSON
* Sekrety **`fields`** (poświadczenia logowania, worki pól typowanych) są wstrzykiwane jako ciągi JSON

## Kiedy sekrety są wstrzykiwane

| Kontekst                          | Wstrzykiwane? | Szczegóły                                                                             |
| --------------------------------- | ------------- | ------------------------------------------------------------------------------------- |
| **Wdrażanie** (komponent procesu) | Tak           | Dodane jako zmienne środowiskowe czasu wykonywania w produkcji                        |
| **Wdrażanie** (komponent UI)      | Częściowo     | Tylko sekrety z prefiksem `VITE_*` są przekazywane w czasie kompilacji                |
| **CLI** (`kazzle run`)            | Tak           | Wstrzykiwane do środowiska polecenia                                                  |
| **CLI** (`secrets.export`)        | Tak           | Eksportowane jako linie `KEY=value`                                                   |
| **Podgląd deweloperski**          | Jeszcze nie   | Starter podglądu nie rozwiązuje jeszcze `env` komponentu — na razie użyj `kazzle run` |

## Odwołania do szablonów

Wartości sekretów mogą odwoływać się do innych pól sekretów przy użyciu tej samej składni, którą Kazzle używa w innym miejscu:

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

Obsługiwane formaty:

* `${secret.<uuid>.<field>}` — określone pole lub ścieżka JSON wewnątrz wartości sekretów lub parametrów narzędzia, gdzie odwołania do skarbnic są włączone.
* `${secret.<uuid>}` — całe ciało sekretu. Używaj tylko wtedy, gdy narzędzie wyraźnie prosi o cały surowy sekret; nie używaj tego w konfiguracji/env aplikacji.

Odwołania są rozwiązywane po załadowaniu sekretów. Odwołania cykliczne lub uszkodzone kończą się niepowodzeniem zamiast dyskretnie wracać do wartości domyślnych.