Vai al contenuto principale

​
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 (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 opzionali 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 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 Impostazioni > Vault per creare collection, environment e segreti tramite l’interfaccia.

​
Con l’AI

L’AI può creare collection, creare environment, archiviare segreti, spostarli tra ambiti ed eliminarli per te. L’AI vede i nomi e i metadati dei segreti ma non i valori crittografati.

​
Con la CLI

# Esegui un comando con segreti iniettati come variabili d'ambiente
kazzle run --collection=stripe-keys --env=production -- bun run server.ts

# Esporta segreti come righe KEY=value
kazzle secrets.export --collection=stripe-keys --env=production

​
Referenziare 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 d’ambiente di processo il cui nome corrisponde al nome del segreto: 
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 sono slug, non nomi visualizzati. Usa env.include per iniettare solo un sottoinsieme dei segreti della collection: 
env: {
  collection: 'stripe-keys',
  environment: 'production',
  include: ['STRIPE_SECRET_KEY']
}

​
Come i segreti diventano variabili d’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 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 d’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, campi tipizzati) vengono iniettati come stringhe JSON

​
Quando i segreti vengono iniettati

ContestoIniettato?Dettagli
Deploy (componente process)SìAggiunto come variabili d’ambiente di runtime in produzione
Deploy (componente UI)ParzialeSolo 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
Anteprima devNon ancoraLo starter di anteprima non risolve ancora l’env del componente — usa kazzle run per ora

​
Riferimenti 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. Usa questo formato per env/config dell’app.
  • ${secret.<uuid>} — corpo intero del segreto. Usa solo quando uno strumento chiede esplicitamente il segreto grezzo completo; non usare in env/config dell’app.
I riferimenti vengono risolti dopo che i segreti sono stati caricati. I riferimenti circolari o interrotti falliscono invece di tornare silenziosamente indietro.