aauth 0.1.0__py3-none-any.whl

aauth/__init__.py

@@ -0,0 +1,137 @@
+"""AAuth - Agent Authentication Protocol implementation for Python."""
+
+__version__ = "0.1.0"
+
+# Errors
+from .errors import (
+    AAuthError,
+    SignatureError,
+    TokenError,
+    ChallengeError,
+    MetadataError,
+    JWKSError
+)
+
+# HTTP abstraction
+from .http.request import AAuthRequest
+from .http.response import AAuthResponse
+
+# Key management
+from .keys.keypair import generate_ed25519_keypair
+from .keys.jwk import (
+    public_key_to_jwk,
+    jwk_to_public_key,
+    calculate_jwk_thumbprint,
+    generate_jwks
+)
+from .keys.jwks import JWKSFetcher, JWKSCache, DefaultHTTPClient
+
+# HTTP Message Signing
+from .signing.signer import sign_request
+from .signing.verifier import verify_signature
+from .signing.algorithms import (
+    ED25519,
+    RSA_PSS_SHA512,
+    RSA_PSS_SHA256,
+    ECDSA_P256_SHA256,
+    ECDSA_P384_SHA384,
+    SUPPORTED_ALGORITHMS,
+    is_supported
+)
+
+# Token handling
+from .tokens.agent_token import create_agent_token, verify_agent_token
+from .tokens.auth_token import create_auth_token, parse_token_claims, verify_token
+from .tokens.resource_token import create_resource_token
+
+# Header handling
+from .headers.signature_key import build_signature_key_header, parse_signature_key
+from .headers.signature_input import build_signature_input_header, parse_signature_input
+from .headers.signature import build_signature_header, parse_signature
+from .headers.agent_auth import parse_agent_auth_header, build_agent_auth_challenge
+
+# Metadata
+from .metadata.agent import generate_agent_metadata
+from .metadata.resource import generate_resource_metadata
+from .metadata.auth_server import generate_auth_metadata, fetch_auth_metadata, fetch_metadata
+
+# Agent role
+from .agent.signer import AgentRequestSigner
+from .agent.challenge_handler import ChallengeHandler
+
+# Resource role
+from .resource.verifier import RequestVerifier
+from .resource.challenge_builder import ChallengeBuilder
+from .resource.token_issuer import ResourceTokenIssuer
+
+__all__ = [
+    # Version
+    "__version__",
+    
+    # Errors
+    "AAuthError",
+    "SignatureError",
+    "TokenError",
+    "ChallengeError",
+    "MetadataError",
+    "JWKSError",
+    
+    # HTTP abstraction
+    "AAuthRequest",
+    "AAuthResponse",
+    
+    # Key management
+    "generate_ed25519_keypair",
+    "public_key_to_jwk",
+    "jwk_to_public_key",
+    "calculate_jwk_thumbprint",
+    "generate_jwks",
+    "JWKSFetcher",
+    "JWKSCache",
+    "DefaultHTTPClient",
+    
+    # HTTP Message Signing
+    "sign_request",
+    "verify_signature",
+    "ED25519",
+    "RSA_PSS_SHA512",
+    "RSA_PSS_SHA256",
+    "ECDSA_P256_SHA256",
+    "ECDSA_P384_SHA384",
+    "SUPPORTED_ALGORITHMS",
+    "is_supported",
+    
+    # Token handling
+    "create_agent_token",
+    "verify_agent_token",
+    "create_auth_token",
+    "parse_token_claims",
+    "verify_token",
+    "create_resource_token",
+    
+    # Header handling
+    "build_signature_key_header",
+    "parse_signature_key",
+    "build_signature_input_header",
+    "parse_signature_input",
+    "build_signature_header",
+    "parse_signature",
+    "parse_agent_auth_header",
+    "build_agent_auth_challenge",
+    
+    # Metadata
+    "generate_agent_metadata",
+    "generate_resource_metadata",
+    "generate_auth_metadata",
+    "fetch_auth_metadata",
+    "fetch_metadata",
+    
+    # Agent role
+    "AgentRequestSigner",
+    "ChallengeHandler",
+    
+    # Resource role
+    "RequestVerifier",
+    "ChallengeBuilder",
+    "ResourceTokenIssuer",
+]

aauth/agent/__init__.py

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

aauth/agent/challenge_handler.py

