digitalhub 0.13.4__py3-none-any.whl → 0.14.0__py3-none-any.whl

digitalhub/stores/client/dhcore/configurator.py

@@ -22,54 +22,32 @@ if typing.TYPE_CHECKING:
 
 class ClientDHCoreConfigurator(Configurator):
     """
-    Configurator object used to configure the client.
-
-    The configurator starts reading the credentials from the
-    environment and from the ini file and stores them into the
-    creds_handler object.
-
-    While reading the credentials from the two sources (environment and file),
-    the configurator evaluate if the required keys are present in both sources.
-    If the required keys are not present in both sources, the configurator
-    will rise an error, otherwise decide which source to use.
-
-    Once the credentials are read, the configurator check the current profile
-    name from the ini file, and set it. The default one is __default. The
-    profile is used to discriminate a set of credentials inside the ini file.
-
-    The configurator finally set the authentication type based on the credentials.
-    The logic is the following:
-
-        1. Check for a personal access token. Use it immediately to
-           require a timed access token in an exchange endpoint.
-           Switche then the origin to file and .
-           Set the auth type to EXCHANGE.
-        2. Check for an access token and a refresh token.
-           Set the auth type to OAUTH2.
-        3. Check for username and password.
-           Set the auth type to BASIC.
-        4. If none of the above is true, leave the auth type to None.
+    DHCore client configurator for credential management and authentication.
+
+    Handles loading credentials from environment variables and configuration files,
+    evaluates authentication types, and manages token refresh operations. Supports
+    multiple authentication methods: EXCHANGE (personal access token), OAUTH2
+    (access + refresh tokens), ACCESS_TOKEN (access token only), and BASIC
+    (username + password).
+
+    The configurator automatically determines the best authentication method and
+    handles token exchange for personal access tokens by switching to file-based
+    credential storage.
     """
 
     keys = [*list_enum(CredsEnvVar)]
     required_keys = [CredsEnvVar.DHCORE_ENDPOINT.value]
-    keys_to_unprefix = [
+    keys_to_prefix = [
         CredsEnvVar.DHCORE_REFRESH_TOKEN.value,
         CredsEnvVar.DHCORE_ACCESS_TOKEN.value,
         CredsEnvVar.DHCORE_ISSUER.value,
         CredsEnvVar.DHCORE_CLIENT_ID.value,
+        CredsEnvVar.OAUTH2_TOKEN_ENDPOINT.value,
     ]
 
     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
+        Initialize DHCore configurator and evaluate authentication type.
         """
         super().__init__()
         self._auth_type: str | None = None
@@ -81,20 +59,10 @@ class ClientDHCoreConfigurator(Configurator):
 
     def load_env_vars(self) -> None:
         """
-        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.
+        Load and sanitize credentials from environment variables.
 
-        Returns
-        -------
-        None
-
-        Notes
-        -----
-        This method sanitizes endpoint and issuer URLs to ensure they have
-        proper schemes and removes trailing slashes.
+        Sanitizes endpoint and issuer URLs to ensure proper HTTP/HTTPS schemes
+        and removes trailing slashes.
         """
         env_creds = self._creds_handler.load_from_env(self.keys)
         env_creds = self._sanitize_env_vars(env_creds)
@@ -102,30 +70,25 @@ class ClientDHCoreConfigurator(Configurator):
 
     def _sanitize_env_vars(self, creds: dict) -> dict:
         """
-        Sanitize credentials loaded from environment variables.
+        Sanitize environment variable credentials.
 
-        Validates and normalizes endpoint and issuer URLs from environment
-        variables. Ensures URLs have proper schemes and removes trailing slashes.
+        Validates and normalizes endpoint and issuer URLs. Environment variables
+        use full "DHCORE_" prefixes.
 
         Parameters
         ----------
         creds : dict
-            Raw credentials dictionary loaded from environment variables.
+            Raw credentials from environment variables.
 
         Returns
         -------
         dict
-            Sanitized credentials dictionary with normalized URLs.
+            Sanitized credentials 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])
@@ -133,112 +96,74 @@ class ClientDHCoreConfigurator(Configurator):
 
     def load_file_vars(self) -> None:
         """
-        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
+        Load credentials from configuration file with CLI compatibility.
 
-        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
+        Handles keys without "DHCORE_" prefix for CLI compatibility. Falls back
+        to environment variables for missing endpoint and personal access token values.
         """
