security and doc update

Author: playmiel

README.md

@@ -23,7 +23,7 @@ An asynchronous HTTP client library for ESP32 microcontrollers, built on top of
 - ✅ **Multiple simultaneous requests** - Handle multiple requests concurrently
 - ✅ **Chunked transfer decoding** - Validates framing and exposes parsed trailers
 - ✅ **Optional redirect following** - Follow 301/302/303 (converted to GET) and 307/308 (method preserved)
-- ✅ **Header & body guards** - Limit buffered response headers/body to avoid runaway responses
+- ✅ **Header & body guards** - Limits buffered headers (~2.8 KiB) and body (8 KiB) by default to avoid runaway responses
 - ✅ **Zero-copy streaming** - Combine `req->setNoStoreBody(true)` with `client.onBodyChunk(...)` to stream large payloads without heap spikes
 
 > ⚠ Limitations: provide trust material for HTTPS (CA, fingerprint or insecure flag) and remember the full body is buffered in memory unless you opt into zero-copy streaming via `setNoStoreBody(true)`.
@@ -150,10 +150,10 @@ void setDefaultConnectTimeout(uint32_t ms);
 // Follow HTTP redirects (max hops clamps to >=1). Disabled by default.
 void setFollowRedirects(bool enable, uint8_t maxHops = 3);
 
-// Abort if response headers exceed this many bytes (0 = unlimited)
+// Abort if response headers exceed this many bytes (default ~2.8 KiB, 0 = unlimited)
 void setMaxHeaderBytes(size_t maxBytes);
 
-// Soft limit for buffered response bodies (bytes, 0 = unlimited)
+// Soft limit for buffered response bodies (default 8192 bytes, 0 = unlimited)
 void setMaxBodySize(size_t maxBytes);
 
 // Limit simultaneous active requests (0 = unlimited, others queued)
@@ -162,12 +162,20 @@ void setMaxParallel(uint16_t maxParallel);
 // Set User-Agent string
 void setUserAgent(const char* userAgent);
 
+// Keep-alive connection pooling (idle timeout in ms, clamped to >= 1000)
+void setKeepAlive(bool enable, uint16_t idleMs = 5000);
+
 // Cookie jar helpers
 void clearCookies();
 void setCookie(const char* name, const char* value, const char* path = "/", const char* domain = nullptr,
                bool secure = false);
 ```
 
+Cookies are captured automatically from `Set-Cookie` responses and replayed on matching hosts/paths; call
+`clearCookies()` to wipe the jar or `setCookie()` to pre-seed entries manually. Keep-alive pooling is off by default;
+enable it with `setKeepAlive(true, idleMs)` to reuse TCP/TLS connections for the same host/port (respecting server
+`Connection: close` requests).
+
 #### Callback Types
 
 ```cpp

src/AsyncHttpClient.cpp

@@ -11,6 +11,13 @@
 static constexpr size_t kMaxChunkSizeLineLen = 64;
 static constexpr size_t kMaxChunkTrailerLineLen = 256;
 static constexpr size_t kMaxChunkTrailerLines = 32;
