dfns-sdk 0.0.0.dev0__py3-none-any.whl

dfns_sdk/__init__.py

@@ -0,0 +1,24 @@
+"""Dfns Python SDK - Auto-generated from OpenAPI specification."""
+
+from .client import DfnsClient
+from .delegated_client import DfnsDelegatedClient
+from .types import DfnsClientConfig, DfnsDelegatedClientConfig, DfnsError
+from .auth import Signer, KeySigner
+from .base_auth_api import (
+    BaseAuthApi,
+    UserActionChallengeResponse,
+    SignUserActionChallengeRequest,
+)
+
+__all__ = [
+    "DfnsClient",
+    "DfnsDelegatedClient",
+    "DfnsClientConfig",
+    "DfnsDelegatedClientConfig",
+    "DfnsError",
+    "Signer",
+    "KeySigner",
+    "BaseAuthApi",
+    "UserActionChallengeResponse",
+    "SignUserActionChallengeRequest",
+]

dfns_sdk/_internal/__init__.py

@@ -0,0 +1,5 @@
+"""Internal modules."""
+
+from .http_client import HttpClient, AsyncHttpClient
+
+__all__ = ["HttpClient", "AsyncHttpClient"]

dfns_sdk/_internal/http_client.py

@@ -0,0 +1,395 @@
+"""HTTP client for making API requests."""
+
+import json
+from typing import Any, Optional, TypeVar, TYPE_CHECKING
+from urllib.parse import urlencode
+
+import httpx
+
+from dfns_sdk.types import DfnsClientConfig, DfnsDelegatedClientConfig, DfnsError
+
+if TYPE_CHECKING:
+    from dfns_sdk.auth import Signer
+
+T = TypeVar("T")
+
+
+
+class HttpClient:
+    """HTTP client for Dfns API requests."""
+
+    def __init__(self, config: "DfnsClientConfig | DfnsDelegatedClientConfig"):
+        self.config = config
+        self._client = httpx.Client(
+            base_url=config.base_url,
+            timeout=30.0,
+        )
+
+    def _build_headers(self, user_action_token: Optional[str] = None) -> dict[str, str]:
+        """Build request headers."""
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.config.auth_token}",
+            **self.config.headers,
+        }
+
+        if user_action_token:
+            headers["X-DFNS-USERACTION"] = user_action_token
+
+        return headers
+
+    def _build_url(
+        self,
+        path: str,
+        path_params: Optional[dict[str, Any]] = None,
+        query_params: Optional[dict[str, Any]] = None,
+    ) -> str:
+        """Build the full URL with path and query parameters."""
+        url = path
+
+        if path_params:
+            for key, value in path_params.items():
+                url = url.replace(f"{{{key}}}", str(value))
+
+        if query_params:
+            filtered_params = {k: v for k, v in query_params.items() if v is not None}
+            if filtered_params:
+                url = f"{url}?{urlencode(filtered_params)}"
+
+        return url
+
+    def _handle_response(self, response: httpx.Response) -> Any:
+        """Handle API response and raise errors if needed."""
+        if response.status_code >= 400:
+            try:
+                error_data = response.json()
+                raise DfnsError(
+                    message=error_data.get("message", "Unknown error"),
+                    status_code=response.status_code,
+                    error_code=error_data.get("error"),
+                    details=error_data.get("details"),
+                )
+            except json.JSONDecodeError:
+                raise DfnsError(
+                    message=response.text or "Unknown error",
+                    status_code=response.status_code,
+                )
+
+        if response.status_code == 204 or not response.content:
+            return None
+
+        return response.json()
+
+    def _get_user_action_token(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Any] = None,
+    ) -> str:
+        """
+        Get a user action token by creating and signing a challenge.
+
+        Args:
+            method: HTTP method.
+            path: Request path.
+            body: Request body.
+
+        Returns:
+            The user action token to include in the request header.
+
+        Raises:
+            DfnsError: If no signer is configured or signing fails.
+        """
+        if not self.config.signer:
+            raise DfnsError(
+                message="Signer required for this operation. Configure a signer in DfnsClientConfig.",
+                status_code=None,
+                error_code="SIGNER_REQUIRED",
+            )
+
+        # Step 1: Create user action challenge
+        challenge_body = {
+            "userActionPayload": json.dumps(body, separators=(",", ":")) if body else "",
+            "userActionHttpMethod": method,
+            "userActionHttpPath": path,
+            "userActionServerKind": "Api",
+        }
+
+        challenge_response = self._client.request(
+            method="POST",
+            url="/auth/action/init",
+            headers=self._build_headers(),
+            json=challenge_body,
+        )
+        challenge = self._handle_response(challenge_response)
+
+        # Step 2: Sign the challenge
+        assertion = self.config.signer.sign(challenge)
+
+        # Step 3: Submit signed challenge to get user action token
+        signature_body = {
+            "challengeIdentifier": challenge["challengeIdentifier"],
+            "firstFactor": assertion,
+        }
+
+        signature_response = self._client.request(
+            method="POST",
+            url="/auth/action",
+            headers=self._build_headers(),
+            json=signature_body,
+        )
+        result = self._handle_response(signature_response)
+
+        return result["userAction"]
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        path_params: Optional[dict[str, Any]] = None,
+        query_params: Optional[dict[str, Any]] = None,
+        body: Optional[Any] = None,
+        requires_signature: bool = False,
+    ) -> Any:
+        """Make an HTTP request to the API."""
+        url = self._build_url(path, path_params, query_params)
+
+        # Get user action token if required
+        user_action_token = None
+        if requires_signature:
+            # Use the path with params substituted for signing
+            signing_path = path
+            if path_params:
+                for key, value in path_params.items():
+                    signing_path = signing_path.replace(f"{{{key}}}", str(value))
+            user_action_token = self._get_user_action_token(method, signing_path, body)
+
+        headers = self._build_headers(user_action_token)
+
+        response = self._client.request(
+            method=method,
+            url=url,
+            headers=headers,
+            json=body if body is not None else None,
+        )
+
+        return self._handle_response(response)
+
+    def request_with_user_action(
+        self,
+        method: str,
+        path: str,
+        path_params: Optional[dict[str, Any]] = None,
+        query_params: Optional[dict[str, Any]] = None,
+        body: Optional[Any] = None,
+        user_action: str = "",
+    ) -> Any:
+        """
+        Make an HTTP request with a pre-signed user action token.
+
+        This method is used by delegated clients where signing is handled externally.
+
+        Args:
+            method: HTTP method.
+            path: Request path.
+            path_params: Path parameters to substitute.
+            query_params: Query parameters.
+            body: Request body.
+            user_action: Pre-signed user action token.
+
+        Returns:
+            The API response.
+        """
+        url = self._build_url(path, path_params, query_params)
+        headers = self._build_headers(user_action if user_action else None)
+
+        response = self._client.request(
+            method=method,
+            url=url,
+            headers=headers,
+            json=body if body is not None else None,
+        )
+
+        return self._handle_response(response)
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> "HttpClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+
+class AsyncHttpClient:
+    """Async HTTP client for Dfns API requests."""
+
+    def __init__(self, config: DfnsClientConfig):
+        self.config = config
+        self._client = httpx.AsyncClient(
+            base_url=config.base_url,
+            timeout=30.0,
+        )
+
+    def _build_headers(self, user_action_token: Optional[str] = None) -> dict[str, str]:
+        """Build request headers."""
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self.config.auth_token}",
+            **self.config.headers,
+        }
+
+        if user_action_token:
+            headers["X-DFNS-USERACTION"] = user_action_token
+
+        return headers
+
+    def _build_url(
+        self,
+        path: str,
+        path_params: Optional[dict[str, Any]] = None,
+        query_params: Optional[dict[str, Any]] = None,
+    ) -> str:
+        """Build the full URL with path and query parameters."""
+        url = path
+
+        if path_params:
+            for key, value in path_params.items():
+                url = url.replace(f"{{{key}}}", str(value))
+
+        if query_params:
+            filtered_params = {k: v for k, v in query_params.items() if v is not None}
+            if filtered_params:
+                url = f"{url}?{urlencode(filtered_params)}"
+
+        return url
+
+    def _handle_response(self, response: httpx.Response) -> Any:
+        """Handle API response and raise errors if needed."""
+        if response.status_code >= 400:
+            try:
+                error_data = response.json()
+                raise DfnsError(
+                    message=error_data.get("message", "Unknown error"),
+                    status_code=response.status_code,
+                    error_code=error_data.get("error"),
+                    details=error_data.get("details"),
+                )
+            except json.JSONDecodeError:
+                raise DfnsError(
+                    message=response.text or "Unknown error",
+                    status_code=response.status_code,
+                )
+
+        if response.status_code == 204 or not response.content:
+            return None
+
+        return response.json()
+
+    async def _get_user_action_token(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Any] = None,
+    ) -> str:
+        """
+        Get a user action token by creating and signing a challenge.
+
+        Args:
+            method: HTTP method.
+            path: Request path.
+            body: Request body.
+
+        Returns:
+            The user action token to include in the request header.
+
+        Raises:
+            DfnsError: If no signer is configured or signing fails.
+        """
+        if not self.config.signer:
+            raise DfnsError(
+                message="Signer required for this operation. Configure a signer in DfnsClientConfig.",
+                status_code=None,
+                error_code="SIGNER_REQUIRED",
+            )
+
+        # Step 1: Create user action challenge
+        challenge_body = {
+            "userActionPayload": json.dumps(body, separators=(",", ":")) if body else "",
+            "userActionHttpMethod": method,
+            "userActionHttpPath": path,
+            "userActionServerKind": "Api",
+        }
+
+        challenge_response = await self._client.request(
+            method="POST",
+            url="/auth/action/init",
+            headers=self._build_headers(),
+            json=challenge_body,
+        )
+        challenge = self._handle_response(challenge_response)
+
+        # Step 2: Sign the challenge
+        assertion = self.config.signer.sign(challenge)
+
+        # Step 3: Submit signed challenge to get user action token
+        signature_body = {
+            "challengeIdentifier": challenge["challengeIdentifier"],
+            "firstFactor": assertion,
+        }
+
+        signature_response = await self._client.request(
+            method="POST",
+            url="/auth/action",
+            headers=self._build_headers(),
+            json=signature_body,
+        )
+        result = self._handle_response(signature_response)
+
+        return result["userAction"]
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        path_params: Optional[dict[str, Any]] = None,
+        query_params: Optional[dict[str, Any]] = None,
+        body: Optional[Any] = None,
+        requires_signature: bool = False,
+    ) -> Any:
+        """Make an async HTTP request to the API."""
+        url = self._build_url(path, path_params, query_params)
+
+        # Get user action token if required
+        user_action_token = None
+        if requires_signature:
+            # Use the path with params substituted for signing
+            signing_path = path
+            if path_params:
+                for key, value in path_params.items():
+                    signing_path = signing_path.replace(f"{{{key}}}", str(value))
+            user_action_token = await self._get_user_action_token(method, signing_path, body)
+
+        headers = self._build_headers(user_action_token)
+
+        response = await self._client.request(
+            method=method,
+            url=url,
+            headers=headers,
+            json=body if body is not None else None,
+        )
+
+        return self._handle_response(response)
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncHttpClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

