crypticorn-utils 0.1.0rc1__py3-none-any.whl

crypticorn_utils/__init__.py

@@ -0,0 +1,16 @@
+from crypticorn_utils.ansi_colors import *
+from crypticorn_utils.auth import *
+from crypticorn_utils.decorators import *
+from crypticorn_utils.enums import *
+from crypticorn_utils.errors import *
+from crypticorn_utils.exceptions import *
+from crypticorn_utils.logging import *
+from crypticorn_utils.metrics import *
+from crypticorn_utils.middleware import *
+from crypticorn_utils.mixins import *
+from crypticorn_utils.openapi import *
+from crypticorn_utils.pagination import *
+from crypticorn_utils.router.admin_router import router as admin_router
+from crypticorn_utils.router.status_router import router as status_router
+from crypticorn_utils.utils import *
+from crypticorn_utils.warnings import *

crypticorn_utils/_migration.py

@@ -0,0 +1,12 @@
+# This file is used to check if the crypticorn version is greater than 2.18
+# This is to be compatible with this new utils library
+
+import importlib.metadata
+from importlib.metadata import PackageNotFoundError
+
+try:
+    crypticorn_version = importlib.metadata.distribution("crypticorn").version
+    parts = crypticorn_version.split(".")
+    has_migrated = parts[0] >= "2" and parts[1] > "18"
+except PackageNotFoundError:
+    has_migrated = False

crypticorn_utils/ansi_colors.py

@@ -0,0 +1,41 @@
+try:
+    from enum import StrEnum
+except ImportError:
+    from strenum import StrEnum
+
+
+class AnsiColors(StrEnum):
+    """Provides a collection of ANSI color codes for terminal text formatting, including regular, bright, and bold text colors. Useful for creating colorful and readable console output."""
+
+    # Regular Text Colors
+    BLACK = "\033[30m"  # black
+    RED = "\033[31m"  # red
+    GREEN = "\033[32m"  # green
+    YELLOW = "\033[33m"  # yellow
+    BLUE = "\033[34m"  # blue
+    MAGENTA = "\033[35m"  # magenta
+    CYAN = "\033[36m"  # cyan
+    WHITE = "\033[37m"  # white
+
+    # Bright Text Colors
+    BLACK_BRIGHT = "\033[90m"  # black_bright
+    RED_BRIGHT = "\033[91m"  # red_bright
+    GREEN_BRIGHT = "\033[92m"  # green_bright
+    YELLOW_BRIGHT = "\033[93m"  # yellow_bright
+    BLUE_BRIGHT = "\033[94m"  # blue_bright
+    MAGENTA_BRIGHT = "\033[95m"  # magenta_bright
+    CYAN_BRIGHT = "\033[96m"  # cyan_bright
+    WHITE_BRIGHT = "\033[97m"  # white_bright
+
+    # Bold Text Colors
+    BLACK_BOLD = "\033[1;30m"  # black_bold
+    RED_BOLD = "\033[1;31m"  # red_bold
+    GREEN_BOLD = "\033[1;32m"  # green_bold
+    YELLOW_BOLD = "\033[1;33m"  # yellow_bold
+    BLUE_BOLD = "\033[1;34m"  # blue_bold
+    MAGENTA_BOLD = "\033[1;35m"  # magenta_bold
+    CYAN_BOLD = "\033[1;36m"  # cyan_bold
+    WHITE_BOLD = "\033[1;37m"  # white_bold
+
+    # Reset Color
+    RESET = "\033[0m"

crypticorn_utils/auth.py

