Repository navigation
feat(mac): embed the Electron 41+ ASAR integrity digest into the Electron Framework - #10346
Conversation
…ectron Framework slot Electron 41 reserves a slot (sentinel "AGbevlPCksUGKNL8TSn7wGmJEuJsXb2A" + used, version, SHA-256) in the Electron Framework binary for a digest of the ElectronAsarIntegrity Info.plist dictionary. - computeAsarIntegrityDigest: version 1 digest, SHA-256 over key, algorithm and hash of every entry, keys in UTF-16 code unit order (Electron's NSLiteralSearch, not localeCompare) - writeAsarIntegrityDigest: chunked sentinel scan (handles a sentinel across a read boundary), writes every slot (one per universal slice), rejects more than 2 slots and checks every slot fits before the first write, returns the number written (0 for Electron < 41) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…k (Electron 41+) After the afterPack hook, and before the fuses are flipped and the app is signed, MacPackager computes the digest from the final Info.plist ElectronAsarIntegrity entries, writes it into the Electron Framework slot(s) and signs the framework again ad hoc, so an unsigned arm64 app keeps launching (code signing the app replaces that signature). - new option mac.asarIntegrityDigest (default true; mas and masDev inherit it), schema regenerated - runs for darwin, mas and the merged universal app; skipped for universal slices, asar disabled or asar.disableIntegrity, Electron < 41, and non-macOS hosts (warning, codesign is needed); warns and skips when Info.plist has no entries or the framework has no slot - tests: gating and embedding with codesign mocked (any OS); real Electron 42.4.0 packs on macOS that launch the app with the integrity fuse on (a changed Info.plist entry is rejected, the opt-out lets it through, an unsigned app stays launchable); CLI coercion of the option Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- TSDoc: enableEmbeddedAsarIntegrityValidation points to mac.asarIntegrityDigest; asar.disableIntegrity notes that it skips the digest too (and names the fuse correctly); scheme.json regenerated - website: package integrity (security), the new step before the fuses (build lifecycle), a note in the fuses tutorial, a "New in v27" entry, and a troubleshooting entry for "Failed to get integrity for validatable asar archive" Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…digest An afterPack hook that edits Info.plist with `defaults write` leaves it in the binary format, which the XML-only plist parser rejects with "Cannot read properties of null (reading 'nodeName')", failing the build. A binary Info.plist is now converted with plutil (the step only runs on macOS). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…rity digest `/usr/bin/codesign` and `/usr/bin/plutil` instead of resolving the bare names through PATH, where a planted binary could run instead (as MacTargetHelper already does for codesign). Tests use the same paths. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Packs a universal app with Electron 42.4.0 and checks that both framework slices hold the digest of the merged app's Info.plist, that the app starts, and that Electron refuses to start it once an Info.plist entry is changed. This covers the call after @electron/universal merged the slices, which the host-arch tests never reach. It packs an x64 slice too, so it runs on CI only; its snapshot entry is added by hand because CI does not write new snapshots. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d correct its troubleshooting entry - the digest is on by default and patches and re-signs the Electron Framework, so it gets the same entries as other default-on changes: a v27-breaking-changes section and table row, a what's-new table row and a v26-to-v27 checklist item (afterPack self-signing, changes after afterPack, manual @electron/universal merges) - troubleshooting: "Failed to get integrity for validatable asar archive" means no valid Info.plist entry (changed after the digest, or missing), while a stale app.asar hash fails with "Integrity check failed"; the hashes are computed before afterPack, only the digest after it - security: the digest protects the hashes only with the enableEmbeddedAsarIntegrityValidation fuse - build lifecycle: changing Info.plist after the digest step is what breaks the launch Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ead of converting it
Drops the plutil conversion: the digest step reads Info.plist with parsePlistFile like the rest of
electron-builder, typed as { ElectronAsarIntegrity?: AsarIntegrity }, and computeAsarIntegrityDigest
takes the existing AsarIntegrity type instead of a duplicate interface. A binary Info.plist (as left
by `defaults write` in an afterPack hook) now fails the build with an InvalidConfigurationError that
names the file and the mac.asarIntegrityDigest: false opt-out, instead of an unrelated TypeError.
The tests read and write the plist through the same typed helpers.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
🦋 Changeset detectedLatest commit: 2bc5877 The changes in this PR will be included in the next version bump. This PR includes changesets to release 8 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
… constructed from library input' Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
…unce the digest to afterPack users The CodeQL autofix passed the bare framework name through sanitizeDirPath, which resolves it against the cwd, so every Electron 41+ macOS build opened a nonexistent framework binary (ENOENT). Join the name under the app's Frameworks directory and sanitize the joined paths with containment instead. Warn once per process, with the v27 migration link, when the digest is embedded and a user afterPack hook is configured, since that hook is where re-signing the framework or a later Info.plist change bites. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Sj9aojKiz5RwJ3gLGtjrgg
There was a problem hiding this comment.
The regression I flagged in my previous review (bare framework name resolved against cwd via sanitizeDirPath, causing ENOENT on every Electron 41+ macOS build) is fixed in the latest commit: the framework name is now joined under the app's Frameworks directory before sanitizing with containment, and a dedicated test (rejects a framework name that leaves the Frameworks directory) now covers it.
Extended reasoning...
Reviewed commit 44c87d6, the latest in the range, which changes packages/app-builder-lib/src/electron/mac/asarIntegrityDigest.ts and macPackager.ts: frameworkPath/binaryPath are now built by joining frameworkName under Contents/Frameworks before calling sanitizeDirPath(path, base) with containment, instead of resolving the bare name directly as the earlier CodeQL autofix did. This directly addresses the path-resolution regression I reported inline on the prior push. New tests exercise both the fixed containment path and the new afterPack-hook warning; no new findings beyond this were identified in the delta since my last review.
…y digest enforced The mac blackbox updater builds used ELECTRON_VERSION (39), which has no digest slot, so the default-on mac.asarIntegrityDigest was skipped for them and the enableEmbeddedAsarIntegrityValidation fuse never checked a digest. Build them with ASAR_INTEGRITY_DIGEST_ELECTRON_VERSION and assert every Electron Framework slice holds the digest of the final Info.plist entries, so the old and the updated app both launch under Electron's digest check. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Sj9aojKiz5RwJ3gLGtjrgg
Fixes #9648
Electron Frameworkbinary (section__DATA_CONST,__asar_integrity): the sentinelAGbevlPCksUGKNL8TSn7wGmJEuJsXb2A, thenused(1 byte),version(1 byte) and a SHA-256 digest (32 bytes). With theenableEmbeddedAsarIntegrityValidationfuse on, Electron validates theElectronAsarIntegrityInfo.plist dictionary against that digest at launch, soapp.asarcan no longer be swapped together with itsInfo.plisthash. Whileusedis 0, Electron skips the check (fails open).darwin,mas,mas-dev, and the merged universal app), after theafterPackhook and before the fuses are flipped and the app is signed:Info.pliston disk, so changes made inafterPackand the entries@electron/universalregenerates are covered.Info.plistis read as XML withparsePlistFile, like everywhere else in electron-builder; a binaryInfo.plist(as left bydefaults writein anafterPackhook) fails the build with anInvalidConfigurationErrorthat names the file and themac.asarIntegrityDigest: falseopt-out./usr/bin/codesign --sign - --force --deep --preserve-metadata=entitlements,requirements,flags,runtime <Electron Framework.framework>. Patching the binary invalidates the linker signature Electron's arm64 builds ship with, and Apple Silicon kills a process whose signature is invalid. Code signing the app afterwards replaces the ad-hoc signature.mac.asarIntegrityDigest(defaulttrue, same as@electron/packager;masandmasDevinherit it). Set it tofalseto leave the Electron Framework as Electron ships it.ElectronAsarIntegrity; the merged app gets the digest)asar: falseorasar.disableIntegrity: true(a stock ElectronInfo.pliststill lists the removeddefault_app.asar, which must not be digested)codesignis needed to sign the modified framework againInfo.plistwithoutElectronAsarIntegrityentries, or a framework without a slot: warningelectron/mac/asarIntegrityDigest.ts:computeAsarIntegrityDigest: version 1 digest over the existingAsarIntegritytype, SHA-256 over the key, algorithm and hash of every entry, keys in UTF-16 code unit order (Electron sorts withNSLiteralSearch;localeCompareorder produces a digest Electron rejects).writeAsarIntegrityDigest: scans the binary in 4 MB chunks for the sentinel (reads overlap bysentinel.length - 1, so a sentinel across a chunk boundary is found once), rejects more than 2 slots, checks every slot fits before the first write, and returns the number of slots written.embedAsarIntegrityDigest: readsInfo.plistwithparsePlistFile<{ ElectronAsarIntegrity?: AsarIntegrity }>, writes the slots, re-signs the framework.PlatformPackager.doAddAsarIntegrityDigesthook (no-op outside macOS), called indoPackright beforedoAddElectronFusesunlessdisableAsarIntegrity(universal slices) is set;MacPackager.doUniversalPackcalls it on the merged app.computeAsarOptionsis nowprotectedfor that call.scheme.jsonregenerated:asarIntegrityDigestonMacConfigurationandMasConfiguration, plus the editedenableEmbeddedAsarIntegrityValidationandasar.disableIntegritydescriptions (the latter now names the fuse correctly).#macos-asar-integrity-digestand table row), and the v26-to-v27 checklist.asarIntegrityDigestTest.ts(any OS): digest vectors checked against Electron 41.3.0 (the app launches with them and is rejected with thelocaleCompare-order digest), slot writer on synthetic binaries (chunk boundary, two slices, no slot, truncated slot, too many slots).asarIntegrityDigestEmbedTest.ts(any OS,codesignmocked): the gating inMacPackager.doAddAsarIntegrityDigest(asar disabled,asar.disableIntegrity, opt-out, Electron 40 vs 41 prerelease, non-macOS host, missing entries, missing slot, branded framework name), the exactcodesigncall, and theInvalidConfigurationErrorfor anInfo.plistthat is not XML (nothing written, nothing signed).asarIntegrityDigestPackTest.ts(macOS, Electron 42.4.0): builds that launch the app with the integrity andonlyLoadAppFromAsarfuses on. The untouched app starts. After anInfo.plistentry is changed (and the app is signed again ad hoc), Electron refuses to start withFailed to get integrity for validatable asar archive. WithasarIntegrityDigest: falsethe same change goes unnoticed. An unsigned app without fuses stays launchable and its framework passescodesign --verify --strict. A universal app (CI only, it packs an x64 slice) gets the digest in both slices and is enforced the same way.configurationValidationTest.ts:-c.mac.asarIntegrityDigest=falseand-c.mas.asarIntegrityDigest=falsevalidate to booleanfalse.testConfig.ts:ASAR_INTEGRITY_DIGEST_ELECTRON_VERSION = "42.4.0"for these tests only;ELECTRON_VERSION(39.8.10) predates the slot and is not bumped.app-builder-libminor.Design notes
@electron/asar(fix: extra resources copied to wrong folder on linux/windows #380) was reverted (Codesigning: "a sealed resource is missing or invalid", file modified in Squirrel framework #424), and@electron/fuses2.1.3 and@electron/universal3.0.6 have none.@electron/packager20.3.0 (Asar packages everything even itself? #1890) is the reference implementation; this follows its slot format, scan and re-sign, and its default (on).electronFuses.resetAdHocDarwinSignatureis set, the fuses' whole-app ad-hoc re-sign then covers the digest too. Writing the digest after that re-sign would leave the app's outer seal stale.resetAdHocDarwinSignaturestill invalidates the framework signature of an unsigned arm64 build, as it does today. TheFuseOptionsV1doc's claim that the ad-hoc signature is re-applied automatically after flipping fuses does not match the code.mac.asarIntegrityDigest: false: anyone who changesapp.asarorInfo.plistafterafterPack, signs the app themselves inafterPack(the ad-hoc re-sign replaces the framework signature), or merges separately builtx64andarm64apps with@electron/universalthemselves (the per-arch framework_CodeSignaturemakes the slices differ).--prepackagedapps are not modified.enableEmbeddedAsarIntegrityValidationfuse on (Electron reads the slot only then). A digest mismatch fails with the sameFailed to get integrity for validatable asar archivemessage as a missing entry; a staleapp.asarhash fails withIntegrity check failed for asar archiveinstead.nativeModules.verifyNativeBinaries, and documented in the same v27 behavior-change places.