chore: capture post-P0/P1 state for clean P2 start (working tree was dirty at task begin)

README.md

@@ -98,6 +98,10 @@ SteamCache2 uses a YAML configuration file (`config.yaml`) for all settings. Her
 # Server configuration
 listen_address: :80
 
+# P1 hardening (see Security Hardening section)
+max_object_size: "0"   # 0=unlimited; set e.g. "256MB" for response size DoS protection
+trusted_proxies: []    # empty = safe (ignore XFF for rate limit); set CIDRs for trusted proxies
+
 # Cache configuration
 cache:
   # Memory cache settings
@@ -121,6 +125,31 @@ cache:
 upstream: "https://steam.cdn.com"
 ```
 
+#### Startup Validation
+As of P0, `steamcache2` performs strict validation on startup (after loading config + CLI overrides, before creating the cache). Invalid configs cause immediate clean failure (no default written, no panic):
+
+- Negative `max_concurrent_requests` / `max_requests_per_client`: "negative concurrency not allowed"
+- Invalid `gc_algorithm` (memory): "invalid memory gc algorithm: badvalue"
+- Disk enabled (`size` non-zero/"") but no `path`: "disk cache enabled but no path specified"
+- Invalid memory/disk `size` strings (via direct New): "invalid memory size: ..." / "invalid disk size: ..." (clean error return, no panic)
+
+Example error on stderr + logs:
+```
+Error: Invalid configuration: invalid memory gc algorithm: foo. Please fix the config file and try again.
+```
+
+See `config.Validate()` and `steamcache.New` error paths. This ensures the LAN appliance fails fast on misconfig.
+
+#### Security Hardening (P1)
+- `max_object_size` (default "0" = unlimited): set e.g. "256MB" or "512MB" to reject oversized upstream responses with HTTP 413 before buffering/ReadAll. Prevents OOM DoS from large or malicious responses (P1-01). Large legitimate Steam files still served if under limit.
+- `trusted_proxies`: CIDR list (default empty). When empty (safe default), X-Forwarded-For and client IP spoofing are ignored for rate limiting — always uses `r.RemoteAddr` only. When set (e.g. your reverse proxy CIDR), uses correct "rightmost untrusted" extraction. Prevents bypass of `max_requests_per_client` (P1-02). Documented for LAN proxy setups only.
+- These + P0 validation make steamcache2 safe-by-default for LAN exposure.
+
+#### Migration / Breaking Changes (P1)
+- `New()` public signature gained 2 required trailing params (`maxObjectSize`, `trustedProxies`). Direct callers (rare; most use config or NewWithOptions) must update.
+- Recommended: migrate to `NewWithOptions(Options{...})` (non-breaking) or rely on YAML config + cmd/root.go.
+- No behavior change for existing configs (defaults preserve prior semantics).
+
 #### Garbage Collection Algorithms
 
 SteamCache2 supports different garbage collection algorithms for memory and disk caches, allowing you to optimize performance for each storage tier:
@@ -128,11 +157,11 @@ SteamCache2 supports different garbage collection algorithms for memory and disk
 **Available GC Algorithms:**
 
 - **`lru`** (default): Least Recently Used - evicts oldest accessed files
-- **`lfu`**: Least Frequently Used - evicts least accessed files (good for popular content)
+- **`lfu`**: Least Frequently Used (P1 real impl) - evicts by lowest AccessCount (tiebreak older ATime); uses existing FileInfo counters
 - **`fifo`**: First In, First Out - evicts oldest created files (predictable)
 - **`largest`**: Size-based - evicts largest files first (maximizes file count)
 - **`smallest`**: Size-based - evicts smallest files first (maximizes cache hit rate)
-- **`hybrid`**: Combines access time and file size for optimal eviction
+- **`hybrid`**: Recency + frequency hybrid (P1 meaningful) - evicts by lowest time-decayed score (GetTimeDecayedScore combining ATime + AccessCount)
 
 **Recommended Algorithms by Cache Type:**