agentpayments-python 0.1.0__tar.gz

agentpayments_python-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Brzosko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentpayments_python-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: agentpayments-python
+Version: 0.1.0
+Summary: AgentPayments gate for Python web frameworks — charge AI agents USDC on Solana before they can access your API
+License: MIT
+Project-URL: Homepage, https://github.com/adambrzosko/AgentPayments
+Project-URL: Documentation, https://github.com/adambrzosko/AgentPayments/tree/main/sdk/python
+Project-URL: Repository, https://github.com/adambrzosko/AgentPayments
+Project-URL: Bug Tracker, https://github.com/adambrzosko/AgentPayments/issues
+Keywords: agentpayments,ai-agents,solana,usdc,payments,middleware,x402
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31
+Provides-Extra: django
+Requires-Dist: Django>=5.0; extra == "django"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110; extra == "fastapi"
+Requires-Dist: starlette>=0.37; extra == "fastapi"
+Provides-Extra: flask
+Requires-Dist: flask>=3.0; extra == "flask"
+Provides-Extra: all
+Requires-Dist: Django>=5.0; extra == "all"
+Requires-Dist: fastapi>=0.110; extra == "all"
+Requires-Dist: starlette>=0.37; extra == "all"
+Requires-Dist: flask>=3.0; extra == "all"
+Dynamic: license-file
+
+# agentpayments-python
+
+Python adapters for the AgentPayments gate. Supports Django, FastAPI/Starlette, and Flask.
+
+## Install
+
+```bash
+pip install agentpayments-python
+# or, in this monorepo:
+# pip install -e sdk/python
+```
+
+## Django
+
+```python
+# settings.py
+MIDDLEWARE = [
+    "django.middleware.security.SecurityMiddleware",
+    "agentpayments_python.django_adapter.GateMiddleware",
+    # ... other middleware
+]
+
+# Required settings
+CHALLENGE_SECRET = os.environ["CHALLENGE_SECRET"]
+HOME_WALLET_ADDRESS = os.environ["HOME_WALLET_ADDRESS"]
+
+# Optional settings
+SOLANA_RPC_URL = os.environ.get("SOLANA_RPC_URL")
+USDC_MINT = os.environ.get("USDC_MINT")
+DEBUG = True  # True = devnet, False = mainnet
+```
+
+## FastAPI
+
+```python
+from fastapi import FastAPI, Request
+from agentpayments_python.fastapi_adapter import (
+    AgentPaymentsASGIMiddleware,
+    challenge_verify_endpoint,
+)
+
+app = FastAPI()
+
+app.add_middleware(
+    AgentPaymentsASGIMiddleware,
+    challenge_secret=os.environ["CHALLENGE_SECRET"],
+    home_wallet_address=os.environ["HOME_WALLET_ADDRESS"],
+    debug=True,
+)
+
+@app.post("/__challenge/verify")
+async def verify(request: Request):
+    return await challenge_verify_endpoint(
+        request,
+        challenge_secret=os.environ["CHALLENGE_SECRET"],
+    )
+```
+
+## Flask
+
+```python
+from flask import Flask
+from agentpayments_python.flask_adapter import register_agentpayments
+
+app = Flask(__name__)
+register_agentpayments(
+    app,
+    challenge_secret=os.environ["CHALLENGE_SECRET"],
+    home_wallet_address=os.environ["HOME_WALLET_ADDRESS"],
+    debug=True,
+)
+```
+
+## Configuration
+
+| Parameter | Required | Default | Description |
+|---|---|---|---|
+| `challenge_secret` | Yes (production) | `'default-secret-change-me'` | HMAC secret for signing cookies, nonces, and agent keys. |
+| `home_wallet_address` | Yes | `''` | Solana wallet address to receive USDC payments. |
+| `solana_rpc_url` | No | Auto (devnet/mainnet) | Custom Solana RPC endpoint. |
+| `usdc_mint` | No | Auto (devnet/mainnet) | Custom USDC mint address. |
+| `debug` | No | `True` | `True` = devnet. `False` = mainnet + strict mode. |
+
+Django reads these from `settings.*` (e.g., `settings.CHALLENGE_SECRET`). FastAPI and Flask accept them as constructor arguments.
+
+## Security Features
+
+- **Timing-safe HMAC comparison** — uses `hmac.compare_digest()` for all signature checks
+- **Payment verification cache** — 10-minute TTL, 1000-entry max (thread-safe)
+- **Rate limiting** — 20 challenge verifications per minute per IP (thread-safe)
+- **Input size limits** — key (64 chars), nonce (128), return URL (2048), fingerprint (128)
+- **Wallet address validation** — base58 format, 32-44 chars, validated at init
+- **Default secret detection** — warns in debug, raises `RuntimeError` in production
+- **Secure cookies** — Django auto-detects HTTPS via `request.is_secure()`
+
+## Module Structure
+
+```
+agentpayments_python/
+  __init__.py
+  django_adapter.py      Django middleware (GateMiddleware)
+  fastapi_adapter.py     FastAPI/Starlette ASGI middleware
+  flask_adapter.py       Flask integration (before_request hook)
+  challenge.py           Shared challenge HTML generation
+  cookies.py             Cookie creation and validation
+  crypto.py              HMAC signing and agent key management
+  detection.py           Browser detection and public path checks
+  solana.py              On-chain payment verification + caching
+  ratelimit.py           Shared IP-based rate limiter
+```
+
+## Notes
+- Constants loaded from `sdk/constants.json` via `pathlib`.
+- Logging uses Python stdlib `logging` module.
+- All shared modules are framework-agnostic; adapters are thin wiring.

