Merge branch 'main' into application-layer-udp

Author: bradfitz

README.md

@@ -69,7 +69,14 @@ Or build from source with a Go toolchain:
 $ go install github.com/tailscale/tailcat/cmd/tailcat@latest
 ```
 
-Or with Nix flakes, run it directly or install it:
+Or with Nix, from [nixpkgs](https://search.nixos.org/packages?channel=unstable&query=tailcat):
+
+```sh
+$ nix profile install nixpkgs#tailcat
+$ nix-env -iA nixpkgs.tailcat  # or with classic nix-env
+```
+
+Or with Nix flakes from this repo, run it directly or install it:
 
 ```sh
 $ nix run github:tailscale/tailcat
@@ -197,9 +204,33 @@ $ tailcat forward --bind=0.0.0.0 tcXXXXXXXXX 18080:8080
 
 Press Ctrl-C to stop forwarding.
 
+### Public-key-authenticated SSH server
+
+Run an SSH server that accepts keys from local `authorized_keys` files,
+literal OpenSSH public key lines, or GitHub accounts:
+
+```sh
+$ tailcat serve --ssh-authorized-keys=~/.ssh/authorized_keys ssh
+# 🐈 Server listening with new address: tcXXXXXXXXX
+```
+
+Multiple sources can be comma-separated. A `user@github` source fetches
+`https://github.com/user.keys` once, before the server starts:
+
+```sh
+$ tailcat serve --ssh-authorized-keys=bradfitz@github,./contractor.pub ssh
+```
+
+Every source must exist, fetch successfully, and contain valid public key
+lines or startup fails. Authorized-key options such as `command=` and
+`from=` are rejected because the built-in server does not implement them.
+Running `tailcat serve ssh` without `--ssh-authorized-keys` also fails; use the
+explicit `no-auth-ssh` service when the tunnel identity alone is sufficient.
+
 ### Auth-free SSH server
 
-On Linux and macOS, you can run an SSH server too with no auth. (If you want auth, you can just `tailcat serve 22` and proxy to your system SSH server)
+On Linux, macOS, and Windows, you can also explicitly run the SSH server with
+no client authentication. The encrypted tunnel provides the client identity.
 
 ```sh
 $ tailcat serve no-auth-ssh
@@ -253,8 +284,8 @@ The server confines all paths to the served directory (via Go's
 `os.Root`), so neither `..` nor symlinks escape it. The file service
 speaks SFTP, so the stock `sftp` and `scp` clients also work against
 it, given a ProxyCommand that pipes through tailcat (the same trick
-`tailcat cp` and `tailcat ssh` use). A `no-auth-ssh` server serves
-SFTP too, with the same access as the shell.
+`tailcat cp` and `tailcat ssh` use). Both `ssh` and `no-auth-ssh`
+servers serve SFTP too, with the same access as the shell.
 
 Transfers are not compressed: the SFTP protocol has no compression
 of its own, and the SSH transport here doesn't either (Go's SSH
@@ -341,8 +372,8 @@ A server can print the long self-contained form directly with the
 
 ## Key Management
 
-A server's tailcat address is derived from its WireGuard key, so
-the key you use determines who can reach you:
+A server's tailcat address contains its WireGuard public key and an independent
+WireGuard pre-shared key, so the saved key material determines who can reach you:
 
 * **Ephemeral keys (the default):** each server run generates a fresh key in
   memory and prints an address nobody has ever seen. When the process exits,
@@ -359,6 +390,11 @@ The CLI says at startup which kind it's using, so you know whether you're
 starting a fresh single-use server or re-listening on an address you may
 have shared in the past.
 
+WireGuard pre-shared keys are enabled by default and strongly recommended. For
+compatibility with tailcat clients v0.5.0 and earlier, `--psk=false` on `serve`
+or `genkey` produces shorter addresses, but removes post-quantum protection and
+protection from public DERP operators that observe the peers' public keys.
+
 ```sh
 $ tailcat genkey --key=default --region=nyc
 # prints the tailcat address; key saved to ~/.config/tailcat/keys/default.private.json
