aauth 0.1.0__py3-none-any.whl

aauth/signing/signature_base.py

@@ -0,0 +1,193 @@
+"""Signature base construction for HTTP Message Signing (RFC 9421)."""
+
+from typing import List, Tuple, Dict, Optional
+from urllib.parse import urlparse
+import base64
+import hashlib
+
+
+def build_signature_base(
+    method: str,
+    authority: str,
+    path: str,
+    query: Optional[str],
+    headers: Dict[str, str],
+    body: Optional[bytes],
+    signature_key_header: str,
+    covered_components: Optional[List[str]] = None,
+    signature_params: Optional[str] = None
+) -> str:
+    """Build signature base string per RFC 9421 Section 2.5.
+    
+    Args:
+        method: HTTP method
+        authority: Canonical authority (host:port)
+        path: Request path
+        query: Query string (without leading "?")
+        headers: Request headers
+        body: Request body bytes (None if no body)
+        signature_key_header: Signature-Key header value
+        covered_components: Optional list of components to cover (auto-detected if None)
+        signature_params: Signature-Input header value (required for @signature-params line)
+        
+    Returns:
+        Signature base string
+    """
+    # Auto-detect covered components if not provided
+    if covered_components is None:
+        covered_components = _determine_covered_components(query, body, additional_components=None)
+    
+    # Build component list
+    components: List[Tuple[str, str]] = []
+    
+    for component_name in covered_components:
+        if component_name == "@method":
+            components.append(("@method", method))
+        elif component_name == "@authority":
+            components.append(("@authority", authority))
+        elif component_name == "@path":
+            components.append(("@path", path))
+        elif component_name == "@query":
+            if query:
+                # RFC 9421 Section 2.2.7: @query value MUST include leading ?
+                components.append(("@query", f"?{query}"))
+            else:
+                raise ValueError("@query component specified but no query string present")
+        elif component_name == "content-type":
+            if body:
+                content_type = _get_header(headers, "content-type")
+                if content_type:
+                    components.append(("content-type", content_type))
+                else:
+                    raise ValueError("content-type component required but header missing")
+            else:
+                raise ValueError("content-type component specified but no body present")
+        elif component_name == "content-digest":
+            if body:
+                content_digest = _get_header(headers, "content-digest")
+                if content_digest:
+                    components.append(("content-digest", content_digest))
+                else:
+                    raise ValueError("content-digest component required but header missing")
+            else:
+                raise ValueError("content-digest component specified but no body present")
+        elif component_name == "signature-key":
+            components.append(("signature-key", signature_key_header))
+        elif component_name == "nonce":
+            nonce_value = _get_header(headers, "nonce")
+            if nonce_value:
+                components.append(("nonce", nonce_value))
+            else:
+                raise ValueError("nonce component required but Nonce header missing")
+        else:
+            raise ValueError(f"Unknown component: {component_name}")
+    
+    # Build signature base (RFC 9421 Section 2.5)
+    signature_base_parts = []
+    for component_name, component_value in components:
+        if component_name.startswith("@"):
+            signature_base_parts.append(f'"{component_name}": {component_value}')
+        else:
+            header_name = component_name.lower()
+            signature_base_parts.append(f'"{header_name}": {component_value}')
+    
+    # Add @signature-params as the FINAL line (RFC 9421 Section 2.5 requirement)
+    # The @signature-params line contains the Signature-Input header value (without the label prefix)
+    # RFC 9421 Section 2.5: @signature-params MUST be present
+    if not signature_params:
+        raise ValueError("signature_params is required for valid signature base")
+    signature_base_parts.append(f'"@signature-params": {signature_params}')
+    
+    signature_base = "\n".join(signature_base_parts)
+    
+    return signature_base
+
+
+def _determine_covered_components(
+    query: Optional[str], 
+    body: Optional[bytes],
+    additional_components: Optional[List[str]] = None
+) -> List[str]:
+    """Determine covered components based on request structure.
+    
+    Per AAuth spec Section 10.3:
+    - Always: @method, @authority, @path, signature-key
+    - If query present: @query
+    - Body components (content-type, content-digest) are opt-in via additional_components
+    
+    Args:
+        query: Query string (None if no query)
+        body: Request body (None if no body)
+        additional_components: Optional list of additional components to include (e.g., ["content-type", "content-digest", "nonce"])
+        
+    Returns:
+        List of component names
+    """
+    components = ["@method", "@authority", "@path"]
+    
+    if query:
+        components.append("@query")
+    
+    # Body components are opt-in via additional_components
+    # Only add if explicitly requested
+    if additional_components:
+        components.extend(additional_components)
+    
+    # signature-key MUST always be included
+    components.append("signature-key")
+    
+    return components
+
+
+def _get_header(headers: Dict[str, str], name: str) -> Optional[str]:
+    """Get header value (case-insensitive).
+    
+    Args:
+        headers: Headers dictionary
+        name: Header name (case-insensitive)
+        
+    Returns:
+        Header value or None
+    """
+    name_lower = name.lower()
+    for key, value in headers.items():
+        if key.lower() == name_lower:
+            return value
+    return None
+
+
+def build_signature_params(
+    covered_components: List[str],
+    created: int,
+    keyid: Optional[str] = None
+) -> str:
+    """Build the Signature-Input value (the part after the label).
+    
+    Args:
+        covered_components: List of component names
+        created: Creation timestamp (Unix time)
+        keyid: Optional key identifier
+        
+    Returns:
+        Signature params string: ("@method" "@authority" ...);created=1234567890
+    """
+    components_str = " ".join(f'"{c}"' for c in covered_components)
+    params = f"({components_str});created={created}"
+    if keyid:
+        params += f';keyid="{keyid}"'
+    return params
+
+
+def calculate_content_digest(body: bytes) -> str:
+    """Calculate Content-Digest header value per RFC 9530.
+    
+    Args:
+        body: Request body bytes
+    
+    Returns:
+        Content-Digest header value (e.g., "sha-256=:...:")
+    """
+    digest = hashlib.sha256(body).digest()
+    digest_b64 = base64.b64encode(digest).decode('ascii')
+    return f"sha-256=:{digest_b64}:"
+

