Add client support for ephemeral key (ePSKc) credentials sharing

[lboue]

Summary

• Adds client support for Thread 1.4 Credentials Sharing / ephemeral key (ePSKc), per [Request] Add support for EphemeralKey (ePSK) #211
• New OTBR methods: get_ephemeral_key_enabled, set_ephemeral_key_enabled, get_ephemeral_key_status, activate_ephemeral_key, deactivate_ephemeral_key
• New models: EphemeralKeyState, EphemeralKeyStatus, EphemeralKeyActivationResult
• New exceptions: EphemeralKeyNotSupportedError (404), EphemeralKeyConflictError (409)

Wraps the /node/ba-epskc/state and /node/ba-epskc/key REST endpoints as implemented in @puddly's reference branch (openthread/ot-br-posix@main...puddly:epsck-rest).

See discussion in #211. This PR is here to get early feedback on the client-side API shape; it'll need re-checking once the server-side endpoints actually land upstream (paths/JSON could still change).

Test plan

• pytest — full suite passes (90 tests, 16 new)
• mypy — clean
• pylint — 10/10
• black/flake8 — clean
• Verify against a real otbr-agent build once OTBR_ENABLE_EPSKC
• the upstream PR lands

Closes #211 once server-side support is available.

[lboue]

Test results

Unit tests (tests/test_ephemeral_key.py, mocked REST server):

============================= test session starts ==============================
platform linux -- Python 3.12.3, pytest-9.1.1, pluggy-1.6.0
plugins: asyncio-1.4.0
collected 15 items

tests/test_ephemeral_key.py::test_get_ephemeral_key_enabled_true PASSED  [  6%]
tests/test_ephemeral_key.py::test_get_ephemeral_key_enabled_false PASSED [ 13%]
tests/test_ephemeral_key.py::test_get_ephemeral_key_enabled_not_supported PASSED [ 20%]
tests/test_ephemeral_key.py::test_get_ephemeral_key_enabled_unexpected_status PASSED [ 26%]
tests/test_ephemeral_key.py::test_set_ephemeral_key_enabled PASSED       [ 33%]
tests/test_ephemeral_key.py::test_set_ephemeral_key_enabled_not_supported PASSED [ 40%]
tests/test_ephemeral_key.py::test_get_ephemeral_key_status PASSED        [ 46%]
tests/test_ephemeral_key.py::test_get_ephemeral_key_status_not_supported PASSED [ 53%]
tests/test_ephemeral_key.py::test_get_ephemeral_key_status_invalid PASSED [ 60%]
tests/test_ephemeral_key.py::test_activate_ephemeral_key_defaults PASSED [ 66%]
tests/test_ephemeral_key.py::test_activate_ephemeral_key_with_params PASSED [ 73%]
tests/test_ephemeral_key.py::test_activate_ephemeral_key_conflict PASSED [ 80%]
tests/test_ephemeral_key.py::test_activate_ephemeral_key_not_supported PASSED [ 86%]
tests/test_ephemeral_key.py::test_deactivate_ephemeral_key PASSED        [ 93%]
tests/test_ephemeral_key.py::test_deactivate_ephemeral_key_not_supported PASSED [100%]

============================== 15 passed in 0.07s ==============================

Live end-to-end test against a real OTBR server, to validate the wire contract (paths, tap/state/port field names, 409 conflict handling) rather than just mocks:

• Server: otbr-agent built from openthread/ot-br-posix#3480 (adds the /node/ba-epskc/state and /node/ba-epskc/key REST endpoints this client talks to), same OpenThread core config as the Home Assistant openthread_border_router add-on.
• Radio: real hardware, Nabu Casa ZBT-2 (Silicon Labs EFR32 RCP, SL-OPENTHREAD/3.0.0.0_GitHub-61e43cffb) over spinel+hdlc+uart.
• Client: this branch's python_otbr_api.OTBR, unmocked, talking to http://127.0.0.1:8081.

get_ephemeral_key_enabled -> True   # (persisted from a previous run)
set_ephemeral_key_enabled(True) -> OK
get_ephemeral_key_enabled -> True
get_ephemeral_key_status -> EphemeralKeyStatus(state=<EphemeralKeyState.STOPPED: 'stopped'>, port=0)
activate_ephemeral_key -> EphemeralKeyActivationResult(tap='382181509', port=49154)
get_ephemeral_key_status -> EphemeralKeyStatus(state=<EphemeralKeyState.STARTED: 'started'>, port=49154)
second activate_ephemeral_key -> EphemeralKeyConflictError (expected)
deactivate_ephemeral_key -> OK
get_ephemeral_key_status -> EphemeralKeyStatus(state=<EphemeralKeyState.STOPPED: 'stopped'>, port=0)
set_ephemeral_key_enabled(False) -> OK
get_ephemeral_key_enabled -> False

Both the mocked unit tests and the live hardware round-trip confirm the client and server agree on the REST contract end-to-end.

[lboue]

Working fine with modified OpenThread Border Router M5Stack Example.

[lboue]

The upstream PR has been merged.
openthread/ot-br-posix#3480

[lboue]

@puddly
Can we merge this and include it in a beta version?

[puddly]

Looks good to me!

[lboue]

@puddly Are we implementing API version validation in this PR?

[puddly]

Any operation interacting with ePSKc when the OTBR doesn't support it will throw EphemeralKeyNotSupportedError so I think we technically don't need to, Core can check get_ephemeral_key_enabled() on OTBR integration startup. But a feature bitmap would be nice to have to reduce startup traffic.