TASK-058 step 2: pre-normalize auth_skip_paths + empty-list early-out

Pre-normalize each auth_skip_paths entry once at webserver
construction time and short-circuit should_skip_auth when the list is
empty.  Two wins:

1. Empty-list early-out -- servers with no skip paths configured (the
   production-typical case for any auth_handler that gates every
   route, or any server with no auth_handler at all) pay zero
   normalize cost per request.

2. Compare canonical-vs-canonical -- the request path is normalised
   on the per-request side; pre-TASK-058 the skip list was matched
   verbatim against it, so non-canonical inputs like "/public/" or
   "/a/../b" silently never matched.  This is a latent bug-fix in
   addition to the perf win.

Note on the task brief's "store on route_entry" framing.  The plan
calls for storing the normalized form on route_entry, but route_entry
is a per-route attribute and auth_skip_paths is a webserver-level
request filter that doesn't look at route_entry at all (see
webserver_request.cpp should_skip_auth -- it compares the request
path against parent->auth_skip_paths, not any route attribute).  The
optimization is moved to where the registration-time data actually
lives: auth_skip_paths_normalized_ as a sibling on webserver.  The
brief's *spirit* (do the normalize once at registration, not per
request) is preserved.

New helper detail::normalize_auth_skip_paths handles the wildcard-
suffix carve-out: entries ending in "/*" keep their trailing wildcard
verbatim; only the prefix before "/*" is normalized.  The "/*" case
maps to itself (matches the v1 dispatch behaviour).

TDD red->green via new test/unit/auth_skip_normalize_test.cpp:
 - non-canonical skip entries ({/public/, /a/../b, /x/./y}) now match
   canonical request paths ({/public, /b, /x/y})
 - canonical skip entries continue to work (regression net)
 - wildcard-suffix skip entries normalize the prefix correctly
 - empty skip list returns false for every path without touching the
   per-request normalize machinery

Files touched:
 - src/httpserver/detail/path_normalize.hpp (new, declares the helper)
 - src/detail/webserver_request.cpp (defines normalize_auth_skip_paths
   alongside normalize_path; should_skip_auth uses the normalized list
   and the empty-list early-out)
 - src/httpserver/webserver.hpp (auth_skip_paths_normalized_ member)
 - src/webserver.cpp (populate at construction)
 - test/Makefile.am (wire auth_skip_normalize)
 - test/unit/auth_skip_normalize_test.cpp (new)

Author: etr

src/detail/webserver_request.cpp

@@ -67,6 +67,7 @@
 #include "httpserver/detail/http_endpoint.hpp"
 #include "httpserver/detail/lambda_resource.hpp"
 #include "httpserver/detail/modded_request.hpp"
+#include "httpserver/detail/path_normalize.hpp"
 #include "httpserver/detail/resource_hook_table.hpp"
 #include "httpserver/http_request.hpp"
 #include "httpserver/http_resource.hpp"
@@ -136,10 +137,61 @@ std::string normalize_path(const std::string& path) {
 
 }  // namespace
 
