Merge branch 'main' into carl/doc-improvements

Author: carl-adams-planet

docs/api-planet-auth-config-injection.md

@@ -13,8 +13,8 @@
 
 @click.group(help="my cli main help message")
 @planet_auth_utils.opt_profile
-@planet_auth_utils.opt_client_id
-@planet_auth_utils.opt_client_secret
+@planet_auth_utils.opt_client_id()
+@planet_auth_utils.opt_client_secret()
 @click.pass_context
 def my_cli_main(ctx, auth_profile, auth_client_id, auth_client_secret):
     ctx.ensure_object(dict)

docs/examples/cli/embed-plauth-click.py

@@ -80,6 +80,7 @@ nav:
   - API Reference:
     - Planet Auth: 'api-planet-auth.md'
     - Planet Auth Utils: 'api-planet-auth-utils.md'
+    - Planet Auth Config Injection: 'api-planet-auth-config-injection.md'
   - Examples:
     - Installation: 'examples-installation.md'
     - CLI: 'examples-cli.md'

mkdocs.yml

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/auth.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/auth_client.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/auth_exception.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/constants.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/credential.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/internal/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/logging/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/logging/auth_logger.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/logging/events.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/none/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/none/noop_auth.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/api_clients/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/api_clients/api_client.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/api_clients/authorization_api_client.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/api_clients/device_authorization_api_client.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/api_clients/discovery_api_client.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/api_clients/introspect_api_client.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/api_clients/jwks_api_client.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/api_clients/oidc_request_auth.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/api_clients/revocation_api_client.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/api_clients/token_api_client.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/api_clients/userinfo_api_client.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/auth_client.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/auth_client_default_authenticators.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/auth_client_with_client_pubkey.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/auth_client_with_client_secret.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/auth_clients/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/auth_clients/auth_code_flow.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/auth_clients/client_credentials_flow.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/auth_clients/client_validator.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/auth_clients/device_code_flow.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/auth_clients/resource_owner_flow.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/multi_validator.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/oidc_credential.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,7 +14,7 @@
 
 import jwt
 import time
-from typing import Dict
+from typing import Dict, Optional
 
 import planet_auth.logging.auth_logger
 from planet_auth.credential import Credential
@@ -79,45 +79,68 @@ def _load(self):
 
     def _refresh(self):
         if self._auth_client:
+            # TODO: cleanup?  We did this before we wrote "update_credential_data()"
+            #    We maybe should just be using that now.  Taking that clean-up slow
+            #    since it may have interactions with derived code.
+            #    It seems to me we should be able to collapse the credential.save()
+            #    calls in this file with the superclass.
             new_credentials = self._auth_client.refresh(self._credential.refresh_token())
             new_credentials.set_path(self._credential.path())
             new_credentials.set_storage_provider(self._credential.storage_provider())
             new_credentials.save()
 
+            # self.update_credential(new_credential=new_credentials)
             self._credential = new_credentials
             self._load()
 
-    def pre_request_hook(self):
+    def _refresh_if_needed(self):
         # Reload the file before refreshing. Another process might
         # have done it for us, and save us the network call.
         #
         # Also, if refresh tokens are configured to be one time use,
-        # we want a fresh refresh token. Stale refresh tokens are
-        # invalid in this case.
+        # we want a fresh refresh token. Stale refresh tokens may be
+        # invalid depending on server configuration.
         #
         # Also, it's possible that we have a valid refresh token,
         # but not an access token.  When that's true, we should
         # try to cash in the refresh token.
         #
         # If everything fails, continue with what we have. Let the API
         # we are calling decide if it's good enough.
-        if int(time.time()) > self._refresh_at:
+        now = int(time.time())
+        if now > self._refresh_at:
             try:
                 self._load()
             except Exception as e:  # pylint: disable=broad-exception-caught
                 auth_logger.warning(
-                    msg="Error loading auth token. Continuing with old auth token. Load error: " + str(e)
+                    msg=f"Error loading auth token. Continuing with old configuration and token data. Load error: {str(e)}"
                 )
-        if int(time.time()) > self._refresh_at:
+        if now > self._refresh_at:
             try:
                 self._refresh()
             except Exception as e:  # pylint: disable=broad-exception-caught
                 auth_logger.warning(
-                    msg="Error refreshing auth token. Continuing with old auth token. Refresh error: " + str(e)
+                    msg=f"Error obtaining new or refreshed auth token. Continuing with old configuration and token data. Refresh error: {str(e)}"
                 )
+
+        # This tries to give a client a better error when there is no old
+        # token to fall back to.  But, it is known to cause problems when
+        # auth truly isn't needed, either because the service does not need
+        # it or because it has been mocked out (as in unit test cases).
+        # So, we rely on the warnings to keep the user informed. This might
+        # also result in the user seeing errors from the server - the quality
+        # of which we have no control over.
+        #
+        # if not (self._credential and self._credential.is_loaded()):
+        #     # "refresh" may also be called to initialize in some cases, as in client credentials flow.
+        #     # Continuing with what we have is not an option when we have nothing.
+        #     raise AuthException("Failed to load or obtain a valid access token.")
+
+    def pre_request_hook(self):
+        self._refresh_if_needed()
         super().pre_request_hook()
 
-    def update_credential(self, new_credential: Credential):
+    def update_credential(self, new_credential: Credential) -> None:
         if not isinstance(new_credential, FileBackedOidcCredential):
             raise TypeError(
                 f"{type(self).__name__} does not support {type(new_credential)} credentials.  Use FileBackedOidcCredential."
@@ -126,7 +149,7 @@ def update_credential(self, new_credential: Credential):
         self._refresh_at = 0
         # self._load()  # Mimic __init__.  Don't load, let that happen JIT.
 
-    def update_credential_data(self, new_credential_data: Dict):
+    def update_credential_data(self, new_credential_data: Dict) -> None:
         # This is more different than update_credential() than it may
         # appear. Inherent in being passed a Credential in update_credential()
         # is that it may not yet be loaded from disk, and so deferring
@@ -137,6 +160,11 @@ def update_credential_data(self, new_credential_data: Dict):
         super().update_credential_data(new_credential_data=new_credential_data)
         self._load()
 
+    def credential(self, refresh_if_needed: bool = False) -> Optional[Credential]:
+        if refresh_if_needed:
+            self._refresh_if_needed()
+        return super().credential()
+
 
 class RefreshOrReloginOidcTokenRequestAuthenticator(RefreshingOidcTokenRequestAuthenticator):
     """
@@ -171,5 +199,6 @@ def _refresh(self):
             new_credentials.set_storage_provider(self._credential.storage_provider())
             new_credentials.save()
 
+            # self.update_credential(new_credential=new_credentials)
             self._credential = new_credentials
             self._load()

src/planet_auth/oidc/request_authenticator.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/resources/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/token_validator.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/oidc/util.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/planet_legacy/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

src/planet_auth/planet_legacy/auth_client.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Planet Labs PBC.
+# Copyright 2024-2025 Planet Labs PBC.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.