docs: actualize guides after 0.1.6/0.1.7 — security warnings on flags, GraphQL defaults, gRPC RPC cap, static-response cache, credential-compare note

Author: Berik Ashimov

docs/guide/feature-flags.md

@@ -20,7 +20,10 @@ async def checkout(flags: Flags = Depends(get_flags)):
     return {"flow": "v1"}
 ```
 
-`get_flags` automatically builds an `EvalContext` from the incoming request headers (`x-user-id`, `x-tenant-id`) and returns a `Flags` instance backed by `app.flags`.
+`get_flags` returns a `Flags` instance backed by `app.flags` with an `EvalContext` that exposes the raw request headers via `ctx.headers`. **It does not infer identity from headers** — `ctx.user_id` and `ctx.tenant_id` are always `None`. Identity must come from an authenticated dependency that *you* wire in (see [EvalContext](#evalcontext)).
+
+!!! warning "Why identity isn't lifted from headers (CWE-290)"
+    Previous releases (< 0.1.6) read `X-User-Id` / `X-Tenant-Id` request headers straight into `ctx.user_id` / `ctx.tenant_id`. That trusted attacker-controlled input as the targeting identity — any client could claim any user / tenant by setting the header and bypass flag gates on admin previews, beta features, or pricing experiments. 0.1.6 removed that read; the headers are still on `ctx.headers` for non-identity targeting (region, A/B variant, locale).
 
 ---
 
@@ -126,7 +129,31 @@ ctx = EvalContext(
 )
 ```
 
