From b02350d423120165fdbe76e1710a548075c52c5e Mon Sep 17 00:00:00 2001
From: maziggy <mz@v8w.de>
Date: Sat, 2 May 2026 12:32:02 +0200
Subject: [PATCH]   fix(security): allow iframe embedding from trusted origins
 via env var (#1191)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

  Bambuddy ships strict anti-clickjacking headers (X-Frame-Options:
  SAMEORIGIN + CSP frame-ancestors 'none') by default. Internet-exposed
  deployments need this; same-LAN HA Webpage-panel users do not, and
  SAMEORIGIN is port-strict so HA on :8123 + Bambuddy on :8000 always
  fails. azurusnova hit exactly that case.

  Add TRUSTED_FRAME_ORIGINS env var (comma-separated scheme://host[:port]).
  When set, drop X-Frame-Options entirely (modern browsers honor
  frame-ancestors and the legacy ALLOW-FROM syntax is deprecated /
  inconsistent across vendors) and emit "frame-ancestors 'self' <list>"
  on every CSP-bearing route. Origin validation is strict: only http(s),
  no paths, no query/fragment, no wildcards. Bad entries get a warning
  and are dropped — startup never fails.

  Default behaviour (no env var) is unchanged: X-Frame-Options:
  SAMEORIGIN + frame-ancestors 'none', so existing Docker / bare-metal
  deployments are not affected.
---
 .env.example                                  |   8 +
 CHANGELOG.md                                  |   2 +
 backend/app/main.py                           |  88 +++++++++-
 .../integration/test_security_headers.py      | 162 ++++++++++++++++++
 4 files changed, 253 insertions(+), 7 deletions(-)
 create mode 100644 backend/tests/integration/test_security_headers.py

diff --git a/.env.example b/.env.example
index b8df7014c..6527d4a34 100644
--- a/.env.example
+++ b/.env.example
@@ -16,3 +16,11 @@ LOG_TO_FILE=true
 # and these values override any database settings (read-only in UI)
 # HA_URL=http://supervisor/core
 # HA_TOKEN=your-long-lived-access-token
+
+# Trusted iframe origins (#1191) — comma-separated list of scheme://host[:port]
+# origins permitted to embed Bambuddy via <iframe>. Defaults to empty (strict:
+# only same-origin embedding allowed). Set this to your Home Assistant origin
+# when using the HA Webpage dashboard panel, since HA on port 8123 and Bambuddy
+# on port 8000 are different origins to the browser. Wildcards, paths, and
+# non-http(s) schemes are rejected at startup with a warning.
+# TRUSTED_FRAME_ORIGINS=http://homeassistant.local:8123
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 02449b518..83c1c3928 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,8 @@ All notable changes to Bambuddy will be documented in this file.
 - **Filament Track Switch (FTS) support — print modal filament dropdown is no longer empty when an X2D / H2D has the FTS accessory installed** ([#1162](https://github.com/maziggy/bambuddy/issues/1162), reported by @mkavalecz) — When the FTS accessory is installed the printer's MQTT changes one nibble of the per-AMS `info` bitmask: bits 8-11 flip from a fixed extruder ID (0x0 / 0x1) to `0xE` ("uninitialized"), because the AMS is no longer wired to a single nozzle — the FTS dynamically routes any slot to either extruder. Bambuddy's MQTT parser already skipped 0xE entries when building `ams_extruder_map` (matching BambuStudio's reading for boot-time transient state), so with the FTS installed the map ended up empty and the print modal's filament dropdown — which filters by `extruderId === nozzle_id` to prevent cross-nozzle assignment ("position of left hotend is abnormal" failures) — filtered out *every* loaded slot. Net effect: empty Filament Mapping dropdown on every dual-nozzle print with the FTS, even when the AMS was fully loaded with the right material. Detection comes from a new MQTT field — `print.device.fila_switch` — which is non-null only when the accessory is installed; it carries the routing topology as two arrays: `in[track] = currently fed slot (-1 = empty)` and `out[track] = extruder this track terminates at`. The fix surfaces this through a new `FilaSwitchState` dataclass on `PrinterState` (`installed`, `in_slots`, `out_extruders`, `stat`, `info`) and the equivalent `FilaSwitchResponse` Pydantic schema on the `GET /printers/{id}/status` route. Frontend (`useFilamentMapping.ts` + `FilamentMapping.tsx`) skips the per-extruder filter when `printerStatus.fila_switch?.installed === true` so any compatible AMS slot can satisfy any nozzle's filament requirement, since the FTS handles the routing. Slots currently fed into a track also get a routing badge in the dropdown — `[L]` or `[R]` — so the user can tell at a glance which slot the FTS is currently routing where (idle slots get no badge: they can be routed to either extruder on demand). The hard "no cross-nozzle assignment" filter on real dual-nozzle printers without the FTS stays untouched (still trips the same way it always has — `fila_switch == null` keeps the existing behaviour). 4 backend tests in `test_bambu_mqtt.py::TestFilamentTrackSwitchDetection` (default-not-installed, detect-from-MQTT-using-the-reporter's-bundle, no-fila_switch-field-stays-not-installed, missing-in-out-arrays-don't-crash) and 2 frontend tests in `useFilamentMapping.test.ts` (FTS-active drops the nozzle filter; explicit `fila_switch: null` keeps the filter applied). Upstream fila_switch payloads with anything other than the documented shape are tolerated — `installed` flips on the *presence* of the field, the routing arrays default to empty lists if missing, and the dropdown skips the badge for slots not currently in `in_slots`.
 
 ### Fixed
+- **iframe embedding from trusted origins (e.g. Home Assistant Webpage panel) no longer blocked** ([#1191](https://github.com/maziggy/bambuddy/issues/1191), reported by @azurusnova) — Bambuddy ships strict anti-clickjacking headers (`X-Frame-Options: SAMEORIGIN` and CSP `frame-ancestors 'none'`) by default, which protects internet-exposed deployments from being embedded by hostile sites. But it also broke a documented integration path: Home Assistant's Webpage dashboard panel embeds Bambuddy via `<iframe>` on a different origin (HA on `:8123`, Bambuddy on `:8000`), and the SAMEORIGIN value is port-strict, so even same-LAN trusted setups got "refused to connect". A new `TRUSTED_FRAME_ORIGINS` env var takes a comma-separated list of `scheme://host[:port]` origins; when set, the middleware drops `X-Frame-Options` (modern browsers honor `frame-ancestors`, and the legacy `ALLOW-FROM <url>` syntax is deprecated and inconsistent across vendors) and the CSP `frame-ancestors` directive becomes `'self' <origin> <origin>...`. The default — empty env var — keeps the strict `'none'` behavior, so Docker / bare-metal users without HA see no behavioural change. Origin validation happens at startup: only `http://` and `https://` are accepted, paths/query/fragments/wildcards are rejected with a warning (one bad entry doesn't take the deployment down — it's just dropped from the allowlist). The `gcode-viewer` route's `frame-ancestors 'self'` (same-origin embed for the in-app gcode preview iframe) also includes the allowlist when configured, so HA users embedding Bambuddy can still open the gcode viewer modal. 16 new tests in `test_security_headers.py`: 12 unit tests for the env-var parser (empty / unset / single / multiple / whitespace / empty-segment / non-http scheme dropped / missing host dropped / path dropped / query+fragment dropped / wildcard dropped / trailing-slash kept) and 4 integration tests for the middleware (default-strict emits SAMEORIGIN + 'none', allowlist relaxes CSP and drops X-Frame-Options, /docs branch also honors the allowlist, other security headers like X-Content-Type-Options and Referrer-Policy are unaffected in both modes). Documented in the Docker env-var reference page on the wiki and in `.env.example`.
+
 - **Virtual Printer queue mode auto-dispatched onto the wrong colour when multiple compatible printers were available** ([#1188](https://github.com/maziggy/bambuddy/issues/1188), reported by @EdwardChamberlain) — Sending a sliced 3MF to a queue-mode VP via Orca / Studio with auto-dispatch on caused Bambuddy to schedule the job onto a printer of the right model but the wrong loaded filament: a print sliced for matte white PLA would land on a printer with no white loaded, and the printer would start the job using whatever was the closest available match. Edward's diagnosis was exact (`virtual_printer/manager.py:325-326`): the manual /api/v1/print-queue/ POST flow extracts the 3MF's per-slot filament requirements at queue-add time and writes `required_filament_types`, `filament_overrides`, and `ams_mapping` on the resulting `PrintQueueItem`, so the scheduler's color-match enforcement (`print_scheduler.py:512` — keys on `filament_overrides[].force_color_match === true`) actually runs. The VP queue-write path (`_add_to_print_queue`) skipped all of that and built a bare `PrintQueueItem` with only `printer_id`, `target_model`, `archive_id`, `plate_id`, `position`, `status`, `manual_start`. Net effect: the scheduler reached the model-only-matching fallback and accepted the first available printer of the target model regardless of loaded colour, exactly as he described. **Fix:** the scheduler's existing `_get_filament_requirements` 3MF parser is extracted into a shared helper (`backend/app/services/filament_requirements.py:extract_filament_requirements`) so the VP path can reuse it at upload time. The VP's `_add_to_print_queue` now calls that helper after archiving and populates `required_filament_types` unconditionally (cheap; helps the scheduler reject obvious type mismatches even without `force_color_match`); and writes `filament_overrides` with `force_color_match: true` per consumed slot when a new per-VP setting `queue_force_color_match` is on. Default is **off** to preserve current behaviour for upgraders — a fresh-install user who wants the bug-free behaviour flips the toggle once on the VP card; an existing user gets exactly the model-only-matching they had before until they opt in. Auto-dispatch onto the wrong material happens loudly enough that anyone affected can find the toggle. **Why default-off** rather than default-on: existing automation that relies on "send to queue VP, get printed somewhere" without caring about colour shouldn't silently start blocking on colour matching after an upgrade. The toggle has clear UI copy (`virtualPrinter.queueForceColorMatch`) explaining the trade-off. **Defence in depth:** a malformed or unparseable 3MF (e.g. fake bytes from a misconfigured upload tool) leaves both fields None and the scheduler falls back to model-only matching, matching pre-fix behaviour for the unhappy path. The scheduler itself is unchanged — it already handled `force_color_match` correctly when the field was populated; the bug was purely the VP path not populating it. **Schema:** one nullable column `virtual_printers.queue_force_color_match BOOLEAN DEFAULT 0/FALSE` (Postgres-safe) added via the existing `_safe_execute` migration pattern. **API:** `VirtualPrinterCreate` and `VirtualPrinterUpdate` Pydantic schemas + `_vp_to_dict` response shape carry `queue_force_color_match`, the create + update routes wire it through to the model, and `VirtualPrinterInstance` constructor + `multiVirtualPrinterApi` TypeScript client mirror the field. **UI:** new toggle on `VirtualPrinterCard` rendered only when `mode === 'print_queue'` (parallels the existing `auto_dispatch` toggle's mode-gating), with `pendingAction` state for the in-flight indicator. **i18n:** new `virtualPrinter.queueForceColorMatch.{title,description}` keys in all 8 locales — English fully translated, German fully translated, the other 6 locales seeded with English copy pending native translation (matches the project's existing flow for newly-added user-facing features). 11 new tests: 8 in `test_filament_requirements.py` covering the extracted parser end-to-end (per-slot dicts, zero-use slots filtered, plate filtering, no-plate flat-walk fallback, unparseable / missing / config-less files, sorted output); 3 in `test_virtual_printer.py::TestVirtualPrinterInstance` covering the VP write path (setting-off → only `required_filament_types` populated; setting-on → `filament_overrides` populated with `force_color_match: true` per slot; unparseable 3MF → both fields None, no crash). Existing scheduler tests still pass against the refactored helper (verified end-to-end across the scheduler / virtual_printer / print_queue / filament test suites — 479 tests). Edward's "out of scope nice-to-have" suggestion of a "Requires Color Match" pill on queue cards is deferred to a follow-up so this PR stays scoped to his repro.
 
 - **Slicing a library file via API key fails with "no Bambu Cloud session is stored" even when the key has cloud access** ([#1182](https://github.com/maziggy/bambuddy/issues/1182) follow-up, reported by @turulix) — Tim shipped the headless slicing pipeline #1182 was filed for, then hit a second wall: `GET /api/v1/cloud/settings` returned the cloud preset IDs correctly (the `/cloud/*` router-level gate from #1182 was doing its job), but `POST /api/v1/library/files/{id}/slice` with those IDs in the request body failed the slice job with `error_status: 400, error_detail: "Cloud preset selected for printer, but no Bambu Cloud session is stored. Sign in to Bambu Cloud and retry."` Cause: the `/cloud/*` fix routes the API key's owner User through `cloud_caller` (a router-level gate stashes the owner on `request.state.api_key_owner`, route-level deps pull it back out), but the slice route lives on `/library/*` — different router, no gate, so when the auth dep returned `None` for the API-keyed request the slice route passed `current_user_id=None` straight through to `_run_slicer_with_fallback` → `_resolve_cloud(db, user=None)` → `get_stored_token(db, None)`, which falls back to the auth-disabled global `Settings` table. That table is empty in auth-enabled deployments, so cloud preset resolution failed even though the key's owner User had a perfectly valid `cloud_token` on their User row. Fix is a new route-level dep `resolve_api_key_cloud_owner` in `cloud.py` that's permissive (returns the owner User if the key has `can_access_cloud=true`, otherwise None — never raises) so it can be safely added to non-`/cloud/*` routes without breaking the local-presets path: a request with an API key that lacks the cloud scope still slices fine against local presets, and only fails with the existing "no Bambu Cloud session" error if it actually selects a cloud preset. Wired into `POST /library/files/{id}/slice` (Tim's blocker) and `GET /slicer/presets` (the SliceModal preset dropdown source — same root cause, would have hit anyone using the UI through an API-keyed reverse proxy). Both routes now resolve the cloud-token owner via `current_user or api_key_cloud_owner` instead of `current_user.id if current_user else None`. The auth gate's None-return for API keys is unchanged — keeping that fix scoped to the routes that actually need cloud-token resolution prevents accidental scope creep into other routes that fence on `current_user is None`. 4 new integration tests in `test_api_key_cloud_access.py::TestSliceRouteCloudOwnerResolution` pin the dep contract: returns the owner for a key with `can_access_cloud=True` and a valid owner; returns None for an owned key without the cloud scope (so cloud presets still 400 cleanly, local presets still slice); returns None for legacy ownerless keys; no-op for JWT and anonymous callers.
diff --git a/backend/app/main.py b/backend/app/main.py
index 9cab62495..9601ceeef 100644
--- a/backend/app/main.py
+++ b/backend/app/main.py
@@ -1,11 +1,13 @@
 import asyncio
 import logging
 import mimetypes as _mimetypes
+import os
 import posixpath
 import time
 from contextlib import asynccontextmanager
 from datetime import datetime, timedelta, timezone
 from logging.handlers import RotatingFileHandler
+from urllib.parse import urlparse
 
 from fastapi import FastAPI
 from fastapi.responses import FileResponse
@@ -4538,12 +4540,87 @@ PUBLIC_API_PATTERNS = [
 ]
 
 
+_security_headers_logger = logging.getLogger("backend.app.main.security_headers")
+
+
+def _parse_trusted_frame_origins() -> tuple[str, ...]:
+    """Parse TRUSTED_FRAME_ORIGINS env var into a validated allowlist (#1191).
+
+    Format: comma-separated list of ``scheme://host[:port]`` origins.
+
+    Used by ``security_headers_middleware`` to relax ``frame-ancestors`` for
+    trusted same-LAN deployments (e.g. Home Assistant Webpage panel embedding
+    Bambuddy from a different port). Defaults to empty — strict ``'none'``.
+
+    Invalid entries are dropped with a warning rather than failing startup, so
+    a typo in one origin doesn't take the whole deployment down.
+    """
+    raw = os.environ.get("TRUSTED_FRAME_ORIGINS", "").strip()
+    if not raw:
+        return ()
+    valid: list[str] = []
+    for item in raw.split(","):
+        candidate = item.strip()
+        if not candidate:
+            continue
+        try:
+            parsed = urlparse(candidate)
+        except ValueError as e:
+            _security_headers_logger.warning("TRUSTED_FRAME_ORIGINS: dropping %r — %s", candidate, e)
+            continue
+        if parsed.scheme not in ("http", "https"):
+            _security_headers_logger.warning("TRUSTED_FRAME_ORIGINS: dropping %r — must be http(s)", candidate)
+            continue
+        if not parsed.netloc:
+            _security_headers_logger.warning("TRUSTED_FRAME_ORIGINS: dropping %r — missing host", candidate)
+            continue
+        if parsed.path and parsed.path != "/":
+            _security_headers_logger.warning("TRUSTED_FRAME_ORIGINS: dropping %r — paths not allowed", candidate)
+            continue
+        if parsed.query or parsed.fragment:
+            _security_headers_logger.warning(
+                "TRUSTED_FRAME_ORIGINS: dropping %r — query/fragment not allowed", candidate
+            )
+            continue
+        if "*" in parsed.netloc:
+            _security_headers_logger.warning("TRUSTED_FRAME_ORIGINS: dropping %r — wildcards not allowed", candidate)
+            continue
+        valid.append(f"{parsed.scheme}://{parsed.netloc}")
+    if valid:
+        _security_headers_logger.info("TRUSTED_FRAME_ORIGINS: %s", ", ".join(valid))
+    return tuple(valid)
+
+
+_TRUSTED_FRAME_ORIGINS: tuple[str, ...] = _parse_trusted_frame_origins()
+
+
+def _frame_ancestors(default_value: str) -> str:
+    """Compose the ``frame-ancestors`` CSP directive (#1191).
+
+    ``default_value`` is the strict directive used when the operator has not
+    configured ``TRUSTED_FRAME_ORIGINS`` — typically ``'none'`` (catch-all and
+    docs) or ``'self'`` (gcode-viewer, served same-origin). When trusted origins
+    are configured, ``'self'`` is always included so same-origin embedding never
+    breaks even if an operator forgets to add their own origin to the list.
+    """
+    if _TRUSTED_FRAME_ORIGINS:
+        return "frame-ancestors 'self' " + " ".join(_TRUSTED_FRAME_ORIGINS) + ";"
+    return f"frame-ancestors {default_value};"
+
+
 @app.middleware("http")
 async def security_headers_middleware(request, call_next):
     """Add standard HTTP security headers to every response."""
     response = await call_next(request)
     response.headers["X-Content-Type-Options"] = "nosniff"
-    response.headers["X-Frame-Options"] = "SAMEORIGIN"
+    # X-Frame-Options is the legacy cross-origin embedding control. Modern
+    # browsers honour CSP frame-ancestors instead, and the legacy
+    # `ALLOW-FROM <url>` syntax is deprecated and inconsistent across vendors.
+    # When operators have explicitly allowlisted trusted frame origins (#1191
+    # — typically Home Assistant on a different port), drop X-Frame-Options
+    # and let the CSP-side frame-ancestors directive govern embedding.
+    if not _TRUSTED_FRAME_ORIGINS:
+        response.headers["X-Frame-Options"] = "SAMEORIGIN"
     response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
     # Content-Security-Policy for the React SPA.
     # Notes:
@@ -4566,8 +4643,7 @@ async def security_headers_middleware(request, call_next):
             "font-src 'self' data: https://fonts.gstatic.com; "
             "object-src 'none'; "
             "base-uri 'self'; "
-            "frame-src 'self' http: https:; "
-            "frame-ancestors 'self';"
+            "frame-src 'self' http: https:; " + _frame_ancestors("'self'")
         )
     elif request.url.path in ("/docs", "/redoc", "/docs/oauth2-redirect"):
         # FastAPI's built-in Swagger UI / ReDoc pages load assets from
@@ -4582,8 +4658,7 @@ async def security_headers_middleware(request, call_next):
             "font-src 'self' data: https://fonts.gstatic.com; "
             "worker-src 'self' blob:; "
             "object-src 'none'; "
-            "base-uri 'self'; "
-            "frame-ancestors 'none';"
+            "base-uri 'self'; " + _frame_ancestors("'none'")
         )
     else:
         response.headers["Content-Security-Policy"] = (
@@ -4596,8 +4671,7 @@ async def security_headers_middleware(request, call_next):
             "font-src 'self' data: https://fonts.gstatic.com; "
             "object-src 'none'; "
             "base-uri 'self'; "
-            "frame-src 'self' http: https:; "
-            "frame-ancestors 'none';"
+            "frame-src 'self' http: https:; " + _frame_ancestors("'none'")
         )
     if request.url.scheme == "https":
         response.headers["Strict-Transport-Security"] = "max-age=31536000; includeSubDomains"
diff --git a/backend/tests/integration/test_security_headers.py b/backend/tests/integration/test_security_headers.py
new file mode 100644
index 000000000..336040c0f
--- /dev/null
+++ b/backend/tests/integration/test_security_headers.py
@@ -0,0 +1,162 @@
+"""Integration tests for security_headers_middleware (#1191).
+
+Default behaviour is strict: ``X-Frame-Options: SAMEORIGIN`` plus
+``frame-ancestors 'none'`` on the catch-all route, ``frame-ancestors 'self'``
+on /gcode-viewer/. Operators can opt into iframe embedding from trusted
+origins (e.g. Home Assistant on a different port) via the
+``TRUSTED_FRAME_ORIGINS`` env var; when set, X-Frame-Options is dropped and
+``frame-ancestors`` includes the allowlist.
+"""
+
+from __future__ import annotations
+
+import pytest
+from httpx import AsyncClient
+
+# ─── helpers ──────────────────────────────────────────────────────────────
+
+
+def _parse_origins(value: str) -> tuple[str, ...]:
+    """Re-import the parser with a specific env var set, return its result.
+
+    Uses a fresh import so the module-level _TRUSTED_FRAME_ORIGINS is
+    re-evaluated against the patched os.environ.
+    """
+    import os
+
+    from backend.app import main as main_module
+
+    old = os.environ.get("TRUSTED_FRAME_ORIGINS")
+    try:
+        if value is None:
+            os.environ.pop("TRUSTED_FRAME_ORIGINS", None)
+        else:
+            os.environ["TRUSTED_FRAME_ORIGINS"] = value
+        # Function reads from os.environ each call.
+        return main_module._parse_trusted_frame_origins()
+    finally:
+        if old is None:
+            os.environ.pop("TRUSTED_FRAME_ORIGINS", None)
+        else:
+            os.environ["TRUSTED_FRAME_ORIGINS"] = old
+
+
+# ─── env-var parsing ──────────────────────────────────────────────────────
+
+
+class TestParseTrustedFrameOrigins:
+    """Unit tests for _parse_trusted_frame_origins."""
+
+    def test_empty_env_returns_empty_tuple(self):
+        assert _parse_origins("") == ()
+
+    def test_unset_env_returns_empty_tuple(self):
+        assert _parse_origins(None) == ()  # type: ignore[arg-type]
+
+    def test_single_origin(self):
+        assert _parse_origins("http://homeassistant.local:8123") == ("http://homeassistant.local:8123",)
+
+    def test_multiple_origins(self):
+        result = _parse_origins("http://homeassistant.local:8123,https://ha.example.com")
+        assert result == ("http://homeassistant.local:8123", "https://ha.example.com")
+
+    def test_whitespace_around_entries_stripped(self):
+        result = _parse_origins("  http://a.local:1 ,   https://b.local:2  ")
+        assert result == ("http://a.local:1", "https://b.local:2")
+
+    def test_empty_segment_skipped(self):
+        result = _parse_origins("http://a.local,,https://b.local")
+        assert result == ("http://a.local", "https://b.local")
+
+    def test_non_http_scheme_dropped(self):
+        # ftp://, javascript:, file:// etc. — never a valid frame ancestor.
+        assert _parse_origins("ftp://attacker.example,http://ok.local") == ("http://ok.local",)
+        assert _parse_origins("javascript:alert(1)") == ()
+
+    def test_missing_host_dropped(self):
+        # "http://" with no host
+        assert _parse_origins("http://") == ()
+
+    def test_path_dropped(self):
+        # frame-ancestors only takes scheme://host[:port], no path
+        assert _parse_origins("http://ha.local/dashboard") == ()
+
+    def test_query_or_fragment_dropped(self):
+        assert _parse_origins("http://ha.local?foo=1") == ()
+        assert _parse_origins("http://ha.local#frag") == ()
+
+    def test_wildcard_in_host_dropped(self):
+        # Wildcards would defeat the allowlist purpose; reject explicitly.
+        assert _parse_origins("http://*.example.com") == ()
+
+    def test_root_path_kept(self):
+        # Trailing slash is a degenerate but harmless path; treat as bare host.
+        assert _parse_origins("http://ha.local:8123/") == ("http://ha.local:8123",)
+
+
+# ─── HTTP integration: middleware emits expected headers ──────────────────
+
+
+@pytest.mark.asyncio
+@pytest.mark.integration
+async def test_default_headers_strict(async_client: AsyncClient, monkeypatch):
+    """Without env var: X-Frame-Options=SAMEORIGIN and frame-ancestors 'none'."""
+    monkeypatch.delenv("TRUSTED_FRAME_ORIGINS", raising=False)
+    # Re-import the module-level constant so the middleware closes over the new value.
+    from backend.app import main as main_module
+
+    monkeypatch.setattr(main_module, "_TRUSTED_FRAME_ORIGINS", ())
+
+    resp = await async_client.get("/api/v1/auth/status")
+    assert resp.headers.get("X-Frame-Options") == "SAMEORIGIN"
+    assert "frame-ancestors 'none'" in resp.headers.get("Content-Security-Policy", "")
+
+
+@pytest.mark.asyncio
+@pytest.mark.integration
+async def test_trusted_origins_relaxes_csp_and_drops_xfo(async_client: AsyncClient, monkeypatch):
+    """With env var set: X-Frame-Options is absent, frame-ancestors lists the origins."""
+    from backend.app import main as main_module
+
+    monkeypatch.setattr(
+        main_module,
+        "_TRUSTED_FRAME_ORIGINS",
+        ("http://homeassistant.local:8123",),
+    )
+
+    resp = await async_client.get("/api/v1/auth/status")
+    assert "X-Frame-Options" not in resp.headers
+    csp = resp.headers.get("Content-Security-Policy", "")
+    assert "frame-ancestors 'self' http://homeassistant.local:8123;" in csp
+    assert "'none'" not in csp.split("frame-ancestors")[1].split(";")[0]
+
+
+@pytest.mark.asyncio
+@pytest.mark.integration
+async def test_trusted_origins_applies_to_docs_branch(async_client: AsyncClient, monkeypatch):
+    """The /docs CSP also honors the allowlist (consistent with main app)."""
+    from backend.app import main as main_module
+
+    monkeypatch.setattr(
+        main_module,
+        "_TRUSTED_FRAME_ORIGINS",
+        ("https://ha.example.com",),
+    )
+
+    resp = await async_client.get("/docs")
+    csp = resp.headers.get("Content-Security-Policy", "")
+    assert "frame-ancestors 'self' https://ha.example.com;" in csp
+
+
+@pytest.mark.asyncio
+@pytest.mark.integration
+async def test_other_security_headers_unchanged(async_client: AsyncClient, monkeypatch):
+    """Other headers (X-Content-Type-Options, Referrer-Policy) are not affected."""
+    from backend.app import main as main_module
+
+    # Test in both modes — headers should be the same regardless.
+    for origins in [(), ("http://homeassistant.local:8123",)]:
+        monkeypatch.setattr(main_module, "_TRUSTED_FRAME_ORIGINS", origins)
+        resp = await async_client.get("/api/v1/auth/status")
+        assert resp.headers.get("X-Content-Type-Options") == "nosniff"
+        assert resp.headers.get("Referrer-Policy") == "strict-origin-when-cross-origin"