Phase 7: Bluetooth offline pairing (v0.2.0)

.gitignore

@@ -3,4 +3,8 @@
 
 # venv Python cục bộ của tools/ (tạo: python3 -m venv tools/.venv && tools/.venv/bin/pip install -r tools/vectors/requirements.txt -r tools/schemas/requirements.txt)
 tools/.venv/
+# venv riêng cho từng thư mục con của tools/ (tools/setup-cpace-refs.sh, một venv cạnh mỗi requirements*.txt)
+tools/**/.venv/
+# Văn bản gốc (.txt) tải từ IETF datatracker để chép vector — không commit (tools/setup-cpace-refs.sh)
+tools/vectors/.refs/
 __pycache__/

CHANGELOG.md

@@ -6,6 +6,35 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.2.0] — 2026-10-30
+
+### Added
+
+- **Phase 7 (offline connectivity):** test vectors for the Bluetooth L2CAP link-security handshake (Noise prologue,
+  challenge, `noise1`, `noise2`, `bt-link.json`), the pre-auth/transport frame codec (channel IDs, record length bounds,
+  `bt-frame.json`), advertisement service data (rotating hint, `bt-advertisement.json`) and CPace-X25519-SHA512
+  password-authenticated key exchange (`cpace.json`, draft vectors plus HandLive-specific cases); Bluetooth pairing
+  envelopes (`bt-pairing.json`) — all consumed by `core/crypto`/`core/protocol`/`core/transport` on Android and
+  `HLCrypto`/`HLProtocol`/`HLTransport` on Apple; `tools/setup-cpace-refs.sh` fetches the CPace draft and verifies the
+  vectors in per-tool venvs. `envelope.schema.json`/`error.schema.json`: new envelope types `direct` and `bulk` (both
+  already in the Android/Apple `MessageType` enum).
+
+- UI strings for the device label "Connected via Bluetooth" (`status.connected_bluetooth(_to)`, CONN-05, shown by the
+  status indicator on Android/Mac/iOS) and the Mac Bluetooth permission prompt text (`infoplist.bluetooth_always`, wired
+  into `macOS/Info.plist`'s `NSBluetoothAlwaysUsageDescription`).
+
+### Specs
+
+- Catalog entries added for 01-setup-settings.md SET-01/SET-03 that no Android/Apple UI calls yet: the Bluetooth
+  permission-primer screen (`permission.bluetooth_title/body/body_mac`), the Mac "Bluetooth off"/"Bluetooth denied"
+  status lines and their settings button (`status.bluetooth_off`, `status.bluetooth_denied`,
+  `common.open_bluetooth_settings`), and the Settings feature-card label (`settings.bluetooth_link`).
+- `error.schema.json`'s new `DIRECT_WIFI_UNAVAILABLE` code (0.4.6): schema only, no code returns or handles it yet —
+  Wi-Fi Direct itself (SSID/passphrase format, per-connection bulk stream keys `K_bulk`) has no code or test vectors on
+  either platform.
+- `bt_seen`/`bt_lost`/`wifi_assoc` bench events (`tools/bench/reconnect_time.py`): the trigger logic is in place, but
+  only `tools/ble-spike` and `Tools/BLESpike` emit these events today — the shipped app does not yet.
+
 ## [0.1.1] — 2026-10-22
 
 ### Changed

schemas/envelope.schema.json

@@ -27,7 +27,7 @@
   },
   "$defs": {
     "type": {
-      "description": "Nhóm tin (0.7.1): tập đã chốt cộng session, camera, web.",
+      "description": "Nhóm tin (0.7.1): tập đã chốt cộng session, camera, web, direct, bulk (Phase 7, 0.4.6/0.4.7).",
       "enum": [
         "clipboard",
         "sms",
@@ -39,7 +39,9 @@
         "capability",
         "session",
         "camera",
-        "web"
+        "web",
+        "direct",
+        "bulk"
       ]
     }
   }