agentpayments_python-0.1.0/README.md

@@ -0,0 +1,115 @@
+# agentpayments-python
+
+Python adapters for the AgentPayments gate. Supports Django, FastAPI/Starlette, and Flask.
+
+## Install
+
+```bash
+pip install agentpayments-python
+# or, in this monorepo:
+# pip install -e sdk/python
+```
+
+## Django
+
+```python
+# settings.py
+MIDDLEWARE = [
+    "django.middleware.security.SecurityMiddleware",
+    "agentpayments_python.django_adapter.GateMiddleware",
+    # ... other middleware
+]
+
+# Required settings
+CHALLENGE_SECRET = os.environ["CHALLENGE_SECRET"]
+HOME_WALLET_ADDRESS = os.environ["HOME_WALLET_ADDRESS"]
+
+# Optional settings
+SOLANA_RPC_URL = os.environ.get("SOLANA_RPC_URL")
+USDC_MINT = os.environ.get("USDC_MINT")
+DEBUG = True  # True = devnet, False = mainnet
+```
+
+## FastAPI
+
+```python
+from fastapi import FastAPI, Request
+from agentpayments_python.fastapi_adapter import (
+    AgentPaymentsASGIMiddleware,
+    challenge_verify_endpoint,
+)
+
+app = FastAPI()
+
+app.add_middleware(
+    AgentPaymentsASGIMiddleware,
+    challenge_secret=os.environ["CHALLENGE_SECRET"],
+    home_wallet_address=os.environ["HOME_WALLET_ADDRESS"],
+    debug=True,
+)
+
+@app.post("/__challenge/verify")
+async def verify(request: Request):
+    return await challenge_verify_endpoint(
+        request,
+        challenge_secret=os.environ["CHALLENGE_SECRET"],
+    )
+```
+
+## Flask
+
+```python
+from flask import Flask
+from agentpayments_python.flask_adapter import register_agentpayments
+
+app = Flask(__name__)
+register_agentpayments(
+    app,
+    challenge_secret=os.environ["CHALLENGE_SECRET"],
+    home_wallet_address=os.environ["HOME_WALLET_ADDRESS"],
+    debug=True,
+)
+```
+
+## Configuration
+
+| Parameter | Required | Default | Description |
+|---|---|---|---|
+| `challenge_secret` | Yes (production) | `'default-secret-change-me'` | HMAC secret for signing cookies, nonces, and agent keys. |
+| `home_wallet_address` | Yes | `''` | Solana wallet address to receive USDC payments. |
+| `solana_rpc_url` | No | Auto (devnet/mainnet) | Custom Solana RPC endpoint. |
+| `usdc_mint` | No | Auto (devnet/mainnet) | Custom USDC mint address. |
+| `debug` | No | `True` | `True` = devnet. `False` = mainnet + strict mode. |
+
+Django reads these from `settings.*` (e.g., `settings.CHALLENGE_SECRET`). FastAPI and Flask accept them as constructor arguments.
+
+## Security Features
+
+- **Timing-safe HMAC comparison** — uses `hmac.compare_digest()` for all signature checks
+- **Payment verification cache** — 10-minute TTL, 1000-entry max (thread-safe)
+- **Rate limiting** — 20 challenge verifications per minute per IP (thread-safe)
+- **Input size limits** — key (64 chars), nonce (128), return URL (2048), fingerprint (128)
+- **Wallet address validation** — base58 format, 32-44 chars, validated at init
+- **Default secret detection** — warns in debug, raises `RuntimeError` in production
+- **Secure cookies** — Django auto-detects HTTPS via `request.is_secure()`
+
+## Module Structure
+
+```
+agentpayments_python/
+  __init__.py
+  django_adapter.py      Django middleware (GateMiddleware)
+  fastapi_adapter.py     FastAPI/Starlette ASGI middleware
+  flask_adapter.py       Flask integration (before_request hook)
+  challenge.py           Shared challenge HTML generation
+  cookies.py             Cookie creation and validation
+  crypto.py              HMAC signing and agent key management
+  detection.py           Browser detection and public path checks
+  solana.py              On-chain payment verification + caching
+  ratelimit.py           Shared IP-based rate limiter
+```
+
+## Notes
+- Constants loaded from `sdk/constants.json` via `pathlib`.
+- Logging uses Python stdlib `logging` module.
+- All shared modules are framework-agnostic; adapters are thin wiring.

