Security hardening (v0.2.0)

- CSRF middleware now verifies the submitted token HMAC signature (CWE-352)
- HTML-escape OpenAPI UI title and JSON-encode URL in JS context; pin CDN asset versions (CWE-79)
- DebugMiddleware defaults to enabled=False (CWE-489)
- TrustedProxyMiddleware whitelists X-Forwarded-Proto to http/https
- StructuredLoggingMiddleware sanitizes client request IDs (CWE-117)
- parse_multipart enforces a max_parts limit (CWE-770)
- SecurityHeadersMiddleware sets HSTS by default
- Scaffold no longer ships allow_origins=["*"]

Author: Berik Ashimov

.gitignore

@@ -34,5 +34,5 @@ coverage.xml
 site/
 .remember/
 
-# Local Claude worktrees / state
+# Local tooling worktrees / state
 .claude/

CHANGELOG.md

@@ -4,6 +4,25 @@ The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/
 
 ## [Unreleased]
 
+## 0.2.0 — 2026-06-10
+
+Security hardening.
+
+### Security
+
+- CSRF middleware now verifies the HMAC signature of the submitted token before the constant-time comparison against the cookie value. The signature was never checked before, leaving the secret unused and protection degraded to a naive double-submit cookie (CWE-352).
+- OpenAPI UI templates (Swagger UI, Scalar, ReDoc) HTML-escape the title and JSON-encode the OpenAPI URL in JS contexts; CDN assets pinned to exact versions (`swagger-ui-dist@5.17.14`, `@scalar/api-reference@1.25.28`, `redoc@2.1.5`) instead of floating `@5` / `@latest` tags (CWE-79).
+- `DebugMiddleware` now defaults to `enabled=False` (was `True`); the route map and request stats are no longer exposed by default (CWE-489).
+- `TrustedProxyMiddleware` only rewrites the scheme for `X-Forwarded-Proto` values of `http` or `https`; any other value leaves the existing scheme untouched.
+- `StructuredLoggingMiddleware` validates client-supplied request IDs (length ≤ 128, ASCII, no control characters) before logging, falling back to a generated UUID otherwise (log injection — CWE-117).
+- `parse_multipart` enforces a `max_parts` limit (default 1000), raising `ValueError` on bodies with more parts, to prevent part-flooding denial of service (CWE-770).
+- `SecurityHeadersMiddleware` sets HSTS by default (`max-age=31536000; includeSubDomains`); pass `hsts=None` to disable for local HTTP development.
+- `ErrorHandlerMiddleware` documents that `debug=True` leaks tracebacks and must never be enabled in production; the default remains `False`.
+
+### Changed
+
+- Project scaffold no longer ships `CORSMiddleware` with `allow_origins=["*"]`; it emits a placeholder origin and a `TODO` instructing operators to set real origins before production.
+
 ## [0.1.7] - 2026-05-16
 
 Static-response cache. Plaintext throughput jumped from #2 to #1 in the competitive suite, and we lead all six scenarios on both throughput and p99 latency now.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hawkapi"
-version = "0.1.7"
+version = "0.2.0"
 description = "High-performance Python web framework — faster alternative to FastAPI"
 readme = "README.md"
 license = { file = "LICENSE" }

src/hawkapi/_scaffold/templates.py

@@ -53,8 +53,9 @@ async def get_greeting_service() -> GreetingService:
 
 app = HawkAPI(title="{name}", container=container)
 
-# CORSMiddleware: allows cross-origin requests from any origin.
-app.add_middleware(CORSMiddleware, allow_origins=["*"])
+# CORSMiddleware: restrict cross-origin requests to known origins.
+# TODO: set real origins before production. Never ship allow_origins=["*"].
+app.add_middleware(CORSMiddleware, allow_origins=["https://example.com"])
 
 # RequestIDMiddleware: assigns a unique ID to every request (useful for tracing).
 app.add_middleware(RequestIDMiddleware)

src/hawkapi/middleware/csrf.py

