TASK-193: Serve public certificate TLS through native HTTP/1 listeners

Install provider-neutral shared credentials backed by atomic registry snapshots. Pin accepted generations through bounded handshake and raw/provider retirement, retain one native connection owner, propagate real TLS metadata, and make multi-listener binding transactional.

Verified behavioral RED and final normal/ASan/UBSan/TSan TLS-off/on gates: 113 programs, 1711 cases and 26962 checks without failures or skips. All 24 installed public shared/static managed/external cells pass; TLS-on cells verify 23 independent-client scenarios. Strict package/declaration audits, plaintext package traffic, check-local, distribution manifests, lint and 61 tooling contracts pass. Preserve H2/H3 and expanded profile rejection; nonlocal execution remains CI/v3-PR owned.

Author: etr

.gitignore

@@ -140,3 +140,5 @@ __pycache__/
 .debug/
 
 !test/integ/native_websocket_regression.py
+
+!scripts/check-v3-public-tls.py

Makefile.am

@@ -557,3 +557,5 @@ EXTRA_DIST += scripts/test-v3-installed-consumer.py scripts/test-v3-package-work
 EXTRA_DIST += docs/v2-to-v3-migration.md docs/v3-api.md docs/task-183-migration-evidence.md examples/README.md
 
 EXTRA_DIST += scripts/audit-v3-native-linkage.sh scripts/test-v3-cutover.py scripts/check-v3-runtime-coexistence.py docs/task-184-cutover-evidence.md
+
+EXTRA_DIST += scripts/check-v3-public-tls.py test/installed/v3_tls_consumer.cpp

docs/native-tls-build.md

@@ -26,10 +26,11 @@ cross builds must run the smoke on the target in CI.
 
 `<httpserver/features.hpp>` exposes the same compiled `query_features()` declaration
 in both builds, without backend headers or configuration macros. Availability of
-the provider is distinct from availability of TCP TLS, HTTP/2, and HTTP/3. These
-transports remain unavailable until their owning tasks implement them. Native
-`listen()` returns `not_supported` before binding any endpoint for a configuration
-requesting those transports; `server_options::validate()` remains semantic.
+the provider is distinct from availability of TCP TLS, HTTP/2, and HTTP/3. TCP TLS is available in TLS-on builds for certificate-authenticated HTTP/1.0
+and HTTP/1.1 in both managed and external modes. HTTP/2 and HTTP/3 remain
+unavailable until their owning tasks implement public listeners. `listen()`
+rejects unsupported protocol/profile requests before binding;
+`server_options::validate()` remains semantic.
 
 Run `make check-v3-native-linkage` in each mode. It inspects the executable behind
 any libtool wrapper and the native archive, fails closed on missing artifacts or
@@ -57,7 +58,7 @@ checks configure/build provenance, installed metadata, effective public headers,
 recursive dependency graphs and all static-archive members, including unused
 members. Provider build proof remains distinct from encrypted listener or QUIC
 interoperability proof. Nonlocal BSD, macOS and Windows execution belongs to CI
-and the v3 PR; public TLS/H2/H3 listeners and credential installation remain gaps.
+and the v3 PR; public H2/H3 listeners and expanded TLS profiles remain later-task work.
 
 Run the clean installed-consumer matrix from a bootstrapped source checkout:
 
@@ -72,7 +73,7 @@ Repeat `--prerequisite-prefix` for separate prerequisite library prefixes and
 (such as macOS SDK zlib metadata). The runner refuses an existing output path,
 clears ambient consumer include/link flags, and isolates pkg-config discovery.
 It independently builds and installs both modes, compiles shared and static
-consumers, checks provider availability and the typed TLS-listener rejection,
+consumers, checks provider/TCP TLS availability and typed missing-credential outcomes,
 serves bounded plaintext traffic, and compares installed header file sets and
 effective declarations. `make check-v3-installed-consumer
 INSTALL_AUDIT_ARGS='...'` invokes the same standalone matrix.
