phasmid-profile-gen 0.1.1__py3-none-any.whl

phasmid_profile_gen/__init__.py

@@ -0,0 +1,165 @@
+"""Generate Phasmid browser profiles.
+
+    from phasmid_profile_gen import generate_profile
+
+    profile = generate_profile("windows", exit_ip=proxy_exit_ip)   # needs the location extra
+    profile = generate_profile("linux", seed="0a1b...", timezone="Europe/Berlin",
+                               languages=["de-DE", "de", "en-US", "en"])
+
+A profile regenerates byte for byte from its seed and inputs (``dumps``).
+"""
+
+from __future__ import annotations
+
+import os
+import secrets
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+
+# Submodules are imported by name only: binding a function under a submodule's name here
+# (generate, captures) would hide that submodule as an attribute of the package.
+from . import generate as _generate
+from . import geoip
+from . import location as _location
+from .captures import Capture, catalog, gpu_key, validate
+from .generate import (
+    FAMILIES,
+    GenerationError,
+    MissingCaptures,
+    ProfileGenerator,
+    RandomCapture,
+    Request,
+    dumps,
+    from_capture,
+)
+from .location import Location, LocationError
+
+try:
+    __version__ = version("phasmid-profile-gen")
+except PackageNotFoundError:  # running from a source tree that was never installed
+    __version__ = "0.0.0"
+
+__all__ = [
+    "FAMILIES",
+    "Capture",
+    "GenerationError",
+    "Location",
+    "LocationError",
+    "MissingCaptures",
+    "ProfileGenerator",
+    "RandomCapture",
+    "Request",
+    "__version__",
+    "catalog",
+    "dumps",
+    "from_capture",
+    "generate_profile",
+    "list_captures",
+    "list_gpus",
+    "locate",
+    "new_seed",
+    "validate",
+]
+
+GeoipDatabase = str | os.PathLike[str] | None
+
+
+def new_seed() -> str:
+    """A fresh profile seed: 32 lowercase hex characters."""
+    return secrets.token_hex(16)
+
+
+def locate(exit_ip: str, seed: str, *, geoip_db: GeoipDatabase = None) -> Location:
+    """Where a profile with ``seed`` behind ``exit_ip`` is placed: zone, position, languages.
+
+    ``geoip_db`` is a DB-IP City Lite .mmdb; by default ``$PHASMID_GEOIP_MMDB``, else the pinned
+    build, downloaded into the cache on first use (about 60 MB)."""
+    return _location.locate(exit_ip, seed, geoip.reader(geoip_db))
+
+
+def generate_profile(
+    os: str,
+    seed: str | None = None,
+    *,
+    exit_ip: str | None = None,
+    timezone: str | None = None,
+    languages: list[str] | None = None,
+    gpu: str | None = None,
+    geoip_db: GeoipDatabase = None,
+    generator: ProfileGenerator | None = None,
+) -> dict[str, Any]:
+    """A schema-valid Phasmid profile.
+
+    - ``os``: ``"linux"`` or ``"windows"``.
+    - ``seed``: 32 lowercase hex characters; a new one when omitted (read it back from
+      ``profile["seed"]``).
+    - ``exit_ip`` or ``timezone``, exactly one. An exit IP places the profile where the proxy
+      comes out: zone, geolocation, WebRTC public address and, unless ``languages`` is given,
+      Chrome's default languages for that country. Generate Windows profiles with one: Windows
+      Chrome answers geolocation from the system provider, so a Windows profile with no
+      position is a stronger tell than a Linux one.
+    - ``languages``: ``navigator.languages``; default ``["en-US", "en"]`` with a timezone.
+    - ``gpu``: ``"vendor_id:device_id"`` of a GPU a bundled capture has (see ``list_gpus()``).
+    - ``generator``: how the capture behind the profile is chosen (a ``ProfileGenerator``);
+      default ``RandomCapture()``, one of the OS's captures drawn uniformly from the seed.
+
+    Raises ``GenerationError`` (``MissingCaptures`` when no capture covers the OS),
+    ``LocationError`` or ``geoip.GeoipError``.
+    """
+    if (exit_ip is None) == (timezone is None):
+        raise GenerationError("give exactly one of exit_ip and timezone")
+    seed = seed or new_seed()
+    found: Location | None = None
+    data_note = ""
+    if exit_ip is not None:
+        db = geoip.reader(geoip_db)
+        found = _location.locate(exit_ip, seed, db)
+        data_note = f"{db.provenance}, {_location.provenance()}"
+        timezone = found.timezone
+    assert timezone is not None
+    langs = list(languages) if languages else (found.languages if found else ["en-US", "en"])
+    profile = _generate.generate(
+        os, seed, langs, timezone, gpu, found, data_note, generator=generator
+    )
+    errors = validate(profile)
+    if errors:
+        raise GenerationError("generated profile does not validate: " + "; ".join(errors))
+    return profile
+
+
+def list_gpus() -> list[dict[str, Any]]:
+    """Every GPU of the bundled captures, per OS, most captures first:
+    ``[{"os", "gpu", "renderer", "captures"}]``. ``gpu`` is what ``generate_profile(gpu=)``
+    takes."""
+    seen: dict[tuple[str, str], dict[str, Any]] = {}
+    for capture in catalog():
+        gpu = capture.profile["gpu"]
+        key = gpu_key(gpu)
+        entry = seen.setdefault(
+            (capture.family, key),
+            {
+                "os": capture.family,
+                "gpu": key,
+                "renderer": gpu["webgl"]["unmasked_renderer"],
+                "captures": 0,
+            },
+        )
+        entry["captures"] += 1
+    return sorted(seen.values(), key=lambda e: (e["os"], -e["captures"], e["gpu"]))
+
+
+def list_captures() -> list[dict[str, Any]]:
+    """The bundled captures: ``[{"name", "os", "os_version", "gpu", "renderer", "date",
+    "dump_sha256"}]``."""
+    return [
+        {
+            "name": c.name,
+            "os": c.family,
+            "os_version": c.profile["os"]["version"],
+            "gpu": gpu_key(c.profile["gpu"]),
+            "renderer": c.profile["gpu"]["webgl"]["unmasked_renderer"],
+            "date": c.date,
+            "dump_sha256": c.dump_sha256,
+        }
+        for c in catalog()
+    ]

