Merge TASK-194: Complete public TLS profiles, rotation and ACME selection

Author: etr

Makefile.am

@@ -559,3 +559,5 @@ EXTRA_DIST += docs/v2-to-v3-migration.md docs/v3-api.md docs/task-183-migration-
 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
+
+EXTRA_DIST += scripts/lib/v3_public_tls_profiles.py test/installed/v3_tls_profiles.cpp test/installed/v3_tls_client.cpp

docs/external-psk-lookup-contract.md

@@ -42,8 +42,10 @@ Historical seams characterized at TASK-134's base `d1349b59`, before TASK-135:
 
 ## Callback shape
 
-The installed provider-neutral types are in `detail/tls_psk.hpp` (internal,
-excluded from installed public headers). The callback shape is:
+The original private types remain in `detail/tls_psk.hpp`. TASK-194 exposes the
+provider-neutral public equivalents in `server/tls_credentials.hpp`: `tls_psk_version`,
+`tls_psk_context`, `tls_psk_result`, `tls_psk_lookup` and move-only `tls_psk_key`.
+The private callback shape is:
 
 ```cpp
 enum class psk_tls_version { tls12, tls13 };
@@ -208,7 +210,7 @@ late-result wiping and retirement against this contract. Local acceptance is rec
 `tls_psk_runtime_options` defaults to two handshake workers and two lookup
 workers, with sixteen additional outstanding slots on each lane and a five
 second handshake timeout. Validation permits 1–64 workers per lane, 0–65536
-additional slots and a timeout greater than zero and at most ten minutes.
+additional slots and a timeout greater than zero and at most 24 hours.
 Admission counts running and queued jobs together (`workers + queue`); a reserved
 worker slot may still be queued while its worker wakes. Running callbacks never
 exceed the worker count. Queued and running jobs share one absolute deadline.
@@ -258,3 +260,28 @@ authentication, binary TLS 1.3 identities, SNI/mixed profiles, replacement,
 0-RTT rejection, admission, timeouts, cancellation/destruction, late-key wiping,
 local TLS-on/off gates and fully instrumented local sanitizer runs. BSD, Windows
 and other nonlocal checks remain assigned to CI and the v3 PR.
+
+## Public runtime ownership
+
+`server::tls_psk_runtime::create(options, output)` reports typed configuration or
+availability failures and preserves output on failure. Public options configure
+only the callback lane: 1–64 workers and 0–65536 additional queued slots. The
+native server separately owns bounded provider steps. Publication retains the
+public runtime and copied callable; repeated generations never replenish capacity
+occupied by an unreturned callback. Caller handles and PEM buffers may die while
+listeners/generations retain their owners. Callback references last one invocation.
+
+`request_stop()` requests cancellation without joining; call it before
+`wait_retired(deadline)`. Incomplete retirement returns `timeout`; self-wait returns
+`would_deadlock`. Runtime destruction never waits for arbitrary callback code.
+Owned captured state lasts through actual callback retirement, including late
+results after connection timeout/cancellation. Native server stop never implicitly
+stops a shared application lookup runtime. Stop handlers must remain nonblocking.
+The private runtime retains its existing scheduling implementation and defaults;
+the current private timeout ceiling is 24 hours, matching `server::max_timeout`.
+
+Both public TLS builds expose the same declarations and secure key operations.
+TLS-off runtime creation and credential/ACME operations return `not_supported`.
+The installed public matrix adds real TCP independent TLS1.2/1.3 PSK, binary
+identity, negative authentication, early-data, blocked-callback and retirement
+witnesses; private memory-BIO/provider suites remain supporting evidence.

docs/native-tls-build.md

@@ -26,8 +26,8 @@ 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. 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
+the provider is distinct from availability of TCP TLS, HTTP/2, and HTTP/3. TCP TLS is available in TLS-on builds for certificate, initial mTLS and eligible
+external-PSK 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.
@@ -58,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 H2/H3 listeners and expanded TLS profiles remain later-task work.
+and the v3 PR; public H2/H3 listeners remain later-task work.
 
 Run the clean installed-consumer matrix from a bootstrapped source checkout:
 
@@ -163,12 +163,10 @@ requests before binding. Every endpoint binds before admission activates; failur
 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.
+TASK-193 supplies public certificate/default/SNI configuration and generation
+lifetime safety. TASK-194 extends the same store to initial mTLS, HTTP/1 external
+PSK and ACME, and exercises live listener rotation through installed packages.
+Private profile suites remain supporting protocol evidence.
 
 Run the installed certificate capability matrix after staging a package:
 
@@ -186,3 +184,70 @@ 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.
+
+## Public initial client authentication, external PSK and ACME
+
+`server/tls_credentials.hpp` supplies provider-neutral host trust, authentication,
+owned keys and a bounded callback runtime. Set `tls_host_credentials::profile`
+and the listener's `options.tls().profile` consistently. For mTLS, set
+`trust_roots_pem` to the client CA roots. `mutual_tls` defaults to `require`;
+explicit `client_auth.mode = tls_client_certificate_mode::request` verifies any
+presented chain while allowing anonymous peers. `require` refuses absent or
+untrusted client chains. Set the same resolved mode on the listener. Authentication
+is initial-handshake only. Exchanges and request hooks own immutable verified
+leaf identity, fingerprint and validity metadata.
+
+A bound store rejects publication that contradicts any active listener's profile,
+resolved mode or enabled HTTP/1 policy. Bind registration and publication share
+one private writer transaction; a concurrent writer cannot downgrade authentication
+between validation and admission. Compatible listeners hold independent leases;
+stopping admission releases that listener's lease. Already accepted sessions keep
+their pinned generation. Invalid material and policy leave the active generation
+unchanged. Mixed profiles in one store cannot attach to a listener configured for
+one contradictory profile.
+
+For HTTP/1 external PSK, create `tls_psk_runtime` with finite `lookup_workers`
+(1–64) and `lookup_queue` (0–65536), supply `tls_psk_config::lookup` and its shared
+runtime, and set the host/listener profile to `external_psk`. Certificate/key/trust
+material must be empty for PSK. Return `tls_psk_result` with an accepted status and
+move-only `tls_psk_key` built from owned bytes. Identity/context references last
+one invocation; retain copies when needed. TLS1.3 identities are binary; TLS1.2
+exposes textual NUL-terminated identities. The context owns canonical selected
+host, generation identity, absolute monotonic deadline and cancellation token.
+Callbacks can run concurrently and must synchronize mutable captured state.
+
+The lookup runtime is distinct from native server-owned provider workers. It
+counts active and queued callbacks together; ignored cancellation retains a slot
+until callback return, including across rotation. Late keys are wiped and never
+route requests. `request_stop()` is nonblocking. Call it before
+`wait_retired(absolute_deadline)` to observe actual callback retirement: timeout
+means application work remains; waiting from that runtime's callback returns
+`would_deadlock`. Destruction requests stop without joining arbitrary application
+code. Captured resources must be owned through retirement. A native handler's
+`request_stop()` or `begin_drain()` does not stop a shared application runtime;
+one server stopping cannot disable another server using that runtime.
+
+Normal certificate sessions have a host/context namespace. Same-generation
+resumption may reuse authentication; replacements create fresh contexts, so an
+old session cannot bypass the replacement or cross host/store identity. External
+PSK authentication differs from ticket resumption: PSK profiles and ACME disable
+tickets/session caching. Every ACME handshake sends its challenge certificate.
+Application 0-RTT remains disabled; early requests never enter routes.
+
+`tls_credentials::publish_acme(tls_acme_challenge)` validates a supplied challenge
+certificate/key, canonical DNS host, 32-byte authorization digest and future
+absolute system-clock expiry no later than certificate expiry. The certificate
+must have exactly one matching DNS SAN and one critical ACME authorization digest
+extension. `remove_acme(host)` is canonical and idempotent. Publication validation
+is independent of listener port. Selection requires matching exact canonical SNI,
+sole `acme-tls/1`, TCP, and the socket's actual local port443. Other ALPN offers and
+ordinary HTTP use normal credentials; challenge sessions cannot route HTTP. This
+API performs no certificate issuance or challenge-client orchestration.
+
+TLS-off installs identical declarations and secure key operations, with typed
+`not_supported` for credential/runtime/ACME availability. Public H2/H3 listeners
+remain later-task work; external PSK remains HTTP/1-only. The installed rotation
+example takes `certificate-directory managed|external port`, opens a real public
+listener and accepts `replace`, `invalid` and `stop` on stdin. Its independent
+installed witness holds a usable connection across rotation and validates the
+new certificate plus rejected-publication preservation.

docs/v2-to-v3-migration.md

@@ -160,11 +160,14 @@ 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. 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)
+selects provider/profile policy. Public host values accept initial mTLS trust and
+request/require mode, or bounded external PSK for HTTP/1. The application owns the
+shared lookup runtime through actual callback retirement; server stop requests
+cancellation without joining application code. Public ACME publication/removal
+uses application-supplied material and exact SNI/sole `acme-tls/1` on TCP443.
+Post-handshake auth remains unavailable; see the [public TLS lifetime contract](native-tls-build.md).
+
+The [public listener rotation example](../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
@@ -180,6 +183,8 @@ 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.
+Managed and external loops support the same HTTP/1 routes. TASK-194 extends
+installed witnesses to mTLS/PSK/ACME and live listener rotation. H2/H3 public
+listeners remain subsequent repair tasks; unsupported combinations retain typed
+pre-bind outcomes. TLS-off exposes the same declarations and typed unavailable
+credential/runtime operations.

docs/v3-api.md

@@ -10,8 +10,9 @@ There is no v2 source/ABI compatibility shim.
 \ref httpserver::server::server_options defines listener endpoints, protocol
 selection, budgets, timeouts, worker concurrency and loop ownership.
 \ref httpserver::server::native_server validates before binding and owns shutdown.
-Plaintext HTTP/1.0 and HTTP/1.1 listeners are available. Public TLS/H2/H3 listeners
-return not_supported before binding, even when semantic validation succeeds.
+Plaintext HTTP/1.0 and HTTP/1.1 listeners are available. TLS-on builds also serve
+public HTTP/1 certificate, initial mTLS and eligible external-PSK listeners.
+Public H2/H3 listeners still return not_supported before binding.
 Provider availability from \ref httpserver::query_features is a separate fact.
 
 \include v3_protocol_options.cpp
@@ -67,8 +68,18 @@ counted work returns would_deadlock. \ref httpserver::http::outcome and
 \ref httpserver::auth::basic_auth_policy, \ref httpserver::auth::digest_auth_policy,
 and the bounded forms APIs replace the corresponding v2 conveniences.
 
-Certificate rotation has no public installation API. The separately labeled
-repository-internal demonstration at test/examples/v3_tls_rotation.cpp uses an
-uninstalled private header. It is not included as a public API example here.
+\ref httpserver::server::tls_credentials copies share an immutable-generation
+store attached to each TLS listener. replace validates before atomic publication;
+selected connections retain their generation, and incompatible bound-policy
+changes reject. Public host values carry mTLS trust/request/require policy or
+external-PSK lookup configuration. The application owns the bounded shared lookup
+runtime through actual callback retirement; native stop never joins application
+lookups. Public ACME publish/remove accepts application-supplied material and
+selects only exact SNI plus sole acme-tls/1 on authentic TCP443.
+
+The installed public listener example at test/examples/v3_tls_rotation.cpp serves
+requests across valid/rejected live replacement. Read the [TLS usage and lifetime
+contract](https://github.com/etr/libhttpserver/blob/v3/docs/native-tls-build.md).
+TLS-off retains the same declarations and typed unavailable operations.
 The [TASK-179 audit](https://github.com/etr/libhttpserver/blob/v3/docs/task-179-behavior-parity.md) distinguishes semantic,
 frame, provider and private TCP/TLS/QUIC observations.