@@ -0,0 +1,345 @@
+import json
+from typing import Union
+
+from crypticorn.auth import AuthClient, Configuration, Verify200Response
+from crypticorn.auth.client.exceptions import ApiException
+from crypticorn_utils.enums import Scope, BaseUrl
+from crypticorn_utils.exceptions import ApiError, ExceptionContent, HTTPException
+from fastapi import Depends, Query
+from fastapi.security import (
+    APIKeyHeader,
+    HTTPAuthorizationCredentials,
+    HTTPBasic,
+    HTTPBasicCredentials,
+    HTTPBearer,
+    SecurityScopes,
+)
+from typing_extensions import Annotated
+
+AUTHENTICATE_HEADER = "WWW-Authenticate"
+BEARER_AUTH_SCHEME = "Bearer"
+APIKEY_AUTH_SCHEME = "X-API-Key"
+BASIC_AUTH_SCHEME = "Basic"
+
+# Auth Schemes
+http_bearer = HTTPBearer(
+    bearerFormat="JWT",
+    auto_error=False,
+    description="The JWT to use for authentication.",
+)
+
+apikey_header = APIKeyHeader(
+    name=APIKEY_AUTH_SCHEME,
+    auto_error=False,
+    description="The API key to use for authentication.",
+)
+
+http_basic = HTTPBasic(
+    scheme_name=BASIC_AUTH_SCHEME,
+    auto_error=False,
+    description="The username and password to use for authentication.",
+)
+
+
+# Auth Handler
+class AuthHandler:
+    """
+    Middleware for verifying API requests. Verifies the validity of the authentication token, scopes, etc.
+
+    :param base_url: The base URL of the API.
+    :param api_version: The version of the API.
+    """
+
+    def __init__(
+        self,
+        base_url: BaseUrl = BaseUrl.PROD,
+    ):
+        self.url = f"{base_url}/v1/auth"
+        self.client = AuthClient(Configuration(host=self.url), is_sync=False)
+
+    async def _verify_api_key(self, api_key: str) -> Verify200Response:
+        """
+        Verifies the API key.
+        """
+        # self.client.config.api_key = {apikey_header.scheme_name: api_key}
+        return await self.client.login.verify_api_key(api_key)
+
+    async def _verify_bearer(
+        self, bearer: HTTPAuthorizationCredentials
+    ) -> Verify200Response:
+        """
+        Verifies the bearer token.
+        """
+        self.client.config.access_token = bearer.credentials
+        return await self.client.login.verify()
+
+    async def _verify_basic(self, basic: HTTPBasicCredentials) -> Verify200Response:
+        """
+        Verifies the basic authentication credentials.
+        """
+        return await self.client.login.verify_basic_auth(basic.username, basic.password)
+
+    async def _validate_scopes(
+        self, api_scopes: list[Scope], user_scopes: list[Scope]
+    ) -> bool:
+        """
+        Checks if the required scopes are a subset of the user scopes.
+        """
+        if not set(api_scopes).issubset(user_scopes):
+            raise HTTPException(
+                content=ExceptionContent(
+                    error=ApiError.INSUFFICIENT_SCOPES,
+                    message="Insufficient scopes to access this resource (required: "
+                    + ", ".join(api_scopes)
+                    + ")",
+                ),
+            )
+
+    async def _extract_message(self, e: ApiException) -> str:
+        """
+        Tries to extract the message from the body of the exception.
+        """
+        try:
+            load = json.loads(e.body)
+        except (json.JSONDecodeError, TypeError):
+            return e.body
+        else:
+            common_keys = ["message"]
+            for key in common_keys:
+                if key in load:
+                    return load[key]
+            return load
+
+    async def _handle_exception(self, e: Exception) -> HTTPException:
+        """
+        Handles exceptions and returns a HTTPException with the appropriate status code and detail.
+        """
+        if isinstance(e, ApiException):
+            # handle the TRPC Zod errors from auth-service
+            # Unfortunately, we cannot share the error messages defined in python/crypticorn/common/errors.py with the typescript client
+            message = await self._extract_message(e)
+            if message == "Invalid API key":
+                error = ApiError.INVALID_API_KEY
+            elif message == "API key expired":
+                error = ApiError.EXPIRED_API_KEY
+            elif message == "jwt expired":
+                error = ApiError.EXPIRED_BEARER
+            elif message == "Invalid basic authentication credentials":
+                error = ApiError.INVALID_BASIC_AUTH
+            else:
+                message = "Invalid bearer token"
+                error = (
+                    ApiError.INVALID_BEARER
+                )  # jwt malformed, jwt not active (https://www.npmjs.com/package/jsonwebtoken#errors--codes)
+            return HTTPException(
+                content=ExceptionContent(
+                    error=error,
+                    message=message,
+                ),
+            )
+        elif isinstance(e, HTTPException):
+            return e
+        else:
+            return HTTPException(
+                content=ExceptionContent(
+                    error=ApiError.UNKNOWN_ERROR,
+                    message=str(e),
+                ),
+            )
+
+    async def api_key_auth(
+        self,
+        api_key: Annotated[Union[str, None], Depends(apikey_header)] = None,
+        sec: SecurityScopes = SecurityScopes(),
+    ) -> Verify200Response:
+        """
+        Verifies the API key and checks the scopes.
+        Use this function if you only want to allow access via the API key.
+        This function is used for HTTP connections.
+        """
+        try:
+            return await self.full_auth(
+                bearer=None, api_key=api_key, basic=None, sec=sec
+            )
+        except HTTPException as e:
+            raise HTTPException(
+                content=ExceptionContent(
+                    error=ApiError.from_json(e.detail),
+                    message=e.detail.get("message"),
+                ),
+                headers={AUTHENTICATE_HEADER: APIKEY_AUTH_SCHEME},
+            )
+
+    async def bearer_auth(
+        self,
+        bearer: Annotated[
+            Union[HTTPAuthorizationCredentials, None],
+            Depends(http_bearer),
+        ] = None,
+        sec: SecurityScopes = SecurityScopes(),
+    ) -> Verify200Response:
+        """
+        Verifies the bearer token and checks the scopes.
+        Use this function if you only want to allow access via the bearer token.
+        This function is used for HTTP connections.
+        """
+        try:
+            return await self.full_auth(
+                bearer=bearer, api_key=None, basic=None, sec=sec
+            )
+        except HTTPException as e:
+            raise HTTPException(
+                content=ExceptionContent(
+                    error=ApiError.from_json(e.detail),
+                    message=e.detail.get("message"),
+                ),
+                headers={AUTHENTICATE_HEADER: BEARER_AUTH_SCHEME},
+            )
+
+    async def basic_auth(
+        self,
+        credentials: Annotated[Union[HTTPBasicCredentials, None], Depends(http_basic)],
+    ) -> Verify200Response:
+        """
+        Verifies the basic authentication credentials. This authentication method should just be used for special cases like /admin/metrics, where JWT and API key authentication are not desired or not possible.
+        """
+        try:
+            return await self.full_auth(
+                basic=credentials, bearer=None, api_key=None, sec=None
+            )
+        except HTTPException as e:
+            raise HTTPException(
+                content=ExceptionContent(
+                    error=ApiError.from_json(e.detail),
+                    message=e.detail.get("message"),
+                ),
+                headers={AUTHENTICATE_HEADER: BASIC_AUTH_SCHEME},
+            )
+
+    async def combined_auth(
+        self,
+        bearer: Annotated[
+            Union[HTTPAuthorizationCredentials, None], Depends(http_bearer)
+        ] = None,
+        api_key: Annotated[Union[str, None], Depends(apikey_header)] = None,
+        sec: SecurityScopes = SecurityScopes(),
+    ) -> Verify200Response:
+        """
+        Verifies the bearer token and/or API key and checks the scopes.
+        Returns early on the first successful verification, otherwise tries all available tokens.
+        Use this function if you want to allow access via either the bearer token or the API key.
+        This function is used for HTTP connections.
+        """
+        try:
+            return await self.full_auth(
+                basic=None, bearer=bearer, api_key=api_key, sec=sec
+            )
+        except HTTPException as e:
+            raise HTTPException(
+                content=ExceptionContent(
+                    error=ApiError.from_json(e.detail),
+                    message=e.detail.get("message"),
+                ),
+                headers={
+                    AUTHENTICATE_HEADER: f"{BEARER_AUTH_SCHEME}, {APIKEY_AUTH_SCHEME}"
+                },
+            )
+
+    async def full_auth(
+        self,
+        basic: Annotated[Union[HTTPBasicCredentials, None], Depends(http_basic)] = None,
+        bearer: Annotated[
+            Union[HTTPAuthorizationCredentials, None], Depends(http_bearer)
+        ] = None,
+        api_key: Annotated[Union[str, None], Depends(apikey_header)] = None,
+        sec: SecurityScopes = SecurityScopes(),
+    ) -> Verify200Response:
+        """
+        IMPORTANT: combined_auth is sufficient for most use cases. This function adds basic auth to the mix, which is needed for external services like prometheus, but is not recommended for internal use.
+        Verifies the bearer token, API key and basic authentication credentials and checks the scopes.
+        Returns early on the first successful verification, otherwise tries all available tokens.
+        Use this function if you want to allow access via either the bearer token, the API key or the basic authentication credentials.
+        This function is used for HTTP connections.
+        """
+        tokens = [bearer, api_key, basic]
+        last_error = None
+        for token in tokens:
+            try:
+                if token is None:
+                    continue
+                res = None
+                if isinstance(token, str):
+                    res = await self._verify_api_key(token)
+                elif isinstance(token, HTTPAuthorizationCredentials):
+                    res = await self._verify_bearer(token)
+                elif isinstance(token, HTTPBasicCredentials):
+                    res = await self._verify_basic(token)
+                if res is None:
+                    continue
+                if sec:
+                    await self._validate_scopes(sec.scopes, res.scopes)
+                return res
+
+            except Exception as e:
+                last_error = await self._handle_exception(e)
+                continue
+
+        if last_error:
+            raise last_error
+        else:
+            raise HTTPException(
+                content=ExceptionContent(
+                    error=ApiError.NO_CREDENTIALS,
+                    message="No credentials provided. Check the WWW-Authenticate header for the available authentication methods.",
+                ),
+                headers={
+                    AUTHENTICATE_HEADER: f"{BEARER_AUTH_SCHEME}, {APIKEY_AUTH_SCHEME}, {BASIC_AUTH_SCHEME}"
+                },
+            )
+
+    async def ws_api_key_auth(
+        self,
+        api_key: Annotated[Union[str, None], Query()] = None,
+        sec: SecurityScopes = SecurityScopes(),
+    ) -> Verify200Response:
+        """
+        Verifies the API key and checks the scopes.
+        Use this function if you only want to allow access via the API key.
+        This function is used for WebSocket connections.
+        """
+        return await self.api_key_auth(api_key=api_key, sec=sec)
+
+    async def ws_bearer_auth(
+        self,
+        bearer: Annotated[Union[str, None], Query()] = None,
+        sec: SecurityScopes = SecurityScopes(),
+    ) -> Verify200Response:
+        """
+        Verifies the bearer token and checks the scopes.
+        Use this function if you only want to allow access via the bearer token.
+        This function is used for WebSocket connections.
+        """
+        credentials = (
+            HTTPAuthorizationCredentials(scheme="Bearer", credentials=bearer)
+            if bearer
+            else None
+        )
+        return await self.bearer_auth(bearer=credentials, sec=sec)
+
+    async def ws_combined_auth(
+        self,
+        bearer: Annotated[Union[str, None], Query()] = None,
+        api_key: Annotated[Union[str, None], Query()] = None,
+        sec: SecurityScopes = SecurityScopes(),
+    ) -> Verify200Response:
+        """
+        Verifies the bearer token and/or API key and checks the scopes.
+        Use this function if you want to allow access via either the bearer token or the API key.
+        This function is used for WebSocket connections.
+        """
+        credentials = (
+            HTTPAuthorizationCredentials(scheme="Bearer", credentials=bearer)
+            if bearer
+            else None
+        )
+        return await self.combined_auth(bearer=credentials, api_key=api_key, sec=sec)

