envsec

Gestione sicura dei segreti di ambiente utilizzando i credential store nativi del sistema operativo.

Demo

Caratteristiche

• Archivia i segreti nel credential store nativo del tuo sistema operativo (non in file di testo semplice)
• Multipiattaforma: macOS, Linux, Windows
• Organizza i segreti per contesto (es. myapp.dev, stripe-api.prod, work.staging)
• Traccia i metadati dei segreti (nomi delle chiavi, timestamp) tramite SQLite
• Cerca contesti e segreti con pattern glob
• Esegui comandi con interpolazione dei segreti
• Salva e riesegui comandi con cmd (cerca, elenca, esegui, elimina)
• Esporta i segreti in file .env (con tracciamento delle generazioni tramite audit)
• Esporta i segreti come variabili d'ambiente della shell (eval $(envsec env))
• Carica i segreti da file .env (con rilevamento dei conflitti)
• Condividi segreti crittografati con GPG per i membri del team
• Interfaccia terminale interattiva (envsec tui) per gestire i segreti senza memorizzare comandi

Pacchetti

Questo è un monorepo contenente i seguenti pacchetti:

Pacchetto	Descrizione	npm
envsec	Strumento CLI per la gestione dei segreti
@envsec/sdk	SDK Node.js / Bun per caricare i segreti a livello di programmazione
@envsec/core	Motore principale — adattatori per credential store del sistema operativo + database dei metadati
@envsec/tui	Interfaccia terminale interattiva per la gestione dei segreti

Avvio rapido SDK

Per l'accesso programmatico ai segreti da Node.js o Bun, utilizza @envsec/sdk:```bash npm install @envsec/sdk

Installazione

Requisiti

• Python 3.8 o superiore
• pip (gestore di pacchetti Python)
• Accesso a Internet per il download dei pacchetti

Passaggi di installazione

1. Clona il repository:

git clone https://github.com/example/tool.git
cd tool

2. Installa le dipendenze:

pip install -r requirements.txt

3. Verifica l'installazione:

python tool.py --version

Risoluzione dei problemi

Se riscontri errori durante l'installazione, prova i seguenti passaggi:

• Assicurati di utilizzare una versione supportata di Python
• Esegui il comando pip con i privilegi di amministratore se necessario
• Controlla la connessione di rete e riprova

Per ulteriore assistenza, consulta la sezione FAQ o apri un problema nella pagina delle issue.

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 completa dell'SDK](https://github.com/davidnussio/envsec/blob/main/packages/sdk/README.md) per tutte le API, il supporto multi-contesto e le opzioni.

## Requisiti

- Node.js >= 22

### macOS

Nessuna dipendenza aggiuntiva. Utilizza il Keychain integrato tramite lo strumento CLI `security`.

### Linux

Richiede `libsecret-tools` (che fornisce il comando `secret-tool`), che comunica con GNOME Keyring, KDE Wallet o qualsiasi provider dell'API Secret Service tramite D-Bus.```bash
# Debian / Ubuntu
sudo apt install libsecret-tools

# Fedora
sudo dnf install libsecret

# Arch
sudo pacman -S libsecret
```
Una sessione D-Bus attiva e un demone del portachiavi (ad es. `gnome-keyring-daemon`) devono essere in esecuzione. La maggior parte degli ambienti desktop gestisce questo automaticamente.

### Windows

Nessuna dipendenza aggiuntiva. Utilizza il Gestione credenziali integrato di Windows tramite `cmdkey` e PowerShell.

## Installazione

### Homebrew (macOS / Linux)```bash
brew tap davidnussio/homebrew-tap
brew install envsec
```
### npm```bash
npm install -g envsec
```
### npx (senza installazione)```bash
npx envsec
```
### mise```bash
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 i 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 lo scripting
- `--db` — Percorso del file del database SQLite (predefinito: `~/.envsec/store.sqlite`). Legge anche la variabile d'ambiente `ENVSEC_DB`

### Percorso database personalizzato

Per impostazione predefinita, i metadati sono memorizzati in `~/.envsec/store.sqlite`. Puoi sovrascriverli con `--db` o con 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
```
Il flag `--db` ha precedenza su `ENVSEC_DB`. I casi d'uso includono database per progetto, database condivisi dal team su unità di rete e CI/CD con storage effimero.

### Aggiungere un segreto

Memorizza un segreto nel credential store del sistema operativo.

- `<key>` — Nome della chiave del segreto (es. `api.key`, `db.password`)
- `--value`, `-v` — Valore da memorizzare (omettere per prompt mascherato interattivo)
- `--expires`, `-e` — Durata di scadenza (es. `30m`, `2h`, `7d`, `4w`, `3mo`, `1y`)```bash
# Store a value inline
envsec -c myapp.dev add api.key --value "sk-abc123"

# Or use the short alias
envsec -c myapp.dev add api.key -v "sk-abc123"

# Omit --value for an interactive masked prompt
envsec -c myapp.dev add api.key

# Set an expiry duration with --expires (-e)
envsec -c myapp.dev add api.key -v "sk-abc123" --expires 30d

# Supported duration units: m (minutes), h (hours), d (days), w (weeks), mo (months), y (years)
# Combinable: 1y6mo, 2w3d, 1d12h
envsec -c myapp.dev add api.key -v "sk-abc123" -e 6mo
```
### Get a secret

Recupera un valore segreto dall'archivio delle credenziali del sistema operativo.

- `<key>` — Nome della chiave del segreto 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
```
### Elimina un segreto

Rimuovi un segreto dall'archivio delle credenziali del sistema operativo.

- `<key>` — Nome della chiave del segreto da eliminare (opzionale se si usa `--all`)
- `--yes`, `-y` — Salta il prompt di conferma
- `--all` — Elimina tutti i segreti nel contesto```bash
envsec -c myapp.dev delete api.key

# or use the alias
envsec -c myapp.dev del api.key
```
### Rinomina un segreto
```