# `SquatchMail.Web.Plugs.Auth`
[🔗](https://github.com/Axio-Intelligence/Squatch-Mail/blob/v0.1.0/lib/squatch_mail/web/plugs/auth.ex#L1)

Enforces layers (b) and (c) of `SquatchMail.Web.Router`'s security model.

Layer (a) — a host `pipe_through`ing its own auth pipeline before mounting
`squatch_mail_dashboard` — needs no code here at all; it's just the host's
own plug running earlier in the same `scope`.

This plug runs *before* `live_session`, in the plain Plug pipeline, which
is the only place a real HTTP 401 (with a `www-authenticate` challenge) or
a rendered refusal page can be sent — by the time a LiveView's `on_mount`
hooks run, Phoenix has already committed to a 200 response for the dead
render (see `Phoenix.LiveView.Router`'s own docs on this: auth belongs in
a plug, `on_mount` is for post-auth assigns only).

Precedence, checked in order:

  1. If `config :squatch_mail, :basic_auth` is set, enforce it via
     `Plug.BasicAuth` on every request (layer b).
  2. Otherwise, if a host `:on_mount` was supplied to `squatch_mail_dashboard`,
     assume the host is handling auth itself further up the pipeline and
     let the request through untouched (layer a).
  3. Otherwise — no basic_auth configured, no host on_mount given — allow
     the request through only when
     `Application.get_env(:squatch_mail, :allow_unauthenticated, false)` is
     true. When it is false, halt and render the refusal page (layer c).

Asset routes (`.../assets/css-*`, `.../assets/js-*`) are mounted outside
this plug's scope entirely (see `SquatchMail.Web.Router`), so they are
never subject to any of the above.

---

*Consult [api-reference.md](api-reference.md) for complete listing*