@purpleraven/hits 0.2.0

package/hits_core/api/server.py

@@ -0,0 +1,181 @@
+"""FastAPI application factory with security middleware and web UI serving.
+
+Security features:
+- Argon2id password hashing (or HMAC-SHA256 fallback)
+- JWT access/refresh tokens in HttpOnly cookies
+- Content-Security-Policy (CSP) headers
+- CORS with strict origin validation
+- Rate limiting on authentication endpoints
+- Secure response headers (HSTS, X-Frame-Options, etc.)
+- Input validation via Pydantic v2
+"""
+
+import asyncio
+import os
+import threading
+from pathlib import Path
+from typing import Optional
+
+from fastapi import FastAPI, Request, status
+from fastapi.responses import HTMLResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from starlette.middleware.cors import CORSMiddleware
+
+from .routes import health, work_log, node, handover, auth, knowledge
+from ..auth.middleware import SecurityMiddleware
+
+
+# --- Rate Limiter (simple in-memory) ---
+
+class RateLimiter:
+    """Simple in-memory rate limiter for authentication endpoints."""
+
+    def __init__(self, max_requests: int = 10, window_seconds: int = 60):
+        self.max_requests = max_requests
+        self.window_seconds = window_seconds
+        self._requests: dict[str, list[float]] = {}
+        self._lock = asyncio.Lock() if asyncio.get_event_loop().is_running() else None
+
+    def is_limited(self, client_id: str) -> bool:
+        """Check if client is rate limited. Returns True if limited."""
+        import time
+        now = time.time()
+
+        if client_id not in self._requests:
+            self._requests[client_id] = []
+
+        # Remove old entries
+        self._requests[client_id] = [
+            t for t in self._requests[client_id]
+            if now - t < self.window_seconds
+        ]
+
+        if len(self._requests[client_id]) >= self.max_requests:
+            return True
+
+        self._requests[client_id].append(now)
+        return False
+
+
+_rate_limiter = RateLimiter(max_requests=10, window_seconds=60)
+
+
+class APIServer:
+    def __init__(self, port: int = 8765, dev_mode: bool = False):
+        self.port = port
+        self.dev_mode = dev_mode
+        self.app: Optional[FastAPI] = None
+        self.server = None
+        self.thread: Optional[threading.Thread] = None
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+
+    def create_app(self) -> FastAPI:
+        app = FastAPI(
+            title="HITS API",
+            description="Hybrid Intel Trace System - Secure Web UI",
+            version="0.2.0",
+        )
+
+        # --- Security Middleware ---
+        app.add_middleware(SecurityMiddleware, dev_mode=self.dev_mode)
+
+        # --- CORS ---
+        if self.dev_mode:
+            app.add_middleware(
+                CORSMiddleware,
+                allow_origins=["http://localhost:5173", "http://127.0.0.1:5173"],
+                allow_credentials=True,
+                allow_methods=["*"],
+                allow_headers=["*"],
+            )
+
+        # --- Rate Limiting for Auth ---
+        @app.middleware("http")
+        async def rate_limit_auth(request: Request, call_next):
+            if request.url.path.startswith("/api/auth/login"):
+                client_id = request.client.host if request.client else "unknown"
+                if _rate_limiter.is_limited(client_id):
+                    return JSONResponse(
+                        status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                        content={"detail": "Too many login attempts. Try again later."},
+                    )
+            return await call_next(request)
+
+        # --- API Routes ---
+        app.include_router(health.router, prefix="/api", tags=["health"])
+        app.include_router(auth.router, prefix="/api", tags=["auth"])
+        app.include_router(work_log.router, prefix="/api", tags=["work-log"])
+        app.include_router(node.router, prefix="/api", tags=["node"])
+        app.include_router(handover.router, prefix="/api", tags=["handover"])
+        app.include_router(knowledge.router, prefix="/api", tags=["knowledge"])
+
+        # --- Static Files (Web UI) ---
+        static_dir = Path(__file__).parent.parent.parent / "hits_web" / "dist"
+        if static_dir.exists():
+            # Mount static assets
+            assets_dir = static_dir / "assets"
+            if assets_dir.exists():
+                app.mount("/assets", StaticFiles(directory=str(assets_dir)), name="assets")
+
+            # SPA fallback: serve index.html for all non-API, non-static routes
+            index_html = static_dir / "index.html"
+
+            @app.get("/{path:path}", response_class=HTMLResponse, include_in_schema=False)
+            async def spa_fallback(path: str):
+                """Serve the SPA index.html for all non-API routes."""
+                # Try to serve a specific static file first
+                file_path = static_dir / path
+                if path and file_path.exists() and file_path.is_file():
+                    from fastapi.responses import FileResponse
+                    return FileResponse(file_path)
+                # Otherwise serve index.html (SPA routing)
+                if index_html.exists():
+                    return HTMLResponse(content=index_html.read_text(encoding="utf-8"))
+                return HTMLResponse(content="<h1>HITS Web UI not built yet. Run: cd hits_web && npm run build</h1>")
+
+        return app
+
+    def _run_server(self):
+        self._loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(self._loop)
+
+        import uvicorn
+        config = uvicorn.Config(
+            app=self.app,
+            host="127.0.0.1",
+            port=self.port,
+            loop="asyncio",
+            log_level="warning" if not self.dev_mode else "info",
+        )
+        self.server = uvicorn.Server(config)
+        self._loop.run_until_complete(self.server.serve())
+
+    def start(self):
+        if self.thread and self.thread.is_alive():
+            return
+
+        self.app = self.create_app()
+        self.thread = threading.Thread(target=self._run_server, daemon=True)
+        self.thread.start()
+
+    def stop(self):
+        if self.server and self._loop:
+            self._loop.call_soon_threadsafe(self.server.should_exit)
+
+
+_api_server: Optional[APIServer] = None
+
+
+def start_api_server(port: int = 8765, dev_mode: bool = False) -> APIServer:
+    global _api_server
+    if _api_server is None:
+        _api_server = APIServer(port=port, dev_mode=dev_mode)
+        _api_server.start()
+    return _api_server
+
+
+def stop_api_server():
+    global _api_server
+    if _api_server:
+        _api_server.stop()
+        _api_server = None

