remdb 0.3.181__py3-none-any.whl → 0.3.223__py3-none-any.whl

rem/api/routers/messages.py

@@ -16,6 +16,7 @@ Endpoints:
 """
 
 from datetime import datetime
+from enum import Enum
 from typing import Literal
 from uuid import UUID
 
@@ -23,6 +24,8 @@ from fastapi import APIRouter, Depends, Header, HTTPException, Query, Request
 from loguru import logger
 from pydantic import BaseModel, Field
 
+from .common import ErrorResponse
+
 from ..deps import (
     get_current_user,
     get_user_filter,
@@ -38,6 +41,18 @@ from ...utils.date_utils import parse_iso, utc_now
 router = APIRouter(prefix="/api/v1")
 
 
+# =============================================================================
+# Enums
+# =============================================================================
+
+
+class SortOrder(str, Enum):
+    """Sort order for list queries."""
+
+    ASC = "asc"
+    DESC = "desc"
+
+
 # =============================================================================
 # Request/Response Models
 # =============================================================================
@@ -93,6 +108,23 @@ class SessionListResponse(BaseModel):
     has_more: bool
 
 
+class SessionWithUser(BaseModel):
+    """Session with user info for admin views."""
+
+    id: str
+    name: str
+    mode: str | None = None
+    description: str | None = None
+    user_id: str | None = None
+    user_name: str | None = None
+    user_email: str | None = None
+    message_count: int = 0
+    total_tokens: int | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    metadata: dict | None = None
+
+
 class PaginationMetadata(BaseModel):
     """Pagination metadata for paginated responses."""
 
@@ -108,7 +140,7 @@ class SessionsQueryResponse(BaseModel):
     """Response for paginated sessions query."""
 
     object: Literal["list"] = "list"
-    data: list[Session] = Field(description="List of sessions for the current page")
+    data: list[SessionWithUser] = Field(description="List of sessions for the current page")
     metadata: PaginationMetadata = Field(description="Pagination metadata")
 
 
@@ -117,7 +149,14 @@ class SessionsQueryResponse(BaseModel):
 # =============================================================================
 
 
-@router.get("/messages", response_model=MessageListResponse, tags=["messages"])
+@router.get(
+    "/messages",
+    response_model=MessageListResponse,
+    tags=["messages"],
+    responses={
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
+)
 async def list_messages(
     request: Request,
     mine: bool = Query(default=False, description="Only show my messages (uses JWT identity)"),
@@ -134,6 +173,7 @@ async def list_messages(
     ),
     limit: int = Query(default=50, ge=1, le=100, description="Max results to return"),
     offset: int = Query(default=0, ge=0, description="Offset for pagination"),
+    sort: SortOrder = Query(default=SortOrder.DESC, description="Sort order by created_at (asc or desc)"),
 ) -> MessageListResponse:
     """
     List messages with optional filters.
