feat(tls): add a libssl TLS transport and an https:// HTTP/1.1 stack

HTTP/1.1 was plaintext-only, which left `https://` to either an HTTP/3
listener or a terminating proxy in front. Neither helps the callers this
stack exists for — curl scripts, CI tooling, old proxies — so wrap the
transport in libssl instead.

Two new partitions:

  :Stream  a ByteStream with per-call deadlines on both directions, plus
           the plaintext socket implementation. The HTTP/1.1 client and
           listener now hold a ByteStream& and never learn which
           transport they have, which is what lets one code path serve
           both schemes.
  :TLS     TLSContext/TLSStream over OpenSSL 3, with credentials for both
           roles: chain and hostname verification on by default, private
           trust anchors, client certificates, mutual TLS, ALPN, and an
           in-process self-signed certificate for development.

Both descriptors go non-blocking and every read and write is driven by
poll() against a deadline. That is required for TLS — a blocking
descriptor cannot express a handshake timeout — and it means a plaintext
write can now time out too, instead of parking forever against a peer
that stopped reading.

ClientHTTP1 and ListenerHTTP1 gain credential-taking constructors; the
existing ones still speak http://. The listener handshakes on the
connection's own thread, so a peer that stalls mid-handshake costs one
thread rather than the accept loop, and a failed handshake is counted
rather than logged — on a public port it is ordinary traffic.

MessageParser gains SetDefaultScheme so origin-form targets report the
scheme the transport actually used; handlers shared with ListenerHTTP now
see the same "https" they would over HTTP/3.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

implementations/Crafter.Network-ClientHTTP1.cpp

@@ -2,8 +2,6 @@
 //SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®
 
 module;
-#include <poll.h>
-#include <sys/socket.h>
 #include <cerrno>
 
 module Crafter.Network:ClientHTTP1_impl;
@@ -11,41 +9,19 @@ import :ClientHTTP1;
 import :ClientTCP;
 import :HTTP;
 import :HTTP1;
