Merge TASK-057: redact credentials in http_request::operator<<

Default-redact user:/pass:/Authorization-header values and cookies
in http_request::operator<< output (CWE-312/CWE-532). Verbose form
is opt-in via create_webserver::expose_credentials_in_logs(true)
for development.

Conflicts: test/Makefile.am check_PROGRAMS list — kept both
http_request_operator_stream (TASK-057) and v2_dispatch_contract
(TASK-053, just merged) alongside the auth_handler_* entries.

Author: etr

RELEASE_NOTES.md

@@ -209,6 +209,17 @@ and see the v2 replacement.
   on the builder. Configured `internal_error_handler` callbacks are
   unaffected — they still receive the message and can build any body
   they want.
+- **`http_request::operator<<` redacts credentials by default.**
+  v1 (and earlier v2 builds) emitted `pass:"<plaintext>"`,
+  `digested_pass:"<plaintext>"`, `Authorization`/`Proxy-Authorization`
+  header values, and cookie values verbatim into diagnostic output,
+  leaking every credential into any log aggregation pipeline that
+  captures operator-stream dumps (CWE-312, CWE-532, OWASP A09:2021).
+  v2.0 replaces those fields with the fixed token `<redacted>` in the
+  default stream output. To restore the v1 verbose form for local
+  development, call `.expose_credentials_in_logs(true)` on the
+  `create_webserver` builder — this flag is intended for development
+  only and must not be set in production deployments.
 
 ## Threading
 

specs/tasks/v2-deferred-backlog-plan.md

@@ -304,13 +304,13 @@ production deploy leaks every Basic-auth password into their log
 aggregation pipeline.
 
 **Action Items:**
-- [ ] Replace the literal password emission with a fixed redaction token
+- [x] Replace the literal password emission with a fixed redaction token
   (`pass:"<redacted>"`). Same treatment for `digested_pass` and any
   other authentication secret on the stream.
-- [ ] Add an opt-in `webserver_builder.expose_credentials_in_logs(true)`
+- [x] Add an opt-in `webserver_builder.expose_credentials_in_logs(true)`
   flag for the rare developer who needs the verbose form locally.
-- [ ] Update Doxygen on the operator to call out the redaction policy.
-- [ ] Add a unit test
+- [x] Update Doxygen on the operator to call out the redaction policy.
+- [x] Add a unit test
   `http_request_test::operator_stream_redacts_credentials`.
 
 **Dependencies:**
@@ -327,6 +327,8 @@ aggregation pipeline.
 **Related Findings:** task-019 #22
 **Related Decisions:** none new; A09:2021
 
+**Status:** Done
+
 ---
 
 ## TASK-058 — Hot-path allocation pass

specs/unworked_review_issues/2026-05-30_235001_task-057.md

@@ -103,6 +103,11 @@ http_request create_test_request::build() {
     req.impl_->tls_enabled_local = _tls_enabled;
 #endif  // HAVE_GNUTLS
 
+    // TASK-057: propagate the test-builder opt-in into the impl. The
+    // webserver-dispatch path does the equivalent assignment in
+    // webserver_impl::requests_answer_first_step.
+    req.set_expose_credentials_in_logs(_expose_credentials_in_logs);
+
     return req;
 }
 

src/create_test_request.cpp

@@ -123,6 +123,9 @@ MHD_Result webserver_impl::requests_answer_first_step(MHD_Connection* connection
     // site but explicit within the constructor. (spec-alignment-checker-iter1-2/3)
     mr->dhr.reset(new http_request(connection, parent->unescaper));
     mr->dhr->set_file_cleanup_callback(parent->file_cleanup_callback);
+    // TASK-057: propagate the redaction-bypass bit so operator<< honours
+    // the builder opt-in for every request the webserver dispatches.
+    mr->dhr->set_expose_credentials_in_logs(parent->expose_credentials_in_logs);
 
     // TASK-047 -- request_received hook. Fires after the http_request is
     // populated but before any body bytes are read (and before any

src/detail/webserver_body_pipeline.cpp

@@ -362,17 +362,90 @@ void http_request::set_file_cleanup_callback(file_cleanup_callback_ptr callback)
     impl_->file_cleanup_callback_ = callback;
 }
 
