feat(ota): add authenticated firmware update workflow

- report firmware versions at startup and every six hours with a fresh device JWT
- support optional HMAC headers and retry once after authorization rejection
- handle forced and confirmed updates through managed OTA state
- stream images to the inactive partition and verify size, SHA-256, and format
- coordinate OTA HTTPS activity with voice teardown and restoration
- confirm pending images and expose configuration, status, and integration docs

components/domain/include/domain.h

@@ -248,6 +248,7 @@ void domain_runtime_read_device_identity(char *device_id,
                                          size_t device_id_len,
                                          char *serial_number,
                                          size_t serial_number_len);
+esp_err_t domain_runtime_read_firmware_version(char *out, size_t out_len);
 
 esp_err_t domain_runtime_write_device_identity(const char *device_id, const char *serial_number);
 
@@ -404,6 +405,64 @@ esp_err_t domain_runtime_post_json(const char *url,
                                    size_t *out_response_body_len,
                                    int *out_status);
 
+#define DOMAIN_OTA_VERSION_MAX_LEN 32
+#define DOMAIN_OTA_URL_MAX_LEN 2048
+#define DOMAIN_OTA_SHA256_HEX_LEN 64
+
+typedef enum {
+    DOMAIN_OTA_REPORT_NO_UPDATE = 0,
+    DOMAIN_OTA_REPORT_UPDATE_AVAILABLE,
+    DOMAIN_OTA_REPORT_SERVER_ERROR,
+} domain_ota_report_outcome_t;
+
+typedef struct {
+    const char *report_url;
+    const char *device_id;
+    const char *serial_number;
+    const char *current_version;
+    const char *device_jwt;
+    const char *internal_auth_secret;
+    int timeout_ms;
+} domain_ota_report_request_t;
+
+typedef struct {
+    char version[DOMAIN_OTA_VERSION_MAX_LEN];
+    char url[DOMAIN_OTA_URL_MAX_LEN];
+    char sha256[DOMAIN_OTA_SHA256_HEX_LEN + 1];
+    uint64_t size_bytes;
+    bool forced;
+    bool confirmed;
+} domain_ota_firmware_t;
+
+typedef struct {
+    domain_ota_report_outcome_t outcome;
+    int http_status;
+    int business_code;
+    domain_ota_firmware_t firmware;
+} domain_ota_report_response_t;
+
+typedef struct {
+    uint32_t free_internal;
+    uint32_t largest_internal;
+    uint32_t largest_dma;
+} domain_ota_memory_headroom_t;
+
+typedef void (*domain_ota_progress_callback_t)(uint64_t bytes_received,
+                                               uint64_t total_bytes,
+                                               void *user_data);
+typedef bool (*domain_ota_cancel_callback_t)(void *user_data);
+
+esp_err_t domain_runtime_ota_report(const domain_ota_report_request_t *request,
+                                    domain_ota_report_response_t *response);
+esp_err_t domain_runtime_ota_install(const domain_ota_firmware_t *firmware,
+                                     int timeout_ms,
+                                     domain_ota_progress_callback_t progress_cb,
+                                     domain_ota_cancel_callback_t cancel_cb,
+                                     void *user_data);
+esp_err_t domain_runtime_ota_confirm_running_image(void);
+esp_err_t domain_runtime_ota_get_memory_headroom(domain_ota_memory_headroom_t *out);
+void domain_runtime_restart(void);
+
 /**
  * @brief Console (UART) line-transport primitives, bridged to the platform.
  *