keywarden

Tu agente de IA puede usar tus claves de API. Nunca puede leerlas.

keywarden es un almacén de credenciales local y cifrado que habla MCP. Claude Code, Claude Desktop, Cursor o cualquier cliente MCP se conecta a él y obtiene dos capacidades: hacer una llamada API autenticada y ejecutar un comando con credenciales en su entorno. Ninguna de las dos pone la credencial en sí en el contexto del modelo.

No existe una herramienta get_secret. Esa ausencia es todo el producto.

   agent                keywarden                    upstream
     |                     |                          |
     |  "POST /v1/chat     |                          |
     |   using openai/prod"|                          |
     |-------------------->|                          |
     |                     | check policy             |
     |                     | decrypt key              |
     |                     | attach Authorization     |
     |                     |------------------------->|
     |                     |<-------------------------|
     |  response only      | scrub any key from body  |
     |<--------------------| append to audit log      |

Por qué

Ahora mismo, la forma normal de permitir que un agente use tu clave de OpenAI es poner la clave en un archivo .env y dejar que el agente la lea. En el momento en que lo hace, la clave está en la ventana de contexto de un modelo. Desde ahí está en los registros de un proveedor, posiblemente en un conjunto de entrenamiento, posiblemente en un informe de fallo, y definitivamente en tu propio historial de transcripciones que pegarás en un informe de error dentro de seis meses.

Rotar una clave es molesto. No saber si se ha filtrado es peor.

keywarden elimina el paso en el que el modelo ve la clave en absoluto.

Related MCP server: AgentPay MCP Server

Instalación

npm install -g keywarden

Node 20.10 o más reciente. Dos dependencias de ejecución: el SDK de MCP y zod. Sin módulos nativos, sin compilador, sin demonio.

Inicio rápido

keywarden init --passphrase
keywarden add openai/prod --provider openai
keywarden mcp-config

init crea ~/.keywarden/ con un almacén cifrado y una política de denegación por defecto. add solicita cada campo, para que nada termine en el historial de tu shell. mcp-config imprime el bloque para pegar en tu cliente MCP.

Luego, en Claude Code:

Llama al endpoint de modelos de OpenAI con mi clave de producción y dime a cuáles tengo acceso.

El modelo llama a http_request con ref: "openai/prod". keywarden adjunta la clave, hace la llamada, devuelve la respuesta. Pídele que imprima la clave y te dirá que no puede.

Las herramientas que obtiene un agente

Establece KEYWARDEN_DISABLE_EXEC=1 para eliminar run por completo y exponer solo el proxy HTTP.

Tres superficies, un modelo de autorización

El mismo almacén, motor de políticas, concesiones y registro de auditoría son accesibles de tres maneras. Cuál uses no cambia nada sobre lo que está permitido.

La superficie HTTP es lo que hace que keywarden sea utilizable desde código que no habla MCP, y es el primer lugar donde keywarden puede distinguir a un llamante de otro:

keywarden apikey create ci-runner --ref 'openai/**' --http --audit --ttl 30d
keywarden serve --port 8787

curl -s http://127.0.0.1:8787/v1/proxy/openai%2Fprod \
  -H "Authorization: Bearer kw_live_..." \
  -H "content-type: application/json" \
  -d '{"method":"POST","url":"/v1/chat/completions","body":{"model":"gpt-4o","messages":[]}}'

