Implement macOS Direct Protocol for KDE Connect

[gloomcheng]

Parent Epic

Part of #6 (Mobile Notification Sync via KDE Connect Protocol)

Objective

On macOS, directly implement KDE Connect Protocol v7 without relying on DBus.

Why Direct Protocol?

macOS lacks native DBus support. While dbus-daemon can be installed via Homebrew:

1. Requires additional user setup
2. Must be manually started on each boot
3. Poor integration with macOS system

Direct protocol implementation means inboxd becomes the KDE Connect "desktop client" itself, communicating directly with the Android phone.

Protocol Overview

┌─────────────────────────────────────────────────────────────────┐
│                   KDE Connect Protocol v7                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Phase 1: Discovery (UDP)                                        │
│  ┌─────────┐  broadcast identity   ┌─────────┐                  │
│  │ inboxd  │ ──────────────────►  │ Android │                  │
│  │         │ ◄──────────────────  │  Phone  │                  │
│  └─────────┘  respond identity     └─────────┘                  │
│       Ports: 1714-1764 (UDP)                                     │
│                                                                  │
│  Phase 2: Connection (TLS)                                       │
│  ┌─────────┐  TLS handshake        ┌─────────┐                  │
│  │ inboxd  │ ◄═══════════════════► │ Android │                  │
│  └─────────┘  Port: 1716 (TCP)     └─────────┘                  │
│                                                                  │
│  Phase 3: Pairing                                                │
│  ┌─────────┐  {pair: true}         ┌─────────┐                  │
│  │ inboxd  │ ──────────────────►  │ Android │                  │
│  │         │ ◄──────────────────  │  Phone  │                  │
│  └─────────┘  {pair: true}         └─────────┘                  │
│       (User confirms on both devices)                            │
│                                                                  │
│  Phase 4: Communication                                          │
│  ┌─────────┐  kdeconnect.*         ┌─────────┐                  │
│  │ inboxd  │ ◄═══════════════════► │ Android │                  │
│  └─────────┘  JSON packets         └─────────┘                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Technical Implementation

Dependencies

# Node.js built-in modules only
# - dgram (UDP)
# - tls (TLS/TCP)
# - crypto (certificate generation)

Files to Create

src/services/mobileSync/
├── protocol/
│   ├── KDEConnectProtocol.ts   # Main protocol handler
│   ├── UDPDiscovery.ts         # Device discovery
│   ├── TLSConnection.ts        # Secure channel
│   ├── PacketHandler.ts        # Packet parsing/routing
│   └── CertificateManager.ts   # TLS cert management
├── plugins/
│   ├── NotificationsPlugin.ts  # Handle notifications
│   ├── PingPlugin.ts           # Simple ping/pong
│   └── BatteryPlugin.ts        # Optional: battery status
└── MobileSyncManager.ts        # Platform router

Packet Types to Implement

Type	Direction	Purpose
kdeconnect.identity	both	Device discovery
kdeconnect.pair	both	Pairing handshake
kdeconnect.notification	receive	Incoming notifications
kdeconnect.notification.reply	send	Reply to notification
kdeconnect.notification.action	send	Trigger notification action
kdeconnect.ping	both	Connection keep-alive

Certificate Management

KDE Connect uses self-signed certificates for TLS. Requirements:

1. Generate RSA 2048 key pair
2. Create X.509 certificate
3. Store paired device certificates

// Certificate storage
~/.config/inboxd/kdeconnect/
├── privateKey.pem
├── certificate.pem
└── trusted/
    └── {deviceId}.pem

Tasks

• Create UDPDiscovery.ts - broadcast/receive identity
• Create CertificateManager.ts - generate/store certs
• Create TLSConnection.ts - secure channel
• Create PacketHandler.ts - parse/route packets
• Create KDEConnectProtocol.ts - main orchestrator
• Implement pairing flow
• Create NotificationsPlugin.ts
• Integrate with message pipeline
• Write unit tests
• Test with real Android device

Acceptance Criteria

• inboxd appears in Android KDE Connect app
• Can successfully pair devices
• Receives notifications after pairing
• Pairing persists across restarts
• Can reply to notifications

Security Considerations

• Validate incoming packet structure
• Verify device certificates after pairing
• Rate limit pairing attempts
• Secure storage for private keys

Estimated Effort

~2 weeks

References

• Protocol spec: https://valent.andyholmes.ca/documentation/protocol.html
• Valent (GTK impl): https://github.com/andyholmes/valent
• Konnect (Python): https://github.com/metallkopf/konnect