---
id: validation-restore-backup-package
title: Validación de Restore backup package
category: backups
version: 1.0
status: validated
updated_at: 2026-07-14
---

# 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:

```text
/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:

```text
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.