docs: update all documentation for security audit remediations

- Landing page (docs/index.html): add 3 new config fields to tables,
  update security tabs (DoS, TLS, runtime), architecture pipeline
  descriptions, and feature cards
- README.md: update architecture diagram, config tables (+3 fields),
  env vars (+3 vars), DoS mitigations, and path-safety cache design
- USER_GUIDE.md: update config example, env vars table, preload section
  (symlink validation, bounded LRU), add 413 troubleshooting entry
- config.toml.example: add max_compress_size to [compression] section
- CHANGELOG.md: add v1.6.2 entry covering all 16 security fixes,
  dependency bumps, and documentation updates

Author: jkyberneees

CHANGELOG.md

@@ -1,3 +1,29 @@
+## v1.6.2 (2026-04-11)
+
+### Security
+
+- **SEC-001**: replace unbounded `sync.Map` path cache with bounded LRU (10k entries) to prevent memory exhaustion
+- **SEC-003**: suppress stack traces in recovery middleware unless `STATIC_DEBUG=1` is set
+- **SEC-004**: use `crypto/rand` for multipart range boundaries instead of hardcoded string
+- **SEC-005**: add `max_compress_size` config (default 10 MB) to cap on-the-fly compression
+- **SEC-006**: normalize cache keys with `path.Clean` to prevent cache poisoning via path variants
+- **SEC-007**: suppress server banner (`Server` header) on all responses
+- **SEC-008**: sanitize log output by escaping ASCII control characters in request URIs
+- **SEC-009**: remove deprecated `PreferServerCipherSuites` (Go runtime manages cipher order)
+- **SEC-010**: return 500 on directory listing template render failure instead of silently ignoring
+- **SEC-011**: add `max_serve_file_size` config (default 1 GB) with 413 response for oversized files
+- **SEC-014**: set `MaxRequestBodySize` to 1024 bytes (static file server needs no large uploads)
+- **SEC-015**: add `max_conns_per_ip` config for per-IP connection rate limiting
+- **SEC-016**: validate symlink targets stay within document root during preload
+
+### Fix
+
+- **deps**: bump andybalholm/brotli v1.2.0→v1.2.1, klauspost/compress v1.18.4→v1.18.5, valyala/fasthttp v1.69.0→v1.70.0
+
+### Docs
+
+- update landing page, README, USER_GUIDE, and config.toml.example with new config fields and security notes
+
 ## v1.6.1 (2026-03-28)
 
 ### Fix

README.md

@@ -91,7 +91,7 @@ HTTP request
 │  • Method whitelist (GET/HEAD/OPTIONS only)      │
 │  • Security headers (set BEFORE path check)      │
 │  • PathSafe: null bytes, path.Clean, EvalSymlinks│
-│  • Path-safety cache (sync.Map, pre-warmed)      │
+│  • Path-safety cache (bounded LRU, pre-warmed)   │
 │  • Dotfile blocking                              │
 │  • CORS (preflight + per-origin or wildcard *)   │
 │  • Injects validated path into ctx.SetUserValue  │
