Add coverage-gap detection: ignored-hrefs registry, Repairs issue, redaction

Implements the first half of the device-capability-diagnostics spec:

- registry/capabilities/ignored.py: known-noise hrefs (Bixby/voice
  provisioning, WiFi/BLE info, OTA/region housekeeping, and a couple of
  redundant hrefs) declared as no-entity Capability objects, so
  discover()'s existing unknown-resource reporting treats them as covered
  instead of flagging every device as having gaps. Folded into each
  by_type registry and into the global fallback CAPABILITIES set.
- discovery.py: log() callback now passes the raw href instead of a
  formatted message, so callers can collect a clean unbound-hrefs list.
- coordinator.py: wires that callback into self._unbound_hrefs, tracks
  device_type_name/one_ui_version, and raises (or clears) a Repairs issue
  when a device's type is unrecognized or it has genuinely unmodeled
  hrefs left over.
- registry/redact.py: recursive, substring-keyed redaction for anything
  that looks like account/identity data, ahead of the diagnostics.py
  platform that will consume it.

Verified against the real dishwasher/refrigerator fixtures: known-noise
hrefs no longer show up as gaps, while genuine gaps (e.g. /bespoke/vs/0
on the fridge) still do.
This commit is contained in:
Marc Billow committed 2026-07-07 23:49:58 -05:00
1 parent b67e0e5cf5
commit 35b47d6b5a
14 files changed
+383 -11

No files matched your search

