# Phase 3 MQTT security for the shared Mosquitto > **APPLIED 2026-10-13 (AUD-80).** The shared Mosquitto on `.13` now runs the > 8883 listener below next to its original anonymous `1883` listener, and the > Control Service connects over TLS with credentials. Backups: > `/home/sam/Docker/Containers/mosquitto/mosquitto.conf.bak.aud80-20261013-152648` > and `docker-compose.yml.bak.aud80-20261013-152648`. See "What was changed on > `.13`" at the end of this file. This directory holds the **broker-side** half of Phase 3 (AGENTS.md §11, §10 rule 6; `TRANSPORT_DESIGN.md` "Security"). The Go half lives in `internal/mqtt/`. The transport itself — retained config per device, status and telemetry subscriptions, LWT presence — is implemented and running against the shared Mosquitto on `.13:1883`. What follows is the credential and TLS layer that onboards the kids' devices. ## What is here | File | What it is | |---|---| | `conf.d/webrestrict.conf` | the TLS listener on 8883 with authentication | | `conf.d/webrestrict.acl` | the topic ACL: one device, one topic set | | `conf.d/webrestrict.passwd` | **generated** hashed accounts (gitignored) | | `generate-tls.sh` | builds the lab CA and the broker certificate | | `build-config.sh` | writes the scratch broker config used by the verifier | | `provision-clients.sh` | creates one broker account per registered device | | `verify-isolation.sh` | proves the ACL on a throwaway broker | | `clients.env` | **generated** device credentials (gitignored) | ## The design Two listeners on the one broker. No second broker (§10 rule 6), no router change, no DNS change. | Listener | Auth | Who uses it | |---|---|---| | `1883` (existing, unchanged) | anonymous | n8n and the rest of the lab | | `8883` (new, TLS) | required account | the kids' devices and the Control Service | `per_listener_settings true` is what keeps the two planes apart: the plain listener stays anonymous, the TLS listener requires credentials. It must appear in the main `mosquitto.conf` **before the first `listener` line**. ### Topic ACL ```acl user control-service topic write restrict/+/config topic read restrict/+/status topic read restrict/+/telemetry pattern read restrict/%u/config pattern write restrict/%u/status pattern write restrict/%u/telemetry ``` - Only the Control Service publishes config (§10 rule 5). It cannot read config and cannot write status or telemetry. - A device's MQTT username **is** its topic token — the middle level of its config topic. For `restrict/harry_phone_2/config` the account is `harry_phone_2`. - `%u` expands to that username, so a device can only ever touch its own topics. Adding a device is therefore one account, no ACL edit. - A device publishing to its own config topic is dropped by the broker, so a child cannot publish a fake "unlocked". List the tokens the Control Service expects: ```bash docker exec webrestrict-control /app/control mqtt-clients ``` ## Prove it without touching anything shared ```bash make mqtt-verify # TLS + CA + scratch broker on 127.0.0.1:18883 ``` `verify-isolation.sh` stages a throwaway copy of the config, runs its own Mosquitto container on a spare port, and asserts the whole policy: the plain listener is still anonymous, the TLS listener rejects anonymous clients and a wrong password, a device reads only its own config, writes only its own status and telemetry, cannot write another device's topics, and **cannot overwrite its own config to fake an unlock**. ## Applying it (approval required first) Applying it changes files outside this project (`mosquitto.conf` and the Mosquitto `docker-compose.yml`), adds port 8883 to a family-facing service, and restarts that service — a change to a shared household service, so it needs Sam's approval first. Everything below is additive and a backup is taken before anything is written. ```bash # 1. Credentials and certificates. docker exec webrestrict-control /app/control mqtt-clients # tokens, no secrets deploy/mosquitto/provision-clients.sh # writes conf.d/webrestrict.passwd + clients.env make mqtt-tls # writes tls/{ca,server}.{crt,key} # 2. Copy the material into the shared broker's config directory. BROKER_DIR=/home/sam/Docker/Containers/mosquitto sudo -u sam cp "$BROKER_DIR/mosquitto.conf" \ "$BROKER_DIR/mosquitto.conf.bak.$(date +%Y%m%d-%H%M%S)" install -d -m 755 "$BROKER_DIR/conf.d" "$BROKER_DIR/tls" install -m 644 deploy/mosquitto/conf.d/webrestrict.conf "$BROKER_DIR/conf.d/" install -m 644 deploy/mosquitto/conf.d/webrestrict.acl "$BROKER_DIR/conf.d/" install -m 644 deploy/mosquitto/conf.d/webrestrict.passwd "$BROKER_DIR/conf.d/" install -m 644 deploy/mosquitto/tls/* "$BROKER_DIR/tls/" # then add to mosquitto.conf (leave `listener 1883 0.0.0.0` and # `allow_anonymous true` exactly as they are): # per_listener_settings true (before the first listener) # include_dir /mosquitto/config/conf.d # 3. Mount the new directories, publish 8883, restart, bounded. # The shared compose mounts mosquitto.conf as a single file, so the new # directories need their own lines or the broker will not start # ("Error: Unable to open include_dir"). Add to the mosquitto service: # # ports: # - "8883:8883" # volumes: # - /home/sam/Docker/Containers/mosquitto/conf.d:/mosquitto/config/conf.d:ro # - /home/sam/Docker/Containers/mosquitto/tls:/mosquitto/config/tls:ro # # then: cd "$BROKER_DIR" timeout 120 docker compose up -d timeout 30 docker logs --tail 20 mosquitto # expect both listeners to open # 4. Prove the plain plane still works (n8n depends on it). timeout 40 docker run --rm --network host --entrypoint sh eclipse-mosquitto:latest -c \ 'mosquitto_sub -h 127.0.0.1 -p 1883 -t lab/after -C 1 -W 10 & sleep 1; \ mosquitto_pub -h 127.0.0.1 -p 1883 -t lab/after -m ok; wait' # 5. Point the Control Service at TLS. # environment.d/control-service.env: # CONTROL_MQTT_BROKER=tls://host.docker.internal:8883 # CONTROL_MQTT_INSECURE=false # CONTROL_MQTT_USERNAME=control-service # CONTROL_MQTT_PASSWORD= timeout 120 docker compose up -d --build timeout 30 docker logs --tail 30 webrestrict-control # expect "mqtt connected" over tls ``` ### Notes from the live apply (2026-10-13) - The broker logs `The 'per_listener_settings' option is now deprecated and will be removed in version 3.0` and the matching `allow_anonymous` notice. It still works on the `eclipse-mosquitto:latest` image, which is 2.1.0.1 today. `per_listener_settings true` is kept because it is the only way on 2.1.0 to give the two listeners different `password_file`/`acl_file` values: the per-listener `listener_*` prefix exists only for `allow_anonymous`. **Pin the image tag before Mosquitto 3.0 arrives**, or rework the two planes. - The bind mounts in step 3 are not optional. The shared compose mounts `mosquitto.conf` as a single file, so `include_dir` fails without them and the broker restart-loops. - The password file and the TLS key are installed mode 0644 because the broker runs as uid 1883 and that user does not exist on the host. See `tls/README.md`. ### Roll back ```bash cd /home/sam/Docker/Containers/mosquitto cp mosquitto.conf.bak.aud80- mosquitto.conf cp docker-compose.yml.bak.aud80- docker-compose.yml rm -rf conf.d tls timeout 120 docker compose up -d ``` Rolling back the broker needs no change in this project: set `CONTROL_MQTT_INSECURE=true` and `CONTROL_MQTT_BROKER=tcp://host.docker.internal:1883` in `environment.d/control-service.env` and restart the service. ## What was changed on `.13` (2026-10-13) Files outside this project were edited for the first time. The backup copies are listed above; everything is additive. `/home/sam/Docker/Containers/mosquitto/mosquitto.conf` — the two original lines (`listener 1883 0.0.0.0`, `allow_anonymous true`) are untouched: ```diff log_dest file /mosquitto/log/mosquitto.log + +# Internet Use Control (AUD-80). Two listeners, two auth planes. Mosquitto +# requires per_listener_settings before the first listener, and it is what keeps +# the 1883 listener below anonymous while 8883 requires an account. +per_listener_settings true + listener 1883 0.0.0.0 allow_anonymous true # IMPORTANT: For production, configure authentication (username/password) + +# Internet Use Control device plane (AUD-80): TLS on 8883, account required, +# topic ACL. Roll back by deleting this line and the conf.d directory. +include_dir /mosquitto/config/conf.d ``` `/home/sam/Docker/Containers/mosquitto/docker-compose.yml`: ```diff ports: - "1883:1883" # Standard MQTT port + - "8883:8883" # Internet Use Control device plane (TLS, AUD-80) - "9001:9001" # Websockets port (optional, good for web clients) volumes: - /home/sam/Docker/Containers/mosquitto/mosquitto.conf:/mosquitto/config/mosquitto.conf:ro + - /home/sam/Docker/Containers/mosquitto/conf.d:/mosquitto/config/conf.d:ro + - /home/sam/Docker/Containers/mosquitto/tls:/mosquitto/config/tls:ro - /home/sam/Docker/Containers/mosquitto/data:/mosquitto/data - /home/sam/Docker/Containers/mosquitto/log:/mosquitto/log ``` New on the host, copied from this directory: `conf.d/webrestrict.{conf,acl,passwd}` and `tls/{ca.crt,server.crt,server.key}`. `environment.d/control-service.env` in this project now points at `tls://host.docker.internal:8883` with the `control-service` account and `CONTROL_MQTT_INSECURE=false`. Verified on the live broker after the restart: the `1883` plane still carries anonymous traffic, `8883` refuses anonymous clients and a wrong password, each device reads only its own retained config, a device's write to another device's status and to its own config is dropped, and a client killed without DISCONNECT drove the retained will into an offline transition in the Control Service.