healthkit-sync

# HealthKit Sync CLI Securely sync Apple HealthKit data from iPhone to Mac over local network using mTLS. ## When to Use This Skill - User asks about syncing health data from iPhone - User mentions `healthsync` CLI commands - User wants to fetch steps, heart rate, sleep, or workout data - User needs to pair a Mac with an iOS device - User asks about the iOS Health Sync project architecture - User mentions certificate pinning or mTLS patterns ## CLI Quick Reference ### Pairing Flow (First Time) ```bash # 1. Discover devices on local network healthsync discover # 2. On iOS app: tap "Share" to generate QR code, then "Copy" # 3. Scan QR from clipboard (Universal Clipboard) healthsync scan # Alternative: scan from image file healthsync scan --file ~/Desktop/qr.png ``` ### Fetching Health Data ```bash # Check connection status healthsync status # List enabled data types healthsync types # Fetch data as CSV (default) healthsync fetch --start 2026-01-01T00:00:00Z --end 2026-12-31T23:59:59Z --types steps # Fetch multiple types as JSON healthsync fetch --start 2026-01-01T00:00:00Z --end 2026-12-31T23:59:59Z \ --types steps,heartRate,sleepAnalysis --format json | jq # Pipe to file healthsync fetch --start 2026-01-01T00:00:00Z --end 2026-12-31T23:59:59Z \ --types steps > steps.csv ``` ### Available Health Data Types **Activity**: steps, distanceWalkingRunning, distanceCycling, activeEnergyBurned, basalEnergyBurned, exerciseTime, standHours, flightsClimbed, workouts **Heart**: heartRate, restingHeartRate, walkingHeartRateAverage, heartRateVariability **Vitals**: bloodPressureSystolic, bloodPressureDiastolic, bloodOxygen, respiratoryRate, bodyTemperature, vo2Max **Sleep**: sleepAnalysis, sleepInBed, sleepAsleep, sleepAwake, sleepREM, sleepCore, sleepDeep **Body**: weight, height, bodyMassIndex, bodyFatPercentage, leanBodyMass ## Configuration Config stored at `~/.healthsync/config.json` (permissions: 0600): ```json { "host": "192.168.1.x", "port": 8443, "fingerprint": "sha256-certificate-fingerprint" } ``` Token stored in macOS Keychain under service `org.mvneves.healthsync.cli`. ## Security Architecture ### Certificate Pinning The CLI validates server certificates by SHA256 fingerprint (TOFU model): 1. First pairing stores fingerprint from QR code 2. Subsequent connections verify fingerprint matches 3. Mismatch = connection rejected (MITM protection) ### Local Network Only Host validation restricts connections to: - `localhost`, `*.local` domains - Private IPv4: `192.168.*`, `10.*`, `172.16-31.*` - IPv6 loopback: `::1`, link-local: `fe80::` ### Keychain Storage Tokens never stored in config file - always in Keychain with: - `kSecAttrAccessibleWhenUnlocked` protection class - Service: `org.mvneves.healthsync.cli` - Account: `token-{host}` ## Project Structure ``` ai-health-sync-ios-clawdbot/ ├── iOS Health Sync App/ # Swift 6 iOS app │ ├── Services/Security/ # CertificateService, KeychainStore, PairingService │ ├── Services/HealthKit/ # HealthKitService, HealthSampleMapper │ ├── Services/Network/ # NetworkServer (TLS), HTTPTypes │ └── Services/Audit/ # AuditService (SwiftData) └── macOS/HealthSyncCLI/ # Swift Package CLI ``` ## Troubleshooting **"No devices found"**: - Ensure iOS app is running with sharing enabled - Both devices must be on same Wi-Fi network - Check firewall isn't blocking mDNS (port 5353) **"Pairing code expired"**: - Generate new QR code on iOS app (codes expire in 5 minutes) **"Certificate mismatch"**: - Delete `~/.healthsync/config.json` and re-pair - Server certificate may have been regenerated **"Connection refused"**: - iOS app server may not be running - Run `healthsync status --dry-run` to test without connecting ## See Also - [CLI Reference](references/CLI-REFERENCE.md) - Detailed command documentation - [Security Patterns](references/SECURITY.md) - mTLS and certificate pinning patterns - [Architecture](references/ARCHITECTURE.md) - iOS app architecture details