traia-iatp 0.1.29__py3-none-any.whl

traia_iatp/d402/payment_signing.py

@@ -0,0 +1,178 @@
+import time
+import secrets
+from typing import Dict, Any
+from typing_extensions import (
+    TypedDict,
+)  # use `typing_extensions.TypedDict` instead of `typing.TypedDict` on Python < 3.12
+from eth_account import Account
+from .encoding import safe_base64_encode, safe_base64_decode
+from .types import (
+    PaymentRequirements,
+)
+from .chains import get_chain_id
+import json
+
+
+def create_nonce() -> bytes:
+    """Create a random 32-byte nonce for authorization signatures."""
+    return secrets.token_bytes(32)
+
+
+def prepare_payment_header(
+    sender_address: str, d402_version: int, payment_requirements: PaymentRequirements
+) -> Dict[str, Any]:
+    """Prepare an unsigned payment header with sender address, d402 version, and payment requirements."""
+    nonce = create_nonce()
+    valid_after = str(int(time.time()) - 60)  # 60 seconds before
+    valid_before = str(int(time.time()) + payment_requirements.max_timeout_seconds)
+
+    return {
+        "d402Version": d402_version,
+        "scheme": payment_requirements.scheme,
+        "network": payment_requirements.network,
+        "payload": {
+            "signature": None,
+            "authorization": {
+                "from": sender_address,
+                "to": payment_requirements.pay_to,
+                "value": payment_requirements.max_amount_required,
+                "validAfter": valid_after,
+                "validBefore": valid_before,
+                "nonce": nonce,
+            },
+        },
+    }
+
+
+class PaymentHeader(TypedDict):
+    d402Version: int
+    scheme: str
+    network: str
+    payload: dict[str, Any]
+
+
+def sign_payment_header(
+    operator_account: Account, 
+    payment_requirements: PaymentRequirements, 
+    header: PaymentHeader,
+    wallet_address: str = None,
+    request_path: str = None
+) -> str:
+    """
+    Sign a payment header using EIP-712 PullFundsForSettlement signature.
+    
+    This signature format matches IATPWallet.sol validateConsumerSignature.
+    
+    Contract Type Hash (IATPWallet.sol line 34-36):
+    PullFundsForSettlement(
+        address wallet,      // Consumer's IATPWallet contract address
+        address provider,    // Provider's IATPWallet contract address
+        address token,       // Token address (USDC, etc.)
+        uint256 amount,      // Payment amount
+        uint256 deadline,    // Signature expiration
+        string requestPath   // API path (e.g., "/mcp/tools/call")
+    )
+    
+    Note: chainId is in the EIP-712 domain, NOT in the message (per EIP-712 standard)
+    
+    Args:
+        operator_account: Operator account with private key for signing (EOA)
+        payment_requirements: Payment requirements from server
+        header: Payment header structure
+        wallet_address: Consumer's IATPWallet contract address (if None, uses operator_account.address)
+        request_path: API request path (if None, uses payment_requirements.resource)
+    """
+    try:
+        auth = header["payload"]["authorization"]
+        
+        # Get wallet address (IATPWallet contract, not EOA)
+        consumer_wallet = wallet_address or auth["from"]
+        
+        # Get request path from payment_requirements if not provided
+        if request_path is None:
+            request_path = payment_requirements.resource or "/mcp"
+            logger.info(f"🔍 payment_requirements.resource: {payment_requirements.resource}")
+            logger.info(f"🔍 Using request_path: {request_path}")
+        
+        # Ensure we have a valid request path (contract requires non-empty string)
+        if not request_path or request_path.strip() == "":
+            logger.warning(f"⚠️  request_path was empty, defaulting to /mcp")
+            request_path = "/mcp"
+        
+        # Get domain info from payment_requirements.extra (IATPWallet domain)
+        extra = payment_requirements.extra or {}
+        wallet_name = extra.get("name", "IATPWallet")
+        wallet_version = extra.get("version", "1")
+        
+        # Build EIP-712 typed data for PullFundsForSettlement
+        # Note: chainId is in the domain, not the message (EIP-712 standard)
+        typed_data = {
+            "types": {
+                "PullFundsForSettlement": [
+                    {"name": "wallet", "type": "address"},
+                    {"name": "provider", "type": "address"},
+                    {"name": "token", "type": "address"},
+                    {"name": "amount", "type": "uint256"},
+                    {"name": "deadline", "type": "uint256"},
+                    {"name": "requestPath", "type": "string"},
+                ]
+            },
+            "primaryType": "PullFundsForSettlement",
+            "domain": {
+                "name": wallet_name,
+                "version": wallet_version,
+                "chainId": int(get_chain_id(payment_requirements.network)),  # chainId in domain only
+                "verifyingContract": consumer_wallet,  # Consumer's IATPWallet contract
+            },
+            "message": {
+                "wallet": consumer_wallet,  # Consumer's IATPWallet contract address
+                "provider": auth["to"],  # Provider's IATPWallet contract address
+                "token": payment_requirements.asset,  # Token address (e.g., USDC)
+                "amount": int(auth["value"]),
+                "deadline": int(auth["validBefore"]),
+                "requestPath": request_path,  # Actual API path, not nonce
+            },
+        }
+
+        signed_message = operator_account.sign_typed_data(
+            domain_data=typed_data["domain"],
+            message_types=typed_data["types"],
+            message_data=typed_data["message"],
+        )
+        signature = signed_message.signature.hex()
+        if not signature.startswith("0x"):
+            signature = f"0x{signature}"
+
+        header["payload"]["signature"] = signature
+        
+        # Store wallet address and request path in header for verification
+        header["payload"]["authorization"]["from"] = consumer_wallet
+        header["payload"]["authorization"]["requestPath"] = request_path
+
+        encoded = encode_payment(header)
+        return encoded
+    except Exception:
+        raise
+
+
+def encode_payment(payment_payload: Dict[str, Any]) -> str:
+    """Encode a payment payload into a base64 string, handling HexBytes and other non-serializable types."""
+    from hexbytes import HexBytes
+
+    def default(obj):
+        if isinstance(obj, HexBytes):
+            return obj.hex()
+        if hasattr(obj, "to_dict"):
+            return obj.to_dict()
+        if hasattr(obj, "hex"):
+            return obj.hex()
+        raise TypeError(
+            f"Object of type {obj.__class__.__name__} is not JSON serializable"
+        )
+
+    return safe_base64_encode(json.dumps(payment_payload, default=default))
+
+
+def decode_payment(encoded_payment: str) -> Dict[str, Any]:
+    """Decode a base64 encoded payment string back into a PaymentPayload object."""
+    return json.loads(safe_base64_decode(encoded_payment))