El llamante tiene una clave de keywarden con alcance a openai/**, que lleva solo las capacidades que se le otorgaron, expira en 30 días y es revocable con un comando. Nunca tiene la clave de OpenAI. Rutas: /v1/secrets, /v1/secrets/:ref, /v1/proxy/:ref, /v1/run, /v1/audit, /v1/usage, /v1/whoami, /healthz.

El servidor se vincula a 127.0.0.1 y rechaza una interfaz enrutable sin --allow-remote, porque cualquiera que pueda alcanzar ese puerto obtiene un oráculo de autorización para cada credencial que cubre la clave.

Quién usó qué, y cuánto costó

Cada entrada en el registro de auditoría nombra a un actor, y el actor está dentro del hash, por lo que la atribución no puede reescribirse sin romper la cadena. Cada respuesta proxy se analiza para obtener los recuentos de tokens reportados por el proveedor.

keywarden usage --since 7d

CREDENTIAL        CALLS          IN         OUT       TOTAL
openai/prod         142     418,220      96,410     514,630
anthropic/prod       38      92,004      31,887     123,891

ACTOR             CALLS          IN         OUT       TOTAL
http:ci-runner      118     356,900      74,220     431,120
mcp:mcp-client       62     153,324      54,077     207,401

keywarden registra tokens, no dinero. Los precios cambian, difieren según el contrato, y una tarifa fija obsoleta produce un número incorrecto con confianza en un informe financiero. Ten en cuenta que run no puede medirse: una vez que una credencial está dentro de un subproceso, keywarden ve un código de salida, no un recuento de tokens.

Dos formas de usar una credencial

Proxy, para APIs HTTP. El agente describe una solicitud, keywarden adjunta la credencial y hace la llamada. Funciona para OpenAI, Anthropic, Stripe, GitHub, Slack, Cloudflare, Vercel, Supabase y cualquier API que se autentique con un encabezado o un parámetro de consulta.

// what the agent sends
{ "ref": "openai/prod", "method": "POST", "url": "/v1/chat/completions", "body": { "model": "gpt-4o", "messages": [] } }

Inyección, para todo lo demás. AWS necesita firma de solicitudes SigV4, una URL de Postgres no es HTTP en absoluto, y terraform apply quiere variables de entorno reales. keywarden lanza el proceso él mismo:

{ "command": "aws", "args": ["s3", "ls"], "inject": ["aws/prod"] }

El proceso hijo obtiene AWS_ACCESS_KEY_ID y compañía. El modelo obtiene la salida estándar, con cualquier credencial que aparezca enmascarada al salir.

Política

~/.keywarden/policy.json decide qué credencial puede usarse, con qué capacidad, contra qué. Las reglas se evalúan de arriba a abajo, la primera coincidencia gana, y el valor por defecto es denegar.

{
  "version": 1,
  "default": "deny",
  "redactResponses": true,
  "rules": [
    {
      "ref": "openai/**",
      "http": { "allow": true, "methods": ["POST"], "paths": ["/v1/**"] },
      "exec": { "allow": false, "commands": [] },
      "rateLimitPerMinute": 30
    },
    {
      "ref": "aws/prod",
      "http": { "allow": false },
      "exec": { "allow": true, "commands": ["aws", "terraform"] },
      "rateLimitPerMinute": 10,
      "expiresAt": "2026-12-31T00:00:00.000Z"
    }
  ]
}

O desde la CLI:

keywarden policy allow "openai/**" --http --path "/v1/**" --method POST
keywarden policy allow aws/prod --exec aws --exec terraform --arg-deny "s3://*"
keywarden policy test aws/prod exec terraform

* coincide dentro de un segmento de ruta, ** abarca segmentos. expiresAt hace que una regla sea temporal.

Nombrar un comando no es suficiente por sí solo. Permitir aws para aws s3 ls y el mismo binario hace aws s3 cp a un bucket que pertenece a otra persona. Esa es la brecha a nivel de secuencia que la literatura de amenazas de MCP sigue señalando: cada llamada individual está autorizada, y la combinación es la exfiltración. Así que las reglas también restringen argumentos:

"exec": {
  "allow": true,
  "commands": ["aws"],
  "argsDeny": ["s3://*", "--endpoint-url"],   // any match refuses the call
  "argsAllow": ["s3", "ls", "--region", "*"]  // if set, every argument must match
}

Concesiones: acceso temporal, con expiración y límite de uso

La política es configuración permanente. Es la forma incorrecta para "deja que el agente haga esta única cosa, ahora, durante quince minutos", que hoy significa ampliar una regla y olvidar estrecharla de nuevo.

Una concesión es una capacidad que lleva sus propias restricciones, tomada de la línea de trabajo de macaroon y biscuit, y emitida por ti en una terminal:

keywarden grant aws/prod --exec aws --ttl 15m --uses 5 --arg-deny "s3://*"
keywarden grant openai/prod --http --path "/v1/chat/**" --method POST --ttl 1h --uses 20
keywarden grant list
keywarden grant revoke <id>

Las concesiones expiran solas, mueren cuando se agota su presupuesto de uso, y están protegidas con HMAC con una clave derivada de tu almacén, por lo que un grants.json editado a mano se rechaza en lugar de honrarse. Un intento denegado no consume un uso.

Establece "requireGrant": true en una regla de política y la configuración permanente se vuelve necesaria pero no suficiente: no pasa nada hasta que emitas una concesión. Ese es el paso de aprobación con un humano en el circuito, sin necesidad de un aviso interactivo dentro de un servidor stdio.

Integridad de configuración

Cifrar los secretos es la mitad del trabajo. policy.json decide si una credencial puede usarse y providers.json decide a dónde se envía. Ambos son archivos planos. Alguien que no pueda descifrar un solo byte aún puede agregar un proveedor cuyos hosts sean suyos y redirigir tu credencial hacia él.

Así que el almacén fija un hash de ambos archivos, y se niega a actuar sobre cualquiera de ellos hasta que hayas revisado el cambio:

keywarden trust show    # what drifted
keywarden trust         # review, then pin the current contents

El archivo del almacén en sí está protegido con MAC en su totalidad, no solo por campo, porque cambiar provider: "openai" a otra cosa nunca toca un texto cifrado y de otro modo se verificaría limpiamente.

Lo que keywarden realmente hace cumplir

• Sin herramienta de texto plano. La superficie MCP no tiene una ruta de código que devuelva un valor de credencial.

• Lista de permitidos de salida. Una credencial solo puede enviarse a hosts que su proveedor declara, más los que agregues en la política. Una inyección de prompt que le diga al agente que haga POST de tu clave a attacker.example falla en la verificación del host, antes de tocar la red.

• Solo HTTPS, sin seguir redirecciones. Un 302 a otro origen no reproducirá tu encabezado Authorization fuera del host.

• Protección SSRF. Loopback, rangos privados, CGNAT y link-local (que cubre el endpoint de metadatos de nube 169.254.169.254) están bloqueados, y la dirección se valida en la búsqueda DNS que el socket realmente usa, por lo que el rebinding de DNS no abre una ventana.

• Sin shell. run pasa un array argv a spawn con shell: false. No hay análisis de metacaracteres en el que inyectar.

• Entorno hijo construido. El hijo obtiene una lista de permitidos de variables heredadas más las inyectadas. Tus otros secretos, y la propia frase de contraseña de keywarden, no se heredan.

• Redacción de salida. Cada resultado de herramienta se escanea en busca de valores de credencial conocidos, sus formas base64 y codificadas en URL, y alrededor de una docena de formas de clave bien conocidas. Defensa en profundidad, no el control principal.

• Auditoría a prueba de manipulaciones. Cada decisión, permitir o denegar, se agrega a un registro encadenado por hash. keywarden audit verify recalcula la cadena e informa la primera entrada modificada o eliminada.

• Integridad de archivo completo. El almacén está protegido con MAC incluyendo sus metadatos, por lo que una credencial no puede redirigirse a otro proveedor sin detección. policy.json y providers.json están fijados por hash al almacén y se rechazan cuando cambian fuera de banda.

• Endurecimiento del entorno. El servidor se niega a iniciar cuando NODE_TLS_REJECT_UNAUTHORIZED=0, NODE_OPTIONS o SSLKEYLOGFILE están establecidos, y advierte sobre NODE_EXTRA_CA_CERTS y HTTPS_PROXY. CVE-2026-21852 contra Claude Code fue una anulación de entorno que redirigió el tráfico saliente con el encabezado Authorization adjunto; un proceso cuyo trabajo es adjuntar credenciales no debe iniciarse cuando la ruta de solicitud está bajo el control de otra persona.

• Restricciones de argumentos. argsAllow / argsDeny estrechan qué invocaciones de un comando permitido están permitidas, no solo qué binario.

• Concesiones atenuadas. Capacidades con expiración, límite de uso y emitidas por el operador, resistentes a falsificación mediante un MAC derivado del almacén.

• Enmarcado de datos no confiables. Los cuerpos de respuesta proxy se etiquetan como contenido no confiable de un host nombrado, por lo que una instrucción inyectada en una respuesta de API se presenta al modelo como datos.

Criptografía

Cifrado de sobre, todo desde node:crypto, sin bibliotecas criptográficas de terceros.

• Una clave de datos aleatoria de 256 bits cifra cada campo con AES-256-GCM, con el ref de la credencial y el nombre del campo como datos autenticados adicionales, por lo que un texto cifrado no puede moverse entre entradas del almacén.

• La clave de datos está envuelta por una clave derivada de tu frase de contraseña con scrypt a N=2^17, r=8, aproximadamente 128 MiB y aproximadamente un segundo por intento. Eso es deliberado: el archivo del almacén es lo que un atacante se lleva, por lo que adivinar sin conexión tiene que ser costoso.

• Rotar tu frase de contraseña reenvuelve 32 bytes. No vuelve a cifrar cada secreto.

Modos de almacén

--passphrase es el fuerte. El servidor MCP necesita KEYWARDEN_PASSPHRASE en su entorno para desbloquear sin un aviso.

--keyfile escribe una clave aleatoria en ~/.keywarden/masterkey para que nada tenga que solicitar. Es conveniente, y significa que cualquiera que pueda leer tu directorio de inicio puede abrir el almacén. Sigue siendo mucho mejor que archivos .env en texto plano dispersos por proyectos, porque la clave está en un solo lugar, su uso está restringido por política, y cada uso se registra. Conoce qué intercambio hiciste. keywarden doctor te lo recordará.

En Windows, los modos de archivo se establecen pero no se aplican de la manera en que POSIX aplica 0600. Consulta THREAT_MODEL.md.

CLI

keywarden init --passphrase|--keyfile   create the vault
keywarden doctor                        check the install, flag weak settings
keywarden trust [show]                  re-pin policy.json + providers.json after reviewing a change
keywarden grant <ref> ...               issue a temporary, use-capped capability
keywarden grant list | revoke <id>
keywarden add <ref> --provider <id>     store a credential (prompts for each field)
keywarden list                          metadata only
keywarden describe <ref>                metadata plus how it can be used
keywarden reveal <ref>                  print plaintext, asks first, always audited
keywarden rm <ref> [--field f]          delete
keywarden exec <ref[,ref]> -- <cmd>     run a command with credentials injected
keywarden policy show|init|allow|deny|test
keywarden audit [tail|verify]
keywarden passphrase                    rotate
keywarden providers                     built-in presets
keywarden mcp-config                    print the MCP client config
keywarden doctor                        check the install, flag weak settings

Proveedores personalizados

Cualquier cosa no integrada va en ~/.keywarden/providers.json. Consulta docs/PROVIDERS.md.

{
  "acme": {
    "label": "Acme Internal API",
    "hosts": ["api.acme.internal", "*.acme.io"],
    "baseUrl": "https://api.acme.io",
    "fields": ["token", "tenant"],
    "required": ["token"],
    "auth": { "type": "header", "name": "X-Acme-Key", "template": "{{token}}" },
    "env": { "ACME_TOKEN": "{{token}}", "ACME_TENANT": "{{tenant}}" }
  }
}

De lo que keywarden no te protege

Lee THREAT_MODEL.md antes de confiarle algo costoso. La versión corta:

• Si el agente puede ejecutar comandos locales arbitrarios a través de alguna otra herramienta, puede leer tu archivo de bóveda y, en modo keyfile, tu clave maestra. keywarden protege el contexto del modelo, no tu disco.

• run da la credencial a un proceso real. Si incluyes en la lista de permitidos un comando que pueda manipularse para exfiltrar su propio entorno, la credencial se escapa. Acota la lista de permitidos al máximo.

• El enmascarado es una red de seguridad con agujeros. Una credencial que una API devuelva recodificada en una forma que no reconozcamos no será detectada.

• keywarden no impide que un agente haga algo costoso o destructivo con una credencial que tiene un permiso legítimo para usar. Para eso sirven el alcance de las políticas y los límites de frecuencia.

Desarrollo

npm install
npm run build
npm test          # 89 unit tests + 46 end-to-end checks against the real CLI, MCP and HTTP servers

La suite e2e ejecuta los binarios reales en un KEYWARDEN_HOME desechable y comprueba, entre otras cosas, que ninguna respuesta de herramienta contiene la credencial.

Lectura

• THREAT_MODEL.md — qué está dentro del alcance y qué, honestamente, no lo está

• docs/RESEARCH.md — la literatura de 2026 en la que se basa este diseño, qué se adoptó y qué se consideró y se descartó

• docs/COMPETITORS.md — el panorama del sector, y en qué keywarden es realmente distinto y no solo se comercializa de otra manera

• docs/TEAM.md — la arquitectura para varios desarrolladores: identidad, intercambio de claves sin un servidor legible, flujo de aprobación, contabilidad de costes y orden de compilación

• docs/PROVIDERS.md — escribir un proveedor personalizado

Versión alojada

Se prevé una versión alojada para quienes quieren una bóveda de equipo, gestión mediante navegador y sincronización entre máquinas, con la misma garantía de cero exposición. Todo lo que hay en este repositorio sigue siendo MIT y se puede seguir usando de forma totalmente independiente. Ver docs/HOSTED.md.

Licencia

MIT