+// TASK-058 step 2: pre-normalize each auth_skip_paths entry once at
+// webserver construction time.  Entries ending in "/*" keep their
+// wildcard suffix; the prefix before the wildcard is normalized.
+// Callers (webserver::webserver) pass the raw config-bag list and
+// store the result on the webserver instance as a sibling to the
+// original `auth_skip_paths` list.  Pre-TASK-058 the skip list was
+// matched verbatim against a normalized request path, so non-
+// canonical inputs (e.g. "/public/", "/a/../b") silently never
+// matched -- the on-the-wire bug this normalization closes.
+std::vector<std::string> normalize_auth_skip_paths(
+        const std::vector<std::string>& raw) {
+    std::vector<std::string> out;
+    out.reserve(raw.size());
+    for (const auto& entry : raw) {
+        // Wildcard suffix: strip the trailing "/*", normalize the
+        // prefix, then re-append "/*".  Empty prefix (just "/*")
+        // canonicalises to "/" + "/*" -> "//*", which would never
+        // have matched anything sensible pre-fix either, so we keep
+        // the literal "/*" unchanged (matches the v1 wildcard
+        // behaviour at the dispatch site).
+        if (entry.size() > 2 && entry.back() == '*' &&
+            entry[entry.size() - 2] == '/') {
+            std::string prefix = entry.substr(0, entry.size() - 2);
+            std::string normalized_prefix = normalize_path(prefix);
+            if (normalized_prefix == "/") {
+                // "/" + "/*" -> "/*" (keep literal).
+                out.push_back("/*");
+            } else {
+                out.push_back(normalized_prefix + "/*");
+            }
+            continue;
+        }
+        out.push_back(normalize_path(entry));
+    }
+    return out;
+}
+
 bool webserver_impl::should_skip_auth(const std::string& path) const {
+    // TASK-058 step 2: empty-list early-out.  Servers with no
+    // auth_skip_paths configured pay zero normalization cost.  This
+    // is the production-typical case for any server whose auth
+    // surface either covers every route or has no auth_handler at
+    // all.
+    if (parent->auth_skip_paths_normalized.empty()) {
+        return false;
+    }
+
+    // TASK-058 step 2: compare against the pre-normalized list (built
+    // once at construction time) instead of re-normalizing skip-list
+    // entries on every request.  The per-request normalize_path call
+    // on @p path remains -- the inbound URL is per-request data and
+    // cannot be pre-normalized.
     std::string normalized = normalize_path(path);
 
-    for (const auto& skip_path : parent->auth_skip_paths) {
+    for (const auto& skip_path : parent->auth_skip_paths_normalized) {
         if (skip_path == normalized) return true;
         // Support wildcard suffix (e.g., "/public/*")
         if (skip_path.size() > 2 && skip_path.back() == '*' &&

src/httpserver/detail/path_normalize.hpp

@@ -0,0 +1,53 @@
+/*
+     This file is part of libhttpserver
+     Copyright (C) 2011-2026 Sebastiano Merlino
+
+     This library is free software; you can redistribute it and/or
+     modify it under the terms of the GNU Lesser General Public
+     License as published by the Free Software Foundation; either
+     version 2.1 of the License, or (at your option) any later version.
+
+     This library is distributed in the hope that it will be useful,
+     but WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+     Lesser General Public License for more details.
+
+     You should have received a copy of the GNU Lesser General Public
+     License along with this library; if not, write to the Free Software
+     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+     USA
+*/
+
+// Internal detail header.  Strict gate: reachable only from libhttpserver
+// translation units.
+#if !defined(HTTPSERVER_COMPILATION)
+#error "path_normalize.hpp is internal; only reachable when compiling libhttpserver."
+#endif
+
+#ifndef SRC_HTTPSERVER_DETAIL_PATH_NORMALIZE_HPP_
+#define SRC_HTTPSERVER_DETAIL_PATH_NORMALIZE_HPP_
+
+#include <string>
+#include <vector>
+
+namespace httpserver {
+namespace detail {
+
+// TASK-058 step 2: pre-normalize an auth_skip_paths list so the per-
+// request comparison in webserver_impl::should_skip_auth runs against
+// already-canonical entries.  Each entry is fed through normalize_path
+// (the same helper that normalizes the *request* path inside
+// should_skip_auth).  Entries ending in "/*" keep their trailing "/*"
+// wildcard suffix; the prefix before the wildcard is normalized.
+//
+// Pure function: no shared state, callable from the webserver
+// constructor body.  The definition lives in detail/webserver_request.cpp
+// alongside normalize_path so the helper and its callers share a single
+// canonicalisation rule.
+std::vector<std::string> normalize_auth_skip_paths(
+        const std::vector<std::string>& raw);
+
+}  // namespace detail
+}  // namespace httpserver
+
+#endif  // SRC_HTTPSERVER_DETAIL_PATH_NORMALIZE_HPP_

src/httpserver/webserver.hpp

@@ -450,6 +450,13 @@ class webserver {
      const file_cleanup_callback_ptr file_cleanup_callback;
      const auth_handler_ptr auth_handler;
      const std::vector<std::string> auth_skip_paths;
+     // TASK-058 step 2: pre-normalized form of @ref auth_skip_paths,
+     // populated once at construction.  webserver_impl::should_skip_auth
+     // compares request paths against this list (not @ref auth_skip_paths)
+     // so non-canonical entries like "/public/" or "/a/../b" match the
+     // canonical request path the dispatch surface produces.  Built by
+     // detail::normalize_auth_skip_paths in webserver_request.cpp.
+     const std::vector<std::string> auth_skip_paths_normalized;
      const sni_callback_t sni_callback;
      const bool no_listen_socket;
      const bool no_thread_safety;

src/webserver.cpp

@@ -70,6 +70,7 @@
 #include "httpserver/detail/http_endpoint.hpp"
 #include "httpserver/detail/lambda_resource.hpp"
 #include "httpserver/detail/modded_request.hpp"
+#include "httpserver/detail/path_normalize.hpp"
 #include "httpserver/http_request.hpp"
 #include "httpserver/http_resource.hpp"
 #include "httpserver/http_response.hpp"
@@ -235,6 +236,8 @@ webserver::webserver(const create_webserver& params):
     file_cleanup_callback(params._file_cleanup_callback),
     auth_handler(params._auth_handler),
     auth_skip_paths(params._auth_skip_paths),
+    auth_skip_paths_normalized(
+        detail::normalize_auth_skip_paths(params._auth_skip_paths)),
     sni_callback(params._sni_callback),
     no_listen_socket(params._no_listen_socket),
     no_thread_safety(params._no_thread_safety),

test/Makefile.am

@@ -26,7 +26,7 @@ LDADD += -lcurl
 
 AM_CPPFLAGS = -I$(top_srcdir)/src -I$(top_srcdir)/src/httpserver/ -DHTTPSERVER_COMPILATION
 METASOURCES = AUTO
-check_PROGRAMS = basic file_upload http_utils threaded nodelay string_utilities http_endpoint ban_system ws_start_stop authentication deferred http_resource http_response create_webserver create_webserver_explicit new_response_types daemon_info uri_log feature_unavailable header_hygiene_iovec header_hygiene iovec_entry http_method constants body http_response_sbo http_response_factories http_response_move_sanitizer webserver_pimpl http_request_pimpl create_test_request http_request_arena http_request_const_getters http_request_tls_accessors http_request_operator_stream webserver_register_smartptr webserver_register_path_prefix webserver_on_methods webserver_route route_table lookup_pipeline route_table_concurrency routing_regression route_lookup_canonicalize v2_dispatch_contract threadsafety_stress webserver_features webserver_ws_unavailable webserver_register_ws_smartptr webserver_dauth_unavailable consumer_fixture header_hygiene_hooks hook_api_shape hooks_no_firing hooks_accept_ctx_shape hooks_connection_lifecycle hooks_accept_decision_banned hooks_accept_decision_throwing hooks_body_chunk_ctx_shape hooks_request_received_short_circuit hooks_body_chunk_observes_progress hooks_body_chunk_short_circuit_no_leak hooks_before_handler_ctx_shape hooks_route_resolved_miss_and_hit hooks_before_handler_short_circuit hooks_alias_count hooks_alias_functional hooks_handler_exception_chain hooks_handler_exception_user_handler_throws_continues_chain hooks_handler_exception_fallback_to_hardcoded_500 hooks_handler_exception_slot hooks_response_sent_ctx_shape hooks_request_completed_ctx_shape hooks_after_handler_replaces_response hooks_after_handler_mutates_response_in_place hooks_response_sent_carries_status_bytes_timing hooks_request_completed_fires_on_early_failure hooks_log_access_alias_slot hooks_per_route_invalid_phase_throws hooks_per_route_order hooks_per_route_early_413_per_endpoint hooks_per_route_resource_destroyed_first hooks_per_route_concurrent_registration auth_handler_optional_signature auth_handler_legacy_shim
+check_PROGRAMS = basic file_upload http_utils threaded nodelay string_utilities http_endpoint ban_system ws_start_stop authentication deferred http_resource http_response create_webserver create_webserver_explicit new_response_types daemon_info uri_log feature_unavailable header_hygiene_iovec header_hygiene iovec_entry http_method constants body http_response_sbo http_response_factories http_response_move_sanitizer webserver_pimpl http_request_pimpl create_test_request http_request_arena http_request_const_getters http_request_tls_accessors http_request_operator_stream webserver_register_smartptr webserver_register_path_prefix webserver_on_methods webserver_route route_table lookup_pipeline route_table_concurrency routing_regression route_lookup_canonicalize auth_skip_normalize v2_dispatch_contract threadsafety_stress webserver_features webserver_ws_unavailable webserver_register_ws_smartptr webserver_dauth_unavailable consumer_fixture header_hygiene_hooks hook_api_shape hooks_no_firing hooks_accept_ctx_shape hooks_connection_lifecycle hooks_accept_decision_banned hooks_accept_decision_throwing hooks_body_chunk_ctx_shape hooks_request_received_short_circuit hooks_body_chunk_observes_progress hooks_body_chunk_short_circuit_no_leak hooks_before_handler_ctx_shape hooks_route_resolved_miss_and_hit hooks_before_handler_short_circuit hooks_alias_count hooks_alias_functional hooks_handler_exception_chain hooks_handler_exception_user_handler_throws_continues_chain hooks_handler_exception_fallback_to_hardcoded_500 hooks_handler_exception_slot hooks_response_sent_ctx_shape hooks_request_completed_ctx_shape hooks_after_handler_replaces_response hooks_after_handler_mutates_response_in_place hooks_response_sent_carries_status_bytes_timing hooks_request_completed_fires_on_early_failure hooks_log_access_alias_slot hooks_per_route_invalid_phase_throws hooks_per_route_order hooks_per_route_early_413_per_endpoint hooks_per_route_resource_destroyed_first hooks_per_route_concurrent_registration auth_handler_optional_signature auth_handler_legacy_shim
 
 MOSTLYCLEANFILES = *.gcda *.gcno *.gcov
 
@@ -291,6 +291,14 @@ routing_regression_LDADD = $(LDADD) -lmicrohttpd
 route_lookup_canonicalize_SOURCES = unit/route_lookup_canonicalize_test.cpp
 route_lookup_canonicalize_LDADD = $(LDADD) -lmicrohttpd
 
+# auth_skip_normalize (TASK-058 step 2): pins that auth_skip_paths
+# entries are normalized at webserver construction time, so non-
+# canonical inputs match canonical request paths.  Same -lmicrohttpd
+# dependency as routing_regression: webserver pulls libhttpserver in,
+# which transitively touches libmicrohttpd headers.
+auth_skip_normalize_SOURCES = unit/auth_skip_normalize_test.cpp
+auth_skip_normalize_LDADD = $(LDADD) -lmicrohttpd
+
 # v2_dispatch_contract: TASK-053. End-to-end safety net pinning the
 # observable invariants the dispatch path must satisfy AFTER finalize_answer
 # is cut over from resolve_resource_for_request (v1 maps) to

test/unit/auth_skip_normalize_test.cpp

@@ -0,0 +1,148 @@
+/*
+     This file is part of libhttpserver
+     Copyright (C) 2011-2026 Sebastiano Merlino
+
+     This library is free software; you can redistribute it and/or
+     modify it under the terms of the GNU Lesser General Public
+     License as published by the Free Software Foundation; either
+     version 2.1 of the License, or (at your option) any later version.
+
+     This library is distributed in the hope that it will be useful,
+     but WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+     Lesser General Public License for more details.
+
+     You should have received a copy of the GNU Lesser General Public
+     License along with this library; if not, write to the Free Software
+     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+     USA
+*/
+
+// TASK-058 step 2: pin that auth_skip_paths entries are normalized at
+// webserver construction time, so non-canonical inputs ({"/public/",
+// "/a/../b", "/x/./y"}) match canonical request paths ({"/public",
+// "/b", "/x/y"}).
+//
+// Pre-TASK-058: should_skip_auth normalized the *request* path but
+// compared it verbatim against the skip list, so a non-canonical skip-
+// list entry never matched.  This was a latent bug -- callers who
+// passed pretty-but-non-canonical skip paths (e.g. trailing slashes
+// from copy-paste, "/foo/./bar" from path-builder code) silently saw
+// their auth-skip preference ignored.
+//
+// After step 2 the skip list is pre-normalized at construction; this
+// test pins the new behaviour and also covers the empty-list early-
+// out path (no skip paths configured -> should_skip_auth returns
+// false without touching normalize_path).
+
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "./httpserver.hpp"
+#include "./httpserver/detail/webserver_impl.hpp"
+#include "./littletest.hpp"
+
+namespace ht = httpserver;
+
+namespace {
+
+ht::detail::webserver_impl& impl_of(ht::webserver& ws) {
+    return *ht::webserver_test_access::impl(ws);
+}
+
+}  // namespace
+
+LT_BEGIN_SUITE(auth_skip_normalize_suite)
+    void set_up() {}
+    void tear_down() {}
+LT_END_SUITE(auth_skip_normalize_suite)
+
+// ---------------------------------------------------------------------
+// Non-canonical skip paths with trailing slashes match canonical
+// request paths after construction-time normalization.
+// ---------------------------------------------------------------------
+LT_BEGIN_AUTO_TEST(auth_skip_normalize_suite,
+                   trailing_slash_skip_path_matches_canonical_request)
+    ht::webserver ws{ht::create_webserver(8080)
+        .start_method(ht::http::http_utils::INTERNAL_SELECT)
+        .auth_skip_paths({"/public/"})};
+
+    // Canonical request path -- pre-normalize on skip-list side makes
+    // this match.
+    LT_CHECK(impl_of(ws).should_skip_auth("/public"));
+LT_END_AUTO_TEST(trailing_slash_skip_path_matches_canonical_request)
+
+// ---------------------------------------------------------------------
+// ".." segments in skip paths are collapsed at construction time.
+// ---------------------------------------------------------------------
+LT_BEGIN_AUTO_TEST(auth_skip_normalize_suite,
+                   dotdot_skip_path_matches_canonical_request)
+    ht::webserver ws{ht::create_webserver(8080)
+        .start_method(ht::http::http_utils::INTERNAL_SELECT)
+        .auth_skip_paths({"/a/../b"})};
+
+    LT_CHECK(impl_of(ws).should_skip_auth("/b"));
+LT_END_AUTO_TEST(dotdot_skip_path_matches_canonical_request)
+
+// ---------------------------------------------------------------------
+// "." segments in skip paths are stripped at construction time.
+// ---------------------------------------------------------------------
+LT_BEGIN_AUTO_TEST(auth_skip_normalize_suite,
+                   dot_skip_path_matches_canonical_request)
+    ht::webserver ws{ht::create_webserver(8080)
+        .start_method(ht::http::http_utils::INTERNAL_SELECT)
+        .auth_skip_paths({"/x/./y"})};
+
+    LT_CHECK(impl_of(ws).should_skip_auth("/x/y"));
+LT_END_AUTO_TEST(dot_skip_path_matches_canonical_request)
+
+// ---------------------------------------------------------------------
+// Already-canonical skip paths continue to work (regression net for
+// the existing happy path).
+// ---------------------------------------------------------------------
+LT_BEGIN_AUTO_TEST(auth_skip_normalize_suite,
+                   canonical_skip_path_still_matches)
+    ht::webserver ws{ht::create_webserver(8080)
+        .start_method(ht::http::http_utils::INTERNAL_SELECT)
+        .auth_skip_paths({"/public", "/health"})};
+
+    LT_CHECK(impl_of(ws).should_skip_auth("/public"));
+    LT_CHECK(impl_of(ws).should_skip_auth("/health"));
+    LT_CHECK(!impl_of(ws).should_skip_auth("/api"));
+LT_END_AUTO_TEST(canonical_skip_path_still_matches)
+
+// ---------------------------------------------------------------------
+// Wildcard-suffix skip paths ("/public/*") have their prefix
+// normalized too; the wildcard semantics are preserved.
+// ---------------------------------------------------------------------
+LT_BEGIN_AUTO_TEST(auth_skip_normalize_suite,
+                   wildcard_suffix_skip_path_normalizes_prefix)
+    ht::webserver ws{ht::create_webserver(8080)
+        .start_method(ht::http::http_utils::INTERNAL_SELECT)
+        .auth_skip_paths({"/public/*"})};
+
+    LT_CHECK(impl_of(ws).should_skip_auth("/public/foo"));
+    LT_CHECK(impl_of(ws).should_skip_auth("/public/foo/bar"));
+    LT_CHECK(!impl_of(ws).should_skip_auth("/private/foo"));
+LT_END_AUTO_TEST(wildcard_suffix_skip_path_normalizes_prefix)
+
+// ---------------------------------------------------------------------
+// Empty skip list early-out: no auth_skip_paths configured, so
+// should_skip_auth must return false without touching the per-request
+// normalize machinery.  Behavior pin only -- the perf win is visible
+// in the bench, not here.
+// ---------------------------------------------------------------------
+LT_BEGIN_AUTO_TEST(auth_skip_normalize_suite,
+                   empty_skip_list_returns_false_for_any_path)
+    ht::webserver ws{ht::create_webserver(8080)
+        .start_method(ht::http::http_utils::INTERNAL_SELECT)};
+
+    LT_CHECK(!impl_of(ws).should_skip_auth("/anywhere"));
+    LT_CHECK(!impl_of(ws).should_skip_auth("/"));
+    LT_CHECK(!impl_of(ws).should_skip_auth(""));
+LT_END_AUTO_TEST(empty_skip_list_returns_false_for_any_path)
+
+LT_BEGIN_AUTO_TEST_ENV()
+    AUTORUN_TESTS()
+LT_END_AUTO_TEST_ENV()