# ADR-0115: Privilege Lifetime and Sliding TTL (60 Seconds)

Status: Accepted

## Context

The E27 panel grants elevated session privileges (via PIN authorization) on a
temporary basis. According to vendor guidance, privilege persistence is time-
limited and automatically expires unless refreshed by additional privileged
commands.

Without a defined architectural policy, Home Assistant risks:
- prompting for PIN too often (poor UX), or
- assuming privilege persists longer than the panel allows (command failures)

This behavior must be modeled explicitly so permission-aware command planning
(ADR-0110) remains correct and predictable.

## Decision

Elevated session privilege is modeled as a time-limited, sliding window with a
60-second duration.

1. After a successful privilege escalation, the session is considered
   privileged for 60 seconds.

2. Each subsequent privileged command sent to the panel within that window
   resets the 60-second privilege timer.

3. If no privileged command is sent within the window, privilege expires
   automatically and the session reverts to baseline permission.

4. Privilege expiration is treated as a normal lifecycle event, not an error.

5. The library tracks privilege lifetime and exposes it semantically to higher
   layers (e.g., via privilege state and expiration events).

6. Home Assistant must not prompt for a PIN if:
   - the required permission level is already satisfied, and
   - the current privilege window has not expired.

7. Home Assistant must prompt for a PIN proactively (per ADR-0110) if:
   - a command requires elevated permission, and
   - the privilege window has expired or is absent.

## Rationale

Modeling privilege as a sliding TTL:
- matches panel behavior exactly
- minimizes unnecessary PIN prompts
- avoids reliance on error-driven authorization
- provides predictable timing semantics for both manual actions and automations

Treating expiration as a lifecycle transition (rather than a failure) keeps
control flow simple and observable.

## Consequences

- The library must track privilege expiration time using a monotonic clock.
- Privilege refresh occurs implicitly on successful privileged commands.
- Home Assistant may display or log privilege expiration but does not treat it
  as a fault.
- Automations that require privilege must ensure commands are sent within the
  active window or trigger re-authorization.

## Scope / Non-Goals

- Does not define how PINs are stored or entered.
- Does not extend privilege beyond the panel-defined window.
- Does not guarantee uninterrupted privilege across reconnects.

## References

- ADR-0110: Permission-Aware Command Planning
- ADR-0111: E27 Request Concurrency and Backpressure
- E27 API Permission Levels
