whisper-id 0.1.0__tar.gz

whisper_id-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,15 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e . pytest
+      - run: python -m pytest -q

whisper_id-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+permissions:
+  contents: read
+  id-token: write   # OIDC — PyPI Trusted Publishing (no API token/secret)
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - run: pip install build
+      - run: python -m build
+      # No password: pypa/gh-action-pypi-publish authenticates via OIDC against the
+      # Trusted Publisher you configure at pypi.org/manage/account/publishing
+      # (project: whisper-id, owner: whisper-sec, repo: whisper-py, workflow: publish.yml).
+      - uses: pypa/gh-action-pypi-publish@release/v1

whisper_id-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.venv/

whisper_id-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 viaGraph B.V. (Whisper Security)
+
+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.

whisper_id-0.1.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: whisper-id
+Version: 0.1.0
+Summary: Give any Python agent a real, routable Whisper IPv6 identity and safe egress.
+Project-URL: Homepage, https://whisper.online
+Project-URL: Source, https://github.com/whisper-sec/whisper-py
+Project-URL: Issues, https://github.com/whisper-sec/whisper-py/issues
+Author: Whisper Security
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,dns,egress,identity,ipv6,proxy,whisper
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: Name Service (DNS)
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.9
+Provides-Extra: socks
+Requires-Dist: pysocks>=1.7; extra == 'socks'
+Description-Content-Type: text/markdown
+
+# whisper-id
+
+A real, routable **IPv6 identity** and **safe egress** for any Python agent — in two calls.
+
+```sh
+pip install whisper-id            # add [socks] for requests+SOCKS: pip install "whisper-id[socks]"
+```
+
+```python
+from whisper_id import register, egress
+import requests
+
+agent = register("my-bot")                       # a routable Whisper /128 identity
+with egress():                                   # route this block through your /128
+    requests.get("https://api64.ipify.org").text # ← leaves from your Whisper IPv6
+```
+
+That's it. Inside the `with` block the standard proxy env vars point at your local Whisper
+proxy, so `requests`, `httpx`, `urllib`, and most libraries "just work"; on exit they're restored.
+
+## API
+
+| Call | Does |
+|------|------|
+| `register(name, *, new_key=False)` | Create a named agent — a routable `/128`. `new_key=True` mints a new agent **and** its own API key. → `Agent(address, id, name)` |
+| `egress(agent=None, *, tier="socks5", set_env=True)` | Context manager: bring up egress bound to your `/128`. Yields `Egress` (`.port`, `.proxy_url`, `.socks_url`, `.proxies`). `tier="wireguard"` for a routed `/128`. |
+| `verify(address)` | Keyless — is `address` a real Whisper agent? (DANE + DNSSEC + reverse-DNS + JWS) → `bool` |
+| `ip()` | Your current egress IP, proving it's your `/128`. → `str` |
+
+Pass the proxy explicitly instead of via env if you prefer:
+
+```python
+with egress(set_env=False) as e:
+    requests.get(url, proxies=e.proxies)
+```
+
+## Requirements
+
+The `whisper` CLI on your `PATH` (this package is a thin, dependency-free wrapper over it):
+
+```sh
+curl get.whisper.online | sh
+```
+
+For authenticated calls (`register`, `egress`, `ip`), set `WHISPER_API_KEY` in the environment
+or run `whisper login`. `verify` is keyless. (`$WHISPER_BIN` overrides the CLI path.)
+
+## Links
+
+- Site — https://whisper.online
+- CLI — https://github.com/whisper-sec/whisper-cli
+
+MIT licensed.

whisper_id-0.1.0/README.md

