identity

package
v0.0.27 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 28, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package identity provides consistent anti-detection identity profiles.

Every request uses a complete, internally-consistent identity profile where UA + TLS fingerprint + header order + OS + hardware + screen + locale + geo all match. Random UA without matching TLS is worse than no rotation.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddWebRTCConfig 

func AddWebRTCConfig(config map[string]any, proxyExitIP string)

AddWebRTCConfig adds WebRTC IP override to the config when a proxy exit IP is known. This prevents WebRTC from leaking the real IP address.

Types

type Browser 

type Browser string

Browser represents a supported browser type. 

const (
	BrowserFirefox Browser = "firefox"
	BrowserChrome  Browser = "chrome"
)

type BuiltinResolver 

type BuiltinResolver struct{}

BuiltinResolver uses the built-in country table.

Because the builtin resolver has no IP→country database it only handles proxy metadata strings in the form "country:<CODE>" (e.g., "country:DE"). Plain IP addresses return an error — use a real GeoResolver (e.g., MaxMind) for those.

func (*BuiltinResolver) Resolve 

func (r *BuiltinResolver) Resolve(ip string) (*GeoInfo, error)

Resolve parses the "country:<CODE>" tag injected by proxy providers and returns the matching GeoInfo from the built-in table. Any other format (plain IP, CIDR, etc.) returns a descriptive error.

type GeoInfo 

type GeoInfo struct {
	Country   string // ISO 3166-1 alpha-2 (e.g., "US")
	City      string
	Timezone  string   // IANA timezone (e.g., "America/New_York")
	Locale    string   // e.g., "en-US"
	Languages []string // e.g., ["en-US", "en"]
	Lat       float64
	Lng       float64
}

GeoInfo contains geographic information derived from an IP address or country code.

func LookupCountry 

func LookupCountry(countryCode string) (GeoInfo, bool)

LookupCountry returns the built-in GeoInfo for a country code. The second return value is false when the code is not in the table.

type GeoResolver 

type GeoResolver interface {
	Resolve(ip string) (*GeoInfo, error)
}

GeoResolver resolves IP addresses (or tagged strings) to GeoInfo. Implement this interface to plug in a real MaxMind database or any external geo service.

type HTTP2Settings 

type HTTP2Settings struct {
	HeaderTableSize      uint32 `json:"header_table_size"`
	EnablePush           bool   `json:"enable_push"`
	MaxConcurrentStreams uint32 `json:"max_concurrent_streams"`
	InitialWindowSize    uint32 `json:"initial_window_size"`
	MaxFrameSize         uint32 `json:"max_frame_size"`
	MaxHeaderListSize    uint32 `json:"max_header_list_size"`
}

HTTP2Settings holds HTTP/2 connection settings for fingerprinting.

type LocalePolicy added in v0.0.25 

type LocalePolicy int

LocalePolicy controls how the Locale and Languages fields are set relative to proxy geo resolution. 

const (
	// LocalePolicyProxyGeo (default) — locale and languages are derived from
	// the proxy exit IP or country constraint, matching geo-based anti-detection
	// principle #6. This is the existing behavior; it is not changed.
	LocalePolicyProxyGeo LocalePolicy = iota

	// LocalePolicyEnglishDefault — locale is forced to "en-US" and languages
	// to ["en-US", "en"] regardless of proxy geo. Use this when scraping
	// English-language content (SERP, English news, etc.) through a proxy in a
	// non-English-speaking country. Timezone and geo coordinates are still
	// derived from the proxy geo (physical location stays coherent; only
	// language preference is overridden).
	//
	// Example:
	//
	//   id := identity.Generate(
	//       identity.WithCountry("RU"),
	//       identity.WithLocalePolicy(identity.LocalePolicyEnglishDefault),
	//   )
	//   // id.Locale == "en-US", id.Timezone == "Europe/Moscow"
	LocalePolicyEnglishDefault
)

type OS 

type OS string

OS represents a supported operating system. 

const (
	OSWindows OS = "windows"
	OSMacOS   OS = "macos"
	OSLinux   OS = "linux"
)

type Option 

type Option func(*generateConfig)

Option is a functional option for configuring identity generation.

func WithBrowser 

func WithBrowser(b Browser) Option

WithBrowser constrains identity generation to a specific browser.

func WithCountry 

func WithCountry(code string) Option

WithCountry constrains the identity to a specific country by looking up the built-in geo table (or the configured GeoResolver). It is a convenience alternative to WithProxy when the caller knows the country directly. If the country code is unknown the option is silently ignored.

func WithGeo 

func WithGeo(lat, lng float64) Option

WithGeo sets explicit geo coordinates for the identity.

func WithGeoResolver 

func WithGeoResolver(r GeoResolver) Option

WithGeoResolver plugs in a custom GeoResolver so callers can use a real MaxMind database or any external geo service instead of the built-in table. The resolver is called during Generate when WithProxy or WithCountry is set.

