q-ring

Almacena secretos en el llavero del sistema operativo (macOS/Linux/Windows) y exponlos a agentes de codificación de IA mediante 44 herramientas MCP gobernadas por políticas.

GitHub

Prueba este MCPPatrocinado

Documentación

q-ring

Secretos del llavero del sistema operativo para agentes de codificación de IA, a través de MCP.

Deja de pegar claves de API en archivos .env de texto plano o de luchar con gestores de secretos torpes. q-ring ancla de forma segura tus credenciales al almacén nativo de tu sistema operativo (Llavero de macOS, Servicio de Secretos de Linux, Almacén de Credenciales de Windows) y las potencia con mecánicas de la física cuántica.

📖 Consulta la Documentación Oficial para una referencia completa de la CLI, recetarios de prompts para MCP y detalles de arquitectura.

¿Por qué q-ring?

Superposición: Almacena una clave con múltiples estados (dev/staging/prod) que colapsan según el contexto.
Entrelazamiento: Vincula claves entre proyectos para que al rotar una, todas se actualicen automáticamente.
Efecto túnel: Crea secretos efímeros en memoria que se autodestruyen tras un tiempo o un número de lecturas.
Teletransportación: Empaqueta y comparte de forma segura paquetes de secretos cifrados con AES-256-GCM.
Integración fluida con IA: 46 herramientas MCP integradas para uso nativo en Cursor, Kiro y Claude Code.

🚀 Instalación

q-ring está diseñado para instalarse globalmente y estar disponible en cualquier lugar de tu terminal. Elige tu gestor de paquetes favorito:

# pnpm (recommended)
pnpm add -g @i4ctime/q-ring

# npm
npm install -g @i4ctime/q-ring

# yarn
yarn global add @i4ctime/q-ring

# Homebrew (macOS / Linux)
brew install i4ctime/tap/qring

Docker (servidor MCP)

El repositorio incluye un Dockerfile que compila el servidor MCP y lo expone a través de mcp-proxy — útil para despliegues MCP alojados (p. ej. Glama) o para mantener el servidor fuera del host por completo:

git clone https://github.com/I4cTime/q-ring.git
cd q-ring
docker build -t qring-mcp .
docker run --rm -p 8080:8080 qring-mcp

Nota: dentro de un contenedor no hay llavero del sistema operativo (GNOME Keyring / Llavero de macOS), por lo que esta vía es para la superficie del protocolo MCP, uso efímero y experimentos de CI — no para almacenamiento duradero de secretos local. Para el uso diario, instala la CLI de forma nativa mediante uno de los gestores de paquetes anteriores.

⚡ Inicio Rápido

# 1️⃣ Store a secret (prompts securely if value is omitted)
qring set OPENAI_API_KEY sk-...

# 2️⃣ Retrieve it anytime
qring get OPENAI_API_KEY

# 3️⃣ List all keys (values are never shown)
qring list

# 4️⃣ Generate a cryptographic secret and save it
qring generate --format api-key --prefix "sk-" --save MY_KEY

# 5️⃣ Run a full health scan
qring health

# Something not working? Diagnose the install (keyring, audit, MCP wiring)
qring doctor

# Tab completion for your shell
qring completion zsh > ~/.zsh/completions/_qring   # also: bash, fish

Funciones Cuánticas

Superposición — Una Clave, Múltiples Entornos

Un único secreto puede contener diferentes valores para dev, staging y prod simultáneamente. El valor correcto se resuelve según tu contexto actual.

# Set environment-specific values
qring set API_KEY "sk-dev-123" --env dev
qring set API_KEY "sk-stg-456" --env staging
qring set API_KEY "sk-prod-789" --env prod

# Value resolves based on context
QRING_ENV=prod qring get API_KEY   # → sk-prod-789
QRING_ENV=dev  qring get API_KEY   # → sk-dev-123

# Inspect the quantum state
qring inspect API_KEY

Promoción de Entornos — Compara, Luego Promueve

Una vez que un secreto lleva estados por entorno, la promoción reemplaza al copiar y pegar: compara dos entornos clave por clave (solo estados, nunca valores), luego copia un valor de un estado a otro. diff sale con código 1 si hay desviación, por lo que también sirve como compuerta de CI; promote se niega a sobrescribir un destino diferente a menos que lo confirmes.

# What differs between staging and prod? (same / different / missing on one side)
qring diff staging prod

# Make prod match staging for one key (asks before overwriting a different value)
qring promote DATABASE_URL --from staging --to prod

# Non-interactive, e.g. in a release script
qring promote DATABASE_URL --from staging --to prod --force --json

Los agentes MCP obtienen las mismas dos operaciones como diff_environments y promote_secret.

Colapso de la Función de Onda — Detección Inteligente de Entorno

q-ring detecta automáticamente tu entorno sin banderas explícitas. Orden de resolución:

Bandera --env
Variable de entorno QRING_ENV
Variable de entorno NODE_ENV
Heurísticas de rama Git (main/master → prod, develop → dev)
Configuración de proyecto .q-ring.json
Entorno predeterminado del secreto

# See what environment q-ring detects
qring env

# Project config (.q-ring.json)
echo '{"env": "staging", "branchMap": {"release/*": "staging"}}' > .q-ring.json

Decaimiento Cuántico — Secretos con TTL

Los secretos pueden tener un tiempo de vida. Los secretos caducados se bloquean para lecturas. Los secretos obsoletos (75%+ de vida útil) activan advertencias.

# Set a secret that expires in 1 hour
qring set SESSION_TOKEN "tok-..." --ttl 3600

# Set with explicit expiry
qring set CERT_KEY "..." --expires "2026-06-01T00:00:00Z"

# Health check shows decay status
qring health

Efecto Observador — Audita Todo

Cada lectura, escritura y eliminación de secretos se registra con una cadena de hash a prueba de manipulaciones. Los patrones de acceso se rastrean para la detección de anomalías.

# View audit log
qring audit
qring audit --key OPENAI_KEY --limit 50

# Detect anomalies (burst access, unusual hours, chain tampering)
qring audit --anomalies

# Verify audit chain integrity
qring audit:verify

# Export audit log
qring audit:export --format json --since 2026-03-01
qring audit:export --format csv --output audit-report.csv

Ruido Cuántico — Generación de Secretos

Genera secretos criptográficamente sólidos en formatos comunes.

qring generate                          # API key (default)
qring generate --format password -l 32  # Strong password
qring generate --format uuid            # UUID v4
qring generate --format token           # Base64url token
qring generate --format hex -l 64       # 64-byte hex
qring generate --format api-key --prefix "sk-live-" --save STRIPE_KEY

Entrelazamiento — Secretos Vinculados

Vincula secretos entre proyectos. Cuando rotas uno, todas las copias entrelazadas se actualizan automáticamente.

# Entangle two secrets
qring entangle API_KEY API_KEY_BACKUP

# Now updating API_KEY also updates API_KEY_BACKUP
qring set API_KEY "new-value"

# Unlink entangled secrets
qring disentangle API_KEY API_KEY_BACKUP

Efecto Túnel — Secretos Efímeros

Crea secretos que existen solo en memoria. Nunca tocan el disco. TTL opcional y autodestrucción por máximo de lecturas.

# Create an ephemeral secret (returns tunnel ID)
qring tunnel create "temporary-token-xyz" --ttl 300 --max-reads 1

# Read it (self-destructs after this read)
qring tunnel read tun_abc123

# List active tunnels
qring tunnel list

Teletransportación — Compartición Cifrada

