Novedades de zn-gate 1.13.0: zn-gate connect, zn-gate report y una corrección de la GitHub Action

zn-gate 1.13.0 añade zn-gate connect, que activa la comprobación opcional en la nube con una clave de API solo de análisis guardada en el llavero del sistema, y zn-gate disconnect, que además puede revocar esa clave. Añade zn-gate report, un resumen local de lo que zn-gate hizo en los últimos días. También corrige la versión por defecto de la GitHub Action, mantiene el registro de auditoría en una sola cadena cuando varios programas escriben en él y permite desactivar el color con NO_COLOR. zn-gate sigue sin necesitar cuenta y no envía nada por defecto. Actualiza con npm install -g zn-gate@1.13.0 y pip install -U zn-gate.

¿Cómo activo la comprobación opcional en la nube?

Ejecuta esto en tu propia terminal:

npx -y zn-gate connect

La comprobación en la nube es opcional. zn-gate funciona por completo en tu equipo sin ella. Al activarla, el texto de las llamadas a analyze_prompt (y zn-gate analyze), con los secretos detectados ocultos antes, también lo comprueba el clasificador Galvanize 2 de usezn.com. Los hooks, la protección de archivos y secretos y el resto de comandos siguen siendo locales.

Qué hace connect:

1. Solo se ejecuta en una terminal en la que tecleas. Si lo lanza un agente de IA, se niega.
2. Abre usezn.com en tu navegador, donde creas una clave de API solo de análisis.
3. Pegas la clave en un prompt oculto. Nunca se toma de la línea de comandos.
4. Guarda la clave en el llavero del sistema, o en la bóveda de zn si no hay llavero y la bóveda está desbloqueada (zn unlock), y nunca en un archivo.

Solo acepta una clave limitada a analizar texto. Una clave así no puede leer tu uso ni gestionar claves, de modo que una copia filtrada sirve de poco, y una clave de acceso completo se rechaza. zn-gate status muestra si hay una clave conectada y de dónde viene, sin mostrarla. Una clave en ZN_API_KEY o --key solo interviene si además defines ZN_CLOUD=1. La clave guardada solo se envía a https://api.usezn.com. La guía completa, con lo que se envía y qué hacer si algo falla, está en la documentación de connect.

¿Cómo me desconecto y revoco la clave?

zn-gate disconnect

Elimina la clave guardada de este equipo y pregunta si también quieres revocarla en usezn.com, para que deje de funcionar en todas partes. La respuesta por defecto es no. Solo un sí explícito envía algo: una petición con la clave a https://api.usezn.com. En tu propia terminal, --revoke se salta la pregunta y --no-revoke nunca revoca. Si la petición de revocación falla, la copia local se elimina igualmente y el comando te remite a la página de claves de API de usezn.com para que revoques la clave tú mismo.

Igual que connect, disconnect solo se ejecuta en tu propia terminal. Desde un script o un agente de IA se niega y no cambia nada. Los hooks también rechazan los comandos que piden al llavero del sistema las entradas propias de zn, así que se cierran las vías directas para que un agente lea la clave guardada. Un programa que se ejecuta como tú aún puede consultar el llavero, como con cualquier entrada. Por eso la clave se limita a analizar texto.

¿Qué muestra zn-gate report?

npx -y zn-gate report

Imprime un resumen corto de los últimos 7 días en este equipo:

• acciones bloqueadas, por agente;
• secretos ocultados, por tipo;
• servidores MCP nuevos que zn-gate empezó a proteger;
• herramientas de servidores MCP protegidos que cambiaron y esperan tu aprobación;
• el día con más actividad.

Usa --since con un periodo de 1d a 90d para cambiar el rango, y --json para scripts. El informe solo lee archivos locales, no escribe nada y no envía nada. Termina con una línea sobre zn Team; --no-team-line la oculta, y no aparece cuando el equipo ya se ha unido a un Team. Consulta la documentación de report.

¿Hay alguna corrección de seguridad?