@@ -1,10 +1,11 @@
"""Dishwasher device registry."""
from ..capabilities import common, dishwasher, fridge, laundry, operational
from ..capabilities import common, dishwasher, fridge, ignored, laundry, operational
from ._base import DeviceRegistry, _build
REGISTRY = DeviceRegistry(
name='dishwasher',
capabilities=_build([
*ignored.IGNORED,
common.POWER,
common.KIDS_LOCK,
common.REMOTE_CONTROL,
@@ -3,12 +3,13 @@
Note: dryer devices use port 49155 (not 49154). The config flow handles
this automatically via port probing.
"""
from ..capabilities import common, dryer, fridge, laundry, operational
from ..capabilities import common, dryer, fridge, ignored, laundry, operational
from ._base import DeviceRegistry, _build
REGISTRY = DeviceRegistry(
name='dryer',
capabilities=_build([
*ignored.IGNORED,
common.POWER,
common.KIDS_LOCK,
common.REMOTE_CONTROL,
@@ -1,10 +1,11 @@
"""Oven device registry."""
from ..capabilities import common, fridge, oven
from ..capabilities import common, fridge, ignored, oven
from ._base import DeviceRegistry, _build
REGISTRY = DeviceRegistry(
name='oven',
capabilities=_build([
*ignored.IGNORED,
common.POWER,
common.KIDS_LOCK,
common.REMOTE_CONTROL,
@@ -1,10 +1,11 @@
"""Refrigerator device registry."""
from ..capabilities import common, fridge
from ..capabilities import common, fridge, ignored
from ._base import DeviceRegistry, _build
REGISTRY = DeviceRegistry(
name='refrigerator',
capabilities=_build([
*ignored.IGNORED,
common.POWER,
fridge.STATUS_LOCK,
fridge.DOOR_ALERT,
@@ -1,4 +1,4 @@
from . import common, dishwasher, fridge, laundry, operational, oven
from . import common, dishwasher, fridge, ignored, laundry, operational, oven
from ..capability import Capability
@@ -16,4 +16,4 @@ _OVEN_GLOBAL_CAPS = [
]
ALL = [v for mod in (common, operational, laundry, fridge)
for v in vars(mod).values() if _is_capability(v)] + _OVEN_GLOBAL_CAPS
for v in vars(mod).values() if _is_capability(v)] + _OVEN_GLOBAL_CAPS + ignored.IGNORED
@@ -0,0 +1,67 @@
"""Hrefs deliberately not modeled as capabilities.
Every entry here is either irrelevant plumbing (network/account/OTA
housekeeping that will never be home-automation-relevant) or a duplicate of
state we already expose through a friendlier href. Declaring them here,
rather than leaving them unregistered, keeps discover()'s unknown-resource
reporting limited to genuine coverage gaps.
Capability defaults entities=() and discover() treats any href that
resolves to a capability at all as matched, even one with no entities, so
this list uses the same declaration shape as a real capability with no
extra machinery. Fold into by_type registries (per-family gap detection)
and into the global ALL list (unknown-device-type fallback).
Deliberately exact hrefs only, no href_prefix/pattern capabilities: the
unknown-device-type fallback path (coordinator's `discover(resources,
CAPABILITIES)` call) doesn't pass pattern_caps, so a prefix-based entry
here would silently do nothing on that path. Enumerate each known href
instead; it's a short, stable list.
This list is maintainer-curated only; there is no per-installation
override. Grow it as real /device/0 dumps surface more universal noise —
do not add a href here on a guess. If a href's relevance is unclear, leave
it unbound so it surfaces as a gap for a human to look at.
"""
from ..capability import Capability
IGNORED: list[Capability] = [
# Device serial/model is read directly by the coordinator for HA device
# identity, not modeled as an entity capability.
Capability(href='/information/vs/0'),
# Bixby voice assistant: feature negotiation, account provisioning
# (Samsung account email, access tokens), terms-of-service state, and
# enable/disable status.
Capability(href='/voice/feature/vs/0'),
Capability(href='/voice/provisioning/vs/0'),
Capability(href='/bixby/vs/0'),
Capability(href='/bixby/status/vs/0'),
Capability(href='/bixbyuservalidate/vs/0'),
Capability(href='/bixbyterms/vs/0'),
# Network/WiFi housekeeping — MAC addresses, supported auth/crypto
# types, no controllable or observable appliance state.
Capability(href='/wirelessinfo/vs/0'),
Capability(href='/connectionconfig/vs/0'),
# Static or internal-protocol metadata, not entity-worthy.
Capability(href='/quickcontrol/info/vs/0'),
Capability(href='/realtimenotiforclient/vs/0'),
Capability(href='/file/information/vs/0'),
Capability(href='/configuration/vs/0'), # region/countryCode
Capability(href='/setting/vs/0'), # supported/selected UI language
Capability(href='/timezone/vs/0'), # redundant with HA's own timezone
Capability(href='/wm/setinfo/vs/0'), # model/manufacturing metadata
# Demand Response Load Control — utility-company grid signals; requires
# cloud registration with a utility program we don't support locally.
Capability(href='/drlc/vs/0'),
# Redundant with capabilities already declared elsewhere.
# /speakersound/vs/0 duplicates /settings/sound/volume/vs/0 (laundry.SOUND_VOLUME).
Capability(href='/speakersound/vs/0'),
# /wm/editcourse/vs/0 is the raw encoded course-list byte string already
# decoded and exposed via /course/vs/0 (dishwasher.CYCLE_OPTIONS).
Capability(href='/wm/editcourse/vs/0'),
]
@@ -2,7 +2,8 @@
A device advertises a set of OCF resources keyed by href. For every href
present in the registry, emit the capability's entities bound to that resource.
Unknown hrefs are a coverage gap, logged at debug and skipped.
Unknown hrefs are a coverage gap; each one is passed to the optional `log`
callback (as the raw href, not a formatted message) and otherwise skipped.
"""
from __future__ import annotations
@@ -79,6 +80,6 @@ def discover(
break
if not matched and log is not None:
log(f"unknown resource {href}")
log(href)
return out
@@ -0,0 +1,41 @@
"""Redact account/identity data from a raw resource tree before it leaves
the user's Home Assistant instance (diagnostics downloads, issue reports).
/device/0 dumps mix appliance state with genuinely sensitive data when
Bixby/voice is set up on the device: a Samsung account email, a Bixby
access token, a hashed device ID, WiFi/BLE MAC addresses, the serial
number, and otnDUID. This walks the whole tree and redacts any value whose
key matches a known-sensitive substring, regardless of which href it's
under — new device types will have unknown-shaped data we can't fully
enumerate in advance, so this errs on catching the field by name rather
than only redacting inside hrefs we already recognize.
"""
from __future__ import annotations
REDACTED = "**REDACTED**"
_SENSITIVE_SUBSTRINGS = (
'mac', 'serial', 'token', 'login', 'account', 'email',
'userid', 'deviceid', 'uuid', 'duid', 'password', 'secret',
)
def _is_sensitive_key(key: str) -> bool:
lowered = key.lower()
return any(s in lowered for s in _SENSITIVE_SUBSTRINGS)
def redact_resources(resources):
"""Recursively redact dict values whose key matches a sensitive substring.
Works on the shape produced by parse_device0_batch (dict[href, rep]) or
any nested dict/list structure within a rep.
"""
if isinstance(resources, dict):
return {
key: (REDACTED if _is_sensitive_key(key) else redact_resources(value))
for key, value in resources.items()
}
if isinstance(resources, list):
return [redact_resources(item) for item in resources]
return resources