Phase 3: MQTT transport — retained config, status/telemetry, LWT presence, TLS/ACL design

- internal/mqtt: publish each device's desired state retained on
  restrict/<device>/config; subscribe to restrict/+/status and
  restrict/+/telemetry and write reports to SQLite; publish on every state
  change, republish on connect and every 15 minutes from SQLite, so the broker
  is repaired from the source of truth.
- store: presence (devices.online and last_seen, audited only on transitions),
  telemetry upsert per (device, day, app, domain) via migration 002, allow and
  block lists read into the config payload, device lookup by topic.
- config: MQTT settings. TLS plus per-device credentials are required; the
  pre-TLS shared broker needs an explicit CONTROL_MQTT_INSECURE escape hatch.
- web: republish config after lock, unlock, expiry, create and edit; broker card
  on the status partial.
- deploy/mosquitto: TLS listener, topic ACL, credential provisioning and a
  verifier that proves the policy on a throwaway broker. Not applied to the
  shared Mosquitto on .13 — that change needs Sam's approval.
- cmd/control: mqtt-clients prints the MQTT identity of every device.
- paho.mqtt.golang v1.5.1, which pulls golang.org/x/net and with it the
  golang.org/x/crypto bump to v0.42.0.

Verified on .13: retained config delivered to a fresh subscriber; a client
killed without DISCONNECT drove the broker's retained will and the service
flipped the device offline; telemetry landed in SQLite; make mqtt-verify passed
13/13; the service connected over TLS with credentials and a CA.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

internal/config/config.go

@@ -37,6 +37,25 @@ type Config struct {
 	AppEnv string
 	// Version is injected at build time.
 	Version string
+
+	// MQTTEnabled turns the broker link on. When false the service runs
+	// HTTP-only and never touches the broker.
+	MQTTEnabled bool
+	// MQTTBroker is the broker URL, for example "tls://mosquitto:8883" or
+	// "tcp://127.0.0.1:1883".
+	MQTTBroker string
+	// MQTTClientID is the MQTT client id of the Control Service.
+	MQTTClientID string
+	// MQTTUsername and MQTTPassword are the Control Service credentials
+	// (AGENTS.md §10 rule 6: per-device credentials).
+	MQTTUsername string
+	MQTTPassword string
+	// MQTTCAFile is the PEM bundle used to verify the broker certificate.
+	MQTTCAFile string
+	// MQTTInsecure allows a plaintext, credential-less broker link. It exists
+	// only until the shared Mosquitto gets the TLS listener; never set it in
+	// production.
+	MQTTInsecure bool
 }
 
 // Load reads and validates the configuration.
@@ -49,6 +68,13 @@ func Load() (*Config, error) {
 		AdminPasswordHash: os.Getenv("CONTROL_ADMIN_PASSWORD_HASH"),
 		CookieSecure:      envBool("CONTROL_COOKIE_SECURE", true),
 		AppEnv:            env("CONTROL_APP_ENV", "production"),
+		MQTTEnabled:       envBool("CONTROL_MQTT_ENABLED", true),
+		MQTTBroker:        env("CONTROL_MQTT_BROKER", DefaultMQTTBroker),
+		MQTTClientID:      env("CONTROL_MQTT_CLIENT_ID", "control-service"),
+		MQTTUsername:      os.Getenv("CONTROL_MQTT_USERNAME"),
+		MQTTPassword:      os.Getenv("CONTROL_MQTT_PASSWORD"),
+		MQTTCAFile:        env("CONTROL_MQTT_CA_FILE", "/etc/webrestrict/tls/ca.crt"),
+		MQTTInsecure:      envBool("CONTROL_MQTT_INSECURE", false),
 	}
 
 	secret := os.Getenv("CONTROL_SESSION_SECRET")
@@ -76,9 +102,45 @@ func Load() (*Config, error) {
 	}
 	cfg.LogLevel = lvl
 
+	if err := cfg.validateMQTT(); err != nil {
+		return nil, err
+	}
+
 	return cfg, nil
 }
 
