@mikrojs/firmware 0.18.0 → 0.18.1

package/components/mikrojs/CMakeLists.txt

@@ -69,6 +69,7 @@ idf_component_register(
     "${MIK_SRC_DIR}/mik_sys.cpp"
     "${MIK_SRC_DIR}/mik_text_encoding.cpp"
     "${MIK_SRC_DIR}/mik_cbor.cpp"
+    "${MIK_SRC_DIR}/mik_sys_codec.cpp"
     "${MIK_SRC_DIR}/mik_result.cpp"
     "${MIK_SRC_DIR}/mik_udp.cpp"
     "${MIK_SRC_DIR}/mik_observable.cpp"
@@ -97,6 +98,15 @@ idf_component_register(
     "mik_pwm.cpp"
     "mik_nvs_kv.cpp"
     "mik_ota.cpp"
+    # The OTA check-in client and config reader: policy, state machine and slot
+    # store in the portable library, platform seam and JS surface here.
+    "${MIK_SRC_DIR}/mik_ota_policy.cpp"
+    "${MIK_SRC_DIR}/mik_ota_slots.cpp"
+    "${MIK_SRC_DIR}/mik_ota_config.cpp"
+    "${MIK_SRC_DIR}/mik_ota_js_hooks.cpp"
+    "${MIK_SRC_DIR}/mik_ota_client.cpp"
+    "mik_ota_env.cpp"
+    "mik_ota_client_module.cpp"
     "mik_recovery.cpp"
     "mik_rtc.cpp"
     "mik_serial_io.cpp"
@@ -182,7 +192,8 @@ include("${MIK_BYTECODE_CMAKE}")
 
 # Force linker to include self-registering native modules
 set(_MIK_MODULES cbor pin i2c i2s spi http http_server wifi rtc nvs_kv sntp sleep neopixel pwm uart ota)
-set(_MIK_BYTECODE_MODULES abort cbor env result schema fs http/helpers http/request http/server i2c i2s kv/nvs kv/rtc kv/shared module neopixel observable observable/lazy observable/operators ota ota/client pin pwm reader sleep spi sntp stdio stream sys test uart udp wifi)
+list(APPEND _MIK_MODULES ota_client)
+set(_MIK_BYTECODE_MODULES abort cbor env result schema fs http/helpers http/request http/server i2c i2s kv/nvs kv/rtc kv/shared module neopixel observable observable/lazy observable/operators ota ota/client ota/config pin pwm reader sleep spi sntp stdio stream sys test uart udp wifi)
 if(CONFIG_BT_ENABLED)
     list(APPEND _MIK_MODULES ble)
     list(APPEND _MIK_BYTECODE_MODULES ble)

package/components/mikrojs/include/mik_http_internal.h

@@ -48,10 +48,30 @@ struct MIKHttpQueuedMsg {
     MIKHttpQueuedMsg* next;
 };
 
+/* A C consumer of one request's messages, used when the requester is native
+ * code rather than JS — the OTA client. Set on a pending entry, it replaces the
+ * two promises entirely: nothing on that entry is ever handed to JS.
+ *
+ * Callbacks run from mik__http_consume, i.e. on the JS loop thread, never on the
+ * HTTP background task. `done` fires exactly once and is terminal. */
+struct MIKHttpNativeSink {
+    void (*headers)(void* user_data, int status);
+    void (*data)(void* user_data, const uint8_t* data, size_t len);
+    void (*done)(void* user_data, int status, const char* error_msg);
+    void* user_data;
+};
+
 struct MIKHttpPending {
     uint32_t id;
     std::atomic<bool>* cancelled;
     bool js_cancelled;
+    /* Native requests only: when this request stops being worth waiting for,
+     * in esp_timer microseconds. 0 means no deadline. */
+    int64_t deadline_us;
+
+    /* `done == nullptr` means this is a JS request and the promises below are
+     * live. Otherwise messages route to the sink and the promises are unused. */
+    MIKHttpNativeSink sink;
 
     MIKPromise headers_promise;
     bool headers_resolved;
@@ -63,6 +83,33 @@ struct MIKHttpPending {
     MIKHttpQueuedMsg* queue_tail;
 };
 
+/* One native request, as the OTA client describes it. Strings and buffers are
+ * borrowed for the duration of the start call only; the module copies them. */
+struct MIKHttpNativeRequest {
+    const char* url;
+    const char* method;
+    const char* const* header_keys;
+    const char* const* header_values;
+    size_t header_count;
+    const uint8_t* body;
+    size_t body_len;
+    /* Whole-request bound, milliseconds; 0 for none. The 10s socket timeout
+     * only bounds a single read, so a server that dribbles is otherwise
+     * unbounded and holds the task and its TLS session indefinitely. */
+    uint32_t timeout_ms;
+};
+
+/* Bring the transport up for a native consumer that never imports the JS module.
+ * Must be called before mik__http_start_native. Idempotent. */
+void mik__http_ensure_native(struct JSContext* ctx);
+
+/* Start a request whose messages go to `sink`. Returns the request id, or 0 when
+ * it could not be started. Defined in mik_http.cpp. */
+uint32_t mik__http_start_native(struct MIKRuntime* rt, const MIKHttpNativeRequest* req,
+                                const MIKHttpNativeSink* sink);
+/* Abandon a native request. No further sink callbacks fire for it. */
+void mik__http_cancel_native(struct MIKRuntime* rt, uint32_t id);
+
 /* Ceilings shared with the test harness. Must match the #defines in
  * mik_http.cpp. */
 #define MIK_HTTP_MAX_PENDING 4

package/components/mikrojs/include/mik_ota_native.h

@@ -0,0 +1,19 @@
+/* Internal wiring for the native OTA client (mikro/ota/client backed by C).
+ * Not part of the public ESP API: only the OTA module and its env implementation
+ * include this. */
+#pragma once
+
+#include "mikrojs/ota_env.h"
+
+/* Fill the install-op slots with mik_ota.cpp's staging machinery — the same
+ * cores the native:mikro/ota JS bindings call. */
+void mik__ota_fill_install_ops(MIKOtaEnv* env);
+
+/* The OTA environment for this runtime, fully populated (install ops, kv, HTTP,
+ * identity, clock). Valid until the runtime is freed. `rt` is needed because the
+ * HTTP seam borrows the http module's task and queue, which live per runtime.
+ *
+ * `bytecode_version` cannot be derived without a JSContext, so it is passed in
+ * from the module init that has one. */
+struct MIKRuntime;
+const MIKOtaEnv* mik__ota_env_for(struct MIKRuntime* rt, int bytecode_version);

package/components/mikrojs/mik_config.cpp

@@ -223,26 +223,47 @@ bool mik__handle_config_command(MIKReplTransport* transport, uint8_t cmd_type,
             uint16_t val_len = vl[0] | (vl[1] << 8);
             consumed += 2;
 
-            char value[512];
-            if (val_len >= sizeof(value) || consumed + (uint32_t)val_len > payload_len) {
+            /* Sized to carry a 4 KiB config document plus its {version, doc}
+             * envelope (a config seed is the largest value this path sees);
+             * mirrored as KV_VALUE_MAX_BYTES in the CLI/sim protocol — keep
+             * the two in sync. Heap, not stack: the value and its CBOR blob
+             * together would not fit a task stack. */
+            constexpr uint32_t kValueMax = 4608;
+            if (val_len >= kValueMax || consumed + (uint32_t)val_len > payload_len) {
                 mik__proto_drain(transport, payload_len - consumed);
                 mik__proto_send_err(transport, "value too long");
                 return true;
             }
-            if (!mik__proto_read_exact(transport, value, val_len)) return false;
+            char* value = (char*)malloc((size_t)val_len + 1);
+            uint8_t* blob = (uint8_t*)malloc((size_t)val_len + 8);
+            if (value == NULL || blob == NULL) {
+                free(value);
+                free(blob);
+                mik__proto_drain(transport, payload_len - consumed);
+                mik__proto_send_err(transport, "out of memory");
+                return true;
+            }
+            if (!mik__proto_read_exact(transport, value, val_len)) {
+                free(value);
+                free(blob);
+                return false;
+            }
             value[val_len] = '\0';
             consumed += val_len;
             if (payload_len > consumed) mik__proto_drain(transport, payload_len - consumed);
 
             if (key_len == 0 || key_len > 15) {
+                free(value);
+                free(blob);
                 mik__proto_send_err(transport, "key exceeds NVS 15-char limit");
                 return true;
             }
 
             nanocbor_encoder_t enc;
-            uint8_t blob[sizeof(value) + 4];
-            nanocbor_encoder_init(&enc, blob, sizeof(blob));
+            nanocbor_encoder_init(&enc, blob, (size_t)val_len + 8);
             if (nanocbor_put_tstrn(&enc, value, val_len) < 0) {
+                free(value);
+                free(blob);
                 mik__proto_send_err(transport, "cbor encode failed");
                 return true;
             }
@@ -255,6 +276,8 @@ bool mik__handle_config_command(MIKReplTransport* transport, uint8_t cmd_type,
                 if (err == ESP_OK) err = nvs_commit(handle);
                 nvs_close(handle);
             }
+            free(value);
+            free(blob);
             if (err == ESP_OK) {
                 mik__proto_send_ok(transport);
             } else {

package/components/mikrojs/mik_http.cpp

@@ -3,9 +3,12 @@
 
 #include "esp_crt_bundle.h"
 #include "esp_event.h"
+#include "esp_heap_caps.h"
 #include "esp_http_client.h"
 #include "esp_log.h"
 #include "esp_netif.h"
+#include "esp_system.h"
+#include "esp_timer.h"
 #include "freertos/FreeRTOS.h"
 #include "freertos/queue.h"
 #include "freertos/semphr.h"
@@ -162,17 +165,19 @@ static bool mik__task_cancelled(MIKHttpTaskArgs* args) {
  * fragmentation that is NOT a leak in this code — it's mbedTLS scatter-alloc
  * during handshake plus lwIP holding socket TCBs in TIME_WAIT for 2*MSL
  * (CONFIG_LWIP_TCP_MSL). Both reclaim over time; sysFree recovers after the
- * TIME_WAIT window. The UAF fix in commit [UAF fix] removed the real bug;
- * remaining drift is expected platform behavior, not worth chasing without
- * a broader evaluation of CONFIG_MBEDTLS_DYNAMIC_BUFFER, session tickets,
- * or moving to a custom esp-tls-direct HTTP implementation. */
+ * TIME_WAIT window. The UAF fix in commit [UAF fix] removed the real bug.
+ * CONFIG_MBEDTLS_DYNAMIC_BUFFER and a shorter MSL are now both in
+ * sdkconfig.defaults.
+ * Still unexplored: session reuse, or an esp-tls-direct implementation. */
 static void mik__http_task(void* arg) {
     auto* args = static_cast<MIKHttpTaskArgs*>(arg);
 
     MIKHttpEventData event_data = {};
     bool headers_posted = false;
     bool cancelled = false;
-    char error_buf[256] = {0};
+    /* 384: a build URL (64-hex checksum path) plus full TLS detail and heap
+     * figures overruns 256, and truncation eats the trailing heap figures. */
+    char error_buf[384] = {0};
     bool have_error = false;
 
     esp_http_client_config_t config = {};
@@ -188,6 +193,13 @@ static void mik__http_task(void* arg) {
     config.event_handler = mik__http_event_handler;
     config.user_data = &event_data;
     config.crt_bundle_attach = esp_crt_bundle_attach;
+    // No HTTP_TLS_DYN_BUF_RX_STATIC: converting the RX buffer to a static
+    // ~16.6 KB allocation right after the handshake demands a contiguous
+    // block exactly when the heap is most fragmented, and the failure is
+    // silent (esp-tls records no error code and its log line compiles out) —
+    // observed live on a c6 as a connect failure with empty TLS slots. For
+    // check-in-sized exchanges dynamic RX allocates per record (~2 KB), which
+    // is strictly lighter than pinning the full buffer.
 
     esp_http_client_handle_t client = esp_http_client_init(&config);
     if (!client) {
@@ -225,12 +237,18 @@ static void mik__http_task(void* arg) {
              * keep the plain connect error (no heap-level guessing). */
             bool out_of_memory = err == ESP_ERR_NO_MEM || last_tls_err == ESP_ERR_NO_MEM ||
                                  tls_code == 0x008d || tls_code == 0x7f00;
+            /* Heap figures settle ambiguous codes: -0x3000 (X509 fatal) is
+             * both "CA not in bundle" and "calloc failed in the bundle verify
+             * callback" — a starved largest block names the second. */
             snprintf(error_buf, sizeof(error_buf),
                      "fetch failed: %s %s (%s, errno=%d, "
-                     "esp_tls=%s, mbedtls=-0x%04x, flags=0x%x)",
+                     "esp_tls=%s, mbedtls=-0x%04x, flags=0x%x, "
+                     "sysFree=%u, largestBlock=%u)",
                      out_of_memory ? "out of memory connecting to" : "could not connect to",
                      args->req.url, esp_err_to_name(err), sock_errno,
-                     esp_err_to_name(last_tls_err), tls_code, tls_flags);
+                     esp_err_to_name(last_tls_err), tls_code, tls_flags,
+                     static_cast<unsigned>(esp_get_free_heap_size()),
+                     static_cast<unsigned>(heap_caps_get_largest_free_block(MALLOC_CAP_8BIT)));
             have_error = true;
             goto cleanup;
         }
@@ -476,6 +494,104 @@ static bool mik__enqueue_msg(MIKHttpPending* p, const MIKHttpMsg& m) {
     return true;
 }
 
+/* ── Native requests ───────────────────────────────────────────────── */
+/* Native code (the OTA client) shares this module's task, TLS setup, inflight
+ * ceiling and chunk budget rather than standing up a second esp_http_client
+ * path: one TLS client on the device is what keeps the handshake heap spike
+ * bounded and tuned in one place. */
+
+uint32_t mik__http_start_native(MIKRuntime* rt, const MIKHttpNativeRequest* spec,
+                                const MIKHttpNativeSink* sink) {
+    if (!rt || !spec || !sink || !sink->done) return 0;
+    if (mik__http_slot < 0 || !mik__http_st(rt)) return 0;
+    MIKHttpState* state = mik__http_st(rt);
+    if (state->pending_count >= MIK_HTTP_MAX_PENDING) return 0;
+
+    MIKHttpRequest req = {};
+    req.url = strdup(spec->url ? spec->url : "");
+    if (!req.url) return 0;
+    req.method = mik__method_from_string(spec->method);
+
+    if (spec->body && spec->body_len > 0) {
+        req.body = static_cast<uint8_t*>(malloc(spec->body_len));
+        if (!req.body) {
+            mik__http_free_request(&req);
+            return 0;
+        }
+        memcpy(req.body, spec->body, spec->body_len);
+        req.body_len = spec->body_len;
+    }
+
+    if (spec->header_count > 0) {
+        req.headers =
+            static_cast<MIKHttpHeader*>(calloc(spec->header_count, sizeof(MIKHttpHeader)));
+        if (!req.headers) {
+            mik__http_free_request(&req);
+            return 0;
+        }
+        for (size_t i = 0; i < spec->header_count; i++) {
+            char* key = strdup(spec->header_keys[i]);
+            char* value = strdup(spec->header_values[i]);
+            if (!key || !value) {
+                free(key);
+                free(value);
+                mik__http_free_request(&req);
+                return 0;
+            }
+            req.headers[req.header_count].key = key;
+            req.headers[req.header_count].value = value;
+            req.header_count++;
+        }
+    }
+
+    MIKHttpPending pending = {};
+    pending.id = state->next_id++;
+    pending.sink = *sink;
+    pending.deadline_us =
+        spec->timeout_ms > 0
+            ? esp_timer_get_time() + static_cast<int64_t>(spec->timeout_ms) * 1000
+            : 0;
+
+    auto* cancelled = new std::atomic<bool>(false);
+    pending.cancelled = cancelled;
+
+    auto* task_args = static_cast<MIKHttpTaskArgs*>(malloc(sizeof(MIKHttpTaskArgs)));
+    if (!task_args) {
+        mik__http_free_request(&req);
+        delete cancelled;
+        return 0;
+    }
+    task_args->id = pending.id;
+    task_args->req = req;
+    task_args->result_queue = state->result_queue;
+    task_args->inflight = state->inflight;
+    task_args->cancelled = cancelled;
+
+    if (xTaskCreate(mik__http_task, "mik_http", MIK_HTTP_TASK_STACK_SIZE, task_args,
+                    tskIDLE_PRIORITY + 1, nullptr) != pdPASS) {
+        mik__http_free_request(&task_args->req);
+        free(task_args);
+        delete cancelled;
+        return 0;
+    }
+
+    state->pending[state->pending_count++] = pending;
+    return pending.id;
+}
+
+void mik__http_cancel_native(MIKRuntime* rt, uint32_t id) {
+    if (!rt || mik__http_slot < 0 || !mik__http_st(rt)) return;
+    MIKHttpState* state = mik__http_st(rt);
+    MIKHttpPending* p = mik__find_pending(state, id);
+    if (!p || !p->sink.done) return;
+    if (p->cancelled) p->cancelled->store(true, std::memory_order_relaxed);
+    /* Stop delivering entirely: the task still emits a terminal message, which
+     * the consume loop then drops along with the pending entry. */
+    p->sink.headers = nullptr;
+    p->sink.data = nullptr;
+    p->js_cancelled = true;
+}
+
 static JSValue mik__http_request(JSContext* ctx, JSValue this_val, int argc, JSValue* argv) {
     MIKRuntime* mik_rt = MIK_GetRuntime(ctx);
     CHECK_NOT_NULL(mik_rt);
@@ -774,6 +890,18 @@ static void mik__ensure_netif_initialized() {
     }
 }
 
+/* Bring the transport up for a native consumer — the OTA client, which uses this
+ * module's task and queue from C rather than importing it from JS.
+ *
+ * Without this the module is only ever initialized by an import, so a firmware
+ * whose only HTTP user is native would have no slot, no state and no loop
+ * consumer: every request would fail to start and no response would ever be
+ * drained. Idempotent, and safe either side of a JS import — the loop consumer
+ * registration de-duplicates. */
+void mik__http_ensure_native(JSContext* ctx);
+void mik__http_consume(JSContext* ctx);
+void mik__http_destroy(JSContext* ctx);
+
 static void mik__http_ensure_initialized(JSContext* ctx) {
     MIKRuntime* mik_rt = MIK_GetRuntime(ctx);
     CHECK_NOT_NULL(mik_rt);
@@ -792,6 +920,14 @@ static void mik__http_ensure_initialized(JSContext* ctx) {
     mik__http_st(mik_rt) = state;
 }
 
+void mik__http_ensure_native(JSContext* ctx) {
+    MIKRuntime* mik_rt = MIK_GetRuntime(ctx);
+    if (!mik_rt) return;
+    if (mik__http_slot < 0) mik__http_slot = MIK_AllocModuleSlot(mik_rt);
+    mik__http_ensure_initialized(ctx);
+    MIK_RegisterLoopConsumer(mik_rt, mik__http_consume, mik__http_destroy);
+}
+
 static int mik__http_module_init(JSContext* ctx, JSModuleDef* m) {
     mik__http_ensure_initialized(ctx);
     JS_SetModuleExport(ctx, m, "request",
@@ -806,7 +942,9 @@ static int mik__http_module_init(JSContext* ctx, JSModuleDef* m) {
 
 static JSModuleDef* mik__http_init(JSContext* ctx) {
     MIKRuntime* mik_rt = MIK_GetRuntime(ctx);
-    mik__http_slot = MIK_AllocModuleSlot(mik_rt);
+    /* The slot may already exist: a native consumer can bring the transport up
+     * before anything imports the JS module. */
+    if (mik__http_slot < 0) mik__http_slot = MIK_AllocModuleSlot(mik_rt);
 
     JSModuleDef* m = JS_NewCModule(ctx, "native:mikro/http", mik__http_module_init);
     if (!m) return nullptr;
@@ -825,6 +963,26 @@ void mik__http_consume(JSContext* ctx) {
     if (!mik__http_st(mik_rt)) return;
 
     MIKHttpState* state = mik__http_st(mik_rt);
+
+    /* Time out native requests before draining, so a request whose deadline
+     * passed reports it even when the transport has gone quiet. The socket
+     * timeout bounds one read; this bounds the request. */
+    int64_t now_us = esp_timer_get_time();
+    for (size_t i = 0; i < state->pending_count; i++) {
+        MIKHttpPending* p = &state->pending[i];
+        if (!p->sink.done || p->deadline_us == 0 || now_us < p->deadline_us) continue;
+        MIKHttpNativeSink sink = p->sink;
+        /* Stop delivering and let the task's terminal message drop the entry;
+         * the sink hears about it once, here. */
+        p->sink.headers = nullptr;
+        p->sink.data = nullptr;
+        p->sink.done = nullptr;
+        p->js_cancelled = true;
+        p->deadline_us = 0;
+        if (p->cancelled) p->cancelled->store(true, std::memory_order_relaxed);
+        sink.done(sink.user_data, 0, "timeout");
+    }
+
     MIKHttpMsg msg;
     while (xQueueReceive(state->result_queue, &msg, 0) == pdTRUE) {
         MIKHttpPending* p = mik__find_pending(state, msg.id);
@@ -841,6 +999,38 @@ void mik__http_consume(JSContext* ctx) {
             continue;
         }
 
+        if (p->sink.done) {
+            /* Native consumer: hand the message over and free the payload here,
+             * since nothing is queued for a later JS read. */
+            size_t idx = static_cast<size_t>(p - state->pending);
+            if (msg.kind == MIK_HTTP_MSG_HEADERS) {
+                if (p->sink.headers) p->sink.headers(p->sink.user_data, msg.status);
+                mik__http_free_headers(msg.headers, msg.header_count);
+            } else if (msg.kind == MIK_HTTP_MSG_CHUNK) {
+                if (p->sink.data) p->sink.data(p->sink.user_data, msg.chunk_data, msg.chunk_len);
+                xSemaphoreGive(state->inflight);
+                free(msg.chunk_data);
+            } else {
+                const char* error = msg.kind == MIK_HTTP_MSG_ERROR
+                                        ? (msg.error_message ? msg.error_message : "HTTP error")
+                                        : nullptr;
+                /* A cancelled request never calls back, whatever the task ended
+                 * up reporting. The consumer cancels on its way out, so calling
+                 * `done` here would reach a destroyed object. */
+                if (!p->js_cancelled) {
+                    MIKHttpNativeSink sink = p->sink;
+                    /* Drop first: the callback may start the next request, and
+                     * that would reuse this slot. */
+                    mik__pending_drop(state, idx);
+                    sink.done(sink.user_data, msg.status, error);
+                } else {
+                    mik__pending_drop(state, idx);
+                }
+                if (msg.kind == MIK_HTTP_MSG_ERROR) free(msg.error_message);
+            }
+            continue;
+        }
+
         if (msg.kind == MIK_HTTP_MSG_HEADERS) {
             JSValue v =
                 mik__headers_result_ok(ctx, msg.status, msg.headers, msg.header_count);
@@ -966,6 +1156,7 @@ void mik__http_destroy(JSContext* ctx) {
             mik__free_queued_msg(m);
             m = next;
         }
+        if (p->sink.done) continue;  /* native pending: no promises to free */
         if (!p->headers_resolved) MIK_FreePromise(ctx, &p->headers_promise);
         if (p->next_promise_active) MIK_FreePromise(ctx, &p->next_promise);
     }

package/components/mikrojs/mik_nvs_kv.cpp

@@ -107,20 +107,36 @@ static JSValue mik__nvs_kv_get(JSContext* ctx, JSValue this_val, int argc, JSVal
         return JS_UNDEFINED;
     }
 
+    /* Absence is the only silent outcome: a missing namespace (nothing ever
+     * stored) or a missing key reads as undefined. Every other failure throws,
+     * so a read starved by heap pressure (nvs_open allocates its handle) is
+     * never mistaken for "not stored". */
     nvs_handle_t handle;
-    if (nvs_open(mik__nvs_ns(magic), NVS_READONLY, &handle) != ESP_OK) {
+    esp_err_t err = nvs_open(mik__nvs_ns(magic), NVS_READONLY, &handle);
+    if (err == ESP_ERR_NVS_NOT_FOUND) {
         JS_FreeCString(ctx, key);
         return JS_UNDEFINED;
     }
+    if (err != ESP_OK) {
+        JS_ThrowPlainError(ctx, "nvs open failed reading \"%s\": %s", key, esp_err_to_name(err));
+        JS_FreeCString(ctx, key);
+        return JS_EXCEPTION;
+    }
 
     /* Query size first */
     size_t len = 0;
-    esp_err_t err = nvs_get_blob(handle, key, nullptr, &len);
-    if (err != ESP_OK || len == 0) {
+    err = nvs_get_blob(handle, key, nullptr, &len);
+    if (err == ESP_ERR_NVS_NOT_FOUND || (err == ESP_OK && len == 0)) {
         JS_FreeCString(ctx, key);
         nvs_close(handle);
         return JS_UNDEFINED;
     }
+    if (err != ESP_OK) {
+        JS_ThrowPlainError(ctx, "nvs read failed for \"%s\": %s", key, esp_err_to_name(err));
+        JS_FreeCString(ctx, key);
+        nvs_close(handle);
+        return JS_EXCEPTION;
+    }
 
     /* Read blob */
     auto* buf = static_cast<uint8_t*>(js_malloc(ctx, len));
@@ -136,7 +152,7 @@ static JSValue mik__nvs_kv_get(JSContext* ctx, JSValue this_val, int argc, JSVal
 
     if (err != ESP_OK) {
         js_free(ctx, buf);
-        return JS_UNDEFINED;
+        return JS_ThrowPlainError(ctx, "nvs read failed: %s", esp_err_to_name(err));
     }
 
     /* Decode CBOR */
@@ -145,7 +161,14 @@ static JSValue mik__nvs_kv_get(JSContext* ctx, JSValue this_val, int argc, JSVal
     JSValue result = mik__cbor_decode_value(ctx, &decoder, 0);
     js_free(ctx, buf);
 
-    if (JS_IsException(result)) return JS_UNDEFINED;
+    /* A stored blob that does not decode is corruption, not absence. The
+     * decoder signals malformed input by value with no pending exception
+     * (only allocation failures inside it carry one). TypeError marks it as
+     * corruption: the kv layer deletes and heals on TypeError only, never on
+     * the transient (plain Error) failures above. */
+    if (JS_IsException(result) && !JS_HasException(ctx)) {
+        return JS_ThrowTypeError(ctx, "stored nvs value is not valid CBOR");
+    }
     return result;
 }