@@ -0,0 +1,53 @@
+# whisper-id
+
+A real, routable **IPv6 identity** and **safe egress** for any Python agent — in two calls.
+
+```sh
+pip install whisper-id            # add [socks] for requests+SOCKS: pip install "whisper-id[socks]"
+```
+
+```python
+from whisper_id import register, egress
+import requests
+
+agent = register("my-bot")                       # a routable Whisper /128 identity
+with egress():                                   # route this block through your /128
+    requests.get("https://api64.ipify.org").text # ← leaves from your Whisper IPv6
+```
+
+That's it. Inside the `with` block the standard proxy env vars point at your local Whisper
+proxy, so `requests`, `httpx`, `urllib`, and most libraries "just work"; on exit they're restored.
+
+## API
+
+| Call | Does |
+|------|------|
+| `register(name, *, new_key=False)` | Create a named agent — a routable `/128`. `new_key=True` mints a new agent **and** its own API key. → `Agent(address, id, name)` |
+| `egress(agent=None, *, tier="socks5", set_env=True)` | Context manager: bring up egress bound to your `/128`. Yields `Egress` (`.port`, `.proxy_url`, `.socks_url`, `.proxies`). `tier="wireguard"` for a routed `/128`. |
+| `verify(address)` | Keyless — is `address` a real Whisper agent? (DANE + DNSSEC + reverse-DNS + JWS) → `bool` |
+| `ip()` | Your current egress IP, proving it's your `/128`. → `str` |
+
+Pass the proxy explicitly instead of via env if you prefer:
+
+```python
+with egress(set_env=False) as e:
+    requests.get(url, proxies=e.proxies)
+```
+
+## Requirements
+
+The `whisper` CLI on your `PATH` (this package is a thin, dependency-free wrapper over it):
+
+```sh
+curl get.whisper.online | sh
+```
+
+For authenticated calls (`register`, `egress`, `ip`), set `WHISPER_API_KEY` in the environment
+or run `whisper login`. `verify` is keyless. (`$WHISPER_BIN` overrides the CLI path.)
+
+## Links
+
+- Site — https://whisper.online
+- CLI — https://github.com/whisper-sec/whisper-cli
+
+MIT licensed.

whisper_id-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "whisper-id"
+version = "0.1.0"
+description = "Give any Python agent a real, routable Whisper IPv6 identity and safe egress."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Whisper Security" }]
+keywords = ["whisper", "agent", "identity", "ipv6", "egress", "proxy", "dns"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Internet :: Name Service (DNS)",
+  "Topic :: System :: Networking",
+  "Intended Audience :: Developers",
+]
+
+[project.optional-dependencies]
+socks = ["PySocks>=1.7"]
+
+[project.urls]
+Homepage = "https://whisper.online"
+Source = "https://github.com/whisper-sec/whisper-py"
+Issues = "https://github.com/whisper-sec/whisper-py/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["whisper_id"]

whisper_id-0.1.0/tests/test_whisper_id.py

