authy CLAUDE.md

CLAUDE.md — Project Instructions

What is this

Authy is a CLI secrets store & dispatch tool for AI agents. Built in Rust. Single binary, no server, no accounts.

Build & Test

cargo build                    # dev build
cargo build --release          # release build
cargo test                     # all tests (unit + integration)
cargo clippy -- -D warnings    # lint (must pass clean)

Project Structure

• src/cli/ — clap command definitions and handlers (one file per command)
• src/cli/common.rs — shared secret resolution logic (used by run, env, export)
• src/cli/json_output.rs — JSON response structs for --json output
• src/cli/env.rs — authy env command (output secrets as env vars)
• src/cli/import.rs — authy import command (import from .env files)
• src/cli/export.rs — authy export command (export as .env or JSON)
• src/cli/serve.rs — authy serve --mcp command (MCP server entry point)
• src/lib.rs — library crate root, re-exports core modules
• src/api.rs — AuthyClient high-level programmatic API facade
• src/mcp/mod.rs — MCP server: JSON-RPC 2.0 handler, McpServer struct
• src/mcp/tools.rs — MCP tool definitions and dispatch (5 tools)
• src/vault/ — encrypted vault storage (age encryption, MessagePack serialization)
• src/auth/ — authentication dispatcher (passphrase / keyfile / session token)
• src/policy/ — glob-based access control policies
• src/session/ — HMAC session token generation and validation
• src/audit/ — append-only JSONL audit log with HMAC chain
• src/subprocess/ — child process spawning with env var injection
• tests/api_test.rs — lib-level tests for AuthyClient API (serial, isolated HOME)
• tests/mcp_test.rs — in-memory MCP server tests (JSON-RPC, serial, isolated HOME)
• tests/integration/ — CLI integration tests using assert_cmd + tempfile
• skills/authy/ — Agent Skills standard skill (works with Claude Code, Cursor, OpenClaw, etc.)

Key Conventions

• All secret-holding types must derive Zeroize and be zeroized on drop
• Secret values flow through stdin/stdout, never CLI arguments
• Diagnostics and errors go to stderr, secret values to stdout
• Session tokens are read-only — no mutation commands accept token auth
• Policy evaluation: deny overrides allow, default deny
• Vault writes use atomic rename (write to .tmp, then rename)
• --json flag produces structured JSON output on stdout, JSON errors on stderr
• Non-interactive mode: fails fast when no TTY and no credentials provided
• Typed exit codes: each error category maps to a specific exit code (1-7)