# AGENTS.md

Single-node, self-hosted OpenTunnel-compatible server in Go. The wire
protocol and API contract are **the reference's**, not ours to invent:

- Source of truth: `.reference/opentunnel/docs/protocol.md`
- API contract: `.reference/opentunnel/crates/opentunnel-server/tests/fixtures/worker-contract.json`
  (paths, status codes, bodies, JSON key order — installed clients depend on it)
- Conformance vectors: `.reference/opentunnel/spec/vectors/*.json`, run by
  `internal/server/*_test.go` (the reference checkout must exist; tests skip
  otherwise)

`.reference/` is untracked research input (see `.reference/opentunnel.md` for
what we take vs. skip). Never vendor it into the build.

## Layout

- `cmd/tunneld` — flags/env wiring, listeners, signal handling
- `internal/server/proto.go` — wire types (pinned JSON key order), IDs/tokens
  (same generation as the reference: 12-char base32 slugs, `rly_` tokens,
  hex SHA-256 token hashes), route validation, data frames
- `internal/server/clienthello.go` — TLS ClientHello parser (SNI + ALPN) that
  reads exact bytes only, so the connection can be replayed or forwarded
- `internal/server/localca.go` — the built-in insecure CA (the reference's
  `ISSUER=local` equivalent); signs tunnel CSRs after checking CN == hostname
  and SANs ⊆ {hostname, `*.hostname`}
- `internal/server/store.go` — JSON-file store (0600, atomic rename); single
  writer, self-hosted scale
- `internal/server/api.go` — HTTP API per the contract; tunnel existence is
  checked before auth (404 before 401), body JSON syntax before everything
- `internal/server/bridge.go` — WebSocket bridge sessions: attach, route
  claiming (one owner per route), heartbeats, idle retirement, visitor pumps
- `internal/server/relay.go` — public TLS listener: parses the ClientHello,
  terminates the domain itself, passes tunnel hostnames to bridges untouched

## Commands

- `go build ./...` / `go vet ./...` / `gofmt -l .` — must stay clean
- `go test ./...`
- Dev loop: `go build -o .local/tunneld ./cmd/tunneld && .local/tunneld -domain localhost`,
  then `OPENTUNNEL_API=http://localhost:8080 opentunnel route add 4096 --name api`
  with the official CLI. `go build` drops a binary next to the source — it is
  gitignored; prefer `-o .local/`.

## Gotchas

- **macOS system curl (LibreSSL) does not send SNI for `*.localhost` names**,
  so `curl https://api.<id>.localhost:8443/` gets closed (the relay requires
  SNI). Test with `openssl s_client -servername ...` or Homebrew curl.
- JSON key order of API bodies is contractual — always `json.Marshal` structs
  with declared field order, never maps.
- Bridge writes go through one ordered `outbox` channel per session. Control
  messages therefore can queue behind data — a known M1 deviation from the
  reference's deadlock-avoidance; a stalled visitor self-heals via the
  client's idle timeout. Revisit with per-connection flow control.
- The bridge WebSocket must use `coder/websocket` with compression disabled
  and the `opentunnel` subprotocol; read limits are 64 KiB before attach and
  4+32 KiB after.
- No third-party deps beyond `github.com/coder/websocket`; keep it that way
  unless a milestone calls for it.
- Milestones: M1 core data path (done); M2 real ACME DNS-01 + renewals; M3
  rate limits/admin/hardening; M4 maybe a Go client. Don't pull M2+ scope
  into M1 fixes.