# DDR-0014: Client Serial Number Derived from Outbound Interface MAC Address

Status: Accepted  
Date: 2025-12-22  
Related ADRs: ADR-0012 (Inventory-Driven API Surface), ADR-0007 (E27 Layering)

## Context

The E27 `api_link` and subsequent authentication flows require a client serial number
(`sn`) to uniquely identify the client to the panel. Hard-coding a serial number or
requiring user configuration introduces friction and risk of duplication across clients.

A deterministic, locally-derivable identifier is preferred for both live testing and
production use.

## Decision

The client serial number (`sn`) will be derived from the MAC address of the outbound
network interface used to reach the panel.

Derivation rules:
- Determine the outbound local IP by creating a UDP socket connected to the panel IP.
- Resolve the network interface that owns that local IP.
- Read the MAC address of that interface.
- Format `sn` as uppercase hexadecimal with no separators.

Example:
- MAC address: `aa:bb:cc:dd:ee:ff`
- Derived `sn`: `AABBCCDDEEFF`

If the outbound interface cannot be resolved deterministically:
- Fall back to a best-effort system identifier (e.g., `uuid.getnode()`).
- Emit a warning indicating reduced identity stability.

## Rationale

- Ensures uniqueness across clients without user configuration
- Stable across reboots on the same machine and interface
- Reflects the actual network path used to reach the panel
- Aligns with the E27 protocol’s expectation of a client identifier
- Simplifies live testing and Home Assistant deployment

## Consequences

- Changing the outbound interface or routing path may change the derived `sn`
- Multi-homed systems may present different identities depending on route selection
- Documentation and logs must clearly indicate how `sn` is derived for troubleshooting
- The derivation logic must run before `api_link` hash computation
