feat(cli): add --passphrase-file flag for agent create-token

[graysonhyc]

Summary

• Adds --passphrase-file <path> to zerion agent create-token so the wallet passphrase can be read from a chmod 600 file instead of an interactive TTY prompt. Unblocks CI, headless servers, Docker / k8s / Vault, and scripted agent provisioning.
• Argv-passed passphrases are explicitly rejected (--passphrase <value> → unsupported_flag error) because they leak to ps aux, shell history, and CI logs. SSH-style file at parity is the security/UX balance.
• Scope strictly limited to agent create-token. wallet create, wallet import, and other passphrase-gated commands still require an interactive TTY. Skill docs (zerion-agent-management, zerion-sign, zerion-trading) and the README updated to point CI users at the new flag.

File format (documented in zerion-agent-management/SKILL.md)

The file <path> points at is a plain UTF-8 text file whose entire contents are the wallet passphrase (same string a human would type at the TTY prompt). No JSON, no key=value, no headers, no quotes. One optional trailing \n / \r\n is stripped; leading/trailing spaces inside the passphrase are preserved.

Canonical usage:

umask 077
printf '%s' "\$ZERION_PASSPHRASE" > ~/.zerion-pass
chmod 600 ~/.zerion-pass
zerion agent create-token --name bot --wallet my-agent --policy <id> --passphrase-file ~/.zerion-pass
shred -u ~/.zerion-pass 2>/dev/null || rm -f ~/.zerion-pass

Security model

readPassphraseFromFile enforces, on POSIX:

• Path resolves to a regular file (symlinks-to-files OK, but the target is what we validate).
• File mode is 0600 — any group/other bits → refused with passphrase_file_error.
• File is owned by the current uid — refuses another user's file even if it's mode 0600 (matches SSH IdentityFile behavior; prevents a planted symlink from leaking a different principal's secret into this process).
• File is non-empty after the trailing-newline strip.

On Windows, perm + ownership checks are skipped (POSIX mode bits and uid not meaningful there) — users are directed at NTFS ACLs in the docs.

Argv passphrase is rejected before any keystore state is touched; flag-shape errors fail fast and never reach OWS.

What's in the diff

File	Why
`cli/utils/common/prompt.js`	New `readPassphraseFromFile(path)` — perm + uid + format guards
`cli/commands/agent/create-token.js`	Branches on `flags["passphrase-file"]`, rejects `--passphrase `, validates flag shape before policy lookup
`cli/router.js`	Self-explanatory `--help` line for the new flag
`cli/tests/unit/cli/utils/common/prompt.test.mjs`	8 new unit tests: missing, loose perms (POSIX), 0600 happy, CRLF strip, embedded-space preservation, empty file, zero-byte file, non-existent path
`skills/zerion-agent-management/SKILL.md`	Non-interactive section + file-format subsection (rules table + worked examples) + cross-platform deployment table (Docker / k8s / GH Actions / Vault) + threat-model paragraph + `passphrase_file_error` row in the error table
`skills/zerion-sign/SKILL.md`, `skills/zerion-trading/SKILL.md`	CI/headless callouts now point at `--passphrase-file`
`README.md`	New row in the agent-tokens table + one-line intro mention

Test plan

• `npm test` → 167/167 unit tests pass (8 new `readPassphraseFromFile` tests included)
• Manual: `--passphrase` rejected with `unsupported_flag` (verified via `node ./cli/zerion.js agent create-token ... --passphrase x`)
• Manual: `--passphrase-file` (no value) rejected with `missing_args`
• Manual: `--passphrase-file=` (empty) rejected with `missing_args`
• Manual end-to-end on a throwaway wallet — recipe in PR comments / SKILL.md:
  • happy path with `printf '%s' > /tmp/zpass && chmod 600`
  • mode-0644 file refused with `passphrase_file_error` (insecure permissions)
  • non-existent path refused with `passphrase_file_error` (not found)
  • wrong passphrase produces `ows_error` (proves the bytes reach the keystore)
• CI smoke: GitHub Actions snippet from the skill doc, on a feature branch
• No-op on Windows perm/uid checks (verified via guard `process.platform !== "win32"`)

Out of scope (future work)

• `wallet create` / `wallet import` non-interactive paths.
• OS keychain integration (1Password / Keychain / libsecret) — separate PR, different dependency surface.
• TOCTOU between `statSync` and `readFileSync` (would need `openSync` + `fstatSync`) — accepted for now; exploit requires write access to the file's parent dir, at which point compromise is complete.

🤖 Generated with Claude Code