From cce6a4960ed2b1f722e69763227d7b6b6935d771 Mon Sep 17 00:00:00 2001 From: Jonas Bengtsson Date: Tue, 15 Sep 2026 21:32:30 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=8E=89=20Initial=20commit?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- specification.md | 2312 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 2312 insertions(+) create mode 100644 specification.md diff --git a/specification.md b/specification.md new file mode 100644 index 0000000..69b140f --- /dev/null +++ b/specification.md @@ -0,0 +1,2312 @@ +# MQTT Management Platform + +## Service Specification + +**Status:** Initial specification +**Target deployment:** Docker Compose / Portainer Stack +**Primary broker:** Eclipse Mosquitto 2.1.x +**Architecture:** Mosquitto + custom backend + custom frontend + PostgreSQL + +--- + +# 1. Purpose + +The purpose of the platform is to provide a centrally managed MQTT broker environment based on Eclipse Mosquitto together with a web-based administration interface. + +The platform shall provide administrators with a controlled interface for: + +* managing the MQTT broker; +* configuring listeners and broker behaviour; +* managing MQTT client authentication; +* managing MQTT client authorization and ACLs; +* generating and managing certificates; +* configuring TLS and mutual TLS; +* managing application administrators and operators; +* monitoring broker state; +* testing MQTT connectivity and permissions; +* auditing configuration and security changes; +* versioning and rolling back broker configuration; +* backing up and restoring configuration. + +The management interface shall remove the normal requirement to directly edit Mosquitto configuration files, ACL files or certificate files on the host. + +The system shall nevertheless generate standards-compliant Mosquitto configuration and retain the ability for an administrator to inspect the actual configuration generated by the platform. + +--- + +# 2. Design principles + +The platform shall follow the following design principles. + +## 2.1 Separation of identities + +Two distinct identity domains shall exist. + +### Management identities + +These are users of the web management platform. + +Examples: + +* Administrator +* MQTT administrator +* Certificate administrator +* Operator +* Auditor + +These users authenticate against the backend API. + +### MQTT identities + +These are devices, applications, services or people connecting to Mosquitto. + +Examples: + +* PLC gateway +* IoT sensor +* SCADA application +* historian +* Grafana collector +* integration application + +MQTT identities shall be managed separately from management users. + +--- + +# 3. Proposed technology stack + +## 3.1 Mosquitto + +Use: + +`eclipse-mosquitto:2.1.2-alpine` + +or an explicitly pinned later 2.1.x release after verification. + +The Docker image version shall always be pinned in production and shall not use `latest`. + +Mosquitto shall provide: + +* MQTT 5 +* MQTT 3.1.1 +* MQTT 3.1 where required +* TLS +* mutual TLS +* persistence +* retained messages +* Dynamic Security plugin +* `$SYS` telemetry +* optional WebSockets +* bridges +* broker control API where required + +Mosquitto 2.1.2 is currently an official supported Docker tag. + +--- + +## 3.2 Backend + +Recommended implementation: + +**Python 3.13 + FastAPI** + +Supporting libraries should include: + +* SQLAlchemy +* Alembic +* psycopg +* Pydantic +* cryptography +* Argon2id password hashing +* an MQTT 5 capable Python client +* structured logging + +The backend shall expose a versioned REST API: + +`/api/v1/...` + +OpenAPI documentation shall automatically be generated. + +--- + +## 3.3 Frontend + +Recommended implementation: + +**React + TypeScript** + +Suggested tooling: + +* Vite +* React Router +* TanStack Query +* component library suitable for administration interfaces + +The frontend shall contain no privileged credentials. + +It shall communicate exclusively with the backend REST API. + +The frontend shall not directly modify Mosquitto configuration, Dynamic Security configuration or certificate files. + +--- + +# 4. Docker architecture + +The initial stack shall contain the following services. + +```text + HTTPS + │ + ▼ + ┌─────────────────┐ + │ Frontend │ + │ React / nginx │ + └────────┬────────┘ + │ + REST API + │ + ▼ + ┌─────────────────┐ + │ Backend │ + │ FastAPI │ + └───┬────┬────┬──┘ + │ │ │ + │ │ └──────────────┐ + │ │ │ + │ ▼ ▼ + │ PostgreSQL Broker Control + │ / config agent + │ + ▼ + MQTT administration + │ + ▼ + ┌───────────────┐ + │ Mosquitto │ + │ MQTT Broker │ + └───────────────┘ +``` + +Required services: + +```text +mqtt-frontend +mqtt-backend +mqtt-db +mosquitto +mosquitto-control +``` + +Optional future services: + +```text +reverse-proxy +prometheus +grafana +loki +postgres-backup +``` + +--- + +# 5. Docker networks + +At minimum two networks shall exist. + +## 5.1 frontend-net + +Contains: + +* frontend +* backend + +## 5.2 backend-net + +Contains: + +* backend +* PostgreSQL +* Mosquitto management interface +* Mosquitto control service + +PostgreSQL shall not expose its port to the host by default. + +The Mosquitto management/control interface shall not be externally accessible. + +The normal MQTT listener may be exposed externally. + +Example: + +```text +8883/tcp MQTT TLS +1883/tcp optional MQTT plaintext +9001/tcp optional MQTT WebSocket +``` + +Plaintext port 1883 should be disabled by default in production. + +--- + +# 6. Persistent storage + +Separate Docker volumes shall be used. + +```text +mqtt_db_data +mosquitto_data +mosquitto_config +mosquitto_certs +mosquitto_logs +mqtt_backend_data +``` + +The following information shall persist across container restarts: + +* PostgreSQL database; +* Mosquitto persistence database; +* active Mosquitto configuration; +* Dynamic Security configuration; +* CA certificates; +* server certificates; +* encrypted private keys where applicable; +* CRLs; +* configuration revisions; +* audit information. + +--- + +# 7. Environment configuration + +A `.env` file may be supported for development. + +Production installations should support Docker secrets for sensitive values. + +Example configuration: + +```env +APP_NAME=MQTT Management +APP_ENV=production + +ADMIN_INITIAL_USERNAME=admin +ADMIN_INITIAL_PASSWORD=change-me + +DATABASE_NAME=mqttadmin +DATABASE_USER=mqttadmin +DATABASE_PASSWORD=change-me + +SESSION_SECRET=change-me +SECRET_ENCRYPTION_KEY=change-me + +MOSQUITTO_HOST=mosquitto +MOSQUITTO_PORT=8883 + +MOSQUITTO_DYNSEC_USERNAME=admin +MOSQUITTO_DYNSEC_PASSWORD=change-me + +DEFAULT_TLS_MIN_VERSION=TLSv1.2 +DEFAULT_CERT_VALIDITY_DAYS=365 +DEFAULT_CA_VALIDITY_DAYS=3650 +``` + +Mosquitto 2.1 supports the `MOSQUITTO_DYNSEC_PASSWORD` environment variable for initial Dynamic Security administration setup. + +## 7.1 Initial application administrator + +`ADMIN_INITIAL_PASSWORD` shall only be used during initial backend bootstrap. + +The backend shall: + +1. determine whether an administrator already exists; +2. create the administrator only if none exists; +3. hash the password using Argon2id; +4. never persist the plaintext password; +5. require password change after first login. + +Once initialization has completed, changing `ADMIN_INITIAL_PASSWORD` shall not automatically overwrite the administrator's password. + +## 7.2 Frontend password configuration + +No administrator password shall be compiled into the frontend. + +The requirement for an environment-configured default administrator password therefore applies to the **management application as a whole**, with the backend consuming the environment variable. + +Browser-visible frontend environment variables shall never contain: + +* passwords; +* API secrets; +* private keys; +* signing secrets; +* database credentials; +* Dynamic Security credentials. + +--- + +# 8. Management authentication + +The frontend shall authenticate management users against the backend. + +Recommended authentication mechanism: + +```text +Browser + │ + │ username/password + ▼ +Backend + │ + ├── validate credentials + ├── create session + └── return secure session cookie +``` + +Sessions should use: + +* Secure cookies; +* HttpOnly; +* SameSite; +* session expiration; +* server-side revocation. + +Authentication tokens should not normally be stored in browser `localStorage`. + +--- + +# 9. Management RBAC + +Application RBAC shall be independent of MQTT ACL configuration. + +Initial roles: + +### Super Administrator + +Full platform access. + +### Broker Administrator + +May: + +* configure Mosquitto; +* manage listeners; +* manage MQTT clients; +* manage MQTT roles/groups/ACLs; +* apply configuration. + +### PKI Administrator + +May: + +* manage CAs; +* generate certificates; +* sign CSRs; +* revoke certificates; +* generate CRLs. + +### Operator + +May: + +* view broker status; +* inspect clients; +* inspect topics; +* perform permitted diagnostic operations. + +### Auditor + +Read-only access to: + +* configuration; +* certificates; +* users; +* audit logs; +* configuration history. + +The platform shall support creation of additional custom roles in a later release. + +--- + +# 10. Mosquitto authentication and authorization + +The preferred authorization mechanism shall be the **Mosquitto Dynamic Security plugin**. + +Dynamic Security provides: + +```text +Clients + │ + ├── Groups + │ │ + │ └── Roles + │ │ + │ └── ACL rules + │ + └── Roles + │ + └── ACL rules +``` + +Mosquitto supports dynamic clients, groups, roles and ACLs while the broker is running. + +--- + +# 11. MQTT client management + +The frontend shall provide a page named: + +**Clients** + +Each MQTT client shall support metadata including: + +```text +Username +Client ID +Display name +Description +Enabled/disabled +Authentication method +Certificate identity +Groups +Direct roles +Tags +Owner +Purpose +Created timestamp +Modified timestamp +Last known connection +``` + +The user shall be able to: + +* create a client; +* disable a client; +* enable a client; +* delete a client; +* reset a password; +* generate a random password; +* assign groups; +* assign roles; +* bind an expected client ID; +* issue a client certificate; +* revoke a client certificate. + +Passwords shall never be retrievable after creation. + +--- + +# 12. MQTT groups + +The frontend shall provide a page named: + +**Groups** + +Example groups might be: + +```text +SCADA +Sensors +Gateways +Historians +Grafana +Administrators +Site-A +Site-B +``` + +A group may have: + +* name; +* display name; +* description; +* clients; +* roles; +* role priority. + +--- + +# 13. MQTT roles + +The frontend shall provide a page named: + +**Roles** + +Example: + +```text +role: site-a-sensors + +ALLOW publishClientSend +site/a/%u/telemetry/# + +ALLOW subscribePattern +site/a/%u/config/# + +ALLOW publishClientReceive +site/a/%u/config/# +``` + +The UI should present ACL rules in a table rather than requiring users to manually manipulate Mosquitto JSON. + +Mosquitto Dynamic Security supports ACL types including publishing, receiving, subscribing and unsubscribing as well as `%u` username and `%c` client-ID substitutions. + +--- + +# 14. ACL editor + +The ACL editor shall support: + +```text +ACL type +Topic filter +Allow / deny +Priority +Description +``` + +ACL types shall include: + +```text +publishClientSend +publishClientReceive +subscribeLiteral +subscribePattern +unsubscribeLiteral +unsubscribePattern +``` + +The UI shall show a human-readable interpretation. + +Example: + +```text +Client: +pumpstation-042 + +Role: +pumpstation + +ACL: +site/%u/telemetry/# + +Resolved example: +site/pumpstation-042/telemetry/# +``` + +--- + +# 15. ACL simulator + +A highly recommended feature is an **ACL simulator**. + +The administrator shall be able to enter: + +```text +Client +Client ID +Operation +Topic +``` + +Example: + +```text +client: ps042 +operation: publish +topic: vivab/ps042/status +``` + +The application shall evaluate the current role/group hierarchy and display: + +```text +ALLOW + +Matched through: +client ps042 + → group pumpstations + → role telemetry-producer + → ACL vivab/%u/status +``` + +or: + +```text +DENY + +No matching allow rule. +``` + +This would substantially reduce ACL configuration mistakes. + +--- + +# 16. Certificate management + +The frontend shall provide a complete PKI management area. + +The UI triggers certificate operations while all private-key and signing operations are performed by the backend. + +Pages: + +```text +Certificate Authorities +Server Certificates +Client Certificates +Certificate Requests +Revocations +Certificate Policies +``` + +--- + +# 17. Certificate authority + +The system shall support creation of an internal CA. + +At minimum: + +```text +CA name +Common Name +Organization +Organizational Unit +Country +Validity +Key algorithm +Key length +Creation date +Expiration date +Status +``` + +Supported key types should initially include: + +```text +RSA 3072 +RSA 4096 +ECDSA P-256 +ECDSA P-384 +``` + +--- + +# 18. Recommended CA hierarchy + +Production use should support: + +```text +Offline Root CA + │ + ▼ +MQTT Intermediate CA + │ + ├── Broker certificate + ├── Client certificate + ├── Client certificate + └── Client certificate +``` + +The system may generate the root CA during initial setup, but should allow the root key to subsequently be exported and removed from the online platform. + +The backend should preferably keep only the intermediate signing CA online. + +--- + +# 19. Server certificate generation + +The UI shall allow an administrator to specify: + +```text +Common Name +DNS SANs +IP SANs +Validity +Key algorithm +``` + +Example: + +```text +CN = mqtt.example.local + +SAN: +mqtt.example.local +mqtt +10.20.30.40 +``` + +The generated certificate shall contain the appropriate `serverAuth` extended key usage. + +--- + +# 20. Client certificate generation + +The frontend shall support two modes. + +## Managed key generation + +Backend generates: + +```text +client.key +client.crt +ca.crt +``` + +The files can be delivered as: + +```text +ZIP +PEM +PKCS#12/PFX +``` + +The generated bundle should be available for one-time download. + +## CSR mode + +Preferred for higher security. + +The client generates its own private key and submits a CSR. + +The frontend allows the administrator to: + +1. upload or paste CSR; +2. inspect subject and SANs; +3. approve signing; +4. issue certificate; +5. download signed certificate and CA chain. + +The private key then never enters the management platform. + +--- + +# 21. Certificate inventory + +Each certificate shall be tracked with: + +```text +Serial number +Subject +Issuer +Common Name +SAN +Certificate type +Associated MQTT client +Issued date +Expiration date +Status +Fingerprint +Revocation date +Revocation reason +``` + +--- + +# 22. Certificate revocation + +The platform shall support: + +* certificate revocation; +* CRL generation; +* CRL renewal; +* publication of active CRL to Mosquitto; +* immediate application of changed CRL. + +Mosquitto can be configured with a PEM encoded CRL using `crlfile` when client certificates are required. + +--- + +# 23. Certificate expiry monitoring + +Dashboard warnings shall be generated at configurable intervals. + +Example: + +```text +90 days +60 days +30 days +14 days +7 days +Expired +``` + +Future support should allow notification through: + +```text +SMTP +Webhook +Teams +Slack +MQTT +``` + +--- + +# 24. Mutual TLS + +The platform shall support listeners where: + +```text +require_certificate true +``` + +Optional identity mapping: + +```text +use_identity_as_username true +``` + +Mosquitto can use the certificate CN as the MQTT username when client certificates are required. + +This enables an architecture such as: + +```text +Certificate CN: +ps042 + + │ + ▼ + +MQTT identity: +ps042 + + │ + ▼ + +Dynamic Security: +client ps042 + + │ + ▼ + +Role/ACL evaluation +``` + +This combination shall be explicitly integration-tested as part of the implementation. + +--- + +# 25. Mosquitto configuration management + +The platform shall not directly overwrite the active configuration when an administrator edits a setting. + +Instead: + +```text +Edit + ↓ +Draft configuration + ↓ +Validate + ↓ +Show diff + ↓ +Approve + ↓ +Create revision + ↓ +Deploy + ↓ +Reload/restart + ↓ +Health check +``` + +--- + +# 26. Configuration revisions + +Each broker configuration change shall generate a revision. + +Store: + +```text +Revision ID +Timestamp +User +Reason/comment +Previous revision +Generated mosquitto.conf +Change diff +Validation result +Deployment result +``` + +The administrator shall be able to view: + +```text +Revision 34 → Revision 35 + +- max_connections 1000 ++ max_connections 2000 + +- log_type warning ++ log_type notice +``` + +--- + +# 27. Configuration validation + +Before deployment, the generated Mosquitto configuration shall be tested. + +Mosquitto 2.1 provides: + +```text +mosquitto -c mosquitto.conf --test-config +``` + +The command exits successfully when the configuration is valid without starting the broker. + +A configuration failing validation shall never become active. + +--- + +# 28. Configuration reload + +Where supported, changes shall be applied using a configuration reload. + +Mosquitto 2.1 provides: + +```text +mosquitto_signal config-reload +``` + +or equivalent `SIGHUP` behaviour. + +The frontend shall distinguish: + +```text +No reload required +Reload required +Broker restart required +``` + +because not every Mosquitto option can be dynamically reloaded. + +--- + +# 29. Broker control service + +A small internal `mosquitto-control` service is recommended. + +Its responsibilities shall be limited to: + +```text +validate staged configuration +activate configuration revision +signal config reload +signal log rotation +restart broker where explicitly supported +check broker process state +``` + +The normal backend shall call this service through an isolated Docker network. + +The Docker socket: + +```text +/var/run/docker.sock +``` + +shall **not** be mounted into the frontend or backend. + +This avoids giving the web application unrestricted control over the Docker host. + +--- + +# 30. Listener management + +The frontend shall support graphical configuration of Mosquitto listeners. + +Fields include: + +```text +Port +Protocol +Bind address +IPv4/IPv6 +TLS enabled +Certificate +CA +Client certificates required +Minimum TLS version +Authentication mode +WebSockets +Maximum connections +Anonymous access +``` + +Example: + +```text +Listener: Production MQTT + +Port: 8883 +Protocol: MQTT +TLS: enabled +Minimum TLS: TLS 1.2 +Client certificate: required +Anonymous: false +``` + +--- + +# 31. Broker settings + +The UI should support commonly required settings including: + +```text +persistence +autosave_interval +global_max_clients +max_connections +max_queued_messages +max_queued_bytes +message_size_limit +max_inflight_messages +keepalive behaviour +connection logging +log levels +retain support +WebSockets +``` + +Advanced settings may initially be exposed through an expert configuration editor. + +--- + +# 32. Safe configuration editor + +The UI shall have two modes. + +## Basic mode + +Structured forms. + +## Advanced mode + +Show generated: + +`mosquitto.conf` + +The advanced editor shall not directly replace the active file. + +Changes still undergo: + +```text +validation +revision creation +diff +approval +deployment +``` + +--- + +# 33. Broker dashboard + +The landing page should show: + +```text +Broker status +Broker version +Uptime + +Connected clients +Stored sessions +Subscriptions +Retained messages + +Messages received/sec +Messages sent/sec + +Bytes received/sec +Bytes sent/sec + +Dropped messages +Publish failures + +Certificates expiring +Disabled clients +Recent authentication failures + +Current config revision +Last backup +``` + +Much of the runtime information can be collected from Mosquitto `$SYS/#`. + +--- + +# 34. Connected-client view + +Where information is available, display: + +```text +Client ID +Username +Source IP +Protocol version +Connected since +Keepalive +Session state +Subscriptions +Authentication mechanism +Certificate +``` + +Future versions may use a Mosquitto plugin if more detailed connection information is required than `$SYS` exposes. + +--- + +# 35. Topic explorer + +A useful management tool shall be provided. + +The administrator can: + +```text +subscribe to a topic filter +inspect messages +publish test messages +select QoS +set retained flag +inspect MQTT 5 properties +``` + +Example: + +```text +Subscribe: +vivab/+/telemetry/# + +Publish: +vivab/test/command +``` + +Access to this feature shall be restricted through management RBAC. + +All publishes through the test console shall be audited. + +--- + +# 36. Retained-message management + +The frontend should support: + +```text +list known retained topics where feasible +inspect retained payload +clear retained message +publish replacement +``` + +Destructive actions shall require explicit confirmation. + +--- + +# 37. Bridge management + +Mosquitto supports connections between brokers through bridges. + +The platform should therefore support configuration of: + +```text +Bridge name +Remote broker +Port +TLS +CA +Client certificate +Username +Password +Remote topics +Local topics +Direction +QoS +Clean start +Reconnect interval +``` + +This is particularly useful for distributed OT environments. + +Example: + +```text +Pump station broker + │ + │ MQTT bridge + ▼ +Central MQTT broker +``` + +--- + +# 38. Audit log + +All privileged actions shall be audited. + +Each audit event shall contain: + +```text +Timestamp +User +Source IP +Action +Object type +Object identifier +Old value +New value +Result +Correlation ID +``` + +Examples: + +```text +CLIENT_CREATED +CLIENT_DISABLED +ACL_CHANGED +CERTIFICATE_ISSUED +CERTIFICATE_REVOKED +BROKER_CONFIG_CHANGED +BROKER_CONFIG_DEPLOYED +BROKER_RESTARTED +USER_CREATED +ROLE_CHANGED +LOGIN_FAILED +BACKUP_CREATED +RESTORE_PERFORMED +``` + +Audit records should be append-only from the application's perspective. + +--- + +# 39. Application database + +Recommended database: + +**PostgreSQL** + +Initial logical entities: + +```text +users +roles +permissions +user_roles + +broker_settings +broker_config_revisions + +certificate_authorities +certificates +certificate_revocations + +mqtt_client_metadata + +audit_events + +system_settings + +backup_records +``` + +Dynamic Security clients/groups/roles shall remain managed by Mosquitto. + +The application database stores additional metadata and synchronization state. + +--- + +# 40. Source-of-truth model + +The system shall have clear ownership rules. + +```text +Management users + → PostgreSQL + +Management RBAC + → PostgreSQL + +MQTT authentication + → Mosquitto Dynamic Security + +MQTT ACL + → Mosquitto Dynamic Security + +MQTT client metadata + → PostgreSQL + +Broker configuration + → PostgreSQL revision + generated files + +Certificates + → backend PKI store + +Mosquitto runtime state + → Mosquitto +``` + +The backend shall reconcile its expected Dynamic Security configuration with Mosquitto and report discrepancies. + +--- + +# 41. Backend API + +Minimum API groups: + +```text +/api/v1/auth +/api/v1/users +/api/v1/roles + +/api/v1/broker +/api/v1/broker/config +/api/v1/broker/revisions +/api/v1/broker/status + +/api/v1/mqtt/clients +/api/v1/mqtt/groups +/api/v1/mqtt/roles +/api/v1/mqtt/acls + +/api/v1/pki/ca +/api/v1/pki/certificates +/api/v1/pki/csr +/api/v1/pki/crl + +/api/v1/topics + +/api/v1/audit + +/api/v1/backups +/api/v1/system +``` + +--- + +# 42. API conventions + +The REST API shall: + +* use JSON; +* use ISO 8601 timestamps; +* use UUID identifiers; +* provide consistent error objects; +* provide pagination; +* provide filtering; +* provide sorting; +* provide request correlation IDs; +* automatically generate OpenAPI documentation. + +Example error: + +```json +{ + "code": "ACL_CONFLICT", + "message": "The ACL conflicts with an existing higher priority deny rule.", + "correlation_id": "..." +} +``` + +--- + +# 43. Secret storage + +Passwords shall use non-reversible hashing where authentication only requires validation. + +Recommended: + +```text +Argon2id +``` + +Secrets that must later be retrieved shall be encrypted. + +Examples: + +```text +CA private keys +bridge passwords +service credentials +PKCS#12 passwords +``` + +Use authenticated encryption such as: + +```text +AES-256-GCM +``` + +The encryption master key shall be provided externally through: + +```text +Docker secret + +or + +environment variable for development +``` + +The master key shall never be stored in PostgreSQL. + +--- + +# 44. Private-key handling + +Certificate private keys shall be handled according to their purpose. + +### Server private key + +May be stored encrypted because Mosquitto requires continued access. + +### Intermediate CA private key + +May be stored encrypted. + +### Root CA private key + +Preferably export and remove after creation. + +### Client private key + +Prefer CSR-based issuance. + +If generated by the system: + +* encrypt at rest; +* permit one-time download; +* optionally delete after download. + +--- + +# 45. Backup and restore + +The frontend shall provide backup administration. + +A logical backup shall include: + +```text +PostgreSQL database +Mosquitto configuration +Dynamic Security configuration +certificate database +encrypted CA/server keys +CRL +application configuration +``` + +Mosquitto persistence data may optionally be included depending on the selected backup mode. + +Backup files shall be encrypted. + +The UI shall support: + +```text +Create backup +Download backup +Verify backup +Restore backup +``` + +Restore shall require elevated privileges. + +--- + +# 46. Health checks + +Each container shall provide a health check. + +Backend health: + +```text +/health/live +/health/ready +``` + +Readiness should verify: + +```text +database +Mosquitto management connection +certificate storage +configuration storage +``` + +The dashboard shall distinguish: + +```text +Frontend healthy +Backend healthy +Database healthy +Broker healthy +Management channel healthy +``` + +--- + +# 47. Logging + +The platform shall use structured logs. + +Recommended format: + +```json +{ + "timestamp": "...", + "level": "INFO", + "service": "mqtt-backend", + "event": "certificate_issued", + "correlation_id": "...", + "user": "admin" +} +``` + +Passwords, private keys and authentication tokens shall never be logged. + +--- + +# 48. Configuration drift detection + +A highly recommended feature is configuration drift detection. + +The system shall periodically compare: + +```text +expected configuration + vs +active Mosquitto configuration +``` + +and report: + +```text +IN SYNC +DRIFT DETECTED +UNKNOWN +``` + +The same principle should apply to Dynamic Security configuration. + +This is particularly useful where administrators still have shell access to the host. + +--- + +# 49. Change approval + +A later version should optionally support a four-eyes workflow. + +Example: + +```text +Administrator A + │ + ▼ +Proposes ACL change + │ + ▼ +Administrator B + │ + ▼ +Approves + │ + ▼ +Backend applies change +``` + +This should be configurable rather than mandatory. + +It is especially useful in OT environments where an ACL or listener change can affect production communications. + +--- + +# 50. Client provisioning workflow + +The frontend should provide a provisioning wizard. + +Example: + +```text +Create client + ↓ +Select authentication + ↓ +Generate credentials/certificate + ↓ +Select group + ↓ +Assign roles + ↓ +Evaluate ACL + ↓ +Test credentials + ↓ +Download package +``` + +The generated package could contain: + +```text +ca.crt +client.crt +client.key +README.txt +connection.json +mosquitto_pub-example.txt +mosquitto_sub-example.txt +``` + +--- + +# 51. Connection profile export + +A very useful feature would be generation of ready-to-use client configuration. + +Example: + +```json +{ + "host": "mqtt.example.local", + "port": 8883, + "clientId": "PS042", + "username": "PS042", + "tls": true, + "ca": "ca.crt", + "certificate": "client.crt", + "privateKey": "client.key" +} +``` + +The frontend may generate example configuration for: + +```text +mosquitto_pub/sub +Python +Node.js +Node-RED +Ignition +Grafana +generic MQTT clients +``` + +--- + +# 52. Test connection + +After creating a client, the administrator should be able to perform: + +```text +Authentication test +TLS test +Publish test +Subscribe test +ACL test +``` + +Result: + +```text +TLS handshake PASS +Certificate PASS +Authentication PASS +Publish telemetry PASS +Subscribe commands PASS +Forbidden topic DENIED — expected +``` + +This provides a useful commissioning function. + +--- + +# 53. MQTT namespace documentation + +The frontend should optionally contain a **Topic Namespace** registry. + +Example: + +```text +vivab/{site}/{device}/telemetry/{signal} +vivab/{site}/{device}/status +vivab/{site}/{device}/command/{command} +vivab/{site}/{device}/config/{parameter} +``` + +Administrators can document: + +```text +topic pattern +purpose +payload schema +publisher +subscriber +QoS +retain behaviour +owner +``` + +This goes beyond native Mosquitto administration but would be extremely valuable as the MQTT environment grows. + +--- + +# 54. Payload/schema registry – future feature + +A later version could associate topic patterns with schemas. + +Example: + +```text +vivab/+/+/telemetry/level +``` + +Schema: + +```json +{ + "type": "object", + "properties": { + "value": { + "type": "number" + }, + "unit": { + "const": "m" + } + } +} +``` + +The test console could then validate messages against the expected schema. + +--- + +# 55. Metrics + +The backend shall collect broker metrics from `$SYS/#`. + +Metrics should include: + +```text +uptime +clients connected +clients disconnected +subscriptions +stored messages +retained messages +messages received +messages sent +bytes received +bytes sent +publish received +publish sent +dropped messages +load +``` + +Historical storage should initially be optional. + +Prometheus support may later be added. + +--- + +# 56. Alerts + +The platform should eventually support configurable alerts such as: + +```text +Broker unavailable +Client count unusually high +Certificate expiring +Certificate expired +Repeated authentication failures +Configuration drift detected +Backup failure +Bridge disconnected +Disk usage high +``` + +--- + +# 57. UI navigation + +Recommended primary navigation: + +```text +Dashboard + +Broker + ├── Status + ├── Configuration + ├── Listeners + ├── Bridges + └── Revisions + +MQTT Security + ├── Clients + ├── Groups + ├── Roles + ├── ACL Simulator + └── Authentication + +Certificates + ├── Authorities + ├── Server Certificates + ├── Client Certificates + ├── CSRs + └── Revocations + +Tools + ├── Topic Explorer + ├── Connection Test + └── Client Provisioning + +Administration + ├── Users + ├── Roles + ├── Audit Log + ├── Backup + └── System +``` + +--- + +# 58. Security defaults + +The default installation shall favour secure configuration. + +Recommended defaults: + +```text +allow_anonymous false + +TLS required externally + +Minimum TLS version TLS 1.2 + +Plain MQTT listener disabled + +Default ACL policy deny + +Management API not externally exposed except through frontend/reverse proxy + +Database not host exposed + +Dynamic Security administration listener internal only + +No Docker socket exposure +``` + +Dynamic Security supports deny-by-default ACL behaviour and runtime modification of clients, groups and roles. + +--- + +# 59. Initial installation workflow + +On first startup: + +```text +PostgreSQL starts + ↓ +Backend migrations run + ↓ +Initial management admin created + ↓ +Dynamic Security initialized + ↓ +Mosquitto admin identity initialized + ↓ +Default broker config generated + ↓ +CA setup checked + ↓ +Mosquitto starts + ↓ +Backend verifies broker + ↓ +Frontend becomes ready +``` + +If no PKI exists, the administrator should see: + +```text +MQTT TLS is not yet configured. + +[Create internal CA] +[Import CA] +[Configure later] +``` + +--- + +# 60. Initial default broker configuration + +A secure installation should initially expose only an internal administration connection until the administrator configures the production listener. + +Typical production result: + +```text +listener 8883 + +TLS enabled +server certificate configured +anonymous disabled +dynamic security enabled +persistence enabled +logging enabled +``` + +An optional mTLS profile would additionally enable: + +```text +require_certificate true +``` + +--- + +# 61. Mosquitto configuration ownership + +The frontend shall never be considered the actual configuration store. + +The ownership hierarchy shall be: + +```text +PostgreSQL configuration model + │ + ▼ +Generated configuration revision + │ + ▼ +mosquitto.conf + │ + ▼ +Mosquitto +``` + +This allows validation, auditing, versioning and rollback. + +--- + +# 62. Rollback + +Each successfully deployed configuration shall be recoverable. + +Example: + +```text +Revision 53 + ↓ +configuration causes problem + ↓ +Select revision 52 + ↓ +Validate + ↓ +Deploy + ↓ +Reload/restart +``` + +Rollback itself shall create a new revision rather than modifying history. + +Example: + +```text +52 +53 +54 = rollback to contents of 52 +``` + +--- + +# 63. Database migrations + +Database schema changes shall use Alembic migrations. + +Backend startup shall either: + +* automatically apply compatible migrations; or +* fail readiness and require an explicit migration command. + +Production deployments should favour explicit migrations. + +--- + +# 64. API tests + +Automated tests shall cover at minimum: + +```text +authentication +authorization +client creation +ACL creation +certificate issuance +certificate revocation +configuration generation +configuration validation +configuration rollback +audit creation +backup/restore +``` + +--- + +# 65. Integration tests + +An automated test environment shall launch an actual Mosquitto container. + +Tests shall verify: + +```text +MQTT username/password authentication +mTLS authentication +certificate CN mapping +ACL allow +ACL deny +group ACL +role ACL +client disable +certificate revocation +configuration reload +broker restart +``` + +--- + +# 66. Security tests + +Security testing shall include: + +```text +authentication bypass attempts +horizontal privilege escalation +vertical privilege escalation +CSRF +XSS +SQL injection +path traversal +malicious certificate upload +malformed CSR +secret exposure +Docker breakout exposure +API rate abuse +``` + +--- + +# 67. Recommended repository structure + +```text +mqtt-platform/ +│ +├── compose.yaml +├── .env.example +├── README.md +│ +├── frontend/ +│ ├── Dockerfile +│ ├── package.json +│ └── src/ +│ +├── backend/ +│ ├── Dockerfile +│ ├── pyproject.toml +│ ├── migrations/ +│ └── app/ +│ +├── broker-control/ +│ ├── Dockerfile +│ └── app/ +│ +├── mosquitto/ +│ ├── templates/ +│ └── bootstrap/ +│ +├── scripts/ +│ +└── tests/ + ├── unit/ + ├── integration/ + └── e2e/ +``` + +Generated configuration and secrets shall not be stored in Git. + +--- + +# 68. MVP scope + +The first functional release should include: + +```text +Docker Compose stack + +Mosquitto 2.1.x + +PostgreSQL + +FastAPI backend + +React frontend + +Management authentication + +Management RBAC + +Dynamic Security integration + +MQTT clients + +Groups + +Roles + +ACL editor + +ACL simulator + +CA creation + +Server certificates + +Client certificates + +CSR signing + +Certificate revocation + +CRL + +Broker configuration editor + +Listener configuration + +Configuration validation + +Configuration revisioning + +Configuration deployment + +Broker reload + +Dashboard + +$SYS monitoring + +Audit logging + +Backup/restore +``` + +--- + +# 69. Phase 2 + +The second phase should add: + +```text +Topic explorer +MQTT test client +Connection tester +Client provisioning wizard +Bridge configuration +Certificate expiry alerts +Config drift detection +Retained message administration +Client metadata/tags +Configuration approval workflow +Prometheus metrics +External notification mechanisms +``` + +--- + +# 70. Phase 3 + +Potential advanced functionality: + +```text +MQTT topic namespace registry +JSON Schema registry +payload validation +device inventory integration +automatic certificate renewal +ACME/SCEP/EST integration +LDAP/Active Directory/OIDC login +external PKI integration +multiple Mosquitto brokers +broker federation +HA deployment +configuration-as-code export +Git integration +API-driven provisioning +``` + +--- + +# 71. Particularly recommended additional frontend functionality + +Beyond the original requirements, the features with the highest operational value are: + +**Configuration versioning and rollback** +Mosquitto configuration should be treated like controlled configuration rather than an editable text file. + +**ACL simulator** +Makes complex authorization understandable before deployment. + +**Client provisioning wizard** +Makes creation of credentials, certificates and ACL assignments consistent. + +**Certificate lifecycle dashboard** +Expiration, revocation and ownership become difficult to manage manually as the number of clients increases. + +**Topic explorer and MQTT test client** +Extremely useful when commissioning devices and troubleshooting. + +**Configuration drift detection** +Detects manual changes outside the platform. + +**Audit logging** +Provides traceability for security and configuration changes. + +**Broker diagnostics and `$SYS` monitoring** +Makes the platform useful for daily operation rather than only configuration. + +**Bridge management** +Particularly valuable for distributed broker architectures. + +**Topic namespace registry** +Turns the system from merely a broker manager into a controlled MQTT information-management platform. + +--- + +# 72. Architectural target + +The intended platform can ultimately be viewed as four layers: + +```text +┌─────────────────────────────────────────────┐ +│ MQTT Management UI │ +│ │ +│ Broker | Clients | ACL | PKI | Monitoring │ +└──────────────────────┬──────────────────────┘ + │ +┌──────────────────────▼──────────────────────┐ +│ Management API │ +│ │ +│ Auth | RBAC | PKI | Config | Audit | MQTT │ +└────────────┬───────────────────┬────────────┘ + │ │ +┌────────────▼─────────┐ ┌───────▼────────────┐ +│ PostgreSQL │ │ Broker management │ +│ │ │ / Dynamic Security │ +└─────────────────────┘ └───────┬────────────┘ + │ + ┌────────▼─────────┐ + │ Mosquitto │ + │ │ + │ MQTT / TLS/mTLS │ + └──────────────────┘ +``` + +The result should behave as a self-contained **MQTT broker management platform**, rather than simply a graphical editor for `mosquitto.conf`.