Metadata-Version: 2.5
Name: usernet
Version: 0.7.1
Summary: A userspace TCP/IP stack and SOCKS5 proxy for tunnels that carry raw IP
Project-URL: Homepage, https://github.com/dehesselle/usernet
Project-URL: Documentation, https://github.com/dehesselle/usernet/blob/master/docs/MANUAL.md
Project-URL: Issues, https://github.com/dehesselle/usernet/issues
Project-URL: Changelog, https://github.com/dehesselle/usernet/releases
Author-email: René de Hesselle <dehesselle@web.de>
License-Expression: 0BSD
License-File: LICENSE
License-File: LICENSES/0BSD.txt
Keywords: asyncio,ip,network-stack,socks5,tcp,tunnel,userspace,vpn
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: System :: Networking
Classifier: Typing :: Typed
Requires-Python: >=3.12
Provides-Extra: httpx
Requires-Dist: httpx<0.29,>=0.27; extra == 'httpx'
Provides-Extra: testing
Requires-Dist: trustme>=1.1; extra == 'testing'
Description-Content-Type: text/markdown

# usernet

A userspace TCP/IPv4 stack for VPN clients whose tunnel carries raw IP packets.
A client built on it needs nothing from the operating system: no tun device, no
virtual adapter, no routing change, no administrator rights. It hands
decapsulated packets to usernet and gets back connections, an asyncio stream
pair, an httpx client, or a local SOCKS5 proxy that ordinary tools can use.

usernet does not provide the tunnel itself. A tunnel is anything that
implements `IpLink`: `pyac` supplies CSTP over TLS, and `pyts` supplies
WireGuard over DERP. The library needs only the standard library; the httpx
bridge is an optional extra.

## Installation and usage

```sh
uv add usernet
uv add "usernet[httpx]"  # with the httpx bridge
```

The example below opens a connection through the stack. `VirtualLink` is the
in-memory test link that ships with the package; a real client passes its own
tunnel there instead.

```python
import asyncio

from usernet import Driver
from usernet.testing import TcpPeer, VirtualLink
from usernet.testing.peer import http_handler


async def main() -> None:
    # A real tunnel goes here. VirtualLink connects to an in-memory TCP peer.
    peer = TcpPeer(ip="10.0.0.5", port=80, handler=http_handler(b"hello"))
    driver = Driver(VirtualLink(peer, address="10.0.0.2"))
    driver.start()
    try:
        stream = await driver.connect("10.0.0.5", 80)
        await stream.write(b"GET / HTTP/1.1\r\nHost: internal\r\n\r\n")
        print((await stream.read_all()).decode())
    finally:
        await driver.aclose()


asyncio.run(main())
```

## Caveats

- A SOCKS5 listener lets every local process into the VPN without
  authentication. `Socks5Server` therefore binds to loopback only unless told
  otherwise.
- Hostnames are resolved only by the resolver you give the driver. They are
  never sent to the host's DNS. Without a resolver, only addresses work.
- TCP is client-only: the stack opens connections and never accepts them.

## Documentation

<!-- Absolute links: this file is also the PyPI project description. -->

- [docs/MANUAL.md](https://github.com/dehesselle/usernet/blob/master/docs/MANUAL.md):
  the library API, covering how to supply a tunnel, the driver, streams, HTTP,
  SOCKS5, resolvers, errors, logging and the test helpers
- [docs/DESIGN.md](https://github.com/dehesselle/usernet/blob/master/docs/DESIGN.md):
  architecture, seams, scope and the core principles the code must keep
- [docs/OPERATIONS.md](https://github.com/dehesselle/usernet/blob/master/docs/OPERATIONS.md):
  runtime behavior, covering defaults and limits, failure and recovery,
  diagnostics, and troubleshooting hangs
- [docs/DEVELOPMENT.md](https://github.com/dehesselle/usernet/blob/master/docs/DEVELOPMENT.md):
  setup, checks, test strategy, CI and releasing
- [tests/conformance/README.md](https://github.com/dehesselle/usernet/blob/master/tests/conformance/README.md):
  the test suite against a real Linux kernel
- [bench/README.md](https://github.com/dehesselle/usernet/blob/master/bench/README.md):
  benchmark method and measured results

## AI disclosure

Substantial parts of this code were generated with Sonnet 5.x/Opus 5.x.
Generated code was tested, but not every line was reviewed in detail.

## License

[0BSD](https://github.com/dehesselle/usernet/blob/master/LICENSES/0BSD.txt)
