chore: lint and minor updates

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

Author: araujof

Makefile

@@ -241,7 +241,7 @@ test-file:
 
 doctest:
 	@echo "🧪 Running doctest on all modules..."
-	@PYTHONPATH="$(SRC_DIR)" $(VENV_BIN)/pytest --doctest-modules cpex/ --tb=short --no-cov --disable-warnings
+	@PYTHONPATH="$(SRC_DIR)" $(VENV_BIN)/pytest --doctest-modules cpex/ --ignore=cpex/templates --tb=short --no-cov --disable-warnings
 
 # =============================================================================
 # Documentation (Hugo Book theme — no Python deps required)

cpex/framework/__init__.py

@@ -82,6 +82,7 @@
     PluginResult,
     PluginViolation,
     TransportType,
+    UserContext,
 )
 from cpex.framework.observability import ObservabilityProvider
 from cpex.framework.utils import get_attr
@@ -187,4 +188,5 @@ def get_plugin_manager(
     "TenantPluginManager",
     "ToolPreInvokePayload",
     "TransportType",
+    "UserContext",
 ]

cpex/framework/models.py

@@ -14,6 +14,7 @@
 import logging
 import os
 import re
+from datetime import datetime
 from enum import Enum, StrEnum
 from pathlib import Path
 from typing import Any, Generic, List, Optional, Self, TypeVar, Union
@@ -1487,6 +1488,56 @@ def plugin_name(self, name: str) -> None:
         self._plugin_name = name
 
 
+class UserContext(BaseModel):
+    """Authenticated user identity context for propagation to upstream servers and plugins.
+
+    Attributes:
+        user_id: Primary user identifier (typically email).
+        email: User email address.
+        full_name: User's display name.
+        is_admin: Whether the user has admin privileges.
+        groups: User's group memberships.
+        roles: User's RBAC roles.
+        team_id: Current team context (for single-team API tokens).
+        teams: All teams the user belongs to.
+        department: User's department.
+        attributes: Additional user attributes (extensible).
+        auth_method: How the user authenticated (bearer, api_key, basic, sso, proxy).
+        authenticated_at: When the authentication occurred.
+        service_account: Set when a service account is acting on behalf of this user.
+        delegation_chain: Chain of delegated identities for audit trail.
+
+    Examples:
+        >>> uc = UserContext(user_id="alice@example.com")
+        >>> uc.user_id
+        'alice@example.com'
+        >>> uc.is_admin
+        False
+        >>> uc.groups
+        []
+        >>> uc2 = UserContext(user_id="bob@example.com", email="bob@example.com", is_admin=True, auth_method="bearer")
+        >>> uc2.is_admin
+        True
+        >>> uc2.auth_method
+        'bearer'
+    """
+
+    user_id: str
+    email: Optional[str] = None
+    full_name: Optional[str] = None
+    is_admin: bool = False
+    groups: list[str] = Field(default_factory=list)
+    roles: list[str] = Field(default_factory=list)
+    team_id: Optional[str] = None
+    teams: Optional[list[str]] = None
+    department: Optional[str] = None
+    attributes: dict[str, Any] = Field(default_factory=dict)
+    auth_method: Optional[str] = None
+    authenticated_at: Optional[datetime] = None
+    service_account: Optional[str] = None
+    delegation_chain: list[str] = Field(default_factory=list)
+
+
 class Config(BaseModel):
     """Configurations for plugins.
 
@@ -1582,6 +1633,7 @@ class GlobalContext(BaseModel):
     Attributes:
             request_id (str): ID of the HTTP request.
             user (str): user ID associated with the request.
+            user_context (Optional[UserContext]): structured user identity context.
             tenant_id (str): tenant ID.
             server_id (str): server ID.
             content_type (Optional[str]): Content-Type header from the request.
@@ -1611,6 +1663,7 @@ class GlobalContext(BaseModel):
 
     request_id: str
     user: Optional[Union[str, dict[str, Any]]] = None
+    user_context: Optional[UserContext] = None
     tenant_id: Optional[str] = None
     server_id: Optional[str] = None
     content_type: Optional[str] = None
@@ -1664,6 +1717,63 @@ class PluginContext(BaseModel):
     global_context: GlobalContext
     metadata: dict[str, Any] = Field(default_factory=dict)
 
+    @property
+    def user_context(self) -> Optional[UserContext]:
+        """Get the authenticated user context.
+
+        Returns:
+            The UserContext if available, None otherwise.
+
+        Examples:
+            >>> gctx = GlobalContext(request_id="req-1")
+            >>> ctx = PluginContext(global_context=gctx)
+            >>> ctx.user_context is None
+            True
+        """
+        return self.global_context.user_context
+
+    @property
+    def user_email(self) -> Optional[str]:
+        """Get the authenticated user's email.
+
+        Falls back to the legacy ``global_context.user`` field when no
+        structured UserContext is available.
+
+        Returns:
+            User email string or None.
+
+        Examples:
+            >>> gctx = GlobalContext(request_id="req-1", user="alice@example.com")
+            >>> ctx = PluginContext(global_context=gctx)
+            >>> ctx.user_email
+            'alice@example.com'
+        """
+        uc = self.global_context.user_context
+        if uc:
+            return uc.email
+        user = self.global_context.user
+        if isinstance(user, str):
+            return user
+        if isinstance(user, dict):
+            return user.get("email")
+        return None
+
+    @property
+    def user_groups(self) -> list[str]:
+        """Get the authenticated user's groups.
+
+        Returns:
+            List of group names. Empty if no user context.
+
+        Examples:
+            >>> gctx = GlobalContext(request_id="req-1")
+            >>> ctx = PluginContext(global_context=gctx)
+            >>> ctx.user_groups
+            []
+        """
+        uc = self.global_context.user_context
+        return uc.groups if uc else []
+
     def get_state(self, key: str, default: Any = None) -> Any:
         """Get value from shared state.
 
@@ -1732,8 +1842,8 @@ class PluginPackageInfo(BaseModel):
 
     Examples:
         >>> pkg = PluginPackageInfo(git_repository="https://github.com/user/repo.git",
-            git_branch_tag_commit="v1.0.0",
-            version_constraint=">=1.0.0")
+        ...     git_branch_tag_commit="v1.0.0",
+        ...     version_constraint=">=1.0.0")
         >>> pkg2 = PluginPackageInfo(pypi_package="my-package", version_constraint=">=1.0.0")
     """