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

> Encrypted vault for API keys, credentials, and sensitive config.

# Secrets

Kazzle có một kho lưu trữ được mã hóa tích hợp sẵn để lưu trữ khóa API, thông tin đăng nhập cơ sở dữ liệu, token và các giá trị nhạy cảm khác mà ứng dụng của bạn cần. Secrets được mã hóa khi lưu trữ bằng AES-256-GCM sử dụng các khóa mã hóa dữ liệu được bao bọc bởi KMS — các giá trị văn bản thuần túy không bao giờ chạm vào cơ sở dữ liệu.

## Concepts

**Collections** nhóm các secrets liên quan lại với nhau (ví dụ: `stripe-keys`, `database-credentials`). Mỗi collection có một **slug** (chữ thường, có dấu gạch ngang) mà bạn tham chiếu trong các tệp cấu hình và lệnh CLI.

**Environments** là các phạm vi tùy chọn trong một collection (ví dụ: `production`, `staging`). Secrets có thể được giới hạn trong một môi trường cụ thể hoặc để ở cấp collection như các giá trị mặc định.

**Thứ tự phân giải:** khi phân giải secrets cho một collection + environment nhất định, secrets dành riêng cho môi trường sẽ ghi đè các secrets cấp collection có cùng tên. Điều này cho phép bạn chia sẻ hầu hết các secrets trên các môi trường trong khi ghi đè các giá trị cụ thể cho từng môi trường.

## Managing secrets

### In the app

Mở **Settings > Vault** để tạo collections, environments và secrets thông qua giao diện người dùng.

### With the AI

AI có thể tạo collections, tạo environments, lưu trữ secrets, di chuyển chúng giữa các phạm vi và xóa chúng cho bạn.

AI nhìn thấy tên secrets và siêu dữ liệu nhưng không nhìn thấy các giá trị được mã hóa.

### With the CLI

```bash theme={"theme":"material-theme-darker"}
# Export secrets as KEY=value lines
kazzle secrets.export --collection=stripe-keys --env=production
```

## Referencing secrets from your app

Trỏ `env` của một component tới một secret collection và environment trong `kazzle.config.ts`. Mỗi secret trong phạm vi đó được tiêm dưới dạng một biến env quy trình có tên khớp với tên secret:

```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` và `env.environment` là **slugs**, không phải tên hiển thị. Sử dụng `env.include` để tiêm chỉ một tập hợp con các secrets của collection:

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

## How secrets become env vars

Khi secrets được phân giải cho một component:

1. Collection được tìm thấy theo slug trong space của bạn
2. Secrets được giới hạn trong environment được chỉ định được tải
3. Secrets cấp collection (không có environment) được bao gồm như các giá trị mặc định
4. Secrets dành riêng cho môi trường ghi đè các secrets cấp collection có cùng tên
5. Các tham chiếu secret bên trong các giá trị được phân giải
6. Tên secrets được chuyển đổi thành định dạng biến env: chữ hoa, các ký tự không phải chữ và số trở thành dấu gạch dưới

Một secret có tên `Stripe Secret Key` trở thành `STRIPE_SECRET_KEY`.

Mỗi secret có một **body mode** xác định cách nó được tiêm:

* **`string`** secrets (khóa API, tokens, URI) được tiêm dưới dạng các chuỗi vô hướng thuần túy
* **`json`** secrets (cấu hình có cấu trúc) được tiêm dưới dạng các chuỗi JSON
* **`fields`** secrets (thông tin đăng nhập, các túi trường được gõ) được tiêm dưới dạng các chuỗi JSON

## When secrets are injected

| Context                        | Injected? | Details                                                                            |
| ------------------------------ | --------- | ---------------------------------------------------------------------------------- |
| **Deploy** (process component) | Yes       | Added as runtime environment variables in production                               |
| **Deploy** (UI component)      | Partial   | Only `VITE_*` prefixed secrets are passed at build time                            |
| **CLI** (`kazzle run`)         | Yes       | Injected into the command's environment                                            |
| **CLI** (`secrets.export`)     | Yes       | Exported as `KEY=value` lines                                                      |
| **Dev preview**                | Not yet   | The preview starter doesn't resolve component `env` yet — use `kazzle run` for now |

## Template references

Các giá trị secret có thể tham chiếu các trường secret khác bằng cú pháp tương tự mà Kazzle sử dụng ở nơi khác:

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

Các định dạng được hỗ trợ:

* `${secret.<uuid>.<field>}` — trường cụ thể hoặc đường dẫn JSON bên trong các giá trị secret hoặc tham số công cụ nơi các tham chiếu vault được bật.
* `${secret.<uuid>}` — toàn bộ body secret. Chỉ sử dụng khi một công cụ rõ ràng yêu cầu toàn bộ secret thô; không sử dụng cái này trong app env/config.

Các tham chiếu được phân giải sau khi secrets được tải. Các tham chiếu vòng tròn hoặc bị hỏng sẽ thất bại thay vì im lặng quay lại.