# DDR-0023: Provisioning Flow and Home Assistant Credential Exchange

Status: Approved
Date: 2025-12-22
Applies to: elkm1/elke27_lib (E27 only)

Related ADRs:
- ADR-0004: E27 Transport and Session Model
- ADR-0006: E27 Cryptographic Model and Key Handling
- ADR-0009: Home Assistant as Configuration Authority

Related DDRs:
- DDR-0020: Silent Failure Behavior on Invalid Credentials
- DDR-0022: Session Lifecycle and Framed vs Unframed Traffic Handling

---

Context

The Elk E27 panel requires an API_LINK exchange using an access code and pass phrase in order to establish a persistent link key and link HMAC. The panel exhibits silent failure behavior when these credentials are incorrect.

For security reasons:
- Access code
- Pass phrase
- User PIN

must NOT be stored persistently by the E27 library.

Therefore, a mechanism is required to obtain credentials from Home Assistant at runtime when provisioning or re-provisioning is required.

---

Decision

A dedicated provisioning flow SHALL be implemented, coordinated by a provisioning module.

Responsibilities are divided as follows:

- session.py
  - Detects absence of valid link credentials
  - Detects silent failure / timeout during API_LINK
  - Signals provisioning-required state

- provisioning.py
  - Coordinates credential exchange with Home Assistant
  - Requests access code and pass phrase from the user
  - Supplies credentials to linking.py for a single API_LINK attempt
  - Ensures credentials are not retained after use

- linking.py
  - Performs API_LINK protocol exchange only
  - Does not own credential storage
  - Does not interact directly with Home Assistant

---

Implementation Rules

- Credentials SHALL be held in memory only for the duration of API_LINK
- Credentials SHALL NOT be written to disk or logs
- If API_LINK times out or fails silently, provisioning SHALL be re-triggered
- session.py SHALL remain agnostic of credential contents

---

Rationale

This separation:
- Aligns with Home Assistant’s security model
- Avoids long-term storage of sensitive credentials
- Cleanly isolates user interaction from protocol logic
- Allows re-provisioning without restarting the integration

The panel’s silent failure behavior makes explicit provisioning orchestration mandatory.

---

Consequences

- provisioning.py becomes the sole bridge between Home Assistant and E27 credentials
- session.py can be implemented without any knowledge of access code or pass phrase
- Future UI or onboarding changes are isolated from protocol code

This decision is binding for all E27 provisioning behavior.