aauth/signing/signer.py

@@ -0,0 +1,138 @@
+"""HTTP request signing for AAuth."""
+
+from typing import Dict, Any, Optional, List
+from urllib.parse import urlparse
+import time
+from ..headers.signature_key import build_signature_key_header
+from ..headers.signature_input import build_signature_input_header
+from ..headers.signature import build_signature_header
+from ..signing.signature_base import build_signature_base, calculate_content_digest, build_signature_params
+from ..errors import SignatureError
+
+
+def sign_request(
+    method: str,
+    target_uri: str,
+    headers: Dict[str, str],
+    body: Optional[bytes],
+    private_key,
+    sig_scheme: str = "hwk",
+    additional_signature_components: Optional[List[str]] = None,
+    **kwargs
+) -> Dict[str, str]:
+    """Sign an HTTP request using HTTP Message Signatures (RFC 9421).
+    
+    Args:
+        method: HTTP method (GET, POST, etc.)
+        target_uri: Target URI
+        headers: Request headers dictionary (will be modified)
+        body: Request body bytes (None if no body)
+        private_key: Ed25519 private key
+        sig_scheme: Signature scheme - "hwk", "jwks", or "jwt"
+        **kwargs: Additional parameters for signature schemes:
+            - For "jwks": id (required), kid (required), well-known (optional)
+            - For "jwt": jwt (required)
+    
+    Returns:
+        Dictionary with Signature-Input, Signature, and Signature-Key headers
+        
+    Raises:
+        SignatureError: If signing fails
+    """
+    try:
+        # Parse URI for derived components
+        parsed_uri = urlparse(target_uri)
+        authority = parsed_uri.netloc
+        path = parsed_uri.path or "/"
+        query_string = parsed_uri.query if parsed_uri.query else None
+        
+        # Build Signature-Key header first (needed for signature-key component)
+        # Use label "sig1" to match Signature-Input and Signature headers
+        signature_key_header = build_signature_key_header(
+            sig_scheme=sig_scheme,
+            private_key=private_key,
+            label="sig1",
+            **kwargs
+        )
+        
+        # Add Signature-Key to headers (needed for signature-key component)
+        headers["Signature-Key"] = signature_key_header
+        
+        # Determine body components to include (opt-in only, per SPEC_NOTES.md)
+        # Body components are NOT automatic - only included if explicitly requested
+        # via additional_signature_components parameter (typically from server metadata)
+        body_components = []
+        if body and additional_signature_components:
+            # Only add if explicitly requested via additional_signature_components
+            for comp in additional_signature_components:
+                if comp in ("content-type", "content-digest"):
+                    body_components.append(comp)
+            
+            # Add Content-Digest header if needed and not already present (RFC 9530)
+            # Only calculate Content-Digest if it's in body_components but not in headers
+            if "content-digest" in body_components and "Content-Digest" not in headers:
+                content_digest = calculate_content_digest(body)
+                headers["Content-Digest"] = content_digest
+            
+            # Add content-type header if needed and not already present
+            if "content-type" in body_components and "Content-Type" not in headers:
+                headers["Content-Type"] = "application/octet-stream"
+        
+        # Check for Nonce header (per SPEC.md Section 10.5)
+        # Nonce MUST be included if present, regardless of body or additional_signature_components
+        if "Nonce" in headers:
+            body_components.append("nonce")
+        
+        # Determine covered components
+        from ..signing.signature_base import _determine_covered_components
+        covered_components = _determine_covered_components(
+            query_string, 
+            body,
+            additional_components=body_components
+        )
+        
+        # Build signature params using new function
+        created = int(time.time())
+        signature_params = build_signature_params(
+            covered_components=covered_components,
+            created=created
+        )
+        
+        # Build Signature-Input header (needed for @signature-params in signature base)
+        signature_input_header = f"sig1={signature_params}"
+        
+        # Build signature base (now includes @signature-params per RFC 9421)
+        signature_base = build_signature_base(
+            method=method,
+            authority=authority,
+            path=path,
+            query=query_string,
+            headers=headers,
+            body=body,
+            signature_key_header=signature_key_header,
+            covered_components=covered_components,
+            signature_params=signature_params
+        )
+        
+        import logging
+        logger = logging.getLogger("aauth.signing")
+        logger.debug(f"🔐 AAUTH LIBRARY SIGNATURE BASE:")
+        logger.debug(f"🔐 Signature base length: {len(signature_base)} bytes")
+        logger.debug(f"🔐 Signature base hex (first 200): {signature_base.encode('utf-8').hex()[:200]}...")
+        for i, line in enumerate(signature_base.split('\n')):
+            logger.debug(f"🔐   Line {i}: {repr(line)}")
+        
+        # Sign the signature base
+        signature_bytes = private_key.sign(signature_base.encode('utf-8'))
+        
+        # Build Signature header
+        signature_header = build_signature_header(signature_bytes, label="sig1")
+        
+        return {
+            "Signature-Input": signature_input_header,
+            "Signature": signature_header,
+            "Signature-Key": signature_key_header
+        }
+    except Exception as e:
+        raise SignatureError(f"Failed to sign request: {e}", details={"scheme": sig_scheme}) from e
+

