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

# Rahasia

> Vault terenkripsi untuk kunci API, kredensial, dan konfigurasi sensitif.

# Rahasia

Kazzle memiliki vault terenkripsi bawaan untuk menyimpan kunci API, kredensial database, token, dan nilai sensitif lainnya yang dibutuhkan aplikasi Anda. Rahasia dienkripsi saat istirahat dengan AES-256-GCM menggunakan kunci enkripsi data yang dibungkus KMS — nilai plaintext tidak pernah menyentuh database.

## Konsep

**Koleksi** mengelompokkan rahasia terkait bersama (misalnya `stripe-keys`, `database-credentials`). Setiap koleksi memiliki **slug** (huruf kecil, dengan tanda hubung) yang Anda referensikan dalam file konfigurasi dan perintah CLI.

**Lingkungan** adalah cakupan opsional dalam koleksi (misalnya `production`, `staging`). Rahasia dapat dibatasi ke lingkungan tertentu atau dibiarkan di tingkat koleksi sebagai default.

**Urutan resolusi:** saat menyelesaikan rahasia untuk koleksi + lingkungan tertentu, rahasia khusus lingkungan menimpa rahasia tingkat koleksi dengan nama yang sama. Ini memungkinkan Anda berbagi sebagian besar rahasia di seluruh lingkungan sambil menimpa nilai tertentu per lingkungan.

## Mengelola rahasia

### Di aplikasi

Buka **Settings > Vault** untuk membuat koleksi, lingkungan, dan rahasia melalui UI.

### Dengan AI

AI dapat membuat koleksi, membuat lingkungan, menyimpan rahasia, memindahkannya antar cakupan, dan menghapusnya untuk Anda.

AI melihat nama dan metadata rahasia tetapi bukan nilai terenkripsi.

### Dengan CLI

```bash theme={"theme":"material-theme-darker"}
# Ekspor rahasia sebagai baris KEY=value
kazzle secrets.export --collection=stripe-keys --env=production
```

## Mereferensikan rahasia dari aplikasi Anda

Arahkan `env` komponen ke koleksi rahasia dan lingkungan dalam `kazzle.config.ts`. Setiap rahasia dalam cakupan itu disuntikkan sebagai variabel env proses yang namanya cocok dengan nama rahasia:

```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` dan `env.environment` adalah **slug**, bukan nama tampilan. Gunakan `env.include` untuk menyuntikkan hanya sebagian dari rahasia koleksi:

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

## Bagaimana rahasia menjadi variabel env

Saat rahasia diselesaikan untuk komponen:

1. Koleksi ditemukan berdasarkan slug dalam space Anda
2. Rahasia yang dibatasi ke lingkungan yang ditentukan dimuat
3. Rahasia tingkat koleksi (tanpa lingkungan) disertakan sebagai default
4. Rahasia khusus lingkungan menimpa yang tingkat koleksi dengan nama yang sama
5. Referensi rahasia di dalam nilai diselesaikan
6. Nama rahasia dikonversi ke format variabel env: huruf besar, karakter non-alfanumerik menjadi garis bawah

Rahasia bernama `Stripe Secret Key` menjadi `STRIPE_SECRET_KEY`.

Setiap rahasia memiliki **mode body** yang menentukan cara penyuntikannya:

* Rahasia **`string`** (kunci API, token, URI) disuntikkan sebagai string skalar biasa
* Rahasia **`json`** (konfigurasi terstruktur) disuntikkan sebagai string JSON
* Rahasia **`fields`** (kredensial login, tas bidang yang diketik) disuntikkan sebagai string JSON

## Saat rahasia disuntikkan

| Konteks                      | Disuntikkan? | Detail                                                                                     |
| ---------------------------- | ------------ | ------------------------------------------------------------------------------------------ |
| **Deploy** (komponen proses) | Ya           | Ditambahkan sebagai variabel lingkungan runtime dalam produksi                             |
| **Deploy** (komponen UI)     | Sebagian     | Hanya rahasia dengan awalan `VITE_*` yang dilewatkan saat waktu build                      |
| **CLI** (`kazzle run`)       | Ya           | Disuntikkan ke lingkungan perintah                                                         |
| **CLI** (`secrets.export`)   | Ya           | Diekspor sebagai baris `KEY=value`                                                         |
| **Pratinjau dev**            | Belum        | Starter pratinjau belum menyelesaikan `env` komponen — gunakan `kazzle run` untuk saat ini |

## Referensi template

Nilai rahasia dapat mereferensikan bidang rahasia lain dengan sintaks yang sama yang digunakan Kazzle di tempat lain:

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

Format yang didukung:

* `${secret.<uuid>.<field>}` — bidang tertentu atau jalur JSON di dalam nilai rahasia atau parameter alat tempat referensi vault diaktifkan.
* `${secret.<uuid>}` — seluruh badan rahasia. Gunakan hanya saat alat secara eksplisit meminta seluruh rahasia mentah; jangan gunakan ini dalam env/konfigurasi aplikasi.

Referensi diselesaikan setelah rahasia dimuat. Referensi melingkar atau rusak gagal daripada diam-diam kembali.