+// DefaultMQTTBroker is where the shared Mosquitto on `.13` lives, as seen from
+// inside this project's container. The compose file maps host.docker.internal
+// to the host gateway.
+const DefaultMQTTBroker = "tcp://host.docker.internal:1883"
+
+// MQTTTLS reports whether the broker URL asks for TLS.
+func (c *Config) MQTTTLS() bool {
+	return strings.HasPrefix(c.MQTTBroker, "tls://") || strings.HasPrefix(c.MQTTBroker, "ssl://")
+}
+
+// validateMQTT refuses a link that carries neither TLS nor credentials, unless
+// CONTROL_MQTT_INSECURE explicitly allows it (AGENTS.md §10 rule 6).
+func (c *Config) validateMQTT() error {
+	if !c.MQTTEnabled {
+		return nil
+	}
+	if c.MQTTBroker == "" {
+		return errors.New("CONTROL_MQTT_BROKER must not be empty when MQTT is enabled")
+	}
+	if c.MQTTUsername == "" || c.MQTTPassword == "" {
+		if !c.MQTTInsecure {
+			return errors.New("CONTROL_MQTT_USERNAME and CONTROL_MQTT_PASSWORD are required; " +
+				"set CONTROL_MQTT_INSECURE=true only for the pre-TLS lab broker")
+		}
+	}
+	if !c.MQTTTLS() && !c.MQTTInsecure {
+		return errors.New("CONTROL_MQTT_BROKER must use tls:// (AGENTS.md §10 rule 6); " +
+			"set CONTROL_MQTT_INSECURE=true only for the pre-TLS lab broker")
+	}
+	return nil
+}
+
 func env(key, fallback string) string {
 	if v := strings.TrimSpace(os.Getenv(key)); v != "" {
 		return v

internal/config/config_test.go

@@ -11,6 +11,9 @@ func TestLoadDefaultsAndValidation(t *testing.T) {
 	t.Setenv("CONTROL_ADMIN_PASSWORD", "hunter2")
 	t.Setenv("CONTROL_ADDR", "")
 	t.Setenv("CONTROL_DB_PATH", "")
+	// The lab broker has no TLS listener yet, so the pre-TLS escape hatch is
+	// the current deployment default (see CONTROL_MQTT_INSECURE).
+	t.Setenv("CONTROL_MQTT_INSECURE", "true")
 
 	cfg, err := Load()
 	if err != nil {
@@ -50,3 +53,56 @@ func TestLoadRequiresSecretAndPassword(t *testing.T) {
 		t.Error("expected error when no admin password is set")
 	}
 }
+
+func TestMQTTDefaultsAndGuards(t *testing.T) {
+	t.Setenv("CONTROL_SESSION_SECRET", "0123456789abcdef")
+	t.Setenv("CONTROL_ADMIN_PASSWORD", "hunter2")
+
+	// Enabled by default, pointed at the shared Mosquitto on `.13`.
+	t.Setenv("CONTROL_MQTT_INSECURE", "true")
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if !cfg.MQTTEnabled {
+		t.Error("MQTTEnabled = false, want true by default")
+	}
+	if cfg.MQTTBroker != DefaultMQTTBroker {
+		t.Errorf("MQTTBroker = %q, want %q", cfg.MQTTBroker, DefaultMQTTBroker)
+	}
+	if cfg.MQTTTLS() {
+		t.Error("MQTTTLS = true for the default plaintext broker, want false")
+	}
+
+	// Without the escape hatch, a plaintext credential-less broker is refused
+	// (AGENTS.md §10 rule 6).
+	t.Setenv("CONTROL_MQTT_INSECURE", "false")
+	if _, err := Load(); err == nil {
+		t.Error("expected an error for a plaintext broker without CONTROL_MQTT_INSECURE")
+	}
+
+	// TLS plus credentials is the supported shape.
+	t.Setenv("CONTROL_MQTT_BROKER", "tls://mosquitto.lab.audasmedia.com.au:8883")
+	t.Setenv("CONTROL_MQTT_USERNAME", "control-service")
+	t.Setenv("CONTROL_MQTT_PASSWORD", "secret")
+	cfg, err = Load()
+	if err != nil {
+		t.Fatalf("Load with TLS: %v", err)
+	}
+	if !cfg.MQTTTLS() {
+		t.Error("MQTTTLS = false for a tls:// broker, want true")
+	}
+
+	// MQTT can be switched off entirely.
+	t.Setenv("CONTROL_MQTT_ENABLED", "false")
+	t.Setenv("CONTROL_MQTT_BROKER", "")
+	t.Setenv("CONTROL_MQTT_USERNAME", "")
+	t.Setenv("CONTROL_MQTT_PASSWORD", "")
+	cfg, err = Load()
+	if err != nil {
+		t.Fatalf("Load with MQTT disabled: %v", err)
+	}
+	if cfg.MQTTEnabled {
+		t.Error("MQTTEnabled = true, want false when CONTROL_MQTT_ENABLED=false")
+	}
+}