BreakGlass.Notifier (BreakGlassEx v0.1.0)

Copy Markdown View Source

Handles out-of-band alerting via email and/or webhook after a successful break-glass login, and delivers OTP codes to the break-glass email address.

Both send_otp/3 and alert/1 are intended to be called inside Task.start/1 by the BreakGlass façade (fire-and-forget). Alert delivery failure never prevents a session from being established; all delivery errors are logged at Logger.error level.

Configuration

All keys live under config :break_glass_ex:

  • :mailer — Swoosh mailer module for email delivery (required for email alerting)
  • :from_email — sender address for outbound emails
  • :alert_emails — list of recipient addresses for break-glass alert emails
  • :alert_webhook_url — URL to POST a JSON alert payload on successful login
  • :dev_otp_log — when true, logs the OTP at Logger.warning level to aid local development when using an in-memory mailer

Functions

  • send_otp/3 — delivers the OTP code to the break-glass email address
  • alert/1 — sends alert emails and/or a webhook POST on successful login

Requirements

9.1, 9.2, 9.3, 9.4, 9.5, 9.6, 9.7, 9.8, 9.9, 9.10

Summary

Functions

alert(ip)

Sends break-glass alert notifications after a successful login.

send_otp(to, otp, ip)

Delivers the OTP code to the break-glass email address.

Functions

alert(ip)

@spec alert(ip :: String.t()) :: :ok

Sends break-glass alert notifications after a successful login.

Email alerting

For each address in the :alert_emails config list, an alert email is delivered. If delivery to a single recipient fails, the error is logged at Logger.error level and delivery continues to the remaining recipients.

If :alert_emails is an empty list, a Logger.warning is emitted and email notification is skipped.

If :alert_emails is not configured (absent), email alerting is skipped silently.

Webhook alerting

If :alert_webhook_url is a non-empty string, a JSON POST is sent to that URL via Req.post/2. The payload contains the fields event, ip, timestamp, severity, and message.

If the POST returns a non-2xx status, the error is logged at Logger.error level. If :alert_webhook_url is nil or absent, the webhook step is skipped silently.

Always returns :ok.

send_otp(to, otp, ip)

@spec send_otp(to :: String.t(), otp :: String.t(), ip :: String.t()) :: :ok

Delivers the OTP code to the break-glass email address.

Composes a Swoosh.Email using the configured :mailer and :from_email, then delivers it via mailer.deliver/1. On delivery error the error is logged at Logger.error level and :ok is returned (fire-and-forget contract).

When config :break_glass_ex, dev_otp_log: true is set, the OTP code is also emitted at Logger.warning level to aid local development when using an in-memory mailer.

Always returns :ok.