flying-jib/agent/ADRs/0005-local-only-bind-invariant.md

ADR-0005: Local-only bind invariant

• Status: Accepted
• Date: 2026-07-30

Context

minecraft-protocol createServer defaults host to undefined, which listens on all interfaces. Accidental WAN exposure of Squid would violate the product security model and user expectations (“P2P app, not open server”).

Decision

1. Every Squid start must pass host: '127.0.0.1'.
2. Post-listen verification asserts loopback.
3. Automated tests cover the config writer and bind guard.
4. No product feature may enable public MC TCP listen.

Remote access is only via encrypted HyperDHT tunnels to that loopback port.

Consequences

Positive

• Clear security boundary
• Java clients remain simple (always localhost)

Negative / tradeoffs

• LAN-only play without the app tunnel requires using the tunnel or a future explicit advanced mode (not planned as open bind)

Follow-ups

• Phase 1 bind-guard test
• Document in SECURITY.md (done)