schemas/error.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://handlive.app/schemas/v1/error.schema.json",
   "title": "HandLive — đối tượng lỗi trong ack",
-  "description": "00-common-specs 0.5.1 (ack lỗi) và 0.8.1 (mã lỗi ứng dụng). Mã lỗi relay HTTP (0.8.2) không thuộc schema này.",
+  "description": "00-common-specs 0.5.1 (ack lỗi) và 0.8.1 (mã lỗi ứng dụng, đủ cả Phase 7 DIRECT_WIFI_UNAVAILABLE). Mã lỗi relay HTTP (0.8.2) không thuộc schema này.",
   "type": "object",
   "required": ["code", "message"],
   "additionalProperties": false,
@@ -70,7 +70,8 @@
         "USB_ADB_UNAUTHORIZED",
         "USB_ADB_UNAVAILABLE",
         "MAC_EXTENSION_NOT_ACTIVE",
-        "MAC_MIC_DRIVER_MISSING"
+        "MAC_MIC_DRIVER_MISSING",
+        "DIRECT_WIFI_UNAVAILABLE"
       ]
     }
   }

strings/ui-strings.json

@@ -940,6 +940,14 @@
       "platforms": ["android", "macos", "ios"],
       "specs": ["SET-02", "SET-01"]
     },
+    {
+      "key": "common.open_bluetooth_settings",
+      "en": "Open Bluetooth Settings",
+      "vi": "Mở cài đặt Bluetooth",
+      "comment": "Button next to the Bluetooth-off status line, opens x-apple.systempreferences:com.apple.BluetoothSettings (SET-03 field 18)",
+      "platforms": ["macos"],
+      "specs": ["SET-03"]
+    },
     {
       "key": "common.open_settings",
       "en": "Open Settings",
@@ -1360,6 +1368,15 @@
       "platforms": ["macos"],
       "specs": ["WEB-03"]
     },
+    {
+      "key": "infoplist.bluetooth_always",
+      "plist_key": "NSBluetoothAlwaysUsageDescription",
+      "en": "HandLive connects to your Android phone over Bluetooth when they aren't on the same Wi-Fi network.",
+      "vi": "HandLive kết nối với điện thoại Android qua Bluetooth khi hai máy không cùng mạng Wi-Fi.",
+      "comment": "Purpose string of the Bluetooth permission, asked during setup (SET-03 field 17); shared with AUDIO-01, whose wording must cover call audio again when Phase 4 reopens",
+      "platforms": ["macos"],
+      "specs": ["SET-03"]
+    },
     {
       "key": "infoplist.focus_status_usage",
       "plist_key": "NSFocusStatusUsageDescription",
@@ -1921,6 +1938,30 @@
       "platforms": ["android"],
       "specs": ["SET-01"]
     },
+    {
+      "key": "permission.bluetooth_body",
+      "en": "When your phone and Mac aren't on the same Wi-Fi network, HandLive connects them over Bluetooth. Android calls this permission Nearby devices. HandLive doesn't use it to find your location.",
+      "vi": "Khi điện thoại và Mac không cùng mạng Wi-Fi, HandLive nối hai máy qua Bluetooth. Android gọi quyền này là Thiết bị ở gần. HandLive không dùng nó để biết vị trí của bạn.",
+      "comment": "Body of the Android PermissionPrimer before BLUETOOTH_ADVERTISE/BLUETOOTH_CONNECT (Nearby devices); title permission.bluetooth_title (SET-01 field 12)",
+      "platforms": ["android"],
+      "specs": ["SET-01"]
+    },
+    {
+      "key": "permission.bluetooth_body_mac",
+      "en": "When your Mac and phone aren't on the same Wi-Fi network, HandLive connects them over Bluetooth. macOS asks for permission next.",
+      "vi": "Khi Mac và điện thoại không cùng mạng Wi-Fi, HandLive nối hai máy qua Bluetooth. Tiếp theo macOS sẽ hỏi quyền.",
+      "comment": "Body of the Mac primer before CBCentralManager triggers the system Bluetooth dialog; title permission.bluetooth_title (SET-03 field 17, step B1)",
+      "platforms": ["macos"],
+      "specs": ["SET-03"]
+    },
+    {
+      "key": "permission.bluetooth_title",
+      "en": "Connect Without Wi-Fi",
+      "vi": "Kết nối không cần Wi-Fi",
+      "comment": "Title of the Bluetooth permission primer, shared by the Android PermissionPrimer (body permission.bluetooth_body, SET-01 field 12) and the Mac primer before the system dialog (body permission.bluetooth_body_mac, SET-03 field 17)",
+      "platforms": ["android", "macos"],
+      "specs": ["SET-01", "SET-03"]
+    },
     {
       "key": "permission.calls_primer",
       "en": "To announce incoming calls and let you answer or decline them on your Mac, HandLive needs to read the phone state, the call log, and your contacts.",
@@ -2210,6 +2251,14 @@
       "platforms": ["android"],
       "specs": ["SET-02"]
     },
