key_extraction_responder.cpp

Go to the documentation of this file.

#include "key_extraction_responder.h"
 
#include "log_helpers.h"
 
#include "device_registry.h"
#include "pairing_responder.h"
#include "proto_commands.h"
#include "proto_crypto.h"
#include "radio_interface.h"
#include "tuning_config.h"
 
#include <esp_random.h>
 
#include <cinttypes>
#include <cstdio>
#include <cstring>
#include <string>
 
/// @file key_extraction_responder.cpp
/// @brief "Recover System Key" (key extraction) — device-role responder collaborator.
/// @ingroup hioc_hub
///
/// Owns the impure side of the key-extraction feature: arming/disarming, throwaway node-ID
/// generation, the 10-minute auto-off timer, the post-extraction grace window, transmitting
/// device-role replies, and the security-sensitive result log block. The pure state-transition
/// decisions live in pairing_responder.h/.cpp; the six RX branches
/// (0x28/0x2C/0x31/0x32/0x36/0x3C) dispatch through try_handle_frame(), called from
/// process_received_packet_() (hub_status.cpp).
///
/// @note Hardware-confirmed 2026-08-02: a full extraction (0x28 through 0x33) between two real
/// boards — SX1276 running this responder, SX1262 running this project's own PairingEngine as
/// the "hub" — recovered the hub's node_id/system_key byte-for-byte. That validates the crypto,
/// the state machine, and the radio wiring end-to-end on real RF hardware.
/// @warning What that test does NOT validate: compatibility with a genuine third-party hub
/// (Somfy TaHoma/Smoove, Velux KLF200, etc.). The device-role frames built here
/// (create_discover_resp(), create_challenge_req(), create_key_confirm()) were reverse-engineered
/// from this project's own encoder and a small number of captures. The self-test above
/// necessarily agrees with those conventions (it's the same codebase on both ends); a real hub's
/// exact requirements (discovery-response field completeness, retry cadence) may still differ. It
/// is blind to two things in particular: a device-role frame that is self-consistent but wrong on
/// air, and a protocol step a real hub requires that this project's own controller role never
/// sends. Both are real failure modes against real hubs; see
/// tests/corpus/captures/pairing/velux_kig300_pairing_key_extraction_stall.yaml and
/// tests/corpus/captures/pairing/somfy_connectivity_kit_pairing_key_extraction_stall.yaml.
///
/// The device-role builders (create_discover_resp(), create_challenge_req_device_role(),
/// create_key_confirm(), create_discover_confirm_ack()) are each pinned against a real device's
/// captured framing by tests/corpus/corpus_device_role_builder_test.cpp, including
/// create_discover_resp()'s flags/timestamp bytes, which mirror a real Somfy Izymo dimmer's
/// captured values (see KEY_EXTRACTION_DISCOVER_RESP_FLAGS/_TIMESTAMP in proto_constants.h/proto_commands.cpp for
/// the derivation) but remain unconfirmed against a real hub like every device-role field here.
///
/// recover_system_key_from_transfer()'s IV-derivation formula itself is independently pinned
/// against two externally-captured known-answer key transfers
/// (ProtoCrypto.CryptKeyMatchesDocumented*Capture in proto_crypto_test.cpp), so that formula does
/// not rest on this codebase's own conventions — though both captures are short requests and don't
/// exercise construct_iv()'s 8-byte truncation window, so a real hub sending a longer request is an
/// open question. Treat a recovered key as unconfirmed until it has been verified against a real
/// hub, or by successfully controlling a device with it.
 
