aauth 0.1.0__py3-none-any.whl

aauth/metadata/agent.py

@@ -0,0 +1,20 @@
+"""Agent metadata handling for AAuth."""
+
+from typing import Dict, Any
+
+
+def generate_agent_metadata(agent_id: str, jwks_uri: str) -> Dict[str, Any]:
+    """Generate agent metadata JSON per AAuth spec Section 8.1.
+    
+    Args:
+        agent_id: Agent identifier (HTTPS URL)
+        jwks_uri: URL to agent's JSON Web Key Set
+        
+    Returns:
+        Agent metadata dictionary with required fields
+    """
+    return {
+        "agent": agent_id,
+        "jwks_uri": jwks_uri
+    }
+

aauth/metadata/auth_server.py

@@ -0,0 +1,114 @@
+"""Auth server metadata handling for AAuth."""
+
+from typing import Dict, Any, Optional
+
+
+def generate_auth_metadata(
+    auth_id: str,
+    jwks_uri: str,
+    token_endpoint: str,
+    auth_endpoint: str,
+    signing_algs_supported: Optional[list[str]] = None,
+    request_types_supported: Optional[list[str]] = None,
+    scopes_supported: Optional[list[str]] = None
+) -> Dict[str, Any]:
+    """Generate auth server metadata JSON per AAuth spec Section 8.2.
+    
+    Args:
+        auth_id: Auth server identifier (HTTPS URL)
+        jwks_uri: URL to auth server's JSON Web Key Set
+        token_endpoint: Endpoint for auth requests, code exchange, token exchange, and refresh
+        auth_endpoint: Endpoint for user authentication and consent flow
+        signing_algs_supported: Optional list of supported HTTPSig algorithms
+        request_types_supported: Optional list of supported request_type values
+        scopes_supported: Optional list of supported scopes
+        
+    Returns:
+        Auth server metadata dictionary with required fields
+    """
+    metadata = {
+        "issuer": auth_id,
+        "jwks_uri": jwks_uri,
+        "agent_token_endpoint": token_endpoint,
+        "agent_auth_endpoint": auth_endpoint
+    }
+    
+    if signing_algs_supported:
+        metadata["agent_signing_algs_supported"] = signing_algs_supported
+    else:
+        # Default to Ed25519
+        metadata["agent_signing_algs_supported"] = ["ed25519"]
+    
+    if request_types_supported:
+        metadata["request_types_supported"] = request_types_supported
+    else:
+        # Default to auth, code, exchange, refresh
+        metadata["request_types_supported"] = ["auth", "code", "exchange", "refresh"]
+    
+    if scopes_supported:
+        metadata["scopes_supported"] = scopes_supported
+    
+    return metadata
+
+
+def fetch_metadata(url: str) -> Dict[str, Any]:
+    """Fetch metadata document from URL via HTTPS (sync version for backward compatibility).
+    
+    Args:
+        url: HTTPS URL to metadata document (HTTP allowed for localhost development)
+        
+    Returns:
+        Parsed metadata dictionary
+        
+    Raises:
+        ValueError: If URL is not HTTPS (except localhost for development)
+        MetadataError: If HTTP request fails
+    """
+    import httpx
+    from ..errors import MetadataError
+    
+    # Verify HTTPS (allow HTTP for localhost development)
+    if not url.startswith("https://"):
+        # Allow HTTP for localhost/127.0.0.1 for development
+        parsed = httpx.URL(url)
+        if parsed.host not in ("localhost", "127.0.0.1", "::1"):
+            raise ValueError(f"Metadata URL must use HTTPS (except localhost): {url}")
+    
+    # Fetch metadata
+    try:
+        response = httpx.get(url, timeout=10.0)
+        response.raise_for_status()
+        return response.json()
+    except Exception as e:
+        raise MetadataError(
+            f"Failed to fetch metadata from {url}: {e}",
+            metadata_url=url
+        ) from e
+
+
+async def fetch_auth_metadata(url: str, http_client=None) -> Dict[str, Any]:
+    """Fetch auth server metadata from URL (async version).
+    
+    Args:
+        url: URL to auth server metadata document (e.g., https://auth.example/.well-known/aauth-issuer)
+        http_client: Optional HTTP client (default: uses DefaultHTTPClient from keys.jwks)
+        
+    Returns:
+        Parsed auth server metadata dictionary
+        
+    Raises:
+        MetadataError: If fetch fails
+    """
+    from ..keys.jwks import DefaultHTTPClient
+    from ..errors import MetadataError
+    
+    client = http_client or DefaultHTTPClient()
+    
+    try:
+        return await client.fetch_json(url)
+    except Exception as e:
+        raise MetadataError(
+            f"Failed to fetch auth server metadata from {url}: {e}",
+            metadata_url=url
+        )
+