@@ -129,7 +129,7 @@ GET /app.js
               NO  → os.Stat → os.ReadFile → cache.Put → serveFromCache
 ```
 
-When `preload = true`, every eligible file is loaded into cache at startup. The path-safety cache (`sync.Map`) is also pre-warmed, so the very first request for any preloaded file skips both filesystem I/O and `EvalSymlinks`.
+When `preload = true`, every eligible file is loaded into cache at startup. The path-safety cache (bounded LRU) is also pre-warmed, so the very first request for any preloaded file skips both filesystem I/O and `EvalSymlinks`. Symlink targets are validated against the root during the preload walk — symlinks pointing outside root are skipped.
 
 ---
 
@@ -164,7 +164,7 @@ Measured on Apple M2 Pro (`go test -bench=. -benchtime=5s`):
 - **Direct `ctx.SetBody()` fast path**: cache hits bypass range/conditional logic entirely; pre-formatted `Content-Type` and `Content-Length` headers are assigned directly.
 - **Custom Range implementation**: `parseRange()`/`serveRange()` handle byte-range requests without `http.ServeContent`.
 - **Post-processing compression**: compress middleware runs after the handler, compressing the response body in a single pass.
-- **Path-safety cache**: `sync.Map`-based cache eliminates per-request `filepath.EvalSymlinks` syscalls. Pre-warmed from preload.
+- **Path-safety cache**: Bounded LRU cache (default 10,000 entries) eliminates per-request `filepath.EvalSymlinks` syscalls. Pre-warmed from preload.
 - **GC tuning**: `gc_percent = 400` reduces garbage collection frequency — the hot path avoids all formatting allocations, with only minimal byte-to-string conversions from fasthttp's `[]byte` API.
 - **Cache-before-stat**: `os.Stat` is never called on a cache hit — the hot path is pure memory.
 - **Zero-alloc `AcceptsEncoding`**: walks the `Accept-Encoding` header byte-by-byte without `strings.Split`.
@@ -214,7 +214,8 @@ Only `GET`, `HEAD`, and `OPTIONS` are accepted. All other methods (including `TR
 | `ReadTimeout` | 10 s (covers full read phase including headers — Slowloris protection) |
 | `WriteTimeout` | 10 s |
 | `IdleTimeout` | 75 s (keep-alive) |
-| `MaxRequestBodySize` | 0 (no body accepted — static server) |
+| `MaxRequestBodySize` | 1024 bytes (static file server needs no large request bodies) |
+| `MaxConnsPerIP` | Configurable (default 0 = unlimited) |
 
 ---
 
@@ -235,6 +236,7 @@ Copy `config.toml.example` to `config.toml` and edit as needed. The server start
 | `write_timeout` | duration | `10s` | Response write deadline |
 | `idle_timeout` | duration | `75s` | Keep-alive idle timeout |
 | `shutdown_timeout` | duration | `15s` | Graceful drain window |
+| `max_conns_per_ip` | int | `0` | Max concurrent connections per IP (0 = unlimited) |
 
 ### `[files]`
 
@@ -243,6 +245,7 @@ Copy `config.toml.example` to `config.toml` and edit as needed. The server start
 | `root` | string | `./public` | Directory to serve |
 | `index` | string | `index.html` | Index file for directory requests |
 | `not_found` | string | — | Custom 404 page (relative to `root`) |
+| `max_serve_file_size` | int | `1073741824` | Max file size to serve in bytes (0 = unlimited; default 1 GB). Files exceeding this limit receive 413. |
 
 ### `[cache]`
 
@@ -263,6 +266,7 @@ Copy `config.toml.example` to `config.toml` and edit as needed. The server start
 | `min_size` | int | `1024` | Minimum bytes to compress |
 | `level` | int | `5` | gzip level (1–9) |
 | `precompressed` | bool | `true` | Serve `.gz`/`.br`/`.zst` sidecar files |
+| `max_compress_size` | int | `10485760` | Max body size for on-the-fly gzip compression in bytes (0 = unlimited; default 10 MB) |
 
 ### `[headers]`
 
@@ -303,9 +307,11 @@ All environment variables override the corresponding TOML setting. Useful for co
 | `STATIC_SERVER_WRITE_TIMEOUT` | `server.write_timeout` |
 | `STATIC_SERVER_IDLE_TIMEOUT` | `server.idle_timeout` |
 | `STATIC_SERVER_SHUTDOWN_TIMEOUT` | `server.shutdown_timeout` |
+| `STATIC_SERVER_MAX_CONNS_PER_IP` | `server.max_conns_per_ip` |
 | `STATIC_FILES_ROOT` | `files.root` |
 | `STATIC_FILES_INDEX` | `files.index` |
 | `STATIC_FILES_NOT_FOUND` | `files.not_found` |
