feat: trusted-proxy identity from Remote-User / X-Forwarded-User (#23)

When a request reaches the backend from an IP listed in
API_TRUSTED_PROXY_IPS and carries Remote-User (or X-Forwarded-User)
naming an active agent, the auth-gate accepts it without an
X-Agent-Key. This is the contract the gateway (Caddy → Authelia)
needs to hand off browser SSO identity to the API.

Behavior unchanged for X-Agent-Key clients and for requests from
untrusted source IPs — the proxy-identity path is only consulted
when the key header is absent.

Helpers:
- trusted_proxy_ips(): set parsed from API_TRUSTED_PROXY_IPS
- is_trusted_proxy_request(): client.host membership check
- normalize_proxy_user(): lowercase + email local-part fallback
- resolve_proxy_agent(): DB lookup for active agent by name

Replaces the abandoned feat/trusted-proxy-ips branch (3 weeks
behind main; deleted recently-merged permissions/coherence work
and conflated frontend StaticFiles serving with this work).
This change carries only the proxy-identity primitives; no
StaticFiles, no FileResponse — the SPA is now served by Caddy
from /var/www/delega and the backend stays API-only.

Tests: 6 cases in tests/test_trusted_proxy.py covering accept
(Remote-User, X-Forwarded-User, email form) and reject (untrusted
source IP, unknown user, inactive agent). Full suite: 56 passed.

Co-authored-by: Marty (Clawdbot) <marty@mcmillan.io>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

backend/main.py

@@ -42,6 +42,12 @@ def env_flag(name: str, default: bool) -> bool:
     if o.strip()
 ]
 
+
+def trusted_proxy_ips() -> set[str]:
+    raw = os.environ.get("API_TRUSTED_PROXY_IPS", "")
+    return {term.strip() for term in raw.split(",") if term.strip()}
+
+
 from apscheduler.schedulers.background import BackgroundScheduler
 
 from database import engine, get_db, SessionLocal, Base
@@ -275,6 +281,40 @@ def require_localhost_target(request: Request, detail: str) -> None:
     raise HTTPException(status_code=403, detail=detail)
 
 
+def is_trusted_proxy_request(request: Request) -> bool:
+    client_host = request.client.host if request.client else ""
+    if not client_host:
+        return False
+    return client_host in trusted_proxy_ips()
+
+
+def normalize_proxy_user(raw_value: Optional[str]) -> list[str]:
+    if not raw_value:
+        return []
+    value = raw_value.strip().lower()
+    if not value:
+        return []
+    candidates = [value]
+    if "@" in value:
+        local_part = value.split("@", 1)[0]
+        if local_part and local_part not in candidates:
+            candidates.append(local_part)
+    return candidates
+
+
+def resolve_proxy_agent(db: Session, request: Request) -> Optional[models.Agent]:
+    if not is_trusted_proxy_request(request):
+        return None
+    proxy_user = request.headers.get("Remote-User") or request.headers.get("X-Forwarded-User")
+    candidates = normalize_proxy_user(proxy_user)
+    if not candidates:
+        return None
+    return db.query(models.Agent).filter(
+        models.Agent.active == True,
+        models.Agent.name.in_(candidates),
+    ).first()
+
+
 def is_initial_agent_bootstrap_request(request: Request) -> bool:
     return request.method.upper() == "POST" and request.url.path == "/api/agents"
 
@@ -499,6 +539,19 @@ async def auth_gate_middleware(request: Request, call_next):
     if not x_agent_key:
         if REQUIRE_AUTH and allow_initial_agent_bootstrap(request):
             return await call_next(request)
+        db = SessionLocal()
+        try:
+            agent = resolve_proxy_agent(db, request)
+            if agent:
+                agent.last_seen_at = datetime.now(timezone.utc)
+                db.commit()
+                request.state.current_agent_id = agent.id
+                return await call_next(request)
+        except Exception as exc:
+            db.rollback()
+            logger.error("Trusted-proxy resolution error: %s", exc)
+        finally:
+            db.close()
         if REQUIRE_AUTH:
             return JSONResponse(
                 status_code=401,

backend/tests/test_trusted_proxy.py

@@ -0,0 +1,166 @@
+"""Tests for the trusted-proxy / Remote-User auth path.
+
+When a request arrives from an IP listed in API_TRUSTED_PROXY_IPS and
+carries a Remote-User (or X-Forwarded-User) header naming an active
+agent, the auth-gate middleware accepts it without an X-Agent-Key.
+This is the contract that lets Authelia (in front of Caddy) hand off
+identity to the backend on behalf of browser SSO sessions.
+
+Untrusted source IPs sending the same header must be rejected.
+"""
+
+import os
+import sys
+import pytest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+os.environ["DELEGA_REQUIRE_AUTH"] = "true"
+os.environ["DELEGA_DB_PATH"] = ":memory:"
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+from fastapi.testclient import TestClient
+
+import main
+import models
+from main import app, get_db, derive_key_hash, derive_key_lookup
+
+
+@pytest.fixture(autouse=True)
+def fresh_db(tmp_path):
+    db_path = str(tmp_path / "test.db")
+    test_engine = create_engine(
+        f"sqlite:///{db_path}",
+        connect_args={"check_same_thread": False},
+    )
+    models.Base.metadata.create_all(bind=test_engine)
+    TestSession = sessionmaker(autocommit=False, autoflush=False, bind=test_engine)
+
+    def override_get_db():
+        db = TestSession()
+        try:
+            yield db
+        finally:
+            db.close()
+
+    app.dependency_overrides[get_db] = override_get_db
+    _orig = main.SessionLocal
+    main.SessionLocal = TestSession
+    main._rate_limiter._hits.clear()
+
+    yield test_engine
+
+    main.SessionLocal = _orig
+    app.dependency_overrides.clear()
+
+
+def make_agent(engine, name: str):
+    import secrets as _secrets
+    raw_key = "dlg_" + _secrets.token_urlsafe(32)
+    salt = _secrets.token_hex(16)
+    Session = sessionmaker(bind=engine)
+    db = Session()
+    agent = models.Agent(
+        name=name,
+        api_key=raw_key,
+        key_hash=derive_key_hash(raw_key, salt),
+        key_salt=salt,
+        key_lookup=derive_key_lookup(raw_key),
+        is_admin=False,
+        permissions=[],
+        active=True,
+    )
+    db.add(agent)
+    db.commit()
+    db.refresh(agent)
+    db.close()
+    return agent.name
+
+
+class TestTrustedProxyIdentity:
+    def test_remote_user_from_trusted_proxy_authenticates(self, fresh_db, monkeypatch):
+        agent_name = make_agent(fresh_db, "marty")
+        monkeypatch.setenv("API_TRUSTED_PROXY_IPS", "192.168.10.220,127.0.0.1")
+        client = TestClient(
+            app, base_url="http://localhost", client=("192.168.10.220", 50001)
+        )
+        try:
+            r = client.get("/api/tasks", headers={"Remote-User": agent_name})
+            assert r.status_code == 200, r.text
+        finally:
+            client.close()
+
+    def test_x_forwarded_user_also_accepted(self, fresh_db, monkeypatch):
+        agent_name = make_agent(fresh_db, "doc")
+        monkeypatch.setenv("API_TRUSTED_PROXY_IPS", "192.168.10.220")
+        client = TestClient(
+            app, base_url="http://localhost", client=("192.168.10.220", 50002)
+        )
+        try:
+            r = client.get("/api/tasks", headers={"X-Forwarded-User": agent_name})
+            assert r.status_code == 200, r.text
+        finally:
+            client.close()
+
+    def test_email_form_resolves_to_local_part(self, fresh_db, monkeypatch):
+        make_agent(fresh_db, "biff")
+        monkeypatch.setenv("API_TRUSTED_PROXY_IPS", "192.168.10.220")
+        client = TestClient(
+            app, base_url="http://localhost", client=("192.168.10.220", 50003)
+        )
+        try:
+            r = client.get("/api/tasks", headers={"Remote-User": "biff@mcmillan.io"})
+            assert r.status_code == 200, r.text
+        finally:
+            client.close()
+
+    def test_untrusted_source_ip_is_rejected(self, fresh_db, monkeypatch):
+        make_agent(fresh_db, "george")
+        monkeypatch.setenv("API_TRUSTED_PROXY_IPS", "192.168.10.220")
+        client = TestClient(
+            app, base_url="http://localhost", client=("192.168.10.221", 50004)
+        )
+        try:
+            r = client.get("/api/tasks", headers={"Remote-User": "george"})
+            assert r.status_code == 401
+        finally:
+            client.close()
+
+    def test_unknown_user_from_trusted_proxy_is_rejected(self, fresh_db, monkeypatch):
+        monkeypatch.setenv("API_TRUSTED_PROXY_IPS", "192.168.10.220")
+        client = TestClient(
+            app, base_url="http://localhost", client=("192.168.10.220", 50005)
+        )
+        try:
+            r = client.get("/api/tasks", headers={"Remote-User": "ghost"})
+            assert r.status_code == 401
+        finally:
+            client.close()
+
+    def test_inactive_agent_from_trusted_proxy_is_rejected(self, fresh_db, monkeypatch):
+        Session = sessionmaker(bind=fresh_db)
+        db = Session()
+        agent = models.Agent(
+            name="strickland",
+            api_key="dlg_xx",
+            key_hash="x",
+            key_salt="x",
+            key_lookup="x",
+            is_admin=False,
+            permissions=[],
+            active=False,
+        )
+        db.add(agent)
+        db.commit()
+        db.close()
+        monkeypatch.setenv("API_TRUSTED_PROXY_IPS", "192.168.10.220")
+        client = TestClient(
+            app, base_url="http://localhost", client=("192.168.10.220", 50006)
+        )
+        try:
+            r = client.get("/api/tasks", headers={"Remote-User": "strickland"})
+            assert r.status_code == 401
+        finally:
+            client.close()