phantom-secrets: Instructions file for Claude Code

Phantom — Development Guide

Quick Reference

# Build
~/.cargo/bin/cargo build

# Test
~/.cargo/bin/cargo test

# Lint (must pass with zero warnings)
~/.cargo/bin/cargo clippy --all-targets -- -D warnings

# Format
~/.cargo/bin/cargo fmt --all

# Run CLI
~/.cargo/bin/cargo run -- <command>

If cargo is not on your PATH (a fresh rustup install puts it in ~/.cargo/bin), run export PATH="$HOME/.cargo/bin:$PATH" first.

Architecture

Modular Rust workspace with a shipped secret-protection product and separate fail-closed governed-execution foundations:

• phantom-core — Config (.phantom.toml), .env parsing/rewriting, phantom token generation (256-bit CSPRNG, phm_ prefix), error types
• phantom-vault — VaultBackend trait with OS keychain (macOS Keychain, Linux Secret Service, Windows Credential Manager) and encrypted file fallback. Argon2id parameters hardened to OWASP balanced (m=64 MiB, t=3, p=1) with legacy-default fallback for older vaults
• phantom-proxy — HTTP reverse proxy on 127.0.0.1. It authenticates and matches exact routes, discards client control of the route auth header, injects only the route-owned vault value there, and forwards client bodies byte-for-byte under a hard size cap. Client headers/bodies never resolve phm_ tokens. Uses hyper for server and reqwest for outbound HTTPS; response streaming/SSE is preserved through scrubbing.
• phantom-cli — clap-based CLI for init, proxy execution, diagnostics, sync, teams, audit, validation, provider design foundations, and trusted-terminal workspace setup. Live provider issuance/rotation is hard-denied before credential/network access in 0.7.9. Use phantom --help as the canonical command inventory. Plaintext JSON export is disabled; reveal requires an attached terminal and exact typed confirmation.
• phantom-mcp — MCP server for Claude Code, Cursor, Windsurf, Codex. Uses rmcp 3.5 SDK and stdio transport. Exposes core vault/diagnostic/cloud/team tools plus advanced audit, validation, rotation, expiry, leak-incident, and compliance workflows. The exact catalog is declared in crates/phantom-mcp/src/server.rs; mcp-registry/server.json must match the runtime tools/list exactly (CI runs node scripts/release/mcp-stdio-smoke.mjs target/debug/phantom-mcp 54; after a reviewed schema change, regenerate with node scripts/release/mcp-stdio-smoke.mjs target/debug/phantom-mcp 54 mcp-registry/server.json --write-registry). User-fixable states (not initialized, locked vault, wrong passphrase, bad config) return -32600 with a next step (tools/helpers.rs::state_err); -32603 is for server faults.
• governed-execution foundations — phantom-workspace provides the active value-blind Unix setup transaction. phantom-authority, phantom-locus-contract, phantom-broker, phantom-runtime, phantom-session, and phantom-evidence remain fail closed for production execution.