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

Replaces the #ifdef DEBUG guard around the raw request-body stdout
dump in src/detail/webserver_body_pipeline.cpp with a runtime opt-in
keyed on LIBHTTPSERVER_DEBUG_DUMP_REQUEST_BODY. Default behaviour is
now silent on RELEASE *and* DEBUG builds alike -- the env var is the
only gate, so a debug build accidentally shipped to production cannot
leak credentials/PII unless the operator explicitly opted in.

When the env var is observed at webserver::start(), the library emits
a single SECURITY WARNING line to stderr (and to the user's log_error
callback when wired) naming the env var, the credential/PII risk, and
the docs pointer. Process-wide std::atomic<bool> flag means multiple
webservers in the same process produce exactly one stderr emission.

The runtime gate is cached in a function-local static (Magic Static)
so getenv() is read at most once per process; subsequent setenv()
calls are intentionally ignored (debug-knob semantics).

New documentation:
  - docs/debug-env-vars.md   - canonical home for LIBHTTPSERVER_*
    debug knobs; describes effect, risk, startup signal, disable
    procedure, and the spot-check that release-with-DDEBUG still
    behaves correctly. Includes a checklist for future debug knobs.
  - specs/architecture/10-observability.md cross-references the new
    doc.

New tests (test/integ/):
  - debug_dump_request_body_unset_test.cpp - asserts silence on both
    stdout and stderr when the env var is unset; passes identically
    on DEBUG and RELEASE builds.
  - debug_dump_request_body_set_test.cpp - asserts the body dump
    and one-shot SECURITY WARNING fire when the env var is set, and
    pins the process-wide idempotence with a second webserver.

The two binaries are split because the function-local-static cache
means the first observation in the process locks in for the rest;
splitting gives each scenario a deterministic fresh process.

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:** In Progress

src/detail/webserver_body_pipeline.cpp

@@ -36,16 +36,18 @@
 
 #include <strings.h>
 
+#include <atomic>
 #include <chrono>
 #include <cstddef>
 #include <cstdint>
+#include <cstdio>
+#include <cstdlib>
 #include <cstring>
-#ifdef DEBUG
 #include <iostream>
-#endif  // DEBUG
 #include <optional>
 #include <span>
 #include <string>
+#include <string_view>
 #include <utility>
 
 #include "httpserver/create_webserver.hpp"