+import :Stream;
+import :TLS;
 import Crafter.Thread;
 import std;
 
 using namespace Crafter;
 
 namespace {
-    // Read whatever is available, waiting at most `timeout`. Returns 0 on a
-    // clean close by the peer. ClientTCP::RecieveSync() can't express a
-    // timeout — and a server that accepts the connection and then says
-    // nothing would hang Send() forever — so the read is done here.
-    std::size_t ReadSome(int socketid, char* buffer, std::size_t size,
-                         std::chrono::milliseconds timeout) {
-        for (;;) {
-            pollfd pfd{ .fd = socketid, .events = POLLIN, .revents = 0 };
-            const int ready = poll(&pfd, 1, static_cast<int>(timeout.count()));
-            if (ready < 0) {
-                if (errno == EINTR) continue;
-                throw std::runtime_error(std::string("poll failed: ") + std::strerror(errno));
-            }
-            if (ready == 0) throw std::runtime_error("timed out waiting for the response");
-
-            const auto read = recv(socketid, buffer, size, 0);
-            if (read < 0) {
-                if (errno == EINTR) continue;
-                throw std::runtime_error(std::string("recv failed: ") + std::strerror(errno));
-            }
-            return static_cast<std::size_t>(read);
-        }
-    }
-
     // Host header value. The port is elided when it is the scheme default,
     // which is what every other HTTP/1.1 client on the wire does and what
     // virtual-host matching on the far side tends to expect.
-    std::string DefaultAuthority(const std::string& host, std::uint16_t port) {
-        if (port == 80) return host;
+    std::string DefaultAuthority(const std::string& host, std::uint16_t port, bool secure) {
+        if (port == (secure ? 443 : 80)) return host;
         return host + ":" + std::to_string(port);
     }
 }
@@ -53,13 +29,34 @@ namespace {
 struct ClientHTTP1::Impl {
     std::string host;
     std::uint16_t port;
+    // Null for plaintext; shared by every connection this client dials, so the
+    // trust store is parsed once rather than per redial.
+    std::shared_ptr<TLSContext> tls;
     std::unique_ptr<ClientTCP> tcp;
+    // Sits on top of `tcp` and must therefore be destroyed before it.
+    std::unique_ptr<ByteStream> stream;
+    std::string protocol;
 
-    void Connect() {
+    void Connect(std::chrono::milliseconds handshakeTimeout) {
         tcp = std::make_unique<ClientTCP>(host, port);
+        try {
+            if (tls) {
+                stream = TLSStream::Connect(tcp->socketid, tls, host, handshakeTimeout);
+            } else {
+                stream = std::make_unique<PlainStream>(tcp->socketid);
+            }
+        } catch (...) {
+            // A half-built connection must not be left pooled: the next Send()
+            // would treat it as reusable and read from a socket with no
+            // session on it.
+            tcp.reset();
+            throw;
+        }
+        protocol = std::string(stream->Protocol());
     }
 
     void Close() {
+        stream.reset();
         tcp.reset();
     }
 
@@ -69,14 +66,19 @@ struct ClientHTTP1::Impl {
     HTTPResponse Exchange(const std::string& wire, std::string_view method,
                           const HTTP1::MessageLimits& limits,
                           std::chrono::milliseconds timeout, bool& received) {
-        tcp->Send(wire.data(), static_cast<std::uint32_t>(wire.size()));
+        stream->Write(wire.data(), wire.size(), timeout);
 
         HTTP1::MessageParser parser(HTTP1::MessageKind::Response, limits);
         parser.SetRequestMethod(method);
         std::vector<char> chunk(16 * 1024);
         while (!parser.Complete()) {
-            const std::size_t read = ReadSome(tcp->socketid, chunk.data(), chunk.size(), timeout);
-            if (read == 0) {
+            std::size_t read = 0;
+            const StreamStatus status = stream->ReadSome(chunk.data(), chunk.size(),
+                                                        timeout, read);
+            if (status == StreamStatus::TimedOut) {
+                throw std::runtime_error("timed out waiting for the response");
+            }
+            if (status == StreamStatus::Closed) {
                 // Peer closed. Completes a response framed by close;
                 // anything else throws out of Finish().
                 parser.Finish();
@@ -100,6 +102,17 @@ ClientHTTP1::ClientHTTP1(const char* host, std::uint16_t port)
 ClientHTTP1::ClientHTTP1(std::string host, std::uint16_t port)
     : ClientHTTP1(host.c_str(), port) {}
 
+ClientHTTP1::ClientHTTP1(const char* host, std::uint16_t port, TLSClientCredentials credentials)
+    : host(host), port(port), impl(std::make_unique<Impl>(std::string(host), port)) {
+    // Built here rather than on first Send() so bad credentials — an
+    // unreadable certificate, a trust anchor that is not a certificate —
+    // surface at construction, where the caller is still looking.
+    impl->tls = TLSContext::Client(credentials);
+}
+
+ClientHTTP1::ClientHTTP1(std::string host, std::uint16_t port, TLSClientCredentials credentials)
+    : ClientHTTP1(host.c_str(), port, std::move(credentials)) {}
+
 ClientHTTP1::ClientHTTP1(ClientHTTP1&&) noexcept = default;
 ClientHTTP1::~ClientHTTP1() = default;
 
@@ -107,13 +120,23 @@ bool ClientHTTP1::Connected() const noexcept {
     return impl && impl->tcp != nullptr;
 }
 
+bool ClientHTTP1::Secure() const noexcept {
+    return impl && impl->tls != nullptr;
+}
+
+std::string_view ClientHTTP1::Protocol() const noexcept {
+    return impl ? std::string_view(impl->protocol) : std::string_view();
+}
+
 void ClientHTTP1::Disconnect() {
     if (impl) impl->Close();
 }
 
 HTTPResponse ClientHTTP1::Send(const HTTPRequest& request) {
     HTTPRequest prepared = request;
-    if (prepared.authority.empty()) prepared.authority = DefaultAuthority(host, port);
+    if (prepared.authority.empty()) {
+        prepared.authority = DefaultAuthority(host, port, Secure());
+    }
     const std::string wire = HTTP1::SerializeRequest(prepared);
     const std::string method = prepared.method.empty() ? std::string("GET") : prepared.method;
 
@@ -123,7 +146,7 @@ HTTPResponse ClientHTTP1::Send(const HTTPRequest& request) {
     // read fails. Nothing is replayed once a response byte has arrived.
     for (int attempt = 0;; ++attempt) {
         const bool reused = impl->tcp != nullptr;
-        if (!reused) impl->Connect();
+        if (!reused) impl->Connect(handshakeTimeout);
 
         bool received = false;
         try {

implementations/Crafter.Network-ListenerHTTP1.cpp

@@ -2,7 +2,6 @@
 //SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®
 
 module;
-#include <poll.h>
 #include <sys/socket.h>
 #include <cerrno>
 
@@ -12,39 +11,12 @@ import :ListenerTCP;
 import :ClientTCP;
 import :HTTP;
 import :HTTP1;
+import :Stream;
+import :TLS;
 import std;
 
 using namespace Crafter;
 
-namespace {
-    enum class ReadStatus { Data, Closed, TimedOut };
-
-    // Wait for readable data with a deadline, so an idle or stalled peer
-    // releases the connection thread instead of holding it forever.
-    ReadStatus ReadSome(int socketid, char* buffer, std::size_t size,
-                        std::chrono::milliseconds timeout, std::size_t& read) {
-        read = 0;
-        for (;;) {
-            pollfd pfd{ .fd = socketid, .events = POLLIN, .revents = 0 };
-            const int ready = poll(&pfd, 1, static_cast<int>(timeout.count()));
-            if (ready < 0) {
-                if (errno == EINTR) continue;
-                return ReadStatus::Closed;
-            }
-            if (ready == 0) return ReadStatus::TimedOut;
-
-            const auto got = recv(socketid, buffer, size, 0);
-            if (got < 0) {
-                if (errno == EINTR) continue;
-                return ReadStatus::Closed;
-            }
-            if (got == 0) return ReadStatus::Closed;
-            read = static_cast<std::size_t>(got);
-            return ReadStatus::Data;
-        }
-    }
-}
-
 // One accepted connection: the socket, the thread serving it, and a flag
 // the accept loop uses to join finished threads without blocking.
 struct HTTP1Connection {
@@ -56,6 +28,9 @@ struct HTTP1Connection {
 struct ListenerHTTP1::Impl {
     ListenerHTTP1* owner = nullptr;
     std::unique_ptr<ListenerTCP> listener;
+    // Null on a plaintext listener. One context for every connection: the
+    // certificate and trust store are parsed once, at construction.
+    std::shared_ptr<TLSContext> tls;
     std::mutex mutex;
     // Signalled when a connection thread finishes, so Stop() can wait for
     // the last one instead of polling.
@@ -63,6 +38,7 @@ struct ListenerHTTP1::Impl {
     std::vector<std::unique_ptr<HTTP1Connection>> connections;
     std::atomic<bool> running{true};
     std::atomic<std::uint64_t> accepted{0};
+    std::atomic<std::uint64_t> handshakeFailures{0};
 
     // Join threads whose connection has ended. Called from the accept loop
     // with `mutex` held, so a connection is never reaped mid-registration.
@@ -88,7 +64,13 @@ struct ListenerHTTP1::Impl {
         this->accepted.fetch_add(1);
         connection->thread = std::thread([this, pointer] {
             try {
-                Serve(*pointer->client);
+                // The TLS handshake happens here, on the connection's own
+                // thread, so a peer that stalls halfway through it costs one
+                // thread rather than the whole accept loop. The stream is
+                // scoped so it — and its close_notify — go out before the
+                // socket underneath is released below.
+                std::unique_ptr<ByteStream> stream = Wrap(*pointer->client);
+                if (stream) Serve(*stream);
             } catch (...) {
                 // A connection dying must never take the server with it.
             }
@@ -112,8 +94,22 @@ struct ListenerHTTP1::Impl {
         // would abort the process.
     }
 
-    void Send(ClientTCP& client, const std::string& wire) {
-        client.Send(wire.data(), static_cast<std::uint32_t>(wire.size()));
+    // Put the transport on top of the accepted socket. A TLS handshake that
+    // fails is a normal event on a public port — a scanner, a client with no
+    // protocol in common, an untrusted client certificate — so it is counted
+    // and the connection dropped rather than logged or thrown.
+    std::unique_ptr<ByteStream> Wrap(ClientTCP& client) {
+        if (!tls) return std::make_unique<PlainStream>(client.socketid);
+        try {
+            return TLSStream::Accept(client.socketid, tls, owner->handshakeTimeout);
+        } catch (...) {
+            handshakeFailures.fetch_add(1);
+            return nullptr;
+        }
+    }
+
+    void Send(ByteStream& stream, const std::string& wire) {
+        stream.Write(wire.data(), wire.size(), owner->requestTimeout);
     }
 
     HTTPResponse Dispatch(const HTTPRequest& request) {
@@ -138,8 +134,12 @@ struct ListenerHTTP1::Impl {
 
     // Serve one connection until the peer goes away, asks to close, stalls,
     // or sends something we refuse to parse.
-    void Serve(ClientTCP& client) {
+    void Serve(ByteStream& stream) {
         HTTP1::MessageParser parser(HTTP1::MessageKind::Request, owner->limits);
+        // Origin-form targets carry no scheme, so the transport supplies it —
+        // handlers shared with ListenerHTTP see the same "https" they would
+        // over HTTP/3.
+        if (stream.Secure()) parser.SetDefaultScheme("https");
         std::vector<char> chunk(16 * 1024);
         bool keepAlive = true;
 
@@ -151,21 +151,21 @@ struct ListenerHTTP1::Impl {
                     const bool idle = parser.AtMessageBoundary();
                     const auto timeout = idle ? owner->keepAliveTimeout : owner->requestTimeout;
                     std::size_t read = 0;
-                    const ReadStatus status = ReadSome(client.socketid, chunk.data(), chunk.size(),
-                                                       timeout, read);
-                    if (status == ReadStatus::TimedOut) {
+                    const StreamStatus status = stream.ReadSome(chunk.data(), chunk.size(),
+                                                               timeout, read);
+                    if (status == StreamStatus::TimedOut) {
                         // An idle keep-alive connection is simply dropped;
                         // a half-sent request earns a 408 first.
                         if (!idle) {
                             try {
-                                Send(client, HTTP1::SerializeResponse(
+                                Send(stream, HTTP1::SerializeResponse(
                                     CreateResponseHTTP("408", "Request Timeout"),
                                     { .keepAlive = false }));
                             } catch (...) {}
                         }
                         return;
                     }
-                    if (status == ReadStatus::Closed) {
+                    if (status == StreamStatus::Closed) {
                         if (parser.AtMessageBoundary()) return;  // clean end of connection
                         parser.Finish();                          // throws if truncated
                         closed = true;
@@ -174,13 +174,13 @@ struct ListenerHTTP1::Impl {
                     parser.Feed(chunk.data(), read);
                     // The peer is holding its body back until we say go.
                     if (parser.ExpectsContinue()) {
-                        Send(client, HTTP1::SerializeContinue());
+                        Send(stream, HTTP1::SerializeContinue());
                         parser.ContinueSent();
                     }
                 }
             } catch (const HTTP1::HTTP1ProtocolError& error) {
                 try {
-                    Send(client, HTTP1::SerializeResponse(
+                    Send(stream, HTTP1::SerializeResponse(
                         CreateResponseHTTP("400", std::string(error.what())),
                         { .keepAlive = false }));
                 } catch (...) {}
@@ -210,7 +210,7 @@ struct ListenerHTTP1::Impl {
             }
 
             try {
-                Send(client, HTTP1::SerializeResponse(response, {
+                Send(stream, HTTP1::SerializeResponse(response, {
                     .keepAlive = keepAlive,
                     // HTTP/1.0 peers only reuse a connection they were told
                     // stays open.
@@ -252,11 +252,30 @@ ListenerHTTP1::ListenerHTTP1(std::uint16_t port,
     });
 }
 
+ListenerHTTP1::ListenerHTTP1(std::uint16_t port,
+                             std::unordered_map<std::string, std::function<HTTPResponse(const HTTPRequest&)>> routes,
+                             TLSServerCredentials credentials)
+    : ListenerHTTP1(port, std::move(routes), {}, std::move(credentials))
+{}
+
+ListenerHTTP1::ListenerHTTP1(std::uint16_t port,
+                             std::unordered_map<std::string, std::function<HTTPResponse(const HTTPRequest&)>> routes,
+                             std::function<HTTPResponse(const HTTPRequest&)> fallback,
+                             TLSServerCredentials credentials)
+    : ListenerHTTP1(port, std::move(routes), std::move(fallback))
+{
+    // After the plaintext constructor: the socket is already bound and
+    // listening, but nothing has been accepted (Listen() has not run), so
+    // there is no window in which a connection could be served unencrypted.
+    impl->tls = TLSContext::Server(credentials);
+}
+
 ListenerHTTP1::ListenerHTTP1(ListenerHTTP1&& other) noexcept
     : routes(std::move(other.routes))
     , fallback(std::move(other.fallback))
     , keepAliveTimeout(other.keepAliveTimeout)
     , requestTimeout(other.requestTimeout)
+    , handshakeTimeout(other.handshakeTimeout)
     , limits(other.limits)
     , impl(std::move(other.impl))
 {
@@ -313,6 +332,14 @@ std::uint64_t ListenerHTTP1::AcceptedCount() const {
     return impl ? impl->accepted.load() : 0;
 }
 
+std::uint64_t ListenerHTTP1::HandshakeFailureCount() const {
+    return impl ? impl->handshakeFailures.load() : 0;
+}
+
+bool ListenerHTTP1::Secure() const noexcept {
+    return impl && impl->tls != nullptr;
+}
+
 ListenerAsyncHTTP1::ListenerAsyncHTTP1(std::uint16_t port,
                                        std::unordered_map<std::string, std::function<HTTPResponse(const HTTPRequest&)>> routes)
     : listener(port, std::move(routes))
@@ -326,6 +353,21 @@ ListenerAsyncHTTP1::ListenerAsyncHTTP1(std::uint16_t port,
     , thread(&ListenerHTTP1::Listen, &listener)
 {}
 
+ListenerAsyncHTTP1::ListenerAsyncHTTP1(std::uint16_t port,
+                                       std::unordered_map<std::string, std::function<HTTPResponse(const HTTPRequest&)>> routes,
+                                       TLSServerCredentials credentials)
+    : listener(port, std::move(routes), std::move(credentials))
+    , thread(&ListenerHTTP1::Listen, &listener)
+{}
+
+ListenerAsyncHTTP1::ListenerAsyncHTTP1(std::uint16_t port,
+                                       std::unordered_map<std::string, std::function<HTTPResponse(const HTTPRequest&)>> routes,
+                                       std::function<HTTPResponse(const HTTPRequest&)> fallback,
+                                       TLSServerCredentials credentials)
+    : listener(port, std::move(routes), std::move(fallback), std::move(credentials))
+    , thread(&ListenerHTTP1::Listen, &listener)
+{}
+
 ListenerAsyncHTTP1::~ListenerAsyncHTTP1() {
     Stop();
 }

implementations/Crafter.Network-Stream.cpp

@@ -0,0 +1,99 @@
+//SPDX-License-Identifier: LGPL-3.0-only
+//SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®
+
+module;
+#include <poll.h>
+#include <fcntl.h>
+#include <sys/socket.h>
+#include <cerrno>
+
+module Crafter.Network:Stream_impl;
+import :Stream;
+import std;
+
+using namespace Crafter;
+
+void Crafter::SetNonBlocking(int descriptor) {
+    const int flags = fcntl(descriptor, F_GETFL, 0);
+    if (flags == -1 || fcntl(descriptor, F_SETFL, flags | O_NONBLOCK) == -1) {
+        throw std::runtime_error(std::string("could not make the socket non-blocking: ")
+                                 + std::strerror(errno));
+    }
+}
+
+bool Crafter::PollDescriptor(int descriptor, short events,
+                             std::chrono::steady_clock::time_point deadline) {
+    for (;;) {
+        const auto left = std::chrono::duration_cast<std::chrono::milliseconds>(
+            deadline - std::chrono::steady_clock::now());
+        // A deadline already in the past still gets one non-blocking look, so
+        // a zero timeout means "is it ready right now" rather than "give up".
+        const int wait = left.count() > 0 ? static_cast<int>(left.count()) : 0;
+
+        pollfd descriptors{ .fd = descriptor, .events = events, .revents = 0 };
+        const int ready = poll(&descriptors, 1, wait);
+        if (ready < 0) {
+            if (errno == EINTR) continue;
+            throw std::runtime_error(std::string("poll failed: ") + std::strerror(errno));
+        }
+        if (ready == 0) return false;
+        return true;
+    }
+}
+
+PlainStream::PlainStream(int descriptor) : descriptor(descriptor) {
+    SetNonBlocking(descriptor);
+}
+
+StreamStatus PlainStream::ReadSome(char* buffer, std::size_t size,
+                                   std::chrono::milliseconds timeout,
+                                   std::size_t& read) {
+    read = 0;
+    const auto deadline = std::chrono::steady_clock::now() + timeout;
+    for (;;) {
+        const auto got = recv(descriptor, buffer, size, 0);
+        if (got > 0) {
+            read = static_cast<std::size_t>(got);
+            return StreamStatus::Data;
+        }
+        if (got == 0) return StreamStatus::Closed;
+        if (errno == EINTR) continue;
+        if (errno == EAGAIN || errno == EWOULDBLOCK) {
+            if (!PollDescriptor(descriptor, POLLIN, deadline)) return StreamStatus::TimedOut;
+            continue;
+        }
+        // A reset is how a peer that stopped caring shows up; it is an end of
+        // connection rather than something worth a diagnostic.
+        if (errno == ECONNRESET) return StreamStatus::Closed;
+        throw std::runtime_error(std::string("recv failed: ") + std::strerror(errno));
+    }
+}
+
+void PlainStream::Write(const void* buffer, std::size_t size,
+                        std::chrono::milliseconds timeout) {
+    const auto deadline = std::chrono::steady_clock::now() + timeout;
+    const char* data = reinterpret_cast<const char*>(buffer);
+    std::size_t sent = 0;
+    while (sent < size) {
+        // MSG_NOSIGNAL: a peer that closed early must surface as EPIPE here,
+        // not as a SIGPIPE that takes the process down.
+        const auto wrote = send(descriptor, data + sent, size - sent, MSG_NOSIGNAL);
+        if (wrote > 0) {
+            sent += static_cast<std::size_t>(wrote);
+            continue;
+        }
+        if (wrote == 0) throw std::runtime_error("the peer closed the connection");
+        if (errno == EINTR) continue;
+        if (errno == EAGAIN || errno == EWOULDBLOCK) {
+            if (!PollDescriptor(descriptor, POLLOUT, deadline)) {
+                throw std::runtime_error("timed out writing to the peer");
+            }
+            continue;
+        }
+        throw std::runtime_error(std::string("send failed: ") + std::strerror(errno));
+    }
+}
+
+void PlainStream::Shutdown() noexcept {
+    shutdown(descriptor, SHUT_WR);
+}

implementations/Crafter.Network-TLS.cpp

@@ -0,0 +1,669 @@
+//SPDX-License-Identifier: LGPL-3.0-only
+//SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®
+
+module;
+#include <poll.h>
+#include <arpa/inet.h>
+#include <cerrno>
+#include <climits>
+
+#include <openssl/bio.h>
+#include <openssl/err.h>
+#include <openssl/evp.h>
+#include <openssl/pem.h>
+#include <openssl/ssl.h>
+#include <openssl/sslerr.h>
+#include <openssl/x509v3.h>
+
+module Crafter.Network:TLS_impl;
+import :TLS;
+import :Stream;
+import std;
+
+using namespace Crafter;
+
+namespace {
+    // ── OpenSSL plumbing ─────────────────────────────────────────────────
+    template <typename T, void (*Release)(T*)>
+    struct Releaser {
+        void operator()(T* pointer) const noexcept { if (pointer) Release(pointer); }
+    };
+    template <typename T, void (*Release)(T*)>
+    using Owned = std::unique_ptr<T, Releaser<T, Release>>;
+
+    using OwnedBio = Owned<BIO, BIO_free_all>;
+    using OwnedKey = Owned<EVP_PKEY, EVP_PKEY_free>;
+    using OwnedCertificate = Owned<X509, X509_free>;
+
+    // Drain OpenSSL's per-thread error queue into a readable message. Without
+    // this every TLS failure reads as "handshake failed" with no hint as to
+    // whether it was the certificate, the version, or the peer hanging up.
+    std::string Describe(std::string_view what) {
+        std::string message(what);
+        bool first = true;
+        while (const unsigned long code = ERR_get_error()) {
+            char buffer[256];
+            ERR_error_string_n(code, buffer, sizeof(buffer));
+            message += first ? ": " : "; ";
+            message += buffer;
+            first = false;
+        }
+        return message;
+    }
+
+    // True once OpenSSL has told us the peer vanished without a close_notify.
+    // For HTTP/1.1 that is an end of connection like any other — the message
+    // parser is the thing that decides whether it arrived too early.
+    bool UnexpectedEof() {
+        const unsigned long code = ERR_peek_error();
+        return ERR_GET_LIB(code) == ERR_LIB_SSL
+            && ERR_GET_REASON(code) == SSL_R_UNEXPECTED_EOF_WHILE_READING;
+    }
+
+    std::string BioToString(BIO* bio) {
+        char* data = nullptr;
+        const long length = BIO_get_mem_data(bio, &data);
+        if (length <= 0 || data == nullptr) return {};
+        return std::string(data, static_cast<std::size_t>(length));
+    }
+
+    bool IsIpLiteral(const std::string& name) {
+        in_addr v4{};
+        in6_addr v6{};
+        return inet_pton(AF_INET, name.c_str(), &v4) == 1
+            || inet_pton(AF_INET6, name.c_str(), &v6) == 1;
+    }
+
+    // ── ALPN ─────────────────────────────────────────────────────────────
+    // Wire form is a sequence of length-prefixed protocol names.
+    std::vector<unsigned char> EncodeAlpn(const std::vector<std::string>& protocols) {
+        std::vector<unsigned char> wire;
+        for (const std::string& protocol : protocols) {
+            if (protocol.empty() || protocol.size() > 255) {
+                throw TLSException("ALPN protocol names must be 1..255 bytes: '" + protocol + "'");
+            }
+            wire.push_back(static_cast<unsigned char>(protocol.size()));
+            wire.insert(wire.end(), protocol.begin(), protocol.end());
+        }
+        return wire;
+    }
+
+    // Server-side selection, in *our* preference order rather than the
+    // client's: the server is the side that knows what it can actually parse.
+    // No overlap is a fatal no_application_protocol alert (RFC 7301 §3.2) —
+    // letting the connection through would mean answering HTTP/2 with an
+    // HTTP/1.1 response and confusing both ends.
+    int SelectAlpn(SSL*, const unsigned char** out, unsigned char* outLength,
+                   const unsigned char* in, unsigned int inLength, void* argument) {
+        const auto& preferred = *static_cast<const std::vector<std::string>*>(argument);
+        for (const std::string& candidate : preferred) {
+            for (unsigned int offset = 0; offset < inLength;) {
+                const unsigned int length = in[offset];
+                if (offset + 1 + length > inLength) break;  // malformed list
+                if (length == candidate.size()
+                    && std::memcmp(in + offset + 1, candidate.data(), length) == 0) {
+                    *out = in + offset + 1;
+                    *outLength = static_cast<unsigned char>(length);
+                    return SSL_TLSEXT_ERR_OK;
+                }
+                offset += 1 + length;
+            }
+        }
+        return SSL_TLSEXT_ERR_ALERT_FATAL;
+    }
+
+    // ── Self-signed certificate ──────────────────────────────────────────
+    void AddExtension(X509* certificate, X509V3_CTX* context, int nid, const char* value) {
+        X509_EXTENSION* extension = X509V3_EXT_conf_nid(nullptr, context, nid, value);
+        if (extension == nullptr) {
+            throw TLSException(Describe("could not build certificate extension"));
+        }
+        const int added = X509_add_ext(certificate, extension, -1);
+        X509_EXTENSION_free(extension);
+        if (added != 1) throw TLSException(Describe("could not add certificate extension"));
+    }
+
+    TLSCertificatePem MakeSelfSignedCertificate() {
+        OwnedKey key(EVP_EC_gen("P-256"));
+        if (!key) throw TLSException(Describe("could not generate a P-256 key"));
+
+        OwnedCertificate certificate(X509_new());
+        if (!certificate) throw TLSException(Describe("could not allocate a certificate"));
+
+        // X509_set_version takes the zero-based version, so 2 is v3 — which is
+        // what the extensions below require.
+        X509_set_version(certificate.get(), 2);
+        ASN1_INTEGER_set(X509_get_serialNumber(certificate.get()), 1);
+        // Backdated an hour so a peer whose clock runs slightly behind ours
+        // does not reject a certificate we just minted.
+        X509_gmtime_adj(X509_getm_notBefore(certificate.get()), -3600);
+        X509_gmtime_adj(X509_getm_notAfter(certificate.get()), 10 * 24 * 60 * 60);
+        if (X509_set_pubkey(certificate.get(), key.get()) != 1) {
+            throw TLSException(Describe("could not set the certificate public key"));
+        }
+
+        X509_NAME* subject = X509_get_subject_name(certificate.get());
+        X509_NAME_add_entry_by_txt(subject, "CN", MBSTRING_ASC,
+                                   reinterpret_cast<const unsigned char*>("localhost"), -1, -1, 0);
+        // Self-signed: issuer is the subject.
+        X509_set_issuer_name(certificate.get(), subject);
+
+        X509V3_CTX extensionContext;
+        X509V3_set_ctx_nodb(&extensionContext);
+        X509V3_set_ctx(&extensionContext, certificate.get(), certificate.get(),
+                       nullptr, nullptr, 0);
+        AddExtension(certificate.get(), &extensionContext, NID_basic_constraints,
+                     "critical,CA:FALSE");
+        AddExtension(certificate.get(), &extensionContext, NID_key_usage,
+                     "critical,digitalSignature,keyEncipherment");
+        AddExtension(certificate.get(), &extensionContext, NID_ext_key_usage, "serverAuth");
+        // The SANs are what a verifying client actually matches on; a bare CN
+        // has not been accepted by anything for years.
+        AddExtension(certificate.get(), &extensionContext, NID_subject_alt_name,
+                     "DNS:localhost,IP:127.0.0.1,IP:::1");
+
+        if (X509_sign(certificate.get(), key.get(), EVP_sha256()) == 0) {
+            throw TLSException(Describe("could not sign the certificate"));
+        }
+
+        TLSCertificatePem pem;
+        {
+            OwnedBio bio(BIO_new(BIO_s_mem()));
+            if (!bio || PEM_write_bio_X509(bio.get(), certificate.get()) != 1) {
+                throw TLSException(Describe("could not encode the certificate as PEM"));
+            }
+            pem.certificate = BioToString(bio.get());
+        }
+        {
+            OwnedBio bio(BIO_new(BIO_s_mem()));
+            if (!bio || PEM_write_bio_PrivateKey(bio.get(), key.get(), nullptr, nullptr, 0,
+                                                 nullptr, nullptr) != 1) {
+                throw TLSException(Describe("could not encode the private key as PEM"));
+            }
+            pem.privateKey = BioToString(bio.get());
+        }
+        return pem;
+    }
+
+    // ── Credential loading ───────────────────────────────────────────────
+    OwnedBio MemoryBio(const std::string& contents) {
+        if (contents.size() > static_cast<std::size_t>(INT_MAX)) {
+            throw TLSException("PEM blob is implausibly large");
+        }
+        OwnedBio bio(BIO_new_mem_buf(contents.data(), static_cast<int>(contents.size())));
+        if (!bio) throw TLSException(Describe("could not wrap the PEM blob"));
+        return bio;
+    }
+
+    // Leaf first, then any intermediates, exactly as OpenSSL's own
+    // *_chain_file loader treats a PEM bundle.
+    void UseCertificateChainPem(SSL_CTX* context, const std::string& pem) {
+        OwnedBio bio = MemoryBio(pem);
+        OwnedCertificate leaf(PEM_read_bio_X509(bio.get(), nullptr, nullptr, nullptr));
+        if (!leaf) throw TLSException(Describe("could not read the certificate PEM"));
+        if (SSL_CTX_use_certificate(context, leaf.get()) != 1) {
+            throw TLSException(Describe("could not install the certificate"));
+        }
+        SSL_CTX_clear_chain_certs(context);
+        for (;;) {
+            OwnedCertificate extra(PEM_read_bio_X509(bio.get(), nullptr, nullptr, nullptr));
+            if (!extra) break;
+            // add0 takes ownership on success, so the pointer is released.
+            if (SSL_CTX_add0_chain_cert(context, extra.get()) != 1) {
+                throw TLSException(Describe("could not install a chain certificate"));
+            }
+            (void)extra.release();
+        }
+        // PEM_read_bio_X509 leaves a "no start line" error behind when it runs
+        // out of certificates; that is the loop's exit condition, not a fault.
+        ERR_clear_error();
+    }
+
+    void UsePrivateKeyPem(SSL_CTX* context, const std::string& pem) {
+        OwnedBio bio = MemoryBio(pem);
+        OwnedKey key(PEM_read_bio_PrivateKey(bio.get(), nullptr, nullptr, nullptr));
+        if (!key) throw TLSException(Describe("could not read the private key PEM"));
+        if (SSL_CTX_use_PrivateKey(context, key.get()) != 1) {
+            throw TLSException(Describe("could not install the private key"));
+        }
+    }
+
+    // A trust anchor path is either a PEM bundle or a hashed directory of
+    // them; OpenSSL wants to be told which, so look.
+    void LoadTrustAnchorPath(SSL_CTX* context, const std::string& path) {
+        std::error_code error;
+        const bool directory = std::filesystem::is_directory(path, error);
+        const int loaded = directory
+            ? SSL_CTX_load_verify_locations(context, nullptr, path.c_str())
+            : SSL_CTX_load_verify_locations(context, path.c_str(), nullptr);
+        if (loaded != 1) {
+            throw TLSException(Describe("could not load trust anchors from '" + path + "'"));
+        }
+    }
+
+    void LoadTrustAnchorPem(SSL_CTX* context, const std::string& pem) {
+        X509_STORE* store = SSL_CTX_get_cert_store(context);
+        OwnedBio bio = MemoryBio(pem);
+        std::size_t added = 0;
+        for (;;) {
+            OwnedCertificate anchor(PEM_read_bio_X509(bio.get(), nullptr, nullptr, nullptr));
+            if (!anchor) break;
+            if (X509_STORE_add_cert(store, anchor.get()) != 1) {
+                throw TLSException(Describe("could not add a trust anchor"));
+            }
+            ++added;
+        }
+        ERR_clear_error();
+        if (added == 0) throw TLSException("caPem contained no certificate");
+    }
+
+    void ApplyCommonOptions(SSL_CTX* context) {
+        // TLS 1.2 floor: 1.0/1.1 are deprecated (RFC 8996) and nothing we want
+        // to talk to needs them.
+        if (SSL_CTX_set_min_proto_version(context, TLS1_2_VERSION) != 1) {
+            throw TLSException(Describe("could not require TLS 1.2 or newer"));
+        }
+        // Partial writes plus a moving write buffer: our Write() loops over
+        // its own offset, so it must be allowed to make progress a record at a
+        // time instead of being forced to re-present a byte-identical buffer.
+        SSL_CTX_set_mode(context, SSL_MODE_ENABLE_PARTIAL_WRITE
+                                | SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER);
+        // Renegotiation buys nothing here and is a cheap way for a peer to
+        // make us do asymmetric crypto on demand.
+        SSL_CTX_set_options(context, SSL_OP_NO_RENEGOTIATION);
+    }
+}
+
+// ── TLSContext ───────────────────────────────────────────────────────────
+struct TLSContext::Impl {
+    SSL_CTX* context = nullptr;
+    bool verifyPeer = true;
+    std::string serverName;
+    // Server preference list; SelectAlpn holds a pointer to it, so it must
+    // outlive every SSL made from this context — which it does, being owned
+    // by the shared_ptr'd TLSContext.
+    std::vector<std::string> alpn;
+
+    ~Impl() { if (context) SSL_CTX_free(context); }
+};
+
+TLSContext::TLSContext() : impl(std::make_unique<Impl>()) {}
+TLSContext::~TLSContext() = default;
+
+std::shared_ptr<TLSContext> TLSContext::Server(const TLSServerCredentials& credentials) {
+    std::shared_ptr<TLSContext> wrapper(new TLSContext());
+    Impl& state = *wrapper->impl;
+
+    state.context = SSL_CTX_new(TLS_server_method());
+    if (state.context == nullptr) throw TLSException(Describe("could not create a TLS context"));
+    ApplyCommonOptions(state.context);
+
+    if (!credentials.certPath.empty()) {
+        if (credentials.keyPath.empty()) {
+            throw TLSException("certPath was given without a matching keyPath");
+        }
+        if (SSL_CTX_use_certificate_chain_file(state.context, credentials.certPath.c_str()) != 1) {
+            throw TLSException(Describe("could not load the certificate '"
+                                        + credentials.certPath + "'"));
+        }
+        if (SSL_CTX_use_PrivateKey_file(state.context, credentials.keyPath.c_str(),
+                                        SSL_FILETYPE_PEM) != 1) {
+            throw TLSException(Describe("could not load the private key '"
+                                        + credentials.keyPath + "'"));
+        }
+    } else if (!credentials.certPem.empty()) {
+        if (credentials.keyPem.empty()) {
+            throw TLSException("certPem was given without a matching keyPem");
+        }
+        UseCertificateChainPem(state.context, credentials.certPem);
+        UsePrivateKeyPem(state.context, credentials.keyPem);
+    } else if (credentials.selfSigned) {
+        const TLSCertificatePem& pem = GetSelfSignedCertificatePem();
+        UseCertificateChainPem(state.context, pem.certificate);
+        UsePrivateKeyPem(state.context, pem.privateKey);
+    } else {
+        throw TLSException("no server certificate: set certPath/keyPath, certPem/keyPem, "
+                           "or selfSigned for a development certificate");
+    }
+    if (SSL_CTX_check_private_key(state.context) != 1) {
+        throw TLSException(Describe("the private key does not match the certificate"));
+    }
+
+    if (credentials.requireClientCertificate) {
+        if (!credentials.clientCaPath.empty()) {
+            LoadTrustAnchorPath(state.context, credentials.clientCaPath);
+            // Advertise the acceptable issuers so the client can choose a
+            // certificate instead of guessing.
+            std::error_code error;
+            if (!std::filesystem::is_directory(credentials.clientCaPath, error)) {
+                if (STACK_OF(X509_NAME)* names =
+                        SSL_load_client_CA_file(credentials.clientCaPath.c_str())) {
+                    SSL_CTX_set_client_CA_list(state.context, names);
+                }
+            }
+        } else if (SSL_CTX_set_default_verify_paths(state.context) != 1) {
+            throw TLSException(Describe("could not load the system trust store"));
+        }
+        SSL_CTX_set_verify(state.context,
+                           SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT, nullptr);
+    }
+
+    state.alpn = credentials.alpnProtocols;
+    if (!state.alpn.empty()) {
+        // Validate the names now rather than inside the handshake callback,
+        // where there is nowhere useful to report a bad configuration.
+        (void)EncodeAlpn(state.alpn);
+        SSL_CTX_set_alpn_select_cb(state.context, SelectAlpn, &state.alpn);
+    }
+    return wrapper;
+}
+
+std::shared_ptr<TLSContext> TLSContext::Client(const TLSClientCredentials& credentials) {
+    std::shared_ptr<TLSContext> wrapper(new TLSContext());
+    Impl& state = *wrapper->impl;
+
+    state.context = SSL_CTX_new(TLS_client_method());
+    if (state.context == nullptr) throw TLSException(Describe("could not create a TLS context"));
+    ApplyCommonOptions(state.context);
+
+    state.verifyPeer = !credentials.insecureNoServerValidation;
+    state.serverName = credentials.serverName;
+    if (state.verifyPeer) {
+        if (SSL_CTX_set_default_verify_paths(state.context) != 1) {
+            throw TLSException(Describe("could not load the system trust store"));
+        }
+        if (!credentials.caPath.empty()) LoadTrustAnchorPath(state.context, credentials.caPath);
+        if (!credentials.caPem.empty()) LoadTrustAnchorPem(state.context, credentials.caPem);
+        SSL_CTX_set_verify(state.context, SSL_VERIFY_PEER, nullptr);
+    } else {
+        // The handshake still completes and SSL_get_verify_result still
+        // reports what it found; nothing acts on it.
+        SSL_CTX_set_verify(state.context, SSL_VERIFY_NONE, nullptr);
+    }
+
+    if (!credentials.certPath.empty()) {
+        if (credentials.keyPath.empty()) {
+            throw TLSException("certPath was given without a matching keyPath");
+        }
+        if (SSL_CTX_use_certificate_chain_file(state.context, credentials.certPath.c_str()) != 1) {
+            throw TLSException(Describe("could not load the client certificate '"
+                                        + credentials.certPath + "'"));
+        }
+        if (SSL_CTX_use_PrivateKey_file(state.context, credentials.keyPath.c_str(),
+                                        SSL_FILETYPE_PEM) != 1) {
+            throw TLSException(Describe("could not load the client private key '"
+                                        + credentials.keyPath + "'"));
+        }
+        if (SSL_CTX_check_private_key(state.context) != 1) {
+            throw TLSException(Describe("the client key does not match the client certificate"));
+        }
+    }
+
+    if (!credentials.alpnProtocols.empty()) {
+        const std::vector<unsigned char> wire = EncodeAlpn(credentials.alpnProtocols);
+        if (SSL_CTX_set_alpn_protos(state.context, wire.data(),
+                                    static_cast<unsigned int>(wire.size())) != 0) {
+            throw TLSException(Describe("could not set the ALPN protocol list"));
+        }
+    }
+    return wrapper;
+}
+
+// ── TLSStream ────────────────────────────────────────────────────────────
+struct TLSStream::Impl {
+    std::shared_ptr<TLSContext> context;
+    SSL* ssl = nullptr;
+    int descriptor = -1;
+    std::string protocol;
+    bool shutdownSent = false;
+
+    ~Impl() { if (ssl) SSL_free(ssl); }
+
+    // Drive SSL_connect/SSL_accept to completion, polling for whichever
+    // direction OpenSSL is waiting on. The deadline covers the whole
+    // handshake, not each poll, so a peer that dribbles records cannot
+    // stretch it indefinitely.
+    void Handshake(bool client, std::chrono::milliseconds timeout) {
+        const auto deadline = std::chrono::steady_clock::now() + timeout;
+        for (;;) {
+            ERR_clear_error();
+            const int result = client ? SSL_connect(ssl) : SSL_accept(ssl);
+            if (result == 1) break;
+
+            const int error = SSL_get_error(ssl, result);
+            if (error == SSL_ERROR_WANT_READ || error == SSL_ERROR_WANT_WRITE) {
+                const short events = error == SSL_ERROR_WANT_READ ? POLLIN : POLLOUT;
+                if (!PollDescriptor(descriptor, events, deadline)) {
+                    throw TLSException("TLS handshake timed out");
+                }
+                continue;
+            }
+            // Certificate problems are the failure people actually hit, and
+            // OpenSSL's generic queue message for them ("certificate verify
+            // failed") does not say which check tripped.
+            const long verified = SSL_get_verify_result(ssl);
+            if (verified != X509_V_OK) {
+                throw TLSException(std::string("TLS certificate rejected: ")
+                                   + X509_verify_cert_error_string(verified));
+            }
+            if (error == SSL_ERROR_ZERO_RETURN
+                || (error == SSL_ERROR_SYSCALL && result == 0)
+                || (error == SSL_ERROR_SSL && UnexpectedEof())) {
+                throw TLSException("the peer closed the connection during the TLS handshake");
+            }
+            if (error == SSL_ERROR_SYSCALL) {
+                throw TLSException(std::string("TLS handshake failed: ") + std::strerror(errno));
+            }
+            throw TLSException(Describe("TLS handshake failed"));
+        }
+
+        const unsigned char* selected = nullptr;
+        unsigned int length = 0;
+        SSL_get0_alpn_selected(ssl, &selected, &length);
+        if (selected != nullptr && length != 0) {
+            protocol.assign(reinterpret_cast<const char*>(selected), length);
+        }
+    }
+};
+
+TLSStream::TLSStream() : impl(std::make_unique<Impl>()) {}
+
+TLSStream::~TLSStream() {
+    Shutdown();
+}
+
+std::unique_ptr<TLSStream> TLSStream::Connect(int descriptor,
+                                              std::shared_ptr<TLSContext> context,
+                                              const std::string& hostName,
+                                              std::chrono::milliseconds timeout) {
+    if (!context) throw TLSException("no TLS context");
+    SetNonBlocking(descriptor);
+
+    std::unique_ptr<TLSStream> stream(new TLSStream());
+    TLSContext::Impl& configuration = *context->impl;
+    stream->impl->context = std::move(context);
+    stream->impl->descriptor = descriptor;
+
+    SSL* ssl = SSL_new(configuration.context);
+    if (ssl == nullptr) throw TLSException(Describe("could not create a TLS session"));
+    stream->impl->ssl = ssl;
+    if (SSL_set_fd(ssl, descriptor) != 1) {
+        throw TLSException(Describe("could not attach the socket to the TLS session"));
+    }
+
+    const std::string& name = configuration.serverName.empty()
+        ? hostName : configuration.serverName;
+    const bool literal = !name.empty() && IsIpLiteral(name);
+    // SNI carries host names only — an IP literal there is a protocol
+    // violation and some servers reject the handshake outright (RFC 6066 §3).
+    if (!name.empty() && !literal && SSL_set_tlsext_host_name(ssl, name.c_str()) != 1) {
+        throw TLSException(Describe("could not set the SNI host name"));
+    }
+    if (configuration.verifyPeer) {
+        if (name.empty()) {
+            throw TLSException("certificate verification needs a name to check against; "
+                               "set serverName or use insecureNoServerValidation");
+        }
+        SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS);
+        const int named = literal
+            ? X509_VERIFY_PARAM_set1_ip_asc(SSL_get0_param(ssl), name.c_str())
+            : SSL_set1_host(ssl, name.c_str());
+        if (named != 1) {
+            throw TLSException("could not use '" + name + "' as the name to verify");
+        }
+    }
+
+    SSL_set_connect_state(ssl);
+    stream->impl->Handshake(true, timeout);
+    return stream;
+}
+
+std::unique_ptr<TLSStream> TLSStream::Accept(int descriptor,
+                                             std::shared_ptr<TLSContext> context,
+                                             std::chrono::milliseconds timeout) {
+    if (!context) throw TLSException("no TLS context");
+    SetNonBlocking(descriptor);
+
+    std::unique_ptr<TLSStream> stream(new TLSStream());
+    TLSContext::Impl& configuration = *context->impl;
+    stream->impl->context = std::move(context);
+    stream->impl->descriptor = descriptor;
+
+    SSL* ssl = SSL_new(configuration.context);
+    if (ssl == nullptr) throw TLSException(Describe("could not create a TLS session"));
+    stream->impl->ssl = ssl;
+    if (SSL_set_fd(ssl, descriptor) != 1) {
+        throw TLSException(Describe("could not attach the socket to the TLS session"));
+    }
+
+    SSL_set_accept_state(ssl);
+    stream->impl->Handshake(false, timeout);
+    return stream;
+}
+
+StreamStatus TLSStream::ReadSome(char* buffer, std::size_t size,
+                                 std::chrono::milliseconds timeout,
+                                 std::size_t& read) {
+    read = 0;
+    if (size == 0) return StreamStatus::Data;
+    const auto deadline = std::chrono::steady_clock::now() + timeout;
+    const int wanted = static_cast<int>(std::min<std::size_t>(size, INT_MAX));
+    for (;;) {
+        ERR_clear_error();
+        const int got = SSL_read(impl->ssl, buffer, wanted);
+        if (got > 0) {
+            read = static_cast<std::size_t>(got);
+            return StreamStatus::Data;
+        }
+        const int error = SSL_get_error(impl->ssl, got);
+        switch (error) {
+            case SSL_ERROR_WANT_READ:
+                if (!PollDescriptor(impl->descriptor, POLLIN, deadline)) {
+                    return StreamStatus::TimedOut;
+                }
+                continue;
+            // A read can need the socket writable: TLS 1.3 key updates and
+            // (where allowed) renegotiation both send records mid-read.
+            case SSL_ERROR_WANT_WRITE:
+                if (!PollDescriptor(impl->descriptor, POLLOUT, deadline)) {
+                    return StreamStatus::TimedOut;
+                }
+                continue;
+            case SSL_ERROR_ZERO_RETURN:
+                return StreamStatus::Closed;   // close_notify: an orderly end
+            case SSL_ERROR_SYSCALL:
+                if (errno == EINTR) continue;
+                if (got == 0 || errno == 0 || errno == ECONNRESET) return StreamStatus::Closed;
+                throw TLSException(std::string("TLS read failed: ") + std::strerror(errno));
+            case SSL_ERROR_SSL:
+                if (UnexpectedEof()) return StreamStatus::Closed;
+                throw TLSException(Describe("TLS read failed"));
+            default:
+                throw TLSException(Describe("TLS read failed"));
+        }
+    }
+}
+
+void TLSStream::Write(const void* buffer, std::size_t size,
+                      std::chrono::milliseconds timeout) {
+    const auto deadline = std::chrono::steady_clock::now() + timeout;
+    const char* data = reinterpret_cast<const char*>(buffer);
+    std::size_t sent = 0;
+    while (sent < size) {
+        const int wanted = static_cast<int>(std::min<std::size_t>(size - sent, INT_MAX));
+        ERR_clear_error();
+        const int wrote = SSL_write(impl->ssl, data + sent, wanted);
+        if (wrote > 0) {
+            sent += static_cast<std::size_t>(wrote);
+            continue;
+        }
+        const int error = SSL_get_error(impl->ssl, wrote);
+        switch (error) {
+            case SSL_ERROR_WANT_READ:
+                if (!PollDescriptor(impl->descriptor, POLLIN, deadline)) {
+                    throw TLSException("timed out writing to the TLS peer");
+                }
+                continue;
+            case SSL_ERROR_WANT_WRITE:
+                if (!PollDescriptor(impl->descriptor, POLLOUT, deadline)) {
+                    throw TLSException("timed out writing to the TLS peer");
+                }
+                continue;
+            case SSL_ERROR_ZERO_RETURN:
+                throw TLSException("the TLS peer closed the connection");
+            case SSL_ERROR_SYSCALL:
+                if (errno == EINTR) continue;
+                throw TLSException(std::string("TLS write failed: ")
+                                   + (errno == 0 ? "the peer closed the connection"
+                                                 : std::strerror(errno)));
+            default:
+                throw TLSException(Describe("TLS write failed"));
+        }
+    }
+}
+
+void TLSStream::Shutdown() noexcept {
+    if (!impl || impl->ssl == nullptr || impl->shutdownSent) return;
+    impl->shutdownSent = true;
+    // One attempt only: close_notify goes out, and we deliberately do not
+    // wait for the peer's. Waiting means blocking a teardown path on a peer
+    // that may never answer, and every framing decision has already been made
+    // by the time we get here.
+    ERR_clear_error();
+    SSL_shutdown(impl->ssl);
+    ERR_clear_error();
+}
+
+int TLSStream::Descriptor() const noexcept {
+    return impl ? impl->descriptor : -1;
+}
+
+std::string_view TLSStream::Protocol() const noexcept {
+    return impl ? std::string_view(impl->protocol) : std::string_view();
+}
+
+std::string TLSStream::Version() const {
+    if (!impl || impl->ssl == nullptr) return {};
+    const char* version = SSL_get_version(impl->ssl);
+    return version == nullptr ? std::string() : std::string(version);
+}
+
+std::string TLSStream::PeerCertificateSubject() const {
+    if (!impl || impl->ssl == nullptr) return {};
+    OwnedCertificate peer(SSL_get1_peer_certificate(impl->ssl));
+    if (!peer) return {};
+    char buffer[512] = {};
+    X509_NAME_oneline(X509_get_subject_name(peer.get()), buffer, sizeof(buffer));
+    return std::string(buffer);
+}
+
+const TLSCertificatePem& Crafter::GetSelfSignedCertificatePem() {
+    // Generated once per process so every listener presents the same
+    // certificate: a client that was handed it as a trust anchor keeps
+    // working across reconnects.
+    static std::mutex mutex;
+    static std::optional<TLSCertificatePem> cached;
+    std::lock_guard lock(mutex);
+    if (!cached) cached = MakeSelfSignedCertificate();
+    return *cached;
+}