captchafox

Documentation

Index

• Constants
• func BuildAttestation(site string, profile *AttestationProfile) map[string]interface{}
• func EncodePayload(payload map[string]interface{}) ([]byte, error)
• func SolvePow(seed string, difficulty int) int
• type AttestationProfile
  • func RandomAttestationProfile() *AttestationProfile
• type CaptchaFoxClient
  • func NewCaptchaFoxClient() *CaptchaFoxClient
  • func (c *CaptchaFoxClient) Challenge(config *CaptchaFoxConfig, challengeType string, cs map[string]interface{}, ...) (map[string]interface{}, error)
  • func (c *CaptchaFoxClient) FetchConfig(siteKey, site string) (*CaptchaFoxConfig, error)
  • func (c *CaptchaFoxClient) GetTestToken(site string) (string, error)
  • func (c *CaptchaFoxClient) Verify(payload map[string]interface{}, site string) (map[string]interface{}, error)
  • func (c *CaptchaFoxClient) VerifyToken(secret, response, sitekey, remoteIP string) (map[string]interface{}, error)
• type CaptchaFoxConfig
  • func (c CaptchaFoxConfig) H() string
• type CaptchaFoxSolver
  • func NewCaptchaFoxSolver(client *CaptchaFoxClient, siteKey, site, challengeType, lang string, ...) *CaptchaFoxSolver
  • func (s *CaptchaFoxSolver) Probe() (map[string]interface{}, error)
  • func (s *CaptchaFoxSolver) Solve(maxAttempts int) (string, error)

Constants

const (
	// ApiBase is the CaptchaFox challenge/config API origin.
	ApiBase = "https://mam-api.captchafox.com"
	// Pulse is the static X-Pulse header value required by the API.
	Pulse = "2bd77e6f8a17bc0e"
	// TestSiteKey is CaptchaFox's public test site key.
	TestSiteKey = "sk_11111111000000001111111100000000"
	// TestSecret is CaptchaFox's public test organization secret.
	TestSecret = "ok_11111111000000001111111100000000"
	// SiteVerifyURL is the public siteverify endpoint.
	SiteVerifyURL = "https://api.captchafox.com/siteverify"
	// DefaultSite is the default origin/referer site used for solves.
	DefaultSite = "https://signup.mail.com/"
	// DefaultUA is the Chrome 125 Linux User-Agent matched by CF0115 in the
	// captured attestation template.
	DefaultUA = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36"
)

Functions

func BuildAttestation

func BuildAttestation(site string, profile *AttestationProfile) map[string]interface{}

BuildAttestation deep-copies the captured Chrome attestation template and freshens it for a solve: CF0106 (timestamp) and CF0148 (site) are always refreshed. When a profile is supplied the per-user signal fields (CF0101, CF0105, CF0108, CF0111, CF0114, CF0120, CF0121) are overridden so each call yields a distinct fingerprint while remaining Chrome-consistent.

func EncodePayload

func EncodePayload(payload map[string]interface{}) ([]byte, error)

EncodePayload encodes the text/plain POST body used by CaptchaFox challenge/verify calls. The encoding pipeline mirrors the Python reference (encode_captchafox_payload):

1. compact JSON (no HTML escaping, like ensure_ascii=False)
2. gzip
3. prefix the magic bytes [0x01, 0x04]
4. XOR each compressed byte with (index+4)&0xFF

The second prefix byte (0x04) doubles as the initial XOR key, so byte 0 of the gzip stream is XOR'd with 4, byte 1 with 5, and so on, wrapping at 256.

func SolvePow

func SolvePow(seed string, difficulty int) int

SolvePow finds the smallest nonce whose sha256(seed+nonce) hex digest starts with `difficulty` leading '0' characters. This is the CaptchaFox proof-of-work: the worker message is [tag, seed, difficultyBinaryString] where the difficulty is the count of leading hex zeros (parsed from a binary string such as "101" -> 5). The seed and nonce are concatenated as decimal-integer strings, exactly mirroring the Python reference: hashlib.sha256(f"{seed}{nonce}".encode("utf-8")).hexdigest().