agentpayments_python-0.1.0/agentpayments_python/__init__.py

@@ -0,0 +1,30 @@
+# Adapters are optional: each import succeeds only if its framework is
+# installed. ImportError (missing framework) is expected; any other exception
+# is a real bug and should propagate.
+
+# x402 helpers are always available (no framework dependency).
+from .x402 import build_payment_requirements, enrich_402_body, payment_required_header
+
+__all__ = [
+    "build_payment_requirements",
+    "enrich_402_body",
+    "payment_required_header",
+]
+
+try:
+    from .django_adapter import GateMiddleware, challenge_verify
+    __all__ += ["GateMiddleware", "challenge_verify"]
+except ImportError:
+    pass
+
+try:
+    from .fastapi_adapter import AgentPaymentsASGIMiddleware, challenge_verify_endpoint as fastapi_challenge_verify
+    __all__ += ["AgentPaymentsASGIMiddleware", "fastapi_challenge_verify"]
+except ImportError:
+    pass
+
+try:
+    from .flask_adapter import register_agentpayments
+    __all__ += ["register_agentpayments"]
+except ImportError:
+    pass

agentpayments_python-0.1.0/agentpayments_python/challenge.py

@@ -0,0 +1,151 @@
+import hmac
+import json
+import re
+import secrets as _secrets
+import threading
+import time
+from pathlib import Path
+
+from .crypto import client_id_for_ip, hmac_sign, sha256_hex
+
+_constants = json.loads((Path(__file__).resolve().parent / "constants.json").read_text())
+POW_DIFFICULTY = _constants["POW_DIFFICULTY"]
+MAX_POW_LENGTH = _constants["MAX_POW_LENGTH"]
+NONCE_TTL_MS = _constants["NONCE_TTL_MS"]
+
+# Canvas fingerprints are a base64 slice of a data URL. Reject anything that
+# isn't base64 or is degenerate (e.g. a single repeated character).
+_FP_RE = re.compile(r"^[A-Za-z0-9+/]{10,}$")
+_POW_RE = re.compile(r"^\d{1,20}$")
+
+
+def make_nonce(secret: str, client_ip: str) -> str:
+    """Nonce format: <ts>.<rand>.<sig>, signature bound to the client IP."""
+    ts = str(int(time.time() * 1000))
+    rand = _secrets.token_hex(8)
+    client_id = client_id_for_ip(client_ip, secret)
+    sig = hmac_sign(f"nonce:{ts}:{rand}:{client_id}", secret)
+    return f"{ts}.{rand}.{sig}"
+
+
+def _is_plausible_fingerprint(fp: str) -> bool:
+    return bool(_FP_RE.match(fp)) and len(set(fp)) >= 4
+
+
+def _verify_pow(nonce: str, pow_value: str, difficulty: int) -> bool:
+    """Proof-of-work: sha256(f"{nonce}:{pow}") must start with `difficulty`
+    zero hex chars. Verification is one hash; solving costs ~16^difficulty."""
+    if not _POW_RE.match(pow_value):
+        return False
+    return sha256_hex(f"{nonce}:{pow_value}").startswith("0" * difficulty)
+
+
+class _ConsumedNonces:
+    """Single-use nonce tracking (best-effort, in-memory, thread-safe)."""
+
+    def __init__(self, ttl_ms: int = NONCE_TTL_MS, max_size: int = 10000):
+        self.ttl = ttl_ms / 1000.0
+        self.max_size = max_size
+        self._seen: dict[str, float] = {}
+        self._lock = threading.Lock()
+
+    def consume(self, sig: str) -> bool:
+        """Returns True if the nonce was fresh (and marks it consumed)."""
+        now = time.time()
+        with self._lock:
+            exp = self._seen.get(sig)
+            if exp is not None and exp > now:
+                return False
+            if len(self._seen) >= self.max_size:
+                expired = [k for k, v in self._seen.items() if v <= now]
+                for k in expired:
+                    del self._seen[k]
+                if len(self._seen) >= self.max_size:
+                    del self._seen[next(iter(self._seen))]
+            self._seen[sig] = now + self.ttl
+            return True
+
+
+_consumed_nonces = _ConsumedNonces()
+
+
+def validate_challenge_submission(
+    nonce: str,
+    fp: str,
+    pow_value: str,
+    secret: str,
+    client_ip: str,
+    difficulty: int = POW_DIFFICULTY,
+) -> bool:
+    """Full server-side validation of a challenge form submission.
+
+    Checks: nonce structure and expiry, IP-bound HMAC signature, plausible
+    fingerprint, proof-of-work, and single use.
+    """
+    parts = nonce.split(".")
+    if len(parts) != 3 or not _is_plausible_fingerprint(fp):
+        return False
+    nonce_ts, nonce_rand, nonce_sig = parts
+    try:
+        ts = int(nonce_ts)
+    except ValueError:
+        return False
+    if int(time.time() * 1000) - ts > NONCE_TTL_MS:
+        return False
+    client_id = client_id_for_ip(client_ip, secret)
+    expected = hmac_sign(f"nonce:{nonce_ts}:{nonce_rand}:{client_id}", secret)
+    if not hmac.compare_digest(nonce_sig, expected):
+        return False
+    if not _verify_pow(nonce, pow_value, difficulty):
+        return False
+    return _consumed_nonces.consume(nonce_sig)
+
+
+def challenge_html(return_to: str, nonce: str, pow_difficulty: int = POW_DIFFICULTY) -> str:
+    # Reject protocol-relative URLs (e.g. //attacker.com) which start with '/'
+    # but are treated as external by browsers.
+    safe_path = return_to if (return_to.startswith("/") and not return_to.startswith("//")) else "/"
+    nonce_json = json.dumps(nonce)
+    safe_path_json = json.dumps(safe_path)
+    target_json = json.dumps("0" * pow_difficulty)
+    return (
+        "<!DOCTYPE html><html lang='en'><head><meta charset='UTF-8'>"
+        "<meta name='viewport' content='width=device-width, initial-scale=1.0'>"
+        "<title>Verifying your access...</title>"
+        "<style>body{font-family:system-ui,sans-serif;display:flex;justify-content:center;"
+        "align-items:center;min-height:100vh;margin:0;background:#fafafa;color:#333}"
+        "main{text-align:center;padding:2rem}"
+        ".spinner{width:40px;height:40px;border:4px solid #e0e0e0;border-top-color:#333;"
+        "border-radius:50%;animation:spin .8s linear infinite;margin:1rem auto}"
+        "@keyframes spin{to{transform:rotate(360deg)}}</style>"
+        "</head><body>"
+        "<main role='status' aria-live='polite'>"
+        "<div class='spinner' aria-hidden='true'></div>"
+        "<p>Verifying your access&hellip;</p>"
+        "<noscript><p><strong>JavaScript is required to verify your access. "
+        "Please enable JavaScript and reload this page.</strong></p></noscript>"
+        "</main>"
+        "<script>(function(){"
+        "if(navigator.webdriver)return;"
+        "if(!window.crypto||!window.crypto.subtle)return;"
+        "var c=document.createElement('canvas');c.width=200;c.height=50;"
+        "var ctx=c.getContext('2d');if(!ctx)return;"
+        "ctx.font='18px Arial';ctx.fillStyle='#1a1a2e';ctx.fillText('verify',10,30);"
+        "var data=c.toDataURL();if(!data||data.length<100)return;"
+        "if(typeof window.innerWidth==='undefined'||window.innerWidth===0)return;"
+        f"var nonce={nonce_json};var target={target_json};"
+        "var enc=new TextEncoder();var i=0;"
+        "function submit(pow){"
+        "var form=document.createElement('form');form.method='POST';form.action='/__challenge/verify';"
+        f"var fields={{nonce:nonce,return_to:{safe_path_json},fp:data.slice(22,86),pow:pow}};"
+        "for(var k in fields){var input=document.createElement('input');"
+        "input.type='hidden';input.name=k;input.value=fields[k];form.appendChild(input);}"
+        "document.body.appendChild(form);form.submit();}"
+        "function mine(){window.crypto.subtle.digest('SHA-256',enc.encode(nonce+':'+i)).then(function(buf){"
+        "var b=new Uint8Array(buf);var h='';"
+        "for(var j=0;j<4;j++)h+=(b[j]<16?'0':'')+b[j].toString(16);"
+        "if(h.slice(0,target.length)===target)return submit(String(i));"
+        "i++;mine();});}"
+        "mine();})();</script>"
+        "</body></html>"
+    )

