use anyhow::{Context, Result};
use serde_json::{json, Value};
use std::fs;
use std::path::Path;
use std::process::Command;
pub const STARTER_POLICY: &str = r#"# Termaxa policy — first matching rule wins; `*` is a wildcard.
# Actions: allow (run silently) | ask (require approval) | deny (block)
#
# ORDER MATTERS, and the hard stops come first on purpose. Until v0.14.1 the
# read-only allows sat at the top, so a broad prefix shadowed the stop below
# it: `git branch -D main` matched `git branch*` and was ALLOWED, and
# `echo $(rm -rf /)` matched `echo *` before `*rm -rf*` could deny it. A rule
# that can never be reached is not a rule. Put your own exceptions ABOVE the
# deny you want them to override — that is what first-match-wins is for.
#
# Matching is case-insensitive unless a rule opts in with
# `case_sensitive: true` (rare; used where a flag's case carries the meaning,
# like `git branch -D` vs `-d`). Quoting cannot disguise a command: rules are
# matched against the tokenized reading as well as the raw one, and the most
# severe verdict governs.
version: 1
default: ask
rules:
# ---- self-defence: the gate's own configuration ----
# A gate that will happily rewrite its own rules is a suggestion. These
# come FIRST because first-match-wins: `echo *` at the bottom of this file
# would otherwise allow
# echo 'default: allow' > .termaxa/policy.yaml
# and every command after it is judged by the agent's own policy.
#
# `*` matches any run of characters, so one rule covers both path
# separators: `.termaxa/policy.yaml` and `.termaxa\policy.yaml`.
#
# These are SHELL rules, and an agent's file-writing tool (Write, Edit, the
# editor's apply-patch) produces no command for them to match. The same
# files are therefore defended a second way: `termaxa init` also registers
# a PreToolUse hook on the write tools, which reads the target path and
# denies a write landing in `.termaxa/` or an agent hook config. It reads
# nothing else and has no opinion about any other file — see src/protect.rs.
#
# A project wired by hand from a pre-v0.15 snippet has the shell half only.
# `termaxa doctor` fingerprints the policy for that case: what was not
# blocked can at least be noticed.
#
# Reads are denied too, except for the handful listed below, because
# separating reads from writes in general would mean enumerating every read
# command. To add one, put it in that group — NOT at the top of the file.
- match: "*.claude*settings*"
action: deny
reason: "Agent hook configuration is off limits — editing it unhooks the gate."
- match: "*.cursor*hooks*"
action: deny
reason: "Agent hook configuration is off limits — editing it unhooks the gate."
- match: "*.codex*hooks*"
action: deny
reason: "Agent hook configuration is off limits — editing it unhooks the gate."
- match: "*.github*hooks*"
action: deny
reason: "Agent hook configuration is off limits — editing it unhooks the gate."
# ---- destruction by overwrite (v0.15) ----
#
# `>` truncates. Until v0.15 the operator was lexed and discarded, so
# `cat /dev/null > .env` matched the read-only `cat *` rule and was ALLOWED.
# Nothing was deleted; the contents were simply replaced.
#
# POSITION IS LOAD-BEARING, twice over. These sit with the self-defence
# denies and ABOVE the .termaxa read exceptions below, because those
# exceptions end in `*` and a trailing `*` swallows a redirect — placed any
# lower, `cat .termaxa/policy.yaml > .env` matches `cat .termaxa*` and the
# gate's own reviewability exception launders the overwrite it exists to
# stop. `the_gates_own_exception_cannot_launder_an_overwrite` holds this.
#
# These rules cover the paths whose loss is not recoverable from the repo.
# Everything else that truncates is classified `file-overwrite` and insured
# (backup::overwrite_targets copies the file aside first), but is NOT gated
# here: agents write files constantly, and a gate that asks on every redirect
# is auto-approved into meaninglessness. Insurance without friction is the
# trade — see #14.
#
# The two string rules below are kept, and a `match_path` rule now sits with
# them. They are not redundant: the string rules read the command as typed,
# the path rule reads what the command actually TOUCHES after resolution.
# `> .env` and `> ./.env` are the same file and different strings - the
# second walked past both string rules for four releases (known-limitations
# 0.2, pinned as a test until v0.16). Matching the resolved target closes
# every spelling of one path at once, which is what the string rules could
# never do by adding more patterns.
- match: "*> .env*"
action: deny
reason: "Overwriting .env destroys credentials that are not in the repo."
- match: "*>.env*"
action: deny
reason: "Overwriting .env destroys credentials that are not in the repo."
# No `match:` on purpose. This rule speaks about a PATH, and giving it a
# string pattern to satisfy the schema is what broke it the first time:
# `match: "*.env*"` fired on its own and denied `cat .env`, `grep KEY .env`,
# `git diff .env`, even `vim .env.sample`. Reading a file is ordinary work.
- match_path: "*/.env"
action: deny
reason: "Overwriting .env destroys credentials that are not in the repo."
- match: "*> /etc/*"
action: deny
reason: "Overwriting a system config file."
- match: "*> ~/.ssh/*"
action: deny
reason: "Overwriting an SSH key or config."
- match: "*> *id_rsa*"
action: deny
reason: "Overwriting an SSH private key."
# The policy is an in-repo artifact, reviewable in PRs, and the deny below
# would otherwise make that workflow impossible: `git add .termaxa/…`,
# `git diff .termaxa/…` and `cp .termaxa/policy.yaml backup.yaml` are all
# blocked by it. These exceptions give the workflow back.
#
# The test for inclusion is that the `.termaxa` path can only be READ, never
# written. diff/status/log/show/cat read it; add/commit stage what is
# already on disk. `checkout`, `restore` and `config` are absent on purpose
# — overwriting the working tree from a ref is exactly what the deny is for,
# so restoring a clobbered policy stays a thing you do yourself.
#
# `cat` and `cp` are anchored on the SOURCE path so the copy can only go the
# safe way: `cp .termaxa/policy.yaml backup.yaml` matches,
# `cp backup.yaml .termaxa/policy.yaml` does not.
#
# Position matters twice over. Above the deny, or these never fire. Below
# the four denies above, because a trailing `*` swallows a redirect —
# cat .termaxa/policy.yaml > .claude/settings.json
# matches `cat .termaxa*` too, and at the top of the file it would allow
# that and shadow the rule that exists to stop it.
- match: "git diff *.termaxa*"
action: allow
- match: "git status *.termaxa*"
action: allow
- match: "git log *.termaxa*"
action: allow
- match: "git show *.termaxa*"
action: allow
- match: "git add *.termaxa*"
action: allow
- match: "git commit *.termaxa*"
action: allow
- match: "cat .termaxa*"
action: allow
- match: "cp .termaxa*"
action: allow
- match: "*.termaxa*"
action: deny
reason: "Termaxa's own config is off limits — that is the gate. Edit it yourself."
# ---- destructive: hard stops ----
- match: "git push*--force*"
action: deny
reason: "Force pushes are blocked by policy. Open a PR instead."
# The filesystem root, and only the root. `rm -rf /*` would be a WILDCARD
# matching every absolute path — `rm -rf /home/me/project/.git` included —
# and would then explain itself as "delete from root", which is the right
# verdict wearing the wrong sentence. A proving run caught it: an agent was
# correctly stopped from deleting a .git directory and told the reason was
# the filesystem root. The broad `*rm -rf*` rule below catches everything
# else and says something true about it.
- match: "rm -rf /"
action: deny
reason: "Recursive delete from the filesystem root is blocked."
- match: "rm -rf / *"
action: deny
reason: "Recursive delete from the filesystem root is blocked."
# GNU rm refuses `rm -rf /` on its own; --no-preserve-root is the one
# spelling it obeys. The rule above is named for the command everybody
# quotes, this one is named for the command that actually works.
- match: "*--no-preserve-root*"
action: deny
reason: "--no-preserve-root is the only spelling `rm` obeys at `/`. Blocked."
# Broad recursive-force deletes (any target), Unix + PowerShell + cmd
# forms. DENY by default: with auto-approving agent UIs, `ask` silently
# degrades to `allow`. Relax deliberately, per project, if you need to.
- match: "*rm -rf*"
action: deny
reason: "Recursive force delete blocked by default policy."
- match: "*rm -fr*"
action: deny
reason: "Recursive force delete blocked by default policy."
- match: "*Remove-Item*-Recurse*"
action: deny
reason: "Recursive delete (PowerShell) blocked by default policy."
- match: "*Remove-Item*-Force*"
action: deny
reason: "Forced delete (PowerShell) blocked by default policy."
- match: "*del /s*"
action: deny
reason: "Recursive delete (cmd) blocked by default policy."
- match: "*rmdir /s*"
action: deny
reason: "Recursive delete (cmd) blocked by default policy."
- match: "*rd /s*"
action: deny
reason: "Recursive delete (cmd) blocked by default policy."
- match: "kubectl delete*"
action: deny
reason: "kubectl delete is blocked. Use a manifest change + apply."
- match: "*drop table*"
action: deny
reason: "DROP TABLE is blocked. Archive or rename instead."
- match: "*drop database*"
action: deny
reason: "DROP DATABASE is blocked."
- match: "terraform destroy*"
action: deny
reason: "terraform destroy is blocked by policy."
- match: "tofu destroy*"
action: deny
reason: "tofu destroy is blocked by policy."
# ---- consequential: human in the loop ----
#
# RECOVERABILITY INVARIANT (v0.15). A destructive rule may be `ask` only if
# something can undo it. If neither Termaxa nor the system can, it denies —
# because `ask` under an auto-approving UI is `allow`, and an `allow` you
# cannot undo is the failure this tool exists to prevent.
#
# Recovery paths that count, and who provides them:
# termaxa file snapshot rm and friends (backup::rm_targets)
# termaxa pg_dump psql/mysql destructive (backup::pg_backup_targets)
# termaxa git ref pin push --force (backup::git_force_push_target)
# termaxa tfstate copy terraform apply/destroy (backup::tf_state_target)
# git reflog branch -D, reset --hard (git's own, ~90 days)
# the registry npm/cargo publish (yank; not deletion)
# the remote gh pr merge (revert commit)
#
# `the_starter_policy_has_no_uninsurable_asks` enforces this. A destructive
# rule added here without a recovery path fails the build.
# `git branch -D` force-deletes an unmerged branch; `-d` refuses unless it is
# merged. Until v0.15 a rule could not tell them apart, because matching
# lowercased the rule as well as the command — so this asked for both and
# took the safer action for the gentler flag.
#
# A rule can now opt in with `case_sensitive: true`, matched as written, so
# these can differ. The opt-in is explicit and rare on purpose: an uppercase
# SPELLING alone changes nothing (`*Remove-Item*` still catches
# `remove-item`). `-D` still asks rather than denies, because the commits
# survive in the reflog for ~90 days and denying outright would block a
# routine cleanup; but it says which one it caught.
- match: "git branch*-D*"
case_sensitive: true
action: ask
reason: "Force-deleting a branch even if unmerged. Recoverable via git reflog."
- match: "git branch*-d*"
action: ask
reason: "Deleting a merged branch."
- match: "git push*"
action: ask
- match: "terraform apply*"
action: ask
- match: "tofu apply*"
action: ask
- match: "docker rm*"
action: ask
# No recovery path: prune deletes unused images, containers, networks and
# (with -a or --volumes) data that nothing else holds a copy of. Termaxa
# cannot snapshot a docker volume and docker keeps no undo. Denied rather
# than asked, per the invariant above.
- match: "docker system prune*"
action: deny
reason: "docker system prune has no recovery path. Remove specific objects instead."
# Raw device writes destroy partition tables and filesystems with nothing
# to restore from. Not insurable at any layer.
- match: "dd*of=/dev/*"
action: deny
reason: "Writing to a raw device is not recoverable."
- match: "mkfs*"
action: deny
reason: "Formatting a device is not recoverable."
- match: "npm publish*"
action: ask
- match: "cargo publish*"
action: ask
- match: "gh pr merge*"
action: ask
- match: "aws *"
action: ask
- match: "curl*"
action: ask
- match: "ssh *"
action: ask
# ---- read-only operations: let the agent work ----
- match: "git status*"
action: allow
- match: "git diff*"
action: allow
- match: "git log*"
action: allow
- match: "git branch*"
action: allow
- match: "git commit*"
action: allow
# A prefix without its trailing space is a prefix, not a command: `ls*`
# also matched `lsof` and `lsblk`, `grep*` also matched `grepdiff`.
# `cat *` and `echo *` below always had this right. Bare `ls` needs its own
# rule because `ls *` requires the space; bare `cat`/`grep` just read stdin,
# so they stay on the default.
- match: "ls"
action: allow
- match: "ls *"
action: allow
- match: "cat *"
action: allow
- match: "grep *"
action: allow
- match: "echo *"
action: allow
- match: "git remote -v"
action: allow
- match: "git fetch*"
action: allow
- match: "terraform plan*"
action: allow
- match: "terraform init*"
action: allow
- match: "tofu plan*"
action: allow
- match: "kubectl get*"
action: allow
- match: "kubectl describe*"
action: allow
- match: "docker ps*"
action: allow
# Session circuit breaker (v0.11): if the same destructive intent
# (file delete / db destroy / git force / infra destroy) is asked or
# denied `threshold` times in one agent session, further variants are
# DENIED automatically. Human-approved commands don't count.
circuit_breaker:
enabled: true
threshold: 2 # trip on the 3rd attempt
"#;
pub fn run(
dir: &Path,
write_claude_hook: bool,
write_cursor_hook: bool,
write_codex_hook: bool,
write_copilot_hook: bool,
) -> Result<()> {
let termaxa_dir = dir.join(".termaxa");
fs::create_dir_all(&termaxa_dir)?;
let policy_path = termaxa_dir.join("policy.yaml");
if policy_path.exists() {
println!("• .termaxa/policy.yaml already exists — leaving it untouched");
} else {
fs::write(&policy_path, STARTER_POLICY)?;
println!("✓ wrote .termaxa/policy.yaml (starter policy)");
}
match crate::paths::resolve_readonly(dir)
.and_then(|p| record_fingerprint(&p.state_dir, &policy_path))
{
Ok(Some(short)) => println!("✓ recorded policy fingerprint {}", short),
Ok(None) => {}
Err(e) => println!("! could not record policy fingerprint: {}", e),
}
println!("\nAgent harnesses detected:");
let mut found_any = false;
for (label, probe) in [
(
"Claude Code",
dir.join(".claude").exists() || which("claude"),
),
("Cursor", dir.join(".cursor").exists()),
("OpenHands", which("openhands")),
("Codex CLI", which("codex")),
] {
if probe {
println!(" ✓ {}", label);
found_any = true;
}
}
if !found_any {
println!(" (none found — hook mode still works once you add one)");
}
println!("\nTools detected on PATH:");
for tool in [
"git",
"docker",
"terraform",
"kubectl",
"aws",
"psql",
"npm",
"cargo",
"gh",
"ssh",
] {
if which(tool) {
println!(" ✓ {}", tool);
}
}
if write_claude_hook {
install_claude_hook(dir)?;
} else {
if write_cursor_hook {
let dir_c = dir.join(".cursor");
fs::create_dir_all(&dir_c)?;
let hooks_path = dir_c.join("hooks.json");
let exe = std::env::current_exe()
.ok()
.and_then(|p| p.to_str().map(str::to_string))
.unwrap_or_else(|| "termaxa".to_string());
let cmd = format!("{} hook", exe);
let hooks = serde_json::json!({
"version": 1,
"hooks": {
"beforeShellExecution": [ { "command": cmd } ],
"afterShellExecution": [ { "command": cmd } ]
}
});
fs::write(&hooks_path, serde_json::to_string_pretty(&hooks)?)?;
println!("✓ wrote .cursor/hooks.json (before + after ShellExecution -> termaxa hook)");
println!(" NOTE: restart Cursor after this so it reloads hook config.");
}
println!("\nTo wire Termaxa into Claude Code, run: termaxa init --claude-code");
println!("To wire Termaxa into Cursor (v1.7+), run: termaxa init --cursor");
if write_codex_hook {
let dir_x = dir.join(".codex");
fs::create_dir_all(&dir_x)?;
let hooks_path = dir_x.join("hooks.json");
let hooks = serde_json::json!({
"version": 1,
"hooks": { "PreToolUse": [ { "command": "termaxa hook" } ] }
});
fs::write(&hooks_path, serde_json::to_string_pretty(&hooks)?)?;
println!("✓ wrote .codex/hooks.json (Codex PreToolUse -> termaxa hook)");
}
if write_copilot_hook {
let dir_h = dir.join(".github").join("hooks");
fs::create_dir_all(&dir_h)?;
let hooks_path = dir_h.join("hooks.json");
let hooks = serde_json::json!({
"version": 1,
"hooks": {
"preToolUse": [
{ "type": "command", "command": "termaxa hook", "failClosed": true }
]
}
});
fs::write(&hooks_path, serde_json::to_string_pretty(&hooks)?)?;
println!("✓ wrote .github/hooks/hooks.json (Copilot preToolUse -> termaxa hook, fail-closed)");
}
println!("Other agents: termaxa init --codex | --copilot");
print_hook_snippet();
}
if let Ok(p) = crate::paths::resolve() {
println!("\nRuntime state (logs, backups) lives OUTSIDE the repo:");
println!(" {}", p.state_dir.display());
}
println!("\nDone. Try: termaxa check \"git push --force origin main\"");
Ok(())
}
fn record_fingerprint(state_dir: &Path, policy_path: &Path) -> Result<Option<String>> {
let Some(hash) = crate::fingerprint::of_file(policy_path) else {
return Ok(None);
};
crate::fingerprint::record(state_dir, &hash)?;
Ok(Some(crate::fingerprint::short(&hash)))
}
fn install_claude_hook(dir: &Path) -> Result<()> {
let claude_dir = dir.join(".claude");
fs::create_dir_all(&claude_dir)?;
let settings_path = claude_dir.join("settings.json");
let mut settings: Value = if settings_path.exists() {
let raw = fs::read_to_string(&settings_path)?;
serde_json::from_str(&raw).context("existing .claude/settings.json is not valid JSON")?
} else {
json!({})
};
let hooks = settings
.as_object_mut()
.context("settings.json root must be an object")?
.entry("hooks")
.or_insert(json!({}));
let pre = hooks
.as_object_mut()
.context("hooks must be an object")?
.entry("PreToolUse")
.or_insert(json!([]));
let arr = pre.as_array_mut().context("PreToolUse must be an array")?;
if ensure_hook(arr, BASH_MATCHER) {
println!("\n✓ installed PreToolUse hook in .claude/settings.json");
} else {
println!("\n• Claude Code hook already installed in .claude/settings.json");
}
if ensure_hook(arr, WRITE_MATCHER) {
println!("✓ installed PreToolUse write-tool hook in .claude/settings.json");
}
let post = settings
.as_object_mut()
.context("settings.json root must be an object")?
.get_mut("hooks")
.and_then(|h| h.as_object_mut())
.context("hooks must be an object")?
.entry("PostToolUse")
.or_insert(json!([]));
let post_arr = post
.as_array_mut()
.context("PostToolUse must be an array")?;
if ensure_hook(post_arr, BASH_MATCHER) {
println!("✓ installed PostToolUse hook in .claude/settings.json");
}
fs::write(&settings_path, serde_json::to_string_pretty(&settings)?)?;
Ok(())
}
const BASH_MATCHER: &str = "Bash";
const WRITE_MATCHER: &str = "Write|Edit|MultiEdit|NotebookEdit";
fn ensure_hook(arr: &mut Vec<Value>, matcher: &str) -> bool {
let present = arr.iter().any(|e| {
e.get("matcher").and_then(|m| m.as_str()) == Some(matcher)
&& e.pointer("/hooks/0/command")
.and_then(|c| c.as_str())
.map(|c| c.contains("termaxa hook"))
.unwrap_or(false)
});
if present {
return false;
}
arr.push(json!({
"matcher": matcher,
"hooks": [{ "type": "command", "command": "termaxa hook" }]
}));
true
}
fn print_hook_snippet() {
println!("{}", print_hook_snippet_text());
}
fn print_hook_snippet_text() -> String {
let entry = |matcher: &str| {
json!({
"matcher": matcher,
"hooks": [{ "type": "command", "command": "termaxa hook" }]
})
};
let snippet = json!({
"hooks": {
"PreToolUse": [entry(BASH_MATCHER), entry(WRITE_MATCHER)],
"PostToolUse": [entry(BASH_MATCHER)],
}
});
format!(
"\n .claude/settings.json snippet:\n{}",
serde_json::to_string_pretty(&snippet).unwrap_or_default()
)
}
pub(crate) fn which(bin: &str) -> bool {
let finder = if cfg!(windows) { "where" } else { "which" };
Command::new(finder)
.arg(bin)
.output()
.map(|o| o.status.success())
.unwrap_or(false)
}
fn home_of_project(project: &Path) -> std::path::PathBuf {
project
.parent()
.map(|p| p.to_path_buf())
.unwrap_or_else(|| project.to_path_buf())
}
pub fn print_supervised_setup(project: &Path) -> Result<()> {
use crate::ui::{bold, dim};
let home = crate::paths::home_base()?;
let policy = project.join(".termaxa").join("policy.yaml");
let me = std::env::var("USER").unwrap_or_else(|_| "you".into());
println!();
println!("{}", bold("Supervised mode — setup"));
println!();
if !cfg!(unix) {
println!(
" {}",
dim("Not available on Windows: it needs Unix domain sockets and a")
);
println!(
" {}",
dim("second user account in the form this depends on. Basic mode is")
);
println!(" {}", dim("the Windows answer and is fully supported."));
return Ok(());
}
println!(
" {}",
dim("What this buys: the audit log and the backups stop being the")
);
println!(
" {}",
dim("agent's own account of itself. The agent's user cannot read them,")
);
println!(
" {}",
dim("edit them, or stop the supervisor — not because the code refuses,")
);
println!(" {}", dim("but because the OS does."));
println!();
println!(
"{}",
bold(" Termaxa will not run these for you. Review them, then run as root:")
);
println!();
println!(" # 1. an account for the agent to run as");
println!(" useradd --system --create-home --shell /bin/bash termaxa-agent");
println!();
println!(" # 2. the policy: the agent reads it, and cannot change it");
println!(" chown {me}:{me} {}", policy.display());
println!(" chmod 0644 {}", policy.display());
println!();
println!(" # 3. the state directory: traversable, not listable.");
println!(" # 0711 is deliberate — 0700 makes the socket unreachable");
println!(" # and every command denies; 0755 hands over the log.");
println!(" chown -R {me}:{me} {}", home.display());
println!(" chmod 0711 {}", home.display());
println!();
println!(" # 4. the agent needs to reach the project. 0711 lets it");
println!(" # traverse to a path it knows without listing your home.");
println!(" chmod 0711 {}", home_of_project(project).display());
println!();
println!(" # 5. run it, from the project directory");
println!(" cd {}", project.display());
println!(" termaxa supervise &");
println!(" sudo -u termaxa-agent termaxa wrap -- claude");
println!();
println!(
" {}",
dim("If that last line asks for YOUR password, this machine's sudoers")
);
println!(
" {}",
dim("rule is root-only (`NOPASSWD: ALL` for root, common on managed dev")
);
println!(
" {}",
dim("boxes). `sudo -i` then `su - termaxa-agent` gets there without one.")
);
println!();
println!(
" {}",
dim("Then run `termaxa doctor`, which reports what these produced")
);
println!(
" {}",
dim("rather than assuming they were typed correctly.")
);
println!();
println!(
"{}",
bold(" Credentials are a tradeoff, not a solved problem.")
);
println!(
" {}",
dim("The agent needs git, SSH and registry access to do real work, and")
);
println!(
" {}",
dim("a separate account has none of yours. Three options, none free:")
);
println!();
println!(" shared HOME easiest; dilutes the boundary you just built");
println!(" copied credentials works; you now have two copies to rotate");
println!(" curated per launch most honest, most friction — give the agent");
println!(" only the credentials the task needs");
println!();
println!(
" {}",
dim("Nobody has dissolved this, including us. Pick deliberately.")
);
println!();
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
fn here() -> crate::resolve::EvalContext {
crate::resolve::EvalContext::at(std::path::Path::new("."))
}
use crate::testutil::TempTree;
#[cfg(unix)]
#[test]
fn the_supervised_setup_prints_the_modes_the_rig_proved() {
let t = TempTree::new("sup-setup");
let dir = t.path();
std::fs::create_dir_all(dir.join(".termaxa")).unwrap();
let rig = std::fs::read_to_string("tests/boundary/rig.sh").unwrap();
assert!(
rig.contains("chmod 0711 \"$TERMAXA_HOME\""),
"the rig uses 0711 on the state dir; if that changed, the printed \
setup is now wrong and this test is the only thing that says so"
);
assert!(
rig.contains("chmod 0644 \"$PROJECT/.termaxa/policy.yaml\""),
"the rig uses 0644 on the policy"
);
print_supervised_setup(dir).expect("the setup prints");
}
#[test]
fn shipped_example_policy_matches_the_starter_policy() {
let example = include_str!("../examples/policy.yaml").replace("\r\n", "\n");
assert_eq!(
example, STARTER_POLICY,
"examples/policy.yaml has drifted from init::STARTER_POLICY. \
Regenerate it rather than editing it by hand."
);
}
#[test]
fn the_starter_policy_has_no_uninsurable_asks() {
let p: crate::policy::Policy = serde_yaml::from_str(STARTER_POLICY).unwrap();
let recovery: &[(&str, &str)] = &[
("git branch*-D*", "git reflog retains the commits"),
(
"git branch*-d*",
"git refuses unless merged; reflog retains either way",
),
("git push*", "termaxa pins the remote ref before the push"),
("terraform apply*", "termaxa copies tfstate first"),
("tofu apply*", "termaxa copies tfstate first"),
("docker rm*", "named container; image and volumes survive"),
("npm publish*", "npm deprecate/unpublish window"),
("cargo publish*", "cargo yank"),
("gh pr merge*", "the merge commit can be reverted"),
("aws *", "not destructive by itself; breadth is why it asks"),
(
"curl*",
"not destructive by itself; network egress is why it asks",
),
(
"ssh *",
"not destructive by itself; remote execution is why it asks",
),
];
let mut unjustified = Vec::new();
for rule in p
.rules
.iter()
.filter(|r| r.action == crate::policy::Action::Ask)
{
if !recovery.iter().any(|(m, _)| *m == rule.label()) {
unjustified.push(rule.label());
}
}
assert!(
unjustified.is_empty(),
"these `ask` rules have no documented recovery path: {unjustified:?}\n\
Either add the recovery path to backup.rs and list it here, or make \
the rule `deny`. An ask that cannot be undone is an allow that \
cannot be undone."
);
}
#[test]
fn the_gates_own_exception_cannot_launder_an_overwrite() {
let p: crate::policy::Policy = serde_yaml::from_str(STARTER_POLICY).unwrap();
for cmd in [
"cat .termaxa/policy.yaml > .env",
"cat .termaxa/policy.yaml > /etc/hosts",
] {
assert_eq!(
p.evaluate_command(cmd, &here()).action,
crate::policy::Action::Deny,
"{cmd} must not be allowed via the .termaxa read exception"
);
}
assert_eq!(
p.evaluate_command("cat .termaxa/policy.yaml", &here())
.action,
crate::policy::Action::Allow
);
}
#[test]
fn the_uninsurable_commands_are_denied_not_asked() {
let p: crate::policy::Policy = serde_yaml::from_str(STARTER_POLICY).unwrap();
for cmd in [
"docker system prune -a",
"dd if=/dev/zero of=/dev/sda",
"mkfs.ext4 /dev/sdb1",
] {
assert_eq!(
p.evaluate_command(cmd, &here()).action,
crate::policy::Action::Deny,
"{cmd} has no recovery path and must deny, not ask"
);
}
}
#[test]
fn hard_stops_are_reachable_before_the_read_only_allows() {
let p: crate::policy::Policy = serde_yaml::from_str(STARTER_POLICY).unwrap();
let last_deny = p
.rules
.iter()
.rposition(|r| r.action == crate::policy::Action::Deny)
.expect("starter policy has deny rules");
for (i, r) in p.rules.iter().enumerate().take(last_deny) {
if r.action != crate::policy::Action::Allow {
continue;
}
let Some(pattern) = &r.r#match else {
continue;
};
assert!(
!pattern.starts_with('*') && pattern.contains(".termaxa"),
"rule {i} `{}` is an unanchored allow sitting above a deny — \
it can shadow the rule below it and can never be audited by \
reading the denies alone",
pattern
);
}
}
#[test]
fn init_records_a_baseline_the_policy_directory_cannot_erase() {
let tmp = TempTree::new("init-fp");
let state = tmp.dir("home/projects/proj-abc12345");
let policy = tmp.file("proj/.termaxa/policy.yaml", STARTER_POLICY);
let short = record_fingerprint(&state, &policy)
.unwrap()
.expect("a readable policy must fingerprint");
assert_eq!(short.len(), 12);
let baseline = crate::fingerprint::baseline_file(&state);
assert!(baseline.is_file());
assert!(
!baseline.starts_with(policy.parent().unwrap()),
"baseline must not live in the project: {}",
baseline.display()
);
let again = record_fingerprint(&state, &policy).unwrap().unwrap();
assert_eq!(short, again);
}
fn pre_matchers(settings: &Path) -> Vec<String> {
let v: Value = serde_json::from_str(&fs::read_to_string(settings).unwrap()).unwrap();
v["hooks"]["PreToolUse"]
.as_array()
.unwrap()
.iter()
.map(|e| e["matcher"].as_str().unwrap_or_default().to_string())
.collect()
}
#[test]
fn init_registers_the_write_tools_as_well_as_bash() {
let tmp = TempTree::new("init-write-matcher");
let proj = tmp.dir("proj");
install_claude_hook(&proj).unwrap();
let settings = proj.join(".claude").join("settings.json");
assert_eq!(pre_matchers(&settings), vec![BASH_MATCHER, WRITE_MATCHER]);
let v: Value = serde_json::from_str(&fs::read_to_string(&settings).unwrap()).unwrap();
let post: Vec<&str> = v["hooks"]["PostToolUse"]
.as_array()
.unwrap()
.iter()
.map(|e| e["matcher"].as_str().unwrap_or_default())
.collect();
assert_eq!(post, vec![BASH_MATCHER]);
}
#[test]
fn init_adds_the_write_matcher_to_a_settings_file_that_predates_it() {
let tmp = TempTree::new("init-write-matcher-upgrade");
let proj = tmp.dir("proj");
tmp.file(
"proj/.claude/settings.json",
r#"{"hooks":{"PreToolUse":[{"matcher":"Bash","hooks":[{"type":"command","command":"termaxa hook"}]}]}}"#,
);
install_claude_hook(&proj).unwrap();
assert_eq!(
pre_matchers(&proj.join(".claude").join("settings.json")),
vec![BASH_MATCHER, WRITE_MATCHER]
);
}
#[test]
fn running_init_twice_does_not_duplicate_either_matcher() {
let tmp = TempTree::new("init-write-matcher-twice");
let proj = tmp.dir("proj");
install_claude_hook(&proj).unwrap();
install_claude_hook(&proj).unwrap();
assert_eq!(
pre_matchers(&proj.join(".claude").join("settings.json")),
vec![BASH_MATCHER, WRITE_MATCHER]
);
}
#[test]
fn the_printed_snippet_shows_both_matchers() {
let snippet = print_hook_snippet_text();
assert!(snippet.contains(BASH_MATCHER));
assert!(snippet.contains(WRITE_MATCHER));
}
#[test]
fn the_shadowed_commands_are_no_longer_allowed() {
let p: crate::policy::Policy = serde_yaml::from_str(STARTER_POLICY).unwrap();
for cmd in [
"git branch -D main",
"echo $(rm -rf /)",
"git status & rm -rf /",
] {
assert_ne!(
p.evaluate_command(cmd, &here()).action,
crate::policy::Action::Allow,
"{cmd} is still allowed"
);
}
}
}