Metadata-Version: 2.4
Name: fingerprint-coherence
Version: 0.2.0
Summary: Contradictory UA and screen signals get profiles flagged — lint fingerprints before create.
Project-URL: Homepage, https://github.com/fingerprint-coherence/fingerprint-coherence
Project-URL: Documentation, https://github.com/fingerprint-coherence/fingerprint-coherence#readme
Project-URL: Repository, https://github.com/fingerprint-coherence/fingerprint-coherence
Project-URL: Issues, https://github.com/fingerprint-coherence/fingerprint-coherence/issues
Author: fingerprint-coherence contributors
License-Expression: MIT
License-File: LICENSE
Keywords: canvas-fingerprint,client-hints,coherence-linter,fingerprint-coherence,playwright-fingerprint,ruleset-audit,screen-fingerprint,timezone-mismatch,ua-validation,user-agent-consistency,webgl-fingerprint,yaml-fingerprint
Classifier: Development Status :: 4 - Beta
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: 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

Python 3.10+ | MLX optional · [Compatibility](../packages/COMPATIBILITY.md)

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.

## pip 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`

## Production

Partner offers, eligibility, and disclosure: [docs/AFFILIATE.md](docs/AFFILIATE.md).

At production scale, lint YAML profiles with `fp-coherence` before `profile-factory mlx-create`, then validate live sessions with [playwright-cdp-probe](../playwright-cdp-probe/) on Launcher CDP ports.

## 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.

## Guides

Monorepo playbooks (copy-paste commands, sample output, diagrams):

| Guide | Flow |
|-------|------|
| [Detection fail → MLX farm](../packages/docs/workflows/WORKFLOW_DETECTED.md) | `cdp-probe` → `cdp-connect` → `farm-runner mlx-pool` |
| [Competitor migration](../packages/docs/workflows/WORKFLOW_MIGRATION.md) | `antidetect-import` → `profile-factory mlx-create` |
| [Proxy lane → profile pool](../packages/docs/workflows/WORKFLOW_FARM.md) | `proxy-lane` → `profile-factory` → `farm-runner mlx-pool` |

**FAQ:** [docs/FAQ.md](docs/FAQ.md) — fingerprint consistency, Client Hints, WebGL/UA alignment.

## Related tools

| Tool | Use with |
|------|----------|
| [playwright-cdp-probe](../playwright-cdp-probe/) — Score CDP/WebDriver exposure and fingerprint leaks | → [cdp-connect-kit](../cdp-connect-kit/) when probe fails |
| [cookie-jar-bridge](../cookie-jar-bridge/) — Convert, validate, and merge cookies across formats | → [session-bundle-kit](../session-bundle-kit/) for full session |
| [proxy-lane-checker](../proxy-lane-checker/) — Batch-check proxies for connectivity, geo, and DNSBL | → [profile-yaml-factory](../profile-yaml-factory/) |
| [fingerprint-coherence](../fingerprint-coherence/) — Lint fingerprints for cross-signal contradictions | → [profile-yaml-factory](../profile-yaml-factory/) before create |
| [human-input-kit](../human-input-kit/) — Human-like mouse, scroll, and warmup replay | → [automation-farm-runner](../automation-farm-runner/) |
| [cdp-connect-kit](../cdp-connect-kit/) — Playwright CDP connect; MLX start/stop helpers | → all packages needing CDP |
| [session-bundle-kit](../session-bundle-kit/) — Export/import cookies and storage as portable bundles | → [cookie-jar-bridge](../cookie-jar-bridge/) |
| [profile-yaml-factory](../profile-yaml-factory/) — YAML blueprints → MLX `profile/create` payloads | → [antidetect-importer](../antidetect-importer/) after migration |
| [antidetect-importer](../antidetect-importer/) — Parse competitor exports and push to MLX | → [profile-yaml-factory](../profile-yaml-factory/) |
| [automation-farm-runner](../automation-farm-runner/) — YAML job queue and MLX profile-pool runner | → [cdp-connect-kit](../cdp-connect-kit/) `[mlx]` |

## 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/)