@@ -89,8 +90,8 @@ See [TASK-148 local receipts and limitations](task-148-installed-consumer-eviden
 
 TASK-130 establishes a private nonblocking TCP TLS adapter over owned raw I/O
 operations. Its [local evidence](task-130-tls-io-evidence.md) covers the adapter
-and independent loopback peers. Public TCP TLS availability remains false until
-listeners have a usable credential/configuration path.
+and independent loopback peers. TASK-193 composes this adapter and the existing credential registry into the
+public native TCP listener.
 
 ## Installed four-platform package gate
 
@@ -103,3 +104,85 @@ public transport rejection behavior, and nonlocal CI ownership. The opt-in
 runner requires a genuine selected shared OpenSSL provider satisfying configure;
 CI prepares checksummed OpenSSL 3.5.9. Policy and orchestration fixture tests run
 through `make check-v3-installed-package-fixtures`.
+
+
+## Public certificate credentials and native TCP TLS
+
+```cpp
+#include <httpserver.hpp>
+#include <memory>
+
+// certificate_pem includes the leaf followed by its intermediate chain;
+// private_key_pem contains the matching unencrypted PEM private key.
+auto credentials = std::make_shared<httpserver::server::tls_credentials>();
+httpserver::server::tls_credentials_config material;
+material.hosts.push_back({"www.example.com", certificate_pem, private_key_pem,
+                          {"http/1.1"}});
+auto installed = credentials->replace(material);
+if (!installed.ok()) { /* handle the typed outcome */ }
+httpserver::server::server_options options;
+options.tls().provider = httpserver::server::tls_provider::system_default;
+options.tls().profile = httpserver::server::tls_profile::certificates;
+options.add_listener({"127.0.0.1", 8443, true, credentials});
+httpserver::server::native_server server(options);
+// Register ordinary routes, then check server.listen().
+```
+
+`tls_credentials` copies share a store. Each successful `replace(config)` builds
+and validates a complete immutable generation before atomic publication. Rejected
+material (invalid host/default index, malformed PEM, mismatched key or unsupported
+ALPN) leaves the previous publication active. The store retains provider objects,
+not the PEM input. Caller buffers and handles may die after configuration; the
+listener retains the store and accepted handshakes/sessions pin their generation
+through retiring I/O completions. No global credential store exists.
+
+Host names use exact canonical DNS matching, with case folding and a final dot
+removed. Unknown or absent SNI selects `default_host` (zero by default). Each
+listener has its own explicit store; sharing is intentional only when the same
+store is assigned. ALPN may contain `http/1.1` or be empty for ordinary HTTP/1
+fallback. A listener with HTTP/1.1 disabled must initially use empty ALPN. Later
+publication cannot negotiate a disabled ALPN; wire requests for a disabled H1
+version are rejected before routing. `exchange::tls()` and request hook contexts
+carry library-owned immutable authenticated peer metadata; plaintext uses null,
+and anonymous certificate TLS has no client certificate identity.
+
+Native admission reserves its connection budget before constructing TLS state.
+Handshakes share the existing bounded provider lane and use an absolute
+`timeouts().handshake` deadline. A stalled peer cannot reach an H1 reader or
+handler. Drain cancels pending handshakes and stops new admission; established
+H1 exchanges retain ordinary drain semantics. `request_stop()` remains safe from
+handlers; call blocking `stop()` from the coordinator. External hosts must keep
+advancing published readiness, wake and timer deadlines, including empty dispatch
+when only a deadline is due (the same contract as plaintext).
+
+Pure structural option errors take precedence in both loop modes. An unavailable
+build/protocol/profile returns `not_supported`. TLS-on missing/unpublished
+credentials or incompatible ALPN return `invalid_argument`. TLS-off exposes the
+same declarations, returns `not_supported` from `replace` and rejects valid TLS
+requests before binding. Every endpoint binds before admission activates; failure
+on a later bind synchronously releases earlier endpoints and reports no bound
+ports. A bind failure is terminal for that server instance.
+
+TASK-193 supports public certificate/default/SNI configuration and replacement
+lifetime safety. Public mTLS, external PSK and ACME operations remain TASK-194
+work; native requests for unsupported profiles reject honestly. Private profile
+suites continue to test their existing support. The rotation example now uses the
+public store and demonstrates typed publication outcomes; expanded installed
+profile/rotation examples belong to TASK-194.
+
+Run the installed certificate capability matrix after staging a package:
+
+```sh
+python3 scripts/check-v3-public-tls.py --prefix /installed/package \
+  --provider-prefix /selected/openssl --build /identified/build \
+  --tls yes --output /fresh/public-tls-receipts
+```
+
+The same source compiles in TLS-off and TLS-on lanes. The runner checks staged
+public header origins, pkg-config identity, shared/static linkage and dependency
+graphs; independent Python SSL clients verify chains, named hosts, SNI/default
+certificates, ALPN, H1 status/version/body and lifecycle behavior in both loops.
+Unknown/absent SNI checks verify the chain and compare the selected certificate
+with its independently hostname-verified named certificate. TLS-off runs the same
+configuration code and requires typed unavailability. Nonlocal platform checks
+remain CI/v3-PR owned.

docs/v2-to-v3-migration.md

@@ -22,16 +22,17 @@ TCP/TLS/QUIC transport evidence; these are different kinds of proof.
 | --- | --- | --- |
 | Plaintext HTTP/1.0 and HTTP/1.1 | Managed and external listeners available | `v3_routes`, `v3_external_event_loop` |
 | HTTP/1.1 WebSocket Upgrade | Coroutine API available without legacy WS build flags | `v3_websocket_echo` |
-| TLS, HTTP/2 and HTTP/3 listeners | `native_server::listen()` returns `not_supported` before binding any endpoint | `v3_protocol_options` |
+| Certificate TCP TLS HTTP/1 listeners | Public credential store, managed/external listeners in TLS-on builds | `test/installed/v3_tls_consumer.cpp` |
+| HTTP/2 and HTTP/3 listeners | `native_server::listen()` returns `not_supported` before binding any endpoint | `v3_protocol_options` |
 | Common HTTP/1.1, HTTP/2, HTTP/3 handlers | Semantic exchange contract exercised for each version | `test/unit/v3_examples_test.cpp` |
-| Certificate rotation | Private registry only; no public credential installation or rotation API | `test/examples/v3_tls_rotation.cpp`, TLS rotation tests |
+| Certificate rotation | Public `tls_credentials::replace`, immutable accepted selections | `test/examples/v3_tls_rotation.cpp`, installed TLS runner |
 
 `server_options::validate()` checks configuration semantics, not transport
 availability. A TLS-on build can validate certificate-profile H2/H3 options and
 still refuse `listen()`. `query_features()` distinguishes provider availability
-from public transports. Mixed plaintext/TLS configurations are also rejected
-before binding. The private audit's encrypted handshakes and Extended CONNECT
-journeys do not make public encrypted listeners available.
+from public transports. Valid credential-backed mixed plaintext/TLS listeners
+serve HTTP/1; missing credentials reject atomically. Private H2/H3 and Extended
+CONNECT evidence remains distinct from public protocol availability.
 
 ## Server construction and routing
 
@@ -157,20 +158,28 @@ exclusions, not failed parity observations.
 
 Native TLS selects optional OpenSSL at build time with `--enable-v3-tls`; the
 current build gate requires stable OpenSSL **3.5.x patch 9 or later** and its QUIC
-TLS callbacks. v2 GnuTLS server options and PSK callbacks have no native public
-credential-installation mapping. `server_options::tls()` selects semantic
-provider/profile options. External PSK is restricted to HTTP/1; enabling H2/H3
-with that profile returns `not_supported`. Initial-handshake client auth supports
-optional verified or required certificates; post-handshake auth is unavailable.
-
-The [private rotation demonstration](../test/examples/v3_tls_rotation.cpp) uses
-`detail::tls_credentials_registry::replace()` and `acquire()`: successful
-publication replaces the active generation, old selections retain their contexts,
-and failed replacement leaves the active generation unchanged. Its private header
-requires `HTTPSERVER_COMPILATION` and is not installed. The independent verified
-TLS peers in [tls_credentials_rotation_test.cpp](../test/unit/tls_credentials_rotation_test.cpp)
-prove established sessions continue after replacement. This example is
-repository-internal and cannot be compiled against installed public headers.
+TLS callbacks. Public certificate values go through `server::tls_credentials`;
+`listener_options::credentials` associates the store. `server_options::tls()`
+selects provider/profile policy. Public mTLS/PSK/ACME scenarios remain TASK-194
+work; their native listener requests reject honestly. Private initial-handshake
+client-auth/PSK suites retain existing coverage; post-handshake auth is unavailable.
+
+The [public publication demonstration](../test/examples/v3_tls_rotation.cpp)
+uses `server::tls_credentials::replace()`: successful publication replaces the
+active generation, accepted sessions retain their contexts, and failed
+replacement leaves the active publication unchanged. It uses only installed
+public headers. `check-v3-public-tls.py` verifies selected certificates and held
+handshakes/connections across replacement through installed shared/static
+libraries. The private rotation suite remains supporting lifetime evidence.
 
 BSD, Windows and other nonlocal runs belong to CI and the v3 PR; the
 [TASK-183 local evidence](task-183-migration-evidence.md) records what ran locally.
+
+
+TASK-193 adds public certificate TCP TLS through
+[`server::tls_credentials`](native-tls-build.md#public-certificate-credentials-and-native-tcp-tls).
+Associate a shared store with each TLS listener and publish PEM values with
+`replace`; accepted sessions retain immutable selections during replacement.
+Managed and external loops support the same HTTP/1 routes. Public mTLS/PSK/ACME
+profiles and H2/H3 listeners remain subsequent repair tasks; unsupported requests
+still return typed pre-bind outcomes.

scripts/audit-v3-native-linkage.sh

@@ -60,6 +60,7 @@ src/httpserver/concurrency/cancellation.hpp
 src/httpserver/concurrency/resume_signal.hpp
 src/httpserver/server/budgets.hpp
 src/httpserver/server/options.hpp
+src/httpserver/server/tls_credentials.hpp
 src/httpserver/server/routes.hpp
 src/httpserver/server/configuration.hpp
 src/httpserver/server/server.hpp
@@ -81,6 +82,7 @@ src/httpserver/websocket/session.hpp
 
 V3CORE_SOURCES="
 src/detail/features.cpp
+src/detail/server_tls_credentials.cpp
 src/detail/io_operation.cpp
 src/detail/io_udp_backend.cpp
 src/detail/quic_invariant_header.cpp

scripts/check-v3-installed-consumer.py

@@ -99,6 +99,9 @@ def package_lane(args, source, output, mode, inventory):
         private_libraries = libraries + (shlex.split(env['V3_TLS_LIBS']) if mode == 'yes' else [])
         integrations[linkage] = run_suites(inventory, platform.system(), mode, linkage, private_dir, prefix,
                                           source, build, args.compiler, cflags, private_libraries, command, runtime_env, audit)
+    command([sys.executable, str(source / 'scripts/check-v3-public-tls.py'), '--prefix', str(prefix),
+             '--provider-prefix', str(args.provider_prefix), '--build', str(build), '--tls', mode,
+             '--compiler', args.compiler, '--output', str(lane / 'public-tls')], source, runtime_env)
     receipt = audit.audit(prefix, build, consumer_dir / ('v3_package_consumer' + suffix), mode,
                           'strict', args.provider_prefix, args.compiler)
     receipt.update(consumer_metadata=metadata, public=public, integrations=integrations)