@@ -0,0 +1,61 @@
+"""Agent-Auth challenge handling for agent role."""
+
+from typing import Dict, Any, Optional
+from ..headers.agent_auth import parse_agent_auth_header
+from ..errors import ChallengeError
+
+
+class ChallengeHandler:
+    """Handles Agent-Auth challenges from resources."""
+    
+    def parse_challenge(self, agent_auth_header: str) -> Dict[str, Any]:
+        """Parse Agent-Auth challenge header.
+        
+        Args:
+            agent_auth_header: Agent-Auth header value
+            
+        Returns:
+            Parsed challenge parameters
+            
+        Raises:
+            ChallengeError: If parsing fails
+        """
+        return parse_agent_auth_header(agent_auth_header)
+    
+    def determine_response_scheme(
+        self,
+        challenge: Dict[str, Any],
+        has_agent_token: bool = False,
+        has_auth_token: bool = False
+    ) -> str:
+        """Determine which signature scheme to use in response to challenge.
+        
+        Args:
+            challenge: Parsed challenge parameters
+            has_agent_token: Whether agent has an agent token
+            has_auth_token: Whether agent has an auth token
+            
+        Returns:
+            Signature scheme to use ("hwk", "jwks", or "jwt")
+            
+        Raises:
+            ChallengeError: If challenge cannot be satisfied
+        """
+        if challenge.get("auth_token"):
+            if has_auth_token:
+                return "jwt"
+            else:
+                raise ChallengeError(
+                    "Challenge requires auth token but agent doesn't have one",
+                    challenge_type="auth-token"
+                )
+        
+        if challenge.get("identity"):
+            if has_agent_token:
+                return "jwt"  # Use agent token
+            else:
+                return "jwks"  # Use agent server identity
+        
+        # Just signature required
+        return "hwk"
+

aauth/agent/signer.py

@@ -0,0 +1,78 @@
+"""High-level request signing for agent role."""
+
+from typing import Dict, Any, Optional
+from urllib.parse import urlparse
+from ..signing.signer import sign_request
+from ..headers.signature_key import build_signature_key_header
+from ..errors import SignatureError
+
+
+class AgentRequestSigner:
+    """High-level request signer for agents."""
+    
+    def __init__(
+        self,
+        private_key,
+        agent_id: Optional[str] = None,
+        agent_token: Optional[str] = None,
+        kid: str = "key-1"
+    ):
+        """Initialize agent request signer.
+        
+        Args:
+            private_key: Agent's private signing key
+            agent_id: Agent identifier (HTTPS URL) - required for jwks scheme
+            agent_token: Agent token (JWT) - required for jwt scheme
+            kid: Key ID for jwks scheme
+        """
+        self.private_key = private_key
+        self.agent_id = agent_id
+        self.agent_token = agent_token
+        self.kid = kid
+    
+    def sign_request(
+        self,
+        method: str,
+        target_uri: str,
+        headers: Dict[str, str],
+        body: Optional[bytes] = None,
+        sig_scheme: str = "hwk"
+    ) -> Dict[str, str]:
+        """Sign an HTTP request.
+        
+        Args:
+            method: HTTP method
+            target_uri: Target URI
+            headers: Request headers (will be modified)
+            body: Request body bytes
+            sig_scheme: Signature scheme ("hwk", "jwks", or "jwt")
+        
+        Returns:
+            Dictionary with signature headers
+        
+        Raises:
+            SignatureError: If signing fails
+        """
+        kwargs = {}
+        
+        if sig_scheme == "jwks":
+            if not self.agent_id:
+                raise SignatureError("agent_id required for jwks scheme")
+            kwargs["id"] = self.agent_id
+            kwargs["kid"] = self.kid
+        
+        elif sig_scheme == "jwt":
+            if not self.agent_token:
+                raise SignatureError("agent_token required for jwt scheme")
+            kwargs["jwt"] = self.agent_token
+        
+        return sign_request(
+            method=method,
+            target_uri=target_uri,
+            headers=headers,
+            body=body,
+            private_key=self.private_key,
+            sig_scheme=sig_scheme,
+            **kwargs
+        )
+

aauth/errors.py

@@ -0,0 +1,51 @@
+"""Custom exceptions for AAuth."""
+
+
+class AAuthError(Exception):
+    """Base exception for all AAuth errors."""
+    pass
+
+
+class SignatureError(AAuthError):
+    """HTTP signature validation or creation error."""
+    
+    def __init__(self, message: str, details: dict = None):
+        super().__init__(message)
+        self.details = details or {}
+
+
+class TokenError(AAuthError):
+    """Token validation or creation error."""
+    
+    def __init__(self, message: str, token_type: str = None, details: dict = None):
+        super().__init__(message)
+        self.token_type = token_type
+        self.details = details or {}
+
+
+class ChallengeError(AAuthError):
+    """Agent-Auth challenge parsing or building error."""
+    
+    def __init__(self, message: str, challenge_type: str = None, details: dict = None):
+        super().__init__(message)
+        self.challenge_type = challenge_type
+        self.details = details or {}
+
+
+class MetadataError(AAuthError):
+    """Metadata discovery or parsing error."""
+    
+    def __init__(self, message: str, metadata_url: str = None, details: dict = None):
+        super().__init__(message)
+        self.metadata_url = metadata_url
+        self.details = details or {}
+
+
+class JWKSError(AAuthError):
+    """JWKS fetching or parsing error."""
+    
+    def __init__(self, message: str, jwks_uri: str = None, details: dict = None):
+        super().__init__(message)
+        self.jwks_uri = jwks_uri
+        self.details = details or {}
+

