Merge pull request lightspeed-core#1011 from tisnik/lcore-1142-docstrings-for-authentication

tisnik · web-flow · commit 7e452cdffd1e · 2026-01-18T11:06:26.000+01:00
LCORE-1142: docstrings for authentication module
diff --git a/src/authentication/__init__.py b/src/authentication/__init__.py
@@ -21,7 +21,19 @@
 def get_auth_dependency(
     virtual_path: str = constants.DEFAULT_VIRTUAL_PATH,
 ) -> AuthInterface:
-    """Select the configured authentication dependency interface."""
+    """Select the configured authentication dependency interface.
+
+    Parameters:
+        virtual_path (str): Virtual path passed to the authentication
+                            dependency when it is constructed.
+
+    Returns:
+        AuthInterface: An instance implementing AuthInterface for the
+                       configured authentication module.
+
+    Raises:
+        ValueError: If the configured authentication module is not supported.
+    """
     try:
         module = configuration.authentication_configuration.module
     except LogicError:
diff --git a/src/authentication/interface.py b/src/authentication/interface.py
@@ -36,4 +36,13 @@ class AuthInterface(ABC):  # pylint: disable=too-few-public-methods
 
     @abstractmethod
     async def __call__(self, request: Request) -> AuthTuple:
-        """Validate FastAPI Requests for authentication and authorization."""
+        """Validate FastAPI Requests for authentication and authorization.
+
+        Returns:
+            AuthTuple: A 4-tuple (user_id, user_name, skip_user_id_check, token) where
+                user_id (str): authenticated user's unique identifier,
+                user_name (str): authenticated user's display name,
+                skip_user_id_check (bool): whether downstream handlers should
+                                           skip user-id verification,
+                token (str): authentication token or NO_USER_TOKEN when no token is present.
+        """
diff --git a/src/authentication/jwk_token.py b/src/authentication/jwk_token.py
@@ -35,7 +35,13 @@
 
 
 async def get_jwk_set(url: str) -> KeySet:
-    """Fetch the JWK set from the cache, or fetch it from the URL if not cached."""
+    """Fetch the JWK set from the cache, or fetch it from the URL if not cached.
+
+    Retrieve a JWK KeySet from the in-memory cache or fetch and cache it from the provided URL.
+
+    Returns:
+        KeySet: The JWK `KeySet` corresponding to the URL.
+    """
     async with _jwk_cache_lock:
         if url not in _jwk_cache:
             async with aiohttp.ClientSession() as session:
@@ -54,10 +60,21 @@ def key_resolver_func(
     jwk_set: KeySet,
 ) -> Callable[[dict[str, Any], dict[str, Any]], Key]:
     """
-    Create a key resolver function.
+    Create a JWK key resolver used to locate the verification key from a KeySet.
 
-    Return a function to find a key in the given jwk_set. The function matches the
-    signature expected by the jwt.decode key kwarg.
+    The returned callable accepts a JWT header and payload and selects a key from the provided
+    jwk_set. If the header contains a `kid`, the resolver returns the single key with that `kid`
+    and verifies the key's `alg` matches the header `alg`. If `kid` is absent, the resolver
+    returns the first key that matches the header `alg`. The resolver raises `KeyNotFoundError`
+    if no suitable key is found or if multiple keys are found for the same `kid`.
+
+    Parameters:
+        jwk_set (KeySet): JWK set to search for verification keys.
+
+    Returns:
+        callable: A function `header, payload -> Key` that resolves and returns
+                  the verification key.
+        Raises `KeyNotFoundError` when resolution fails.
     """
 
     def _internal(header: dict[str, Any], _payload: dict[str, Any]) -> Key:
@@ -67,8 +84,16 @@ def _internal(header: dict[str, Any], _payload: dict[str, Any]) -> Key:
         match the algorithm to make sure the algorithm stated by the user
         is the same algorithm the key itself expects.
 
