Skip to content

Linux + iPhone Continuity / iMessage / SMS

fix(protocol): make capabilities accurate and document local additions

Nick Pisani6e3a7ee9dc7b
diff --git a/docs/PROTOCOL.md b/docs/PROTOCOL.md
index e42aa1c..4eeba1a 100644
--- a/docs/PROTOCOL.md
+++ b/docs/PROTOCOL.md
@@ -10,6 +10,21 @@ All communication happens via **newline-delimited JSON**. Every individual comma
If a payload arrives that cannot be parsed as JSON, the daemon will gracefully ignore it. After successfully processing a message, the server currently sends an ad-hoc text response `OK\n`, though standard JSON responses may replace this over time.
+### `protocol_info` (Local client -> Daemon)
+
+**Payload**: `{"command":"protocol_info"}`. The daemon answers the requesting
+Unix socket with `{"command":"protocol_info","version":1,"capabilities":[...]}`
+and sends the same event to local subscribers. Version 1 supports optional
+`operation_id` correlation on Bluetooth pairing commands and exposes the
+`apple_nearby` device hint. Capability names describe usable feature groups;
+`calls` is advertised only while calls are enabled and BlueZ is running, and
+`clipboard` only when the host compositor offers clipboard access. Other
+features have separate status and permission events, so a capability is not a
+promise that a phone is connected or has granted permissions. Older clients may
+ignore this message.
+
+---
+
### `hello` (both directions, paired only)
**Description**: Feature negotiation. A paired client sends it once connected, and the daemon answers with its own. Each side uses a feature only after the other has announced it. An older daemon answers `OK`, which means no optional features.
@@ -343,13 +358,23 @@ Reports adapter capability and the resolved delivery mode.
**Payload**: `{"command": "bt_list_devices"}`
**Response**: `{"command": "bt_devices", "devices": [...]}`, each entry carrying address,
name, `paired`, `bonded`, `connected`, `le_bearer`, and whether the device advertises
-`map`, `pbap`, and `ancs`.
+`map`, `pbap`, and `ancs`. `apple_nearby` is true when the current BlueZ
+advertisement contains Apple's Nearby payload, allowing external UIs to identify
+an unpaired iPhone candidate without guessing from its name. It is only a
+presentation hint, never proof of pairing or authorization.
#### `bt_pair` / `bt_unpair` (Client -> Daemon, broadcast)
-**Payload**: `{"command": "bt_pair", "address": "AA:BB:CC:DD:EE:FF"}`
-Runs asynchronously and reports through `bt_pair_progress` events, then one
-`bt_pair_result` (or `bt_unpair_result`). Only one pairing transaction runs at a time; a
-second returns `{"status": "busy"}`. A successful pair selects the device and starts
+**Payload**: `{"command": "bt_pair", "address": "AA:BB:CC:DD:EE:FF", "operation_id": "pair-1"}`
+`bt_unpair` accepts the same optional `operation_id`. The daemon echoes it in
+pairing progress, confirmation, and result events for client-local correlation.
+When prompted for numeric comparison, reply with
+`{"command":"bt_pair_confirm","operation_id":"pair-1","accept":true}`
+only after the user explicitly verifies the matching code. A mismatched ID
+cannot settle the active confirmation; IDs are not authorization. Legacy local
+clients may omit the ID. Pairing runs asynchronously and reports through
+`bt_pair_progress` events, then one `bt_pair_result` (or `bt_unpair_result`).
+Only one pairing transaction runs at a time; a second returns
+`{"status": "busy"}`. A successful pair selects the device and starts
supervision.
#### `bt_set_device` (Client -> Daemon)
diff --git a/src/core/src/net.cpp b/src/core/src/net.cpp
index 4647717..1b7cc97 100644
--- a/src/core/src/net.cpp
+++ b/src/core/src/net.cpp
@@ -378,22 +378,23 @@ namespace tether {
}
nlohmann::json build_protocol_info() {
- return {{"command", "protocol_info"},
- {"version", 1},
- {"capabilities",
- {"airpods",
- "bluetooth.connection",
- "bluetooth.diagnostics",
- "bluetooth.pairing",
- "calls",
- "clipboard",
- "contacts",
- "files",
- "messages",
- "notifications",
- "otp",
- "peers",
- "settings"}}};
+ nlohmann::json capabilities = {"airpods",
+ "bluetooth.connection",
+ "bluetooth.diagnostics",
+ "bluetooth.pairing",
+ "contacts",
+ "files",
+ "messages",
+ "notifications",
+ "otp",
+ "peers",
+ "settings"};
+ const auto config = bluetooth::load_config();
+ if (config.calls_enabled && bluetooth::g_bluez && bluetooth::g_bluez->running())
+ capabilities.push_back("calls");
+ if (g_wayland && g_wayland->clipboard_available())
+ capabilities.push_back("clipboard");
+ return {{"command", "protocol_info"}, {"version", 1}, {"capabilities", std::move(capabilities)}};
}
nlohmann::json build_bt_status() {
diff --git a/test/test_net.cpp b/test/test_net.cpp
index 36be78d..6030b32 100644
--- a/test/test_net.cpp
+++ b/test/test_net.cpp
@@ -1,12 +1,16 @@
#include <gtest/gtest.h>
+#include <tether/bluetooth/config.hpp>
+#include <tether/bluetooth/monitor.hpp>
#include <tether/client.hpp>
#include <tether/crypto.hpp>
#include <tether/event_loop.hpp>
#include <tether/log.hpp>
#include <tether/net.hpp>
+#include <tether/wayland.hpp>
#include <nlohmann/json.hpp>
+#include <algorithm>
#include <arpa/inet.h>
#include <cerrno>
#include <chrono>
@@ -411,20 +415,14 @@ namespace {
const auto info = tether::build_protocol_info();
EXPECT_EQ(info.value("command", ""), "protocol_info");
EXPECT_EQ(info.value("version", 0), 1);
- EXPECT_EQ(info.at("capabilities"),
- nlohmann::json({"airpods",
- "bluetooth.connection",
- "bluetooth.diagnostics",
- "bluetooth.pairing",
- "calls",
- "clipboard",
- "contacts",
- "files",
- "messages",
- "notifications",
- "otp",
- "peers",
- "settings"}));
+ const auto& capabilities = info.at("capabilities");
+ EXPECT_NE(std::find(capabilities.begin(), capabilities.end(), "files"), capabilities.end());
+ EXPECT_EQ(std::find(capabilities.begin(), capabilities.end(), "files.upload"), capabilities.end());
+ EXPECT_EQ(std::find(capabilities.begin(), capabilities.end(), "calls") != capabilities.end(),
+ tether::bluetooth::load_config().calls_enabled && tether::bluetooth::g_bluez &&
+ tether::bluetooth::g_bluez->running());
+ EXPECT_EQ(std::find(capabilities.begin(), capabilities.end(), "clipboard") != capabilities.end(),
+ tether::g_wayland && tether::g_wayland->clipboard_available());
}
TEST(ClientTest, ConnectsToAnIpv6Literal) {