-        keys = [*self._remove_prefix_dhcore()]
-        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] = env_creds.get(CredsEnvVar.DHCORE_ENDPOINT.value)
+        file_creds = self._creds_handler.load_from_file(self.keys)
 
         # 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] = env_creds.get(
-                CredsEnvVar.DHCORE_PERSONAL_ACCESS_TOKEN.value
-            )
+        pat = CredsEnvVar.DHCORE_PERSONAL_ACCESS_TOKEN.value
+        if file_creds[pat] is None:
+            file_creds[pat] = self._creds_handler.load_from_env([pat]).get(pat)
+
+        # Because in the response there is no endpoint
+        endpoint = CredsEnvVar.DHCORE_ENDPOINT.value
+        if file_creds[endpoint] is None:
+            file_creds[endpoint] = self._creds_handler.load_from_env([endpoint]).get(endpoint)
 
         file_creds = self._sanitize_file_vars(file_creds)
         self._creds_handler.set_credentials(self._file, file_creds)
 
     def _sanitize_file_vars(self, creds: dict) -> dict:
         """
-        Sanitize credentials loaded from configuration file.
+        Sanitize configuration file credentials.
 
-        Handles the different key formats used in configuration files compared
-        to environment variables. File format omits "DHCORE_" prefix for
-        certain keys for CLI compatibility.
+        Handles different key formats between file and environment variables.
+        File format omits "DHCORE_" prefix for: issuer, client_id, access_token,
+        refresh_token. Full names used for: endpoint, user, password, personal_access_token.
 
         Parameters
         ----------
         creds : dict
-            Raw credentials dictionary loaded from configuration file.
+            Raw credentials from configuration file.
 
         Returns
         -------
         dict
-            Sanitized credentials dictionary with standardized key names
-            and normalized URLs, filtered to include only valid keys.
+            Sanitized credentials with standardized keys and normalized URLs.
 
         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(
-            creds[CredsEnvVar.DHCORE_ISSUER.value.removeprefix("DHCORE_")]
-        )
-        creds[CredsEnvVar.DHCORE_REFRESH_TOKEN.value] = creds[
-            CredsEnvVar.DHCORE_REFRESH_TOKEN.value.removeprefix("DHCORE_")
-        ]
-        creds[CredsEnvVar.DHCORE_ACCESS_TOKEN.value] = creds[
-            CredsEnvVar.DHCORE_ACCESS_TOKEN.value.removeprefix("DHCORE_")
-        ]
-        creds[CredsEnvVar.DHCORE_CLIENT_ID.value] = creds[CredsEnvVar.DHCORE_CLIENT_ID.value.removeprefix("DHCORE_")]
+        creds[CredsEnvVar.DHCORE_ISSUER.value] = self._sanitize_endpoint(creds[CredsEnvVar.DHCORE_ISSUER.value])
         return {k: v for k, v in creds.items() if k in self.keys}
 
     @staticmethod
     def _sanitize_endpoint(endpoint: str | None = None) -> str | None:
         """
-        Sanitize and validate endpoint URL.
+        Validate and normalize endpoint URL.
 
-        Validates that the endpoint URL has a proper HTTP/HTTPS scheme,
-        trims whitespace, and removes trailing slashes for consistency.
+        Ensures proper HTTP/HTTPS scheme, trims whitespace, and removes trailing slashes.
 
         Parameters
         ----------
-        endpoint : str, optional
-            The endpoint URL to sanitize. If None, returns None.
+        endpoint : str
+            Endpoint URL to sanitize.
 
         Returns
         -------
         str or None
-            The sanitized endpoint URL with trailing slash removed,
-            or None if input was None.
+            Sanitized URL 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 lacks http:// or https:// scheme.
         """
         if endpoint is None:
             return
@@ -252,23 +177,17 @@ class ClientDHCoreConfigurator(Configurator):
         """
         Get the configured DHCore backend endpoint.
 
-        Retrieves the DHCore endpoint URL from the current credential source
-        (environment or file based on current origin).
+        Returns the sanitized and validated endpoint URL from current credential source.
 
         Returns
         -------
         str