@@ -218,6 +218,15 @@ async def replay_receive() -> dict[str, Any]:
             await response(scope, receive, send)
             return
 
+        # Verify the HMAC signature of the submitted token before (and in
+        # addition to) the constant-time comparison against the cookie value.
+        # Without this, the secret is unused and protection degrades to a naive
+        # double-submit cookie.
+        if not self._verify_token(submitted_token):
+            response = self._forbidden_response("CSRF token signature invalid.")
+            await response(scope, receive, send)
+            return
+
         if not hmac.compare_digest(submitted_token, cookie_token):
             response = self._forbidden_response("CSRF token mismatch.")
             await response(scope, receive, send)

src/hawkapi/middleware/debug.py

@@ -25,7 +25,7 @@ def __init__(
         app: ASGIApp,
         *,
         prefix: str = "/_debug",
-        enabled: bool = True,
+        enabled: bool = False,
     ) -> None:
         super().__init__(app)
         self._prefix = prefix

src/hawkapi/middleware/error_handler.py

@@ -18,6 +18,13 @@ class ErrorHandlerMiddleware(Middleware):
     """Catch exceptions and return structured error responses."""
 
     def __init__(self, app: ASGIApp, *, debug: bool = False) -> None:
+        """Initialize the error handler.
+
+        WARNING: ``debug=True`` returns the full exception traceback in the
+        HTTP response body. This leaks source paths, code, and internal state.
+        It is a development-only aid and MUST NEVER be enabled in production.
+        The default is ``False``.
+        """
         super().__init__(app)
         self.debug = debug
 

src/hawkapi/middleware/security_headers.py

@@ -15,7 +15,9 @@ class SecurityHeadersMiddleware(Middleware):
     - X-Content-Type-Options: nosniff
     - X-Frame-Options: DENY
     - X-XSS-Protection: 1; mode=block
-    - Strict-Transport-Security (via ``hsts`` param, off by default)
+    - Strict-Transport-Security (via ``hsts`` param; defaults to one year with
+      ``includeSubDomains``). Pass ``hsts=None`` to disable it — necessary for
+      local HTTP development, since browsers will otherwise force HTTPS.
     - Referrer-Policy: strict-origin-when-cross-origin
     - Permissions-Policy (via ``permissions_policy`` param)
     - Content-Security-Policy (via ``content_security_policy`` param)
@@ -28,7 +30,7 @@ def __init__(
         content_type_options: str = "nosniff",
         frame_options: str = "DENY",
         xss_protection: str = "1; mode=block",
-        hsts: str | None = None,
+        hsts: str | None = "max-age=31536000; includeSubDomains",
         referrer_policy: str = "strict-origin-when-cross-origin",
         permissions_policy: str | None = None,
         content_security_policy: str | None = None,

src/hawkapi/middleware/structured_logging.py

@@ -63,7 +63,14 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
             if key == self._request_id_header:
                 request_id = value.decode("latin-1")
                 break
-        if request_id is None:
+        # Reject overly long, injection-prone, or non-printable request IDs
+        # (mirrors RequestIDMiddleware) to avoid log injection.
+        if (
+            request_id is None
+            or len(request_id) > 128
+            or not request_id.isascii()
+            or any(ord(c) < 0x20 for c in request_id)
+        ):
             request_id = str(uuid.uuid4())
 
         start = time.monotonic()

src/hawkapi/middleware/trusted_proxy.py

@@ -90,9 +90,12 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
             if real_ip is not None:
                 new_scope["client"] = (real_ip, 0)
 
-        # Rewrite scheme from X-Forwarded-Proto
+        # Rewrite scheme from X-Forwarded-Proto (only accept known schemes;
+        # otherwise leave the existing scheme untouched)
         if forwarded_proto:
-            new_scope["scheme"] = forwarded_proto.strip().lower()
+            proto = forwarded_proto.strip().lower()
+            if proto in ("http", "https"):
+                new_scope["scheme"] = proto
 
         # Rewrite host header from X-Forwarded-Host
         if forwarded_host: