Add public middleware with basic rate limiting and timestamp checks

docs/middleware/public_middleware.md

@@ -0,0 +1,25 @@
+# Public middleware
+
+The `PublicMiddleware` protects openly accessible endpoints with
+lightweight in-memory defenses. It is defined in
+`pkg/middleware/public_middleware.go` and provides:
+
+- **Rate limiting** – `limiter.MemoryLimiter` caps requests per client
+  IP within a sliding window.
+- **Timestamp validation** – `ValidTimestamp` ensures the
+  `X-API-Timestamp` header is within an allowed skew (5 minutes by
+default).
+- **Replay protection** – a `cache.TTLCache` tracks used request IDs and
+  rejects duplicates using a composite key of
+  `limiterKey|requestID|ip` (rate limiter key, request ID and client IP).
+- **Dependency checks** – missing caches or limiters are logged and cause
+  a generic 500 Internal Server Error.
+
+### Required headers
+
+- `X-Request-ID`
+- `X-API-Timestamp`
+
+Requests lacking these headers, using an unparsable client IP, or failing
+validation are rejected with an authentication error. Valid requests pass
+through to the next handler.

docs/middleware/token_analysis_v2.md → docs/middleware/token_middleware.md

@@ -1,7 +1,8 @@
-# Token middleware analysis (v2)
+# Token middleware
 
-Date: 2025-08-11
-Scope: pkg/middleware/token_middleware.go and related helpers (valid_timestamp.go, pkg/portal/support.go)
+This document describes the TokenCheckMiddleware found in
+`pkg/middleware/token_middleware.go` and its supporting helpers such as
+`valid_timestamp.go` and `pkg/portal/support.go`.
 
 ---
 
@@ -24,7 +25,10 @@ Main steps:
    - X-API-Nonce (unique per request)
 
 2) Dependency guard
-   - Ensures ApiKeys repo, TokenHandler, nonce cache, and rate limiter exist. If missing, fails with 401.
+   - Ensures ApiKeys repo, TokenHandler, nonce cache, and rate limiter
+     exist. If any dependency is missing the middleware now logs the
+     configuration error and returns a generic 500 Internal Server
+     Error.
 
 3) Header validation
    - Rejects if any required header is missing (401: "Invalid authentication headers").