-            The DHCore backend endpoint URL.
+            DHCore backend endpoint URL.
 
         Raises
         ------
         KeyError
-            If the endpoint is not configured in the current credential source.
-
-        Notes
-        -----
-        The endpoint returned is already sanitized and validated during
-        the credential loading process.
+            If endpoint not configured in current credential source.
         """
         creds = self._creds_handler.get_credentials(self._origin)
         return creds[CredsEnvVar.DHCORE_ENDPOINT.value]
@@ -279,22 +198,10 @@ class ClientDHCoreConfigurator(Configurator):
 
     def change_origin(self) -> None:
         """
-        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.
+        Switch credential source and re-evaluate authentication type.
 
-        Returns
-        -------
-        None
-
-        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.
+        Changes between environment and file credential sources, then re-evaluates
+        authentication type based on the new credentials.
         """
         super().change_origin()
 
@@ -307,29 +214,12 @@ class ClientDHCoreConfigurator(Configurator):
 
     def set_auth_type(self) -> None:
         """
-        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
+        Determine authentication type from available credentials.
 
-        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
+        Evaluates credentials in priority order: EXCHANGE (personal access token),
+        OAUTH2 (access + refresh tokens), ACCESS_TOKEN (access only), BASIC
+        (username + password). For EXCHANGE type, automatically exchanges the
+        personal access token and switches to file-based credentials storage.
         """
         creds = creds_handler.get_credentials(self._origin)
         self._auth_type = self._eval_auth_type(creds)
@@ -343,55 +233,34 @@ class ClientDHCoreConfigurator(Configurator):
 
     def refreshable_auth_types(self) -> bool:
         """
-        Check if the current authentication type supports token refresh.
+        Check if current authentication supports token refresh.
 
-        Determines whether the current authentication method supports
-        automatic token refresh capabilities.
+        Returns True for OAUTH2 (refresh token) and EXCHANGE (personal access token),
+        False for BASIC and ACCESS_TOKEN.
 
         Returns
         -------
         bool
-            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
+            Whether authentication type supports refresh.
         """
         return self._auth_type in [AuthType.OAUTH2.value, AuthType.EXCHANGE.value]
 
     def get_auth_parameters(self, kwargs: dict) -> dict:
         """
-        Add authentication parameters to HTTP request arguments.
+        Add authentication headers/parameters to HTTP request kwargs.
 
-        Modifies the provided kwargs dictionary to include the appropriate
-        authentication headers or parameters based on the current authentication
-        type and available credentials.
+        Adds Authorization Bearer header for token-based auth or auth tuple
+        for basic authentication.
 
         Parameters
         ----------
         kwargs : dict
-            HTTP request keyword arguments to be modified with authentication.
+            HTTP request arguments to modify.
 
         Returns
         -------
         dict
-            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
+            Modified kwargs with authentication parameters.
         """
         creds = creds_handler.get_credentials(self._origin)
         if self._auth_type in (
@@ -411,51 +280,32 @@ class ClientDHCoreConfigurator(Configurator):
 
     def refresh_credentials(self, change_origin: bool = False) -> None:
         """
-        Refresh authentication credentials by obtaining new access tokens.
+        Refresh authentication tokens using OAuth2 flows.
 
-        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.
+        Uses refresh_token grant for OAUTH2 or token exchange for EXCHANGE authentication.
+        On 400/401/403 errors with change_origin=True, attempts to switch credential
+        sources and retry. Saves new credentials to configuration file.
 
         Parameters
         ----------
         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
+            Whether to switch credential sources on auth failure.
 
         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 auth type doesn't support refresh or credentials missing.
         """
         if not self.refreshable_auth_types():
             raise ClientError(f"Auth type {self._auth_type} does not support refresh.")
 
-        # Get refresh endpoint
-        url = self._get_refresh_endpoint()
-
         # Get credentials
         creds = self._creds_handler.get_credentials(self._origin)
 
+        # Get token refresh from creds
+        if (url := creds.get(CredsEnvVar.OAUTH2_TOKEN_ENDPOINT.value)) is None:
+            url = self._get_refresh_endpoint(creds)
+
         # Get client id
         if (client_id := creds.get(CredsEnvVar.DHCORE_CLIENT_ID.value)) is None:
             raise ClientError("Client id not set.")
@@ -491,67 +341,24 @@ class ClientDHCoreConfigurator(Configurator):
         # Read new credentials and propagate to config file
         self._export_new_creds(response.json())
 
-    def _remove_prefix_dhcore(self) -> list[str]:
+    def _get_refresh_endpoint(self, creds: dict) -> str:
         """