@@ -597,12 +633,19 @@ followed by base64-encoded [CBOR](https://cbor.io/) containing:
 
 - The server's WireGuard public key (Curve25519, 32 bytes)
 - A separate path-discovery public key (Curve25519, 32 bytes)
+- By default, an independent WireGuard pre-shared key (256 random bits),
+  which prevents a DERP operator that observes the peers' public keys from
+  joining the tunnel and provides post-quantum protection against recorded
+  traffic
 - DERP info. Either:
   1. a small integer referencing one of the default [Tailscale-run tailcat servers](https://tailcat.dev/derpmap.json), or
   2. full DERP server metadata, to either use a custom DERP server, or to avoid the client needing a potential round-trip to fetch the latest DERP map (the `tailcat serve --full-address` flag and the `tailcat resolve` subcommand produce this form)
 
-A typical tailcat address with just an integer region ID is around 95 bytes. With
-embedded DERP node details it's longer but self-contained.
+A typical tailcat address with just an integer region ID is around 140 bytes.
+With embedded DERP node details it's longer but self-contained.
+
+The default address is a secret bearer capability because it contains the
+pre-shared key. Share it only with clients that should be able to connect.
 
 ### Network stack
 
@@ -624,15 +667,17 @@ without the control plane.
 
 ### Connection flow
 
-1. **Server starts.** It generates (or loads) a WireGuard keypair,
-   connects to a DERP relay, and prints its tailcat address to stderr.
-   It then waits for clients.
+1. **Server starts.** It generates (or loads) a WireGuard keypair and, by
+   default, a pre-shared key, connects to a DERP relay, and prints its tailcat
+   address to stderr. It then waits for clients.
 
-2. **Client parses the tailcat address** to learn the server's public key and
-   path-discovery key, plus its DERP region. It generates its own ephemeral
-   keypair and connects to the same DERP relay. The separate path-discovery
-   key can appear in cleartext direct-path disco frames without revealing the
-   WireGuard public key that acts as the unlisted connection capability.
+2. **Client parses the tailcat address** to learn the server's public key,
+   path-discovery key, optional pre-shared key, and DERP region. It generates
+   its own ephemeral keypair and connects to the same DERP relay. The separate
+   path-discovery key can appear in cleartext direct-path disco frames without
+   revealing the WireGuard public key. The pre-shared key remains the secret
+   connection capability even when a relay operator observes both peers'
+   public keys.
 
 3. **Discovery handshake.** The client sends a "**Meow**" ping message
   to the server through the
@@ -641,10 +686,10 @@ without the control plane.
    network map, reconfigures the WireGuard engine, and replies with a
    "**Meowed**" acknowledgment.
 
-4. **WireGuard tunnel.** With both sides configured as WireGuard
-   peers, the standard WireGuard handshake proceeds (routed through
-   DERP initially). Once complete, the tunnel is up and encrypted
-   traffic can flow.
+4. **WireGuard tunnel.** With both sides configured as WireGuard peers using
+   the address's pre-shared key when present, the WireGuard handshake proceeds
+   (routed through DERP initially). Once complete, the tunnel is up and
+   encrypted traffic can flow.
 
 5. **NAT traversal.** In parallel, each side advertises its UDP
    endpoints (public IP:port learned via STUN, plus local interface

cmd/tailcat/cli_test.go

@@ -5,8 +5,11 @@ package main
 
 import (
 	"bytes"
+	"encoding/json"
 	"errors"
+	"os"
 	"os/exec"
+	"path/filepath"
 	"strings"
 	"testing"
 
@@ -70,7 +73,7 @@ func TestHelpListsCommandTree(t *testing.T) {
 	// Server-only flags live on the serve subcommand, not the root.
 	// (The long help prose may still mention them; only reject them
 	// as rendered flag entries.)
-	for _, notWant := range []string{"\n  --allow", "\n  --full-address"} {
+	for _, notWant := range []string{"\n  --allow", "\n  --full-address", "\n  --psk", "\n  --ssh-authorized-keys"} {
 		if strings.Contains(help, notWant) {
 			t.Errorf("root help lists server-only flag %q", strings.TrimSpace(notWant))
 		}
@@ -91,13 +94,41 @@ func TestServeHelpListsServerFlags(t *testing.T) {
 		t.Fatal("no serve subcommand")
 	}
 	help := ffhelp.Command(serve).String()
-	for _, want := range []string{"--allow", "--full-address", "--key"} {
+	for _, want := range []string{"--allow", "--full-address", "--key", "--psk", "--ssh-authorized-keys"} {
 		if !strings.Contains(help, want) {
 			t.Errorf("serve help is missing %q", want)
 		}
 	}
 }
 
+func TestPSKFlagDefaults(t *testing.T) {
+	if _, err := parseCLI(t, "serve"); err != nil {
+		t.Fatal(err)
+	}
+	if !*flagPSK {
+		t.Error("serve --psk defaulted to false; want true")
+	}
+	if _, err := parseCLI(t, "serve", "--psk=false"); err != nil {
+		t.Fatal(err)
+	}
+	if *flagPSK {
+		t.Error("serve --psk=false parsed as true")
+	}
+
+	if _, err := parseCLI(t, "genkey", "--key=k", "--region=1"); err != nil {
+		t.Fatal(err)
+	}
+	if !*genkeyPSK {
+		t.Error("genkey --psk defaulted to false; want true")
+	}
+	if _, err := parseCLI(t, "genkey", "--key=k", "--region=1", "--psk=false"); err != nil {
+		t.Fatal(err)
+	}
+	if *genkeyPSK {
+		t.Error("genkey --psk=false parsed as true")
+	}
+}
+
 func TestParseFilesFlagWriteOnlyModes(t *testing.T) {
 	dir := t.TempDir()
 	for _, tt := range []struct {
@@ -158,6 +189,27 @@ func TestServeSubcommand(t *testing.T) {
 	}
 }
 
+func TestServeSSHAuthorizedKeysFlag(t *testing.T) {
+	root, err := parseCLI(t, "serve", "--ssh-authorized-keys=one.pub,alice@github", "ssh")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := *flagSSHAuthorizedKeys, "one.pub,alice@github"; got != want {
+		t.Errorf("--ssh-authorized-keys = %q; want %q", got, want)
+	}
+	args := root.GetSelected().Flags.(*ff.FlagSet).GetArgs()
+	if len(args) != 1 || args[0] != "ssh" {
+		t.Errorf("serve args = %q; want [ssh]", args)
+	}
+	_, services, err := parsePortSet("ssh")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !services.Contains("ssh") {
+		t.Error("parsePortSet did not select the ssh service")
+	}
+}
+
 // TestSSHTrailingArgs verifies that flag parsing stops at the ssh
 // destination, so a remote command's own flags (here "-la") are
 // passed through rather than parsed.
@@ -332,6 +384,51 @@ func TestGenkeyRequiresKeyName(t *testing.T) {
 	}
 }
 
+func TestGenkeyPSK(t *testing.T) {
+	bin := buildTailcat(t)
+	for _, tt := range []struct {
+		name    string
+		pskArg  string
+		wantPSK bool
+	}{
+		{name: "default", wantPSK: true},
+		{name: "disabled", pskArg: "--psk=false", wantPSK: false},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			keyFile := filepath.Join(t.TempDir(), "server.private.json")
+			args := []string{"genkey", "--key=" + keyFile, "--region=1"}
+			if tt.pskArg != "" {
+				args = append(args, tt.pskArg)
+			}
+			cmd := exec.Command(bin, args...)
+			cmd.Env = append(os.Environ(), cacheEnv(t)...)
+			out, err := cmd.Output()
+			if err != nil {
+				t.Fatalf("genkey: %v", err)
+			}
+			ci, err := tailcat.ParseAddr(tailcat.Addr(strings.TrimSpace(string(out))))
+			if err != nil {
+				t.Fatalf("ParseAddr: %v", err)
+			}
+			if got := !ci.PresharedKey.IsZero(); got != tt.wantPSK {
+				t.Errorf("address has PSK = %v; want %v", got, tt.wantPSK)
+			}
+
+			j, err := os.ReadFile(keyFile)
+			if err != nil {
+				t.Fatal(err)
+			}
+			var key tailcat.PrivateKey
+			if err := json.Unmarshal(j, &key); err != nil {
+				t.Fatal(err)
+			}
+			if got := !key.Public.PresharedKey.IsZero(); got != tt.wantPSK {
+				t.Errorf("saved key has PSK = %v; want %v", got, tt.wantPSK)
+			}
+		})
+	}
+}
+
 // TestForwardSubcommand verifies that forward parses its bind flag and
 // positional tailcat address and mappings without executing the listener.
 func TestForwardSubcommand(t *testing.T) {

cmd/tailcat/cp.go

@@ -37,7 +37,7 @@ func cpCommand(parent *ff.FlagSet) *ff.Command {
 const cpLongHelp = `Remote paths are written <tc-addr>:[path], like scp's host:path.
 Paths are relative to the server's served directory ("tailcat serve
 files"), or to the remote home directory for a full SSH server
-("tailcat serve no-auth-ssh"). A DNS name with a "tailcat=" TXT
+("tailcat serve ssh" or "tailcat serve no-auth-ssh"). A DNS name with a "tailcat=" TXT
 record works in place of a tailcat address.
 
 Copy a file to a server, keeping its name, and fetch it back:

cmd/tailcat/ls.go

@@ -37,7 +37,7 @@ func lsCommand(parent *ff.FlagSet) *ff.Command {
 }
 
 const lsLongHelp = `List the files a tailcat server offers ("tailcat serve files" or a
-no-auth-ssh server), speaking SFTP directly: no ssh or sftp binary
+ssh or no-auth-ssh server), speaking SFTP directly: no ssh or sftp binary
 is involved.
 
 List the served directory, or a path under it:

cmd/tailcat/serve_test.go

@@ -11,11 +11,14 @@ import (
 	"net"
 	"net/netip"
 	"os/exec"
+	"path/filepath"
 	"regexp"
 	"strconv"
 	"strings"
 	"testing"
 	"time"
+
+	"github.com/tailscale/tailcat"
 )
 
 // startEchoListener starts a TCP echo server on a 127.0.0.1 ephemeral
@@ -42,6 +45,74 @@ func startEchoListener(t *testing.T) uint16 {
 	return uint16(ln.Addr().(*net.TCPAddr).Port)
 }
 
+func TestServeWithoutPSK(t *testing.T) {
+	e := newTestEnv(t)
+	port := startEchoListener(t)
+	_, addr, serverStderr := e.startServer("serve", "--psk=false", strconv.Itoa(int(port)))
+
+	ci, err := tailcat.ParseAddr(tailcat.Addr(addr))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !ci.PresharedKey.IsZero() {
+		t.Fatal("serve --psk=false produced an address containing a PSK")
+	}
+	if !strings.Contains(serverStderr.String(), "# ⚠️ WARNING: serving without a WireGuard PSK\n") {
+		t.Errorf("server stderr lacks PSK warning:\n%s", serverStderr.String())
+	}
+
+	const payload = "echo without a pre-shared key"
+	got, err := runClient(t, e.cmd("--key=new", "--derpmap-url="+e.derpMapURL, addr, strconv.Itoa(int(port))), serverStderr, payload)
+	if err != nil {
+		t.Fatalf("client to server without PSK: %v", err)
+	}
+	if got != payload {
+		t.Errorf("server echoed %q; want %q", got, payload)
+	}
+}
+
+func TestServeRemembersSavedKeyWithoutPSK(t *testing.T) {
+	e := newTestEnv(t)
+	port := startEchoListener(t)
+	keyFile := filepath.Join(t.TempDir(), "server.private.json")
+	genkey := e.cmd("genkey", "--key="+keyFile, "--region=1", "--psk=false")
+	if out, err := genkey.CombinedOutput(); err != nil {
+		t.Fatalf("genkey: %v\n%s", err, out)
+	}
+
+	addrFile := filepath.Join(t.TempDir(), "addr")
+	server := e.cmd("--key="+keyFile, "--derpmap-url="+e.derpMapURL, "serve", strconv.Itoa(int(port)))
+	server.Env = append(server.Env, "TAILCAT_ADDR_FILE="+addrFile)
+	var serverStderr bytes.Buffer
+	server.Stderr = &serverStderr
+	if err := server.Start(); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { server.Process.Kill() })
+	addr := waitAddr(t, addrFile, &serverStderr)
+
+	ci, err := tailcat.ParseAddr(tailcat.Addr(addr))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !ci.PresharedKey.IsZero() {
+		t.Fatal("saved PSK-free key produced an address containing a PSK")
+	}
+	wantWarning := fmt.Sprintf("# ⚠️ WARNING: saved key %q is not using a WireGuard PSK\n", keyFile)
+	if !strings.Contains(serverStderr.String(), wantWarning) {
+		t.Errorf("server stderr lacks %q:\n%s", wantWarning, serverStderr.String())
+	}
+
+	const payload = "echo with saved PSK policy"
+	got, err := runClient(t, e.cmd("--key=new", "--derpmap-url="+e.derpMapURL, addr, strconv.Itoa(int(port))), &serverStderr, payload)
+	if err != nil {
+		t.Fatalf("client to saved server without PSK: %v", err)
+	}
+	if got != payload {
+		t.Errorf("server echoed %q; want %q", got, payload)
+	}
+}
+
 // runClient runs an unstarted tailcat client command with payload on
 // its stdin and a 60 second watchdog, returning its stdout and error.
 // The watchdog only exists to catch true hangs; it's generous because