aauth/metadata/resource.py

@@ -0,0 +1,42 @@
+"""Resource metadata handling for AAuth."""
+
+from typing import Dict, Any, Optional
+
+
+def generate_resource_metadata(
+    resource_id: str,
+    jwks_uri: str,
+    resource_token_endpoint: str,
+    supported_scopes: Optional[list[str]] = None,
+    scope_descriptions: Optional[Dict[str, str]] = None
+) -> Dict[str, Any]:
+    """Generate resource metadata JSON per AAuth spec Section 8.3.
+    
+    Args:
+        resource_id: Resource identifier (HTTPS URL)
+        jwks_uri: URL to resource's JSON Web Key Set (REQUIRED)
+        resource_token_endpoint: Endpoint where agents request resource tokens (REQUIRED per spec)
+        supported_scopes: Optional list of supported scope values
+        scope_descriptions: Optional dictionary mapping scope names to descriptions
+        
+    Returns:
+        Resource metadata dictionary with required fields
+        
+    Note:
+        Per SPEC.md Section 8.3, resource_token_endpoint is REQUIRED.
+        auth_server is NOT in resource metadata - it's only provided in Agent-Auth challenge headers.
+    """
+    metadata = {
+        "resource": resource_id,
+        "jwks_uri": jwks_uri,
+        "resource_token_endpoint": resource_token_endpoint
+    }
+    
+    if supported_scopes:
+        metadata["supported_scopes"] = supported_scopes
+    
+    if scope_descriptions:
+        metadata["scope_descriptions"] = scope_descriptions
+    
+    return metadata
+

aauth/resource/__init__.py

@@ -0,0 +1,2 @@
+"""Resource role implementation for AAuth."""
+

aauth/resource/challenge_builder.py

@@ -0,0 +1,87 @@
+"""Agent-Auth challenge building for resource role."""
+
+from typing import Optional, List
+from ..headers.agent_auth import build_agent_auth_challenge
+from ..tokens.resource_token import create_resource_token
+from ..keys.jwk import calculate_jwk_thumbprint, public_key_to_jwk
+from ..errors import ChallengeError
+
+
+class ChallengeBuilder:
+    """Builds Agent-Auth challenges for resources."""
+    
+    def __init__(
+        self,
+        resource_id: str,
+        resource_private_key,
+        resource_kid: str,
+        auth_server: str
+    ):
+        """Initialize challenge builder.
+        
+        Args:
+            resource_id: Resource identifier (HTTPS URL)
+            resource_private_key: Resource's private key for signing resource tokens
+            resource_kid: Resource's key ID
+            auth_server: Auth server identifier (HTTPS URL)
+        """
+        self.resource_id = resource_id
+        self.resource_private_key = resource_private_key
+        self.resource_kid = resource_kid
+        self.auth_server = auth_server
+    
+    def build_challenge(
+        self,
+        require_signature: bool = True,
+        require_identity: bool = False,
+        require_auth_token: bool = False,
+        agent_id: Optional[str] = None,
+        agent_public_key=None,
+        scope: Optional[str] = None
+    ) -> str:
+        """Build Agent-Auth challenge header.
+        
+        Args:
+            require_signature: Require HTTP signature
+            require_identity: Require agent identity
+            require_auth_token: Require authorization token
+            agent_id: Agent identifier (for resource token)
+            agent_public_key: Agent's public key (for resource token)
+            scope: Required scope (for resource token)
+        
+        Returns:
+            Agent-Auth header value
+        
+        Raises:
+            ChallengeError: If challenge cannot be built
+        """
+        resource_token = None
+        
+        if require_auth_token:
+            if not agent_id or not agent_public_key or not scope:
+                raise ChallengeError(
+                    "agent_id, agent_public_key, and scope required for auth-token challenge"
+                )
+            
+            # Create resource token
+            agent_jwk = public_key_to_jwk(agent_public_key)
+            agent_jkt = calculate_jwk_thumbprint(agent_jwk)
+            
+            resource_token = create_resource_token(
+                iss=self.resource_id,
+                aud=self.auth_server,
+                agent=agent_id,
+                agent_jkt=agent_jkt,
+                scope=scope,
+                private_key=self.resource_private_key,
+                kid=self.resource_kid
+            )
+        
+        return build_agent_auth_challenge(
+            require_signature=require_signature,
+            require_identity=require_identity,
+            require_auth_token=require_auth_token,
+            resource_token=resource_token,
+            auth_server=self.auth_server if require_auth_token else None
+        )
+

