fingerprint-coherence 0.2.0__tar.gz

fingerprint_coherence-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package and dev deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          playwright install chromium
+
+      - name: Ruff
+        run: ruff check .
+
+      - name: Pytest
+        run: pytest

fingerprint_coherence-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package and dev deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          playwright install chromium
+
+      - name: Ruff
+        run: ruff check .
+
+      - name: Pytest
+        run: pytest
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Build
+        run: python -m build
+
+      - name: Twine check
+        run: twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

fingerprint_coherence-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.venv/
+venv/
+.env

fingerprint_coherence-0.2.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## v0.2.0 — 2026-06-11
+
+### Added
+
+- `fp-coherence mlx-profile --profile-id UUID` — fetch MLX fingerprint via `api.multilogin.com`, run ruleset, report pre-production violations (`[mlx]` extra, raw httpx)
+- Auto ruleset inference from profile `os_type` (windows-chrome / mac-safari / android-chrome)
+- MLX tests with `httpx.MockTransport` and fixture API profile shapes
+
+- Bundled platform rulesets: `windows-chrome`, `mac-safari`, `android-chrome`
+- `fp-coherence audit --ruleset RULESET --config my.yaml` (config file or positional path)
+- Stable violation codes (`E001` UA_OS_MISMATCH through `E011` UA_INVALID)
+- `fp-coherence export-schema -o schema.json` (profile, audit, ruleset JSON Schema)
+- 10+ unit tests per built-in check type
+- README: common violations when using playwright-stealth
+- GitHub Actions CI (Python 3.10–3.12)
+
+### Changed
+
+- Audit JSON and text output include `code` on each violation
+- `mac-safari` ruleset disables Chromium Client Hints checks (Safari-appropriate)
+
+## v0.1.0 — 2026-06-01
+
+- Initial release: YAML rule engine, CLI audit/score/from-playwright, coherence scoring

fingerprint_coherence-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fingerprint-coherence contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fingerprint_coherence-0.2.0/PKG-INFO

@@ -0,0 +1,305 @@
+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/)