# xop · Architecture ## Module dependency graph ``` main.rs │ ▼ lib.rs (run orchestrator) │ ┌────────────┬────────┼────────┬─────────────┬───────────────┐ │ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ ▼ args.rs secret.rs audit.rs policy.rs guard.rs injector.rs (clap) (refs) (JSONL) (DSL types) (runtime) (env/askpass/fd) │ │ ┌────────────┼─────────────┐ │ │ │ ▼ ▼ ▼ auth/ vault/ commands/ │ │ │ ├─ mod.rs ├─ mod.rs ├─ mod.rs │ (Gate/ ├─ keyring.rs├─ init.rs │ decide) └─ format.rs ├─ set.rs └─ touchid.rs ├─ list.rs ├─ get.rs ├─ rm.rs ├─ reset.rs └─ key.rs ``` `backend/` was removed in v0.2 — the local vault replaces all four external backends. ## Data flow: a typical invocation ``` $ xop --secret DB_PASS=db_pass \ --allow-net=db.local:5432 \ --deny-net=* \ -- mysql -h db.local -u app -e 'SELECT 1' 1. CLI parse (args.rs) Args { subcmd: None, secrets: [("DB_PASS", "db_pass")], allow_net: ["db.local:5432"], deny_net: ["*"], on_leak: Mask, dry_run: false, exec_command: ["mysql", "-h", "db.local", "-u", "app", "-e", "SELECT 1"], } 2. Ref resolution (secret.rs) Ref { key: "db_pass", name: "db_pass" } // bare key, no scheme 3. Policy build (policy.rs) Policy { net: NetPolicy { allow: ["db.local:5432"], deny: ["*"] }, read: ReadPolicy { deny: ["/proc/self/environ", "~/.ssh/id_*", ...] }, leak: Mask, } 4. Vault resolve (vault::resolve_all) → auth::authenticate() → Gate // headless(non-TTY)→AllowKeyring; SSH pty→RequirePassphrase (never remote biometric); // local TTY: LAContext fingerprint — pass→AllowKeyring, cancel→exit 77, no-biometrics→RequirePassphrase → Gate::AllowKeyring ∧ keyring::load() // ~/.x/xop/keyring (0600) hit → key, no typing → Gate::RequirePassphrase ∨ no keyring // rpassword::prompt_password() → derive_key = argon2id(passphrase, salt) → AES-GCM decrypt → entries["db_pass"] = "hunter2" → ResolvedValue { key: "DB_PASS", name: "db_pass", backend: "vault", value: Secret("hunter2") } 5. Injector (injector.rs) Strategy: Envp (mysql reads MYSQL_PWD natively) envp_delta: [("DB_PASS", "hunter2"), ("HISTFILE", "/dev/null"), ...] argv_scrubbed: ["mysql", "-h", "db.local", "-u", "app", "-e", "SELECT 1"] 6. Audit pre-event (audit.rs) {"ts":"...","event":"spawn","refs":["db_pass"],"policy_hash":"sha256:abc...", "child_argv":["mysql","-h","db.local","-u","app","-e","SELECT 1"]} 7. Network policy application (guard/network.rs) macOS: pf rule → block all outbound from PID except to db.local:5432 Linux: iptables -m owner --pid-owner rule (STUB in v0.2 — runtime TBD) 8. File policy application (guard/file.rs) sandbox-exec profile → deny file-read* /proc/*/environ, ~/.ssh/id_* (STUB in v0.2) 9. Spawn (tokio::process::Command) cmd.pre_exec(|| { setrlimit(RLIMIT_CORE, 0, 0); Ok(()) }) // no core dumps cmd.spawn() with: - env_clear() + envs(parent_env) + envs(envp_delta) - stdout: piped to xop's stdout filter - stderr: piped to xop's stdout filter - stdin: inherited from parent - kill_on_drop(true) 10. Stdout filter (guard/stdout.rs) Read chunk from child's stdout pipe. For each chunk, check against secret value patterns. If match: replace with [REDACTED:DB_PASS] (Mask) or SIGKILL (Kill). Write to inherited stdout. 11. Audit post-event {"ts":"...","event":"exit","child_pid":12345,"exit_code":0,"duration_ms":42} 12. waitpid() → exit code 0 propagated to xop's caller ``` ## Subcommand flow (zdata vault operations) ``` $ xop set DB_PASS (value piped via stdin) 1. args.rs → Subcmd::Set { key: "DB_PASS", force: false } 2. commands::set::run("DB_PASS", false) a. auth::authenticate("set DB_PASS in vault") → Gate headless (no TTY) → AllowKeyring (automation path; no osascript call) SSH_TTY/SSH_CONNECTION set → RequirePassphrase (never prompt biometrics remotely) local TTY + macOS → LAContext.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics) pass → AllowKeyring · cancel → exit 77 abort · no biometrics → RequirePassphrase local TTY + Linux → RequirePassphrase (system password prompt forbidden) b. Gate::RequirePassphrase → rpassword::prompt_password("Vault passphrase: ") (keyring ignored) Gate::AllowKeyring + keyring present → silent; no keyring → prompt c. vault::Vault::open(path) key = keyring::load() ∨ argon2id(passphrase, salt) plaintext = AES-GCM-decrypt(ciphertext, nonce, key) entries = toml::from_str(plaintext) → HashMap d. read stdin to EOF → get new value (up to 256 chars) e. if !force && entries.contains_key("DB_PASS"): error KeyAlreadyExists f. entries.insert("DB_PASS", value) g. vault.save() serialize entries to TOML re-randomize nonce encrypt with derived key atomic write: tmp + rename h. audit::vault_set("DB_PASS") i. zeroize passphrase buffer (Drop guard) Other subcommands follow the same shape: list: open + enumerate + audit (no stdout for values) get: open + lookup + print + audit (value to stdout, single line) rm: open + delete + save + audit (TTY confirm unless --force) ``` ## Audit log format (JSONL, one event per line) ```jsonl {"ts":"2026-10-01T12:34:56.123Z","event":"spawn","refs":["db_pass"],"backends":["vault"],"policy_hash":"sha256:9f2a...","child_argv":["mysql","-h","db.local","-u","app","-e","SELECT 1"],"net_allow":["db.local:5432"],"net_deny":["*"],"leak_action":"mask"} {"ts":"2026-10-01T12:34:56.165Z","event":"stdout_mask","child_pid":12345,"ref":"db_pass","action":"masked","bytes_replaced":11} {"ts":"2026-10-01T12:34:56.198Z","event":"exit","child_pid":12345,"exit_code":0,"duration_ms":75} ``` Vault subcommand events: ```jsonl {"ts":"...","event":"vault_init","path":"/home/x/.x/xop/key.db"} {"ts":"...","event":"vault_unlock","auth":"touchid","success":true} {"ts":"...","event":"vault_set","name":"DB_PASS"} {"ts":"...","event":"vault_get","name":"DB_PASS","ok":true} {"ts":"...","event":"vault_rm","name":"DB_PASS"} ``` **Invariant (I2):** no `value`, `plaintext`, `ciphertext`, or `passphrase` field exists in any event. `secrecy::Secret` never crosses this boundary — only refs, names, and metadata. ## Trait surfaces ```rust // src/auth/mod.rs #[async_trait] pub trait Auth: Send + Sync { async fn authenticate(&self, reason: &str) -> Result<()>; } // src/vault/mod.rs pub struct Vault { path, salt, nonce, key, entries } impl Vault { pub async fn open(path: &Path) -> Result; // open order is FIXED: auth::authenticate() FIRST, then keyring::load() // (~/.x/xop/keyring, 0600 — NOT macOS Keychain) — falls back to typed // passphrase + argon2id only when the keyring is absent/XOP_NO_KEYRING=1. pub async fn create(path: &Path, passphrase: &str) -> Result; // create writes the vault AND saves the derived key to the keyring. pub fn key_bytes(&self) -> &[u8; 32]; // for `xop key --save` pub fn get(&self, key: &str) -> Option<&str>; pub fn set(&mut self, key: &str, value: &str); pub fn rm(&mut self, key: &str) -> bool; pub fn list(&self) -> impl Iterator; // (key, created_at) pub async fn save(&self) -> Result<()>; } // src/guard/mod.rs #[async_trait] pub trait Guard: Send + Sync { fn name(&self) -> &'static str; async fn setup(&self, policy: &Policy) -> Result<()>; async fn teardown(&self) -> Result<()>; } ``` ## Lifecycle of a Secret\ ``` vault::get(key) ──► Option<&str> (borrowed, never exposed to LLM) │ ▼ injector::build_envp_delta ──► Vec<(String, Secret)> │ │ ▼ ▼ SecretBox::expose_secret() ◄──┘ tokio::Command envs iter │ │ ▼ ▼ String child copy at execve String dropped after spawn │ ▼ guard::stdout::filter ──► regex match against child stdout bytes; never logs value │ ▼ audit::log_event ──► writes ref/name only; type system forbids value field ``` The `secrecy::SecretBox` type provides: - `Debug` impl that prints `` (so accidental `println!("{:?}", s)` is safe). - `ExposeSecret` trait — explicit `.expose_secret()` required to read. - `Drop` impl that zeroizes inner `T` (when `T: Zeroize`). ## Vault file format (binary) ``` Offset Size Field ------ ---- ---------------------------------------------------------- 0 4 magic = b"XOP\x01" 4 4 version = 1 (u32 LE) 8 16 salt = argon2id salt (random per vault) 24 12 nonce = AES-GCM nonce (random per save) 36 N ciphertext = AES-256-GCM(key, nonce, plaintext) output 36+N 16 tag = AES-GCM auth tag (appended by aes-gcm crate) HEADER_LEN = 4 + 4 + 16 + 12 = 36 Plaintext = UTF-8 TOML: `entries = { key_name = "value", ... }` ``` Write path: encrypt → write to `key.db.tmp.` → fsync → rename to `key.db`. Read path: open → read header → read ciphertext → decrypt → parse TOML.