Refuse privileged HA commands on unencrypted connections (B2)

[bbangert]

DRAFT — blocked. Depends on espex#23 being merged and published to hex. mix.exs currently pins espex to that branch; that pin must go back to a hex constraint before merge. A git/path espex dep has caused problems in this project before, so it's called out loudly rather than left as a footnote.

Closes B2 from the /phx:review of #161.

The problem

Firmware Install, Factory Reset and Reboot are reachable by anything on the LAN while the device is keyless. Verified in the dependency source rather than inferred:

• esphome/supervisor.ex:66-70 — psk = PskStore.load_psk() is nil until Home Assistant provisions, so a fresh device runs keyless.
• deps/espex/lib/espex/dispatch.ex:105-107 — espex answers every AuthenticationRequest with invalid_password: false. There is no password check to fail.
• deps/espex/lib/espex/dispatch.ex:425-431 — entity commands route on adapter presence alone. No auth, no encryption, no hello gate.

Once a PSK exists espex enforces encryption properly (a plaintext client gets a handshake rejection), so the exposure is confined to the keyless window — but that window is open indefinitely on a device nobody has adopted yet.

Scoped honestly: this is not arbitrary-firmware execution. :repo is only settable over SSH/IEx, so the reachable outcome is "force-install the legitimate release, then reboot" — availability, not RCE. Factory Reset and Reboot were already on this surface before #161; that PR added flash to it.

Why not just close the window

The keyless window is how HA adopts the device — it connects plaintext and provisions the PSK. Refusing all commands keyless would break onboarding, and refusing none leaves reboot/wipe/reflash exposed. The distinction is per-entity, which is app knowledge, so espex#23 passes the security context and this PR makes the policy decision:

@privileged_object_ids ~w(firmware_update factory_reset reboot)

Those three are refused unless the connection is encrypted; every diagnostic entity keeps working keyless. Refusals return :ok — the protocol has no "denied" reply for a command, so the warning is the audit trail.

What this does not fix

Only the app's own entities. Any other privileged adapter surface is out of scope, and the underlying "keyless means anonymous" property of the protocol is unchanged — this narrows the blast radius rather than removing it. The real close is HA provisioning a PSK, which the app already invites via accepts_key_provisioning.

Pairs with nerves_github_updater#3 (B3), which removes the replay loop independently — so even a caller that is allowed to install can't loop the device.

Verification

• mix compile --warnings-as-errors — PASS
• mise run test — 958 passed, 3 excluded (5 new)
• mix dialyzer — PASS (7 errors, 7 skipped, 0 unnecessary skips)
• MIX_TARGET=rpi3 mix compile — PASS

Mutation-tested: dropping firmware_update from the privileged list fails 2 tests.

Before merge

1. Merge + publish espex#23
2. Replace the git pin with the matching hex constraint
3. Re-run mix deps.get and the suite

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds connection-aware authorization to protect destructive ESPHome commands from plaintext clients.

Changes:

• Rejects firmware install, factory reset, and reboot commands on unencrypted connections.
• Adds tests covering privileged-command identification and encrypted/plaintext behavior.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
lib/universal_proxy/esphome/entity_provider.ex	Adds security-context command filtering and audit logging.
test/universal_proxy/esphome/entity_provider_test.exs	Tests privileged-command filtering.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.