docs: add a server quickstart and disclose the UDP relay provisioning

Same audit as konduit-public (c61664c), applied to koridor. The conclusion
is the opposite: there is no server binary and no config format, so nothing
can be documented wrongly. The source backs the README - ffi/src/ssh.rs:389
uses per-flow channel_open_direct_tcpip, with no streamlocal, remote TUN or
forwarded-tcpip anywhere in the crate. No contradictions found; the gap was
thinness.

Added docs/server-quickstart.md. The whole server story was previously one
clause in the README:

- The real requirement (AllowTcpForwarding yes), and that it is already the
  OpenSSH default, so most servers need no configuration at all.
- What you do NOT need: ip_forward, masquerade rules, /dev/net/tun, root.
  Anyone who has set up a VPN server before assumes all four are required.
- Keypair generation, since the user supplies the key; koridor does not
  generate one for the tunnel.
- Host key trust on first connect. The connect is refused until the
  fingerprint is accepted, and a later change is fatal rather than retried.

The finding that justified the work: UDP forwarding provisions itself on the
user's server on first enable - it writes ~/.koridor/udp-relay.sh, appends a
forced-command line to ~/.ssh/authorized_keys marked # koridor-udp-relay, and
requires socat (hardcoded in ffi/src/udp_relay/script.rs:12). So "No special
server-side software required" is true for TCP and false once that toggle is
on. Nothing public said so. It is off by default and idempotent, and
remove_marked_line strips only koridor's own line, leaving every other key
untouched - but a user's authorized_keys and home directory are modified
without them being told. The README now carries that caveat inline.

#k-ops/#6/#212
This commit is contained in:
E. Kaparulin
2026-10-10 22:58:19 +03:00
parent b7e5dad3be
commit 278cbf4fb4
2 changed files with 174 additions and 1 deletions

View File

@@ -24,7 +24,7 @@ Most VPN apps ask you to trust the app vendor's servers. koridor doesn't have an
## Features
- **Full-device tunnel** — a TUN-based VPN, not just an app-aware SOCKS proxy. Every app on the device is covered, with no per-app setup.
- **Bring your own server** — connects to any SSH server with `AllowTcpForwarding yes`. No special server-side software required.
- **Bring your own server** — connects to any SSH server with `AllowTcpForwarding yes`. No special server-side software required. (One opt-in exception: UDP port forwarding provisions a relay script and an `authorized_keys` line on your server — see the [Server Quickstart](docs/server-quickstart.md#6-optional-udp-port-forwarding).)
- **Simple onboarding** — set up a connection profile, toggle on, done.
- **Fail-closed reconnects** — transient drops are retried with exponential backoff; if the tunnel can't recover, the route is torn down rather than silently leaking traffic in the open.
- **Tunnel-only DNS** — lookups are resolved through the server's own resolver over the tunnel, never leaked to a third-party DNS provider.
@@ -47,6 +47,11 @@ Releases are published on the [Releases](../../releases) page.
Coming soon.
## Setup
- [Server Quickstart](docs/server-quickstart.md) — what your SSH server needs, the
keypair, host-key trust, and what UDP forwarding provisions on your box
## Architecture
```