Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions api/src/sterish_api/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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(),
)


Expand Down
6 changes: 6 additions & 0 deletions api/src/sterish_api/main.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down
146 changes: 146 additions & 0 deletions api/tests/test_proxy_headers.py
Original file line number Diff line number Diff line change
@@ -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: <what the client typed>, <what Cloudflare saw>, <cloudflared>.
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"
)
10 changes: 10 additions & 0 deletions deploy/Caddyfile
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 3 additions & 1 deletion deploy/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
22 changes: 22 additions & 0 deletions deploy/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions deploy/docker-compose.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down
7 changes: 6 additions & 1 deletion docs/api-spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
35 changes: 35 additions & 0 deletions docs/evidence/ste-53-proxy-aware-2026-09-17.json
Original file line number Diff line number Diff line change
@@ -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)"
}
Loading