okta-client-python 0.1.0__py3-none-any.whl

okta_client/authfoundation/key_provider.py

@@ -0,0 +1,130 @@
+# The Okta software accompanied by this notice is provided pursuant to the following terms:
+# Copyright © 2026-Present, Okta, Inc.
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
+# License.
+# You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+# coding: utf-8
+
+from __future__ import annotations
+
+import json
+import threading
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+import jwt
+from jwt import algorithms as jwt_algorithms
+
+_ALLOWED_ALGORITHMS = {
+    "HS256",
+    "HS384",
+    "HS512",
+    "RS256",
+    "RS384",
+    "RS512",
+    "ES256",
+    "ES384",
+    "ES512",
+    "PS256",
+    "PS384",
+    "PS512",
+}
+
+
+@runtime_checkable
+class KeyProvider(Protocol):
+    """Protocol for signing JWT assertions."""
+
+    algorithm: str
+    key_id: str | None
+
+    def sign_jwt(self, claims: Mapping[str, object], headers: Mapping[str, object] | None = None) -> str:
+        """Sign the given claims and return a compact JWT string."""
+        ...
+
+
+@dataclass(frozen=True)
+class LocalKeyProvider(KeyProvider):
+    """Key provider that signs JWTs using local key material."""
+
+    key: str | bytes | Mapping[str, Any]
+    algorithm: str = "RS256"
+    key_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.algorithm not in _ALLOWED_ALGORITHMS:
+            raise ValueError(f"Unsupported JWT algorithm: {self.algorithm}")
+
+    def sign_jwt(self, claims: Mapping[str, object], headers: Mapping[str, object] | None = None) -> str:
+        if not claims:
+            raise ValueError("claims must not be empty")
+        encoded_headers = dict(headers or {})
+        if self.key_id and "kid" not in encoded_headers:
+            encoded_headers["kid"] = self.key_id
+        key = _resolve_key_material(self.key, self.algorithm)
+        token = jwt.encode(payload=dict(claims), key=key, algorithm=self.algorithm, headers=encoded_headers or None)
+        return token.decode("utf-8") if isinstance(token, bytes) else token
+
+    @classmethod
+    def from_pem(
+        cls,
+        pem: str,
+        *,
+        algorithm: str = "RS256",
+        key_id: str | None = None,
+    ) -> LocalKeyProvider:
+        return cls(pem, algorithm=algorithm, key_id=key_id)
+
+    @classmethod
+    def from_pem_file(
+        cls,
+        path: str,
+        *,
+        algorithm: str = "RS256",
+        key_id: str | None = None,
+        encoding: str = "utf-8",
+    ) -> LocalKeyProvider:
+        with open(path, encoding=encoding) as handle:
+            return cls(handle.read(), algorithm=algorithm, key_id=key_id)
+
+
+class DefaultKeyProvider(KeyProvider):
+    """Default provider that requires explicit configuration."""
+
+    algorithm: str = ""
+    key_id: str | None = None
+
+    def sign_jwt(self, claims: Mapping[str, object], headers: Mapping[str, object] | None = None) -> str:
+        raise RuntimeError("KeyProvider is not configured. Use set_key_provider() to supply a signer.")
+
+
+_default_key_provider: KeyProvider = DefaultKeyProvider()
+_key_provider_lock = threading.Lock()
+
+
+def get_key_provider() -> KeyProvider:
+    """Get the global KeyProvider in a thread-safe manner."""
+    with _key_provider_lock:
+        return _default_key_provider
+
+
+def set_key_provider(provider: KeyProvider) -> None:
+    """Set the global KeyProvider in a thread-safe manner."""
+    global _default_key_provider
+    with _key_provider_lock:
+        _default_key_provider = provider
+
+
+def _resolve_key_material(key: str | bytes | Mapping[str, Any], algorithm: str) -> Any:
+    if isinstance(key, (str, bytes)):
+        return key
+    if isinstance(key, Mapping):
+        algorithms = jwt_algorithms.get_default_algorithms()
+        if algorithm not in algorithms:
+            raise ValueError(f"Unsupported JWT algorithm: {algorithm}")
+        return algorithms[algorithm].from_jwk(json.dumps(dict(key)))
+    raise TypeError("key must be a PEM string, bytes, or JWK mapping")

okta_client/authfoundation/networking/__init__.py

