profile: expand ${HOME} in path fields

[congwang-mk]

Closes #198.

Profiles are not portable between machines: a grant under the author's home has to be hand-edited wherever the username differs. CLI flags avoid this because the shell expands them first, but a profile has no shell, so ~/src in a profile is a relative directory named ~ (a loud failure outside chroot, and a silently weaker policy under it).

Path-typed profile fields now expand ${HOME}.

Vocabulary

Exactly one variable, resolved by sandlock rather than looked up in the environment by name. No security-policy format in this space does general ambient expansion: firejail uses a fixed braced macro set, AppArmor uses @{HOME} from policy tunables, systemd uses %h/%u/%U, nono uses a closed set, and NVIDIA OpenShell refuses expansion entirely. Open-ended ${VAR} belongs to deployment manifests, where the file is configuration rather than the boundary. A sandlock profile is the boundary, so reading it must be enough to know what it grants.

${HOME} resolves to $HOME when set and absolute, otherwise the passwd entry for the real uid. Environment first because the sandboxed program resolves its own ~ through $HOME: a passwd-derived grant could cover a directory the program never opens while denying the one it does.

Grammar

Strict by design. Every unrecognised form is a hard error, which is what makes future additions (${CWD}, ${USER}, tilde) non-breaking: they cannot change the meaning of any profile written today.

Form	Meaning
${HOME}	the home directory
$$	a literal $
${OTHER}	error, unknown variable
${home}	error, lookup is case-sensitive
${}, ${HO-ME}	error, malformed name
${ with no }	error, unterminated
$ anywhere else	error, write $$ or ${HOME}
leading ~	error, write ${HOME}

$$ rather than a backslash escape because expansion runs after TOML parsing, where \$ would mean different things in "..." versus '...' strings.

Scope

Path-typed fields only: all of [config], [program].exec and cwd, and [filesystem].read/write/deny/chroot plus both halves of each mount entry (expanded after the VIRTUAL:HOST split, so a resolved value containing a colon cannot be read as a separator). Never [program].args or [program].env, where a $ belongs to the sandboxed program.

Round trips

Expansion lives in parse_input, never in Deserialize, so learn --merge can read a profile and write it back with ${HOME} intact. Merge dedup keys on the expanded path while emitting the raw entry, so observing an access under ${HOME}/.config no longer appends this machine's absolute path beside the variable.

learn and inspect --toml escape literal dollars on output, since observed paths come straight from the kernel and a real file named foo$bar would otherwise produce a profile the grammar refuses.

Parity

Rust and Python parse profiles independently, so both implement the grammar and both are driven by one shared fixture (tests/fixtures/profile_expansion.toml). Expansion takes the home value as an argument, so no test mutates the environment.

Known limitation

A profile cannot express a path whose first character is a literal ~. Write it as ./~name. Emitted paths are absolute, so learn can never produce one.

Testing

• 782 lib tests, 439 integration tests, 86 sandlock-cli tests, 405 Python tests, all passing.
• New: shared fixture cases in both languages, home-resolution precedence, field scope (args untouched), mount-spec halves, an end-to-end test proving a ${HOME} grant reaches a running sandbox, and a learn --merge round trip asserting the variable survives without a duplicate.

🤖 Generated with Claude Code