-        Remove DHCORE_ prefix from selected credential keys for CLI compatibility.
-
-        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 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:
-            if key in self.keys_to_unprefix:
-                new_list.append(key.removeprefix("DHCORE_"))
-            else:
-                new_list.append(key)
-        return new_list
+        Discover OAuth2 token endpoint from issuer well-known configuration.
 
-    def _get_refresh_endpoint(self) -> str:
-        """
-        Discover the OAuth2 token refresh endpoint from the issuer.
+        Queries /.well-known/openid-configuration to extract token_endpoint for
+        credential refresh operations.
 
-        Queries the OAuth2 issuer's well-known configuration endpoint to
-        discover the token endpoint used for credential refresh operations.
+        Parameters
+        ----------
+        creds : dict
+            Available credential values.
 
         Returns
         -------
         str
-            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
+            Token endpoint URL for credential refresh.
         """
         # Get issuer endpoint
-        creds = self._creds_handler.get_credentials(self._origin)
         endpoint_issuer = creds.get(CredsEnvVar.DHCORE_ISSUER.value)
         if endpoint_issuer is None:
             raise ClientError("Issuer endpoint not set.")
@@ -570,30 +377,22 @@ class ClientDHCoreConfigurator(Configurator):
         **kwargs,
     ) -> Response:
         """
-        Make HTTP request to OAuth2 token refresh endpoint.
+        Make OAuth2 token refresh request.
 
-        Performs a POST request to the OAuth2 token endpoint with the
-        appropriate form-encoded payload for token refresh or exchange.
+        Sends POST request with form-encoded payload using required OAuth2
+        content type and 60-second timeout.
 
         Parameters
         ----------
         url : str
-            The token endpoint URL to call.
+            Token endpoint URL.
         **kwargs : dict
-            Token request parameters such as grant_type, client_id,
-            refresh_token, subject_token, etc.
+            Token request parameters (grant_type, client_id, etc.).
 
         Returns
         -------
         Response
-            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
+            Raw HTTP response for caller handling.
         """
         # Send request to get new access token
         payload = {**kwargs}
@@ -602,30 +401,20 @@ class ClientDHCoreConfigurator(Configurator):
 
     def _eval_auth_type(self, creds: dict) -> str | None:
         """
-        Evaluate authentication type based on available credentials.
+        Determine authentication type from available credentials.
 
-        Analyzes the provided credentials and determines the most appropriate
-        authentication method based on which credential types are available.
+        Evaluates in priority order: EXCHANGE (personal access token), OAUTH2
+        (access + refresh tokens), ACCESS_TOKEN (access only), BASIC (username + password).
 
         Parameters
         ----------
         creds : dict
-            Dictionary containing credential values.
+            Available 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
+            Authentication type from AuthType enum, or None if no valid credentials.
         """
         if creds[CredsEnvVar.DHCORE_PERSONAL_ACCESS_TOKEN.value] is not None:
             return AuthType.EXCHANGE.value
@@ -642,32 +431,24 @@ class ClientDHCoreConfigurator(Configurator):
 
     def _export_new_creds(self, response: dict) -> None:
         """
-        Save new credentials from token refresh response.
+        Save refreshed credentials and switch to file-based storage.
 
-        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.
+        Persists new tokens (access_token, refresh_token, etc.) to configuration
+        file and switches credential origin to file storage.
 
         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.
+            OAuth2 token response with new credentials.
         """
+        for key in self.keys_to_prefix:
+            if key == CredsEnvVar.OAUTH2_TOKEN_ENDPOINT.value:
+                prefix = "oauth2_"
+            else:
+                prefix = "dhcore_"
+            key = key.lower()
+            if key.removeprefix(prefix) in response:
+                response[key] = response.pop(key.removeprefix(prefix))
         creds_handler.write_env(response)
         self.load_file_vars()