feat(protocol): discover advertised OCF secure endpoints

[atc722]

Summary

• add a bounded known-host API that discovers secure ports advertised by GET /oic/res?rt=oic.r.doxm
• add an explicit identity-aware IPv4 multicast API that returns the address and secure ports from the one exact di container
• keep both entry points independent: neither calls the other, starts an automatic fallback, probes DTLS, or changes an existing caller's discovery latency
• harden CoAP parsing and keep addresses, UUIDs, ports, and wire data out of result representations

Why both paths are included

These APIs solve the same endpoint-selection problem under two different trust conditions:

1. If the caller already trusts the appliance IP, the known-host API performs one bounded unicast directory lookup.
2. If one IP exposes multiple logical OCF devices, the caller can explicitly use the SmartThings OCF di to select the matching response source and secure endpoint.

Keeping only the known-host path leaves the representative/root-device ambiguity unresolved. Making multicast an automatic fallback would instead slow existing setup flows. The combined API surface makes that choice explicit.

A redacted live acceptance run demonstrated the distinction: both entry points found exactly one statelessly confirmed DTLS listener on the same host, but the candidate sets were different. No IP, UUID, or port values were retained in the evidence.

Bounds and safety

• known-host default socket-I/O budget: 3 seconds total; retries share that deadline
• multicast: exactly two NON rounds, a 6-second collection window per round, at most 64 datagrams per round
• exact normalized top-level di match; no pi fallback
• legacy ports are bound to the response source; eps hosts must equal that source
• multicast succeeds only when both rounds produce the same sole source and non-empty port set
• advertisements remain candidates and still require stateless DTLS plus authenticated device-identity checks
• no ownership transfer, credential acquisition, authentication attempt, control command, or OCF security-resource write

The implementation is split into two logical commits so the known-host transport and identity-aware selection can be reviewed independently inside one PR.

Validation

• python -m pytest -q: 220 passed on Python 3.13
• focused discovery/public API/PSK compatibility tests: 121 passed
• git diff --check origin/main...HEAD
• python tools/check_share_safety.py --changed-since origin/main
• Ruff check on the changed Python files
• wheel and sdist build, distribution-content check, and isolated imports
• redacted GET-only live discovery plus one-ClientHello stateless DTLS checks for both paths

The repository CI matrix remains responsible for Python 3.11, 3.12, and 3.14 coverage.