namespace esphome {
namespace home_io_control {
 
namespace {
 
constexpr uint32_t KEY_EXTRACTION_AUTO_OFF_MS = 10 * 60 * 1000;  ///< Arm window: 10 minutes.
// TODO(hardware-verify): confirm a real hub's pairing flow doesn't validate the advertised
// manufacturer/type against a known-device allowlist before completing key exchange —
// Somfy/roller-shutter is a plausible but unconfirmed default.
constexpr uint8_t KEY_EXTRACTION_MANUFACTURER_ID = MANUFACTURER_SOMFY;  ///< Plausible, widely-supported default.
constexpr uint8_t KEY_EXTRACTION_ID_GEN_MAX_ATTEMPTS = 16;  ///< Collision-retry budget for the throwaway node ID.
constexpr size_t IO_CHANNEL_COUNT = 3;                      ///< FREQ_CH1..FREQ_CH3.
constexpr const char *KEY_EXTRACTION_DISCOVER_REPLY_TIMER_NAME = "key_extraction_discover_reply";
constexpr const char *KEY_EXTRACTION_TIMEOUT_NAME = "key_extraction_auto_off";
constexpr uint32_t RANDOM_LOW_BYTE_MASK = 0xFF;  ///< Isolates one random byte from esp_random()'s 32-bit output.
 
constexpr uint32_t KEY_EXTRACTION_MID_ATTEMPT_TIMEOUT_MS = 5000;  ///< 5 seconds.
// Bounds the responder listen (key_extraction_responder.h's key_extraction_hold_deadline_ms_ /
// awaiting_reply()) for the 3 pre-extraction states (SENT_DISCOVER_RESP, SENT_CONFIRM_ACK,
// SENT_CHALLENGE), none of which has a hold bound of its own otherwise -- CMD_DISCOVER_REQ is
// handled before the throwaway-ID dst filter (try_handle_frame()), so *any* 0x28 from any hub in
// range that then goes silent would otherwise keep the radio listening for the rest of the arm
// window, with background polls deferred.
//
// This is purely a radio-scheduling optimization, not a protocol-recovery deadline: expiry only
// stops loop() from listening for this responder (see key_extraction_hold_deadline_ms_'s doc
// comment in key_extraction_responder.h) -- it does NOT touch key_extraction_ctx_.state, so a real
// hub's frame arriving even slightly late is still accepted by the pure guards in
// pairing_responder.cpp exactly as if the listen were still active, just caught by the coarser
// idle hop instead. That makes the cost of sizing this too small merely "occasionally falls back
// to the idle hop a little early," not "silently drops a live attempt" -- so 5s is sized
// generously rather than tightly: a real hub that's still trying should have its very next frame
// land well inside this window -- comfortably above a single retry gap (EXCHANGE_RETRY_DELAY_MS=250ms)
// plus the request/response windows either side of it
// (PAIRING_KEY_CHALLENGE_TIMEOUT_MS/PAIRING_KEY_CONFIRM_TIMEOUT_MS=500ms each, pairing_engine.h) --
// while staying "a few seconds", not minutes, sized against third-party hub timing (the whole
// reason this feature exists), not this project's own controller role. Not hardware-measured;
// deliberately generous rather than tight, matching KEY_EXTRACTION_POST_EXTRACT_GRACE_MS's own
// reasoning below.
 
constexpr uint32_t KEY_EXTRACTION_POST_EXTRACT_GRACE_MS = 60000;  ///< One minute.
// TODO(hardware-verify): no timing data exists for the 0x33->0x36 gap on real hardware (the only
// capture of that gap is an untimed SPI trace). One minute is deliberately generous rather than
// tight: every pre-EXTRACTED guard in pairing_responder.cpp still rejects EXTRACTED/SENT_ADDRESS_
// RESP for 0x2C/0x31/0x32, so a *different* hub cannot interfere with a live round inside this
// window. on_discover_request() is the one exception, deliberately: it accepts a fresh 0x28 from
// the *same* hub as ctx.hub_node_id (see that function's doxygen for why), so the window is inert
// to every hub except the one it's actually running a round with. It is still hard-capped by the
// 10-minute auto-off timer above, and the only cost of overshooting is that the HA switch reports
// "still listening" for longer. Undershooting, by contrast, silently drops a slow hub's
// node-verification round — the exact failure this feature exists to fix. Not measured.
constexpr const char *KEY_EXTRACTION_GRACE_TIMER_NAME = "key_extraction_post_extract_grace";
 
}  // namespace
 
namespace detail {
 
std::string build_key_extraction_report(const uint8_t node_id[NODE_ID_SIZE], const uint8_t key[AES_KEY_SIZE]) {
  return "SYSTEM KEY EXTRACTED -- DO NOT SHARE YOUR SYSTEM KEY\n"
         "Anyone with this key and node_id can control every device on this installation.\n"
         "This exchange has not been independently confirmed against your specific hub -- test\n"
         "this key (e.g. by controlling a device with it) before relying on it.\n"
         "Copy the block below into a new hub's YAML.\n"
         "home_io_control:\n"
         "  node_id: \"" +
         node_id_to_string(node_id) + "\"\n" + "  system_key: \"" + format_key_hex(key) + "\"";
}
 
}  // namespace detail
 
KeyExtractionResponder::KeyExtractionResponder(const uint8_t *node_id, RadioDriver **radio, const TuningConfig *tuning,
                                               DeviceRegistry &registry, TransmitFrameFn transmit,
                                               NamedTimeoutFn schedule_auto_off)
    : node_id_(node_id),
      radio_(radio),
      tuning_(tuning),
      registry_(registry),
      transmit_(std::move(transmit)),
      schedule_auto_off_(std::move(schedule_auto_off)) {}
 
void KeyExtractionResponder::generate_throwaway_id(uint8_t out[NODE_ID_SIZE]) {
  for (uint8_t attempt = 0; attempt < KEY_EXTRACTION_ID_GEN_MAX_ATTEMPTS; attempt++) {
    for (uint8_t i = 0; i < NODE_ID_SIZE; i++)
      out[i] = static_cast<uint8_t>(esp_random() & RANDOM_LOW_BYTE_MASK);
    if (!stored_node_id_is_valid(out))
      continue;
    if (memcmp(out, this->node_id_, NODE_ID_SIZE) == 0)
      continue;
    if (memcmp(out, BROADCAST_DISCOVER, NODE_ID_SIZE) == 0 || memcmp(out, BROADCAST_DISCOVER_ALT, NODE_ID_SIZE) == 0)
      continue;
    if (this->registry_.get(node_id_to_string(out)) != nullptr)
      continue;
    return;
  }
  // Every attempt collided (astronomically unlikely for a 3-byte space against a handful of
  // reserved/registered IDs) — fall through and use the last-generated candidate rather than
  // leaving the buffer stale; a false collision here only degrades to "discovery/key-init from
  // the colliding real device also gets intercepted," not a crash or security issue.
}
 
void KeyExtractionResponder::set_armed(bool armed) {
  if (!armed) {
    if (this->key_extraction_ctx_.state == pairing_responder::ResponderState::DISARMED)
      return;
    this->key_extraction_ctx_ = pairing_responder::ResponderContext{};
    ESP_LOGI(detail::TAG, "Key extraction: disarmed");
    if (this->armed_callback_)
      this->armed_callback_(false);
    return;
  }
 
  this->key_extraction_ctx_ = pairing_responder::ResponderContext{};
  this->generate_throwaway_id(this->key_extraction_ctx_.throwaway_id);
  this->set_configured_type_();
  this->key_extraction_ctx_.state = pairing_responder::ResponderState::ARMED_IDLE;
 
  ESP_LOGW(detail::TAG,
           "Key extraction: ARMED for 10 minutes, throwaway ID %s. Put your existing hub into pairing/add-device "
           "mode now.",
           node_id_to_string(this->key_extraction_ctx_.throwaway_id).c_str());
 
  // This timer and arm_post_extraction_grace()'s below share one idiom (named set_timeout(),
  // guarded by a state check so a stale callback from a disarm-and-rearm inside the window can't
  // act on the wrong cycle, logging, then disarming) — two call sites, not enough to be worth
  // extracting into a shared helper at the cost of an extra layer of indirection between the
  // guard condition and what it's guarding.
  this->schedule_auto_off_(KEY_EXTRACTION_TIMEOUT_NAME, KEY_EXTRACTION_AUTO_OFF_MS, [this]() {
    // Guards against a stale timeout firing after a manual disarm/re-arm already ran; this hub's
    // set_timeout() replaces any pending callback with the same name, but the check is cheap
    // insurance and documents the intent either way.
    if (this->key_extraction_ctx_.state == pairing_responder::ResponderState::DISARMED)
      return;
    if (this->key_extraction_ctx_.state == pairing_responder::ResponderState::ARMED_IDLE) {
      ESP_LOGW(detail::TAG, "Key extraction: window expired, no pairing attempt seen. Disarming.");
    } else {
      ESP_LOGW(detail::TAG, "Key extraction: window expired while in progress (reached stage=%s). Disarming.",
               pairing_responder::responder_stage_name(this->key_extraction_ctx_.state));
    }
    this->set_armed(false);
  });
 
  if (this->armed_callback_)
    this->armed_callback_(true);
}
 
bool KeyExtractionResponder::try_handle_frame(const IoFrame &frame, uint32_t rx_freq_hz) {
  if (this->key_extraction_ctx_.state == pairing_responder::ResponderState::DISARMED)
    return false;
  // Kept for the handler that answers this frame: answering makes this channel the session's
  // (send_reply_()). An unanswered frame leaves the session channel as it was.
  this->rx_freq_hz_ = rx_freq_hz != 0 ? rx_freq_hz : FREQ_CH2;
  this->rx_ms_ = millis();
 
  if (frame.cmd == CMD_DISCOVER_REQ) {
    this->handle_discover_(frame);
    return true;
  }
  if (memcmp(frame.dst, this->key_extraction_ctx_.throwaway_id, NODE_ID_SIZE) != 0)
    return false;
  if (frame.cmd == CMD_DISCOVER_CONFIRM) {
    this->handle_discover_confirm_(frame);
    return true;
  }
  if (frame.cmd == CMD_KEY_INIT) {
    this->handle_key_init_(frame);
    return true;
  }
  if (frame.cmd == CMD_KEY_TRANSFER) {
    this->handle_key_transfer_(frame);
    return true;
  }
  if (frame.cmd == CMD_NODE_VERIFY_REQ) {
    this->handle_node_verify_req_(frame);
    return true;
  }
  if (frame.cmd == CMD_CHALLENGE_REQ) {
    this->handle_node_verify_challenge_(frame);
    return true;
  }
  return false;
}
 
void KeyExtractionResponder::send_reply_(const IoFrame &frame) {
  // The frame being answered opens (or continues) the session on its channel: the peer sent it
  // there and waits there for our answer, and its in-session follow-up comes on the same channel.
  this->session_freq_ = this->rx_freq_hz_;
  this->session_rx_ms_ = this->rx_ms_;
 
  // Every reply that reaches this path (0x2D, 0x3C, 0x33, 0x37, 0x3D) is `start=false`: it lands
  // on the channel the peer holds, so it keeps the driver's chip-tuned response_preamble(), same
  // as every other in-exchange reply in this codebase. The one start-flagged reply, the 0x29, goes
  // out through schedule_discover_reply_() instead.
  //
  // Do NOT widen this to a flat LONG_PREAMBLE(1024) for every reply: hardware-confirmed
  // 2026-08-02, that blocked the main loop long enough to blow through the hub's tight per-try
  // wait windows and broke both directions.
  const uint16_t preamble = (*this->radio_)->response_preamble();
 
  // An answer to a frame addressed to us goes out once, on that frame's channel, at once: the
  // peer stays on the channel it sent on to wait for it (0 of 300 measured unicast replies came
  // back on another channel, exchange_engine.cpp's first-response wait). Repeating it on the
  // other channels would only keep this radio transmitting while the peer already answers.
  this->transmit_(frame, this->session_freq_, preamble);
}
 
void KeyExtractionResponder::schedule_discover_reply_(const IoFrame &search, const IoFrame &resp) {
  // A device answers a search once, in a random slot from 1 to N (never slot 0), on one
  // channel, and the searcher collects for the whole window before it confirms. The answer is
  // therefore a timed transmission, not a reply at once: the searcher's window is N slots long.
  const uint32_t slots = discovery_slot_count(search.dst);
  const uint32_t slot = 1 + (esp_random() % slots);
  const uint32_t delay_ms = slot * DISCOVERY_SLOT_MS;
  // One random channel of the two the search did not come in on: a searcher listens on those for
  // its answers (a discovery reply lands on the request channel in about 1 of 149 measured
  // answers, ListenPolicy::ROTATE_SKIPPING_REQUEST), so a draw over all three would lose a third.
  static constexpr uint32_t CHANNELS[IO_CHANNEL_COUNT] = {FREQ_CH1, FREQ_CH2, FREQ_CH3};
  size_t search_index = 1;  // CH2, the channel a frame with no reported channel counts as
  for (size_t i = 0; i < IO_CHANNEL_COUNT; i++) {
    if (CHANNELS[i] == this->rx_freq_hz_)
      search_index = i;
  }
  // One or two channels on from the search's: always one of the other two.
  const size_t step = 1 + (esp_random() % (IO_CHANNEL_COUNT - 1));
  const uint32_t freq = CHANNELS[(search_index + step) % IO_CHANNEL_COUNT];
 
  // The 0x29 is no reply on the search's channel: the session (and its channel hold) opens only
  // with the confirm that follows, which may come on any channel. Leave the hold expired.
  this->session_freq_ = this->rx_freq_hz_;
  this->session_rx_ms_ = this->rx_ms_ - this->session_window_ms_;
 
  this->pending_discover_resp_ = resp;
  this->discover_reply_pending_ = true;
  this->discover_reply_due_ms_ = millis() + delay_ms;
  // Same timer name: a repeated search replaces the answer still waiting for its slot.
  this->schedule_auto_off_(KEY_EXTRACTION_DISCOVER_REPLY_TIMER_NAME, delay_ms, [this, freq]() {
    this->discover_reply_pending_ = false;
    // Only the attempt that scheduled it may send it: after a disarm, or a disarm and re-arm (a
    // fresh throwaway ID, state back to ARMED_IDLE), this answer is stale.
    if (this->key_extraction_ctx_.state != pairing_responder::ResponderState::SENT_DISCOVER_RESP)
      return;
    // The one reply a hopping/scanning peer has to catch cold, so `cold_broadcast_reply_preamble`:
    // long enough for that, much shorter than LONG_PREAMBLE so the loop is not blocked.
    this->transmit_(this->pending_discover_resp_, freq, this->tuning_->cold_broadcast_reply_preamble);
  });
  // Hold the radio (and defer background polls) through the slot and the confirm that follows it.
  this->key_extraction_hold_deadline_ms_ = millis() + delay_ms + KEY_EXTRACTION_MID_ATTEMPT_TIMEOUT_MS;
  ESP_LOGD(detail::TAG,
           "Key extraction: discovery answer in slot %" PRIu32 " of %" PRIu32 " (%" PRIu32 " ms) on %" PRIu32 " Hz",
           slot, slots, delay_ms, freq);
}
 
void KeyExtractionResponder::set_configured_type_() {
  // The word is the wire form (type << 6 | subtype), so a value copied from a real device's 0x29 is
  // sent back byte for byte.
  const uint16_t word = this->tuning_->key_extraction_type_word;
  const auto msb = static_cast<uint8_t>(word >> BITS_PER_BYTE);
  const auto lsb = static_cast<uint8_t>(word);  // low byte: top 2 type bits + 6-bit subtype
  this->key_extraction_ctx_.advertised_type = decode_packed_device_type(msb, lsb);
  this->key_extraction_ctx_.advertised_subtype = decode_packed_device_subtype(lsb);
}
 
void KeyExtractionResponder::handle_discover_(const IoFrame &frame) {
  if (!pairing_responder::on_discover_request(this->key_extraction_ctx_, frame.src))
    return;
 
  // A controller that searches for one device type (a typed discovery such as `00 FF FB`, sent by an
  // Atlantic heater in its connectivity menu, #199) is expected to ignore answers of any other type, so
  // answer as the type it asked for. Decided per request, not per attempt: a hub may send a typed and an open discovery
  // in sequence. Without a typed request (an open `00 00 3B` discovery, or an undefined type) the configured
  // `key_extraction_type_word` applies. The manufacturer stays Somfy: one variable at a time.
  const DeviceType requested_type = discovery_target_type(frame.dst);
  if (requested_type != DeviceType::UNKNOWN) {
    this->key_extraction_ctx_.advertised_type = requested_type;
    this->key_extraction_ctx_.advertised_subtype = 0;
  } else {
    this->set_configured_type_();
  }
 
  IoFrame resp;
  // The Multi Information Byte is a tuning choice (key_extraction_multi_info): a hub may skip a
  // device that advertises low power (#215). The session window follows its turnaround class.
  const uint8_t flags = this->tuning_->key_extraction_multi_info;
  this->session_window_ms_ = key_extraction_session_window_ms(flags);
  if (!create_discover_resp(resp, this->key_extraction_ctx_.throwaway_id, frame.src,
                            this->key_extraction_ctx_.advertised_type, this->key_extraction_ctx_.advertised_subtype,
                            KEY_EXTRACTION_MANUFACTURER_ID, flags)) {
    ESP_LOGW(detail::TAG, "Key extraction: failed to build discovery response");
    // Deliberately does NOT touch key_extraction_hold_deadline_ms_: on_discover_request() already
    // advanced ctx.state above, but a failed builder means no reply went out, so there is nothing
    // for the hub to be replying to yet. Leaving the deadline exactly as it was (0 on a fresh arm,
    // safely "already expired" per key_extraction_hold_deadline_ms_'s doc comment; or whatever an
    // earlier successful reply set it to, still correctly bounded) is what keeps a builder failure
    // from either holding the radio unboundedly or clobbering a still-valid earlier deadline.
    return;
  }
  this->schedule_discover_reply_(frame, resp);
  ESP_LOGI(detail::TAG,
           "Key extraction: answering discovery from hub %s as node type %u subtype %u (type word 0x%02X%02X, "
           "multi info 0x%02X) with throwaway ID %s",
           node_id_to_string(frame.src).c_str(), static_cast<unsigned>(this->key_extraction_ctx_.advertised_type),
           this->key_extraction_ctx_.advertised_subtype, resp.data[0], resp.data[1], flags,
           node_id_to_string(this->key_extraction_ctx_.throwaway_id).c_str());
}
 
void KeyExtractionResponder::handle_discover_confirm_(const IoFrame &frame) {
  if (!pairing_responder::on_discover_confirm(this->key_extraction_ctx_))
    return;
 
  IoFrame resp;
  if (!create_discover_confirm_ack(resp, this->key_extraction_ctx_.throwaway_id, frame.src)) {
    ESP_LOGW(detail::TAG, "Key extraction: failed to build discovery-confirm ack");
    // See handle_discover_()'s matching comment: leaving the hold deadline untouched on a builder
    // failure is deliberate, not an oversight.
    return;
  }
  this->send_reply_(resp);
  this->key_extraction_hold_deadline_ms_ = millis() + KEY_EXTRACTION_MID_ATTEMPT_TIMEOUT_MS;
  ESP_LOGI(detail::TAG, "Key extraction: acknowledged discovery confirm from hub %s",
           node_id_to_string(frame.src).c_str());
}
 
void KeyExtractionResponder::handle_key_init_(const IoFrame &frame) {
  uint8_t candidate_challenge[HMAC_SIZE];
  crypto::generate_challenge(candidate_challenge);
  if (!pairing_responder::on_key_init(this->key_extraction_ctx_, candidate_challenge, frame.src))
    return;
 
  IoFrame resp;
  if (!create_challenge_req_device_role(resp, frame.src, this->key_extraction_ctx_.throwaway_id,
                                        this->key_extraction_ctx_.challenge)) {
    ESP_LOGW(detail::TAG, "Key extraction: failed to build challenge request");
    // See handle_discover_()'s matching comment: leaving the hold deadline untouched on a builder
    // failure is deliberate, not an oversight.
    return;
  }
  this->send_reply_(resp);
  this->key_extraction_hold_deadline_ms_ = millis() + KEY_EXTRACTION_MID_ATTEMPT_TIMEOUT_MS;
  ESP_LOGI(detail::TAG, "Key extraction: sent challenge to hub %s", node_id_to_string(frame.src).c_str());
}
 
void KeyExtractionResponder::handle_key_transfer_(const IoFrame &frame) {
  if (frame.data_len < AES_KEY_SIZE) {
    ESP_LOGW(detail::TAG, "Key extraction: key-transfer payload too short (%u bytes)", frame.data_len);
    return;
  }
  if (!pairing_responder::on_key_transfer(this->key_extraction_ctx_, frame.data))
    return;
 
  IoFrame resp;
  if (create_key_confirm(resp, this->key_extraction_ctx_.throwaway_id, frame.src)) {
    this->send_reply_(resp);
  } else {
    ESP_LOGW(detail::TAG, "Key extraction: failed to build key confirm");
  }
 
  // Log before the grace window can disarm us: disarm resets key_extraction_ctx_, which is where
  // the recovered key and the hub's real node ID live.
  this->log_result_();
  ESP_LOGI(detail::TAG,
           "Key extraction: still listening for up to %" PRIu32
           " more seconds in case the hub verifies this device (CMD_NODE_VERIFY_REQ/0x36) — leave the "
           "switch on until it turns off on its own.",
           KEY_EXTRACTION_POST_EXTRACT_GRACE_MS / 1000);
  // Don't disarm immediately: some hubs (Velux KLR200) follow the key exchange with a node
  // verification request (0x36) and a challenge (0x3C) against our answer, and disarming here would make the
  // responder deaf to that round before it can happen. A *different* hub attempting to pair
  // mid-window still cannot succeed and produce a second, confusing log block — every pure guard in
  // pairing_responder.cpp except on_discover_request() unconditionally rejects EXTRACTED/
  // SENT_NODE_VERIFY_RESP, and on_discover_request() itself only accepts a fresh 0x28 from that same
  // hub_node_id, so a different hub's traffic still cannot advance the state machine backwards. The
  // grace timer below disarms once no further progress is seen from the real hub, instead of doing
  // it at once.
  this->arm_post_extraction_grace();
}
 
void KeyExtractionResponder::handle_node_verify_req_(const IoFrame &frame) {
  // Our throwaway ID is not a secret -- it went out in clear in our own 0x29/0x37 -- so the dst
  // check in try_handle_frame() alone doesn't establish this frame actually came from the hub we
  // exchanged keys with. hub_node_id was captured from the 0x31 that started this attempt
  // (pairing_responder::on_key_init()); anything else claiming our throwaway ID as dst is not that
  // hub and gets no reply, closing an otherwise-unbounded loop an onlooker could drive to keep
  // re-arming the grace window for as long as the arm cycle lasts.
  if (memcmp(frame.src, this->key_extraction_ctx_.hub_node_id, NODE_ID_SIZE) != 0)
    return;
  if (!pairing_responder::on_node_verify_req(this->key_extraction_ctx_))
    return;
  IoFrame resp;
  if (!create_node_verify_resp_device_role(resp, this->key_extraction_ctx_.throwaway_id, frame.src)) {
    ESP_LOGW(detail::TAG, "Key extraction: failed to build address response");
    return;
  }
  this->send_reply_(resp);
  this->arm_post_extraction_grace();  // Hub is still progressing — push the disarm back out.
  ESP_LOGI(detail::TAG, "Key extraction: answered node verification request from hub %s",
           node_id_to_string(frame.src).c_str());
}
 
void KeyExtractionResponder::handle_node_verify_challenge_(const IoFrame &frame) {
  // Hub-identity guard, mirroring handle_node_verify_req_()'s: only the hub we actually exchanged keys
  // with may drive this round.
  if (memcmp(frame.src, this->key_extraction_ctx_.hub_node_id, NODE_ID_SIZE) != 0)
    return;
  // Length guard, mirroring handle_key_transfer_()'s: frame.data is passed straight into a
  // `const uint8_t challenge[HMAC_SIZE]` parameter, so a short 0x3C would silently authenticate
  // over stale bytes left in IoFrame::data from a previous parse.
  if (frame.data_len < HMAC_SIZE) {
    ESP_LOGW(detail::TAG, "Key extraction: address challenge payload too short (%u bytes)", frame.data_len);
    return;
  }
  if (!pairing_responder::on_node_verify_challenge(this->key_extraction_ctx_))
    return;
  // Rebuild the 0x37 we last sent — deterministic from ctx, nothing stored across the two calls.
  // Only origin.cmd/origin.data/origin.data_len feed the transcript, so the dst passed here is
  // irrelevant to the HMAC; the real builder is used anyway so the transcript cannot drift if the
  // 0x37 payload ever changes.
  IoFrame our_node_verify_resp;
  if (!create_node_verify_resp_device_role(our_node_verify_resp, /*own=*/this->key_extraction_ctx_.throwaway_id,
                                           /*dst=*/frame.src))
    return;
  IoFrame resp;
  if (!create_challenge_resp_device_role(resp, /*dst=*/frame.src, /*src=*/this->key_extraction_ctx_.throwaway_id,
                                         frame.data, our_node_verify_resp, this->key_extraction_ctx_.recovered_key)) {
    ESP_LOGW(detail::TAG, "Key extraction: failed to build address challenge response");
    return;
  }
  this->send_reply_(resp);
  ESP_LOGI(detail::TAG, "Key extraction: answered address challenge from hub %s", node_id_to_string(frame.src).c_str());
  // Do NOT disarm here — re-arm the grace window instead and stay in SENT_NODE_VERIFY_RESP so a
  // retried 0x3C is answered (on_node_verify_challenge() deliberately never advances state).
  this->arm_post_extraction_grace();
}
 
void KeyExtractionResponder::arm_post_extraction_grace() {
  // Same replace-on-reschedule idiom as KEY_EXTRACTION_TIMEOUT_NAME's 10-minute timer above —
  // every new sign of hub progress (0x36 received, 0x3D sent, and this same call at extraction
  // time) pushes the disarm back out, so a slow multi-retry hub isn't cut off mid-round. That
  // 10-minute timer is deliberately neither cancelled nor extended here, so it still bounds the
  // whole arm cycle: no amount of grace-window re-arming can keep the responder listening past the
  // 10 minutes the switch entity documents.
  //
  // Also pushes out key_extraction_hold_deadline_ms_ (key_extraction_responder.h) by the same
  // window: the listen that field governs is not just for the 3 pre-extraction states
  // KEY_EXTRACTION_MID_ATTEMPT_TIMEOUT_MS bounds -- EXTRACTED/SENT_NODE_VERIFY_RESP are "awaiting
  // reply" too (a hub may still send 0x36/0x3C to verify the address it was handed), and this
  // grace window, not the 5s mid-attempt one, is what should bound the listen during that phase.
  // Without this, the listen would (per key_extraction_hold_deadline_ms_'s default-past-if-unset
  // behavior) never actually engage once the responder reaches EXTRACTED, for the very phase whose
  // whole point is catching a hub's follow-up unicast frame.
  this->schedule_auto_off_(KEY_EXTRACTION_GRACE_TIMER_NAME, KEY_EXTRACTION_POST_EXTRACT_GRACE_MS, [this]() {
    // Only a still-running post-extraction cycle may be disarmed from here. Checking DISARMED
    // alone is NOT enough: a user who toggles the switch off and back on inside the grace window
    // leaves this callback pending against a brand-new, unrelated arm cycle (set_timeout() only
    // replaces a *pending* timer of the same name, and re-arming schedules the 10-minute auto-off
    // timer, not this one) — and that new cycle is ARMED_IDLE, not DISARMED, so a DISARMED-only
    // guard would let a stale callback kill it.
    // The converse worry — that the new cycle reaches EXTRACTED (a state this guard accepts)
    // before the stale callback fires — cannot happen: reaching EXTRACTED calls this function,
    // whose set_timeout() replaces the pending callback under the same name. The stale timer is
    // destroyed exactly when the state becomes acceptable to it, so the only window it can fire in
    // is one this guard rejects.
    const auto state = this->key_extraction_ctx_.state;
    if (state != pairing_responder::ResponderState::EXTRACTED &&
        state != pairing_responder::ResponderState::SENT_NODE_VERIFY_RESP)
      return;
    ESP_LOGI(detail::TAG, "Key extraction: post-extraction grace window elapsed (stage=%s). Disarming.",
             pairing_responder::responder_stage_name(state));
    this->set_armed(false);
  });
  this->key_extraction_hold_deadline_ms_ = millis() + KEY_EXTRACTION_POST_EXTRACT_GRACE_MS;
}
 
// TODO(hardware-verify): an authenticated read-back to the foreign hub using the recovered key,
// to confirm it before trusting it. recover_system_key_from_transfer()'s IV-derivation formula is
// independently pinned against externally-captured known-answer key transfers (see the file-level
// @warning above), but nothing here confirms this specific extraction talks to a real third-party
// hub correctly — the single highest-risk unverified piece of this feature. That read-back subflow
// is deliberately not implemented: doubling the protocol-speculation surface for a feature that
// already ships marked experimental is not worth it for a second unverified vendor-hub
// interaction. The key is still always printed (gating it on an equally-unverified secondary check
// risks hiding a correct key), but the log below says so.
void KeyExtractionResponder::log_result_() {
  // Deliberate, explicit exception to redaction.h's masking — see that file and README.md's
  // "Reporting Unsupported Devices" section, which already warns about pairing logs and the
  // shared TRANSFER_KEY in almost identical terms. Do NOT route this through the generic
  // frame-log helpers (log_frame()/log_component_capture()); those must keep masking 0x32.
  //
  // Logged line-by-line via log_multiline_result(), not as one ESP_LOGW("%s", ...) call: a single
  // call silently truncates at ESPHome's 512-byte log buffer -- see that function's doxygen
  // (log_helpers.h) for the root cause, and build_oneway_adoption_report()'s caller for the
  // identical reasoning on the 1W path.
  ESP_LOGW(detail::TAG, "========================================");
  detail::log_multiline_result(detail::TAG, /*is_warning=*/true, /*prefix=*/"",
                               detail::build_key_extraction_report(this->key_extraction_ctx_.hub_node_id,
                                                                   this->key_extraction_ctx_.recovered_key));
  ESP_LOGW(detail::TAG, "========================================");
}
 
}  // namespace home_io_control
}  // namespace esphome