personaltunnel-python-client 0.1.0__py3-none-any.whl

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_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_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

personaltunnel_client/forward.py

@@ -0,0 +1,183 @@
+"""
+Per-stream HTTP request forwarding.
+
+Each yamux stream carries one HTTP/1.1 request from the public internet
+(already read and parsed by the Go server's proxy.go). This module reads
+the request from the stream, forwards it to the local service, and writes
+the HTTP/1.1 response back into the stream.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+import httpx
+
+if TYPE_CHECKING:
+    from .yamux import YamuxStream
+
+logger = logging.getLogger(__name__)
+
+# Headers that must not be forwarded to the local service (hop-by-hop).
+_HOP_BY_HOP = frozenset(
+    {
+        "connection",
+        "keep-alive",
+        "proxy-authenticate",
+        "proxy-authorization",
+        "proxy-connection",
+        "te",
+        "trailers",
+        "transfer-encoding",
+        "upgrade",
+    }
+)
+
+
+async def handle_stream(stream: "YamuxStream", local_addr: str) -> None:
+    """
+    Read one HTTP request from *stream*, forward it to *local_addr*, and write
+    the HTTP/1.1 response back. Always closes the stream when finished.
+
+    Args:
+        stream:     An open YamuxStream received from YamuxSession.accept().
+        local_addr: Host:port of the local service (e.g. "localhost:8000").
+    """
+    try:
+        method, path, req_headers, body = await _read_http_request(stream)
+
+        fwd_headers = {
+            k: v
+            for k, v in req_headers.items()
+            if k.lower() not in _HOP_BY_HOP
+        }
+
+        async with httpx.AsyncClient() as http:
+            resp = await http.request(
+                method,
+                f"http://{local_addr}{path}",
+                headers=fwd_headers,
+                content=body,
+                follow_redirects=False,
+            )
+
+        await _write_http_response(stream, resp)
+        logger.debug(
+            "forward: %s %s → %d (%d bytes)",
+            method,
+            path,
+            resp.status_code,
+            len(resp.content),
+        )
+
+    except (httpx.ConnectError, httpx.TimeoutException, OSError) as exc:
+        logger.warning("forward: local service unreachable at %s: %r", local_addr, exc)
+        await _write_error(stream, 502, "local service unreachable")
+
+    except EOFError as exc:
+        logger.debug("forward: stream closed before request complete: %r", exc)
+
+    except Exception as exc:
+        logger.debug("forward: unexpected error: %r", exc)
+
+    finally:
+        await stream.close()
+
+
+async def _read_http_request(
+    stream: "YamuxStream",
+) -> tuple[str, str, dict[str, str], bytes]:
+    """
+    Read a full HTTP/1.1 request from *stream*.
+
+    Returns (method, path, headers_dict, body_bytes).
+    Raises EOFError if the stream closes before the request is complete.
+    """
+    # Read headers section (up to and including the blank line).
+    buf = bytearray()
+    while True:
+        chunk = await stream.read(4096)
+        if not chunk:
+            raise EOFError("stream closed before HTTP headers complete")
+        buf.extend(chunk)
+        if b"\r\n\r\n" in buf:
+            break
+
+    split_pos = buf.index(b"\r\n\r\n")
+    header_bytes = bytes(buf[:split_pos])
+    leftover = bytes(buf[split_pos + 4 :])
+
+    # Parse request line and headers.
+    lines = header_bytes.split(b"\r\n")
+    if not lines:
+        raise ValueError("empty HTTP request")
+
+    request_line = lines[0].decode("latin-1")
+    parts = request_line.split(" ", 2)
+    if len(parts) < 2:
+        raise ValueError(f"malformed request line: {request_line!r}")
+    method = parts[0]
+    path = parts[1]
+
+    headers: dict[str, str] = {}
+    for line in lines[1:]:
+        if b":" in line:
+            name, _, value = line.partition(b":")
+            headers[name.decode("latin-1").strip()] = value.decode("latin-1").strip()
+
+    # Read body.
+    content_length = int(
+        headers.get("Content-Length", headers.get("content-length", "0"))
+    )
+    body = bytearray(leftover[:content_length])
+
+    while len(body) < content_length:
+        remaining = content_length - len(body)
+        chunk = await stream.read(min(remaining, 65536))
+        if not chunk:
+            break
+        body.extend(chunk)
+
+    return method, path, headers, bytes(body)
+
+
+async def _write_http_response(
+    stream: "YamuxStream", resp: httpx.Response
+) -> None:
+    """Serialise *resp* as HTTP/1.1 and write it into *stream*."""
+    reason = resp.reason_phrase or ""
+    lines = [f"HTTP/1.1 {resp.status_code} {reason}"]
+
+    response_headers: dict[str, str] = {}
+    for k, v in resp.headers.items():
+        if k.lower() not in _HOP_BY_HOP:
+            response_headers[k.lower()] = v
+
+    # Always set Content-Length from the actual body we received.
+    response_headers["content-length"] = str(len(resp.content))
+    response_headers["connection"] = "close"
+
+    for k, v in response_headers.items():
+        lines.append(f"{k}: {v}")
+
+    header_section = "\r\n".join(lines) + "\r\n\r\n"
+    await stream.write(header_section.encode("latin-1") + resp.content)
+
+
+async def _write_error(stream: "YamuxStream", code: int, message: str) -> None:
+    """Write a minimal HTTP error response into *stream*."""
+    body = (message + "\n").encode()
+    reasons = {502: "Bad Gateway", 503: "Service Unavailable"}
+    reason = reasons.get(code, "Error")
+    response = (
+        f"HTTP/1.1 {code} {reason}\r\n"
+        f"Content-Type: text/plain\r\n"
+        f"Content-Length: {len(body)}\r\n"
+        f"Connection: close\r\n"
+        f"\r\n"
+    ).encode() + body
+    try:
+        await stream.write(response)
+    except Exception:
+        pass

personaltunnel_client/yamux.py

@@ -0,0 +1,319 @@
+"""
+Minimal asyncio implementation of the hashicorp/yamux client protocol.
+
+The Python library always plays the yamux *Client* role (even stream IDs).
+The Go personaltunnel server plays the yamux *Server* role and opens streams
+(odd stream IDs) — one per incoming public HTTP request.
+
+Frame header (12 bytes, big-endian):
+    version   (1 byte):  always 0
+    type      (1 byte):  0=Data, 1=WindowUpdate, 2=Ping, 3=GoAway
+    flags     (2 bytes): SYN=0x0001, ACK=0x0002, FIN=0x0004, RST=0x0008
+    stream_id (4 bytes)
+    length    (4 bytes): payload bytes (Data) or window delta (WindowUpdate)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import struct
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .crypto import EncConn
+
+logger = logging.getLogger(__name__)
+
+# Frame types
+_TYPE_DATA = 0
+_TYPE_WINDOW_UPDATE = 1
+_TYPE_PING = 2
+_TYPE_GO_AWAY = 3
+
+# Frame flags
+_FLAG_SYN = 0x0001
+_FLAG_ACK = 0x0002
+_FLAG_FIN = 0x0004
+_FLAG_RST = 0x0008
+
+# hashicorp/yamux default initial receive window
+_INITIAL_WINDOW = 256 * 1024  # 262144 bytes
+
+_HEADER_FMT = ">BBHII"  # version, type, flags, stream_id, length
+_HEADER_SIZE = 12
+
+
+def _pack_header(type_: int, flags: int, stream_id: int, length: int) -> bytes:
+    return struct.pack(_HEADER_FMT, 0, type_, flags, stream_id, length)
+
+
+class YamuxStream:
+    """
+    A single bidirectional yamux stream.
+
+    Callers use read() / write() / close() as with any async byte stream.
+    Created internally by YamuxSession when the server opens a new stream.
+    """
+
+    def __init__(self, stream_id: int, session: "YamuxSession") -> None:
+        self._stream_id = stream_id
+        self._session = session
+
+        self._recv_buf = bytearray()
+        self._data_event = asyncio.Event()
+
+        # Flow control: how much data the server is allowed to send us.
+        # The reader sends WindowUpdate frames to restore the server's quota.
+        self._send_window: int = _INITIAL_WINDOW
+        self._window_event = asyncio.Event()
+
+        self._eof = False       # server sent FIN
+        self._rst = False       # stream was reset
+        self._write_closed = False  # we sent FIN
+
+    # ── Internal helpers called by YamuxSession._read_loop ──────────────────
+
+    def _feed(self, data: bytes, fin: bool) -> None:
+        """Append incoming data and/or mark EOF."""
+        if data:
+            self._recv_buf.extend(data)
+        if fin:
+            self._eof = True
+        self._data_event.set()
+
+    def _reset(self) -> None:
+        """Mark the stream as reset by the remote peer."""
+        self._rst = True
+        self._eof = True
+        self._data_event.set()
+        self._window_event.set()
+
+    def _add_send_window(self, delta: int) -> None:
+        """Increase the send window and unblock any waiting write()."""
+        self._send_window += delta
+        if self._send_window > 0:
+            self._window_event.set()
+
+    # ── Public async API ────────────────────────────────────────────────────
+
+    async def read(self, n: int) -> bytes:
+        """
+        Read up to n bytes from the stream.
+        Blocks until data is available or the stream is closed (returns b'').
+        """
+        while not self._recv_buf and not self._eof and not self._rst:
+            self._data_event.clear()
+            # Re-check after clearing to avoid a TOCTOU gap.
+            if self._recv_buf or self._eof or self._rst:
+                break
+            await self._data_event.wait()
+
+        if self._rst and not self._recv_buf:
+            raise ConnectionResetError("yamux stream was reset")
+
+        if not self._recv_buf:
+            return b""  # EOF
+
+        data = bytes(self._recv_buf[:n])
+        consumed = len(data)
+        del self._recv_buf[:consumed]
+
+        # Restore the server's send quota so it can keep sending.
+        if consumed > 0:
+            await self._session._send_frame(
+                _TYPE_WINDOW_UPDATE, 0, self._stream_id, consumed
+            )
+
+        return data
+
+    async def write(self, data: bytes) -> None:
+        """
+        Write data to the stream.
+        Blocks when the remote receive window is exhausted (flow control).
+        """
+        if self._write_closed:
+            raise ConnectionError("write on closed yamux stream")
+
+        offset = 0
+        while offset < len(data):
+            # Wait for window space.
+            while self._send_window <= 0 and not self._rst:
+                self._window_event.clear()
+                if self._send_window > 0 or self._rst:
+                    break
+                await self._window_event.wait()
+
+            if self._rst:
+                raise ConnectionResetError("yamux stream was reset")
+
+            chunk_size = min(len(data) - offset, self._send_window)
+            chunk = data[offset : offset + chunk_size]
+            self._send_window -= chunk_size
+
+            await self._session._send_frame(
+                _TYPE_DATA, 0, self._stream_id, len(chunk), chunk
+            )
+            offset += chunk_size
+
+    async def close(self) -> None:
+        """Send FIN to signal end-of-write; does not prevent further reads."""
+        if not self._write_closed and not self._rst:
+            self._write_closed = True
+            await self._session._send_frame(
+                _TYPE_DATA, _FLAG_FIN, self._stream_id, 0
+            )
+        self._session._remove_stream(self._stream_id)
+
+
+class YamuxSession:
+    """
+    Async yamux client session.
+
+    After calling start(), the session accepts streams opened by the remote
+    yamux server (the Go personaltunnel server). Each accepted YamuxStream
+    carries exactly one HTTP request/response pair.
+
+    Usage::
+
+        session = YamuxSession(enc_conn)
+        await session.start()
+
+        while not session.closed:
+            stream = await session.accept()
+            if stream is None:
+                break
+            asyncio.create_task(handle_stream(stream))
+    """
+
+    def __init__(self, enc_conn: "EncConn") -> None:
+        self._enc_conn = enc_conn
+        self._streams: dict[int, YamuxStream] = {}
+        self._accept_queue: asyncio.Queue[YamuxStream | None] = asyncio.Queue()
+        self._send_lock = asyncio.Lock()
+        self._reader_task: asyncio.Task | None = None
+        self._closed = False
+
+    async def start(self) -> None:
+        """Launch the background frame-reader task."""
+        self._reader_task = asyncio.create_task(
+            self._read_loop(), name="yamux-reader"
+        )
+
+    async def accept(self) -> YamuxStream | None:
+        """
+        Wait for the server to open a new stream.
+        Returns None when the session has been closed.
+        """
+        return await self._accept_queue.get()
+
+    async def close(self) -> None:
+        """Close the session and its underlying connection."""
+        if not self._closed:
+            self._closed = True
+            if self._reader_task:
+                self._reader_task.cancel()
+            self._enc_conn.close()
+            await self._accept_queue.put(None)
+
+    @property
+    def closed(self) -> bool:
+        return self._closed
+
+    # ── Internal ──────────────────────────────────────────────────────────
+
+    async def _send_frame(
+        self,
+        type_: int,
+        flags: int,
+        stream_id: int,
+        length: int,
+        data: bytes = b"",
+    ) -> None:
+        """Serialise and send a yamux frame atomically."""
+        async with self._send_lock:
+            header = _pack_header(type_, flags, stream_id, length)
+            await self._enc_conn.write(header + data)
+
+    def _remove_stream(self, stream_id: int) -> None:
+        self._streams.pop(stream_id, None)
+
+    async def _read_loop(self) -> None:
+        """Background task: read yamux frames and dispatch to streams."""
+        try:
+            while not self._closed:
+                header = await self._enc_conn.read(_HEADER_SIZE)
+                _version, type_, flags, stream_id, length = struct.unpack(
+                    _HEADER_FMT, header
+                )
+
+                if type_ == _TYPE_DATA:
+                    await self._handle_data(stream_id, flags, length)
+                elif type_ == _TYPE_WINDOW_UPDATE:
+                    self._handle_window_update(stream_id, flags, length)
+                elif type_ == _TYPE_PING:
+                    await self._handle_ping(flags, length)
+                elif type_ == _TYPE_GO_AWAY:
+                    logger.info("yamux: received GoAway (code=%d)", length)
+                    break
+                else:
+                    logger.warning("yamux: unknown frame type %d, ignoring", type_)
+
+        except asyncio.CancelledError:
+            pass
+        except Exception as exc:
+            if not self._closed:
+                logger.debug("yamux: reader error: %r", exc)
+        finally:
+            self._closed = True
+            for stream in list(self._streams.values()):
+                stream._reset()
+            self._streams.clear()
+            await self._accept_queue.put(None)
+
+    async def _handle_data(self, stream_id: int, flags: int, length: int) -> None:
+        body = b""
+        if length > 0:
+            body = await self._enc_conn.read(length)
+
+        syn = bool(flags & _FLAG_SYN)
+        fin = bool(flags & _FLAG_FIN)
+        rst = bool(flags & _FLAG_RST)
+
+        if rst:
+            stream = self._streams.pop(stream_id, None)
+            if stream:
+                stream._reset()
+            return
+
+        if syn:
+            # Server is opening a new stream.
+            stream = YamuxStream(stream_id, self)
+            self._streams[stream_id] = stream
+            # Acknowledge with WindowUpdate + ACK and grant our receive window.
+            await self._send_frame(
+                _TYPE_WINDOW_UPDATE, _FLAG_ACK, stream_id, _INITIAL_WINDOW
+            )
+            if body or fin:
+                stream._feed(body, fin)
+            await self._accept_queue.put(stream)
+            return
+
+        stream = self._streams.get(stream_id)
+        if stream is None:
+            logger.debug(
+                "yamux: data for unknown stream %d (len=%d)", stream_id, length
+            )
+            return
+
+        stream._feed(body, fin)
+
+    def _handle_window_update(self, stream_id: int, flags: int, delta: int) -> None:
+        stream = self._streams.get(stream_id)
+        if stream is None:
+            return
+        stream._add_send_window(delta)
+
+    async def _handle_ping(self, flags: int, value: int) -> None:
+        if flags & _FLAG_SYN:
+            await self._send_frame(_TYPE_PING, _FLAG_ACK, 0, value)

personaltunnel_python_client-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+personaltunnel_client/__init__.py,sha256=izDLa5Mq6Nc_xvPZd1M3SwHRWEneHtsuddERwQncwEk,896
+personaltunnel_client/client.py,sha256=vE1wHZzxPLdjeNaSYbz2RJkwl_WmM2SmZWcKQgms85k,8659
+personaltunnel_client/crypto.py,sha256=O1Mgm4jTiiMQwM8zGkBM0p4mjBnL_H5d4_0w5vaNumA,8690
+personaltunnel_client/forward.py,sha256=Rw6KU_ly_vImweoK-EC_sF_KvRULOChTGppL_7mCZQw,5558
+personaltunnel_client/yamux.py,sha256=wG5E4gqMJIcvhLlcvrxju70HWPYdqAKKfhEEpmjhTFo,10859
+personaltunnel_python_client-0.1.0.dist-info/METADATA,sha256=c9cnmQv3RRtEsDuF0_fcq56SUxZiEpO-zMUePuusY8s,289
+personaltunnel_python_client-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+personaltunnel_python_client-0.1.0.dist-info/RECORD,,

personaltunnel_python_client-0.1.0.dist-info/WHEEL

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