Skip to content

Abuse and rate limiting

Witness accepts hashes without accounts. That makes admission simple but lets a spam client submit many cheap requests unless an operator adds an admission boundary. Rate limits are defense in depth, not a complete abuse-control system.

Current built-in limits

  • Gateway attestation creation is limited to 30 requests per IP per minute.
  • A witness node's /v1/sign endpoint is limited to 60 requests per IP per minute, after bearer authentication.

The gateway uses a direct connection IP unless WITNESS_BEHIND_PROXY=true is configured. Behind a proxy, trust X-Forwarded-For only from that trusted proxy. A spoofable forwarded header can defeat per-IP controls and corrupt operational observations.

These limits do not provide identity, anonymity, or internet-scale resistance to distributed abuse. Restrict witness signing routes to trusted gateways.

Optional Freebird admission

Freebird is the current optional anonymous rate-limiting/admission integration. For a public gateway, configure an equivalent admission boundary or require Freebird:

FREEBIRD_VERIFIER_URL=https://freebird-verifier.example.org
FREEBIRD_REQUIRED=true
FREEBIRD_CONSUME_TOKENS=true

Consuming mode sends { "token_b64": "..." } to /v1/verify, records the nullifier, and rejects reuse. Non-consuming mode sends it to /v1/check; it proves possession but permits reuse and therefore needs another replay or rate-control boundary. FREEBIRD_ALLOW_INSECURE_LOCAL is for plaintext loopback tests only and must not be used publicly.

Freebird can make eligibility unlinkable from issuance, but it does not hide source IP, timing, User-Agent, or reverse-proxy metadata. Keep its verifier over HTTPS and keep the gateway SSRF filter enabled. See the Freebird guide for the current contract.