aauth 0.1.0__py3-none-any.whl

aauth/headers/signature_key.py

@@ -0,0 +1,99 @@
+"""Signature-Key header parsing and building for AAuth."""
+
+import re
+from typing import Dict, Any
+from ..keys.jwk import public_key_to_jwk
+
+
+def build_signature_key_header(
+    sig_scheme: str,
+    private_key,
+    label: str = "sig1",
+    **kwargs
+) -> str:
+    """Build Signature-Key header as RFC 8941 Structured Fields Dictionary.
+    
+    Format: {label}=(scheme=hwk kty="OKP" crv="Ed25519" x="...")
+    The label must match the label used in Signature-Input and Signature headers.
+    
+    Args:
+        sig_scheme: Signature scheme ("hwk", "jwks", "jwt")
+        private_key: Private key (for hwk scheme)
+        label: Signature label (default: "sig1")
+        **kwargs: Additional parameters:
+            - For "hwk": None (key extracted from private_key)
+            - For "jwks": id (required), kid (required), well-known (optional)
+            - For "jwt": jwt (required)
+    
+    Returns:
+        Signature-Key header value
+        
+    Raises:
+        ValueError: If required parameters are missing
+    """
+    if sig_scheme == "hwk":
+        public_key = private_key.public_key()
+        jwk = public_key_to_jwk(public_key)
+        return f'{label}=(scheme=hwk kty="{jwk["kty"]}" crv="{jwk["crv"]}" x="{jwk["x"]}")'
+    elif sig_scheme == "jwks":
+        agent_id = kwargs.get("id")
+        kid = kwargs.get("kid", "key-1")
+        well_known = kwargs.get("well-known")
+        if not agent_id:
+            raise ValueError("sig=jwks requires 'id' parameter")
+        header_parts = [f'scheme=jwks', f'id="{agent_id}"', f'kid="{kid}"']
+        if well_known:
+            header_parts.append(f'well-known="{well_known}"')
+        return f'{label}=({" ".join(header_parts)})'
+    elif sig_scheme == "jwt":
+        jwt_token = kwargs.get("jwt")
+        if not jwt_token:
+            raise ValueError("sig=jwt requires 'jwt' parameter")
+        return f'{label}=(scheme=jwt jwt="{jwt_token}")'
+    else:
+        raise ValueError(f"Unknown signature scheme: {sig_scheme}")
+
+
+def parse_signature_key(header_value: str) -> Dict[str, Any]:
+    """Parse Signature-Key header value (RFC 8941 Structured Fields Dictionary).
+    
+    Supports any label (sig, sig1, etc.) - the label is extracted but not validated here.
+    
+    Args:
+        header_value: Signature-Key header value
+        
+    Returns:
+        Dictionary with keys: scheme, params, label
+        
+    Raises:
+        ValueError: If header format is invalid
+    """
+    # Match any label: sig=, sig1=, etc.
+    match = re.match(r'(\w+)=\((.*)\)', header_value)
+    if not match:
+        raise ValueError(f"Invalid Signature-Key format: {header_value}")
+    
+    label = match.group(1)
+    inner_content = match.group(2)
+    params = {}
+    scheme = None
+    
+    # Allow hyphens in parameter names (e.g., "well-known")
+    param_pattern = r'([\w-]+)=(?:"([^"]*)"|([^\s)]+))'
+    for match in re.finditer(param_pattern, inner_content):
+        key = match.group(1)
+        value = match.group(2) or match.group(3)
+        if key == "scheme":
+            scheme = value
+        else:
+            params[key] = value
+    
+    if not scheme:
+        raise ValueError(f"Missing scheme in Signature-Key: {header_value}")
+    
+    return {
+        "scheme": scheme,
+        "params": params,
+        "label": label  # Include label for consistency checking
+    }
+

aauth/http/__init__.py

@@ -0,0 +1,2 @@
+"""HTTP abstraction layer for framework-agnostic AAuth operations."""
+

aauth/http/request.py

