didit-sdk 0.1.0__py3-none-any.whl

didit/__init__.py

@@ -0,0 +1,64 @@
+"""Official-grade Python SDK for Didit Identity Verification & KYC.
+
+Disclaimer:
+    This is an independent open-source library and is not officially affiliated
+    with or endorsed by Didit Protocol Inc.
+"""
+
+from didit.client import AsyncDidit, Didit
+from didit.config import DiditConfig
+from didit.errors import (
+    DiditAPIError,
+    DiditAuthenticationError,
+    DiditConfigurationError,
+    DiditError,
+    DiditNotFoundError,
+    DiditRateLimitError,
+    DiditServerError,
+    DiditSignatureError,
+    DiditTimeoutError,
+)
+from didit.models.decision import (
+    AMLData,
+    BiometricsData,
+    DecisionResponse,
+    DocumentData,
+    ReviewData,
+)
+from didit.models.enums import Language, SessionStatus
+from didit.models.session import CreateSessionRequest, SessionResponse
+from didit.models.webhook import WebhookPayload
+from didit.simulation import SimulatedAsyncDidit, SimulatedDidit
+from didit.webhooks import parse_webhook_payload, verify_webhook_signature
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AMLData",
+    "AsyncDidit",
+    "BiometricsData",
+    "CreateSessionRequest",
+    "DecisionResponse",
+    "Didit",
+    "DiditAPIError",
+    "DiditAuthenticationError",
+    "DiditConfig",
+    "DiditConfigurationError",
+    "DiditError",
+    "DiditNotFoundError",
+    "DiditRateLimitError",
+    "DiditServerError",
+    "DiditSignatureError",
+    "DiditTimeoutError",
+    "DocumentData",
+    "Language",
+    "ReviewData",
+    "SessionResponse",
+    "SessionStatus",
+    "SimulatedAsyncDidit",
+    "SimulatedDidit",
+    "WebhookPayload",
+    "__version__",
+    "parse_webhook_payload",
+    "verify_webhook_signature",
+]

didit/client.py

