Metadata-Version: 2.4
Name: fingerprint-coherence
Version: 0.2.2
Summary: Browser fingerprint consistency checker — UA, Client Hints, WebGL, timezone lint. CLI: fp-coherence.
Project-URL: Homepage, https://pypi.org/project/fingerprint-coherence/
Project-URL: Documentation, https://pypi.org/project/fingerprint-coherence/
Project-URL: Repository, https://github.com/fingerprint-coherence/fingerprint-coherence
Project-URL: Issues, https://github.com/fingerprint-coherence/fingerprint-coherence/issues
Project-URL: Changelog, https://github.com/fingerprint-coherence/fingerprint-coherence/blob/main/CHANGELOG.md
Author: fingerprint-coherence contributors
License-Expression: MIT
License-File: LICENSE
Keywords: antidetect-fingerprint,bot-detection,browser-fingerprint,client-hints,coherence-linter,fingerprint-coherence,fingerprint-consistency,playwright-fingerprint,playwright-stealth,ruleset-audit,screen-fingerprint,sec-ch-ua,timezone-mismatch,ua-validation,user-agent-consistency,webgl-fingerprint,yaml-fingerprint
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: playwright>=1.40
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: mlx
Requires-Dist: httpx>=0.27; extra == 'mlx'
Description-Content-Type: text/markdown

# fingerprint-coherence

**Browser fingerprint consistency checker** — lint UA, Client Hints, WebGL, and timezone contradictions before deploy.

