remdb 0.3.114__py3-none-any.whl → 0.3.172__py3-none-any.whl

rem/auth/jwt.py

@@ -0,0 +1,352 @@
+"""
+JWT Token Service for REM Authentication.
+
+Provides JWT token generation and validation for stateless authentication.
+Uses HS256 algorithm with the session secret for signing.
+
+Token Types:
+- Access Token: Short-lived (default 1 hour), used for API authentication
+- Refresh Token: Long-lived (default 7 days), used to obtain new access tokens
+
+Token Claims:
+- sub: User ID (UUID string)
+- email: User email
+- name: User display name
+- role: User role (user, admin)
+- tier: User subscription tier
+- roles: List of roles for authorization
+- provider: Auth provider (email, google, microsoft)
+- tenant_id: Tenant identifier for multi-tenancy
+- exp: Expiration timestamp
+- iat: Issued at timestamp
+- type: Token type (access, refresh)
+
+Usage:
+    from rem.auth.jwt import JWTService
+
+    jwt_service = JWTService()
+
+    # Generate tokens after successful authentication
+    tokens = jwt_service.create_tokens(user_dict)
+    # Returns: {"access_token": "...", "refresh_token": "...", "token_type": "bearer", "expires_in": 3600}
+
+    # Validate token from Authorization header
+    user = jwt_service.verify_token(token)
+    # Returns user dict or None if invalid
+
+    # Refresh access token
+    new_tokens = jwt_service.refresh_access_token(refresh_token)
+"""
+
+import time
+import hmac
+import hashlib
+import base64
+import json
+from datetime import datetime, timezone
+from typing import Optional
+
+from loguru import logger
+
+
+class JWTService:
+    """
+    JWT token service for authentication.
+
+    Uses HMAC-SHA256 for signing - simple and secure for single-service deployment.
+    For multi-service deployments, consider switching to RS256 with public/private keys.
+    """
+
+    def __init__(
+        self,
+        secret: str | None = None,
+        access_token_expiry_seconds: int = 3600,  # 1 hour
+        refresh_token_expiry_seconds: int = 604800,  # 7 days
+        issuer: str = "rem",
+    ):
+        """
+        Initialize JWT service.
+
+        Args:
+            secret: Secret key for signing (uses settings.auth.session_secret if not provided)
+            access_token_expiry_seconds: Access token lifetime in seconds
+            refresh_token_expiry_seconds: Refresh token lifetime in seconds
+            issuer: Token issuer identifier
+        """
+        if secret:
+            self._secret = secret
+        else:
+            from ..settings import settings
+            self._secret = settings.auth.session_secret
+
+        self._access_expiry = access_token_expiry_seconds
+        self._refresh_expiry = refresh_token_expiry_seconds
+        self._issuer = issuer
+
+    def _base64url_encode(self, data: bytes) -> str:
+        """Base64url encode without padding."""
+        return base64.urlsafe_b64encode(data).rstrip(b"=").decode("utf-8")
+
+    def _base64url_decode(self, data: str) -> bytes:
+        """Base64url decode with padding restoration."""
+        padding = 4 - len(data) % 4
+        if padding != 4:
+            data += "=" * padding
+        return base64.urlsafe_b64decode(data)
+
+    def _sign(self, message: str) -> str:
+        """Create HMAC-SHA256 signature."""
+        signature = hmac.new(
+            self._secret.encode("utf-8"),
+            message.encode("utf-8"),
+            hashlib.sha256
+        ).digest()
+        return self._base64url_encode(signature)
+
+    def _create_token(self, payload: dict) -> str:
+        """
+        Create a JWT token.
+
+        Args:
+            payload: Token claims
+
+        Returns:
+            Encoded JWT string
+        """
+        header = {"alg": "HS256", "typ": "JWT"}
+
+        header_encoded = self._base64url_encode(json.dumps(header, separators=(",", ":")).encode())
+        payload_encoded = self._base64url_encode(json.dumps(payload, separators=(",", ":")).encode())
+
+        message = f"{header_encoded}.{payload_encoded}"
+        signature = self._sign(message)
+
+        return f"{message}.{signature}"
+
+    def _verify_signature(self, token: str) -> dict | None:
+        """
+        Verify token signature and decode payload.
+
+        Args:
+            token: JWT token string
+
+        Returns:
+            Decoded payload dict or None if invalid
+        """
+        try:
+            parts = token.split(".")
+            if len(parts) != 3:
+                return None
+
+            header_encoded, payload_encoded, signature = parts
+
+            # Verify signature
+            message = f"{header_encoded}.{payload_encoded}"
+            expected_signature = self._sign(message)
+
+            if not hmac.compare_digest(signature, expected_signature):
+                logger.debug("JWT signature verification failed")
+                return None
+
+            # Decode payload
+            payload = json.loads(self._base64url_decode(payload_encoded))
+            return payload
+
+        except Exception as e:
+            logger.debug(f"JWT decode error: {e}")
+            return None
+
+    def create_tokens(
+        self,
+        user: dict,
+        access_expiry: int | None = None,
+        refresh_expiry: int | None = None,
+    ) -> dict:
+        """
+        Create access and refresh tokens for a user.
+
+        Args:
+            user: User dict with id, email, name, role, tier, roles, provider, tenant_id
+            access_expiry: Override access token expiry (seconds)
+            refresh_expiry: Override refresh token expiry (seconds)
+
+        Returns:
+            Dict with access_token, refresh_token, token_type, expires_in
+        """
+        now = int(time.time())
+        access_exp = access_expiry or self._access_expiry
+        refresh_exp = refresh_expiry or self._refresh_expiry
+
+        # Common claims
+        base_claims = {
+            "sub": user.get("id", ""),
+            "email": user.get("email", ""),
+            "name": user.get("name", ""),
+            "role": user.get("role"),
+            "tier": user.get("tier", "free"),
+            "roles": user.get("roles", ["user"]),
+            "provider": user.get("provider", "email"),
+            "tenant_id": user.get("tenant_id", "default"),
+            "iss": self._issuer,
+            "iat": now,
+        }
+
+        # Access token
+        access_payload = {
+            **base_claims,
+            "type": "access",
+            "exp": now + access_exp,
+        }
+        access_token = self._create_token(access_payload)
+
+        # Refresh token (minimal claims for security)
+        refresh_payload = {
+            "sub": user.get("id", ""),
+            "email": user.get("email", ""),
+            "type": "refresh",
+            "iss": self._issuer,
+            "iat": now,
+            "exp": now + refresh_exp,
+        }
+        refresh_token = self._create_token(refresh_payload)
+
+        return {
+            "access_token": access_token,
+            "refresh_token": refresh_token,
+            "token_type": "bearer",
+            "expires_in": access_exp,
+        }
+
+    def verify_token(self, token: str, token_type: str = "access") -> dict | None:
+        """
+        Verify a token and return user claims.
+
+        Args:
+            token: JWT token string
+            token_type: Expected token type ("access" or "refresh")
+
+        Returns:
+            User dict with claims or None if invalid/expired
+        """
+        payload = self._verify_signature(token)
+        if not payload:
+            return None
+
+        # Check token type
+        if payload.get("type") != token_type:
+            logger.debug(f"Token type mismatch: expected {token_type}, got {payload.get('type')}")
+            return None
+
+        # Check expiration
+        exp = payload.get("exp", 0)
+        if exp < time.time():
+            logger.debug("Token expired")
+            return None
+
+        # Check issuer
+        if payload.get("iss") != self._issuer:
+            logger.debug(f"Token issuer mismatch: expected {self._issuer}, got {payload.get('iss')}")
+            return None
+
+        # Return user dict (compatible with session user format)
+        return {
+            "id": payload.get("sub"),
+            "email": payload.get("email"),
+            "name": payload.get("name"),
+            "role": payload.get("role"),
+            "tier": payload.get("tier", "free"),
+            "roles": payload.get("roles", ["user"]),
+            "provider": payload.get("provider", "email"),
+            "tenant_id": payload.get("tenant_id", "default"),
+        }
+
+    def refresh_access_token(self, refresh_token: str) -> dict | None:
+        """
+        Create new access token using refresh token.
+
+        Args:
+            refresh_token: Valid refresh token
+
+        Returns:
+            New token dict or None if refresh token is invalid
+        """
+        # Verify refresh token
+        payload = self._verify_signature(refresh_token)
+        if not payload:
+            return None
+
+        if payload.get("type") != "refresh":
+            logger.debug("Not a refresh token")
+            return None
+
+        # Check expiration
+        exp = payload.get("exp", 0)
+        if exp < time.time():
+            logger.debug("Refresh token expired")
+            return None
+
+        # Create new access token with minimal info from refresh token
+        # In production, you'd look up the full user from database
+        user = {
+            "id": payload.get("sub"),
+            "email": payload.get("email"),
+            "name": payload.get("email", "").split("@")[0],
+            "provider": "email",
+            "tenant_id": "default",
+            "tier": "free",
+            "roles": ["user"],
+        }
+
+        # Only return new access token, keep same refresh token
+        now = int(time.time())
+        access_payload = {
+            "sub": user["id"],
+            "email": user["email"],
+            "name": user["name"],
+            "role": user.get("role"),
+            "tier": user["tier"],
+            "roles": user["roles"],
+            "provider": user["provider"],
+            "tenant_id": user["tenant_id"],
+            "type": "access",
+            "iss": self._issuer,
+            "iat": now,
+            "exp": now + self._access_expiry,
+        }
+
+        return {
+            "access_token": self._create_token(access_payload),
+            "token_type": "bearer",
+            "expires_in": self._access_expiry,
+        }
+
+    def decode_without_verification(self, token: str) -> dict | None:
+        """
+        Decode token without verification (for debugging only).
+
+        Args:
+            token: JWT token string
+
+        Returns:
+            Decoded payload or None
+        """
+        try:
+            parts = token.split(".")
+            if len(parts) != 3:
+                return None
+            payload = json.loads(self._base64url_decode(parts[1]))
+            return payload
+        except Exception:
+            return None
+
+
+# Singleton instance for convenience
+_jwt_service: Optional[JWTService] = None
+
+
+def get_jwt_service() -> JWTService:
+    """Get or create the JWT service singleton."""
+    global _jwt_service
+    if _jwt_service is None:
+        _jwt_service = JWTService()
+    return _jwt_service