agentpayments_python-0.1.0/agentpayments_python/constants.json

@@ -0,0 +1,27 @@
+{
+  "USDC_MINT_DEVNET": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
+  "USDC_MINT_MAINNET": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+  "RPC_DEVNET": "https://api.devnet.solana.com",
+  "RPC_MAINNET": "https://api.mainnet-beta.solana.com",
+  "MEMO_PROGRAM": "MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr",
+  "MIN_PAYMENT": 0.01,
+  "COOKIE_NAME": "__agp_verified",
+  "COOKIE_MAX_AGE": 86400,
+  "KEY_PREFIX": "ag_",
+  "POW_DIFFICULTY": 4,
+  "MAX_POW_LENGTH": 20,
+  "NONCE_TTL_MS": 300000,
+  "MAX_KEY_LENGTH": 64,
+  "MAX_NONCE_LENGTH": 128,
+  "MAX_RETURN_TO_LENGTH": 2048,
+  "MAX_FP_LENGTH": 128,
+  "NEGATIVE_CACHE_TTL_MS": 30000,
+  "MAX_TRANSACTIONS_PER_VERIFY": 20,
+  "AGENT_KEY_RATE_LIMIT_MAX": 10,
+  "USDC_DECIMALS": 6,
+  "X402_VERSION": 1,
+  "SOLANA_CHAIN_ID_MAINNET": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+  "SOLANA_CHAIN_ID_DEVNET": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+  "PLATFORM_API_URL": "https://api.agentpayments.dev",
+  "HOSTED_KEY_PREFIX": "agp_"
+}