@@ -0,0 +1,204 @@
+"""Synchronous and asynchronous Didit client implementations."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from didit.config import DiditConfig
+from didit.errors import DiditConfigurationError
+from didit.models.webhook import WebhookPayload
+from didit.resources.sessions import AsyncSessionsResource, SessionsResource
+from didit.webhooks import parse_webhook_payload, verify_webhook_signature
+
+
+class Didit:
+    """Synchronous client for the Didit Verification API."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        webhook_secret: str | None = None,
+        config: DiditConfig | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        if config is not None:
+            self._config = config
+        else:
+            self._config = DiditConfig.from_env(
+                api_key=api_key,
+                base_url=base_url,
+                timeout=timeout,
+                max_retries=max_retries,
+                webhook_secret=webhook_secret,
+            )
+
+        self._manage_http = http_client is None
+        self._http = http_client or httpx.Client(
+            base_url=self._config.base_url,
+            headers={
+                "x-api-key": self._config.api_key,
+                "Accept": "application/json",
+            },
+            timeout=self._config.timeout,
+        )
+
+        self.sessions = SessionsResource(self._http)
+
+    @property
+    def config(self) -> DiditConfig:
+        """Client configuration instance."""
+        return self._config
+
+    @property
+    def http_client(self) -> httpx.Client:
+        """Underlying httpx.Client instance."""
+        return self._http
+
+    def verify_webhook(
+        self,
+        raw_body: bytes,
+        headers: Mapping[str, str],
+        *,
+        secret: str | None = None,
+        max_age_seconds: int | None = None,
+    ) -> bool:
+        """Verify an incoming webhook's signature and timestamp freshness."""
+        wh_secret = secret or self._config.webhook_secret
+        if not wh_secret:
+            raise DiditConfigurationError(
+                "No webhook_secret configured on client. "
+                "Provide secret parameter or configure DIDIT_WEBHOOK_SECRET."
+            )
+        return verify_webhook_signature(
+            raw_body, headers, wh_secret, max_age_seconds=max_age_seconds
+        )
+
+    def parse_webhook(
+        self,
+        raw_body: bytes,
+        headers: Mapping[str, str],
+        *,
+        secret: str | None = None,
+        max_age_seconds: int | None = None,
+    ) -> WebhookPayload:
+        """Verify and parse an incoming webhook payload into a WebhookPayload object."""
+        wh_secret = secret or self._config.webhook_secret
+        if not wh_secret:
+            raise DiditConfigurationError(
+                "No webhook_secret configured on client. "
+                "Provide secret parameter or configure DIDIT_WEBHOOK_SECRET."
+            )
+        return parse_webhook_payload(raw_body, headers, wh_secret, max_age_seconds=max_age_seconds)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        if self._manage_http:
+            self._http.close()
+
+    def __enter__(self) -> Didit:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class AsyncDidit:
+    """Asynchronous client for the Didit Verification API."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        webhook_secret: str | None = None,
+        config: DiditConfig | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        if config is not None:
+            self._config = config
+        else:
+            self._config = DiditConfig.from_env(
+                api_key=api_key,
+                base_url=base_url,
+                timeout=timeout,
+                max_retries=max_retries,
+                webhook_secret=webhook_secret,
+            )
+
+        self._manage_http = http_client is None
+        self._http = http_client or httpx.AsyncClient(
+            base_url=self._config.base_url,
+            headers={
+                "x-api-key": self._config.api_key,
+                "Accept": "application/json",
+            },
+            timeout=self._config.timeout,
+        )
+
+        self.sessions = AsyncSessionsResource(self._http)
+
+    @property
+    def config(self) -> DiditConfig:
+        """Client configuration instance."""
+        return self._config
+
+    @property
+    def http_client(self) -> httpx.AsyncClient:
+        """Underlying httpx.AsyncClient instance."""
+        return self._http
+
+    def verify_webhook(
+        self,
+        raw_body: bytes,
+        headers: Mapping[str, str],
+        *,
+        secret: str | None = None,
+        max_age_seconds: int | None = None,
+    ) -> bool:
+        """Verify an incoming webhook's signature and timestamp freshness."""
+        wh_secret = secret or self._config.webhook_secret
+        if not wh_secret:
+            raise DiditConfigurationError(
+                "No webhook_secret configured on client. "
+                "Provide secret parameter or configure DIDIT_WEBHOOK_SECRET."
+            )
+        return verify_webhook_signature(
+            raw_body, headers, wh_secret, max_age_seconds=max_age_seconds
+        )
+
+    def parse_webhook(
+        self,
+        raw_body: bytes,
+        headers: Mapping[str, str],
+        *,
+        secret: str | None = None,
+        max_age_seconds: int | None = None,
+    ) -> WebhookPayload:
+        """Verify and parse an incoming webhook payload into a WebhookPayload object."""
+        wh_secret = secret or self._config.webhook_secret
+        if not wh_secret:
+            raise DiditConfigurationError(
+                "No webhook_secret configured on client. "
+                "Provide secret parameter or configure DIDIT_WEBHOOK_SECRET."
+            )
+        return parse_webhook_payload(raw_body, headers, wh_secret, max_age_seconds=max_age_seconds)
+
+    async def aclose(self) -> None:
+        """Close the underlying asynchronous HTTP client."""
+        if self._manage_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncDidit:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()

didit/config.py