package/hits_core/auth/__init__.py

@@ -0,0 +1,21 @@
+"""Authentication and security package for HITS web UI.
+
+Security design:
+- Argon2id password hashing (PHC winner, resistant to GPU/ASIC attacks)
+- JWT with HttpOnly + Secure + SameSite=Lax cookies (no localStorage)
+- Short-lived access tokens (15 min) + long-lived refresh tokens (7 days)
+- Rate limiting on auth endpoints
+- CSRF protection via SameSite cookies + origin validation
+"""
+
+from .manager import AuthManager, get_auth_manager
+from .middleware import SecurityMiddleware
+from .dependencies import get_current_user, require_auth
+
+__all__ = [
+    "AuthManager",
+    "get_auth_manager",
+    "SecurityMiddleware",
+    "get_current_user",
+    "require_auth",
+]

package/hits_core/auth/dependencies.py

@@ -0,0 +1,61 @@
+"""FastAPI dependencies for authentication.
+
+Usage in routes:
+    @router.get("/protected")
+    async def protected_route(user: dict = Depends(require_auth)):
+        username = user["username"]
+        ...
+
+    @router.get("/optional")
+    async def optional_route(user: Optional[dict] = Depends(get_current_user)):
+        if user:
+            # authenticated
+        else:
+            # anonymous
+"""
+
+from typing import Optional
+
+from fastapi import Depends, HTTPException, Request, status
+
+from .manager import get_auth_manager
+
+
+async def get_current_user(request: Request) -> Optional[dict]:
+    """Extract and verify user from access token cookie.
+
+    Returns user dict or None if not authenticated.
+    """
+    token = request.cookies.get("access_token")
+    if not token:
+        # Also check Authorization header for API clients
+        auth_header = request.headers.get("Authorization", "")
+        if auth_header.startswith("Bearer "):
+            token = auth_header[7:]
+
+    if not token:
+        return None
+
+    auth = get_auth_manager()
+    return auth.verify_access_token(token)
+
+
+async def require_auth(user: Optional[dict] = Depends(get_current_user)) -> dict:
+    """Require authentication. Raises 401 if not authenticated."""
+    if user is None:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Authentication required",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    return user
+
+
+async def require_admin(user: dict = Depends(require_auth)) -> dict:
+    """Require admin role."""
+    if user.get("role") != "admin":
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Admin access required",
+        )
+    return user

package/hits_core/auth/manager.py