rem/auth/middleware.py

@@ -1,17 +1,28 @@
 """
-OAuth Authentication Middleware for FastAPI.
+Authentication Middleware for FastAPI.
 
-Protects API endpoints by requiring valid session.
-Supports anonymous access with rate limiting when allow_anonymous=True.
+Protects API endpoints by requiring valid authentication.
+Supports multiple auth methods: JWT, API Key, Session, Dev Token.
+Anonymous access with rate limiting when allow_anonymous=True.
 MCP endpoints are always protected unless explicitly disabled.
 
 Design Pattern:
-- Check session for user on protected paths
-- Check Bearer token for dev token (non-production only)
+- API Key (X-API-Key): Access control guardrail, NOT user identity
+- JWT (Authorization: Bearer): Primary method for user identity
+- Dev token: Non-production testing (starts with "dev_")
+- Session: Backward compatibility for browser-based auth
 - MCP paths always require authentication (protected service)
-- If allow_anonymous=True: Allow unauthenticated requests (marked as ANONYMOUS tier)
-- If allow_anonymous=False: Return 401 for API calls, redirect browsers to login
-- Exclude auth endpoints and public paths
+
+Authentication Flow:
+1. If API key enabled: Validate X-API-Key header (access gate)
+2. Check JWT token for user identity (primary)
+3. Check dev token for testing (non-production only)
+4. Check session for user (backward compatibility)
+5. If allow_anonymous=True: Allow as anonymous (rate-limited)
+6. If allow_anonymous=False: Return 401 / redirect to login
+
+IMPORTANT: API key validates ACCESS, JWT identifies USER.
+Both can be required: API key for access + JWT for user identity.
 
 Access Modes (configured in settings.auth):
 - enabled=true, allow_anonymous=true: Auth available, anonymous gets rate-limited access
@@ -20,6 +31,11 @@ Access Modes (configured in settings.auth):
 - mcp_requires_auth=true (default): MCP always requires login regardless of allow_anonymous
 - mcp_requires_auth=false: MCP follows normal allow_anonymous rules (dev only)
 
+API Key Authentication (configured in settings.api):
+- api_key_enabled=true: Require X-API-Key header for access
+- api_key: The secret key to validate against
+- API key is an ACCESS GATE, not user identity - JWT still needed for user
+
 Dev Token Support (non-production only):
 - GET /api/auth/dev/token returns a Bearer token for test-user
 - Include as: Authorization: Bearer dev_<signature>
@@ -82,6 +98,67 @@ class AuthMiddleware(BaseHTTPMiddleware):
         self.mcp_requires_auth = mcp_requires_auth
         self.mcp_path = mcp_path
 
+    def _check_api_key(self, request: Request) -> dict | None:
+        """
+        Check for valid X-API-Key header.
+
+        Returns:
+            API key user dict if valid, None otherwise
+        """
+        # Only check if API key auth is enabled
+        if not settings.api.api_key_enabled:
+            return None
+
+        # Check for X-API-Key header
+        api_key = request.headers.get("x-api-key")
+        if not api_key:
+            return None
+
+        # Validate against configured API key
+        if settings.api.api_key and api_key == settings.api.api_key:
+            logger.debug("X-API-Key authenticated")
+            return {
+                "id": "api-key-user",
+                "email": "api@rem.local",
+                "name": "API Key User",
+                "provider": "api-key",
+                "tenant_id": "default",
+                "tier": "pro",  # API key users get full access
+                "roles": ["user"],
+            }
+
+        # Invalid API key
+        logger.warning("Invalid X-API-Key provided")
+        return None
+
+    def _check_jwt_token(self, request: Request) -> dict | None:
+        """
+        Check for valid JWT in Authorization header.
+
+        Returns:
+            User dict if valid JWT, None otherwise
+        """
+        auth_header = request.headers.get("authorization", "")
+        if not auth_header.startswith("Bearer "):
+            return None
+
+        token = auth_header[7:]  # Strip "Bearer "
+
+        # Skip dev tokens (handled separately)
+        if token.startswith("dev_"):
+            return None
+
+        # Verify JWT token
+        from .jwt import get_jwt_service
+        jwt_service = get_jwt_service()
+        user = jwt_service.verify_token(token)
+
+        if user:
+            logger.debug(f"JWT authenticated: {user.get('email')}")
+            return user
+
+        return None
+
     def _check_dev_token(self, request: Request) -> dict | None:
         """
         Check for valid dev token in Authorization header (non-production only).
