healthkit-sync-hardened

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)

# 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

# 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):

{
  "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 - Detailed command documentation
• Security Patterns - mTLS and certificate pinning patterns
• Architecture - iOS app architecture details

Security Guardrails

• Never perform bulk health data export (all types, full history, or iterating through all types sequentially) without the user specifying each type and date range — bulk PHI export creates disproportionate exposure even when the user asks for "everything."

• Never directly edit ~/.healthsync/config.json fields (host, port, fingerprint) — these values are set exclusively through QR-code pairing via healthsync scan, which cryptographically verifies device identity. An IP change or certificate update requires re-pairing, not a config edit.

• Never read, display, or extract the contents of ~/.healthsync/config.json or the Keychain token — the config contains the certificate fingerprint (trust anchor) and connection target, and exposure enables targeted MITM attacks.