aauth 0.3.2__tar.gz → 0.3.3__tar.gz

{aauth-0.3.2 → aauth-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aauth
-Version: 0.3.2
+Version: 0.3.3
 Summary: AAuth protocol implementation for Python
 License: MIT License
         

{aauth-0.3.2 → aauth-0.3.3}/aauth/__init__.py

@@ -147,6 +147,7 @@ from .metadata.mission_manager import (
 # Agent role
 from .agent.signer import AgentRequestSigner
 from .agent.challenge_handler import ChallengeHandler
+from .agent.token_exchange import exchange_resource_token, extract_resource_token
 
 # Resource role
 from .resource.verifier import RequestVerifier
@@ -278,6 +279,8 @@ __all__ = [
     # Agent role
     "AgentRequestSigner",
     "ChallengeHandler",
+    "exchange_resource_token",
+    "extract_resource_token",
 
     # Resource role
     "RequestVerifier",

aauth-0.3.3/aauth/agent/__init__.py

@@ -0,0 +1,13 @@
+"""Agent role implementation for AAuth."""
+
+from .signer import AgentRequestSigner
+from .challenge_handler import ChallengeHandler
+from .token_exchange import exchange_resource_token, extract_resource_token
+
+__all__ = [
+    "AgentRequestSigner",
+    "ChallengeHandler",
+    "exchange_resource_token",
+    "extract_resource_token",
+]
+

aauth-0.3.3/aauth/agent/token_exchange.py

@@ -0,0 +1,147 @@
+"""AAuth PS token exchange for three-party mode (SPEC §4.1.3)."""
+
+import json
+import httpx
+import jwt as _jwt
+from typing import Optional, Mapping
+
+from ..errors import TokenError, MetadataError
+from ..signing.signer import sign_request
+from ..metadata.mission_manager import fetch_ps_metadata_async
+
+
+def extract_resource_token(headers: Mapping[str, str]) -> Optional[str]:
+    """Extract resource_token from an AAuth 401 challenge response.
+
+    Parses the AAuth-Requirement header to find the resource-token parameter
+    per SPEC §6. If not found or header is missing, returns None.
+
+    Args:
+        headers: HTTP response headers (dict-like, case-insensitive access).
+
+    Returns:
+        resource_token JWT string if present, else None.
+    """
+    from ..headers.aauth_header import get_challenge_header_value, parse_aauth_header
+
+    raw = get_challenge_header_value(headers)
+    if not raw:
+        return None
+    try:
+        parsed = parse_aauth_header(raw)
+        return parsed.get("resource_token")
+    except Exception:
+        return None
+
+
+async def exchange_resource_token(
+    resource_token: str,
+    private_key,
+    agent_jwt: str,
+    *,
+    ps_discovery_timeout: float = 10.0,
+    exchange_timeout: float = 30.0,
+) -> str:
+    """Exchange a resource_token for an auth_token via the PS (SPEC §4.1.3).
+
+    Three-party token exchange flow:
+      1. Decode resource_token to get PS URL from ``aud`` claim.
+      2. Discover PS token_endpoint via /.well-known/aauth-person.json
+         (falls back to {aud}/token if metadata fetch fails).
+      3. POST {resource_token} to PS, signed with aa-agent+jwt.
+      4. Return auth_token (aa-auth+jwt) from PS response.
+
+    Args:
+        resource_token: The resource token JWT from the 401 AAuth challenge.
+        private_key: Agent's Ed25519 private key for request signing.
+        agent_jwt: Agent token (aa-agent+jwt) for Signature-Key header.
+        ps_discovery_timeout: Timeout in seconds for PS metadata fetch.
+        exchange_timeout: Timeout in seconds for PS token endpoint POST.
+
+    Returns:
+        auth_token string (aa-auth+jwt) returned by the PS.
+
+    Raises:
+        TokenError: resource_token is malformed, PS returns non-200,
+                    or response missing auth_token.
+        MetadataError: PS metadata fetch encounters a hard error
+                       (non-timeout, non-404 failures).
+    """
+    # Step 1: Decode resource_token to get PS URL from aud claim
+    try:
+        claims = _jwt.decode(resource_token, options={"verify_signature": False})
+    except Exception as exc:
+        raise TokenError(
+            f"Cannot decode resource_token JWT: {exc}",
+            token_type="aa-resource+jwt",
+        )
+
+    aud = claims.get("aud")
+    if not aud:
+        raise TokenError(
+            "resource_token missing 'aud' claim — cannot locate PS",
+            token_type="aa-resource+jwt",
+        )
+
+    # Step 2: Discover PS token_endpoint from metadata
+    ps_base = aud.rstrip("/")
+    token_endpoint = f"{ps_base}/token"  # fallback
+
+    try:
+        meta = await fetch_ps_metadata_async(ps_base, timeout=ps_discovery_timeout)
+        discovered = meta.get("token_endpoint")
+        if discovered:
+            token_endpoint = discovered
+    except Exception:
+        # Metadata fetch failed — use default fallback endpoint
+        pass
+
+    # Step 3: Sign and POST resource_token to PS
+    body = json.dumps({"resource_token": resource_token}, separators=(",", ":")).encode()
+    headers = {"Content-Type": "application/json"}
+
+    sig_headers = sign_request(
+        method="POST",
+        target_uri=token_endpoint,
+        headers=headers,
+        body=None,
+        private_key=private_key,
+        sig_scheme="jwt",
+        jwt=agent_jwt,
+    )
+    headers.update(sig_headers)
+
+    try:
+        async with httpx.AsyncClient(
+            timeout=httpx.Timeout(exchange_timeout)
+        ) as http_client:
+            resp = await http_client.post(token_endpoint, headers=headers, content=body)
+    except Exception as exc:
+        raise TokenError(
+            f"PS token_endpoint request failed: {exc}",
+            token_type="aa-auth+jwt",
+        )
+
+    if resp.status_code != 200:
+        raise TokenError(
+            f"PS token_endpoint returned HTTP {resp.status_code}: {resp.text[:500]}",
+            token_type="aa-auth+jwt",
+        )
+
+    # Step 4: Extract and return auth_token
+    try:
+        data = resp.json()
+    except Exception as exc:
+        raise TokenError(
+            f"PS response is not valid JSON: {exc}",
+            token_type="aa-auth+jwt",
+        )
+
+    auth_token = data.get("auth_token")
+    if not auth_token:
+        raise TokenError(
+            f"PS response missing 'auth_token'; response keys: {list(data.keys())}",
+            token_type="aa-auth+jwt",
+        )
+
+    return auth_token

{aauth-0.3.2 → aauth-0.3.3}/aauth.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aauth
-Version: 0.3.2
+Version: 0.3.3
 Summary: AAuth protocol implementation for Python
 License: MIT License
         

{aauth-0.3.2 → aauth-0.3.3}/aauth.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ aauth/agent/__init__.py
 aauth/agent/challenge_handler.py
 aauth/agent/poller.py
 aauth/agent/signer.py
+aauth/agent/token_exchange.py
 aauth/headers/__init__.py
 aauth/headers/aauth_header.py
 aauth/headers/agent_auth.py
@@ -57,4 +58,5 @@ tests/test_phase5.py
 tests/test_phase6.py
 tests/test_phase7.py
 tests/test_phase8.py
-tests/test_phase9.py
+tests/test_phase9.py
+tests/test_token_exchange.py

{aauth-0.3.2 → aauth-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aauth"
-version = "0.3.2"
+version = "0.3.3"
 description = "AAuth protocol implementation for Python"
 readme = "README.md"
 requires-python = ">=3.9"

aauth-0.3.3/tests/test_token_exchange.py

@@ -0,0 +1,200 @@
+"""Tests for PS token exchange (three-party mode, SPEC §4.1.3)."""
+
+import pytest
+import asyncio
+import json
+import time
+from typing import Dict, Any
+from urllib.parse import urlparse
+
+from aauth.agent.token_exchange import extract_resource_token, exchange_resource_token
+from aauth.tokens.resource_token import create_resource_token
+from aauth.tokens.agent_token import create_agent_token
+from aauth.keys.keypair import generate_ed25519_keypair
+from aauth.keys.jwk import public_key_to_jwk, calculate_jwk_thumbprint
+from aauth.errors import TokenError, MetadataError
+import httpx
+
+
+class TestExtractResourceToken:
+    """Tests for extract_resource_token helper."""
+
+    def test_extract_from_valid_challenge_header(self):
+        """Extract resource_token from a valid AAuth challenge header."""
+        test_token = "eyJhbGciOiJFZERTQSJ9.eyJhdWQiOiJodHRwczovL2V4YW1wbGUifQ.sig"
+        headers = {
+            "AAuth-Requirement": f'requirement=auth-token; resource-token="{test_token}"'
+        }
+        result = extract_resource_token(headers)
+        assert result == test_token
+
+    def test_extract_from_case_insensitive_header(self):
+        """extract_resource_token is case-insensitive for header names."""
+        test_token = "eyJhbGciOiJFZERTQSJ9.eyJhdWQiOiJodHRwczovL2V4YW1wbGUifQ.sig"
+        headers = {
+            "aauth-requirement": f'requirement=auth-token; resource-token="{test_token}"'
+        }
+        result = extract_resource_token(headers)
+        assert result == test_token
+
+    def test_extract_from_missing_header(self):
+        """extract_resource_token returns None when no AAuth header present."""
+        headers = {"Content-Type": "application/json"}
+        result = extract_resource_token(headers)
+        assert result is None
+
+    def test_extract_from_header_without_resource_token_param(self):
+        """extract_resource_token returns None when resource-token param missing."""
+        headers = {"AAuth-Requirement": "requirement=identity"}
+        result = extract_resource_token(headers)
+        assert result is None
+
+    def test_extract_handles_malformed_header_gracefully(self):
+        """extract_resource_token returns None on parse errors."""
+        headers = {"AAuth-Requirement": "garbage_header_content"}
+        result = extract_resource_token(headers)
+        assert result is None
+
+
+class TestExchangeResourceToken:
+    """Tests for exchange_resource_token function."""
+
+    @pytest.fixture
+    def agent_keys(self):
+        """Generate test agent keys."""
+        agent_priv, agent_pub = generate_ed25519_keypair()
+        agent_jwk = public_key_to_jwk(agent_pub)
+        agent_jkt = calculate_jwk_thumbprint(agent_jwk)
+        return agent_priv, agent_pub, agent_jkt
+
+    def test_exchange_resource_token_missing_aud(self, agent_keys):
+        """Raises TokenError if resource_token missing aud claim."""
+        import jwt
+
+        agent_priv, _, _ = agent_keys
+
+        # Create JWT without aud claim
+        bad_token = jwt.encode(
+            {"iss": "https://ps.example", "agent": "https://agent.example"},
+            agent_priv,
+            algorithm="EdDSA",
+        )
+
+        async def run_test():
+            with pytest.raises(TokenError, match="missing 'aud' claim"):
+                await exchange_resource_token(
+                    resource_token=bad_token,
+                    private_key=agent_priv,
+                    agent_jwt="dummy-jwt",
+                )
+
+        asyncio.run(run_test())
+
+    def test_exchange_resource_token_malformed(self, agent_keys):
+        """Raises TokenError if resource_token is not valid JWT."""
+        agent_priv, _, _ = agent_keys
+
+        async def run_test():
+            with pytest.raises(TokenError, match="Cannot decode resource_token"):
+                await exchange_resource_token(
+                    resource_token="not-a-jwt",
+                    private_key=agent_priv,
+                    agent_jwt="dummy-jwt",
+                )
+
+        asyncio.run(run_test())
+
+
+@pytest.mark.integration
+class TestTokenExchangeIntegration:
+    """Integration tests using a real PS-like endpoint."""
+
+    def test_exchange_against_real_ps_server(self):
+        """End-to-end test with a real PS-like server."""
+        # Import here to avoid hard dependency unless running integration tests
+        from starlette.applications import Starlette
+        from starlette.responses import JSONResponse
+        import threading
+        import uvicorn
+        import time
+
+        # Generate test keys
+        agent_priv, agent_pub = generate_ed25519_keypair()
+        agent_jwk = public_key_to_jwk(agent_pub)
+        agent_jkt = calculate_jwk_thumbprint(agent_jwk)
+
+        ps_priv, ps_pub = generate_ed25519_keypair()
+
+        # Create a simple Starlette app that mimics PS behavior
+        app = Starlette()
+
+        @app.route("/.well-known/aauth-person.json", methods=["GET"])
+        async def ps_metadata(request):
+            return JSONResponse(
+                {
+                    "issuer": "http://127.0.0.1:8766",
+                    "token_endpoint": "http://127.0.0.1:8766/token",
+                    "jwks_uri": "http://127.0.0.1:8766/.well-known/jwks.json",
+                }
+            )
+
+        @app.route("/token", methods=["POST"])
+        async def token_endpoint(request):
+            body = await request.json()
+            # Just echo back a fake auth token
+            auth_token = "eyJhbGciOiJFZERTQSIsInR5cCI6ImFhLWF1dGhydHQifQ.eyJpc3MiOiJodHRwOi8vMTI3LjAuMC4xOjg3NjYiLCJhdWQiOiJodHRwczovL3Jlc291cmNlLmV4YW1wbGUiLCJhZ2VudCI6Imh0dHBzOi8vYWdlbnQuZXhhbXBsZSJ9.sig"
+            return JSONResponse({"auth_token": auth_token})
+
+        # Run server in background thread
+        server_thread = threading.Thread(
+            target=lambda: uvicorn.run(
+                app,
+                host="127.0.0.1",
+                port=8766,
+                log_level="critical",
+            ),
+            daemon=True,
+        )
+        server_thread.start()
+        time.sleep(0.5)  # Give server time to start
+
+        try:
+            # Create resource token pointing to our test PS
+            resource_token = create_resource_token(
+                iss="http://127.0.0.1:8766",
+                aud="http://127.0.0.1:8766",
+                agent="https://agent.example",
+                agent_jkt=agent_jkt,
+                scope="data.read",
+                private_key=ps_priv,
+                kid="ps-key-1",
+            )
+
+            # Create agent JWT using correct signature
+            agent_jwt = create_agent_token(
+                iss="https://agent.example",
+                sub="https://agent.example",
+                cnf_jwk=agent_jwk,
+                private_key=agent_priv,
+                kid="agent-key-1",
+            )
+
+            # Perform the exchange
+            async def run_exchange():
+                return await exchange_resource_token(
+                    resource_token=resource_token,
+                    private_key=agent_priv,
+                    agent_jwt=agent_jwt,
+                )
+
+            auth_token = asyncio.run(run_exchange())
+
+            # Verify we got back a token
+            assert auth_token is not None
+            assert isinstance(auth_token, str)
+            assert len(auth_token) > 0
+            # Should have 3 JWT parts
+            assert len(auth_token.split(".")) == 3
+        finally:
+            # Note: conftest will clean up the server via _server_lifecycle
+            pass

aauth-0.3.2/aauth/agent/__init__.py

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