[Feature] Add shared credential-refresh lifecycle to AWSCredentialsProvider

src/aws-cpp-sdk-core/include/aws/core/auth/CredentialsRefreshProvider.h

@@ -0,0 +1,57 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0.
+ */
+
+#pragma once
+
+#include <aws/core/Core_EXPORTS.h>
+#include <aws/core/auth/AWSCredentialsProvider.h>
+#include <aws/core/auth/CredentialsRefreshResult.h>
+#include <aws/core/utils/DateTime.h>
+#include <memory>
+
+namespace Aws
+{
+    namespace Internal { class CredentialsRefreshStateImpl; }
+    namespace Auth
+    {
+        /**
+         * A single credential fetch against the underlying source, classified fresh/recoverable/
+         * non-recoverable. Providers implement this to be wrapped by CredentialsRefreshProvider;
+         * the classification drives serve-last-good and backoff.
+         */
+        class AWS_CORE_API CredentialsSource
+        {
+        public:
+            virtual ~CredentialsSource() = default;
+            virtual Aws::Auth::RefreshResult<AWSCredentials> FetchCredentials() = 0;
+        };
+
+        /**
+         * Wraps a CredentialsSource with the shared credentials-refresh lifecycle (caching,
+         * advisory/mandatory windows, jittered backoff, serve-last-good, single in-flight refresh,
+         * invalidation). The wrap is applied only when AWS_NEW_CREDENTIAL_REFRESH_2026 is on; when
+         * off the source provider is used directly, preserving legacy behavior.
+         */
+        class AWS_CORE_API CredentialsRefreshProvider : public AWSCredentialsProvider
+        {
+        public:
+            explicit CredentialsRefreshProvider(std::shared_ptr<CredentialsSource> source);
+            ~CredentialsRefreshProvider() override;
+
+            AWSCredentials GetAWSCredentials() override;
+
+            // Marks cached credentials for refresh after a service rejects them (ExpiredToken/InvalidToken).
+            virtual void Invalidate();
+
+        protected:
+            // Clock for the refresh windows/backoff; defaults to the system clock, overridable for tests.
+            virtual Aws::Utils::DateTime CurrentTime() const;
+
+        private:
+            std::shared_ptr<CredentialsSource> m_source;
+            std::unique_ptr<Aws::Internal::CredentialsRefreshStateImpl> m_refreshState;
+        };
+    } // namespace Auth
+} // namespace Aws

src/aws-cpp-sdk-core/include/aws/core/auth/CredentialsRefreshResult.h

@@ -0,0 +1,58 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0.
+ */
+
+#pragma once
+
+#include <aws/core/Core_EXPORTS.h>
+#include <aws/core/utils/DateTime.h>
+#include <aws/core/utils/memory/stl/AWSString.h>
+#include <aws/crt/Optional.h>
+#include <utility>
+
+namespace Aws
+{
+    namespace Auth
+    {
+        // Result of one credential-source fetch: the return type of CredentialsSource::FetchCredentials(),
+        // so it is public (the refresh engine that consumes it stays internal).
+        template<typename CredentialsT>
+        class RefreshResult
+        {
+        public:
+            enum class Status
+            {
+                Success,        // fresh credentials obtained
+                Recoverable,    // transient failure: back off and keep serving cache
+                NonRecoverable  // will not succeed without customer action: raise + briefly cache the error
+            };
+
+            RefreshResult() = default;
+            RefreshResult(Status status, CredentialsT credentials, Aws::Crt::Optional<Aws::Utils::DateTime> expiration,
+                          Aws::String errorMessage)
+                : status(status), credentials(std::move(credentials)),
+                  expiration(std::move(expiration)), errorMessage(std::move(errorMessage)) {}
+
+            // Named constructors. Only Fresh() carries an expiration.
+            static RefreshResult Fresh(CredentialsT credentials, Aws::Utils::DateTime expiration)
+            {
+                return RefreshResult(Status::Success, std::move(credentials),
+                                     Aws::Crt::Optional<Aws::Utils::DateTime>(expiration), {});
+            }
+            static RefreshResult Recoverable(Aws::String errorMessage = {})
+            {
+                return RefreshResult(Status::Recoverable, CredentialsT{}, {}, std::move(errorMessage));
+            }
+            static RefreshResult NonRecoverable(Aws::String errorMessage)
+            {
+                return RefreshResult(Status::NonRecoverable, CredentialsT{}, {}, std::move(errorMessage));
+            }
+
+            Status status{Status::Recoverable};
+            CredentialsT credentials{};
+            Aws::Crt::Optional<Aws::Utils::DateTime> expiration; // engaged only when status == Success
+            Aws::String errorMessage;
+        };
+    } // namespace Auth
+} // namespace Aws