traia_iatp/d402/paywall.py

@@ -0,0 +1,119 @@
+import json
+from typing import Dict, Any, List, Optional
+
+from .types import PaymentRequirements, PaywallConfig
+from .common import d402_VERSION
+from .template import PAYWALL_TEMPLATE
+
+
+def is_browser_request(headers: Dict[str, Any]) -> bool:
+    """
+    Determine if request is from a browser vs API client.
+
+    Args:
+        headers: Dictionary of request headers (case-insensitive keys)
+
+    Returns:
+        True if request appears to be from a browser, False otherwise
+    """
+    headers_lower = {k.lower(): v for k, v in headers.items()}
+    accept_header = headers_lower.get("accept", "")
+    user_agent = headers_lower.get("user-agent", "")
+
+    if "text/html" in accept_header and "Mozilla" in user_agent:
+        return True
+
+    return False
+
+
+def create_d402_config(
+    error: str,
+    payment_requirements: List[PaymentRequirements],
+    paywall_config: Optional[PaywallConfig] = None,
+) -> Dict[str, Any]:
+    """Create d402 configuration object from payment requirements."""
+
+    requirements = payment_requirements[0] if payment_requirements else None
+    display_amount = 0
+    current_url = ""
+    testnet = True
+
+    if requirements:
+        # Convert atomic amount back to USD (assuming USDC with 6 decimals)
+        try:
+            display_amount = (
+                float(requirements.max_amount_required) / 1000000
+            )  # USDC has 6 decimals
+        except (ValueError, TypeError):
+            display_amount = 0
+
+        current_url = requirements.resource or ""
+        testnet = requirements.network == "base-sepolia"
+
+    # Get paywall config values or defaults
+    config = paywall_config or {}
+
+    # Create the window.d402 configuration object
+    return {
+        "amount": display_amount,
+        "paymentRequirements": [
+            req.model_dump(by_alias=True) for req in payment_requirements
+        ],
+        "testnet": testnet,
+        "currentUrl": current_url,
+        "error": error,
+        "d402_version": d402_VERSION,
+        "cdpClientKey": config.get("cdp_client_key", ""),
+        "appName": config.get("app_name", ""),
+        "appLogo": config.get("app_logo", ""),
+        "sessionTokenEndpoint": config.get("session_token_endpoint", ""),
+    }
+
+
+def inject_payment_data(
+    html_content: str,
+    error: str,
+    payment_requirements: List[PaymentRequirements],
+    paywall_config: Optional[PaywallConfig] = None,
+) -> str:
+    """Inject payment requirements into HTML as JavaScript variables."""
+
+    # Create d402 configuration object
+    d402_config = create_d402_config(error, payment_requirements, paywall_config)
+
+    # Create the configuration script (matching TypeScript pattern)
+    log_on_testnet = (
+        "console.log('Payment requirements initialized:', window.d402);"
+        if d402_config["testnet"]
+        else ""
+    )
+
+    config_script = f"""
+  <script>
+    window.d402 = {json.dumps(d402_config)};
+    {log_on_testnet}
+  </script>"""
+
+    # Inject the configuration script into the head (same as TypeScript)
+    return html_content.replace("</head>", f"{config_script}\n</head>")
+
+
+def get_paywall_html(
+    error: str,
+    payment_requirements: List[PaymentRequirements],
+    paywall_config: Optional[PaywallConfig] = None,
+) -> str:
+    """
+    Load paywall HTML and inject payment data.
+
+    Args:
+        error: Error message to display
+        payment_requirements: List of payment requirements
+        paywall_config: Optional paywall UI configuration
+
+    Returns:
+        Complete HTML with injected payment data
+    """
+    return inject_payment_data(
+        PAYWALL_TEMPLATE, error, payment_requirements, paywall_config
+    )