aauth/signing/verifier.py

@@ -0,0 +1,323 @@
+"""HTTP signature verification for AAuth."""
+
+import re
+import time
+from typing import Dict, Any, Optional, Callable
+from urllib.parse import urlparse
+import jwt
+from ..headers.signature_key import parse_signature_key
+from ..headers.signature_input import parse_signature_input
+from ..headers.signature import parse_signature
+from ..signing.signature_base import build_signature_base
+from ..keys.jwk import jwk_to_public_key
+from ..tokens.agent_token import verify_agent_token
+from ..errors import SignatureError
+
+
+def verify_signature(
+    method: str,
+    target_uri: str,
+    headers: Dict[str, str],
+    body: Optional[bytes],
+    signature_input_header: str,
+    signature_header: str,
+    signature_key_header: str,
+    public_key=None,
+    jwks_fetcher: Optional[Callable] = None
+) -> bool:
+    """Verify HTTP signature using HTTP Message Signatures (RFC 9421).
+    
+    Args:
+        method: HTTP method
+        target_uri: Target URI
+        headers: Request headers
+        body: Request body bytes (None if no body)
+        signature_input_header: Signature-Input header value
+        signature_header: Signature header value
+        signature_key_header: Signature-Key header value
+        public_key: Optional public key (for hwk scheme)
+        jwks_fetcher: Optional JWKS fetcher function (for jwks/jwt schemes)
+        
+    Returns:
+        True if signature is valid, False otherwise
+        
+    Raises:
+        SignatureError: If verification fails due to invalid format
+    """
+    import logging
+    logger = logging.getLogger("aauth.signing")
+
+    logger.debug(f"🔐 VERIFIER: verify_signature() called")
+    logger.debug(f"🔐 VERIFIER: method={method}, target_uri={target_uri}")
+    logger.debug(f"🔐 VERIFIER: signature_input_header={signature_input_header}")
+    
+    try:
+        # Parse Signature-Input
+        components, sig_params = parse_signature_input(signature_input_header)
+        
+        # Verify created timestamp (per spec Section 10.4)
+        if "created" in sig_params:
+            created = int(sig_params["created"])
+            now = int(time.time())
+            if abs(now - created) > 60:
+                return False
+        
+        # Parse Signature-Key
+        parsed_key = parse_signature_key(signature_key_header)
+        scheme = parsed_key["scheme"]
+        params = parsed_key["params"]
+        label = parsed_key["label"]
+        
+        # Verify label consistency (per spec Section 10.1.1)
+        label_match = re.match(r'(\w+)=', signature_input_header)
+        sig_label_match = re.match(r'(\w+)=', signature_header)
+        
+        if not (label_match and sig_label_match):
+            return False
+        
+        if not (label_match.group(1) == sig_label_match.group(1) == label):
+            return False
+        
+        # Extract public key based on scheme
+        if scheme == "hwk":
+            if not public_key:
+                jwk = {
+                    "kty": params.get("kty"),
+                    "crv": params.get("crv"),
+                    "x": params.get("x")
+                }
+                public_key = jwk_to_public_key(jwk)
+        
+        elif scheme == "jwks":
+            if not jwks_fetcher:
+                raise SignatureError("sig=jwks requires jwks_fetcher")
+            
+            agent_id = params.get("id")
+            kid = params.get("kid")
+            well_known = params.get("well-known")
+            jwks_param = params.get("jwks")
+            
+            # Per spec Section 10.7 Mode 2: jwks parameter MUST NOT be present
+            if jwks_param:
+                return False
+            
+            # Fetch JWKS
+            if callable(jwks_fetcher):
+                # Try both calling patterns
+                try:
+                    jwks = jwks_fetcher(agent_id, kid) if kid else jwks_fetcher(agent_id)
+                except:
+                    jwks = jwks_fetcher(agent_id)
+            else:
+                jwks = jwks_fetcher
+            
+            if not jwks:
+                return False
+            
+            # Find key by kid
+            keys = jwks.get("keys", [])
+            signing_key = None
+            for key in keys:
+                if key.get("kid") == kid:
+                    signing_key = key
+                    break
+            
+            if not signing_key:
+                return False
+            
+            public_key = jwk_to_public_key(signing_key)
+        
+        elif scheme == "jwt":
+            if not jwks_fetcher:
+                raise SignatureError("sig=jwt requires jwks_fetcher")
+            
+            jwt_token = params.get("jwt")
+            if not jwt_token:
+                return False
+            
+            # Parse JWT to determine type
+            try:
+                header = jwt.get_unverified_header(jwt_token)
+                payload = jwt.decode(jwt_token, options={"verify_signature": False})
+            except Exception:
+                return False
+            
+            typ = header.get("typ")
+            if typ not in ("agent+jwt", "auth+jwt"):
+                return False
+            
+            # Validate JWT and extract cnf.jwk
+            if typ == "agent+jwt":
+                # Verify agent token
+                try:
+                    agent_claims = verify_agent_token(
+                        token=jwt_token,
+                        jwks_fetcher=jwks_fetcher,
+                        expected_aud=None
+                    )
+                    cnf = agent_claims.get("cnf")
+                    cnf_jwk = cnf.get("jwk") if cnf else None
+                except Exception:
+                    return False
+            
+            elif typ == "auth+jwt":
+                # Extract cnf.jwk from payload
+                cnf = payload.get("cnf")
+                if not cnf:
+                    return False
+                
+                cnf_jwk = cnf.get("jwk")
+                if not cnf_jwk:
+                    return False
+                
+                # Verify JWT signature using auth server's JWKS
+                iss = payload.get("iss")
+                kid_header = header.get("kid")
+                if not iss or not kid_header:
+                    return False
+                
+                # Fetch auth server JWKS
+                try:
+                    if callable(jwks_fetcher):
+                        auth_jwks = jwks_fetcher(iss)
+                    else:
+                        auth_jwks = jwks_fetcher
+                    
+                    if not auth_jwks:
+                        return False
+                    
+                    # Find signing key
+                    keys = auth_jwks.get("keys", [])
+                    signing_key = None
+                    for key in keys:
+                        if key.get("kid") == kid_header:
+                            signing_key = key
+                            break
+                    
+                    if not signing_key:
+                        logger.debug(f"🔐 VERIFIER: Signing key not found in JWKS (kid={kid_header})")
+                        return False
+                    
+                    logger.debug(f"🔐 VERIFIER: Found signing key in JWKS: {signing_key}")
+                    
+                    # Get algorithm from JWT header
+                    alg = header.get("alg")
+                    if not alg:
+                        logger.debug(f"🔐 VERIFIER: JWT header missing 'alg' field")
+                        return False
+                    
+                    # Map algorithm to PyJWT algorithm names
+                    # RS256 -> RS256, EdDSA -> EdDSA, etc.
+                    algorithms = [alg]
+                    
+                    logger.debug(f"🔐 VERIFIER: Verifying JWT with algorithm: {alg}")
+                    logger.debug(f"🔐 VERIFIER: JWT token (first 100 chars): {jwt_token[:100]}...")
+                    
+                    # Handle different key types
+                    # For RSA keys (RS256, etc.), convert JWK to public key using PyJWT's RSA algorithm
+                    # For Ed25519 keys, we need to convert using jwk_to_public_key
+                    key_type = signing_key.get("kty")
+                    if key_type == "RSA":
+                        # Convert RSA JWK to public key object using PyJWT's RSA algorithm
+                        from jwt.algorithms import RSAAlgorithm
+                        auth_public_key = RSAAlgorithm.from_jwk(signing_key)
+                        logger.debug(f"🔐 VERIFIER: Converted RSA JWK to public key using RSAAlgorithm.from_jwk()")
+                    elif key_type == "OKP" and signing_key.get("crv") == "Ed25519":
+                        # Convert Ed25519 JWK to public key
+                        auth_public_key = jwk_to_public_key(signing_key)
+                        logger.debug(f"🔐 VERIFIER: Converted Ed25519 JWK to public key")
+                    else:
+                        logger.debug(f"🔐 VERIFIER: Unsupported key type: {key_type}")
+                        return False
+                    
+                    logger.debug(f"🔐 VERIFIER: Auth public key type: {type(auth_public_key)}")
+                    
+                    # Verify JWT signature
+                    try:
+                        jwt.decode(
+                            jwt_token,
+                            auth_public_key,
+                            algorithms=algorithms,
+                            options={"verify_signature": True, "verify_exp": False, "verify_aud": False}
+                        )
+                        logger.debug(f"🔐 VERIFIER: JWT signature verification PASSED")
+                    except Exception as jwt_error:
+                        logger.debug(f"🔐 VERIFIER: JWT decode failed: {jwt_error}")
+                        import traceback
+                        logger.debug(f"🔐 VERIFIER: JWT decode traceback: {traceback.format_exc()}")
+                        raise
+                    
+                    # Check expiration
+                    exp = payload.get("exp")
+                    if exp and int(time.time()) >= exp:
+                        logger.debug(f"🔐 VERIFIER: JWT expired (exp={exp}, now={int(time.time())})")
+                        return False
+                except Exception as e:
+                    logger.debug(f"🔐 VERIFIER: JWT verification failed with exception: {e}")
+                    import traceback
+                    logger.debug(f"🔐 VERIFIER: Exception traceback: {traceback.format_exc()}")
+                    return False
+            
+            # Convert cnf.jwk to public key for HTTPSig verification
+            public_key = jwk_to_public_key(cnf_jwk)
+        
+        else:
+            raise SignatureError(f"Unknown signature scheme: {scheme}")
+        
+        # Reconstruct signature base
+        parsed_uri = urlparse(target_uri)
+        authority = parsed_uri.netloc
+        path = parsed_uri.path or "/"
+        query_string = parsed_uri.query if parsed_uri.query else None
+        
+        # Extract signature params (the part after "sig1=") for @signature-params line
+        # Signature-Input format: sig1=("@method" "@authority" ...);created=...
+        # RFC 9421 Section 2.5: @signature-params is required
+        signature_params = signature_input_header[5:] if signature_input_header.startswith("sig1=") else signature_input_header
+        if not signature_params:
+            return False  # Invalid - signature_params required
+        
+        logger.debug(f"🔐 VERIFIER: Building signature base")
+        logger.debug(f"🔐 VERIFIER: method={method}, authority={authority}, path={path}")
+        logger.debug(f"🔐 VERIFIER: covered_components={components}")
+        logger.debug(f"🔐 VERIFIER: signature_params={signature_params}")
+        logger.debug(f"🔐 VERIFIER: signature_key_header={signature_key_header[:100]}...")
+        logger.debug(f"🔐 VERIFIER: body is None: {body is None}")
+        
+        signature_base = build_signature_base(
+            method=method,
+            authority=authority,
+            path=path,
+            query=query_string,
+            headers=headers,
+            body=body,
+            signature_key_header=signature_key_header,
+            covered_components=components,
+            signature_params=signature_params
+        )
+        
+        logger.debug(f"🔐 VERIFIER SIGNATURE BASE:")
+        logger.debug(f"🔐 Signature base length: {len(signature_base)} bytes")
+        logger.debug(f"🔐 Signature base hex (first 200): {signature_base.encode('utf-8').hex()[:200]}...")
+        for i, line in enumerate(signature_base.split('\n')):
+            logger.debug(f"🔐   Line {i}: {repr(line)}")
+        
+        # Parse signature
+        signature_bytes = parse_signature(signature_header, label=label)
+        
+        # Verify signature
+        try:
+            public_key.verify(signature_bytes, signature_base.encode('utf-8'))
+            logger.debug(f"🔐 VERIFIER: ✅ Signature verification PASSED")
+            return True
+        except Exception as e:
+            logger.debug(f"🔐 VERIFIER: ❌ Signature verification FAILED: {e}")
+            import traceback
+            logger.debug(f"🔐 VERIFIER: Exception traceback: {traceback.format_exc()}")
+            return False
+    
+    except SignatureError:
+        raise
+    except Exception as e:
+        raise SignatureError(f"Signature verification failed: {e}") from e
+

aauth/tokens/__init__.py

@@ -0,0 +1,2 @@
+"""JWT token handling for AAuth."""
+