npm package: @nubemsystems/secrets-cli
Description: CLI para gestión segura de secretos con cifrado E2E - inyecta secretos en memoria sin exponerlos
Author: NubemSystems
Latest version: 1.0.4

# NubemSecrets CLI

Sistema de gestion de secretos con **cifrado E2E** donde los valores **nunca viajan en texto plano**.

---

## Que es NubemSecrets

Un gestor de secretos que permite almacenar API keys, contrasenas y credenciales de forma segura, con dos modos de uso:

| Modo | Uso | Secretos en |
|------|-----|-------------|
| `run` | Desarrollo local | Memoria RAM (nunca en disco) |
| `sync` | Produccion | GCP Secret Manager |

---

## Arquitectura

```
┌─────────────────────────────────────────────────────────────────────┐
│                        NUBEMSECRETS                                 │
│                    (Fuente unica de verdad)                         │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │  Vaults → Secretos (cifrados AES-256-GCM + KMS)              │  │
│  └──────────────────────────────────────────────────────────────┘  │
└───────────────────────────┬─────────────────────────────────────────┘
                            │
         ┌──────────────────┼──────────────────┐
         │                  │                  │
         ▼                  ▼                  ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│  CLI: run       │ │  CLI: sync      │ │  Cloud Run      │
│  (E2E + RAM)    │ │  (→ GCP SM)     │ │  (lee de GCP)   │
└─────────────────┘ └─────────────────┘ └─────────────────┘
     LOCAL              DEPLOY              PRODUCCION
```

---

## Inicio Rapido

### 1. Crear cuenta y guardar secretos

1. Ve a **https://nubemsecrets.app** (o tu instancia)
2. Inicia sesion con Google
3. Se crea tu **vault personal**
4. Anade tus secretos (API keys de OpenAI, Supabase, etc.)

### 2. Crear API Key

1. En NubemSecrets web → **Configuracion** → **API Keys**
2. Clic en **"Nueva API Key"**
3. Copia la key (`nbm_live_...`) - solo se muestra una vez

### 3. Instalar el CLI

```bash
cd cli
npm link
```

### 4. Configurar API Key

```bash
# Variable de entorno (recomendado)
export NBM_API_KEY="nbm_live_tu_key_aqui"

# Anadirlo a tu .zshrc/.bashrc
echo 'export NBM_API_KEY="nbm_live_tu_key_aqui"' >> ~/.zshrc
```

---

## Comandos

### Listar vaults

```bash
nbm-secrets vaults
```

### Listar secretos

```bash
nbm-secrets list --vault <vault_id>
```

### Ejecutar con secretos en memoria (`run`)

```bash
nbm-secrets run --vault <vault_id> -- <comando>
```

**Ejemplo:**
```bash
nbm-secrets run --vault abc123 -- npm start
```

Los secretos se obtienen via **E2E cifrado**, se descifran en memoria y se inyectan como variables de entorno al proceso hijo. **Nunca tocan el disco.**

### Sincronizar a GCP Secret Manager (`sync`)

```bash
nbm-secrets sync --vault <vault_id> --to-gcp <gcp_project_id>
```

**Ejemplo:**
```bash
# Simular (dry-run)
nbm-secrets sync --vault abc123 --to-gcp mi-proyecto --dry-run

# Ejecutar
nbm-secrets sync --vault abc123 --to-gcp mi-proyecto
```

### Verificar secreto en .env

```bash
nbm-secrets verify <NOMBRE_VAR>
```

---

## Flujos de Uso

### Desarrollo Local

```bash
# Los secretos SOLO existen en RAM mientras corre el proceso
nbm-secrets run --vault prod -- npm start

# Con Docker
nbm-secrets run --vault prod -- docker run -p 8000:8000 \
  -e OPENAI_API_KEY \
  -e SUPABASE_URL \
  mi-imagen
```

**Tu app no cambia nada:**
```javascript
// Funciona igual que con .env
const apiKey = process.env.OPENAI_API_KEY;
```

### Produccion (Cloud Run, GKE)

```bash
# 1. Sincronizar secretos a GCP Secret Manager
nbm-secrets sync --vault prod --to-gcp mi-proyecto

# 2. Configurar Cloud Run para leer de GCP SM
gcloud run deploy mi-app \
  --set-secrets=OPENAI_API_KEY=openai-api-key:latest
```

---

## Seguridad - Cifrado E2E

| Punto de control | Secreto visible |
|------------------|-----------------|
| En transito (red) | NO - cifrado ECDH + AES-256-GCM |
| En servidor NubemSecrets | NO - cifrado con KMS |
| En disco local | NO - solo en RAM |
| En RAM del proceso | SI - mientras ejecuta |
| En GCP Secret Manager | SI - despues de sync |

### Protocolo E2E

```
CLI                                    SERVIDOR
 │                                        │
 ├─► Genera par ECDH efimero              │
 │   (cliPrivate, cliPublic)              │
 │                                        │
 ├──────── POST /api/e2e/secrets ─────────►
 │   { publicKey, vaultId }               │
 │                                        │
 │                      Genera par ECDH ◄─┤
 │                      Deriva sharedKey   │
 │                      Cifra secretos     │
 │                                        │
 ◄─────────── Response ───────────────────┤
 │   { serverPublicKey, encrypted,        │
 │     iv, authTag }                      │
 │                                        │
 ├─► Deriva misma sharedKey               │
 ├─► Descifra secretos                    │
 ├─► Inyecta en proceso hijo              │
 └─► NUNCA escribe a disco                │
```

---

## Variables de Entorno

| Variable | Descripcion |
|----------|-------------|
| `NBM_API_KEY` | API Key de NubemSecrets (requerida) |
| `NBM_API_URL` | URL del servidor (opcional) |

---

## Integracion MCP

Configura el servidor MCP en Claude Code:

```bash
claude mcp add nubemsecrets \
  https://nubemsecrets-api-xxx.run.app/api/mcp \
  --scope user \
  --transport http \
  --header "X-API-Key: nbm_live_tu_key"
```

El MCP permite a Claude listar vaults y secretos (sin valores) para ayudarte a gestionar tus credenciales.

---

## Ejemplo Completo

```bash
# 1. Configurar
export NBM_API_KEY="nbm_live_xxxxx"

# 2. Ver vaults y secretos
nbm-secrets vaults
nbm-secrets list --vault abc123

# 3. Desarrollo local (secretos en RAM)
nbm-secrets run --vault abc123 -- npm start

# 4. Despliegue a produccion
nbm-secrets sync --vault abc123 --to-gcp mi-proyecto

# 5. Cloud Run lee de GCP Secret Manager nativamente
```

---

## Troubleshooting

### "API Key requerida"

```bash
export NBM_API_KEY="nbm_live_tu_key"
```

### "No autenticado"

Verifica que la API Key es valida y tiene los scopes correctos.

### "No se pudo obtener token de GCP"

Para el comando `sync`, necesitas estar autenticado con GCP:
```bash
gcloud auth login
```

---

## Licencia

MIT - NubemSystems