Device security and robustness (openpanel C0): check code, pnc, lenient report

- POST /devices/pair answers a 2-character `check`, listed by /devices/pending
  and shown beside each waiting entry; five codes a minute per address, and at
  50 waiting the oldest gives way instead of a 429
- portal-minted device tokens are asked for with the device's nonce (`pnc`) and
  held against it, so unpair and delete revoke them; one without `pnc` stands
  only while the nonce is 0
- a device credential acts as the device (`device_principal`), not as the
  approving superuser, so deleting that account unpairs nothing
- the report is validated port by port: unknown enum values read as `unknown`,
  unreadable ports and sections are left out and logged, `config` may name an
  entry of `config_schemas`; 422 only for no schema 1 or no object
- devices.json is parsed once per change (cached by stat), delete drops the
  report and keeps the nonce, a busy recheck runs in the background
- scope and io only from enabled flows (start/stop tells the devices), a port
  bound twice gives one io row
- the Devices tab's saves cancel and hold back device refetches until settled
This commit is contained in:
Melvin Strobl
2026-10-16 19:26:05 +02:00
parent 13d23f6baf
commit c604cfdf3b
21 changed files with 773 additions and 119 deletions
+13 -5
View File
@@ -619,6 +619,8 @@ class FlowController:
finally:
self._lock.release()
# A stopped flow wires no device ports.
self._rewired()
self._publish(
{
"type": "pipeline_rebuilt",
@@ -836,7 +838,7 @@ class FlowController:
)
self._rewired()
async def recheck(self) -> None:
async def recheck(self, wait: float | None = FLOW_REBUILD_WAIT) -> None:
"""Validate the built graph again without rebuilding anything.
For what validation reads from outside the flows: a device created or
@@ -844,7 +846,7 @@ class FlowController:
"""
if self.pipeline is None:
return
await self._acquire(FLOW_REBUILD_WAIT)
await self._acquire(wait)
try:
self.issues = _collect_issues(
self.loaded, self.pipeline, self._all_flow_inputs(), self.devices
@@ -2124,6 +2126,14 @@ def _collect_issues(
_NUMBERS = frozenset({"int", "float"})
def _ways(said: dict[str, Any]) -> list[str]:
"""The directions a reported port may be wired in, none when it does not
say: a direction this version does not know is no reason to refuse one."""
if said.get("modes"):
return list(said["modes"])
return [said["direction"]] if said.get("direction") in ("in", "out") else []
def _device_issues(
loaded: dict[str, LoadedNode], devices: Any
) -> list[ValidationIssue]:
@@ -2190,9 +2200,7 @@ def _device_issues(
elif said is None:
problem = f"'{device}' does not report a port '{spec.port}'."
advisory = True
elif said.get("direction") and direction not in (
said.get("modes") or [said["direction"]]
):
elif (ways := _ways(said)) and direction not in ways:
problem = (
f"'{spec.port}' of '{device}' is an {said['direction']} "
f"port, wired here as {direction}."
+204 -17
View File
@@ -34,7 +34,16 @@ from datetime import UTC, datetime
from pathlib import Path
from typing import Any, Literal
from pydantic import BaseModel, Field, TypeAdapter, ValidationError, field_validator
from pydantic import (
BaseModel,
Field,
TypeAdapter,
ValidationError,
ValidationInfo,
ValidatorFunctionWrapHandler,
field_validator,
model_validator,
)
from fluksio.flow.dashboards import DashboardDef, DashboardNotFound, DashboardStore
from fluksio.flow.events import event_bus
@@ -167,21 +176,48 @@ class DeviceState(BaseModel):
_STATES = TypeAdapter(dict[str, DeviceState])
#: Read in place of a value this version does not know, such as a newer
#: firmware's display shape or port direction: no reason to refuse the rest of
#: what the device says.
UNKNOWN = "unknown"
def _known(value: Any, known: tuple[str, ...]) -> Any:
return value if value in known else UNKNOWN
def _left_out(info: ValidationInfo, what: str, why: str) -> None:
"""Note a part of a report that was dropped, for whoever reads it to log."""
if isinstance(info.context, dict):
info.context.setdefault("left_out", []).append(f"{what} ({why})")
def _why(exc: ValidationError) -> str:
error = exc.errors(include_url=False)[0]
where = ".".join(str(part) for part in error["loc"])
return f"{where}: {error['msg']}" if where else str(error["msg"])
class ReportDisplay(BaseModel):
"""The device's screen, in pixels."""
w: int = Field(ge=0)
h: int = Field(ge=0)
shape: Literal["rect", "round"] = "rect"
shape: Literal["rect", "round", "unknown"] = "rect"
touch: bool = False
@field_validator("shape", mode="before")
@classmethod
def _shape(cls, value: Any) -> Any:
return _known(value, ("rect", "round"))
class ReportPort(BaseModel):
"""One port the device has, and how it may be wired."""
port: str = Field(pattern=PORT_PATTERN.pattern)
#: Its default direction: ``in`` publishes, ``out`` follows.
direction: Literal["in", "out"]
direction: Literal["in", "out", "unknown"]
dtype: DType
#: A JSON schema of the ``config`` the device reads for this port.
config: dict[str, Any] | None = None
@@ -190,6 +226,19 @@ class ReportPort(BaseModel):
#: The directions it may be wired in, when it may be either: a GPIO pin.
modes: list[Literal["in", "out"]] | None = None
@field_validator("direction", mode="before")
@classmethod
def _direction(cls, value: Any) -> Any:
return _known(value, ("in", "out"))
@field_validator("modes", mode="before")
@classmethod
def _modes(cls, value: Any) -> Any:
# The ones this version wires. Another is not said, rather than wrong.
if isinstance(value, list):
return [mode for mode in value if mode in ("in", "out")]
return value
class ReportCamera(BaseModel):
"""The camera sensor the device found, and what it delivers."""
@@ -203,8 +252,16 @@ class ReportCamera(BaseModel):
class DeviceReport(BaseModel):
"""What a device says it has, version 1.
Keys this version does not know are dropped, so a newer firmware still
reports to an older instance. The whole report replaces the one before.
Read leniently, so a newer firmware still reports to an older instance.
Keys this version does not know are dropped, a value of a closed set it
does not know reads as ``unknown``, and a port or a section it cannot read
is left out on its own. Only a report that is not version 1, or not an
object at all, is refused. :func:`read_report` says what was left out.
A port's ``config`` may name an entry of ``config_schemas`` instead of
spelling the schema out, so a board with thirty pins sends the pin schema
once. It is put in place when the report is read. The whole report
replaces the one before.
"""
version: Literal[1] = Field(alias="schema")
@@ -217,11 +274,85 @@ class DeviceReport(BaseModel):
#: The build's features, true when there: ``{"camera": true}``.
features: dict[str, bool] = Field(default_factory=dict)
@model_validator(mode="before")
@classmethod
def _named_configs(cls, data: Any, info: ValidationInfo) -> Any:
if not isinstance(data, dict) or not isinstance(data.get("ports"), list):
return data
schemas = data.get("config_schemas")
schemas = schemas if isinstance(schemas, dict) else {}
ports = []
for port in data["ports"]:
if isinstance(port, dict) and isinstance(port.get("config"), str):
schema = schemas.get(port["config"])
if not isinstance(schema, dict):
_left_out(
info,
f"the config of port {port.get('port')!r}",
f"no schema named {port['config']!r}",
)
schema = None
port = {**port, "config": schema}
ports.append(port)
return {**data, "ports": ports}
@field_validator("ports", mode="before")
@classmethod
def _each_port(cls, value: Any, info: ValidationInfo) -> Any:
if not isinstance(value, list):
_left_out(info, "ports", "not a list")
return []
kept = []
for raw in value:
try:
kept.append(ReportPort.model_validate(raw))
except ValidationError as exc:
name = raw.get("port") if isinstance(raw, dict) else raw
_left_out(info, f"port {name!r}", _why(exc))
return kept
@field_validator("features", mode="before")
@classmethod
def _flags(cls, value: Any, info: ValidationInfo) -> Any:
if not isinstance(value, dict):
_left_out(info, "features", "not an object")
return {}
flags = {}
for name, flag in value.items():
if isinstance(flag, bool):
flags[str(name)] = flag
else:
_left_out(info, f"feature {name!r}", f"{flag!r} is not true or false")
return flags
@field_validator("platform", "board", "firmware", "display", "camera", mode="wrap")
@classmethod
def _or_left_out(
cls, value: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo
) -> Any:
try:
return handler(value)
except ValidationError as exc:
name = info.field_name or ""
_left_out(info, name, _why(exc))
return cls.model_fields[name].get_default()
def stored(self) -> dict[str, Any]:
"""As ``devices.json`` keeps it: the device's own keys, nothing unset."""
return self.model_dump(mode="json", by_alias=True, exclude_none=True)
def read_report(raw: bytes) -> tuple[DeviceReport, list[str]]:
"""A device's report, and each part of it that was left out.
Raises ``ValidationError`` only for a report that is not version 1 or
not an object.
"""
context: dict[str, list[str]] = {"left_out": []}
report = DeviceReport.model_validate_json(raw, context=context)
return report, context["left_out"]
class DeviceNotFound(KeyError):
def __init__(self, device_id: str) -> None:
super().__init__(device_id)
@@ -265,6 +396,11 @@ class DeviceStore:
self._wiring: dict[str, list[Binding]] = {}
self._wiring_at = -1
self._wiring_lock = threading.Lock()
#: ``devices.json`` as last parsed, by the file's stat. Every device
#: request holds its nonce against it.
self._states_seen: (
tuple[tuple[int, int, int], dict[str, DeviceState]] | None
) = None
def _file(self, device_id: str) -> Path:
return self.root / f"{checked(device_id)}.json"
@@ -281,18 +417,24 @@ class DeviceStore:
# -- what the published flows wire ------------------------------------
def wiring(self) -> dict[str, list[Binding]]:
"""Every device's bound ports, keyed by device id.
"""Every device's bound ports in enabled published flows, by device id.
A stopped flow wires nothing: its ports go out of the device's ``io``
and out of its credential's reach until it is started again.
Each list is in one fixed order, port first, so what a device reads is
the same bytes for as long as the flows are the same: the firmware
compares the whole document and rebuilds its screen on any change.
Read again when the flow store commits, a device save included.
Read again when the flow store commits, a device save, starting and
stopping a flow included.
"""
with self._wiring_lock:
revision = self.flows.revision
if self._wiring_at != revision:
found: dict[str, list[Binding]] = {}
for flow in self.flows.read_all():
if not self.flows.read_enabled(flow.name):
continue
for binding in bindings_of(flow):
found.setdefault(binding.device, []).append(binding)
for rows in found.values():
@@ -303,7 +445,19 @@ class DeviceStore:
return self._wiring
def bound(self, device_id: str) -> list[Binding]:
return self.wiring().get(device_id, [])
"""What the device's ports are wired to, one binding per port.
A port wired twice is an issue on both nodes. Until it is fixed the
device follows the first of the two in the fixed order, for its
``io`` and its credential's reach alike, so neither flips between them.
"""
found: list[Binding] = []
seen: set[str] = set()
for binding in self.wiring().get(device_id, []):
if binding.port not in seen:
seen.add(binding.port)
found.append(binding)
return found
def io(self, device_id: str) -> list[DeviceIo]:
"""The ports as the device reads them."""
@@ -315,7 +469,10 @@ class DeviceStore:
]
def bindings(self, device_id: str) -> list[DeviceBinding]:
"""The same ports by the node holding each, for whoever wires them."""
"""The same ports by the node holding each, for whoever wires them.
Every binding, a port wired twice twice, so the one to remove shows.
"""
return sorted(
(
DeviceBinding(
@@ -325,7 +482,7 @@ class DeviceStore:
message=b.message,
direction=b.direction,
)
for b in self.bound(device_id)
for b in self.wiring().get(device_id, [])
),
key=lambda b: (b.flow, b.node, b.port, b.message),
)
@@ -403,7 +560,8 @@ class DeviceStore:
The nonce is bumped rather than dropped: a device created again under
the same id, or brought back by a revert, must not take the old
screen's credential back with it.
screen's credential back with it. Its report goes, since a device
created again is not the board that made it.
"""
with self.flows._write_lock:
path = self._file(device_id)
@@ -411,14 +569,15 @@ class DeviceStore:
raise DeviceNotFound(device_id)
path.unlink()
self.flows._commit(f"Delete device '{device_id}'")
self.bump(device_id)
self.bump(device_id, forget=True)
presence.forget(device_id)
# -- outside git -------------------------------------------------------
def _read_states(self) -> dict[str, DeviceState]:
"""Raises on a file that does not parse, rather than reading it as empty.
"""The file as it is now, for a writer to change and write back.
Raises on a file that does not parse, rather than reading it as empty.
Empty would put every nonce back to 0, which honours again every
credential an unpair refused.
"""
@@ -426,6 +585,26 @@ class DeviceStore:
return {}
return _STATES.validate_json(self.state_file.read_bytes())
def _states(self) -> dict[str, DeviceState]:
"""The same for reading only, parsed again only once the file changed.
Every device request reads its nonce here. A write from this process
replaces what is held at once, and one from anywhere else changes the
file's stat. Shared between callers, so never changed in place.
"""
try:
seen = self.state_file.stat()
except FileNotFoundError:
return {}
key = (seen.st_mtime_ns, seen.st_size, seen.st_ino)
held = self._states_seen
if held is not None and held[0] == key:
return held[1]
# Stat before read, so what is held is never older than its key.
states = _STATES.validate_json(self.state_file.read_bytes())
self._states_seen = (key, states)
return states
def _write_states(self, states: dict[str, DeviceState]) -> None:
# Through a temporary file, so a crash mid-write cannot leave a torn
# file behind.
@@ -433,19 +612,27 @@ class DeviceStore:
tmp = self.state_file.with_name(self.state_file.name + ".tmp")
tmp.write_bytes(_STATES.dump_json(states, indent=2))
os.replace(tmp, self.state_file)
seen = self.state_file.stat()
self._states_seen = ((seen.st_mtime_ns, seen.st_size, seen.st_ino), states)
def state(self, device_id: str) -> DeviceState:
return self._read_states().get(device_id, DeviceState())
return self._states().get(device_id, DeviceState())
def nonce(self, device_id: str) -> int:
return self.state(device_id).nonce
def bump(self, device_id: str) -> int:
"""Refuse the credential this device holds now. Returns the new nonce."""
def bump(self, device_id: str, *, forget: bool = False) -> int:
"""Refuse the credential this device holds now. Returns the new nonce.
``forget`` drops everything else kept about the device as well.
"""
with self._state_lock:
states = self._read_states()
state = states.setdefault(device_id, DeviceState())
state = states.get(device_id) or DeviceState()
if forget:
state = DeviceState(nonce=state.nonce)
state.nonce += 1
states[device_id] = state
self._write_states(states)
return state.nonce