steerable-egress-proxy 0.3.0__tar.gz

steerable_egress_proxy-0.3.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,33 @@
+# 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/pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "steerable-egress-proxy"
+version = "0.3.0"
+description = "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."
+readme = "README.md"
+requires-python = ">=3.10"
+# Zero runtime dependencies by design: the proxy sits on the security
+# boundary, so its supply chain must stay auditable. asyncio streams only.
+dependencies = []
+
+[project.scripts]
+steerable-egress-proxy = "steerable_egress_proxy.__main__:main"
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.uv.sources]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

steerable_egress_proxy-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

steerable_egress_proxy-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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/src/steerable_egress_proxy.egg-info/PKG-INFO

@@ -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/src/steerable_egress_proxy.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/steerable_egress_proxy/__init__.py
+src/steerable_egress_proxy/__main__.py
+src/steerable_egress_proxy/proxy.py
+src/steerable_egress_proxy.egg-info/PKG-INFO
+src/steerable_egress_proxy.egg-info/SOURCES.txt
+src/steerable_egress_proxy.egg-info/dependency_links.txt
+src/steerable_egress_proxy.egg-info/entry_points.txt
+src/steerable_egress_proxy.egg-info/top_level.txt
+tests/test_proxy.py

steerable_egress_proxy-0.3.0/src/steerable_egress_proxy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

steerable_egress_proxy-0.3.0/src/steerable_egress_proxy.egg-info/entry_points.txt

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

steerable_egress_proxy-0.3.0/src/steerable_egress_proxy.egg-info/top_level.txt

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

steerable_egress_proxy-0.3.0/tests/test_proxy.py

