aauth 0.3.2__tar.gz → 0.3.4__tar.gz

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

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

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

@@ -1,6 +1,6 @@
 """AAuth - Agent Authentication Protocol implementation for Python."""
 
-__version__ = "0.3.0"
+__version__ = "0.3.4"
 
 # Errors and error codes
 from .errors import (
@@ -147,6 +147,8 @@ 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
+from .agent.poller import poll_pending_url, async_poll_pending_url, PollingResult
 
 # Resource role
 from .resource.verifier import RequestVerifier
@@ -278,6 +280,11 @@ __all__ = [
     # Agent role
     "AgentRequestSigner",
     "ChallengeHandler",
+    "exchange_resource_token",
+    "extract_resource_token",
+    "poll_pending_url",
+    "async_poll_pending_url",
+    "PollingResult",
 
     # Resource role
     "RequestVerifier",

aauth-0.3.4/aauth/agent/__init__.py

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

{aauth-0.3.2 → aauth-0.3.4}/aauth/agent/poller.py

@@ -3,16 +3,40 @@
 Per spec Section 10.6, the agent polls the pending URL with GET
 until a terminal response is received.
 
-This module provides a synchronous polling implementation for demos.
+This module provides both a synchronous polling implementation (for demos
+and scripts) and an async implementation suitable for use inside async
+frameworks and the exchange_resource_token() function.
 """
 
+import asyncio
 import time
 import logging
-from typing import Dict, Any, Optional, Callable
+from typing import Awaitable, Dict, Any, Optional, Callable
 
 logger = logging.getLogger("aauth.agent.poller")
 
 
+def _extract_interaction_url(aauth_req_header: str, code: str, pending_url: str) -> str:
+    """Extract the user-facing interaction URL from AAuth-Requirement header.
+
+    The header carries ``url="<interaction_endpoint>"`` per spec §6.2.
+    The code is appended as a query parameter so the user arrives pre-filled.
+    Falls back to ``pending_url`` when the header carries no url field.
+    """
+    if not aauth_req_header:
+        return pending_url
+    try:
+        from ..headers.aauth_header import parse_aauth_header
+        parsed = parse_aauth_header(aauth_req_header)
+        endpoint = parsed.get("url")
+        if endpoint:
+            sep = "&" if "?" in endpoint else "?"
+            return f"{endpoint}{sep}code={code}"
+    except Exception:
+        pass
+    return pending_url
+
+
 class PollingResult:
     """Result of polling a pending URL."""
 
@@ -169,7 +193,8 @@ def poll_pending_url(
 
             # Handle interaction requirement (first time only)
             if require == "interaction" and code and on_interaction and attempt == 0:
-                on_interaction(pending_url, code)
+                interaction_url = _extract_interaction_url(aauth_req_header, code, pending_url)
+                on_interaction(interaction_url, code)
 
             # When status=interacting, user has arrived — stop prompting
             if poll_status == "interacting":
@@ -234,6 +259,201 @@ def poll_pending_url(
     )
 
 
+async def async_poll_pending_url(
+    pending_url: str,
+    sign_and_send_get: Callable[[str], Awaitable[Any]],
+    max_polls: int = 60,
+    default_wait: int = 2,
+    on_interaction: Optional[Callable[[str, str], Awaitable[None]]] = None,
+    on_clarification: Optional[Callable[[str, str], Awaitable[Optional[str]]]] = None,
+    sign_and_send_post: Optional[Callable[[str, Dict], Awaitable[Any]]] = None,
+) -> PollingResult:
+    """Async version of poll_pending_url — same state machine, awaitable throughout.
+
+    Implements the agent state machine from spec Section 10.6.
+
+    Args:
+        pending_url: The Location URL from the 202 response.
+        sign_and_send_get: Async callable that sends a signed GET to a URL and
+            returns a response with .status_code, .json(), and .headers.
+        max_polls: Maximum number of poll attempts.
+        default_wait: Default seconds between polls.
+        on_interaction: Async callback when require=interaction is received.
+            Called with (pending_url, code). Agent should direct user there.
+        on_clarification: Async callback when clarification question is received.
+            Called with (pending_url, question). Should return answer string or None.
+        sign_and_send_post: Async callable for POST requests (needed for
+            clarification responses). Called with (url, json_body).
+
+    Returns:
+        PollingResult with the outcome.
+    """
+    for attempt in range(max_polls):
+        logger.debug(f"Poll attempt {attempt + 1}/{max_polls}: GET {pending_url}")
+
+        try:
+            response = await sign_and_send_get(pending_url)
+        except Exception as e:
+            logger.error(f"Poll request failed: {e}")
+            return PollingResult(
+                success=False,
+                error="network_error",
+                error_description=str(e),
+            )
+
+        status = response.status_code
+
+        # Terminal: 200 OK — success
+        if status == 200:
+            body = response.json()
+            return PollingResult(
+                success=True,
+                auth_token=body.get("auth_token"),
+                response_body=body,
+                status_code=200,
+            )
+
+        # Terminal: 403 Denied/Abandoned
+        if status == 403:
+            body = response.json()
+            return PollingResult(
+                success=False,
+                status_code=403,
+                response_body=body,
+                error=body.get("error", "denied"),
+                error_description=body.get("error_description"),
+            )
+
+        # Terminal: 408 Expired
+        if status == 408:
+            body = response.json()
+            return PollingResult(
+                success=False,
+                status_code=408,
+                response_body=body,
+                error=body.get("error", "expired"),
+                error_description=body.get("error_description"),
+            )
+
+        # Terminal: 410 Gone
+        if status == 410:
+            body = response.json()
+            return PollingResult(
+                success=False,
+                status_code=410,
+                response_body=body,
+                error=body.get("error", "invalid_code"),
+                error_description=body.get("error_description"),
+            )
+
+        # Terminal: 500 Server Error
+        if status == 500:
+            body = response.json() if response.headers.get("content-type", "").startswith("application/json") else {}
+            return PollingResult(
+                success=False,
+                status_code=500,
+                response_body=body,
+                error=body.get("error", "server_error"),
+                error_description=body.get("error_description"),
+            )
+
+        # Transient: 429 Too Many Requests (slow_down)
+        if status == 429:
+            default_wait += 5  # Per spec: increase interval by 5 seconds
+            retry_after = default_wait
+            retry_header = getattr(response, 'headers', {}).get('retry-after') or getattr(response, 'headers', {}).get('Retry-After')
+            if retry_header:
+                try:
+                    retry_after = max(int(retry_header), default_wait)
+                except (ValueError, TypeError):
+                    pass
+            logger.debug(f"Received 429 slow_down, increasing poll interval to {retry_after}s")
+            await asyncio.sleep(retry_after)
+            continue
+
+        # Transient: 202 Pending or Interacting — continue polling
+        if status == 202:
+            body = response.json()
+            require = body.get("requirement") or body.get("require")
+            code = body.get("code")
+            aauth_req_header = (
+                getattr(response, "headers", {}).get("aauth-requirement")
+                or getattr(response, "headers", {}).get("AAuth-Requirement")
+                or ""
+            )
+            if not require and "requirement=clarification" in aauth_req_header:
+                require = "clarification"
+            clarification = body.get("clarification")
+            poll_status = body.get("status", "pending")
+
+            # Handle interaction requirement (first time only)
+            if require == "interaction" and code and on_interaction and attempt == 0:
+                interaction_url = _extract_interaction_url(aauth_req_header, code, pending_url)
+                await on_interaction(interaction_url, code)
+
+            # When status=interacting, user has arrived — stop prompting
+            if poll_status == "interacting":
+                logger.debug("User has arrived at interaction endpoint (status=interacting)")
+
+            # Handle clarification question
+            if clarification and on_clarification and sign_and_send_post:
+                answer = await on_clarification(pending_url, clarification)
+                if answer:
+                    try:
+                        await sign_and_send_post(pending_url, {
+                            "clarification_response": answer
+                        })
+                    except Exception as e:
+                        logger.warning(f"Failed to send clarification response: {e}")
+
+            # Respect Retry-After
+            retry_after = default_wait
+            retry_header = getattr(response, 'headers', {}).get('retry-after') or getattr(response, 'headers', {}).get('Retry-After')
+            if retry_header:
+                try:
+                    retry_after = max(int(retry_header), 0)
+                except (ValueError, TypeError):
+                    pass
+
+            if retry_after > 0:
+                await asyncio.sleep(retry_after)
+            continue
+
+        # Transient: 503 Temporarily unavailable
+        if status == 503:
+            retry_after = default_wait * 2
+            retry_header = getattr(response, 'headers', {}).get('retry-after') or getattr(response, 'headers', {}).get('Retry-After')
+            if retry_header:
+                try:
+                    retry_after = max(int(retry_header), 1)
+                except (ValueError, TypeError):
+                    pass
+            await asyncio.sleep(retry_after)
+            continue
+
+        # Unknown status — treat as fatal
+        logger.warning(f"Unexpected status code {status} during polling")
+        body = {}
+        try:
+            body = response.json()
+        except Exception:
+            pass
+        return PollingResult(
+            success=False,
+            status_code=status,
+            response_body=body,
+            error="unexpected_status",
+            error_description=f"Unexpected HTTP status {status}",
+        )
+
+    # Exhausted polls
+    return PollingResult(
+        success=False,
+        error="max_polls_exceeded",
+        error_description=f"Exceeded maximum {max_polls} poll attempts",
+    )
+
+
 def cancel_pending_request(
     sign_and_send_delete: Callable[[str], Any],
     pending_url: str,

aauth-0.3.4/aauth/agent/token_exchange.py

@@ -0,0 +1,219 @@
+"""AAuth PS token exchange for three-party mode (SPEC §4.1.3)."""
+
+import json
+import httpx
+import jwt as _jwt
+from typing import Awaitable, Callable, Dict, Optional, Mapping
+
+from ..errors import TokenError, MetadataError
+from ..signing.signer import sign_request
+from ..metadata.mission_manager import fetch_ps_metadata_async
+from .poller import async_poll_pending_url
+
+
+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,
+    on_interaction: Optional[Callable[[str, str], Awaitable[None]]] = None,
+    on_clarification: Optional[Callable[[str, str], Awaitable[Optional[str]]]] = None,
+    max_polls: int = 60,
+) -> 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.
+      4a. 200 → return auth_token directly.
+      4b. 202 → poll the Location URL until a terminal response, honouring
+          any interaction or clarification callbacks, then return auth_token.
+
+    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 individual HTTP requests.
+        on_interaction: Async callback invoked when the PS requires human
+            interaction. Called with ``(pending_url, code)`` on the first
+            poll that returns ``requirement=interaction``. The app should
+            surface the URL and code to the user (e.g. via SSE).
+        on_clarification: Async callback invoked when the PS asks a
+            clarification question. Called with ``(pending_url, question)``
+            and should return the user's answer string, or None to skip.
+        max_polls: Maximum polling attempts before giving up (default 60).
+
+    Returns:
+        auth_token string (aa-auth+jwt) returned by the PS.
+
+    Raises:
+        TokenError: resource_token is malformed, PS returns a non-recoverable
+                    error, or polling is exhausted/denied.
+        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",
+        )
+
+    # Step 4a: Immediate success
+    if resp.status_code == 200:
+        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
+
+    # Step 4b: Deferred — PS needs human interaction or approval before issuing token
+    if resp.status_code == 202:
+        location = resp.headers.get("location") or resp.headers.get("Location")
+        if not location:
+            raise TokenError(
+                "PS returned 202 but no Location header — cannot poll",
+                token_type="aa-auth+jwt",
+            )
+
+        # Build async signing closures so the poller can make authenticated requests
+        async def _signed_get(url: str):
+            sig_hdrs = sign_request(
+                method="GET",
+                target_uri=url,
+                headers={},
+                body=None,
+                private_key=private_key,
+                sig_scheme="jwt",
+                jwt=agent_jwt,
+            )
+            async with httpx.AsyncClient(timeout=httpx.Timeout(exchange_timeout)) as c:
+                return await c.get(url, headers=sig_hdrs)
+
+        async def _signed_post(url: str, body_dict: Dict):
+            post_body = json.dumps(body_dict, separators=(",", ":")).encode()
+            post_headers = {"Content-Type": "application/json"}
+            sig_hdrs = sign_request(
+                method="POST",
+                target_uri=url,
+                headers=post_headers,
+                body=None,
+                private_key=private_key,
+                sig_scheme="jwt",
+                jwt=agent_jwt,
+            )
+            post_headers.update(sig_hdrs)
+            async with httpx.AsyncClient(timeout=httpx.Timeout(exchange_timeout)) as c:
+                return await c.post(url, headers=post_headers, content=post_body)
+
+        result = await async_poll_pending_url(
+            pending_url=location,
+            sign_and_send_get=_signed_get,
+            max_polls=max_polls,
+            on_interaction=on_interaction,
+            on_clarification=on_clarification,
+            sign_and_send_post=_signed_post if on_clarification else None,
+        )
+
+        if not result.success:
+            raise TokenError(
+                f"PS deferred exchange failed: {result.error} — {result.error_description}",
+                token_type="aa-auth+jwt",
+            )
+        if not result.auth_token:
+            raise TokenError(
+                "PS polling succeeded but response missing 'auth_token'",
+                token_type="aa-auth+jwt",
+            )
+        return result.auth_token
+
+    raise TokenError(
+        f"PS token_endpoint returned HTTP {resp.status_code}: {resp.text[:500]}",
+        token_type="aa-auth+jwt",
+    )

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

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

{aauth-0.3.2 → aauth-0.3.4}/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,6 @@ 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_poller.py
+tests/test_token_exchange.py

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

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