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

# Segredos

> Cofre criptografado para chaves de API, credenciais e configurações sensíveis.

# Segredos

Kazzle possui um cofre criptografado integrado para armazenar chaves de API, credenciais de banco de dados, tokens e outros valores sensíveis que seu app precisa. Os segredos são criptografados em repouso com AES-256-GCM usando chaves de criptografia de dados encapsuladas por KMS — valores em texto plano nunca tocam o banco de dados.

## Conceitos

**Coleções** agrupam segredos relacionados (ex: `stripe-keys`, `database-credentials`). Cada coleção tem um **slug** (minúsculas, com hífens) que você referencia em arquivos de configuração e comandos CLI.

**Ambientes** são escopos opcionais dentro de uma coleção (ex: `production`, `staging`). Os segredos podem ser limitados a um ambiente específico ou deixados no nível da coleção como padrões.

**Ordem de resolução:** ao resolver segredos para uma determinada coleção + ambiente, segredos específicos do ambiente substituem segredos no nível da coleção com o mesmo nome. Isso permite compartilhar a maioria dos segredos entre ambientes enquanto substitui valores específicos por ambiente.

## Gerenciando segredos

### No app

Abra **Configurações > Cofre** para criar coleções, ambientes e segredos pela interface.

### Com a IA

A IA pode criar coleções, criar ambientes, armazenar segredos, movê-los entre escopos e deletá-los para você.

A IA vê nomes e metadados dos segredos, mas não os valores criptografados.

### Com a CLI

```bash theme={"theme":"material-theme-darker"}
# Exportar segredos como linhas KEY=value
kazzle secrets.export --collection=stripe-keys --env=production
```

## Referenciando segredos do seu app

Aponte o `env` de um componente para uma coleção de segredos e ambiente em `kazzle.config.ts`. Cada segredo nesse escopo é injetado como uma variável de ambiente de processo cujo nome corresponde ao nome do segredo:

```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` e `env.environment` são **slugs**, não nomes de exibição. Use `env.include` para injetar apenas um subconjunto dos segredos da coleção:

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

## Como segredos se tornam variáveis de ambiente

Quando segredos são resolvidos para um componente:

1. A coleção é encontrada pelo slug dentro do seu espaço
2. Segredos limitados ao ambiente especificado são carregados
3. Segredos no nível da coleção (sem ambiente) são incluídos como padrões
4. Segredos específicos do ambiente substituem os no nível da coleção com o mesmo nome
5. Referências de segredos dentro de valores são resolvidas
6. Nomes de segredos são convertidos para formato de variável de ambiente: maiúsculas, caracteres não alfanuméricos se tornam underscores

Um segredo chamado `Stripe Secret Key` se torna `STRIPE_SECRET_KEY`.

Cada segredo tem um **modo de corpo** que determina como é injetado:

* Segredos **`string`** (chaves de API, tokens, URIs) são injetados como strings escalares simples
* Segredos **`json`** (configuração estruturada) são injetados como strings JSON
* Segredos **`fields`** (credenciais de login, bolsas de campos tipados) são injetados como strings JSON

## Quando segredos são injetados

| Contexto                            | Injetado? | Detalhes                                                                                           |
| ----------------------------------- | --------- | -------------------------------------------------------------------------------------------------- |
| **Deploy** (componente process)     | Sim       | Adicionado como variáveis de ambiente em tempo de execução na produção                             |
| **Deploy** (componente UI)          | Parcial   | Apenas segredos com prefixo `VITE_*` são passados em tempo de compilação                           |
| **CLI** (`kazzle run`)              | Sim       | Injetado no ambiente do comando                                                                    |
| **CLI** (`secrets.export`)          | Sim       | Exportado como linhas `KEY=value`                                                                  |
| **Visualização de desenvolvimento** | Ainda não | O iniciador de visualização ainda não resolve `env` de componentes — use `kazzle run` por enquanto |

## Referências de template

Valores de segredos podem referenciar outros campos de segredos com a mesma sintaxe que Kazzle usa em outros lugares:

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

Formatos suportados:

* `${secret.<uuid>.<field>}` — campo específico ou caminho JSON dentro de valores de segredos ou parâmetros de ferramentas onde referências de cofre estão habilitadas.
* `${secret.<uuid>}` — corpo inteiro do segredo. Use apenas quando uma ferramenta solicita explicitamente o segredo bruto inteiro; não use isso em env/config do app.

Referências são resolvidas após os segredos serem carregados. Referências circulares ou quebradas falham em vez de retornar silenciosamente.