fix(homecore-api security): auth-gate GET /api/ (was unauthenticated) + recover WS subscription on broadcast lag (#1076)

* fix(homecore-api security): auth-gate GET /api/ (HC-API-AUTH-01, ADR-161)

`rest::api_root` took no headers and unconditionally returned
`200 {"message":"API running."}`, while every sibling REST route gates
on `BearerAuth::from_headers`. HA's `APIStatusView` inherits
`requires_auth = True`, so `/api/` must return 401 for a missing/wrong
bearer — HA clients use it as a token-validation probe, so a 200 told a
bad-token client its token was valid and let an unauthenticated party
confirm a live endpoint. LOW severity (static body, no data leak),
reported at true severity.

Fix: `api_root(headers, State)` validates the bearer like `get_config`.

Pinned by fails-on-old tests (200 -> assert 401):
- api_root_rejects_missing_bearer
- api_root_rejects_wrong_bearer
guarded by api_root_accepts_correct_bearer (still 200 with valid token).

Co-Authored-By: claude-flow <ruv@ruv.net>

* fix(homecore-api security): recover WS subscription on broadcast lag (HC-WS-LAG-01, ADR-161)

`subscribe_events`'s per-subscription task matched `Err(_) => break` on
both broadcast `recv()` arms. `RecvError::Lagged(n)` (a slow consumer
falling >EVENT_CHANNEL_CAPACITY=4,096 events behind) is recoverable —
the bus doc says "Lagged receivers must re-sync" and HA keeps the
subscription alive across a lag. The old code treated the first lag as
fatal, so after an event burst the client's stream went permanently
silent with no error frame — a self-inflicted event-delivery DoS under
load. LOW severity.

Fix: `Lagged(_) => continue` (skip dropped window, re-sync),
`Closed => break`, on both the system and domain arms.

Pinned by subscription_survives_broadcast_lag: subscribes, floods 6,000
filtered events past the 4,096 capacity to force a Lagged, then asserts
a subsequent subscribed event is still delivered (old code: 5s timeout).

Co-Authored-By: claude-flow <ruv@ruv.net>

* docs(homecore-api security): record HC-API-AUTH-01 + HC-WS-LAG-01 review (ADR-161)

CHANGELOG [Unreleased] Security entry + ADR-161 addendum documenting the
beyond-SOTA network-API review: two LOW bugs fixed (unauthenticated
GET /api/; WS subscription killed on broadcast lag) and the
auth/traversal/injection/info-leak/CORS dimensions confirmed clean with
evidence (no traversal surface — in-memory DashMap + EntityId allowlist;
HashSet token compare, not a byte-== timing oracle).

Co-Authored-By: claude-flow <ruv@ruv.net>

v2/crates/homecore-api/src/rest.rs

@@ -12,8 +12,20 @@ use crate::state::SharedState;
 #[derive(Serialize)]
 pub struct ApiRunning { message: &'static str }
 
-pub async fn api_root() -> Json<ApiRunning> {
-    Json(ApiRunning { message: "API running." })
+/// `GET /api/` — the HA `APIStatusView` ("API running." ping).
+///
+/// Security (HC-API-AUTH-01): HA's `APIStatusView` inherits
+/// `requires_auth = True` from `HomeAssistantView`, so an unauthenticated
+/// (or wrong-token) request to `/api/` returns **401**, not 200. HA
+/// clients (and the companion app) rely on this status route as a
+/// *token-validation probe* — a 200 here would tell a client a bad token
+/// is good, and would let an unauthenticated party confirm a live
+/// HOMECORE-API endpoint. The P2 handler skipped the bearer gate that
+/// every sibling route applies; this restores wire-compat by validating
+/// the bearer like `get_config`/`get_states` before replying.
+pub async fn api_root(headers: HeaderMap, State(s): State<SharedState>) -> ApiResult<Json<ApiRunning>> {
+    let _ = BearerAuth::from_headers(&headers, s.tokens()).await?;
+    Ok(Json(ApiRunning { message: "API running." }))
 }
 
 #[derive(Serialize)]

v2/crates/homecore-api/src/ws.rs

@@ -298,7 +298,17 @@ impl Connection {
                                     }
                                 }
                                 Ok(_) => {}
-                                Err(_) => break,
+                                // A slow consumer that falls >4,096 events behind
+                                // gets `Lagged(n)`, which is RECOVERABLE: the bus
+                                // doc (`bus.rs` §"Lagged receivers must re-sync")
+                                // and HA's WS contract both keep the subscription
+                                // alive across a lag. The pre-fix `Err(_) => break`
+                                // treated `Lagged` as fatal, silently killing the
+                                // client's event stream on a burst (HC-WS-LAG-01).
+                                // Skip the dropped window and continue; only a
+                                // `Closed` sender ends the task.
+                                Err(broadcast::error::RecvError::Lagged(_)) => continue,
+                                Err(broadcast::error::RecvError::Closed) => break,
                             },
                             evt = domain_rx.recv() => match evt {
                                 Ok(de) => {
@@ -316,7 +326,12 @@ impl Connection {
                                         if tx_clone.send(payload.to_string()).is_err() { break; }
                                     }
                                 }
-                                Err(_) => break,
+                                // Same recoverable-lag handling as the system arm
+                                // above (HC-WS-LAG-01): a lagged domain-event
+                                // receiver re-syncs and continues; only `Closed`
+                                // terminates the subscription.
+                                Err(broadcast::error::RecvError::Lagged(_)) => continue,
+                                Err(broadcast::error::RecvError::Closed) => break,
                             }
                         }
                     }

