Saltar al contenido principal

​
Secretos

Kazzle tiene una bóveda encriptada integrada para almacenar claves API, credenciales de base de datos, tokens y otros valores sensibles que tu app necesita. Los secretos se encriptan en reposo con AES-256-GCM usando claves de encriptación de datos envueltas en KMS — los valores en texto plano nunca tocan la base de datos.

​
Conceptos

Colecciones agrupan secretos relacionados (p. ej. stripe-keys, database-credentials). Cada colección tiene un slug (minúsculas, con guiones) que referencias en archivos de configuración y comandos CLI. Entornos son alcances opcionales dentro de una colección (p. ej. production, staging). Los secretos pueden estar limitados a un entorno específico o dejarse a nivel de colección como valores por defecto. Orden de resolución: al resolver secretos para una colección + entorno dados, los secretos específicos del entorno anulan los secretos a nivel de colección con el mismo nombre. Esto te permite compartir la mayoría de secretos entre entornos mientras anuelas valores específicos por entorno.

​
Gestionar secretos

​
En la app

Abre Configuración > Bóveda para crear colecciones, entornos y secretos a través de la interfaz.

​
Con la IA

La IA puede crear colecciones, crear entornos, almacenar secretos, moverlos entre alcances y eliminarlos por ti. La IA ve los nombres y metadatos de los secretos pero no los valores encriptados.

​
Con la CLI

# Ejecuta un comando con secretos inyectados como variables de entorno
kazzle run --collection=stripe-keys --env=production -- bun run server.ts

# Exporta secretos como líneas KEY=value
kazzle secrets.export --collection=stripe-keys --env=production

​
Referenciar secretos desde tu app

Apunta el env de un componente a una colección de secretos y entorno en kazzle.config.ts. Cada secreto en ese alcance se inyecta como una variable de entorno de proceso cuyo nombre coincide con el nombre del secreto: 
import { defineConfig } from './kazzle.types';

export default defineConfig({
  components: [
    {
      name: 'API Server',
      type: 'process',
      path: './server',
      env: {
        collection: 'stripe-keys',
        environment: 'production'
      }
    }
  ]
});
env.collection y env.environment son slugs, no nombres para mostrar. Usa env.include para inyectar solo un subconjunto de los secretos de la colección: 
env: {
  collection: 'stripe-keys',
  environment: 'production',
  include: ['STRIPE_SECRET_KEY']
}

​
Cómo los secretos se convierten en variables de entorno

Cuando se resuelven secretos para un componente:
  1. La colección se encuentra por slug dentro de tu espacio
  2. Se cargan los secretos limitados al entorno especificado
  3. Los secretos a nivel de colección (sin entorno) se incluyen como valores por defecto
  4. Los secretos específicos del entorno anulan los de nivel de colección con el mismo nombre
  5. Las referencias de secretos dentro de valores se resuelven
  6. Los nombres de secretos se convierten al formato de variable de entorno: mayúsculas, los caracteres no alfanuméricos se convierten en guiones bajos
Un secreto llamado Stripe Secret Key se convierte en STRIPE_SECRET_KEY. Cada secreto tiene un modo de cuerpo que determina cómo se inyecta:
  • Los secretos string (claves API, tokens, URIs) se inyectan como cadenas escalares simples
  • Los secretos json (configuración estructurada) se inyectan como cadenas JSON
  • Los secretos fields (credenciales de inicio de sesión, bolsas de campos tipados) se inyectan como cadenas JSON

​
Cuándo se inyectan los secretos

Contexto¿Inyectado?Detalles
Deploy (componente de proceso)SíSe añade como variables de entorno en tiempo de ejecución en producción
Deploy (componente UI)ParcialSolo los secretos con prefijo VITE_* se pasan en tiempo de compilación
CLI (kazzle run)SíSe inyecta en el entorno del comando
CLI (secrets.export)SíSe exporta como líneas KEY=value
Vista previa de desarrolloAún noEl iniciador de vista previa aún no resuelve el env del componente — usa kazzle run por ahora

​
Referencias de plantilla

Los valores de secretos pueden referenciar otros campos de secretos con la misma sintaxis que Kazzle usa en otros lugares: 
postgresql://${secret.123e4567-e89b-12d3-a456-426614174000.username}:${secret.123e4567-e89b-12d3-a456-426614174000.password}@db.example.com:5432/mydb
Formatos soportados:
  • ${secret.<uuid>.<field>} — campo específico o ruta JSON. Usa este formato para env/config de app.
  • ${secret.<uuid>} — cuerpo de secreto completo. Usa solo cuando una herramienta te pida explícitamente el secreto completo sin procesar; no uses esto en env/config de app.
Las referencias se resuelven después de que se cargan los secretos. Las referencias circulares o rotas fallan en lugar de retroceder silenciosamente.