derptun 0.16.1 → 0.16.3

package/README.md

@@ -1,43 +1,62 @@
 # derphole
 
-`derphole` is a standalone CLI for session-scoped byte transfer and temporary local TCP service sharing. Use it for one-shot transfers, receive-code flows, and short-lived service sharing.
-
-[`derptun`](#long-lived-tcp-tunnels) is its companion for long-lived TCP tunnels. Use it when a tunnel needs stable tokens, restartable endpoints, and repeated client reconnects.
-
-[`derpssh`](#share-a-terminal) is its companion for interactive terminal sharing. Use it when two people need one shared PTY with host approval and no open ports.
-
-`derphole` supports:
-
-- raw byte streams with `listen` and `pipe`
-- 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`
-
-Both tools use the public Tailscale [DERP](#what-is-derp) relay network for rendezvous and fallback, then promote live traffic to direct encrypted UDP when possible. Payload bytes stay end-to-end encrypted on relay fallback, direct UDP, and authenticated QUIC stream paths; DERP sees routing metadata, not contents. They are **not** affiliated with Tailscale and do **not** use `tailscaled`.
-
-Neither tool is a WireGuard overlay or VPN. `derphole` handles one token, one session, one transfer or shared service. `derptun` handles one long-lived tunnel. See [Transport Model](#transport-model), [Why It Is Fast](#why-it-is-fast), and [Security Model](#security-model).
-
-Neither tool requires:
-
-- a Tailscale account
-- a tailnet
-- `tailscaled`
-- a separate control plane to run yourself
-
-Session tokens carry authorization. Public sessions fetch the DERP map at runtime so both sides can find relay and bootstrap nodes. See [Security Model](#security-model) for token and relay details.
+`derphole` is a small CLI for the network job that should not require a new
+network: move bytes, expose a local TCP service, or exchange SSH access for one
+short session when neither side has an inbound port to offer.
+
+The obvious answer is "use a VPN." Sometimes that is correct. If you need
+stable private IPs, ACLs, subnet routes, exit nodes, and machines that remember
+each other, use a VPN. If you need one transfer, one tunnel, or one shared
+terminal, a VPN is a lot of state for a short conversation.
+
+This repo ships three tools:
+
+- `derphole` for one-shot files, byte streams, receive-code flows, temporary
+  localhost shares, and SSH access exchange.
+- [`derptun`](#tcp-tunnels) for longer-lived TCP tunnels with stable server and
+  client tokens.
+- [`derpssh`](#share-a-terminal) for shared terminal sessions with host approval
+  and no open ports.
+
+The tools use the public Tailscale [DERP](#what-is-derp) relay network for
+rendezvous and fallback, then promote live traffic to direct encrypted UDP when
+possible. Payload bytes stay end-to-end encrypted on relay fallback, direct UDP,
+and authenticated QUIC stream paths. DERP sees routing metadata and packet
+timing, not contents.
+
+These tools are **not** affiliated with Tailscale and do **not** use
+`tailscaled`.
+
+They are also not a WireGuard overlay or a VPN. `derphole` handles one token,
+one session, one transfer or shared service. `derptun` handles one tunnel with
+reusable scoped tokens. `derpssh` handles one approved PTY session. See
+[Transport Model](#transport-model), [Why It Is Fast](#why-it-is-fast), and
+[Security Model](#security-model).
+
+No Tailscale account, tailnet, daemon, or self-hosted control plane is required.
+Session tokens carry authorization. Treat them like passwords with a shorter
+half-life. Public sessions fetch the DERP map at runtime so both sides can find
+relay and bootstrap nodes.
 
 ## Pick the Workflow
 
-- Use `listen` and `pipe` for raw byte streams and shell pipelines.
-- Use `send` and `receive` for text, files, directories, progress, and receive-code UX.
-- Use `share` and `open` for temporary access to a local TCP service.
-- Use `ssh invite` and `ssh accept` for SSH public key exchange.
-- Use [`derpssh`](#share-a-terminal) for approved terminal sharing.
-- Use [`derptun`](#long-lived-tcp-tunnels) for long-lived TCP tunnels with reusable tokens.
+- Use `listen` and `pipe` when you want raw bytes and shell pipelines.
+- Use `send` and `receive` when you want text, files, directories, progress, and
+  receive-code UX.
+- Use `share` and `open` when you want temporary access to a local TCP service.
+- Use `ssh invite` and `ssh accept` when you want to exchange SSH access.
+- Use [`derpssh`](#share-a-terminal) when two people need one approved terminal.
+- Use [`derptun`](#tcp-tunnels) when the TCP tunnel needs reusable tokens and
+  reconnects.
 
 ## Quick Start
 
-`listen` receives bytes and prints a token. `pipe` sends stdin into that token. `share` and `open` do the same for local TCP services. Use [`derptun`](#long-lived-tcp-tunnels) for reusable, longer-lived tunnels.
+`listen` receives bytes and prints a token. `pipe` sends stdin into that token.
+`share` and `open` do the same shape of thing for local TCP services. The trick
+is small on purpose: one token, one capability, one session.
+
+Use [`derptun`](#tcp-tunnels) when the tunnel should live longer than a one-off
+share.
 
 ### Stream a Raw File
 
@@ -47,7 +66,8 @@ Receiver:
 npx -y derphole@latest listen > received.img
 ```
 
-`listen` prints a token to stderr, keeping stdout clean. Copy the token to the sender.
+`listen` prints a token to stderr, keeping stdout clean. Copy the token to the
+sender.
 
 Sender:
 
@@ -75,7 +95,8 @@ npx -y derphole@latest send ./photo.jpg
 npx -y derphole@latest receive <code>
 ```
 
-Known-size files and directories show progress on stderr. Use `--hide-progress` for quiet output.
+Known-size files and directories show progress on stderr. Use `--hide-progress`
+when quiet output matters more than watching the counter move.
 
 Text uses the same flow:
 
@@ -141,47 +162,83 @@ npx -y derpssh@latest share
 npx -y derpssh@latest connect <invite>
 ```
 
-The host approves the guest as read-only or read/write. The session uses the derptun transport path, so neither side needs an inbound port.
+The host approves the guest as read-only or read/write. The session uses the
+`derptun` transport path, so neither side needs an inbound port.
+
+Optional local lookup keeps the invite behind a service name on the connecting
+machine:
+
+```bash
+npx -y derpssh@latest service set ops-shell <invite>
+npx -y derpssh@latest connect --service ops-shell
+```
+
+The host still approves the guest. The service name only finds the invite; it
+does not bypass approval.
 
-### Long-Lived TCP Tunnels
+### TCP Tunnels
 
-`derptun` is the long-lived TCP tunnel companion to `derphole`. It uses stable tokens, survives restarts on either side, and lets one client reconnect many times without opening ports on `vps-server`. It fits SSH well.
+`derptun` exposes a local TCP service without asking either side to open an
+inbound port. Start with a one-off tunnel:
 
-On `vps-server`:
+On the serving machine:
 
 ```bash
-npx -y derptun@latest token server > server.dts
-npx -y derptun@latest token client --token-file server.dts > client.dtc
-npx -y derptun@latest serve --token-file server.dts --tcp 127.0.0.1:22
+npx -y derptun@latest serve --tcp 127.0.0.1:3000
 ```
 
-Copy only `client.dtc` to `alice-laptop`.
+`serve` prints the command for the other side:
 
-On `alice-laptop`:
+```bash
+npx -y derptun@latest open --token DT1...
+```
+
+Run that command on the connecting machine. It opens a local listener and
+forwards connections through the tunnel.
+
+For a persistent tunnel, create both tokens on the serving machine and keep the
+server token there:
 
 ```bash
-npx -y derptun@latest open --token-file client.dtc --listen 127.0.0.1:2222
-ssh -p 2222 user@127.0.0.1
+npx -y derptun@latest token server > server.dts
+npx -y derptun@latest token client --token-file server.dts > client.dt1
+npx -y derptun@latest serve --token-file server.dts --tcp 127.0.0.1:3000
 ```
 
-For SSH without a separate local listener, use `ProxyCommand`:
+Copy only `client.dt1` to the connecting machine.
+
+On the connecting machine:
 
 ```bash
-ssh -o ProxyCommand='npx -y derptun@latest connect --token-file ./client.dtc --stdio' foo@127.0.0.1
+npx -y derptun@latest open --token-file client.dt1 --listen 127.0.0.1:3001
 ```
 
-The server token is serving authority. Keep it on the serving machine or in its secret manager. The client token can connect until expiry, but cannot serve or mint tokens.
+The server token is serving authority. Keep it on the serving machine or in a
+secret manager. Client tokens can connect until expiry, but cannot serve or mint
+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:
+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-file server.dts --expires 2026-04-25T00:00:00Z > client.dtc
+npx -y derptun@latest token client --token-file server.dts --expires 2026-04-25T00:00:00Z > client.dt1
 ```
 
-Use `--token TOKEN` for inline one-off commands. Prefer `--token-file PATH` for durable tokens. `--token-stdin` reads the token from the first stdin line.
+Use `--token TOKEN` for inline one-off commands. Prefer `--token-file PATH` for
+durable tokens. `--token-stdin` reads the token from the first stdin line.
+
+Optional local lookup keeps the client token behind a service name on the
+connecting machine:
+
+```bash
+npx -y derptun@latest service set web --token-file client.dt1
+npx -y derptun@latest open --service web --listen 127.0.0.1:3001
+```
 
-`derptun` is TCP-only for now. UDP forwarding is planned for use cases like Minecraft Bedrock servers.
+The registry is local name-to-token storage. It is not a hosted control plane,
+and no lookup server is contacted by default.
 
 ### Useful Extras
 
@@ -193,7 +250,9 @@ npx -y derptun@dev version
 npx -y derpssh@dev version
 ```
 
-Default output stays quiet: tokens, bind addresses, receive commands, and progress only. Use `--hide-progress` to suppress progress, or `--verbose` to see transitions like `connected-relay` and `connected-direct`:
+Default output stays quiet: tokens, bind addresses, receive commands, and
+progress only. Use `--hide-progress` to suppress progress, or `--verbose` to see
+path changes such as `connected-relay` and `connected-direct`:
 
 ```bash
 npx -y derphole@latest --verbose listen
@@ -201,93 +260,161 @@ npx -y derphole@latest --verbose pipe <token>
 npx -y derphole@latest --verbose send ./photo.jpg
 ```
 
-For transport details, see [Transport Model](#transport-model), [Behavior](#behavior), and [Security Model](#security-model).
+For transport details, see [Transport Model](#transport-model),
+[Behavior](#behavior), and [Security Model](#security-model).
 
 ## Transport Model
 
-Flow:
+The session flow is deliberately boring. Boring is good here.
 
-1. `listen`, `share`, or `receive` creates a session and prints an opaque bearer token or receive code.
-2. The token carries session ID, expiry, DERP bootstrap hints, listener public identity, bearer secret, and allowed capability.
-3. `pipe`, `send`, or `open` uses that token to contact the listener through DERP and claim the session.
-4. The listener validates the claim, checks the requested capability, and returns current direct-path candidates.
+1. `listen`, `share`, or `receive` creates a session and prints an opaque bearer
+   token or receive code.
+2. The token carries session ID, expiry, DERP bootstrap hints, listener public
+   identity, bearer secret, and allowed capability.
+3. `pipe`, `send`, or `open` uses that token to contact the listener through
+   DERP and claim the session.
+4. The listener validates the claim, checks the requested capability, and returns
+   current direct-path candidates.
 5. Both sides start on the first working path, including DERP relay if needed.
-6. Both sides keep probing for a better direct path. Successful direct paths upgrade the live session in place.
+6. Both sides keep probing for a better direct path. Successful direct paths
+   upgrade the live session in place.
 
 ### Data Plane Selection
 
-DERP provides **rendezvous** and **relay fallback**. See [What Is DERP?](#what-is-derp):
+DERP provides **rendezvous** and **relay fallback**. See
+[What Is DERP?](#what-is-derp):
 
-- rendezvous: exchange claim, decision, and direct-path coordination messages without an account-backed control plane
-- relay fallback: keep the session working when NAT traversal fails or direct connectivity is not ready
+- rendezvous: exchange claim, decision, and direct-path coordination messages
+  without an account-backed control plane
+- relay fallback: keep the session working when NAT traversal fails or direct
+  connectivity is not ready
 
 The data plane is selected per session:
 
-- `share/open` uses multiplexed QUIC streams over `derphole`'s relay/direct UDP transport. One claimed session can carry many TCP connections to the shared service.
-- `derptun` uses a stable tunnel token and the same transport for reconnectable TCP streams. It is built for longer-lived access, such as SSH to a host behind NAT.
-- `derpssh` uses the derptun app mux for approved terminal streams and side-channel control.
-- `listen/pipe` uses a one-shot byte stream. It coordinates through DERP, promotes to rate-adaptive direct UDP when traversal succeeds, and stays on encrypted relay fallback when direct paths fail.
-- `send/receive` wraps the same one-shot stream with text, file, directory, and progress metadata.
+- `share/open` uses multiplexed QUIC streams over `derphole`'s relay/direct UDP
+  transport. One claimed session can carry many TCP connections to the shared
+  service.
+- `derptun` uses a stable tunnel token and the same transport for reconnectable
+  TCP streams. It is built for longer-lived access, such as a private service
+  behind NAT.
+- `derpssh` uses the `derptun` app mux for approved terminal streams and
+  side-channel control.
+- `listen/pipe` uses a one-shot byte stream. It coordinates through DERP,
+  promotes to rate-adaptive direct UDP when traversal succeeds, and stays on
+  encrypted relay fallback when direct paths fail.
+- `send/receive` wraps the same one-shot stream with text, file, directory, and
+  progress metadata.
 
 Candidate discovery splits into two phases:
 
-- fast local candidates first: advertise local sockets, interfaces, and cached port mappings immediately
-- background traversal discovery: run STUN and UPnP / NAT-PMP / PCP refresh, then send updated candidates and `call-me-maybe` probes
+- fast local candidates first: advertise local sockets, interfaces, and cached
+  port mappings immediately
+- background traversal discovery: run STUN and UPnP / NAT-PMP / PCP refresh,
+  then send updated candidates and `call-me-maybe` probes
 
 This keeps startup latency low while preserving relay-to-direct promotion.
 
 ## How This Differs From Tailscale / WireGuard
 
-Tailscale uses WireGuard for a secure general-purpose network: durable machine connectivity, private addresses, ACLs, subnet routing, exit nodes, and long-lived overlays.
+Tailscale uses WireGuard for a secure general-purpose network: durable machine
+connectivity, private addresses, ACLs, subnet routing, exit nodes, and
+long-lived overlays.
+
+That is the right tool when you want a network.
 
-`derphole` is narrower. It creates session-scoped transport for one transfer or one shared service:
+`derphole` is narrower. It creates session-scoped transport for one transfer or
+one shared service:
 
 - no WireGuard tunnel device
 - no overlay network interface
 - no persistent mesh control plane
 - no need to route arbitrary traffic through a general encrypted network
 
-Instead, `derphole` authorizes one session with a bearer token, uses DERP to connect peers immediately, then promotes onto the best direct path it can establish. See [Transport Model](#transport-model) and [Security Model](#security-model).
+Instead, `derphole` authorizes one session with a bearer token, uses DERP to get
+peers connected immediately, then promotes onto the best direct path it can
+establish. See [Transport Model](#transport-model) and
+[Security Model](#security-model).
 
-For `listen/pipe`, `send/receive`, and `share/open`, this can beat routing the same traffic through a WireGuard-based overlay because `derphole` optimizes one active session. See [Why It Is Fast](#why-it-is-fast).
+For `listen/pipe`, `send/receive`, and `share/open`, this can beat routing the
+same traffic through a WireGuard-based overlay because `derphole` optimizes one
+active session instead of maintaining a whole private network. Not magic. Less
+machinery.
 
 ## Why It Is Fast
 
-Performance comes from transport shape:
+Performance comes from the transport shape:
 
 - DERP handles rendezvous and fallback, not preferred steady-state data.
-- Sessions can start relayed, then promote in place to direct without restarting.
-- `listen/pipe` and `send/receive` can scale across direct UDP lanes, run path-rate probes, then use paced sending, adaptive rate control, and targeted replay/repair. Fast links can run near WAN ceiling without forcing slower links into the same send rate.
-- Direct UDP payloads use AEAD with a per-session key derived from the bearer secret. Headers stay visible for sequencing and repair; user bytes stay encrypted and authenticated.
-- `share/open` keeps QUIC stream multiplexing for service sharing, where many independent TCP streams need one claimed session.
-- Candidate discovery starts with local interfaces and cached mappings, then refines in the background with STUN and port mapping refresh.
-
-Result: move bytes early, keep relay fallback, and shift live sessions to direct paths when ready.
+- Sessions can start relayed, then promote in place to direct without
+  restarting.
+- `listen/pipe` and `send/receive` can scale across direct UDP lanes, run
+  path-rate probes, then use paced sending, adaptive rate control, and targeted
+  replay/repair. Fast links can run near WAN ceiling without forcing slower
+  links into the same send rate.
+- Direct UDP payloads use AEAD with a per-session key derived from the bearer
+  secret. Headers stay visible for sequencing and repair; user bytes stay
+  encrypted and authenticated.
+- `share/open` keeps QUIC stream multiplexing for service sharing, where many
+  independent TCP streams need one claimed session.
+- Candidate discovery starts with local interfaces and cached mappings, then
+  refines in the background with STUN and port mapping refresh.
+
+The practical result: move bytes early, keep relay fallback, and shift live
+sessions to direct paths when ready.
 
 ## Security Model
 
-Tokens are **bearer capabilities**. Anyone with a token can claim the matching session or tunnel until expiry, 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.
-
-Payload bytes are always end-to-end encrypted between token holders. Session and tunnel encryption is pinned to token-derived identity, so DERP relays do **not** get keys needed to read or impersonate sessions. DERP can see routing metadata and packet timing, but not plaintext user payload bytes:
-
-- On `listen/pipe` and `send/receive`, direct UDP and relay fallback both encrypt and authenticate user payloads with session AEAD derived from the bearer secret.
-- Relay-prefix startup frames leave frame kind and byte offsets visible for flow control, but encrypt user payload bytes.
-- 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.
-- On `derpssh`, terminal streams use authenticated QUIC streams pinned to the invite identity.
-
-Simple rule: token possession authorizes the session. Relays move packets; they do not hold decrypt keys for user payloads.
+Tokens are **bearer capabilities**. Anyone with a token can claim the matching
+session or tunnel until expiry, 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.
+
+Local service registry entries are bearer secrets because they contain derptun
+client tokens or derpssh invites. Protect the registry file like token files.
+List output redacts token and invite values, and no lookup server is contacted
+by default.
+
+Payload bytes are always end-to-end encrypted between token holders. Session and
+tunnel encryption is pinned to token-derived identity, so DERP relays do **not**
+get keys needed to read or impersonate sessions. DERP can see routing metadata
+and packet timing, but not plaintext user payload bytes:
+
+- On `listen/pipe` and `send/receive`, direct UDP and relay fallback both encrypt
+  and authenticate user payloads with session AEAD derived from the bearer
+  secret.
+- Relay-prefix startup frames leave frame kind and byte offsets visible for flow
+  control, but encrypt user payload bytes.
+- 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.
+- On `derpssh`, terminal streams use authenticated QUIC streams pinned to the
+  invite identity.
+
+Simple rule: token possession authorizes the session. Relays move packets; they
+do not hold decrypt keys for user payloads.
 
 ## Behavior
 
-Sessions can start on DERP relay and later promote to direct paths without restarting. By default, CLI output stays minimal. Use `--verbose` for path changes, NAT traversal state, and direct-path tuning.
+Sessions can start on DERP relay and later promote to direct paths without
+restarting. By default, CLI output stays minimal. Use `--verbose` for path
+changes, NAT traversal state, and direct-path tuning.
 
 ## Use Cases
 
+Use this when you need:
+
 - cross-host transfer with no account setup
-- NAT-heavy networks where direct connectivity may or may not work
+- useful behavior on NAT-heavy networks where direct connectivity may or may not
+  work
 - quick sharing of local web apps, APIs, and admin interfaces
-- `npx` use without manual install
+- `npx` execution without manual install
+
+Do not use this as a replacement for a real private network when you actually
+need one. That is how small tools become infrastructure nobody remembers
+owning. Oops.
 
 ## Development
 
@@ -326,13 +453,22 @@ REMOTE_HOST=my-server.example.com mise run promotion-1g
 
 ## What Is DERP?
 
-DERP stands for **Designated Encrypted Relay for Packets**. It is a globally reachable relay network that both peers can use when they cannot yet talk directly.
+DERP stands for **Designated Encrypted Relay for Packets**. It is a globally
+reachable relay network that both peers can use when they cannot yet talk
+directly.
 
-DERP was built by Tailscale for the Tailscale networking stack. The public Tailscale-operated DERP network is reachable without running your own relays. Headscale, the open-source Tailscale control server, can also serve DERP maps and DERP servers.
+DERP was built by Tailscale for the Tailscale networking stack. The public
+Tailscale-operated DERP network is reachable without running your own relays.
+Headscale, the open-source Tailscale control server, can also serve DERP maps
+and DERP servers.
 
 In `derphole`, DERP has two jobs:
 
-- rendezvous: carry claim, decision, and direct-path coordination messages without a separate account-backed control plane
-- fallback relay: carry encrypted session traffic when NAT traversal has not succeeded or direct connectivity is unavailable
+- rendezvous: carry claim, decision, and direct-path coordination messages
+  without a separate account-backed control plane
+- fallback relay: carry encrypted session traffic when NAT traversal has not
+  succeeded or direct connectivity is unavailable
 
-DERP is not the preferred steady-state path. It starts the session and keeps it working. If direct UDP becomes available, `derphole` promotes the live session. DERP forwards bytes; it does not get session decrypt keys.
+DERP is not the preferred steady-state path. It starts the session and keeps it
+working. If direct UDP becomes available, `derphole` promotes the live session.
+DERP forwards bytes; it does not get session decrypt keys.

package/package.json

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