lucky-cat/docs/adr/0004-device-auth-persistence-port.md

ADR 0004: Device Auth Persistence Port Ownership

Status

Accepted

Context

Device authentication persists long-lived key material and runtime JWT/backoff state. The bytes are meaningful only to the authentication policy, but the storage location also needs legacy migration names and must stay off the generic platform key/value API at upper layers.

Decision

• platform owns only opaque blob key/value primitives and NVS mechanics.
• domain owns the narrow auth persistence port: the public auth record slot enum, mapping to storage namespaces/keys, legacy migration target names, and atomic load/save adapter.
• control_plane owns the serialized auth key/state schemas, challenge/response policy, JWT refresh policy, retry/backoff state transitions, and factory rotation behavior.
• Upper layers must not call generic storage adapters for auth records. They must use domain_runtime_auth_store_load_record() and domain_runtime_auth_store_save_record().

Consequences

• Auth persistence has one facade declaration without exposing platform storage types to control_plane.
• Changing the serialized record layout remains a control_plane migration concern.
• Changing NVS namespace/key migration names remains a domain adapter concern.
• A future secure-element or encrypted-storage backend can replace the platform blob primitive without changing auth policy contracts.