@@ -65,6 +67,35 @@ namespace detail {
 
 namespace {
 
+// TASK-074: gate the raw-body dump in requests_answer_second_step
+// behind an explicit, runtime, opt-in environment variable. The check
+// is cached in a function-local static so getenv() is called at most
+// once per process; subsequent setenv() calls are intentionally
+// ignored (debug-knob semantics, matches the cheap race-free choice
+// described in DR-009 / TASK-074 plan). C++11 guarantees thread-safe
+// init of function-local statics, so the first call from MHD's
+// request-handling threads is safe even under concurrent first-touch.
+//
+// Default behaviour is silent on RELEASE and DEBUG builds alike; the
+// env var is the ONLY gate. A debug build accidentally shipped to
+// production therefore still does not leak credentials/PII unless the
+// operator explicitly opted in. Accepts any non-empty, non-"0" value.
+bool debug_dump_request_body_enabled() {
+    static const bool enabled = [] {
+        const char* v = std::getenv("LIBHTTPSERVER_DEBUG_DUMP_REQUEST_BODY");
+        return v != nullptr && v[0] != '\0' && std::string_view(v) != "0";
+    }();
+    return enabled;
+}
+
+// TASK-074: process-wide print-once flag for the SECURITY WARNING
+// emitted at the first webserver::start() that observes the env var.
+// std::atomic<bool> + compare_exchange_strong matches the lock-free
+// atomic style used elsewhere (e.g. g_arena_fallback_count). The
+// idempotence is process-wide -- multiple webservers in the same
+// process trigger exactly one stderr warning.
+std::atomic<bool> g_debug_dump_warning_emitted{false};
+
 // Wrap the body_chunk firing site so requests_answer_second_step stays a
 // flat sequence of small steps. Returns true iff a hook short-circuited
 // and the caller should signal MHD that the chunk was consumed (returns
@@ -115,6 +146,55 @@ void run_post_processor_if_attached(modded_request* mr,
 
 }  // namespace
 
+// TASK-074: free function in namespace detail, declared in
+// webserver_impl.hpp. Reports whether the runtime opt-in env var is
+// effective in this process. Used by webserver::start()'s
+// security-warning emitter to decide whether to fire the one-shot
+// stderr notice.
+bool debug_dump_request_body_opted_in() {
+    return debug_dump_request_body_enabled();
+}
+
+// TASK-074: free function in namespace detail, declared in
+// webserver_impl.hpp. Called from webserver::start() before
+// MHD_start_daemon. Emits a one-shot SECURITY WARNING to stderr when
+// the env-var opt-in is observed, and forwards the same line to the
+// owning webserver's log_error callback when one is wired. The flag
+// is process-wide so multiple webservers do not flood stderr.
+//
+// Stderr is used (not std::cerr) to match the pre-existing
+// fprintf-to-stderr pattern in src/http_request.cpp / src/webserver.cpp
+// and to remain visible even when the user has not wired log_error.
+//
+// Both the stderr path and the log_error forwarding swallow any
+// exception so a misconfigured logger cannot abort the daemon
+// start sequence.
+void maybe_warn_debug_dump_request_body(const webserver* parent) {
+    if (!debug_dump_request_body_opted_in()) return;
+    bool expected = false;
+    if (!g_debug_dump_warning_emitted.compare_exchange_strong(
+            expected, true)) {
+        return;  // already warned this process
+    }
+    constexpr const char* msg =
+        "[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.";
+    std::fprintf(stderr, "%s\n", msg);
+    std::fflush(stderr);
+    if (parent != nullptr) {
+        if (auto sink = parent->get_error_logger()) {
+            try {
+                sink(msg);
+            } catch (...) {
+                // swallow: misconfigured logger must not abort start()
+            }
+        }
+    }
+}
+
 MHD_Result webserver_impl::requests_answer_first_step(MHD_Connection* connection, struct detail::modded_request* mr) {
     // The http_request constructor calls pick_resource(connection) internally
     // to locate the per-connection arena installed by connection_notify via
@@ -196,16 +276,19 @@ MHD_Result webserver_impl::requests_answer_second_step(MHD_Connection* connectio
         }
     }
 
-#ifdef DEBUG
-    // WARNING (TASK-057): this emits the raw request body to stdout.
-    // If a client posts credentials in a form body
-    // (`application/x-www-form-urlencoded` with a `password=` field) or
-    // raw Basic-auth bytes, those values will appear verbatim in the
-    // debug stream. Must remain guarded by `#ifdef DEBUG` and must not
-    // be widened to release builds; the operator<< redaction policy
-    // does NOT cover this code path.
-    std::cout << "Writing content: " << std::string(upload_data, *upload_data_size) << std::endl;
-#endif  // DEBUG
+    // TASK-074 (was TASK-057): raw request-body dump, opt-in via the
+    // env var LIBHTTPSERVER_DEBUG_DUMP_REQUEST_BODY. Default behaviour
+    // is silent on RELEASE *and* DEBUG builds -- the env var is the
+    // only gate, so a debug build accidentally shipped to production
+    // still does not leak credentials/PII unless the operator opted
+    // in. See docs/debug-env-vars.md for the security warning and
+    // the one-shot startup notice that fires when the env var is set.
+    // The operator<< redaction policy (TASK-057) does NOT cover this
+    // code path: raw bytes are written verbatim.
+    if (debug_dump_request_body_enabled()) {
+        std::cout << "Writing content: "
+                  << std::string(upload_data, *upload_data_size) << std::endl;
+    }
     // The post iterator is only created from the libmicrohttpd for content of type
     // multipart/form-data and application/x-www-form-urlencoded
     // all other content (which is indicated by mr-pp == nullptr)

src/detail/webserver_setup.cpp

@@ -296,6 +296,13 @@ bool webserver::start(bool blocking) {
             "Cannot specify maximum number of threads when using a thread per connection");
     }
 
+    // TASK-074: fire the one-shot raw-body-dump opt-in SECURITY
+    // WARNING before MHD_start_daemon so the operator sees the
+    // notice on every fresh process invocation that actually starts
+    // accepting traffic. Defined in webserver_body_pipeline.cpp
+    // alongside the consumer of the opt-in flag.
+    detail::maybe_warn_debug_dump_request_body(this);
+
     vector<struct MHD_OptionItem> iov;
     impl_->build_mhd_option_array(iov);
     const int start_conf = impl_->compose_start_flags();

src/httpserver/detail/webserver_impl.hpp

@@ -100,6 +100,34 @@ class lambda_resource;
 // httpserver/detail/connection_state.hpp for documentation and
 // rationale.
 
+/**
+ * @brief Whether the runtime opt-in for raw-body debug dumping is in
+ *        effect for this process (TASK-074).
+ *
+ * Reads the env var LIBHTTPSERVER_DEBUG_DUMP_REQUEST_BODY once on
+ * first call via a function-local static; subsequent setenv() calls
+ * are intentionally ignored. Returns true iff the variable is set to
+ * any non-empty, non-`"0"` value. Default behaviour is silent on both
+ * RELEASE and DEBUG builds.
+ */
+bool debug_dump_request_body_opted_in();
+
+/**
+ * @brief Emit a one-shot SECURITY WARNING when raw-body dumping is
+ *        opted in (TASK-074).
+ *
+ * Called from webserver::start() before MHD_start_daemon. If the env
+ * var opt-in is active, writes a single line naming the env var, the
+ * SECURITY WARNING marker, and the credential / PII risk to stderr,
+ * and (when wired) forwards the same line to the owning webserver's
+ * log_error callback. Process-wide idempotent: multiple webservers in
+ * the same process produce exactly one stderr emission.
+ *
+ * @param parent  Owning webserver pointer (used to find log_error).
+ *                May be nullptr; the stderr emission still fires.
+ */
+void maybe_warn_debug_dump_request_body(const webserver* parent);
+
 // webserver_impl: backing object holding all backend-coupled state of
 // `webserver` (MHD daemon, mutexes, ban/allowance sets, route table,
 // route cache, websocket registry, optional GnuTLS SNI cache) plus the