aauth/headers/__init__.py

@@ -0,0 +1,2 @@
+"""HTTP header parsing and building for AAuth."""
+

aauth/headers/agent_auth.py

@@ -0,0 +1,146 @@
+"""Agent-Auth header parsing and building for AAuth."""
+
+import re
+from typing import Dict, Any, Optional, List
+from ..errors import ChallengeError
+
+
+def parse_agent_auth_header(header_value: str) -> Dict[str, Any]:
+    """Parse Agent-Auth header per AAuth spec Section 4.
+    
+    Agent-Auth header uses RFC 8941 structured fields format:
+    - httpsig (required)
+    - identity=?1 (optional boolean)
+    - auth-token (optional bare token)
+    - resource_token="..." (optional string)
+    - auth_server="..." (optional string)
+    - user_interaction="..." (optional string)
+    - algs=("ed25519" "rsa-pss-sha512") (optional inner list)
+    
+    Args:
+        header_value: Agent-Auth header value
+        
+    Returns:
+        Dictionary with parsed parameters:
+        - httpsig: bool (always True)
+        - identity: Optional[bool]
+        - auth_token: Optional[bool]
+        - resource_token: Optional[str]
+        - auth_server: Optional[str]
+        - user_interaction: Optional[str]
+        - algs: Optional[List[str]]
+        
+    Raises:
+        ChallengeError: If header format is invalid
+    """
+    try:
+        result = {
+            "httpsig": True,
+            "identity": None,
+            "auth_token": False,
+            "resource_token": None,
+            "auth_server": None,
+            "user_interaction": None,
+            "algs": None
+        }
+        
+        # Parse structured fields format
+        # Basic format: httpsig; identity=?1; auth-token; resource_token="..."; auth_server="..."
+        
+        # Check for httpsig (required)
+        if "httpsig" not in header_value:
+            raise ChallengeError("Agent-Auth header must include 'httpsig'")
+        
+        # Parse identity parameter (?1 = true)
+        if "identity=?1" in header_value or "identity=?1;" in header_value:
+            result["identity"] = True
+        elif "identity=" in header_value:
+            # Could be ?0 or other value
+            match = re.search(r'identity=(\?[01])', header_value)
+            if match:
+                result["identity"] = match.group(1) == "?1"
+        
+        # Parse auth-token (bare token, no value)
+        if re.search(r'\bauth-token\b', header_value):
+            result["auth_token"] = True
+        
+        # Parse resource_token="..."
+        resource_token_match = re.search(r'resource_token="([^"]+)"', header_value)
+        if resource_token_match:
+            result["resource_token"] = resource_token_match.group(1)
+        
+        # Parse auth_server="..."
+        auth_server_match = re.search(r'auth_server="([^"]+)"', header_value)
+        if auth_server_match:
+            result["auth_server"] = auth_server_match.group(1)
+        
+        # Parse user_interaction="..."
+        user_interaction_match = re.search(r'user_interaction="([^"]+)"', header_value)
+        if user_interaction_match:
+            result["user_interaction"] = user_interaction_match.group(1)
+        
+        # Parse algs=("ed25519" "rsa-pss-sha512") (inner list)
+        algs_match = re.search(r'algs=\("([^"]+)"(?:\s+"([^"]+)")*\)', header_value)
+        if algs_match:
+            # Extract all quoted strings
+            algs = re.findall(r'"([^"]+)"', algs_match.group(0))
+            result["algs"] = algs
+        
+        return result
+    
+    except ChallengeError:
+        raise
+    except Exception as e:
+        raise ChallengeError(f"Failed to parse Agent-Auth header: {e}") from e
+
+
+def build_agent_auth_challenge(
+    require_signature: bool = True,
+    require_identity: bool = False,
+    require_auth_token: bool = False,
+    resource_token: Optional[str] = None,
+    auth_server: Optional[str] = None,
+    user_interaction: Optional[str] = None,
+    algs: Optional[List[str]] = None
+) -> str:
+    """Build Agent-Auth challenge header per AAuth spec Section 4.
+    
+    Args:
+        require_signature: Require HTTP signature (default: True)
+        require_identity: Require agent identity verification
+        require_auth_token: Require authorization token
+        resource_token: Resource token (required if require_auth_token=True)
+        auth_server: Auth server URL (required if require_auth_token=True)
+        user_interaction: User interaction URL
+        algs: List of supported algorithms
+        
+    Returns:
+        Agent-Auth header value
+        
+    Raises:
+        ChallengeError: If parameters are invalid
+    """
+    if not require_signature:
+        raise ChallengeError("Agent-Auth header must require httpsig")
+    
+    parts = ["httpsig"]
+    
+    if require_identity:
+        parts.append("identity=?1")
+    
+    if require_auth_token:
+        parts.append("auth-token")
+        if resource_token:
+            parts.append(f'resource_token="{resource_token}"')
+        if auth_server:
+            parts.append(f'auth_server="{auth_server}"')
+    
+    if user_interaction:
+        parts.append(f'user_interaction="{user_interaction}"')
+    
+    if algs:
+        algs_str = ' '.join([f'"{alg}"' for alg in algs])
+        parts.append(f'algs=({algs_str})')
+    
+    return "; ".join(parts)
+