@@ -0,0 +1,56 @@
+# The Okta software accompanied by this notice is provided pursuant to the following terms:
+# Copyright © 2026-Present, Okta, Inc.
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
+# License.
+# You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+# coding: utf-8
+
+from .body import APIRequestBodyMixin
+from .client import APIClient, DefaultNetworkInterface
+from .types import (
+    APIAuthorization,
+    APIClientConfiguration,
+    APIClientListener,
+    APIContentType,
+    APIParsingContext,
+    APIRateLimit,
+    APIRequest,
+    APIRequestBody,
+    APIRequestMethod,
+    APIResponse,
+    APIRetry,
+    BaseAPIRequest,
+    HTTPRequest,
+    ListenerCollection,
+    NetworkInterface,
+    RawResponse,
+    RequestValue,
+    RequestValueConvertible,
+)
+
+__all__ = [
+    "APIAuthorization",
+    "APIClient",
+    "APIClientConfiguration",
+    "APIClientListener",
+    "APIContentType",
+    "APIParsingContext",
+    "APIRateLimit",
+    "APIRequest",
+    "APIRequestBody",
+    "APIRequestBodyMixin",
+    "APIRequestMethod",
+    "APIResponse",
+    "APIRetry",
+    "BaseAPIRequest",
+    "DefaultNetworkInterface",
+    "HTTPRequest",
+    "ListenerCollection",
+    "NetworkInterface",
+    "RawResponse",
+    "RequestValue",
+    "RequestValueConvertible",
+]

okta_client/authfoundation/networking/body.py

@@ -0,0 +1,46 @@
+# The Okta software accompanied by this notice is provided pursuant to the following terms:
+# Copyright © 2026-Present, Okta, Inc.
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
+# License.
+# You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+# coding: utf-8
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from urllib.parse import parse_qs, urlencode
+
+from okta_client.authfoundation.utils import serialize_parameters
+
+from .types import APIContentType, APIParsingContext, APIRequestBody, RawResponse
+
+
+class APIRequestBodyMixin(APIRequestBody):
+    """Mixin that serializes body parameters based on content type."""
+
+    @property
+    def content_type(self) -> APIContentType | None:
+        raise NotImplementedError
+
+    @property
+    def accepts_type(self) -> APIContentType | None:
+        raise NotImplementedError
+
+    def body(self) -> bytes | None:
+        params = serialize_parameters(self.body_parameters)
+        if self.content_type == APIContentType.JSON:
+            return json.dumps(params).encode("utf-8")
+        return urlencode(params).encode("utf-8")
+
+    def parse_response(self, response: RawResponse, parsing_context: APIParsingContext | None = None) -> Any:
+        if not response.body:
+            return {}
+        if self.accepts_type == APIContentType.JSON:
+            return json.loads(response.body.decode("utf-8"))
+        if self.accepts_type == APIContentType.FORM_URLENCODED:
+            return parse_qs(response.body.decode("utf-8"))
+        return response.body.decode("utf-8")

okta_client/authfoundation/networking/client.py