traia_iatp/d402/starlette_middleware.py

@@ -0,0 +1,326 @@
+"""
+Starlette middleware adaptors for d402 payment protocol.
+
+These middleware classes work with Starlette apps (like FastMCP's streamable_http_app())
+to provide HTTP 402 payment support and authentication.
+"""
+
+import logging
+import json
+import os
+from typing import Dict, Any, Optional
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from .types import PaymentRequirements, d402PaymentRequiredResponse, PaymentPayload
+from .common import d402_VERSION
+from .facilitator import IATPSettlementFacilitator
+from .encoding import safe_base64_decode
+
+logger = logging.getLogger(__name__)
+
+
+class D402PaymentMiddleware(BaseHTTPMiddleware):
+    """
+    Starlette middleware that intercepts MCP tool calls for HTTP 402 payment.
+    
+    This middleware:
+    1. Extracts API key if present → stores in request.state
+    2. Checks if tool requires payment
+    3. Returns HTTP 402 if neither auth nor payment
+    4. Sets request.state.api_key_to_use with the resolved key
+    5. Forwards to FastMCP
+    
+    Usage:
+        app = mcp.streamable_http_app()
+        app.add_middleware(
+            D402PaymentMiddleware,
+            tool_payment_configs=TOOL_PAYMENT_CONFIGS,
+            server_address=SERVER_ADDRESS,
+            requires_auth=True,
+            internal_api_key="server_api_key"  # Server's internal key
+        )
+    """
+    
+    def __init__(
+        self,
+        app,
+        tool_payment_configs: Dict[str, Dict[str, Any]],
+        server_address: str,
+        requires_auth: bool = False,
+        internal_api_key: Optional[str] = None,
+        testing_mode: bool = False,
+        facilitator_url: Optional[str] = None,
+        facilitator_api_key: Optional[str] = None
+    ):
+        super().__init__(app)
+        self.tool_payment_configs = tool_payment_configs
+        self.server_address = server_address
+        self.requires_auth = requires_auth
+        self.internal_api_key = internal_api_key  # Server's internal API key
+        self.testing_mode = testing_mode or os.getenv("D402_TESTING_MODE", "false").lower() == "true"
+        
+        # Initialize facilitator for payment verification and settlement
+        self.facilitator = None
+        if not self.testing_mode:
+            try:
+                operator_key = os.getenv("MCP_OPERATOR_PRIVATE_KEY") or os.getenv("OPERATOR_PRIVATE_KEY")
+                self.facilitator = IATPSettlementFacilitator(
+                    relayer_url=facilitator_url or os.getenv("D402_FACILITATOR_URL", "https://facilitator.d402.net"),
+                    relayer_api_key=facilitator_api_key or os.getenv("D402_FACILITATOR_API_KEY"),
+                    provider_operator_key=operator_key,
+                    facilitator_url=facilitator_url or os.getenv("D402_FACILITATOR_URL", "https://facilitator.d402.net"),
+                    facilitator_api_key=facilitator_api_key or os.getenv("D402_FACILITATOR_API_KEY")
+                )
+                if operator_key:
+                    logger.info(f"  Facilitator initialized with operator key (settlement enabled)")
+                else:
+                    logger.warning(f"  No operator key - settlement disabled")
+            except Exception as e:
+                logger.warning(f"  Could not initialize facilitator: {e}")
+                self.testing_mode = True
+        
+        logger.info(f"D402PaymentMiddleware initialized:")
+        logger.info(f"  Payment-enabled tools: {len(tool_payment_configs)}")
+        logger.info(f"  Server address: {server_address}")
+        logger.info(f"  Testing mode: {self.testing_mode}")
+        logger.info(f"  Facilitator: {'Enabled' if self.facilitator else 'Disabled (testing)'}")
+    
+    async def dispatch(self, request: Request, call_next):
+        """
+        Intercept requests for auth and payment checking.
+        
+        Handles both:
+        1. If server requires auth: Extract API key and store in request.state
+        2. If tool requires payment: Check payment or auth, return HTTP 402 if missing
+        """
+        
+        # Step 1: Store middleware reference for decorator access (for settlement)
+        request.state.d402_middleware = self
+        
+        # Step 2: Extract and store API key if present (for all requests)
+        if self.requires_auth:
+            auth = request.headers.get("Authorization", "")
+            if auth.lower().startswith("bearer "):
+                token = auth[7:].strip()
+                request.state.api_key = token
+                request.state.authenticated = True
+                logger.debug(f"D402: API key stored: {token[:10]}...")
+            elif request.headers.get("X-API-KEY"):
+                token = request.headers.get("X-API-KEY")
+                request.state.api_key = token
+                request.state.authenticated = True
+                logger.debug(f"D402: X-API-KEY stored: {token[:10]}...")
+            else:
+                request.state.api_key = None
+                request.state.authenticated = False
+        
+        # Step 2: Check payment for tool calls
+        # Only intercept POST to /mcp
+        if request.method != "POST" or not request.url.path.startswith("/mcp"):
+            return await call_next(request)
+        
+        try:
+            # Read body to check tool name
+            body = await request.body()
+            data = json.loads(body)
+            
+            # Check if it's a tool call
+            if data.get("method") == "tools/call":
+                tool_name = data.get("params", {}).get("name")
+                
+                # Calculate tool-specific path for signature binding
+                # For MCP servers: /mcp/tools/{tool_name}
+                # For other servers: use the actual HTTP path
+                if request.url.path.rstrip('/').endswith('/mcp'):
+                    base_path = request.url.path.rstrip('/')
+                    tool_path = f"{base_path}/tools/{tool_name}"
+                else:
+                    tool_path = request.url.path
+                
+                # Check if tool requires payment
+                if tool_name in self.tool_payment_configs:
+                    # Mode 1: If server requires auth AND client has API key → FREE
+                    if self.requires_auth and request.state.authenticated:
+                        logger.info(f"✅ {tool_name}: Client authenticated with API key (Mode 1: Free)")
+                        # Set api_key_to_use = client's key
+                        request.state.api_key_to_use = request.state.api_key
+                        # Continue to FastMCP
+                        return await self._continue_with_body(request, body, call_next)
+                    
+                    # Mode 2: Check payment → Client must pay, server uses internal API key
+                    payment_header = request.headers.get("X-Payment")
+                    if not payment_header:
+                        logger.info(f"💰 {tool_name}: Payment required (Mode 2) - HTTP 402")
+                        config = self.tool_payment_configs[tool_name]
+                        return self._create_402_response(config, "Payment required", request_path=tool_path)
+                    else:
+                        # Payment header present - VALIDATE IT!
+                        logger.info(f"💰 {tool_name}: Payment header RECEIVED - validating...")
+                        logger.info(f"📦 Payment header length: {len(payment_header)} bytes")
+                        
+                        # TODO: Add full payment validation:
+                        # 1. Decode and parse payment header
+                        # 2. Verify EIP-3009 signature
+                        # 3. Check amount >= required
+                        # 4. Verify pay_to == SERVER_ADDRESS
+                        # 5. Check timestamp validity
+                        # 6. Call facilitator.verify() if not testing mode
+                        
+                        # For now: Basic validation in testing mode
+                        try:
+                            from .encoding import safe_base64_decode
+                            payment_data = safe_base64_decode(payment_header)
+                            if not payment_data:
+                                logger.error(f"❌ {tool_name}: Invalid payment encoding")
+                                # Return 402 with error
+                                config = self.tool_payment_configs[tool_name]
+                                return self._create_402_response(config, "Invalid payment encoding", request_path=tool_path)
+                            
+                            payment_dict = json.loads(payment_data)
+                            
+                            # Basic validation: check structure
+                            if not payment_dict.get("payload") or not payment_dict["payload"].get("authorization"):
+                                logger.error(f"❌ {tool_name}: Invalid payment structure")
+                                config = self.tool_payment_configs[tool_name]
+                                return self._create_402_response(config, "Invalid payment structure", request_path=tool_path)
+                            
+                            auth = payment_dict["payload"]["authorization"]
+                            
+                            # Verify payment destination
+                            if auth.get("to", "").lower() != self.server_address.lower():
+                                logger.error(f"❌ {tool_name}: Payment to wrong address")
+                                config = self.tool_payment_configs[tool_name]
+                                return self._create_402_response(config, "Payment to wrong address", request_path=tool_path)
+                            
+                            # Verify payment amount
+                            config = self.tool_payment_configs[tool_name]
+                            payment_amount = int(auth.get("value", 0))
+                            required_amount = int(config["price_wei"])
+                            
+                            if payment_amount < required_amount:
+                                logger.error(f"❌ {tool_name}: Insufficient payment: {payment_amount} < {required_amount}")
+                                return self._create_402_response(config, f"Insufficient payment: {payment_amount} < {required_amount}", request_path=tool_path)
+                            
+                            # Call facilitator.verify() if available (production mode)
+                            if self.facilitator and not self.testing_mode:
+                                try:
+                                    # Create PaymentPayload for facilitator
+                                    payment_payload = PaymentPayload.model_validate(payment_dict)
+                                    
+                                    # Create PaymentRequirements with full token info
+                                    payment_reqs = PaymentRequirements(
+                                        scheme="exact",
+                                        network=config["network"],
+                                        pay_to=config["server_address"],
+                                        max_amount_required=config["price_wei"],
+                                        max_timeout_seconds=300,
+                                        description=config["description"],
+                                        resource="",
+                                        mime_type="application/json",
+                                        asset=config["token_address"],
+                                        extra=None
+                                    )
+                                    
+                                    # Verify with facilitator
+                                    logger.info(f"🔐 Verifying payment with facilitator...")
+                                    #==============================================================
+                                    verify_result = await self.facilitator.verify(payment_payload, payment_reqs)
+                                    #==============================================================
+                                    logger.info(f"🔐 Facilitator verify result: {verify_result}")
+                                    if not verify_result.is_valid:
+                                        logger.error(f"❌ {tool_name}: Facilitator rejected payment: {verify_result.invalid_reason}")
+                                        return self._create_402_response(config, f"Payment verification failed: {verify_result.invalid_reason}", request_path=tool_path)
+                                    
+                                    # Store payment_uuid and facilitatorFeePercent for settlement
+                                    request.state.payment_uuid = verify_result.payment_uuid
+                                    request.state.facilitator_fee_percent = verify_result.facilitator_fee_percent or 250
+                                    logger.info(f"✅ {tool_name}: Facilitator verified payment (UUID: {verify_result.payment_uuid[:20] if verify_result.payment_uuid else 'N/A'}...)")
+                                    logger.info(f"   Facilitator fee: {request.state.facilitator_fee_percent} basis points")
+                                    
+                                except Exception as e:
+                                    logger.error(f"❌ {tool_name}: Facilitator error: {e}")
+                                    return self._create_402_response(config, f"Facilitator verification failed: {str(e)}", request_path=tool_path)
+                            else:
+                                logger.info(f"⚠️  {tool_name}: Testing mode - skipping facilitator verification")
+                            
+                            # Payment validated! Set api_key_to_use
+                            logger.info(f"✅ {tool_name}: Payment VERIFIED successfully (Mode 2: Paid)")
+                            logger.info(f"   Payment amount: {payment_amount} wei (required: {required_amount} wei)")
+                            logger.info(f"   From (wallet): {auth.get('from', 'unknown')}")
+                            logger.info(f"   To (provider): {auth.get('to', 'unknown')}")
+                            logger.info(f"   Request path: {auth.get('requestPath', auth.get('request_path', 'unknown'))}")
+                            request.state.api_key_to_use = self.internal_api_key
+                            request.state.payment_validated = True
+                            request.state.payment_dict = payment_dict
+                            
+                            # Store payment info for settlement
+                            request.state.payment_payload = PaymentPayload.model_validate(payment_dict)
+                            logger.info(f"💾 {tool_name}: Payment payload stored for settlement")
+                            
+                        except Exception as e:
+                            logger.error(f"❌ {tool_name}: Payment validation error: {e}")
+                            config = self.tool_payment_configs[tool_name]
+                            return self._create_402_response(config, f"Payment validation failed: {str(e)}", request_path=tool_path)
+            
+            # Continue with reconstructed request
+            return await self._continue_with_body(request, body, call_next)
+            
+        except Exception as e:
+            logger.error(f"Error in D402PaymentMiddleware: {e}")
+            import traceback
+            logger.error(traceback.format_exc())
+            # Continue on error
+            return await call_next(request)
+    
+    async def _continue_with_body(self, request: Request, body: bytes, call_next):
+        """Continue request processing with body we already read."""
+        # Create new request with reconstructed receive
+        async def receive():
+            return {"type": "http.request", "body": body, "more_body": False}
+        
+        from starlette.requests import Request as NewRequest
+        new_request = NewRequest(request.scope, receive)
+        return await call_next(new_request)
+    
+    def _create_402_response(self, config: Dict[str, Any], error_message: str, request_path: str = "/mcp") -> JSONResponse:
+        """Helper to create HTTP 402 response with request path for signature binding."""
+        # Include EIP712 domain in extra for client to sign payment
+        # This should be IATPWallet domain (consumer's wallet contract)
+        extra_data = config.get("eip712_domain", {
+            "name": "IATPWallet",  # Consumer's wallet contract
+            "version": "1"
+        })
+        
+        logger.info(f"   🔧 Creating 402 response with resource: {request_path}")
+        
+        payment_req = PaymentRequirements(
+            scheme="exact",
+            network=config["network"],
+            pay_to=config["server_address"],
+            max_amount_required=config["price_wei"],
+            max_timeout_seconds=300,
+            description=config["description"],
+            resource=request_path,  # Include actual API path for signature binding
+            mime_type="application/json",
+            asset=config["token_address"],
+            extra=extra_data  # EIP712 domain for signature
+        )
+        
+        response_data = d402PaymentRequiredResponse(
+            d402_version=d402_VERSION,
+            accepts=[payment_req],
+            error=error_message
+        )
+        
+        return JSONResponse(
+            status_code=402,
+            content=response_data.model_dump(by_alias=True),
+            headers={"Access-Control-Expose-Headers": "X-Payment-Response"}
+        )
+
+
+__all__ = ["D402PaymentMiddleware"]
+