# `Sigra.Plug.RequireSudo`
[🔗](https://github.com/sztheory/sigra/blob/v1.20.0/lib/sigra/plug/require_sudo.ex#L1)

Sudo mode gate plug that requires recent re-authentication.

This plug checks that the user is authenticated AND that the session's
`sudo_at` timestamp (from `conn.private[:sigra_session]`) is within the
configured sudo window. If the window has expired (or `sudo_at` is nil),
the configured error handler is called with `:stale_sudo` and the
connection is halted.

When MFA is enabled for the user, sudo re-authentication can also be
completed via TOTP code (not just password). The `:mfa_verify_fn` option
enables this: when provided, the sudo confirmation endpoint can accept
a TOTP code as an alternative to the password. Per D-40.

## Options

  * `:error_handler` - Module implementing `Sigra.Plug.ErrorHandler`.
    Required.
  * `:sudo_window` - Maximum age of sudo confirmation in seconds.
    Defaults to `300` (5 minutes).
  * `:mfa_verify_fn` - Optional function `(user, code -> boolean)` for
    TOTP-based sudo verification when MFA is enabled.

## Example

    plug Sigra.Plug.RequireSudo,
      error_handler: MyAppWeb.AuthErrorHandler,
      sudo_window: 600,
      mfa_verify_fn: &MyApp.Auth.verify_totp/2

# `call`
*since 0.4.0* 

Check sudo window freshness and halt if expired.

Reads the session from `conn.private[:sigra_session]` and checks
`session.sudo_at` against the configured sudo window.

# `init`
*since 0.1.0* 

Initialize the plug with the given options.

Sets the default `:sudo_window` to 300 seconds (5 minutes) if not provided.

---

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