Merge pull request #35 from gorecodes/develop

Develop

Author: gorecodes

.gitignore

@@ -30,3 +30,4 @@ ARBOR_REMEDIATION_PLAN.md
 ARBOR_ARCHITECTURE_ROADMAP.md
 ONLINE_AUTH_HARDENING_PLAN.md
 PHASE1_PROGRESS.md
+FEATURE_PROPOSALS.md

README.md

@@ -353,6 +353,43 @@ ARBOR_CORS_ORIGINS=https://arbor.lan:8443,https://192.168.1.10:8443
 
 Then restart the services and open `https://<hostname>:8443`. You will need to accept the certificate warning unless you import the certificate into your browser trust store.
 
+### Pattern C — plain HTTP on a VPN interface
+
+If Arbor is reachable only through a VPN tunnel (e.g. WireGuard), the tunnel itself provides confidentiality and a self-signed certificate adds no real security. Use `ARBOR_ALLOW_PLAINTEXT=1` to opt out of the TLS requirement:
+
+```bash
+ARBOR_HOST=0.0.0.0        # or the specific WireGuard interface IP
+ARBOR_PORT=8444
+ARBOR_TLS=0
+ARBOR_ALLOW_PLAINTEXT=1   # opt-in: VPN tunnel provides confidentiality
+ARBOR_CORS_ORIGINS=http://10.0.0.1:8444
+```
+
+Arbor prints a startup warning. This mode is **only safe** when the bind address is reachable exclusively through a trusted private network or VPN — do not combine it with a public interface.
+
+If you also want to keep the existing HTTPS reverse-proxy path (e.g. for access via a public domain), run two separate Arbor instances on different ports, or keep Apache terminating TLS on the public side while Arbor binds to the WireGuard IP directly.
+
+**Apache HTTP proxy in front of the VPN path** (optional, e.g. to share port 80 with other services):
+
+```apache
+<VirtualHost *:80>
+    ServerName 10.0.0.1
+    ProxyPreserveHost On
+    RequestHeader set X-Forwarded-Proto "http"
+
+    ProxyPass /ws/ ws://127.0.0.1:8444/ws/
+    ProxyPassReverse /ws/ http://127.0.0.1:8444/ws/
+
+    ProxyPass /api/ http://127.0.0.1:8444/api/
+    ProxyPassReverse /api/ http://127.0.0.1:8444/api/
+
+    ProxyPass / http://127.0.0.1:8444/
+    ProxyPassReverse / http://127.0.0.1:8444/
+</VirtualHost>
+```
+
+Do **not** add `ProxyPassReverseCookiePath` — it rewrites the cookie `Path` attribute, which causes the browser to hold multiple cookies with the same name and breaks CSRF validation. If you previously had this directive and see CSRF errors after removing it, clear all `arbor_*` cookies in the browser and re-login.
+
 ### After any LAN config change
 
 - Sessions made before the change carry the old cookie attributes — log out + log in again to pick up `SameSite=Strict` and the CSRF cookie.
@@ -382,7 +419,7 @@ Then restart the services and open `https://<hostname>:8443`. You will need to a
 | `ARBOR_IPC_KEY_FILE` | `/etc/arbor/ipc.key` | Shared HMAC key file, generated by setup by default |
 | `ARBOR_IPC_ALLOWED_UIDS` | uid of user `arbor` | Comma-separated peer uid allowlist for `/run/arbor/daemon.sock`. Anything outside this set is rejected via `SO_PEERCRED`. |
 | `ARBOR_TRUSTED_PROXIES` | `127.0.0.1` | Comma-separated IPs passed to uvicorn's `forwarded_allow_ips`. Controls which proxy addresses are trusted to set `X-Forwarded-For` / `X-Forwarded-Proto`. |
-| `ARBOR_ALLOW_PLAINTEXT` | unset | Allow plain HTTP on **loopback only** when `ARBOR_TLS` is unset and cert/key are missing. Refused on public binds. |
+| `ARBOR_ALLOW_PLAINTEXT` | unset | Allow plain HTTP on non-loopback interfaces (e.g. a WireGuard VPN address). Set to `1` alongside `ARBOR_HOST=0.0.0.0` (or a specific VPN IP) and `ARBOR_TLS=0`. Only safe when the network itself provides confidentiality (VPN tunnel). A startup warning is printed. |
 | `ARBOR_CORS_ORIGINS` | loopback `http(s)` on `localhost`, `127.0.0.1`, `[::1]` (port `8443`) | Comma-separated allowed origins |
 | `ARBOR_STATIC_DIR` | auto-detected | Override the frontend static directory |
 