aauth/resource/token_issuer.py

@@ -0,0 +1,74 @@
+"""Resource token issuance for resource role."""
+
+from typing import Optional
+from ..tokens.resource_token import create_resource_token
+from ..keys.jwk import calculate_jwk_thumbprint, public_key_to_jwk
+from ..errors import TokenError
+
+
+class ResourceTokenIssuer:
+    """Issues resource tokens for agents."""
+    
+    def __init__(
+        self,
+        resource_id: str,
+        resource_private_key,
+        resource_kid: str,
+        auth_server: str
+    ):
+        """Initialize resource token issuer.
+        
+        Args:
+            resource_id: Resource identifier (HTTPS URL)
+            resource_private_key: Resource's private key for signing
+            resource_kid: Resource's key ID
+            auth_server: Auth server identifier (HTTPS URL)
+        """
+        self.resource_id = resource_id
+        self.resource_private_key = resource_private_key
+        self.resource_kid = resource_kid
+        self.auth_server = auth_server
+    
+    def issue_token(
+        self,
+        agent_id: str,
+        agent_public_key,
+        scope: str,
+        exp: Optional[int] = None
+    ) -> str:
+        """Issue a resource token.
+        
+        Args:
+            agent_id: Agent identifier (HTTPS URL)
+            agent_public_key: Agent's public signing key
+            scope: Space-separated scope values
+            exp: Optional expiration timestamp
+        
+        Returns:
+            Resource token (JWT string)
+        
+        Raises:
+            TokenError: If token creation fails
+        """
+        try:
+            # Calculate agent JWK thumbprint
+            agent_jwk = public_key_to_jwk(agent_public_key)
+            agent_jkt = calculate_jwk_thumbprint(agent_jwk)
+            
+            # Create resource token
+            return create_resource_token(
+                iss=self.resource_id,
+                aud=self.auth_server,
+                agent=agent_id,
+                agent_jkt=agent_jkt,
+                scope=scope,
+                private_key=self.resource_private_key,
+                kid=self.resource_kid,
+                exp=exp
+            )
+        except Exception as e:
+            raise TokenError(
+                f"Failed to issue resource token: {e}",
+                token_type="resource+jwt"
+            ) from e
+

aauth/resource/verifier.py