+| `STATIC_FILES_MAX_SERVE_FILE_SIZE` | `files.max_serve_file_size` |
 | `STATIC_CACHE_ENABLED` | `cache.enabled` |
 | `STATIC_CACHE_PRELOAD` | `cache.preload` |
 | `STATIC_CACHE_MAX_BYTES` | `cache.max_bytes` |
@@ -315,6 +321,7 @@ All environment variables override the corresponding TOML setting. Useful for co
 | `STATIC_COMPRESSION_ENABLED` | `compression.enabled` |
 | `STATIC_COMPRESSION_MIN_SIZE` | `compression.min_size` |
 | `STATIC_COMPRESSION_LEVEL` | `compression.level` |
+| `STATIC_COMPRESSION_MAX_COMPRESS_SIZE` | `compression.max_compress_size` |
 | `STATIC_HEADERS_ENABLE_ETAGS` | `headers.enable_etags` |
 | `STATIC_SECURITY_BLOCK_DOTFILES` | `security.block_dotfiles` |
 | `STATIC_SECURITY_CSP` | `security.csp` |

USER_GUIDE.md

@@ -117,11 +117,13 @@ read_timeout        = "10s"      # full read deadline (covers headers; Slowloris
 write_timeout       = "10s"
 idle_timeout        = "75s"
 shutdown_timeout    = "15s"      # graceful drain window on SIGTERM/SIGINT
+# max_conns_per_ip  = 0          # max concurrent connections per IP (0 = unlimited)
 
 [files]
 root      = "./public"           # directory to serve
 index     = "index.html"         # index file for directory requests (e.g. GET /)
 not_found = "404.html"           # custom 404 page, relative to root (optional)
+# max_serve_file_size = 1073741824  # files > 1 GB get 413 (0 = no limit)
 
 [cache]
 enabled       = true
@@ -136,6 +138,7 @@ enabled       = true
 min_size      = 1024             # don't compress responses smaller than 1 KB
 level         = 5                # gzip level 1 (fastest) – 9 (best)
 precompressed = true             # serve .gz / .br / .zst sidecar files when available
+# max_compress_size = 10485760   # skip on-the-fly gzip for bodies > 10 MB (0 = no limit)
 
 [headers]
 immutable_pattern = ""           # glob for fingerprinted assets → Cache-Control: immutable
@@ -169,9 +172,11 @@ Every config field can also be set via an environment variable, which takes prec
 | `STATIC_SERVER_WRITE_TIMEOUT`       | `server.write_timeout`                           |
 | `STATIC_SERVER_IDLE_TIMEOUT`        | `server.idle_timeout`                            |
 | `STATIC_SERVER_SHUTDOWN_TIMEOUT`    | `server.shutdown_timeout`                        |
+| `STATIC_SERVER_MAX_CONNS_PER_IP`   | `server.max_conns_per_ip`                        |
 | `STATIC_FILES_ROOT`                 | `files.root`                                     |
 | `STATIC_FILES_INDEX`                | `files.index`                                    |
 | `STATIC_FILES_NOT_FOUND`            | `files.not_found`                                |
+| `STATIC_FILES_MAX_SERVE_FILE_SIZE`  | `files.max_serve_file_size`                      |
 | `STATIC_CACHE_ENABLED`              | `cache.enabled`                                  |
 | `STATIC_CACHE_PRELOAD`              | `cache.preload`                                  |
 | `STATIC_CACHE_MAX_BYTES`            | `cache.max_bytes`                                |
@@ -181,6 +186,7 @@ Every config field can also be set via an environment variable, which takes prec
 | `STATIC_COMPRESSION_ENABLED`        | `compression.enabled`                            |
 | `STATIC_COMPRESSION_MIN_SIZE`       | `compression.min_size`                           |
 | `STATIC_COMPRESSION_LEVEL`          | `compression.level`                              |
