fix(oauth): unwrap U-Tec {code,data} token envelope + surface INVALID_TOKEN

U-Tec's /token endpoint returns the OAuth token nested under
{"code":200,"data":{access_token,...}} instead of the RFC-6749 fields at the
top level. HA's stock OAuth2 implementations look for access_token/expires_in
at the top level, so token refresh silently produced no usable token. The
access token then went stale/revoked and every API call came back as an
HTTP-200 INVALID_TOKEN error envelope, which the integration treated as
success -- so entities froze on last-known state with no error, no
unavailable, and no reauth prompt.

Two fixes, both in custom_components/u_tec:

1. Unwrap the envelope (oauth.py): _unwrap_utec_token lifts data.{...} to the
   top level for both the authorization-code and refresh-token grants. Wired
   via UtecAuthImplementation (runtime/refresh, through
   application_credentials.async_get_auth_implementation) and
   UtecLocalOAuth2Implementation (config-flow auth/reauth).

2. Surface auth failure (coordinator.py): _raise_for_error_payload maps
   payload.error INVALID_TOKEN -> ConfigEntryAuthFailed (HA triggers reauth +
   marks entities unavailable) and other codes -> UpdateFailed, from both the
   poll and discovery. Discovery uses auth_only so a revoked token surfaces at
   setup/reload instead of silently building 0 devices (which wiped entities).

Also fixes a stale test: HA core changed LocalOAuth2Implementation.name from
"Configuration.yaml" to "Local application credentials"; assert the durable
behavior (static "U-Tec" entry title) rather than HA's internal label.

Tests: tests/test_oauth.py, tests/test_oauth_wiring.py, and coordinator
error-envelope cases in tests/test_coordinator.py.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: geofffranks

custom_components/u_tec/application_credentials.py

@@ -1,9 +1,14 @@
 """Application credentials platform for the Uhome integration."""
 
-from homeassistant.components.application_credentials import AuthorizationServer
+from homeassistant.components.application_credentials import (
+    AuthorizationServer,
+    ClientCredential,
+)
 from homeassistant.core import HomeAssistant
+from homeassistant.helpers import config_entry_oauth2_flow
 
 from .const import OAUTH2_AUTHORIZE, OAUTH2_TOKEN
+from .oauth import UtecAuthImplementation
 
 
 async def async_get_authorization_server(hass: HomeAssistant) -> AuthorizationServer:
@@ -12,3 +17,20 @@ async def async_get_authorization_server(hass: HomeAssistant) -> AuthorizationSe
         authorize_url=OAUTH2_AUTHORIZE,
         token_url=OAUTH2_TOKEN,
     )
+
+
+async def async_get_auth_implementation(
+    hass: HomeAssistant, auth_domain: str, credential: ClientCredential
+) -> config_entry_oauth2_flow.AbstractOAuth2Implementation:
+    """Return a custom auth implementation that unwraps U-Tec's token envelope.
+
+    Defining this hook overrides application_credentials' default
+    AuthImplementation for the runtime (refresh) path, so token refresh can
+    parse U-Tec's non-standard ``{code,data}`` response. See ``oauth.py``.
+    """
+    return UtecAuthImplementation(
+        hass,
+        auth_domain,
+        credential,
+        await async_get_authorization_server(hass),
+    )

custom_components/u_tec/config_flow.py

@@ -48,6 +48,7 @@
     OAUTH2_AUTHORIZE,
     OAUTH2_TOKEN,
 )
+from .oauth import UtecLocalOAuth2Implementation
 
 
 OPTIMISTIC_MODE_ALL = "all"
@@ -140,7 +141,10 @@ async def async_step_replace_credentials(
                 )
 
             self._pending_credential = ClientCredential(client_id, client_secret)