+void http_request::set_expose_credentials_in_logs(bool v) {
+    impl_->expose_credentials_in_logs_ = v;
+}
+
+namespace {
+
+// TASK-057: Authorization-class header names whose values carry
+// credential material (Basic / Digest / Bearer payloads). Matched
+// case-insensitively against the keys in the Headers / Footers maps
+// so that the redaction policy is robust to header-case variation.
+bool is_authorization_header_key(std::string_view key) noexcept {
+    constexpr std::string_view kAuth = "Authorization";
+    constexpr std::string_view kProxyAuth = "Proxy-Authorization";
+    if (key.size() != kAuth.size() && key.size() != kProxyAuth.size()) {
+        return false;
+    }
+    auto ieq = [](std::string_view a, std::string_view b) noexcept {
+        if (a.size() != b.size()) return false;
+        for (std::size_t i = 0; i < a.size(); ++i) {
+            const unsigned char ca = static_cast<unsigned char>(a[i]);
+            const unsigned char cb = static_cast<unsigned char>(b[i]);
+            if (std::tolower(ca) != std::tolower(cb)) return false;
+        }
+        return true;
+    };
+    return ieq(key, kAuth) || ieq(key, kProxyAuth);
+}
+
+constexpr std::string_view kRedacted = "<redacted>";
+
+// TASK-057: emit a Headers/Footers map with Authorization-class header
+// values replaced by the fixed redaction token. Mirrors the wire shape
+// of http::dump_header_map(header_view_map) for non-authorization
+// entries so the on-the-wire diagnostic format is unchanged.
+void dump_header_map_redacted(std::ostream& os, const std::string& prefix,
+                              const http::header_view_map& map) {
+    if (map.empty()) return;
+    os << "    " << prefix << " [";
+    for (const auto& kv : map) {
+        os << kv.first << ":\"";
+        if (is_authorization_header_key(kv.first)) {
+            os << kRedacted;
+        } else {
+            os << kv.second;
+        }
+        os << "\" ";
+    }
+    os << "]" << std::endl;
+}
+
+// TASK-057: cookie values are credential material by default (session
+// IDs, CSRF tokens, JWTs); redaction is unconditional on the keys
+// (which remain visible for log triage).
+void dump_cookie_map_redacted(std::ostream& os, const std::string& prefix,
+                              const http::header_view_map& map) {
+    if (map.empty()) return;
+    os << "    " << prefix << " [";
+    for (const auto& kv : map) {
+        os << kv.first << ":\"" << kRedacted << "\" ";
+    }
+    os << "]" << std::endl;
+}
+
+}  // namespace
+
 std::ostream& operator<< (std::ostream& os, const http_request& r) {
+    const bool expose = r.impl_->expose_credentials_in_logs_;
     os << r.get_method() << " Request [";
-    // TASK-034: get_user/get_pass are unconditional; they return empty
-    // on HAVE_BAUTH-off builds, so the dump prints two empty quoted
-    // strings in that case (harmless).
-    os << "user:\"" << r.get_user() << "\" pass:\"" << r.get_pass() << "\"";
+    if (expose) {
+        os << "user:\"" << r.get_user() << "\" pass:\"" << r.get_pass() << "\"";
+    } else {
+        os << "user:\"" << r.get_user() << "\" pass:\"" << kRedacted << "\"";
+    }
     os << "] path:\"" << r.get_path() << "\"" << std::endl;
 
-    http::dump_header_map(os, "Headers", r.get_headers());
-    http::dump_header_map(os, "Footers", r.get_footers());
-    http::dump_header_map(os, "Cookies", r.get_cookies());
+    if (expose) {
+        http::dump_header_map(os, "Headers", r.get_headers());
+        http::dump_header_map(os, "Footers", r.get_footers());
+        http::dump_header_map(os, "Cookies", r.get_cookies());
+    } else {
+        dump_header_map_redacted(os, "Headers", r.get_headers());
+        dump_header_map_redacted(os, "Footers", r.get_footers());
+        dump_cookie_map_redacted(os, "Cookies", r.get_cookies());
+    }
     http::dump_arg_map(os, "Query Args", r.get_args());
 
     os << "    Version [ " << r.get_version() << " ] Requestor [ " << r.get_requestor()

src/http_request.cpp

@@ -120,6 +120,15 @@ class create_test_request {
         return *this;
     }
 
+    // TASK-057: opt out of the default credential-redaction policy in
+    // http_request::operator<<. Mirrors the webserver-side builder
+    // setter @ref create_webserver::expose_credentials_in_logs for the
+    // unit-test scope (no webserver construction).
+    create_test_request& expose_credentials_in_logs(bool enable = true) {
+        _expose_credentials_in_logs = enable;
+        return *this;
+    }
+
     http_request build();
 
  private:
@@ -142,6 +151,10 @@ class create_test_request {
     std::string _requestor = "127.0.0.1";
     uint16_t _requestor_port = 0;
     bool _tls_enabled = false;
+    // TASK-057: default false (secure-by-default). When true, build()
+    // sets http_request_impl::expose_credentials_in_logs_ so the
+    // diagnostic dump streams the v1 verbose form.
+    bool _expose_credentials_in_logs = false;
 };
 
 }  // namespace httpserver

