destiny_sdk 0.1.0__py3-none-any.whl

destiny_sdk/__init__.py

@@ -0,0 +1,23 @@
+"""The DESTINY SDK provides files for interacting with DESTINY repository."""
+
+from . import (
+    auth,
+    client,
+    enhancements,
+    identifiers,
+    imports,
+    references,
+    robots,
+    visibility,
+)
+
+__all__ = [
+    "auth",
+    "client",
+    "enhancements",
+    "identifiers",
+    "imports",
+    "references",
+    "robots",
+    "visibility",
+]

destiny_sdk/auth.py

@@ -0,0 +1,204 @@
+"""HMAC authentication assistance methods."""
+
+import hashlib
+import hmac
+import time
+from typing import Protocol, Self
+from uuid import UUID
+
+from fastapi import HTTPException, Request, status
+from pydantic import UUID4, BaseModel
+
+FIVE_MINUTES = 60 * 5
+
+
+class AuthException(HTTPException):
+    """
+    An exception related to HTTP authentication.
+
+    Raised by implementations of the AuthMethod protocol.
+
+    .. code-block:: python
+
+        raise AuthException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Unable to parse authentication token.",
+        )
+
+    """
+
+
+def create_signature(
+    secret_key: str, request_body: bytes, client_id: UUID4, timestamp: float
+) -> str:
+    """
+    Create an HMAC signature using SHA256.
+
+    :param secret_key: secret key with which to encrypt message
+    :type secret_key: bytes
+    :param request_body: request body to be encrypted
+    :type request_body: bytes
+    :param client_id: client id to include in hmac
+    :type: UUID4
+    :param timestamp: timestamp for when the request is sent
+    :type: float
+    :return: encrypted hexdigest of the request body with the secret key
+    :rtype: str
+    """
+    timestamp_bytes = f"{timestamp}".encode()
+    signature_components = b":".join([request_body, client_id.bytes, timestamp_bytes])
+    return hmac.new(
+        secret_key.encode(), signature_components, hashlib.sha256
+    ).hexdigest()
+
+
+class HMACAuthorizationHeaders(BaseModel):
+    """
+    The HTTP authorization headers required for HMAC authentication.
+
+    Expects the following headers to be present in the request
+
+    - Authorization: Signature [request signature]
+    - X-Client-Id: [UUID]
+    - X-Request-Timestamp: [float]
+    """
+
+    signature: str
+    client_id: UUID4
+    timestamp: float
+
+    @classmethod
+    def from_request(cls, request: Request) -> Self:
+        """
+        Get the required headers for HMAC authentication.
+
+        :param request: The incoming request
+        :type request: Request
+        :raises AuthException: Authorization header is missing
+        :raises AuthException: Authorization type not supported
+        :raises AuthException: X-Client-Id header is missing
+        :raises AuthException: Client id format is invalid
+        :raises AuthException: X-Request-Timestamp header is missing
+        :raises AuthException: Request timestamp has expired
+        :return: Header values necessary for authenticating the request
+        :rtype: HMACAuthorizationHeaders
+        """
+        signature_header = request.headers.get("Authorization")
+
+        if not signature_header:
+            raise AuthException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Authorization header missing.",
+            )
+
+        scheme, _, signature = signature_header.partition(" ")
+
+        if scheme != "Signature":
+            raise AuthException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Authorization type not supported.",
+            )
+
+        client_id = request.headers.get("X-Client-Id")
+
+        if not client_id:
+            raise AuthException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="X-Client-Id header missing",
+            )
+
+        try:
+            UUID(client_id)
+        except (ValueError, TypeError) as exc:
+            raise AuthException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid format for client id, expected UUID4.",
+            ) from exc
+
+        timestamp = request.headers.get("X-Request-Timestamp")
+
+        if not timestamp:
+            raise AuthException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="X-Request-Timestamp header missing",
+            )
+
+        if (time.time() - float(timestamp)) > FIVE_MINUTES:
+            raise AuthException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Request timestamp has expired.",
+            )
+
+        return cls(signature=signature, client_id=client_id, timestamp=timestamp)
+
+
+class HMACAuthMethod(Protocol):
+    """
+    Protocol for HMAC auth methods, enforcing the implmentation of __call__().
+
+    This allows FastAPI to call class instances as depenedencies in FastAPI routes,
+    see https://fastapi.tiangolo.com/advanced/advanced-dependencies
+
+        .. code-block:: python
+
+            auth = HMACAuthMethod()
+
+            router = APIRouter(
+                prefix="/robots", tags=["robot"], dependencies=[Depends(auth)]
+            )
+    """
+
+    async def __call__(self, request: Request) -> bool:
+        """
+        Callable interface to allow use as a dependency.
+
+        :param request: The request to verify
+        :type request: Request
+        :raises NotImplementedError: __call__() method has not been implemented.
+        :return: True if authorization is successful.
+        :rtype: bool
+        """
+        raise NotImplementedError
+
+
+class HMACAuth(HMACAuthMethod):
+    """Adds HMAC auth when used as a router or endpoint dependency."""
+
+    def __init__(self, secret_key: str) -> None:
+        """Initialise HMAC auth with a given secret key."""
+        self.secret_key = secret_key
+
+    async def __call__(self, request: Request) -> bool:
+        """Perform Authorization check."""
+        auth_headers = HMACAuthorizationHeaders.from_request(request)
+        request_body = await request.body()
+        expected_signature = create_signature(
+            self.secret_key,
+            request_body,
+            auth_headers.client_id,
+            auth_headers.timestamp,
+        )
+
+        if not hmac.compare_digest(auth_headers.signature, expected_signature):
+            raise AuthException(
+                status_code=status.HTTP_401_UNAUTHORIZED, detail="Signature is invalid."
+            )
+
+        return True
+
+
+class BypassHMACAuth(HMACAuthMethod):
+    """
+    A fake auth class that will always respond successfully.
+
+    Intended for use in local environments and for testing.
+
+    Not for production use!
+    """
+
+    async def __call__(
+        self,
+        request: Request,  # noqa: ARG002
+    ) -> bool:
+        """Bypass Authorization check."""
+        return True