-        # We intentionally do not use find_by_kid because it's a bad function
-        # that doesn't take the alg into account
+        We intentionally do not use find_by_kid because it's a bad function
+        that doesn't take the alg into account
+
+        Returns:
+            key (Key): The JWK matching the header's selection criteria.
+
+        Raises:
+            KeyNotFoundError: If the header is missing `alg`, no matching key
+            is found, multiple keys match a `kid`, or a found key's algorithm
+            does not match the header's `alg`.
         """
         if "alg" not in header:
             raise KeyNotFoundError("Token header missing 'alg' field")
@@ -117,13 +142,42 @@ class JwkTokenAuthDependency(AuthInterface):  # pylint: disable=too-few-public-m
     def __init__(
         self, config: JwkConfiguration, virtual_path: str = DEFAULT_VIRTUAL_PATH
     ) -> None:
-        """Initialize the required allowed paths for authorization checks."""
+        """Initialize the required allowed paths for authorization checks.
+
+        Create a JWK-based token authentication dependency configured for a specific virtual path.
+
+        Parameters:
+            config (JwkConfiguration): Configuration containing the JWK URL,
+                                       claim names, and validation settings.
+            virtual_path (str): Virtual authorization scope path used when
+                                resolving authorization rules; defaults to DEFAULT_VIRTUAL_PATH.
+
+        Notes:
+            Initializes the instance and sets `skip_userid_check` to False.
+        """
         self.virtual_path: str = virtual_path
         self.config: JwkConfiguration = config
         self.skip_userid_check = False
 
     async def __call__(self, request: Request) -> AuthTuple:
-        """Authenticate the JWT in the headers against the keys from the JWK url."""
+        """Authenticate the JWT in the headers against the keys from the JWK url.
+
+        If the Authorization header is missing, returns NO_AUTH_TUPLE. On token
+        verification or validation failures this function raises HTTPException
+        with appropriate HTTP status codes:
+        - 401 for unknown signing key/algorithm, bad signature, expired token,
+              or missing required claims;
+        - 400 for token decode or other JOSE-related decode/validation errors;
+        - 500 for unexpected internal errors.
+
+        Parameters:
+            request (Request): The incoming FastAPI request containing the Authorization header.
+
+        Returns:
+            AuthTuple: A tuple (user_id, username, skip_userid_check, token)
+            extracted from the validated token, or NO_AUTH_TUPLE when no
+            Authorization header is present.
+        """
         if not request.headers.get("Authorization"):
             return NO_AUTH_TUPLE
 
diff --git a/src/authentication/k8s.py b/src/authentication/k8s.py
@@ -52,6 +52,9 @@ def __new__(cls: type[Self]) -> Self:
 
         This method initializes the Kubernetes API clients the first time it is called.
         and ensures that subsequent calls return the same instance.
+
+        Returns:
+            instance (K8sClientSingleton): The singleton instance.
         """
         if cls._instance is None:
             cls._instance = super().__new__(cls)
@@ -105,6 +108,9 @@ def get_authn_api(cls) -> kubernetes.client.AuthenticationV1Api:
         """Return the Authentication API client instance.
 
         Ensures the singleton is initialized before returning the Authentication API client.
+
+        Returns:
+            kubernetes.client.AuthenticationV1Api: The initialized AuthenticationV1Api instance.
         """
         if cls._instance is None or cls._authn_api is None:
             cls()
@@ -115,6 +121,10 @@ def get_authz_api(cls) -> kubernetes.client.AuthorizationV1Api:
         """Return the Authorization API client instance.
 
         Ensures the singleton is initialized before returning the Authorization API client.
+
+        Returns:
+            kubernetes.client.AuthorizationV1Api: The Kubernetes Authorization
+                                                  API client instance.
         """
         if cls._instance is None or cls._authz_api is None:
             cls()
@@ -125,13 +135,30 @@ def get_custom_objects_api(cls) -> kubernetes.client.CustomObjectsApi:
         """Return the custom objects API instance.
 
         Ensures the singleton is initialized before returning the Authorization API client.
+
+        Returns:
+            kubernetes.client.CustomObjectsApi: The CustomObjectsApi client used by the singleton.
         """
         if cls._instance is None or cls._custom_objects_api is None:
             cls()
         return cls._custom_objects_api
 
     @classmethod
     def _get_cluster_id(cls) -> str:
+        """
+        Retrieve the OpenShift cluster ID from the ClusterVersion custom object and cache it.
+
+        Fetches the "version" ClusterVersion from group
+        `config.openshift.io/v1`, extracts `spec.clusterID`, assigns it to
+        `cls._cluster_id`, and returns it.
+
+        Returns:
+            str: The cluster's `clusterID`.
+
+        Raises:
+            ClusterIDUnavailableError: If the cluster ID cannot be obtained due
+            to missing keys, an API error, or any unexpected error.
+        """
         try:
             custom_objects_api = cls.get_custom_objects_api()
             version_data = custom_objects_api.get_cluster_custom_object(
@@ -159,7 +186,21 @@ def _get_cluster_id(cls) -> str:
 
     @classmethod
     def get_cluster_id(cls) -> str:
-        """Return the cluster ID."""
+        """Return the cluster ID.
+
+        Get the cached Kubernetes cluster identifier, initializing the
+        singleton and fetching the ID when necessary.
+
+        If running outside a cluster, sets and returns the sentinel value
+        "local". When running inside a cluster, attempts to fetch and cache the
+        cluster ID via the private retrieval method.
+
+        Returns:
+            str: The cluster identifier.
+
+        Raises:
+            ClusterIDUnavailableError: If running in-cluster and fetching the cluster ID fails.
+        """
         if cls._instance is None:
             cls()
         if cls._cluster_id is None:
@@ -174,7 +215,7 @@ def get_cluster_id(cls) -> str:
 def get_user_info(token: str) -> Optional[kubernetes.client.V1TokenReview]:
     """Perform a Kubernetes TokenReview to validate a given token.
 
-    Args:
+    Parameters:
         token: The bearer token to be validated.
 
     Returns:
@@ -221,14 +262,27 @@ class K8SAuthDependency(AuthInterface):  # pylint: disable=too-few-public-method
     """
 
     def __init__(self, virtual_path: str = DEFAULT_VIRTUAL_PATH) -> None:
-        """Initialize the required allowed paths for authorization checks."""
+        """Initialize the required allowed paths for authorization checks.
+
+        Create a K8SAuthDependency configured for performing
+        SubjectAccessReview checks on a specific virtual path.
+
+        Parameters:
+            virtual_path (str): The request path used in SubjectAccessReview
+            non-resource attributes; defaults to DEFAULT_VIRTUAL_PATH.
+
+        Attributes set:
+            virtual_path: Stored `virtual_path` value.
+            skip_userid_check (bool): Flag indicating whether user ID checks
+                                      should be skipped; initialized to False.
+        """
         self.virtual_path = virtual_path
         self.skip_userid_check = False
 
     async def __call__(self, request: Request) -> tuple[str, str, bool, str]:
         """Validate FastAPI Requests for authentication and authorization.
 
-        Args:
+        Parameters:
             request: The FastAPI request object.
 
         Returns:
diff --git a/src/authentication/noop.py b/src/authentication/noop.py
@@ -18,19 +18,31 @@ class NoopAuthDependency(AuthInterface):  # pylint: disable=too-few-public-metho
     """No-op AuthDependency class that bypasses authentication and authorization checks."""
 
     def __init__(self, virtual_path: str = DEFAULT_VIRTUAL_PATH) -> None:
-        """Initialize the required allowed paths for authorization checks."""
+        """Initialize the required allowed paths for authorization checks.
+
+        Create a NoopAuthDependency configured with a virtual path and with
+        user-ID checking disabled.
+
+        Parameters:
+            virtual_path (str): Virtual path context used by the dependency
+                                (defaults to DEFAULT_VIRTUAL_PATH).
+        """
         self.virtual_path = virtual_path
         self.skip_userid_check = True
 
     async def __call__(self, request: Request) -> tuple[str, str, bool, str]:
         """Validate FastAPI Requests for authentication and authorization.
 
-        Args:
-            request: The FastAPI request object.
+        Parameters:
+            request (Request): FastAPI request whose query parameters may contain "user_id".
 
         Returns:
-            The user's UID and username if authentication and authorization succeed
-            user_id check is skipped with noop auth to allow consumers provide user_id
+            tuple[str, str, bool, str]: A 4-tuple containing:
+                - user_id: the value of the "user_id" query parameter if
+                           present, otherwise DEFAULT_USER_UID.
+                - username: DEFAULT_USER_NAME.
+                - skip_userid_check: True to indicate the user ID check is skipped.
+                - token: NO_USER_TOKEN.
         """
         logger.warning(
             "No-op authentication dependency is being used. "
diff --git a/src/authentication/noop_with_token.py b/src/authentication/noop_with_token.py
@@ -29,19 +29,31 @@ class NoopWithTokenAuthDependency(
     """No-op AuthDependency class that bypasses authentication and authorization checks."""
 
     def __init__(self, virtual_path: str = DEFAULT_VIRTUAL_PATH) -> None:
-        """Initialize the required allowed paths for authorization checks."""
+        """Initialize the required allowed paths for authorization checks.
+
+        Parameters:
+            virtual_path (str): Virtual base path used for authorization
+            context; defaults to DEFAULT_VIRTUAL_PATH.
+
+        Notes:
+            Sets the instance attribute `virtual_path` and sets `skip_userid_check` to True.
+        """
         self.virtual_path = virtual_path
         self.skip_userid_check = True
 
     async def __call__(self, request: Request) -> tuple[str, str, bool, str]:
         """Validate FastAPI Requests for authentication and authorization.
 
-        Args:
+        Parameters:
             request: The FastAPI request object.
 
         Returns:
-            The user's UID and username if authentication and authorization succeed
-            user_id check is skipped with noop auth to allow consumers provide user_id
+            tuple[str, str, bool, str]: A 4-tuple containing:
+                - user_id: The value of the "user_id" query parameter or
+                           DEFAULT_USER_UID if absent.
+                - username: DEFAULT_USER_NAME.
+                - skip_userid_check: True to indicate user-id checks are skipped.
+                - user_token: Token extracted from the request headers.
         """
         logger.warning(
             "No-op with token authentication dependency is being used. "
diff --git a/src/authentication/utils.py b/src/authentication/utils.py
@@ -8,11 +8,12 @@
 def extract_user_token(headers: Headers) -> str:
     """Extract the bearer token from an HTTP Authorization header.
 
-    Args:
-        headers: The request headers containing the Authorization value.
+    Parameters:
+        headers (Headers): Incoming request headers from which the
+        Authorization header will be read.
 
     Returns:
-        The extracted bearer token.
+        str: The bearer token string extracted from the header.
 
     Raises:
         HTTPException: If the Authorization header is missing or malformed.
