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

# Secretos

> Bóveda cifrada para claves API, credenciales y configuración sensible.

# Secretos

Kazzle tiene una bóveda cifrada integrada para almacenar claves API, credenciales de base de datos, tokens y otros valores sensibles que tu aplicación necesita. Los secretos se cifran en reposo con AES-256-GCM usando claves de cifrado 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 ámbitos 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 aplicación

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 ámbitos y eliminarlos por ti.

La IA ve los nombres y metadatos de los secretos pero no los valores cifrados.

### Con la CLI

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

## Referenciar secretos desde tu aplicación

Apunta la propiedad `env` de un componente a una colección de secretos y entorno en `kazzle.config.ts`. Cada secreto en ese ámbito se inyecta como una variable de entorno de proceso cuyo nombre coincide con el nombre del secreto:

```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` y `env.environment` son **slugs**, no nombres para mostrar. Usa `env.include` para inyectar solo un subconjunto de los secretos de la colección:

```typescript theme={"theme":"material-theme-darker"}
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 de UI)      | Parcial     | Solo 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 desarrollo**     | Aún no      | El iniciador de vista previa aún no resuelve `env` de componentes — 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 dentro de valores de secretos o parámetros de herramientas donde las referencias de bóveda están habilitadas.
* `${secret.<uuid>}` — cuerpo de secreto completo. Úsalo solo cuando una herramienta te pida explícitamente el secreto completo sin procesar; no lo uses en configuración/entorno de aplicación.

Las referencias se resuelven después de que se cargan los secretos. Las referencias circulares o rotas fallan en lugar de retroceder silenciosamente.