diff --git a/README.md b/README.md index f8e48ee..eb42de3 100644 --- a/README.md +++ b/README.md @@ -112,6 +112,7 @@ The `bal-server` application can be configured using environment variables. | `BAL_SERVER_ACTIX_DEFAULT_BURST` | Rate limit: default burst size. | `100` | | `BAL_SERVER_ACTIX_WORKERS` | Number of Actix worker threads. | `4` | | `BAL_SERVER_ACTIX_MAX_CONNECTIONS` | Maximum concurrent connections. | `100` | +| `BAL_SERVER_TRUSTED_PROXY` | Trusted reverse proxy IP for rate-limiting client identification. | `127.0.0.1` | --- diff --git a/docs/04_modules_detail.md b/docs/04_modules_detail.md index da8bf6e..d2c96f9 100644 --- a/docs/04_modules_detail.md +++ b/docs/04_modules_detail.md @@ -117,7 +117,7 @@ The main application binary that provides an async HTTP server. ### Architecture - **Runtime:** `actix-web 4.9.0` with `actix-rt` (`#[actix_web::main]`). -- **Rate Limiting:** `actix-governor` middleware with token-bucket algorithm per endpoint. +- **Rate Limiting:** `actix-governor` middleware with token-bucket algorithm. Uses `RealIpKeyExtractor` to identify clients by real IP behind reverse proxy (via `X-Real-IP` / `X-Forwarded-For` headers). - **Response Compression:** `actix_web::middleware::Compress`. - **Request Logging:** `actix_web::middleware::Logger::default()`. - **Shared State:** `Arc>` for database access, `MyConfig` for configuration. @@ -132,7 +132,7 @@ The main application binary that provides an async HTTP server. - `address` (xpub or address), `fixed_fee` (sats), `xpub` (bool), `network` (bitcoin::Network), `name`, `enabled` **`ActixConfig`** (server tuning): -- `max_body_size`, `timeout_secs`, per-endpoint rate limits (`pushtxs`, `searchtx`, `info`, `default`), `workers`, `max_connections` +- `max_body_size`, `timeout_secs`, rate limits (`pushtxs` per sec/burst), `workers`, `max_connections`, `trusted_proxy` ### Key Routes | Method | Path | Handler | Description | diff --git a/docs/05_api_reference.md b/docs/05_api_reference.md index 6105828..08cec81 100644 --- a/docs/05_api_reference.md +++ b/docs/05_api_reference.md @@ -10,16 +10,11 @@ ### Rate Limiting -All endpoints are rate-limited via `actix-governor` with a token-bucket algorithm. Defaults: +All endpoints are rate-limited via `actix-governor` with a token-bucket algorithm. The rate limit key is the **real client IP address**, extracted from `X-Real-IP` / `X-Forwarded-For` headers when the request comes from a trusted proxy (default `127.0.0.1`, configurable via `BAL_SERVER_TRUSTED_PROXY`). Direct connections (non-proxy) use the TCP peer IP. -| Endpoint | Rate (req/s) | Burst | -|----------|-------------|-------| -| `POST /{network}/pushtxs` | 1 | 3 | -| `POST /searchtx` | 5 | 10 | -| `GET /{network}/info` | 20 | 30 | -| All others | 50 | 100 | +Default: 1 req/s with burst of 3 (configurable via `BAL_SERVER_ACTIX_PUSHTXS_PER_SEC` / `BAL_SERVER_ACTIX_PUSHTXS_BURST`). -Rate limits are configurable via `BAL_SERVER_ACTIX_*` environment variables. +When behind Nginx, ensure `proxy_set_header X-Real-IP $remote_addr` is set so the server can identify individual clients. ### `GET /` - **Description:** Returns a static identification string (default: "Will Executor Server"). diff --git a/docs/07_deployment_and_ops.md b/docs/07_deployment_and_ops.md index 5a7176c..d3c208d 100644 --- a/docs/07_deployment_and_ops.md +++ b/docs/07_deployment_and_ops.md @@ -40,8 +40,9 @@ Example: `BAL_SERVER_REGTEST_ADDRESS=tpub...`, `BAL_SERVER_BITCOIN_FIXED_FEE=500 | `BAL_SERVER_ACTIX_TIMEOUT_SECS` | `5` | Request timeout in seconds | | `BAL_SERVER_ACTIX_WORKERS` | `4` | Number of actix-web worker threads | | `BAL_SERVER_ACTIX_MAX_CONNECTIONS` | `100` | Maximum concurrent connections | -| `BAL_SERVER_ACTIX_PUSHTXS_PER_SEC` | `1` | Rate limit: pushtxs requests per second | -| `BAL_SERVER_ACTIX_PUSHTXS_BURST` | `3` | Rate limit: pushtxs burst size | +| `BAL_SERVER_TRUSTED_PROXY` | `127.0.0.1` | Trusted reverse proxy IP for rate-limiting client identification | +| `BAL_SERVER_ACTIX_PUSHTXS_PER_SEC` | `1` | Rate limit: requests per second (applied to all endpoints) | +| `BAL_SERVER_ACTIX_PUSHTXS_BURST` | `3` | Rate limit: burst size (applied to all endpoints) | | `BAL_SERVER_ACTIX_SEARCHTX_PER_SEC` | `5` | Rate limit: searchtx requests per second | | `BAL_SERVER_ACTIX_SEARCHTX_BURST` | `10` | Rate limit: searchtx burst size | | `BAL_SERVER_ACTIX_INFO_PER_SEC` | `20` | Rate limit: info requests per second | diff --git a/docs/08_security_audit.md b/docs/08_security_audit.md index 98d0628..c8156fd 100644 --- a/docs/08_security_audit.md +++ b/docs/08_security_audit.md @@ -52,7 +52,7 @@ **Description:** All DoS vectors mitigated via actix-web migration. **Mitigation Applied:** - Body size limit: `PayloadConfig::default().limit(max_body_size)` via `BAL_SERVER_ACTIX_MAX_BODY_SIZE` (default 1 MiB). -- Rate limiting: `actix-governor` with token-bucket per endpoint (`BAL_SERVER_ACTIX_PUSHTXS_PER_SEC`/`BURST`). +- Rate limiting: `actix-governor` with token-bucket per client IP (`BAL_SERVER_ACTIX_PUSHTXS_PER_SEC`/`BURST`). Uses `RealIpKeyExtractor` to extract real client IP from proxy headers. - Connection limits: `workers(4)` and `max_connections(100)` via `BAL_SERVER_ACTIX_WORKERS`/`MAX_CONNECTIONS`. - Body timeout: configurable via `BAL_SERVER_ACTIX_TIMEOUT_SECS`. - ZMQ timeout: `set_rcvtimeo(5000)` prevents infinite blocking. @@ -130,7 +130,7 @@ 6. Use read-only filesystem for the server binary. ### Application-Level -1. **Rate Limiting:** Implemented via `actix-governor` with per-endpoint token-bucket configuration. +1. **Rate Limiting:** Implemented via `actix-governor` with token-bucket per client IP. `RealIpKeyExtractor` identifies clients behind reverse proxy using `X-Real-IP` / `X-Forwarded-For` headers. Trusted proxy IP configurable via `BAL_SERVER_TRUSTED_PROXY`. 2. **Input Validation:** Network enum check, txid hex validation, body size limits. 3. **HTTPS:** Via Nginx reverse proxy with Let's Encrypt. 4. **WAL Mode:** Enabled with retry logic for concurrent access.