agentpayments-python 0.1.0__py3-none-any.whl

agentpayments_python/fastapi_adapter.py

@@ -0,0 +1,198 @@
+import asyncio
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import HTMLResponse, JSONResponse, RedirectResponse
+
+from .challenge import POW_DIFFICULTY, challenge_html, make_nonce, validate_challenge_submission
+from .cookies import COOKIE_MAX_AGE, COOKIE_NAME, is_valid_cookie_value, make_cookie
+from .crypto import generate_agent_key, is_valid_agent_key
+from .detection import is_browser_from_headers, is_public_path
+from .ratelimit import _challenge_limiter, _agent_key_limiter, _challenge_issue_limiter
+from .crawler import is_verified_crawler
+from .solana import MIN_PAYMENT, RPC_DEVNET, RPC_MAINNET, USDC_MINT_DEVNET, USDC_MINT_MAINNET, is_valid_solana_address, verify_payment_on_chain
+from .x402 import build_payment_requirements, enrich_402_body, payment_required_header
+from .platform_client import HOSTED_KEY_PREFIX, PlatformClient, is_valid_hosted_key
+
+import json as _json
+from pathlib import Path as _Path
+_constants = _json.loads((_Path(__file__).resolve().parent / "constants.json").read_text())
+MAX_NONCE_LENGTH = _constants["MAX_NONCE_LENGTH"]
+MAX_RETURN_TO_LENGTH = _constants["MAX_RETURN_TO_LENGTH"]
+MAX_FP_LENGTH = _constants["MAX_FP_LENGTH"]
+MAX_POW_LENGTH = _constants["MAX_POW_LENGTH"]
+
+
+def _payment_required_response(body: dict, *, wallet_address: str, mint: str, min_payment: float, debug: bool, agent_key: str = "", resource: str = "") -> JSONResponse:
+    """Return a Starlette JSONResponse (402) enriched with x402-standard fields and header."""
+    pay_req = build_payment_requirements(wallet_address=wallet_address, mint=mint, min_payment=min_payment, debug=debug, agent_key=agent_key, resource=resource)
+    return JSONResponse(
+        content=enrich_402_body(body, pay_req),
+        status_code=402,
+        headers={"X-PAYMENT-REQUIRED": payment_required_header(pay_req)},
+    )
+
+
+def _client_ip(request: Request) -> str:
+    forwarded = request.headers.get("x-forwarded-for", "").split(",")[0].strip()
+    if forwarded:
+        return forwarded
+    return request.client.host if request.client else "unknown"
+
+
+class AgentPaymentsASGIMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app, *, challenge_secret: str, home_wallet_address: str, debug: bool = True, solana_rpc_url=None, usdc_mint: str = "", pow_difficulty: int = POW_DIFFICULTY, verify_crawlers: bool = True, grant_store=None, require_https: bool = None, api_key: str = None, platform_url: str = None):
+        super().__init__(app)
+        if challenge_secret == "default-secret-change-me":
+            import logging
+            logger = logging.getLogger("agentpayments")
+            if debug:
+                logger.warning("Using default CHALLENGE_SECRET. Set a strong secret before deploying to production.")
+            else:
+                raise RuntimeError("CHALLENGE_SECRET is set to the insecure default. Set a strong, unique secret for production.")
+        if home_wallet_address and not is_valid_solana_address(home_wallet_address):
+            raise ValueError(f"HOME_WALLET_ADDRESS '{home_wallet_address}' is not a valid Solana public key (expected 32-44 base58 characters).")
+        self.challenge_secret = challenge_secret
+        self.home_wallet_address = home_wallet_address
+        self.debug = debug
+        raw_rpc = solana_rpc_url or (RPC_DEVNET if debug else RPC_MAINNET)
+        self.solana_rpc_url = raw_rpc if isinstance(raw_rpc, list) else [raw_rpc]
+        self.usdc_mint = usdc_mint or (USDC_MINT_DEVNET if debug else USDC_MINT_MAINNET)
+        self.pow_difficulty = pow_difficulty
+        self.verify_crawlers = verify_crawlers
+        self.grant_store = grant_store
+        self.require_https = (not debug) if require_https is None else require_https
+        self._platform_client = PlatformClient(api_key, platform_url) if api_key else None
+
+    async def dispatch(self, request: Request, call_next):
+        path = request.url.path
+        if is_public_path(path):
+            return await call_next(request)
+
+        if path == "/__challenge/verify" and request.method == "POST":
+            return await call_next(request)
+
+        # Reject plaintext HTTP in production.
+        if self.require_https and request.url.scheme != "https":
+            return JSONResponse({"error": "https_required", "message": "This service requires a secure HTTPS connection."}, status_code=400)
+
+        # Verified search crawlers bypass the gate entirely.
+        # is_verified_crawler is blocking I/O — run in executor to avoid blocking the event loop.
+        if self.verify_crawlers:
+            client_ip_early = _client_ip(request)
+            ua = request.headers.get("user-agent", "")
+            loop = asyncio.get_event_loop()
+            if await loop.run_in_executor(None, is_verified_crawler, client_ip_early, ua):
+                return await call_next(request)
+
+        if not is_browser_from_headers(dict(request.headers)):
+            agent_key = request.headers.get("x-agent-key")
+            network = "devnet" if self.debug else "mainnet-beta"
+            if not agent_key:
+                if self._platform_client:
+                    try:
+                        new_key = await loop.run_in_executor(None, self._platform_client.issue_key)
+                    except Exception as exc:
+                        import logging as _log
+                        _log.getLogger("agentpayments").warning("Platform key issuance failed, falling back to local key: %s", exc)
+                        new_key = generate_agent_key(self.challenge_secret)
+                else:
+                    new_key = generate_agent_key(self.challenge_secret)
+                return _payment_required_response(
+                    {
+                        "error": "payment_required",
+                        "message": "Access requires a paid API key. A key has been generated for you below. Send a USDC payment on Solana with this key as the memo to activate it, then retry your request with the X-Agent-Key header.",
+                        "your_key": new_key,
+                        "payment": {
+                            "chain": "solana",
+                            "network": network,
+                            "token": "USDC",
+                            "amount": str(MIN_PAYMENT),
+                            "wallet_address": self.home_wallet_address,
+                            "memo": new_key,
+                            "instructions": f'Send {MIN_PAYMENT} USDC on Solana {network} to {self.home_wallet_address} with memo "{new_key}". Then include the header X-Agent-Key: {new_key} on all subsequent requests.',
+                        },
+                    },
+                    wallet_address=self.home_wallet_address, mint=self.usdc_mint, min_payment=MIN_PAYMENT,
+                    debug=self.debug, agent_key=new_key, resource=path,
+                )
+
+            if agent_key.startswith(HOSTED_KEY_PREFIX):
+                if not self._platform_client:
+                    return JSONResponse({"error": "forbidden", "message": "Platform-issued keys (agp_) require api_key to be configured."}, status_code=403)
+                try:
+                    ver_sec = await loop.run_in_executor(None, lambda: self._platform_client.verification_secret)
+                except Exception as exc:
+                    import logging as _log
+                    _log.getLogger("agentpayments").error("Failed to fetch verificationSecret: %s", exc)
+                    return JSONResponse({"error": "service_unavailable", "message": "Key verification temporarily unavailable."}, status_code=503)
+                if not is_valid_hosted_key(agent_key, ver_sec):
+                    return JSONResponse({"error": "forbidden", "message": "Invalid API key."}, status_code=403)
+            elif not is_valid_agent_key(agent_key, self.challenge_secret):
+                return JSONResponse({"error": "forbidden", "message": "Invalid API key."}, status_code=403)
+
+            if not _agent_key_limiter.check(_client_ip(request)):
+                return JSONResponse({"error": "rate_limited", "message": "Too many payment verification requests. Please wait and try again."}, status_code=429)
+
+            if not self.home_wallet_address:
+                return JSONResponse({"error": "server_error", "message": "Payment verification unavailable."}, status_code=500)
+
+            # Durable grant check — bypasses RPC scan entirely for known-paid keys.
+            if self.grant_store and self.grant_store.has(agent_key):
+                return await call_next(request)
+
+            # verify_payment_on_chain is synchronous (uses requests). Run it in a
+            # thread-pool executor so it doesn't block the async event loop.
+            loop = asyncio.get_event_loop()
+            paid = await loop.run_in_executor(
+                None, verify_payment_on_chain, agent_key, self.home_wallet_address, self.solana_rpc_url, self.usdc_mint
+            )
+            if paid and self.grant_store:
+                self.grant_store.add(agent_key)
+            if not paid:
+                return _payment_required_response(
+                    {
+                        "error": "payment_required",
+                        "message": "Key is valid but payment has not been verified on-chain yet.",
+                        "your_key": agent_key,
+                        "payment": {"chain": "solana", "network": network, "token": "USDC", "amount": str(MIN_PAYMENT), "wallet_address": self.home_wallet_address, "memo": agent_key},
+                    },
+                    wallet_address=self.home_wallet_address, mint=self.usdc_mint, min_payment=MIN_PAYMENT,
+                    debug=self.debug, agent_key=agent_key, resource=path,
+                )
+
+            return await call_next(request)
+
+        client_ip = _client_ip(request)
+        cookie_val = request.cookies.get(COOKIE_NAME, "")
+        if is_valid_cookie_value(cookie_val, self.challenge_secret, client_ip):
+            return await call_next(request)
+
+        if not _challenge_issue_limiter.check(client_ip):
+            return JSONResponse({"error": "rate_limited", "message": "Too many requests. Please try again later."}, status_code=429)
+
+        nonce = make_nonce(self.challenge_secret, client_ip)
+        return HTMLResponse(challenge_html(str(request.url.path), nonce, self.pow_difficulty), headers={
+            "Cache-Control": "no-store",
+            "X-Frame-Options": "DENY",
+            "Content-Security-Policy": "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; form-action 'self'",
+        })
+
+
+async def challenge_verify_endpoint(request: Request, challenge_secret: str, pow_difficulty: int = POW_DIFFICULTY):
+    client_ip = _client_ip(request)
+    if not _challenge_limiter.check(client_ip):
+        return JSONResponse({"error": "rate_limited", "message": "Too many verification attempts. Please wait and try again."}, status_code=429)
+    form = await request.form()
+    nonce = str(form.get("nonce", ""))[:MAX_NONCE_LENGTH]
+    return_to = str(form.get("return_to", "/"))[:MAX_RETURN_TO_LENGTH]
+    fp = str(form.get("fp", ""))[:MAX_FP_LENGTH]
+    pow_value = str(form.get("pow", ""))[:MAX_POW_LENGTH]
+
+    if not validate_challenge_submission(nonce, fp, pow_value, challenge_secret, client_ip, pow_difficulty):
+        return JSONResponse({"error": "forbidden", "message": "Challenge verification failed."}, status_code=403)
+
+    safe_path = return_to if (return_to.startswith("/") and not return_to.startswith("//")) else "/"
+    resp = RedirectResponse(url=safe_path, status_code=302)
+    resp.set_cookie(COOKIE_NAME, make_cookie(challenge_secret, client_ip), max_age=COOKIE_MAX_AGE, path="/", httponly=True, secure=True, samesite="lax")
+    return resp

