ruvnet--RuView/docs/adr/ADR-130-homecore-rest-websocket-api.md

ADR-130: HOMECORE-API — Wire-compatible REST and WebSocket API

Field	Value
Status	Proposed
Date	2026-05-25
Deciders	ruv
Codename	HOMECORE-API
Relates to	ADR-126 (HOMECORE master), ADR-127 (HOMECORE-CORE), ADR-055 (sensing-server Axum pattern), ADR-124 (SENSE-BRIDGE — bearer auth pattern)
Tracking issue	TBD

---

1. Context

Home Assistant's HTTP and WebSocket APIs are the primary interface for every non-frontend client: the iOS companion app, the Android companion app, HACS, Node-RED, the homeassistant Python client library, ESPHome native API clients, external automation scripts, and the hundreds of third-party HA dashboard projects.

The API surface is defined in two Python modules:

1. homeassistant/components/api/__init__.py — 24 REST API routes mounted at /api/. Key routes: GET /api/, GET /api/states, GET /api/states/<entity_id>, POST /api/states/<entity_id>, GET /api/events, POST /api/events/<event_type>, GET /api/services, POST /api/services/<domain>/<service>, GET /api/error_log, GET /api/config, POST /api/template, POST /api/check_config, GET /api/history/period/<datetime> (deprecated — recorder), POST /api/logbook/ (deprecated — recorder).

2. homeassistant/components/websocket_api/ — the WebSocket API handler (connection.py handles auth handshake; commands.py handles 30+ command types). Key commands: auth, subscribe_events, unsubscribe_events, call_service, get_states, get_services, get_config, subscribe_trigger, render_template, validate_config, subscribe_entities (entity registry updates), config/entity_registry/list, and many more.

1.1 Auth model

HA uses long-lived access tokens (LLAT) as the primary auth mechanism for non-UI clients. Tokens are created in the HA user profile UI and stored in .storage/auth. The REST API accepts Authorization: Bearer <token> or the api_password legacy header (deprecated since HA 2022.x). The WebSocket API requires an auth message with access_token as the first message after connection.

1.2 Why wire-compat matters

The iOS and Android HA companion apps (>100,000 installs combined) hardcode the HA API paths and WebSocket command schemas. Any implementation that deviates from the exact JSON schemas causes the apps to fail silently — not with a meaningful error, but by returning empty entity lists or missing state updates. Wire-compat is therefore a hard requirement, not a nice-to-have.

The baseline for compatibility is HA 2025.1 (the version that introduced SQLite recorder schema version 48). Any HOMECORE instance claiming compliance with this ADR must pass the companion app integration test suite.

---

2. Decision

Implement the homecore-api crate as an Axum-based server that replicates the HA REST and WebSocket API on port 8123. The implementation is informed by — but does not copy — homeassistant/components/api/__init__.py and homeassistant/components/websocket_api/.

The server reuses the Axum + Tokio architecture established in v2/crates/wifi-densepose-sensing-server/src/main.rs and its bearer auth pattern (v2/crates/wifi-densepose-sensing-server/src/bearer_auth.rs).

2.1 REST API route table

Route	Method	HA source line (approx.)	HOMECORE status
/api/	GET	api/__init__.py:74	P2 — returns { "message": "API running." }
/api/config	GET	api/__init__.py:97	P2 — returns homecore.config as JSON
/api/states	GET	api/__init__.py:116	P2 — returns hass.states.all() as JSON array
/api/states/<entity_id>	GET	api/__init__.py:130	P2
/api/states/<entity_id>	POST	api/__init__.py:145	P2 — writes state; fires state_changed
/api/events	GET	api/__init__.py:168	P3
/api/events/<event_type>	POST	api/__init__.py:180	P3 — fires domain event
/api/services	GET	api/__init__.py:192	P2
/api/services/<domain>/<service>	POST	api/__init__.py:206	P2
/api/template	POST	api/__init__.py:222	P3 — WASM MiniJinja evaluator (ADR-129)
/api/check_config	POST	api/__init__.py:240	P4
/api/error_log	GET	api/__init__.py:252	P3
/api/history/period/<datetime>	GET	api/__init__.py:270	P4 — recorder query (ADR-132)
/api/logbook/	POST	api/__init__.py:310	P4 — recorder query
/api/camera_proxy/<entity_id>	GET	api/__init__.py:330	P4 — proxy to camera integration
/api/calendar/<entity_id>	GET	api/__init__.py:348	P4
/api/webhook/<webhook_id>	POST/GET	api/__init__.py:368	P3 — fires webhook.<id> event
/api/intent/handle	POST	api/__init__.py:400	P4 — HOMECORE-ASSIST (ADR-133)
/auth/token	POST	auth/providers/__init__.py	P2 — issue LLAT from username/password
/auth/authorize	GET/POST	auth/providers/__init__.py	P3 — OAuth2 flow
/frontend/ static assets	GET	frontend/__init__.py	P1 — serve HA Python frontend static files until ADR-131 ships