@@ -149,8 +189,9 @@ async def list_messages(
     - session_id: Filter by conversation session
     - start_date/end_date: Filter by creation time range (ISO 8601 format)
     - message_type: Filter by role (user, assistant, system, tool)
+    - sort: Sort order by created_at (asc or desc, default: desc)
 
-    Returns paginated results ordered by created_at descending.
+    Returns paginated results ordered by created_at.
     """
     if not settings.postgres.enabled:
         raise HTTPException(status_code=503, detail="Database not enabled")
@@ -172,6 +213,7 @@ async def list_messages(
 
     # Apply optional filters
     if session_id:
+        # session_id is the session UUID - use directly
         filters["session_id"] = session_id
     if message_type:
         filters["message_type"] = message_type
@@ -183,12 +225,15 @@ async def list_messages(
         f"filters={filters}"
     )
 
+    # Build order_by clause based on sort parameter
+    order_by = f"created_at {sort.value.upper()}"
+
     # For date filtering, we need custom SQL (not supported by basic Repository)
     # For now, fetch all matching base filters and filter in Python
     # TODO: Extend Repository to support date range filters
     messages = await repo.find(
         filters,
-        order_by="created_at DESC",
+        order_by=order_by,
         limit=limit + 1,  # Fetch one extra to determine has_more
         offset=offset,
     )
@@ -224,7 +269,16 @@ async def list_messages(
     return MessageListResponse(data=messages, total=total, has_more=has_more)
 
 
-@router.get("/messages/{message_id}", response_model=Message, tags=["messages"])
+@router.get(
+    "/messages/{message_id}",
+    response_model=Message,
+    tags=["messages"],
+    responses={
+        403: {"model": ErrorResponse, "description": "Access denied: not owner"},
+        404: {"model": ErrorResponse, "description": "Message not found"},
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
+)
 async def get_message(
     request: Request,
     message_id: str,
@@ -270,10 +324,19 @@ async def get_message(
 # =============================================================================
 
 
-@router.get("/sessions", response_model=SessionsQueryResponse, tags=["sessions"])
+@router.get(
+    "/sessions",
+    response_model=SessionsQueryResponse,
+    tags=["sessions"],
+    responses={
+        503: {"model": ErrorResponse, "description": "Database not enabled or connection failed"},
+    },
+)
 async def list_sessions(
     request: Request,
     user_id: str | None = Query(default=None, description="Filter by user ID (admin only for cross-user)"),
+    user_name: str | None = Query(default=None, description="Filter by user name (partial match, admin only)"),
+    user_email: str | None = Query(default=None, description="Filter by user email (partial match, admin only)"),
     mode: SessionMode | None = Query(default=None, description="Filter by session mode"),
     page: int = Query(default=1, ge=1, description="Page number (1-indexed)"),
     page_size: int = Query(default=50, ge=1, le=100, description="Number of results per page"),
@@ -283,51 +346,113 @@ async def list_sessions(
 
     Access Control:
     - Regular users: Only see their own sessions
-    - Admin users: Can filter by any user_id or see all sessions
+    - Admin users: Can filter by any user_id, user_name, user_email, or see all sessions
 
     Filters:
     - user_id: Filter by session owner (admin only for cross-user)
+    - user_name: Filter by user name partial match (admin only)
+    - user_email: Filter by user email partial match (admin only)
     - mode: Filter by session mode (normal or evaluation)
 
     Pagination:
     - page: Page number (1-indexed, default: 1)
     - page_size: Number of sessions per page (default: 50, max: 100)
 
-    Returns paginated results ordered by created_at descending with pagination metadata.
+    Returns paginated results with user info ordered by created_at descending.
     """
     if not settings.postgres.enabled:
         raise HTTPException(status_code=503, detail="Database not enabled")
 
-    repo = Repository(Session, table_name="sessions")
+    current_user = get_current_user(request)
+    admin = is_admin(current_user)
 
-    # Build user-scoped filters (admin can see all, regular users see only their own)
-    filters = await get_user_filter(request, x_user_id=user_id)
-    if mode:
-        filters["mode"] = mode.value
+    # Get postgres service for raw SQL query
+    db = get_postgres_service()
+    if not db:
+        raise HTTPException(status_code=503, detail="Database connection failed")
+    if not db.pool:
+        await db.connect()
 
-    # Use CTE-based pagination with ROW_NUMBER() OVER (PARTITION BY user_id ORDER BY created_at DESC)
-    result = await repo.find_paginated(
-        filters,
-        page=page,
-        page_size=page_size,
-        order_by="created_at DESC",
-        partition_by="user_id",
-    )
+    # Build effective filters based on user role
+    effective_user_id = user_id
+    effective_user_name = user_name if admin else None  # Only admin can search by name
+    effective_user_email = user_email if admin else None  # Only admin can search by email
+
+    if not admin:
+        # Non-admin users can only see their own sessions
+        effective_user_id = current_user.get("id") if current_user else None
+        if not effective_user_id:
+            # Anonymous user - return empty
+            return SessionsQueryResponse(
+                data=[],
+                metadata=PaginationMetadata(
+                    total=0, page=page, page_size=page_size,
+                    total_pages=0, has_next=False, has_previous=False,
+                ),
+            )
+
+    # Call the SQL function for sessions with user info
+    async with db.pool.acquire() as conn:
+        rows = await conn.fetch(
+            """
+            SELECT * FROM fn_list_sessions_with_user(
+                $1, $2, $3, $4, $5, $6
+            )
+            """,
+            effective_user_id,
+            effective_user_name,
+            effective_user_email,
+            mode.value if mode else None,
+            page,
+            page_size,
+        )
+
+    # Extract total from first row
+    total = rows[0]["total_count"] if rows else 0
+
+    # Convert rows to SessionWithUser
+    data = [
+        SessionWithUser(
+            id=str(row["id"]),
+            name=row["name"],
+            mode=row["mode"],
+            description=row["description"],
+            user_id=row["user_id"],
+            user_name=row["user_name"],
+            user_email=row["user_email"],
+            message_count=row["message_count"] or 0,
+            total_tokens=row["total_tokens"],
+            created_at=row["created_at"],
+            updated_at=row["updated_at"],
+            metadata=row["metadata"],
+        )
+        for row in rows
+    ]
+
+    total_pages = (total + page_size - 1) // page_size if total > 0 else 0
 
     return SessionsQueryResponse(
-        data=result["data"],
+        data=data,
         metadata=PaginationMetadata(
-            total=result["total"],
-            page=result["page"],
-            page_size=result["page_size"],
-            total_pages=result["total_pages"],
-            has_next=result["has_next"],
-            has_previous=result["has_previous"],
+            total=total,
+            page=page,
+            page_size=page_size,
+            total_pages=total_pages,
+            has_next=page < total_pages,
+            has_previous=page > 1,
         ),
     )
 
 
-@router.post("/sessions", response_model=Session, status_code=201, tags=["sessions"])
+@router.post(
+    "/sessions",
+    response_model=Session,
+    status_code=201,
+    tags=["sessions"],
+    responses={
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
+)
 async def create_session(
     request_body: SessionCreateRequest,
     user: dict = Depends(require_admin),
@@ -379,7 +504,16 @@ async def create_session(
     return result  # type: ignore
 
 
-@router.get("/sessions/{session_id}", response_model=Session, tags=["sessions"])
+@router.get(
+    "/sessions/{session_id}",
+    response_model=Session,
+    tags=["sessions"],
+    responses={
+        403: {"model": ErrorResponse, "description": "Access denied: not owner"},
+        404: {"model": ErrorResponse, "description": "Session not found"},
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
+)
 async def get_session(
     request: Request,
     session_id: str,
@@ -392,7 +526,7 @@ async def get_session(
     - Admin users: Can access any session
 
     Args:
-        session_id: UUID or name of the session
+        session_id: UUID of the session
 
     Returns:
         Session object if found
@@ -408,12 +542,7 @@ async def get_session(
     session = await repo.get_by_id(session_id)
 
     if not session:
-        # Try finding by name
-        sessions = await repo.find({"name": session_id}, limit=1)
-        if sessions:
-            session = sessions[0]
-        else:
-            raise HTTPException(status_code=404, detail=f"Session '{session_id}' not found")
+        raise HTTPException(status_code=404, detail=f"Session '{session_id}' not found")
 
     # Check access: admin or owner
     current_user = get_current_user(request)
@@ -425,7 +554,16 @@ async def get_session(
     return session
 
 
-@router.put("/sessions/{session_id}", response_model=Session, tags=["sessions"])
+@router.put(
+    "/sessions/{session_id}",
+    response_model=Session,
+    tags=["sessions"],
+    responses={
+        403: {"model": ErrorResponse, "description": "Access denied: not owner"},
+        404: {"model": ErrorResponse, "description": "Session not found"},
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
+)
 async def update_session(
     request: Request,
     session_id: str,

rem/api/routers/models.py

@@ -15,6 +15,8 @@ from typing import Literal
 from fastapi import APIRouter, HTTPException
 from pydantic import BaseModel, Field
 
+from .common import ErrorResponse
+
 from rem.agentic.llm_provider_models import (
     ModelInfo,
     AVAILABLE_MODELS,
@@ -57,7 +59,13 @@ async def list_models() -> ModelsResponse:
     return ModelsResponse(data=AVAILABLE_MODELS)
 
 
-@router.get("/models/{model_id:path}", response_model=ModelInfo)
+@router.get(
+    "/models/{model_id:path}",
+    response_model=ModelInfo,
+    responses={
+        404: {"model": ErrorResponse, "description": "Model not found"},
+    },
+)
 async def get_model(model_id: str) -> ModelInfo:
     """
     Get information about a specific model.

rem/api/routers/query.py

@@ -86,6 +86,8 @@ from fastapi import APIRouter, Header, HTTPException
 from loguru import logger
 from pydantic import BaseModel, Field
 
+from .common import ErrorResponse
+
 from ...services.postgres import get_postgres_service
 from ...services.rem.service import RemService
 from ...services.rem.parser import RemQueryParser
@@ -213,7 +215,16 @@ class QueryResponse(BaseModel):
     )
 
 
-@router.post("/query", response_model=QueryResponse)
+@router.post(
+    "/query",
+    response_model=QueryResponse,
+    responses={
+        400: {"model": ErrorResponse, "description": "Invalid query or missing required fields"},
+        500: {"model": ErrorResponse, "description": "Query execution failed"},
+        501: {"model": ErrorResponse, "description": "Feature not yet implemented"},
+        503: {"model": ErrorResponse, "description": "Database not configured or unavailable"},
+    },
+)
 async def execute_query(
     request: QueryRequest,
     x_user_id: str | None = Header(default=None, description="User ID for query isolation (optional, uses default if not provided)"),

rem/api/routers/shared_sessions.py

@@ -18,6 +18,8 @@ from fastapi import APIRouter, Depends, Header, HTTPException, Query, Request
 from loguru import logger
 from pydantic import BaseModel, Field
 
+from .common import ErrorResponse
+
 from ..deps import get_current_user, require_auth
 from ...models.entities import (
     Message,
@@ -83,6 +85,10 @@ class ShareSessionResponse(BaseModel):
     response_model=ShareSessionResponse,
     status_code=201,
     tags=["sessions"],
+    responses={
+        400: {"model": ErrorResponse, "description": "Session already shared with this user"},
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
 )
 async def share_session(
     request: Request,
@@ -175,6 +181,10 @@ async def share_session(
     "/sessions/{session_id}/share/{shared_with_user_id}",
     status_code=200,
     tags=["sessions"],
+    responses={
+        404: {"model": ErrorResponse, "description": "Share not found"},
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
 )
 async def remove_session_share(
     request: Request,
@@ -250,6 +260,9 @@ async def remove_session_share(
     "/sessions/shared-with-me",
     response_model=SharedWithMeResponse,
     tags=["sessions"],
+    responses={
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
 )
 async def get_shared_with_me(
     request: Request,
@@ -328,6 +341,9 @@ async def get_shared_with_me(
     "/sessions/shared-with-me/{owner_user_id}/messages",
     response_model=SharedMessagesResponse,
     tags=["sessions"],
+    responses={
+        503: {"model": ErrorResponse, "description": "Database not enabled"},
+    },
 )
 async def get_shared_messages(
     request: Request,

rem/auth/jwt.py

@@ -260,12 +260,16 @@ class JWTService:
             "tenant_id": payload.get("tenant_id", "default"),
         }
 
-    def refresh_access_token(self, refresh_token: str) -> dict | None:
+    def refresh_access_token(
+        self, refresh_token: str, user_override: dict | None = None
+    ) -> dict | None:
         """
         Create new access token using refresh token.
 
         Args:
             refresh_token: Valid refresh token
+            user_override: Optional dict with user fields to override defaults
+                           (e.g., role, roles, tier, name from database lookup)
 
         Returns:
             New token dict or None if refresh token is invalid
@@ -285,8 +289,7 @@ class JWTService:
             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
+        # Build user dict with defaults
         user = {
             "id": payload.get("sub"),
             "email": payload.get("email"),
@@ -294,16 +297,28 @@ class JWTService:
             "provider": "email",
             "tenant_id": "default",
             "tier": "free",
+            "role": "user",
             "roles": ["user"],
         }
 
+        # Apply overrides from database lookup if provided
+        if user_override:
+            if user_override.get("role"):
+                user["role"] = user_override["role"]
+            if user_override.get("roles"):
+                user["roles"] = user_override["roles"]
+            if user_override.get("tier"):
+                user["tier"] = user_override["tier"]
+            if user_override.get("name"):
+                user["name"] = user_override["name"]
+
         # 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"),
+            "role": user["role"],
             "tier": user["tier"],
             "roles": user["roles"],
             "provider": user["provider"],

rem/auth/middleware.py

@@ -14,15 +14,14 @@ Design Pattern:
 - MCP paths always require authentication (protected service)
 
 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
+1. Check JWT/dev token/session for user identity first
+2. If user is admin: bypass API key check (admin privilege)
+3. If API key enabled and user is not admin: Validate X-API-Key header
+4. If allow_anonymous=True: Allow as anonymous (rate-limited)
+5. 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.
+Admin users bypass the API key requirement (trusted identity).
 
 Access Modes (configured in settings.auth):
 - enabled=true, allow_anonymous=true: Auth available, anonymous gets rate-limited access
@@ -195,6 +194,12 @@ class AuthMiddleware(BaseHTTPMiddleware):
 
         return None
 
+    def _is_admin(self, user: dict | None) -> bool:
+        """Check if user has admin role."""
+        if not user:
+            return False
+        return "admin" in user.get("roles", [])
+
     async def dispatch(self, request: Request, call_next):
         """
         Check authentication for protected paths.
@@ -219,8 +224,35 @@ 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
+        # Check for user identity FIRST (JWT, dev token, session)
+        # This allows admin users to bypass API key requirement
+        user = None
+
+        # Check for JWT token in Authorization header (primary user identity)
+        jwt_user = self._check_jwt_token(request)
+        if jwt_user:
+            user = jwt_user
+
+        # Check for dev token (non-production only)
+        if not user:
+            dev_user = self._check_dev_token(request)
+            if dev_user:
+                user = dev_user
+
+        # Check for valid session (backward compatibility)
+        if not user:
+            session_user = request.session.get("user")
+            if session_user:
+                user = session_user
+
+        # If user is admin, bypass API key check entirely
+        if self._is_admin(user):
+            logger.debug(f"Admin user {user.get('email')} bypassing API key check")
+            request.state.user = user
+            request.state.is_anonymous = False
+            return await call_next(request)
+
+        # API key validation for non-admin users (access control guardrail)
         if settings.api.api_key_enabled:
             api_key = request.headers.get("x-api-key")
             if not api_key:
@@ -238,27 +270,9 @@ class AuthMiddleware(BaseHTTPMiddleware):
                     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:
-            request.state.user = dev_user
-            request.state.is_anonymous = False
-            return await call_next(request)
-
-        # Check for valid session (backward compatibility)
-        user = request.session.get("user")
 
+        # If we have a valid user (non-admin, but passed API key check), allow access
         if user:
-            # Authenticated user - add to request state
             request.state.user = user
             request.state.is_anonymous = False
             return await call_next(request)