-            self.flow_impl = config_entry_oauth2_flow.LocalOAuth2Implementation(
+            # Unwrapping implementation: U-Tec's /token returns the OAuth fields
+            # nested under {"code","data"}, which HA's stock implementation can't
+            # parse. See oauth.py.
+            self.flow_impl = UtecLocalOAuth2Implementation(
                 self.hass,
                 DOMAIN,
                 client_id,

custom_components/u_tec/coordinator.py

@@ -26,6 +26,34 @@
 _LOGGER = logging.getLogger(__name__)
 
 
+def _raise_for_error_payload(response, *, auth_only: bool = False) -> None:
+    """Surface U-Tec error envelopes returned with an HTTP 2xx status.
+
+    U-Tec replies HTTP 200 even on failure, carrying the error under
+    ``payload.error`` (e.g. ``{"code": "INVALID_TOKEN", "message": ...}``).
+    Left unraised, a revoked/expired token is swallowed and the coordinator
+    serves stale state indefinitely with no reauth prompt. ``INVALID_TOKEN``
+    becomes ``ConfigEntryAuthFailed`` (so HA triggers reauth and marks entities
+    unavailable); other error codes become ``UpdateFailed`` unless ``auth_only``
+    is set — discovery only needs to surface auth failures and lets other
+    errors fall through to its existing graceful handling.
+    """
+    if not isinstance(response, dict):
+        return
+    payload = response.get("payload")
+    if not isinstance(payload, dict):
+        return
+    error = payload.get("error")
+    if not isinstance(error, dict):
+        return
+    code = error.get("code")
+    message = error.get("message", "")
+    if code == "INVALID_TOKEN":
+        raise ConfigEntryAuthFailed(f"U-Tec rejected access token: {message}")
+    if not auth_only:
+        raise UpdateFailed(f"U-Tec API error {code}: {message}")
+
+
 class UhomeDataUpdateCoordinator(DataUpdateCoordinator):
     """Class to manage fetching Uhome data."""
 
@@ -88,6 +116,11 @@ async def async_discover_devices(self) -> None:
             _LOGGER.error("Invalid discovery data received: %s", discovery_data)
             return
 
+        # A revoked token returns an INVALID_TOKEN envelope here; surface it so
+        # setup/reload fails into reauth instead of silently building 0 devices
+        # (which wipes every entity to unavailable on reload).
+        _raise_for_error_payload(discovery_data, auth_only=True)
+
         devices_data = discovery_data.get("payload", {}).get("devices", [])
         _LOGGER.debug("Found %s devices in discovery data", len(devices_data))
 
@@ -152,6 +185,11 @@ async def _async_update_data(self) -> dict[str, dict]:
         except ApiError as err:
             raise UpdateFailed(f"Error communicating with API: {err}") from err
 
+        # U-Tec returns HTTP 200 with an error envelope (e.g. INVALID_TOKEN) that
+        # get_device_state does not raise on — surface it instead of treating an
+        # error response as an empty-but-successful poll.
+        _raise_for_error_payload(response)
+
         if response and "payload" in response:
             for device_data in response["payload"].get("devices", []):
                 device_id = device_data.get("id")

custom_components/u_tec/oauth.py

@@ -0,0 +1,60 @@
+"""Custom OAuth2 implementations for U-Tec.
+
+U-Tec's token endpoint (``https://oauth.u-tec.com/token``) returns the OAuth
+token wrapped in a non-standard envelope::
+
+    {"code": 200, "data": {"access_token": ..., "token_type": "Bearer",
+                           "expires_in": 601200, "scope": "openapi", ...}}
+
+Home Assistant's stock OAuth2 implementations expect the RFC-6749 fields at the
+top level, so without unwrapping the refresh (and authorization-code) grant
+silently produces no usable token and the access token goes stale. These
+subclasses unwrap the envelope for both paths: the config-flow
+``LocalOAuth2Implementation`` and the runtime application-credentials
+``AuthImplementation``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from homeassistant.components.application_credentials import AuthImplementation
+from homeassistant.helpers import config_entry_oauth2_flow
+
+
+def _unwrap_utec_token(result: Any) -> dict:
+    """Lift U-Tec's nested token payload to the top level.
+
+    Accepts both the wrapped ``{"code","data":{...}}`` shape and an
+    already-standard response (passthrough). Raises ``ValueError`` when no
+    ``access_token`` is present (an error envelope), so the caller fails loudly
+    instead of persisting a token dict with no usable access token.
+    """
+    if isinstance(result, dict) and "access_token" in result:
+        return result
+    if isinstance(result, dict):
+        data = result.get("data")
+        if isinstance(data, dict) and "access_token" in data:
+            return data
+    raise ValueError(f"U-Tec token response missing access_token: {result!r}")
+
+
+class _UtecTokenUnwrapMixin:
+    """Mixin unwrapping U-Tec's ``{code,data}`` token envelope.
+
+    Overrides ``_token_request`` — used by both the authorization-code and
+    refresh-token grants — to normalise the response before HA consumes it.
+    """
+
+    async def _token_request(self, data: dict) -> dict:
+        return _unwrap_utec_token(await super()._token_request(data))
+
+
+class UtecLocalOAuth2Implementation(
+    _UtecTokenUnwrapMixin, config_entry_oauth2_flow.LocalOAuth2Implementation
+):
+    """Config-flow LocalOAuth2Implementation with U-Tec envelope unwrapping."""
+
+
+class UtecAuthImplementation(_UtecTokenUnwrapMixin, AuthImplementation):
+    """Runtime application-credentials AuthImplementation with envelope unwrapping."""

tests/test_config_flow.py

@@ -74,11 +74,12 @@ async def test_async_oauth_create_entry_builds_entry(hass):
 async def test_async_oauth_create_entry_title_independent_of_flow_impl_name(hass):
     """Title uses a static integration name, not flow_impl.name.
 
-    LocalOAuth2Implementation.name returns the literal string "Configuration.yaml"
-    (hardcoded in HA core for yaml-configured impls). The deferred-credential
-    flow builds a LocalOAuth2Implementation directly, so using flow_impl.name
-    as the entry title would produce a confusing "Configuration.yaml" entry in
-    the UI. Title must be a static, recognisable integration name.
+    LocalOAuth2Implementation.name returns a generic HA-internal label whose
+    exact value is version-dependent (e.g. "Configuration.yaml" on older cores,
+    "Local application credentials" on current ones). The deferred-credential
+    flow builds a LocalOAuth2Implementation directly, so using flow_impl.name as
+    the entry title would surface that confusing label in the UI. Title must be a
+    static, recognisable integration name regardless of the HA-core string.
     """
     from homeassistant.helpers.config_entry_oauth2_flow import (
         LocalOAuth2Implementation,
@@ -92,8 +93,10 @@ async def test_async_oauth_create_entry_title_independent_of_flow_impl_name(hass
     handler.flow_impl = LocalOAuth2Implementation(
         hass, DOMAIN, "test-id", "test-secret", OAUTH2_AUTHORIZE, OAUTH2_TOKEN,
     )
-    # Sanity check: HA core really does return this literal string.
-    assert handler.flow_impl.name == "Configuration.yaml"
+    # flow_impl.name is a generic HA-internal label (version-dependent) and,
+    # crucially, NOT our integration name — so the static title asserted below
+    # cannot have been derived from it.
+    assert handler.flow_impl.name != "U-Tec"
 
     result = await handler.async_oauth_create_entry({"token": {"access_token": "t"}})
 

tests/test_coordinator.py

@@ -281,3 +281,59 @@ async def test_discover_device_missing_id_is_skipped(coordinator, mock_uhome_api
     }
     await coordinator.async_discover_devices()
     assert coordinator.devices == {}
+
+
+# --- error-envelope surfacing (U-Tec returns HTTP 200 with payload.error) ---
+
+
+async def test_async_update_data_invalid_token_payload_raises_config_entry_auth_failed(
+    coordinator, mock_uhome_api,
+):
+    """A revoked/expired token comes back as an HTTP-200 INVALID_TOKEN envelope.
+
+    It must surface as ConfigEntryAuthFailed (→ reauth + entities unavailable),
+    not be swallowed as success (which left HA serving stale state silently).
+    """
+    coordinator.devices["sw-1"] = make_fake_switch("sw-1")
+    mock_uhome_api.get_device_state.return_value = {
+        "payload": {"error": {"code": "INVALID_TOKEN", "message": "expired"}}
+    }
+    with pytest.raises(ConfigEntryAuthFailed):
+        await coordinator._async_update_data()
+
+
+async def test_async_update_data_other_error_payload_raises_update_failed(
+    coordinator, mock_uhome_api,
+):
+    coordinator.devices["sw-1"] = make_fake_switch("sw-1")
+    mock_uhome_api.get_device_state.return_value = {
+        "payload": {"error": {"code": "INTERNAL_ERROR", "message": "boom"}}
+    }
+    with pytest.raises(UpdateFailed):
+        await coordinator._async_update_data()
+
+
+async def test_async_update_data_success_payload_still_returns(coordinator, mock_uhome_api):
+    """Regression guard: a normal devices payload is unaffected by the error check."""
+    sw = make_fake_switch("sw-1")
+    sw.get_state_data = lambda: {"st.switch": {"switch": "on"}}
+    coordinator.devices["sw-1"] = sw
+    mock_uhome_api.get_device_state.return_value = {
+        "payload": {"devices": [
+            {"id": "sw-1", "states": [{"capability": "st.switch", "name": "switch", "value": "on"}]},
+        ]}
+    }
+    result = await coordinator._async_update_data()
+    assert "sw-1" in result
+
+
+async def test_discover_invalid_token_payload_raises_config_entry_auth_failed(
+    coordinator, mock_uhome_api,
+):
+    """A bad token during discovery must surface (→ reauth), not silently yield
+    zero devices — which on reload wipes every entity to unavailable."""
+    mock_uhome_api.discover_devices.return_value = {
+        "payload": {"error": {"code": "INVALID_TOKEN", "message": "expired"}}
+    }
+    with pytest.raises(ConfigEntryAuthFailed):
+        await coordinator.async_discover_devices()

tests/test_oauth.py

@@ -0,0 +1,57 @@
+"""Tests for U-Tec OAuth token-envelope unwrapping.
+
+U-Tec's /token endpoint wraps the token under {"code","data":{...}} instead of
+returning the RFC-6749 fields at the top level. Home Assistant's stock OAuth2
+implementation looks for access_token/expires_in at the top level, so without
+unwrapping a token refresh silently yields no usable token and the access token
+goes stale. These cover the unwrap and its wiring into the implementations.
+"""
+
+from aioresponses import aioresponses
+import pytest
+
+from custom_components.u_tec.const import DOMAIN, OAUTH2_AUTHORIZE, OAUTH2_TOKEN
+from custom_components.u_tec.oauth import (
+    UtecLocalOAuth2Implementation,
+    _unwrap_utec_token,
+)
+
+_WRAPPED = {
+    "code": 200,
+    "data": {
+        "access_token": "abc123",
+        "token_type": "Bearer",
+        "expires_in": 601200,
+        "scope": "openapi",
+        "refresh_token": "r-456",
+    },
+}
+
+
+def test_unwrap_lifts_nested_data_to_top_level():
+    assert _unwrap_utec_token(_WRAPPED) == _WRAPPED["data"]
+
+
+def test_unwrap_passthrough_standard_response():
+    standard = {"access_token": "xyz", "token_type": "Bearer", "expires_in": 3600}
+    assert _unwrap_utec_token(standard) == standard
+
+
+def test_unwrap_raises_when_no_access_token_present():
+    with pytest.raises(ValueError):
+        _unwrap_utec_token({"code": 401, "data": {"message": "bad refresh token"}})
+
+
+async def test_local_impl_token_request_unwraps(hass):
+    """_token_request against the real {code,data} envelope returns standard fields."""
+    impl = UtecLocalOAuth2Implementation(
+        hass, DOMAIN, "client-id", "client-secret", OAUTH2_AUTHORIZE, OAUTH2_TOKEN,
+    )
+    with aioresponses() as mock:
+        mock.post(OAUTH2_TOKEN, payload=_WRAPPED)
+        result = await impl._token_request(
+            {"grant_type": "refresh_token", "refresh_token": "r"}
+        )
+    assert result["access_token"] == "abc123"
+    assert result["expires_in"] == 601200
+    assert result["refresh_token"] == "r-456"

tests/test_oauth_wiring.py

@@ -0,0 +1,67 @@
+"""The unwrapping OAuth implementations must be wired into both code paths.
+
+Runtime token refresh resolves its implementation via the application_credentials
+platform hook; the config flow builds its own in-memory implementation. Both must
+use the U-Tec envelope-unwrapping classes, or refresh/auth silently break.
+"""
+
+from unittest.mock import AsyncMock, patch
+
+from aioresponses import aioresponses
+
+from custom_components.u_tec.const import DOMAIN, OAUTH2_TOKEN
+from custom_components.u_tec.oauth import (
+    UtecAuthImplementation,
+    UtecLocalOAuth2Implementation,
+)
+
+_WRAPPED = {
+    "code": 200,
+    "data": {
+        "access_token": "abc123",
+        "token_type": "Bearer",
+        "expires_in": 601200,
+        "scope": "openapi",
+    },
+}
+
+
+async def test_application_credentials_returns_unwrapping_implementation(hass):
+    """Runtime path: the app-creds hook returns an unwrapping implementation."""
+    from homeassistant.components.application_credentials import ClientCredential
+
+    from custom_components.u_tec.application_credentials import (
+        async_get_auth_implementation,
+    )
+
+    impl = await async_get_auth_implementation(
+        hass, DOMAIN, ClientCredential("client-id", "client-secret")
+    )
+    assert isinstance(impl, UtecAuthImplementation)
+
+    with aioresponses() as mock:
+        mock.post(OAUTH2_TOKEN, payload=_WRAPPED)
+        result = await impl._token_request(
+            {"grant_type": "refresh_token", "refresh_token": "r"}
+        )
+    assert result["access_token"] == "abc123"
+    assert result["expires_in"] == 601200
+
+
+async def test_config_flow_uses_unwrapping_implementation(hass):
+    """Config-flow path: replace-credentials sets an unwrapping flow_impl."""
+    from custom_components.u_tec.config_flow import UhomeOAuth2FlowHandler
+
+    handler = UhomeOAuth2FlowHandler()
+    handler.hass = hass
+
+    with patch.object(
+        UhomeOAuth2FlowHandler,
+        "async_step_auth",
+        new=AsyncMock(return_value={"type": "external_step"}),
+    ):
+        await handler.async_step_replace_credentials(
+            {"client_id": "client-id", "client_secret": "client-secret"}
+        )
+
+    assert isinstance(handler.flow_impl, UtecLocalOAuth2Implementation)