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:
1. Select source:
   - saved ESP Platform backup;
   - uploaded "esp-platform-backup.zip".
2. Validate package.
3. Connect target ESP32 through Web Serial over HTTPS.
4. Review compatibility.
5. Choose restore mode:
   - complete restore;
   - selective restore.
6. Choose regions for selective restore.
7. Choose options:
   - erase flash before complete restore;
   - create safety backup before restore;
   - verify after restore.
8. Review summary.
9. Type "RESTORE".
10. Execute restore.
11. Verify and reset.
12. 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.