Sí. Algunos formatos de token de proveedores no se ocultaban en la API de la biblioteca, en las comprobaciones de las herramientas MCP, en el texto enviado al análisis en la nube ni en la vista previa local de la evidencia. Ahora se ocultan igual que en el paquete de Python. Los hooks de agente no se vieron afectados. Actualiza a zn-gate 1.13.0.

¿Qué más hay de nuevo?

• El scrubber reconoce una clave de API de zn (zn_ seguido de 48 caracteres) y la oculta como otras claves de proveedores.
• Claude Code: un nuevo hook UserPromptExpansion comprueba en qué se expande una skill o un comando escritos. Bloquea la expansión, con el motivo y el siguiente paso, cuando el modelo vería un valor secreto, una clave privada o las líneas de un archivo .env. Ejecuta de nuevo zn-gate hooks install claude-code para añadirlo; el plugin ya lo incluye.
• zn-gate check ahora avisa cuando los hooks de Claude Code instalados por un zn-gate anterior no tienen esa comprobación, y sugiere el mismo comando.
• zn-gate init ya no instala el plugin de Claude Code cuando Node.js es anterior a la 20.12, que el plugin necesita. En su lugar configura los hooks de zn para Claude Code y lo indica en una línea.
• Los hooks comprueban el código que ejecutan shells y wrappers a partir de una cadena (sh -c, bash -lc, eval, pwsh -Command, cmd /c y más) como un comando propio, de modo que cada regla se aplica dentro.
• zn audit oculta el valor tras una opción de credencial en más formas de listas de argumentos, en sus informes de texto, JSON y SARIF.
• Más pruebas automáticas de los servidores MCP, zn run, la bóveda, zn team, reach, audit y el paquete de Python. Sin cambios de comportamiento.

¿Qué cambia en la GitHub Action?

La entrada version ahora tiene por defecto la versión de zn-gate de la propia release de la Action (1.13.0 en esta release). La versión 1.12.0 de la Action usaba por defecto la 1.10.0, así que un workflow con usezn/zn@v1.12.0 y sin version instalaba zn-gate 1.10.0. Si usas la Action, indica version en tu workflow para elegir exactamente qué se ejecuta. La guía de GitHub Actions incluye las entradas y un ejemplo mínimo de auditoría, y esta versión también actualiza el texto de la ficha del Marketplace sin cambiar el comportamiento.

¿Qué pasa si el registro de auditoría está dañado?

El registro de auditoría (~/.zn/evidence.jsonl) ahora se comprueba en busca de daños antes de añadirle nada. Un registro con bytes ilegibles o una última línea cortada se notifica como corrupto, con el número de línea, mediante evidence --verify (salida distinta de cero), evidence y evidence --export, en lugar de fallar con un error de Python. Un registro dañado nunca se usa para iniciar una cadena nueva. El evento no se escribe, se muestra un aviso y tu comando o agente sigue como siempre.

Para recuperarlo, aparta el archivo dañado y el siguiente evento inicia una cadena nueva:

mv ~/.zn/evidence.jsonl ~/.zn/evidence.damaged.jsonl

En Windows, en cmd: move %USERPROFILE%\.zn\evidence.jsonl %USERPROFILE%\.zn\evidence.damaged.jsonl; en PowerShell: Move-Item $env:USERPROFILE\.zn\evidence.jsonl $env:USERPROFILE\.zn\evidence.damaged.jsonl. El archivo antiguo se conserva para revisarlo.

Varios programas pueden escribir en el registro a la vez, por ejemplo dos agentes en un mismo proyecto, o los paquetes de Node.js y de Python juntos. Cada escritura toma ahora un bloqueo breve (un archivo evidence.jsonl.lock junto al registro), de modo que los registros se mantienen en una sola cadena. Si el bloqueo sigue ocupado durante 2 segundos, o no se puede escribir en el registro (sin permiso, disco lleno), el evento se omite con un aviso y la decisión no cambia. Un bloqueo que deja un programa que falló se libera a los 10 segundos. Los paquetes de Node.js y de Python también pueden compartir un registro con texto no ASCII, como letras con acento o CJK, y los registros escritos por versiones anteriores siguen verificándose.

¿Qué más se ha corregido?