agentpayments_python-0.1.0/agentpayments_python/cookies.py

@@ -0,0 +1,37 @@
+import hmac
+import json
+import time
+from pathlib import Path
+
+from .crypto import client_id_for_ip, hmac_sign
+
+_constants = json.loads((Path(__file__).resolve().parent / "constants.json").read_text())
+COOKIE_NAME = _constants["COOKIE_NAME"]
+COOKIE_MAX_AGE = _constants["COOKIE_MAX_AGE"]
+
+
+def make_cookie(secret: str, client_ip: str) -> str:
+    """Cookie format: <ts>.<sig>, signature bound to the client IP that
+    solved the challenge, so a captured cookie is useless from another IP."""
+    now_ms = str(int(time.time() * 1000))
+    client_id = client_id_for_ip(client_ip, secret)
+    return f"{now_ms}.{hmac_sign(f'cookie:{now_ms}:{client_id}', secret)}"
+
+
+def is_valid_cookie_value(cookie_value: str, secret: str, client_ip: str) -> bool:
+    if not cookie_value:
+        return False
+    i = cookie_value.find(".")
+    if i == -1:
+        return False
+    ts_str = cookie_value[:i]
+    sig = cookie_value[i + 1:]
+    try:
+        ts = int(ts_str)
+    except ValueError:
+        return False
+    if int(time.time() * 1000) - ts > COOKIE_MAX_AGE * 1000:
+        return False
+    client_id = client_id_for_ip(client_ip, secret)
+    expected = hmac_sign(f"cookie:{ts_str}:{client_id}", secret)
+    return hmac.compare_digest(sig, expected)

