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

> API keys, credentials, और sensitive config के लिए encrypted vault।

# Secrets

Kazzle में एक built-in encrypted vault है जो API keys, database credentials, tokens, और अन्य sensitive values को store करता है जिनकी आपके app को जरूरत है। Secrets को AES-256-GCM से encrypt किया जाता है KMS-wrapped data encryption keys का उपयोग करके — plaintext values कभी database को touch नहीं करते।

## Concepts

**Collections** related secrets को एक साथ group करते हैं (जैसे `stripe-keys`, `database-credentials`)। हर collection का एक **slug** होता है (lowercase, hyphenated) जिसे आप config files और CLI commands में reference करते हैं।

**Environments** एक collection के अंदर optional scopes हैं (जैसे `production`, `staging`)। Secrets को एक specific environment के लिए scope किया जा सकता है या collection level पर defaults के रूप में रखा जा सकता है।

**Resolution order:** जब किसी दिए गए collection + environment के लिए secrets को resolve किया जाता है, तो environment-specific secrets उसी नाम वाले collection-level secrets को override करते हैं। यह आपको ज्यादातर secrets को environments में share करने देता है जबकि specific values को per-environment override करते हैं।

## Managing secrets

### App में

**Settings > Vault** खोलें collections, environments, और secrets को UI के through create करने के लिए।

### AI के साथ

AI आपके लिए collections create कर सकता है, environments create कर सकता है, secrets store कर सकता है, उन्हें scopes के बीच move कर सकता है, और उन्हें delete कर सकता है।

AI secret names और metadata देख सकता है लेकिन encrypted values नहीं।

### CLI के साथ

```bash theme={"theme":"material-theme-darker"}
# Secrets को KEY=value lines के रूप में export करें
kazzle secrets.export --collection=stripe-keys --env=production
```

## अपने app से secrets को reference करना

`kazzle.config.ts` में एक component के `env` को एक secret collection और environment पर point करें। उस scope में हर secret को एक process env var के रूप में inject किया जाता है जिसका नाम secret name से match करता है:

```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** हैं, display names नहीं। Collection के secrets का केवल एक subset inject करने के लिए `env.include` का उपयोग करें:

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

## Secrets कैसे env vars बनते हैं

जब एक component के लिए secrets को resolve किया जाता है:

1. Collection को slug के द्वारा आपके space में find किया जाता है
2. Specified environment के लिए scoped secrets को load किया जाता है
3. Collection-level secrets (कोई environment नहीं) को defaults के रूप में include किया जाता है
4. Environment-specific secrets उसी नाम वाले collection-level ones को override करते हैं
5. Values के अंदर secret references को resolve किया जाता है
6. Secret names को env var format में convert किया जाता है: uppercased, non-alphanumeric characters underscores बन जाते हैं

`Stripe Secret Key` नाम वाला secret `STRIPE_SECRET_KEY` बन जाता है।

हर secret का एक **body mode** होता है जो यह determine करता है कि इसे कैसे inject किया जाता है:

* **`string`** secrets (API keys, tokens, URIs) को plain scalar strings के रूप में inject किया जाता है
* **`json`** secrets (structured config) को JSON strings के रूप में inject किया जाता है
* **`fields`** secrets (login credentials, typed field bags) को JSON strings के रूप में inject किया जाता है

## जब secrets को inject किया जाता है

| Context                        | Injected? | Details                                                                                          |
| ------------------------------ | --------- | ------------------------------------------------------------------------------------------------ |
| **Deploy** (process component) | Yes       | Production में runtime environment variables के रूप में add किए जाते हैं                         |
| **Deploy** (UI component)      | Partial   | केवल `VITE_*` prefixed secrets को build time पर pass किया जाता है                                |
| **CLI** (`kazzle run`)         | Yes       | Command के environment में inject किए जाते हैं                                                   |
| **CLI** (`secrets.export`)     | Yes       | `KEY=value` lines के रूप में export किए जाते हैं                                                 |
| **Dev preview**                | Not yet   | Preview starter अभी component `env` को resolve नहीं करता — अभी के लिए `kazzle run` का उपयोग करें |

## Template references

Secret values अन्य secret fields को reference कर सकते हैं उसी syntax के साथ जो Kazzle अन्य जगहों पर उपयोग करता है:

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

Supported formats:

* `${secret.<uuid>.<field>}` — specific field या JSON path secret values या tool parameters के अंदर जहां vault refs enabled हैं।
* `${secret.<uuid>}` — whole secret body। केवल तब उपयोग करें जब कोई tool explicitly पूरे raw secret के लिए पूछे; इसे app env/config में उपयोग न करें।

References को secrets load होने के बाद resolve किया जाता है। Circular या broken references fail हो जाते हैं silently fallback करने की बजाय।