Merge remote-tracking branch 'upstream/dev' into noise-session-resume

AGENTS.md

@@ -44,6 +44,16 @@ This document provides essential context for AI models interacting with this pro
 
 ## 4. Coding Conventions & Style Guide
 
+**Read the developer documentation before writing a component.** https://developers.esphome.io covers the
+component lifecycle, the main loop, and the reasoning behind the rules below in far more depth than this
+file does, and it is the authority when they disagree. The most useful starting points:
+
+*   https://developers.esphome.io/architecture/components/ - component lifecycle, `setup()`, `loop()`,
+    setup priorities, and how a component is registered.
+*   https://developers.esphome.io/architecture/components/advanced/ - choosing between `loop()`,
+    `set_interval`, `set_timeout` and `defer`; waking the loop from another thread; the RAM cost of each.
+*   https://developers.esphome.io/contributing/code/ - contribution rules, public API and breaking changes.
+
 *   **Formatting:**
     *   **Python:** Uses `ruff` and `flake8` for linting and formatting. Configuration is in `pyproject.toml`.
     *   **C++:** Uses `clang-format` for formatting. Configuration is in `.clang-format`.
@@ -142,6 +152,47 @@ This document provides essential context for AI models interacting with this pro
     *   **Indentation:** Use spaces (two per indentation level), not tabs
     *   **Type aliases:** Prefer `using type_t = int;` over `typedef int type_t;`
     *   **Line length:** Wrap lines at no more than 120 characters
+    *   **Timing in `loop()`:** Never call `millis()` in a `loop()` body. The current tick's timestamp is
+        already cached - use `App.get_loop_component_start_time()` (from `esphome/core/application.h`).
+        Only reach for `millis()` when you genuinely need sub-tick resolution inside a long operation.
+    *   **The main loop runs every 16 ms.** A rate-limit gate shorter than that does nothing: the check
+        passes on essentially every pass of the loop, so it costs a comparison and buys nothing. Pick an
+        interval comfortably coarser than 16 ms, or drop the gate entirely and accept running every loop.
+        ```cpp
+        // Bad - a 10ms gate against a 16ms loop never holds anything back
+        static constexpr uint32_t POLL_INTERVAL_MS = 10;
+        const uint32_t now = millis();
+        if (now - this->last_poll_ < POLL_INTERVAL_MS)
+          return;
+        this->last_poll_ = now;
+        ```
+        ```cpp
+        // Good - an interval that actually rate limits, off the cached timestamp
+        static constexpr uint32_t POLL_INTERVAL_MS = 100;
+        const uint32_t now = App.get_loop_component_start_time();
+        if (now - this->last_poll_ < POLL_INTERVAL_MS)
+          return;
+        this->last_poll_ = now;
+        ```
+        Pick the primitive by cadence: under 250 ms use a gated `loop()`; 500 ms and above use
+        `set_interval`. Full reasoning, including why `set_interval` costs more below 500 ms:
+        https://developers.esphome.io/architecture/components/advanced/#quick-rule-of-thumb
+    *   **Don't override a default with the same value:** if a base class method already returns what you
+        want, do not override it. `Component::get_setup_priority()` returns `setup_priority::DATA`, so a
+        component that wants `DATA` should simply leave it alone.
+        ```cpp
+        // Bad - this is exactly what the base class already does
+        float get_setup_priority() const override { return setup_priority::DATA; }
+        ```
+    *   **Logging string literals:** wrap literals passed as `%s` arguments in `LOG_STR_LITERAL()` so they
+        can be stored in flash rather than RAM.
+        ```cpp
+        // Bad
+        ESP_LOGV(TAG, "Key %u %s", key, pressed ? "pressed" : "released");
+
+        // Good
+        ESP_LOGV(TAG, "Key %u %s", key, pressed ? LOG_STR_LITERAL("pressed") : LOG_STR_LITERAL("released"));
+        ```
     *   **Constructor parameters vs setters:** Component properties that are both **required** and **invariant**
         (never change after construction) should be constructor parameters rather than set via setter methods.
         This makes the dependency explicit and prevents use of the object in an incompletely-initialized state.
@@ -562,6 +613,33 @@ This document provides essential context for AI models interacting with this pro
            Use `cg.add_define("MAX_SERVICES", count)` to set the size from Python configuration.
            Like `std::array` but with vector-like API (`push_back()`, `size()`) and no STL reallocation code.
 
+           **Listener and child-entity registration lists are the most common case, and the most commonly
+           missed.** A `register_*()` method called once per child at code generation time has a count that
+           is known at compile time, so it should never be a `std::vector`. Use `cg.slot_counter()`: it
+           returns a function that each consumer calls once per slot it will occupy, and after every
+           `to_code` has run it emits the define with the final count. When nothing registers, no define is
+           emitted and the storage plus its registration method compile out entirely.
+           ```python
+           # hub component's __init__.py
+           _request_listener_slot = cg.slot_counter("MY_COMPONENT_LISTENER_COUNT")
+
+
+           async def register_listener(hub: MockObj, var: MockObj) -> None:
+               _request_listener_slot()
+               cg.add(hub.register_listener(var))
+           ```
+           ```cpp
+           #ifdef MY_COMPONENT_LISTENER_COUNT
+             void register_listener(MyComponentListener *listener);
+           #endif
+            protected:
+           #ifdef MY_COMPONENT_LISTENER_COUNT
+             StaticVector<MyComponentListener *, MY_COMPONENT_LISTENER_COUNT> listeners_;
+           #endif
+           ```
+           Request slots from `to_code`, not from a job that runs after `CoroPriority.FINAL` - a late
+           request raises rather than silently undercounting.
+
         3. **Runtime-known sizes:** Use `FixedVector` from `esphome/core/helpers.h` when the size is only known at runtime initialization.
            ```cpp
            // Bad - generates STL realloc code (_M_realloc_insert)
@@ -599,9 +677,25 @@ This document provides essential context for AI models interacting with this pro
            ```
            Linear search on small datasets (1-16 elements) is often faster than hashing/tree overhead, but this depends on lookup frequency and access patterns. For frequent lookups in hot code paths, the O(1) vs O(n) complexity difference may still matter even for small datasets. `std::vector` with simple structs is usually fine—it's the heavy containers (`map`, `set`, `unordered_map`) that should be avoided for small datasets unless profiling shows otherwise.
 
-        5. **Avoid `std::deque`:** It allocates in 512-byte blocks regardless of element size, guaranteeing at least 512 bytes of RAM usage immediately. This is a major source of crashes on memory-constrained devices.
+        5. **Strings set once from configuration:** Use `StringRef` (`esphome/core/string_ref.h`) rather than
+           `std::string`. Code generation passes a string literal that lives in flash for the life of the
+           program, so storing a `std::string` copies it onto the heap for nothing. `StringRef` is a
+           non-owning pointer plus length; it does not copy, and it must only ever refer to storage that
+           outlives it (a string literal, or a buffer owned elsewhere).
+           ```cpp
+           // Bad - heap copy of a literal that is already in flash
+           void set_keys(std::string keys) { this->keys_ = std::move(keys); }
+           std::string keys_;
+           ```
+           ```cpp
+           // Good - no allocation
+           void set_keys(const char *keys) { this->keys_ = StringRef(keys); }
+           StringRef keys_;
+           ```
 
-        6. **Detection:** Look for these patterns in compiler output:
+        6. **Avoid `std::deque`:** It allocates in 512-byte blocks regardless of element size, guaranteeing at least 512 bytes of RAM usage immediately. This is a major source of crashes on memory-constrained devices.
+
+        7. **Detection:** Look for these patterns in compiler output:
            - Large code sections with STL symbols (vector, map, set)
            - `alloc`, `realloc`, `dealloc` in symbol names
            - `_M_realloc_insert`, `_M_default_append` (vector reallocation)

esphome/components/api/api.proto

@@ -893,6 +893,20 @@ message NoiseEncryptionSetKeyResponse {
   bool success = 1;
 }
 
