personaltunnel-python-client 0.1.0__tar.gz

personaltunnel_python_client-0.1.0/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv init:*)",
+      "Bash(uv add:*)",
+      "Bash(uv run:*)"
+    ]
+  }
+}

personaltunnel_python_client-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+personaltunnel-*.md
+snuggly-*.md
+.DS_Store

personaltunnel_python_client-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

personaltunnel_python_client-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: personaltunnel-python-client
+Version: 0.1.0
+Summary: Python asyncio client library for the personaltunnel Go server
+Requires-Python: >=3.11
+Requires-Dist: bip-utils>=2.9.0
+Requires-Dist: cffi<2.0
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: httpx>=0.27.0

personaltunnel_python_client-0.1.0/personaltunnel_client/__init__.py

@@ -0,0 +1,29 @@
+"""
+personaltunnel_client — asyncio Python client library for the personaltunnel Go server.
+
+Quick start::
+
+    import asyncio
+    from personaltunnel_client import PersonalTunnelClient, generate_keypair
+
+    # Generate a keypair (one-time setup — share your public key with the server operator)
+    priv_hex, pub_hex = generate_keypair()
+
+    async def main():
+        async with PersonalTunnelClient(
+            server_addr="vps.example.com",
+            control_port=7000,
+            local_addr="localhost:8000",
+            client_priv_key=priv_hex,
+            server_pub_key="<server_pub_hex>",
+        ):
+            print("Tunnel active. Press Ctrl+C to stop.")
+            await asyncio.Event().wait()  # run forever
+
+    asyncio.run(main())
+"""
+
+from .client import PersonalTunnelClient
+from .crypto import generate_keypair
+
+__all__ = ["PersonalTunnelClient", "generate_keypair"]

personaltunnel_python_client-0.1.0/personaltunnel_client/client.py