@@ -0,0 +1,68 @@
+"""Configuration and global defaults for Didit SDK."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+DEFAULT_BASE_URL: str = "https://verification.didit.me/v3"
+DEFAULT_TIMEOUT: float = 30.0
+DEFAULT_MAX_RETRIES: int = 2
+DEFAULT_WEBHOOK_MAX_AGE_SECONDS: int = 300  # 5 minutes
+
+
+@dataclass(frozen=True)
+class DiditConfig:
+    """Immutable client configuration."""
+
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+    timeout: float = DEFAULT_TIMEOUT
+    max_retries: int = DEFAULT_MAX_RETRIES
+    webhook_secret: str | None = None
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        webhook_secret: str | None = None,
+    ) -> DiditConfig:
+        """Resolve configuration falling back to environment variables."""
+        resolved_key = api_key or os.environ.get("DIDIT_API_KEY")
+        if not resolved_key:
+            from didit.errors import DiditConfigurationError
+
+            raise DiditConfigurationError(
+                "Missing Didit API key. "
+                "Provide api_key or set the DIDIT_API_KEY environment variable."
+            )
+
+        resolved_base_url = (
+            base_url or os.environ.get("DIDIT_BASE_URL") or DEFAULT_BASE_URL
+        ).rstrip("/")
+
+        resolved_timeout = (
+            timeout
+            if timeout is not None
+            else float(os.environ.get("DIDIT_TIMEOUT", DEFAULT_TIMEOUT))
+        )
+
+        resolved_retries = (
+            max_retries
+            if max_retries is not None
+            else int(os.environ.get("DIDIT_MAX_RETRIES", DEFAULT_MAX_RETRIES))
+        )
+
+        resolved_secret = webhook_secret or os.environ.get("DIDIT_WEBHOOK_SECRET")
+
+        return cls(
+            api_key=resolved_key,
+            base_url=resolved_base_url,
+            timeout=resolved_timeout,
+            max_retries=resolved_retries,
+            webhook_secret=resolved_secret,
+        )

didit/errors.py

@@ -0,0 +1,83 @@
+"""Exception hierarchy for didit-sdk."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+
+class DiditError(Exception):
+    """Base exception for all Didit SDK errors."""
+
+
+class DiditConfigurationError(DiditError):
+    """Raised when the client is configured with missing or invalid parameters."""
+
+
+class DiditSignatureError(DiditError):
+    """Raised when a webhook signature fails cryptographic verification or freshness check."""
+
+
+class DiditTimeoutError(DiditError):
+    """Raised when an operation such as polling exceeds the configured timeout limit."""
+
+
+class DiditAPIError(DiditError):
+    """Raised when the Didit API returns an HTTP error status code."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        response_body: str | None = None,
+        headers: Mapping[str, str] | None = None,
+        error_code: str | None = None,
+        details: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body
+        self.headers = dict(headers) if headers else {}
+        self.error_code = error_code
+        self.details = details
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}(status_code={self.status_code}, "
+            f"error_code={self.error_code!r}, message={str(self)!r})"
+        )
+
+
+class DiditAuthenticationError(DiditAPIError):
+    """Raised on 401 Unauthorized or 403 Forbidden responses (invalid API key)."""
+
+
+class DiditNotFoundError(DiditAPIError):
+    """Raised on 404 Not Found responses (session or resource does not exist)."""
+
+
+class DiditRateLimitError(DiditAPIError):
+    """Raised on 429 Too Many Requests responses."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int = 429,
+        response_body: str | None = None,
+        headers: Mapping[str, str] | None = None,
+        retry_after: float | None = None,
+    ) -> None:
+        super().__init__(
+            message,
+            status_code=status_code,
+            response_body=response_body,
+            headers=headers,
+            error_code="RATE_LIMIT_EXCEEDED",
+        )
+        self.retry_after = retry_after
+
+
+class DiditServerError(DiditAPIError):
+    """Raised on 5xx Internal Server Error responses."""

didit/integrations/__init__.py

@@ -0,0 +1,5 @@
+"""Web framework integrations for Didit SDK."""
+
+from didit.integrations.fastapi import DiditWebhookGuard
+
+__all__ = ["DiditWebhookGuard"]

didit/integrations/fastapi.py