agentpayments_python-0.1.0/agentpayments_python/crawler.py

@@ -0,0 +1,74 @@
+"""
+Verified search crawler detection.
+
+UA heuristic + reverse/forward DNS (Google's documented method).
+Results are cached for 1 hour to avoid repeated DNS lookups.
+"""
+import re
+import socket
+import time
+import threading
+from typing import Optional
+
+# (ua_pattern, expected_ptr_suffix)
+# suffix=None means UA match only — not recommended, included for completeness.
+CRAWLERS = [
+    (re.compile(r'googlebot', re.I),             '.googlebot.com'),
+    (re.compile(r'google-inspectiontool', re.I), '.google.com'),
+    (re.compile(r'bingbot', re.I),               '.search.msn.com'),
+    (re.compile(r'slurp', re.I),                 '.crawl.yahoo.net'),
+    (re.compile(r'duckduckbot', re.I),           '.duckduckgo.com'),
+    (re.compile(r'baiduspider', re.I),           '.crawl.baidu.com'),
+    (re.compile(r'yandexbot', re.I),             '.yandex.com'),
+    (re.compile(r'applebot', re.I),              '.applebot.apple.com'),
+]
+
+CRAWLER_CACHE_TTL = 3600  # 1 hour
+_cache: dict[str, tuple[bool, float]] = {}  # ip -> (verified, expiry)
+_cache_lock = threading.Lock()
+
+
+def is_verified_crawler(ip: str, user_agent: str) -> bool:
+    """
+    Return True if the request is from a verified search crawler.
+
+    Verification is: UA matches a known crawler pattern AND the IP's reverse-DNS
+    hostname ends with the crawler's published suffix AND a forward DNS lookup of
+    that hostname resolves back to the same IP.
+
+    Results are cached for 1 hour to limit DNS round-trips. Blocking I/O — for
+    FastAPI/async use, call this in a thread-pool executor.
+    """
+    if not user_agent or not ip or ip == 'unknown':
+        return False
+
+    match = next((c for c in CRAWLERS if c[0].search(user_agent)), None)
+    if match is None:
+        return False
+
+    suffix = match[1]
+
+    with _cache_lock:
+        entry = _cache.get(ip)
+        if entry is not None and entry[1] > time.time():
+            return entry[0]
+
+    verified = _verify_dns(ip, suffix)
+
+    with _cache_lock:
+        _cache[ip] = (verified, time.time() + CRAWLER_CACHE_TTL)
+
+    return verified
+
+
+def _verify_dns(ip: str, suffix: str) -> bool:
+    try:
+        hostname, _, _ = socket.gethostbyaddr(ip)
+        if not hostname.endswith(suffix):
+            return False
+        # Forward verify: resolve hostname back and confirm it includes the original IP.
+        results = socket.getaddrinfo(hostname, None)
+        resolved_ips = {r[4][0] for r in results}
+        return ip in resolved_ips
+    except Exception:
+        return False