aauth/headers/signature.py

@@ -0,0 +1,53 @@
+"""Signature header parsing and building for AAuth."""
+
+import re
+import base64
+from typing import Optional
+
+
+def build_signature_header(signature_bytes: bytes, label: str = "sig1") -> str:
+    """Build Signature header per RFC 9421 Section 4.2.
+    
+    Args:
+        signature_bytes: Raw signature bytes
+        label: Signature label (default: "sig1")
+        
+    Returns:
+        Signature header value
+    """
+    signature_b64 = base64.urlsafe_b64encode(signature_bytes).decode('utf-8').rstrip('=')
+    return f'{label}=:{signature_b64}:'
+
+
+def parse_signature(header_value: str, label: Optional[str] = None) -> bytes:
+    """Parse Signature header to extract signature bytes.
+    
+    Args:
+        header_value: Signature header value
+        label: Optional expected label (for validation)
+        
+    Returns:
+        Signature bytes
+        
+    Raises:
+        ValueError: If header format is invalid or label doesn't match
+    """
+    match = re.search(r'(\w+)=:([A-Za-z0-9_-]+):', header_value)
+    if not match:
+        raise ValueError(f"Invalid Signature format: {header_value}")
+    
+    found_label = match.group(1)
+    signature_b64 = match.group(2)
+    
+    if label and found_label != label:
+        raise ValueError(f"Label mismatch: expected {label}, got {found_label}")
+    
+    # Add padding if needed
+    signature_b64 += '=' * (4 - len(signature_b64) % 4)
+    
+    try:
+        signature_bytes = base64.urlsafe_b64decode(signature_b64)
+        return signature_bytes
+    except Exception as e:
+        raise ValueError(f"Failed to decode signature: {e}")
+

aauth/headers/signature_input.py

@@ -0,0 +1,65 @@
+"""Signature-Input header parsing and building for AAuth."""
+
+import re
+import time
+from typing import List, Dict, Any, Optional
+
+
+def build_signature_input_header(
+    covered_components: List[str],
+    label: str = "sig1",
+    created: Optional[int] = None
+) -> str:
+    """Build Signature-Input header per RFC 9421 Section 4.1.
+    
+    Args:
+        covered_components: List of component names to cover
+        label: Signature label (default: "sig1")
+        created: Creation timestamp (Unix time). If None, uses current time.
+        
+    Returns:
+        Signature-Input header value
+    """
+    if created is None:
+        created = int(time.time())
+    
+    # Format components: "@method" "@authority" "content-type"
+    component_list = ' '.join([
+        f'"{comp}"' for comp in covered_components
+    ])
+    
+    return f'{label}=({component_list});created={created}'
+
+
+def parse_signature_input(header_value: str) -> tuple[List[str], Dict[str, Any]]:
+    """Parse Signature-Input header to extract covered components and parameters.
+    
+    Args:
+        header_value: Signature-Input header value
+        
+    Returns:
+        Tuple of (components list, parameters dict)
+        
+    Raises:
+        ValueError: If header format is invalid
+    """
+    match = re.match(r'(\w+)=\((.*)\)(?:;(.*))?', header_value)
+    if not match:
+        raise ValueError(f"Invalid Signature-Input format: {header_value}")
+    
+    label = match.group(1)
+    components_str = match.group(2)
+    params_str = match.group(3) or ""
+    
+    components = []
+    for match in re.finditer(r'"([^"]+)"', components_str):
+        components.append(match.group(1))
+    
+    params = {}
+    for match in re.finditer(r'(\w+)=([^\s;]+)', params_str):
+        key = match.group(1)
+        value = match.group(2).strip('"')
+        params[key] = value
+    
+    return components, params
+