Empaqueta secretos en paquetes cifrados con AES-256-GCM para transferencia segura entre máquinas. Dos formas de bloquear un paquete:

Frase de contraseña (v1): claves derivadas con PBKDF2-HMAC-SHA512 (210 000 iteraciones); cada paquete registra su número de iteraciones, por lo que los paquetes antiguos aún se descomprimen.
Destinatarios (v2, 0.18): cada compañero ejecuta qring teleport keygen una vez y comparte su cadena de destinatario (qring1…, una clave pública X25519; la mitad privada vive en su llavero del sistema operativo). pack --to cifra una clave de contenido nueva para cada destinatario — HKDF-SHA256 sobre un acuerdo X25519 efímero, AES-256-GCM en todo momento, solo node:crypto — por lo que nada secreto viaja junto al paquete y nadie tiene que susurrar una frase de contraseña.

# Passphrase bundle (prompts)
qring teleport pack --keys "API_KEY,DB_PASS" > bundle.txt
cat bundle.txt | qring teleport unpack

# Recipient bundle: teammates publish their recipient once…
qring teleport keygen            # → qring1a3F…  (share this; keep the keyring)
qring teleport identity          # print it again later

# …then you address the pack to them (repeatable or comma-separated)
qring teleport pack --keys "API_KEY,DB_PASS" --to qring1a3F… --to qring1Zz9… > bundle.txt

# They unpack with the identity in their keyring — no passphrase
cat bundle.txt | qring teleport unpack

# Preview: who it's addressed to, whether that's you, and what's inside
qring teleport unpack <bundle> --dry-run

Importación — Ingesta Masiva de Secretos

Importa secretos desde archivos .env directamente a q-ring. Soporta sintaxis estándar de dotenv, incluidos comentarios, valores entre comillas y secuencias de escape. La CLI acepta una ruta de archivo o contenido sin procesar; la herramienta MCP import_dotenv solo acepta contenido sin procesar (nunca lee archivos del disco) para que un agente no pueda obligarla a leer archivos locales arbitrarios.

# Import all secrets from a .env file
qring import .env

# Import to project scope, skipping existing keys
qring import .env --project --skip-existing

# Preview what would be imported
qring import .env --dry-run

Exportación Selectiva

Exporta solo los secretos que necesitas usando nombres de clave o filtros de etiquetas.

# Export specific keys
qring export --keys "API_KEY,DB_PASS,REDIS_URL"

# Export by tag
qring export --tags "backend"

# Combine with format
qring export --keys "API_KEY,DB_PASS" --format json

Búsqueda y Filtrado de Secretos

Filtra la salida de qring list por etiqueta, estado de caducidad o patrón de clave.

# Filter by tag
qring list --tag backend

# Show only expired secrets
qring list --expired

# Show only stale secrets (75%+ decay)
qring list --stale

# Glob pattern on key name
qring list --filter "API_*"

# Script-friendly existence check (exit 0 if present, 1 if not; decay-aware)
qring has OPENAI_API_KEY --quiet && echo "configured"

Manifiesto de Secretos del Proyecto

Declara los secretos requeridos en .q-ring.json y valida la preparación del proyecto con un solo comando.

# Validate project secrets against the manifest
qring check

# See which secrets are present, missing, expired, or stale
qring check --project-path /path/to/project

Sincronización de Archivos Env

Genera un archivo .env a partir del manifiesto del proyecto, resolviendo cada clave desde q-ring con colapso de superposición consciente del entorno.

# Generate to stdout
qring env:generate

# Write to a file
qring env:generate --output .env

# Force a specific environment
qring env:generate --env staging --output .env.staging

Referencias de Secretos y Ejecución con Privilegios Mínimos

Una referencia qring:// es un puntero confirmable a un secreto — va en tu archivo .env en lugar del valor. qring run resuelve referencias y claves del manifiesto en el momento del lanzamiento, inyectando solo lo que el proyecto declara (a diferencia de exec, que inyecta todo el ámbito). La salida se redacta automáticamente.

# .env — safe to commit: these are references, not values
DATABASE_URL=qring://project/DATABASE_URL
OPENAI_API_KEY=qring://global/OPENAI_API_KEY
STRIPE_KEY=qring:///STRIPE_KEY            # auto scope: project, then global
SESSION_TTL=3600                          # plain values pass through

# Run with declared secrets injected (manifest + .env refs)
qring run -- pnpm dev

# Preview what would be injected, without running
qring run --dry-run -- pnpm dev

# Pin an environment, use a specific env file, or skip the manifest
qring run --env prod --env-file .env.prod --no-manifest -- ./deploy.sh

