From d78cb09b17bb12dea1a8e6cd2d6e6b67f3004a38 Mon Sep 17 00:00:00 2001
From: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
Date: Mon, 13 Jul 2026 23:23:55 +1200
Subject: [PATCH 01/24] [web_server] Use dict-style packages in tests so they
 can be batch-grouped (#17544)

---
 tests/components/web_server/test.esp32-ard.yaml    | 3 ++-
 tests/components/web_server/test.esp32-idf.yaml    | 3 ++-
 tests/components/web_server/test.esp8266-ard.yaml  | 3 ++-
 tests/components/web_server/test.rp2040-ard.yaml   | 3 ++-
 tests/components/web_server/test_v1.esp32-ard.yaml | 3 ++-
 tests/components/web_server/test_v1.esp32-idf.yaml | 3 ++-
 tests/components/web_server/test_v3.esp32-ard.yaml | 3 ++-
 7 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/tests/components/web_server/test.esp32-ard.yaml b/tests/components/web_server/test.esp32-ard.yaml
index 7e6658e20e..11ad5456ef 100644
--- a/tests/components/web_server/test.esp32-ard.yaml
+++ b/tests/components/web_server/test.esp32-ard.yaml
@@ -1 +1,2 @@
-<<: !include common_v2.yaml
+packages:
+  web_server: !include common_v2.yaml
diff --git a/tests/components/web_server/test.esp32-idf.yaml b/tests/components/web_server/test.esp32-idf.yaml
index 24b292d0d6..858e3b0190 100644
--- a/tests/components/web_server/test.esp32-idf.yaml
+++ b/tests/components/web_server/test.esp32-idf.yaml
@@ -1,4 +1,5 @@
-<<: !include common_v2.yaml
+packages:
+  web_server: !include common_v2.yaml
 
 web_server:
   auth:
diff --git a/tests/components/web_server/test.esp8266-ard.yaml b/tests/components/web_server/test.esp8266-ard.yaml
index 7e6658e20e..11ad5456ef 100644
--- a/tests/components/web_server/test.esp8266-ard.yaml
+++ b/tests/components/web_server/test.esp8266-ard.yaml
@@ -1 +1,2 @@
-<<: !include common_v2.yaml
+packages:
+  web_server: !include common_v2.yaml
diff --git a/tests/components/web_server/test.rp2040-ard.yaml b/tests/components/web_server/test.rp2040-ard.yaml
index 7e6658e20e..11ad5456ef 100644
--- a/tests/components/web_server/test.rp2040-ard.yaml
+++ b/tests/components/web_server/test.rp2040-ard.yaml
@@ -1 +1,2 @@
-<<: !include common_v2.yaml
+packages:
+  web_server: !include common_v2.yaml
diff --git a/tests/components/web_server/test_v1.esp32-ard.yaml b/tests/components/web_server/test_v1.esp32-ard.yaml
index 389a930284..1d563de834 100644
--- a/tests/components/web_server/test_v1.esp32-ard.yaml
+++ b/tests/components/web_server/test_v1.esp32-ard.yaml
@@ -1 +1,2 @@
-<<: !include common_v1.yaml
+packages:
+  web_server: !include common_v1.yaml
diff --git a/tests/components/web_server/test_v1.esp32-idf.yaml b/tests/components/web_server/test_v1.esp32-idf.yaml
index 389a930284..1d563de834 100644
--- a/tests/components/web_server/test_v1.esp32-idf.yaml
+++ b/tests/components/web_server/test_v1.esp32-idf.yaml
@@ -1 +1,2 @@
-<<: !include common_v1.yaml
+packages:
+  web_server: !include common_v1.yaml
diff --git a/tests/components/web_server/test_v3.esp32-ard.yaml b/tests/components/web_server/test_v3.esp32-ard.yaml
index 00d05521e4..956a88bc68 100644
--- a/tests/components/web_server/test_v3.esp32-ard.yaml
+++ b/tests/components/web_server/test_v3.esp32-ard.yaml
@@ -1 +1,2 @@
-<<: !include common_v3.yaml
+packages:
+  web_server: !include common_v3.yaml

From 5e3e2f82c9800bc232b0c9c9d962418a1b4f7d44 Mon Sep 17 00:00:00 2001
From: Clyde Stubbs <2366188+clydebarrow@users.noreply.github.com>
Date: Tue, 14 Jul 2026 00:16:53 +1000
Subject: [PATCH 02/24] [script] Fix duplicate import in build_codeowners.py
 (#17543)

---
 script/build_codeowners.py | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/script/build_codeowners.py b/script/build_codeowners.py
index 10ca1295b7..be8b445542 100755
--- a/script/build_codeowners.py
+++ b/script/build_codeowners.py
@@ -61,6 +61,13 @@ for path in components_dir.iterdir():
     codeowners[f"esphome/components/{name}/*"].extend(comp.codeowners)
 
     for platform_path in path.iterdir():
+        if platform_path.name == "__init__.py":
+            # `import pkg.__init__` is valid but distinct from `import pkg`: it re-executes
+            # the component's __init__.py as a second, separate module. That's harmless for
+            # components whose top-level code is idempotent, but not guaranteed in general
+            # (e.g. code that registers into a global registry with a duplicate check), so
+            # never treat __init__.py itself as a platform candidate.
+            continue
         platform_name = platform_path.stem
         platform = get_platform(platform_name, name)
         if platform is None:

From 65d6c028cea339b1e8baa1fcb456afbe76f3d210 Mon Sep 17 00:00:00 2001
From: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
Date: Tue, 14 Jul 2026 10:33:44 +1200
Subject: [PATCH 03/24] [web_server] Add HTTP digest authentication with
 selectable scheme (#17541)

---
 esphome/components/web_server/__init__.py     |  52 ++++--
 .../web_server_base/web_server_base.h         |   8 +
 .../web_server_idf/web_server_idf.cpp         | 170 +++++++++++++++++-
 .../web_server_idf/web_server_idf.h           |   2 +-
 esphome/core/defines.h                        |   3 +
 .../web_server/test_web_server_auth.py        |  65 +++++++
 .../web_server/web_server_auth_basic.yaml     |  18 ++
 .../web_server/web_server_auth_default.yaml   |  17 ++
 .../web_server/web_server_auth_digest.yaml    |  18 ++
 .../web_server/web_server_no_auth.yaml        |  14 ++
 .../components/web_server/test.esp32-idf.yaml |   1 +
 .../web_server/test.esp8266-ard.yaml          |   6 +
 .../web_server/test.rp2040-ard.yaml           |   6 +
 .../web_server/validate.esp32-idf.yaml        |   8 +
 14 files changed, 370 insertions(+), 18 deletions(-)
 create mode 100644 tests/component_tests/web_server/test_web_server_auth.py
 create mode 100644 tests/component_tests/web_server/web_server_auth_basic.yaml
 create mode 100644 tests/component_tests/web_server/web_server_auth_default.yaml
 create mode 100644 tests/component_tests/web_server/web_server_auth_digest.yaml
 create mode 100644 tests/component_tests/web_server/web_server_no_auth.yaml
 create mode 100644 tests/components/web_server/validate.esp32-idf.yaml

diff --git a/esphome/components/web_server/__init__.py b/esphome/components/web_server/__init__.py
index 68f1c18072..2587d13b9e 100644
--- a/esphome/components/web_server/__init__.py
+++ b/esphome/components/web_server/__init__.py
@@ -25,6 +25,7 @@ from esphome.const import (
     CONF_OTA,
     CONF_PASSWORD,
     CONF_PORT,
+    CONF_TYPE,
     CONF_USERNAME,
     CONF_VERSION,
     CONF_WEB_SERVER,
@@ -44,6 +45,9 @@ _LOGGER = logging.getLogger(__name__)
 
 AUTO_LOAD = ["json", "web_server_base"]
 
+AUTH_TYPE_BASIC = "basic"
+AUTH_TYPE_DIGEST = "digest"
+
 CONF_SORTING_GROUP_ID = "sorting_group_id"
 CONF_SORTING_GROUPS = "sorting_groups"
 CONF_SORTING_WEIGHT = "sorting_weight"
@@ -85,6 +89,19 @@ def validate_version_deprecated(config: ConfigType) -> ConfigType:
     return config
 
 
+def validate_auth_type_deprecated(auth: ConfigType) -> ConfigType:
+    # Remove before 2027.1.0: the default auth scheme changes from basic to digest.
+    if CONF_TYPE not in auth:
+        _LOGGER.warning(
+            "The 'web_server' 'auth' scheme currently defaults to 'basic', which sends the "
+            "password over the network in an easily reversible form. The default will change "
+            "to 'digest' in ESPHome 2027.1.0. To keep using basic authentication, set "
+            "'type: basic' under 'auth:' explicitly; otherwise set 'type: digest' now to "
+            "adopt the more secure scheme."
+        )
+    return auth
+
+
 def validate_local(config: ConfigType) -> ConfigType:
     if CONF_LOCAL in config and config[CONF_VERSION] == 1:
         raise cv.Invalid("'local' is not supported in version 1")
@@ -242,15 +259,21 @@ CONFIG_SCHEMA = cv.All(
             cv.Optional(CONF_ALLOWED_ORIGINS): cv.All(
                 cv.ensure_list(validate_origin), cv.Length(min=1)
             ),
-            cv.Optional(CONF_AUTH): cv.Schema(
-                {
-                    cv.Required(CONF_USERNAME): cv.All(
-                        cv.string_strict, cv.Length(min=1)
-                    ),
-                    cv.Required(CONF_PASSWORD): cv.sensitive(
-                        cv.All(cv.string_strict, cv.Length(min=1))
-                    ),
-                }
+            cv.Optional(CONF_AUTH): cv.All(
+                cv.Schema(
+                    {
+                        cv.Required(CONF_USERNAME): cv.All(
+                            cv.string_strict, cv.Length(min=1)
+                        ),
+                        cv.Required(CONF_PASSWORD): cv.sensitive(
+                            cv.All(cv.string_strict, cv.Length(min=1))
+                        ),
+                        cv.Optional(CONF_TYPE): cv.one_of(
+                            AUTH_TYPE_BASIC, AUTH_TYPE_DIGEST, lower=True
+                        ),
+                    }
+                ),
+                validate_auth_type_deprecated,
             ),
             cv.GenerateID(CONF_WEB_SERVER_BASE_ID): cv.use_id(
                 web_server_base.WebServerBase
@@ -378,10 +401,15 @@ async def to_code(config):
     if (allowed_origins := config.get(CONF_ALLOWED_ORIGINS)) is not None:
         cg.add_define("USE_WEBSERVER_ALLOWED_ORIGINS")
         cg.add(var.set_allowed_origins(allowed_origins))
-    if CONF_AUTH in config:
+    if (auth := config.get(CONF_AUTH)) is not None:
         cg.add_define("USE_WEBSERVER_AUTH")
-        cg.add(paren.set_auth_username(config[CONF_AUTH][CONF_USERNAME]))
-        cg.add(paren.set_auth_password(config[CONF_AUTH][CONF_PASSWORD]))
+        # The scheme is fixed at build time so the unused Basic/Digest code path is compiled
+        # out. Basic is the current default (the absence of this define); an explicit
+        # 'type: digest' opts in early. Default changes to digest in 2027.1.0.
+        if auth.get(CONF_TYPE) == AUTH_TYPE_DIGEST:
+            cg.add_define("USE_WEBSERVER_AUTH_DIGEST")
+        cg.add(paren.set_auth_username(auth[CONF_USERNAME]))
+        cg.add(paren.set_auth_password(auth[CONF_PASSWORD]))
     if CONF_CSS_INCLUDE in config:
         cg.add_define("USE_WEBSERVER_CSS_INCLUDE")
         path = CORE.relative_config_path(config[CONF_CSS_INCLUDE])
diff --git a/esphome/components/web_server_base/web_server_base.h b/esphome/components/web_server_base/web_server_base.h
index 19c2185fb9..9657853a73 100644
--- a/esphome/components/web_server_base/web_server_base.h
+++ b/esphome/components/web_server_base/web_server_base.h
@@ -59,7 +59,15 @@ class AuthMiddlewareHandler : public MiddlewareHandler {
   bool check_auth(AsyncWebServerRequest *request) {
     bool success = request->authenticate(credentials_->username.c_str(), credentials_->password.c_str());
     if (!success) {
+      // The scheme is chosen at build time (USE_WEBSERVER_AUTH_DIGEST); the unused path is
+      // compiled out. On ESP32 our own server picks the scheme internally.
+#if USE_ESP32
       request->requestAuthentication();
+#elif defined(USE_WEBSERVER_AUTH_DIGEST)
+      request->requestAuthentication(nullptr, true);
+#else
+      request->requestAuthentication(nullptr, false);
+#endif
     }
     return success;
   }
diff --git a/esphome/components/web_server_idf/web_server_idf.cpp b/esphome/components/web_server_idf/web_server_idf.cpp
index 46a389f359..bf5a8666dc 100644
--- a/esphome/components/web_server_idf/web_server_idf.cpp
+++ b/esphome/components/web_server_idf/web_server_idf.cpp
@@ -16,6 +16,11 @@
 #include "utils.h"
 #include "web_server_idf.h"
 
+#ifdef USE_WEBSERVER_AUTH_DIGEST
+#include <esp_random.h>
+#include <esp_rom_md5.h>
+#endif
+
 #ifdef USE_WEBSERVER_OTA
 #include <multipart_parser.h>
 #include "multipart.h"  // For parse_multipart_boundary and other utils
@@ -372,6 +377,135 @@ void AsyncWebServerRequest::init_response_(AsyncWebServerResponse *rsp, int code
 }
 
 #ifdef USE_WEBSERVER_AUTH
+
+#ifdef USE_WEBSERVER_AUTH_DIGEST
+namespace {
+
+// Hex-encode `len` bytes into `out`, which must hold at least 2 * len + 1 bytes. Null-terminated.
+void bytes_to_hex(const uint8_t *data, size_t len, char *out) {
+  static const char HEX[] = "0123456789abcdef";
+  for (size_t i = 0; i < len; i++) {
+    out[i * 2] = HEX[data[i] >> 4];
+    out[i * 2 + 1] = HEX[data[i] & 0x0f];
+  }
+  out[len * 2] = '\0';
+}
+
+// Extract the value of a Digest auth parameter (e.g. "nonce") from the comma-separated
+// parameter list. Values may be quoted or bare. Returns an empty ref when the key is absent.
+// Only whole parameter names match, so "nc" does not match inside "cnonce".
+StringRef digest_param(StringRef params, const char *key) {
+  size_t key_len = strlen(key);
+  const char *base = params.c_str();
+  size_t n = params.size();
+  size_t i = 0;
+  while (i < n) {
+    while (i < n && (base[i] == ' ' || base[i] == ','))
+      i++;
+    size_t name_start = i;
+    while (i < n && base[i] != '=' && base[i] != ',')
+      i++;
+    if (i >= n || base[i] == ',')
+      continue;  // token without a '=', skip it
+    size_t name_len = i - name_start;
+    while (name_len > 0 && base[name_start + name_len - 1] == ' ')
+      name_len--;
+    i++;  // consume '='
+    const char *val_start;
+    size_t val_len;
+    if (i < n && base[i] == '"') {
+      i++;
+      val_start = base + i;
+      while (i < n && base[i] != '"')
+        i++;
+      val_len = (base + i) - val_start;
+      if (i < n)
+        i++;  // consume closing quote
+    } else {
+      val_start = base + i;
+      while (i < n && base[i] != ',')
+        i++;
+      val_len = (base + i) - val_start;
+    }
+    if (name_len == key_len && memcmp(base + name_start, key, key_len) == 0)
+      return StringRef(val_start, val_len);
+    while (i < n && base[i] != ',')
+      i++;
+  }
+  return StringRef();
+}
+
+// Verify an RFC 2617 Digest response. Stateless (the nonce we issued is not tracked), which
+// matches the ESPAsyncWebServer backend used on the Arduino platforms.
+bool check_digest_auth(const char *username, const char *password, const std::string &header, const char *method) {
+  const size_t prefix_len = sizeof("Digest ") - 1;
+  StringRef params(header.c_str() + prefix_len, header.size() - prefix_len);
+
+  if (digest_param(params, "username") != username)
+    return false;
+
+  StringRef realm = digest_param(params, "realm");
+  StringRef nonce = digest_param(params, "nonce");
+  StringRef uri = digest_param(params, "uri");
+  StringRef qop = digest_param(params, "qop");
+  StringRef nc = digest_param(params, "nc");
+  StringRef cnonce = digest_param(params, "cnonce");
+  StringRef response = digest_param(params, "response");
+  if (response.size() != 32)
+    return false;
+
+  // Compute the three MD5 hashes by streaming the pieces straight into the ROM MD5 engine, so
+  // nothing is concatenated on the heap. Each hash is emitted as 32 lowercase hex characters.
+  md5_context_t ctx;
+  uint8_t digest[16];
+
+  // HA1 = MD5(username:realm:password) -- uses the realm the client echoed back.
+  char ha1[33];
+  esp_rom_md5_init(&ctx);
+  esp_rom_md5_update(&ctx, username, strlen(username));
+  esp_rom_md5_update(&ctx, ":", 1);
+  esp_rom_md5_update(&ctx, realm.c_str(), realm.size());
+  esp_rom_md5_update(&ctx, ":", 1);
+  esp_rom_md5_update(&ctx, password, strlen(password));
+  esp_rom_md5_final(digest, &ctx);
+  bytes_to_hex(digest, sizeof(digest), ha1);
+
+  // HA2 = MD5(method:uri) -- uses the uri the client echoed back.
+  char ha2[33];
+  esp_rom_md5_init(&ctx);
+  esp_rom_md5_update(&ctx, method, strlen(method));
+  esp_rom_md5_update(&ctx, ":", 1);
+  esp_rom_md5_update(&ctx, uri.c_str(), uri.size());
+  esp_rom_md5_final(digest, &ctx);
+  bytes_to_hex(digest, sizeof(digest), ha2);
+
+  // expected = MD5(HA1:nonce:nc:cnonce:qop:HA2)
+  char expected[33];
+  esp_rom_md5_init(&ctx);
+  esp_rom_md5_update(&ctx, ha1, 32);
+  esp_rom_md5_update(&ctx, ":", 1);
+  esp_rom_md5_update(&ctx, nonce.c_str(), nonce.size());
+  esp_rom_md5_update(&ctx, ":", 1);
+  esp_rom_md5_update(&ctx, nc.c_str(), nc.size());
+  esp_rom_md5_update(&ctx, ":", 1);
+  esp_rom_md5_update(&ctx, cnonce.c_str(), cnonce.size());
+  esp_rom_md5_update(&ctx, ":", 1);
+  esp_rom_md5_update(&ctx, qop.c_str(), qop.size());
+  esp_rom_md5_update(&ctx, ":", 1);
+  esp_rom_md5_update(&ctx, ha2, 32);
+  esp_rom_md5_final(digest, &ctx);
+  bytes_to_hex(digest, sizeof(digest), expected);
+
+  // Constant-time comparison of the two 32-char hex digests.
+  uint8_t result = 0;
+  for (size_t i = 0; i < 32; i++)
+    result |= static_cast<uint8_t>(expected[i] ^ response[i]);
+  return result == 0;
+}
+
+}  // namespace
+#endif  // USE_WEBSERVER_AUTH_DIGEST
+
 bool AsyncWebServerRequest::authenticate(const char *username, const char *password) const {
   if (username == nullptr || password == nullptr || *username == 0) {
     return true;
@@ -383,9 +517,18 @@ bool AsyncWebServerRequest::authenticate(const char *username, const char *passw
 
   auto *auth_str = auth.value().c_str();
 
+#ifdef USE_WEBSERVER_AUTH_DIGEST
+  // The build fixed the scheme to Digest, so the Basic path is compiled out entirely.
+  const auto auth_prefix_len = sizeof("Digest ") - 1;
+  if (strncmp("Digest ", auth_str, auth_prefix_len) != 0) {
+    ESP_LOGW(TAG, "Only Digest authorization supported");
+    return false;
+  }
+  return check_digest_auth(username, password, auth.value(), http_method_str(this->method()));
+#else
   const auto auth_prefix_len = sizeof("Basic ") - 1;
   if (strncmp("Basic ", auth_str, auth_prefix_len) != 0) {
-    ESP_LOGW(TAG, "Only Basic authorization supported yet");
+    ESP_LOGW(TAG, "Only Basic authorization supported");
     return false;
   }
 
@@ -434,16 +577,33 @@ bool AsyncWebServerRequest::authenticate(const char *username, const char *passw
     result |= static_cast<uint8_t>(digest[i] ^ provided_ch);
   }
   return result == 0;
+#endif  // USE_WEBSERVER_AUTH_DIGEST
 }
 
-void AsyncWebServerRequest::requestAuthentication(const char *realm) const {
+void AsyncWebServerRequest::requestAuthentication() const {
   httpd_resp_set_hdr(*this, "Connection", "keep-alive");
-  // Note: realm is never configured in ESPHome, always nullptr -> "Login Required"
-  (void) realm;  // Unused - always use default
+#ifdef USE_WEBSERVER_AUTH_DIGEST
+  // Issue a fresh random nonce and opaque. The nonce is not stored, so this is stateless and
+  // does not defend against replay -- its purpose is to keep the password off the wire.
+  // The header value must stay alive until httpd_resp_send_err() below sends it, so the buffer
+  // lives on this stack frame (httpd_resp_set_hdr stores the pointer, it does not copy).
+  uint8_t random_bytes[16];
+  char nonce[33];
+  char opaque[33];
+  char header[160];
+  esp_fill_random(random_bytes, sizeof(random_bytes));
+  bytes_to_hex(random_bytes, sizeof(random_bytes), nonce);
+  esp_fill_random(random_bytes, sizeof(random_bytes));
+  bytes_to_hex(random_bytes, sizeof(random_bytes), opaque);
+  snprintf(header, sizeof(header), R"(Digest realm="Login Required", qop="auth", nonce="%s", opaque="%s")", nonce,
+           opaque);
+  httpd_resp_set_hdr(*this, "WWW-Authenticate", header);
+#else
   httpd_resp_set_hdr(*this, "WWW-Authenticate", "Basic realm=\"Login Required\"");
+#endif  // USE_WEBSERVER_AUTH_DIGEST
   httpd_resp_send_err(*this, HTTPD_401_UNAUTHORIZED, nullptr);
 }
-#endif
+#endif  // USE_WEBSERVER_AUTH
 
 AsyncWebParameter *AsyncWebServerRequest::getParam(const char *name) {
   // Check cache first - only successful lookups are cached
diff --git a/esphome/components/web_server_idf/web_server_idf.h b/esphome/components/web_server_idf/web_server_idf.h
index 8b5fd5b726..baa55898bb 100644
--- a/esphome/components/web_server_idf/web_server_idf.h
+++ b/esphome/components/web_server_idf/web_server_idf.h
@@ -129,7 +129,7 @@ class AsyncWebServerRequest {
 #ifdef USE_WEBSERVER_AUTH
   bool authenticate(const char *username, const char *password) const;
   // NOLINTNEXTLINE(readability-identifier-naming)
-  void requestAuthentication(const char *realm = nullptr) const;
+  void requestAuthentication() const;
 #endif
 
   void redirect(const std::string &url);
diff --git a/esphome/core/defines.h b/esphome/core/defines.h
index 78f7769cf6..5c5fc5e8b9 100644
--- a/esphome/core/defines.h
+++ b/esphome/core/defines.h
@@ -298,6 +298,7 @@
 #define USE_VOICE_ASSISTANT
 #define USE_WEBSERVER
 #define USE_WEBSERVER_AUTH
+#define USE_WEBSERVER_AUTH_DIGEST
 #define USE_WEBSERVER_OTA
 #define USE_WEBSERVER_PORT 80  // NOLINT
 #define USE_WEBSERVER_GZIP
@@ -408,6 +409,7 @@
 
 #define USE_WEBSERVER
 #define USE_WEBSERVER_AUTH
+#define USE_WEBSERVER_AUTH_DIGEST
 #define USE_WEBSERVER_PORT 80  // NOLINT
 #endif
 
@@ -438,6 +440,7 @@
 #define USE_LWIP_FAST_SELECT
 #define USE_WEBSERVER
 #define USE_WEBSERVER_AUTH
+#define USE_WEBSERVER_AUTH_DIGEST
 #define USE_WEBSERVER_PORT 80  // NOLINT
 #define USE_ESPHOME_TASK_LOG_BUFFER
 #define ESPHOME_TASK_LOG_BUFFER_SIZE 768
diff --git a/tests/component_tests/web_server/test_web_server_auth.py b/tests/component_tests/web_server/test_web_server_auth.py
new file mode 100644
index 0000000000..82635b26da
--- /dev/null
+++ b/tests/component_tests/web_server/test_web_server_auth.py
@@ -0,0 +1,65 @@
+"""Tests for web_server authentication codegen."""
+
+from collections.abc import Callable
+
+import pytest
+
+from esphome.core import CORE
+
+_DEFAULT_CHANGE_WARNING = "default will change to 'digest' in ESPHome 2027.1.0"
+
+
+def _has_define(name: str) -> bool:
+    return any(d.name == name for d in CORE.defines)
+
+
+def test_web_server_auth_default_is_basic_with_deprecation_warning(
+    generate_main: Callable[[str], str],
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Auth without an explicit type builds Basic and warns about the upcoming default change."""
+    main_cpp = generate_main(
+        "tests/component_tests/web_server/web_server_auth_default.yaml"
+    )
+
+    assert '->set_auth_username("admin");' in main_cpp
+    assert '->set_auth_password("password");' in main_cpp
+    assert _has_define("USE_WEBSERVER_AUTH")
+    assert not _has_define("USE_WEBSERVER_AUTH_DIGEST")
+    assert _DEFAULT_CHANGE_WARNING in caplog.text
+
+
+def test_web_server_auth_explicit_basic_no_warning(
+    generate_main: Callable[[str], str],
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Auth type basic builds Basic and does not warn."""
+    generate_main("tests/component_tests/web_server/web_server_auth_basic.yaml")
+
+    assert _has_define("USE_WEBSERVER_AUTH")
+    assert not _has_define("USE_WEBSERVER_AUTH_DIGEST")
+    assert _DEFAULT_CHANGE_WARNING not in caplog.text
+
+
+def test_web_server_auth_explicit_digest(
+    generate_main: Callable[[str], str],
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Auth type digest builds Digest and does not warn."""
+    generate_main("tests/component_tests/web_server/web_server_auth_digest.yaml")
+
+    assert _has_define("USE_WEBSERVER_AUTH")
+    assert _has_define("USE_WEBSERVER_AUTH_DIGEST")
+    assert _DEFAULT_CHANGE_WARNING not in caplog.text
+
+
+def test_web_server_without_auth(
+    generate_main: Callable[[str], str],
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Without an auth block, no auth is compiled in and no warning is emitted."""
+    generate_main("tests/component_tests/web_server/web_server_no_auth.yaml")
+
+    assert not _has_define("USE_WEBSERVER_AUTH")
+    assert not _has_define("USE_WEBSERVER_AUTH_DIGEST")
+    assert _DEFAULT_CHANGE_WARNING not in caplog.text
diff --git a/tests/component_tests/web_server/web_server_auth_basic.yaml b/tests/component_tests/web_server/web_server_auth_basic.yaml
new file mode 100644
index 0000000000..70180f9fbc
--- /dev/null
+++ b/tests/component_tests/web_server/web_server_auth_basic.yaml
@@ -0,0 +1,18 @@
+---
+esphome:
+  name: test
+
+esp32:
+  board: nodemcu-32s
+  framework:
+    type: esp-idf
+
+wifi:
+  ssid: MySSID
+  password: password1
+
+web_server:
+  auth:
+    username: admin
+    password: password
+    type: basic
diff --git a/tests/component_tests/web_server/web_server_auth_default.yaml b/tests/component_tests/web_server/web_server_auth_default.yaml
new file mode 100644
index 0000000000..076180ab79
--- /dev/null
+++ b/tests/component_tests/web_server/web_server_auth_default.yaml
@@ -0,0 +1,17 @@
+---
+esphome:
+  name: test
+
+esp32:
+  board: nodemcu-32s
+  framework:
+    type: esp-idf
+
+wifi:
+  ssid: MySSID
+  password: password1
+
+web_server:
+  auth:
+    username: admin
+    password: password
diff --git a/tests/component_tests/web_server/web_server_auth_digest.yaml b/tests/component_tests/web_server/web_server_auth_digest.yaml
new file mode 100644
index 0000000000..f413787601
--- /dev/null
+++ b/tests/component_tests/web_server/web_server_auth_digest.yaml
@@ -0,0 +1,18 @@
+---
+esphome:
+  name: test
+
+esp32:
+  board: nodemcu-32s
+  framework:
+    type: esp-idf
+
+wifi:
+  ssid: MySSID
+  password: password1
+
+web_server:
+  auth:
+    username: admin
+    password: password
+    type: digest
diff --git a/tests/component_tests/web_server/web_server_no_auth.yaml b/tests/component_tests/web_server/web_server_no_auth.yaml
new file mode 100644
index 0000000000..1c7823b4ae
--- /dev/null
+++ b/tests/component_tests/web_server/web_server_no_auth.yaml
@@ -0,0 +1,14 @@
+---
+esphome:
+  name: test
+
+esp32:
+  board: nodemcu-32s
+  framework:
+    type: esp-idf
+
+wifi:
+  ssid: MySSID
+  password: password1
+
+web_server:
diff --git a/tests/components/web_server/test.esp32-idf.yaml b/tests/components/web_server/test.esp32-idf.yaml
index 858e3b0190..2e091b905a 100644
--- a/tests/components/web_server/test.esp32-idf.yaml
+++ b/tests/components/web_server/test.esp32-idf.yaml
@@ -5,3 +5,4 @@ web_server:
   auth:
     username: admin
     password: password
+    type: digest
diff --git a/tests/components/web_server/test.esp8266-ard.yaml b/tests/components/web_server/test.esp8266-ard.yaml
index 11ad5456ef..2e091b905a 100644
--- a/tests/components/web_server/test.esp8266-ard.yaml
+++ b/tests/components/web_server/test.esp8266-ard.yaml
@@ -1,2 +1,8 @@
 packages:
   web_server: !include common_v2.yaml
+
+web_server:
+  auth:
+    username: admin
+    password: password
+    type: digest
diff --git a/tests/components/web_server/test.rp2040-ard.yaml b/tests/components/web_server/test.rp2040-ard.yaml
index 11ad5456ef..e4d50d7776 100644
--- a/tests/components/web_server/test.rp2040-ard.yaml
+++ b/tests/components/web_server/test.rp2040-ard.yaml
@@ -1,2 +1,8 @@
 packages:
   web_server: !include common_v2.yaml
+
+web_server:
+  auth:
+    username: admin
+    password: password
+    type: basic
diff --git a/tests/components/web_server/validate.esp32-idf.yaml b/tests/components/web_server/validate.esp32-idf.yaml
new file mode 100644
index 0000000000..e4d50d7776
--- /dev/null
+++ b/tests/components/web_server/validate.esp32-idf.yaml
@@ -0,0 +1,8 @@
+packages:
+  web_server: !include common_v2.yaml
+
+web_server:
+  auth:
+    username: admin
+    password: password
+    type: basic

From 49bbceb1dad7be50364ad5db11d4796df0061d59 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Mon, 13 Jul 2026 13:51:54 -1000
Subject: [PATCH 04/24] [libretiny] Keep renamed board generic-ln882hki
 validating against generic-ln882h (#17542)

---
 esphome/components/libretiny/__init__.py      | 15 ++++++
 tests/unit_tests/components/test_libretiny.py | 52 +++++++++++++++++++
 2 files changed, 67 insertions(+)
 create mode 100644 tests/unit_tests/components/test_libretiny.py

diff --git a/esphome/components/libretiny/__init__.py b/esphome/components/libretiny/__init__.py
index 3fde11b1eb..62cef331fd 100644
--- a/esphome/components/libretiny/__init__.py
+++ b/esphome/components/libretiny/__init__.py
@@ -76,12 +76,27 @@ _BLE5_BK_SYS_CONFIG_OPTIONS = [
     "CFG_SUPPORT_BLE=0",
 ]
 
+# Board ids upstream LibreTiny renamed; configs written against the old id
+# keep validating and building against the new one (with a warning).
+# generic-ln882hki -> generic-ln882h: LibreTiny v1.13.0.
+_RENAMED_BOARDS = {
+    "generic-ln882hki": "generic-ln882h",
+}
+
 
 def _detect_variant(value):
     if KEY_LIBRETINY not in CORE.data:
         raise cv.Invalid("Family component didn't populate core data properly!")
     component: LibreTinyComponent = CORE.data[KEY_LIBRETINY][KEY_COMPONENT_DATA]
     board = value[CONF_BOARD]
+    if board not in component.boards and (renamed := _RENAMED_BOARDS.get(board)):
+        _LOGGER.warning(
+            "Board '%s' was renamed to '%s'; please update your configuration",
+            board,
+            renamed,
+        )
+        value = value.copy()
+        value[CONF_BOARD] = board = renamed
     # read board-default family if not specified
     if board not in component.boards:
         if CONF_FAMILY not in value:
diff --git a/tests/unit_tests/components/test_libretiny.py b/tests/unit_tests/components/test_libretiny.py
new file mode 100644
index 0000000000..ee00bdc180
--- /dev/null
+++ b/tests/unit_tests/components/test_libretiny.py
@@ -0,0 +1,52 @@
+"""Tests for LibreTiny board detection, including renamed-board migration."""
+
+import pytest
+
+from esphome.components.libretiny import _detect_variant
+from esphome.components.libretiny.const import (
+    FAMILY_LN882H,
+    KEY_COMPONENT_DATA,
+    KEY_LIBRETINY,
+)
+from esphome.components.ln882x import COMPONENT_DATA
+import esphome.config_validation as cv
+from esphome.const import CONF_BOARD, CONF_FAMILY
+from esphome.core import CORE
+
+
+@pytest.fixture
+def ln882x_core_data() -> None:
+    """Populate CORE the way the ln882x component schema does."""
+    CORE.data[KEY_LIBRETINY] = {KEY_COMPONENT_DATA: COMPONENT_DATA}
+
+
+def test_detect_variant_known_board_passes(ln882x_core_data: None) -> None:
+    """A current board id resolves its family without warnings."""
+    result = _detect_variant({CONF_BOARD: "generic-ln882h"})
+    assert result[CONF_BOARD] == "generic-ln882h"
+    assert result[CONF_FAMILY] == FAMILY_LN882H
+
+
+def test_detect_variant_renamed_board_migrates(
+    ln882x_core_data: None, caplog: pytest.LogCaptureFixture
+) -> None:
+    """A pre-rename board id validates against the new id, with a warning."""
+    result = _detect_variant({CONF_BOARD: "generic-ln882hki"})
+    assert result[CONF_BOARD] == "generic-ln882h"
+    assert result[CONF_FAMILY] == FAMILY_LN882H
+    assert "renamed to 'generic-ln882h'" in caplog.text
+
+
+def test_detect_variant_renamed_board_does_not_mutate_input(
+    ln882x_core_data: None,
+) -> None:
+    """Migration copies the config; the caller's dict keeps the old id."""
+    value = {CONF_BOARD: "generic-ln882hki"}
+    _detect_variant(value)
+    assert value[CONF_BOARD] == "generic-ln882hki"
+
+
+def test_detect_variant_unknown_board_still_raises(ln882x_core_data: None) -> None:
+    """Ids outside the rename map keep the family-override error."""
+    with pytest.raises(cv.Invalid, match="This board is unknown"):
+        _detect_variant({CONF_BOARD: "not-a-real-board"})

From f1e4726f4e38a464a26cbed4bbdbc95cfe6d11d7 Mon Sep 17 00:00:00 2001
From: Jonathan Swoboda <154711427+swoboda1337@users.noreply.github.com>
Date: Mon, 13 Jul 2026 19:53:31 -0400
Subject: [PATCH 05/24] [veml7700][as7341][ltr501] Fix device class on
 raw-count sensors (#17549)

---
 esphome/components/as7341/sensor.py   |  4 ++--
 esphome/components/ltr501/sensor.py   | 10 +++++-----
 esphome/components/veml7700/sensor.py |  5 +++--
 3 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/esphome/components/as7341/sensor.py b/esphome/components/as7341/sensor.py
index fa51a1cdfa..8b6cf61028 100644
--- a/esphome/components/as7341/sensor.py
+++ b/esphome/components/as7341/sensor.py
@@ -5,7 +5,7 @@ from esphome.const import (
     CONF_CLEAR,
     CONF_GAIN,
     CONF_ID,
-    DEVICE_CLASS_ILLUMINANCE,
+    DEVICE_CLASS_EMPTY,
     ICON_BRIGHTNESS_5,
     STATE_CLASS_MEASUREMENT,
 )
@@ -54,7 +54,7 @@ SENSOR_SCHEMA = sensor.sensor_schema(
     unit_of_measurement=UNIT_COUNTS,
     icon=ICON_BRIGHTNESS_5,
     accuracy_decimals=0,
-    device_class=DEVICE_CLASS_ILLUMINANCE,
+    device_class=DEVICE_CLASS_EMPTY,
     state_class=STATE_CLASS_MEASUREMENT,
 )
 
diff --git a/esphome/components/ltr501/sensor.py b/esphome/components/ltr501/sensor.py
index cca9330e76..c1fa9009b3 100644
--- a/esphome/components/ltr501/sensor.py
+++ b/esphome/components/ltr501/sensor.py
@@ -15,7 +15,7 @@ from esphome.const import (
     CONF_NAME,
     CONF_REPEAT,
     CONF_TYPE,
-    DEVICE_CLASS_DISTANCE,
+    DEVICE_CLASS_EMPTY,
     DEVICE_CLASS_ILLUMINANCE,
     ICON_BRIGHTNESS_5,
     ICON_BRIGHTNESS_6,
@@ -159,7 +159,7 @@ CONFIG_SCHEMA = cv.All(
                     unit_of_measurement=UNIT_COUNTS,
                     icon=ICON_BRIGHTNESS_5,
                     accuracy_decimals=0,
-                    device_class=DEVICE_CLASS_ILLUMINANCE,
+                    device_class=DEVICE_CLASS_EMPTY,
                     state_class=STATE_CLASS_MEASUREMENT,
                 ),
                 key=CONF_NAME,
@@ -169,7 +169,7 @@ CONFIG_SCHEMA = cv.All(
                     unit_of_measurement=UNIT_COUNTS,
                     icon=ICON_BRIGHTNESS_7,
                     accuracy_decimals=0,
-                    device_class=DEVICE_CLASS_ILLUMINANCE,
+                    device_class=DEVICE_CLASS_EMPTY,
                     state_class=STATE_CLASS_MEASUREMENT,
                 ),
                 key=CONF_NAME,
@@ -179,7 +179,7 @@ CONFIG_SCHEMA = cv.All(
                     unit_of_measurement=UNIT_COUNTS,
                     icon=ICON_PROXIMITY,
                     accuracy_decimals=0,
-                    device_class=DEVICE_CLASS_DISTANCE,
+                    device_class=DEVICE_CLASS_EMPTY,
                     state_class=STATE_CLASS_MEASUREMENT,
                 ),
                 key=CONF_NAME,
@@ -188,7 +188,7 @@ CONFIG_SCHEMA = cv.All(
                 sensor.sensor_schema(
                     icon=ICON_GAIN,
                     accuracy_decimals=0,
-                    device_class=DEVICE_CLASS_ILLUMINANCE,
+                    device_class=DEVICE_CLASS_EMPTY,
                     state_class=STATE_CLASS_MEASUREMENT,
                 ),
                 key=CONF_NAME,
diff --git a/esphome/components/veml7700/sensor.py b/esphome/components/veml7700/sensor.py
index 6ad2eb417f..d0d3584dc2 100644
--- a/esphome/components/veml7700/sensor.py
+++ b/esphome/components/veml7700/sensor.py
@@ -14,6 +14,7 @@ from esphome.const import (
     CONF_INFRARED,
     CONF_INTEGRATION_TIME,
     CONF_NAME,
+    DEVICE_CLASS_EMPTY,
     DEVICE_CLASS_ILLUMINANCE,
     ICON_BRIGHTNESS_5,
     ICON_BRIGHTNESS_6,
@@ -91,7 +92,7 @@ CONFIG_SCHEMA = cv.All(
                     unit_of_measurement=UNIT_COUNTS,
                     icon=ICON_BRIGHTNESS_6,
                     accuracy_decimals=0,
-                    device_class=DEVICE_CLASS_ILLUMINANCE,
+                    device_class=DEVICE_CLASS_EMPTY,
                     state_class=STATE_CLASS_MEASUREMENT,
                 ),
                 key=CONF_NAME,
@@ -111,7 +112,7 @@ CONFIG_SCHEMA = cv.All(
                     unit_of_measurement=UNIT_COUNTS,
                     icon=ICON_BRIGHTNESS_7,
                     accuracy_decimals=0,
-                    device_class=DEVICE_CLASS_ILLUMINANCE,
+                    device_class=DEVICE_CLASS_EMPTY,
                     state_class=STATE_CLASS_MEASUREMENT,
                 ),
                 key=CONF_NAME,

From ca77cc585c6d3a00ddfd1b6eb1405924a13904a8 Mon Sep 17 00:00:00 2001
From: Keith Burzinski <kbx81x@gmail.com>
Date: Mon, 13 Jul 2026 18:56:03 -0500
Subject: [PATCH 06/24] [nextion] Fix unbounded queue growth and OOM crash when
 display sends no data (#17553)

---
 esphome/components/nextion/nextion.cpp | 32 +++++++++++++++++++-------
 esphome/components/nextion/nextion.h   |  4 ++++
 2 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/esphome/components/nextion/nextion.cpp b/esphome/components/nextion/nextion.cpp
index 4ebc717552..bdc66adb70 100644
--- a/esphome/components/nextion/nextion.cpp
+++ b/esphome/components/nextion/nextion.cpp
@@ -1,6 +1,7 @@
 #include "nextion.h"
 
 #include <cinttypes>
+#include <new>
 
 #include "esphome/core/application.h"
 #include "esphome/core/helpers.h"
@@ -352,8 +353,9 @@ void Nextion::loop() {
     this->connection_state_.ignore_is_setup_ = false;
   }
 
-  this->process_serial_();            // Receive serial data
-  this->process_nextion_commands_();  // Process nextion return commands
+  this->process_serial_();             // Receive serial data
+  this->process_nextion_commands_();   // Process nextion return commands
+  this->purge_stale_queue_entries_();  // Drop expired entries even when the display sends no data
 
   if (!this->connection_state_.nextion_reports_is_setup_) {
     if (this->started_ms_ == 0)
@@ -902,6 +904,11 @@ void Nextion::process_nextion_commands_() {
     this->command_data_.erase(0, to_process_length + DELIMITER_SIZE + 1);
   }
 
+  ESP_LOGN(TAG, "Loop end");
+  this->process_serial_();
+}  // Nextion::process_nextion_commands_()
+
+void Nextion::purge_stale_queue_entries_() {
   const uint32_t ms = App.get_loop_component_start_time();
 
   if (this->max_q_age_ms_ > 0 && !this->nextion_queue_.empty() &&
@@ -927,10 +934,7 @@ void Nextion::process_nextion_commands_() {
       }
     }
   }
-  ESP_LOGN(TAG, "Loop end");
-  // App.feed_wdt(); Remove before master merge
-  this->process_serial_();
-}  // Nextion::process_nextion_commands_()
+}
 
 void Nextion::set_nextion_sensor_state(int queue_type, const std::string &name, float state) {
   this->set_nextion_sensor_state(static_cast<NextionQueueType>(queue_type), name, state);
@@ -1101,7 +1105,13 @@ void Nextion::add_no_result_to_queue_(const std::string &variable_name) {
   new (nextion_queue) nextion::NextionQueue();
 
   // NOLINTNEXTLINE(cppcoreguidelines-owning-memory)
-  nextion_queue->component = new nextion::NextionComponentBase;
+  nextion_queue->component = new (std::nothrow) nextion::NextionComponentBase;
+  if (nextion_queue->component == nullptr) {
+    ESP_LOGW(TAG, "Component alloc failed");
+    nextion_queue->~NextionQueue();
+    allocator.deallocate(nextion_queue, 1);
+    return;
+  }
   nextion_queue->component->set_variable_name(variable_name);
 
   nextion_queue->queue_time = App.get_loop_component_start_time();
@@ -1157,7 +1167,13 @@ void Nextion::add_no_result_to_queue_with_pending_command_(const std::string &va
   }
   new (nextion_queue) nextion::NextionQueue();
 
-  nextion_queue->component = new nextion::NextionComponentBase;
+  nextion_queue->component = new (std::nothrow) nextion::NextionComponentBase;
+  if (nextion_queue->component == nullptr) {
+    ESP_LOGW(TAG, "Component alloc failed");
+    nextion_queue->~NextionQueue();
+    allocator.deallocate(nextion_queue, 1);
+    return;
+  }
   nextion_queue->component->set_variable_name(variable_name);
   nextion_queue->queue_time = App.get_loop_component_start_time();
   nextion_queue->pending_command = command;  // Store command for retry
diff --git a/esphome/components/nextion/nextion.h b/esphome/components/nextion/nextion.h
index d361d9725b..7dc5a4fe44 100644
--- a/esphome/components/nextion/nextion.h
+++ b/esphome/components/nextion/nextion.h
@@ -1486,6 +1486,10 @@ class Nextion final : public NextionBase, public PollingComponent, public uart::
 
   void process_nextion_commands_();
   void process_serial_();
+  /// Drop queue entries older than max_q_age_ms_. Called from loop() so it also runs when the
+  /// display sends no data at all (disconnected or asleep), which would otherwise grow the queue
+  /// without bound.
+  void purge_stale_queue_entries_();
   uint16_t touch_sleep_timeout_ = 0;
   uint8_t wake_up_page_ = 255;
 #ifdef USE_NEXTION_CONF_START_UP_PAGE

From 3e75020007e598fdf1794867565825cdf36c97fd Mon Sep 17 00:00:00 2001
From: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
Date: Mon, 13 Jul 2026 15:28:55 +1200
Subject: [PATCH 07/24] [gsl3670] Fix i2c package variant in esp32-s3-idf test
 (#17535)

---
 tests/components/gsl3670/test.esp32-s3-idf.yaml | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/tests/components/gsl3670/test.esp32-s3-idf.yaml b/tests/components/gsl3670/test.esp32-s3-idf.yaml
index 48bb9982d9..5c3f4b931c 100644
--- a/tests/components/gsl3670/test.esp32-s3-idf.yaml
+++ b/tests/components/gsl3670/test.esp32-s3-idf.yaml
@@ -1,5 +1,5 @@
 packages:
-  i2c: !include ../../test_build_components/common/i2c/esp32-idf.yaml
+  i2c: !include ../../test_build_components/common/i2c/esp32-s3-idf.yaml
   spi: !include ../../test_build_components/common/spi/esp32-s3-idf.yaml
 
 xl9535:
@@ -10,6 +10,9 @@ display:
     id: gsl3670_display
     spi_id: spi_bus
     model: t-display-s3-pro
+    # The model's default DC pin (GPIO9) clashes with the shared i2c bus SCL
+    # pin, so override it onto a free pin for this test.
+    dc_pin: GPIO5
 
 psram:
   mode: quad

From f38e7f2de21b72122d53552966d4ff073265661d Mon Sep 17 00:00:00 2001
From: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
Date: Mon, 13 Jul 2026 15:38:48 +1200
Subject: [PATCH 08/24] [web_server] Add CORS origin checking with
 allowed_origins (#17530)

---
 THREAT_MODEL.md                               | 46 ++++++++++
 esphome/components/web_server/__init__.py     | 46 +++++++++-
 esphome/components/web_server/web_server.cpp  | 71 +++++++++++++--
 esphome/components/web_server/web_server.h    | 26 ++++++
 esphome/core/defines.h                        |  1 +
 .../web_server/test_private_network_access.py | 86 +++++++++++++++++++
 tests/components/web_server/common_v2.yaml    |  3 +
 tests/components/web_server/common_v3.yaml    |  3 +
 8 files changed, 274 insertions(+), 8 deletions(-)
 create mode 100644 tests/component_tests/web_server/test_private_network_access.py

diff --git a/THREAT_MODEL.md b/THREAT_MODEL.md
index a4355a5055..5816f38176 100644
--- a/THREAT_MODEL.md
+++ b/THREAT_MODEL.md
@@ -79,6 +79,48 @@ These *are* security bugs in this repo, and we want to hear about them privately
 - Flaws that weaken the device's API encryption (Noise), OTA, or web server auth
   below their documented guarantees.
 
+## The web server is an open HTTP API by design
+
+The `web_server` component exposes a plain HTTP interface for viewing and
+controlling entities, and, when the `web_server` OTA platform is enabled, for
+uploading firmware at `/update`. Its only access controls are the optional
+`web_server` `auth:` credentials and the network the device sits on.
+
+When `auth:` is not configured, every endpoint is reachable by any client that
+can reach the device. This is intentional; enabling `web_server` without `auth:`
+is choosing an open control surface, in the same way that running native OTA
+without a password leaves OTA open. The API is documented and is meant to be
+called by other devices, scripts, and pages.
+
+As defense-in-depth, the web server checks the `Origin` header on browser requests
+to its entity control and state endpoints: a request whose `Origin` does not match
+the address the device is served on is rejected, and the `allowed_origins` option
+widens that list. This blocks the common "confused deputy" (CSRF) case where a page
+the operator visits drives the device through their browser. It is **not** an
+authentication boundary: it only constrains browsers. Any client that omits the
+`Origin` header — `curl`, scripts, or other non-browser callers on the same
+network — reaches every endpoint exactly as before. The check also does not cover
+the web OTA `/update` endpoint. The device performs no CSRF-token or `Referer`
+validation. The following are therefore **not** vulnerabilities in this repository:
+
+- Requests without an `Origin` header (for example `curl`) reaching the control
+  endpoints, whether or not `web_server` `auth:` is set.
+- Requests from an origin the operator added to `allowed_origins`.
+- Cross-origin or CSRF firmware upload through the web OTA endpoint (`/update`) when
+  web OTA is enabled without `web_server` `auth:`. The `/update` endpoint is not
+  covered by the `Origin` check; this is the same exposure as running OTA without a
+  password.
+
+The supported defenses are `web_server` `auth:`, protecting OTA (a web password or
+a native OTA password), and keeping devices on a trusted, segmented network. See
+the security best practices guide linked above.
+
+What remains in scope is bypassing `web_server` `auth:` when it *is* configured,
+and any memory-safety or protocol bug in the server reachable without credentials.
+
+This section documents the current design and scope; it is not a judgment that the
+design is optimal or that it will not change.
+
 ## Explicitly out of scope
 
 - Local attackers who already have shell access on the host that runs `esphome`.
@@ -86,6 +128,10 @@ These *are* security bugs in this repo, and we want to hear about them privately
 - Operator-supplied hostile YAML (covered above — config authoring is trusted).
 - Attacks that require an already-authenticated device peer (someone who already
   holds the API key / OTA / web credentials).
+- Access to the device web server or its web OTA endpoint by non-browser clients
+  (those that send no `Origin` header). The web server is an open HTTP API by
+  design (see above); browser cross-origin requests are blocked by default, but the
+  real controls are `web_server` `auth:` and network isolation.
 - Anything in the dashboard / device-builder — report that in its own repository
   (linked at the top).
 - Deployments where the operator removed protections or exposed credentials. See
diff --git a/esphome/components/web_server/__init__.py b/esphome/components/web_server/__init__.py
index d9fd27dbc2..68f1c18072 100644
--- a/esphome/components/web_server/__init__.py
+++ b/esphome/components/web_server/__init__.py
@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import gzip
 import logging
+import re
 
 import esphome.codegen as cg
 from esphome.components import web_server_base
@@ -46,6 +47,7 @@ AUTO_LOAD = ["json", "web_server_base"]
 CONF_SORTING_GROUP_ID = "sorting_group_id"
 CONF_SORTING_GROUPS = "sorting_groups"
 CONF_SORTING_WEIGHT = "sorting_weight"
+CONF_ALLOWED_ORIGINS = "allowed_origins"
 
 
 web_server_ns = cg.esphome_ns.namespace("web_server")
@@ -104,6 +106,41 @@ def validate_ota(config: ConfigType) -> ConfigType:
     return config
 
 
+# An Origin header is always "scheme://host[:port]" with no path or trailing slash.
+_ORIGIN_RE = re.compile(r"^[a-zA-Z][a-zA-Z0-9+.-]*://[^/\s]+$")
+
+
+def validate_origin(value: str) -> str:
+    # "*" is the wildcard that allows any origin.
+    if value == "*":
+        return value
+    value = cv.string_strict(value)
+    if not _ORIGIN_RE.match(value):
+        raise cv.Invalid(
+            f"'{value}' is not a valid origin. An origin must be 'scheme://host[:port]' with no "
+            f"path or trailing slash (e.g. 'https://example.com'), or '*' to allow any origin."
+        )
+    # Browsers send the scheme and host lowercased in the Origin header, so normalize to match.
+    return value.lower()
+
+
+def validate_private_network_access(config: ConfigType) -> ConfigType:
+    # PNA preflights are always cross-origin, so they can only be authorized against the
+    # allowed_origins list. Enabling PNA without any origins would deny every PNA request.
+    if (
+        config[CONF_ENABLE_PRIVATE_NETWORK_ACCESS]
+        and config.get(CONF_ALLOWED_ORIGINS) is None
+    ):
+        raise cv.Invalid(
+            f"'{CONF_ALLOWED_ORIGINS}' must be set when "
+            f"'{CONF_ENABLE_PRIVATE_NETWORK_ACCESS}' is enabled. List each origin that is "
+            f"allowed to reach the device (e.g. 'https://example.com'). '*' allows any origin "
+            f"but is not recommended.",
+            path=[CONF_ENABLE_PRIVATE_NETWORK_ACCESS],
+        )
+    return config
+
+
 def validate_sorting_groups(config: ConfigType) -> ConfigType:
     if CONF_SORTING_GROUPS in config and config[CONF_VERSION] != 3:
         raise cv.Invalid(
@@ -201,7 +238,10 @@ CONFIG_SCHEMA = cv.All(
             cv.Optional(CONF_CSS_INCLUDE): cv.file_,
             cv.Optional(CONF_JS_URL): cv.string,
             cv.Optional(CONF_JS_INCLUDE): cv.file_,
-            cv.Optional(CONF_ENABLE_PRIVATE_NETWORK_ACCESS, default=True): cv.boolean,
+            cv.Optional(CONF_ENABLE_PRIVATE_NETWORK_ACCESS, default=False): cv.boolean,
+            cv.Optional(CONF_ALLOWED_ORIGINS): cv.All(
+                cv.ensure_list(validate_origin), cv.Length(min=1)
+            ),
             cv.Optional(CONF_AUTH): cv.Schema(
                 {
                     cv.Required(CONF_USERNAME): cv.All(
@@ -238,6 +278,7 @@ CONFIG_SCHEMA = cv.All(
     validate_local,
     validate_sorting_groups,
     validate_ota,
+    validate_private_network_access,
     _consume_web_server_sockets,
 )
 
@@ -334,6 +375,9 @@ async def to_code(config):
         request_log_listener()  # Request a log listener slot for web server log streaming
     if config[CONF_ENABLE_PRIVATE_NETWORK_ACCESS]:
         cg.add_define("USE_WEBSERVER_PRIVATE_NETWORK_ACCESS")
+    if (allowed_origins := config.get(CONF_ALLOWED_ORIGINS)) is not None:
+        cg.add_define("USE_WEBSERVER_ALLOWED_ORIGINS")
+        cg.add(var.set_allowed_origins(allowed_origins))
     if CONF_AUTH in config:
         cg.add_define("USE_WEBSERVER_AUTH")
         cg.add(paren.set_auth_username(config[CONF_AUTH][CONF_USERNAME]))
diff --git a/esphome/components/web_server/web_server.cpp b/esphome/components/web_server/web_server.cpp
index 3bba879823..1e6c4e8c62 100644
--- a/esphome/components/web_server/web_server.cpp
+++ b/esphome/components/web_server/web_server.cpp
@@ -456,9 +456,58 @@ void WebServer::handle_index_request(AsyncWebServerRequest *request) {
 }
 #endif
 
+// Read a request header value portably across the Arduino and ESP-IDF web servers.
+// Returns an empty string when the header is absent (only allocates when a value is present).
+static std::string get_request_header(AsyncWebServerRequest *request, const char *name) {
+#ifdef USE_ESP32
+  // ESP32 (Arduino and ESP-IDF) uses the web_server_idf backend.
+  optional<std::string> value = request->get_header(name);
+  return value.has_value() ? std::move(*value) : std::string();
+#else
+  // ESP8266, RP2040 and LibreTiny use the Arduino ESPAsyncWebServer backend.
+  const AsyncWebHeader *header = request->getHeader(name);
+  return header != nullptr ? std::string(header->value().c_str()) : std::string();
+#endif
+}
+
+bool WebServer::is_request_origin_allowed_(AsyncWebServerRequest *request, const std::string &origin) {
+  // No Origin header: not a browser cross-origin request (e.g. curl, native API client). Allow.
+  if (origin.empty())
+    return true;
+
+  // Same-origin: the Origin authority (scheme stripped) matches the Host the request was sent to.
+  // This covers the device's own IP, mDNS name, or DNS name without knowing any at compile time.
+  const size_t scheme_sep = origin.find("://");
+  if (scheme_sep != std::string::npos) {
+    const std::string host = get_request_header(request, "Host");
+    if (!host.empty() && origin.compare(scheme_sep + 3, std::string::npos, host) == 0)
+      return true;
+  }
+
+#ifdef USE_WEBSERVER_ALLOWED_ORIGINS
+  // Otherwise the origin must be explicitly allowed via configuration.
+  for (const char *allowed_origin : this->allowed_origins_) {
+    // A single "*" entry allows any origin.
+    if (allowed_origin[0] == '*' && allowed_origin[1] == '\0')
+      return true;
+    if (origin == allowed_origin)
+      return true;
+  }
+#endif
+  return false;
+}
+
 #ifdef USE_WEBSERVER_PRIVATE_NETWORK_ACCESS
 void WebServer::handle_pna_cors_request(AsyncWebServerRequest *request) {
+  const std::string origin = get_request_header(request, "Origin");
+  if (!this->is_request_origin_allowed_(request, origin)) {
+    request->send(403);
+    return;
+  }
+
   AsyncWebServerResponse *response = request->beginResponse(200, ESPHOME_F(""));
+  // Echo the specific origin back so the response is valid even when auth (credentials) is enabled.
+  response->addHeader(ESPHOME_F("Access-Control-Allow-Origin"), origin.empty() ? "*" : origin.c_str());
   response->addHeader(ESPHOME_F("Access-Control-Allow-Private-Network"), ESPHOME_F("true"));
   response->addHeader(ESPHOME_F("Private-Network-Access-Name"), App.get_name().c_str());
   char mac_s[18];
@@ -2448,6 +2497,21 @@ void WebServer::handleRequest(AsyncWebServerRequest *request) {
     return;
   }
 
+#ifdef USE_WEBSERVER_PRIVATE_NETWORK_ACCESS
+  // Private Network Access preflight carries a cross-origin Origin by design; its handler does the
+  // origin check itself, so let it run before the general enforcement below.
+  if (request->method() == HTTP_OPTIONS && request->hasHeader(ESPHOME_F("Access-Control-Request-Private-Network"))) {
+    this->handle_pna_cors_request(request);
+    return;
+  }
+#endif
+
+  // Reject cross-origin browser requests unless the origin is explicitly allowed.
+  if (!this->is_request_origin_allowed_(request, get_request_header(request, "Origin"))) {
+    request->send(403);
+    return;
+  }
+
 #if !defined(USE_ESP32) && defined(USE_ARDUINO)
   if (url == ESPHOME_F("/events")) {
     this->events_.add_new_client(this, request);
@@ -2469,13 +2533,6 @@ void WebServer::handleRequest(AsyncWebServerRequest *request) {
   }
 #endif
 
-#ifdef USE_WEBSERVER_PRIVATE_NETWORK_ACCESS
-  if (request->method() == HTTP_OPTIONS && request->hasHeader(ESPHOME_F("Access-Control-Request-Private-Network"))) {
-    this->handle_pna_cors_request(request);
-    return;
-  }
-#endif
-
   // Parse URL for component routing
   // Pass HTTP method to disambiguate 3-segment URLs (GET=sub-device state, POST=main device action)
   UrlMatch match = match_url(url.c_str(), url.length(), false, request->method() == HTTP_POST);
diff --git a/esphome/components/web_server/web_server.h b/esphome/components/web_server/web_server.h
index 42182fe510..0fbe4ec551 100644
--- a/esphome/components/web_server/web_server.h
+++ b/esphome/components/web_server/web_server.h
@@ -242,6 +242,22 @@ class WebServer final : public Controller, public Component, public AsyncWebHand
    */
   void set_expose_log(bool expose_log) { this->expose_log_ = expose_log; }
 
+#ifdef USE_WEBSERVER_ALLOWED_ORIGINS
+  /** Set the origins that browsers are allowed to make cross-origin requests from.
+   *
+   * Requests without an `Origin` header (e.g. non-browser clients like curl or the native API)
+   * are always allowed. Requests whose `Origin` matches the address the device is served on
+   * (same-origin) are always allowed. Any other browser origin must appear in this list, or the
+   * request is rejected. A single "*" entry allows any origin. Each other entry must exactly match
+   * the requesting page's `Origin` header (e.g. "https://example.com").
+   *
+   * This list is also used to authorize Private Network Access requests when that feature is enabled.
+   *
+   * @param origins The list of allowed origins.
+   */
+  void set_allowed_origins(std::initializer_list<const char *> origins) { this->allowed_origins_ = origins; }
+#endif
+
   // ========== INTERNAL METHODS ==========
   // (In most use cases you won't need these)
   /// Setup the internal web server and register handlers.
@@ -593,6 +609,16 @@ class WebServer final : public Controller, public Component, public AsyncWebHand
   const char *js_include_{nullptr};
 #endif
   bool expose_log_{true};
+#ifdef USE_WEBSERVER_ALLOWED_ORIGINS
+  // Extra origins allowed to make cross-origin browser requests ("*" means any origin).
+  // Only compiled when allowed_origins is configured; same-origin is always allowed regardless.
+  FixedVector<const char *> allowed_origins_;
+#endif
+
+  /// Check whether the given request Origin is permitted. Same-origin (matching the Host the
+  /// request was sent to) and requests without an Origin header are always allowed; any other
+  /// origin must be listed in allowed_origins. The caller passes the already-read Origin header.
+  bool is_request_origin_allowed_(AsyncWebServerRequest *request, const std::string &origin);
 
  private:
 #ifdef USE_SENSOR
diff --git a/esphome/core/defines.h b/esphome/core/defines.h
index bdb0f27f45..78f7769cf6 100644
--- a/esphome/core/defines.h
+++ b/esphome/core/defines.h
@@ -302,6 +302,7 @@
 #define USE_WEBSERVER_PORT 80  // NOLINT
 #define USE_WEBSERVER_GZIP
 #define USE_WEBSERVER_SORTING
+#define USE_WEBSERVER_ALLOWED_ORIGINS
 #define WEB_SERVER_DEFAULT_HEADERS_COUNT 1
 #define USE_CAPTIVE_PORTAL_GZIP
 #define USE_WIFI_11KV_SUPPORT
diff --git a/tests/component_tests/web_server/test_private_network_access.py b/tests/component_tests/web_server/test_private_network_access.py
new file mode 100644
index 0000000000..87911c5f9b
--- /dev/null
+++ b/tests/component_tests/web_server/test_private_network_access.py
@@ -0,0 +1,86 @@
+"""Tests for web_server Private Network Access / allowed_origins validation."""
+
+import pytest
+
+from esphome import config_validation as cv
+from esphome.components.web_server import (
+    CONF_ALLOWED_ORIGINS,
+    validate_origin,
+    validate_private_network_access,
+)
+from esphome.const import CONF_ENABLE_PRIVATE_NETWORK_ACCESS
+from esphome.types import ConfigType
+
+
+def test_pna_enabled_without_origins_fails() -> None:
+    """Enabling PNA without allowed_origins must fail validation."""
+    config: ConfigType = {CONF_ENABLE_PRIVATE_NETWORK_ACCESS: True}
+
+    with pytest.raises(cv.Invalid) as exc_info:
+        validate_private_network_access(config)
+
+    error_msg = str(exc_info.value)
+    assert CONF_ALLOWED_ORIGINS in error_msg
+    assert "must be set" in error_msg
+
+
+def test_pna_enabled_with_origins_passes() -> None:
+    """Enabling PNA with at least one allowed origin passes validation."""
+    config: ConfigType = {
+        CONF_ENABLE_PRIVATE_NETWORK_ACCESS: True,
+        CONF_ALLOWED_ORIGINS: ["https://app.esphome.io"],
+    }
+    assert validate_private_network_access(config) == config
+
+
+def test_origins_without_pna_passes() -> None:
+    """allowed_origins can be set without enabling PNA (they are independent)."""
+    config: ConfigType = {
+        CONF_ENABLE_PRIVATE_NETWORK_ACCESS: False,
+        CONF_ALLOWED_ORIGINS: ["https://app.esphome.io"],
+    }
+    assert validate_private_network_access(config) == config
+
+
+def test_pna_disabled_without_origins_passes() -> None:
+    """PNA disabled and no origins specified passes validation."""
+    config: ConfigType = {CONF_ENABLE_PRIVATE_NETWORK_ACCESS: False}
+    assert validate_private_network_access(config) == config
+
+
+def test_validate_origin_wildcard() -> None:
+    """The '*' wildcard is accepted as-is."""
+    assert validate_origin("*") == "*"
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "https://example.com",
+        "http://example.com:8080",
+        "https://192.168.1.5",
+    ],
+)
+def test_validate_origin_valid(value: str) -> None:
+    """Well-formed origins pass through unchanged."""
+    assert validate_origin(value) == value
+
+
+def test_validate_origin_lowercased() -> None:
+    """Scheme and host are normalized to lowercase to match the browser Origin header."""
+    assert validate_origin("HTTPS://App.Example.com") == "https://app.example.com"
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "https://example.com/",  # trailing slash
+        "https://example.com/path",  # path segment
+        "example.com",  # missing scheme
+        "",  # empty
+    ],
+)
+def test_validate_origin_invalid(value: str) -> None:
+    """Malformed origins are rejected at config time instead of silently 403ing."""
+    with pytest.raises(cv.Invalid, match="not a valid origin"):
+        validate_origin(value)
diff --git a/tests/components/web_server/common_v2.yaml b/tests/components/web_server/common_v2.yaml
index f2b15e484d..b9bc0bbf61 100644
--- a/tests/components/web_server/common_v2.yaml
+++ b/tests/components/web_server/common_v2.yaml
@@ -5,3 +5,6 @@ web_server:
   port: 8080
   version: 2
   compression: br
+  enable_private_network_access: true
+  allowed_origins:
+    - https://app.esphome.io
diff --git a/tests/components/web_server/common_v3.yaml b/tests/components/web_server/common_v3.yaml
index bdacaaddbe..354d7bb6ac 100644
--- a/tests/components/web_server/common_v3.yaml
+++ b/tests/components/web_server/common_v3.yaml
@@ -4,6 +4,9 @@ packages:
 web_server:
   port: 8080
   version: 3
+  # allowed_origins can be set independently of Private Network Access
+  allowed_origins:
+    - https://app.esphome.io
   sorting_groups:
     - id: sorting_group_1
       name: "Group 1 Diplayed Last"

From af9a0404d9b4e32385ccd8cb412512a352870dc2 Mon Sep 17 00:00:00 2001
From: Keith Burzinski <kbx81x@gmail.com>
Date: Sun, 12 Jul 2026 23:23:40 -0500
Subject: [PATCH 09/24] [esp32] Do not require verification_key with Secure
 Boot V2 signing schemes (#17497)

---
 esphome/components/esp32/__init__.py          | 99 +++++++++++++++----
 tests/component_tests/esp32/test_esp32.py     | 75 ++++++++++++++
 ...date-signed_ota_external.esp32-s3-idf.yaml | 11 +++
 3 files changed, 167 insertions(+), 18 deletions(-)
 create mode 100644 tests/components/esp32/validate-signed_ota_external.esp32-s3-idf.yaml

diff --git a/esphome/components/esp32/__init__.py b/esphome/components/esp32/__init__.py
index 7c926fe28e..9b568dd629 100644
--- a/esphome/components/esp32/__init__.py
+++ b/esphome/components/esp32/__init__.py
@@ -1160,6 +1160,74 @@ def _ota_downgrade_protection_errors(
     return errs
 
 
+_SIGNED_OTA_VERIFICATION_SCHEMA = cv.Schema(
+    {
+        cv.Optional(CONF_SIGNING_KEY): cv.file_,
+        cv.Optional(CONF_VERIFICATION_KEY): cv.file_,
+        cv.Optional(CONF_SIGNING_SCHEME, default="rsa3072"): cv.one_of(
+            *SIGNING_SCHEMES, lower=True
+        ),
+    }
+)
+
+
+@schema_extractor("schema")
+def _validate_signed_ota_verification(value):
+    if value is SCHEMA_EXTRACT:
+        # Expose the inner schema so the language-schema dumper can walk the
+        # signing_key / verification_key / signing_scheme options.
+        return _SIGNED_OTA_VERIFICATION_SCHEMA
+    if value is None:
+        # A bare `signed_ota_verification:` block is valid: the default V2
+        # scheme needs no keys (verify externally-signed binaries).
+        value = {}
+    return _validate_signed_ota_keys(_SIGNED_OTA_VERIFICATION_SCHEMA(value))
+
+
+def _validate_signed_ota_keys(config: ConfigType) -> ConfigType:
+    """Validate the signing/verification key combination for the selected scheme.
+
+    A verification key is only used by the Secure Boot V1 scheme (ecdsa_v1):
+    the public key is compiled into the app so it can verify externally-signed
+    images. ESP-IDF's CONFIG_SECURE_BOOT_VERIFICATION_KEY only takes effect
+    when the V1 ECDSA scheme is selected and binaries are not signed during
+    the build (see SECURE_BOOT_VERIFICATION_KEY in the bootloader Kconfig).
+
+    The V2 schemes (rsa3072, ecdsa256) embed the public key in the signature
+    block appended to each image, so verifying externally-signed binaries
+    needs no key in the config at all -- omitting both keys selects that
+    external-signing mode.
+    """
+    has_signing_key = CONF_SIGNING_KEY in config
+    has_verification_key = CONF_VERIFICATION_KEY in config
+    scheme = config[CONF_SIGNING_SCHEME]
+    if has_signing_key and has_verification_key:
+        raise cv.Invalid(
+            f"Provide at most one of '{CONF_SIGNING_KEY}' and "
+            f"'{CONF_VERIFICATION_KEY}', not both.",
+            path=[CONF_VERIFICATION_KEY],
+        )
+    if scheme == "ecdsa_v1":
+        if not has_signing_key and not has_verification_key:
+            raise cv.Invalid(
+                f"Signing scheme 'ecdsa_v1' requires either '{CONF_SIGNING_KEY}' "
+                f"(to sign binaries during the build) or '{CONF_VERIFICATION_KEY}' "
+                f"(to verify binaries signed externally).",
+                path=[CONF_SIGNING_KEY],
+            )
+    elif has_verification_key:
+        raise cv.Invalid(
+            f"'{CONF_VERIFICATION_KEY}' is only used with signing scheme "
+            f"'ecdsa_v1'. With '{scheme}' the public key is embedded in each "
+            f"image's signature block, so no key file is needed to verify "
+            f"externally-signed binaries: remove '{CONF_VERIFICATION_KEY}', and "
+            f"set '{CONF_SIGNING_KEY}' only if binaries should be signed during "
+            f"the build.",
+            path=[CONF_VERIFICATION_KEY],
+        )
+    return config
+
+
 def final_validate(config):
     # Imported locally to avoid circular import issues
     from esphome.components.psram import DOMAIN as PSRAM_DOMAIN
@@ -1361,7 +1429,7 @@ def final_validate(config):
             )
         else:
             _LOGGER.info(
-                "Signed OTA verification is configured with a public verification key. "
+                "Signed OTA verification is enabled without a signing key. "
                 "Binaries will NOT be signed automatically during build. "
                 "You must sign them externally before flashing."
             )
@@ -1640,18 +1708,9 @@ FRAMEWORK_SCHEMA = cv.Schema(
                 cv.Optional(
                     CONF_ENABLE_OTA_DOWNGRADE_PROTECTION, default=False
                 ): cv.boolean,
-                cv.Optional(CONF_SIGNED_OTA_VERIFICATION): cv.All(
-                    cv.Schema(
-                        {
-                            cv.Optional(CONF_SIGNING_KEY): cv.file_,
-                            cv.Optional(CONF_VERIFICATION_KEY): cv.file_,
-                            cv.Optional(
-                                CONF_SIGNING_SCHEME, default="rsa3072"
-                            ): cv.one_of(*SIGNING_SCHEMES, lower=True),
-                        }
-                    ),
-                    cv.has_exactly_one_key(CONF_SIGNING_KEY, CONF_VERIFICATION_KEY),
-                ),
+                cv.Optional(
+                    CONF_SIGNED_OTA_VERIFICATION
+                ): _validate_signed_ota_verification,
                 cv.Optional(CONF_NVS_ENCRYPTION): cv.Schema(
                     {
                         # eFuse key block (0-5) that stores the HMAC key from
@@ -2498,12 +2557,16 @@ async def to_code(config):
                 signed_ota[CONF_SIGNING_KEY].resolve().as_posix(),
             )
         else:
-            # Public key mode — verification only, external signing required
+            # External signing mode — binaries must be signed after the build
             add_idf_sdkconfig_option("CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES", False)
-            add_idf_sdkconfig_option(
-                "CONFIG_SECURE_BOOT_VERIFICATION_KEY",
-                signed_ota[CONF_VERIFICATION_KEY].resolve().as_posix(),
-            )
+            if CONF_VERIFICATION_KEY in signed_ota:
+                # V1 ECDSA only: the public key is compiled into the app to
+                # verify externally-signed images. V2 schemes carry the public
+                # key in each image's signature block and need no key here.
+                add_idf_sdkconfig_option(
+                    "CONFIG_SECURE_BOOT_VERIFICATION_KEY",
+                    signed_ota[CONF_VERIFICATION_KEY].resolve().as_posix(),
+                )
 
         cg.add_define("USE_OTA_SIGNED_VERIFICATION")
 
diff --git a/tests/component_tests/esp32/test_esp32.py b/tests/component_tests/esp32/test_esp32.py
index dd8881e46f..fdca70bf2c 100644
--- a/tests/component_tests/esp32/test_esp32.py
+++ b/tests/component_tests/esp32/test_esp32.py
@@ -665,3 +665,78 @@ def test_downgrade_protection_reports_all_unmet_requirements() -> None:
     # No project version and no signing -> two distinct errors.
     errs = _ota_downgrade_protection_errors(None, signed_ota_enabled=False)
     assert len(errs) == 2
+
+
+@pytest.mark.parametrize(
+    "config",
+    [
+        # V2 schemes: signing key (sign during build) or no key at all
+        # (external signing; the public key travels in the signature block).
+        {"signing_scheme": "rsa3072", "signing_key": "key.pem"},
+        {"signing_scheme": "rsa3072"},
+        {"signing_scheme": "ecdsa256", "signing_key": "key.pem"},
+        {"signing_scheme": "ecdsa256"},
+        # V1 ECDSA: exactly one of signing key / verification key.
+        {"signing_scheme": "ecdsa_v1", "signing_key": "key.pem"},
+        {"signing_scheme": "ecdsa_v1", "verification_key": "key.bin"},
+    ],
+)
+def test_signed_ota_keys_valid_combinations(config: dict) -> None:
+    from esphome.components.esp32 import _validate_signed_ota_keys
+
+    assert _validate_signed_ota_keys(config) is config
+
+
+@pytest.mark.parametrize("value", [None, {}])
+def test_signed_ota_bare_block_selects_v2_external_signing(value: dict | None) -> None:
+    """A bare `signed_ota_verification:` block is valid: the default V2
+    scheme embeds the public key in the signature block, so verifying
+    externally-signed binaries needs no keys in the config."""
+    from esphome.components.esp32 import _validate_signed_ota_verification
+
+    config = _validate_signed_ota_verification(value)
+    assert config == {"signing_scheme": "rsa3072"}
+
+
+@pytest.mark.parametrize(
+    ("config", "match"),
+    [
+        # A verification key is meaningless with the V2 schemes -- the public
+        # key is embedded in each image's signature block.
+        (
+            {"signing_scheme": "rsa3072", "verification_key": "key.bin"},
+            "only used with signing scheme 'ecdsa_v1'",
+        ),
+        (
+            {"signing_scheme": "ecdsa256", "verification_key": "key.bin"},
+            "only used with signing scheme 'ecdsa_v1'",
+        ),
+        # V1 ECDSA needs a key either way.
+        (
+            {"signing_scheme": "ecdsa_v1"},
+            "Signing scheme 'ecdsa_v1' requires either",
+        ),
+        # Never both keys at once.
+        (
+            {
+                "signing_scheme": "rsa3072",
+                "signing_key": "key.pem",
+                "verification_key": "key.bin",
+            },
+            "not both",
+        ),
+        (
+            {
+                "signing_scheme": "ecdsa_v1",
+                "signing_key": "key.pem",
+                "verification_key": "key.bin",
+            },
+            "not both",
+        ),
+    ],
+)
+def test_signed_ota_keys_invalid_combinations(config: dict, match: str) -> None:
+    from esphome.components.esp32 import _validate_signed_ota_keys
+
+    with pytest.raises(cv.Invalid, match=match):
+        _validate_signed_ota_keys(config)
diff --git a/tests/components/esp32/validate-signed_ota_external.esp32-s3-idf.yaml b/tests/components/esp32/validate-signed_ota_external.esp32-s3-idf.yaml
new file mode 100644
index 0000000000..5b57993e87
--- /dev/null
+++ b/tests/components/esp32/validate-signed_ota_external.esp32-s3-idf.yaml
@@ -0,0 +1,11 @@
+# Secure Boot V2 schemes carry the public key inside each image's signature
+# block, so verifying externally-signed binaries needs no key in the config:
+# a bare block enables verification with the default rsa3072 scheme.
+esp32:
+  variant: esp32s3
+  framework:
+    type: esp-idf
+    advanced:
+      signed_ota_verification:
+
+<<: !include common.yaml

From 583adc9e69a30898556ce68f945fe6718abb7829 Mon Sep 17 00:00:00 2001
From: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
Date: Mon, 13 Jul 2026 23:23:55 +1200
Subject: [PATCH 10/24] [web_server] Use dict-style packages in tests so they
 can be batch-grouped (#17544)

---
 tests/components/web_server/test.esp32-ard.yaml    | 3 ++-
 tests/components/web_server/test.esp32-idf.yaml    | 3 ++-
 tests/components/web_server/test.esp8266-ard.yaml  | 3 ++-
 tests/components/web_server/test.rp2040-ard.yaml   | 3 ++-
 tests/components/web_server/test_v1.esp32-ard.yaml | 3 ++-
 tests/components/web_server/test_v1.esp32-idf.yaml | 3 ++-
 tests/components/web_server/test_v3.esp32-ard.yaml | 3 ++-
 7 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/tests/components/web_server/test.esp32-ard.yaml b/tests/components/web_server/test.esp32-ard.yaml
index 7e6658e20e..11ad5456ef 100644
--- a/tests/components/web_server/test.esp32-ard.yaml
+++ b/tests/components/web_server/test.esp32-ard.yaml
@@ -1 +1,2 @@
-<<: !include common_v2.yaml
+packages:
+  web_server: !include common_v2.yaml
diff --git a/tests/components/web_server/test.esp32-idf.yaml b/tests/components/web_server/test.esp32-idf.yaml
index 24b292d0d6..858e3b0190 100644
--- a/tests/components/web_server/test.esp32-idf.yaml
+++ b/tests/components/web_server/test.esp32-idf.yaml
@@ -1,4 +1,5 @@
-<<: !include common_v2.yaml
+packages:
+  web_server: !include common_v2.yaml
 
 web_server:
   auth:
diff --git a/tests/components/web_server/test.esp8266-ard.yaml b/tests/components/web_server/test.esp8266-ard.yaml
index 7e6658e20e..11ad5456ef 100644
--- a/tests/components/web_server/test.esp8266-ard.yaml
+++ b/tests/components/web_server/test.esp8266-ard.yaml
@@ -1 +1,2 @@
-<<: !include common_v2.yaml
+packages:
+  web_server: !include common_v2.yaml
diff --git a/tests/components/web_server/test.rp2040-ard.yaml b/tests/components/web_server/test.rp2040-ard.yaml
index 7e6658e20e..11ad5456ef 100644
--- a/tests/components/web_server/test.rp2040-ard.yaml
+++ b/tests/components/web_server/test.rp2040-ard.yaml
@@ -1 +1,2 @@
-<<: !include common_v2.yaml
+packages:
+  web_server: !include common_v2.yaml
diff --git a/tests/components/web_server/test_v1.esp32-ard.yaml b/tests/components/web_server/test_v1.esp32-ard.yaml
index 389a930284..1d563de834 100644
--- a/tests/components/web_server/test_v1.esp32-ard.yaml
+++ b/tests/components/web_server/test_v1.esp32-ard.yaml
@@ -1 +1,2 @@
-<<: !include common_v1.yaml
+packages:
+  web_server: !include common_v1.yaml
diff --git a/tests/components/web_server/test_v1.esp32-idf.yaml b/tests/components/web_server/test_v1.esp32-idf.yaml
index 389a930284..1d563de834 100644
--- a/tests/components/web_server/test_v1.esp32-idf.yaml
+++ b/tests/components/web_server/test_v1.esp32-idf.yaml
@@ -1 +1,2 @@
-<<: !include common_v1.yaml
+packages:
+  web_server: !include common_v1.yaml
diff --git a/tests/components/web_server/test_v3.esp32-ard.yaml b/tests/components/web_server/test_v3.esp32-ard.yaml
index 00d05521e4..956a88bc68 100644
--- a/tests/components/web_server/test_v3.esp32-ard.yaml
+++ b/tests/components/web_server/test_v3.esp32-ard.yaml
@@ -1 +1,2 @@
-<<: !include common_v3.yaml
+packages:
+  web_server: !include common_v3.yaml

From 989797be5356506765574b480be4681a96d7b53c Mon Sep 17 00:00:00 2001
From: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
Date: Tue, 14 Jul 2026 10:33:44 +1200
Subject: [PATCH 11/24] [web_server] Add HTTP digest authentication with
 selectable scheme (#17541)

---
 esphome/components/web_server/__init__.py     |  52 ++++--
 .../web_server_base/web_server_base.h         |   8 +
 .../web_server_idf/web_server_idf.cpp         | 170 +++++++++++++++++-
 .../web_server_idf/web_server_idf.h           |   2 +-
 esphome/core/defines.h                        |   3 +
 .../web_server/test_web_server_auth.py        |  65 +++++++
 .../web_server/web_server_auth_basic.yaml     |  18 ++
 .../web_server/web_server_auth_default.yaml   |  17 ++
 .../web_server/web_server_auth_digest.yaml    |  18 ++
 .../web_server/web_server_no_auth.yaml        |  14 ++
 .../components/web_server/test.esp32-idf.yaml |   1 +
 .../web_server/test.esp8266-ard.yaml          |   6 +
 .../web_server/test.rp2040-ard.yaml           |   6 +
 .../web_server/validate.esp32-idf.yaml        |   8 +
 14 files changed, 370 insertions(+), 18 deletions(-)
 create mode 100644 tests/component_tests/web_server/test_web_server_auth.py
 create mode 100644 tests/component_tests/web_server/web_server_auth_basic.yaml
 create mode 100644 tests/component_tests/web_server/web_server_auth_default.yaml
 create mode 100644 tests/component_tests/web_server/web_server_auth_digest.yaml
 create mode 100644 tests/component_tests/web_server/web_server_no_auth.yaml
 create mode 100644 tests/components/web_server/validate.esp32-idf.yaml

diff --git a/esphome/components/web_server/__init__.py b/esphome/components/web_server/__init__.py
index 68f1c18072..2587d13b9e 100644
--- a/esphome/components/web_server/__init__.py
+++ b/esphome/components/web_server/__init__.py
@@ -25,6 +25,7 @@ from esphome.const import (
     CONF_OTA,
     CONF_PASSWORD,
     CONF_PORT,
+    CONF_TYPE,
     CONF_USERNAME,
     CONF_VERSION,
     CONF_WEB_SERVER,
@@ -44,6 +45,9 @@ _LOGGER = logging.getLogger(__name__)
 
 AUTO_LOAD = ["json", "web_server_base"]
 
+AUTH_TYPE_BASIC = "basic"
+AUTH_TYPE_DIGEST = "digest"
+
 CONF_SORTING_GROUP_ID = "sorting_group_id"
 CONF_SORTING_GROUPS = "sorting_groups"
 CONF_SORTING_WEIGHT = "sorting_weight"
@@ -85,6 +89,19 @@ def validate_version_deprecated(config: ConfigType) -> ConfigType:
     return config
 
 
+def validate_auth_type_deprecated(auth: ConfigType) -> ConfigType:
+    # Remove before 2027.1.0: the default auth scheme changes from basic to digest.
+    if CONF_TYPE not in auth:
+        _LOGGER.warning(
+            "The 'web_server' 'auth' scheme currently defaults to 'basic', which sends the "
+            "password over the network in an easily reversible form. The default will change "
+            "to 'digest' in ESPHome 2027.1.0. To keep using basic authentication, set "
+            "'type: basic' under 'auth:' explicitly; otherwise set 'type: digest' now to "
+            "adopt the more secure scheme."
+        )
+    return auth
+
+
 def validate_local(config: ConfigType) -> ConfigType:
     if CONF_LOCAL in config and config[CONF_VERSION] == 1:
         raise cv.Invalid("'local' is not supported in version 1")
@@ -242,15 +259,21 @@ CONFIG_SCHEMA = cv.All(
             cv.Optional(CONF_ALLOWED_ORIGINS): cv.All(
                 cv.ensure_list(validate_origin), cv.Length(min=1)
             ),
-            cv.Optional(CONF_AUTH): cv.Schema(
-                {
-                    cv.Required(CONF_USERNAME): cv.All(
-                        cv.string_strict, cv.Length(min=1)
-                    ),
-                    cv.Required(CONF_PASSWORD): cv.sensitive(
-                        cv.All(cv.string_strict, cv.Length(min=1))
-                    ),
-                }
+            cv.Optional(CONF_AUTH): cv.All(
+                cv.Schema(
+                    {
+                        cv.Required(CONF_USERNAME): cv.All(
+                            cv.string_strict, cv.Length(min=1)
+                        ),
+                        cv.Required(CONF_PASSWORD): cv.sensitive(
+                            cv.All(cv.string_strict, cv.Length(min=1))
+                        ),
+                        cv.Optional(CONF_TYPE): cv.one_of(
+                            AUTH_TYPE_BASIC, AUTH_TYPE_DIGEST, lower=True
+                        ),
+                    }
+                ),
+                validate_auth_type_deprecated,
             ),
             cv.GenerateID(CONF_WEB_SERVER_BASE_ID): cv.use_id(
                 web_server_base.WebServerBase
@@ -378,10 +401,15 @@ async def to_code(config):
     if (allowed_origins := config.get(CONF_ALLOWED_ORIGINS)) is not None:
         cg.add_define("USE_WEBSERVER_ALLOWED_ORIGINS")
         cg.add(var.set_allowed_origins(allowed_origins))
-    if CONF_AUTH in config:
+    if (auth := config.get(CONF_AUTH)) is not None:
         cg.add_define("USE_WEBSERVER_AUTH")
-        cg.add(paren.set_auth_username(config[CONF_AUTH][CONF_USERNAME]))
-        cg.add(paren.set_auth_password(config[CONF_AUTH][CONF_PASSWORD]))
+        # The scheme is fixed at build time so the unused Basic/Digest code path is compiled
+        # out. Basic is the current default (the absence of this define); an explicit
+        # 'type: digest' opts in early. Default changes to digest in 2027.1.0.
+        if auth.get(CONF_TYPE) == AUTH_TYPE_DIGEST:
+            cg.add_define("USE_WEBSERVER_AUTH_DIGEST")
+        cg.add(paren.set_auth_username(auth[CONF_USERNAME]))
+        cg.add(paren.set_auth_password(auth[CONF_PASSWORD]))
     if CONF_CSS_INCLUDE in config:
         cg.add_define("USE_WEBSERVER_CSS_INCLUDE")
         path = CORE.relative_config_path(config[CONF_CSS_INCLUDE])
diff --git a/esphome/components/web_server_base/web_server_base.h b/esphome/components/web_server_base/web_server_base.h
index 19c2185fb9..9657853a73 100644
--- a/esphome/components/web_server_base/web_server_base.h
+++ b/esphome/components/web_server_base/web_server_base.h
@@ -59,7 +59,15 @@ class AuthMiddlewareHandler : public MiddlewareHandler {
   bool check_auth(AsyncWebServerRequest *request) {
     bool success = request->authenticate(credentials_->username.c_str(), credentials_->password.c_str());
     if (!success) {
+      // The scheme is chosen at build time (USE_WEBSERVER_AUTH_DIGEST); the unused path is
+      // compiled out. On ESP32 our own server picks the scheme internally.
+#if USE_ESP32
       request->requestAuthentication();
+#elif defined(USE_WEBSERVER_AUTH_DIGEST)
+      request->requestAuthentication(nullptr, true);
+#else
+      request->requestAuthentication(nullptr, false);
+#endif
     }
     return success;
   }
diff --git a/esphome/components/web_server_idf/web_server_idf.cpp b/esphome/components/web_server_idf/web_server_idf.cpp
index 46a389f359..bf5a8666dc 100644
--- a/esphome/components/web_server_idf/web_server_idf.cpp
+++ b/esphome/components/web_server_idf/web_server_idf.cpp
@@ -16,6 +16,11 @@
 #include "utils.h"
 #include "web_server_idf.h"
 
+#ifdef USE_WEBSERVER_AUTH_DIGEST
+#include <esp_random.h>
+#include <esp_rom_md5.h>
+#endif
+
 #ifdef USE_WEBSERVER_OTA
 #include <multipart_parser.h>
 #include "multipart.h"  // For parse_multipart_boundary and other utils
@@ -372,6 +377,135 @@ void AsyncWebServerRequest::init_response_(AsyncWebServerResponse *rsp, int code
 }
 
 #ifdef USE_WEBSERVER_AUTH
+
+#ifdef USE_WEBSERVER_AUTH_DIGEST
+namespace {
+
+// Hex-encode `len` bytes into `out`, which must hold at least 2 * len + 1 bytes. Null-terminated.
+void bytes_to_hex(const uint8_t *data, size_t len, char *out) {
+  static const char HEX[] = "0123456789abcdef";
+  for (size_t i = 0; i < len; i++) {
+    out[i * 2] = HEX[data[i] >> 4];
+    out[i * 2 + 1] = HEX[data[i] & 0x0f];
+  }
+  out[len * 2] = '\0';
+}
+
+// Extract the value of a Digest auth parameter (e.g. "nonce") from the comma-separated
+// parameter list. Values may be quoted or bare. Returns an empty ref when the key is absent.
+// Only whole parameter names match, so "nc" does not match inside "cnonce".
+StringRef digest_param(StringRef params, const char *key) {
+  size_t key_len = strlen(key);
+  const char *base = params.c_str();
+  size_t n = params.size();
+  size_t i = 0;
+  while (i < n) {
+    while (i < n && (base[i] == ' ' || base[i] == ','))
+      i++;
+    size_t name_start = i;
+    while (i < n && base[i] != '=' && base[i] != ',')
+      i++;
+    if (i >= n || base[i] == ',')
+      continue;  // token without a '=', skip it
+    size_t name_len = i - name_start;
+    while (name_len > 0 && base[name_start + name_len - 1] == ' ')
+      name_len--;
+    i++;  // consume '='
+    const char *val_start;
+    size_t val_len;
+    if (i < n && base[i] == '"') {
+      i++;
+      val_start = base + i;
+      while (i < n && base[i] != '"')
+        i++;
+      val_len = (base + i) - val_start;
+      if (i < n)
+        i++;  // consume closing quote
+    } else {
+      val_start = base + i;
+      while (i < n && base[i] != ',')
+        i++;
+      val_len = (base + i) - val_start;
+    }
+    if (name_len == key_len && memcmp(base + name_start, key, key_len) == 0)
+      return StringRef(val_start, val_len);
+    while (i < n && base[i] != ',')
+      i++;
+  }
+  return StringRef();
+}
+
+// Verify an RFC 2617 Digest response. Stateless (the nonce we issued is not tracked), which
+// matches the ESPAsyncWebServer backend used on the Arduino platforms.
+bool check_digest_auth(const char *username, const char *password, const std::string &header, const char *method) {
+  const size_t prefix_len = sizeof("Digest ") - 1;
+  StringRef params(header.c_str() + prefix_len, header.size() - prefix_len);
+
+  if (digest_param(params, "username") != username)
+    return false;
+
+  StringRef realm = digest_param(params, "realm");
+  StringRef nonce = digest_param(params, "nonce");
+  StringRef uri = digest_param(params, "uri");
+  StringRef qop = digest_param(params, "qop");
+  StringRef nc = digest_param(params, "nc");
+  StringRef cnonce = digest_param(params, "cnonce");
+  StringRef response = digest_param(params, "response");
+  if (response.size() != 32)
+    return false;
+
+  // Compute the three MD5 hashes by streaming the pieces straight into the ROM MD5 engine, so
+  // nothing is concatenated on the heap. Each hash is emitted as 32 lowercase hex characters.
+  md5_context_t ctx;
+  uint8_t digest[16];
+
+  // HA1 = MD5(username:realm:password) -- uses the realm the client echoed back.
+  char ha1[33];
+  esp_rom_md5_init(&ctx);
+  esp_rom_md5_update(&ctx, username, strlen(username));
+  esp_rom_md5_update(&ctx, ":", 1);
+  esp_rom_md5_update(&ctx, realm.c_str(), realm.size());
+  esp_rom_md5_update(&ctx, ":", 1);
+  esp_rom_md5_update(&ctx, password, strlen(password));
+  esp_rom_md5_final(digest, &ctx);
+  bytes_to_hex(digest, sizeof(digest), ha1);
+
+  // HA2 = MD5(method:uri) -- uses the uri the client echoed back.
+  char ha2[33];
+  esp_rom_md5_init(&ctx);
+  esp_rom_md5_update(&ctx, method, strlen(method));
+  esp_rom_md5_update(&ctx, ":", 1);
+  esp_rom_md5_update(&ctx, uri.c_str(), uri.size());
+  esp_rom_md5_final(digest, &ctx);
+  bytes_to_hex(digest, sizeof(digest), ha2);
+
+  // expected = MD5(HA1:nonce:nc:cnonce:qop:HA2)
+  char expected[33];
+  esp_rom_md5_init(&ctx);
+  esp_rom_md5_update(&ctx, ha1, 32);
+  esp_rom_md5_update(&ctx, ":", 1);
+  esp_rom_md5_update(&ctx, nonce.c_str(), nonce.size());
+  esp_rom_md5_update(&ctx, ":", 1);
+  esp_rom_md5_update(&ctx, nc.c_str(), nc.size());
+  esp_rom_md5_update(&ctx, ":", 1);
+  esp_rom_md5_update(&ctx, cnonce.c_str(), cnonce.size());
+  esp_rom_md5_update(&ctx, ":", 1);
+  esp_rom_md5_update(&ctx, qop.c_str(), qop.size());
+  esp_rom_md5_update(&ctx, ":", 1);
+  esp_rom_md5_update(&ctx, ha2, 32);
+  esp_rom_md5_final(digest, &ctx);
+  bytes_to_hex(digest, sizeof(digest), expected);
+
+  // Constant-time comparison of the two 32-char hex digests.
+  uint8_t result = 0;
+  for (size_t i = 0; i < 32; i++)
+    result |= static_cast<uint8_t>(expected[i] ^ response[i]);
+  return result == 0;
+}
+
+}  // namespace
+#endif  // USE_WEBSERVER_AUTH_DIGEST
+
 bool AsyncWebServerRequest::authenticate(const char *username, const char *password) const {
   if (username == nullptr || password == nullptr || *username == 0) {
     return true;
@@ -383,9 +517,18 @@ bool AsyncWebServerRequest::authenticate(const char *username, const char *passw
 
   auto *auth_str = auth.value().c_str();
 
+#ifdef USE_WEBSERVER_AUTH_DIGEST
+  // The build fixed the scheme to Digest, so the Basic path is compiled out entirely.
+  const auto auth_prefix_len = sizeof("Digest ") - 1;
+  if (strncmp("Digest ", auth_str, auth_prefix_len) != 0) {
+    ESP_LOGW(TAG, "Only Digest authorization supported");
+    return false;
+  }
+  return check_digest_auth(username, password, auth.value(), http_method_str(this->method()));
+#else
   const auto auth_prefix_len = sizeof("Basic ") - 1;
   if (strncmp("Basic ", auth_str, auth_prefix_len) != 0) {
-    ESP_LOGW(TAG, "Only Basic authorization supported yet");
+    ESP_LOGW(TAG, "Only Basic authorization supported");
     return false;
   }
 
@@ -434,16 +577,33 @@ bool AsyncWebServerRequest::authenticate(const char *username, const char *passw
     result |= static_cast<uint8_t>(digest[i] ^ provided_ch);
   }
   return result == 0;
+#endif  // USE_WEBSERVER_AUTH_DIGEST
 }
 
-void AsyncWebServerRequest::requestAuthentication(const char *realm) const {
+void AsyncWebServerRequest::requestAuthentication() const {
   httpd_resp_set_hdr(*this, "Connection", "keep-alive");
-  // Note: realm is never configured in ESPHome, always nullptr -> "Login Required"
-  (void) realm;  // Unused - always use default
+#ifdef USE_WEBSERVER_AUTH_DIGEST
+  // Issue a fresh random nonce and opaque. The nonce is not stored, so this is stateless and
+  // does not defend against replay -- its purpose is to keep the password off the wire.
+  // The header value must stay alive until httpd_resp_send_err() below sends it, so the buffer
+  // lives on this stack frame (httpd_resp_set_hdr stores the pointer, it does not copy).
+  uint8_t random_bytes[16];
+  char nonce[33];
+  char opaque[33];
+  char header[160];
+  esp_fill_random(random_bytes, sizeof(random_bytes));
+  bytes_to_hex(random_bytes, sizeof(random_bytes), nonce);
+  esp_fill_random(random_bytes, sizeof(random_bytes));
+  bytes_to_hex(random_bytes, sizeof(random_bytes), opaque);
+  snprintf(header, sizeof(header), R"(Digest realm="Login Required", qop="auth", nonce="%s", opaque="%s")", nonce,
+           opaque);
+  httpd_resp_set_hdr(*this, "WWW-Authenticate", header);
+#else
   httpd_resp_set_hdr(*this, "WWW-Authenticate", "Basic realm=\"Login Required\"");
+#endif  // USE_WEBSERVER_AUTH_DIGEST
   httpd_resp_send_err(*this, HTTPD_401_UNAUTHORIZED, nullptr);
 }
-#endif
+#endif  // USE_WEBSERVER_AUTH
 
 AsyncWebParameter *AsyncWebServerRequest::getParam(const char *name) {
   // Check cache first - only successful lookups are cached
diff --git a/esphome/components/web_server_idf/web_server_idf.h b/esphome/components/web_server_idf/web_server_idf.h
index 8b5fd5b726..baa55898bb 100644
--- a/esphome/components/web_server_idf/web_server_idf.h
+++ b/esphome/components/web_server_idf/web_server_idf.h
@@ -129,7 +129,7 @@ class AsyncWebServerRequest {
 #ifdef USE_WEBSERVER_AUTH
   bool authenticate(const char *username, const char *password) const;
   // NOLINTNEXTLINE(readability-identifier-naming)
-  void requestAuthentication(const char *realm = nullptr) const;
+  void requestAuthentication() const;
 #endif
 
   void redirect(const std::string &url);
diff --git a/esphome/core/defines.h b/esphome/core/defines.h
index 78f7769cf6..5c5fc5e8b9 100644
--- a/esphome/core/defines.h
+++ b/esphome/core/defines.h
@@ -298,6 +298,7 @@
 #define USE_VOICE_ASSISTANT
 #define USE_WEBSERVER
 #define USE_WEBSERVER_AUTH
+#define USE_WEBSERVER_AUTH_DIGEST
 #define USE_WEBSERVER_OTA
 #define USE_WEBSERVER_PORT 80  // NOLINT
 #define USE_WEBSERVER_GZIP
@@ -408,6 +409,7 @@
 
 #define USE_WEBSERVER
 #define USE_WEBSERVER_AUTH
+#define USE_WEBSERVER_AUTH_DIGEST
 #define USE_WEBSERVER_PORT 80  // NOLINT
 #endif
 
@@ -438,6 +440,7 @@
 #define USE_LWIP_FAST_SELECT
 #define USE_WEBSERVER
 #define USE_WEBSERVER_AUTH
+#define USE_WEBSERVER_AUTH_DIGEST
 #define USE_WEBSERVER_PORT 80  // NOLINT
 #define USE_ESPHOME_TASK_LOG_BUFFER
 #define ESPHOME_TASK_LOG_BUFFER_SIZE 768
diff --git a/tests/component_tests/web_server/test_web_server_auth.py b/tests/component_tests/web_server/test_web_server_auth.py
new file mode 100644
index 0000000000..82635b26da
--- /dev/null
+++ b/tests/component_tests/web_server/test_web_server_auth.py
@@ -0,0 +1,65 @@
+"""Tests for web_server authentication codegen."""
+
+from collections.abc import Callable
+
+import pytest
+
+from esphome.core import CORE
+
+_DEFAULT_CHANGE_WARNING = "default will change to 'digest' in ESPHome 2027.1.0"
+
+
+def _has_define(name: str) -> bool:
+    return any(d.name == name for d in CORE.defines)
+
+
+def test_web_server_auth_default_is_basic_with_deprecation_warning(
+    generate_main: Callable[[str], str],
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Auth without an explicit type builds Basic and warns about the upcoming default change."""
+    main_cpp = generate_main(
+        "tests/component_tests/web_server/web_server_auth_default.yaml"
+    )
+
+    assert '->set_auth_username("admin");' in main_cpp
+    assert '->set_auth_password("password");' in main_cpp
+    assert _has_define("USE_WEBSERVER_AUTH")
+    assert not _has_define("USE_WEBSERVER_AUTH_DIGEST")
+    assert _DEFAULT_CHANGE_WARNING in caplog.text
+
+
+def test_web_server_auth_explicit_basic_no_warning(
+    generate_main: Callable[[str], str],
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Auth type basic builds Basic and does not warn."""
+    generate_main("tests/component_tests/web_server/web_server_auth_basic.yaml")
+
+    assert _has_define("USE_WEBSERVER_AUTH")
+    assert not _has_define("USE_WEBSERVER_AUTH_DIGEST")
+    assert _DEFAULT_CHANGE_WARNING not in caplog.text
+
+
+def test_web_server_auth_explicit_digest(
+    generate_main: Callable[[str], str],
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Auth type digest builds Digest and does not warn."""
+    generate_main("tests/component_tests/web_server/web_server_auth_digest.yaml")
+
+    assert _has_define("USE_WEBSERVER_AUTH")
+    assert _has_define("USE_WEBSERVER_AUTH_DIGEST")
+    assert _DEFAULT_CHANGE_WARNING not in caplog.text
+
+
+def test_web_server_without_auth(
+    generate_main: Callable[[str], str],
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Without an auth block, no auth is compiled in and no warning is emitted."""
+    generate_main("tests/component_tests/web_server/web_server_no_auth.yaml")
+
+    assert not _has_define("USE_WEBSERVER_AUTH")
+    assert not _has_define("USE_WEBSERVER_AUTH_DIGEST")
+    assert _DEFAULT_CHANGE_WARNING not in caplog.text
diff --git a/tests/component_tests/web_server/web_server_auth_basic.yaml b/tests/component_tests/web_server/web_server_auth_basic.yaml
new file mode 100644
index 0000000000..70180f9fbc
--- /dev/null
+++ b/tests/component_tests/web_server/web_server_auth_basic.yaml
@@ -0,0 +1,18 @@
+---
+esphome:
+  name: test
+
+esp32:
+  board: nodemcu-32s
+  framework:
+    type: esp-idf
+
+wifi:
+  ssid: MySSID
+  password: password1
+
+web_server:
+  auth:
+    username: admin
+    password: password
+    type: basic
diff --git a/tests/component_tests/web_server/web_server_auth_default.yaml b/tests/component_tests/web_server/web_server_auth_default.yaml
new file mode 100644
index 0000000000..076180ab79
--- /dev/null
+++ b/tests/component_tests/web_server/web_server_auth_default.yaml
@@ -0,0 +1,17 @@
+---
+esphome:
+  name: test
+
+esp32:
+  board: nodemcu-32s
+  framework:
+    type: esp-idf
+
+wifi:
+  ssid: MySSID
+  password: password1
+
+web_server:
+  auth:
+    username: admin
+    password: password
diff --git a/tests/component_tests/web_server/web_server_auth_digest.yaml b/tests/component_tests/web_server/web_server_auth_digest.yaml
new file mode 100644
index 0000000000..f413787601
--- /dev/null
+++ b/tests/component_tests/web_server/web_server_auth_digest.yaml
@@ -0,0 +1,18 @@
+---
+esphome:
+  name: test
+
+esp32:
+  board: nodemcu-32s
+  framework:
+    type: esp-idf
+
+wifi:
+  ssid: MySSID
+  password: password1
+
+web_server:
+  auth:
+    username: admin
+    password: password
+    type: digest
diff --git a/tests/component_tests/web_server/web_server_no_auth.yaml b/tests/component_tests/web_server/web_server_no_auth.yaml
new file mode 100644
index 0000000000..1c7823b4ae
--- /dev/null
+++ b/tests/component_tests/web_server/web_server_no_auth.yaml
@@ -0,0 +1,14 @@
+---
+esphome:
+  name: test
+
+esp32:
+  board: nodemcu-32s
+  framework:
+    type: esp-idf
+
+wifi:
+  ssid: MySSID
+  password: password1
+
+web_server:
diff --git a/tests/components/web_server/test.esp32-idf.yaml b/tests/components/web_server/test.esp32-idf.yaml
index 858e3b0190..2e091b905a 100644
--- a/tests/components/web_server/test.esp32-idf.yaml
+++ b/tests/components/web_server/test.esp32-idf.yaml
@@ -5,3 +5,4 @@ web_server:
   auth:
     username: admin
     password: password
+    type: digest
diff --git a/tests/components/web_server/test.esp8266-ard.yaml b/tests/components/web_server/test.esp8266-ard.yaml
index 11ad5456ef..2e091b905a 100644
--- a/tests/components/web_server/test.esp8266-ard.yaml
+++ b/tests/components/web_server/test.esp8266-ard.yaml
@@ -1,2 +1,8 @@
 packages:
   web_server: !include common_v2.yaml
+
+web_server:
+  auth:
+    username: admin
+    password: password
+    type: digest
diff --git a/tests/components/web_server/test.rp2040-ard.yaml b/tests/components/web_server/test.rp2040-ard.yaml
index 11ad5456ef..e4d50d7776 100644
--- a/tests/components/web_server/test.rp2040-ard.yaml
+++ b/tests/components/web_server/test.rp2040-ard.yaml
@@ -1,2 +1,8 @@
 packages:
   web_server: !include common_v2.yaml
+
+web_server:
+  auth:
+    username: admin
+    password: password
+    type: basic
diff --git a/tests/components/web_server/validate.esp32-idf.yaml b/tests/components/web_server/validate.esp32-idf.yaml
new file mode 100644
index 0000000000..e4d50d7776
--- /dev/null
+++ b/tests/components/web_server/validate.esp32-idf.yaml
@@ -0,0 +1,8 @@
+packages:
+  web_server: !include common_v2.yaml
+
+web_server:
+  auth:
+    username: admin
+    password: password
+    type: basic

From 519ce38b7932fd3e4b8b3bbba0b5e709caea13d4 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Mon, 13 Jul 2026 13:51:54 -1000
Subject: [PATCH 12/24] [libretiny] Keep renamed board generic-ln882hki
 validating against generic-ln882h (#17542)

---
 esphome/components/libretiny/__init__.py      | 15 ++++++
 tests/unit_tests/components/test_libretiny.py | 52 +++++++++++++++++++
 2 files changed, 67 insertions(+)
 create mode 100644 tests/unit_tests/components/test_libretiny.py

diff --git a/esphome/components/libretiny/__init__.py b/esphome/components/libretiny/__init__.py
index 3fde11b1eb..62cef331fd 100644
--- a/esphome/components/libretiny/__init__.py
+++ b/esphome/components/libretiny/__init__.py
@@ -76,12 +76,27 @@ _BLE5_BK_SYS_CONFIG_OPTIONS = [
     "CFG_SUPPORT_BLE=0",
 ]
 
+# Board ids upstream LibreTiny renamed; configs written against the old id
+# keep validating and building against the new one (with a warning).
+# generic-ln882hki -> generic-ln882h: LibreTiny v1.13.0.
+_RENAMED_BOARDS = {
+    "generic-ln882hki": "generic-ln882h",
+}
+
 
 def _detect_variant(value):
     if KEY_LIBRETINY not in CORE.data:
         raise cv.Invalid("Family component didn't populate core data properly!")
     component: LibreTinyComponent = CORE.data[KEY_LIBRETINY][KEY_COMPONENT_DATA]
     board = value[CONF_BOARD]
+    if board not in component.boards and (renamed := _RENAMED_BOARDS.get(board)):
+        _LOGGER.warning(
+            "Board '%s' was renamed to '%s'; please update your configuration",
+            board,
+            renamed,
+        )
+        value = value.copy()
+        value[CONF_BOARD] = board = renamed
     # read board-default family if not specified
     if board not in component.boards:
         if CONF_FAMILY not in value:
diff --git a/tests/unit_tests/components/test_libretiny.py b/tests/unit_tests/components/test_libretiny.py
new file mode 100644
index 0000000000..ee00bdc180
--- /dev/null
+++ b/tests/unit_tests/components/test_libretiny.py
@@ -0,0 +1,52 @@
+"""Tests for LibreTiny board detection, including renamed-board migration."""
+
+import pytest
+
+from esphome.components.libretiny import _detect_variant
+from esphome.components.libretiny.const import (
+    FAMILY_LN882H,
+    KEY_COMPONENT_DATA,
+    KEY_LIBRETINY,
+)
+from esphome.components.ln882x import COMPONENT_DATA
+import esphome.config_validation as cv
+from esphome.const import CONF_BOARD, CONF_FAMILY
+from esphome.core import CORE
+
+
+@pytest.fixture
+def ln882x_core_data() -> None:
+    """Populate CORE the way the ln882x component schema does."""
+    CORE.data[KEY_LIBRETINY] = {KEY_COMPONENT_DATA: COMPONENT_DATA}
+
+
+def test_detect_variant_known_board_passes(ln882x_core_data: None) -> None:
+    """A current board id resolves its family without warnings."""
+    result = _detect_variant({CONF_BOARD: "generic-ln882h"})
+    assert result[CONF_BOARD] == "generic-ln882h"
+    assert result[CONF_FAMILY] == FAMILY_LN882H
+
+
+def test_detect_variant_renamed_board_migrates(
+    ln882x_core_data: None, caplog: pytest.LogCaptureFixture
+) -> None:
+    """A pre-rename board id validates against the new id, with a warning."""
+    result = _detect_variant({CONF_BOARD: "generic-ln882hki"})
+    assert result[CONF_BOARD] == "generic-ln882h"
+    assert result[CONF_FAMILY] == FAMILY_LN882H
+    assert "renamed to 'generic-ln882h'" in caplog.text
+
+
+def test_detect_variant_renamed_board_does_not_mutate_input(
+    ln882x_core_data: None,
+) -> None:
+    """Migration copies the config; the caller's dict keeps the old id."""
+    value = {CONF_BOARD: "generic-ln882hki"}
+    _detect_variant(value)
+    assert value[CONF_BOARD] == "generic-ln882hki"
+
+
+def test_detect_variant_unknown_board_still_raises(ln882x_core_data: None) -> None:
+    """Ids outside the rename map keep the family-override error."""
+    with pytest.raises(cv.Invalid, match="This board is unknown"):
+        _detect_variant({CONF_BOARD: "not-a-real-board"})

From 1da8900ffc80df4c7220df9a998ee7d419c3a815 Mon Sep 17 00:00:00 2001
From: Jonathan Swoboda <154711427+swoboda1337@users.noreply.github.com>
Date: Mon, 13 Jul 2026 19:53:31 -0400
Subject: [PATCH 13/24] [veml7700][as7341][ltr501] Fix device class on
 raw-count sensors (#17549)

---
 esphome/components/as7341/sensor.py   |  4 ++--
 esphome/components/ltr501/sensor.py   | 10 +++++-----
 esphome/components/veml7700/sensor.py |  5 +++--
 3 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/esphome/components/as7341/sensor.py b/esphome/components/as7341/sensor.py
index fa51a1cdfa..8b6cf61028 100644
--- a/esphome/components/as7341/sensor.py
+++ b/esphome/components/as7341/sensor.py
@@ -5,7 +5,7 @@ from esphome.const import (
     CONF_CLEAR,
     CONF_GAIN,
     CONF_ID,
-    DEVICE_CLASS_ILLUMINANCE,
+    DEVICE_CLASS_EMPTY,
     ICON_BRIGHTNESS_5,
     STATE_CLASS_MEASUREMENT,
 )
@@ -54,7 +54,7 @@ SENSOR_SCHEMA = sensor.sensor_schema(
     unit_of_measurement=UNIT_COUNTS,
     icon=ICON_BRIGHTNESS_5,
     accuracy_decimals=0,
-    device_class=DEVICE_CLASS_ILLUMINANCE,
+    device_class=DEVICE_CLASS_EMPTY,
     state_class=STATE_CLASS_MEASUREMENT,
 )
 
diff --git a/esphome/components/ltr501/sensor.py b/esphome/components/ltr501/sensor.py
index cca9330e76..c1fa9009b3 100644
--- a/esphome/components/ltr501/sensor.py
+++ b/esphome/components/ltr501/sensor.py
@@ -15,7 +15,7 @@ from esphome.const import (
     CONF_NAME,
     CONF_REPEAT,
     CONF_TYPE,
-    DEVICE_CLASS_DISTANCE,
+    DEVICE_CLASS_EMPTY,
     DEVICE_CLASS_ILLUMINANCE,
     ICON_BRIGHTNESS_5,
     ICON_BRIGHTNESS_6,
@@ -159,7 +159,7 @@ CONFIG_SCHEMA = cv.All(
                     unit_of_measurement=UNIT_COUNTS,
                     icon=ICON_BRIGHTNESS_5,
                     accuracy_decimals=0,
-                    device_class=DEVICE_CLASS_ILLUMINANCE,
+                    device_class=DEVICE_CLASS_EMPTY,
                     state_class=STATE_CLASS_MEASUREMENT,
                 ),
                 key=CONF_NAME,
@@ -169,7 +169,7 @@ CONFIG_SCHEMA = cv.All(
                     unit_of_measurement=UNIT_COUNTS,
                     icon=ICON_BRIGHTNESS_7,
                     accuracy_decimals=0,
-                    device_class=DEVICE_CLASS_ILLUMINANCE,
+                    device_class=DEVICE_CLASS_EMPTY,
                     state_class=STATE_CLASS_MEASUREMENT,
                 ),
                 key=CONF_NAME,
@@ -179,7 +179,7 @@ CONFIG_SCHEMA = cv.All(
                     unit_of_measurement=UNIT_COUNTS,
                     icon=ICON_PROXIMITY,
                     accuracy_decimals=0,
-                    device_class=DEVICE_CLASS_DISTANCE,
+                    device_class=DEVICE_CLASS_EMPTY,
                     state_class=STATE_CLASS_MEASUREMENT,
                 ),
                 key=CONF_NAME,
@@ -188,7 +188,7 @@ CONFIG_SCHEMA = cv.All(
                 sensor.sensor_schema(
                     icon=ICON_GAIN,
                     accuracy_decimals=0,
-                    device_class=DEVICE_CLASS_ILLUMINANCE,
+                    device_class=DEVICE_CLASS_EMPTY,
                     state_class=STATE_CLASS_MEASUREMENT,
                 ),
                 key=CONF_NAME,
diff --git a/esphome/components/veml7700/sensor.py b/esphome/components/veml7700/sensor.py
index 6ad2eb417f..d0d3584dc2 100644
--- a/esphome/components/veml7700/sensor.py
+++ b/esphome/components/veml7700/sensor.py
@@ -14,6 +14,7 @@ from esphome.const import (
     CONF_INFRARED,
     CONF_INTEGRATION_TIME,
     CONF_NAME,
+    DEVICE_CLASS_EMPTY,
     DEVICE_CLASS_ILLUMINANCE,
     ICON_BRIGHTNESS_5,
     ICON_BRIGHTNESS_6,
@@ -91,7 +92,7 @@ CONFIG_SCHEMA = cv.All(
                     unit_of_measurement=UNIT_COUNTS,
                     icon=ICON_BRIGHTNESS_6,
                     accuracy_decimals=0,
-                    device_class=DEVICE_CLASS_ILLUMINANCE,
+                    device_class=DEVICE_CLASS_EMPTY,
                     state_class=STATE_CLASS_MEASUREMENT,
                 ),
                 key=CONF_NAME,
@@ -111,7 +112,7 @@ CONFIG_SCHEMA = cv.All(
                     unit_of_measurement=UNIT_COUNTS,
                     icon=ICON_BRIGHTNESS_7,
                     accuracy_decimals=0,
-                    device_class=DEVICE_CLASS_ILLUMINANCE,
+                    device_class=DEVICE_CLASS_EMPTY,
                     state_class=STATE_CLASS_MEASUREMENT,
                 ),
                 key=CONF_NAME,

From 8da377ab43922307ff40440b8c5dad4f7f5de72a Mon Sep 17 00:00:00 2001
From: Keith Burzinski <kbx81x@gmail.com>
Date: Mon, 13 Jul 2026 18:56:03 -0500
Subject: [PATCH 14/24] [nextion] Fix unbounded queue growth and OOM crash when
 display sends no data (#17553)

---
 esphome/components/nextion/nextion.cpp | 32 +++++++++++++++++++-------
 esphome/components/nextion/nextion.h   |  4 ++++
 2 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/esphome/components/nextion/nextion.cpp b/esphome/components/nextion/nextion.cpp
index 4ebc717552..bdc66adb70 100644
--- a/esphome/components/nextion/nextion.cpp
+++ b/esphome/components/nextion/nextion.cpp
@@ -1,6 +1,7 @@
 #include "nextion.h"
 
 #include <cinttypes>
+#include <new>
 
 #include "esphome/core/application.h"
 #include "esphome/core/helpers.h"
@@ -352,8 +353,9 @@ void Nextion::loop() {
     this->connection_state_.ignore_is_setup_ = false;
   }
 
-  this->process_serial_();            // Receive serial data
-  this->process_nextion_commands_();  // Process nextion return commands
+  this->process_serial_();             // Receive serial data
+  this->process_nextion_commands_();   // Process nextion return commands
+  this->purge_stale_queue_entries_();  // Drop expired entries even when the display sends no data
 
   if (!this->connection_state_.nextion_reports_is_setup_) {
     if (this->started_ms_ == 0)
@@ -902,6 +904,11 @@ void Nextion::process_nextion_commands_() {
     this->command_data_.erase(0, to_process_length + DELIMITER_SIZE + 1);
   }
 
+  ESP_LOGN(TAG, "Loop end");
+  this->process_serial_();
+}  // Nextion::process_nextion_commands_()
+
+void Nextion::purge_stale_queue_entries_() {
   const uint32_t ms = App.get_loop_component_start_time();
 
   if (this->max_q_age_ms_ > 0 && !this->nextion_queue_.empty() &&
@@ -927,10 +934,7 @@ void Nextion::process_nextion_commands_() {
       }
     }
   }
-  ESP_LOGN(TAG, "Loop end");
-  // App.feed_wdt(); Remove before master merge
-  this->process_serial_();
-}  // Nextion::process_nextion_commands_()
+}
 
 void Nextion::set_nextion_sensor_state(int queue_type, const std::string &name, float state) {
   this->set_nextion_sensor_state(static_cast<NextionQueueType>(queue_type), name, state);
@@ -1101,7 +1105,13 @@ void Nextion::add_no_result_to_queue_(const std::string &variable_name) {
   new (nextion_queue) nextion::NextionQueue();
 
   // NOLINTNEXTLINE(cppcoreguidelines-owning-memory)
-  nextion_queue->component = new nextion::NextionComponentBase;
+  nextion_queue->component = new (std::nothrow) nextion::NextionComponentBase;
+  if (nextion_queue->component == nullptr) {
+    ESP_LOGW(TAG, "Component alloc failed");
+    nextion_queue->~NextionQueue();
+    allocator.deallocate(nextion_queue, 1);
+    return;
+  }
   nextion_queue->component->set_variable_name(variable_name);
 
   nextion_queue->queue_time = App.get_loop_component_start_time();
@@ -1157,7 +1167,13 @@ void Nextion::add_no_result_to_queue_with_pending_command_(const std::string &va
   }
   new (nextion_queue) nextion::NextionQueue();
 
-  nextion_queue->component = new nextion::NextionComponentBase;
+  nextion_queue->component = new (std::nothrow) nextion::NextionComponentBase;
+  if (nextion_queue->component == nullptr) {
+    ESP_LOGW(TAG, "Component alloc failed");
+    nextion_queue->~NextionQueue();
+    allocator.deallocate(nextion_queue, 1);
+    return;
+  }
   nextion_queue->component->set_variable_name(variable_name);
   nextion_queue->queue_time = App.get_loop_component_start_time();
   nextion_queue->pending_command = command;  // Store command for retry
diff --git a/esphome/components/nextion/nextion.h b/esphome/components/nextion/nextion.h
index d361d9725b..7dc5a4fe44 100644
--- a/esphome/components/nextion/nextion.h
+++ b/esphome/components/nextion/nextion.h
@@ -1486,6 +1486,10 @@ class Nextion final : public NextionBase, public PollingComponent, public uart::
 
   void process_nextion_commands_();
   void process_serial_();
+  /// Drop queue entries older than max_q_age_ms_. Called from loop() so it also runs when the
+  /// display sends no data at all (disconnected or asleep), which would otherwise grow the queue
+  /// without bound.
+  void purge_stale_queue_entries_();
   uint16_t touch_sleep_timeout_ = 0;
   uint8_t wake_up_page_ = 255;
 #ifdef USE_NEXTION_CONF_START_UP_PAGE

From 6fadf353b196dc31c9ffba2a7ff1e8baedae5f2b Mon Sep 17 00:00:00 2001
From: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
Date: Tue, 14 Jul 2026 12:40:45 +1200
Subject: [PATCH 15/24] Bump version to 2026.7.0b3

---
 Doxyfile         | 2 +-
 esphome/const.py | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Doxyfile b/Doxyfile
index 1bcfded35d..3bd4dc140f 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -48,7 +48,7 @@ PROJECT_NAME           = ESPHome
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 2026.7.0b2
+PROJECT_NUMBER         = 2026.7.0b3
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
diff --git a/esphome/const.py b/esphome/const.py
index f6014176b8..01ff67e3f2 100644
--- a/esphome/const.py
+++ b/esphome/const.py
@@ -4,7 +4,7 @@ from enum import Enum
 
 from esphome.enum import StrEnum
 
-__version__ = "2026.7.0b2"
+__version__ = "2026.7.0b3"
 
 ALLOWED_NAME_CHARS = "abcdefghijklmnopqrstuvwxyz0123456789-_"
 VALID_SUBSTITUTIONS_CHARACTERS = (

From db9a09d05a7b2e38f02dfe71aabc61b2ef9af627 Mon Sep 17 00:00:00 2001
From: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
Date: Tue, 14 Jul 2026 14:11:03 +1200
Subject: [PATCH 16/24] [script] Recursively expand nested packages when
 merging component tests (#17557)

---
 script/merge_component_configs.py            | 49 +++++++++++------
 tests/script/test_merge_component_configs.py | 56 ++++++++++++++++++++
 2 files changed, 89 insertions(+), 16 deletions(-)

diff --git a/script/merge_component_configs.py b/script/merge_component_configs.py
index 5eeeafac2a..c2be7be7fd 100755
--- a/script/merge_component_configs.py
+++ b/script/merge_component_configs.py
@@ -263,22 +263,39 @@ def prepare_component_body(comp_data: dict, comp_name: str, comp_dir: Path) -> d
         else {}
     )
 
-    packages_value = comp_data.get("packages")
-    if isinstance(packages_value, dict):
-        common_bus_packages = get_common_bus_packages()
-        for pkg_name, pkg_value in list(packages_value.items()):
-            if pkg_name in common_bus_packages:
-                continue
-            if isinstance(pkg_value, yaml_util.IncludeFile):
-                pkg_value = pkg_value.load()
-            if isinstance(pkg_value, dict):
-                comp_data = merge_config(comp_data, pkg_value)
-    elif isinstance(packages_value, list):
-        for pkg_value in packages_value:
-            if isinstance(pkg_value, yaml_util.IncludeFile):
-                pkg_value = pkg_value.load()
-            if isinstance(pkg_value, dict):
-                comp_data = merge_config(comp_data, pkg_value)
+    # Expand component-specific package includes inline. A package include may
+    # itself pull in further component-specific packages (e.g. web_server's test
+    # includes common_v2, which includes common with the wifi/network config), so
+    # keep expanding until only common bus packages remain -- otherwise the nested
+    # includes are silently dropped when the packages key is removed below.
+    common_bus_packages = get_common_bus_packages()
+    while True:
+        packages_value = comp_data.get("packages")
+        expanded = False
+        if isinstance(packages_value, dict):
+            for pkg_name, pkg_value in list(packages_value.items()):
+                if pkg_name in common_bus_packages:
+                    continue
+                # Drop before merging so a nested packages dict introduced by the
+                # include does not re-add this same key on the next iteration.
+                del packages_value[pkg_name]
+                if isinstance(pkg_value, yaml_util.IncludeFile):
+                    pkg_value = pkg_value.load()
+                if isinstance(pkg_value, dict):
+                    comp_data = merge_config(comp_data, pkg_value)
+                expanded = True
+        elif isinstance(packages_value, list):
+            # List-style packages never contain common bus packages, so expand
+            # them all and drop the key entirely.
+            comp_data.pop("packages", None)
+            for pkg_value in packages_value:
+                if isinstance(pkg_value, yaml_util.IncludeFile):
+                    pkg_value = pkg_value.load()
+                if isinstance(pkg_value, dict):
+                    comp_data = merge_config(comp_data, pkg_value)
+                    expanded = True
+        if not expanded:
+            break
     # Common bus packages are re-added once by the caller; drop them here.
     comp_data.pop("packages", None)
 
diff --git a/tests/script/test_merge_component_configs.py b/tests/script/test_merge_component_configs.py
index 6ed1bd2c1e..27be3b5628 100644
--- a/tests/script/test_merge_component_configs.py
+++ b/tests/script/test_merge_component_configs.py
@@ -10,7 +10,10 @@ sys.path.insert(0, str((Path(__file__).parent / ".." / ".." / "script").resolve(
 
 import merge_component_configs  # noqa: E402
 
+from esphome import yaml_util  # noqa: E402
+
 deduplicate_by_id = merge_component_configs.deduplicate_by_id
+prepare_component_body = merge_component_configs.prepare_component_body
 
 
 def test_identical_duplicate_ids_collapse() -> None:
@@ -99,3 +102,56 @@ def test_nested_lists_are_checked() -> None:
     }
     with pytest.raises(ValueError, match="dup"):
         deduplicate_by_id(data)
+
+
+def test_nested_package_includes_are_fully_expanded(tmp_path: Path) -> None:
+    """A package include that itself pulls in another package expands fully.
+
+    Mirrors web_server's tests, where test.yaml includes common_v2, which
+    includes common (holding the wifi/network config). Without recursive
+    expansion the nested include is dropped and network config is lost.
+    """
+    (tmp_path / "common.yaml").write_text("wifi:\n  ssid: MySSID\n")
+    (tmp_path / "common_v2.yaml").write_text(
+        "packages:\n  device_base: !include common.yaml\nweb_server:\n  port: 8080\n"
+    )
+    (tmp_path / "test.yaml").write_text(
+        "packages:\n  web_server: !include common_v2.yaml\n"
+        "web_server:\n  auth:\n    username: admin\n"
+    )
+
+    comp_data = yaml_util.load_yaml(tmp_path / "test.yaml")
+    result = prepare_component_body(comp_data, "web_server", tmp_path)
+
+    assert "packages" not in result
+    assert result["wifi"] == {"ssid": "MySSID"}
+    assert result["web_server"] == {"port": 8080, "auth": {"username": "admin"}}
+
+
+def test_common_bus_package_is_left_for_caller(tmp_path: Path) -> None:
+    """Common bus packages are not expanded inline; the caller re-adds them."""
+    comp_data = {
+        "packages": {
+            "i2c": {"sda": 21, "scl": 22},
+            "device_base": {"wifi": {"ssid": "MySSID"}},
+        },
+    }
+    result = prepare_component_body(comp_data, "mycomp", tmp_path)
+
+    # The bus package's body must not be merged in, and the packages key is
+    # dropped entirely for the caller to re-add the common bus package.
+    assert "packages" not in result
+    assert "sda" not in result
+    assert result["wifi"] == {"ssid": "MySSID"}
+
+
+def test_list_style_packages_are_expanded(tmp_path: Path) -> None:
+    """List-style package includes are expanded and the key removed."""
+    (tmp_path / "common.yaml").write_text("wifi:\n  ssid: MySSID\n")
+    (tmp_path / "test.yaml").write_text("packages:\n  - !include common.yaml\n")
+
+    comp_data = yaml_util.load_yaml(tmp_path / "test.yaml")
+    result = prepare_component_body(comp_data, "mycomp", tmp_path)
+
+    assert "packages" not in result
+    assert result["wifi"] == {"ssid": "MySSID"}

From 0a1065da75b3b4d6dea3ef9dd73f6789cf9e68ae Mon Sep 17 00:00:00 2001
From: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
Date: Tue, 14 Jul 2026 14:11:03 +1200
Subject: [PATCH 17/24] [script] Recursively expand nested packages when
 merging component tests (#17557)

---
 script/merge_component_configs.py            | 49 +++++++++++------
 tests/script/test_merge_component_configs.py | 56 ++++++++++++++++++++
 2 files changed, 89 insertions(+), 16 deletions(-)

diff --git a/script/merge_component_configs.py b/script/merge_component_configs.py
index 5eeeafac2a..c2be7be7fd 100755
--- a/script/merge_component_configs.py
+++ b/script/merge_component_configs.py
@@ -263,22 +263,39 @@ def prepare_component_body(comp_data: dict, comp_name: str, comp_dir: Path) -> d
         else {}
     )
 
-    packages_value = comp_data.get("packages")
-    if isinstance(packages_value, dict):
-        common_bus_packages = get_common_bus_packages()
-        for pkg_name, pkg_value in list(packages_value.items()):
-            if pkg_name in common_bus_packages:
-                continue
-            if isinstance(pkg_value, yaml_util.IncludeFile):
-                pkg_value = pkg_value.load()
-            if isinstance(pkg_value, dict):
-                comp_data = merge_config(comp_data, pkg_value)
-    elif isinstance(packages_value, list):
-        for pkg_value in packages_value:
-            if isinstance(pkg_value, yaml_util.IncludeFile):
-                pkg_value = pkg_value.load()
-            if isinstance(pkg_value, dict):
-                comp_data = merge_config(comp_data, pkg_value)
+    # Expand component-specific package includes inline. A package include may
+    # itself pull in further component-specific packages (e.g. web_server's test
+    # includes common_v2, which includes common with the wifi/network config), so
+    # keep expanding until only common bus packages remain -- otherwise the nested
+    # includes are silently dropped when the packages key is removed below.
+    common_bus_packages = get_common_bus_packages()
+    while True:
+        packages_value = comp_data.get("packages")
+        expanded = False
+        if isinstance(packages_value, dict):
+            for pkg_name, pkg_value in list(packages_value.items()):
+                if pkg_name in common_bus_packages:
+                    continue
+                # Drop before merging so a nested packages dict introduced by the
+                # include does not re-add this same key on the next iteration.
+                del packages_value[pkg_name]
+                if isinstance(pkg_value, yaml_util.IncludeFile):
+                    pkg_value = pkg_value.load()
+                if isinstance(pkg_value, dict):
+                    comp_data = merge_config(comp_data, pkg_value)
+                expanded = True
+        elif isinstance(packages_value, list):
+            # List-style packages never contain common bus packages, so expand
+            # them all and drop the key entirely.
+            comp_data.pop("packages", None)
+            for pkg_value in packages_value:
+                if isinstance(pkg_value, yaml_util.IncludeFile):
+                    pkg_value = pkg_value.load()
+                if isinstance(pkg_value, dict):
+                    comp_data = merge_config(comp_data, pkg_value)
+                    expanded = True
+        if not expanded:
+            break
     # Common bus packages are re-added once by the caller; drop them here.
     comp_data.pop("packages", None)
 
diff --git a/tests/script/test_merge_component_configs.py b/tests/script/test_merge_component_configs.py
index 6ed1bd2c1e..27be3b5628 100644
--- a/tests/script/test_merge_component_configs.py
+++ b/tests/script/test_merge_component_configs.py
@@ -10,7 +10,10 @@ sys.path.insert(0, str((Path(__file__).parent / ".." / ".." / "script").resolve(
 
 import merge_component_configs  # noqa: E402
 
+from esphome import yaml_util  # noqa: E402
+
 deduplicate_by_id = merge_component_configs.deduplicate_by_id
+prepare_component_body = merge_component_configs.prepare_component_body
 
 
 def test_identical_duplicate_ids_collapse() -> None:
@@ -99,3 +102,56 @@ def test_nested_lists_are_checked() -> None:
     }
     with pytest.raises(ValueError, match="dup"):
         deduplicate_by_id(data)
+
+
+def test_nested_package_includes_are_fully_expanded(tmp_path: Path) -> None:
+    """A package include that itself pulls in another package expands fully.
+
+    Mirrors web_server's tests, where test.yaml includes common_v2, which
+    includes common (holding the wifi/network config). Without recursive
+    expansion the nested include is dropped and network config is lost.
+    """
+    (tmp_path / "common.yaml").write_text("wifi:\n  ssid: MySSID\n")
+    (tmp_path / "common_v2.yaml").write_text(
+        "packages:\n  device_base: !include common.yaml\nweb_server:\n  port: 8080\n"
+    )
+    (tmp_path / "test.yaml").write_text(
+        "packages:\n  web_server: !include common_v2.yaml\n"
+        "web_server:\n  auth:\n    username: admin\n"
+    )
+
+    comp_data = yaml_util.load_yaml(tmp_path / "test.yaml")
+    result = prepare_component_body(comp_data, "web_server", tmp_path)
+
+    assert "packages" not in result
+    assert result["wifi"] == {"ssid": "MySSID"}
+    assert result["web_server"] == {"port": 8080, "auth": {"username": "admin"}}
+
+
+def test_common_bus_package_is_left_for_caller(tmp_path: Path) -> None:
+    """Common bus packages are not expanded inline; the caller re-adds them."""
+    comp_data = {
+        "packages": {
+            "i2c": {"sda": 21, "scl": 22},
+            "device_base": {"wifi": {"ssid": "MySSID"}},
+        },
+    }
+    result = prepare_component_body(comp_data, "mycomp", tmp_path)
+
+    # The bus package's body must not be merged in, and the packages key is
+    # dropped entirely for the caller to re-add the common bus package.
+    assert "packages" not in result
+    assert "sda" not in result
+    assert result["wifi"] == {"ssid": "MySSID"}
+
+
+def test_list_style_packages_are_expanded(tmp_path: Path) -> None:
+    """List-style package includes are expanded and the key removed."""
+    (tmp_path / "common.yaml").write_text("wifi:\n  ssid: MySSID\n")
+    (tmp_path / "test.yaml").write_text("packages:\n  - !include common.yaml\n")
+
+    comp_data = yaml_util.load_yaml(tmp_path / "test.yaml")
+    result = prepare_component_body(comp_data, "mycomp", tmp_path)
+
+    assert "packages" not in result
+    assert result["wifi"] == {"ssid": "MySSID"}

From b6b5b6164082fcbfa8f9aba1e7bde872af24063d Mon Sep 17 00:00:00 2001
From: Daniele Palumbo <daniele@retaggio.net>
Date: Tue, 14 Jul 2026 04:38:07 +0200
Subject: [PATCH 18/24] [mcp23017] reset IPOL registers to 0x00 on setup
 (#17177)

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
---
 esphome/components/mcp23017/mcp23017.cpp | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/esphome/components/mcp23017/mcp23017.cpp b/esphome/components/mcp23017/mcp23017.cpp
index 9e3d75575a..173d117457 100644
--- a/esphome/components/mcp23017/mcp23017.cpp
+++ b/esphome/components/mcp23017/mcp23017.cpp
@@ -19,6 +19,10 @@ void MCP23017::setup() {
   this->read_reg(mcp23x17_base::MCP23X17_OLATA, &this->olat_a_);
   this->read_reg(mcp23x17_base::MCP23X17_OLATB, &this->olat_b_);
 
+  // Reset IPOL to 0x00: ESPHome handles 'inverted' in software.
+  this->write_reg(mcp23x17_base::MCP23X17_IPOLA, 0x00);
+  this->write_reg(mcp23x17_base::MCP23X17_IPOLB, 0x00);
+
   uint8_t iocon_flags = 0;
   if (this->open_drain_ints_) {
     iocon_flags |= IOCON_ODR;

From 2753ab1f4570e76129aea55f06e89e8a7c4dcb4a Mon Sep 17 00:00:00 2001
From: "esphome[bot]" <115708604+esphome[bot]@users.noreply.github.com>
Date: Mon, 13 Jul 2026 16:50:08 -1000
Subject: [PATCH 19/24] Bump bundled esphome-device-builder to 1.5.0 (#17558)

---
 docker/Dockerfile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docker/Dockerfile b/docker/Dockerfile
index f09280a50e..01ff53a463 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -22,7 +22,7 @@ RUN \
     -r /requirements.txt
 
 # Install the ESPHome Device Builder dashboard.
-RUN uv pip install --no-cache-dir esphome-device-builder==1.4.3
+RUN uv pip install --no-cache-dir esphome-device-builder==1.5.0
 
 RUN \
     platformio settings set enable_telemetry No \

From a833685a730679801e956b9e0b278affbe714a8a Mon Sep 17 00:00:00 2001
From: "esphome[bot]" <115708604+esphome[bot]@users.noreply.github.com>
Date: Mon, 13 Jul 2026 16:50:08 -1000
Subject: [PATCH 20/24] Bump bundled esphome-device-builder to 1.5.0 (#17558)

---
 docker/Dockerfile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docker/Dockerfile b/docker/Dockerfile
index f09280a50e..01ff53a463 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -22,7 +22,7 @@ RUN \
     -r /requirements.txt
 
 # Install the ESPHome Device Builder dashboard.
-RUN uv pip install --no-cache-dir esphome-device-builder==1.4.3
+RUN uv pip install --no-cache-dir esphome-device-builder==1.5.0
 
 RUN \
     platformio settings set enable_telemetry No \

From 4ebe49b141f49dae8ca5815111011b80f85b2bd5 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 14 Jul 2026 09:54:02 -1000
Subject: [PATCH 21/24] Bump clang-tidy from 22.1.7 to 22.1.8 (#17565)

Signed-off-by: dependabot[bot] <support@github.com>
---
 requirements_dev.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/requirements_dev.txt b/requirements_dev.txt
index 7e66c7244d..f2cf855d6b 100644
--- a/requirements_dev.txt
+++ b/requirements_dev.txt
@@ -1,4 +1,4 @@
 # Useful stuff when working in a development environment
 clang-format==13.0.1  # also change in .pre-commit-config.yaml and Dockerfile when updating
-clang-tidy==22.1.7
+clang-tidy==22.1.8
 yamllint==1.38.0  # also change in .pre-commit-config.yaml when updating

From 427534323114264b0f89ee3bdf0bbe95b7383c5e Mon Sep 17 00:00:00 2001
From: Jonathan Swoboda <154711427+swoboda1337@users.noreply.github.com>
Date: Tue, 14 Jul 2026 17:23:37 -0400
Subject: [PATCH 22/24] [atc_mithermometer] Make duplicate-packet counter
 per-instance (#17496)

---
 esphome/components/atc_mithermometer/atc_mithermometer.cpp | 7 +++----
 esphome/components/atc_mithermometer/atc_mithermometer.h   | 2 ++
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/esphome/components/atc_mithermometer/atc_mithermometer.cpp b/esphome/components/atc_mithermometer/atc_mithermometer.cpp
index f8bbd9d55e..7b5cdcfa20 100644
--- a/esphome/components/atc_mithermometer/atc_mithermometer.cpp
+++ b/esphome/components/atc_mithermometer/atc_mithermometer.cpp
@@ -65,12 +65,11 @@ optional<ParseResult> ATCMiThermometer::parse_header_(const esp32_ble_tracker::S
     return {};
   }
 
-  static uint8_t last_frame_count = 0;
-  if (last_frame_count == raw[12]) {
-    ESP_LOGVV(TAG, "parse_header(): duplicate data packet received (%hhu).", last_frame_count);
+  if (this->last_frame_count_ == raw[12]) {
+    ESP_LOGVV(TAG, "parse_header(): duplicate data packet received (%hhu).", this->last_frame_count_);
     return {};
   }
-  last_frame_count = raw[12];
+  this->last_frame_count_ = raw[12];
 
   return result;
 }
diff --git a/esphome/components/atc_mithermometer/atc_mithermometer.h b/esphome/components/atc_mithermometer/atc_mithermometer.h
index 3dde5f1868..0f472c11b9 100644
--- a/esphome/components/atc_mithermometer/atc_mithermometer.h
+++ b/esphome/components/atc_mithermometer/atc_mithermometer.h
@@ -38,6 +38,8 @@ class ATCMiThermometer final : public Component, public esp32_ble_tracker::ESPBT
   sensor::Sensor *battery_voltage_{nullptr};
   sensor::Sensor *signal_strength_{nullptr};
 
+  uint8_t last_frame_count_{0};
+
   optional<ParseResult> parse_header_(const esp32_ble_tracker::ServiceData &service_data);
   bool parse_message_(const std::vector<uint8_t> &message, ParseResult &result);
   bool report_results_(const optional<ParseResult> &result, const char *address);

From e2b62bcd00950fbe7b868e1513fdb9376cb5236e Mon Sep 17 00:00:00 2001
From: luar123 <49960470+luar123@users.noreply.github.com>
Date: Tue, 14 Jul 2026 23:27:17 +0200
Subject: [PATCH 23/24] [zigbee] bump esp-zigbee-sdk to 2.0.3 (#17564)

---
 esphome/components/zigbee/zigbee_esp32.py | 2 +-
 esphome/idf_component.yml                 | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/esphome/components/zigbee/zigbee_esp32.py b/esphome/components/zigbee/zigbee_esp32.py
index 73dcd07029..116dce8cc5 100644
--- a/esphome/components/zigbee/zigbee_esp32.py
+++ b/esphome/components/zigbee/zigbee_esp32.py
@@ -274,7 +274,7 @@ async def attributes_to_code(
 async def esp32_to_code(config: ConfigType) -> "MockObj":
     add_idf_component(
         name="espressif/esp-zigbee-lib",
-        ref="2.0.2",
+        ref="2.0.3",
     )
 
     # add sdkconfigs later so they can overwrite esp32 defaults
diff --git a/esphome/idf_component.yml b/esphome/idf_component.yml
index 7ad41fa978..60b00d33c7 100644
--- a/esphome/idf_component.yml
+++ b/esphome/idf_component.yml
@@ -48,7 +48,7 @@ dependencies:
     rules:
       - if: "target in [esp32, esp32p4]"
   espressif/esp-zigbee-lib:
-    version: 2.0.2
+    version: 2.0.3
     rules:
       - if: "target in [esp32h2, esp32c5, esp32c6]"
   espressif/lan87xx:

From a5583dcba60946492846d0b5c7a64966b2e352aa Mon Sep 17 00:00:00 2001
From: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
Date: Wed, 15 Jul 2026 11:22:47 +1200
Subject: [PATCH 24/24] [tests] Add test_display component to free touchscreen
 tests from display pins (#17540)

---
 .../components/gsl3670/test.esp32-s3-idf.yaml | 18 ++--------
 tests/components/gt911/common.yaml            | 13 +------
 tests/components/gt911/test.esp32-idf.yaml    |  5 ++-
 tests/components/gt911/test.esp8266-ard.yaml  |  5 ++-
 tests/components/gt911/test.rp2040-ard.yaml   |  5 ++-
 tests/components/test_display/common.yaml     | 13 +++++++
 .../components/test_display/__init__.py       |  0
 .../components/test_display/display.py        | 36 +++++++++++++++++++
 .../components/test_display/test_display.h    | 36 +++++++++++++++++++
 .../test_display/test.esp32-idf.yaml          |  3 ++
 .../test_display/test.esp8266-ard.yaml        |  3 ++
 .../test_display/test.rp2040-ard.yaml         |  3 ++
 tests/components/tt21100/common.yaml          | 13 +------
 tests/components/tt21100/test.esp32-idf.yaml  |  5 ++-
 .../components/tt21100/test.esp8266-ard.yaml  |  5 ++-
 tests/components/tt21100/test.rp2040-ard.yaml |  5 ++-
 .../common/test_display/test_display.yaml     | 26 ++++++++++++++
 17 files changed, 137 insertions(+), 57 deletions(-)
 create mode 100644 tests/components/test_display/common.yaml
 create mode 100644 tests/components/test_display/components/test_display/__init__.py
 create mode 100644 tests/components/test_display/components/test_display/display.py
 create mode 100644 tests/components/test_display/components/test_display/test_display.h
 create mode 100644 tests/components/test_display/test.esp32-idf.yaml
 create mode 100644 tests/components/test_display/test.esp8266-ard.yaml
 create mode 100644 tests/components/test_display/test.rp2040-ard.yaml
 create mode 100644 tests/test_build_components/common/test_display/test_display.yaml

diff --git a/tests/components/gsl3670/test.esp32-s3-idf.yaml b/tests/components/gsl3670/test.esp32-s3-idf.yaml
index 5c3f4b931c..384e12eaba 100644
--- a/tests/components/gsl3670/test.esp32-s3-idf.yaml
+++ b/tests/components/gsl3670/test.esp32-s3-idf.yaml
@@ -1,32 +1,20 @@
 packages:
   i2c: !include ../../test_build_components/common/i2c/esp32-s3-idf.yaml
-  spi: !include ../../test_build_components/common/spi/esp32-s3-idf.yaml
+  test_display: !include ../../test_build_components/common/test_display/test_display.yaml
 
 xl9535:
   id: expander
 
-display:
-  - platform: mipi_spi
-    id: gsl3670_display
-    spi_id: spi_bus
-    model: t-display-s3-pro
-    # The model's default DC pin (GPIO9) clashes with the shared i2c bus SCL
-    # pin, so override it onto a free pin for this test.
-    dc_pin: GPIO5
-
-psram:
-  mode: quad
-
 touchscreen:
   # Firmware downloaded from the model's default release URL and cached.
   - platform: gsl3670
     model: seeed-reterminal-d1001
-    display: gsl3670_display
+    display: test_display_screen
     interrupt_pin: 18
   # Explicit firmware URL + SHA-256 override.
   - platform: gsl3670
     model: seeed-reterminal-d1001
-    display: gsl3670_display
+    display: test_display_screen
     reset_pin: 10
     interrupt_pin: 11
     firmware:
diff --git a/tests/components/gt911/common.yaml b/tests/components/gt911/common.yaml
index 0fc40737f0..24a67e2e45 100644
--- a/tests/components/gt911/common.yaml
+++ b/tests/components/gt911/common.yaml
@@ -1,19 +1,8 @@
-display:
-  - platform: ssd1306_i2c
-    i2c_id: i2c_bus
-    id: gt911_ssd1306_i2c_display
-    model: SSD1306_128X64
-    reset_pin: ${display_reset_pin}
-    pages:
-      - id: gt911_page1
-        lambda: |-
-          it.rectangle(0, 0, it.get_width(), it.get_height());
-
 touchscreen:
   - platform: gt911
     i2c_id: i2c_bus
     id: gt911_touchscreen
-    display: gt911_ssd1306_i2c_display
+    display: test_display_screen
     interrupt_pin: ${interrupt_pin}
     reset_pin: ${reset_pin}
 
diff --git a/tests/components/gt911/test.esp32-idf.yaml b/tests/components/gt911/test.esp32-idf.yaml
index 3bce86d9a3..9c2de1a425 100644
--- a/tests/components/gt911/test.esp32-idf.yaml
+++ b/tests/components/gt911/test.esp32-idf.yaml
@@ -1,9 +1,8 @@
 substitutions:
-  display_reset_pin: "10"
   interrupt_pin: "20"
   reset_pin: "21"
 
 packages:
   i2c: !include ../../test_build_components/common/i2c/esp32-idf.yaml
-
-<<: !include common.yaml
+  test_display: !include ../../test_build_components/common/test_display/test_display.yaml
+  gt911: !include common.yaml
diff --git a/tests/components/gt911/test.esp8266-ard.yaml b/tests/components/gt911/test.esp8266-ard.yaml
index c3bc159b5b..59af399be8 100644
--- a/tests/components/gt911/test.esp8266-ard.yaml
+++ b/tests/components/gt911/test.esp8266-ard.yaml
@@ -1,9 +1,8 @@
 substitutions:
-  display_reset_pin: "10"
   interrupt_pin: "12"
   reset_pin: "13"
 
 packages:
   i2c: !include ../../test_build_components/common/i2c/esp8266-ard.yaml
-
-<<: !include common.yaml
+  test_display: !include ../../test_build_components/common/test_display/test_display.yaml
+  gt911: !include common.yaml
diff --git a/tests/components/gt911/test.rp2040-ard.yaml b/tests/components/gt911/test.rp2040-ard.yaml
index 0c7f0bc504..efd5d9c2b1 100644
--- a/tests/components/gt911/test.rp2040-ard.yaml
+++ b/tests/components/gt911/test.rp2040-ard.yaml
@@ -1,9 +1,8 @@
 substitutions:
-  display_reset_pin: "10"
   interrupt_pin: "20"
   reset_pin: "21"
 
 packages:
   i2c: !include ../../test_build_components/common/i2c/rp2040-ard.yaml
-
-<<: !include common.yaml
+  test_display: !include ../../test_build_components/common/test_display/test_display.yaml
+  gt911: !include common.yaml
diff --git a/tests/components/test_display/common.yaml b/tests/components/test_display/common.yaml
new file mode 100644
index 0000000000..c36cf4b997
--- /dev/null
+++ b/tests/components/test_display/common.yaml
@@ -0,0 +1,13 @@
+# The test_display platform (and its external_components entry) is provided by
+# the shared package included from the test.*.yaml files. These extra instances
+# exercise the remaining `dimensions` code paths: the width/height map form and
+# the default when omitted. The package's own `test_display_screen` covers the
+# "WIDTHxHEIGHT" string form.
+display:
+  - platform: test_display
+    id: test_display_wh_dimensions
+    dimensions:
+      width: 320
+      height: 240
+  - platform: test_display
+    id: test_display_default_dimensions
diff --git a/tests/components/test_display/components/test_display/__init__.py b/tests/components/test_display/components/test_display/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/tests/components/test_display/components/test_display/display.py b/tests/components/test_display/components/test_display/display.py
new file mode 100644
index 0000000000..8503053b46
--- /dev/null
+++ b/tests/components/test_display/components/test_display/display.py
@@ -0,0 +1,36 @@
+import esphome.codegen as cg
+from esphome.components import display
+import esphome.config_validation as cv
+from esphome.const import CONF_DIMENSIONS, CONF_HEIGHT, CONF_ID, CONF_WIDTH
+from esphome.core import CoroPriority, coroutine_with_priority
+
+test_display_ns = cg.esphome_ns.namespace("test_display")
+TestDisplay = test_display_ns.class_("TestDisplay", display.Display)
+
+CONFIG_SCHEMA = display.FULL_DISPLAY_SCHEMA.extend(
+    {
+        cv.GenerateID(): cv.declare_id(TestDisplay),
+        cv.Optional(CONF_DIMENSIONS, default="100x100"): cv.Any(
+            cv.dimensions,
+            cv.Schema(
+                {
+                    cv.Required(CONF_WIDTH): cv.int_,
+                    cv.Required(CONF_HEIGHT): cv.int_,
+                }
+            ),
+        ),
+    }
+)
+
+
+@coroutine_with_priority(CoroPriority.CORE)
+async def to_code(config):
+    var = cg.new_Pvariable(config[CONF_ID])
+    await display.register_display(var, config)
+
+    dimensions = config[CONF_DIMENSIONS]
+    if isinstance(dimensions, dict):
+        width, height = dimensions[CONF_WIDTH], dimensions[CONF_HEIGHT]
+    else:
+        width, height = dimensions
+    cg.add(var.set_dimensions(width, height))
diff --git a/tests/components/test_display/components/test_display/test_display.h b/tests/components/test_display/components/test_display/test_display.h
new file mode 100644
index 0000000000..3f2b03a773
--- /dev/null
+++ b/tests/components/test_display/components/test_display/test_display.h
@@ -0,0 +1,36 @@
+#pragma once
+
+#include "esphome/components/display/display.h"
+#include "esphome/core/color.h"
+
+namespace esphome::test_display {
+
+/** A no-op display that draws nothing and uses no pins.
+ *
+ * It exists purely to satisfy components that require a display (for example
+ * touchscreens, which read the display dimensions) in configurations - most
+ * notably YAML build tests - where a real display driver would only get in the
+ * way by occupying GPIO pins and pulling in bus dependencies.
+ */
+class TestDisplay : public display::Display {
+ public:
+  void update() override { this->do_update_(); }
+
+  void set_dimensions(int width, int height) {
+    this->width_ = width;
+    this->height_ = height;
+  }
+
+  display::DisplayType get_display_type() override { return display::DisplayType::DISPLAY_TYPE_COLOR; }
+
+  void draw_pixel_at(int x, int y, Color color) override {}
+
+ protected:
+  int get_width_internal() override { return this->width_; }
+  int get_height_internal() override { return this->height_; }
+
+  int width_{0};
+  int height_{0};
+};
+
+}  // namespace esphome::test_display
diff --git a/tests/components/test_display/test.esp32-idf.yaml b/tests/components/test_display/test.esp32-idf.yaml
new file mode 100644
index 0000000000..dfc8006c38
--- /dev/null
+++ b/tests/components/test_display/test.esp32-idf.yaml
@@ -0,0 +1,3 @@
+packages:
+  test_display: !include ../../test_build_components/common/test_display/test_display.yaml
+  test_display_extra: !include common.yaml
diff --git a/tests/components/test_display/test.esp8266-ard.yaml b/tests/components/test_display/test.esp8266-ard.yaml
new file mode 100644
index 0000000000..dfc8006c38
--- /dev/null
+++ b/tests/components/test_display/test.esp8266-ard.yaml
@@ -0,0 +1,3 @@
+packages:
+  test_display: !include ../../test_build_components/common/test_display/test_display.yaml
+  test_display_extra: !include common.yaml
diff --git a/tests/components/test_display/test.rp2040-ard.yaml b/tests/components/test_display/test.rp2040-ard.yaml
new file mode 100644
index 0000000000..dfc8006c38
--- /dev/null
+++ b/tests/components/test_display/test.rp2040-ard.yaml
@@ -0,0 +1,3 @@
+packages:
+  test_display: !include ../../test_build_components/common/test_display/test_display.yaml
+  test_display_extra: !include common.yaml
diff --git a/tests/components/tt21100/common.yaml b/tests/components/tt21100/common.yaml
index 1f9249f1ba..5cb6b99a8e 100644
--- a/tests/components/tt21100/common.yaml
+++ b/tests/components/tt21100/common.yaml
@@ -1,19 +1,8 @@
-display:
-  - platform: ssd1306_i2c
-    i2c_id: i2c_bus
-    id: tt21100_ssd1306_i2c_display
-    model: SSD1306_128X64
-    reset_pin: ${disp_reset_pin}
-    pages:
-      - id: tt21100_page1
-        lambda: |-
-          it.rectangle(0, 0, it.get_width(), it.get_height());
-
 touchscreen:
   - platform: tt21100
     i2c_id: i2c_bus
     id: tt21100_touchscreen
-    display: tt21100_ssd1306_i2c_display
+    display: test_display_screen
     interrupt_pin: ${interrupt_pin}
     reset_pin: ${reset_pin}
 
diff --git a/tests/components/tt21100/test.esp32-idf.yaml b/tests/components/tt21100/test.esp32-idf.yaml
index 033aafb73c..a79695d611 100644
--- a/tests/components/tt21100/test.esp32-idf.yaml
+++ b/tests/components/tt21100/test.esp32-idf.yaml
@@ -1,9 +1,8 @@
 substitutions:
-  disp_reset_pin: GPIO12
   interrupt_pin: GPIO15
   reset_pin: GPIO4
 
 packages:
   i2c: !include ../../test_build_components/common/i2c/esp32-idf.yaml
-
-<<: !include common.yaml
+  test_display: !include ../../test_build_components/common/test_display/test_display.yaml
+  tt21100: !include common.yaml
diff --git a/tests/components/tt21100/test.esp8266-ard.yaml b/tests/components/tt21100/test.esp8266-ard.yaml
index 25d1ff82e3..ae6977c6ec 100644
--- a/tests/components/tt21100/test.esp8266-ard.yaml
+++ b/tests/components/tt21100/test.esp8266-ard.yaml
@@ -1,9 +1,8 @@
 substitutions:
-  disp_reset_pin: GPIO0
   interrupt_pin: GPIO15
   reset_pin: GPIO16
 
 packages:
   i2c: !include ../../test_build_components/common/i2c/esp8266-ard.yaml
-
-<<: !include common.yaml
+  test_display: !include ../../test_build_components/common/test_display/test_display.yaml
+  tt21100: !include common.yaml
diff --git a/tests/components/tt21100/test.rp2040-ard.yaml b/tests/components/tt21100/test.rp2040-ard.yaml
index 0d13628294..98b2ad600c 100644
--- a/tests/components/tt21100/test.rp2040-ard.yaml
+++ b/tests/components/tt21100/test.rp2040-ard.yaml
@@ -1,9 +1,8 @@
 substitutions:
-  disp_reset_pin: GPIO10
   interrupt_pin: GPIO2
   reset_pin: GPIO3
 
 packages:
   i2c: !include ../../test_build_components/common/i2c/rp2040-ard.yaml
-
-<<: !include common.yaml
+  test_display: !include ../../test_build_components/common/test_display/test_display.yaml
+  tt21100: !include common.yaml
diff --git a/tests/test_build_components/common/test_display/test_display.yaml b/tests/test_build_components/common/test_display/test_display.yaml
new file mode 100644
index 0000000000..986ab45223
--- /dev/null
+++ b/tests/test_build_components/common/test_display/test_display.yaml
@@ -0,0 +1,26 @@
+# Shared "test display" package for component tests.
+#
+# Provides a no-op display (id: test_display_screen) that uses no pins and no
+# bus, so tests that only need a display to exist -- touchscreens especially --
+# don't have to instantiate a real driver and fight it over GPIOs. Include it
+# like a common bus package; the consuming test does NOT need to declare
+# external_components itself:
+#
+#   packages:
+#     test_display: !include ../../test_build_components/common/test_display/test_display.yaml
+#
+# then point the touchscreen (or other display consumer) at `test_display_screen`.
+#
+# The test_display platform lives at tests/components/test_display/components/ and
+# is loaded via external_components. The source path is written relative to the
+# build directory (tests/test_build_components/build/), which every test --
+# standalone or grouped -- is generated into, so this always resolves to the
+# component under tests/components/test_display/.
+external_components:
+  - source: ../../components/test_display/components
+    components: [test_display]
+
+display:
+  - platform: test_display
+    id: test_display_screen
+    dimensions: 240x320