security: harden route-based pricing (path norm, numeric prices, limits)

- Normalize path: unquote encoding, collapse . and .., cap length 2048
- Only numeric prices in price_by_route; invalid fallback to 1000
- Max 256 route entries; non-numeric and excess entries ignored
- Docs: PUBLISHER_GUIDE, README Security, CONCEPTS, DEVELOPMENT

Author: arun-fairfetch

DEVELOPMENT.md

@@ -191,7 +191,7 @@ curl -s "http://localhost:8402/content/fetch?url=http://127.0.0.1/admin" \
 - **`FAIRFETCH_TEST_MODE=true`** (default): CORS allows all origins (`*`); wallet ledger pre-seeds `wallet_test_agent_alpha` and `wallet_test_agent_beta`; mock payment tokens accepted.
 - **`FAIRFETCH_TEST_MODE=false`**: CORS is restricted to `https://{FAIRFETCH_PUBLISHER_DOMAIN}`; no pre-seeded wallets; use real payment integration.
 
-Optional **`FAIRFETCH_PRICE_BY_ROUTE`** (JSON map of path prefix → price) enables variable pricing by content URL path; see [Publisher Guide](docs/PUBLISHER_GUIDE.md) and [README Configuration](README.md#-configuration).
+Optional **`FAIRFETCH_PRICE_BY_ROUTE`** (JSON map of path prefix → price) enables variable pricing by content URL path. Prices must be numeric; path is normalized for matching; up to 256 entries. See [Publisher Guide](docs/PUBLISHER_GUIDE.md) and [README Configuration](README.md#-configuration).
 
 ## Architecture Decisions
 

README.md

@@ -697,6 +697,7 @@ fairfetch/
 ## 🔒 Security
 
 - **URL validation:** The `url` parameter is validated before any outbound request. Private IPs (e.g. `127.0.0.1`, `10.x`, `192.168.x`), cloud metadata endpoints (e.g. `169.254.169.254`), and non-HTTP(S) schemes are rejected with `400` and `error: "url_blocked"`. This prevents SSRF (server-side request forgery).
+- **Route-based pricing:** The content URL path used for price lookup is normalized (percent-encoding decoded, `.` and `..` segments collapsed) so clients cannot bypass route matching to get a different price. Only numeric prices are accepted; invalid route or default prices fall back safely.
 - **Test mode:** With `FAIRFETCH_TEST_MODE=false`, CORS allows only `https://{FAIRFETCH_PUBLISHER_DOMAIN}` and the ledger does not pre-seed test wallets. Use test mode only for local development.
 - **Error responses:** Upstream fetch and summarization errors return generic messages to clients; details are logged server-side only.
 

api/dependencies.py

@@ -5,7 +5,7 @@
 import json
 import os
 from functools import lru_cache
-from urllib.parse import urlparse
+from urllib.parse import unquote, urlparse
 
 from pydantic import BaseModel, Field
 
@@ -102,15 +102,33 @@ def build_license_facilitator(
     return MockLicenseFacilitator(signer)
 
 
+# Max path length for route matching to avoid DoS from huge URLs
+_MAX_PATH_LENGTH = 2048
+# Max route rules to avoid DoS from huge FAIRFETCH_PRICE_BY_ROUTE
+_MAX_PRICE_BY_ROUTE_ENTRIES = 256
+
+
+def _is_valid_price_string(s: str) -> bool:
+    """True if s is a non-empty string of digits (safe for int())."""
+    return isinstance(s, str) and len(s) <= 20 and s.isdigit()
+
+
 def _parse_price_by_route(raw: str) -> dict[str, str]:
-    """Parse FAIRFETCH_PRICE_BY_ROUTE JSON (path prefix -> price)."""
+    """Parse FAIRFETCH_PRICE_BY_ROUTE JSON (path prefix -> price). Only numeric prices kept."""
     if not raw or not raw.strip():
         return {}
     try:
         data = json.loads(raw)
         if not isinstance(data, dict):
             return {}
-        return {str(k): str(v) for k, v in data.items()}
+        out: dict[str, str] = {}
+        for k, v in data.items():
+            if len(out) >= _MAX_PRICE_BY_ROUTE_ENTRIES:
+                break
+            vs = str(v)
+            if _is_valid_price_string(vs):
+                out[str(k)] = vs
+        return out
     except (json.JSONDecodeError, TypeError):
         return {}
 
@@ -120,33 +138,68 @@ def resolve_content_price(config: FairFetchConfig, content_url: str) -> str:
 
     The content URL path (e.g. /business, /sports) is matched against
     config.price_by_route; longest matching prefix wins. If no rules or no
-    match, returns config.content_price.
+    match, returns config.content_price. Path is normalized to prevent
+    bypass via encoding or traversal.
     """
     if not config.price_by_route:
-        return config.content_price
+        return config.content_price if _is_valid_price_string(config.content_price) else "1000"
     path = _path_from_content_url(content_url)
     # Longest matching prefix first
     candidates = sorted(config.price_by_route.keys(), key=len, reverse=True)
     for prefix in candidates:
         if path == prefix or path.startswith(prefix + "/"):
-            return config.price_by_route[prefix]
+            price = config.price_by_route[prefix]
+            if _is_valid_price_string(price):
+                return price
+            break
     # Explicit default key "" if present
     if "" in config.price_by_route:
-        return config.price_by_route[""]
-    return config.content_price
+        p = config.price_by_route[""]
+        if _is_valid_price_string(p):
+            return p
+    # Fallback: ensure we never return a non-numeric price (misconfig)
+    return config.content_price if _is_valid_price_string(config.content_price) else "1000"
+
+
+def _normalize_path(path: str) -> str:
+    """Decode percent-encoding and collapse . / .. segments to prevent price bypass."""
+    decoded = unquote(path)
+    if len(decoded) > _MAX_PATH_LENGTH:
+        decoded = decoded[:_MAX_PATH_LENGTH]
+    parts = decoded.split("/")
+    out: list[str] = []
+    for part in parts:
+        if part == ".":
+            continue
+        if part == "":
+            if not out:
+                out.append("")
+            continue
+        if part == "..":
+            if out and out[-1] != "":
+                out.pop()
+            continue
+        out.append(part)
+    joined = "/".join(out) if out else "/"
+    return joined if joined.startswith("/") else "/" + joined
 
 
 def _path_from_content_url(content_url: str) -> str:
-    """Extract path for route matching. Handles full URLs and bare paths."""
+    """Extract and normalize path for route matching. Handles full URLs and bare paths.
+    Decodes percent-encoding before parsing so %2F cannot be used to bypass route match.
+    """
     s = (content_url or "").strip()
     if not s:
         return "/"
     if "://" in s:
+        # Decode so path is consistent (e.g. %2F -> /) and cannot be used to bypass
+        s = unquote(s)
         parsed = urlparse(s)
         path = parsed.path or "/"
     else:
         path = s if s.startswith("/") else "/" + s
-    return path if path else "/"
+    path = path or "/"
+    return _normalize_path(path)
 
 
 def build_payment_requirement(

docs/CONCEPTS.md

@@ -264,7 +264,7 @@ what it costs. Here's what each field means:
 | `compliance_level` | How strict the rules are for that tier. "standard" for light use, "strict" for training/commercial. |
 | `available_tiers` | A menu of all options with prices, so your agent can pick the cheapest tier that fits its needs. |
 
-**Variable pricing by route:** A publisher can configure different base prices for different URL paths (e.g. `FAIRFETCH_PRICE_BY_ROUTE` in the [Publisher Guide](PUBLISHER_GUIDE.md)). The 402 response for `?url=https://site.com/business` may show a different base price than `?url=https://site.com/sports`. Longest path prefix wins; the default price applies when no path matches.
+**Variable pricing by route:** A publisher can configure different base prices for different URL paths (e.g. `FAIRFETCH_PRICE_BY_ROUTE` in the [Publisher Guide](PUBLISHER_GUIDE.md)). The 402 response for `?url=https://site.com/business` may show a different base price than `?url=https://site.com/sports`. Longest path prefix wins; the default price applies when no path matches. The path is normalized (encoding decoded, traversal collapsed) so route matching cannot be bypassed; only numeric prices are used.
 
 ---
 
@@ -293,7 +293,7 @@ The `Accept` header in your request tells Fairfetch what format you want:
 | **USDC** | A stablecoin (cryptocurrency) pegged 1:1 to the US Dollar. Used for micro-payments because it has low transaction fees. |
 | **Wallet (Pre-Funded)** | An account with a prepaid balance. AI agents include a wallet token in their requests, and the fee is deducted automatically — no 402 round-trip needed. Like an E-ZPass for content. |
 | **Wallet Token** | A string (like `wallet_test_agent_alpha`) that identifies a pre-funded wallet. Include it in the `X-WALLET-TOKEN` header. |
-| **Route-based pricing** | Optional publisher config (`FAIRFETCH_PRICE_BY_ROUTE`) that sets different base prices for different URL path prefixes (e.g. `/business` vs `/sports`). Longest matching path wins; the 402 quote reflects the base price for the requested content URL. |
+| **Route-based pricing** | Optional publisher config (`FAIRFETCH_PRICE_BY_ROUTE`) that sets different base prices for different URL path prefixes (e.g. `/business` vs `/sports`). Longest matching path wins; the 402 quote reflects the base price for the requested content URL. Path is normalized and only numeric prices are accepted. |
 | **x402** | A protocol that uses HTTP status code 402 to enable machine-to-machine payments. The server tells the client the price; the client pays and retries. |
 | **Usage Grant** | A signed receipt proving an AI agent was authorized to use specific content for a specific purpose. |
 | **Bot Steering** | The practice of redirecting web crawlers from scraping HTML to using the publisher's official API instead. |

docs/PUBLISHER_GUIDE.md

@@ -180,6 +180,8 @@ FAIRFETCH_PRICE_BY_ROUTE='{"": "1000", "/business": "2000", "/sports": "500"}'
 
 Here, `/business` (and `/business/...`) is 2000, `/sports` is 500, and all other paths use the default 1000. Omit `FAIRFETCH_PRICE_BY_ROUTE` to use a single price for the whole site.
 
+**Behavior and limits:** Prices must be numeric (digits only); non-numeric values are ignored. The content URL path is normalized (percent-encoding decoded, `.` and `..` segments collapsed) so route matching cannot be bypassed. At most 256 route entries are used; extra entries are ignored.
+
 ### 3.2 Generate a signing key (recommended for production)
 
 This key lets AI agents (and you) verify that content really came from your server.

tests/test_route_pricing.py

@@ -5,6 +5,7 @@
 from api.dependencies import (
     FairFetchConfig,
     _parse_price_by_route,
+    _path_from_content_url,
     build_payment_requirement,
     resolve_content_price,
 )
@@ -29,6 +30,22 @@ def test_invalid_json_returns_empty_dict(self):
         assert _parse_price_by_route("not json") == {}
         assert _parse_price_by_route("{/business: 2000}") == {}
 
+    def test_non_numeric_prices_dropped(self):
+        # Only numeric price strings are kept; invalid values skipped
+        result = _parse_price_by_route(
+            '{"": "1000", "/a": "2000", "/b": "bad", "/c": "3.14", "/d": ""}'
+        )
+        assert result == {"": "1000", "/a": "2000"}
+
+    def test_max_entries_cap(self):
+        # More than _MAX_PRICE_BY_ROUTE_ENTRIES: only first 256 kept
+        from api.dependencies import _MAX_PRICE_BY_ROUTE_ENTRIES
+
+        entries = {f"/p{i}": "1000" for i in range(_MAX_PRICE_BY_ROUTE_ENTRIES + 10)}
+        raw = "{" + ", ".join(f'"{k}": "{v}"' for k, v in entries.items()) + "}"
+        result = _parse_price_by_route(raw)
+        assert len(result) == _MAX_PRICE_BY_ROUTE_ENTRIES
+
 
 class TestResolveContentPrice:
     def test_no_rules_uses_default(self):
@@ -65,6 +82,40 @@ def test_bare_path_handled(self):
         assert resolve_content_price(config, "/business") == "2000"
         assert resolve_content_price(config, "/sports") == "1000"
 
+    def test_path_normalization_prevents_bypass(self):
+        # Traversal: /business/../sports must resolve to /sports price
+        config = FairFetchConfig(
+            content_price="1000",
+            price_by_route={"/business": "2000", "/sports": "500"},
+        )
+        assert resolve_content_price(config, "https://x.com/business/../sports") == "500"
+        assert resolve_content_price(config, "https://x.com/sports/../sports") == "500"
+
+    def test_percent_encoded_path_normalized(self):
+        # %2F (encoded /) decoded so path matches consistently
+        config = FairFetchConfig(
+            content_price="1000",
+            price_by_route={"/business": "2000"},
+        )
+        assert resolve_content_price(config, "https://x.com/business") == "2000"
+        # Path with encoded slash still matches after unquote
+        assert resolve_content_price(config, "https://x.com%2Fbusiness") == "2000"
+
+    def test_invalid_content_price_fallback(self):
+        config = FairFetchConfig(
+            content_price="not_a_number",
+            price_by_route={},
+        )
+        assert resolve_content_price(config, "https://x.com/any") == "1000"
+
+    def test_invalid_route_price_fallback_to_default(self):
+        config = FairFetchConfig(
+            content_price="1000",
+            price_by_route={"/premium": "invalid", "": "999"},
+        )
+        # /premium matches but value invalid -> fall through to "" -> 999
+        assert resolve_content_price(config, "https://x.com/premium") == "999"
+
 
 class TestBuildPaymentRequirementWithRoute:
     def test_without_content_url_uses_default_price(self):
@@ -81,3 +132,21 @@ def test_with_content_url_uses_route_price(self):
         req_sports = build_payment_requirement(config, "https://abc.com/sports")
         assert req_business.price == "2000"
         assert req_sports.price == "500"
+
+
+class TestPathNormalization:
+    """Security: path normalization to prevent price bypass."""
+
+    def test_traversal_collapsed(self):
+        assert _path_from_content_url("https://x.com/business/../sports") == "/sports"
+        assert _path_from_content_url("https://x.com/a/b/../../c") == "/c"
+
+    def test_dot_segments_removed(self):
+        assert _path_from_content_url("https://x.com/./business/.//x") == "/business/x"
+
+    def test_path_length_capped(self):
+        from api.dependencies import _MAX_PATH_LENGTH
+
+        long_path = "https://x.com/" + ("a" * (_MAX_PATH_LENGTH + 100))
+        result = _path_from_content_url(long_path)
+        assert len(result) <= _MAX_PATH_LENGTH + 1  # +1 for leading /