@@ -451,9 +488,9 @@ Arbor is still an early-release, local-first admin tool. The default install bin
 ### Web edge
 
 - **CSRF**: every state-changing request (`POST`, `PUT`, `DELETE`, `PATCH`) requires a matching `X-CSRF-Token` header that echoes the `arbor_csrf` cookie. The cookie is set at login, rotated on logout/TOTP changes, and verified by middleware before the handler runs. The first WebSocket auth frame must include the same token. The login endpoint itself is the only exemption.
-- **Cookies**: both `arbor_session` (HttpOnly) and `arbor_csrf` are `Secure` and `SameSite=Strict`. Cross-site navigations no longer carry the session, which closes most CSRF vectors at the browser level.
+- **Cookies**: both `arbor_session` (HttpOnly) and `arbor_csrf` are `SameSite=Strict`. The `Secure` flag is set when the request is served over HTTPS (either Arbor's own TLS or via a reverse proxy that sets `X-Forwarded-Proto: https`); on plain HTTP (e.g. VPN access with `ARBOR_ALLOW_PLAINTEXT=1`) cookies are set without `Secure` so the browser accepts and returns them. Cross-site navigations no longer carry the session, which closes most CSRF vectors at the browser level.
 - **HSTS**: emitted as `Strict-Transport-Security: max-age=63072000; includeSubDomains` when the request is served over HTTPS (including via a reverse proxy that sets `X-Forwarded-Proto: https`).
-- **TLS bind enforcement**: a non-loopback bind (`ARBOR_HOST` other than `127.0.0.1`/`::1`/`localhost`) requires TLS to be active. Arbor refuses to start in plain HTTP on a public interface.
+- **TLS bind enforcement**: a non-loopback bind (`ARBOR_HOST` other than `127.0.0.1`/`::1`/`localhost`) requires TLS to be active by default. Arbor refuses to start in plain HTTP on a public interface unless `ARBOR_ALLOW_PLAINTEXT=1` is set (opt-in escape hatch for VPN/private network deployments where the tunnel itself provides confidentiality).
 - **WebSocket origin**: a missing `Origin` header is accepted only when bound to loopback. On any public bind, the connecting `Origin` must be in `ARBOR_CORS_ORIGINS`.
 - **Security response headers**: a strict CSP (`script-src 'self'`, `object-src 'none'`, `frame-ancestors 'none'`), `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff`, `Referrer-Policy: strict-origin-when-cross-origin`. `/docs`, `/redoc`, and `/openapi.json` are disabled.
 

backend/arbor/csrf.py

@@ -30,12 +30,12 @@ def generate_csrf_token() -> str:
     return secrets.token_urlsafe(_TOKEN_BYTES)
 
 
-def set_csrf_cookie(response: Response, token: str) -> None:
+def set_csrf_cookie(response: Response, token: str, *, secure: bool = True) -> None:
     response.set_cookie(
         key=CSRF_COOKIE_NAME,
         value=token,
         httponly=False,
-        secure=True,
+        secure=secure,
         samesite="strict",
         max_age=session_ttl_seconds(),
         path="/",

backend/arbor/main.py

@@ -259,8 +259,9 @@ async def auth_login(request: Request):
             "step_up_method": session.get("step_up_method", ""),
         },
     )
-    set_session_cookie(response, session["session_id"])
-    set_csrf_cookie(response, generate_csrf_token())
+    _secure = getattr(getattr(request, "url", None), "scheme", "http") == "https"
+    set_session_cookie(response, session["session_id"], secure=_secure)
+    set_csrf_cookie(response, generate_csrf_token(), secure=_secure)
     return response
 
 

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/arbor/session.py

@@ -276,12 +276,12 @@ def session_from_cookie_header(cookie_header: str | None) -> str:
     return morsel.value if morsel is not None else ""
 
 
-def set_session_cookie(response: Response, session_id: str) -> None:
+def set_session_cookie(response: Response, session_id: str, *, secure: bool = True) -> None:
     response.set_cookie(
         key=session_cookie_name(),
         value=session_id,
         httponly=True,
-        secure=True,
+        secure=secure,
         samesite="strict",
         max_age=session_ttl_seconds(),
         path="/",

backend/tests/test_phase7_local_auth_foundation.py

@@ -17,11 +17,12 @@
 
 
 class FakeRequest:
-    def __init__(self, body=None, *, cookies=None, headers=None, client_host="127.0.0.1"):
+    def __init__(self, body=None, *, cookies=None, headers=None, client_host="127.0.0.1", scheme="http"):
         self._body = body
         self.cookies = cookies or {}
         self.headers = headers or {}
         self.client = SimpleNamespace(host=client_host)
+        self.url = SimpleNamespace(scheme=scheme)
 
     async def body(self):
         if self._body is None:

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