Skip to content

feat(mac): embed the Electron 41+ ASAR integrity digest into the Electron Framework - #10346

Merged
mmaietta merged 13 commits into
masterfrom
feat/mac-asar-integrity-digest
Oct 21, 2026
Merged

mmaietta merged 13 commits into
masterfrom
feat/mac-asar-integrity-digest

Conversation

@mmaietta

Copy link
Copy Markdown
Collaborator

Fixes #9648

  • Electron 41 (feat: validate integrity of ASAR Integrity dictionary on macOS electron/electron#48587) reserves a 66-byte slot in the Electron Framework binary (section __DATA_CONST,__asar_integrity): the sentinel AGbevlPCksUGKNL8TSn7wGmJEuJsXb2A, then used (1 byte), version (1 byte) and a SHA-256 digest (32 bytes). With the enableEmbeddedAsarIntegrityValidation fuse on, Electron validates the ElectronAsarIntegrity Info.plist dictionary against that digest at launch, so app.asar can no longer be swapped together with its Info.plist hash. While used is 0, Electron skips the check (fails open).
  • electron-builder now embeds that digest for every macOS build (darwin, mas, mas-dev, and the merged universal app), after the afterPack hook and before the fuses are flipped and the app is signed:
    • The digest is computed from the final Info.plist on disk, so changes made in afterPack and the entries @electron/universal regenerates are covered. Info.plist is read as XML with parsePlistFile, like everywhere else in electron-builder; a binary Info.plist (as left by defaults write in an afterPack hook) fails the build with an InvalidConfigurationError that names the file and the mac.asarIntegrityDigest: false opt-out.
    • It is written into every slot of the framework (one per architecture slice).
    • The framework is then signed again ad hoc: /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.
  • New option mac.asarIntegrityDigest (default true, same as @electron/packager; mas and masDev inherit it). Set it to false to leave the Electron Framework as Electron ships it.
  • Skipped when the digest would protect nothing or can't be applied:
    • universal slices (they have no ElectronAsarIntegrity; the merged app gets the digest)
    • asar: false or asar.disableIntegrity: true (a stock Electron Info.plist still lists the removed default_app.asar, which must not be digested)
    • Electron < 41 (silently)
    • non-macOS hosts: warning, because codesign is needed to sign the modified framework again
    • an Info.plist without ElectronAsarIntegrity entries, or a framework without a slot: warning
  • New electron/mac/asarIntegrityDigest.ts:
    • computeAsarIntegrityDigest: version 1 digest over the existing AsarIntegrity type, SHA-256 over the key, algorithm and hash of every entry, keys in UTF-16 code unit order (Electron sorts with NSLiteralSearch; localeCompare order produces a digest Electron rejects).
    • writeAsarIntegrityDigest: scans the binary in 4 MB chunks for the sentinel (reads overlap by sentinel.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: reads Info.plist with parsePlistFile<{ ElectronAsarIntegrity?: AsarIntegrity }>, writes the slots, re-signs the framework.
  • PlatformPackager.doAddAsarIntegrityDigest hook (no-op outside macOS), called in doPack right before doAddElectronFuses unless disableAsarIntegrity (universal slices) is set; MacPackager.doUniversalPack calls it on the merged app. computeAsarOptions is now protected for that call.
  • scheme.json regenerated: asarIntegrityDigest on MacConfiguration and MasConfiguration, plus the edited enableEmbeddedAsarIntegrityValidation and asar.disableIntegrity descriptions (the latter now names the fuse correctly).
  • Docs: package integrity (security), the new step before the fuses (build lifecycle), a note in the fuses tutorial, a troubleshooting entry for "Failed to get integrity for validatable asar archive", and the v27 behavior-change entries: what's new (feature bullet and table row), v27 breaking changes (section #macos-asar-integrity-digest and table row), and the v26-to-v27 checklist.
  • Tests:
    • asarIntegrityDigestTest.ts (any OS): digest vectors checked against Electron 41.3.0 (the app launches with them and is rejected with the localeCompare-order digest), slot writer on synthetic binaries (chunk boundary, two slices, no slot, truncated slot, too many slots).
    • asarIntegrityDigestEmbedTest.ts (any OS, codesign mocked): the gating in MacPackager.doAddAsarIntegrityDigest (asar disabled, asar.disableIntegrity, opt-out, Electron 40 vs 41 prerelease, non-macOS host, missing entries, missing slot, branded framework name), the exact codesign call, and the InvalidConfigurationError for an Info.plist that is not XML (nothing written, nothing signed).
    • asarIntegrityDigestPackTest.ts (macOS, Electron 42.4.0): builds that launch the app with the integrity and onlyLoadAppFromAsar fuses on. The untouched app starts. After an Info.plist entry is changed (and the app is signed again ad hoc), Electron refuses to start with Failed to get integrity for validatable asar archive. With asarIntegrityDigest: false the same change goes unnoticed. An unsigned app without fuses stays launchable and its framework passes codesign --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=false and -c.mas.asarIntegrityDigest=false validate to boolean false.
    • 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.
  • Changeset: app-builder-lib minor.

Design notes

  • No upstream library to reuse: the integrity digest API added to @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/fuses 2.1.3 and @electron/universal 3.0.6 have none. @electron/packager 20.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).
  • The digest is written before the fuses because both patch the same binary. When electronFuses.resetAdHocDarwinSignature is 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.
  • Unchanged and out of scope: flipping fuses without resetAdHocDarwinSignature still invalidates the framework signature of an unsigned arm64 build, as it does today. The FuseOptionsV1 doc's claim that the ad-hoc signature is re-applied automatically after flipping fuses does not match the code.
  • Who should set mac.asarIntegrityDigest: false: anyone who changes app.asar or Info.plist after afterPack, signs the app themselves in afterPack (the ad-hoc re-sign replaces the framework signature), or merges separately built x64 and arm64 apps with @electron/universal themselves (the per-arch framework _CodeSignature makes the slices differ). --prepackaged apps are not modified.
  • The digest only has a runtime effect with the enableEmbeddedAsarIntegrityValidation fuse on (Electron reads the slot only then). A digest mismatch fails with the same Failed to get integrity for validatable asar archive message as a missing entry; a stale app.asar hash fails with Integrity check failed for asar archive instead.
  • Classified as a minor feature, like the default-on nativeModules.verifyNativeBinaries, and documented in the same v27 behavior-change places.

mmaietta and others added 10 commits October 19, 2026 21:51
…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-bot

changeset-bot Bot commented Oct 20, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 2bc5877

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 8 packages
Name Type
app-builder-lib Minor
dmg-builder Minor
electron-builder-squirrel-windows Minor
electron-builder Minor
electron-forge-maker-appimage Minor
electron-forge-maker-nsis-web Minor
electron-forge-maker-nsis Minor
electron-forge-maker-snap Minor

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>
@mmaietta
mmaietta marked this pull request as ready for review October 20, 2026 14:27
…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

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code review found no issues

No high-confidence issues detected in this change.

@mmaietta
mmaietta merged commit 4cd8a92 into master Oct 21, 2026
59 of 60 checks passed
@mmaietta
mmaietta deleted the feat/mac-asar-integrity-digest branch October 21, 2026 02:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support for Electron v41 ASAR Integrity Digests for macOS

3 participants

⌂ 换网址