traia-iatp 0.1.29__py3-none-any.whl

traia_iatp/d402/facilitator.py

@@ -0,0 +1,453 @@
+"""Custom d402 facilitator that interfaces with IATP Settlement Layer."""
+
+import logging
+from typing import Optional, Dict, Any
+from datetime import datetime
+import httpx
+from eth_account import Account
+from web3 import Web3
+from eth_account.messages import encode_defunct
+
+from .types import (
+    PaymentPayload,
+    PaymentRequirements,
+    VerifyResponse,
+    SettleResponse
+)
+from .models import IATPSettlementRequest
+
+logger = logging.getLogger(__name__)
+
+
+class IATPSettlementFacilitator:
+    """Custom d402 facilitator that settles payments through IATP Settlement Layer.
+    
+    This facilitator verifies d402 payment headers and then submits settlement
+    requests to the on-chain IATP Settlement Layer contract via a relayer service.
+    
+    Flow:
+    1. Utility agent receives request with X-PAYMENT header
+    2. Facilitator verifies the payment signature and authorization
+    3. Utility agent processes the request
+    4. Facilitator settles the payment by submitting to relayer
+    5. Relayer submits to IATPSettlementLayer.sol on-chain
+    """
+    
+    def __init__(
+        self,
+        relayer_url: str,
+        relayer_api_key: Optional[str] = None,
+        provider_operator_key: Optional[str] = None,
+        web3_provider: Optional[str] = None,
+        facilitator_url: Optional[str] = None,
+        facilitator_api_key: Optional[str] = None
+    ):
+        """Initialize the IATP Settlement Facilitator.
+        
+        Args:
+            relayer_url: URL of the Traia relayer service
+            relayer_api_key: Optional API key for relayer authentication
+            provider_operator_key: Operator private key for provider attestation
+            web3_provider: Optional Web3 provider URL for direct blockchain interaction
+            facilitator_url: Optional external facilitator URL for verification (if None, uses local verification)
+            facilitator_api_key: Optional API key for external facilitator
+        """
+        self.relayer_url = relayer_url.rstrip("/")
+        self.relayer_api_key = relayer_api_key
+        self.provider_operator_key = provider_operator_key
+        self.facilitator_url = facilitator_url.rstrip("/") if facilitator_url else None
+        self.facilitator_api_key = facilitator_api_key
+        
+        # Initialize Web3 if provider is given
+        self.w3 = Web3(Web3.HTTPProvider(web3_provider)) if web3_provider else None
+        
+        # Initialize operator account if key provided
+        self.operator_account = None
+        if provider_operator_key:
+            if provider_operator_key.startswith("0x"):
+                provider_operator_key = provider_operator_key[2:]
+            self.operator_account = Account.from_key(provider_operator_key)
+    
+    async def verify(
+        self,
+        payment: PaymentPayload,
+        payment_requirements: PaymentRequirements
+    ) -> VerifyResponse:
+        """Verify a payment header is valid.
+        
+        If facilitator_url is configured, calls external facilitator /verify endpoint
+        which returns a payment_uuid. Otherwise performs local verification.
+        
+        This checks:
+        1. Signature is valid
+        2. Authorization is not expired
+        3. Amount matches requirements
+        4. From address has sufficient balance
+        
+        Args:
+            payment: Payment payload from X-PAYMENT header
+            payment_requirements: Payment requirements from server
+            
+        Returns:
+            VerifyResponse with validation result and payment_uuid (if from external facilitator)
+        """
+        # If external facilitator URL is configured, call it
+        if self.facilitator_url:
+            try:
+                headers = {"Content-Type": "application/json"}
+                if self.facilitator_api_key:
+                    headers["Authorization"] = f"Bearer {self.facilitator_api_key}"
+                
+                verify_request = {
+                    "paymentPayload": payment.model_dump(by_alias=True),
+                    "paymentRequirements": payment_requirements.model_dump(by_alias=True)
+                }
+                
+                async with httpx.AsyncClient(timeout=30.0) as client:
+                    response = await client.post(
+                        f"{self.facilitator_url}/verify",
+                        json=verify_request,
+                        headers=headers
+                    )
+                    
+                    if response.status_code == 200:
+                        result = response.json()
+                        # Parse response and extract payment_uuid
+                        verify_response = VerifyResponse(**result)
+                        if verify_response.payment_uuid:
+                            logger.info(f"Payment verified via facilitator with payment_uuid: {verify_response.payment_uuid[:20]}...")
+                        return verify_response
+                    else:
+                        error_msg = f"Facilitator verify error: {response.status_code} - {response.text}"
+                        logger.error(error_msg)
+                        return VerifyResponse(
+                            is_valid=False,
+                            invalid_reason=error_msg,
+                            payer=None,
+                            payment_uuid=None
+                        )
+            except Exception as e:
+                logger.error(f"Error calling external facilitator verify: {e}")
+                # Fall back to local verification
+                logger.warning("Falling back to local verification")
+        
+        # Local verification (fallback or if no facilitator_url configured)
+        try:
+            # Extract payment details
+            if payment.scheme != "exact":
+                return VerifyResponse(
+                    is_valid=False,
+                    invalid_reason=f"Unsupported scheme: {payment.scheme}",
+                    payer=None,
+                    payment_uuid=None
+                )
+            
+            payload = payment.payload
+            authorization = payload.authorization
+            signature = payload.signature
+            
+            # Verify the signature matches the authorization
+            payer = authorization.from_
+            
+            # Reconstruct the EIP-712 message and verify signature
+            # This would use the exact EIP-712 domain from payment_requirements.extra
+            eip712_domain = payment_requirements.extra or {}
+            
+            # For now, perform basic validation
+            # In production, this should verify the EIP-3009 signature
+            if not payer or not signature:
+                return VerifyResponse(
+                    is_valid=False,
+                    invalid_reason="Missing payer or signature",
+                    payer=None,
+                    payment_uuid=None
+                )
+            
+            # Verify amount matches requirements
+            if authorization.value != payment_requirements.max_amount_required:
+                return VerifyResponse(
+                    is_valid=False,
+                    invalid_reason=f"Amount mismatch: expected {payment_requirements.max_amount_required}, got {authorization.value}",
+                    payer=payer,
+                    payment_uuid=None
+                )
+            
+            # Verify not expired
+            import time
+            current_time = int(time.time())
+            valid_after = int(authorization.valid_after)
+            valid_before = int(authorization.valid_before)
+            
+            if current_time < valid_after or current_time > valid_before:
+                return VerifyResponse(
+                    is_valid=False,
+                    invalid_reason="Authorization expired or not yet valid",
+                    payer=payer,
+                    payment_uuid=None
+                )
+            
+            # Verify to address matches pay_to
+            if authorization.to.lower() != payment_requirements.pay_to.lower():
+                return VerifyResponse(
+                    is_valid=False,
+                    invalid_reason=f"Pay-to address mismatch",
+                    payer=payer,
+                    payment_uuid=None
+                )
+            
+            # All checks passed (local verification - no payment_uuid)
+            return VerifyResponse(
+                is_valid=True,
+                invalid_reason=None,
+                payer=payer,
+                payment_uuid=None  # Local verification doesn't provide payment_uuid
+            )
+            
+        except Exception as e:
+            logger.error(f"Error verifying payment: {e}")
+            return VerifyResponse(
+                is_valid=False,
+                invalid_reason=f"Verification error: {str(e)}",
+                payer=None,
+                payment_uuid=None
+            )
+    
+    async def settle(
+        self,
+        payment: PaymentPayload,
+        payment_requirements: PaymentRequirements
+    ) -> SettleResponse:
+        """Settle a verified payment through the IATP Settlement Layer.
+        
+        This submits the payment to the relayer, which will:
+        1. Verify both consumer and provider signatures
+        2. Submit to IATPSettlementLayer.settleRequest()
+        3. Process the EIP-3009 authorization on-chain
+        4. Credit the provider's epoch balance
+        
+        Args:
+            payment: Verified payment payload
+            payment_requirements: Payment requirements
+            
+        Returns:
+            SettleResponse with settlement result
+        """
+        try:
+            payload = payment.payload
+            authorization = payload.authorization
+            consumer_signature = payload.signature
+            
+            # Create the service request struct (matches Solidity ServiceRequest)
+            service_request = {
+                "consumer": authorization.from_,
+                "provider": payment_requirements.pay_to,
+                "amount": authorization.value,
+                "timestamp": int(authorization.valid_after),
+                "serviceDescription": Web3.keccak(
+                    text=payment_requirements.description
+                ).hex()
+            }
+            
+            # Create provider attestation if operator key is available
+            provider_signature = None
+            extra = payment_requirements.extra or {}
+            output_hash = extra.get("output_hash")
+            payment_uuid = extra.get("payment_uuid")  # Primary payment identifier from facilitator verify
+            facilitator_fee_percent = extra.get("facilitator_fee_percent", 250)  # Get fee from facilitator verify response
+            
+            if not payment_uuid:
+                logger.warning("No payment_uuid in payment_requirements.extra - attestation may not be linkable")
+            
+            if self.operator_account:
+                # Create EIP-712 ProviderAttestation signature matching IATPWallet.sol
+                # ProviderAttestation(bytes32 consumerSignature, bytes32 outputHash, uint256 timestamp, bytes32 serviceDescription, uint256 facilitatorFeePercent)
+                
+                # Hash the consumer signature bytes
+                consumer_signature_hash = Web3.keccak(hexstr=consumer_signature)
+                
+                # Prepare output hash for contract verification
+                # Python: output_hash = keccak256(output_json) ← First hash (line 161 in mcp_middleware.py)
+                # Contract: outputHashHash = keccak256(outputHash bytes) ← Second hash (line 245 in IATPWallet.sol)
+                # Provider signs over outputHashHash (the double-hashed value)
+                if output_hash:
+                    # Output hash is hex string like "0xabcd..." (already hashed once)
+                    output_hash_bytes = bytes.fromhex(output_hash[2:] if output_hash.startswith("0x") else output_hash)
+                    # Hash it again to match what contract will compute: keccak256(outputHash)
+                    output_hash_hash = Web3.keccak(output_hash_bytes)
+                    logger.debug(f"Output hash (1st): {output_hash[:20]}...")
+                    logger.debug(f"Output hash (2nd): {output_hash_hash.hex()[:20]}...")
+                else:
+                    # Use zero hash if no output provided
+                    output_hash_hash = Web3.keccak(b"")
+                
+                # Get service description hash
+                service_description_hash = Web3.keccak(text=payment_requirements.description)
+                
+                # Attestation timestamp
+                attestation_timestamp = int(authorization.valid_after)
+                
+                # Build EIP-712 typed data for ProviderAttestation
+                # Domain should be the Provider's IATPWallet domain
+                from .chains import get_chain_id
+                
+                typed_data = {
+                    "types": {
+                        "ProviderAttestation": [
+                            {"name": "consumerSignature", "type": "bytes32"},
+                            {"name": "outputHash", "type": "bytes32"},
+                            {"name": "timestamp", "type": "uint256"},
+                            {"name": "serviceDescription", "type": "bytes32"},
+                            {"name": "facilitatorFeePercent", "type": "uint256"},
+                        ]
+                    },
+                    "primaryType": "ProviderAttestation",
+                    "domain": {
+                        "name": "IATPWallet",
+                        "version": "1",
+                        "chainId": int(get_chain_id(payment.network)),
+                        "verifyingContract": payment_requirements.pay_to,  # Provider's IATPWallet address
+                    },
+                    "message": {
+                        "consumerSignature": consumer_signature_hash,
+                        "outputHash": output_hash_hash,
+                        "timestamp": attestation_timestamp,
+                        "serviceDescription": service_description_hash,
+                        "facilitatorFeePercent": facilitator_fee_percent,
+                    },
+                }
+                
+                # Sign with provider's operator key
+                signed = self.operator_account.sign_typed_data(
+                    domain_data=typed_data["domain"],
+                    message_types=typed_data["types"],
+                    message_data=typed_data["message"],
+                )
+                provider_signature = signed.signature.hex()
+                if not provider_signature.startswith("0x"):
+                    provider_signature = f"0x{provider_signature}"
+                
+                logger.info(f"Provider attestation (EIP-712) created:")
+                if output_hash:
+                    logger.info(f"  Output hash: {output_hash[:20]}...")
+                if payment_uuid:
+                    logger.info(f"  Payment UUID: {payment_uuid[:20]}...")
+                logger.info(f"  Facilitator fee: {facilitator_fee_percent} basis points ({facilitator_fee_percent/100}%)")
+            
+            # Prepare settlement request for relayer
+            settlement_request = {
+                "signedRequest": consumer_signature,
+                "serviceRequest": service_request,
+                "providerSignature": provider_signature or "0x",
+                "attestationTimestamp": int(get_now_in_utc().timestamp()),
+                "network": payment.network,
+                "outputHash": output_hash or "0x",  # Include output hash (proof of service completion)
+                "paymentUuid": payment_uuid or "0x"  # Include payment_uuid (primary payment identifier)
+            }
+            
+            # Submit to relayer
+            headers = {"Content-Type": "application/json"}
+            if self.relayer_api_key:
+                headers["Authorization"] = f"Bearer {self.relayer_api_key}"
+            
+            async with httpx.AsyncClient(timeout=30.0) as client:
+                response = await client.post(
+                    f"{self.relayer_url}/settle",
+                    json=settlement_request,
+                    headers=headers
+                )
+                
+                if response.status_code == 200:
+                    result = response.json()
+                    return SettleResponse(
+                        success=True,
+                        error_reason=None,
+                        transaction=result.get("transactionHash"),
+                        network=payment.network,
+                        payer=authorization.from_
+                    )
+                else:
+                    error_msg = f"Relayer error: {response.status_code} - {response.text}"
+                    logger.error(error_msg)
+                    return SettleResponse(
+                        success=False,
+                        error_reason=error_msg,
+                        transaction=None,
+                        network=payment.network,
+                        payer=authorization.from_
+                    )
+                    
+        except Exception as e:
+            logger.error(f"Error settling payment: {e}")
+            return SettleResponse(
+                success=False,
+                error_reason=f"Settlement error: {str(e)}",
+                transaction=None,
+                network=payment.network,
+                payer=None
+            )
+    
+    async def list(self, request: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """List discoverable IATP services that accept d402 payments.
+        
+        This queries the Traia registry for utility agents with d402 enabled.
+        
+        Args:
+            request: Optional filters for discovery
+            
+        Returns:
+            List of discoverable services
+        """
+        # This would query the MongoDB registry
+        # For now, return empty list
+        return {
+            "d402Version": 1,
+            "items": [],
+            "pagination": {
+                "limit": 100,
+                "offset": 0,
+                "total": 0
+            }
+        }
+
+
+def create_iatp_facilitator(
+    relayer_url: str = "https://api.traia.io/relayer",
+    relayer_api_key: Optional[str] = None,
+    provider_operator_key: Optional[str] = None,
+    web3_provider: Optional[str] = None
+) -> IATPSettlementFacilitator:
+    """Convenience function to create an IATP Settlement Facilitator.
+    
+    Args:
+        relayer_url: URL of the Traia relayer service
+        relayer_api_key: Optional API key for relayer
+        provider_operator_key: Provider's operator private key
+        web3_provider: Optional Web3 provider URL
+        
+    Returns:
+        Configured IATPSettlementFacilitator
+        
+    Example:
+        facilitator = create_iatp_facilitator(
+            relayer_url="https://api.traia.io/relayer",
+            relayer_api_key=os.getenv("TRAIA_RELAYER_API_KEY"),
+            provider_operator_key=os.getenv("OPERATOR_PRIVATE_KEY")
+        )
+        
+        # Use in d402 middleware
+        from traia_iatp.d402 import D402Config, require_iatp_payment
+        
+        config = D402Config(
+            enabled=True,
+            pay_to_address="0x...",  # Utility agent contract address
+            default_price=D402ServicePrice(...),
+            facilitator_url="custom"  # Will use custom facilitator
+        )
+    """
+    return IATPSettlementFacilitator(
+        relayer_url=relayer_url,
+        relayer_api_key=relayer_api_key,
+        provider_operator_key=provider_operator_key,
+        web3_provider=web3_provider
+    )
+

traia_iatp/d402/fastapi_middleware/__init__.py

@@ -0,0 +1,6 @@
+"""FastAPI middleware for d402 payments."""
+
+from .middleware import require_payment
+
+__all__ = ["require_payment"]
+

traia_iatp/d402/fastapi_middleware/middleware.py

@@ -0,0 +1,225 @@
+import base64
+import json
+import logging
+from typing import Any, Callable, Optional, get_args, cast
+
+from fastapi import Request
+from fastapi.responses import JSONResponse, HTMLResponse
+from pydantic import validate_call
+
+from ..common import (
+    process_price_to_atomic_amount,
+    d402_VERSION,
+    find_matching_payment_requirements,
+)
+from ..encoding import safe_base64_decode
+# FacilitatorClient not used - we use custom IATP facilitator
+from typing import Optional
+from typing_extensions import TypedDict
+
+class FacilitatorConfig(TypedDict, total=False):
+    url: str
+    create_headers: Callable[[], dict[str, dict[str, str]]]
+from ..path import path_is_match
+from ..paywall import is_browser_request, get_paywall_html
+from ..types import (
+    PaymentPayload,
+    PaymentRequirements,
+    Price,
+    d402PaymentRequiredResponse,
+    PaywallConfig,
+    SupportedNetworks,
+    HTTPInputSchema,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@validate_call
+def require_payment(
+    price: Price,
+    pay_to_address: str,
+    path: str | list[str] = "*",
+    description: str = "",
+    mime_type: str = "",
+    max_deadline_seconds: int = 60,
+    input_schema: Optional[HTTPInputSchema] = None,
+    output_schema: Optional[Any] = None,
+    discoverable: Optional[bool] = True,
+    facilitator_config: Optional[FacilitatorConfig] = None,
+    network: str = "base-sepolia",
+    resource: Optional[str] = None,
+    paywall_config: Optional[PaywallConfig] = None,
+    custom_paywall_html: Optional[str] = None,
+):
+    """Generate a FastAPI middleware that gates payments for an endpoint.
+
+    Args:
+        price (Price): Payment price. Can be:
+            - Money: USD amount as string/int (e.g., "$3.10", 0.10, "0.001") - defaults to USDC
+            - TokenAmount: Custom token amount with asset information
+        pay_to_address (str): Ethereum address to receive the payment
+        path (str | list[str], optional): Path to gate with payments. Defaults to "*" for all paths.
+        description (str, optional): Description of what is being purchased. Defaults to "".
+        mime_type (str, optional): MIME type of the resource. Defaults to "".
+        max_deadline_seconds (int, optional): Maximum time allowed for payment. Defaults to 60.
+        input_schema (Optional[HTTPInputSchema], optional): Schema for the request structure. Defaults to None.
+        output_schema (Optional[Any], optional): Schema for the response. Defaults to None.
+        discoverable (bool, optional): Whether the route is discoverable. Defaults to True.
+        facilitator_config (Optional[Dict[str, Any]], optional): Configuration for the payment facilitator.
+            If not provided, defaults to the public d402.org facilitator.
+        network (str, optional): Ethereum network ID. Defaults to "base-sepolia" (Base Sepolia testnet).
+        resource (Optional[str], optional): Resource URL. Defaults to None (uses request URL).
+        paywall_config (Optional[PaywallConfig], optional): Configuration for paywall UI customization.
+            Includes options like cdp_client_key, app_name, app_logo, session_token_endpoint.
+        custom_paywall_html (Optional[str], optional): Custom HTML to display for paywall instead of default.
+
+    Returns:
+        Callable: FastAPI middleware function that checks for valid payment before processing requests
+    """
+
+    # Validate network is supported
+    supported_networks = get_args(SupportedNetworks)
+    if network not in supported_networks:
+        raise ValueError(
+            f"Unsupported network: {network}. Must be one of: {supported_networks}"
+        )
+
+    try:
+        max_amount_required, asset_address, eip712_domain = (
+            process_price_to_atomic_amount(price, network)
+        )
+    except Exception as e:
+        raise ValueError(f"Invalid price: {price}. Error: {e}")
+
+    facilitator = FacilitatorClient(facilitator_config)
+
+    async def middleware(request: Request, call_next: Callable):
+        # Skip if the path is not the same as the path in the middleware
+        if not path_is_match(path, request.url.path):
+            return await call_next(request)
+
+        # Get resource URL if not explicitly provided
+        resource_url = resource or str(request.url)
+
+        # Construct payment details
+        payment_requirements = [
+            PaymentRequirements(
+                scheme="exact",
+                network=cast(SupportedNetworks, network),
+                asset=asset_address,
+                max_amount_required=max_amount_required,
+                resource=resource_url,
+                description=description,
+                mime_type=mime_type,
+                pay_to=pay_to_address,
+                max_timeout_seconds=max_deadline_seconds,
+                # TODO: Rename output_schema to request_structure
+                output_schema={
+                    "input": {
+                        "type": "http",
+                        "method": request.method.upper(),
+                        "discoverable": discoverable
+                        if discoverable is not None
+                        else True,
+                        **(input_schema.model_dump() if input_schema else {}),
+                    },
+                    "output": output_schema,
+                },
+                extra=eip712_domain,
+            )
+        ]
+
+        def d402_response(error: str):
+            """Create a 402 response with payment requirements."""
+            request_headers = dict(request.headers)
+            status_code = 402
+
+            if is_browser_request(request_headers):
+                html_content = custom_paywall_html or get_paywall_html(
+                    error, payment_requirements, paywall_config
+                )
+                headers = {"Content-Type": "text/html; charset=utf-8"}
+
+                return HTMLResponse(
+                    content=html_content,
+                    status_code=status_code,
+                    headers=headers,
+                )
+            else:
+                response_data = d402PaymentRequiredResponse(
+                    d402_version=d402_VERSION,
+                    accepts=payment_requirements,
+                    error=error,
+                ).model_dump(by_alias=True)
+                headers = {"Content-Type": "application/json"}
+
+                return JSONResponse(
+                    content=response_data,
+                    status_code=status_code,
+                    headers=headers,
+                )
+
+        # Check for payment header
+        payment_header = request.headers.get("X-PAYMENT", "")
+
+        if payment_header == "":
+            return d402_response("No X-PAYMENT header provided")
+
+        # Decode payment header
+        try:
+            payment_dict = json.loads(safe_base64_decode(payment_header))
+            payment = PaymentPayload(**payment_dict)
+        except Exception as e:
+            logger.warning(
+                f"Invalid payment header format from {request.client.host if request.client else 'unknown'}: {str(e)}"
+            )
+            return d402_response("Invalid payment header format")
+
+        # Find matching payment requirements
+        selected_payment_requirements = find_matching_payment_requirements(
+            payment_requirements, payment
+        )
+
+        if not selected_payment_requirements:
+            return d402_response("No matching payment requirements found")
+
+        # Verify payment
+        verify_response = await facilitator.verify(
+            payment, selected_payment_requirements
+        )
+
+        if not verify_response.is_valid:
+            error_reason = verify_response.invalid_reason or "Unknown error"
+            return d402_response(f"Invalid payment: {error_reason}")
+
+        request.state.payment_details = selected_payment_requirements
+        request.state.verify_response = verify_response
+
+        # Process the request
+        response = await call_next(request)
+
+        # Early return without settling if the response is not a 2xx
+        if response.status_code < 200 or response.status_code >= 300:
+            return response
+
+        # Settle the payment
+        try:
+            settle_response = await facilitator.settle(
+                payment, selected_payment_requirements
+            )
+            if settle_response.success:
+                response.headers["X-PAYMENT-RESPONSE"] = base64.b64encode(
+                    settle_response.model_dump_json(by_alias=True).encode("utf-8")
+                ).decode("utf-8")
+            else:
+                return d402_response(
+                    "Settle failed: "
+                    + (settle_response.error_reason or "Unknown error")
+                )
+        except Exception:
+            return d402_response("Settle failed")
+
+        return response
+
+    return middleware