v2/crates/homecore-api/tests/server_bin_auth.rs

@@ -75,3 +75,72 @@ async fn from_env_path_enforces_whitelist() {
     assert!(!store.is_valid("not_in_whitelist").await);
     assert!(!store.is_dev_mode().await, "from_env must NOT be dev mode");
 }
+
+// ─── HC-API-AUTH-01: `GET /api/` must be auth-gated like every sibling ───
+//
+// HA's `APIStatusView` inherits `requires_auth = True`, so `/api/` returns
+// 401 for a missing/wrong bearer and 200 only for a valid one. The pre-fix
+// `api_root` took no headers and unconditionally returned 200 — these two
+// tests FAIL on that code.
+
+#[tokio::test]
+async fn api_root_rejects_missing_bearer() {
+    let app = router(provisioned_state("the_real_token").await);
+    let resp = app
+        .oneshot(
+            Request::builder()
+                .uri("/api/")
+                .body(Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(
+        resp.status(),
+        StatusCode::UNAUTHORIZED,
+        "GET /api/ with NO bearer must be 401 (HC-API-AUTH-01) — HA's \
+         APIStatusView requires_auth=True; a 200 here lets an \
+         unauthenticated party confirm a live endpoint and tells a \
+         token-validation probe a bad token is good"
+    );
+}
+
+#[tokio::test]
+async fn api_root_rejects_wrong_bearer() {
+    let app = router(provisioned_state("the_real_token").await);
+    let resp = app
+        .oneshot(
+            Request::builder()
+                .uri("/api/")
+                .header("Authorization", "Bearer the_wrong_token")
+                .body(Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(
+        resp.status(),
+        StatusCode::UNAUTHORIZED,
+        "GET /api/ with a WRONG bearer must be 401 (HC-API-AUTH-01)"
+    );
+}
+
+#[tokio::test]
+async fn api_root_accepts_correct_bearer() {
+    let app = router(provisioned_state("the_real_token").await);
+    let resp = app
+        .oneshot(
+            Request::builder()
+                .uri("/api/")
+                .header("Authorization", "Bearer the_real_token")
+                .body(Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    assert_eq!(
+        resp.status(),
+        StatusCode::OK,
+        "GET /api/ with the correct bearer must still return 200 (API running.)"
+    );
+}

v2/crates/homecore-api/tests/ws_handshake.rs

@@ -166,3 +166,100 @@ async fn ping_pong_reply_is_received() {
     assert_eq!(reply["type"], "pong");
     assert_eq!(reply["id"], 7);
 }
+
+/// Variant of [`spawn_server_with_token`] that also returns a `HomeCore`
+/// handle (cheap `Arc` clone) so the test can fire events into the *same*
+/// bus the served subscription reads from.
+async fn spawn_server_returning_homecore(valid_token: &str) -> (SocketAddr, HomeCore) {
+    let hc = HomeCore::new();
+    let tokens = LongLivedTokenStore::empty();
+    tokens.register(valid_token).await;
+    let state = SharedState::with_tokens(hc.clone(), "Test", "test-version", tokens);
+    let app = router(state);
+
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let addr = listener.local_addr().unwrap();
+    tokio::spawn(async move {
+        axum::serve(listener, app).await.unwrap();
+    });
+    (addr, hc)
+}
+
+#[tokio::test]
+async fn subscription_survives_broadcast_lag() {
+    // HC-WS-LAG-01: the per-subscription event task must treat a broadcast
+    // `Lagged(n)` as RECOVERABLE (re-sync + continue), matching the bus
+    // contract ("Lagged receivers must re-sync") and HA's WS semantics.
+    //
+    // The pre-fix `Err(_) => break` killed the whole event-stream task on
+    // the first lag, so after a >4,096-event burst the client's stream
+    // went permanently silent. This test fires far more than the 4,096
+    // channel capacity to force a `Lagged`, then fires ONE more event and
+    // asserts the subscription still delivers it. FAILS (5s timeout) on
+    // the old code because the task is already dead.
+    use homecore::{Context, DomainEvent};
+
+    let (addr, hc) = spawn_server_returning_homecore("good_token_abc").await;
+    let url = format!("ws://{addr}/api/websocket");
+    let (mut ws, _resp) = connect_async(&url).await.unwrap();
+
+    let _ = next_json(&mut ws).await; // auth_required
+    ws.send(Message::Text(
+        serde_json::json!({"type":"auth","access_token":"good_token_abc"}).to_string(),
+    ))
+    .await
+    .unwrap();
+    let auth = next_json(&mut ws).await;
+    assert_eq!(auth["type"], "auth_ok");
+
+    // Subscribe to a specific domain event type so unrelated traffic is
+    // filtered out and we can deterministically match the post-lag event.
+    ws.send(Message::Text(
+        serde_json::json!({"id": 1, "type": "subscribe_events", "event_type": "lag_probe"})
+            .to_string(),
+    ))
+    .await
+    .unwrap();
+    let ack = next_json(&mut ws).await; // result ok for the subscribe
+    assert_eq!(ack["type"], "result");
+    assert_eq!(ack["success"], true);
+
+    // Flood the bus far past EVENT_CHANNEL_CAPACITY (4,096) with events the
+    // subscription FILTERS OUT (different event_type). Because the client
+    // never reads them off the WS, the server-side broadcast receiver falls
+    // behind and the NEXT `recv()` yields `Lagged`. We fire synchronously
+    // and don't yield to the WS reader, guaranteeing the overflow.
+    for i in 0..6000u32 {
+        hc.bus().fire_domain(DomainEvent::new(
+            "noise",
+            serde_json::json!({ "i": i }),
+            Context::new(),
+        ));
+    }
+
+    // Now fire the event the client IS subscribed to. On the fixed code the
+    // task recovered from `Lagged` and continues, so this is delivered. On
+    // the old code the task broke on `Lagged` and this never arrives.
+    hc.bus().fire_domain(DomainEvent::new(
+        "lag_probe",
+        serde_json::json!({ "marker": "post-lag" }),
+        Context::new(),
+    ));
+
+    // Drain frames until we see our post-lag event (ignoring any noise the
+    // filter let slip before the lag), bounded by a timeout.
+    let got = tokio::time::timeout(std::time::Duration::from_secs(5), async {
+        loop {
+            let v = next_json(&mut ws).await;
+            if v["type"] == "event" && v["event"]["event_type"] == "lag_probe" {
+                return v;
+            }
+        }
+    })
+    .await
+    .expect(
+        "subscription went silent after a broadcast lag — Lagged was treated \
+         as fatal (HC-WS-LAG-01)",
+    );
+    assert_eq!(got["event"]["data"]["marker"], "post-lag");
+}