0022. Finding the hub on the network

• Status: Accepted
• Date: 2026-10-28

Context

A hub on a shop’s LAN usually gets its IP address from the router. After a power cut or a router change, the address can change, and every paired device loses the hub until someone types the new address into each one (Change hub address, M7). The hub already announces itself over mDNS as _openkedai._tcp (ADR 0019), but nothing listened.

Following a hub automatically has a risk that typing an address doesn’t: a device follows whatever answers on the network. Anyone on the shop’s Wi-Fi can announce a service with any name. A device that sent its token to such a service would hand over the shop’s access.

Decision

The hub’s identity.

• Each hub makes a random hub id once and keeps it in its registry (hub_state.hub_id).
• The id is in the hub’s mDNS TXT record (id, next to api), in GET /api/hub, in the credentials from claiming, pairing and rejoining, and in GET /api/devices/me.
• Devices store it with the hub’s address (hub.id). It is optional in the protocol, so devices paired before M8.5 learn it the first time they follow the hub.

Proving the hub is the device’s own, before the token is sent.

• The hub stores only the SHA-256 of each device token. A device that finds a candidate hub sends POST /api/hub/prove with its device id and a fresh random nonce (no token).
• The hub answers with HMAC-SHA256(key = token hash, message = nonce) for each working token of that device. The device computes the same from its own token and compares.
• Only a hub that holds the token’s hash can answer. A new nonce each time means an answer can’t be replayed. A removed device has no working token, so its old hub can’t prove anything.
• Only after the proof does the device send its token, to GET /api/devices/me. It follows the hub if the answer names the same shop and device. This is the same check as Change hub address.

When a device looks.

• The app feeds the sync engine’s status to a HubFollower. It starts looking when the hub stops answering, or when the hub at the old address doesn’t know the device (another hub took its address).
• It looks 5 seconds after the hub is lost, then every 20 seconds while it stays lost. Each look browses for 4 seconds. A device follows a restarted hub within about 30 seconds of it answering again.
• It considers only hubs advertising its hub id. A device without a stored id considers every hub that has one, and the proof filters the rest.
• When the hub is still at its old address, the device just syncs again at once.
• It doesn’t look for a hub whose address is https://. Such a hub is on the internet or behind a proxy with a fixed name, so it doesn’t move around a LAN.

Native code. A new Expo module, openkedai-discovery, has one call: browse(type, timeoutMs). It lists the services found, each with its IPv4 addresses, port and TXT record.

• iOS: Network.framework’s NWBrowser, resolving each service by connecting to it over IPv4. The app declares NSBonjourServices: ["_openkedai._tcp"] for iOS’s local network permission.
• Android: NsdManager, resolving one service at a time (older Android allows only one at a time).
• Web preview and Expo Go: browsing isn’t available, and the app simply doesn’t look.

Joining. The join screen and Change hub address list the hubs found on the network. Tapping one fills in its address; the pairing code is still needed.

Consequences

• Hub IP changes: devices reconnect on their own, with no one touching them. A fixed address in the router is no longer needed, though it is still a good idea.
• Spoofed hubs: something announcing the shop’s hub id gets a nonce, never a token.
  • A copy of the hub’s registry (hub.sqlite) could pass the proof. Whoever has that file has the hub’s data anyway.
  • Plain HTTP on the LAN can still be watched, as ADR 0019 says.
• Network limits: mDNS doesn’t cross routers or VLANs, and some guest Wi-Fi networks block it. There, devices keep retrying the old address, and Change hub address remains the way to move them.
• Android emulator: the emulator’s own network usually doesn’t receive the Mac’s mDNS, so checking discovery on Android may need a real device on the same Wi-Fi.
• Old hubs: devices can’t follow a hub older than M8.5. Its info has no hub id, and it has no prove route.
• Hub port: the hub now advertises the port it actually listens on, not the configured one. They differ only when the configured port is 0.