[chrisuthe]

Adds --pairing-token-endpoint <address>:<port> (config key pairing-token-endpoint). With it set, the player:

• answers GET / with the pairing token as plain text (text/plain, Cache-Control: no-store) on that one address only;
• lists _ohf_local_pairing@v1 in client/hello supported_roles with "_ohf_local_pairing@v1_support": {"port": N}.

The address is required and must be a numeric IPv4 or bracketed IPv6 literal. A bare port, a hostname, 0.0.0.0, :: or ::ffff:0.0.0.0 is refused at parse time, so it can never listen on every interface. If the address cannot be bound, the player exits before it advertises anything. A request whose Host is not the endpoint's own address:port gets 421 and no token, so a page that DNS-rebinds its hostname to the address can't read it. At most four connections are served at once; a fifth is closed as soon as it is accepted. Requests are logged at debug with the peer address and status only. With the endpoint on, the startup line that otherwise prints the token points at sendspin-cli pair-token instead, because add-on logs are visible in the UI.

Docs: the wiki Configuration key, and a new Advanced Usage section, "Pairing with a server on the same host", that covers the security model.

Decisions

• Plain text on GET /, matching Pair Sendspin players on the Home Assistant host with their local token music-assistant/server#7371's fetch. An earlier revision answered GET /pairing-token with JSON carrying the client id. MA's pair_with_token already refuses a token issued for another client id, so the reply carries only the token.
• An ix::SocketServer subclass, not ix::HttpServer. In IXWebSocket v12.0.1, ix::HttpServer counts only upgraded WebSocket clients against its connection limit, and that count is final, so plain requests were never capped. The subclass counts every accepted connection, from the accept loop until its worker thread is reaped.
• cli, not the add-on wrapper. The cli already advertises the role and holds the key. Serving the token from the same process means the advertised port is bound before client/hello goes out, and the cli refuses to start if it can't bind. A wrapper serving pair-token output could advertise a port nobody is serving.
• Role name _ohf_local_pairing@v1, following the ohf_ prefix suggestion on backlog#86, instead of the brief's _ma_local_pairing@v1. Still provisional. Pair Sendspin players on the Home Assistant host with their local token music-assistant/server#7371 uses the same name.

Requires upstream

Builds on #115, which re-pins sendspin-cpp to 3a3722a8 (sendspin-cpp#218 as merged, adding SendspinClientConfig::application_roles) and moves to is_paired(). Until #115 merges, its commit shows here too; review the last three.

Compatibility

Nothing breaks for CLI users: no existing flag, config key, control-socket message, state format or exit code changes, and the option is off by default. application_roles defaults to empty, so hello is unchanged unless the new option is set.

Testing

• Unit tests: the parser accepts and rejects the right addresses and ports, and the config key works. Reply bodies: the token is only in a GET on the path. A live HTTP fetch over loopback works on 127.0.0.1 and gets no answer on 127.0.0.2. Host matching accepts the endpoint's own address and port (any case, the bare address only on port 80) and refuses a foreign name, a wrong port or none. Over a raw connection, Host: evil.example gets 421 without the token, and with four stalled connections open a fifth is closed unanswered, then requests are served again once they close.
• Manual, before the switch to plain text: with the option on, ss shows the endpoint bound only to 127.0.0.1, curl returns the token with Cache-Control: no-store, 0.0.0.0 is refused, and an address the host doesn't have exits with a bind error.
• Full suite on top of Re-pin sendspin-cpp to 3a3722a8 and read pairing from is_paired() #115 (Ubuntu 24.04, -DSENDSPIN_CLI_WERROR=ON): 566 of 569 pass, every endpoint test included; the live fetch checks the plain-text body and both headers. The three failures are the StateStore read-only-directory tests, which cannot pass as root, as on Re-pin sendspin-cpp to 3a3722a8 and read pairing from is_paired() #115. scripts/smoke_test.sh and scripts/format.sh --check pass.

Part of Sendspin/backlog#86.

[Copilot]

🟡 Changes recommended

Critical issues leave ordinary HTTP connections unbounded, enabling resource exhaustion, and allow DNS rebinding to expose the pairing token because the Host header is not validated.

2 open issues

• Connection limit excludes stalled HTTP connections · New
• Pairing token endpoint does not validate the Host header · New

What changed in this PR

Adds an opt-in HTTP pairing-token endpoint so a server on the same host can pair with the player without manually copying a token.

Changes:

• Adds CLI and config options requiring an explicit, non-wildcard IP address.
• Binds the endpoint before client startup, advertises its role and port, and suppresses startup token logging when enabled.
• Updates the library pin and adds parser, HTTP, and address-binding tests plus security documentation.

File	Description
tests/​pairing_endpoint_test.cpp	Tests responses, HTTP serving, and address isolation.
tests/​config_file_test.cpp	Tests endpoint configuration and wildcard rejection.
tests/​cli_test.cpp	Tests defaults and address/port validation.
src/​pairing_endpoint.h	Declares the endpoint interface and role constants.
src/​pairing_endpoint.cpp	Implements parsing, HTTP responses, and listener lifecycle.
src/​main.cpp	Integrates binding, advertisement, logging, and shutdown.
src/​cli.h	Adds endpoint option fields.
src/​cli.cpp	Adds flag/config parsing and help text.
README.md	Documents the new option.
docs/​wiki/​Configuration.md	Documents the configuration key.
docs/​wiki/​Advanced-Usage.md	Explains same-host pairing and its security model.
CMakeLists.txt	Updates the dependency pin and registers endpoint sources and tests.

_{Review effort: Balanced}

[chrisuthe]

Confirmed: in v12.0.1 HttpServer inherits WebSocketServer::getConnectedClientsCount(), which is final and counts only upgraded clients, so the limit never applied to plain requests. (A stalled one was still dropped after the 5 s parseRequest deadline, so threads were bounded by connection rate rather than unbounded.) Fixed in edb2a9e: the endpoint now serves from an ix::SocketServer subclass whose count is every live connection, tracked from the accept loop until the worker is reaped. ClosesAConnectionBeyondItsLimit holds four stalled connections open, checks a fifth is closed unanswered, then that requests are served again once they close.

[chrisuthe]

Fixed in edb2a9e: the token goes only to a request whose Host is the endpoint's own address:port (case-insensitive; the bare address only on port 80). Anything else gets 421 and no token. Covered by RefusesAHostThatDoesNotNameIt, MatchesHostLikeAnAddress, and RefusesARebindingHostOverHttp, which sends Host: evil.example over a raw connection.