@@ -105,7 +182,7 @@ class AuthMiddleware(BaseHTTPMiddleware):
         # Verify dev token
         from ..api.routers.dev import verify_dev_token
         if verify_dev_token(token):
-            logger.debug(f"Dev token authenticated as test-user")
+            logger.debug("Dev token authenticated as test-user")
             return {
                 "id": "test-user",
                 "email": "test@rem.local",
@@ -142,6 +219,34 @@ class AuthMiddleware(BaseHTTPMiddleware):
         if not is_protected or is_excluded:
             return await call_next(request)
 
+        # API key validation (access control, not user identity)
+        # API key is a guardrail for access - JWT identifies the actual user
+        if settings.api.api_key_enabled:
+            api_key = request.headers.get("x-api-key")
+            if not api_key:
+                logger.debug(f"Missing X-API-Key for: {path}")
+                return JSONResponse(
+                    status_code=401,
+                    content={"detail": "API key required. Include X-API-Key header."},
+                    headers={"WWW-Authenticate": 'ApiKey realm="REM API"'},
+                )
+            if api_key != settings.api.api_key:
+                logger.warning(f"Invalid X-API-Key for: {path}")
+                return JSONResponse(
+                    status_code=401,
+                    content={"detail": "Invalid API key"},
+                    headers={"WWW-Authenticate": 'ApiKey realm="REM API"'},
+                )
+            logger.debug("X-API-Key validated for access")
+            # API key valid - continue to check JWT for user identity
+
+        # Check for JWT token in Authorization header (primary user identity)
+        jwt_user = self._check_jwt_token(request)
+        if jwt_user:
+            request.state.user = jwt_user
+            request.state.is_anonymous = False
+            return await call_next(request)
+
         # Check for dev token (non-production only)
         dev_user = self._check_dev_token(request)
         if dev_user:
@@ -149,7 +254,7 @@ class AuthMiddleware(BaseHTTPMiddleware):
             request.state.is_anonymous = False
             return await call_next(request)
 
-        # Check for valid session
+        # Check for valid session (backward compatibility)
         user = request.session.get("user")
 
         if user:

rem/auth/providers/__init__.py

@@ -1,6 +1,7 @@
-"""OAuth provider implementations."""
+"""Authentication provider implementations."""
 
 from .base import OAuthProvider, OAuthTokens, OAuthUserInfo
+from .email import EmailAuthProvider, EmailAuthResult
 from .google import GoogleOAuthProvider
 from .microsoft import MicrosoftOAuthProvider
 
@@ -8,6 +9,8 @@ __all__ = [
     "OAuthProvider",
     "OAuthTokens",
     "OAuthUserInfo",
+    "EmailAuthProvider",
+    "EmailAuthResult",
     "GoogleOAuthProvider",
     "MicrosoftOAuthProvider",
 ]