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

# Секрети

> Зашифрований сейф для ключів API, облікових даних та конфіденційної конфігурації.

# Секрети

Kazzle має вбудований зашифрований сейф для зберігання ключів API, облікових даних баз даних, токенів та інших конфіденційних значень, які потребує ваш додаток. Секрети зашифровані в спокої за допомогою AES-256-GCM з ключами шифрування даних, обгорнутими KMS — значення у відкритому вигляді ніколи не потрапляють до бази даних.

## Концепції

**Колекції** групують пов'язані секрети разом (наприклад `stripe-keys`, `database-credentials`). Кожна колекція має **slug** (малі літери, через дефіс), на який ви посилаєтесь у файлах конфігурації та командах CLI.

**Середовища** — це необов'язкові області видимості в межах колекції (наприклад `production`, `staging`). Секрети можуть бути обмежені конкретним середовищем або залишатися на рівні колекції як значення за замовчуванням.

**Порядок розв'язання:** під час розв'язання секретів для заданої колекції + середовища секрети, специфічні для середовища, перевизначають секрети на рівні колекції з тим самим іменем. Це дозволяє вам ділитися більшістю секретів між середовищами, перевизначаючи конкретні значення для кожного середовища.

## Управління секретами

### У додатку

Відкрийте **Параметри > Сейф**, щоб створювати колекції, середовища та секрети через інтерфейс.

### За допомогою ШІ

ШІ може створювати колекції, створювати середовища, зберігати секрети, переміщувати їх між областями видимості та видаляти їх для вас.

ШІ бачить імена та метадані секретів, але не зашифровані значення.

### За допомогою CLI

```bash theme={"theme":"material-theme-darker"}
# Експортувати секрети як рядки KEY=value
kazzle secrets.export --collection=stripe-keys --env=production
```

## Посилання на секрети з вашого додатку

Вкажіть `env` компонента на колекцію секретів та середовище в `kazzle.config.ts`. Кожен секрет у цій області видимості вводиться як змінна середовища процесу, ім'я якої відповідає імені секрету:

```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` та `env.environment` — це **slugs**, а не імена для відображення. Використовуйте `env.include`, щоб вводити лише підмножину секретів колекції:

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

## Як секрети стають змінними середовища

Коли секрети розв'язуються для компонента:

1. Колекція знаходиться за slug у вашому простору
2. Завантажуються секрети, обмежені вказаним середовищем
3. Секрети на рівні колекції (без середовища) включаються як значення за замовчуванням
4. Секрети, специфічні для середовища, перевизначають секрети на рівні колекції з тим самим іменем
5. Посилання на секрети всередині значень розв'язуються
6. Імена секретів перетворюються у формат змінної середовища: великі літери, не буквено-цифрові символи стають підкресленнями

Секрет з іменем `Stripe Secret Key` стає `STRIPE_SECRET_KEY`.

Кожен секрет має **режим тіла**, який визначає, як він вводиться:

* Секрети **`string`** (ключі API, токени, URI) вводяться як звичайні скалярні рядки
* Секрети **`json`** (структурована конфігурація) вводяться як рядки JSON
* Секрети **`fields`** (облікові дані для входу, типізовані мішки полів) вводяться як рядки JSON

## Коли вводяться секрети

| Контекст                            | Введено? | Деталі                                                                                                       |
| ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| **Розгортання** (компонент процесу) | Так      | Додано як змінні середовища виконання у виробництві                                                          |
| **Розгортання** (компонент UI)      | Частково | Лише секрети з префіксом `VITE_*` передаються під час збирання                                               |
| **CLI** (`kazzle run`)              | Так      | Введено в середовище команди                                                                                 |
| **CLI** (`secrets.export`)          | Так      | Експортовано як рядки `KEY=value`                                                                            |
| **Попередній перегляд розробки**    | Ще ні    | Стартер попереднього перегляду ще не розв'язує компонент `env` — використовуйте `kazzle run` на даний момент |

## Посилання на шаблони

Значення секретів можуть посилатися на інші поля секретів з тим самим синтаксисом, який Kazzle використовує в інших місцях:

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

Підтримувані формати:

* `${secret.<uuid>.<field>}` — конкретне поле або шлях JSON всередині значень секретів або параметрів інструменту, де увімкнено посилання на сейф.
* `${secret.<uuid>}` — все тіло секрету. Використовуйте лише коли інструмент явно запитує весь сирий секрет; не використовуйте це в конфігурації/середовищі додатку.

Посилання розв'язуються після завантаження секретів. Циклічні або розірвані посилання призводять до помилки замість мовчазного повернення.