dfns_sdk/auth.py

@@ -0,0 +1,137 @@
+"""Authentication utilities for the Dfns SDK."""
+
+import base64
+import hashlib
+import json
+from typing import Any, Optional, Protocol, TypedDict
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec, ed25519, padding
+
+
+class UserActionChallenge(TypedDict):
+    """Challenge returned by the server for user action signing."""
+
+    challenge: str
+    challengeIdentifier: str
+    supportedCredentialKinds: list[dict[str, Any]]
+    allowCredentials: dict[str, Any]
+    rp: dict[str, str]
+    externalAuthenticationUrl: str
+
+
+class CredentialAssertion(TypedDict):
+    """Credential assertion for signing."""
+
+    kind: str
+    credentialAssertion: dict[str, str]
+
+
+class Signer(Protocol):
+    """Protocol for signing user action challenges."""
+
+    def sign(self, challenge: UserActionChallenge) -> CredentialAssertion:
+        """
+        Sign a user action challenge.
+
+        Args:
+            challenge: The challenge from the server.
+
+        Returns:
+            The credential assertion to submit to the server.
+        """
+        ...
+
+
+def base64url_encode(data: bytes) -> str:
+    """Encode bytes to base64url string without padding."""
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def base64url_decode(data: str) -> bytes:
+    """Decode base64url string to bytes."""
+    padding = 4 - len(data) % 4
+    if padding != 4:
+        data += "=" * padding
+    return base64.urlsafe_b64decode(data)
+
+
+class KeySigner:
+    """
+    Signer implementation using a private key credential.
+
+    Supports Ed25519, ECDSA (secp256k1, P-256), and RSA keys.
+
+    Example:
+        >>> from dfns_sdk.auth import KeySigner
+        >>> signer = KeySigner(
+        ...     credential_id="cr-xxx-xxx",
+        ...     private_key=open("private_key.pem").read(),
+        ...     app_origin="https://app.dfns.io",
+        ... )
+    """
+
+    def __init__(
+        self,
+        credential_id: str,
+        private_key: str,
+        app_origin: str = "https://app.dfns.io",
+    ):
+        """
+        Initialize the key signer.
+
+        Args:
+            credential_id: The credential ID (cr-xxx-xxx format).
+            private_key: The private key in PEM format.
+            app_origin: The application origin for the client data.
+        """
+        self.credential_id = credential_id
+        self.app_origin = app_origin
+        self._private_key = serialization.load_pem_private_key(
+            private_key.encode() if isinstance(private_key, str) else private_key,
+            password=None,
+        )
+
+    def sign(self, challenge: UserActionChallenge) -> CredentialAssertion:
+        """
+        Sign a user action challenge.
+
+        Args:
+            challenge: The challenge from the server.
+
+        Returns:
+            The credential assertion to submit to the server.
+        """
+        client_data = {
+            "type": "key.get",
+            "challenge": challenge["challenge"],
+            "origin": self.app_origin,
+            "crossOrigin": False,
+        }
+        client_data_json = json.dumps(client_data, separators=(",", ":"))
+        client_data_bytes = client_data_json.encode("utf-8")
+
+        signature = self._sign_bytes(client_data_bytes)
+
+        return {
+            "kind": "Key",
+            "credentialAssertion": {
+                "credId": self.credential_id,
+                "clientData": base64url_encode(client_data_bytes),
+                "signature": base64url_encode(signature),
+            },
+        }
+
+    def _sign_bytes(self, data: bytes) -> bytes:
+        """Sign bytes with the private key."""
+        if isinstance(self._private_key, ed25519.Ed25519PrivateKey):
+            return self._private_key.sign(data)
+        elif isinstance(self._private_key, ec.EllipticCurvePrivateKey):
+            return self._private_key.sign(data, ec.ECDSA(hashes.SHA256()))
+        else:
+            # RSA
+            return self._private_key.sign(
+                data,
+                padding.PKCS1v15(),
+                hashes.SHA256(),
+            )

