Supervised, auto-refreshing cookie + CSRF session.

UnifiApi.Auth.Cookie.login/4 returns a static Req.Request.t() — fine for one-shot scripts, but when the controller rotates the CSRF token mid-session, callers have to either notice the 403, manually call refresh_csrf/1, and retry, or just re-login.

UnifiApi.Auth.Session wraps the auth state in a GenServer:

• The request struct returned by client/1 has request steps that pull the current cookies + CSRF from :persistent_term (keyed by a per-session ref) at send time — concurrent reads, no mailbox serialization.
• Response steps capture any rotated x-csrf-token header from the response and update the GenServer state and the :persistent_term snapshot for the next call.

Use this in long-running pollers that mix reads and writes against the v1 / v2 endpoints.

Why a GenServer

A GenServer is justified here per the Iron Law: the CSRF token mutates across calls and the rotation write needs to be serialised. Reads, however, do not — they hit :persistent_term directly, so concurrent consumers of one session no longer block on a single mailbox. Read-only stateless usage should stick with UnifiApi.Auth.Cookie.login/4.

Credentials

The username/password are not stored as separate fields in the GenServer state (CWE-522). Supply a :relogin callback instead — the lib calls it only when a fresh login is needed and never holds the plaintext beyond the closure's own capture.

format_status/1 redacts the state, so :sys.get_status/1 and the State: line of :gen_server's abnormal-termination report carry only style/remember/pid.

One exposure remains, and it is a property of OTP's error reporting rather than of this module. If a crash inside a callback is a FunctionClauseError (or another error that captures its arguments), the stacktrace prints those arguments — and the argument may be the authed Req.Request, whose cookie and x-csrf-token headers Req's Inspect implementation renders verbatim. format_status/1 cannot intercept a stacktrace. If you forward crash reports to a third party, scrub cookie and x-csrf-token at your Logger backend or error-tracker boundary.

Quick start

children = [
  {UnifiApi.Auth.Session,
   name: MyApp.UnifiSession,
   client: UnifiApi.new(base_url: "https://192.168.1.1",
             cert_fingerprints: System.get_env("UNIFI_CERT_FINGERPRINTS", "")
             |> String.split(",", trim: true)),
   relogin: fn ->
     UnifiApi.Auth.Cookie.login(
       UnifiApi.new(base_url: "https://192.168.1.1"),
       System.fetch_env!("UNIFI_USERNAME"),
       System.fetch_env!("UNIFI_PASSWORD"),
       style: :udm
     )
   end,
   style: :udm}
]

Supervisor.start_link(children, strategy: :one_for_one)

# Anywhere in your app:
authed = UnifiApi.Auth.Session.client(MyApp.UnifiSession)
UnifiApi.Network.Events.list(authed, "default")

Legacy username/password (deprecated, v0.5 removal)

For backward compatibility, :username + :password are still accepted — the session synthesises a :relogin closure from them. This keeps the plaintext alive for the process lifetime via the closure, so prefer the explicit :relogin callback for new code.