ES

← Portfolio · Case · Open source

zks: secrets for AI agents that never see them

An AI agent that provisions or rotates secrets normally reads every value it handles. zks inverts that: the agent edits a policy of names and destinations, and the values travel from source to provider without passing through its hands.

Mauro José Ciappina · TypeScript · Node 22 · SQLite · macOS · Apache-2.0 · code on GitHub

01The problem

Coding agents already install packages, run commands and edit files. The natural next step —provisioning an API key on Vercel, storing a token in GitHub Actions— hits a wall: any path that passes the value through the agent exposes it in logs, history and context. Giving it the whole Keychain is worse.

02How it works

The agent edits a policy file: names, sources and destinations, never values. zks resolves every value itself — 1Password, macOS Keychain, a hidden dialog, format-aware generators, templates, dotenv —, shows the human one native approval dialog per new destination, writes straight to the provider, and records metadata only in a hash-chained audit log that any tampering breaks. With zks run -- <command>, secrets are injected into a single child process, with a dialog every time.

03The destinations

Ten destinations: Vercel, AWS SSM Parameter Store, AWS Secrets Manager, GitHub Actions, Railway, Supabase, Netlify, Docker Swarm, Docker Compose secret files, and local .env files. System-wide install owned by root with tools pinned by sha256, plus an SBOM and npm audit on every installation.

04Web token capture

The problem

Tokens a provider issues on the web (clicking "generate API key") must enter the flow without the agent copying the value.

With zks capture inside ego-browser, a zks-built script moves the value from the page to the Keychain: the agent only sees lengths, and provider tokens are only captured from their pinned origins.

05Honest limits

The threat model is documented: it protects against the value traveling through the agent's context or logs, but a same-user agent could still read a page while it shows the value; zks shrinks that window (it clicks the reveal itself, blanks the field, leaves the page on about:blank) and cannot close it. macOS only, and it is not cryptographic zero-knowledge: the README says so.

06Result

Result

Release v1.0.0 (November 2026), Apache-2.0, 483 automated tests — including the suite of its own MCP stdio server that exposes zks to tool-calling agents — and CI on GitHub Actions. Built with ODD on Gentle Shell: specs, test-first, and AI code reviews whose CRITICAL findings were fixed before the release. Code: github.com/mauroociappinaph/zk-secrets .