davidnussio/envsecStrumento CLI sicuro per la gestione dei segreti di ambiente utilizzando i depositi di credenziali nativi del sistema operativo (macOS Keychain, Linux Secret Service, Windows Credential Manager)
Gestione sicura dei segreti d'ambiente utilizzando i depositi nativi del sistema operativo.
myapp.dev, stripe-api.prod, work.staging)cmd (cerca, elenca, esegui, elimina).env (con tracciamento delle generazioni tramite audit)eval $(envsec env)).env (con rilevamento dei conflitti)envsec tui) per gestire segreti senza memorizzare comandiQuesto è un monorepo contenente i seguenti pacchetti:
Per l'accesso programmatico ai segreti da Node.js o Bun, usa @envsec/sdk:```bash
npm install @envsec/sdk
Please provide the Markdown content to translate.```typescript
import { loadSecrets } from "@envsec/sdk";
// Load and inject into process.env
await loadSecrets({ context: "myapp.dev", inject: true });
// Or use the client for full control
import { EnvsecClient } from "@envsec/sdk";
const client = await EnvsecClient.create({ context: "myapp.dev" });
const apiKey = await client.get("api.key");
await client.close();
Vedi la documentazione SDK completa per tutte le API, il supporto multi-contesto e le opzioni.
Nessuna dipendenza aggiuntiva. Utilizza il Keychain integrato tramite lo strumento CLI security.
Richiede libsecret-tools (fornisce il comando secret-tool), che comunica con GNOME Keyring, KDE Wallet o qualsiasi provider dell'API Secret Service tramite D-Bus.```bash
sudo apt install libsecret-tools
sudo dnf install libsecret
sudo pacman -S libsecret
Una sessione D-Bus in esecuzione e un demone keyring (es. `gnome-keyring-daemon`) devono essere attivi. La maggior parte degli ambienti desktop gestisce questo automaticamente.
### Windows
Nessuna dipendenza extra. Utilizza il Gestore credenziali di Windows integrato tramite `cmdkey` e PowerShell.
## Installation
### Homebrew (macOS / Linux)```bash
brew tap davidnussio/homebrew-tap
brew install envsec
npm install -g envsec
### npx (nessuna installazione)```bash
npx envsec
mise use -g npm:envsec
## Utilizzo
La maggior parte dei comandi richiede un contesto specificato con `--context` (o `-c`).
Un contesto è un'etichetta libera per raggruppare segreti — ad es. `myapp.dev`, `stripe-api.prod`, `work.staging`.
### Opzioni globali
Queste opzioni sono disponibili su tutti i comandi:
- `--context`, `-c` — Nome del contesto (ad es. `myapp.dev`, `stripe-api.prod`). Legge anche la variabile d'ambiente `ENVSEC_CONTEXT`
- `--debug`, `-d` — Abilita il logging di debug
- `--json` — Output in formato JSON per script
- `--db` — Percorso del file del database SQLite (default: `~/.envsec/store.sqlite`). Legge anche la variabile d'ambiente `ENVSEC_DB`
### Percorso personalizzato del database
Per impostazione predefinita, i metadati sono memorizzati in `~/.envsec/store.sqlite`. Puoi sovrascrivere questo con `--db` o la variabile d'ambiente `ENVSEC_DB`:```bash
# Use a project-local database
envsec --db ./local-store.sqlite -c myapp.dev list
# Or via environment variable
export ENVSEC_DB=/shared/team/envsec.sqlite
envsec -c myapp.dev list
The --db flag ha la precedenza su ENVSEC_DB. I casi d'uso includono database per progetto, database condivisi in team su unità di rete e CI/CD con storage effimero.
Archivia un segreto nel deposito di credenziali del sistema operativo.
<key> — Nome della chiave segreta (ad es. api.key, db.password)--value, -v — Valore da archiviare (omettere per prompt interattivo mascherato)--expires, -e — Durata di scadenza (ad es. 30m, 2h, 7d, 4w, 3mo, 1y)```bashenvsec -c myapp.dev add api.key --value "sk-abc123"
envsec -c myapp.dev add api.key -v "sk-abc123"
envsec -c myapp.dev add api.key
envsec -c myapp.dev add api.key -v "sk-abc123" --expires 30d
envsec -c myapp.dev add api.key -v "sk-abc123" -e 6mo
### Ottieni un segreto
Recupera un valore segreto dal deposito di credenziali del sistema operativo.
- `<key>` — Nome della chiave segreta da recuperare
- `--quiet`, `-q` — Stampa solo il valore grezzo (nessun avviso o output aggiuntivo)
- `--json` — Output in formato JSON (include contesto, chiave, valore, expires_at)```bash
envsec -c myapp.dev get api.key
# Print only the raw value (no warnings or extra output)
envsec -c myapp.dev get api.key --quiet
envsec -c myapp.dev get api.key -q
Rimuovi un segreto dall'archivio di credenziali del sistema operativo.
<key> — Nome della chiave del segreto da eliminare (opzionale se si usa --all)--yes, -y — Salta la richiesta di conferma--all — Elimina tutti i segreti nel contesto```bash
envsec -c myapp.dev delete api.keyenvsec -c myapp.dev del api.key
### Rinominare un segreto
Rinomina una chiave segreta all'interno dello stesso contesto. Il valore e i metadati di scadenza vengono preservati.
- `<old-key>` — Nome attuale della chiave segreta
- `<new-key>` — Nuovo nome della chiave segreta
- `--force`, `-f` — Sovrascrivi la destinazione se esiste già```bash
# Rename a key
envsec -c myapp.dev rename old.key new.key
# Overwrite target if it already exists
envsec -c myapp.dev rename old.key existing.key --force
Elenca tutte le chiavi segrete e i metadati in un contesto.
--json — Output in formato JSON```bash
envsec -c myapp.dev list### Elenca tutti i contesti
Elenca tutti i contesti disponibili con il conteggio dei segreti.
- `--json` — Output in formato JSON```bash
# Without --context, lists all available contexts with secret counts
envsec list
Cerca segreti o contesti utilizzando pattern glob.
<pattern> — Pattern glob da cercare (es. api.*, myapp.*)--json — Output in formato JSON```bashenvsec -c myapp.dev search "api.*"
envsec search "myapp.*"
### Sposta segreti tra contesti
Sposta segreti da un contesto a un altro. I segreti sorgente vengono rimossi dopo lo spostamento.
- `<pattern>` — Pattern glob o chiave esatta da spostare (opzionale se si usa `--all`)
- `--to`, `-t` — Contesto di destinazione in cui spostare i segreti
- `--all` — Sposta tutti i segreti dal contesto sorgente
- `--force`, `-f` — Sovrascrivi segreti esistenti nel contesto di destinazione
- `--yes`, `-y` — Salta la richiesta di conferma```bash
# Move a single secret
envsec -c myapp.dev move api.token --to myapp.prod
# Move secrets matching a glob pattern
envsec -c myapp.dev move "redis.*" --to myapp.prod -y
# Move all secrets from one context to another
envsec -c myapp.dev move --all --to myapp.prod -y
# Overwrite existing secrets in the target context
envsec -c myapp.dev move "redis.*" --to myapp.prod --force -y
Copia segreti da un contesto a un altro. I segreti di origine rimangono intatti.
<pattern> — Pattern glob o chiave esatta da copiare (opzionale se si usa --all)--to, -t — Contesto di destinazione in cui copiare i segreti--all — Copia tutti i segreti dal contesto di origine--force, -f — Sovrascrivi segreti esistenti nel contesto di destinazione--yes, -y — Salta la richiesta di conferma```bashenvsec -c myapp.dev copy api.token --to myapp.staging
envsec -c myapp.dev copy "redis.*" --to myapp.staging -y
envsec -c myapp.dev copy --all --to myapp.staging -y
envsec -c myapp.dev copy "redis.*" --to myapp.staging --force -y
### Esegui un comando con segreti
Esegui un comando con valori segreti interpolati tramite segnaposto o iniettati come variabili d'ambiente.
- `<command>` — Comando da eseguire. Usa i segnaposto `{key}` per interpolare i segreti
- `--inject`, `-i` — Inietta tutti i segreti del contesto come variabili d'ambiente (`KEY.NAME` → `KEY_NAME`)
- `--save`, `-s` — Salva questo comando per un uso futuro
- `--name`, `-n` — Nome per il comando salvato (richiesto interattivamente se omesso con `--save`)```bash
# Placeholders {key} are resolved with secret values before execution
envsec -c myapp.dev run 'curl {api.url} -H "Authorization: Bearer {api.token}"'
# Any {dotted.key} in the command string is replaced with its value
envsec -c myapp.prod run 'psql {db.connection_string}'
# Inject ALL context secrets as environment variables (KEY.NAME → KEY_NAME)
envsec -c myapp.dev run --inject 'node server.js'
envsec -c myapp.dev run -i 'docker compose up'
# Combine --inject with placeholders
envsec -c myapp.dev run --inject 'curl {api.url} -H "Authorization: Bearer $API_TOKEN"'
# Save the command for later use with --save (-s) and --name (-n)
envsec -c myapp.dev run --save --name deploy 'kubectl apply -f - <<< {k8s.manifest}'
# If you use --save without --name, you'll be prompted interactively
envsec -c myapp.dev run --save 'psql {db.connection_string}'
Se un placeholder fa riferimento a un segreto che non esiste, il comando non verrà eseguito e vedrai un chiaro errore:``` ❌ Missing secrets in context "myapp.dev":
Add them with: envsec -c myapp.dev add
### Comandi salvati
I comandi salvati si trovano sotto il sottocomando `cmd`, mantenendoli separati dalle operazioni segrete.
#### cmd list
Elenca tutti i comandi salvati.```bash
envsec cmd list
Esegue un comando salvato (utilizza il contesto con cui è stato salvato).
<name> — Nome del comando salvato da eseguire--override-context, -o — Sovrascrive il contesto salvato al momento dell'esecuzione--quiet, -q — Sopprime l'output informativo (stampa solo l'output del comando)--inject, -i — Inietta tutti i segreti del contesto come variabili di ambiente```bash
envsec cmd run deployenvsec cmd run deploy --quiet envsec cmd run deploy -q
envsec cmd run deploy --override-context myapp.prod envsec cmd run deploy -o myapp.prod
envsec cmd run deploy --inject envsec cmd run deploy -i
#### cmd search
Cerca comandi salvati per nome o stringa di comando.
- `<pattern>` — Pattern di ricerca
- `--name`, `-n` — Cerca solo nei nomi dei comandi
- `--command`, `-m` — Cerca solo nelle stringhe dei comandi```bash
envsec cmd search psql
# Search only by name
envsec cmd search deploy -n
# Search only by command string
envsec cmd search kubectl -m
Elimina un comando salvato.
<name> — Nome del comando da eliminare```bash
envsec cmd delete deploy### Genera un file .env
Esporta tutti i segreti da un contesto in un file `.env`.
- `--output`, `-o` — Percorso del file di output (predefinito: `.env`)```bash
# Creates .env with all secrets from the context
envsec -c myapp.dev env-file
# Specify a custom output path
envsec -c myapp.dev env-file --output .env.local
Keys are converted to UPPER_SNAKE_CASE (e.g. api.token → API_TOKEN).
Restituisce istruzioni di esportazione da usare con eval o sourcing di shell.
--shell, -s — Sintassi della shell di destinazione: bash (default), zsh, fish, powershell--unset, -u — Restituisce comandi di unset/rimozione invece di export```basheval $(envsec -c myapp.dev env)
envsec -c myapp.dev env --shell fish envsec -c myapp.dev env --shell powershell
eval $(envsec -c myapp.dev env --unset)
envsec -c myapp.dev env --unset --shell fish
Shell supportati: `bash` (default), `zsh`, `fish`, `powershell`. Le chiavi vengono convertite in `UPPER_SNAKE_CASE` (es. `api.token` → `API_TOKEN`). L'output va su stdout in modo che possa essere passato tramite pipe a `eval` o eseguito direttamente con source — nessun file viene scritto su disco.
### Avviare una sessione shell con ambito secrets
Avvia un subshell interattivo con tutti i segreti del contesto iniettati come
variabili d'ambiente. Quando fai `exit`, i segreti scompaiono — nessuna pulizia necessaria.
- `--shell`, `-s` — Shell in cui avviare (`bash`, `zsh`, `fish`, `powershell`). Default: rilevamento automatico
- `--no-inherit` — Non ereditare le variabili d'ambiente genitore
- `--quiet`, `-q` — Sopprime il banner di avvio/uscita```bash
envsec -c myapp.dev shell
INPUT:``` ▶ envsec shell — context: myapp.dev (8 secrets loaded) Type 'exit' or press Ctrl+D to leave the session.
(envsec:myapp.dev) ~ $ echo $DATABASE_URL postgres://user:pass@localhost/mydb
(envsec:myapp.dev) ~ $ exit → Exiting envsec shell — secrets cleared.
INPUT:```bash
# Force a specific shell
envsec -c myapp.dev shell --shell zsh
# Only envsec secrets in env (no parent variables, except PATH)
envsec -c myapp.dev shell --no-inherit
# Suppress the startup/exit banner
envsec -c myapp.dev shell --quiet
La variabile ENVSEC_CONTEXT è sempre impostata all'interno della sessione, quindi puoi
farci riferimento in script o personalizzazioni del prompt.
Importa i segreti da un file .env in un contesto.
--input, -i — Percorso del file .env di input (default: .env)--force, -f — Sovrascrive i segreti esistenti senza richiedere conferma--batch, -b — Modalità batch: rimanda la persistenza nel database fino all'importazione di tutti i segreti```bashenvsec -c myapp.dev load
envsec -c myapp.dev load --input .env.local
envsec -c myapp.dev load --force
Keys are converted from `UPPER_SNAKE_CASE` to `dotted.lowercase` (ad esempio `API_TOKEN` → `api.token`). Se una chiave esiste già, viene saltata con un avviso a meno che non venga specificato `--force` (`-f`).
### Condividi segreti (crittografati con GPG)
Crittografa tutti i segreti da un contesto per un membro del team utilizzando GPG.
- `--encrypt-to` — chiave del destinatario GPG (email, ID chiave o impronta digitale) per cui crittografare
- `--output`, `-o` — Percorso del file di output (default: stdout). Usa `-` per stdout esplicitamente
- `--json` — Usa il formato JSON all'interno del payload crittografato (default: formato `.env`)```bash
# Encrypt all secrets from a context for a team member
envsec -c myapp.dev share --encrypt-to [email protected]
# Save encrypted output to a file
envsec -c myapp.dev share --encrypt-to [email protected] -o secrets.enc
# Use JSON format inside the encrypted payload
envsec -c myapp.dev --json share --encrypt-to [email protected] -o secrets.enc
Il destinatario può decrittare con gpg --decrypt secrets.enc e inviare il risultato a envsec load. Per impostazione predefinita, il payload crittografato utilizza il formato .env (KEY="value"); con --json utilizza un oggetto JSON strutturato. Richiede che GPG sia installato e che la chiave pubblica del destinatario sia nel tuo portachiavi.
Verifica i segreti scaduti o in scadenza e le esportazioni tracciate dei file .env.
--within, -w — Mostra i segreti in scadenza entro questa durata (default: 30d). Usa 0d per mostrare solo quelli già scaduti--json — Output in formato JSON```bashenvsec -c myapp.dev audit
envsec -c myapp.dev audit --within 7d
envsec -c myapp.dev audit --within 0d
envsec audit
envsec -c myapp.dev audit --json
I segreti con una durata `--expires` impostata tramite `envsec add` vengono tracciati nei metadati. Il comando `audit` cerca i segreti già scaduti o che scadranno entro la finestra specificata. I comandi `get` e `list` mostrano anche avvisi di scadenza in linea.
Il comando `audit` traccia anche i file `.env` generati. Ogni volta che `env-file` viene utilizzato, vengono registrati il percorso di output, il contesto e il timestamp. L'output del comando audit include una seconda sezione che elenca questi file. Se un file `.env` tracciato non esiste più sul disco, audit lo rimuove automaticamente dai metadati e segnala la pulizia.
### Genera un segreto casuale
Genera un segreto casuale crittograficamente sicuro, opzionalmente memorizzandolo.
- `<key>` — Nome della chiave segreta (opzionale; omettere per generazione di password standalone)
- `--length`, `-l` — Lunghezza del segreto generato (default: `32`)
- `--prefix`, `-p` — Prefisso da anteporre al segreto generato (es. `sk_`)
- `--expires`, `-e` — Durata di scadenza (es. `30m`, `2h`, `7d`, `4w`, `3mo`, `1y`)
- `--alphanumeric`, `-a` — Usa solo caratteri alfanumerici `[a-zA-Z0-9]` (default)
- `--special`, `-s` — Includi caratteri speciali comuni `[a-zA-Z0-9!@#$%^&*]`
- `--all-chars`, `-A` — Usa tutti i caratteri ASCII stampabili per la massima entropia```bash
# Generate and store a 32-char alphanumeric secret
envsec -c myapp.dev secret api.key
# Custom length and prefix
envsec -c myapp.dev secret api.key --prefix "sk_" --length 48
# Character sets:
# --alphanumeric (-a) [a-zA-Z0-9] (default)
# --special (-s) [a-zA-Z0-9] + !@#$%^&*
# --all-chars (-A) all printable ASCII
envsec -c myapp.dev secret db.password --special --length 64
# With expiry
envsec -c myapp.dev secret api.key --prefix "sk_" -l 48 --expires 90d
# Standalone password generator (no store, just print)
envsec secret --length 32
envsec secret --special --length 64 --prefix "pk_"
Quando sono forniti sia context che key, il valore generato viene memorizzato e stampato. Senza nessuno dei due, il valore grezzo va su stdout — utile per reindirizzare a pbcopy, xclip o altri strumenti.
envsec include un'interfaccia terminale a schermo intero per gestire i segreti in modo interattivo — nessun bisogno di memorizzare comandi.```bash
envsec tui
envsec -c myapp.dev tui
La TUI fornisce otto schermate accessibili dal menu principale:
- **Contesti** — sfoglia tutti i contesti, imposta il contesto attivo con `s`, cancella il contesto con `x`, visualizza il conteggio dei segreti, elimina interi contesti
- **Segreti** — elenca i segreti in una tabella, rivela i valori, aggiungi o elimina segreti
- **Aggiungi Segreto** — modulo interattivo con input mascherato e durata opzionale di scadenza
- **Ricerca** — ricerca con pattern glob tra segreti o contesti
- **Comandi Salvati** — elenca, visualizza ed elimina modelli di comandi salvati
- **Audit** — verifica segreti scaduti/in scadenza, rivedi esportazioni tracciate di file `.env`
- **Importa .env** — carica segreti da un file `.env` nel contesto corrente
- **Esporta .env** — esporta segreti in un file `.env` (tracciato per audit)
Scorciatoie da tastiera:
| Tasto | Azione |
|-------|--------|
| `↑` / `↓` | Naviga tra voci di menu e righe della tabella |
| `Enter` | Seleziona / conferma |
| `c` | Apri la vista contesti (menu principale) |
| `s` | Imposta selezionato come contesto attivo (vista contesti) |
| `x` | Cancella contesto attivo (vista contesti) |
| `a` | Aggiungi un nuovo segreto (vista segreti) |
| `d` | Elimina elemento selezionato |
| `r` | Rivela valore segreto (vista dettaglio) |
| `Esc` | Torna indietro / annulla |
| `q` | Esci dalla TUI |
### Diagnostica la tua configurazione
Esegui controlli di integrità per verificare la tua installazione di envsec.
- `--json` — Output in formato JSON per scripting```bash
# Run all health checks
envsec doctor
# JSON output for scripting
envsec --json doctor
Il comando doctor verifica che l'installazione di envsec funzioni correttamente. Controlla:
ENVSEC_DB, ENVSEC_CONTEXT)envsec supporta il completamento dinamico con tab per bash, zsh e fish. I completamenti sono sensibili al contesto: suggeriscono i tuoi nomi di contesto effettivi, le chiavi dei segreti e i nomi dei comandi salvati in tempo reale interrogando il database dei metadati.```bash
eval "$(envsec --completions bash)"
eval "$(envsec --completions zsh)"
envsec --completions fish | source
Ciò che viene completato dinamicamente:
- `--context` / `-c` — elenca tutti i tuoi contesti
- Argomenti della chiave segreta (`get`, `add`, `delete`) — elenca le chiavi per il contesto corrente
- `cmd run` / `cmd delete` — elenca i nomi dei comandi salvati
- `--override-context` / `-o` — elenca i contesti per `cmd run`
- Sottocomandi, flag e scelte statiche (shell, ecc.) sono anch'essi completati
## Confronto
Come si confronta envsec con altri strumenti per la gestione dei segreti di ambiente?
| Caratteristica | envsec | dotenv / dotenvx | CLI 1Password (`op`) |
|---|---|---|---|
| Archiviazione segreti | Archivio credenziali del sistema operativo (Keychain, Secret Service, Credential Manager) | File `.env` su disco (dotenvx aggiunge crittografia) | Cloud vault 1Password |
| Crittografia a riposo | Delegata al sistema operativo (Keychain, GNOME Keyring, DPAPI) | Nessuna (dotenv) / ECIES per file (dotenvx) | AES-256 nel cloud 1Password |
| Segreti su disco | Mai — i valori vanno direttamente nell'archivio credenziali del sistema operativo | Sempre — i file `.env` sono in chiaro di default | Mai localmente (recuperati a runtime dal cloud) |
| Accesso offline | Completo — i segreti sono locali nell'archivio del sistema operativo | Completo — i file sono locali | Richiede rete (elementi memorizzati nella cache disponibili offline nell'app) |
| Account / abbonamento | Nessuno — gratuito, open source, nessuna registrazione | Gratuito (dotenv) / open source gratuito (dotenvx) | Abbonamento a pagamento (da ~$3/mese individuale, ~$8/utente/mese aziendale) |
| Multipiattaforma | macOS, Linux, Windows | Qualsiasi piattaforma con Node.js / qualsiasi runtime (dotenvx) | macOS, Linux, Windows |
| Organizzazione contesti/ambienti | Contesti (es. `myapp.dev`, `stripe.prod`) | File `.env` separati per ambiente | Vault e oggetti |
| Esecuzione comandi con segreti | `envsec run` — interpolazione placeholder + `--inject` variabili d'ambiente | `dotenvx run -- cmd` — inietta da `.env` crittografato | `op run -- cmd` — inietta tramite riferimenti segreti |
| Esportazione in file `.env` | `envsec env-file` (tracciato per audit) | Formato nativo — i file `.env` sono la fonte di verità | `op inject --out-file` |
| Importazione da file `.env` | `envsec load` (con rilevamento conflitti) | N/D — `.env` è l'archivio primario | Creazione manuale di oggetti |
| Esportazione variabili d'ambiente shell | `eval $(envsec env)` — bash, zsh, fish, powershell | `dotenvx run` o `node -r dotenv/config` | `op run --env-file` |
| Sessione shell interattiva | `envsec shell` — subshell con ambito e pulizia automatica | Non integrato | Non integrato |
| Ricerca segreti | Pattern glob su chiavi e contesti | Non integrato | Filtro `op item list --tags/--category` |
| Audit scadenza/rotazione | `envsec audit` — scaduti, in scadenza, file `.env` tracciati | Non integrato | Watchtower (nell'app, non nella CLI) |
| Comandi salvati | `envsec cmd` — salva, elenca, cerca, esegui, elimina | Non integrato | Non integrato |
| Sposta/copia segreti | `envsec move` e `envsec copy` tra contesti | Copia manuale di file | `op item move` tra vault |
| Rinomina segreti | `envsec rename` (preserva valore e metadati) | Modifica manuale del file `.env` | `op item edit` |
| Condivisione crittografata GPG | `envsec share --encrypt-to` | File `.env` crittografati committati in git (dotenvx) | Condivisione vault integrata, provisioning team |
| TUI interattivo | `envsec tui` — interfaccia terminale a schermo intero | Non integrato | Non integrato |
| Diagnostica salute | `envsec doctor` — verifica piattaforma, portachiavi, integrità DB | Non integrato | Non integrato |
| Completamenti shell | Dinamici (contesti, chiavi, comandi) per bash, zsh, fish | Non integrato | Completamenti statici per bash, zsh, fish, powershell |
| SDK / accesso programmatico | `@envsec/sdk` per Node.js / Bun | `require('dotenv').config()` — caso d'uso principale | SDK 1Password (Node.js, Python, Go, ecc.) |
| Team / multiutente | Condivisione GPG (manuale) | Condivisione basata su git con file `.env` crittografati (dotenvx) | Gestione team integrata, RBAC, log di audit |
<!-- | Integrazione CI/CD | CLI standard — funziona ovunque Node.js sia eseguito | `dotenvx run` in qualsiasi pipeline CI | Account di servizio, integrazioni CI/CD native | -->
| Autenticazione biometrica | Eredita i biometrici del sistema operativo (es. sblocco Keychain macOS) | Nessuna | Impronta digitale / Touch ID tramite integrazione app |
| Tracciamento metadati | SQLite (nomi chiave, timestamp — mai valori) | Nessuno | Cronologia oggetti e log di audit basati su cloud |
In breve: dotenv è l'approccio più semplice (file su disco), CLI 1Password è il più ricco di funzionalità per team con sincronizzazione cloud e RBAC, e envsec si colloca nel mezzo — offrendo crittografia nativa del sistema operativo senza account, senza dipendenze cloud e un flusso di lavoro incentrato sugli sviluppatori che va oltre ciò che i file `.env` possono fare.
## Come funziona
I segreti vengono archiviati nell'archivio credenziali nativo del sistema operativo. Il backend viene selezionato automaticamente in base alla piattaforma:
| Sistema operativo | Backend | Strumento / API |
|---|---|---|
| macOS | Portachiavi | CLI `security` |
| Linux | API Secret Service (D-Bus) | `secret-tool` (libsecret) |
| Windows | Gestione credenziali | `cmdkey` + PowerShell (advapi32) |
I metadati (nomi delle chiavi, timestamp) sono conservati in un database SQLite in `~/.envsec/store.sqlite` (configurabile tramite `--db` o `ENVSEC_DB`). Le chiavi devono contenere almeno un separatore punto (es. `service.account`) che corrisponde alla struttura servizio/account dell'archivio credenziali.
## Sicurezza
envsec è costruito attorno a un principio semplice: i tuoi segreti appartengono al tuo sistema operativo, non ai file di configurazione. Ogni decisione progettuale parte da questa base.
### Come envsec protegge i tuoi segreti
**Crittografia nativa del sistema operativo, zero crittografia personalizzata.** I valori segreti vengono archiviati direttamente in macOS Keychain, GNOME Keyring / KDE Wallet o Windows Credential Manager. envsec non inventa mai una propria crittografia — si affida agli archivi credenziali collaudati che il tuo sistema operativo già fornisce, protetti dalla tua sessione utente e (su macOS) dal portachiavi di login.
**Supporto Unicode completo.** I valori segreti possono contenere qualsiasi carattere Unicode, inclusi emoji e lettere accentate. I valori vengono codificati in base64 prima di essere archiviati nell'archivio credenziali del sistema operativo, evitando stranezze di codifica specifiche della piattaforma (es. la CLI `security` di macOS codifica in esadecimale l'output non ASCII). I segreti legacy in testo semplice vengono letti in modo trasparente per la compatibilità con le versioni precedenti.
**I segreti non toccano mai il disco come testo in chiaro.** I valori vanno direttamente dal terminale all'archivio credenziali del sistema operativo. Non vengono mai scritti in file di configurazione, log o archivi intermedi.
**Nessun segreto nell'output del terminale.** I comandi `list` e `search` mostrano solo i nomi delle chiavi — i valori non vengono mai stampati. Questo mantiene i segreti fuori dai buffer di scorrimento, dalle registrazioni dello schermo e dalla portata di curiosi.
**Esecuzione sicura dei comandi.** Il comando `run` inietta i segreti come variabili d'ambiente del processo figlio anziché interpolarli nella stringa di comando. Ciò significa che i valori segreti non compaiono nell'output di `ps` o nella cronologia della shell. Se un segreto referenziato è mancante, il comando viene bloccato completamente — nessuna esecuzione parziale con credenziali incomplete.
**Convalida dell'input e prevenzione dell'iniezione.** I nomi dei contesti vengono convalidati rispetto a un elenco consentito rigoroso (alfanumerici, punti, trattini, underscore) con controlli di path traversal e prototype pollution. Tutte le query SQLite utilizzano istruzioni preparate con parametri vincolati, prevenendo l'iniezione SQL. Gli argomenti PowerShell su Windows vengono escaped per proteggere dall'iniezione di comandi.
**Permessi restrittivi sui file.** La directory dei metadati (`~/.envsec/`) viene creata con permessi `0700` e il database SQLite con `0600`, limitando l'accesso all'utente proprietario.
### Limitazioni note e aree di miglioramento
Crediamo nell'essere trasparenti su ciò che envsec non copre ancora. Questi sono compromessi reali, non bug — e comprenderli ti aiuta a prendere decisioni informate.
**I metadati sono visibili.** Il database SQLite in `~/.envsec/store.sqlite` memorizza nomi di chiavi, nomi di contesti e timestamp — mai valori segreti, ma abbastanza per rivelare *quali* segreti esistono. I modelli di comandi salvati (con segnaposto `{key}`) sono anch'essi memorizzati lì. Se la riservatezza dei metadati è importante per te, assicurati che la tua home directory sia su un volume crittografato.
**Le esportazioni `env-file` sono in chiaro.** Il comando `env-file` scrive i valori segreti in un file `.env` su disco. Questo è intrinsecamente sensibile — tratta il file di output di conseguenza e non committarlo mai nel controllo versione. Consideralo un ponte di comodità, non un meccanismo di archiviazione.
**L'esecuzione della shell comporta rischi intrinseci.** Il comando `run` passa il tuo modello di comando attraverso `/bin/sh` (o `cmd.exe` su Windows). Se il modello stesso proviene da input non fidato, è possibile l'iniezione di shell. Esegui solo modelli di comando che hai scritto tu o di cui ti fidi.
**Nessun controllo di accesso tra contesti.** Qualsiasi processo in esecuzione come utente del sistema operativo può leggere tutti i segreti in tutti i contesti. envsec si affida all'isolamento a livello di sistema operativo — non aggiunge un proprio livello di autorizzazione tra i contesti.
**Ambienti Linux headless.** Su Linux, envsec dipende da una sessione D-Bus attiva e da un demone keyring (es. `gnome-keyring-daemon`). In contenitori o server headless senza sessione grafica, il keyring potrebbe non essere disponibile o potrebbe archiviare segreti con protezione più debole.
**La crittografia dipende dal tuo sistema operativo.** envsec non aggiunge ulteriore crittografia a riposo oltre a quella fornita dall'archivio credenziali nativo. Su sistemi senza crittografia completa del disco, un utente malintenzionato con accesso fisico potrebbe potenzialmente estrarre segreti dal portachiavi. Raccomandiamo di attivare la crittografia completa del disco (FileVault, LUKS, BitLocker) per la massima protezione.
## Sviluppo
### Prerequisiti
- Node.js >= 22
- pnpm
### Configurazione```bash
git clone https://github.com/davidnussio/envsec.git
cd envsec
pnpm install
pnpm run build
packages/
cli/ → envsec CLI (published as envsec)
sdk/ → Node.js/Bun SDK (published as @envsec/sdk)
core/ → Core engine, shared by CLI and SDK (published as @envsec/core)
tui/ → Interactive terminal UI (published as @envsec/tui)
apps/
website/ → Documentation website
### Comandi comuni```bash
# Build all packages
pnpm run build
# Lint and format check (all packages)
pnpm run check
# Auto-fix lint and formatting
pnpm run fix
# Release (build + changeset publish)
pnpm run release
Crea un alias temporaneo per utilizzare la build locale come se fosse installata globalmente:```bash
alias envsec="node $(pwd)/packages/cli/dist/main.js"
alias envsec "node (pwd)/packages/cli/dist/main.js"
### Testare i completamenti della shell localmente
Dopo aver creato e impostato l'alias, carica i completamenti nella tua sessione corrente:```bash
# Bash
alias envsec="node $(pwd)/packages/cli/dist/main.js"
eval "$(envsec --completions bash)"
# Zsh
alias envsec="node $(pwd)/packages/cli/dist/main.js"
eval "$(envsec --completions zsh)"
# Fish
alias envsec "node (pwd)/packages/cli/dist/main.js"
envsec --completions fish | source
Quindi premi TAB dopo envsec -c per vedere i tuoi contesti, oppure dopo envsec -c myapp.dev get per vedere le chiavi segrete.
I test di integrazione end-to-end coprono l'intero ciclo di vita della CLI (add, get, list, search, env-file, load, delete, run, cmd, audit, share, completions).```bash
pnpm run build
bash packages/cli/test/e2e-test.sh
pwsh packages/cli/test/e2e-test.ps1
CI viene eseguita automaticamente su push/PR verso `main` tramite GitHub Actions, eseguendo `e2e-test.sh` su macOS e Ubuntu, e `e2e-test.ps1` su Windows.
## Licenza
MIT
| Pacchetto | Descrizione | npm |
|---|
envsec | Strumento CLI per la gestione dei segreti |  |
@envsec/sdk | SDK Node.js / Bun per caricare segreti a livello di programmazione |  |
@envsec/core | Motore principale — adattatori del deposito OS + database metadata |  |
@envsec/tui | Interfaccia utente terminale interattiva per la gestione dei segreti |  |