2.2 WebSocket API command table

WS command type	HA source	HOMECORE status
auth (handshake)	websocket_api/connection.py:55	P2
subscribe_events	websocket_api/commands.py:120	P2
unsubscribe_events	websocket_api/commands.py:145	P2
call_service	websocket_api/commands.py:160	P2
get_states	websocket_api/commands.py:200	P2
get_services	websocket_api/commands.py:218	P2
get_config	websocket_api/commands.py:230	P2
subscribe_trigger	websocket_api/commands.py:250	P3
render_template	websocket_api/commands.py:280	P3
validate_config	websocket_api/commands.py:300	P3
subscribe_entities	websocket_api/commands.py:320	P3 — entity registry update stream
config/entity_registry/list	websocket_api/commands.py:370	P3
config/entity_registry/update	websocket_api/commands.py:400	P3
config/area_registry/list	websocket_api/commands.py:450	P3
config/device_registry/list	websocket_api/commands.py:480	P3
config/config_entries/list	websocket_api/commands.py:510	P3
lovelace/config (dashboard)	lovelace/dashboard.py	P4 — reads from HOMECORE storage
media_player/*	websocket_api/commands.py:600	P4

2.3 Auth implementation

HOMECORE-API implements long-lived access tokens as JWTs signed with an Ed25519 key (generated at first startup, stored in .homecore/auth_key.pem). Token format:

{
  "sub": "<user_id>",
  "iss": "homecore",
  "iat": <unix_timestamp>,
  "exp": <unix_timestamp or null for LLAT>,
  "type": "long_lived_access_token"
}

The HA companion app sends Authorization: Bearer <token> on every REST request. The WebSocket auth handshake sends { "type": "auth", "access_token": "<token>" }. Both paths validate the JWT against the stored Ed25519 key.

Legacy api_password is deliberately not supported (removed in HA 2022.x and never properly secure).

---

3. HA-side reference table

HA module / file	What it does	HOMECORE preserves	Changes	Drops
components/api/__init__.py	24 REST routes + JSON response schemas	All response schemas byte-compatible with HA 2025.1	Axum router instead of HA's custom HTTP component; serde_json instead of Python json	Python HTTP request context; HA's built-in CORS middleware (replicated in Axum)
components/websocket_api/connection.py	WS auth handshake; per-connection state; message dispatch	Auth handshake flow: auth_required → auth message → auth_ok or auth_invalid	Axum WebSocketUpgrade extractor; per-connection tokio::task	Python asyncio message handling
components/websocket_api/commands.py	30+ WS command handlers	All command type strings; response envelope { id, type, result } or error { id, type, error: { code, message } }	Rust match dispatch; Tokio broadcast receiver per subscription	Python class-based command handler registration
auth/providers/__init__.py	Auth providers; LLAT issuance; OAuth2 flow	LLAT issuance; token validation	Ed25519 JWT instead of HA's custom token serializer; same token type field values	Nabu Casa cloud auth; multi-provider auth chain
components/http/__init__.py	Aiohttp-based HTTP server setup; CORS; trusted proxies	CORS headers; X-Forwarded-For trusted proxy handling	Axum Tower middleware	Aiohttp; Python SSL context

---

4. Public API parity table

HA API surface	HOMECORE exact equivalent
GET /api/states → [{entity_id, state, attributes, last_changed, last_updated, context}]	Identical JSON schema; last_changed / last_updated in ISO 8601
GET /api/services → {domain: {service: {description, fields}}}	Identical schema; service descriptions read from plugin manifests
WS subscribe_events → {type: "event", event: {event_type, data, origin, time_fired, context}}	Identical envelope; time_fired in ISO 8601
WS call_service → {type: "result", success: true, result: {context}}	Identical; context.id is a UUID
WS get_states → {type: "result", result: [{entity_id, state, attributes, ...}]}	Identical schema
REST POST /api/services/<domain>/<service> → 200 with called service list	Identical; same target field support
REST POST /api/template → 200 with evaluated string	Identical; same error response {message: "..."} on template error
Auth WS flow: auth_required → auth → auth_ok	Identical message type strings; same ha_version field in auth_required
REST Authorization: Bearer <token>	Identical header name; JWT instead of HA's opaque token format (transparent to clients)

---

5. Phased implementation plan

P1 — Axum skeleton + static frontend (1 week)

• Create v2/crates/homecore-api/ workspace member.
• Axum router on port 8123; Tower CORS middleware (allow http://homeassistant.local:8123).
• Static file handler: serve HA's Python frontend build from a configurable path (default ./frontend/build/). This allows using the Python HA frontend as-is until ADR-131 ships.
• GET /api/ returns { "message": "API running." }.
• CI: cargo check -p homecore-api; HTTP smoke test.

P2 — Core REST + WebSocket auth + states (3 weeks)

• Axum WebSocket upgrade at /api/websocket.
• Auth: Ed25519 JWT issuance at /auth/token; validation middleware.
• WS auth handshake: auth_required → auth → auth_ok / auth_invalid.
• WS commands: get_states, subscribe_events, unsubscribe_events, call_service, get_services, get_config.
• REST: /api/states, /api/states/<entity_id> (GET + POST), /api/services, /api/services/<domain>/<service>, /api/config.
• Integration test: HA iOS companion app authenticates and displays entity list against HOMECORE.

P3 — Remaining WS commands + entity registry API (3 weeks)

• WS: subscribe_trigger, render_template, validate_config, subscribe_entities, entity/area/device registry commands.
• REST: /api/template, /api/webhook/<id>, /api/error_log, /api/events, /api/events/<type>.
• /auth/authorize OAuth2 flow for UI login.
• HACS smoke test: HACS connects, lists integrations.

P4 — Recorder + history API (2 weeks)

• /api/history/period/<datetime> backed by ADR-132 recorder SQLite.
• /api/logbook/ backed by ADR-132 recorder.
• /api/camera_proxy/, /api/calendar/, /api/intent/handle.
• Companion app full feature test: automations, notifications, history charts.

---

6. Risks

Risk	Likelihood	Severity	Mitigation	Cross-ADR impact
JSON schema drift — HA updates a response field name between 2025.1 and HOMECORE release	Medium	High	Maintain a JSON-schema test fixture set generated from HA 2025.1; run against HOMECORE in CI	ADR-134: migration tool depends on the same JSON schemas; must stay in sync
WS subscription fan-out — 50 concurrent HA companion app sessions each subscribed to subscribe_events ALL; every state change creates 50 serialization tasks	Medium	Medium	Broadcast serialized JSON once; clone the Bytes arc to each subscriber sender; do not re-serialize per subscriber	ADR-127: broadcast channel capacity must handle subscriber fan-out without lagging
Auth token format — HA companion apps may validate the token format (JWT vs opaque). HOMECORE uses JWT; HA uses a custom opaque token. Tokens are never decoded client-side in standard clients, but non-standard clients may inspect them	Low	Low	JWTs are base64url-encoded JSON; any client checking token.startsWith("ey") will see a JWT. HA's own tokens are also base64url but not JWTs. Document the difference; test with the iOS app specifically	None
Port 8123 conflict — HOMECORE runs on the same port as HA; side-by-side mode (ADR-134) requires HOMECORE on a different port until cutover	High	Medium	ADR-134 side-by-side mode runs HOMECORE on port 8124; companion app can be pointed at port 8124 for testing	ADR-134 owns the cutover mechanism

---

7. Open questions

Q1: The HA WebSocket API uses incremental integer IDs (id: 1, 2, 3, ...) for command/response correlation within a session. HOMECORE uses the same scheme. What is the maximum id value the companion app supports before wrapping? If the app doesn't wrap and HOMECORE processes > 2^31 commands per session, this becomes an overflow issue in extremely long-lived sessions.

Q2: The subscribe_entities WS command (added in HA 2021.x) sends entity registry change events in addition to state change events. The iOS companion app uses this to maintain a local entity list without polling. Is the full subscribe_entities delta schema (including action: "create" | "update" | "remove") fully documented, or must it be reverse-engineered from the companion app source?

Q3: HA's /auth/token endpoint accepts grant_type=password (username/password) and grant_type=refresh_token. HOMECORE's initial implementation supports password grant only. Is refresh token support required for the companion app (it caches tokens between sessions) or does the companion app re-authenticate on each launch?

Q4: CORS policy: HA's default CORS allows http://localhost:* and http://homeassistant.local:*. The HOMECORE-UI frontend (ADR-131) will be served from a different origin in development. What CORS policy should HOMECORE-API use in production vs development mode?

---

8. References

HA upstream

• homeassistant/components/api/__init__.py — 24 REST routes with exact URL paths, methods, and JSON response schemas
• homeassistant/components/websocket_api/connection.py — auth handshake protocol; per-connection state management
• homeassistant/components/websocket_api/commands.py — 30+ command type handlers with exact type strings and result schemas
• homeassistant/components/http/__init__.py — CORS setup; trusted proxy handling; aiohttp-based server
• homeassistant/auth/providers/__init__.py — token issuance; AuthManager; LLAT format
• homeassistant/auth/__init__.py — AuthManager.async_create_long_lived_access_token

This repo

• v2/crates/wifi-densepose-sensing-server/src/main.rs — Axum server architecture (REST + WebSocket); pattern for this ADR
• v2/crates/wifi-densepose-sensing-server/src/bearer_auth.rs — Bearer auth middleware pattern
• docs/adr/ADR-127-homecore-state-machine-rust.md — state machine that REST/WS routes read from
• docs/adr/ADR-126-ruview-native-ha-port-master.md — §6 compatibility contract with companion apps

External

• HA WebSocket API Developer Docs — authoritative command type catalog
• HA REST API — REST endpoint schemas