Secrets: le chiavi che servono al codice del sito

#Cos'è un secret

Un segreto è un valore con un nome. Il valore di solito è una chiave API: la password che un programma usa per parlare con un altro, come la chiave che ti dà un servizio di mailing. Il nome è il modo in cui il codice del tuo sito la richiede, per esempio MAILING_LIST_KEY.

La parte del tuo sito che legge i segreti gira sul server, dietro le sue route (indirizzi sotto /api/ che eseguono codice invece di mostrare una pagina). Il valore resta lì. Non è nelle pagine del sito, non viene inviato ai browser dei visitatori e non è nel codice che puoi scaricare.

Una volta salvato, un valore non può più essere mostrato, da nessuno, nemmeno da te. Lo studio conserva solo il nome, chi l'ha salvato e quando. Tieni una tua copia in un posto sicuro, come un gestore di password.

Hai bisogno dei segreti solo quando il codice del tuo sito lavora con qualcosa che richiede una chiave. Un sito vetrina con un modulo di contatto non ne ha bisogno.

#Prima di iniziare

• Pubblica il sito una volta. I segreti sono conservati solo sul sito pubblicato, mai dallo studio. Fino alla prima pubblicazione la pagina mostra Publish the site first e non si può aggiungere nulla.
• Controlla il tuo ruolo. Editor, Admin e Owner aggiungono, modificano ed eliminano i segreti. I Viewer vedono i nomi e quando ognuno è stato salvato.
• Scegli un nome. Lettere, cifre e trattini bassi, a partire da una lettera, fino a 128 caratteri. Di solito si usano le maiuscole con i trattini bassi. I nomi che iniziano con BRIKS_ sono riservati allo studio.
• Attenzione ai limiti. Un valore può arrivare a 5 KB, abbastanza per qualsiasi chiave o certificato. Un progetto contiene fino a 100 segreti, compresi quelli dello studio stesso.

#Aggiungi un segreto

#Importane diversi da un file .env

Un file .env è un file di testo semplice con righe NOME=valore, una per ogni segreto. Gli sviluppatori spesso ne tengono uno. Se ne hai uno, puoi importare tutte le righe in una volta.

#Cambiare o rimuovere un segreto

Le modifiche arrivano subito al sito online: vedi The live site has it now o, per un'eliminazione, The live site no longer has it. Se hai molti segreti, la casella Search secrets ne trova uno per nome. La tabella mostra Name e Last saved di ciascuno, con chi lo ha salvato.

Alcune righe hanno l'etichetta Managed. Lo studio le imposta per i propri servizi, come le email del sito, e qui non si possono modificare né eliminare.

#Come la build usa un segreto

Il codice del tuo sito legge un secret tramite il suo nome ogni volta che viene eseguito, quindi una build non ha mai bisogno del valore. Quando chiedi allo studio di collegare il tuo sito a un altro servizio, come una mailing list o un modello di IA, il suo codice legge la chiave di quel servizio con un nome chiaro, come MAILING_LIST_KEY. Il valore lo aggiungi qui, con quel nome.

#Quando ti viene chiesta una chiave prima di una build

• Una modifica a un sito pubblicato. Quando la tua richiesta collega un altro servizio, per un momento lo stato indica Checking which keys this needs. Se il sito non ha ancora un valore per una chiave, lo studio te lo chiede prima di costruire. La scheda nella conversazione ha un campo per ogni chiave, fino a 3 per una modifica. Incolla il valore e premi Save and build: va direttamente nei Secrets del sito, mai nella conversazione, e la modifica parte. Premi Add it later per costruire senza.
• Un messaggio inviato mentre aspetta si unisce alla modifica. Le chiavi che hai già salvato o che hai scelto di aggiungere più tardi non vengono mai richieste di nuovo: se il tuo nuovo messaggio collega un altro servizio, viene chiesta solo la sua chiave, quando la prima scheda è completata.
• Un sito nuovo. I Secrets richiedono un sito pubblicato, quindi una prima build non può ancora ricevere una chiave. Tra le domande prima di costruire, può chiederti se creare subito il collegamento e aggiungere la chiave quando il sito è online, oppure lasciare per ora da parte quella parte.
• In Telegram, la scheda ha un pulsante per ogni chiave che apre Secrets nello studio, e Build per proseguire. Una chiave non viene mai inviata in chat.