phasmid_profile_gen/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

phasmid_profile_gen/_data.py

@@ -0,0 +1,25 @@
+"""The bundled data: xz-compressed JSON under ``data/``, built by scripts/build_data.py."""
+
+from __future__ import annotations
+
+import json
+import lzma
+from functools import cache
+from importlib.resources import files
+from typing import Any
+
+
+def path(name: str):
+    return files(__package__).joinpath("data", name)
+
+
+@cache
+def load(name: str) -> Any:
+    """``data/<name>.json.xz``, decompressed and parsed once per process. Callers must not
+    mutate what this returns."""
+    return json.loads(lzma.decompress(path(f"{name}.json.xz").read_bytes()))
+
+
+@cache
+def manifest() -> dict[str, Any]:
+    return json.loads(path("manifest.json").read_text())

phasmid_profile_gen/_rng.py

@@ -0,0 +1,17 @@
+"""Per-decision randomness: every draw a seed decides has its own RNG.
+
+``decision_rng(seed, decision)`` is ``random.Random(sha256(seed + ":" + decision))``, so a
+seed gives the same profile byte for byte and the global ``random`` state is never read or
+advanced.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import random
+
+
+def decision_rng(seed: str, decision: str) -> random.Random:
+    return random.Random(
+        int.from_bytes(hashlib.sha256(f"{seed}:{decision}".encode()).digest(), "big")
+    )

phasmid_profile_gen/captures.py

@@ -0,0 +1,78 @@
+"""The capture catalog: real devices, already mapped onto the profile schema.
+
+Each entry was built by scripts/build_data.py from a harness dump of a real
+device. The mapping is Phasmid's ``tests/consistency/capture.py``, the code
+``consistency capture`` runs, so there is one mapping from a dump to profile
+fields. Only what generation reads is bundled, under a neutral name (OS family
+and PCI ids); ``data/manifest.json`` names every capture's dump by sha256.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import cache
+from typing import Any
+
+import jsonschema
+
+from . import _data
+
+
+@dataclass(frozen=True)
+class Capture:
+    name: str
+    family: str
+    gpu: str
+    date: str
+    dump_sha256: str
+    profile: dict[str, Any]
+    battery: dict[str, Any] | None
+    # media_devices.labels shown after permission. A dump has no capture permission, so it
+    # shows no labels; a Phasmid record lists what the host shows after it. A capture
+    # without any makes profiles that claim no media device.
+    media_device_labels: dict[str, list[str]]
+
+
+def gpu_key(gpu: dict[str, Any]) -> str:
+    return f"{gpu['vendor_id']}:{gpu['device_id']}"
+
+
+@cache
+def catalog() -> tuple[Capture, ...]:
+    return tuple(
+        Capture(
+            name=c["name"],
+            family=c["family"],
+            gpu=c["gpu"],
+            date=c["date"],
+            dump_sha256=c["dump_sha256"],
+            profile=c["profile"],
+            battery=c["battery"],
+            media_device_labels=c["media_device_labels"],
+        )
+        for c in _data.load("captures")["captures"]
+    )
+
+
+def for_os(family: str) -> list[Capture]:
+    return [c for c in catalog() if c.family == family]
+
+
+@cache
+def schema() -> dict[str, Any]:
+    """Phasmid's profiles/schema.json at the commit the data was built from."""
+    return _data.load("schema")
+
+
+@cache
+def _validator() -> jsonschema.Draft202012Validator:
+    return jsonschema.Draft202012Validator(schema(), format_checker=jsonschema.FormatChecker())
+
+
+def validate(profile: dict[str, Any]) -> list[str]:
+    """Human-readable schema violations, empty when valid (what ``consistency validate`` runs)."""
+    errors = []
+    for err in sorted(_validator().iter_errors(profile), key=lambda e: list(e.absolute_path)):
+        where = "/".join(str(p) for p in err.absolute_path) or "<root>"
+        errors.append(f"{where}: {err.message}")
+    return errors

