feat: add public demo mode

Author: stephenh67

README.md

@@ -121,6 +121,7 @@ python helix_code/live_demo_server.py
 - Audit dashboard endpoints: `GET /audit-dashboard` and `GET /api/audit-dashboard`
 - Optional operator auth: `HELIX_ADMIN_TOKEN` for runtime, security, dashboard, and receipt surfaces
 - Recommended production operator posture: set `HELIX_ADMIN_TOKEN` and `HELIX_ENFORCE_ADMIN_TOKEN=true`
+- Hackathon/demo posture: set `HELIX_PUBLIC_DEMO=true` to open only `/` and `/demo-live` while keeping operator surfaces under admin auth
 - Recommended production throttling posture: keep operator APIs on `HELIX_OPERATOR_RATE_LIMIT_MAX_REQUESTS=120` / `HELIX_OPERATOR_RATE_LIMIT_WINDOW_SECONDS=60` and audio ingress on `HELIX_AUDIO_INGRESS_MAX_CONNECTIONS=12` / `HELIX_AUDIO_INGRESS_RATE_LIMIT_WINDOW_SECONDS=60` unless measured load requires adjustment
 - Recommended production browser posture: set `HELIX_ALLOWED_ORIGINS` to the exact trusted UI origins; otherwise Guardian WebSockets default to same-origin-only in production
 - Optional durable receipt envs: `HELIX_RECEIPT_PERSISTENCE`, `HELIX_RECEIPT_STORE_PATH`, `GCS_RECEIPT_BUCKET`

helix_code/live_guardian.py

@@ -529,6 +529,11 @@ def _admin_auth_enabled() -> bool:
     return bool(_configured_admin_token()) or _env_flag("HELIX_ENFORCE_ADMIN_TOKEN")
 
 
+def _public_demo_enabled() -> bool:
+    """[FACT] Optional public demo mode opens only the hackathon demo surface."""
+    return _env_flag("HELIX_PUBLIC_DEMO")
+
+
 def _require_admin_token(request: Request) -> str:
     """[FACT] Enforce admin auth on protected request handlers."""
     required_token = _configured_admin_token()
@@ -640,6 +645,7 @@ def _runtime_config_snapshot() -> dict[str, Any]:
             "audio_audit_allowed_origins": allowed_origins,
             "admin_token_required": bool(resolve_admin_token(refresh=True)),
             "admin_token_enforced": _env_flag("HELIX_ENFORCE_ADMIN_TOKEN"),
+            "public_demo_enabled": _public_demo_enabled(),
             "guardian_allowed_origins": _guardian_allowed_origins(),
             "guardian_origin_enforced": _guardian_origin_enforced(),
         },
@@ -1207,15 +1213,18 @@ async def health_check() -> JSONResponse:
 @app.get("/", response_class=HTMLResponse)
 async def root(request: Request) -> HTMLResponse:
     """[FACT] Root endpoint serves the interactive demo dashboard."""
-    gate = _guard_html_page(request, "/")
-    if isinstance(gate, HTMLResponse):
-        return gate
+    gate: str | HTMLResponse = ""
+    if not _public_demo_enabled():
+        gate = _guard_html_page(request, "/")
+        if isinstance(gate, HTMLResponse):
+            return gate
 
     # Import demo HTML from live_demo_server_html
     from live_demo_server_html import DEMO_HTML
 
     response = HTMLResponse(content=DEMO_HTML)
-    _set_admin_session_cookie(response, request, gate)
+    if gate:
+        _set_admin_session_cookie(response, request, gate)
     return response
 
 

helix_code/tests/test_live_guardian_extended.py

@@ -526,6 +526,32 @@ def test_audit_dashboard_page_returns_login_form_when_token_missing(self, monkey
             assert response.status_code == 401
             assert "Admin Access Required" in response.text
 
+    def test_root_demo_page_can_be_public_when_enabled(self, monkeypatch) -> None:
+        """[FACT] Public demo mode opens only the root demo surface."""
+        monkeypatch.setenv("HELIX_ADMIN_TOKEN", "secret-token")
+        monkeypatch.setenv("HELIX_PUBLIC_DEMO", "true")
+
+        with TestClient(app) as client:
+            response = client.get("/")
+
+        assert response.status_code == 200
+        assert "CONSTITUTIONAL GUARDIAN" in response.text
+        assert "LIVE v1.4.8" in response.text
+
+    def test_runtime_config_reports_public_demo_flag(self, monkeypatch) -> None:
+        """[FACT] Runtime config reports whether public demo mode is enabled."""
+        monkeypatch.setenv("HELIX_ADMIN_TOKEN", "secret-token")
+        monkeypatch.setenv("HELIX_PUBLIC_DEMO", "true")
+
+        with TestClient(app) as client:
+            response = client.get(
+                "/api/runtime-config",
+                headers={"X-Helix-Admin-Token": "secret-token"},
+            )
+
+        assert response.status_code == 200
+        assert response.json()["auth"]["public_demo_enabled"] is True
+
     def test_receipts_api_accepts_custom_admin_header(self, monkeypatch) -> None:
         """[FACT] Receipts API accepts custom admin header."""
         monkeypatch.setenv("HELIX_ADMIN_TOKEN", "secret-token")