@@ -0,0 +1,200 @@
+# The Okta software accompanied by this notice is provided pursuant to the following terms:
+# Copyright © 2026-Present, Okta, Inc.
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
+# License.
+# You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
+# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and limitations under the License.
+# coding: utf-8
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from collections.abc import Mapping
+from typing import Any, TypeVar
+from urllib.parse import urlencode, urlsplit, urlunsplit
+
+from okta_client.authfoundation.utils import serialize_parameters, serialize_request_value
+
+from .types import (
+    APIClientConfiguration,
+    APIClientListener,
+    APIContentType,
+    APIParsingContext,
+    APIRateLimit,
+    APIRequest,
+    APIRequestBody,
+    APIResponse,
+    APIRetry,
+    HTTPRequest,
+    ListenerCollection,
+    NetworkInterface,
+    RawResponse,
+    RequestValue,
+)
+
+T = TypeVar("T")
+
+
+class APIClient:
+    """Network client that executes APIRequest objects and parses responses."""
+    def __init__(
+        self,
+        base_url: str | None = None,
+        user_agent: str | None = None,
+        additional_http_headers: Mapping[str, str] | None = None,
+        request_id_header: str | None = None,
+        configuration: APIClientConfiguration | None = None,
+        network: NetworkInterface | None = None,
+    ) -> None:
+        """Create a client with configuration and network transport."""
+        if configuration is None:
+            if base_url is None or user_agent is None:
+                raise ValueError("base_url and user_agent are required when configuration is not provided")
+            configuration = APIClientConfiguration(
+                base_url=base_url,
+                user_agent=user_agent,
+                additional_http_headers=additional_http_headers or {},
+                request_id_header=request_id_header,
+            )
+        self.configuration = configuration
+        self.base_url = configuration.base_url
+        self.user_agent = configuration.user_agent
+        self.network = network or DefaultNetworkInterface()
+        self.additional_http_headers = dict(configuration.additional_http_headers or {})
+        self.request_id_header = configuration.request_id_header
+        self._listeners: ListenerCollection[APIClientListener] = ListenerCollection()
+
+    @property
+    def listeners(self) -> ListenerCollection[APIClientListener]:
+        """Registered listeners for request lifecycle events."""
+        return self._listeners
+
+    def send(self, request: APIRequest[T], parsing_context: APIParsingContext | None = None) -> APIResponse[T]:
+        """Send an APIRequest and return a typed APIResponse."""
+        http_request = self.build_http_request(request)
+        self.will_send(http_request)
+        try:
+            raw_response = self._send_once(request, http_request=http_request)
+            result = request.parse_response(raw_response, parsing_context=parsing_context)
+            response = APIResponse(
+                result=result,
+                status_code=raw_response.status_code,
+                headers=raw_response.headers,
+                request_id=self._extract_request_id(raw_response.headers),
+                rate_limit=None,
+                links=None,
+            )
+            self.did_send(http_request, response)
+            return response
+        except Exception as error:
+            self.did_send_error(http_request, error)
+            raise
+
+    def will_send(self, request: HTTPRequest) -> None:
+        """Notify listeners before a request is sent."""
+        for listener in self._listeners:
+            listener.will_send(self, request)
+
+    def did_send(self, request: HTTPRequest, response: APIResponse[Any]) -> None:
+        """Notify listeners after a successful response."""
+        for listener in self._listeners:
+            listener.did_send(self, request, response)
+
+    def did_send_error(self, request: HTTPRequest, error: Exception) -> None:
+        """Notify listeners after a failed request."""
+        for listener in self._listeners:
+            listener.did_send_error(self, request, error)
+
+    def should_retry(self, request: HTTPRequest, rate_limit: APIRateLimit | None = None) -> APIRetry:
+        """Ask listeners for a retry policy for a request."""
+        for listener in self._listeners:
+            retry = listener.should_retry(self, request, rate_limit)
+            if retry.kind != "default":
+                return retry
+        return APIRetry.default()
+
+    def _send_once(self, request: APIRequest[T], http_request: HTTPRequest | None = None) -> RawResponse:
+        """Send a request once using the configured network interface."""
+        if not self.network:
+            raise RuntimeError("APIClient.network is not configured")
+        built_request = http_request or self.build_http_request(request)
+        return self.network.send(built_request)
+
+    def build_http_request(self, request: APIRequest[Any]) -> HTTPRequest:
+        """Build a platform HTTP request from an APIRequest."""
+        headers = dict(self._build_headers(request))
+        url = self._build_url(request.url, request.query)
+        body = self._build_body(request)
+        timeout = request.timeout if request.timeout is not None else self.configuration.timeout
+        http_request = HTTPRequest(method=request.http_method, url=url, headers=headers, body=body, timeout=timeout)
+        if request.authorization:
+            http_request = request.authorization.authorize(http_request)
+        return http_request
+
+    def _build_headers(self, request: APIRequest[Any]) -> Mapping[str, str]:
+        """Build request headers from defaults and request data."""
+        headers: dict[str, str] = {}
+        headers.update(self.additional_http_headers)
+        headers["User-Agent"] = self.user_agent
+        if request.headers:
+            for key, value in request.headers.items():
+                serialized = serialize_request_value(value)
+                if serialized is not None:
+                    headers[key] = serialized
+        if request.accepts_type:
+            headers["Accept"] = request.accepts_type.value
+        if request.content_type:
+            headers["Content-Type"] = request.content_type.value
+        return headers
+
+    def _build_url(self, url: str, query: Mapping[str, RequestValue] | None) -> str:
+        """Build a URL with merged query parameters."""
+        if not query:
+            return url
+        query_string = urlencode(serialize_parameters(query))
+        split = urlsplit(url)
+        merged_query = "&".join(filter(None, [split.query, query_string]))
+        return urlunsplit((split.scheme, split.netloc, split.path, merged_query, split.fragment))
+
+    def _build_body(self, request: APIRequest[Any]) -> bytes | None:
+        """Serialize the request body based on content type."""
+        if isinstance(request, APIRequestBody):
+            params = serialize_parameters(request.body_parameters)
+            if request.content_type == APIContentType.JSON:
+                return json.dumps(params).encode("utf-8")
+            return urlencode(params).encode("utf-8")
+        return request.body()
+
+    def _extract_request_id(self, headers: Mapping[str, str]) -> str | None:
+        """Extract a request ID from response headers, if configured."""
+        if not self.request_id_header:
+            return None
+        for key, value in headers.items():
+            if key.lower() == self.request_id_header.lower():
+                return value
+        return None
+
+
+class DefaultNetworkInterface(NetworkInterface):
+    """Default network interface using urllib.request."""
+
+    def send(self, request: HTTPRequest) -> RawResponse:
+        req = urllib.request.Request(
+            request.url,
+            data=request.body,
+            headers=request.headers,
+            method=request.method.value,
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=request.timeout) as response:
+                body = response.read() or b""
+                headers = {k: v for k, v in response.headers.items()}
+                return RawResponse(status_code=response.status, headers=headers, body=body)
+        except urllib.error.HTTPError as error:
+            body = error.read() or b""
+            headers = {k: v for k, v in error.headers.items()}
+            return RawResponse(status_code=error.code, headers=headers, body=body)