docs: reflect v0.2.0 CSRF signed double-submit behavior

The CSRF middleware now verifies the submitted token's HMAC signature
against the secret before the constant-time comparison with the cookie
value. Update the README and middleware/security guides so the described
behavior matches the shipped implementation.

Co-Authored-By: Claude Fable 5 <[email protected]>

Author: 2 people

README.md

@@ -347,7 +347,7 @@ class AuthMiddleware(Middleware):
 | `CircuitBreakerMiddleware` | Three-state circuit breaker (per-path tracking) |
 | `RedisCircuitBreakerMiddleware` | Distributed circuit breaker (Redis-backed) |
 | `AdaptiveConcurrencyMiddleware` | Adaptive in-flight limit based on latency |
-| `CSRFMiddleware` | Double-submit cookie CSRF protection |
+| `CSRFMiddleware` | Signed double-submit cookie CSRF protection |
 | `SessionMiddleware` | Signed cookie-based session management |
 | `ErrorHandlerMiddleware` | Structured error handling pipeline |
 | `PrometheusMiddleware` | Prometheus-compatible `/metrics` endpoint |
@@ -771,7 +771,7 @@ Rejects oversized requests at the ASGI scope level before body parsing. Returns
 
 ### CSRF Protection
 
-Double-submit cookie CSRF protection. Safe methods (GET, HEAD, OPTIONS) pass through and receive a signed CSRF token cookie. Unsafe methods require the token in an `X-CSRF-Token` header or `csrf_token` form field:
+Signed double-submit cookie CSRF protection. Safe methods (GET, HEAD, OPTIONS) pass through and receive a signed CSRF token cookie. Unsafe methods require the token in an `X-CSRF-Token` header or `csrf_token` form field:
 
 ```python
 from hawkapi.middleware.csrf import CSRFMiddleware
@@ -786,7 +786,7 @@ app.add_middleware(
 )
 ```
 
-Returns 403 with `application/problem+json` when the token is missing or mismatched. Tokens are HMAC-SHA256 signed and verified with `hmac.compare_digest` for timing safety.
+Returns 403 with `application/problem+json` when the token is missing, its signature is invalid, or it does not match the cookie. Tokens are HMAC-SHA256 signed; the submitted token's signature is verified against the secret before a constant-time `hmac.compare_digest` comparison against the cookie value.
 
 ### Session Middleware
 

docs/guide/middleware.md

@@ -48,7 +48,7 @@ app.add_middleware(TimingMiddleware)
 
 | Middleware | Description | Extra |
 |-----------|-------------|-------|
-| `CSRFMiddleware` | CSRF protection (double-submit cookie) | — |
+| `CSRFMiddleware` | CSRF protection (signed double-submit cookie) | — |
 | `SessionMiddleware` | Signed cookie-based sessions | — |
 | `RedisRateLimitMiddleware` | Redis-backed rate limiting | `redis` |
 | `CORSMiddleware` | Cross-Origin Resource Sharing | — |
@@ -151,7 +151,7 @@ app.add_middleware(PrometheusMiddleware)
 
 ## CSRF Middleware
 
-HawkAPI includes CSRF protection using the **double-submit cookie** pattern. A CSRF token is set in a cookie on safe requests (GET, HEAD, OPTIONS) and must be echoed back via a header or form field on unsafe requests (POST, PUT, DELETE, PATCH).
+HawkAPI includes CSRF protection using the **signed double-submit cookie** pattern. A CSRF token is set in a cookie on safe requests (GET, HEAD, OPTIONS) and must be echoed back via a header or form field on unsafe requests (POST, PUT, DELETE, PATCH).
 
 ```python
 from hawkapi.middleware.csrf import CSRFMiddleware
@@ -162,7 +162,7 @@ app.add_middleware(
 )
 ```
 
-On safe requests, the middleware sets a `csrftoken` cookie automatically. On unsafe requests, the client must send the token back via the `X-CSRF-Token` header or a `csrf_token` form field. If the token is missing or does not match, a 403 response is returned.
+On safe requests, the middleware sets a `csrftoken` cookie automatically. The token is an HMAC-SHA256-signed value (`<random>.<signature>`). On unsafe requests, the client must send the token back via the `X-CSRF-Token` header or a `csrf_token` form field. The submitted token's HMAC signature is verified against the configured `secret` before a constant-time comparison against the cookie value, so a forged token without a valid signature is rejected. If the token is missing, its signature is invalid, or it does not match the cookie, a 403 response is returned.
 
 | Option | Default | Description |
 |--------|---------|-------------|

docs/guide/security.md

@@ -80,4 +80,4 @@ API keys can also be read from query parameters (`APIKeyQuery`) or cookies (`API
 
 ## CSRF Protection
 
-HawkAPI includes built-in CSRF protection via `CSRFMiddleware`, which implements the double-submit cookie pattern. See the [Middleware guide](middleware.md#csrf-middleware) for configuration options and usage examples.
+HawkAPI includes built-in CSRF protection via `CSRFMiddleware`, which implements a signed double-submit cookie pattern: the token carries an HMAC-SHA256 signature that is verified against the configured `secret` before the constant-time comparison against the cookie value. See the [Middleware guide](middleware.md#csrf-middleware) for configuration options and usage examples.