Merge branch 'main' into update_redis

Author: Ad1th

README.md

@@ -88,6 +88,14 @@ Or add it directly to your Claude Desktop config (`claude_desktop_config.json`):
 
 This exposes 3 tools to your AI agent: `check_message_safety`, `get_session_risk`, and `list_recent_escalations`.
 
+For HTTP MCP, the server binds to `127.0.0.1` by default. If you expose it
+beyond localhost, set a bearer token first:
+
+```bash
+export HUMANE_PROXY_ADMIN_KEY=your-secret-token
+humane-proxy mcp-serve --transport http --host 0.0.0.0 --port 3000
+```
+
 ---
 
 ## Available On
@@ -441,16 +449,27 @@ curl -X DELETE http://localhost:8000/admin/sessions/user-42 \
 ```bash
 pip install humane-proxy[mcp]
 humane-proxy mcp-serve                         # stdio (default)
-humane-proxy mcp-serve --transport http --port 3000  # HTTP
+humane-proxy mcp-serve --transport http --port 3000  # HTTP on 127.0.0.1
 ```
 
+HTTP MCP is local-only by default. To bind publicly, pass `--host 0.0.0.0`
+explicitly and protect tool access with a bearer token:
+
+```bash
+export HUMANE_PROXY_ADMIN_KEY=your-secret-token
+humane-proxy mcp-serve --transport http --host 0.0.0.0 --port 3000
+```
+
+Clients must send `Authorization: Bearer your-secret-token` when the token is
+configured. Leave `HUMANE_PROXY_ADMIN_KEY` unset for stdio/local-only MCP.
+
 Exposes three tools via Model Context Protocol:
 
 | Tool | Description |
 |---|---|
 | `check_message_safety` | Full pipeline classification |
-| `get_session_risk` | Session trajectory (trend, spike, category counts) |
-| `list_recent_escalations` | Audit log query |
+| `get_session_risk` | Read-only session trajectory snapshot (trend, spike, category counts) |
+| `list_recent_escalations` | Bounded audit log query |
 
 Available on the [Official MCP Registry](https://registry.modelcontextprotocol.io).
 

humane_proxy/api/admin.py

@@ -19,6 +19,7 @@
 from __future__ import annotations
 
 import csv
+import hmac
 import io
 import json
 import logging
@@ -28,7 +29,7 @@
 from datetime import datetime, timezone
 from typing import Any
 
-from fastapi import APIRouter, Depends, HTTPException, Query
+from fastapi import APIRouter, Depends, HTTPException, Query, Response
 from fastapi.responses import StreamingResponse
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 
@@ -60,7 +61,7 @@ def _require_admin(
                 "environment variable to enable it."
             ),
         )
-    if credentials is None or credentials.credentials != admin_key:
+    if credentials is None or not hmac.compare_digest(credentials.credentials, admin_key):
         raise HTTPException(
             status_code=401,
             detail="Invalid or missing Bearer token.",
@@ -298,32 +299,21 @@ def get_session_risk(
     finally:
         conn.close()
 
-    from humane_proxy.risk.trajectory import analyze
+    from humane_proxy.risk.trajectory import snapshot
 
-    # Build trajectory by replaying each escalation.
-    trajectory = None
-    for row in rows:
-        rec = _row_to_dict(row)
-        trajectory = analyze(
-            session_id + "_admin_replay",  # isolated session key
-            rec["risk_score"],
-            rec.get("category", "safe"),
-        )
+    trajectory = snapshot(session_id)
 
     return {
         "session_id": session_id,
         "escalation_count": len(rows),
         "history": [_row_to_dict(r) for r in rows],
-        "trajectory": (
-            {
-                "spike_detected": trajectory.spike_detected,
-                "trend": trajectory.trend,
-                "window_scores": trajectory.window_scores,
-                "category_counts": trajectory.category_counts,
-            }
-            if trajectory
-            else None
-        ),
+        "trajectory": {
+            "spike_detected": trajectory.spike_detected,
+            "trend": trajectory.trend,
+            "window_scores": trajectory.window_scores,
+            "category_counts": trajectory.category_counts,
+            "message_count": trajectory.message_count,
+        },
     }
 
 
@@ -381,11 +371,11 @@ def get_stats(_: str = Depends(_require_admin)) -> dict:
     }
 
 
-@router.delete("/sessions/{session_id}", status_code=204)
+@router.delete("/sessions/{session_id}", status_code=204, response_class=Response)
 def delete_session_data(
     session_id: str,
     _: str = Depends(_require_admin),
-) -> None:
+) -> Response:
     """Delete all escalation records for a session (privacy right to erasure)."""
     conn = _get_conn()
     try:
@@ -397,3 +387,4 @@ def delete_session_data(
         conn.close()
 
     logger.info("Deleted %d records for session %s (admin request)", deleted, session_id)
+    return Response(status_code=204)

humane_proxy/cli.py

@@ -555,13 +555,14 @@ async def _run_all():
 @click.option("--transport", "-t", default="stdio",
               type=click.Choice(["stdio", "http"]),
               help="Transport mode: stdio (default) or http")
-@click.option("--host", default="0.0.0.0", help="HTTP bind host (default: 0.0.0.0)")
+@click.option("--host", default="127.0.0.1", help="HTTP bind host (default: 127.0.0.1)")
 @click.option("--port", "-p", default=3000, type=int, help="HTTP bind port (default: 3000)")
 def mcp_serve(transport: str, host: str, port: int) -> None:
     """Start the MCP server (requires [mcp] extra).
 
     Use --transport stdio (default) for local integration with agents.
-    Use --transport http for remote access and registry listing.
+    Use --transport http for HTTP access. Set HUMANE_PROXY_ADMIN_KEY
+    before exposing HTTP MCP beyond localhost.
     """
     try:
         if transport == "http":

humane_proxy/escalation/query.py

@@ -0,0 +1,29 @@
+"""Shared escalation query validation helpers."""
+
+from __future__ import annotations
+
+ALLOWED_ESCALATION_CATEGORIES = frozenset({"self_harm", "criminal_intent"})
+DEFAULT_ESCALATION_LIMIT = 20
+MAX_ESCALATION_LIMIT = 100
+
+
+def normalize_escalation_query(
+    limit: int = DEFAULT_ESCALATION_LIMIT,
+    category: str | None = None,
+) -> tuple[int, str | None]:
+    """Clamp escalation query size and validate optional category filters."""
+    try:
+        normalized_limit = int(limit)
+    except (TypeError, ValueError):
+        normalized_limit = DEFAULT_ESCALATION_LIMIT
+
+    normalized_limit = max(1, min(normalized_limit, MAX_ESCALATION_LIMIT))
+    normalized_category = category.strip() if isinstance(category, str) else None
+    if normalized_category == "":
+        normalized_category = None
+
+    if normalized_category and normalized_category not in ALLOWED_ESCALATION_CATEGORIES:
+        allowed = ", ".join(sorted(ALLOWED_ESCALATION_CATEGORIES))
+        raise ValueError(f"category must be one of: {allowed}")
+
+    return normalized_limit, normalized_category

humane_proxy/integrations/autogen.py

@@ -59,16 +59,9 @@ def get_session_risk(session_id: str) -> str:
     Returns:
         JSON string with spike detection, trend, and category distribution.
     """
-    from humane_proxy.risk.trajectory import analyze
+    from humane_proxy.risk.trajectory import snapshot, to_dict
 
-    result = analyze(session_id, 0.0, "safe")
-    return json.dumps({
-        "spike_detected": result.spike_detected,
-        "trend": result.trend,
-        "window_scores": result.window_scores,
-        "category_counts": result.category_counts,
-        "message_count": result.message_count,
-    }, indent=2)
+    return json.dumps(to_dict(snapshot(session_id)), indent=2)
 
 
 def list_recent_escalations(limit: int = 20, category: str = "") -> str:
@@ -81,11 +74,13 @@ def list_recent_escalations(limit: int = 20, category: str = "") -> str:
     Returns:
         JSON string with list of escalation records.
     """
+    from humane_proxy.escalation.query import normalize_escalation_query
     from humane_proxy.storage.factory import get_store
 
+    limit, category = normalize_escalation_query(limit, category)
     store = get_store()
     results = store.query(
-        category=category if category else None,
+        category=category,
         limit=limit,
     )
     return json.dumps(results, indent=2, default=str)

humane_proxy/integrations/crewai.py

@@ -94,30 +94,25 @@ class GetSessionRiskTool(BaseTool):
         args_schema: Type[BaseModel] = SessionRiskInput
 
         def _run(self, session_id: str) -> str:
-            from humane_proxy.risk.trajectory import analyze
+            from humane_proxy.risk.trajectory import snapshot, to_dict
             import json
 
-            result = analyze(session_id, 0.0, "safe")
-            return json.dumps({
-                "spike_detected": result.spike_detected,
-                "trend": result.trend,
-                "window_scores": result.window_scores,
-                "category_counts": result.category_counts,
-                "message_count": result.message_count,
-            }, indent=2)
+            return json.dumps(to_dict(snapshot(session_id)), indent=2)
 
     class ListEscalationsTool(BaseTool):
         name: str = "list_recent_escalations"
         description: str = "Query recent escalation events from the safety audit log."
         args_schema: Type[BaseModel] = ListEscalationsInput
 
         def _run(self, limit: int = 20, category: str = "") -> str:
+            from humane_proxy.escalation.query import normalize_escalation_query
             from humane_proxy.storage.factory import get_store
             import json
 
+            limit, category = normalize_escalation_query(limit, category)
             store = get_store()
             results = store.query(
-                category=category if category else None,
+                category=category,
                 limit=limit,
             )
             return json.dumps(results, indent=2, default=str)

humane_proxy/integrations/llamaindex.py

@@ -56,16 +56,9 @@ def _get_session_risk(session_id: str) -> dict:
     dict
         ``{"spike_detected": bool, "trend": str, "window_scores": list, ...}``
     """
-    from humane_proxy.risk.trajectory import analyze
+    from humane_proxy.risk.trajectory import snapshot, to_dict
 
-    result = analyze(session_id, 0.0, "safe")
-    return {
-        "spike_detected": result.spike_detected,
-        "trend": result.trend,
-        "window_scores": result.window_scores,
-        "category_counts": result.category_counts,
-        "message_count": result.message_count,
-    }
+    return to_dict(snapshot(session_id))
 
 
 def _list_recent_escalations(limit: int = 20, category: str | None = None) -> list[dict]:
@@ -83,8 +76,10 @@ def _list_recent_escalations(limit: int = 20, category: str | None = None) -> li
     list[dict]
         List of escalation records.
     """
+    from humane_proxy.escalation.query import normalize_escalation_query
     from humane_proxy.storage.factory import get_store
 
+    limit, category = normalize_escalation_query(limit, category)
     store = get_store()
     return store.query(category=category, limit=limit)