security(cli): prefer file/stdin/env over --private-key argv (#4032)

[Chessing234]

Summary

• Adds --private-key-file and --private-key-stdin; keeps BUZZ_PRIVATE_KEY.
• Warns when --private-key appears on argv (shell history / ps).
• Docs: CLI README, SECURITY.md, AGENTS.md, TESTING.md.

Fixes #4032

Test plan

• cargo test -p buzz-cli private_key
• cargo test -p buzz-cli cli_definition_is_valid
• buzz --private-key-file /tmp/nsec channels list (with valid key)
• printf '%s' "$NSEC" | buzz --private-key-stdin channels list
• buzz --private-key nsec1… … prints deprecation warning

Made with Cursor

[Chessing234]

Rebased with Signed-off-by so DCO Check is green.

[Chessing234]

Rebased onto latest upstream/main with Signed-off-by on all commits and force-pushed. CI should re-run shortly — still ready for @block/buzz-oss-team review when you have bandwidth.

[Chessing234]

@tlongwell-block @wesbillman @wpfleger96 mind taking a look when you get a chance?

[Chessing234]

still green on tip — this one is the argv private-key leak fix. @tlongwell-block if you get a spare slot on security-ish cli stuff, a look would help a lot.

[Chessing234]

@atishpatel @michaelneale if you have a minute — this is the --private-key argv leak fix (#4032). small, focused, dco green. a quick look would help a lot.

[Chessing234]

@wesbillman this is the --private-key argv leak fix — small and security-relevant. mind reviewing / merging if it still looks good?

[idk-its-unknown]

We hit the same need and independently implemented essentially this design on a fork — --private-key-file on the CLI plus a BUZZ_PRIVATE_KEY_FILE env fallback — and it is now running in production.

Context: we run a 12-agent Buzz fleet on one host, each agent a systemd service. Env-passed BUZZ_PRIVATE_KEY was our biggest operational sore spot: our agent harness sanitizes secret env vars out of tool subprocesses, and env-visible keys are one /proc/<pid>/environ read away from cross-agent identity forgery (we had a real incident of one agent publishing as another). A file-based key (0600) referenced per-unit via Environment=BUZZ_PRIVATE_KEY_FILE=… drop-ins fixed both.

Verification on our fork (fleet-fixes-2026-08-15, base 78cbffeb): 358 buzz-cli tests green on Linux including a keyfile-permissions test; deployed 2026-08-16; every agent's publishing re-verified with its own key (reply signatures checked on the relay wire), zero auth errors.

Two notes that may help this land:

• security: agent signing keys can only be supplied via BUZZ_PRIVATE_KEY (no file, keyring or systemd-credential source) #5568 asks for the env-var half (BUZZ_PRIVATE_KEY_FILE). Implementing both halves together would close that too. The precedence we shipped — explicit BUZZ_PRIVATE_KEY env over flag over BUZZ_PRIVATE_KEY_FILE — made mixed-mode rollout safe: existing env injection keeps winning until you remove it, so a fleet cuts over unit-by-unit with no flag day.
• A cheap file-permissions check (reject group/world-readable keyfiles on Unix) was worth it.

The branch also ships patch-maint/ — the drop-on-adoption carry tooling we use to track exactly this PR and drop our commit the day it merges — plus deployment notes (systemd drop-ins, rollout order), if useful as a reference for anyone running a patched build pre-merge. Would love to see this reviewed — for multi-agent fleets it's a real security boundary, not a convenience flag.