alea-q 0.2.0__py3-none-any.whl

alea_q/__init__.py

@@ -0,0 +1,83 @@
+# alea_q/__init__.py
+"""
+alea-q — SDK Python pour l'API ALEA-Q / CERTROPI.
+
+Génération d'entiers aléatoires certifiés Device-Independent
+depuis des QPU réels (IBM, Quandela, Pasqal).
+
+Usage rapide :
+    from alea_q import AleaQClient
+
+    client = AleaQClient(api_key="sk_plat_xxx")
+    result = client.platinum.generate(n_bits=256)
+    print(result.as_hex())
+
+Documentation : https://docs.alea-q.com
+"""
+from alea_q.client import AleaQClient, AsyncAleaQClient
+from alea_q.exceptions import (
+    AleaQError,
+    AuthenticationError,
+    BackendUnavailable,
+    CertificateError,
+    InsufficientBalance,
+    PermissionError,
+    QuotaExceeded,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from alea_q.models import (
+    AccountInfo,
+    BatchResult,
+    GenerateResult,
+    HealthStatus,
+    MLKemEncapsResult,
+    MLKemKeyPair,
+    PoolStatus,
+    QuotaInfo,
+    SLHDSAKeyPair,
+    SLHDSASignResult,
+    SLHDSAVerifyResult,
+    UsageStats,
+)
+from alea_q.pqc_crypto import DecapsulationError, mlkem_decaps
+from alea_q.verify import verify_certificate, verify_certificate_dict
+
+__version__ = "0.2.0"
+__all__ = [
+    # Clients
+    "AleaQClient",
+    "AsyncAleaQClient",
+    # Modèles
+    "GenerateResult",
+    "BatchResult",
+    "PoolStatus",
+    "HealthStatus",
+    "AccountInfo",
+    "QuotaInfo",
+    "UsageStats",
+    "MLKemKeyPair",
+    "MLKemEncapsResult",
+    "SLHDSAKeyPair",
+    "SLHDSASignResult",
+    "SLHDSAVerifyResult",
+    # Exceptions
+    "AleaQError",
+    "AuthenticationError",
+    "PermissionError",
+    "QuotaExceeded",
+    "BackendUnavailable",
+    "RateLimitError",
+    "ServerError",
+    "CertificateError",
+    "ValidationError",
+    "InsufficientBalance",
+    # Vérification certificat
+    "verify_certificate",
+    "verify_certificate_dict",
+    # Décapsulation ML-KEM locale (#438)
+    "mlkem_decaps",
+    "DecapsulationError",
+]
+

alea_q/_http.py

@@ -0,0 +1,220 @@
+# alea_q/_http.py
+"""
+Couche HTTP du SDK alea-q — gestion centralisée des requêtes et des erreurs.
+
+Utilisé par AleaQClient (sync) et AsyncAleaQClient (async).
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+
+import httpx
+
+from alea_q.exceptions import (
+    AleaQError,
+    AuthenticationError,
+    BackendUnavailable,
+    InsufficientBalance,
+    PermissionError,
+    QuotaExceeded,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+# Version du SDK — mise à jour à chaque release
+SDK_VERSION = "0.2.0"
+
+DEFAULT_BASE_URL = os.getenv("ALEA_Q_BASE_URL", "https://api.alea-q.com")
+DEFAULT_TIMEOUT  = float(os.getenv("ALEA_Q_TIMEOUT", "60"))
+DEFAULT_RETRIES  = int(os.getenv("ALEA_Q_MAX_RETRIES", "2"))
+
+
+def _resolve_api_key(api_key: Optional[str]) -> str:
+    """
+    Résout la clé API depuis le paramètre ou la variable d'environnement.
+    Lève ValidationError si aucune clé n'est disponible.
+    """
+    key = api_key or os.getenv("ALEA_Q_API_KEY", "")
+    if not key:
+        raise ValidationError(
+            "Clé API manquante. Passez api_key= au constructeur ou "
+            "définissez la variable d'environnement ALEA_Q_API_KEY."
+        )
+    return key
+
+
+# Préfixes réels des clés API (api/auth.py côté serveur) — sk_ivor_, pas
+# sk_ivory_ (#116, faute de frappe corrigée dans la doc du SDK au passage).
+_TIER_PREFIXES = {
+    "sk_ivor_": "ivory",
+    "sk_silv_": "silver",
+    "sk_plat_": "platinum",
+}
+
+
+def _detect_tier(api_key: str) -> Optional[str]:
+    """
+    Détecte le tier ('ivory' | 'silver' | 'platinum') depuis le préfixe
+    de la clé API (#116) — best-effort, informationnel.
+
+    Retourne None si le préfixe n'est pas reconnu, plutôt que de lever :
+    la validation qui compte réellement se fait côté serveur (401 sur
+    une clé invalide, via _raise_for_status ci-dessous) — bloquer la
+    construction du client sur un préfixe inconnu casserait des clés
+    de test/staging légitimes qui ne suivent pas cette convention,
+    pour une garantie que le serveur apporte de toute façon.
+    """
+    for prefix, tier in _TIER_PREFIXES.items():
+        if api_key.startswith(prefix):
+            return tier
+    return None
+
+
+def _build_headers(api_key: str) -> Dict[str, str]:
+    return {
+        "X-API-Key":    api_key,
+        "User-Agent":   f"alea-q-python/{SDK_VERSION}",
+        "Accept":       "application/json",
+        "Content-Type": "application/json",
+    }
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """
+    Convertit les erreurs HTTP en exceptions typées alea-q.
+    Extrait request_id et retry_after si disponibles.
+    """
+    if response.status_code < 400:
+        return
+
+    request_id  = response.headers.get("x-request-id")
+    retry_after_raw = response.headers.get("retry-after")
+    retry_after = int(retry_after_raw) if retry_after_raw and retry_after_raw.isdigit() else None
+
+    try:
+        body = response.json()
+        detail = body.get("detail", str(response.status_code))
+        reason = body.get("reason")
+    except Exception:
+        detail = response.text or str(response.status_code)
+        reason = None
+
+    sc = response.status_code
+
+    if sc == 401:
+        raise AuthenticationError(detail, status_code=sc, request_id=request_id)
+    if sc == 403:
+        raise PermissionError(detail, status_code=sc, request_id=request_id)
+    if sc == 422:
+        raise ValidationError(detail, status_code=sc, request_id=request_id)
+    if sc == 402:
+        raise InsufficientBalance(detail, status_code=sc, request_id=request_id)
+    if sc == 429:
+        # Distinguer rate-limit (Caddy) et quota (applicatif)
+        if reason or "quota" in detail.lower():
+            raise QuotaExceeded(
+                detail, retry_after=retry_after,
+                status_code=sc, request_id=request_id,
+            )
+        raise RateLimitError(
+            detail, retry_after=retry_after,
+            status_code=sc, request_id=request_id,
+        )
+    if sc == 503:
+        raise BackendUnavailable(
+            detail, retry_after=retry_after, reason=reason,
+            status_code=sc, request_id=request_id,
+        )
+    if sc >= 500:
+        raise ServerError(detail, status_code=sc, request_id=request_id)
+
+    raise AleaQError(detail, status_code=sc, request_id=request_id)
+
+
+# ── Client synchrone ──────────────────────────────────────────
+
+class HttpClient:
+    """Client HTTP synchrone (httpx)."""
+
+    def __init__(
+        self,
+        api_key:  str,
+        base_url: str,
+        timeout:  float,
+    ) -> None:
+        self._headers = _build_headers(api_key)
+        self._client  = httpx.Client(
+            base_url = base_url,
+            headers  = self._headers,
+            timeout  = timeout,
+        )
+
+    def post(self, path: str, json: Dict[str, Any]) -> Dict[str, Any]:
+        response = self._client.post(path, json=json)
+        _raise_for_status(response)
+        return response.json()
+
+    def get(self, path: str, params: Optional[Dict] = None) -> Dict[str, Any]:
+        response = self._client.get(path, params=params)
+        _raise_for_status(response)
+        return response.json()
+
+    def get_bytes(self, path: str) -> bytes:
+        response = self._client.get(path)
+        _raise_for_status(response)
+        return response.content
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "HttpClient":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+
+# ── Client asynchrone ─────────────────────────────────────────
+
+class AsyncHttpClient:
+    """Client HTTP asynchrone (httpx.AsyncClient)."""
+
+    def __init__(
+        self,
+        api_key:  str,
+        base_url: str,
+        timeout:  float,
+    ) -> None:
+        self._headers = _build_headers(api_key)
+        self._client  = httpx.AsyncClient(
+            base_url = base_url,
+            headers  = self._headers,
+            timeout  = timeout,
+        )
+
+    async def post(self, path: str, json: Dict[str, Any]) -> Dict[str, Any]:
+        response = await self._client.post(path, json=json)
+        _raise_for_status(response)
+        return response.json()
+
+    async def get(self, path: str, params: Optional[Dict] = None) -> Dict[str, Any]:
+        response = await self._client.get(path, params=params)
+        _raise_for_status(response)
+        return response.json()
+
+    async def get_bytes(self, path: str) -> bytes:
+        response = await self._client.get(path)
+        _raise_for_status(response)
+        return response.content
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncHttpClient":
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self.close()
+

alea_q/client.py

@@ -0,0 +1,181 @@
+# alea_q/client.py
+"""
+Clients principaux du SDK alea-q.
+
+Usage sync :
+    from alea_q import AleaQClient
+
+    client = AleaQClient(api_key="sk_plat_xxx")
+
+    # Platinum
+    result = client.platinum.generate(n_bits=256)
+    print(result.as_hex())
+
+    # Silver
+    result = client.silver.generate(n_bits=128)
+
+    # Ivory batch
+    batch = client.ivory.batch(size=1000, n_bits=32)
+
+    # Vérification certificat
+    client.platinum.generate(n_bits=256, verify=True, pubkey_path="certropi_public.pem")
+
+    # Context manager
+    with AleaQClient() as client:
+        result = client.platinum.generate()
+
+Usage async :
+    from alea_q import AsyncAleaQClient
+
+    async with AsyncAleaQClient(api_key="sk_plat_xxx") as client:
+        result = await client.platinum.generate(n_bits=256)
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from alea_q._http import (
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    AsyncHttpClient,
+    HttpClient,
+    _detect_tier,
+    _resolve_api_key,
+)
+from alea_q.models import AccountInfo, HealthStatus
+from alea_q.tiers.ivory import AsyncIvoryTier, IvoryTier
+from alea_q.tiers.platinum import AsyncPlatinumTier, PlatinumTier
+from alea_q.tiers.silver import AsyncSilverTier, SilverTier
+
+
+class AleaQClient:
+    """
+    Client synchrone ALEA-Q / CERTROPI.
+
+    Paramètres
+    ----------
+    api_key  : clé API (sk_plat_xxx, sk_silv_xxx, sk_ivor_xxx).
+               Si absent, lit ALEA_Q_API_KEY depuis l'environnement.
+    base_url : URL de base de l'API (défaut : https://api.alea-q.com).
+               Surcharger avec ALEA_Q_BASE_URL pour staging/dev.
+    timeout  : timeout HTTP en secondes (défaut : 60).
+
+    Attributs
+    ---------
+    tier     : tier détecté depuis le préfixe de la clé (#116) —
+               'ivory' | 'silver' | 'platinum', ou None si le préfixe
+               n'est pas reconnu (informationnel ; la validation
+               réelle de la clé se fait côté serveur).
+    platinum : sous-client Platinum (génération DI-certifiée)
+    silver   : sous-client Silver   (DRBG seedé QPU)
+    ivory    : sous-client Ivory    (simulateur Toeplitz)
+
+    Exemple
+    -------
+    >>> client = AleaQClient(api_key="sk_plat_xxx")
+    >>> result = client.platinum.generate(n_bits=256)
+    >>> print(result.as_hex())
+    """
+
+    def __init__(
+        self,
+        api_key:  Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout:  float = DEFAULT_TIMEOUT,
+    ) -> None:
+        resolved_key = _resolve_api_key(api_key)
+        self.tier     = _detect_tier(resolved_key)
+        self._http    = HttpClient(
+            api_key  = resolved_key,
+            base_url = base_url,
+            timeout  = timeout,
+        )
+        self.platinum = PlatinumTier(self._http)
+        self.silver   = SilverTier(self._http)
+        self.ivory    = IvoryTier(self._http)
+
+    def health(self) -> HealthStatus:
+        """
+        Retourne l'état du service ALEA-Q.
+        Requiert une clé admin pour la réponse complète.
+        """
+        data = self._http.get("/health")
+        return HealthStatus.from_dict(data)
+
+    def me(self) -> AccountInfo:
+        """
+        Informations du compte authentifié (#116) — tier, quota
+        journalier restant et statistiques d'usage cumulées.
+        """
+        data = self._http.get("/v1/me")
+        return AccountInfo.from_dict(data)
+
+    def close(self) -> None:
+        """Ferme le client HTTP et libère les ressources."""
+        self._http.close()
+
+    def __enter__(self) -> "AleaQClient":
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"AleaQClient(base_url={self._http._client.base_url!r})"
+
+
+class AsyncAleaQClient:
+    """
+    Client asynchrone ALEA-Q / CERTROPI.
+
+    Paramètres
+    ----------
+    api_key  : clé API. Si absent, lit ALEA_Q_API_KEY depuis l'environnement.
+    base_url : URL de base de l'API.
+    timeout  : timeout HTTP en secondes.
+
+    Exemple
+    -------
+    >>> async with AsyncAleaQClient(api_key="sk_plat_xxx") as client:
+    ...     result = await client.platinum.generate(n_bits=256)
+    ...     print(result.as_hex())
+    """
+
+    def __init__(
+        self,
+        api_key:  Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout:  float = DEFAULT_TIMEOUT,
+    ) -> None:
+        resolved_key = _resolve_api_key(api_key)
+        self.tier     = _detect_tier(resolved_key)
+        self._http    = AsyncHttpClient(
+            api_key  = resolved_key,
+            base_url = base_url,
+            timeout  = timeout,
+        )
+        self.platinum = AsyncPlatinumTier(self._http)
+        self.silver   = AsyncSilverTier(self._http)
+        self.ivory    = AsyncIvoryTier(self._http)
+
+    async def health(self) -> HealthStatus:
+        data = await self._http.get("/health")
+        return HealthStatus.from_dict(data)
+
+    async def me(self) -> AccountInfo:
+        """Informations du compte authentifié (#116) — voir AleaQClient.me()."""
+        data = await self._http.get("/v1/me")
+        return AccountInfo.from_dict(data)
+
+    async def close(self) -> None:
+        await self._http.close()
+
+    async def __aenter__(self) -> "AsyncAleaQClient":
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self.close()
+
+    def __repr__(self) -> str:
+        return f"AsyncAleaQClient(base_url={self._http._client.base_url!r})"
+

alea_q/exceptions.py

@@ -0,0 +1,120 @@
+# alea_q/exceptions.py
+"""
+Exceptions typées du SDK alea-q.
+
+Hiérarchie :
+  AleaQError                  — base commune
+    AuthenticationError       — clé API invalide ou absente (401)
+    PermissionError           — tier insuffisant (403)
+    QuotaExceeded             — quota de complexité dépassé (429)
+    BackendUnavailable        — backend QPU indisponible (503)
+    RateLimitError            — trop de requêtes (429 rate-limit)
+    ServerError               — erreur interne serveur (500)
+    CertificateError          — erreur de vérification d'attestation
+    ValidationError           — paramètres invalides côté client
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+
+class AleaQError(Exception):
+    """Exception de base du SDK alea-q."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.request_id  = request_id
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"message={str(self)!r}, "
+            f"status_code={self.status_code}, "
+            f"request_id={self.request_id!r})"
+        )
+
+
+class AuthenticationError(AleaQError):
+    """Clé API invalide, expirée ou absente. (HTTP 401)"""
+
+
+class PermissionError(AleaQError):
+    """Tier de la clé insuffisant pour cette opération. (HTTP 403)"""
+
+
+class QuotaExceeded(AleaQError):
+    """Quota de complexité ou de requêtes dépassé. (HTTP 429)"""
+
+    def __init__(
+        self,
+        message: str,
+        retry_after: Optional[int] = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class BackendUnavailable(AleaQError):
+    """
+    Backend QPU temporairement indisponible — pool vide ou en maintenance.
+    (HTTP 503)
+
+    Attributs
+    ---------
+    retry_after : secondes avant de réessayer (depuis l'en-tête Retry-After)
+    reason      : cause technique ('pool_empty_no_backend', 'backend_unavailable', etc.)
+    """
+
+    def __init__(
+        self,
+        message: str,
+        retry_after: Optional[int] = None,
+        reason: Optional[str] = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+        self.reason      = reason
+
+
+class RateLimitError(AleaQError):
+    """Trop de requêtes — rate-limit atteint. (HTTP 429)"""
+
+    def __init__(
+        self,
+        message: str,
+        retry_after: Optional[int] = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class ServerError(AleaQError):
+    """Erreur interne serveur ALEA-Q. (HTTP 500)"""
+
+
+class InsufficientBalance(AleaQError):
+    """
+    Solde prépayé insuffisant pour honorer la requête. (HTTP 402)
+
+    #178/#179 — jamais câblé dans le SDK avant cette découverte en
+    travaillant sur le streaming Silver : le mode pay-as-you-go existe
+    côté API depuis #178 mais ne levait qu'une AleaQError générique.
+    """
+
+
+class CertificateError(AleaQError):
+    """Erreur lors de la vérification d'un certificat d'attestation Platinum."""
+
+
+class ValidationError(AleaQError):
+    """Paramètres de requête invalides (vérification côté client avant envoi)."""
+