#Richiesta dal sito

Dopo ogni pubblicazione, Briks legge quali nomi di segreti richiede il codice del sito. Quelli che non hanno ancora un valore compaiono per primi in questa pagina, con l'etichetta Needed by the site. Premi Add value su uno di essi e il modulo si apre con il nome già inserito. Finché un nome non ha un valore, la parte del sito che lo usa non funziona.

Anche la risposta a una build o a una modifica li nomina, per esempio: The site reads MAILING_LIST_KEY, which has no value yet: add it in Project Settings → Secrets. Ogni nome ha un suo pulsante, come Add MAILING_LIST_KEY, che apre questa pagina con il nome già inserito. La stessa frase arriva nella notifica e, su Telegram, quando ti avvisa che una build è finita.

#Una chiave incollata in un messaggio

Briks riconosce le forme più comuni di chiavi e token di servizio. Una chiave incollata nella chat dello studio, nella descrizione di un nuovo progetto, nel brief di un progetto, in un messaggio a un agente o nelle sue istruzioni, in Ask AI del Visual Editor o in una chat con il bot viene rimossa prima che il messaggio sia conservato o letto, e sostituita con [key removed: add it in Settings → Secrets]. Lo studio lo dice subito: A key was removed from your message so it isn't stored. Add it in Project Settings → Secrets. La risposta ha un pulsante Open Secrets che porta a questa pagina. Nella conversazione di un agente che lavora su tutti i progetti, Open Secrets elenca i tuoi progetti così puoi scegliere quello a cui serve la chiave. Qualcosa che un agente deve ricordare viene rifiutato se contiene una chiave.

Prima che un sito venga pubblicato, Briks legge il proprio codice alla ricerca di chiavi scritte nei file: valori che sembrano chiavi dalla loro forma e valori assegnati a qualsiasi cosa abbia un nome da chiave, token o password. Se ne trova una, la build viene rimandata indietro per togliere il valore e leggere il segreto per nome.

#Regole di sicurezza che Briks applica

• I valori vanno direttamente al lato server del sito pubblicato, cifrati. Lo studio non li conserva, non li mostra più e non li scrive mai nei suoi log.
• I valori non compaiono mai nelle pagine del sito, nei browser dei visitatori né nel codice che scarichi.
• Solo Editor, Admin e Owner possono aggiungere, modificare o eliminare i segreti.
• I nomi che iniziano con BRIKS_ appartengono allo studio e i segreti gestiti non possono essere modificati.
• Un progetto può fare fino a 60 modifiche ai suoi secret al minuto. Oltre questo limite vedi: That is a lot of changes at once. Wait a minute and try again.

#Quando manca un segreto

I segreti appartengono all'indirizzo del sito. Se cambi l'indirizzo (vedi L'indirizzo del tuo sito), i tuoi segreti restano con quello vecchio. Il messaggio dello studio li elenca e ti chiede di inserirli di nuovo in Settings, Secrets, e ogni riga mostra Not on the site · enter again. Scegli Edit value su ciascuno e incolla il suo valore.

Se il codice del sito richiede un segreto che non c'è, quella parte del sito risponde: Part of this site is not set up yet. Controlla che il nome corrisponda esattamente, maiuscole comprese, e che la riga non riporti Not on the site.

#Esempio pratico: sostituire una chiave trapelata

Solo allora hanno eliminato la vecchia chiave nel servizio di mailing, così il sito non è mai rimasto un istante senza una chiave funzionante. Non è stato necessario ricostruire nulla, perché il codice richiama la chiave per nome.