api-service-handler 0.1.6__py3-none-any.whl

api_service_handler/config.py

@@ -0,0 +1,177 @@
+"""Configuration module for the API Service Handler.
+
+Provides :class:`ASHConfig` — a dataclass holding every tuneable knob — and
+the helper :func:`get_config_from_env` that builds an ``ASHConfig`` purely
+from environment variables prefixed with ``ASH_``.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+# ---------------------------------------------------------------------------
+# Supported literal values (kept as module-level constants for validation)
+# ---------------------------------------------------------------------------
+
+VALID_STORAGE_BACKENDS = frozenset({"memory", "sqlite", "mongodb", "postgresql"})
+VALID_ROTATION_STRATEGIES = frozenset({"round_robin", "least_used", "random", "weighted"})
+
+
+# ---------------------------------------------------------------------------
+# Core configuration dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ASHConfig:
+    """Configuration for the API Service Handler.
+
+    Attributes
+    ----------
+    storage_backend:
+        Which persistence layer to use.  One of ``memory``, ``sqlite``,
+        ``mongodb``, or ``postgresql``.  Falls back to the
+        ``ASH_STORAGE_BACKEND`` env var when set to ``"memory"`` (the default).
+    connection_string:
+        Database connection URI.  Falls back to ``ASH_CONNECTION_STRING``.
+    shared_secret:
+        Passphrase used to derive an AES-256-GCM key for encrypting stored API
+        keys.  Falls back to ``ASH_SHARED_SECRET``.
+    encrypt_keys:
+        Whether API key values should be encrypted at rest.
+    rotation_strategy:
+        Algorithm used when picking the next key.  One of ``round_robin``,
+        ``least_used``, ``random``, or ``weighted``.
+    auto_reset_counters:
+        Automatically reset daily / monthly usage counters on access when the
+        current period has elapsed.
+    soft_delete:
+        When ``True``, deleting a key sets its status to ``REVOKED`` rather
+        than removing the record.
+    default_daily_limit:
+        Default daily request cap applied to newly created keys.
+    default_monthly_limit:
+        Default monthly request cap applied to newly created keys.
+    default_max_concurrent:
+        Default maximum number of concurrent in-flight requests per key.
+    metadata_indexes:
+        List of metadata keys to create compound indexes for (e.g. ['client_id']).
+    """
+
+    # Storage
+    storage_backend: str = "memory"
+    connection_string: str = ""
+
+    # Encryption
+    shared_secret: str = ""
+    encrypt_keys: bool = True
+
+    # Rotation
+    rotation_strategy: str = "round_robin"
+
+    # Behaviour
+    auto_reset_counters: bool = True
+    soft_delete: bool = True
+    default_daily_limit: Optional[int] = None
+    default_monthly_limit: Optional[int] = None
+    default_max_concurrent: Optional[int] = None
+    metadata_indexes: list[str] = field(default_factory=list)
+
+    # ------------------------------------------------------------------
+    # Post-init: resolve env-var fallbacks & validate
+    # ------------------------------------------------------------------
+
+    def __post_init__(self) -> None:
+        # Env-var fallbacks
+        if not self.shared_secret:
+            self.shared_secret = os.environ.get("ASH_SHARED_SECRET", "")
+        if not self.connection_string:
+            self.connection_string = os.environ.get("ASH_CONNECTION_STRING", "")
+        if self.storage_backend == "memory":
+            self.storage_backend = os.environ.get("ASH_STORAGE_BACKEND", "memory")
+
+        # Normalise & validate
+        self.storage_backend = self.storage_backend.lower().strip()
+        self.rotation_strategy = self.rotation_strategy.lower().strip()
+
+        if self.storage_backend not in VALID_STORAGE_BACKENDS:
+            raise ValueError(
+                f"Invalid storage_backend {self.storage_backend!r}. "
+                f"Choose from {sorted(VALID_STORAGE_BACKENDS)}."
+            )
+        if self.rotation_strategy not in VALID_ROTATION_STRATEGIES:
+            raise ValueError(
+                f"Invalid rotation_strategy {self.rotation_strategy!r}. "
+                f"Choose from {sorted(VALID_ROTATION_STRATEGIES)}."
+            )
+
+        # Limit fields must be non-negative when set
+        for attr in ("default_daily_limit", "default_monthly_limit", "default_max_concurrent"):
+            value = getattr(self, attr)
+            if value is not None and value < 0:
+                raise ValueError(f"{attr} must be a non-negative integer, got {value}.")
+
+
+# ---------------------------------------------------------------------------
+# Factory – build config entirely from environment variables
+# ---------------------------------------------------------------------------
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    """Read an env var as a boolean (``true/1/yes`` → True)."""
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"true", "1", "yes"}
+
+
+def _env_optional_int(name: str) -> Optional[int]:
+    """Read an env var as an optional integer."""
+    raw = os.environ.get(name)
+    if raw is None or raw.strip() == "":
+        return None
+    try:
+        return int(raw)
+    except ValueError:
+        raise ValueError(
+            f"Environment variable {name} must be an integer, got {raw!r}."
+        ) from None
+
+
+def get_config_from_env() -> ASHConfig:
+    """Build an :class:`ASHConfig` entirely from ``ASH_*`` environment variables.
+
+    Recognised variables
+    --------------------
+    * ``ASH_STORAGE_BACKEND``   – storage backend name
+    * ``ASH_CONNECTION_STRING`` – database connection URI
+    * ``ASH_SHARED_SECRET``     – encryption passphrase
+    * ``ASH_ENCRYPT_KEYS``      – ``true`` / ``false``
+    * ``ASH_ROTATION_STRATEGY`` – rotation algorithm name
+    * ``ASH_AUTO_RESET_COUNTERS`` – ``true`` / ``false``
+    * ``ASH_SOFT_DELETE``       – ``true`` / ``false``
+    * ``ASH_DEFAULT_DAILY_LIMIT``
+    * ``ASH_DEFAULT_MONTHLY_LIMIT``
+    * ``ASH_DEFAULT_MAX_CONCURRENT``
+
+    Returns
+    -------
+    ASHConfig
+        A fully populated configuration instance.
+    """
+    return ASHConfig(
+        storage_backend=os.environ.get("ASH_STORAGE_BACKEND", "memory"),
+        connection_string=os.environ.get("ASH_CONNECTION_STRING", ""),
+        shared_secret=os.environ.get("ASH_SHARED_SECRET", ""),
+        encrypt_keys=_env_bool("ASH_ENCRYPT_KEYS", default=True),
+        rotation_strategy=os.environ.get("ASH_ROTATION_STRATEGY", "round_robin"),
+        auto_reset_counters=_env_bool("ASH_AUTO_RESET_COUNTERS", default=True),
+        soft_delete=_env_bool("ASH_SOFT_DELETE", default=True),
+        default_daily_limit=_env_optional_int("ASH_DEFAULT_DAILY_LIMIT"),
+        default_monthly_limit=_env_optional_int("ASH_DEFAULT_MONTHLY_LIMIT"),
+        default_max_concurrent=_env_optional_int("ASH_DEFAULT_MAX_CONCURRENT"),
+        metadata_indexes=[x.strip() for x in os.environ.get("ASH_METADATA_INDEXES", "").split(",")] if os.environ.get("ASH_METADATA_INDEXES") else [],
+    )

api_service_handler/encryption.py

@@ -0,0 +1,238 @@
+"""AES-256-GCM encryption utilities for the API Service Handler.
+
+API key values are encrypted at rest using a symmetric key derived from a
+shared secret.  The encrypted representation is a dot-separated triple of
+Base-64 segments::
+
+    <iv_b64>.<auth_tag_b64>.<ciphertext_b64>
+
+This format is deterministic enough to be detected by :func:`is_encrypted`
+yet safe against accidental double-encryption because plain API keys never
+contain two dots separating valid Base-64 segments.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import re
+from typing import Any
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from .exceptions import EncryptionError
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_IV_BYTES: int = 12          # 96-bit nonce recommended for AES-GCM
+_TAG_BYTES: int = 16         # 128-bit authentication tag
+_KEY_BYTES: int = 32         # 256-bit key (AES-256)
+
+# Loose regex for a Base-64 segment (standard or URL-safe, with optional padding)
+_B64_SEGMENT = r"[A-Za-z0-9+/\-_]+=*"
+_ENCRYPTED_PATTERN: re.Pattern[str] = re.compile(
+    rf"^{_B64_SEGMENT}\.{_B64_SEGMENT}\.{_B64_SEGMENT}$"
+)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _derive_key(shared_secret: str) -> bytes:
+    """Derive a 256-bit AES key from *shared_secret* via SHA-256.
+
+    Parameters
+    ----------
+    shared_secret:
+        The passphrase to derive the key from.  Must be non-empty.
+
+    Returns
+    -------
+    bytes
+        A 32-byte key suitable for ``AESGCM``.
+
+    Raises
+    ------
+    ValueError
+        If *shared_secret* is empty.
+    """
+    if not shared_secret:
+        raise ValueError("shared_secret must not be empty for encryption/decryption.")
+    return hashlib.sha256(shared_secret.encode("utf-8")).digest()
+
+
+def _b64_encode(data: bytes) -> str:
+    """Return standard Base-64 encoding of *data* as a UTF-8 string."""
+    return base64.b64encode(data).decode("utf-8")
+
+
+def _b64_decode(data: str) -> bytes:
+    """Decode a standard Base-64 string to bytes."""
+    return base64.b64decode(data)
+
+
+# ---------------------------------------------------------------------------
+# Public API – encrypt / decrypt
+# ---------------------------------------------------------------------------
+
+
+def encrypt_api_key(plain_text: str, shared_secret: str) -> str:
+    """Encrypt *plain_text* with AES-256-GCM using a key derived from *shared_secret*.
+
+    Parameters
+    ----------
+    plain_text:
+        The raw API key (or any secret) to encrypt.
+    shared_secret:
+        Passphrase used to derive the encryption key.
+
+    Returns
+    -------
+    str
+        The encrypted payload formatted as ``iv_b64.auth_tag_b64.ciphertext_b64``.
+
+    Raises
+    ------
+    ValueError
+        If *shared_secret* is empty.
+    """
+    key = _derive_key(shared_secret)
+    iv = os.urandom(_IV_BYTES)
+
+    aesgcm = AESGCM(key)
+    # AESGCM.encrypt returns ciphertext || tag (tag is the last 16 bytes)
+    ciphertext_with_tag: bytes = aesgcm.encrypt(iv, plain_text.encode("utf-8"), None)
+
+    # Split into ciphertext body + authentication tag
+    ciphertext = ciphertext_with_tag[:-_TAG_BYTES]
+    auth_tag = ciphertext_with_tag[-_TAG_BYTES:]
+
+    return f"{_b64_encode(iv)}.{_b64_encode(auth_tag)}.{_b64_encode(ciphertext)}"
+
+
+def decrypt_api_key(encrypted_str: str, shared_secret: str) -> str:
+    """Decrypt an encrypted payload produced by :func:`encrypt_api_key`.
+
+    Values that do not look like an encrypted triple (non-string, or fewer/more
+    than three dot-separated segments) are returned unchanged, so plain-text
+    keys pass through safely.
+
+    Values that *do* look encrypted but fail decryption (e.g. wrong secret,
+    tampered ciphertext) raise :class:`EncryptionError` — callers should not
+    silently swallow decryption failures, as they indicate a misconfiguration
+    or data integrity problem.
+
+    Parameters
+    ----------
+    encrypted_str:
+        The dot-separated encrypted payload, or a plain-text fallback.
+    shared_secret:
+        Passphrase used to derive the decryption key.
+
+    Returns
+    -------
+    str
+        The decrypted plain text.
+
+    Raises
+    ------
+    EncryptionError
+        If the value looks encrypted but decryption fails.
+    """
+    # Guard: not a string → return as-is
+    if not isinstance(encrypted_str, str):
+        return encrypted_str  # type: ignore[return-value]
+
+    # Guard: must be exactly three dot-separated segments to look encrypted
+    parts = encrypted_str.split(".")
+    if len(parts) != 3:
+        return encrypted_str
+
+    # Value matches the encrypted format — decrypt and raise on any failure.
+    try:
+        iv = _b64_decode(parts[0])
+        auth_tag = _b64_decode(parts[1])
+        ciphertext = _b64_decode(parts[2])
+
+        key = _derive_key(shared_secret)
+        aesgcm = AESGCM(key)
+
+        # Reconstruct the format AESGCM expects: ciphertext || tag
+        ciphertext_with_tag = ciphertext + auth_tag
+        decrypted_bytes: bytes = aesgcm.decrypt(iv, ciphertext_with_tag, None)
+
+        # Try to deserialise as JSON first (handles stored dicts / lists)
+        try:
+            result: Any = json.loads(decrypted_bytes)
+            return str(result) if not isinstance(result, str) else result
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            return decrypted_bytes.decode("utf-8")
+
+    except EncryptionError:
+        raise
+    except Exception as exc:
+        raise EncryptionError(
+            f"Decryption failed — verify shared_secret matches the one used for encryption: {exc}"
+        ) from exc
+
+
+# ---------------------------------------------------------------------------
+# Public API – inspection helpers
+# ---------------------------------------------------------------------------
+
+
+def is_encrypted(value: str) -> bool:
+    """Check whether *value* looks like an encrypted payload.
+
+    This is a *heuristic* based on the ``iv.tag.ciphertext`` format — three
+    dot-separated Base-64 segments — and does **not** attempt actual
+    decryption.
+
+    Parameters
+    ----------
+    value:
+        The string to inspect.
+
+    Returns
+    -------
+    bool
+        ``True`` if *value* matches the encrypted format.
+    """
+    if not isinstance(value, str):
+        return False
+    return bool(_ENCRYPTED_PATTERN.match(value))
+
+
+def mask_key(key_value: str, show: int = 8) -> str:
+    """Return a masked representation of *key_value* suitable for display.
+
+    Parameters
+    ----------
+    key_value:
+        The API key (plain text or encrypted) to mask.
+    show:
+        Number of leading characters to reveal.  Defaults to ``8``.
+
+    Returns
+    -------
+    str
+        The first *show* characters followed by ``***``, or the full value
+        if it is shorter than or equal to *show* characters.
+
+    Examples
+    --------
+    >>> mask_key("sk-abc123def456ghi789")
+    'sk-abc12***'
+    >>> mask_key("short")
+    'short'
+    """
+    if not isinstance(key_value, str) or len(key_value) <= show:
+        return key_value
+    return key_value[:show] + "***"

