tunnel/AGENTS.md

# 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/admin.go` + `dashboard.html` — the admin dashboard served
  at `/` (embedded HTML, no build step) and `GET /api/admin/overview`, both
  behind the `ADMIN_TOKEN` bearer token (503 when unset, 401 when wrong)
- `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

- **Coolify deployment** (verified 2026-10-25): app `nokzgyrlhuuzduozr7yts4z3`
  in project Personal, `https://tunnel.tzgyn.dev`, deploy-key source on the
  shared `gitea` key, push to `main` auto-deploys via the Gitea webhook.
  Redeploy with `POST /api/v1/deploy?uuid=<app>` (the GET form is gone).
  Webhook details when debugging: Coolify's *manual* Gitea webhook verifies
  `X-Hub-Signature-256` (HMAC-SHA256 hex of the raw body with the app's
  `manual_webhook_secret_gitea`; Gitea sends this header natively) and
  matches apps by `repository.full_name` against the app's `git_repository`
  after canonicalization — the `:22222` port in the scp-style URL is ignored,
  so it matches fine. A curl replay needs `X-Gitea-Event: push` and the
  signature header, or it answers "No matching application or invalid
  signature."
  Coolify's audit log (MCP `list_audit_events`, `source=webhook`) is the
  debugging oracle: `webhook.deployment.queued` = authenticated and queued,
  `webhook.gitea.signature_failed` = the Gitea hook's secret does not match
  the app's current `manual_webhook_secret_gitea`.
  **Gitea's hook edit API does not update the stored secret** — PATCHing the
  hook returns 200 but deliveries keep failing signature checks; delete the
  hook and create a fresh one with the secret instead (current hook: id 6,
  branch_filter `main`). The app's secret is regenerated whenever the app is
  recreated, so recreate the hook after any app recreation.
  Coolify's webhook deploy pins the pushed commit (`git fetch origin <sha>`),
  and this Gitea only serves the *current tip* by SHA
  (`uploadpack.allowReachableSHA1InWant` is off; other SHAs fail with
  "not our ref"). Deploys fail if a later push lands before the fetch —
  re-trigger the deploy. Proper fix, inside the Gitea container:
  `git -C /data/git/repositories/TZGyn/tunnel.git config
  uploadpack.allowReachableSHA1InWant true`.
  This Coolify version stores `custom_labels` **base64-encoded** and does
  *not* merge its generated Traefik labels for API-created apps: the full
  label set must live in `custom_labels` (mirror a working app's generated
  format — http/https routers with `certresolver=letsencrypt` — plus the TCP
  passthrough lines). Deployment JSON from the API can break `jq` (invalid
  escapes in the logs field) — parse with python instead.
- **Deployment**: the multi-stage `Dockerfile` builds a static non-root
  alpine image; verify `CGO_ENABLED=0 go build -trimpath -ldflags="-s -w"
  ./cmd/tunneld` after changing build-affecting code (no Docker runtime on
  the dev machine). Tunnel visitor traffic must reach the SNI listener
  without TLS termination (raw TCP, or a Traefik **TCP passthrough** router);
  the API domain may sit behind a TLS-terminating proxy. On a
  Coolify-managed host (Traefik owns 443/80): API = app domain → container
  :8080 with `HTTP_MODE=serve`; tunnel traffic = custom Traefik TCP labels
  (`HostSNIRegexp` + `tls.passthrough=true`) → container :8443. See README
  "Deploy on Coolify".

- **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.