"""Webhook ingress for the in-process ha-mcp server (issue #1527). Ported from the proven webhook-proxy add-on (``mcp_proxy``): an HA webhook (``/api/webhook/``) forwards MCP traffic to the loopback server and streams the response back, so the server is reachable through Nabu Casa remote UI (or any reverse proxy) with the webhook id as the shared secret. Three auth postures, chosen in the options flow: * ``none`` — the secret webhook URL *is* the credential (matches the add-on's default). No bearer is required and the forwarder always returns 200. It still serves our own corrected RFC 8414 / RFC 9728 discovery documents plus an invisible auto-approve authorization server (:mod:`oauth_autoapprove`), so claude.ai's intermittent OAuth discovery resolves against us — not HA core's broken origin-root doc — and connects with no HA login (issue #1969). * ``ha_auth`` — Home Assistant core is the OAuth authorization server. This module serves the RFC 8414 / RFC 9728 discovery documents (so claude.ai / ChatGPT can sign in with the user's HA account) and validates inbound bearer tokens via ``hass.auth``. The component-scoped authorize/token views redirect and forward into core's own ``/auth/*`` endpoints; core remains the authority. * ``legacy`` — this module (via :mod:`oauth_legacy`) is its own OAuth 2.1 authorization server with a static client_id/secret, for MCP clients (Google Gemini Spark) that need a credential to paste rather than an HA sign-in. The forwarding handler mirrors ``mcp_proxy._handle_webhook`` exactly (hop-by-hop header stripping, the SSE streaming branch with anti-buffering headers, the content-type whitelist, ``Mcp-Session-Id`` propagation, and the 502/500 error mapping); the ``ha_auth`` bearer check + discovery documents mirror the add-on's ``auth_native.py`` + the ``ha_auth`` subset of ``oauth.py``; the ``legacy`` provider + its root ``/authorize`` + ``/token`` views live in :mod:`oauth_legacy`, ported from the ``legacy`` subset of the add-on's ``oauth.py``. The seven RFC 8414 / RFC 9728 discovery views below are shared by ``ha_auth``, ``legacy``, and ``none`` (which serves a distinct auto-approve authorization-server document pointing at :mod:`oauth_autoapprove`'s endpoints) — see :func:`active_auth_mode`. """ from __future__ import annotations import inspect import logging from contextlib import suppress from typing import TYPE_CHECKING, Any import aiohttp from aiohttp import web from homeassistant.components.http import HomeAssistantView from homeassistant.components.webhook import async_register, async_unregister from homeassistant.core import HomeAssistant from .const import ( DATA_WEBHOOK, DATA_WEBHOOK_ID, DOMAIN, OAUTH_BASE, WEBHOOK_AUTH_HA, WEBHOOK_AUTH_LEGACY, WEBHOOK_AUTH_NONE, ) from .oauth_autoapprove import ( CFG_AUTOAPPROVE_PROVIDER, CFG_CIMD_SESSION, AutoApproveProvider, bind_autoapprove_views, ) from .oauth_dcr import CFG_DCR_SIGNING_KEY, bind_dcr_view from .oauth_legacy import ( OAUTH_ROUTE_OWNER_KEY, LegacyOAuthProvider, LegacyOAuthRouteConflict, bind_legacy_views, build_unbound_legacy_provider, clear_scoped_legacy_credentials, ) if TYPE_CHECKING: from homeassistant.config_entries import ConfigEntry _LOGGER = logging.getLogger(__name__) # Human-readable webhook name shown in the HA webhook registry. _WEBHOOK_NAME = "HA-MCP in-process server" # Hop-by-hop / sensitive request headers never forwarded upstream (identical set # to mcp_proxy). ``authorization`` is stripped because the server authenticates # to HA with its own provisioned token, not the caller's bearer. _STRIPPED_REQUEST_HEADERS = frozenset( { "host", "content-length", "transfer-encoding", "connection", "cookie", "authorization", } ) # Content-Types the forwarded response may carry as-is; anything else is coerced # to JSON to prevent HTML injection / XSS through the proxy. ``text/plain`` is # safe (a browser never executes it) and lets the server's friendly landing page # — a plain-text 405 shown when a browser GETs the endpoint — render as text # instead of a mislabeled JSON blob. ``text/html`` and friends stay coerced. _ALLOWED_CONTENT_TYPES = ("application/json", "text/event-stream", "text/plain") # Timeout for streamed MCP responses (matches mcp_proxy). Deliberately NO # wall-clock ``total``: an MCP response stream is long-lived by design (the # upcoming spec's ``subscriptions/listen`` holds one open indefinitely), so a # ``total`` bound would cut a *healthy* stream and force the client to # re-subscribe. ``sock_read`` bounds a *dead* one instead — idle detection, not # elapsed time. ``connect`` stays finite: it covers connection-POOL acquisition # (not just the TCP connect ``sock_connect`` bounds), so a pool exhausted by # long-lived streams fails a new request in 30 s instead of hanging it forever. _CLIENT_TIMEOUT = aiohttp.ClientTimeout(connect=30, sock_connect=10, sock_read=300) # Anonymous CIMD lookups get a separate, deliberately small connection pool. # The relay session may hold long-lived SSE connections; public metadata fetches # must never consume that authenticated forwarding capacity. _CIMD_CONNECTOR_LIMIT = 4 # TOP-LEVEL hass.data flag recording that the ha_auth discovery views are bound # for this HA session. Deliberately NOT under DOMAIN so it survives # async_unload_entry's teardown — aiohttp cannot unregister an HTTP view until HA # restarts, so the views (and this ownership flag) must outlive the config entry. _OAUTH_VIEWS_REGISTERED_KEY = "ha_mcp_tools_oauth_metadata_views_registered" # --------------------------------------------------------------------------- # ha_auth resource server (HA core is the OAuth authorization server) # --------------------------------------------------------------------------- def _build_base_url(request: web.Request) -> str: """Build the public base URL from the request (host-derived). ha_auth is always host-derived so the SAME install works via the Nabu Casa cloud URL AND any other external URL. Reads ``X-Forwarded-Proto/Host`` as sent: HA's forwarded middleware only validates proxy headers when ``X-Forwarded-For`` is present, so these can reach us raw. A peer can thereby only shape the discovery/WWW-Authenticate URLs in its OWN response (no cross-user vector), which is within SECURITY.md's local-network trust model; treat stricter proxy validation as optional hardening. """ host = request.headers.get("X-Forwarded-Host") or request.headers.get("Host", "") scheme = request.headers.get("X-Forwarded-Proto", request.scheme) return f"{scheme}://{host}" def _authorization_server_document(base: str) -> dict[str, Any]: """RFC 8414 metadata for ha_auth mode — component-owned endpoints only. HA core is still the authorization server (the scoped /authorize 302s into core's /auth/authorize and /token forwards server-side — see oauth_autoapprove's ha_auth branches), but every URL a client can CACHE is ours: a later auth-mode switch re-dispatches per request instead of stranding the client on core paths we can never retract (#2188's stickiness). ``registration_endpoint`` serves DCR-fallback brokers; both CIMD-selection flags stay pinned (see test_as_documents_pin_the_claude_cimd_selection_contract). ``revocation_endpoint`` is ours for a second reason (#2248): the refresh token the client holds is a signed envelope, and core's own ``/auth/revoke`` answers 200 without revoking anything for a value it cannot recognise. Only ha_auth mints those, so only this document advertises it. The endpoint takes no client authentication, matching ``token_endpoint_auth_methods_supported``. """ return { "issuer": f"{base}{OAUTH_BASE}", "authorization_endpoint": f"{base}{OAUTH_BASE}/authorize", "token_endpoint": f"{base}{OAUTH_BASE}/token", "registration_endpoint": f"{base}{OAUTH_BASE}/register", "revocation_endpoint": f"{base}{OAUTH_BASE}/revoke", "revocation_endpoint_auth_methods_supported": ["none"], "response_types_supported": ["code"], "grant_types_supported": ["authorization_code", "refresh_token"], "code_challenge_methods_supported": ["S256"], "token_endpoint_auth_methods_supported": ["none"], "client_id_metadata_document_supported": True, } class ResourceServer: """ha_auth resource server: bearer validation + discovery URL building. Owns no signing key, no client credentials, and binds no root views — HA core is the authorization server. Held by the discovery views and the webhook handler. """ def __init__(self, hass: HomeAssistant, webhook_id: str) -> None: """Bind to the HA instance and this install's webhook id.""" self._hass = hass self._webhook_id = webhook_id @property def webhook_id(self) -> str: """This install's private webhook id.""" return self._webhook_id async def validate_request(self, request: web.Request) -> bool: """Return True iff the request carries a Bearer token HA core accepts. A missing/malformed ``Authorization`` header is rejected without touching the validator. ``hass.auth.async_validate_access_token`` is a synchronous ``@callback`` in HA core; it is awaited defensively in case a future release makes it a coroutine, and any raise is treated as unauthorized so a crafted token yields a 401 challenge rather than a 500. """ header = request.headers.get("Authorization", "") if not header.lower().startswith("bearer "): return False token = header[7:].strip() if not token: return False try: result = self._hass.auth.async_validate_access_token(token) if inspect.isawaitable(result): result = await result except Exception: _LOGGER.debug( "ha_auth: bearer validation raised; treating as unauthorized", exc_info=True, ) return False if result is None: return False # ADMIN-ONLY: the server performs every Home Assistant operation with # its own provisioned ADMIN token, so accepting any valid login would # grant every household member admin-equivalent control. Require an # active, human, administrator account (mirrors the settings panel). user = getattr(result, "user", None) if user is None: return False if getattr(user, "system_generated", False): return False if not getattr(user, "is_active", False): return False return bool(getattr(user, "is_admin", False)) # --------------------------------------------------------------------------- # RFC 8414 / RFC 9728 discovery views (ha_auth + legacy modes) # --------------------------------------------------------------------------- def _active_webhook_cfg(hass: HomeAssistant) -> dict[str, Any] | None: """Return the live webhook forwarding cfg dict, or None if not set up.""" domain_data = hass.data.get(DOMAIN) if not isinstance(domain_data, dict): return None cfg = domain_data.get(DATA_WEBHOOK) return cfg if isinstance(cfg, dict) else None def active_auth_mode(hass: HomeAssistant) -> str | None: """Return the OAuth-relevant auth mode of the live webhook registration. ``WEBHOOK_AUTH_HA``, ``WEBHOOK_AUTH_LEGACY``, or ``WEBHOOK_AUTH_NONE`` (the none-mode auto-approve surface, issue #1969), or None when no discovery surface is live. Checked via PROVIDER PRESENCE, not the raw configured ``auth_mode`` string, so local-only mode (remote webhook disabled by option — ``register_endpoint=False`` in ``async_register_webhook``) correctly reports None even when ``webhook_auth`` is set: no provider is constructed for a webhook that was never registered, so there is nothing to advertise or authenticate against. Read live from hass.data (not captured at view/provider construction time) so the SAME registered/bound instances serve whichever mode is active now — mirrors the add-on's ``_active_oauth_mode``. Used by the discovery views below AND by ``LegacyOAuthProvider.is_active`` (via the getter passed into :func:`oauth_legacy.bind_legacy_views`) so the root ``/authorize``/``/token`` views, which aiohttp can never unbind, 404 once the operator switches away from legacy (or to local-only mode) without a restart. The webhook forwarder's own bearer gate (``_async_handle_webhook``) reads ``cfg["resource_server"]`` / ``cfg["oauth_provider"]`` directly instead of through this function — it already has ``cfg`` in hand and needs the provider OBJECT, not just the mode name. """ cfg = _active_webhook_cfg(hass) if cfg is None: return None if cfg.get("resource_server") is not None: return WEBHOOK_AUTH_HA if cfg.get("oauth_provider") is not None: return WEBHOOK_AUTH_LEGACY if cfg.get(CFG_AUTOAPPROVE_PROVIDER) is not None: return WEBHOOK_AUTH_NONE return None def _active_webhook_id(hass: HomeAssistant) -> str | None: """Webhook id of the live registration, gated the same as the AS document (None whenever :func:`active_auth_mode` is None) so the protected-resource document 404s in exactly the same cases.""" if active_auth_mode(hass) is None: return None cfg = _active_webhook_cfg(hass) return cfg.get("webhook_id") if cfg is not None else None def _json_not_found() -> web.Response: """404 JSON body used by stale-but-bound discovery views.""" return web.json_response({"error": "not_found"}, status=404) def _protected_resource_document(webhook_id: str, base: str) -> dict[str, Any]: """RFC 9728 protected-resource document for ``webhook_id`` under ``base``. Identical shape in both OAuth modes — only the authorization-server document (below) differs by mode. """ return { "resource": f"{base}/api/webhook/{webhook_id}", "authorization_servers": [f"{base}{OAUTH_BASE}"], "bearer_methods_supported": ["header"], "resource_documentation": "https://github.com/homeassistant-ai/ha-mcp", } def oauth_issuer(base: str) -> str: """Issuer identifier this component's OWN authorization servers advertise. Single source for the ``issuer`` field of the legacy and none-mode documents below and for the RFC 9207 ``iss`` authorization-response parameter that :mod:`oauth_legacy` / :mod:`oauth_autoapprove` put on their redirects — RFC 9207 §2 requires the redirect's ``iss`` to equal the advertised issuer exactly. """ return f"{base}{OAUTH_BASE}" def issuer_for_request(request: web.Request) -> str: """:func:`oauth_issuer` for the public base URL ``request`` resolves to.""" return oauth_issuer(_build_base_url(request)) def _legacy_authorization_server_document(base: str) -> dict[str, Any]: """RFC 8414 metadata for legacy mode's component-scoped endpoints. The root ``/authorize`` + ``/token`` views remain bound as aliases for metadata-ignoring clients (see :mod:`oauth_legacy`). """ return { "issuer": oauth_issuer(base), # RFC 9207 §3: authorization responses carry ``iss`` (oauth_legacy's # redirects); omission reads as "not supported" to discovery clients. "authorization_response_iss_parameter_supported": True, "authorization_endpoint": f"{base}{OAUTH_BASE}/authorize", "token_endpoint": f"{base}{OAUTH_BASE}/token", "response_types_supported": ["code"], "grant_types_supported": ["authorization_code", "refresh_token"], "code_challenge_methods_supported": ["S256"], "token_endpoint_auth_methods_supported": [ "client_secret_basic", "client_secret_post", ], } def _none_mode_authorization_server_document(base: str) -> dict[str, Any]: """RFC 8414 authorization-server metadata for none mode's auto-approve server. Points at OUR OWN ``OAUTH_BASE`` ``/authorize`` + ``/token`` (the invisible auto-approve endpoints in :mod:`oauth_autoapprove`), NOT HA core's ``/auth/*``. Serving this — with ``token_endpoint_auth_methods_supported: ["none"]`` (public PKCE client) and ``client_id_metadata_document_supported`` — is the none-mode fix: claude.ai's intermittent discovery resolves against this corrected document instead of HA core's origin-root ``/.well-known/oauth-authorization-server``, which omits the ``"none"`` auth method and has no ``registration_endpoint`` (issue #1969). No refresh grant: the token is cosmetic (none mode ignores bearers), so only ``authorization_code`` is advertised. """ return { "issuer": oauth_issuer(base), # RFC 9207 §3: authorization responses carry ``iss`` (the auto-approve # redirects); omission reads as "not supported" to discovery clients. "authorization_response_iss_parameter_supported": True, "authorization_endpoint": f"{base}{OAUTH_BASE}/authorize", "token_endpoint": f"{base}{OAUTH_BASE}/token", "registration_endpoint": f"{base}{OAUTH_BASE}/register", "response_types_supported": ["code"], "grant_types_supported": ["authorization_code"], "code_challenge_methods_supported": ["S256"], "token_endpoint_auth_methods_supported": ["none"], "client_id_metadata_document_supported": True, } class _ProtectedResourceMetadataView(HomeAssistantView): """RFC 9728 Protected Resource Metadata.""" requires_auth = False cors_allowed = True url = f"{OAUTH_BASE}/protected-resource" name = "ha_mcp_tools:oauth:protected-resource" def __init__(self, hass: HomeAssistant) -> None: """Bind the view to the HA instance; liveness is resolved per request.""" self._hass = hass async def get(self, request: web.Request) -> web.Response: """Serve the protected-resource document for the bearer-gated modes only. SECURITY (#1976 review): this ANONYMOUS, fixed (guessable) path exposes ``resource: /api/webhook/``. In none mode the webhook id is the SOLE credential, so serving it here would leak it to any unauthenticated GET. Serve only for ``ha_auth``/``legacy`` (where the id is not a secret and the 401 ``WWW-Authenticate`` pointer legitimately directs a client here); 404 otherwise. The PATH-SCOPED well-known view still serves in none mode — its caller must already know the id (it is a route parameter). """ if active_auth_mode(self._hass) not in (WEBHOOK_AUTH_HA, WEBHOOK_AUTH_LEGACY): return _json_not_found() webhook_id = _active_webhook_id(self._hass) if webhook_id is None: return _json_not_found() return web.json_response( _protected_resource_document(webhook_id, _build_base_url(request)) ) class _AuthorizationServerMetadataView(HomeAssistantView): """RFC 8414 Authorization Server Metadata. Every mode advertises the component-scoped authorize/token pair; the bound views dispatch each request according to the currently active mode. """ requires_auth = False cors_allowed = True url = f"{OAUTH_BASE}/authorization-server" name = "ha_mcp_tools:oauth:authorization-server" def __init__(self, hass: HomeAssistant) -> None: """Bind the view to the HA instance; liveness is resolved per request.""" self._hass = hass async def get(self, request: web.Request) -> web.Response: """Serve the AS document (or 404 when no OAuth mode is live).""" mode = active_auth_mode(self._hass) if mode is None: return _json_not_found() base = _build_base_url(request) if mode == WEBHOOK_AUTH_LEGACY: return web.json_response(_legacy_authorization_server_document(base)) if mode == WEBHOOK_AUTH_NONE: return web.json_response(_none_mode_authorization_server_document(base)) return web.json_response(_authorization_server_document(base)) class _WellKnownProtectedResourceView(HomeAssistantView): """RFC 9728 §3.1 path-scoped Protected Resource Metadata. Same document as :class:`_ProtectedResourceMetadataView`, served at the well-known location derived from the webhook resource URL — claude.ai's first fallback probe when the 401's ``resource_metadata`` pointer is missing. The webhook id is a ROUTE PARAMETER (not baked into the path at registration): a remove + re-add of the entry mints a new webhook id in the same HA session, and the bound view must serve whichever id is currently live (404 for any other). Standalone view (not a subclass of the plain document view) because its handler takes the extra route parameter. """ requires_auth = False cors_allowed = True name = "ha_mcp_tools:oauth:wellknown-protected-resource" url = "/.well-known/oauth-protected-resource/api/webhook/{webhook_id}" def __init__(self, hass: HomeAssistant) -> None: """Bind the view to the HA instance; liveness is resolved per request.""" self._hass = hass async def get(self, request: web.Request, webhook_id: str) -> web.Response: """Serve the document only for the CURRENT entry's webhook id.""" active_id = _active_webhook_id(self._hass) if active_id is None or webhook_id != active_id: return _json_not_found() return web.json_response( _protected_resource_document(active_id, _build_base_url(request)) ) class _WellKnownAuthorizationServerMetadataView(_AuthorizationServerMetadataView): """RFC 8414 / OIDC-discovery locations for the AS metadata document. Same document as :class:`_AuthorizationServerMetadataView`, registered at the well-known URLs MCP clients actually probe for the issuer. """ def __init__(self, hass: HomeAssistant, url: str, name: str) -> None: """Bind and set an explicit well-known URL + unique view name.""" super().__init__(hass) self.url = url self.name = name def _metadata_views(hass: HomeAssistant) -> list[HomeAssistantView]: """Build the seven discovery-document views, shared by ha_auth and legacy (mode-agnostic — each view resolves the active mode per request).""" views: list[HomeAssistantView] = [ _ProtectedResourceMetadataView(hass), _AuthorizationServerMetadataView(hass), _WellKnownProtectedResourceView(hass), ] for url, name in ( ( f"/.well-known/oauth-authorization-server{OAUTH_BASE}", "ha_mcp_tools:oauth:wellknown-as-rfc8414", ), ( f"/.well-known/openid-configuration{OAUTH_BASE}", "ha_mcp_tools:oauth:wellknown-oidc-prefixed", ), ( f"{OAUTH_BASE}/.well-known/openid-configuration", "ha_mcp_tools:oauth:wellknown-oidc-suffixed", ), ( f"{OAUTH_BASE}/.well-known/oauth-authorization-server", "ha_mcp_tools:oauth:wellknown-as-suffixed", ), ): views.append( _WellKnownAuthorizationServerMetadataView(hass, url=url, name=name) ) return views def _register_metadata_views(hass: HomeAssistant) -> None: """Register the seven discovery views at most once per HA session. aiohttp cannot unregister a bound view, so a reload / re-enable / re-add / ha_auth<->legacy mode switch must all reuse the already-bound views — they resolve the ACTIVE mode + provider from hass.data per request (see ``active_auth_mode``), so a later entry (even with a new webhook id, or a different auth mode) is served correctly. The guard flag lives at a top-level hass.data key that survives config-entry teardown. """ if hass.data.get(_OAUTH_VIEWS_REGISTERED_KEY): return # Set the flag only AFTER every view registers (issue #1978): it must mean # "the full bundle is bound", so a partial bind stays distinguishable from a # complete one. Marking it bound early would let a later setup assign a # provider and advertise discovery while some RFC metadata routes are still # unbound — a 404 for the clients that probe them. On a partial bind the flag # stays unset; the none-mode caller then fails open (the retry's duplicate # register is caught harmlessly) while ha_auth/legacy fail closed. for view in _metadata_views(hass): hass.http.register_view(view) hass.data[_OAUTH_VIEWS_REGISTERED_KEY] = True def _build_unauthorized_response(request: web.Request) -> web.Response: """Build the 401 + ``WWW-Authenticate`` challenge MCP clients use to discover. Per RFC 9728 §5.1 / MCP spec, the ``resource_metadata`` parameter points to the protected-resource metadata URL where the client finds the authorization server. """ base = _build_base_url(request) metadata_url = f"{base}{OAUTH_BASE}/protected-resource" return web.Response( status=401, text="Unauthorized", headers={ "WWW-Authenticate": ( f'Bearer realm="HA-MCP", resource_metadata="{metadata_url}"' ) }, ) # --------------------------------------------------------------------------- # Webhook forwarding handler # --------------------------------------------------------------------------- async def _check_webhook_auth( request: web.Request, cfg: dict[str, Any] ) -> web.StreamResponse | None: """Return a 401 challenge response if the request fails the auth gate, else None.""" # Auth gate. ``none`` = the secret webhook URL is the credential; ``ha_auth`` # validates the bearer via HA core; ``legacy`` validates it against this # module's own opaque tokens. Either failure emits the same 401 discovery # challenge so the client can start the OAuth flow. Gate on the PROVIDER # (constructed only for the matching mode) rather than a string compare, # so the coupling "provider present <=> mode" has a single owner and an # inconsistent cfg cannot fail open. auth_mode makes the two mutually # exclusive, so at most one of these is ever set. resource_server: ResourceServer | None = cfg.get("resource_server") if resource_server is not None and not await resource_server.validate_request( request ): return _build_unauthorized_response(request) oauth_provider: LegacyOAuthProvider | None = cfg.get("oauth_provider") if oauth_provider is not None and not oauth_provider.validate_bearer(request): return _build_unauthorized_response(request) return None async def _async_handle_webhook( hass: HomeAssistant, webhook_id: str, request: web.Request ) -> web.StreamResponse: """Forward an MCP request to the loopback server and stream the reply back.""" domain_data = hass.data.get(DOMAIN) cfg = domain_data.get(DATA_WEBHOOK) if isinstance(domain_data, dict) else None if not isinstance(cfg, dict): return web.Response(status=503, text="MCP server is not available") auth_response = await _check_webhook_auth(request, cfg) if auth_response is not None: return auth_response target_url: str = cfg["target_url"] session: aiohttp.ClientSession = cfg["session"] body = await request.read() forward_headers = { key: value for key, value in request.headers.items() if key.lower() not in _STRIPPED_REQUEST_HEADERS } try: async with session.request( method=request.method, url=target_url, headers=forward_headers, data=body if body else None, ) as upstream_resp: content_type = upstream_resp.headers.get("Content-Type", "") resp_headers = { "Cache-Control": "no-cache, no-transform", "Content-Encoding": "identity", } mcp_session = upstream_resp.headers.get("Mcp-Session-Id") if mcp_session: resp_headers["Mcp-Session-Id"] = mcp_session if "text/event-stream" in content_type: # SSE streaming: prevent HA's compression middleware from # buffering/breaking the stream (supervisor#6470). resp_headers["Content-Type"] = "text/event-stream" resp_headers["X-Accel-Buffering"] = "no" response = web.StreamResponse( status=upstream_resp.status, headers=resp_headers ) await response.prepare(request) # Once prepare() has sent the 200 + headers, a mid-stream # upstream failure can no longer become a 502 — returning a # fresh Response here would be silently dropped and the client # would see only a truncated stream with no log trail. End the # prepared stream deterministically and log instead. # Count forwarded bytes manually: StreamResponse.body_length # is only assigned in write_eof(), so it is still 0 here. bytes_forwarded = 0 try: async for chunk in upstream_resp.content.iter_any(): await response.write(chunk) bytes_forwarded += len(chunk) except aiohttp.ClientError as err: _LOGGER.error( "MCP webhook: upstream dropped mid-stream after %d bytes: %s", bytes_forwarded, err, ) with suppress(ConnectionResetError): await response.write_eof() return response if not any(ct in content_type for ct in _ALLOWED_CONTENT_TYPES): content_type = "application/json" resp_headers["Content-Type"] = content_type resp_body = await upstream_resp.read() return web.Response( status=upstream_resp.status, body=resp_body, headers=resp_headers ) except aiohttp.ClientError as err: _LOGGER.error("MCP webhook: upstream request failed: %s", err) return web.Response(status=502, text="MCP server unavailable") except Exception as err: _LOGGER.exception("MCP webhook: unexpected error: %s", err) return web.Response(status=500, text="MCP server internal error") # --------------------------------------------------------------------------- # Registration / teardown # --------------------------------------------------------------------------- def _bind_ha_auth_surface( hass: HomeAssistant, cfg: dict[str, Any], webhook_id: str, dcr_signing_key: str | None, ) -> None: """Bind the ha_auth surface (fail-closed) and mark cfg's live providers.""" provider = ResourceServer(hass, webhook_id) _register_metadata_views(hass) bind_autoapprove_views(hass) bind_dcr_view(hass) cfg["resource_server"] = provider if dcr_signing_key: cfg[CFG_DCR_SIGNING_KEY] = bytes.fromhex(dcr_signing_key) def _bind_legacy_surface( hass: HomeAssistant, cfg: dict[str, Any], oauth_client_id: str | None, oauth_client_secret: str | None, oauth_signing_key: str | None, ) -> bool: """Bind the legacy surface (fail-closed); return oauth_restart_needed. A root-route conflict with the Webhook Proxy add-on is survivable since the unified scoped endpoints carry legacy's advertised URLs — downgrade it to a warning and serve scoped-only via an unbound provider. """ if not (oauth_client_id and oauth_client_secret and oauth_signing_key): raise ValueError( "legacy webhook auth mode requires oauth_client_id, " "oauth_client_secret, and oauth_signing_key" ) _register_metadata_views(hass) bind_autoapprove_views(hass) oauth_restart_needed = False try: oauth_provider, oauth_restart_needed = bind_legacy_views( hass, oauth_client_id, oauth_client_secret, oauth_signing_key ) except LegacyOAuthRouteConflict: # Log the owner read directly from hass.data, NOT the exception object: # the exception flowed through code holding the client secret, and # CodeQL's taint tracking flags logging it as clear-text sensitive-data # (#2213 gate). The owner string is what the message needs anyway. _LOGGER.warning( "HA-MCP: the Webhook Proxy add-on ('%s') owns the root " "/authorize and /token routes; legacy OAuth will serve " "only on %s/authorize + %s/token (metadata-honoring " "clients are unaffected; metadata-ignoring clients that " "guess root paths reach the add-on instead).", hass.data.get(OAUTH_ROUTE_OWNER_KEY), OAUTH_BASE, OAUTH_BASE, ) oauth_provider = build_unbound_legacy_provider( hass, oauth_client_id, oauth_client_secret, oauth_signing_key ) cfg["oauth_provider"] = oauth_provider return oauth_restart_needed def _bind_none_surface( hass: HomeAssistant, cfg: dict[str, Any], dcr_signing_key: str | None ) -> None: """Bind the none-mode auto-approve surface — FAILS OPEN. The secret webhook URL is the credential; this discovery surface is an enhancement layered on a webhook that otherwise always forwards, so a failure here must NOT tear down the unauthenticated endpoint (issue #1978) — it only means claude.ai's rare OAuth-discovery fallback goes unassisted. Both view bundles bind at most once per HA session; per-request resolvers gate them on cfg, so a none<->ha_auth switch needs no restart (#1969). The DCR key parses before the provider is assigned, so ANY failure — including a corrupt key — leaves the whole surface inactive (plain proxy) rather than half-enabled. """ try: _register_metadata_views(hass) bind_autoapprove_views(hass) bind_dcr_view(hass) # Key BEFORE provider (#2213 review): a bad key raises here and leaves # BOTH unset — plain proxy — instead of a half-enabled surface whose # advertised /register 404s while /authorize auto-approves. if dcr_signing_key: cfg[CFG_DCR_SIGNING_KEY] = bytes.fromhex(dcr_signing_key) cfg[CFG_AUTOAPPROVE_PROVIDER] = AutoApproveProvider() except Exception: _LOGGER.exception( "MCP webhook: failed to set up none-mode auto-approve " "discovery; continuing as a plain unauthenticated proxy " "(the webhook still forwards — only claude.ai's rare " "OAuth-discovery fallback is unassisted)." ) async def async_register_webhook( hass: HomeAssistant, entry: ConfigEntry, *, port: int, secret_path: str, auth_mode: str, register_endpoint: bool = True, oauth_client_id: str | None = None, oauth_client_secret: str | None = None, oauth_signing_key: str | None = None, dcr_signing_key: str | None = None, ) -> bool: """Register the ingress webhook (and, for ha_auth/legacy, the OAuth surface). Stores the forwarding config in ``hass.data[DOMAIN][DATA_WEBHOOK]`` and opens a long-lived aiohttp session for streaming. Raises on failure with the webhook already unregistered, so the caller never leaves a half-configured endpoint live. ``webhook`` is a manifest dependency, so HA guarantees it is set up before this runs. ``oauth_client_id``/``oauth_client_secret``/ ``oauth_signing_key`` are required when ``auth_mode == WEBHOOK_AUTH_LEGACY`` (ignored otherwise); ``oauth_signing_key`` is the hex string persisted in ``entry.data`` — see ``oauth_legacy._normalize_signing_key``. With ``register_endpoint=False`` (remote webhook access disabled by option) no public endpoint or ha_auth/legacy surface is created — and any leftover endpoint from a crashed unload is cleared, so off means off; only the forwarding config is stored, which same-host consumers — the sidebar settings panel proxy — need to reach the loopback server (#1803). Returns True when the caller should surface ``ISSUE_LEGACY_OAUTH_RESTART``: the root ``/authorize``/``/token`` views just bound for the first time this HA session (or with changed credentials), or they are still bound from a prior legacy registration that this call has moved away from — either way aiohttp cannot bind or release a view without a full HA restart. """ if auth_mode not in (WEBHOOK_AUTH_NONE, WEBHOOK_AUTH_HA, WEBHOOK_AUTH_LEGACY): # Fail CLOSED on an unknown mode (corrupt/migrated options): refusing # bring-up files a repair issue, instead of an unrecognized string # silently taking the unauthenticated forward path. raise ValueError(f"Unknown webhook auth mode: {auth_mode!r}") webhook_id: str = entry.data[DATA_WEBHOOK_ID] # The scoped-only provider is held in this registration's cfg and stops # serving on every reload/unload. Its top-level credential fingerprint must # follow that lifetime rather than surviving a switch away from legacy. clear_scoped_legacy_credentials(hass) # Reload-safe and off-means-off: clear any leftover registration from a # crashed unload before (re)registering — or before storing a local-only # config (async_unregister is a no-op pop when nothing is registered). # Runs before the session opens so a raise here cannot leak it. async_unregister(hass, webhook_id) target_url = f"http://127.0.0.1:{port}{secret_path}" session = aiohttp.ClientSession(timeout=_CLIENT_TIMEOUT) cimd_session: aiohttp.ClientSession | None = None if register_endpoint and auth_mode == WEBHOOK_AUTH_HA: try: cimd_session = aiohttp.ClientSession( connector=aiohttp.TCPConnector(limit=_CIMD_CONNECTOR_LIMIT) ) except Exception: # Creating the isolated pool is part of fail-closed ha_auth setup. # Do not leak the already-open relay session if it fails. await session.close() raise cfg: dict[str, Any] = { "webhook_id": webhook_id, "target_url": target_url, "session": session, CFG_CIMD_SESSION: cimd_session, "auth_mode": auth_mode, "resource_server": None, "oauth_provider": None, CFG_AUTOAPPROVE_PROVIDER: None, CFG_DCR_SIGNING_KEY: None, } oauth_restart_needed = False if register_endpoint: try: async_register( hass, DOMAIN, _WEBHOOK_NAME, webhook_id, _async_handle_webhook, allowed_methods=["POST", "GET"], ) if auth_mode == WEBHOOK_AUTH_HA: _bind_ha_auth_surface(hass, cfg, webhook_id, dcr_signing_key) elif auth_mode == WEBHOOK_AUTH_LEGACY: oauth_restart_needed = _bind_legacy_surface( hass, cfg, oauth_client_id, oauth_client_secret, oauth_signing_key ) else: # WEBHOOK_AUTH_NONE (the only remaining mode — unknown modes # already raised above). _bind_none_surface(hass, cfg, dcr_signing_key) except Exception: # Never leave a live endpoint (or a leaked session) behind a failed # auth-setup path. suppress: the ORIGINAL error must be what # propagates (review finding) - a raising cleanup would mask it. with suppress(Exception): async_unregister(hass, webhook_id) with suppress(Exception): await session.close() if cimd_session is not None: with suppress(Exception): await cimd_session.close() clear_scoped_legacy_credentials(hass) raise # A PRIOR registration this HA session may still own the legacy root views # even though THIS call bound no legacy provider — either the mode is no # longer legacy, OR legacy is still selected but the webhook endpoint is now # off (register_endpoint=False skips the bind block above). aiohttp can never # release a bound view without a restart, so gate on "no provider bound this # call" (not the mode string) to surface the restart that releases route # ownership in both cases. if cfg["oauth_provider"] is None and hass.data.get(OAUTH_ROUTE_OWNER_KEY) == DOMAIN: oauth_restart_needed = True hass.data.setdefault(DOMAIN, {})[DATA_WEBHOOK] = cfg return oauth_restart_needed async def async_unregister_webhook(hass: HomeAssistant) -> None: """Unregister the ingress webhook and close its aiohttp session. Idempotent. The discovery views and the legacy root ``/authorize``/``/token`` views are intentionally left bound (aiohttp can't unregister them until HA restarts); they 404 while their mode is not live (see ``active_auth_mode`` / ``LegacyOAuthProvider.is_active``). """ clear_scoped_legacy_credentials(hass) domain_data = hass.data.get(DOMAIN) if not isinstance(domain_data, dict): return cfg = domain_data.pop(DATA_WEBHOOK, None) if not isinstance(cfg, dict): return webhook_id = cfg.get("webhook_id") if webhook_id: async_unregister(hass, webhook_id) session = cfg.get("session") if session is not None: await session.close() cimd_session = cfg.get(CFG_CIMD_SESSION) if cimd_session is not None: await cimd_session.close()