mudraid-sdk 1.1.0__py3-none-any.whl

mudraid/__init__.py

@@ -0,0 +1,66 @@
+"""mudraid — Python SDK for MudraID.
+
+Two auth profiles are exposed:
+
+  * :class:`Agent` — the *legacy* profile: a drop-in replacement for ``requests``
+    that authenticates with an api_key_id/secret pair and routes per registered
+    platform. Retained additively; see :meth:`Agent.legacy` and the class
+    docstring's retirement policy.
+  * :class:`MachineAgent` — the *V2 machine-authority* profile:
+    ``private_key_jwt`` client-assertion auth with explicit audience + scopes,
+    resource/scope-bound access tokens, and consequence-safe retry. An omitted
+    scope set is the empty (minimal) set — never a wildcard — and a consequential
+    call whose outcome is unknown is never blindly replayed.
+"""
+
+from mudraid._agent import Agent
+from mudraid._consequence import IDEMPOTENCY_KEY_HEADER, is_idempotent
+from mudraid._machine_agent import MachineAgent
+from mudraid._machine_auth import (
+    AssertionSigner,
+    MachineIdentity,
+    MachineTokenManager,
+    PyJWTSigner,
+    build_client_assertion_claims,
+)
+from mudraid._scopes import RequestedScopes
+from mudraid.exceptions import (
+    MudraIDAuthError,
+    MudraIDBillingFrozenError,
+    MudraIDConfigError,
+    MudraIDError,
+    MudraIDExecutionUnknownError,
+    MudraIDNetworkError,
+    MudraIDPlatformNotRegisteredError,
+    MudraIDRateLimitedError,
+    MudraIDRevokedError,
+    MudraIDScopeError,
+)
+
+__all__ = [
+    # Legacy profile
+    "Agent",
+    # V2 machine-authority profile
+    "MachineAgent",
+    "MachineIdentity",
+    "MachineTokenManager",
+    "AssertionSigner",
+    "PyJWTSigner",
+    "RequestedScopes",
+    "build_client_assertion_claims",
+    "IDEMPOTENCY_KEY_HEADER",
+    "is_idempotent",
+    # Errors
+    "MudraIDError",
+    "MudraIDConfigError",
+    "MudraIDAuthError",
+    "MudraIDRevokedError",
+    "MudraIDNetworkError",
+    "MudraIDPlatformNotRegisteredError",
+    "MudraIDRateLimitedError",
+    "MudraIDScopeError",
+    "MudraIDBillingFrozenError",
+    "MudraIDExecutionUnknownError",
+]
+
+__version__ = "1.1.0"

mudraid/_agent.py