[![PyPI version](https://img.shields.io/pypi/v/fingerprint-coherence.svg)](https://pypi.org/project/fingerprint-coherence/)
[![Python versions](https://img.shields.io/pypi/pyversions/fingerprint-coherence.svg)](https://pypi.org/project/fingerprint-coherence/)
[![License: MIT](https://img.shields.io/pypi/l/fingerprint-coherence.svg)](https://pypi.org/project/fingerprint-coherence/)

```bash
pip install fingerprint-coherence
fp-coherence audit profile.yaml --strict
```

CLI: **`fp-coherence`** · Python **3.10+** · optional **`[mlx]`** for Launcher helpers

Audit browser fingerprint configurations for **internal coherence** — do UA, `navigator.platform`, screen size, timezone, languages, WebGL, and Client Hints tell the same story?

Returns a **0–100 coherence score** and human-readable violations. No antidetect browser required for `audit` and `score`; optional live collection via Playwright.

## Problem

JS-level fingerprint spoofing often creates contradictions:

- iPhone UA with `Win32` platform and 1920×1080 screen
- `America/New_York` timezone with `ja-JP` as the primary language
- `sec-ch-ua-platform: "Windows"` on a macOS user agent
- Apple WebGL renderer on a Windows UA string

Bot-detection stacks hunt these mismatches. `fp-coherence` gives developers a fast lint for stealth configs **before** they hit production traffic.

## Install

```bash
pip install fingerprint-coherence
playwright install chromium   # only for from-playwright
```

Development:

```bash
pip install fingerprint-coherence[mlx]

# Audit MLX Cloud profile before production
export MLX_TOKEN=your_bearer_token
fp-coherence mlx-profile --profile-id PROFILE_UUID --strict

pip install fingerprint-coherence[dev]
```

## Quick start

```bash
# Audit a YAML config with a platform ruleset
fp-coherence audit --ruleset windows-chrome --config my-profile.yaml

# Or pass the config as a positional argument
fp-coherence audit my-profile.yaml --ruleset windows-chrome --json --strict

# Lint explicit fields (no config file)
fp-coherence audit \
  --ua "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..." \
  --screen 1920x1080 \
  --timezone America/New_York \
  --platform Win32 \
  --lang en-US

# Export JSON Schema for CI validation
fp-coherence export-schema -o schema.json

# Collect from a real Playwright launch
fp-coherence from-playwright --url about:blank --ruleset windows-chrome
```

## CLI

| Command | Description |
|---------|-------------|
| `fp-coherence audit --config my.yaml --ruleset windows-chrome` | Audit YAML config with platform ruleset |
| `fp-coherence audit --ua ... --screen WxH` | Audit CLI-provided fields |
| `fp-coherence from-playwright --url URL` | Collect live signals + audit |
| `fp-coherence score config.yaml --ruleset mac-safari` | Score config against ruleset |
| `fp-coherence export-schema -o schema.json` | Export JSON Schema bundle |
| `fp-coherence mlx-profile --profile-id UUID` | Fetch MLX fingerprint via API + audit (`[mlx]`) |

### Options

- `--ruleset NAME\|PATH` — built-in (`windows-chrome`, `mac-safari`, `android-chrome`) or custom YAML path
- `--json` — machine-readable output (includes violation `code` fields)
- `--strict` — exit `1` when violations exist

### Built-in rulesets

| Ruleset | Use when |
|---------|----------|
| `windows-chrome` | Desktop Windows + Chromium / Chrome |
| `mac-safari` | macOS Safari (Client Hints checks disabled) |
| `android-chrome` | Mobile Android + Chrome |

Shipped under `fingerprint_coherence/rulesets/`. Custom rulesets use the same YAML shape as `default.yaml`.

### Violation codes

| Code | Name | Check |
|------|------|-------|
| `E001` | UA_OS_MISMATCH | `platform_matches_ua` |
| `E002` | SCREEN_IMPOSSIBLE | `mobile_screen_alignment` |
| `E003` | TIMEZONE_LANG_MISMATCH | `timezone_language` |
| `E004` | CH_PLATFORM_MISMATCH | `client_hints_platform` |
| `E005` | CH_MOBILE_MISMATCH | `client_hints_mobile` |
| `E006` | CHROME_VERSION_MISMATCH | `chrome_version_hints` |
| `E007` | WEBGL_OS_MISMATCH | `webgl_os_alignment` |
| `E008` | SCREEN_AVAIL_OVERFLOW | `screen_avail_bounds` |
| `E009` | TOUCH_POINTS_MISMATCH | `touch_points_mobile` |
| `E010` | DPR_IMPLAUSIBLE | `dpr_screen_sanity` |
| `E011` | UA_INVALID | `ua_required` (empty or HeadlessChrome) |

Filter in CI: `jq '.violations[] | select(.code == "E001")' audit.json`

### Exit codes

| Code | Meaning |
|------|---------|
| `0` | No violations (or non-strict mode) |
| `1` | Violations found with `--strict` |
| `2` | Runtime error |

## YAML config format

```yaml
user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..."
platform: "Win32"
screen: 1920x1080
timezone: America/New_York
languages:
  - en-US
webgl_vendor: "Google Inc. (NVIDIA)"
webgl_renderer: "ANGLE (NVIDIA, ...)"
client_hints:
  sec_ch_ua: '"Chromium";v="120", "Google Chrome";v="120"'
  sec_ch_ua_platform: '"Windows"'
  sec_ch_ua_mobile: "?0"
```

## Rule engine

Bundled ruleset (`fingerprint_coherence/rules/default.yaml`) checks:

| Rule | What it validates |
|------|-------------------|
| `platform_matches_ua` | `navigator.platform` vs UA OS family |
| `mobile_screen_alignment` | Mobile UA vs desktop screen widths |
| `timezone_language` | IANA timezone vs primary language |
| `client_hints_platform` | `sec-ch-ua-platform` vs UA |
| `client_hints_mobile` | `sec-ch-ua-mobile` vs form factor |
| `chrome_version_hints` | Chromium version in UA vs Client Hints |
| `webgl_os_alignment` | WebGL vendor/renderer vs claimed OS |
| `screen_avail_bounds` | `availWidth/Height` ≤ screen size |
| `touch_points_mobile` | `maxTouchPoints` vs mobile/desktop UA |
| `dpr_screen_sanity` | `devicePixelRatio` plausibility |

Custom rulesets reference built-in check names:

```yaml
rules:
  - id: my_rule
    severity: high
    check: platform_matches_ua
    enabled: true
```

### Scoring

Start at **100**, deduct by severity: high **−18**, medium **−10**, low **−5**.

| Grade | Score |
|-------|-------|
| `coherent` | ≥ 85 |
| `minor-drift` | 65–84 |
| `inconsistent` | 40–64 |
| `contradictory` | < 40 |

## API

```python
from fingerprint_coherence import CoherenceEngine, FingerprintProfile

profile = FingerprintProfile(
    user_agent="Mozilla/5.0 (iPhone; ...) ...",
    platform="Win32",
    screen_width=1920,
    screen_height=1080,
    timezone="America/New_York",
    languages=["en-US"],
)
result = CoherenceEngine().audit(profile)
print(result.score, result.grade)
for v in result.violations:
    print(v.code, v.rule_id, v.message)
```

## Common violations when using playwright-stealth

Libraries like `playwright-stealth` patch individual APIs at runtime. That often fixes `navigator.webdriver` but leaves **cross-signal drift** that `fp-coherence` catches:

| Symptom | Typical cause | Code |
|---------|---------------|------|
| `HeadlessChrome` still in UA | Stealth plugin not applied before first navigation | `E011` |
| iPhone UA + `Win32` platform | UA overridden, `navigator.platform` left default | `E001` |
| Mobile UA + 1920×1080 viewport | Desktop viewport with mobile UA string | `E002` |
| Windows UA + `sec-ch-ua-platform: "Linux"` | Client Hints not patched to match UA | `E004` |
| Desktop UA + `sec-ch-ua-mobile: ?1` | Mobile hint left at Chromium default | `E005` |
| Chrome 120 UA + `v="119"` in sec-ch-ua | Version bump in UA only, hints stale | `E006` |
| Windows UA + Apple WebGL renderer | WebGL override from wrong OS template | `E007` |
| `availWidth` > `screen.width` | Taskbar/chrome UI math wrong in screen spoof | `E008` |
| Android UA + `maxTouchPoints: 0` | Touch API not patched for mobile profile | `E009` |
| Pixel 7 viewport + `devicePixelRatio: 1` | DPR not aligned with mobile screen | `E010` |

**Workflow:** export your intended YAML profile, run `fp-coherence from-playwright --ruleset android-chrome`, compare violations against the target config, then fix the highest-severity codes first (`E001`, `E002`, `E004`, `E007`).

## JS spoofing vs profile-level fingerprints

**This tool measures logical consistency**, not whether spoofing evades detection.

Patching individual JS APIs (`navigator.webdriver`, canvas noise, WebGL overrides) frequently leaves **cross-signal contradictions** — one property updated, another forgotten. That is exactly what `fp-coherence` surfaces.

**Antidetect browsers** (e.g. Multilogin X, GoLogin) manage fingerprints at the **profile level** — OS, screen, timezone, WebGL, and Client Hints are provisioned together, which reduces internal drift compared to ad-hoc Playwright patches.

Use `fp-coherence` to:

1. Lint YAML configs before loading them into automation
2. Compare a patched Playwright launch (`from-playwright`) against your intended profile
3. Regression-test rule changes in CI with `--strict`

## When coherence score stays low (playbook)

High **exposure** from `cdp-probe` with high **coherence** here means different problems — fix both.

| Score band | Grade | Likely issue | Next step |
|------------|-------|--------------|-----------|
| &lt; 40 | contradictory | Multiple E001/E004/E007 | Rebuild profile template; avoid patchwork stealth |
| 40–64 | inconsistent | Client Hints or WebGL drift | Fix `E004`–`E007` before traffic |
| 65–84 | minor-drift | Timezone/lang or DPR | Tune `E003`, `E010`; re-audit |
| ≥ 85 | coherent | Internal signals align | Run `cdp-probe` for CDP leaks |

**Pre-production pipeline:**

```bash
proxy-lane check proxies.txt -o lanes.json
fp-coherence audit profile.yaml --ruleset windows-chrome --strict --json -o audit.json
profile-factory render profile.yaml --vars ... -o payload.json
fp-coherence mlx-profile --profile-id UUID --strict    # optional MLX API audit
cdp-probe mlx --profile-id UUID --url https://example.com
```

Coherence measures **logical consistency** — not whether a site accepts you.

## Limitations

- **Heuristic rules** — timezone/language mapping is simplified, not exhaustive.
- **Client Hints** — only available in Chromium; `from-playwright` may return null hints in some builds.
- **Not a bypass tool** — high coherence ≠ undetectable; low coherence ≠ instant block.
- **No canvas/font audit** — focuses on UA, screen, timezone, WebGL, and Client Hints alignment.

## Production

Lint YAML with `fp-coherence` before [profile-yaml-factory](https://pypi.org/project/profile-yaml-factory/) `mlx-create`, then validate live Launcher sessions with [playwright-cdp-probe](https://pypi.org/project/playwright-cdp-probe/).

**Partner note (affiliate):** Profile-level antidetect (e.g. **Multilogin X**) provisions OS, screen, WebGL, and Client Hints together — often fewer `E001`–`E007` violations than ad-hoc Playwright patches. If you outgrow JS spoofing, eligible new browser purchases may accept code **`SAAS50`** at [multilogin.com](https://multilogin.com/?ref=SAAS50) — verify terms before checkout. `audit`/`score` need no MLX account. Full disclosure: [docs/AFFILIATE.md](docs/AFFILIATE.md). Coupon details only via `fp-coherence --show-deal` (never printed by default).

**FAQ:** [docs/FAQ.md](docs/FAQ.md) — browser fingerprint consistency, Client Hints mismatch, playwright-stealth vs profile.





## Related tools (on PyPI)

| Package | CLI | Role |
|---------|-----|------|
| [playwright-cdp-probe](https://pypi.org/project/playwright-cdp-probe/) | `cdp-probe` | CDP / WebDriver exposure score |
| [cookie-jar-bridge](https://pypi.org/project/cookie-jar-bridge/) | `cookie-bridge` | Netscape ↔ Playwright cookies |
| [proxy-lane-checker](https://pypi.org/project/proxy-lane-checker/) | `proxy-lane` | Proxy TCP / HTTP / geo / DNSBL |
| [fingerprint-coherence](https://pypi.org/project/fingerprint-coherence/) | `fp-coherence` | UA / screen / timezone lint |

**Toolkit pipeline:** `proxy-lane check` → `fp-coherence audit` → automate → `cdp-probe run` → `cookie-bridge validate`

## License

MIT

---

**Production antidetect:** [Multilogin X](https://multilogin.com/?ref=SAAS50) · Code `SAAS50` (-50% browser) · `MIN50` (-50% cloud phone)  
More scripts: [@Multilogin_Scripts_Bot](https://t.me/Multilogin_Scripts_Bot) · [Coupons](https://anti-detect.github.io/)