@@ -0,0 +1,140 @@
+"""Framework-agnostic HTTP request representation for AAuth."""
+
+from typing import Dict, Optional
+from urllib.parse import urlparse
+
+
+class AAuthRequest:
+    """Framework-agnostic HTTP request representation.
+    
+    This class provides a common interface for HTTP requests that AAuth
+    operations can work with, independent of the underlying framework
+    (FastAPI, Flask, Django, etc.).
+    
+    Attributes:
+        method: HTTP method (GET, POST, etc.)
+        authority: Canonical authority (host:port) per SPEC 10.3.1
+        path: Request path (e.g., "/api/data")
+        query: Query string (without leading "?")
+        headers: Request headers dictionary (case-insensitive keys)
+        body: Request body bytes (None if no body)
+    """
+    
+    def __init__(
+        self,
+        method: str,
+        authority: str,
+        path: str,
+        query: Optional[str] = None,
+        headers: Optional[Dict[str, str]] = None,
+        body: Optional[bytes] = None
+    ):
+        """Initialize AAuthRequest.
+        
+        Args:
+            method: HTTP method
+            authority: Canonical authority (host:port)
+            path: Request path
+            query: Query string (without leading "?")
+            headers: Request headers
+            body: Request body bytes
+        """
+        self.method = method.upper()
+        self.authority = authority
+        self.path = path or "/"
+        self.query = query
+        self.headers = headers or {}
+        self.body = body
+    
+    @classmethod
+    def from_dict(cls, data: Dict) -> "AAuthRequest":
+        """Create AAuthRequest from dictionary.
+        
+        Args:
+            data: Dictionary with keys: method, authority, path, query (optional),
+                  headers (optional), body (optional)
+        
+        Returns:
+            AAuthRequest instance
+        """
+        return cls(
+            method=data["method"],
+            authority=data["authority"],
+            path=data.get("path", "/"),
+            query=data.get("query"),
+            headers=data.get("headers"),
+            body=data.get("body")
+        )
+    
+    @classmethod
+    def from_fastapi_request(cls, request) -> "AAuthRequest":
+        """Create AAuthRequest from FastAPI Request object.
+        
+        Args:
+            request: FastAPI Request object
+        
+        Returns:
+            AAuthRequest instance
+        
+        Note:
+            This is a convenience method. The library remains framework-agnostic.
+        """
+        try:
+            from fastapi import Request as FastAPIRequest
+            
+            if not isinstance(request, FastAPIRequest):
+                raise ValueError("Expected FastAPI Request object")
+            
+            # Extract authority from URL
+            parsed_url = urlparse(str(request.url))
+            authority = parsed_url.netloc
+            
+            # Extract query string (without leading "?")
+            query = parsed_url.query if parsed_url.query else None
+            
+            # Extract headers (FastAPI uses case-insensitive headers)
+            headers = dict(request.headers)
+            
+            # Get body if available
+            body = None
+            if hasattr(request, "_body"):
+                body = request._body
+            elif hasattr(request, "body"):
+                # For async requests, body() is a coroutine
+                # This is a limitation - users should read body separately
+                pass
+            
+            return cls(
+                method=request.method,
+                authority=authority,
+                path=parsed_url.path,
+                query=query,
+                headers=headers,
+                body=body
+            )
+        except ImportError:
+            raise ValueError("FastAPI not installed. Use from_dict() or construct directly.")
+    
+    def get_header(self, name: str, default: Optional[str] = None) -> Optional[str]:
+        """Get header value (case-insensitive).
+        
+        Args:
+            name: Header name (case-insensitive)
+            default: Default value if header not found
+        
+        Returns:
+            Header value or default
+        """
+        name_lower = name.lower()
+        for key, value in self.headers.items():
+            if key.lower() == name_lower:
+                return value
+        return default
+    
+    def __repr__(self) -> str:
+        """String representation."""
+        return (
+            f"AAuthRequest(method={self.method!r}, authority={self.authority!r}, "
+            f"path={self.path!r}, query={self.query!r})"
+        )
+

aauth/http/response.py

