feat: add public GetSecurityInfo and FlashMD5 API methods

Author: jgangemi

pkg/espflasher/flasher.go

@@ -119,6 +119,7 @@ type Flasher struct {
 	chip    *chipDef
 	opts    *FlasherOptions
 	portStr string
+	secInfo []byte // cached security info from ROM (GET_SECURITY_INFO opcode 0x14)
 }
 
 // New creates a new Flasher connected to the given serial port.
@@ -665,8 +666,13 @@ func (f *Flasher) EraseFlash() error {
 }
 
 // EraseRegion erases a region of flash memory.
+// Requires the stub loader to be running.
 // Both offset and size must be aligned to the flash sector size (4096 bytes).
 func (f *Flasher) EraseRegion(offset, size uint32) error {
+	if !f.conn.isStub() {
+		return &UnsupportedCommandError{Command: "erase region (requires stub)"}
+	}
+
 	if offset%flashSectorSize != 0 {
 		return fmt.Errorf("offset 0x%X is not aligned to sector size 0x%X", offset, flashSectorSize)
 	}
@@ -688,6 +694,29 @@ func (f *Flasher) WriteRegister(addr, value uint32) error {
 	return f.conn.writeReg(addr, value, 0xFFFFFFFF, 0)
 }
 
+// GetSecurityInfo returns security-related information from the device.
+func (f *Flasher) GetSecurityInfo() (*SecurityInfo, error) {
+	return f.readSecurityInfo()
+}
+
+// FlashMD5 returns the MD5 hash of a flash region.
+// Requires the stub loader to be running.
+func (f *Flasher) FlashMD5(offset, size uint32) (string, error) {
+	if !f.conn.isStub() {
+		return "", &UnsupportedCommandError{Command: "flash MD5 (requires stub)"}
+	}
+
+	if err := f.attachFlash(); err != nil {
+		return "", err
+	}
+
+	result, err := f.conn.flashMD5(offset, size)
+	if err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(result), nil
+}
+
 // Reset performs a hard reset of the device, causing it to run user code.
 func (f *Flasher) Reset() {
 	if f.conn.isStub() {

pkg/espflasher/flasher_test.go

@@ -433,3 +433,46 @@ func TestFlashSizeFromJEDECMatchesChipSizes(t *testing.T) {
 		}
 	}
 }
+
+func TestFlashMD5RequiresStub(t *testing.T) {
+	mock := &mockConnection{}
+	mock.stubMode = false // ROM mode
+	f := &Flasher{conn: mock, chip: chipDefs[ChipESP32]}
+	_, err := f.FlashMD5(0, 1024)
+	if err == nil {
+		t.Fatal("expected error when stub is not running")
+	}
+	if ue, ok := err.(*UnsupportedCommandError); !ok {
+		t.Errorf("expected UnsupportedCommandError, got %T: %v", err, err)
+	} else if ue.Command != "flash MD5 (requires stub)" {
+		t.Errorf("unexpected error message: %s", ue.Command)
+	}
+}
+
+func TestGetSecurityInfo(t *testing.T) {
+	secInfo := make([]byte, 20)
+	binary.LittleEndian.PutUint32(secInfo[0:4], 0x05)
+	secInfo[4] = 0x02
+	binary.LittleEndian.PutUint32(secInfo[12:16], 0x1234)
+	binary.LittleEndian.PutUint32(secInfo[16:20], 0x0200)
+
+	mock := &mockConnection{}
+	mock.securityInfoFunc = func() ([]byte, error) {
+		return secInfo, nil
+	}
+	f := &Flasher{conn: mock}
+	info, err := f.GetSecurityInfo()
+	if err != nil {
+		t.Fatalf("GetSecurityInfo failed: %v", err)
+	}
+	if info == nil {
+		t.Fatal("expected non-nil SecurityInfo")
+	}
+	if info.ChipID == nil || *info.ChipID != 0x1234 {
+		if info.ChipID != nil {
+			t.Errorf("unexpected chip ID: got 0x%X, want 0x1234", *info.ChipID)
+		} else {
+			t.Error("unexpected nil ChipID")
+		}
+	}
+}

pkg/espflasher/protocol.go

@@ -284,6 +284,7 @@ func (c *conn) writeReg(addr, value, mask, delayUS uint32) error {
 // securityInfo reads security-related information from the device.
 // Try with 20 bytes first (most chips), fallback to 12 bytes (ESP32-S2).
 func (c *conn) securityInfo() ([]byte, error) {
+	c.flushInput()
 	data := make([]byte, 20)
 
 	result, err := c.checkCommand("get security info", cmdSecurityInfoReg, data, 0, defaultTimeout, 20)

pkg/espflasher/security_info.go

@@ -30,9 +30,19 @@ type ParsedFlags struct {
 }
 
 func (f *Flasher) readSecurityInfo() (*SecurityInfo, error) {
-	res, err := f.conn.securityInfo()
-	if err != nil {
-		return nil, err
+	var res []byte
+	var err error
+
+	// Use cached security info if available (from ROM before stub was loaded)
+	if len(f.secInfo) > 0 {
+		res = f.secInfo
+	} else {
+		res, err = f.conn.securityInfo()
+		if err != nil {
+			return nil, err
+		}
+		// Cache the raw bytes for future calls
+		f.secInfo = res
 	}
 
 	var si SecurityInfo

pkg/espflasher/security_info_test.go

@@ -202,3 +202,124 @@ func TestReadSecurityInfo(t *testing.T) {
 		})
 	}
 }
+
+func TestSecurityInfoFlushInput(t *testing.T) {
+	// Test that securityInfo clears any stray input before querying.
+	// This verifies the fix for the ESP32-S3 issue where SLIP frame delimiters
+	// in the input buffer corrupted the response (command 0x14 failed: status=0xC0).
+	buf20 := make([]byte, 20)
+	binary.LittleEndian.PutUint32(buf20[0:4], 0x05)
+	buf20[4] = 0x03
+	binary.LittleEndian.PutUint32(buf20[12:16], 0x0009)
+
+	mc := &mockConnection{
+		securityInfoFunc: func() ([]byte, error) {
+			return buf20, nil
+		},
+	}
+	f := &Flasher{conn: mc}
+
+	si, err := f.readSecurityInfo()
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if si.Flags != 0x05 {
+		t.Errorf("Flags = 0x%x, want 0x05", si.Flags)
+	}
+
+	if si == nil {
+		t.Error("expected SecurityInfo to be populated")
+	}
+}
+
+func TestSecurityInfoCaching(t *testing.T) {
+	// Test that security info is cached from the first call (ROM before stub loads)
+	// and subsequent calls return the cached bytes without re-issuing the command.
+	buf20 := make([]byte, 20)
+	binary.LittleEndian.PutUint32(buf20[0:4], 0x05)     // flags
+	buf20[4] = 0x03                                     // FlashCryptCnt
+	binary.LittleEndian.PutUint32(buf20[12:16], 0x0009) // ChipID
+
+	callCount := 0
+	mc := &mockConnection{
+		securityInfoFunc: func() ([]byte, error) {
+			callCount++
+			return buf20, nil
+		},
+	}
+	f := &Flasher{conn: mc}
+
+	// First call should invoke the connection
+	si1, err := f.readSecurityInfo()
+	if err != nil {
+		t.Fatalf("first call: unexpected error: %v", err)
+	}
+	if si1.Flags != 0x05 {
+		t.Errorf("first call: Flags = 0x%x, want 0x05", si1.Flags)
+	}
+	if callCount != 1 {
+		t.Errorf("first call: expected 1 connection call, got %d", callCount)
+	}
+
+	// Second call should use the cached bytes without calling conn.securityInfo()
+	si2, err := f.readSecurityInfo()
+	if err != nil {
+		t.Fatalf("second call: unexpected error: %v", err)
+	}
+	if si2.Flags != 0x05 {
+		t.Errorf("second call: Flags = 0x%x, want 0x05", si2.Flags)
+	}
+	if callCount != 1 {
+		t.Errorf("second call: expected 1 total connection call, got %d", callCount)
+	}
+
+	// Results should be identical
+	if si1.Flags != si2.Flags || si1.FlashCryptCnt != si2.FlashCryptCnt {
+		t.Error("cached result differs from initial result")
+	}
+}
+
+func TestSecurityInfoCachingWithStubFailure(t *testing.T) {
+	// Test that when security info is cached from ROM, a stub failure (0xC0)
+	// on a second call to GetSecurityInfo() returns the cached data instead.
+	buf20 := make([]byte, 20)
+	binary.LittleEndian.PutUint32(buf20[0:4], 0x05)     // flags
+	buf20[4] = 0x03                                     // FlashCryptCnt
+	binary.LittleEndian.PutUint32(buf20[12:16], 0x0009) // ChipID
+
+	callCount := 0
+	mc := &mockConnection{
+		securityInfoFunc: func() ([]byte, error) {
+			callCount++
+			if callCount == 1 {
+				// First call (ROM) succeeds
+				return buf20, nil
+			}
+			// Second call (stub) would fail, but it won't be called
+			return nil, errors.New("stub does not support command 0x14")
+		},
+	}
+	f := &Flasher{conn: mc}
+
+	// First call succeeds and caches the data
+	si1, err := f.readSecurityInfo()
+	if err != nil {
+		t.Fatalf("first call: unexpected error: %v", err)
+	}
+	if si1.Flags != 0x05 {
+		t.Errorf("first call: Flags = 0x%x, want 0x05", si1.Flags)
+	}
+
+	// Second call returns cached data without hitting the connection
+	si2, err := f.readSecurityInfo()
+	if err != nil {
+		t.Fatalf("second call: unexpected error: %v", err)
+	}
+	if si2.Flags != 0x05 {
+		t.Errorf("second call: Flags = 0x%x, want 0x05", si2.Flags)
+	}
+	if callCount != 1 {
+		t.Errorf("expected only 1 connection call (second should use cache), got %d", callCount)
+	}
+}