Types

type AttestationProfile

type AttestationProfile struct {
	DarkMode            bool
	HardwareConcurrency int
	TimezoneOffset      int
	Languages           []string
	WebGLVendor         string
	WebGLRenderer       string
	ScreenWidth         int
	ScreenHeight        int
	PixelRatio          int
}

AttestationProfile is a self-consistent per-user Chrome attestation profile. Only genuine per-user signals are varied (screen, GPU, timezone, core count, languages, dark mode). The UA, platform and property inventories stay constant from the captured Chrome template so the fingerprint remains Chrome-plausible and consistent with the HTTP User-Agent header.

func RandomAttestationProfile

func RandomAttestationProfile() *AttestationProfile

RandomAttestationProfile mints a fresh randomized per-user fingerprint by sampling from the variation pools. The global math/rand source is auto-seeded (Go 1.20+) and concurrency-safe.

type CaptchaFoxClient

type CaptchaFoxClient struct {
	HTTP      *http.Client
	UserAgent string
	Timeout   time.Duration
}

CaptchaFoxClient is a minimal direct client for the CaptchaFox protocol.

func NewCaptchaFoxClient

func NewCaptchaFoxClient() *CaptchaFoxClient

NewCaptchaFoxClient returns a client with sensible defaults.

func (*CaptchaFoxClient) Challenge

func (c *CaptchaFoxClient) Challenge(config *CaptchaFoxConfig, challengeType string, cs map[string]interface{}, k int, lang string) (map[string]interface{}, error)

Challenge requests a challenge for the configured handshake. The body is encoded with EncodePayload and sent as text/plain.

func (*CaptchaFoxClient) FetchConfig

func (c *CaptchaFoxClient) FetchConfig(siteKey, site string) (*CaptchaFoxConfig, error)

FetchConfig fetches the challenge configuration for a site key.

func (*CaptchaFoxClient) GetTestToken

func (c *CaptchaFoxClient) GetTestToken(site string) (string, error)

GetTestToken mints a token from CaptchaFox's public test site key.

func (*CaptchaFoxClient) Verify

func (c *CaptchaFoxClient) Verify(payload map[string]interface{}, site string) (map[string]interface{}, error)

Verify submits the solved challenge payload and returns the server result.

func (*CaptchaFoxClient) VerifyToken

func (c *CaptchaFoxClient) VerifyToken(secret, response, sitekey, remoteIP string) (map[string]interface{}, error)

VerifyToken verifies a CaptchaFox response token against the public siteverify endpoint.

type CaptchaFoxConfig

type CaptchaFoxConfig struct {
	SiteKey string
	Site    string
	Raw     map[string]interface{}
}

CaptchaFoxConfig wraps the JSON returned by the config endpoint.

func (CaptchaFoxConfig) H

func (c CaptchaFoxConfig) H() string

H returns the config handshake token ("h") used to anchor a challenge.

type CaptchaFoxSolver

type CaptchaFoxSolver struct {
	// contains filtered or unexported fields
}

CaptchaFoxSolver runs the full CaptchaFox flow without a browser: it replays a real-Chrome attestation object as `cs` and solves the slide challenge by detecting the puzzle gap in the background image.

func NewCaptchaFoxSolver

func NewCaptchaFoxSolver(client *CaptchaFoxClient, siteKey, site, challengeType, lang string, profile *AttestationProfile) *CaptchaFoxSolver

NewCaptchaFoxSolver constructs a solver. A nil client is replaced with a default CaptchaFoxClient.

func (*CaptchaFoxSolver) Probe

func (s *CaptchaFoxSolver) Probe() (map[string]interface{}, error)

Probe fetches the config and issues a challenge with a synthesized attestation. A non-error response means the attestation (cs) was accepted by the live server.

func (*CaptchaFoxSolver) Solve

func (s *CaptchaFoxSolver) Solve(maxAttempts int) (string, error)

Solve runs the full flow with up to maxAttempts retries and returns a verified response token.