MutagenEx.JsonReporter.Sanitizer (mutagen_ex v0.2.0)

Copy Markdown View Source

Truncation + redaction of free-form text that flows into the version 2 JSON document (warnings, compile-error messages, abort-detail messages, and any other string field that captures user-code-derived bytes).

Contract: mutagen.json_schema r10, r11.

Compiler diagnostics and exception messages can include credentials or large excerpts from host code. This module redacts and bounds those messages before the reporter serializes them.

Truncation (r10)

Every sanitized binary is capped at byte_size_limit/0 bytes (default 4 KiB). When truncation occurs, the binary ends with the literal marker " ... <N bytes truncated>" where N is the byte-count that was dropped. Multibyte UTF-8 grapheme boundaries are respected on a best-effort basis — we truncate on a codepoint boundary rather than splitting a grapheme.

Redaction (r11)

Built-in patterns redact URL userinfo, common credential keys, and token prefixes. Add patterns via application config:

config :mutagen_ex, redact: [~r/AWS_SECRET[A-Z0-9_]+=\S+/, "BEARER \S+"]

Each element of the list may be a %Regex{} or a binary regex source. Matches are replaced with the literal string [REDACTED]. Redaction runs BEFORE truncation so the replacement does not push redacted bytes past the cap and then drop them as truncated text.

The default extra pattern list is empty.

API

  • clean/1 — full pass: redact then truncate. The standard entry point for all message and warning strings.
  • clean/2 — same as clean/1 but accepts an explicit opts list (:byte_size_limit, :patterns) for tests that need to override the default cap or pattern list without touching application env.
  • truncate/2 — truncation only.
  • apply_redactions/2 — redaction only.

Summary

Functions

Apply each pattern in patterns to bin, replacing every match with [REDACTED]. Patterns may be %Regex{} or binary regex sources. Binary sources are compiled with Regex.compile!/1 on each call; callers that care about performance should pre-compile.

Default byte-size limit. The cap is fixed at 4 KiB in v1. A future version may make it configurable; until then, callers that need a different cap pass :byte_size_limit to clean/2 (test seam) or truncate/2 directly.

Apply built-in and configured redactions, then truncate to 4 KiB. Returns the cleaned binary. Non-binary input is converted via to_string/1 first; nil is returned unchanged so callers can chain with optional fields.

Same as clean/1 but with explicit opts

See MutagenEx.JsonReporter.Redactor.secret_key?/1.

Truncate bin to at most limit bytes. When truncation happens, the returned binary ends with " ... <N bytes truncated>" and its total byte_size/1 may exceed limit by the length of the marker. This is intentional: the marker is metadata about the truncation, not part of the captured payload, and downstream consumers need a visible signal that bytes were dropped.

Functions

apply_redactions(bin, patterns)

@spec apply_redactions(binary(), list()) :: binary()

Apply each pattern in patterns to bin, replacing every match with [REDACTED]. Patterns may be %Regex{} or binary regex sources. Binary sources are compiled with Regex.compile!/1 on each call; callers that care about performance should pre-compile.

An empty pattern list is a no-op.

byte_size_limit()

@spec byte_size_limit() :: pos_integer()

Default byte-size limit. The cap is fixed at 4 KiB in v1. A future version may make it configurable; until then, callers that need a different cap pass :byte_size_limit to clean/2 (test seam) or truncate/2 directly.

clean(value)

@spec clean(binary() | nil | iodata()) :: binary() | nil

Apply built-in and configured redactions, then truncate to 4 KiB. Returns the cleaned binary. Non-binary input is converted via to_string/1 first; nil is returned unchanged so callers can chain with optional fields.

clean(value, opts)

@spec clean(
  binary() | nil | iodata(),
  keyword()
) :: binary() | nil

Same as clean/1 but with explicit opts:

  • :byte_size_limit — pos_integer cap (default byte_size_limit/0)
  • :patterns — list of patterns (defaults to Application.get_env(:mutagen_ex, :redact, []))

secret_key?(key)

See MutagenEx.JsonReporter.Redactor.secret_key?/1.

truncate(bin, limit)

@spec truncate(binary(), pos_integer()) :: binary()

Truncate bin to at most limit bytes. When truncation happens, the returned binary ends with " ... <N bytes truncated>" and its total byte_size/1 may exceed limit by the length of the marker. This is intentional: the marker is metadata about the truncation, not part of the captured payload, and downstream consumers need a visible signal that bytes were dropped.

Multibyte safety: we split on a codepoint boundary so we never emit an invalid UTF-8 fragment. The marker bytes are pure ASCII.