@@ -0,0 +1,106 @@
+"""Framework-agnostic HTTP response representation for AAuth."""
+
+from typing import Dict, Optional
+
+
+class AAuthResponse:
+    """Framework-agnostic HTTP response representation.
+    
+    This class provides a common interface for HTTP responses that AAuth
+    operations can work with, independent of the underlying framework.
+    
+    Attributes:
+        status_code: HTTP status code (200, 401, etc.)
+        headers: Response headers dictionary
+        body: Response body bytes (None if no body)
+    """
+    
+    def __init__(
+        self,
+        status_code: int,
+        headers: Optional[Dict[str, str]] = None,
+        body: Optional[bytes] = None
+    ):
+        """Initialize AAuthResponse.
+        
+        Args:
+            status_code: HTTP status code
+            headers: Response headers
+            body: Response body bytes
+        """
+        self.status_code = status_code
+        self.headers = headers or {}
+        self.body = body
+    
+    @classmethod
+    def from_dict(cls, data: Dict) -> "AAuthResponse":
+        """Create AAuthResponse from dictionary.
+        
+        Args:
+            data: Dictionary with keys: status_code, headers (optional),
+                  body (optional)
+        
+        Returns:
+            AAuthResponse instance
+        """
+        return cls(
+            status_code=data["status_code"],
+            headers=data.get("headers"),
+            body=data.get("body")
+        )
+    
+    @classmethod
+    def from_fastapi_response(cls, response) -> "AAuthResponse":
+        """Create AAuthResponse from FastAPI Response object.
+        
+        Args:
+            response: FastAPI Response object
+        
+        Returns:
+            AAuthResponse instance
+        
+        Note:
+            This is a convenience method. The library remains framework-agnostic.
+        """
+        try:
+            from fastapi.responses import Response as FastAPIResponse
+            
+            if not isinstance(response, FastAPIResponse):
+                raise ValueError("Expected FastAPI Response object")
+            
+            # Extract body if available
+            body = None
+            if hasattr(response, "body"):
+                body = response.body
+            
+            return cls(
+                status_code=response.status_code,
+                headers=dict(response.headers),
+                body=body
+            )
+        except ImportError:
+            raise ValueError("FastAPI not installed. Use from_dict() or construct directly.")
+    
+    def get_header(self, name: str, default: Optional[str] = None) -> Optional[str]:
+        """Get header value (case-insensitive).
+        
+        Args:
+            name: Header name (case-insensitive)
+            default: Default value if header not found
+        
+        Returns:
+            Header value or default
+        """
+        name_lower = name.lower()
+        for key, value in self.headers.items():
+            if key.lower() == name_lower:
+                return value
+        return default
+    
+    def __repr__(self) -> str:
+        """String representation."""
+        return (
+            f"AAuthResponse(status_code={self.status_code}, "
+            f"headers={len(self.headers)} headers)"
+        )
+

aauth/keys/__init__.py

@@ -0,0 +1,2 @@
+"""Key management and JWK operations for AAuth."""
+

aauth/keys/jwk.py