destiny_sdk/client.py

@@ -0,0 +1,113 @@
+"""Send authenticated requests to Destiny Repository."""
+
+import time
+from collections.abc import Generator
+
+import httpx
+from pydantic import UUID4, HttpUrl
+
+from destiny_sdk.robots import (
+    BatchEnhancementRequestRead,
+    BatchRobotResult,
+    EnhancementRequestRead,
+    RobotResult,
+)
+
+from .auth import create_signature
+
+
+class HMACSigningAuth(httpx.Auth):
+    """Client that adds an HMAC signature to a request."""
+
+    requires_request_body = True
+
+    def __init__(self, secret_key: str, client_id: UUID4) -> None:
+        """
+        Initialize the client.
+
+        :param secret_key: the key to use when signing the request
+        :type secret_key: str
+        """
+        self.secret_key = secret_key
+        self.client_id = client_id
+
+    def auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response]:
+        """
+        Add a signature to the given request.
+
+        :param request: request to be sent with signature
+        :type request: httpx.Request
+        :yield: Generator for Request with signature headers set
+        :rtype: Generator[httpx.Request, httpx.Response]
+        """
+        timestamp = time.time()
+        signature = create_signature(
+            self.secret_key, request.content, self.client_id, timestamp
+        )
+        request.headers["Authorization"] = f"Signature {signature}"
+        request.headers["X-Client-Id"] = f"{self.client_id}"
+        request.headers["X-Request-Timestamp"] = f"{timestamp}"
+        yield request
+
+
+class Client:
+    """
+    Client for interaction with the Destiny API.
+
+    Current implementation only supports robot results.
+    """
+
+    def __init__(self, base_url: HttpUrl, secret_key: str, client_id: UUID4) -> None:
+        """
+        Initialize the client.
+
+        :param base_url: The base URL for the Destiny Repository API.
+        :type base_url: HttpUrl
+        :param secret_key: The secret key for signing requests
+        :type auth_method: str
+        """
+        self.session = httpx.Client(
+            base_url=str(base_url),
+            headers={"Content-Type": "application/json"},
+            auth=HMACSigningAuth(secret_key=secret_key, client_id=client_id),
+        )
+
+    def send_robot_result(self, robot_result: RobotResult) -> EnhancementRequestRead:
+        """
+        Send a RobotResult to destiny repository.
+
+        Signs the request with the client's secret key.
+
+        :param robot_result: The Robot Result to send
+        :type robot_result: RobotResult
+        :return: The EnhancementRequestRead object from the response.
+        :rtype: EnhancementRequestRead
+        """
+        response = self.session.post(
+            "/robot/enhancement/single/",
+            json=robot_result.model_dump(mode="json"),
+        )
+        response.raise_for_status()
+        return EnhancementRequestRead.model_validate(response.json())
+
+    def send_batch_robot_result(
+        self, batch_robot_result: BatchRobotResult
+    ) -> BatchEnhancementRequestRead:
+        """
+        Send a BatchRobotResult to destiny repository.
+
+        Signs the request with the client's secret key.
+
+        :param batch_robot_result: The Batch Robot Result to send
+        :type batch_robot_result: BatchRobotResult
+        :return: The BatchEnhancementRequestRead object from the response.
+        :rtype: BatchEnhancementRequestRead
+        """
+        response = self.session.post(
+            "/robot/enhancement/batch/",
+            json=batch_robot_result.model_dump(mode="json"),
+        )
+        response.raise_for_status()
+        return BatchEnhancementRequestRead.model_validate(response.json())

destiny_sdk/core.py

@@ -0,0 +1,35 @@
+"""Core classes for the Destiny SDK, not exposed to package users."""
+
+from typing import Self
+
+from pydantic import BaseModel
+
+
+class _JsonlFileInputMixIn(BaseModel):
+    """
+    A mixin class for models that are used at the top-level for entries in .jsonl files.
+
+    This class is used to define a common interface for file input models.
+    It is not intended to be used directly.
+    """
+
+    def to_jsonl(self) -> str:
+        """
+        Convert the model to a JSONL string.
+
+        :return: The JSONL string representation of the model.
+        :rtype: str
+        """
+        return self.model_dump_json(exclude_none=True)
+
+    @classmethod
+    def from_jsonl(cls, jsonl: str) -> Self:
+        """
+        Create an object from a JSONL string.
+
+        :param jsonl: The JSONL string to parse.
+        :type jsonl: str
+        :return: The created object.
+        :rtype: Self
+        """
+        return cls.model_validate_json(jsonl)