btkey-sync 0.2.0__tar.gz

btkey_sync-0.2.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: btkey-sync
+Version: 0.2.0
+Summary: Synchronize Bluetooth LE and Classic bond keys between Windows and Linux in dual-boot setups
+License: MIT
+Project-URL: Homepage, https://github.com/netssv/btkey_sync
+Project-URL: Repository, https://github.com/netssv/btkey_sync
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# btkey-sync
+
+[![PyPI version](https://img.shields.io/pypi/v/btkey-sync.svg)](https://pypi.org/project/btkey-sync/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Synchronize Bluetooth pairing and cryptographic bonding keys (**BLE** and **Classic BR/EDR**) between operating systems in dual-boot setups (Windows & Linux) or across partitions and physical machines — **without having to re-pair devices on every reboot**.
+
+---
+
+## Why This Exists
+
+Bluetooth peripherals (keyboards, mice, headsets) generate cryptographic keys during pairing. Dual-booting causes devices to fail on OS switches because each OS stores independent keys:
+
+| Feature | Windows | Linux (BlueZ) |
+|---|---|---|
+| **Storage Location** | `HKLM\SYSTEM\...\BTHPORT\Parameters\Keys` | `/var/lib/bluetooth/<adapter>/<device>/info` |
+| **Required Privileges** | SYSTEM account (automated via scheduled task) | `root` (`sudo`) |
+| **Numeric Formats** | Hexadecimal (`dword`, `qword`, `hex`) | Decimal (`EDiv`, `Rand`) |
+| **Daemon Reload** | Immediate | Requires `systemctl restart bluetooth` |
+
+`btkey-sync` automates extracting, converting, importing, and validating keys across systems.
+
+---
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install btkey-sync
+```
+
+*(Or via `pipx install btkey-sync` for isolated CLI environments)*
+
+### From Source
+
+```bash
+git clone https://github.com/netssv/btkey_sync.git
+cd btkey_sync
+pip install .
+```
+
+### Optional Dependencies (Linux Offline Windows Reading)
+To clone directly from a mounted Windows partition on Linux without booting Windows:
+```bash
+sudo apt install chntpw bluetooth   # Debian/Ubuntu/Mint
+sudo dnf install chntpw bluez       # Fedora/RHEL
+sudo pacman -S chntpw bluez-utils   # Arch Linux
+```
+
+---
+
+## Usage
+
+### 1. Interactive TUI Menu (Recommended)
+
+Run the command with elevated privileges:
+
+**Linux:**
+```bash
+sudo btkey-sync
+```
+*(If run as normal user, `btkey-sync` will offer to re-launch with `sudo` automatically).*
+
+**Windows (PowerShell / Command Prompt as Administrator):**
+```powershell
+btkey-sync
+```
+
+The menu provides:
+- **[1] Clone Device**: Directly sync BLE, Classic, or Dual-Mode devices from a mounted Windows partition (`/mnt/windows`) or local installation.
+- **[2] Export Key to File**: Export device pairing data to `.reg` + `.json` sidecar files.
+- **[3] Import Key from File**: Load a `.reg` file and inject keys into the host Bluetooth stack.
+- **[4] Force Push Sync**: Clear daemon caches, restart BlueZ, set trust, and reconnect.
+- **[5] Remove Device**: Delete bonding for a device cleanly with automatic backup.
+- **[6] Show Keys**: Inspect all locally stored bonding keys and parameters.
+- **[7] Device Help & Advice**: Guidance on BLE vs. Classic single-slot devices.
+
+---
+
+### 2. Direct CLI Flags
+
+```bash
+# Non-interactive import of an exported .reg file
+sudo btkey-sync --import exports/aabbccddeeff__windows__20260829.reg
+
+# Force reload BlueZ stack, trust, and reconnect to a specific MAC
+sudo btkey-sync --push-sync AA:BB:CC:DD:EE:FF
+```
+
+---
+
+## Dual-Boot Migration Workflows
+
+### Method A: Offline Cloning on Linux (Fastest)
+1. Pair device in **Windows**.
+2. Boot into **Linux** and mount your Windows partition (e.g. at `/mnt/windows`).
+3. Run `sudo btkey-sync` and select **Option 1 (Clone Device)**.
+4. Select the detected Windows partition. `btkey-sync` reads the keys offline and sets up BlueZ automatically.
+
+### Method B: Export / Import via `.reg` File
+1. Pair device on **Source OS** (e.g. Windows).
+2. Run `btkey-sync` → **Option 2 (Export)** to generate a `.reg` file in `exports/`.
+3. Copy the `.reg` file to the **Destination OS** (via USB drive or shared partition).
+4. On destination, run `sudo btkey-sync` → **Option 3 (Import)**.
+
+---
+
+## Documentation Wiki
+
+Detailed guides are available in the [docs/](docs/index.md) directory:
+- [Architecture & Design](docs/architecture.md)
+- [BLE Synchronization (LTK/EDIV/ERand/IRK)](docs/ble_sync.md)
+- [Classic BR/EDR Sync (Link Keys)](docs/classic_sync.md)
+- [Dual-Boot Cloning Guide](docs/device_cloning.md)
+- [Troubleshooting & Diagnostics](docs/troubleshooting.md)
+
+---
+
+## Testing
+
+```bash
+python3 tests/test_parsing.py
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

btkey_sync-0.2.0/README.md

@@ -0,0 +1,129 @@
+# btkey-sync
+
+[![PyPI version](https://img.shields.io/pypi/v/btkey-sync.svg)](https://pypi.org/project/btkey-sync/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Synchronize Bluetooth pairing and cryptographic bonding keys (**BLE** and **Classic BR/EDR**) between operating systems in dual-boot setups (Windows & Linux) or across partitions and physical machines — **without having to re-pair devices on every reboot**.
+
+---
+
+## Why This Exists
+
+Bluetooth peripherals (keyboards, mice, headsets) generate cryptographic keys during pairing. Dual-booting causes devices to fail on OS switches because each OS stores independent keys:
+
+| Feature | Windows | Linux (BlueZ) |
+|---|---|---|
+| **Storage Location** | `HKLM\SYSTEM\...\BTHPORT\Parameters\Keys` | `/var/lib/bluetooth/<adapter>/<device>/info` |
+| **Required Privileges** | SYSTEM account (automated via scheduled task) | `root` (`sudo`) |
+| **Numeric Formats** | Hexadecimal (`dword`, `qword`, `hex`) | Decimal (`EDiv`, `Rand`) |
+| **Daemon Reload** | Immediate | Requires `systemctl restart bluetooth` |
+
+`btkey-sync` automates extracting, converting, importing, and validating keys across systems.
+
+---
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install btkey-sync
+```
+
+*(Or via `pipx install btkey-sync` for isolated CLI environments)*
+
+### From Source
+
+```bash
+git clone https://github.com/netssv/btkey_sync.git
+cd btkey_sync
+pip install .
+```
+
+### Optional Dependencies (Linux Offline Windows Reading)
+To clone directly from a mounted Windows partition on Linux without booting Windows:
+```bash
+sudo apt install chntpw bluetooth   # Debian/Ubuntu/Mint
+sudo dnf install chntpw bluez       # Fedora/RHEL
+sudo pacman -S chntpw bluez-utils   # Arch Linux
+```
+
+---
+
+## Usage
+
+### 1. Interactive TUI Menu (Recommended)
+
+Run the command with elevated privileges:
+
+**Linux:**
+```bash
+sudo btkey-sync
+```
+*(If run as normal user, `btkey-sync` will offer to re-launch with `sudo` automatically).*
+
+**Windows (PowerShell / Command Prompt as Administrator):**
+```powershell
+btkey-sync
+```
+
+The menu provides:
+- **[1] Clone Device**: Directly sync BLE, Classic, or Dual-Mode devices from a mounted Windows partition (`/mnt/windows`) or local installation.
+- **[2] Export Key to File**: Export device pairing data to `.reg` + `.json` sidecar files.
+- **[3] Import Key from File**: Load a `.reg` file and inject keys into the host Bluetooth stack.
+- **[4] Force Push Sync**: Clear daemon caches, restart BlueZ, set trust, and reconnect.
+- **[5] Remove Device**: Delete bonding for a device cleanly with automatic backup.
+- **[6] Show Keys**: Inspect all locally stored bonding keys and parameters.
+- **[7] Device Help & Advice**: Guidance on BLE vs. Classic single-slot devices.
+
+---
+
+### 2. Direct CLI Flags
+
+```bash
+# Non-interactive import of an exported .reg file
+sudo btkey-sync --import exports/aabbccddeeff__windows__20260829.reg
+
+# Force reload BlueZ stack, trust, and reconnect to a specific MAC
+sudo btkey-sync --push-sync AA:BB:CC:DD:EE:FF
+```
+
+---
+
+## Dual-Boot Migration Workflows
+
+### Method A: Offline Cloning on Linux (Fastest)
+1. Pair device in **Windows**.
+2. Boot into **Linux** and mount your Windows partition (e.g. at `/mnt/windows`).
+3. Run `sudo btkey-sync` and select **Option 1 (Clone Device)**.
+4. Select the detected Windows partition. `btkey-sync` reads the keys offline and sets up BlueZ automatically.
+
+### Method B: Export / Import via `.reg` File
+1. Pair device on **Source OS** (e.g. Windows).
+2. Run `btkey-sync` → **Option 2 (Export)** to generate a `.reg` file in `exports/`.
+3. Copy the `.reg` file to the **Destination OS** (via USB drive or shared partition).
+4. On destination, run `sudo btkey-sync` → **Option 3 (Import)**.
+
+---
+
+## Documentation Wiki
+
+Detailed guides are available in the [docs/](docs/index.md) directory:
+- [Architecture & Design](docs/architecture.md)
+- [BLE Synchronization (LTK/EDIV/ERand/IRK)](docs/ble_sync.md)
+- [Classic BR/EDR Sync (Link Keys)](docs/classic_sync.md)
+- [Dual-Boot Cloning Guide](docs/device_cloning.md)
+- [Troubleshooting & Diagnostics](docs/troubleshooting.md)
+
+---
+
+## Testing
+
+```bash
+python3 tests/test_parsing.py
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

btkey_sync-0.2.0/actions.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+from pathlib import Path
+from exporters import export_bond_key
+from importers import load_bond_from_reg_file
+from platform_detect import OSKind
+from storage import ensure_exports_dir
+import tui_helpers as tui
+import actions_common as common
+from actions_windows import run_offline_windows_export
+from actions_verify import verify_and_connect, run_verify_flow  # noqa: F401
+from actions_remove import run_remove_flow  # noqa: F401
+
+
+def _ensure_device_name(bond) -> None:
+    """If bond has no name, prompt the user to enter one interactively."""
+    if not bond.device_name:
+        name = tui.ask("Device has no name — enter a label (Enter to skip)", default="")
+        if name.strip():
+            bond.device_name = name.strip()
+
+
+def run_export_flow() -> None:
+    tui.header("Select & Extract — Step 1: System detection")
+    env, backend = common.detect_and_validate()
+    tui.header("Select & Extract — Step 2: Choose extraction source")
+    source_os, win_mount = common.prompt_source_os(env.os_kind)
+    if source_os == OSKind.WINDOWS and env.os_kind == OSKind.LINUX:
+        run_offline_windows_export(win_mount, export_bond_key, ensure_exports_dir)
+        return
+    tui.header("Select & Extract — Step 3: Choose a device")
+    with tui.Spinner("Scanning bonded BLE devices…"):
+        devices = backend.list_devices()
+    chosen = common.prompt_select_device(devices) if devices else None
+    if not chosen:
+        tui.info("No devices or cancelled.")
+        return
+    tui.header("Select & Extract — Step 4: Extract and save")
+    with tui.Spinner(f"Extracting bonding for {chosen.device_mac}…"):
+        bond = backend.extract_bond_key(chosen)
+        bond.source_os = source_os.value
+    common.print_bond_summary(bond)
+    _ensure_device_name(bond)
+    with tui.Spinner("Writing export files…"):
+        exports_dir = ensure_exports_dir()
+        reg_path = export_bond_key(bond)
+    print()
+    tui.ok(f"Exports folder : {tui.dim(str(exports_dir))}")
+    tui.ok(f"File generated : {tui.bold(reg_path.name)}")
+    tui.ok(f"Metadata (JSON): {tui.bold(reg_path.with_suffix('.json').name)}")
+
+
+def _pick_adapter(backend, default_adapter: str | None = None) -> str | None:
+    adapters = backend._list_adapters()
+    if not adapters:
+        tui.err("No Bluetooth adapters found in /var/lib/bluetooth.")
+        return None
+    if len(adapters) == 1:
+        return adapters[0]
+    print(f"\n  {tui.bold('Multiple Bluetooth adapters found on this system:')}\n")
+    for i, a in enumerate(adapters, 1):
+        mark = tui.green(" (matches file)") if a == default_adapter else ""
+        print(f"    {tui.cyan(f'[{i}]')}  {a}{mark}")
+    print()
+    while True:
+        raw = tui.ask("Adapter index")
+        if raw.isdigit():
+            idx = int(raw)
+            if 1 <= idx <= len(adapters):
+                return adapters[idx - 1]
+        tui.warn("Invalid index, try again.")
+
+
+def run_import_flow(reg_file_arg: str | None = None) -> None:
+    tui.header("Import & Reconnect — Step 1: System detection")
+    env, backend = common.detect_and_validate()
+    if env.os_kind != OSKind.LINUX:
+        tui.err("Import is only supported when running on Linux (target system).")
+        return
+    tui.header("Import & Reconnect — Step 2: Select file")
+    reg_path = Path(reg_file_arg) if reg_file_arg else common.prompt_select_export_file()
+    if not reg_path or not reg_path.exists():
+        tui.err(f"File not found: {reg_path}")
+        return
+    tui.ok(f"File: {tui.bold(reg_path.name)}")
+    tui.header("Import & Reconnect — Step 3: Inspect key")
+    try:
+        bond = load_bond_from_reg_file(reg_path)
+    except Exception as e:
+        tui.err(f"Failed to parse {reg_path.name}: {e}")
+        return
+    common.print_bond_summary(bond)
+    tui.header("Import & Reconnect — Step 4: Map local device")
+    chosen_adapter = _pick_adapter(backend, default_adapter=bond.adapter_mac)
+    if not chosen_adapter:
+        return
+    bond.adapter_mac = chosen_adapter
+    with tui.Spinner("Scanning existing devices in BlueZ…"):
+        existing = backend.list_devices()
+    local_match = next((d for d in existing if d.device_mac.upper() == bond.device_mac.upper()), None)
+    ltk_match = None
+    if not local_match:
+        for d in existing:
+            if d.has_ltk:
+                try:
+                    local_bond = backend.extract_bond_key(d)
+                    if (local_bond.ltk_hex.upper() == bond.ltk_hex.upper() or
+                        (bond.irk_hex and local_bond.irk_hex and
+                         local_bond.irk_hex.upper() == bond.irk_hex.upper())):
+                        ltk_match = d
+                        if not bond.device_name and local_bond.device_name:
+                            bond.device_name = local_bond.device_name
+                        break
+                except Exception:
+                    pass
+    source_device_mac = None
+    if ltk_match:
+        tui.info(f"Matched physical device under a different MAC address: {ltk_match.device_mac}")
+        q = f"Migrate profile/cache from {ltk_match.device_mac} to {bond.device_mac}? [Y/n]"
+        if tui.ask(q, default="Y").upper() == "Y":
+            source_device_mac = ltk_match.device_mac
+    elif local_match:
+        tui.info("Device found locally but has no LTK.")
+    else:
+        tui.info("Device not paired locally yet.")
+
+    print()
+    target_mac = tui.ask("Destination MAC (Enter to keep original)", default=bond.device_mac)
+    target_mac = target_mac if target_mac != bond.device_mac else None
+
+    tui.header("Import — Step 5: Write and restart Bluetooth")
+    with tui.Spinner("Writing bonding to disk…"):
+        written_path = backend.import_bond_key(
+            bond, target_device_mac=target_mac, source_device_mac=source_device_mac
+        )
+    tui.ok(f"Written to: {tui.dim(str(written_path))}")
+    tui.info("Restarting Bluetooth service to apply changes. This may take a moment…")
+    with tui.Spinner("Restarting Bluetooth service…"):
+        backend.restart_bluetooth_stack()
+    tui.ok("Bluetooth service restarted.")
+    verify_and_connect(backend, target_mac or bond.device_mac)
+
+
+def run_clone_flow() -> None:
+    """Delegates to unified clone flow for BLE, Classic, and Dual-Mode."""
+    from actions_clone import run_unified_clone_flow
+    run_unified_clone_flow()

btkey_sync-0.2.0/actions_classic.py

@@ -0,0 +1,173 @@
+"""
+actions_classic.py
+
+Top-level orchestration for Classic (BR/EDR) export and import flows.
+
+Implements RC5, RC6, RC7, RC9, RC11 from CLASSIC_SUPPORT.agent.md.
+Each step of the bonding lifecycle is sequenced explicitly here — the backend
+exposes discrete methods (RC9) and this layer calls them in order.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import tui_helpers as tui
+import actions_common as common
+from exporters.classic_exporter import export_classic_bond
+from importers.classic_importer import load_classic_bond_from_reg_file
+from platform_detect import OSKind
+from actions_verify import verify_and_connect
+
+
+def _filter_classic_devices(backend, devices):
+    """Return only devices whose info file has a [LinkKey] section."""
+    import configparser
+    classic = []
+    for d in devices:
+        info_path = Path(d.raw_source_path)
+        if not info_path.exists():
+            continue
+        cfg = configparser.ConfigParser()
+        try:
+            cfg.read(info_path)
+            if "LinkKey" in cfg:
+                classic.append(d)
+        except Exception:
+            pass
+    return classic
+
+
+def run_classic_export_flow() -> None:
+    """
+    Full Classic export flow:
+    pre-flight → pick device → extract bond → write .reg + .json.
+    """
+    tui.header("Classic Export — Step 1: System detection")
+    env, backend = common.detect_and_validate()
+
+    tui.header("Classic Export — Pre-flight Check")
+    if not tui.warn_classic_preflight():
+        tui.info("Aborted — pre-flight not acknowledged.")
+        return
+
+    tui.header("Classic Export — Step 2: Choose device")
+    with tui.Spinner("Scanning bonded devices…"):
+        all_devices = backend.list_devices()
+
+    classic_devices = _filter_classic_devices(backend, all_devices)
+    if not classic_devices:
+        tui.warn("No Classic (BR/EDR) bonded devices found.")
+        tui.info("Classic devices have a [LinkKey] section in their BlueZ info file.")
+        return
+
+    chosen = common.prompt_select_device(classic_devices)
+    if not chosen:
+        tui.info("Cancelled.")
+        return
+
+    tui.header("Classic Export — Step 3: Extract and save")
+    with tui.Spinner(f"Extracting Classic bond for {chosen.device_mac}…"):
+        bond = backend.extract_classic_bond(chosen)
+
+    tui.info(bond.summary())
+
+    with tui.Spinner("Writing export files…"):
+        reg_path = export_classic_bond(bond)
+
+    tui.ok(f"Exported to: {tui.bold(reg_path.name)}")
+    tui.warn("Keep the device powered ON. Do NOT power-cycle it before importing.")
+
+
+def run_classic_import_flow(reg_file_arg: str | None = None) -> None:
+    """
+    Full Classic import flow (RC5, RC9, RC11):
+    pre-flight → load .reg → check active link → confirm remove →
+    stop BT → remove → write info → set perms → start BT → post-import warnings.
+    """
+    tui.header("Classic Import — Step 1: System detection")
+    env, backend = common.detect_and_validate()
+
+    if env.os_kind != OSKind.LINUX:
+        tui.err("Classic import (write destination) is only supported on Linux.")
+        return
+
+    tui.header("Classic Import — Pre-flight Check")
+    if not tui.warn_classic_preflight():
+        tui.info("Aborted — pre-flight not acknowledged.")
+        return
+
+    tui.header("Classic Import — Step 2: Load bond key")
+    reg_path = Path(reg_file_arg) if reg_file_arg else common.prompt_select_export_file()
+    if not reg_path:
+        tui.info("Cancelled.")
+        return
+    if not reg_path.exists():
+        tui.err(f"File not found: {reg_path}")
+        return
+
+    with tui.Spinner(f"Parsing {reg_path.name}…"):
+        bond = load_classic_bond_from_reg_file(reg_path)
+
+    tui.info(bond.summary())
+
+    if not bond.device_name:
+        name = tui.ask("Device has no name — enter a label (Enter to skip)", default="")
+        if name.strip():
+            bond.device_name = name.strip()
+
+    tui.header("Classic Import — Step 3: Pre-write checks")
+
+    # RC11: check for active connection before touching bonding state
+    with tui.Spinner(f"Checking if {bond.device_mac} is currently connected…"):
+        is_connected = backend.check_active_link(bond.device_mac)
+
+    if is_connected:
+        tui.warn(f"Device {bond.device_mac} is currently connected!")
+        tui.info("Writing bonding state over an active connection may leave BlueZ inconsistent.")
+        confirm = tui.ask("Proceed anyway? [y/N]", default="N")
+        if confirm.strip().lower() != "y":
+            tui.info("Aborted. Disconnect the device first, then re-run.")
+            return
+
+    # RC5: remove existing bonding folder with explicit user confirmation
+    target_dir = (backend.bluetooth_dir / bond.adapter_mac / bond.device_mac)
+    if target_dir.exists():
+        tui.warn(f"Existing bonding folder found: {target_dir}")
+        tui.info("It must be removed before writing the new Classic bond (RC5).")
+        tui.info("A timestamped backup will be kept automatically.")
+        confirm_rm = tui.ask("Remove existing bonding? [y/N]", default="N")
+        if confirm_rm.strip().lower() != "y":
+            tui.info("Aborted. Existing bonding preserved.")
+            return
+
+    tui.header("Classic Import — Step 4: Write bond to disk")
+
+    with tui.Spinner("Stopping Bluetooth service…"):
+        backend.stop_bluetooth()
+    tui.ok("Bluetooth service stopped.")
+
+    if target_dir.exists():
+        with tui.Spinner(f"Removing {bond.device_mac} bonding folder…"):
+            backend.remove_bond_key(bond.adapter_mac, bond.device_mac)
+        tui.ok("Old bonding removed (backup kept).")
+
+    with tui.Spinner("Disabling discovery scan if active…"):
+        disabled = backend.disable_discovery_if_active()
+    if disabled:
+        tui.info("Discovery scan disabled.")
+
+    with tui.Spinner(f"Writing Classic info for {bond.device_mac}…"):
+        write_dir = backend.bluetooth_dir / bond.adapter_mac / bond.device_mac
+        info_path = backend.write_classic_info(bond, write_dir)
+        backend.set_info_permissions(info_path)
+    tui.ok(f"Written to: {tui.dim(str(info_path))}")
+
+    with tui.Spinner("Starting Bluetooth service…"):
+        backend.start_bluetooth()
+    tui.ok("Bluetooth service started.")
+
+    # RC7: mandatory post-import instructions
+    tui.warn_classic_post_import(bond.device_mac)
+
+    verify_and_connect(backend, bond.device_mac)