feat(notifications): JSON-safe webhook template, SMTP timeout and implicit TLS, test-send buttons (#5064)

#5064 "Notifications that arrive":
- render_webhook: alert.* is escaped to sit inside a JSON string (a quote
  or newline in a rule name no longer breaks the body); raw.* is the plain
  value for |tojson; a missing value reads "no data"; the template runs
  sandboxed and the body is checked to be JSON before it is sent.
- SMTP: 15s timeout; port 465 connects with implicit TLS, otherwise the
  box means STARTTLS; a From address setting (falls back to the username).
- A webhook error no longer carries the URL, which is a secret.
- Settings → Notifications: "Send a test email" / "Send a test webhook"
  send a sample alert with the form's values (unsaved) and show the result
  and the body that went out; template help names alert.* and raw.*.
- Notification audits go through audit_request; the test send is audited
  as settings.notification.tested, with the channel and outcome only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

steward/core/notifications.py

@@ -8,7 +8,7 @@ import types
 from email.message import EmailMessage
 
 import httpx
-from jinja2 import Template
+from jinja2.sandbox import SandboxedEnvironment
 
 logger = logging.getLogger(__name__)
 
@@ -30,22 +30,37 @@ async def dispatch_notifications(
     return results
 
 
+SMTP_TIMEOUT_S = 15
+
+
+def smtp_mode(port, tls) -> str:
+    """How to talk to the SMTP server: "ssl" (implicit TLS, port 465),
+    "starttls" (upgrade a plain connection, when TLS is ticked) or "plain"."""
+    if int(port or 0) == 465:
+        return "ssl"
+    return "starttls" if tls else "plain"
+
+
+def email_body(alert: dict) -> str:
+    value = "no data" if alert.get("value") is None else alert["value"]
+    return (
+        f"Alert: {alert['state']}\n"
+        f"Rule: {alert['rule_name']}\n"
+        f"Resource: {alert['resource']}\n"
+        f"Metric: {alert['metric']} = {value}\n"
+        f"Threshold: {alert['threshold']}\n"
+        + (f"Note: {alert['note']}\n" if alert.get("note") else "")
+        + f"Time: {alert['timestamp']}\n"
+    )
+
+
 async def _send_email(cfg: dict, alert: dict) -> dict:
     try:
         msg = EmailMessage()
         msg["Subject"] = f"[Steward] {alert['state']} — {alert['rule_name']}"
-        msg["From"] = cfg.get("username", "steward@localhost")
+        msg["From"] = cfg.get("from") or cfg.get("username") or "steward@localhost"
         msg["To"] = ", ".join(cfg["recipients"])
-        value = "no data" if alert.get("value") is None else alert["value"]
-        msg.set_content(
-            f"Alert: {alert['state']}\n"
-            f"Rule: {alert['rule_name']}\n"
-            f"Resource: {alert['resource']}\n"
-            f"Metric: {alert['metric']} = {value}\n"
-            f"Threshold: {alert['threshold']}\n"
-            + (f"Note: {alert['note']}\n" if alert.get("note") else "")
-            + f"Time: {alert['timestamp']}\n"
-        )
+        msg.set_content(email_body(alert))
         loop = asyncio.get_running_loop()
         await loop.run_in_executor(None, _smtp_send_sync, cfg, msg)
         return {"sent": True, "error": None}
@@ -55,37 +70,59 @@ async def _send_email(cfg: dict, alert: dict) -> dict:
 
 
 def _smtp_send_sync(cfg: dict, msg: EmailMessage) -> None:
-    ctx = ssl.create_default_context() if cfg.get("tls", True) else None
-    with smtplib.SMTP(cfg["host"], cfg.get("port", 587)) as smtp:
-        if ctx:
+    port = int(cfg.get("port") or 587)
+    mode = smtp_mode(port, cfg.get("tls", True))
+    ctx = ssl.create_default_context()
+    if mode == "ssl":
+        smtp = smtplib.SMTP_SSL(cfg["host"], port, timeout=SMTP_TIMEOUT_S, context=ctx)
+    else:
+        smtp = smtplib.SMTP(cfg["host"], port, timeout=SMTP_TIMEOUT_S)
+    with smtp:
+        if mode == "starttls":
             smtp.starttls(context=ctx)
         if cfg.get("username"):
             smtp.login(cfg["username"], cfg.get("password", ""))
         smtp.send_message(msg)
 
 
-async def _send_webhook(cfg: dict, alert: dict) -> dict:
-    template_str = cfg.get(
-        "template",
-        '{"content": "{{ alert.state }} — {{ alert.rule_name }}"}',
-    )
+def _json_str(value) -> str:
+    """A value as it may sit between the quotes of a JSON string."""
+    return json.dumps("" if value is None else str(value))[1:-1]
 
-    # Render Jinja2 template with alert as a namespace object (attribute access)
+
+def render_webhook(template_str: str, alert: dict) -> str:
+    """The webhook body for an alert, checked to be JSON.
+
+    In the template, `alert.<field>` is escaped to sit inside a JSON string
+    ("{{ alert.rule_name }}" stays valid whatever the name holds), with a
+    missing value reading "no data"; `raw.<field>` is the plain value for use
+    with |tojson ({{ raw.value | tojson }} gives a number or null). The
+    template runs sandboxed. ValueError says why a body could not be made.
+    """
+    shown = dict(alert)
+    if shown.get("value") is None:
+        shown["value"] = "no data"
+    env = SandboxedEnvironment()
     try:
-        alert_ns = types.SimpleNamespace(**alert)
-        rendered = Template(template_str).render(alert=alert_ns)
+        rendered = env.from_string(template_str).render(
+            alert=types.SimpleNamespace(**{k: _json_str(v) for k, v in shown.items()}),
+            raw=types.SimpleNamespace(**alert))
     except Exception as exc:
-        error = f"Template render failed: {exc}"
-        logger.error(error)
-        return {"sent": False, "error": error}
-
-    # Validate JSON before sending
+        raise ValueError(f"Template render failed: {exc}") from None
     try:
         json.loads(rendered)
     except json.JSONDecodeError as exc:
-        error = f"Rendered webhook template is not valid JSON: {exc}"
-        logger.error(error)
-        return {"sent": False, "error": error}
+        raise ValueError(f"Rendered webhook template is not valid JSON: {exc}") from None
+    return rendered
+
+
+async def _send_webhook(cfg: dict, alert: dict) -> dict:
+    template_str = cfg.get("template") or '{"content": "{{ alert.state }} — {{ alert.rule_name }}"}'
+    try:
+        rendered = render_webhook(template_str, alert)
+    except ValueError as exc:
+        logger.error(str(exc))
+        return {"sent": False, "error": str(exc)}
 
     try:
         async with httpx.AsyncClient(timeout=10) as client:
@@ -97,6 +134,8 @@ async def _send_webhook(cfg: dict, alert: dict) -> dict:
             response.raise_for_status()
         return {"sent": True, "error": None}
     except Exception as exc:
-        error = str(exc)
+        # The URL is a secret (it usually carries its own token) and httpx
+        # puts it in its error messages.
+        error = str(exc).replace(cfg["url"], "<webhook URL>")
         logger.error(f"Webhook notification failed: {error}")
         return {"sent": False, "error": error}