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

pip install -r requirements.txt

python tool.py --version

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

Rinomina una chiave segreta nello 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` — Sovrascrive 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 tutti i segreti in un contesto

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

Cerca segreti o contesti utilizzando pattern glob.

- `<pattern>` — Pattern glob da cercare (es. `api.*`, `myapp.*`)
- `--json` — Output in formato JSON```bash
# Search secrets within a context
envsec -c myapp.dev search "api.*"

# Search contexts by pattern (without --context)
envsec search "myapp.*"
```
### Sposta i segreti tra contesti

Sposta i segreti da un contesto a un altro. I segreti di origine 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 di origine
- `--force`, `-f` — Sovrascrive i segreti esistenti nel contesto di destinazione
- `--yes`, `-y` — Salta il prompt 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
```
### Copiare i segreti tra contesti

Copia i 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 a cui copiare i segreti
- `--all` — Copia tutti i segreti dal contesto di origine
- `--force`, `-f` — Sovrascrive i segreti esistenti nel contesto di destinazione
- `--yes`, `-y` — Salta il prompt di conferma```bash
# Copy a single secret
envsec -c myapp.dev copy api.token --to myapp.staging

# Copy secrets matching a glob pattern
envsec -c myapp.dev copy "redis.*" --to myapp.staging -y

# Copy all secrets from one context to another
envsec -c myapp.dev copy --all --to myapp.staging -y

# Overwrite existing secrets in the target context
envsec -c myapp.dev copy "redis.*" --to myapp.staging --force -y
```
### Eseguire un comando con i segreti

Esegue un comando con valori segreti interpolati tramite segnaposto o iniettati come variabili d'ambiente.

- `<command>` — Comando da eseguire. Usa i segnaposto `{key}` per l'interpolazione dei 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 in modo interattivo 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 qualsiasi segnaposto fa riferimento a un segreto che non esiste, il comando non verrà eseguito e vedrai un errore chiaro:```
❌ Missing secrets in context "myapp.dev":
  - api.url
  - api.token

Add them with: envsec -c myapp.dev add <key>
```
### Comandi salvati

I comandi salvati risiedono nel sottocomando `cmd`, mantenendoli separati dalle operazioni segrete.

#### cmd list

Elenca tutti i comandi salvati.```bash
envsec cmd list
```
#### cmd run

Esegue un comando salvato (utilizza il contesto con cui è stato salvato).

- `<name>` — Nome del comando salvato da eseguire
- `--override-context`, `-o` — Sostituisce 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 d'ambiente```bash
envsec cmd run deploy

# Run quietly (suppress informational output like "Resolved N secret(s)")
envsec cmd run deploy --quiet
envsec cmd run deploy -q

# Override the context at execution time
envsec cmd run deploy --override-context myapp.prod
envsec cmd run deploy -o myapp.prod

# Inject all context secrets as env vars when running a saved command
envsec cmd run deploy --inject
envsec cmd run deploy -i
```
#### cmd search

Cerca i 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
```
#### cmd delete

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
```
Le chiavi vengono convertite in `UPPER_SNAKE_CASE` (es. `api.token` → `API_TOKEN`).

### Esporta i segreti come variabili d'ambiente

Genera istruzioni di export da usare con `eval` o con il sourcing della shell.

- `--shell`, `-s` — Sintassi della shell di destinazione: `bash` (predefinita), `zsh`, `fish`, `powershell`
- `--unset`, `-u` — Genera comandi di unset/rimozione invece dell'export```bash
# Output export statements for eval (bash/zsh)
eval $(envsec -c myapp.dev env)

# Specify target shell syntax
envsec -c myapp.dev env --shell fish
envsec -c myapp.dev env --shell powershell

# Output unset commands to clean up exported variables
eval $(envsec -c myapp.dev env --unset)

# Combine shell and unset
envsec -c myapp.dev env --unset --shell fish
```
Shell supportati: `bash` (predefinito), `zsh`, `fish`, `powershell`. Le chiavi vengono convertite in `UPPER_SNAKE_CASE` (es. `api.token` → `API_TOKEN`). L'output va su stdout, quindi può essere passato tramite pipe a `eval` o eseguito direttamente tramite source — nessun file viene scritto su disco.

### Avvia una sessione shell con ambito secrets

Avvia una subshell interattiva con tutti i secrets del contesto iniettati come
variabili d'ambiente. Quando esegui `exit`, i secrets spariscono — nessuna pulizia necessaria.

- `--shell`, `-s` — Shell da avviare (`bash`, `zsh`, `fish`, `powershell`). Predefinito: rilevamento automatico
- `--no-inherit` — Non ereditare le variabili d'ambiente del processo padre
- `--quiet`, `-q` — Sopprime il banner di avvio/uscita```bash
envsec -c myapp.dev shell
```
```
## 🛠️ Installazione