@@ -0,0 +1,123 @@
+"""JWK (JSON Web Key) operations for AAuth."""
+
+import base64
+import hashlib
+import json
+from typing import Dict, Any, Optional
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+from cryptography.hazmat.primitives import serialization
+
+
+def private_key_to_jwk(private_key: Ed25519PrivateKey, kid: Optional[str] = None) -> Dict[str, Any]:
+    """Convert Ed25519 private key to JWK format.
+    
+    Args:
+        private_key: Ed25519 private key
+        kid: Optional key ID
+        
+    Returns:
+        JWK dictionary
+    """
+    public_key = private_key.public_key()
+    return public_key_to_jwk(public_key, kid)
+
+
+def public_key_to_jwk(public_key: Ed25519PublicKey, kid: Optional[str] = None) -> Dict[str, Any]:
+    """Convert Ed25519 public key to JWK format.
+    
+    Args:
+        public_key: Ed25519 public key
+        kid: Optional key ID
+        
+    Returns:
+        JWK dictionary
+    """
+    public_bytes = public_key.public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw
+    )
+    
+    # Ed25519 public key is 32 bytes, encode as base64url
+    x = base64.urlsafe_b64encode(public_bytes).decode('utf-8').rstrip('=')
+    
+    jwk = {
+        "kty": "OKP",
+        "crv": "Ed25519",
+        "x": x
+    }
+    
+    if kid:
+        jwk["kid"] = kid
+    
+    return jwk
+
+
+def jwk_to_public_key(jwk: Dict[str, Any]) -> Ed25519PublicKey:
+    """Convert JWK to Ed25519PublicKey object.
+    
+    Args:
+        jwk: JWK dictionary with kty="OKP", crv="Ed25519"
+        
+    Returns:
+        Ed25519PublicKey object
+        
+    Raises:
+        ValueError: If JWK is not Ed25519 format
+    """
+    if jwk.get("kty") != "OKP" or jwk.get("crv") != "Ed25519":
+        raise ValueError("JWK must be Ed25519 (OKP, Ed25519)")
+    
+    x = jwk["x"]
+    # Add padding if needed
+    x += '=' * (4 - len(x) % 4)
+    public_bytes = base64.urlsafe_b64decode(x)
+    
+    return Ed25519PublicKey.from_public_bytes(public_bytes)
+
+
+def calculate_jwk_thumbprint(jwk: Dict[str, Any]) -> str:
+    """Calculate JWK Thumbprint per RFC 7638.
+    
+    Args:
+        jwk: JWK dictionary (must be canonical - only include required fields)
+        
+    Returns:
+        Base64url-encoded SHA-256 hash of canonical JWK JSON
+    """
+    # Create canonical JWK (only include required fields, sorted)
+    # For Ed25519: kty, crv, x (kid excluded from thumbprint)
+    canonical_jwk = {}
+    
+    # Required fields in order
+    if "kty" in jwk:
+        canonical_jwk["kty"] = jwk["kty"]
+    if "crv" in jwk:
+        canonical_jwk["crv"] = jwk["crv"]
+    if "x" in jwk:
+        canonical_jwk["x"] = jwk["x"]
+    
+    # Convert to canonical JSON (no spaces, sorted keys)
+    canonical_json = json.dumps(canonical_jwk, separators=(',', ':'), sort_keys=True)
+    
+    # SHA-256 hash
+    hash_bytes = hashlib.sha256(canonical_json.encode('utf-8')).digest()
+    
+    # Base64url encode (no padding)
+    thumbprint = base64.urlsafe_b64encode(hash_bytes).decode('utf-8').rstrip('=')
+    
+    return thumbprint
+
+
+def generate_jwks(keys: list[Dict[str, Any]]) -> Dict[str, Any]:
+    """Generate a JWKS document from a list of JWKs.
+    
+    Args:
+        keys: List of JWK dictionaries
+        
+    Returns:
+        JWKS document dictionary
+    """
+    return {
+        "keys": keys
+    }
+

aauth/keys/jwks.py