api_service_handler/enums.py

@@ -0,0 +1,217 @@
+"""Enumerations for the api-service-handler library.
+
+Defines all enum types used across the library including API providers,
+key statuses, storage backends, rotation strategies, and environments.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class Provider(str, Enum):
+    """Supported API service providers.
+
+    Covers a wide range of provider categories including AI/LLM, speech/audio,
+    cloud infrastructure, communication, payments, search/data, auth,
+    storage/CDN, dev tools, messaging, productivity, monitoring, and maps.
+
+    Use ``Provider.from_string()`` for case-insensitive lookup with automatic
+    fallback to ``CUSTOM`` for unrecognised values.
+    """
+
+    # --- AI / LLM ---
+    OPENAI = "openai"
+    ANTHROPIC = "anthropic"
+    GOOGLE_GEMINI = "google_gemini"
+    GOOGLE_VERTEX = "google_vertex"
+    MISTRAL = "mistral"
+    COHERE = "cohere"
+    HUGGINGFACE = "huggingface"
+    REPLICATE = "replicate"
+    TOGETHER_AI = "together_ai"
+    GROQ = "groq"
+    FIREWORKS = "fireworks"
+    DEEPSEEK = "deepseek"
+    XAI = "xai"
+    PERPLEXITY = "perplexity"
+    OPENROUTER = "openrouter"
+    LEMOFOX = "lemofox"
+
+    # --- Speech / Audio ---
+    DEEPGRAM = "deepgram"
+    ELEVEN_LABS = "eleven_labs"
+    ASSEMBLY_AI = "assembly_ai"
+    WHISPER = "whisper"
+
+    # --- Cloud ---
+    AWS = "aws"
+    AZURE = "azure"
+    GCP = "gcp"
+    CLOUDFLARE = "cloudflare"
+    DIGITAL_OCEAN = "digital_ocean"
+    VERCEL = "vercel"
+
+    # --- Communication ---
+    TWILIO = "twilio"
+    SENDGRID = "sendgrid"
+    MAILGUN = "mailgun"
+    RESEND = "resend"
+    POSTMARK = "postmark"
+
+    # --- Payments ---
+    STRIPE = "stripe"
+    RAZORPAY = "razorpay"
+    PAYPAL = "paypal"
+    LEMONSQUEEZY = "lemonsqueezy"
+
+    # --- Search / Data ---
+    SERP_API = "serp_api"
+    BING_SEARCH = "bing_search"
+    ALGOLIA = "algolia"
+    PINECONE = "pinecone"
+    WEAVIATE = "weaviate"
+
+    # --- Auth ---
+    AUTH0 = "auth0"
+    CLERK = "clerk"
+    FIREBASE = "firebase"
+    SUPABASE_AUTH = "supabase_auth"
+
+    # --- Storage / CDN ---
+    CLOUDINARY = "cloudinary"
+    S3 = "s3"
+    SUPABASE = "supabase"
+    R2 = "r2"
+    UPLOADTHING = "uploadthing"
+
+    # --- Dev Tools ---
+    GITHUB = "github"
+    GITLAB = "gitlab"
+    BITBUCKET = "bitbucket"
+    LINEAR = "linear"
+    JIRA = "jira"
+
+    # --- Messaging ---
+    SLACK = "slack"
+    DISCORD = "discord"
+    TELEGRAM = "telegram"
+    WHATSAPP = "whatsapp"
+
+    # --- Productivity ---
+    NOTION = "notion"
+    AIRTABLE = "airtable"
+    ZAPIER = "zapier"
+    MAKE = "make"
+
+    # --- Monitoring ---
+    SENTRY = "sentry"
+    DATADOG = "datadog"
+    NEW_RELIC = "new_relic"
+    LOGFLARE = "logflare"
+
+    # --- Maps ---
+    GOOGLE_MAPS = "google_maps"
+    MAPBOX = "mapbox"
+    HERE = "here"
+
+    # --- Catch-all ---
+    CUSTOM = "custom"
+
+    @classmethod
+    def from_string(cls, value: str) -> Provider:
+        """Look up a provider by name (case-insensitive).
+
+        Attempts to match *value* against both the enum member **name**
+        (e.g. ``"OPENAI"``) and the enum member **value** (e.g. ``"openai"``).
+        Returns :attr:`Provider.CUSTOM` when no match is found.
+
+        Args:
+            value: The provider string to look up.
+
+        Returns:
+            The matching ``Provider`` member, or ``Provider.CUSTOM``.
+
+        Examples:
+            >>> Provider.from_string("openai")
+            <Provider.OPENAI: 'openai'>
+            >>> Provider.from_string("ANTHROPIC")
+            <Provider.ANTHROPIC: 'anthropic'>
+            >>> Provider.from_string("unknown_service")
+            <Provider.CUSTOM: 'custom'>
+        """
+        normalised = value.strip().upper()
+
+        # Fast path: match by member name (e.g. "OPENAI", "GOOGLE_GEMINI").
+        try:
+            return cls[normalised]
+        except KeyError:
+            pass
+
+        # Slower path: match by member value (lowercase form).
+        lower = value.strip().lower()
+        for member in cls:
+            if member.value == lower:
+                return member
+
+        return cls.CUSTOM
+
+
+class KeyStatus(str, Enum):
+    """Status of an API key in the key pool."""
+
+    ACTIVE = "active"
+    """Key is available for use."""
+
+    INACTIVE = "inactive"
+    """Key has been manually disabled."""
+
+    RATE_LIMITED = "rate_limited"
+    """Key has hit a rate limit and is temporarily unavailable."""
+
+    EXPIRED = "expired"
+    """Key has passed its expiration date."""
+
+    REVOKED = "revoked"
+    """Key has been permanently revoked by the provider or admin."""
+
+
+class StorageBackend(str, Enum):
+    """Supported storage backends for persisting key data."""
+
+    MEMORY = "memory"
+    """In-process dictionary — useful for testing and single-process apps."""
+
+    SQLITE = "sqlite"
+    """SQLite file-based database."""
+
+    MONGODB = "mongodb"
+    """MongoDB document store."""
+
+    POSTGRESQL = "postgresql"
+    """PostgreSQL relational database."""
+
+
+class RotationStrategy(str, Enum):
+    """Strategy for selecting the next API key from the pool."""
+
+    ROUND_ROBIN = "round_robin"
+    """Cycle through keys in order."""
+
+    LEAST_USED = "least_used"
+    """Pick the key with the fewest total uses."""
+
+    RANDOM = "random"
+    """Pick a key at random."""
+
+    WEIGHTED = "weighted"
+    """Pick a key based on assigned weights / priorities."""
+
+
+class Environment(str, Enum):
+    """Application deployment environment."""
+
+    PRODUCTION = "production"
+    STAGING = "staging"
+    DEVELOPMENT = "development"
+    TESTING = "testing"