src/httpserver/create_test_request.hpp

@@ -283,6 +283,34 @@ class create_webserver {
          _expose_exception_messages = enable; return *this;
      }
 
+     /**
+      * Restore the v1 / pre-TASK-057 behaviour of streaming credential
+      * material verbatim from @ref httpserver::operator<<(std::ostream&, const http_request&).
+      *
+      * @warning CWE-312 / CWE-532 (OWASP A09:2021): when this flag is
+      *          enabled and the dump is routed to a log aggregator
+      *          (`log_access`, `log_error`, stdout-capturing systemd, or
+      *          a centralised syslog / SIEM pipeline), every Basic-auth
+      *          password, every Authorization / Proxy-Authorization
+      *          header value, and every cookie / session token is
+      *          written in plaintext to the log store. Enable only in
+      *          development or behind an explicit `#ifndef NDEBUG`
+      *          guard.
+      *
+      * Default is `false`: `pass`, `Authorization`, `Proxy-Authorization`,
+      * and every cookie value are streamed as the fixed token
+      * `"<redacted>"`. The username (`user:"..."`) is never redacted —
+      * it is an identifier, not a secret (REMOTE_USER access-log
+      * convention).
+      *
+      * @param enable `true` to expose credentials in diagnostic dumps
+      *               (dev only), `false` for the default redaction.
+      * @return reference to this builder for chaining.
+      */
+     create_webserver& expose_credentials_in_logs(bool enable = true) {
+         _expose_credentials_in_logs = enable; return *this;
+     }
+
      create_webserver& https_mem_key(const std::string& v) { _https_mem_key = http::load_file(v); return *this; }
      create_webserver& https_mem_cert(const std::string& v) { _https_mem_cert = http::load_file(v); return *this; }
      create_webserver& https_mem_trust(const std::string& v) { _https_mem_trust = http::load_file(v); return *this; }
