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.goindex 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.OSdiff --git a/internal/handlers/stealth_test.go b/internal/handlers/stealth_test.goindex 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.goindex 8d984b15..dcdba707 100644--- a/internal/stealth/bundle_test.go+++ b/internal/stealth/bundle_test.go@@ -1,6 +1,9 @@package stealthimport (+ "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.goindex 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 PlatformMacOScase "windows":- return "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/" + chromeVersion + " Safari/537.36"+ return PlatformWindowsdefault:- 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 {