phasmid_profile_gen/cli.py

@@ -0,0 +1,168 @@
+"""phasmid-profile-gen: generate, place and list Phasmid profiles.
+
+    phasmid-profile-gen generate --os windows --exit-ip <proxy exit IP> -o profile.json
+    phasmid-profile-gen generate --os linux --seed <32 hex> --timezone Europe/Berlin \\
+        --languages de-DE,de,en-US,en
+    phasmid-profile-gen locate <proxy exit IP> --seed <32 hex>
+    phasmid-profile-gen gpus
+    phasmid-profile-gen captures
+    phasmid-profile-gen geoip [--archive dbip-city-lite-YYYY-MM.mmdb.gz]
+    phasmid-profile-gen validate profile.json
+
+Placing a profile at an exit IP needs the location extra
+(pip install 'phasmid-profile-gen[location]') and the DB-IP City Lite database,
+downloaded on first use; --geoip-db or $PHASMID_GEOIP_MMDB names another copy.
+"""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import json
+import sys
+from pathlib import Path
+
+from . import __version__, generate_profile, list_captures, list_gpus, locate, new_seed, validate
+from .generate import FAMILIES, GenerationError, MissingCaptures, dumps
+from .geoip import GeoipError, fetch
+from .locales import LocaleDataError
+from .location import LocationError
+
+_ERRORS = (GenerationError, LocationError, GeoipError, LocaleDataError, ValueError)
+
+
+def _summary(profile: dict) -> str:
+    d, h = profile["display"], profile["hardware"]
+    w = d["window"]
+    return (
+        f"{profile['os']['family']} {profile['os'].get('version', '?')}, "
+        f"{h['concurrency']} threads, "
+        f"{h['device_memory']} GB, {d['width']}x{d['height']}@{d['device_pixel_ratio']} "
+        f"window {w['outer_width']}x{w['outer_height']}, "
+        f"gpu {profile.get('gpu', {}).get('device_id', '-')}, seed {profile['seed']}"
+    )
+
+
+def _write(text: str, out: str | None) -> None:
+    if out is None or out == "-":
+        sys.stdout.write(text)
+        return
+    path = Path(out)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text)
+
+
+def _languages(raw: str | None) -> list[str] | None:
+    if not raw:
+        return None
+    return [lang.strip() for lang in raw.split(",") if lang.strip()]
+
+
+def _cmd_generate(args: argparse.Namespace) -> int:
+    try:
+        profile = generate_profile(
+            args.os,
+            args.seed,
+            exit_ip=args.exit_ip,
+            timezone=args.timezone,
+            languages=_languages(args.languages),
+            gpu=args.gpu,
+            geoip_db=args.geoip_db,
+        )
+    except MissingCaptures as e:
+        print(e, file=sys.stderr)
+        return 1
+    _write(dumps(profile), args.out)
+    if args.out not in (None, "-"):
+        print(f"wrote {args.out}: {_summary(profile)}", file=sys.stderr)
+    return 0
+
+
+def _cmd_locate(args: argparse.Namespace) -> int:
+    found = locate(args.ip, args.seed or new_seed(), geoip_db=args.geoip_db)
+    print(json.dumps(dataclasses.asdict(found), indent=1, ensure_ascii=False))
+    return 0
+
+
+def _cmd_gpus(_: argparse.Namespace) -> int:
+    print(json.dumps(list_gpus(), indent=1))
+    return 0
+
+
+def _cmd_captures(_: argparse.Namespace) -> int:
+    print(json.dumps(list_captures(), indent=1))
+    return 0
+
+
+def _cmd_geoip(args: argparse.Namespace) -> int:
+    print(fetch(args.archive))
+    return 0
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    errors = validate(json.loads(Path(args.profile).read_text()))
+    for err in errors:
+        print(err)
+    return 1 if errors else 0
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="phasmid-profile-gen",
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    g = sub.add_parser("generate", help="write one profile")
+    g.add_argument("--os", required=True, choices=FAMILIES)
+    g.add_argument("--seed", help="32 lowercase hex chars; a new one when omitted")
+    where = g.add_mutually_exclusive_group(required=True)
+    where.add_argument("--timezone", help="IANA zone, e.g. America/New_York")
+    where.add_argument(
+        "--exit-ip",
+        help="the proxy's exit IP: derives the zone, geolocation, WebRTC public address and "
+        "languages",
+    )
+    g.add_argument(
+        "--languages",
+        help="navigator.languages, comma separated (default en-US,en, or the exit IP country's)",
+    )
+    g.add_argument(
+        "--gpu", help="vendor_id:device_id of a GPU listed by `gpus`, e.g. 0x10de:0x2504"
+    )
+    g.add_argument("--geoip-db", help="a DB-IP City Lite .mmdb instead of the pinned build")
+    g.add_argument("-o", "--out", help="output file (default: stdout)")
+    g.set_defaults(run=_cmd_generate)
+
+    loc = sub.add_parser("locate", help="where a profile behind an exit IP is placed")
+    loc.add_argument("ip")
+    loc.add_argument("--seed", help="the profile's seed; a new one when omitted")
+    loc.add_argument("--geoip-db", help="a DB-IP City Lite .mmdb instead of the pinned build")
+    loc.set_defaults(run=_cmd_locate)
+
+    sub.add_parser("gpus", help="GPUs of the bundled captures").set_defaults(run=_cmd_gpus)
+    sub.add_parser("captures", help="the bundled captures").set_defaults(run=_cmd_captures)
+
+    geo = sub.add_parser("geoip", help="download and verify the pinned DB-IP database")
+    geo.add_argument("--archive", type=Path, help="a local copy of the pinned .mmdb.gz")
+    geo.set_defaults(run=_cmd_geoip)
+
+    val = sub.add_parser("validate", help="check a profile against the bundled schema")
+    val.add_argument("profile")
+    val.set_defaults(run=_cmd_validate)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    try:
+        return args.run(args)
+    except _ERRORS as e:
+        print(e, file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

phasmid_profile_gen/data/CLDR-LICENSE

@@ -0,0 +1,41 @@
+UNICODE LICENSE V3
+
+COPYRIGHT AND PERMISSION NOTICE
+
+Copyright © 2004-2025 Unicode, Inc.
+
+NOTICE TO USER: Carefully read the following legal agreement. BY
+DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR
+SOFTWARE, YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE
+TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT
+DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of data files and any associated documentation (the "Data Files") or
+software and any associated documentation (the "Software") to deal in the
+Data Files or Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, and/or sell
+copies of the Data Files or Software, and to permit persons to whom the
+Data Files or Software are furnished to do so, provided that either (a)
+this copyright and permission notice appear with all copies of the Data
+Files or Software, or (b) this copyright and permission notice appear in
+associated Documentation.
+
+THE DATA FILES AND SOFTWARE ARE 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 OF
+THIRD PARTY RIGHTS.
+
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE
+BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES,
+OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA
+FILES OR SOFTWARE.
+
+Except as contained in this notice, the name of a copyright holder shall
+not be used in advertising or otherwise to promote the sale, use or other
+dealings in these Data Files or Software without prior written
+authorization of the copyright holder.
+
+SPDX-License-Identifier: Unicode-3.0

phasmid_profile_gen/data/LICENSES.md

@@ -0,0 +1,16 @@
+# Bundled data: sources and licences
+
+Every file here is built by `scripts/build_data.py`; `manifest.json` names each
+source version and each file's sha256.
+
+| File | Source | Licence |
+| --- | --- | --- |
+| `captures.json.xz` | Harness dumps of real devices mapped onto the Phasmid profile schema. Only device data is kept, under a neutral name: no raw dump, no file name, no locale. | BSD 3-Clause (Phasmid) |
+| `locale.json.xz` `cldr` | Phasmid's `profiles/data/cldr/cldr.json`, extracted from [Unicode CLDR](https://cldr.unicode.org/) (tag in the file). | Unicode License v3, `CLDR-LICENSE` |
+| `locale.json.xz` `chromium` | Phasmid's `profiles/data/chromium/accept-languages.json`: Chromium's `IDS_ACCEPT_LANGUAGES` per desktop UI locale at Phasmid's Chromium tag, each source file named by git blob id. | Chromium's BSD-style licence |
+| `schema.json.xz` | Phasmid's `profiles/schema.json`. | BSD 3-Clause (Phasmid) |
+| `dbip-city-lite.json` | The pin (URL, sizes, sha256) of a DB-IP IP to City Lite build. The database is downloaded on first use, never bundled. | The database: CC BY 4.0, "IP Geolocation by DB-IP, https://db-ip.com"; profiles placed with it name it in `captured.note` |
+
+Not bundled, but used at runtime by the `location` extra: time zone boundaries
+from [timezone-boundary-builder](https://github.com/evansiroky/timezone-boundary-builder)
+via `timezonefinder-data` (ODbL 1.0, © OpenStreetMap contributors).

phasmid_profile_gen/data/dbip-city-lite.json

@@ -0,0 +1,11 @@
+{
+ "attribution": "IP Geolocation by DB-IP, https://db-ip.com",
+ "build": "2026-10",
+ "licence": "CC BY 4.0, https://creativecommons.org/licenses/by/4.0/ (db-ip.com/db/download/ip-to-city-lite)",
+ "mmdb_sha256": "9e250f02722d1ad1780f88192f0e908af285478a33e76b88b349c9181ae9d0f5",
+ "mmdb_size": 126998165,
+ "name": "DB-IP IP to City Lite",
+ "sha256": "c839d407f85a1e0bddba354cef16b2c398182d1c34ed8d985555dce134b36b14",
+ "size": 60193321,
+ "url": "https://download.db-ip.com/free/dbip-city-lite-2026-10.mmdb.gz"
+}