Module pairing 

Pairing: nonce verification + device-token issuance (PROTOCOL.md §5/§6).

Flow: an unprovisioned device advertises ryu-pair://<device_id>?n=<nonce>&t=<type> (QR for watch/desk, BLE characteristic for necklace). The signed-in mobile app calls POST /api/hardware/pair { device_id, pairing_nonce, device_type }; this module verifies the nonce, registers the device, and returns a per-device device_token + node_url. The app then provisions the device over BLE.

Trust model

The pairing nonce is generated on the device at boot and shown to the user out-of-band (a QR code on the watch/desk screen, or read over a local BLE GATT characteristic on the necklace). Possession of the nonce is therefore the proof that the app is physically near the device. The node does not pre-know the nonce; it accepts the first pairing call that presents a well-formed nonce for an unpaired device_id, registers the device, and then burns that (device_id, nonce) pair so the same QR can’t be replayed to mint a second token. A device_id that is already paired is rejected (re-pair requires an explicit revoke first), which prevents a stranger who later sees the QR from hijacking an in-use device.

Enums

PairError

Why a pairing attempt was rejected (maps to an error.code / HTTP status).

Functions

generate_device_id

Generate a stable per-device id with the protocol’s class prefix (rhw_/rhn_/rhd_ for watch/necklace/desk). The firmware generates its own id at first boot; this mirror is used by tests and any node-driven flow.

generate_device_token

Generate a fresh, cryptographically-random per-device Bearer token (256 bits, hex-encoded). The raw token is returned to the app exactly once (in PairResponse); only its hash is persisted (see DeviceStore).

pair

Verify the pairing nonce and register the device, returning its token and the node URL the device should connect to.