-`get_flags` auto-populates `user_id` and `tenant_id` from `x-user-id` / `x-tenant-id` request headers. Custom providers can use these fields to implement percentage rollouts, user allowlists, and tenant overrides.
+`get_flags` always returns an `EvalContext` with `user_id=None` / `tenant_id=None` — see the warning in [Quick start](#quick-start). Build a richer context from an authenticated dependency yourself:
+
+```python
+from hawkapi import Depends
+from hawkapi.flags import EvalContext, Flags, get_flags
+
+async def authed_flags(
+    flags: Flags = Depends(get_flags),
+    user = Depends(current_user),  # your own auth dependency
+) -> Flags:
+    return Flags(
+        flags._provider,  # type: ignore[attr-defined]
+        EvalContext(
+            user_id=user.id,
+            tenant_id=user.tenant_id,
+            attrs={"plan": user.plan},
+        ),
+    )
+
+@app.get("/checkout")
+async def checkout(flags: Flags = Depends(authed_flags)) -> dict:
+    ...
+```
+
+Custom providers can use these fields to implement percentage rollouts, user allowlists, and tenant overrides — once identity is derived from a trusted source.
 
 ---
 

docs/guide/graphql.md

@@ -127,16 +127,45 @@ The base context always contains:
 ## GraphiQL toggle
 
 The interactive GraphiQL UI is served on `GET /graphql` when a browser `Accept`
-header prefers `text/html`:
+header prefers `text/html`. **Disabled by default** since 0.1.6 — opt in for
+development environments only:
 
 ```python
-# Enabled by default
+# Default — UI is OFF, GET on /graphql returns 404 for browsers
+app.mount_graphql("/graphql", executor=executor)
+
+# Enable explicitly for local development
 app.mount_graphql("/graphql", executor=executor, graphiql=True)
+```
+
+The bundled HTML pins exact CDN versions of React + GraphiQL and includes
+`integrity=` SRI hashes on every `<script>` / `<link>` so a compromised CDN
+cannot inject arbitrary JS.
+
+## Depth and timeout limits
+
+Every mounted endpoint enforces two DoS-protection budgets out of the box
+(since 0.1.6):
+
+| Argument    | Default | Disable        | What it caps                              |
+|-------------|--------:|----------------|-------------------------------------------|
+| `max_depth` |    `15` | `None`         | Maximum brace-nesting depth of the query  |
+| `timeout_s` |  `30.0` | `None`         | Wall-clock budget for `await executor(...)` |
 
-# Disable for production APIs that don't need the explorer
-app.mount_graphql("/graphql", executor=executor, graphiql=False)
+Override per mount:
+
+```python
+app.mount_graphql(
+    "/graphql",
+    executor=executor,
+    max_depth=8,       # tighter cap for an unauthenticated endpoint
+    timeout_s=5.0,     # tight tail-latency budget
+)
 ```
 
+Queries that exceed `max_depth` are rejected with HTTP **400** before the
+executor is invoked. Queries that exceed `timeout_s` return HTTP **504**.
+
 ## Disabling GET queries
 
 Restrict the endpoint to POST-only:
@@ -147,6 +176,13 @@ app.mount_graphql("/graphql", executor=executor, allow_get=False)
 
 GET requests will receive HTTP **405** when `allow_get=False`.
 
+## GET-vs-mutation guard (CWE-352)
+
+Multi-operation documents are now parsed before the GET-method check. A
+document containing both a query and a mutation with `?operationName=B`
+selecting the mutation is rejected over GET — closes the CSRF vector that
+allowed image tags / cache-poisoning to trigger writes.
+
 ## Roadmap
 
 - Multipart request support (file uploads per the GraphQL multipart spec)

docs/guide/grpc.md

@@ -170,6 +170,22 @@ app.mount_grpc(
 )
 ```
 
+## Concurrent-RPC cap
+
+Since 0.1.6 every server starts with `maximum_concurrent_rpcs=1000` — a single
+peer cannot open enough RPCs to exhaust the event loop or FD table. HTTP-side
+rate-limit / bulkhead middleware does **not** apply to the gRPC port, so this
+in-band cap is the only protection layer for the gRPC transport.
+
+```python
+app.mount_grpc(
+    MyGreeter(),
+    add_to_server=add_GreeterServicer_to_server,
+    maximum_concurrent_rpcs=500,   # tighter than default for a public endpoint
+    # maximum_concurrent_rpcs=None # opt out (previous behaviour)
+)
+```
+
 ## Multiple services on one port
 
 Call `mount_grpc` twice with the **same port** — servicers are merged onto one

docs/guide/performance.md

@@ -6,7 +6,61 @@ languages. For latency-sensitive deployments you can squeeze additional
 throughput by compiling HawkAPI's hot Python modules with
 [mypyc](https://mypyc.readthedocs.io/).
 
-## When to enable mypyc
+## Automatic fast paths
+
+Two dispatcher fast paths trigger at route-registration time — no opt-in flag,
+no runtime overhead, no behavioural difference.
+
+### Static-response cache (Wave 4, since 0.1.7)
+
+Handlers whose body is exactly `return SomeResponse(literal_args)` with no
+parameters have their two ASGI messages (`http.response.start` +
+`http.response.body`) built **once** at registration time and re-emitted on
+every request. No handler call, no Response allocation, no header construction
+per request.
+
+```python
+@app.get("/plaintext")
+async def plaintext() -> PlainTextResponse:
+    return PlainTextResponse("Hello, World!")
+
+@app.get("/health")
+async def health() -> JSONResponse:
+    return JSONResponse({"status": "ok"})
+```
+
+Local micro-benchmark on Darwin / Python 3.13: plaintext handler at
+**0.89 µs / request (1.1 M req/s on ASGI directly)** vs the previous
+trivial-path 6.76 µs / request — a 7.5× speedup for static endpoints.
+
+Eligible handlers:
+
+- No parameters of any kind (no `Request`, no `Depends`, no path/query)
+- Async function (sync handlers fall through to the regular path)
+- Single `return` statement (an optional docstring is allowed)
+- Return value is a `Call` to `Response`, `PlainTextResponse`, `JSONResponse`,
+  or `HTMLResponse` by bare name
+- Every positional and keyword argument is a literal (`Constant`, list,
+  tuple, set, dict of literals, or unary +/− of a numeric constant)
+
+Anything else falls through to the trivial / general path. No regression on
+dynamic handlers.
+
+### Trivial-route fast path (Wave 3, since 0.1.4)
+
+When the static-response cache does not apply but the route has no DI, no
+`Depends(...)`, no permissions, no background tasks, no `response_model`, no
+deprecation headers, and no per-route middleware, the dispatcher takes a
+slimmer execution path that skips the DI scope, cleanup stack, and exception
+classifier branches. Path / query params are still coerced via `_coerce_fast`
+(since 0.1.5).
+
+The eligibility flag is computed once at registration; the per-request branch
+is a single boolean check.
+
+## Manual fast paths
+
+### When to enable mypyc
 
 Enable mypyc when:
 
@@ -26,7 +80,7 @@ Skip mypyc when:
 The default `pip install hawkapi` always installs the pure-Python wheel; mypyc
 compilation is strictly opt-in.
 
-## Installing the mypyc-compiled build
+### Installing the mypyc-compiled build
 
 The build is gated by the `HAWKAPI_BUILD_MYPYC` environment variable.
 
@@ -59,7 +113,7 @@ python -c "import hawkapi.routing._radix_tree; print(hawkapi.routing._radix_tree
 Pre-built mypyc wheels for common platforms may be published in a future
 release; until then, building from source is required.
 
-## What gets compiled
+### What gets compiled
 
 The build hook compiles only the request-routing hot path. Response classes are
 intentionally left interpreted because user code (and the bundled
@@ -74,7 +128,7 @@ ones.
 | `hawkapi.routing.param_converters` | Path parameter coercion. |
 | `hawkapi.middleware._pipeline` | Middleware chain assembly at startup. |
 
-## Expected gains
+### Expected gains
 
 The dominant per-request cost in HawkAPI is already in C (granian, msgspec). On
 the bundled competitive benchmark suite (`benchmarks/competitive/runner.py`)
@@ -94,7 +148,7 @@ HAWKAPI_BUILD_MYPYC=1 uv pip install . --reinstall --no-build-isolation
 uv run python benchmarks/competitive/runner.py --framework hawkapi --duration 8
 ```
 
-## Caveats
+### Caveats
 
 - **PyPy is unsupported.** mypyc emits CPython C extensions; PyPy users get the
   pure-Python build automatically.

docs/guide/security.md

@@ -2,6 +2,30 @@
 
 HawkAPI provides authentication schemes that integrate with OpenAPI.
 
+!!! warning "Comparing credentials safely"
+    All built-in schemes (`HTTPBasic`, `HTTPBearer`, `APIKey*`,
+    `OAuth2PasswordBearer`) only *extract* credentials from the request.
+    Comparing the extracted value against your stored secret is **your**
+    responsibility. Always use a constant-time helper:
+
+    ```python
+    import secrets
+
+    if not secrets.compare_digest(creds.password, stored_hash):
+        raise HTTPException(401, detail="Invalid credentials")
+    ```
+
+    A plain `==` comparison leaks timing information and lets an attacker
+    discover the secret one byte at a time.
+
+For threat-model, OWASP API Top 10 compliance map, and responsible-disclosure
+policy see:
+
+- [`SECURITY.md`](https://github.com/ashimov/HawkAPI/blob/main/SECURITY.md) — disclosure policy
+- [`docs/security/threat-model.md`](../security/threat-model.md) — STRIDE per subsystem
+- [`docs/security/owasp-api-top10-2023.md`](../security/owasp-api-top10-2023.md) — compliance map
+- `hawkapi doctor app:app` — lint 18 production-readiness rules
+
 ## HTTP Bearer
 
 ```python