secrets (agentic-secrets)
A zero-dependency Node CLI that lets an AI coding agent move, generate, compare and check secrets without the value ever being printed or entering its context.
- Status
- Preparing for public release
- First commit
- Latest commit
- Node.js
- ESM
- ssh
- macOS Keychain
- node:test
The problem
Agents that deploy or configure software constantly need to put a secret somewhere: copy an API key into a server’s env file, rotate a signing secret, check two environments agree. The obvious tools (cat .env, ssh host cat file, echo $KEY) put the value into the agent’s context, transcripts and logs.
Key design decisions
Metadata only, by construction. Every command prints one JSON object, and there is no --print or --show flag and no code path that returns a value. check reports presence, length, shape and a six-character SHA-256 fingerprint, plus whether the locations match. Values travel from reader to writer in memory or over ssh stdin, never argv, and an output scrubber replaces any value the process has touched with *** in errors and logs.
A policy file the agent cannot write. Which hosts and paths are allowed lives in a policy file only the human edits. A built-in deny list (production env files, private keys, anything under .ssh/) cannot be removed by policy, a malformed policy fails closed, and a missing one is restrictive by default.
Boring file edits. Env files are edited line by line: only the target line changes, quoting and comments are kept, writes are atomic with a backup, and duplicate keys are refused rather than guessed at.
Honest about limits. The README states this is a sanctioned path, not a sandbox. An agent with other tools can still cat a file, so the tool has to be paired with permission rules that deny those routes, and a six-character fingerprint leaks a few bits for low-entropy values.
Stack
Plain Node 18+ ESM with zero dependencies. All I/O (spawn, fs, tty, clock, RNG, clipboard) is injected, so the tests are hermetic: temp directories and fake ssh, pbcopy, docker and security binaries.
Outcome and what I would change
I ran the suite: 83 tests pass, including leak tests that assert a sentinel value never appears in stdout, stderr, the audit log or any argv. I use it myself, with an instruction in my global agent config pointing at it. Gaps: the keychain and clipboard locators are macOS-only, and remote writes do not fsync. The package is named agentic-secrets and installs a secrets command; the repository is private until the release is ready.