ant0-browser 0.1.0__py3-none-any.whl

ant0_browser-0.1.0.dist-info/METADATA

@@ -0,0 +1,213 @@
+Metadata-Version: 2.5
+Name: ant0-browser
+Version: 0.1.0
+Summary: Local Playwright launcher for the Ant0 Browser research build.
+Project-URL: Homepage, https://docs.ant0.link/sdk
+Project-URL: Support, https://ant0.link/contact
+License: BSD-3-Clause
+License-File: LICENSE
+Keywords: ant0-browser,anti-detect,anti-fingerprint,automation,chromium,farbling,fingerprint,playwright,stealth,ungoogled
+Requires-Python: >=3.9
+Requires-Dist: maxminddb>=2.2
+Requires-Dist: playwright>=1.40
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Ant0 Browser Python SDK
+
+Local Playwright launcher for a caller-supplied Ant0 Browser build. This package contains Python
+SDK code, **not the engine**, browser assets, or account credentials. The SDK code is BSD-3-Clause
+licensed; using the engine requires a separately installed Ant0 Browser build and signing in with a
+valid Ant0 licence. Native identity needs no synthetic assets; synthetic identities require separately
+authorized local model/template assets.
+
+Once version `0.1.0` is available from PyPI, install it with `python -m pip install ant0-browser==0.1.0`.
+For local candidate installs, use `ant0_browser-0.1.0-py3-none-any.whl` or
+`ant0_browser-0.1.0.tar.gz`; these filenames do not indicate registry availability.
+
+## Local package preparation and installation
+
+Prerequisites: Python with `venv` and pip, and access to the package index for build/runtime
+dependencies. Metadata declares Python 3.9+; this local qualification used Python 3.12, not every
+supported interpreter. pip installs `playwright>=1.40` and `maxminddb>=2.2`. An unsupported platform
+may need a compiler to build dependencies when their wheels are unavailable. Do not run
+`playwright install`: it would download stock browser binaries, not Ant0's engine.
+
+From the repository root, build both `0.1.0` candidate artifacts without publishing:
+
+```bash
+SDK_SOURCE="$PWD/sdk/python"
+ARTIFACT_DIR="$HOME/ant0-sdk-artifacts"
+mkdir -p "$ARTIFACT_DIR"
+python3 -m venv "$ARTIFACT_DIR/build-venv"
+"$ARTIFACT_DIR/build-venv/bin/python" -m pip install build
+"$ARTIFACT_DIR/build-venv/bin/python" -m build --outdir "$ARTIFACT_DIR" "$SDK_SOURCE"
+```
+
+The candidate filenames are `ant0_browser-0.1.0-py3-none-any.whl` and
+`ant0_browser-0.1.0.tar.gz`. Install each into its own fresh consumer venv outside the checkout,
+not as an editable/source install:
+
+```bash
+CONSUMER_DIR="$(mktemp -d)"
+cd "$CONSUMER_DIR"
+python3 -m venv wheel-venv
+python3 -m venv sdist-venv
+wheel-venv/bin/python -m pip install "$ARTIFACT_DIR/ant0_browser-0.1.0-py3-none-any.whl"
+sdist-venv/bin/python -m pip install "$ARTIFACT_DIR/ant0_browser-0.1.0.tar.gz"
+```
+
+Optional installed-package qualification (no engine launch, daemon discovery, or account access):
+copy the committed smoke script into that consumer. Isolated Python ignores checkout/PYTHONPATH
+imports; run deterministic sync/async checks and console help in both environments:
+
+```bash
+cp "$SDK_SOURCE/scripts/installed_smoke.py" .
+for VENV in wheel-venv sdist-venv; do
+  "$VENV/bin/python" -I installed_smoke.py
+  "$VENV/bin/python" -m pip check
+  "$VENV/bin/ant0-browser-serve" --help
+done
+```
+
+These examples use POSIX venv paths; on Windows use `Scripts/python.exe` and
+`Scripts/ant0-browser-serve.exe`. Remove only the temporary consumer/build venv you created when
+finished. These checks qualify package contents and deterministic SDK operations, not engine
+launches or registry availability.
+
+## Using a separately installed engine
+
+For current signed releases, first install Ant0 and sign in to the local `ant0d` with a valid
+licence. Supply the complete matching Ant0 engine installation via `executable_path` or
+`ANT0_BROWSER_BINARY`; arbitrary stock Chrome/Chromium is rejected by the SDK's capability check.
+The daemon must issue a launch ticket for that **exact engine release version**, not the SDK package
+version. See Launch ticket below. Setting `launch_ticket=False` does not bypass engine enforcement.
+New synthetic identities additionally require authorized local model/template assets; the package
+contains neither. The following native-mode example needs no synthetic assets:
+
+```python
+from ant0browser import launch
+
+browser = launch(
+    executable_path=r"C:\path\to\chrome.exe",
+    identity={"mode": "native"},
+)
+page = browser.new_page()
+page.goto("https://example.com")
+browser.close()
+```
+
+Set `ANT0_BROWSER_BINARY` instead of passing `executable_path` on every call. A previously populated
+cache is resolved without network access. If no local binary is found, the SDK stops with
+instructions to build the browser and set its path, unless `ANT0_BROWSER_RELEASE_URL` points at a
+release store: then the SDK installs the channel's release after verifying its minisign signature
+and hashes against the key embedded in the SDK (see `docs/RELEASING.md`).
+
+The async API mirrors launch and persistent contexts:
+
+```python
+from ant0browser.async_api import launch
+
+browser = await launch(executable_path="/path/to/chrome", identity={"mode": "native"})
+```
+
+Retained helpers include:
+
+- `launch()` and `launch_persistent_context()`
+- `serve()` and the `ant0-browser-serve` local CDP command
+- native, captured, and persisted synthetic identities
+- canonical template loading via `ANT0_BROWSER_TEMPLATE_SOURCE`
+- fingerprint-profile encoding, geometry and coherence warnings
+- humanized input wrappers and rendering checks
+- optional GeoIP (Ant0's `ip.ant0.link` + offline database, see Network calls) and Widevine helpers
+
+Omitting `identity` means native mode. The removed `fingerprint`, `fingerprint_profile`,
+`light_stealth`, `profile`, `profile_select`, and `geoip` launch options are rejected. Use
+`resolve_geo()` explicitly when needed and place its identity values under `overrides`. Explicit identity
+switches belong under `overrides`; supported keys are `platform`, `platform_version`, `brand`,
+`brand_version`, `gpu_vendor`, `gpu_renderer`, hardware/display fields, `location`, `timezone`,
+`accept_language`, WebRTC/GPU/noise controls, `storage_quota`, `canvas_bridge`, and `tls_profile`.
+Overrides take precedence over captured or synthetic profiles.
+
+The SDK resolves browser binaries and identity templates locally by default. Automatic launch-ticket
+requests go only to the local daemon; optional asset/release and GeoIP requests are listed below.
+
+## Network calls
+
+Nothing in `launch`/`serve` leaves the machine on its own: the only automatic request is to the
+**local** `ant0d` for a launch ticket (loopback, see the first row). The optional helpers do, and only when
+called:
+
+| Helper | Endpoint | Purpose |
+| --- | --- | --- |
+| `launch()` / `serve()` | local `ant0d` only (`ANT0_URL`, else `ant0d.pid`/`ant0d.token` under `ANT0_HOME`/the platform data folder; loopback) | `GET /v1/licence/ticket?engine=<version>` to obtain the engine's launch ticket when the caller passed no `launch_ticket` (see below). Skipped when no daemon token exists, when `launch_ticket=False`, or when the binary is not an installed release. |
+| `resolve_geo()` | `http://ip.ant0.link/` (then `https://ip.ant0.link/`; `api.ipify.org` and `ip-api.com` only if both fail) | Exit-IP echo, sent *through the configured HTTP proxy* so the proxy's exit is measured. Ant0's echo runs with zero request logging (`ant0-infra/ipecho`). |
+| `resolve_geo()` | `https://releases.ant0.link/ant0-assets/geoip/v1/geoip-aio-all.mmdb.zip` | Offline geo database (~52 MB, cached in the SDK cache dir for 30 days), fetched directly, not through the proxy. Mirror of daijro/geoip-all-in-one. |
+| `resolve_geo()` | `http://ip.ant0.link/json` | Geo for the exit IP computed server-side from the same database; used only when the local database is unavailable. |
+| release install | `ANT0_BROWSER_RELEASE_URL` (opt-in) | Signed engine releases. |
+| font pack / model | `ANT0_BROWSER_FONT_PACK_URL`, `ANT0_BROWSER_MODEL_SOURCE`, `ANT0_BROWSER_TEMPLATE_SOURCE` (opt-in) | Assets. |
+
+Overrides: `ANT0_BROWSER_IPECHO_URL`, `ANT0_BROWSER_GEOIP_URL`, `ANT0_BROWSER_GEOJSON_URL` (read at call time). Set `ANT0_BROWSER_IPECHO_URL` to disable the third-party
+last-resort echoes entirely (only the given URL is tried).
+
+Geo data attribution (required by the sources merged into geoip-all-in-one, GPL-3.0): this product
+uses the IP2Location LITE database for IP geolocation (https://lite.ip2location.com); includes
+GeoLite2 data created by MaxMind, available from https://www.maxmind.com/; IP geolocation by DB-IP
+(https://db-ip.com). The database carries country, coordinates and timezone only.
+
+## Launch ticket (engine patch 0037)
+
+Engine releases built with patch `0037-launch-ticket` refuse to start without
+`--ant0-launch=<ticket>`: a licence token from the Ant0 server plus a 15-minute claim signed by the
+local device key, bound to the engine's release version (`ant0/docs/PHASE3-CONTRACT.md` §10). The
+SDK cannot mint one; it resolves the switch like this:
+
+1. `launch_ticket="<lic.claim.csig>"` — passed through verbatim.
+2. `--ant0-launch=` already in `args` — kept.
+3. Otherwise, when a local daemon is reachable (see the table above) and the engine's release version
+   is known (`.release.json` next to the install's `browser/`, a `<version>/browser/` path, or
+   `ANT0_BROWSER_ENGINE_VERSION`), the SDK fetches one. `engine_version=` overrides the inference.
+4. Else (`launch_ticket=False`, no daemon, daemon refuses, bare binary) the launch proceeds without
+   the switch. A patched engine then exits with code 90 and `ant0: launch ticket invalid (<reason>)`
+   on stderr, which `launch()`, `launch_persistent_context()`, the async API and `serve()` surface as
+   `LaunchTicketRejectedError` (`code == "engine.launch_ticket_rejected"`, `reason` as printed by
+   the engine: `missing`, `unknown_kid`, `wrong_engine`, `claim_expired`, ...). Pre-0037 engines
+   ignore the switch.
+
+## Known engine behaviours
+
+- **Profile portability is not a Chromium launch mode.** The removed `portable_profile` and
+  `encryption_key` options did not provide supported engine portability. Cross-machine sync must use
+  authenticated encrypted Ant0 bundles of logical profile data, not copied raw user-data directories
+  or Chromium portability flags.
+- **No SOCKS5 username/password authentication.** The engine has no RFC 1929 client (stock Chromium
+  has none and no Ant0 patch adds one), and Playwright rejects credentials in a SOCKS proxy
+  descriptor. `launch()`, `launch_persistent_context()` and `serve()` therefore raise `ValueError`
+  on a `socks*://` proxy with `username`/`password`. Use an `http(s)://` proxy with credentials
+  (Playwright handles those), a SOCKS5 proxy that allows your client IP without credentials, or a
+  local relay that authenticates upstream (the `ant0d` daemon runs one per session) and pass its
+  unauthenticated loopback address.
+- **Direct launches show the ungoogled first-run page without hygiene switches.** Playwright's
+  `launch()` passes `--no-first-run`, `--no-default-browser-check` and
+  `--disable-search-engine-choice-screen` itself; a binary spawned directly with none of them opens
+  `chrome://ungoogled-first-run` ("ungoogled-chromium first run page", empty body) in the first tab
+  when no start URL is given. `serve()` adds those three switches (plain UI
+  switches, no `base::Feature` toggles, so nothing a page can observe changes and the identity
+  layer's feature flags are untouched) and append `about:blank` as the final positional when `args`
+  carries no URL, so the first tab is neutral. A caller URL in `args` suppresses the `about:blank`.
+
+## Source development and verification
+
+From the repository root of an authorized private checkout, use a development venv with the test
+extra installed. This editable install is for source tests, not installed-artifact qualification:
+
+```bash
+python3 -m venv "$ARTIFACT_DIR/test-venv"
+"$ARTIFACT_DIR/test-venv/bin/python" -m pip install -e './sdk/python[test]'
+PYTHONDONTWRITEBYTECODE=1 "$ARTIFACT_DIR/test-venv/bin/python" -m pytest -p no:cacheprovider sdk/python/tests
+```
+
+Leave `ANT0_BROWSER_TEST_BINARY` unset for the engine-free suite; the real-engine serve test is
+opt-in and excluded from this package qualification.

ant0_browser-0.1.0.dist-info/RECORD

@@ -0,0 +1,35 @@
+ant0browser/__init__.py,sha256=lqPwWWbag2XSreYUHkbe9fV29IDGZWSQv-5PiDXq8Jc,25455
+ant0browser/_fingerprint.py,sha256=OMeXSAgI2LT3Aj4koB0KTNbrS00xEYzM8R1nLDL8PJ0,23160
+ant0browser/_fontpersona.py,sha256=ZkJNVn2Sgv4_xoENYk2nSgPUhYT1ki0YybBYQPgT-XA,7386
+ant0browser/_fonts.py,sha256=fZ0xp-l3L7csrD_CSDOjNWkW-mLNLtimS36fzATINmA,4884
+ant0browser/_geometry.py,sha256=1jStCw4sIHQacZN1PElbjEN3jmpiphA8-t6G7zlDOO0,3481
+ant0browser/_humanize.py,sha256=dXWI5urkOchB8AO0h8iJ4tzwSwMauWvHf6VZQOT2XHg,47521
+ant0browser/_humanize_async.py,sha256=KAndO4GcvIbYL07YvpqxadI9H38tpKwzSRRKKW0ulDs,34021
+ant0browser/_launch_ticket.py,sha256=Aajm_vKl7C-QGitkMFcW9hJvZJpO8SEH5JLEYHR_9lE,11945
+ant0browser/_launchopts.py,sha256=iwL0oBnEINnJjLHdszm7Yc9gKxwe_MhhVIA3gHUi9kM,12188
+ant0browser/_motion.py,sha256=tPefe5SkS3t_9DJZQV3tFOz7JGWJl9c7FK-EshpMe2c,14358
+ant0browser/_motionscore.py,sha256=4ijyYD4kesN1I0OHQG-Y7teY-rIun1vQMmy1FiciV3k,13470
+ant0browser/_render.py,sha256=gocZaLuY6hZKZKzkpSvkwM6uYsI5NGmfEvBjcEXS-eQ,6034
+ant0browser/_render_async.py,sha256=2nNhcHuvua6txZ05YS7i-xzXPj_qFE1BvCcU3YrJbqc,828
+ant0browser/_serve.py,sha256=mSEeDX31n4wbZLwyJqKpcOt02q1nLMd9a6eEhQAwdgY,14613
+ant0browser/_shaderdialect.py,sha256=BYDnK5ZU6m2cIoolAvq_yhj6q4ahyZb5PjR8yjcTYfw,1928
+ant0browser/_warnings.py,sha256=c96n7CrSLstKdBWruAZT-5frwT2D0928r9KNOIU1J68,14199
+ant0browser/_widevine.py,sha256=KMQrzpkndYeds557D0Wz4aMcdrWNiAz0ij97AfXRVRQ,11641
+ant0browser/async_api.py,sha256=9XHuW1bBiLFCNMt7J6En5q-eUrCSz5C_5KdJbiEuQb8,11557
+ant0browser/chromium_version.py,sha256=wMW5e1wyzIncBd7r_qGmoVc5keS7BE_tanJMdTrRaDw,946
+ant0browser/download.py,sha256=xnXPvlrqvMl2-y4s0tpQBncjK46p8hLt2lartdwG4Uc,8363
+ant0browser/fontpack.py,sha256=9dz7AHvWJtXABmoegcLqtm_BAf7zfsmjWXHJK_DCETU,6097
+ant0browser/geoip.py,sha256=W1veUaQ14SCRxM61lcSoKeWdVMLxX1-1KaVeTDqZEaE,11661
+ant0browser/identity.py,sha256=B4_l4MooJ3ZEx2zJg8uEQ-mvxgZxmQ6zIn1NpZ5ThxY,11107
+ant0browser/identity_persistence.py,sha256=3j2_pfeAjiSZCZq5OUjxBFlc_E15GRM2nIgnlY045us,11916
+ant0browser/persona_migration.py,sha256=GsDS93k4_L2CzAqPrDQxF5nSY7akVwr2Q7CyqQ2JhA8,4447
+ant0browser/persona_profile.py,sha256=E4evMC71cCi99ioHJizJxsp1M_y92yQF8XH3j1MgiTo,16822
+ant0browser/population_model.py,sha256=WEHGsruLJEygX8rfvZVgzc4mNrMwfZ2VTNy-g-Gwulk,8523
+ant0browser/release.py,sha256=pE8Nc8lshCNPNU1jfOf3Te0B7LtHyrbrwjrVmU1fKbw,985
+ant0browser/release_fetch.py,sha256=SEyZemhM1UmaZwKfApwrLDJE7efDbpsiYPlv4sPLMoc,15209
+ant0browser/template_selection.py,sha256=G7TA18bHNDhWnilDX7NhvXKPkyLR4d6rDaDXIyB9YMo,2720
+ant0_browser-0.1.0.dist-info/METADATA,sha256=9ZZzywlFXN6cNtENU3FQjY9kly7Bd6E1fbOu4UmYfMI,12267
+ant0_browser-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+ant0_browser-0.1.0.dist-info/entry_points.txt,sha256=nWaOOvK_HS3d2liFQgCRdOcFfrgRzkth4ET5rIz-0mw,68
+ant0_browser-0.1.0.dist-info/licenses/LICENSE,sha256=9aLoPs9Tq49KwlGaSikFR7XIKgJk3khtzQZlpl5v09c,1803
+ant0_browser-0.1.0.dist-info/RECORD,,

ant0_browser-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

ant0_browser-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ant0-browser-serve = ant0browser._serve:_cli_main

ant0_browser-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,35 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Ant0 Browser contributors
+Copyright (c) 2026, Clearcote Labs and the Clearcote contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+---
+
+The Clearcote notice above applies to source and patches imported into Ant0
+Browser. Other upstream components (Chromium, ungoogled-chromium, and others)
+are distributed under their respective licenses; see CREDITS.md.