@@ -569,6 +597,11 @@ class create_webserver {
      // true, internal_error_page surfaces the originating exception's
      // message in the default 500 body (development-only behaviour).
      bool _expose_exception_messages = false;
+     // TASK-057: default false (CWE-312 / CWE-532 fix). When true,
+     // http_request::operator<< restores the v1 verbose form for the
+     // four credential surfaces (pass, Authorization /
+     // Proxy-Authorization header values, cookie values).
+     bool _expose_credentials_in_logs = false;
      std::string _https_mem_key;
      std::string _https_mem_cert;
      std::string _https_mem_trust;

src/httpserver/create_webserver.hpp

@@ -250,6 +250,15 @@ class http_request_impl {
     mutable std::vector<std::string> path_pieces_public_;
     mutable bool path_pieces_public_built_ = false;
 
+    // TASK-057: when true, http_request::operator<< streams credential
+    // material verbatim (v1 verbose form). Default false: the four
+    // credential surfaces (pass, Authorization / Proxy-Authorization
+    // header values, all cookie values) are replaced by the fixed
+    // token "<redacted>". Plumbed from webserver::expose_credentials_in_logs
+    // via webserver_impl::requests_answer_first_step, or directly via
+    // create_test_request::expose_credentials_in_logs() for unit tests.
+    bool expose_credentials_in_logs_ = false;
+
 #ifdef HAVE_GNUTLS
     // TASK-019: cache fields for the high-level cert accessors. The two
     // time fields are spelled std::int64_t (not std::time_t) so they

src/httpserver/detail/http_request_impl.hpp

@@ -525,12 +525,52 @@ class http_request {
 
      void set_file_cleanup_callback(file_cleanup_callback_ptr callback);
 
+     // TASK-057: set the redaction-bypass bit for diagnostic streaming.
+     // Plumbed from webserver::expose_credentials_in_logs at dispatch
+     // time and from create_test_request::build() for unit tests.
+     void set_expose_credentials_in_logs(bool v);
+
      friend class webserver;
      friend class detail::webserver_impl;  // TASK-014: PIMPL dispatch path
      friend struct detail::modded_request;
      friend class create_test_request;    // TASK-015: test builder accesses impl_
 };
 
+/**
+ * Stream-insert a human-readable dump of @p r into @p os for diagnostic
+ * logging.
+ *
+ * @section redaction Redaction policy (TASK-057, OWASP A09:2021 / CWE-312 / CWE-532)
+ * By default the following fields are emitted as the fixed token
+ * `"<redacted>"` instead of their plaintext values:
+ *   - The Basic-auth password (`pass:"<redacted>"`)
+ *   - The `Authorization` and `Proxy-Authorization` request headers
+ *     (and the same names in trailers / footers), case-insensitive
+ *   - Every cookie value (cookie keys are preserved for log triage)
+ *
+ * The username (`user:"..."`) is NOT redacted — it follows the REMOTE_USER
+ * access-log convention; it is an identifier, not a secret.
+ *
+ * Query-string arguments are streamed verbatim. Callers that put
+ * credential material in query parameters (`?token=...`) should
+ * sanitize before constructing the request URL; see the warning in
+ * the class-level block of @ref http_request.
+ *
+ * @section opt_in Restoring the verbose v1 form
+ * Call `create_webserver::expose_credentials_in_logs(true)` on the
+ * builder used to construct the parent @ref webserver. This restores
+ * the pre-TASK-057 plaintext-everywhere behaviour for every
+ * @ref http_request the webserver dispatches.
+ *
+ * @warning `expose_credentials_in_logs(true)` is DEVELOPMENT-ONLY.
+ *          When the dump is routed to a log aggregator (`log_access`,
+ *          `log_error`, stdout-capturing systemd, or a centralised
+ *          syslog/SIEM pipeline), enabling the flag in production
+ *          exposes every Basic-auth password, every Authorization
+ *          header, and every cookie/session token in plaintext to
+ *          anyone with read access to the log store. Guard with
+ *          `#ifndef NDEBUG` or an explicit environment check.
+ */
 std::ostream &operator<< (std::ostream &os, const http_request &r);
 
 }  // namespace httpserver