### 📦 Installazione rapida

```bash
# Clona il repository
git clone https://github.com/example/tool.git
cd tool

# Installa le dipendenze
pip install -r requirements.txt

# Esegui lo strumento
python main.py --help
```

### 🐳 Installazione con Docker

```bash
docker build -t tool .
docker run -it --rm tool --help
```

### 📝 Requisiti

- Python 3.8 o superiore
- pip
- Accesso a Internet (per il download delle dipendenze)

---

## 🚀 Utilizzo

### Comandi di base

```bash
python main.py scan --target example.com
python main.py report --format html
```

### Opzioni avanzate

| Opzione | Descrizione | Valore predefinito |
|---------|-------------|-------------------|
| `--target` | URL o IP di destinazione | Nessuno (obbligatorio) |
| `--threads` | Numero di thread da utilizzare | `10` |
| `--timeout` | Timeout della richiesta in secondi | `30` |
| `--verbose` | Output dettagliato | `false` |

### Esempi

```bash
# Scansione di base
python main.py scan --target https://example.com

# Scansione con 20 thread e timeout di 60 secondi
python main.py scan --target https://example.com --threads 20 --timeout 60

# Genera un report in formato HTML
python main.py report --format html --output report.html
```

---

## 📊 Output

Lo strumento genera i seguenti tipi di output:

1. **Output della console** - Risultati in tempo reale visualizzati nel terminale
2. **File di report** - Report dettagliati in formato JSON, HTML o Markdown
3. **File di log** - Log completi dell'esecuzione per il debug

### Struttura del report

```json
{
  "scan_id": "uuid-generato",
  "target": "https://example.com",
  "timestamp": "2024-01-01T12:00:00Z",
  "results": [
    {
      "type": "vulnerability",
      "severity": "high",
      "description": "Descrizione della vulnerabilità"
    }
  ]
}
```

---

## 🔧 Configurazione

### File di configurazione

Lo strumento supporta un file di configurazione in formato YAML:

```yaml
# config.yaml
target:
  timeout: 30
  threads: 10
  user_agent: "Mozilla/5.0"

report:
  format: "html"
  output_dir: "./reports"
```

### Variabili d'ambiente

| Variabile | Descrizione |
|-----------|-------------|
| `TOOL_API_KEY` | Chiave API per i servizi esterni |
| `TOOL_PROXY` | URL del proxy da utilizzare |
| `TOOL_DEBUG` | Abilita la modalità di debug (`true`/`false`) |

---

## 📚 Documentazione

Per una documentazione completa, consulta:

- [Guida per l'utente](https://github.com/davidnussio/envsec/blob/main/docs/user-guide.md)
- [Riferimento API](https://github.com/davidnussio/envsec/blob/main/docs/api-reference.md)
- [FAQ](https://github.com/davidnussio/envsec/blob/main/docs/faq.md)

---

## 🤝 Contributi

I contributi sono benvenuti! Per favore, segui questi passaggi:

1. Fai un fork del repository
2. Crea un nuovo branch (`git checkout -b feature/amazing-feature`)
3. Committa le tue modifiche (`git commit -m 'Aggiungi una funzionalità straordinaria'`)
4. Pusha il branch (`git push origin feature/amazing-feature`)
5. Apri una Pull Request

---

## 📄 Licenza

Distribuito sotto la licenza MIT. Vedi `LICENSE` per maggiori informazioni.

---

## 📧 Contatti

- **Sito web**: [https://example.com](https://example.com)
- **Email**: [email protected]
- **Twitter**: [@tool](https://twitter.com/tool)

---

## 🙏 Ringraziamenti

- Alla comunità open source per il supporto continuo
- A tutti i contributori che hanno dedicato tempo e sforzo
- Agli utenti che hanno fornito feedback preziosi

---

*Ultimo aggiornamento: gennaio 2024*

# 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
farvi riferimento negli script o nelle personalizzazioni del prompt.

### Caricare i segreti da un file .env

Importa i segreti da un file `.env` in un contesto.

- `--input`, `-i` — Percorso del file `.env` di input (predefinito: `.env`)
- `--force`, `-f` — Sovrascrive i segreti esistenti senza richiedere conferma
- `--batch`, `-b` — Modalità batch: rimanda la persistenza nel database finché tutti i segreti non sono stati importati```bash
# Import secrets from .env into the context
envsec -c myapp.dev load

# Specify a custom input file
envsec -c myapp.dev load --input .env.local

# Overwrite existing secrets without warning
envsec -c myapp.dev load --force
```
Le chiavi vengono convertite da `UPPER_SNAKE_CASE` a `dotted.lowercase` (es. `API_TOKEN` → `api.token`). Se una chiave esiste già, viene saltata con un avviso a meno che non venga fornito `--force` (`-f`).

### Condividi segreti (crittografati con GPG)

Crittografa tutti i segreti di 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 (predefinito: stdout). Usa `-` per stdout esplicitamente
- `--json` — Usa il formato JSON all'interno del payload crittografato (predefinito: 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ò decifrare con `gpg --decrypt secrets.enc` e convogliare il risultato in `envsec load`. Di default il payload cifrato usa il formato `.env` (`KEY="value"`); con `--json` usa un oggetto JSON strutturato. Richiede che GPG sia installato e che la chiave pubblica del destinatario sia nel tuo portachiavi.

### Controlla i segreti per la scadenza

Verifica la presenza di segreti scaduti o in scadenza e delle 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```bash
# Check for expired or expiring secrets in a context (default window: 30 days)
envsec -c myapp.dev audit

# Specify a custom window
envsec -c myapp.dev audit --within 7d

# Show only already-expired secrets
envsec -c myapp.dev audit --within 0d

# Audit across all contexts (omit --context)
envsec audit

# JSON output
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 inline.

Il comando `audit` traccia anche i file `.env` generati. Ogni volta che viene usato `env-file`, vengono registrati il percorso di output, il contesto e il timestamp. L'output di audit include una seconda sezione che elenca questi file. Se un file `.env` tracciato non esiste più su disco, audit lo rimuove automaticamente dai metadati e segnala la pulizia.

### Genera un segreto casuale

Genera un segreto casuale crittograficamente sicuro, con la possibilità di salvarlo.

- `<key>` — Nome della chiave del segreto (opzionale; ometti per la generazione autonoma di password)
- `--length`, `-l` — Lunghezza del segreto generato (predefinito: `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]` (predefinito)
- `--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 vengono forniti sia il contesto che la chiave, il valore generato viene salvato e stampato. Senza nessuno dei due, il valore grezzo viene inviato a stdout — utile per il piping a `pbcopy`, `xclip` o altri strumenti.

### TUI interattiva

envsec include un'interfaccia terminale a schermo intero per gestire i segreti in modo interattivo — senza bisogno di memorizzare i comandi.```bash
# Launch the TUI
envsec tui

# Launch with a pre-selected context
envsec -c myapp.dev tui
```
La TUI fornisce otto schermate accessibili dal menu principale:

- **Contexts** — sfoglia tutti i contesti, imposta il contesto attivo con `s`, cancella il contesto con `x`, visualizza i conteggi dei segreti, elimina interi contesti
- **Secrets** — elenca i segreti in una tabella, rivela i valori, aggiungi o elimina segreti
- **Add Secret** — modulo interattivo con input mascherato e durata di scadenza opzionale
- **Search** — ricerca con pattern glob tra segreti o contesti
- **Saved Commands** — elenca, visualizza ed elimina modelli di comandi salvati
- **Audit** — verifica la presenza di segreti scaduti/in scadenza, rivedi le esportazioni tracciate dei file `.env`
- **Import .env** — carica segreti da un file `.env` nel contesto corrente
- **Export .env** — esporta segreti in un file `.env` (tracciato per l'audit)

Scorciatoie da tastiera:

| Tasto | Azione |
|-----|--------|
| `↑` / `↓` | Naviga tra le voci del menu e le righe della tabella |
| `Enter` | Seleziona / conferma |
| `c` | Apre la vista contesti (menu principale) |
| `s` | Imposta l'elemento selezionato come contesto attivo (vista contesti) |
| `x` | Cancella il contesto attivo (vista contesti) |
| `a` | Aggiunge un nuovo segreto (vista segreti) |
| `d` | Elimina l'elemento selezionato |
| `r` | Rivela il valore del segreto (vista dettagli) |
| `Esc` | Torna indietro / annulla |
| `q` | Esce dalla TUI |

### Diagnostica la tua configurazione

Esegui controlli di integrità per verificare la tua installazione di envsec.

- `--json` — Output in formato JSON per lo scripting```bash
# Run all health checks
envsec doctor

# JSON output for scripting
envsec --json doctor
```
Il comando `doctor` verifica che la tua installazione di envsec funzioni correttamente. Controlla:
- Supporto della piattaforma e versione di Node.js
- Disponibilità dell'archivio delle credenziali (macOS Keychain, Linux secret-tool, Windows cmdkey)
- Accesso in lettura/scrittura al portachiavi
- Percorso del database, permessi e integrità dello schema
- Segreti orfani (metadati senza voce nel portachiavi)
- Segreti scaduti
- Variabili d'ambiente (`ENVSEC_DB`, `ENVSEC_CONTEXT`)
- Shell corrente

### Completamenti della shell

envsec supporta il completamento dinamico tramite tab per bash, zsh e fish. I completamenti sono sensibili al contesto: suggeriscono i nomi dei tuoi contesti effettivi, le chiavi dei segreti e i nomi dei comandi salvati in tempo reale interrogando il database dei metadati.```bash
# Bash (add to ~/.bashrc)
eval "$(envsec --completions bash)"

# Zsh (add to ~/.zshrc)
eval "$(envsec --completions zsh)"

# Fish (add to ~/.config/fish/config.fish)
envsec --completions fish | source
```
Cosa 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.) vengono anch'essi completati

## Confronto

Come si confronta envsec con altri strumenti per la gestione dei segreti di ambiente?

| Funzionalità | 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) | Vault cloud 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 per impostazione predefinita | 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 (gli elementi memorizzati nella cache sono 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 business) |
| 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 elementi |
| Esecuzione comandi con segreti | `envsec run` — interpolazione segnaposto + variabili d'ambiente `--inject` | `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 elementi |
| 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` — sottoshell 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` — segreti 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 dei 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 interattiva | `envsec tui` — interfaccia terminale a schermo intero | Non integrato | Non integrato |
| Diagnostica salute | `envsec doctor` — verifica piattaforma, keychain, 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 / multi-utente | Condivisione GPG (manuale) | Condivisione basata su git con `.env` crittografato (dotenvx) | Gestione team integrata, RBAC, log di audit |
<!-- | Integrazione CI/CD | CLI standard — funziona ovunque giri Node.js | `dotenvx run` in qualsiasi pipeline CI | Account di servizio, integrazioni CI/CD native | -->
| Autenticazione biometrica | Eredita le biometrie 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 elementi e log di audit basati su cloud |

In breve: dotenv è l'approccio più semplice (file su disco), la CLI 1Password è la più ricca di funzionalità per i team con sincronizzazione cloud e RBAC, e envsec si colloca nel mezzo — offrendo crittografia nativa del sistema operativo con zero account, zero dipendenze cloud e un flusso di lavoro orientato agli sviluppatori che va oltre ciò che i file `.env` possono fare.

## Come funziona

I segreti sono archiviati nell'archivio credenziali nativo del sistema operativo. Il backend viene selezionato automaticamente in base alla piattaforma:

| OS      | Backend                        | Strumento / API                          |
|---------|--------------------------------|-------------------------------------|
| macOS   | Keychain                       | CLI `security`                      |
| Linux   | API Secret Service (D-Bus)     | `secret-tool` (libsecret)           |
| Windows | Credential Manager             | `cmdkey` + PowerShell (advapi32)    |

I metadati (nomi chiave, 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 dotfile. Ogni decisione di progettazione parte da questa base.

### Come envsec protegge i tuoi segreti

**Crittografia nativa del sistema operativo, zero crittografia personalizzata.** I valori segreti sono archiviati direttamente in macOS Keychain, GNOME Keyring / KDE Wallet o Windows Credential Manager. envsec non inventa mai la propria crittografia — delega agli archivi credenziali collaudati che il tuo sistema operativo già fornisce, protetti dalla tua sessione utente e (su macOS) dal keychain di accesso.

**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 che codifica in esadecimale l'output non ASCII). I segreti legacy in chiaro vengono letti in modo trasparente per compatibilità con le versioni precedenti.

**I segreti non toccano mai il disco come testo in chiaro.** I valori vanno direttamente dal tuo terminale all'archivio credenziali del sistema operativo. Non vengono mai scritti in file di configurazione, log o archiviazione intermedia.

**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 sguardi indiscreti.

**Esecuzione sicura dei comandi.** Il comando `run` inietta i segreti come variabili d'ambiente del processo figlio anziché interpolarli nella stringa di comando. Questo significa che i valori segreti non compaiono nell'output di `ps` o nella cronologia della shell. Se manca un segreto referenziato, il comando viene bloccato completamente — nessuna esecuzione parziale con credenziali incomplete.

**Validazione dell'input e prevenzione dell'iniezione.** I nomi dei contesti vengono validati rispetto a un elenco consentito rigoroso (alfanumerici, punti, trattini, underscore) con controlli di path traversal e prototipo pollution. Tutte le query SQLite utilizzano istruzioni preparate con parametri bind, prevenendo l'iniezione SQL. Gli argomenti PowerShell su Windows vengono escaped per proteggere dall'iniezione di comandi.

**Permessi file restrittivi.** 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` archivia nomi chiave, nomi contesto e timestamp — mai valori segreti, ma abbastanza per rivelare *quali* segreti esistono. I modelli di comando salvati (con segnaposto `{key}`) sono anch'essi archiviati 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 un rischio intrinseco.** 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 attendibile, è 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 tuo utente del sistema operativo può leggere tutti i segreti in tutti i contesti. envsec si affida all'isolamento a livello di utente del 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 i segreti con protezione più debole.

**La crittografia dipende dal tuo sistema operativo.** envsec non aggiunge alcuna crittografia a riposo aggiuntiva oltre a quella fornita dall'archivio credenziali nativo. Su sistemi senza crittografia completa del disco, un attaccante con accesso fisico potrebbe potenzialmente estrarre i segreti dal keychain. Raccomandiamo di abilitare la crittografia completa del disco (FileVault, LUKS, BitLocker) per la protezione più forte.

## Sviluppo

### Prerequisiti

- Node.js >= 22
- pnpm

I pacchetti core, SDK, CLI e TUI utilizzano Effect 4 e sono attualmente bloccati su
`4.0.0-rc.112`. Mantieni allineate le versioni di Effect e `@effect/platform-node`
in tutto il workspace mentre Effect 4 rimane in stato di release candidate.

### Configurazione```bash
git clone https://github.com/davidnussio/envsec.git
cd envsec
pnpm install
pnpm run build
```
### Struttura del Progetto```
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

# Run package unit and contract tests
pnpm run test:unit

# Run the CLI end-to-end suite with isolated database and credential fixtures
pnpm --filter envsec test

# Release (build + changeset publish)
pnpm run release
```
Il test E2E isolato non accede mai al deposito nativo delle credenziali. Per esercitare
il vero adapter di sistema su macOS o Linux, compila prima e attiva esplicitamente:```bash
ENVSEC_E2E_CLI="$PWD/packages/cli/dist/main.js" \
  ENVSEC_E2E_ISOLATED=0 \
  pnpm --filter envsec test
```
I test E2E nativi utilizzano contesti dedicati `test.e2e*` e li rimuovono successivamente.

### Esecuzione locale senza installazione

Crea un alias temporaneo per utilizzare la build locale come se fosse installata globalmente:```bash
# Bash / Zsh
alias envsec="node $(pwd)/packages/cli/dist/main.js"

# Fish
alias envsec "node (pwd)/packages/cli/dist/main.js"
```
### Testare le completions della shell localmente

Dopo aver compilato e configurato l'alias, carica le completions nella 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
```
Poi premi TAB dopo `envsec -c ` per vedere i tuoi contesti, oppure dopo `envsec -c myapp.dev get ` per vedere le chiavi dei segreti.

### Esecuzione dei test

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
# Build first
pnpm run build

# macOS / Linux
bash packages/cli/test/e2e-test.sh

# Windows (PowerShell)
pwsh packages/cli/test/e2e-test.ps1
```
CI viene eseguito 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