+| `STATIC_COMPRESSION_MAX_COMPRESS_SIZE` | `compression.max_compress_size`               |
 | `STATIC_HEADERS_ENABLE_ETAGS`       | `headers.enable_etags`                           |
 | `STATIC_SECURITY_BLOCK_DOTFILES`    | `security.block_dotfiles`                        |
 | `STATIC_SECURITY_CSP`               | `security.csp`                                   |
@@ -644,10 +650,11 @@ STATIC_CACHE_PRELOAD=true STATIC_CACHE_GC_PERCENT=400 ./bin/static-web
 ### What preloading does
 
 1. At startup, walks every file under `files.root`.
-2. Files smaller than `max_file_size` are read into the LRU cache.
-3. Pre-formatted `Content-Type` and `Content-Length` response headers are computed once per file.
-4. The path-safety cache (`sync.Map`) is pre-warmed — the first request for any preloaded file skips `filepath.EvalSymlinks`.
-5. Preload statistics (file count, total bytes, duration) are logged at startup.
+2. Symlink targets are validated — symlinks pointing outside root are skipped.
+3. Files smaller than `max_file_size` are read into the LRU cache.
+4. Pre-formatted `Content-Type` and `Content-Length` response headers are computed once per file.
+5. The path-safety cache (bounded LRU) is pre-warmed — the first request for any preloaded file skips `filepath.EvalSymlinks`.
+6. Preload statistics (file count, total bytes, duration) are logged at startup.
 
 ### When to use preload
 
@@ -783,6 +790,17 @@ The most common causes:
 
 The server only accepts `GET`, `HEAD`, and `OPTIONS`. Any other method (POST, PUT, DELETE, PATCH, TRACE, etc.) is rejected with `405`. This is intentional — it's a static file server, not an API. If your browser is sending a `POST` request, check your HTML form actions and JavaScript fetch calls.
 
+### `413 Payload Too Large`
+
+A file exceeds the `max_serve_file_size` limit (default 1 GB). Increase the limit in config:
+
+```toml
+[files]
+max_serve_file_size = 2147483648   # 2 GB
+```
+
+Or set to 0 to disable the limit entirely. This also applies via the `STATIC_FILES_MAX_SERVE_FILE_SIZE` environment variable.
+
 ### Files are stale after a deploy
 
 The in-memory cache serves files from memory after the first request (or immediately if `preload = true`). After deploying new files to disk, flush both the file cache and the path-safety cache:

config.toml.example

@@ -32,6 +32,11 @@ idle_timeout = "75s"
 # How long to wait for in-flight requests to complete during graceful shutdown.
 shutdown_timeout = "15s"
 
+# Maximum concurrent connections allowed from a single IP address.
+# 0 means unlimited (default). Set to a positive value (e.g. 100) to limit
+# per-IP connection count and mitigate connection exhaustion attacks.
+# max_conns_per_ip = 0
+
 [files]
 # Directory to serve files from.
 root = "./public"
@@ -42,6 +47,10 @@ index = "index.html"
 # Custom 404 page path, relative to root. Leave empty for the built-in 404.
 not_found = "404.html"
 
+# Maximum file size (bytes) that will be served. Files exceeding this limit
+# receive a 413 Payload Too Large response. Default: 1 GB. Set to 0 to disable.
+# max_serve_file_size = 1073741824
+
 [cache]
 # Enable or disable the in-memory LRU file cache.
 enabled = true
@@ -69,6 +78,11 @@ level = 5
 # Encoding priority: br > zstd > gzip
 precompressed = true
 
+# Maximum response body size (bytes) eligible for on-the-fly compression.
+# Responses larger than this are sent uncompressed to avoid excessive memory use.
+# Default: 10 MB (10485760). Set to 0 to disable the limit.
+# max_compress_size = 10485760
+
 [headers]
 # Glob pattern for fingerprinted/immutable assets (gets "Cache-Control: immutable").
 # Example: "**-[0-9a-f]*.{js,css}"