@@ -0,0 +1,170 @@
+"""Request verification for resource role."""
+
+from typing import Dict, Any, Optional, List, Callable
+from ..signing.verifier import verify_signature
+from ..headers.signature_key import parse_signature_key
+from ..headers.signature_input import parse_signature_input
+from ..errors import SignatureError
+
+
+class RequestVerifier:
+    """Verifies incoming requests for resources."""
+    
+    def __init__(
+        self,
+        canonical_authorities: List[str],
+        jwks_fetcher: Optional[Callable] = None,
+        trusted_auth_servers: Optional[List[str]] = None
+    ):
+        """Initialize request verifier.
+        
+        Args:
+            canonical_authorities: List of canonical authorities (host:port) per SPEC 10.3.1
+            jwks_fetcher: Optional JWKS fetcher function
+            trusted_auth_servers: Optional list of trusted auth server identifiers
+        """
+        self.canonical_authorities = canonical_authorities
+        self.jwks_fetcher = jwks_fetcher
+        self.trusted_auth_servers = trusted_auth_servers or []
+    
+    def verify_request(
+        self,
+        method: str,
+        target_uri: str,
+        headers: Dict[str, str],
+        body: Optional[bytes],
+        require_identity: bool = False,
+        require_auth_token: bool = False
+    ) -> Dict[str, Any]:
+        """Verify incoming request.
+        
+        Args:
+            method: HTTP method
+            target_uri: Target URI
+            headers: Request headers
+            body: Request body bytes
+            require_identity: Whether agent identity is required
+            require_auth_token: Whether auth token is required
+            
+        Returns:
+            Dictionary with verification result:
+            - valid: bool
+            - agent_id: Optional[str]
+            - agent_delegate: Optional[str]
+            - user_sub: Optional[str]
+            - scopes: Optional[List[str]]
+            - error: Optional[str]
+            
+        Raises:
+            SignatureError: If verification fails due to invalid format
+        """
+        # Extract signature headers
+        signature_input_header = headers.get("signature-input") or headers.get("Signature-Input")
+        signature_header = headers.get("signature") or headers.get("Signature")
+        signature_key_header = headers.get("signature-key") or headers.get("Signature-Key")
+        
+        if not (signature_input_header and signature_header and signature_key_header):
+            return {
+                "valid": False,
+                "error": "Missing signature headers"
+            }
+        
+        # Parse Signature-Key to determine scheme
+        try:
+            parsed_key = parse_signature_key(signature_key_header)
+            scheme = parsed_key["scheme"]
+        except Exception as e:
+            return {
+                "valid": False,
+                "error": f"Invalid Signature-Key: {e}"
+            }
+        
+        # Check canonical authority
+        from urllib.parse import urlparse
+        parsed_uri = urlparse(target_uri)
+        request_authority = parsed_uri.netloc
+        
+        if request_authority not in self.canonical_authorities:
+            return {
+                "valid": False,
+                "error": f"Request authority {request_authority} not in canonical authorities"
+            }
+        
+        # Verify signature
+        try:
+            is_valid = verify_signature(
+                method=method,
+                target_uri=target_uri,
+                headers=headers,
+                body=body,
+                signature_input_header=signature_input_header,
+                signature_header=signature_header,
+                signature_key_header=signature_key_header,
+                jwks_fetcher=self.jwks_fetcher
+            )
+            
+            if not is_valid:
+                return {
+                    "valid": False,
+                    "error": "Signature verification failed"
+                }
+        except SignatureError as e:
+            return {
+                "valid": False,
+                "error": str(e)
+            }
+        
+        # Extract identity/authorization info based on scheme
+        result = {
+            "valid": True,
+            "agent_id": None,
+            "agent_delegate": None,
+            "user_sub": None,
+            "scopes": None
+        }
+        
+        if scheme == "jwks":
+            # Extract agent ID from Signature-Key
+            params = parsed_key["params"]
+            result["agent_id"] = params.get("id")
+        
+        elif scheme == "jwt":
+            # Extract from JWT token
+            jwt_token = parsed_key["params"].get("jwt")
+            if jwt_token:
+                try:
+                    import jwt as pyjwt
+                    payload = pyjwt.decode(jwt_token, options={"verify_signature": False})
+                    
+                    # Determine token type
+                    header = pyjwt.get_unverified_header(jwt_token)
+                    typ = header.get("typ")
+                    
+                    if typ == "agent+jwt":
+                        result["agent_id"] = payload.get("iss")
+                        result["agent_delegate"] = payload.get("sub")
+                    elif typ == "auth+jwt":
+                        result["agent_id"] = payload.get("agent")
+                        result["agent_delegate"] = payload.get("agent_delegate")
+                        result["user_sub"] = payload.get("sub")
+                        scope_str = payload.get("scope")
+                        if scope_str:
+                            result["scopes"] = scope_str.split()
+                except Exception:
+                    pass
+        
+        # Check requirements
+        if require_identity and not result["agent_id"]:
+            return {
+                "valid": False,
+                "error": "Agent identity required but not present"
+            }
+        
+        if require_auth_token and not result.get("scopes"):
+            return {
+                "valid": False,
+                "error": "Auth token required but not present"
+            }
+        
+        return result
+

aauth/signing/__init__.py

@@ -0,0 +1,2 @@
+"""HTTP Message Signing (RFC 9421) for AAuth."""
+

aauth/signing/algorithms.py

@@ -0,0 +1,35 @@
+"""Signature algorithm support for AAuth."""
+
+# Supported algorithms per AAuth spec Section 10.2
+# MUST support ed25519, MAY support others
+
+ED25519 = "ed25519"
+RSA_PSS_SHA512 = "rsa-pss-sha512"
+RSA_PSS_SHA256 = "rsa-pss-sha256"
+ECDSA_P256_SHA256 = "ecdsa-p256-sha256"
+ECDSA_P384_SHA384 = "ecdsa-p384-sha384"
+
+# Required algorithm
+REQUIRED_ALGORITHM = ED25519
+
+# All supported algorithms
+SUPPORTED_ALGORITHMS = [
+    ED25519,
+    RSA_PSS_SHA512,
+    RSA_PSS_SHA256,
+    ECDSA_P256_SHA256,
+    ECDSA_P384_SHA384,
+]
+
+
+def is_supported(algorithm: str) -> bool:
+    """Check if algorithm is supported.
+    
+    Args:
+        algorithm: Algorithm name
+        
+    Returns:
+        True if supported, False otherwise
+    """
+    return algorithm.lower() in [alg.lower() for alg in SUPPORTED_ALGORITHMS]
+