+// Single-use session resume ticket, sent unsolicited by the device after a
+// Noise connection authenticates. A client presents it in the ClientHello of
+// its next connection to skip the curve25519 handshake; the device then
+// issues a fresh ticket on that connection. Never sent on plaintext
+// connections. Clients that do not understand it drop it silently.
+// Contents are secret; the device generator redacts this message from dump_to
+message NoiseResumeTicket {
+  option (id) = 152;
+  option (source) = SOURCE_SERVER;
+  option (ifdef) = "USE_API_NOISE";
+
+  bytes ticket = 1;  // session_id(8) || secret(32)
+}
+
 // ==================== HOMEASSISTANT.SERVICE ====================
 message SubscribeHomeassistantServicesRequest {
   option (id) = 34;

esphome/components/api/api_connection.cpp

@@ -1779,6 +1779,9 @@ void APIConnection::complete_authentication_() {
     this->send_time_request();
   }
 #endif
+#ifdef USE_API_NOISE
+  this->send_resume_ticket_();
+#endif
 #ifdef USE_ZWAVE_PROXY
   if (zwave_proxy::global_zwave_proxy != nullptr) {
     zwave_proxy::global_zwave_proxy->api_connection_authenticated(this);
@@ -1786,6 +1789,27 @@ void APIConnection::complete_authentication_() {
 #endif
 }
 
+#ifdef USE_API_NOISE
+void APIConnection::send_resume_ticket_() {
+#ifdef USE_API_PLAINTEXT
+  // Only encrypted transports get a ticket: on dual-mode builds a plaintext
+  // connection has no frame footer
+  if (this->helper_->frame_footer_size() == 0) {
+    return;
+  }
+#endif
+  noise::ResumeTicket ticket;
+  if (!this->parent_->get_noise_ctx().resume_cache().issue(ticket)) {
+    return;
+  }
+  NoiseResumeTicket msg;
+  msg.set_ticket(reinterpret_cast<const uint8_t *>(&ticket), sizeof(ticket));
+  // A dropped ticket is harmless: the client does a full handshake next time
+  static_cast<void>(this->send_message(msg));
+  noise_clean(&ticket, sizeof(ticket));
+}
+#endif
+
 bool APIConnection::send_hello_response_(const HelloRequest &msg) {
   // Copy client name with truncation if needed (set_client_name handles truncation)
   this->helper_->set_client_name(msg.client_info.c_str(), msg.client_info.size());

esphome/components/api/api_connection.h

@@ -381,6 +381,11 @@ class APIConnection final : public APIServerConnectionBase {
   // Helper function to handle authentication completion
   void complete_authentication_();
 
+#ifdef USE_API_NOISE
+  // Issue a fresh single-use session resume ticket over the encrypted channel
+  void send_resume_ticket_();
+#endif
+
   // Pattern B helpers: send response and return success/failure
   bool send_hello_response_(const HelloRequest &msg);
   bool send_disconnect_response_();

esphome/components/api/api_frame_helper_noise.cpp

@@ -271,8 +271,8 @@ APIError APINoiseFrameHelper::state_action_client_hello_() {
   if (aerr != APIError::OK) {
     return handle_handshake_frame_error_(aerr);
   }
-  // ignore contents, may be used in future for flags
-  // Resize for: existing prologue + 2 size bytes + frame data
+  // Contents are extension flags (today: the resume offer); mixed into the
+  // prologue either way. Resize for: existing prologue + 2 size bytes + frame data
   size_t old_size = this->prologue_.size();
   size_t rx_size = this->rx_buf_.size();
   if (!this->prologue_.resize(old_size + 2 + rx_size)) [[unlikely]] {
@@ -289,6 +289,8 @@ APIError APINoiseFrameHelper::state_action_client_hello_() {
   return APIError::OK;
 }
 APIError APINoiseFrameHelper::state_action_server_hello_() {
+  // A verified resume offer (still in rx_buf_ from the client hello step)
+  // replaces the whole handshake; any failure falls back to the full one.
   // send server hello
   const auto &name = App.get_name();
   char mac[MAC_ADDRESS_BUFFER_SIZE];
@@ -302,7 +304,9 @@ APIError APINoiseFrameHelper::state_action_server_hello_() {
 
   // 1 (proto) + name (max ESPHOME_DEVICE_NAME_MAX_LEN) + 1 (name null)
   // + mac (MAC_ADDRESS_BUFFER_SIZE - 1) + 1 (mac null)
-  constexpr size_t max_msg_size = 1 + ESPHOME_DEVICE_NAME_MAX_LEN + 1 + MAC_ADDRESS_BUFFER_SIZE;
+  // + optional resume accept extension
+  constexpr size_t max_msg_size =
+      1 + ESPHOME_DEVICE_NAME_MAX_LEN + 1 + MAC_ADDRESS_BUFFER_SIZE + noise::RESUME_ACCEPT_SIZE;
   uint8_t msg[max_msg_size];
 
   // chosen proto
@@ -313,16 +317,32 @@ APIError APINoiseFrameHelper::state_action_server_hello_() {
   // node mac, terminated by null byte
   std::memcpy(msg + mac_offset, mac, MAC_ADDRESS_BUFFER_SIZE);
 
+  // The accept extension, if any, is written straight after the mac
+  size_t ext_len = this->ctx_.resume_cache().try_accept(
+      this->rx_buf_.data(), this->rx_buf_.size(), this->prologue_.data(), this->prologue_.size(), msg + total_size,
+      sizeof(msg) - total_size, send_cipher_, recv_cipher_);
+  bool resume = ext_len != 0;
+  total_size += ext_len;
+
   APIError aerr = write_frame_(msg, total_size);
   if (aerr != APIError::OK)
     return aerr;
 
-  // start handshake
-  aerr = init_handshake_();
-  if (aerr != APIError::OK)
-    return aerr;
-
-  state_ = State::HANDSHAKE;
+  if (resume) {
+    // A resuming client waits for this hello instead of pipelining
+    // handshake message 1, so the transport is ready now
+    this->frame_footer_size_ = noise_cipherstate_get_mac_length(this->send_cipher_);
+    HELPER_LOG("Session resumed!");
+    state_ = State::DATA;
+  } else {
+    aerr = init_handshake_();
+    if (aerr != APIError::OK)
+      return aerr;
+    state_ = State::HANDSHAKE;
+  }
+  // init_handshake_ copied the prologue into the handshake state; the resume
+  // path is done with it too
+  this->prologue_.release();
   return APIError::OK;
 }
 APIError APINoiseFrameHelper::state_action_handshake_() {
@@ -552,8 +572,6 @@ APIError APINoiseFrameHelper::init_handshake_() {
   APIError aerr = handle_noise_error_(err, LOG_STR("noise_handshake_init"), APIError::HANDSHAKESTATE_SETUP_FAILED);
   if (aerr != APIError::OK)
     return aerr;
-  // init copies the prologue into the handshakestate, so we can get rid of it now
-  prologue_.release();
   return APIError::OK;
 }
 

esphome/components/api/api_pb2.cpp

@@ -1061,6 +1061,16 @@ uint32_t NoiseEncryptionSetKeyResponse::calculate_size() const {
   size += ProtoSize::calc_bool(1, this->success);
   return size;
 }
+uint8_t *NoiseResumeTicket::encode(ProtoWriteBuffer &buffer PROTO_ENCODE_DEBUG_PARAM) const {
+  uint8_t *__restrict__ pos = buffer.get_pos();
+  ProtoEncode::encode_bytes(pos PROTO_ENCODE_DEBUG_ARG, 1, this->ticket_ptr_, this->ticket_len_);
+  return pos;
+}
+uint32_t NoiseResumeTicket::calculate_size() const {
+  uint32_t size = 0;
+  size += ProtoSize::calc_length(1, this->ticket_len_);
+  return size;
+}
 #endif
 #ifdef USE_API_HOMEASSISTANT_SERVICES
 uint8_t *HomeassistantServiceMap::encode(ProtoWriteBuffer &buffer PROTO_ENCODE_DEBUG_PARAM) const {

esphome/components/api/api_pb2.h

@@ -1147,6 +1147,27 @@ class NoiseEncryptionSetKeyResponse final : public ProtoMessage {
 
  protected:
 };
+class NoiseResumeTicket final : public ProtoMessage {
+ public:
+  static constexpr uint16_t MESSAGE_TYPE = 152;
+  static constexpr uint8_t ESTIMATED_SIZE = 19;
+#ifdef HAS_PROTO_MESSAGE_DUMP
+  const LogString *message_name() const override { return LOG_STR("noise_resume_ticket"); }
+#endif
+  const uint8_t *ticket_ptr_{nullptr};
+  size_t ticket_len_{0};
+  void set_ticket(const uint8_t *data, size_t len) {
+    this->ticket_ptr_ = data;
+    this->ticket_len_ = len;
+  }
+  uint8_t *encode(ProtoWriteBuffer &buffer PROTO_ENCODE_DEBUG_PARAM) const;
+  uint32_t calculate_size() const;
+#ifdef HAS_PROTO_MESSAGE_DUMP
+  const char *dump_to(DumpBuffer &out) const override;
+#endif
+
+ protected:
+};
 #endif
 #ifdef USE_API_HOMEASSISTANT_SERVICES
 class HomeassistantServiceMap final : public ProtoMessage {

esphome/components/api/api_pb2_dump.cpp

@@ -1393,6 +1393,10 @@ const char *NoiseEncryptionSetKeyResponse::dump_to(DumpBuffer &out) const {
   dump_field(out, ESPHOME_PSTR("success"), this->success);
   return out.c_str();
 }
+const char *NoiseResumeTicket::dump_to(DumpBuffer &out) const {
+  out.append_p(ESPHOME_PSTR("NoiseResumeTicket {}"));
+  return out.c_str();
+}
 #endif
 #ifdef USE_API_HOMEASSISTANT_SERVICES
 const char *HomeassistantServiceMap::dump_to(DumpBuffer &out) const {

esphome/components/noise/noise.h

@@ -6,6 +6,8 @@
 #include <cstdint>
 #include "esphome/core/log.h"
 
+#include "noise_resume.h"
+
 namespace esphome::noise {
 
 using psk_t = std::array<uint8_t, 32>;
@@ -26,12 +28,16 @@ class NoiseContext {
   void set_psk(psk_t psk) {
     this->psk_ = psk;
     this->has_psk_ = !is_all_zeros(psk);
+    // Resume tickets were minted under the old key; forget them
+    this->resume_cache_.clear();
   }
   const psk_t &get_psk() const { return this->psk_; }
   bool has_psk() const { return this->has_psk_; }
+  ResumeTicketCache &resume_cache() { return this->resume_cache_; }
 
  protected:
   psk_t psk_{};
+  ResumeTicketCache resume_cache_;
   bool has_psk_{false};
 };
 

esphome/components/noise/noise_resume.cpp

@@ -0,0 +1,127 @@
+#include "noise_resume.h"
+#ifdef USE_NOISE
+#include <cstring>
+
+#include <noise/protocol.h>
+
+#include "esphome/core/hal.h"
+#include "esphome/core/helpers.h"
+
+namespace esphome::noise {
+
+const char RESUME_LABEL_OFFER[6] PROGMEM = "offer";
+const char RESUME_LABEL_CONFIRM[8] PROGMEM = "confirm";
+const char RESUME_LABEL_KEYS[5] PROGMEM = "keys";
+bool resume_kdf(const uint8_t *secret, const char *label, size_t label_len, const uint8_t *a, size_t a_len,
+                const uint8_t *b, size_t b_len, const uint8_t *hash_in, size_t hash_in_len, uint8_t *out1,
+                size_t out1_len, uint8_t *out2) {
+  uint8_t data[RESUME_KDF_MAX_DATA];
+  uint8_t scratch[32];
+  size_t len = label_len + a_len + b_len;
+  progmem_memcpy(data, label, label_len);
+  std::memcpy(data + label_len, a, a_len);
+  std::memcpy(data + label_len + a_len, b, b_len);
+  NoiseHashState *hash = nullptr;
+  if (noise_hashstate_new_by_id(&hash, NOISE_HASH_SHA256) != NOISE_ERROR_NONE) {
+    return false;
+  }
+  int err = NOISE_ERROR_NONE;
+  if (hash_in != nullptr) {
+    err = noise_hashstate_hash_one(hash, hash_in, hash_in_len, data + len, 32);
+    len += 32;
+  }
+  if (err == NOISE_ERROR_NONE) {
+    err = noise_hashstate_hkdf(hash, secret, RESUME_SECRET_SIZE, data, len, out1, out1_len,
+                               out2 != nullptr ? out2 : scratch, 32);
+  }
+  noise_hashstate_free(hash);
+  noise_clean(data, sizeof(data));
+  noise_clean(scratch, sizeof(scratch));
+  return err == NOISE_ERROR_NONE;
+}
+
+bool ResumeTicketCache::issue(ResumeTicket &out) {
+  if (!random_bytes(reinterpret_cast<uint8_t *>(&out), sizeof(out))) {
+    return false;
+  }
+  uint8_t slot = this->next_;
+  this->next_ = static_cast<uint8_t>((slot + 1) % SLOTS);
+  this->slots_[slot] = out;
+  this->used_mask_ |= static_cast<uint8_t>(1u << slot);
+  return true;
+}
+
+size_t ResumeTicketCache::try_accept(const uint8_t *offer, size_t offer_len, const uint8_t *prologue,
+                                     size_t prologue_len, uint8_t *out_ext, size_t out_capacity,
+                                     NoiseCipherState *&send_cipher, NoiseCipherState *&recv_cipher) {
+  if (offer_len != RESUME_OFFER_SIZE || offer[0] != RESUME_OFFER_VERSION || out_capacity < RESUME_ACCEPT_SIZE) {
+    return 0;
+  }
+  const uint8_t *session_id = offer + RESUME_OFFER_SESSION_ID_OFFSET;
+  const uint8_t *client_nonce = offer + RESUME_OFFER_NONCE_OFFSET;
+  ResumeTicket *ticket = nullptr;
+  for (uint8_t i = 0; i < SLOTS; i++) {
+    if ((this->used_mask_ & (1u << i)) &&
+        std::memcmp(this->slots_[i].session_id, session_id, RESUME_SESSION_ID_SIZE) == 0) {
+      ticket = &this->slots_[i];
+      this->used_mask_ &= static_cast<uint8_t>(~(1u << i));
+      break;
+    }
+  }
+  if (ticket == nullptr) {
+    return 0;
+  }
+  uint8_t expected[RESUME_MAC_SIZE];
+  bool ok = resume_compute_offer_mac(ticket->secret, session_id, client_nonce, expected) &&
+            noise_is_equal(expected, offer + RESUME_OFFER_MAC_OFFSET, RESUME_MAC_SIZE);
+  noise_clean(expected, sizeof(expected));
+  if (!ok) {
+    // Bad MAC: keep the ticket so a forger cannot burn it
+    this->used_mask_ |= static_cast<uint8_t>(1u << static_cast<uint8_t>(ticket - this->slots_));
+    return 0;
+  }
+  // The ticket is spent from here; any later failure falls back to the full
+  // handshake and the client gets a fresh one.
+  uint8_t *server_nonce = out_ext + 1;
+  uint8_t k_c2d[32];
+  uint8_t k_d2c[32];
+  out_ext[0] = RESUME_ACCEPT_VERSION;
+  ok = random_bytes(server_nonce, RESUME_NONCE_SIZE) &&
+       resume_compute_confirm_mac(ticket->secret, client_nonce, server_nonce, out_ext + 1 + RESUME_NONCE_SIZE) &&
+       resume_derive_keys(ticket->secret, client_nonce, server_nonce, prologue, prologue_len, k_c2d, k_d2c);
+  noise_clean(ticket, sizeof(*ticket));
+  if (ok) {
+    recv_cipher = resume_make_cipher(k_c2d);
+    send_cipher = resume_make_cipher(k_d2c);
+    ok = recv_cipher != nullptr && send_cipher != nullptr;
+    if (!ok) {
+      noise_cipherstate_free(recv_cipher);
+      noise_cipherstate_free(send_cipher);
+      recv_cipher = nullptr;
+      send_cipher = nullptr;
+    }
+  }
+  noise_clean(k_c2d, sizeof(k_c2d));
+  noise_clean(k_d2c, sizeof(k_d2c));
+  return ok ? RESUME_ACCEPT_SIZE : 0;
+}
+
+void ResumeTicketCache::clear() {
+  noise_clean(this->slots_, sizeof(this->slots_));
+  this->used_mask_ = 0;
+}
+
+NoiseCipherState *resume_make_cipher(const uint8_t *key) {
+  NoiseCipherState *cipher = nullptr;
+  if (noise_cipherstate_new_by_id(&cipher, NOISE_CIPHER_CHACHAPOLY) != NOISE_ERROR_NONE) {
+    return nullptr;
+  }
+  if (noise_cipherstate_init_key(cipher, key, 32) != NOISE_ERROR_NONE) {
+    noise_cipherstate_free(cipher);
+    return nullptr;
+  }
+  return cipher;
+}
+
+}  // namespace esphome::noise
+#endif  // USE_NOISE

esphome/components/noise/noise_resume.h

@@ -0,0 +1,132 @@
+#pragma once
+#include "esphome/core/defines.h"
+#ifdef USE_NOISE
+#include <cstddef>
+#include <cstdint>
+
+// Forward declaration matching <noise/protocol/cipherstate.h>; keeps noise-c
+// headers out of everything that includes noise.h.
+extern "C" {
+typedef struct NoiseCipherState_s NoiseCipherState;  // NOLINT(modernize-use-using)
+}
+
+namespace esphome::noise {
+
+/** Session resume for the noise transports.
+ *
+ * After a full handshake the responder issues a single-use ticket over the
+ * encrypted channel. A client presents it in its next ClientHello and both
+ * sides derive the transport keys with HKDF-SHA256 alone, skipping the two
+ * curve25519 operations. Old peers ignore the extension bytes on both
+ * sides, so every mismatch degrades to a normal full handshake.
+ *
+ * HKDF is the Noise construction (noise_hashstate_hkdf). Derivations:
+ *   offer_mac   = HKDF(secret, "offer"   || session_id || client_nonce).out1[:16]
+ *   confirm_mac = HKDF(secret, "confirm" || client_nonce || server_nonce).out1[:16]
+ *   k_c2d, k_d2c = HKDF(secret, "keys" || client_nonce || server_nonce || SHA256(prologue))
+ *
+ * An offering client sends handshake message 1 only after a decline.
+ * Resumed sessions have no ephemeral DH; the ticket is wiped on use.
+ */
+
+static constexpr uint8_t RESUME_OFFER_VERSION = 0x01;
+static constexpr uint8_t RESUME_ACCEPT_VERSION = 0x01;
+static constexpr size_t RESUME_SESSION_ID_SIZE = 8;
+static constexpr size_t RESUME_NONCE_SIZE = 16;
+static constexpr size_t RESUME_MAC_SIZE = 16;
+static constexpr size_t RESUME_SECRET_SIZE = 32;
+
+// ClientHello body: version | session_id | client_nonce | offer_mac
+static constexpr size_t RESUME_OFFER_SIZE = 1 + RESUME_SESSION_ID_SIZE + RESUME_NONCE_SIZE + RESUME_MAC_SIZE;  // 41
+static constexpr size_t RESUME_OFFER_SESSION_ID_OFFSET = 1;
+static constexpr size_t RESUME_OFFER_NONCE_OFFSET = RESUME_OFFER_SESSION_ID_OFFSET + RESUME_SESSION_ID_SIZE;
+static constexpr size_t RESUME_OFFER_MAC_OFFSET = RESUME_OFFER_NONCE_OFFSET + RESUME_NONCE_SIZE;
+
+// ServerHello trailing extension: version | server_nonce | confirm_mac
+static constexpr size_t RESUME_ACCEPT_SIZE = 1 + RESUME_NONCE_SIZE + RESUME_MAC_SIZE;  // 33
+
+struct ResumeTicket {
+  uint8_t session_id[RESUME_SESSION_ID_SIZE];
+  uint8_t secret[RESUME_SECRET_SIZE];
+};
+// Sent on the wire as one blob: session_id || secret
+static_assert(sizeof(ResumeTicket) == RESUME_SESSION_ID_SIZE + RESUME_SECRET_SIZE, "ticket must be packed");
+
+/// Fixed-slot RAM cache of single-use resume tickets. Lost on reboot by
+/// design: clients fall back to a full handshake.
+class ResumeTicketCache {
+ public:
+  /// Generate a fresh ticket into out and store it, evicting the oldest
+  /// slot. Returns false (and stores nothing) if the RNG fails.
+  bool issue(ResumeTicket &out);
+  /// Accept a resume offer: verify and consume the ticket (single use; a
+  /// forged MAC never burns one), build both transport ciphers, and write
+  /// the ServerHello accept extension into out_ext. Returns the extension
+  /// length, or 0 (nothing allocated) on any miss, failure, or when
+  /// out_capacity is too small. Secrets are wiped internally.
+  size_t try_accept(const uint8_t *offer, size_t offer_len, const uint8_t *prologue, size_t prologue_len,
+                    uint8_t *out_ext, size_t out_capacity, NoiseCipherState *&send_cipher,
+                    NoiseCipherState *&recv_cipher);
+  /// Forget every ticket (PSK change).
+  void clear();
+
+  // Round robin; more clients than slots thrash and fall back to full handshakes
+  static constexpr uint8_t SLOTS = 2;
+  static_assert(SLOTS <= 8, "used_mask_ is uint8_t");
+
+ protected:
+  ResumeTicket slots_[SLOTS];
+  uint8_t used_mask_{0};
+  uint8_t next_{0};
+};
+
+/// HKDF labels, PROGMEM on ESP8266.
+extern const char RESUME_LABEL_OFFER[6];
+extern const char RESUME_LABEL_CONFIRM[8];
+extern const char RESUME_LABEL_KEYS[5];
+
+// Largest KDF input: "keys" || client_nonce || server_nonce || SHA256(prologue)
+static constexpr size_t RESUME_KDF_MAX_DATA =
+    sizeof(RESUME_LABEL_KEYS) - 1 + RESUME_NONCE_SIZE + RESUME_NONCE_SIZE + 32;
+
+/// Noise-construction HKDF-SHA256 keyed with the ticket secret over
+/// label || a || b [|| SHA256(hash_in)], at most RESUME_KDF_MAX_DATA. out2 == nullptr means MAC only.
+bool resume_kdf(const uint8_t *secret, const char *label, size_t label_len, const uint8_t *a, size_t a_len,
+                const uint8_t *b, size_t b_len, const uint8_t *hash_in, size_t hash_in_len, uint8_t *out1,
+                size_t out1_len, uint8_t *out2);
+
+/// offer_mac for the ClientHello resume offer (what a client computes and
+/// try_accept checks).
+inline bool resume_compute_offer_mac(const uint8_t *secret, const uint8_t *session_id, const uint8_t *client_nonce,
+                                     uint8_t *out_mac) {
+  static_assert(sizeof(RESUME_LABEL_OFFER) - 1 + RESUME_SESSION_ID_SIZE + RESUME_NONCE_SIZE <= RESUME_KDF_MAX_DATA,
+                "KDF buffer");
+  return resume_kdf(secret, RESUME_LABEL_OFFER, sizeof(RESUME_LABEL_OFFER) - 1, session_id, RESUME_SESSION_ID_SIZE,
+                    client_nonce, RESUME_NONCE_SIZE, nullptr, 0, out_mac, RESUME_MAC_SIZE, nullptr);
+}
+
+/// confirm_mac for the ServerHello extension.
+inline bool resume_compute_confirm_mac(const uint8_t *secret, const uint8_t *client_nonce, const uint8_t *server_nonce,
+                                       uint8_t *out_mac) {
+  static_assert(sizeof(RESUME_LABEL_CONFIRM) - 1 + RESUME_NONCE_SIZE + RESUME_NONCE_SIZE <= RESUME_KDF_MAX_DATA,
+                "KDF buffer");
+  return resume_kdf(secret, RESUME_LABEL_CONFIRM, sizeof(RESUME_LABEL_CONFIRM) - 1, client_nonce, RESUME_NONCE_SIZE,
+                    server_nonce, RESUME_NONCE_SIZE, nullptr, 0, out_mac, RESUME_MAC_SIZE, nullptr);
+}
+
+/// Derive the transport keys. k_c2d encrypts client-to-device traffic,
+/// k_d2c device-to-client.
+inline bool resume_derive_keys(const uint8_t *secret, const uint8_t *client_nonce, const uint8_t *server_nonce,
+                               const uint8_t *prologue, size_t prologue_len, uint8_t *k_c2d, uint8_t *k_d2c) {
+  static_assert(sizeof(RESUME_LABEL_KEYS) - 1 + RESUME_NONCE_SIZE + RESUME_NONCE_SIZE + 32 <= RESUME_KDF_MAX_DATA,
+                "KDF buffer");
+  return resume_kdf(secret, RESUME_LABEL_KEYS, sizeof(RESUME_LABEL_KEYS) - 1, client_nonce, RESUME_NONCE_SIZE,
+                    server_nonce, RESUME_NONCE_SIZE, prologue, prologue_len, k_c2d, 32, k_d2c);
+}
+
+/// Build a ChaChaPoly cipher state keyed with key (32 bytes); nullptr on
+/// failure. Nonce counter starts at 0, exactly like a post-split cipher.
+NoiseCipherState *resume_make_cipher(const uint8_t *key);
+
+}  // namespace esphome::noise
+#endif  // USE_NOISE

script/api_protobuf/api_protobuf.py

@@ -2531,6 +2531,11 @@ def calculate_message_max_size(desc: descriptor.DescriptorProto) -> int | None:
     return total_size
 
 
+# Contents must never reach the log: dump_to prints only the name
+SENSITIVE_MESSAGES = {"NoiseResumeTicket"}
+SENSITIVE_MESSAGES_SEEN: set[str] = set()
+
+
 def build_message_type(
     desc: descriptor.DescriptorProto,
     base_class_fields: dict[str, list[descriptor.FieldDescriptorProto]],
@@ -2808,6 +2813,10 @@ def build_message_type(
         public_content.append(prot)
     # If no fields to calculate size for or message doesn't need encoding, the default implementation in ProtoMessage will be used
 
+    if desc.name in SENSITIVE_MESSAGES:
+        dump = []
+        SENSITIVE_MESSAGES_SEEN.add(desc.name)
+
     # dump_to method declaration in header
     prot = "#ifdef HAS_PROTO_MESSAGE_DUMP\n"
     prot += "const char *dump_to(DumpBuffer &out) const override;\n"
@@ -3715,6 +3724,11 @@ static const char *const TAG = "api.service";
     except ImportError:
         pass
 
+    # A renamed message must fail the build, not silently start dumping secrets
+    missing = SENSITIVE_MESSAGES - SENSITIVE_MESSAGES_SEEN
+    if missing:
+        raise RuntimeError(f"SENSITIVE_MESSAGES not found in api.proto: {missing}")
+
 
 if __name__ == "__main__":
     sys.exit(main())

tests/components/noise/test_noise_resume.cpp

@@ -0,0 +1,224 @@
+#include <gtest/gtest.h>
+
+#include <cstring>
+
+#include <noise/protocol.h>
+
+#include "esphome/components/noise/noise.h"
+#include "esphome/components/noise/noise_resume.h"
+
+namespace esphome::noise::testing {
+
+// Known-answer vectors shared with the client implementation
+// (aioesphomeapi tests/test_noise_resume.py); the two must stay identical
+// byte for byte or resumed sessions cannot interoperate.
+static const uint8_t KAT_SECRET[RESUME_SECRET_SIZE] = {1,  2,  3,  4,  5,  6,  7,  8,  9,  10, 11, 12, 13, 14, 15, 16,
+                                                       17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32};
+static const uint8_t KAT_SESSION_ID[RESUME_SESSION_ID_SIZE] = {0xa0, 0xa1, 0xa2, 0xa3, 0xa4, 0xa5, 0xa6, 0xa7};
+static const uint8_t KAT_CLIENT_NONCE[RESUME_NONCE_SIZE] = {0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
+                                                            0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f};
+static const uint8_t KAT_SERVER_NONCE[RESUME_NONCE_SIZE] = {0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37,
+                                                            0x38, 0x39, 0x3a, 0x3b, 0x3c, 0x3d, 0x3e, 0x3f};
+static const uint8_t KAT_OFFER_MAC[RESUME_MAC_SIZE] = {0xa8, 0x08, 0xea, 0xdb, 0xec, 0x81, 0xa7, 0xcb,
+                                                       0xf4, 0xca, 0xaa, 0xb8, 0x0d, 0x7f, 0x9d, 0x01};
+static const uint8_t KAT_CONFIRM_MAC[RESUME_MAC_SIZE] = {0x09, 0xa3, 0x70, 0x3e, 0xc8, 0x34, 0x77, 0xe9,
+                                                         0x45, 0xe7, 0xf1, 0x61, 0x9d, 0x4f, 0x6a, 0x76};
+static const uint8_t KAT_K_C2D[32] = {0xd6, 0x01, 0xe3, 0xc1, 0x16, 0xa1, 0x64, 0x66, 0xdb, 0xc5, 0x9e,
+                                      0xdd, 0x60, 0x2a, 0x64, 0x1e, 0xbe, 0xf5, 0x11, 0x95, 0x98, 0xd2,
+                                      0xf2, 0x47, 0x1b, 0xc6, 0x8c, 0x51, 0x8f, 0xbe, 0xb7, 0x23};
+static const uint8_t KAT_K_D2C[32] = {0x7f, 0x8d, 0x57, 0x7e, 0x9f, 0xb4, 0xbb, 0xde, 0x86, 0xcd, 0xa9,
+                                      0xf4, 0x9b, 0x42, 0xe7, 0x24, 0xc8, 0x49, 0xce, 0x89, 0xd8, 0x96,
+                                      0x3f, 0x3c, 0x4b, 0x3f, 0x8f, 0x80, 0xc2, 0x56, 0xab, 0x65};
+
+/// The one place in this file that spells the offer wire layout
+static void build_offer(uint8_t *offer, const uint8_t *session_id, const uint8_t *client_nonce, const uint8_t *mac) {
+  offer[0] = RESUME_OFFER_VERSION;
+  std::memcpy(offer + RESUME_OFFER_SESSION_ID_OFFSET, session_id, RESUME_SESSION_ID_SIZE);
+  std::memcpy(offer + RESUME_OFFER_NONCE_OFFSET, client_nonce, RESUME_NONCE_SIZE);
+  std::memcpy(offer + RESUME_OFFER_MAC_OFFSET, mac, RESUME_MAC_SIZE);
+}
+
+/// "NoiseAPIInit" || be16(len) || offer, exactly as the api frame helper mixes it
+static constexpr size_t KAT_PROLOGUE_SIZE = 12 + 2 + RESUME_OFFER_SIZE;
+static void build_prologue(uint8_t *out, const uint8_t *offer) {
+  std::memcpy(out, "NoiseAPIInit", 12);  // NOLINT(bugprone-not-null-terminated-result)
+  out[12] = 0x00;
+  out[13] = RESUME_OFFER_SIZE;
+  std::memcpy(out + 14, offer, RESUME_OFFER_SIZE);
+}
+
+static void build_offer_for_ticket(uint8_t *offer, const ResumeTicket &ticket, const uint8_t *client_nonce) {
+  uint8_t mac[RESUME_MAC_SIZE];
+  ASSERT_TRUE(resume_compute_offer_mac(ticket.secret, ticket.session_id, client_nonce, mac));
+  build_offer(offer, ticket.session_id, client_nonce, mac);
+}
+
+/// Test access to the protected slots so a test can plant the KAT ticket
+struct TestCache : ResumeTicketCache {
+  void plant(const uint8_t *session_id, const uint8_t *secret) {
+    std::memcpy(this->slots_[0].session_id, session_id, RESUME_SESSION_ID_SIZE);
+    std::memcpy(this->slots_[0].secret, secret, RESUME_SECRET_SIZE);
+    this->used_mask_ |= 1u;
+  }
+};
+
+TEST(NoiseResumeKat, ConfirmMacMatchesClientImplementation) {
+  uint8_t mac[RESUME_MAC_SIZE];
+  ASSERT_TRUE(resume_compute_confirm_mac(KAT_SECRET, KAT_CLIENT_NONCE, KAT_SERVER_NONCE, mac));
+  EXPECT_EQ(std::memcmp(mac, KAT_CONFIRM_MAC, RESUME_MAC_SIZE), 0);
+}
+
+TEST(NoiseResumeKat, OfferMacMatchesClientImplementation) {
+  uint8_t mac[RESUME_MAC_SIZE];
+  ASSERT_TRUE(resume_compute_offer_mac(KAT_SECRET, KAT_SESSION_ID, KAT_CLIENT_NONCE, mac));
+  EXPECT_EQ(std::memcmp(mac, KAT_OFFER_MAC, RESUME_MAC_SIZE), 0);
+}
+
+TEST(NoiseResumeKat, KeyDerivationMatchesClientImplementation) {
+  // Prologue used by the shared vectors: "NoiseAPIInit" + be16(41) + a
+  // 41-byte offer whose MAC field is 16 bytes of 0xEE
+  uint8_t mac_filler[RESUME_MAC_SIZE];
+  std::memset(mac_filler, 0xEE, sizeof(mac_filler));
+  uint8_t offer[RESUME_OFFER_SIZE];
+  build_offer(offer, KAT_SESSION_ID, KAT_CLIENT_NONCE, mac_filler);
+  uint8_t prologue[KAT_PROLOGUE_SIZE];
+  build_prologue(prologue, offer);
+
+  uint8_t k_c2d[32], k_d2c[32];
+  ASSERT_TRUE(
+      resume_derive_keys(KAT_SECRET, KAT_CLIENT_NONCE, KAT_SERVER_NONCE, prologue, sizeof(prologue), k_c2d, k_d2c));
+  EXPECT_EQ(std::memcmp(k_c2d, KAT_K_C2D, 32), 0);
+  EXPECT_EQ(std::memcmp(k_d2c, KAT_K_D2C, 32), 0);
+}
+
+TEST(NoiseResumeCache, TryAcceptConsumesTicketOnceAndProvesPossession) {
+  TestCache cache;
+  cache.plant(KAT_SESSION_ID, KAT_SECRET);
+
+  uint8_t offer[RESUME_OFFER_SIZE];
+  build_offer(offer, KAT_SESSION_ID, KAT_CLIENT_NONCE, KAT_OFFER_MAC);
+  uint8_t prologue[KAT_PROLOGUE_SIZE];
+  build_prologue(prologue, offer);
+
+  uint8_t ext[RESUME_ACCEPT_SIZE];
+  NoiseCipherState *send = nullptr, *recv = nullptr;
+  ASSERT_EQ(cache.try_accept(offer, sizeof(offer), prologue, sizeof(prologue), ext, sizeof(ext), send, recv),
+            RESUME_ACCEPT_SIZE);
+  ASSERT_NE(send, nullptr);
+  ASSERT_NE(recv, nullptr);
+
+  // The extension proves possession: verify like the client does
+  EXPECT_EQ(ext[0], RESUME_ACCEPT_VERSION);
+  const uint8_t *server_nonce = ext + 1;
+  uint8_t expected_confirm[RESUME_MAC_SIZE];
+  ASSERT_TRUE(resume_compute_confirm_mac(KAT_SECRET, KAT_CLIENT_NONCE, server_nonce, expected_confirm));
+  EXPECT_EQ(std::memcmp(ext + 1 + RESUME_NONCE_SIZE, expected_confirm, RESUME_MAC_SIZE), 0);
+
+  // The ciphers must interoperate with the documented key derivation
+  uint8_t k_c2d[32], k_d2c[32];
+  ASSERT_TRUE(resume_derive_keys(KAT_SECRET, KAT_CLIENT_NONCE, server_nonce, prologue, sizeof(prologue), k_c2d, k_d2c));
+  NoiseCipherState *client_send = resume_make_cipher(k_c2d);
+  ASSERT_NE(client_send, nullptr);
+  uint8_t buf[64] = "resumed";
+  NoiseBuffer nb;
+  noise_buffer_init(nb);
+  noise_buffer_set_inout(nb, buf, 7, sizeof(buf));
+  ASSERT_EQ(noise_cipherstate_encrypt(client_send, &nb), NOISE_ERROR_NONE);
+  ASSERT_EQ(noise_cipherstate_decrypt(recv, &nb), NOISE_ERROR_NONE);
+  EXPECT_EQ(std::memcmp(buf, "resumed", 7), 0);
+  noise_cipherstate_free(client_send);
+  noise_cipherstate_free(send);
+  noise_cipherstate_free(recv);
+
+  // Single use: the same offer must miss the second time
+  NoiseCipherState *send2 = nullptr, *recv2 = nullptr;
+  EXPECT_EQ(cache.try_accept(offer, sizeof(offer), prologue, sizeof(prologue), ext, sizeof(ext), send2, recv2), 0u);
+  EXPECT_EQ(send2, nullptr);
+  EXPECT_EQ(recv2, nullptr);
+}
+
+TEST(NoiseResumeCache, BadMacOrMalformedOfferLeavesTicketIntact) {
+  TestCache cache;
+  cache.plant(KAT_SESSION_ID, KAT_SECRET);
+
+  uint8_t offer[RESUME_OFFER_SIZE];
+  uint8_t bad_mac[RESUME_MAC_SIZE];
+  std::memcpy(bad_mac, KAT_OFFER_MAC, RESUME_MAC_SIZE);
+  bad_mac[0] ^= 0x01;
+  build_offer(offer, KAT_SESSION_ID, KAT_CLIENT_NONCE, bad_mac);
+
+  uint8_t prologue[1] = {0};
+  uint8_t ext[RESUME_ACCEPT_SIZE];
+  NoiseCipherState *send = nullptr, *recv = nullptr;
+  // A forged offer must not burn the ticket
+  EXPECT_EQ(cache.try_accept(offer, sizeof(offer), prologue, sizeof(prologue), ext, sizeof(ext), send, recv), 0u);
+  // Wrong size or version must be recognized as "no offer"
+  build_offer(offer, KAT_SESSION_ID, KAT_CLIENT_NONCE, KAT_OFFER_MAC);
+  EXPECT_EQ(cache.try_accept(offer, sizeof(offer) - 1, prologue, sizeof(prologue), ext, sizeof(ext), send, recv), 0u);
+  offer[0] = 0x7f;
+  EXPECT_EQ(cache.try_accept(offer, sizeof(offer), prologue, sizeof(prologue), ext, sizeof(ext), send, recv), 0u);
+  offer[0] = RESUME_OFFER_VERSION;
+  // No room for the extension must also decline without burning it
+  EXPECT_EQ(cache.try_accept(offer, sizeof(offer), prologue, sizeof(prologue), ext, sizeof(ext) - 1, send, recv), 0u);
+  // The genuine offer still redeems
+  EXPECT_EQ(cache.try_accept(offer, sizeof(offer), prologue, sizeof(prologue), ext, sizeof(ext), send, recv),
+            RESUME_ACCEPT_SIZE);
+  noise_cipherstate_free(send);
+  noise_cipherstate_free(recv);
+}
+
+TEST(NoiseResumeCache, SetPskForgetsTickets) {
+  NoiseContext ctx;
+  ResumeTicket ticket;
+  ASSERT_TRUE(ctx.resume_cache().issue(ticket));
+
+  psk_t psk{};
+  psk[0] = 1;
+  ctx.set_psk(psk);
+
+  uint8_t offer[RESUME_OFFER_SIZE];
+  build_offer_for_ticket(offer, ticket, KAT_CLIENT_NONCE);
+  uint8_t prologue[KAT_PROLOGUE_SIZE];
+  build_prologue(prologue, offer);
+  uint8_t ext[RESUME_ACCEPT_SIZE];
+  NoiseCipherState *send = nullptr, *recv = nullptr;
+  EXPECT_EQ(
+      ctx.resume_cache().try_accept(offer, sizeof(offer), prologue, sizeof(prologue), ext, sizeof(ext), send, recv),
+      0u);
+  EXPECT_EQ(send, nullptr);
+  EXPECT_EQ(recv, nullptr);
+}
+
+TEST(NoiseResumeCache, IssueRotatesSlotsAndClearForgetsAll) {
+  ResumeTicketCache cache;
+  ResumeTicket tickets[ResumeTicketCache::SLOTS + 1];
+  for (auto &ticket : tickets) {
+    ASSERT_TRUE(cache.issue(ticket));
+  }
+  uint8_t offer[RESUME_OFFER_SIZE];
+  uint8_t prologue[1] = {0};
+  uint8_t ext[RESUME_ACCEPT_SIZE];
+
+  // The oldest ticket was evicted by the one-past-capacity issue
+  build_offer_for_ticket(offer, tickets[0], KAT_CLIENT_NONCE);
+  NoiseCipherState *send = nullptr, *recv = nullptr;
+  EXPECT_EQ(cache.try_accept(offer, sizeof(offer), prologue, sizeof(prologue), ext, sizeof(ext), send, recv), 0u);
+  // The rest remain redeemable
+  for (int i = 1; i <= ResumeTicketCache::SLOTS; i++) {
+    build_offer_for_ticket(offer, tickets[i], KAT_CLIENT_NONCE);
+    EXPECT_EQ(cache.try_accept(offer, sizeof(offer), prologue, sizeof(prologue), ext, sizeof(ext), send, recv),
+              RESUME_ACCEPT_SIZE);
+    noise_cipherstate_free(send);
+    noise_cipherstate_free(recv);
+    send = recv = nullptr;
+  }
+
+  // clear() forgets everything
+  ResumeTicket ticket;
+  ASSERT_TRUE(cache.issue(ticket));
+  cache.clear();
+  build_offer_for_ticket(offer, ticket, KAT_CLIENT_NONCE);
+  EXPECT_EQ(cache.try_accept(offer, sizeof(offer), prologue, sizeof(prologue), ext, sizeof(ext), send, recv), 0u);
+}
+
+}  // namespace esphome::noise::testing

tests/integration/fixtures/api_noise_resume.yaml

@@ -0,0 +1,9 @@
+esphome:
+  name: host-noise-resume
+host:
+api:
+  encryption:
+    key: N4Yle5YirwZhPiHHsdZLdOA73ndj/84veVaLhTvxCuU=
+# VERY_VERBOSE so the frame helper logs "Session resumed!"
+logger:
+  level: VERY_VERBOSE

tests/integration/integration_test_durations.json

@@ -1,142 +1,143 @@
 {
-  "tests/integration/test_action_concurrent_reentry.py": 45.23,
-  "tests/integration/test_addressable_light_transition.py": 74.47,
-  "tests/integration/test_alarm_control_panel_state_transitions.py": 74.1,
-  "tests/integration/test_api_action_metadata.py": 62.1,
-  "tests/integration/test_api_action_responses.py": 71.08,
-  "tests/integration/test_api_action_timeout.py": 21.64,
-  "tests/integration/test_api_conditional_memory.py": 13.72,
-  "tests/integration/test_api_custom_services.py": 24.16,
-  "tests/integration/test_api_get_time_response_timezone.py": 23.48,
-  "tests/integration/test_api_homeassistant.py": 37.87,
-  "tests/integration/test_api_homeassistant_action_no_subscriber.py": 14.38,
-  "tests/integration/test_api_list_entities_backpressure.py": 26.85,
-  "tests/integration/test_api_message_size_batching.py": 33.36,
-  "tests/integration/test_api_reboot_timeout.py": 13.63,
-  "tests/integration/test_api_string_lambda.py": 25.04,
-  "tests/integration/test_api_vv_logging.py": 16.6,
-  "tests/integration/test_api_zero_psk_provisioning.py": 43.14,
-  "tests/integration/test_areas_and_devices.py": 25.98,
-  "tests/integration/test_automation_wait_actions.py": 21.91,
-  "tests/integration/test_automations.py": 42.43,
-  "tests/integration/test_batch_delay_zero_rapid_transitions.py": 16.65,
-  "tests/integration/test_binary_sensor_autorepeat_filter.py": 28.67,
-  "tests/integration/test_binary_sensor_invalidate_state.py": 23.69,
-  "tests/integration/test_blocking_warning_log_time_not_charged_to_next_operation.py": 22.99,
-  "tests/integration/test_build_info.py": 24.96,
-  "tests/integration/test_camera_mock.py": 14.47,
-  "tests/integration/test_climate_control_action.py": 31.07,
-  "tests/integration/test_climate_custom_modes.py": 28.59,
-  "tests/integration/test_continuation_actions.py": 14.96,
-  "tests/integration/test_cover_control_action.py": 26.14,
-  "tests/integration/test_crc8_helper.py": 10.92,
-  "tests/integration/test_device_id_in_state.py": 64.97,
-  "tests/integration/test_duplicate_entities.py": 30.81,
-  "tests/integration/test_entity_icon.py": 32.85,
-  "tests/integration/test_fan_turn_on_action.py": 24.91,
-  "tests/integration/test_fnv1_hash_object_id.py": 12.54,
-  "tests/integration/test_fnv1a_hash.py": 21.8,
-  "tests/integration/test_gpio_expander_cache.py": 5.2,
-  "tests/integration/test_host_logger_thread_safety.py": 21.7,
-  "tests/integration/test_host_mode_basic.py": 13.62,
-  "tests/integration/test_host_mode_batch_delay.py": 14.56,
-  "tests/integration/test_host_mode_climate_basic_state.py": 30.95,
-  "tests/integration/test_host_mode_climate_control.py": 29.06,
-  "tests/integration/test_host_mode_empty_string_options.py": 27.22,
-  "tests/integration/test_host_mode_entity_fields.py": 30.95,
-  "tests/integration/test_host_mode_fan_preset.py": 14.44,
-  "tests/integration/test_host_mode_many_entities.py": 54.13,
-  "tests/integration/test_host_mode_many_entities_multiple_connections.py": 32.17,
-  "tests/integration/test_host_mode_noise_encryption.py": 42.77,
-  "tests/integration/test_host_mode_reconnect.py": 4.06,
-  "tests/integration/test_host_mode_sensor.py": 13.47,
-  "tests/integration/test_host_ota.py": 21.4,
-  "tests/integration/test_host_preferences.py": 25.43,
-  "tests/integration/test_host_preferences_suspend_resume.py": 19.2,
-  "tests/integration/test_improv_serial_uart.py": 31.52,
-  "tests/integration/test_large_message_batching.py": 15.64,
-  "tests/integration/test_legacy_area.py": 22.63,
-  "tests/integration/test_legacy_climate_compat.py": 26.13,
-  "tests/integration/test_legacy_fan_compat.py": 24.05,
-  "tests/integration/test_light_automations.py": 30.86,
-  "tests/integration/test_light_binary_effect_off_phase.py": 23.19,
-  "tests/integration/test_light_calls.py": 32.35,
-  "tests/integration/test_light_constant_brightness.py": 29.89,
-  "tests/integration/test_light_control_action.py": 29.06,
-  "tests/integration/test_light_dim_relative_action.py": 29.61,
-  "tests/integration/test_light_effect_zero_brightness.py": 18.68,
-  "tests/integration/test_light_initial_state.py": 24.49,
-  "tests/integration/test_light_toggle_action.py": 26.46,
-  "tests/integration/test_lock_automations.py": 23.28,
-  "tests/integration/test_logger_buffered_recursion_guard.py": 24.29,
-  "tests/integration/test_loop_disable_enable.py": 45.28,
-  "tests/integration/test_loop_interval_decoupling.py": 28.35,
-  "tests/integration/test_loop_interval_default_not_pulled_forward.py": 21.97,
-  "tests/integration/test_micros_to_millis.py": 20.79,
-  "tests/integration/test_multi_click_trigger.py": 26.2,
-  "tests/integration/test_multi_device_preferences.py": 16.87,
-  "tests/integration/test_noise_encryption_key_protection.py": 77.05,
-  "tests/integration/test_object_id_api_verification.py": 73.51,
-  "tests/integration/test_object_id_friendly_name_no_mac_suffix.py": 62.33,
-  "tests/integration/test_object_id_no_friendly_name.py": 43.47,
-  "tests/integration/test_online_image_auto_detects_image_bmp_mime.py": 32.21,
-  "tests/integration/test_online_image_auto_detects_redirected_image_bmp_mime.py": 56.86,
-  "tests/integration/test_online_image_bmp.py": 50.9,
-  "tests/integration/test_oversized_payloads.py": 53.2,
-  "tests/integration/test_preference_key_stability.py": 26.09,
-  "tests/integration/test_runtime_stats.py": 18.34,
-  "tests/integration/test_safe_mode_loop_runs.py": 10.07,
-  "tests/integration/test_scheduler_blocking_warning.py": 40.91,
-  "tests/integration/test_scheduler_bulk_cleanup.py": 23.14,
-  "tests/integration/test_scheduler_defer_cancel.py": 24.54,
-  "tests/integration/test_scheduler_defer_cancel_regular.py": 13.48,
-  "tests/integration/test_scheduler_defer_fifo_simple.py": 26.86,
-  "tests/integration/test_scheduler_defer_stress.py": 27.23,
-  "tests/integration/test_scheduler_heap_stress.py": 24.02,
-  "tests/integration/test_scheduler_internal_id_no_collision.py": 24.57,
-  "tests/integration/test_scheduler_interval_reschedule.py": 13.12,
-  "tests/integration/test_scheduler_interval_zero_coerced.py": 22.91,
-  "tests/integration/test_scheduler_null_name.py": 23.46,
-  "tests/integration/test_scheduler_numeric_id_test.py": 24.54,
-  "tests/integration/test_scheduler_pool.py": 25.0,
-  "tests/integration/test_scheduler_rapid_cancellation.py": 14.68,
-  "tests/integration/test_scheduler_recursive_timeout.py": 25.35,
-  "tests/integration/test_scheduler_removed_item_race.py": 26.19,
-  "tests/integration/test_scheduler_self_keyed.py": 23.43,
-  "tests/integration/test_scheduler_simultaneous_callbacks.py": 22.16,
-  "tests/integration/test_scheduler_string_test.py": 15.22,
-  "tests/integration/test_script_array_params.py": 14.67,
-  "tests/integration/test_script_delay_params.py": 15.65,
-  "tests/integration/test_script_queued.py": 24.93,
-  "tests/integration/test_script_queued_idle_loop.py": 5.04,
-  "tests/integration/test_script_wait_on_boot.py": 13.08,
-  "tests/integration/test_select_stringref_trigger.py": 29.6,
-  "tests/integration/test_sensor_filters_delta.py": 28.01,
-  "tests/integration/test_sensor_filters_ring_buffer.py": 25.04,
-  "tests/integration/test_sensor_filters_sliding_window.py": 71.5,
-  "tests/integration/test_sensor_filters_value_list.py": 16.94,
-  "tests/integration/test_sensor_timeout_filter.py": 29.48,
-  "tests/integration/test_socket_wake_gate_tcp.py": 20.36,
-  "tests/integration/test_status_flags.py": 37.42,
-  "tests/integration/test_strftime_to.py": 22.61,
-  "tests/integration/test_syslog.py": 16.34,
-  "tests/integration/test_template_alarm_control_panel_many_sensors.py": 29.81,
-  "tests/integration/test_template_text_save.py": 25.43,
-  "tests/integration/test_text_command.py": 23.34,
-  "tests/integration/test_text_sensor_raw_state.py": 69.57,
-  "tests/integration/test_uart_mock_ld2410.py": 37.95,
-  "tests/integration/test_uart_mock_ld2412.py": 93.22,
-  "tests/integration/test_uart_mock_ld2420.py": 43.24,
-  "tests/integration/test_uart_mock_ld2450.py": 31.75,
-  "tests/integration/test_uart_mock_modbus.py": 667.4,
-  "tests/integration/test_udp.py": 9.38,
-  "tests/integration/test_use_address_runtime.py": 37.05,
-  "tests/integration/test_valve_control_action.py": 24.47,
-  "tests/integration/test_varint_five_byte_device_id.py": 25.03,
-  "tests/integration/test_wait_until_mid_loop_timing.py": 23.73,
-  "tests/integration/test_wait_until_on_boot.py": 9.16,
-  "tests/integration/test_wait_until_ordering.py": 13.3,
-  "tests/integration/test_wait_until_reentrant_restart.py": 25.23,
-  "tests/integration/test_wake_loop_forces_phase_b.py": 23.34,
-  "tests/integration/test_water_heater_template.py": 17.67
+  "tests/integration/test_action_concurrent_reentry.py": 57.91,
+  "tests/integration/test_addressable_light_transition.py": 21.25,
+  "tests/integration/test_alarm_control_panel_state_transitions.py": 70.71,
+  "tests/integration/test_api_action_metadata.py": 66.6,
+  "tests/integration/test_api_action_responses.py": 36.1,
+  "tests/integration/test_api_action_timeout.py": 68.86,
+  "tests/integration/test_api_conditional_memory.py": 15.48,
+  "tests/integration/test_api_custom_services.py": 18.77,
+  "tests/integration/test_api_get_time_response_timezone.py": 21.08,
+  "tests/integration/test_api_homeassistant.py": 65.59,
+  "tests/integration/test_api_homeassistant_action_no_subscriber.py": 18.44,
+  "tests/integration/test_api_homeassistant_binary_sensor_initial_state.py": 15.05,
+  "tests/integration/test_api_list_entities_backpressure.py": 13.88,
+  "tests/integration/test_api_message_size_batching.py": 29.98,
+  "tests/integration/test_api_reboot_timeout.py": 16.05,
+  "tests/integration/test_api_string_lambda.py": 15.31,
+  "tests/integration/test_api_vv_logging.py": 19.28,
+  "tests/integration/test_api_zero_psk_provisioning.py": 31.5,
+  "tests/integration/test_areas_and_devices.py": 24.95,
+  "tests/integration/test_automation_wait_actions.py": 20.92,
+  "tests/integration/test_automations.py": 35.19,
+  "tests/integration/test_batch_delay_zero_rapid_transitions.py": 17.99,
+  "tests/integration/test_binary_sensor_autorepeat_filter.py": 20.39,
+  "tests/integration/test_binary_sensor_invalidate_state.py": 18.41,
+  "tests/integration/test_blocking_warning_log_time_not_charged_to_next_operation.py": 24.69,
+  "tests/integration/test_build_info.py": 18.7,
+  "tests/integration/test_camera_mock.py": 16.23,
+  "tests/integration/test_climate_control_action.py": 21.14,
+  "tests/integration/test_climate_custom_modes.py": 20.74,
+  "tests/integration/test_continuation_actions.py": 16.81,
+  "tests/integration/test_cover_control_action.py": 20.34,
+  "tests/integration/test_crc8_helper.py": 9.36,
+  "tests/integration/test_device_id_in_state.py": 44.67,
+  "tests/integration/test_duplicate_entities.py": 23.58,
+  "tests/integration/test_entity_icon.py": 34.35,
+  "tests/integration/test_fan_turn_on_action.py": 24.23,
+  "tests/integration/test_fnv1_hash_object_id.py": 16.21,
+  "tests/integration/test_fnv1a_hash.py": 13.38,
+  "tests/integration/test_gpio_expander_cache.py": 13.06,
+  "tests/integration/test_host_logger_thread_safety.py": 23.66,
+  "tests/integration/test_host_mode_basic.py": 8.01,
+  "tests/integration/test_host_mode_batch_delay.py": 21.0,
+  "tests/integration/test_host_mode_climate_basic_state.py": 22.14,
+  "tests/integration/test_host_mode_climate_control.py": 19.39,
+  "tests/integration/test_host_mode_empty_string_options.py": 21.76,
+  "tests/integration/test_host_mode_entity_fields.py": 29.61,
+  "tests/integration/test_host_mode_fan_preset.py": 20.01,
+  "tests/integration/test_host_mode_many_entities.py": 39.08,
+  "tests/integration/test_host_mode_many_entities_multiple_connections.py": 23.92,
+  "tests/integration/test_host_mode_noise_encryption.py": 42.42,
+  "tests/integration/test_host_mode_reconnect.py": 3.41,
+  "tests/integration/test_host_mode_sensor.py": 22.96,
+  "tests/integration/test_host_ota.py": 29.5,
+  "tests/integration/test_host_preferences.py": 16.06,
+  "tests/integration/test_host_preferences_suspend_resume.py": 18.71,
+  "tests/integration/test_improv_serial_uart.py": 20.22,
+  "tests/integration/test_large_message_batching.py": 26.56,
+  "tests/integration/test_legacy_area.py": 22.72,
+  "tests/integration/test_legacy_climate_compat.py": 14.13,
+  "tests/integration/test_legacy_fan_compat.py": 14.33,
+  "tests/integration/test_light_automations.py": 18.81,
+  "tests/integration/test_light_binary_effect_off_phase.py": 8.38,
+  "tests/integration/test_light_calls.py": 21.88,
+  "tests/integration/test_light_constant_brightness.py": 59.45,
+  "tests/integration/test_light_control_action.py": 31.91,
+  "tests/integration/test_light_dim_relative_action.py": 14.43,
+  "tests/integration/test_light_effect_zero_brightness.py": 25.05,
+  "tests/integration/test_light_initial_state.py": 18.97,
+  "tests/integration/test_light_toggle_action.py": 17.44,
+  "tests/integration/test_lock_automations.py": 18.9,
+  "tests/integration/test_logger_buffered_recursion_guard.py": 18.2,
+  "tests/integration/test_loop_disable_enable.py": 63.35,
+  "tests/integration/test_loop_interval_decoupling.py": 17.7,
+  "tests/integration/test_loop_interval_default_not_pulled_forward.py": 21.56,
+  "tests/integration/test_micros_to_millis.py": 15.89,
+  "tests/integration/test_multi_click_trigger.py": 17.23,
+  "tests/integration/test_multi_device_preferences.py": 19.4,
+  "tests/integration/test_noise_encryption_key_protection.py": 72.59,
+  "tests/integration/test_object_id_api_verification.py": 19.22,
+  "tests/integration/test_object_id_friendly_name_no_mac_suffix.py": 16.77,
+  "tests/integration/test_object_id_no_friendly_name.py": 45.8,
+  "tests/integration/test_online_image_auto_detects_image_bmp_mime.py": 86.73,
+  "tests/integration/test_online_image_auto_detects_redirected_image_bmp_mime.py": 40.4,
+  "tests/integration/test_online_image_bmp.py": 37.24,
+  "tests/integration/test_oversized_payloads.py": 55.75,
+  "tests/integration/test_preference_key_stability.py": 25.49,
+  "tests/integration/test_runtime_stats.py": 29.81,
+  "tests/integration/test_safe_mode_loop_runs.py": 6.26,
+  "tests/integration/test_scheduler_blocking_warning.py": 37.98,
+  "tests/integration/test_scheduler_bulk_cleanup.py": 18.67,
+  "tests/integration/test_scheduler_defer_cancel.py": 18.46,
+  "tests/integration/test_scheduler_defer_cancel_regular.py": 16.34,
+  "tests/integration/test_scheduler_defer_fifo_simple.py": 18.26,
+  "tests/integration/test_scheduler_defer_stress.py": 17.74,
+  "tests/integration/test_scheduler_heap_stress.py": 3.89,
+  "tests/integration/test_scheduler_internal_id_no_collision.py": 20.01,
+  "tests/integration/test_scheduler_interval_reschedule.py": 16.29,
+  "tests/integration/test_scheduler_interval_zero_coerced.py": 16.09,
+  "tests/integration/test_scheduler_null_name.py": 14.69,
+  "tests/integration/test_scheduler_numeric_id_test.py": 17.08,
+  "tests/integration/test_scheduler_pool.py": 19.88,
+  "tests/integration/test_scheduler_rapid_cancellation.py": 4.42,
+  "tests/integration/test_scheduler_recursive_timeout.py": 4.3,
+  "tests/integration/test_scheduler_removed_item_race.py": 15.49,
+  "tests/integration/test_scheduler_self_keyed.py": 25.77,
+  "tests/integration/test_scheduler_simultaneous_callbacks.py": 14.84,
+  "tests/integration/test_scheduler_string_test.py": 15.42,
+  "tests/integration/test_script_array_params.py": 12.73,
+  "tests/integration/test_script_delay_params.py": 12.69,
+  "tests/integration/test_script_queued.py": 20.38,
+  "tests/integration/test_script_queued_idle_loop.py": 25.06,
+  "tests/integration/test_script_wait_on_boot.py": 15.67,
+  "tests/integration/test_select_stringref_trigger.py": 19.48,
+  "tests/integration/test_sensor_filters_delta.py": 27.62,
+  "tests/integration/test_sensor_filters_ring_buffer.py": 20.27,
+  "tests/integration/test_sensor_filters_sliding_window.py": 56.28,
+  "tests/integration/test_sensor_filters_value_list.py": 20.6,
+  "tests/integration/test_sensor_timeout_filter.py": 22.21,
+  "tests/integration/test_socket_wake_gate_tcp.py": 16.37,
+  "tests/integration/test_status_flags.py": 29.68,
+  "tests/integration/test_strftime_to.py": 17.42,
+  "tests/integration/test_syslog.py": 18.39,
+  "tests/integration/test_template_alarm_control_panel_many_sensors.py": 25.61,
+  "tests/integration/test_template_text_save.py": 19.16,
+  "tests/integration/test_text_command.py": 16.43,
+  "tests/integration/test_text_sensor_raw_state.py": 17.19,
+  "tests/integration/test_uart_mock_ld2410.py": 37.0,
+  "tests/integration/test_uart_mock_ld2412.py": 40.82,
+  "tests/integration/test_uart_mock_ld2420.py": 32.7,
+  "tests/integration/test_uart_mock_ld2450.py": 32.84,
+  "tests/integration/test_uart_mock_modbus.py": 548.87,
+  "tests/integration/test_udp.py": 16.67,
+  "tests/integration/test_use_address_runtime.py": 27.26,
+  "tests/integration/test_valve_control_action.py": 24.58,
+  "tests/integration/test_varint_five_byte_device_id.py": 22.5,
+  "tests/integration/test_wait_until_mid_loop_timing.py": 22.05,
+  "tests/integration/test_wait_until_on_boot.py": 10.37,
+  "tests/integration/test_wait_until_ordering.py": 18.23,
+  "tests/integration/test_wait_until_reentrant_restart.py": 19.35,
+  "tests/integration/test_wake_loop_forces_phase_b.py": 17.83,
+  "tests/integration/test_water_heater_template.py": 25.7
 }

tests/integration/test_api_noise_resume.py

@@ -0,0 +1,58 @@
+"""Integration test for noise session resume."""
+
+from __future__ import annotations
+
+import asyncio
+
+import aioesphomeapi.core
+import pytest
+
+from .types import APIClientConnectedFactory, RunCompiledFunction
+
+NOISE_KEY = "N4Yle5YirwZhPiHHsdZLdOA73ndj/84veVaLhTvxCuU="
+
+
+@pytest.mark.asyncio
+async def test_api_noise_resume(
+    yaml_config: str,
+    run_compiled: RunCompiledFunction,
+    api_client_connected: APIClientConnectedFactory,
+) -> None:
+    """A reconnect with the ticket from the first connection resumes the session."""
+    if not hasattr(aioesphomeapi.core, "ResumeAPIError"):
+        pytest.skip("aioesphomeapi without noise session resume")
+
+    resumed = asyncio.Event()
+    resumed_count = 0
+
+    def on_line(line: str) -> None:
+        nonlocal resumed_count
+        if "Session resumed" in line:
+            resumed_count += 1
+            resumed.set()
+
+    async with (
+        run_compiled(yaml_config, line_callback=on_line),
+        api_client_connected(noise_psk=NOISE_KEY) as client,
+    ):
+        # First connection: full handshake, the device issues a ticket
+        info = await client.device_info()
+        assert info.name == "host-noise-resume"
+        assert resumed_count == 0
+
+        # Same client reconnects and offers the ticket
+        await client.disconnect()
+        await client.connect(login=True)
+        info = await client.device_info()
+        assert info.name == "host-noise-resume"
+        await asyncio.wait_for(resumed.wait(), timeout=10.0)
+        assert resumed_count == 1
+        resumed.clear()
+
+        # The resumed session issued a fresh ticket, so it resumes again
+        await client.disconnect()
+        await client.connect(login=True)
+        info = await client.device_info()
+        assert info.name == "host-noise-resume"
+        await asyncio.wait_for(resumed.wait(), timeout=10.0)
+        assert resumed_count == 2