@@ -0,0 +1,129 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 viaGraph B.V. (Whisper Security)
+"""Unit tests for whisper-id — the CLI is mocked, so these run anywhere (no live box)."""
+from __future__ import annotations
+
+import os
+import subprocess
+from types import SimpleNamespace
+
+import pytest
+
+import whisper_id
+from whisper_id import Agent, WhisperError, egress, ip, register, verify
+
+
+def _proc(stdout="", stderr="", code=0):
+    return subprocess.CompletedProcess(args=["whisper"], returncode=code, stdout=stdout, stderr=stderr)
+
+
+@pytest.fixture(autouse=True)
+def _fake_cli(monkeypatch):
+    # Pretend the binary exists so cli_path() resolves without hitting the real PATH.
+    monkeypatch.setenv("WHISPER_BIN", "/usr/bin/whisper")
+    # Clean proxy env for deterministic save/restore assertions.
+    for k in whisper_id._PROXY_VARS:
+        monkeypatch.delenv(k, raising=False)
+
+
+def _capture(monkeypatch, proc):
+    calls = []
+
+    def fake_run(cmd, **kw):
+        calls.append(cmd)
+        return proc
+
+    monkeypatch.setattr(subprocess, "run", fake_run)
+    return calls
+
+
+def test_cli_path_missing(monkeypatch):
+    monkeypatch.delenv("WHISPER_BIN", raising=False)
+    monkeypatch.setattr(whisper_id.shutil, "which", lambda _: None)
+    with pytest.raises(WhisperError, match="not found on PATH"):
+        whisper_id.cli_path()
+
+
+def test_register_parses_address(monkeypatch):
+    calls = _capture(monkeypatch, _proc(stdout='{"agent":"2a04:2a01:b69a:6717:dead:beef:1:2","id":"ag_123"}'))
+    a = register("my-bot")
+    assert isinstance(a, Agent)
+    assert a.address == "2a04:2a01:b69a:6717:dead:beef:1:2"
+    assert a.id == "ag_123"
+    assert a.name == "my-bot"
+    assert calls[0][1:] == ["--json", "create", "--name", "my-bot"]
+
+
+def test_register_new_key_flag(monkeypatch):
+    calls = _capture(monkeypatch, _proc(stdout='{"address":"2a04:2a01:1::9"}'))
+    register("boot", new_key=True)
+    assert "--register" in calls[0]
+
+
+def test_register_requires_name():
+    with pytest.raises(WhisperError, match="non-empty"):
+        register("  ")
+
+
+def test_register_no_address_raises(monkeypatch):
+    _capture(monkeypatch, _proc(stdout='{"ok":true}'))
+    with pytest.raises(WhisperError, match="no /128"):
+        register("x")
+
+
+def test_egress_sets_and_restores_env(monkeypatch):
+    os.environ["HTTP_PROXY"] = "http://old:1"  # must be restored exactly
+    _capture(monkeypatch, _proc(stdout="whisper: connection up on 127.0.0.1:36123\n"))
+    with egress() as e:
+        assert e.port == 36123
+        assert e.proxy_url == "http://127.0.0.1:36123"
+        assert e.socks_url == "socks5h://127.0.0.1:36123"
+        assert os.environ["HTTP_PROXY"] == "http://127.0.0.1:36123"
+        assert os.environ["ALL_PROXY"] == "socks5h://127.0.0.1:36123"
+    assert os.environ["HTTP_PROXY"] == "http://old:1"  # restored
+    assert "ALL_PROXY" not in os.environ  # was unset before → unset after
+    del os.environ["HTTP_PROXY"]
+
+
+def test_egress_set_env_false_leaves_environ(monkeypatch):
+    _capture(monkeypatch, _proc(stdout="connection up on 127.0.0.1:40000"))
+    with egress(set_env=False) as e:
+        assert e.port == 40000
+        assert "HTTP_PROXY" not in os.environ
+
+
+def test_egress_passes_agent_and_tier(monkeypatch):
+    calls = _capture(monkeypatch, _proc(stdout="up on 127.0.0.1:5555"))
+    with egress(agent="2a04:2a01:1::1", tier="wireguard"):
+        pass
+    cmd = calls[0]
+    assert "--agent" in cmd and "2a04:2a01:1::1" in cmd
+    assert "wireguard" in cmd
+
+
+def test_egress_no_port_raises(monkeypatch):
+    _capture(monkeypatch, _proc(stdout="something went sideways"))
+    with pytest.raises(WhisperError, match="could not determine"):
+        with egress():
+            pass
+
+
+def test_verify_truthy_on_zero_exit(monkeypatch):
+    _capture(monkeypatch, _proc(code=0))
+    assert verify("2a04:2a01:1::1") is True
+
+
+def test_verify_false_on_nonzero(monkeypatch):
+    _capture(monkeypatch, _proc(code=3, stderr="not a whisper agent"))
+    assert verify("2001:db8::1") is False
+
+
+def test_ip_returns_address(monkeypatch):
+    _capture(monkeypatch, _proc(stdout='{"agent":"2a04:2a01:1::a","ip":"2a04:2a01:1::a","verified":true}'))
+    assert ip() == "2a04:2a01:1::a"
+
+
+def test_run_check_raises_with_stderr(monkeypatch):
+    _capture(monkeypatch, _proc(code=1, stderr="boom"))
+    with pytest.raises(WhisperError, match="boom"):
+        ip()

whisper_id-0.1.0/whisper_id/__init__.py

