Release v0.28.0: security-audit-0026 I3 + I4 (HTML-email guard + async Turnstile)

Two informational findings from the Session-0026 audit, both
framework-internal defense-in-depth. No operator action: no migration,
no schema/config/overlay change, no deployment-facing surface.

- I3: guard the dead text/html branch in email_envelope.build_envelope.
  No send path passes body_html; the unused branch would emit HTML built
  from possibly-unescaped user content (C1 stored-XSS class in the mail
  channel). Passing body_html now raises NotImplementedError; the arg is
  kept for documented future symmetry, enabling HTML mail becomes a
  deliberate escape-then-unguard change.

- I4: make turnstile.verify_token async. The sync httpx.post ran inside
  the async /auth/otc/request handler, blocking the event loop up to the
  10s timeout on a slow CloudFlare call. It now awaits httpx.AsyncClient
  via a narrow _siteverify_post seam (tests patch the seam, not the
  shared AsyncClient). The sole caller (main.py) now awaits it.

Tests: full backend suite 365 passed. Added a coroutine-contract unit
test for verify_token and flipped the email_envelope HTML test to assert
the guard.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

backend/app/email_envelope.py

@@ -60,12 +60,17 @@ def build_envelope(
     `from_name` is the display label that goes through `formataddr`
     so spaces / commas in the display string are encoded correctly.
 
-    `body_plain` is mandatory. `body_html`, if supplied, lands as the
-    second part of a `multipart/alternative` body — mail clients
-    that prefer HTML render it; clients that don't fall back to the
-    plain part. The text/plain part comes first per RFC 2046, so a
-    plain-text client that picks the first body gets the readable
-    text.
+    `body_plain` is mandatory. `body_html` is **reserved and not yet
+    enabled** (security-audit-0026 I3): no send path supplies it today —
+    every rfc-app mail is plain text — and passing it raises
+    `NotImplementedError`. The parameter is kept in the signature for
+    documented future symmetry: when HTML mail is enabled it will land
+    as the second part of a `multipart/alternative` body (text/plain
+    first per RFC 2046, so a plain-text client picking the first part
+    still gets the readable text). Enabling it is a deliberate act — the
+    caller MUST HTML-escape any user content into `body_html` first (cf.
+    the C1 stored-XSS class: a mail client renders the HTML) and remove
+    the guard below in the same change.
 
     `reply_to`, when set, lets a send path point replies at a
     different mailbox than the From line (e.g., a watcher
@@ -131,13 +136,20 @@ def build_envelope(
             # idempotent and not require auth. See
             # `api_notifications.py` for the receiver.
             msg["List-Unsubscribe-Post"] = "List-Unsubscribe=One-Click"
-    if body_html:
-        # multipart/alternative: text/plain first, text/html second.
-        # `set_content` sets the first part (and the message's main
-        # body); `add_alternative` adds the second part and
-        # restructures the message as multipart/alternative.
-        msg.set_content(body_plain)
-        msg.add_alternative(body_html, subtype="html")
-    else:
-        msg.set_content(body_plain)
+    if body_html is not None:
+        # I3 (security-audit-0026): the multipart/alternative HTML path
+        # is intentionally NOT enabled. No send path passes `body_html`
+        # today, and emitting an HTML body built from user-supplied
+        # content without escaping it first would reintroduce the C1
+        # stored-XSS class in the mail channel (the recipient's client
+        # renders the HTML). Fail loudly here rather than silently
+        # shipping HTML: enabling HTML mail is a deliberate change that
+        # MUST HTML-escape user content at the call site and remove this
+        # guard together. The text/plain path below is the only live one.
+        raise NotImplementedError(
+            "HTML email is not enabled (security-audit-0026 I3): do not "
+            "pass body_html until user content is HTML-escaped at the "
+            "call site and this guard is intentionally removed."
+        )
+    msg.set_content(body_plain)
     return msg

backend/app/main.py

@@ -267,7 +267,7 @@ def _oauth_router(config) -> APIRouter:
         # secret AND TURNSTILE_REQUIRED=false (the default), the gate
         # opens — see `backend/app/turnstile.py` for the full matrix.
         client_ip = request.client.host if request.client else None
-        ts = turnstile.verify_token(body.turnstile_token, client_ip=client_ip)
+        ts = await turnstile.verify_token(body.turnstile_token, client_ip=client_ip)
         if not ts.ok:
             if ts.reason == "misconfigured":
                 # TURNSTILE_REQUIRED=true but the secret is unset. This

backend/app/turnstile.py

@@ -73,6 +73,19 @@ def _siteverify_url() -> str:
     return os.environ.get("TURNSTILE_SITEVERIFY_URL", "").strip() or SITEVERIFY_URL
 
 
+async def _siteverify_post(url: str, data: dict) -> httpx.Response:
+    """Perform the siteverify POST on an `httpx.AsyncClient`.
+
+    Isolated as a narrow seam (I4, security-audit-0026): the call is
+    awaited so a slow CloudFlare response can't block the event loop,
+    and tests patch *this function* rather than the shared
+    `httpx.AsyncClient` (which other modules — gitea, docs — also
+    construct, so a global patch would break app boot).
+    """
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        return await client.post(url, data=data)
+
+
 @dataclass
 class VerifyOutcome:
     """Result of a Turnstile siteverify call.
@@ -98,7 +111,7 @@ class VerifyOutcome:
     reason: str
 
 
-def verify_token(token: str | None, *, client_ip: str | None = None) -> VerifyOutcome:
+async def verify_token(token: str | None, *, client_ip: str | None = None) -> VerifyOutcome:
     """Validate a Turnstile token against CloudFlare's siteverify endpoint.
 
     Returns a VerifyOutcome describing whether the calling endpoint
@@ -108,9 +121,14 @@ def verify_token(token: str | None, *, client_ip: str | None = None) -> VerifyOu
       * 'misconfigured' → 500 "auth misconfigured"
       * 'missing-token' / 'failed' / 'network' → 400 "verification failed"
 
-    Tests monkeypatch `httpx.post` (or set `TURNSTILE_SITEVERIFY_URL`
-    + a MockTransport client) to avoid touching the real CloudFlare
-    endpoint. No real keys are ever embedded in tests.
+    Async (I4, security-audit-0026): the siteverify call is awaited on an
+    `httpx.AsyncClient` so a slow CloudFlare response can't block the
+    event loop (the prior synchronous `httpx.post` stalled the single
+    worker for up to the 10s timeout). Callers must `await` it.
+
+    Tests monkeypatch `_siteverify_post` (the narrow async seam) to avoid
+    touching the real CloudFlare endpoint and to keep the patch off the
+    shared `httpx.AsyncClient`. No real keys are ever embedded in tests.
     """
     secret = _secret()
     required = _required()
@@ -133,7 +151,7 @@ def verify_token(token: str | None, *, client_ip: str | None = None) -> VerifyOu
         data["remoteip"] = client_ip
 
     try:
-        response = httpx.post(_siteverify_url(), data=data, timeout=10.0)
+        response = await _siteverify_post(_siteverify_url(), data)
         payload = response.json()
     except Exception as exc:  # network, JSON parse, etc.
         log.warning("Turnstile siteverify call failed: %s", exc)