server: tls-echo — ClientHello capture + JA4 on the TCP-echo port (§4 complete)

A connection opening with a TLS handshake (first byte 0x16) and ALPN
elt-echo gets the ClientHello it sent back raw (b64) and as a JA4
fingerprint (sec.clienthello_echo), then a TLS byte-echo; plain
connections are unchanged. One port, multiplexed by a timed peek:
plain echo is server-speaks-first, so a silent client (peek timeout) is
greeted, while a TLS client's immediate ClientHello (0x16) routes to the
TLS path — 500ms tolerates ~1s RTT before misdetection.

JA4 (FoxIO): full ClientHello parser (ciphers, extensions, ALPN,
supported_versions, sig algs) with GREASE exclusion; a_b_c fingerprint,
unit-tested for structure + GREASE invariance. Live-verified: elt-echo
negotiated, JA4 t13d1712eo computed, 1530-byte ClientHello returned.
Capability tls-echo. This completes spec §4.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

server/cmd/echolot-server/main.go

@@ -103,11 +103,14 @@ func serve(cfg *config.Config) error {
 
 	sessions := session.NewManager(15 * time.Minute)
 	dp := &dataplane.Server{Sessions: sessions}
-	tcpSrv := &tcpecho.Server{}
+	// TCP echo shares the control cert for its elt-echo TLS variant.
+	tcpSrv := &tcpecho.Server{
+		TLSConfig: &tls.Config{Certificates: []tls.Certificate{cert}, MinVersion: tls.VersionTLS12},
+	}
 
 	caps := []string{"udp-probe", "delayed-echo", "connect-back", "http-echo"}
 	if len(config.Addrs(cfg.TCPListen)) > 0 {
-		caps = append(caps, "tcp-echo")
+		caps = append(caps, "tcp-echo", "tls-echo")
 	}
 
 	ctl := &control.Server{

server/internal/tcpecho/ja4.go

@@ -0,0 +1,286 @@
+// SPDX-FileCopyrightText: 2026 Echolot contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+package tcpecho
+
+import (
+	"crypto/sha256"
+	"encoding/binary"
+	"encoding/hex"
+	"fmt"
+	"sort"
+	"strings"
+)
+
+// clientHello holds the fields JA4 needs from a parsed TLS ClientHello.
+type clientHello struct {
+	legacyVersion     uint16
+	cipherSuites      []uint16
+	extensions        []uint16 // in wire order
+	hasSNI            bool
+	alpns             []string
+	supportedVersions []uint16
+	sigAlgs           []uint16 // in wire order
+}
+
+// isGREASE reports whether a code point is a GREASE value (RFC 8701): both
+// bytes equal and of the form 0x?a. JA4 excludes these everywhere.
+func isGREASE(v uint16) bool {
+	return v&0x0f0f == 0x0a0a && v>>8 == v&0xff
+}
+
+// parseClientHello parses a full TLS record (starting at the 0x16 record
+// header) and extracts the ClientHello fields. Returns false if the bytes are
+// not a well-formed ClientHello.
+func parseClientHello(rec []byte) (*clientHello, bool) {
+	// Record header: type(1)=0x16, version(2), length(2).
+	if len(rec) < 5 || rec[0] != 0x16 {
+		return nil, false
+	}
+	recLen := int(binary.BigEndian.Uint16(rec[3:5]))
+	if len(rec) < 5+recLen {
+		return nil, false
+	}
+	b := rec[5 : 5+recLen]
+	// Handshake header: msg_type(1)=0x01 ClientHello, length(3).
+	if len(b) < 4 || b[0] != 0x01 {
+		return nil, false
+	}
+	hsLen := int(b[1])<<16 | int(b[2])<<8 | int(b[3])
+	b = b[4:]
+	if len(b) < hsLen {
+		return nil, false
+	}
+	b = b[:hsLen]
+
+	h := &clientHello{}
+	// client_version(2), random(32).
+	if len(b) < 34 {
+		return nil, false
+	}
+	h.legacyVersion = binary.BigEndian.Uint16(b[0:2])
+	b = b[34:]
+	// session_id.
+	if len(b) < 1 || len(b) < 1+int(b[0]) {
+		return nil, false
+	}
+	b = b[1+int(b[0]):]
+	// cipher_suites.
+	if len(b) < 2 {
+		return nil, false
+	}
+	cslen := int(binary.BigEndian.Uint16(b[0:2]))
+	b = b[2:]
+	if len(b) < cslen || cslen%2 != 0 {
+		return nil, false
+	}
+	for i := 0; i < cslen; i += 2 {
+		h.cipherSuites = append(h.cipherSuites, binary.BigEndian.Uint16(b[i:i+2]))
+	}
+	b = b[cslen:]
+	// compression_methods.
+	if len(b) < 1 || len(b) < 1+int(b[0]) {
+		return nil, false
+	}
+	b = b[1+int(b[0]):]
+	// extensions (optional).
+	if len(b) < 2 {
+		return h, true
+	}
+	extTotal := int(binary.BigEndian.Uint16(b[0:2]))
+	b = b[2:]
+	if len(b) < extTotal {
+		return nil, false
+	}
+	ext := b[:extTotal]
+	for len(ext) >= 4 {
+		etype := binary.BigEndian.Uint16(ext[0:2])
+		elen := int(binary.BigEndian.Uint16(ext[2:4]))
+		if len(ext) < 4+elen {
+			break
+		}
+		data := ext[4 : 4+elen]
+		h.extensions = append(h.extensions, etype)
+		switch etype {
+		case 0x0000: // server_name
+			h.hasSNI = true
+		case 0x0010: // ALPN
+			h.alpns = append(h.alpns, parseALPN(data)...)
+		case 0x002b: // supported_versions
+			h.supportedVersions = parseSupportedVersions(data)
+		case 0x000d: // signature_algorithms
+			h.sigAlgs = parseU16List(data)
+		}
+		ext = ext[4+elen:]
+	}
+	return h, true
+}
+
+func parseALPN(d []byte) []string {
+	if len(d) < 2 {
+		return nil
+	}
+	listLen := int(binary.BigEndian.Uint16(d[0:2]))
+	d = d[2:]
+	if len(d) < listLen {
+		return nil
+	}
+	var out []string
+	for len(d) >= 1 {
+		n := int(d[0])
+		if len(d) < 1+n {
+			break
+		}
+		out = append(out, string(d[1:1+n]))
+		d = d[1+n:]
+	}
+	return out
+}
+
+func parseSupportedVersions(d []byte) []uint16 {
+	if len(d) < 1 {
+		return nil
+	}
+	n := int(d[0])
+	d = d[1:]
+	if len(d) < n || n%2 != 0 {
+		return nil
+	}
+	var out []uint16
+	for i := 0; i < n; i += 2 {
+		out = append(out, binary.BigEndian.Uint16(d[i:i+2]))
+	}
+	return out
+}
+
+// parseU16List parses a 2-byte-length-prefixed list of u16 values (used for
+// signature_algorithms).
+func parseU16List(d []byte) []uint16 {
+	if len(d) < 2 {
+		return nil
+	}
+	n := int(binary.BigEndian.Uint16(d[0:2]))
+	d = d[2:]
+	if len(d) < n || n%2 != 0 {
+		return nil
+	}
+	var out []uint16
+	for i := 0; i < n; i += 2 {
+		out = append(out, binary.BigEndian.Uint16(d[i:i+2]))
+	}
+	return out
+}
+
+// ja4 computes the JA4 TLS client fingerprint (FoxIO spec) from a parsed
+// ClientHello: a_b_c where a is a human-readable prefix, b hashes the sorted
+// cipher list, c hashes the sorted extensions + signature algorithms.
+func ja4(h *clientHello) string {
+	// --- a ---
+	ver := ja4Version(h)
+	sni := "i"
+	if h.hasSNI {
+		sni = "d"
+	}
+	nCiphers := countNonGREASE(h.cipherSuites)
+	nExts := countNonGREASE(h.extensions) // count includes SNI + ALPN
+	alpn := "00"
+	if len(h.alpns) > 0 && h.alpns[0] != "" {
+		a := h.alpns[0]
+		alpn = string(a[0]) + string(a[len(a)-1])
+	}
+	a := fmt.Sprintf("t%s%s%02d%02d%s", ver, sni, capAt99(nCiphers), capAt99(nExts), alpn)
+
+	// --- b: sorted non-GREASE cipher suites, lowercase hex, comma-joined ---
+	b := hash12(strings.Join(sortedHex(nonGREASE(h.cipherSuites)), ","))
+
+	// --- c: sorted non-GREASE extensions (minus SNI 0000 and ALPN 0010),
+	// then "_", then signature algorithms IN ORDER (non-GREASE) ---
+	extsForC := filterOut(nonGREASE(h.extensions), 0x0000, 0x0010)
+	cInput := strings.Join(sortedHex(extsForC), ",") + "_" + strings.Join(hexList(nonGREASE(h.sigAlgs)), ",")
+	c := hash12(cInput)
+
+	return a + "_" + b + "_" + c
+}
+
+// ja4Version picks the highest offered version (supported_versions if present,
+// else the legacy field) mapped to JA4's two-char code.
+func ja4Version(h *clientHello) string {
+	best := h.legacyVersion
+	for _, v := range h.supportedVersions {
+		if isGREASE(v) {
+			continue
+		}
+		if v > best {
+			best = v
+		}
+	}
+	switch best {
+	case 0x0304:
+		return "13"
+	case 0x0303:
+		return "12"
+	case 0x0302:
+		return "11"
+	case 0x0301:
+		return "10"
+	case 0x0300:
+		return "s3"
+	}
+	return "00"
+}
+
+func nonGREASE(in []uint16) []uint16 {
+	out := make([]uint16, 0, len(in))
+	for _, v := range in {
+		if !isGREASE(v) {
+			out = append(out, v)
+		}
+	}
+	return out
+}
+
+func countNonGREASE(in []uint16) int { return len(nonGREASE(in)) }
+
+func filterOut(in []uint16, drop ...uint16) []uint16 {
+	out := make([]uint16, 0, len(in))
+	for _, v := range in {
+		skip := false
+		for _, d := range drop {
+			if v == d {
+				skip = true
+			}
+		}
+		if !skip {
+			out = append(out, v)
+		}
+	}
+	return out
+}
+
+func sortedHex(in []uint16) []string {
+	cp := append([]uint16(nil), in...)
+	sort.Slice(cp, func(i, j int) bool { return cp[i] < cp[j] })
+	return hexList(cp)
+}
+
+func hexList(in []uint16) []string {
+	out := make([]string, len(in))
+	for i, v := range in {
+		var b [2]byte
+		binary.BigEndian.PutUint16(b[:], v)
+		out[i] = hex.EncodeToString(b[:])
+	}
+	return out
+}
+
+func hash12(s string) string {
+	sum := sha256.Sum256([]byte(s))
+	return hex.EncodeToString(sum[:])[:12]
+}
+
+func capAt99(n int) int {
+	if n > 99 {
+		return 99
+	}
+	return n
+}

server/internal/tcpecho/ja4_test.go

@@ -0,0 +1,111 @@
+// SPDX-FileCopyrightText: 2026 Echolot contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+package tcpecho
+
+import (
+	"encoding/binary"
+	"strings"
+	"testing"
+)
+
+// buildClientHello assembles a minimal but valid TLS ClientHello record for
+// tests: TLS1.2 legacy version, the given ciphers, and extensions SNI, ALPN
+// (h2), supported_versions (1.3), signature_algorithms (0x0403).
+func buildClientHello(ciphers []uint16) []byte {
+	u16 := func(v uint16) []byte { b := make([]byte, 2); binary.BigEndian.PutUint16(b, v); return b }
+
+	var body []byte
+	body = append(body, u16(0x0303)...)      // client_version TLS1.2
+	body = append(body, make([]byte, 32)...) // random
+	body = append(body, 0)                    // session_id len 0
+	// cipher suites
+	cs := []byte{}
+	for _, c := range ciphers {
+		cs = append(cs, u16(c)...)
+	}
+	body = append(body, u16(uint16(len(cs)))...)
+	body = append(body, cs...)
+	body = append(body, 1, 0) // compression: 1 method, null
+
+	// extensions
+	var exts []byte
+	addExt := func(typ uint16, data []byte) {
+		exts = append(exts, u16(typ)...)
+		exts = append(exts, u16(uint16(len(data)))...)
+		exts = append(exts, data...)
+	}
+	// SNI: server_name_list -> host_name "x"
+	sni := append(u16(3), 0)      // list len 3, name_type host_name(0)
+	sni = append(sni, u16(1)...)  // name len 1
+	sni = append(sni, 'x')
+	addExt(0x0000, sni)
+	// ALPN: protocol_name_list -> "h2"
+	alpn := append(u16(3), 2, 'h', '2') // list len 3, strlen 2, "h2"
+	addExt(0x0010, alpn)
+	// supported_versions: list len 2, 0x0304
+	addExt(0x002b, append([]byte{2}, u16(0x0304)...))
+	// signature_algorithms: list len 2, 0x0403
+	addExt(0x000d, append(u16(2), u16(0x0403)...))
+
+	body = append(body, u16(uint16(len(exts)))...)
+	body = append(body, exts...)
+
+	// handshake header
+	hs := []byte{0x01, byte(len(body) >> 16), byte(len(body) >> 8), byte(len(body))}
+	hs = append(hs, body...)
+	// record header
+	rec := []byte{0x16, 0x03, 0x01, byte(len(hs) >> 8), byte(len(hs))}
+	return append(rec, hs...)
+}
+
+func TestParseAndJA4(t *testing.T) {
+	rec := buildClientHello([]uint16{0x1301, 0x1302})
+	h, ok := parseClientHello(rec)
+	if !ok {
+		t.Fatal("parse failed")
+	}
+	if len(h.cipherSuites) != 2 || !h.hasSNI || len(h.alpns) != 1 || h.alpns[0] != "h2" {
+		t.Fatalf("parsed fields wrong: %+v", h)
+	}
+	if len(h.supportedVersions) != 1 || h.supportedVersions[0] != 0x0304 {
+		t.Fatalf("supported_versions: %v", h.supportedVersions)
+	}
+
+	got := ja4(h)
+	// _a: t + 13 (supported_versions 1.3) + d (SNI) + 02 ciphers + 04 exts + h2
+	wantA := "t13d0204h2"
+	parts := strings.Split(got, "_")
+	if len(parts) != 3 {
+		t.Fatalf("JA4 not 3 parts: %s", got)
+	}
+	if parts[0] != wantA {
+		t.Fatalf("JA4_a = %s, want %s (full %s)", parts[0], wantA, got)
+	}
+	if len(parts[1]) != 12 || len(parts[2]) != 12 {
+		t.Fatalf("JA4 hash parts not 12 hex: %s", got)
+	}
+	// determinism
+	if ja4(h) != got {
+		t.Fatal("JA4 not deterministic")
+	}
+}
+
+func TestJA4GREASEExcluded(t *testing.T) {
+	// Same hello but with a GREASE cipher inserted; cipher count and _b hash
+	// must be identical to the non-GREASE version.
+	base := ja4(mustParse(t, buildClientHello([]uint16{0x1301, 0x1302})))
+	withGrease := ja4(mustParse(t, buildClientHello([]uint16{0x0a0a, 0x1301, 0x1302})))
+	if base != withGrease {
+		t.Fatalf("GREASE changed JA4:\n base=%s\n grease=%s", base, withGrease)
+	}
+}
+
+func mustParse(t *testing.T, rec []byte) *clientHello {
+	t.Helper()
+	h, ok := parseClientHello(rec)
+	if !ok {
+		t.Fatal("parse failed")
+	}
+	return h
+}

server/internal/tcpecho/tcpecho.go

@@ -1,16 +1,17 @@
 // SPDX-FileCopyrightText: 2026 Echolot contributors
 // SPDX-License-Identifier: GPL-3.0-or-later
 
-// Package tcpecho implements the spec §4 TCP echo: after connect the server
-// sends one JSON line with what it observed (source address/port, negotiated
-// MSS and TCP options from TCP_INFO), then byte-echoes until FIN. This is the
-// evidence source for mtu.mss_observed.
-//
-// The TLS/ALPN "elt-echo" variant (ClientHello capture + JA4) is not
-// implemented yet.
+// Package tcpecho implements spec §4 TCP echo and its TLS variant on the same
+// port. Plain connections get a JSON greeting (observed source, negotiated
+// MSS and TCP options from TCP_INFO — the mtu.mss_observed evidence) then a
+// byte echo. A connection that opens with a TLS handshake (first byte 0x16)
+// and ALPN "elt-echo" gets, additionally, the ClientHello it sent back raw +
+// as a JA4 fingerprint (sec.clienthello_echo) before the echo.
 package tcpecho
 
 import (
+	"crypto/tls"
+	"encoding/base64"
 	"encoding/json"
 	"io"
 	"net"
@@ -24,9 +25,16 @@ type ConnRecord struct {
 	Src         string    `json:"src"`
 	MSS         int       `json:"mss"`
 	Options     []string  `json:"options"`
+	TLS         bool      `json:"tls"`
+	JA4         string    `json:"ja4,omitempty"`
+	ALPN        string    `json:"alpn,omitempty"`
 }
 
 type Server struct {
+	// TLSConfig enables the elt-echo TLS variant; nil disables it (plain echo
+	// only). "elt-echo" is appended to NextProtos at Serve time.
+	TLSConfig *tls.Config
+
 	mu     sync.Mutex
 	recent []ConnRecord // ring, newest last
 }
@@ -65,27 +73,120 @@ func (s *Server) Serve(ln net.Listener) error {
 	}
 }
 
+// prefixConn replays already-read bytes before continuing with the underlying
+// connection — used to hand the peeked ClientHello record to tls.Server.
+type prefixConn struct {
+	net.Conn
+	prefix []byte
+}
+
+func (p *prefixConn) Read(b []byte) (int, error) {
+	if len(p.prefix) > 0 {
+		n := copy(b, p.prefix)
+		p.prefix = p.prefix[n:]
+		return n, nil
+	}
+	return p.Conn.Read(b)
+}
+
 func (s *Server) handle(conn net.Conn) {
 	defer conn.Close()
 	_ = conn.SetDeadline(time.Now().Add(5 * time.Minute))
 
-	info := tcpInfo(conn) // platform-specific; zero values off-Linux
+	// TCP_INFO must be read from the raw *net.TCPConn, before any wrapping.
+	info := tcpInfo(conn)
 	rec := ConnRecord{
 		ConnectedAt: time.Now().UTC(),
 		Src:         conn.RemoteAddr().String(),
 		MSS:         info.MSS,
 		Options:     info.Options,
 	}
+
+	// Multiplex TLS vs plain on one port. Plain echo is server-speaks-first
+	// (the client waits for the greeting), while a TLS client sends its
+	// ClientHello immediately — so peek the first byte with a short deadline:
+	// a byte that arrives fast and is 0x16 means TLS; a timeout means a plain
+	// client waiting to be greeted.
+	// 500ms tolerates ~1s RTT (incl. satellite) before a TLS ClientHello would
+	// be misread as a silent plain client; plain clients simply wait this long
+	// for the greeting they're already waiting for.
+	first := make([]byte, 1)
+	_ = conn.SetReadDeadline(time.Now().Add(500 * time.Millisecond))
+	n, err := io.ReadFull(conn, first)
+	_ = conn.SetDeadline(time.Now().Add(5 * time.Minute)) // reset for the session
+	switch {
+	case err == nil && first[0] == 0x16 && s.TLSConfig != nil:
+		s.handleTLS(conn, first, rec)
+		return
+	case err == nil:
+		s.plainEcho(conn, first, rec) // client spoke first (rare) — replay it
+		return
+	case n == 0 && isTimeout(err):
+		s.plainEcho(conn, nil, rec) // client waiting for greeting — normal path
+		return
+	default:
+		return // EOF or a real error
+	}
+}
+
+func (s *Server) plainEcho(conn net.Conn, peeked []byte, rec ConnRecord) {
+	pc := &prefixConn{Conn: conn, prefix: peeked}
+	s.record(rec)
+	greeting, _ := json.Marshal(map[string]any{
+		"observed_src": rec.Src, "mss": rec.MSS, "options": rec.Options, "tls": false,
+	})
+	if _, err := pc.Write(append(greeting, '\n')); err != nil {
+		return
+	}
+	_, _ = io.Copy(pc, pc)
+}
+
+func isTimeout(err error) bool {
+	ne, ok := err.(net.Error)
+	return ok && ne.Timeout()
+}
+
+// handleTLS captures the full ClientHello record, computes JA4, completes the
+// handshake, then greets with the ClientHello (raw + JA4) and echoes over TLS.
+func (s *Server) handleTLS(conn net.Conn, first []byte, rec ConnRecord) {
+	// Read the rest of the record header (version[2], length[2]) and the body.
+	hdr := make([]byte, 4)
+	if _, err := io.ReadFull(conn, hdr); err != nil {
+		return
+	}
+	recLen := int(hdr[2])<<8 | int(hdr[3])
+	body := make([]byte, recLen)
+	if _, err := io.ReadFull(conn, body); err != nil {
+		return
+	}
+	full := append(append(append([]byte{}, first...), hdr...), body...)
+
+	rec.TLS = true
+	if h, ok := parseClientHello(full); ok {
+		rec.JA4 = ja4(h)
+	}
+
+	// Replay the captured ClientHello into the TLS server.
+	cfg := s.TLSConfig.Clone()
+	cfg.NextProtos = append([]string{"elt-echo"}, cfg.NextProtos...)
+	tconn := tls.Server(&prefixConn{Conn: conn, prefix: full}, cfg)
+	if err := tconn.Handshake(); err != nil {
+		return
+	}
+	rec.ALPN = tconn.ConnectionState().NegotiatedProtocol
 	s.record(rec)
 
 	greeting, _ := json.Marshal(map[string]any{
 		"observed_src":    rec.Src,
 		"mss":             rec.MSS,
 		"options":         rec.Options,
+		"tls":             true,
+		"alpn":            rec.ALPN,
+		"ja4":             rec.JA4,
+		"clienthello_b64": base64.StdEncoding.EncodeToString(full),
 	})
-	if _, err := conn.Write(append(greeting, '\n')); err != nil {
+	if _, err := tconn.Write(append(greeting, '\n')); err != nil {
 		return
 	}
-	// Byte-echo until FIN; the client's data is its own to interpret.
-	_, _ = io.Copy(conn, conn)
+	_, _ = io.Copy(tconn, tconn)
 }

server/internal/tcpecho/tcpecho_test.go

@@ -0,0 +1,53 @@
+// SPDX-FileCopyrightText: 2026 Echolot contributors
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+package tcpecho
+
+import (
+	"bufio"
+	"encoding/json"
+	"net"
+	"testing"
+	"time"
+)
+
+// Plain echo must be server-speaks-first: a client that sends nothing still
+// gets the greeting (via the peek timeout), then its bytes are echoed.
+func TestPlainEchoServerSpeaksFirst(t *testing.T) {
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer ln.Close()
+	go (&Server{}).Serve(ln)
+
+	c, err := net.Dial("tcp", ln.Addr().String())
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer c.Close()
+	c.SetDeadline(time.Now().Add(3 * time.Second))
+
+	line, err := bufio.NewReader(c).ReadBytes('\n')
+	if err != nil {
+		t.Fatalf("no greeting: %v", err)
+	}
+	var g struct {
+		TLS bool `json:"tls"`
+		Src string `json:"observed_src"`
+	}
+	if err := json.Unmarshal(line, &g); err != nil {
+		t.Fatal(err)
+	}
+	if g.TLS {
+		t.Fatal("plain connection reported tls=true")
+	}
+	if g.Src == "" {
+		t.Fatal("greeting missing observed_src")
+	}
+	c.Write([]byte("xyz"))
+	buf := make([]byte, 3)
+	if _, err := c.Read(buf); err != nil || string(buf) != "xyz" {
+		t.Fatalf("echo failed: %q %v", buf, err)
+	}
+}