Merge TASK-074: gate DEBUG raw-body printing behind explicit opt-in

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: etr

docs/debug-env-vars.md

@@ -0,0 +1,89 @@
+# Debug-only environment variables
+
+This document inventories environment variables that the libhttpserver
+runtime reads. **None of these are meant to be set in production.**
+All are silent unless explicitly enabled; the library emits a one-shot
+`SECURITY WARNING` to stderr (and to the user's `log_error` callback,
+when wired) the first time `webserver::start()` observes a set
+variable.
+
+---
+
+## `LIBHTTPSERVER_DEBUG_DUMP_REQUEST_BODY`
+
+| Field | Value |
+| --- | --- |
+| Introduced | TASK-074 (June 2026) |
+| Replaces | The prior compile-time `#ifdef DEBUG` guard in `src/detail/webserver_body_pipeline.cpp` |
+| Read by | `httpserver::detail::debug_dump_request_body_opted_in()` (cached in a function-local static) |
+| Independent of | Compile-time `DEBUG` / `NDEBUG`. The runtime check is the only gate. |
+
+### Effect
+
+When set to any non-empty, non-`"0"` value, every inbound request body
+chunk is written verbatim to `stdout`, prefixed by `Writing content: `,
+from the body pipeline in `src/detail/webserver_body_pipeline.cpp`.
+
+### Risk
+
+Raw request bodies routinely contain:
+- Basic-auth credentials (when sent in the body rather than the header),
+- form-posted passwords (`application/x-www-form-urlencoded` with a
+  `password=` field),
+- session cookies,
+- CSRF tokens,
+- PII (email addresses, names, IDs, addresses).
+
+The `http_request::operator<<` redaction policy introduced in TASK-057
+does **not** cover this code path -- bytes are written verbatim. Treat
+any process where this variable is set as a credential-leaking
+surface (CWE-532: Insertion of Sensitive Information into Log File).
+
+### Startup signal
+
+The library emits a single `SECURITY WARNING` line to stderr at the
+first `webserver::start()` call after the variable is observed. The
+exact line is:
+
+```
+[libhttpserver] SECURITY WARNING: LIBHTTPSERVER_DEBUG_DUMP_REQUEST_BODY is set. Raw request bodies will be written to stdout, including credentials, session cookies, and PII. Unset the variable for production deployments. See docs/debug-env-vars.md.
+```
+
+The same line is forwarded to the owning webserver's `log_error`
+callback when one is wired via `create_webserver().log_error(...)`. The
+forwarding is best-effort: an exception from the callback is swallowed
+so a misconfigured logger cannot abort daemon startup.
+
+Multiple `webserver` instances constructed in the same process share a
+process-wide print-once flag, so the warning is emitted exactly once
+per process.
+
+### How to disable
+
+```sh
+unset LIBHTTPSERVER_DEBUG_DUMP_REQUEST_BODY
+```
+
+then restart the process. The value is cached in a function-local
+static on first request, so a mid-process `unsetenv()` has no effect.
+
+### Spot-check: release build with `-DDEBUG` accidentally set
+
+The runtime check is the only gate; the env var must be explicitly set
+for the dump to fire, regardless of the compile-time `DEBUG` /
+`NDEBUG` posture. A release binary built with `-DDEBUG` accidentally
+defined therefore still does not leak credentials/PII unless the
+operator opted in.
+
+---
+
+## Adding new debug env vars
+
+When introducing a new `LIBHTTPSERVER_*` debug environment variable:
+
+1. Read it once via a function-local static (cached, race-free C++
+   memory model semantics).
+2. Add a one-shot stderr warning in `webserver::start()` naming the
+   risk explicitly.
+3. Document the variable, its risk, and its startup signal here.
+4. Cross-reference the entry from `specs/architecture/10-observability.md`.

specs/architecture/10-observability.md

@@ -4,5 +4,6 @@ The library is a passive provider; callers wire their own logging:
 - `log_access` callback (already in `create_webserver`): invoked per request with the URI.
 - `log_error` callback: invoked on internal errors and uncaught handler exceptions.
 - No metrics or tracing surface added in v2.0.