La clave vive en la ruta, nunca en el host (qring://project/KEY, no qring://KEY) — los hosts de URL no distinguen entre mayúsculas y minúsculas, y las claves de variables de entorno sí. Las referencias malformadas fallan de forma ruidosa en lugar de filtrar una cadena literal qring://… al hijo. Una referencia fijada a un entorno: qring://project/DATABASE_URL?env=prod.

Configuración del Editor

Conecta el servidor MCP de q-ring a la configuración MCP de un editor con un comando. Fusiona de forma no destructiva — otros servidores se conservan, y una entrada existente de q-ring solo se reemplaza con --force.

qring setup cursor          # .cursor/mcp.json (project) or --global for ~/.cursor
qring setup kiro            # .kiro/settings/mcp.json, with read-only autoApprove list
qring setup claude          # .mcp.json (project scope)

# Preview without writing
qring setup cursor --dry-run

Envío a Plataformas de Despliegue

Envía secretos del manifiesto a GitHub Actions, Vercel, Cloudflare Workers, fly.io, Railway o Netlify a través de la propia CLI autenticada de cada plataforma (gh / vercel / wrangler / flyctl / railway / netlify) — q-ring nunca retiene tokens de plataforma, y los valores viajan por stdin (o, para la CLI de solo importación de Netlify, un archivo temporal 0600 que se elimina de inmediato), nunca por argv. Cada envío se registra en la cadena de auditoría.

# Push the .q-ring.json manifest keys to GitHub Actions secrets
qring push github --repo you/your-app

# Push to Vercel environments
qring push vercel --vercel-env production,preview

# Push to Cloudflare Workers secrets
qring push cloudflare

# fly.io (flyctl secrets import over stdin — note flyctl deploys per import), Railway, Netlify
qring push fly --app my-app
qring push railway --service api --railway-env production
qring push netlify --site 1234-abcd

# Explicit keys, preview first
qring push github --keys DATABASE_URL,API_KEY --dry-run

Los canarios pueden viajar junto: qring canary plant KEY --format aws --push github planta un honeytoken localmente y lo siembra en la plataforma sin leerlo de vuelta (ver Canary Honeytokens).

Validación de Vitalidad de Secretos

Prueba si un secreto es realmente válido con su servicio objetivo. q-ring detecta automáticamente el proveedor a partir de prefijos de clave (sk- → OpenAI, ghp_ → GitHub, etc.) o acepta un nombre de proveedor explícito.

# Validate a single secret
qring validate OPENAI_API_KEY

# Force a specific provider
qring validate SOME_KEY --provider stripe

# Validate all secrets with detectable providers
qring validate --all

# Only validate manifest-declared secrets
qring validate --all --manifest

# List available providers
qring validate --list-providers

Proveedores integrados: OpenAI, Anthropic, OpenRouter, Google AI (Gemini), Groq, Hugging Face, ElevenLabs*, Vercel*, Stripe, GitHub, AWS (verificación de formato), HTTP genérico. Las claves solo se envían en encabezados, nunca en URLs. (*sin prefijo público seguro — selecciona explícitamente con --provider o el campo provider del manifiesto.)

Salida:

  ✓ OPENAI_API_KEY   valid    (openai, 342ms)
  ✗ STRIPE_KEY       invalid  (stripe, 128ms) — API key has been revoked
  ⚠ AWS_ACCESS_KEY   error    (aws, 10002ms) — network timeout
  ○ DATABASE_URL     unknown  — no provider detected

Hooks — Devoluciones de Llamada en Cambio de Secretos

Registra webhooks, comandos de shell o señales de proceso que se activan cuando los secretos se crean, actualizan o eliminan. Soporta coincidencia de claves, patrones glob, filtrado de etiquetas y restricciones de ámbito.

# Run a shell command when a secret changes
qring hook add --key DB_PASS --exec "docker restart app"

# POST to a webhook on any write/delete
qring hook add --key API_KEY --url "https://hooks.example.com/rotate"

# Trigger on all secrets tagged "backend"
qring hook add --tag backend --exec "pm2 restart all"

# Signal a process when DB secrets change
qring hook add --key-pattern "DB_*" --signal-target "node"

# List all hooks
qring hook list

# Remove a hook
qring hook remove <id>

# Enable/disable
qring hook enable <id>
qring hook disable <id>

# Dry-run test a hook
qring hook test <id>

Los hooks son de tipo disparar y olvidar: un hook que falla nunca bloquea las operaciones de secretos. El registro de hooks se almacena en ~/.config/q-ring/hooks.json.

Protección SSRF: Las URLs de hooks HTTP que apuntan a rangos IP privados/de bucle local (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, ::1, fc00::/7) se bloquean de forma predeterminada. El DNS se verifica de antemano y se revalida en el momento de la conexión, por lo que un nombre de host no puede pasar la verificación y luego reenlazarse a una dirección privada antes de que se abra el socket. Para permitir hooks dirigidos a servicios locales (p. ej. durante el desarrollo), establece la variable de entorno Q_RING_ALLOW_PRIVATE_HOOKS=1.

Rotación Configurable

Establece un formato de rotación por secreto para que el agente rote automáticamente con la forma de valor correcta, y un intervalo de rotación para que q-ring te recuerde antes de que una credencial quede obsoleta. Cada secreto recuerda cuándo cambió su valor por última vez (rotatedAt); con --rotate-every se vuelve próximo a vencer dentro del último 20% del intervalo (o los últimos 7 días, lo que sea más corto) y vencido más allá — en qring inspect, qring rotate:due, la tarjeta "Rotar pronto" del panel y la herramienta inspect_secret.

# Store a secret with rotation format metadata
qring set STRIPE_KEY "sk-..." --rotation-format api-key --rotation-prefix "sk-"

# Store a password with password rotation format
qring set DB_PASS "..." --rotation-format password

# Remind me every 90 days
qring set STRIPE_KEY "sk-..." --rotate-every 90

# What needs rotating? (most overdue first; --all lists every scheduled secret)
qring rotate:due
qring rotate:due --json

Ejecución Segura y Redacción Automática

Ejecuta comandos con secretos inyectados de forma segura en el entorno. Todos los valores de secretos conocidos se redactan automáticamente de stdout y stderr para evitar fugas en registros de terminal o transcripciones de agentes. Los perfiles de ejecución restringen qué comandos pueden ejecutarse.

# Execute a deployment script with secrets injected
qring exec -- npm run deploy

# Inject only specific tags
qring exec --tags backend -- node server.js

# Run with a restricted profile (blocks network tools and interpreters/shells, 30s timeout)
qring exec --profile restricted -- npm test

Escáner de Secretos en el Código

¿Migrando una base de código heredada? Escanea rápidamente directorios en busca de credenciales codificadas usando heurísticas de regex y análisis de entropía de Shannon.

# Scan current directory
qring scan .

Salida:

  ✗ src/db/connection.js:12
    Key:     DB_PASSWORD
    Entropy: 4.23
    Context: const DB_PASSWORD = "..."

Secretos Compuestos / con Plantillas

Almacena cadenas de conexión complejas que resuelven dinámicamente otros secretos. Si DB_PASS rota, DB_URL se corrige automáticamente sin actualizaciones manuales.

qring set DB_USER "admin"
qring set DB_PASS "supersecret"
qring set DB_URL "postgres://{{DB_USER}}:{{DB_PASS}}@localhost/mydb"

# Resolves embedded templates automatically
qring get DB_URL 
# Output: postgres://admin:supersecret@localhost/mydb

Aprobaciones de Usuario (Agente de Confianza Cero)

Protege secretos de producción sensibles de ser leídos de forma autónoma por el servidor MCP sin aprobación explícita del usuario. Cada token de aprobación se verifica con HMAC, tiene ámbito, está razonado y limitado en el tiempo. La compuerta se aplica también a lecturas masivas — export_secrets y teleport_pack a través de MCP omiten claves protegidas por aprobación que carecen de una concesión válida.

# Mark a secret as requiring approval
qring set PROD_DB_URL "..." --requires-approval

# Temporarily grant MCP access for 1 hour with a reason
qring approve PROD_DB_URL --for 3600 --reason "deploying v2.0"

# List all approvals with verification status
qring approvals

# Revoke an approval
qring approve PROD_DB_URL --revoke

Cuando un agente se bloquea en una clave protegida por aprobación, q-ring genera una notificación de escritorio (Linux notify-send, macOS osascript) nombrando la clave y el comando exacto qring approve — limitada por clave, deshabilitada con QRING_NOTIFY=off.

Canary Honeytokens

Planta credenciales falsas que se ven y leen exactamente como las reales. Cualquier cosa que las toque — un servidor MCP comprometido, un agente demasiado curioso, herramientas exfiltradas que barren el anillo — recibe el valor falso sin pistas, mientras q-ring dispara una alerta de escritorio y escribe un evento canary en la cadena de auditoría a prueba de manipulaciones.

# Plant a canary shaped like a real AWS access key
qring canary plant AWS_SECRET_ACCESS_KEY --format aws

# Other shapes: aws-secret, github, github-pat, openai, openai-project,
# anthropic, stripe, gitlab, slack, google, npm, generic
qring canary plant GHP_BACKUP_TOKEN --format github-pat

# See what's been tripped
qring canary list
qring audit --action canary

Los valores son ruido CSPRNG en la forma real de token del proveedor (un canario aws coincide con AKIA[A-Z0-9]{16}, uno anthropic con el diseño real de sk-ant-api03-…AA) — lo suficientemente plausibles para ser tomados, nunca válidos. Las alertas se limitan a una por clave cada 30 segundos; el rastro de auditoría registra cada lectura.

Que te localicen. Las notificaciones de escritorio solo ayudan cuando estás en la máquina. Registra canales de webhook y cada disparo también llega a ellos:

qring canary alert add --discord https://discord.com/api/webhooks/…
qring canary alert add --slack   https://hooks.slack.com/services/…
qring canary alert add --ntfy    https://ntfy.sh/my-canaries
qring canary alert add --url     https://example.com/canary   # generic JSON POST
qring canary alert list
qring canary alert test          # send a clearly-labelled drill

Los canales viven en ~/.config/q-ring/canary-alerts.json (modo 0600). Los envíos son de tipo "dispara y olvida", protegidos contra SSRF como los hooks, limitados junto con la alerta de escritorio, y nunca incluyen el valor falso — solo la clave, el alcance, la fuente y la etiqueta del agente que lo alcanzó.

Siembra un tripwire en CI. Planta un canario y empújalo a una plataforma de despliegue en un solo paso, para que un entorno filtrado de GitHub Actions / Vercel / Cloudflare lleve un señuelo:

qring canary plant AWS_SECRET_ACCESS_KEY --format aws-secret --push github --repo you/your-app

Advertencia honesta: q-ring solo ve las lecturas que pasan por q-ring. Un valor filtrado usado directamente en el lado de la plataforma no es observable aquí — combínalo con el sistema de alertas del propio proveedor si necesitas eso.

Los canarios están diseñados para permanecer encubiertos: no llevan una descripción identificativa (añade una historia de portada inocua con --description si lo deseas), su bandera nunca aparece en las respuestas de las herramientas MCP, y los registros de activación solo son visibles desde la terminal del operador — nunca para los agentes a través de las herramientas de auditoría MCP. Las operaciones masivas de export y delete los activan igual que las lecturas, así que barrer el anillo o eliminar el tripwire hacen sonar la campana. ¿Terminaste con uno? qring canary disarm <key> lo convierte de nuevo en un secreto ordinario (qring set sobre un canario te advierte primero — la bandera sobrevive deliberadamente a las sobrescrituras para que un agente no pueda lavarlo).

MCP Airlock

Ejecuta un servidor MCP de terceros detrás de q-ring. La esclusa se sitúa entre tu host de agente y el servidor envuelto, lo inicia con un entorno depurado (sin claves API heredadas — vuelve a optar por ellas con --inherit-env), registra cada llamada a herramienta, lectura de recurso y recuperación de prompt que lo cruza como un evento wrap en la cadena de auditoría (agrupado por sesión y etiquetado con la identidad del cliente que llama), elimina los valores de secretos conocidos de cada resultado antes de que llegue a la transcripción, y aplica las reglas policy.wrap del proyecto. Los argumentos de herramientas y prompts nunca se registran — pueden contener secretos.

{
  "mcpServers": {
    "some-server": {
      "command": "qring",
      "args": ["mcp", "wrap", "--", "npx", "-y", "some-mcp-server"]
    }
  }
}

Las herramientas, recursos y prompts pasan todos textualmente (paginación, notificaciones de progreso, cancelación, suscripciones y las notificaciones list_changed / updated incluidas); la esclusa anuncia exactamente las capacidades que tiene el servidor envuelto. Las herramientas de larga duración se rigen por el tiempo de espera del propio host, con un techo generoso de esclusa configurable mediante QRING_WRAP_TIMEOUT_MS.

# Wrap a remote Streamable HTTP server; the Bearer token comes from q-ring (audited read)
qring mcp wrap --url https://mcp.example.com/mcp --auth-secret EXAMPLE_MCP_TOKEN

# Keep results verbatim (default: known secret values are replaced with [QRING:REDACTED])
qring mcp wrap --no-redact -- npx -y some-mcp-server

Política de envoltura. Gobierna el servidor envuelto desde .q-ring.json — el mismo archivo, el mismo motor de cierre ante fallos:

{
  "policy": {
    "wrap": {
      "allowTools": ["github_*", "search"],
      "denyTools": ["github_delete_*"],
      "approveTools": ["github_merge_pr"],
      "rateLimit": { "maxCalls": 60, "perSeconds": 60 },
      "toolRateLimits": { "search": { "maxCalls": 5, "perSeconds": 10 } },
      "redactResults": true
    }
  }
}

Las herramientas denegadas están ocultas de tools/list y se rechazan al llamarlas con un evento de auditoría policy_deny; approveTools se rechazan hasta que las concedas:

qring mcp approve github_merge_pr --for 900 --reason "release 1.4"
qring mcp approvals
qring mcp approve github_merge_pr --revoke

Sé claro sobre lo que es la esclusa: depuración de entorno, un registro a prueba de manipulaciones de cada cruce, política en el límite de herramientas y redacción de mejor esfuerzo de los valores de secretos que el anillo conoce. No es un sandbox — el proceso envuelto sigue ejecutándose como tu usuario con acceso normal al sistema de archivos, red y llavero del SO, y las descripciones de herramientas pasan sin inspección. Consulta docs/threat-model.md para ver la imagen honesta de los límites.

Aprovisionamiento Just-In-Time (JIT)

En lugar de almacenar credenciales estáticas, configura q-ring para generar dinámicamente tokens de corta duración sobre la marcha cuando se soliciten (por ejemplo, AWS STS, endpoints HTTP genéricos).

# Store the STS role configuration
qring set AWS_TEMP_KEYS '{"roleArn":"arn:aws:iam::123:role/AgentRole", "durationSeconds":3600}' --jit-provider aws-sts

# Resolving the secret automatically assumes the role and caches the temporary token
qring get AWS_TEMP_KEYS

Contexto de Proyecto para Agentes de IA

Una visión general segura y redactada de los secretos, configuración y estado del proyecto. Diseñada para alimentar el prompt del sistema de un agente de IA sin exponer nunca los valores de los secretos.

# Human-readable summary
qring context

# JSON output (for MCP / programmatic use)
qring context --json

Linter Consciente de Secretos

Escanea archivos específicos en busca de secretos codificados con corrección automática opcional. Cuando se usa --fix, los secretos detectados se reemplazan con referencias process.env.KEY y se almacenan en q-ring.

# Lint files for hardcoded secrets
qring lint src/config.ts src/db.ts

# Auto-fix: replace hardcoded values and store in q-ring
qring lint src/config.ts --fix

# Scan entire directory with auto-fix
qring scan . --fix

Memoria del Agente

Almacén de clave-valor cifrado y persistente que sobrevive entre sesiones de agentes de IA. Útil para recordar historial de rotación, decisiones de proyecto o contexto.

# Store a memory
qring remember last_rotation "Rotated STRIPE_KEY on 2026-03-21"

# Retrieve it
qring recall last_rotation

# List all memories
qring recall

# Forget
qring forget last_rotation

Escaneo de Secretos Pre-Commit

Instala un hook de git pre-commit que bloquea automáticamente los commits que contengan secretos codificados.

# Install the hook
qring hook:install

# Uninstall
qring hook:uninstall

Analítica de Secretos

Analiza patrones de uso y obtén sugerencias de optimización para tus secretos.

qring analyze

La salida incluye los secretos más accedidos, secretos no utilizados/obsoletos, sugerencias de optimización de alcance y recomendaciones de rotación.

Asistente de Configuración de Servicios

Configura rápidamente una nueva integración de servicio con secretos, entradas de manifiesto y hooks en un solo comando.

# Create secrets for a new Stripe integration
qring wizard stripe --keys STRIPE_KEY,STRIPE_SECRET --provider stripe --tags payment

# With a hook to restart the app on change
qring wizard myservice --hook-exec "pm2 restart app"

Política de Gobernanza

Define reglas de gobernanza a nivel de proyecto en .q-ring.json para controlar qué herramientas MCP se pueden usar, qué claves son accesibles, qué comandos se pueden ejecutar y qué puede hacer un servidor MCP envuelto detrás de la esclusa. La política se aplica a nivel de servidor MCP, llavero y esclusa.

A través de MCP, la política se resuelve desde el directorio en el que se lanzó el servidor — no desde el projectPath que pasa un llamador — para que un agente no pueda eludir las restricciones apuntando a un directorio sin política. Lanza el servidor MCP desde la raíz de tu proyecto (donde vive .q-ring.json). Las ediciones a .q-ring.json se recogen automáticamente (la caché de política se invalida al cambiar el archivo), así que no necesitas reiniciar el servidor.

Los archivos de política se validan contra el esquema y cierran ante fallos: un objeto policy inválido (por ejemplo, un error tipográfico como denytools) genera un PolicyConfigError en lugar de ignorarse silenciosamente, para que una regla malformada nunca pueda ampliar el acceso.

# View the active policy
qring policy

# JSON output
qring policy --json

Ejemplo de política en .q-ring.json:

{
  "policy": {
    "mcp": {
      "denyTools": ["delete_secret"],
      "deniedKeys": ["PROD_DB_PASSWORD"],
      "deniedTags": ["production"]
    },
    "exec": {
      "denyCommands": ["curl", "wget", "ssh"],
      "maxRuntimeSeconds": 30
    },
    "secrets": {
      "requireApprovalForTags": ["production"],
      "maxTtlSeconds": 86400
    },
    "wrap": {
      "denyTools": ["*_delete_*"],
      "approveTools": ["deploy_*"],
      "rateLimit": { "maxCalls": 60, "perSeconds": 60 }
    }
  }
}

Perfiles de Ejecución

Restringe la ejecución de comandos con perfiles nombrados que controlan los comandos permitidos, el acceso a red, los tiempos de espera y la sanitización del entorno.

# Run with the "restricted" profile (blocks network tools and interpreters/shells; 30s timeout)
qring exec --profile restricted -- npm test

# Run with the "ci" profile (5min timeout, allows network)
qring exec --profile ci -- npm run deploy

# Default: unrestricted
qring exec -- echo "hello"

Perfiles integrados: unrestricted, restricted (deniega herramientas de red y intérpretes/shells — python -c, node -e, bash y similares no pueden exfiltrar secretos inyectados; límite de 30s), ci (límite de 5min, bloquea comandos destructivos).

Auditoría a Prueba de Manipulaciones

Cada evento de auditoría incluye un hash SHA-256 del evento anterior, creando una cadena a prueba de manipulaciones. Desde v0.14 la cadena también está anclada con un HMAC con clave almacenado en el llavero del SO, por lo que qring audit:verify detecta truncamiento y reescrituras completas de archivos — no solo ediciones en el lugar. Verifica la integridad y exporta registros en múltiples formatos. Los eventos de sesiones MCP también llevan la identidad autoinformada del cliente conectado (clientInfo nombre@versión) — mostrada en la salida de qring audit y filtrable con qring audit --agent <label>. Es una etiqueta de auditoría para "qué agente hizo esto", nunca un límite de autorización, ya que los clientes eligen qué informar.

# Verify the entire audit chain
qring audit:verify

# Export as JSON
qring audit:export --format json --since 2026-03-01

# Export as CSV
qring audit:export --format csv --output audit-report.csv

Línea de Tiempo de Sesiones de Agente

Cada sesión MCP lleva la identidad del cliente (clientInfo nombre@versión) y cada sesión de esclusa un id de correlación. audit:sessions pliega el feed de auditoría plano de nuevo en una línea de tiempo por proceso de agente, así que "¿qué hizo Cursor en esa sesión?" es un comando en lugar de un grep.

# One block per session: agent, source, window, event + denial counts, keys touched
qring audit:sessions

# Narrow to one client, widen the window, print every event line
qring audit:sessions --agent "Cursor@1.2.3" --since 7d --verbose

# Machine-readable
qring audit:sessions --json

Las sesiones de esclusa (qring mcp wrap) aparecen como airlock: <wrapped command> con cada llamada proxy en orden. El panel de estado (qring status) renderiza los mismos datos como una tarjeta expandible de Sesiones de Agente (24h).

Los agentes también pueden ver su propio historial — como recursos MCP, no herramientas: qring://sessions lista resúmenes de sesión y qring://sessions/{id} devuelve una línea de tiempo (solo nombres de claves y acciones, nunca valores). Dos garantías se mantienen en el lado del agente: los disparos de canarios se eliminan antes de resumir cualquier cosa, para que un honeytoken nunca pueda descubrirse desde una vista de sesión, y denegar la herramienta audit_log en la política .q-ring.json oculta también los recursos — un interruptor controla la visibilidad de auditoría para los agentes.

Backend de Archivos Cifrado (Headless / CI)

Los hosts sin llavero del SO en absoluto (Linux headless, contenedores, CI) pueden optar por un almacén de archivos cifrado. Todo — secretos, el ancla de auditoría, la clave de memoria del agente — pasa a través de él.

export QRING_BACKEND=file
export QRING_FILE_PASSPHRASE="a strong passphrase"   # required — no passphrase, no access
qring set CI_TOKEN

El almacén es AES-256-GCM en ~/.config/q-ring/file-backend.enc (modo 0600, anulación de ruta mediante QRING_FILE_BACKEND_PATH), con clave derivada por PBKDF2 de la frase de contraseña. Es solo explícito: un llavero del SO ausente nunca recurre a él silenciosamente, y sin la frase de contraseña cada operación cierra ante fallos — q-ring nunca cifra bajo una clave derivable por máquina.

Alcances de Equipo y Organización

Extiende más allá de los alcances global y project con los alcances team y org para secretos compartidos entre grupos. Orden de resolución: proyecto → equipo → organización → global (el más específico gana).

# Store a secret in team scope
qring set SHARED_API_KEY "sk-..." --team my-team

# Store in org scope
qring set ORG_LICENSE "lic-..." --org acme-corp

# Resolution cascades: project > team > org > global
qring get API_KEY --team my-team --org acme-corp

Rotación Nativa del Emisor

Intenta la rotación de secretos nativa del proveedor (para proveedores que la soporten) o recurre a la generación local.

# Rotate via the detected provider
qring rotate STRIPE_KEY

# Force a specific provider
qring rotate API_KEY --provider openai

Validación de Secretos en CI

Valida en lote todos los secretos contra sus proveedores en un modo amigable para CI. Devuelve un informe estructurado de aprobado/fallido con código de salida 1 en caso de fallo.

# Validate all secrets (CI mode)
qring ci:validate

# JSON output for pipeline parsing
qring ci:validate --json

Modo Agente — Monitoreo Autónomo

Un daemon en segundo plano que monitorea continuamente la salud de los secretos, detecta anomalías y, opcionalmente, rota automáticamente los secretos caducados.

# Start the agent
qring agent --interval 60 --verbose

# With auto-rotation of expired secrets
qring agent --auto-rotate

# Single scan (for CI/cron)
qring agent --once

Panel de Estado Cuántico — Monitoreo en Vivo

Lanza un panel en tiempo real en tu navegador que convierte todo el subsistema cuántico en una página visualizable de un vistazo. Es una única página HTML autocontenida servida localmente — sin nube, sin configuración, totalmente offline — construida como una aplicación Preact + htm (runtime empaquetado e incrustado). Transmite actualizaciones cada 5 segundos mediante Server-Sent Events y hace diff del DOM en el lugar, para que los datos se refresquen sin volver a ejecutar animaciones de entrada y tu entrada de búsqueda, cursor y posición de desplazamiento se conserven entre ticks.

Lo que obtienes:

Franja de KPIs — total de secretos, entorno detectado, recuento protegido, aprobaciones activas, hooks, lecturas de 24 horas y recuento de anomalías en vivo.
Resumen de salud — gráfico de donut de secretos saludables / obsoletos / caducados / sin decaimiento más recuentos por alcance (global / proyecto / equipo / organización).
Entorno — detalles del colapso de la función de onda: entorno detectado, fuente, rama y cualquier contexto de proyecto.
Manifiesto — resumen de .q-ring.json con claves declaradas / requeridas / faltantes / caducadas / obsoletas.
Política — vista de un vistazo de las políticas MCP, de ejecución y de secretos (permitir/denegar herramientas, denegar claves/etiquetas, permitir/denegar comandos, requisitos de aprobación y rotación).
Tabla de secretos — vista buscable y ordenable de cada secreto (clave, alcance, entorno, tipo, decaimiento, etiquetas, última lectura), con chips rápidos para los filtros expired, stale y protected. Pulsa / para enfocar el cuadro de búsqueda.
Tarjetas cuánticas — temporizadores de decaimiento, estados de superposición, pares de entrelazamiento y túneles cuánticos activos.
Aprobaciones y hooks — lista en vivo de concesiones de aprobación válidas (y manipuladas) y cada hook registrado con su resumen de coincidencia.
Sesiones de agente (24h) — una fila expandible por cliente MCP o sesión de esclusa: etiqueta de agente, fuente, ventana, recuentos de eventos y denegaciones, eventos recientes.
Memoria del agente — recuento de claves de memoria cifradas persistidas en ~/.config/q-ring/agent-memory.enc.
Alertas de anomalías — lecturas en ráfaga, acceso fuera de horario, cadena de auditoría manipulada y otros patrones sospechosos.
Registro de auditoría (24h) — feed filtrable con chips de acción (read/write/delete/export), chips de fuente (cli/mcp/hook/agent) y un filtro de texto libre.

Los controles de la barra superior te permiten pausar las actualizaciones SSE (útil mientras lees el feed de auditoría), refrescar bajo demanda o saltar a la instantánea JSON cruda en /api/status. Atajos de teclado: / enfocar búsqueda de secretos · P pausar · R refrescar. El panel se vincula solo a 127.0.0.1 y nunca expone valores secretos, pero sí muestra nombres de claves, el registro de auditoría y las concesiones de aprobación, por lo que cada ruta está protegida por un token aleatorio generado por lanzamiento. qring status imprime (y abre) la URL completa, incluido ?token=…; las solicitudes sin el token reciben un 403. Detén el servidor para invalidar el token.

# Open the dashboard (auto-launches your browser at http://127.0.0.1:9876/?token=…)
qring status

# Specify a custom port
qring status --port 4200

# Don't auto-open the browser (copy the printed tokenized URL yourself)
qring status --no-open

Servidor MCP

q-ring incluye un servidor MCP completo con 46 herramientas para la integración de agentes de IA.

Herramientas principales

Herramienta	Descripción
`get_secret`	Lee un valor secreto (colapsa la superposición, audita la lectura)
`list_secrets`	Lista claves + metadatos en el ámbito (los valores nunca se exponen); filtra por etiqueta, caducidad, glob
`set_secret`	Crea o sobrescribe un único secreto con TTL opcional, estado por entorno, etiquetas, formato de rotación
`promote_secret`	Copia el valor de un secreto de un estado de entorno a otro (sin operación si son iguales; `force` para sobrescribir un destino diferente)
`diff_environments`	Compara dos entornos clave por clave: igual / diferente / solo-a / solo-b / colapsado; solo estados, nunca valores
`delete_secret`	Elimina permanentemente un valor secreto (no se puede deshacer desde q-ring)
`has_secret`	Verificación booleana de existencia que respeta la decadencia (sin lectura de auditoría)
`export_secrets`	Renderiza múltiples secretos como `.env` o JSON para exportación puntual (omite claves protegidas por aprobación sin concesión)
`import_dotenv`	Analiza texto `.env` y almacena en bloque cada par clave/valor (acepta solo contenido sin procesar; nunca lee archivos)
`check_project`	Compara el manifiesto `.q-ring.json` contra el llavero para detectar claves faltantes, caducadas u obsoletas
`env_generate`	Renderiza un cuerpo `.env` completo desde el manifiesto del proyecto, con advertencias para vacíos

Herramientas cuánticas

Herramienta	Descripción
`inspect_secret`	Muestra metadatos de una clave (estados, decadencia, entrelazamiento, contador de accesos) sin revelar el valor
`detect_environment`	Resuelve qué slug de entorno debe impulsar el colapso de superposición para el contexto actual
`generate_secret`	Genera un valor respaldado por CSPRNG en un formato elegido y opcionalmente lo almacena
`entangle_secrets`	Vincula dos claves para que futuras escrituras/rotaciones propaguen el mismo valor
`disentangle_secrets`	Rompe el enlace de sincronización entre dos claves (no elimina valores)

Herramientas de tunelización

Herramienta	Descripción
`tunnel_create`	Guarda un valor en la memoria del proceso y devuelve un ID opaco (nunca toca el disco)
`tunnel_read`	Recupera un valor tunelizado por ID: puede autodestruirse al leerlo
`tunnel_list`	Enumera túneles activos con presupuesto de lectura restante y TTL (solo IDs)
`tunnel_destroy`	Elimina inmediatamente un túnel de la memoria antes de que se agoten su TTL/lecturas

Herramientas de teletransportación

Herramienta	Descripción
`teleport_pack`	Cifra secretos seleccionados en un paquete AES-256-GCM protegido por contraseña
`teleport_unpack`	Descifra un paquete de teletransportación e importa cada secreto (con ejecución simulada opcional)

Herramientas de validación

Herramienta	Descripción
`validate_secret`	Consulta el servicio upstream (OpenAI/Stripe/GitHub/AWS/HTTP) para confirmar que una clave sigue activa
`list_providers`	Enumera los proveedores de validación integrados y sus prefijos de autodetección

Herramientas de hooks

Herramienta	Descripción
`register_hook`	Registra un efecto secundario de shell/HTTP/señal que se activa al escribir/eliminar/rotar
`list_hooks`	Muestra cada hook registrado con criterios de coincidencia, tipo y bandera de habilitación
`remove_hook`	Desconecta un solo hook por ID sin tocar ningún secreto

Herramientas de ejecución y escaneo

Herramienta	Descripción
`exec_with_secrets`	Ejecuta un comando hijo con secretos inyectados como variables de entorno y cualquier valor filtrado redactado de la salida
`scan_codebase_for_secrets`	Recorre un árbol de directorios y marca secretos codificados mediante regex + heurísticas de entropía
`lint_files`	Inspecciona una lista específica de archivos en busca de secretos codificados con corrección automática opcional a `process.env.KEY`

Herramientas para agentes de IA

Herramienta	Descripción
`get_project_context`	Instantánea única redactada de secretos, entorno, manifiesto, hooks y actividad de auditoría reciente
`agent_remember`	Persiste una nota no secreta en la memoria cifrada del agente entre sesiones
`agent_recall`	Lee un valor de memoria, o lista cada clave almacenada cuando no se proporciona ninguna
`agent_forget`	Elimina permanentemente una clave de la memoria del agente
`analyze_secrets`	Perfil de uso: más accedidas, obsoletas, nunca accedidas, candidatas sin rotación

Herramientas de observador y salud

Herramienta	Descripción
`audit_log`	Consulta el registro de auditoría a prueba de manipulaciones filtrado por clave, acción y límite
`detect_anomalies`	Superficie de hallazgos de lecturas ráfaga y fuera de horario del historial de auditoría
`verify_audit_chain`	Recalcula la cadena de hash de auditoría e informa el primer punto de ruptura si se manipuló
`export_audit`	Exporta eventos de auditoría como jsonl, json o csv para archivado/SIEM
`health_check`	Barrido de ámbito de solo lectura: recuentos de decadencia/obsoletos/caducados más anomalías actuales
`status_dashboard`	Inicia un panel SSE local con KPI en vivo, secretos, hooks y feed de auditoría (devuelve una URL `127.0.0.1` protegida por token)
`agent_scan`	Pase de salud multiproyecto con `autoRotate` opcional para secretos caducados

Herramientas de gobernanza y políticas

Herramienta	Descripción
`check_policy`	Ejecución simulada de una acción de herramienta/clave/ejecución contra la política `.q-ring.json` sin realizarla
`get_policy_summary`	Resumen de alto nivel de los recuentos de reglas de política y requisitos de aprobación/rotación
`rotate_secret`	Solicita al proveedor upstream que emita una nueva credencial y la almacene de nuevo en el llavero
`ci_validate_secrets`	Valida en lote cada secreto accesible en el ámbito y devuelve un informe estructurado de aprobado/fallido

Configuración de Cursor / Kiro

Agrega a .cursor/mcp.json o .kiro/settings/mcp.json (o deja que qring setup cursor / qring setup kiro lo escriba):

Si q-ring está instalado globalmente (p. ej., pnpm add -g @i4ctime/q-ring):

{
  "mcpServers": {
    "q-ring": {
      "command": "qring-mcp"
    }
  }
}

Si se usa un clon local:

{
  "mcpServers": {
    "q-ring": {
      "command": "node",
      "args": ["/path/to/q-ring/dist/mcp.js"]
    }
  }
}

Configuración de Claude Code

Agrega a .mcp.json en la raíz del proyecto — o ejecuta qring setup claude, o claude mcp add q-ring -- qring-mcp (Claude Desktop es la aplicación que usa claude_desktop_config.json, no Claude Code):

Instalación global:

{
  "mcpServers": {
    "q-ring": {
      "command": "qring-mcp"
    }
  }
}

Clon local:

{
  "mcpServers": {
    "q-ring": {
      "command": "node",
      "args": ["/path/to/q-ring/dist/mcp.js"]
    }
  }
}

Configuración de VS Code

VS Code habla MCP de forma nativa: agrega a .vscode/mcp.json (nota la clave servers, no mcpServers):

{
  "servers": {
    "q-ring": {
      "command": "qring-mcp"
    }
  }
}

qring setup aún no escribe este archivo: VS Code es solo configuración (sin paquete de plugin de primera parte).

Plugins de editor

El repositorio de q-ring incluye tres paquetes de editor de primera parte: cada uno agrega reglas/orientación, agentes, comandos, habilidades, hooks y el conector MCP a su editor anfitrión.

Plugin	Editor	Destacados
`cursor-plugin/`	Cursor	3 reglas, 5 habilidades, 2 agentes, 8 comandos de barra, 3 hooks, autoconexión MCP
`kiro-plugin/`	Kiro	Diseño oficial Power: `POWER.md`, raíz `mcp.json`, `steering/`, `hooks/`; o aplana con `plugin:sync:kiro`
`claude-code-plugin/`	Claude Code	Memoria `CLAUDE.md`, `.mcp.json` del proyecto, 2 subagentes, 8 comandos de barra, 6 habilidades, 3 scripts de hook

Plugin de Cursor

El plugin de q-ring para Cursor lleva la gestión cuántica de secretos directamente a tu IDE con reglas, habilidades, agentes, comandos, hooks y un conector MCP integrado.

Componente	Qué hace
3 reglas	Orientación siempre activa: nunca codificar secretos, usar q-ring para todas las operaciones, advertir sobre archivos `.env`
5 habilidades	Activadas automáticamente por contexto: gestión de secretos, escaneo, rotación, incorporación de proyectos, ejecución con secretos
2 agentes	`security-auditor` (monitoreo proactivo) y `secret-ops` (asistente diario)
8 comandos	`/qring:scan-secrets`, `/qring:health-check`, `/qring:rotate-expired`, `/qring:setup-project`, `/qring:teleport-secrets`, `/qring:dashboard`, `/qring:exec-safe`, `/qring:analyze`
3 hooks	`afterFileEdit` (escaneo de lint), `sessionStart` (contexto del proyecto), `beforeShellExecution` (guardia `.env`)
Conector MCP	Se autoconecta a `qring-mcp` vía stdio: las 46 herramientas disponibles

Instala desde el marketplace de Cursor o consulta cursor-plugin/README.md para configuración manual.

Plugin de Kiro (Power)

El directorio kiro-plugin/ es un Kiro Power según Crear powers: POWER.md (metadatos, incorporación, mapa de orientación), raíz mcp.json (el servidor MCP debe coincidir con el nombre del servidor referenciado en el power) y steering/ para flujos de trabajo. Instala desde Kiro → Powers → Agregar power desde ruta local y selecciona kiro-plugin, o publica la carpeta en GitHub y usa Agregar power desde GitHub.

La orientación siempre activa bloquea secretos codificados y enruta todo a través de q-ring; los archivos de orientación manual actúan como personas de agente (#qring-secret-ops, #qring-security-auditor), paquetes de habilidades y comandos estilo barra (#qring-cmd-scan-secrets, etc.). Los hooks opcionales viven en hooks/ para copiarlos a .kiro/hooks/.

# Alternative: flatten into ~/.kiro (settings + steering + hooks)
pnpm run plugin:sync:kiro

# Or scope to a single project
pnpm run plugin:sync:kiro -- /path/to/your/project/.kiro

Consulta kiro-plugin/README.md para el desglose completo.

Plugin de Claude Code

Para Claude Code, q-ring incluye un archivo de memoria CLAUDE.md, un .mcp.json con ámbito de proyecto, dos subagentes (secret-ops, security-auditor), ocho comandos de barra (/qring-scan-secrets, /qring-health-check, …), seis habilidades y tres hooks (recordatorio de lint posterior a edición, guardia .env previa a Bash, introducción de contexto al inicio de sesión).

# Install into the current project ($PWD)
pnpm run plugin:sync:claude

# Install agents/commands/skills/hooks at user scope (~/.claude)
pnpm run plugin:sync:claude -- --user

# Or target a specific project
pnpm run plugin:sync:claude -- /path/to/your/project

Los archivos existentes CLAUDE.md, .mcp.json o .claude/settings.json nunca se sobrescriben silenciosamente: el script escribe un <filename>.qring-template junto a ellos para que puedas fusionarlos manualmente. Pasa --force para sobrescribir.

Consulta claude-code-plugin/README.md para el desglose completo.

Arquitectura

qring CLI ─────┐
               ├──▶ Core Engine ──▶ @napi-rs/keyring ──▶ OS Keyring
MCP Server ────┘       │
                       ├── Envelope (quantum metadata)
                       ├── Scope Resolver (global / project / team / org)
                       ├── Collapse (env detection + branchMap globs)
                       ├── Observer (tamper-evident audit chain)
                       ├── Policy (governance-as-code engine)
                       ├── Noise (secret generation)
                       ├── Entanglement (cross-secret linking)
                       ├── Validate (provider-based liveness + rotation)
                       ├── Hooks (shell/HTTP/signal callbacks)
                       ├── Import (.env file ingestion)
                       ├── Exec (profile-restricted injection + redaction)
                       ├── Scan (codebase entropy heuristics)
                       ├── Provision (JIT ephemeral credentials)
                       ├── Approval (HMAC-verified zero-trust tokens)
                       ├── Context (safe redacted project view)
                       ├── Linter (secret-aware code scanning)
                       ├── Memory (encrypted agent persistence)
                       ├── Tunnel (ephemeral in-memory)
                       ├── Teleport (encrypted sharing)
                       ├── Agent (autonomous monitor + rotation)
                       └── Dashboard (live status via SSE)

Configuración del proyecto (`.q-ring.json`)

Configuración opcional por proyecto:

{
  "env": "dev",
  "defaultEnv": "dev",
  "branchMap": {
    "main": "prod",
    "develop": "dev",
    "staging": "staging",
    "release/*": "staging",
    "feature/*": "dev"
  },
  "secrets": {
    "OPENAI_API_KEY": { "required": true, "description": "OpenAI API key", "format": "api-key", "prefix": "sk-", "provider": "openai" },
    "DATABASE_URL": { "required": true, "description": "Postgres connection string", "validationUrl": "https://api.example.com/health" },
    "SENTRY_DSN": { "required": false, "description": "Sentry error tracking" }
  },
  "policy": {
    "mcp": {
      "denyTools": ["delete_secret"],
      "deniedKeys": ["PROD_DB_PASSWORD"],
      "deniedTags": ["production"]
    },
    "exec": {
      "denyCommands": ["curl", "wget"],
      "maxRuntimeSeconds": 60
    }
  }
}

branchMap admite patrones glob con comodines * (p. ej., release/* coincide con release/v1.0)
secrets declara los secretos requeridos del proyecto: usa qring check para validar, qring env:generate para producir un archivo .env
provider asocia un proveedor de validación de actividad con un secreto (p. ej., "openai", "stripe", "github"): usa qring validate para probar
validationUrl configura el endpoint del proveedor HTTP genérico para validación personalizada
policy define reglas de gobernanza para el control de herramientas MCP, restricciones de acceso a claves, listas de permitidos de ejecución y requisitos del ciclo de vida de secretos

📚 Documentación

Inicio rápido: Claude Code · Cursor · Kiro
Solución de problemas — backends de llavero, conexión MCP, puerta de aprobación, fijación de políticas
Paridad CLI ↔ MCP — cada comando mapeado a su herramienta MCP
Publicación de versiones — flujo de publicación impulsado por etiquetas

Contribuciones

Consulta CONTRIBUTING.md para la guía completa (entorno de desarrollo, convenciones, archivos a mantener sincronizados). La versión corta:

Ejecuta pnpm run lint, pnpm run typecheck y pnpm run test:ci antes de abrir un PR.
Las pruebas o sandboxes pueden dirigir el registro de auditoría a otra ubicación con QRING_AUDIT_DIR (el directorio se crea si no existe); el valor predeterminado es ~/.config/q-ring/audit.jsonl.
Pre-commit local opcional: qring hook:install (usa el hook precommit de este paquete cuando qring esté en tu PATH).
Después de cambiar uno de los plugins de editor:
- Cursor: pnpm run plugin:sync copia cursor-plugin/ a ~/.cursor/plugins/local/my-plugin (o pasa una ruta personalizada).
- Kiro: pnpm run plugin:sync:kiro copia kiro-plugin/mcp.json → ~/.kiro/settings/mcp.json, además de steering/ y hooks/ (o pasa una ruta de .kiro del proyecto). Prefiere agregar kiro-plugin/ como un Power desde el panel de Powers.
- Claude Code: pnpm run plugin:sync:claude copia claude-code-plugin/ en el directorio actual (o pasa una ruta de proyecto; agrega --user para instalar en ~/.claude/).
Consulta también docs/cli-mcp-parity.md.

🔒 Seguridad

Local primero. El almacenamiento principal es el llavero de tu sistema operativo: no hay nube q-ring ni cuenta. La superficie MCP, el registro de auditoría y la memoria del agente viven en tu máquina (los archivos de auditoría y memoria se escriben solo para el propietario, 0600).
Modelo de amenazas documentado. Qué protege q-ring, qué no protege y dónde reside el riesgo residual, incluida una respuesta honesta a la pregunta de exfiltración por agentes, en docs/threat-model.md.
Endurecido mediante revisión adversarial. v0.14.0 incluyó los resultados de una auditoría adversarial interna: hallazgos de omisión de políticas, alcance de aprobaciones y perfiles de ejecución, todos corregidos con pruebas de regresión. Los detalles están en las secciones Security del CHANGELOG (estilo de la casa desde 0.12.0: primero corregir, luego divulgar allí).
Reportar una vulnerabilidad. Usa el reporte privado de vulnerabilidades de GitHub; consulta SECURITY.md para la tabla de versiones compatibles y los compromisos de respuesta (acuse en 48 horas, evaluación en 7 días).

📜 Licencia

AGPL-3.0: libre de usar, modificar y compartir. Cualquier trabajo derivado o servicio alojado debe publicar su código fuente bajo la misma licencia.

q-ring

Documentación

q-ring

¿Por qué q-ring?

🚀 Instalación

Docker (servidor MCP)

⚡ Inicio Rápido

Funciones Cuánticas

Superposición — Una Clave, Múltiples Entornos

Promoción de Entornos — Compara, Luego Promueve

Colapso de la Función de Onda — Detección Inteligente de Entorno

Decaimiento Cuántico — Secretos con TTL

Efecto Observador — Audita Todo

Ruido Cuántico — Generación de Secretos

Entrelazamiento — Secretos Vinculados

Efecto Túnel — Secretos Efímeros

Teletransportación — Compartición Cifrada

Importación — Ingesta Masiva de Secretos

Exportación Selectiva

Búsqueda y Filtrado de Secretos

Manifiesto de Secretos del Proyecto

Sincronización de Archivos Env

Referencias de Secretos y Ejecución con Privilegios Mínimos

Configuración del Editor

Envío a Plataformas de Despliegue

Validación de Vitalidad de Secretos

Hooks — Devoluciones de Llamada en Cambio de Secretos

Rotación Configurable

Ejecución Segura y Redacción Automática

Escáner de Secretos en el Código

Secretos Compuestos / con Plantillas

Aprobaciones de Usuario (Agente de Confianza Cero)

Canary Honeytokens

MCP Airlock

Aprovisionamiento Just-In-Time (JIT)

Contexto de Proyecto para Agentes de IA

Linter Consciente de Secretos

Memoria del Agente

Escaneo de Secretos Pre-Commit

Analítica de Secretos

Asistente de Configuración de Servicios

Política de Gobernanza

Perfiles de Ejecución

Auditoría a Prueba de Manipulaciones

Línea de Tiempo de Sesiones de Agente

Backend de Archivos Cifrado (Headless / CI)

Alcances de Equipo y Organización

Rotación Nativa del Emisor

Validación de Secretos en CI

Modo Agente — Monitoreo Autónomo

Panel de Estado Cuántico — Monitoreo en Vivo

Servidor MCP

Herramientas principales

Herramientas cuánticas

Herramientas de tunelización

Herramientas de teletransportación

Herramientas de validación

Herramientas de hooks

Herramientas de ejecución y escaneo

Herramientas para agentes de IA

Herramientas de observador y salud

Herramientas de gobernanza y políticas

Configuración de Cursor / Kiro

Configuración de Claude Code

Configuración de VS Code

Plugins de editor

Plugin de Cursor

Plugin de Kiro (Power)

Plugin de Claude Code

Arquitectura

Configuración del proyecto (.q-ring.json)

📚 Documentación

Contribuciones

🔒 Seguridad

📜 Licencia

Configuración del proyecto (`.q-ring.json`)