agentpayments_python/flask_adapter.py

@@ -0,0 +1,167 @@
+from flask import jsonify, make_response, redirect, request, Response as FlaskResponse
+import json as _flask_json
+
+from .challenge import POW_DIFFICULTY, challenge_html, make_nonce, validate_challenge_submission
+from .cookies import COOKIE_MAX_AGE, COOKIE_NAME, is_valid_cookie_value, make_cookie
+from .crypto import generate_agent_key, is_valid_agent_key
+from .detection import is_browser_from_headers, is_public_path
+from .ratelimit import _challenge_limiter, _agent_key_limiter, _challenge_issue_limiter
+from .crawler import is_verified_crawler
+from .solana import MIN_PAYMENT, RPC_DEVNET, RPC_MAINNET, USDC_MINT_DEVNET, USDC_MINT_MAINNET, is_valid_solana_address, verify_payment_on_chain
+from .x402 import build_payment_requirements, enrich_402_body, payment_required_header
+from .platform_client import HOSTED_KEY_PREFIX, PlatformClient, is_valid_hosted_key
+
+import json as _json
+from pathlib import Path as _Path
+_constants = _json.loads((_Path(__file__).resolve().parent / "constants.json").read_text())
+MAX_NONCE_LENGTH = _constants["MAX_NONCE_LENGTH"]
+MAX_RETURN_TO_LENGTH = _constants["MAX_RETURN_TO_LENGTH"]
+MAX_FP_LENGTH = _constants["MAX_FP_LENGTH"]
+MAX_POW_LENGTH = _constants["MAX_POW_LENGTH"]
+
+
+def _payment_required_flask(body: dict, *, wallet_address: str, mint: str, min_payment: float, debug: bool, agent_key: str = "", resource: str = ""):
+    """Return a Flask 402 response enriched with x402-standard fields and header."""
+    pay_req = build_payment_requirements(wallet_address=wallet_address, mint=mint, min_payment=min_payment, debug=debug, agent_key=agent_key, resource=resource)
+    enriched = enrich_402_body(body, pay_req)
+    resp = make_response(_flask_json.dumps(enriched, indent=2), 402)
+    resp.headers["Content-Type"] = "application/json"
+    resp.headers["X-PAYMENT-REQUIRED"] = payment_required_header(pay_req)
+    return resp
+
+
+def _client_ip() -> str:
+    return request.headers.get("X-Forwarded-For", "").split(",")[0].strip() or request.remote_addr or "unknown"
+
+
+def register_agentpayments(app, *, challenge_secret: str, home_wallet_address: str, debug: bool = True, solana_rpc_url=None, usdc_mint: str = "", pow_difficulty: int = POW_DIFFICULTY, verify_crawlers: bool = True, grant_store=None, require_https: bool = None, api_key: str = None, platform_url: str = None):
+    if challenge_secret == "default-secret-change-me":
+        import logging
+        logger = logging.getLogger("agentpayments")
+        if debug:
+            logger.warning("Using default CHALLENGE_SECRET. Set a strong secret before deploying to production.")
+        else:
+            raise RuntimeError("CHALLENGE_SECRET is set to the insecure default. Set a strong, unique secret for production.")
+    if home_wallet_address and not is_valid_solana_address(home_wallet_address):
+        raise ValueError(f"HOME_WALLET_ADDRESS '{home_wallet_address}' is not a valid Solana public key (expected 32-44 base58 characters).")
+    raw_rpc = solana_rpc_url or (RPC_DEVNET if debug else RPC_MAINNET)
+    rpc_url = raw_rpc if isinstance(raw_rpc, list) else [raw_rpc]
+    mint = usdc_mint or (USDC_MINT_DEVNET if debug else USDC_MINT_MAINNET)
+    _require_https = (not debug) if require_https is None else require_https
+    _platform_client = PlatformClient(api_key, platform_url) if api_key else None
+
+    @app.before_request
+    def _gate():
+        path = request.path
+        if is_public_path(path):
+            return None
+        if path == "/__challenge/verify" and request.method == "POST":
+            return None
+
+        # Reject plaintext HTTP in production.
+        if _require_https and not request.is_secure:
+            return make_response(_flask_json.dumps({"error": "https_required", "message": "This service requires a secure HTTPS connection."}, indent=2), 400, {"Content-Type": "application/json"})
+
+        # Verified search crawlers bypass the gate entirely.
+        if verify_crawlers:
+            ua = request.headers.get("User-Agent", "")
+            if is_verified_crawler(_client_ip(), ua):
+                return None
+
+        if not is_browser_from_headers(request.headers):
+            key = request.headers.get("X-Agent-Key")
+            network = "devnet" if debug else "mainnet-beta"
+            if not key:
+                if _platform_client:
+                    try:
+                        new_key = _platform_client.issue_key()
+                    except Exception as exc:
+                        import logging as _log
+                        _log.getLogger("agentpayments").warning("Platform key issuance failed, falling back to local key: %s", exc)
+                        new_key = generate_agent_key(challenge_secret)
+                else:
+                    new_key = generate_agent_key(challenge_secret)
+                return _payment_required_flask(
+                    {
+                        "error": "payment_required",
+                        "message": "Access requires a paid API key. A key has been generated for you below. Send a USDC payment on Solana with this key as the memo to activate it, then retry your request with the X-Agent-Key header.",
+                        "your_key": new_key,
+                        "payment": {
+                            "chain": "solana",
+                            "network": network,
+                            "token": "USDC",
+                            "amount": str(MIN_PAYMENT),
+                            "wallet_address": home_wallet_address,
+                            "memo": new_key,
+                            "instructions": f'Send {MIN_PAYMENT} USDC on Solana {network} to {home_wallet_address} with memo "{new_key}". Then include the header X-Agent-Key: {new_key} on all subsequent requests.',
+                        },
+                    },
+                    wallet_address=home_wallet_address, mint=mint, min_payment=MIN_PAYMENT,
+                    debug=debug, agent_key=new_key, resource=path,
+                )
+            if key.startswith(HOSTED_KEY_PREFIX):
+                if not _platform_client:
+                    return jsonify({"error": "forbidden", "message": "Platform-issued keys (agp_) require api_key to be configured."}), 403
+                try:
+                    ver_sec = _platform_client.verification_secret
+                except Exception as exc:
+                    import logging as _log
+                    _log.getLogger("agentpayments").error("Failed to fetch verificationSecret: %s", exc)
+                    return jsonify({"error": "service_unavailable", "message": "Key verification temporarily unavailable."}), 503
+                if not is_valid_hosted_key(key, ver_sec):
+                    return jsonify({"error": "forbidden", "message": "Invalid API key."}), 403
+            elif not is_valid_agent_key(key, challenge_secret):
+                return jsonify({"error": "forbidden", "message": "Invalid API key."}), 403
+            if not _agent_key_limiter.check(_client_ip()):
+                return jsonify({"error": "rate_limited", "message": "Too many payment verification requests. Please wait and try again."}), 429
+            if not home_wallet_address:
+                return jsonify({"error": "server_error", "message": "Payment verification unavailable."}), 500
+            if grant_store and grant_store.has(key):
+                return None
+            paid = verify_payment_on_chain(key, home_wallet_address, rpc_url, mint)
+            if paid and grant_store:
+                grant_store.add(key)
+            if not paid:
+                return _payment_required_flask(
+                    {
+                        "error": "payment_required",
+                        "message": "Key is valid but payment has not been verified on-chain yet.",
+                        "your_key": key,
+                        "payment": {"chain": "solana", "network": network, "token": "USDC", "amount": str(MIN_PAYMENT), "wallet_address": home_wallet_address, "memo": key},
+                    },
+                    wallet_address=home_wallet_address, mint=mint, min_payment=MIN_PAYMENT,
+                    debug=debug, agent_key=key, resource=path,
+                )
+            return None
+
+        client_ip = _client_ip()
+        cookie_val = request.cookies.get(COOKIE_NAME, "")
+        if is_valid_cookie_value(cookie_val, challenge_secret, client_ip):
+            return None
+
+        if not _challenge_issue_limiter.check(client_ip):
+            return make_response(_flask_json.dumps({"error": "rate_limited", "message": "Too many requests. Please try again later."}, indent=2), 429, {"Content-Type": "application/json"})
+
+        nonce = make_nonce(challenge_secret, client_ip)
+        return make_response(challenge_html(request.full_path or request.path, nonce, pow_difficulty), 200, {
+            "Content-Type": "text/html",
+            "Cache-Control": "no-store",
+            "X-Frame-Options": "DENY",
+            "Content-Security-Policy": "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; form-action 'self'",
+        })
+
+    @app.post("/__challenge/verify")
+    def _verify():
+        client_ip = _client_ip()
+        if not _challenge_limiter.check(client_ip):
+            return jsonify({"error": "rate_limited", "message": "Too many verification attempts. Please wait and try again."}), 429
+        nonce = request.form.get("nonce", "")[:MAX_NONCE_LENGTH]
+        return_to = request.form.get("return_to", "/")[:MAX_RETURN_TO_LENGTH]
+        fp = request.form.get("fp", "")[:MAX_FP_LENGTH]
+        pow_value = request.form.get("pow", "")[:MAX_POW_LENGTH]
+        if not validate_challenge_submission(nonce, fp, pow_value, challenge_secret, client_ip, pow_difficulty):
+            return jsonify({"error": "forbidden", "message": "Challenge verification failed."}), 403
+        safe = return_to if (return_to.startswith("/") and not return_to.startswith("//")) else "/"
+        resp = redirect(safe, code=302)
+        resp.set_cookie(COOKIE_NAME, make_cookie(challenge_secret, client_ip), max_age=COOKIE_MAX_AGE, path='/', httponly=True, secure=True, samesite='Lax')
+        return resp