func WithLocale 

func WithLocale(locale string, langs ...string) Option

WithLocale sets an explicit locale and languages for the identity.

func WithLocalePolicy added in v0.0.25 

func WithLocalePolicy(policy LocalePolicy) Option

WithLocalePolicy sets the locale assignment policy for the generated identity.

The default policy is LocalePolicyProxyGeo (locale matches proxy IP geo — existing behavior, unchanged). Pass LocalePolicyEnglishDefault when scraping English-language content through proxies in non-English-speaking countries to avoid locale-query mismatch detection.

Note: an explicit WithLocale call takes precedence over any locale policy.

func WithOS 

func WithOS(o OS) Option

WithOS constrains identity generation to a specific operating system.

func WithProxy 

func WithProxy(ip string) Option

WithProxy sets the proxy IP for geo-matching of timezone, locale, and languages.

func WithTimezone 

func WithTimezone(tz string) Option

WithTimezone sets an explicit timezone for the identity.

type Profile 

type Profile struct {
	// Browser identification
	UA          string  `json:"ua"`
	BrowserName Browser `json:"browser_name"`
	BrowserVer  string  `json:"browser_ver"`

	// TLS fingerprint profile that MATCHES the browser
	TLSProfile string `json:"tls_profile"`

	// Header ordering specific to this browser version
	HeaderOrder []string `json:"header_order"`

	// Operating system
	OS        OS     `json:"os"`
	OSVersion string `json:"os_version"`
	Platform  string `json:"platform"`

	// Hardware (consistent with OS)
	Cores  int     `json:"cores"`
	Memory float64 `json:"memory"`
	GPU    string  `json:"gpu"`

	// Screen (common resolution for this OS)
	ScreenW    int     `json:"screen_w"`
	ScreenH    int     `json:"screen_h"`
	ColorDepth int     `json:"color_depth"`
	PixelRatio float64 `json:"pixel_ratio"`

	// Locale (matched to proxy geo)
	Languages []string `json:"languages"`
	Timezone  string   `json:"timezone"`
	Locale    string   `json:"locale"`

	// Geo (derived from proxy IP)
	Lat float64 `json:"lat"`
	Lng float64 `json:"lng"`

	// Camoufox environment configuration
	CamoufoxEnv map[string]string `json:"camoufox_env,omitempty"`
}

Profile contains a complete, internally-consistent identity for a scraping session. All attributes are guaranteed to match each other: UA matches browser+OS, TLS profile matches browser version, header order matches browser, GPU matches OS, screen resolution is common for OS, timezone matches proxy geo, etc.

func Generate 

func Generate(opts ...Option) *Profile

Generate creates a new consistent identity profile. All attributes are guaranteed to be internally consistent. Use functional options to constrain the generation.

func (*Profile) BuildCamoufoxConfig 

func (p *Profile) BuildCamoufoxConfig() map[string]any

BuildCamoufoxConfig builds the Camoufox fingerprint configuration as a flat map suitable for JSON-encoding into CAMOU_CONFIG_N env vars.

Camoufox expects all fingerprint overrides in a single JSON object split across CAMOU_CONFIG_1, CAMOU_CONFIG_2, ... environment variables (max ~2000 chars each due to Windows env-var limits). The JSON uses dot-path keys like "screen.width", "navigator.userAgent", etc.

IMPORTANT: Only set properties we want to CONTROL (identity consistency). BrowserForge auto-populates unset properties with realistic statistical distributions. Do NOT manually set: webGl:*, fonts, canvas:*, voices, shaderPrecisionFormats — BrowserForge handles these better than we can.

func (*Profile) BuildCamoufoxEnv 

func (p *Profile) BuildCamoufoxEnv() map[string]string

BuildCamoufoxEnv marshals the Camoufox config to JSON and chunks it into CAMOU_CONFIG_1, CAMOU_CONFIG_2, ... environment variables.

func (*Profile) MergeCamoufoxConfig 

func (p *Profile) MergeCamoufoxConfig(extra map[string]any) map[string]string

MergeCamoufoxConfig merges additional config (e.g. addons) into the profile's Camoufox config, re-marshals to JSON, and returns chunked CAMOU_CONFIG_N env vars. This is used by the browser launcher to combine fingerprint config with addon config in a single CAMOU_CONFIG blob.

type TLSProfileData 

type TLSProfileData struct {
	JA3   string        `json:"ja3"`
	JA4   string        `json:"ja4"`
	HTTP2 HTTP2Settings `json:"http2"`
}

TLSProfileData holds JA3/JA4 and HTTP/2 fingerprint data for a browser.

func GetTLSProfile 

func GetTLSProfile(key string) *TLSProfileData

GetTLSProfile returns the TLS fingerprint data for a browser version.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.