@@ -0,0 +1,368 @@
+"""Authentication manager - JWT + Argon2id password hashing.
+
+Security choices:
+- Argon2id: Winner of Password Hashing Competition (2015).
+  Resistant to GPU, ASIC, and side-channel attacks.
+  Parameters: memory=64MB, iterations=3, parallelism=1.
+- JWT HS256: Symmetric signing for simplicity in single-server setup.
+  Access token: 15 minutes. Refresh token: 7 days.
+- HttpOnly cookies: Not accessible to JavaScript (XSS protection).
+  Secure flag: Only sent over HTTPS (set False only for localhost dev).
+  SameSite=Lax: CSRF protection while allowing top-level navigations.
+"""
+
+import json
+import os
+import secrets
+import hashlib
+import hmac
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Optional
+
+# Argon2id - fallback to bcrypt if not available
+try:
+    from argon2 import PasswordHasher
+    from argon2.exceptions import VerifyMismatchError
+
+    _HAS_ARGON2 = True
+except ImportError:
+    import hashlib as _hl
+
+    _HAS_ARGON2 = False
+
+# JWT - use python-jose if available, else pure Python HMAC-based tokens
+try:
+    from jose import jwt, JWTError
+
+    _HAS_JOSE = True
+except ImportError:
+    _HAS_JOSE = False
+
+
+class PasswordHasher:
+    """Password hashing with Argon2id (preferred) or HMAC-SHA256 fallback."""
+
+    def __init__(self):
+        self._argon2: Optional["PasswordHasher"] = None
+        self._pepper: bytes = b""
+        self._load_pepper()
+
+        if _HAS_ARGON2:
+            self._argon2 = PasswordHasher(
+                time_cost=3,        # iterations
+                memory_cost=65536,  # 64 MB
+                parallelism=1,
+                hash_len=32,
+                salt_len=16,
+            )
+
+    def _load_pepper(self):
+        """Load or generate pepper for HMAC fallback."""
+        pepper_path = Path.home() / ".hits" / ".pepper"
+        pepper_path.parent.mkdir(parents=True, exist_ok=True)
+
+        if pepper_path.exists():
+            self._pepper = pepper_path.read_bytes()
+        else:
+            self._pepper = secrets.token_bytes(32)
+            # Restrict permissions to owner only
+            pepper_path.write_bytes(self._pepper)
+            os.chmod(pepper_path, 0o600)
+
+    def hash_password(self, password: str) -> str:
+        """Hash a password. Returns hash string."""
+        if self._argon2:
+            return self._argon2.hash(password)
+        else:
+            # Fallback: HMAC-SHA256 with pepper + random salt
+            salt = secrets.token_hex(16)
+            h = hmac.new(self._pepper, (salt + password).encode(), hashlib.sha256).hexdigest()
+            return f"hmac${salt}${h}"
+
+    def verify_password(self, password: str, hash_str: str) -> bool:
+        """Verify a password against a hash."""
+        if self._argon2 and not hash_str.startswith("hmac$"):
+            try:
+                self._argon2.verify(hash_str, password)
+                return True
+            except VerifyMismatchError:
+                return False
+            except Exception:
+                return False
+        elif hash_str.startswith("hmac$"):
+            parts = hash_str.split("$")
+            if len(parts) != 3:
+                return False
+            salt = parts[1]
+            expected = parts[2]
+            h = hmac.new(self._pepper, (salt + password).encode(), hashlib.sha256).hexdigest()
+            return hmac.compare_digest(h, expected)
+        return False
+
+
+class TokenManager:
+    """JWT token management with HttpOnly cookie support."""
+
+    def __init__(self, secret_key: Optional[str] = None):
+        self._secret = secret_key or self._load_or_create_secret()
+
+    def _load_or_create_secret(self) -> str:
+        """Load or create a persistent JWT secret key."""
+        key_path = Path.home() / ".hits" / ".jwt_secret"
+        key_path.parent.mkdir(parents=True, exist_ok=True)
+
+        if key_path.exists():
+            return key_path.read_text().strip()
+        else:
+            secret = secrets.token_urlsafe(48)
+            key_path.write_text(secret)
+            os.chmod(key_path, 0o600)
+            return secret
+
+    def create_access_token(self, username: str, expires_minutes: int = 15) -> str:
+        """Create a short-lived access token."""
+        payload = {
+            "sub": username,
+            "type": "access",
+            "iat": datetime.now(timezone.utc),
+            "exp": datetime.now(timezone.utc) + timedelta(minutes=expires_minutes),
+            "jti": secrets.token_urlsafe(16),
+        }
+        if _HAS_JOSE:
+            return jwt.encode(payload, self._secret, algorithm="HS256")
+        else:
+            return self._encode_simple(payload)
+
+    def create_refresh_token(self, username: str, expires_days: int = 7) -> str:
+        """Create a long-lived refresh token."""
+        payload = {
+            "sub": username,
+            "type": "refresh",
+            "iat": datetime.now(timezone.utc),
+            "exp": datetime.now(timezone.utc) + timedelta(days=expires_days),
+            "jti": secrets.token_urlsafe(16),
+        }
+        if _HAS_JOSE:
+            return jwt.encode(payload, self._secret, algorithm="HS256")
+        else:
+            return self._encode_simple(payload)
+
+    def verify_token(self, token: str, expected_type: str = "access") -> Optional[dict]:
+        """Verify and decode a token. Returns payload or None."""
+        try:
+            if _HAS_JOSE:
+                payload = jwt.decode(token, self._secret, algorithms=["HS256"])
+            else:
+                payload = self._decode_simple(token)
+
+            if payload.get("type") != expected_type:
+                return None
+            return payload
+        except Exception:
+            return None
+
+    def _encode_simple(self, payload: dict) -> str:
+        """Simple HMAC-based token encoding (fallback without jose)."""
+        import base64
+
+        header = base64.urlsafe_b64encode(b'{"alg":"HS256","typ":"JWT"}').decode().rstrip("=")
+        body = base64.urlsafe_b64encode(
+            json.dumps(payload, default=str).encode()
+        ).decode().rstrip("=")
+
+        signing_input = f"{header}.{body}"
+        sig = hmac.new(
+            self._secret.encode(), signing_input.encode(), hashlib.sha256
+        ).hexdigest()
+
+        return f"{signing_input}.{sig}"
+
+    def _decode_simple(self, token: str) -> dict:
+        """Simple HMAC-based token decoding (fallback without jose)."""
+        import base64
+
+        parts = token.split(".")
+        if len(parts) != 3:
+            raise ValueError("Invalid token format")
+
+        header, body, sig = parts
+        signing_input = f"{header}.{body}"
+        expected_sig = hmac.new(
+            self._secret.encode(), signing_input.encode(), hashlib.sha256
+        ).hexdigest()
+
+        if not hmac.compare_digest(sig, expected_sig):
+            raise ValueError("Invalid signature")
+
+        # Decode payload
+        padding = 4 - len(body) % 4
+        if padding != 4:
+            body += "=" * padding
+        payload = json.loads(base64.urlsafe_b64decode(body))
+
+        # Check expiration
+        exp = payload.get("exp")
+        if exp:
+            exp_dt = datetime.fromisoformat(str(exp).replace("Z", "+00:00"))
+            if datetime.now(timezone.utc) > exp_dt:
+                raise ValueError("Token expired")
+
+        return payload
+
+
+class AuthManager:
+    """Central authentication manager.
+
+    Manages users, password hashing, and token lifecycle.
+    Users are stored in ~/.hits/.auth/users.json with restricted permissions.
+    """
+
+    def __init__(self):
+        self._hasher = PasswordHasher()
+        self._tokens = TokenManager()
+        self._users_path = Path.home() / ".hits" / ".auth" / "users.json"
+        self._users_path.parent.mkdir(parents=True, exist_ok=True)
+        # Restrict auth directory permissions
+        os.chmod(self._users_path.parent, 0o700)
+
+    def _load_users(self) -> dict:
+        """Load users database."""
+        if self._users_path.exists():
+            try:
+                return json.loads(self._users_path.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, IOError):
+                return {}
+        return {}
+
+    def _save_users(self, users: dict) -> None:
+        """Save users database with restricted permissions."""
+        self._users_path.write_text(
+            json.dumps(users, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+        os.chmod(self._users_path, 0o600)
+
+    def create_user(self, username: str, password: str) -> bool:
+        """Create a new user. Returns False if username exists."""
+        users = self._load_users()
+        if username in users:
+            return False
+
+        users[username] = {
+            "password_hash": self._hasher.hash_password(password),
+            "created_at": datetime.now(timezone.utc).isoformat(),
+            "role": "admin" if len(users) == 0 else "user",
+        }
+        self._save_users(users)
+        return True
+
+    def authenticate(self, username: str, password: str) -> Optional[str]:
+        """Authenticate a user. Returns access token or None."""
+        users = self._load_users()
+        user = users.get(username)
+
+        if not user:
+            # Constant-time: always hash to prevent timing attacks
+            self._hasher.hash_password(secrets.token_urlsafe(16))
+            return None
+
+        if not self._hasher.verify_password(password, user["password_hash"]):
+            return None
+
+        return self._tokens.create_access_token(username)
+
+    def create_tokens(self, username: str, password: str) -> Optional[dict]:
+        """Authenticate and return both access + refresh tokens."""
+        users = self._load_users()
+        user = users.get(username)
+
+        if not user:
+            self._hasher.hash_password(secrets.token_urlsafe(16))
+            return None
+
+        if not self._hasher.verify_password(password, user["password_hash"]):
+            return None
+
+        return {
+            "access_token": self._tokens.create_access_token(username),
+            "refresh_token": self._tokens.create_refresh_token(username),
+            "username": username,
+            "role": user.get("role", "user"),
+        }
+
+    def refresh_access_token(self, refresh_token: str) -> Optional[str]:
+        """Generate a new access token from a valid refresh token."""
+        payload = self._tokens.verify_token(refresh_token, expected_type="refresh")
+        if not payload:
+            return None
+
+        username = payload.get("sub")
+        if not username:
+            return None
+
+        # Verify user still exists
+        users = self._load_users()
+        if username not in users:
+            return None
+
+        return self._tokens.create_access_token(username)
+
+    def verify_access_token(self, token: str) -> Optional[dict]:
+        """Verify an access token. Returns payload with user info."""
+        payload = self._tokens.verify_token(token, expected_type="access")
+        if not payload:
+            return None
+
+        username = payload.get("sub")
+        users = self._load_users()
+        user = users.get(username)
+
+        if not user:
+            return None
+
+        return {
+            "username": username,
+            "role": user.get("role", "user"),
+        }
+
+    def change_password(self, username: str, old_password: str, new_password: str) -> bool:
+        """Change a user's password. Requires current password."""
+        users = self._load_users()
+        user = users.get(username)
+
+        if not user:
+            return False
+
+        if not self._hasher.verify_password(old_password, user["password_hash"]):
+            return False
+
+        users[username]["password_hash"] = self._hasher.hash_password(new_password)
+        self._save_users(users)
+        return True
+
+    def user_exists(self, username: str) -> bool:
+        """Check if a user exists."""
+        return username in self._load_users()
+
+    def has_any_user(self) -> bool:
+        """Check if any user has been created (for initial setup)."""
+        return len(self._load_users()) > 0
+
+    def get_user_role(self, username: str) -> Optional[str]:
+        """Get user role."""
+        users = self._load_users()
+        user = users.get(username)
+        return user.get("role") if user else None
+
+
+# Singleton
+_auth_manager: Optional[AuthManager] = None
+
+
+def get_auth_manager() -> AuthManager:
+    """Get or create the global AuthManager singleton."""
+    global _auth_manager
+    if _auth_manager is None:
+        _auth_manager = AuthManager()
+    return _auth_manager

package/hits_core/auth/middleware.py

@@ -0,0 +1,69 @@
+"""Security middleware for FastAPI.
+
+Applies defense-in-depth headers and protections:
+- Content-Security-Policy (CSP): Prevents XSS by restricting resource sources
+- X-Content-Type-Options: Prevents MIME type sniffing
+- X-Frame-Options: Prevents clickjacking
+- Strict-Transport-Security (HSTS): Forces HTTPS
+- Referrer-Policy: Limits referrer information leakage
+- Permissions-Policy: Restricts browser features
+- X-XSS-Protection: Legacy XSS filter
+"""
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+
+class SecurityMiddleware(BaseHTTPMiddleware):
+    """Adds security headers to all responses."""
+
+    def __init__(self, app, dev_mode: bool = False):
+        super().__init__(app)
+        self.dev_mode = dev_mode
+
+    async def dispatch(self, request: Request, call_next):
+        response: Response = await call_next(request)
+
+        # Content-Security-Policy
+        if self.dev_mode:
+            # Dev: allow localhost connections for Vite HMR
+            csp = (
+                "default-src 'self'; "
+                "script-src 'self' 'unsafe-inline' http://localhost:5173; "
+                "style-src 'self' 'unsafe-inline'; "
+                "connect-src 'self' http://localhost:5173 http://localhost:8765; "
+                "img-src 'self' data:; "
+                "font-src 'self'; "
+                "frame-ancestors 'none'; "
+                "base-uri 'self'; "
+                "form-action 'self'"
+            )
+        else:
+            # Production: strict CSP
+            csp = (
+                "default-src 'self'; "
+                "script-src 'self'; "
+                "style-src 'self' 'unsafe-inline'; "
+                "connect-src 'self'; "
+                "img-src 'self' data:; "
+                "font-src 'self'; "
+                "frame-ancestors 'none'; "
+                "base-uri 'self'; "
+                "form-action 'self'"
+            )
+
+        response.headers["Content-Security-Policy"] = csp
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["X-XSS-Protection"] = "1; mode=block"
+        response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+        response.headers["Permissions-Policy"] = "camera=(), microphone=(), geolocation=()"
+        response.headers["Cache-Control"] = "no-store"
+
+        if not self.dev_mode:
+            response.headers["Strict-Transport-Security"] = (
+                "max-age=63072000; includeSubDomains; preload"
+            )
+
+        return response