• El hook ya no rechaza un comando que escribe un archivo desde un here-document (cat > file <<'EOF') cuando el cuerpo contiene un * u otro carácter comodín, y comprueba un cuerpo de 100 KB en pocos milisegundos en lugar de decenas de milisegundos. El cuerpo de un here-document solo se lee como dato en un comando de datos simple como cat o tee. Los cuerpos que ejecuta un shell, un intérprete o xargs se siguen rechazando, igual que toda lectura de .env o de un archivo de credenciales en la línea de comandos.
• La salida de la línea de comandos de los paquetes de Node.js y de Python no lleva códigos de color cuando NO_COLOR tiene cualquier valor no vacío, cuando TERM=dumb o cuando la salida no es una terminal. Con NO_COLOR o TERM=dumb también omite símbolos y líneas de recuadro. Las palabras de estado, como ALLOWED y BLOCKED, mantienen su significado, y los códigos de salida y las salidas JSON, SARIF y de los hooks de agentes no cambian.
• Los hooks rechazan un archivo .env al que se llega mediante una raíz de Windows, un recurso de red compartido o una ruta de longitud extendida (type %CD%\.env, more \\server\share\.env, gc \\?\C:\path\.env), porque zn no puede leer una ruta así para comprobar si el archivo contiene valores.
• La regla que protege la clave de zn ya no confunde un módulo llamado cloud-keys con el módulo cloud-key propio de zn, y ahora también reconoce nombres de módulo escritos con secuencias de escape o partidos con comillas.
• El scrubber ya no notifica como secreto un ejemplo enmascarado (una clave de Anthropic o un valor bearer formado casi todo por un mismo carácter repetido).
• zn-gate reach --remember muestra la fecha de la ejecución anterior solo cuando es una fecha simple, así que un archivo de memoria editado no puede meter otro texto en el informe.

Preguntas frecuentes

¿Qué novedades trae zn-gate 1.13.0?

zn-gate connect y zn-gate disconnect, para activar y desactivar la comprobación opcional en la nube con una clave de API solo de análisis guardada en el llavero del sistema o en la bóveda. zn-gate report, un resumen local de los últimos días. El scrubber reconoce las claves de API de zn, los hooks comprueban en qué se expande una skill escrita, un registro de auditoría dañado se notifica en vez de fallar y se corrige la versión por defecto de la GitHub Action. El registro de auditoría mantiene una sola cadena cuando varios programas escriben en él, y la salida de la línea de comandos puede ser texto plano con NO_COLOR.

¿Cómo actualizo a zn-gate 1.13.0?

Ejecuta npm install -g zn-gate@1.13.0 para el paquete de Node y pip install -U zn-gate para el de Python. Si Claude Code usa los hooks de zn en lugar del plugin, ejecuta npx -y zn-gate@1.13.0 hooks install claude-code para añadir el hook nuevo; npx -y zn-gate@1.13.0 check te avisa si falta. Si usas el plugin de Claude Code, actualízalo desde el directorio de plugins cuando la 1.13.0 aparezca allí.

¿Necesito una cuenta para usar zn-gate 1.13.0?

No. zn-gate sigue sin necesitar cuenta y no envía nada por defecto. zn-gate connect es opcional: solo después de ejecutarlo, el texto de las llamadas a analyze_prompt (con los secretos detectados ocultos antes) también lo comprueba el clasificador Galvanize 2 de usezn.com.

¿zn-gate report envía mis datos a algún sitio?

No. Solo lee archivos locales, no escribe nada y no envía nada. Compartir estadísticas de uso con zn es una decisión aparte que está desactivada salvo que la actives.

¿Qué versión instala la GitHub Action si omito version?

Desde la 1.13.0, cada versión de la Action usa por defecto su propia versión de zn-gate. La versión 1.12.0 de la Action usaba por defecto la 1.10.0, así que un workflow con usezn/zn@v1.12.0 y sin version instalaba zn-gate 1.10.0. Indica version en tu workflow para elegir exactamente qué se ejecuta.

---

La lista completa de cambios está en las notas de la versión 1.13.0. zn-gate es MIT, se ejecuta en local y no necesita cuenta: empieza con npx -y zn-gate report, o consulta Instalación para cada agente.