digitalhub 0.13.0b2__py3-none-any.whl → 0.13.0b4__py3-none-any.whl

digitalhub/stores/client/dhcore/configurator.py

@@ -10,7 +10,7 @@ from requests import request
 
 from digitalhub.stores.client.dhcore.enums import AuthType
 from digitalhub.stores.credentials.configurator import Configurator
-from digitalhub.stores.credentials.enums import CredsEnvVar, CredsOrigin
+from digitalhub.stores.credentials.enums import CredsEnvVar
 from digitalhub.stores.credentials.handler import creds_handler
 from digitalhub.utils.exceptions import ClientError
 from digitalhub.utils.generic_utils import list_enum
@@ -61,10 +61,17 @@ class ClientDHCoreConfigurator(Configurator):
     ]
 
     def __init__(self) -> None:
+        """
+        Initialize the DHCore configurator.
+
+        Sets up the configurator by calling the parent constructor and
+        initializing the authentication type evaluation process.
+
+        Returns
+        -------
+        None
+        """
         super().__init__()
-        self.load_configs()
-        self._origin = self.set_origin()
-        self._current_profile = creds_handler.get_current_env()
         self._auth_type: str | None = None
         self.set_auth_type()
 
@@ -72,34 +79,53 @@ class ClientDHCoreConfigurator(Configurator):
     # Credentials methods
     ##############################
 
-    def load_configs(self) -> str:
-        """
-        Load the configuration from the environment and from the file.
-        """
-        self.load_env_vars()
-        self.load_file_vars()
-
     def load_env_vars(self) -> None:
         """
-        Load the credentials from the environment.
+        Load credentials from environment variables.
+
+        Retrieves DHCore credentials from environment variables, sanitizes
+        them (particularly endpoint URLs), and stores them in the credentials
+        handler for the environment origin.
+
+        Returns
+        -------
+        None
+
+        Notes
+        -----
+        This method sanitizes endpoint and issuer URLs to ensure they have
+        proper schemes and removes trailing slashes.
         """
-        env_creds = {var: self._creds_handler.load_from_env(var) for var in self.keys}
+        env_creds = self._creds_handler.load_from_env(self.keys)
         env_creds = self._sanitize_env_vars(env_creds)
         self._creds_handler.set_credentials(self._env, env_creds)
 
     def _sanitize_env_vars(self, creds: dict) -> dict:
         """
-        Sanitize the env vars. We expect issuer to have the
-        form "DHCORE_ISSUER" in env.
+        Sanitize credentials loaded from environment variables.
+
+        Validates and normalizes endpoint and issuer URLs from environment
+        variables. Ensures URLs have proper schemes and removes trailing slashes.
 
         Parameters
         ----------
         creds : dict
-            Credentials dictionary.
+            Raw credentials dictionary loaded from environment variables.
 
         Returns
         -------
         dict
+            Sanitized credentials dictionary with normalized URLs.
+
+        Raises
+        ------
+        ClientError
+            If endpoint or issuer URLs have invalid schemes.
+
+        Notes
+        -----
+        Environment variables are expected to have the full "DHCORE_" prefix
+        for issuer endpoints.
         """
         creds[CredsEnvVar.DHCORE_ENDPOINT.value] = self._sanitize_endpoint(creds[CredsEnvVar.DHCORE_ENDPOINT.value])
         creds[CredsEnvVar.DHCORE_ISSUER.value] = self._sanitize_endpoint(creds[CredsEnvVar.DHCORE_ISSUER.value])
@@ -107,20 +133,35 @@ class ClientDHCoreConfigurator(Configurator):
 
     def load_file_vars(self) -> None:
         """
-        Load the credentials from the file.
+        Load credentials from configuration file.
+
+        Retrieves DHCore credentials from the .dhcore.ini file, handles
+        compatibility with CLI format (keys without DHCORE_ prefix), and
+        falls back to environment variables for missing endpoint and
+        personal access token values.
+
+        Returns
+        -------
+        None
+
+        Notes
+        -----
+        This method handles the case where:
+        - Endpoint might not be present in file response, falls back to env
+        - Personal access token might not be present, falls back to env
+        - File format uses keys without "DHCORE_" prefix for compatibility
         """
         keys = [*self._remove_prefix_dhcore()]
