derptun 0.1.0 → 0.9.0

package/README.md

@@ -8,6 +8,7 @@ It supports:
 - text, file, and directory transfer with `send` and `receive`
 - local TCP service sharing with `share` and `open`
 - SSH access exchange with `ssh invite` and `ssh accept`
+- durable TCP tunnels with the companion `derptun` package
 
 `derphole` uses the public Tailscale [DERP](#what-is-derp) relay network for rendezvous and relay fallback. It is **not** affiliated with Tailscale, does **not** require a Tailscale account or tailnet, and does **not** use `tailscaled` for transport.
 
@@ -34,7 +35,7 @@ Session tokens carry authorization, and receive-code flows resolve into the same
 
 ## Quick Start
 
-`listen` receives bytes and prints a token. `pipe` sends stdin into that token. `share` and `open` use the same token shape for local TCP services.
+`listen` receives bytes and prints a token. `pipe` sends stdin into that token. `share` and `open` use the same token shape for local TCP services. Use `derptun` when the service needs a reusable token and longer-lived tunnel.
 
 ### Stream a Raw File
 
@@ -151,32 +152,42 @@ npx -y derphole@latest open <token> 127.0.0.1:8080
 
 ### Durable SSH Tunnels with `derptun`
 
-`derptun` is the durable TCP tunnel companion to `derphole`. Use it when a host is behind NAT and you want a stable token you can reuse for days instead of a one-hour, session-scoped share token.
+`derptun` is the durable TCP tunnel companion to `derphole`. Use it when `serverhost` is behind NAT and you want a stable server credential that can survive process restarts.
 
-On the target host:
+On `serverhost`:
 
 ```bash
-npx -y derptun@latest token --days 7 > alpha.token
-npx -y derptun@latest serve --token "$(cat alpha.token)" --tcp 127.0.0.1:22
+npx -y derptun@latest token server > server.dts
+npx -y derptun@latest token client --token "$(cat server.dts)" > client.dtc
+npx -y derptun@latest serve --token "$(cat server.dts)" --tcp 127.0.0.1:22
 ```
 
-On the client:
+Copy only `client.dtc` to `clienthost`.
+
+On `clienthost`:
 
 ```bash
-npx -y derptun@latest open --token "$(cat alpha.token)" --listen 127.0.0.1:2222
-ssh -p 2222 foo@127.0.0.1
+npx -y derptun@latest open --token "$(cat client.dtc)" --listen 127.0.0.1:2222
+ssh -p 2222 user@127.0.0.1
 ```
 
 For SSH without a separate local listener, use `ProxyCommand`:
 
 ```sshconfig
-Host alpha-derptun
-  HostName alpha
+Host serverhost-derptun
+  HostName serverhost
   User foo
-  ProxyCommand derptun connect --token ~/.config/derptun/alpha.token --stdio
+  ProxyCommand derptun connect --token ~/.config/derptun/client.dtc --stdio
 ```
 
-`derptun` keeps trying when the network path drops, and it can reconnect while both `derptun` processes stay alive. If either process exits, the token can bring the tunnel back, but an already-open TCP session is gone. Use `tmux` or `screen` on the remote host when shell continuity matters.
+The server token is secret serving authority. Keep it on the serving machine or in its secret manager. The client token can connect until it expires, but it cannot serve or mint more tokens.
+
+Server tokens default to 180 days. Client tokens default to 90 days and cannot outlive their server token. Set a relative lifetime with `--days`, or use an absolute expiry:
+
+```bash
+npx -y derptun@latest token server --expires 2026-05-01T00:00:00Z > server.dts
+npx -y derptun@latest token client --token "$(cat server.dts)" --expires 2026-04-25T00:00:00Z > client.dtc
+```
 
 The first `derptun` release is TCP-only. UDP forwarding is planned for use cases like Minecraft Bedrock servers, but it is not part of this release.
 
@@ -186,6 +197,7 @@ Use the development channel for the latest commit from `main`:
 
 ```bash
 npx -y derphole@dev version
+npx -y derptun@dev version
 ```
 
 By default, `listen`, `pipe`, `send`, `receive`, `share`, and `open` keep transport status quiet. `listen` and `share` print tokens, `open` prints the local listening address, and `send` / `receive` print the receiver command or code needed to complete the transfer. Known-size transfers show wormhole-shaped progress on stderr. Use `--hide-progress` to suppress the progress bar. Use `--verbose` to see state transitions like `connected-relay` and `connected-direct`:
@@ -219,6 +231,7 @@ DERP provides **rendezvous** and **relay fallback**. If the term is new, see [Wh
 The data plane is selected per session:
 
 - `share/open` uses multiplexed QUIC streams over `derphole`'s relay/direct UDP transport, so one claimed session can carry many independent TCP connections to the shared service.
+- `derptun` uses a stable tunnel token and the same relay/direct UDP transport to carry reconnectable TCP streams. It is built for longer-lived access, such as SSH to a host behind NAT.
 - `listen/pipe` uses a one-shot byte stream. By default, `derphole` coordinates through DERP, promotes to rate-adaptive direct UDP when traversal succeeds, and stays on encrypted relay fallback when no direct path is available.
 - `send/receive` wraps the same one-shot stream with text, file, directory, and progress metadata.
 
@@ -259,12 +272,13 @@ In practice: move bytes early, keep them moving through relay if needed, then sh
 
 ## Security Model
 
-The session token is a **bearer capability**. Anyone with the token can claim the session until it expires, so share it over a trusted channel. Tokens expire after one hour.
+Tokens are **bearer capabilities**. Anyone with a token can claim the matching session or tunnel until it expires, so share tokens over a trusted channel. `derphole` session tokens expire after one hour. `derptun` server tokens default to 180 days and can mint shorter-lived client tokens; client tokens default to 90 days and cannot serve.
 
 DERP relays do **not** get the secret material needed to read or impersonate the session:
 
 - On the default `listen/pipe` and `send/receive` direct UDP path, payload packets are encrypted and authenticated with session AEAD derived from the token bearer secret.
 - On `share/open`, stream traffic uses authenticated QUIC streams for the claimed session.
+- On `derptun`, stream traffic uses authenticated QUIC streams pinned to the stable tunnel identity in the token.
 - If packets are relayed through DERP, DERP only forwards encrypted session bytes.
 
 Important security property: `derphole` does not trade speed for plaintext shortcuts:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "derptun",
-  "version": "0.1.0",
+  "version": "0.9.0",
   "license": "BSD-3-Clause",
   "bin": {
     "derptun": "bin/derptun.js"