authplane-sdk 0.1.0__py3-none-any.whl

authplane/README.md

@@ -0,0 +1,46 @@
+# authplane-sdk
+
+[![PyPI](https://img.shields.io/pypi/v/authplane-sdk?style=flat-square&label=authplane-sdk)](https://pypi.org/project/authplane-sdk/)
+[![Python versions](https://img.shields.io/pypi/pyversions/authplane-sdk?style=flat-square)](https://pypi.org/project/authplane-sdk/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue?style=flat-square)](https://opensource.org/licenses/Apache-2.0)
+
+Framework-agnostic OAuth 2.1 JWT validation and token operations for Python resource servers.
+
+## Install
+
+```bash
+pip install authplane-sdk
+```
+
+## Quickstart
+
+```python
+import asyncio
+from authplane import ASCredentials, AuthplaneClient
+
+
+async def main():
+    client = await AuthplaneClient.create(
+        issuer="https://auth.example.com",
+        auth=ASCredentials(client_id="my-resource", client_secret="s3cret"),
+    )
+
+    res = client.resource(
+        resource="https://api.example.com",
+        scopes=["read", "write"],
+    )
+
+    claims = await res.verify(incoming_jwt)
+    print(claims.sub, claims.scopes)
+
+    await client.aclose()
+
+
+asyncio.run(main())
+```
+
+Call `await client.aclose()` on shutdown to stop background JWKS and metadata refresh tasks.
+
+## Documentation
+
+Full API reference, configuration options, error hierarchy, DPoP, token operations, introspection, token exchange, and advanced usage: **[User Guide](docs/user-guide.md)**.

authplane/__init__.py

@@ -0,0 +1,116 @@
+"""Authplane Python SDK — OAuth 2.1 JWT validation and token operations for protected resources."""
+
+__version__ = "0.1.0"
+
+# Client
+# Authentication
+from .auth_provider import AuthProvider, ClientCredentialsProvider
+from .client import AuthplaneClient
+from .credentials import ASCredentials
+from .dpop import (
+    SUPPORTED_DPOP_ALGORITHMS,
+    DPoPKeyMaterial,
+    DPoPNonceStore,
+    DPoPProvider,
+    DPoPReplayStore,
+    DPoPRequestContext,
+    InboundDPoPOptions,
+    InMemoryDPoPNonceStore,
+    InMemoryDPoPReplayStore,
+)
+from .dpop_verification import VerifiedDPoPProof
+
+# Errors (base + the one that changes HTTP status)
+from .errors import (
+    AuthError,
+    AuthplaneError,
+    CircuitOpenError,
+    ConsentRequiredError,
+    DPoPBindingMismatchError,
+    DPoPError,
+    DPoPNotSupportedError,
+    DPoPProofMissingError,
+    DPoPReplayDetectedError,
+    InsufficientScopeError,
+    InvalidClaimsError,
+    InvalidClientError,
+    InvalidDPoPProofError,
+    InvalidGrantError,
+    InvalidRequestError,
+    InvalidScopeError,
+    InvalidSignatureError,
+    JWKSFetchError,
+    MetadataFetchError,
+    MissingMetadataEndpointError,
+    ProtocolError,
+    ServerError,
+    TokenExpiredError,
+    TokenMissingError,
+    TokenRevokedError,
+    UnauthorizedClientError,
+    UnsupportedGrantTypeError,
+    VerifierRuntimeError,
+    http_status,
+    www_authenticate,
+)
+
+# Configuration
+from .net import FetchSettings
+from .oauth.types import IntrospectionRevocation
+
+# Resource (verifier)
+from .verifier import AuthplaneResource, VerifiedClaims
+from .verifier.verifier import RevocationChecker
+
+__all__ = [
+    "SUPPORTED_DPOP_ALGORITHMS",
+    "ASCredentials",
+    "AuthError",
+    "AuthProvider",
+    "AuthplaneClient",
+    "AuthplaneError",
+    "AuthplaneResource",
+    "CircuitOpenError",
+    "ClientCredentialsProvider",
+    "ConsentRequiredError",
+    "DPoPBindingMismatchError",
+    "DPoPError",
+    "DPoPKeyMaterial",
+    "DPoPNonceStore",
+    "DPoPNotSupportedError",
+    "DPoPProofMissingError",
+    "DPoPProvider",
+    "DPoPReplayDetectedError",
+    "DPoPReplayStore",
+    "DPoPRequestContext",
+    "FetchSettings",
+    "InMemoryDPoPNonceStore",
+    "InMemoryDPoPReplayStore",
+    "InboundDPoPOptions",
+    "InsufficientScopeError",
+    "IntrospectionRevocation",
+    "InvalidClaimsError",
+    "InvalidClientError",
+    "InvalidDPoPProofError",
+    "InvalidGrantError",
+    "InvalidRequestError",
+    "InvalidScopeError",
+    "InvalidSignatureError",
+    "JWKSFetchError",
+    "MetadataFetchError",
+    "MissingMetadataEndpointError",
+    "ProtocolError",
+    "RevocationChecker",
+    "ServerError",
+    "TokenExpiredError",
+    "TokenMissingError",
+    "TokenRevokedError",
+    "UnauthorizedClientError",
+    "UnsupportedGrantTypeError",
+    "VerifiedClaims",
+    "VerifiedDPoPProof",
+    "VerifierRuntimeError",
+    "__version__",
+    "http_status",
+    "www_authenticate",
+]

authplane/auth_provider.py

@@ -0,0 +1,28 @@
+"""AuthProvider protocol — pluggable authentication for OAuth operations."""
+
+from typing import Protocol, runtime_checkable
+
+from .net.http import build_basic_auth_header
+
+
+@runtime_checkable
+class AuthProvider(Protocol):
+    """Protocol for providing authentication headers to OAuth endpoints.
+
+    Implementations return the headers dict (e.g. ``{"Authorization": "Basic ..."}``).
+    """
+
+    def auth_headers(self) -> dict[str, str]:
+        """Return HTTP headers for authenticating to the AS."""
+        ...
+
+
+class ClientCredentialsProvider:
+    """HTTP Basic Auth from client_id + client_secret (RFC 6749 §2.3.1)."""
+
+    def __init__(self, client_id: str, client_secret: str) -> None:
+        self._headers = build_basic_auth_header(client_id, client_secret)
+
+    def auth_headers(self) -> dict[str, str]:
+        """Return Basic auth headers built from client_id and client_secret."""
+        return self._headers

authplane/cache.py

@@ -0,0 +1,78 @@
+"""Token cache with TTL buffer for client_credentials tokens."""
+
+import time
+from dataclasses import dataclass
+
+
+@dataclass
+class CacheEntry:
+    """A cached token."""
+
+    access_token: str
+    token_type: str
+    expires_in: int
+    scope: str
+    expires_at: float  # monotonic time
+
+
+class TokenCache:
+    """In-memory token cache with configurable TTL buffer.
+
+    Tokens are evicted `ttl_buffer_seconds` before their actual expiry
+    to avoid using tokens that are about to expire.
+    """
+
+    def __init__(
+        self,
+        ttl_buffer_seconds: float = 30.0,
+        default_ttl_seconds: float = 3600.0,
+    ) -> None:
+        self._ttl_buffer = ttl_buffer_seconds
+        self._default_ttl = default_ttl_seconds
+        self._entries: dict[str, CacheEntry] = {}
+
+    def get(self, key: str) -> CacheEntry | None:
+        """Get a cached entry if it exists and hasn't expired."""
+        entry = self._entries.get(key)
+        if entry is None:
+            return None
+        if time.monotonic() >= entry.expires_at:
+            del self._entries[key]
+            return None
+        return entry
+
+    def set(
+        self,
+        key: str,
+        access_token: str,
+        token_type: str,
+        expires_in: int = 0,
+        scope: str = "",
+    ) -> None:
+        """Cache a token. Skips caching if effective TTL <= 0."""
+        ttl = (expires_in if expires_in > 0 else self._default_ttl) - self._ttl_buffer
+        if ttl <= 0:
+            return
+        self._entries[key] = CacheEntry(
+            access_token=access_token,
+            token_type=token_type,
+            expires_in=expires_in,
+            scope=scope,
+            expires_at=time.monotonic() + ttl,
+        )
+
+    def delete(self, key: str) -> None:
+        """Remove a cached entry."""
+        self._entries.pop(key, None)
+
+    @staticmethod
+    def cache_key(scope: str = "", resource: str = "") -> str:
+        """Generate a deterministic cache key from scope and resource.
+
+        Scopes are sorted for consistency.
+        """
+        parts = sorted(scope.split()) if scope else []
+        scope_part = " ".join(parts)
+        if resource:
+            return f"{scope_part}|{resource}" if scope_part else f"|{resource}"
+        return scope_part or "_default"

authplane/circuit_breaker.py

@@ -0,0 +1,90 @@
+"""Circuit breaker for AS resilience."""
+
+import time
+from enum import Enum
+
+
+class _State(Enum):
+    CLOSED = "closed"
+    OPEN = "open"
+    HALF_OPEN = "half_open"
+
+
+class CircuitBreaker:
+    """Protects against cascading failures when the AS is unavailable."""
+
+    def __init__(
+        self,
+        threshold: int = 5,
+        cooldown_seconds: float = 30.0,
+    ) -> None:
+        self._threshold = threshold
+        self._cooldown_seconds = cooldown_seconds
+        self._state = _State.CLOSED
+        self._failure_count = 0
+        self._opened_at = 0.0
+        self._probe_in_flight = False
+
+    @property
+    def state(self) -> str:
+        """Return the current circuit state ('closed', 'open', or 'half_open')."""
+        return self._effective_state().value
+
+    def _effective_state(self) -> _State:
+        # OPEN transitions to a logical HALF_OPEN view after the cooldown
+        # window expires. We delay mutating the stored state until a caller
+        # actually attempts the probe so repeated state checks remain cheap.
+        if (
+            self._state == _State.OPEN
+            and time.monotonic() - self._opened_at >= self._cooldown_seconds
+        ):
+            return _State.HALF_OPEN
+        return self._state
+
+    def allow(self) -> bool:
+        """Return True if a request should be attempted, False if shed."""
+        state = self._effective_state()
+        if state == _State.CLOSED:
+            return True
+        if state == _State.OPEN:
+            return False
+
+        # HALF_OPEN allows exactly one in-flight probe. Everybody else keeps
+        # seeing the circuit as unavailable until that probe succeeds or fails.
+        if self._state != _State.HALF_OPEN:
+            self._state = _State.HALF_OPEN
+        if self._probe_in_flight:
+            return False
+        self._probe_in_flight = True
+        return True
+
+    def record_success(self) -> None:
+        """Record a successful request, closing the circuit if it was half-open."""
+        # Any success, including the half-open probe, fully restores traffic.
+        self._failure_count = 0
+        self._state = _State.CLOSED
+        self._probe_in_flight = False
+
+    def record_failure(self) -> None:
+        """Record a failed request, opening the circuit when the threshold is reached."""
+        effective_state = self._effective_state()
+        # A failed half-open probe immediately re-opens the circuit instead of
+        # walking failure_count up again.
+        if self._probe_in_flight and (
+            effective_state == _State.HALF_OPEN or self._state == _State.HALF_OPEN
+        ):
+            self._state = _State.OPEN
+            self._opened_at = time.monotonic()
+            self._probe_in_flight = False
+            self._failure_count = self._threshold
+            return
+        if effective_state == _State.HALF_OPEN and self._state == _State.OPEN:
+            # Ignore failures that arrive after cooldown but before a probe was
+            # actually admitted; they should not reset the cooldown timer.
+            return
+
+        self._failure_count += 1
+        if self._failure_count >= self._threshold:
+            self._state = _State.OPEN
+            self._opened_at = time.monotonic()
+        self._probe_in_flight = False