Canonicalisation and safety checks for --json <path>.
mix mutagen accepts arbitrary user-supplied output paths via --json.
Combined with the in-process compile-and-execute pipeline
(mutagen.decision.in_process_pipeline), an un-validated path is an
arbitrary-file-write primitive: a malicious mutated test in a third-party
library could redirect the report into /etc/, ~/.ssh/authorized_keys,
or any other path the OS user can write.
This module is the single home for the path-safety contract. Two layers:
validate_literal/1— pure-string checks. Runs at CLI parse time so the bad shapes (NUL byte,..segments) produce an:unsafe_json_pathabort-JSON before any filesystem touch.canonicalize/2— filesystem-aware check. Runs once after CLI parse but before any mutation phase. Expands the path, follows symlinks, and refuses any path whose resolved target lives outside the project root (unless the caller passedunsafe_outside_project: true).
The split keeps MutagenEx.CLI pure (no IO from the parser) while letting
the mix task gate the run on the FS-level check before any mutation runs.
Project root
The project root is File.cwd!/0 at the time of invocation — mix mutagen
always runs from the host project's root (Mix enforces this), so cwd is a
reliable anchor. Symlinks in the cwd itself are resolved once via
Path.expand/1 so a symlinked project directory does not spuriously
trip the inside-root check.
Summary
Types
Details map shape attached to every rejection.
Reason atom returned on rejection. Single value; details map carries the variant.
Types
@type details() :: %{ :variant => :nul_byte | :traversal | :outside_project_root | :empty_path, :path => String.t(), :message => String.t(), optional(:resolved) => String.t(), optional(:project_root) => String.t() }
Details map shape attached to every rejection.
@type reason() :: :unsafe_json_path
Reason atom returned on rejection. Single value; details map carries the variant.
Functions
Filesystem-level canonicalisation.
Returns {:ok, absolute_path} for the resolved destination. Existing
symlinks are resolved. The report file or its parent can be missing.
The writer rechecks the destination before creating or replacing it.
Rejects {:error, :unsafe_json_path, details} when:
- Any existing component is a symlink whose target escapes the project
root (
:outside_project_root). - The fully-resolved absolute path is outside the project root and the
caller did not pass
unsafe_outside_project: true(:outside_project_root).
Options:
:project_root— absolute path of the project root. Defaults toFile.cwd!/0. Resolved throughPath.expand/1so a symlinked cwd does not trip the inside-root check.:unsafe_outside_project— boolean. Whentrue, the inside-root check is bypassed; only the symlink-escape check runs. Defaultfalse.
Note: this function does NOT call validate_literal/1 — callers (the
CLI) run that at parse time, well before this function. Calling
canonicalize/2 with a literal-unsafe path is a programmer error, but
to be safe the function still re-runs the cheap NUL-byte check (Erlang
IO operations on NUL-containing paths raise; we prefer a typed error).
Pure-string validation of a --json path literal.
Rejects:
- NUL bytes anywhere in the path (
:nul_byte). - Any
..segment in the path (:traversal). A literal..is the only way to escape upward without involving the filesystem; refusing it at the literal layer means downstream resolution does not need to deal with it. - Empty strings (
:empty_path).--jsonrequires a non-empty value.
Accepts everything else, including:
- Relative paths (resolved against cwd at write time).
- Absolute paths (anchored where they are — the inside-root check happens
in
canonicalize/2). - Paths that pass through symlinks (handled in
canonicalize/2).
Returns :ok or {:error, :unsafe_json_path, details}.