@@ -0,0 +1,72 @@
+"""FastAPI integration utilities and webhook security guard."""
+
+from __future__ import annotations
+
+import json
+import os
+
+from starlette.requests import Request
+
+from didit.config import DEFAULT_WEBHOOK_MAX_AGE_SECONDS
+from didit.errors import DiditConfigurationError
+from didit.models.webhook import WebhookPayload
+from didit.webhooks import verify_webhook_signature
+
+
+class DiditWebhookGuard:
+    """FastAPI dependency for verifying and parsing Didit webhook requests.
+
+    Example:
+        ```python
+        guard = DiditWebhookGuard(secret="whsec_...")
+
+        @app.post("/webhooks/didit")
+        async def handle_webhook(payload: WebhookPayload = Depends(guard)):
+            if payload.status == SessionStatus.APPROVED:
+                # Process approved KYC verification
+                ...
+        ```
+    """
+
+    def __init__(
+        self,
+        secret: str | None = None,
+        *,
+        max_age_seconds: int = DEFAULT_WEBHOOK_MAX_AGE_SECONDS,
+    ) -> None:
+        resolved_secret = secret or os.environ.get("DIDIT_WEBHOOK_SECRET")
+        if not resolved_secret:
+            raise DiditConfigurationError(
+                "Missing webhook secret. "
+                "Provide secret parameter or set DIDIT_WEBHOOK_SECRET environment variable."
+            )
+        self.secret: str = resolved_secret
+        self.max_age_seconds = max_age_seconds
+
+    async def __call__(self, request: Request) -> WebhookPayload:
+        from fastapi import HTTPException
+
+        raw_body = await request.body()
+        try:
+            body_dict = json.loads(raw_body.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            raise HTTPException(status_code=400, detail="Malformed JSON in webhook body") from None
+
+        if not isinstance(body_dict, dict):
+            raise HTTPException(status_code=400, detail="Malformed JSON in webhook body")
+
+        is_valid = verify_webhook_signature(
+            raw_body,
+            request.headers,
+            self.secret,
+            max_age_seconds=self.max_age_seconds,
+        )
+        if not is_valid:
+            raise HTTPException(
+                status_code=401,
+                detail="Invalid webhook signature or expired timestamp",
+            )
+
+        payload = WebhookPayload.model_validate(body_dict)
+        payload.raw_data = body_dict
+        return payload

didit/models/__init__.py

@@ -0,0 +1,25 @@
+"""Domain and data models for Didit SDK."""
+
+from didit.models.decision import (
+    AMLData,
+    BiometricsData,
+    DecisionResponse,
+    DocumentData,
+    ReviewData,
+)
+from didit.models.enums import Language, SessionStatus
+from didit.models.session import CreateSessionRequest, SessionResponse
+from didit.models.webhook import WebhookPayload
+
+__all__ = [
+    "AMLData",
+    "BiometricsData",
+    "CreateSessionRequest",
+    "DecisionResponse",
+    "DocumentData",
+    "Language",
+    "ReviewData",
+    "SessionResponse",
+    "SessionStatus",
+    "WebhookPayload",
+]

didit/models/decision.py

@@ -0,0 +1,85 @@
+"""Decision and verification result data models."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from didit.models.enums import SessionStatus
+
+
+class DocumentData(BaseModel):
+    """Document extraction and validation data."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    document_type: str | None = Field(
+        default=None, description="e.g. passport, id_card, drivers_license"
+    )
+    country: str | None = Field(default=None, description="ISO-3 country code")
+    document_number: str | None = Field(default=None, description="Masked or raw document number")
+    first_name: str | None = Field(default=None, description="Given names")
+    last_name: str | None = Field(default=None, description="Family names")
+    date_of_birth: str | None = Field(default=None, description="YYYY-MM-DD format")
+    expiration_date: str | None = Field(default=None, description="YYYY-MM-DD format")
+    is_valid: bool | None = Field(
+        default=None, description="Whether document authenticity checks passed"
+    )
+
+
+class BiometricsData(BaseModel):
+    """Facial matching and liveness assessment."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    face_match: bool | None = Field(default=None, description="Face match against document photo")
+    liveness_check: bool | None = Field(
+        default=None, description="Active or passive liveness check"
+    )
+    score: float | None = Field(
+        default=None, description="Biometric confidence score between 0.0 and 1.0"
+    )
+
+
+class AMLData(BaseModel):
+    """Anti-Money Laundering and Watchlist screening results."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    pep_detected: bool | None = Field(
+        default=None, description="Politically Exposed Person detection"
+    )
+    sanctions_detected: bool | None = Field(
+        default=None, description="International sanctions list match"
+    )
+    adverse_media_detected: bool | None = Field(default=None, description="Adverse media match")
+
+
+class ReviewData(BaseModel):
+    """Manual or compliance agent review information."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    reviewed_by: str | None = Field(default=None, description="Identifier of the reviewer")
+    decision_reason: str | None = Field(default=None, description="Reviewer explanation or notes")
+
+
+class DecisionResponse(BaseModel):
+    """Complete verification decision returned by Didit."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    session_id: str = Field(..., description="Unique session identifier")
+    status: SessionStatus = Field(..., description="Final or current verification status")
+    workflow_id: str | None = Field(default=None, description="Associated workflow identifier")
+    vendor_data: str | None = Field(default=None, description="Echoed vendor reference")
+    document: DocumentData | None = Field(default=None, description="Document verification details")
+    biometrics: BiometricsData | None = Field(
+        default=None, description="Biometric matching details"
+    )
+    aml: AMLData | None = Field(default=None, description="AML / Watchlist screening details")
+    review: ReviewData | None = Field(default=None, description="Human review details")
+    raw_data: dict[str, Any] | None = Field(
+        default=None, description="Raw JSON payload received from Didit"
+    )

didit/models/enums.py

@@ -0,0 +1,39 @@
+"""Enumerations for Didit verification statuses and configurations."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class SessionStatus(str, Enum):
+    """Case-sensitive session statuses defined by Didit's Sessions API."""
+
+    NOT_STARTED = "Not Started"
+    IN_PROGRESS = "In Progress"
+    IN_REVIEW = "In Review"
+    APPROVED = "Approved"
+    DECLINED = "Declined"
+
+    @property
+    def is_terminal(self) -> bool:
+        """Return True if the verification workflow has finished (Approved or Declined)."""
+        return self in (SessionStatus.APPROVED, SessionStatus.DECLINED)
+
+    @property
+    def is_in_review(self) -> bool:
+        """Return True if the verification requires manual human review."""
+        return self == SessionStatus.IN_REVIEW
+
+
+class Language(str, Enum):
+    """Supported UI languages for Didit hosted verification pages."""
+
+    EN = "en"
+    ES = "es"
+    FR = "fr"
+    DE = "de"
+    IT = "it"
+    PT = "pt"
+    CA = "ca"
+    EU = "eu"
+    GL = "gl"