@@ -0,0 +1,342 @@
+"""Agent — public entry point of the MudraID SDK.
+
+Each call:
+
+  1. Resolves the URL's host to a ``platform_id`` via
+     :class:`mudraid._platform_resolver.PlatformResolver`.
+  2. Asks :class:`mudraid._token_manager.TokenManager` for a current
+     JWT for that platform (cache hit, or mint on miss).
+  3. Injects ``Authorization: Bearer <jwt>`` into the outgoing
+     ``requests`` call, preserving every other ``requests`` kwarg.
+  4. Runs the request under consequence-safe retry semantics
+     (:mod:`mudraid._consequence`) and returns the
+     :class:`requests.Response`.
+
+The class mirrors :class:`requests.Session` so an integrator's diff
+is "``import requests``" → "``from mudraid import Agent``".
+
+Consequence safety
+------------------
+
+This client will not replay a request whose replay could duplicate a
+side effect. That applies to both ways a replay can arise:
+
+  * a **transport failure** where the request was sent and no response
+    was read, and
+  * a resource-server **401**, where the token is refreshed and the
+    call retried.
+
+For ``GET``/``HEAD``/``OPTIONS``/``PUT``/``DELETE`` a replay cannot
+duplicate an effect, so it happens as before. For ``POST``/``PATCH``
+it happens only when the caller supplies an ``idempotency_key`` the
+server deduplicates on. Without one, the 401 is returned to the caller
+unreplayed and an ambiguous transport failure raises
+:class:`mudraid.MudraIDExecutionUnknownError`.
+
+This is the same rule :class:`mudraid.MachineAgent` applies. It used to
+differ here, and the difference mattered: a platform that mutated state
+and *then* answered 401 had the mutation performed twice, and the caller
+saw a clean success from the second attempt with nothing to indicate the
+first had landed.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import requests
+
+from mudraid._consequence import execute, is_idempotent
+from mudraid._env import SdkConfig, load_config
+from mudraid._http import MudraIDHttpClient
+from mudraid._platform_resolver import PlatformResolver
+from mudraid._token_manager import TokenManager
+
+_logger = logging.getLogger("mudraid.agent")
+
+
+class Agent:
+    """Authenticated HTTP client that speaks for one MudraID agent.
+
+    .. note:: **Legacy machine-authority profile.**
+
+        This class is the *legacy* auth profile: it authenticates with an
+        api_key_id/secret pair against ``POST /api/v1/auth/token`` and — by
+        design — lets an empty ``scopes`` request expand to the agent's *full*
+        permitted set on the platform. The V2 machine-authority profile
+        (:class:`mudraid.MachineAgent` /
+        :class:`mudraid.MachineIdentity`), where a ``private_key_jwt`` assertion
+        carries explicit audience + scopes and an omitted scope set means the
+        *empty* (minimal) set, never "everything."
+
+        The legacy profile stays fully supported and reachable — additively, so
+        existing integrations do not break — and can be selected explicitly via
+        :meth:`Agent.legacy` to make the choice visible at call sites.
+
+        **Retirement policy:** the legacy profile is retained through the V2
+        transition and is scheduled for removal in a future major SDK release
+        once V2 machine authority is generally available; it will be deprecated
+        (with a runtime warning and a migration window) before any removal. New
+        integrations should adopt :class:`mudraid.MachineAgent`.
+
+    Construction resolves credentials with the following precedence:
+
+      1. Explicit keyword arguments (``api_key_id=``, ``secret=``,
+         ``base_url=``)
+      2. The OS environment (``MUDRAID_API_KEY_ID``, ``MUDRAID_SECRET``,
+         ``MUDRAID_BASE_URL``)
+      3. A ``.env`` file in the project tree (auto-discovered)
+
+    Raises:
+        MudraIDConfigError: when ``api_key_id`` or ``secret`` cannot
+            be resolved from any of the above. ``base_url`` always has a
+            sensible production default and never raises on its own.
+
+    The first outgoing request triggers a one-time bootstrap call to
+    MudraID to learn which platforms this agent is registered with.
+    Subsequent calls are cache-warm.
+    """
+
+    def __init__(
+        self,
+        api_key_id: str | None = None,
+        secret: str | None = None,
+        base_url: str | None = None,
+    ) -> None:
+        self._config: SdkConfig = load_config(
+            api_key_id=api_key_id,
+            secret=secret,
+            base_url=base_url,
+        )
+        # api_key_id is public; base_url is public. Logging both is
+        # safe and useful for "which agent did this?" debugging.
+        _logger.info(
+            "Agent created: api_key_id=%s base_url=%s",
+            self._config.api_key_id,
+            self._config.base_url,
+        )
+        self._mudraid_http = MudraIDHttpClient(self._config)
+        self._tokens = TokenManager(self._mudraid_http)
+        self._platforms = PlatformResolver(self._mudraid_http)
+        # A separate Session for outgoing platform calls. We do NOT
+        # share the MudraID session because the two have different
+        # security properties: MudraID requests carry the agent's
+        # plaintext secret in the body; platform requests carry the
+        # short-lived JWT in a header. Keeping the sessions distinct
+        # makes it impossible to accidentally send one's headers on
+        # the other's connection.
+        self._platform_session = requests.Session()
+
+    @classmethod
+    def legacy(
+        cls,
+        api_key_id: str | None = None,
+        secret: str | None = None,
+        base_url: str | None = None,
+    ) -> "Agent":
+        """Explicitly construct the legacy api_key_id/secret auth profile.
+
+        Behaviourally identical to calling ``Agent(...)`` directly — the default
+        constructor *is* the legacy profile — but naming it at the call site
+        documents the choice now that the V2 profile
+        (:class:`mudraid.MachineAgent`) exists. Provided so integrations can pin
+        themselves to the legacy behaviour intentionally rather than by default,
+        and so a future deprecation can target this explicit entry point. See the
+        class docstring for the retirement policy.
+        """
+        _logger.info("Agent.legacy() — constructing the legacy auth profile explicitly")
+        return cls(api_key_id=api_key_id, secret=secret, base_url=base_url)
+
+    # ---- public, safe-to-read accessors ---------------------------------
+
+    @property
+    def api_key_id(self) -> str:
+        """The public agent identifier (``muid_kid_...``).
+
+        Safe to log and display — this is the public half of the
+        credential pair. The secret is intentionally not exposed via
+        any property.
+        """
+        return self._config.api_key_id
+
+    @property
+    def base_url(self) -> str:
+        """Resolved MudraID API base URL.
+
+        Useful for diagnostics and dev tooling that need to confirm
+        the SDK is pointed at the right backend.
+        """
+        return self._config.base_url
+
+    # ---- maintenance ----------------------------------------------------
+
+    def refresh_platforms(self) -> None:
+        """Force a fresh bootstrap of the platform map.
+
+        Call this after granting a new platform to the agent in the
+        portal, or after removing one. The next outgoing request
+        triggers a re-fetch of ``/auth/agents/me/platforms`` and
+        rebuilds the host→platform_id map. Cached JWTs are also
+        dropped so a now-revoked platform cannot serve a stale token.
+        """
+        _logger.info("Agent.refresh_platforms() — clearing resolver + token caches")
+        self._platforms.refresh()
+        self._tokens.clear()
+
+    def close(self) -> None:
+        """Release the underlying HTTP connection pools.
+
+        Optional — both sessions garbage-collect cleanly. Provided for
+        scripts that want deterministic shutdown.
+        """
+        self._platform_session.close()
+        self._mudraid_http.close()
+
+    # ---- HTTP surface ---------------------------------------------------
+
+    # The idempotent verbs take no ``idempotency_key``: replaying them cannot
+    # duplicate an effect, so nothing about their retry behaviour depends on one.
+    def get(self, url: str, **kwargs: Any) -> requests.Response:
+        return self._request("GET", url, **kwargs)
+
+    def head(self, url: str, **kwargs: Any) -> requests.Response:
+        return self._request("HEAD", url, **kwargs)
+
+    def options(self, url: str, **kwargs: Any) -> requests.Response:
+        return self._request("OPTIONS", url, **kwargs)
+
+    # ``idempotency_key`` is what makes a replay of a consequential call safe:
+    # the server collapses the duplicate. The signature mirrors
+    # :class:`mudraid.MachineAgent` exactly, so moving between the two profiles
+    # is not also a change of retry semantics.
+    def post(
+        self, url: str, *, idempotency_key: str | None = None, **kwargs: Any
+    ) -> requests.Response:
+        return self._request("POST", url, idempotency_key=idempotency_key, **kwargs)
+
+    def patch(
+        self, url: str, *, idempotency_key: str | None = None, **kwargs: Any
+    ) -> requests.Response:
+        return self._request("PATCH", url, idempotency_key=idempotency_key, **kwargs)
+
+    # PUT and DELETE are idempotent, so a key is not needed for SDK-side safety.
+    # It is accepted anyway — a server may still want to deduplicate, and
+    # refusing the argument here would make the two clients disagree.
+    def put(
+        self, url: str, *, idempotency_key: str | None = None, **kwargs: Any
+    ) -> requests.Response:
+        return self._request("PUT", url, idempotency_key=idempotency_key, **kwargs)
+
+    def delete(
+        self, url: str, *, idempotency_key: str | None = None, **kwargs: Any
+    ) -> requests.Response:
+        return self._request("DELETE", url, idempotency_key=idempotency_key, **kwargs)
+
+    # ---- internals ------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        url: str,
+        *,
+        idempotency_key: str | None = None,
+        **kwargs: Any,
+    ) -> requests.Response:
+        """The single point through which every HTTP method flows.
+
+        Behaviour:
+
+          - Resolves the URL host → platform_id. Failure here raises
+            ``MudraIDPlatformNotRegisteredError`` BEFORE any outbound
+            HTTP call.
+          - Asks TokenManager for a JWT for the platform. Failure
+            here raises ``MudraIDAuthError`` / ``MudraIDRevokedError``
+            / ``MudraIDNetworkError`` BEFORE the platform is contacted.
+          - Sends the request with ``Authorization: Bearer <jwt>``,
+            under :func:`mudraid._consequence.execute` so an ambiguous
+            transport failure is never blindly replayed.
+          - On a platform ``401``, refreshes the JWT and replays the
+            request EXACTLY ONCE — **when replaying is consequence-safe**.
+            A second 401 is surfaced to the caller; we never loop. Any
+            other status (200, 4xx, 5xx) is returned unmodified.
+
+        WHY THE 401 REPLAY IS CONDITIONAL. It used to be unconditional,
+        defended by the argument that a 401 proves the platform rejected
+        the request *before* processing it, so the replay is the first
+        time the call is really seen. That argument is about a platform
+        the SDK does not control and cannot inspect. A server that writes
+        and then fails to renew its own auth check, a proxy that turns an
+        expired session into a 401 after forwarding, a gateway that
+        answers 401 on the response path — each produces a 401 that
+        arrives *after* the effect. The SDK cannot distinguish those from
+        the benign case, and the cost of being wrong is a duplicated
+        payment, message or deletion, reported to the caller as a clean
+        success from the second attempt.
+
+        So the rule is the one :class:`mudraid.MachineAgent` already
+        applies: replay when replaying provably cannot duplicate an
+        effect — an idempotent method, or a caller-supplied
+        ``idempotency_key`` the server deduplicates on. Otherwise return
+        the 401 and let the caller decide, which is the only party that
+        knows whether the action is safe to repeat.
+        """
+        platform_id = self._platforms.resolve(url)
+
+        # Pop the caller's headers exactly once so each attempt sees a clean
+        # copy. Without this, a ``kwargs.pop`` inside the retry would silently
+        # drop the caller's headers on the second attempt.
+        caller_headers = dict(kwargs.pop("headers", None) or {})
+
+        def send(extra_headers: dict[str, str]) -> requests.Response:
+            """Attach a current JWT and dispatch one HTTP request.
+
+            Header merge policy: caller-supplied entries first, then the
+            consequence layer's ``Idempotency-Key``, then the SDK's
+            ``Authorization`` last so it always wins. A developer passing their
+            own ``Authorization`` is almost certainly using a different auth
+            mechanism; overriding is correct because attaching the MudraID
+            bearer token is what this client is for.
+
+            The token is fetched per attempt rather than captured once, so a
+            replay after ``TokenManager.refresh`` carries the fresh one.
+            """
+            token = self._tokens.get_token(platform_id)
+            headers = {
+                **caller_headers,
+                **extra_headers,
+                "Authorization": f"Bearer {token}",
+            }
+            return self._platform_session.request(
+                method=method,
+                url=url,
+                headers=headers,
+                **kwargs,
+            )
+
+        response = execute(send, method=method, idempotency_key=idempotency_key)
+        if response.status_code != 401:
+            return response
+
+        if not (is_idempotent(method) or idempotency_key):
+            # Consequential, unkeyed, and the outcome of the first attempt is
+            # not knowable from here. Returning the 401 is the honest answer:
+            # the caller learns authentication failed and decides whether the
+            # action is safe to repeat. Replaying would decide that for them.
+            _logger.warning(
+                "platform returned 401 for %s %s; NOT replaying a consequential "
+                "call with no idempotency key (a post-mutation 401 would be "
+                "duplicated) — returning the 401. Pass idempotency_key= to make "
+                "the replay safe.",
+                method,
+                url,
+            )
+            return response
+
+        _logger.warning(
+            "platform returned 401 for %s %s; refreshing token and retrying once",
+            method,
+            url,
+        )
+        self._tokens.refresh(platform_id)
+        return execute(send, method=method, idempotency_key=idempotency_key)

mudraid/_consequence.py

@@ -0,0 +1,153 @@
+"""Consequence-safe request execution — the no-blind-replay invariant.
+
+The invariant: *a consequential call whose outcome is
+unknown must not be blindly retried in a way that could duplicate a
+side-effecting action.* This module classifies failures precisely so retries
+happen only where they are provably safe:
+
+  * **Pre-response failures** (the server never received the request — e.g. a
+    connect timeout) are safe to retry for *any* method: the action never
+    started.
+  * **Idempotent methods** (``GET``/``HEAD``/``OPTIONS``/``PUT``/``DELETE``, per
+    RFC 7231) are safe to retry even on an *ambiguous* failure: replaying them
+    cannot duplicate an effect by definition.
+  * **Ambiguous failures on a consequential method** (``POST``/``PATCH`` sent,
+    but no response read — a read timeout, a mid-flight connection drop) are the
+    dangerous case. Here the server may have fully processed the action, so the
+    SDK does **not** retry. Instead it either
+      - attaches a caller-supplied **idempotency key** the server deduplicates,
+        making the replay safe, or
+      - raises :class:`mudraid.MudraIDExecutionUnknownError` and hands the
+        outcome-unknown decision back to the caller.
+
+An *HTTP response* — even a 5xx — is a definite outcome and is always returned;
+retrying on status codes is a separate policy the SDK intentionally leaves to
+the caller. Only *transport* exceptions are classified here.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Callable
+
+import requests
+
+from mudraid.exceptions import MudraIDExecutionUnknownError
+
+_logger = logging.getLogger("mudraid.consequence")
+
+# RFC 7231 idempotent methods: replaying them cannot duplicate an effect, so an
+# ambiguous (sent, no response) failure may be safely retried.
+_IDEMPOTENT_METHODS = frozenset({"GET", "HEAD", "OPTIONS", "PUT", "DELETE", "TRACE"})
+
+# The header the server deduplicates on. A stable key across attempts lets the
+# server collapse a replayed consequential call to a single effect.
+IDEMPOTENCY_KEY_HEADER = "Idempotency-Key"
+
+
+def is_idempotent(method: str) -> bool:
+    """True if ``method`` is idempotent (safe to replay on an ambiguous failure)."""
+    return method.upper() in _IDEMPOTENT_METHODS
+
+
+def _is_pre_response_failure(exc: requests.RequestException) -> bool:
+    """True when the request provably never reached the server.
+
+    A connect timeout means the TCP/TLS connection was never established, so the
+    server never saw the request — the action never started and a retry is safe
+    for any method. Everything else that happens *after* a connection exists
+    (read timeouts, mid-flight drops, chunked-encoding truncation) is treated as
+    ambiguous: the bytes may already be on the server.
+    """
+    if isinstance(exc, requests.exceptions.ConnectTimeout):
+        return True
+    # A ConnectionError raised while *establishing* the connection is
+    # pre-response; requests does not always distinguish, so we stay
+    # conservative and treat a bare ConnectionError as ambiguous unless it is a
+    # ConnectTimeout (handled above). Under-claiming "pre-response" is the safe
+    # direction: at worst we refuse a retry that would have been fine.
+    return False
+
+
+def execute(
+    send: Callable[[dict[str, str]], requests.Response],
+    *,
+    method: str,
+    idempotency_key: str | None = None,
+    max_retries: int = 1,
+) -> requests.Response:
+    """Run a request with consequence-safe retry semantics.
+
+    Args:
+        send: performs one attempt given the extra headers to merge in (so the
+            idempotency-key header can be injected on retries). Returns the
+            :class:`requests.Response`, or raises a ``requests.RequestException``
+            on a transport failure.
+        method: the HTTP method, used to classify idempotency.
+        idempotency_key: when provided, attached as the ``Idempotency-Key``
+            header on every attempt so the server can deduplicate a replay —
+            which makes retrying a consequential call safe.
+        max_retries: additional attempts after the first, used only where a
+            retry is provably safe. Defaults to a single extra attempt.
+
+    Returns:
+        The :class:`requests.Response` from the first attempt that produced one.
+
+    Raises:
+        MudraIDExecutionUnknownError: an ambiguous failure on a consequential
+            method with no idempotency key — the outcome is unknown and the SDK
+            refuses to duplicate the action.
+        requests.RequestException: a transport failure that exhausted the safe
+            retry budget (e.g. repeated connect timeouts).
+    """
+    extra_headers: dict[str, str] = {}
+    if idempotency_key:
+        extra_headers[IDEMPOTENCY_KEY_HEADER] = idempotency_key
+
+    method_upper = method.upper()
+    # A key or an idempotent method makes a replay safe; otherwise a replay could
+    # duplicate the action and is forbidden on an ambiguous failure.
+    retry_is_safe = bool(idempotency_key) or is_idempotent(method_upper)
+
+    attempt = 0
+    while True:
+        try:
+            # A completed HTTP response — any status — is a definite outcome.
+            return send(extra_headers)
+        except requests.RequestException as exc:
+            pre_response = _is_pre_response_failure(exc)
+            can_retry = (pre_response or retry_is_safe) and attempt < max_retries
+            if can_retry:
+                attempt += 1
+                _logger.warning(
+                    "transport failure on %s (attempt %d); retry is safe "
+                    "(pre_response=%s idempotent=%s keyed=%s), retrying",
+                    method_upper,
+                    attempt,
+                    pre_response,
+                    is_idempotent(method_upper),
+                    bool(idempotency_key),
+                    exc_info=False,
+                )
+                continue
+
+            if not pre_response and not retry_is_safe:
+                # The consequential + ambiguous case: sent, outcome unknown, no
+                # dedupe key. Do NOT replay — surface a typed result so the
+                # caller reconciles or re-issues with an idempotency key. The
+                # transport error is chained; the message carries no request body.
+                _logger.warning(
+                    "ambiguous failure on consequential %s with no idempotency key; "
+                    "NOT retrying — surfacing execution-unknown",
+                    method_upper,
+                )
+                raise MudraIDExecutionUnknownError(
+                    f"the {method_upper} request was sent but its outcome is unknown "
+                    "(no response, no idempotency key). It was NOT retried to avoid "
+                    "duplicating a side effect; verify server state or re-issue with an "
+                    "idempotency key the server deduplicates."
+                ) from exc
+
+            # Safe-to-retry class but the retry budget is exhausted — surface the
+            # original transport error unchanged.
+            raise