@@ -0,0 +1,234 @@
+"""
+PersonalTunnelClient — asyncio client that connects to the personaltunnel
+Go server, authenticates via the Nostr handshake, and forwards public HTTP
+requests to a local service via yamux streams.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+from typing import Awaitable, Callable, Optional
+
+from .crypto import EncConn, HandshakeError, client_handshake
+from .forward import handle_stream
+from .yamux import YamuxSession
+
+logger = logging.getLogger(__name__)
+
+
+class PersonalTunnelClient:
+    """
+    Asyncio client library for the personaltunnel Go server.
+
+    Connects to the server's control port, performs Nostr mutual-auth,
+    multiplexes incoming HTTP requests over a yamux session, and forwards
+    each request to a local service. Reconnects automatically with
+    exponential backoff on connection loss.
+
+    Usage::
+
+        # Async context manager (tunnel runs as a background task)
+        async with PersonalTunnelClient(
+            server_addr="vps.example.com",
+            control_port=7000,
+            local_addr="localhost:8000",
+            client_priv_key="<hex>",
+            server_pub_key="<hex>",
+        ) as client:
+            await asyncio.sleep(3600)
+
+        # Explicit background task
+        client = PersonalTunnelClient(...)
+        task = await client.start()
+        await asyncio.sleep(3600)
+        await client.stop()
+
+        # Blocking run (never returns until stop() is called elsewhere)
+        await client.run()
+    """
+
+    def __init__(
+        self,
+        server_addr: str,
+        control_port: int,
+        local_addr: str,
+        client_priv_key: str,
+        server_pub_key: str,
+        reconnect_interval: float = 2.0,
+        on_connect: Optional[Callable[[], Awaitable[None] | None]] = None,
+        on_disconnect: Optional[
+            Callable[[Optional[Exception]], Awaitable[None] | None]
+        ] = None,
+    ) -> None:
+        """
+        Args:
+            server_addr:         Hostname or IP of the VPS running the Go server.
+            control_port:        Control port of the Go server (typically 7000).
+            local_addr:          Local service to forward traffic to
+                                 (e.g. "localhost:8000").
+            client_priv_key:     Hex-encoded 32-byte secp256k1 private key.
+            server_pub_key:      Hex-encoded 32-byte x-only secp256k1 public key
+                                 of the server (from ``generate_keypair()``).
+            reconnect_interval:  Base reconnect delay in seconds (doubles on
+                                 each failure, capped at 60 s).
+            on_connect:          Optional async or sync callback invoked each
+                                 time the tunnel connects successfully.
+            on_disconnect:       Optional async or sync callback invoked when
+                                 the tunnel disconnects. Receives the exception
+                                 that caused the disconnect (or None on clean close).
+        """
+        self.server_addr = server_addr
+        self.control_port = control_port
+        self.local_addr = local_addr
+        self.reconnect_interval = reconnect_interval
+        self.on_connect = on_connect
+        self.on_disconnect = on_disconnect
+
+        # Pre-decode keys so errors surface at construction time.
+        self._client_priv_bytes: bytes = bytes.fromhex(client_priv_key)
+        self._server_pub_x: bytes = bytes.fromhex(server_pub_key)
+
+        if len(self._client_priv_bytes) != 32:
+            raise ValueError("client_priv_key must be a 32-byte (64 hex char) key")
+        if len(self._server_pub_x) != 32:
+            raise ValueError("server_pub_key must be a 32-byte (64 hex char) x-only key")
+
+        self._stop_event: asyncio.Event | None = None
+        self._task: asyncio.Task | None = None
+        self._active_session: YamuxSession | None = None
+
+    # ── Public API ───────────────────────────────────────────────────────────
+
+    async def start(self) -> asyncio.Task:
+        """
+        Start the tunnel in a background asyncio Task.
+
+        Returns the running Task so callers can await it or cancel it if needed.
+        """
+        self._stop_event = asyncio.Event()
+        self._task = asyncio.create_task(
+            self._run_loop(), name="personaltunnel-client"
+        )
+        return self._task
+
+    async def stop(self) -> None:
+        """Signal the client to stop and wait for the background task to finish."""
+        if self._stop_event:
+            self._stop_event.set()
+        if self._active_session:
+            await self._active_session.close()
+        if self._task and not self._task.done():
+            try:
+                await asyncio.wait_for(self._task, timeout=5.0)
+            except (asyncio.TimeoutError, asyncio.CancelledError):
+                self._task.cancel()
+
+    async def run(self) -> None:
+        """
+        Run the tunnel reconnect loop until stop() is called.
+
+        Useful as a top-level coroutine::
+
+            client = PersonalTunnelClient(...)
+            await client.run()
+        """
+        self._stop_event = asyncio.Event()
+        await self._run_loop()
+
+    async def __aenter__(self) -> "PersonalTunnelClient":
+        await self.start()
+        return self
+
+    async def __aexit__(self, *_args: object) -> None:
+        await self.stop()
+
+    # ── Internal ─────────────────────────────────────────────────────────────
+
+    async def _run_loop(self) -> None:
+        """Reconnect loop with exponential backoff."""
+        assert self._stop_event is not None
+
+        backoff = self.reconnect_interval
+
+        while not self._stop_event.is_set():
+            exc: Exception | None = None
+            try:
+                await self._connect_once()
+                backoff = self.reconnect_interval
+            except asyncio.CancelledError:
+                return
+            except (HandshakeError, ValueError) as e:
+                logger.error("tunnel: auth error: %s", e)
+                exc = e
+            except Exception as e:
+                logger.warning("tunnel: disconnected (%r), retry in %.1fs", e, backoff)
+                exc = e
+            else:
+                logger.info("tunnel: session closed cleanly")
+
+            if self.on_disconnect:
+                await _maybe_await(self.on_disconnect(exc))
+
+            # Wait for backoff duration (wake immediately if stop() is called).
+            try:
+                await asyncio.wait_for(
+                    asyncio.shield(self._stop_event.wait()),
+                    timeout=backoff,
+                )
+                return  # stop was requested
+            except asyncio.TimeoutError:
+                pass
+
+            if exc is not None:
+                backoff = min(backoff * 2, 60.0)
+
+    async def _connect_once(self) -> None:
+        """Open one connection to the server and serve streams until closed."""
+        addr = f"{self.server_addr}:{self.control_port}"
+        logger.info("tunnel: connecting to %s", addr)
+
+        reader, writer = await asyncio.wait_for(
+            asyncio.open_connection(self.server_addr, self.control_port),
+            timeout=10.0,
+        )
+
+        try:
+            enc_conn: EncConn = await client_handshake(
+                reader,
+                writer,
+                self._client_priv_bytes,
+                self._server_pub_x,
+            )
+
+            session = YamuxSession(enc_conn)
+            self._active_session = session
+            await session.start()
+
+            logger.info("tunnel: connected and authenticated to %s", addr)
+            if self.on_connect:
+                await _maybe_await(self.on_connect())
+
+            while not session.closed:
+                stream = await session.accept()
+                if stream is None:
+                    break
+                asyncio.create_task(
+                    handle_stream(stream, self.local_addr),
+                    name=f"stream-{stream._stream_id}",
+                )
+
+        finally:
+            self._active_session = None
+            writer.close()
+            try:
+                await writer.wait_closed()
+            except Exception:
+                pass
+
+
+async def _maybe_await(result: object) -> None:
+    """Await *result* if it is a coroutine, otherwise discard it."""
+    if inspect.isawaitable(result):
+        await result  # type: ignore[arg-type]

personaltunnel_python_client-0.1.0/personaltunnel_client/crypto.py

@@ -0,0 +1,229 @@
+"""
+Nostr mutual-auth handshake and ChaCha20-Poly1305 encrypted connection.
+
+Wire protocol (client side):
+  Step 1 receive: nonce_s (32) + server_pub_x_only (32)
+  Step 1 send:    nonce_c (32) + client_pub_x_only (32)
+  Step 2 send:    schnorr_sig(SHA256(nonce_s)) (64 bytes)
+  Step 2 receive: schnorr_sig(SHA256(nonce_c)) (64 bytes)
+  Step 3 receive: status byte (0x00 = OK, 0x01 = rejected)
+  Step 4:         ECDH + HKDF → 32-byte ChaCha20-Poly1305 key
+
+Crypto dependencies:
+  - coincurve (via bip-utils): secp256k1 Schnorr BIP340 sign/verify, ECDH
+  - cryptography: ChaCha20-Poly1305 AEAD, HKDF-SHA256
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import os
+import struct
+
+import coincurve
+from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305
+from cryptography.hazmat.primitives.hashes import SHA256
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+_MAX_MESSAGE_SIZE = 1 << 20  # 1 MiB, matches Go's maxMessageSize
+_HKDF_INFO = b"personaltunnel-v1"
+_STATUS_OK = 0x00
+
+
+class HandshakeError(Exception):
+    """Raised when the Nostr mutual-auth handshake fails."""
+
+
+class EncConn:
+    """
+    Async ChaCha20-Poly1305 encrypted connection.
+
+    Wire format per message:
+        4 bytes  big-endian uint32: length of ciphertext (incl. 16-byte AEAD tag)
+        N bytes  ChaCha20-Poly1305 ciphertext
+
+    Nonces are 12-byte little-endian encodings of a uint64 counter (separate
+    send/recv sequences starting at 0), matching Go's encconn.go seqNonce().
+    """
+
+    def __init__(
+        self,
+        reader: asyncio.StreamReader,
+        writer: asyncio.StreamWriter,
+        key: bytes,
+    ) -> None:
+        self._reader = reader
+        self._writer = writer
+        self._aead = ChaCha20Poly1305(key)
+        self._send_lock = asyncio.Lock()
+        self._send_seq: int = 0
+        self._recv_seq: int = 0
+        self._recv_buf = bytearray()
+
+    @staticmethod
+    def _seq_nonce(seq: int) -> bytes:
+        """12-byte little-endian nonce from a uint64 counter (4 zero pad bytes)."""
+        return struct.pack("<Q", seq) + b"\x00\x00\x00\x00"
+
+    async def send_msg(self, plaintext: bytes) -> None:
+        """Encrypt plaintext and write as a single length-prefixed message."""
+        async with self._send_lock:
+            nonce = self._seq_nonce(self._send_seq)
+            self._send_seq += 1
+            ciphertext = self._aead.encrypt(nonce, plaintext, None)
+            if len(ciphertext) > _MAX_MESSAGE_SIZE:
+                raise ValueError(f"message too large: {len(ciphertext)} bytes")
+            self._writer.write(struct.pack(">I", len(ciphertext)) + ciphertext)
+            await self._writer.drain()
+
+    async def recv_msg(self) -> bytes:
+        """Read and decrypt the next length-prefixed message."""
+        length_bytes = await self._reader.readexactly(4)
+        msg_len = struct.unpack(">I", length_bytes)[0]
+        if msg_len == 0 or msg_len > _MAX_MESSAGE_SIZE:
+            raise ValueError(f"invalid message length: {msg_len}")
+        ciphertext = await self._reader.readexactly(msg_len)
+        nonce = self._seq_nonce(self._recv_seq)
+        self._recv_seq += 1
+        try:
+            return self._aead.decrypt(nonce, ciphertext, None)
+        except Exception as exc:
+            raise ValueError(f"decryption failed: {exc}") from exc
+
+    async def read(self, n: int) -> bytes:
+        """
+        Read exactly n bytes, decrypting new messages as needed.
+        Excess plaintext from a decrypted message is retained in an internal
+        buffer for subsequent reads, matching Go's encConn.Read() behaviour.
+        """
+        while len(self._recv_buf) < n:
+            chunk = await self.recv_msg()
+            self._recv_buf.extend(chunk)
+        data = bytes(self._recv_buf[:n])
+        del self._recv_buf[:n]
+        return data
+
+    async def write(self, data: bytes) -> None:
+        """Encrypt and send data (one encrypted message per call)."""
+        await self.send_msg(data)
+
+    def close(self) -> None:
+        """Close the underlying transport."""
+        self._writer.close()
+
+
+async def client_handshake(
+    reader: asyncio.StreamReader,
+    writer: asyncio.StreamWriter,
+    client_priv_bytes: bytes,
+    expected_server_pub_x: bytes,
+) -> EncConn:
+    """
+    Perform the Nostr mutual-auth handshake as the client side.
+
+    Args:
+        reader: asyncio StreamReader connected to the server control port.
+        writer: asyncio StreamWriter connected to the server control port.
+        client_priv_bytes: 32-byte raw secp256k1 private key.
+        expected_server_pub_x: 32-byte x-only Nostr pubkey of the server.
+
+    Returns:
+        An EncConn ready to be used as a yamux transport.
+
+    Raises:
+        HandshakeError: On pubkey mismatch, invalid signature, or server rejection.
+    """
+    # ── Step 1 receive: nonce_s + server_pub_x_only ──────────────────────────
+    data = await reader.readexactly(64)
+    nonce_s: bytes = data[:32]
+    server_pub_x_only: bytes = data[32:]
+
+    if server_pub_x_only != expected_server_pub_x:
+        raise HandshakeError(
+            f"server pubkey mismatch: got {server_pub_x_only.hex()}, "
+            f"expected {expected_server_pub_x.hex()}"
+        )
+
+    # ── Step 1 send: nonce_c + client_pub_x_only ─────────────────────────────
+    nonce_c: bytes = os.urandom(32)
+    client_priv = coincurve.PrivateKey(secret=client_priv_bytes)
+    # x-only pubkey: 32-byte x-coordinate (BIP340 even-Y key)
+    client_pub_x_only: bytes = client_priv.public_key_xonly.format()
+    writer.write(nonce_c + client_pub_x_only)
+    await writer.drain()
+
+    # ── Step 2 send: schnorr_sig(SHA256(nonce_s)) ────────────────────────────
+    nonce_s_hash = hashlib.sha256(nonce_s).digest()
+    sig_c: bytes = client_priv.sign_schnorr(nonce_s_hash)
+    writer.write(sig_c)
+    await writer.drain()
+
+    # ── Step 2 receive: server signature over nonce_c ────────────────────────
+    sig_s = await reader.readexactly(64)
+    nonce_c_hash = hashlib.sha256(nonce_c).digest()
+    server_xonly_pub = coincurve.PublicKeyXOnly(server_pub_x_only)
+    if not server_xonly_pub.verify(sig_s, nonce_c_hash):
+        raise HandshakeError("server signature verification failed")
+
+    # ── Step 3 receive: status byte ──────────────────────────────────────────
+    status = await reader.readexactly(1)
+    if status[0] != _STATUS_OK:
+        raise HandshakeError(
+            f"server rejected connection (status {status[0]:#04x})"
+        )
+
+    # ── Step 4: ECDH + HKDF → encryption key ─────────────────────────────────
+    shared_x = _ecdh_x(client_priv_bytes, server_pub_x_only)
+    key = _derive_key(shared_x, salt=nonce_s + nonce_c)
+
+    return EncConn(reader, writer, key)
+
+
+def _ecdh_x(priv_bytes: bytes, peer_pub_x_only: bytes) -> bytes:
+    """
+    Compute the x-coordinate of the ECDH shared point.
+
+    Peer's x-only key is converted to a compressed secp256k1 point using the
+    BIP340 even-Y convention (0x02 prefix) before scalar multiplication.
+
+    Equivalent to Go:
+        btcec.ScalarMultNonConst(&privKeyScalar, peerPoint, peerPoint)
+        sharedX := peerPoint.X.Bytes()
+    """
+    # BIP340 x-only → even-Y compressed point (0x02 prefix)
+    peer_compressed = b"\x02" + peer_pub_x_only
+    peer_pub = coincurve.PublicKey(peer_compressed)
+    # multiply returns a new PublicKey; extract x-coordinate from compressed form
+    shared_pub = peer_pub.multiply(priv_bytes)
+    return shared_pub.format(compressed=True)[1:]  # 32-byte x-coordinate
+
+
+def _derive_key(ikm: bytes, salt: bytes) -> bytes:
+    """
+    HKDF-SHA256 with info="personaltunnel-v1", output 32 bytes.
+
+    Equivalent to Go:
+        hkdf.New(sha256.New, sharedX, salt, []byte("personaltunnel-v1"))
+    """
+    hkdf = HKDF(
+        algorithm=SHA256(),
+        length=32,
+        salt=salt,
+        info=_HKDF_INFO,
+    )
+    return hkdf.derive(ikm)
+
+
+def generate_keypair() -> tuple[str, str]:
+    """
+    Generate a new secp256k1 keypair suitable for use with personaltunnel.
+
+    Returns:
+        (privkey_hex, pubkey_hex) where pubkey_hex is the 32-byte x-only
+        (Nostr/BIP340) public key, both hex-encoded.
+    """
+    priv = coincurve.PrivateKey()
+    priv_hex = priv.secret.hex()
+    pub_hex = priv.public_key_xonly.format().hex()
+    return priv_hex, pub_hex