gateway pairing

flow

1. gateway starts, prints 6-digit pairing code to terminal
2. client sends code via POST /pair with X-Pairing-Code header
3. server validates with constant-time comparison (no timing leaks)
4. server responds with bearer token (bh_ prefix)
5. all subsequent requests require Authorization: Bearer bh_...

brute force protection

5 wrong attempts triggers a 5-minute lockout. this is enforced server-side, not client-side.

constant-time comparison

the pairing code comparison iterates max(a.len, b.len) and pads with zeros so timing is flat regardless of how many characters match. this prevents timing attacks that could leak the code one digit at a time.

network binding

• default: 127.0.0.1 (localhost only)
• refuses 0.0.0.0 unless a tunnel is configured or allow_public_bind = true
• when using cloudflare/tailscale/ngrok tunnel, public binding is safe because traffic is authenticated at the tunnel layer