feat(bundlers): opt-in app:// protocol for serving packaged renderers

[erickzhao]

• I have read the contribution documentation for this project.
• I agree to follow the code of conduct that this project follows, as appropriate.
• The changes are appropriately documented (if applicable).
• The changes have sufficient test coverage (if applicable).
• The testsuite passes successfully on my local machine (if applicable).

Summarize your changes:

Adds an opt-in appProtocol option to plugin-vite and plugin-webpack that serves packaged renderer files over a privileged custom scheme (default app://) instead of file://, per Electron's security recommendations — file:// pages get an opaque origin, which breaks fetch() of local resources and origin-scoped storage.

// forge.config.js
{
  name: '@electron-forge/plugin-vite', // or plugin-webpack
  config: {
    build: [/* ... */],
    renderer: [/* ... */],

    // simplest form: serve renderers over app:// in packaged apps
    appProtocol: true,

    // or the object form:
    appProtocol: {
      scheme: 'myapp', // default: 'app' — validated at build time
      additionalPrivilegedSchemes: [
        { scheme: 'media', privileges: { stream: true } },
      ],
    },
  },
}

The protocol boilerplate (scheme registration, protocol.handle with a renderer-name allowlist and path traversal guard) lives once in @electron-forge/core-utils and is injected into production main-process bundles as a banner, rather than being duplicated into every scaffolded app where it would drift. Templates stay minimal: the Vite templates collapse to a single mainWindow.loadURL(MAIN_WINDOW_VITE_ENTRY) (new define: dev-server URL in dev, app:// URL in prod); the webpack templates only add appProtocol: true.

Notes:

• Opt-in only — existing apps are unaffected. Dev mode keeps dev-server URLs; webpack JS-only entries keep file://; the base template is untouched.
• The banner runs before any user code, so registerSchemesAsPrivileged happens before ready and the handler is registered ahead of any user loadURL. Since that call is once-per-app, additionalPrivilegedSchemes folds an app's own privileged schemes into it.
• scheme is validated at build time (lowercase RFC 3986 syntax, not a scheme Chromium/Electron claim). It becomes part of the renderer's origin, so renaming after release orphans origin-scoped data — documented accordingly.

Verified by unit specs, real builds through both pipelines, and a new Verdaccio e2e test that packages each bundler template, launches the binary, and asserts the renderer was served from app:// (it caught a real config-plumbing bug during development, fixed here). The custom-scheme path is also verified in a packaged asar app.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JHmXuuGMGg1bcCCYDNVSKW

[MarshallOfSound]

Comments inline. The webpack publicPath one is the big one, I think packaged webpack template apps do not load their JS at all with this. The rest is smaller.

[erickzhao]

Thanks for the thorough review — all ten findings are addressed in c9d72b0.

The big one (webpack publicPath): confirmed real. Served renderers now share the .webpack/renderer/ origin root with publicPath: '/' (Web-target compilations only, mirroring how the dev server already serves them), and entry URLs carry the per-entry subdirectory (app://main_window/main_window/index.html). Per-entry publicPath can't work since one compilation serves multiple entries, so the shared root was the viable option of the two you sketched. The Verdaccio probe now proves the renderer bundle executed — the renderer script posts a message, the preload forwards it with window.location.href over IPC — so an app whose subresources 404 fails the test; all four bundler templates pass it packaged.

The rest, briefly:

• Non-browser main-target bundles: if (process.type !== 'browser') return; guard (took the cheap fix — the plugin config can't distinguish the real main entry from workers).
• output.banner fragility: moved to a Forge-owned Vite plugin whose outputOptions hook composes with a user's banner, and the runtime carries its own leading 'use strict'; so the bundle's prologue stays effective (also applies to the webpack BannerPlugin path).
• Dev/prod privilege parity: both plugins now emit a registration-only runtime in dev (schemes registered, no handler), which also makes webpack validate the config under start like vite does.
• nodeIntegration renderers stay on file:// (kept AssetRelocatorPatch untouched).
• *_VITE_ENTRY resolves to a file:// expression in builds without appProtocol, so it's always a valid URL.
• Serving-scheme privileges: defaults now include stream + codeCache, and the object form accepts a privileges override merged over them.
• Validation: scheme syntax applies to additionalPrivilegedSchemes entries; renderer names are validated as URL hosts with a message pointing at the constraint.
• decodeURIComponent wrapped, malformed escapes return 400; the mangled timeout comment is fixed (vitest options-object form so the formatter can't collapse it again).

---

Generated by Claude Code

[felixrieseberg]

I suspect this to end up being a little unergonomic and believe some apps will want to handle protocol registration themselves while still wanting app:// for Vite resources.

Not a blocker though, just something I'm noticing.

[erickzhao]

@felixrieseberg on apps wanting to own registration while keeping app:// serving — agreed that funneling every privileged scheme through Forge config is the least ergonomic part of this design. It follows from registerSchemesAsPrivileged being once-per-app and needing to run before ready, which forces a single owner; the injected runtime claimed that role so the common case stays zero-config.

A clean escape hatch would be an opt-out like appProtocol: { registerSchemes: false }: Forge injects only the protocol.handle serving part, and the app makes its own registerSchemesAsPrivileged call (which must then include the serving scheme — we'd export the default privileges so that's one spread rather than folklore). That splits ownership exactly along the line you're describing: the app owns the registration call, Forge owns serving. Happy to add it to this PR if you and @MarshallOfSound think it's worth the extra surface now, or leave it as a documented follow-up since the current object form covers the known cases.

---

Generated by Claude Code

[felixrieseberg]

Seems fine. Some bike-shedding things that I don't think deserve blocking on:

• I'd love an easy way for apps to not get locked out of using registerSchemesAsPrivileged themselves when using the plugin.
• Some minor worries about the API contract but I doubt we'll change it anytime soon

Couldn't find any individual code I'd write differently!

[MarshallOfSound]

Second pass on c9d72b0 and e57a3c5. The earlier stuff looks fixed. A few of these are new from the fix commit itself: the webpack publicPath: '/' on JS-only entries, the file-level 'use strict' on the webpack main bundle, and the *_VITE_ENTRY define breaking Vite < 8.

[MarshallOfSound]

This list is every non-preload-only entry, and the banner validates each one as a URL host. But rendererEntryPoint() only puts isLocalWindow && !nodeIntegration entries on the scheme. JS-only and nodeIntegration entries stay on file://. So a config that was valid before, like { name: 'background worker', js: 'worker.js' } (toEnvironmentVariable supports names with spaces), now throws "cannot be used with appProtocol" in start and package for an entry the scheme never serves. Filter this with the same predicate rendererEntryPoint uses. That also keeps the handler host allowlist to origins that are actually served.

[MarshallOfSound]

Pre-existing on next, but this PR rewrites the comment. It says hotRestart is moot because workers only run when packaging. The dev branch of build() also runs every main and preload target through spawnViteBuildWatch(this.serializableConfig, ...). hotRestart is not in the serialized config, so the worker vite.main.config.ts never installs pluginHotRestart, and the worker IPC has no restart message anyway. hotRestart: true is a silent no-op under start. At minimum the comment is wrong. Real fix is to include hotRestart in serializableConfig and bridge requestAppRestart from the worker to the parent like reload-renderers. Fine as a follow up.

[MarshallOfSound]

Two configs pass resolveAppProtocolConfig and validateRendererNameForAppProtocol but cannot work at runtime, which breaks the "throws rather than emitting a runtime that could never serve a window" contract:

• privileges is spread over the defaults (which now include codeCache: true) with no validation. privileges: { standard: false }, or an additionalPrivilegedSchemes entry with codeCache and no standard, emits a registerSchemesAsPrivileged call that Electron rejects ("Code cache can only be enabled when the custom scheme is registered as standard scheme"). That throws synchronously in the IIFE at the top of the main bundle. standard: false on the serving scheme cannot work with host-based renderer matching anyway. Force or reject it, and reject codeCache without standard.
• RENDERER_NAME_AS_HOST accepts all-numeric names (1, 2024, 1.2, 0x10). standard: true schemes get Chromium IPv4 host canonicalisation, app://1/ becomes app://0.0.0.1/, so the handler rendererName.toLowerCase() === url.hostname check never matches and the window 404s, packaged only. Require at least one letter, or compare against the canonicalised host.

[MarshallOfSound]

Third pass on 852b054. The second pass stuff looks fixed. Four small things left, all in the new serving code and the Vite fallback.

[MarshallOfSound]

The 206 branch takes Content-Type from an 11-entry table and falls back to application/octet-stream. Chromium plays .aac, .mkv, .oga and .weba, and none of them are in the table. So <audio src="app://main_window/narration.aac"> gets an octet-stream 206 on the first range request. Under file:// it got the real type. Any other file that gets a Range request, like an app fetch with a Range header for a .js or .json file, also gets application/octet-stream.

Either only take this branch for known media extensions and let the rest go through net.fetch, or get the type from the same lookup net.fetch uses.

[MarshallOfSound]

On webpack rootIncludesName is false, so root is .webpack/renderer and / maps to .webpack/renderer/index.html. That file is never emitted. The entry URL is app://main_window/main_window/index.html, so the first load works. But app://main_window/ returns 404, and that is what <a href="/">, location.href = '/', or a reload after a router pushes / request. Vite does not have this problem because its root is the renderer directory.

When rootIncludesName is false, map / to path.join(name, 'index.html').

[MarshallOfSound]

name goes into a single-quoted JS string here with no escaping. validateRendererNameForAppProtocol only runs on the appProtocol branch. So a renderer named won't-fix gives an invalid define, and the main build fails with an oxc parse error that points at the define and not at the config. VITE_NAME above already uses JSON.stringify. Do the same here:

`require('node:url').pathToFileURL(require('node:path').join(__dirname, ${JSON.stringify(`../renderer/${name}/index.html`)})).href`

[MarshallOfSound]

relative.startsWith('..') also matches a file inside root whose name starts with .., like ..manifest.json. That file gets a 404. Bundlers do not usually emit names like that, so this is minor. But this code is injected and apps cannot patch it. Use relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative).

[claude]

Beyond the two inline findings, I checked whether webpack's appProtocol served/unserved split at WebpackConfig.ts (buildRendererConfigs and the banner allowlist) mishandles nodeIntegration: true window entries the way rendererEntryPoint does — it doesn't; those entries are still correctly excluded from the app:// path. I also checked that additionalPrivilegedSchemes entries skip the RESERVED_SCHEMES check applied to the main scheme — confirmed true, but low severity (self-inflicted misconfiguration, not a security bypass).

Extended reasoning...

This is a targeted, narrow addition beyond the two confirmed inline findings (mis-cased supportFetchApi and case-insensitive renderer-name collisions), which are already being posted as inline comments and should not be restated here. I independently verified from the current diff/HEAD state that the most recent third-party reviewer round (MarshallOfSound's 2026-09-03T23:25 comments on app-protocol.ts:446/402/405 and vite.base.config.ts:104) was concretely addressed by the immediate follow-up commit 0e5ebcc four minutes later — the media-type Range handling, root/index.html mapping, traversal-guard tightening, and JSON.stringify path escaping in that commit's diff line up exactly with those four comment locations. That rules out those specific third-party objections as still-open blockers, but does not change the overall picture: this PR is a large, security-sensitive change (custom privileged scheme registration, protocol handler with a path-traversal guard, banner code injected into every main-process bundle) that has already been through three rounds of reviewer feedback and still has two live, confirmed correctness/security-relevant findings in the current HEAD. Given the findings-present branch of the decision guidance, a full defer/approve review body is not appropriate; only the narrow "ruled out beyond the findings" exception applies, and I have two concrete, verified items to report there (the webpack nodeIntegration split behaving correctly, and the additionalPrivilegedSchemes reserved-scheme gap being real but low severity) that were not already surfaced by the posted findings or ruled-out list restated verbatim.

Findings marked 🟡 are optional suggestions and need no follow-up push.

[claude]

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

Beyond the inline finding, I checked a few other candidates and ruled them out: additionalPrivilegedSchemes bypassing RESERVED_SCHEMES isn't actually possible since scheme collision with the serving scheme is still checked separately; the *_VITE_ENTRY becoming undefined when appProtocol is off matches existing (pre-PR) dev-mode behavior, not a regression; and the webpack prod publicPath split correctly only ever sees nodeIntegration:false entries by the time it runs, since getRendererConfig has already routed nodeIntegration:true entries to the electronRenderer target bucket.

Extended reasoning...

This run's new confirmed finding is a real ordering bug in packages/plugin/webpack/src/WebpackConfig.ts where splitting Web-target entry points into served/unserved compilations for appProtocol breaks the positional index alignment that WebpackPlugin.ts's runWebpack/writeJSONStats relies on between stats.stats[index] and rendererOptions.entryPoints[index].name, causing JSON stats (and potentially other index-based lookups) to be written under the wrong entry name whenever a Web-target renderer group mixes served and unserved entries. This is a legitimate, non-trivial bug in security/build-pipeline-adjacent code that a human should look at before merge.

Separately, the two issues I flagged in my own prior reviews on this PR (the supportFetchApi/supportFetchAPI mis-casing that silently disabled Fetch API support for app:// origins, and the case-insensitive renderer-name collision that could let two windows resolve to the same origin) have both been fixed in the current code: supportFetchAPI is now correctly capitalized throughout app-protocol.ts, and getAppProtocolBanner now explicitly tracks seenHosts and throws a build-time error when two renderer names collide after lowercasing.

I also examined three additional candidates raised in this run's investigation and ruled them out as non-issues, as summarized in the body above.

Given there is an unresolved confirmed finding, plus multiple third-party (MarshallOfSound) review threads from the most recent 2026-09-03 review that show no clear resolution marker, this is not a case for approval. The one-sentence-verdict + ruled-out-note format is used here per the exception for findings-present runs where additional concrete items were checked and ruled out.

[claude]

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

Still open from earlier reviews (1):

• Unresolved: 1 minor or pre-existing.

[claude]

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

Beyond the inline finding, I looked at two more candidates and ruled them out: the Vite<8 console.warn only fires in the narrow case where appProtocol is off and the Vite major is <8 (not unconditionally on every build), and additionalPrivilegedSchemes entries aren't checked against RESERVED_SCHEMES here, but registerSchemesAsPrivileged validates schemes itself at startup rather than silently accepting a bogus one.

Extended reasoning...

This run confirmed a real bug (the vite.base.config.ts:107 VITE_ENTRY define hardcodes a CJS require(...) expression regardless of the main bundle's actual output format, which will be posted inline) and found additional verified findings not being posted here. Given that, plus prior unresolved objections from a human reviewer (MarshallOfSound) on earlier pushes that are not clearly addressed by later commits, approval is not appropriate. Beyond the posted finding, I re-read getBuildDefine() in vite.base.config.ts and confirmed the console.warn is correctly scoped to the appProtocol off + Vite<8 branch only, not emitted unconditionally, so that candidate is not a bug. I also read resolveAppProtocolConfig in app-protocol.ts and confirmed additionalPrivilegedSchemes entries skip the RESERVED_SCHEMES check that the main scheme gets, but Electron's own registerSchemesAsPrivileged validates scheme names and privilege combinations at call time, so a reserved scheme there would surface as a startup error rather than a silent security gap — a lower-severity gap than the posted finding, appropriately left out of the inline comments.

Still open from earlier reviews (1):

• Unresolved: 1 minor or pre-existing.

[claude]

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

[claude]

I reviewed this PR and found no new bugs this round. Because it's a large, security-sensitive change (custom protocol registration, path-traversal-guarded file serving, and format-aware banner injection across both bundlers), a human look is still worthwhile before merging.

Reviewed: app-protocol.ts's scheme/privilege validation and traversal guard, the webpack/vite served-vs-unserved entry wiring and publicPath handling, and the jsonStats/entry-naming logic. Confirmed the previously flagged supportFetchApi casing bug, renderer-name case collisions, webpack jsonStats filename collisions, and the CJS-only banner/VITE_ENTRY format assumptions are now fixed in the current HEAD.

Extended reasoning...

Overview

This PR adds an opt-in appProtocol feature (serving packaged renderers over a privileged app:// scheme) shared by @ electron-forge/core-utils, plugin-webpack, and plugin-vite, plus template updates. It has gone through roughly seven review rounds (human reviewer MarshallOfSound plus this bot across multiple pushes) since 2026-08-27, with real, non-trivial bugs surfacing and being fixed each round: a mis-cased supportFetchAPI privilege that silently disabled the feature's headline fetch() benefit, case-colliding renderer names resolving to the same origin, webpack jsonStats files colliding across preload/served-vs-unserved compilations, and CJS-only assumptions in the Vite VITE_ENTRY define/banner that would crash ESM main bundles. All of these — including the ones I raised in my last review (app-protocol.ts casing, vite.main.config.ts format-awareness) — are addressed by the four most recent commits (1d0c72a, 406335f, 001d8df, 0b0b749, 2b908d6), which I traced against the current file contents.

Security risks

The feature intentionally exposes a new attack surface: a custom protocol handler serving files from the packaged app's install directory, gated by a path-traversal guard and a renderer-name allowlist derived from URL hostname matching. I re-checked the traversal guard and the renderer-name-to-host validation (including the IPv4-like-name and case-collision checks added in later commits) and they look internally consistent with the runtime's case-insensitive hostname matching. I did not attempt to independently fuzz the traversal guard or the Range-request handling beyond reading the code and the specs that exercise it.

Level of scrutiny

Given the security-sensitive nature (custom protocol registration is a once-per-app, hard-to-change-later commitment, and file-serving logic is a classic place for traversal bugs) and the sheer size of the diff (2383 insertions across 30 files touching two bundler plugins plus a new shared core-utils module), this warrants a human review pass even though this automated run found nothing new. Three of MarshallOfSound's inline threads (WebpackConfig.ts:290, VitePlugin.ts:356, app-protocol.ts:270) remain marked unresolved in the thread metadata, but commit 852b054 — pushed minutes after that review round — has commit-message language ("Only validate and allowlist renderer names the scheme actually serves", "Reject privileges that cannot work at runtime: standard: false... codeCache without standard", "Correct the serializableConfig comment about hotRestart") that closely matches those line locations, so they were plausibly addressed even though the GitHub threads were never manually resolved.

Other factors

Test coverage is extensive (new/updated unit specs for every module touched, plus new Verdaccio e2e tests for all four templates), and the author notes the e2e test caught a real config-plumbing bug during development. Given the iteration history and remaining complexity, I'm deferring rather than approving, but I'm not raising a new finding since none was found this round.