Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

refactor: one owner for the Chrome user-agent string template, and close the unreduced-version path (PIN-083)

Luigi Agostibe7556b7cad7
diff --git a/internal/handlers/stealth.go b/internal/handlers/stealth.go
index 2221b140..4c83eb1b 100644
--- a/internal/handlers/stealth.go
+++ b/internal/handlers/stealth.go
@@ -126,22 +126,30 @@ func (h *Handlers) generateFingerprint(req fingerprintRequest) fingerprint {
// pins Chrome/144.0.0.0 — a page/post-rotate version drift.
reducedBrowserVersion := stealth.ReducedBrowserVersion(h.Config.BrowserVersion)
+ // The Chrome UA strings come from stealth.ChromeUserAgent, the same template the
+ // launch persona uses, so the frozen OS tokens are spelled out once. mac/safari
+ // stays a literal on purpose: it is a Safari UA, not the Chrome template with a
+ // different OS token, and folding it in would manufacture a false sibling.
+ windowsChrome := stealth.ChromeUserAgent(stealth.PlatformWindows, reducedBrowserVersion)
+ macChrome := stealth.ChromeUserAgent(stealth.PlatformMacOS, reducedBrowserVersion)
+ linuxChrome := stealth.ChromeUserAgent(stealth.PlatformLinux, reducedBrowserVersion)
+
osConfigs := map[string]map[string]fingerprint{
"windows": {
"chrome": {
- UserAgent: fmt.Sprintf("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/%s Safari/537.36", reducedBrowserVersion),
+ UserAgent: windowsChrome,
Platform: "Win32",
Vendor: "Google Inc.",
},
"edge": {
- UserAgent: fmt.Sprintf("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/%s Safari/537.36 Edg/%s", reducedBrowserVersion, reducedBrowserVersion),
+ UserAgent: stealth.EdgeUserAgent(windowsChrome, reducedBrowserVersion),
Platform: "Win32",
Vendor: "Google Inc.",
},
},
"mac": {
"chrome": {
- UserAgent: fmt.Sprintf("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/%s Safari/537.36", reducedBrowserVersion),
+ UserAgent: macChrome,
Platform: "MacIntel",
Vendor: "Google Inc.",
},
@@ -151,6 +159,16 @@ func (h *Handlers) generateFingerprint(req fingerprintRequest) fingerprint {
Vendor: "Apple Computer, Inc.",
},
},
+ // A Linux host asking for a fingerprint used to get a foreign one, since only
+ // windows and mac had entries. os: "random" stays windows-or-mac: adding linux
+ // to the weighted pick would change what a default request returns.
+ "linux": {
+ "chrome": {
+ UserAgent: linuxChrome,
+ Platform: "Linux x86_64",
+ Vendor: "Google Inc.",
+ },
+ },
}
os := req.OS
diff --git a/internal/handlers/stealth_test.go b/internal/handlers/stealth_test.go
index d26f55af..047688ba 100644
--- a/internal/handlers/stealth_test.go
+++ b/internal/handlers/stealth_test.go
@@ -223,3 +223,81 @@ func TestHandleStealthStatus_WithTabOverride(t *testing.T) {
t.Fatalf("expected fingerprintRotateActive=true, got %v", got)
}
}
+
+// The drift this pins already happened once on the version axis and had to be
+// resynced by hand; the OS-token axis was the next one. Comparing against
+// stealth.ChromeUserAgent rather than against a literal is what makes it
+// impossible rather than merely corrected: there is one template, and if it moves,
+// both sides move together or this test fails.
+func TestGenerateFingerprintUsesTheSharedChromeTemplate(t *testing.T) {
+ const version = "144.0.7559.133"
+ h := Handlers{Config: &config.RuntimeConfig{BrowserVersion: version}}
+ reduced := stealth.ReducedBrowserVersion(version)
+
+ for _, tc := range []struct {
+ os, browser string
+ wantPlatform string
+ wantUA string
+ }{
+ {os: "windows", browser: "chrome", wantPlatform: "Win32", wantUA: stealth.ChromeUserAgent(stealth.PlatformWindows, reduced)},
+ {os: "mac", browser: "chrome", wantPlatform: "MacIntel", wantUA: stealth.ChromeUserAgent(stealth.PlatformMacOS, reduced)},
+ {os: "linux", browser: "chrome", wantPlatform: "Linux x86_64", wantUA: stealth.ChromeUserAgent(stealth.PlatformLinux, reduced)},
+ {os: "windows", browser: "edge", wantPlatform: "Win32", wantUA: stealth.EdgeUserAgent(stealth.ChromeUserAgent(stealth.PlatformWindows, reduced), reduced)},
+ } {
+ t.Run(tc.os+"/"+tc.browser, func(t *testing.T) {
+ fp := h.generateFingerprint(fingerprintRequest{OS: tc.os, Browser: tc.browser})
+
+ if fp.UserAgent != tc.wantUA {
+ t.Errorf("user agent =\n %q\nwant the shared template's\n %q", fp.UserAgent, tc.wantUA)
+ }
+ if fp.Platform != tc.wantPlatform {
+ t.Errorf("platform = %q, want %q", fp.Platform, tc.wantPlatform)
+ }
+ // The reduced version is what real Chrome exposes; a full build here is the
+ // exact drift the comment above generateFingerprint was written for.
+ if strings.Contains(fp.UserAgent, version) {
+ t.Errorf("user agent carries the full build %q: %s", version, fp.UserAgent)
+ }
+ })
+ }
+}
+
+// The same template serves the launch persona, so the endpoint and the browser
+// PinchTab actually launches cannot describe different Chromes on the same host.
+func TestGenerateFingerprintAgreesWithTheLaunchPersonaOnThisHost(t *testing.T) {
+ const version = "144.0.7559.133"
+ h := Handlers{Config: &config.RuntimeConfig{BrowserVersion: version}}
+
+ hostOS := map[string]string{
+ stealth.PlatformWindows: "windows",
+ stealth.PlatformMacOS: "mac",
+ stealth.PlatformLinux: "linux",
+ }[stealth.HostPlatform()]
+
+ fp := h.generateFingerprint(fingerprintRequest{OS: hostOS, Browser: "chrome"})
+ persona := stealth.BuildPersona("", version)
+
+ if fp.UserAgent != persona.UserAgent {
+ t.Fatalf("fingerprint endpoint and launch persona disagree on this host:\n endpoint %q\n persona %q", fp.UserAgent, persona.UserAgent)
+ }
+ if fp.Platform != persona.NavigatorPlatform {
+ t.Errorf("platform = %q, want the persona's %q", fp.Platform, persona.NavigatorPlatform)
+ }
+}
+
+// os: "linux" is answerable now; os: "random" is deliberately NOT extended to it,
+// because that would change what a default request returns. This states which.
+func TestGenerateFingerprintRandomStaysWindowsOrMac(t *testing.T) {
+ h := Handlers{Config: &config.RuntimeConfig{BrowserVersion: "144.0.7559.133"}}
+ linuxUA := stealth.ChromeUserAgent(stealth.PlatformLinux, stealth.ReducedBrowserVersion("144.0.7559.133"))
+
+ for i := 0; i < 200; i++ {
+ fp := h.generateFingerprint(fingerprintRequest{OS: "random"})
+ if fp.UserAgent == linuxUA {
+ t.Fatalf("os: random returned the Linux UA; adding linux to the weighted pick changes what a default request returns")
+ }
+ if fp.Platform != "Win32" && fp.Platform != "MacIntel" {
+ t.Fatalf("os: random returned platform %q, want Win32 or MacIntel", fp.Platform)
+ }
+ }
+}
diff --git a/internal/stealth/bundle_test.go b/internal/stealth/bundle_test.go
index 8d984b15..dcdba707 100644
--- a/internal/stealth/bundle_test.go
+++ b/internal/stealth/bundle_test.go
@@ -1,6 +1,9 @@
package stealth
import (
+ "io/fs"
+ "os"
+ "path/filepath"
"strings"
"testing"
@@ -119,13 +122,101 @@ func TestStatusFromBundleDisablesWebGLSpoofingWhenHeaded(t *testing.T) {
}
func TestResolveUserAgent(t *testing.T) {
- if got := ResolveUserAgent("custom-agent", "144.0.0.0"); got != "custom-agent" {
+ if got := resolveUserAgent("custom-agent", "144.0.0.0"); got != "custom-agent" {
t.Fatalf("expected explicit UA to win, got %q", got)
}
- got := ResolveUserAgent("", "144.0.0.0")
+ got := resolveUserAgent("", "144.0.0.0")
if !strings.Contains(got, "Chrome/144.0.0.0") {
t.Fatalf("expected generated UA to include chrome version, got %q", got)
}
+ if want := ChromeUserAgent(HostPlatform(), "144.0.0.0"); got != want {
+ t.Fatalf("generated UA = %q, want the shared template's %q", got, want)
+ }
+}
+
+// One template, three platforms, and the OS tokens spelled out here so a change to
+// either side has to be deliberate. Chrome's UA reduction has moved these frozen
+// tokens before; when it moves them again this is the test that says so.
+func TestChromeUserAgentIsTheOnlyTemplate(t *testing.T) {
+ for _, tc := range []struct{ platform, want string }{
+ {PlatformWindows, "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36"},
+ {PlatformMacOS, "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36"},
+ {PlatformLinux, "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36"},
+ } {
+ t.Run(tc.platform, func(t *testing.T) {
+ if got := ChromeUserAgent(tc.platform, "144.0.0.0"); got != tc.want {
+ t.Errorf("ChromeUserAgent(%q) =\n %q\nwant\n %q", tc.platform, got, tc.want)
+ }
+ })
+ }
+
+ // An unknown platform falls to Linux rather than returning an empty UA: a
+ // persona with no user agent is a worse answer than a plausible one.
+ if got, want := ChromeUserAgent("Android", "144.0.0.0"), ChromeUserAgent(PlatformLinux, "144.0.0.0"); got != want {
+ t.Errorf("unknown platform = %q, want the Linux template %q", got, want)
+ }
+}
+
+// Edge is a decoration over the Chrome result, not a fourth template — asserted by
+// composition so the OS tokens cannot appear in a second place.
+func TestEdgeUserAgentDecoratesTheChromeTemplate(t *testing.T) {
+ chrome := ChromeUserAgent(PlatformWindows, "144.0.0.0")
+
+ got := EdgeUserAgent(chrome, "144.0.0.0")
+
+ if want := chrome + " Edg/144.0.0.0"; got != want {
+ t.Fatalf("EdgeUserAgent = %q, want %q", got, want)
+ }
+ if !strings.HasPrefix(got, chrome) {
+ t.Errorf("Edge UA %q no longer starts with the Chrome UA it decorates", got)
+ }
+}
+
+// The platform is read back out of the UA string, which looks like a round trip on
+// the generated path and is load-bearing on the custom-UA path: nobody selected a
+// platform there, so the string is the only thing that knows. A custom Windows UA on
+// a mac host must still report Win32 — replacing the sniff with the generated
+// platform would report the host's.
+func TestCustomUserAgentPlatformComesFromTheStringNotTheHost(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ userAgent string
+ navigatorPlatform string
+ uaDataPlatform string
+ }{
+ {
+ name: "windows UA",
+ userAgent: ChromeUserAgent(PlatformWindows, "144.0.0.0"),
+ navigatorPlatform: "Win32",
+ uaDataPlatform: PlatformWindows,
+ },
+ {
+ name: "macOS UA",
+ userAgent: ChromeUserAgent(PlatformMacOS, "144.0.0.0"),
+ navigatorPlatform: "MacIntel",
+ uaDataPlatform: PlatformMacOS,
+ },
+ {
+ name: "linux UA",
+ userAgent: ChromeUserAgent(PlatformLinux, "144.0.0.0"),
+ navigatorPlatform: "Linux x86_64",
+ uaDataPlatform: PlatformLinux,
+ },
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ persona := BuildPersona(tc.userAgent, "144.0.7559.133")
+
+ if persona.UserAgent != tc.userAgent {
+ t.Fatalf("custom UA was rewritten: %q", persona.UserAgent)
+ }
+ if persona.NavigatorPlatform != tc.navigatorPlatform {
+ t.Errorf("navigator.platform = %q, want %q for a UA the caller supplied", persona.NavigatorPlatform, tc.navigatorPlatform)
+ }
+ if persona.UserAgentData.Platform != tc.uaDataPlatform {
+ t.Errorf("userAgentData.platform = %q, want %q", persona.UserAgentData.Platform, tc.uaDataPlatform)
+ }
+ })
+ }
}
func TestBuildLaunchContractOwnsStealthLaunchFlags(t *testing.T) {
@@ -294,3 +385,52 @@ func equalStringSlices(a, b []string) bool {
}
return true
}
+
+// chromeTemplateMarker is the part of the Chrome UA that must exist in exactly one
+// place. The parity tests would stay green if a caller kept a byte-identical copy of
+// its own — that is how the two copies this consolidation removed passed for as long
+// as they agreed — so the census is what makes a second owner impossible rather than
+// merely currently-correct.
+const chromeTemplateMarker = "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/"
+
+func TestChromeUserAgentTemplateHasOneOwner(t *testing.T) {
+ root, err := filepath.Abs("../..")
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ owners := map[string]int{}
+ walkErr := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
+ if err != nil {
+ return err
+ }
+ if d.IsDir() || !strings.HasSuffix(path, ".go") || strings.HasSuffix(path, "_test.go") {
+ return nil
+ }
+ raw, readErr := os.ReadFile(path)
+ if readErr != nil {
+ return readErr
+ }
+ if n := strings.Count(string(raw), chromeTemplateMarker); n > 0 {
+ rel, relErr := filepath.Rel(root, path)
+ if relErr != nil {
+ return relErr
+ }
+ owners[filepath.ToSlash(rel)] = n
+ }
+ return nil
+ })
+ if walkErr != nil {
+ t.Fatal(walkErr)
+ }
+
+ const owner = "internal/stealth/ua.go"
+ if len(owners) != 1 || owners[owner] == 0 {
+ t.Fatalf("the Chrome UA template is spelled out in %v, want only %s — a second copy drifts on the frozen OS tokens exactly as the fingerprint endpoint's copy drifted on the version", owners, owner)
+ }
+ // One arm per platform, in one function. A fourth arm means a platform gained a
+ // spelling without going through ChromeUserAgent.
+ if owners[owner] != 3 {
+ t.Errorf("%s spells the template %d times, want 3 (one arm per platform)", owner, owners[owner])
+ }
+}
diff --git a/internal/stealth/ua.go b/internal/stealth/ua.go
index 2ec4c729..372f9e06 100644
--- a/internal/stealth/ua.go
+++ b/internal/stealth/ua.go
@@ -50,24 +50,66 @@ func ReducedBrowserVersion(chromeVersion string) string {
return major + ".0.0.0"
}
-func ResolveUserAgent(userAgent, chromeVersion string) string {
- if userAgent != "" {
- return userAgent
- }
- if chromeVersion == "" {
- return ""
+// The platform vocabulary of the persona: the same values UserAgentDataProfile
+// reports and PlatformVersionFor is keyed on, so a caller names a platform once
+// and every UA fact follows from it.
+const (
+ PlatformWindows = "Windows"
+ PlatformMacOS = "macOS"
+ PlatformLinux = "Linux"
+)
+
+// ChromeUserAgent is the only place the Chrome UA string is spelled out. It is
+// keyed on a platform rather than on GOOS because its two callers select the
+// platform differently — the launch persona from the host, the fingerprint
+// endpoint from the request — and that selection is theirs, not the template's.
+// The frozen OS tokens (Mac OS X 10_15_7, Windows NT 10.0) are what Chrome's UA
+// reduction pins; they have changed before, and a second copy of them is a drift
+// waiting to happen. Callers pass a version already reduced by
+// ReducedBrowserVersion; handing it a full build emits a UA real Chrome never
+// sends.
+func ChromeUserAgent(platform, chromeVersion string) string {
+ switch platform {
+ case PlatformMacOS:
+ return "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/" + chromeVersion + " Safari/537.36"
+ case PlatformWindows:
+ return "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/" + chromeVersion + " Safari/537.36"
+ default:
+ return "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/" + chromeVersion + " Safari/537.36"
}
+}
+// EdgeUserAgent decorates a Chrome UA with Edge's own token, which is what Edge
+// actually sends: the Chrome string plus Edg/<version>. Building it as a fourth
+// template would put the OS tokens in one more place.
+func EdgeUserAgent(chromeUserAgent, chromeVersion string) string {
+ return chromeUserAgent + " Edg/" + chromeVersion
+}
+
+// HostPlatform is the persona platform of the machine this process runs on.
+func HostPlatform() string {
switch goruntime.GOOS {
case "darwin":
- return "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/" + chromeVersion + " Safari/537.36"
+ return PlatformMacOS
case "windows":
- return "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/" + chromeVersion + " Safari/537.36"
+ return PlatformWindows
default:
- return "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/" + chromeVersion + " Safari/537.36"
+ return PlatformLinux
}
}
+// resolveUserAgent honours an explicit custom UA verbatim and otherwise builds the
+// host's. It stays unexported: the only correct entry point is BuildPersona, which
+// reduces the version first — an exported form invites a caller to pass
+// cfg.BrowserVersion straight through and reintroduce the version drift the
+// fingerprint endpoint already had to be resynced for by hand.
+func resolveUserAgent(userAgent, chromeVersion string) string {
+ if userAgent != "" {
+ return userAgent
+ }
+ return ChromeUserAgent(HostPlatform(), chromeVersion)
+}
+
func BuildPersona(userAgent, chromeVersion string) BrowserPersona {
reduced := ReducedBrowserVersion(chromeVersion)
major := reduced
@@ -78,19 +120,17 @@ func BuildPersona(userAgent, chromeVersion string) BrowserPersona {
// exposes the full build in navigator.userAgent — a UA like "Chrome/146.0.7680.80"
// is a fingerprint tell. The full build still lives in the high-entropy UA-CH
// (uaFullVersion / fullVersionList). An explicit custom userAgent is respected
- // verbatim by ResolveUserAgent.
- ua := ResolveUserAgent(userAgent, reduced)
+ // verbatim by resolveUserAgent.
+ ua := resolveUserAgent(userAgent, reduced)
language := "en-US"
languages := []string{"en-US", "en"}
acceptLanguage := "en-US,en"
- if ua == "" {
- return BrowserPersona{
- Language: language,
- Languages: languages,
- AcceptLanguage: acceptLanguage,
- }
- }
+ // The platform is read back out of the UA rather than carried down from the
+ // caller, and that is not a round trip: on the custom-UA path no platform was
+ // ever selected, so the string is the only thing that knows. A custom Windows UA
+ // on a mac host must report Win32, which is why this sniff cannot be replaced by
+ // passing the generated platform through.
navigatorPlatform := "Linux x86_64"
uaDataPlatform := "Linux"
switch {