@@ -0,0 +1,191 @@
+"""JWKS fetching and caching for AAuth."""
+
+import time
+from typing import Dict, Any, Optional, Callable, Protocol
+from ..errors import JWKSError
+
+
+class HTTPClient(Protocol):
+    """Protocol for HTTP client implementations."""
+    
+    async def fetch_json(self, url: str) -> Dict[str, Any]:
+        """Fetch JSON from URL.
+        
+        Args:
+            url: URL to fetch
+            
+        Returns:
+            Parsed JSON dictionary
+            
+        Raises:
+            Exception: If fetch fails
+        """
+        ...
+
+
+class DefaultHTTPClient:
+    """Default httpx-based HTTP client."""
+    
+    async def fetch_json(self, url: str) -> Dict[str, Any]:
+        """Fetch JSON using httpx."""
+        try:
+            import httpx
+            async with httpx.AsyncClient() as client:
+                response = await client.get(url, timeout=10.0)
+                response.raise_for_status()
+                return response.json()
+        except ImportError:
+            raise JWKSError("httpx not installed. Install it or provide custom HTTP client.")
+        except Exception as e:
+            raise JWKSError(f"Failed to fetch JWKS from {url}: {e}", jwks_uri=url)
+
+
+class JWKSCache:
+    """Simple in-memory cache for JWKS documents."""
+    
+    def __init__(self, ttl: int = 3600):
+        """Initialize cache.
+        
+        Args:
+            ttl: Time-to-live in seconds (default: 1 hour)
+        """
+        self._cache: Dict[str, tuple[Dict[str, Any], float]] = {}
+        self._ttl = ttl
+    
+    def get(self, url: str) -> Optional[Dict[str, Any]]:
+        """Get cached JWKS if still valid.
+        
+        Args:
+            url: JWKS URL
+            
+        Returns:
+            Cached JWKS or None if expired/not found
+        """
+        if url not in self._cache:
+            return None
+        
+        jwks, cached_at = self._cache[url]
+        if time.time() - cached_at > self._ttl:
+            del self._cache[url]
+            return None
+        
+        return jwks
+    
+    def set(self, url: str, jwks: Dict[str, Any]) -> None:
+        """Cache JWKS.
+        
+        Args:
+            url: JWKS URL
+            jwks: JWKS document
+        """
+        self._cache[url] = (jwks, time.time())
+    
+    def clear(self) -> None:
+        """Clear all cached entries."""
+        self._cache.clear()
+
+
+class JWKSFetcher:
+    """JWKS fetcher with caching support."""
+    
+    def __init__(
+        self,
+        http_client: Optional[HTTPClient] = None,
+        cache: Optional[JWKSCache] = None,
+        cache_ttl: int = 3600
+    ):
+        """Initialize JWKS fetcher.
+        
+        Args:
+            http_client: HTTP client implementation (default: DefaultHTTPClient)
+            cache: Cache implementation (default: JWKSCache with specified TTL)
+            cache_ttl: Cache TTL in seconds (used if cache not provided)
+        """
+        self._http_client = http_client or DefaultHTTPClient()
+        self._cache = cache or JWKSCache(ttl=cache_ttl)
+    
+    async def fetch(
+        self,
+        identifier: str,
+        kid: Optional[str] = None,
+        well_known: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Fetch JWKS for an identifier.
+        
+        Args:
+            identifier: Agent/resource/auth server identifier (HTTPS URL)
+            kid: Optional key ID (for cache key)
+            well_known: Optional well-known metadata document name
+        
+        Returns:
+            JWKS document dictionary
+            
+        Raises:
+            JWKSError: If fetch fails
+        """
+        # Determine JWKS URL
+        if well_known:
+            # Fetch metadata first, then extract jwks_uri
+            metadata_url = f"{identifier}/.well-known/{well_known}"
+            try:
+                metadata = await self._http_client.fetch_json(metadata_url)
+                jwks_uri = metadata.get("jwks_uri")
+                if not jwks_uri:
+                    raise JWKSError(
+                        f"No jwks_uri in metadata from {metadata_url}",
+                        jwks_uri=metadata_url
+                    )
+            except Exception as e:
+                raise JWKSError(
+                    f"Failed to fetch metadata from {metadata_url}: {e}",
+                    jwks_uri=metadata_url
+                )
+        else:
+            # Assume identifier is JWKS URL or can be fetched directly
+            jwks_uri = identifier
+        
+        # Check cache
+        cache_key = f"{jwks_uri}:{kid}" if kid else jwks_uri
+        cached = self._cache.get(cache_key)
+        if cached:
+            return cached
+        
+        # Fetch JWKS
+        try:
+            jwks = await self._http_client.fetch_json(jwks_uri)
+            
+            # Validate JWKS structure
+            if not isinstance(jwks, dict) or "keys" not in jwks:
+                raise JWKSError(
+                    f"Invalid JWKS structure from {jwks_uri}",
+                    jwks_uri=jwks_uri
+                )
+            
+            # Cache it
+            self._cache.set(cache_key, jwks)
+            
+            return jwks
+        except JWKSError:
+            raise
+        except Exception as e:
+            raise JWKSError(
+                f"Failed to fetch JWKS from {jwks_uri}: {e}",
+                jwks_uri=jwks_uri
+            )
+    
+    def get_key_by_kid(self, jwks: Dict[str, Any], kid: str) -> Optional[Dict[str, Any]]:
+        """Get key from JWKS by kid.
+        
+        Args:
+            jwks: JWKS document
+            kid: Key ID
+            
+        Returns:
+            JWK dictionary or None if not found
+        """
+        keys = jwks.get("keys", [])
+        for key in keys:
+            if key.get("kid") == kid:
+                return key
+        return None
+

aauth/keys/keypair.py

@@ -0,0 +1,16 @@
+"""Key pair generation for AAuth."""
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+from typing import Tuple
+
+
+def generate_ed25519_keypair() -> Tuple[Ed25519PrivateKey, Ed25519PublicKey]:
+    """Generate a new Ed25519 key pair.
+    
+    Returns:
+        Tuple of (private_key, public_key)
+    """
+    private_key = Ed25519PrivateKey.generate()
+    public_key = private_key.public_key()
+    return private_key, public_key
+

aauth/metadata/__init__.py

@@ -0,0 +1,2 @@
+"""Metadata discovery for AAuth."""
+