feat(server): allow plain HTTP on non-loopback via ARBOR_ALLOW_PLAINTEXT=1

ARBOR_ALLOW_PLAINTEXT=1 now bypasses the loopback-only check in addition
to the cert-not-found check. This lets users bind to a VPN interface
(e.g. WireGuard 10.x.x.x) with plain HTTP when the tunnel itself
provides confidentiality, without needing a self-signed certificate.

A WARNING is printed at startup; the error message for the default
(unset) case now mentions ARBOR_ALLOW_PLAINTEXT=1 as the escape hatch.
Documented in arbor.env.example under the VPN / private network section.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: gorecodes

backend/arbor/server.py

@@ -29,11 +29,19 @@ def _is_loopback_host(host: str) -> bool:
 def _enforce_loopback_or_tls(host: str, tls: bool) -> None:
     if tls or _is_loopback_host(host):
         return
+    if env_value("ARBOR_ALLOW_PLAINTEXT") == "1":
+        print(
+            f"[arbor] WARNING: ARBOR_ALLOW_PLAINTEXT=1 — plain HTTP on {host!r}. "
+            "Only safe behind a VPN or trusted private network.",
+            flush=True,
+        )
+        return
     print(
         f"[arbor] ERROR: refusing to bind {host!r} without TLS. Plain HTTP is only\n"
         f"[arbor] permitted on loopback (127.0.0.1, ::1, localhost). Provide a\n"
         f"[arbor] TLS certificate (ARBOR_CERT, ARBOR_KEY) or place this instance\n"
-        f"[arbor] behind a TLS-terminating reverse proxy and bind to 127.0.0.1.",
+        f"[arbor] behind a TLS-terminating reverse proxy and bind to 127.0.0.1.\n"
+        f"[arbor] To allow plain HTTP on a private/VPN interface set ARBOR_ALLOW_PLAINTEXT=1.",
         file=sys.stderr,
     )
     sys.exit(2)

backend/tests/test_pr1_web_edge.py

@@ -1,6 +1,8 @@
 """Tests for PR 1 (hardening/web-edge): CSRF, HSTS, TLS bind, WS origin."""
 
+import os
 import unittest
+import unittest.mock
 from unittest.mock import patch
 
 from fastapi.testclient import TestClient
@@ -146,6 +148,12 @@ def test_public_without_tls_exits_2(self):
             web_server._enforce_loopback_or_tls("192.168.1.10", tls=False)
         self.assertEqual(cm.exception.code, 2)
 
+    def test_public_without_tls_allowed_by_plaintext_override(self):
+        with unittest.mock.patch.dict(os.environ, {"ARBOR_ALLOW_PLAINTEXT": "1"}):
+            # No SystemExit expected — user explicitly opted in (e.g. behind VPN).
+            web_server._enforce_loopback_or_tls("0.0.0.0", tls=False)
+            web_server._enforce_loopback_or_tls("10.0.0.1", tls=False)
+
 
 if __name__ == "__main__":
     unittest.main()

config/arbor.env.example

@@ -11,6 +11,12 @@ ARBOR_TLS=0
 # ARBOR_CERT=/etc/arbor/cert.pem
 # ARBOR_KEY=/etc/arbor/key.pem
 # ARBOR_CORS_ORIGINS=https://arbor.lan
+#
+# VPN / private network: to allow plain HTTP on a non-loopback interface
+# (e.g. WireGuard 10.0.0.1) set both of the following:
+#   ARBOR_HOST=0.0.0.0   (or the specific VPN interface IP)
+#   ARBOR_ALLOW_PLAINTEXT=1
+# Only safe when the network itself provides confidentiality (VPN tunnel).
 
 # --- Auth backend (do not change) ---
 ARBOR_AUTH_BACKEND=local