Restore Backup Package

Date: 2026-07-14

Status: implemented and physically validated

Scope

Restore backup package completes the backup/write cycle for ESP Platform Backups. It supports:

selecting a saved ESP Platform backup;
uploading an esp-platform-backup.zip from the computer;
validating the package before restore options are shown;
complete restore from full-flash.bin at 0x0;
selective restore by detected regions;
optional safety backup before writing;
post-write verification by reading written bytes when enabled;
audit of restore result.

It does not convert backups into firmware. Backup and firmware remain separate concepts.

Out of scope:

Compare with repository;
Import firmware from connected ESP32;
OTA;
Provisioning;
Fleet Management;
Edge OS.

Backend Validation

Endpoints:

POST /api/v1/backups/{id}/restore/validate
POST /api/v1/backups/restore/upload
GET /api/v1/backups/restore-sessions/{id}/files/{filename}
POST /api/v1/backups/restore-sessions/{id}/complete

The backend validates:

ZIP structure;
manifest.json existence;
checksums.sha256 existence;
SHA-256 checksums;
file sizes;
flash size bounds;
region offsets;
region overlap;
backup format and format version;
sensitive/device-state/diagnostic region metadata.

Uploaded ZIPs are extracted into a private temporary path under:

/srv/esp-platform/backups/restore-tmp/<session-id>/

Files are not placed in a public web path. Downloads are served through authenticated backend routes.

Restore Session Audit

Restore sessions are stored in backup_restore_session with:

source type: SERVER_BACKUP or UPLOADED_ZIP;
package filename;
package SHA-256;
manifest JSON;
source MAC;
target MAC;
chip;
flash size;
restore mode;
selected regions;
result;
error message;
duration;
flasher build.

backup_audit_log also records validation/upload and final restore events.

UI Flow

Backups > Restore backup package:

Select source:
- saved ESP Platform backup;
- uploaded esp-platform-backup.zip.
Validate package.
Connect target ESP32 through Web Serial over HTTPS.
Review compatibility.
Choose restore mode:
- complete restore;
- selective restore.
Choose regions for selective restore.
Choose options:
- erase flash before complete restore;
- create safety backup before restore;
- verify after restore.
Review summary.
Type RESTORE.
Execute restore.
Verify and reset.
Review final status.

Safe Defaults

Selected by default for selective restore:

bootloader;
partition table;
app partitions;
reusable filesystem partitions.

Excluded by default:

NVS;
OTA data;
coredump;
NVS keys;
sensitive regions;
diagnostic regions;
device-state regions.

Selecting sensitive/device-state/diagnostic regions requires explicit warning acceptance in the browser.

NVS Warning

NVS may contain:

Wi-Fi SSIDs;
Wi-Fi passwords;
tokens;
certificates;
identifiers;
calibrations;
activations;
configuration tied to device identity.

Restoring NVS to another ESP32 can duplicate identity, copy credentials, create network conflicts or fail if data is tied to MAC, eFuse or chip state.

Secure Boot and Flash Encryption

The UI performs best-effort detection through esptool-js chip hooks when available:

Secure Boot;
Flash Encryption / flash crypt config.

If detected, the compatibility report shows critical warnings. ESP Platform does not promise complete cloning of protected devices because flash dumps do not contain eFuses.

Write Behavior

Default baudrate remains 115200.

Complete restore:

writes full-flash.bin at 0x0;
offers Erase flash before restore, enabled by default;
warns that everything on flash may be overwritten.

Selective restore:

writes only selected regions;
does not erase full flash by default;
leaves non-selected regions untouched.

Progress states:

Validating;
Connecting;
Reading;
Erasing;
Writing;
Verifying;
Resetting;
Completed;
Cancelled;
Failed.

The UI uses:

global progress for the entire operation;
partial progress for the current region/block/segment.

Cancellation

Cancel requests stop new stages and attempt to abort during progress callbacks. esptool-js may finish the active write/read block before cancellation takes effect.

If a restore is cancelled during writing, ESP Platform reports:

Restore cancelled; device state may be incomplete.

No rollback is attempted automatically.

Software Validation Completed

Validated on 2026-07-14:

saved backup restore validation for backup #2;
returned 4 MB full-flash package;
detected 8 restore regions;
safe defaults: bootloader, partition-table, app0, app1, spiffs;
controlled backend download returns 4,194,304 bytes;
controlled backend download SHA-256: ca965603a5c02668e63721b34c05fba0dc2494e3050edcb36b1c621bcafe785a;
uploaded real esp-platform-backup-2.zip validates successfully;
uploaded ZIP download returns the same 4 MB full-flash image;
corrupted checksum ZIP is rejected with HTTP 400 and clear message;
Backups page loads Restore UI without JavaScript console errors;
Restore package validation renders compatibility, warnings and region table.

Physical Validation Completed

Validated on 2026-07-14 with ESP32-D0WD revision 1, MAC 2c:bc:bb:75:f2:74, Flash ID 16405e, 4 MB flash, baudrate 115200.

Test A - Complete restore: passed.

Backup source: saved ESP Platform backup #2.
Full image size: 4,194,304 bytes.
Full image SHA-256: ca965603a5c02668e63721b34c05fba0dc2494e3050edcb36b1c621bcafe785a.
Safety backup was enabled and downloaded before write.
Safety backup SHA-256: cd3517473707d59c3d915b52a3e16213cadce80d9ffb2b4371958fb7acb51a08.
Full restore wrote from 0x0 and post-write verification matched the source SHA-256.
RTS hard reset was requested after restore.

Test B - Selective app0 restore: passed.

Selected only app0.
Excluded NVS, OTA data and filesystem.
app0 offset: 0x10000.
app0 size: 1,310,720 bytes.
app0 SHA-256: d79d4b3db73b490429122d64e076dedecf3c3a198497374ce3a8fa4b575fd948.
NVS SHA-256 before and after remained 83db022f60712229ae24ca0412897611d656ea5c66102d3f87d5eb3014619172.

Test C - Cancel during write: passed.

Cancellation was requested during Writing, after erase had completed.
UI reported Restore cancelled; device state may be incomplete.
Success was not shown for the cancelled operation.
Serial port was released.
Audit event RESTORE_CANCELLED was recorded.
Device was recovered with a complete verified restore.

Test D - Incompatibility: passed.

Controlled invalid package was rejected before writing.
Error: Region bootloader exceeds flash size.; Region bootloader overlaps coredump.

Test E - Corrupt checksum: passed at package-validation boundary.

Controlled ZIP with altered checksum was rejected before writing.
Error: Checksum mismatch for full-flash.bin.
Chrome automation could not attach the ZIP through the native file chooser due Not allowed; validation was confirmed through the same backend package-validation endpoint.

Execute Restore Enablement

Execute restore is intentionally disabled until all of these are true:

ESP32 connected through Web Serial;
restore package validated;
compatibility is not incompatible;
confirmation text is exactly RESTORE;
no operation is currently busy.

Selecting every partition does not disable execution by itself. Sensitive or device-specific regions such as NVS, OTA data and coredump require explicit warning confirmation when selected.

Closure

Restore backup package is approved for MVP Flasher/Backups closure. New features remain frozen except bug fixes.