diff --git a/api/src/sterish_api/config.py b/api/src/sterish_api/config.py index 5944622..207cc05 100644 --- a/api/src/sterish_api/config.py +++ b/api/src/sterish_api/config.py @@ -64,6 +64,12 @@ class Settings: # human to approve a wallet prompt, short enough that a captured signature is # worthless soon after. Clamped to [30, 900]. proof_ttl_seconds: int + # Peers whose X-Forwarded-For / X-Forwarded-Proto are believed (STE-53). The API runs + # behind Cloudflare -> cloudflared -> Caddy; without this every public request looks + # like it came from Caddy's container address, so all visitors shared one rate-limit + # bucket and generated URLs said http://. Only proxies are trusted, never clients: + # the port is not published outside the compose network. + trusted_proxies: str @property def network(self) -> str: @@ -132,6 +138,10 @@ def load_settings() -> Settings: indexer_chunk_ledgers=_env_int("INDEXER_CHUNK_LEDGERS", 4000), report_base_url=os.getenv("REPORT_BASE_URL", "").rstrip("/"), proof_ttl_seconds=min(900, max(30, _env_int("STERISH_PROOF_TTL_SECONDS", 300))), + trusted_proxies=os.getenv( + "STERISH_TRUSTED_PROXIES", + "127.0.0.1,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,fd00::/8", + ).strip(), ) diff --git a/api/src/sterish_api/main.py b/api/src/sterish_api/main.py index f28c12b..a906c41 100644 --- a/api/src/sterish_api/main.py +++ b/api/src/sterish_api/main.py @@ -11,6 +11,7 @@ from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware from fastapi.responses import JSONResponse +from uvicorn.middleware.proxy_headers import ProxyHeadersMiddleware from . import chain, indexer, payments, proofs, x402 from .chain import ChainError, ContractError, NotConfiguredError @@ -96,6 +97,11 @@ async def lifespan(app: FastAPI): ], ) app.add_middleware(RateLimitMiddleware) +# Added last so it runs first: the client address and scheme are restored from the +# trusted proxy chain BEFORE the rate limiter keys on the address and before any route +# builds a URL from the request (STE-53). uvicorn's own proxy handling is switched off +# in the Dockerfile so there is exactly one place that decides whom to believe. +app.add_middleware(ProxyHeadersMiddleware, trusted_hosts=settings.trusted_proxies) app.add_exception_handler(ApiError, api_error_handler) app.add_exception_handler(ContractError, contract_error_handler) diff --git a/api/tests/test_proxy_headers.py b/api/tests/test_proxy_headers.py new file mode 100644 index 0000000..f4e73d6 --- /dev/null +++ b/api/tests/test_proxy_headers.py @@ -0,0 +1,146 @@ +"""The API behind Cloudflare -> cloudflared -> Caddy sees the client, not the proxy (STE-53). + +Found on production: every public request reached the API from Caddy's container +address, so the per-IP rate limit was one bucket shared by every visitor, and URLs built +from the request (the x402 `resource.url`, the STE-48 `challenge_url`) said `http://`. +""" + +import base64 +import json + +import pytest +from fastapi import FastAPI, Request +from fastapi.testclient import TestClient +from uvicorn.middleware.proxy_headers import ProxyHeadersMiddleware + +from sterish_api.ratelimit import RateLimitMiddleware + +PROXY = "172.18.0.3" # Caddy on the compose network +CLIENT_A = "203.0.113.10" # documentation ranges: two real visitors +CLIENT_B = "198.51.100.20" + + +def _app(limit, trusted, peer): + """The production middleware order, with the TCP peer address under test control.""" + app = FastAPI() + app.add_middleware(RateLimitMiddleware, limit_per_minute=limit) + app.add_middleware(ProxyHeadersMiddleware, trusted_hosts=trusted) + + @app.get("/who") + def who(request: Request): + return {"client": request.client.host, "url": str(request.url)} + + return TestClient(app, client=(peer, 50000)) + + +def fwd(client, proto="https"): + return {"X-Forwarded-For": client, "X-Forwarded-Proto": proto} + + +def test_two_visitors_behind_the_same_proxy_get_their_own_buckets(): + c = _app(2, "172.16.0.0/12", PROXY) + assert [c.get("/who", headers=fwd(CLIENT_A)).status_code for _ in range(2)] == [200, 200] + assert c.get("/who", headers=fwd(CLIENT_A)).status_code == 429 + # Before STE-53 this was 429 too: B was counted in A's bucket, because both were PROXY. + assert c.get("/who", headers=fwd(CLIENT_B)).status_code == 200 + + +def test_the_route_sees_the_real_client_and_scheme(): + body = _app(0, "172.16.0.0/12", PROXY).get("/who", headers=fwd(CLIENT_A)).json() + assert body["client"] == CLIENT_A + assert body["url"].startswith("https://") + + +def test_an_untrusted_peer_cannot_choose_its_own_address(): + """A client talking to the API directly must not dodge the limit with a fake header.""" + c = _app(1, "172.16.0.0/12", CLIENT_A) + assert c.get("/who", headers=fwd("1.1.1.1")).status_code == 200 + r = c.get("/who", headers=fwd("8.8.8.8")) + assert r.status_code == 429 # still keyed on CLIENT_A, the real peer + + +def test_a_spoofed_left_entry_is_ignored_when_the_chain_is_trusted(): + """X-Forwarded-For: , , . + The rightmost untrusted entry is the client; anything to its left is theirs to invent.""" + c = _app(0, "172.16.0.0/12", PROXY) + body = c.get("/who", headers=fwd(f"6.6.6.6, {CLIENT_A}, 172.18.0.2")).json() + assert body["client"] == CLIENT_A + + +def test_the_app_is_wired_with_the_proxy_middleware_outermost(): + from sterish_api.main import app + + names = [m.cls.__name__ for m in app.user_middleware] + assert names[0] == "ProxyHeadersMiddleware" # first in this list = outermost + assert names.index("ProxyHeadersMiddleware") < names.index("RateLimitMiddleware") + + +def test_the_default_trust_covers_the_compose_network_and_not_the_internet(): + from uvicorn.middleware.proxy_headers import _TrustedHosts + + from sterish_api.config import settings + + trusted = _TrustedHosts(settings.trusted_proxies) + assert PROXY in trusted and "172.18.0.2" in trusted and "127.0.0.1" in trusted + assert CLIENT_A not in trusted and "8.8.8.8" not in trusted + + +@pytest.fixture +def behind_proxy(monkeypatch, client): + """The real app, reached as Caddy forwarding an https request.""" + return TestClient(client.app, client=(PROXY, 50000)) + + +def test_the_x402_challenge_advertises_https_behind_the_proxy(behind_proxy, monkeypatch, tmp_path): + from sterish_pipeline.content_hash import content_hash + + from sterish_api import chain + from sterish_api.config import settings + + root = tmp_path / "artifacts" / "com.acme.pdf-suite" / "1.0.0" + root.mkdir(parents=True) + (root / "manifest.json").write_bytes(b"{}\n") + digest = content_hash({"manifest.json": b"{}\n"}) + record = {"skill_id": "com.acme.pdf-suite", "version": "1.0.0", "content_hash": digest, + "verdict": "SAFE", "is_verified": True} + monkeypatch.setattr(chain, "get_version", lambda s, v: record) + previous = settings.skills_dir + object.__setattr__(settings, "skills_dir", str(tmp_path / "artifacts")) + try: + r = behind_proxy.get("/use/com.acme.pdf-suite/1.0.0", + headers={**fwd(CLIENT_A), "Host": "api-sterish.jameshub.fun"}) + finally: + object.__setattr__(settings, "skills_dir", previous) + assert r.status_code == 402 + challenge = json.loads(base64.b64decode(r.headers["PAYMENT-REQUIRED"])) + assert challenge["resource"]["url"] == ( + "https://api-sterish.jameshub.fun/use/com.acme.pdf-suite/1.0.0" + ) + + +def test_the_ownership_challenge_url_is_https_behind_the_proxy(behind_proxy, monkeypatch, tmp_path): + from sterish_pipeline.content_hash import content_hash + + from sterish_api import chain + from sterish_api.config import settings + + holder = "GD73M4F7RN74KBLFGJP4WKBMCBJWBOA4SFNOP5HG4NBCDQUQCC2ARSZU" + root = tmp_path / "artifacts" / "com.acme.pdf-suite" / "1.0.0" + root.mkdir(parents=True) + (root / "manifest.json").write_bytes(b"{}\n") + digest = content_hash({"manifest.json": b"{}\n"}) + monkeypatch.setattr(chain, "get_version", lambda s, v: { + "skill_id": s, "version": v, "content_hash": digest, "verdict": "SAFE", + "is_verified": True}) + monkeypatch.setattr(chain, "has_license", lambda a, s, v: True) + previous = settings.skills_dir + object.__setattr__(settings, "skills_dir", str(tmp_path / "artifacts")) + try: + r = behind_proxy.get("/use/com.acme.pdf-suite/1.0.0", headers={ + **fwd(CLIENT_A), "Host": "api-sterish.jameshub.fun", "X-AGENT-ADDRESS": holder}) + finally: + object.__setattr__(settings, "skills_dir", previous) + assert r.status_code == 401 + assert r.json()["challenge_url"].startswith( + "https://api-sterish.jameshub.fun/use/com.acme.pdf-suite/1.0.0/challenge" + ) diff --git a/deploy/Caddyfile b/deploy/Caddyfile index 095bdfc..6e0c1cd 100644 --- a/deploy/Caddyfile +++ b/deploy/Caddyfile @@ -11,6 +11,16 @@ # are issued fine without a contact address; to add one, put `tls you@example.com` # inside the site block below. +# STE-53: keep the client's address and scheme from the proxies in front of Caddy +# (cloudflared on the compose network, tailscale serve via the host gateway), instead of +# replacing them with Caddy's own view. Only private-range peers are trusted, so a client +# on the internet cannot set its own X-Forwarded-For. +{ + servers { + trusted_proxies static private_ranges + } +} + {$STERISH_DOMAIN} { encode gzip diff --git a/deploy/Dockerfile b/deploy/Dockerfile index 8fce3e6..29cad4c 100644 --- a/deploy/Dockerfile +++ b/deploy/Dockerfile @@ -65,4 +65,6 @@ EXPOSE 8000 HEALTHCHECK --interval=30s --timeout=10s --start-period=20s --retries=3 \ CMD python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8000/health', timeout=8).status==200 else 1)" -CMD ["uvicorn", "sterish_api.main:app", "--host", "0.0.0.0", "--port", "8000"] +# --no-proxy-headers: the app applies the trusted-proxy chain itself (STE-53, +# STERISH_TRUSTED_PROXIES), so the rule is testable and lives in one place. +CMD ["uvicorn", "sterish_api.main:app", "--host", "0.0.0.0", "--port", "8000", "--no-proxy-headers"] diff --git a/deploy/README.md b/deploy/README.md index 9b09dda..3a83c08 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -161,6 +161,28 @@ that restarts forever while every other service looks healthy. `*.jameshub.fun` — a single level. `api.sterish.jameshub.fun` would need a wildcard that is not covered, so the name is `api-sterish.jameshub.fun`. +## Client address and scheme behind the proxies (STE-53) + +Requests arrive as **Cloudflare → cloudflared → Caddy → API**. Two settings make the API see the +visitor rather than the last proxy, and both are needed: + +- `Caddyfile` sets `trusted_proxies static private_ranges`, so Caddy keeps the `X-Forwarded-For` + and `X-Forwarded-Proto` that cloudflared (or `tailscale serve`) sends instead of overwriting them + with its own view. +- The API applies those headers only when its direct peer is in `STERISH_TRUSTED_PROXIES` + (private ranges by default) — uvicorn's own handling is off (`--no-proxy-headers`), so there is + one rule in one place. + +Without the first, every public request reaches the API from Caddy's container address: the +per-IP rate limit becomes a single bucket for the whole internet, and the x402 challenge advertises +`http://`. Measured on 17 Sep 2026 with a real Caddy in front of the API: with the old Caddyfile a +second visitor got `429` because of the first visitor's traffic and `resource.url` was `http://`; +with the new one, `200` and `https://`. + +Trust is limited to private ranges, so it also covers anything on the LAN that can reach the +published port 80 directly. That is acceptable on the homelab network; tighten +`STERISH_TRUSTED_PROXIES` to the compose subnet if the host moves somewhere shared. + ## Two things that will bite otherwise **The build context is the repo root.** Without `.dockerignore` every build ships diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml index baaa9df..591dd29 100644 --- a/deploy/docker-compose.yml +++ b/deploy/docker-compose.yml @@ -24,6 +24,10 @@ services: STELLAR_NETWORK_PASSPHRASE: ${STELLAR_NETWORK_PASSPHRASE:-Test SDF Network ; September 2015} INDEXER_ENABLED: ${INDEXER_ENABLED:-1} RATE_LIMIT_PER_MINUTE: ${RATE_LIMIT_PER_MINUTE:-100} + # Proxies whose forwarding headers are believed (STE-53): cloudflared and Caddy on + # this compose network, tailscale serve via the host gateway. Per-IP rate limiting + # and the https URLs in x402 challenges depend on it. + STERISH_TRUSTED_PROXIES: ${STERISH_TRUSTED_PROXIES:-127.0.0.1,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,fd00::/8} # Per-row chain reads a single /skills request may have in flight (STE-33). # Lower it if the RPC node starts rate-limiting; the page just gets slower. STERISH_CHAIN_CONCURRENCY: ${STERISH_CHAIN_CONCURRENCY:-20} diff --git a/docs/api-spec.md b/docs/api-spec.md index 0b185fc..cb5931c 100644 --- a/docs/api-spec.md +++ b/docs/api-spec.md @@ -677,7 +677,12 @@ storage; only `evidence_hash` is on the ledger. skill can be registered at any moment. - **Fan-out cap.** `GET /skills/{skill_id}` needs one `get_version` per version; cap it at 50 versions per response and paginate beyond that. -- **Rate limiting.** 100 req/min per IP by default (configurable). +- **Rate limiting.** 100 req/min per client IP by default (configurable). The client IP is the + real visitor's, taken from `X-Forwarded-For` **only when the direct peer is a trusted proxy** + (`STERISH_TRUSTED_PROXIES`, private ranges by default), so a caller cannot choose its own bucket. + Until STE-53 the limiter keyed on the proxy's address, so every public visitor shared one bucket. + The same rule sets the scheme of URLs the API builds from a request (the x402 `resource.url`, + the STE-48 `challenge_url`): `https` when the proxy chain says so. - **CORS.** Open — everything served is public ledger data. - **Config.** `REGISTRY_CONTRACT_ID` (or `REGISTRY_CA`, the name the deploy scripts write), `STELLAR_RPC_URL`, `STELLAR_NETWORK_PASSPHRASE`. Full list with defaults in diff --git a/docs/evidence/ste-53-proxy-aware-2026-09-17.json b/docs/evidence/ste-53-proxy-aware-2026-09-17.json new file mode 100644 index 0000000..8051a26 --- /dev/null +++ b/docs/evidence/ste-53-proxy-aware-2026-09-17.json @@ -0,0 +1,35 @@ +{ + "ticket": "STE-53", + "date": "2026-09-17", + "production_before_fix": { + "api_log_client_addresses_last_400_lines": { + "127.0.0.1 (healthcheck)": 74, + "172.18.0.3 (caddy container)": 165 + }, + "x402_resource_url": "http://api-sterish.jameshub.fun/use/org.stellar.skills.cross-chain.cctp/2026.8.31", + "429_in_last_24h": 0 + }, + "e2e": { + "setup": "caddy:2-alpine (host network, :8095) in front of this branch's API (uvicorn --no-proxy-headers, RATE_LIMIT_PER_MINUTE=3); requests carry X-Forwarded-For + X-Forwarded-Proto: https as cloudflared sends them", + "old_caddyfile": { + "resource_url": "http://api-sterish.jameshub.fun/use/org.stellar.skills.cross-chain.cctp/2026.8.31", + "client_A_3_requests": [ + 200, + 200, + 200 + ], + "client_B_first_request": 429 + }, + "new_caddyfile": { + "resource_url": "https://api-sterish.jameshub.fun/use/org.stellar.skills.cross-chain.cctp/2026.8.31", + "client_A_3_requests": [ + 200, + 200, + 200 + ], + "client_B_first_request": 200 + }, + "api_log_with_new_caddyfile": "client addresses 203.0.113.10 and 198.51.100.20 (the real visitors), not the proxy" + }, + "caddy_validate": "Valid configuration (caddy:2-alpine)" +} \ No newline at end of file