# DDR-0007: Separate linking.py and hello.py Modules for Handshake Phases

Status: Accepted  
Date: 2025-12-22  
Related ADRs: ADR-0003 (linking vs session lifetimes)

## Context

E27 startup includes distinct phases:
- Linking: establishing/storing long-lived link key and link HMAC
- Hello/session establishment: receiving session key and session HMAC encrypted under the link key

These messages have quirks (field placement, special cases) and different lifetime rules
for derived secrets.

## Decision

Handshake phases will be implemented in dedicated modules:

- linking.py: build link request, parse link response, extract/store link key + link HMAC
- hello.py: build hello request, parse hello response, obtain session material (via encryption.py)

These modules return normalized results suitable for Home Assistant persistence (link keys)
and runtime-only session state (session keys).

## Rationale

- Keeps handshake quirks out of message dispatch and general encryption paths
- Enforces clear key lifetimes (link keys persisted; session keys ephemeral)
- Improves testability with captured buffers and specific validation rules
- Provides clean boundaries for HA config/discovery flows

## Consequences

- message dispatch modules must not implement linking/hello parsing logic
- hello.py must call encryption.decrypt_session_material() to derive session keys
- link key and link HMAC must be exportable in a HA-friendly representation (e.g., base64)
