EN

← Portfolio · Caso · Open source

zks: secretos para agentes de IA que nunca los ven

Un agente de IA que provisiona o rotea secretos normalmente Lee cada valor que maneja. zks invierte eso: el agente edita una política con nombres y destinos, y los valores viajan de la fuente al proveedor sin pasar por sus manos.

Mauro José Ciappina · TypeScript · Node 22 · SQLite · macOS · Apache-2.0 · código en GitHub

01El problema

Los agentes de programación ya instalan paquetes, corren comandos y editan archivos. El paso siguiente natural —provisionar una API key en Vercel, guardar un token en GitHub Actions— choca con una pared: cualquier camino que pase el valor por el agente lo expone en logs, historial y contexto. Darle acceso al Keychain entero es peor.

02Cómo funciona

El agente edita un archivo de política: nombres, orígenes y destinos, nunca valores. zks resuelve cada valor por su cuenta —1Password, Keychain de macOS, un diálogo oculto, generadores con formato, plantillas, dotenv—, muestra al humano un diálogo nativo de aprobación por cada destino nuevo, escribe directo en el proveedor y registra solo metadatos en un log de auditoría encadenado por hash, que cualquier modificación rompe. Con zks run -- <comando> los secretos se inyectan en un único proceso hijo, con diálogo cada vez.

03Los destinos

Diez destinos soportados: Vercel, AWS SSM Parameter Store, AWS Secrets Manager, GitHub Actions, Railway, Supabase, Netlify, Docker Swarm, archivos de secretos de Docker Compose y archivos .env locales. La instalación es de sistema con dueño root y herramientas fijadas por sha256, con SBOM y npm audit en cada instalación.

04Captura de tokens web

El problema

Los tokens que un proveedor emite en la web (un clique en "generar API key") tienen que entrar al Flujo sin que el agente copie el valor.

Con zks capture en ego-browser, un script propio de zks mueve el valor desde la página al Keychain: el agente solo ve longitudes, y los tokens de proveedores solo se capturan desde sus orígenes fijados.

05Límites honestos

El modelo de amenazas está documentado: protege frente a que el valor viaje por el context o logs del agente, pero el agente de mismo usuario podría leer una página mientras la muestra; zks acorta esa ventana (hace el click de revelar, borra el campo, deja la página en about:blank) y no puede cerrarla. Es solo macOS y no es zero-knowledge criptográfico: lo dice en el README.

06Resultado

Resultado

Release v1.0.0 (noviembre de 2026), Apache-2.0, 483 tests automatizados —incluida la suite de su servidor MCP stdio que expone zks a agentes con tools— y CI en GitHub Actions. Hecho con ODD en Gentle Shell: specs, test-first y revisiones de código con IA cuyos hallazgos CRITICAL se corrigieron antes del release. Código: github.com/mauroociappinaph/zk-secrets .