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

# Segreti

> Vault crittografato per chiavi API, credenziali e configurazioni sensibili.

# Segreti

Kazzle ha un vault crittografato integrato per archiviare chiavi API, credenziali di database, token e altri valori sensibili di cui la tua app ha bisogno. I segreti sono crittografati a riposo con AES-256-GCM utilizzando chiavi di crittografia dei dati avvolte da KMS — i valori in chiaro non toccano mai il database.

## Concetti

**Collections** raggruppano segreti correlati insieme (ad es. `stripe-keys`, `database-credentials`). Ogni collection ha uno **slug** (minuscolo, con trattini) che referenzi nei file di configurazione e nei comandi CLI.

**Environments** sono ambiti facoltativi all'interno di una collection (ad es. `production`, `staging`). I segreti possono essere limitati a un ambiente specifico o lasciati a livello di collection come valori predefiniti.

**Ordine di risoluzione:** quando si risolvono i segreti per una determinata collection + environment, i segreti specifici dell'ambiente sovrascrivono i segreti a livello di collection con lo stesso nome. Questo ti permette di condividere la maggior parte dei segreti tra gli ambienti mentre sovrascrivi valori specifici per ambiente.

## Gestione dei segreti

### Nell'app

Apri **Settings > Vault** per creare collection, environment e segreti tramite l'interfaccia utente.

### Con l'AI

L'AI può creare collection, creare environment, archiviare segreti, spostarli tra ambiti ed eliminarli per te.

L'AI vede i nomi dei segreti e i metadati ma non i valori crittografati.

### Con la CLI

```bash theme={"theme":"material-theme-darker"}
# Esporta i segreti come righe KEY=value
kazzle secrets.export --collection=stripe-keys --env=production
```

## Referenziare i segreti dalla tua app

Punta l'`env` di un componente a una collection di segreti e a un environment in `kazzle.config.ts`. Ogni segreto in quell'ambito viene iniettato come variabile di ambiente di processo il cui nome corrisponde al nome del segreto:

```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` sono **slug**, non nomi visualizzati. Usa `env.include` per iniettare solo un sottoinsieme dei segreti della collection:

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

## Come i segreti diventano variabili di ambiente

Quando i segreti vengono risolti per un componente:

1. La collection viene trovata per slug all'interno del tuo space
2. I segreti limitati all'environment specificato vengono caricati
3. I segreti a livello di collection (senza environment) vengono inclusi come valori predefiniti
4. I segreti specifici dell'environment sovrascrivono quelli a livello di collection con lo stesso nome
5. I riferimenti ai segreti all'interno dei valori vengono risolti
6. I nomi dei segreti vengono convertiti nel formato di variabile di ambiente: maiuscoli, i caratteri non alfanumerici diventano trattini bassi

Un segreto denominato `Stripe Secret Key` diventa `STRIPE_SECRET_KEY`.

Ogni segreto ha una **body mode** che determina come viene iniettato:

* I segreti **`string`** (chiavi API, token, URI) vengono iniettati come stringhe scalari semplici
* I segreti **`json`** (configurazione strutturata) vengono iniettati come stringhe JSON
* I segreti **`fields`** (credenziali di accesso, borse di campi tipizzati) vengono iniettati come stringhe JSON

## Quando i segreti vengono iniettati

| Contesto                        | Iniettato? | Dettagli                                                                                   |
| ------------------------------- | ---------- | ------------------------------------------------------------------------------------------ |
| **Deploy** (componente process) | Sì         | Aggiunto come variabili di ambiente di runtime in produzione                               |
| **Deploy** (componente UI)      | Parziale   | Solo i segreti con prefisso `VITE_*` vengono passati al momento della build                |
| **CLI** (`kazzle run`)          | Sì         | Iniettato nell'ambiente del comando                                                        |
| **CLI** (`secrets.export`)      | Sì         | Esportato come righe `KEY=value`                                                           |
| **Dev preview**                 | Non ancora | Lo starter di preview non risolve ancora l'`env` del componente — usa `kazzle run` per ora |

## Riferimenti ai template

I valori dei segreti possono referenziare altri campi di segreti con la stessa sintassi che Kazzle usa altrove:

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

Formati supportati:

* `${secret.<uuid>.<field>}` — campo specifico o percorso JSON all'interno di valori di segreti o parametri di strumenti dove i riferimenti al vault sono abilitati.
* `${secret.<uuid>}` — corpo del segreto intero. Usa solo quando uno strumento chiede esplicitamente il segreto grezzo intero; non usare questo nella configurazione/env dell'app.

I riferimenti vengono risolti dopo che i segreti sono stati caricati. I riferimenti circolari o interrotti falliscono invece di tornare silenziosamente indietro.