agentpayments_python-0.1.0/agentpayments_python/crypto.py

@@ -0,0 +1,43 @@
+import hashlib
+import hmac
+import json
+import uuid
+from pathlib import Path
+
+_constants = json.loads((Path(__file__).resolve().parent / "constants.json").read_text())
+KEY_PREFIX = _constants["KEY_PREFIX"]
+MAX_KEY_LENGTH = _constants["MAX_KEY_LENGTH"]
+
+
+def hmac_sign(data: str, secret: str) -> str:
+    return hmac.new(secret.encode(), data.encode(), hashlib.sha256).hexdigest()
+
+
+def sha256_hex(data: str) -> str:
+    return hashlib.sha256(data.encode()).hexdigest()
+
+
+def client_id_for_ip(ip: str, secret: str) -> str:
+    """Short HMAC of the client IP. Used to bind nonces and cookies to the
+    client that solved the challenge, so a captured cookie is useless from
+    another IP."""
+    return hmac_sign(f"client:{ip}", secret)[:16]
+
+
+def generate_agent_key(secret: str) -> str:
+    random_part = uuid.uuid4().hex[:16]
+    sig = hmac_sign(random_part, secret)
+    return f"{KEY_PREFIX}{random_part}_{sig[:16]}"
+
+
+def is_valid_agent_key(key: str, secret: str) -> bool:
+    if not key or len(key) > MAX_KEY_LENGTH or not key.startswith(KEY_PREFIX):
+        return False
+    rest = key[len(KEY_PREFIX):]
+    i = rest.find("_")
+    if i == -1:
+        return False
+    random_part = rest[:i]
+    sig = rest[i + 1:]
+    expected = hmac_sign(random_part, secret)
+    return hmac.compare_digest(sig, expected[:16])

agentpayments_python-0.1.0/agentpayments_python/detection.py

@@ -0,0 +1,28 @@
+import re as _re
+
+def is_public_path(pathname: str) -> bool:
+    return pathname == "/robots.txt" or pathname.startswith("/.well-known/")
+
+
+# Sec-Fetch-* headers were introduced in Chrome 76 (2019) and Firefox 90 (2021).
+# Older browsers, some mobile WebViews, and certain proxies strip them.
+# This UA pattern matches common desktop/mobile browsers as a fallback so they
+# get a challenge rather than a 402.
+_BROWSER_UA_RE = _re.compile(
+    r"(Chrome|Chromium|Firefox|Safari|Edg|OPR|Opera|SamsungBrowser|UCBrowser|Mobile Safari)"
+    r"(?!/.*bot)",  # exclude UA strings that contain the browser name followed by /.*bot
+    _re.IGNORECASE,
+)
+# Explicit bot/crawler suffixes that should NOT match even if they spoof a browser UA.
+_BOT_UA_RE = _re.compile(r"bot|crawl|spider|slurp|mediapartners|adsbot", _re.IGNORECASE)
+
+
+def is_browser_from_headers(headers: dict) -> bool:
+    # Primary signal: Fetch metadata headers (Chrome 76+, Firefox 90+).
+    if headers.get("sec-fetch-mode") or headers.get("sec-fetch-dest"):
+        return True
+    # Fallback: UA heuristic for older browsers that don't send Sec-Fetch-*.
+    ua = headers.get("user-agent") or headers.get("User-Agent") or ""
+    if ua and not _BOT_UA_RE.search(ua) and _BROWSER_UA_RE.search(ua):
+        return True
+    return False