crypticorn_utils/cli/__init__.py

@@ -0,0 +1,4 @@
+from crypticorn.cli.init import init_group
+from crypticorn.cli.version import version
+
+__all__ = ["init_group", "version"]

crypticorn_utils/cli/__main__.py

@@ -0,0 +1,17 @@
+# crypticorn/cli.py
+
+import click
+from crypticorn.cli import init_group, version
+
+
+@click.group()
+def cli():
+    """🧙 Crypticorn CLI — magic for our microservices."""
+    pass
+
+
+cli.add_command(init_group, name="init")
+cli.add_command(version, name="version")
+
+if __name__ == "__main__":
+    cli()

crypticorn_utils/cli/init.py

@@ -0,0 +1,127 @@
+import click
+from pathlib import Path
+import subprocess
+import importlib.resources
+import crypticorn.cli.templates as templates
+
+
+def get_git_root() -> Path:
+    """Get the root directory of the git repository."""
+    try:
+        return Path(
+            subprocess.check_output(
+                ["git", "rev-parse", "--show-toplevel"], text=True
+            ).strip()
+        )
+    except Exception:
+        return Path.cwd()
+
+
+def copy_template(template_name: str, target_path: Path):
+    """Copy a template file to the target path."""
+    with importlib.resources.files(templates).joinpath(template_name).open(
+        "r"
+    ) as template_file:
+        content = template_file.read()
+
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+    with target_path.open("w") as f:
+        f.write(content)
+
+    click.secho(f"✅ Created: {target_path}", fg="green")
+
+
+def check_file_exists(path: Path, force: bool):
+    if path.exists() and not force:
+        click.secho("File already exists, use --force / -f to overwrite", fg="red")
+        return False
+    return True
+
+
+@click.group()
+def init_group():
+    """Initialize files like CI configs, linters, etc."""
+    pass
+
+
+@init_group.command("ruff")
+@click.option("-f", "--force", is_flag=True, help="Force overwrite the ruff.yml")
+def init_ruff(force):
+    """Add .github/workflows/ruff.yml"""
+    root = get_git_root()
+    target = root / ".github/workflows/ruff.yml"
+    if target.exists() and not force:
+        click.secho("File already exists, use --force / -f to overwrite", fg="red")
+        return
+    copy_template("ruff.yml", target)
+
+
+@init_group.command("docker")
+@click.option(
+    "-o", "--output", type=click.Path(), help="Custom output path for the Dockerfile"
+)
+@click.option("-f", "--force", is_flag=True, help="Force overwrite the Dockerfile")
+def init_docker(output, force):
+    """Add Dockerfile"""
+    root = get_git_root()
+    if output and Path(output).is_file():
+        click.secho("Output path is a file, please provide a directory path", fg="red")
+        return
+    target = (Path(output) if output else root) / "Dockerfile"
+    if not check_file_exists(target, force):
+        return
+    copy_template("Dockerfile", target)
+    click.secho("Make sure to update the Dockerfile", fg="yellow")
+
+
+@init_group.command("auth")
+@click.option(
+    "-o", "--output", type=click.Path(), help="Custom output path for the auth handler"
+)
+@click.option("-f", "--force", is_flag=True, help="Force overwrite the auth handler")
+def init_auth(output, force):
+    """Add auth.py with auth handler. Everything you need to start using the auth service."""
+    root = get_git_root()
+    if output and Path(output).is_file():
+        click.secho("Output path is a file, please provide a directory path", fg="red")
+        return
+    target = (Path(output) if output else root) / "auth.py"
+    if not check_file_exists(target, force):
+        return
+    copy_template("auth.py", target)
+    click.secho(
+        """
+    Make sure to update the .env and .env.example files with:
+        IS_DOCKER=0
+        API_ENV=local
+    and the docker-compose.yml file with:
+        environment:
+            - IS_DOCKER=1
+    and the .github/workflows/main.yaml file with:
+        env:
+            API_ENV: ${{ github.ref == 'refs/heads/main' && 'prod' || 'dev' }}
+    """,
+        fg="yellow",
+    )
+
+
+@init_group.command("dependabot")
+@click.option("-f", "--force", is_flag=True, help="Force overwrite the dependabot.yml")
+def init_dependabot(force):
+    """Add dependabot.yml"""
+    root = get_git_root()
+    target = root / ".github/dependabot.yml"
+    if not check_file_exists(target, force):
+        return
+    copy_template("dependabot.yml", target)
+
+
+@init_group.command("merge-env")
+@click.option("-f", "--force", is_flag=True, help="Force overwrite the .env file")
+def init_merge_env(force):
+    """Add script to merge environment and file variables into .env"""
+    root = get_git_root()
+    target = root / "scripts/merge-env.sh"
+    if not check_file_exists(target, force):
+        return
+    copy_template("merge-env.sh", target)