@@ -0,0 +1,219 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 viaGraph B.V. (Whisper Security)
+"""whisper-id — a real, routable IPv6 identity and safe egress for any Python agent.
+
+A thin, dependency-free wrapper over the ``whisper`` CLI (https://whisper.online).
+The CLI holds the auth, the control plane, and the egress tunnel; this package gives
+you a Pythonic ``register()`` / ``egress()`` / ``verify()`` / ``ip()`` surface over it.
+
+    from whisper_id import register, egress
+
+    agent = register("my-bot")            # a routable Whisper /128 identity
+    with egress():                        # route this block's traffic via your /128
+        import requests
+        requests.get("https://api64.ipify.org").text   # leaves from your Whisper IPv6
+
+Requires the ``whisper`` CLI on PATH (``curl get.whisper.online | sh``) and, for the
+authenticated calls, ``WHISPER_API_KEY`` in the environment (or a logged-in CLI).
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Iterator, Optional
+
+__all__ = [
+    "register",
+    "egress",
+    "verify",
+    "ip",
+    "Agent",
+    "Egress",
+    "WhisperError",
+    "cli_path",
+    "__version__",
+]
+__version__ = "0.1.0"
+
+# The publicly-announced Whisper agent prefix (AS219419) — used to liberally recover a
+# /128 from any control-plane envelope shape (Postel: be liberal in what we accept).
+_ADDR_RE = re.compile(r"2a04:2a01:[0-9a-fA-F:]{2,}")
+_HOSTPORT_RE = re.compile(r"127\.0\.0\.1:(\d{2,5})")
+_PROXY_VARS = ("HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY", "http_proxy", "https_proxy", "all_proxy")
+
+
+class WhisperError(RuntimeError):
+    """A ``whisper`` CLI invocation failed, or the CLI is not installed."""
+
+
+@dataclass(frozen=True)
+class Agent:
+    """A Whisper agent — a routable IPv6 /128 that is both the identity and the auth."""
+
+    address: str
+    id: Optional[str] = None
+    name: Optional[str] = None
+
+
+@dataclass
+class Egress:
+    """A live local egress proxy bound to your /128."""
+
+    port: int
+    address: Optional[str] = None
+
+    @property
+    def proxy_url(self) -> str:
+        return f"http://127.0.0.1:{self.port}"
+
+    @property
+    def socks_url(self) -> str:
+        return f"socks5h://127.0.0.1:{self.port}"
+
+    @property
+    def proxies(self) -> dict:
+        """A requests/httpx-style proxies mapping for explicit per-call use."""
+        return {"http": self.proxy_url, "https": self.proxy_url}
+
+
+def cli_path() -> str:
+    """Locate the ``whisper`` binary (``$WHISPER_BIN`` overrides ``PATH``)."""
+    found = os.environ.get("WHISPER_BIN") or shutil.which("whisper")
+    if not found:
+        raise WhisperError(
+            "the `whisper` CLI was not found on PATH. Install it with "
+            "`curl get.whisper.online | sh` (see https://whisper.online)."
+        )
+    return found
+
+
+def _run(args, *, timeout: int = 120, check: bool = True) -> subprocess.CompletedProcess:
+    cmd = [cli_path(), *args]
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+    except subprocess.TimeoutExpired as exc:  # pragma: no cover - timing dependent
+        raise WhisperError(f"`whisper {' '.join(args)}` timed out after {timeout}s") from exc
+    if check and proc.returncode != 0:
+        detail = (proc.stderr or proc.stdout or "").strip() or f"exit {proc.returncode}"
+        raise WhisperError(f"`whisper {' '.join(args)}` failed: {detail}")
+    return proc
+
+
+def _run_json(args, **kw):
+    proc = _run(["--json", *args], **kw)
+    out = (proc.stdout or "").strip()
+    try:
+        return json.loads(out)
+    except json.JSONDecodeError as exc:
+        raise WhisperError(
+            f"could not parse JSON from `whisper {' '.join(args)}`: {out[:200]!r}"
+        ) from exc
+
+
+def _first_addr(obj) -> Optional[str]:
+    """Pull the first Whisper /128 out of an arbitrary JSON envelope, or None."""
+    match = _ADDR_RE.search(json.dumps(obj))
+    return match.group(0) if match else None
+
+
+def _get(obj, *keys):
+    """Liberally fetch the first present key (one level deep), or None."""
+    if isinstance(obj, dict):
+        for key in keys:
+            if obj.get(key):
+                return obj[key]
+        for value in obj.values():
+            if isinstance(value, dict):
+                got = _get(value, *keys)
+                if got:
+                    return got
+    return None
+
+
+def register(name: str, *, new_key: bool = False, timeout: int = 120) -> Agent:
+    """Create a named agent identity — a routable Whisper IPv6 /128.
+
+    Drives ``whisper create --name <name>``. Pass ``new_key=True`` to mint a brand-new
+    agent *with its own API key* (``op:register``). Requires ``WHISPER_API_KEY`` (or a
+    logged-in CLI), except ``new_key=True`` which bootstraps its own key.
+    """
+    if not name or not name.strip():
+        raise WhisperError("register() needs a non-empty agent name")
+    args = ["create", "--name", name]
+    if new_key:
+        args.append("--register")
+    env = _run_json(args, timeout=timeout)
+    addr = _first_addr(env)
+    if not addr:
+        raise WhisperError(f"no /128 returned by `whisper create`: {json.dumps(env)[:200]}")
+    return Agent(address=addr, id=_get(env, "id", "agent_id", "agentId"), name=name)
+
+
+@contextmanager
+def egress(
+    agent: Optional[str] = None,
+    *,
+    tier: str = "socks5",
+    set_env: bool = True,
+    timeout: int = 90,
+) -> Iterator[Egress]:
+    """Bring egress up bound to your /128 and route this block's traffic through it.
+
+    Drives ``whisper connect --ensure`` (an idempotent, detached local proxy). While the
+    ``with`` block is active the standard proxy env vars (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY)
+    point at the local proxy; on exit they are restored to their prior values. The proxy
+    daemon itself is left running (it is shared and idempotent).
+
+        with egress() as e:
+            requests.get("https://api64.ipify.org")          # via your /128
+            requests.get(url, proxies=e.proxies)             # or pass explicitly
+
+    Set ``set_env=False`` to only start the proxy and receive the :class:`Egress` handle
+    without mutating the process environment.
+    """
+    args = ["connect", "--ensure", "--tier", tier]
+    if agent:
+        args += ["--agent", agent]
+    proc = _run(args, timeout=timeout)
+    text = (proc.stdout or "") + "\n" + (proc.stderr or "")
+    match = _HOSTPORT_RE.search(text)
+    if not match:
+        raise WhisperError(
+            f"could not determine the local proxy port from `whisper connect`: {text.strip()[:200]!r}"
+        )
+    handle = Egress(port=int(match.group(1)), address=agent)
+    saved = {k: os.environ.get(k) for k in _PROXY_VARS} if set_env else {}
+    try:
+        if set_env:
+            os.environ["HTTP_PROXY"] = os.environ["http_proxy"] = handle.proxy_url
+            os.environ["HTTPS_PROXY"] = os.environ["https_proxy"] = handle.proxy_url
+            os.environ["ALL_PROXY"] = os.environ["all_proxy"] = handle.socks_url
+        yield handle
+    finally:
+        for key, value in saved.items():
+            if value is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = value
+
+
+def verify(address: str, *, timeout: int = 60) -> bool:
+    """Return ``True`` iff ``address`` is a real Whisper agent.
+
+    Keyless: drives ``whisper verify`` (DANE + DNSSEC + reverse-DNS + JWS). Never raises
+    on a negative verdict — it returns ``False``.
+    """
+    if not address or not address.strip():
+        raise WhisperError("verify() needs an address")
+    return _run(["verify", address], timeout=timeout, check=False).returncode == 0
+
+
+def ip(*, timeout: int = 60) -> str:
+    """Return the current egress IP, proving it is your Whisper /128 (drives ``whisper ip``)."""
+    env = _run_json(["ip"], timeout=timeout)
+    return _get(env, "ip", "agent") or _first_addr(env) or ""