Mailglass.Tracking.Guard (Mailglass v1.5.1)

Copy Markdown View Source

Runtime auth-stream tracking guard ().

Dual enforcement with TRACK-02 NoTrackingOnAuthStream:

  • Compile-time: Credo catches most cases via AST inspection of @mailglass_opts + mailable function names.
  • Runtime: THIS MODULE catches the dynamic-function-name bypass (metaprogrammed mailables, def unquote(name)(...) patterns).

Invoked from Mailglass.Outbound.send/2 () as a precondition similar to Mailglass.Tenancy.assert_stamped!/0 — not a preflight STAGE (no {:error, _} return path), but a FAIL-LOUD raise.

Regex ()

^(magic_link|password_reset|verify_email|confirm_account) — matches the four canonical auth-carrying function-name prefixes. Variant function names starting with these prefixes (e.g. magic_link_verify, password_reset_confirm) ALSO match — Outlook SafeLinks pre-fetch could pre-trigger a tracked pixel on an auth email, which would be visible in scroll-tracking logs and represent a privacy regression.

Adopters CANNOT turn this off

Deliberate choice (). The "acknowledged" escape hatch is not provided. Adopters who hit the regex falsely should rename their function or split their mailable module.

nil mailable_function (T-3-04-01)

When mailable_function is nil, the guard returns :ok — it cannot perform the heuristic without a function name. Credo TRACK-02 is the primary enforcement for this case via compile-time AST inspection.

Summary

Functions

Raises %Mailglass.ConfigError{type: :tracking_on_auth_stream} when the mailable's compile-time tracking opts would enable opens or clicks AND the calling function name matches the auth-stream regex.

Functions

assert_safe!(message)

(since 0.1.0)
@spec assert_safe!(Mailglass.Message.t()) :: :ok

Raises %Mailglass.ConfigError{type: :tracking_on_auth_stream} when the mailable's compile-time tracking opts would enable opens or clicks AND the calling function name matches the auth-stream regex.

Returns :ok otherwise.

Examples

iex> msg = %Mailglass.Message{mailable: MyApp.UserMailer, mailable_function: :welcome}
iex> Mailglass.Tracking.Guard.assert_safe!(msg)
:ok