+- Debug-only environment variables (e.g. `LIBHTTPSERVER_DEBUG_DUMP_REQUEST_BODY`): see [`docs/debug-env-vars.md`](../../docs/debug-env-vars.md). None are read on the production code path; all are silent unless explicitly set, and the library emits a one-shot `SECURITY WARNING` to stderr (and to `log_error` when wired) when any of them is detected at `webserver::start()`.
 
 ---

specs/tasks/M7-v2-cleanup/TASK-074.md

@@ -8,10 +8,10 @@
 `webserver_body_pipeline.cpp:199-208` contains a `#ifdef DEBUG` block that prints the raw request body (including credentials and PII) to stdout. The inline comment explicitly warns it must never be widened to release builds. The risk is contained but the suppression mechanism is fragile (a developer could ship a debug build to production). Make the print opt-in via an explicit env var so the default behaviour even in `DEBUG` builds is safe.
 
 **Action Items:**
-- [ ] Replace the `#ifdef DEBUG` guard with a runtime check on `getenv("LIBHTTPSERVER_DEBUG_DUMP_REQUEST_BODY")`. The block compiles always but only fires when the env var is set and the build is `DEBUG` (or unconditionally, since prod builds never set the var). Document the env var in `src/httpserver/detail/README.md` (or wherever debug knobs live).
-- [ ] Add a warning log at startup if the env var is set, naming the security risk.
-- [ ] Update the inline comment to reference the env var rather than `#ifdef DEBUG`.
-- [ ] Spot-check that release builds with `-DDEBUG` accidentally set still do not print without the env var.
+- [x] Replace the `#ifdef DEBUG` guard with a runtime check on `getenv("LIBHTTPSERVER_DEBUG_DUMP_REQUEST_BODY")`. The block compiles always but only fires when the env var is set; release builds never set the var, so the gate is a one-line runtime check independent of any compile-time `DEBUG` define. Documented in the new `docs/debug-env-vars.md` (a fresh, dedicated home for `LIBHTTPSERVER_*` debug knobs) with a cross-reference from `specs/architecture/10-observability.md`.
+- [x] Add a warning log at startup if the env var is set, naming the security risk. Implemented as `httpserver::detail::maybe_warn_debug_dump_request_body()` called from `webserver::start()`. One-shot stderr write (process-wide `std::atomic<bool>` flag) plus best-effort forwarding to `webserver::get_error_logger()` when wired. Message names the env var, the SECURITY WARNING marker, credentials/cookies/PII at risk, and points to `docs/debug-env-vars.md`.
+- [x] Update the inline comment to reference the env var rather than `#ifdef DEBUG`. The comment in `webserver_body_pipeline.cpp` now names `LIBHTTPSERVER_DEBUG_DUMP_REQUEST_BODY`, points to `docs/debug-env-vars.md`, and notes that the TASK-057 `operator<<` redaction does not cover this code path.
+- [x] Spot-check that release builds with `-DDEBUG` accidentally set still do not print without the env var. Pinned by `test/integ/debug_dump_request_body_unset_test.cpp`, which builds and runs identically on both `--enable-debug` and stock release configurations; the runtime check is the only gate, so the spot-check resolves by construction.
 
 **Dependencies:**
 - Blocked by: None
@@ -27,4 +27,4 @@
 **Related Requirements:** PRD §2 security NFR (defense-in-depth)
 **Related Decisions:** None new
 
-**Status:** Backlog
+**Status:** Done

specs/tasks/M7-v2-cleanup/_index.md

@@ -38,7 +38,7 @@ TASK-093).
 | TASK-071 | Wire `install_not_found_alias_` stub and remove dead `lambda_handler` arm | MED | S | Done |
 | TASK-072 | Arena-allocated unescape on the warm path | MED | M | Done |
 | TASK-073 | Revisit libmicrohttpd v0.99 unescape workaround | LOW | S | Done |
-| TASK-074 | Gate DEBUG raw-body printing behind explicit opt-in | LOW (sec) | S | Backlog |
+| TASK-074 | Gate DEBUG raw-body printing behind explicit opt-in | LOW (sec) | S | Done |
 | TASK-075 | Propagate `wait_for_server_ready` to sibling hooks integ tests | HIGH | M | Backlog |
 | TASK-076 | Replace tautological-pass blocks in TLS test lanes | HIGH | M | Backlog |
 | TASK-077 | Restore Windows / Darwin coverage in skipped test suites | HIGH | L | Backlog |