-        file_creds = {var: self._creds_handler.load_from_file(var) for var in keys}
+        file_creds = self._creds_handler.load_from_file(keys)
+        env_creds = self._creds_handler.load_from_env(self.keys)
 
         # Because in the response there is no endpoint
         if file_creds[CredsEnvVar.DHCORE_ENDPOINT.value] is None:
-            file_creds[CredsEnvVar.DHCORE_ENDPOINT.value] = self._creds_handler.load_from_env(
-                CredsEnvVar.DHCORE_ENDPOINT.value
-            )
+            file_creds[CredsEnvVar.DHCORE_ENDPOINT.value] = env_creds.get(CredsEnvVar.DHCORE_ENDPOINT.value)
 
         # Because in the response there is no personal access token
         if file_creds[CredsEnvVar.DHCORE_PERSONAL_ACCESS_TOKEN.value] is None:
-            file_creds[CredsEnvVar.DHCORE_PERSONAL_ACCESS_TOKEN.value] = self._creds_handler.load_from_env(
+            file_creds[CredsEnvVar.DHCORE_PERSONAL_ACCESS_TOKEN.value] = env_creds.get(
                 CredsEnvVar.DHCORE_PERSONAL_ACCESS_TOKEN.value
             )
 
@@ -129,17 +170,33 @@ class ClientDHCoreConfigurator(Configurator):
 
     def _sanitize_file_vars(self, creds: dict) -> dict:
         """
-        Sanitize the file vars. We expect issuer, client_id and access_token and
-        refresh_token to not have the form "DHCORE_" in the file.
+        Sanitize credentials loaded from configuration file.
+
+        Handles the different key formats used in configuration files compared
+        to environment variables. File format omits "DHCORE_" prefix for
+        certain keys for CLI compatibility.
 
         Parameters
         ----------
         creds : dict
-            Credentials dictionary.
+            Raw credentials dictionary loaded from configuration file.
 
         Returns
         -------
         dict
+            Sanitized credentials dictionary with standardized key names
+            and normalized URLs, filtered to include only valid keys.
+
+        Raises
+        ------
+        ClientError
+            If endpoint or issuer URLs have invalid schemes.
+
+        Notes
+        -----
+        File format expects these keys without "DHCORE_" prefix:
+        - issuer, client_id, access_token, refresh_token
+        But uses full names for: endpoint, user, password, personal_access_token
         """
         creds[CredsEnvVar.DHCORE_ENDPOINT.value] = self._sanitize_endpoint(creds[CredsEnvVar.DHCORE_ENDPOINT.value])
         creds[CredsEnvVar.DHCORE_ISSUER.value] = self._sanitize_endpoint(
@@ -157,12 +214,31 @@ class ClientDHCoreConfigurator(Configurator):
     @staticmethod
     def _sanitize_endpoint(endpoint: str | None = None) -> str | None:
         """
-        Sanitize the endpoint.
+        Sanitize and validate endpoint URL.
+
+        Validates that the endpoint URL has a proper HTTP/HTTPS scheme,
+        trims whitespace, and removes trailing slashes for consistency.
+
+        Parameters
+        ----------
+        endpoint : str, optional
+            The endpoint URL to sanitize. If None, returns None.
 
         Returns
         -------
-        str | None
-            The sanitized endpoint.
+        str or None
+            The sanitized endpoint URL with trailing slash removed,
+            or None if input was None.
+
+        Raises
+        ------
+        ClientError
+            If the endpoint does not start with http:// or https://.
+
+        Notes
+        -----
+        This method ensures endpoint URLs are properly formatted for
+        HTTP requests and prevents common URL formatting issues.
         """
         if endpoint is None:
             return
@@ -172,31 +248,27 @@ class ClientDHCoreConfigurator(Configurator):
         endpoint = endpoint.strip()
         return endpoint.removesuffix("/")
 
-    def check_config(self) -> None:
+    def get_endpoint(self) -> str:
         """
-        Check if the config is valid.
+        Get the configured DHCore backend endpoint.
 
-        Parameters
-        ----------
-        config : dict
-            Configuration dictionary.
+        Retrieves the DHCore endpoint URL from the current credential source
+        (environment or file based on current origin).
 
         Returns
         -------
-        None
-        """
-        if (current := creds_handler.get_current_env()) != self._current_profile:
-            self.load_file_vars()
-            self._current_profile = current
+        str
+            The DHCore backend endpoint URL.
 
-    def get_endpoint(self) -> str:
-        """
-        Get the DHCore endpoint.
+        Raises
+        ------
+        KeyError
+            If the endpoint is not configured in the current credential source.
 
-        Returns
-        -------
-        str
-            The endpoint.
+        Notes
+        -----
+        The endpoint returned is already sanitized and validated during
+        the credential loading process.
         """
         creds = self._creds_handler.get_credentials(self._origin)
         return creds[CredsEnvVar.DHCORE_ENDPOINT.value]
@@ -205,70 +277,59 @@ class ClientDHCoreConfigurator(Configurator):
     # Origin methods
     ##############################
 
-    def set_origin(self) -> str:
+    def change_origin(self) -> None:
         """
-        Evaluate the default origin from the credentials.
+        Change the credentials origin and re-evaluate authentication type.
+
+        Switches the credential source (between environment and file) and
+        re-evaluates the authentication type based on the new credential set.
+        This is typically called when the current credential source fails
+        or when switching contexts.
 
         Returns
         -------
-        str
-            The origin.
-        """
-        origin = CredsOrigin.ENV.value
-
-        env_creds = self._creds_handler.get_credentials(self._env)
-        missing_env = self._check_credentials(env_creds)
-
-        file_creds = self._creds_handler.get_credentials(self._file)
-        missing_file = self._check_credentials(file_creds)
-
-        msg = ""
-        if missing_env:
-            msg = f"Missing required vars in env: {', '.join(missing_env)}"
-            origin = CredsOrigin.FILE.value
-        elif missing_file:
-            msg += f"Missing required vars in .dhcore.ini file: {', '.join(missing_file)}"
-
-        if missing_env and missing_file:
-            raise ClientError(msg)
-
-        return origin
+        None
 
-    def change_origin(self) -> None:
-        """
-        Change the origin of the credentials.
+        Notes
+        -----
+        This method extends the parent class behavior by also re-evaluating
+        the authentication type, which may change based on different
+        credentials available in the new source.
         """
-        if self._origin == CredsOrigin.ENV.value:
-            self.change_to_file()
-        else:
-            self.change_to_env()
+        super().change_origin()
 
         # Re-evaluate the auth type
         self.set_auth_type()
 
-    def change_to_file(self) -> None:
-        """
-        Change the origin to file. Re-evaluate the auth type.
-        """
-        self._origin = CredsOrigin.FILE.value
-
-    def change_to_env(self) -> None:
-        """
-        Change the origin to env. Re-evaluate the auth type.
-        """
-        self._origin = CredsOrigin.ENV.value
-
     ##############################
     # Auth methods
     ##############################
 
     def set_auth_type(self) -> None:
         """
-        Evaluate the auth type from the credentials.
+        Evaluate and set the authentication type from available credentials.
+
+        Analyzes the available credentials and determines the appropriate
+        authentication method based on the following priority:
+        1. EXCHANGE - Personal access token available
+        2. OAUTH2 - Access token and refresh token available
+        3. ACCESS_TOKEN - Only access token available
+        4. BASIC - Username and password available
+        5. None - No valid credentials found
+
+        For EXCHANGE authentication, automatically performs token exchange
+        and switches to file-based credential storage.
 
         Returns
         -------
         None
+
+        Notes
+        -----
+        When EXCHANGE authentication is detected, this method automatically:
+        - Performs credential refresh to exchange the personal access token
+        - Changes origin to file-based storage for the new tokens
+        - Updates the authentication type accordingly
         """
         creds = creds_handler.get_credentials(self._origin)
         self._auth_type = self._eval_auth_type(creds)
@@ -276,39 +337,68 @@ class ClientDHCoreConfigurator(Configurator):
         # Therefore, we change the origin to file, where the refresh token is written.
         # We also try to fetch the PAT from both env and file
         if self._auth_type == AuthType.EXCHANGE.value:
-            self.get_new_access_token(change_origin=True)
+            self.refresh_credentials(change_origin=True)
             # Just to ensure we get the right source from file
             self.change_to_file()
 
     def refreshable_auth_types(self) -> bool:
         """
-        Check if the auth type is refreshable.
+        Check if the current authentication type supports token refresh.
+
+        Determines whether the current authentication method supports
+        automatic token refresh capabilities.
 
         Returns
         -------
         bool
-            True if the auth type is refreshable, False otherwise.
+            True if the authentication type supports refresh (OAUTH2 or EXCHANGE),
+            False otherwise (BASIC or ACCESS_TOKEN).
+
+        Notes
+        -----
+        Only OAUTH2 and EXCHANGE authentication types support refresh:
+        - OAUTH2: Uses refresh token to get new access tokens
+        - EXCHANGE: Uses personal access token for token exchange
+        - BASIC and ACCESS_TOKEN do not support refresh
         """
         return self._auth_type in [AuthType.OAUTH2.value, AuthType.EXCHANGE.value]
 
     def get_auth_parameters(self, kwargs: dict) -> dict:
         """
-        Get the authentication header for the request.
-        It is given for granted that the auth type is set and that,
-        if the auth type is EXCHANGE, the refresh token is set.
+        Add authentication parameters to HTTP request arguments.
+
+        Modifies the provided kwargs dictionary to include the appropriate
+        authentication headers or parameters based on the current authentication
+        type and available credentials.
 
         Parameters
         ----------
         kwargs : dict
-            Keyword arguments to pass to the request.
+            HTTP request keyword arguments to be modified with authentication.
 
         Returns
         -------
         dict
-            Authentication parameters.
+            The modified kwargs dictionary with authentication parameters added.
+
+        Notes
+        -----
+        Authentication is added based on auth type:
+        - OAUTH2/EXCHANGE/ACCESS_TOKEN: Adds Authorization Bearer header
+        - BASIC: Adds auth tuple with username/password
+        - None: No authentication added
+
+        The method assumes that:
+        - Authentication type has been properly set
+        - For EXCHANGE type, refresh token has been obtained
+        - Required credentials are available for the current auth type
         """
         creds = creds_handler.get_credentials(self._origin)
-        if self._auth_type in (AuthType.EXCHANGE.value, AuthType.OAUTH2.value, AuthType.ACCESS_TOKEN.value):
+        if self._auth_type in (
+            AuthType.EXCHANGE.value,
+            AuthType.OAUTH2.value,
+            AuthType.ACCESS_TOKEN.value,
+        ):
             access_token = creds[CredsEnvVar.DHCORE_ACCESS_TOKEN.value]
             if "headers" not in kwargs:
                 kwargs["headers"] = {}
@@ -319,18 +409,43 @@ class ClientDHCoreConfigurator(Configurator):
             kwargs["auth"] = (user, password)
         return kwargs
 
-    def get_new_access_token(self, change_origin: bool = False) -> None:
+    def refresh_credentials(self, change_origin: bool = False) -> None:
         """
-        Get a new access token.
+        Refresh authentication credentials by obtaining new access tokens.
+
+        Performs credential refresh using either OAuth2 refresh token flow
+        or personal access token exchange, depending on the current
+        authentication type. Updates stored credentials with new tokens.
 
         Parameters
         ----------
-        change_origin : bool, optional
-            Whether to change the origin of the credentials, by default False
+        change_origin : bool, default False
+            Whether to allow changing credential source if refresh fails.
+            If True and refresh fails, attempts to switch credential sources
+            and retry once.
 
         Returns
         -------
         None
+
+        Raises
+        ------
+        ClientError
+            If the authentication type doesn't support refresh, if required
+            credentials are missing, or if refresh fails and change_origin
+            is False.
+
+        Notes
+        -----
+        Refresh behavior by authentication type:
+        - OAUTH2: Uses refresh_token grant to get new access/refresh tokens
+        - EXCHANGE: Uses token exchange with personal access token
+
+        If refresh fails with 400/401/403 status and change_origin=True,
+        attempts to switch credential sources and retry once.
+
+        New credentials are automatically saved to the configuration file
+        and the origin is switched to file-based storage.
         """
         if not self.refreshable_auth_types():
             raise ClientError(f"Auth type {self._auth_type} does not support refresh.")
@@ -347,7 +462,7 @@ class ClientDHCoreConfigurator(Configurator):
 
         # Handling of token exchange or refresh
         if self._auth_type == AuthType.OAUTH2.value:
-            response = self._call_refresh_token_endpoint(
+            response = self._call_refresh_endpoint(
                 url,
                 client_id=client_id,
                 refresh_token=creds.get(CredsEnvVar.DHCORE_REFRESH_TOKEN.value),
@@ -355,7 +470,7 @@ class ClientDHCoreConfigurator(Configurator):
                 scope="credentials",
             )
         elif self._auth_type == AuthType.EXCHANGE.value:
-            response = self._call_refresh_token_endpoint(
+            response = self._call_refresh_endpoint(
                 url,
                 client_id=client_id,
                 subject_token=creds.get(CredsEnvVar.DHCORE_PERSONAL_ACCESS_TOKEN.value),
@@ -367,47 +482,37 @@ class ClientDHCoreConfigurator(Configurator):
         # Change origin of creds if needed
         if response.status_code in (400, 401, 403):
             if not change_origin:
-                raise ClientError("Unable to refresh token. Please check your credentials.")
-            self.change_origin()
-            self.get_new_access_token(change_origin=False)
+                raise ClientError("Unable to refresh credentials. Please check your credentials.")
+            self.eval_change_origin()
+            self.refresh_credentials(change_origin=False)
 
         response.raise_for_status()
 
         # Read new credentials and propagate to config file
         self._export_new_creds(response.json())
 
-    def _export_new_creds(self, response: dict) -> None:
-        """
-        Set new credentials.
-
-        Parameters
-        ----------
-        response : dict
-            Response from refresh token endpoint.
-
-        Returns
-        -------
-        None
-        """
-        creds_handler.write_env(response)
-        self.load_file_vars()
-
-        # Change current origin to file because of refresh
-        self._origin = CredsOrigin.FILE.value
-
     def _remove_prefix_dhcore(self) -> list[str]:
         """
-        Remove prefix from selected keys. (Compatibility with CLI)
+        Remove DHCORE_ prefix from selected credential keys for CLI compatibility.
 
-        Parameters
-        ----------
-        keys : list[str]
-            List of keys.
+        Creates a list of credential key names with "DHCORE_" prefix removed
+        from specific keys that are stored without the prefix in configuration
+        files for compatibility with CLI tools.
 
         Returns
         -------
         list[str]
-            List of keys without prefix.
+            List of credential keys with selective prefix removal applied.
+
+        Notes
+        -----
+        Keys that have prefix removed (defined in keys_to_unprefix):
+        - DHCORE_REFRESH_TOKEN -> refresh_token
+        - DHCORE_ACCESS_TOKEN -> access_token
+        - DHCORE_ISSUER -> issuer
+        - DHCORE_CLIENT_ID -> client_id
+
+        Other keys retain their full names for consistency.
         """
         new_list = []
         for key in self.keys:
@@ -419,12 +524,31 @@ class ClientDHCoreConfigurator(Configurator):
 
     def _get_refresh_endpoint(self) -> str:
         """
-        Get the refresh endpoint.
+        Discover the OAuth2 token refresh endpoint from the issuer.
+
+        Queries the OAuth2 issuer's well-known configuration endpoint to
+        discover the token endpoint used for credential refresh operations.
 
         Returns
         -------
         str
-            Refresh endpoint.
+            The token endpoint URL for credential refresh.
+
+        Raises
+        ------
+        ClientError
+            If the issuer endpoint is not configured.
+        HTTPError
+            If the well-known configuration endpoint is not accessible.
+        KeyError
+            If the token_endpoint is not found in the issuer configuration.
+
+        Notes
+        -----
+        This method follows the OAuth2/OpenID Connect discovery standard by:
+        1. Accessing the issuer's /.well-known/openid-configuration endpoint
+        2. Extracting the token_endpoint from the configuration
+        3. Using this endpoint for subsequent token refresh operations
         """
         # Get issuer endpoint
         creds = self._creds_handler.get_credentials(self._origin)
@@ -440,25 +564,36 @@ class ClientDHCoreConfigurator(Configurator):
         r.raise_for_status()
         return r.json().get("token_endpoint")
 
-    def _call_refresh_token_endpoint(
+    def _call_refresh_endpoint(
         self,
         url: str,
         **kwargs,
     ) -> Response:
         """
-        Call the refresh token endpoint.
+        Make HTTP request to OAuth2 token refresh endpoint.
+
+        Performs a POST request to the OAuth2 token endpoint with the
+        appropriate form-encoded payload for token refresh or exchange.
 
         Parameters
         ----------
         url : str
-            Refresh token endpoint.
-        kwargs : dict
-            Keyword arguments to pass to the request.
+            The token endpoint URL to call.
+        **kwargs : dict
+            Token request parameters such as grant_type, client_id,
+            refresh_token, subject_token, etc.
 
         Returns
         -------
         Response
-            Response object.
+            The HTTP response object from the token endpoint.
+
+        Notes
+        -----
+        This method:
+        - Uses application/x-www-form-urlencoded content type as required by OAuth2
+        - Sets a 60-second timeout for the request
+        - Returns the raw response for caller to handle status and parsing
         """
         # Send request to get new access token
         payload = {**kwargs}
@@ -466,6 +601,32 @@ class ClientDHCoreConfigurator(Configurator):
         return request("POST", url, data=payload, headers=headers, timeout=60)
 
     def _eval_auth_type(self, creds: dict) -> str | None:
+        """
+        Evaluate authentication type based on available credentials.
+
+        Analyzes the provided credentials and determines the most appropriate
+        authentication method based on which credential types are available.
+
+        Parameters
+        ----------
+        creds : dict
+            Dictionary containing credential values.
+
+        Returns
+        -------
+        str or None
+            The determined authentication type from AuthType enum, or None
+            if no valid authentication method can be determined.
+
+        Notes
+        -----
+        Authentication type priority (checked in order):
+        1. EXCHANGE - Personal access token is available
+        2. OAUTH2 - Both access token and refresh token are available
+        3. ACCESS_TOKEN - Only access token is available
+        4. BASIC - Both username and password are available
+        5. None - No valid credential combination found
+        """
         if creds[CredsEnvVar.DHCORE_PERSONAL_ACCESS_TOKEN.value] is not None:
             return AuthType.EXCHANGE.value
         if (
@@ -478,3 +639,37 @@ class ClientDHCoreConfigurator(Configurator):
         if creds[CredsEnvVar.DHCORE_USER.value] is not None and creds[CredsEnvVar.DHCORE_PASSWORD.value] is not None:
             return AuthType.BASIC.value
         return None
+
+    def _export_new_creds(self, response: dict) -> None:
+        """
+        Save new credentials from token refresh response.
+
+        Takes the response from a successful token refresh operation and
+        persists the new credentials to the configuration file, then
+        reloads file-based credentials and switches to file origin.
+
+        Parameters
+        ----------
+        response : dict
+            Token response containing new access_token, refresh_token,
+            and other credential information.
+
+        Returns
+        -------
+        None
+
+        Notes
+        -----
+        This method:
+        1. Writes new credentials to the configuration file
+        2. Reloads file-based credentials to ensure consistency
+        3. Changes current origin to file since new tokens are file-based
+
+        The response typically contains access_token, refresh_token,
+        token_type, expires_in, and other OAuth2 standard fields.
+        """
+        creds_handler.write_env(response)
+        self.load_file_vars()
+
+        # Change current origin to file because of refresh
+        self.change_to_file()