download layout: load CryptoJS so installer can verify flash writes#1775
Merged
makermelissa merged 1 commit intoMay 14, 2026
Conversation
The Web Firmware Installer (cpinstaller) asks esptool-js to verify each flashed image by comparing the MD5 of the bytes we wrote against the MD5 the chip reports for the same flash region. esptool-js only performs that check when the caller supplies a calculateMD5Hash function; the installer obtains a hash via a CryptoJS global when one is available, and silently skips verification when one isn't (which is the current production state). Skipping verification can mask flash corruption on some USB-serial bridges (notably Pi 5 + CP2104) and was the underlying cause of the "OPEN INSTALLER does not complete on Feather ESP32 V2" hang fixed in adafruit/web-firmware-installer-js#23. Loading CryptoJS from the same jsdelivr CDN we already use for the installer bundle activates the verification path on every page that renders the installer. CryptoJS is ~50 kB minified and only loads on pages that also load the installer (gated by bootloader_info.installer == true), so the cost is bounded to the small set of download pages where it adds value. Refs adafruit/web-firmware-installer-js#22 Refs adafruit/web-firmware-installer-js#23
Contributor
Author
|
Heads-up: adafruit/web-firmware-installer-js#23 is merged and released as 2.2.4. The existing |
makermelissa
approved these changes
May 14, 2026
Collaborator
makermelissa
left a comment
makermelissa
left a comment
There was a problem hiding this comment.
That's exactly where I would have added it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up to adafruit/web-firmware-installer-js#23, which fixed issue #22 (OPEN INSTALLER hang on Feather ESP32 V2).
The installer fix enables post-flash MD5 verification by passing a
calculateMD5Hashcallback toesptool-js'swriteFlash. esptool-js only runs the readback hash check when that callback is supplied, and the callback in turn relies on a hashing library being present on the host page. To keep the installer drop-in for all consumers, that library is optional: when it isn't loaded, the installer's callback returnsnulland esptool-js skips verification (preserving the prior behavior).This PR loads
crypto-json the download pages that render the installer, which is what activates the verification path in production.Change
Adds one
<script>tag to_layouts/download.html, inside the same{% if bootloader_info and bootloader_info.installer == true %}block that already loadscpinstaller.min.js, so the cost is bounded to pages where the installer is actually rendered. Source is the samecdn.jsdelivr.netwe already use for the installer bundle.Minified CryptoJS is ~50 kB. It loads in parallel with the installer module and is a no-op if cached.
Why this matters
Without this script tag,
esptool-jssilently trusts every flash write. On flaky USB-serial bridges (notably Pi 5 + CP2104) that masked active flash corruption and made boards boot-loop withinvalid header: 0xffffffffafter a successful-looking install — which is exactly what issue #22 was. With CryptoJS loaded, the installer now surfaces the upstreamMD5 of file does not match data in flash!error instead of producing a silently bricked board.Testing
adafruit/web-firmware-installer-jsalready detectsCryptoJSat runtime, so once this change is deployed the verification path runs automatically for every installer launch. No installer-side change is required here.crypto-jsbefore thecpinstaller.min.jsmodule) makes the global available when the module evaluates.Related