Warn when we see passwords where they are not needed. (#10)

* Warn when we see passwords where they are not needed.

* cleanup docs

Author: carl-alexander-adams

src/planet_auth/auth_client.py

@@ -260,7 +260,6 @@ def login(
                 a browser window.
             allow_tty_prompt: specify whether login is permitted to request
                 input from the terminal.
-
         Returns:
             Upon successful login, a Credential will be returned. The returned
                 value will be in memory only. It is the responsibility of the

src/planet_auth/oidc/auth_client.py

@@ -28,6 +28,10 @@
 from planet_auth.oidc.api_clients.userinfo_api_client import UserinfoApiClient
 from planet_auth.oidc.api_clients.token_api_client import TokenApiClient
 from planet_auth.oidc.oidc_credential import FileBackedOidcCredential
+import planet_auth.logging.auth_logger
+
+
+auth_logger = planet_auth.logging.auth_logger.getAuthLogger()
 
 
 class OidcAuthClientConfig(AuthClientConfig, ABC):
@@ -426,6 +430,44 @@ def login(
             **kwargs,
         )
 
+    def _warn_password_kwarg(self, **kwargs):
+        """
+        Helper function for _oidc_flow_login implementations to offer guidance to users
+        and developers when options are unnecessary and will be ignored.
+        """
+        if "password" in kwargs:
+            if kwargs["password"]:
+                # Safety check. "password" is a legitimate kwarg for some OAuth flows
+                # like Resource Owner Flow.  But, it should never be provided to the client
+                # of other flows such as Auth Code or Device Code flows.
+                # We could simply ignore it in the kwargs, but it's a good opportunity
+                # to improve user or developer security practices.
+                warning_msg = (
+                    "Supplying your password is not a supported option for the current login process. "
+                    "Protect your password. Do not expose your password unnecessarily."
+                )
+                # If we decide we want to not just warn, but halt user interactive
+                # clients, uncomment this:
+                # if allow_open_browser or allow_tty_prompt:
+                #     raise AuthCodeAuthClientException(message=warning_msg)
+                auth_logger.warning(msg=warning_msg)
+
+    def _warn_ignored_kwargs(self, ignore_kws: list, **kwargs):
+        """
+        Helper function for _oidc_flow_login implementations to offer guidance to users
+        and developers when options are unnecessary and will be ignored.  This is mostly
+        to steer users away from habitually passing unnecessary arguments. OAuth flows
+        behave differently enough that extra data through the generic login() kwargs
+        is a problem we can anticipate.
+        """
+        for ignore_kw in ignore_kws:
+            if ignore_kw in kwargs:
+                if kwargs[ignore_kw]:
+                    auth_logger.debug(
+                        msg=f'Ignoring "{ignore_kw}" argument to login. '
+                        "It is not used for the current login process."
+                    )
+
     @abstractmethod
     def _oidc_flow_login(
         self,

src/planet_auth/oidc/auth_clients/auth_code_flow.py

@@ -132,6 +132,9 @@ def _oidc_flow_login(
             A FileBackedOidcCredential object
         """
 
+        self._warn_password_kwarg(**kwargs)
+        self._warn_ignored_kwargs(["username", "password", "client_id", "client_secret"], **kwargs)
+
         pkce_code_verifier, pkce_code_challenge = create_pkce_challenge_verifier_pair()
         if allow_open_browser:
             redirect_uri = self._authcode_client_config.local_redirect_uri()

src/planet_auth/oidc/auth_clients/client_credentials_flow.py

@@ -97,6 +97,8 @@ def _oidc_flow_login(
         extra: Optional[dict],
         **kwargs,
     ) -> FileBackedOidcCredential:
+        self._warn_password_kwarg(**kwargs)
+        self._warn_ignored_kwargs(["username", "password"], **kwargs)
         return FileBackedOidcCredential(
             self.token_client().get_token_from_client_credentials(
                 client_id=self._ccauth_client_config.client_id(),
@@ -144,6 +146,8 @@ def _oidc_flow_login(
         extra: Optional[dict],
         **kwargs,
     ):
+        self._warn_password_kwarg(**kwargs)
+        self._warn_ignored_kwargs(["username", "password"], **kwargs)
         return FileBackedOidcCredential(
             self.token_client().get_token_from_client_credentials(
                 client_id=self._pubkey_client_config.client_id(),

src/planet_auth/oidc/auth_clients/device_code_flow.py

@@ -161,6 +161,9 @@ def _oidc_flow_login(
          Returns:
             A FileBackedOidcCredential object
         """
+        self._warn_password_kwarg(**kwargs)
+        self._warn_ignored_kwargs(["username", "password", "client_id", "client_secret"], **kwargs)
+
         if not allow_tty_prompt:
             # Without a TTY to confirm the authorization code with the user,
             # the client using this library really must use device_login_initiate and