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

cd cli
npm link

4. Configurar API Key

# 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

nbm-secrets vaults

Listar secretos

nbm-secrets list --vault <vault_id>

Ejecutar con secretos en memoria (run)

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

Ejemplo:

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)

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

Ejemplo:

# 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

nbm-secrets verify <NOMBRE_VAR>

Flujos de Uso

Desarrollo Local

# 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:

// Funciona igual que con .env
const apiKey = process.env.OPENAI_API_KEY;

Produccion (Cloud Run, GKE)

# 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:

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

# 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"

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:

gcloud auth login

Licencia

MIT - NubemSystems