agentpayments_python/grant_store.py

@@ -0,0 +1,86 @@
+"""
+Grant stores for durable paid-key persistence (P0 #5).
+
+Once a key is added to a grant store it is never re-scanned on-chain, making
+paid access durable even after the vendor wallet accumulates 100+ newer
+transactions that would push the original payment out of the scan window.
+
+Usage — pass to any adapter as ``grant_store``:
+
+    from agentpayments_python.grant_store import FileGrantStore
+
+    # Django settings.py
+    AGENTPAYMENTS_GRANT_STORE = FileGrantStore("/var/data/agp_grants.json")
+
+    # FastAPI / Flask constructor arg
+    register_agentpayments(app, ..., grant_store=FileGrantStore("/var/data/agp_grants.json"))
+
+Grant store interface (implement your own for Redis, Postgres, etc.):
+
+    class GrantStore(Protocol):
+        def has(self, agent_key: str) -> bool: ...
+        def add(self, agent_key: str) -> None: ...
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from pathlib import Path
+
+
+class MemoryGrantStore:
+    """In-memory grant store. Does not survive restarts."""
+
+    def __init__(self) -> None:
+        self._grants: set[str] = set()
+        self._lock = threading.Lock()
+
+    def has(self, agent_key: str) -> bool:
+        with self._lock:
+            return agent_key in self._grants
+
+    def add(self, agent_key: str) -> None:
+        with self._lock:
+            self._grants.add(agent_key)
+
+
+class FileGrantStore:
+    """
+    File-backed grant store. Persists grants to a JSON file so they survive
+    process restarts. Writes are atomic (write to temp file, os.replace).
+
+    Not suitable for multi-process deployments — use a database or Redis there.
+    """
+
+    def __init__(self, path: str | Path) -> None:
+        self._path = Path(path).resolve()
+        self._grants: set[str] = set()
+        self._lock = threading.Lock()
+        self._load()
+
+    def _load(self) -> None:
+        try:
+            keys = json.loads(self._path.read_text())
+            if isinstance(keys, list):
+                self._grants.update(keys)
+        except FileNotFoundError:
+            pass  # will be created on first write
+
+    def _save(self) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self._path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(sorted(self._grants), indent=2))
+        os.replace(tmp, self._path)
+
+    def has(self, agent_key: str) -> bool:
+        with self._lock:
+            return agent_key in self._grants
+
+    def add(self, agent_key: str) -> None:
+        with self._lock:
+            if agent_key in self._grants:
+                return
+            self._grants.add(agent_key)
+            self._save()

agentpayments_python/platform_client.py

@@ -0,0 +1,117 @@
+"""
+AgentPayments Platform Client
+
+Thin HTTP client for the AgentPayments Platform API.
+
+Usage:
+    client = PlatformClient(api_key="ap_live_...")
+    key = client.issue_key()          # returns 'agp_...'
+    secret = client.verification_secret  # cached after first call
+
+The verificationSecret is fetched once per client instance and cached in memory.
+Agent keys are verified locally using is_valid_hosted_key() — no per-request
+platform round-trip is needed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac as _hmac
+import json
+import threading
+import urllib.request
+import urllib.error
+
+from pathlib import Path as _Path
+
+_constants = json.loads((_Path(__file__).resolve().parent / "constants.json").read_text())
+PLATFORM_API_URL: str = _constants["PLATFORM_API_URL"]
+HOSTED_KEY_PREFIX: str = _constants["HOSTED_KEY_PREFIX"]
+
+
+def _hmac_hex(data: str, key: str) -> str:
+    return _hmac.new(key.encode(), data.encode(), hashlib.sha256).hexdigest()
+
+
+def is_valid_hosted_key(key: str, verification_secret: str) -> bool:
+    """
+    Verify a platform-issued agent key locally.
+
+    Key format: agp_${vendorId8}_${nonce16}_${sig16}
+    sig = hmac('agp:vendorId:nonce', verificationSecret).slice(0,16)
+    """
+    if not key or not key.startswith(HOSTED_KEY_PREFIX):
+        return False
+    parts = key.split("_")
+    # ['agp', vendorId(8), nonce(16), sig(16)]
+    if len(parts) != 4:
+        return False
+    _, vendor_id, nonce, sig = parts
+    if not vendor_id or not nonce or not sig or len(sig) != 16:
+        return False
+    expected = _hmac_hex(f"agp:{vendor_id}:{nonce}", verification_secret)[:16]
+    return _hmac.compare_digest(sig, expected)
+
+
+class PlatformClient:
+    """
+    Manages communication with the AgentPayments Platform API.
+
+    Thread-safe: the verificationSecret is fetched once and cached for the
+    lifetime of the process.
+    """
+
+    def __init__(self, api_key: str, platform_url: str = PLATFORM_API_URL) -> None:
+        self.api_key = api_key
+        self.platform_url = platform_url.rstrip("/")
+        self._verification_secret: str | None = None
+        self._lock = threading.Lock()
+
+    def _auth_headers(self) -> dict:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    def _get(self, path: str) -> dict:
+        req = urllib.request.Request(
+            f"{self.platform_url}{path}",
+            headers=self._auth_headers(),
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                return json.loads(resp.read())
+        except urllib.error.HTTPError as exc:
+            raise RuntimeError(f"Platform API {path} returned {exc.code}") from exc
+
+    def _post(self, path: str, body: dict | None = None) -> dict:
+        data = json.dumps(body or {}).encode()
+        req = urllib.request.Request(
+            f"{self.platform_url}{path}",
+            data=data,
+            headers=self._auth_headers(),
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                return json.loads(resp.read())
+        except urllib.error.HTTPError as exc:
+            raise RuntimeError(f"Platform API {path} returned {exc.code}") from exc
+
+    @property
+    def verification_secret(self) -> str:
+        """Fetch + cache verificationSecret from /v1/account (thread-safe)."""
+        if self._verification_secret:
+            return self._verification_secret
+        with self._lock:
+            # Double-checked locking
+            if self._verification_secret:
+                return self._verification_secret
+            data = self._get("/v1/account")
+            self._verification_secret = data["verificationSecret"]
+        return self._verification_secret
+
+    def issue_key(self) -> str:
+        """Issue a single platform-signed agent key (agp_...). Metered."""
+        data = self._post("/v1/keys/issue")
+        return data["key"]

agentpayments_python/ratelimit.py

@@ -0,0 +1,43 @@
+import threading
+import time
+
+RATE_LIMIT_WINDOW = 60  # 1 minute in seconds
+RATE_LIMIT_MAX = 20  # max attempts per window per key
+# Probabilistic cleanup: purge all expired entries roughly 1-in-N calls.
+_CLEANUP_PROBABILITY = 50
+
+
+class RateLimiter:
+    def __init__(self, window: int = RATE_LIMIT_WINDOW, max_hits: int = RATE_LIMIT_MAX):
+        self.window = window
+        self.max_hits = max_hits
+        self._hits: dict[str, tuple[float, int]] = {}
+        self._lock = threading.Lock()
+        self._call_count = 0
+
+    def check(self, key: str) -> bool:
+        now = time.time()
+        with self._lock:
+            # Periodically purge stale entries to prevent unbounded growth.
+            self._call_count += 1
+            if self._call_count % _CLEANUP_PROBABILITY == 0:
+                expired = [k for k, v in self._hits.items() if now - v[0] > self.window]
+                for k in expired:
+                    del self._hits[k]
+
+            entry = self._hits.get(key)
+            if entry is None or now - entry[0] > self.window:
+                self._hits[key] = (now, 1)
+                return True
+            start, count = entry
+            count += 1
+            self._hits[key] = (start, count)
+            return count <= self.max_hits
+
+
+_challenge_limiter = RateLimiter()
+# Stricter limit for the agent-key payment verification path.
+_agent_key_limiter = RateLimiter(max_hits=10)
+# Rate-limit challenge page issuance (browser fallback) to prevent unlimited
+# nonce harvesting for offline PoW mining.
+_challenge_issue_limiter = RateLimiter(max_hits=30)