295 lines
11 KiB
Python
295 lines
11 KiB
Python
"""Dynamic Security client — the runtime control channel (spec sections 10-14).
|
|
|
|
The backend connects to Mosquitto as the seeded `admin` client and issues
|
|
commands on the $CONTROL/dynamic-security/v1 topic API.
|
|
|
|
Wire protocol (verified against Mosquitto 2.1 source: src/control_common.c,
|
|
plugins/dynamic-security/control.c and clients.c):
|
|
|
|
Request -> $CONTROL/dynamic-security/v1
|
|
{"commands": [{"command": "createClient", ...,
|
|
"correlationData": "<id>"}]}
|
|
Response <- $CONTROL/dynamic-security/v1/response (FIXED topic)
|
|
{"responses": [{"command": "createClient",
|
|
"correlationData": "<id>",
|
|
"error": "..." (only on failure),
|
|
"data": {...}}]}
|
|
|
|
Responses are matched to requests by the echoed correlationData in the
|
|
PAYLOAD, not by topic. Command results live under `data` (data.client,
|
|
data.clients, ...). Client objects report `disabled` (absent == enabled).
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
import logging
|
|
import queue
|
|
import threading
|
|
import uuid
|
|
from typing import Any
|
|
|
|
import paho.mqtt.client as mqtt
|
|
from paho.mqtt.enums import CallbackAPIVersion
|
|
|
|
from app.config import get_settings
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
CONTROL_TOPIC = "$CONTROL/dynamic-security/v1"
|
|
RESPONSE_TOPIC = "$CONTROL/dynamic-security/v1/response"
|
|
_RESPONSE_TIMEOUT_S = 10.0
|
|
|
|
|
|
class DynsecError(Exception):
|
|
"""The dynamic security API returned an error for a command."""
|
|
|
|
def __init__(self, message: str) -> None:
|
|
super().__init__(message)
|
|
self.message = message
|
|
|
|
|
|
class DynsecTimeout(DynsecError):
|
|
"""No response from the broker management channel."""
|
|
|
|
|
|
class DynsecClient:
|
|
"""Thin, thread-safe wrapper around the dynsec $CONTROL API."""
|
|
|
|
def __init__(self) -> None:
|
|
self._client: mqtt.Client | None = None
|
|
self._lock = threading.Lock()
|
|
self._responses: dict[str, queue.Queue[dict[str, Any]]] = {}
|
|
self._connected = threading.Event()
|
|
|
|
# -- connection lifecycle ------------------------------------------------
|
|
def connect(self) -> None:
|
|
with self._lock:
|
|
if self._client is not None:
|
|
return
|
|
settings = get_settings()
|
|
client = mqtt.Client(
|
|
callback_api_version=CallbackAPIVersion.VERSION2,
|
|
client_id=f"mqtt-backend-{uuid.uuid4().hex[:8]}",
|
|
)
|
|
client.username_pw_set(
|
|
settings.mosquitto_dynsec_username, settings.mosquitto_dynsec_password
|
|
)
|
|
client.on_connect = self._on_connect
|
|
client.on_message = self._on_message
|
|
client.connect_async(
|
|
settings.mosquitto_host, settings.mosquitto_mgmt_port, keepalive=30
|
|
)
|
|
client.loop_start()
|
|
if not self._connected.wait(timeout=_RESPONSE_TIMEOUT_S):
|
|
client.loop_stop()
|
|
raise DynsecError("could not connect to broker management channel")
|
|
self._client = client
|
|
|
|
def close(self) -> None:
|
|
with self._lock:
|
|
if self._client is None:
|
|
return
|
|
self._client.disconnect()
|
|
self._client.loop_stop()
|
|
self._client = None
|
|
self._connected.clear()
|
|
|
|
# -- paho callbacks -------------------------------------------------------
|
|
def _on_connect(self, client, userdata, flags, reason_code, properties) -> None:
|
|
if reason_code == 0:
|
|
# FIXED response topic — all commands reply here; requests are
|
|
# matched by the correlationData echo inside the payload.
|
|
client.subscribe(RESPONSE_TOPIC, qos=1)
|
|
self._connected.set()
|
|
else:
|
|
logger.error("dynsec client connect failed: %s", reason_code)
|
|
|
|
def _on_message(self, client, userdata, msg) -> None:
|
|
if msg.topic != RESPONSE_TOPIC:
|
|
return
|
|
try:
|
|
payload = json.loads(msg.payload.decode("utf-8"))
|
|
except (UnicodeDecodeError, json.JSONDecodeError):
|
|
logger.warning("unreadable dynsec response payload")
|
|
return
|
|
# Envelope is {"responses": [...]}; fan entries out to waiters by
|
|
# their echoed correlationData.
|
|
for entry in payload.get("responses", []):
|
|
correlation = entry.get("correlationData")
|
|
if correlation and correlation in self._responses:
|
|
self._responses[correlation].put_nowait(entry)
|
|
|
|
# -- command plumbing -----------------------------------------------------
|
|
def _command(self, command: str, **kwargs: Any) -> dict[str, Any]:
|
|
"""Send one command; return its `data` object on success.
|
|
|
|
Raises DynsecError when the broker replies with an error, and
|
|
DynsecTimeout when no response arrives in time.
|
|
"""
|
|
self.connect()
|
|
assert self._client is not None # for type checkers
|
|
correlation = uuid.uuid4().hex
|
|
reply_queue: queue.Queue[dict[str, Any]] = queue.Queue()
|
|
self._responses[correlation] = reply_queue
|
|
body = {
|
|
"commands": [
|
|
{"command": command, "correlationData": correlation, **kwargs}
|
|
]
|
|
}
|
|
try:
|
|
result = self._client.publish(
|
|
CONTROL_TOPIC, json.dumps(body).encode("utf-8"), qos=1
|
|
)
|
|
result.wait_for_publish(timeout=_RESPONSE_TIMEOUT_S)
|
|
try:
|
|
entry = reply_queue.get(timeout=_RESPONSE_TIMEOUT_S)
|
|
except queue.Empty as exc:
|
|
raise DynsecTimeout(f"dynsec command '{command}' timed out") from exc
|
|
finally:
|
|
self._responses.pop(correlation, None)
|
|
|
|
if "error" in entry:
|
|
raise DynsecError(f"{command}: {entry['error']}")
|
|
return entry.get("data") or {}
|
|
|
|
# -- Release 1 API surface (spec sections 11-14) ---------------------------
|
|
|
|
# Clients
|
|
def create_client(
|
|
self,
|
|
username: str,
|
|
password: str,
|
|
clientid: str | None = None,
|
|
text_name: str | None = None,
|
|
text_description: str | None = None,
|
|
groups: list[dict[str, Any]] | None = None,
|
|
roles: list[dict[str, Any]] | None = None,
|
|
) -> None:
|
|
params: dict[str, Any] = {"username": username, "password": password}
|
|
if clientid:
|
|
params["clientid"] = clientid
|
|
if text_name:
|
|
params["textname"] = text_name
|
|
if text_description:
|
|
params["textdescription"] = text_description
|
|
if groups:
|
|
params["groups"] = groups
|
|
if roles:
|
|
params["roles"] = roles
|
|
self._command("createClient", **params)
|
|
|
|
def delete_client(self, username: str) -> None:
|
|
self._command("deleteClient", username=username)
|
|
|
|
def enable_client(self, username: str) -> None:
|
|
self._command("enableClient", username=username)
|
|
|
|
def disable_client(self, username: str) -> None:
|
|
self._command("disableClient", username=username)
|
|
|
|
def set_client_password(self, username: str, password: str) -> None:
|
|
self._command("setClientPassword", username=username, password=password)
|
|
|
|
def get_client(self, username: str) -> dict[str, Any]:
|
|
return self._command("getClient", username=username).get("client", {})
|
|
|
|
def list_clients(self) -> list[dict[str, Any]]:
|
|
"""Full client objects (verbose=true gives groups/roles/disabled)."""
|
|
data = self._command("listClients", verbose=True)
|
|
return data.get("clients", [])
|
|
|
|
def set_client_group_memberships(
|
|
self, username: str, groups: list[dict[str, Any]]
|
|
) -> None:
|
|
"""Replace a client's complete group membership list."""
|
|
self._command("modifyClient", username=username, groups=groups)
|
|
|
|
def set_client_roles(self, username: str, roles: list[dict[str, Any]]) -> None:
|
|
"""Replace a client's direct role assignments."""
|
|
self._command("modifyClient", username=username, roles=roles)
|
|
|
|
def add_client_role(self, username: str, rolename: str, priority: int = -1) -> None:
|
|
"""Incrementally add one role to a client (spec section 11).
|
|
|
|
Deliberately incremental rather than modifyClient full-list
|
|
replacement: safer against accidental clobbering from the UI.
|
|
"""
|
|
self._command(
|
|
"addClientRole", username=username, rolename=rolename, priority=priority
|
|
)
|
|
|
|
def remove_client_role(self, username: str, rolename: str) -> None:
|
|
self._command("removeClientRole", username=username, rolename=rolename)
|
|
|
|
# Groups
|
|
def create_group(self, groupname: str, roles: list[dict[str, Any]] | None = None) -> None:
|
|
params: dict[str, Any] = {"groupname": groupname}
|
|
if roles:
|
|
params["roles"] = roles
|
|
self._command("createGroup", **params)
|
|
|
|
def delete_group(self, groupname: str) -> None:
|
|
self._command("deleteGroup", groupname=groupname)
|
|
|
|
def get_group(self, groupname: str) -> dict[str, Any]:
|
|
return self._command("getGroup", groupname=groupname).get("group", {})
|
|
|
|
def list_groups(self) -> list[dict[str, Any]]:
|
|
data = self._command("listGroups", verbose=True)
|
|
return data.get("groups", [])
|
|
|
|
def set_group_roles(self, groupname: str, roles: list[dict[str, Any]]) -> None:
|
|
self._command("modifyGroup", groupname=groupname, roles=roles)
|
|
|
|
def add_group_role(self, groupname: str, rolename: str, priority: int = -1) -> None:
|
|
"""Incrementally add one role to a group (spec section 12)."""
|
|
self._command(
|
|
"addGroupRole", groupname=groupname, rolename=rolename, priority=priority
|
|
)
|
|
|
|
def remove_group_role(self, groupname: str, rolename: str) -> None:
|
|
self._command("removeGroupRole", groupname=groupname, rolename=rolename)
|
|
|
|
def add_group_client(self, groupname: str, username: str, priority: int = 1) -> None:
|
|
self._command(
|
|
"addGroupClient", groupname=groupname, username=username, priority=priority
|
|
)
|
|
|
|
def remove_group_client(self, groupname: str, username: str) -> None:
|
|
self._command("removeGroupClient", groupname=groupname, username=username)
|
|
|
|
# Roles
|
|
def create_role(self, rolename: str, acls: list[dict[str, Any]] | None = None) -> None:
|
|
params: dict[str, Any] = {"rolename": rolename}
|
|
if acls:
|
|
params["acls"] = acls
|
|
self._command("createRole", **params)
|
|
|
|
def delete_role(self, rolename: str) -> None:
|
|
self._command("deleteRole", rolename=rolename)
|
|
|
|
def get_role(self, rolename: str) -> dict[str, Any]:
|
|
return self._command("getRole", rolename=rolename).get("role", {})
|
|
|
|
def list_roles(self) -> list[dict[str, Any]]:
|
|
data = self._command("listRoles", verbose=True)
|
|
return data.get("roles", [])
|
|
|
|
def set_role_acls(self, rolename: str, acls: list[dict[str, Any]]) -> None:
|
|
"""Replace the full ACL list of a role (spec section 14 editor)."""
|
|
self._command("modifyRole", rolename=rolename, acls=acls)
|
|
|
|
# Default ACL behaviour (spec section 58: deny by default)
|
|
def set_default_acl_access(self, acl_type: str, allow: bool) -> None:
|
|
self._command(
|
|
"setDefaultACLAccess",
|
|
acls=[{"acltype": acl_type, "allow": allow}],
|
|
)
|
|
|
|
def get_default_acl_access(self) -> list[dict[str, Any]]:
|
|
return self._command("getDefaultACLAccess").get("acls", [])
|
|
|
|
|
|
# Module-level singleton used by FastAPI dependencies.
|
|
dynsec_client = DynsecClient() |