MutagenEx.JsonPath (mutagen_ex v0.2.0)

Copy Markdown View Source

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:

  1. validate_literal/1 — pure-string checks. Runs at CLI parse time so the bad shapes (NUL byte, .. segments) produce an :unsafe_json_path abort-JSON before any filesystem touch.
  2. 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 passed unsafe_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.

Functions

Filesystem-level canonicalisation.

Pure-string validation of a --json path literal.

Types

details()

@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.

reason()

@type reason() :: :unsafe_json_path

Reason atom returned on rejection. Single value; details map carries the variant.

Functions

canonicalize(path, opts \\ [])

@spec canonicalize(
  String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, reason(), details()}

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 to File.cwd!/0. Resolved through Path.expand/1 so a symlinked cwd does not trip the inside-root check.
  • :unsafe_outside_project — boolean. When true, the inside-root check is bypassed; only the symlink-escape check runs. Default false.

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).

validate_literal(path)

@spec validate_literal(String.t()) :: :ok | {:error, reason(), details()}

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). --json requires 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}.