@esp-vision/device-core 0.6.0 → 0.7.0

package/src/firmware_flash.js

@@ -1,6 +1,11 @@
 // SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
 // SPDX-License-Identifier: Apache-2.0
 // ROM flashing is separate from DeviceSession and its EV-MUX v4 owner protocol.
+import { planInstallFilesystemErase } from './firmware_partitions.js'
+
+function checkAbort(signal) {
+  if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : Object.assign(new Error('Firmware operation cancelled'), { name: 'AbortError' })
+}
 export async function firmwareSha256(bytes) {
   const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes)
   return Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, '0')).join('')
@@ -35,45 +40,68 @@ export async function validateFirmwareImage(image, bytes, { mode = 'update' } =
 
 /** Loader injected by the browser host; no Web Serial or ROM protocol duplicated. */
 export class FirmwareFlashSession {
-  constructor(loader, image, { reset = () => loader.hardReset(), mode = 'update' } = {}) {
+  #image
+  #mode
+  #filesystem
+  #signal
+
+  constructor(loader, image, { reset = () => loader.hardReset(), mode = 'update', signal } = {}) {
     this.mode = firmwareMode(mode)
     this.loader = loader
     this.reset = reset
     this.image = image
     this.state = 'idle'
     this.stub = null
+    this.#signal = signal
   }
 
   async connect(bytes) {
     if (this.state !== 'idle') throw new Error('Firmware loader is already in use')
     this.state = 'connecting'
     try {
-      await validateFirmwareImage(this.image, bytes, { mode: this.mode })
+      checkAbort(this.#signal)
+      // Keep qualification independent of caller mutations during callbacks or
+      // asynchronous ROM operations. Public metadata is not an erase authority.
+      const image = this.#image = structuredClone(this.image)
+      const mode = this.#mode = firmwareMode(this.mode)
+      const payload = bytes instanceof Uint8Array ? new Uint8Array(bytes) : bytes
+      await validateFirmwareImage(image, payload, { mode })
+      this.#filesystem = mode === 'install' ? planInstallFilesystemErase(image, payload) : null
+      checkAbort(this.#signal)
       await this.loader.initialize()
-      const revisionMatches = this.image.chipRevision !== undefined ? this.loader.chipRevision === this.image.chipRevision
-        : Number.isInteger(this.image.chipRevisionMin) && Number.isInteger(this.image.chipRevisionMax) && this.loader.chipRevision >= this.image.chipRevisionMin && this.loader.chipRevision <= this.image.chipRevisionMax
-      if (this.loader.chipFamily !== this.image.chipFamily || !revisionMatches) {
+      checkAbort(this.#signal)
+      const revisionMatches = image.chipRevision !== undefined ? this.loader.chipRevision === image.chipRevision
+        : Number.isInteger(image.chipRevisionMin) && Number.isInteger(image.chipRevisionMax) && this.loader.chipRevision >= image.chipRevisionMin && this.loader.chipRevision <= image.chipRevisionMax
+      if (this.loader.chipFamily !== image.chipFamily || !Number.isInteger(this.loader.chipRevision) || !revisionMatches) {
         throw new Error('Chip or silicon revision does not match the approved board firmware')
       }
       const security = await this.loader.getSecurityInfo()
-      if (!Number.isSafeInteger(security.flags) || !Number.isSafeInteger(security.flashCryptCnt)) {
+      checkAbort(this.#signal)
+      if (!Number.isSafeInteger(security.flags) || security.flags < 0 || security.flags > 0xffffffff
+          || !Number.isSafeInteger(security.flashCryptCnt) || security.flashCryptCnt < 0 || security.flashCryptCnt > 0xffffffff) {
         throw new Error('Cannot qualify the device ROM security mode')
       }
       const encrypted = security.flashCryptCnt.toString(2).replace(/0/g, '').length % 2 === 1
-      if ((security.flags & 1) !== 0 || encrypted) throw new Error('Secure boot or encrypted devices require their signed flashing workflow')
+      if ((security.flags & 5) !== 0 || encrypted) throw new Error('Secure boot, secure download or encrypted devices require their signed flashing workflow')
       this.stub = await this.loader.runStub(true)
-      if (this.mode === 'install') {
+      checkAbort(this.#signal)
+      if (mode === 'install') {
         // JEDEC capacity byte encodes log2(bytes); shared with browser loaders.
         if (typeof this.stub.flashId !== 'function') throw new Error('Installation requires ROM flash capacity detection (flashId)')
         const id = await this.stub.flashId()
+        checkAbort(this.#signal)
         const capacity = (id >>> 16) & 0xff
         if (!Number.isSafeInteger(id) || id <= 0 || id > 0xffffff || capacity < 18 || capacity > 30
-            || 2 ** capacity < this.image.flashSize) throw new Error('Detected flash is unknown or smaller than the approved complete image layout')
+            || 2 ** capacity < image.flashSize) throw new Error('Detected flash is unknown or smaller than the approved complete image layout')
+        if (typeof this.stub.eraseRegion !== 'function' || typeof this.stub.readFlash !== 'function' || typeof this.stub.flashData !== 'function') {
+          throw Object.assign(new Error('Complete installation requires bounded filesystem erase and readback support'), { code: 'FIRMWARE_ERASE_UNSUPPORTED' })
+        }
       } else {
-        const table = this.image.partitionTable
+        const table = image.partitionTable
         const existing = await this.stub.readFlash(table.offset, table.bytes)
         if (await firmwareSha256(existing) !== table.sha256) throw new Error('Partition layout differs; select explicit install mode to replace the layout')
       }
+      checkAbort(this.#signal)
       this.state = 'connected'
     } catch (error) { await this.disconnect(); throw error }
   }
@@ -82,33 +110,63 @@ export class FirmwareFlashSession {
     if (this.state !== 'connected') throw new Error('Connect and validate the device before flashing')
     this.state = 'flashing'
     try {
-      await validateFirmwareImage(this.image, bytes, { mode: this.mode })
-      onPhase(this.mode === 'install' ? 'Installing complete firmware; existing data in the written range will be replaced' : 'Writing application; bootloader, partition table, NVS and user files are preserved')
-      await this.stub.flashData(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength),
-        (written, total) => onProgress(total ? Math.min(80, Math.round(written / total * 80)) : 0), this.image.offset, true)
-      onPhase(this.mode === 'install' ? 'Verifying the complete installation image' : 'Verifying the complete application image')
+      checkAbort(this.#signal)
+      const image = this.#image, install = this.#mode === 'install'
+      const payload = bytes instanceof Uint8Array ? new Uint8Array(bytes) : bytes
+      await validateFirmwareImage(image, payload, { mode: this.#mode })
+      checkAbort(this.#signal)
+      if (install) {
+        const { offset, size } = this.#filesystem
+        onPhase('Erasing internal FAT filesystem; device files will be deleted')
+        checkAbort(this.#signal)
+        // Erase only the range parsed from the qualified image. No whole-chip
+        // erase, backups or automatic recovery/replay are part of installation.
+        await this.stub.eraseRegion(offset, size)
+        checkAbort(this.#signal)
+        onPhase('Verifying the erased internal FAT filesystem')
+        checkAbort(this.#signal)
+        for (let position = 0; position < size; position += 65536) {
+          const count = Math.min(65536, size - position)
+          const chunk = await this.stub.readFlash(offset + position, count, undefined,
+            { chunkSize: 65536, blockSize: 1024, maxInFlight: 1 })
+          checkAbort(this.#signal)
+          if (!(chunk instanceof Uint8Array) || chunk.byteLength !== count || chunk.some(value => value !== 0xff)) {
+            throw Object.assign(new Error('Internal FAT filesystem erase verification failed; keep the device in download mode'), { code: 'FIRMWARE_ERASE_VERIFY_FAILED' })
+          }
+          onProgress(Math.floor(20 * (position + count) / size))
+          checkAbort(this.#signal)
+        }
+      }
+      onPhase(install ? 'Installing complete firmware; internal FAT filesystem cleared' : 'Writing application; bootloader, partition table, NVS and user files are preserved')
+      checkAbort(this.#signal)
+      await this.stub.flashData(payload.buffer.slice(payload.byteOffset, payload.byteOffset + payload.byteLength),
+        (written, total) => onProgress((install ? 20 : 0) + (total ? Math.min(install ? 60 : 80, Math.round(written / total * (install ? 60 : 80))) : 0)), image.offset, true)
+      // Once firmware writing starts, preserve the existing completion policy:
+      // finish verification/reset rather than interrupting a partial image.
+      onPhase(install ? 'Verifying the complete installation image' : 'Verifying the complete application image')
       // maxInFlight is a packet count: one 1 KiB packet bounds USB-JTAG backlog.
-      const readback = new Uint8Array(bytes.byteLength)
-      for (let offset = 0; offset < bytes.byteLength; offset += 65536) {
-        const count = Math.min(65536, bytes.byteLength - offset)
-        const chunk = await this.stub.readFlash(this.image.offset + offset, count, undefined,
+      const readback = new Uint8Array(payload.byteLength)
+      for (let offset = 0; offset < payload.byteLength; offset += 65536) {
+        const count = Math.min(65536, payload.byteLength - offset)
+        const chunk = await this.stub.readFlash(image.offset + offset, count, undefined,
           { chunkSize: 65536, blockSize: 1024, maxInFlight: 1 })
         if (chunk.byteLength !== count) throw new Error('Written firmware readback is incomplete')
         readback.set(chunk, offset)
-        onProgress(80 + Math.floor(20 * (offset + count) / bytes.byteLength))
+        onProgress(80 + Math.min(19, Math.floor(20 * (offset + count) / payload.byteLength)))
       }
-      if (readback.byteLength !== bytes.byteLength || await firmwareSha256(readback) !== this.image.sha256) throw new Error('Written firmware verification failed; keep the device in download mode for recovery')
+      if (await firmwareSha256(readback) !== image.sha256) throw new Error('Written firmware verification failed; keep the device in download mode for recovery')
+      onProgress(100)
       this.state = 'verified'
       try {
-        // P4 software download requests survive a CPU reset. Clear only that
+        // P4/S31 software download requests survive a CPU reset. Clear only that
         // latch, verify all other live fields, then apply the host reset policy.
-        if (this.loader.chipFamily === 0x3280) {
-          const address = 0x50110008, mask = 4
+        if (image.chipFamily === 0x3280 || image.chipFamily === 0x3231) {
+          const address = image.chipFamily === 0x3280 ? 0x50110008 : 0x20700008, mask = 4
           const before = await this.stub.readRegister(address)
-          if (!Number.isInteger(before) || before < 0 || before > 0xffffffff) throw new Error('Invalid P4 system control register')
+          if (!Number.isInteger(before) || before < 0 || before > 0xffffffff) throw new Error('Invalid download system control register')
           if (before & mask) await this.stub.writeRegister(address, 0, mask)
           const after = await this.stub.readRegister(address)
-          if (after !== ((before & ~mask) >>> 0)) throw new Error('P4 normal boot latch verification failed')
+          if (after !== ((before & ~mask) >>> 0)) throw new Error('Normal boot latch verification failed')
         }
         await this.reset()
       }

package/src/firmware_partitions.js

@@ -0,0 +1,57 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import { romMd5 } from './rom_md5.js'
+
+const SECTOR_BYTES = 4096
+const invalid = message => Object.assign(new Error(`Invalid installation partition table: ${message}`), { code: 'FIRMWARE_PARTITION_INVALID' })
+const allFF = bytes => bytes.every(value => value === 0xff)
+
+// Call only after validateFirmwareImage has authenticated the complete image
+// and every declared segment. Never infer an erase range from a host/UI field.
+export function planInstallFilesystemErase(image, bytes) {
+  const table = image.partitionTable
+  if (table.offset % SECTOR_BYTES || table.bytes % 32 || table.bytes > 0xc00) throw invalid('unsupported table bounds')
+  const raw = bytes.subarray(table.offset, table.offset + table.bytes)
+  const view = new DataView(raw.buffer, raw.byteOffset, raw.byteLength)
+  const entries = [], labels = new Set()
+  let digestSeen = false, terminated = false
+  for (let cursor = 0; cursor < raw.length; cursor += 32) {
+    const entry = raw.subarray(cursor, cursor + 32)
+    if (allFF(entry)) {
+      if (!allFF(raw.subarray(cursor))) throw invalid('data after the end marker')
+      terminated = true
+      break
+    }
+    const magic = view.getUint16(cursor, true)
+    if (magic === 0xebeb && !digestSeen) {
+      if (!allFF(entry.subarray(2, 16))) throw invalid('malformed MD5 record')
+      const digest = romMd5(raw.subarray(0, cursor))
+      if (!digest.every((value, index) => value === entry[16 + index])) throw invalid('MD5 mismatch')
+      digestSeen = true
+      continue
+    }
+    if (magic !== 0x50aa || digestSeen) throw invalid('unexpected entry or data after MD5')
+    const offset = view.getUint32(cursor + 4, true), size = view.getUint32(cursor + 8, true)
+    const type = entry[2], subtype = entry[3], flags = view.getUint32(cursor + 28, true)
+    const labelBytes = entry.subarray(12, 28), end = labelBytes.indexOf(0)
+    const label = String.fromCharCode(...labelBytes.subarray(0, end < 0 ? 16 : end))
+    if (!label || labels.has(label) || (end >= 0 && labelBytes.subarray(end).some(value => value !== 0))) throw invalid('empty, duplicate or malformed label')
+    if (offset < table.offset + SECTOR_BYTES || offset % SECTOR_BYTES || !size
+        || offset + size > image.flashSize || (type === 0 && offset % 65536)) throw invalid('unsupported partition bounds')
+    labels.add(label)
+    entries.push({ label, type, subtype, offset, size, flags })
+  }
+  if (!terminated || !entries.length) throw invalid('missing entries or end marker')
+  entries.sort((a, b) => a.offset - b.offset)
+  for (let index = 1; index < entries.length; index++) {
+    if (entries[index].offset < entries[index - 1].offset + entries[index - 1].size) throw invalid('overlapping partitions')
+  }
+  const app = image.application
+  if (!entries.some(entry => entry.type === 0 && entry.offset === app.offset
+      && entry.size === app.partitionSize && app.bytes <= entry.size)) throw invalid('application does not match the approved layout')
+  const fat = entries.find(entry => entry.label === 'ffat')
+  if (!fat) throw Object.assign(new Error('Complete installation requires a declared internal ffat partition'), { code: 'FIRMWARE_FATFS_UNAVAILABLE' })
+  if (fat.type !== 1 || fat.subtype !== 0x81 || fat.flags !== 0 || fat.size % SECTOR_BYTES
+      || fat.offset < Math.ceil(bytes.byteLength / SECTOR_BYTES) * SECTOR_BYTES) throw invalid('ffat is not an unencrypted, writable FAT partition outside the firmware write range')
+  return Object.freeze({ label: fat.label, offset: fat.offset, size: fat.size })
+}

package/src/firmware_updates.js

@@ -5,6 +5,7 @@ import { loadOfficialFirmware } from './firmware_feed.js'
 import { FirmwareFlashSession, validateFirmwareImage, firmwareMode } from './firmware_flash.js'
 import { validateFirmwareRelease as release } from './firmware_release.js'
 import { downloadBytes, MAX_FIRMWARE_BYTES } from './firmware_io.js'
+import { planInstallFilesystemErase } from './firmware_partitions.js'
 
 function record(value, keys, name) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError(`${name} must be an object`)
@@ -79,6 +80,7 @@ export async function updateFirmware(request, connectedIdentity, disconnect) {
     bytes = bytes.slice(source.offset, source.offset + image.bytes)
   }
   await validateFirmwareImage(image, bytes, { mode })
+  if (mode === 'install') planInstallFilesystemErase(image, bytes)
   abort(signal)
   // Validate everything before releasing EV-MUX or acquiring a download port.
   await disconnect()
@@ -87,10 +89,11 @@ export async function updateFirmware(request, connectedIdentity, disconnect) {
   let session
   try {
     abort(signal)
-    session = new FirmwareFlashSession(loader, image, { mode, reset: reset ? () => reset(loader) : undefined })
+    session = new FirmwareFlashSession(loader, image, { mode, signal, reset: reset ? () => reset(loader) : undefined })
     await session.connect(bytes)
     abort(signal)
-    // No interruption after writing starts: finish verification and reset policy.
+    // Erase/erase-verification honor cancellation; once firmware writing starts,
+    // finish verification/reset as before. No uncertain operation is replayed.
     const result = await session.flash(bytes, { onProgress, onPhase })
     return { ...result, version: target.version, board: target.board, reconnected: false }
   } finally {

package/src/node_rom.js

@@ -10,22 +10,22 @@ export function openNodeRom({ port, python = defaultPython, signal } = {}, depen
   if (!port) throw new TypeError('Firmware update requires a local --port')
   const lifecycle = new AbortController()
   signal = signal ? AbortSignal.any([signal, lifecycle.signal]) : lifecycle.signal
-  let child, input, pending, sequence = 0, closed = false, initializing = false, romReady = false
-  const fail = code => Object.assign(new Error(code === 'ESPTOOL_UNAVAILABLE' ? 'Install Python esptool>=5.3,<6 for the built-in flasher' : 'ROM operation failed'), { code })
+  let child, input, pending, sequence = 0, closed = false, initializing = false, romReady = false, stubReady = false
+  const fail = code => Object.assign(new Error(code === 'ESPTOOL_UNAVAILABLE' ? 'Install Python esptool==5.6.0 for the built-in flasher' : 'ROM operation failed'), { code })
   const reject = code => { if (pending) { clearTimeout(pending.timer); pending.reject(fail(code)); pending = null } }
-  function rpc(method, args = []) {
+  function rpc(method, args = [], timeout = 180000) {
     if (closed) return Promise.reject(fail('ROM_CLOSED'))
     if (!child || (method !== 'initialize' && !romReady)) return Promise.reject(fail('ROM_NOT_INITIALIZED'))
     if (pending) return Promise.reject(fail('ROM_BUSY'))
     return new Promise((resolve, rejectPromise) => {
       const id = ++sequence
-      pending = { id, resolve, reject: rejectPromise, timer: setTimeout(() => { reject('ROM_TIMEOUT'); void loader.disconnect() }, 180000) }
+      pending = { id, resolve, reject: rejectPromise, timer: setTimeout(() => { reject('ROM_TIMEOUT'); void loader.disconnect() }, timeout) }
       child.stdin.write(JSON.stringify({ id, method, args }) + '\n', error => { if (error) reject('ROM_IO_FAILED') })
     })
   }
   async function closeProcess() {
     const process = child
-    child = null; romReady = false; reject('ROM_CLOSED'); input?.close(); input = null
+    child = null; romReady = stubReady = false; reject('ROM_CLOSED'); input?.close(); input = null
     if (!process || process.exitCode !== null) return
     await new Promise(resolve => {
       const timer = setTimeout(() => { process.kill(); resolve() }, 2000)
@@ -97,8 +97,50 @@ export function openNodeRom({ port, python = defaultPython, signal } = {}, depen
     },
     flashId: () => rpc('flashId'),
     getSecurityInfo: () => rpc('security'),
-    async runStub() { await rpc('stub'); return loader },
-    async readFlash(offset, bytes) { return new Uint8Array(Buffer.from(await rpc('read', [offset, bytes]), 'base64')) },
+    get IS_STUB() { return romReady && stubReady },
+    async runStub() {
+      stubReady = false
+      try {
+        const result = await rpc('stub')
+        if (result?.stubRunning !== true) throw fail('ROM_STUB_REQUIRED')
+        stubReady = true
+        return loader
+      } catch (error) { await loader.disconnect(); throw error }
+    },
+    async eraseRegion(address, size) {
+      if (!Number.isSafeInteger(address) || address < 0 || address % 4096 !== 0
+          || !Number.isSafeInteger(size) || size <= 0 || size > 0xffffffff || size % 4096 !== 0
+          || address + size > 0x100000000) throw new RangeError('ROM erase requires a positive, sector-aligned 32-bit address range')
+      if (closed) throw fail('ROM_CLOSED')
+      if (!romReady) throw fail('ROM_NOT_INITIALIZED')
+      if (!stubReady) throw fail('ROM_STUB_REQUIRED')
+      const cancelled = () => { reject('CANCELLED'); void loader.disconnect() }
+      signal.addEventListener('abort', cancelled, { once: true })
+      try {
+        signal.throwIfAborted()
+        // esptool 5.6.0 permits 40 seconds per decimal MB. Large FFAT regions
+        // must not inherit the shorter generic RPC timeout.
+        await rpc('eraseRegion', [address, size], Math.max(180000, Math.ceil(size / 1000000 * 40000) + 30000))
+        signal.throwIfAborted()
+        if (closed || !stubReady) throw fail('ROM_CLOSED')
+      } catch (error) { await loader.disconnect(); throw error }
+      finally { signal.removeEventListener('abort', cancelled) }
+    },
+    async readFlash(offset, bytes, progress, options) {
+      if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(bytes) || bytes <= 0 || bytes > 0xffffffff
+          || offset + bytes > 0x100000000) throw new RangeError('ROM read requires a positive 32-bit address range')
+      if (progress !== undefined && typeof progress !== 'function') throw new TypeError('ROM read progress must be a function')
+      if (options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options))) throw new TypeError('ROM read options must be an object')
+      if (options && Object.keys(options).some(key => !['blockSize', 'maxInFlight', 'chunkSize'].includes(key))) throw new TypeError('Unsupported ROM read option')
+      const blockSize = options?.blockSize === undefined ? 1024 : options.blockSize
+      const maxInFlight = options?.maxInFlight === undefined ? 1 : options.maxInFlight
+      if (![1024, 4096].includes(blockSize) || !Number.isSafeInteger(maxInFlight) || maxInFlight < 1 || maxInFlight > 64) throw new RangeError('ROM read requires 1024 or 4096 byte blocks and 1..64 outstanding packets')
+      if (options?.chunkSize !== undefined && (!Number.isSafeInteger(options.chunkSize) || options.chunkSize <= 0 || bytes > options.chunkSize)) throw new RangeError('ROM read exceeds the requested chunk size')
+      const data = new Uint8Array(Buffer.from(await rpc('read', [offset, bytes, { blockSize, maxInFlight }]), 'base64'))
+      if (data.length !== bytes) throw Object.assign(fail('ROM_READ_LENGTH'), { operation: 'read' })
+      progress?.(data, data.length, bytes)
+      return data
+    },
     async flashData(bytes, progress, offset) { await rpc('write', [offset, Buffer.from(bytes).toString('base64')]); progress(bytes.byteLength, bytes.byteLength) },
     readRegister: address => rpc('readRegister', [address]),
     writeRegister: (address, value, mask) => rpc('writeRegister', [address, value, mask]),

package/src/node_rom.py

@@ -5,6 +5,7 @@ import base64
 import contextlib
 import json
 import os
+import struct
 import sys
 
 
@@ -59,13 +60,87 @@ def _open_rom(esptool, port):
             first_error = error
 
 
+
+def _read_flash(esp, offset, length, options=None):
+    """Bound the upstream stub reader without replacing its ACK/MD5 parser."""
+    if type(offset) is not int or offset < 0 or type(length) is not int or length <= 0 or length > 0xffffffff or offset + length > 0x100000000:
+        raise ValueError('ROM read requires a positive 32-bit address range')
+    if options is None:
+        options = {}
+    if not isinstance(options, dict) or set(options) - {'blockSize', 'maxInFlight'}:
+        raise ValueError('Unsupported ROM read options')
+    block_size, max_in_flight = options.get('blockSize', 1024), options.get('maxInFlight', 1)
+    if type(block_size) is not int or block_size not in (1024, 4096) or type(max_in_flight) is not int or not 1 <= max_in_flight <= 64:
+        raise ValueError('ROM read requires 1024 or 4096 byte blocks and 1..64 outstanding packets')
+    if not getattr(esp, 'IS_STUB', False):
+        raise RuntimeError('Bounded Flash read requires an initialized flasher stub')
+    if getattr(esp, 'FLASH_SECTOR_SIZE', None) != 4096 or not callable(getattr(esp, 'check_command', None)):
+        raise RuntimeError('Unsupported esptool stub read layout; use esptool==5.6.0')
+    command = esp.ESP_CMDS['READ_FLASH']
+    original_check = esp.check_command
+    missing = object()
+    old_check = vars(esp).get('check_command', missing)
+    old_block = vars(esp).get('FLASH_SECTOR_SIZE', missing)
+    commands = 0
+    block_changed = check_changed = False
+
+    def bounded_check(op_description, op=None, data=b'', *args, **kwargs):
+        nonlocal commands
+        if op == command:
+            commands += 1
+            if commands != 1 or not isinstance(data, bytes) or len(data) != 16:
+                raise RuntimeError('Unsupported esptool READ_FLASH command layout')
+            wire_offset, wire_length, wire_block, wire_window = struct.unpack('<IIII', data)
+            if (wire_offset, wire_length, wire_block, wire_window) != (offset, length, block_size, 64):
+                raise RuntimeError('Unexpected esptool READ_FLASH range or packet layout')
+            data = struct.pack('<IIII', offset, length, block_size, max_in_flight)
+        return original_check(op_description, op, data, *args, **kwargs)
+
+    try:
+        # Upstream 5.6.0 uses this instance field for both its request and its
+        # short-packet validation. Changing only the wire request is invalid.
+        esp.FLASH_SECTOR_SIZE = block_size
+        block_changed = True
+        esp.check_command = bounded_check
+        check_changed = True
+        result = esp.read_flash(offset, length)
+        if commands != 1 or not isinstance(result, bytes) or len(result) != length:
+            raise RuntimeError('Upstream Flash read did not complete the bounded request')
+        return result
+    finally:
+        try:
+            if check_changed:
+                if old_check is missing:
+                    del esp.check_command
+                else:
+                    esp.check_command = old_check
+        finally:
+            if block_changed:
+                if old_block is missing:
+                    del esp.FLASH_SECTOR_SIZE
+                else:
+                    esp.FLASH_SECTOR_SIZE = old_block
+
+
+def _erase_region(esptool, esp, address, size):
+    """Erase only the qualified range through the external official command."""
+    if type(address) is not int or address < 0 or address % 4096 or type(size) is not int or size <= 0 or size > 0xffffffff or size % 4096 or address + size > 0x100000000:
+        raise ValueError('ROM erase requires a positive, sector-aligned 32-bit address range')
+    if not getattr(esp, 'IS_STUB', False):
+        raise RuntimeError('Flash region erase requires an initialized flasher stub')
+    if getattr(esp, 'FLASH_SECTOR_SIZE', None) != 4096 or not callable(getattr(esp, 'erase_region', None)):
+        raise RuntimeError('Unsupported esptool stub region erase; use esptool==5.6.0')
+    # Do not use force: the official command also checks active security state.
+    esptool.erase_region(esp, address, size, force=False)
+
+
 def main():
     with contextlib.redirect_stdout(sys.stderr):
         import esptool
-    major, minor = map(int, esptool.__version__.split('.')[:2])
-    if major != 5 or minor < 3:
-        raise RuntimeError('Install esptool>=5.3,<6')
+    if esptool.__version__ != '5.6.0':
+        raise RuntimeError('Install esptool==5.6.0 for the verified bounded Flash reader')
     esp = None
+    erase_failed = False
     families = {'ESP32-P4': 0x3280, 'ESP32-S3': 0x3253, 'ESP32-S31': 0x3231}
     try:
         for line in sys.stdin:
@@ -74,6 +149,8 @@ def main():
                 with contextlib.redirect_stdout(sys.stderr):
                     method, args = request['method'], request.get('args', [])
                     result = None
+                    if erase_failed:
+                        raise RuntimeError('Flash region erase failed; start a fresh ROM session')
                     if method != 'initialize' and esp is None:
                         raise RuntimeError('Initialize the ROM adapter before issuing operations')
                     if method == 'initialize':
@@ -96,12 +173,17 @@ def main():
                         result = {'flags': security['flags'], 'flashCryptCnt': security['flash_crypt_cnt']}
                     elif method == 'stub':
                         esp = esptool.run_stub(esp)
+                        if not esp.IS_STUB:
+                            raise RuntimeError('A validated flasher stub is required')
                         esptool.attach_flash(esp)
                         esp.change_baud(460800)
+                        result = {'stubRunning': True}
                     elif method == 'flashId':
                         result = esp.flash_id()
                     elif method == 'read':
-                        result = base64.b64encode(esp.read_flash(*args)).decode('ascii')
+                        result = base64.b64encode(_read_flash(esp, *args)).decode('ascii')
+                    elif method == 'eraseRegion':
+                        _erase_region(esptool, esp, *args)
                     elif method == 'write':
                         offset, encoded = args
                         data = base64.b64decode(encoded, validate=True)
@@ -116,9 +198,14 @@ def main():
                         raise ValueError('Unknown ROM adapter method')
                 print(json.dumps({'id': request['id'], 'result': result}), flush=True)
             except Exception as error:
+                if request['method'] == 'eraseRegion':
+                    erase_failed = True
+                    with contextlib.suppress(Exception):
+                        if esp is not None and esp._port.is_open:
+                            esp._port.close()
                 print(json.dumps({'id': request['id'], 'error': 'ROM_OPERATION_FAILED', 'method': request['method'], 'detail': str(error)}), flush=True)
     finally:
-        if esp is not None:
+        if esp is not None and esp._port.is_open:
             esp._port.close()
 
 

package/src/node_rom_port.js

@@ -179,33 +179,41 @@ export async function recoverNodeRomPort(previous, { python = defaultPython, sig
   if (mac(previous.transition.serial) !== expectedMac) return null
   const enumerate = dependencies.listSerial ?? listSerial
   const now = dependencies.now ?? (() => performance.now())
+  const sleep = dependencies.sleep ?? ((ms, abortSignal) => delay(ms, undefined, { signal: abortSignal }))
   const deadline = now() + timeout
-  let ports
-  try { ports = await enumerate({ python, signal, timeout }) }
-  catch (error) {
+  const sameDevice = item => mac(item.serialNumber) === expectedMac && physicalLocation(item.location) === location
+  let runtime
+  // A closed native stub may still enumerate as ROM, then disappear before
+  // the same device's runtime reappears. Only observe during this window;
+  // never re-SYNC the stale ROM or issue a second handoff while it settles.
+  while (now() < deadline) {
+    checkAbort(signal)
+    let ports
+    try { ports = await enumerate({ python, signal, timeout: Math.max(1, Math.ceil(deadline - now())) }) }
+    catch (error) {
+      checkAbort(signal)
+      throw fail('ROM_PORT_ENUMERATION_FAILED', 'Cannot verify the selected device for read-only initialization recovery', error)
+    }
     checkAbort(signal)
-    throw fail('ROM_PORT_ENUMERATION_FAILED', 'Cannot verify the selected device for read-only initialization recovery', error)
+    if (now() >= deadline) throw fail('ROM_PORT_REBIND_TIMEOUT', 'Read-only initialization recovery enumeration exceeded its deadline')
+    if (!Array.isArray(ports)) throw fail('ROM_PORT_ENUMERATION_FAILED', 'Serial enumeration returned invalid descriptors')
+    const candidates = ports.filter(item => nativeRom(item) || nativeRuntime(item))
+    const conflicting = candidates.filter(item => (mac(item.serialNumber) === expectedMac || physicalLocation(item.location) === location) && !sameDevice(item))
+    if (conflicting.length) throw fail('ROM_RUNTIME_IDENTITY_MISMATCH', 'Runtime descriptors do not match the previously selected ROM device')
+    const matches = candidates.filter(sameDevice)
+    if (matches.length > 1) throw fail('ROM_PORT_AMBIGUOUS', 'Multiple native USB ports match the selected device')
+    if (matches.length && nativeRuntime(matches[0])) { runtime = matches[0]; break }
+    await sleep(Math.min(50, Math.max(1, deadline - now())), signal)
   }
-  checkAbort(signal)
-  if (now() >= deadline) throw fail('ROM_PORT_REBIND_TIMEOUT', 'Read-only initialization recovery enumeration exceeded its deadline')
-  if (!Array.isArray(ports)) throw fail('ROM_PORT_ENUMERATION_FAILED', 'Serial enumeration returned invalid descriptors')
-  const sameDevice = item => mac(item.serialNumber) === expectedMac && physicalLocation(item.location) === location
-  const existingRom = ports.filter(item => nativeRom(item) && sameDevice(item))
-  if (existingRom.length > 1) throw fail('ROM_PORT_AMBIGUOUS', 'Multiple ROM ports match the selected device')
-  if (existingRom.length) return null
-  const runtimes = ports.filter(nativeRuntime)
-  const conflicting = runtimes.filter(item => (mac(item.serialNumber) === expectedMac || physicalLocation(item.location) === location) && !sameDevice(item))
-  if (conflicting.length) throw fail('ROM_RUNTIME_IDENTITY_MISMATCH', 'Runtime descriptors do not match the previously selected ROM device')
-  const matches = runtimes.filter(sameDevice)
-  if (matches.length > 1) throw fail('ROM_PORT_AMBIGUOUS', 'Multiple runtime ports match the selected device')
-  if (!matches.length) return null
+  // Returning null preserves the caller's original initialize failure.
+  if (!runtime) return null
   // Revalidate at prepare's fresh enumeration, before opening EV-MUX. An OS port
   // may have been reused for a different board since the recovery snapshot.
-  const result = await prepareNodeRomPort({ port: matches[0].path, python, signal, timeout,
+  const result = await prepareNodeRomPort({ port: runtime.path, python, signal, timeout,
     expectedIdentity: { mac: expectedMac, location } }, dependencies)
   if (result.expectedMac !== expectedMac || result.transition?.observed !== 'rom' || physicalLocation(result.transition.location) !== location) {
     throw fail('ROM_RUNTIME_IDENTITY_MISMATCH', 'Recovery did not preserve the selected physical device identity')
   }
-  result.transition.recovery = { previousPort: previous.port, runtimePid: matches[0].productId }
+  result.transition.recovery = { previousPort: previous.port, runtimePid: runtime.productId }
   return result
 }