Segredos

Kazzle tem 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 envolvidas 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 > Vault 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

# Execute um comando com segredos injetados como variáveis de ambiente
kazzle run --collection=stripe-keys --env=production -- bun run server.ts

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

import { defineConfig } from './kazzle.types';

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:

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:

A coleção é encontrada pelo slug dentro do seu espaço
Segredos limitados ao ambiente especificado são carregados
Segredos no nível da coleção (sem ambiente) são incluídos como padrões
Segredos específicos do ambiente substituem os no nível da coleção com o mesmo nome
Referências de segredos dentro de valores são resolvidas
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 de processo)	Sim	Adicionado como variáveis de ambiente em tempo de execução na produção
Deploy (componente de 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. Use este formato para env/config de app.
${secret.<uuid>} — corpo do segredo inteiro. Use apenas quando uma ferramenta pedir explicitamente pelo segredo bruto inteiro; não use isso em env/config de app.

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

​Segredos

​Conceitos

​Gerenciando segredos

​No app

​Com a IA

​Com a CLI

​Referenciando segredos do seu app

​Como segredos se tornam variáveis de ambiente

​Quando segredos são injetados

​Referências de template