dfns_sdk/base_auth_api.py

@@ -0,0 +1,129 @@
+"""Base authentication API for delegated client operations."""
+
+import json
+from typing import Any, TypedDict, Optional
+
+from ._internal import HttpClient
+
+
+class AllowCredential(TypedDict):
+    """Allowed credential for signing."""
+
+    type: str
+    id: str
+    transports: list[str]
+
+
+class SupportedCredentialKind(TypedDict):
+    """Supported credential kind."""
+
+    kind: str
+    factor: str
+    requiresSecondFactor: bool
+
+
+class UserActionChallengeResponse(TypedDict):
+    """Response from creating a user action challenge."""
+
+    challengeIdentifier: str
+    challenge: str
+    allowCredentials: list[AllowCredential]
+    supportedCredentialKinds: list[SupportedCredentialKind]
+    userVerification: str
+    rp: dict[str, str]
+    externalAuthenticationUrl: str
+
+
+class SignUserActionChallengeRequest(TypedDict, total=False):
+    """Request to complete a user action challenge."""
+
+    challengeIdentifier: str
+    firstFactor: dict[str, Any]
+    secondFactor: dict[str, Any]
+
+
+class BaseAuthApi:
+    """
+    Helper class for delegated client user action signing.
+
+    This class provides static methods for the two-phase user action signing flow:
+    1. create_user_action_challenge() - Creates a challenge for external signing
+    2. sign_user_action_challenge() - Completes signing with the signed challenge
+
+    Example:
+        >>> # Step 1: Create challenge
+        >>> challenge = BaseAuthApi.create_user_action_challenge(
+        ...     http_client,
+        ...     user_action_http_method="POST",
+        ...     user_action_http_path="/wallets",
+        ...     user_action_payload='{"network":"EthereumSepolia"}',
+        ... )
+        >>>
+        >>> # Step 2: Sign externally (your signing system)
+        >>> signed = your_external_signer.sign(challenge)
+        >>>
+        >>> # Step 3: Complete with signed challenge
+        >>> result = BaseAuthApi.sign_user_action_challenge(
+        ...     http_client,
+        ...     signed_challenge={
+        ...         "challengeIdentifier": challenge["challengeIdentifier"],
+        ...         "firstFactor": signed,
+        ...     },
+        ... )
+    """
+
+    @staticmethod
+    def create_user_action_challenge(
+        http_client: HttpClient,
+        user_action_http_method: str,
+        user_action_http_path: str,
+        user_action_payload: str,
+        user_action_server_kind: str = "Api",
+    ) -> UserActionChallengeResponse:
+        """
+        Create a user action challenge for signing.
+
+        Args:
+            http_client: The HTTP client to use.
+            user_action_http_method: The HTTP method of the action (GET, POST, etc.).
+            user_action_http_path: The path of the action endpoint.
+            user_action_payload: The JSON-serialized request body.
+            user_action_server_kind: The server kind (default: "Api").
+
+        Returns:
+            The challenge response containing the challenge to sign.
+        """
+        return http_client.request(
+            method="POST",
+            path="/auth/action/init",
+            body={
+                "userActionHttpMethod": user_action_http_method,
+                "userActionHttpPath": user_action_http_path,
+                "userActionPayload": user_action_payload,
+                "userActionServerKind": user_action_server_kind,
+            },
+            requires_signature=False,
+        )
+
+    @staticmethod
+    def sign_user_action_challenge(
+        http_client: HttpClient,
+        signed_challenge: SignUserActionChallengeRequest,
+    ) -> dict[str, Any]:
+        """
+        Complete user action signing with a signed challenge.
+
+        Args:
+            http_client: The HTTP client to use.
+            signed_challenge: The signed challenge containing challengeIdentifier
+                and firstFactor (and optional secondFactor).
+
+        Returns:
+            Dictionary containing the userAction token.
+        """
+        return http_client.request(
+            method="POST",
+            path="/auth/action",
+            body=signed_challenge,
+            requires_signature=False,
+        )