* Let a launch leave Web Audio output unmodified The launchers seed Web Audio noise per identity so a returning identity reproduces its audio hash. A caller who wanted stock audio output had to pass audio:seed in config, and NewContext contexts still drew their own seed. audio_noise (default True, as before) set to False sends seed 0, which audio-fingerprint-manager.patch reads as no noise, and NewBrowser records it so NewContext gives its contexts seed 0 as well. An audio:seed the caller sets wins either way. Python and TypeScript take the option the same way, the launch goldens gain an audio_noise_false scenario, and both package READMEs list it. On v158.0-beta.40 an OfflineAudioContext probe renders the same with audio_noise=False across launches, in the page and in a NewContext, and matches a launch with audio:seed 0; default launches differ. Split out of #890, without its gpu_passthrough option. Co-Authored-By: coffeegrind123 <103264516+coffeegrind123@users.noreply.github.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Let a context turn its Web Audio noise off A context without an audio seed of its own takes the launch's audio:seed, so a per-context seed of 0 means "the launch's seed", not "no noise". On a browser launched with noise, no context could render stock audio. setAudioFingerprintNoise(false) stores that choice for the calling context, and AudioFingerprintManager::GetSeed returns 0 for it whatever the launch seed. The setter has its own gate and is sealed with the others; the build tester and the setter-seal guard list it. The context-audio-off guard renders an OfflineAudioContext with the noise off at launch as the reference, then on a noised launch requires a context that called the setter to match it, also after a navigation, while a plain context and a NewContext context stay noised. It fails on v158.0-beta.40, which has no such setter. Both patches were regenerated from a tree of the files the series touches, and the whole series applies to vanilla 158 without fuzz. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Replace audio_noise with fingerprint_options The launchers take one option for the noise Camoufox adds on top of an identity, in Python and TypeScript alike: fingerprint_options={"audio": {"noise": False}} # stock Web Audio fingerprint_options={"audio": {"seed": 1000433}} # fixed audio seed fingerprint_options={"canvas": {"randomize": True}} Without an audio entry the seed still follows the identity; without a canvas entry randomization is still on for another OS or GPU. Any other surface or key raises InvalidFingerprintOptions, naming the tribal rules that keep canvas pixels and glyph spacing unnoised, as do a seed outside 1 to 2**32-1 and noise off together with a seed. fingerprint= stays the fpgen identity. canvas_noise= and config={"audio:seed": N} keep working with a FutureWarning, as a deprecated GeoIP source does; either one together with the matching fingerprint_options entry raises. NewContext takes the audio entry per context. Without one a context follows the browser, read from the audio:seed the launch sent, so launch_options() and from_options launches behave the same: no noise if the launch sent 0, otherwise a fresh seed of its own. A context never takes the browser's seed, fixed or not, since two devices sharing an audio hash are linked; a per-context seed reproduces a context instead. A context with its noise off calls setAudioFingerprintNoise(false). On a noised browser that needs a build with the setter: NewContext asks the browser once, from an init script in a throwaway context, and raises on an older build rather than leave the context noised. canvas in a context raises: randomization belongs to the browser. audio_noise, context_audio(browser) and _camoufox_audio_noise are gone. The launch goldens replace audio_noise_false with audio and canvas scenarios, the init-script golden gains a seed-0 case, and the READMEs, AGENTS.md and docs/per-context-patches.md describe the option; repo callers of canvas_noise use the new form. On v158.0-beta.40, an OfflineAudioContext probe renders the same with {"audio": {"noise": False}} in the page, in a NewContext and with config audio:seed 0; default launches differ; seed 1000433 and a context seed reproduce across launches; a context turning its noise off on a noised browser raises. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Audio renders as stock: remove the noise, the seed and fingerprint_options Stock Firefox has one audio fingerprint per CPU architecture. 103 runs of Firefox 152-158 on 12 CPUs gave 35.749972093850374 on every x86-64 machine and 35.74996626004577 on every ARM64 one, whatever the OS, sound device, sample rate or version. The per-identity noise put every Camoufox identity on a value no real machine renders. Browser: audio-fingerprint-manager.patch is gone, with setAudioFingerprintSeed and setAudioFingerprintNoise; font-list-spoofing, webrtc-ip-spoofing and window-setter-seal are regenerated without its context (the series applies cleanly to vanilla 158). audio:seed is marked removed in properties.json. Library (py and ts): no seed is derived or drawn, and config or config_overrides carrying audio:seed raise InvalidPropertyType pointing at the new tribal rule. fingerprint_options, never released, is reverted; canvas_noise stays as released. Tests: tribal rule audio-is-not-noised with its test; the audio-matches-stock guard replaces context-audio-off and audio-frequency-noise, holding the fpjs buffer, AnalyserNode, biquad and sine renders to the recorded stock values in several contexts and two launches while sending the seed released libraries send. build-tester counts the audio hash as must-match and fails its noise trap. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * A removed audio:seed warns and is dropped; the rule lists each machine Passing audio:seed in config (or a NewContext config_overrides) no longer raises. Both launchers drop the key and emit one FutureWarning from warnings.yml (audio_seed_removed): the option was removed and audio is rendered exactly as stock Firefox renders it. The caller's dict is left as it was. Tests on both sides check the single warning and a normal launch; the launch golden records the warning in order. audio-is-not-noised now lists the evidence per machine and architecture, including the Raspberry Pi 4 runs (106 runs: 45 ARM64, 61 x86-64), the device swap, fpgen's share and what the noise produced. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: coffeegrind123 <103264516+coffeegrind123@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
17 KiB
Firefox Patch Upgrading Guide
How to update Camoufox's patches when browser/upstream.sh moves to a new Firefox
version. Patches break because Firefox renames APIs, moves code and shifts line
numbers; this guide covers finding and fixing those rejects.
Table of Contents
- Understanding the Patch System
- The Source Tree and Its Make Targets
- General Workflow
- Fixing Common Reject Types
- Per-Context Machinery
- Porting Playwright
- Testing and Validation
- Pitfalls
Understanding the Patch System
Patch Categories
All patches live under browser/patches/, and browser/scripts/patch.py applies every
*.patch in it (subdirectories included), sorted by file name:
- Playwright:
playwright/0-playwright.patch(Juggler integration) andplaywright/1-leak-fixes.patch. Their names sort first, and every other patch is written against a tree that already has them. - Feature patches:
webrtc-ip-spoofing.patch,anti-font-fingerprinting.patch, etc. Per-user-context (per-Playwright-context) support is built into each one. librewolf/,ghostery/: patches taken from those projects.
Compile-time dependencies between patches (MaskConfig, RoverfoxStorageManager)
are listed in browser/patches/patch-dependencies.md.
Key Infrastructure Files
- RoverfoxStorageManager.cpp/h: Thread-safe key-value storage for per-context data
- Manager Classes: FontListManager, WebRTCIPManager, etc.
- Window.webidl: Exposes the per-context setters to Playwright
The Source Tree and Its Make Targets
The Firefox tree is browser/camoufox-<version>-<release>/ (from
browser/upstream.sh). It is a git repository whose unpatched tag is plain
Firefox plus browser/additions/ and browser/settings/. Run every target, and
every command in this guide that does not say otherwise, from browser/:
| Target | What it does |
|---|---|
make dir |
Fetches and extracts Firefox if the tree is missing. Otherwise resets it to unpatched, runs mach clobber and git clean -fdx (the object directory goes too), re-copies additions, then applies every patch and lists the ones that left rejects. |
make revert |
git reset --hard unpatched. Untracked files stay, including new files that patches created. |
make clean |
mach clobber, git clean -fdx, then make revert: unpatched Firefox with nothing left over, without re-fetching. |
make patch ./patches/x.patch |
Applies one patch (patch -p1). |
make unpatch ./patches/x.patch |
Reverses one patch. |
make first-checkpoint |
Commits the current tree and tags it first-checkpoint. |
make workspace ./patches/x.patch |
Unapplies x if it is applied, runs first-checkpoint, then applies x again, so the working tree differs from the checkpoint by exactly that patch. |
make diff |
git diff first-checkpoint. Redirect it into the patch file. |
make checkpoint |
Commits tracked changes, keeping the first-checkpoint tag where it is. |
make grep <text> |
Searches the top-level patches for a string. |
make build |
./mach build (runs make dir first if the tree was never prepared). |
make run |
Runs the build with debug on in CAMOU_CONFIG; wipes ~/.camoufox. args="..." passes arguments. |
make path |
Prints the built camoufox-bin. |
make stage-fonts |
Stages the font bundle into the unpackaged build, which tests through the launchers need. |
make tests |
The Playwright suite against the build (headful=true for headed). |
make help |
Lists every target. |
git diff does not show untracked files. Before make diff, mark new files
with git add -N <file> inside the source tree, or they will be missing from
the patch.
General Workflow
Step 1: Bump the Version and Find the Broken Patches
Update version and release in browser/upstream.sh, then:
make dir
patch.py applies every patch and ends with a list of the ones that failed and
their reject files. It deletes the .rej files after listing them, so reproduce
each failure one patch at a time (Step 2).
Step 2: Set Up One Patch
Start from a clean unpatched tree, apply what the patch builds on (at least the
Playwright patches, plus anything from browser/patches/patch-dependencies.md),
checkpoint, then apply the broken patch. Use make clean rather than
make revert here: files that other patches created survive a revert and make
patch stop on "previously applied" prompts.
make clean
make patch ./patches/playwright/0-playwright.patch
make patch ./patches/playwright/1-leak-fixes.patch
make first-checkpoint
make patch ./patches/patch-name.patch # fails, leaving .rej files
Find the reject files:
cd camoufox-<version>-<release>
find . -name '*.rej' -type f
Step 3: Analyze Each Reject File
Read the reject file to understand what failed:
cat path/to/file.cpp.rej
Reject files show:
@@lines: Line numbers where patch expected to apply-lines: What the patch expected to find (old code)+lines: What the patch wanted to add (new code)
Step 4: Locate the Correct Position in Firefox Code
The line numbers in rejects are usually wrong for the new Firefox version. You need to:
- Search for unique context around the reject
- Understand what the patch is doing
- Find equivalent location in new Firefox code
Step 5: Apply Changes Manually
Edit the file to make the rejected change at the correct location.
Step 6: Remove Reject Files
After fixing all rejects, delete the .rej files and any .orig backups
patch left, so they do not end up in the diff:
find . -name '*.rej' -o -name '*.orig' | xargs rm -f
Step 7: Write the Updated Patch
From browser/:
(cd camoufox-<version>-<release> && git add -N path/to/new/file.cpp) # new files only
make diff > patches/patch-name.patch
Step 8: Verify
Run make dir again. The patch should no longer be listed as failing.
Fixing Common Reject Types
Type 1: Include Directive Rejects
Symptom: Reject shows failed #include additions
Example Reject:
@@ -325,6 +325,7 @@
#include "xpcpublic.h"
+#include "WebRTCIPManager.h"
#include "nsDocShell.h"
How to Fix:
- Read the actual file to find the includes section
- Search for nearby includes (e.g.,
xpcpublic.h) - Add the new include in the appropriate location
- Firefox include order: system headers, then Mozilla headers, alphabetically within groups
Example:
// Find this in the actual file:
#include "xpcpublic.h"
// Add the missing includes after it:
#include "xpcpublic.h"
#include "WebRTCIPManager.h"
#include "nsDocShell.h"
#include "mozilla/OriginAttributes.h"
Type 2: Function Signature Changes
Symptom: Reject shows function call with changed parameters
Example Reject:
- mouseOrPointerEvent.mButton = aButton;
+ mouseOrPointerEvent.mJugglerEventId = aMouseEventData.mJugglerEventId;
Common Causes:
- Firefox refactored the API
- Parameters moved from individual args to struct/data object
- Parameter order changed
How to Fix:
- Search for the function definition in Firefox source
- Understand the new API structure
- Port the patch logic to the new API
Example - Firefox 146 Mouse Event Refactoring:
Old Firefox 144 API (individual parameters):
void SynthesizeMouseEvent(int x, int y, int button, ...)
New Firefox 146 API (structured data):
void SynthesizeMouseEvent(SynthesizeMouseEventData& aData,
SynthesizeMouseEventOptions& aOptions)
Port the patch:
// Old patch code:
mouseEvent.mButton = aButton;
mouseEvent.jugglerEventId = aJugglerEventId;
// New patch code for Firefox 146:
mouseOrPointerEvent.mButton = aMouseEventData.mButton;
mouseOrPointerEvent.mJugglerEventId = aMouseEventData.mJugglerEventId;
mouseOrPointerEvent.convertToPointer = aOptions.mConvertToPointer;
Type 3: Missing Context - Code Moved
Symptom: Reject shows context that doesn't exist in the file
How to Fix:
- Use grep to search for unique function names or variables in the reject
- Find where Firefox moved the code
- Apply the patch to the new location
# Search across the codebase
grep -r "FunctionName" camoufox-<version>/ --include="*.cpp"
Type 4: New Parameter Added to Function Calls
Symptom: Reject shows function call, but Firefox added/removed parameters
Example - MakeTextRun userContextId:
Old call:
MakeTextRun(text, len, drawTarget, appUnitsPerDevPixel, flags, recorder);
New Firefox expects:
MakeTextRun(text, len, drawTarget, appUnitsPerDevPixel, flags, recorder, userContextId);
How to Fix:
- Extract userContextId from available context (Document, PresContext, etc.)
- Add proper extraction code before the call
- Pass userContextId as the last parameter
userContextId extraction: the per-context patches resolve it from the
BrowsingContext, which exists before the document's attributes are set:
uint32_t userContextId = 0;
if (BrowsingContext* bc = win->GetBrowsingContext()) {
userContextId = bc->OriginAttributesRef().mUserContextId;
}
MakeTextRun(..., userContextId);
Workers use WorkerPrivate::GetOriginAttributes() instead.
Type 5: Line Number Shifts (No Code Changes)
Symptom: Reject shows patch tried to apply at wrong line number, but code is identical
How to Fix:
Simply apply the patch manually at the correct line number. The code hasn't changed, just the location.
Per-Context Machinery
Most spoofing patches carry per-context support. When porting one, expect these pieces:
-
Manager classes (e.g., FontListManager, WebRTCIPManager):
- Store per-context settings using RoverfoxStorageManager
- Gate their setter with
RoverfoxStorageManager::IsSetterOfferedandMarkSetterUsed
-
Window.webidl functions:
- JavaScript APIs exposed to Playwright
- Examples:
setFontList(),setWebRTCIPv4()
-
nsGlobalWindowInner.cpp implementations:
- Extract userContextId from window/document/docshell
- Call manager classes
- Remove the setter after use with
RoverfoxStorageManager::RemoveSetter
-
Core logic changes:
- Consult the per-context manager before the global config (MaskConfig)
- Pass userContextId through call chains
See per-context-patches.md for the full list.
Porting Playwright
The two Playwright patches (browser/patches/playwright/)
and Camoufox's Juggler (browser/additions/juggler/) both started from upstream
Playwright and both carry Camoufox changes: fixes to Juggler's input and
navigation paths, the isolated-world page agent, and the human cursor
(input/). Port upstream changes into them; never copy upstream over them.
The Bootstrap Patch
Compare what changed in Playwright's bootstrap.diff since the last sync, then port it like any other patch:
make dir
make workspace ./patches/playwright/0-playwright.patch
# port the upstream changes into camoufox-<version>-<release>/
make diff > patches/playwright/0-playwright.patch
Juggler
git clone https://github.com/microsoft/playwright.git /tmp/playwright
diff -r additions/juggler/ /tmp/playwright/browser_patches/firefox/juggler/
Port the upstream hunks one by one, keeping the Camoufox changes. Then check:
-
components/Juggler.jsstill exportsJugglerFactory. -
components/components.confregisters it withesModule(Firefox no longer supportsjsm) and"constructor": "JugglerFactory":{ "esModule": "resource://gre/modules/juggler/components/Juggler.js", "constructor": "JugglerFactory", } -
Every file upstream added or renamed is listed in
FINAL_TARGET_FILESinjuggler/moz.build, and everyChromeUtils.importESModule()path still exists. Upstream registers ajugglerchrome package injar.mn; Camoufox does not, because a page can detect one (seejuggler/moz.build), so upstream'schrome://juggler/content/paths becomeresource://gre/modules/juggler/.
Then make dir && make build && make tests. A wrong components.conf shows up
as one of these:
| Error | Cause |
|---|---|
undefined symbol: ... mozCreateComponent<nsICommandLineHandler>() at link time |
components.conf is not an ESM component |
Externally-constructed components may not specify 'constructor' or 'legacy_constructor' properties |
It uses jsm instead of esModule |
Externally-constructed components must specify a type other than nsISupports |
It is an external component with no type; make it an ESM component |
JavaScript components must specify a constructor |
The constructor field is missing |
Testing and Validation
Minimal Verification
After updating a patch, always verify:
-
Every patch applies cleanly:
make dirlists no failures. -
Build compiles (if feasible):
make build
Full Testing
Run the suites that cover the patch (see ci/README.md).
From the repository root,
python3 -m ci.run_patch_guards --binary <camoufox-bin> is the most direct
evidence that a patch which still applies was not neutered by the upgrade.
Browser-Owned GPU Values
The launchers build WebGL from fpgen's recordings, which an older Firefox made.
Some values are the browser's rather than the GPU's, and an upgrade can change
them on every device: Firefox 156 added EXT_depth_clamp on Windows and fixed
WebGL1's ALIASED_LINE_WIDTH_RANGE at [1, 1] on Linux
(webgl-browser-owned-values-follow-firefox).
Firefox 158 added EXT_polygon_offset_clamp on Windows devices with WebGL2
(ANGLE's D3D11 backend at feature level 10_0 and above) and on Linux desktop GL,
but not on macOS, where release builds use CGL's GL 4.1. The
stock-gpu-parity guard finds them. It runs stock Firefox of the new version,
stock Firefox of the release fpgen's model recorded, and Camoufox claiming the
machine's GPU, and fails where the two stock releases differ and Camoufox does
not follow the new one. From the repository root:
python3 -m ci.run_patch_guards --binary <camoufox-bin> --only stock-gpu-parity
CI runs it on Linux with a software renderer. Run it on Windows and macOS too, passing the stock binaries by hand, because each OS has its own graphics backend. From the repository root:
python3 browser/tests/playwright/patches/stock-gpu-parity.py --binary <camoufox-bin> \
--stock <Firefox of upstream.sh's version> --recorded-stock <Firefox of fpgen's release>
For each failure, find in the Firefox source why the value changed and whether
it holds on every device of that backend, then follow it where the launchers
convert a recording (to_config in python/src/camoufox/webgl.py and
typescript/src/webgl.ts).
Pitfalls
| Pitfall | Avoid it by |
|---|---|
| Trusting reject line numbers | Searching for the context lines instead |
Hand-editing a .patch file |
Editing the tree and running make diff |
| Missing new files in the patch | git add -N them before make diff |
| A diff that includes the patch's dependencies | Running make first-checkpoint after applying them and before the patch being fixed |
.rej and .orig files in the diff |
Deleting them first (Step 6) |
| Guessing a value a refactored API now needs | Reading the new Firefox code, or the release notes |
| Fixing several patches in one pass | One patch at a time, each from make clean |
Appendix: Firefox Source Navigation
Finding Files
# Find files by name
find . -name "Navigator.cpp" -type f
# Find files containing a symbol
grep -r "GetAcceptLanguages" . --include="*.cpp"
# Find class definitions
grep -r "class Navigator" . --include="*.h"
Understanding Firefox Code Structure
dom/: DOM implementationdom/base/: Core DOM classes (Window, Document, Navigator, etc.)dom/webidl/: WebIDL interface definitionsdom/media/webrtc/: WebRTC implementation
gfx/: Graphics and font renderinggfx/thebes/: Text rendering (fonts, glyphs, shaping)
layout/: Layout enginelayout/generic/: Text frameslayout/mathml/: MathML rendering
Checklist
- Bump
browser/upstream.shand runmake dirto list the failing patches - Delete the backports the new Firefox ships
- For each:
make clean, apply its dependencies,make first-checkpoint,make patchit - Port each reject to the new Firefox code
- Remove
.rejand.origfiles,git add -Nnew files make diff > patches/<name>.patchmake dirapplies the whole stack cleanly, with no fuzzmake build, then run the patch guards;firefox-version-pinchecks that the build and every identity are the new Firefox- Run
stock-gpu-parityon Linux, Windows and macOS (Browser-Owned GPU Values)
Additional Resources
- Firefox source: https://searchfox.org/
- Firefox API documentation: https://firefox-source-docs.mozilla.org/
- Mercurial repository: https://hg.mozilla.org/mozilla-central/