+    {
+      "key": "settings.bluetooth_link",
+      "en": "Connect Without Wi-Fi",
+      "vi": "Kết nối không cần Wi-Fi",
+      "comment": "Feature card label for link.bluetooth in the feature list (SET-01 field 10): status ready/needs_permission/permanently_denied/off",
+      "platforms": ["android"],
+      "specs": ["SET-01"]
+    },
     {
       "key": "settings.call_app_calls",
       "en": "Calls from Other Apps",
@@ -3252,6 +3301,22 @@
       "platforms": ["macos", "ios"],
       "specs": ["SMS-05"]
     },
+    {
+      "key": "status.bluetooth_denied",
+      "en": "HandLive can't use Bluetooth, so it can't connect to the phone without Wi-Fi. Turn on HandLive in System Settings › Privacy & Security › Bluetooth.",
+      "vi": "HandLive không dùng được Bluetooth nên không kết nối được với điện thoại khi không có Wi-Fi. Bật HandLive trong Cài đặt hệ thống › Quyền riêng tư & Bảo mật › Bluetooth.",
+      "comment": "Mac Bluetooth-unavailable status line when access is denied or restricted (SET-03 E8); shown with common.open_system_settings",
+      "platforms": ["macos"],
+      "specs": ["SET-03", "CONN-05"]
+    },
+    {
+      "key": "status.bluetooth_off",
+      "en": "Bluetooth is off. Turn it on to connect without Wi-Fi.",
+      "vi": "Bluetooth đang tắt. Bật Bluetooth để kết nối khi không có Wi-Fi.",
+      "comment": "Mac Bluetooth-unavailable status line, shown under the status line while there is no LAN session (SET-03 field 18); shown with common.open_bluetooth_settings",
+      "platforms": ["macos"],
+      "specs": ["SET-03", "CONN-05"]
+    },
     {
       "key": "status.channel_internet",
       "en": "Internet",
@@ -3276,6 +3341,23 @@
       "platforms": ["android", "macos", "ios"],
       "specs": ["PAIR-02"]
     },
+    {
+      "key": "status.connected_bluetooth",
+      "en": "Connected via Bluetooth",
+      "vi": "Đã kết nối qua Bluetooth",
+      "comment": "State Connected while the session goes over Bluetooth; new catalog key (S7.1)",
+      "platforms": ["android", "macos", "ios"],
+      "specs": ["0.11"]
+    },
+    {
+      "key": "status.connected_bluetooth_to",
+      "en": "Connected via Bluetooth to {device_name}",
+      "vi": "Đã kết nối qua Bluetooth với {device_name}",
+      "comment": "Status line with the device's name (Mac menu bar menu); also the VoiceOver/TalkBack text of the indicator; new catalog key (S7.1)",
+      "platforms": ["android", "macos", "ios"],
+      "args": [{"name": "device_name", "type": "string"}],
+      "specs": ["0.11"]
+    },
     {
       "key": "status.connected_internet",
       "en": "Connected over the internet",