apron-auth 0.1.0__py3-none-any.whl

apron_auth/__init__.py

@@ -0,0 +1,36 @@
+"""Stateless OAuth 2.0 protocol library."""
+
+from __future__ import annotations
+
+from apron_auth.client import OAuthClient
+from apron_auth.errors import (
+    ConfigurationError,
+    OAuthError,
+    PermanentOAuthError,
+    RevocationError,
+    StateError,
+    TokenExchangeError,
+    TokenRefreshError,
+)
+from apron_auth.models import OAuthPendingState, ProviderConfig, ScopeMetadata, TokenSet
+from apron_auth.protocols import RevocationHandler, StandardRevocationHandler, StateStore
+from apron_auth.stores import MemoryStateStore
+
+__all__ = [
+    "ConfigurationError",
+    "MemoryStateStore",
+    "OAuthClient",
+    "OAuthError",
+    "OAuthPendingState",
+    "PermanentOAuthError",
+    "ProviderConfig",
+    "RevocationError",
+    "RevocationHandler",
+    "ScopeMetadata",
+    "StandardRevocationHandler",
+    "StateError",
+    "StateStore",
+    "TokenExchangeError",
+    "TokenRefreshError",
+    "TokenSet",
+]

apron_auth/client.py

@@ -0,0 +1,282 @@
+"""OAuth 2.0 client for authorization code flows."""
+
+from __future__ import annotations
+
+import secrets
+import time
+from typing import TYPE_CHECKING, Any
+from urllib.parse import parse_qs, urlencode, urlparse, urlunparse
+
+import httpx
+
+from apron_auth.errors import (
+    ConfigurationError,
+    PermanentOAuthError,
+    RevocationError,
+    StateError,
+    TokenExchangeError,
+    TokenRefreshError,
+)
+from apron_auth.models import OAuthPendingState, TokenSet
+from apron_auth.pkce import generate_code_challenge, generate_code_verifier
+from apron_auth.protocols import StandardRevocationHandler
+from apron_auth.scopes import join_scopes
+
+if TYPE_CHECKING:
+    from apron_auth.models import ProviderConfig
+    from apron_auth.protocols import RevocationHandler, StateStore
+
+
+class _TokenEndpointError(Exception):
+    """Internal exception carrying the OAuth error code from the token endpoint."""
+
+    def __init__(self, message: str, error_code: str = "") -> None:
+        super().__init__(message)
+        self.error_code = error_code
+
+
+class OAuthClient:
+    """Stateless OAuth 2.0 client for authorization code flows."""
+
+    DEFAULT_PERMANENT_ERROR_CODES = frozenset({"invalid_grant", "unauthorized_client", "invalid_client"})
+
+    def __init__(
+        self,
+        config: ProviderConfig,
+        state_store: StateStore | None = None,
+        revocation_handler: RevocationHandler | None = None,
+        permanent_error_codes: set[str] | None = None,
+    ) -> None:
+        """Create an OAuth client.
+
+        Args:
+            config: Provider endpoints, credentials, and behavior.
+            state_store: Optional persistence for OAuth state across requests.
+            revocation_handler: Optional provider-specific token revocation.
+            permanent_error_codes: Additional OAuth error codes that should be
+                treated as irrecoverable during token refresh. These merge
+                with, rather than replace, DEFAULT_PERMANENT_ERROR_CODES.
+        """
+        self._config = config
+        self._state_store = state_store
+        self._revocation_handler = revocation_handler
+        self._permanent_error_codes = self.DEFAULT_PERMANENT_ERROR_CODES | (permanent_error_codes or set())
+
+    async def get_authorization_url(
+        self,
+        redirect_uri: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> tuple[str, OAuthPendingState]:
+        """Build an authorization URL with state and optional PKCE.
+
+        If a ``StateStore`` is configured, the pending state is saved
+        automatically before returning.
+
+        Args:
+            redirect_uri: Override the redirect URI from ``ProviderConfig``.
+            metadata: Opaque caller context attached to the pending state.
+                Carried through ``StateStore`` save/consume and surfaced
+                on ``TokenSet.context`` when ``exchange_code`` auto-consumes.
+
+        Returns:
+            A tuple of the authorization URL and the pending state.
+
+        Raises:
+            ConfigurationError: If no redirect URI is available.
+        """
+        effective_redirect_uri = redirect_uri or self._config.redirect_uri
+        if not effective_redirect_uri:
+            msg = "redirect_uri must be provided either in the method call or in ProviderConfig"
+            raise ConfigurationError(msg)
+
+        state = secrets.token_urlsafe(32)
+        code_verifier = None
+
+        params: dict[str, str] = {
+            "client_id": self._config.client_id,
+            "response_type": "code",
+            "redirect_uri": effective_redirect_uri,
+            "state": state,
+        }
+
+        if self._config.scopes:
+            params["scope"] = join_scopes(self._config.scopes, self._config.scope_separator)
+
+        if self._config.use_pkce:
+            code_verifier = generate_code_verifier()
+            params["code_challenge"] = generate_code_challenge(code_verifier)
+            params["code_challenge_method"] = "S256"
+
+        params.update(self._config.extra_params)
+
+        parsed = urlparse(self._config.authorize_url)
+        existing_params = parse_qs(parsed.query)
+        merged = {k: v[0] if len(v) == 1 else v for k, v in existing_params.items()}
+        merged.update(params)
+        url = urlunparse(parsed._replace(query=urlencode(merged, doseq=True)))
+
+        pending_state = OAuthPendingState(
+            state=state,
+            redirect_uri=effective_redirect_uri,
+            code_verifier=code_verifier,
+            created_at=time.time(),
+            metadata=metadata or {},
+        )
+
+        if self._state_store is not None:
+            await self._state_store.save(pending_state)
+
+        return url, pending_state
+
+    async def exchange_code(
+        self,
+        code: str,
+        state: str | None = None,
+        redirect_uri: str | None = None,
+        code_verifier: str | None = None,
+    ) -> TokenSet:
+        """Exchange an authorization code for tokens.
+
+        Two modes:
+        - Pass state to consume from StateStore and retrieve stored
+          redirect_uri and code_verifier.
+        - Pass redirect_uri and code_verifier directly.
+        """
+        context: dict[str, Any] = {}
+        if state is not None and self._state_store is not None:
+            pending = await self._state_store.consume(state)
+            if pending is None:
+                msg = "OAuth state is invalid, expired, or already consumed"
+                raise StateError(msg)
+            redirect_uri = pending.redirect_uri
+            code_verifier = pending.code_verifier
+            context = pending.metadata
+
+        data: dict[str, str] = {
+            "grant_type": "authorization_code",
+            "code": code,
+        }
+        if redirect_uri:
+            data["redirect_uri"] = redirect_uri
+        if code_verifier:
+            data["code_verifier"] = code_verifier
+
+        try:
+            response = await self._token_request(data)
+        except _TokenEndpointError as exc:
+            raise TokenExchangeError(str(exc)) from exc
+        return self._parse_token_response(response, context=context)
+
+    async def refresh_token(self, refresh_token: str) -> TokenSet:
+        """Refresh an access token using a refresh token.
+
+        Raises PermanentOAuthError for irrecoverable failures
+        (invalid_grant, unauthorized_client, invalid_client).
+        Raises TokenRefreshError for transient failures.
+        """
+        data = {
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+        }
+        try:
+            response = await self._token_request(data)
+        except _TokenEndpointError as exc:
+            if exc.error_code in self._permanent_error_codes:
+                raise PermanentOAuthError(str(exc)) from exc
+            raise TokenRefreshError(str(exc)) from exc
+        except Exception as exc:
+            raise TokenRefreshError(str(exc)) from exc
+        return self._parse_token_response(response)
+
+    async def revoke_token(self, token: str) -> bool:
+        """Revoke a token via the provider's revocation endpoint.
+
+        Uses the configured RevocationHandler, or falls back to
+        StandardRevocationHandler (RFC 7009 POST).
+        """
+        if not self._config.revocation_url:
+            msg = "revocation_url is not configured for this provider"
+            raise ConfigurationError(msg)
+
+        handler = self._revocation_handler
+        if handler is None:
+            handler = StandardRevocationHandler()
+
+        try:
+            result = await handler.revoke(token, self._config)
+        except RevocationError:
+            raise
+        except Exception as exc:
+            raise RevocationError(str(exc)) from exc
+        if not result:
+            msg = "Token revocation failed"
+            raise RevocationError(msg)
+        return True
+
+    async def _token_request(self, data: dict[str, str]) -> dict:
+        """Send a token request via authlib's AsyncOAuth2Client.
+
+        Authlib handles token_endpoint_auth_method (client_secret_post vs
+        client_secret_basic), request encoding, and response parsing.
+        Three error paths are possible — see inline comments.
+        """
+        from authlib.integrations.base_client.errors import OAuthError
+        from authlib.integrations.httpx_client import AsyncOAuth2Client
+
+        try:
+            async with AsyncOAuth2Client(
+                client_id=self._config.client_id,
+                client_secret=self._config.client_secret.get_secret_value(),
+                token_endpoint_auth_method=self._config.token_endpoint_auth_method,
+            ) as client:
+                token = await client.fetch_token(self._config.token_url, **data)
+            return dict(token)
+        except OAuthError as exc:
+            # Authlib raises OAuthError for 4xx responses that contain an
+            # OAuth error body ({"error": "...", "error_description": "..."}).
+            # The .error attribute carries the OAuth error code (e.g.
+            # "invalid_grant") which refresh_token uses to distinguish
+            # permanent from transient failures.
+            raise _TokenEndpointError(
+                f"{exc.error}: {exc.description}" if exc.description else str(exc.error),
+                error_code=str(exc.error),
+            ) from exc
+        except httpx.HTTPStatusError as exc:
+            # Authlib calls raise_for_status() for 5xx responses, producing
+            # an httpx.HTTPStatusError. We attempt to extract the OAuth
+            # error code from the response body if present.
+            error_code = ""
+            msg = f"HTTP {exc.response.status_code}"
+            try:
+                body = exc.response.json()
+                error_code = body.get("error", "")
+                description = body.get("error_description", "")
+                msg = f"{error_code}: {description}" if description else error_code or msg
+            except Exception:
+                pass
+            raise _TokenEndpointError(msg, error_code=error_code) from exc
+        except Exception as exc:
+            # Network errors (ConnectError, TimeoutException), JSON decode
+            # errors, or anything else. No error_code available.
+            raise _TokenEndpointError(str(exc), error_code="") from exc
+
+    def _parse_token_response(self, data: dict, context: dict[str, Any] | None = None) -> TokenSet:
+        """Parse a token endpoint response into a TokenSet."""
+        known_fields = {"access_token", "token_type", "refresh_token", "expires_in", "expires_at", "scope"}
+        metadata = {k: v for k, v in data.items() if k not in known_fields}
+
+        expires_at = data.get("expires_at")
+        expires_in = data.get("expires_in")
+        if expires_at is None and expires_in is not None:
+            expires_at = time.time() + int(expires_in)
+
+        return TokenSet(
+            access_token=data["access_token"],
+            token_type=data.get("token_type", "Bearer"),
+            refresh_token=data.get("refresh_token"),
+            expires_in=int(expires_in) if expires_in is not None else None,
+            expires_at=expires_at,
+            scope=data.get("scope"),
+            metadata=metadata,
+            context=context or {},
+        )

apron_auth/errors.py

@@ -0,0 +1,35 @@
+"""Exception hierarchy for apron-auth OAuth operations."""
+
+from __future__ import annotations
+
+
+class OAuthError(Exception):
+    """Base exception for all apron-auth errors."""
+
+
+class TokenExchangeError(OAuthError):
+    """Authorization code exchange failed."""
+
+
+class TokenRefreshError(OAuthError):
+    """Token refresh failed (transient — retry may succeed)."""
+
+
+class PermanentOAuthError(OAuthError):
+    """Irrecoverable OAuth failure.
+
+    Raised for errors like invalid_grant, unauthorized_client, or
+    invalid_client. The caller should delete the stored token.
+    """
+
+
+class RevocationError(OAuthError):
+    """Token revocation failed at the provider."""
+
+
+class StateError(OAuthError):
+    """OAuth state invalid, expired, or already consumed."""
+
+
+class ConfigurationError(OAuthError):
+    """Provider configuration is invalid or incomplete."""

apron_auth/models.py

@@ -0,0 +1,152 @@
+"""Data models for OAuth configuration, tokens, and state."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, SecretStr
+
+AccessType = Literal["read", "write", "admin"]
+
+
+class ScopeMetadata(BaseModel, frozen=True):
+    """Consent-UI metadata for a single OAuth scope.
+
+    Field shape mirrors apron-tools' ``ScopeMetadata`` so a consumer can
+    concatenate ``CapabilityGroup.metadata()`` from apron-tools with
+    :attr:`ProviderConfig.scope_metadata` to produce a complete
+    ``list[ScopeMetadata]`` for a consent picker. apron-auth declares
+    metadata only for the cross-cutting scopes its presets inject;
+    apron-tools owns metadata for tool-level scopes.
+
+    Attributes:
+        scope: The OAuth scope string sent to the provider, exactly as it
+            appears in :attr:`ProviderConfig.scopes`.
+        label: Short human-readable name for the consent picker.
+        description: Longer explanation of what granting this scope does;
+            should match the provider's authorize-page wording where
+            possible so the consent picker stays in sync with what the
+            user sees at the provider.
+        access_type: Coarse classification used for visual grouping in
+            the consent picker.
+        required: When ``True``, the consumer's UI should not allow the
+            user to deselect the scope — typically because the OAuth
+            flow itself depends on it (e.g. ``openid`` for identity,
+            ``offline_access`` for refresh tokens).
+    """
+
+    scope: str
+    label: str
+    description: str
+    access_type: AccessType
+    required: bool = False
+
+
+class ProviderConfig(BaseModel, frozen=True):
+    """OAuth provider configuration — endpoints, credentials, behaviour.
+
+    Attributes:
+        disconnect_fully_revokes: Whether ``revoke_token`` removes the
+            user's portal-level OAuth grant.
+
+            When ``True``, calling
+            :meth:`~apron_auth.client.OAuthClient.revoke_token` is
+            sufficient to force a fresh consent screen on the next
+            authorization flow — enabling automatic scope-reduction
+            (tier 1) end-to-end inside the OAuth flow.
+
+            When ``False``, revocation only invalidates the current
+            token. A subsequent authorization flow reuses the existing
+            portal-level grant and the user keeps their previously-
+            granted scopes regardless of what's requested. Consumers
+            must surface a deep link to the provider's app-management
+            settings (tier 3) for the user to remove the grant
+            manually.
+
+            Defaults to ``False``. Over-claiming silently breaks scope
+            reduction; under-claiming harmlessly falls back to the
+            manual deep-link path.
+        scope_metadata: Consent-UI metadata for the cross-cutting scopes
+            the preset injects into :attr:`scopes` (e.g. ``openid``,
+            ``offline_access``). Empty when the preset does not inject
+            any scopes of its own. Consumers building a consent picker
+            should concatenate apron-tools' ``CapabilityGroup.metadata()``
+            with this list to cover both tool-level and cross-cutting
+            scopes without a parallel hand-maintained table.
+        required_scope_families: Set-level scope constraints expressing
+            "at least one of these scope sets must be requested".  Each
+            inner list is an "at-least-one-of" group; the constraint is
+            satisfied when the final scope selection contains at least
+            one scope drawn from at least one family.  Used by providers
+            (e.g. Slack) whose token endpoint applies a set-level OR
+            rule that cannot be expressed as per-scope
+            :attr:`ScopeMetadata.required`.  A consent picker can
+            enforce the constraint generically without provider-specific
+            knowledge.  Defaults to empty (no set-level constraint).
+    """
+
+    client_id: str
+    client_secret: SecretStr
+    authorize_url: str
+    token_url: str
+    revocation_url: str | None = None
+    redirect_uri: str | None = None
+    scopes: list[str] = []
+    scope_separator: str = " "
+    use_pkce: bool = True
+    token_endpoint_auth_method: str = "client_secret_post"
+    extra_params: dict[str, str] = {}
+    disconnect_fully_revokes: bool = False
+    scope_metadata: list[ScopeMetadata] = []
+    required_scope_families: list[list[str]] = []
+
+
+class TokenSet(BaseModel, frozen=True):
+    """Token data returned from code exchange or refresh.
+
+    Attributes:
+        access_token: The access token issued by the provider.
+        token_type: Token type, typically ``"Bearer"``.
+        refresh_token: Optional refresh token for obtaining new access tokens.
+        expires_in: Token lifetime in seconds as reported by the provider.
+        expires_at: Absolute expiry time as a Unix timestamp.
+        scope: Space-separated scopes granted by the provider.
+        metadata: Additional fields from the provider's token endpoint
+            response that are not captured by the named attributes above
+            (e.g. Slack's ``team_id``).  Populated automatically.
+        context: Caller-supplied context carried opaquely from
+            ``OAuthPendingState.metadata`` through the authorization flow.
+            Populated when ``exchange_code`` auto-consumes from a
+            ``StateStore``; empty otherwise.
+    """
+
+    access_token: str
+    token_type: str = "Bearer"
+    refresh_token: str | None = None
+    expires_in: int | None = None
+    expires_at: float | None = None
+    scope: str | None = None
+    metadata: dict[str, Any] = {}
+    context: dict[str, Any] = {}
+
+
+class OAuthPendingState(BaseModel, frozen=True):
+    """State stored during the OAuth authorization flow.
+
+    Attributes:
+        state: Unique token identifying this authorization request.
+        redirect_uri: Redirect URI for this flow.
+        code_verifier: PKCE code verifier, if PKCE is enabled.
+        created_at: Unix timestamp when this state was created.
+        metadata: Opaque caller-supplied context that apron-auth carries
+            but never interprets.  Attach application-specific data
+            (e.g. ``user_id``, ``tenant_id``) here; it will be preserved
+            through ``StateStore`` save/consume and surfaced on
+            ``TokenSet.context`` when ``exchange_code`` auto-consumes.
+    """
+
+    state: str
+    redirect_uri: str
+    code_verifier: str | None = None
+    created_at: float
+    metadata: dict[str, Any] = {}

apron_auth/pkce.py

@@ -0,0 +1,25 @@
+"""PKCE (Proof Key for Code Exchange) support per RFC 7636."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import secrets
+
+
+def generate_code_verifier() -> str:
+    """Generate a cryptographically random code verifier.
+
+    Returns a 43-character URL-safe string with 256 bits of entropy.
+    """
+    return secrets.token_urlsafe(32)
+
+
+def generate_code_challenge(code_verifier: str) -> str:
+    """Generate an S256 code challenge from a code verifier.
+
+    Computes the SHA-256 hash of the verifier and returns the
+    base64url encoding without padding.
+    """
+    digest = hashlib.sha256(code_verifier.encode("utf-8")).digest()
+    return base64.urlsafe_b64encode(digest).decode("utf-8").rstrip("=")

apron_auth/protocols.py

@@ -0,0 +1,85 @@
+"""Protocols for caller-provided storage and provider-specific revocation."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+import httpx
+
+from apron_auth.errors import RevocationError
+
+if TYPE_CHECKING:
+    from apron_auth.models import OAuthPendingState, ProviderConfig
+
+
+@runtime_checkable
+class StateStore(Protocol):
+    """Caller provides persistence for OAuth state.
+
+    Implementations are responsible for expiring stale entries.
+    Each OAuthPendingState carries a created_at timestamp that
+    implementations should use to enforce a maximum age (typically
+    under 10 minutes for OAuth authorization flows).
+
+    See MemoryStateStore for a reference implementation with
+    automatic expiry.
+    """
+
+    async def save(self, state: OAuthPendingState) -> None:
+        """Store pending state during authorization URL generation."""
+        ...
+
+    async def consume(self, state_key: str) -> OAuthPendingState | None:
+        """Atomically retrieve and invalidate state.
+
+        Returns None if the state is invalid, expired, or already consumed.
+        """
+        ...
+
+
+@runtime_checkable
+class RevocationHandler(Protocol):
+    """Provider-specific token revocation."""
+
+    async def revoke(self, token: str, config: ProviderConfig) -> bool:
+        """Revoke a token at the provider.
+
+        Returns True if revocation succeeded.
+        """
+        ...
+
+
+class StandardRevocationHandler:
+    """RFC 7009 token revocation via POST with token in form body."""
+
+    def __init__(self, client: httpx.AsyncClient | None = None) -> None:
+        self._client = client
+
+    async def revoke(self, token: str, config: ProviderConfig) -> bool:
+        """Revoke a token using standard RFC 7009 POST."""
+        if config.revocation_url is None:
+            msg = "revocation_url is required but not set in ProviderConfig"
+            raise ValueError(msg)
+        revocation_url = config.revocation_url
+        if self._client is not None:
+            return await self._send(self._client, token, revocation_url, config)
+        async with httpx.AsyncClient() as client:
+            return await self._send(client, token, revocation_url, config)
+
+    async def _send(
+        self,
+        client: httpx.AsyncClient,
+        token: str,
+        revocation_url: str,
+        config: ProviderConfig,
+    ) -> bool:
+        """Send the revocation request and return success status."""
+        try:
+            response = await client.post(
+                revocation_url,
+                data={"token": token},
+                auth=(config.client_id, config.client_secret.get_secret_value()),
+            )
+        except httpx.RequestError as exc:
+            raise RevocationError(str(exc)) from exc
+        return response.is_success

apron_auth/providers/__init__.py

@@ -0,0 +1,3 @@
+"""Provider presets for common OAuth providers."""
+
+from __future__ import annotations