> ## 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 키, 데이터베이스 자격증명, 토큰 및 앱에 필요한 기타 민감한 값을 저장하기 위한 내장 암호화 저장소를 제공합니다. 시크릿은 KMS로 래핑된 데이터 암호화 키를 사용하여 AES-256-GCM으로 저장 시 암호화되며, 평문 값은 데이터베이스에 절대 저장되지 않습니다.

## 개념

**컬렉션**은 관련 시크릿을 함께 그룹화합니다(예: `stripe-keys`, `database-credentials`). 모든 컬렉션에는 설정 파일과 CLI 명령에서 참조하는 **슬러그**(소문자, 하이픈 구분)가 있습니다.

**환경**은 컬렉션 내의 선택적 범위입니다(예: `production`, `staging`). 시크릿은 특정 환경으로 범위를 지정하거나 컬렉션 수준에서 기본값으로 남겨둘 수 있습니다.

**해석 순서:** 주어진 컬렉션 + 환경에 대해 시크릿을 해석할 때, 환경별 시크릿이 같은 이름의 컬렉션 수준 시크릿을 재정의합니다. 이를 통해 대부분의 시크릿을 환경 간에 공유하면서 환경별로 특정 값을 재정의할 수 있습니다.

## 시크릿 관리

### 앱에서

**설정 > 저장소**를 열어 UI를 통해 컬렉션, 환경 및 시크릿을 생성합니다.

### AI와 함께

AI는 컬렉션을 생성하고, 환경을 생성하고, 시크릿을 저장하고, 범위 간에 이동하고, 삭제할 수 있습니다.

AI는 시크릿 이름과 메타데이터는 볼 수 있지만 암호화된 값은 볼 수 없습니다.

### CLI 사용

```bash theme={"theme":"material-theme-darker"}
# 시크릿을 KEY=value 줄로 내보내기
kazzle secrets.export --collection=stripe-keys --env=production
```

## 앱에서 시크릿 참조

`kazzle.config.ts`에서 컴포넌트의 `env`를 시크릿 컬렉션과 환경으로 지정합니다. 해당 범위의 모든 시크릿은 시크릿 이름과 일치하는 이름의 프로세스 환경 변수로 주입됩니다:

```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`는 **슬러그**이며, 표시 이름이 아닙니다. `env.include`를 사용하여 컬렉션의 시크릿 중 일부만 주입합니다:

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

## 시크릿이 환경 변수가 되는 방식

컴포넌트에 대해 시크릿이 해석될 때:

1. 슬러그로 스페이스 내에서 컬렉션을 찾습니다
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>}` — 전체 시크릿 본문. 도구가 전체 원본 시크릿을 명시적으로 요청할 때만 사용하며, 앱 env/config에서는 사용하지 마세요.

참조는 시크릿이 로드된 후 해석됩니다. 순환 또는 손상된 참조는 자동