crypticorn_utils/cli/templates/auth.py

@@ -0,0 +1,33 @@
+from crypticorn.common import (
+    AuthHandler as AuthHandler,
+    Scope as Scope,
+    Verify200Response as Verify200Response,
+    BaseUrl as BaseUrl,
+    ApiEnv as ApiEnv,
+)
+from fastapi import Security as Security
+import os
+import dotenv
+import logging
+
+dotenv.load_dotenv()
+
+logger = logging.getLogger(__name__)
+
+DOCKER_ENV = os.getenv("IS_DOCKER", "0")
+API_ENV = os.getenv("API_ENV")
+
+if not API_ENV:
+    raise ValueError(
+        "API_ENV is not set. Please set it to 'prod', 'dev' or 'local' in .env (of type ApiEnv)."
+    )
+
+if DOCKER_ENV == "0":
+    logger.info(f"Using {API_ENV} environment")
+    base_url = BaseUrl.from_env(ApiEnv(API_ENV))
+else:
+    base_url = BaseUrl.DOCKER
+    logger.info("Using docker environment")
+
+auth_handler = AuthHandler(base_url=base_url)
+logger.info(f"Auth URL: {auth_handler.client.config.host}")

crypticorn_utils/cli/version.py

@@ -0,0 +1,8 @@
+import importlib.metadata
+import click
+
+
+@click.command("version")
+def version():
+    """Print the version of the crypticorn package"""
+    click.echo(importlib.metadata.distribution("crypticorn").version)

crypticorn_utils/decorators.py

@@ -0,0 +1,38 @@
+from copy import deepcopy
+from typing import Any, Optional, Tuple, Type
+
+from pydantic import BaseModel, create_model
+from pydantic.fields import FieldInfo
+
+
+def partial_model(model: Type[BaseModel]) -> Type[BaseModel]:
+    """Marks all fields of a model as optional. Useful for updating models.
+    Inherits all fields, docstrings, and the model name.
+
+    >>> @partial_model
+    >>> class Model(BaseModel):
+    >>>     i: int
+    >>>     f: float
+    >>>     s: str
+
+    >>> Model(i=1)
+    """
+
+    def make_field_optional(
+        field: FieldInfo, default: Any = None
+    ) -> Tuple[Any, FieldInfo]:
+        new = deepcopy(field)
+        new.default = default
+        new.annotation = Optional[field.annotation]  # type: ignore
+        return new.annotation, new
+
+    return create_model(
+        model.__name__,
+        __base__=model,
+        __module__=model.__module__,
+        __doc__=model.__doc__,
+        **{
+            field_name: make_field_optional(field_info)
+            for field_name, field_info in model.model_fields.items()
+        },
+    )