boto3-refresh-session 3.0.3__py3-none-any.whl → 5.0.0__py3-none-any.whl

boto3_refresh_session/__init__.py

@@ -3,13 +3,13 @@ __all__ = []
 from . import exceptions, session
 from .exceptions import *
 from .methods.custom import *
-from .methods.ecs import *
+from .methods.iot import *
 from .methods.sts import *
 from .session import *
 
 __all__.extend(session.__all__)
 __all__.extend(exceptions.__all__)
-__version__ = "3.0.3"
+__version__ = "5.0.0"
 __title__ = "boto3-refresh-session"
 __author__ = "Mike Letts"
 __maintainer__ = "Mike Letts"

boto3_refresh_session/exceptions.py

@@ -1,5 +1,7 @@
 __all__ = ["BRSError", "BRSWarning"]
 
+import warnings
+
 
 class BRSError(Exception):
     """The base exception for boto3-refresh-session.
@@ -39,3 +41,9 @@ class BRSWarning(UserWarning):
 
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}({self.message!r})"
+
+    @classmethod
+    def warn(cls, message: str, *, stacklevel: int = 2):
+        """Emits a BRSWarning with a consistent stacklevel."""
+
+        warnings.warn(cls(message), stacklevel=stacklevel)

boto3_refresh_session/methods/__init__.py

@@ -1,12 +1,10 @@
 __all__ = []
 
-# TODO: import iot submodules when finished
-from . import custom, ecs, sts
-from .custom import CustomRefreshableSession
-from .ecs import ECSRefreshableSession
-from .sts import STSRefreshableSession
+from . import custom, iot, sts
+from .custom import *
+from .iot import *
+from .sts import *
 
-# TODO: add iot submodules to __all__ when finished
 __all__.extend(custom.__all__)
-__all__.extend(ecs.__all__)
+__all__.extend(iot.__all__)
 __all__.extend(sts.__all__)

boto3_refresh_session/methods/custom.py

@@ -71,7 +71,7 @@ class CustomRefreshableSession(BaseRefreshableSession, registry_key="custom"):
         **kwargs,
     ):
         if "refresh_method" in kwargs:
-            BRSWarning(
+            BRSWarning.warn(
                 "'refresh_method' cannot be set manually. "
                 "Reverting to 'custom'."
             )

boto3_refresh_session/methods/iot/__init__.py

@@ -0,0 +1,7 @@
+__all__ = []
+
+from . import core
+from .core import IoTRefreshableSession
+from .x509 import IOTX509RefreshableSession
+
+__all__.extend(core.__all__)

boto3_refresh_session/methods/iot/{core.typed → core.py}

@@ -6,28 +6,16 @@ from typing import get_args
 
 from ...exceptions import BRSError
 from ...utils import (
-    BaseRefreshableSession, 
-    BRSSession,
-    CredentialProvider, 
-    IoTAuthenticationMethod, 
-    Registry,
+    BaseIoTRefreshableSession,
+    BaseRefreshableSession,
+    IoTAuthenticationMethod,
 )
 
 
-class BaseIoTRefreshableSession(
-    Registry[IoTAuthenticationMethod],
-    CredentialProvider,
-    BRSSession,
-    registry_key="__iot_sentinel__",
-):
-    def __init__(self, **kwargs):
-        super().__init__(**kwargs)
-
-
 class IoTRefreshableSession(BaseRefreshableSession, registry_key="iot"):
     def __new__(
         cls,
-        authentication_method: IoTAuthenticationMethod = "certificate",
+        authentication_method: IoTAuthenticationMethod = "x509",
         **kwargs,
     ) -> BaseIoTRefreshableSession:
         if authentication_method not in (

boto3_refresh_session/methods/iot/x509.py

@@ -0,0 +1,336 @@
+__all__ = ["IOTX509RefreshableSession"]
+
+import json
+import re
+from pathlib import Path
+from typing import cast
+from urllib.parse import ParseResult, urlparse
+
+from awscrt.exceptions import AwsCrtError
+from awscrt.http import HttpClientConnection, HttpRequest
+from awscrt.io import (
+    ClientBootstrap,
+    ClientTlsContext,
+    DefaultHostResolver,
+    EventLoopGroup,
+    Pkcs11Lib,
+    TlsConnectionOptions,
+    TlsContextOptions,
+)
+
+from ...exceptions import BRSError, BRSWarning
+from ...utils import (
+    PKCS11,
+    AWSCRTResponse,
+    Identity,
+    TemporaryCredentials,
+    refreshable_session,
+)
+from .core import BaseIoTRefreshableSession
+
+
+@refreshable_session
+class IOTX509RefreshableSession(
+    BaseIoTRefreshableSession, registry_key="x509"
+):
+    """A :class:`boto3.session.Session` object that automatically refreshes
+    temporary credentials returned by the IoT Core credential provider.
+
+    Parameters
+    ----------
+    endpoint : str
+        The endpoint URL for the IoT Core credential provider. Must contain
+        '.credentials.iot.'.
+    role_alias : str
+        The IAM role alias to use when requesting temporary credentials.
+    certificate : str | bytes
+        The X.509 certificate to use when requesting temporary credentials.
+        ``str`` represents the file path to the certificate, while ``bytes``
+        represents the actual certificate data.
+    thing_name : str, optional
+        The name of the IoT thing to use when requesting temporary
+        credentials. Default is None.
+    private_key : str | bytes | None, optional
+        The private key to use when requesting temporary credentials. ``str``
+        represents the file path to the private key, while ``bytes``
+        represents the actual private key data. Optional only if ``pkcs11``
+        is provided. Default is None.
+    pkcs11 : PKCS11, optional
+        The PKCS#11 library to use when requesting temporary credentials. If
+        provided, ``private_key`` must be None.
+    ca : str | bytes | None, optional
+        The CA certificate to use when verifying the IoT Core endpoint. ``str``
+        represents the file path to the CA certificate, while ``bytes``
+        represents the actual CA certificate data. Default is None.
+    verify_peer : bool, optional
+        Whether to verify the CA certificate when establishing the TLS
+        connection. Default is True.
+    timeout : float | int | None, optional
+        The timeout for the TLS connection in seconds. Default is 10.0.
+    duration_seconds : int | None, optional
+        The duration for which the temporary credentials are valid, in
+        seconds. Cannot exceed the value declared in the IAM policy.
+        Default is None.
+
+    Notes
+    -----
+    Gavin Adams at AWS was a major influence on this implementation.
+    Thank you, Gavin!
+    """
+
+    def __init__(
+        self,
+        endpoint: str,
+        role_alias: str,
+        certificate: str | bytes,
+        thing_name: str | None = None,
+        private_key: str | bytes | None = None,
+        pkcs11: PKCS11 | None = None,
+        ca: str | bytes | None = None,
+        verify_peer: bool = True,
+        timeout: float | int | None = None,
+        duration_seconds: int | None = None,
+        **kwargs,
+    ):
+        # initializing BRSSession
+        super().__init__(refresh_method="iot-x509", **kwargs)
+
+        # initializing public attributes
+        self.endpoint = self._normalize_iot_credential_endpoint(
+            endpoint=endpoint
+        )
+        self.role_alias = role_alias
+        self.certificate = certificate
+        self.thing_name = thing_name
+        self.private_key = private_key
+        self.pkcs11 = pkcs11
+        self.ca = ca
+        self.verify_peer = verify_peer
+        self.timeout = 10.0 if timeout is None else timeout
+        self.duration_seconds = duration_seconds
+
+        # loading X.509 certificate if presented as a string, which
+        # is presumed to be the file path.
+        # if presented as bytes then self.certificate is presumed to be
+        # the actual certificate itself
+        if self.certificate and isinstance(self.certificate, str):
+            self.certificate = (
+                Path(self.certificate).expanduser().resolve().read_bytes()
+            )
+
+        # either private_key or pkcs11 must be provided
+        if self.private_key is None and self.pkcs11 is None:
+            raise BRSError(
+                "Either 'private_key' or 'pkcs11' must be provided."
+            )
+
+        # . . . but both cannot be provided!
+        if self.private_key is not None and self.pkcs11 is not None:
+            raise BRSError(
+                "Only one of 'private_key' or 'pkcs11' can be provided."
+            )
+
+        # if the provided private_key is bytes then it's presumed to be
+        # the actual private key. but if it's string then it's presumed
+        # to be the file path
+        if self.private_key and isinstance(self.private_key, str):
+            self.private_key = (
+                Path(self.private_key).expanduser().resolve().read_bytes()
+            )
+
+        # verifying PKCS#11 dict
+        if self.pkcs11:
+            self.pkcs11 = self._validate_pkcs11(pkcs11=self.pkcs11)
+
+        # ca is like many other attributes in that str implies file location
+        if self.ca and isinstance(self.ca, str):
+            self.ca = Path(self.ca).expanduser().resolve().read_bytes()
+
+    def _get_credentials(self) -> TemporaryCredentials:
+        url = urlparse(
+            f"https://{self.endpoint}/role-aliases/{self.role_alias}"
+            "/credentials"
+        )
+        request = HttpRequest("GET", url.path)
+        request.headers.add("host", str(url.hostname))
+        if self.thing_name:
+            request.headers.add("x-amzn-iot-thingname", self.thing_name)
+        if self.duration_seconds:
+            request.headers.add(
+                "x-amzn-iot-credential-duration-seconds",
+                str(self.duration_seconds),
+            )
+        response = AWSCRTResponse()
+        port = 443 if not url.port else url.port
+        connection = (
+            self._mtls_client_connection(url=url, port=port)
+            if not self.pkcs11
+            else self._mtls_pkcs11_client_connection(url=url, port=port)
+        )
+
+        try:
+            stream = connection.request(
+                request, response.on_response, response.on_body
+            )
+            stream.activate()
+            stream.completion_future.result(float(self.timeout))
+        finally:
+            try:
+                connection.close()
+            except Exception:
+                ...
+
+        if response.status_code == 200:
+            credentials = json.loads(response.body.decode("utf-8"))[
+                "credentials"
+            ]
+            return {
+                "access_key": credentials["accessKeyId"],
+                "secret_key": credentials["secretAccessKey"],
+                "token": credentials["sessionToken"],
+                "expiry_time": credentials["expiration"],
+            }
+        else:
+            raise BRSError(
+                "Error getting credentials: "
+                f"{json.loads(response.body.decode())}"
+            )
+
+    def _mtls_client_connection(
+        self, url: ParseResult, port: int
+    ) -> HttpClientConnection:
+        event_loop_group: EventLoopGroup = EventLoopGroup()
+        host_resolver: DefaultHostResolver = DefaultHostResolver(
+            event_loop_group
+        )
+        bootstrap: ClientBootstrap = ClientBootstrap(
+            event_loop_group, host_resolver
+        )
+        tls_ctx_opt = TlsContextOptions.create_client_with_mtls(
+            cert_buffer=self.certificate, key_buffer=self.private_key
+        )
+
+        if self.ca:
+            tls_ctx_opt.override_default_trust_store(self.ca)
+
+        tls_ctx_opt.verify_peer = self.verify_peer
+        tls_ctx = ClientTlsContext(tls_ctx_opt)
+        tls_conn_opt: TlsConnectionOptions = cast(
+            TlsConnectionOptions, tls_ctx.new_connection_options()
+        )
+        tls_conn_opt.set_server_name(str(url.hostname))
+
+        try:
+            connection_future = HttpClientConnection.new(
+                host_name=str(url.hostname),
+                port=port,
+                bootstrap=bootstrap,
+                tls_connection_options=tls_conn_opt,
+            )
+            return connection_future.result(self.timeout)
+        except AwsCrtError as err:
+            raise BRSError(
+                "Error completing mTLS connection to endpoint "
+                f"'{url.hostname}'"
+            ) from err
+
+    def _mtls_pkcs11_client_connection(
+        self, url: ParseResult, port: int
+    ) -> HttpClientConnection:
+        event_loop_group: EventLoopGroup = EventLoopGroup()
+        host_resolver: DefaultHostResolver = DefaultHostResolver(
+            event_loop_group
+        )
+        bootstrap: ClientBootstrap = ClientBootstrap(
+            event_loop_group, host_resolver
+        )
+
+        if not self.pkcs11:
+            raise BRSError(
+                "Attempting to establish mTLS connection using PKCS#11"
+                "but 'pkcs11' parameter is 'None'!"
+            )
+
+        tls_ctx_opt = TlsContextOptions.create_client_with_mtls_pkcs11(
+            pkcs11_lib=Pkcs11Lib(file=self.pkcs11["pkcs11_lib"]),
+            user_pin=self.pkcs11["user_pin"],
+            slot_id=self.pkcs11["slot_id"],
+            token_label=self.pkcs11["token_label"],
+            private_key_label=self.pkcs11["private_key_label"],
+            cert_file_contents=self.certificate,
+        )
+
+        if self.ca:
+            tls_ctx_opt.override_default_trust_store(self.ca)
+
+        tls_ctx_opt.verify_peer = self.verify_peer
+        tls_ctx = ClientTlsContext(tls_ctx_opt)
+        tls_conn_opt: TlsConnectionOptions = cast(
+            TlsConnectionOptions, tls_ctx.new_connection_options()
+        )
+        tls_conn_opt.set_server_name(str(url.hostname))
+
+        try:
+            connection_future = HttpClientConnection.new(
+                host_name=str(url.hostname),
+                port=port,
+                bootstrap=bootstrap,
+                tls_connection_options=tls_conn_opt,
+            )
+            return connection_future.result(self.timeout)
+        except AwsCrtError as err:
+            raise BRSError("Error completing mTLS connection.") from err
+
+    def get_identity(self) -> Identity:
+        """Returns metadata about the current caller identity.
+
+        Returns
+        -------
+        Identity
+            Dict containing information about the current calleridentity.
+        """
+
+        return self.client("sts").get_caller_identity()
+
+    @staticmethod
+    def _normalize_iot_credential_endpoint(endpoint: str) -> str:
+        if ".credentials.iot." in endpoint:
+            return endpoint
+
+        if ".iot." in endpoint and "-ats." in endpoint:
+            logged_data_endpoint = re.sub(r"^[^. -]+", "***", endpoint)
+            logged_credential_endpoint = re.sub(
+                r"^[^. -]+",
+                "***",
+                (endpoint := endpoint.replace("-ats.iot", ".credentials.iot")),
+            )
+            BRSWarning.warn(
+                "The 'endpoint' parameter you provided represents the data "
+                "endpoint for IoT not the credentials endpoint! The endpoint "
+                "you provided was therefore modified from "
+                f"'{logged_data_endpoint}' -> '{logged_credential_endpoint}'"
+            )
+            return endpoint
+
+        raise BRSError(
+            "Invalid IoT endpoint provided for credentials provider. "
+            "Expected '<id>.credentials.iot.<region>.amazonaws.com'"
+        )
+
+    @staticmethod
+    def _validate_pkcs11(pkcs11: PKCS11) -> PKCS11:
+        if "pkcs11_lib" not in pkcs11:
+            raise BRSError(
+                "PKCS#11 library path must be provided as 'pkcs11_lib'"
+                " in 'pkcs11'."
+            )
+        elif not Path(pkcs11["pkcs11_lib"]).expanduser().resolve().is_file():
+            raise BRSError(
+                f"'{pkcs11['pkcs11_lib']}' is not a valid file path for "
+                "'pkcs11_lib' in 'pkcs11'."
+            )
+        pkcs11.setdefault("user_pin", None)
+        pkcs11.setdefault("slot_id", None)
+        pkcs11.setdefault("token_label", None)
+        pkcs11.setdefault("private_key_label", None)
+        return pkcs11

boto3_refresh_session/methods/sts.py

@@ -45,7 +45,7 @@ class STSRefreshableSession(BaseRefreshableSession, registry_key="sts"):
         **kwargs,
     ):
         if "refresh_method" in kwargs:
-            BRSWarning(
+            BRSWarning.warn(
                 "'refresh_method' cannot be set manually. "
                 "Reverting to 'sts-assume-role'."
             )
@@ -60,7 +60,7 @@ class STSRefreshableSession(BaseRefreshableSession, registry_key="sts"):
         if sts_client_kwargs is not None:
             # overwriting 'service_name' if if appears in sts_client_kwargs
             if "service_name" in sts_client_kwargs:
-                BRSWarning(
+                BRSWarning.warn(
                     "'sts_client_kwargs' cannot contain values for "
                     "'service_name'. Reverting to service_name = 'sts'."
                 )

boto3_refresh_session/session.py

@@ -36,8 +36,8 @@ class RefreshableSession:
     See Also
     --------
     boto3_refresh_session.methods.custom.CustomRefreshableSession
+    boto3_refresh_session.methods.iot.IOTX509RefreshableSession
     boto3_refresh_session.methods.sts.STSRefreshableSession
-    boto3_refresh_session.methods.ecs.ECSRefreshableSession
     """
 
     def __new__(
@@ -60,7 +60,7 @@ class RefreshableSession:
         -------
         list[str]
             A list of all currently available credential refresh methods,
-            e.g. 'sts', 'ecs', 'custom'.
+            e.g. 'sts', 'custom'.
         """
 
         args = list(get_args(Method))

boto3_refresh_session/utils/internal.py

@@ -1,4 +1,6 @@
 __all__ = [
+    "AWSCRTResponse",
+    "BaseIoTRefreshableSession",
     "BaseRefreshableSession",
     "BRSSession",
     "CredentialProvider",
@@ -10,6 +12,7 @@ from abc import ABC, abstractmethod
 from functools import wraps
 from typing import Any, Callable, ClassVar, Generic, TypeVar, cast
 
+from awscrt.http import HttpHeaders
 from boto3.session import Session
 from botocore.credentials import (
     DeferredRefreshableCredentials,
@@ -19,6 +22,7 @@ from botocore.credentials import (
 from ..exceptions import BRSWarning
 from .typing import (
     Identity,
+    IoTAuthenticationMethod,
     Method,
     RefreshableTemporaryCredentials,
     RefreshMethod,
@@ -46,7 +50,9 @@ class Registry(Generic[RegistryKey]):
         super().__init_subclass__(**kwargs)
 
         if registry_key in cls.registry:
-            BRSWarning(f"{registry_key!r} already registered. Overwriting.")
+            BRSWarning.warn(
+                f"{registry_key!r} already registered. Overwriting."
+            )
 
         if "sentinel" not in registry_key:
             cls.registry[registry_key] = cls
@@ -202,3 +208,35 @@ class BaseRefreshableSession(
 
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
+
+
+class BaseIoTRefreshableSession(
+    Registry[IoTAuthenticationMethod],
+    CredentialProvider,
+    BRSSession,
+    registry_key="__iot_sentinel__",
+):
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+
+
+class AWSCRTResponse:
+    """Lightweight response collector for awscrt HTTP."""
+
+    def __init__(self):
+        """Initialize to default for when callbacks are called."""
+
+        self.status_code = None
+        self.headers = None
+        self.body = bytearray()
+
+    def on_response(self, http_stream, status_code, headers, **kwargs):
+        """Process awscrt.io response."""
+
+        self.status_code = status_code
+        self.headers = HttpHeaders(headers)
+
+    def on_body(self, http_stream, chunk, **kwargs):
+        """Process awscrt.io body."""
+
+        self.body.extend(chunk)

boto3_refresh_session/utils/typing.py

@@ -33,22 +33,23 @@ except ImportError:
     from typing_extensions import NotRequired
 
 #: Type alias for all currently available IoT authentication methods.
-IoTAuthenticationMethod = Literal["certificate", "cognito", "__iot_sentinel__"]
+IoTAuthenticationMethod = Literal["x509", "__iot_sentinel__"]
 
 #: Type alias for all currently available credential refresh methods.
 Method = Literal[
-    "sts",
-    "ecs",
     "custom",
+    "iot",
+    "sts",
     "__sentinel__",
-]  # TODO: Add iot when implemented
+    "__iot_sentinel__",
+]
 
 #: Type alias for all refresh method names.
 RefreshMethod = Literal[
-    "sts-assume-role",
-    "ecs-container-metadata",
     "custom",
-]  # TODO: Add iot-certificate and iot-cognito when iot implemented
+    "iot-x509",
+    "sts-assume-role",
+]
 
 #: Type alias for all currently registered credential refresh methods.
 RegistryKey = TypeVar("RegistryKey", bound=str)
@@ -138,7 +139,7 @@ class STSClientParams(TypedDict):
 
 
 class PKCS11(TypedDict):
-    pkcs11_loc: str
+    pkcs11_lib: str
     user_pin: NotRequired[str]
     slot_id: NotRequired[int]
     token_label: NotRequired[str | None]

{boto3_refresh_session-3.0.3.dist-info → boto3_refresh_session-5.0.0.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.3
 Name: boto3-refresh-session
-Version: 3.0.3
+Version: 5.0.0
 Summary: A simple Python package for refreshing the temporary security credentials in a boto3.session.Session object automatically.
 License: MIT
-Keywords: boto3,botocore,aws,sts,ecs,credentials,token,refresh
+Keywords: boto3,botocore,aws,sts,credentials,token,refresh,iot,x509
 Author: Mike Letts
 Author-email: lettsmt@gmail.com
 Maintainer: Michael Letts
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: awscrt
 Requires-Dist: boto3
 Requires-Dist: botocore
 Requires-Dist: requests
@@ -120,13 +121,14 @@ Description-Content-Type: text/markdown
 ## 😛 Features
 
 - Drop-in replacement for `boto3.session.Session`
-- Supports automatic credential refresh methods for various AWS services:
-  - STS
-  - ECS
-- Supports custom authentication methods for complicated authentication flows
+- Supports automatic credential refresh for: 
+  - **STS**
+  - **IoT Core** 
+    - X.509 certificates w/ role aliases over mTLS (PEM files and PKCS#11)
+  - Custom authentication methods
 - Natively supports all parameters supported by `boto3.session.Session`
 - [Tested](https://github.com/michaelthomasletts/boto3-refresh-session/tree/main/tests), [documented](https://michaelthomasletts.github.io/boto3-refresh-session/index.html), and [published to PyPI](https://pypi.org/project/boto3-refresh-session/)
-- Future releases will include support for IoT (coming soon), EC2, and SSO
+- Future releases will include support for IoT (coming soon)
 
 ## ⚠️ Important Updates
 
@@ -138,6 +140,14 @@ Advanced users, however, particularly those using low-level objects such as `Bas
 
 Please review [this PR](https://github.com/michaelthomasletts/boto3-refresh-session/pull/75) for additional details.
 
+#### ✂️ v4.0.0
+
+The `ecs` module has been dropped. For additional details and rationale, please review [this PR](https://github.com/michaelthomasletts/boto3-refresh-session/pull/78).
+
+#### 😛 v5.0.0
+
+Support for IoT Core via X.509 certificate-based authentication (over HTTPS) is now available!
+
 #### ☎️ Delayed Responses
 
 I am currently grappling with a very serious medical condition. Accordingly, expect delayed responses to issues and requests until my health stabilizes.
@@ -171,7 +181,7 @@ pip install boto3-refresh-session
 
   To use the `boto3.client` or `boto3.resource` interface, but with the benefits of `boto3-refresh-session`, you have a few options! 
   
-  In the following examples, let's assume you want to use STS for retrieving temporary credentials for the sake of simplicity. Let's also focus specifically on `client`. Switching to `resource` follows the same exact idioms as below, except that `client` must be switched to `resource` in the pseudo-code, obviously. If you are not sure how to use `RefreshableSession` for STS (or ECS or custom auth flows) then check the usage instructions in the following sections!
+  In the following examples, let's assume you want to use STS for retrieving temporary credentials for the sake of simplicity. Let's also focus specifically on `client`. Switching to `resource` follows the same exact idioms as below, except that `client` must be switched to `resource` in the pseudo-code, obviously. If you are not sure how to use `RefreshableSession` for STS (or custom auth flows) then check the usage instructions in the following sections!
 
   ##### `RefreshableSession.client` (Recommended)
 
@@ -269,24 +279,6 @@ pip install boto3-refresh-session
 
 </details>
 
-<details>
-   <summary><strong>ECS (click to expand)</strong></summary>
-
-  ### ECS
-
-  You can use boto3-refresh-session in an ECS container to automatically refresh temporary security credentials. For additional information on the exact parameters that `RefreshableSession` takes for ECS, [check this documentation](https://github.com/michaelthomasletts/boto3-refresh-session/blob/main/boto3_refresh_session/methods/ecs.py).
-
-  ```python
-  session = RefreshableSession(
-    method="ecs", 
-    region_name=region_name, 
-    profile_name=profile_name,
-    ...
-  )
-  ```
-
-</details>
-
 <details>
    <summary><strong>Custom Authentication Flows (click to expand)</strong></summary>
 
@@ -317,3 +309,56 @@ pip install boto3-refresh-session
   ```
 
 </details>
+
+<details>
+  <summary><strong>IoT Core X.509 (click to expand)</strong></summary>
+
+  ### IoT Core X.509
+
+  AWS IoT Core can vend temporary AWS credentials through the **credentials provider** when you connect with an X.509 certificate and a **role alias**. `boto3-refresh-session` makes this flow seamless by automatically refreshing credentials over **mTLS**.
+
+  For additional information on the exact parameters that `IOTX509RefreshableSession` takes, [check this documentation](https://github.com/michaelthomasletts/boto3-refresh-session/blob/main/boto3_refresh_session/methods/iot/x509.py).
+
+  ### PEM file
+
+  ```python
+  import boto3_refresh_session as brs
+
+  # PEM certificate + private key example
+  session = brs.RefreshableSession(
+      method="iot",
+      endpoint="<your-credentials-endpoint>.credentials.iot.<region>.amazonaws.com",
+      role_alias="<your-role-alias>",
+      certificate="/path/to/certificate.pem",
+      private_key="/path/to/private-key.pem",
+      thing_name="<your-thing-name>",       # optional, if used in policies
+      duration_seconds=3600,                # optional, capped by role alias
+      region_name="us-east-1",
+  )
+
+  # Now you can use the session like any boto3 session
+  s3 = session.client("s3")
+  print(s3.list_buckets())
+  ```
+
+  ### PKCS#11
+
+  ```python
+  session = brs.RefreshableSession(
+      method="iot",
+      endpoint="<your-credentials-endpoint>.credentials.iot.<region>.amazonaws.com",
+      role_alias="<your-role-alias>",
+      certificate="/path/to/certificate.pem",
+      pkcs11={
+          "pkcs11_lib": "/usr/local/lib/softhsm/libsofthsm2.so",
+          "user_pin": "1234",
+          "slot_id": 0,
+          "token_label": "MyToken",
+          "private_key_label": "MyKey",
+      },
+      thing_name="<your-thing-name>",
+      region_name="us-east-1",
+  )
+  ```
+
+</details>

boto3_refresh_session-5.0.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+boto3_refresh_session/__init__.py,sha256=XR8slNXWaySOCG-_BnO5yi6d8276TH34EzGUTS347vM,415
+boto3_refresh_session/exceptions.py,sha256=QS5_xy3hNrfkdT_wKPZWH8WqSbFYCKPcK8DomGYIvcU,1218
+boto3_refresh_session/methods/__init__.py,sha256=FpwWixSVpy_6pUe1u4fXmjO-_fDH--qTk_xrMnBCHxU,193
+boto3_refresh_session/methods/custom.py,sha256=MLdUMU9s6NQoJWBKQ5Fsxeyxb_Xrm9V59pVX22M8fyI,4178
+boto3_refresh_session/methods/iot/__init__.py,sha256=wIYp7HFZ_Q8XEHwWmpKjDNXxBm29C0RisP_9GSVwzZI,147
+boto3_refresh_session/methods/iot/core.py,sha256=xtvbC23h6fw06lRZWN4r7TlnUEf3t9T7-zSPGCSlSLI,1151
+boto3_refresh_session/methods/iot/x509.py,sha256=QvHXJKRkRuF5TOUOEH4rTN8lfm_rRnp-flLoolMaxbw,12368
+boto3_refresh_session/methods/sts.py,sha256=NGqJFJNLjG9Mve7o19tb_i6lvgQW1HoALIqF6lJNV9A,3336
+boto3_refresh_session/session.py,sha256=UM_dWHSo0Wn8gLN99zg36SRVb-Yy_to1wk8UgZEuQZA,2086
+boto3_refresh_session/utils/__init__.py,sha256=6F2ErbgBT2ZmZwFF3OzvQEd1Vh4XM3kaL6YGMTrcrkQ,156
+boto3_refresh_session/utils/internal.py,sha256=HbuIzT0pC8QS4pgNj3M7POGaW-OEz2l3ESfYI1Qouuo,7072
+boto3_refresh_session/utils/typing.py,sha256=AqPey1N8nNUU2BwQYIIz-xGrfgjyNUzDt8MK0eB5DSQ,3429
+boto3_refresh_session-5.0.0.dist-info/LICENSE,sha256=I3ZYTXAjbIly6bm6J-TvFTuuHwTKws4h89QaY5c5HiY,1067
+boto3_refresh_session-5.0.0.dist-info/METADATA,sha256=xTwVXf2-RzpcMWZH9SvZTvrVM2stHCp6ZWRYrX5Q7p4,14151
+boto3_refresh_session-5.0.0.dist-info/NOTICE,sha256=1s8r33qbl1z0YvPB942iWgvbkP94P_e8AnROr1qXXuw,939
+boto3_refresh_session-5.0.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+boto3_refresh_session-5.0.0.dist-info/RECORD,,

boto3_refresh_session/methods/ecs.py

@@ -1,115 +0,0 @@
-__all__ = ["ECSRefreshableSession"]
-
-import os
-
-import requests
-
-from ..exceptions import BRSError, BRSWarning
-from ..utils import (
-    BaseRefreshableSession,
-    Identity,
-    TemporaryCredentials,
-    refreshable_session,
-)
-
-_ECS_CREDENTIALS_RELATIVE_URI = "AWS_CONTAINER_CREDENTIALS_RELATIVE_URI"
-_ECS_CREDENTIALS_FULL_URI = "AWS_CONTAINER_CREDENTIALS_FULL_URI"
-_ECS_AUTHORIZATION_TOKEN = "AWS_CONTAINER_AUTHORIZATION_TOKEN"
-_DEFAULT_ENDPOINT_BASE = "http://169.254.170.2"
-
-
-@refreshable_session
-class ECSRefreshableSession(BaseRefreshableSession, registry_key="ecs"):
-    """A boto3 session that automatically refreshes temporary AWS credentials
-    from the ECS container credentials metadata endpoint.
-
-    Parameters
-    ----------
-    defer_refresh : bool, optional
-        If ``True`` then temporary credentials are not automatically
-        refreshed until they are explicitly needed. If ``False`` then
-        temporary credentials refresh immediately upon expiration. It
-        is highly recommended that you use ``True``. Default is ``True``.
-
-    Other Parameters
-    ----------------
-    kwargs : dict
-        Optional keyword arguments passed to :class:`boto3.session.Session`.
-    """
-
-    def __init__(self, **kwargs):
-        if "refresh_method" in kwargs:
-            BRSWarning(
-                "'refresh_method' cannot be set manually. "
-                "Reverting to 'ecs-container-metadata'."
-            )
-            del kwargs["refresh_method"]
-
-        # initializing BRSSession
-        super().__init__(refresh_method="ecs-container-metadata", **kwargs)
-
-        # initializing various other attributes
-        self._endpoint = self._resolve_endpoint()
-        self._headers = self._build_headers()
-        self._http = self._init_http_session()
-
-    def _resolve_endpoint(self) -> str:
-        uri = os.environ.get(_ECS_CREDENTIALS_FULL_URI) or os.environ.get(
-            _ECS_CREDENTIALS_RELATIVE_URI
-        )
-        if not uri:
-            raise BRSError(
-                "Neither AWS_CONTAINER_CREDENTIALS_FULL_URI nor "
-                "AWS_CONTAINER_CREDENTIALS_RELATIVE_URI is set. "
-                "Are you running inside an ECS container?"
-            )
-        if uri.startswith("http://") or uri.startswith("https://"):
-            return uri
-        return f"{_DEFAULT_ENDPOINT_BASE}{uri}"
-
-    def _build_headers(self) -> dict[str, str]:
-        token = os.environ.get(_ECS_AUTHORIZATION_TOKEN)
-        if token:
-            return {"Authorization": f"Bearer {token}"}
-        return {}
-
-    def _init_http_session(self) -> requests.Session:
-        session = requests.Session()
-        session.headers.update(self._headers)
-        return session
-
-    def _get_credentials(self) -> TemporaryCredentials:
-        try:
-            response = self._http.get(self._endpoint, timeout=3)
-            response.raise_for_status()
-        except requests.RequestException as exc:
-            raise BRSError(
-                f"Failed to retrieve ECS credentials from {self._endpoint}"
-            ) from exc
-
-        credentials = response.json()
-        required = {
-            "AccessKeyId",
-            "SecretAccessKey",
-            "SessionToken",
-            "Expiration",
-        }
-        if not required.issubset(credentials):
-            raise BRSError(f"Incomplete credentials received: {credentials}")
-        return {
-            "access_key": credentials.get("AccessKeyId"),
-            "secret_key": credentials.get("SecretAccessKey"),
-            "token": credentials.get("SessionToken"),
-            "expiry_time": credentials.get("Expiration"),  # already ISO8601
-        }
-
-    def get_identity(self) -> Identity:
-        """Returns metadata about ECS.
-
-        Returns
-        -------
-        Identity
-            Dict containing metadata about ECS.
-        """
-
-        return {"method": "ecs", "source": "ecs-container-metadata"}

boto3_refresh_session/methods/iot/__init__.typed

@@ -1,4 +0,0 @@
-from .certificate import IoTCertificateRefreshableSession
-from .core import IoTRefreshableSession
-
-__all__ = ["IoTRefreshableSession"]

boto3_refresh_session/methods/iot/certificate.typed

@@ -1,57 +0,0 @@
-__all__ = ["IoTCertificateRefreshableSession"]
-
-from pathlib import Path
-from typing import Any
-
-from ...exceptions import BRSError
-from ...utils import (
-    Identity, PKCS11, TemporaryCredentials, refreshable_session
-)
-from .core import BaseIoTRefreshableSession
-
-
-@refreshable_session
-class IoTCertificateRefreshableSession(
-    BaseIoTRefreshableSession, registry_key="certificate"
-):
-    def __init__(
-        self,
-        endpoint: str,
-        role_alias: str,
-        thing_name: str,
-        certificate: str | bytes,
-        private_key: str | bytes | None = None,
-        pkcs11: PKCS11 | None = None,
-        ca: bytes | None = None,
-        verify_peer: bool = True,
-    ):
-        self.endpoint = endpoint
-        self.role_alias = role_alias
-        self.thing_name = thing_name
-        self.certificate = certificate
-        self.private_key = private_key
-        self.pkcs11 = pkcs11
-        self.ca = ca
-        self.verify_peer = verify_peer
-
-        if self.certificate and isinstance(self.certificate, str):
-            with open(Path(self.certificate), "rb") as cert_pem_file:
-                self.certificate = cert_pem_file.read()
-
-        if self.private_key is None and self.pkcs11 is None:
-            raise BRSError(
-                "Either 'private_key' or 'pkcs11' must be provided."
-            )
-
-        if self.private_key is not None and self.pkcs11 is not None:
-            raise BRSError(
-                "Only one of 'private_key' or 'pkcs11' can be provided."
-            )
-
-        if self.private_key and isinstance(self.private_key, str):
-            with open(Path(self.private_key), "rb") as private_key_pem_file:
-                self.private_key = private_key_pem_file.read()
-
-    def _get_credentials(self) -> TemporaryCredentials: ...
-
-    def get_identity(self) -> Identity: ...

boto3_refresh_session/methods/iot/cognito.typed

@@ -1,17 +0,0 @@
-__all__ = ["IoTCognitoRefreshableSession"]
-
-from typing import Any
-
-from ...utils import Identity, TemporaryCredentials, refreshable_session
-from .core import BaseIoTRefreshableSession
-
-
-@refreshable_session
-class IoTCognitoRefreshableSession(
-    BaseIoTRefreshableSession, registry_key="cognito"
-):
-    def __init__(self): ...
-
-    def _get_credentials(self) -> TemporaryCredentials: ...
-
-    def get_identity(self) -> Identity: ...

boto3_refresh_session-3.0.3.dist-info/RECORD

@@ -1,19 +0,0 @@
-boto3_refresh_session/__init__.py,sha256=L-9FGJIUsvwRFNlfJeKb_61NvZpT07xGdBAyV38DMhI,415
-boto3_refresh_session/exceptions.py,sha256=DumBh6cDVU46eelSNt1CsG2uMSBekSbmhqWEaAWw130,1003
-boto3_refresh_session/methods/__init__.py,sha256=zpVBJIR4P-l4pjE9kMnLGffehPVawY1vLiX2CPcpV7w,352
-boto3_refresh_session/methods/custom.py,sha256=j90Iv1DKdGgP1JNwQfpEhaJDBrB2AtDe8kqI2Mktwlg,4173
-boto3_refresh_session/methods/ecs.py,sha256=dxDrNOu8xTFHciuwL7jLh5nB2QXWwQRRA1CoY7AuO5g,3893
-boto3_refresh_session/methods/iot/__init__.typed,sha256=Z33nIB6oCsz9TZwikHfNHgY1SKxkSCdB5rwdPSUl3C4,135
-boto3_refresh_session/methods/iot/certificate.typed,sha256=sFTa1rF7tebr48Bjw_YtVeOdVvazAHBJGGiM33tsFXI,1828
-boto3_refresh_session/methods/iot/cognito.typed,sha256=wyBMWUkuhLt27JsKZIwtfylDdCavNexcEy16ZaDFjUY,435
-boto3_refresh_session/methods/iot/core.typed,sha256=Q5WshxgIIOgAaqoU7n8wBKMe9eSzZ6H8db-q1gThHzk,1407
-boto3_refresh_session/methods/sts.py,sha256=dzf68BE0f1nFsITOKOnygh-mTvBqThKkrW2eEc-wFKA,3326
-boto3_refresh_session/session.py,sha256=8YAdanwnJUG622Cv9MNKg25uj9ZmMYzRL4xiqH1i0nk,2089
-boto3_refresh_session/utils/__init__.py,sha256=6F2ErbgBT2ZmZwFF3OzvQEd1Vh4XM3kaL6YGMTrcrkQ,156
-boto3_refresh_session/utils/internal.py,sha256=bpKTAF_xdBw1wJPHIG8aGRMiXkSkp7CI9et0U5o3qEI,6103
-boto3_refresh_session/utils/typing.py,sha256=I4VJS1vkRwIRdJF08dZF1YgUed_anviz3hq4hLvPnLw,3537
-boto3_refresh_session-3.0.3.dist-info/LICENSE,sha256=I3ZYTXAjbIly6bm6J-TvFTuuHwTKws4h89QaY5c5HiY,1067
-boto3_refresh_session-3.0.3.dist-info/METADATA,sha256=91keQVV9MNrd7zoC8s5c4e59qzrU7vMB9plvJ1d4Sr8,12561
-boto3_refresh_session-3.0.3.dist-info/NOTICE,sha256=1s8r33qbl1z0YvPB942iWgvbkP94P_e8AnROr1qXXuw,939
-boto3_refresh_session-3.0.3.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-boto3_refresh_session-3.0.3.dist-info/RECORD,,