@@ -0,0 +1,218 @@
+"""Tests for the allow-listing CONNECT egress proxy.
+
+Tunnel tests use a real loopback echo server as the CONNECT target — the
+proxy's job is byte plumbing plus the allow-list gate, and both are only
+honestly tested over real sockets.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+from steerable_egress_proxy import (
+    AllowList,
+    EgressProxyServer,
+    ProxyConfig,
+    parse_allow_entry,
+)
+from steerable_egress_proxy.__main__ import main as cli_main
+
+
+async def _start_echo() -> tuple[asyncio.AbstractServer, int]:
+    async def echo(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        while True:
+            data = await reader.read(4096)
+            if not data:
+                break
+            writer.write(data)
+            await writer.drain()
+        writer.close()
+
+    server = await asyncio.start_server(echo, "127.0.0.1", 0)
+    port = int(server.sockets[0].getsockname()[1])
+    return server, port
+
+
+async def _start_proxy(allow: list[str]) -> tuple[EgressProxyServer, asyncio.Task, int]:
+    server = EgressProxyServer(
+        ProxyConfig(allow=AllowList(allow), bind_host="127.0.0.1", bind_port=0)
+    )
+    task = asyncio.create_task(server.serve())
+    # Let serve() bind before we read the port.
+    for _ in range(100):
+        if server._server is not None:
+            break
+        await asyncio.sleep(0.01)
+    return server, task, server.bound_port
+
+
+async def _connect(
+    proxy_port: int, authority: str
+) -> tuple[bytes, asyncio.StreamReader, asyncio.StreamWriter]:
+    reader, writer = await asyncio.open_connection("127.0.0.1", proxy_port)
+    writer.write(f"CONNECT {authority} HTTP/1.1\r\nhost: {authority}\r\n\r\n".encode())
+    await writer.drain()
+    head = await reader.readuntil(b"\r\n\r\n")
+    return head, reader, writer
+
+
+async def _raw_request(proxy_port: int, payload: bytes) -> bytes:
+    reader, writer = await asyncio.open_connection("127.0.0.1", proxy_port)
+    writer.write(payload)
+    await writer.drain()
+    head = await reader.readuntil(b"\r\n\r\n")
+    writer.close()
+    return head
+
+
+# ---- allow-list parsing ---------------------------------------------------
+
+
+def test_bare_host_allows_443_and_80():
+    entry = parse_allow_entry("api.deepseek.com")
+    assert entry.allows("api.deepseek.com", 443)
+    assert entry.allows("api.deepseek.com", 80)
+    assert not entry.allows("api.deepseek.com", 22)
+
+
+def test_host_port_entry_is_exact():
+    entry = parse_allow_entry("localhost:11434")
+    assert entry.allows("localhost", 11434)
+    assert not entry.allows("localhost", 443)
+
+
+def test_entry_matching_is_case_insensitive():
+    entry = parse_allow_entry("API.Example.COM:8443")
+    assert entry.allows("api.example.com", 8443)
+
+
+@pytest.mark.parametrize(
+    "raw",
+    ["", ":", "host:", "host:0", "host:65536", "host:abc", "bad host:443", "h:o:s:t"],
+)
+def test_malformed_entries_raise(raw):
+    with pytest.raises(ValueError):
+        parse_allow_entry(raw)
+
+
+def test_empty_allow_list_fails_loud():
+    with pytest.raises(ValueError, match="empty"):
+        AllowList([])
+
+
+def test_proxy_config_requires_allow_list():
+    # No default: constructing without `allow` is a type error; a None
+    # smuggled past the type checker still fails loud.
+    with pytest.raises((TypeError, ValueError)):
+        ProxyConfig(allow=None)  # type: ignore[arg-type]
+
+
+# ---- live tunneling -------------------------------------------------------
+
+
+async def test_allowed_connect_tunnels_bytes_both_ways():
+    echo, echo_port = await _start_echo()
+    proxy, task, proxy_port = await _start_proxy([f"127.0.0.1:{echo_port}"])
+    try:
+        head, reader, writer = await _connect(proxy_port, f"127.0.0.1:{echo_port}")
+        assert head.startswith(b"HTTP/1.1 200")
+        writer.write(b"ping-through-proxy\n")
+        await writer.drain()
+        assert await reader.readline() == b"ping-through-proxy\n"
+        writer.close()
+    finally:
+        await proxy.close()
+        task.cancel()
+        echo.close()
+
+
+async def test_denied_host_gets_403_and_no_dial():
+    proxy, task, proxy_port = await _start_proxy(["127.0.0.1:1"])
+    try:
+        head = await _raw_request(proxy_port, b"CONNECT 10.9.8.7:443 HTTP/1.1\r\n\r\n")
+        assert head.startswith(b"HTTP/1.1 403")
+    finally:
+        await proxy.close()
+        task.cancel()
+
+
+async def test_denied_port_gets_403():
+    echo, echo_port = await _start_echo()
+    proxy, task, proxy_port = await _start_proxy(["127.0.0.1:1"])
+    try:
+        head = await _raw_request(
+            proxy_port, f"CONNECT 127.0.0.1:{echo_port} HTTP/1.1\r\n\r\n".encode()
+        )
+        assert head.startswith(b"HTTP/1.1 403")
+    finally:
+        await proxy.close()
+        task.cancel()
+        echo.close()
+
+
+async def test_non_connect_method_gets_405():
+    proxy, task, proxy_port = await _start_proxy(["127.0.0.1:80"])
+    try:
+        head = await _raw_request(
+            proxy_port, b"GET http://example.com/ HTTP/1.1\r\n\r\n"
+        )
+        assert head.startswith(b"HTTP/1.1 405")
+    finally:
+        await proxy.close()
+        task.cancel()
+
+
+async def test_malformed_request_gets_400():
+    proxy, task, proxy_port = await _start_proxy(["127.0.0.1:80"])
+    try:
+        head = await _raw_request(proxy_port, b"garbage\r\n\r\n")
+        assert head.startswith(b"HTTP/1.1 400")
+    finally:
+        await proxy.close()
+        task.cancel()
+
+
+async def test_oversized_head_gets_431():
+    proxy, task, proxy_port = await _start_proxy(["127.0.0.1:80"])
+    try:
+        reader, writer = await asyncio.open_connection("127.0.0.1", proxy_port)
+        writer.write(
+            b"CONNECT 127.0.0.1:80 HTTP/1.1\r\nx: " + b"a" * 32768 + b"\r\n\r\n"
+        )
+        await writer.drain()
+        head = await reader.readuntil(b"\r\n\r\n")
+        assert head.startswith(b"HTTP/1.1 431")
+        writer.close()
+    finally:
+        await proxy.close()
+        task.cancel()
+
+
+async def test_unreachable_allowed_target_gets_502():
+    # Port 1 is allowed by the list but nothing listens there.
+    proxy, task, proxy_port = await _start_proxy(["127.0.0.1:1"])
+    try:
+        head = await _raw_request(proxy_port, b"CONNECT 127.0.0.1:1 HTTP/1.1\r\n\r\n")
+        assert head.startswith(b"HTTP/1.1 502")
+    finally:
+        await proxy.close()
+        task.cancel()
+
+
+# ---- CLI ------------------------------------------------------------------
+
+
+def test_cli_without_allow_exits_loud(capsys):
+    assert cli_main(["--bind", "127.0.0.1:0"]) == 2
+    assert "empty" in capsys.readouterr().err
+
+
+def test_cli_with_bad_bind_exits_loud(capsys):
+    assert cli_main(["--bind", "no-port", "--allow", "x:443"]) == 2
+    assert "--bind" in capsys.readouterr().err
+
+
+def test_cli_with_bad_allow_entry_exits_loud(capsys):
+    assert cli_main(["--allow", "bad entry:443"]) == 2
+    assert "invalid allow entry" in capsys.readouterr().err