# ADR-0116: HMAC Non-Enforcement (Reserved for Future Use)

Status: Accepted

## Context

The E27 protocol includes link-layer and session-layer HMAC fields intended for
message integrity and authentication. Vendor guidance indicates that these HMAC
mechanisms are currently defined for future use and are not enforced by present
panel firmware.

Premature enforcement of HMAC validation would risk:
- false negatives on valid traffic
- unnecessary connection failures
- incompatibility with current firmware behavior

At the same time, the architecture must remain forward-compatible with future
firmware that may require HMAC enforcement.

## Decision

HMAC fields are treated as non-enforced, forward-compatible metadata.

1. The library parses, stores, and propagates HMAC-related fields as defined by
   the protocol.

2. The library does not reject frames or messages solely due to:
   - missing HMAC
   - invalid HMAC
   - HMAC mismatch

3. HMAC values are not used as part of replay protection or message validation
   in the current architecture.

4. HMAC enforcement is explicitly deferred until the vendor enables and
   documents required behavior in panel firmware.

5. Any future introduction of HMAC enforcement must be accompanied by a new
   ADR that defines:
   - enforcement scope
   - failure behavior
   - migration and compatibility strategy

## Rationale

Deferring enforcement:
- aligns with vendor-defined current behavior
- avoids introducing correctness or interoperability regressions
- preserves architectural clarity by treating HMAC as optional today

Explicitly documenting non-enforcement prevents accidental partial or implicit
use by future contributors.

## Consequences

- HMAC-related code paths exist but are passive.
- Security guarantees rely on existing encryption and session semantics.
- Future firmware updates may require architectural revision.

## Scope / Non-Goals

- Does not implement partial or “best effort” HMAC checks.
- Does not define how HMAC keys are generated or rotated.
- Does not provide user-facing configuration for HMAC strictness.

## References

- ADR-0105: E27 Error Classification and Responsibility Boundaries
- ADR-0106: Replay, Ordering, and Idempotency Policy
- E27 API Comms Protocol
