# automation-access-broker

Automation MCP access broker: tiered, human-gated access to Home
Assistant entities, on the access-broker suite architecture (see
AUTHORS.md for provenance). Formerly smarthome-access-broker; the
product renamed to automation-access-broker (2026-09-21 decision: the
domain's invariant is an access that ends in a physical change,
automated for the user).

## What it is

One MCP server brokering an AI agent's access to a Home Assistant
instance: the agent sees the house freely, adjusts reversible comfort
freely, and touches locks, alarm panels, covers, and climate setpoints
only through per-operation human approvals (Matrix reactions), with
admin functions gated and never delegated. Built on access-broker-core
(grant lifecycle, hash-chained write-before-operate audit, tier
mechanics, approval-gateway core); this broker contributes the smart
home wall (entity/class scoping), the Home Assistant backend, and the
physical-domain tier table.

## The tier model for physics

- **T0 free reads:** entity state, entity list, subscriptions.
  Occupancy-derived reads (person, device_tracker, zones,
  motion/occupancy/presence sensors) are audit-logged even though
  free.
- **T1 free, audit-logged (reversible comfort):** lights, fans,
  switches, media player, input helpers.
- **T2 gated, per operation (no batches):** lock/unlock/open,
  alarm arming/disarming, cover open/close/position/tilt, climate
  set-temperature/preset. Physical actuators have no version history;
  per-operation approval is the compensating-control argument applied
  honestly. A configurable climate band narrows set-temperature calls:
  in-band calls ride an approved band grant (a grant carrying the
  climate_band marker, requested automatically for in-band calls);
  outside the band is always gated and rides only an explicit
  per-operation grant.
- **Fan-out:** scenes and scripts are classified by what they expand
  to, not their names. An unresolvable expansion fails closed to
  gated.
- **T3 gated, never delegated:** automation/script reload, HA
  restart/stop, zone/person/config administration.

## What is NOT here (v1)

Hubitat (Maker API tokens are all-or-nothing: a permanent custody
caveat, designed-unbuilt), Matter native adapter, raw MQTT (untyped
pub/sub has no scope object to grant). File storage is the data
broker's domain; PIM is the groupware broker's; chat is the
communications broker's.

## Status

Production alpha (owner-verified live 2026-09-22 through the native
MCP client: a comfort-tier switch op executed and audited in the free
lane, and the full gated loop on a garage cover — pending request,
human approval, execute, state read back through the broker, per-
operation grant granularity confirmed). 350 tests across fourteen
files. See CHANGELOG.md and DEPLOYMENT.md (including the user-space
systemd supervision section).

## Production-alpha notes

- **Bearer transport contract.** Transport http requires
  `auth.bearer.token_env` (refuse-to-start without it): every request
  presents `Authorization: Bearer <token>`, compared constant-time
  through the core's `check_static_credential` before any MCP parsing.
- **Lifecycle notices.** The approval gateway announces
  `gateway started` / `gateway stopping` in the approval room; a
  delivery failure is logged and swallowed (a notice must never kill
  the gateway).
- **Service-name shape.** `call_entity_service` requires the full
  `domain.service` form (`switch.turn_off`); a bare service name is
  refused with a named error. Cosmetic item on the queue: accept the
  bare form when the entity's domain disambiguates it.
- **T2 grant semantics (open, owner decision pending, suite-wide).**
  An approved T2 grant carries a time window; no consume-on-use path
  exists in v1. Options on record: execute-time self-revocation after
  a gated op fires, or a docstring correction to match the window.
  Per-operation grant granularity is confirmed live: an open grant
  did not cover close.
- **Shared-room routing.** When one approval room serves several
  broker gateways (Option B), every typed command carries the broker's
  tag (`automation approve 3`) and every outbound message is stamped
  `[automation]`; unprefixed commands are refused with a hint, never
  guessed at.

## License

GPL-3.0-or-later. See AUTHORS.md for provenance.