+static constexpr size_t kDefaultMaxHeaderBytes = 2800; // ~2.8 KiB
+static constexpr size_t kDefaultMaxBodyBytes = 8192;   // 8 KiB
+static constexpr size_t kMaxCookieCount = 16;
+static constexpr size_t kMaxCookieBytes = 4096;
+static const char* kPublicSuffixes[] = {"com",  "net",  "org", "gov", "edu", "mil", "int",
+                                        "co.uk", "ac.uk", "gov.uk", "uk",  "io",  "co"};
+
 static bool equalsIgnoreCase(const String& a, const char* b) {
     size_t lenA = a.length();
     size_t lenB = strlen(b);
@@ -26,7 +33,8 @@ static bool equalsIgnoreCase(const String& a, const char* b) {
 
 AsyncHttpClient::AsyncHttpClient()
     : _defaultTimeout(10000), _defaultUserAgent(String("ESPAsyncWebClient/") + ESP_ASYNC_WEB_CLIENT_VERSION),
-      _bodyChunkCallback(nullptr), _followRedirects(false), _maxRedirectHops(3), _maxHeaderBytes(0) {
+      _bodyChunkCallback(nullptr), _maxBodySize(kDefaultMaxBodyBytes), _followRedirects(false), _maxRedirectHops(3),
+      _maxHeaderBytes(kDefaultMaxHeaderBytes) {
 #if defined(ARDUINO_ARCH_ESP32) && defined(ASYNC_HTTP_ENABLE_AUTOLOOP)
     // Create recursive mutex for shared containers when auto-loop may run in background
     _reqMutex = xSemaphoreCreateRecursiveMutex();
@@ -1292,6 +1300,18 @@ bool AsyncHttpClient::isIpLiteral(const String& host) const {
     return hasColon || hasDot;
 }
 
+static bool isPublicSuffix(const String& domain) {
+    if (domain.length() == 0)
+        return false;
+    String lower = domain;
+    lower.toLowerCase();
+    for (auto suffix : kPublicSuffixes) {
+        if (lower.equals(suffix))
+            return true;
+    }
+    return false;
+}
+
 bool AsyncHttpClient::normalizeCookieDomain(String& domain, const String& host, bool domainAttributeProvided) const {
     String cleaned = domain;
     cleaned.trim();
@@ -1316,6 +1336,8 @@ bool AsyncHttpClient::normalizeCookieDomain(String& domain, const String& host,
         return false;
     if (cleaned.indexOf('.') == -1)
         return false;
+    if (isPublicSuffix(cleaned))
+        return false;
 
     domain = cleaned;
     return true;
@@ -1409,6 +1431,8 @@ void AsyncHttpClient::storeResponseCookie(const AsyncHttpRequest* request, const
     String raw = setCookieValue;
     if (raw.length() == 0)
         return;
+    if (raw.length() > kMaxCookieBytes)
+        return;
     int semi = raw.indexOf(';');
     String pair = semi == -1 ? raw : raw.substring(0, semi);
     pair.trim();
@@ -1456,6 +1480,9 @@ void AsyncHttpClient::storeResponseCookie(const AsyncHttpRequest* request, const
         return;
     if (!cookie.path.startsWith("/"))
         cookie.path = "/" + cookie.path;
+    size_t payloadSize = cookie.name.length() + cookie.value.length() + cookie.domain.length() + cookie.path.length();
+    if (payloadSize > kMaxCookieBytes)
+        return;
 
     lock();
     for (auto it = _cookies.begin(); it != _cookies.end();) {
@@ -1466,7 +1493,10 @@ void AsyncHttpClient::storeResponseCookie(const AsyncHttpRequest* request, const
             ++it;
         }
     }
-    if (!remove)
+    if (!remove) {
+        if (_cookies.size() >= kMaxCookieCount)
+            _cookies.erase(_cookies.begin());
         _cookies.push_back(cookie);
+    }
     unlock();
 }

src/AsyncTransport.cpp

@@ -274,6 +274,7 @@ class AsyncTlsTransport : public AsyncTransport {
     std::vector<uint8_t> _encryptedBuffer;
     size_t _encryptedOffset = 0;
     std::vector<uint8_t> _fingerprintBytes;
+    bool _fingerprintInvalid = false;
 
     mbedtls_ssl_context _ssl;
     mbedtls_ssl_config _sslConfig;
@@ -295,7 +296,8 @@ static int hexValue(char c) {
     return -1;
 }
 
-static std::vector<uint8_t> parseFingerprintString(const String& text) {
+static std::vector<uint8_t> parseFingerprintString(const String& text, bool* outValid) {
+    bool valid = true;
     std::vector<uint8_t> bytes;
     int accum = -1;
     for (size_t i = 0; i < text.length(); ++i) {
@@ -306,6 +308,7 @@ static std::vector<uint8_t> parseFingerprintString(const String& text) {
         int v = hexValue(ch);
         if (v < 0) {
             bytes.clear();
+            valid = false;
             break;
         }
         if (accum == -1) {
@@ -318,7 +321,10 @@ static std::vector<uint8_t> parseFingerprintString(const String& text) {
     if (accum != -1) {
         // Odd number of nibbles -> invalid
         bytes.clear();
+        valid = false;
     }
+    if (outValid)
+        *outValid = valid || text.length() == 0;
     return bytes;
 }
 
@@ -334,7 +340,9 @@ AsyncTlsTransport::AsyncTlsTransport(const AsyncHttpTLSConfig& config) : _client
     mbedtls_pk_init(&_clientKey);
     mbedtls_entropy_init(&_entropy);
     mbedtls_ctr_drbg_init(&_ctrDrbg);
-    _fingerprintBytes = parseFingerprintString(_config.fingerprint);
+    bool fpValid = true;
+    _fingerprintBytes = parseFingerprintString(_config.fingerprint, &fpValid);
+    _fingerprintInvalid = (_config.fingerprint.length() > 0 && !fpValid);
 }
 
 AsyncTlsTransport::~AsyncTlsTransport() {
@@ -364,6 +372,10 @@ void AsyncTlsTransport::shutdownClient() {
 bool AsyncTlsTransport::connect(const char* host, uint16_t port) {
     if (!_client)
         return false;
+    if (_fingerprintInvalid) {
+        fail(TLS_FINGERPRINT_MISMATCH, "Invalid TLS fingerprint format");
+        return false;
+    }
     _host = host;
     _port = port;
     _handshakeStartMs = millis();

src/UrlParser.cpp

@@ -1,4 +1,6 @@
 #include "UrlParser.h"
+#include <cerrno>
+#include <cstdlib>
 
 namespace UrlParser {
 
@@ -9,6 +11,24 @@ static bool startsWith(const std::string& s, const char* prefix) {
     return s.size() >= n && s.compare(0, n, prefix) == 0;
 }
 
+static bool parsePort(const std::string& portStr, uint16_t* out) {
+    if (!out || portStr.empty())
+        return false;
+    for (char c : portStr) {
+        if (c < '0' || c > '9')
+            return false;
+    }
+    errno = 0;
+    char* end = nullptr;
+    unsigned long val = std::strtoul(portStr.c_str(), &end, 10);
+    if (end == portStr.c_str() || *end != '\0')
+        return false;
+    if (errno == ERANGE || val > 65535)
+        return false;
+    *out = static_cast<uint16_t>(val);
+    return true;
+}
+
 bool parse(const std::string& originalUrl, ParsedUrl& out) {
     std::string url = originalUrl; // working copy
     out.secure = false;
@@ -54,9 +74,10 @@ bool parse(const std::string& originalUrl, ParsedUrl& out) {
     if (colon != std::string::npos) {
         std::string portStr = out.host.substr(colon + 1);
         out.host = out.host.substr(0, colon);
-        if (!portStr.empty()) {
-            out.port = static_cast<uint16_t>(std::stoi(portStr));
-        }
+        uint16_t parsedPort = 0;
+        if (!parsePort(portStr, &parsedPort))
+            return false;
+        out.port = parsedPort;
     }
 
     return !out.host.empty();