TASK-036 review: document auth_handler_ptr deferral (findings 4 & 7)

- Add a TODO comment on auth_handler_ptr in create_webserver.hpp
  documenting the deferred migration to std::optional<http_response>
  (findings 4 & 7: code-quality-reviewer + code-simplifier). Changing
  the public typedef mid-milestone would cascade into
  centralized_authentication.cpp and authentication.cpp; scoped out.
- Rename local variable auth_resp -> auth_rejection_response in the
  auth_handler alias hook (webserver_aliases.cpp) to clarify that null
  means "allow" and non-null means "reject with this response" — the
  minimum improvement from finding 7 recommendation (b).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: etr

src/detail/webserver_aliases.cpp

@@ -194,14 +194,20 @@ void webserver::install_default_alias_hooks_() {
                     if (impl_ptr->should_skip_auth(path)) {
                         return hook_action::pass();
                     }
-                    // Call the user-supplied auth_handler.
-                    std::shared_ptr<http_response> auth_resp =
+                    // Call the user-supplied auth_handler. Returns nullptr
+                    // to mean "allow" (pass-through); non-null means
+                    // "reject with this response". The shared_ptr<> is the
+                    // v1 nullable-optional pattern; see the TODO on
+                    // auth_handler_ptr in create_webserver.hpp for the
+                    // deferred migration plan.
+                    std::shared_ptr<http_response> auth_rejection_response =
                         ws_ptr->auth_handler(*ctx.request);
-                    if (auth_resp == nullptr) {
+                    if (auth_rejection_response == nullptr) {
                         return hook_action::pass();
                     }
-                    // Auth failed: short-circuit with the auth response.
-                    return hook_action::respond_with(std::move(*auth_resp));
+                    // Auth failed: short-circuit with the rejection response.
+                    return hook_action::respond_with(
+                        std::move(*auth_rejection_response));
                 })))
             .detach();
     }

src/httpserver/create_webserver.hpp

@@ -78,6 +78,15 @@ typedef std::function<std::pair<std::string, std::string>(const std::string& ser
 namespace http { class file_info; }
 
 typedef std::function<bool(const std::string&, const std::string&, const http::file_info&)> file_cleanup_callback_ptr;
+
+// TODO(follow-up): migrate auth_handler_ptr to
+//   std::function<std::optional<http_response>(const http_request&)>
+// to complete the DR-004 value-return rollout to the auth hook (removing
+// the per-authenticated-request heap allocation for the shared_ptr control
+// block). This requires updating the call site in webserver_finalize.cpp,
+// the example in examples/centralized_authentication.cpp, and the
+// integration test in test/integ/authentication.cpp. Deferred from TASK-036
+// to avoid a cascading public-API break mid-milestone.
 typedef std::function<std::shared_ptr<http_response>(const http_request&)> auth_handler_ptr;
 
 /**