> ## 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`）。すべてのコレクションには**スラッグ**（小文字、ハイフン区切り）があり、これを設定ファイルと CLI コマンドで参照します。

**環境**はコレクション内のオプションのスコープです（例：`production`、`staging`）。シークレットは特定の環境にスコープするか、コレクション レベルのデフォルトとして保持できます。

**解決順序：** 指定されたコレクション + 環境のシークレットを解決する場合、環境固有のシークレットは同じ名前のコレクション レベルのシークレットをオーバーライドします。これにより、ほとんどのシークレットを環境全体で共有しながら、環境ごとに特定の値をオーバーライドできます。

## シークレットの管理

### アプリ内

**Settings > Vault** を開いて、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 では使用しないでください。

参照はシークレットが読み込まれた後に解決されます。循環参照または壊れた参照は、サイレント フォールバックの代わりに失敗します。