Metadata-Version: 2.4
Name: supatunnel
Version: 0.1.0
Summary: Lightweight TCP tunnel over Supabase Broadcast
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: supabase>=2.3.0
Requires-Dist: cryptography>=41.0.0

# SupaTunnel

[English](README.md) · [中文指南](README.zh.md)

> Lightweight TCP tunnel over Supabase broadcast channels with AES-GCM encryption, ACK-based retransmit, and rate control.

## ⚙️ Features
- `tunnel_uuid + sid` isolation keeps concurrent local connections from interfering.
- AES-GCM protects payload confidentiality and integrity (secret is derived from your password).
- ACK + timeout retransmit makes the broadcast layer behave more like a reliable stream.
- Per-session token-bucket rate limiter (`--rate-kbps`).
- Installable CLI (`supatunnel`) via `pip install -e .` or registry publish.

## 🧱 Installation
```bash
git clone https://github.com/your-org/marx_supabase_tunnel.git
cd marx_supabase_tunnel
pip install -e .
```

## 🧩 Configuration
Export the following environment variables (see `.env.example` for templates) **before** running the CLI.
```bash
export SUPATUNNEL_URL="https://your-project.supabase.co"
export SUPATUNNEL_KEY="your-anon-key"
export SUPATUNNEL_ROOM="supa_tunnel_default"
export SUPATUNNEL_TUNNEL_UUID="7f3e9f5c-1a4d-4b2a-b3d5-2c4f9a8e1f6e"
export SUPATUNNEL_SECRET="a-strong-secret"
```
Optional tuning:
- `SUPATUNNEL_RATE_KBPS`: kilobytes per second limit (default `0` = unlimited)
- `SUPATUNNEL_CHUNK_BYTES`: chunk size per send (default `16384`)
- `SUPATUNNEL_RTO_MS`: retransmit timeout (default `800`)
- `SUPATUNNEL_MAX_RETRIES`: retransmit attempts (default `5`)
- `SUPATUNNEL_TARGET_HOST`/`PORT`: server forwarding target
- `SUPATUNNEL_LISTEN_HOST`/`PORT`: client local listen endpoint

## 🚀 Usage
1. **Server machine** (where the target service runs):
   ```bash
   supatunnel server --target-host 127.0.0.1 --target-port 80
   ```
   - Starts a Supabase broadcast listener, opens the local target, and waits for client tunnels.

2. **Client machine** (your access point):
   ```bash
   supatunnel client --listen-host 127.0.0.1 --listen-port 8080
   ```
   - Listens locally and forwards the traffic over Supabase using the configured tunnel ID.
   - Access `http://127.0.0.1:8080` to reach the remote service.

## 🧪 Health & debugging
- `supatunnel --help` shows all flags.
- Run `supatunnel client server --rate-kbps 50` to exercise rate limiting.
- Secrets must match on both ends; mismatched secrets fail with decrypt errors.
- The tool prints session lifecycle logs (`OPEN`, `DATA`, `ACK`, `CLOSE`).

## 🏗️ Advanced topics
- Use distinct `SUPATUNNEL_TUNNEL_UUID` values for multiple tunnels even within the same room.
- `SUPATUNNEL_ROOM` lets you isolate groups of tunnels inside Supabase if needed.
- Drop-in AES key rotation: change `SUPATUNNEL_SECRET` and coordinate reconnects.
- The code keeps unacknowledged packets in memory until they are ACKed; tune `--max-retries` to avoid stuck sessions.

## ⚠️ 当前不支持
- UDP 流量，目前仅转发 TCP。
- 不提供本地 NAT 穿透或端口映射逻辑；数据必须依赖 Supabase 广播通道完成转发。
- 没有图形化界面，所有操作通过命令行与日志完成。

## 🧭 Research history
Older prototypes live in the `research/` directory (see `research/README.md`). Production entrypoint is `supatunnel` in `supatunnel/cli.py`.

---

Need more control? Add `--rate-kbps` per session, or drop into the source for custom broadcast hooks.
