steerable-egress-proxy 0.3.0__py3-none-any.whl

steerable_egress_proxy/__init__.py

@@ -0,0 +1,20 @@
+"""steerable-egress-proxy — local allow-listing CONNECT egress proxy.
+
+Optional component. See docs/spec/safety.md "Egress allow-list": OS
+sandboxes degrade to port-level (Seatbelt) or namespace-level (bwrap)
+egress; per-host enforcement needs a local proxy that owns the host list.
+"""
+
+from .proxy import (
+    AllowList,
+    EgressProxyServer,
+    ProxyConfig,
+    parse_allow_entry,
+)
+
+__all__ = [
+    "AllowList",
+    "EgressProxyServer",
+    "ProxyConfig",
+    "parse_allow_entry",
+]

steerable_egress_proxy/__main__.py

@@ -0,0 +1,75 @@
+"""CLI: `steerable-egress-proxy --bind 127.0.0.1:8899 --allow api.deepseek.com ...`
+
+Misconfiguration fails loud at startup: no `--allow` entries (or a
+malformed one) exits non-zero before the socket opens — a proxy with an
+unintended list is worse than no proxy.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+
+from .proxy import AllowList, EgressProxyServer, ProxyConfig
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="steerable-egress-proxy",
+        description="Local allow-listing CONNECT egress proxy (v1: no TLS interception).",
+    )
+    parser.add_argument(
+        "--bind",
+        default="127.0.0.1:8899",
+        help="listen address (default 127.0.0.1:8899)",
+    )
+    parser.add_argument(
+        "--allow",
+        action="append",
+        default=[],
+        metavar="HOST[:PORT]",
+        help="allowed CONNECT target; repeatable. Bare host allows 443 and 80.",
+    )
+    parser.add_argument(
+        "--connect-timeout",
+        type=float,
+        default=10.0,
+        help="upstream dial timeout in seconds (default 10)",
+    )
+    args = parser.parse_args(argv)
+
+    bind_host, sep, bind_port_s = args.bind.rpartition(":")
+    if not sep or not bind_host:
+        print(f"error: --bind must be host:port, got {args.bind!r}", file=sys.stderr)
+        return 2
+    try:
+        bind_port = int(bind_port_s)
+        allow = AllowList(args.allow)
+        config = ProxyConfig(
+            allow=allow,
+            bind_host=bind_host,
+            bind_port=bind_port,
+            connect_timeout_s=args.connect_timeout,
+        )
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    server = EgressProxyServer(config)
+
+    async def run() -> None:
+        try:
+            await server.serve()
+        except asyncio.CancelledError:
+            await server.close()
+
+    try:
+        asyncio.run(run())
+    except KeyboardInterrupt:
+        pass
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

steerable_egress_proxy/proxy.py

@@ -0,0 +1,256 @@
+"""Allow-listing CONNECT forward proxy (v1: HTTPS tunneling only).
+
+The proxy accepts only ``CONNECT host:port`` requests, checks the target
+against an explicit allow-list, dials, and pipes bytes bidirectionally.
+Everything else fails closed:
+
+- target not on the list            → 403
+- non-CONNECT method                → 405 (no plain-HTTP forwarding in v1)
+- malformed request line / headers  → 400
+- unreachable target                → 502
+
+TLS is NOT intercepted: the proxy sees the CONNECT target only, which is
+exactly the metadata the host allow-list needs. v1 scope per PARITY_TODO
+0.4.2 — no TLS interception, no plain-HTTP forwarding.
+
+Bounds that keep the security boundary tight:
+
+- request head capped at ``MAX_HEAD_BYTES`` (16 KiB) → 431 over cap
+- CONNECT dial bounded by ``connect_timeout_s``
+- an empty allow-list is a configuration error, not "open" — constructing
+  ``AllowList([])`` raises ``ValueError`` (fail loud, never silently open)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+MAX_HEAD_BYTES = 16 * 1024
+_DEFAULT_CONNECT_TIMEOUT_S = 10.0
+#: Ports implied by a bare `host` allow entry — mirrors the Seatbelt
+#: profile semantics in docs/spec/safety.md so the two layers agree.
+_BARE_HOST_PORTS = frozenset({443, 80})
+
+_ENTRY_RE = re.compile(
+    r"^(?P<host>[A-Za-z0-9._-]+|\[[0-9a-fA-F:]+\])(?::(?P<port>\d{1,5}))?$"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class AllowEntry:
+    host: str
+    ports: frozenset[int]  # empty frozenset is never stored; see parse
+
+    def allows(self, host: str, port: int) -> bool:
+        return self.host == host.lower() and port in self.ports
+
+
+def parse_allow_entry(raw: str) -> AllowEntry:
+    """Parse one `host` or `host:port` entry. Bare hosts allow 443 and 80.
+
+    Raises ValueError on anything malformed — a bad entry must never
+    silently widen or narrow the list.
+    """
+    text = raw.strip()
+    m = _ENTRY_RE.match(text)
+    if not m:
+        raise ValueError(f"invalid allow entry {raw!r}: expected host or host:port")
+    host = m.group("host").lower()
+    if host.startswith("[") and host.endswith("]"):
+        host = host[1:-1]
+    port_s = m.group("port")
+    if port_s is None:
+        return AllowEntry(host, frozenset(_BARE_HOST_PORTS))
+    port = int(port_s)
+    if not 1 <= port <= 65535:
+        raise ValueError(f"invalid allow entry {raw!r}: port out of range")
+    return AllowEntry(host, frozenset({port}))
+
+
+class AllowList:
+    """Closed set of allowed CONNECT targets. Empty input is an error."""
+
+    def __init__(self, entries: list[str]):
+        if not entries:
+            raise ValueError(
+                "allow-list is empty: an egress proxy with no entries is "
+                "either a mistake or should not be run at all"
+            )
+        self._entries = tuple(parse_allow_entry(e) for e in entries)
+
+    @property
+    def entries(self) -> tuple[AllowEntry, ...]:
+        return self._entries
+
+    def allows(self, host: str, port: int) -> bool:
+        host = host.lower()
+        return any(e.allows(host, port) for e in self._entries)
+
+
+@dataclass(frozen=True, slots=True)
+class ProxyConfig:
+    allow: AllowList  # required — fail-closed by construction
+    bind_host: str = "127.0.0.1"
+    bind_port: int = 8899
+    connect_timeout_s: float = _DEFAULT_CONNECT_TIMEOUT_S
+
+    def __post_init__(self) -> None:
+        if self.allow is None:
+            raise ValueError("ProxyConfig.allow is required (fail-closed)")
+        # 0 is valid: ephemeral bind (tests, supervised spawns that read the
+        # port back from `bound_port`).
+        if not 0 <= self.bind_port <= 65535:
+            raise ValueError(f"bind_port out of range: {self.bind_port}")
+
+
+class EgressProxyServer:
+    """Asyncio CONNECT proxy. `await serve()` runs until cancelled."""
+
+    def __init__(self, config: ProxyConfig):
+        self.config = config
+        self._server: asyncio.AbstractServer | None = None
+
+    @property
+    def bound_port(self) -> int:
+        if self._server and self._server.sockets:
+            return int(self._server.sockets[0].getsockname()[1])
+        return self.config.bind_port
+
+    async def serve(self) -> None:
+        self._server = await asyncio.start_server(
+            self._handle,
+            self.config.bind_host,
+            self.config.bind_port,
+        )
+        logger.info(
+            "egress proxy on %s:%s (%d allow entries)",
+            self.config.bind_host,
+            self.bound_port,
+            len(self.config.allow.entries),
+        )
+        async with self._server:
+            await self._server.serve_forever()
+
+    async def close(self) -> None:
+        if self._server:
+            self._server.close()
+            await self._server.wait_closed()
+            self._server = None
+
+    # ---- connection handling -------------------------------------------
+
+    async def _handle(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        try:
+            head = await self._read_head(reader)
+            if head is None:
+                await self._reply(writer, 431, "Request Header Fields Too Large")
+                return
+            parsed = self._parse_request_line(head)
+            if parsed is None:
+                await self._reply(writer, 400, "Bad Request")
+                return
+            method, host, port = parsed
+            if method != "CONNECT":
+                # Checked before authority validity: a GET with a weird
+                # target is still a 405, not a 400.
+                await self._reply(writer, 405, "Method Not Allowed")
+                return
+            if host is None or port is None:
+                await self._reply(writer, 400, "Bad Request")
+                return
+            if not self.config.allow.allows(host, port):
+                logger.info("deny %s:%d (not on allow-list)", host, port)
+                await self._reply(writer, 403, "Forbidden")
+                return
+            try:
+                upstream_r, upstream_w = await asyncio.wait_for(
+                    asyncio.open_connection(host, port),
+                    timeout=self.config.connect_timeout_s,
+                )
+            except (OSError, asyncio.TimeoutError):
+                await self._reply(writer, 502, "Bad Gateway")
+                return
+            await self._reply(writer, 200, "Connection Established")
+            await self._tunnel(reader, writer, upstream_r, upstream_w)
+        except (ConnectionResetError, BrokenPipeError, asyncio.IncompleteReadError):
+            pass  # client or upstream hung up mid-stream — normal teardown
+        finally:
+            try:
+                writer.close()
+                await writer.wait_closed()
+            except OSError:
+                pass  # peer already gone
+
+    async def _read_head(self, reader: asyncio.StreamReader) -> bytes | None:
+        """Read up to the blank line ending the request head; None = over cap."""
+        data = b""
+        while b"\r\n\r\n" not in data:
+            chunk = await reader.read(min(4096, MAX_HEAD_BYTES - len(data) + 4))
+            if not chunk:
+                return data if data else b""
+            data += chunk
+            if len(data) > MAX_HEAD_BYTES:
+                return None
+        return data
+
+    @staticmethod
+    def _parse_request_line(head: bytes) -> tuple[str, str | None, int | None] | None:
+        """Split the request line. `(method, None, None)` means the method is
+        fine but the authority is not a CONNECT target — caller maps that to
+        405-before-400 ordering."""
+        try:
+            first = head.split(b"\r\n", 1)[0].decode("ascii")
+        except UnicodeDecodeError:
+            return None
+        parts = first.split(" ")
+        if len(parts) != 3 or not parts[2].startswith("HTTP/"):
+            return None
+        method, authority = parts[0].upper(), parts[1]
+        if ":" not in authority:
+            return (method, None, None)
+        host, _, port_s = authority.rpartition(":")
+        try:
+            port = int(port_s)
+        except ValueError:
+            return (method, None, None)
+        if not host or not 1 <= port <= 65535:
+            return (method, None, None)
+        return method, host.lower(), port
+
+    @staticmethod
+    async def _reply(writer: asyncio.StreamWriter, code: int, reason: str) -> None:
+        writer.write(f"HTTP/1.1 {code} {reason}\r\ncontent-length: 0\r\n\r\n".encode())
+        await writer.drain()
+
+    async def _tunnel(
+        self,
+        client_r: asyncio.StreamReader,
+        client_w: asyncio.StreamWriter,
+        upstream_r: asyncio.StreamReader,
+        upstream_w: asyncio.StreamWriter,
+    ) -> None:
+        async def pipe(src: asyncio.StreamReader, dst: asyncio.StreamWriter) -> None:
+            while True:
+                chunk = await src.read(64 * 1024)
+                if not chunk:
+                    break
+                dst.write(chunk)
+                await dst.drain()
+            if dst.can_write_eof():
+                dst.write_eof()
+
+        up = asyncio.create_task(pipe(client_r, upstream_w))
+        down = asyncio.create_task(pipe(upstream_r, client_w))
+        try:
+            await asyncio.wait({up, down}, return_when=asyncio.FIRST_COMPLETED)
+        finally:
+            for t in (up, down):
+                t.cancel()
+            upstream_w.close()

steerable_egress_proxy-0.3.0.dist-info/METADATA

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: steerable-egress-proxy
+Version: 0.3.0
+Summary: Steerable optional component — local allow-listing CONNECT egress proxy. Gives per-host egress control on platforms whose sandbox can only pin ports (Seatbelt) or only drop the network namespace (bwrap): confine the sidecar to localhost:<proxy> and let the proxy own the host list.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# steerable-egress-proxy
+
+Optional Steerable component: a local, allow-listing `CONNECT` egress proxy.
+
+## Why it exists
+
+The sidecar's OS sandboxes cannot do per-host egress on their own:
+macOS Seatbelt degrades hostnames to ports (`*:443`), and Linux bwrap can
+only drop the whole network namespace. The remedy on both is the same —
+confine the sidecar to `localhost:<proxy port>` and let this proxy own the
+host list. See `docs/spec/safety.md` ("Egress allow-list") for the full
+threat model.
+
+## Usage
+
+```sh
+steerable-egress-proxy --bind 127.0.0.1:8899 \
+    --allow api.deepseek.com \
+    --allow localhost:11434
+```
+
+- Only `CONNECT host:port` is served (HTTPS tunneling). Plain-HTTP
+  forwarding and TLS interception are deliberately out of v1 scope.
+- Bare `host` entries allow ports 443 and 80, mirroring the Seatbelt
+  profile semantics so the two layers agree.
+- Fail-closed by construction: an empty allow-list is a startup error,
+  not "open"; targets off the list get `403`; non-CONNECT gets `405`.
+- Request heads are capped at 16 KiB; upstream dials time out after 10s.
+
+Wire-up with the sandbox: set the sidecar's egress allow-list to
+`localhost:8899` only, and point the sidecar's HTTP stack at the proxy
+(`HTTPS_PROXY=http://127.0.0.1:8899` — httpx honors it). The sandbox then
+pins the process to the proxy and the proxy enforces the host list.

steerable_egress_proxy-0.3.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+steerable_egress_proxy/__init__.py,sha256=cWEeWjO9VxS2ar8PsbiAUhs7E-fpeZ3Rz72A91U5M64,492
+steerable_egress_proxy/__main__.py,sha256=gMwqOQ7XPLnnUMR9MOkg0qFUiEu3ztuE06QbA91oTCI,2070
+steerable_egress_proxy/proxy.py,sha256=IW0WMbjOBztqQZui1MqJO1GxExkLvsNGgaE4sjAclKo,9469
+steerable_egress_proxy-0.3.0.dist-info/METADATA,sha256=uE-hp5-PrD7ZSBPxc9h07mVoa5e2JohAr10R8iL2S0A,1794
+steerable_egress_proxy-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+steerable_egress_proxy-0.3.0.dist-info/entry_points.txt,sha256=HVK6cSmCj9sZx8uhlO6GiMnq1VcQ4wwd2qZr4Eu6ceE,80
+steerable_egress_proxy-0.3.0.dist-info/top_level.txt,sha256=_MpXoKraWMC_SI5PcvoptFodbc5gXXRYzhqcxqiF7c8,23
+steerable_egress_proxy-0.3.0.dist-info/RECORD,,

steerable_egress_proxy-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

steerable_egress_proxy-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+steerable-egress-proxy = steerable_egress_proxy.__main__:main

steerable_egress_proxy-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+steerable_egress_proxy