# ADR-0110: Permission-Aware Command Planning (Proactive PIN Prompting)

Status: Accepted

## Context

The E27 panel enforces a minimum required permission level for API handlers.
Permission is session-scoped and can be elevated via user credential (PIN)
authorization.

If Home Assistant always attempts an action first and only prompts for a PIN
after receiving an "authorization required" response, it introduces:
- unnecessary round trips
- slower user experience
- noisy error handling paths for routine privileged actions

The E27 API Permission Levels documentation defines a permission ladder
(PLT_ENCRYPTION_KEY, PLT_ANY_USER, PLT_MASTER_USER, PLT_INSTALLER_USER, and
*_DISARMED variants) and notes additional layered requirements such as:
- area permission constraints
- user-group based permission gating
- “automation authority” requirements for many automation-oriented domains

This information can be used to decide whether a PIN is required before
sending the command.

## Decision

Home Assistant will implement permission-aware command planning for E27:

1. Each supported E27 API command has an associated required permission level
   and optional additional constraints (gates) derived from authoritative
   documentation and the committed API inventory.

2. Before issuing a command that can change panel state, the integration
   compares:
   - required_permission_level (command metadata)
   against:
   - current_permission_level (session state as reported by the library)

3. If current permission is insufficient, Home Assistant prompts for a PIN
   proactively (before sending the command), performs authorization escalation,
   and then issues the command once in the correct privilege context.

4. Additional constraints are evaluated locally when possible and used to
   guide UX before prompting:
   - “*_DISARMED” constraints require all relevant areas disarmed; if not,
     Home Assistant guides the user to disarm first (no PIN prompt yet).
   - “automation authority” constraints are surfaced to the user as part of
     the PIN prompt context.
   - area permission constraints are surfaced to the user as “PIN must have
     access to Area X.”

5. The integration retains support for handling “authorization required”
   responses as a safety net, because the panel may enforce constraints
   (e.g., user-group membership) that are not fully knowable locally.

## Rationale

This approach:
- eliminates the common “try → fail → prompt → retry” loop
- improves responsiveness for privileged actions
- reduces reliance on error-driven control flow
- keeps security semantics correct by honoring panel-defined permission levels
- respects layered authorization rules while still providing a fallback path

## Consequences

- The E27 API inventory must carry permission metadata per command:
  - required_permission_level
  - optional gates: requires_disarmed, requires_automation_authority,
    requires_area_permission
- The library must expose the session’s current permission level as a stable,
  semantic attribute and emit events when it changes.
- Home Assistant must provide a PIN prompt UX path suitable for:
  - manual UI actions
  - (optionally) automations, if the user supplies a stored credential
- Some commands may still require panel feedback to confirm authorization due
  to layered rules; proactive prompting reduces but does not eliminate this.

## Scope / Non-Goals

- Does not define how PINs are stored; storing PINs is optional and must be
  user-controlled.
- Does not require Home Assistant to model every possible panel user-group or
  area permission rule locally.
- Does not mandate how long an elevated session remains privileged; session
  lifetime policy may be handled separately.

## References

- E27 API Permission Levels (docx)
- ADR-0012: Stable Inventory-Driven E27 API Surface
- ADR-0105: E27 Error Classification and Responsibility Boundaries
- ADR-0106: Replay, Ordering, and Idempotency Policy (Current and Deferred)
- ADR-0109: Home Assistant Integration Adapts to E27 Library Model
