initial: xop source tree
This commit is contained in:
commit
e4c93e1e13
43 files changed
+7599
No files matched your search
@@ -0,0 +1,249 @@
|
||||
# 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() // ~/.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 <x> except to db.local:5432
|
||||
Linux: iptables -m owner --pid-owner <x> 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<String, String>
|
||||
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/.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<Self>;
|
||||
// open order is FIXED: auth::authenticate() FIRST, then keyring::load()
|
||||
// (~/.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<Self>;
|
||||
// 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<Item = (&str, &str)>; // (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\<T\>
|
||||
|
||||
```
|
||||
vault::get(key) ──► Option<&str> (borrowed, never exposed to LLM)
|
||||
│
|
||||
▼
|
||||
injector::build_envp_delta ──► Vec<(String, Secret<String>)>
|
||||
│ │
|
||||
▼ ▼
|
||||
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 `<secret>` (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.<pid>` → fsync → rename to `key.db`.
|
||||
Read path: open → read header → read ciphertext → decrypt → parse TOML.
|
||||
Reference in new issue
Block a user