Relay tunnel TLS certificate never provisions — "Waiting for trusted TLS certificate" indefinitely

[eatinhamson]

Environment

• hapi version: 0.16.7 (latest)
• OS: macOS (Apple Silicon)
• Tunnel binary: tunwg (bundled)

Problem

The hub starts fine with --relay and tunwg successfully connects to relay.hapi.run, receiving a subdomain assignment:

[Tunnel] 2026/04/19 16:29:16 tunwg: http://localhost:3006 <= https://4a2pcn2nq4lay4c4.relay.hapi.run

However, the TLS certificate for the subdomain never provisions. The log loops indefinitely with:

[Tunnel] Waiting for trusted TLS certificate...
[Tunnel] 2026/04/19 16:29:00 tunwg: initiating handshake to server
[Tunnel] Waiting for trusted TLS certificate...

The root domain relay.hapi.run has valid TLS. The subdomain does not — curl confirms:

$ curl -sv https://4a2pcn2nq4lay4c4.relay.hapi.run/health
* LibreSSL SSL_connect: SSL_ERROR_SYSCALL in connection to 4a2pcn2nq4lay4c4.relay.hapi.run:443

Impact

• The PWA (phone) shows "Failed to fetch" on every interaction since it can't establish HTTPS to the hub
• Push notifications still work (they use VAPID/web-push, bypassing the tunnel)
• Hub is fully functional on localhost — only the relay tunnel is broken
• Multiple hub restarts produce the same subdomain and the same stuck state

Steps to Reproduce

1. Install hapi 0.16.7
2. Run hapi hub --relay
3. Observe Waiting for trusted TLS certificate... looping in stdout
4. Attempt to curl the assigned *.relay.hapi.run subdomain — SSL_ERROR_SYSCALL

Expected Behavior

The relay should provision a valid TLS certificate for the assigned subdomain so the PWA can connect over HTTPS.

[github-actions]

Thanks for the detailed report. From the current code path, the local hub is not provisioning the certificate itself; it starts tunwg, waits for a ready event with the assigned URL, then repeatedly opens a TLS connection to that assigned HTTPS host until the certificate is trusted, time-valid, and matches the hostname.

So the repeated Waiting for trusted TLS certificate... line means the hub already has a tunnel URL, but waitForTunnelTlsReady() is still failing the TLS readiness check. I did not find a local hub code path that can create/repair the *.relay.hapi.run certificate after that point.

One local diagnostic worth trying is TCP relay mode, since relay docs mention it for connectivity issues:

HAPI_RELAY_FORCE_TCP=true hapi hub --relay

That does not bypass certificate validation; it only changes the relay transport mode passed to tunwg.

Relevant code:

• hub/src/index.ts:112 - default relay API domain is relay.hapi.run unless HAPI_RELAY_API is set.
• hub/src/index.ts:233 - relay mode creates TunnelManager after the local web server is already listening.
• hub/src/index.ts:250 - public URL / QR output is delayed until waitForTunnelTlsReady() succeeds.
• hub/src/tunnel/tunnelManager.ts:127 - hub starts bundled tunwg with --json --forward=http://localhost:<port>.
• hub/src/tunnel/tunnelManager.ts:160 - hub treats tunwg JSON ready event as the source of the tunnel URL.
• hub/src/tunnel/tlsGate.ts:116 - TLS readiness check opens a TLS socket to the assigned host.
• hub/src/tunnel/tlsGate.ts:145 - readiness fails if Node does not authorize the certificate.
• hub/src/tunnel/tlsGate.ts:154 - readiness also checks hostname and certificate validity period.
• hub/src/tunnel/tlsGate.ts:188 - polling continues while the tunnel process stays connected.
• hub/src/tunnel/tlsGate.ts:195 - this is the log line you are seeing.
• docs/guide/installation.md:143 - HAPI_RELAY_FORCE_TCP=true documented as relay connectivity fallback.

Need more info:

• Does HAPI_RELAY_FORCE_TCP=true hapi hub --relay change the behavior?
• Full hub log from process start through at least two Waiting for trusted TLS certificate... messages.
• Whether the same assigned subdomain still fails from another network/device with curl -sv https://<subdomain>.relay.hapi.run/health.

---

HAPI Bot